@tpsdev-ai/flair 0.30.0 → 0.31.1

package/docs/quickstart.md

@@ -2,37 +2,50 @@
 
 From zero to a persistent agent memory in five minutes.
 
-## 0. Prerequisite
+## 0. Prerequisites
 
-**Node.js 22 or newer.** That's it — no Docker, no database to install, no API keys. Flair runs in a single process with embeddings computed locally.
+**Node.js 22 or newer.** No Docker, no database to install, no API keys — Flair runs in a single process and computes embeddings locally.
 
 ```bash
-node --version   # v22.x.x or higher
+node --version   # v22.x.x or newer
 ```
 
-If you need Node 22: [nodejs.org](https://nodejs.org/) or `brew install node@24`.
+Need it? [nodejs.org](https://nodejs.org/), `nvm install 22`, or `brew install node`.
 
-## 1. Install (30 seconds)
+**A user-writable npm global prefix.** Do not install Flair with `sudo`. A root-owned install cannot write the embedding model into its own package directory, and semantic search silently falls back to keyword-only matching. `nvm` gives you a user-owned prefix already; otherwise:
+
+```bash
+mkdir -p ~/.npm-global
+npm config set prefix ~/.npm-global
+export PATH="$HOME/.npm-global/bin:$PATH"   # add this to ~/.zshrc or ~/.bashrc
+```
+
+## 1. Install
 
 ```bash
 npm install -g @tpsdev-ai/flair
 ```
 
-`flair`, `flair-mcp`, and the client library all come in under one install.
+One install gives you `flair`, `flair-mcp` and the client library.
 
-## 2. Bootstrap Flair (1–2 minutes)
+## 2. Bootstrap Flair and register an agent
 
 ```bash
-flair init
+flair init --agent local
 ```
 
-First run does a few things:
+> **Pass `--agent`.** A bare `flair init` bootstraps the instance and stops there — it prints `✅ Flair initialized (no agent registered)` and creates no keypair, no soul, and no MCP wiring.
+
+First run does six things:
 
-1. Installs the embedded Harper (memory store) into `~/.flair/data/`.
-2. Downloads the local embedding model (~80 MB — first run only).
+1. Installs the embedded Harper memory store into `~/.flair/data/`.
+2. Downloads the local embedding model — about 80 MB, first run only.
 3. Starts Flair as a launchd / systemd service on port 19926.
-4. Creates a default agent (`--agent-id local` unless you pass one).
-5. Opens a short **soul wizard** so your agent knows who it is.
+4. Generates the agent's Ed25519 keypair in `~/.flair/keys/` and registers it.
+5. Wires every MCP client it detects — Claude Code, Cursor, Codex CLI, Gemini CLI — to `npx -y @tpsdev-ai/flair-mcp`, then smoke-tests it. `--no-mcp` skips this.
+6. Opens a short **soul wizard** so your agent knows who it is.
+
+It also generates a Harper admin password and writes it to `~/.flair/admin-pass` (mode 0600). The CLI prints that **path**, never the value — read the file when a command needs the password, and prefer `--admin-pass-file ~/.flair/admin-pass` over pasting it into a command line.
 
 The soul wizard offers a few shapes:
 
@@ -49,7 +62,7 @@ The soul wizard offers a few shapes:
      (s) Skip — set up later; `flair doctor` will nudge
 ```
 
-Pick the template that matches how you'll use this agent. You can edit or replace any entry later with `flair soul set`.
+Pick the template that matches how you'll use the agent. Edit or replace any entry later with `flair soul set`. The wizard is skipped automatically in a non-interactive shell, and by `--skip-soul`.
 
 ## 3. Confirm it's running
 
@@ -57,61 +70,68 @@ Pick the template that matches how you'll use this agent. You can edit or replac
 flair status
 ```
 
-A bare `flair status` (no agent, no admin credentials) only shows the public health
-summary:
-
 ```
-Flair vX.Y.Z — 🟢 running (PID 12345, uptime 1m)
-  URL:        http://127.0.0.1:19926
+Flair vX.Y.Z — ✓ running  PID 12345 · uptime 0m
+  URL            http://127.0.0.1:19926
 
-  ✓ all checks passing
-```
+Memory
+  Total          0
+  Durability     permanent:0 · persistent:0 · standard:0 · ephemeral:0
+  Archived       0
 
-The **🟢** icon means everything is healthy. A **🟡** would mean there's something worth looking at — usually surfaced with a recommended command inline. See [docs/troubleshooting.md](troubleshooting.md) if you see **🔴 unreachable**.
+Agents
+  Total          1 — local
 
-For the full picture — Memory, Agents, and Soul detail — pass the agent you just created:
+REM
+  Nightly        disabled
 
-```bash
-flair status --agent local
-```
+Federation  not configured
 
-```
-Flair vX.Y.Z — 🟢 running (PID 12345, uptime 1m)
-  URL:        http://127.0.0.1:19926
+Bridges  none installed
 
-Memory:
-  Total:       0
-  Durability:  0 permanent / 0 persistent / 0 standard / 0 ephemeral
-
-Agents:
-  1 total — local
-
-Soul:
-  3 entries — 0 critical / 0 high / 3 standard / 0 low
+Disk
+  Data           ~/.flair/data — 0 B
+  Snapshots      ~/.flair/snapshots — 0 B
 
   ✓ all checks passing
 ```
 
+You will also see a **Soul** section if you completed the wizard in step 2.
+
+`✓` means healthy. `⚠` means something is worth looking at, and the warning names the command that fixes it. For `✗ unreachable`, see [troubleshooting.md](troubleshooting.md).
+
 ## 4. Write your first memory
 
 ```bash
-flair memory add --agent local --content "Harper v5 sandbox blocks node:module but process.dlopen works"
+flair memory add --agent local "Harper v5 sandbox blocks node:module but process.dlopen works"
+```
+
+```json
+{
+  "id": "local-1785277247486",
+  "written": true,
+  "deduplicated": false
+}
 ```
 
-Flair generates a semantic embedding locally and stores it. No network calls.
+Flair embedded the text locally on write. No network calls.
 
 ## 5. Find it back by meaning
 
 ```bash
-flair memory search --agent local --q "native addon loading in sandboxed runtimes"
+flair search --agent local "native addon loading in sandboxed runtimes"
 ```
 
 ```
   Harper v5 sandbox blocks node:module but process.dlopen works
-  (2026-04-22 · memory · 67%)
+  ( 2026-07-28 · standard · 100% )
 ```
 
-**You searched for a concept, not the keywords.** The 67% is the semantic-similarity score.
+You searched for a concept, not the keywords. The line under each hit is its creation date, durability tier, and rank score.
+
+> The percentage is a **rank-fusion score, not a similarity**. It is normalized so the top result is always near 100%. Read it as ordering within these results, never as confidence that the match is good.
+
+Add `--explain` to see the ranking inputs, or `--limit`, `--tag`, `--since 7d` to narrow the search. `flair memory search` runs the same query but always prints raw JSON — use it when piping to a script.
 
 ## 6. Give your agent context on boot
 
@@ -119,35 +139,41 @@ flair memory search --agent local --q "native addon loading in sandboxed runtime
 flair bootstrap --agent local --max-tokens 2000
 ```
 
-This returns a formatted text block that includes the soul entries you just set plus recent/relevant memories. Paste that into any LLM session — Claude Code, Codex, Cursor, an Anthropic API call — to give the agent its identity + memory in one shot.
+```
+## Recent Context
+📝 Harper v5 sandbox blocks node:module but process.dlopen works (2026-07-28)
+✓ budget 20/2000 tokens (1%) · ✓ 1 included · ✓ 0 truncated
+```
+
+Soul entries and relevant memories, in one block sized to a token budget. Paste it into any LLM session — Claude Code, Codex, Cursor, an API call — to hand the agent its identity and memory in one shot.
 
-If you use Claude Code, add this to your `CLAUDE.md`:
+Using Claude Code? Add this to your `CLAUDE.md`:
 
 ```
 At the start of every session, run mcp__flair__bootstrap before responding.
 ```
 
-With the MCP server wired up (see the [integration section in README.md](../README.md#integration)), Claude Code runs bootstrap automatically on every new session.
+With the MCP server wired up — `flair init` does this automatically for every client it detects — Claude Code runs bootstrap on every new session. See the [integration section in README.md](../README.md#integration).
 
 ## What's next
 
 | You want to... | Go to |
 |----------------|-------|
 | Add more agents to the same instance | `flair agent add <id>` |
-| Let one agent read another's memories | `flair grant <from> <to>` ([docs/auth.md](auth.md)) |
-| Import memories from agentic-stack / Mem0 / etc. | [docs/bridges.md](bridges.md) |
-| Sync memories across machines | [docs/federation.md](federation.md) |
+| Keep a memory owner-only | `flair memory add --visibility private` — reads are otherwise open to every agent on the instance ([auth.md](auth.md)) |
+| Import memories from agentic-stack / Mem0 / etc. | [bridges.md](bridges.md) |
+| Sync memories across machines | [federation.md](federation.md) |
 | Integrate with OpenClaw, Claude Code, Cursor | [README.md#integration](../README.md#integration) |
-| Fix something that isn't working | [docs/troubleshooting.md](troubleshooting.md) |
-| Upgrade to a new version | `flair upgrade --restart` or [docs/upgrade.md](upgrade.md) |
+| Fix something that isn't working | `flair doctor`, then [troubleshooting.md](troubleshooting.md) |
+| Upgrade to a new version | `flair upgrade` (restarts automatically) or [upgrade.md](upgrade.md) |
 
 ## If you change your mind
 
 ```bash
-flair stop              # stop the service (keeps data)
+flair stop              # stop the service, keep data
 flair restart           # restart
-flair uninstall         # remove the service (keeps data + keys)
-flair uninstall --purge # remove everything including data and keys
+flair uninstall         # remove the service, keep data and keys
+flair uninstall --purge # remove everything, including data and keys
 ```
 
 All reversible. Your memories aren't locked in.

package/docs/releasing.md

@@ -5,9 +5,9 @@ Flair publishes eight workspace packages to npm under `@tpsdev-ai/*`. Releases a
 (no `NPM_TOKEN` lives anywhere) and submits each package to npm's **staging** area.
 A maintainer then approves the staged tarballs on npmjs.com with 2FA to make them live.
 
-> `flair-bench` is version-bumped and tagged in lockstep with the other 7, but stages
-> in its own step in CI (allowed to fail) until its one-time bootstrap is done — see
-> [flair-bench bootstrap](#flair-bench-bootstrap-one-time) below.
+> `flair-bench` is version-bumped and tagged in lockstep with the other 7, and stages in
+> its own step in CI for [historical reasons](#flair-bench-bootstrap-one-time-done). That
+> step is no longer allowed to fail: all eight packages must stage for a release to pass.
 
 ```
  merge release PR ──▶ push tag v0.11.0 ──▶ CI stages all packages ──▶ npm staging
@@ -29,13 +29,39 @@ the maintainer's 2FA approval.
 ### Phase 1 — open the release PR
 
 ```bash
-# promote ## Unreleased to the new version in CHANGELOG.md first, then:
 ./scripts/release.sh 0.11.0
 ```
 
-This bumps every workspace package to the version, aligns internal deps, refreshes
-`bun.lock`, builds, tests, and opens a `release: v0.11.0` PR. Review and merge it
-(CI green + K&S approval) the same as any other PR.
+This assembles the changelog, bumps every workspace package to the version, aligns
+internal deps, refreshes `bun.lock`, builds, tests, and opens a `release: v0.11.0` PR.
+Review and merge it (CI green + K&S approval) the same as any other PR.
+
+**Nothing about the version is bumped by hand.** The version is declared outside
+`package.json` too — `packages/flair-bench/src/version.ts` holds it as a `TOOL_VERSION`
+constant — and `release.sh` bumps every such site. It checks them *before* creating the
+branch, so an out-of-sync tree aborts while nothing has been touched, and again after the
+bump so a missed site can't be committed. The same check runs in CI
+(`node scripts/check-version-sync.mjs`) and fails on any file outside the known set that
+declares the release version, so a new version-bearing file is caught on the PR that adds
+it. If you ever find yourself editing a version constant by hand during a release, that is
+a bug in the script — add the file to `SOURCE_VERSION_FILES` in
+`scripts/check-version-sync.mjs` and to the `git add` list in `scripts/release.sh`.
+
+**The changelog is assembled, not hand-promoted.** Entries land during development as one
+file per change under `.changelog/unreleased/` (flair#835 — a shared `[Unreleased]` block
+conflicted on every concurrent PR, and resolving a conflict dismisses approvals). The
+release script runs:
+
+```bash
+node scripts/changelog-fragments.mjs promote 0.11.0
+```
+
+which writes a `## [0.11.0] - <date>` section from the fragments — Keep a Changelog category
+order, filename order within a category, entry bodies copied verbatim — and deletes the
+fragment files. Released history above it is not touched. It **refuses** to run when the
+fragment directory is empty (nothing to release) or when someone hand-wrote an entry into
+`## [Unreleased]` that the step would otherwise silently overwrite. Preview any time with
+`node scripts/changelog-fragments.mjs render`.
 
 ### Phase 2 — tag the release
 
@@ -51,9 +77,10 @@ workflow, which:
 
 1. Resolves the version from the tag and validates it as semver.
 2. Verifies the tagged commit is an ancestor of `main` (a tag can't ship un-merged code).
-3. Verifies all 7 `package.json` files are at that version.
+3. Verifies all 8 `package.json` files are at that version.
 4. Builds every package.
-5. Runs `npm stage publish` for each package in dependency order (flair-client first).
+5. Runs `npm stage publish` for each package in dependency order (flair-client first),
+   then `flair-bench` in its own step. Any one of the eight failing fails the release.
 
 It authenticates via OIDC — no secrets, and it does **not** create or move any tag (the
 tag you pushed is the trigger). Watch the run; when it's green, the packages are staged
@@ -66,7 +93,8 @@ by `scripts/changelog-extract.mjs`). It is idempotent: re-running the workflow o
 re-pushing the tag updates the existing release rather than failing. The GitHub release
 documents the tagged commit immediately; it does not wait on the npm 2FA gate. If the
 CHANGELOG has no section for the version, this job fails loudly rather than cutting an
-empty release — so always promote `## [Unreleased]` to `## [X.Y.Z]` in the release PR.
+empty release — which is why phase 1's fragment assembly refuses to produce an empty
+section rather than letting the failure surface here, after the tag is already pushed.
 
 > `workflow_dispatch` with a `version` input remains as a manual fallback (needs
 > `Actions: write`), but the tag push is the normal path.
@@ -82,10 +110,9 @@ npm stage view <stage-id> # inspect one
 npm stage approve <stage-id>   # 2FA prompt; package goes live
 ```
 
-There are seven lockstep-staged packages, so seven approvals (the web UI lists them on
+There are eight lockstep-staged packages, so eight approvals (the web UI lists them on
 one page). Approve in dependency order if installing immediately — flair-client before
-its dependents — though staging does not itself resolve dependencies. `flair-bench`
-stages separately and only appears here once its bootstrap (below) is done.
+its dependents — though staging does not itself resolve dependencies.
 
 Verify when done:
 
@@ -99,7 +126,7 @@ These are configured once and reused for every release.
 
 ### npm trusted publisher (per package)
 
-For **each** of the seven packages, on npmjs.com → the package → **Settings → Trusted
+For **each** of the eight packages, on npmjs.com → the package → **Settings → Trusted
 Publisher → Add**:
 
 | Field           | Value                       |
@@ -116,32 +143,39 @@ CI/OIDC identity from publishing anything live directly — the only path to liv
 human 2FA approval of a staged package.
 
 Packages: `flair-client`, `flair-mcp`, `flair`, `openclaw-flair`, `pi-flair`,
-`n8n-nodes-flair`, `langgraph-flair`.
+`n8n-nodes-flair`, `langgraph-flair`, `flair-bench`.
 
 > A package must already exist on npm before a trusted publisher can be added — all
-> seven already do. This account-level config can only be done by an npm org owner.
-> `flair-bench` doesn't exist on npm yet (verified via `npm view @tpsdev-ai/flair-bench`
-> → 404 as of 2026-07-13) so it can't have a Trusted Publisher yet either — see below.
-
-### `flair-bench` bootstrap (one-time)
-
-`flair-bench` (added 2026-07-12, flair#702) is wired into the version-bump/tag flow
-(`scripts/release.sh`, `release-publish.yml`'s version-check) alongside the other 7, but
-`npm stage publish` categorically requires the package already exist on the npm registry
-(`npm help stage`: "Package must exist"), and a Trusted Publisher can only be registered
-for a package that already exists — chicken-and-egg for a brand-new package. Until an npm
-org owner does this once, the workflow's dedicated "Stage-publish flair-bench" step is
-expected to fail (it's `continue-on-error: true` so it doesn't block the other 7):
-
-1. From a machine logged into npm with 2FA: `cd packages/flair-bench && npm run build &&
-   npm publish --access public` — one normal (non-staged) publish to create the package
-   on the registry. Any valid semver works; the very next lockstep release will bump it
-   to match the other 7 automatically (it's in `scripts/release.sh`'s `PACKAGES` array).
-2. Add the Trusted Publisher for `@tpsdev-ai/flair-bench` using the same table as the
-   other 7 above (org=`tpsdev-ai`, repo=`flair`, workflow=`release-publish.yml`,
-   environment=`release`, allowed=`npm stage publish` only).
-3. Remove `continue-on-error: true` from the "Stage-publish flair-bench" step in
-   `release-publish.yml` once a tag push has staged it successfully.
+> eight already do. This account-level config can only be done by an npm org owner.
+
+### `flair-bench` bootstrap (one-time, done)
+
+**Nothing to do here.** This section is kept because the next brand-new package added to
+the release set will hit the same wall, and because it explains why `flair-bench` still
+stages in its own workflow step.
+
+`flair-bench` (added 2026-07-12, flair#702) was wired into the version-bump/tag flow
+(`scripts/release.sh`, `release-publish.yml`'s version-check) alongside the other 7 before
+it existed on npm at all. That is a chicken-and-egg: `npm stage publish` categorically
+requires the package to already exist on the registry (`npm help stage`: "Package must
+exist"), and a Trusted Publisher can only be registered for a package that already exists.
+So the workflow gave it a dedicated "Stage-publish flair-bench" step marked
+`continue-on-error: true`, letting the expected failure pass without blocking the other 7,
+and an npm org owner broke the cycle once:
+
+1. One normal (non-staged) `npm publish --access public` from a machine logged into npm
+   with 2FA, to create the package on the registry. Any valid semver works — the next
+   lockstep release bumps it to match the other 7 automatically.
+2. Add its Trusted Publisher using the same table as the other packages above.
+
+Both are done, and the step staged `@tpsdev-ai/flair-bench` successfully at v0.30.0, so
+`continue-on-error` has been **removed**: a flair-bench staging failure now fails the
+release like any other package's.
+
+> Why it mattered to go back and remove it: `continue-on-error: true` makes a step report
+> `conclusion: success` even when it failed. While it was set, a green run was not evidence
+> that flair-bench had staged — the only way to know was to read the raw log. A justified
+> exception outlives the condition that justified it unless someone returns for it.
 
 ### GitHub `release` environment
 

package/docs/supply-chain-policy.md

@@ -41,6 +41,9 @@ Override per-run via `FLAIR_DEP_KEEP_CURRENT="pkg1,pkg2,@scope/pkg3"` env (addit
 Every `dependencies` entry in any `package.json` must be a single concrete version (`"5.0.9"`), not a range (`"^5.0"`, `"~5.0.9"`, `">=5"`). Range specifiers expose us to silent supply-chain swaps every install — exactly the surface attackers exploit.
 
 - `peerDependencies` may use ranges (host-provided; never installed by us). `devDependencies` are also exact-pinned for build reproducibility, though they don't ship in our published tarballs.
+- **Flair declares no optional peers today**, and no `optionalDependencies` at all. If either is ever proposed as an install-weight fix, the mechanism has now been measured twice (`@harperfast/oauth` flair#750, `node-llama-cpp` flair#887) and the result is counter-intuitive enough to be worth stating: **only `peerDependencies` + `peerDependenciesMeta.optional` is skipped by a default install** (npm and bun alike). A plain `optionalDependencies` entry *is* still installed by default — "optional" there means "a failed install is non-fatal", not "skipped" — so it buys no install-weight reduction whatsoever. Exact-pinning an optional peer (rather than ranging it) is also legitimate where the consuming code path is version-sensitive, so that an operator who installs a different version gets told the version they have is not the version that was tested.
+
+  Note the corollary, measured during flair#893: an optional peer that is simply *absent* installs silently — npm prints no warning at all — so it cannot be relied on to prompt anyone to install it. Anything a user must install for a feature to work needs to be documented, or detected and reported at runtime.
 - `bun.lock` is committed and frozen-lockfile installed in CI. Any unintended dep drift fails the workspace-deps consistency gate.
 - Pin updates happen via deliberate, test-gated PRs — never auto-merged. **Renovate is enabled** (`.github/renovate.json`) to *propose* these updates on a schedule, but it respects the bake-time cooldown (`minimumReleaseAge: "7 days"`, matching `FLAIR_DEP_MIN_AGE_DAYS`) and opens PRs only — `automerge` is off, so every bump flows through the full test suite + K&S review. Renovate uses `rangeStrategy: "pin"` so it proposes exact-version bumps (never re-widens to ranges) and shares the keep-current allow-list with `check-dep-ages.mjs`. Vulnerability alerts bypass the cooldown so security fixes aren't delayed.
 
@@ -69,6 +72,39 @@ Only Nathan publishes to npm (per the existing MFA boundary). Flint preps the re
 - The build host is not logged into npm by design.
 - A planned post-publish smoke job will add an automated round-trip check after each publish to ensure cross-package resolution works on the actually-published artifacts.
 
+### 7. Dependency audit gate: blocking, with dated exceptions
+
+`bun audit` runs on every PR via the `audit` job and **blocks merge**. Every advisory it reports must either be fixed or appear in `.github/audit-allowlist.json`. There is no third option and no global escape hatch.
+
+This replaced a step that could not fail:
+
+```yaml
+run: bun audit || echo "::warning::Audit found vulnerabilities — all in harper transitive deps (unreleased v5 build)"
+continue-on-error: true
+```
+
+Both mechanisms independently forced a pass (`|| echo` made the shell exit 0, so `continue-on-error` was dead config that never even fired). The justification was accurate the day it was written. It carried **no expiry**, so it outlived its reason — by the time it was removed, "all in harper transitive deps" was false, and a critical advisory was reaching users through a first-party workspace package while the gate reported green.
+
+**The defect was the unexpirable exception, not the exception.** Some advisories genuinely cannot be fixed from this repo. So each one is now enumerated with:
+
+| field | meaning |
+|---|---|
+| `ghsa` | the published advisory id |
+| `package`, `severity` | re-verified against `bun audit` on every run; drift fails the gate |
+| `class` | `no-patch-published`, `vendor-pinned`, or `remediation-available` |
+| `introducedBy` | the dependency edge that pulls it in |
+| `reason` | why it cannot be fixed here, specifically |
+| `added`, `expires` | hard dates; lifetime is capped by severity |
+| `removeWhen` | the concrete condition that retires the entry |
+
+`scripts/audit-gate.mjs` fails the build on: an unlisted advisory, a malformed entry, an entry parked beyond its severity cap (critical 30 days, high 60, moderate/low 180), an **expired** entry, a **stale** entry whose advisory no longer appears, or a `no-patch-published` entry for which a patched version has since shipped. That last pair matters — an allowlist that only ever grows is the same failure with more ceremony.
+
+When an entry expires the build fails and a human re-decides. **That is the mechanism working, not a flaw.** Re-dating an entry without re-reading its reason is how this file rots back into the thing it replaced.
+
+Run it locally with `node scripts/audit-gate.mjs --explain`.
+
+**Standing rule for every check in this repo:** any check that is advisory-only must carry, in a comment at its own definition, what would make it blocking and when that gets re-evaluated. Advisory is a terminating state with a defined promotion event, never a resting place.
+
 ---
 
 ## Automation

package/docs/troubleshooting.md

@@ -173,6 +173,30 @@ flair doctor    # check for issues
 
 **Fix:** Either rephrase the content to avoid injection patterns, or switch to default mode (remove `FLAIR_CONTENT_SAFETY=strict` from environment). In default mode, flagged content is stored but tagged — not rejected.
 
+### "no writable migration data directory" / migrations reported failed
+
+**Symptoms:** `flair doctor` reports every migration `failed` with a "no writable migration data directory" reason, and the instance log carries a matching `[flair-migrations]` line naming each path it tried.
+
+**Cause:** flair keeps its migration bookkeeping (`.migrations/state.json`, the single-flight lock, and risk-scoped snapshots) in a directory alongside the instance's data — by default `~/.flair/data`, falling back to Harper's root path. On a provisioned install (a service-managed unit, a container, a component deployment) the account the process runs as may have a home directory it cannot write to, and if none of the candidates is usable there is nowhere safe to snapshot before a migration writes.
+
+**Fix:** point `FLAIR_MIGRATION_DATA_DIR` at a writable directory and restart, or make one of the paths named in the error writable by the account the instance runs as:
+
+```bash
+export FLAIR_MIGRATION_DATA_DIR=/var/lib/flair   # add to the service unit / launch script to persist
+flair restart
+flair doctor                                     # migrations should now report completed
+```
+
+Migrations are boot-keyed, so the next start runs the cycle and clears the finding. Nothing is lost while this is unresolved — a migration that cannot snapshot refuses to run rather than writing unprotected.
+
+### "Migration boot cycle never fired on this instance"
+
+**Symptoms:** `flair doctor` reports the boot cycle never fired, and `/HealthDetail` shows `migrations.cyclePhase: "idle"`.
+
+**Cause:** the trigger that schedules the migration cycle registers itself at boot, so `idle` means the running build's `dist/resources/migration-boot.js` never loaded — usually a partial or interrupted install rather than a runtime failure.
+
+**Fix:** reinstall flair (`npm install -g @tpsdev-ai/flair`) and restart, then check the instance log for `[flair-migrations]` lines, which name any error raised while the trigger was loading.
+
 ## Getting Help
 
 ```bash

package/docs/upgrade.md

@@ -50,13 +50,25 @@ actually running:
   stage the new packages without bouncing the process yet (the old
   opt-in `--restart` flag still parses but is now a no-op — restart is the
   default).
+- **The restart runs through the newly installed CLI** (flair#905), not the
+  process that did the installing. Only version N's own code knows how version
+  N starts — spawn arguments, required environment, config templates and the
+  Harper dependency's own package name are all things a release may change, and
+  the pre-swap process would get every one of them wrong the same silent way.
+  The output names the CLI it handed the restart to. If that CLI can't be found
+  or its version can't be confirmed, the upgrade says so and restarts in-process
+  rather than refusing to start anything.
 - **Post-restart verification** (skip with `--no-verify`) confirms the
   restarted instance answers `/Health`, that an authenticated request
   round-trips, and that the reported running version matches what was just
   installed.
-- **On verification failure**, `flair upgrade` automatically reinstalls the
-  previously-running `@tpsdev-ai/flair` version, restarts again, and
-  re-verifies — then exits nonzero with a clear report of what failed. If the
+- **On a failed restart OR a failed verification**, `flair upgrade`
+  automatically reinstalls the previously-running `@tpsdev-ai/flair` version,
+  restarts again, and re-verifies — then exits nonzero with a clear report of
+  what failed. Until flair#905 the rollback was wired to the *verification* leg
+  only: an upgrade that installed new packages and then failed to start them
+  exited 1 and left the operator on the new version with nothing running, which
+  is the single outcome this transaction exists to prevent. If the
   rollback itself fails verification, it says so loudly and points at the
   concrete pre-upgrade snapshot path (see "Pre-upgrade snapshot" below)
   instead of retrying in a loop — see [Downgrade](#downgrade) for the
@@ -176,7 +188,7 @@ FABRIC_USER=<admin> FABRIC_PASSWORD=<pass> \
 
 (or `--fabric-password-file <path>` instead of the `FABRIC_PASSWORD` env var — reads the
 password from a file, chmod 600). This resolves the target version (latest published
-`@tpsdev-ai/flair`, or pin one with `--version`), stages a clean deployable with the
+`@tpsdev-ai/flair`, or pin one with `--flair-version`), stages a clean deployable with the
 required `harper` version pin applied (`--harper-version` to override),
 confirms the staged Harper build before deploying, then reuses `flair deploy` to push it
 and verifies the result. `--check` shows the version diff and plan without deploying
@@ -233,6 +245,56 @@ dropped, never shown green. The sweep also needs Basic-auth credentials
 `--fabric-user`/`--fabric-password`) to authenticate each peer probe; a token-only
 (`--fabric-token`) deploy skips it with a note instead of a silent no-op.
 
+### Peer-replication errors are not verdicts
+
+Harper replicates a deployed component to its cluster peers **asynchronously**, so
+`harper deploy` can exit non-zero with
+
+```
+Component 'flair' was deployed on the origin node but failed to replicate to 1 of 1
+peer node(s): <peer> (Error: Connection closed 1006)
+```
+
+for a deploy that then converges on its own moments later. That error describes one
+instant, not an outcome.
+
+Both `flair deploy` and `flair upgrade --target` therefore **check before they
+declare**. On that error the CLI reads the peer node names out of Harper's own
+message, polls each node's component file tree (`get_components` — path, size and
+mtime), and compares it against the origin's. If every named peer converged, the
+deploy is reported as a **success**, with a line saying that Harper's error resolved:
+
+```
+⚠ harper reported a peer-replication failure, but every named peer node's component
+  tree matched the origin when checked afterwards — replication converged on its own.
+```
+
+Convergence is only ever claimed on positive evidence. A peer whose name is not an
+addressable host, whose hostname does not resolve, which cannot be reached, which
+reports no such component, or which currently resolves to the *same address as the
+deploy target* (a Fabric cluster endpoint is steered to one member node, so that
+comparison would be a node against itself) is reported as unverified — never as
+converged.
+
+| Flag | Effect |
+|------|--------|
+| `--convergence-timeout <ms>` | How long to wait for replication to converge before reporting failure (default `180000`) |
+| `--no-convergence-check` | Skip the poll and fail on Harper's error verbatim |
+| `--ignore-replication-errors` | Accept an origin-only deploy when replication has not converged; the peer catches up via federation sync or a later deploy |
+| `--deploy-retries <n>` | Retry the full deploy when replication is *observed* not to have converged (default `0`) |
+
+**`--deploy-retries` defaults to `0`, deliberately.** A retry re-runs the whole
+deploy, including Harper's own `npm install` into the component directory on every
+node, and a real upgrade died that way — `ENOTEMPTY` on a native module, on the
+*retry*, for a deploy whose peers had already converged. Retrying was compensating
+for the absence of a convergence check; the poll above covers that window without
+touching the cluster. When retries are enabled they are gated twice: only on
+positively observed non-convergence, and only once the origin's component tree has
+stopped changing across consecutive reads. If a retry does still fail differently
+from the original error, the CLI reports the **original** failure as the headline and
+labels the later one as a consequence of retrying — a retry can never change what the
+failure is reported to be.
+
 ## Re-embedding after an upgrade
 
 Two situations require a re-embed pass, and `flair doctor` will flag both:
@@ -345,6 +407,39 @@ reason as above: the restart is performed by the *old*, already-installed CLI.
 - If you already hit it (upgrade "finished" but the server is down): run
   `flair start` — not `restart` — and you're on the new version. Nothing was lost.
 
+### Known issue — upgrading *from* 0.29.0 stops with a false "Harper binary not found"
+
+0.30.0 renamed its Harper dependency from `@harperfast/harper` to the bare
+`harper` package (flair#870, a real ~104 MB saving — the two names are the same
+engine and no package manager can dedupe across them). `flair upgrade` replaces
+the package tree *while the CLI is executing out of it*, and 0.29.0's restart
+step only ever probes the old name — so once the swap lands, the name it is
+looking for is genuinely gone:
+
+```
+Restarting Flair...
+Stopping...
+Starting...
+❌ restart failed: Harper binary not found. Run 'flair init' first.
+   Flair may be partially down. Check: flair doctor
+```
+
+The error is false twice over. The install is complete and Harper is present
+under its new name; and `flair init` is the wrong remedy — on an initialised
+instance it is not what you want to reach for, and it could not have fixed a
+missing binary anyway.
+
+**Workaround when upgrading from 0.29.0:** run `flair start`. The new version is
+installed and correct; only the old CLI's restart step failed. `flair status`
+should then report 0.30.0 and healthy. Nothing was lost — the upgrade never
+touches `~/.flair/data`.
+
+Forward-only, for the same reason as the two issues above: the code that
+performs the restart is the version you are upgrading *from*. From flair#905
+onward the restart is handed to the newly installed CLI and the Harper package
+name is read from the post-swap `package.json` instead of being compiled in, so
+a future dependency rename cannot reproduce it.
+
 ## Downgrade
 
 Rolling back the **package** (above) assumes the data on disk is fine — only the new

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.30.0",
+  "version": "0.31.1",
   "packageManager": "bun@1.3.10",
   "description": "Identity, memory, and soul for AI agents. Cryptographic identity (Ed25519), semantic memory with local embeddings, and persistent personality — all in a single process.",
   "type": "module",
@@ -63,19 +63,9 @@
     "harper-fabric-embeddings": "^0.5.0",
     "jose": "6.2.2",
     "js-yaml": "4.3.0",
-    "node-llama-cpp": "3.18.1",
     "tar": "7.5.20",
     "tweetnacl": "1.0.3"
   },
-  "optionalDependencies": {
-    "@node-llama-cpp/linux-arm64": "3.18.1",
-    "@node-llama-cpp/linux-armv7l": "3.18.1",
-    "@node-llama-cpp/linux-x64": "3.18.1",
-    "@node-llama-cpp/mac-arm64-metal": "3.18.1",
-    "@node-llama-cpp/mac-x64": "3.18.1",
-    "@node-llama-cpp/win-arm64": "3.18.1",
-    "@node-llama-cpp/win-x64": "3.18.1"
-  },
   "overrides": {
     "react-native-fs": "npm:empty-npm-package@1.0.0"
   },