agents-handoff 2.0.2 → 2.0.4

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-All notable changes to agent-handoff are recorded here.
+All notable changes to agents-handoff are recorded here.
 
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Releases before 2.0.0
@@ -15,6 +15,77 @@ version, and it is the version published to npm: the repository root is the
 
 Add entries under the matching heading as changes land.
 
+## [2.0.4] - 2026-10-09
+
+### Added
+
+- A demo animation on the README and the documentation home page: one run installing into every
+  harness, a session captured and verified, and an installation proved against the published
+  tarball (`assets/handoff-demo.gif`).
+- **[Compatibility](https://github.com/Alot1z/agent-handoff/blob/main/docs/COMPATIBILITY.md)**
+  (`docs/COMPATIBILITY.md`) now records what was measured rather than what
+  is assumed: Node 26 verified, and Bun verified as an alternative runtime — the engine's
+  verbs run unchanged there, and the suite passes 34/34 with `bun test --timeout 30000` (Bun's
+  default 5-second per-test timeout is shorter than the suite's child-process tests). It also
+  states why the artifacts are JavaScript rather than TypeScript: the contracts are the
+  versioned JSON Schemas the runtime validates against, and a build step would put a compiler
+  between a user and a working tool.
+
+### Fixed
+
+- `--update` and `--verify` reported "no installations found" on a machine whose copies predate
+  the 2.0.3 rename, because they only looked for `agents-handoff/`. Both now recognise the
+  `agent-handoff/` directory every earlier release installed and act on it in place.
+- The global-root search missed `~/.config`, which is where a desktop client keeps its
+  account-skill store on Windows too — so that store's installation was invisible to `--list`,
+  `--update`, `--verify` and `doctor` even though the client kept reading it.
+
+### Changed
+
+- `remove` states what it keeps before asking, so its confirmation matches what it does.
+
+## [2.0.3] - 2026-10-09
+
+### Added
+
+- **Named harness targets.** One run can install the skill into Claude Code, Codex CLI and the
+  harness-neutral `~/.agents/skills` at once: `--claude`, `--codex`, `--agents`,
+  `--harness claude,codex` (repeatable), `--all` for every harness whose directory exists on
+  this machine, `--skills-dir <dir>` for any other stack, and `--project` for the
+  per-repository form. Every target gets its own copy and its own install record.
+- **`verify-package`**, a verb that checks an installation against the package npm is actually
+  serving for its version: it verifies the downloaded tarball against the registry's own
+  `integrity` and `shasum`, compares the published file set with the installed one file by
+  file, and compares the tarball sha256 with the value recorded for that install. `--record`
+  stores the tarball hashes in the install record, so later runs compare with a stored value.
+- The install record (`.agents-handoff-install.json`) now carries a `package` block — name,
+  version, registry, tarball URL, and the sha256/sha512/integrity/shasum filled in by
+  `verify-package` — so an installation can be checked against the published artifact rather
+  than only against itself.
+- Installing from the repository without publishing: `npx github:Alot1z/agent-handoff` runs the
+  same installer straight from GitHub, and the installation guide documents both that and the
+  clone-and-run path.
+- Five installer behaviour tests — multi-harness install with a record per target, `--update`
+  over every installation, `--verify` failing on a tampered copy, `remove` keeping user data,
+  and `verify-package` refusing a version npm does not serve. The suite is 34 tests.
+
+### Changed
+
+- `--update` and `--verify` with no harness flag now act on **every** installation found on the
+  machine instead of the one resolved target. A machine holding the skill in `~/.claude/skills`
+  and in `~/.agents/skills` has two copies, and updating only the resolved one left the other
+  silently stale; both verbs print a per-target summary.
+- The runtime layer's entry point is `tools/agents-handoff.mjs`, matching the product name.
+  `tools/agent-handoff.mjs` is installed alongside it as a forwarder, so notes and scripts that
+  name the old path keep working.
+
+### Fixed
+
+- `remove` deleted anything that was not one of three expected directory names, which meant a
+  handoff store kept under any other name was destroyed by `remove --force`. Removal is now
+  driven by the install manifest — what an install owns is what it copied — and the run prints
+  the entries it deliberately kept, including the store and `handoff.config.json`.
+
 ## [2.0.2] - 2026-10-09
 
 ### Added
@@ -49,7 +120,7 @@ Add entries under the matching heading as changes land.
   the development tree has. Sources are written in the shipped tree's terms and resolved against
   both layouts, and an install that cannot resolve a source now fails with the missing paths
   instead of warning and continuing.
-- CI failed on every run: the runtime-layer smoke test ran `agent-handoff.mjs list`, which is not
+- CI failed on every run: the runtime-layer smoke test ran `agents-handoff.mjs list`, which is not
   a verb of that tool (it exits 2). The step builds a handoff into a scratch store and runs
   `index`, a verb that exists.
 - The shipped version disagreed across files: `SKILL.md` said 2.0.0 while `skill.json` and
@@ -107,7 +178,7 @@ documentation site.
 
 ### Added
 
-- **Capture engine** (`tools/handoff.mjs`, published as the `agent-handoff` bin). `build`
+- **Capture engine** (`tools/handoff.mjs`, published as the `agents-handoff` bin). `build`
   reads a JSONL or plain-text transcript and writes a handoff directory:
   `HANDOFF.md`, `HANDOFF.summary.json`, `HANDOFF.llm.json`, `timeline.jsonl`, `TOOLS.md`,
   `manifest.json`. Also `list`, `show`, `verify`, `rename`, `retitle` and `config`.
@@ -121,7 +192,7 @@ documentation site.
 - **Store-root resolution** (`tools/lib/handoff-root.mjs`): `HANDOFFS_ROOT`, then
   `handoff.config.json` found by walking up, then a `handoffs/` directory on the same walk,
   then the skill directory. Reported by `handoff.mjs config`.
-- **Runtime layer** (`tools/agent-handoff.mjs`): `auto`, `verify-gate`, `promote`, `merge`,
+- **Runtime layer** (`tools/agents-handoff.mjs`): `auto`, `verify-gate`, `promote`, `merge`,
   `federated-merge`, `self-improve`, `index`. Every mutating command takes a lock, backs up
   before writing, verifies after applying, and rolls back on failure.
 - **Bounded execution** (`tools/runtime-engine.mjs`): risk classes `R0`–`R4` evaluated against
@@ -131,8 +202,8 @@ documentation site.
   `command` probes that report `healthy` / `unhealthy` / `unknown` with the evidence behind
   each verdict.
 - **Installer** (`install/`, package `agents-handoff`): `install`, `update`, `remove`,
-  `verify`, `list`, `where`, targeting a resolved global root, `./local/skills/agent-handoff`,
-  or `./skills/agent-handoff`.
+  `verify`, `list`, `where`, targeting a resolved global root, `./local/skills/agents-handoff`,
+  or `./skills/agents-handoff`.
 - **Documentation site** at <https://alot1z.github.io/agent-handoff/>, built by GitHub Pages
   from `docs/`.
 - **CI** (`.github/workflows/ci.yml`): the test suite on Node 18, 20 and 22, a runtime-layer

package/README.md

@@ -1,4 +1,4 @@
-# agent-handoff
+# agents-handoff
 
 **[Installation guide →](https://alot1z.github.io/agent-handoff/INSTALL.html)**  ·  **[Documentation →](https://alot1z.github.io/agent-handoff/)**  ·  **[Changelog](CHANGELOG.md)**
 
@@ -8,22 +8,68 @@
 
 One handoff format for every AI coding harness. A working session — messages, tool calls,
 reasoning, and the provenance to prove where each byte came from — is captured as a folder
-that a fresh agent can continue from with zero shared memory.
+that a fresh agent can continue from with zero shared memory. Zero runtime dependencies,
+Node.js 18 or newer, nothing read from the network at run time.
 
-- Zero runtime dependencies; Node.js 18 or newer.
-- Reads any JSONL or plain-text transcript, whatever produced it.
-- Every artifact carries a sha256 provenance chain, and `verify` recomputes it.
-- Writes are backed up, verified and rolled back on failure.
+![agents-handoff: one install into every harness, a verified handoff, and an installation
+proved against the published npm tarball](assets/handoff-demo.gif)
+
+*An abbreviated run of 2.0.3: `--all` installs into every harness found, a session is captured
+and verified, and `--verify-package` proves the installed copy is the published one. The sample
+session is illustrative; the command and output shapes are the real ones.*
 
 ## Install
 
 ```bash
-npx agents-handoff
-npx agents-handoff where     # show the resolved install root, and why it was chosen
+npx agents-handoff --all      # every harness found on this machine, in one run
+```
+
+That is the whole install. Choose your stack instead — one harness, several, or a skills
+directory of your own:
+
+| Command | Installs into |
+|---|---|
+| `npx agents-handoff --claude` | `~/.claude/skills` — Claude Code |
+| `npx agents-handoff --codex` | `~/.codex/skills` — Codex CLI |
+| `npx agents-handoff --agents` | `~/.agents/skills` — the harness-neutral store |
+| `npx agents-handoff --harness claude,codex` | the named harnesses, in one run |
+| `npx agents-handoff --project --claude` | `./.claude/skills` — this repository only |
+| `npx agents-handoff --skills-dir <dir>` | any other stack, exactly |
+
+Without a harness flag the installer resolves the global root rather than hard-coding one and
+reports which it chose — `npx agents-handoff where` prints the same decision on its own.
+
+### Or straight from the repository
+
+```bash
+npx github:Alot1z/agent-handoff --claude   # run the installer from GitHub, no npm
+```
+
+```bash
+git clone https://github.com/Alot1z/agent-handoff.git
+cd agent-handoff
+node install/install.mjs --all      # the same installer, run from the tree
+```
+
+### Update it, and check it against the published package
+
+```bash
+npx agents-handoff --update                    # every installation found, one run
+npx agents-handoff --verify --provenance       # every installation, against its own record
+npx agents-handoff --verify-package --record   # against the tarball npm is serving
+npx agents-handoff --doctor                    # what is here, and is it intact
+npx agents-handoff --remove                    # removes the skill; your store is kept
 ```
 
-The installer resolves the global root instead of hard-coding one. The resolution order,
-the location targets and the requirements are in the
+Every install writes `.agents-handoff-install.json` beside the skill: a sha256 over the
+installed file set, what it was installed from, and a `package` block naming the version it
+should match. `verify` recomputes that hash and fails when a file changed, so an installation
+is checkable rather than merely present; `verify-package` fetches the published tarball,
+checks it against the registry's own integrity and shasum, and compares the installed files
+with the package file by file — `--record` stores the tarball hashes in the install record.
+`update` and `verify` with no harness flag act on **every** installation found, and `remove`
+deletes only what the install manifest owns, printing what it kept, so a store survives under
+any name. The resolution order, the location targets and the requirements are in the
 **[installation guide](https://alot1z.github.io/agent-handoff/INSTALL.html)** and
 [docs/INSTALL.md](docs/INSTALL.md).
 
@@ -86,13 +132,14 @@ Full documentation is published at **<https://alot1z.github.io/agent-handoff/>**
 
 ```
 tools/handoff.mjs              capture engine (the CLI above)
-tools/agent-handoff.mjs        runtime layer: auto, verify-gate, promote, merge, self-improve, index, dispatch
+tools/agents-handoff.mjs        runtime layer: auto, verify-gate, promote, merge, self-improve, index, dispatch
+tools/agent-handoff.mjs        forwarder to the above, kept so older notes keep working
 tools/runtime-engine.mjs       bounded execution and the permission gate
 tools/capability-registry.mjs  capability health probes
 tools/lib/                     shared store-root resolution
 docs/  refs/  templates/       documentation, reference material, output templates
 schemas/                       handoff payload and configuration schemas
-install/                       the npx installer package
+install/                       the installer behind the agents-handoff npx package
 tests/                         acceptance fixture and a minimal transcript
 ```
 

package/SKILL.md

@@ -1,12 +1,12 @@
 ---
-name: agent-handoff
+name: agents-handoff
 description: >-
   Write, verify, and hand off complete AI working sessions across any harness
   (Claude Code, Codex, DeepSeek Harness, plain JSONL or text logs). Captures a
   session as a portable, sha256-proven handoff folder a fresh agent can continue
   from with zero shared memory, with versioned contracts, an evidence gate, and
   backup/verify/rollback on every write. Zero runtime dependencies, no network.
-version: 2.0.2
+version: 2.0.4
 domain: orchestration
 tokens: 900
 allowed-tools: Bash(node:*), Read, Edit, Write
@@ -25,8 +25,8 @@ conversation anywhere, with provenance for every artifact.
 | **L1 Metadata** | Always (frontmatter above) | ~100 | name + description |
 | **L2 Instructions** | This file, when triggered | <5k | core workflow + commands below |
 | **L3 Resources** | As needed | none until read | `docs/`, `templates/`, `refs/`, `tools/handoff.mjs` |
-| **L4 Dynamic** | When you need runtime/self-adapting | none until run | `tools/agent-handoff.mjs`: auto, verify-gate, promote, merge, self-improve |
-| **L5 Collaborative** | Verified handoff dispatches a worker | none until run | `tools/agent-handoff.mjs` dispatch + `docs/LEVEL5.md` |
+| **L4 Dynamic** | When you need runtime/self-adapting | none until run | `tools/agents-handoff.mjs`: auto, verify-gate, promote, merge, self-improve |
+| **L5 Collaborative** | Verified handoff dispatches a worker | none until run | `tools/agents-handoff.mjs` dispatch + `docs/LEVEL5.md` |
 
 ## What this skill is (capabilities + contracts)
 
@@ -100,13 +100,13 @@ FOLLOW_UP:
 
 ### D. Level 4 runtime + L5 dispatch
 ```bash
-HANDOFFS_ROOT=<store> node tools/agent-handoff.mjs auto --source <file> --session <id> --harness <h> --project <p>
-HANDOFFS_ROOT=<store> node tools/agent-handoff.mjs verify-gate <id-prefix>
-HANDOFFS_ROOT=<store> node tools/agent-handoff.mjs promote <id-prefix>
-HANDOFFS_ROOT=<store> node tools/agent-handoff.mjs merge <a> <b>
-HANDOFFS_ROOT=<store> node tools/agent-handoff.mjs self-improve
-HANDOFFS_ROOT=<store> node tools/agent-handoff.mjs index
-HANDOFFS_ROOT=<store> node tools/agent-handoff.mjs dispatch <id-prefix> --task "<objective>" [--broker <orchestrator-root> --live]
+HANDOFFS_ROOT=<store> node tools/agents-handoff.mjs auto --source <file> --session <id> --harness <h> --project <p>
+HANDOFFS_ROOT=<store> node tools/agents-handoff.mjs verify-gate <id-prefix>
+HANDOFFS_ROOT=<store> node tools/agents-handoff.mjs promote <id-prefix>
+HANDOFFS_ROOT=<store> node tools/agents-handoff.mjs merge <a> <b>
+HANDOFFS_ROOT=<store> node tools/agents-handoff.mjs self-improve
+HANDOFFS_ROOT=<store> node tools/agents-handoff.mjs index
+HANDOFFS_ROOT=<store> node tools/agents-handoff.mjs dispatch <id-prefix> --task "<objective>" [--broker <orchestrator-root> --live]
 ```
 Dispatch re-runs the evidence gate first; carries manifest sha256; dry-run by default
 (autonomy ladder: workflow-execute requires explicit --live).
@@ -137,7 +137,7 @@ Dispatch re-runs the evidence gate first; carries manifest sha256; dry-run by de
 | Fresh-session bootstrap | `refs/bootstrap.md` |
 | Brief discipline | `refs/brief-checklist.md` |
 | Engine source | `tools/handoff.mjs` |
-| L4 runtime | `tools/agent-handoff.mjs` |
+| L4 runtime | `tools/agents-handoff.mjs` |
 | L4/L5 design | `docs/LEVEL4.md`, `docs/LEVEL5.md` |
 | Cross-harness adapters | `refs/ADAPTERS.md` |
 | Handoff format + schema | `docs/FORMAT.md`, `templates/` |

package/capability-registry.json

@@ -11,7 +11,7 @@
     {
       "id": "filesystem.write",
       "kind": "dir-writable",
-      "target": ".agent-handoff",
+      "target": ".agents-handoff",
       "required": true,
       "purpose": "persist runtime state and checkpoints"
     },

package/docs/ARCHITECTURE.md

@@ -11,7 +11,7 @@ elsewhere means either pasting the chat back in, or starting from memory. Both l
 that matters: the exact turns, the tool calls, and the ability to prove which source bytes
 produced the brief you are reading.
 
-agent-handoff turns the session into files instead. A directory of plain text and JSON, a
+agents-handoff turns the session into files instead. A directory of plain text and JSON, a
 hash chain over it, and a fixed folder layout. Anything that can read a file can continue
 from one, with no shared memory between the two sessions.
 
@@ -22,10 +22,10 @@ Five layers, each with one job, and each usable without the ones above it.
 | Layer | File | Job |
 |---|---|---|
 | Capture engine | `tools/handoff.mjs` | Turns one transcript into one handoff folder. Passive: something has to invoke it. |
-| Runtime layer | `tools/agent-handoff.mjs` | Acts on the state of the store: staleness, gates, composition, imports, index. |
+| Runtime layer | `tools/agents-handoff.mjs` | Acts on the state of the store: staleness, gates, composition, imports, index. |
 | Bounded execution | `tools/runtime-engine.mjs` | Decides whether an operation may run, before running it. |
 | Capability probes | `tools/capability-registry.mjs` | Reports what a declared capability actually does on this machine. |
-| Distribution | `install/install.mjs` | Puts the skill where a client will look for it. |
+| Distribution | `install/install.mjs` | Puts the skill where a client will look for it — one harness, several at once, or an exact directory — and records what it installed. |
 
 The capture engine has no opinion about installation, and the runtime layer has no opinion
 about transcripts — it shells out to the engine for builds and verification. That split is
@@ -90,6 +90,23 @@ What the chain detects: a manifest edited by hand, a truncated or extended timel
 payload that no longer parses. What it does not do is prove that the source was authentic —
 read [PROVENANCE.md](PROVENANCE.md) for the precise boundary.
 
+## Install provenance
+
+A handoff folder proves what it was built from. An installation answers a different question:
+what is on this machine, and where did it come from. The installer writes
+`.agents-handoff-install.json` into every copy it makes, and `verify` re-hashes the same file
+set to compare the copy with that record.
+
+| Value | Definition |
+|---|---|
+| `files_sha256` | SHA-256 over the sorted `path\0sha256(file)` lines of every manifest file. |
+| `files` | Per-file sha256 values, so a mismatch names the file that changed. |
+| `source` | `tree` for a copy made from a checkout or archive beside the installer, or `archive` with the tag and the archive's own sha256 when the copy was fetched. |
+
+The install record is a record, not a signature: it proves what was installed and detects
+drift, and it cannot prove the tree it came from was trustworthy. That distinction is stated
+in full in [PROVENANCE.md](PROVENANCE.md).
+
 ## Concurrency and write safety
 
 Every mutating runtime command takes a lock before touching the store. Locks live in
@@ -145,19 +162,25 @@ stated in the command reference rather than left for a caller to discover.
 
 ```
 tools/handoff.mjs          capture engine
-tools/agent-handoff.mjs    runtime layer
+tools/agents-handoff.mjs    runtime layer
+tools/agent-handoff.mjs     forwarder from the runtime layer's pre-rename path
 tools/runtime-engine.mjs   bounded execution
 tools/capability-registry.mjs  capability probes
 tools/lib/handoff-root.mjs store-root resolution (single owner)
 tools/handoff.test.mjs     the hermetic test suite
 docs/                      this documentation and the Pages site
+docs/SESSIONS.md           the session index, rendered from a real store
+.github/scripts/           generators and checks: the session index, the doc link check
 refs/                      reference material: adapters, protocol, roles, brief checklist
 templates/                 handoff templates and the LLM payload schema
 schemas/                   the portable handoff payload schema
-install/                   the npx installer package
+install/                   the installer behind the agents-handoff npx package
 tests/                     acceptance fixture and a minimal transcript
 ```
 
+Inside an installed copy — not in this repository — the installer adds
+`.agents-handoff-install.json`, the record of what landed there and what it was made from.
+
 The documentation site at <https://alot1z.github.io/agent-handoff/> is built by GitHub Pages
 directly from `docs/`. `docs/_data/nav.yml` is the navigation, `docs/_config.yml` is the
 Jekyll configuration, and `.github/scripts/check-docs.mjs` fails CI when a page is missing

package/docs/CHANGELOG.md

@@ -4,7 +4,7 @@ title: Changelog
 
 # Changelog
 
-All notable changes to agent-handoff are recorded here.
+All notable changes to agents-handoff are recorded here.
 
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Releases before 2.0.0
@@ -12,15 +12,86 @@ were development builds and were never published, so they are not listed.
 
 The version in [package.json](https://github.com/Alot1z/agent-handoff/blob/main/package.json)
 and [skill.json](https://github.com/Alot1z/agent-handoff/blob/main/skill.json) is the release
-version. The version of the separate installer package is in
-[install/package.json](https://github.com/Alot1z/agent-handoff/blob/main/install/package.json)
-and has its own
-[changelog](https://github.com/Alot1z/agent-handoff/blob/main/install/CHANGELOG.md).
+version, and it is the version published to npm: the repository root is the
+[`agents-handoff`](https://www.npmjs.com/package/agents-handoff) package.
 
 ## [Unreleased]
 
 Add entries under the matching heading as changes land.
 
+## [2.0.4] - 2026-10-09
+
+### Added
+
+- A demo animation on the README and the documentation home page: one run installing into every
+  harness, a session captured and verified, and an installation proved against the published
+  tarball (`assets/handoff-demo.gif`).
+- **[Compatibility](https://github.com/Alot1z/agent-handoff/blob/main/docs/COMPATIBILITY.md)**
+  (`docs/COMPATIBILITY.md`) now records what was measured rather than what
+  is assumed: Node 26 verified, and Bun verified as an alternative runtime — the engine's
+  verbs run unchanged there, and the suite passes 34/34 with `bun test --timeout 30000` (Bun's
+  default 5-second per-test timeout is shorter than the suite's child-process tests). It also
+  states why the artifacts are JavaScript rather than TypeScript: the contracts are the
+  versioned JSON Schemas the runtime validates against, and a build step would put a compiler
+  between a user and a working tool.
+
+### Fixed
+
+- `--update` and `--verify` reported "no installations found" on a machine whose copies predate
+  the 2.0.3 rename, because they only looked for `agents-handoff/`. Both now recognise the
+  `agent-handoff/` directory every earlier release installed and act on it in place.
+- The global-root search missed `~/.config`, which is where a desktop client keeps its
+  account-skill store on Windows too — so that store's installation was invisible to `--list`,
+  `--update`, `--verify` and `doctor` even though the client kept reading it.
+
+### Changed
+
+- `remove` states what it keeps before asking, so its confirmation matches what it does.
+
+## [2.0.3] - 2026-10-09
+
+### Added
+
+- **Named harness targets.** One run can install the skill into Claude Code, Codex CLI and the
+  harness-neutral `~/.agents/skills` at once: `--claude`, `--codex`, `--agents`,
+  `--harness claude,codex` (repeatable), `--all` for every harness whose directory exists on
+  this machine, `--skills-dir <dir>` for any other stack, and `--project` for the
+  per-repository form. Every target gets its own copy and its own install record.
+- **`verify-package`**, a verb that checks an installation against the package npm is actually
+  serving for its version: it verifies the downloaded tarball against the registry's own
+  `integrity` and `shasum`, compares the published file set with the installed one file by
+  file, and compares the tarball sha256 with the value recorded for that install. `--record`
+  stores the tarball hashes in the install record, so later runs compare with a stored value.
+- The install record (`.agents-handoff-install.json`) now carries a `package` block — name,
+  version, registry, tarball URL, and the sha256/sha512/integrity/shasum filled in by
+  `verify-package` — so an installation can be checked against the published artifact rather
+  than only against itself.
+- Installing from the repository without publishing: `npx github:Alot1z/agent-handoff` runs the
+  same installer straight from GitHub, and the installation guide documents both that and the
+  clone-and-run path.
+- Five installer behaviour tests — multi-harness install with a record per target, `--update`
+  over every installation, `--verify` failing on a tampered copy, `remove` keeping user data,
+  and `verify-package` refusing a version npm does not serve. The suite is 34 tests.
+
+### Changed
+
+- `--update` and `--verify` with no harness flag now act on **every** installation found on the
+  machine instead of the one resolved target. A machine holding the skill in `~/.claude/skills`
+  and in `~/.agents/skills` has two copies, and updating only the resolved one left the other
+  silently stale; both verbs print a per-target summary.
+- The runtime layer's entry point is `tools/agents-handoff.mjs`, matching the product name.
+  `tools/agent-handoff.mjs` is installed alongside it as a forwarder, so notes and scripts that
+  name the old path keep working.
+
+### Fixed
+
+- `remove` deleted anything that was not one of three expected directory names, which meant a
+  handoff store kept under any other name was destroyed by `remove --force`. Removal is now
+  driven by the install manifest — what an install owns is what it copied — and the run prints
+  the entries it deliberately kept, including the store and `handoff.config.json`.
+
+## [2.0.2] - 2026-10-09
+
 ### Added
 
 - **[Session index](https://alot1z.github.io/agent-handoff/SESSIONS.html)** (`docs/SESSIONS.md`):
@@ -30,16 +101,19 @@ Add entries under the matching heading as changes land.
   the engine from the two transcripts this repository ships, and
   `.github/scripts/build-sessions-index.mjs --check` fails the build when the page and the store
   disagree.
-- The installer is published to npm from the release workflow: a tag publishes `install/` as
-  `agents-handoff`, skips a version npm already has, and reports — without failing the
-  release — when `NPM_TOKEN` is not configured.
+- The skill is published to npm as
+  [`agents-handoff`](https://www.npmjs.com/package/agents-handoff), from the repository root,
+  and the release workflow publishes it on a tag: it skips a version npm already has, and
+  reports — without failing the release — when `NPM_TOKEN` is not configured. The package
+  carries the skill tree, so `npx agents-handoff` installs with no download.
+- `npm test`, `npm run check:docs` and `npm run check:session-index` are wired into
+  `prepublishOnly`, so a tree whose suite, links or session index are stale cannot be published.
 
 ### Changed
 
-- `npx agents-handoff` now installs the skill as documented. The published package
-  carries `install/` alone, so the installer downloads the archive for the requested version and
-  copies from it. It previously looked for the skill files beside itself, found none, and
-  reported success while installing nothing.
+- `npx agents-handoff` now installs the skill as documented. It previously looked for the skill
+  files beside itself, found none, and reported success while installing nothing; a bare copy of
+  `install/` still falls back to downloading the archive for the requested version.
 - The clean-checkout suite builds its fixture from the shipped projection rather than the
   development tree, which is what let the installer's broken source paths pass every local test.
 
@@ -50,7 +124,7 @@ Add entries under the matching heading as changes land.
   the development tree has. Sources are written in the shipped tree's terms and resolved against
   both layouts, and an install that cannot resolve a source now fails with the missing paths
   instead of warning and continuing.
-- CI failed on every run: the runtime-layer smoke test ran `agent-handoff.mjs list`, which is not
+- CI failed on every run: the runtime-layer smoke test ran `agents-handoff.mjs list`, which is not
   a verb of that tool (it exits 2). The step builds a handoff into a scratch store and runs
   `index`, a verb that exists.
 - The shipped version disagreed across files: `SKILL.md` said 2.0.0 while `skill.json` and
@@ -108,7 +182,7 @@ documentation site.
 
 ### Added
 
-- **Capture engine** (`tools/handoff.mjs`, published as the `agent-handoff` bin). `build`
+- **Capture engine** (`tools/handoff.mjs`, published as the `agents-handoff` bin). `build`
   reads a JSONL or plain-text transcript and writes a handoff directory:
   `HANDOFF.md`, `HANDOFF.summary.json`, `HANDOFF.llm.json`, `timeline.jsonl`, `TOOLS.md`,
   `manifest.json`. Also `list`, `show`, `verify`, `rename`, `retitle` and `config`.
@@ -122,7 +196,7 @@ documentation site.
 - **Store-root resolution** (`tools/lib/handoff-root.mjs`): `HANDOFFS_ROOT`, then
   `handoff.config.json` found by walking up, then a `handoffs/` directory on the same walk,
   then the skill directory. Reported by `handoff.mjs config`.
-- **Runtime layer** (`tools/agent-handoff.mjs`): `auto`, `verify-gate`, `promote`, `merge`,
+- **Runtime layer** (`tools/agents-handoff.mjs`): `auto`, `verify-gate`, `promote`, `merge`,
   `federated-merge`, `self-improve`, `index`. Every mutating command takes a lock, backs up
   before writing, verifies after applying, and rolls back on failure.
 - **Bounded execution** (`tools/runtime-engine.mjs`): risk classes `R0`–`R4` evaluated against
@@ -132,8 +206,8 @@ documentation site.
   `command` probes that report `healthy` / `unhealthy` / `unknown` with the evidence behind
   each verdict.
 - **Installer** (`install/`, package `agents-handoff`): `install`, `update`, `remove`,
-  `verify`, `list`, `where`, targeting a resolved global root, `./local/skills/agent-handoff`,
-  or `./skills/agent-handoff`.
+  `verify`, `list`, `where`, targeting a resolved global root, `./local/skills/agents-handoff`,
+  or `./skills/agents-handoff`.
 - **Documentation site** at <https://alot1z.github.io/agent-handoff/>, built by GitHub Pages
   from `docs/`.
 - **CI** (`.github/workflows/ci.yml`): the test suite on Node 18, 20 and 22, a runtime-layer