Mentions, Citations and Links

Three ways to connect what you write to the rest of your architecture:

  • @mentions name a person or a team, who are told in their inbox;
  • #citations point to a C4 element, a decision or a page, which lists everything citing it;
  • links to Archyl pages open as previews, in the app and in Slack.

Where you can use them

You can type @ and # wherever text is written in a project:

  • comments and replies, in discussions and in an element's details panel;
  • the context, decision and consequences of an architecture decision (ADR);
  • documentation pages;
  • change request descriptions, their comments and reviews.

Mentions

Type @ and start typing a name. The list shows the people who can open the project, and the teams that have at least one of them. Pick one with the arrow keys and Enter, or with the mouse.

  • The name is written into the text and shown as a highlighted chip once saved.
  • Everyone you mention is told in their inbox: "Ada mentioned you in a decision", "on change request #12", and so on. A team reaches its members who can open the project.
  • People are told once: editing the text again does not notify those already mentioned.
  • You are never notified of your own mention.

Mentions in a title are not detected; write them in the body.

Citations

Type # and start typing. The list shows what the project contains:

  • its systems, containers, components and code elements, each with its parent;
  • its decisions, listed as ADR-3 with their title;
  • its documentation pages.

The citation becomes a chip. Clicking it opens what it cites: an element opens in the diagram at its own level, already selected; a decision or a page opens on its page.

Cited in

Everything that can be cited lists where it is cited, newest first:

  • an element, in the Cited in section of its details panel;
  • a decision, at the bottom of its expanded card;
  • a page, at the bottom of the page.

Each line shows the excerpt around the citation and opens its source: the discussion of a comment, the change request of a review.

From agents (MCP)

Agents connected through the MCP server can mention and cite too. When an agent writes a comment, an ADR, a documentation page or a change request:

  • @Name mentions a person or a team, with the same rules and notifications as in the app. The agent gets the exact names from the list_mentionables tool.
  • #Label cites an element, a decision (#ADR-3) or a page, which lists the agent's text under Cited in.
  • A comment from an agent also notifies the people already in the discussion and the followers of the element.

Each write returns what was linked, so the agent can check its mentions reached the right people. The get_backlinks tool returns where an element, a decision or a page is cited, which tells an agent who discusses something before it changes it.

Links and previews

Copy a link

Use Copy link to get a link to share:

  • on an element's details panel, next to the close button: the link opens the element at its level, selected;
  • on a decision card;
  • at the top of a documentation page.

Change requests and discussions can be shared from the address bar.

Previews in Archyl

A link to an Archyl page pasted in a comment, a change request description or a review is shown as a card under the text: the title, its type and status, the project and an excerpt. Clicking the card opens the page without reloading the app. Up to three links are previewed per message.

A preview is shown only to people who can open the project the content belongs to. For everyone else the link stays a plain link.

Previews in Slack

When the Slack bot is installed, links to Archyl posted in Slack unfurl into the same preview. See Link previews in Slack for the rules and the setup.