Work in Chorus rarely stands on its own — it leans on the official docs you are following, a
repository you are modelling after, an issue thread that raised the problem, or a post that
inspired the approach. A **reference** captures that evidence as a link: a URL, a title, and
an optional note on why it matters. Chorus stores the link and your note only; it never
fetches, downloads, or snapshots the page behind the URL.

References attach to an **idea**, a **proposal**, or a **task**, so the evidence sits next to
the work it grounds. When an agent picks up a task, the references you attached travel with
it, and when an agent proposes a plan it can attach the sources it drew on for you to check.

## Add a reference

Open an idea, proposal, or task and find its **References** section — a card on the proposal
panel, a labeled section on tasks and ideas. Select **Add reference** and fill in:

- **Type** — one of four kinds, each shown with its own icon and badge:
  - **Docs** — official documentation.
  - **Repository** — a reference implementation or codebase.
  - **Issue / PR** — an issue or pull-request thread.
  - **Paper / Blog** — a paper or blog post.
- **URL** — the web link (`http://` or `https://`; local files are not accepted).
- **Title** — a short name for the reference.
- **Notes** — optional. One concise sentence on why the reference is relevant. Only the first
  two lines are shown, so keep it tight; the full text is available on hover.

The reference appears in the section immediately. Edit or delete any reference from the same
place — deleting removes the link from Chorus and cannot be undone.

## Read inline citations

A description, document, or comment can cite a reference right where it makes a claim. The
citation appears as a small bracketed number, such as **[1]**, in the text:

- **Hover or focus it** to see the reference's current title, type, URL, and notes. If the
  reference was edited since the text was written, you see the latest version.
- **Select it** to open the source in a new tab.
- A **gray** citation cannot be opened. Hover or focus it to see why: the reference no
  longer exists (**Evidence not found**), its details are still loading, or they failed to
  load (Chorus tries again the next time you hover or focus it).

A citation can point at any reference you can access, not only one attached to the item you
are reading. This is how a Research pass on an
[idea](/guides/capture-an-idea/#ask-for-research-before-development) ties each finding to
its source.

## How agents use references

Agents attach references the same way you do, which is how a proposal can arrive already
grounded in its sources. An agent with the `document:write` permission has three tools —
`chorus_add_reference`, `chorus_update_reference`, and `chorus_remove_reference` — and can
also attach references inline when it creates an idea, proposal, or set of tasks. Anyone
reading an entity sees its references inline, no special permission required.

Agents write citations as ordinary Markdown links to the reference's ID, for example
`[1](ref:<reference-uuid>)`, using the ID Chorus returns when the reference is attached or
read. An ID that matches no reference shows as **Evidence not found**, so an agent should
attach or look up the reference first and never make up an ID.

It is worth getting your agents into the habit of citing sources: a proposal that links the
exact API docs it targets is far easier to verify than one that asks you to trust it. For how the
permission that gates these tools fits the wider model, see the
[authentication reference](/reference/authentication/); for the tools themselves, see the
[MCP tools reference](/reference/mcp-tools/).