@tpsdev-ai/flair 0.48.0 → 0.49.0

package/dist/resources/embeddings-boot.js

@@ -84,6 +84,7 @@
  * Harper boot), registration is skipped and logged — Harper falls back to
  * keyword-only search, matching the pre-existing degrade contract.
  */
+import { availableParallelism } from "node:os";
 import { resolveModelsDir } from "./embeddings-provider.js";
 const LOGICAL_NAME = "default";
 const MODEL_NAME = "nomic-embed-text";
@@ -148,6 +149,43 @@ const EMBEDDING_POOLING = "mean";
 function benchModelPathOverride() {
     return process.env.FLAIR_RECALL_HARNESS_MODEL_PATH || undefined;
 }
+/**
+ * llama.cpp CPU thread count passed to HFE `register({config:{threads}})`.
+ *
+ * HFE's own default is a fixed 6 (see harper-fabric-embeddings' `init()`
+ * table). flair never used to pass `threads`, so every host inherited that
+ * 6: an 8-vCPU ingest box left cores idle (flair#1330), a 4-core laptop
+ * oversubscribed. We always pass an explicit value.
+ *
+ * Default (unset / empty / non-integer / <1): `max(1, cores - 1)`. Safer
+ * than `min(6, cores)` — that still leaves the 8-vCPU case idle at 6 —
+ * and safer than using every core: Harper's JS worker (`THREADS_COUNT=1`)
+ * and the OS keep one. `availableParallelism()` (not `os.cpus().length`)
+ * so a cgroup CPU quota (Docker / k8s / Fabric) is what we count.
+ *
+ * Override: `FLAIR_EMBED_THREADS` — a positive integer, env-only. A
+ * config.yaml key would go through Harper's models-config persist path,
+ * which is exactly the class of state embeddings-boot exists to avoid
+ * (flair#694). Invalid values fall through to the host-aware default.
+ */
+export function resolveEmbedThreads(env = process.env, cores = availableParallelism()) {
+    const parsed = parsePositiveInt(env.FLAIR_EMBED_THREADS);
+    if (parsed !== undefined)
+        return parsed;
+    const safeCores = Number.isFinite(cores) && cores >= 1 ? Math.floor(cores) : 1;
+    return Math.max(1, safeCores - 1);
+}
+function parsePositiveInt(raw) {
+    if (raw == null)
+        return undefined;
+    const trimmed = raw.trim();
+    if (trimmed === "")
+        return undefined;
+    const n = Number(trimmed);
+    if (!Number.isInteger(n) || n < 1)
+        return undefined;
+    return n;
+}
 let registered = false;
 /**
  * Register the embedding backend. Idempotent within a process (mirrors
@@ -161,12 +199,16 @@ export async function registerEmbeddingsBackend() {
     try {
         const { register } = await import("harper-fabric-embeddings");
         const modelPath = benchModelPathOverride();
+        const threads = resolveEmbedThreads();
         await register({
             logicalName: LOGICAL_NAME,
             kind: "embedding",
-            config: modelPath
-                ? { modelPath, pooling: EMBEDDING_POOLING }
-                : { modelName: MODEL_NAME, modelsDir: resolveModelsDir(), pooling: EMBEDDING_POOLING },
+            config: {
+                ...(modelPath
+                    ? { modelPath, pooling: EMBEDDING_POOLING }
+                    : { modelName: MODEL_NAME, modelsDir: resolveModelsDir(), pooling: EMBEDDING_POOLING }),
+                threads,
+            },
         });
     }
     catch (err) {

package/dist/resources/memory-read-scope.js

@@ -95,5 +95,7 @@ export async function resolveReadScope(authAgentId) {
             return false;
         return record.agentId === authAgentId || !isPrivateVisibility(record.visibility);
     };
+    // See ReadScope.isAllowed's doc: agentId + visibility, nothing else.
+    isAllowed.scopableOnly = true;
     return { allowedOwners: [authAgentId], condition, isAllowed };
 }

package/dist/resources/semantic-retrieval-core.js

@@ -59,6 +59,7 @@ import { cosineSimilarity } from "./dedup.js";
 import { compositeScore } from "./scoring.js";
 import { buildBM25, fuseRrfNormalized, SEM_LIMIT } from "./bm25.js";
 import { isAllowedBm25Candidate } from "./bm25-filter.js";
+import { indexedBm25Ids } from "./bm25-index-service.js";
 // Convert HNSW cosine distance (1 - similarity) to similarity score.
 function distanceToSimilarity(distance) {
     return 1 - distance;
@@ -154,23 +155,60 @@ export async function retrieveCandidates(params) {
                 semIds.push(record.id);
             }
         }
-        // ── (b) BM25 candidate records over the SCOPED corpus ────────────────
-        const corpusQuery = conditions.length > 0
-            ? { conditions, select }
-            : { select };
-        const corpusResults = withDetachedTxn(ctx, () => databases.flair.Memory.search(corpusQuery));
+        // ── (b) The BM25 lexical leg ─────────────────────────────────────────
+        //
+        // flair#1357. This used to be unconditional: fetch the WHOLE scoped corpus
+        // out of Harper, then `buildBM25()` it — per query. That made retrieval
+        // latency linear in store size (5.6s p50 at 60k rows, 28.7s at 180k). The
+        // lexical leg is now served from a persistent, incrementally-maintained
+        // index (resources/bm25-index.ts) whose contract is RANKING-IDENTICAL:
+        // same ids, same order, byte for byte. The legacy scan below is still the
+        // reference implementation AND the fallback — the index returns null for
+        // any query it cannot reproduce exactly, and for a query with no text
+        // there is no lexical leg to serve at all.
         const allowedById = new Map();
-        const bm25Docs = [];
-        for await (const record of corpusResults) {
-            // Defense-in-depth: re-check the SAME conditions[] + temporal filters
-            // in-process. Even if a Harper query change ever let an out-of-scope
-            // record through, it is dropped here BEFORE it can be BM25-scored/fused.
-            if (!isAllowedBm25Candidate(record, conditions, { sinceDate, asOf }))
-                continue;
-            if (!passesAllowed(record))
-                continue;
-            allowedById.set(record.id, record);
-            bm25Docs.push({ id: record.id, content: record.content });
+        let bm25Ids = [];
+        // Only the no-signal listing branch (d) still needs the full scoped
+        // corpus materialised; every other branch resolves records by id.
+        const needCorpusListing = !q && !qEmb;
+        let servedFromIndex = false;
+        if (q) {
+            const fromIndex = await indexedBm25Ids({
+                q: String(q),
+                conditions: conditions,
+                timeFilters: { sinceDate, asOf },
+                isAllowed,
+                limit: SEM_LIMIT,
+                ctx,
+            });
+            if (fromIndex) {
+                bm25Ids = fromIndex;
+                servedFromIndex = true;
+            }
+        }
+        if (!servedFromIndex && (q || needCorpusListing)) {
+            // ── Legacy path: scoped corpus scan + per-query buildBM25() ──────────
+            const corpusQuery = conditions.length > 0
+                ? { conditions, select }
+                : { select };
+            const corpusResults = withDetachedTxn(ctx, () => databases.flair.Memory.search(corpusQuery));
+            const bm25Docs = [];
+            for await (const record of corpusResults) {
+                // Defense-in-depth: re-check the SAME conditions[] + temporal filters
+                // in-process. Even if a Harper query change ever let an out-of-scope
+                // record through, it is dropped here BEFORE it can be BM25-scored/fused.
+                if (!isAllowedBm25Candidate(record, conditions, { sinceDate, asOf }))
+                    continue;
+                if (!passesAllowed(record))
+                    continue;
+                allowedById.set(record.id, record);
+                bm25Docs.push({ id: record.id, content: record.content });
+            }
+            if (q) {
+                const bm25 = buildBM25(bm25Docs);
+                const ranked = bm25.rank(String(q));
+                bm25Ids = ranked.filter(r => r.score > 0).slice(0, SEM_LIMIT).map(r => r.id);
+            }
         }
         // Carry semantic candidates that survived their temporal gate into the
         // allowed map too (so a fused id always resolves to a record). Semantic
@@ -181,12 +219,45 @@ export async function retrieveCandidates(params) {
                 allowedById.set(r.id, rest);
             }
         }
-        // ── (c) BM25 lexical ranking → top SEM_LIMIT (only when q present) ────
-        let bm25Ids = [];
-        if (q) {
-            const bm25 = buildBM25(bm25Docs);
-            const ranked = bm25.rank(String(q));
-            bm25Ids = ranked.filter(r => r.score > 0).slice(0, SEM_LIMIT).map(r => r.id);
+        // ── (b2) Resolve the index-served BM25 candidates ─────────────────────
+        // On the indexed path there is no corpus map to read from, so a BM25-only
+        // rescue is point-looked-up and projected down to `select`. The projection
+        // reproduces Harper's own `search({select})` shape exactly — the keys of
+        // `select` that the row actually carries, in `select` declaration order
+        // (measured; pinned by test/integration/bm25-index-scan-order-1357.test.ts).
+        //
+        // The freshly-read row is then re-checked against the SAME conditions[] +
+        // temporal filters + scope predicate before it is allowed into the fusion.
+        // The index already applied all three to its own copy of the row; this is
+        // the Sherlock gate applied to the row we are actually about to return, so
+        // a stale index entry can only ever REMOVE a candidate, never smuggle an
+        // out-of-scope record into the union.
+        if (servedFromIndex) {
+            const resolved = [];
+            for (const id of bm25Ids) {
+                if (allowedById.has(id)) {
+                    resolved.push(id);
+                    continue;
+                }
+                const full = await withDetachedTxn(ctx, () => databases.flair.Memory.get(id));
+                if (!full)
+                    continue;
+                if (!isAllowedBm25Candidate(full, conditions, { sinceDate, asOf }))
+                    continue;
+                if (!passesAllowed(full))
+                    continue;
+                const projected = {};
+                for (const key of select)
+                    if (key in full)
+                        projected[key] = full[key];
+                allowedById.set(id, projected);
+                if (qEmb) {
+                    const storedEmbedding = Array.isArray(full.embedding) ? full.embedding : [];
+                    semSimById.set(id, cosineSimilarity(qEmb, storedEmbedding));
+                }
+                resolved.push(id);
+            }
+            bm25Ids = resolved;
         }
         // ── (d) No retrieval signal at all → full scoped listing ────────────
         if (!q && !qEmb) {

package/dist/version-check.js

@@ -18,6 +18,15 @@
  *   - No advisory data — we don't know which release fixed which CVE, so the
  *     severity heuristic is purely the version GAP (major/minor count), not
  *     "did this release carry a security fix". See classifyGap().
+ *
+ * Honest-numbers refinement (flair#1341): the TTL fast-path is only taken
+ * when the cached answer implies NOTHING will be printed. When a cached
+ * answer would produce a nudge, we spend one fresh fetch (same short timeout,
+ * same failure tolerance) so the printed fact is current whenever possible —
+ * nudges are rare, so the TTL still protects the common up-to-date path. If
+ * that fetch fails, the nudge falls back to the cached value but SAYS so
+ * ("latest known (checked 9h ago): …") instead of stating a stale number as
+ * current fact.
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -85,13 +94,23 @@ export function defaultVersionCheckDeps() {
  * Resolve the latest published @tpsdev-ai/flair version, preferring a fresh
  * cache hit over a network round trip, and falling back to a stale cache (or
  * giving up quietly) when the registry is unreachable. NEVER throws.
+ *
+ * flair#1341: the cache fast-path applies only when the cached answer implies
+ * no nudge. A cached answer that WOULD nudge triggers one fresh fetch (same
+ * timeout, same failure tolerance) so the printed fact is current whenever
+ * the network allows; on failure it falls back to the cache, age attached.
  */
 export async function checkVersion(installed, injected = {}) {
     const deps = { ...defaultVersionCheckDeps(), ...injected };
     const nowMs = deps.now();
     const cached = deps.readCache(deps.cachePath);
     if (cached && nowMs - cached.checkedAt < deps.ttlMs) {
-        return { installed, latest: cached.latest, source: "cache" };
+        if (classifyGap(installed, cached.latest).severity === "none") {
+            return { installed, latest: cached.latest, source: "cache", checkedAgoMs: nowMs - cached.checkedAt };
+        }
+        // The cached answer would print a nudge — fall through to one fresh
+        // fetch so we present a CURRENT fact when possible. The failure path
+        // below still falls back to this same cache (offline tolerance intact).
     }
     // Defense-in-depth: the default fetchLatest already catches everything
     // internally (network error, timeout, non-2xx, bad JSON) and resolves
@@ -109,10 +128,10 @@ export async function checkVersion(installed, injected = {}) {
         deps.writeCache(deps.cachePath, { latest: fetched, checkedAt: nowMs });
         return { installed, latest: fetched, source: "network" };
     }
-    // Registry unreachable/timed out — fall back to a stale cache rather than
+    // Registry unreachable/timed out — fall back to the cache rather than
     // reporting nothing, but never block or throw trying to get a fresh one.
     if (cached) {
-        return { installed, latest: cached.latest, source: "cache" };
+        return { installed, latest: cached.latest, source: "cache", checkedAgoMs: nowMs - cached.checkedAt };
     }
     return { installed, latest: null, source: "unavailable" };
 }
@@ -129,7 +148,7 @@ export function primeVersionCheckCache(latest, injected = {}) {
     const now = injected.now ?? (() => Date.now());
     writeCacheFile(cachePath, { latest, checkedAt: now() });
 }
-const NO_GAP = { severity: "none", majorBehind: false, releasesBehind: 0 };
+const NO_GAP = { severity: "none", majorBehind: false, unit: null, versionsBehind: 0 };
 /**
  * Classify how far `installed` is behind `latest` using major.minor.patch
  * math only — we don't have advisory data, so:
@@ -146,24 +165,43 @@ export function classifyGap(installed, latest) {
     const [aMaj, aMin, aPatch] = a;
     const [bMaj, bMin, bPatch] = b;
     if (bMaj > aMaj)
-        return { severity: "red", majorBehind: true, releasesBehind: 0 };
+        return { severity: "red", majorBehind: true, unit: null, versionsBehind: 0 };
     if (bMaj < aMaj)
         return NO_GAP; // installed is ahead (e.g. local/pre-release build)
     if (bMin > aMin) {
-        const releasesBehind = bMin - aMin;
-        return { severity: releasesBehind >= 2 ? "red" : "yellow", majorBehind: false, releasesBehind };
+        const versionsBehind = bMin - aMin;
+        return { severity: versionsBehind >= 2 ? "red" : "yellow", majorBehind: false, unit: "minor", versionsBehind };
     }
     if (bMin < aMin)
         return NO_GAP; // ahead on minor
-    if (bPatch > aPatch)
-        return { severity: "yellow", majorBehind: false, releasesBehind: bPatch - aPatch };
+    if (bPatch > aPatch) {
+        return { severity: "yellow", majorBehind: false, unit: "patch", versionsBehind: bPatch - aPatch };
+    }
     return NO_GAP; // equal, or ahead on patch
 }
+/** Compact human age for "checked … ago" — coarse on purpose (a nudge, not a log). */
+function formatCheckedAgo(ms) {
+    const minutes = Math.round(ms / 60_000);
+    if (minutes < 60)
+        return `${Math.max(1, minutes)}m`;
+    const hours = Math.round(ms / 3_600_000);
+    if (hours < 48)
+        return `${hours}h`;
+    return `${Math.round(ms / 86_400_000)}d`;
+}
 /**
  * Build the human-readable nudge line for `flair status`/`flair doctor`, or
  * null when there's nothing worth printing — current, ahead (local/dev
  * build), or we couldn't determine latest at all (offline with no cache).
  * Callers own icon/color; this returns plain text plus a severity to color by.
+ *
+ * flair#1341 honest-numbers contract:
+ *   - A cache-sourced answer is labelled as such ("latest known (checked 9h
+ *     ago): X"), never stated as current fact.
+ *   - The count names its unit ("N minor versions behind" / "M patch
+ *     releases behind") — it must say what classifyGap actually counted.
+ *   - The suggested command is our paved path, `flair upgrade` (refreshes
+ *     MCP pins, verifies restart — see flair#1324), not a bare npm install.
  */
 export function formatVersionNudge(result) {
     if (!result.latest)
@@ -171,11 +209,19 @@ export function formatVersionNudge(result) {
     const gap = classifyGap(result.installed, result.latest);
     if (gap.severity === "none")
         return null;
+    const latestClaim = result.source === "cache"
+        ? result.checkedAgoMs != null
+            ? `latest known (checked ${formatCheckedAgo(result.checkedAgoMs)} ago): ${result.latest}`
+            : `latest known: ${result.latest}`
+        : `latest is ${result.latest}`;
+    const plural = gap.versionsBehind === 1 ? "" : "s";
     const countHint = gap.majorBehind
-        ? "major version"
-        : `${gap.releasesBehind} release${gap.releasesBehind === 1 ? "" : "s"}`;
-    const message = `flair ${result.installed} is behind — latest is ${result.latest} (${countHint} behind). ` +
-        `Upgrade: npm i -g ${FLAIR_PKG_NAME}@latest`;
+        ? "major version behind"
+        : gap.unit === "patch"
+            ? `${gap.versionsBehind} patch release${plural} behind`
+            : `${gap.versionsBehind} minor version${plural} behind`;
+    const message = `flair ${result.installed} is behind — ${latestClaim} (${countHint}). ` +
+        `Run: flair upgrade`;
     return { severity: gap.severity, message };
 }
 /**

package/docs/claude-code.md

@@ -43,10 +43,15 @@ Copy this into your project's `CLAUDE.md` (or `.claude/settings.md`, `AGENTS.md`
 
     Run this FIRST, before doing anything else:
 
-        flair bootstrap --agent my-project --max-tokens 4000
+        mcp__flair__bootstrap
 
+    (`mcp__flair__bootstrap` is Claude Code's namespaced name for the server's `bootstrap` tool.)
     Read the output — that's your soul and recent memories.
 
+    Use the CLI variant when MCP is not wired — previewing context yourself, a script, or any agent that can run a shell command:
+
+        flair bootstrap --agent my-project --max-tokens 4000
+
     ### During work
 
     - Remember something: `flair memory add --agent my-project --content "what you learned"`
@@ -121,10 +126,12 @@ export FLAIR_URL=http://localhost:19926  # default, only needed if custom
 Then the CLAUDE.md simplifies to:
 
     ## Memory
-    - Bootstrap: `flair bootstrap`
+    - Bootstrap: `mcp__flair__bootstrap`
     - Remember: `flair memory add --content "what you learned"`
     - Search: `flair search "your query"`
 
+    Use `flair bootstrap` when MCP is not wired.
+
 ## Soul (Personality / Context)
 
 Want Claude Code to have consistent personality or project context? Set soul entries:
@@ -143,7 +150,7 @@ 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.
+Soul entries are included in every bootstrap — they're the persistent context that shapes how Claude Code thinks about your project.
 
 ## Remote Flair
 

package/docs/deployment.md

@@ -108,7 +108,7 @@ 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).
+Note: embeddings run on CPU in Docker (no Metal acceleration). Performance is acceptable for small-to-medium memory stores (< 10K memories). Thread count follows `FLAIR_EMBED_THREADS` (default `max(1, availableParallelism() − 1)`); pin it if the container CPU quota and the host you want to use disagree.
 
 ---
 
@@ -187,6 +187,16 @@ Set these in the Flair process environment (`~/Library/LaunchAgents/ai.tpsdev.fl
 | `HTTP_PORT` | Override the Harper HTTP port. Useful for sandboxes; production deployments should configure the port in `config.yaml` instead. | Rare. |
 | `FLAIR_OPS_BIND` | Bind address for the Harper **ops API**. Resolution order: `flair init --ops-bind` > this variable > the `opsBind` key `flair init` persists in `~/.flair/config.yaml` > `127.0.0.1`. Every Flair-managed Harper start re-asserts the resolved value, so the persisted key is what makes a choice survive `flair restart` / `flair upgrade`. | Only for deployments that genuinely need remote ops admin (multi-host / Fabric) — set it to `0.0.0.0`, or record it once with `flair init --ops-bind 0.0.0.0`. Single-host installs want the loopback default. |
 
+### Performance-related environment variables
+
+These are read by the Harper process at boot (same places as the table above: launchd plist, systemd unit, component `.env` / Fabric env). They are **not** `config.yaml` keys — embedding registration is in-process and must not persist into Harper's config file.
+
+| Variable | Default | What it does |
+|----------|---------|--------------|
+| `FLAIR_EMBED_THREADS` | `max(1, availableParallelism() − 1)` | CPU threads for in-process embedding (harper-fabric-embeddings / llama.cpp). Host-aware so a 4-core box does not inherit HFE's fixed 6, and an 8-vCPU ingest host is not stuck at 6 idle cores. One core is left for Harper's event loop and the OS. `availableParallelism()` respects a container CPU quota. Set a positive integer to pin. Invalid values fall back to the default. |
+| `FLAIR_HYBRID_RETRIEVAL` | `true` | Hybrid BM25 + vector retrieval. Set `false` / `0` / `off` to revert to the legacy HNSW + keyword-bump path. |
+| `FLAIR_MODELS_DIR` | `<data-dir>/models` | Directory the embedding GGUF is loaded from (and downloaded into on first boot). Point this at a pre-seeded directory to skip the HuggingFace download; see [troubleshooting.md](troubleshooting.md). |
+
 ---
 
 ## Backup & Restore

package/docs/integrations.md

@@ -22,7 +22,7 @@ Where Flair already runs. Each integration shown here is a working surface — t
 | **OpenClaw** | [`openclaw-flair`](#openclaw) | Ed25519 | Native plugin + context engine |
 | **n8n** | [`n8n-nodes-flair`](#n8n) | FlairApi credential | Three nodes (chat memory, search, store) |
 | **Hermes Agent** | [`hermes-flair`](#hermes-agent) | Ed25519 | Python `MemoryProvider` |
-| **Pi agent** | [`pi-flair`](#pi-agent) | Ed25519 | TS plugin |
+| **Pi agent** | [`pi-flair`](#pi-agent) | Ed25519 | Native pi extension (pi has no MCP support); `flair init --client pi` wires it, `flair doctor` checks it |
 
 Don't see your harness? If it speaks **MCP** — Flair already works with `flair-mcp`. If it has a **custom memory protocol** like LangGraph's `BaseStore` or CrewAI's `RAGStorage`, an adapter is a ~200-line package; [open an issue](https://github.com/tpsdev-ai/flair/issues) or [send a PR](https://github.com/tpsdev-ai/flair).
 
@@ -168,13 +168,34 @@ Auth: TPS-Ed25519 (the same model the rest of Flair uses) — writes are isolate
 
 ## Pi agent
 
-[`@tpsdev-ai/pi-flair`](https://www.npmjs.com/package/@tpsdev-ai/pi-flair) is the TS plugin for the [Pi coding agent](https://github.com/mariozechner/pi-coding-agent). Memory + identity for the Pi runtime.
+[`@tpsdev-ai/pi-flair`](https://www.npmjs.com/package/@tpsdev-ai/pi-flair) is the **native pi extension** for the [Pi coding agent](https://github.com/mariozechner/pi-coding-agent) — pi has no MCP client support, so this is a first-party plugin, not an MCP bridge. Memory + identity (`memory_search`, `memory_store`, `bootstrap`) for the pi runtime.
+
+Wire it (either form is equivalent):
+
+```bash
+flair init --client pi        # writes a pinned "packages" entry into ~/.pi/agent/settings.json
+# or
+pi install npm:@tpsdev-ai/pi-flair
+```
+
+Which produces:
+
+```json
+{
+  "packages": ["npm:@tpsdev-ai/pi-flair@<version>"]
+}
+```
+
+**Known trap:** the `extensions` settings key takes local file paths only — an `npm:` spec there is *silently ignored* by pi, so the tools never register ([#1346](https://github.com/tpsdev-ai/flair/issues/1346)). Package sources belong under `packages`. `flair doctor` detects pi, verifies the wiring, calls this exact misconfiguration out, and `flair doctor --fix` moves the entry.
+
+pi settings carry no per-package env, so identity comes from the environment that launches pi:
 
 ```bash
-npm install @tpsdev-ai/pi-flair
+export FLAIR_AGENT_ID=my-agent   # per host/purpose
+pi
 ```
 
-Pi resolves the plugin via its standard plugin config; pin `agentId` per host.
+Full details (tools, env reference, auto-recall/auto-capture flags, security notes): [`packages/pi-flair/README.md`](../packages/pi-flair/README.md).
 
 ---
 

package/docs/mcp-clients.md

@@ -266,6 +266,24 @@ The MCP server has no client-side flags beyond these env vars; everything else (
 
 ---
 
+## What about pi?
+
+pi has no MCP client support, so Flair ships a **native pi extension** instead: [`@tpsdev-ai/pi-flair`](../packages/pi-flair/README.md). Same backend, same agent isolation, zero MCP in the path.
+
+Wiring is a `packages` entry in pi's own settings (`~/.pi/agent/settings.json`), not an `mcpServers` block:
+
+```json
+{
+  "packages": ["npm:@tpsdev-ai/pi-flair@<version>"]
+}
+```
+
+`flair init --client pi` writes exactly that (pinned), or use pi's own installer: `pi install npm:@tpsdev-ai/pi-flair`. `flair doctor` detects pi and checks the wiring — including the one known trap: **an `npm:` spec under the `extensions` settings key is silently ignored by pi** (`extensions` takes local file paths only; package sources belong under `packages` — [#1346](https://github.com/tpsdev-ai/flair/issues/1346)). Doctor calls that misconfiguration out by name, and `flair doctor --fix` moves the entry.
+
+One difference from the MCP clients above: pi settings carry no per-package `env` block, so `FLAIR_AGENT_ID` (and `FLAIR_URL` when non-default) must be exported in the environment that launches pi. Doctor reports what it sees in its own shell and says so — it cannot observe the environment of every pi launch.
+
+---
+
 ## 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.

package/docs/notes/mcp-oauth-model2.md

@@ -61,25 +61,43 @@ opt-in, never something the server infers. The practical consequences:
   agent id to attach the sub to it; the step's output states the resulting
   `sub → Agent` mapping in as many words.
 - **Linking a sub to an existing Agent (the same-identity opt-in).** Re-run
-  `flair mcp enable` with the SAME `--idp-provider`/`--idp-subject` and
-  `--principal <your-cli-agent-id>`. The existing `(provider, subject)`
-  Credential is RE-POINTED to that principal — one Credential row per subject,
-  so resolution stays deterministic. The link *replaces* the mapping; it does
-  not merge the two agents' memories.
+  `flair mcp enable` with the SAME `--idp-subject` and `--principal
+  <your-cli-agent-id>`. The existing Credential for that subject is RE-POINTED
+  to that principal — one ACTIVE Credential row per subject, so resolution stays
+  deterministic. The link *replaces* the mapping; it does not merge the two
+  agents' memories.
 - **First diagnostic: ask the server who you are.** The `bootstrap` tool's
   response always carries the resolved `agentId` and a `scope` descriptor
   (`scope.agentId` / `scope.isAdmin` / `scope.reads`, flair#1182). "My memory
   is empty over the connector" + a `bootstrap.agentId` you don't recognize =
   the sub resolved to a different (often JIT-provisioned) Agent — link it as
   above.
-- **JIT caveat.** A JIT-provisioned mapping (`FLAIR_MCP_JIT_PROVISION=1`)
-  stamps `idpProvider: "mcp-oauth"`. Runtime resolution matches on
-  `(kind, idpSubject)` only, but the *linking* upsert matches on
-  `(kind, idpProvider, idpSubject)` — so when re-linking a JIT-provisioned
-  sub, pass `--idp-provider mcp-oauth` (matching the JIT stamp), or first
-  revoke the JIT credential (`status: "revoked"`). Linking under a different
-  provider name creates a SECOND active credential for the same subject, and
-  which one wins resolution is unspecified.
+- **Re-linking under a different provider name SUPERSEDES (flair#1317).** A
+  JIT-provisioned mapping (`FLAIR_MCP_JIT_PROVISION=1`) stamps `idpProvider:
+  "mcp-oauth"`, so re-linking that sub as, say, `github` is a *provider change*.
+  The invariant is **at most one ACTIVE `Credential(kind:"idp", idpSubject)` per
+  subject, regardless of provider** — the same key runtime resolution uses. So
+  the link revokes the prior credential (terminal `status: "revoked"`, the row
+  retained for audit) and writes the new one, in a single batched write. You do
+  NOT need to match `--idp-provider` to the JIT stamp, and you do not need to
+  revoke anything by hand first. `provisionIdpIdentityMapping` returns
+  `credentialSuperseded: true` with the revoked ids, and the `flair mcp enable`
+  identity-mapping step prints them.
+
+  Read `credentialSuperseded` as **"the prior credential for this subject is now
+  dead"**, not "a duplicate was tidied up". `idpProvider` is audit/diagnostic
+  metadata on the row; it does not namespace the subject. Residual risk, ruled
+  acceptable (Sherlock, #1317): anyone who can run the link for a subject can
+  revoke that subject's existing credential, so two genuinely different people
+  sharing one subject string across providers would evict each other. IdP
+  subjects are opaque per-IdP identifiers, so this is remote — and the
+  alternative, duplicate active credentials resolved by iteration order, is
+  strictly worse.
+
+  Before the fix, the linking upsert deduped on `(kind, idpProvider,
+  idpSubject)` while resolution read `(kind, idpSubject)`, so a cross-provider
+  re-link silently created a SECOND active credential and which one won was
+  unspecified.
 
 The two-identity contract (a distinct connector agent sees other agents'
 org-non-private rows, never their private rows, 404-never-403 by id; a linked

package/docs/quickstart.md

@@ -164,6 +164,14 @@ Add `--explain` to see the ranking inputs per hit — the raw score, the composi
 
 ## 6. Give your agent context on boot
 
+With MCP wired (`flair init` does this for every client it detects), the recommended session-start is the `bootstrap` tool. In Claude Code that appears as `mcp__flair__bootstrap` (Claude Code's namespaced name for the server's `bootstrap` tool). Add this to your `CLAUDE.md`:
+
+```
+At the start of every session, run mcp__flair__bootstrap before responding.
+```
+
+Use the CLI variant — `flair bootstrap --agent <id>` — when MCP is not wired: previewing context yourself, a script, or any agent that can run a shell command.
+
 ```bash
 flair bootstrap --agent local --max-tokens 2000
 ```
@@ -174,15 +182,7 @@ flair bootstrap --agent local --max-tokens 2000
 ✓ budget 20/2000 tokens (1%) · ✓ 1 included · ✓ 0 truncated
 ```
 
-Soul entries and relevant memories, in one block sized to a token budget. Paste it into any LLM session — Claude Code, Codex, Cursor, an API call — to hand the agent its identity and memory in one shot.
-
-Using Claude Code? Add this to your `CLAUDE.md`:
-
-```
-At the start of every session, run mcp__flair__bootstrap before responding.
-```
-
-With the MCP server wired up — `flair init` does this automatically for every client it detects — Claude Code runs bootstrap on every new session. See the [integration section in README.md](../README.md#integration).
+Soul entries and relevant memories, in one block sized to a token budget. Paste that CLI output into any LLM session that does not have the MCP server — Codex, Cursor, an API call — to hand the agent its identity and memory in one shot. See the [integration section in README.md](../README.md#integration).
 
 ## What's next
 

package/docs/standalone-local.md

@@ -107,6 +107,9 @@ logging:
 | `HDB_ADMIN_PASSWORD` | Bootstrap password for the embedded Harper. After first start, the persisted user record is the source of truth. | Set at install time. See [secrets-and-keys.md](secrets-and-keys.md) for rotation. |
 | `FLAIR_KEY_PASSPHRASE` | Passphrase for AES-256-GCM encryption of federation private-key seeds. | Set explicitly for production federation deployments. |
 | `FLAIR_URL` | Override the Flair base URL for CLI commands (points to a remote instance). | When connecting from a different machine. |
+| `FLAIR_EMBED_THREADS` | CPU threads for in-process embedding. Default is `max(1, availableParallelism() − 1)` — host-aware, one core left for Harper. | Pin a positive integer on a dedicated ingest host, or when the default leaves cores idle / oversubscribed. See [deployment.md](deployment.md#performance-related-environment-variables). |
+| `FLAIR_HYBRID_RETRIEVAL` | Hybrid BM25 + vector retrieval (default on). | Set `false` to revert to HNSW-only. |
+| `FLAIR_MODELS_DIR` | Directory the embedding GGUF is loaded from. | When the model lives outside `<data-dir>/models`. |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.48.0",
+  "version": "0.49.0",
   "packageManager": "bun@1.3.10",
   "description": "Identity, memory, and soul for AI agents. Cryptographic identity (Ed25519), semantic memory with local embeddings, and persistent personality — all in a single process.",
   "type": "module",
@@ -83,7 +83,8 @@
     "@opentelemetry/core": "^2.8.0",
     "uuid": "^11.1.1",
     "tar": "^7.5.22",
-    "@tootallnate/once": "^2.0.1"
+    "@tootallnate/once": "^2.0.1",
+    "form-data": "^4.0.6"
   },
   "devDependencies": {
     "@playwright/test": "1.59.1",