agents-handoff 2.0.2 → 2.0.4

package/docs/CLI.md

@@ -9,8 +9,9 @@ dependencies; there is no build step and nothing to install to run them from a c
 
 | Executable | Role | Invoked as |
 |---|---|---|
-| [`tools/handoff.mjs`](https://github.com/Alot1z/agent-handoff/blob/main/tools/handoff.mjs) | Capture engine: transcript in, handoff folder out. | `node tools/handoff.mjs <verb>`, or the published `agent-handoff` bin |
-| [`tools/agent-handoff.mjs`](https://github.com/Alot1z/agent-handoff/blob/main/tools/agent-handoff.mjs) | Runtime layer: acts on the state of the store. | `node tools/agent-handoff.mjs <verb>` |
+| [`tools/handoff.mjs`](https://github.com/Alot1z/agent-handoff/blob/main/tools/handoff.mjs) | Capture engine: transcript in, handoff folder out. | `node tools/handoff.mjs <verb>`, or the published `agents-handoff` bin |
+| [`tools/agents-handoff.mjs`](https://github.com/Alot1z/agent-handoff/blob/main/tools/agents-handoff.mjs) | Runtime layer: acts on the state of the store. | `node tools/agents-handoff.mjs <verb>` |
+| [`tools/agent-handoff.mjs`](https://github.com/Alot1z/agent-handoff/blob/main/tools/agent-handoff.mjs) | Compatibility forwarder: the runtime layer's pre-rename path, kept so older notes and hooks keep working. | `node tools/agent-handoff.mjs <verb>` (forwards to `tools/agents-handoff.mjs`) |
 | [`tools/runtime-engine.mjs`](https://github.com/Alot1z/agent-handoff/blob/main/tools/runtime-engine.mjs) | Bounded execution: evaluates an operation against the policy before running it. | `node tools/runtime-engine.mjs <verb>` |
 | [`tools/capability-registry.mjs`](https://github.com/Alot1z/agent-handoff/blob/main/tools/capability-registry.mjs) | Health probes for declared capabilities. | `node tools/capability-registry.mjs <verb>` |
 | [`install/install.mjs`](https://github.com/Alot1z/agent-handoff/blob/main/install/install.mjs) | Installs, updates and removes the skill. | `npx agents-handoff <verb>` |
@@ -60,7 +61,7 @@ source hash writes nothing and prints `handoff: up-to-date`.
 | 3 | The id prefix matched more than one session, or none. |
 | 4 | No match for `show`/`verify`/`rename`/`retitle`; also `build` when no turn could be parsed from the source. |
 
-## `tools/agent-handoff.mjs` — runtime layer
+## `tools/agents-handoff.mjs` — runtime layer
 
 Acts on the state of the store rather than being invoked per file. Every mutating command
 takes a lock in `<root>/.locks/`, so two runs cannot capture or merge the same session at
@@ -77,6 +78,11 @@ once. Behaviour per command is described in [LEVEL4.md](LEVEL4.md).
 | `self-improve` | Scan for brief shortfalls and write a rules candidate file. |
 | `index` | Rebuild `INDEX.json` and report sessions with no `HANDOFF.md`. |
 
+`tools/agent-handoff.mjs` is a forwarder, not a second implementation: it spawns
+`tools/agents-handoff.mjs`, passes every argument through, and exits with the same code. Its
+stdout and stderr are the runtime's own. Use the new path in anything you write today; the
+old one exists only so a command that already names it does not break.
+
 `auto` flags: `--source` (required), `--session`, `--harness`, `--project`, `--min-fresh-ms`.
 `dispatch` flags: `--task` (required), `--role` (default `implementation-agent`), `--parent`
 (default `handoff:<id>`), `--broker <root>`, `--live`.
@@ -147,21 +153,41 @@ Probe kinds: `file-exists`, `dir-writable`, `command` (with `command` and `args`
 | 4 | Unknown capability id, or a usage error. |
 
 State is written to `<state>/capability-state.json`, where `<state>` is
-`AGENT_HANDOFF_STATE_DIR` or `.agent-handoff/`.
+`AGENT_HANDOFF_STATE_DIR` or `.agents-handoff/`.
 
 ## `install/install.mjs` — installer
 
 Published as `agents-handoff`. Location resolution is documented in
 [INSTALL.md](INSTALL.md).
 
-| Verb | Effect |
+A bare verb and its flag form are the same command: `npx agents-handoff update` and
+`npx agents-handoff --update` behave identically.
+
+| Verb | Flag form | Effect |
+|---|---|---|
+| `install` (default), `i` | `--install` | Install the skill into every selected target. |
+| `update`, `u` | `--update` | Update to the latest or a named version. |
+| `remove`, `rm` | `--remove` | Remove the installation, keeping everything that is not the installer's. |
+| `verify`, `v` | `--verify` | Verify each installation against the record written when it was installed. |
+| `verify-package`, `vp` | `--verify-package` | Verify each installation against the tarball npm publishes for its version. |
+| `list`, `ls` | `--list` | List every installed location, with its provenance state. |
+| `where` | — | Show the resolved global root and why it was chosen. |
+| `doctor` | `--doctor` | Report which harnesses exist here, what is installed where, and whether each installation still matches its record. Read-only: it never installs. |
+| `help` | `--help`, `-h` | Print the usage block. |
+
+Harness targets. With no harness flag the installer keeps its historical single target
+(`--location` / `--path`); any of these switches to named targets, and several may be combined
+in one run — each target gets its own copy and its own install record.
+
+| Flag | Target |
 |---|---|
-| `install` (default) | Install the skill. |
-| `update` | Update to the latest or a specified version. |
-| `remove` | Remove the installation. |
-| `verify` | Verify installation integrity. |
-| `list` | List every installed location. |
-| `where` | Show the resolved global root and why it was chosen. |
+| `--claude` | `~/.claude/skills/` — Claude Code personal skills. |
+| `--codex` | `~/.codex/skills/` — Codex CLI personal skills. |
+| `--agents` | `~/.agents/skills/` — the harness-neutral store. |
+| `--harness <a,b>` | Named harnesses, comma separated; repeatable. |
+| `--all` | Every harness whose directory exists on this machine. |
+| `--skills-dir <dir>` | Any other stack, exactly; repeatable. |
+| `--project` | Use the per-repository form of the harness directories (`./.claude/skills`, `./.codex/skills`). |
 
 | Flag | Meaning |
 |---|---|
@@ -169,13 +195,89 @@ Published as `agents-handoff`. Location resolution is documented in
 | `--path <dir>` | Install to an exact directory. |
 | `--version latest\|<v>` | Version to install. Default `latest`. |
 | `--force`, `-f` | Skip confirmations and overwrite. |
+| `--provenance` | With `verify`: print the install record the check was run against. |
+| `--record` | With `verify-package`: store the fetched tarball hashes in the install record. |
+
+### `update` and `verify` with no harness flag
+
+A machine can hold the same skill in several places at once — `~/.claude/skills` for Claude
+Code, `~/.agents/skills` for a neutral store, an account-skill store a desktop client reads.
+With no harness flag, `update` and `verify` act on **every** installation they can find rather
+than on the single target the resolver happens to pick, because updating only the resolved one
+is how a second harness keeps an old engine without anyone noticing.
+
+The search covers the resolved global root, `./local/skills`, `./skills`, `~/.claude/skills`,
+`~/.codex/skills`, `~/.agents/skills`, each harness's per-repository form, and every
+account-skill root discovered under the platform's application-data directories. `update`
+reports one line per installation, with the version before and after; `verify` fails the run
+when any copy fails. Neither touches a store, `handoff.config.json` or any file the install
+manifest does not name.
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | The command ran and everything it checked passed. |
+| 1 | Any failure: a usage error, nothing installed to act on, a verification that did not match, or a `verify-package` mismatch. |
+
+### The install record
+
+Every install writes `.agents-handoff-install.json` into the copy it just made. [FORMAT.md](FORMAT.md)
+lists the fields and [PROVENANCE.md](PROVENANCE.md) states what the record does and does not prove.
+
+| Field | Contents |
+|---|---|
+| `schema_version` | `1.0-install-provenance`. |
+| `product`, `version` | `agents-handoff`, and the version read back out of the installed `SKILL.md`. |
+| `installer_version` | The installer package's own version. |
+| `installed_at` | ISO timestamp of the write. |
+| `harness` | The harness the copy went into, or `null` for the resolved single target. |
+| `target` | Absolute install directory. |
+| `source` | What the copy was made from: `{kind: "tree", path}` for a checkout or release archive, or `{kind: "archive", ref, label, archive_url, archive_sha256}` for a fetched tag archive. |
+| `package` | The npm identity this install should match: `name`, `version`, `registry`, `tarball`, `sha256`, `sha512`, `integrity`, `shasum`, `verified_at`. The hashes are `null` until `verify-package --record` fills them, because a copy made from a tree is not the published tarball. |
+| `file_count`, `manifest_entries` | Files present, and entries in the installer's manifest. |
+| `files_sha256` | One sha256 folded over every manifest path together with that file's own hash. |
+| `files` | Per-path sha256, or `missing` for a path this version does not have. |
+
+### What `verify` compares
+
+For each installation: that every manifest file exists (a path the version never had is
+reported as not part of that version rather than failed), that `SKILL.md` carries a name and a
+version, that the engine actually runs — `tools/handoff.mjs config` must exit 0 with its
+resolved-root marker, which also proves the import graph resolves — and that a recomputed
+`files_sha256` equals the recorded one. An installation made before this record existed is
+reported as having none, never silently passed.
+
+### What `verify-package` checks, and in what order
+
+Each step makes the next one meaningful:
+
+1. **The registry's own hashes.** The tarball is downloaded for the installed version and must
+   match the `integrity` (sha512) and `shasum` (sha1) the registry declares for it; otherwise
+   "the published package" is just whatever the network handed over.
+2. **Per-file identity.** The manifest is compared file by file against the extracted tarball,
+   and every difference is named (`not installed`, `not in the published package`, or
+   `content differs`).
+3. **The recorded hash.** When the install record already holds a package `sha256`, it must
+   match too.
+
+Without `--record` nothing is written; with it, the fetched `sha256`, `sha512`, `integrity`
+and `shasum` are stored in `package`. A version that is not on the registry cannot pass this
+check, and it says so rather than reporting success.
+
+### What `remove` deletes
+
+`remove` deletes what the install manifest owns, plus the record it wrote itself and the
+`private` `package.json` stub it created — and nothing else. Store directories, notes, a
+`handoff.config.json`, and any file a later version treats as user data survive by default,
+and every entry that was left is printed under `Kept — not the installer's to delete:`.
 
 ## Environment variables
 
 | Variable | Read by | Effect |
 |---|---|---|
 | `HANDOFFS_ROOT` | capture engine, runtime layer | Store root. Always wins over every other rule. |
-| `AGENT_HANDOFF_STATE_DIR` | runtime engine, capability registry | State directory for executions, checkpoints, jobs and capability state. Default `<repo>/.agent-handoff`. |
+| `AGENT_HANDOFF_STATE_DIR` | runtime engine, capability registry | State directory for executions, checkpoints, jobs and capability state. Default `<repo>/.agents-handoff`. |
 | `AGENT_HANDOFF_GLOBAL_DIR` | installer | Overrides the resolved global install root. |
 
 ## Files written
@@ -191,6 +293,7 @@ Published as `agents-handoff`. Location resolution is documented in
 | `<state>/jobs/<session>/work.log` | `runtime-engine job` |
 | `<state>/capability-state.json` | `capability-registry check` |
 | `<skill>/docs/self-improve-candidates.json` | `self-improve` |
+| `<install>/.agents-handoff-install.json` | `install`, `update`, `verify-package --record` |
 
 `self-improve` writes inside the skill directory on purpose: the candidate file describes the
 skill's brief rules, so a configured store never collects rule candidates.

package/docs/COMPATIBILITY.md

@@ -37,8 +37,32 @@ dependencies.
 | 18.x | SUPPORTED (minimum) |
 | 20.x | SUPPORTED |
 | 22.x | SUPPORTED |
+| 26.x | VERIFIED (developed and released on it) |
 | < 18 | UNSUPPORTED |
 
+## Other runtimes: Bun, Deno, TypeScript
+
+The tools are plain ESM with `node:` built-ins and no dependencies, so another runtime that
+implements those APIs runs them unchanged. Bun was tested against this release:
+
+```bash
+bun tools/handoff.mjs config
+bun tools/handoff.mjs build --source transcript.jsonl --project my-project
+bun tools/handoff.mjs verify my-project          # PASS, same hashes as Node
+bun tools/agents-handoff.mjs index
+bun test --timeout 30000 tools/handoff.test.mjs  # 34 pass, 0 fail
+```
+
+One caveat, and it is a property of the runner rather than of the tools: the suite spawns child
+Node processes, and Bun's default per-test timeout is 5 seconds, so raising it
+(`--timeout 30000`) is what makes all 34 tests pass — at the default, one test times out.
+
+The published artifact is JavaScript, not TypeScript, and there is no build step to add one.
+What TypeScript would have declared — the shape of a handoff, a manifest and the LLM payload —
+is declared by the versioned JSON Schemas the runtime validates against
+(`schemas/handoff.schema.json`, `templates/HANDOFF.llm.schema.json`,
+`handoff.config.schema.json`), and `docs/CLI.md` is the interface of record for the commands.
+
 ## Input formats the engine parses
 
 | Format | How it is detected | Fields read |

package/docs/CONTRIBUTING.md

@@ -91,7 +91,7 @@ Checklist:
 - Keep the exit codes. They are contracts (see the table above and
   [INTEGRATION.md](INTEGRATION.md)).
 - Never commit session data or credentials: no `handoffs/`, `projects/`, `links/`,
-  `.agent-handoff/`, no `*.key`, `*.pem`, `*.token`, and no transcript copied from a real
+  `.agents-handoff/`, no `*.key`, `*.pem`, `*.token`, and no transcript copied from a real
   session. Test input belongs in `tests/fixtures/`.
 - A behaviour change comes with a test in `tools/handoff.test.mjs` and an update to the
   document that owns the contract: [FORMAT.md](FORMAT.md) for the files and fields,
@@ -108,7 +108,7 @@ Checklist:
 | `docs/` | These documents. |
 | `install/` | `install.mjs`, the `npx` installer, and its own README. |
 | `tools/handoff.mjs` | The handoff engine: build, list, show, verify, rename, retitle, config. |
-| `tools/agent-handoff.mjs` | The runtime verbs layered over the engine. |
+| `tools/agents-handoff.mjs` | The runtime verbs layered over the engine. |
 | `tools/runtime-engine.mjs` | Permission policy, bounded execution, checkpoints and resume. |
 | `tools/capability-registry.mjs` | Probes declared capabilities and reports honest verdicts. |
 | `tools/handoff.test.mjs` | The test suite. |

package/docs/FORMAT.md

@@ -62,6 +62,34 @@ project recorded in its manifest.
 Renders (`HANDOFF.md`, the two JSON payloads) are rewritten on every build; `timeline.jsonl`
 is not.
 
+## Installed-copy artifacts (not part of a session)
+
+Two files belong to an INSTALLATION rather than to a session, and neither is written by the
+capture engine. They sit in the directory the installer copied into, beside `SKILL.md`, and
+nothing above in this document describes them.
+
+| File | Written by | Contents |
+|---|---|---|
+| `package.json` | `install`, `update` | Only when the directory has none. A minimal manifest marked `private`, so the copy can report its own version and cannot be published to npm by accident. |
+| `.agents-handoff-install.json` | `install`, `update` | The install record: what version landed, from which source, and a sha256 over the installed file set. |
+
+The install record:
+
+| Field | Meaning |
+|---|---|
+| `schema_version` | `1.0-install-provenance`. |
+| `product`, `version` | The skill this is a copy of, and the version that landed, read back out of the installed `SKILL.md`. |
+| `installer_version`, `installed_at` | The installer that wrote the record, and when. |
+| `harness`, `target` | The harness the copy went to (`claude`, `codex`, `agents`) when one was named, else `null`, and the absolute target path. |
+| `source` | `{kind: 'tree', path}` for a copy made from a tree beside the installer, or `{kind: 'archive', ref, label, archive_url, archive_sha256}` when the copy was fetched instead. |
+| `file_count`, `files_sha256` | How many manifest files the copy holds, and one sha256 over all of them. |
+| `files` | Per-path sha256 values, so a mismatch names the file that changed. |
+
+`verify` re-hashes the manifest files, recomputes `files_sha256` and fails when one changed or
+went missing. An installation made before this record existed has none: `verify` says so and
+checks everything else, and treats the absence as neither a pass nor a failure.
+[PROVENANCE.md](PROVENANCE.md) states what the record proves and what it cannot.
+
 ## manifest.json
 
 | Field | Meaning |

package/docs/INSTALL.md

@@ -4,7 +4,7 @@ title: Installation
 
 # Installation
 
-agent-handoff turns a working session into a portable handoff folder, and verifies that folder
+agents-handoff turns a working session into a portable handoff folder, and verifies that folder
 later. It is a Node.js command-line skill with no runtime dependencies.
 
 ## Requirements
@@ -13,16 +13,23 @@ later. It is a Node.js command-line skill with no runtime dependencies.
 |---|---|
 | Node.js >= 18.0.0 | The engine uses ES modules and `node:fs`. |
 | `unzip` | Only needed to extract a release archive by hand. |
-| No network at run time | The engine never makes a network call. |
+| `tar` | Only needed when the installer fetches an archive instead of copying the tree beside it. |
+| No network at run time | The engine never makes a network call. `npx` and `--verify-package` do. |
 
 ## Quick start
 
 ```bash
-npx agents-handoff
+npx agents-handoff --all      # every harness found on this machine
 ```
 
-The installer copies the skill files into the resolved global root, then reports how many files
-it copied. Confirm the installation:
+One run covers one harness, several, or a directory of your own; the table in
+[Install into the harness you use](#install-into-the-harness-you-use) has the whole set. The
+installer copies the skill files into the resolved global root (or the harness directories
+named), then reports how many files it copied. The published package carries the whole tree, so
+this needs no download; only a bare copy of `install/` falls back to fetching the archive for
+the requested version.
+
+Confirm the installation:
 
 ```bash
 node "<install-path>/tools/handoff.mjs" config
@@ -37,6 +44,99 @@ handoff: config file=none
 handoff: config schema=<dir>/handoff.config.schema.json
 ```
 
+## Installing from GitHub
+
+Two ways, and both install the same tree:
+
+```bash
+# npm runs the repository's own package straight from GitHub — no registry copy involved
+npx github:Alot1z/agent-handoff --all
+
+# or clone it and run the installer from the checkout
+git clone https://github.com/Alot1z/agent-handoff.git
+cd agent-handoff
+node install/install.mjs --all
+```
+
+The clone is also the way to install a version that is not on npm at all: a branch, a commit or
+a tag. The installer accepts the same flags either way, and a checkout installs the tree in front
+of it.
+
+## Install into the harness you use
+
+With no harness flag the installer uses the resolved global root (next section). A harness flag
+puts the skill where that tool reads its skills, and several flags cover several tools in one
+run:
+
+```bash
+npx agents-handoff --claude             # Claude Code
+npx agents-handoff --codex              # Codex CLI
+npx agents-handoff --agents             # the harness-neutral store
+npx agents-handoff --all                # every harness found on this machine
+npx agents-handoff --claude --codex     # exactly these two, one run
+npx agents-handoff --harness claude,codex
+npx agents-handoff --skills-dir ~/.config/mytool/skills
+npx agents-handoff --project --claude   # this repository only (./.claude/skills)
+```
+
+| Flag | Harness | User-level directory | Per-repository directory, with `--project` |
+|---|---|---|---|
+| `--claude` | Claude Code | `~/.claude/skills` | `./.claude/skills` |
+| `--codex` | Codex CLI | `~/.codex/skills` | `./.codex/skills` |
+| `--agents` | the harness-neutral store | `~/.agents/skills` | `./.agents/skills` |
+| `--harness <a,b>` | named harness(es), comma separated, repeatable | as above | as above |
+| `--skills-dir <dir>` | any other stack, exactly | `<dir>` | `<dir>` |
+| `--all` | every harness whose configuration directory exists here | as above | — |
+
+Each target gets the skill folder `agents-handoff/` below that directory, so Claude Code finds
+`~/.claude/skills/agents-handoff/`. Targets are installed, reported and recorded one by one,
+and the run ends with a summary:
+
+```
+── target 1 of 2: claude ──
+✓ Installed agents-handoff v<version> to <dir>/agents-handoff
+Provenance: the tree beside the installer (.) · file-set sha256 3dab5c0d754a27fd…  (.agents-handoff-install.json)
+
+── target 2 of 2: custom dir <dir> ──
+…
+
+Summary
+  ✓ installed <dir> — v<version>
+  ✓ installed <dir> — v<version>
+```
+
+`--all` installs into the harnesses whose configuration directory exists in your home directory
+and names the ones it skipped; `--claude` and its siblings install there whether or not the
+directory exists yet. Detection is a suggestion, never a decision.
+
+Ask what this machine has, and whether what is installed is still intact:
+
+```bash
+npx agents-handoff doctor
+```
+
+```
+agents-handoff doctor
+  product v<version> · installer v<version> · node v<node version>
+
+Harnesses
+  ✓ claude  present  <home>/.claude/skills
+      v<version> · 39/39 files · provenance OK
+  · codex   not found  <home>/.codex/skills
+  ✓ agents  present  <home>/.agents/skills
+
+Global resolution
+  <dir> — <reason>
+
+Store (where handoffs are written)
+  handoff: config root=<dir>
+
+Verdict
+  1 harness installation(s) found.
+```
+
+`doctor` reads and reports. It never installs, updates or removes anything.
+
 ## Where a global install goes
 
 `--location global` does not point at a fixed directory. The installer searches for a store and
@@ -45,7 +145,7 @@ reports the reason it chose one. The order is:
 | # | Condition | Result |
 |---|---|---|
 | 1 | `AGENT_HANDOFF_GLOBAL_DIR` is set | that directory |
-| 2 | A skill store already holds an `agent-handoff` install | the newest such location |
+| 2 | A skill store already holds an `agents-handoff` install | the newest such location |
 | 3 | `~/.agents/skills` exists | `~/.agents/skills` |
 | 4 | A skill store exists | its first account-skill root |
 | 5 | Nothing found | the default store, created on install |
@@ -53,7 +153,7 @@ reports the reason it chose one. The order is:
 An account-skill store keeps skills two identifier levels below the store itself:
 
 ```
-<store>/<account-id>/<profile-id>/agent-handoff/
+<store>/<account-id>/<profile-id>/agents-handoff/
 ```
 
 `<store>` is `%APPDATA%\<client>\account-skills` on Windows, and `~/.<client>/account-skills` or
@@ -72,17 +172,18 @@ Global install root: <dir>
   override with: AGENT_HANDOFF_GLOBAL_DIR=<dir> or --path <dir>
 ```
 
-`--list` shows the resolved root, the local location, every candidate root, the harness skills
-home, and — inside a git repository — the project location. Each installed location is printed
-with its version and the number of manifest files present.
+`--list` shows the resolved root, the local location, every candidate root, each harness
+directory (whether or not it exists on this machine), and — inside a git repository — the
+project location. Each installation found is printed with its version, the number of manifest
+files present, and whether it still matches its install record.
 
 ## Locations
 
 | Location | Target directory |
 |---|---|
-| `global` (default) | `<resolved global root>/agent-handoff` |
-| `local` | `./local/skills/agent-handoff` |
-| `project` | `./skills/agent-handoff` |
+| `global` (default) | `<resolved global root>/agents-handoff` |
+| `local` | `./local/skills/agents-handoff` |
+| `project` | `./skills/agents-handoff` |
 | `--path <dir>` | exactly `<dir>` |
 
 ## Options
@@ -93,21 +194,31 @@ with its version and the number of manifest files present.
 | `--path <dir>` | none | Use this directory instead of a resolved location. |
 | `--version <v>` | `latest` | Request a version. Confirm what landed with `--verify`, which prints the installed version. |
 | `--force`, `-f` | off | Skip confirmations and overwrite an existing installation. |
+| `--claude`, `--codex`, `--agents` | none | Install into that harness's skills directory (table above). Repeatable, and combinable. |
+| `--harness <a,b>` | none | Named harness(es), comma separated. Repeatable. |
+| `--all` | none | Every harness whose configuration directory exists on this machine. |
+| `--skills-dir <dir>` | none | Any other stack, exactly. Repeatable. |
+| `--project` | off | With a harness flag: use the per-repository directory instead of the user-level one. |
+| `--provenance` | off | With `verify`: print the install record the verification was checked against. |
+| `--record` | off | With `verify-package`: store the tarball hashes in the install record. |
 | `--help`, `-h` | — | Print the installer usage text. |
 
 The installer accepts both bare verbs and flag forms: `install`/`--install`, `update`/`--update`,
-`remove`/`--remove`, `verify`/`--verify`, `list`/`--list`.
+`remove`/`--remove`, `verify`/`--verify`, `verify-package`/`--verify-package`, `list`/`--list`,
+`doctor`/`--doctor`.
 
 ## Commands
 
 | Command | Description |
 |---|---|
 | `install`, `i` (default) | Copy the skill files to the target. |
-| `update`, `u` | Reinstall over an existing installation. See [UPGRADE.md](UPGRADE.md). |
-| `remove`, `rm` | Remove the installation. See [UNINSTALL.md](UNINSTALL.md). |
-| `verify`, `v` | Check every manifest file, the skill metadata, and that the engine runs. |
-| `list`, `ls` | List installed locations with version and manifest file count. |
+| `update`, `u` | Update every installation found, or the harnesses named. See [UPGRADE.md](UPGRADE.md). |
+| `remove`, `rm` | Remove an installation, keeping everything the manifest does not own. See [UNINSTALL.md](UNINSTALL.md). |
+| `verify`, `v` | Check every installation found: each manifest file, the skill metadata, that the engine runs, and the install record. |
+| `verify-package`, `vp` | Check an installation against the published npm tarball for its version. |
+| `list`, `ls` | List installed locations with version, manifest file count and provenance state. |
 | `where` | Print the global root and why it was chosen. |
+| `doctor` | Which harnesses are present here, what is installed where, and whether each installation still matches its record. |
 
 ## Verify an installation
 
@@ -115,18 +226,115 @@ The installer accepts both bare verbs and flag forms: `install`/`--install`, `up
 npx agents-handoff --verify
 ```
 
-Verification runs three kinds of check:
+Verification runs four kinds of check:
 
 1. every file named in the installer manifest exists in the target;
 2. `SKILL.md` declares both `name` and `version`;
 3. `node tools/handoff.mjs config` exits 0 and prints the `handoff: config root=` marker — this
-   exercises the engine's module graph, so a missing module fails here.
+   exercises the engine's module graph, so a missing module fails here;
+4. the installation still matches the provenance record written when it was installed.
 
 Each check is printed with a pass or fail mark. On success the installer also prints the
-installed location and version; on failure it exits non-zero and tells you to reinstall.
+installed location and version; on failure it exits non-zero and names the files that changed.
+
+With no harness flag, `--verify` verifies **every installation found on this machine**, not just
+the one the global resolver would pick: a machine that holds the skill in `~/.claude/skills` and
+in `~/.agents/skills` has two copies, and both are checked. A harness flag or `--skills-dir`
+scopes the run to those targets. The run fails if any installation fails.
 
 There is no `--verbose` flag.
 
+## Prove an installation matches the published package
+
+`--verify` compares an installation with its own record. `--verify-package` compares it with the
+artifact npm is actually serving for its version — the strongest check available, and it works
+whichever way the install happened: from a tree, from a GitHub archive, or from `npx`.
+
+```bash
+npx agents-handoff --verify-package
+npx agents-handoff --verify-package --record
+```
+
+It runs three checks, in this order, because each one makes the next meaningful:
+
+1. the downloaded tarball matches the hashes the **registry declares** for that version
+   (`dist.integrity` and `dist.shasum`) — otherwise "the published package" would be whatever
+   the network handed over;
+2. every file named in the installer manifest is byte-identical to the file of that name in the
+   published tarball — each difference is named, with `not installed`, `not in the published
+   package` or `content differs`;
+3. the tarball's sha256 matches the one recorded for this installation, when one was recorded.
+
+It prints the package name and version, the tarball URL and the tarball's sha256. `--record`
+stores that sha256 (plus sha512, the integrity string and the shasum) in the `package` block of
+the install record, so every later run compares against a stored value instead of re-deriving
+one.
+
+This check needs the network. When the registry cannot be reached, or the installed version is
+not published, it fails and says so — it never passes by default.
+
+## The install record (provenance)
+
+Every install writes `.agents-handoff-install.json` inside the installed copy. It records what
+landed and what it was made from:
+
+| Field | Meaning |
+|---|---|
+| `product`, `version`, `installer_version` | What was installed, and which installer did it. |
+| `installed_at` | When. |
+| `harness`, `target` | Which harness flag selected the target, and its absolute path. |
+| `source` | `the tree beside the installer`, or the tag archive with its URL and sha256. |
+| `package` | The npm identity this installation should match: `name`, `version`, `registry`, `tarball`, and — once `--verify-package --record` has run — `sha256`, `sha512`, `integrity`, `shasum` and `verified_at`. |
+| `file_count`, `files_sha256` | The installed file set, folded into one hash. |
+| `files` | Every manifest path with its own sha256. |
+
+`verify` re-hashes the same file set and compares it with the record, so a changed, missing or
+renamed file fails the check and is named. That is the difference between an installation being
+present and being checkable: the file that changed is reported, not just `verification failed`.
+
+```bash
+npx agents-handoff --verify --provenance
+```
+
+`--provenance` prints the record it checked against, so the verification can be read without
+opening the file:
+
+```
+  provenance record
+    installed_at: <iso timestamp>
+    source: the tree beside the installer (.)
+    harness: claude
+    files: 39 · file-set sha256 3dab5c0d754a27fd…
+```
+
+An installation made before the record existed reports
+`· no provenance record — installed before 2.0.3; reinstall to record one` and is otherwise
+verified as before. Reinstall to write one.
+
+The `package` block is the hook for the published-tarball check: installing from a tree cannot
+know the hash of a tarball it did not download, so the hash is recorded the first time
+`npx agents-handoff --verify-package --record` runs, and compared on every run after that.
+
+## What `remove` keeps
+
+`remove` deletes exactly what the install manifest owns — the skill files, and the two files the
+installer writes for itself — and nothing else. Everything the manifest does not own is kept and
+listed:
+
+```
+Kept — not the installer's to delete:
+  .agent-handoff/
+  handoff-session.md
+  handoff.config.json
+  handoffs/
+  projects/
+```
+
+The rule is stated as a removal set rather than a keep list on purpose: a keep list deletes
+whatever nobody remembered to name, so a store called anything other than the expected
+directories would have gone with the skill. A `package.json` you wrote yourself is kept too; only
+the installer's own private stub is removed.
+
 ## Installing again
 
 Installing over an existing installation does nothing by default when the requested version is
@@ -137,8 +345,9 @@ Installing over an existing installation does nothing by default when the reques
 
 Use the release archive when you cannot run `npx`.
 
-1. Download the archive from the repository releases page: `agent-handoff-latest.zip`, or
-   `agent-handoff-v<version>.zip` for a pinned version.
+1. Download the archive the release attaches: `agents-handoff-v<version>.zip` from the
+   [releases page](https://github.com/Alot1z/agent-handoff/releases) (there is no
+   `latest` asset — the newest release carries its own version in the file name).
 2. Extract it into the target directory with `unzip`.
 3. Confirm the engine runs: `node "<target>/tools/handoff.mjs" config`.
 
@@ -164,13 +373,19 @@ By default the engine stores handoff data under its own root, inside the install
 | Symptom | Cause and fix |
 |---|---|
 | `Cannot write to <dir>` | The target is not writable. Pick another location with `--path`, or fix permissions. |
-| `Not installed at <dir>` | `update` and `verify` require an existing installation. Run `install` first. |
+| `Not installed at <dir>` | `--path` or a harness flag named a directory that holds no installation. Drop the flag to act on every installation found, or run `install` first. |
+| `Nothing to update:` / `Nothing to verify:` | No installation was found anywhere the installer looks. Install one, or name a target with `--path`. |
+| `verify-package` fails with `is not on the npm registry, or the registry is unreachable` | The installed version has no published tarball to compare against (a checkout install, or no network). The installation itself is untouched by that result. |
+| `verify-package` fails with `does NOT match ... as published` | The check names each differing file. Reinstall with `--force`, then run it again; a file you edited on purpose will keep failing until it is reverted. |
 | `Incomplete install: <n> of <m> file(s) missing — …` | The tree the installer reads from is not a complete one. Install from a fresh clone, or from a freshly downloaded archive. |
 | `no published release found — fetching the main branch` | Not an error: `--version latest` found no release object, so the archive of `main` is used instead. Pass `--version <x>` to install a released tag. |
 | `Cannot extract the archive (tar exited …)` | `tar` is missing, or the download did not arrive intact. The message prints the `curl` and `tar` commands that do the same job by hand. |
 | The wrong root was chosen | Run `where` to see the reason, then set `AGENT_HANDOFF_GLOBAL_DIR` or pass `--path`. |
 | `remove` did nothing | Removal asks for confirmation, and refuses in a non-interactive shell. Pass `--force`. |
 | Verification fails | The output names the failing check. Fix it, or reinstall with `--force`. |
+| `provenance: file-set sha256 matches the install record` fails | A file in the installation changed or went missing after it was installed. The changed paths are listed under the check; reinstall with `--force` to restore them, or keep the edit knowingly. |
+| `no provenance record` | The installation predates the record. That is not a failure; reinstall to write one. |
+| A harness install went somewhere unexpected | Harness directories are listed in the table above and by `doctor`/`list`. Use `--path` or `--skills-dir` to name the directory yourself. |
 
 ## See also