@tpsdev-ai/flair 0.46.0 → 0.47.0

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

package/package.json

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