@tpsdev-ai/flair 0.26.0 → 0.27.0

package/docs/claude-code.md

@@ -0,0 +1,202 @@
+# Flair + Claude Code
+
+Give Claude Code persistent memory across sessions. Works with subagents too.
+
+## Setup (5 minutes)
+
+### 1. Install Flair
+
+```bash
+npm install -g @tpsdev-ai/flair
+```
+
+### 2. Initialize
+
+```bash
+flair init
+```
+
+This starts a local Flair server (Harper) and creates `~/.flair/`.
+
+### 3. Create an agent identity
+
+```bash
+# One agent per project, or one shared agent — your call
+flair agent add my-project
+```
+
+This generates an Ed25519 key pair at `~/.flair/keys/my-project.key` and registers the agent with Flair.
+
+### 4. Add to your project's CLAUDE.md
+
+Copy this into your project's `CLAUDE.md` (or `.claude/settings.md`, `AGENTS.md`, etc.):
+
+---
+
+> **Start of CLAUDE.md snippet** — copy everything between the lines.
+
+    ## Memory
+
+    You have persistent memory via Flair. Use it to remember context across sessions.
+
+    ### On session start
+
+    Run this FIRST, before doing anything else:
+
+        flair bootstrap --agent my-project --max-tokens 4000
+
+    Read the output — that's your soul and recent memories.
+
+    ### During work
+
+    - Remember something: `flair memory add --agent my-project --content "what you learned"`
+    - Search memory: `flair search "your query" --agent my-project`
+    - Store a lesson: `flair memory add --agent my-project --content "lesson text" --type lesson --durability persistent`
+    - Store a decision: `flair memory add --agent my-project --content "decision text" --type decision --durability persistent`
+
+    ### What to remember
+
+    - Lessons learned (bugs, workarounds, patterns)
+    - Decisions made (why we chose X over Y)
+    - Project-specific context (architecture, conventions, constraints)
+    - User preferences (coding style, review standards)
+
+    ### What NOT to remember
+
+    - Transient task details (what file am I editing right now)
+    - Things already in the codebase (read the code instead)
+    - Secrets or credentials (never store these in memory)
+
+    ### Durability levels
+
+    - persistent — survives indefinitely. Use for lessons, decisions, preferences.
+    - standard — default. Good for session context, observations.
+    - ephemeral — auto-expires after 24h. Use for temporary notes.
+
+> **End of CLAUDE.md snippet.**
+
+---
+
+That's it. Claude Code will now bootstrap context on start and store important things as it works.
+
+## Multiple Projects
+
+Create a separate agent per project:
+
+```bash
+flair agent add project-alpha
+flair agent add project-beta
+flair agent add infra-ops
+```
+
+Each project's `CLAUDE.md` uses its own agent ID. Memories are fully isolated between projects.
+
+## Subagents
+
+Claude Code subagents (spawned via `/run` or background tasks) can share the parent's memory:
+
+    ### Subagents
+    Subagents share memory with the parent session. Use the same agent ID:
+    FLAIR_AGENT_ID=my-project
+
+    When spawning subagents, pass the agent ID so they can access shared context.
+
+Or give subagents their own identity for isolation:
+
+```bash
+flair agent add my-project-review   # code review subagent
+flair agent add my-project-test     # test runner subagent
+```
+
+## Environment Variables
+
+Instead of passing `--agent` every time, set environment variables:
+
+```bash
+# In your shell profile or .envrc
+export FLAIR_AGENT_ID=my-project
+export FLAIR_URL=http://localhost:19926  # default, only needed if custom
+```
+
+Then the CLAUDE.md simplifies to:
+
+    ## Memory
+    - Bootstrap: `flair bootstrap`
+    - Remember: `flair memory add --content "what you learned"`
+    - Search: `flair search "your query"`
+
+## Soul (Personality / Context)
+
+Want Claude Code to have consistent personality or project context? Set soul entries:
+
+```bash
+# Project context
+flair soul set --agent my-project --key project \
+  --value "E-commerce platform. Rust backend, React frontend. Ship quality over speed."
+
+# Coding standards
+flair soul set --agent my-project --key standards \
+  --value "Always write tests. Prefer composition over inheritance. No any types in TypeScript."
+
+# Review guidelines
+flair soul set --agent my-project --key review \
+  --value "Check for: error handling, edge cases, performance implications, security."
+```
+
+Soul entries are included in every `flair bootstrap` — they're the persistent context that shapes how Claude Code thinks about your project.
+
+## Remote Flair
+
+If you want to share memory across machines (e.g., work laptop + home setup):
+
+```bash
+# On your server
+npm install -g @tpsdev-ai/flair
+flair init
+flair agent add my-project
+
+# On client machines
+npm install -g @tpsdev-ai/flair  # for the CLI
+export FLAIR_URL=http://your-server:19926
+export FLAIR_AGENT_ID=my-project
+# Copy the key from the server:
+scp server:~/.flair/keys/my-project.key ~/.flair/keys/
+```
+
+Or use an SSH tunnel:
+
+```bash
+ssh -f -N -L 19926:localhost:19926 your-server
+# Now FLAIR_URL=http://localhost:19926 works
+```
+
+## Programmatic Access
+
+For custom tooling, use the lightweight client library:
+
+```bash
+npm install @tpsdev-ai/flair-client
+```
+
+```typescript
+import { FlairClient } from '@tpsdev-ai/flair-client'
+
+const flair = new FlairClient({ agentId: 'my-project' })
+
+await flair.memory.write('learned that X causes Y', {
+  type: 'lesson',
+  durability: 'persistent',
+})
+
+const results = await flair.memory.search('what causes Y')
+const context = await flair.bootstrap({ maxTokens: 4000 })
+```
+
+## Tips
+
+- **Bootstrap is cheap.** Run it at the start of every session. It's one HTTP call.
+- **Write lessons immediately.** Don't wait for the session to end — you might not get the chance.
+- **Use durability wisely.** Most things are `standard`. Only promote to `persistent` for things that should survive months.
+- **Search is semantic.** "deployment issues" finds memories about "CI pipeline failures" — you don't need exact keywords.
+- **Temporal queries work.** "What happened today" and "what did we ship recently" are understood.
+- **Dedup is automatic.** Writing the same fact twice won't create duplicates (0.7 similarity threshold).

package/docs/deployment.md

@@ -0,0 +1,204 @@
+# Deployment Guide
+
+Run Flair on macOS, Linux, or Docker.
+
+## macOS (Apple Silicon)
+
+### Install
+
+```bash
+npm install -g @tpsdev-ai/flair
+flair init
+```
+
+`flair init` will:
+- Download Harper and the nomic-embed-text embedding model
+- Create `~/.flair/` (config, data, keys)
+- Generate admin credentials
+- Install a launchd plist for auto-start on boot
+- Start the server
+
+### Verify
+
+```bash
+flair status
+flair doctor
+```
+
+### Auto-start
+
+`flair init` installs a launchd plist at `~/Library/LaunchAgents/ai.tpsdev.flair.plist`. Flair starts automatically on login and restarts if it crashes.
+
+```bash
+# Manual control
+flair stop
+flair start
+flair restart
+```
+
+### Port
+
+Default port is `19926`. Override during init:
+
+```bash
+flair init --port 8000
+```
+
+Or edit `~/.flair/config.yaml` and restart.
+
+---
+
+## Linux
+
+### Prerequisites
+
+- Node.js >= 22
+- systemd (for auto-start)
+
+### Install
+
+```bash
+npm install -g @tpsdev-ai/flair
+flair init
+```
+
+Same as macOS — detects the platform and generates a systemd unit file instead of a launchd plist.
+
+### Verify
+
+```bash
+flair status
+flair doctor
+```
+
+### Auto-start
+
+The systemd unit file is installed at `~/.config/systemd/user/flair.service`.
+
+```bash
+# Manual control
+systemctl --user start flair
+systemctl --user stop flair
+systemctl --user restart flair
+
+# View logs
+journalctl --user -u flair -f
+```
+
+---
+
+## Docker
+
+### Quick test (from-scratch validation)
+
+```bash
+cd docker/
+./test-from-scratch.sh
+```
+
+This runs a clean install in a container — useful for verifying the install path works on a fresh machine.
+
+### Production Docker
+
+```dockerfile
+FROM node:22-slim
+RUN npm install -g @tpsdev-ai/flair
+RUN flair init --skip-soul
+EXPOSE 19926
+CMD ["flair", "start", "--foreground"]
+```
+
+Note: embeddings run on CPU in Docker (no Metal acceleration). Performance is acceptable for small-to-medium memory stores (< 10K memories).
+
+---
+
+## Harper Fabric
+
+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.
+
+---
+
+## Remote Access
+
+### SSH tunnel (simplest)
+
+```bash
+ssh -f -N -L 19926:localhost:19926 your-server
+```
+
+Then set `FLAIR_URL=http://localhost:19926` on the client.
+
+### Direct network access
+
+Edit `~/.flair/config.yaml`:
+
+```yaml
+http:
+  port: 19926
+  host: 0.0.0.0  # listen on all interfaces
+```
+
+**Security:** Flair uses Ed25519 authentication. Agents must present a valid signature to read or write. However, the `/Health` endpoint is unauthenticated. For internet-facing deployments, put Flair behind a reverse proxy with TLS.
+
+---
+
+## Configuration
+
+All configuration lives in `~/.flair/`:
+
+```
+~/.flair/
+├── config.yaml          # port, host, embedding model
+├── data/                # Harper database
+├── keys/                # Ed25519 keypairs per agent
+└── backups/             # flair backup output
+```
+
+### Key config options (`~/.flair/config.yaml`)
+
+```yaml
+http:
+  port: 19926            # API port (ops port = this - 1)
+  host: 127.0.0.1        # bind address
+
+clustering:
+  nodeName: flair
+
+logging:
+  level: warn
+  stdStreams: true
+```
+
+### Environment variables
+
+Set these in the Flair process environment (`~/Library/LaunchAgents/ai.tpsdev.flair.plist` on macOS, the systemd unit on Linux, the component env on Fabric).
+
+| Variable | What it does | When to set it |
+|----------|--------------|----------------|
+| `FLAIR_PUBLIC_URL` | The URL operators reach this Flair on (e.g. `https://flair.example.com`). Surfaced in the AdminInstance pane's Endpoints table and used by OAuth metadata + A2A discovery so external clients see a reachable URL. | **Always set on remote / Fabric / VPS deployments.** Local-only installs can leave it unset. |
+| `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. |
+
+---
+
+## Backup & Restore
+
+```bash
+# Backup all data (agents, memories, souls)
+flair backup > ~/flair-backup-$(date +%Y%m%d).json
+
+# Restore to a fresh instance
+flair restore < ~/flair-backup-20260405.json
+```
+
+Always backup before upgrades.
+
+---
+
+## Uninstall
+
+```bash
+flair uninstall   # stops server, removes ~/.flair/, removes launchd/systemd service
+npm uninstall -g @tpsdev-ai/flair
+```

package/docs/entity-vocabulary.md

@@ -0,0 +1,109 @@
+# Entity Vocabulary
+
+The **attention plane** — an agent seeing what its teammates are actively touching, and
+where its own work collides with theirs — needs one thing to work at all: a single,
+consistent way to name the "things" (repos, issues, customers, subsystems, people, agents)
+that memories, workspace state, org events, and relationships all reference. Without it,
+"what touches entity E" can never be an indexed lookup — it degenerates into fuzzy string
+matching across free-text fields.
+
+This document is that convention. It's written down and enforced by a small validator
+(`resources/entity-vocab.ts`) **before** anything is built on top of it, because three
+surfaces already consume entity strings today (the `Relationship` graph's `subject`/`object`,
+and the new `entities` fields on `WorkspaceState`/`OrgEvent`/`Memory`), plus a future
+attention query and any future MCP scope field — retrofitting a divergent vocabulary later
+is expensive.
+
+> This doc covers the vocabulary and validator only — the foundation slice of the attention
+> plane (flair#675). The attention query ("what touches entity E in the last N days") and
+> bootstrap collision surfacing are separate, later slices. See `FLAIR-ATTENTION-PLANE.md`
+> for the full design.
+
+## The form
+
+An entity is a single string: `type:value`.
+
+- **type** — lowercase, drawn from a **closed** set (below). Not user-extensible at write
+  time; new types are added deliberately, by changing `ENTITY_TYPES` in
+  `resources/entity-vocab.ts` (and this doc) in the same change.
+- **value** — a stable identifier whose grammar depends on the type (see table).
+
+Matching is **exact on the full string** — `repo:tpsdev-ai/flair` and
+`repo:tpsdev-ai/flair-mcp` are unrelated entities, not prefix-related. This is what makes the
+indexed `entities: [String] @indexed` fields a plain equality lookup rather than a scan.
+
+## The closed type set
+
+| Type | Form | Example | Value grammar |
+|------|------|---------|---------------|
+| `repo` | `repo:<owner>/<name>` | `repo:tpsdev-ai/flair` | Two lowercase path segments (alnum + `.`/`-`/`_` internal separators) joined by exactly one `/`. |
+| `issue` | `issue:<repo>#<n>` | `issue:tpsdev-ai/flair#504` | A valid `repo` value, then `#`, then a positive integer with no leading zero. |
+| `customer` | `customer:<slug>` | `customer:acme` | A lowercase slug (alnum segments joined by single `-`/`_`). |
+| `subsystem` | `subsystem:<slug>` | `subsystem:embeddings` | Same slug grammar as `customer`. |
+| `agent` | `agent:<agentId>` | `agent:flint` | Same slug grammar — the agent's registered id. |
+| `person` | `person:<id>` | `person:nathan` | Same slug grammar. |
+
+Rules that apply across every type:
+
+- The type prefix is **always lowercase** — `Repo:x`, `CUSTOMER:x` etc. are invalid (not a
+  case-insensitive match against the closed set — they simply aren't in it).
+- No leading/trailing whitespace anywhere in the string.
+- No empty type or empty value (`:acme`, `repo:`, `repo` with no colon are all invalid).
+- Slugs never have leading/trailing/doubled separators (`-embeddings`, `embeddings-`,
+  `embed--dings` are all invalid).
+
+## The validator
+
+`resources/entity-vocab.ts` is the single source of truth — every write path that persists
+an `entities` value validates against it, not a local reimplementation of the grammar.
+
+```ts
+import { isValidEntity, validateEntities, invalidEntitiesResponse } from "./entity-vocab.js";
+
+isValidEntity("repo:tpsdev-ai/flair");      // true
+isValidEntity("project:flair");             // false — "project" isn't in the closed type set
+isValidEntity("Customer:Acme");             // false — uppercase type and value both reject
+
+validateEntities(["repo:tpsdev-ai/flair", "bogus"]);
+// => { valid: false, invalid: ["bogus"] }
+
+validateEntities(undefined);
+// => { valid: true, invalid: [] }  — the field is additive/optional; absence is not an error
+```
+
+`invalidEntitiesResponse(entities)` is a thin convenience wrapper for Harper resource write
+paths: it returns a ready-to-return `400 { error: "invalid_entities", invalid: [...] }`
+`Response` when validation fails, or `null` when the field is absent or every entry is valid.
+`WorkspaceState.ts`, `OrgEvent.ts`, and `Memory.ts` all call it early in `post()`/`put()`.
+
+## Where `entities` lives today
+
+Per the attention-plane spec's K&S-approved refinements, `entities: [String] @indexed` is an
+**additive, nullable** field on:
+
+- `WorkspaceState` (`schemas/workspace.graphql`)
+- `OrgEvent` (`schemas/event.graphql`)
+- `Memory` (`schemas/memory.graphql`) — added in v1 (not deferred to v2) for index-pushdown
+  uniformity across all three sources the future attention query joins.
+
+Existing rows on all three tables simply carry no `entities` — readers must tolerate absence,
+the same pattern already used for `Presence.activityUpdatedAt`. No migration, no backfill.
+
+`Relationship` gets **no** `entities` field: its `subject`/`object` columns already carry
+free-form entity-reference strings and are already indexed — they're the vocabulary carrier
+for that table. They are lowercased on write today but not yet validated against this
+vocabulary; wiring that validation is a follow-up, not part of this foundation slice.
+
+## What's explicitly NOT in this slice
+
+- The attention query (`AttentionQuery` / `flair attention <entity>`) that joins Memory,
+  Relationship, WorkspaceState, Presence, and OrgEvent by entity — shipped in flair#678
+  (`resources/AttentionQuery.ts`), a later slice.
+- Bootstrap collision surfacing ("others in the room") — shipped in flair#681
+  (`resources/collision-lib.ts` + `MemoryBootstrap.ts`'s "Others in the room" section), a
+  later slice.
+- Automatic entity extraction/tagging on write (producers set `entities` themselves today,
+  where they choose to; there's no NLP-derived auto-population yet).
+- Validating `Relationship.subject`/`object` against this vocabulary.
+
+These are tracked as follow-ups in `FLAIR-ATTENTION-PLANE.md`.

package/docs/federation.md

@@ -0,0 +1,179 @@
+# Federation
+
+Hub-and-spoke sync between Flair instances. A hub instance coordinates sync for one or more spoke instances.
+
+## Overview
+
+Federation lets multiple Flair instances share memories, relationships, and agent records. Each instance maintains its own Ed25519 identity. Sync requests are signed and verified against pinned peer public keys.
+
+```
+Spoke A ──[signed sync]──▶ Hub ◀──[signed sync]── Spoke B
+```
+
+- **Hub:** accepts sync pushes from paired spokes, can relay records between peers
+- **Spoke:** pushes local changes to the hub, receives changes from other spokes via the hub
+
+## Pairing a New Spoke (Bootstrap-User Flow)
+
+Pairing connects a spoke to a hub with mutual key pinning and an auth-aware handshake that works across all Harper topologies, including Harper Fabric.
+
+### Step-by-step
+
+**1. Hub admin generates a pairing token triple**
+
+On the hub machine, the admin runs `flair federation token`. The command emits a JSON triple containing a one-time bootstrap credential:
+
+```bash
+flair federation token --admin-pass <hub-admin-password>
+```
+
+Output (a single JSON object):
+
+```json
+{"token":"<one-time-pairing-token>","user":"<bootstrap-username>","password":"<bootstrap-password>","expiresAt":"<ISO-8601-timestamp>"}
+```
+
+Tokens expire after 60 minutes by default. Use `--ttl <minutes>` to adjust.
+
+**2. Hub admin shares the triple with the spoke admin**
+
+The JSON triple is shared out-of-band (secure file transfer, password manager, or similar). It must be stored as a plain JSON file on the spoke side or piped via stdin.
+
+**3. Spoke admin runs the pair command**
+
+On the spoke machine:
+
+```bash
+# From a file
+flair federation pair <hub-url> --token-from /path/to/triple.json
+
+# From stdin
+cat triple.json | flair federation pair <hub-url> --token-from -
+```
+
+**4. Behind the scenes**
+
+- The bootstrap user authenticates at the platform layer (works on standalone deployments and Harper Fabric alike).
+- The resource handler validates the pairing token, the signed request body, and the binding between the bootstrap user and the token.
+- On success the hub creates a `Peer` record for the spoke and removes the temporary bootstrap user. The spoke records the hub as its peer.
+
+After pairing, both instances pin each other's Ed25519 public keys and are ready to sync.
+
+## Why the Bootstrap-User Flow?
+
+Earlier designs relied on `allowCreate=true` combined with body-only authentication. That approach works on single-component deployments but breaks on Harper Fabric, where the platform authentication gate fires before the resource handler sees the request. The bootstrap-user flow (Option B) makes the pair handshake auth-aware so it operates correctly on all Harper topologies: standalone, Fabric single-node, and Fabric multi-node.
+
+## Fabric Pairing Example
+
+When the hub runs on Harper Fabric, adapt the hub URL to the Fabric pattern:
+
+```bash
+# 1. Hub admin generates the triple (on the Fabric host)
+ssh hub-host
+flair federation token --admin-pass <hub-admin-password> > /tmp/pair-triple.json
+
+# 2. Transfer the triple to the spoke admin (out-of-band)
+scp hub-host:/tmp/pair-triple.json ./pair-triple.json
+
+# 3. Spoke admin pairs using the Fabric URL
+flair federation pair https://<fabric-node>:19926/<instance-name> --token-from ./pair-triple.json
+```
+
+Replace `<fabric-node>`, `<instance-name>`, and `<hub-admin-password>` with your actual values.
+
+## Sync
+
+Push local changes to the hub:
+
+```bash
+flair federation sync --admin-pass <password>
+# Output: ✅ Synced 12 records (0 skipped) in 145ms
+```
+
+## Security
+
+### Signed requests
+
+Every federation request (pair, sync) is signed with the sender's Ed25519 private key. The receiver verifies the signature against the peer's pinned public key. Unsigned or tampered requests are rejected with 401.
+
+The signature covers the canonical JSON of the request body (keys sorted recursively, signature field excluded).
+
+### Encrypted key storage
+
+Private key seeds are stored in `~/.flair/keys/<instanceId>.key`, encrypted with AES-256-GCM. The encryption key is derived via HKDF from:
+
+1. `FLAIR_KEY_PASSPHRASE` environment variable (recommended for production), or
+2. An auto-generated random passphrase at `~/.flair/keys/.passphrase` (mode 0600)
+
+If neither the env var nor the passphrase file can be accessed, federation identity creation fails. Private keys are never stored in the database.
+
+### Pairing tokens
+
+New peers must present a valid, unexpired, unused pairing token. This prevents unauthorized instances from joining the federation. Tokens are generated by the hub admin and are single-use.
+
+Re-pairing an existing peer (same instance ID, same public key) does not require a token.
+
+### Originator enforcement
+
+Spoke instances can only push records they originated. A spoke cannot overwrite records from another spoke or from the hub. The hub can relay records from any origin.
+
+### Timestamp ceiling
+
+Records with `updatedAt` more than 5 minutes in the future are rejected. This prevents an attacker from using far-future timestamps to permanently win last-write-wins (LWW) merge conflicts.
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `flair federation status` | Show instance identity and peer connections |
+| `flair federation pair <hub-url> --token-from <file>` | Pair this spoke with a hub using a token triple file (or `-` for stdin) |
+| `flair federation sync` | Push local changes to the hub (one-shot) |
+| `flair federation watch [--interval <s>]` | Run sync in a foreground daemon loop (default 30s) |
+| `flair federation reachability` | Probe local instance + each paired peer (read-only) |
+| `flair federation token [--ttl <min>]` | Generate a one-time pairing token triple (hub only) |
+
+## Conflict Resolution
+
+Federation uses record-level last-write-wins (LWW) with ISO timestamp comparison. When two instances modify the same record, the one with the later `updatedAt` wins. Field-level LWW is planned for a future version.
+
+## Troubleshooting
+
+### config.yaml port drift
+
+If the hub's configured port in `config.yaml` differs from the port the spoke is targeting, federation requests fail with a connection error. Verify the port matches between the spoke's pair URL and the hub's `config.yaml` (`federation.port` or the instance's listen port).
+
+```bash
+# On the hub, confirm the listening port
+grep -E 'port|federation' ~/.flair/config.yaml
+```
+
+### Local FederationInstance fetch needs auth
+
+When troubleshooting on the hub, fetching `/federation/instances/<id>` locally (e.g. via `curl localhost`) may return a 401 if the request does not carry the authentication headers the platform layer expects. On Fabric this gate is enforced even on localhost. Use the CLI tooling (`flair federation status`) instead of raw HTTP calls for local inspection.
+
+### `flair_pair_initiator` role not found on hub
+
+If pairing fails with a role-not-found error, the hub instance may be missing the `flair_pair_initiator` role. This role is created automatically during `flair init --remote` but can be lost if the database was reset or migrated manually. Re-run `flair init --remote` on the hub to restore default roles, then retry pairing.
+
+### Bootstrap user not deleted on Fabric
+
+After a successful pairing, the temporary bootstrap user is automatically deleted. If it persists on a Fabric deployment, check that the hub's Harper operations log does not show a rollback or permission error during the cleanup step. Manually removing the stale bootstrap user via the Harper Studio is safe if needed — it is never used after pairing completes.
+
+### Stale Peer record on spoke
+
+If a spoke was previously paired with a different hub (or the hub's identity key changed), the spoke may retain a stale `Peer` record pointing to the old hub. Remove the stale record before pairing with the new hub:
+
+```bash
+# Show current peers
+flair federation status
+
+# Remove a specific peer (replace <instanceId>)
+flair federation unpin <instanceId>
+```
+
+## Limitations (1.0)
+
+- **HTTP push only** — no persistent WebSocket connections or real-time sync
+- **Manual or watch-loop sync** — `flair federation sync` is one-shot; `flair federation watch --interval 30` runs it on a loop in a foreground daemon (wrap in launchd / systemd for production)
+- **Single hub** — spoke-to-spoke sync goes through the hub
+- **Record-level LWW** — not field-level; concurrent edits to different fields of the same record may lose data