@tpsdev-ai/flair 0.26.0 → 0.27.0

package/docs/assets/flair-cross-orchestrator.cast

@@ -0,0 +1,33 @@
+{"version": 3, "term": {"cols": 96, "rows": 28}, "timestamp": 1778889600, "command": "/tmp/flair-cross-orchestrator-script.sh", "env": {"SHELL": "/bin/zsh"}}
+[0.245, "o", "\u001b[H\u001b[J"]
+[0.001, "o", "  Flair  \u00b7  same identity, every orchestrator\r\n  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n\r\n"]
+[1.3, "o", "$ # One agent identity. One memory store. Three orchestrators.\r\n"]
+[1.2, "o", "$ flair init --client all --agent flint\r\n"]
+[0.5, "o", "  \u001b[32m\u2713\u001b[0m Claude Code   wired (~/.claude/mcp.json)\r\n"]
+[0.18, "o", "  \u001b[32m\u2713\u001b[0m Codex CLI     wired (~/.codex/config.toml)\r\n"]
+[0.18, "o", "  \u001b[32m\u2713\u001b[0m Gemini CLI    wired (~/.gemini/settings.json)\r\n\r\n"]
+[1.0, "o", "  Each MCP client now connects to:  http://127.0.0.1:9926\r\n"]
+[0.0, "o", "  Ed25519 keypair shared:           ~/.flair/keys/flint.ed25519\r\n\r\n"]
+[2.2, "o", "$ # \u2500\u2500 Claude Code: agent writes a memory \u2500\u2500\r\n"]
+[0.7, "o", "$ claude\r\n"]
+[0.5, "o", "\u001b[36mflint>\u001b[0m \u001b[2mremember: we picked Postgres for replication-lag reasons; ScyllaDB ruled out by ops complexity\u001b[0m\r\n"]
+[1.8, "o", "  \u001b[32m\u2713\u001b[0m wrote memory mem_2026-05-14_3f9a (durability=persistent)\r\n\r\n"]
+[1.5, "o", "$ # \u2500\u2500 New session. Different orchestrator. Same identity. \u2500\u2500\r\n"]
+[1.0, "o", "$ codex\r\n"]
+[0.5, "o", "\u001b[36mflint>\u001b[0m \u001b[2mwhat database did we pick and why?\u001b[0m\r\n"]
+[1.5, "o", "  \u001b[32m\u2713\u001b[0m bootstrap: 287 memories loaded for agent flint\r\n"]
+[0.4, "o", "  Postgres \u2014 chosen for replication-lag reasons.\r\n"]
+[0.0, "o", "  ScyllaDB was ruled out by ops complexity.\r\n"]
+[0.0, "o", "  \u001b[2m(source: mem_2026-05-14_3f9a, written via Claude Code 4m ago)\u001b[0m\r\n\r\n"]
+[2.0, "o", "$ # \u2500\u2500 New session. Another orchestrator. Same identity. \u2500\u2500\r\n"]
+[1.0, "o", "$ gemini\r\n"]
+[0.5, "o", "\u001b[36mflint>\u001b[0m \u001b[2msummarize our recent infra decisions\u001b[0m\r\n"]
+[1.7, "o", "  \u001b[32m\u2713\u001b[0m bootstrap: same 287 memories, same soul, same Ed25519 identity\r\n"]
+[0.5, "o", "  \u2022 Postgres for replication-lag (2026-05-14)\r\n"]
+[0.0, "o", "  \u2022 Federation pair: local\u2192Fabric via Ed25519 (2026-05-05)\r\n"]
+[0.0, "o", "  \u2022 REM nightly cycle ships in v0.9.0 (2026-05-14)\r\n\r\n"]
+[2.5, "o", "  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n"]
+[0.0, "o", "  No SaaS in the middle.  No vendor lock.\r\n"]
+[0.0, "o", "  Memory follows the agent across orchestrators.\r\n"]
+[0.0, "o", "\r\n  github.com/tpsdev-ai/flair  \u00b7  Apache 2.0\r\n\r\n"]
+[5.0, "x", "0"]

package/docs/assets/flair-demo.cast

@@ -0,0 +1,18 @@
+{"version":3,"term":{"cols":80,"rows":24},"timestamp":1778359292,"command":"/tmp/flair-demo-script.sh","env":{"SHELL":"/bin/zsh"}}
+[0.245, "o", "\u001b[H\u001b[J"]
+[0.001, "o", "  Flair  ·  identity infrastructure for AI agents\r\n  ─────────────────────────────────────────────\r\n\r\n"]
+[1.520, "o", "$ # Agent writes a memory\r\n"]
+[0.628, "o", "$ flair memory add --agent flint-demo --content \"Postgres replication lag spiked when we added the read-replica\"\r\n"]
+[0.796, "o", "{\r\n  \"ok\": true\r\n}\r\n"]
+[1.411, "o", "\r\n"]
+[0.000, "o", "$ # Six months later — find it by meaning, not keywords\r\n"]
+[0.509, "o", "$ flair search \"why did our database fall behind during scaling\" --agent flint-demo\r\n"]
+[0.824, "o", "  Postgres replication lag spiked when we added the read-replica\r\n  (2026-05-09)\r\n"]
+[0.000, "o", "\r\n"]
+[2.054, "o", "\r\n$ # Same memory, every harness.\r\n"]
+[0.630, "o", "$ # Claude Code · Cursor · Codex CLI · Gemini CLI · Continue.dev · Goose\r\n$ #          all via   @tpsdev-ai/flair-mcp\r\n$ # LangGraph         @tpsdev-ai/langgraph-flair\r\n$ # OpenClaw          @tpsdev-ai/openclaw-flair\r\n$ # n8n               @tpsdev-ai/n8n-nodes-flair\r\n$ # Hermes Agent      packages/hermes-flair  (Python)\r\n$ # Pi agent          @tpsdev-ai/pi-flair\r\n"]
+[2.125, "o", "\r\n"]
+[0.000, "o", "  ─────────────────────────────────────────────\r\n"]
+[0.000, "o", "  Apache 2.0  ·  self-hosted  ·  no SaaS in the middle\r\n  github.com/tpsdev-ai/flair\r\n"]
+[0.000, "o", "\r\n"]
+[5.147, "x", "0"]

package/docs/auth.md

@@ -0,0 +1,178 @@
+# Authentication & Authorization
+
+Flair supports three authentication methods, from simplest to most enterprise-ready.
+
+## Auth across surfaces (read this first)
+
+Different surfaces authenticate differently. The model in one place:
+
+| Surface | Auth | Scope | Notes |
+|---------|------|-------|-------|
+| **CLI / SDK clients** (`flair`, `flair-client`) | **Ed25519 per-agent** | Own writes; org-wide non-private reads | Default, recommended. Signs every request; an agent can never write as another, and reads are scoped to its own memories (any visibility) plus every other agent's **non-private** memories on the instance. |
+| **MCP server** (`@tpsdev-ai/flair-mcp`) | **Ed25519 per-agent** | Own writes; org-wide non-private reads | Same per-agent identity as the CLI — key auto-resolved from `~/.flair/keys/<agent>.key`. |
+| **OpenClaw / pi / Hermes plugins** | **Ed25519 per-agent** | Own writes; org-wide non-private reads | Same secure path; auto-detect agent identity. |
+| **`n8n-nodes-flair`** | **Harper admin-password Basic auth** | ⚠️ **Whole instance, read + write, including `private`** | The admin credential bypasses agent scoping entirely — every workflow gets read/write on the *entire* memory store, including other agents' `private`-marked memories, not just the org-wide non-private pool an Ed25519 identity would see. |
+
+**The default, secure path is Ed25519 per-agent** (see below): each agent holds its own key and signs every request. That guarantees **write isolation** — no agent can write as another — and identity-verified reads. It does **not** mean cross-agent reads are refused: within one Flair instance (one org), any verified agent can read any other agent's memory unless that memory is explicitly marked `visibility: private` (owner-only). The hard access boundary is the **federation edge** (a separate Flair instance / org), not reads within an instance. See [SECURITY.md](../SECURITY.md) for the full model. Use Ed25519 per-agent everywhere you can regardless — it's still what makes writes and identity trustworthy.
+
+### Known limitation — n8n uses admin-password Basic auth
+
+The `n8n-nodes-flair` community node authenticates with the Harper **admin password** (Basic auth), which bypasses agent scoping entirely — not just the org-wide non-private reads an Ed25519 identity already gets. Concretely, an n8n workflow using the admin credential can write memories under *any* agent's identity (no per-agent write isolation) and can read *every* memory including ones marked `visibility: private` (which stay owner-only under normal Ed25519 auth). This is acceptable only when **all** of the following hold:
+
+- The n8n instance is single-tenant and operator-controlled.
+- Workflow inputs are trusted (your own CRM, your own webhook source).
+- Write-forgery and full read access (including `private` memories) are acceptable for the use case.
+
+If any of those don't hold, use Flair's CLI / SDK clients (which support per-agent Ed25519 today) and wait for the n8n credential to gain Ed25519 per-agent auth (planned). Full guidance in [docs/n8n.md](n8n.md#security).
+
+## Ed25519 Agent Auth (Default)
+
+Every agent has an Ed25519 key pair. Requests are signed with `agentId:timestamp:nonce:METHOD:/path` and verified against the agent's registered public key. 30-second replay window with nonce deduplication.
+
+```bash
+# Register an agent
+flair agent add myagent
+
+# The key is stored at ~/.flair/keys/myagent.key
+# Requests are signed automatically by flair-client and the MCP server
+```
+
+This is the default and recommended auth for single-instance deployments.
+
+## Deployment shapes: personal vs org
+
+Flair has no `mode`/`shape` config setting — the shape you get is emergent from *how you provision principals*, not something you declare:
+
+- **Personal (the default).** `flair init` mints ONE agent identity and wires that same `FLAIR_AGENT_ID` into every MCP client it configures (Claude Code, Codex, Gemini, Cursor). One human driving several AI clients ends up with one canonical principal and one Ed25519 keypair — all clients share ownership of the same memory. This is intentional, not a limitation: all clients see each other's private rows (one human's memory, one view), a fact re-asserted from two different clients dedups to one memory, and usage counting treats the principal as one contributor.
+- **Org (multiple real agents).** `flair agent add <id>` mints a distinct principal — its own keypair, its own ownership boundary — for each real agent that should be a separate identity. Wire each principal's own `FLAIR_AGENT_ID` into its own client(s).
+
+Nothing in flair validates which shape you're in; a personal install that later grows into an org just runs `flair agent add` for the new distinct identities it needs.
+
+### Authorship: which client wrote a row
+
+The personal shape's one shared principal means `agentId` alone can't answer "was this written by Claude Code or Codex?" — every write it receives has the same owner. `flair init`'s per-client wiring closes that gap by setting an additional env var per client: `FLAIR_CLIENT` (`"claude-code"` / `"codex"` / `"gemini"` / `"cursor"`). `flair-client` and `flair-mcp` forward it on memory writes as `claimedClient`, and the server folds it into the write's `provenance` blob as `claimed.client` — self-reported, unverified metadata recording *which tool* authored a row, alongside the existing `claimed.model`.
+
+This is deliberately in `claimed`, never `verified`: it carries **zero authority**. It is never read for access control, read-scope, attribution weighting, or dedup decisions — it exists purely for audit/analysis. Absent on any install that predates this field (no backfill, no migration) and absent whenever a client doesn't set `FLAIR_CLIENT`.
+
+The native `/mcp` OAuth surface (see below) doesn't need any client-side wiring at all: the handler stamps `claimed.client` directly from the OAuth token's verified `client_id` claim — the server-generated `flair_cl_...` machine id assigned at Dynamic Client Registration, **not** the user-supplied `client_name` (which the registering client fully controls and could set to anything). Using `client_id` keeps the stamp a stable, server-verified label even though it still only carries `claimed`-level (unverified-by-content) authority.
+
+## OAuth 2.1
+
+Flair includes a built-in OAuth 2.1 authorization server for client integrations (e.g., Claude connecting to Flair as an MCP server).
+
+### Dynamic Client Registration
+
+Clients register automatically on first connection:
+
+```
+POST /OAuthRegister
+Content-Type: application/json
+
+{
+  "client_name": "Claude Desktop",
+  "redirect_uris": ["http://localhost:3000/callback"],
+  "grant_types": ["authorization_code"],
+  "response_types": ["code"],
+  "token_endpoint_auth_method": "none"
+}
+```
+
+Returns `client_id` and `client_secret` (if applicable).
+
+### Authorization Code Flow with PKCE
+
+Standard OAuth 2.1 authorization code flow:
+
+1. Client generates PKCE `code_verifier` and `code_challenge`
+2. Client redirects user to `GET /OAuthAuthorize?client_id=...&code_challenge=...&redirect_uri=...`
+3. User approves (or auto-approves for trusted clients)
+4. Flair redirects back with authorization code
+5. Client exchanges code for access token at `POST /OAuthToken`
+
+### Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/OAuthRegister` | POST | Dynamic client registration |
+| `/OAuthAuthorize` | GET/POST | Authorization endpoint |
+| `/OAuthToken` | POST | Token endpoint |
+| `/.well-known/oauth-authorization-server` | GET | Server metadata |
+
+## XAA (Enterprise-Managed Authorization)
+
+For organizations using an Identity Provider (IdP), XAA lets the IdP control who accesses Flair and with what scopes.
+
+### How It Works
+
+1. User authenticates with the organization's IdP (Google, Azure AD, Okta)
+2. IdP issues an ID token (JWT) with user identity and group claims
+3. Client sends the ID token to Flair's token endpoint using the `jwt-bearer` grant type
+4. Flair validates the JWT signature, checks issuer/domain, maps to a Principal, and issues a scoped access token
+
+```
+POST /OAuthToken
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
+&assertion=<id-token-from-idp>
+```
+
+### IdP Configuration
+
+Register an IdP with the CLI:
+
+```bash
+flair idp add \
+  --name "Google Workspace" \
+  --issuer "https://accounts.google.com" \
+  --jwks-uri "https://www.googleapis.com/oauth2/v3/certs" \
+  --required-domain "yourcompany.com"
+```
+
+### Supported IdPs
+
+| IdP | Issuer | Domain Claim |
+|-----|--------|-------------|
+| Google Workspace | `https://accounts.google.com` | `hd` (hosted domain) |
+| Azure AD (Entra) | `https://login.microsoftonline.com/{tenant}/v2.0` | `tid` (tenant ID) |
+| Okta / Auth0 | `https://{org}.okta.com` | Issuer-scoped |
+
+### Scopes
+
+| Scope | Description |
+|-------|-------------|
+| `memory:read` | Read memories and search |
+| `memory:write` | Write and delete memories |
+| `memory:admin` | Memory maintenance operations |
+| `principal:read` | View principal list |
+| `principal:admin` | Create/modify/disable principals |
+| `connector:admin` | Manage OAuth clients and IdPs |
+
+### JIT Provisioning
+
+First-time IdP users are automatically created as `unverified` principals. An admin can promote them to `verified` or `admin` via:
+
+```bash
+flair principal promote <principal-id>
+```
+
+### CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `flair idp add` | Register an IdP |
+| `flair idp list` | List configured IdPs |
+| `flair idp remove <id>` | Remove an IdP |
+| `flair idp test <id>` | Test IdP connectivity |
+
+## Web Admin
+
+The web admin at `/AdminDashboard` provides a UI for managing:
+
+- **Principals:** view, promote, disable agents and users
+- **Connectors:** OAuth clients and active sessions
+- **IdP:** enterprise identity provider configuration
+- **Memory:** browse and search stored memories
+- **Instance:** federation status, peer connections
+
+Access requires admin-level authentication (Basic auth with the Harper admin password).

package/docs/bridges.md

@@ -0,0 +1,291 @@
+# Memory Bridges
+
+> Pluggable import/export between Flair and foreign memory systems.
+
+Flair stores memories in its own schema. The rest of the agent ecosystem stores memories too — agentic-stack's `.agent/` directory, Mem0, Letta, Zep, Anthropic memory, and more every week. **Bridges** let Flair speak those formats without a core-code change per integration.
+
+The design goal is *agent-authorable first*: a capable agent should be able to ship a working bridge by reading this doc and running one command.
+
+## Two shapes
+
+| Shape | When to use | Artifact |
+|-------|-------------|----------|
+| **File** (YAML descriptor) | Foreign system stores memories as files on disk (`.agent/`, JSONL, Markdown) | `.flair-bridge/<name>.yaml` in a project, or `~/.flair/bridges/<name>.yaml` user-wide |
+| **API** (TypeScript plugin) | Foreign system exposes an HTTP API (Mem0, Letta, Zep, Anthropic memory) | npm package named `flair-bridge-<name>` |
+
+Pick one. The runtime normalizes both into the same memory-record shape before import.
+
+## The memory record
+
+Every bridge deals in `BridgeMemory` objects. Fields:
+
+```ts
+interface BridgeMemory {
+  // Identity
+  id?: string              // Flair ID if round-tripping; omit on first import
+  foreignId?: string       // original ID in the foreign system (preserved)
+
+  // Content
+  content: string          // REQUIRED
+  subject?: string
+  tags?: string[]
+  visibility?: "private" | "shared" | "public"
+
+  // Durability & lifecycle
+  durability?: "ephemeral" | "standard" | "persistent" | "permanent"
+  createdAt?: string       // ISO-8601; defaults to now on import
+  validFrom?: string
+  validTo?: string
+  expiresAt?: string
+
+  // Ownership
+  agentId?: string         // required on import unless --agent is passed
+
+  // Provenance
+  source?: string
+  derivedFrom?: string[]
+}
+```
+
+**Required on import:** `content` and (`agentId` or the `--agent` flag).
+
+**Flair-owned, never set by a bridge:** `contentHash`, `embedding`, `embeddingModel`, `retrievalCount`, `lastRetrieved`, `promotionStatus`, `_safetyFlags`, any `*By` audit field. These are computed on ingest; if a bridge emits them they're ignored.
+
+## Commands
+
+```bash
+flair bridge list                           # installed bridges
+flair bridge scaffold <name> [--file|--api] # emit starter files
+flair bridge import <name> [src] [opts]     # foreign → Flair (Shape A YAML / built-ins)
+flair bridge test <name> [--fixture <path>] # round-trip diff (coming in slice 3)
+flair bridge export <name> <dst> [opts]     # Flair → foreign (coming in slice 3)
+```
+
+`list`, `scaffold`, and `import` are live as of 0.6.0+. `test` and `export` are stubbed with pointers to slice 3.
+
+Common runtime options for `import`:
+
+| Flag | Meaning |
+|------|---------|
+| `--agent <id>` | Default agent ID for memories that don't carry one (or set `FLAIR_AGENT_ID`) |
+| `--cwd <dir>` | Filesystem root the descriptor's relative paths resolve against (default: cwd) |
+| `--dry-run` | Parse + validate + count, don't write to Flair |
+| `--port <port>` | Harper HTTP port |
+| `--url <url>` | Flair base URL (overrides `--port`) |
+| `--key <path>` | Ed25519 private key path (default: resolved from agent) |
+
+## Your first import (worked example: agentic-stack)
+
+`agentic-stack` ships as a built-in. Drop into a directory that has agentic-stack lessons and run:
+
+```bash
+$ flair bridge list
+  name           kind  source   description
+  agentic-stack  file  builtin  Import agentic-stack lessons.jsonl into Flair persistent memories
+
+$ ls .agent/memory/semantic/
+lessons.jsonl
+
+$ flair bridge import agentic-stack --agent mybot --dry-run
+agentic-stack: would import 47 memories. Re-run without --dry-run to write to Flair.
+
+$ flair bridge import agentic-stack --agent mybot
+  47 imported (lesson-47)
+agentic-stack: imported 47/47 memories.
+```
+
+Each lesson lands as a Flair memory tagged `source: "agentic-stack/lessons"` with `durability: persistent`, the foreign `id` preserved as `foreignId` (so re-importing is idempotent on the same source).
+
+A few things worth knowing:
+
+- **`--agent` is required** unless your descriptor maps an `agentId` column. If you forget, `flair bridge import` errors with a one-line operator-pointer hint plus a structured `BridgeRuntimeError` JSON on stderr.
+- **`--dry-run` is your friend.** Validates the descriptor, parses every record, applies the mapping, but skips the PUT. Use it to confirm the count and check a few records before committing.
+- **Output is throttled** to one progress line every 2 seconds (or every 25 records, whichever comes first), so big imports don't flood your terminal.
+- **Errors are structured.** Every error includes `bridge`, `op`, `path`, `record`, `field`, `expected`, `got`, `hint` (per [§10 of the spec](../specs/FLAIR-BRIDGES.md#-10-error-format)). The `hint` is the part you act on; the rest is for an LLM to self-correct without operator help.
+
+## Shape A — Declarative YAML
+
+For bridges whose source or target is a directory of files, write a YAML descriptor. No code required.
+
+```yaml
+# .flair-bridge/agentic-stack.yaml
+name: agentic-stack
+version: 1
+kind: file
+description: "agentic-stack .agent/memory/semantic/lessons.jsonl"
+
+detect:
+  anyExists:
+    - ".agent/AGENTS.md"
+    - ".agent/memory/semantic/lessons.jsonl"
+
+import:
+  sources:
+    - path: ".agent/memory/semantic/lessons.jsonl"
+      format: jsonl
+      map:
+        content: "$.claim"
+        subject: "$.topic"
+        tags: "$.tags"
+        foreignId: "$.id"
+        durability: "persistent"
+        source: "agentic-stack/lessons"
+
+export:
+  targets:
+    - path: ".agent/memory/semantic/lessons.jsonl"
+      format: jsonl
+      when: "durability in ['persistent', 'permanent']"
+      map:
+        id: "foreignId ?? id"
+        claim: "content"
+        topic: "subject"
+        tags: "tags"
+```
+
+- **Path expressions:** JSONPath subset — `$.field`, `$.nested.field`, `$.array[*]`.
+- **`when:`** boolean expression over `BridgeMemory` fields. Omit for "always".
+- **Formats supported in 1.0:** `jsonl`, `json`, `yaml`, `markdown-frontmatter`.
+- **What the runtime gives you:** file discovery, format parsing, schema validation, error reporting with `line:column`. You only describe the mapping.
+
+## Shape B — Code plugin
+
+For bridges that talk to HTTP APIs:
+
+```ts
+// flair-bridge-mem0/index.ts
+import type { MemoryBridge, BridgeMemory, BridgeContext } from "@tpsdev-ai/flair";
+
+export const bridge: MemoryBridge = {
+  name: "mem0",
+  version: 1,
+  kind: "api",
+
+  options: {
+    apiKey:  { env: "MEM0_API_KEY", required: true, description: "Mem0 API token" },
+    userId:  { required: true, description: "Mem0 user ID" },
+    baseUrl: { default: "https://api.mem0.ai" },
+  },
+
+  async *import(opts, ctx: BridgeContext) {
+    const res = await ctx.fetch(`${opts.baseUrl}/v1/memories/?user_id=${opts.userId}`, {
+      headers: { Authorization: `Token ${opts.apiKey}` },
+    });
+    const payload = await res.json();
+    for (const m of payload.results ?? []) {
+      yield {
+        foreignId: String(m.id),
+        content: String(m.memory),
+        createdAt: m.created_at,
+        tags: m.categories,
+        source: "mem0",
+      };
+    }
+  },
+
+  async export(memories, opts, ctx) {
+    for await (const m of memories) {
+      await ctx.fetch(`${opts.baseUrl}/v1/memories/`, {
+        method: "POST",
+        headers: { Authorization: `Token ${opts.apiKey}` },
+        body: JSON.stringify({
+          messages: [{ role: "user", content: m.content }],
+          user_id: opts.userId,
+        }),
+      });
+    }
+  },
+};
+```
+
+**`BridgeContext`** gives you:
+
+- `ctx.fetch` — instrumented, rate-limited HTTP. **Always use this instead of the global `fetch`** — it's how the runtime applies per-bridge throttling and audit logging.
+- `ctx.log` — structured `{debug, info, warn, error}` logger.
+- `ctx.cache` — per-bridge key/value cache with optional TTL. Useful for pagination cursors, auth refresh, etc.
+
+Code plugins have no direct filesystem or network access outside `ctx`. This keeps the surface area small and auditable.
+
+## Discovery
+
+`flair bridge list` scans, in precedence order:
+
+1. **Built-ins** shipped inside `@tpsdev-ai/flair`
+2. **Project YAML** — `.flair-bridge/*.yaml` in the current working directory
+3. **User YAML** — `~/.flair/bridges/*.yaml`
+4. **npm packages** — anything matching `flair-bridge-*` or `@scope/flair-bridge-*` under `node_modules/`
+
+Earlier sources win on name conflict. So a built-in adapter can't be accidentally shadowed by a same-named npm package, but a project-local YAML *can* intentionally override an npm bridge for local development.
+
+## Distribution
+
+Publish bridges to npm as `flair-bridge-<name>`. Example `package.json`:
+
+```json
+{
+  "name": "flair-bridge-mem0",
+  "version": "0.1.0",
+  "description": "Flair bridge for Mem0",
+  "main": "index.js",
+  "flair": { "kind": "api", "version": 1 },
+  "peerDependencies": { "@tpsdev-ai/flair": ">=0.6.0" }
+}
+```
+
+There's no registry to curate; npm is the registry. `flair bridge list` surfaces everything installed.
+
+## Round-trip testing
+
+Every bridge ships a fixture. `flair bridge test <name>` will run (slice 2):
+
+1. Import the fixture → `BridgeMemory[]`
+2. Export those memories to a tmp target
+3. Re-import the tmp target → `BridgeMemory[]`
+4. Structural diff on the round-trip-stable fields: `content`, `subject`, `tags`, `durability`
+5. Pass iff the diff is empty
+
+Pass = ship. Iterate against this signal.
+
+## Trust and security
+
+Different sources have different blast radii.
+
+| Source | Default trust |
+|--------|---------------|
+| Built-in | Allowed |
+| Declarative YAML (no code) | Allowed; remote API calls require `--allow-remote` at invocation |
+| Code plugin from npm | Requires `flair bridge allow <name>` on first use |
+| Remote API calls | Always require `--allow-remote` on the invocation |
+
+A code plugin is untrusted JavaScript. The explicit `allow` gate keeps an unreviewed npm package from executing on your machine the first time `flair bridge import` names it. VM isolation is a 1.1 hardening pass.
+
+## Error format
+
+Every bridge error is structured:
+
+```json
+{
+  "bridge": "agentic-stack",
+  "op": "import",
+  "path": ".agent/memory/semantic/lessons.jsonl",
+  "record": 42,
+  "field": "$.claim",
+  "expected": "string",
+  "got": "null",
+  "hint": "lessons.jsonl row 42 has no 'claim' field — skipped"
+}
+```
+
+Printed as a single JSON object per line when `--json`; human-formatted otherwise. Field paths, expected/got, and a hint — that's the minimum an LLM needs to self-correct without operator help.
+
+## Writing your own — the prompt
+
+If you want an agent to write a bridge for you, here's the one-shot prompt:
+
+> You are implementing a Flair bridge for **\<FOREIGN_SYSTEM\>**. Read the sections above on the memory record, on Shape A (file-format targets) or Shape B (API targets) depending on \<FOREIGN_SYSTEM\>, and on round-trip testing. Produce either `.flair-bridge/<name>.yaml` (file targets) or an `index.ts` implementing `MemoryBridge` (API targets). Include a fixture at `fixtures/<name>.fixture.json` or `fixtures/<name>.mock.json`. Run `flair bridge test <name>` and iterate until the round-trip diff is empty.
+
+That's the bar. If an agent can't ship a working bridge from this doc plus the scaffold, the doc is the bug.
+
+## Full spec
+
+The authoritative contract is in [`specs/FLAIR-BRIDGES.md`](../specs/FLAIR-BRIDGES.md). This doc is the user-facing view; the spec covers edge cases, future extensions, and design rationale.