Description
Conversation Citations convert source markers in an assistant response into durable references that a chat renderer can present as numbered evidence. A marker can identify a Dots human ID or a validated HTTP(S) URL. Extraction replaces each valid marker with an ordinal token, deduplicates repeated references, and attaches structured citation records to the assistant message. Malformed markers stay literal rather than generating a convincing but broken source.
The parser is Markdown-aware enough to protect code. Citation-looking text inside fenced blocks, indented code, and inline code spans is preserved verbatim, allowing an agent to explain the syntax without accidentally creating a source. Prompt assembly separately teaches the model to use clickable [[HUMAN-ID]] entity mentions and end-of-statement citation markers for distinct purposes, giving users both navigation and attribution.
Selling Points
- Answers can point back to workspace rows or web pages, helping users verify important claims at the moment they read them.
- Deduplication keeps repeated evidence readable and prevents a sources list from ballooning with the same reference.
- Code-aware parsing avoids turning examples, regexes, or pasted snippets into accidental citations.
- Invalid URLs and empty markers fail visibly as text instead of becoming fake evidence.
- Structured references survive persistence, enabling transcript readers, artifact views, and later graph writers to reuse the same source identity.
User Story
An agent researches a decision using a Memory Bank row and an external specification. Its answer cites the memory several times and includes a code sample showing citation syntax. Dots assigns one ordinal to the repeated memory, another to the validated URL, and leaves the sample untouched. The user walks away with a clean answer, a concise source list, and durable links that still work when the conversation is reopened.
Extension Surface
This feature is fixed_core. packages/chat/src/dispatch/citation-extract.ts owns a closed marker grammar and parsing algorithm, and packages/chat/src/citation-url.ts owns URL normalization. Callers receive structured citations but cannot register new citation syntaxes or resolver plugins. The fixed grammar is intentional so stored transcripts mean the same thing across every provider and surface.
Capabilities & Limits
- It extracts, validates, deduplicates, and numbers human-ID and web citations.
- It preserves citation-like text inside fenced, indented, and inline code.
- It stores citations with assistant messages and exposes them in dispatch results.
- Limit: extraction proves marker shape, not the truth of the cited claim; malformed or unsupported schemes remain literal text.
Implementation Map
packages/chat/src/dispatch/citation-extract.tspackages/chat/src/dispatch/prompt-assembly.tspackages/chat/src/citation-url.tspackages/chat/src/types.tspackages/chat/src/dispatch/commit-turn.ts