@tpsdev-ai/flair 0.26.0 → 0.27.0

package/docs/notes/mcp-oauth-model2.md

@@ -0,0 +1,132 @@
+# Native /mcp OAuth surface — Model 2 (experimental, default-OFF)
+
+> **Status: experimental, opt-in, DEFAULT-OFF.** Gated behind `FLAIR_MCP_OAUTH`.
+> When the flag is unset, flair boots byte-identically to before — no `/mcp`
+> route, no authorization-server load, no change to the default auth chain.
+> Do NOT enable in production until Sherlock signs off on live enablement.
+
+This is the **Model 2** native-MCP path: a custom in-process `/mcp` JSON-RPC
+handler guarded by `@harperfast/oauth`'s `withMCPAuth`, serving the 9 curated
+flair tools with a per-agent OAuth identity. It is distinct from the
+native-application-MCP surface (design A / `FLAIR_MCP_ENABLED`); Model 2 does not
+use Harper's native MCP transport, so it is not blocked by the Harper native-MCP
+gating gaps.
+
+## What it is
+
+- `resources/mcp-handler.ts` — a minimal MCP (JSON-RPC 2.0) handler over
+  Streamable HTTP: `initialize` / `tools/list` / `tools/call` / `ping`. On
+  `tools/call` it resolves the verified token `sub` → a flair `Agent`, then
+  dispatches to the curated tool.
+- `resources/mcp-tools.ts` — the 9 curated tools (memory_search, memory_store,
+  memory_get, memory_delete, bootstrap, soul_set, soul_get, flair_workspace_set,
+  flair_orgevent), each a thin wrapper over the existing resource handler
+  (Memory / SemanticSearch / BootstrapMemories / Soul / WorkspaceState /
+  OrgEvent). No raw CRUD surface — the only path to the datastore through `/mcp`
+  is one of these 9 semantic tools. Curated **by construction**.
+- `resources/mcp-oauth.ts` — registers `server.http(withMCPAuth(mcpHandler),
+  { urlPath: '/mcp' })` **only when `FLAIR_MCP_OAUTH` is on.** `/mcp` runs on its
+  own dispatch chain; flair's default auth-middleware does not run for it.
+- `resources/mcp-oauth-flag.ts` — the flag + issuer/resource config helpers.
+
+## The sub → Agent mapping (identity)
+
+`withMCPAuth` verifies the RS256 JWT and sets `request.mcp = { sub, client_id,
+aud, scope }`. The handler maps `sub` → a flair `Agent` id:
+
+1. Look up `Credential` where `kind === "idp"` AND `idpSubject === sub` → its
+   `principalId` is the Agent id. (Same credential surface XAA's ID-JAG path
+   uses — one identity model.)
+2. If no mapping and `FLAIR_MCP_JIT_PROVISION` is on, JIT-provision a
+   non-admin `Agent` + `Credential(kind:"idp")` from the sub.
+3. Otherwise **deny** — an unresolvable sub never runs as anonymous or admin.
+
+The resolved agent is set as `request.tpsAgent` on a flair-shaped delegation
+context, so the wrapped handler scopes to the verified agent exactly as an
+Ed25519-signed REST call would. Identity always comes from the resolved agent,
+never from the tool arguments (no forging of agentId / authorId).
+
+## Enabling (operator checklist)
+
+1. **Install the AS plugin** — add `@harperfast/oauth` (already an exact-pinned
+   dependency) and declare it in `config.yaml`:
+
+   ```yaml
+   '@harperfast/oauth':
+     package: '@harperfast/oauth'
+     providers:
+       github:
+         clientId: ${OAUTH_GITHUB_CLIENT_ID}
+         clientSecret: ${OAUTH_GITHUB_CLIENT_SECRET}
+     mcp:
+       enabled: true
+       issuer: ${FLAIR_MCP_ISSUER}          # pin to your public origin — REQUIRED
+       resource: ${FLAIR_MCP_ISSUER}/mcp     # RFC-8707 audience the /mcp token binds to
+       accessTokenTtl: 900                    # 5–15 min (Sherlock req 1) — short-lived
+       dynamicClientRegistration:
+         enabled: false                       # DCR is NOT SUPPORTED (flair#756) — explicit, not omitted (an absent block leaves DCR OPEN by the plugin's own default)
+       clientIdMetadataDocuments:
+         allowedHosts:                        # CIMD is the only supported client-registration path
+           - claude.ai
+           - claude.com
+       signingKeyPem: ${FLAIR_MCP_SIGNING_KEY_PEM}    # pin in clusters
+   ```
+
+   **DCR is not supported; clients connect via CIMD (Client ID Metadata
+   Documents).** `flair mcp enable` (flair#756) writes exactly this shape —
+   see "Legacy clients" below.
+
+   The `config.yaml` block is intentionally NOT committed to the live config in
+   this slice — adding it changes boot behavior, which would break the
+   default-OFF / byte-identical contract. An operator adds it deliberately when
+   turning the surface on.
+
+2. **Set the env:**
+   - `FLAIR_MCP_OAUTH=1` — turns on the `/mcp` route registration.
+   - `FLAIR_MCP_ISSUER=https://your-public-origin` (or `FLAIR_PUBLIC_URL`).
+   - `FLAIR_MCP_JIT_PROVISION=1` — ONLY if you want unknown subjects
+     auto-provisioned (default OFF; pre-provision Agent+Credential otherwise).
+
+3. **Restart flair.** `/mcp` mounts, OAuth-guarded.
+
+## Sherlock's 4 requirements — how they are met
+
+1. **Token lifetime.** `mcp.accessTokenTtl: 900` (5–15 min) in the AS config +
+   the standard OAuth refresh flow (the plugin rotates refresh tokens on use).
+   `withMCPAuth` validates `exp` strictly. Documented as a required config value,
+   not a default (the plugin's own default is 1h — too long).
+2. **RS256 pinning.** The `@harperfast/oauth` plugin mints and verifies RS256-only
+   (per its docs: "Signing algorithms other than RS256 … are not supported"), so
+   `none`/HS256 confusion is structurally rejected — the verifier only knows
+   RS256. No configurable `alg` to widen.
+3. **Dual-auth precedence.** `/mcp` is OAuth-only on its own urlPath chain;
+   flair's default chain (Ed25519) never runs for `/mcp`, and the OAuth Bearer
+   never reaches the default chain. They cannot collide on the same request —
+   `/mcp` sees only the token, every other path sees only Ed25519/Basic. There is
+   no path that carries both.
+4. **Client registration.** DCR is not supported; clients connect via CIMD
+   (Client ID Metadata Documents) — `mcp.dynamicClientRegistration.enabled:
+   false` explicitly closes RFC 7591 registration (open DCR would let an
+   attacker register as any agent; leaving the block unset does NOT close it —
+   see `src/lib/mcp-enable.ts`'s module header for the ground-truth citation),
+   and `mcp.clientIdMetadataDocuments.allowedHosts` restricts which hosts may
+   present a CIMD client_id URL. On the resolution side, JIT-provisioning of
+   an unknown sub is itself gated (`FLAIR_MCP_JIT_PROVISION`, default OFF) —
+   a second explicit trust anchor.
+
+## Legacy clients
+
+DCR (RFC 7591 Dynamic Client Registration) is UNSUPPORTED on this surface —
+not a fallback, not a flag. `flair mcp enable` (flair#756) writes
+`dynamicClientRegistration: { enabled: false }`, which 404s
+`/oauth/mcp/register`. A client that cannot present a CIMD client_id URL
+cannot connect to this surface.
+
+## Deferred (not in this slice)
+
+- Live `config.yaml` wiring of the `@harperfast/oauth` plugin (kept out to
+  preserve the byte-identical flag-OFF contract; documented above for operators).
+- Migrating the homegrown `OAuth.ts` / `XAA.ts` opaque-token AS to the plugin.
+  Per Kern: deprecate-don't-delete — they stay for the Ed25519/signed-REST path.
+  XAA's JIT-provisioning is kept; the Model-2 handler reuses the same
+  `Credential(kind:"idp")` surface.

package/docs/notes/rem-ux.md

@@ -0,0 +1,39 @@
+# REM UX — trigger model, attach semantics, review loop
+
+> Design note accompanying REM slice 2 (#707). Describes the intended user experience of in-process distillation so the CLI/docs surfaces stay coherent as the feature grows. Parent spec: `specs/FLAIR-NIGHTLY-REM.md`; slice spec: `specs/FLAIR-NIGHTLY-REM-SLICE-2-DISTILLATION.md`.
+
+## Triggers — three, nothing implicit
+
+1. **Interactive:** an agent (or a human at the CLI) runs `flair rem rapid` — one bounded distillation of that agent's own recent memories. Non-admin actors can only reflect on themselves; an admin can run it for any agent.
+2. **Scheduled:** the nightly cycle, per agent, only where deliberately enabled (`flair rem nightly enable`). In a multi-node deploy, exactly one node gets the timer (see #709).
+3. **Admin-run:** same endpoint, another agent's corpus, admin credentials.
+
+REM never fires as a side effect of writes, searches, or boot. Distillation is always a deliberate act with an audit trail.
+
+## Locality — the model call runs next to the data
+
+The CLI is a thin HTTP trigger pointed at whatever Flair instance it is configured for (local or remote). Distillation executes **server-side** in the Flair component via Harper's model-access API. Consequences:
+
+- Memory content never transits the operator's machine on its way to a model.
+- Data egress is determined solely by the *server's* `models:` configuration — a local backend means nothing leaves the box; a hosted provider is an explicit, documented choice (keys ride Harper env-secret encryption on managed deploys).
+- The same trigger UX works identically against a laptop instance and a managed deployment.
+
+## Attach semantics — synchronous now, and the rule for when that changes
+
+**Interactive mode stays attached.** One request, one bounded generate call (gather cap 50 memories, bounded output tokens), a staged-candidate summary printed on return. Seconds, not minutes — request/response is the honest shape for it, and `--prompt-only` preserves the bring-your-own-model handoff.
+
+**Nightly mode is fully detached.** The scheduler fires the cycle; results land as pending candidates plus an audit row; the operator reviews next morning.
+
+**The rule for revisiting:** any run shape that exceeds a single bounded generate call — hierarchical/recursive consolidation, org-level REM across many agents — gets a real job model (run id, `flair rem status <id>`, resumability) *designed before that slice ships*. The failure mode to avoid is a timeout bug forcing an ad-hoc job system into existence.
+
+## The review loop — where REM's UX actually lives
+
+Distillation is the cheap half; the reviewable stream of candidates is the product surface:
+
+- **Today (CLI):** `flair rem candidates` lists pending rows; `flair rem promote <id> --rationale` / `flair rem reject <id> --reason` decide them. Every candidate carries its claim, source memory ids, generating model, and timestamp — enough to judge provenance at a glance.
+- **Direction:** a reviewable feed — candidates as a stream with one-glance provenance and one-action promote/reject, recurring rejected claims surfaced via their `supersedes` chains rather than appearing fresh each time. The nightly diff report should point at that surface, making morning review a two-minute ritual instead of a CLI expedition.
+- **Invariant either way:** nothing self-promotes. The feed can get faster and friendlier; the explicit-decision gate is load-bearing and stays.
+
+## Configuration UX — one decision, one knob
+
+Wanting REM should reduce to: *point the server's `models:` block at a backend.* Local Ollama works with zero credentials; a hosted provider takes an API key stored as an encrypted env secret. `FLAIR_REM_MODEL` selects a logical model name when the default routing isn't right. There is no REM-specific provider code, wiring, or plugin to install — if the server can `generate()`, REM works.

package/docs/openclaw.md

@@ -0,0 +1,131 @@
+# Flair + OpenClaw
+
+Give OpenClaw agents persistent memory and identity.
+
+## Setup
+
+### 1. Install Flair (if not already running)
+
+```bash
+npm install -g @tpsdev-ai/flair
+flair init
+```
+
+### 2. Install the OpenClaw plugin
+
+```bash
+openclaw plugins install @tpsdev-ai/openclaw-flair
+```
+
+### 3. Create an agent identity
+
+```bash
+flair agent add my-agent
+```
+
+### 4. Configure the plugin
+
+In your OpenClaw agent config, add the Flair plugin:
+
+```json
+{
+  "plugins": {
+    "@tpsdev-ai/openclaw-flair": {
+      "agentId": "my-agent",
+      "flairUrl": "http://localhost:19926"
+    }
+  }
+}
+```
+
+Or set environment variables:
+
+```bash
+export FLAIR_AGENT_ID=my-agent
+export FLAIR_URL=http://localhost:19926
+```
+
+### 5. Restart the gateway
+
+```bash
+openclaw gateway restart
+```
+
+## What the Plugin Provides
+
+The Flair plugin adds these tools to your OpenClaw agent:
+
+| Tool | Description |
+|------|-------------|
+| `memory_store` | Write a memory with optional type, durability, and tags |
+| `memory_recall` | Semantic search over stored memories |
+| `memory_get` | Retrieve a specific memory by ID |
+
+### Automatic Bootstrap
+
+On each new conversation, the plugin injects relevant context from Flair:
+- Soul entries (persistent personality and project context)
+- Recent memories (last 24h)
+- Relevant memories (semantically matched to the conversation topic)
+
+This happens automatically — no agent configuration needed beyond the plugin setup.
+
+## Multi-Agent
+
+Each OpenClaw agent gets its own isolated memory space:
+
+```bash
+flair agent add research-agent
+flair agent add coding-agent
+flair agent add review-agent
+```
+
+Agents can share memories via grants:
+
+```bash
+# Let review-agent read coding-agent's memories
+flair grant coding-agent review-agent --scope read
+```
+
+## Soul (Personality)
+
+Set persistent context that shapes how the agent behaves:
+
+```bash
+flair soul set --agent my-agent --key role \
+  --value "Senior engineer focused on reliability. Ship quality over speed."
+
+flair soul set --agent my-agent --key project \
+  --value "E-commerce API. Node.js, PostgreSQL. 200K DAU."
+```
+
+Soul entries are included in every bootstrap — they're the agent's persistent identity.
+
+## Key Resolution
+
+The plugin resolves Ed25519 keys in this order:
+1. `FLAIR_KEY_PATH` environment variable
+2. `~/.flair/keys/<agent-id>.key`
+3. `~/.tps/secrets/flair/<agent-id>-priv.key` (legacy TPS path)
+
+## Troubleshooting
+
+```bash
+# Verify Flair is running
+flair status
+
+# Verify the agent exists
+flair agent list
+
+# Test memory roundtrip
+flair memory add --agent my-agent --content "test memory"
+flair search "test" --agent my-agent
+
+# Check plugin is loaded
+openclaw plugins list
+```
+
+If the plugin fails to load, check the gateway logs for Flair connection errors. Common issues:
+- Wrong port (default changed to 19926 in v0.4.0)
+- Agent not registered (`flair agent add <id>`)
+- Key file missing (`~/.flair/keys/<agent-id>.key`)

package/docs/quickstart.md

@@ -0,0 +1,153 @@
+# Quick Start
+
+From zero to a persistent agent memory in five minutes.
+
+## 0. Prerequisite
+
+**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.
+
+```bash
+node --version   # v22.x.x or higher
+```
+
+If you need Node 22: [nodejs.org](https://nodejs.org/) or `brew install node@24`.
+
+## 1. Install (30 seconds)
+
+```bash
+npm install -g @tpsdev-ai/flair
+```
+
+`flair`, `flair-mcp`, and the client library all come in under one install.
+
+## 2. Bootstrap Flair (1–2 minutes)
+
+```bash
+flair init
+```
+
+First run does a few things:
+
+1. Installs the embedded Harper (memory store) into `~/.flair/data/`.
+2. Downloads the local embedding model (~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.
+
+The soul wizard offers a few shapes:
+
+```
+🎭 Agent personality setup
+   Soul entries shape what every future session starts with.
+
+   What best describes this agent?
+     (1) Solo developer — helps you with code on this machine
+     (2) Team agent — runs in a shared repo / ops flow
+     (3) Research assistant — surveys sources, writes notes
+     (4) Draft from Claude — paste a Claude-generated JSON draft
+     (5) Custom — I'll prompt for each field with examples
+     (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`.
+
+## 3. Confirm it's running
+
+```bash
+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
+
+  ✓ all checks passing
+```
+
+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**.
+
+For the full picture — Memory, Agents, and Soul detail — pass the agent you just created:
+
+```bash
+flair status --agent local
+```
+
+```
+Flair vX.Y.Z — 🟢 running (PID 12345, uptime 1m)
+  URL:        http://127.0.0.1:19926
+
+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
+
+  ✓ all checks passing
+```
+
+## 4. Write your first memory
+
+```bash
+flair memory add --agent local --content "Harper v5 sandbox blocks node:module but process.dlopen works"
+```
+
+Flair generates a semantic embedding locally and stores it. No network calls.
+
+## 5. Find it back by meaning
+
+```bash
+flair memory search --agent local --q "native addon loading in sandboxed runtimes"
+```
+
+```
+  Harper v5 sandbox blocks node:module but process.dlopen works
+  (2026-04-22 · memory · 67%)
+```
+
+**You searched for a concept, not the keywords.** The 67% is the semantic-similarity score.
+
+## 6. Give your agent context on boot
+
+```bash
+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.
+
+If you use 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.
+
+## 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) |
+| 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) |
+
+## If you change your mind
+
+```bash
+flair stop              # stop the service (keeps data)
+flair restart           # restart
+flair uninstall         # remove the service (keeps data + keys)
+flair uninstall --purge # remove everything including data and keys
+```
+
+All reversible. Your memories aren't locked in.

package/docs/releasing.md

@@ -0,0 +1,173 @@
+# Releasing Flair
+
+Flair publishes eight workspace packages to npm under `@tpsdev-ai/*`. Releases are
+**tokenless** and **staged**: CI authenticates to npm with a short-lived OIDC token
+(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.
+
+```
+ merge release PR ──▶ push tag v0.11.0 ──▶ CI stages all packages ──▶ npm staging
+                                                                          │
+                                                  maintainer reviews + approves (2FA)
+                                                                          ▼
+                                                                      live on npm
+```
+
+Pushing a `vX.Y.Z` tag triggers the release. This replaces the old "run
+`release.sh --publish` from a laptop logged into npm" flow. Nothing publishes without
+a human 2FA approval, and every package ships with a provenance attestation (public
+repo → verifiable build origin). The person who tags the release does **not** need npm
+credentials or `Actions: write` — only repo push access; the only privileged step is
+the maintainer's 2FA approval.
+
+## Cutting a release
+
+### 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.
+
+### Phase 2 — tag the release
+
+After the release PR is merged to `main`, push the version tag:
+
+```bash
+git checkout main && git pull
+git tag v0.11.0 && git push origin v0.11.0
+```
+
+The tag push triggers the [`release-publish`](../.github/workflows/release-publish.yml)
+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.
+4. Builds every package.
+5. Runs `npm stage publish` for each package in dependency order (flair-client first).
+
+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
+but **not yet live**.
+
+In parallel — and **independent of the npm staging approval** — a `github-release` job
+auto-cuts a [GitHub release](https://github.com/tpsdev-ai/flair/releases) for the tag,
+using the matching `## [X.Y.Z]` section of `CHANGELOG.md` as the release notes (extracted
+by `scripts/changelog-extract.mjs`). It is idempotent: re-running the workflow or
+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.
+
+> `workflow_dispatch` with a `version` input remains as a manual fallback (needs
+> `Actions: write`), but the tag push is the normal path.
+
+### Phase 3 — approve the staged packages
+
+Go to **[npmjs.com → tpsdev-ai → Staged Packages](https://www.npmjs.com/settings/tpsdev-ai/staging)**,
+review each staged tarball, and approve with 2FA. Or from a machine logged into npm:
+
+```bash
+npm stage list            # show staged packages + their stage-ids
+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
+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.
+
+Verify when done:
+
+```bash
+npm view @tpsdev-ai/flair version   # should report the new version
+```
+
+## One-time setup
+
+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
+Publisher → Add**:
+
+| Field           | Value                       |
+| --------------- | --------------------------- |
+| Provider        | GitHub Actions              |
+| Organization    | `tpsdev-ai`                 |
+| Repository      | `flair`                     |
+| Workflow        | `release-publish.yml`       |
+| Environment     | `release`                   |
+| Allowed actions | **`npm stage publish` only** |
+
+Leave `npm publish` **unchecked** under allowed actions. This structurally prevents the
+CI/OIDC identity from publishing anything live directly — the only path to live is the
+human 2FA approval of a staged package.
+
+Packages: `flair-client`, `flair-mcp`, `flair`, `openclaw-flair`, `pi-flair`,
+`n8n-nodes-flair`, `langgraph-flair`.
+
+> 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.
+
+### GitHub `release` environment
+
+A repository environment named `release` scopes the OIDC trust. It has **no required
+reviewers** — the human gate is the npm staging approval, not a GitHub deployment
+review. Because the release is triggered by a tag push, its deployment policy must allow
+**`v*` tags** (Settings → Environments → `release` → Deployment branches and tags →
+Selected branches and tags → add tag rule `v*`).
+
+### Approver 2FA
+
+The maintainer who approves staged packages must have 2FA enabled on their npm account.
+
+## If something goes wrong
+
+- **A staged package looks wrong** — reject it on npmjs.com instead of approving; it
+  never goes live. Fix forward on `main` and cut a new patch version.
+- **Re-run the stage for the same version** — delete and re-push the tag
+  (`git push origin :v0.11.0` then `git tag -f v0.11.0 && git push origin v0.11.0`).
+  The tag push re-triggers the workflow.
+- **Break-glass (CI down):** `./scripts/release.sh X.Y.Z --publish` still works from a
+  machine logged into npm. Prefer the staged flow; this bypasses the staging gate.
+
+## Requirements
+
+- npm CLI **≥ 11.15.0** (`npm stage`) and **≥ 11.5.1** (OIDC) — the workflow upgrades
+  npm itself; local approvers need a recent npm.
+- Node **≥ 22.14**.
+- Trusted publishing runs on GitHub-hosted runners only (no self-hosted support yet).