Cite2Site

v1.0 — Source-clean citations that don't touch your files.

Cite2Site lets you point at evidence — in code, in a doc, on a page — without leaving a mark on it. Every citation lives in a separate, append-only ledger. Replay that history at any time and Cite2Site tells you whether the evidence still holds: still there, changed, gone, or — when it genuinely can't verify — it says so instead of guessing.

Why doesn't it touch my files?

Most citation tools want to write something into the thing you're citing — a comment, a bookmark, a hidden ID. That falls apart the moment the source isn't yours to edit: a shared PDF, someone else's code, an exported chat log, a spreadsheet with strict formatting. Cite2Site sidesteps that entirely:

select evidence -> source-clean citation -> inspectable citation projection

The current implementation uses the CLI. Integration contracts and reference examples for editor, browser, and document-tool builders are delivered; native right-click plugins are deferred.

The source file never changes. Citations live in a dedicated .c2s repository as an append-only history, and everything you see — status, exports, the published site — is generated by replaying that history against the current state of your files.

Quick Start — Human Path (Browser)

pip install cite2site
c2s init

# Load the Chrome extension:
# 1. Go to chrome://extensions, enable Developer mode
# 2. Click "Load unpacked" and select the browser-extension/ folder
# 3. Right-click any selected text on any page -> "Cite with Cite2Site"
#    Or drag a file into the extension popup, select text, and click Cite

The Chrome extension covers 90% of users — cite text from any webpage or local file without leaving the browser. For editor-specific integrations, see the Integration Contract.

Quick Start — Agent Path (CLI)

Agents and automation use the deterministic JSON CLI. Install, init, cite, query, export:

pip install cite2site
echo -e "Alpha claim\nBeta claim\n" > notes.md
c2s init
c2s cite-selection --artifact notes.md --start 0 --end 11 --handle NOTE-1
c2s citations --artifact notes.md --format json
c2s export

Every command returns JSON. Errors are structured. Citations never touch your files. See the Agent Guide for batch operations, workflow commands, and the full agent contract.

A few things worth knowing:

• Handles are aliases, not identity. Rename one anytime — the underlying citation ID never changes.
• Publication policy defaults to metadata-only. Default exports omit accepted evidence text; richer snippet and private-link modes require explicit repository authorization.
• The source artifact is never rewritten, no matter which command you run.

Where things stand

Cite2Site v1.0 is a working CLI tool for text and Markdown files. It creates source-clean citations, validates hash chains, replays citation history against current files, and exports grouped JSON and MkDocs sites — all with metadata-only privacy by default. 98 tests cover the core engine.

Beyond text and Markdown, a ConverterAdapter turns DOCX, PDF, and XLSX into canonical text by shelling out to standard converters (pandoc for DOCX, pdftotext for PDF). The architecture separates how you get text out of an artifact from how citation history, verification, and replay work — new formats extend the first part without touching the second. When a converter isn't available, Cite2Site reports the limitation honestly rather than returning a guess.

The v1 stable contract is frozen: 15 CLI commands, 7 event types, 38 stable error codes, 4 privacy modes, and 6 schema identifiers. See build-docs/internal/CURRENT_STATUS_MATRIX.md for the full capability inventory.

Guides

• User Guide — everyday commands, fixing mistakes, handles, publishing, batch citations, error codes.
• Agent Guide — deterministic JSON CLI, agent workflows, batch schema, privacy modes, integration contract.
• Integration Contract — for editor, browser, and document-tool builders.
• v1 Stable Contract — every frozen command, event field, error code, projection field, and URL shape.

Running the tests

python -m unittest discover -s tests

If you're an agent picking this up

Start with AGENTS.md. It has the reading order, the invariants that keep citations trustworthy, and the session gate protocol this project uses instead of ad-hoc review. Don't skip it — the short version is "the source file is sacred, everything else is a replay."

Digging deeper

The full build plan — requirements, workflows, whitepaper, protocol and implementation specs, current status, and ADRs — lives under build-docs/.