@tpsdev-ai/flair 0.53.0 → 0.54.2

package/dist/stamp-migration-verify.js

@@ -0,0 +1,163 @@
+/**
+ * stamp-migration-verify.ts — post-deploy / `upgrade --target` check that
+ * embedding-stamp actually converged (flair#1073).
+ *
+ * Route verify (`verifyDeployServing`) proves the component is serving.
+ * That is not enough: a Fabric upgrade can serve new writes (prefixed
+ * stamps) while pre-flip rows stay stale, and `flair status` used to
+ * report only a generic mixed-models warning. This polls authenticated
+ * /HealthDetail until the corpus is a single current space (and
+ * embedding-stamp is not halted/failed), the same way route verify polls
+ * until /Memory is non-404.
+ */
+import { EMBEDDING_STAMP_ID, stampMigrationConverged, } from "./stamp-outstanding.js";
+export const DEFAULT_STAMP_VERIFY_TIMEOUT_MS = 600_000;
+export const STAMP_VERIFY_POLL_INTERVAL_MS = 2_000;
+function basicAuthHeader(user, password) {
+    return "Basic " + Buffer.from(`${user}:${password}`, "utf8").toString("base64");
+}
+/**
+ * Parse /HealthDetail into a verify snapshot. `memories: null` (HealthDetail
+ * 200 after the Memory walk threw) and a missing `modelCounts` field stay
+ * `undefined` — that is unread, not an empty corpus. An explicit
+ * `modelCounts: {}` is the valid empty-store case (Bugbot Medium on #1606).
+ */
+export function snapshotFromHealthDetail(body) {
+    const rec = body && typeof body === "object" ? body : {};
+    const memories = rec.memories && typeof rec.memories === "object" ? rec.memories : null;
+    const migrationsBlock = rec.migrations && typeof rec.migrations === "object" ? rec.migrations : {};
+    const modelCounts = memories && memories.modelCounts && typeof memories.modelCounts === "object"
+        ? memories.modelCounts
+        : undefined;
+    const rawList = Array.isArray(migrationsBlock.migrations) ? migrationsBlock.migrations : undefined;
+    const migrations = rawList
+        ?.filter((m) => !!m && typeof m === "object" && typeof m.id === "string")
+        .map((m) => ({
+        id: m.id,
+        state: String(m.state ?? ""),
+        rowsDone: typeof m.rowsDone === "number" ? m.rowsDone : undefined,
+        rowsRemaining: typeof m.rowsRemaining === "number" ? m.rowsRemaining : undefined,
+        reason: typeof m.reason === "string" ? m.reason : undefined,
+    }));
+    const warnings = Array.isArray(rec.warnings)
+        ? rec.warnings
+            .map((w) => (w && typeof w === "object" && typeof w.message === "string" ? w.message : null))
+            .filter((m) => m !== null)
+        : undefined;
+    return {
+        modelCounts,
+        cyclePhase: typeof migrationsBlock.cyclePhase === "string" ? migrationsBlock.cyclePhase : undefined,
+        lastCycleError: typeof migrationsBlock.lastCycleError === "string" ? migrationsBlock.lastCycleError : migrationsBlock.lastCycleError === null ? null : undefined,
+        migrations,
+        warnings,
+    };
+}
+/**
+ * Read the current-space id from the HealthDetail warning or from the
+ * dominant +searchprefix / gguf: stamp. Fallback: the most common real
+ * stamp — verify then treats any other space as stale.
+ */
+export function inferCurrentModelId(snapshot) {
+    const counts = snapshot.modelCounts ?? {};
+    let best = null;
+    let prefixed = null;
+    for (const [stamp, n] of Object.entries(counts)) {
+        if (stamp === "hash-512d" || typeof n !== "number" || n <= 0)
+            continue;
+        if (!best || n > best.n)
+            best = { stamp, n };
+        if (stamp.includes("+searchprefix") && (!prefixed || n > prefixed.n))
+            prefixed = { stamp, n };
+    }
+    return prefixed?.stamp ?? best?.stamp ?? "nomic-embed-text-v1.5-Q4_K_M+searchprefix";
+}
+export function evaluateStampSnapshot(snapshot) {
+    // Unread corpus (HealthDetail omitted modelCounts, including memories: null)
+    // is not an empty store. Reject before stampMigrationConverged can treat
+    // `undefined` as `{}` and report success (Bugbot Medium on #1606).
+    if (snapshot.modelCounts === undefined) {
+        return {
+            converged: false,
+            detail: "HealthDetail did not include memories.modelCounts",
+        };
+    }
+    const outstandingWarning = snapshot.warnings?.find((w) => w.includes(`migration '${EMBEDDING_STAMP_ID}' is outstanding`) || w.includes("duplicate detection is inactive"));
+    if (outstandingWarning) {
+        return { converged: false, detail: outstandingWarning };
+    }
+    const counts = snapshot.modelCounts;
+    const realStamps = Object.entries(counts).filter(([k, n]) => k !== "hash-512d" && typeof n === "number" && n > 0);
+    // Production getModelId() stamps +searchprefix. A corpus that is entirely
+    // on the pre-flip bare id is the #1073 failure mode — do not treat a
+    // single-space bare corpus as converged just because inferCurrentModelId
+    // would pick that majority stamp as "current."
+    if (realStamps.length > 0 && realStamps.every(([k]) => !k.includes("+searchprefix"))) {
+        const list = realStamps.map(([k, n]) => `${k}:${n}`).join(", ");
+        return {
+            converged: false,
+            detail: `migration '${EMBEDDING_STAMP_ID}' is outstanding — corpus has no +searchprefix stamp yet (${list})`,
+        };
+    }
+    const currentModelId = inferCurrentModelId(snapshot);
+    const migration = snapshot.migrations?.find((m) => m.id === EMBEDDING_STAMP_ID);
+    return stampMigrationConverged({
+        modelCounts: counts,
+        currentModelId,
+        migration,
+        cyclePhase: snapshot.cyclePhase,
+        lastCycleError: snapshot.lastCycleError,
+    });
+}
+async function readHealthDetail(baseUrl, auth, fetchImpl) {
+    const url = `${baseUrl.replace(/\/+$/, "")}/HealthDetail`;
+    try {
+        const res = await fetchImpl(url, {
+            headers: { Authorization: auth, Accept: "application/json" },
+            signal: AbortSignal.timeout(15_000),
+        });
+        if (!res.ok) {
+            return { ok: false, status: res.status, error: `GET /HealthDetail returned ${res.status}` };
+        }
+        const body = await res.json();
+        return { ok: true, status: res.status, snapshot: snapshotFromHealthDetail(body) };
+    }
+    catch (err) {
+        return { ok: false, status: 0, error: err?.message ?? String(err) };
+    }
+}
+/**
+ * Poll /HealthDetail until embedding-stamp has converged, or throw.
+ * Skipped by the caller when verify is disabled (`--no-verify`).
+ */
+export async function verifyStampMigrationConverged(o) {
+    const { baseUrl, fabricUser, fabricPassword, timeoutMs = DEFAULT_STAMP_VERIFY_TIMEOUT_MS, pollIntervalMs = STAMP_VERIFY_POLL_INTERVAL_MS, fetchImpl = fetch, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), onProgress, } = o;
+    const auth = basicAuthHeader(fabricUser, fabricPassword);
+    onProgress?.(`verifying ${EMBEDDING_STAMP_ID} converged on ${baseUrl}...`);
+    const deadline = Date.now() + timeoutMs;
+    let last = await readHealthDetail(baseUrl, auth, fetchImpl);
+    for (;;) {
+        if (last.ok && last.snapshot) {
+            const verdict = evaluateStampSnapshot(last.snapshot);
+            if (verdict.converged) {
+                onProgress?.(`embedding-stamp converged`);
+                return;
+            }
+            onProgress?.(verdict.detail);
+        }
+        else {
+            onProgress?.(last.error ?? "HealthDetail not readable yet");
+        }
+        if (Date.now() >= deadline)
+            break;
+        await sleep(Math.min(pollIntervalMs, Math.max(0, deadline - Date.now())));
+        last = await readHealthDetail(baseUrl, auth, fetchImpl);
+    }
+    if (!last.ok) {
+        throw new Error(`deploy verification: embedding-stamp did not converge within ${timeoutMs}ms — ` +
+            `could not read /HealthDetail (${last.error ?? `HTTP ${last.status}`}). ` +
+            `The component may still be restarting; re-run without --no-verify, or ` +
+            `\`flair status --json\` and look for migration '${EMBEDDING_STAMP_ID}'.`);
+    }
+    const verdict = last.snapshot ? evaluateStampSnapshot(last.snapshot) : { detail: "no HealthDetail snapshot" };
+    throw new Error(`deploy verification: embedding-stamp did not converge within ${timeoutMs}ms — ${verdict.detail}`);
+}

package/dist/stamp-outstanding.js

@@ -0,0 +1,144 @@
+/**
+ * stamp-outstanding.ts — CLI-side copy of the corpus-derived
+ * "is embedding-stamp still pending?" helper (flair#1073).
+ *
+ * INLINED, not imported from resources/: cross-boundary imports from src/
+ * into resources/ do not survive npm packaging. tsconfig.cli.json compiles
+ * with `rootDir: "src"`, so dist/cli.js has no resources/ module it can
+ * resolve at the same relative path. Same reason as entity-vocab-cli.ts
+ * and the getModelId() literals in src/cli.ts.
+ *
+ * Canonical module: resources/migrations/stamp-outstanding.ts (Harper
+ * HealthDetail / embedding-stamp). The two files MUST stay in sync —
+ * test/unit/stamp-outstanding-cli-parity.test.ts pins export names and a
+ * known-answer table. Drift fails CI rather than shipping.
+ */
+export const EMBEDDING_STAMP_ID = "embedding-stamp";
+const NON_SPACE_STAMPS = new Set(["hash-512d"]);
+const DEFAULT_ENGINE = "gguf";
+export function normalizeStampForOutstanding(stamp) {
+    if (stamp == null)
+        return null;
+    const s = String(stamp).trim();
+    if (s === "" || NON_SPACE_STAMPS.has(s))
+        return null;
+    return s.includes(":") ? s : `${DEFAULT_ENGINE}:${s}`;
+}
+/**
+ * Current-space id for a client that only has `modelCounts` (no live
+ * `getModelId()`). Prefers an existing `+searchprefix` stamp so a healthy
+ * bare+`gguf:` pair of the SAME space does not invent a foreign current.
+ * A uniformly pre-flip corpus has no suffix — append `+searchprefix` so
+ * those rows read as stale.
+ */
+export function resolveCurrentModelId(modelCounts, explicit) {
+    const trimmed = explicit?.trim();
+    if (trimmed)
+        return trimmed;
+    let prefixed;
+    let anyReal;
+    for (const [stamp, n] of Object.entries(modelCounts)) {
+        if (NON_SPACE_STAMPS.has(stamp) || typeof n !== "number" || n <= 0)
+            continue;
+        anyReal ??= stamp;
+        if (stamp.includes("+searchprefix")) {
+            if (!prefixed || stamp.includes(":"))
+                prefixed = stamp;
+        }
+    }
+    if (prefixed)
+        return prefixed;
+    if (anyReal) {
+        const bare = anyReal.includes(":") ? anyReal.slice(anyReal.indexOf(":") + 1) : anyReal;
+        return `${DEFAULT_ENGINE}:${bare}+searchprefix`;
+    }
+    return `${DEFAULT_ENGINE}:nomic-embed-text-v1.5-Q4_K_M+searchprefix`;
+}
+export function countStampSpaces(modelCounts, currentModelId) {
+    const currentSpace = normalizeStampForOutstanding(currentModelId);
+    let currentCount = 0;
+    let staleCount = 0;
+    const staleStamps = [];
+    for (const [raw, n] of Object.entries(modelCounts)) {
+        if (typeof n !== "number" || n <= 0)
+            continue;
+        const space = normalizeStampForOutstanding(raw);
+        if (space === null)
+            continue;
+        if (currentSpace !== null && space === currentSpace) {
+            currentCount += n;
+        }
+        else {
+            staleCount += n;
+            staleStamps.push(`${raw}:${n}`);
+        }
+    }
+    return { currentCount, staleCount, staleStamps, currentSpace };
+}
+function runnerAnnotation(input) {
+    const mig = input.migration;
+    const phase = input.cyclePhase;
+    if (input.lastCycleError) {
+        return ` last boot cycle failed (${input.lastCycleError})`;
+    }
+    if (phase === "idle") {
+        return " migration boot cycle never fired on this instance — no migration will run until this is resolved";
+    }
+    if (mig?.state === "running" || mig?.state === "checking" || mig?.state === "preflight" || mig?.state === "snapshotting" || mig?.state === "completing") {
+        const rem = typeof mig.rowsRemaining === "number" ? `, ${mig.rowsRemaining} remaining` : "";
+        return ` in progress (${mig.state}${rem})`;
+    }
+    if (mig?.state === "halted" || mig?.state === "failed") {
+        return ` ${mig.state}${mig.reason ? `: ${mig.reason}` : ""} — see \`flair doctor\``;
+    }
+    if (mig?.state === "completed" || phase === "done") {
+        return " the last cycle marked it complete without converging; it will retry automatically";
+    }
+    if (input.audience === "client") {
+        return " the Harper process applies it on its next migration cycle — this CLI does not";
+    }
+    return " it will apply automatically on this process's next migration cycle";
+}
+export function describeStampOutstanding(input) {
+    const { currentCount, staleCount, staleStamps } = countStampSpaces(input.modelCounts, input.currentModelId);
+    if (staleCount === 0) {
+        return { outstanding: false, staleCount: 0, currentCount };
+    }
+    const list = staleStamps.join(", ");
+    const warning = `migration '${EMBEDDING_STAMP_ID}' is outstanding ` +
+        `(${staleCount} row${staleCount === 1 ? "" : "s"} still on ${list}` +
+        `${currentCount > 0 ? `, ${currentCount} already current` : ""}) — ` +
+        `cross-model search is unreliable and duplicate detection is inactive ` +
+        `until the re-embed completes;` +
+        runnerAnnotation(input);
+    return {
+        outstanding: true,
+        migrationId: EMBEDDING_STAMP_ID,
+        staleCount,
+        currentCount,
+        staleStamps,
+        warning,
+    };
+}
+export function stampMigrationConverged(input) {
+    const described = describeStampOutstanding(input);
+    if (described.outstanding) {
+        return { converged: false, detail: described.warning };
+    }
+    const mig = input.migration;
+    if (mig?.state === "halted" || mig?.state === "failed") {
+        return {
+            converged: false,
+            detail: `migration '${EMBEDDING_STAMP_ID}' ${mig.state}${mig.reason ? `: ${mig.reason}` : ""}`,
+        };
+    }
+    if (mig &&
+        (mig.state === "running" ||
+            mig.state === "checking" ||
+            mig.state === "preflight" ||
+            mig.state === "snapshotting" ||
+            mig.state === "completing")) {
+        return { converged: false, detail: `migration '${EMBEDDING_STAMP_ID}' still ${mig.state}` };
+    }
+    return { converged: true, detail: "embedding-stamp converged (corpus is a single current space)" };
+}

package/dist/version-check.js

@@ -32,6 +32,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { parseSemverCore } from "./fabric-upgrade.js";
+import { fetchLatestVersion } from "./lib/npm-registry.js";
 export const FLAIR_PKG_NAME = "@tpsdev-ai/flair";
 export const DEFAULT_CACHE_PATH = join(homedir(), ".flair", ".version-check-cache.json");
 /** How long a cached "latest" answer is trusted before we re-hit the registry. */
@@ -65,19 +66,39 @@ function writeCacheFile(path, entry) {
 }
 async function defaultFetchLatest(timeoutMs) {
     try {
-        const res = await fetch(`https://registry.npmjs.org/${FLAIR_PKG_NAME}/latest`, {
-            signal: AbortSignal.timeout(timeoutMs),
-        });
-        if (!res.ok)
+        // flair#1688: honour the registry npm is configured to use (scoped
+        // `@scope:registry`, project/user/global .npmrc, env `npm_config_registry`)
+        // rather than a hardcoded public host — a private mirror must not be
+        // silently bypassed by the update check.
+        //
+        // flair#1692: `fetchLatestVersion` validates the URL scheme, refuses
+        // redirects, applies npm's transport where a bare fetch cannot, and —
+        // critically — validates the returned value as strict semver before it can
+        // ever be used as an install spec.
+        const result = await fetchLatestVersion(FLAIR_PKG_NAME, { timeoutMs });
+        if (result.kind === "ok")
+            return result.version;
+        if (result.kind === "invalid") {
+            // A hostile/compromised registry can return a URL or tag as `latest`;
+            // npm would install `pkg@<url>` as a remote tarball. Refuse, and say so
+            // rather than silently treating it as "no update".
+            console.error(`flair version check: the configured registry returned a non-semver "latest" (${JSON.stringify(result.value)}) ` +
+                `from ${result.registry.url} — refusing to use it. Check \`registry\` / \`@scope:registry\` (source: ${result.registry.source}).`);
             return null;
-        const data = (await res.json());
-        return typeof data?.version === "string" ? data.version : null;
-    }
-    catch {
+        }
+        if (result.kind === "refused") {
+            console.error(result.message);
+            return null;
+        }
         // Offline, DNS failure, timeout, registry 5xx, bad JSON — all the same:
         // we couldn't determine "latest" over the network this time.
         return null;
     }
+    catch {
+        // Defense-in-depth: the helper already swallows its failure modes. This
+        // guards the status/doctor never-throws contract even if it does not.
+        return null;
+    }
 }
 export function defaultVersionCheckDeps() {
     return {

package/docs/api-reference.md

@@ -154,7 +154,8 @@ Skill-tagged Memory rows embed from `trigger` (the recall signal), not
 | GET / POST / PUT | `/WorkspaceState` | Ed25519 | Owner-only. POST stamps `agentId`; PUT rejects a mismatch. |
 | GET | `/WorkspaceLatest` | Ed25519 | Latest workspace row for the caller. |
 | GET / POST / PUT | `/OrgEvent` | Ed25519 | Any verified agent reads every event. Writes stamp `authorId`. |
-| GET | `/OrgEventCatchup` | Ed25519 | Catch-up feed for the caller. |
+| GET / POST | `/OrgEventCatchup` | Ed25519 | Catch-up feed for the caller. `since` is optional (defaults to the per-agent watermark). GET pages; POST acks `{ position }` (advance-on-ack). |
+| GET / POST | `/AgentReadPosition` | Ed25519 | Owner-only watermark (`stream`, default `org-event`). Foundation for light-comms catch-up. |
 | POST | `/OrgEventMaintenance` | Ed25519 / admin | Expire / sweep org events. |
 | POST | `/AttentionQuery` | Ed25519 | Cross-table “what touches entity E”. Entity strings: [docs/entity-vocabulary.md](entity-vocabulary.md). |
 
@@ -163,7 +164,7 @@ Skill-tagged Memory rows embed from `trigger` (the recall signal), not
 | Method | Path | Auth | Notes |
 |--------|------|------|-------|
 | GET | `/FederationInstance` | Admin Basic | Local instance identity (CLI / admin). Peers do not call this during pair. |
-| POST | `/FederationPair` | Pairing token + body-sig | Public at the Harper role gate. Handler validates token, signature, anti-replay. Fabric uses the bootstrap-user triple from `flair federation token`. |
+| POST | `/FederationPair` | Pairing token + body-sig | Public at the Harper role gate. Handler validates token, signature, anti-replay. Response includes `instance {id, publicKey}` when this hub has an Instance row; `instance` is null if it does not (flair#839). The spoke CLI must not store an empty hub key (flair#822). Fabric uses the bootstrap-user triple from `flair federation token`. |
 | POST | `/FederationSync` | Peer body-sig | Public at the role gate. Merge Memory / Soul / Agent / Relationship (and classifier-ready Message). Originator + per-record signature checks. |
 | GET | `/FederationPeers` | Admin Basic | Known peers. |
 | GET / write | `/Instance` | Read: Ed25519. Write: admin | Instance row (`flair_…` id, role hub/spoke). |
@@ -355,6 +356,7 @@ ed25519 / idp) and **Integration** (legacy platform connection).
 | **Asset** | memory.graphql | yes | Blob (`contentType`, `data`) owned by `agentId`, linked by `memoryId` |
 | **WorkspaceState** | workspace.graphql | yes | Current work (`ref`, `provider`, `phase`, `entities`) |
 | **OrgEvent** | event.graphql | yes | Org-visible event (`authorId`, `kind`, `summary`, `entities`) |
+| **AgentReadPosition** | agent.graphql | no | Per-agent watermark (`agentId`, `stream`, `position`). HTTP via `/AgentReadPosition`, not raw-table REST. |
 | **Message** | message.graphql | yes | Signed envelope (`from`, `to`, `threadId`, `seq`, `state`, `signature`) |
 | **OAuthClient** | oauth.graphql | yes | Registered OAuth clients |
 | **OAuthAuthCode** | oauth.graphql | no | Single-use codes + PKCE |

package/docs/deploying-on-fabric.md

@@ -241,7 +241,9 @@ Provision once, from one place, before serving multi-region traffic: step 2's
 | `flair fleet verify --target <url>` | health, auth, version across origin + Flair peers |
 | `flair federation status\|verify\|reachability --target <url>` | peer table, sync recency, probes |
 
-`fleet verify` exit codes: 1 origin failed, 2 peer version skew, 3 peer unverifiable.
+`fleet verify` exit codes: 1 origin failed, 2 reachable peer diverged (wrong version), 3 reachable peer unreachable/auth-failed. Unverifiable peers (no endpoint on file) warn and exit 0.
+
+`federation verify` is a different question (did this canary land). Exit 0 includes unverifiable peers (401/403, unreachable); exit 1 is a reachable peer missing the canary. It pushes before probing so a spoke with no sync daemon can still check.
 
 > **A credential mismatch renders as an empty section, not an error.** `flair status`
 > reads `/HealthDetail` with `FLAIR_ADMIN_PASS` / `HDB_ADMIN_PASSWORD` / a pinned agent
@@ -299,17 +301,16 @@ without this re-flip will appear healthy (`/Health` green) while its MCP tools a
 dark to every connected client. If you rely on MCP, add the re-flip to your upgrade
 runbook.
 
-### Known hazard: unbounded npm cache
+### npm cache on the node
 
-**Open — [flair#886](https://github.com/tpsdev-ai/flair/issues/886).** Every deploy runs a
-server-side `npm install` using the node's default cache. npm never evicts it, so it
-grows until it fills the quota.
+`flair deploy` and `flair upgrade --target` pass Harper an `install_command` that runs
+`npm install --cache <tmp>` and deletes that directory when the install finishes. The
+node's `~/.npm/_cacache` is no longer the install cache, so repeated deploys do not
+accumulate tarballs ([flair#886](https://github.com/tpsdev-ai/flair/issues/886)).
 
-No in-product mitigation: no cache flag, no alternate location, no cleanup. One install
-per deploy bounds the *rate*, not the total. Harper consults `install_command` only when
-`node_modules` is absent and `deploy_component` has no force-reinstall option, so the
-obvious fix isn't available — and clearing the cache needs node access this shape
-doesn't give you.
+Harper still consults `install_command` only when `node_modules` is absent — that is
+exactly when a fresh extract runs the install, which is every deploy (Harper replaces
+the component directory). There is nothing for an operator to clean.
 
 ### Backup and rollback
 

package/docs/deployment.md

@@ -194,6 +194,7 @@ These are read by the Harper process at boot (same places as the table above: la
 | 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_EMBED_GPU_LAYERS` | unset (HFE default `0`, CPU only) | Layers to offload to the GPU. **Unset omits the field** so harper-fabric-embeddings keeps its own default of 0. This is a pin for measurement (the ingest-throughput bench, flair#1436), not a new product default — #1437 is the detect-and-default decision. `0` = CPU; `99` = full offload (Metal on mac-arm64). Invalid values fall through to omit. |
 | `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). |
 
@@ -216,6 +217,7 @@ Always backup before upgrades.
 ## Uninstall
 
 ```bash
-flair uninstall   # stops server, removes ~/.flair/, removes launchd/systemd service
+flair uninstall           # stop the server and remove the launchd/systemd service; keep data and keys
+flair uninstall --purge   # also remove ~/.flair (data, keys, secrets), schedulers, and client wiring
 npm uninstall -g @tpsdev-ai/flair
 ```

package/docs/federation.md

@@ -120,6 +120,24 @@ knob. The first sync runs immediately on enable.
 `flair federation watch` is unchanged and still the right tool for an
 interactive "watch it sync while I debug" session.
 
+### Did the canary actually land?
+
+`flair federation verify` writes a tagged memory, **pushes it** (so a
+freshly paired spoke with no sync daemon can still pass), then probes each
+peer. It uses the same couldn't-check-≠-failed split as `flair fleet verify`
+(flair#988 / #823):
+
+| What the probe saw | Verdict | Exit |
+|---|---|---|
+| Canary found | OK | 0 |
+| HTTP 401/403, unreachable, or no endpoint | UNVERIFIABLE (warning) | 0 |
+| Reachable peer answered 200 without the canary after a successful push | FAIL | 1 |
+| Revoked peer | UNVERIFIABLE (warning; not probed) | 0 |
+
+A 401 is "could not authenticate to that peer," not "sync failed." Do not
+treat unverifiable as a pass that hides a reachable peer on the wrong side
+of the canary.
+
 **Credentials.** The scheduler never writes a password into a unit file. It
 stores the *path* given to `--admin-pass-file` (defaulting to
 `~/.flair/admin-pass` when that exists) and the CLI reads the file at run time,
@@ -197,6 +215,7 @@ Records with `updatedAt` more than 5 minutes in the future are rejected. This pr
 | `flair federation sync disable [--remove-shim]` | Remove the scheduled sync driver |
 | `flair federation sync status` | Show whether the driver is installed and genuinely active |
 | `flair federation watch [--interval <s>]` | Run sync in a foreground loop for an interactive session (default 30s) |
+| `flair federation verify [--wait <s>] [--admin-pass <pass>]` | Write a canary, push it, and check each peer. Flag/file admin credentials authenticate the admin-gated peer listing. 401/403, unreachable, and revoked are UNVERIFIABLE (warning, exit 0); a reachable peer missing the canary still FAILs (exit 1). |
 | `flair federation reachability` | Probe local instance + each paired peer (read-only) |
 | `flair federation token [--ttl <min>]` | Generate a one-time pairing token triple (hub only) |
 

package/docs/hosted-on-fabric.md

@@ -155,7 +155,7 @@ flair status --target https://<cluster>.<org>.harperfabric.com
 flair fleet verify --target https://<cluster>.<org>.harperfabric.com
 ```
 
-`fleet verify` checks health, auth, and version across the origin node plus every Flair federation peer on file. Exit codes: 0 = all verified, 1 = origin failed, 2 = peer version skew, 3 = peer unverifiable.
+`fleet verify` checks health, auth, and version across the origin node plus every Flair federation peer on file. Exit codes: 0 = all probed nodes verified (unverifiable peers warn, do not fail), 1 = origin failed, 2 = reachable peer diverged, 3 = reachable peer unreachable/auth-failed.
 
 > **A credential mismatch renders as an empty section.** `flair status` reads `/HealthDetail` with `FLAIR_ADMIN_PASS` / `HDB_ADMIN_PASSWORD` / a pinned agent key — **not** the `FABRIC_*` credentials. On failure it renders blank.
 
@@ -241,9 +241,9 @@ Fabric gives you N regional nodes running one component — **not** N Flair inst
 
 `flair status` reports usage for two directories: no free space, no total, no quota. An instance can hit its quota with nothing saying so. The one indirect signal is a migration halting for space.
 
-### Unbounded npm cache
+### npm cache is ephemeral per deploy
 
-Every deploy runs a server-side `npm install` using the node's default cache. npm never evicts it, so it grows until it fills the quota. There is no cache flag, alternate location, or cleanup option. [flair#886](https://github.com/tpsdev-ai/flair/issues/886).
+`flair deploy` / `flair upgrade --target` run the node's `npm install` against a temporary cache and delete it afterwards, so hub quota no longer grows with every install ([flair#886](https://github.com/tpsdev-ai/flair/issues/886)).
 
 ---
 

package/docs/quickstart.md

@@ -202,7 +202,8 @@ Soul entries and relevant memories, in one block sized to a token budget. Paste
 flair stop              # stop the service, keep data
 flair restart           # restart
 flair uninstall         # remove the service, keep data and keys
-flair uninstall --purge # remove everything, including data and keys
+flair uninstall --purge # remove data, keys, secrets, schedulers, and client wiring
+                        # (the npm package is left; `npm uninstall -g @tpsdev-ai/flair`)
 ```
 
 All reversible. Your memories aren't locked in.

package/docs/releasing.md

@@ -1,13 +1,14 @@
 # Releasing Flair
 
-Flair publishes eight workspace packages to npm under `@tpsdev-ai/*`. Releases are
+Flair publishes nine workspace packages to npm under `@tpsdev-ai/*`. Releases are
 **tokenless** and **staged**: CI authenticates to npm with a short-lived OIDC token
 (no `NPM_TOKEN` lives anywhere) and submits each package to npm's **staging** area.
 A maintainer then approves the staged tarballs on npmjs.com with 2FA to make them live.
 
 > `flair-bench` is version-bumped and tagged in lockstep with the other 7, and stages in
 > its own step in CI for [historical reasons](#flair-bench-bootstrap-one-time-done). That
-> step is no longer allowed to fail: all eight packages must stage for a release to pass.
+> step is no longer allowed to fail: every already-published package must stage
+> for a release to pass.
 
 ```
  merge release PR ──▶ push tag v0.11.0 ──▶ CI stages all packages ──▶ npm staging
@@ -145,11 +146,15 @@ Leave `npm publish` **unchecked** under allowed actions. This structurally preve
 CI/OIDC identity from publishing anything live directly — the only path to live is the
 human 2FA approval of a staged package.
 
-Packages: `flair-client`, `flair-mcp`, `flair`, `openclaw-flair`, `pi-flair`,
-`n8n-nodes-flair`, `langgraph-flair`, `flair-bench`.
+Packages: `flair-client`, `flair-mcp`, `flair`,
+`openclaw-flair`, `pi-flair`, `n8n-nodes-flair`, `langgraph-flair`, `flair-bench`.
 
-> A package must already exist on npm before a trusted publisher can be added — all
-> eight already do. This account-level config can only be done by an npm org owner.
+> `flair-tool-descriptors` is private and never published. Since flair#1683 it is a
+> **build-time source**: `scripts/vendor-tool-descriptors.mjs` copies it into each
+> consumer's own tree at prebuild (`resources/tool-descriptors/` for `flair`,
+> `packages/flair-mcp/src/tool-descriptors/` for `flair-mcp`) and the consumers
+> import it by relative path. Nothing declares or bundles it as a dependency —
+> 0.54.1's `bundleDependencies` broke fresh global installs (flair#1681 → #1683).
 
 ### `flair-bench` bootstrap (one-time, done)
 
@@ -188,6 +193,15 @@ review. Because the release is triggered by a tag push, its deployment policy mu
 **`v*` tags** (Settings → Environments → `release` → Deployment branches and tags →
 Selected branches and tags → add tag rule `v*`).
 
+### Required status checks (ruleset)
+
+Add **`First-publish preflight`** to the main branch ruleset's required status
+checks (repo settings → Rules → main). This is a repo-settings act, not a code
+change: until it is listed, the release-PR job is **advisory only** and a red
+first-publish preflight can be merged past. The tag-triggered
+`release-publish.yml` also runs the same check before staging, so a hazard is
+still stopped on the normal release path either way.
+
 ### Approver 2FA
 
 The maintainer who approves staged packages must have 2FA enabled on their npm account.

package/docs/spoke-bringup.md

@@ -138,8 +138,8 @@ The `--admin-pass` is required so the CLI can write the hub as a local `Peer` re
 
 1. The spoke POSTs a signed pairing request to the hub's `/FederationPair` endpoint.
 2. The bootstrap user authenticates at the Harper platform layer (works on standalone and Fabric deployments alike).
-3. The hub validates the one-time token, verifies the Ed25519 signature, and creates a `Peer` record.
-4. The spoke writes a `Peer` record pointing to the hub so sync knows where to push.
+3. The hub validates the one-time token, verifies the Ed25519 signature, and creates a `Peer` record. The response includes the hub's `instance {id, publicKey}` when the hub has a FederationInstance row.
+4. The spoke writes a `Peer` record pointing to the hub so sync knows where to push. A missing hub `publicKey` is an error, never an empty string. That does not create the hub's Instance row.
 
 ---
 
@@ -156,13 +156,18 @@ Syncing to hub: <hub-instance-id>...
 ✅ Synced 0 records (0 skipped) in 45ms
 ```
 
-Then verify reachability across the federation:
+Then verify the pairing. `federation verify` pushes the canary itself — you
+do not need the systemd timer from §7 first:
 
 ```bash
+flair federation verify --admin-pass "$FLAIR_ADMIN_PASS"
 flair federation reachability
 ```
 
-Both local and hub peer should report `OK`.
+`verify` writes a tagged memory, syncs it, and checks each peer. HTTP 401/403,
+an unreachable peer, or a revoked leftover row is UNVERIFIABLE (a warning),
+not FAIL. A reachable peer that is missing the canary still fails.
+`reachability` should report `OK` for local and the hub.
 
 ---
 
@@ -290,7 +295,7 @@ flair federation pair https://fabric-node.example.com:19926/<instance> \
 | Hub: mint token | `flair federation token --admin-pass <pass> > triple.json` |
 | Spoke: pair | `flair federation pair <hub-url> --token-from ./triple.json --admin-pass <pass>` |
 | Spoke: sync | `flair federation sync --admin-pass <pass>` |
-| Spoke: verify | `flair federation reachability` |
+| Spoke: verify | `flair federation verify --admin-pass <pass>` then `flair federation reachability` |
 | Watch loop | `flair federation watch --interval 30` |
 
 ---

package/docs/standalone-local.md

@@ -57,7 +57,8 @@ flair status        # check everything is working
 flair stop          # stop the service (keeps data)
 flair restart       # restart the service
 flair uninstall     # remove the service (keeps data + keys)
-flair uninstall --purge   # remove everything including data and keys
+flair uninstall --purge   # remove data, keys, secrets, schedulers, and client wiring
+                          # (the npm package is left; `npm uninstall -g @tpsdev-ai/flair`)
 ```
 
 On macOS the service is a launchd plist at `~/Library/LaunchAgents/ai.tpsdev.flair.plist`. On Linux it is a systemd unit at `~/.config/systemd/user/flair.service`. Both auto-start on login/boot and restart on crash.
@@ -108,6 +109,7 @@ logging:
 | `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_EMBED_GPU_LAYERS` | GPU layers to offload. Unset leaves HFE's default of 0 (CPU only) — this is a pin, not a new default. | Only to measure Metal offload (`99`) or pin CPU (`0`). See [deployment.md](deployment.md#performance-related-environment-variables) and #1437. |
 | `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`. |