@tpsdev-ai/flair 0.30.0 → 0.31.0

package/docs/embedding-in-a-harper-app.md

@@ -0,0 +1,299 @@
+# Embedding Flair in a Harper app
+
+Flair is a Harper component. If your app already runs on Harper, load Flair into the same instance and call it **in-process** — no HTTP, no second process, and **no shell on the node**.
+
+Everything below is code you run inside your own component. The CLI is an alternative for local development, not a requirement — see [If you have shell access](#if-you-have-shell-access).
+
+| | Embedded | Standalone ([deployment.md](deployment.md)) |
+|---|---|---|
+| Latency | A method call | HTTP round trip |
+| Agent identity | You assert it per call | Ed25519 signature, verified server-side |
+| Trust boundary | Callers are **inside** it | Callers are outside it, and must authenticate |
+
+Embedding *adds* the in-process path; `rest: true` keeps serving MCP clients and remote agents as before.
+
+---
+
+## Quickstart
+
+**1. Add Flair to your instance.** Deploy `@tpsdev-ai/flair` as a component the way you deploy your own — Fabric's component deploy, Studio, or your pipeline. Its tables are declared `@table(database: "flair")`, so they never collide with yours.
+
+**2. Resolve the resource and write a memory.**
+
+```javascript
+import { server } from "harper";
+// Flair ships these two helpers so you do not have to get either of them right
+// by hand. They are the whole in-process contract.
+import { agentContext, internalContext, collectionResource } from "@tpsdev-ai/flair/dist/resources/in-process.js";
+
+// The RESOURCE — carries auth, scoping, visibility, embedding.
+// NOT databases.flair.Memory: that is the raw table, and enforces none of it.
+// Keys carry NO leading slash: get("Memory"), never get("/Memory").
+const flair = (path) => server.resources.get(path).Resource;
+
+export async function remember(agentId, content, opts = {}) {
+  // A create needs a COLLECTION-bound instance. `new Cls(...)` does not give
+  // you one, and cannot be made to — see the note below.
+  const h = await collectionResource(flair("Memory"), agentContext(agentId));
+  return h.post({
+    agentId,                                // required — an absent one is never filled in
+    content,
+    durability: opts.durability ?? "standard",
+  });
+}
+```
+
+> ### Why `collectionResource`, and not `new Memory()`
+>
+> A resource's `post()` only works on an instance Harper has marked as a **collection**, and that mark is a *private* field only Harper's own `getResource()` can set. The public `isCollection` is a getter with no setter, so the obvious spelling fails two different ways, neither of which names the cause:
+>
+> ```javascript
+> const h = new (flair("Memory"))(undefined, agentContext(agentId));
+> h.isCollection = true;   // TypeError: Cannot set property isCollection ... which has only a getter
+> h.post({ ... });         // without the line above: 405 "The Memory does not have a post method implemented"
+> ```
+>
+> `collectionResource(Cls, context)` is a two-line wrapper over the supported call — `Cls.getResource({}, context, { isCollection: true })` — and exists so this is written once. **Reads do not need it:** `Cls.get(id, context)` and `Cls.search(query, context)` thread the context themselves.
+
+> ### ⚠️ A resource with no context is an administrator
+>
+> A resource built without a context resolves to Flair's trusted `internal` verdict and runs **unfiltered** — every read unscoped, every write unowned. Silently. No error, no warning, no trace.
+>
+> Measured, not inferred: a context-less `Memory.search()` returns every agent's `private` records, and so does a context-less `SemanticSearch`.
+>
+> Correct for Flair's own maintenance passes. In your app it is a data leak you find months later.
+>
+> **Make `agentId` a required argument, as above.** Never export a version that defaults it.
+
+**3. Read it back, scoped to that agent.**
+
+```javascript
+export async function recall(agentId, query, limit = 5) {
+  const h = await collectionResource(flair("SemanticSearch"), agentContext(agentId));
+  return h.post({ q: query, limit });
+}
+```
+
+**4. Verify it worked, still in-process.**
+
+```javascript
+await remember("agent-alpha", "deploy runs at 0200 UTC");
+console.log(await recall("agent-alpha", "deploy schedule"));
+console.log([...server.resources.keys()].sort());   // what Flair registered
+```
+
+> ### What we measured, so you do not have to
+>
+> Run end to end on **Harper 5.1.22**, from a second component loaded into the same instance — the exact shape above. `test/integration/in-process-agents.test.ts` in the Flair repo is that run, and `test/fixtures/inproc-app` is the component it drives.
+>
+> | Claim | Result |
+> |---|---|
+> | `server.resources.get("Memory")` from another component | Returns an **entry object** `{ Resource, path, exportTypes, hasSubPaths, relativeURL }` — `.Resource` is required, it is not the class itself |
+> | `.Resource` is Flair's resource, not the raw table | Confirmed: prototype chain `Memory → Memory → Resource`, and it is **not** `databases.flair.Memory` |
+> | Key format | **No leading slash.** `get("Memory")` hits; `get("/Memory")` returns `undefined` |
+> | `getMatch` | `getMatch("Memory")` hits. **`getMatch("/Memory")` misses** — do not use the slashed form |
+> | When the lookup becomes valid | Flair's resources were already registered at the app component's **module top level** (55 entries, `Memory` and `Agent` present). The only entry missing at that moment was the app's *own*, still mid-registration. Resolving lazily, as above, is still the advice — it costs nothing and does not depend on component load order |
+> | Per-agent scoping through `SemanticSearch` | Holds. Querying as `agent-beta` for a topic only `agent-alpha` has written returns **beta's own** memory, never alpha's private one — with real 768-dim embeddings attached, not a degraded path |
+> | Cross-agent by-id read | `Memory.get(<beta's private id>)` as alpha returns **404**, never 403 — a denied caller cannot enumerate ids |
+> | Context-less call | Unfiltered across all agents, via both `search` and `SemanticSearch` (see the warning above) |
+
+Handlers return a `Response` for `401`/`403`/`400` rather than throwing — check for one. `Memory.post()` is in-process only; over HTTP the schema exposes `PUT`.
+
+---
+
+## N agents in one process
+
+**Acting as an agent needs nothing but the context.** Identity resolves per call from `request.tpsAgent`, so one process serves any number of agents — no client to construct, no key to load, no per-agent setup:
+
+```javascript
+for (const id of ["planner", "researcher", "reviewer"]) {
+  await remember(id, `${id} came online`);
+}
+```
+
+`tpsAgent` is **not** checked against the `Agent` table, so this works with no registration at all. Register agents anyway — the admin UI, federation, and the HTTP path all read those records.
+
+### Registering agents, no CLI
+
+Go through the `Agent` **resource**, with no context — provisioning is infrastructure work your app has already authorised, and `Agent.post()` fills in the whole Principal shape for you:
+
+```javascript
+export async function registerAgent(id, { publicKey = "pending", admin = false } = {}) {
+  const h = await collectionResource(flair("Agent"), internalContext());   // provisioning is infrastructure, not an agent's write
+  return h.post({
+    id, name: id, displayName: id,
+    publicKey,                            // a placeholder is fine — see below
+    runtime: "headless",
+    ...(admin ? { role: "admin", admin: true } : {}),   // role is what actually grants admin
+  });
+}
+```
+
+Verified against a real instance: that lands `kind: "agent"`, `status: "active"`, `displayName`, `admin: false`, `defaultTrustTier: "unverified"`, `type: "agent"`, `createdAt`/`updatedAt` and the federation `originatorInstanceId` stamp — without you naming any of them.
+
+> **Prefer this to `databases.flair.Agent.put()`.** The raw table applies **no** defaults, so a hand-written literal has to reproduce every field above and then stay in step with Flair as the Principal model grows. Records written that way are missing `kind`/`status`/`defaultTrustTier` and read as under-specified Principals in the admin surfaces.
+
+> **`isAdmin()` reads `role === "admin"`, not the `admin` boolean.** They are separate fields and only `role` grants admin rights; set both to keep the record self-consistent. Admin lookups are cached for 60 seconds, so a newly-created admin is not effective immediately.
+
+`publicKey` is non-nullable in the schema, but it does not have to be a real key. An agent that only ever acts in-process never authenticates, and Flair's own paths write placeholders — `"pending"` when seeding, `mcp-oauth:<sub>` for token-authenticated agents. Give an agent a real key only if it must also authenticate **over HTTP**, which your app can do without any CLI:
+
+```javascript
+import { generateKeyPairSync } from "node:crypto";
+
+const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+const raw = publicKey.export({ format: "der", type: "spki" }).subarray(-32);
+await registerAgent("remote-worker", { publicKey: raw.toString("hex") });
+// keep `privateKey` in your own secret store — Flair never sees it
+```
+
+Flair accepts the public key as 64-char hex, or base64 of the raw 32 bytes.
+
+Both verified end to end: an agent registered this way, with a key its app minted, then authenticated over HTTP with a real `TPS-Ed25519` signature — and a request signed with the *wrong* key was rejected.
+
+> **Two traps.** `Agent.put()` on the *resource* silently strips `publicKey`, so set the key when you **create** the record; to rotate one later, write `databases.flair.Agent.put({ ...existing, publicKey })` on the raw table (which is what `flair agent rotate-key` does through the admin ops API — there is no dedicated endpoint today). And do **not** call `AgentSeed` in-process: although its `allowCreate()` explicitly permits the trusted `internal` verdict, its `post()` then re-checks for a named admin and returns `403 forbidden: admin only` — confirmed by running it.
+
+---
+
+## The table is not the resource
+
+Flair declares `Memory` as a table, then exports a **subclass** as the resource. Harper's loader registers exported classes in the routing map only, never back into `databases`, so the two stay distinct:
+
+| Import | What you get |
+|---|---|
+| `server.resources.get("Memory").Resource` | **The resource.** Auth, read-scoping, private-memory exclusion, no-forge attribution, embedding generation, default visibility, rate limiting. |
+| `databases.flair.Memory` | **The table.** Raw storage. None of the above. |
+
+Flair uses the raw table where it *wants* to bypass its own rules — the federation merge path writes through it so a synced record's origin stamp survives. Use it only for work you have authorised yourself: provisioning, migrations, admin sweeps, reporting. Never for a memory written on an agent's behalf.
+
+---
+
+## Identity
+
+| Context | Verdict | Effect |
+|---|---|---|
+| `{ request: { tpsAnonymous: true } }` | `anonymous` | Denied everywhere |
+| `{ request: { tpsAgent: "mybot" } }` | `agent` | Scoped to that agent — **use this** |
+| `{ request: { tpsAgent: "mybot", tpsAgentIsAdmin: true } }` | admin | Unfiltered reads, cross-agent writes |
+| **Nothing**, or an empty/missing `tpsAgent` | `internal` | **Trusted. Unfiltered.** See the warning above. |
+
+Build these with `agentContext(id)`, `adminContext(id)` and `internalContext()` rather than by hand — see [below](#the-api-is-built-so-omission-cannot-happen-quietly) for why the hand-written form is a trap.
+
+### The context object is a security boundary
+
+**In-process identity is asserted, not verified.** Flair reads `request.tpsAgent` and acts as that agent. There is no signature check, no lookup against the `Agent` table, and no registration requirement — an id that has never been registered acts as an agent immediately. `tpsAgentIsAdmin: true` is asserted exactly the same way, and nothing checks that the named agent is really an admin.
+
+That is deliberate. A co-located caller is already inside the trust boundary and could write `databases.flair.Memory` directly, so demanding a signature from same-process code would be theatre. Ed25519 is how agents *outside* the process prove identity.
+
+The consequence is the single most important line in this guide:
+
+> **Build the context from your own server-side state. Never from request data.**
+>
+> If an agent id can reach `agentContext()` from user input — a body field, a query param, a header you did not verify yourself — that is privilege escalation with **no error, no 403 and no trace**. Authenticate the caller with your own mechanism first, then map the identity *you* established onto `tpsAgent`.
+
+There are exactly two ways to lose the model, from opposite ends. Both are pinned as tests in the Flair repo:
+
+| | |
+|---|---|
+| **By omission** | No usable agent id ⇒ `internal` ⇒ admin-equivalent, unfiltered. |
+| **By assertion** | An attacker-influenced `agentId` is honoured verbatim. |
+
+### The API is built so omission cannot happen quietly
+
+`resolveAgentAuth` tests `tpsAgent` for *truthiness*, so a missing or empty id is indistinguishable from "no identity supplied" — which is the trusted, unfiltered verdict. Measured:
+
+```
+resolveAgentAuth({ request: { tpsAgent: undefined } })  ->  { kind: "internal" }
+allowAdmin({ request: { tpsAgent: undefined } })        ->  true
+```
+
+That would turn the most ordinary bug there is — `agentContext(session.agentId)` where the field came back undefined — into silent administrator access. So the helpers refuse rather than default:
+
+| | |
+|---|---|
+| `agentContext(id)` | **Throws** `InProcessContextError` on a missing, empty or blank id. Takes **no options**, so no object spread into it can escalate. |
+| `adminContext(id)` | The *only* way to get admin authority. Same id guard. |
+| `internalContext()` | The *only* way to get the unfiltered verdict. |
+| `collectionResource(Cls, context)` | Context is **required**; omitting it throws rather than granting `internal`. |
+
+The privileged paths are now the longest ones to type, and `git grep "adminContext\|internalContext"` enumerates every deliberate escalation in your codebase. These are runtime guards, not type annotations — a plain-JavaScript embedder gets exactly the same protection.
+
+### Individual identities, not one app identity
+
+Give every agent its own. A per-agent context costs nothing — no client to construct, no key to load, no per-agent setup, not even a registration. Collapsing N agents onto one shared identity buys you nothing and loses the two things that make the memory model work: **per-agent attribution**, which is what trust grading and provenance are computed from, and **N separate blast radii**, which become one.
+
+### In a cluster
+
+Harper replicates every table in a replicated database unless the table opts out with `@table(replicate: false)`. None of Flair's do. So:
+
+- **The registry replicates.** An agent registered on node A is visible on node B with no coordination. (Replication comes from the *database* being replicated — not from `@export`, which only controls REST exposure. `Memory` carries no `@export` and still replicates.)
+- **Authority is local.** The context is constructed per call, in whichever process handles it. No node asks another who a caller is.
+- **Attribution travels.** `agentId` is a field *on the record*, so a memory written on node A reads back correctly attributed — and correctly scoped — wherever it lands. Verified as far as this can be without a cluster: a fresh Harper process over the same storage resolves identical per-agent scope, so none of it lives in the process that did the writing.
+
+The consequence, stated plainly because someone will ask: **every node running the app is equally trusted**, since each one can assert any identity. That is fine for one application spread across regions — it is a single trust domain by construction. It is **not** fine for running this component beside untrusted co-tenants on the same instance. Co-location *is* the grant.
+
+---
+
+## Coexisting with your components
+
+Flair's instance-wide middleware runs first but is **non-rejecting** — unrecognised requests pass through rather than 401'ing, so your component's auth keeps working. Two collisions to check:
+
+- **`/Admin` is a prefix match.** Flair 401s any unauthenticated path *starting with* `/Admin` — including an app route like `/AdminPanel`. Rename yours.
+- **Top-level paths.** Flair claims ~53, including `Memory`, `Agent`, `Instance`, `Integration`, `Credential`, `Health`, `Presence`, `Relationship`, `Soul`, `SemanticSearch`. `server.resources.keys()` lists them.
+
+---
+
+## Federation
+
+Pairing an embedded instance to an external hub as a spoke **requires shell access today** — the pairing and sync commands are CLI-only. If your deployment has no shell, federation is not available to it yet.
+
+> **Sync is push-only — one direction per call.** A spoke pushes its records up and **receives nothing back**. There is no pull endpoint, and nothing initiates a hub-to-spoke push. Do not plan on reading another instance's memories through the hub.
+>
+> For records both ways, each instance must pair **as a spoke of the other** — two pairings, each side running its own sync.
+
+Private memories are never pushed. Full walkthrough: [federation.md](federation.md).
+
+---
+
+## If you have shell access
+
+Local development and self-hosted installs can drive the same things from the CLI:
+
+```bash
+flair doctor
+flair agent add mybot          # registers + generates and stores a keypair
+flair agent list
+flair memory search "deploy schedule" --agent mybot
+```
+
+Federation, which has no in-process equivalent:
+
+```bash
+flair federation token --admin-pass <hub-admin-pass> > triple.json
+flair federation pair <hub-url> --token-from ./triple.json
+flair federation sync enable --interval 300
+flair federation status
+```
+
+`sync enable` landed **after 0.30.0**; on an older install, schedule the one-shot yourself.
+
+A `SyncLog` row reads `direction: "pull"` — the receiver's label for a push it accepted. `"push"` is never written. Not a pull path.
+
+---
+
+## Choosing a surface
+
+| Surface | Use when |
+|---|---|
+| **In-process resource** | Your app's agents, same instance. No round trip — and no auth safety net. |
+| **[`@tpsdev-ai/flair-client`](https://www.npmjs.com/package/@tpsdev-ai/flair-client)** | Out of process: another host, runtime or sidecar. One client per `agentId`. |
+| **Native `/mcp`** | MCP clients against this instance. Identity from the OAuth token. |
+| **`@tpsdev-ai/flair-mcp`** (stdio) | Local MCP clients. Talks HTTP via `FlairClient`. |
+| **`flair` CLI** | Pairing and key generation. Needs a shell. |
+
+**Trust-graded recall (`includeTrust`)** — provenance, author, usage, freshness, supersession — works in-process (`SemanticSearch.post({ q, includeTrust: true })`, `Memory.get(id, { includeTrust: true })`), over REST, and on the native `/mcp` handler. It is **not** exposed by the CLI, the stdio MCP server, or `FlairClient`'s typed methods.
+
+---
+
+## See also
+
+[Integrations](integrations.md) · [Deployment](deployment.md) · [Federation](federation.md) · [Auth](auth.md) · [Architecture](../DESIGN.md)

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"