npm CLI

The citation-cli npm package tracks cited code in package.json under the "citation" key.

Install

npm install -g citation-cli

Or as a dev dependency:

npm install --save-dev citation-cli

Or run without installing:

npx citation-cli --help

Commands

`cite add`

Record a citation. Scans files in the target directory and records each as a quote with its sha256 hash.

cite add <name> \
  --source <path-or-url> \
  --version <semver> \
  --target <local-dir>

Flag	Required	Description
`<name>`	yes	Entry name (e.g. `agent-harness`)
`--source`	yes	Path or URL to the reference package
`--version`	yes	Semver of the reference at citation time
`--target`	yes	Local directory where files were placed
`--package-json`	no	Path to package.json (default: `package.json`)

What it does:

Reads the existing package.json.
Scans all files in --target (skipping hidden directories).
Computes sha256 for each file.
Records everything as "status": "quote" under "citation.packages.<name>".
Sets "cited" to today’s date.
Writes "schema": 2 on the package entry.

`cite check`

Verify integrity of cited files.

cite check [name]

Flag	Required	Description
`[name]`	no	Check a specific package (omit to check all)
`--package-json`	no	Path to package.json (default: `package.json`)

What it reports:

OK — file hash matches the recorded sha256.
DRIFT — file was modified (hash mismatch).
MISSING — file was deleted.
SKIP — file is a paraphrase or synthesize (expected to differ).

`cite migrate`

Migrate a legacy "assimilai" key in package.json to the v2 "citation" schema.

cite migrate [--dry-run]

Refuses to run if "citation" already exists and errors on any unknown file status.

`cite sync`

Reserved for 0.2.0 — will update quoted files from the source, following the propagation rules in the Specification.

package.json schema

{
  "citation": {
    "packages": {
      "harness-claude": {
        "schema": 2,
        "source": "../packages/agent-harness",
        "version": "0.6.0",
        "target": "src/clients/claude",
        "cited": "2026-04-13",
        "files": {
          "daemon.js": { "status": "paraphrase" },
          "transport.js": {
            "status": "quote",
            "sha256": "e3b0c44..."
          },
          "config.js": {
            "status": "synthesize",
            "into": "src/clients/claude/settings.js"
          }
        }
      }
    }
  }
}

File status

After cite add, all files start as quote. To reclassify a file as a paraphrase or synthesis, edit package.json directly:

{
  "daemon.js": { "status": "paraphrase" },
  "config.js": {
    "status": "synthesize",
    "into": "src/settings.js"
  }
}

cite check will then skip these files.

Walkthrough

# 1. Copy reference files into your project
cp -r ../packages/agent-harness/ ./src/clients/claude/

# 2. Record the citation
cite add harness-claude \
  --source ../packages/agent-harness \
  --version 0.6.0 \
  --target ./src/clients/claude

# 3. Engage with the files
# Rewrite daemon.js → mark it "status": "paraphrase"
# Absorb config.js into settings.js → mark it "status": "synthesize"

# 4. Update package.json to reflect those decisions

# 5. Check integrity of the remaining quotes
cite check harness-claude