References & mentions

What references are

A reference is a single, unified way to point at something from inside a body of text. You @-mention a person, or you reference a task or a note, and Elliptic turns it into a compact chip right where you typed it. The same mechanism works across rich-text surfaces: a note page, a project description, a task description, and a comment on a task, meeting, or note. One reference can pull the runbook note a task depends on into its description, name a teammate in a comment, or cite a related task from a page. Work stays connected instead of scattered.

There are three kinds of reference. A user reference is a mention of a person. A task reference points at a work item. A note reference points at a page. People are mentioned so they can be notified, tasks and notes are referenced so the chip becomes a link you can follow.

Mentioning in the app

Type @ where you want the reference. A picker opens and filters as you type. Pick one with the mouse, or move with the arrow keys and press Enter. Elliptic inserts the chip and drops a trailing space so you can keep typing.

What the picker offers depends on the surface. On a note page and in a project description it lists people, tasks (each shown with its # identifier), and notes (each shown with a Note tag and a page icon). In a task description and a task comment the picker offers tasks and notes, so you reference work items and pages there rather than people. The placeholder text tells you which: a task comment composer reads @ to mention a task or note.

1. 1
   Type @

   In a note, a project description, a task description, or a comment composer, type @ followed by a few letters of a name, a task title or identifier, or a page title.
2. 2
   Pick from the picker

   The list shows the targets available on that surface. Filter by typing, then select with the mouse or with the arrow keys and Enter.
3. 3
   It becomes a chip

   Elliptic inserts the chip. A task or note chip is clickable right away and opens the referenced item. A person chip names them.

On a note page the editor placeholder says it all: type @ to mention, type / for a block menu, and Markdown shortcuts like ## for a heading, - for a list, and > for a quote all work. Mentioning is just one of the editor's inline behaviors.

How a chip behaves

• Task and note chips are interactive. Clicking a chip (or focusing it and pressing Enter or Space) opens the referenced item. A note chip routes to the page, a task chip resolves to the task in the browse view.
• Person chips are labels, not links. An @ person chip shows who is mentioned. It does not navigate anywhere, its job is to identify the person.
• Chips are atomic. A chip is a single unit in the editor, not editable character by character. The label is what you see, the kind and id underneath are what make it resolve.

The /__mention/ link format

Notes, descriptions, and comments are all stored as Markdown. A reference is encoded as an ordinary Markdown link whose href is a relative sentinel path carrying the kind and the id of the target:

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

The <kind> is one of user, task, or note. The <id> is the target's identifier, URL-encoded. The visible label is the link text. For example, a note reference, a task reference, and a person reference look like this:

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).
Handing this to [Ada](/__mention/user/019ed9c3-7a1b-4c2d-8e3f-556677889900).

The editor's Mention extension writes this href when you pick from the @ picker, and serializes the chip back to the same link when the content is saved as Markdown. The Markdown renderer does the reverse: it recognizes any link whose href begins with /__mention/, parses out the kind and id, and re-hydrates it into a chip. A note resolves to its notes route, a task resolves to the browse route built from its identifier, and a person renders as a styled, non-navigating glyph chip. Ordinary Markdown links are left untouched and render as normal links.

Each kind has a glyph the renderer prepends so the chip reads naturally even as plain text: # for a task, @ for a person, and ※ for a note. When the same Markdown is flattened to plain text (for a search index or a snippet), the link collapses to that glyph plus the label, so [Ada](/__mention/user/...) becomes simply @Ada.

Drag to cite

When you are editing a note page, you can drag an entity from elsewhere in the app and drop it into the page to drop a citation link. The editor accepts the drag payload, works out where you dropped it, and inserts a link to that entity at that exact spot followed by a non-breaking space. Drag to cite is wired in the full note editor, the same surface that supports the @ picker, slash menu, and AI tools.

The drag carries a small structured payload over a Elliptic-specific clipboard type, with a kind, an id, a title, and an href. On drop, the editor builds an anchor from it: the link text is the entity's title, the href is the entity's own route, and the anchor also carries data-entity-kind and data-entity-id attributes so the citation stays identifiable. If the dragged entity has no route, the citation is inserted as the plain title instead of a link.

Notifications from mentions

Mentioning a person is how you get their attention. The notification path is driven by an explicit mention_user_ids field on the create and update payload, not by scanning the body for /__mention/user/ links. When that field carries member ids, Elliptic emits a MENTIONED notification to each of them. It only notifies ids that are genuine members of the same organization, and it never notifies you about your own mention.

• On a note, creating or updating the page with mention_user_ids notifies each named member with a MENTIONED notification titled "You were mentioned in <note title>", pointing at the note.
• On a comment, each named member gets a MENTIONED notification pointing at the entity the comment is on (the task, meeting, or note), with a snippet of the comment text.
• On a task, each named member gets a MENTIONED notification pointing at the task and titled with the task's identifier, and is auto-subscribed to that task.
• In a task comment specifically, each named member is likewise auto-subscribed to the task, idempotently, so they keep getting that task's updates. Auto-subscribe on mention happens for task targets, not for note or meeting targets.

Writing references as an agent (via the MCP)

Because a reference is just a Markdown link, an agent on the Company-Brain MCP can embed one anywhere a body of text is written. Resolve the target's id first, then write the /__mention/<kind>/<id> link inline and it renders as a chip for everyone who opens the item.

1. 1
   Resolve the id

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

   Write the reference link with that id in the Markdown body, in the [label](/__mention/<kind>/<id>) form.
3. 3
   Write the body

   Pass the Markdown as description on create_task or update_task, as content on create_note or update_note, or as body on create_comment. The link renders as a chip when anyone 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 show up

References are not their own surface, they live inside the surfaces you already use:

• Notes. Pages are the richest place for references and the only surface that supports drag to cite. See Notes, Activity & Calendar.
• Comments. Task, meeting, and note comments are composed with @ and store the same link form in the comment text. A task comment's @ picker offers tasks and notes.
• Task descriptions. A description can reference related tasks and notes with @, and the same Markdown link form is stored. See Projects & Tasks.
• Project descriptions. A project brief is a rich-text body where you can @ people, tasks, and notes.
• Activity. Creating or editing a note, or commenting, records an entry in the activity feed, so a referenced item's history shows when it was touched. See Notes, Activity & Calendar.
• The assistant. The org assistant has its own @ context picker for attaching a project or a work item to a message, so you can ground an answer in a specific task or project.

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 reference chips. Normal Markdown links stay normal links.
• The kind is one of user, task, or note. An unrecognized kind falls back to user.
• The label is display text and the id is authoritative. Editing the label does not change the target.
• Task and note chips are clickable and navigate, person chips are labels.
• Notifying a mentioned person uses the explicit mention_user_ids field, only members of the same org are notified, and you are never notified about your own mention.
• Mentioning a member on a task or in a task comment auto-subscribes them to that task, idempotently.