agents-handoff 2.0.2 → 2.0.3

package/docs/LEVEL4.md

@@ -5,7 +5,7 @@ title: Level 4 — the dynamic runtime layer
 # Level 4 — the dynamic runtime layer
 
 The engine ([handoff.mjs](https://github.com/Alot1z/agent-handoff/blob/main/tools/handoff.mjs)) is passive: something has to invoke it. The
-runtime layer is [tools/agent-handoff.mjs](https://github.com/Alot1z/agent-handoff/blob/main/tools/agent-handoff.mjs), which acts on the
+runtime layer is [tools/agents-handoff.mjs](https://github.com/Alot1z/agent-handoff/blob/main/tools/agents-handoff.mjs), which acts on the
 state of the store — it probes for staleness, checks a handoff against a contract, composes
 sessions, imports other stores and maintains the index.
 
@@ -13,7 +13,7 @@ Every mutating command takes a lock, so two runs cannot capture or merge the sam
 once. Locks live in `<root>/.locks/` and are named after a hash of the operation target.
 
 ```bash
-node tools/agent-handoff.mjs <command> [args]
+node tools/agents-handoff.mjs <command> [args]
 ```
 
 | Command | Purpose |
@@ -32,7 +32,7 @@ An unknown command prints that list and exits 2.
 ## `auto` — self-triggering capture
 
 ```bash
-node tools/agent-handoff.mjs auto --source transcript.jsonl \
+node tools/agents-handoff.mjs auto --source transcript.jsonl \
   [--session <id>] [--harness <name>] [--project <name>] [--min-fresh-ms <n>]
 ```
 
@@ -49,7 +49,7 @@ file exits 2.
 ## `verify-gate` — the evidence gate
 
 ```bash
-node tools/agent-handoff.mjs verify-gate <id-prefix>
+node tools/agents-handoff.mjs verify-gate <id-prefix>
 ```
 
 | Check | Passes when |
@@ -71,7 +71,7 @@ manifest is visible as a nonzero status.
 ## `promote` — stamping verified work
 
 ```bash
-node tools/agent-handoff.mjs promote <id-prefix>
+node tools/agents-handoff.mjs promote <id-prefix>
 ```
 
 The manifest is backed up to `manifest.json.bak`, the gate above is run and its verdict is
@@ -88,7 +88,7 @@ Two honest caveats:
 ## `merge` — composing two sessions
 
 ```bash
-node tools/agent-handoff.mjs merge <id-prefix-a> <id-prefix-b>
+node tools/agents-handoff.mjs merge <id-prefix-a> <id-prefix-b>
 ```
 
 Timelines are concatenated and sorted by `ts`, and written to a new session directory named
@@ -103,7 +103,7 @@ on `contract` and `payload` until a brief is written for it, and `index` reports
 ## `federated-merge` — importing another store root
 
 ```bash
-node tools/agent-handoff.mjs federated-merge --from <remote-root> [--from <root> ...] [--dry-run]
+node tools/agents-handoff.mjs federated-merge --from <remote-root> [--from <root> ...] [--dry-run]
 ```
 
 Each remote root is expected to have the same `projects/<project>/<session>/` layout. A
@@ -121,7 +121,7 @@ recorded as failed, and a missing `--from` exits 2.
 ## `self-improve` — brief shortfalls
 
 ```bash
-node tools/agent-handoff.mjs self-improve
+node tools/agents-handoff.mjs self-improve
 ```
 
 Every session is scanned, and a session with 40 or more USER+AGENT turns whose `HANDOFF.md`
@@ -132,7 +132,7 @@ so a configured store never collects rule candidates. The file lists counts, not
 ## `index` — the store index
 
 ```bash
-node tools/agent-handoff.mjs index
+node tools/agents-handoff.mjs index
 ```
 
 Rebuilds `<root>/INDEX.json` from the manifests, with one entry per session (`id`, `uuid`,
@@ -178,7 +178,7 @@ is rewritten with a sha256 seal, and the step is appended to `<state>/jobs/<sess
 Each step is permission-gated at `R1`. `--fail-at <k>` simulates an abrupt kill before step
 `k` executes, leaving the durable state at `k-1`.
 
-The state directory is `<repo>/.agent-handoff`, or `AGENT_HANDOFF_STATE_DIR` when set.
+The state directory is `<repo>/.agents-handoff`, or `AGENT_HANDOFF_STATE_DIR` when set.
 
 | Code | Meaning |
 |---|---|

package/docs/LEVEL5.md

@@ -9,7 +9,7 @@ lets a handoff whose own record is complete hand its continuation to a worker th
 broker, instead of waiting for a reader.
 
 ```bash
-node tools/agent-handoff.mjs dispatch <id-prefix> --task "<objective>" \
+node tools/agents-handoff.mjs dispatch <id-prefix> --task "<objective>" \
   [--role <role>] [--parent <parentTaskId>] [--broker <broker-root>] [--live]
 ```
 

package/docs/PERMISSIONS.md

@@ -22,7 +22,7 @@ Every operation is evaluated first and executed only on an `ALLOWED` verdict. A
 
 | Key | Shipped value |
 |---|---|
-| `approved_workspaces` | `.` (the skill root), `repo-upstream`, `.agent-handoff`, `.context` |
+| `approved_workspaces` | `.` (the skill root), `repo-upstream`, `.agents-handoff`, `.context` |
 | `system_read_only_roots` | `C:\Windows`, `C:\Program Files`, `C:\Program Files (x86)` |
 | `personal_data_roots` | `C:\Users` |
 | `denied_roots` | empty |
@@ -103,7 +103,7 @@ are allowed only inside an approved workspace.
 
 Every decision, allowed or denied, is written to
 `<state dir>/executions/<timestamp>-<pid>-<random>.json`. The state directory is
-`AGENT_HANDOFF_STATE_DIR` when set, and `<skill>/.agent-handoff` otherwise; it is treated as
+`AGENT_HANDOFF_STATE_DIR` when set, and `<skill>/.agents-handoff` otherwise; it is treated as
 an approved workspace wherever it points.
 
 ## Declared but not enforced

package/docs/PROVENANCE.md

@@ -60,6 +60,33 @@ It prints one `PASS` line, or `FAIL` with the reason.
 
 Treat the chain as damage detection, not as authentication.
 
+## Install provenance
+
+An installation carries its own record, `.agents-handoff-install.json`, written by the
+installer into the copy it made. It is separate from every handoff folder: it says what was
+installed and where the bytes came from, not what a session contains. `verify` run from the
+installer re-hashes the installed file set and compares it with the record.
+
+| Field group | What it records |
+|---|---|
+| `product`, `version`, `installer_version`, `installed_at` | Which version landed, and which installer wrote the record. |
+| `harness`, `target` | Where the copy went (`claude`, `codex`, `agents`, or `null` for a direct path). |
+| `source` | The tree beside the installer (`kind: 'tree'`), or the tagged archive it was fetched from (`kind: 'archive'`) with that archive's sha256. |
+| `file_count`, `files_sha256`, `files` | That the files present are the files that were installed — one hash over the set, and one per path. |
+
+What it detects: a file edited, replaced or removed after the install, because the per-file
+values and the set hash no longer match. `verify` exits non-zero and names the differing
+files, and `doctor` reports the same state for every harness installation it finds.
+
+What it cannot detect:
+
+- **A compromised source.** The record is written from whatever tree the installer ran in, so a
+  copy made from a tampered tree carries a record that matches that tree.
+- **Files outside the manifest.** The hash covers the manifest files, not anything added beside
+  them.
+- **A rewritten record.** Anyone who edits an installed copy can recompute the hashes, exactly
+  as a manifest can be re-hashed. There is no signature and no external trust anchor.
+
 ## Update instead of recreate
 
 Re-running `build` on the same session id merges rather than duplicates: turns with a sequence above

package/docs/SECURITY.md

@@ -6,7 +6,7 @@ title: Security
 
 ## Scope
 
-agent-handoff reads session transcripts you point it at and writes a handoff folder to disk. It has
+agents-handoff reads session transcripts you point it at and writes a handoff folder to disk. It has
 no network code, no third-party dependencies, and no privileged operations. This document states
 what the tool does with data, what it refuses to do, and which guarantees it does not make.
 

package/docs/SESSIONS.md

@@ -59,6 +59,37 @@ node .github/scripts/build-sessions-index.mjs --check    # exit 1 when the page
 `--check` is wired into CI, so a store that changes without the page changing fails the build
 instead of publishing a table that no longer matches what the engine can read.
 
+The store is also published as JSON, for anything that would rather read data than
+markdown: [`sessions.json`](sessions.json) (`1.0-session-feed`) — the same rows, with an
+`integrity` verdict per session. The filter below runs in the browser against the table you
+are looking at; nothing is fetched.
+
+<p class="session-filter">
+  <label for="session-filter">Filter sessions</label>
+  <input id="session-filter" type="search" placeholder="project, session, harness, integrity…" size="34" />
+  <span id="session-filter-count" class="session-filter-count"></span>
+</p>
+
+<script>
+(function () {
+  var input = document.getElementById('session-filter');
+  if (!input) return;
+  var rows = Array.prototype.slice.call(document.querySelectorAll('table tbody tr'));
+  var count = document.getElementById('session-filter-count');
+  function apply() {
+    var q = input.value.trim().toLowerCase(), shown = 0;
+    rows.forEach(function (tr) {
+      var hit = !q || tr.textContent.toLowerCase().indexOf(q) > -1;
+      tr.style.display = hit ? '' : 'none';
+      if (hit) shown += 1;
+    });
+    if (count) count.textContent = shown + ' of ' + rows.length + ' shown';
+  }
+  input.addEventListener('input', apply);
+  apply();
+})();
+</script>
+
 ## Next
 
 - The file-by-file contract for a session folder is in [FORMAT.md](FORMAT.md).

package/docs/UNINSTALL.md

@@ -15,10 +15,10 @@ npx agents-handoff --remove
 Removal asks for confirmation first:
 
 ```
-This will remove agent-handoff from:
+This will remove agents-handoff from:
   <install-path>
 
-Your handoffs (projects/, handoffs/, links/) will NOT be deleted.
+Your handoffs and anything else you put in this directory will NOT be deleted.
 Configuration (handoff.config.json) will NOT be deleted.
 
 Continue? (y/N)
@@ -36,36 +36,56 @@ npx agents-handoff --remove --force
 | Option | Effect |
 |---|---|
 | `--remove` | Remove the installation (interactive confirmation). |
-| `--force`, `-f` | Skip the confirmation, and delete the kept directories when they are empty. |
+| `--force`, `-f` | Skip the confirmation. |
 | `--location <global\|local\|project>` | Which installation to remove. Global is the default and is resolved the same way as for install. |
 | `--path <dir>` | Remove the installation at exactly this directory. |
+| `--claude`, `--codex`, `--agents` | Remove that harness's installation. Repeatable, and combinable. |
+| `--harness <a,b>` | Named harness(es), comma separated. Repeatable. |
+| `--all` | Every harness whose configuration directory exists on this machine. |
+| `--skills-dir <dir>` | Remove the installation under exactly this directory. Repeatable. |
+| `--project` | With a harness flag: the per-repository installation. |
+
+Removing several harnesses at once is the same one run as installing them, and each target is
+reported on its own:
+
+```bash
+npx agents-handoff --remove --claude --force
+npx agents-handoff --remove --all --force
+```
 
 Flag form and bare verb are equivalent: `--remove` and `remove`, `--force` and `-f`.
 
 ## What is removed
 
-Everything in the installation directory, except the entries listed in the next section:
+**Only what the installation owns — the manifest.** The rule is a removal set, not a keep
+list, so a directory nobody thought to name is kept rather than deleted:
 
 - the engine and runtime: `tools/`, `tools/lib/`
-- metadata: `SKILL.md`, `skill.json`, `package.json`, the manifest JSON files
+- metadata: `SKILL.md`, `README.md`, `LICENSE`, `skill.json`, the manifest JSON files
+- the install record: `.agents-handoff-install.json`
 - `schemas/`, `refs/`, `templates/`, `docs/`, `tests/`
-- `INDEX.json` and any other generated file in that directory
+- the `package.json` stub the installer wrote, and only that stub — a `package.json` you have
+  edited is kept
 
 Each removed entry is printed as `Removed file: <name>` or `Removed directory: <name>/`.
 
 ## What is kept
 
-| Kept | Why |
-|---|---|
-| `handoffs/`, `projects/`, `links/` | Your session data. |
-| `handoff.config.json` | Your configuration. |
-| `.env.example` | Your environment template. |
-| Anything you added elsewhere in the directory | The installer only removes entries it walks past; it never deletes a directory it keeps. |
+Everything else in the directory — the installer prints the list at the end:
 
-With `--force`, the three data directories are still kept unless they are empty, in which case
-they are removed and reported as `Removed empty directory: <name>/`. After that, if the
-installation directory itself is empty it is removed too. If handoffs remain in it, the
-directory stays.
+```
+Kept — not the installer's to delete:
+  .agent-handoff/
+  handoff-session.md
+  handoff.config.json
+  handoffs/
+  projects/
+```
+
+That includes a store under any name (`.agent-handoff/`, `projects/`, `handoffs/`, or one of
+your own), `links/`, notes, your `handoff.config.json`, and anything else you added. Nothing is
+deleted for being empty, and nothing outside those paths is touched; if data remains, the
+installation directory remains with it.
 
 ## Manual uninstall
 
@@ -74,13 +94,18 @@ Remove the skill files and leave the data behind:
 ```bash
 cd "<install-path>"
 
-# Keep these: handoffs/ projects/ links/ handoff.config.json .env.example
-rm -rf tools docs refs templates schemas src tests
-rm -f SKILL.md skill.json package.json INDEX.json \
+# Exactly the manifest this same release installs. Your store, notes and
+# handoff.config.json are not listed, so they stay.
+rm -rf tools docs refs templates schemas tests
+rm -f SKILL.md README.md LICENSE skill.json \
       capability-registry.json permission-policy.json \
-      handoff.config.schema.json handoff.config.example.json
+      handoff.config.schema.json handoff.config.example.json \
+      .agents-handoff-install.json
 ```
 
+A `package.json` the installer wrote (`"private": true`, `"name": "agents-handoff"`) can go
+too; one you edited is yours to keep. `--remove` makes that distinction itself.
+
 If you never store handoffs inside the installation — for example when `HANDOFFS_ROOT` points
 somewhere else — and you do not need anything else in it, the whole directory can go:
 
@@ -113,7 +138,8 @@ and can be read by a later installation, or by any tool that reads a handoff fol
 | Nothing was removed | The confirmation was skipped. Pass `--force`. |
 | `EPERM` or `EBUSY` on Windows | A process is holding the files. Close it and retry, or check file attributes. |
 | Permission denied | The installation is outside your user directory. Remove it with the privileges that created it, or use `--force` from a shell that can write there. |
-| Handoff data disappeared | It was an empty kept directory removed by `--force`, or `HANDOFFS_ROOT` points elsewhere. Check the root printed by `handoff.mjs config`. |
+| The directory is still there after `--remove` | It is not empty: the entries printed under `Kept — not the installer's to delete:` are still inside. Remove them yourself if you no longer want them. |
+| Handoff data seems to be missing | `HANDOFFS_ROOT` points elsewhere. Check the root printed by `handoff.mjs config`; `--remove` never deletes a store inside the install directory. |
 
 ## See also
 

package/docs/UPGRADE.md

@@ -35,43 +35,71 @@ leaves that file alone.
 npx agents-handoff --update
 ```
 
-`--update` requires an existing installation; without one it exits with
-`Not installed at <dir>. Run 'install' first.`
+With no target flag, `--update` updates **every installation found on this machine**. That is
+the whole answer to "keep my install current": a machine can hold the same skill in
+`~/.claude/skills` and in `~/.agents/skills`, and updating only one of them is how the other
+keeps running an old engine. Each installation is updated and reported on its own, and the run
+ends with a summary naming the version it moved from and to:
+
+```
+Update summary
+  ✓ updated <dir>/agents-handoff — 2.0.2 → v2.0.3
+  ✓ updated <dir>/agents-handoff — 2.0.2 → v2.0.3
+✓ 2 of 2 installation(s) updated
+```
+
+When nothing is installed anywhere the installer can see, it says so and exits non-zero:
+`Nothing to update: no agents-handoff installation found.`
 
 The update then reinstalls: the skill files are copied over the existing installation and
 overwrite the files of the same name. Files that are not part of the installation manifest —
-`handoffs/`, `projects/`, `links/`, `handoff.config.json`, `.env.example`, and anything you added
-— are left in place.
+`handoffs/`, `projects/`, `links/`, `.agent-handoff/`, `handoff.config.json`, `.env.example`, and
+anything you added — are left in place. Nothing outside the manifest is read or rewritten.
 
-To update into a specific location or version:
+Scope the update to one harness, or several, with the same flags install uses:
 
 ```bash
+npx agents-handoff --update --claude     # just Claude Code
+npx agents-handoff --update --codex      # just Codex CLI
+npx agents-handoff --update --all        # every harness found on this machine
 npx agents-handoff --update --location project
 npx agents-handoff --update --version 2.0.0
 ```
 
-`--version` installs the version you ask for: the tree beside the installer when there is one
-(a checkout, a release archive), or the archive of that version's tag when there is not (the
-published package carries the installer alone). Confirm what is actually installed with
-`--verify`, which prints the version read back from the installed `SKILL.md`, rather than
-trusting the request.
+`--all` covers the harnesses whose configuration directory exists here; a named harness is
+updated whether or not that directory exists.
+
+`--version` asks for a version, and the installer resolves it honestly: the tree beside the
+installer is used when it **is** that version (or when nothing was requested), and when it is a
+different version the requested tag's archive is fetched instead, with its sha256 recorded in
+the install record's `source`. To switch versions, ask npm for the one you want
+(`npx agents-handoff@<version>`), pass `--version <x>`, or install manually from that version's
+tag archive. Confirm what is actually installed with `--verify`, which prints the version read
+back from the installed `SKILL.md`, rather than trusting the request.
+
+An update rewrites the install record as well, so `--verify --provenance` describes the new
+state afterwards and reports the archive (with its sha256) when the files came from a download
+rather than from a tree. The record's `package` block names the npm package and version the
+installation should match; `npx agents-handoff --verify-package --record` fills in that
+package's tarball hashes.
 
 ## Manual upgrade
 
 Replace the skill files and keep the data:
 
-1. Extract the release archive (`agent-handoff-latest.zip`, or
-   `agent-handoff-v<version>.zip`) to a temporary directory.
+1. Extract the release archive (`agents-handoff-v<version>.zip` from the
+   [releases page](https://github.com/Alot1z/agent-handoff/releases); the newest release carries
+   its own version in the file name) into a temporary directory.
 2. Copy the skill files over the installation: `SKILL.md`, `skill.json`, the manifest JSON
    files, `tools/`, `tools/lib/`, `schemas/`, `refs/`, `templates/`, `docs/`, `tests/`.
 3. Do not delete `handoffs/`, `projects/`, `links/`, or `handoff.config.json`.
 
 ```bash
-unzip agent-handoff-latest.zip -d /tmp/agent-handoff-new
-cp -r /tmp/agent-handoff-new/tools/ /tmp/agent-handoff-new/refs/ \
-      /tmp/agent-handoff-new/templates/ /tmp/agent-handoff-new/schemas/ \
-      /tmp/agent-handoff-new/docs/ "<install-path>/"
-cp /tmp/agent-handoff-new/SKILL.md /tmp/agent-handoff-new/skill.json "<install-path>/"
+unzip agents-handoff-v<version>.zip -d /tmp/agents-handoff-new
+cp -r /tmp/agents-handoff-new/tools/ /tmp/agents-handoff-new/refs/ \
+      /tmp/agents-handoff-new/templates/ /tmp/agents-handoff-new/schemas/ \
+      /tmp/agents-handoff-new/docs/ "<install-path>/"
+cp /tmp/agents-handoff-new/SKILL.md /tmp/agents-handoff-new/skill.json "<install-path>/"
 ```
 
 ## What an upgrade changes
@@ -82,6 +110,8 @@ cp /tmp/agent-handoff-new/SKILL.md /tmp/agent-handoff-new/skill.json "<install-p
 | `refs/`, `templates/`, `schemas/`, `docs/` | `projects/`, `links/` |
 | `SKILL.md`, `skill.json`, manifest JSON files | `handoff.config.json` and your edits |
 | `install/` — the installer itself | `HANDOFFS_ROOT`, if you use it |
+| `.agents-handoff-install.json` — the install record, rewritten for the new version, including its `package` block | — |
+| `.agent-handoff/` and any other store directory, whatever it is called | — |
 
 Handoff folders are read from the handoff root in place, so an upgrade does not move or rewrite
 them.
@@ -89,13 +119,18 @@ them.
 ## After upgrading
 
 ```bash
-npx agents-handoff --verify
+npx agents-handoff --verify                  # every installation found
+npx agents-handoff --verify --provenance
+npx agents-handoff --verify-package --record  # and prove it matches the published tarball
+npx agents-handoff doctor
 node "<install-path>/tools/handoff.mjs" config
 node "<install-path>/tools/handoff.mjs" list
 ```
 
 `config` proves the engine starts and prints the handoff root it resolved. `list` proves the
-engine still finds the handoff folders that were already there.
+engine still finds the handoff folders that were already there. `--verify --provenance` prints
+the install record the verification was checked against — version, source, harness and the
+file-set hash — which is the shortest way to prove an upgrade landed and left nothing behind.
 
 The shipped test suite is a stronger check and does not touch existing handoffs when you point
 it at a scratch root:
@@ -126,10 +161,13 @@ upgrade damaged the folder.
 
 | Symptom | Cause and fix |
 |---|---|
-| `Not installed at <dir>` | Nothing to update at that location. Check `--list`, or drop `--location`/`--path`. |
-| Reported version did not change | The installer installs the tree beside it when there is one, so running it from a checkout installs that checkout. Use the published package, or pass `--version <x>` to fetch a tagged archive. |
+| `Not installed at <dir>` | `--path`, `--location` or a harness flag named a directory that holds no installation. Drop the flag to update every installation found, or check `--list`. |
+| `Nothing to update: no agents-handoff installation found.` | Nothing to update anywhere the installer looks. Run `npx agents-handoff --all`, or name the directory with `--path`. |
+| Reported version did not change | The installer uses the tree beside it when that tree **is** the requested version (or nothing was requested), so running it from a checkout installs that checkout. Use the published package, pass `--version <x>` to fetch that tag's archive, or check `--verify --provenance` to see which source the record names. |
+| `verify-package` fails with `does NOT match … as published` | A file changed after the update. The check names it; reinstall with `--force`. |
 | Verification fails after an upgrade | A file is missing or the engine cannot start. Reinstall with `--force` and read the failing check. |
 | Handoffs no longer listed | The engine is reading a different root. Run `config` and compare it with where your handoffs live; set `HANDOFFS_ROOT` if needed. |
+| `no provenance record` after upgrading | The record is written by installs from 2.0.3 on. Reinstall with `--force` to write one for this target. |
 | Configuration was overwritten | `handoff.config.json` is preserved, but a manual copy step can still overwrite it. Restore your backup. |
 
 ## See also

package/docs/_config.yml

@@ -1,6 +1,8 @@
-title: agent-handoff
+title: agents-handoff
 description: Cross-harness capture and verified continuation for AI working sessions.
 url: https://alot1z.github.io
+# The site is served from the repository's Pages path, which follows the REPOSITORY name
+# (agent-handoff), not the product name (agents-handoff).
 baseurl: /agent-handoff
 plugins:
   - jekyll-relative-links

package/docs/index.md

@@ -1,10 +1,10 @@
 ---
-title: agent-handoff
+title: agents-handoff
 ---
 
-# agent-handoff documentation
+# agents-handoff documentation
 
-agent-handoff turns an AI working session — chat turns, tool calls, reasoning, however the
+agents-handoff turns an AI working session — chat turns, tool calls, reasoning, however the
 client stored it — into a folder of plain files that a different agent, a different harness,
 or a colleague can read and continue from without the original chat. It builds from a
 transcript or an adapter export, keeps a hash chain so a handoff can be re-verified, and
@@ -13,8 +13,8 @@ merges later turns into the same session instead of duplicating it.
 ## Quick start
 
 ```bash
-# 1. Install the skill
-npx agents-handoff
+# 1. Install the skill into every harness found on this machine
+npx agents-handoff --all
 
 # 2. Build a handoff from a transcript
 node tools/handoff.mjs build --source transcript.jsonl --project my-project
@@ -28,11 +28,20 @@ node tools/handoff.mjs verify <id-prefix>
 `build` also accepts `--session`, `--harness`, `--model` and `--objective`. Run
 `node tools/handoff.mjs config` to see which store root the engine resolved and why.
 
+`--all` installs into every harness present on the machine; `--claude`, `--codex`, `--agents`
+and `--skills-dir <dir>` pick one or several instead, and `npx agents-handoff --update` brings
+every copy on the machine up to date in one run. `npx agents-handoff --verify-package` then
+proves the copy on disk is identical to the tarball npm is serving for its version, while
+`npx agents-handoff --doctor` reports what is installed where and whether each copy still
+matches the record written when it was installed. The installer's full surface is in
+[CLI.md](CLI.md) and [INSTALL.md](INSTALL.md).
+
 ## Where to start
 
 | If you want to… | Read |
 |---|---|
 | install it | [INSTALL.md](INSTALL.md) |
+| prove an install matches the published package | [INSTALL.md](INSTALL.md) and [CLI.md](CLI.md) |
 | understand how the pieces fit | [ARCHITECTURE.md](ARCHITECTURE.md) |
 | look up a command, flag or exit code | [CLI.md](CLI.md) |
 | know exactly what a handoff folder holds | [FORMAT.md](FORMAT.md) |
@@ -51,7 +60,7 @@ node tools/handoff.mjs verify <id-prefix>
 | [ARCHITECTURE.md](ARCHITECTURE.md) | The layers, the data flow, the store root, the write-safety discipline, the boundaries |
 | [CLI.md](CLI.md) | Every executable, verb, flag, exit code, environment variable and file written |
 | [FORMAT.md](FORMAT.md) | Handoff folder layout, every file in it, the manifest and the schemas |
-| [SESSIONS.md](SESSIONS.md) | Session index: a sample store, its captured sessions, and how to verify and re-render them |
+| [SESSIONS.md](SESSIONS.md) | Session index: a sample store, its captured sessions, and how to verify and re-render them. The same rows are published as [sessions.json](sessions.json) (schema `1.0-session-feed`) for anything that would rather read data than markdown, and the page filters in the browser |
 | [INTEGRATION.md](INTEGRATION.md) | Embedding the engine, configuration and environment, CI and pipeline use |
 | [LEVEL4.md](LEVEL4.md) | Dynamic runtime layer: runtime verbs, gates and promotion |
 | [LEVEL5.md](LEVEL5.md) | Collaborative dispatch: routing a handoff to another agent |

package/docs/sessions.json

@@ -0,0 +1,34 @@
+{
+  "schema_version": "1.0-session-feed",
+  "generated_by": ".github/scripts/build-sessions-index.mjs",
+  "store": "examples/sessions",
+  "index_source": "INDEX.json",
+  "as_of": "2026-10-08T22:53:03.964Z",
+  "count": 2,
+  "projects": 2,
+  "failed": 0,
+  "sessions": [
+    {
+      "id": "typescript-project-setup",
+      "project": "demo",
+      "harness": "claude-code",
+      "model": "claude-3-5-sonnet",
+      "turns": 11,
+      "revisions": 1,
+      "updated": "2026-10-08T22:53:03.865Z",
+      "manifest_sha256": "141e232eb2ad668f59d746828517e646a5cbe2bc914dd976df3c43c209214d3c",
+      "integrity": "pass"
+    },
+    {
+      "id": "fixture-roundtrip",
+      "project": "smoke-test",
+      "harness": "codex",
+      "model": "gpt-5-codex",
+      "turns": 2,
+      "revisions": 1,
+      "updated": "2026-10-08T22:53:03.964Z",
+      "manifest_sha256": "a81d076e3334b8341f2829d0f38daf2cdbaf667269a9909dc523797c74e46ce5",
+      "integrity": "pass"
+    }
+  ]
+}

package/install/CHANGELOG.md

@@ -42,7 +42,7 @@ machine that has neither a checkout nor an unpacked archive.
 - `install` (default), `update`, `remove`, `verify`, `list` and `where`.
 - Location targets `global`, `local` and `project`, with `--path` for an exact directory.
 - Global root resolution instead of a hard-coded path: an account-skill store that already
-  holds `agent-handoff`, else `~/.agents/skills`, else an account-skill store found on the
+  holds `agents-handoff`, else `~/.agents/skills`, else an account-skill store found on the
   machine, else `~/.agents/skills`, created on install. `where` prints the resolved root and
   the rule that chose it. `AGENT_HANDOFF_GLOBAL_DIR` overrides it.
 - `--version` to install a specific version, and `--force` to skip confirmations.

package/install/README.md

@@ -1,6 +1,6 @@
 # agents-handoff
 
-npx installer for the agent-handoff skill.
+npx installer for the agents-handoff skill.
 
 ## Quick start
 
@@ -56,13 +56,13 @@ npx agents-handoff where
 ## Locations
 
 - **global**: resolved, not hard-coded — an account-skill root that already holds
-  `agent-handoff`, else `~/.agents/skills`, else any account-skill store found on this
-  machine (`<store>/<account-id>/<profile-id>/agent-handoff/`), else `~/.agents/skills`,
+  `agents-handoff`, else `~/.agents/skills`, else any account-skill store found on this
+  machine (`<store>/<account-id>/<profile-id>/agents-handoff/`), else `~/.agents/skills`,
   created on install. See it resolved:
   `npx agents-handoff where`. Override with `AGENT_HANDOFF_GLOBAL_DIR`, or target an
   exact path with `--path`.
-- **local**: `./local/skills/agent-handoff/`
-- **project**: `./skills/agent-handoff/` (only detected if in a git repo)
+- **local**: `./local/skills/agents-handoff/`
+- **project**: `./skills/agents-handoff/` (only detected if in a git repo)
 
 ## Requirements
 
@@ -71,6 +71,6 @@ npx agents-handoff where
 
 ## Development
 
-This installer is part of the agent-handoff skill source code.
+This installer is part of the agents-handoff skill source code.
 
-See the [agent-handoff docs](https://github.com/Alot1z/agent-handoff/tree/main/docs) for more.
+See the [agents-handoff docs](https://github.com/Alot1z/agent-handoff/tree/main/docs) for more.