Say what an upgrade does not reach, and what to run about it

docs/COMPATIBILITY.md

@@ -97,6 +97,49 @@ What still holds: execution correctness is unaffected. A registration that works
 is verified normally, and one that is genuinely broken is still reported as
 unverified — a user is never told a broken registration is healthy.
 
+## After upgrading, run `doctor` (#693)
+
+An upgrade updates the CLI. It does not reach two things:
+
+- **Hooks already installed in a repository.** `commitlore hooks install` records
+  the exact bundle it ran from, which pins that repository to one release. The
+  installer cannot fix this for you — it has no way to know which repositories
+  have hooks.
+- **Sessions already running.** A host loads its runtime once and keeps it.
+
+So after installing a new version:
+
+```sh
+commitlore doctor
+```
+
+Two warnings are the ones to expect and act on:
+
+```
+runtime identity — hook identity differs from CLI: hook v<old>; CLI v<new>
+  fix: commitlore hooks install          # run it in that repository
+
+live MCP runtime identity — N live CommitLore MCP runtime(s) are unusable
+  restart those sessions                 # a host keeps the runtime it loaded
+```
+
+Neither is a defect in the release. Both are state a release cannot reach, and
+`doctor` naming them is the product doing what it can — which is to say what it
+knows rather than to guess that everything is current.
+
+### Why the hook records a version
+
+It is deliberate. The recorded path makes the hook independent of `PATH` and of
+whatever `node_modules/.bin/commitlore` sits above the repository, and the
+interpreter is recorded beside it because a hook runs where `PATH` may carry no
+`node` at all. A launcher that resolves through `PATH` would undo both — which
+was measured, not assumed: recording the `bin` wrapper made hooks fail under the
+restricted `PATH` a hook actually runs in.
+
+Making the recorded path version-free without losing those properties needs a
+stable directory the installer maintains, and that is tracked in #693 rather than
+improvised.
+
 ## Prerequisites
 
 Two columns, because **required** and **checked** are not the same claim. Only

docs/handoff/20260815-after-v1.md

@@ -75,6 +75,48 @@ That is the sharpest thing this release taught, and it is worth more than the
 issue count: **the suite starts from nothing every time, which is what makes it
 repeatable and what makes it blind.**
 
+## v1.0.1, and what the release itself taught
+
+v1.0.0 shipped and then three defects appeared that no test could have caught,
+all at the install boundary. Fixing them produced two more of the same kind. The
+whole set became v1.0.1:
+
+```
+#683  the release workflow failing on a release that already existed
+#684  hermes install refusing the config it wrote
+#687  the skills root taken from the running bundle, not --data-root
+#688  an installed plugin treated as a reason to stop rather than upgrade
+#690  claude-code wired by nothing, in neither hosts nor notDetected
+```
+
+The controls all inverted after v1.0.1: exit code 1 → 0, claude-code absent →
+installed healthy, plugin cache unmoved → new generation present, hermes failed →
+healthy, doctor unusable 4 → 2 (the remainder being sessions that predate the
+upgrade).
+
+**#688 alone did nothing.** It repaired a function nothing called; #690 is what
+made it reachable. Measured, not inferred — the cache still did not move after
+#688 landed.
+
+## One pattern, four times
+
+```
+.mcp.json             "commitlore"                    the wrapper → survived every upgrade
+Hermes external_dirs  .../v0.8.2/hermes/skills        versioned   → broke   (#686)
+plugin cache          a copy of the code              a copy      → stalled (#660)
+hook commitlore.bin   .../v0.8.2/dist/commitlore.mjs  versioned   → open    (#693)
+```
+
+The configuration that pinned nothing is the one that survived. Every other one
+needed a fix.
+
+#693 is the one still open, and the obvious repair is wrong: recording the `bin`
+wrapper makes hooks fail under the restricted `PATH` a hook runs in, because the
+wrapper is a shell script and `commitlore.node` exists precisely because `PATH`
+may carry no `node`. That was asserted in a PR, then disproved by CI. What it
+needs is a version-free path to a `.mjs`, which needs a directory the installer
+maintains — gated with #691.
+
 ## Traps this repository sets
 
 Each cost a cycle today.