agents-handoff 0.0.0-stage → 2.0.3

package/docs/PROVENANCE.md

@@ -0,0 +1,110 @@
+---
+title: Provenance
+---
+
+# Provenance
+
+## What this document covers
+
+Every handoff carries a hash chain that ties its rendered files to the transcript it was built from.
+This document states what is hashed, how to re-verify it, and what the check cannot prove.
+
+## The chain
+
+| Artifact | Field | Definition |
+|---|---|---|
+| Source transcript | `raw_sha256` | SHA-256 of the whole source file, read as UTF-8 at build time |
+| `manifest.json` | `manifest_sha256` | SHA-256 of `JSON.stringify(manifest)` with `manifest_sha256` removed |
+| `HANDOFF.summary.json` | `provenance.raw_sha256`, `provenance.manifest_sha256` | Copies of the two hashes above |
+| `HANDOFF.llm.json` | `provenance.manifest_sha256` | Copy of the manifest hash |
+| `HANDOFF.md` | *Provenance* section | Both hashes and the revision, rendered as text |
+
+`manifest.json` also records `source_paths` (every transcript ever merged into the session),
+`watermark` (the highest turn sequence emitted), `revisions` and `turn_count`.
+
+## Verification
+
+```bash
+node tools/handoff.mjs verify <id-prefix>
+```
+
+`verify` recomputes `manifest_sha256` from the stored manifest and compares it, then requires
+`timeline.jsonl` to exist and to hold exactly `turn_count` lines, then parses `HANDOFF.llm.json`.
+It prints one `PASS` line, or `FAIL` with the reason.
+
+| Exit | Meaning |
+|---|---|
+| 0 | All three checks passed |
+| 1 | Manifest mismatch, timeline missing, turn-count drift, or unparsable payload |
+| 2 | No prefix given |
+| 3 | Prefix matched more than one session |
+| 4 | No session matched, or no handoffs exist |
+
+## What the check detects
+
+- A stored manifest whose fields have been edited or added.
+- A truncated or padded `timeline.jsonl`, because its line count must equal `turn_count`.
+- A missing timeline.
+- A `HANDOFF.llm.json` that is no longer valid JSON.
+
+## What the check cannot detect
+
+- **Edits to unhashed renders.** `HANDOFF.md`, `HANDOFF.summary.json` and `TOOLS.md` are not hashed.
+  Their bytes can be changed freely and `verify` still passes.
+- **Timeline content edits that preserve the line count.** A rewritten turn keeps the count.
+- **Re-hashing by the editor.** The hashes are self-consistent, not signed. Anyone who edits the
+  manifest can recompute `manifest_sha256` and produce a folder that verifies clean. There is no key
+  material, no signature and no external trust anchor.
+- **Anything outside the session folder.** `PROJECT.md`, `INDEX.json` and `links/*.md` carry no
+  hashes.
+
+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
+`watermark` are appended to `timeline.jsonl`, `revisions` increments, and the manifest hash is
+recomputed. If the source is unchanged and no new turns exist, the run reports `up-to-date` and
+bumps nothing. The rendered summary, payload and `HANDOFF.md` are regenerated from the full
+timeline, so a revision never mixes stale and fresh text.
+
+## Privacy note on `source_paths`
+
+A manifest records the absolute path of every transcript that fed the session. A handoff folder
+therefore contains the local paths of the machine it was built on. Review that field before sharing
+a folder outside the machine.
+
+## Repository provenance
+
+- License: MIT, see [../LICENSE](https://github.com/Alot1z/agent-handoff/blob/main/LICENSE).
+- The engine and runtime use only `node:` built-ins. No third-party source is bundled and
+  `package.json` declares no dependencies.
+- Development notes, internal plans and research material are not part of this repository and are
+  not published with it.

package/docs/SECURITY.md

@@ -0,0 +1,93 @@
+---
+title: Security
+---
+
+# Security
+
+## Scope
+
+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.
+
+## What the tool reads
+
+| Input | How it is used |
+|---|---|
+| The file passed to `build --source` | Read as UTF-8 text and parsed into turns. A `.jsonl` file is parsed line by line; anything else is parsed with role markers. |
+| `handoff.config.json` | Walked up from the current directory and validated against `handoff.config.schema.json`. A present-but-invalid file is fatal (`exit 2`). |
+
+Adapters that read a harness session store are external to the engine. They read stores and never
+write to them. See [../refs/ADAPTERS.md](https://github.com/Alot1z/agent-handoff/blob/main/refs/ADAPTERS.md).
+
+## What the tool writes
+
+Under the resolved root (see [FORMAT.md](FORMAT.md)): `HANDOFF.md`, `HANDOFF.summary.json`,
+`HANDOFF.llm.json`, `timeline.jsonl`, `TOOLS.md`, `manifest.json`, and per project `PROJECT.md`,
+plus `INDEX.json` and `links/*.md`. Nothing else is written and nothing outside the root is
+modified.
+
+Writes go straight to the destination path with `fs.writeFileSync`. They are not atomic and are not
+staged through a temporary file, so an interrupted run can leave a partial file. `verify` detects
+that only indirectly — see [PROVENANCE.md](PROVENANCE.md).
+
+## Secrets
+
+The engine performs **no secret detection and no redaction**. A transcript containing a token or a
+key produces a handoff containing that token or key. There is no scanning pass, no allowlist and no
+masking.
+
+`handoff.config.example.json` lists an `exclude_from_handoff` array. Treat that as intent, not as an
+enforced control: the engine reads `storage.path`, `handoff_dir`, `project_name` and `linking` from a
+config, and does not read that array.
+
+Only hand off transcripts you have reviewed. Keep `.env` files and key material out of version
+control, and do not commit a handoff folder that quotes them.
+
+## Malicious input
+
+A transcript is data. It is never evaluated, never executed, and never interpreted as configuration
+or as a request. Concretely:
+
+- A tool call recorded in a transcript is copied verbatim as text into `TOOLS.md`. The engine does not run it.
+- A transcript cannot change the engine's arguments, the store root, or the exit code beyond a parse failure.
+- A transcript with no parsable turns stops the run (`exit 4`). Individual malformed JSONL lines are skipped.
+
+The realistic risk is not code execution but content. A handoff is a readable document that a later
+human or agent may treat as instructions, and it inherits whatever instructions the transcript
+contained. Review a handoff before handing it to another agent.
+
+## Paths and the workspace boundary
+
+The engine resolves `--source` against the current directory and writes under the resolved root. It
+performs no workspace-boundary check of its own: a path you pass is a path it uses.
+
+`permission-policy.json` declares the boundary for the runtime layer — approved workspaces,
+read-only system roots, personal-data roots, per-level grants (`READ_ONLY` and `WORKSPACE_WRITE`
+allowed; `EXTERNAL_EFFECT`, `DESTRUCTIVE` and `IRREVERSIBLE` need authorization) and the R0–R4 risk
+mapping. See [PERMISSIONS.md](PERMISSIONS.md). The handoff engine itself does not consult that file.
+
+## Guarantees that are not made
+
+- No sandboxing. No process isolation, no privilege separation. The tool runs with the permissions of the user who invoked it.
+- No encryption. Handoff files are plain text and JSON.
+- No authentication. Hashes are self-consistent, not signed — see [PROVENANCE.md](PROVENANCE.md).
+- No audit log and no system logging.
+- No secret scanning, no PII detection, no redaction.
+
+## Dependencies
+
+None. The engine and the runtime use only `node:` built-ins and require Node 18 or newer. The
+installer is a single script with no package dependencies.
+
+## Reporting a vulnerability
+
+Report it privately to the maintainer, not in a public issue. Use the repository's private
+vulnerability reporting if it is enabled, otherwise contact the maintainer directly. Include the
+command, the input, and the observed result.
+
+## Checklist before publishing a handoff folder
+
+- [ ] The transcript was reviewed and contains no credentials, tokens or personal data.
+- [ ] The handoff quotes no private path and no machine identifier.
+- [ ] `node tools/handoff.mjs verify <id-prefix>` passes for every session in the folder.

package/docs/SESSIONS.md

@@ -0,0 +1,97 @@
+---
+title: Session index
+---
+
+# Session index
+
+A handoff store is a directory of captured sessions. This page is generated from the
+sample store in [`examples/sessions/`](https://github.com/Alot1z/agent-handoff/tree/main/examples/sessions), whose sessions the
+engine built from the two transcripts this repository ships. Nothing here is written by hand:
+the table below is a rendering of that store, re-checked on every build.
+
+| Project | Session | Harness | Turns | Revision | Manifest sha256 | Integrity |
+|---|---|---|---:|---:|---|---|
+| demo | `typescript-project-setup` | claude-code | 11 | 1 | `141e232eb2ad…` | PASS |
+| smoke-test | `fixture-roundtrip` | codex | 2 | 1 | `a81d076e3334…` | PASS |
+
+**2 session(s) across 2 project(s): all verified.**
+
+## What each column proves
+
+| Column | Where it comes from |
+|---|---|
+| Project, Session | The store layout: `projects/<project>/<session>/` |
+| Harness | `harness` in the session manifest — what produced the transcript |
+| Turns | Lines in `timeline.jsonl`, checked against `turn_count` in the manifest |
+| Revision | `revisions` in the manifest. A rebuild that appends turns raises it; it never forks a session |
+| Manifest sha256 | `manifest_sha256`, the hash of the manifest with that field removed |
+| Integrity | `PASS` when the manifest hash matches, the turn count matches and `HANDOFF.llm.json` parses |
+
+## Verify a session yourself
+
+Point the engine at the sample store and ask it the same question this page answers:
+
+```bash
+# the store this page is rendered from
+HANDOFFS_ROOT=examples/sessions node tools/handoff.mjs list
+HANDOFFS_ROOT=examples/sessions node tools/handoff.mjs verify typescript-project-setup
+HANDOFFS_ROOT=examples/sessions node tools/handoff.mjs verify fixture-roundtrip
+
+# your own store
+HANDOFFS_ROOT=/path/to/your/store node tools/handoff.mjs list
+```
+
+`verify` exits non-zero the moment one of the three checks fails, so it works as a gate:
+
+```bash
+HANDOFFS_ROOT=examples/sessions node tools/handoff.mjs verify typescript-project-setup || echo "do not resume this session"
+```
+
+## Generate this page from your own store
+
+The generator is part of this repository, and it reads any store in the format above:
+
+```bash
+node .github/scripts/build-sessions-index.mjs --store examples/sessions --out docs/SESSIONS.md
+node .github/scripts/build-sessions-index.mjs --check    # exit 1 when the page is stale
+```
+
+`--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).
+- The commands that read and write a store are in [CLI.md](CLI.md).
+- What the hashes prove, and what they cannot, is in [PROVENANCE.md](PROVENANCE.md).

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,158 @@
+---
+title: Troubleshooting
+---
+
+# Troubleshooting
+
+Each entry names the symptom, the cause, and the fix. Exit codes are the ones documented in
+[CLI.md](CLI.md).
+
+## Nothing is listed
+
+**Symptom:** `handoff: no handoffs yet`.
+
+**Cause:** no build has run against the store being read, or the build wrote to a different
+store.
+
+**Fix:** check which store the engine resolved, and which rule chose it:
+
+```bash
+node tools/handoff.mjs config
+```
+
+The rule is one of `env`, `config`, `discover`, `default`. If it is not the store you
+expected, set `HANDOFFS_ROOT` for the run, or add a `handoff.config.json` at the project
+root. Resolution order is in [FORMAT.md](FORMAT.md#where-handoffs-live).
+
+## `build` exits 2
+
+**Cause:** `--source` was not given, or the value was consumed as another flag.
+
+**Fix:** `build` requires it:
+
+```bash
+node tools/handoff.mjs build --source transcript.jsonl --project my-project
+```
+
+## `build` exits 4 after reading the file
+
+**Cause:** no turn parsed. A `.jsonl` source is parsed one line at a time and a line that
+does not parse is skipped; a text source needs a line starting with `user:`, `human:`,
+`assistant:`, `ai:`, `system:` or `tool:`.
+
+**Fix:** inspect the first few lines of the source. If the transcript is JSONL but the fields
+are named differently, an adapter is what you want — see [ADAPTERS.md](https://github.com/Alot1z/agent-handoff/blob/main/refs/ADAPTERS.md)
+for the canonical shape, and [INTEGRATION.md](INTEGRATION.md) for mapping a new source onto
+it.
+
+## `verify` prints FAIL
+
+**Cause:** one of three things — the manifest was edited by hand after the build, the
+timeline line count no longer matches `turn_count`, or `HANDOFF.llm.json` does not parse.
+
+**Fix:** do not edit a handoff by hand. Rebuild from the same source:
+
+```bash
+node tools/handoff.mjs build --source <original source> --session <id>
+```
+
+A rebuild re-seals the manifest and rewrites the renders. If the original source is gone,
+the handoff cannot be re-verified, and the honest answer is to say so rather than patch the
+hash.
+
+## `show`, `verify`, `rename` or `retitle` exits 3 or 4
+
+**Cause:** 3 means the prefix matched more than one session; 4 means it matched none.
+
+**Fix:** run `handoff.mjs list`, then use a longer prefix.
+
+## `config` exits 2 and names a config file
+
+**Cause:** a `handoff.config.json` was found but is not valid against
+`handoff.config.schema.json`. The engine refuses to fall back to another store, because
+falling back would write somewhere other than the configured location.
+
+**Fix:** correct the file against the schema, or delete it to fall through to the
+`handoffs/` convention.
+
+## A runtime command exits 3 with "capture already in flight"
+
+**Cause:** another run holds the lock for that project and session. Locks are files in
+`<root>/.locks/`, named after a hash of the operation target.
+
+**Fix:** wait for the other run. If a previous process was killed abruptly, it can leave a
+lock file behind; the file is normally removed when the run finishes, so a lock that is
+still present after every process has stopped can be deleted by hand.
+
+## `dispatch` or `merge` produced something that fails the gate
+
+**Cause:** by design. A `merge` writes a timeline with no brief, no payload and no
+`TOOLS.md`, so `verify-gate` fails it on `payload` and `contract` until a brief is written
+for the merged session. `index` reports the same sessions as stale.
+
+**Fix:** write the brief for the merged session, then re-run `verify-gate`. A brief needs the
+seven contract fields — `RESULT`, `WHAT_CHANGED`, `VALIDATION`, `EVIDENCE`, `BLOCKERS`,
+`RISKS`, `FOLLOW_UP` — each starting a line.
+
+## `verify-gate` exits 0 but the verdict says REJECTED
+
+**Cause:** not a bug. `verify-gate` exits 0 for both verdicts so that "the gate ran" and
+"the gate passed" stay distinguishable. Read `ok` or `verdict` from the JSON.
+
+**Fix:** branch on the verdict in any script that calls it. The same applies to `promote`,
+which prints the gate result but stamps the manifest either way.
+
+## `promote` stamped a session that is not verified
+
+**Cause:** expected behaviour, and stated in the command reference. Promotion is a local
+stamp, not an enforcement.
+
+**Fix:** run `verify-gate` first and only call `promote` when the verdict is `VERIFIED`.
+
+## `capability-registry check` fails with `unknown`
+
+**Cause:** a capability declares a probe kind with no implementation, or declares no target
+or command for its kind. The registry reports `unknown` with the reason instead of guessing.
+
+**Fix:** read the evidence line for the capability. `unknown` for a required capability is
+treated as a failure on purpose: an unanswered question is not a pass.
+
+## `runtime-engine run` exits 3
+
+**Cause:** `DENIED`. An explicit denial, a personal-data path, an unknown risk class or an
+unknown grant all land here. A personal-data or denied target is refused at any risk class.
+
+**Fix:** inspect the decision before changing anything:
+
+```bash
+node tools/runtime-engine.mjs evaluate --risk R1 --target <path> --json
+```
+
+The policy itself is [permission-policy.json](https://github.com/Alot1z/agent-handoff/blob/main/permission-policy.json); read
+[PERMISSIONS.md](PERMISSIONS.md) for the levels.
+
+## `runtime-engine resume` exits 4
+
+**Cause:** there is no checkpoint to resume from, either because no job ran for that session
+or because the session name does not match. Exit 5 means a checkpoint exists but is corrupt
+or its integrity seal does not match.
+
+**Fix:** run `status` for the session to see the durable state, then start a new job.
+
+## The documentation site is missing a page, or a link 404s
+
+**Cause:** the site is built from `docs/`. A page not listed in `docs/_data/nav.yml` does not
+appear in the navigation, and a relative link that points at a file outside `docs/` does not
+resolve in the built site.
+
+**Fix:** add the page under `docs/`, add it to `nav.yml`, and run the check CI runs:
+
+```bash
+node .github/scripts/check-docs.mjs
+```
+
+## Node version
+
+The tools require Node.js 18 or newer and use only built-in modules. `node --version` below
+18 is the only unsupported configuration; there is no build step and no dependencies to
+reinstall. Platform notes are in [COMPATIBILITY.md](COMPATIBILITY.md).

package/docs/UNINSTALL.md

@@ -0,0 +1,148 @@
+---
+title: Uninstall
+---
+
+# Uninstall
+
+Uninstalling removes the skill files. Your handoffs and your configuration stay where they are.
+
+## Quick uninstall
+
+```bash
+npx agents-handoff --remove
+```
+
+Removal asks for confirmation first:
+
+```
+This will remove agents-handoff from:
+  <install-path>
+
+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)
+```
+
+Answer `y` to proceed. In a non-interactive shell the prompt is skipped and nothing is removed;
+the installer prints `Non-interactive mode, use --force to skip confirmation` instead.
+
+```bash
+npx agents-handoff --remove --force
+```
+
+## Options
+
+| Option | Effect |
+|---|---|
+| `--remove` | Remove the installation (interactive confirmation). |
+| `--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
+
+**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`, `README.md`, `LICENSE`, `skill.json`, the manifest JSON files
+- the install record: `.agents-handoff-install.json`
+- `schemas/`, `refs/`, `templates/`, `docs/`, `tests/`
+- 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
+
+Everything else in the directory — the installer prints the list at the end:
+
+```
+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
+
+Remove the skill files and leave the data behind:
+
+```bash
+cd "<install-path>"
+
+# 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 \
+      .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:
+
+```bash
+rm -rf "<install-path>"
+```
+
+Check where handoff data actually lives before doing that:
+
+```bash
+node "<install-path>/tools/handoff.mjs" config
+```
+
+`handoff: config root=<dir>` is the directory that holds your handoffs.
+
+## After uninstalling
+
+```bash
+npx agents-handoff --list
+```
+
+The removed location should no longer appear. Handoff data that was kept still exists on disk
+and can be read by a later installation, or by any tool that reads a handoff folder directly.
+
+## Troubleshooting
+
+| Symptom | Cause and fix |
+|---|---|
+| `Not installed at <dir>` | That location holds no installation. Check `--list` and `where`, then retry with the right `--location` or `--path`. |
+| 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. |
+| 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
+
+- [INSTALL.md](INSTALL.md)
+- [UPGRADE.md](UPGRADE.md)
+- [../README.md](https://github.com/Alot1z/agent-handoff/blob/main/README.md)