Sombra
DocsStart FreeSign in
← All docs

Citations

A citation is a verifiable link between a claim in one place and its source in another. The claim might be a sentence in a collection's distilled context; the source might be a passage in a saved web page, a note, or an external URL. Sombra stores the exact text on both ends, the offsets, and the timestamps — so a reader can trace any assertion back to where it came from, and you can see when something has drifted.

Citations work two ways:

  • In the app — select text on either side and capture it, then click a suggested passage on the other side to commit. No syntax to learn.
  • Via MCP — your AI assistant can author and verify citations programmatically with the seven citation tools.

Authoring in the app

The flow has two halves and you can start from either side.

1. Capture a claim. Select text in a collection context or a note's body. A floating button appears above the selection — click Capture as claim. A persistent toast pins to the bottom of the screen showing what you captured, so you can keep working without losing your place.

2. Find the source. Navigate to whichever saved artifact backs the claim. The page enters a focused "capture mode" — existing citation chrome is dimmed and Sombra highlights candidate passages it thinks could anchor the claim. Each candidate has a small match-strength meter on hover. Click one to commit the citation. The candidate disappears, the toast clears, and the new citation paints on both ends.

If no candidate looks right, just select source text manually and click Commit citation. Either way, the server only commits citations that anchor verbatim — selections that don't match the underlying source loudly fail rather than silently land on the wrong text. The error toast explains what happened and keeps your captured claim around so you can adjust.

Drift detection

Citations don't break silently. The server resolves each citation's current location at read time and labels it:

  • Coincident — the cited text still appears exactly where it was when the citation was authored. The normal state.
  • Drifted — the text has changed but a similar passage is found nearby. The popover shows the original excerpt struck through alongside the new location, so you can see what shifted.
  • Stranded — the cited text is no longer findable. The citation surfaces in a stranded list at the bottom of the parent so you can supersede or invalidate it.

External citations to content-addressed URLs (like a GitHub blob pinned to a commit SHA) can never drift by construction, so the renderer skips the drift block for them.

Removing a citation

Hover any citation highlight — the popover footer has a small Remove button. First click arms it (becomes a destructive-styled "Confirm remove"); the second click invalidates the citation. Invalidation is reversible at the data layer — the citation stays in history with state invalidated rather than being deleted.

Removal works from either side of a citation: hover on the claim mark in a context, or on the source mark on the artifact body.

Where citations live

Citations are stored as their own entities, not embedded in markdown. That means your distilled context document stays clean and portable — you can copy the markdown out, export it, render it anywhere, and the citation chrome is added by the renderer rather than baked into the text. Sombra splices <cite> tags into the rendered markdown right before display.

The source can be:

  • Another Sombra artifact — a saved web page, a note. Common case.
  • An external content-addressed URL — currently GitHub blob URLs with a commit SHA. These can't drift; the source-of-truth lives outside Sombra.

Citations via MCP

If you're working with an AI assistant connected to Sombra, it has the same authoring surface plus a few power-tools:

  • cite_text — propose a batch of citations against a collection or artifact, returning ranges and confidence scores you can inspect before committing.
  • commit_citations — persist a validated batch in one transaction.
  • check_citations — get a drift report for every active citation on a parent.
  • find_citations — reverse lookup: what cites this source?
  • supersede_citation — replace a citation with a new range, keeping the old one in history.
  • set_citation_state — flip a citation between active, invalidated, and deferred.
  • repair_citations — re-anchor drifted citations to their current location.

Full tool descriptions are at sombra.so/mcp. Citations from MCP and the in-app authoring flow share the same data substrate — they show up identically on the page, with the same hover-card chrome and drift detection.