@tpsdev-ai/flair 0.28.0 → 0.29.0

package/README.md

@@ -67,7 +67,7 @@ If you need any of those specifically, use them. If you need crypto-pinned ident
 
 Anthropic shipped [Claude Dreams](https://platform.claude.com/docs/en/managed-agents/dreams) (research preview, April 2026) — async pipeline that reads a memory store + session transcripts and produces a curated output store: duplicates merged, stale entries replaced, insights surfaced. Validates the category: agent memory accumulates drift and needs cleanup.
 
-Flair ships both the on-demand curation surface (`flair rem rapid`) AND the scheduled nightly cycle, per the [FLAIR-NIGHTLY-REM spec](specs/FLAIR-NIGHTLY-REM.md) and its [in-process distillation slice](specs/FLAIR-NIGHTLY-REM-SLICE-2-DISTILLATION.md). Config recipe (Ollama zero-key default, hosted-provider egress warning, clustered-deploy rules): [`docs/rem.md`](docs/rem.md).
+Flair ships both the on-demand curation surface (`flair rem rapid`) AND the scheduled nightly cycle, per [`docs/rem.md`](docs/rem.md) and its [distillation UX design note](docs/notes/rem-ux.md). **REM requires a configured generative backend** (Ollama, OpenAI, Anthropic, etc.) — without one, `flair rem rapid` fails with `Reflection error: No generative backend configured`. Config recipe (Ollama zero-key default, hosted-provider egress warning, clustered-deploy rules): [`docs/rem.md`](docs/rem.md).
 
 - **`flair rem rapid`** — reflects and distills server-side by default, staging candidates in one bounded call. `--focus {lessons_learned, patterns, decisions, errors}` mirrors Dreams' `instructions` parameter. `--prompt-only` falls back to the bring-your-own-model handoff. Outputs *candidates*, not a wholesale store swap.
 - **`flair rem candidates` / `flair rem promote <id> --rationale "<why>"` / `flair rem reject <id>`** — review and promote distilled candidates with required rationale.

package/dist/bridges/builtins/index.js

@@ -10,7 +10,7 @@
  * To add a new built-in:
  *   - YAML: write `src/bridges/builtins/<name>.ts` exporting a `YamlBridgeDescriptor`
  *   - Code plugin: write `src/bridges/builtins/<name>.ts` exporting a `MemoryBridge`
- *   Then register it here. See specs/FLAIR-BRIDGES.md §2 for shapes A/B.
+ *   Then register it here. See docs/bridges.md § Two shapes for shapes A/B.
  */
 import { agenticStackDescriptor } from "./agentic-stack.js";
 import { claudeProjectMemoryBridge } from "./claude-project.js";

package/dist/bridges/discover.js

@@ -1,6 +1,6 @@
 /**
  * Bridge discovery — scans the four conventional sources defined in
- * FLAIR-BRIDGES.md §7:
+ * docs/bridges.md § Discovery:
  *
  *   1. Project YAML:   <cwd>/.flair-bridge/*.yaml
  *   2. User YAML:      ~/.flair/bridges/*.yaml

package/dist/bridges/runtime/load-plugin.js

@@ -53,7 +53,7 @@ export async function loadCodePlugin(discovered, opts = {}) {
             field: "exports",
             expected: "named `bridge` export or default export implementing MemoryBridge",
             got: typeof mod === "object" && mod !== null ? `exports=${Object.keys(mod).join(",") || "(empty)"}` : typeof mod,
-            hint: `flair-bridge-<name> packages must export \`bridge\` (or default-export) a MemoryBridge. See specs/FLAIR-BRIDGES.md §6`,
+            hint: `flair-bridge-<name> packages must export \`bridge\` (or default-export) a MemoryBridge. See docs/bridges.md § Shape B`,
         });
     }
     // Validate the shape. Keep this minimal — we trust the plugin author

package/dist/bridges/scaffold.js

@@ -1,7 +1,7 @@
 /**
  * Bridge scaffolding — emits a working starter for a new bridge.
  *
- * From FLAIR-BRIDGES.md §2: "Scaffold & test in-tree. `flair bridge
+ * From docs/bridges.md § Two shapes: "Scaffold & test in-tree. `flair bridge
  * scaffold <name>` emits a working starter; `flair bridge test <name>`
  * runs a round-trip diff." This file handles the `scaffold` half.
  *
@@ -34,7 +34,7 @@ function fileDescriptorTemplate(name) {
 # Generated by \`flair bridge scaffold ${name} --file\`.
 # Edit to match your foreign system, then run \`flair bridge test ${name}\`.
 #
-# Spec: see FLAIR-BRIDGES.md §4 (memory schema) and §5 (YAML shape).
+# Spec: see docs/bridges.md § The memory record and § Shape A.
 name: ${name}
 version: 1
 kind: file
@@ -90,7 +90,7 @@ function apiIndexTemplate(name) {
  * flair-bridge-${name}
  *
  * Generated by \`flair bridge scaffold ${name} --api\`.
- * Spec: see FLAIR-BRIDGES.md §4 (memory schema) and §6 (code plugin shape).
+ * Spec: see docs/bridges.md § The memory record and § Shape B.
  *
  * After editing, run:
  *   flair bridge test ${name}

package/dist/bridges/types.js

@@ -1,7 +1,7 @@
 /**
  * Types for the Flair memory bridge plugin system.
  *
- * Mirrors the contract in specs/FLAIR-BRIDGES.md. These types are the
+ * Mirrors the contract in docs/bridges.md. These types are the
  * public surface a bridge author (human or agent) targets.
  *
  * IMPORTANT: the YAML bridge format (shape A) also conforms to these types

package/dist/cli.js

@@ -384,6 +384,33 @@ export function detectOpsApiAllInterfacesBind(portValue) {
     }
     return { allInterfaces: true, boundHost: null };
 }
+/**
+ * Decide the source `flair init` should use for the admin password when no
+ * explicit `--admin-pass` / `--admin-pass-file` / env var was given
+ * (flair#827).
+ *
+ * Before this existed, init ALWAYS generated a fresh random password and
+ * overwrote `~/.flair/admin-pass` on every run — including a re-run against
+ * an install that was already bootstrapped and working (e.g. following
+ * `flair doctor`'s ops-bind finding, whose only prescribed remedy is
+ * re-running `flair init`). Harper's `HDB_ADMIN_PASSWORD` env var only seeds
+ * a brand-new install's user record — it does NOT rotate an existing user's
+ * stored password hash on every boot. So overwriting the file desynced it
+ * from what Harper actually had persisted, and the very next ops-API call in
+ * that SAME init run (seeding the agent) failed with a 401 "Login failed",
+ * breaking working auth on an install that had nothing wrong with its
+ * credentials.
+ *
+ * An admin-pass file that already exists on disk IS the working install's
+ * password — `flair init` is the only thing that ever writes it — so reuse
+ * it instead of generating a new one. That makes re-init idempotent: safe to
+ * run again at any time without risking the instance's auth. Deliberately
+ * rotating the admin password is a separate operation, not a `flair init`
+ * side effect.
+ */
+export function resolveInitAdminPasswordSource(adminPassFileExists) {
+    return adminPassFileExists ? "reuse-existing" : "generate-new";
+}
 // ─── Ops-socket permission posture (flair#763) ─────────────────────────────────
 //
 // The ops API domain socket (dataDir/operations-server) is protected by a
@@ -1846,6 +1873,39 @@ const __pkgVersion = (() => {
         return "unknown";
     }
 })();
+/**
+ * The `@tpsdev-ai/flair-mcp` spec written into a client's MCP config.
+ *
+ * PINNED, deliberately. A bare `npx -y @tpsdev-ai/flair-mcp` re-resolves to
+ * whatever is currently published on EVERY agent session — so a single bad
+ * publish (stolen credentials, a malicious commit that clears review, or a
+ * compromised dependency of the MCP package) reaches every wired user
+ * silently, with no lockfile and no review step in the path. The postmark-mcp
+ * incident was exactly this shape: a legitimate publish by the legitimate
+ * owner, propagating for 16 days before anyone noticed. Worse, a yank does
+ * not help — unpinned clients keep resolving latest.
+ *
+ * Our publish side is already hardened (OIDC staged publish, human 2FA at the
+ * release gate), but that defends against credential theft, not against a bad
+ * version being published legitimately. The consumer side is where that gap
+ * closes, and pinning is what closes it: a wired client keeps running the
+ * exact version that was current when it was wired, and moving forward
+ * becomes a deliberate act.
+ *
+ * flair and flair-mcp ship in version lockstep from this monorepo, so the
+ * running CLI's own version is the correct pin. `flair init` re-run rewires
+ * to the then-current version; see the upgrade-rewire follow-up issue for
+ * making `flair upgrade` do the same.
+ *
+ * Falls back to the unpinned spec only when the version can't be read, which
+ * is the same condition under which `--version` reports "unknown" — a broken
+ * install, where a working MCP wiring matters more than a precise pin.
+ */
+export function mcpServerSpec(version = __pkgVersion) {
+    return version && version !== "unknown"
+        ? `@tpsdev-ai/flair-mcp@${version}`
+        : "@tpsdev-ai/flair-mcp";
+}
 const program = new Command();
 program.name("flair").version(__pkgVersion, "-v, --version");
 // ─── CLI↔server version handshake (flair#695 §B) ────────────────────────────
@@ -2117,9 +2177,10 @@ program
         selectedClients.push(clientOpt);
     }
     // Admin password: determine from opts, env, or generate
-    // Priority: 1) --admin-pass-file, 2) env vars, 3) generate new
+    // Priority: 1) --admin-pass-file, 2) env vars, 3) reuse existing file, 4) generate new
     let adminPass;
     let passwordSource = "generated";
+    let reusedExistingAdminPass = false;
     // Warn if --admin-pass is passed inline (not from env)
     if (shouldShowInlineSecretWarning(opts.adminPass, false, new Set(["--admin-pass"]), "--admin-pass")) {
         console.error("warning: --admin-pass passed inline. Consider --admin-pass-file <path> or FLAIR_ADMIN_PASS env " +
@@ -2151,34 +2212,65 @@ program
         passwordSource = "env"; // Treat same as env for display purposes
     }
     else {
-        // Generate new password and write to file atomically
-        adminPass = Buffer.from(nacl.randomBytes(18)).toString("base64url");
-        passwordSource = "generated";
-        // Atomic write: create temp file in same dir, then rename
         const flairDir = join(homedir(), ".flair");
-        mkdirSync(flairDir, { recursive: true });
         const adminPassPath = join(flairDir, "admin-pass");
-        const tempPath = mkdtempSync(join(flairDir, ".admin-pass.tmp-"));
-        const finalTempPath = join(tempPath, "admin-pass");
-        try {
-            writeFileSync(finalTempPath, adminPass + "\n", { mode: 0o600 });
-            renameSync(finalTempPath, adminPassPath);
-            rmSync(tempPath, { recursive: true, force: true });
+        passwordSource = "generated";
+        if (resolveInitAdminPasswordSource(existsSync(adminPassPath)) === "reuse-existing") {
+            // flair#827: an admin-pass file already on disk means a PRIOR `flair
+            // init` already bootstrapped Harper's admin user with this password.
+            // HDB_ADMIN_PASSWORD only seeds a brand-new install — Harper does
+            // NOT rotate an existing user's stored password hash from env on
+            // every boot. Generating and overwriting the file here would desync
+            // it from what Harper actually has persisted, breaking ops-API auth
+            // (401 "Login failed") on THIS SAME init run (the agent-seeding call
+            // below) without fixing whatever the re-run was meant to fix — e.g.
+            // `flair doctor`'s ops-bind finding, whose only prescribed remedy is
+            // re-running `flair init`. Re-init must be idempotent here: reuse
+            // the existing password so it's always safe to re-run against a
+            // working install. Rotating the admin password on purpose is a
+            // separate, deliberate operation (see the ops runbook), not a side
+            // effect of re-init.
+            try {
+                adminPass = readAdminPassFileSecure(adminPassPath);
+            }
+            catch (err) {
+                console.error(`Error: ${err.message}`);
+                process.exit(1);
+            }
+            reusedExistingAdminPass = true;
         }
-        catch (err) {
-            // Clean up temp dir on failure
+        else {
+            // Generate new password and write to file atomically
+            adminPass = Buffer.from(nacl.randomBytes(18)).toString("base64url");
+            // Atomic write: create temp file in same dir, then rename
+            mkdirSync(flairDir, { recursive: true });
+            const tempPath = mkdtempSync(join(flairDir, ".admin-pass.tmp-"));
+            const finalTempPath = join(tempPath, "admin-pass");
             try {
+                writeFileSync(finalTempPath, adminPass + "\n", { mode: 0o600 });
+                renameSync(finalTempPath, adminPassPath);
                 rmSync(tempPath, { recursive: true, force: true });
             }
-            catch { }
-            throw err;
+            catch (err) {
+                // Clean up temp dir on failure
+                try {
+                    rmSync(tempPath, { recursive: true, force: true });
+                }
+                catch { }
+                throw err;
+            }
         }
     }
     const adminUser = DEFAULT_ADMIN_USER;
-    // If we generated the password, report where it was saved
+    // If we generated (or reused) the password, report where it lives
     if (passwordSource === "generated") {
         const adminPassPath = join(homedir(), ".flair", "admin-pass");
-        console.log(`Admin password saved to: ${adminPassPath}`);
+        if (reusedExistingAdminPass) {
+            console.log(`Reusing existing admin password from: ${adminPassPath} (flair#827: re-init never rotates it — see the ops runbook to change it deliberately)`);
+        }
+        else {
+            console.log(`Admin password saved to: ${adminPassPath}`);
+        }
     }
     // Check Node.js version
     const major = parseInt(process.version.slice(1), 10);
@@ -2515,7 +2607,8 @@ program
         }
         // ── MCP client wiring ────────────────────────────────────────────────
         // The full one-command front door: detect installed MCP clients and wire
-        // each to the zero-install `npx -y @tpsdev-ai/flair-mcp` server. Claude
+        // each to the zero-install `npx -y @tpsdev-ai/flair-mcp@<version>` server
+        // (pinned — see mcpServerSpec()). Claude
         // Code is auto-wired into ~/.claude.json (the only client the CLI can
         // safely modify); other clients get copy-paste snippets. `--no-mcp`
         // skips wiring entirely; `--client <name>` targets one client; the
@@ -2551,7 +2644,7 @@ program
                     const flairMcpConfig = {
                         type: "stdio",
                         command: "npx",
-                        args: ["-y", "@tpsdev-ai/flair-mcp"],
+                        args: ["-y", mcpServerSpec()],
                         // flair#718 authorship-provenance: each client's wired env block
                         // gets its OWN FLAIR_CLIENT label (never the shared mcpEnv
                         // object directly — that would stamp the same label into every
@@ -2640,7 +2733,9 @@ program
         if (!opts.skipSmoke && !noMcp && clientOpt !== "none" && wiringResults.length > 0) {
             console.log("\n   Smoke-testing MCP server...");
             try {
-                const mcpProc = spawn("npx", ["-y", "@tpsdev-ai/flair-mcp"], {
+                // Same spec that gets WIRED above — the smoke test must exercise the
+                // exact version the user will run, not whatever npm resolves latest to.
+                const mcpProc = spawn("npx", ["-y", mcpServerSpec()], {
                     env: { ...process.env, FLAIR_AGENT_ID: agentId, FLAIR_URL: httpUrl },
                     stdio: ["pipe", "pipe", "pipe"],
                 });
@@ -5863,8 +5958,7 @@ export function describeReflectError(message) {
     return { kind: "other", text: message };
 }
 // ─── flair rem rapid ──────────────────────────────────────────────────────────
-// Executes by default (specs/FLAIR-NIGHTLY-REM-SLICE-2-DISTILLATION.md § 3C,
-// issue #707): distills server-side via /ReflectMemories execute:true and
+// Executes by default (§3C, issue #707): distills server-side via /ReflectMemories execute:true and
 // stages MemoryCandidate rows, printing a staged-candidate summary. --prompt-only
 // preserves the pre-#710 handoff behavior byte-for-byte, for the bring-your-
 // own-model workflow.
@@ -9707,7 +9801,13 @@ program
     // 3b. Ops API bind (flair#670) — report-only finding, never auto-fixed.
     // Rebinding the ops API requires a Harper restart to take effect, so
     // `doctor --fix` deliberately does not touch it here; the fix is
-    // `flair init` (re-run) or a manual harper-config.yaml edit + restart.
+    // `flair init` (re-run, then `flair restart` to apply it) or a manual
+    // harper-config.yaml edit + restart. flair#827: re-running `flair init`
+    // used to regenerate ~/.flair/admin-pass unconditionally, desyncing it
+    // from Harper's already-persisted credential and breaking admin auth on
+    // the very re-run this remedy prescribed — resolveInitAdminPasswordSource
+    // (see its doc comment) now reuses the existing password instead, so this
+    // remedy is safe to follow on a working install.
     try {
         const harperConfigPath = join(defaultDataDir(), "harper-config.yaml");
         if (existsSync(harperConfigPath)) {
@@ -9716,7 +9816,7 @@ program
             const bind = detectOpsApiAllInterfacesBind(opsPortValue);
             if (bind.allInterfaces) {
                 console.log(`  ${render.icons.error} Ops API bound to ${render.wrap(render.c.bold, "all interfaces")} (${render.wrap(render.c.dim, String(opsPortValue))})`);
-                console.log(`     ${render.wrap(render.c.dim, "Single-host installs don't need this reachable off-box. Fix:")} flair init ${render.wrap(render.c.dim, "(rebinds to loopback + domain socket on next start; pass --ops-bind for deliberate remote admin)")}`);
+                console.log(`     ${render.wrap(render.c.dim, "Single-host installs don't need this reachable off-box. Fix:")} flair init && flair restart ${render.wrap(render.c.dim, "(rebinds to loopback + domain socket; re-init reuses your existing admin password, so this is safe on a running install — pass --ops-bind for deliberate remote admin)")}`);
                 issues++;
             }
         }
@@ -12082,7 +12182,7 @@ soul.command("list")
 // Slice 1: discovery + scaffold. Slice 2: YAML runtime + `import` for Shape A
 // + agentic-stack reference adapter as a built-in.
 // `test` and `export` are still stubbed; Shape B (npm code plugins) too.
-// See specs/FLAIR-BRIDGES.md.
+// See docs/bridges.md.
 const bridge = program.command("bridge").description("Manage memory bridges (import/export between Flair and foreign systems)");
 bridge
     .command("list")

package/dist/rem/runner.js

@@ -20,8 +20,8 @@
  *   - Steps 1, 2 shipped in slice-1 PR-1 (#414).
  *   - Step 3 (maintenance) shipped in a prior slice-2 PR — fills
  *     `archived`/`expired` in the audit row.
- *   - Step 4: per specs/FLAIR-NIGHTLY-REM-SLICE-2-DISTILLATION.md § 3B,
- *     "Deferred from parent § 4 step 4" — trust tiers aren't derivable yet
+ *   - Step 4: per §3B (issue #707), "Deferred from parent § 4 step 4" —
+ *     trust tiers aren't derivable yet
  *     (that's the emergent-trust arc). The input filter stays as today (own
  *     agent, non-archived, non-permanent, scope window); the safety net for
  *     un-tiered input is structural — candidates are staged, never

package/dist/resources/MemoryReflect.js

@@ -5,7 +5,7 @@
  * reflection prompt for a human/agent to run through their own LLM, or (b)
  * with execute:true, runs the distillation server-side via Harper's models
  * facade and stages the results as MemoryCandidate rows for review. See
- * specs/FLAIR-NIGHTLY-REM-SLICE-2-DISTILLATION.md §3A (issue #707).
+ * issue #707 (§3A).
  *
  * Request:
  *   agentId      string   — which agent to reflect on

package/dist/resources/RecordUsage.js

@@ -34,6 +34,17 @@
  * (and its ownership gate) — its own auth model is verified-agent +
  * within-org + explicitly NO ownership requirement.
  *
+ * NO READ-SCOPE GATE — INTENTIONAL ASYMMETRY with citation-on-write
+ * (flair#775): this endpoint deliberately does NOT validate reported ids
+ * against the caller's read scope. Usage feedback is the cross-agent
+ * contract described above (agent B reports using agent A's memory
+ * regardless of A's visibility setting), and the no-enumeration response
+ * below already denies existence probing on this surface. Citation-on-write
+ * (./usage-recording.ts's recordCitations()) DOES scope-gate each cited id —
+ * it is a separate write surface with a narrower threat model; see that
+ * module's doc. Do not "unify" the two: the difference is a K&S binding
+ * condition on the flair#775 locked design, not drift.
+ *
  * WHY THIS ISN'T A @table-BACKED RESOURCE: the actual dedup ledger (one row
  * per (agentId, memoryId) contribution) lives in the `MemoryUsage` table
  * (schemas/memory.graphql), guarded by resources/MemoryUsage.ts. But this
@@ -164,7 +175,10 @@ export class RecordUsage extends Resource {
                 // ./usage-recording.ts's recordUsageContribution() — a shared,
                 // single-implementation extraction (also used by citation-on-write,
                 // resources/Memory.ts's post()/put()). Byte-identical behavior to
-                // the former private _recordOne() this replaced.
+                // the former private _recordOne() this replaced. Deliberately NO
+                // read-scope check on memoryId here (flair#775 asymmetry — see the
+                // module doc's NO READ-SCOPE GATE paragraph; citation-on-write's
+                // recordCitations() is the surface that scope-gates).
                 await recordUsageContribution(ctx, agentId, memoryId, attribution, now);
             }
             catch (err) {

package/dist/resources/embeddings-provider.js

@@ -107,9 +107,6 @@
  * still a separate, deliberate step from shipping this code — see the PR
  * description for that distinction.
  */
-import { join } from "node:path";
-import { existsSync } from "node:fs";
-import { homedir } from "node:os";
 const VALID_INPUT_TYPES = new Set(["document", "query"]);
 /**
  * THE GATE (flair#504 Phase 2 — flipped ON). A module-level constant, not an
@@ -239,42 +236,15 @@ async function getModelsApi() {
 /**
  * Resolve the directory the embeddings model lives in / downloads into.
  *
- * Resolution order (everything writable, never the read-only package dir):
- *   1. FLAIR_MODELS_DIR        — explicit operator/docker override.
- *   2. <ROOTPATH>/models       — Harper's data dir (Flair passes ROOTPATH =
- *                                ~/.flair/data when it spawns Harper). User-
- *                                owned and writable even on sudo-global installs.
- *   3. <cwd>/models            — ONLY if a model already lives there. Backward
- *                                compat for existing writable installs that
- *                                downloaded into the package dir before this fix;
- *                                never used as a download target on fresh installs.
- *   4. ~/.flair/data/models    — last-resort default when ROOTPATH is unset.
- *
- * The chosen dir is always writable, so the embeddings engine can download the
- * model on first use without hitting EACCES on a root-owned package dir.
- *
- * Called by `resources/embeddings-boot.ts` (flair#694) to build the
- * `modelsDir` it passes to harper-fabric-embeddings' `register()` — both run
- * in the SAME process now (unlike the retired src/cli.ts-side computation,
- * which duplicated this exact default because it ran in a separate process
- * that set the resulting value via an env var). Still exported and tested
- * independently (test/unit/embeddings-models-dir.test.ts) as the single
- * documented source of truth for this default.
+ * Implementation moved to `resources/models-dir.ts` (flair#815) so the
+ * reranker can share the exact same resolution without importing this module
+ * (several unit-isolated tests `mock.module()` this file wholesale — see
+ * models-dir.ts's header). Re-exported here so existing consumers keep their
+ * import site: `resources/embeddings-boot.ts` (flair#694), which builds the
+ * `modelsDir` it passes to harper-fabric-embeddings' `register()`, and
+ * test/unit/embeddings-models-dir.test.ts, which pins the resolution order.
  */
-export function resolveModelsDir() {
-    const override = process.env.FLAIR_MODELS_DIR;
-    if (override)
-        return override;
-    const rootPath = process.env.ROOTPATH;
-    if (rootPath)
-        return join(rootPath, "models");
-    // Backward compat: a prior (writable) install may have the model cached in
-    // the package dir. Reuse it rather than re-downloading — but only if present.
-    const cwdModels = join(process.cwd(), "models");
-    if (existsSync(cwdModels))
-        return cwdModels;
-    return join(homedir(), ".flair", "data", "models");
-}
+export { resolveModelsDir } from "./models-dir.js";
 // Kern: "Boot probe MUST have a 5-10s timeout ... on timeout set mode='none'
 // + log a warning. A hung probe ... must never block Harper boot."
 const PROBE_TIMEOUT_MS = 8_000;

package/dist/resources/mcp-tools.js

@@ -35,6 +35,7 @@
  * version bump + a new FlairClient method, out of scope for this query-only
  * slice.
  */
+import { resolveVersion } from "./version.js";
 const H = {};
 const LOADERS = {
     SemanticSearch: async () => (await import("./SemanticSearch.js")).SemanticSearch,
@@ -248,7 +249,14 @@ async function bootstrap(agent, args) {
     // ONLY when requested so a plain bootstrap delegates a byte-identical body.
     if (args?.abstain === true)
         body.abstain = true;
-    return unwrap(await h.post(body));
+    // flair#831 — attach the running Flair version to the RESPONSE (not the
+    // delegated request body) so the calling agent learns the server version
+    // on its very first call.
+    const result = unwrap(await h.post(body));
+    if (result && typeof result === "object" && !Array.isArray(result)) {
+        return { ...result, flairVersion: resolveVersion() };
+    }
+    return result;
 }
 async function soulSet(agent, args) {
     const Cls = await handler("Soul");

package/dist/resources/memory-reflect-lib.js

@@ -1,6 +1,6 @@
 // ─── Memory Reflection — pure logic for /ReflectMemories ────────────────────
 // Pure helpers backing resources/MemoryReflect.ts (FLAIR-NIGHTLY-REM slice 2,
-// §3A — see specs/FLAIR-NIGHTLY-REM-SLICE-2-DISTILLATION.md, issue #707).
+// §3A — see issue #707).
 //
 // Same split as resources/memory-consolidate-lib.ts: importing MemoryReflect.ts
 // pulls in the Harper runtime (`databases`/`Resource`/`models`, storage init),

package/dist/resources/models-dir.js

@@ -0,0 +1,55 @@
+/**
+ * models-dir.ts — the ONE place that decides where model GGUFs live.
+ *
+ * Extracted from embeddings-provider.ts (flair#815) so the reranker
+ * (rerank-provider.ts) can share the exact same resolution WITHOUT importing
+ * embeddings-provider: several unit-isolated tests `mock.module()` the whole
+ * embeddings-provider module (with only the named exports THEY consume), and
+ * bun's module cache is process-wide — so any new cross-module import of
+ * embeddings-provider from another resource makes those mocks incomplete and
+ * kills unrelated test files at module load. This module is tiny, pure
+ * node-stdlib, and never mocked, so both providers (and any future model
+ * consumer) can depend on it safely.
+ */
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * Resolve the directory model GGUFs live in / download into — shared by the
+ * embedding engine (embeddings-boot.ts's `register()` options) and the
+ * cross-encoder reranker (rerank-provider.ts, flair#815 — it used to hardcode
+ * `<cwd>/models`, silently failing open wherever Harper's cwd wasn't the
+ * models location).
+ *
+ * Resolution order (everything writable, never the read-only package dir):
+ *   1. FLAIR_MODELS_DIR        — explicit operator/docker override.
+ *   2. <ROOTPATH>/models       — Harper's data dir (Flair passes ROOTPATH =
+ *                                ~/.flair/data when it spawns Harper). User-
+ *                                owned and writable even on sudo-global installs.
+ *   3. <cwd>/models            — ONLY if a model already lives there. Backward
+ *                                compat for existing writable installs that
+ *                                downloaded into the package dir before this fix;
+ *                                never used as a download target on fresh installs.
+ *   4. ~/.flair/data/models    — last-resort default when ROOTPATH is unset.
+ *
+ * The chosen dir is always writable, so the embeddings engine can download the
+ * model on first use without hitting EACCES on a root-owned package dir.
+ *
+ * Tested independently (test/unit/embeddings-models-dir.test.ts, via
+ * embeddings-provider's re-export) as the single documented source of truth
+ * for this default.
+ */
+export function resolveModelsDir() {
+    const override = process.env.FLAIR_MODELS_DIR;
+    if (override)
+        return override;
+    const rootPath = process.env.ROOTPATH;
+    if (rootPath)
+        return join(rootPath, "models");
+    // Backward compat: a prior (writable) install may have the model cached in
+    // the package dir. Reuse it rather than re-downloading — but only if present.
+    const cwdModels = join(process.cwd(), "models");
+    if (existsSync(cwdModels))
+        return cwdModels;
+    return join(homedir(), ".flair", "data", "models");
+}

package/dist/resources/record-types.js

@@ -127,8 +127,8 @@
  *
  * `remEligible` — MUST be `false` for every entry in v1 (typed as the
  * literal `false`, not `boolean`, so a stray `true` is a compile error, not
- * just a runtime policy mistake). REM's nightly gather step
- * (specs/FLAIR-NIGHTLY-REM.md §11) is hardcoded to `GET /Memory?agentId=…`
+ * just a runtime policy mistake). REM's nightly gather step (see docs/rem.md)
+ * is hardcoded to `GET /Memory?agentId=…`
  * — single table, single agent, by construction. There is no multi-table
  * distillation input path to opt into yet; the field exists so a future
  * REM generalization doesn't require a breaking schema change to every

package/dist/resources/rerank-provider.js

@@ -70,10 +70,16 @@
  * No Ollama (no logprobs, no rerank endpoint — verified), no network hop, no
  * new auth boundary.
  *
- * GGUF files are NOT committed; they are provisioned into models/ alongside the
- * embedding GGUF. See docs/rerank-provisioning.md for download sources.
+ * GGUF files are NOT committed; they are provisioned into the models dir
+ * alongside the embedding GGUF — resolved via the SAME `resolveModelsDir()`
+ * the embedding engine uses (FLAIR_MODELS_DIR → <ROOTPATH>/models →
+ * <cwd>/models → ~/.flair/data/models; flair#815 — this file used to hardcode
+ * <cwd>/models, so any deployment whose cwd wasn't the models location failed
+ * init and silently fell open to vector order). See docs/rerank-provisioning.md
+ * for download sources.
  */
 import { join } from "node:path";
+import { resolveModelsDir } from "./models-dir.js";
 // Known reranker models → GGUF filename + inference mode. jina is the DEFAULT
 // (working — see file header, flair#811): its rank-pooling path completes
 // inside Harper. qwen3 is EXPERIMENTAL: its generative path is validated
@@ -181,6 +187,20 @@ function resolveModelKey() {
         return requested;
     return DEFAULT_MODEL;
 }
+/**
+ * Absolute path the reranker GGUF is expected at: `<models dir>/<file>`,
+ * where the models dir is the shared `resolveModelsDir()` (models-dir.ts,
+ * same resolution the embedding engine uses) — the single documented source
+ * of truth (FLAIR_MODELS_DIR override, ROOTPATH/models, cwd/models backward
+ * compat, ~/.flair/data/models default).
+ * flair#815: this used to be a hardcoded `<cwd>/models/<file>`, which broke
+ * (fail-open, silently) in any deployment where Harper's cwd wasn't the
+ * models location — including the recall harness's ephemeral Harpers.
+ * Exported for unit testing (see test/unit/rerank-provider.test.ts).
+ */
+export function resolveRerankModelPath(file) {
+    return join(resolveModelsDir(), file);
+}
 /**
  * Decide whether `ensureInit()` needs to (re)run the engine init sequence —
  * the flair#811 point-3 fix. Pure so the decision matrix is directly
@@ -234,9 +254,9 @@ async function ensureInit() {
         const spec = MODELS[_modelKey];
         _mode = spec.mode;
         const { existsSync } = await import("node:fs");
-        const modelPath = join(process.cwd(), "models", spec.file);
+        const modelPath = resolveRerankModelPath(spec.file);
         if (!existsSync(modelPath)) {
-            throw new Error(`reranker GGUF not found: models/${spec.file} (provision per docs/rerank-provisioning.md)`);
+            throw new Error(`reranker GGUF not found: ${modelPath} (provision per docs/rerank-provisioning.md; set FLAIR_MODELS_DIR to override the models dir)`);
         }
         // Dynamic import — deferred to avoid Harper 5.x VM linker race (same reason
         // embeddings-provider.ts defers harper-fabric-embeddings).

package/dist/resources/usage-recording.js

@@ -26,10 +26,28 @@
  * RecordUsage.post()'s loop, parameterized so Memory.ts can drive it from a
  * write body instead of a dedicated POST body. It NEVER reads the ledger for
  * authority — it only writes contributions; `usedMemoryIds` must never enter
- * an access/scope/attribution/dedup decision (flair#744 slice A invariant 3).
+ * an access/scope/attribution/dedup decision (flair#744 slice A invariant 3;
+ * the flair#775 read-scope gate below is the REVERSE direction — the writer's
+ * scope vets the cited ids, the cited ids never widen anything).
+ *
+ * recordCitations() additionally validates each cited id against the
+ * WRITER's own read-scope before crediting (flair#775, a Kern+Sherlock
+ * binding condition on the locked design): citing a memory the writer cannot
+ * read is silently dropped, uniformly with a nonexistent id — never an
+ * error, never a distinguishable code path (an error, or any response/shape
+ * difference, would leak "that id exists but you can't see it").
+ * POST /RecordUsage is DELIBERATELY not scope-gated — its module doc
+ * establishes usage feedback as a cross-agent contract (agent B reports
+ * using agent A's memory regardless of A's visibility setting);
+ * citation-on-write is a separate write surface with a narrower threat
+ * model (the ids ride along on the WRITER's own memory-creation call, so
+ * crediting an unreadable id would let a writer both probe for and boost
+ * memories it cannot see). So the scope gate lives HERE, not retrofitted
+ * onto recordUsageContribution() — do not "unify" the two surfaces.
  */
 import { databases } from "@harperfast/harper";
 import { withDetachedTxn } from "./table-helpers.js";
+import { resolveReadScope } from "./memory-read-scope.js";
 /**
  * Per-call cap on ids credited in one batch — shared by RecordUsage.post()'s
  * validated `memoryIds` body (rejects a batch over the cap with a 400) and
@@ -106,6 +124,17 @@ export async function recordUsageContribution(ctx, agentId, memoryId, attributio
         return; // deleted between the checks above and now — no-op
     await withDetachedTxn(ctx, () => databases.flair.Memory.put({ ...fresh, usageCount: (fresh.usageCount ?? 0) + 1 }));
 }
+/**
+ * Default record fetch for recordCitations()'s read-scope gate — the RAW
+ * Memory table (bypassing the Memory RESOURCE class's own read wrapper; the
+ * same trusted-internal-caller pattern recordUsageContribution() uses) so
+ * `scope.isAllowed` runs against the raw stored record. Never throws: a
+ * fetch failure reads as "not found", which the gate silently drops —
+ * identical to a nonexistent id.
+ */
+async function fetchMemoryForScopeCheck(ctx, memoryId) {
+    return withDetachedTxn(ctx, () => databases.flair.Memory.get(memoryId)).catch(() => null);
+}
 /**
  * Batch citation helper — credits every id in `usedMemoryIds` through
  * `recordFn` (the real `recordUsageContribution` by default), one contribution
@@ -129,16 +158,30 @@ export async function recordUsageContribution(ctx, agentId, memoryId, attributio
  *     validated request body, so an oversized list is trimmed rather than
  *     rejected (unlike RecordUsage.post()'s validated `memoryIds`, which
  *     400s over the same cap).
+ *   - Each cited id is validated against the WRITER's read scope before it
+ *     is credited (flair#775 slice 1, K&S binding condition — see the module
+ *     doc above): the scope is resolved ONCE per batch via resolveReadScope
+ *     (the same single source every cross-agent Memory read path uses), then
+ *     each id gets one raw fetch + one in-process `scope.isAllowed` check.
+ *     Not-found and out-of-scope take the SAME silent-drop branch — there is
+ *     no structurally distinguishable code path, error, or response
+ *     difference between them that a caller could use to probe whether
+ *     another agent's private id exists.
  *   - Each id is credited independently: one id throwing never stops the
  *     rest, and the failure is logged server-side, never surfaced to the
  *     caller (the write already committed by the time this runs).
  *
- * `agentId` passed to `recordFn` is ALWAYS `auth.agentId` — the resolved
- * auth context, never anything derived from `usedMemoryIds` or any other
- * caller-supplied input (flair#744 slice A invariant 4: no forging on
- * behalf of another identity).
+ * `agentId` passed to `recordFn` (and to the scope resolution) is ALWAYS
+ * `auth.agentId` — the resolved auth context, never anything derived from
+ * `usedMemoryIds` or any other caller-supplied input (flair#744 slice A
+ * invariant 4: no forging on behalf of another identity).
+ *
+ * `recordFn` / `fetchFn` / `scopeFn` are unit-test injection seams
+ * (test/unit/usage-recording.test.ts) — production callers pass none of
+ * them and always get the real recordUsageContribution / raw-table fetch /
+ * resolveReadScope.
  */
-export async function recordCitations(ctx, auth, usedMemoryIds, now, recordFn = recordUsageContribution) {
+export async function recordCitations(ctx, auth, usedMemoryIds, now, recordFn = recordUsageContribution, fetchFn = fetchMemoryForScopeCheck, scopeFn = resolveReadScope) {
     if (auth.kind !== "agent")
         return;
     if (!Array.isArray(usedMemoryIds) ||
@@ -147,8 +190,31 @@ export async function recordCitations(ctx, auth, usedMemoryIds, now, recordFn =
         return;
     }
     const ids = [...new Set(usedMemoryIds)].slice(0, MAX_USAGE_IDS_PER_CALL);
+    // Resolve the WRITER's read scope ONCE per batch. Fail CLOSED: if scope
+    // resolution itself fails, drop the whole batch rather than credit
+    // unvetted ids — citations are advisory signal, so losing a batch is
+    // strictly safer than crediting an id the writer may not be able to read.
+    let scope;
+    try {
+        scope = await scopeFn(auth.agentId);
+    }
+    catch (err) {
+        console.error("recordCitations: read-scope resolution failed — batch dropped (no-op)", { err });
+        return;
+    }
     for (const id of ids) {
         try {
+            // flair#775 slice 1 read-scope gate. The raw fetch + in-process
+            // predicate is deliberately ONE branch for both "doesn't exist" and
+            // "exists but out of the writer's read scope" — uniform silent drop
+            // (see the module doc). recordUsageContribution's own existence
+            // re-check makes this a second point-lookup of the same record;
+            // accepted — keeping the shared ledger core byte-identical for
+            // RecordUsage.post() is worth two point-lookups on a ≤20-id advisory
+            // batch.
+            const record = await fetchFn(ctx, id);
+            if (!record || !scope.isAllowed(record))
+                continue;
             await recordFn(ctx, auth.agentId, id, undefined, now);
         }
         catch (err) {

package/dist/resources/version.js

@@ -0,0 +1,33 @@
+/**
+ * version.ts — shared runtime-version resolver.
+ *
+ * Reads the running @tpsdev-ai/flair version from the bundled package.json.
+ * `process.env.npm_package_version` is only populated inside `npm run`, so
+ * reading package.json relative to THIS running module is the only way to
+ * report the version of the code that's actually executing.
+ *
+ * Extracted from the duplicated copies in resources/Presence.ts and
+ * resources/AdminInstance.ts (flair#831). Those modules still carry their
+ * own copies for now — migrating them is a follow-up.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+export function resolveVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const candidates = [
+            join(here, "..", "..", "package.json"),
+            join(here, "..", "package.json"),
+        ];
+        for (const p of candidates) {
+            if (existsSync(p)) {
+                const pkg = JSON.parse(readFileSync(p, "utf-8"));
+                if (pkg.version)
+                    return pkg.version;
+            }
+        }
+    }
+    catch { /* fall through */ }
+    return process.env.npm_package_version ?? "dev";
+}

package/docs/assets/flair-cross-orchestrator.cast

@@ -3,7 +3,7 @@
 [0.001, "o", "  Flair  \u00b7  same identity, every orchestrator\r\n  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n\r\n"]
 [1.3, "o", "$ # One agent identity. One memory store. Three orchestrators.\r\n"]
 [1.2, "o", "$ flair init --client all --agent flint\r\n"]
-[0.5, "o", "  \u001b[32m\u2713\u001b[0m Claude Code   wired (~/.claude/mcp.json)\r\n"]
+[0.5, "o", "  \u001b[32m\u2713\u001b[0m Claude Code   wired (~/.claude.json)\r\n"]
 [0.18, "o", "  \u001b[32m\u2713\u001b[0m Codex CLI     wired (~/.codex/config.toml)\r\n"]
 [0.18, "o", "  \u001b[32m\u2713\u001b[0m Gemini CLI    wired (~/.gemini/settings.json)\r\n\r\n"]
 [1.0, "o", "  Each MCP client now connects to:  http://127.0.0.1:9926\r\n"]

package/docs/bridges.md

@@ -101,7 +101,7 @@ A few things worth knowing:
 - **`--agent` is required** unless your descriptor maps an `agentId` column. If you forget, `flair bridge import` errors with a one-line operator-pointer hint plus a structured `BridgeRuntimeError` JSON on stderr.
 - **`--dry-run` is your friend.** Validates the descriptor, parses every record, applies the mapping, but skips the PUT. Use it to confirm the count and check a few records before committing.
 - **Output is throttled** to one progress line every 2 seconds (or every 25 records, whichever comes first), so big imports don't flood your terminal.
-- **Errors are structured.** Every error includes `bridge`, `op`, `path`, `record`, `field`, `expected`, `got`, `hint` (per [§10 of the spec](../specs/FLAIR-BRIDGES.md#-10-error-format)). The `hint` is the part you act on; the rest is for an LLM to self-correct without operator help.
+- **Errors are structured.** Every error includes `bridge`, `op`, `path`, `record`, `field`, `expected`, `got`, `hint` (per [Error format](#error-format) below). The `hint` is the part you act on; the rest is for an LLM to self-correct without operator help.
 
 ## Shape A — Declarative YAML
 
@@ -286,6 +286,6 @@ If you want an agent to write a bridge for you, here's the one-shot prompt:
 
 That's the bar. If an agent can't ship a working bridge from this doc plus the scaffold, the doc is the bug.
 
-## Full spec
+## Authority
 
-The authoritative contract is in [`specs/FLAIR-BRIDGES.md`](../specs/FLAIR-BRIDGES.md). This doc is the user-facing view; the spec covers edge cases, future extensions, and design rationale.
+This document is the authoritative contract for the bridge plugin system: the record schema, both plugin shapes, discovery, distribution, trust, round-trip testing, and the error format are all specified above. There is no separate design spec — the original planning document was retired once the system shipped, and its design-rationale and milestone-scoping sections are preserved in git history rather than maintained here.

package/docs/mcp-clients.md

@@ -38,9 +38,11 @@ Flair runs as a local server at `http://127.0.0.1:19926` by default. The MCP ser
 
 Pick whichever you use. The MCP server is the same package; only the config syntax differs.
 
+> **Pin the version.** The snippets below use the bare package name for readability. `flair init` wires clients to a **pinned** spec (`@tpsdev-ai/flair-mcp@<version>`) on purpose: an unpinned reference re-resolves to whatever is currently published on every agent session, so any future publish reaches your machine silently. If you wire by hand, append the version you intend to run — `@tpsdev-ai/flair-mcp@0.28.0` — and bump it deliberately. `flair init` is the easier path and does this for you.
+
 ### Claude Code
 
-The canonical approach is the `claude mcp add` CLI (writes to `~/.claude/mcp.json`):
+The canonical approach is the `claude mcp add` CLI (writes to `~/.claude.json`):
 
 ```bash
 claude mcp add flair --scope user \

package/docs/n8n.md

@@ -93,7 +93,7 @@ If any of those don't hold, use Flair's CLI / SDK clients (which support per-age
 
 ## Get By Tag — coming soon
 
-The Flair Search node currently exposes Semantic Search and Get By Subject. **Get By Tag** is deferred until `flair-client.memory.list` exposes a `tags` filter (tracked in the [n8n-node spec](https://github.com/tpsdev-ai/flair/blob/main/specs/N8N-NODE-q3qf.md) §6). Workaround for now: use Semantic Search and let the model filter results by tags in the response.
+The Flair Search node currently exposes Semantic Search and Get By Subject. **Get By Tag** is deferred until `flair-client.memory.list` exposes a `tags` filter. Workaround for now: use Semantic Search and let the model filter results by tags in the response.
 
 ## Worked examples
 
@@ -117,6 +117,5 @@ Same Flair instance, same memories, different surfaces.
 
 ## See also
 
-- [Spec — `@tpsdev-ai/n8n-nodes-flair`](https://github.com/tpsdev-ai/flair/blob/main/specs/N8N-NODE-q3qf.md) — implementation plan, design decisions, anti-patterns
 - [Bridges](./bridges.md) — how Flair memories flow between hosts and instances
 - [Federation](./federation.md) — hub-and-spoke replication

package/docs/notes/rem-ux.md

@@ -1,6 +1,6 @@
 # REM UX — trigger model, attach semantics, review loop
 
-> Design note accompanying REM slice 2 (#707). Describes the intended user experience of in-process distillation so the CLI/docs surfaces stay coherent as the feature grows. Parent spec: `specs/FLAIR-NIGHTLY-REM.md`; slice spec: `specs/FLAIR-NIGHTLY-REM-SLICE-2-DISTILLATION.md`.
+> Design note accompanying REM slice 2 (#707). Describes the intended user experience of in-process distillation so the CLI/docs surfaces stay coherent as the feature grows. See [`docs/rem.md`](../rem.md) for the REM configuration and command reference.
 
 ## Triggers — three, nothing implicit
 

package/docs/rem.md

@@ -2,6 +2,8 @@
 
 REM (Reflect · Extract · Merge) is Flair's memory-curation cycle: it reads an agent's recent memories, distills them into candidate insights, and stages those candidates for explicit human/agent review — nothing is ever auto-promoted. `flair rem rapid` runs it on demand; `flair rem nightly enable` runs it on a schedule. See [`docs/notes/rem-ux.md`](notes/rem-ux.md) for the full trigger model, locality guarantees, and the review-loop UX this page's commands feed into.
 
+> **⚠️ Prerequisite: a configured generative backend.** All REM commands (`rapid`, `nightly`, `candidates`, `promote`, `reject`) require Harper's `models.generate()` to be wired — without it, REM calls fail with `Reflection error: No generative backend configured`. Set up a backend first (see [Configuration](#configuration) below) before running any REM command. The fastest path is Ollama with a non-thinking model, which needs zero credentials and keeps all traffic local.
+
 ## Configuration
 
 Distillation runs **server-side**, via Harper's model-access API (`models.generate()`). Flair ships zero provider code — which backend answers a REM call is entirely a Harper `models:` configuration decision.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.28.0",
+  "version": "0.29.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",

package/schemas/memory.graphql

@@ -44,13 +44,17 @@ type Memory @table(database: "flair") {
   usageCount: Int              # flair#683: verified-USE signal, distinct from retrievalCount (a
                                # search HIT). Additive/nullable — absent reads as 0, existing rows
                                # unaffected. NEVER auto-incremented on search/retrieval; the ONLY
-                               # writer is the dedicated usage-feedback endpoint (resources/
-                               # MemoryUsage.ts), which does a targeted patchRecord increment on
-                               # this field alone (never through Memory.put() — see that
-                               # resource's module doc for why: usage-feedback writes to ANOTHER
-                               # agent's memory, and Memory's ownership check would 403 every
-                               # legit call). Drives usageBoost in resources/scoring.ts, which
-                               # replaces retrievalBoost in compositeScore (retrievalCount was the
+                               # writer is resources/usage-recording.ts's recordUsageContribution()
+                               # — the shared ledger core behind BOTH usage surfaces: POST
+                               # /RecordUsage (resources/RecordUsage.ts) and citation-on-write
+                               # (resources/Memory.ts post()/put() → recordCitations(), which also
+                               # validates each cited id against the writer's read scope,
+                               # flair#775). It does a targeted get-then-put increment on this
+                               # field alone (never through Memory.put() — see RecordUsage.ts's
+                               # module doc for why: usage feedback writes to ANOTHER agent's
+                               # memory, and Memory's ownership check would 403 every legit
+                               # call). Drives usageBoost in resources/scoring.ts, which replaces
+                               # retrievalBoost in compositeScore (retrievalCount was the
                                # contaminated "retrieval counted as usage" signal root-caused in
                                # flair#623).
   promotionStatus: String   # null | "pending" | "approved" | "rejected"
@@ -155,9 +159,12 @@ type MemoryGrant @table(database: "flair") @export {
 # contributed to this memory's usageCount" is a single point-lookup, not a
 # query. This is what makes the anti-gaming dedup rule ("each (agent, memory)
 # pair contributes at most 1 to usageCount" — Sherlock) enforceable: the
-# dedicated endpoint (resources/MemoryUsage.ts) only bumps Memory.usageCount
-# when a NEW row is created here; a repeat call from the same agent for the
-# same memory is a no-op against a row that already exists.
+# shared ledger core (resources/usage-recording.ts's recordUsageContribution(),
+# reached via POST /RecordUsage and via citation-on-write's recordCitations())
+# only bumps Memory.usageCount when a NEW row is created here; a repeat call
+# from the same agent for the same memory is a no-op against a row that
+# already exists. resources/MemoryUsage.ts guards this table's own HTTP
+# surface (it is not the writer).
 #
 # `attribution` is OPAQUE — never parsed, never fed to an LLM, never rendered
 # — a free-text "what used this" hint the caller supplies, sanitized
@@ -172,7 +179,7 @@ type MemoryUsage @table(database: "flair") {
 }
 
 # MemoryCandidate — staged distillations from the FLAIR-NIGHTLY-REM cycle.
-# Per specs/FLAIR-NIGHTLY-REM.md § 7. Slice 1 of ops-2qq adds the schema +
+# Per docs/rem.md. Slice 1 of ops-2qq adds the schema +
 # `flair rem candidates` listing command. Future slices wire the nightly
 # cycle that populates this table and the promote/reject endpoints.
 #