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 (Right-Click)

pip install cite2site
c2s init
echo "Alpha claim" > notes.md
c2s cite-selection --artifact notes.md --start 0 --end 11 --handle ALPHA

# Install the right-click context menu
c2s install-context-menu

Right-click any file in Explorer → Cite2Site → Look up citations here to see what citations exist at that position. Cite selection here to create a new citation.

The lookup-actions command behind the menu is the same contract editor plugins and browser extensions call. See the Integration Contract for the API, and the User Guide for everyday workflows.

To uninstall: c2s uninstall-context-menu.

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/.