@tpsdev-ai/flair 0.51.1 → 0.52.0

package/dist/src/rem/promote-policy.js

@@ -0,0 +1,204 @@
+// Pure promotion policy shared by the CLI and trusted server workflow.
+export function validatePromoteOpts(opts) {
+    if (!opts.rationale || !opts.rationale.trim()) {
+        return "--rationale is required (per spec § 5: no rubber-stamp)";
+    }
+    if (!opts.to || (opts.to !== "soul" && opts.to !== "memory")) {
+        return "--to must be 'soul' or 'memory'";
+    }
+    if (opts.to === "soul" && (!opts.key || !opts.key.trim())) {
+        return "--key is required when --to=soul (gives the Soul entry a meaningful identifier)";
+    }
+    return null;
+}
+export function validateRejectOpts(opts) {
+    if (!opts.reason || !opts.reason.trim()) {
+        return "--reason is required";
+    }
+    return null;
+}
+/**
+ * Decide whether a promote/reject action can proceed against a candidate's
+ * current state, and what message to surface to the operator. Pure function;
+ * action side effects happen in the CLI body after this returns ok.
+ */
+export function decideCandidateAction(candidate, action) {
+    if (!candidate)
+        return { ok: false, severity: "error", message: "candidate not found" };
+    const status = candidate.status;
+    if (status === "promoted") {
+        return action === "promote"
+            ? { ok: false, severity: "error", message: `already promoted (target=${candidate.target}, reviewer=${candidate.reviewerId})` }
+            : { ok: false, severity: "error", message: `already promoted; cannot reject after promotion` };
+    }
+    if (status === "rejected") {
+        return action === "reject"
+            ? { ok: false, severity: "info", message: `already rejected on ${candidate.decidedAt} by ${candidate.reviewerId}` }
+            : { ok: false, severity: "error", message: `already rejected; use a fresh candidate or reset status manually` };
+    }
+    return { ok: true };
+}
+// ─── ADK tag-lineage on promote (#1205 slice 1205a — Sherlock security req) ───
+// ADK session records are written by adk-flair (memory_service.py) under a
+// SHARED-namespace agentId, with per-user separation carried ENTIRELY by a
+// compound scope tag `adk:<app>:<user>`. That tag is the access-control
+// boundary. A candidate distilled from those records therefore MUST carry the
+// scope tag when promoted, or the promoted claim lands in the shared agentId
+// memory retrievable by every other user of the app — a cross-user leak.
+//
+// `rem promote` historically hard-coded `["nightly-rem-promoted", from:<id>]`
+// and DROPPED the source tag. We now propagate the source scope tag for
+// ADK-sourced candidates, and FAIL CLOSED (refuse) when a candidate is
+// ADK-sourced but its scope tag can't be uniquely+completely determined.
+//
+// SCOPING (deliberate, per spec): fail-closed applies ONLY to ADK-sourced
+// candidates. Non-ADK candidates carry no `adk:` tag and promote byte-for-byte
+// as before — a transient/deleted source on a non-ADK candidate must NOT block
+// its promotion.
+//
+// SEAM (foundation only; the distillation engine is slice #1205b): ADK-sourcing
+// is detected here by re-reading the candidate's source memories and inspecting
+// their tags. That leaves ONE residual fail-open: an ADK-sourced candidate all
+// of whose source memories are unreadable (deleted/transient) yields no `adk:`
+// evidence and is treated as non-ADK. Closing that corner without regressing
+// non-ADK promotion requires the ENGINE to stamp the authoritative scope tag
+// onto the MemoryCandidate row at distillation time (it distills per single
+// scope:tagged tag, so it knows it authoritatively). `derivePromotedTags` is
+// written so that override can be threaded in later without touching callers.
+export const ADK_SCOPE_TAG_PREFIX = "adk:";
+/**
+ * Decide the tag set for a promoted Memory given the candidate id and the
+ * result of fetching each of its source memories. Pure — no I/O; the action
+ * callback does the fetching and threads the results here so this is unit-
+ * testable and the fail-closed logic is exercised directly.
+ *
+ * `stampedScopeTag` (#1205b-1 — the engine slice the #1205a SEAM note below
+ * anticipated): the authoritative scope:"tagged" tag the distillation engine
+ * stamped onto the MemoryCandidate row (resources/MemoryReflect.ts →
+ * buildStagedCandidateRow). When present it is AUTHORITATIVE and short-circuits
+ * the source re-read entirely — the engine distilled under exactly this one
+ * tag, so it knows the per-user scope tag independent of whether the source
+ * memories are still readable. This closes the residual fail-open the SEAM
+ * note describes: a candidate all of whose sources are unreadable yields no
+ * `adk:` evidence and would otherwise be mis-classified NON-ADK and promoted
+ * tagless into the shared agentId namespace (a cross-user leak). Threading it
+ * in as an optional trailing arg keeps every pre-#1205b caller (and every
+ * candidate that never carried a stamp) on the unchanged source-re-read path.
+ *
+ * With NO stamp (undefined/empty) the source-re-read classification runs
+ * exactly as in #1205a:
+ *  - No `adk:` scope tag across readable sources → NON-ADK candidate; return
+ *    the provenance tags only (unchanged behavior).
+ *  - Exactly one `adk:` scope tag AND every source readable → ADK-sourced;
+ *    return [scopeTag, ...provenance].
+ *  - `adk:` evidence present but the scope tag is ambiguous (>1 distinct tag)
+ *    OR incomplete (some source unreadable) → REFUSE (fail-closed): a
+ *    tagless/mis-tagged claim in a shared ADK namespace is a cross-user leak,
+ *    not a benign miss.
+ */
+export function derivePromotedTags(candidateId, sources, stampedScopeTag) {
+    const provenance = ["nightly-rem-promoted", `from:${candidateId}`];
+    // #1205b-1: a stamped scope tag is AUTHORITATIVE — consume it directly, never
+    // re-read sources. This is the seam closure: correctness no longer depends on
+    // source readability. `adkSourced` (which gates the Soul-promotion refusal in
+    // the promote action) tracks whether the stamped tag is an ADK scope tag.
+    if (typeof stampedScopeTag === "string" && stampedScopeTag.length > 0) {
+        return {
+            ok: true,
+            tags: [stampedScopeTag, ...provenance],
+            adkSourced: stampedScopeTag.startsWith(ADK_SCOPE_TAG_PREFIX),
+        };
+    }
+    const adkTags = new Set();
+    let anySourceUnreadable = false;
+    for (const s of sources) {
+        if (!s.ok) {
+            anySourceUnreadable = true;
+            continue;
+        }
+        for (const t of s.tags) {
+            if (typeof t === "string" && t.startsWith(ADK_SCOPE_TAG_PREFIX))
+                adkTags.add(t);
+        }
+    }
+    // No positive ADK evidence → non-ADK. An unreadable source with zero ADK
+    // evidence does NOT fail closed here (that would regress non-ADK promotion);
+    // see the SEAM note above.
+    if (adkTags.size === 0) {
+        return { ok: true, tags: provenance, adkSourced: false };
+    }
+    if (adkTags.size > 1) {
+        return {
+            ok: false,
+            reason: `ADK-sourced candidate spans multiple scope tags (${[...adkTags].sort().join(", ")}); refusing to promote — a merged cross-user claim would leak across users`,
+        };
+    }
+    if (anySourceUnreadable) {
+        return {
+            ok: false,
+            reason: `ADK-sourced candidate has unreadable source memories; the per-user scope tag cannot be confirmed — refusing to promote (fail-closed)`,
+        };
+    }
+    const scopeTag = [...adkTags][0];
+    return { ok: true, tags: [scopeTag, ...provenance], adkSourced: true };
+}
+// ─── Promoted-row visibility (flair#1257 slice 3 — default-private-unless) ────
+// Continuity-journal scope tag prefix. Canonical string duplicated in
+// resources/memory-reflect-lib.ts / resources/auto-promote-lib.ts and
+// packages/flair-mcp/src/continuity.ts — this file sits on the CLI side of the
+// npm-packaging boundary (see this file's header) and cannot import them; kept
+// in sync by the shared canonical string, same discipline as
+// MACHINE_REVIEWER_* below.
+export const CONTINUITY_SCOPE_TAG_PREFIX = "adk:continuity:";
+/**
+ * Decide a promoted Memory row's visibility for the HUMAN `rem promote` path
+ * (flair#1257 slice 3). Mirror of resources/auto-promote-lib.ts
+ * decidePromotedVisibility (the server-side auto-promote half) — Sherlock's
+ * default-private-unless ruling covers BOTH promotion paths: the sources of a
+ * continuity candidate are the most sensitive tier (ephemeral+private journal
+ * rows), so leaving visibility unset here would let Memory's durability-keyed
+ * default widen it to shared ("persistent" defaults shared) — a silent
+ * visibility escalation. "shared" only when the candidate is continuity-scoped
+ * AND carries the distiller's affirmative ruling WITH its recorded
+ * team-relevance justification; every other case — including every
+ * uncertainty — is "private".
+ *
+ * Returns undefined for NON-continuity candidates: their visibility behavior
+ * (durability-keyed default) is byte-for-byte the pre-slice-3 contract and is
+ * deliberately not changed here.
+ */
+export function derivePromotedVisibility(candidate) {
+    const scopeTag = candidate.scopeTag;
+    const isContinuity = typeof scopeTag === "string" &&
+        scopeTag.length > CONTINUITY_SCOPE_TAG_PREFIX.length &&
+        scopeTag.startsWith(CONTINUITY_SCOPE_TAG_PREFIX);
+    if (!isContinuity)
+        return undefined;
+    if (candidate.visibilityRuling !== "shared")
+        return "private";
+    const rationale = typeof candidate.visibilityRationale === "string" ? candidate.visibilityRationale.trim() : "";
+    return rationale.length > 0 ? "shared" : "private";
+}
+// ─── Machine reviewer namespace (#1205 slice 1205a — Sherlock security req 4) ─
+// A promotion records a reviewerId that feeds audit/attribution
+// (schemas/memory.graphql:209). An automated (machine-driven) promotion path
+// must record a reviewerId that can NEVER be mistaken for a human/agent
+// reviewer, so attribution isn't laundered. Reserve the `machine:` namespace
+// for that, and forbid the human `--reviewer` path from claiming it.
+export const MACHINE_REVIEWER_PREFIX = "machine:";
+/** Canonical machine reviewerId for the ADK auto-promote consumer (#1205b). */
+export const MACHINE_REVIEWER_ADK_AUTO_PROMOTE = "machine:adk-auto-promote";
+/** True iff `id` is in the reserved machine-reviewer namespace — i.e. it
+ *  denotes an automated path, not a human or agent reviewer. */
+export function isMachineReviewerId(id) {
+    return typeof id === "string" && id.startsWith(MACHINE_REVIEWER_PREFIX);
+}
+/** The human `flair rem promote` path must not record a reviewerId in the
+ *  reserved machine namespace — that would launder automated attribution onto
+ *  a human-operated promotion. Returns an error string, or null if allowed. */
+export function validateHumanReviewerId(reviewerId) {
+    if (isMachineReviewerId(reviewerId)) {
+        return `--reviewer '${reviewerId}' uses the reserved '${MACHINE_REVIEWER_PREFIX}' namespace (reserved for automated promotion); use a human/agent reviewer id`;
+    }
+    return null;
+}

package/docs/api-reference.md

@@ -0,0 +1,374 @@
+# API & schema reference
+
+Consolidated catalog of Flair's HTTP surface, per-resource auth, and GraphQL
+table schemas. Narrative lives in the topic docs; this page is the map so an
+adopter does not have to read `resources/` or `schemas/` to see what is
+callable.
+
+- **Auth model:** [docs/auth.md](auth.md), [SECURITY.md](../SECURITY.md)
+- **Access invariant:** [DESIGN.md](../DESIGN.md) — open within the org, closed
+  at the federation edge
+- **Federation pairing and sync:** [docs/federation.md](federation.md)
+- **Source of truth for tables:** [`schemas/*.graphql`](../schemas/)
+- **Source of truth for policy:** [`resources/record-types.ts`](../resources/record-types.ts)
+
+The [docs-freshness gate](../scripts/docs-freshness-check.mjs) (`api-reference-schema-coverage`)
+fails when a GraphQL `@table` type is missing from this file, so a new table
+cannot land undocumented.
+
+Default REST port is `19926` (`DEFAULT_PORT` in `src/cli.ts`). Override with
+`--port` / `HTTP_PORT`. Sign remote requests as
+`agentId:timestamp:nonce:METHOD:/path?query` and send
+`Authorization: TPS-Ed25519 <agentId>:<ts>:<nonce>:<sig>`. Protocol detail is
+in [SECURITY.md](../SECURITY.md).
+
+## How Harper maps resources to URLs
+
+Flair is a Harper application. Two things become HTTP paths:
+
+1. **`@table @export` in GraphQL** — Harper generates REST CRUD at
+   `/<TypeName>` and `/<TypeName>/<id>` (GET collection / GET by id / POST /
+   PUT / PATCH / DELETE). Flair resource classes override those verbs to add
+   identity gates, read-scope, and write policy.
+2. **`export class Foo extends Resource`** in `resources/` — Harper mounts the
+   class name as `/Foo`. Custom verbs are whatever the class implements
+   (`post()` for actions, `get()` for reads).
+
+In-process callers use `server.resources.get("Memory")` (no leading slash).
+See [docs/embedding-in-a-harper-app.md](embedding-in-a-harper-app.md).
+
+`@table` types **without** `@export` have no REST surface. They are listed in
+the schema section so the catalog is complete.
+
+## Auth classes
+
+| Class | Credential | Typical grant |
+|-------|------------|---------------|
+| **Public** | none | Discovery, health, OAuth well-known, Presence roster (field-allowlisted) |
+| **Ed25519 agent** | `TPS-Ed25519` header | Default agent path. Writes as self only. Reads follow the resource's read-scope (below). |
+| **Admin Basic** | Harper `HDB_ADMIN_PASSWORD` / `FLAIR_ADMIN_PASSWORD` | Whole-instance operator. Bypasses agent scoping, including `private` memory. Used by the web admin and `n8n-nodes-flair`. |
+| **Operator / internal** | Admin Basic, or a deliberate `internalContext()` call inside the process | Soul mutations and `AgentSeed`. Agent Ed25519 keys — including admin-agent keys — cannot author Soul. |
+| **Federation body-sig** | Ed25519 over the request body + timestamp/nonce; pairing uses a one-time token | `/FederationPair`, `/FederationSync`. Harper role gate is open; the handler is the auth boundary. |
+| **OAuth bearer** | Access token from Flair's AS or `@harperfast/oauth` | `/mcp` only, and only when `FLAIR_MCP_OAUTH=true` plus a public issuer. Off by default (path 404s). |
+
+Anonymous HTTP is denied on every agent-facing table. A by-id miss and a
+by-id deny both return **404**, never 403, so ids are not an existence oracle.
+
+### Read-scope vocabulary
+
+From `RECORD_TYPES` in `resources/record-types.ts`:
+
+| Scope | Meaning | Tables |
+|-------|---------|--------|
+| **open-within-org** | Own rows (any visibility) plus every other agent's non-private rows | Memory |
+| **owner-only** | Only the owning agent (plus admin / internal) | Relationship, WorkspaceState, Asset, MemoryCandidate |
+| **none** | Any verified agent reads every row; no visibility field | Soul, OrgEvent |
+
+These three scopes are **not** in `RECORD_TYPES`. Each is hand-implemented on its
+own resource:
+
+| Scope | Meaning | Table | Enforced in |
+|-------|---------|-------|-------------|
+| **party** | Sender or recipient only | Message | `resources/Message.ts` |
+| **own-ledger** | Only the contributing agent's rows | MemoryUsage | `resources/MemoryUsage.ts` |
+| **owner-or-grantee** | Either party on the grant | MemoryGrant | `resources/MemoryGrant.ts` |
+
+Writes stamp `agentId` (or `authorId` / `from`) from the authenticated
+principal. A body that names a different owner is rejected or overwritten
+per the table's attribution mode — never trusted.
+
+Federation sync currently pushes **Memory** (non-`private`), **Soul**,
+**Agent**, and **Relationship**. `Message` has a classifier policy for a later
+cross-host slice; it is not in today's spoke push list. Everything else is
+instance-local.
+
+---
+
+## Endpoints
+
+Paths are the Harper class / table name. Collection GET is `GET /Name`; by-id
+is `GET /Name/<id>` unless noted.
+
+### Public and health
+
+| Method | Path | Auth | Notes |
+|--------|------|------|-------|
+| GET | `/Health`, `/health` | Public | Liveness. `searchReady` is always present; HTTP 503 / `ok: false` when search cannot be served. |
+| GET | `/HealthDetail` | Ed25519 | Rich stats (counts, agents, migration). |
+| GET | `/AgentCard/<agentId>` | Public | A2A agent-card; field-allowlisted. |
+| GET | `/a2a`, `/A2AAdapter` | Public | A2A discovery. |
+| POST | `/a2a`, `/A2AAdapter` | Ed25519 | JSON-RPC actions (writes OrgEvents, reads tasks). GET-only is public; POST is not. |
+
+### Identity — Agent, Presence, Soul
+
+| Method | Path | Auth | Read / write |
+|--------|------|------|--------------|
+| GET | `/Agent`, `/Agent/<id>` | Ed25519 | Any verified agent may read principals (discovery). |
+| POST | `/Agent` | Admin Basic | Create principal. Also `POST /AgentSeed` (operator/internal only — not an admin-agent key). |
+| PUT / PATCH | `/Agent/<id>` | Ed25519 | An agent updates **only its own** record. |
+| DELETE | `/Agent/<id>` | Admin Basic | Deprovision. |
+| GET | `/Presence` | Public | Roster, field-allowlisted. `currentTask` is null for anonymous callers; verified agents see the text. |
+| POST | `/Presence` | Ed25519 | Heartbeat. Agent writes only its own row (403 cross-agent). Stamps `flairVersion` / `harperVersion`. |
+| PUT / DELETE | `/Presence/<id>` | Ed25519 | Own row only. Collection PUT is not a public bypass. |
+| GET | `/Soul`, `/Soul/<id>` | Ed25519 | Any verified agent; unscoped (identity/discovery). |
+| POST / PUT / PATCH / DELETE | `/Soul` | **Operator / internal** | Not Ed25519. Learned Memory text cannot be copied in as Soul. See [docs/auth.md](auth.md#soul-authorship). |
+| POST | `/FeedSouls` | Ed25519 | Soul change feed (verified). |
+
+`Credential` (GET/POST verified; extra credentials for a principal) and
+`Integration` (legacy 0.x platform rows; verified, prefer Credential) sit on
+the same identity plane.
+
+### Memory, search, bootstrap
+
+| Method | Path | Auth | Read / write |
+|--------|------|------|--------------|
+| GET | `/Memory`, `/Memory/<id>` | Ed25519 | open-within-org. By-id deny = 404. |
+| POST / PUT / PATCH | `/Memory` | Ed25519 | Own `agentId` only. Auto-embed on write. Visibility defaults from durability (`permanent`/`persistent` → `shared`, `standard`/`ephemeral` → `private`). |
+| DELETE | `/Memory/<id>` | Ed25519 | Owner or admin. `permanent` owner-delete is allowed. |
+| POST | `/SemanticSearch` | Ed25519 | Hybrid semantic + lexical. Same read-scope as Memory. Default scoring is `raw`. |
+| POST | `/BootstrapMemories` | Ed25519 | Cold-start context (soul + predicted memories + optional org events). |
+| POST | `/RecordUsage` | Ed25519 | Cross-agent usage signal (`Memory.usageCount`). No ownership requirement; no existence oracle in the response. Prefer this over writing `/MemoryUsage` directly. |
+| GET | `/MemoryUsage` | Ed25519 | Own ledger rows only. PUT/DELETE are admin/internal — agents must not delete their row to re-count. |
+| GET / write | `/MemoryGrant` | Ed25519 | Read: owner or grantee. Write/delete: owner only (you share your own memories). |
+| GET / write | `/Asset` | Ed25519 | Owner-only blobs linked by `memoryId`. No MCP and no federation in this slice. |
+| GET / write | `/MemoryCandidate` | Ed25519 | Owner-only REM drafts. Never auto-promoted except the narrow ADK path. |
+| POST | `/PromoteMemoryCandidate` | Ed25519 | Promote/reject with required rationale. |
+| POST | `/AutoPromoteCandidates` | Ed25519 | ADK per-user auto-promote only. |
+| POST | `/FeedMemories` | Ed25519 | Ingest path; `agentId` stamped from the caller (`stamp-strict`). |
+| POST | `/MemoryArchive` | Ed25519 | Basement / restore (`memory_basement` / `memory_restore` on `/mcp`). |
+| POST | `/MemoryMaintenance` | Ed25519 or admin | Hygiene: expire ephemeral, archive old standard. Agent-scoped unless admin. |
+| POST | `/MemoryReindex` | Admin / verified per handler | Embedding / HNSW rebuild. |
+| POST | `/MemoryConsolidate` | Ed25519 | Dedup / consolidate. |
+| POST | `/MemoryReflect` | Ed25519 | REM distill → MemoryCandidate. |
+| POST | `/MemoryDedupStats` | Admin Basic | Dedup diagnostics. Fleet-wide sweep; `allowCreate` is `allowAdmin`. |
+| POST | `/SkillScan` | Ed25519 | Skill-tag scan on Memory writes. |
+
+Skill-tagged Memory rows embed from `trigger` (the recall signal), not
+`content`. MCP tools: `skill_store`, `skill_search`, `skill_get`.
+
+### Relationships, workspace, org events, attention
+
+| Method | Path | Auth | Read / write |
+|--------|------|------|--------------|
+| GET / PUT | `/Relationship` | Ed25519 | Owner-only. Upsert via PUT; provenance stamped server-side. |
+| GET / POST / PUT | `/WorkspaceState` | Ed25519 | Owner-only. POST stamps `agentId`; PUT rejects a mismatch. |
+| GET | `/WorkspaceLatest` | Ed25519 | Latest workspace row for the caller. |
+| GET / POST / PUT | `/OrgEvent` | Ed25519 | Any verified agent reads every event. Writes stamp `authorId`. |
+| GET | `/OrgEventCatchup` | Ed25519 | Catch-up feed for the caller. |
+| POST | `/OrgEventMaintenance` | Ed25519 / admin | Expire / sweep org events. |
+| POST | `/AttentionQuery` | Ed25519 | Cross-table “what touches entity E”. Entity strings: [docs/entity-vocabulary.md](entity-vocabulary.md). |
+
+### Federation
+
+| Method | Path | Auth | Notes |
+|--------|------|------|-------|
+| GET | `/FederationInstance` | Admin Basic | Local instance identity (CLI / admin). Peers do not call this during pair. |
+| POST | `/FederationPair` | Pairing token + body-sig | Public at the Harper role gate. Handler validates token, signature, anti-replay. Fabric uses the bootstrap-user triple from `flair federation token`. |
+| POST | `/FederationSync` | Peer body-sig | Public at the role gate. Merge Memory / Soul / Agent / Relationship (and classifier-ready Message). Originator + per-record signature checks. |
+| GET | `/FederationPeers` | Admin Basic | Known peers. |
+| GET / write | `/Instance` | Read: Ed25519. Write: admin | Instance row (`flair_…` id, role hub/spoke). |
+| GET / write | `/Peer` | Admin Basic | Pinned peer keys and sync cursors. |
+| GET / write | `/PairingToken` | Admin Basic | One-time tokens; default TTL 1 hour. |
+
+`Nonce` and `SyncLog` are **not** `@export` — no agent REST. Nonce is the
+anti-replay store; SyncLog is the operator audit trail.
+
+### Messaging (Flair Relay)
+
+| Method | Path | Auth | Notes |
+|--------|------|------|-------|
+| GET / POST | `/Message` | Ed25519 | POST sends (signed envelope). GET is party-scoped (`from` or `to`). Direct PUT is admin/internal. |
+| GET | `/MessageInbox` | Ed25519 | Inbox for the caller. |
+| POST | `/MessageAck` | Ed25519 | Consume a delivered message. |
+| GET | `/MessageDeadLetter` | Ed25519 | Visible failures for the sender (`deadline`, `inbox_full`, …). |
+| GET / POST | `/MessageSweep` | Ed25519 / admin | Deadline sweep. Messages never arrive at a silent drop. |
+
+### OAuth, MCP, XAA
+
+| Method | Path | Auth | Notes |
+|--------|------|------|-------|
+| GET | `/.well-known/oauth-authorization-server`, `/OAuthMetadata` | Public | RFC 8414. CORS `*`. |
+| GET | `/.well-known/oauth-protected-resource`, `…/mcp` | Public | RFC 9728. |
+| POST | `/OAuthRegister` | `X-Flair-Initial-Access-Token` | DCR. **Off** unless `FLAIR_OAUTH_DCR_TOKEN` is set (32–508 chars). Rate-limited. |
+| GET / POST | `/OAuthAuthorize` | Public (user consent) | Authorization code + PKCE. |
+| POST | `/OAuthToken` | Public (client + code/assertion) | Token + `jwt-bearer` (XAA). |
+| POST | `/OAuthRevoke` | Public (token) | Revocation. |
+| GET / POST | `/mcp` | OAuth bearer | Curated tools. **Unmounted** until `FLAIR_MCP_OAUTH=true` and an issuer. |
+| GET / write | `/OAuthClient` | Admin Basic | Durable client rows. |
+| GET / write | `/IdpConfig` | Admin Basic | XAA IdP registration (`flair idp add`). |
+| GET | `/MCPClientMetadata` | Public / handler-gated | CIMD documents for allowed hosts. |
+
+`OAuthAuthCode`, `OAuthToken`, and `IdJagReplay` are internal tables (no
+`@export`). They hold codes, hashed tokens, and used `jti` values.
+
+OAuth rate limits and env vars: [docs/auth.md](auth.md#rate-limiting).
+
+### Admin UI
+
+All `/Admin*` routes require **Admin Basic**.
+
+| Path | Purpose |
+|------|---------|
+| `/Admin`, `/AdminDashboard` | Server-rendered console |
+| `/AdminPrincipals` | Agents / users: view, promote, disable |
+| `/AdminConnectors` | OAuth clients and sessions |
+| `/AdminIdp` | IdP configuration |
+| `/AdminMemory` | Browse / search memory as operator |
+| `/AdminInstance` | Federation status, peers, instance |
+
+---
+
+## `/mcp` tools
+
+Mounted only when OAuth MCP is on. Each tool wraps a resource above; identity
+comes from the token `sub`, never from tool arguments.
+
+| Tool | Wraps |
+|------|-------|
+| `memory_search` | `POST /SemanticSearch` |
+| `memory_store` | `POST /Memory` |
+| `memory_update` | Memory read-modify-write (in-place or `supersedes` version) |
+| `memory_get` | `GET /Memory/<id>` |
+| `memory_delete` | `DELETE /Memory/<id>` |
+| `memory_basement` | `POST /MemoryArchive` (archive) |
+| `memory_restore` | `POST /MemoryArchive` (restore) |
+| `skill_store` / `skill_search` / `skill_get` | Skill-tagged Memory |
+| `bootstrap` | `POST /BootstrapMemories` |
+| `soul_get` | `GET /Soul` |
+| `soul_set` | Soul write — still operator-gated on the resource |
+| `flair_workspace_set` | `POST /WorkspaceState` |
+| `flair_orgevent` | `POST /OrgEvent` |
+| `attention` | `POST /AttentionQuery` |
+| `record_usage` | `POST /RecordUsage` |
+
+The stdio package `@tpsdev-ai/flair-mcp` is a separate HTTP client, not this
+handler. It talks Ed25519 REST via `flair-client`.
+
+---
+
+## Schema
+
+Fields below are the GraphQL attributes. Server-stamped columns are **not**
+client-writable even if a client sends them. Full comments live in
+`schemas/*.graphql`.
+
+### Presence (`schemas/schema.graphql`)
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `agentId` | ID PK | One row per agent |
+| `lastHeartbeatAt` | BigInt | Unix ms; refreshed every heartbeat |
+| `currentTask` | String | Free text; verified-agent read only |
+| `activity` | String | `coding` \| `reviewing` \| `planning` \| `debugging` \| `idle` |
+| `activityUpdatedAt` | BigInt | When activity/task were asserted |
+| `flairVersion` | String | Serving `@tpsdev-ai/flair` version |
+| `harperVersion` | String | Serving Harper version |
+
+### Memory (`schemas/memory.graphql`)
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `id` | ID PK | |
+| `agentId` | String! | Owner; no-forge |
+| `content` | String! | Embedded text (non-skill) |
+| `contentHash` | String | Near-duplicate key |
+| `trigger` | String | Skill “when to use”; skill rows embed from this |
+| `visibility` | String | `shared` \| `private` (durability default if omitted) |
+| `embedding` | [Float] | HNSW, M:16 |
+| `embeddingModel` | String | Stamp of the model that produced the vector |
+| `tags` | [String] | |
+| `durability` | String | `permanent` \| `persistent` \| `standard` \| `ephemeral` |
+| `source` | String | |
+| `createdAt` / `updatedAt` | String | |
+| `expiresAt` | String | Ephemeral TTL |
+| `retrievalCount` / `lastRetrieved` | | Search-hit counters (weak signal). Incremented on `MemoryHitStat` and overlaid on Memory reads — search no longer rewrites the Memory row. |
+| `usageCount` | Int | Verified-use signal; only `RecordUsage` / citations increment |
+| `promotionStatus` / `promotedAt` / `promotedBy` | | REM promotion |
+| `archived` / `archivedAt` / `archivedBy` | | Basement |
+| `parentId` / `derivedFrom` / `sessionId` / `lastReflected` | | Learning pipeline |
+| `supersedes` | String | Version chain |
+| `subject` / `summary` | String | Compression: subject → summary → content |
+| `validFrom` / `validTo` | String | Temporal validity; expired rows drop out of search |
+| `_safetyFlags` | [String] | Content-safety scan |
+| `provenance` | String | Server JSON `{ v, verified, claimed? }` |
+| `originatorInstanceId` | String | Write-time instance id; preserved across sync |
+| `metadata` | String | Client JSON blob; opaque to the server |
+| `entities` | [String] | Attention-plane `type:value` strings |
+
+### Soul
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `id` | ID PK | Typically `agentId:key` |
+| `agentId` | String! | Owner |
+| `key` / `value` | String | Personality / procedure entry |
+| `priority` | String | `critical` \| `high` \| `standard` \| `low` |
+| `metadata` | String | JSON (skill governance, etc.) |
+| `provenance` | String | Operator/internal author + `sourceClass` |
+| `durability` | String | Default `permanent` |
+| `createdAt` / `updatedAt` | String | |
+| `originatorInstanceId` | String | Federation origin |
+
+### Agent (Principal)
+
+The Agent table **is** the Principal table. Pre-1.0 rows without `kind` are
+agents.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `id` | ID PK | Agent id |
+| `name` | String! | |
+| `role` / `type` | String | Legacy; `role` reconciles with `admin` |
+| `kind` | String | `human` \| `agent` |
+| `displayName` | String | |
+| `status` | String | `active` \| `deactivated` |
+| `publicKey` | String! | Ed25519 public key |
+| `defaultTrustTier` | String | `endorsed` \| `corroborated` \| `unverified` |
+| `admin` | Boolean | Principal-table admin bit |
+| `runtime` / `runtimeEndpoint` | String | How to reach the principal |
+| `subjects` | [String] | Soul-level interests |
+| `createdAt` / `updatedAt` | String | |
+| `originatorInstanceId` | String | Federation origin |
+
+Related: **Credential** (`principalId`, `kind` webauthn / bearer-token /
+ed25519 / idp) and **Integration** (legacy platform connection).
+
+### Federation tables (`schemas/federation.graphql`)
+
+| Type | REST? | Purpose |
+|------|-------|---------|
+| **Instance** | yes | One row per Flair instance (`id`, `publicKey`, `role` hub/spoke, `fabricEndpoint`, `status`) |
+| **PairingToken** | yes | One-time token (`expiresAt`, `consumedBy`) |
+| **Peer** | yes | Pinned peer (`publicKey`, `endpoint`, `status`, `lastSyncAt` / `lastMergeAt`, `lastSyncCursor`, `relayOnly`) |
+| **Nonce** | no | Body-sig anti-replay; PK is the nonce string |
+| **SyncLog** | no | Per-sync audit (`peerId`, `direction`, counts, `skippedReasons`, `status`) |
+
+### Other tables
+
+| Type | File | REST? | Role |
+|------|------|-------|------|
+| **Relationship** | memory.graphql | yes | `subject` / `predicate` / `object` + temporal bounds + provenance |
+| **MemoryGrant** | memory.graphql | yes | `ownerId`, `granteeId`, `scope`, `filter` |
+| **MemoryUsage** | memory.graphql | yes | Dedup ledger; PK `${agentId}:${memoryId}` |
+| **MemoryHitStat** | memory.graphql | no | Search-hit ledger (`retrievalCount`, `lastRetrieved`); overlaid onto Memory reads |
+| **MemoryCandidate** | memory.graphql | yes | REM draft (`claim`, `status`, `scopeTag`, visibility ruling) |
+| **Asset** | memory.graphql | yes | Blob (`contentType`, `data`) owned by `agentId`, linked by `memoryId` |
+| **WorkspaceState** | workspace.graphql | yes | Current work (`ref`, `provider`, `phase`, `entities`) |
+| **OrgEvent** | event.graphql | yes | Org-visible event (`authorId`, `kind`, `summary`, `entities`) |
+| **Message** | message.graphql | yes | Signed envelope (`from`, `to`, `threadId`, `seq`, `state`, `signature`) |
+| **OAuthClient** | oauth.graphql | yes | Registered OAuth clients |
+| **OAuthAuthCode** | oauth.graphql | no | Single-use codes + PKCE |
+| **OAuthToken** | oauth.graphql | no | Hashed access/refresh tokens |
+| **IdpConfig** | oauth.graphql | yes | XAA IdP (`issuer`, `jwksUri`, `requiredDomain`) |
+| **IdJagReplay** | oauth.graphql | no | Used ID-JAG `jti` values |
+
+---
+
+## See also
+
+- [docs/auth.md](auth.md) — Ed25519, OAuth 2.1, XAA, Soul authorship
+- [docs/federation.md](federation.md) — pairing, sync, CLI
+- [docs/rem.md](rem.md) — MemoryCandidate promote/reject
+- [docs/entity-vocabulary.md](entity-vocabulary.md) — `entities` grammar
+- [docs/embedding-in-a-harper-app.md](embedding-in-a-harper-app.md) — in-process API
+- [`packages/flair-client/README.md`](../packages/flair-client/README.md) — typed HTTP client

package/docs/auth.md

@@ -1,6 +1,7 @@
 # Authentication & Authorization
 
 Flair supports three authentication methods, from simplest to most enterprise-ready.
+HTTP paths and per-resource auth are catalogued in **[docs/api-reference.md](api-reference.md)**.
 
 ## Auth across surfaces (read this first)
 
@@ -298,3 +299,54 @@ The web admin at `/AdminDashboard` provides a UI for managing:
 - **Instance:** federation status, peer connections
 
 Access requires admin-level authentication (Basic auth with the Harper admin password).
+
+## Soul authorship
+
+Soul mutations require verified Harper administrator Basic credentials on the
+REST API, or a deliberate `internalContext()` call inside the server. Agent
+Ed25519 keys, including admin-agent keys, and MCP/OAuth delegation cannot create,
+update, patch or delete Soul. A missing context does not grant Soul authority.
+This distinguishes credential classes; an administrator password is still a
+privileged secret, not proof that a human typed the request. Keep it out of
+agent-runtime environments. The n8n adapter currently uses admin Basic credentials
+and therefore retains operator-level access; it needs separate runtime credentials
+to receive the runtime restriction. Existing verified Soul reads are unchanged.
+
+For an explicit operator edit:
+
+```sh
+flair soul set --agent mybot --key role --value "Security reviewer" --admin-pass-file ~/.flair/admin-pass
+flair rem restore <date> --agent mybot --apply --admin-pass-file ~/.flair/admin-pass
+```
+
+`--admin-user` selects a non-default Harper administrator. The server overwrites
+Soul's `provenance` with the authenticated author, timestamp, and verified
+`sourceClass` (`operator` or `internal`); body fields cannot choose that class.
+
+`AgentSeed` uses the same operator/internal gate on purpose: minting a principal
+and its identity is a trust-root act, so an admin-agent key cannot provision.
+This is an intended provisioning change, not only a Soul-write restriction.
+`flair agent add` and the setup wizard already seed through administrator Basic
+credentials (ops API); they do not call `AgentSeed` with an Ed25519 agent key.
+Deliberate `internalContext()` provisioning still passes. Do not widen the gate
+to admin-agent keys.
+
+Federation remains an authenticated instance-to-instance replication path and
+preserves the originating record; it does not reclassify a runtime request as
+an operator edit. Raw Harper OPS access remains administrator infrastructure.
+
+An operator write is refused if its value exactly matches stored Memory or
+MemoryCandidate text for the target agent, including legacy or untagged records.
+The owner-scoped lookup prevents another agent from blocking edits by copying
+known Soul text into its own memories. Learned artifacts are not an operator-authored Soul source;
+claimed or missing provenance does not exempt them. Lookup failure aborts the
+write. This is an exact-match backstop, not semantic detection of paraphrases.
+Existing Soul records remain readable without a migration.
+
+The legacy `adk:` body-tag and stored-tag refusal remains a compatibility
+bridge until **2026-10-31** (`ADK_SOUL_REFUSE_KILL_DATE` in
+`resources/soul-adk-guard.ts`). Runtime denial itself never depends on
+connector names — Soul writes are deny-by-default, and Flair stamps
+`sourceClass` from the authenticated credential, not from a body field.
+Removal of the vendor-string bridge is #1540; do not grow a per-connector
+blacklist in Soul.

package/docs/federation.md

@@ -239,6 +239,10 @@ flair federation status
 flair federation unpin <instanceId>
 ```
 
+HTTP paths (`/FederationPair`, `/FederationSync`, `/FederationInstance`,
+`/FederationPeers`) and the Instance / Peer / PairingToken / Nonce / SyncLog
+schemas: **[docs/api-reference.md](api-reference.md#federation)**.
+
 ## Limitations (1.0)
 
 - **HTTP push only** — no persistent WebSocket connections or real-time sync