Linking to a Model Item

There are two ways to reference another item in the architecture model from within a narrative:

A Linked Item block — its own block in the narrative, with a choice of display formats (a summary, a full property list, an embedded narrative, or both together).
An inline model item link — a short Reference: Name link that sits inside a sentence, exactly like a normal hyperlink.

Both keep the narrative connected to the model itself — if a referenced item is renamed or its status changes, the reference updates automatically. Which one to use depends on how much space the reference deserves:

Use	When
Inline link	A natural, in-sentence mention — “see the Payment Gateway API for details” — that shouldn’t interrupt the flow of the paragraph.
Linked Item block	A reference that deserves its own space: a summary, the item’s full properties, its embedded narrative, or the properties and narrative together.

Linking to a Model Item Inline

In the narrative editor, select the text you want to turn into a link — a word or a short phrase, anywhere within a single paragraph (or other single block).
The formatting toolbar appears above the selection. Click the link icon (or press Cmd/Ctrl+K).
In the popup, choose Link to a model item… instead of entering a URL.

Link to a model item… is only available when your selection sits inside one block. If you’ve selected text across more than one paragraph, or across more than one table cell, only the URL link option is offered.
The Link a Model Item dialog opens. Choose the item’s Type first, then pick the specific Item from the list. For a type with many items, type in the search box at the top of the list to narrow it down (see Selecting an Item).
Click Insert Link. Your selected text is replaced with the item’s reference and name — e.g. SYS-014: Payment Gateway API — as a link to that item.

The inline link always shows in this Reference: Name form (or just the name, if the item has no reference code) — there is no display-type choice, unlike the block. It resolves live: if the item is later renamed, the label picks up the new name next time the narrative loads; if the item is deleted, the link shows “(no longer available)” instead.

While the narrative is in edit mode, a small actions button appears beside each inline model item link. Click it to open a menu with:

Action	What it does
Open in new tab	Opens the linked item’s page in a new browser tab, without leaving the narrative you’re editing.
Change linked item…	Opens the same item picker used to create a link, titled Change Link, so you can point this link at a different item. Choose a new type and item, then click Save Changes — the link updates in place, in the same spot in your text.
Remove link	Replaces the link with its current label as plain text — e.g. the link `SYS-014: Payment Gateway API` becomes the ordinary text `SYS-014: Payment Gateway API`, no longer connected to the model.

Change linked item… and Remove link are always available, even if the item behind the link couldn’t be found, is still loading, or failed to load — they’re the way to fix a broken link. Both actions can be undone (Cmd/Ctrl+Z), the same as any other edit.

Pressing Escape closes the menu, or the item picker if it’s open. If you’re viewing the narrative in fullscreen, closing either this way keeps you in fullscreen — only an Escape with nothing open takes you out of it.

You can also open the menu from the keyboard: place your cursor immediately before or after an inline model item link and press Alt+Enter. If your cursor sits between two links that touch each other, Alt+Enter opens the menu for the earlier one.

The actions button only appears while you’re editing the narrative that link belongs to. It’s not shown when viewing a narrative read-only, or on a link inside another item’s narrative that’s been embedded into the one you’re editing.

The Linked Item Block

The Linked Item block lets you reference another item in the architecture model as its own block in the narrative, with a choice of how much detail to show.

Inserting a Linked Item Block

In the narrative editor, click where you want the reference to appear.
Type / to open the slash command menu.
Type modelitem (or link, model, linked, embed) and select Linked Item from the list.
An empty Linked Item block is inserted at that position, and the Link a Model Item dialog opens at once. Closing it without choosing an item — Cancel, the close button or Escape — removes the empty block again, so no stray button is left behind.

Selecting an Item

When the narrative is in edit mode, the block opens an item picker. Choose the item’s Type first, then pick the Item of that type. The Type list shows only the types that have an item you can link, each with how many there are — for example System · 24 — so you are never offered a type with nothing in it. Choose how the link appears under Show as, then click Insert Link.

The item field works as both a list and a search:

Browse. Click the field, or press Enter, Space or the Down arrow while it is focused, to see every item of that type. The item you have already chosen is ticked. When the items fall into groups (categories, for example), each group has a heading.
Search. Once a type has more than eight items, a search box appears at the top of the list. Type part of a name or reference code and the list narrows as you type; the matching letters in each name are shown in bold, and a count such as 9 of 12 tells you how many items match. Letters need not be consecutive, so paygw finds Payment Gateway.
Start typing straight away. If the field is focused and closed, typing a letter opens the list with that letter already in the search box. (Space only opens the list; it is never the first letter of a search.)
Choose. Click an item, or move with the Up and Down arrows (Home and End jump to the ends) and press Enter. The first match is highlighted as soon as you start searching, so typing a few letters and pressing Enter picks the best match.
Leave without choosing. Press Escape to clear a search; press it again (or press it with an empty search) to close the list without changing your choice. Tab also closes the list. Closing the list never closes the dialog behind it.

If nothing matches what you typed, the list says so and offers Clear search to return to the full list. If a type has no items yet, the list says that instead. If the items cannot be loaded, the field shows an error with a Try again button.

You can link to any model item in the same project, regardless of its type — with two exceptions. The item you are editing is never offered (an item cannot usefully embed itself), and items that are no longer available, such as deleted ones, are not offered either.

Editing an existing link

Click the pencil button beside a link to open it again, titled Edit Link. The dialog opens showing the link as it is now:

The Type and Item are already filled in, and the current display is selected under Show as.
You can change only how it appears and click Save Changes; the link keeps pointing at the same item. To point it somewhere else, choose a different Type (the Item is cleared) and then a new Item.
If the item can’t be offered — it was deleted, closed, or is the item you are editing — a line at the top says what the link currently points at, for example Currently linked: SYS-014: Payment Gateway API (no longer available), and Type and Item start empty.
Cancel, Escape and the close button all discard your changes. Opening the dialog again always starts from what is saved.

Display Types

Once an item is selected, you can choose how it is displayed, from six picture cards under Show as in the dialog: two that sit in the text (In the text) and four that are blocks of their own (As a block). In edit mode, each link has a small pencil button beside it (in the header of the framed displays); click it to change the item or the display type at any time.

The four block-level displays — Summary, Properties, Narrative and Properties and narrative — share one frame. Its header shows the item’s icon, type, reference code, name (a link to the item) and status badge, so the reference and status appear once however much of the item you show. If the linked item has been deleted or rejected, its name is struck through; the status badge still shows.

Display Type	What it shows
Name	An inline hyperlink showing the item’s name. Minimal and unobtrusive.
Name and status	A one-line summary with the item’s icon, reference code, name, and current status badge.
Summary	The framed header followed by the item’s description, limited to two lines.
Properties	The framed header followed by every property that has a value, as a structured data list. Properties with no value are left out.
Narrative	The framed header followed by an embedded read-only view of the item’s own narrative.
Properties and narrative	The framed header, the item’s properties, a Narrative divider, then the item’s own narrative — the whole picture of the item in one block.

Choose the display type that best suits the context. For a passing mention, Name keeps the page clean. For a key dependency that readers need to understand in detail, Summary or Properties gives them the full picture without navigating away.

The Narrative and Properties and narrative display types embed another item’s narrative inside the current one. Use them sparingly — deeply nested narratives can be difficult to read and may impact page load time. Embedding stops two levels down, where a note says the item is nested too deeply to show and links to it, and an item that would embed itself is replaced by a note that it is already shown above, with a link to open it.

If an embedded item’s narrative cannot be loaded, the frame still shows its header (and, for Properties and narrative, its properties) with an error in place of the narrative.

Tips

For a passing, in-sentence mention, use the inline link — e.g. “the data flows through the Payment Gateway API”.
Use the block’s Summary display to call out key dependencies at the end of a narrative section.
Use the block’s Properties display when you need the reader to see the full metadata of a referenced item without navigating to it.
Use the block’s Properties and narrative display when the reader needs both the item’s metadata and its narrative in one place.
Both kinds of link are live references. If the referenced item is renamed or its status changes, the link reflects those changes automatically.