agents-handoff 0.0.0-stage → 2.0.3

package/docs/FORMAT.md

@@ -0,0 +1,185 @@
+---
+title: Handoff format
+---
+
+# Handoff format
+
+One handoff is a directory of files generated from a session transcript. The source
+transcript is read, never written: every handoff file is a render of it, and the
+renders carry the digests that let you prove which source bytes produced them.
+
+Everything below describes the behaviour of `tools/handoff.mjs`.
+
+## Where handoffs live
+
+`tools/lib/handoff-root.mjs` is the single implementation of this order. First match wins:
+
+| Order | Source | Notes |
+|---|---|---|
+| 1 | `HANDOFFS_ROOT` | Environment override. Always wins. The test suite uses it to stay hermetic. |
+| 2 | `handoff.config.json` | Found by walking up from the current directory, at most 10 levels. `storage.path` beats `handoff_dir`; a relative `handoff_dir` resolves against the directory holding the config. |
+| 3 | `<dir>/handoffs/` | Zero-config convention, checked at each level of the same upward walk. |
+| 4 | the skill directory | Default store when no environment variable, config or `handoffs/` directory is found. |
+
+A `handoff.config.json` that is present but invalid fails the run with exit 2 instead of
+falling back, because falling back would write the session to a store other than the one
+that was configured. The schema for that file is `handoff.config.schema.json`.
+
+```
+node tools/handoff.mjs config
+```
+
+prints the resolved root, which rule chose it (`env`, `config`, `discover`, `default`),
+the config file used, the schema path, the configured project name and whether
+cross-project linking is enabled.
+
+## Directory layout
+
+```
+<root>/
+  INDEX.json                          index of every session, rewritten on each build
+  links/<other-project>.md            cross-project relation notes
+  projects/<project>/
+    PROJECT.md                        project file: one line per session
+    <session>/                        one handoff
+```
+
+A legacy layout — session directories directly under `<root>` — is migrated on the next
+build: any directory holding a `manifest.json` is moved to `projects/<project>/`, using the
+project recorded in its manifest.
+
+## Files in a session directory
+
+| File | Written by | Contents |
+|---|---|---|
+| `HANDOFF.md` | `build`, `retitle`, `rename` | Human render: objective, current state, open loops, the last 40 turns as a table, tool-call digest, where the other files are, provenance. |
+| `HANDOFF.summary.json` | `build`, `retitle`, `rename` | Compact machine payload, `schema_version` `2.0.0-summary`. Objective, `state_now` head (600 chars), open loops, counts, artifact names, provenance. |
+| `HANDOFF.llm.json` | `build`, `retitle`, `rename` | Full machine payload, `schema_version` `2.0.0`. The summary fields plus the complete `timeline[]` and `tool_calls[]` arrays, with the turn class stored as `class`. |
+| `timeline.jsonl` | `build` (append-only) | One JSON object per turn: `{seq, ts, class, text}`. New turns are appended; existing lines are never rewritten. |
+| `TOOLS.md` | `build` | Every tool turn in full, untruncated, as `## [seq] <ts>` sections. The table in `HANDOFF.md` is a 120-character digest of the same turns. |
+| `manifest.json` | `build`, `retitle`, `rename` | The record the other files are verified against. See below. |
+
+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 |
+|---|---|
+| `session` | Session id as resolved for this handoff. |
+| `project` | Project slug. |
+| `harness`, `model` | From `--harness` / `--model`, from the source's own fields, or `unknown` / `""`. |
+| `created_at`, `updated_at` | ISO 8601. `created_at` is set once on creation. |
+| `source_paths` | Every source path this session was ever built from. |
+| `watermark` | Highest `seq` already emitted. Turn `seq <= watermark` is already in `timeline.jsonl`. |
+| `raw_sha256` | SHA-256 of the source bytes at the last build. |
+| `revisions` | Number of writes. Increments on every build, `retitle` and `rename`. |
+| `turn_count` | Number of turns in `timeline.jsonl` after the build. |
+| `counts` | Turn counts by class: `USER`, `AGENT`, `THOUGHT`, `TOOL`. |
+| `manifest_sha256` | Self-hash: SHA-256 of the manifest JSON with this field removed. |
+| `prev_project` | Set when `rename` moves the session to another project. |
+| `titled_from` | Previous directory names, set by `retitle`. |
+
+## Turn classes
+
+`classify()` assigns each turn one class, in this order:
+
+| Class | Rule |
+|---|---|
+| `TOOL` | `kind` contains `tool`, or `role` is `tool`. |
+| `THOUGHT` | `kind` contains `reason` or `think`. |
+| `USER` | `role` is `user`, or `kind` is `human`. |
+| `AGENT` | `role` is `assistant`, or `kind` is `ai`. |
+| `OTHER` | Everything else. Kept in `timeline.jsonl`, omitted from the tables in `HANDOFF.md`. |
+
+Turn text is taken from `text`, then `content`, then `parts[].text`.
+
+## Accepted input
+
+A source file ending in `.jsonl` is read line by line. Each line is parsed
+independently; a line that does not parse, or whose text is blank, is skipped. `seq` is used
+when it is a finite number, and the line index otherwise.
+
+Any other extension is parsed as text: a line matching `user:`, `human:`, `assistant:`,
+`ai:`, `system:` or `tool:` (optionally prefixed with `#`) starts a turn, and following
+lines are appended to it. The role marker decides the class. Adapters that produce either
+shape are listed in [ADAPTERS.md](https://github.com/Alot1z/agent-handoff/blob/main/refs/ADAPTERS.md).
+
+If no turn parses, the build fails with exit 4.
+
+## Session id and directory name
+
+1. `--session <id>`, if given.
+2. else the `session` field of the first JSONL line, if present.
+3. else the source file name without its `.jsonl`, `.txt` or `.md` extension.
+
+The directory name replaces every character outside `[\w.-]` with `_`. `INDEX.json` is
+checked first: if a session with that id or with the same session UUID already exists, its
+project and directory name are reused, so a rebuild lands in the same place.
+
+`retitle <id-prefix> <new-name>` renames the directory to the slugified name, records the
+old name in `titled_from`, increments `revisions`, re-seals the manifest and refreshes every
+render. `rename <id-prefix> <new-project>` moves the session under another project and sets
+`prev_project`.
+
+## Revisions, watermark and idempotence
+
+Each build appends only the turns with `seq > watermark`, then sets `watermark` to the
+highest `seq` seen and increments `revisions`. A rebuild with no new turns and an unchanged
+`raw_sha256` prints `handoff: up-to-date` and writes nothing.
+
+## Provenance and verification
+
+| Value | Definition |
+|---|---|
+| `raw_sha256` | SHA-256 of the exact source bytes read. |
+| `manifest_sha256` | SHA-256 of the manifest with `manifest_sha256` removed. |
+| `provenance` block in both JSON payloads | `sources`, `raw_sha256`, `manifest_sha256`, `revision`, `watermark`, `total_turns`. |
+
+```
+node tools/handoff.mjs verify <id-prefix>
+```
+
+recomputes the manifest hash, requires `timeline.jsonl` to exist, compares its line count
+with `turn_count`, and parses `HANDOFF.llm.json`. It prints `PASS <id> [...]` and exits 0, or
+`FAIL <id>: ...` and exits 1. Exit 2 is a usage error, 3 an ambiguous prefix, 4 no match.
+
+## Payload schemas
+
+`schemas/handoff.schema.json` is the portable handoff payload contract, version `1.0`: a
+single JSON object with required keys `schema_version`, `handoff_id`, `mission_id`,
+`task_id`, `created_at`, `updated_at`, `source`, `state` and `next_action`, and optional
+blocks for capabilities, permissions, checkpoint, artifacts, evidence, decisions, errors and
+the next action.
+
+The engine does not emit that payload. Its own outputs are the session files listed above,
+and the JSON it writes is validated by consumption, not by that schema. The schema is the
+interchange contract for a consumer that wants a single structured document.

package/docs/INSTALL.md

@@ -0,0 +1,394 @@
+---
+title: Installation
+---
+
+# Installation
+
+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
+
+| Requirement | Notes |
+|---|---|
+| Node.js >= 18.0.0 | The engine uses ES modules and `node:fs`. |
+| `unzip` | Only needed to extract a release archive by hand. |
+| `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 --all      # every harness found on this machine
+```
+
+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
+```
+
+That prints the handoff root the engine will use:
+
+```
+handoff: config root=<dir>
+handoff: config source=default
+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
+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 `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 |
+
+An account-skill store keeps skills two identifier levels below the store itself:
+
+```
+<store>/<account-id>/<profile-id>/agents-handoff/
+```
+
+`<store>` is `%APPDATA%\<client>\account-skills` on Windows, and `~/.<client>/account-skills` or
+`~/.config/<client>/account-skills` on macOS and Linux, for whichever desktop client keeps
+skills there. The installer searches every store it can find and never assumes one of them.
+
+Inspect the decision before installing anything:
+
+```bash
+npx agents-handoff where
+```
+
+```
+Global install root: <dir>
+  chosen because: <reason>
+  override with: AGENT_HANDOFF_GLOBAL_DIR=<dir> or --path <dir>
+```
+
+`--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>/agents-handoff` |
+| `local` | `./local/skills/agents-handoff` |
+| `project` | `./skills/agents-handoff` |
+| `--path <dir>` | exactly `<dir>` |
+
+## Options
+
+| Option | Default | Effect |
+|---|---|---|
+| `--location <global\|local\|project>` | `global` | Which location to install, update, remove or verify. |
+| `--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`, `verify-package`/`--verify-package`, `list`/`--list`,
+`doctor`/`--doctor`.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `install`, `i` (default) | Copy the skill files to the target. |
+| `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
+
+```bash
+npx agents-handoff --verify
+```
+
+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;
+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 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
+`latest`: the installer reports the version already present, then stops. It tells you to use
+`--update` to upgrade, or `--force` to reinstall the same files.
+
+## Manual installation
+
+Use the release archive when you cannot run `npx`.
+
+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`.
+
+A complete installation contains `SKILL.md`, `skill.json`, the manifest JSON files,
+`tools/` (the engine and its runtime), `tools/lib/`, `schemas/`, `refs/`, `templates/`, `docs/`,
+and `tests/`. That list is not a description: it is the installer's manifest, and a run that
+cannot resolve any entry fails rather than reporting an incomplete installation as a success.
+
+## Handoff storage is separate
+
+Two environment variables decide two different things, and they are not interchangeable:
+
+| Variable | Decides |
+|---|---|
+| `AGENT_HANDOFF_GLOBAL_DIR` | Where the installer puts the skill. |
+| `HANDOFFS_ROOT` | Where the engine stores handoff data. |
+
+By default the engine stores handoff data under its own root, inside the installation. Set
+`HANDOFFS_ROOT` when you want handoffs somewhere else, for example in a versioned directory.
+
+## Troubleshooting
+
+| 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>` | `--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
+
+- [UPGRADE.md](UPGRADE.md)
+- [UNINSTALL.md](UNINSTALL.md)
+- [../README.md](https://github.com/Alot1z/agent-handoff/blob/main/README.md)