@tpsdev-ai/flair 0.42.0 → 0.44.0

package/dist/cli.js

@@ -136,6 +136,7 @@ function shouldShowInlineSecretWarning(optValue, fromEnv, secretFlagNames, flagN
 // ─── Defaults ────────────────────────────────────────────────────────────────
 const DEFAULT_PORT = 19926;
 const DEFAULT_OPS_PORT = 19925;
+const FABRIC_OPS_PORT = 9925;
 const DEFAULT_ADMIN_USER = "admin";
 const STARTUP_TIMEOUT_MS = 60_000;
 const HEALTH_POLL_INTERVAL_MS = 500;
@@ -1076,10 +1077,15 @@ function resolveOpsTarget(opts) {
     return opts.opsTarget || process.env.FLAIR_OPS_TARGET || undefined;
 }
 /** Derive the ops API URL from a Flair base URL.
- *  Convention: ops port = HTTP port - 1.
- *  If target has an explicit port, use port-1 (validated: must be 1-65535).
- *  If no explicit port: https → 442 (443-1), http → 19925 (19926-1), bare host → https://<host>:19925.
- *  Throws on unparseable URLs.
+ *  https with effective port 443 (no explicit port, or explicit :443): returns
+ *    <host>:9925 (FABRIC_OPS_PORT) — the Fabric managed case where port-1/:442
+ *    is a dead-end.
+ *  All other cases unchanged:
+ *    https with non-443 explicit port → port-1 (self-hosted TLS: 19926→19925, 8443→8442)
+ *    http with explicit port → port-1 (19926→19925)
+ *    http with no port → DEFAULT_OPS_PORT (19925)
+ *  Bare hosts are normalised to https:// (effective-443 → Fabric path).
+ *  Throws on unparseable URLs or out-of-range ports.
  */
 /** Compute the effective ops API URL for remote commands.
  *  - If --ops-target is set, use it directly (no derivation).
@@ -1099,6 +1105,17 @@ function resolveOpsUrlFromTarget(targetUrl) {
     // Normalise bare hosts: add https:// prefix so URL parser can handle them.
     const normalised = targetUrl.includes("://") ? targetUrl : `https://${targetUrl}`;
     const url = new URL(normalised);
+    // https target with effective port 443 (no explicit port, or explicit :443):
+    // this is the Fabric managed case — the ops API is on the well-known Fabric
+    // ops port, never REST-adjacent. The port-1 / :442 logic is a dead-end here.
+    if (url.protocol === "https:" && (url.port === "" || url.port === "443")) {
+        url.port = String(FABRIC_OPS_PORT);
+        return url.toString().replace(/\/$/, "");
+    }
+    // All other cases: unchanged port-1 convention.
+    //   https with non-443 explicit port → port-1 (self-hosted TLS: 19926→19925, 8443→8442)
+    //   http with explicit port → port-1 (19926→19925)
+    //   http with no port → DEFAULT_OPS_PORT (19925)
     const port = parseInt(url.port, 10);
     if (!isNaN(port) && port > 0 && port <= 65535) {
         const opsPort = port - 1;
@@ -1111,13 +1128,8 @@ function resolveOpsUrlFromTarget(targetUrl) {
     if (url.port !== "" && url.port !== undefined) {
         throw new Error(`Invalid target port: ${url.port} (must be 1-65535)`);
     }
-    // No explicit port — infer from scheme
-    if (url.protocol === "https:") {
-        url.port = "442";
-    }
-    else {
-        url.port = String(DEFAULT_OPS_PORT);
-    }
+    // No explicit port on http — use the default ops port.
+    url.port = String(DEFAULT_OPS_PORT);
     return url.toString().replace(/\/$/, "");
 }
 /**
@@ -1782,12 +1794,21 @@ export async function seedFederationInstanceViaOpsApi(opsPortOrUrl, instanceId,
 export async function callOpsApi(opsUrl, body, user, pass) {
     const url = `${opsUrl.replace(/\/$/, "")}/`;
     const auth = Buffer.from(`${user}:${pass}`).toString("base64");
-    const res = await fetch(url, {
-        method: "POST",
-        headers: { "Content-Type": "application/json", ...(auth ? { Authorization: `Basic ${auth}` } : {}) },
-        body: JSON.stringify(body),
-        signal: AbortSignal.timeout(30_000),
-    });
+    let res;
+    try {
+        res = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", ...(auth ? { Authorization: `Basic ${auth}` } : {}) },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(30_000),
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`ops API unreachable at ${opsUrl} (derived from --target). ` +
+            `Set --ops-target or FLAIR_OPS_TARGET to override. ` +
+            `(${message})`);
+    }
     if (!res.ok) {
         const text = await res.text().catch(() => "");
         throw new Error(`Ops API call failed (${res.status}): ${text}`);
@@ -12085,22 +12106,34 @@ program
             const hook = inspectSessionStartHook(homedir());
             if (hook.present) {
                 if (hook.execution === "broken") {
-                    // Reported in full, with the remedy — but NOT counted as an issue,
-                    // so it never flips doctor's exit code on its own. This is a
-                    // verification of the environment at the moment doctor runs (a
-                    // cold `npx` cache, an offline machine, a slow registry), exactly
-                    // like the FLAIR_URL reachability and agent-registration
-                    // verifications above, which are warnings for the same reason. A
-                    // fresh, correct install on a machine that simply has not fetched
-                    // the adapter yet must not be told it is broken in the exit code.
-                    // The unsilenced finding below IS counted: that one is a fact
-                    // about the file, true regardless of the environment.
-                    console.log(`  ${render.icons.warn} SessionStart hook: wired in ${render.wrap(render.c.dim, hook.path)}, but its command did not run just now`);
-                    console.log(`     ${render.wrap(render.c.dim, hook.detail ?? "")}`);
-                    console.log(`     ${render.wrap(render.c.dim, "If this persists, the Node runtime probably changed and the globally")}`);
-                    console.log(`     ${render.wrap(render.c.dim, "installed @tpsdev-ai/flair-mcp no longer resolves for it.")}`);
-                    console.log(`     ${render.wrap(render.c.dim, "Fix:")} npm install -g @tpsdev-ai/flair-mcp ${render.wrap(render.c.dim, "(reinstall for the runtime you use now)")}`);
-                    console.log(`     ${render.wrap(render.c.dim, "Or, if you no longer want ambient memory:")} flair hook uninstall`);
+                    // Two very different states that share one probe outcome:
+                    //
+                    // 1. Silenced (current) command that didn't run — the npx cache
+                    //    is cold, the machine is offline, or the adapter hasn't been
+                    //    fetched yet.  On a fresh install this is NORMAL: the hook is
+                    //    wired but no Claude Code session has exercised it yet.
+                    //    Report as informational, not a warning, and never suggest
+                    //    reinstall — the setup is correct, the environment just
+                    //    hasn't warmed yet.
+                    //
+                    // 2. Unsilenced (legacy) command that didn't run — the hook has
+                    //    been in place long enough that a cold cache is not the
+                    //    explanation.  This IS a genuine failure: warn and name the
+                    //    actual state with a fitting remedy.
+                    if (hook.silenced) {
+                        console.log(`  ${render.icons.ok} SessionStart hook: wired in ${render.wrap(render.c.dim, hook.path)} — not yet exercised`);
+                        console.log(`     ${render.wrap(render.c.dim, hook.detail ?? "")}`);
+                        console.log(`     ${render.wrap(render.c.dim, "The hook is correctly wired but the adapter has not been fetched yet.")}`);
+                        console.log(`     ${render.wrap(render.c.dim, "This is normal on a fresh install — the first Claude Code session will warm the npx cache.")}`);
+                    }
+                    else {
+                        console.log(`  ${render.icons.warn} SessionStart hook: wired in ${render.wrap(render.c.dim, hook.path)}, but its command did not run just now`);
+                        console.log(`     ${render.wrap(render.c.dim, hook.detail ?? "")}`);
+                        console.log(`     ${render.wrap(render.c.dim, "The hook command could not be executed. Check that npx can resolve")}`);
+                        console.log(`     ${render.wrap(render.c.dim, "@tpsdev-ai/flair-mcp — a cold cache, missing global install, or network")}`);
+                        console.log(`     ${render.wrap(render.c.dim, "issue can prevent the adapter from running on its first invocation.")}`);
+                        console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair doctor --fix ${render.wrap(render.c.dim, "(rewrites the hook to the current silent-failure form)")}`);
+                    }
                 }
                 else if (hook.execution === "unknown") {
                     console.log(`  ${render.icons.warn} SessionStart hook: wired in ${render.wrap(render.c.dim, hook.path)}, but could not be verified ${render.wrap(render.c.dim, `(${hook.detail ?? "no detail"})`)}`);
@@ -16058,7 +16091,7 @@ if (import.meta.main) {
 // ─── Exported for testing ─────────────────────────────────────────────────────
 export { runCli, resolveKeyPath, buildEd25519Auth, readPortFromConfig, readOpsBindFromConfig, readOpsPortFromConfig, writeConfig, resolveHttpPort, resolveOpsPort, resolveOpsBindHost, 
 // Harper's own config — the per-instance port record (flair#914)
-harperConfigPath, readHarperConfig, readPortFromHarperConfig, persistDefaultInstallCoordinates, resolveTarget, resolveOpsTarget, resolveEffectiveOpsUrl, resolveOpsUrlFromTarget, signRequestBody, b64, b64url, program, api, VALID_PRESENCE_ACTIVITIES, MAX_TASK_LENGTH, MAX_WORKSPACE_FIELD_LENGTH, MAX_ORGEVENT_SUMMARY_LENGTH, MAX_ORGEVENT_DETAIL_LENGTH, isLocalBase, isLikelyRealSecret, shouldShowInlineSecretWarning, parseTokenFromFile, resolveLocalAdminPass, readAdminPassFileSecure, 
+harperConfigPath, readHarperConfig, readPortFromHarperConfig, persistDefaultInstallCoordinates, resolveTarget, resolveOpsTarget, resolveEffectiveOpsUrl, resolveOpsUrlFromTarget, FABRIC_OPS_PORT, signRequestBody, b64, b64url, program, api, VALID_PRESENCE_ACTIVITIES, MAX_TASK_LENGTH, MAX_WORKSPACE_FIELD_LENGTH, MAX_ORGEVENT_SUMMARY_LENGTH, MAX_ORGEVENT_DETAIL_LENGTH, isLocalBase, isLikelyRealSecret, shouldShowInlineSecretWarning, parseTokenFromFile, resolveLocalAdminPass, readAdminPassFileSecure, 
 // launchd label (flair#693)
 LEGACY_LAUNCHD_LABEL, launchdLabel, launchdPlistPath, cleanupLegacyLaunchdPlist, resolveLaunchdLabel, migrateLegacyLaunchdLabel, ensureLaunchdServiceLoaded, 
 // launchd management observation (flair#1022)

package/dist/doctor-client.js

@@ -41,7 +41,7 @@ export const SESSION_START_HOOK_MARKER = "flair-session-start";
 //
 // WHY THE INVOCATION IS WRAPPED
 // -----------------------------
-// The hook runs `npx -y @tpsdev-ai/flair-mcp flair-session-start`: it resolves
+// The hook runs `npx -y -p @tpsdev-ai/flair-mcp flair-session-start`: it resolves
 // a package binary through whatever Node runtime the user's shell happens to
 // expose. Under a Node version manager, globally installed packages are
 // per-runtime-version, so a routine and entirely unrelated runtime upgrade
@@ -117,7 +117,7 @@ export function buildSessionStartHookCommand(agentId, flairUrl) {
         throw new Error(`Flair URL '${flairUrl}' contains characters that cannot be safely written into a shell hook command (allowed: letters, digits, . _ : / -)`);
     }
     const env = flairUrl ? `FLAIR_AGENT_ID=${agentId} FLAIR_URL=${flairUrl}` : `FLAIR_AGENT_ID=${agentId}`;
-    const invocation = `${env} npx -y @tpsdev-ai/flair-mcp ${SESSION_START_HOOK_MARKER}`;
+    const invocation = `${env} npx -y -p @tpsdev-ai/flair-mcp ${SESSION_START_HOOK_MARKER}`;
     return `sh -c 'out=$(${invocation} 2>/dev/null) && printf %s "$out" || true'`;
 }
 /**
@@ -525,6 +525,18 @@ export function inspectSessionStartHook(homeDir, opts = {}) {
     const verdict = classifyHookProbe(outcome);
     return { path: found.path, present: true, command, ours, silenced, upgradable, execution: verdict.execution, detail: verdict.detail };
 }
+export function classifyHookReadiness(report) {
+    if (!report.present)
+        return "absent";
+    if (!report.ours)
+        return "custom";
+    if (report.execution === "runs")
+        return "runs";
+    if (report.execution === "broken") {
+        return report.silenced ? "not-yet-exercised" : "genuinely-broken";
+    }
+    return "unverified";
+}
 /**
  * Rewrite an existing Flair-authored hook command to the current canonical
  * form, in place, preserving the agent id and URL the entry already carries —

package/dist/hook-install.js

@@ -344,7 +344,7 @@ export function hookStatus(homeDir, harness) {
     }
     const hookEntry = config.hooks.SessionStart[existing.groupIndex].hooks[existing.hookIndex];
     const command = typeof hookEntry?.command === "string" ? hookEntry.command : "";
-    const correctShape = hookEntry?.type === "command" && command.includes(`npx -y @tpsdev-ai/flair-mcp ${SESSION_START_HOOK_MARKER}`);
+    const correctShape = hookEntry?.type === "command" && command.includes(`npx -y -p @tpsdev-ai/flair-mcp ${SESSION_START_HOOK_MARKER}`);
     const env = parseHookCommandEnv(command);
     return {
         harness, path, wired: true, correctShape,

package/dist/lib/mcp-enable.js

@@ -286,10 +286,12 @@ export function readSigningKeyFile(path) {
 /**
  * The `@harperfast/oauth` config block, matching the installed 2.2.0
  * package's field names (node_modules/@harperfast/oauth/dist/types.d.ts).
- * Secrets are `${ENV_VAR}` placeholders — never literal values — so this
- * block is safe to write to harperdb-config.yaml via `set_configuration`
- * (the config file itself carries no secret material; see the
- * secrets-provisioning step for how the referenced env vars land).
+ * Secrets are `${ENV_VAR}` placeholders — never literal values.
+ *
+ * flair#1136: set_configuration delivery was removed. Fabric regenerates
+ * the root harperdb-config.yaml; the component's own config.yaml is the
+ * source of truth for the oauth block. This function builds the block that
+ * ships in config.yaml — it is never written to harperdb-config.yaml.
  *
  * flair#756: `dynamicClientRegistration: { enabled: false }` is written
  * EXPLICITLY — never omitted. See the module header's "Leaving
@@ -634,32 +636,7 @@ export async function provisionIdpIdentityMapping(params, deps = {}) {
     }
     return { principalCreated, credentialId, credentialReused: Boolean(existing) };
 }
-/** `set_configuration` (writes harperdb-config.yaml) then `restart`
- *  (whole-process restart) — the genuine Harper Operations API operations
- *  this module's header documents. Throws on either non-2xx response. */
-export async function applyRemoteConfigAndRestart(params, deps = {}) {
-    const fetchImpl = deps.fetchImpl ?? fetch;
-    const opsUrl = opsBaseUrl(params.opsPortOrUrl);
-    const authHeader = basicAuthHeader(params.adminUser, params.adminPass);
-    const setRes = await fetchImpl(opsUrl, {
-        method: "POST",
-        headers: { "Content-Type": "application/json", Authorization: authHeader },
-        body: JSON.stringify({ operation: "set_configuration", ...params.configBlock }),
-    });
-    if (!setRes.ok) {
-        const text = await setRes.text().catch(() => "");
-        throw new Error(`set_configuration failed (HTTP ${setRes.status}): ${text}`);
-    }
-    const restartRes = await fetchImpl(opsUrl, {
-        method: "POST",
-        headers: { "Content-Type": "application/json", Authorization: authHeader },
-        body: JSON.stringify({ operation: "restart" }),
-    });
-    if (!restartRes.ok) {
-        const text = await restartRes.text().catch(() => "");
-        throw new Error(`restart failed (HTTP ${restartRes.status}): ${text}`);
-    }
-}
+// ─── Restart only ────────────────────────────────────────────────────────────
 /** `restart` only — used by `disableMcp` (flag off + restart, no config
  *  rewrite: the `@harperfast/oauth` config block is left in place; it is
  *  inert whenever `FLAIR_MCP_OAUTH` is unset, per the byte-identical-boot

package/docs/deploying-on-fabric.md

@@ -129,14 +129,17 @@ where nothing answers:
 # --target https://<fabric-node>:19926/<instance>     → ops derived as :19925 ✓
 ```
 
+**Fabric's ops API runs on the same hostname at port 9925** <!-- docs-freshness-allow: Fabric ops API port, not legacy data port --> (the deploy/upgrade path already targets this port). For a managed `*.harperfabric.com` instance:
+
+```bash
+# Same hostname, port 9925 — not port 442 <!-- docs-freshness-allow: Fabric ops API -->
+flair init --target https://<cluster>.<org>.harperfabric.com \
+    --ops-target https://<cluster>.<org>.harperfabric.com:9925 <!-- docs-freshness-allow: Fabric ops API -->
+```
+
 **Pass `--ops-target <url>` explicitly** (or set `FLAIR_OPS_TARGET`) on any command that
 touches the ops API: `init --target`, `agent add --target`, `federation token --target`.
 
-> **Gap — needs a Fabric account to verify.** This guide does not state the correct
-> ops-API URL for a managed `*.harperfabric.com` instance, or whether the ops API is
-> reachable remotely there at all. The derivation above is certain (read from source);
-> the right value to pass is not.
-
 Precedence: `--target` > `--url` > `FLAIR_TARGET` > `FLAIR_URL` > localhost. For ops:
 `--ops-target` > `FLAIR_OPS_TARGET` > derived > localhost.
 
@@ -250,8 +253,9 @@ and shells out to `lsof`. The command you'd reach for when something breaks is u
 here. Unavailable too: `start`, `stop`, `restart`, `snapshot`, `reembed`, `rem`, `bridge`.
 
 **Fabric's own cluster topology is invisible.** `fleet verify` sweeps *Flair's* federation
-peer table, not Harper's cluster nodes — `cluster_status` is harper-pro-only and absent
-from the OSS `harper` build. **`0 peers known` means "0 on file", never "0 exist."**
+peer table, not Harper's cluster nodes. **`cluster_status` works on Fabric** — Fabric
+always runs harper-pro (not the OSS harper build), so cluster_status is available over
+the ops API. `0 peers known` means "0 on file", never "0 exist."
 
 **There is no disk or quota telemetry.** `flair status` reports usage for two directories:
 no free space, no total, no quota, no warning threshold, walk capped at six levels, no
@@ -263,6 +267,35 @@ with nothing saying so. The one indirect signal is a migration halting for space
 > wouldn't matter: Flair calls it only as a post-failure convergence oracle and discards
 > the `size` field. Component disk usage is invisible structurally.
 
+### The `mcp.enabled` operator step
+
+MCP is **off by default**. The shipped component `config.yaml` contains
+`@harperfast/oauth` → `mcp` → `enabled: false`. Until [flair#1152](https://github.com/tpsdev-ai/flair/issues/1152)
+lands (interpolate from env — *ON HOLD*), you must flip this manually:
+
+1. In your deployed component's `config.yaml`, change:
+    ```yaml
+    '@harperfast/oauth':
+     mcp:
+       enabled: true      # was: false
+    ```
+2. Re-deploy the component so Harper picks up the new value.
+3. **Verify the `/mcp` surface is actually serving** (the flag alone does not
+   guarantee it — a secret that is stored but never decrypted fails at self-verify):
+    ```bash
+    # Check /mcp is reachable and returning MCP protocol (not a loopback proxy or 404)
+    curl -sf https://\<cluster\>.\<org\>.harperfabric.com/mcp
+    # Should return MCP JSON-RPC content; if you get HTML redirect or 404 the flag
+    # is not effective
+    ```
+
+**⚠ SECURITY CAVEAT — the upgrade-reverts trap.** Any package update or fleet component
+update re-ships the literal `enabled: false` and silently darkens a live `/mcp` surface.
+You must **re-flip to `true` after every upgrade** and re-deploy. An updated component
+without this re-flip will appear healthy (`/Health` green) while its MCP tools are
+dark to every connected client. If you rely on MCP, add the re-flip to your upgrade
+runbook.
+
 ### Known hazard: unbounded npm cache
 
 **Open — [flair#886](https://github.com/tpsdev-ai/flair/issues/886).** Every deploy runs a

package/docs/hosted-on-fabric.md

@@ -79,6 +79,35 @@ The staging file is written in every case, so a fallback never strands you mid-r
 
 `--secrets-mechanism <fabric-env-secrets|env-file>` remains an explicit override and skips the probe entirely.
 
+### The `mcp.enabled` operator step (Fabric)
+
+MCP is **off by default**. The shipped component `config.yaml` contains
+`@harperfast/oauth` → `mcp` → `enabled: false`. Until [flair#1152](https://github.com/tpsdev-ai/flair/issues/1152)
+lands (interpolate from env — *ON HOLD*), you must flip this manually:
+
+1. In your deployed component's `config.yaml`, change:
+   ```yaml
+   '@harperfast/oauth':
+     mcp:
+       enabled: true     # was: false
+   ```
+2. Re-deploy the component so Harper picks up the new value.
+3. **Verify the `/mcp` surface is actually serving** (the flag alone does not
+   guarantee it — a secret that is stored but never decrypted fails at self-verify):
+   ```bash
+   # Check /mcp is reachable and returning MCP protocol (not a loopback proxy or 404)
+   curl -sf https://<cluster>.<org>.harperfabric.com/mcp
+   # Should return MCP JSON-RPC content; if you get HTML redirect or 404 the flag
+   # is not effective
+   ```
+
+**⚠ SECURITY CAVEAT — the upgrade-reverts trap.** Any package update or fleet component
+update re-ships the literal `enabled: false` and silently darkens a live `/mcp` surface.
+You must **re-flip to `true` after every upgrade** and re-deploy. An updated component
+without this re-flip will appear healthy (`/Health` green) while its MCP tools are
+dark to every connected client. If you rely on MCP, add the re-flip to your upgrade
+runbook.
+
 ---
 
 ## Agent authentication
@@ -140,7 +169,7 @@ flair fleet verify --target https://<cluster>.<org>.harperfabric.com
 
 **`flair doctor`** takes no `--target` — it hardcodes localhost, reads a local PID file, and shells out to `lsof`. Unavailable too: `start`, `stop`, `restart`, `snapshot`, `reembed`, `rem`, `bridge`.
 
-**Fabric's own cluster topology is invisible.** `fleet verify` sweeps *Flair's* federation peer table, not Harper's cluster nodes. `cluster_status` is harper-pro-only. `0 peers known` means "0 on file", never "0 exist."
+**Fabric's own cluster topology is invisible.** `fleet verify` sweeps *Flair's* federation peer table, not Harper's cluster nodes. **`cluster_status` works on Fabric** — Fabric always runs harper-pro (not the OSS harper build), so cluster_status is available over the ops API. `0 peers known` means "0 on file", never "0 exist."
 
 ---
 

package/docs/mcp-clients.md

@@ -109,7 +109,7 @@ Or wire it by hand — add a `SessionStart` hook to `~/.claude/settings.json`:
         "hooks": [
           {
             "type": "command",
-            "command": "sh -c 'out=$(FLAIR_AGENT_ID=me npx -y @tpsdev-ai/flair-mcp flair-session-start 2>/dev/null) && printf %s \"$out\" || true'"
+            "command": "sh -c 'out=$(FLAIR_AGENT_ID=me npx -y -p @tpsdev-ai/flair-mcp flair-session-start 2>/dev/null) && printf %s \"$out\" || true'"
           }
         ]
       }

package/docs/quickstart.md

@@ -154,6 +154,8 @@ flair search --agent local "native addon loading in sandboxed runtimes"
 
 You searched for a concept, not the keywords. The line under each hit is its creation date, durability tier, and rank score.
 
+> **When stdout is not a terminal** — piped to another command, captured in a script, or run in CI — the same `flair search` command emits a JSON array instead of the formatted prose above. Each hit is an object with `id`, `text`, `createdAt`, `durability`, and `_score` fields. Add `--explain` to include an `_explain` ranking breakdown on each hit. Use `flair search --json` to force JSON output even in a terminal, or `flair memory search` for the raw JSON form in all contexts.
+
 > The percentage is a **rank-fusion score, not a similarity**. It is normalized so the top result is always near 100%. Read it as ordering within these results, never as confidence that the match is good.
 
 Add `--explain` to see the ranking inputs per hit — the raw score, the composite score under `--scoring composite`, and the record's durability, age and usage count. When output is JSON (`--json`, or any time stdout is not a terminal) the same breakdown arrives as an `_explain` object on each hit, so scripts get it too. Use `--limit`, `--tag`, `--since 7d` to narrow the search. `flair memory search` runs the same query but always prints raw JSON — use it when piping to a script.

package/docs/troubleshooting.md

@@ -23,7 +23,8 @@ If it fails to start:
 lsof -i :19926
 
 # Check logs (macOS)
-cat ~/.flair/data/log/hdb.log | tail -50
+cat ~/.flair/data/log/hdb.log | tail -50     # Harper ≤ 5.1 only (see below)
+cat ~/.flair/data/log/system.log | tail -50   # Harper 5.2+ (live log)
 
 # Check logs (Linux)
 journalctl --user -u flair --since "10 minutes ago"
@@ -242,6 +243,14 @@ flair --help          # all commands
 flair <command> -h    # command-specific help
 ```
 
-Logs: `~/.flair/data/log/hdb.log`
+**Log paths depend on Harper version:**
+
+- **Harper ≤ 5.1:** `~/.flair/data/log/hdb.log`
+- **Harper 5.2+:** `~/.flair/data/log/system.log`
+
+> ⚠ **On Harper 5.2+, `hdb.log` freezes at the upgrade boundary.** The live log is
+> `system.log`. The Harper ops `read_log` endpoint keeps serving the frozen `hdb.log`,
+> so remote diagnosis reads days-stale entries that look current. Always check
+> `system.log` after upgrading to 5.2+.
 
 File issues: [github.com/tpsdev-ai/flair/issues](https://github.com/tpsdev-ai/flair/issues)

package/package.json

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