@tpsdev-ai/flair 0.25.4 → 0.27.0

package/docs/supply-chain-policy.md

@@ -0,0 +1,156 @@
+# Flair supply-chain policy
+
+How we keep Flair's published packages safe from upstream supply-chain attacks. This document describes both our policies and the automation that enforces them.
+
+> **Why this exists.** Mini Shai-Hulud worm attack (Apr 30 2026, Intercom npm + Composer PHP). Sleeper malicious Ruby gems and Go modules (May 1). NuGet typosquats with crypto-wallet stealers (May 6). The window between "package compromised" and "compromise widely flagged" is the entire risk surface, and it's been hours-to-days, not weeks. As Flair adds integration adapters across more ecosystems, our exposure grows; this is the policy + automation that bounds it.
+
+---
+
+## Policies
+
+### 1. Bake-time policy: 7 days minimum for new dep versions
+
+We don't pull in any newly-published dep version for **at least 7 days** after its publish date.
+
+- The most-attacked window is "compromise published, defenders haven't yet noticed." Most malicious packages get flagged by Socket.dev, npm advisory, GitHub security advisory, or human reports within 1-7 days. Our delay puts us behind that detection front.
+- pnpm 11 shipped this as a default at 1 day (May 4 2026). We chose 7 as a more conservative posture for a security-adjacent project.
+- Workspace-internal `@tpsdev-ai/*` deps are exempt. We publish ourselves; we have direct visibility into our own changes; our 0.8.0 → 0.8.1 patch turnaround was same-day and we want to keep that latitude.
+- Tunable via `FLAIR_DEP_MIN_AGE_DAYS` env var if a specific run needs a different threshold. Don't bypass; document the exception.
+
+#### 1a. Keep-current allow-list
+
+Some deps are tightly coupled to Flair's runtime correctness — Harper bug fixes and security patches land in `@harperfast/harper`, embedding-pipeline fixes land in `harper-fabric-embeddings`. We accept the bake-time risk and pull these eagerly. Current allow-list:
+
+| Package | Why kept current |
+|---------|------------------|
+| `@harperfast/harper` | Foundational. Vector-index and HNSW correctness fixes land here; we want them ASAP. High-volume upstream, fast detection if compromised. |
+| `harper-fabric-embeddings` | Embedding model loader. Coupled to Harper version. Same trust-and-volume reasoning. |
+| `@harperfast/oauth` | Same high-trust `@harperfast/*` owner as `@harperfast/harper`. Used ONLY by the **default-OFF** native-MCP OAuth surface (`FLAIR_MCP_OAUTH`), which dynamically imports it only when the flag is on — it is **not loaded in the shipped default build**, so bake-time exposure is zero until an operator explicitly opts in. Pinned to the exact version whose `withMCPAuth` API the surface was built against; the API surface (not a floating range) is what we depend on. |
+
+Adding to this list is a deliberate decision. The bar:
+- The upstream is well-known and high-volume (gets eyeballs fast).
+- We have a direct reason to want patches as soon as published (a known bug we're tracking, a security patch we need, or correctness coupling).
+- We accept that a freshly-malicious version could land in our build before broader detection.
+
+Document any addition here, in this section, alongside the package name. The doc is the audit trail.
+
+Override per-run via `FLAIR_DEP_KEEP_CURRENT="pkg1,pkg2,@scope/pkg3"` env (additive — adds to the default allow-list, doesn't replace it).
+
+### 2. Exact-version pinning for production deps
+
+Every `dependencies` entry in any `package.json` must be a single concrete version (`"5.0.9"`), not a range (`"^5.0"`, `"~5.0.9"`, `">=5"`). Range specifiers expose us to silent supply-chain swaps every install — exactly the surface attackers exploit.
+
+- `peerDependencies` may use ranges (host-provided; never installed by us). `devDependencies` are also exact-pinned for build reproducibility, though they don't ship in our published tarballs.
+- `bun.lock` is committed and frozen-lockfile installed in CI. Any unintended dep drift fails the workspace-deps consistency gate.
+- Pin updates happen via deliberate, test-gated PRs — never auto-merged. **Renovate is enabled** (`.github/renovate.json`) to *propose* these updates on a schedule, but it respects the bake-time cooldown (`minimumReleaseAge: "7 days"`, matching `FLAIR_DEP_MIN_AGE_DAYS`) and opens PRs only — `automerge` is off, so every bump flows through the full test suite + K&S review. Renovate uses `rangeStrategy: "pin"` so it proposes exact-version bumps (never re-widens to ranges) and shares the keep-current allow-list with `check-dep-ages.mjs`. Vulnerability alerts bypass the cooldown so security fixes aren't delayed.
+
+### 3. Internal dep version lockstep
+
+Every `@tpsdev-ai/*` dep declared in any workspace package must match the version that workspace package ships. Enforced by `scripts/check-workspace-deps.mjs` in the test-unit CI job.
+
+- Why: prevents the v0.8.0 bug shape where `openclaw-flair@0.8.0` declared `@tpsdev-ai/flair-client@0.5.0`, shipping a 3-version-old client to consumers of the published tarball.
+- See `notes/dogfood-log.md` for the full incident.
+
+### 4. Workspace `bun.lock` is the source of truth
+
+Direct `bun.lock` regenerations (e.g. `rm bun.lock && bun install`) are discouraged. They can rewrite git URLs to use ssh-protocol resolution that breaks Docker builds (the libsignal incident on PR #368) and reset other resolution choices.
+
+- Instead: use `bun install` with the existing lockfile, or surgical edits for known bug fixes.
+- All lockfile changes are reviewed; any cross-protocol or cross-version churn beyond the stated scope of the PR is a red flag.
+
+### 5. Socket.dev CI job is mandatory
+
+Every PR runs the Socket.dev Supply Chain check. Failure blocks merge. The Socket scan complements the bake-time policy — Socket catches *known* compromises; the 7-day delay catches *not-yet-known* ones.
+
+### 6. Publish surface
+
+Only Nathan publishes to npm (per the existing MFA boundary). Flint preps the release commit + version bump + CHANGELOG; Nathan runs `./scripts/release.sh <ver> --publish` from his laptop.
+
+- The build host is not logged into npm by design.
+- A planned post-publish smoke job will add an automated round-trip check after each publish to ensure cross-package resolution works on the actually-published artifacts.
+
+---
+
+## Automation
+
+### `.github/renovate.json` — deliberate, cooldown-gated update proposals
+
+Renovate opens PRs to propose dependency updates so we don't drift behind upstream indefinitely — but on our terms, not the registry's. It is configured to never auto-merge (`automerge: false`), to pin (`rangeStrategy: "pin"`, consistent with §2), and to respect the bake-time cooldown (`minimumReleaseAge: "7 days"`, matching `FLAIR_DEP_MIN_AGE_DAYS` in `check-dep-ages.mjs`) so it only proposes versions that have already cleared the detection window. Non-major updates are grouped; majors land as isolated PRs. The keep-current allow-list (`@harperfast/harper`, `harper-fabric-embeddings`, `@harperfast/oauth`) mirrors the script's `DEFAULT_KEEP_CURRENT` — keep the two in lockstep when either changes. Vulnerability alerts bypass the cooldown. Every Renovate PR still runs the full CI suite (including the bake-time and workspace-deps gates) and is K&S-reviewed before merge.
+
+### `scripts/check-workspace-deps.mjs` (already shipped, PR #368)
+
+Fails any PR where a workspace package declares an internal `@tpsdev-ai/*` dep at a version other than what that workspace package ships. Wired into the `test-unit` job.
+
+### `scripts/check-dep-ages.mjs` (this PR)
+
+Fails any PR with an external pinned production dep version published less than `FLAIR_DEP_MIN_AGE_DAYS` ago (default 7). Queries the npm registry's `time` map. Workspace-internal deps exempt. Wired into the `test-unit` job.
+
+Configurable:
+
+```bash
+# Run with a different threshold:
+FLAIR_DEP_MIN_AGE_DAYS=14 node scripts/check-dep-ages.mjs
+
+# Run against a private registry:
+FLAIR_NPM_REGISTRY=https://my-registry.example/ node scripts/check-dep-ages.mjs
+```
+
+### Pre-commit secret-guard hook (already shipped, `ops/scripts/git-hooks/`)
+
+Blocks at stage time:
+- Secret-shaped filenames (`.pem`, `.key`, `.env*`, `*api-key*`, `*pat*`, `*secret*`, etc.)
+- Embedded git clones added without a `.gitmodules` entry
+- Any single staged file >2MB
+
+Available in `ops/scripts/git-hooks/install.sh`. Required for any agent or operator with commit access.
+
+### Flair pre-commit hook (`scripts/git-hooks/`)
+
+Mirrors the CI test-unit gates locally so issues are caught at `git commit` time, not after the runner round-trip:
+
+```bash
+./scripts/git-hooks/install.sh
+```
+
+Runs three checks before each commit:
+- `check-workspace-deps.mjs` — workspace internal-dep version lockstep
+- `check-dep-ages.mjs` — supply-chain bake-time (≥7 days for external pinned deps)
+- `check-impl-term-leaks.sh` — no Bead refs / impl labels in user-facing docs
+
+Each check matches a CI gate exactly so the local and remote outcomes can't drift. Bypass with `git commit --no-verify` when warranted (rare; CI will still catch you). Skip just the dep-ages check (the slowest one, ~2-5s of registry fetches) with `FLAIR_PRECOMMIT_SKIP_DEP_AGES=1 git commit`.
+
+---
+
+## Adopting this policy in a downstream project
+
+If you're building on top of `@tpsdev-ai/flair-client` and want the same posture:
+
+```bash
+# Copy the dep-age guard into your repo
+curl -fsSL https://raw.githubusercontent.com/tpsdev-ai/flair/main/scripts/check-dep-ages.mjs \
+  -o scripts/check-dep-ages.mjs
+chmod +x scripts/check-dep-ages.mjs
+
+# Wire it into your CI as a fast pre-test step
+- run: node scripts/check-dep-ages.mjs
+```
+
+The script has no external dependencies — node 18+ is enough.
+
+---
+
+## Exceptions and incident response
+
+- **Bypass for known-good fresh dep:** set `FLAIR_DEP_MIN_AGE_DAYS=0` for the affected CI run AND open a PR to add a comment-row in this doc explaining the exception. Don't bypass silently.
+- **Confirmed upstream compromise affecting Flair:** rotate any affected credential, revert the offending dep version, ship a patch release, file a public advisory at `github.com/tpsdev-ai/flair/security/advisories`. Notify Nathan immediately; don't act unilaterally.
+- **Suspected (not confirmed) compromise:** open an issue with the evidence; treat it as P0 in our backlog until disproven.
+
+---
+
+## See also
+
+- `notes/dogfood-log.md` — internal incidents that have shaped this policy
+- `scripts/check-workspace-deps.mjs` — the workspace-internal dep consistency gate
+- `scripts/check-dep-ages.mjs` — the bake-time dep guard
+- `ops/scripts/git-hooks/pre-commit-secret-guard.sh` — pre-commit secret blocker (cross-repo)
+- `scripts/git-hooks/pre-commit` + `scripts/git-hooks/install.sh` — flair-specific pre-commit (mirrors test-unit CI gates)

package/docs/system-requirements.md

@@ -0,0 +1,42 @@
+# System Requirements
+
+Flair runs Harper v5 (a Node.js HTTP+storage runtime) plus a small CLI/MCP layer. This page documents what to expect at idle, with measured numbers from in-production deployments.
+
+## Minimum
+
+| Resource | Spec | Notes |
+|---|---|---|
+| RAM | 1 GB free | 500–800 MB resident is typical for a single-agent spoke. |
+| Disk | 250 MB | Harper data dir grows ~50–200 MB per active agent over weeks. |
+| Node | 22 LTS or 24 LTS | Native fetch + WebStreams. Verified on 22.22.x and 25.9.x. |
+| Network | Outbound HTTPS | For federation-sync to a hub. Local-only deployments need none. |
+
+## Measured at idle (single agent, no load)
+
+| Host | RAM (RSS) | Data dir | Node | Uptime | Notes |
+|---|---|---|---|---|---|
+| Mac mini (16 GB) | 740 MB daemon + ~175 MB across 4 flair-mcp clients = ~915 MB total | 163 MB | 25.9.0 | 35 min | Federation hub; 4 local agents. |
+| Linux VM (19 GB pool) | 500 MB | 88 MB | 22.22.0 | 3d 20h | Federation spoke; 1 agent. |
+| Linux VM (19 GB pool) | (not running) | 71 MB | 22.22.1 | — | Linux deps issue (backlog). |
+
+## What drives the numbers
+
+- **Embedding cache.** First semantic search per cold daemon loads `nomic-embed-text-v1.5` into memory (~270 MB). Subsequent searches reuse it. If you disable embeddings (text-only search), strip ~270 MB.
+- **HNSW index.** In-memory vector index over the agent's memories. Grows linearly with memory count; expect ~1 KB per memory plus the 768-dim vector (~1.5 KB).
+- **Harper transaction log.** Bounded by retention window; grows during writes, compacts on idle.
+- **MCP clients.** Each `flair-mcp` subprocess holds ~40–50 MB. Long-lived MCP host (Claude Code) restarts spawn fresh ones; orphaned ones from the host crashing should be cleaned up by the parent-exit watcher (PR pending).
+
+## Scaling expectations
+
+The numbers above are 1-agent steady state. Per additional agent on the same daemon:
+
+- ~50 MB additional RSS (per-agent HNSW index + small per-agent caches).
+- ~10–30 MB additional data-dir growth per week of active use.
+
+A 4-agent Mac mini at full embeddings + federation runs comfortably in 1 GB. An 8-agent host is fine in 2 GB. Multi-org hubs with hundreds of agents would want measured sizing — file an issue or join the Discord.
+
+## Known constraints
+
+- **Free Fabric tier.** ~512 MB plan ceiling. The full embedding model + HNSW + Harper is tight at that ceiling for a multi-agent spoke; a 1-agent personal spoke fits. Larger deployments (Phase 2 SLM-summarization, multi-agent hubs) require a paid Fabric tier or self-host.
+- **Cold-start.** Embedding model load is ~3–5 s on Mac arm64, ~8–12 s on commodity Linux x86. Subsequent operations are warm.
+- **No GPU required.** Embeddings run on CPU. HNSW is in-memory and CPU-only. GPU only matters if you deploy a Phase 2 SLM-based summarizer (separate process — see [bridges.md](./bridges.md#phase-2-summary-service)).

package/docs/the-team.md

@@ -0,0 +1,129 @@
+# The team behind Flair
+
+This is how LifestyleLab actually runs the multi-agent team that builds Flair, TPS, and the rest of our open-source stack. We dogfood every part of what we ship — the agents themselves are the reference implementation.
+
+If you're trying to run your own multi-agent team using Flair as the memory layer, this is the most concrete example you'll find. Steal whatever's useful.
+
+## Roster
+
+| Agent | Role | Runtime | Model | Where it runs |
+|---|---|---|---|---|
+| **Flint** | Strategy, product, PR review | Claude Code | Claude Opus | always-on local host |
+| **Anvil** | Implementation, PR opener | OpenClaw | Claude Sonnet (API) | cloud VM |
+| **Kern** | Architecture / perf review | OpenClaw | Open-source via Ollama | local inference box |
+| **Sherlock** | Security review | OpenClaw | Open-source via Ollama (local-only) | local inference box |
+| **Pulse** | EA / intel scanning / coordination | OpenClaw | Claude API | cloud VM |
+| **Nathan** | Founder / product owner / human-in-the-loop | (human) | (human) | wherever |
+
+Every agent has its own Ed25519 identity in Flair. They sign every memory write and every read. **Writes are isolated at the Flair API layer** — Sherlock can't accidentally (or maliciously) write into Pulse's memory, because the signature won't verify for anyone but Pulse. Reads are a different story: within one Flair instance, any verified agent can read any other agent's **non-private** memory — that's the shipped model (open-within-org read, no grant needed), not a gap. An agent keeps something genuinely sensitive owner-only by writing it with `visibility: private`. The hard access boundary is the **federation edge** (a separate Flair instance), not reads within one.
+
+## How memory flows
+
+```
+                                ┌────────────────────────┐                  
+                                │  Flair (self-hosted)   │                  
+                                │                        │                  
+                                │  Write isolation +     │                  
+                                │  open-within-org read, │                  
+                                │  enforced server-side  │                  
+                                │  via Ed25519 signing   │                  
+                                └─────────▲──────────────┘                  
+                                          │                                 
+        ┌─────────────────┬───────────────┼──────────────┬─────────────────┐
+        │                 │               │              │                 │
+   Flint               Anvil           Kern          Sherlock           Pulse
+   (local)           (cloud VM)    (inference box) (inference box)    (cloud VM)
+        │                 │               │              │                 │
+   writes own          writes own      writes own     writes own       writes own
+   memories only        memories only   memories only  memories only   memories only
+        │                 │               │              │                 │
+        └─────────────────┴────────┬──────┴──────────────┴─────────────────┘
+                                   │
+                       (every agent can read every other
+                        agent's non-private memories —
+                        `visibility: private` stays owner-only)
+```
+
+No agent can write into another agent's memory — that's enforced server-side by signature verification, no exceptions. Reads are intentionally open within the org: when Flint commits a piece of strategy, any agent can find it on `memory_search` unless Flint marked it `private`. **By design** — the goal is relevance and findability across the team, not secrecy between roles. An agent that genuinely needs something to stay owner-only (a draft not ready for the team, a sensitive finding pre-disclosure) marks it `visibility: private`; everything else is fair game for any teammate to search.
+
+When agents need to *coordinate* — a direct, targeted handoff rather than ambient searchable memory — they pass **explicit messages** through TPS mail (a separate signed delivery channel; see [tpsdev-ai/cli](https://github.com/tpsdev-ai/cli)). That's a different concern from memory visibility: TPS mail is for "I need you, specifically, to see this now"; Flair memory is the shared, searchable record everyone (except where `private`) can draw on later.
+
+## Why these splits
+
+### Different runtimes for different work
+
+- **Claude Code (Flint)** — strategic + code review needs Opus's depth, and Claude Code's tool ecosystem (Bash, Read/Edit/Write, web fetch, MCP) is the broadest available for "do real work in a real repo."
+- **OpenClaw (Anvil, Kern, Sherlock, Pulse)** — for agents that don't need a full IDE-grade tool surface but DO need stable always-on background capability with model-fallback routing, OpenClaw is the right runtime. It's also the one we built into TPS, so we eat our own dog food.
+
+This isn't a value judgment of one runtime over another — it's about matching the runtime to what the agent has to do. **The whole team uses Flair as the memory layer regardless of runtime.** That's the point: Flair is orchestrator-agnostic.
+
+### Local vs API for inference
+
+- **Anvil + Pulse on the Anthropic API** — high-throughput implementation work and EA-shaped intel scanning need frontier model quality and consistent latency. Worth the API spend.
+- **Kern + Sherlock on local Ollama** — review work can be slower and is bursty (a few PRs/day). Self-hosting on a local Ollama box means no rate limits, no session-locks, no third-party data exposure. Both run a large open-weight model (~120B class, permissively licensed) as primary, with smaller open models in the local fallback chain. **Sherlock is local-only as a deliberate privacy decision** — security findings are pre-disclosure-sensitive, not appropriate to send to any external inference provider.
+- **Flint on Opus** — strategy + spec writing is rate-of-thought, not rate-of-tokens. Opus's reasoning depth matters more than throughput.
+
+> **Note on migration safety nets:** when we moved the review agents off a previous cloud model onto local inference, we kept the old model as the *last* fallback for a short trial window to catch quality regressions, then removed it on a fixed date. If you're copying this setup, decide upfront whether you want a cloud safety net during your own migration — and remove it on a known date.
+
+### Different hardware for different load
+
+- **Always-on local host** — lightweight, runs the founder-facing agent + a watchdog + the local Flair Harper instance.
+- **Local inference box** — heavier local inference on a workstation with strong unified memory / GPU. Hosts Ollama; the review agents target this box.
+- **Cloud VMs** — agents that need internet-side work (intel fetching, opening GitHub PRs from a clean network space). Independent failure domain from the local stack.
+
+## The handoff loop
+
+Standard PR-shaped work flows like this:
+
+```
+  1. Nathan brings a need to Flint (Discord)
+  2. Flint writes a spec, files it in the planning repo, updates Beads
+  3. Flint mails Kern + Sherlock for arch + security review of the SPEC
+     (catch issues at design time, not after implementation)
+  4. K&S respond with concerns or sign-off
+  5. Flint refines spec, hands off to Anvil:
+        @Anvil <spec-path> branch:<name>. Open PR to main when done.
+  6. Anvil works on a feature branch, opens PR
+  7. Flint reviews PR, requests K&S review on the implementation
+  8. K&S review, comment, approve
+  9. CI green + 1 approval (or 2 for security-surface PRs) → merge
+ 10. Pulse's intel cron picks up the merge in the next 24h cycle and
+     adds it to the team's situational awareness
+```
+
+The rule that keeps this honest: **K&S approvals are individually load-bearing.** A "yes I approve" with a templated body that doesn't engage with the actual code is rejected — they have to write their own one-line rationale based on what they actually found. Otherwise the gate is theatrics. (This was a real lesson; we learned it the hard way after a rubber-stamp made it into the audit log.)
+
+## How Flair fits in
+
+Flair is the connective tissue:
+
+- **Identity:** every agent has an Ed25519 keypair in Flair (`flair agent add <id>`). All signed requests, no shared passwords, no env-var secrets to leak.
+- **Memory:** each agent writes its own lessons, decisions, observations. Flint's strategic memory survives a session crash. Anvil's "this codebase pattern works for X but fails for Y" persists across PR iterations.
+- **Soul:** each agent has a permanent personality block — role, voice, constraints. Loaded on every bootstrap so the agent stays *themselves* across sessions.
+- **Bridges:** when an agent needs context from a foreign system (e.g., Anvil needs to import lessons from another repo), bridges import them into Flair without a custom integration per source.
+
+The MCP server (`@tpsdev-ai/flair-mcp`) is what makes this orchestrator-agnostic — Flint's Claude Code, Anvil/Kern/Sherlock/Pulse's OpenClaw all hit the same Flair server with the same write-isolation-plus-open-read guarantees.
+
+## What we deliberately don't do
+
+- **No shared write identity.** Every memory is written and owned by exactly one agent's Ed25519 key — there's no merged "team" identity that can write on another agent's behalf. Reads are a separate story: within the org, any agent can search any other's non-private memory by default (see [SECURITY.md](../SECURITY.md)) — that's intentional, not a leak. TPS mail is still how agents route a message to a *specific* teammate; it's for targeted delivery, not for gating ambient visibility.
+- **No silent LLM-driven memory extraction.** Each agent decides what it remembers. No background "summarize and persist" on every turn — that's how memory drifts away from intent.
+- **No multiple agents on one identity.** "Anvil" and "Anvil-2" would be two separate agentIds with two separate keys. Same workload, different identities, separately-owned memories.
+- **No replay-safe-but-otherwise-unsigned reads.** Every Flair request is Ed25519-signed and verified, including reads. Even on a private network we don't trust the network.
+- **No password-based access to memory.** A leaked Flair admin password lets you read the database via Harper directly, but doesn't let you impersonate an agent — you can't write under their identity without their key. We treat that as the right asymmetric defense.
+
+## What we're still figuring out
+
+- **Trust-weighting the open read pool.** Open-within-org read (#578, shipped in 0.21.0) means Flint no longer has to round-trip TPS mail to see Sherlock's recent security findings — `memory_search` already surfaces them directly. What's still unbuilt is any consolidation or trust-discounting of that shared pool: today it's a bigger unfiltered pile, not a ranked or corroborated one. That's the next arc (org-identity, emergent trust from provenance/corroboration/supersession) — it needs a founder-engaged design pass before we build it, not a solo build.
+- **Rhythm agent v1.** Today's v0 is a shell-cron polling for state changes and posting to Discord. v1 moves to a dedicated low-power device, uses a small local model to summarize, and escalates only when truly stuck. Post-1.0 polish.
+
+## Try this with your own team
+
+Pick a starting point that matches your scale:
+
+- **Solo, want continuity across sessions:** install Flair, give Claude Code an MCP-wired identity (see [`docs/mcp-clients.md`](mcp-clients.md)). One agent. Done.
+- **Pair, want explicit handoffs without losing context:** add a second agent identity, each with their own MCP config + Flair agentId. Pass work via TPS mail or your own coordination channel.
+- **Small team, want to see this rig work end-to-end:** clone our setup. Use our Beads issue tracker, our TPS mail, our agent role-splits. Replace Nathan with whoever's playing founder/product-owner.
+- **Bigger team:** federate Flair instances (per [`docs/federation.md`](federation.md)). Each office has its own Flair — that org boundary (the federation edge) is what stays hard across nodes; reads are already open within each office's own instance.
+
+Read the rest of the docs from there.

package/docs/troubleshooting.md

@@ -0,0 +1,187 @@
+# Troubleshooting
+
+Start with `flair doctor` — it diagnoses most common issues automatically.
+
+```bash
+flair doctor
+```
+
+## Common Issues
+
+### "Harper is not running"
+
+**Symptoms:** `flair status` shows not running, bootstrap fails.
+
+**Fix:**
+```bash
+flair start
+```
+
+If it fails to start:
+```bash
+# Check for port conflict
+lsof -i :19926
+
+# Check logs (macOS)
+cat ~/.flair/data/log/hdb.log | tail -50
+
+# Check logs (Linux)
+journalctl --user -u flair --since "10 minutes ago"
+```
+
+### "Semantic search DEGRADED — embeddings not loaded"
+
+**Symptoms:** `flair doctor` or `flair init` reports `Semantic search DEGRADED — embeddings not loaded; recall-by-meaning will NOT work.` A paraphrase search doesn't recall a memory it should match by meaning; search only finds exact keyword overlaps.
+
+**Cause:** The in-process embeddings component (`harper-fabric-embeddings` / the nomic model) failed to initialize, so `SemanticSearch` fell back to a keyword-only scan. The most common cause on a fresh box is a **root-owned global install**: `sudo npm install -g @tpsdev-ai/flair` makes the package directory owned by root, but Harper runs as your user and gets `EACCES` when the embeddings component tries to download/symlink the model file under that package.
+
+**Fix — reinstall without sudo (recommended):**
+```bash
+# Use a user-writable npm prefix so the package dir is yours (see README Quick Start)
+mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global
+export PATH="$HOME/.npm-global/bin:$PATH"     # add to your shell rc to persist
+
+npm uninstall -g @tpsdev-ai/flair             # remove the root-owned copy (may need sudo to remove it)
+npm install -g @tpsdev-ai/flair               # reinstall, no sudo
+flair restart
+flair doctor                                  # should now report semantic search operational
+```
+
+**Other causes:** a missing native llama.cpp addon for your platform, or a corrupted/partial model download. `flair doctor` prints the underlying init error; `flair reembed` re-downloads the model and regenerates embeddings once the component loads.
+
+**HuggingFace outage:** the model normally resolves from HuggingFace (`nomic-ai/nomic-embed-text-v1.5-GGUF`). If HF is down or 403/429-ing, point `FLAIR_MODELS_DIR` at a directory containing your own copy of `nomic-embed-text-v1.5.Q4_K_M.gguf` instead of waiting it out:
+```bash
+mkdir -p ~/models
+curl -fSL -o ~/models/nomic-embed-text-v1.5.Q4_K_M.gguf \
+  https://github.com/tpsdev-ai/flair/releases/download/ci-models/nomic-embed-text-v1.5.Q4_K_M.gguf
+sha256sum ~/models/nomic-embed-text-v1.5.Q4_K_M.gguf
+# expect: d4e388894e09cf3816e8b0896d81d265b55e7a9fff9ab03fe8bf4ef5e11295ac
+
+export FLAIR_MODELS_DIR=~/models   # add to your shell rc to persist
+flair restart
+```
+The `ci-models` release above is a first-party mirror of the same file (public, no auth required) that flair's own CI falls back to for the same reason — same-origin with GitHub, no dependency on HF's availability. Always verify the sha256 against the value printed here (or in `scripts/ci/model-checksums.txt` in the repo) before pointing Harper at a manually-downloaded file.
+
+### "Embeddings: hash-fallback (512-dim)"
+
+**Symptoms:** `flair status` shows hash-fallback instead of nomic. Search returns poor results.
+
+**Cause:** The nomic-embed-text model failed to load. Usually a missing native binary or corrupted model file.
+
+**Fix:**
+```bash
+flair doctor    # shows the specific error
+flair reembed   # re-downloads model and regenerates embeddings
+```
+
+If `flair doctor` shows a native addon error:
+```bash
+# Reinstall with native dependencies
+npm install -g @tpsdev-ai/flair --force
+flair restart
+```
+
+### "invalid_signature" errors
+
+**Symptoms:** API calls return `{"error": "invalid_signature"}`.
+
+**Causes:**
+1. Agent key doesn't match what's registered in Flair
+2. Clock skew (signature includes timestamp)
+3. Wrong agent ID
+
+**Fix:**
+```bash
+# Verify the agent exists
+flair agent list
+
+# Re-register the agent's public key
+flair agent rotate-key <agent-id>
+
+# Check system clock
+date
+```
+
+If using the MCP server, restart Claude Code after rotating keys.
+
+### Port conflict
+
+**Symptoms:** `flair start` fails, "address already in use".
+
+**Fix:**
+```bash
+# Find what's using the port
+lsof -i :19926
+
+# If it's a stale Flair process
+flair stop
+flair start
+
+# If it's another application, use a different port
+flair init --port 29926
+# Or edit ~/.flair/config.yaml and restart
+```
+
+### MCP server can't connect
+
+**Symptoms:** Claude Code shows "Flair tools unavailable" or bootstrap returns nothing.
+
+**Check:**
+```bash
+# Is Flair running?
+flair status
+
+# Can you reach it?
+curl http://localhost:19926/Health
+
+# Is the agent registered?
+flair agent list
+```
+
+**Common fixes:**
+- Set `FLAIR_URL` in your MCP config if using a non-default port
+- Ensure `FLAIR_AGENT_ID` matches a registered agent
+- Restart Claude Code after config changes
+
+### Memories not showing up in search
+
+**Symptoms:** You wrote a memory but search doesn't find it.
+
+**Possible causes:**
+1. **Hash-fallback embeddings:** Check `flair status` — if embeddings are in hash mode, semantic search won't work properly. Fix with `flair reembed`.
+2. **Content safety flags:** The memory might have been flagged. Search for it directly: `flair memory list --agent <id>`.
+3. **`visibility: private`:** Reads are open within the org by default — any agent can find any other agent's non-private memories. If the memory was written with `visibility: private`, only its author can find it; search as that agent instead.
+4. **Dedup threshold:** If the content is very similar to an existing memory, it may have been deduplicated. Check with `flair memory list`.
+
+### High memory usage
+
+**Symptoms:** Harper process using excessive RAM.
+
+**Context:** Harper with nomic-embed-text loads a ~270MB model into memory. This is normal. Total memory usage should stabilize around 400-600MB.
+
+If memory keeps growing:
+```bash
+flair restart   # clean restart
+flair doctor    # check for issues
+```
+
+### "content_safety_violation" on write
+
+**Symptoms:** Memory write rejected with safety error.
+
+**Cause:** Content matched a prompt injection pattern and strict mode is enabled (`FLAIR_CONTENT_SAFETY=strict`).
+
+**Fix:** Either rephrase the content to avoid injection patterns, or switch to default mode (remove `FLAIR_CONTENT_SAFETY=strict` from environment). In default mode, flagged content is stored but tagged — not rejected.
+
+## Getting Help
+
+```bash
+flair doctor          # automated diagnosis
+flair status          # server state
+flair --help          # all commands
+flair <command> -h    # command-specific help
+```
+
+Logs: `~/.flair/data/log/hdb.log`
+
+File issues: [github.com/tpsdev-ai/flair/issues](https://github.com/tpsdev-ai/flair/issues)