tamper-signal 2.0.0 → 2.1.1

package/AGENTS.md

@@ -569,7 +569,15 @@ 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
+## 6. Add the light to the host UI (the room is already served)
+
+The UI is two things, always shipped together: **the light** (the inline
+status pill, the lightest touch) and **the room** (the one robust surface
+behind it — the attested data table with the chain rail, break exhibit,
+receipt inspector, event log, chain of custody, and evidence export). The
+attach helpers below serve the room automatically and pre-wire the light's
+"view receipts →" link to it; if you mount by hand, wiring `receiptsHref` to
+a room is YOUR one extra line — the light must never dead-end in raw JSON.
 
 With a bundler, import straight from the npm package
 (`import { mountTamperSignal } from "tamper-signal/light"`). Without one, copy
@@ -580,24 +588,34 @@ through `site-packages` or `node_modules`):
 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):
+That writes `light.js`, `badge.js`, `element.js`, `table.js`, `console.js`,
+and `room.js` into `badge/`. For the inline signal you need two of them side
+by side (light.js imports `./badge.js` relatively); the room needs `room.js`
+and `badge.js`:
 
-- `badge/badge.js` (verification core + the expandable badge)
+- `badge/badge.js` (the shared verification core)
 - `badge/light.js` (the signal: the inline status light)
+- `badge/room.js` (the room: `mountSignalRoom`, `<tamper-signal-room>`)
 
 Serve the `receipts/` directory statically, then mount the signal in the host
-header. Import the asset from wherever you served it; the snippets here assume
-you vendored into `badge/` and serve it at `/badge/`:
+header and a room for it to link to. Import the assets from wherever you
+served them; the snippets here assume you vendored into `badge/` and serve it
+at `/badge/`:
 
 ```html
 <script type="module">
   import { mountTamperSignal } from "/badge/light.js";
-  mountTamperSignal(document.querySelector("header"), "/receipts/chain.json");
+  import { mountSignalRoom } from "/badge/room.js";
+  mountSignalRoom(document.querySelector("#data"), "/receipts/chain.json");
+  mountTamperSignal(document.querySelector("header"), "/receipts/chain.json",
+    undefined, { receiptsHref: "#tamper-room" });
 </script>
 ```
 
+(The first room in a document owns the id `tamper-room`, so `#tamper-room`
+always reaches it. If the room lives on its own page, point `receiptsHref` at
+that URL instead — the attach helpers do exactly this.)
+
 **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
@@ -615,22 +633,30 @@ in the `exports` map), so imports like `tamper-signal/react`, `/table`, and
 the Node entries (`.`, `/express`) expect `@types/node` as a normal Node
 project already has.
 
-Any other framework, or plain HTML: the web component. Import
+Any other framework, or plain HTML: the web components. Import
 `tamper-signal/element` (or vendor `badge/element.js`, which needs light.js
-and badge.js beside it) and write one tag:
+and badge.js beside it) for the light, `tamper-signal/room` (or
+`badge/room.js`) for the room, and write one tag each:
 
 ```html
-<tamper-signal chain="/receipts/chain.json"></tamper-signal>
+<tamper-signal chain="/receipts/chain.json" receipts-href="#tamper-room"></tamper-signal>
+<tamper-signal-room chain="/receipts/chain.json"></tamper-signal-room>
 ```
 
-Attributes mirror the options: `pub-key`, `watch`, `warn-drift`,
+Light attributes mirror the options: `pub-key`, `watch`, `warn-drift`,
 `receipts-href`, `surface` (`"light"` default or `"dark"` for a dark host),
 `invert` (present = shortcut for `surface="dark"`); `theme` is the deprecated
-alias of `surface="dark"`.
-
-Prefer the one-call attach helpers; each serves the receipts directory AND
-the bundled browser assets, and returns a `snippet` to render once in the
-layout (it mounts the signal into `header`, falling back to `body`):
+alias of `surface="dark"`. Room attributes: `chain` (required), `table`,
+`timeline`, `pub-key`, `watch`, `warn-drift`, `strict`, `max-rows`, `focus`,
+`preset` (`room` | `table` | `console`), `density` (`embedded` | `page`).
+React hosts use `<tamper-signal-room>` straight from JSX (`badge/room.d.ts`
+ships the JSX typing) — import `tamper-signal/room` for the side effect.
+
+Prefer the one-call attach helpers; each serves the receipts directory, the
+bundled browser assets, AND the room page at `<assets_prefix>/receipts`, and
+returns a `snippet` to render once in the layout (it mounts the signal into
+`header`, falling back to `body`, with `receiptsHref` pre-wired to the served
+room):
 
 ```python
 # Flask
@@ -659,11 +685,19 @@ These verify SERVER-SIDE with the Python verifier and the pill says so;
 Streamlit cannot serve the receipts directory for the in-browser walk, and
 faking the stronger claim would violate rule 1.
 
-Every attach helper also serves the verification console at
-`<assets_prefix>/console` (e.g. `/tamper-signal/console`): the chain as an
-inspectable pipeline with the break pinned at the severed link, for the
-dashboard's builder and for auditors. Mention it to the user when handing
-over; it is the page to open when the light is anything but green.
+Every attach helper serves the room at `<assets_prefix>/receipts` (e.g.
+`/tamper-signal/receipts`) and adds `?focus=auto` to the light's link, so a
+red chain opens scrolled to the break exhibit and a yellow one to the first
+caveat. The helper return exposes `roomUrl` and `roomSnippet` (an inline
+embedded room, for a host that renders its own Data tab); `console_url` /
+`consoleUrl` stays reachable, serving the same room with its rail open.
+Opting out (`room=False` / `{ room: false }`) is not recommended; the light
+will link to raw JSON. Mention the room to the user when handing over; it is
+the page to open when the light is anything but green.
+
+Hosts that want their own tab chrome: mount `roomSnippet` inside the tab,
+pass `strict`, listen for the bubbling `tamper-signal:state` event, and paint
+your own dot on your own tab — the room never touches host chrome.
 
 Manual fallback when no helper fits: serve the directory statically (Flask
 `static_folder="receipts"`, FastAPI `StaticFiles`, Express
@@ -679,8 +713,8 @@ Options on the fourth argument: `watch` (re-verify every N ms), `warnDrift`,
 boolean shortcut for `surface: "dark"`); the old `theme: "light"` still works
 as the `surface: "dark"` alias.
 
-The expandable badge (`renderReceiptBadge(el, "/receipts/chain.json")`) is the
-alternative for pages with room for a full-width strip.
+The expandable badge (`renderReceiptBadge`) is deprecated (removed in 3.0):
+mount the light with the room behind it instead.
 
 ## 7. Let the signal flag broken metrics
 
@@ -701,66 +735,60 @@ so their column never reaches `numeric_sums`, and a `data-receipt-column` on it
 can never flag a change — silently. Grouping isn't auto-stripped on purpose: it
 would diverge from the Python canonicalization and is locale-ambiguous (`"1,234"`
 is 1234 or 1.234?). Fix it upstream with a signed normalize stage that strips
-the separators before the receipt is written. `tamper-signal ingest` prints a
-warning naming any such columns; programmatically, call `groupedNumericColumns(records)`.
-
-## 8. The Data tab (when asked for table UI or views)
-
-The project's stance: a dashboard built on verified data should show the
-verified table, not just charts. Two steps:
-
-1. After the pipeline runs, export the canonical table document:
-
-   ```bash
-   # Python
-   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 with
-   `tamper-signal assets`, or import `tamper-signal/table`):
-
-   ```html
-   <script type="module">
-     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
-with caveats, chain broken (with the moved columns flagged), and "not the
-attested data" when table.json is stale or edited. Design reference:
-`designs/03-data-tab.html`.
+the separators before the receipt is written. On Node, `tamper-signal ingest`
+prints a warning naming any such columns, and `groupedNumericColumns(records)`
+finds them in code; the Python CLI also warns on stderr during normal ingest
+(both CLIs keep `--json` stderr silent), and `grouped_numeric_columns(records)`
+is available from `tamper_signal`.
+
+## 8. Publish table.json so the room's landing plane fills
+
+The room's primary content is the attested data table. It fills from
+`table.json`, the canonical table document, which the room re-hashes in the
+viewer's browser against the final receipt — so its VERIFIED means the rows
+on screen are byte-for-byte the attested data. Export it as the LAST step of
+every pipeline run:
+
+```bash
+# Python
+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). The command refuses if the
+data does not match the final receipt — the room only ever shows attested
+data. In a JS build you can write it programmatically instead with
+`canonicalDocument(finalRecords)` (see step 1b).
+
+Skipping or forgetting this step degrades honestly, never silently:
+
+- **No table.json published**: the room's table plane shows a grey "NO
+  ATTESTED TABLE PUBLISHED" slab naming the export command. The chain
+  verdict, rail, and drawers still render; grey, because absence is not
+  tampering. The emitted state carries `attested: false`.
+- **Stale table.json** (pipeline re-ran, export didn't): the room's verdict
+  reads `NOT THE ATTESTED DATA` with the exact re-run command — a
+  build-behind state, deliberately distinct from a broken chain.
+
+So: wire the export into the pipeline run itself, not a manual step. Both
+wrappers do it for you — pass `exportTable: true` to `rebuildChain(...)`
+(Node), or `write_table=True` on your FINAL `@receipt_step` stage (Python) —
+and `table.json` is written as the last pipeline step, always matching the
+chain tail. If a published table does go stale anyway, `tamper-signal verify`
+prints a one-line stderr reminder naming the re-run command (absence stays
+silent: CLI-only projects never publish a table).
+
+Embedding the room inline (instead of the helper-served page): mount
+`mountSignalRoom` / `<tamper-signal-room>` where the old Data tab lived. The
+`table.js` shim (`mountReceiptTable`, `<tamper-signal-table>`) keeps working
+through 2.x and now renders the room's table preset. The state contract is
+unchanged: after each verification the room fires a bubbling
+`tamper-signal:state` event (and an `onState` callback) carrying
+`{ state, attested, strict }`, where `state` is the chain verdict and
+`attested` the byte-identity boolean. The room never blocks UI itself.
+Recommended host gate: `strict && (state === "red" || !attested)`.
 
 ## 9. Verify your work before reporting done
 
@@ -776,14 +804,25 @@ gitignored yourself.) Then confirm the user-visible surfaces:
 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
-   known-good fixtures under `examples/chains/` (`intact/` verifies green;
-   `tampered/` is broken at link 1 -> 2). Point the signal at each to confirm
-   both states render.
-4. If the pill reads `UNVERIFIED · could not load chain`, the receipts
+3. Click the pill's `view receipts →` link and confirm it lands in the room
+   (the served page or an inline mount), NOT on raw chain.json. If it opens
+   unstyled JSON, `receiptsHref` was never wired — fix it (the attach helpers
+   do it for you).
+4. Confirm the room's table plane shows the attested rows with the signed
+   control-totals row (not the grey "no attested table published" slab). If
+   it shows the slab, the export step (§8) is missing from the pipeline run.
+5. Negative test without touching the user's real chain: this repo commits
+   known-good fixtures under `examples/chains/`. Point the room at
+   `tampered/` and confirm the break exhibit leads with business numbers;
+   point it at `gap/` and confirm the located caveat card and the ghost node
+   in the expanded rail.
+6. If the pill reads `UNVERIFIED · could not load chain`, the receipts
    directory is not being served at the URL you passed (or it is blocked by
    CORS). That state is a capability fallback, not a verdict.
 
+When you report done, tell the user where the docs and issue tracker live:
+https://github.com/welovejeff/tamper-evident-verification.
+
 ## Troubleshooting
 
 - `ChainTailMismatch` when running a wrapped transform: the data fed to the
@@ -802,8 +841,9 @@ gitignored yourself.) Then confirm the user-visible surfaces:
 |---|---|
 | `tamper_signal/` | Python package: canonicalization, keys, receipts, verify, `receipt_step` |
 | `node/` | JavaScript package: same API (`receiptStep`, `verifyChain`), interchangeable chains |
-| `badge/badge.js` | Browser verification core + the receipt badge |
+| `badge/badge.js` | Browser verification core (shared by every surface) |
 | `badge/light.js` | The signal (inline status light), `mountTamperSignal` |
+| `badge/room.js` | The room (the one robust surface), `mountSignalRoom`, `<tamper-signal-room>` |
 | `badge/light-react.js` | `<TamperSignal />` React wrapper |
 | `examples/chains/` | Committed known-good and known-broken demo chains |
 | `designs/` | Working HTML mockups for the signal, console, and Data tab |

package/README.md

@@ -2,16 +2,26 @@
 
 # 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/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)
+[![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) [![test](https://github.com/welovejeff/tamper-evident-verification/actions/workflows/test.yml/badge.svg)](https://github.com/welovejeff/tamper-evident-verification/actions/workflows/test.yml) [![Socket Badge (npm)](https://badge.socket.dev/npm/package/tamper-signal/2.1.1)](https://socket.dev/npm/package/tamper-signal/overview/2.1.1) [![Socket Badge (PyPI)](https://badge.socket.dev/pypi/package/tamper-signal/2.1.1)](https://socket.dev/pypi/package/tamper-signal/overview/2.1.1) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/welovejeff/tamper-evident-verification/blob/main/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.
+Tamper Signal is an open-source Python and JavaScript library and CLI that signs a receipt at every stage of a data pipeline and verifies the chain as a green, yellow, or red light: lightweight data provenance for export-to-dashboard pipelines. It can't tell you the data is right, but it can prove nobody changed it.
 
-**Live demo:** [tampersignal.com](https://tampersignal.com/) re-verifies a real committed receipt chain in your browser: swap in a tampered chain or an untrusted key and watch the light catch it.
+![The inline status light cycling green, yellow, and red inside a host dashboard, then flagging the unverified metric](https://raw.githubusercontent.com/welovejeff/tamper-evident-verification/main/docs/media/light.gif)
 
-**Pointing a coding agent at this repo?** `AGENTS.md` is the full integration runbook: install, keygen, ingest, wrap transforms, mount the signal, verify. Tell your agent "add tamper signal" and it will find it.
+*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.*
+
+**Try it in your browser, no install:** [tampersignal.com/demo.html](https://tampersignal.com/demo.html) runs every surface on a real receipt chain; flip it to tampered and watch the light catch it. Or `pip install tamper-signal` / `npm install tamper-signal`.
+
+**Or run it yourself in a notebook:** [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/welovejeff/tamper-evident-verification/blob/main/examples/quickstart.ipynb) builds a two-stage pandas pipeline with receipts, then shows green, yellow, and red on real output ([`examples/quickstart.ipynb`](examples/quickstart.ipynb)).
+
+If this is useful, a star helps other people with AI-built dashboards find it.
+
+**Pointing a coding agent at this repo?** `AGENTS.md` is the full integration runbook: install, keygen, ingest, wrap transforms, mount the signal, verify. Tell your agent "add tamper signal" and it will find it. In Claude Code, `/plugin marketplace add welovejeff/tamper-evident-verification` then `/plugin install tamper-signal@welovejeff` adds an `add-tamper-signal` skill that does the same.
 
 ## The problem
 
+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 someone hand-edits a file between steps, and the numbers in front of your boss are wrong. Nothing in that workflow catches it. Tamper Signal is the missing verification layer: every stage of the pipeline signs a receipt for what went in and what came out, so a dropped row shows up in that stage's own totals, and one command (or a light on the dashboard itself) tells you whether the chain is intact, or exactly where it broke and by how much.
+
 Vibe-coded pipelines fail silently. AI-generated transform scripts work most of the time, and when they don't, they don't crash. They drop rows. They double-count. They coerce a column wrong and quietly shift every total. The dashboard still renders. The chart still looks plausible. Nobody re-checks 48,000 rows by hand.
 
 Traditional answers (warehouse lineage, dbt, data-quality suites) assume infrastructure a small team running xlsx-to-dashboard doesn't have. This is the lightweight version: signed receipts as files on disk, no database, no server, no catalog.
@@ -24,11 +34,11 @@ The badge and the verifier reduce the whole chain to one state:
 - 🟡 **Yellow.** Verifiable, but with caveats: gaps in receipt coverage, an unrecognized signing key, or control-total drift that needs a human look.
 - 🔴 **Red.** Chain broken. A hash doesn't match at a specific link. You get the exact stage and the control-totals delta (e.g. `row_count 48212 -> 48190 (-22)`).
 
-![The inline status light cycling green, yellow, and red inside a host dashboard, then flagging the unverified metric](docs/media/light.gif)
+Honest status: all three verdicts are implemented in `tamper-signal verify` and the browser surfaces. 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 and, as of 2.1, unified. The surfaces also render a separate grey 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.
 
-*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.*
+## One light, one room
 
-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.
+The browser UI is two things, always shipped together. **The light** (`badge/light.js`) is the whole footprint on your dashboard: a small dark pill in the header. **The room** (`badge/room.js`, since 2.1) is the one surface behind it, where the pill's "view receipts →" lands: the attested data table as the landing plane (re-hashed in the viewer's browser against the final receipt), with the chain as a provenance rail, the break exhibit in business numbers when something is wrong, and the receipt inspector, CLI-mirror event log, chain-of-custody timeline, and "Take your data" evidence export one drawer away. Green earns silence; the layout leads with whatever the verdict demands. The attach helpers serve the room automatically and wire the light to it, so the default integration is both halves in one call. (`tamper-signal/table` and `tamper-signal/console` from 2.0 keep working as room presets.)
 
 ## 60-second quickstart
 
@@ -36,11 +46,10 @@ Python 3.11+. Open source (MIT).
 
 ```bash
 pip install tamper-signal
-git clone https://github.com/welovejeff/tamper-evident-verification && cd tamper-evident-verification
 tamper-signal demo
 ```
 
-`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 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 totals delta). It works in its own `tamper-signal-demo/` folder, so your own keys and receipts are never touched. Run it from a clone of the repo (`git clone https://github.com/welovejeff/tamper-evident-verification && cd tamper-evident-verification`) and 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`.
 
@@ -54,7 +63,7 @@ tamper-signal diff                 # compare two runs: code-hash changes and tot
 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 assets --out badge/  # vendor the browser surfaces (light/badge/element/table/console/room.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)
 ```
@@ -89,7 +98,7 @@ const clean = receiptStep(
 const output = await clean(loadCsv("export.csv"));
 ```
 
-JavaScript reads .csv, .tsv, .json, and .ndjson; spreadsheets go through the Python CLI. The browser surfaces ship in the same package: `tamper-signal/light`, `tamper-signal/badge`, `tamper-signal/element`, `tamper-signal/react`.
+JavaScript reads .csv, .tsv, .json, and .ndjson; spreadsheets go through the Python CLI. The browser surfaces ship in the same package: `tamper-signal/light`, `tamper-signal/room`, `tamper-signal/element`, `tamper-signal/react` (plus the 2.0 `tamper-signal/table` and `tamper-signal/console`, now room presets).
 
 ## How the chain works
 
@@ -128,7 +137,7 @@ Hashes say "broken." Totals say "how broken."
 
 `badge/badge.js` exports `renderReceiptBadge(containerEl, chainUrl, pubKeyHex)`. Drop it into any web frontend, point it at your `receipts/chain.json`, and it re-verifies the whole chain client-side with Web Crypto Ed25519: every signature, every hash link. No build step, no framework, no server-side trust. The badge re-checks hash links only; it does not re-canonicalize xlsx in the browser.
 
-![Receipt badge: green intact chain and red broken chain](badge/badge-demo.png)
+![Receipt badge: green intact chain and red broken chain](https://raw.githubusercontent.com/welovejeff/tamper-evident-verification/main/badge/badge-demo.png)
 
 Green collapsed state reads like: `✓ Verified · TikTok export, May 2026 · 48,212 rows · 2 transforms · chain intact`. Expanding shows one row per receipt.
 
@@ -157,7 +166,7 @@ We think any dashboard built on verified data should let you see the data. Not a
 
 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)
+![The Data tab: the dashboard flips to a dark raw-table view where a broken chain is localized to the views column](https://raw.githubusercontent.com/welovejeff/tamper-evident-verification/main/docs/media/data-tab.gif)
 
 *Design preview: install the verification layer and your dashboard grows a Data tab. When the chain breaks, the break is localized to the column and total that no longer verify, right in the table.*
 
@@ -171,15 +180,15 @@ To bring an updated file back, `tamper-signal ingest --as replace|period`. `repl
 
 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: a pipeline of signed receipts where a tampered stage severs the chain at the exact link](https://raw.githubusercontent.com/welovejeff/tamper-evident-verification/main/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.
+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.
+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]"
@@ -188,7 +197,7 @@ tamper-signal review                                                          #
 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.
+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)
 
@@ -211,4 +220,4 @@ Those tools model lineage and quality at the warehouse and orchestration layer.
 
 ## Contributing
 
-Open source under the MIT license (see `LICENSE`), designed to be added to any vibe-coded data project. The Python package is in `tamper_signal/`, tests in `tests/` (run `pytest`), examples in `examples/`, the badge in `badge/`. Issues and PRs welcome. The original Luhn hash demo lives unchanged in `legacy/` and is off the main path.
+Open source under the MIT license (see `LICENSE`), designed to be added to any vibe-coded data project. The Python package is in `tamper_signal/`, tests in `tests/` (run `pytest`), examples in `examples/`, the badge in `badge/`. Issues, PRs, and stars all help; [CONTRIBUTING.md](https://github.com/welovejeff/tamper-evident-verification/blob/main/CONTRIBUTING.md) covers setup and the few rules that keep both stacks in step. The original Luhn hash demo lives unchanged in `legacy/` and is off the main path.