Metadata-Version: 2.4
Name: cite2site
Version: 1.0.6
Summary: Source-clean citations that don't touch your files. Record evidence outside the file, replay it to check if it still holds.
Author: Cite2Site contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/paragon-ux/Cite2Site
Project-URL: Documentation, https://paragon-ux.github.io/Cite2Site/
Project-URL: Repository, https://github.com/paragon-ux/Cite2Site
Keywords: citations,evidence,verification,source-clean,append-only,cli
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Text Processing
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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:

```text
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)

```bash
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](build-docs/architecture/INTEGRATION_CONTRACT.md).

## Quick Start — Agent Path (CLI)

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

```bash
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](build-docs/guides/AGENT_GUIDE.md)** 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`](build-docs/internal/CURRENT_STATUS_MATRIX.md)
for the full capability inventory.

## Guides

- **[User Guide](build-docs/guides/USER_GUIDE.md)** — everyday commands,
  fixing mistakes, handles, publishing, batch citations, error codes.
- **[Agent Guide](build-docs/guides/AGENT_GUIDE.md)** — deterministic JSON CLI,
  agent workflows, batch schema, privacy modes, integration contract.
- **[Integration Contract](build-docs/architecture/INTEGRATION_CONTRACT.md)** —
  for editor, browser, and document-tool builders.
- **[v1 Stable Contract](build-docs/architecture/V1_STABLE_CONTRACT.md)** —
  every frozen command, event field, error code, projection field, and URL shape.

## Running the tests

```bash
python -m unittest discover -s tests
```

## If you're an agent picking this up

Start with [`AGENTS.md`](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/`](build-docs/README.md).
