@tpsdev-ai/flair 0.49.0 → 0.50.0

package/dist/src/rem/scheduler.js

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

package/docs/auth.md

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

package/docs/deepseek-harness.md

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

package/docs/hosted-on-fabric.md

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

package/docs/integrations.md

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

package/docs/mcp-clients.md

@@ -96,10 +96,10 @@ flair hook status                # wired? correct shape? which agent/instance?
 flair hook uninstall             # removes only Flair's hook entry
 ```
 
-`--harness claude-code` is the only supported value today (it's also the
-default) — the flag exists so a future harness is an additive registry entry,
-not a breaking change. `flair doctor` already checks for this same hook (see
-below) and recognizes anything `flair hook install` writes.
+`--harness` defaults to `claude-code`. `codex` is also supported (writes
+`~/.codex/hooks.json` — see the Codex section below). `flair doctor` checks
+the same hook for each detected harness and recognizes anything
+`flair hook install` writes.
 
 Or wire it by hand — add a `SessionStart` hook to `~/.claude/settings.json`:
 
@@ -111,7 +111,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 -p @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@<version> flair-session-start 2>/dev/null) && printf %s \"$out\" || true'"
           }
         ]
       }
@@ -120,12 +120,23 @@ Or wire it by hand — add a `SessionStart` hook to `~/.claude/settings.json`:
 }
 ```
 
-Swap `me` for your `FLAIR_AGENT_ID`. Unlike the MCP-server snippets above, this
-one is shown **unpinned**, because that is what `flair hook install` writes and
-what the tooling recognises: `flair hook status` matches the exact unpinned
-command, so a hand-pinned hook reports `wired: false` there (while `flair
-doctor` still sees it). Pinning this line is therefore not yet supported —
-prefer `flair hook install`.
+Swap `me` for your `FLAIR_AGENT_ID` and `<version>` for `flair --version`. This
+is the same pin `flair init` writes into client MCP configs (`mcpServerSpec()`,
+flair#907): a wired hook should not self-update to a freshly published
+`flair-mcp` any more than a wired MCP client should. `flair hook install`,
+`flair init`, and `flair doctor --fix` (when adding a missing hook) write that
+pin; re-run `flair hook install` to advance a stale or pre-#1143 unpinned hook
+to the running CLI's version.
+
+That is a different surface from public plugin `mcp.json` files, which stay
+**unpinned** on purpose (flair#1308) so directory listings that scrape them do
+not freeze on a shipped version. User-local wiring is pinned; catalog
+manifests are not.
+
+`flair hook status` recognises both the current pinned `-p` form and an older
+unpinned `-p` invocation as `correctShape`. The pre-#1166 form (no `-p`, which
+runs the MCP shim) is still flagged. Prefer `flair hook install` over
+hand-editing.
 
 The `sh -c ... || true` wrapper is not decoration. The invocation resolves a
 package binary through whatever Node runtime your shell exposes, and under a
@@ -208,6 +219,46 @@ For project-scoped trust (per Codex's MCP guide), the same block in `.codex/conf
 
 Restart your Codex CLI session and the `flair_*` tools become available to the agent.
 
+#### Auto-recall on session start (optional hook)
+
+Wiring the MCP server alone does not load memory at session start — Codex
+then has pull tools it never thinks to call. The same `flair-session-start`
+command Claude Code uses writes Codex's SessionStart hook (same JSON schema,
+into `~/.codex/hooks.json`):
+
+```bash
+flair hook install --harness codex
+flair hook status --harness codex
+flair hook uninstall --harness codex
+```
+
+`flair doctor` reports this hook when Codex is detected. After install, trust
+the new command in Codex with `/hooks` — untrusted hooks are listed and
+skipped.
+
+---
+
+## Hookless harnesses (Gemini, Cursor, and anything without SessionStart)
+
+Some clients have no session-start hook Flair can write. Wiring the MCP
+server is necessary but not sufficient — the model still has to choose to
+call `bootstrap`. Add a short instruction block to the file that client
+already loads (`AGENTS.md`, `GEMINI.md`, or the equivalent):
+
+```markdown
+## Flair memory
+
+At the start of every session, call the Flair `bootstrap` tool before
+responding. Before a deep-dive, `memory_search` for related prior work.
+At wrap, `memory_store` durable lessons.
+```
+
+Without that, a config that looks wired is the known failure shape
+([#989](https://github.com/tpsdev-ai/flair/issues/989),
+[#908](https://github.com/tpsdev-ai/flair/issues/908)): tools exist, memory
+never enters the working set. Use `flair hook install` when the client has
+a SessionStart hook; use this static block when it does not.
+
 ---
 
 ## Step 3 — Verify
@@ -222,13 +273,13 @@ If you see (a) the agent calling the `bootstrap` tool returning soul + recent me
 
 ## What the MCP server exposes
 
-Eleven tools, kept deliberately small:
+Twelve tools, kept deliberately small:
 
 | Tool | What it does |
 |---|---|
 | `memory_search` | Semantic search across your agent's memories |
-| `memory_store` | Save a memory with type, durability, tags, visibility. Auto-dedups near-duplicates |
-| `memory_update` | Update an existing memory by ID — overwrite in place, or version it with `preserveHistory` |
+| `memory_store` | Save a memory with type, durability, tags, visibility. Auto-dedups near-duplicates. Optional `usedMemoryIds` cites memories that informed the write |
+| `memory_update` | Update an existing memory by ID — overwrite in place, or version it with `preserveHistory`. Optional `usedMemoryIds` for citation-on-write |
 | `memory_get` | Fetch a specific memory by ID |
 | `memory_delete` | Remove a memory |
 | `relationship_store` | Record a subject-predicate-object relationship triple (e.g. "nathan manages flair") |
@@ -237,6 +288,7 @@ Eleven tools, kept deliberately small:
 | `soul_get` | Get a soul entry |
 | `flair_workspace_set` | Set your agent's current workspace state (ref/branch, phase, task) in the Office Space |
 | `flair_orgevent` | Publish an org-wide coordination event (claim/release/status) to the Office Space |
+| `record_usage` | Report that recalled memories were actually used (id + optional one-line how-it-was-used). Drives `usageCount` / `usageBoost` |
 
 Writes are scoped per-agent (your `FLAIR_AGENT_ID`) and enforced by Flair's server, not by client convention — you can't write as another agent. Reads are more open by design: any agent on the same Flair instance can read any other agent's **non-private** memories, with no grant to set up (open-within-org read; see [SECURITY.md](../SECURITY.md)).
 
@@ -298,7 +350,7 @@ Future MCP-capable agent CLIs (and there are more landing every month) will work
 
 **"connection_error: could not reach Flair at http://127.0.0.1:19926".** The Flair server isn't running. Run `flair status` to check; `flair start` to bring it up.
 
-**"auth_error: …" on every call.** The agent identity doesn't match a registered key. Re-run `flair agent add <id>` (idempotent on re-add — won't lose existing memories).
+**"auth_error: …" on every call.** The agent identity doesn't match a registered key. Re-run `flair agent add <id>` (idempotent on re-add — won't lose existing memories). Against a hosted instance the same three shapes apply (record missing / key mismatch / config wrong), and a by-id 404 is fail-closed ownership, not an existence signal — [Hosted Flair auth](integrations.md#hosted-flair-auth--your-agent-got-a-404).
 
 **Tool calls succeed but the agent doesn't see results in subsequent turns.** Check that the CLI is actually invoking `bootstrap` at session start — most CLIs need an explicit prompt nudge ("call the bootstrap tool now") on first use. Subsequent turns should pick up automatically once the CLI sees the schema.
 

package/docs/quickstart-fabric.md

@@ -119,7 +119,7 @@ Same connector, different panel. This is the field-verified sequence — includi
 
    Keep the pass file mode `0600`. Newer releases add `--admin-pass-file <path>`, which reads the file in-process (invisible to `ps`) — check `flair agent add --help` and prefer it when present.
 
-5. **Restart the MCP process** if it started before the key existed — it does not pick the key up mid-session. Still 401 with the key on disk? Set the key path explicitly in the agent's MCP env: `FLAIR_KEY_PATH=~/.flair/keys/grok-cos.key`. Known papercut, tracked in [flair#1271](https://github.com/tpsdev-ai/flair/issues/1271).
+5. The next tool call picks up the key — a miss is not cached. A 401 names the agent and the paths that were looked in. If those are not where `flair agent add` wrote the file, the MCP process's home differs from the shell; set `FLAIR_KEY_PATH` to the absolute path of the `.key` file.
 
 6. Verify: ask the agent to "load my Flair bootstrap". You should get soul + memories **including shared org context** — findings written by teammate agents. A shared-visibility write from this agent is now readable by every org agent.
 

package/docs/troubleshooting.md

@@ -105,6 +105,31 @@ date
 
 If using the MCP server, restart Claude Code after rotating keys.
 
+`flair agent list` is localhost-only. Against a hosted instance, the
+discriminator is the 401 body on a signed request (`unknown_agent` vs
+`invalid_signature`), not a local agent list. Adapter-shaped walkthrough:
+[integrations.md — Hosted Flair auth](integrations.md#hosted-flair-auth--your-agent-got-a-404).
+
+### 404 on `GET`/`PUT /Memory/{id}`
+
+**Symptoms:** `memory_get`, a by-id update, or an adapter write/read against
+`/Memory/{id}` returns 404. The agent reports "not found" or "Harper rejected
+the verb."
+
+**This is not an existence signal.** By-id routes return the same 404 when
+the id is absent and when the record exists but the caller may not see it
+(fail-closed ownership, [flair#1264](https://github.com/tpsdev-ai/flair/issues/1264)).
+A 403 would confirm the id and can name the owner; Flair refuses that.
+
+**Also not this:** `401 unknown_agent` / `401 invalid_signature` (identity —
+see above). Harper's catch-all 404 when the Flair app is not loaded yet
+(`/Health` can already be 200). A `FLAIR_URL` with a path prefix.
+
+Creates go to `POST /Memory/` (id in the body). Do not treat a by-id 404 as
+a reason to paste admin credentials into the agent's environment.
+
+Full adapter guide: [integrations.md — Hosted Flair auth](integrations.md#hosted-flair-auth--your-agent-got-a-404).
+
 ### "signing key ... could not be parsed as an Ed25519 private key"
 
 **Symptoms:** `flair doctor` reports, naming the file:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.49.0",
+  "version": "0.50.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",
@@ -59,7 +59,7 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=22"
+    "node": "^22.18.0 || >=24.0.0"
   },
   "dependencies": {
     "@harperfast/oauth": "2.5.0",