@tpsdev-ai/flair 0.32.0 → 0.34.0

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": "FLAIR_AGENT_ID=me npx -y @tpsdev-ai/flair-mcp flair-session-start"
+            "command": "sh -c 'out=$(FLAIR_AGENT_ID=me npx -y @tpsdev-ai/flair-mcp flair-session-start 2>/dev/null) && printf %s \"$out\" || true'"
           }
         ]
       }
@@ -125,6 +125,21 @@ 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`.
 
+The `sh -c ... || true` wrapper is not decoration. The invocation resolves a
+package binary through whatever Node runtime your shell exposes, and under a
+Node version manager globally installed packages are per-runtime-version — so
+a routine, unrelated runtime upgrade can orphan it. Without the wrapper the
+hook then fails on *every* session, forever, with an error that names neither
+Flair nor a remedy, and it keeps doing so after Flair itself is uninstalled.
+The wrapper makes any failure to resolve or execute produce no output and exit
+0: ambient memory is a decoration on your session and must never be louder
+than the thing it decorates. Success is unaffected — the hook's output is
+passed through byte-for-byte.
+
+If you already have the older, unwrapped command, `flair doctor` reports it and
+`flair doctor --fix` rewrites it in place (same agent, same instance);
+`flair hook status` shows the same under **On failure**.
+
 The hook reads Claude Code's SessionStart
 payload on stdin, calls Flair's `bootstrap` (soul + relevant memories +
 predicted context, scoped to your project by the session's working directory),
@@ -141,7 +156,14 @@ It honors the same env as the MCP server (`FLAIR_AGENT_ID`, `FLAIR_URL`,
 error, or a hung daemon (past the timeout) → the hook prints `{}` and exits 0.
 Claude Code treats that as "no context to add" and starts normally. The hook
 can never block or break session startup. The injected context is clamped to
-≤10,000 characters to keep the session-start payload small.
+≤10,000 characters to keep the session-start payload small. And if the command
+cannot resolve at all — so none of that code ever runs — the wrapper above
+still yields no output and exit 0.
+
+`flair doctor` verifies the second half by actually running the registered
+command with `FLAIR_HOOK_PROBE=1`, which makes the hook print its inert output
+and exit immediately: no bootstrap, no presence write, no network. Reaching it
+is the whole answer.
 
 ### Gemini CLI
 
@@ -203,7 +225,7 @@ Eleven 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. Auto-dedups near-duplicates |
+| `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_get` | Fetch a specific memory by ID |
 | `memory_delete` | Remove a memory |
@@ -214,7 +236,9 @@ Eleven tools, kept deliberately small:
 | `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 |
 
-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 (open-within-org read; see [SECURITY.md](../SECURITY.md)). Mark a memory `visibility: private` to keep it owner-only.
+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)).
+
+Which memories are non-private is decided at write time, and the default is not "shared". `memory_store` defaults `durability` to `standard`, and the server derives visibility from durability — `permanent`/`persistent` → `shared`, `standard`/`ephemeral` → `private` — so **a bare `memory_store` call writes an owner-only memory that no other agent can read.** Pass `visibility: "shared"` (or `"private"`, to be explicit) to say what you mean; the tool reports the visibility the write actually landed on so an agent can confirm it rather than assume.
 
 ---
 

package/docs/quickstart.md

@@ -26,7 +26,9 @@ export PATH="$HOME/.npm-global/bin:$PATH"   # add this to ~/.zshrc or ~/.bashrc
 npm install -g @tpsdev-ai/flair
 ```
 
-One install gives you `flair`, `flair-mcp` and the client library.
+One install gives you one command: `flair`.
+
+The stdio adapter your MCP client talks to is a separate package, `@tpsdev-ai/flair-mcp`, and it is deliberately not installed globally — `flair init` wires each client to fetch it on demand with `npx -y @tpsdev-ai/flair-mcp@<version>`, so there is no second global package to keep in step. (The server also has its own `/mcp` endpoint built in, but it is off by default — it registers no route unless `FLAIR_MCP_OAUTH` and a public issuer are set — and no client setup in this guide uses it.) `@tpsdev-ai/flair-client` is a separate package you add to your own project when you want to call Flair from code.
 
 ## 2. Bootstrap Flair and register an agent
 
@@ -110,12 +112,35 @@ flair memory add --agent local "Harper v5 sandbox blocks node:module but process
 {
   "id": "local-1785277247486",
   "written": true,
-  "deduplicated": false
+  "deduplicated": false,
+  "visibility": "private"
 }
 ```
 
 Flair embedded the text locally on write. No network calls.
 
+### Who can read it
+
+`visibility: private` means **only `local` can read this memory** — no other agent on the instance can search it, fetch it by id, or receive it in a bootstrap.
+
+You didn't ask for that, and it isn't a setting you have to remember. Flair derives the default from the memory's **durability**, because how long a memory is meant to last is a good proxy for who it was meant for:
+
+| Durability | Default visibility |
+|---|---|
+| `permanent`, `persistent` | `shared` — a fact or decision worth keeping is worth the team being able to find |
+| `standard`, `ephemeral` — including a bare write with no `--durability` | `private` — working context and scratch state belong to the agent that produced them |
+
+So sharing is a deliberate act, and it takes one flag:
+
+```bash
+flair memory add --agent local --visibility shared \
+  "Release tags are cut from main, never from a release branch"
+```
+
+`--visibility` takes exactly `private` or `shared` — a value it doesn't recognise is an error, not a guess — and overrides the durability rule in both directions. The `visibility` field in the response is the value the memory actually landed on, so read it rather than assuming.
+
+Once a memory is `shared`, **every** agent on this instance can read it, with no grant to set up. That is the shipped model: reads open within one instance, closed at the federation edge. Full picture in [SECURITY.md](../SECURITY.md).
+
 ## 5. Find it back by meaning
 
 ```bash
@@ -131,7 +156,7 @@ You searched for a concept, not the keywords. The line under each hit is its cre
 
 > 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, or `--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.
+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.
 
 ## 6. Give your agent context on boot
 
@@ -160,7 +185,7 @@ With the MCP server wired up — `flair init` does this automatically for every
 | You want to... | Go to |
 |----------------|-------|
 | Add more agents to the same instance | `flair agent add <id>` |
-| Keep a memory owner-only | `flair memory add --visibility private` — reads are otherwise open to every agent on the instance ([auth.md](auth.md)) |
+| Share a memory with your other agents | `flair memory add --visibility shared` — a bare write lands `private`, see [step 4](#who-can-read-it); a shared one is readable by every agent on the instance, no grant needed ([auth.md](auth.md)) |
 | Import memories from agentic-stack / Mem0 / etc. | [bridges.md](bridges.md) |
 | Sync memories across machines | [federation.md](federation.md) |
 | Integrate with OpenClaw, Claude Code, Cursor | [README.md#integration](../README.md#integration) |

package/docs/the-team.md

@@ -15,7 +15,7 @@ If you're trying to run your own multi-agent team using Flair as the memory laye
 | **Pulse** | EA / intel scanning / coordination | OpenClaw | Claude API | cloud VM |
 | **Nathan** | Founder / product owner / human-in-the-loop | (human) | (human) | wherever |
 
-Every agent has its own Ed25519 identity in Flair. They sign every memory write and every read. **Writes are isolated at the Flair API layer** — Sherlock can't accidentally (or maliciously) write into Pulse's memory, because the signature won't verify for anyone but Pulse. Reads are a different story: within one Flair instance, any verified agent can read any other agent's **non-private** memory — that's the shipped model (open-within-org read, no grant needed), not a gap. An agent keeps something genuinely sensitive owner-only by writing it with `visibility: private`. The hard access boundary is the **federation edge** (a separate Flair instance), not reads within one.
+Every agent has its own Ed25519 identity in Flair. They sign every memory write and every read. **Writes are isolated at the Flair API layer** — Sherlock can't accidentally (or maliciously) write into Pulse's memory, because the signature won't verify for anyone but Pulse. Reads are a different story: within one Flair instance, any verified agent can read any other agent's **non-private** memory — that's the shipped model (open-within-org read, no grant needed), not a gap. Which memories are non-private is decided at write time: visibility defaults from durability, so `permanent`/`persistent` writes land `shared` and `standard`/`ephemeral` writes land `private`. A teammate's scratch context is therefore owner-only until someone shares it deliberately, and an agent keeps something genuinely sensitive owner-only regardless of durability by writing it with `visibility: private`. The hard access boundary is the **federation edge** (a separate Flair instance), not reads within one.
 
 ## How memory flows
 
@@ -41,10 +41,14 @@ Every agent has its own Ed25519 identity in Flair. They sign every memory write
                                    │
                        (every agent can read every other
                         agent's non-private memories —
-                        `visibility: private` stays owner-only)
+                        permanent/persistent land shared,
+                        standard/ephemeral land private,
+                        and private stays owner-only)
 ```
 
-No agent can write into another agent's memory — that's enforced server-side by signature verification, no exceptions. Reads are intentionally open within the org: when Flint commits a piece of strategy, any agent can find it on `memory_search` unless Flint marked it `private`. **By design** — the goal is relevance and findability across the team, not secrecy between roles. An agent that genuinely needs something to stay owner-only (a draft not ready for the team, a sensitive finding pre-disclosure) marks it `visibility: private`; everything else is fair game for any teammate to search.
+No agent can write into another agent's memory — that's enforced server-side by signature verification, no exceptions. Reads are intentionally open within the org: when Flint commits a piece of strategy as a `permanent` or `persistent` memory, it lands `shared` and any agent can find it on `memory_search`. **By design** — the goal is relevance and findability across the team, not secrecy between roles.
+
+The reverse also holds, and it is the part worth internalising: a `standard` or `ephemeral` write lands `private`, so an agent's day-to-day working context is *not* team-searchable by default. Commit something at `permanent`/`persistent` durability, or pass `visibility: shared`, when you mean the team to find it. An agent that needs something owner-only whatever its durability (a draft not ready for the team, a sensitive finding pre-disclosure) marks it `visibility: private` explicitly.
 
 When agents need to *coordinate* — a direct, targeted handoff rather than ambient searchable memory — they pass **explicit messages** through TPS mail (a separate signed delivery channel; see [tpsdev-ai/cli](https://github.com/tpsdev-ai/cli)). That's a different concern from memory visibility: TPS mail is for "I need you, specifically, to see this now"; Flair memory is the shared, searchable record everyone (except where `private`) can draw on later.
 
@@ -106,7 +110,7 @@ The MCP server (`@tpsdev-ai/flair-mcp`) is what makes this orchestrator-agnostic
 
 ## What we deliberately don't do
 
-- **No shared write identity.** Every memory is written and owned by exactly one agent's Ed25519 key — there's no merged "team" identity that can write on another agent's behalf. Reads are a separate story: within the org, any agent can search any other's non-private memory by default (see [SECURITY.md](../SECURITY.md)) — that's intentional, not a leak. TPS mail is still how agents route a message to a *specific* teammate; it's for targeted delivery, not for gating ambient visibility.
+- **No shared write identity.** Every memory is written and owned by exactly one agent's Ed25519 key — there's no merged "team" identity that can write on another agent's behalf. Reads are a separate story: within the org, any agent can search any other's non-private memory by default (see [SECURITY.md](../SECURITY.md)) — that's intentional, not a leak. "Non-private" is set at write time from durability, not by a per-pair grant. TPS mail is still how agents route a message to a *specific* teammate; it's for targeted delivery, not for gating ambient visibility.
 - **No silent LLM-driven memory extraction.** Each agent decides what it remembers. No background "summarize and persist" on every turn — that's how memory drifts away from intent.
 - **No multiple agents on one identity.** "Anvil" and "Anvil-2" would be two separate agentIds with two separate keys. Same workload, different identities, separately-owned memories.
 - **No replay-safe-but-otherwise-unsigned reads.** Every Flair request is Ed25519-signed and verified, including reads. Even on a private network we don't trust the network.

package/docs/troubleshooting.md

@@ -104,6 +104,42 @@ date
 
 If using the MCP server, restart Claude Code after rotating keys.
 
+### "signing key ... could not be parsed as an Ed25519 private key"
+
+**Symptoms:** `flair doctor` reports, naming the file:
+
+```
+⚠️ could not verify agent 'my-agent' registration — signing key
+   /home/you/.flair/keys/my-agent.key could not be parsed as an Ed25519 private key
+   (error:1E08010C:DECODER routines::unsupported)
+```
+
+**This is not a connectivity problem.** The failure happens locally, before any
+request is sent — the instance is untouched. Checking ports, firewalls or the
+Flair URL will not help. (Before #1023 doctor reported exactly this as
+`instance unreachable`, and separately suggested passing `--agent`; neither was
+the cause.)
+
+**Causes:** the bytes in that file are not a private key Flair can read. Most
+often either the file is truncated or corrupt, or it is not an agent key at all
+— `~/.flair/keys/<id>.key` is also where the federation keystore writes its own
+**encrypted** key files, which are not loadable as plain Ed25519 seeds.
+
+**Fix:** identify which it is before touching the file — the two have opposite
+remedies, and the wrong one loses a key.
+
+```bash
+# Is this id an agent, or a federation instance?
+flair agent list
+flair federation status
+
+# If it IS an agent and the file is corrupt, re-register a fresh keypair:
+flair agent rotate-key <agent-id>
+```
+
+If the id does not appear as an agent, leave the file alone — it belongs to the
+keystore, and doctor simply has no business signing with it.
+
 ### Port conflict
 
 **Symptoms:** `flair start` fails, "address already in use".
@@ -150,7 +186,7 @@ flair agent list
 **Possible causes:**
 1. **Hash-fallback embeddings:** Check `flair status` — if embeddings are in hash mode, semantic search won't work properly. Fix with `flair reembed`.
 2. **Content safety flags:** The memory might have been flagged. Search for it directly: `flair memory list --agent <id>`.
-3. **`visibility: private`:** Reads are open within the org by default — any agent can find any other agent's non-private memories. If the memory was written with `visibility: private`, only its author can find it; search as that agent instead.
+3. **`visibility: private`:** Only its author can find a `private` memory. This is the most common cause when one agent wrote the memory and another is searching for it, because **`private` is what a bare write lands on**: visibility defaults from durability (`permanent`/`persistent` → `shared`, `standard`/`ephemeral` → `private`), and a write with no `--durability` is `standard`. Check what the memory landed on with `flair memory list --agent <author> --json` (the table view doesn't show visibility, the JSON records do), then either search as its author, or rewrite it with `--visibility shared` so every agent on the instance can find it (no grant needed — non-private reads are open within the instance).
 4. **Dedup threshold:** If the content is very similar to an existing memory, it may have been deduplicated. Check with `flair memory list`.
 
 ### High memory usage

package/package.json

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