@tpsdev-ai/flair 0.26.0 → 0.27.1

package/dist/resources/migrations/embedding-stamp.js

@@ -60,6 +60,47 @@
  * known, narrow gap this bounded query cannot see;
  * resources/migration-boot.ts mitigates the common case by waiting for the
  * embeddings engine to settle before running migrations at all.
+ *
+ * flair#807 — completion-gate false-negative on 0.10-era / cross-version
+ * stores, root-caused against the installed `@harperfast/harper@5.1.22`
+ * source (node_modules/@harperfast/harper/resources/search.ts): for an
+ * INDEXED attribute (`embeddingModel` IS `@indexed` — schemas/memory.graphql),
+ * a non-negated `not_equal`/`ne` leaf condition takes `searchByIndex`'s
+ * `index && !skipIndex` branch, which reconstructs a SYNTHETIC partial record
+ * from the SECONDARY INDEX KEY alone (`recordMatcher = { [attribute_name]:
+ * key }`, resources/search.ts ~L418) and filters against THAT — never reading
+ * the live record. On a store whose rows were written under flair 0.10.0 /
+ * Harper 5.0.x and later rewritten via `PUT /Memory` (crossing a Harper
+ * 5.0.21→5.1.22 boot), the secondary index for `embeddingModel` can lag the
+ * live, on-disk value — the filter then evaluates a STALE key that never
+ * equals `getCurrentModelId()`, matching every row regardless of its true
+ * (already-current) stamp.
+ *
+ * The fix: use `comparator: "not_equals"` (the `not_` PREFIX form, distinct
+ * from the legacy `not_equal`/`ne` ALIAS — see search.ts's
+ * `resolveComparator`/`NEGATABLE_BASE_COMPARATORS`) for the not-current leg.
+ * `prepareConditions` resolves this to `{comparator: "equals", negated:
+ * true}`, which flips `searchByIndex`'s `skipIndex` flag
+ * (`searchCondition.negated && index && !isPrimaryKey`) — this is Harper's
+ * OWN documented mechanism for "bypass the secondary index, iterate the
+ * primary store directly" (see that file's comment: "we need to consider
+ * records whose attribute value is missing from the index... so we bypass
+ * the secondary index"). That path reads the LIVE record unconditionally,
+ * immune to any index/record divergence regardless of cause (this migration,
+ * a future one, or a Harper-internal index-rebuild timing issue). Strictly
+ * MORE reliable than the index-assisted path in every case — a genuinely
+ * stale row still matches (full scan over live values), so this changes
+ * nothing about the "3/3 success" happy path, only closes the false-positive
+ * gap on migrated stores. The `equals: null` leg is unaffected (not a
+ * negated comparator — no analogous bypass exists or is needed; its
+ * behavior was already verified against real Harper per the doc above).
+ *
+ * `recheckPending()` below is a SEPARATE, generic defense-in-depth layer
+ * (wired into resources/migrations/runner.ts's completion gate) — even a
+ * migration whose countPending() query is airtight can be defeated by some
+ * OTHER, not-yet-understood counting artifact; this lets the runner PROVE
+ * (via `.get()`, a primary-key lookup — always live, never index-assisted)
+ * that a nonzero countPending() result is real before halting on it.
  */
 import { databases } from "@harperfast/harper";
 import { getModelId } from "../embeddings-provider.js";
@@ -115,16 +156,24 @@ async function regenViaHttpPut(id, existing, fetchImpl) {
  */
 export function createEmbeddingStampMigration(getTable = defaultMemoryTable, getCurrentModelId = getModelId, regen = (id, existing) => regenViaHttpPut(id, existing, fetch)) {
     function staleCondition() {
-        // OR-combined: `not_equal <current>` catches a stale non-null model
+        // OR-combined: `not_equals <current>` catches a stale non-null model
         // string; `equals null` catches the explicit-null state this
         // migration's own writes leave behind on a failed regen (see the
         // module doc above — Harper's index never sees a TRULY ABSENT
         // property, only an explicit null).
+        //
+        // "not_equals" (NOT the legacy "not_equal" alias — see the flair#807
+        // addendum in the module doc) is load-bearing: it's the `not_` PREFIX
+        // form Harper's query engine resolves to a `negated: true` leaf, which
+        // bypasses the (on some stores, stale/desynced) secondary index and
+        // reads the live record directly. Reverting this to "not_equal" would
+        // reopen #807 on any store where the embeddingModel index lags the
+        // on-disk value.
         return [
             {
                 operator: "or",
                 conditions: [
-                    { attribute: "embeddingModel", comparator: "not_equal", value: getCurrentModelId() },
+                    { attribute: "embeddingModel", comparator: "not_equals", value: getCurrentModelId() },
                     { attribute: "embeddingModel", comparator: "equals", value: null },
                 ],
             },
@@ -174,5 +223,37 @@ export function createEmbeddingStampMigration(getTable = defaultMemoryTable, get
             }
             return { processed: touchedIds.length, touchedIds };
         },
+        /**
+         * flair#807 completion-gate safety net (resources/migrations/runner.ts
+         * calls this ONLY when a nonzero countPending() would otherwise halt the
+         * migration). Re-derives up to `limit` currently-"pending" ids via the
+         * SAME staleCondition() search countPending() uses, then re-checks each
+         * one by a DIRECT `.get()` — a primary-key lookup, never index-assisted,
+         * so it can't be fooled by the same secondary-index divergence that can
+         * make the search-based count wrong. Returns counts only (never ids —
+         * matches this codebase's structural-only-disclosure discipline, e.g.
+         * resources/migrations/ledger.ts's module doc), so the runner can log a
+         * loud, actionable WARN without ever needing to know which rows.
+         */
+        async recheckPending(limit) {
+            const table = getTable();
+            const current = getCurrentModelId();
+            const ids = [];
+            for await (const row of table.search({ conditions: staleCondition(), limit })) {
+                const id = String(row.id ?? "");
+                if (id)
+                    ids.push(id);
+            }
+            let falsePositives = 0;
+            for (const id of ids) {
+                const existing = await table.get(id);
+                // A row that vanished since the search, OR whose live embeddingModel
+                // still doesn't match current, is a GENUINE pending row (or a
+                // concurrent delete) — never counted as a false positive.
+                if (existing && existing.embeddingModel === current)
+                    falsePositives++;
+            }
+            return { sampled: ids.length, falsePositives };
+        },
     };
 }

package/dist/resources/migrations/runner.js

@@ -44,6 +44,17 @@ import { join } from "node:path";
  * production deployment (gate off) can never alter the real 100ms throttle.
  */
 export const TEST_BATCH_DELAY_ENV = "FLAIR_MIGRATION_TEST_BATCH_DELAY_MS";
+/**
+ * flair#807 completion-gate safety net: the maximum `finalRemaining` count
+ * the gate will EXHAUSTIVELY re-verify (every claimed-pending row, never a
+ * probabilistic subset) via `migration.recheckPending()` before declaring a
+ * halt. Bounded so this stays "cheap" (a per-boot gate check, not a bulk
+ * job) and so the net can only ever flip a gate from fail→pass when it has
+ * proven — not sampled — that the WHOLE remaining set is a counting
+ * artifact. A `finalRemaining` above this threshold skips the net entirely
+ * and halts exactly as before (a partial recheck is not proof for the rest).
+ */
+const GATE_SAFETY_NET_MAX_RECHECK = 50;
 function resolveTestBatchDelayMs(env = process.env) {
     if (!shouldRegisterSyntheticMigration(env))
         return undefined;
@@ -356,6 +367,39 @@ async function runOneMigration(migration, envelope, deps, lock) {
     }
     let hashEnvelopeMatch = null;
     let gateOk = finalRemaining === 0;
+    // ── flair#807 safety net: a nonzero finalRemaining can itself be a
+    // COUNTING ARTIFACT (e.g. countPending()'s search-based query reading a
+    // stale/desynced secondary index on a migrated store — see
+    // resources/migrations/embedding-stamp.ts's flair#807 doc for the
+    // concrete mechanism that motivated this) rather than real pending work.
+    // Only engages when finalRemaining is small enough to verify
+    // EXHAUSTIVELY — every claimed-pending row, not a subset — via a DIRECT
+    // per-row read (migration.recheckPending(), opt-in per Migration type).
+    // If every single one comes back already correct on direct read, the
+    // gate's nonzero count was the bug: log loudly and PASS with a WARN
+    // instead of halting forever on an artifact a real re-run can never
+    // clear (countPending() would report the same wrong number next boot).
+    if (!gateOk &&
+        finalRemaining > 0 &&
+        finalRemaining <= GATE_SAFETY_NET_MAX_RECHECK &&
+        typeof migration.recheckPending === "function") {
+        try {
+            const recheck = await migration.recheckPending(finalRemaining);
+            if (recheck.sampled === finalRemaining && recheck.falsePositives === recheck.sampled) {
+                console.warn(`[migrations] ${migration.id}: completion gate countPending() reported ${finalRemaining} pending, ` +
+                    `but a direct per-record read of ALL ${recheck.sampled} claimed-pending rows found every one already ` +
+                    `correct. Treating this as a counting artifact (search/index divergence), NOT real pending work — ` +
+                    `passing the gate with this WARN instead of halting.`);
+                gateOk = true;
+            }
+        }
+        catch (err) {
+            // The safety net itself must never crash or worsen the gate outcome —
+            // a failure here just leaves gateOk as countPending() computed it.
+            console.warn(`[migrations] ${migration.id}: completion-gate safety net recheckPending() threw (` +
+                `${err?.message ?? String(err)}) — proceeding with the original gate result.`);
+        }
+    }
     if (gateOk && posture.gate === "count+full-envelope") {
         try {
             const postEnvelope = await computeCorpusEnvelope(deps.getTable, deps.now);

package/docs/assets/flair-cross-orchestrator.cast

@@ -0,0 +1,33 @@
+{"version": 3, "term": {"cols": 96, "rows": 28}, "timestamp": 1778889600, "command": "/tmp/flair-cross-orchestrator-script.sh", "env": {"SHELL": "/bin/zsh"}}
+[0.245, "o", "\u001b[H\u001b[J"]
+[0.001, "o", "  Flair  \u00b7  same identity, every orchestrator\r\n  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n\r\n"]
+[1.3, "o", "$ # One agent identity. One memory store. Three orchestrators.\r\n"]
+[1.2, "o", "$ flair init --client all --agent flint\r\n"]
+[0.5, "o", "  \u001b[32m\u2713\u001b[0m Claude Code   wired (~/.claude/mcp.json)\r\n"]
+[0.18, "o", "  \u001b[32m\u2713\u001b[0m Codex CLI     wired (~/.codex/config.toml)\r\n"]
+[0.18, "o", "  \u001b[32m\u2713\u001b[0m Gemini CLI    wired (~/.gemini/settings.json)\r\n\r\n"]
+[1.0, "o", "  Each MCP client now connects to:  http://127.0.0.1:9926\r\n"]
+[0.0, "o", "  Ed25519 keypair shared:           ~/.flair/keys/flint.ed25519\r\n\r\n"]
+[2.2, "o", "$ # \u2500\u2500 Claude Code: agent writes a memory \u2500\u2500\r\n"]
+[0.7, "o", "$ claude\r\n"]
+[0.5, "o", "\u001b[36mflint>\u001b[0m \u001b[2mremember: we picked Postgres for replication-lag reasons; ScyllaDB ruled out by ops complexity\u001b[0m\r\n"]
+[1.8, "o", "  \u001b[32m\u2713\u001b[0m wrote memory mem_2026-05-14_3f9a (durability=persistent)\r\n\r\n"]
+[1.5, "o", "$ # \u2500\u2500 New session. Different orchestrator. Same identity. \u2500\u2500\r\n"]
+[1.0, "o", "$ codex\r\n"]
+[0.5, "o", "\u001b[36mflint>\u001b[0m \u001b[2mwhat database did we pick and why?\u001b[0m\r\n"]
+[1.5, "o", "  \u001b[32m\u2713\u001b[0m bootstrap: 287 memories loaded for agent flint\r\n"]
+[0.4, "o", "  Postgres \u2014 chosen for replication-lag reasons.\r\n"]
+[0.0, "o", "  ScyllaDB was ruled out by ops complexity.\r\n"]
+[0.0, "o", "  \u001b[2m(source: mem_2026-05-14_3f9a, written via Claude Code 4m ago)\u001b[0m\r\n\r\n"]
+[2.0, "o", "$ # \u2500\u2500 New session. Another orchestrator. Same identity. \u2500\u2500\r\n"]
+[1.0, "o", "$ gemini\r\n"]
+[0.5, "o", "\u001b[36mflint>\u001b[0m \u001b[2msummarize our recent infra decisions\u001b[0m\r\n"]
+[1.7, "o", "  \u001b[32m\u2713\u001b[0m bootstrap: same 287 memories, same soul, same Ed25519 identity\r\n"]
+[0.5, "o", "  \u2022 Postgres for replication-lag (2026-05-14)\r\n"]
+[0.0, "o", "  \u2022 Federation pair: local\u2192Fabric via Ed25519 (2026-05-05)\r\n"]
+[0.0, "o", "  \u2022 REM nightly cycle ships in v0.9.0 (2026-05-14)\r\n\r\n"]
+[2.5, "o", "  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n"]
+[0.0, "o", "  No SaaS in the middle.  No vendor lock.\r\n"]
+[0.0, "o", "  Memory follows the agent across orchestrators.\r\n"]
+[0.0, "o", "\r\n  github.com/tpsdev-ai/flair  \u00b7  Apache 2.0\r\n\r\n"]
+[5.0, "x", "0"]

package/docs/assets/flair-demo.cast

@@ -0,0 +1,18 @@
+{"version":3,"term":{"cols":80,"rows":24},"timestamp":1778359292,"command":"/tmp/flair-demo-script.sh","env":{"SHELL":"/bin/zsh"}}
+[0.245, "o", "\u001b[H\u001b[J"]
+[0.001, "o", "  Flair  ·  identity infrastructure for AI agents\r\n  ─────────────────────────────────────────────\r\n\r\n"]
+[1.520, "o", "$ # Agent writes a memory\r\n"]
+[0.628, "o", "$ flair memory add --agent flint-demo --content \"Postgres replication lag spiked when we added the read-replica\"\r\n"]
+[0.796, "o", "{\r\n  \"ok\": true\r\n}\r\n"]
+[1.411, "o", "\r\n"]
+[0.000, "o", "$ # Six months later — find it by meaning, not keywords\r\n"]
+[0.509, "o", "$ flair search \"why did our database fall behind during scaling\" --agent flint-demo\r\n"]
+[0.824, "o", "  Postgres replication lag spiked when we added the read-replica\r\n  (2026-05-09)\r\n"]
+[0.000, "o", "\r\n"]
+[2.054, "o", "\r\n$ # Same memory, every harness.\r\n"]
+[0.630, "o", "$ # Claude Code · Cursor · Codex CLI · Gemini CLI · Continue.dev · Goose\r\n$ #          all via   @tpsdev-ai/flair-mcp\r\n$ # LangGraph         @tpsdev-ai/langgraph-flair\r\n$ # OpenClaw          @tpsdev-ai/openclaw-flair\r\n$ # n8n               @tpsdev-ai/n8n-nodes-flair\r\n$ # Hermes Agent      packages/hermes-flair  (Python)\r\n$ # Pi agent          @tpsdev-ai/pi-flair\r\n"]
+[2.125, "o", "\r\n"]
+[0.000, "o", "  ─────────────────────────────────────────────\r\n"]
+[0.000, "o", "  Apache 2.0  ·  self-hosted  ·  no SaaS in the middle\r\n  github.com/tpsdev-ai/flair\r\n"]
+[0.000, "o", "\r\n"]
+[5.147, "x", "0"]

package/docs/auth.md

@@ -0,0 +1,178 @@
+# Authentication & Authorization
+
+Flair supports three authentication methods, from simplest to most enterprise-ready.
+
+## Auth across surfaces (read this first)
+
+Different surfaces authenticate differently. The model in one place:
+
+| Surface | Auth | Scope | Notes |
+|---------|------|-------|-------|
+| **CLI / SDK clients** (`flair`, `flair-client`) | **Ed25519 per-agent** | Own writes; org-wide non-private reads | Default, recommended. Signs every request; an agent can never write as another, and reads are scoped to its own memories (any visibility) plus every other agent's **non-private** memories on the instance. |
+| **MCP server** (`@tpsdev-ai/flair-mcp`) | **Ed25519 per-agent** | Own writes; org-wide non-private reads | Same per-agent identity as the CLI — key auto-resolved from `~/.flair/keys/<agent>.key`. |
+| **OpenClaw / pi / Hermes plugins** | **Ed25519 per-agent** | Own writes; org-wide non-private reads | Same secure path; auto-detect agent identity. |
+| **`n8n-nodes-flair`** | **Harper admin-password Basic auth** | ⚠️ **Whole instance, read + write, including `private`** | The admin credential bypasses agent scoping entirely — every workflow gets read/write on the *entire* memory store, including other agents' `private`-marked memories, not just the org-wide non-private pool an Ed25519 identity would see. |
+
+**The default, secure path is Ed25519 per-agent** (see below): each agent holds its own key and signs every request. That guarantees **write isolation** — no agent can write as another — and identity-verified reads. It does **not** mean cross-agent reads are refused: within one Flair instance (one org), any verified agent can read any other agent's memory unless that memory is explicitly marked `visibility: private` (owner-only). The hard access boundary is the **federation edge** (a separate Flair instance / org), not reads within an instance. See [SECURITY.md](../SECURITY.md) for the full model. Use Ed25519 per-agent everywhere you can regardless — it's still what makes writes and identity trustworthy.
+
+### Known limitation — n8n uses admin-password Basic auth
+
+The `n8n-nodes-flair` community node authenticates with the Harper **admin password** (Basic auth), which bypasses agent scoping entirely — not just the org-wide non-private reads an Ed25519 identity already gets. Concretely, an n8n workflow using the admin credential can write memories under *any* agent's identity (no per-agent write isolation) and can read *every* memory including ones marked `visibility: private` (which stay owner-only under normal Ed25519 auth). This is acceptable only when **all** of the following hold:
+
+- The n8n instance is single-tenant and operator-controlled.
+- Workflow inputs are trusted (your own CRM, your own webhook source).
+- Write-forgery and full read access (including `private` memories) are acceptable for the use case.
+
+If any of those don't hold, use Flair's CLI / SDK clients (which support per-agent Ed25519 today) and wait for the n8n credential to gain Ed25519 per-agent auth (planned). Full guidance in [docs/n8n.md](n8n.md#security).
+
+## Ed25519 Agent Auth (Default)
+
+Every agent has an Ed25519 key pair. Requests are signed with `agentId:timestamp:nonce:METHOD:/path` and verified against the agent's registered public key. 30-second replay window with nonce deduplication.
+
+```bash
+# Register an agent
+flair agent add myagent
+
+# The key is stored at ~/.flair/keys/myagent.key
+# Requests are signed automatically by flair-client and the MCP server
+```
+
+This is the default and recommended auth for single-instance deployments.
+
+## 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:
+
+- **Personal (the default).** `flair init` mints ONE agent identity and wires that same `FLAIR_AGENT_ID` into every MCP client it configures (Claude Code, Codex, Gemini, Cursor). One human driving several AI clients ends up with one canonical principal and one Ed25519 keypair — all clients share ownership of the same memory. This is intentional, not a limitation: all clients see each other's private rows (one human's memory, one view), a fact re-asserted from two different clients dedups to one memory, and usage counting treats the principal as one contributor.
+- **Org (multiple real agents).** `flair agent add <id>` mints a distinct principal — its own keypair, its own ownership boundary — for each real agent that should be a separate identity. Wire each principal's own `FLAIR_AGENT_ID` into its own client(s).
+
+Nothing in flair validates which shape you're in; a personal install that later grows into an org just runs `flair agent add` for the new distinct identities it needs.
+
+### Authorship: which client wrote a row
+
+The personal shape's one shared principal means `agentId` alone can't answer "was this written by Claude Code or Codex?" — every write it receives has the same owner. `flair init`'s per-client wiring closes that gap by setting an additional env var per client: `FLAIR_CLIENT` (`"claude-code"` / `"codex"` / `"gemini"` / `"cursor"`). `flair-client` and `flair-mcp` forward it on memory writes as `claimedClient`, and the server folds it into the write's `provenance` blob as `claimed.client` — self-reported, unverified metadata recording *which tool* authored a row, alongside the existing `claimed.model`.
+
+This is deliberately in `claimed`, never `verified`: it carries **zero authority**. It is never read for access control, read-scope, attribution weighting, or dedup decisions — it exists purely for audit/analysis. Absent on any install that predates this field (no backfill, no migration) and absent whenever a client doesn't set `FLAIR_CLIENT`.
+
+The native `/mcp` OAuth surface (see below) doesn't need any client-side wiring at all: the handler stamps `claimed.client` directly from the OAuth token's verified `client_id` claim — the server-generated `flair_cl_...` machine id assigned at Dynamic Client Registration, **not** the user-supplied `client_name` (which the registering client fully controls and could set to anything). Using `client_id` keeps the stamp a stable, server-verified label even though it still only carries `claimed`-level (unverified-by-content) authority.
+
+## OAuth 2.1
+
+Flair includes a built-in OAuth 2.1 authorization server for client integrations (e.g., Claude connecting to Flair as an MCP server).
+
+### Dynamic Client Registration
+
+Clients register automatically on first connection:
+
+```
+POST /OAuthRegister
+Content-Type: application/json
+
+{
+  "client_name": "Claude Desktop",
+  "redirect_uris": ["http://localhost:3000/callback"],
+  "grant_types": ["authorization_code"],
+  "response_types": ["code"],
+  "token_endpoint_auth_method": "none"
+}
+```
+
+Returns `client_id` and `client_secret` (if applicable).
+
+### Authorization Code Flow with PKCE
+
+Standard OAuth 2.1 authorization code flow:
+
+1. Client generates PKCE `code_verifier` and `code_challenge`
+2. Client redirects user to `GET /OAuthAuthorize?client_id=...&code_challenge=...&redirect_uri=...`
+3. User approves (or auto-approves for trusted clients)
+4. Flair redirects back with authorization code
+5. Client exchanges code for access token at `POST /OAuthToken`
+
+### Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/OAuthRegister` | POST | Dynamic client registration |
+| `/OAuthAuthorize` | GET/POST | Authorization endpoint |
+| `/OAuthToken` | POST | Token endpoint |
+| `/.well-known/oauth-authorization-server` | GET | Server metadata |
+
+## XAA (Enterprise-Managed Authorization)
+
+For organizations using an Identity Provider (IdP), XAA lets the IdP control who accesses Flair and with what scopes.
+
+### How It Works
+
+1. User authenticates with the organization's IdP (Google, Azure AD, Okta)
+2. IdP issues an ID token (JWT) with user identity and group claims
+3. Client sends the ID token to Flair's token endpoint using the `jwt-bearer` grant type
+4. Flair validates the JWT signature, checks issuer/domain, maps to a Principal, and issues a scoped access token
+
+```
+POST /OAuthToken
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
+&assertion=<id-token-from-idp>
+```
+
+### IdP Configuration
+
+Register an IdP with the CLI:
+
+```bash
+flair idp add \
+  --name "Google Workspace" \
+  --issuer "https://accounts.google.com" \
+  --jwks-uri "https://www.googleapis.com/oauth2/v3/certs" \
+  --required-domain "yourcompany.com"
+```
+
+### Supported IdPs
+
+| IdP | Issuer | Domain Claim |
+|-----|--------|-------------|
+| Google Workspace | `https://accounts.google.com` | `hd` (hosted domain) |
+| Azure AD (Entra) | `https://login.microsoftonline.com/{tenant}/v2.0` | `tid` (tenant ID) |
+| Okta / Auth0 | `https://{org}.okta.com` | Issuer-scoped |
+
+### Scopes
+
+| Scope | Description |
+|-------|-------------|
+| `memory:read` | Read memories and search |
+| `memory:write` | Write and delete memories |
+| `memory:admin` | Memory maintenance operations |
+| `principal:read` | View principal list |
+| `principal:admin` | Create/modify/disable principals |
+| `connector:admin` | Manage OAuth clients and IdPs |
+
+### JIT Provisioning
+
+First-time IdP users are automatically created as `unverified` principals. An admin can promote them to `verified` or `admin` via:
+
+```bash
+flair principal promote <principal-id>
+```
+
+### CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `flair idp add` | Register an IdP |
+| `flair idp list` | List configured IdPs |
+| `flair idp remove <id>` | Remove an IdP |
+| `flair idp test <id>` | Test IdP connectivity |
+
+## Web Admin
+
+The web admin at `/AdminDashboard` provides a UI for managing:
+
+- **Principals:** view, promote, disable agents and users
+- **Connectors:** OAuth clients and active sessions
+- **IdP:** enterprise identity provider configuration
+- **Memory:** browse and search stored memories
+- **Instance:** federation status, peer connections
+
+Access requires admin-level authentication (Basic auth with the Harper admin password).