@tpsdev-ai/flair 0.29.0 → 0.31.0

package/docs/deploying-on-fabric.md

@@ -0,0 +1,267 @@
+# Deploying on Harper Fabric
+
+Run Flair as a component on [Harper Fabric](https://www.harperdb.io/) — managed, hosted,
+multi-region — instead of a local process you own. The hosted counterpart to
+[deployment.md](deployment.md); two things define it: you *deploy* rather than install,
+and **you get no shell on the node.**
+
+## When to use it
+
+| | Standalone local | Harper Fabric |
+|---|---|---|
+| You run | `flair init` | `flair deploy` |
+| Shell on the node | yes | **no** |
+| Multi-region / failover | no | yes |
+| Upgrade | `flair upgrade` | `flair upgrade --target <url>` |
+
+Choose Fabric for an always-on hub in more than one region. For a single instance on a VPS
+you already have, [Remote Server](../README.md#remote-server) is simpler and keeps your shell.
+
+---
+
+## Quickstart
+
+### 1. Deploy the 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
+
+flair deploy --fabric-org <org> --fabric-cluster <cluster>
+```
+
+Target defaults to `https://<cluster>.<org>.harperfabric.com`; override with `--target`.
+
+Credentials go via the environment, not argv, so they stay out of `ps`. Use
+`--fabric-password-file <path>` (mode `0600`) when scripting; inline flags leak to history.
+
+Deploy verifies the served API (Harper reports success for a component serving
+nothing; `--no-verify` opts out), waits 600s for replication (Harper's 120s default
+aborts mid-replicate on Fabric), and polls for convergence before reporting one.
+
+> `--fabric-token` is accepted but **fails** — `deploy_component` is Basic-auth only.
+
+### 2. Provision
+
+```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.
+
+Run **once**, before serving multi-region traffic — see
+[Multi-region](#multi-region-replication-vs-federation).
+
+### 3. Verify
+
+```bash
+curl -sf https://<cluster>.<org>.harperfabric.com/Health
+flair fleet verify --target https://<cluster>.<org>.harperfabric.com
+flair status --target https://<cluster>.<org>.harperfabric.com
+```
+
+### 4. Connect a client
+
+```bash
+export FLAIR_URL=https://<cluster>.<org>.harperfabric.com
+
+# Register an agent — --ops-target is required, see Ports below
+flair agent add mybot --target "$FLAIR_URL" --ops-target <ops-url>
+```
+
+Also set `FLAIR_PUBLIC_URL` to that URL in the component's environment — OAuth metadata
+and A2A discovery advertise it, or clients see a loopback address.
+
+---
+
+## Ports: the 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:
+
+```bash
+# --target https://<cluster>.<org>.harperfabric.com   → ops derived as :442  ✗
+# --target https://<fabric-node>:19926/<instance>     → ops derived as :19925 ✓
+```
+
+**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`.
+
+> **Gap — needs a Fabric account to verify.** This guide does not state the correct
+> ops-API URL for a managed `*.harperfabric.com` instance, or whether the ops API is
+> reachable remotely there at all. The derivation above is certain (read from source);
+> the right value to pass is not.
+
+Precedence: `--target` > `--url` > `FLAIR_TARGET` > `FLAIR_URL` > localhost. For ops:
+`--ops-target` > `FLAIR_OPS_TARGET` > derived > localhost.
+
+## Auth
+
+Flair ships `authorizeLocal: false` — it only governs loopback, so it changes nothing
+here; remote callers always need real credentials.
+
+- Admin ops use Basic auth; agents use Ed25519 ([auth.md](auth.md)).
+- `/Health` is public — your liveness check.
+- Don't debug with raw `curl` — on Fabric the auth gate fires before the resource
+  handler, so a hand-rolled request 401s in a way that looks like a Flair bug and isn't.
+
+---
+
+## Pairing a spoke to a hosted hub
+
+No shell on the hub, so mint the token remotely rather than over `ssh`:
+
+```bash
+# On any machine — note --ops-target, this hits the ops API
+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
+flair federation pair https://<cluster>.<org>.harperfabric.com \
+  --token-from ./pair-triple.json
+```
+
+`federation token` takes `--admin-pass`, **not** `--admin-pass-file`. The triple holds a
+one-time credential — delete it after pairing (60-min TTL, `--ttl`).
+
+### Federation is push-only
+
+**A spoke pushes up. It cannot pull down.** `POST /FederationSync` is one-directional per
+call and there is no pull endpoint anywhere.
+
+For both directions, each side pairs **as a spoke of the other**: two pairings, two
+tokens, two syncs. No setting makes sync bidirectional.
+
+Syncs `Memory`, `Soul`, `Agent`, `Relationship`. **`Presence` is not federated** — no
+cross-spoke roster.
+
+### Keeping a spoke synced
+
+`flair federation sync` is one-shot; `watch` dies with its terminal. Use the scheduled
+driver ([federation.md](federation.md#keeping-it-synced)):
+
+```bash
+flair federation sync enable --interval 300
+flair federation sync status
+```
+
+> **The driver is local-only.** It writes a launchd job or systemd timer **on the machine
+> running the CLI**; `--target` just points that local job at a remote instance. You
+> cannot install a driver on a Fabric node.
+
+A periodic one-shot, not a supervised watcher; `--interval` is the latency knob.
+`flair federation status` omits its driver verdict for a remote `--target`.
+
+---
+
+## Multi-region: replication vs federation
+
+Fabric gives you N regional nodes running one component — **not** N Flair instances.
+Instance identity lives in the `Instance` table (`schemas/federation.graphql`); it is a
+Harper table, so **it replicates** — every node shares one Flair identity.
+
+| Layer | Handles | Scope |
+|---|---|---|
+| Harper replication | your app across its own regions | intra-app, automatic |
+| Flair federation | this app ↔ another Flair instance | instance-to-instance, you pair it |
+
+**You do not federate your own regions to each other** — Harper already did. Use
+`flair federation pair` only to reach a *separate* Flair instance.
+
+One asymmetry: identity replicates, but `flair-instance.yaml` (port config, per data
+directory) does not. A node reporting a different **port** is expected; a different
+**instance id** is not.
+
+Provision once, from one place, before serving multi-region traffic: step 2's
+`flair init … --remote` seeds the identity row so it exists before any node needs it.
+
+---
+
+## Operating it
+
+### What works remotely
+
+| Command | Gives you |
+|---|---|
+| `GET /Health` | liveness, no auth |
+| `flair status --target <url>` | subsystem rollups; the only byte counts available remotely |
+| `flair quality --target <url>` | recall/coverage; halted-migration reasons |
+| `flair fleet verify --target <url>` | health, auth, version across origin + Flair peers |
+| `flair federation status\|verify\|reachability --target <url>` | peer table, sync recency, probes |
+
+`fleet verify` exit codes: 1 origin failed, 2 peer version skew, 3 peer unverifiable.
+
+> **A credential mismatch renders as an empty section, not an error.** `flair status`
+> reads `/HealthDetail` with `FLAIR_ADMIN_PASS` / `HDB_ADMIN_PASSWORD` / a pinned agent
+> key — **not** the `FABRIC_*` credentials `deploy` and `fleet verify` use. On failure it
+> renders blank — a blank Disk section means "couldn't authenticate" as often as
+> "nothing to report".
+
+### What doesn't
+
+**`flair doctor` takes no `--target`** — it hardcodes localhost, reads a local PID file
+and shells out to `lsof`. The command you'd reach for when something breaks is unavailable
+here. 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 and absent
+from the OSS `harper` build. **`0 peers known` means "0 on file", never "0 exist."**
+
+**There is no disk or quota telemetry.** `flair status` reports usage for two directories:
+no free space, no total, no quota, no warning threshold, walk capped at six levels, no
+per-component size. `system_information` is never called — an instance can hit its quota
+with nothing saying so. The one indirect signal is a migration halting for space.
+
+> **On `get_components`.** A source comment claims Harper excludes `node_modules`
+> server-side. That is uncited and unverified, so this guide doesn't rely on it — and it
+> wouldn't matter: Flair calls it only as a post-failure convergence oracle and discards
+> the `size` field. Component disk usage is invisible structurally.
+
+### Known hazard: unbounded npm cache
+
+**Open — [flair#886](https://github.com/tpsdev-ai/flair/issues/886).** 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.
+
+No in-product mitigation: no cache flag, no alternate location, no cleanup. One install
+per deploy bounds the *rate*, not the total. Harper consults `install_command` only when
+`node_modules` is absent and `deploy_component` has no force-reinstall option, so the
+obvious fix isn't available — and clearing the cache needs node access this shape
+doesn't give you.
+
+### Backup and rollback
+
+`flair snapshot` is local-only. Back up before every upgrade — `flair backup` takes
+**`--url`**, not `--target`:
+
+```bash
+flair backup --url https://<cluster>.<org>.harperfabric.com \
+  --admin-pass-file <path> --output ./flair-backup.json
+
+# --check shows the version diff and plan without deploying
+flair upgrade --target https://<cluster>.<org>.harperfabric.com --check
+```
+
+Full path: [upgrade.md](upgrade.md#upgrading-a-fabric-deployed-instance).
+
+---
+
+## See also
+
+- [deployment.md](deployment.md) — the standalone local shape
+- [upgrade.md](upgrade.md#upgrading-a-fabric-deployed-instance) — Fabric upgrades, fleet verify
+- [federation.md](federation.md) — pairing, sync driver, conflict resolution
+- [spoke-bringup.md](spoke-bringup.md) · [auth.md](auth.md) · [secrets-and-keys.md](secrets-and-keys.md)

package/docs/deployment.md

@@ -116,6 +116,11 @@ Note: embeddings run on CPU in Docker (no Metal acceleration). Performance is ac
 
 Deploying to a Harper Fabric cluster is a different mechanism from the installs above — `flair deploy` pushes Flair as a cluster component instead of `npm install -g`. To upgrade an already-deployed Fabric instance in place, use `FABRIC_USER=<admin> FABRIC_PASSWORD=<pass> flair upgrade --target <fabric-url>` (or `--fabric-password-file <path>` in place of the env var), not the local upgrade path. Inline `--fabric-user`/`--fabric-password` flags also work but are discouraged — both leak to shell history and `ps`. See [`docs/upgrade.md` — Upgrading a Fabric-deployed instance](upgrade.md#upgrading-a-fabric-deployed-instance) for the full walkthrough, including the automatic post-deploy fleet-convergence sweep.
 
+For the hosted shape end to end — when to choose it, ports and auth against a managed
+Fabric endpoint, pairing local spokes to a hosted hub, and what you can and cannot
+observe without a shell on the node — see
+[`docs/deploying-on-fabric.md`](deploying-on-fabric.md).
+
 ---
 
 ## Remote Access
@@ -179,6 +184,7 @@ Set these in the Flair process environment (`~/Library/LaunchAgents/ai.tpsdev.fl
 | `HDB_ADMIN_PASSWORD` | Bootstrap password for the embedded Harper. After first start, the persisted user record is the source of truth; rotate via the Harper ops API, not by changing this env var. | Set at install time. See [secrets-and-keys.md](secrets-and-keys.md) for rotation. |
 | `FLAIR_KEY_PASSPHRASE` | Passphrase used to derive the AES-256-GCM key that wraps federation private-key seeds at rest. Auto-generated to `~/.flair/keys/.passphrase` if unset. | Set explicitly for production federation deployments so the passphrase isn't auto-generated and lost on disk wipe. |
 | `HTTP_PORT` | Override the Harper HTTP port. Useful for sandboxes; production deployments should configure the port in `config.yaml` instead. | Rare. |
+| `FLAIR_OPS_BIND` | Bind address for the Harper **ops API**. Resolution order: `flair init --ops-bind` > this variable > the `opsBind` key `flair init` persists in `~/.flair/config.yaml` > `127.0.0.1`. Every Flair-managed Harper start re-asserts the resolved value, so the persisted key is what makes a choice survive `flair restart` / `flair upgrade`. | Only for deployments that genuinely need remote ops admin (multi-host / Fabric) — set it to `0.0.0.0`, or record it once with `flair init --ops-bind 0.0.0.0`. Single-host installs want the loopback default. |
 
 ---
 

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)