References & Mentions

What a reference is

A reference is an inline @-mention that links one item to another (a task, a note, or a person) directly inside a task description, a project description, or a task comment. It renders as a compact chip showing the target's title, and clicking it jumps to that item. References keep work connected, so a task can point at the runbook note it depends on, and a description can cite a related task.

Creating a reference in the app

Type @ where you want the link. A picker opens listing the tasks and notes in the current project (and people), filtered as you type. Pick one and CompanyOS inserts a chip that is clickable right away and persists across save and reload.

1. 1
   Type @

   In a task description, project description, or comment composer, type @ followed by a few letters of the target's title.
2. 2
   Pick a target

   The picker lists matching tasks (shown with their # identifier) and notes (shown with a Note tag). Select with the mouse, or the arrow keys and Enter.
3. 3
   It becomes a chip

   CompanyOS inserts a reference chip. Click it any time to open the referenced task or note.

Kinds of reference

The wire format: how a reference is stored

Descriptions and comments are stored as Markdown. A reference is encoded as a standard Markdown link whose href is a relative sentinel path carrying the kind and the id of the target, in the form below.

[Visible label](/__mention/<kind>/<id>)

Here the kind is one of task, note, or user, the id is the target's identifier, and the visible label is the link text. For example:

[Runbook — Deploy a backend change](/__mention/note/019ed7a1-2b3c-7d4e-9f01-aabbccddeeff)

When the text is rendered, CompanyOS recognizes any link whose href begins with /__mention/ and re-hydrates it into a clickable reference chip. Ordinary Markdown links are left untouched. Because the kind and id live in the href, the reference survives the save and reload round trip. The label is display only, and the id is the source of truth.

Creating references as an AI agent (via the MCP)

Because a reference is just a Markdown link, an agent can embed one wherever a description or comment is written through the Company-Brain MCP: the description field of create_task and update_task, and the content field of create_comment. Write the link form inline and it renders as a chip for everyone who opens the item.

1. 1
   Resolve the id

   Look up the target id first. Use list_project_tasks or get_task for a task, and list_notes or get_note for a note. Take the returned id.
2. 2
   Embed the link

   Inside the Markdown, write the reference link using that id, in the form shown in the example below.
3. 3
   Write it

   Call update_task with the new description, or create_comment with the content. The reference renders as a clickable chip for everyone who opens the item.

## Plan
Mirror the steps in [Runbook — Deploy a backend change](/__mention/note/019ed7a1-2b3c-7d4e-9f01-aabbccddeeff).
This work is blocked by [#HML-42](/__mention/task/019ed802-4f5a-7b6c-8d9e-001122334455).

Where references render as chips

• Task descriptions.
• Project descriptions.
• Task comments can be composed with @, and the same link form is stored in the comment text.

Rules and behavior

• References round trip. They are saved in the Markdown and re-hydrate into chips on reload, not only during the current edit session.
• Only links whose href starts with /__mention/ become references. Normal Markdown links stay normal links.
• The label is display text and the id is authoritative. Editing the label does not change the target.
• Avoid unescaped square brackets in the label so the link form stays valid.
• The id must belong to an entity in the same organization, and the viewer must have access for the chip to open it.