version: "1.0.0" name: citations description: How to mint a citation. Every fact FKs to a citations row; citations verify against documents.content (never disk) at insert time and are immutable after.

Citations

bun $ANT_CONTRACTS_CLI cite <doc_id> <brief_id> <by> - [start end] [--near <off>] <<'Q'
<quote>
Q

Quote goes on stdin (the - arg) via a quoted heredoc — the 'Q' quotes disable all shell expansion, so $500,000, $(…), backticks, "Term", it's survive unchanged. --near <offset> picks the occurrence closest to where you were reading — pass it whenever the quote is short or boilerplate. created_by is your worker label. The trigger re-verifies on insert; a bad cite ABORTs.

Sweep workers: prefer bun $ANT_CONTRACTS_CLI find (see the sweep skill) — it does cite + finding + link in one transaction.

Two paths

• Exact — the quote is a contiguous substring of documents.content.

Don't supply offsets; cite locates it. Aim for this — quote what's literally there, including the document's whitespace and quote marks.

• Judged — tables, two-column definition schedules, anything where

the contiguous string genuinely doesn't exist. You verify, then cite: spawn an Agent with model: "haiku", pass the span and the quote, prompt "Is every value/label/term in QUOTE faithfully present in PASSAGE with the same meaning? Paraphrases are NOT present. Reply {present, reason}." If present, write the verdict: `` bun $ANT_CONTRACTS_CLI write audits '{"run_id":"'$ANT_CONTRACTS_RUN_ID'","kind":"citation_judge","result":"<reason, one line>"}' ` then re-cite with the span and --audit <id>. The trigger requires that audit FK for kind='judged'`.

What makes a good quote

• Verbatim from the document. Not your summary of it.
• Complete. A definition or enumeration ending in a colon followed by

(a)/(b)/(i) sub-items — quote through the sub-items. Stopping at the colon omits the operative content and is useless evidence.

• Self-locating. Include enough surrounding words that the quote is

unambiguous in the document (a bare "5.5%" appears in fifty places).

• The right family. A clause from another deal's copy of shared

template terms is the wrong source for deal-specific figures, even if the wording matches. Cite from the target family's own documents.

After minting

cite returns {id, kind, start_off, end_off}. Link it:

bun $ANT_CONTRACTS_CLI write finding_citations '{"finding_id":<f>,"citation_id":<c>}'

(or queue_citations / claim_citations / knowledge_citations as fits.)