@tpsdev-ai/flair 0.31.1 → 0.33.0

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

@@ -18,88 +18,91 @@ Embedding *adds* the in-process path; `rest: true` keeps serving MCP clients and
 
 **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.**
+**2. Import the facade 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";
+import { Flair } from "@tpsdev-ai/flair";
 
-// 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;
+const flair = new Flair(server);
+const planner = flair.as("planner");
 
-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",
-  });
-}
+await planner.memory.write("deploy runs at 0200 UTC", { 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.
->
-> They do still need the **context**. Only the collection binding is unnecessary for a read, never the identity — `Cls.search(query)` with the second argument left off resolves to the trusted `internal` verdict when it runs outside a request scope (a boot hook, a timer, a queue worker, a detached promise) and returns every agent's private records. On that path the resource's `allow*` gate is not consulted at all. Pass the context to every call, read and write.
-
-> ### ⚠️ 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.
+That is the whole API. No deep import, no `server.resources`, no `.Resource`, no `collectionResource()`, no double-passing `agentId`. The facade stamps `agentId` from the handle's context onto the body internally — you pass it once, at `flair.as(id)`.
 
 **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 });
-}
+const hits = await planner.recall("deploy schedule", { limit: 5 });
+const record = await planner.memory.get(hits[0].id);
 ```
 
-**4. Verify it worked, still in-process.**
+**4. Register an agent, no CLI.**
 
 ```javascript
-await remember("agent-alpha", "deploy runs at 0200 UTC");
-console.log(await recall("agent-alpha", "deploy schedule"));
+await flair.admin.registerAgent("planner", { publicKey: "pending" });
+```
+
+> **`flair.admin` is a root shell.** Every call site is greppable via `git grep "flair.admin"`. Use for provisioning and maintenance only, never as a request handler's default.
+
+**5. Verify it worked.**
+
+```javascript
+console.log(await planner.memory.search({ limit: 10 }));
 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`.
+## The facade
+
+### `new Flair(server)`
+
+One handle per Harper instance. Resolves resources lazily on first use — no lookup at construction time.
+
+**The handle owns nothing.** It holds a reference to the Harper server the caller already owns and acquires no timers, connections, or file handles. There is no `close()` or `dispose()` method. If a future version acquires something releasable, that is a breaking change and will be versioned as one.
+
+### `flair.as(agentId)`
+
+Returns an `AgentHandle` scoped to that agent. The `agentId` is runtime-validated: missing, empty, blank, or non-string throws `InProcessContextError`.
+
+```javascript
+const planner = flair.as("planner");
+planner.agentId;  // "planner"
+```
+
+**Security:** In-process identity is asserted, not verified — co-location IS the grant. Build the `agentId` from your own server-side state, never from request data. If an agent id can reach `flair.as()` 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**.
+
+### `AgentHandle`
+
+| Method | Description |
+|---|---|
+| `handle.memory.write(content, opts?)` | Write a memory as this agent. `agentId` is stamped from the handle — the caller never passes it. |
+| `handle.memory.get(id)` | Read a memory by id, scoped to this agent. |
+| `handle.memory.search(opts?)` | Search memories scoped to this agent. |
+| `handle.recall(query, opts?)` | Semantic search scoped to this agent. |
+
+### `flair.admin`
+
+Admin operations — unfiltered reads, cross-agent writes. Every call site is greppable via `git grep "flair.admin"`.
+
+**The handle is cached** — `flair.admin === flair.admin` is `true`. Access it once and reuse the reference, or access it inline; either is fine.
+
+| Method | Description |
+|---|---|
+| `flair.admin.registerAgent(id, opts?)` | Register an agent through the Agent resource (full Principal shape). |
+| `flair.admin.memory.get(id)` | Read any memory by id, unfiltered. |
+| `flair.admin.memory.write(asAgentId, content, opts?)` | Write a memory attributed to another agent. |
+
+### `flair.internal`
+
+Trusted, unattributed, unfiltered operations — Flair's `internal` verdict. Every call site is greppable via `git grep "flair.internal"`.
+
+| Method | Description |
+|---|---|
+| `flair.internal.agentTable.put(record)` | Write directly to the Agent resource (bypasses admin gate). |
 
 ---
 
@@ -109,7 +112,8 @@ Handlers return a `Response` for `401`/`403`/`400` rather than throwing — chec
 
 ```javascript
 for (const id of ["planner", "researcher", "reviewer"]) {
-  await remember(id, `${id} came online`);
+  const agent = flair.as(id);
+  await agent.memory.write(`${id} came online`);
 }
 ```
 
@@ -117,18 +121,14 @@ for (const id of ["planner", "researcher", "reviewer"]) {
 
 ### 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:
+Go through `flair.admin.registerAgent()` — it goes through the `Agent` **resource**, which 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 ? { admin: true } : {}),    // sets role:"admin" too — see below
-  });
-}
+await flair.admin.registerAgent("researcher", {
+  publicKey: "pending",
+  displayName: "Research Agent",
+  admin: false,
+});
 ```
 
 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.
@@ -146,7 +146,7 @@ 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") });
+await flair.admin.registerAgent("remote-worker", { publicKey: raw.toString("hex") });
 // keep `privateKey` in your own secret store — Flair never sees it
 ```
 
@@ -298,6 +298,106 @@ A `SyncLog` row reads `direction: "pull"` — the receiver's label for a push it
 
 ---
 
+## Appendix: the primitives layer
+
+The facade wraps a lower-level API that is still available for callers who need direct access. Import it from `@tpsdev-ai/flair/server`:
+
+```javascript
+import { agentContext, adminContext, internalContext, collectionResource } from "@tpsdev-ai/flair/server";
+```
+
+This is the same seam Flair's own MCP handler and internal tooling use. **You should not need it for ordinary agent operations** — the facade covers those. Reach for the primitives when you are building your own abstraction on top of Flair's resources, or when you need the context helpers (`agentContext`, `adminContext`, `internalContext`) to pass into a resource call directly.
+
+### Resolving a resource
+
+```javascript
+// 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;
+```
+
+### Writing a memory (primitives)
+
+```javascript
+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.
+>
+> They do still need the **context**. Only the collection binding is unnecessary for a read, never the identity — `Cls.search(query)` with the second argument left off resolves to the trusted `internal` verdict when it runs outside a request scope (a boot hook, a timer, a queue worker, a detached promise) and returns every agent's private records. On that path the resource's `allow*` gate is not consulted at all. Pass the context to every call, read and write.
+
+> ### ⚠️ 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.
+
+### Reading back (primitives)
+
+```javascript
+export async function recall(agentId, query, limit = 5) {
+  const h = await collectionResource(flair("SemanticSearch"), agentContext(agentId));
+  return h.post({ q: query, limit });
+}
+```
+
+### Registering agents (primitives)
+
+```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 ? { admin: true } : {}),    // sets role:"admin" too — see below
+  });
+}
+```
+
+### 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`.
+
+---
+
 ## See also
 
 [Integrations](integrations.md) · [Deployment](deployment.md) · [Federation](federation.md) · [Auth](auth.md) · [Architecture](../DESIGN.md)

package/docs/hosted-on-fabric.md

@@ -0,0 +1,203 @@
+# Hosted on Harper Fabric
+
+Deploy Flair as a component to a [Harper Fabric](https://www.harperdb.io/) instance. You do not run the Harper process yourself: managed hosting, multi-region replication, no shell on the node.
+
+---
+
+## Deploy
+
+You **deploy** rather than install. `flair deploy` pushes Flair as a Fabric component:
+
+```bash
+export FABRIC_USER=<admin> FABRIC_PASSWORD=<pass>
+
+# Validate args and package layout without deploying
+flair deploy --fabric-org <org> --fabric-cluster <cluster> --dry-run
+
+# Deploy
+flair deploy --fabric-org <org> --fabric-cluster <cluster>
+```
+
+Credentials go via the environment, not argv, so they stay out of `ps`. Use `--fabric-password-file <path>` (mode `0600`) when scripting; inline `--fabric-user`/`--fabric-password` flags leak to shell history and are discouraged.
+
+Target defaults to `https://<cluster>.<org>.harperfabric.com`; override with `--target`. Deploy verifies the served API, waits for replication, and polls for convergence before reporting success.
+
+> `--fabric-token` is accepted but **fails** — `deploy_component` is Basic-auth only.
+
+### Provision the instance
+
+Run **once**, before serving traffic:
+
+```bash
+flair init --target https://<cluster>.<org>.harperfabric.com \
+  --ops-target <ops-url> \
+  --cluster-admin-user <user> --cluster-admin-pass <pass> \
+  --remote --force
+```
+
+- `--force` is required — this writes to a live instance.
+- `--remote` marks it a federation **hub** and creates the `flair_pair_initiator` role; without it, pairing later fails role-not-found.
+- Generated admin password lands in `~/.tps/secrets/flair-fabric-hdb` (mode `0600`); `--flair-admin-pass` to choose your own.
+
+### Port derivation trap
+
+Locally, Flair serves data on `19926` and the ops API on `19925`. The CLI derives **ops = data − 1** everywhere. A managed endpoint is HTTPS on 443 with no port, so derivation produces `:442` — where nothing answers.
+
+**Pass `--ops-target <url>` explicitly** (or set `FLAIR_OPS_TARGET`) on any command that touches the ops API: `init --target`, `agent add --target`, `federation token --target`.
+
+---
+
+## Configuration
+
+On Fabric, configuration goes through the component's environment, not a local `config.yaml`. Set these in the Fabric component env:
+
+| Variable | What it does | When to set it |
+|----------|--------------|----------------|
+| `FLAIR_PUBLIC_URL` | The URL operators reach this Flair on. Surfaced in OAuth metadata and A2A discovery. | **Always set** — or clients see a loopback address. |
+| `HDB_ADMIN_PASSWORD` | Bootstrap password for the embedded Harper. | Set at install time. |
+| `FLAIR_KEY_PASSPHRASE` | Passphrase for federation key encryption. | Set for production federation deployments. |
+
+On Fabric / managed deploys, environment variables are provisioned through Harper's Fabric secrets mechanism (encrypted at rest with `enc:v1:` storage format).
+
+---
+
+## Agent authentication
+
+Agents authenticate with **Ed25519 per-agent keys** — the same model as standalone local. Each agent holds a private key and signs every request.
+
+### Register an agent
+
+```bash
+# Register an agent — --ops-target is required (see Port derivation trap above)
+flair agent add mybot --target "$FLAIR_URL" --ops-target <ops-url>
+```
+
+The private key is stored on the **client machine** at `~/.flair/keys/<agent>.key`, not on the Fabric node. The Fabric node stores only the public key in the `Agent` table.
+
+### Connect a client
+
+```bash
+export FLAIR_URL=https://<cluster>.<org>.harperfabric.com
+
+# Register an agent
+flair agent add mybot --target "$FLAIR_URL" --ops-target <ops-url>
+
+# Use with any MCP client — set FLAIR_AGENT_ID and FLAIR_URL in the client env
+```
+
+Auth is the same protocol as standalone: Ed25519 signature of `agentId:timestamp:nonce:METHOD:/path`, 30-second replay window, nonce deduplication. The difference is purely the transport — HTTPS instead of localhost HTTP.
+
+See [secrets-and-keys.md](secrets-and-keys.md) for the full threat model.
+
+---
+
+## Verify it works
+
+### Health and status
+
+```bash
+curl -sf https://<cluster>.<org>.harperfabric.com/Health
+
+flair status --target https://<cluster>.<org>.harperfabric.com
+flair fleet verify --target https://<cluster>.<org>.harperfabric.com
+```
+
+`fleet verify` checks health, auth, and version across the origin node plus every Flair federation peer on file. Exit codes: 0 = all verified, 1 = origin failed, 2 = peer version skew, 3 = peer unverifiable.
+
+> **A credential mismatch renders as an empty section.** `flair status` reads `/HealthDetail` with `FLAIR_ADMIN_PASS` / `HDB_ADMIN_PASSWORD` / a pinned agent key — **not** the `FABRIC_*` credentials. On failure it renders blank.
+
+### What is available remotely
+
+| Command | Works remotely |
+|---|---|
+| `GET /Health` | Yes — public, no auth |
+| `flair status --target <url>` | Yes — subsystem rollups |
+| `flair quality --target <url>` | Yes — recall/coverage metrics |
+| `flair fleet verify --target <url>` | Yes — origin + Flair peers |
+| `flair federation status\|verify\|reachability --target <url>` | Yes — peer table, sync recency |
+
+### What does **not** work remotely
+
+**`flair doctor`** takes no `--target` — it hardcodes localhost, reads a local PID file, and shells out to `lsof`. Unavailable too: `start`, `stop`, `restart`, `snapshot`, `reembed`, `rem`, `bridge`.
+
+**Fabric's own cluster topology is invisible.** `fleet verify` sweeps *Flair's* federation peer table, not Harper's cluster nodes. `cluster_status` is harper-pro-only. `0 peers known` means "0 on file", never "0 exist."
+
+---
+
+## Upgrade
+
+A Fabric-deployed Flair is a component, not an npm package. Upgrade in place:
+
+```bash
+FABRIC_USER=<admin> FABRIC_PASSWORD=<pass> \
+  flair upgrade --target https://<cluster>.<org>.harperfabric.com
+```
+
+This resolves the target version, stages a clean deployable with the required `@harperfast/harper` version pin, confirms the staged build before deploying, pushes it via `flair deploy`, and verifies the result. After a successful deploy, it runs a fleet convergence sweep across the origin plus every Flair federation peer.
+
+- `--check` shows the version diff and plan without deploying.
+- `--yes` skips the confirmation prompt for scripted use.
+- `--fabric-password-file <path>` reads the password from a file instead of an env var.
+- `--no-fleet-verify` skips the post-deploy fleet sweep.
+
+Inline `--fabric-user`/`--fabric-password` flags also work but are **discouraged** — both leak to shell history and `ps`.
+
+### Backup before upgrading
+
+`flair snapshot` is local-only. Back up before every upgrade:
+
+```bash
+flair backup --url https://<cluster>.<org>.harperfabric.com \
+  --admin-pass-file <path> --output ./flair-backup.json
+```
+
+See [upgrade.md](upgrade.md#upgrading-a-fabric-deployed-instance) for the full walkthrough.
+
+---
+
+## Federation
+
+Available. Pair a local spoke to a Fabric-hosted hub:
+
+```bash
+# On any machine (no shell on the hub) — generate a pairing token triple
+FLAIR_ADMIN_PASS=<hub-admin-password> flair federation token \
+  --target https://<cluster>.<org>.harperfabric.com \
+  --ops-target <ops-url> > ./pair-triple.json
+
+# On the spoke — pair to the Fabric hub
+flair federation pair https://<cluster>.<org>.harperfabric.com \
+  --token-from ./pair-triple.json
+```
+
+### Pairing limitation
+
+The scheduled sync driver (`flair federation sync enable`) writes a launchd job or systemd timer **on the machine running the CLI** — it cannot be installed on a Fabric node. A periodic one-shot from the spoke machine is the workaround.
+
+Full walkthrough: [federation.md](federation.md).
+
+### Multi-region replication
+
+Fabric gives you N regional nodes running one component — **not** N Flair instances. Every node shares one Flair identity (the `Instance` table replicates). You do **not** federate your own regions to each other — Harper replication handles that. Use `flair federation pair` only to reach a **separate** Flair instance.
+
+---
+
+## Known operational limitations
+
+### No disk or quota telemetry
+
+`flair status` reports usage for two directories: no free space, no total, no quota. An instance can hit its quota with nothing saying so. The one indirect signal is a migration halting for space.
+
+### Unbounded npm cache
+
+Every deploy runs a server-side `npm install` using the node's default cache. npm never evicts it, so it grows until it fills the quota. There is no cache flag, alternate location, or cleanup option. [flair#886](https://github.com/tpsdev-ai/flair/issues/886).
+
+---
+
+## See also
+
+- [deployment-shapes.md](deployment-shapes.md) — choose your shape
+- [upgrade.md](upgrade.md#upgrading-a-fabric-deployed-instance) — full Fabric upgrade walkthrough
+- [federation.md](federation.md) — pairing, sync driver, conflict resolution
+- [standalone-local.md](standalone-local.md) — the standalone shape (different upgrade, shell available)
+- [secrets-and-keys.md](secrets-and-keys.md) — admin password, key lifecycle

package/docs/mcp-clients.md

@@ -203,7 +203,7 @@ Eleven tools, kept deliberately small:
 | Tool | What it does |
 |---|---|
 | `memory_search` | Semantic search across your agent's memories |
-| `memory_store` | Save a memory with type, durability, tags. Auto-dedups near-duplicates |
+| `memory_store` | Save a memory with type, durability, tags, visibility. Auto-dedups near-duplicates |
 | `memory_update` | Update an existing memory by ID — overwrite in place, or version it with `preserveHistory` |
 | `memory_get` | Fetch a specific memory by ID |
 | `memory_delete` | Remove a memory |
@@ -214,7 +214,9 @@ Eleven tools, kept deliberately small:
 | `flair_workspace_set` | Set your agent's current workspace state (ref/branch, phase, task) in the Office Space |
 | `flair_orgevent` | Publish an org-wide coordination event (claim/release/status) to the Office Space |
 
-Writes are scoped per-agent (your `FLAIR_AGENT_ID`) and enforced by Flair's server, not by client convention — you can't write as another agent. Reads are more open by design: any agent on the same Flair instance can read any other agent's non-private memories (open-within-org read; see [SECURITY.md](../SECURITY.md)). Mark a memory `visibility: private` to keep it owner-only.
+Writes are scoped per-agent (your `FLAIR_AGENT_ID`) and enforced by Flair's server, not by client convention — you can't write as another agent. Reads are more open by design: any agent on the same Flair instance can read any other agent's **non-private** memories, with no grant to set up (open-within-org read; see [SECURITY.md](../SECURITY.md)).
+
+Which memories are non-private is decided at write time, and the default is not "shared". `memory_store` defaults `durability` to `standard`, and the server derives visibility from durability — `permanent`/`persistent` → `shared`, `standard`/`ephemeral` → `private` — so **a bare `memory_store` call writes an owner-only memory that no other agent can read.** Pass `visibility: "shared"` (or `"private"`, to be explicit) to say what you mean; the tool reports the visibility the write actually landed on so an agent can confirm it rather than assume.
 
 ---
 

package/docs/quickstart.md

@@ -26,7 +26,9 @@ export PATH="$HOME/.npm-global/bin:$PATH"   # add this to ~/.zshrc or ~/.bashrc
 npm install -g @tpsdev-ai/flair
 ```
 
-One install gives you `flair`, `flair-mcp` and the client library.
+One install gives you one command: `flair`.
+
+The stdio adapter your MCP client talks to is a separate package, `@tpsdev-ai/flair-mcp`, and it is deliberately not installed globally — `flair init` wires each client to fetch it on demand with `npx -y @tpsdev-ai/flair-mcp@<version>`, so there is no second global package to keep in step. (The server also has its own `/mcp` endpoint built in, but it is off by default — it registers no route unless `FLAIR_MCP_OAUTH` and a public issuer are set — and no client setup in this guide uses it.) `@tpsdev-ai/flair-client` is a separate package you add to your own project when you want to call Flair from code.
 
 ## 2. Bootstrap Flair and register an agent
 
@@ -110,12 +112,35 @@ flair memory add --agent local "Harper v5 sandbox blocks node:module but process
 {
   "id": "local-1785277247486",
   "written": true,
-  "deduplicated": false
+  "deduplicated": false,
+  "visibility": "private"
 }
 ```
 
 Flair embedded the text locally on write. No network calls.
 
+### Who can read it
+
+`visibility: private` means **only `local` can read this memory** — no other agent on the instance can search it, fetch it by id, or receive it in a bootstrap.
+
+You didn't ask for that, and it isn't a setting you have to remember. Flair derives the default from the memory's **durability**, because how long a memory is meant to last is a good proxy for who it was meant for:
+
+| Durability | Default visibility |
+|---|---|
+| `permanent`, `persistent` | `shared` — a fact or decision worth keeping is worth the team being able to find |
+| `standard`, `ephemeral` — including a bare write with no `--durability` | `private` — working context and scratch state belong to the agent that produced them |
+
+So sharing is a deliberate act, and it takes one flag:
+
+```bash
+flair memory add --agent local --visibility shared \
+  "Release tags are cut from main, never from a release branch"
+```
+
+`--visibility` takes exactly `private` or `shared` — a value it doesn't recognise is an error, not a guess — and overrides the durability rule in both directions. The `visibility` field in the response is the value the memory actually landed on, so read it rather than assuming.
+
+Once a memory is `shared`, **every** agent on this instance can read it, with no grant to set up. That is the shipped model: reads open within one instance, closed at the federation edge. Full picture in [SECURITY.md](../SECURITY.md).
+
 ## 5. Find it back by meaning
 
 ```bash
@@ -131,7 +156,7 @@ You searched for a concept, not the keywords. The line under each hit is its cre
 
 > 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.
+Add `--explain` to see the ranking inputs per hit — the raw score, the composite score under `--scoring composite`, and the record's durability, age and usage count. When output is JSON (`--json`, or any time stdout is not a terminal) the same breakdown arrives as an `_explain` object on each hit, so scripts get it too. Use `--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
 
@@ -160,7 +185,7 @@ With the MCP server wired up — `flair init` does this automatically for every
 | You want to... | Go to |
 |----------------|-------|
 | Add more agents to the same instance | `flair agent add <id>` |
-| Keep a memory owner-only | `flair memory add --visibility private` — reads are otherwise open to every agent on the instance ([auth.md](auth.md)) |
+| Share a memory with your other agents | `flair memory add --visibility shared` — a bare write lands `private`, see [step 4](#who-can-read-it); a shared one is readable by every agent on the instance, no grant needed ([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) |

package/docs/secrets-and-keys.md

@@ -7,11 +7,11 @@ Flair owns **identity**. Flair does **not** own arbitrary secrets. This page dra
 For each registered agent, Flair stores:
 
 - A **public key** in the `Agent` table (server-side; used to verify signed requests).
-- A **private key** at `~/.flair/keys/<agent>.key` on the host that owns that agent (PKCS8 base64). Created by `flair agent add <id>`. Mode `0600`.
+- A **private key** at `~/.flair/keys/<agent>.key` on the host that owns that agent — the raw 32-byte Ed25519 seed. Created by `flair init --agent <id>` or `flair agent add <id>`. Mode `0600`.
 
 Agents sign every request to Flair with this key. Flair refuses unsigned requests and refuses signatures that don't match the registered public key. The signed payload is `<agentId>:<timestamp>:<nonce>:<METHOD>:<path>` with a 30-second replay window and nonce dedup — replays inside that window are rejected.
 
-**This is the only secret material Flair manages.** Lose the key file and the agent is locked out (`flair agent rotate <id>` to issue a new pair).
+**This is the only secret material Flair manages.** Lose the key file and the agent is locked out (`flair agent rotate-key <id>` to issue a new pair).
 
 ## Flair admin password (Harper instance)
 - If not provided via `--admin-pass`, `--admin-pass-file`, `FLAIR_ADMIN_PASS`, or `HDB_ADMIN_PASSWORD`, a random password is generated and written to `~/.flair/admin-pass` (mode `0o600`). The password is **not** printed to the console.
@@ -140,7 +140,7 @@ Hermes uses `~/.hermes/.env` for provider API keys (managed by `hermes auth`). T
 
 - **Stays on the host that owns the agent.** If your agent runs on a given host, the key lives on that host. If you spin up the same agent on another machine, **don't copy the key** — register a new agent identity (`flair agent add <id>-on-<other-host>`) on that machine. Different identities, same Flair instance can store memories for both, you decide cross-agent visibility.
 - **`chmod 600` enforced** by `flair agent add`. Don't relax it.
-- **Don't check it into git.** `.gitignore` should already exclude `~/.flair/keys/`; if you're ever tempted to share keys for "convenience," rotate first (`flair agent rotate <id>`).
+- **Don't check it into git.** `.gitignore` should already exclude `~/.flair/keys/`; if you're ever tempted to share keys for "convenience," rotate first (`flair agent rotate-key <id>`).
 - **Backup separately**, encrypted. The `flair backup` command excludes private keys by default. Roll your own backup of `~/.flair/keys/` via age-encrypted archive if you want offsite recovery.
 
 ## What about a `flair secret` CLI?
@@ -153,7 +153,7 @@ If you find yourself wanting one anyway, your agent can call `security find-gene
 
 | Asset | Owned by | If compromised → |
 |---|---|---|
-| Flair agent private key (`~/.flair/keys/<agent>.key`) | Flair (you, on the host) | Attacker can **write** memories under that agent's identity and read that agent's **`private`**-marked memories until you rotate. Use `flair agent rotate <id>`. Other agents' write identity is unaffected — they can't be impersonated with this key. |
+| Flair agent private key (`~/.flair/keys/<agent>.key`) | Flair (you, on the host) | Attacker can **write** memories under that agent's identity and read that agent's **`private`**-marked memories until you rotate. Use `flair agent rotate-key <id>`. Other agents' write identity is unaffected — they can't be impersonated with this key. |
 | LLM provider API keys (Anthropic, OpenAI, etc.) | OS keyring / 1Password | Standard provider revocation: rotate the key in the provider's console, update keyring entry. |
 | Cross-host secrets (1Password vault, age-sops) | The secret manager itself | Trust falls back to that manager's MFA / key handling. Document recovery in your team's ops runbook. |
 | Memory contents | Flair (server-side) | Write access requires the owning agent's key → see "Per-agent write isolation, org-wide non-private read" below. |