@tpsdev-ai/flair 0.48.0 → 0.50.0

package/dist/src/lib/scheduler-platform.js

@@ -20,9 +20,9 @@
  * in `verifyFirstRun()`: success may not be claimed until the thing the
  * operator asked for has been observed to happen once.
  */
-import { existsSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
-import { resolve, dirname, isAbsolute } from "node:path";
-import { platform } from "node:os";
+import { existsSync, mkdirSync, writeFileSync, readFileSync, realpathSync } from "node:fs";
+import { resolve, dirname, isAbsolute, basename } from "node:path";
+import { platform, userInfo } from "node:os";
 import { spawnSync } from "node:child_process";
 /**
  * 30s ceiling on launchctl/systemctl invocations so a hung service manager
@@ -90,20 +90,71 @@ export function interpretActiveResult(plat, code, stdout, stderr) {
         return null; // spawn itself failed — inconclusive
     return false; // covers the no-bus case: empty stdout, nonzero/failed exit
 }
+/** True when this session already has the env `systemctl --user` needs. */
+export function sessionHasUserBusEnv(env = process.env) {
+    return Boolean(env.XDG_RUNTIME_DIR?.trim() && env.DBUS_SESSION_BUS_ADDRESS?.trim());
+}
+/**
+ * Reads whether lingering is already enabled for the current user.
+ * `loginctl show-user … Linger=yes` is the official answer; the stamp file
+ * `loginctl enable-linger` creates is the fallback when loginctl is missing
+ * or inconclusive. A failed probe is `null`, never linger-off — inventing
+ * linger-off would repeat the linger remedy after it already ran (#1107).
+ */
+export function probeUserLingerEnabled(opts = {}) {
+    const run = opts.run ?? spawnReport;
+    const lingerStampExists = opts.lingerStampExists ?? ((u) => existsSync(`/var/lib/systemd/linger/${u}`));
+    let user = "";
+    try {
+        user = userInfo().username;
+    }
+    catch {
+        user = process.env.USER || process.env.LOGNAME || "";
+    }
+    if (!user)
+        return null;
+    const r = run(["loginctl", "show-user", user, "--property=Linger"], STATUS_CHECK_TIMEOUT_MS);
+    const m = /^Linger=(yes|no)\s*$/m.exec(r.stdout ?? "");
+    if (m)
+        return m[1] === "yes";
+    if (lingerStampExists(user))
+        return true;
+    return null;
+}
 /**
- * Human remedy text for a failed scheduler-load attempt (flair#850). Covers
- * the one root cause traced so far: a missing systemd user session bus,
- * which blocks `systemctl --user` entirely in ssh-without-lingering,
- * container, and CI contexts. Returns null when the failure doesn't match a
- * known pattern — the caller already prints the raw stderr, so the operator
- * still has something to go on.
+ * Human remedy text for a failed scheduler-load attempt (flair#850, #1107).
+ * Covers the traced "no systemd user session bus" failure, which blocks
+ * `systemctl --user` entirely in ssh-without-lingering, container, and CI
+ * contexts. Two cases that used to share one remedy:
+ *   (a) lingering genuinely off — print `loginctl enable-linger`
+ *   (b) linger already on, this session has no user-bus env — print the
+ *       `XDG_RUNTIME_DIR` / `DBUS_SESSION_BUS_ADDRESS` export lines
+ * Repeating (a) after the operator has applied it is the #1107 lie.
+ * Returns null when the failure doesn't match a known pattern — the caller
+ * already prints the raw stderr, so the operator still has something to go on.
  *
  * `enableCommand` is the caller's own enable invocation, named in the remedy
  * so the operator is told to re-run the command they actually ran.
  */
-export function describeLoadFailure(plat, loadResult, enableCommand) {
+export function describeLoadFailure(plat, loadResult, enableCommand, session) {
     const stderr = loadResult.stderr || "";
     if (plat === "linux" && /failed to connect to bus/i.test(stderr)) {
+        if (session?.lingerEnabled === true) {
+            const env = session.env ?? process.env;
+            if (!sessionHasUserBusEnv(env)) {
+                return ("No systemd user session bus is available in this session. Lingering is already enabled — " +
+                    "do not re-run `loginctl enable-linger`. The remaining gap is this session's user-bus environment. " +
+                    "Export:\n" +
+                    "     export XDG_RUNTIME_DIR=/run/user/$(id -u)\n" +
+                    "     export DBUS_SESSION_BUS_ADDRESS=unix:path=$XDG_RUNTIME_DIR/bus\n" +
+                    `   then re-run \`${enableCommand}\`.`);
+            }
+            return ("No systemd user session bus is available in this session. Lingering is already enabled and " +
+                "this session already has XDG_RUNTIME_DIR / DBUS_SESSION_BUS_ADDRESS — " +
+                "do not re-run `loginctl enable-linger` or re-export those variables. " +
+                "Check that `$XDG_RUNTIME_DIR/bus` exists (the systemd --user instance may not be running), " +
+                `then re-run \`${enableCommand}\`.`);
+        }
         return ("No systemd user session bus is available in this session (common over ssh without lingering, " +
             "in containers, or under CI). Fix: enable lingering for this user — `loginctl enable-linger <user>` " +
             `— then re-run \`${enableCommand}\`.`);
@@ -172,6 +223,77 @@ export function resolveNodeBin(explicit) {
         "enable time — refusing to install a shim that would resolve `node` from the service manager's PATH " +
         "at run time. Install node (or put it on PATH for this shell) and re-run enable.");
 }
+/**
+ * Resolves the path enable will bake as FLAIR_BIN, and whether that path is
+ * the stable public `flair` entry (flair#1279).
+ *
+ * Resolution order:
+ *   1. `explicit` — caller/test override. Relatives are resolved against cwd.
+ *   2. `hooks.argv1` / `process.argv[1]` — whatever launched enable.
+ *   3. The public `flair` on PATH, only when (1) and (2) are empty.
+ * Nothing absolute resolvable ⇒ throw. A bare `"flair"` is not an exec
+ * target under #1231's `exec <node> <script>` form (`node flair` looks in
+ * cwd, not PATH).
+ */
+export function resolveFlairBin(explicit, hooks) {
+    const publicBin = hooks && "publicBin" in hooks ? (hooks.publicBin ?? null) : lookupPublicFlairBin();
+    const captured = explicit ?? hooks?.argv1 ?? process.argv[1];
+    let path;
+    if (typeof captured === "string" && captured.length > 0) {
+        path = isAbsolute(captured) ? captured : resolve(captured);
+    }
+    else if (publicBin) {
+        path = publicBin;
+    }
+    else {
+        throw new Error("unable to resolve an absolute path to the flair CLI (process.argv[1] was empty and `command -v flair` " +
+            "found nothing). The scheduler shim bakes this path in at enable time — refusing to install a shim " +
+            "whose exec target is unknown. Re-run enable via the `flair` command.");
+    }
+    return { path, publicBin, canonical: isCanonicalFlairBin(path, publicBin) };
+}
+/** True when `baked` is the public `flair` entry, not a working-tree capture. */
+export function isCanonicalFlairBin(baked, publicBin) {
+    if (basename(baked) === "flair")
+        return true;
+    if (publicBin && pathsReferToSameFile(baked, publicBin))
+        return true;
+    return false;
+}
+/**
+ * The enable-report lines for a non-canonical FLAIR_BIN. Empty when the
+ * baked path is the public entry — callers should not print a warning then.
+ */
+export function formatFlairBinWarning(baked, publicBin, enableCommand) {
+    if (isCanonicalFlairBin(baked, publicBin))
+        return [];
+    const lines = [
+        `⚠️  FLAIR_BIN is ${baked} — that is the process that ran enable, not a stable public entry.`,
+        `   A later blue/green directory swap, or deleting this working tree, will strand the scheduler unit.`,
+    ];
+    if (publicBin) {
+        lines.push(`   Public \`flair\` on PATH: ${publicBin}. Re-run \`${enableCommand}\` as the \`flair\` command to bake that path instead.`);
+    }
+    else {
+        lines.push(`   No \`flair\` on PATH. Re-run \`${enableCommand}\` via the installed \`flair\` command (or a stable symlink) so the baked path survives a tree swap.`);
+    }
+    return lines;
+}
+function lookupPublicFlairBin() {
+    const r = spawnReport(["/bin/sh", "-c", "command -v flair"], STATUS_CHECK_TIMEOUT_MS);
+    const found = r.stdout.trim().split("\n")[0]?.trim() ?? "";
+    if (r.code === 0 && found && isAbsolute(found) && existsSync(found))
+        return found;
+    return null;
+}
+function pathsReferToSameFile(a, b) {
+    try {
+        return realpathSync(a) === realpathSync(b);
+    }
+    catch {
+        return resolve(a) === resolve(b);
+    }
+}
 // ─── first-run verification (flair#1231) ────────────────────────────────────
 // A load/bootstrap command exiting 0 proves the service manager accepted the
 // job — not that the job can run. The only vantage that exercises the real

package/dist/src/rem/scheduler.js

@@ -19,7 +19,7 @@ import { homedir } from "node:os";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { escapeXml } from "../lib/xml-escape.js";
-import { detectPlatform as detectPlatformFor, spawnReport, readTemplate as readTemplateFrom, renderTemplateWith, writeFileWithDir, interpretActiveResult, describeLoadFailure as describeLoadFailureFor, describeExitCode, resolveNodeBin, verifyFirstRun, STATUS_CHECK_TIMEOUT_MS, } from "../lib/scheduler-platform.js";
+import { detectPlatform as detectPlatformFor, spawnReport, readTemplate as readTemplateFrom, renderTemplateWith, writeFileWithDir, interpretActiveResult, describeLoadFailure as describeLoadFailureFor, describeExitCode, resolveNodeBin, resolveFlairBin, formatFlairBinWarning, verifyFirstRun, probeUserLingerEnabled, STATUS_CHECK_TIMEOUT_MS, } from "../lib/scheduler-platform.js";
 // Re-exported so this module's public surface is unchanged by the extraction
 // into src/lib/scheduler-platform.ts (a second scheduler — `flair federation
 // sync enable` — needs the identical launchctl/systemctl interpretation, and
@@ -180,8 +180,8 @@ export async function queryActiveStateAsync(plat, timeoutMs = STATUS_CHECK_TIMEO
  * known pattern — the caller already prints the raw stderr, so the operator
  * still has something to go on.
  */
-export function describeLoadFailure(plat, loadResult) {
-    return describeLoadFailureFor(plat, loadResult, "flair rem nightly enable");
+export function describeLoadFailure(plat, loadResult, session) {
+    return describeLoadFailureFor(plat, loadResult, "flair rem nightly enable", session);
 }
 /**
  * Formats the `flair rem nightly enable` report from an `EnableResult`.
@@ -199,6 +199,15 @@ export function describeLoadFailure(plat, loadResult) {
  * happen once. A missing `loadResult`/`firstRun` (test-only skipLoad shape)
  * therefore withholds the headline too, instead of being treated as success.
  */
+function appendFlairBinWarning(lines, r) {
+    if (r.flairBinCanonical !== false || !r.flairBin)
+        return;
+    const warning = formatFlairBinWarning(r.flairBin, r.flairBinPublic ?? null, "flair rem nightly enable");
+    if (warning.length === 0)
+        return;
+    lines.push("");
+    lines.push(...warning);
+}
 export function formatEnableReport(r, input) {
     const { hour, minute, agentId, flairUrl } = input;
     const scheduleTime = `${String(hour).padStart(2, "0")}:${String(minute).padStart(2, "0")}`;
@@ -216,11 +225,15 @@ export function formatEnableReport(r, input) {
         ];
         if (lr.stderr)
             lines.push(`     stderr: ${lr.stderr.trim()}`);
-        const remedy = describeLoadFailure(r.platform, lr);
+        const lingerEnabled = input.lingerEnabled !== undefined
+            ? input.lingerEnabled
+            : (r.platform === "linux" ? (input.probeLinger ?? probeUserLingerEnabled)() : undefined);
+        const remedy = describeLoadFailure(r.platform, lr, { lingerEnabled, env: input.env });
         lines.push("");
         lines.push(remedy ? `   ${remedy}` : `   Re-run the activation command above manually to see the full diagnostic.`);
         lines.push("");
         lines.push(`   Nothing is scheduled until activation succeeds. Check anytime with: flair rem nightly status`);
+        appendFlairBinWarning(lines, r);
         return { lines, ok: false };
     }
     if (!r.firstRunVerified) {
@@ -272,6 +285,7 @@ export function formatEnableReport(r, input) {
         }
         lines.push("");
         lines.push(`   Check anytime with: flair rem nightly status`);
+        appendFlairBinWarning(lines, r);
         return { lines, ok: false };
     }
     const lines = [
@@ -288,6 +302,7 @@ export function formatEnableReport(r, input) {
     lines.push(`   First run:   completed through the service manager, exit 0`);
     lines.push("");
     lines.push(`Disable with \`flair rem nightly disable\`.`);
+    appendFlairBinWarning(lines, r);
     return { lines, ok: true };
 }
 /**
@@ -329,7 +344,8 @@ export function formatStatusReport(s) {
  */
 export function enableScheduler(opts) {
     const plat = detectPlatform(opts.platformOverride);
-    const flairBin = opts.flairBin ?? process.argv[1] ?? "flair";
+    const resolvedFlair = resolveFlairBin(opts.flairBin);
+    const flairBin = resolvedFlair.path;
     const nodeBin = resolveNodeBin(opts.nodeBin);
     const shimPath = opts.shimPathOverride ?? SHIM_PATH_DEFAULT;
     const templateRoot = opts.templateRootOverride ?? defaultTemplateRoot();
@@ -383,6 +399,7 @@ export function enableScheduler(opts) {
         return {
             platform: plat, shimPath, schedulerPath: plistPath, loadCommand, loadResult,
             firstRunVerified: firstRun?.verified === true, firstRun,
+            flairBin, flairBinCanonical: resolvedFlair.canonical, flairBinPublic: resolvedFlair.publicBin,
         };
     }
     // Linux: systemd user units.
@@ -408,6 +425,7 @@ export function enableScheduler(opts) {
     return {
         platform: plat, shimPath, schedulerPath: timerPath, loadCommand, loadResult,
         firstRunVerified: firstRun?.verified === true, firstRun,
+        flairBin, flairBinCanonical: resolvedFlair.canonical, flairBinPublic: resolvedFlair.publicBin,
     };
 }
 /**

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/auth.md

@@ -39,6 +39,11 @@ flair agent add myagent
 
 This is the default and recommended auth for single-instance deployments.
 
+Adapter or hosted-Flair 404? Identity is three things (keyfile + agent id +
+the `Agent` row on **that** instance). A by-id 404 is fail-closed ownership,
+never an existence signal. The adapter write-up is
+[integrations.md — Hosted Flair auth](integrations.md#hosted-flair-auth--your-agent-got-a-404).
+
 ## Deployment shapes: personal vs org
 
 Flair has no `mode`/`shape` config setting — the shape you get is emergent from *how you provision principals*, not something you declare:

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/deepseek-harness.md

@@ -4,7 +4,7 @@ Give DeepSeek Harness (DSH) sessions persistent, portable memory — no plugin c
 
 > **Verified against DSH as of 2026-08-20** (`deepseek-ai/deepseek-harness`, branch `master`). DSH is a developer preview and its own README promises compatibility-breaking changes. If wiring fails after a DSH upgrade, re-check the config field names against [their MCP client README](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/mcp/mcp-client/README.md) before suspecting Flair.
 
-The same eleven tools every other MCP client gets ([full table in mcp-clients.md](mcp-clients.md#what-the-mcp-server-exposes)) appear to the model under DSH's server-qualified names: `mcp__flair__memory_search`, `mcp__flair__memory_store`, `mcp__flair__bootstrap`, and so on — the same `mcp__<server>__<tool>` convention Claude Code uses.
+The same twelve tools every other MCP client gets ([full table in mcp-clients.md](mcp-clients.md#what-the-mcp-server-exposes)) appear to the model under DSH's server-qualified names: `mcp__flair__memory_search`, `mcp__flair__memory_store`, `mcp__flair__bootstrap`, and so on — the same `mcp__<server>__<tool>` convention Claude Code uses.
 
 Two caveats up front, both structural to DSH's bridge (details below):
 

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/hosted-on-fabric.md

@@ -138,6 +138,8 @@ flair agent add mybot --target "$FLAIR_URL" --ops-target <ops-url>
 
 Auth is the same protocol as standalone: Ed25519 signature of `agentId:timestamp:nonce:METHOD:/path`, 30-second replay window, nonce deduplication. The difference is purely the transport — HTTPS instead of localhost HTTP.
 
+An adapter that just got a 404 is almost never "Harper wants a different verb." Check the three identity pieces (keyfile, agent id, `Agent` row on **this** instance) and treat by-id 404 as fail-closed ownership, not an existence signal: [integrations.md — Hosted Flair auth](integrations.md#hosted-flair-auth--your-agent-got-a-404).
+
 See [secrets-and-keys.md](secrets-and-keys.md) for the full threat model.
 
 ---

package/docs/integrations.md

@@ -22,7 +22,9 @@ 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 |
+| **Google ADK** (Python) | [`adk-flair`](../packages/adk-flair/README.md) | Ed25519 | `BaseMemoryService`; see [hosted auth](#hosted-flair-auth--your-agent-got-a-404) if you just got a 404 |
+| **Google ADK** (JS/TS) | [`@tpsdev-ai/adk-flair`](../packages/adk-flair-js/README.md) | Ed25519 | Same identity model as the Python package |
 
 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).
 
@@ -32,6 +34,56 @@ Don't see your harness? If it speaks **MCP** — Flair already works with `flair
 
 ---
 
+## Hosted Flair auth — your agent got a 404
+
+Written for the person whose adapter just got a 404 against a hosted Flair (Harper Fabric or any non-localhost URL). Laptop `flair init` on `127.0.0.1:19926` is a different machine from the one signing the request.
+
+The protocol lives in [auth.md](auth.md). Key lifecycle lives in [secrets-and-keys.md](secrets-and-keys.md). Fabric registration (including the ops port trap) lives in [quickstart-fabric.md](quickstart-fabric.md). This section is only the identity check.
+
+### Identity is three things that must match
+
+Ed25519 agent auth is not a password. The server accepts a request only when all three line up:
+
+1. **Agent id** — `FLAIR_AGENT_ID`. This is the string inside the signature.
+2. **Keyfile on the machine that signs** — `FLAIR_KEYFILE` (adk-flair / adk-flair-js) or `FLAIR_KEY_PATH` (flair-mcp, Hermes, pi). The private key never leaves that host. `flair agent add` writes `~/.flair/keys/<id>.key`.
+3. **Server-side `Agent` row on the instance at `FLAIR_URL`** whose `publicKey` matches that keyfile. Registration is per instance. A key minted against localhost is not registered on Fabric until you run `flair agent add <id> --target` at that URL.
+
+The signed payload is `agentId:timestamp:nonce:METHOD:/path` (30-second replay window).
+
+Do not "fix" a 401 or 404 by pasting the Harper admin password into the agent's standing environment. Admin Basic auth is for registration, once. The first signed call against an unregistered id is **401 `unknown_agent`** — that is fail-closed working as designed.
+
+### The three failure shapes
+
+| Shape | What is true | What you see | What to do |
+|---|---|---|---|
+| **Record missing** | No `Agent` row for this id on **this** instance | `401 {"error":"unknown_agent"}` on every signed route | Register against the hosted URL: `flair agent add <id> --target "$FLAIR_URL" --ops-target <ops-url> --admin-pass-file <path>`. Fabric ops is not `data-port − 1` — see [quickstart-fabric.md](quickstart-fabric.md). |
+| **Key mismatch** | The id exists; the public key on the server is not the one in your keyfile | `401 {"error":"invalid_signature"}` | Same id, wrong key — copied from another host, rotated on one side only, or the env pointing at a different agent's file. Point the env at the key that matches **this** instance, or re-seed the hosted `Agent` row from the key on this machine: `flair agent add <id> --target "$FLAIR_URL" --ops-target <ops-url> --admin-pass-file <path>` (reuses the local keyfile). `flair agent rotate-key` is localhost-only. Restart the adapter so it reloads the key. |
+| **Config wrong** | Identity may be fine; you are not talking to the Flair you think | Timeouts, connection errors, or **404 from Harper's catch-all** | `FLAIR_URL` must be the origin the **signing process** can open (cloud-agent localhost is the VM, not your laptop). adk-flair also needs `FLAIR_ALLOW_REMOTE_URL=1` and a raised `FLAIR_HTTP_TIMEOUT` (defaults are localhost fail-fast). A `FLAIR_URL` with a path prefix sends every request to a route that does not exist. `/Health` can be 200 while `/Memory` is still 404 if the Flair app is not loaded yet. |
+
+Clock skew is a fourth, rarer 401: `timestamp_out_of_window`.
+
+`flair agent list` talks to **localhost**. It cannot tell you whether the hosted instance has your Agent row. The discriminator is the 401 body on a signed request.
+
+### 404 on by-id routes is not an existence signal
+
+`GET /Memory/{id}`, `PUT /Memory/{id}`, and the adapter/MCP wrappers (`memory_get`, a by-id update) return **404** both when the id is absent **and** when the record exists but your principal may not see it (another agent's `private` memory, or outside your read scope). Same status, same body shape. That is fail-closed ownership ([flair#1264](https://github.com/tpsdev-ai/flair/issues/1264)) — a 403 would confirm the id exists and can name the owner.
+
+**Do not treat that 404 as "the record is missing, so create it" or "Harper rejected the verb."** Creates go to `POST /Memory/` (id in the body). A by-id 404 after a write usually means you are not the owner the server thinks you are — go back to the three shapes above — not that you should switch PUT for POST.
+
+A verified agent that is not allowed the row gets 404, never 403. Anonymous by-id reads are denied at the gate.
+
+### Per-adapter env
+
+| Adapter | URL | Agent id | Keyfile | Hosted extras |
+|---|---|---|---|---|
+| **adk-flair** / **adk-flair-js** | `FLAIR_URL` | `FLAIR_AGENT_ID` | `FLAIR_KEYFILE` | `FLAIR_ALLOW_REMOTE_URL=1`, `FLAIR_HTTP_TIMEOUT` — [adk-flair README](../packages/adk-flair/README.md#hosted-flair) |
+| **flair-mcp** / Cursor plugin | `FLAIR_URL` | `FLAIR_AGENT_ID` | `FLAIR_KEY_PATH` (optional; auto-resolved) | Key must be on the **npx host** |
+| **Hermes / pi / LangGraph** | `FLAIR_URL` | `FLAIR_AGENT_ID` | `FLAIR_KEY_PATH` or client `keyPath` | Same Ed25519 model |
+
+n8n still uses Harper admin Basic auth — it is not this path. See [n8n.md](n8n.md#security).
+
+---
+
 ## Claude Code, Cursor, Codex, Gemini CLI, Continue.dev, Goose — via `flair-mcp`
 
 [`@tpsdev-ai/flair-mcp`](https://www.npmjs.com/package/@tpsdev-ai/flair-mcp) is a [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes Flair as a memory tool to any MCP-speaking client. One server, every MCP client.
@@ -168,13 +220,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).
 
 ---
 
@@ -188,7 +261,6 @@ If it has a custom memory protocol, the adapter pattern is small (~200 lines). L
 - CrewAI (Python `BaseRAGStorage` protocol)
 - AG2 / AutoGen (Python)
 - Mastra (TS, denser thread model)
-- ADK (Google, Python + TS)
 
 [Open an issue](https://github.com/tpsdev-ai/flair/issues) describing the harness and we'll triage. PRs welcome — see [`packages/langgraph-flair`](../packages/langgraph-flair) as the smallest-shape reference.
 
@@ -198,6 +270,7 @@ If it has a custom memory protocol, the adapter pattern is small (~200 lines). L
 
 - [Quickstart](quickstart.md) — `flair init` to working memory on a laptop
 - [Fabric Quickstart](quickstart-fabric.md) — `flair deploy` to a reachable Harper Fabric URL
+- [Hosted Flair auth](#hosted-flair-auth--your-agent-got-a-404) — Ed25519 identity, the three 401/404 shapes, why a by-id 404 is not an existence signal
 - [Embedding in a Harper app](embedding-in-a-harper-app.md) — run Flair as a component of your own Harper instance and call it in-process
 - [Memory bridges](bridges.md) — import/export Flair ↔ Mem0, ChatGPT, claude-project, markdown, agentic-stack (five bridges shipped)
 - [Federation](federation.md) — pair instances peer-to-peer for cross-machine sync