@tpsdev-ai/flair 0.29.0 → 0.31.0

package/docs/federation.md

@@ -81,15 +81,69 @@ flair federation pair https://<fabric-node>:19926/<instance-name> --token-from .
 
 Replace `<fabric-node>`, `<instance-name>`, and `<hub-admin-password>` with your actual values.
 
+Running the hub on Fabric has its own considerations — port derivation against a managed
+`443` endpoint, why the sync driver can only be installed on a machine you control, and
+the observability limits of a node you have no shell on. See
+[`docs/deploying-on-fabric.md`](deploying-on-fabric.md).
+
 ## Sync
 
-Push local changes to the hub:
+Push local changes to the hub, once:
 
 ```bash
 flair federation sync --admin-pass <password>
 # Output: ✅ Synced 12 records (0 skipped) in 145ms
 ```
 
+### Keeping it synced
+
+`flair federation sync` is one-shot and `flair federation watch` only runs
+while its terminal is open. Neither survives a logout, so a spoke that is only
+ever synced by hand looks paired but stops replicating — enable the scheduled
+driver instead:
+
+```bash
+flair federation sync enable                  # every 300s by default
+flair federation sync enable --interval 900   # or pick your own cadence
+flair federation sync status                  # is anything actually driving sync?
+flair federation sync disable
+```
+
+This installs a **periodic one-shot**: a launchd job (`StartInterval`) on
+macOS, a systemd user timer (`OnUnitActiveSec`) on Linux, each invoking
+`flair federation sync` on the interval. It is deliberately not a supervised
+long-lived watcher — the sync holds no state between runs, so a resident
+process would buy nothing, and a supervisor cannot restart a process that
+hangs rather than exits. The trade-off is latency, and `--interval` is the
+knob. The first sync runs immediately on enable.
+
+`flair federation watch` is unchanged and still the right tool for an
+interactive "watch it sync while I debug" session.
+
+**Credentials.** The scheduler never writes a password into a unit file. It
+stores the *path* given to `--admin-pass-file` (defaulting to
+`~/.flair/admin-pass` when that exists) and the CLI reads the file at run time,
+refusing it unless it is owner-only (`chmod 600`). Pass `--no-credentials` to
+wire none at all.
+
+### Is anything driving sync?
+
+`flair federation status` reports the driver alongside the peer table, because
+"no peer has merged in 24h" has two completely different causes:
+
+| What you see | What it means | What to do |
+|---|---|---|
+| `Sync driver: active` | A managed driver is loaded and syncs are landing | Nothing |
+| `Sync driver: active … but no peer contact in <window>` | Sync **is** running; the runs are not reaching the peer | `flair federation reachability`, then the driver log |
+| `Sync driver: NONE` | Nothing has run sync since you paired | `flair federation sync enable` |
+| `Sync driver: INSTALLED BUT NOT LOADED` | Unit files exist, the service manager never loaded them | `flair federation sync enable` |
+| `Sync driver: none managed by Flair — but syncs are landing` | A cron entry / hand-written unit is driving it | Nothing |
+
+The check is local to the machine running the CLI, so it is omitted when
+`--target` points at a remote instance.
+
+Driver logs: `~/.flair/logs/federation-sync.{stdout,stderr}.log`.
+
 ## Security
 
 ### Signed requests
@@ -125,10 +179,13 @@ Records with `updatedAt` more than 5 minutes in the future are rejected. This pr
 
 | Command | Description |
 |---------|-------------|
-| `flair federation status` | Show instance identity and peer connections |
+| `flair federation status` | Show instance identity, peer connections, and whether anything is driving sync |
 | `flair federation pair <hub-url> --token-from <file>` | Pair this spoke with a hub using a token triple file (or `-` for stdin) |
 | `flair federation sync` | Push local changes to the hub (one-shot) |
-| `flair federation watch [--interval <s>]` | Run sync in a foreground daemon loop (default 30s) |
+| `flair federation sync enable [--interval <s>] [--admin-pass-file <path>]` | Install the scheduled sync driver (launchd on macOS, systemd timer on Linux) |
+| `flair federation sync disable [--remove-shim]` | Remove the scheduled sync driver |
+| `flair federation sync status` | Show whether the driver is installed and genuinely active |
+| `flair federation watch [--interval <s>]` | Run sync in a foreground loop for an interactive session (default 30s) |
 | `flair federation reachability` | Probe local instance + each paired peer (read-only) |
 | `flair federation token [--ttl <min>]` | Generate a one-time pairing token triple (hub only) |
 
@@ -174,6 +231,6 @@ flair federation unpin <instanceId>
 ## Limitations (1.0)
 
 - **HTTP push only** — no persistent WebSocket connections or real-time sync
-- **Manual or watch-loop sync** — `flair federation sync` is one-shot; `flair federation watch --interval 30` runs it on a loop in a foreground daemon (wrap in launchd / systemd for production)
+- **Polled sync** — `flair federation sync enable` schedules a periodic one-shot (launchd / systemd, default 300s); there is no write-path trigger, so a new memory replicates on the next tick rather than immediately
 - **Single hub** — spoke-to-spoke sync goes through the hub
 - **Record-level LWW** — not field-level; concurrent edits to different fields of the same record may lose data

package/docs/integrations.md

@@ -24,6 +24,8 @@ Where Flair already runs. Each integration shown here is a working surface — t
 
 Don't see your harness? If it speaks **MCP** — Flair already works with `flair-mcp`. If it has a **custom memory protocol** like LangGraph's `BaseStore` or CrewAI's `RAGStorage`, an adapter is a ~200-line package; [open an issue](https://github.com/tpsdev-ai/flair/issues) or [send a PR](https://github.com/tpsdev-ai/flair).
 
+**Already running on Harper?** Every surface above reaches Flair over HTTP. If your application is itself a Harper app, you can skip the network entirely — load Flair as a component of the same instance and call its resources in-process. See [embedding-in-a-harper-app.md](embedding-in-a-harper-app.md), which also covers the table-vs-resource distinction that decides whether your memories are scoped.
+
 **Adjacent: memory bridges** — for moving memories between Flair and another memory product. Five bridges ship today (Mem0, ChatGPT exports, claude-project files, agentic-stack, markdown); see [bridges.md](bridges.md). Bridges are import/export plumbing, not live orchestrator integrations.
 
 ---
@@ -191,6 +193,7 @@ If it has a custom memory protocol, the adapter pattern is small (~200 lines). L
 ## See also
 
 - [Quickstart](quickstart.md) — `flair init` to working memory in 30 seconds
+- [Embedding in a Harper app](embedding-in-a-harper-app.md) — run Flair as a component of your own Harper instance and call it in-process
 - [Memory bridges](bridges.md) — import/export Flair ↔ Mem0, ChatGPT, claude-project, markdown, agentic-stack (five bridges shipped)
 - [Federation](federation.md) — pair instances peer-to-peer for cross-machine sync
 - [Supply-chain policy](supply-chain-policy.md) — what we do to keep this list of integrations safe

package/docs/mcp-clients.md

@@ -38,7 +38,9 @@ Flair runs as a local server at `http://127.0.0.1:19926` by default. The MCP ser
 
 Pick whichever you use. The MCP server is the same package; only the config syntax differs.
 
-> **Pin the version.** The snippets below use the bare package name for readability. `flair init` wires clients to a **pinned** spec (`@tpsdev-ai/flair-mcp@<version>`) on purpose: an unpinned reference re-resolves to whatever is currently published on every agent session, so any future publish reaches your machine silently. If you wire by hand, append the version you intend to run — `@tpsdev-ai/flair-mcp@0.28.0` — and bump it deliberately. `flair init` is the easier path and does this for you.
+> **Pin the version.** An unpinned `@tpsdev-ai/flair-mcp` re-resolves to whatever is currently published on *every* agent session, so any future publish reaches your machine silently, with no lockfile and no review step in the path. `flair init` wires clients to a **pinned** spec on purpose, and every MCP-server config snippet below is written the same way: `@tpsdev-ai/flair-mcp@<version>`.
+>
+> Replace `<version>` with the version you intend to run — the one you already have is `flair --version` — and bump it deliberately. Leaving the literal `<version>` in place fails loudly at `npx`, which is the intended failure: better than a config that looks pinned and isn't. `flair init` is the easier path and fills this in for you.
 
 ### Claude Code
 
@@ -47,14 +49,14 @@ The canonical approach is the `claude mcp add` CLI (writes to `~/.claude.json`):
 ```bash
 claude mcp add flair --scope user \
   -e FLAIR_AGENT_ID=my-project \
-  -- npx -y @tpsdev-ai/flair-mcp
+  -- npx -y @tpsdev-ai/flair-mcp@<version>
 ```
 
 Verify:
 
 ```bash
 claude mcp list
-# → flair (stdio, npx -y @tpsdev-ai/flair-mcp)
+# → flair (stdio, npx -y @tpsdev-ai/flair-mcp@<version>)
 ```
 
 Or, if you prefer the project-scoped `.mcp.json` checked into your repo:
@@ -64,7 +66,7 @@ Or, if you prefer the project-scoped `.mcp.json` checked into your repo:
   "mcpServers": {
     "flair": {
       "command": "npx",
-      "args": ["-y", "@tpsdev-ai/flair-mcp"],
+      "args": ["-y", "@tpsdev-ai/flair-mcp@<version>"],
       "env": {
         "FLAIR_AGENT_ID": "my-project"
       }
@@ -116,7 +118,14 @@ Or wire it by hand — add a `SessionStart` hook to `~/.claude/settings.json`:
 }
 ```
 
-Swap `me` for your `FLAIR_AGENT_ID`. The hook reads Claude Code's SessionStart
+Swap `me` for your `FLAIR_AGENT_ID`. Unlike the MCP-server snippets above, this
+one is shown **unpinned**, because that is what `flair hook install` writes and
+what the tooling recognises: `flair hook status` matches the exact unpinned
+command, so a hand-pinned hook reports `wired: false` there (while `flair
+doctor` still sees it). Pinning this line is therefore not yet supported —
+prefer `flair hook install`.
+
+The hook reads Claude Code's SessionStart
 payload on stdin, calls Flair's `bootstrap` (soul + relevant memories +
 predicted context, scoped to your project by the session's working directory),
 and emits it as `hookSpecificOutput.additionalContext` — which Claude Code
@@ -143,7 +152,7 @@ Edit `~/.gemini/settings.json` (create it if absent):
   "mcpServers": {
     "flair": {
       "command": "npx",
-      "args": ["-y", "@tpsdev-ai/flair-mcp"],
+      "args": ["-y", "@tpsdev-ai/flair-mcp@<version>"],
       "env": {
         "FLAIR_AGENT_ID": "my-project"
       }
@@ -165,7 +174,7 @@ Edit `~/.codex/config.toml` (create it if absent):
 ```toml
 [mcp_servers.flair]
 command = "npx"
-args = ["-y", "@tpsdev-ai/flair-mcp"]
+args = ["-y", "@tpsdev-ai/flair-mcp@<version>"]
 
 [mcp_servers.flair.env]
 FLAIR_AGENT_ID = "my-project"

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