@tpsdev-ai/flair 0.25.4 → 0.27.0

package/docs/mcp-clients.md

@@ -0,0 +1,240 @@
+# Flair via MCP — Claude Code, Gemini CLI, OpenAI Codex CLI
+
+Flair ships an MCP server (`@tpsdev-ai/flair-mcp`) that any MCP-compatible client can use as its persistent memory + identity layer. One server, three (and counting) integrations. Switch between agent CLIs without losing your agent's memory.
+
+This page is the install + config snippet for each of the three major CLIs. The bootstrap is the same:
+
+1. Install Flair and create an agent identity (one-time, ~2 min).
+2. Add the MCP server to your CLI of choice (1 command or 1 file).
+3. Verify the agent can call `memory_search` / `memory_store`.
+
+If you've never set up Flair before, do step 1 first. If Flair is already running and you have an agent ID, jump to your CLI section.
+
+---
+
+## Step 1 — Install Flair (do once)
+
+```bash
+# Install Flair globally
+npm install -g @tpsdev-ai/flair
+
+# Initialize the local Harper-backed server
+flair init
+
+# Provision an agent identity. Pick a name — typically per-project, per-purpose,
+# or "me" if you want one durable identity across everything.
+flair agent add my-project
+# → writes ~/.flair/keys/my-project.key (Ed25519 PKCS8) and registers the agent
+
+# Sanity check
+flair status
+```
+
+Flair runs as a local server at `http://127.0.0.1:19926` by default. The MCP server connects to it on demand via Ed25519-signed requests; nothing leaves your machine unless you explicitly route to a remote Flair instance.
+
+---
+
+## Step 2 — Wire the MCP server into your CLI
+
+Pick whichever you use. The MCP server is the same package; only the config syntax differs.
+
+### Claude Code
+
+The canonical approach is the `claude mcp add` CLI (writes to `~/.claude/mcp.json`):
+
+```bash
+claude mcp add flair --scope user \
+  -e FLAIR_AGENT_ID=my-project \
+  -- npx -y @tpsdev-ai/flair-mcp
+```
+
+Verify:
+
+```bash
+claude mcp list
+# → flair (stdio, npx -y @tpsdev-ai/flair-mcp)
+```
+
+Or, if you prefer the project-scoped `.mcp.json` checked into your repo:
+
+```json
+{
+  "mcpServers": {
+    "flair": {
+      "command": "npx",
+      "args": ["-y", "@tpsdev-ai/flair-mcp"],
+      "env": {
+        "FLAIR_AGENT_ID": "my-project"
+      }
+    }
+  }
+}
+```
+
+#### Auto-recall on session start (optional hook)
+
+The MCP server gives the agent *pull* access to memory — it calls `bootstrap` /
+`memory_search` when it decides to. If you'd rather have Flair context loaded
+automatically the moment a session opens (no "call the bootstrap tool" nudge),
+register Flair's `SessionStart` hook. It's a separate bin shipped in the same
+package and is entirely optional — it complements the MCP server, it doesn't
+replace it.
+
+The one-command way (recommended — idempotent, `--dry-run`-able, and
+symmetric with `flair hook uninstall`/`flair hook status`):
+
+```bash
+flair hook install               # wires ~/.claude/settings.json for FLAIR_AGENT_ID/FLAIR_URL
+flair hook install --dry-run     # prints the exact JSON delta, writes nothing
+flair hook status                # wired? correct shape? which agent/instance?
+flair hook uninstall             # removes only Flair's hook entry
+```
+
+`--harness claude-code` is the only supported value today (it's also the
+default) — the flag exists so a future harness is an additive registry entry,
+not a breaking change. `flair doctor` already checks for this same hook (see
+below) and recognizes anything `flair hook install` writes.
+
+Or wire it by hand — add a `SessionStart` hook to `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "FLAIR_AGENT_ID=me npx -y @tpsdev-ai/flair-mcp flair-session-start"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Swap `me` for your `FLAIR_AGENT_ID`. The hook reads Claude Code's SessionStart
+payload on stdin, calls Flair's `bootstrap` (soul + relevant memories +
+predicted context, scoped to your project by the session's working directory),
+and emits it as `hookSpecificOutput.additionalContext` — which Claude Code
+injects into the new session's context. The matcher is omitted, so it fires on
+every session start (`startup`, `resume`, `clear`, `compact`); add
+`"matcher": "startup"` to a hook group if you only want it on fresh sessions.
+
+It honors the same env as the MCP server (`FLAIR_AGENT_ID`, `FLAIR_URL`,
+`FLAIR_KEY_PATH`), plus `FLAIR_HOOK_TIMEOUT_MS` (default 8000, clamped
+500–30000) for the bootstrap timeout.
+
+**It degrades to a no-op, always.** No `FLAIR_AGENT_ID`, Flair down, an auth
+error, or a hung daemon (past the timeout) → the hook prints `{}` and exits 0.
+Claude Code treats that as "no context to add" and starts normally. The hook
+can never block or break session startup. The injected context is clamped to
+≤10,000 characters to keep the session-start payload small.
+
+### Gemini CLI
+
+Edit `~/.gemini/settings.json` (create it if absent):
+
+```json
+{
+  "mcpServers": {
+    "flair": {
+      "command": "npx",
+      "args": ["-y", "@tpsdev-ai/flair-mcp"],
+      "env": {
+        "FLAIR_AGENT_ID": "my-project"
+      }
+    }
+  }
+}
+```
+
+Restart your Gemini CLI session for the config to take effect. Then in chat:
+
+```
+> @flair memory_search "what did we decide about auth last week?"
+```
+
+### OpenAI Codex CLI
+
+Edit `~/.codex/config.toml` (create it if absent):
+
+```toml
+[mcp_servers.flair]
+command = "npx"
+args = ["-y", "@tpsdev-ai/flair-mcp"]
+
+[mcp_servers.flair.env]
+FLAIR_AGENT_ID = "my-project"
+```
+
+For project-scoped trust (per Codex's MCP guide), the same block in `.codex/config.toml` at the project root.
+
+Restart your Codex CLI session and the `flair_*` tools become available to the agent.
+
+---
+
+## Step 3 — Verify
+
+In any of the three CLIs, ask the agent to do this:
+
+> Use the bootstrap tool to load my Flair memory context, then store a memory that says "successful first MCP integration test."
+
+If you see (a) the agent calling the `bootstrap` tool returning soul + recent memories, and (b) `memory_store` confirming a write — you're wired up. The memory now persists across CLI sessions AND across CLIs. Switch to a different CLI tomorrow and `memory_search "MCP integration test"` will find it.
+
+---
+
+## What the MCP server exposes
+
+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_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 |
+| `relationship_store` | Record a subject-predicate-object relationship triple (e.g. "nathan manages flair") |
+| `bootstrap` | Get session-start context: soul + recent memories + predicted-relevant context |
+| `soul_set` | Set a personality/project/standards entry — included in every bootstrap |
+| `soul_get` | Get a soul entry |
+| `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.
+
+---
+
+## Configuration reference
+
+| Env var | Default | Notes |
+|---|---|---|
+| `FLAIR_AGENT_ID` | (none — required) | Must match `flair agent add <id>` |
+| `FLAIR_URL` | `http://127.0.0.1:19926` | Override for remote Flair instances |
+| `FLAIR_KEY_PATH` | `~/.flair/keys/<agent>.key` | Ed25519 PKCS8 key — created by `flair agent add` |
+
+The MCP server has no client-side flags beyond these env vars; everything else (timeouts, dedup thresholds, error classification) is opinionated defaults from the underlying [`@tpsdev-ai/flair-client`](../packages/flair-client) package.
+
+---
+
+## What about Hermes (Nous Research)?
+
+Hermes uses its own Python-native `MemoryProvider` ABC instead of MCP. It has its own Flair integration in [`packages/hermes-flair/`](../packages/hermes-flair). Same backend, same agent isolation, different plug shape.
+
+Future MCP-capable agent CLIs (and there are more landing every month) will work out of the box with the MCP server above — no per-framework adapter required from us.
+
+---
+
+## Troubleshooting
+
+**"FLAIR_AGENT_ID is required" on startup.** Set it in the MCP server's `env` block (per snippets above). The CLI's own env doesn't propagate to the spawned MCP subprocess unless declared.
+
+**"connection_error: could not reach Flair at http://127.0.0.1:19926".** The Flair server isn't running. Run `flair status` to check; `flair start` to bring it up.
+
+**"auth_error: …" on every call.** The agent identity doesn't match a registered key. Re-run `flair agent add <id>` (idempotent on re-add — won't lose existing memories).
+
+**Tool calls succeed but the agent doesn't see results in subsequent turns.** Check that the CLI is actually invoking `bootstrap` at session start — most CLIs need an explicit prompt nudge ("call the bootstrap tool now") on first use. Subsequent turns should pick up automatically once the CLI sees the schema.
+
+For deeper issues see [`troubleshooting.md`](troubleshooting.md) and the [`@tpsdev-ai/flair-mcp` repo](https://github.com/tpsdev-ai/flair/tree/main/packages/flair-mcp).

package/docs/n8n-management.md

@@ -0,0 +1,142 @@
+# n8n Workflow Management
+
+Programmatic activation/deactivation of n8n workflows — the approach we use for ops automation.
+
+## The Problem
+
+Direct SQLite edits to `workflow_entity.active` (or using `n8n update:workflow` while n8n is running) don't re-register schedule triggers in the in-memory scheduler. The schedule simply stops firing. Only the v1 public API's `POST /api/v1/workflows/:id/activate` (or flipping Active in the UI) properly registers the trigger.
+
+**Root cause**: n8n tracks activation via `activeVersionId`, not the `active` boolean alone. The `activeWorkflowManager` in-memory scheduler only picks up workflows where `activeVersionId IS NOT NULL`. Direct SQLite edits that only set `active=1` without setting `activeVersionId` will not be picked up even on restart.
+
+## Recommended Approach: v1 Public API (live instance)
+
+The **v1 public API** is the correct tool for managing workflows on a **running** n8n instance. It updates the DB AND calls the in-memory `ActiveWorkflowManager.add()` to register triggers immediately — no restart needed.
+
+### Endpoints
+
+| Action | Method | Endpoint | Body |
+|---|---|---|---|
+| Activate | `POST` | `/api/v1/workflows/:id/activate` | `{}` or `{"versionId": "..."}` |
+| Deactivate | `POST` | `/api/v1/workflows/:id/deactivate` | (none) |
+| List | `GET` | `/api/v1/workflows` | — |
+| Get one | `GET` | `/api/v1/workflows/:id` | — |
+
+### Authentication
+
+All v1 API calls require `X-N8N-API-KEY` header with a valid API key (see [API Key Generation](#api-key-generation) below).
+
+### Examples
+
+```bash
+# Activate workflow
+curl -X POST "http://127.0.0.1:5678/api/v1/workflows/$WORKFLOW_ID/activate" \
+  -H "X-N8N-API-KEY: $N8N_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+
+# Deactivate workflow
+curl -X POST "http://127.0.0.1:5678/api/v1/workflows/$WORKFLOW_ID/deactivate" \
+  -H "X-N8N-API-KEY: $N8N_API_KEY"
+
+# Check if workflow is active
+curl -s "http://127.0.0.1:5678/api/v1/workflows/$WORKFLOW_ID" \
+  -H "X-N8N-API-KEY: $N8N_API_KEY" | python3 -c "import json,sys; print(json.load(sys.stdin)['active'])"
+```
+
+See `scripts/n8n/activate-workflow.sh` for a reusable wrapper.
+
+## Why PATCH Doesn't Work
+
+n8n's v1 API docs mention `PATCH /api/v1/workflows/:id` with `{ "active": true }`. **This returns 405 Method Not Allowed on n8n 1.123.38.** The documented activation endpoints are `POST /api/v1/workflows/:id/activate` and `POST /api/v1/workflows/:id/deactivate`.
+
+## Alternative Approaches
+
+### Approach 2: CLI when n8n is stopped
+
+The `n8n update:workflow` CLI command works when n8n is **not running**. It updates both `active` and `activeVersionId` in the DB. On the next `n8n start`, `ActiveWorkflowManager.init()` reads `getAllActiveIds()` and registers all workflows with non-null `activeVersionId`.
+
+```bash
+# Stop n8n
+launchctl stop ai.tpsdev.n8n
+
+# Activate/deactivate via CLI
+N8N_PATH="/opt/homebrew/opt/node@24/bin" npx n8n@1.123.38 update:workflow --id=$WORKFLOW_ID --active=true
+# or
+N8N_PATH="/opt/homebrew/opt/node@24/bin" npx n8n@1.123.38 update:workflow --id=$WORKFLOW_ID --active=false
+
+# Start n8n
+launchctl start ai.tpsdev.n8n
+```
+
+**Caveats**:
+- `update:workflow` is deprecated (n8n v2 will replace it with `publish:workflow`/`unpublish:workflow`)
+- Requires a full stop/start cycle (downtime for all workflows)
+- `npx` needs node@24 (`/opt/homebrew/opt/node@24/bin/node`)
+
+### Approach 3: Internal REST API (editor UI)
+
+The `/rest/workflows/:id/activate` endpoint is what the editor UI uses. It requires session-based auth (cookie from `/rest/login`), which needs the admin password. Not practical for automation without storing credentials.
+
+```bash
+# Requires session cookie from /rest/login
+curl -X POST "http://127.0.0.1:5678/rest/workflows/$WORKFLOW_ID/activate" \
+  -b "fern-uid=...; n8n.session=..."
+```
+
+**Not recommended** for ops automation — session cookies expire and the password is a higher-value secret than an API key.
+
+## API Key Generation
+
+The v1 API key is a JWT signed with a secret derived from the encryption key. To create one programmatically:
+
+```javascript
+const crypto = require('crypto');
+const jwt = require('jsonwebtoken');
+const fs = require('fs');
+
+// Read encryption key from n8n config
+const config = JSON.parse(fs.readFileSync(process.env.HOME + '/.n8n/config', 'utf8'));
+const encKey = config.encryptionKey;
+
+// Derive JWT secret: SHA256 of every-other-character of encryption key
+let baseKey = '';
+for (let i = 0; i < encKey.length; i += 2) {
+  baseKey += encKey[i];
+}
+const jwtSecret = crypto.createHash('sha256').update(baseKey).digest('hex');
+
+// Sign JWT with user's ID (from `user` table in SQLite)
+const userId = '<user-uuid-from-sqlite>'; // e.g., 'a6ce7ac9-ef6d-4157-835a-4b0f01dc788a'
+const apiKey = jwt.sign(
+  { sub: userId, iss: 'n8n', aud: 'public-api' },
+  jwtSecret
+);
+
+// Store the returned key in the user_api_keys table so it persists
+
+console.log('API key:', apiKey);
+```
+
+Once stored in the DB, the key is valid until deleted. No expiration by default.
+
+**Security note**: The encryption key is needed to derive the JWT secret. This is the same key used to decrypt workflow credentials. If the encryption key is compromised, so are the credentials. Keep it scoped to the n8n user.
+
+## Why Direct SQLite Edits Don't Work
+
+The `workflow_entity` table has two activation fields:
+- `active` (boolean): UI flag
+- `activeVersionId` (varchar): points to the `workflow_history` record that defines the active version
+
+The `ActiveWorkflowManager` only considers workflows where `activeVersionId IS NOT NULL`. If you only flip `active=1` without setting `activeVersionId`, n8n never picks up the workflow — not on restart, not on refresh.
+
+Even with both fields set correctly, a live n8n instance has an in-memory scheduler that doesn't re-read the DB. Only the v1 API (or UI toggle) calls `activeWorkflowManager.add()` to register the trigger in-memory.
+
+## Quick Reference
+
+| Scenario | Method | Restart needed? |
+|---|---|---|
+| Activate on running n8n | `POST /api/v1/workflows/:id/activate` | No |
+| Deactivate on running n8n | `POST /api/v1/workflows/:id/deactivate` | No |
+| Activate when stopped | `n8n update:workflow --id=X --active=true` | Yes |
+| Direct DB edit (active + activeVersionId) | SQLite `UPDATE` | Yes, on restart |
+| Direct DB edit (active only) | SQLite `UPDATE` | **Won't work** — needs activeVersionId too |

package/docs/n8n.md

@@ -0,0 +1,122 @@
+# Flair + n8n
+
+Use Flair as the memory backend for n8n's AI Agent. The same memories are readable from Claude Code, OpenClaw, and any other Flair client — that's the point.
+
+## When to use Flair vs n8n's built-in memory connectors
+
+n8n ships memory connectors for Postgres, MongoDB, and Redis. Those are real, persistent, and work fine for **conversation-buffer** use cases inside a single n8n instance.
+
+Flair is the right pick when you want:
+
+| | Flair | n8n built-ins |
+|---|---|---|
+| **Shape** | Tagged + typed memories with semantic search, plus chat-buffer compatibility | Conversation-buffer only (LangChain `BaseMessage` records) |
+| **Cross-orchestrator** | Same memory readable from Claude Code, OpenClaw, n8n | n8n-internal schema; nothing else reads it |
+| **Cross-instance** | Hub-spoke federation built-in (local ↔ Fabric, etc.) | Single-instance unless you self-build replication |
+| **Identity** | Ed25519 per-agent (planned) or admin-token (v1) | n8n credential per workflow |
+
+If your AI Agent only needs to remember the last N turns of a single chat in a single n8n instance, Postgres-as-memory is fine. If you want the same memory to inform a Claude Code conversation tomorrow, or to persist across n8n redeploys via federated Flair, this package is the path.
+
+## Setup (5 minutes)
+
+### 1. Install Flair (if not already running)
+
+```bash
+npm install -g @tpsdev-ai/flair
+flair init
+```
+
+This starts a local Flair server on `http://localhost:19926`. For shared/team setups, see [Deployment](./deployment.md).
+
+### 2. Install the n8n community node
+
+In n8n: **Settings → Community Nodes → Install** → enter `@tpsdev-ai/n8n-nodes-flair` → confirm and restart.
+
+### 3. Create the credential
+
+In n8n: **Credentials → New → Flair API**. Fill in:
+
+| Field | Value |
+|---|---|
+| **Base URL** | `http://localhost:19926` (or your team's Flair URL) |
+| **Agent ID** | Logical identity that will own memories from this n8n workspace. Workflows that share an Agent ID share memory ownership. Use distinct IDs when isolation matters. |
+| **Admin Password** | Your Flair admin password (in `~/.flair/admin-pass` for local installs). **Sensitive** — see [Security](#security). |
+
+Click **Test** — if the test request to `/Memory` returns 200, the credential is good.
+
+### 4. Wire the nodes
+
+Three nodes ship in the package:
+
+- **Flair Chat Memory** — connects to an AI Agent's `Memory` socket. Stores chat history in Flair, scoped by Subject. Defaults to per-workflow memory; set the optional Session Sub-Key to `={{ $execution.id }}` for per-run isolation.
+- **Flair Search** — connects to an AI Agent's `Tool` socket. Two operations:
+  - *Semantic Search* — agent calls `flair_search({ query })`, gets memories ranked by similarity.
+  - *Get By Subject* — agent calls `flair_get_by_subject()`, gets memories under a config-time-bound subject.
+- **Flair Write** — a regular Main-input/Main-output pipeline node (not wired to the AI Agent's Tool socket). Takes an incoming item and writes its content as a Flair memory, with Subject, Tags, and Durability fields. For operator-driven capture-and-archive flows (mail → memory, webhook → memory, parsed-doc → memory) where the write is the workflow author's choice, not the LLM's.
+
+A typical workflow:
+
+```
+[Webhook] → [AI Agent]
+              ├─ Model: Claude / OpenAI / etc.
+              ├─ Memory: Flair Chat Memory (Subject: customer-support)
+              ├─ Tool: Flair Search (Operation: Semantic Search)
+              └─ Tool: HTTP Request (etc.)
+```
+
+The agent now answers using both its current chat history (from Flair Chat Memory) and any relevant historical memories it pulls in via Flair Search.
+
+## Subject and SessionId guidance
+
+n8n memory connectors expose a `sessionKey` parameter that scopes the chat history. Flair has a richer model:
+
+- **Subject** (required) — the entity / conversation / topic the memory is about. Indexed in Flair's schema; efficient to filter on. Default: `={{ $workflow.name }}`.
+- **Session Sub-Key** (optional) — appended to the subject as `<subject>:<sessionKey>`. Use the n8n execution id (`={{ $execution.id }}`) for per-run isolation, or a customer/user id for per-customer scoping, or leave blank to share across runs.
+
+Patterns:
+
+- **"This assistant remembers"** — set Subject to a stable string (`customer-support`, `daily-standup`). Leave Session Sub-Key blank. All runs share memory.
+- **Per-conversation isolation** — set Subject to the conversation owner (`customer:1234`), leave Session Sub-Key blank. Each conversation is isolated by subject.
+- **Per-execution isolation** — set Session Sub-Key to `={{ $execution.id }}`. Each n8n run gets its own memory window. (This is most similar to n8n's default `sessionKey={{ $execution.id }}`.)
+
+## Security
+
+> **The admin password gives every workflow with this credential read/write access to the entire Flair instance**, not just the configured Agent ID. The blast radius is the whole memory store. Treat the credential as highly sensitive: n8n encrypts credentials at rest, but any n8n admin or backup restore can extract it.
+
+For production deployments where untrusted workflow inputs reach Flair, wait for **Ed25519 per-agent authentication** (planned). v1 (admin password) is appropriate when:
+
+- The n8n instance is single-tenant and operator-controlled
+- Workflow inputs are trusted (your own CRM, your own webhook source)
+- Memory leakage between agents is 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 update.
+
+## Get By Tag — coming soon
+
+The Flair Search node currently exposes Semantic Search and Get By Subject. **Get By Tag** is deferred until `flair-client.memory.list` exposes a `tags` filter (tracked in the [n8n-node spec](https://github.com/tpsdev-ai/flair/blob/main/specs/N8N-NODE-q3qf.md) §6). Workaround for now: use Semantic Search and let the model filter results by tags in the response.
+
+## Worked examples
+
+Two example workflows are coming in a follow-up release; they're authored inside a real n8n instance and round-tripped via Export so they import cleanly:
+
+- **`chat-memory-demo.json`** — Webhook → AI Agent (Claude + Flair Chat Memory) → Respond. Demonstrates the conversation-buffer use case. Run twice with the same input to see memory replay.
+- **`knowledge-search-demo.json`** — Schedule → AI Agent (Claude + Flair Chat Memory + Flair Search as Tool) → action. Demonstrates the structured-knowledge-search use case.
+
+In the interim, follow the [Setup](#setup-5-minutes) and [Subject and SessionId guidance](#subject-and-sessionid-guidance) sections — wiring is straightforward without an example file.
+
+## Compared to other Flair surfaces
+
+| Surface | Use case | Setup |
+|---|---|---|
+| [Claude Code](./claude-code.md) | Personal AI assistant memory across CLI sessions | npm install + `flair init` |
+| [OpenClaw](./openclaw.md) | Multi-agent OpenClaw deployments | OpenClaw plugin install |
+| [MCP](./mcp-clients.md) | Any MCP client (Claude Desktop, etc.) | MCP server registration |
+| **n8n (this doc)** | Workflow-engine AI Agents | n8n community-node install |
+
+Same Flair instance, same memories, different surfaces.
+
+## See also
+
+- [Spec — `@tpsdev-ai/n8n-nodes-flair`](https://github.com/tpsdev-ai/flair/blob/main/specs/N8N-NODE-q3qf.md) — implementation plan, design decisions, anti-patterns
+- [Bridges](./bridges.md) — how Flair memories flow between hosts and instances
+- [Federation](./federation.md) — hub-and-spoke replication