@tpsdev-ai/flair 0.45.0 → 0.47.0

package/docs/deepseek-harness.md

@@ -0,0 +1,110 @@
+# Flair + DeepSeek Harness (zero-code MCP bridge)
+
+Give DeepSeek Harness (DSH) sessions persistent, portable memory — no plugin code, just one Cordis overlay wiring [`@tpsdev-ai/flair-mcp`](../packages/flair-mcp) through DSH's first-party MCP bridge, [`@deepseek-ai/dsh-mcp-client`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/mcp/mcp-client).
+
+> **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.
+
+Two caveats up front, both structural to DSH's bridge (details below):
+
+1. **DSH scrubs the ambient environment before spawning MCP servers.** Flair's env vars must be declared in the overlay's `config.env` — exported shell vars will not reliably reach the server.
+2. **Recall on this path is reactive.** The model must *choose* to call the memory tools; DSH's MCP bridge cannot inject Flair context at session start. There is a documented mitigation (a persona nudge), but real auto-inject requires a native DSH plugin — planned as phase 2 of [flair#1289](https://github.com/tpsdev-ai/flair/issues/1289).
+
+## Prerequisites
+
+Same as every MCP client — a running Flair and an agent identity. Follow [Step 1 of mcp-clients.md](mcp-clients.md#step-1--install-flair-do-once) (install, `flair init`, `flair agent add <id>`, `flair status`). If DSH runs on a machine that cannot see your Flair instance's loopback address, you need a reachable `FLAIR_URL` — see [quickstart-fabric.md](quickstart-fabric.md).
+
+DSH spawns the server with `npx`, so the machine running DSH needs Node.js 22+ (Flair's own floor).
+
+## The overlay
+
+A ready-to-use copy of this file ships in the repo at [`examples/deepseek-harness/flair.cordis.yml`](../examples/deepseek-harness/flair.cordis.yml):
+
+```yaml
+- insert:
+    - id: memory-flair
+      name: '@deepseek-ai/dsh-mcp-client'
+      config:
+        serverName: flair
+        transport: stdio
+        command: npx
+        args: ['-y', '@tpsdev-ai/flair-mcp@<version>']
+        env:
+          FLAIR_AGENT_ID: <agent-id>
+          FLAIR_URL: http://127.0.0.1:19926
+```
+
+Replace the two placeholders before use:
+
+- `<version>` — pin the flair-mcp version you intend to run (the one you already have is `flair --version`). The [pinning rationale from mcp-clients.md](mcp-clients.md#step-2--wire-the-mcp-server-into-your-cli) applies with extra force here: DSH re-spawns the command per session, so an unpinned spec re-resolves to whatever is currently on npm every time. Leaving the literal `<version>` in place fails loudly at `npx` — intended.
+- `<agent-id>` — the identity you created with `flair agent add`.
+
+`FLAIR_URL` as shown is the local default; point it at your Fabric URL for a remote instance.
+
+Apply it for one run:
+
+```sh
+dsh web --patch "$PWD/examples/deepseek-harness/flair.cordis.yml"
+```
+
+To keep it across runs, merge the single `insert` patch into a user patch layer — `$DSH_HOME/profiles/<name>/cordis.patch.yml` for one profile, or `$DSH_HOME/cordis.patch.yml` machine-wide. Merge into an existing file rather than copying over it; it may already carry unrelated patches.
+
+DSH's own reference memory overlays prefer a preinstalled binary over a package runner ("DSH starts it but does not run a package manager"). If you want that shape: `npm install -g @tpsdev-ai/flair-mcp@<version>`, then `command: flair-mcp` with no `args`.
+
+## Caveat 1 — the bridge scrubs ambient env; declare Flair's env explicitly
+
+Before spawning a stdio MCP server, DSH's bridge builds the child environment from a **scrubbed** copy of the parent env: every variable whose name matches `KEY`, `PASSWORD`, `SECRET`, or `TOKEN` (case-insensitive) is dropped, and so is every `DSH_*` variable. The overlay's `config.env` is merged **after** the scrub, so it is the one reliable channel.
+
+Concretely for Flair:
+
+- `FLAIR_KEY_PATH` contains `KEY` — an exported value is **silently dropped**. If your Ed25519 key is not at the default `~/.flair/keys/<agent>.key`, you must set `FLAIR_KEY_PATH` in `config.env`.
+- `FLAIR_AGENT_ID` and `FLAIR_URL` happen to survive today's scrub pattern, but the pattern is DSH's to change. Declare all three in `config.env` and depend on none of the ambient env.
+
+This mirrors the general rule from [mcp-clients.md troubleshooting](mcp-clients.md#troubleshooting) — a client's own env does not propagate to the spawned MCP subprocess unless declared — DSH just enforces it deliberately.
+
+## Caveat 2 — recall is reactive on this path
+
+DSH's MCP bridge registers **tools** on the model's tool list. That is all it can do: DSH has no first-class memory seam, and the bridge has no way to run `bootstrap` at session start and inject the result into context. Whether memory gets consulted is the model's per-turn decision — identical to the behavior DSH documents for its own reference memory servers.
+
+The documented mitigation is a standing prompt nudge. DSH's deployment persona is the `persona` config key on its `system-prompt` row (agent presets can shadow it with a persona row of their own; there is no end-user prompt-editing API — prompt text is config/composition only). Add something like:
+
+> At the start of a task, call `mcp__flair__bootstrap` or `mcp__flair__memory_search` to load relevant memory before planning. When you make a decision worth keeping, or the user asks you to remember something, record it with `mcp__flair__memory_store`.
+
+This is additive guidance in the shape DSH's own memory examples recommend, and it works — but it is a nudge, not a guarantee. **Honest limitation:** automatic session-start injection (what Flair's Claude Code `SessionStart` hook does) requires a native DSH plugin using their per-turn system-prompt context seam. That is phase 2 of [flair#1289](https://github.com/tpsdev-ai/flair/issues/1289); until it ships, this wiring gives pull-based memory only.
+
+## Tools-only bridging
+
+DSH bridges MCP **tools** only — Resources and Prompts are explicitly not bridged (a documented DSH limitation, not a Flair one). This costs nothing here: `flair-mcp` is a tools-only server, so its entire surface crosses the bridge.
+
+## Verify your wiring
+
+Initial tool discovery is asynchronous — wait until the `mcp__flair__*` tools appear in the session's tool list before the first prompt. Then run the write → fresh-session → recall check (the same protocol shape DSH uses to validate its own reference memory servers):
+
+1. In DSH session A, ask: *"Remember that my validation drink is lapsang-`<unique suffix>`."* Confirm the model calls `mcp__flair__memory_store` and the tool reports success.
+2. Open DSH session B in the same running Host — do not copy session A's conversation. Ask: *"What is my validation drink? Check memory."* Confirm the model calls `mcp__flair__memory_search` and returns the value.
+3. Still in session B, ask it to *use* the recalled value ("suggest one drink for the meeting"). Confirm the answer builds on it.
+
+A new DSH session is enough; a Host restart is not. Because the memory now lives in Flair rather than a local file, the same check also passes *across harnesses*: store in DSH, then `memory_search` from Claude Code or any other [MCP client](mcp-clients.md) pointed at the same Flair instance and agent.
+
+## Config reference (the fields this wiring uses)
+
+Field names verified against DSH `master` 2026-08-20; [their table](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/mcp/mcp-client/README.md) is authoritative.
+
+| Field | Value here | Notes |
+|---|---|---|
+| `serverName` | `flair` | Namespace for tool names (`mcp__flair__*`); must be unique across live instances |
+| `transport` | `stdio` | flair-mcp is a stdio server |
+| `command` / `args` | `npx` / `['-y', '@tpsdev-ai/flair-mcp@<version>']` | Or a preinstalled `flair-mcp` binary |
+| `env` | `FLAIR_AGENT_ID`, `FLAIR_URL`, optionally `FLAIR_KEY_PATH` | Merged after DSH's env scrub — the only reliable channel (see caveat 1) |
+| `toolCallTimeoutMs` | (default 60000) | Per-tool-call timeout; raise it only if slow remote searches genuinely exceed a minute |
+
+## Troubleshooting
+
+**"FLAIR_AGENT_ID is required" on startup.** The env block is missing or ambient-only — declare it in `config.env` (caveat 1).
+
+**Tools never appear.** DSH logs initial connection and discovery failures; by default a failed startup registers no tools rather than failing the plugin. Check `flair status` on the Flair side, and check the DSH logs for the `flair` server's connect errors. A duplicate `serverName: flair` across live instances fails the later instance at load.
+
+**`auth_error` on every call.** Identity/key mismatch — and remember that an exported `FLAIR_KEY_PATH` never reaches the server (caveat 1). Re-run `flair agent add <id>` (idempotent) or set `FLAIR_KEY_PATH` in `config.env`.
+
+For everything else: [troubleshooting.md](troubleshooting.md).

package/docs/entity-vocabulary.md

@@ -89,6 +89,21 @@ Per the attention-plane spec's K&S-approved refinements, `entities: [String] @in
 Existing rows on all three tables simply carry no `entities` — readers must tolerate absence,
 the same pattern already used for `Presence.activityUpdatedAt`. No migration, no backfill.
 
+All three fields are reachable from the CLI (flair#1288): `flair memory add`,
+`flair workspace set`, and `flair orgevent` take `--entities <csv>`, a comma-separated list of
+vocabulary strings:
+
+```bash
+flair memory add --agent flint --entities "repo:tpsdev-ai/flair,issue:tpsdev-ai/flair#1288" "shipped the entities CLI surface"
+```
+
+The CLI validates each value before writing (a malformed value is rejected with the
+`type:value` format and the valid type list); the server re-validates on every write path
+regardless. The CLI's validator is an inlined copy of this module
+(`src/lib/entity-vocab-cli.ts` — `src/` can't import across the packaging boundary into
+`resources/`), pinned to it by `test/unit/cli-entities-option.test.ts`; the server-side gate
+remains this module alone.
+
 `Relationship` gets **no** `entities` field: its `subject`/`object` columns already carry
 free-form entity-reference strings and are already indexed — they're the vocabulary carrier
 for that table. They are lowercased on write today but not yet validated against this

package/docs/integrations.md

@@ -17,6 +17,7 @@ Where Flair already runs. Each integration shown here is a working surface — t
 | **Gemini CLI** | [`flair-mcp`](#claude-code-cursor-codex-gemini-cli-continuedev-via-flair-mcp) | MCP config | Standard MCP server |
 | **Antigravity CLI** (`agy`) | [`flair-mcp`](#claude-code-cursor-codex-gemini-cli-continuedev-via-flair-mcp) | MCP config | `~/.gemini/config/mcp_config.json`; pickup by a live `agy` pending verification |
 | **Goose** (block/goose) | [`flair-mcp`](#claude-code-cursor-codex-gemini-cli-continuedev-via-flair-mcp) | MCP config | Goose ships native MCP support |
+| **DeepSeek Harness** (`dsh`) | [`flair-mcp`](deepseek-harness.md) | Cordis overlay | First-party MCP bridge; tools-only, reactive recall — [dedicated page](deepseek-harness.md) |
 | **LangGraph (TS)** | [`langgraph-flair`](#langgraph-typescript) | FlairClient | Drop-in `BaseStore` |
 | **OpenClaw** | [`openclaw-flair`](#openclaw) | Ed25519 | Native plugin + context engine |
 | **n8n** | [`n8n-nodes-flair`](#n8n) | FlairApi credential | Three nodes (chat memory, search, store) |

package/docs/mcp-clients.md

@@ -30,6 +30,8 @@ flair agent add my-project
 flair status
 ```
 
+> **`flair: command not found` right after installing?** Your npm global prefix's bin dir isn't on PATH (common with a user prefix like `~/.npm-global`) — run `export PATH="$(npm prefix -g)/bin:$PATH"`, persist that line in your shell profile, and `flair doctor` will print the exact line for your shell any time.
+
 Flair runs as a local server at `http://127.0.0.1:19926` by default. The MCP server connects to it on demand via Ed25519-signed requests; nothing leaves your machine unless you explicitly route to a remote Flair instance.
 
 ---
@@ -244,6 +246,8 @@ Which memories are non-private is decided at write time, and the default is not
 
 `bootstrap` returns the canonical structured containers — `soul`, `memories`, `predicted`, `teammateFindings`, `events` — plus counts and a `tokenEstimate`. The containers are **always present** (empty `[]`/`{}` when there's nothing), so an empty container is distinguishable from an unsupported one.
 
+**The token ledger reconciles `tokenEstimate` from the payload alone (flair#1270).** Every token-charged content class carries a counter — `soulTokens`, `memoryTokens`, `trustTokens`, `eventsTokens` — plus a measured `scaffoldTokens` for the fixed JSON frame, and `tokenEstimate ≈ scaffoldTokens + soulTokens + memoryTokens + trustTokens + eventsTokens`. The remaining ≈ gap is the bounded per-item difference between the prose lines the memory counters measure and the heavier structured objects the containers ship. A payload whose estimate an agent can't decompose from the reported figures is a bug, not an accounting convention.
+
 **Empty containers say why they're empty (flair#1182).** When a structured container ships empty, the payload carries a short hint naming the reason and what fills it — `eventsHint`, `teammateFindingsHint`, `predictedHint`. This is present *only* when the container is empty, so a deliberately-empty container is never confused with a silent drop (a connector never has to diff against a previous payload to tell the two apart).
 
 **`matchQuality` is null on lifecycle sections — by design (flair#1225).** With `includeTrust: true`, each included memory carries a per-memory trust block, section-tagged, whose `matchQuality` is a `strong`/`moderate`/`breadcrumb` confidence band. On the **lifecycle sections** (`permanent`, `recent`, `predicted`) `matchQuality` is `null`: those are a lifecycle-window *load*, not a retrieval surface, so there is no relevance score to band. This is **correct, not a scoring failure** — an own-recent `null` next to a teammate's band does not mean your own records "scored worse". A retrieval band is only meaningful on the retrieval sections (`relevant`, `teammate`). The entry's `section` field makes this legible, and a `matchQualityNote` on any null entry states the reason inline.

package/docs/notes/mcp-oauth-model2.md

@@ -46,6 +46,48 @@ context, so the wrapped handler scopes to the verified agent exactly as an
 Ed25519-signed REST call would. Identity always comes from the resolved agent,
 never from the tool arguments (no forging of agentId / authorId).
 
+### Which Agent is my connector? (distinct-by-default — flair#1280)
+
+**The connector's Agent is whatever the `Credential(kind:"idp")` mapping says
+— and that is NOT constrained to be your CLI agent.** Distinct identities are
+the ruled default (flair#1280): per-purpose connector identities are the
+product pattern for org/service installs, and same-identity is a deliberate
+opt-in, never something the server infers. The practical consequences:
+
+- **Where the mapping is decided.** `flair mcp enable --principal <agent-id>
+  --idp-subject <sub>` (the identity-mapping step, backed by
+  `provisionIdpIdentityMapping`) writes the mapping. The `--principal` you pass
+  is the Agent every `/mcp` call will read and write as. Pass an EXISTING
+  agent id to attach the sub to it; the step's output states the resulting
+  `sub → Agent` mapping in as many words.
+- **Linking a sub to an existing Agent (the same-identity opt-in).** Re-run
+  `flair mcp enable` with the SAME `--idp-provider`/`--idp-subject` and
+  `--principal <your-cli-agent-id>`. The existing `(provider, subject)`
+  Credential is RE-POINTED to that principal — one Credential row per subject,
+  so resolution stays deterministic. The link *replaces* the mapping; it does
+  not merge the two agents' memories.
+- **First diagnostic: ask the server who you are.** The `bootstrap` tool's
+  response always carries the resolved `agentId` and a `scope` descriptor
+  (`scope.agentId` / `scope.isAdmin` / `scope.reads`, flair#1182). "My memory
+  is empty over the connector" + a `bootstrap.agentId` you don't recognize =
+  the sub resolved to a different (often JIT-provisioned) Agent — link it as
+  above.
+- **JIT caveat.** A JIT-provisioned mapping (`FLAIR_MCP_JIT_PROVISION=1`)
+  stamps `idpProvider: "mcp-oauth"`. Runtime resolution matches on
+  `(kind, idpSubject)` only, but the *linking* upsert matches on
+  `(kind, idpProvider, idpSubject)` — so when re-linking a JIT-provisioned
+  sub, pass `--idp-provider mcp-oauth` (matching the JIT stamp), or first
+  revoke the JIT credential (`status: "revoked"`). Linking under a different
+  provider name creates a SECOND active credential for the same subject, and
+  which one wins resolution is unspecified.
+
+The two-identity contract (a distinct connector agent sees other agents'
+org-non-private rows, never their private rows, 404-never-403 by id; a linked
+connector sees exactly what the linked agent sees) is pinned end-to-end by
+`test/integration/mcp-connector-principal-mapping.test.ts`, which drives the
+real `mcpHandler`/`resolveAgentFromSub` against a real store with two
+registered identities.
+
 ## Enabling (operator checklist)
 
 1. **Install the AS plugin** — add `@harperfast/oauth` (already an exact-pinned
@@ -59,9 +101,12 @@ never from the tool arguments (no forging of agentId / authorId).
          clientId: ${OAUTH_GITHUB_CLIENT_ID}
          clientSecret: ${OAUTH_GITHUB_CLIENT_SECRET}
      mcp:
-       enabled: true
+       enabled: ${FLAIR_MCP_OAUTH}          # whole-token env reference (flair#1152) — the choice lives in the ENVIRONMENT, so a re-packed deploy can't revert it
        issuer: ${FLAIR_MCP_ISSUER}          # pin to your public origin — REQUIRED
-       resource: ${FLAIR_MCP_ISSUER}/mcp     # RFC-8707 audience the /mcp token binds to
+       # NO resource key (flair#1180): the plugin derives <issuer>/mcp when it is
+       # absent. A composite like ${FLAIR_MCP_ISSUER}/mcp never interpolates
+       # (whole-token-only expansion) and fails every connect with
+       # invalid_target. Non-standard resource: set an explicit LITERAL URL.
        accessTokenTtl: 900                    # 5–15 min (Sherlock req 1) — short-lived
        dynamicClientRegistration:
          enabled: false                       # DCR is NOT SUPPORTED (flair#756) — explicit, not omitted (an absent block leaves DCR OPEN by the plugin's own default)
@@ -82,7 +127,11 @@ never from the tool arguments (no forging of agentId / authorId).
    turning the surface on.
 
 2. **Set the env:**
-   - `FLAIR_MCP_OAUTH=1` — turns on the `/mcp` route registration.
+   - `FLAIR_MCP_OAUTH=true` — turns on the `/mcp` route registration AND the
+     component AS (flair#1152: `true` is the ONE value both readers accept —
+     flair's flag takes 1/true/yes/on, but the component's config read of the
+     same var accepts only "true"/"false" and deletes anything else, so `1`
+     gives you a guarded `/mcp` with no authorization server behind it).
    - `FLAIR_MCP_ISSUER=https://your-public-origin` (or `FLAIR_PUBLIC_URL`).
    - `FLAIR_MCP_JIT_PROVISION=1` — ONLY if you want unknown subjects
      auto-provisioned (default OFF; pre-provision Agent+Credential otherwise).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.45.0",
+  "version": "0.47.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",
@@ -47,12 +47,13 @@
   "scripts": {
     "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
     "prebuild": "npm run clean",
-    "build": "tsc -p tsconfig.json --noCheck",
-    "build:cli": "tsc -p tsconfig.cli.json --noCheck",
+    "build": "tsc -p tsconfig.json --noCheck && node scripts/write-build-info.mjs",
+    "build:cli": "tsc -p tsconfig.cli.json --noCheck && node scripts/write-build-info.mjs",
     "prepublishOnly": "npm run build && npm run build:cli",
     "test": "bun test",
     "test:e2e": "playwright test",
-    "release": "./scripts/release.sh"
+    "release": "./scripts/release.sh",
+    "postinstall": "node -e \"try{require('./dist/postinstall.cjs')}catch(e){}\""
   },
   "publishConfig": {
     "access": "public"

package/schemas/memory.graphql

@@ -219,4 +219,16 @@ type MemoryCandidate @table(database: "flair") @export {
                                    # evidence and would promote tagless (a cross-user leak). Nullable/additive —
                                    # pre-#1205b candidates and non-tagged (scope:"recent"/"all") distillations
                                    # read null, unchanged behavior (clean-upgrade-path gate).
+  visibilityRuling: String         # flair#1257 slice 3: the distiller's AFFIRMATIVE visibility ruling for the
+                                   # promoted row — only ever "shared", and only stamped (resources/memory-
+                                   # reflect-lib.ts buildStagedCandidateRow) when the ruling arrived WITH a
+                                   # non-empty team-relevance justification. Promotion (resources/auto-promote-
+                                   # lib.ts decidePromotedVisibility) re-verifies all three conditions
+                                   # (continuity scopeTag + this ruling + visibilityRationale) and defaults
+                                   # "private" otherwise — default-private-unless (Sherlock): a shared promoted
+                                   # row must always trace to a recorded justification, never to a default.
+                                   # Nullable/additive — pre-slice-3 candidates read null ⇒ private, unchanged.
+  visibilityRationale: String      # flair#1257 slice 3: the team-relevance justification paired with
+                                   # visibilityRuling — the auditable "why shared" recorded on the candidate.
+                                   # Nullable/additive, same clean-upgrade contract as scopeTag above.
 }

package/templates/bin/flair-federation-sync.sh.tmpl

@@ -25,4 +25,11 @@ if [ -n "${FLAIR_ADMIN_PASS_FILE:-}" ] && [ -f "${FLAIR_ADMIN_PASS_FILE}" ]; the
   set -- "$@" --admin-pass-file "${FLAIR_ADMIN_PASS_FILE}"
 fi
 
-exec "{{FLAIR_BIN}}" federation sync "$@"
+# Run the CLI under node rather than exec-ing it directly: `node <script>`
+# needs READ permission only, so the shim keeps working when a deploy method
+# (npm-pack tarball extraction) strips the exec bit from the script (#1231).
+# NODE_BIN is an ABSOLUTE path resolved at enable time — the shim performs
+# zero PATH lookups at run time, exactly like the old absolute-FLAIR_BIN
+# form. Do not replace it with a bare `node`: that would hand binary
+# selection to whatever PATH the service manager happens to carry.
+exec "{{NODE_BIN}}" "{{FLAIR_BIN}}" federation sync "$@"

package/templates/bin/flair-rem-nightly.sh.tmpl

@@ -5,5 +5,12 @@
 #
 # Single line that invokes the CLI's run-once subcommand — the runner module
 # does all the work. Logs land in {{HOME}}/.flair/logs/.
+#
+# Run the CLI under node rather than exec-ing it directly: `node <script>`
+# needs READ permission only, so the shim keeps working when a deploy method
+# (npm-pack tarball extraction) strips the exec bit from the script (#1231).
+# NODE_BIN is an ABSOLUTE path resolved at enable time — the shim performs
+# zero PATH lookups at run time. Do not replace it with a bare `node`: that
+# would hand binary selection to whatever PATH the service manager carries.
 set -e
-exec {{FLAIR_BIN}} rem nightly run-once
+exec "{{NODE_BIN}}" "{{FLAIR_BIN}}" rem nightly run-once