@tpsdev-ai/flair 0.26.0 → 0.27.0

package/docs/rem.md

@@ -0,0 +1,60 @@
+# REM — reflection, distillation, and review
+
+REM (Reflect · Extract · Merge) is Flair's memory-curation cycle: it reads an agent's recent memories, distills them into candidate insights, and stages those candidates for explicit human/agent review — nothing is ever auto-promoted. `flair rem rapid` runs it on demand; `flair rem nightly enable` runs it on a schedule. See [`docs/notes/rem-ux.md`](notes/rem-ux.md) for the full trigger model, locality guarantees, and the review-loop UX this page's commands feed into.
+
+## Configuration
+
+Distillation runs **server-side**, via Harper's model-access API (`models.generate()`). Flair ships zero provider code — which backend answers a REM call is entirely a Harper `models:` configuration decision.
+
+The `models:` block goes in **Harper's root instance config** (`harper-config.yaml` / `harperdb-config.yaml` at the Harper data directory) — **not** in flair's own `config.yaml` component config, which Harper only loads as a non-root component config and never reads a `models:` block from.
+
+**Local Ollama (zero-key default):**
+
+```yaml
+# harper-config.yaml
+models:
+  generative:
+    default:            # unset FLAIR_REM_MODEL resolves to this logical name
+      backend: ollama
+      host: localhost:11434   # optional — already the default
+      model: llama3.1         # required — Ollama has no built-in default model
+```
+
+No credentials, nothing leaves the box (see the warning below).
+
+> **⚠️ Pick a non-thinking model for the Ollama backend.**
+> Thinking/reasoning models (`qwen3-next`, `deepseek-r1`, and similar) currently return **empty generations** through Harper's Ollama backend: Ollama routes their output into the response's `thinking` field, which the backend doesn't read, so every REM execute run fails closed with `distillation_failed` (no candidates are ever staged — the failure is availability, not correctness). Use a non-thinking model (`llama3.1`, `qwen3-coder-next`, `gemma3`, …) until the upstream backend behavior changes. Tracked in #712.
+
+**Hosted provider** (OpenAI / Anthropic / Bedrock also supported — `backend: openai|anthropic|bedrock`):
+
+```yaml
+# harper-config.yaml
+models:
+  generative:
+    hosted:
+      backend: openai
+      apiKey: ${OPENAI_API_KEY}   # env-var indirection — never a literal key in YAML
+      model: gpt-4o-mini
+```
+
+A literal (non-`${VAR}`) `apiKey` in the config file is flagged at Harper boot — keep it out of the YAML on disk. On Fabric / managed deploys, the env var itself is provisioned through Harper's Fabric secrets mechanism, which encrypts the value at rest (`enc:v1:` storage format) rather than holding it in plaintext; consult Harper's Fabric secrets documentation for provisioning that env var. Flair's own [`docs/secrets-and-keys.md`](secrets-and-keys.md) covers Flair's Ed25519 agent identity and general client-side credential patterns, but does not cover this Harper-side mechanism.
+
+> **⚠️ Data egress is a configuration decision.**
+> Pointing `models:` at a hosted provider (OpenAI, Anthropic, Bedrock, or any other network backend) sends the memory content being reflected on to that provider. A local Ollama backend keeps everything on the box — nothing transits the network. Default posture: local. Choose a hosted backend deliberately, and know what leaves when you do.
+
+### `FLAIR_REM_MODEL`
+
+Selects which `models.generative.<logicalName>` entry a REM call uses. Unset → Harper's default routing (the `default` logical name above). Set it to route to a different registered backend, e.g. `FLAIR_REM_MODEL=hosted`.
+
+### Clustered deploys — nightly enable is per-node, deliberately
+
+`flair rem nightly enable` installs a platform-native timer (launchd / systemd) **on the host it runs on**. In a multi-node or Fabric deploy, enabling it on every node would run the cycle N times and scatter N sets of pre-cycle snapshots. The v1 rule: **exactly one node gets the timer** — pick it deliberately, the same way you'd pick a cron owner for any single-writer job. This is a v1 constraint, not a permanent one; see #709 for the roadmap toward a coordinated multi-node story.
+
+Snapshot locality follows from this: a nightly cycle's pre-run snapshot (`~/.flair/snapshots/<agent>/`) lands on **the node that ran that cycle** — `flair rem restore <date>` and `flair rem snapshot list` only see local snapshots. If you move which node owns the timer, snapshot history doesn't move with it.
+
+## Interactive vs nightly
+
+- **Interactive (`flair rem rapid`):** one bounded, synchronous distillation call — gather cap 50 memories, bounded output tokens, seconds not minutes. Executes by default, staging candidates and printing a summary; `--prompt-only` returns the reflection prompt instead, for the bring-your-own-model handoff.
+- **Nightly (`flair rem nightly enable` / `run-once`):** fully detached — the scheduler runs the full cycle (snapshot → maintenance → distillation), candidates land as pending rows, and an audit row lands in `~/.flair/logs/rem-nightly.jsonl`. The operator reviews in the morning via `flair rem candidates`.
+
+Either path, the review loop is the same: `flair rem candidates` lists pending rows, `flair rem promote <id> --rationale "<why>"` / `flair rem reject <id> --reason "<why>"` decide them. Nothing self-promotes — see [`docs/notes/rem-ux.md`](notes/rem-ux.md) for why that gate is load-bearing and how the surface is expected to evolve.

package/docs/rerank-provisioning.md

@@ -0,0 +1,67 @@
+# Reranker model provisioning
+
+Flair's optional cross-encoder rerank stage (`resources/rerank-provider.ts`, gated
+behind `FLAIR_RERANK_ENABLED`) loads its model GGUF **in-process** via the same
+node-llama-cpp engine the embedding engine ships. The GGUF is **not** committed to
+the repo (`*.gguf` is gitignored) — it is provisioned into `models/` manually,
+exactly like the embedding model.
+
+The reranker is **OFF by default**. You only need to provision a GGUF if you are
+turning it on (`FLAIR_RERANK_ENABLED=true`) or running the recall-bench A/B.
+
+## Models
+
+| `FLAIR_RERANK_MODEL` | GGUF filename (under `models/`) | Source | Inference mode |
+|---|---|---|---|
+| `qwen3-reranker-0.6b-q8` (default) | `Qwen3-Reranker-0.6B-q8_0.gguf` | `Mungert/Qwen3-Reranker-0.6B-GGUF` (q8_0) | generative yes/no |
+| `jina-reranker-v2` | `jina-reranker-v2-base.Q8_0.gguf` | `gpustack/jina-reranker-v2-base-multilingual-GGUF` (q8_0) | rank-pooling cross-encoder |
+
+Download into `models/` next to the embedding GGUF, e.g.:
+
+```sh
+# quality model (Qwen3 generative path)
+huggingface-cli download Mungert/Qwen3-Reranker-0.6B-GGUF \
+  Qwen3-Reranker-0.6B-q8_0.gguf --local-dir models/
+
+# latency model (jina rank API)
+huggingface-cli download gpustack/jina-reranker-v2-base-multilingual-GGUF \
+  jina-reranker-v2-base.Q8_0.gguf --local-dir models/
+```
+
+If the GGUF is missing, the provider logs one warning and recall falls back to
+vector order — it never blocks or breaks search.
+
+## Config
+
+| Env var | Default | Meaning |
+|---|---|---|
+| `FLAIR_RERANK_ENABLED` | unset (**OFF**) | Master flag. `"true"` to enable. |
+| `FLAIR_RERANK_MODEL` | `qwen3-reranker-0.6b-q8` | Model + inference mode (table above). |
+| `FLAIR_RERANK_TOPN` | `50` | Candidate count fed to the reranker; caps the HNSW fetch. |
+| `FLAIR_RERANK_BUDGET_MS` | `2500` | Hard latency budget; exceeded → vector order. |
+| `FLAIR_RERANK_MIN_CANDIDATES` | `2` | Skip rerank below this many candidates. |
+
+## Why this serving path (not Ollama, not a microservice)
+
+- **In-process node-llama-cpp** is the same engine the embedding engine already
+  ships — no new infra, no network hop, no auth boundary. The reranker GGUF lives
+  next to the embedding GGUF and loads via the same addon-discovery pattern as
+  `embeddings-provider.ts`.
+- **Ollama is out:** it has no rerank endpoint and silently drops next-token
+  logprobs, so it can serve neither the jina rank path nor the Qwen3 generative
+  yes/no path. (Verified live against newton's Ollama 0.30.10.)
+
+## Known limitation — Qwen3 generative path inside Harper
+
+The Qwen3 generative path scores `P(yes)/(P(yes)+P(no))` via node-llama-cpp's
+`controlledEvaluate` with next-token probabilities. This works standalone and in a
+plain Node worker thread, but **inside Harper's resource runtime — where HFE's
+embedding engine has already initialized a separate native llama backend —
+`controlledEvaluate` returns an empty result (no decoded logits).** The provider
+detects this (`out.length === 0`), throws, and **fails open to vector order** (it
+never writes corrupt scores). Net effect today: with `FLAIR_RERANK_MODEL=qwen3-...`
+the rerank stage cleanly no-ops inside Harper.
+
+The `jina-reranker-v2` rank-API path (`createRankingContext()` / `rankAll`) works
+inside Harper. See the integration PR for the live recall-bench A/B numbers and the
+go/no-go read.

package/docs/secrets-and-keys.md

@@ -0,0 +1,173 @@
+# Secrets and keys
+
+Flair owns **identity**. Flair does **not** own arbitrary secrets. This page draws the line and shows you how to wire both into your agent setup without leaking anything into shell history, repo configs, or process arguments.
+
+## What Flair owns: agent identity (Ed25519)
+
+For each registered agent, Flair stores:
+
+- A **public key** in the `Agent` table (server-side; used to verify signed requests).
+- A **private key** at `~/.flair/keys/<agent>.key` on the host that owns that agent (PKCS8 base64). Created by `flair agent add <id>`. Mode `0600`.
+
+Agents sign every request to Flair with this key. Flair refuses unsigned requests and refuses signatures that don't match the registered public key. The signed payload is `<agentId>:<timestamp>:<nonce>:<METHOD>:<path>` with a 30-second replay window and nonce dedup — replays inside that window are rejected.
+
+**This is the only secret material Flair manages.** Lose the key file and the agent is locked out (`flair agent rotate <id>` to issue a new pair).
+
+## Flair admin password (Harper instance)
+- If not provided via `--admin-pass`, `--admin-pass-file`, `FLAIR_ADMIN_PASS`, or `HDB_ADMIN_PASSWORD`, a random password is generated and written to `~/.flair/admin-pass` (mode `0o600`). The password is **not** printed to the console.
+- The `--admin-pass-file <path>` option allows reading the password from a file (for pre-staged secrets).
+- The `--admin-pass <pass>` option is deprecated due to shell history exposure; use `--admin-pass-file` or environment variables instead. A warning is printed when this option is used.
+- Environment variables `FLAIR_ADMIN_PASS` and `HDB_ADMIN_PASSWORD` are also supported.
+## What Flair does *not* own: API keys, tokens, third-party credentials
+
+Things that are NOT Flair's job:
+
+- LLM provider API keys (Anthropic, OpenAI, Gemini, DeepSeek, Ollama Cloud, etc.)
+- Database connection strings
+- Cloud provider credentials (AWS, GCP, Azure)
+- GitHub PATs, GitLab tokens, npm publish tokens
+- Webhook URLs containing secrets (Discord, Slack, etc.)
+- Anything else your agent needs to talk to the rest of the world
+
+These belong in your **OS keyring** (macOS Keychain, Linux secret-service, Windows Credential Manager) or a dedicated secrets manager (1Password, HashiCorp Vault, age-sops, AWS Secrets Manager). Flair stays focused on what it's good at — identity and memory — and inherits the OS-level security model for everything else.
+
+## Patterns for wiring secrets into agent CLIs
+
+The general principle: **never put a secret in a config file checked into a repo, never pass one as a command-line argument, never `echo $SECRET` in a shell that has history**. Read it at process-start from the OS keyring or an env-only source, and pass it through the env to the child process.
+
+### macOS — Keychain
+
+Store once via the Keychain Access app, or:
+
+```bash
+security add-generic-password -a "$USER" -s "anthropic-api-key" -w "sk-ant-..."
+# read at use:
+security find-generic-password -a "$USER" -s "anthropic-api-key" -w
+```
+
+In your `.mcp.json` / `~/.gemini/settings.json` / `~/.codex/config.toml`, reference an env var (don't put the secret literal). Then export the env var from a shell wrapper that reads from Keychain at start:
+
+```bash
+# ~/.config/agent-env.sh — sourced by your shell rc, NOT checked into git
+export ANTHROPIC_API_KEY="$(security find-generic-password -a "$USER" -s "anthropic-api-key" -w)"
+export OPENAI_API_KEY="$(security find-generic-password -a "$USER" -s "openai-api-key" -w)"
+export GEMINI_API_KEY="$(security find-generic-password -a "$USER" -s "gemini-api-key" -w)"
+```
+
+Then your agent CLI configs can reference `${ANTHROPIC_API_KEY}` etc. by name.
+
+### Linux — secret-service (GNOME Keyring / KWallet via libsecret)
+
+```bash
+# Store
+secret-tool store --label="Anthropic API Key" service anthropic-api-key
+# (paste the secret when prompted)
+
+# Read
+secret-tool lookup service anthropic-api-key
+```
+
+Same wrapper-script pattern: read from `secret-tool` in `~/.config/agent-env.sh`, export as env vars.
+
+### 1Password CLI (cross-platform, recommended for teams)
+
+1Password's `op` CLI gives you reproducible secret-loading in scripts and CI:
+
+```bash
+op signin
+
+# Read at use
+ANTHROPIC_API_KEY="$(op item get "Anthropic" --field credential --reveal)"
+```
+
+For agent CLI configs, run them under `op run`, which substitutes `op://` references at process-start without ever touching disk:
+
+```bash
+op run --env-file=.env.agent -- claude
+```
+
+Where `.env.agent` (checked-in-able, just references — no secrets) contains:
+
+```
+ANTHROPIC_API_KEY=op://Personal/Anthropic/credential
+OPENAI_API_KEY=op://Personal/OpenAI/credential
+```
+
+### age + sops (for repo-checked-in encrypted secrets)
+
+If you must store secrets in a repo (e.g. a deployment config that includes a webhook URL), encrypt them with [sops](https://github.com/getsops/sops) using [age](https://github.com/FiloSottile/age) keys. Decrypt at deploy time, never in source.
+
+```bash
+# Encrypt a secrets file
+sops --age $(cat ~/.config/sops/age/keys.txt | grep public | cut -d' ' -f4) \
+     --encrypt --in-place secrets.env
+
+# At process start
+sops --decrypt secrets.env > /tmp/.env.runtime && \
+  set -a && . /tmp/.env.runtime && set +a && \
+  shred -u /tmp/.env.runtime
+```
+
+## Wiring keys into the major agent CLIs
+
+The pattern is identical across CLIs: the CLI config references env var names, your shell wrapper exports those env vars from the OS keyring at start. **The CLI config never holds the secret literal.**
+
+### Claude Code
+
+`claude` reads `ANTHROPIC_API_KEY` from the env. Set it via the wrapper-from-Keychain pattern above; never `claude --api-key sk-ant-...` (writes to shell history).
+
+The flair-mcp server (`@tpsdev-ai/flair-mcp`) reads `FLAIR_AGENT_ID` and (optionally) `FLAIR_KEY_PATH` from its own env block in `.mcp.json`. The Flair private key isn't a "secret" you load from Keychain — it's a key file that already lives at a fixed path with `0600` mode, owned by Flair.
+
+### Gemini CLI
+
+`gemini` reads `GEMINI_API_KEY` (or `GOOGLE_API_KEY` depending on the auth mode) from the env. Same wrapper pattern.
+
+For the flair-mcp server: in `~/.gemini/settings.json`, the `mcpServers.flair.env` block declares `FLAIR_AGENT_ID`, but the value is just a string (the agent id, not a secret).
+
+### OpenAI Codex CLI
+
+`codex` reads `OPENAI_API_KEY` from the env. Same wrapper pattern.
+
+For the flair-mcp server: in `~/.codex/config.toml`, the `[mcp_servers.flair.env]` table declares `FLAIR_AGENT_ID` (just a string).
+
+### Hermes (Nous Research)
+
+Hermes uses `~/.hermes/.env` for provider API keys (managed by `hermes auth`). The Flair plugin (`packages/hermes-flair/`) reads `FLAIR_AGENT_ID` and `FLAIR_KEY_PATH` from env or `$HERMES_HOME/flair.json`. Per the plugin's own `get_config_schema()`, secret fields go to `.env`, non-secret fields go to JSON.
+
+## What to do with the Flair private key itself
+
+`~/.flair/keys/<agent>.key` is the only secret Flair generates. Treat it like an SSH private key:
+
+- **Stays on the host that owns the agent.** If your agent runs on a given host, the key lives on that host. If you spin up the same agent on another machine, **don't copy the key** — register a new agent identity (`flair agent add <id>-on-<other-host>`) on that machine. Different identities, same Flair instance can store memories for both, you decide cross-agent visibility.
+- **`chmod 600` enforced** by `flair agent add`. Don't relax it.
+- **Don't check it into git.** `.gitignore` should already exclude `~/.flair/keys/`; if you're ever tempted to share keys for "convenience," rotate first (`flair agent rotate <id>`).
+- **Backup separately**, encrypted. The `flair backup` command excludes private keys by default. Roll your own backup of `~/.flair/keys/` via age-encrypted archive if you want offsite recovery.
+
+## What about a `flair secret` CLI?
+
+Considered, deferred. Flair could ship a thin wrapper around the OS keyring (`flair secret get/set/list`) — but the OS primitives already work and are universally trusted. Adding a Flair-shaped wrapper would mean we own the bug surface for marginal ergonomic gain. Better path: document the OS primitives well (this page) and stay focused on identity + memory.
+
+If you find yourself wanting one anyway, your agent can call `security find-generic-password` / `secret-tool lookup` / `op read` directly — no Flair involvement needed.
+
+## Threat model summary
+
+| Asset | Owned by | If compromised → |
+|---|---|---|
+| Flair agent private key (`~/.flair/keys/<agent>.key`) | Flair (you, on the host) | Attacker can **write** memories under that agent's identity and read that agent's **`private`**-marked memories until you rotate. Use `flair agent rotate <id>`. Other agents' write identity is unaffected — they can't be impersonated with this key. |
+| LLM provider API keys (Anthropic, OpenAI, etc.) | OS keyring / 1Password | Standard provider revocation: rotate the key in the provider's console, update keyring entry. |
+| Cross-host secrets (1Password vault, age-sops) | The secret manager itself | Trust falls back to that manager's MFA / key handling. Document recovery in your team's ops runbook. |
+| Memory contents | Flair (server-side) | Write access requires the owning agent's key → see "Per-agent write isolation, org-wide non-private read" below. |
+
+### Per-agent write isolation, org-wide non-private read
+
+Writes are scoped per `agentId` and isolation is enforced **server-side** by Ed25519 signature verification — not by client convention. An attacker with another agent's key can write memories as that agent, but cannot forge writes under *your* agent's identity without *your* key.
+
+Reads are a different, and intentionally more open, story: within one Flair instance (one org), **any** verified agent — not just an attacker with a stolen key — can already read **any other agent's non-private memory**. That's the shipped access model (open-within-org read; see [SECURITY.md](../SECURITY.md)), not a consequence of key compromise. A key leak's actual *incremental* exposure is narrower than "read your agent's memories": it's (1) the ability to write under that agent's identity, and (2) the ability to read that agent's `visibility: private` memories, which stay owner-only under normal operation. Non-private memories were already org-readable before the leak.
+
+The hard boundary in this model is the **federation edge** — a separate Flair instance / org. That's a different threat model from password-based or API-key-based memory services where a leaked key gives access to the full namespace across every trust boundary, not just one org.
+
+## See also
+
+- [`docs/auth.md`](auth.md) — full auth scheme and signature format
+- [`docs/mcp-clients.md`](mcp-clients.md) — wiring the flair-mcp server into Claude Code / Gemini CLI / Codex CLI
+- [`packages/hermes-flair/README.md`](../packages/hermes-flair/README.md) — Hermes-specific plugin auth notes

package/docs/spoke-bringup.md

@@ -0,0 +1,303 @@
+# Spoke Bring-Up Recipe
+
+Headless recipe to stand up a new Flair spoke that federates to the `flair.dtrt` hub. This is a **cut-and-paste operator guide** — every command is real and tested against the current CLI.
+
+**Target:** fresh linux-x64 VM.
+**Result:** a running spoke with an Ed25519-registered agent, paired to the hub, and pushing memories.
+
+---
+
+## 1. Prerequisites
+
+- **Node.js ≥ 22** on a linux-x64 VM. Verify:
+
+  ```bash
+  node --version   # ≥ v22.x
+  ```
+
+- **Outbound HTTPS** to the hub. The spoke pushes to the hub on `flair federation sync`; the hub never dials back.
+
+- **Admin access** to the hub — you'll need someone (or yourself, on the hub host) to run `flair federation token` and give you the resulting JSON triple.
+
+---
+
+## 2. Install Flair
+
+```bash
+npm install -g @tpsdev-ai/flair
+```
+
+Confirm the CLI is reachable:
+
+```bash
+flair --version
+```
+
+---
+
+## 3. Bootstrap the Spoke (init + agent)
+
+`flair init` handles Harper install, data-dir setup, admin-password generation, and agent registration in one shot.
+
+### 3a. Default (auto-generated admin pass, default data dir)
+
+```bash
+flair init --agent-id <spoke-agent-id>
+```
+
+- Harper installs into `~/.flair/data/`.
+- Admin password is auto-generated and written to `~/.flair/admin-pass` (mode 0600).
+- An Ed25519 keypair is created at `~/.flair/keys/<agent-id>.key`.
+- After boot, the interactive soul wizard runs — press `s` to skip in a headless pipe, or use `--skip-soul`.
+
+### 3b. Explicit data dir + admin pass (headless)
+
+```bash
+export FLAIR_ADMIN_PASS="$(openssl rand -base64 24)"
+mkdir -p /data/flair
+
+flair init \
+  --agent-id <spoke-agent-id> \
+  --data-dir /data/flair \
+  --admin-pass "$FLAIR_ADMIN_PASS" \
+  --skip-soul
+```
+
+The admin password is passed via env (`FLAIR_ADMIN_PASS` / `HDB_ADMIN_PASSWORD`), which keeps it out of shell history. If you use `--admin-pass inline-value`, the CLI prints a warning.
+
+### 3c. Custom port
+
+Default is **19926** for REST / **19925** for ops. If you need to override (port conflict, multiple instances):
+
+```bash
+flair init --agent-id <id> --port 8000
+```
+
+Port is persisted to `~/.flair/config.yaml`. The ops port is always REST port − 1 (derived automatically).
+
+---
+
+## 4. Verify the Spoke Is Running
+
+```bash
+flair status
+```
+
+Expected output: green **🟢 running** with your agent listed. If you see **🔴 unreachable**, check [docs/troubleshooting.md](troubleshooting.md).
+
+To check the instance's federation identity:
+
+```bash
+flair federation status
+```
+
+At this point you'll see your instance ID, public key, and role: `spoke`. The peer list will be empty — pairing comes next.
+
+---
+
+## 5. Pair with the Hub
+
+### 5a. Generate a pairing token on the hub
+
+On the **hub host**, an admin runs:
+
+```bash
+flair federation token --admin-pass <hub-admin-pass> > pair-triple.json
+```
+
+Output (a single JSON object):
+
+```json
+{
+  "token": "<one-time-pairing-token>",
+  "user": "pair-bootstrap-xxxxxxxx",
+  "password": "<bootstrap-password>",
+  "expiresAt": "<ISO-8601>"
+}
+```
+
+Tokens expire after **60 minutes** by default. Use `--ttl <minutes>` to extend.
+
+### 5b. Transfer the triple to the spoke
+
+```bash
+scp hub-host:/path/to/pair-triple.json ./pair-triple.json
+```
+
+### 5c. Pair from the spoke
+
+```bash
+flair federation pair https://<hub-url> \
+  --token-from ./pair-triple.json \
+  --admin-pass "$FLAIR_ADMIN_PASS"
+```
+
+The `--admin-pass` is required so the CLI can write the hub as a local `Peer` record. Without it, pairing succeeds on the hub side but the spoke never records its peer, and `flair federation sync` reports "No hub peer configured."
+
+### 5d. What pairing does
+
+1. The spoke POSTs a signed pairing request to the hub's `/FederationPair` endpoint.
+2. The bootstrap user authenticates at the Harper platform layer (works on standalone and Fabric deployments alike).
+3. The hub validates the one-time token, verifies the Ed25519 signature, and creates a `Peer` record.
+4. The spoke writes a `Peer` record pointing to the hub so sync knows where to push.
+
+---
+
+## 6. Sync for the First Time
+
+```bash
+flair federation sync --admin-pass "$FLAIR_ADMIN_PASS"
+```
+
+Expected:
+
+```
+Syncing to hub: <hub-instance-id>...
+✅ Synced 0 records (0 skipped) in 45ms
+```
+
+Then verify reachability across the federation:
+
+```bash
+flair federation reachability
+```
+
+Both local and hub peer should report `OK`.
+
+---
+
+## 7. Persist Sync (Production)
+
+For the spoke to stay connected continuously, wrap `flair federation sync` in a loop.
+
+### systemd timer (Linux)
+
+Create `~/.config/systemd/user/flair-sync.service`:
+
+```ini
+[Unit]
+Description=Flair federation sync (one-shot)
+After=flair.service
+
+[Service]
+Type=oneshot
+ExecStart=/usr/bin/env bash -c 'FLAIR_ADMIN_PASS="$(<~/.flair/admin-pass)" flair federation sync'
+Environment=HOME=%h
+```
+
+and a timer at `~/.config/systemd/user/flair-sync.timer`:
+
+```ini
+[Unit]
+Description=Flair federation sync timer
+
+[Timer]
+OnUnitActiveSec=30s
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+```
+
+```bash
+systemctl --user daemon-reload
+systemctl --user enable --now flair-sync.timer
+```
+
+### Built-in watch (foreground, for testing)
+
+```bash
+flair federation watch --interval 30
+```
+
+Press Ctrl-C to stop.
+
+---
+
+## 8. Known Gotchas
+
+### 🔸 bun pins the wrong llama.cpp platform binary
+
+Harper's NAPI modules (`llama.cpp`-backed embeddings) are built for **Node.js**, not bun. The test harness explicitly spawns Harper under `node` because bun 1.3.x doesn't support `uv_ip6_addr` — Harper crashes with a NAPI resolve panic.
+
+**Fix:** Always run Flair under Node.js. Set `NODE_HOSTNAME=127.0.0.1` (IPv4 only) in the Harper environment to bypass the IPv6 path entirely. The `flair init` command does this automatically.
+
+```bash
+# In Harper env (done automatically by flair init):
+NODE_HOSTNAME=127.0.0.1
+```
+
+### 🔸 Symlink not followed by Harper sandbox
+
+The Harper v5 sandbox blocks `node:module` (used by `createRequire` for bridge resolution) but `process.dlopen` (native addon loading) works. Some bridge packages and the OpenClaw Flair plugin reference workspace files via symlinks — Harper's sandbox won't follow them, and the plugin explicitly skips symlink escapes with a warning.
+
+**Fix:** Keep workspace files and Flair data on the same filesystem without symlinks crossing mount boundaries. If you see "skipping anchor symlink escape" warnings in the plugin logs, copy the file instead of symlinking.
+
+### 🔸 Old data-dir `lockdown:freeze` jails
+
+If Harper was previously installed with `lockdown:true` in `harper-config.yaml` or if the data dir contains a stale `hdb_boot_properties.file` from an unrelated Harper install, the install step crashes in Harper v5 beta.6+ (`checkForExistingInstall` queries the database before environment init).
+
+**Fix:** Start with a clean data dir. If reusing an existing dir, ensure no `~/.harperdb/hdb_boot_properties.file` exists and that the data dir's `harper-config.yaml` doesn't set `lockdown: true`.
+
+```bash
+# Clean up old Harper state before init:
+rm -f ~/.harperdb/hdb_boot_properties.file
+# If the data dir has lock-related entries, nuke it and re-init:
+rm -rf /data/flair
+flair init --data-dir /data/flair --agent-id <id>
+```
+
+### 🔸 Legacy hub on the old default (9926) vs a fresh spoke (19926)
+
+Flair's default REST port changed from 9926 to 19926 (ops: 9925 → 19925) to avoid Harper port collisions (see CHANGELOG.md). `flair init` today always resolves and persists the CLI's real `DEFAULT_PORT` — **19926** — to `~/.flair/config.yaml`, and that's what a fresh spoke gets. But a hub that was provisioned before that bump may still be running on the old 9926/9925 pair — nothing auto-migrates an existing instance's config. Don't assume the hub is on the current default; confirm its actual port with the hub admin, or check `~/.flair/config.yaml` on the hub host.
+
+**Fix:** Pass the hub's actual URL (with its real port) to `flair federation pair` — never assume 19926. On the spoke side, confirm your own config matches what `flair init` actually wrote:
+
+```bash
+# Verify the spoke's own config:
+grep port ~/.flair/config.yaml
+# → port: 19926   (fresh install, or whatever you passed via --port)
+
+# Or set explicitly if pairing to a hub still on the legacy default:
+export FLAIR_URL=http://127.0.0.1:9926
+```
+
+### 🔸 Fabric hosts split REST and ops ports
+
+Fabric deployments split the REST API and the Harper operations API onto adjacent ports. The derivation rule is **ops = REST − 1**. When pointing a CLI at a remote Fabric instance, pass the REST URL and the ops URL is derived automatically — substitute the hub's actual REST port (19926 for a fresh deployment, or whatever it was provisioned with):
+
+```bash
+flair federation pair https://fabric-node.example.com:19926/<instance> --token-from triple.json
+```
+
+For explicit ops control:
+
+```bash
+flair federation pair https://fabric-node.example.com:19926/<instance> \
+  --token-from triple.json \
+  --ops-target https://fabric-node.example.com:19925
+```
+
+---
+
+## 9. Quick Reference
+
+| Step | Command |
+|------|---------|
+| Install | `npm install -g @tpsdev-ai/flair` |
+| Init spoke | `flair init --agent-id <id> --data-dir /data/flair --skip-soul` |
+| Check status | `flair status` / `flair federation status` |
+| Hub: mint token | `flair federation token --admin-pass <pass> > triple.json` |
+| Spoke: pair | `flair federation pair <hub-url> --token-from ./triple.json --admin-pass <pass>` |
+| Spoke: sync | `flair federation sync --admin-pass <pass>` |
+| Spoke: verify | `flair federation reachability` |
+| Watch loop | `flair federation watch --interval 30` |
+
+---
+
+## See Also
+
+- [federation.md](federation.md) — hub-and-spoke architecture, security model, CLI reference
+- [deployment.md](deployment.md) — systemd/launchd setup, backup/restore
+- [system-requirements.md](system-requirements.md) — RAM, disk, and scaling expectations
+- [troubleshooting.md](troubleshooting.md) — common failure modes and fixes