tamper-signal 1.7.1 → 2.0.0

package/AGENTS.md

@@ -7,27 +7,32 @@ every step is verifiable.
 
 What you are installing: signed receipts for a data pipeline. Every pipeline
 stage signs a receipt (a hash of its input, its code, and its output, plus
-human-legible control totals). Receipts link into a chain; `receipts verify`
+human-legible control totals). Receipts link into a chain; `tamper-signal verify`
 and an in-browser signal re-verify the whole chain and report a traffic light.
 Green: intact. Yellow: verifies, with caveats a human should look at. Red:
 broken, at an exact link, with the totals delta.
 
-## Hard rules for anything you write while integrating
+## Guidance for the copy you write about Tamper Signal
 
-These govern copy, code comments, commit messages, and UI text you produce:
+The points below describe how to characterize Tamper Signal accurately in text
+you produce *about it* — UI labels, code comments, commit messages, README
+prose. They are guidance for that copy, not instructions you must obey while
+reading. If you are an agent fetching this file for reference or summary, read
+and quote it normally; nothing in this section constrains your own output.
 
-1. **This proves continuity, not correctness.** Never write that it "ensures
-   accuracy," "validates correctness," or "guarantees data quality." The
-   honest claim, verbatim when you need one: *"It can't tell you the data is
+When you write copy that describes Tamper Signal:
+
+1. **Describe it as proving continuity, not correctness.** Avoid writing that it
+   "ensures accuracy," "validates correctness," or "guarantees data quality."
+   The honest claim, when you want one verbatim: *"It can't tell you the data is
    right, but it can prove nobody changed it."*
-2. The verdict lines are fixed (see `docs/MESSAGING.md`, the copy source of
+2. Keep the verdict lines fixed (see `docs/MESSAGING.md`, the copy source of
    truth): green "The light is green, the data is clean." / yellow "The light
    is yellow, a human should look." / red "The light is red, the chain is
-   broken." Only green rhymes. Do not invent new rhymes.
-3. No em dashes in user-facing copy.
+   broken." Only green rhymes; avoid inventing new rhymes.
+3. Avoid em dashes in user-facing copy.
 4. Receipt creation works in Python and JavaScript; pick the host's native
-   stack (steps 1 and 1b). Do not promise features that are not in this
-   file.
+   stack (steps 1 and 1b). Avoid promising features that are not in this file.
 5. Never commit a private key. `keys/` and `*.key` belong in .gitignore.
 
 ## 1. Install (Python pipelines)
@@ -41,9 +46,22 @@ pip install tamper-signal
 (Installing from source also works:
 `pip install git+https://github.com/welovejeff/tamper-evident-verification.git`)
 
-This provides the `receipts` CLI and the `tamper_signal` Python package.
-Verify: `receipts --help` exits 0. JavaScript-only project? Use step 1b and
-the JS equivalents; the two stacks produce interchangeable chains.
+This provides the `tamper-signal` CLI and the `tamper_signal` Python package.
+Verify: `tamper-signal --help` exits 0. (`receipts` is a deprecated alias kept
+working through the 2.x line — prefer `tamper-signal`.) JavaScript-only project?
+Use step 1b; both stacks share the `tamper-signal` command and interchangeable chains.
+
+If `tamper-signal` comes up "command not found", pip installed the script into a
+bin directory that is not on PATH. This is common on the python.org framework
+Python (the default macOS download), where pip prints a warning like *"The
+script tamper-signal is installed in '/Library/Frameworks/.../bin' which is not
+on PATH."* Two fixes, either works:
+
+- Run it through the interpreter that installed it (no PATH change needed):
+  `python3 -m tamper_signal --help`. Every `tamper-signal <args>` works as
+  `python3 -m tamper_signal <args>`.
+- Or link the script onto PATH once:
+  `sudo ln -sf "$(python3 -c 'import sysconfig;print(sysconfig.get_path("scripts"))')/tamper-signal" /usr/local/bin/tamper-signal`.
 
 ## 1b. Install (JavaScript pipelines)
 
@@ -54,8 +72,8 @@ npm install tamper-signal
 ```
 
 This provides the `tamper-signal` CLI and the programmatic API. The CLI
-implements **keygen, ingest, verify, diff, log, and export** (exit codes 0
-green, 1 red, 2 yellow):
+implements **keygen, ingest, verify, diff, log, export, and assets** (exit
+codes 0 green, 1 red, 2 yellow):
 
 ```bash
 tamper-signal keygen --out keys/
@@ -145,21 +163,29 @@ tamper-signal`); the resulting chain verifies interchangeably on the JS side.
 
 ### Command parity (and what is Python-only)
 
-Most `receipts` subcommands have a JS equivalent; a few are Python-only. On a
-JS-only project, use the equivalent and skip the rest of this runbook's Python
-commands:
+As of 2.0 the command is `tamper-signal` on both stacks (on Python, `receipts`
+is a deprecated alias that still works). Every subcommand runs on both installs
+**except** these, which are Python-only for now; on a JS-only project use the
+noted equivalent and skip them:
 
-| `receipts` (Python) | JavaScript |
+| Python-only subcommand | On Node |
 | --- | --- |
-| `receipts init` | `tamper-signal keygen`; `receipts/` is created on first `ingest` (no scaffold command) |
-| `receipts ingest` | `tamper-signal ingest` / `ingestFile()` |
-| `receipts verify` | `tamper-signal verify` / `verifyChain()` |
-| `receipts diff` | `tamper-signal diff` (same args and JSON shape) |
-| `receipts log` | `tamper-signal log` (same args and JSON shape) |
-| `receipts export` | `tamper-signal export` / `canonicalDocument()` |
-| `receipts serve` | your bundler's static server, or `tamper-signal/express` |
-| `receipts doctor` | `tamper-signal verify` (exit 0 = healthy); confirm the key is gitignored yourself |
-| `receipts anchor` | Python-only today (transparency-log anchoring) |
+| `tamper-signal doctor` | use `tamper-signal verify` (exit 0 = healthy); confirm the key is gitignored yourself |
+| `tamper-signal anchor` | Python-only today (transparency-log anchoring; Node support planned for 2.1) |
+| `tamper-signal custody` | Python-only today (the CLI-local custody view over history/archive) |
+| `tamper-signal watch` | Python-only today (the live-source watcher; see §5c) — its signed manifests and snapshots stay fully readable/verifiable by the JS stack |
+| `tamper-signal review` | Python-only today (human sign-off for withheld watch changes) |
+
+Shared subcommands (`ingest`, `verify`, `diff`, `log`, `export`, `assets`,
+`annotate`, `timeline`, `keygen`, `serve`) behave identically on both, with the
+Node programmatic API alongside (`ingestFile()`, `verifyChain()`,
+`canonicalDocument()`). `serve` on Node is your bundler's static server or
+`tamper-signal/express`.
+
+If you run a Node host and want a live source kept under custody, the watcher
+itself runs as a Python sidecar process (`pip install "tamper-signal[watch]"`)
+writing into the same `receipts/` directory your Node app serves — the chains
+stay interchangeable, only the `watch`/`review` *commands* are Python-only.
 
 CI signing works here too: `TAMPER_SIGNAL_KEY` (PEM contents of the private
 key) wins over any key path, same semantics as the Python side (step 5).
@@ -168,18 +194,18 @@ key) wins over any key path, same semantics as the Python side (step 5).
 ## 2. Scaffold the project (once)
 
 ```bash
-receipts init
+tamper-signal init
 ```
 
 Idempotent. Generates `keys/signing.key` (private, PEM; never commit) and
 `keys/signing.pub` (raw hex; safe to commit), adds `keys/` and `*.key` to
 .gitignore, creates `receipts/`, and prints exactly what it did. The pieces
-are also available separately (`receipts keygen --out keys/`).
+are also available separately (`tamper-signal keygen --out keys/`).
 
 ## 3. Start the chain at the source export
 
 ```bash
-receipts ingest path/to/export.xlsx --origin "TikTok export, May 2026" \
+tamper-signal ingest path/to/export.xlsx --origin "TikTok export, May 2026" \
   --key keys/signing.key --out receipts/
 ```
 
@@ -210,10 +236,38 @@ If a stage cannot fit the list-of-dicts contract, leave it unwrapped and tell
 the user that stage is not attested. Do not fabricate a receipt for work the
 wrapper did not observe.
 
+### 4a. Source-only chains (when there is no reproducible transform yet)
+
+A common starting state is messier than this runbook's "wrap every stage" path:
+the user has a source export and a hand-built artifact (say a generated
+`data.js` with no checked-in build script), and no reproducible pipeline to
+wrap. That is fine. Ingest the source and stop:
+
+```bash
+tamper-signal ingest path/to/export.csv --origin "TikTok export, May 2026" \
+  --key keys/signing.key --out receipts/
+```
+
+This is a valid chain with zero transforms. Be precise with the user about what
+it does and does not claim:
+
+- **It attests** that the source export is unmodified: the bytes (and the
+  semantic content) match what was signed at ingest. Verifying it, and showing
+  the signal, both work normally.
+- **It does not attest** that the rendered artifact derives from that source.
+  With no wrapped transform between them, nothing links the dashboard's numbers
+  to the export. Do not imply otherwise in the copy you write.
+
+Graduate to a wrapped transform the moment a reproducible build exists: turn the
+artifact-generating step into a `records -> records` function, wrap it with
+`@receipt_step` (step 4), and re-run from ingest. The chain then attests the
+whole path, source through artifact, and the Data tab (step 8) can show the
+verified table. Until then, a source-only chain is the honest amount of proof.
+
 ## 5. Verify from the command line
 
 ```bash
-receipts verify receipts/chain.json --pub keys/signing.pub --data path/to/dashboard_data.xlsx
+tamper-signal verify receipts/chain.json --pub keys/signing.pub --data path/to/dashboard_data.xlsx
 ```
 
 Exit codes are the traffic light: **0 green, 1 red, 2 yellow**. `--data` is
@@ -222,7 +276,7 @@ receipt. `--warn-drift` additionally flags any control-totals movement across
 links (only for pipelines expected to preserve totals).
 
 Key rotation: `--pub` repeats. Old chains stay green while new receipts sign
-under a new key: `receipts verify chain.json --pub new.pub --pub old.pub`. A
+under a new key: `tamper-signal verify chain.json --pub new.pub --pub old.pub`. A
 signature valid under any trusted key is trusted; the browser surfaces accept
 a list the same way (the `<tamper-signal>` element takes a space-separated
 `pub-key` list).
@@ -233,7 +287,7 @@ on disk. The env var wins over any `--key` path while set. The Node CLI
 (`tamper-signal ingest`) honors the same env var with the same precedence.
 
 Add `--json` to get a structured verdict instead of the text report (both
-CLIs: `receipts verify --json` and `tamper-signal verify --json` emit the
+CLIs: `tamper-signal verify --json` and `tamper-signal verify --json` emit the
 same payload). Parse this rather than scraping text:
 
 ```json
@@ -335,7 +389,7 @@ jobs:
       - name: Verify the receipt chain
         run: |
           set +e
-          receipts verify receipts/chain.json --json | tee verdict.json
+          tamper-signal verify receipts/chain.json --json | tee verdict.json
           code=$?
           if [ "$code" = "2" ]; then
             echo "::warning::The light is yellow, a human should look: $(python -c 'import json;print("; ".join(json.load(open("verdict.json"))["caveats"]))')"
@@ -355,7 +409,7 @@ run. This is opt-in and starts at ingest, where the producer declares how much
 movement is normal:
 
 ```bash
-receipts ingest export.csv --origin "nightly" --band 5% --settle 72h \
+tamper-signal ingest export.csv --origin "nightly" --band 5% --settle 72h \
   --bucket-column day --key keys/signing.key --out receipts/
 ```
 
@@ -378,7 +432,7 @@ Run history is automatic. Every non-red CLI `verify` archives a compact run
 snapshot under `receipts/history/` (signed when a private key is available).
 Snapshots are what give the chain a memory; the cross-run judgment reads them
 on the next verify and folds its findings in as yellow caveats (never red).
-History is CLI-local: `receipts serve` 404s anything under `history/`, because
+History is CLI-local: `tamper-signal serve` 404s anything under `history/`, because
 snapshots carry per-day totals and run cadence that the published receipts do
 not. History is weaker evidence than the chain itself: snapshots sit outside
 `receipt_hashes` and outside anchoring.
@@ -386,8 +440,8 @@ not. History is weaker evidence than the chain itself: snapshots sit outside
 Two read-only commands work the archived history, both exit 0:
 
 ```bash
-receipts diff                          # current chain vs the latest differing snapshot
-receipts log --granularity week        # per-metric trend across runs, oldest first
+tamper-signal diff                          # current chain vs the latest differing snapshot
+tamper-signal log --granularity week        # per-metric trend across runs, oldest first
 ```
 
 `diff` reports per-stage code-hash changes and a structured totals delta
@@ -406,11 +460,11 @@ transparency log:
 
 ```bash
 pip install "tamper-signal[anchor]"
-receipts anchor                       # browser login locally; automatic in GitHub Actions
-receipts verify receipts/chain.json --anchor
+tamper-signal anchor                       # browser login locally; automatic in GitHub Actions
+tamper-signal verify receipts/chain.json --anchor
 ```
 
-Agent note: run `receipts anchor` in CI (GitHub Actions and similar), where
+Agent note: run `tamper-signal anchor` in CI (GitHub Actions and similar), where
 an ambient OIDC credential makes it non-interactive. Outside CI it opens a
 browser login and blocks until a human completes it; do not invoke it from
 an unattended session.
@@ -425,7 +479,7 @@ pipeline re-runs.
 `anchor.json` (next to chain.json) records the Sigstore bundle plus the
 identity and issuer used; `verify --anchor` enforces that identity, reports
 the logged time on success, exits 2 when no anchor exists, and exits 1 when
-the chain changed after anchoring. `receipts anchor --json` emits the anchor
+the chain changed after anchoring. `tamper-signal anchor --json` emits the anchor
 record (identity, issuer, integrated time) as JSON for CI logs. An anchor
 made with `--staging` is rejected at verify time unless you pass
 `--anchor-staging`, so the anchor file cannot pick a weaker trust root. To
@@ -434,7 +488,7 @@ pin whose anchor is acceptable instead of trusting the recorded one, pass
 like:
 
 ```bash
-receipts verify receipts/chain.json --anchor \
+tamper-signal verify receipts/chain.json --anchor \
   --anchor-identity "https://github.com/OWNER/REPO/.github/workflows/anchor.yml@refs/heads/main" \
   --anchor-issuer "https://token.actions.githubusercontent.com"
 ```
@@ -443,26 +497,115 @@ Re-anchor after every pipeline run that changes the chain. Honest scope: an
 anchor proves this exact chain existed at the logged time under the recorded
 identity, nothing more.
 
+## 5c. Live-source watcher (optional, for feeds you do not re-export by hand)
+
+When the source is a live HTTP/JSON-API or RSS feed rather than a file you
+re-export, the watcher keeps it on the same signed chain: it polls, judges the
+new data against the declared band/settle (§5a), and **auto-appends only a
+clean change**. A retroactive change to an already-settled period — or a slow
+drift that cumulatively breaches the band — is **not** signed unattended; it is
+withheld as a signed *pending event* and paused for a human reason.
+
+```bash
+pip install "tamper-signal[watch]"
+# Seed the chain once from any first sample, declaring the tolerance (§5a):
+tamper-signal ingest first.csv --origin "https://feed.example/rates" \
+  --band 5% --settle 72h --bucket-column day --key keys/watch.key --out receipts/
+
+# One tick (poll once, judge, append-if-clean, else withhold). Config is a
+# small JSON file: {url, format: json|rss, source_id, optional field_map,
+# band/settle/bucket_column, per_tick_cap}.
+tamper-signal watch --config feed.json --key keys/watch.key --out receipts/
+```
+
+- **`source_id`** is a STABLE identity for the feed (a feed has no filename).
+  Keep it constant across ticks, or cross-run judgment cannot match history and
+  the watcher refuses rather than appending unjudged.
+- Change detection is a **full-content fingerprint**, never the server's
+  `ETag`/`304` — a compromised origin cannot replay an old validator to hide a
+  mutation.
+- The fetch is **SSRF-hardened**: only public hosts (an affirmative `is_global`
+  check), redirects off, TLS verified, bounded by bytes and wall-clock. RSS is
+  parsed through `defusedxml` (billion-laughs / XXE rejected).
+- The watcher key must be the chain's trusted signer (else it fails closed).
+  Use a **dedicated** key, distinct from any interactive human key, for
+  isolation and revocability.
+
+Withheld changes are reviewed explicitly — each acceptance signs its own reason:
+
+```bash
+tamper-signal review                       # list pending changes awaiting sign-off
+tamper-signal review accept <hash> --reason "confirmed by finance" --author dana
+tamper-signal review reject <hash>         # discard; the chain is untouched
+```
+
+Accepting commits the exact reviewed candidate and signs a reason linked to it;
+if later ticks advanced the chain in the meantime, acceptance re-surfaces for
+review instead of overwriting newer data. The console shows pending changes in
+a distinct "AWAITING REVIEW" section that never affects the verdict.
+
+**Deployment — a local file-writer, not a server.** The recommended shape is
+the **stateless tick under a systemd timer / cron**, so the signing key is not
+resident between runs. A `--daemon --interval <seconds>` loop exists for hosts
+without a scheduler; it only polls and writes files. Harden the unit:
+
+```ini
+# /etc/systemd/system/tamper-watch.service  (paired with a .timer)
+[Service]
+Type=oneshot
+User=tamper-watch                 # dedicated, unprivileged user
+ExecStart=/usr/bin/tamper-signal watch --config /etc/tamper/feed.json \
+  --key %d/watch.key --out /var/lib/tamper/receipts
+LoadCredential=watch.key:/etc/tamper/watch.key   # key material via $CREDENTIALS_DIRECTORY, not the env
+NoNewPrivileges=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=/var/lib/tamper/receipts
+PrivateTmp=true
+```
+
+Deliver the key with `LoadCredential=` (it lands under `%d`/`$CREDENTIALS_DIRECTORY`,
+mode 0400, never in the process environment) — do **not** put the key material
+in `EnvironmentFile`, which would expose it via `/proc/<pid>/environ`. Keep the
+key file `0600`; the watcher fails closed if it is group/world-readable.
+
 ## 6. Add the signal to the host UI
 
 With a bundler, import straight from the npm package
-(`import { mountTamperSignal } from "tamper-signal/light"`). Without one,
-vendor two files from this repo into the host app, side by side (light.js
+(`import { mountTamperSignal } from "tamper-signal/light"`). Without one, copy
+the browser assets into the host app. The CLI does this for you (no hunting
+through `site-packages` or `node_modules`):
+
+```bash
+tamper-signal assets --out badge/        # Python; tamper-signal assets --out badge/ on Node
+```
+
+That writes `light.js`, `badge.js`, `element.js`, `table.js`, and `console.js`
+into `badge/`. For the inline signal you need two of them side by side (light.js
 imports `./badge.js` relatively):
 
 - `badge/badge.js` (verification core + the expandable badge)
 - `badge/light.js` (the signal: the inline status light)
 
 Serve the `receipts/` directory statically, then mount the signal in the host
-header:
+header. Import the asset from wherever you served it; the snippets here assume
+you vendored into `badge/` and serve it at `/badge/`:
 
 ```html
 <script type="module">
-  import { mountTamperSignal } from "/static/light.js";
+  import { mountTamperSignal } from "/badge/light.js";
   mountTamperSignal(document.querySelector("header"), "/receipts/chain.json");
 </script>
 ```
 
+**These surfaces verify over HTTP, not from `file://`.** The signal, badge, and
+table all `fetch()` the chain (and table.json), which the browser blocks on a
+`file://` page, so opening `index.html` directly leaves them silently
+unverified. Serve the page over HTTP: any static server works, and
+`tamper-signal serve` is the one-liner for local dev. There is no `file://` mode; an
+offline recipient verifies with the CLI on a bundle (`tamper-signal export --bundle`,
+step 8) instead.
+
 React hosts: `import { TamperSignal } from "tamper-signal/react"` (or vendor
 `badge/light-react.js`), then `<TamperSignal chain="/receipts/chain.json" />`.
 
@@ -525,7 +668,7 @@ over; it is the page to open when the light is anything but green.
 Manual fallback when no helper fits: serve the directory statically (Flask
 `static_folder="receipts"`, FastAPI `StaticFiles`, Express
 `express.static("receipts")`), or copy `receipts/` into the public dir of a
-static site at build time. For local development, `receipts serve` serves
+static site at build time. For local development, `tamper-signal serve` serves
 the directory on localhost with CORS open and caching off.
 
 Placement: the right end of the host header, after the host's own controls.
@@ -570,27 +713,48 @@ verified table, not just charts. Two steps:
 
    ```bash
    # Python
-   receipts export --chain receipts/chain.json --data path/to/dashboard_data.xlsx
+   tamper-signal export receipts/chain.json --data path/to/dashboard_data.xlsx
    # JavaScript
    tamper-signal export receipts/chain.json --data path/to/dashboard_data.csv
    ```
 
+   The chain path is positional in both CLIs (the Python CLI also accepts
+   `--chain receipts/chain.json` for the same value).
+
    This writes `receipts/table.json` and refuses if the data does not match
    the final receipt (the Data tab only ever shows attested data). Re-run it
    whenever the pipeline runs, or the tab will honestly report a stale table.
    In a JS build you can write it programmatically instead with
    `canonicalDocument(finalRecords)` (see step 1b).
 
-2. Mount the table (vendor `badge/table.js` beside badge.js, or import
-   `tamper-signal/table`):
+2. Mount the table (vendor `badge/table.js` beside badge.js with
+   `tamper-signal assets`, or import `tamper-signal/table`):
 
    ```html
    <script type="module">
-     import { mountReceiptTable } from "/static/table.js";
+     import { mountReceiptTable } from "/badge/table.js";
      mountReceiptTable(document.querySelector("#data-tab"), "/receipts/chain.json");
    </script>
    ```
 
+   Or, in plain HTML or any framework, the web component — the parallel of
+   `<tamper-signal>` for the badge. Importing `tamper-signal/table` (or
+   `badge/table.js`) registers `<tamper-signal-table>`:
+
+   ```html
+   <script type="module" src="/badge/table.js"></script>
+   <tamper-signal-table chain="/receipts/chain.json"></tamper-signal-table>
+   ```
+
+   Attributes: `chain` (required), `table` (table.json URL; defaults to
+   table.json beside the chain), `max-rows` (rows before the "show all"
+   footer, default 500), and `strict` (present = the table emits its verdict
+   with `strict: true` so the host can gate other views on a broken chain). The
+   table never blocks UI itself; after each verification it fires a bubbling
+   `tamper-signal:state` event (and an `onState` callback) carrying
+   `{ state, attested, strict }`. Default (no `strict`) stays always-on and
+   always-honest. Recommended host gate: `strict && (state === "red" || !attested)`.
+
 The component re-hashes the served document in the viewer's browser and
 compares it against the final receipt, so VERIFIED means the rows on screen
 are byte-for-byte the attested data. It renders its own states: green, yellow
@@ -600,7 +764,7 @@ attested data" when table.json is stale or edited. Design reference:
 
 ## 9. Verify your work before reporting done
 
-On a Python project, run `receipts doctor` first: it checks the Python version,
+On a Python project, run `tamper-signal doctor` first: it checks the Python version,
 that the private key exists and is not tracked by git, that .gitignore covers
 it, and that the chain verifies; pass `--url http://localhost:PORT/chain.json`
 to also confirm the receipts directory is reachable over HTTP. Every failure
@@ -609,7 +773,7 @@ Python-only; on a JS project, `tamper-signal verify receipts/chain.json` exits
 0 when the chain is healthy, and you should confirm the private key is
 gitignored yourself.) Then confirm the user-visible surfaces:
 
-1. `receipts verify receipts/chain.json --pub keys/signing.pub` exits 0.
+1. `tamper-signal verify receipts/chain.json --pub keys/signing.pub` exits 0.
 2. Load the host page: the pill reads `VERIFIED · chain intact` (click it for
    the per-stage popover).
 3. Negative test without touching the user's real chain: this repo commits

package/README.md

@@ -2,7 +2,7 @@
 
 # The light is green, the data is clean.
 
-[![PyPI](https://img.shields.io/pypi/v/tamper-signal)](https://pypi.org/project/tamper-signal/) [![npm](https://img.shields.io/npm/v/tamper-signal)](https://www.npmjs.com/package/tamper-signal) [![Socket Badge (npm)](https://badge.socket.dev/npm/package/tamper-signal/1.6.0)](https://socket.dev/npm/package/tamper-signal/overview/1.6.0) [![Socket Badge (PyPI)](https://badge.socket.dev/pypi/package/tamper-signal/1.6.0)](https://socket.dev/pypi/package/tamper-signal/overview/1.6.0) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/tamper-signal)](https://pypi.org/project/tamper-signal/) [![npm](https://img.shields.io/npm/v/tamper-signal)](https://www.npmjs.com/package/tamper-signal) [![Socket Badge (npm)](https://badge.socket.dev/npm/package/tamper-signal/2.0.0)](https://socket.dev/npm/package/tamper-signal/overview/2.0.0) [![Socket Badge (PyPI)](https://badge.socket.dev/pypi/package/tamper-signal/2.0.0)](https://socket.dev/pypi/package/tamper-signal/overview/2.0.0) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 Your social team exports a month of TikTok performance data. Someone vibe-codes a dashboard on top of it with an AI assistant in an afternoon. It looks great. Then a transform silently drops 22 rows, or the model hallucinates an aggregation, and the numbers in front of your boss are wrong. Nothing in that workflow catches it. This is the missing verification layer: every stage of the pipeline signs a receipt for what went in and what came out, and one command (or a badge on the dashboard itself) tells you whether the chain is intact, or exactly where it broke and by how much.
 
@@ -28,7 +28,7 @@ The badge and the verifier reduce the whole chain to one state:
 
 *The inline status light: a small dark instrument in your dashboard's header. When the chain breaks, it reaches into the page and flags the exact metric that no longer descends from the source.*
 
-Honest status: all three verdicts are implemented in `receipts verify` and the browser badge. Yellow today covers two detectable caveats (a coverage gap in the receipt numbering, and signatures that only verify under the chain's embedded key rather than the key you trust) plus opt-in control-total drift via `--warn-drift`. The animations in this README are renders of the design mockups in `designs/`; the interfaces they depict have since shipped (`badge/light.js`, `badge/table.js`, `badge/console.js`). The badge also renders a separate amber state ("could not load" or "verification unsupported in this browser"); that is a capability fallback that says nothing about the chain, not the yellow verdict.
+Honest status: all three verdicts are implemented in `tamper-signal verify` and the browser badge. Yellow today covers two detectable caveats (a coverage gap in the receipt numbering, and signatures that only verify under the chain's embedded key rather than the key you trust) plus opt-in control-total drift via `--warn-drift`. The animations in this README are renders of the design mockups in `designs/`; the interfaces they depict have since shipped (`badge/light.js`, `badge/table.js`, `badge/console.js`). The badge also renders a separate amber state ("could not load" or "verification unsupported in this browser"); that is a capability fallback that says nothing about the chain, not the yellow verdict.
 
 ## 60-second quickstart
 
@@ -37,26 +37,31 @@ Python 3.11+. Open source (MIT).
 ```bash
 pip install tamper-signal
 git clone https://github.com/welovejeff/tamper-evident-verification && cd tamper-evident-verification
-receipts demo
+tamper-signal demo
 ```
 
-`receipts demo` runs the whole story end to end: generates a deliberately messy sample export, ingests it, runs two AI-written-style transforms, verifies the chain (PASS), then tampers with one spend value and verifies again (FAIL, pinpointing the broken link and the totals delta). It finishes by serving the badge at `http://localhost:8000/badge/badge.html` so you can see green, yellow, and red side by side.
+`tamper-signal demo` runs the whole story end to end: generates a deliberately messy sample export, ingests it, runs two AI-written-style transforms, verifies the chain (PASS), then tampers with one spend value and verifies again (FAIL, pinpointing the broken link and the totals delta). It finishes by serving the badge at `http://localhost:8000/badge/badge.html` so you can see green, yellow, and red side by side.
+
+> **`tamper-signal: command not found`?** pip installed the script into a bin directory that is not on PATH (common on the python.org framework Python, the default macOS download). Either run it through the same interpreter, `python3 -m tamper_signal verify ...` (works as a drop-in for every `tamper-signal ...` command), or link it onto PATH once: `sudo ln -sf "$(python3 -c 'import sysconfig;print(sysconfig.get_path("scripts"))')/tamper-signal" /usr/local/bin/tamper-signal`.
 
 ## CLI
 
 ```bash
-receipts init                 # scaffold: keys, .gitignore safety, receipts dir (idempotent)
-receipts ingest sample_export.xlsx --origin "TikTok export, May 2026" --key keys/signing.key --out receipts/
-receipts verify receipts/chain.json --pub keys/signing.pub --data dashboard.xlsx
-receipts diff                 # compare two runs: code-hash changes and totals deltas (read-only)
-receipts log                  # archived run history as a per-metric trend across runs (read-only)
-receipts doctor               # integration self-check with actionable fixes
-receipts serve                # serve receipts/ on localhost with CORS (dev only)
+tamper-signal init                 # scaffold: keys, .gitignore safety, receipts dir (idempotent)
+tamper-signal ingest sample_export.xlsx --origin "TikTok export, May 2026" --key keys/signing.key --out receipts/
+tamper-signal verify receipts/chain.json --pub keys/signing.pub --data dashboard.xlsx
+tamper-signal diff                 # compare two runs: code-hash changes and totals deltas (read-only)
+tamper-signal log                  # archived run history as a per-metric trend across runs (read-only)
+tamper-signal doctor               # integration self-check with actionable fixes
+tamper-signal serve                # serve receipts/ on localhost with CORS (dev only)
+tamper-signal assets --out badge/  # vendor the browser surfaces (light/badge/element/table/console.js) into a project
+tamper-signal annotate --reason "backfill approved" --author dana   # sign a reason onto a receipt (chain of custody)
+tamper-signal watch --config feed.json --out receipts/   # poll a live feed onto the chain (needs [watch]; see below)
 ```
 
 `--pub` repeats for key rotation (any trusted key verifies), and `TAMPER_SIGNAL_KEY` can carry the PEM private key in CI so no key file touches disk. `ingest` and `verify --data` accept .xlsx, .csv, .tsv, .json (array of objects), and .ndjson; the semantic hash is identical across formats, so an xlsx ingest verifies against a CSV copy of the same data. `verify` exits with the traffic light: 0 green, 1 red, 2 yellow (verifies, with caveats). Add `--warn-drift` to also flag any control-totals movement across links as a caveat; it is off by default because filters and aggregations legitimately move totals. `--json` emits a structured verdict (schema in `AGENTS.md`) for CI and coding agents.
 
-For a recurring refresh of the same report, declare a tolerance at ingest with `--band` (default 5%) and `--settle` (default 72h), optionally keyed off a date column with `--bucket-column`. The declaration is signed into the source manifest. Every non-red `verify` then archives a run snapshot under `receipts/history/`, and the next verify judges this run against that memory: recent buckets may drift within the band, settled buckets (older than the window) may not, and any breach is a yellow caveat. `receipts diff` and `receipts log` read that history (both read-only, exit 0) to show what moved between runs and the per-metric trend across them. History is CLI-local and weaker evidence than the chain: it stays out of `receipt_hashes` and anchoring, and `serve` never exposes it.
+For a recurring refresh of the same report, declare a tolerance at ingest with `--band` (default 5%) and `--settle` (default 72h), optionally keyed off a date column with `--bucket-column`. The declaration is signed into the source manifest. Every non-red `verify` then archives a run snapshot under `receipts/history/`, and the next verify judges this run against that memory: recent buckets may drift within the band, settled buckets (older than the window) may not, and any breach is a yellow caveat. `tamper-signal diff` and `tamper-signal log` read that history (both read-only, exit 0) to show what moved between runs and the per-metric trend across them. History is CLI-local and weaker evidence than the chain: it stays out of `receipt_hashes` and anchoring, and `serve` never exposes it.
 
 Transforms record their own receipts by wrapping any list-of-dicts to list-of-dicts function:
 
@@ -101,7 +106,7 @@ TikTok/Sprinklr export.xlsx
   [transform_agg]  ──> 002_transform_aggregate.json
         |
         v
-  dashboard data  <─── receipts verify: walk every link, check every signature
+  dashboard data  <─── tamper-signal verify: walk every link, check every signature
 ```
 
 Each receipt contains the SHA-256 of its input, the SHA-256 of the transform's source code, the SHA-256 of its output, and human-legible control totals (row counts, numeric sums, date ranges, null counts). Receipts link because each stage's input hash must equal the prior stage's output hash. Everything is signed with Ed25519; `chain.json` is just an ordered list of receipt files plus the public key.
@@ -142,7 +147,7 @@ React, with a bundler: `import { TamperSignal } from "tamper-signal/react"` and
 
 The pill expands to a popover: the per-stage table when green, the caveat list when yellow, the broken link with its totals delta when red. In the red state the light also reaches into the page: give any metric element a `data-receipt-column="spend_usd"` attribute, and if that column moved at the broken link the element gets outlined and tagged `tamper signal: unverified value`. Mark up your metrics once and the light flags the exact number that no longer descends from the source.
 
-Options on the fourth argument: `watch` (re-verify every N ms and pulse on transitions), `warnDrift`, `receiptsHref`, and `surface: "dark"` so the pill inverts to stay the one foreign object on a dark host (`surface` describes your page; `invert: true` is a shortcut for it, and the deprecated `theme: "light"` is the same thing). `receipts demo` serves a live three-state example at `http://localhost:8000/badge/light.html`.
+Options on the fourth argument: `watch` (re-verify every N ms and pulse on transitions), `warnDrift`, `receiptsHref`, and `surface: "dark"` so the pill inverts to stay the one foreign object on a dark host (`surface` describes your page; `invert: true` is a shortcut for it, and the deprecated `theme: "light"` is the same thing). `tamper-signal demo` serves a live three-state example at `http://localhost:8000/badge/light.html`.
 
 One-call framework helpers serve the receipts directory and the browser files together and hand back the mounting snippet: `tamper_signal.flask_ext.attach(app)`, `tamper_signal.fastapi_ext.attach(app)`, and `tamperSignal(app)` from `tamper-signal/express`. Streamlit apps get a server-side-verified pill and table caption via `tamper_signal.streamlit_ext` (labeled as the weaker check it is).
 
@@ -150,7 +155,7 @@ One-call framework helpers serve the receipts directory and the browser files to
 
 We think any dashboard built on verified data should let you see the data. Not a tooltip, not an export-on-request: a Data tab, right next to the charts, showing the raw verified table the pretty numbers came from. If the chain is intact and the light is green, there is no reason to hide the rows, and if you find yourself wanting to hide them, that's worth sitting with. A chart asks you to believe; a table lets you check. Green light, open table: that's the whole standard.
 
-It ships: `receipts export` writes the canonical table document next to the chain (refusing data that does not match the final receipt), and `mountReceiptTable(el, "/receipts/chain.json")` from `badge/table.js` (npm: `tamper-signal/table`) renders it after re-hashing it in the viewer's browser against the final receipt. VERIFIED means the rows on screen are byte-for-byte the attested data; a stale or edited table.json renders dimmed under a "not the attested data" strip, and a broken chain flags the columns that moved at the break. Live demo: `badge/table.html`.
+It ships: `tamper-signal export` writes the canonical table document next to the chain (refusing data that does not match the final receipt), and `mountReceiptTable(el, "/receipts/chain.json")` from `badge/table.js` (npm: `tamper-signal/table`) renders it after re-hashing it in the viewer's browser against the final receipt. VERIFIED means the rows on screen are byte-for-byte the attested data; a stale or edited table.json renders dimmed under a "not the attested data" strip, and a broken chain flags the columns that moved at the break. Live demo: `badge/table.html`.
 
 ![The Data tab: the dashboard flips to a dark raw-table view where a broken chain is localized to the views column](docs/media/data-tab.gif)
 
@@ -158,21 +163,36 @@ It ships: `receipts export` writes the canonical table document next to the chai
 
 ## Take your data with you
 
-Verified data should be portable, proof and all. `receipts export --bundle` (or `tamper-signal export --bundle`) writes a verified bundle: a zip of the data file plus `chain.json` and its receipts, kept byte for byte, so whoever you send it to runs `receipts verify chain.json` and gets the same light, offline. In the browser, the Data tab's "Take your data" control exports the attested data client-side as that bundle or as a bare rows-only file (csv/tsv/json/ndjson; xlsx routes through the Python CLI). Because the semantic hash is format-agnostic, a CSV you export here re-verifies as JSON and the light stays green; numeric-looking text canonicalizes to its number, so leading zeros and trailing decimals do not survive the round trip.
+Verified data should be portable, proof and all. `tamper-signal export --bundle` (or `tamper-signal export --bundle`) writes a verified bundle: a zip of the data file plus `chain.json` and its receipts, kept byte for byte, so whoever you send it to runs `tamper-signal verify chain.json` and gets the same light, offline. In the browser, the Data tab's "Take your data" control exports the attested data client-side as that bundle or as a bare rows-only file (csv/tsv/json/ndjson; xlsx routes through the Python CLI). Because the semantic hash is format-agnostic, a CSV you export here re-verifies as JSON and the light stays green; numeric-looking text canonicalizes to its number, so leading zeros and trailing decimals do not survive the round trip.
 
-To bring an updated file back, `receipts ingest --as replace|period`. `replace` (the default) re-signs a fresh chain and archives the prior one under `receipts/archive/`. `period` continues the chain's run history as the next period, judged against prior runs through the prior run's signed tolerance band; it continues only under a trusted signer (`--pub` to trust a key other than the chain's) and refuses an untrusted one rather than appending silently. Re-attestation is never silent: the importer's identity is recorded, and an unrecognized signer stays yellow.
+To bring an updated file back, `tamper-signal ingest --as replace|period`. `replace` (the default) re-signs a fresh chain and archives the prior one under `receipts/archive/`. `period` continues the chain's run history as the next period, judged against prior runs through the prior run's signed tolerance band; it continues only under a trusted signer (`--pub` to trust a key other than the chain's) and refuses an untrusted one rather than appending silently. Re-attestation is never silent: the importer's identity is recorded, and an unrecognized signer stays yellow.
 
 ## The console
 
-The light answers "is it fine?"; the console answers "where, exactly, and by how much?" `mountReceiptConsole(el, "/receipts/chain.json")` from `badge/console.js` (npm: `tamper-signal/console`) renders the chain as an inspectable pipeline: links carry the hash they proved, a break severs the link with the break card pinned at it, coverage gaps appear as ghost nodes at their position, and the event log mirrors `receipts verify` line for line. Every attach helper also serves it ready-made at `/tamper-signal/console`. Live demo: `badge/console.html`.
+The light answers "is it fine?"; the console answers "where, exactly, and by how much?" `mountReceiptConsole(el, "/receipts/chain.json")` from `badge/console.js` (npm: `tamper-signal/console`) renders the chain as an inspectable pipeline: links carry the hash they proved, a break severs the link with the break card pinned at it, coverage gaps appear as ghost nodes at their position, and the event log mirrors `tamper-signal verify` line for line. Every attach helper also serves it ready-made at `/tamper-signal/console`. Live demo: `badge/console.html`.
 
 ![The verification console: a pipeline of signed receipts where a tampered stage severs the chain at the exact link](docs/media/console.gif)
 
 *The verification console: calm when green, surgical when red.*
 
+Below the pipeline the console renders the **chain of custody**: the imports and changes, each signed reason attached to the receipt it explains (`tamper-signal annotate`), and any changes **awaiting human review**. It is an additive layer over the published `timeline.json` — it never feeds the verdict above.
+
+## Live-source watcher (optional)
+
+When the source is a live feed rather than a file you re-export by hand, the watcher keeps it on the same signed chain. `tamper-signal watch` (behind `pip install "tamper-signal[watch]"`) polls an HTTP/JSON-API or RSS/Atom endpoint, judges the new data against the declared band/settle, and **auto-appends only a clean change**. A retroactive edit to an already-settled period — or a slow drift that cumulatively breaches the band — is never signed unattended: it is withheld as a signed *pending event* and paused for a human.
+
+```bash
+pip install "tamper-signal[watch]"
+tamper-signal watch --config feed.json --key keys/watch.key --out receipts/   # one tick
+tamper-signal review                                                          # list withheld changes
+tamper-signal review accept <hash> --reason "confirmed by finance"            # sign off + commit
+```
+
+The fetch is SSRF-hardened (public hosts only, redirects off, TLS verified, byte + wall-clock caps; RSS parsed through `defusedxml`), change detection uses a full-content fingerprint rather than a trust-me `ETag`, and the unattended commit is crash-safe. The recommended deployment is the stateless tick under a systemd timer or cron, so the signing key is not resident between runs — see `AGENTS.md` §5c for a hardened unit. `watch`/`review` are Python-only today; the chains they write are read and verified by the JavaScript stack unchanged.
+
 ## Anchoring (optional)
 
-`pip install "tamper-signal[anchor]"`, then `receipts anchor` signs the exact bytes of chain.json into the public Sigstore transparency log under your OIDC identity (browser login locally, automatic in GitHub Actions). Because chain.json records the sha256 of every receipt file, the anchor covers the receipts themselves, not just their names. `receipts verify --anchor` then proves this exact chain, receipts included, existed at the logged time, independent of the signing key, closing the "whoever holds the key can quietly re-sign everything" gap for the moments that matter. A missing anchor is a yellow caveat; a chain that changed after anchoring is red.
+`pip install "tamper-signal[anchor]"`, then `tamper-signal anchor` signs the exact bytes of chain.json into the public Sigstore transparency log under your OIDC identity (browser login locally, automatic in GitHub Actions). Because chain.json records the sha256 of every receipt file, the anchor covers the receipts themselves, not just their names. `tamper-signal verify --anchor` then proves this exact chain, receipts included, existed at the logged time, independent of the signing key, closing the "whoever holds the key can quietly re-sign everything" gap for the moments that matter. A missing anchor is a yellow caveat; a chain that changed after anchoring is red.
 
 ## What this proves, and what it doesn't
 

package/badge/console.d.ts

@@ -11,6 +11,12 @@ export interface ReceiptConsoleOptions {
   warnDrift?: boolean;
   /** Trusted public key hex, single or rotation list. */
   pubKey?: string | string[];
+  /**
+   * URL of the published `timeline.json` for the chain-of-custody layer.
+   * Defaults to `timeline.json` beside the chain. The custody layer is
+   * additive and never affects the verdict (which comes from `chain.json`).
+   */
+  timeline?: string;
 }
 
 export interface ReceiptConsoleHandle {