@oneie/sdk 0.14.4 → 0.14.6

package/dist/receivers.js

@@ -257,6 +257,30 @@ export const RECEIVERS = {
         idempotent: true,
         examples: [{ visitorHash: "9f2a1c7b4e0d8a3f5c6b" }],
     }),
+    "visitor:identify": receiver({
+        receiver: "visitor:identify",
+        summary: "Every surface's front door to identify a visitor — mines free text, enriches by email, climbs the ladder, merges tenant-walled candidates, upserts the vCard.",
+        request: z.object({
+            email: z.string().optional(),
+            phone: z.string().optional(),
+            name: z.string().optional(),
+            handle: z.string().optional(),
+            channel: z.string().optional(),
+            sender: z.string().optional(),
+            visitorHash: z.string().optional(),
+            freeText: z.string().optional(),
+            source: z.enum(["door", "chat", "asked", "event"]),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            aid: z.string().optional(),
+            merged: z.boolean().optional(),
+            reason: z.string().optional(),
+        }),
+        effect: "ask",
+        auth: "manage_actors",
+        examples: [{ email: "sam@acme.com", source: "chat" }],
+    }),
     "world:update-contact": receiver({
         receiver: "world:update-contact",
         summary: "Update an actor's contact/profile attributes — identity, contact details, professional, personal, CRM metrics",
@@ -399,6 +423,13 @@ export const RECEIVERS = {
         summary: "Delete a thing",
         request: z.object({ tid: z.string() }), response: ok, effect: "ask", auth: "manage_things", reversible: false,
     }),
+    "world:publish-agent": receiver({
+        receiver: "world:publish-agent",
+        summary: "Publish an agent.md to a workspace's R2 bucket so it can be loaded by the chat UI",
+        request: z.object({ slug: z.string(), name: z.string(), content: z.string() }),
+        response: z.object({ ok: z.boolean(), url: z.string(), name: z.string(), bytes: z.number() }),
+        effect: "ask", auth: "update_group",
+    }),
     "world:list-things": receiver({
         receiver: "world:list-things",
         summary: "List things of a given type — relation pickers (browse, first 100 by name) and name resolution (pass `ids` to resolve exactly those, uncapped)",
@@ -485,6 +516,54 @@ export const RECEIVERS = {
         response: z.object({ ok: z.boolean(), target: z.string().optional() }),
         effect: "ask", auth: "session", reversible: true,
     }),
+    "world:in": receiver({
+        receiver: "world:in",
+        summary: "The one front door: a message enters the world inbox, a guard quarantines toxic content, the router classifies the destination (private/fanout/public), and delivers into each destined workspace. Opt-in delivery — a workspace receives only tags it subscribed.",
+        request: z.object({
+            content: z.string().min(1),
+            tags: z.array(z.string()).optional(),
+            to: z.string().optional(),
+            from: z.string().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            decision: z.enum(["private", "fanout", "public", "quarantine"]).optional(),
+            targets: z.array(z.string()).optional(),
+            delivered: z.array(z.string()).optional(),
+            guard: z.object({ toxic: z.boolean(), score: z.number(), reason: z.string() }).optional(),
+            note: z.string().optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", auth: "session", reversible: false,
+    }),
+    "world:subscribe": receiver({
+        receiver: "world:subscribe",
+        summary: "Opt into a tag so the world:in front door routes matching messages to you. An agent self-subscribes (omit workspace/actor); a workspace you own via `workspace`; a trusted relay may register an agent via `actor`. Writes claw_paths world:sub:<tag>.",
+        request: z.object({ tag: z.string().min(1), workspace: z.string().optional(), actor: z.string().optional() }),
+        response: z.object({ ok: z.boolean(), subscriber: z.string().optional(), tag: z.string().optional(), error: z.string().optional() }),
+        effect: "ask", auth: "session", reversible: true,
+    }),
+    "world:unsubscribe": receiver({
+        receiver: "world:unsubscribe",
+        summary: "Leave a tag — the symmetric op to world:subscribe. Removes the claw_paths world:sub:<tag> row so the front door stops routing it to you. Same authority as subscribe.",
+        request: z.object({ tag: z.string().min(1), workspace: z.string().optional(), actor: z.string().optional() }),
+        response: z.object({ ok: z.boolean(), subscriber: z.string().optional(), tag: z.string().optional(), removed: z.number().optional(), error: z.string().optional() }),
+        effect: "ask", auth: "session", reversible: false,
+    }),
+    "world:subscribers": receiver({
+        receiver: "world:subscribers",
+        summary: "Discovery — who follows this tag? Returns the subscribers (agents + workspaces) of one or more tags from the world space. The world's subscriber directory: agents find each other by shared interest, then peer:message or broadcast to them. Read-only; not gated by inbox tenancy.",
+        request: z.object({ tag: z.string().optional(), tags: z.array(z.string()).optional() }),
+        response: z.object({
+            ok: z.boolean(),
+            tags: z.array(z.string()).optional(),
+            count: z.number().optional(),
+            subscribers: z.array(z.string()).optional(),
+            byTag: z.record(z.string(), z.array(z.string())).optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", auth: "session", reversible: true,
+    }),
     // ════════════════════════════════════════════════════════════════════════
     // C4 — remaining families (sequenced by recipe: identity → groups → BUILD
     // → TRADE → TRANSACT → reads). Request schemas mirror the exact client.ts
@@ -547,7 +626,7 @@ export const RECEIVERS = {
         summary: "Agency P&L — per-client funded · burned · margin · balance · cap (margin from the ledger)",
         request: z.object({ slug: z.string().optional() }).optional(),
         response: z.object({
-            agency: z.object({ slug: z.string(), name: z.string().nullable(), markup_pct: z.number(), pool: z.number() }).nullable(),
+            agency: z.object({ slug: z.string(), name: z.string().nullable(), markup_pct: z.number(), plan: z.string(), pool: z.number() }).nullable(),
             clients: z.array(z.object({
                 slug: z.string(), name: z.string().nullable(), plan: z.string(),
                 funded: z.number(), burned: z.number(), margin: z.number(), balance: z.number(), cap: z.number().nullable(),
@@ -571,6 +650,18 @@ export const RECEIVERS = {
             receiver: z.string(),
             tags: z.array(z.string()),
             scope: z.enum(["private", "public"]).optional(),
+            // Shared cross-tenant board — the one workspace two different ctx.ownerSlug
+            // identities can both land in (subscriptions.ts fanOut never delivers to its
+            // own sender, so a self-follow needs a distinct board+actor pairing).
+            board: z.literal("marketplace").optional(),
+            delivery: z.enum(["inbox", "telegram", "discord", "webhook"]).optional(),
+            delivery_target: z.string().optional(),
+            match: z.enum(["any", "all"]).optional(),
+            // Service-caller nomination only (Bearer === GATEWAY_API_KEY / X-Gateway-Key ===
+            // GATEWAY_SERVICE_SECRET) — a session/browser caller's value here is ignored in
+            // favor of their attested locals.slug. See one.ie/web/src/pages/api/ask/[...receiver].ts.
+            slug: z.string().optional(),
+            workspace: z.string().optional(),
         }),
         response: ok,
         effect: "signal", idempotent: true,
@@ -581,16 +672,81 @@ export const RECEIVERS = {
         request: z.object({
             tags: z.array(z.string()),
             content: z.string().optional(),
+            board: z.literal("marketplace").optional(),
+            slug: z.string().optional(),
+            workspace: z.string().optional(),
         }),
         response: z.object({ ok: z.boolean(), matched: z.number().optional(), actors: z.array(z.string()).optional() }),
         effect: "ask",
     }),
+    "world": receiver({
+        receiver: "world",
+        summary: "THE door — say it once, the world decides. Routes a tagged signal via the ladder (learned path → staked subscribers → CEO); fan:'all' broadcasts to every matching subscriber instead. Address form world:<tag-expr> carries tags in the receiver",
+        request: z.object({
+            tags: z.array(z.string()).optional(),
+            fan: z.enum(["one", "all"]).optional(),
+            deliver: z.boolean().optional(),
+            board: z.literal("marketplace").optional(),
+            slug: z.string().optional(),
+            workspace: z.string().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            routed: z.enum(["learned", "staked", "explore", "ceo"]).optional(),
+            actor: z.string().optional(),
+            matched: z.number().optional(),
+            actors: z.array(z.string()).optional(),
+            tags: z.array(z.string()).optional(),
+        }),
+        effect: "ask",
+    }),
+    "world:outcome": receiver({
+        receiver: "world:outcome",
+        summary: "Close the routing loop with the RESULT: whoever consumed a route reports success/failure, moving the same tag→receiver paths the router reads — success marks, failure warns. Pass the actor id the route returned",
+        request: z.object({
+            tags: z.array(z.string()),
+            actor: z.string(),
+            success: z.boolean().optional(),
+            weight: z.number().optional(),
+            slug: z.string().optional(),
+            workspace: z.string().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            outcome: z.enum(["marked", "warned"]).optional(),
+            actor: z.string().optional(),
+            tags: z.array(z.string()).optional(),
+            weight: z.number().optional(),
+        }),
+        effect: "ask", idempotent: false,
+    }),
+    "world:route": receiver({
+        receiver: "world:route",
+        summary: "Route a tagged signal to THE handler via the ladder: learned tag-node path (follow_route) → staked subscribers (reputation-ranked) → CEO standing workflow; marks the delivery path so the next route is smarter",
+        request: z.object({
+            tags: z.array(z.string()),
+            deliver: z.boolean().optional(),
+            board: z.literal("marketplace").optional(),
+            slug: z.string().optional(),
+            workspace: z.string().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            routed: z.enum(["learned", "staked", "explore", "ceo"]).optional(),
+            actor: z.string().optional(),
+            tags: z.array(z.string()).optional(),
+        }),
+        effect: "ask",
+    }),
     "tasks:announce": receiver({
         receiver: "tasks:announce",
         summary: "Announce a task into the world by its tags — the first caller of world:announce",
         request: z.object({
             taskId: z.string(),
             tags: z.array(z.string()),
+            board: z.literal("marketplace").optional(),
+            slug: z.string().optional(),
+            workspace: z.string().optional(),
         }),
         response: z.object({ ok: z.boolean(), taskId: z.string().optional(), matched: z.number().optional(), actors: z.array(z.string()).optional() }),
         effect: "ask",
@@ -999,6 +1155,48 @@ export const RECEIVERS = {
         effect: "ask", cost: "free", idempotent: true,
         examples: [{}],
     }),
+    "plugins:buy": receiver({
+        receiver: "plugins:buy",
+        summary: "Buy a plugin for the caller's workspace. method:'stripe' (default) returns a hosted-checkout url; method:'credits' spends the workspace credit pool and grants the entitlement synchronously. Pay with ONE coin by topping up credits on the one-token rail first, then buy with credits. Price is looked up server-side from the plugin name.",
+        request: z.object({
+            name: z.string(),
+            method: z.enum(["stripe", "credits"]).optional(),
+        }),
+        response: z.object({
+            method: z.enum(["stripe", "credits"]),
+            // stripe rail
+            sessionId: z.string().optional(),
+            clientSecret: z.string().nullable().optional(),
+            url: z.string().nullable().optional(),
+            price_usd: z.number().optional(),
+            // credits rail
+            entitled: z.boolean().optional(),
+            already: z.boolean().optional(),
+            credits_spent: z.number().optional(),
+            plugin: z.string(),
+            feature: z.string(),
+        }),
+        effect: "ask", auth: "owner", cost: "variable", idempotent: false,
+        examples: [{ name: "shop" }, { name: "shop", method: "credits" }],
+    }),
+    "plugins:grant": receiver({
+        receiver: "plugins:grant",
+        summary: "Agency resale — grant a plugin to a client workspace the caller controls. Two gates, no money: the caller must itself be entitled to the plugin (you can only resell what you own) and must control the target client via the owners walk-up. The client's entitlement is granted idempotently; nobody is charged. Billing the client is a separate concern.",
+        request: z.object({
+            name: z.string(),
+            for: z.string().describe("the client workspace slug to grant the plugin to"),
+        }),
+        response: z.object({
+            granted: z.boolean().optional(),
+            already: z.boolean().optional(),
+            plugin: z.string(),
+            feature: z.string(),
+            client: z.string().optional(),
+            reseller: z.string().optional(),
+        }),
+        effect: "ask", auth: "owner", cost: "free", idempotent: true,
+        examples: [{ name: "shop", for: "acme-client" }],
+    }),
     "plugins:source": receiver({
         receiver: "plugins:source",
         summary: "Get the install reference for a plugin — 402 when the workspace is not entitled. Use meta:entitlements to check first; this doubles as the delivery gate.",
@@ -1501,6 +1699,42 @@ export const RECEIVERS = {
         }),
         effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
     }),
+    // ── view:* — saved views (custom-views C1). A view is a workspace-scoped Thing (world_things type 'view'). ──
+    "view:create": receiver({
+        receiver: "view:create",
+        summary: "Save a named view — dimension × tags × kind × config — as a workspace Thing",
+        request: z.object({ slug: z.string(), name: z.string(), kind: z.string().optional(), query: z.object({ dimension: z.string().optional(), type: z.string().optional(), tags: z.array(z.string()).optional(), stage: z.string().optional() }), config: z.record(z.string(), z.unknown()).optional(), pinned: z.boolean().optional() }),
+        response: z.object({ ok: z.boolean(), id: z.string().optional(), name: z.string().optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: false, auth: "member",
+    }),
+    "view:list": receiver({
+        receiver: "view:list",
+        summary: "List a workspace's saved views (cold flag derived at read time)",
+        request: z.object({ slug: z.string() }),
+        response: z.object({ views: z.array(z.object({ id: z.string(), name: z.string(), kind: z.string().optional(), pinned: z.boolean(), cold: z.boolean() })) }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
+    }),
+    "view:get": receiver({
+        receiver: "view:get",
+        summary: "Read a saved view and resolve its live rows",
+        request: z.object({ slug: z.string(), id: z.string() }),
+        response: z.object({ ok: z.boolean(), rows: z.array(z.record(z.string(), z.unknown())).optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
+    }),
+    "view:update": receiver({
+        receiver: "view:update",
+        summary: "Update a saved view's name / query / kind / config / pinned",
+        request: z.object({ slug: z.string(), id: z.string(), name: z.string().optional(), kind: z.string().optional(), query: z.object({ dimension: z.string().optional(), type: z.string().optional(), tags: z.array(z.string()).optional(), stage: z.string().optional() }).optional(), config: z.record(z.string(), z.unknown()).optional(), pinned: z.boolean().optional() }),
+        response: z.object({ ok: z.boolean(), id: z.string().optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: false, auth: "member",
+    }),
+    "view:delete": receiver({
+        receiver: "view:delete",
+        summary: "Delete a saved view (the prune)",
+        request: z.object({ slug: z.string(), id: z.string() }),
+        response: z.object({ ok: z.boolean(), id: z.string().optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
+    }),
     // ── pages + workspace settings — handlers in resolvers/pages.ts ────────────────
     "pages:create": receiver({
         receiver: "pages:create",
@@ -1597,21 +1831,21 @@ export const RECEIVERS = {
     "playbook:save": receiver({
         receiver: "playbook:save",
         summary: "Save a learner's playbook entry for a course lesson (upsert)",
-        request: z.object({ course: z.string(), lesson: z.string(), content: z.string().optional() }),
+        request: z.object({ course: z.string(), lesson: z.string(), content: z.string().optional(), slug: z.string().optional(), workspace: z.string().optional() }),
         response: z.object({ ok: z.boolean() }),
         effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "public",
     }),
     "playbook:get": receiver({
         receiver: "playbook:get",
         summary: "Get the caller's playbook entries (optionally scoped to one course)",
-        request: z.object({ course: z.string().optional() }),
+        request: z.object({ course: z.string().optional(), slug: z.string().optional(), workspace: z.string().optional() }),
         response: z.object({ entries: z.array(z.record(z.string(), z.unknown())).optional() }),
         effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "public",
     }),
     "playbook:promote": receiver({
         receiver: "playbook:promote",
         summary: "Promote a completed playbook into a reusable skill in the workspace's content repo",
-        request: z.object({ course: z.string() }),
+        request: z.object({ course: z.string(), slug: z.string().optional(), workspace: z.string().optional() }),
         response: z.object({ ok: z.boolean(), skillRef: z.string().optional() }),
         effect: "ask", cost: "free", reversible: true, idempotent: false, auth: "member",
     }),
@@ -1871,6 +2105,23 @@ export const RECEIVERS = {
         auth: "manage_workflows",
         examples: [{ name: "Client Onboarding" }, { name: "demo", simulate: true }],
     }),
+    "workflow:webhook-subscribe": receiver({
+        receiver: "workflow:webhook-subscribe",
+        summary: "Register a URL that receives every future run's events for one workflow as signed, retried POSTs. Mints a signing secret server-side, returned once.",
+        request: z.object({
+            workflowId: z.string(),
+            url: z.string().url(),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            subId: z.string().optional(),
+            secret: z.string().optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", reversible: true, idempotent: false, simulatable: false,
+        auth: "manage_workflows",
+        examples: [{ workflowId: "wf_abc", url: "https://example.com/hooks/one" }],
+    }),
     "workflow:apply-diff": receiver({
         receiver: "workflow:apply-diff",
         summary: "Apply a WorkflowDiff (add/remove/connect/disconnect/update). simulate=true validates the DAG without persisting",
@@ -2029,6 +2280,14 @@ export const RECEIVERS = {
         effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "manage_workflows",
         examples: [{ workflowId: "wf_abc", name: "Renamed Workflow" }, { workflowId: "wf_abc", status: "paused" }],
     }),
+    "workflow:fade": receiver({
+        receiver: "workflow:fade",
+        summary: "Decay edge weights (strength & resistance) on one workflow — or all of the caller's workflows when workflowId is omitted — so stale bottlenecks stop glowing; multiplies both by (1-rate), default 0.05",
+        request: z.object({ workflowId: z.string().optional(), rate: z.number().optional() }),
+        response: z.object({ ok: z.boolean(), faded: z.number().optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: false, idempotent: false, auth: "manage_workflows",
+        examples: [{ workflowId: "wf_abc" }, { rate: 0.1 }, {}],
+    }),
     // ── The autonomy ladder's leaf runners — a workflow skill/agent step compiles
     //    to one of these (workflow-executor.ts stepBinding). Both proxy to the
     //    channels runtime; web owns the catalog + tenant authority (workflows-lock C2/C3).
@@ -2088,6 +2347,9 @@ export const RECEIVERS = {
         }),
         effect: "ask", cost: "free", idempotent: false, auth: "manage_clients",
         examples: [{ workspace: "acme", roomSlug: "algebra-101", name: "Algebra 101", type: "classroom" }],
+        // Fan-out pilot (actions-fan-out C2): offered to chat via chatToolsFor — no
+        // curated workspace tool needed; the registry derivation is the whole tool.
+        surfaces: { chat: true },
     }),
     "video:delete-room": receiver({
         receiver: "video:delete-room",
@@ -2150,6 +2412,7 @@ export const RECEIVERS = {
         }),
         effect: "ask", cost: "free", idempotent: false, auth: "manage_clients",
         examples: [{ workspace: "acme", name: "Product Launch", actorIds: ["actor_1", "actor_2"] }],
+        surfaces: { chat: true }, // fan-out: registry-derived chat tool (actions-fan-out C5)
     }),
     "video:create-session": receiver({
         receiver: "video:create-session",
@@ -2188,6 +2451,7 @@ export const RECEIVERS = {
         }),
         effect: "ask", cost: "variable", idempotent: false, auth: "manage_clients",
         examples: [{ threadId: "thr_abc", transcript: "Host: Hello... Guest: Hi..." }],
+        surfaces: { chat: true }, // fan-out: registry-derived chat tool (actions-fan-out C5)
     }),
     "video:quick-room": receiver({
         receiver: "video:quick-room",
@@ -2207,6 +2471,8 @@ export const RECEIVERS = {
         }),
         effect: "ask", cost: "free", idempotent: false, auth: "manage_clients",
         examples: [{ workspace: "acme", threadId: "thr_xyz", name: "Quick sync" }],
+        // Fan-out pilot (actions-fan-out C2).
+        surfaces: { chat: true },
     }),
     "video:join-event": receiver({
         receiver: "video:join-event",
@@ -2232,6 +2498,7 @@ export const RECEIVERS = {
         }),
         effect: "ask", cost: "free", idempotent: false, auth: "manage_clients",
         examples: [{ workspace: "acme", roomSlug: "algebra-101" }],
+        surfaces: { chat: true }, // fan-out: registry-derived chat tool (actions-fan-out C5)
     }),
     "video:start-stream": receiver({
         receiver: "video:start-stream",
@@ -2248,6 +2515,7 @@ export const RECEIVERS = {
         }),
         effect: "ask", cost: "free", idempotent: false, auth: "manage_clients",
         examples: [{ workspace: "acme", roomSlug: "product-launch" }],
+        surfaces: { chat: true }, // fan-out: registry-derived chat tool (actions-fan-out C5)
     }),
     // connect:channel — token-paste connect for a channel (Connect plan C7). The
     // typed contract over the shipped /api/connect/telegram route: the caller pastes
@@ -2542,6 +2810,94 @@ export const RECEIVERS = {
         }),
         effect: "signal", auth: "read_corpus", cost: "free", reversible: false, idempotent: false,
     }),
+    // -- rag:connect + brain: family — the phase-2 ingestion edge (brain C5 catalog; C7 handlers) --
+    "rag:connect": receiver({
+        receiver: "rag:connect",
+        summary: "Register a knowledge source (e.g. a Google Drive folder) to sync into a workspace brain. Records the source in workspace_settings.sources; ingest-tick pulls changes on a schedule. Provision the brain (brain:provision) first.",
+        request: z.object({
+            provider: z.enum(["google-drive"]).optional().default("google-drive"),
+            folder_id: z.string().describe("Drive folder id to sync (read-only)."),
+            corpus: z.string().optional().describe("Target brain @-pointer; defaults to your workspace brain @<slug>-brain. Authority-walked (write_corpus)."),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            corpus: z.string().optional(),
+            provider: z.string().optional(),
+            folder_id: z.string().optional(),
+            sources: z.number().optional().describe("Count of registered sources after this connect."),
+            reason: z.string().optional(),
+        }),
+        effect: "ask", auth: "write_corpus", cost: { fixed: 1 }, reversible: true, idempotent: true,
+    }),
+    "brain:ingest": receiver({
+        receiver: "brain:ingest",
+        summary: "Ingest one document (Drive file, URL, or inline text) into a corpus: fetch -> markdown -> chunk -> hash-gate -> embed -> upsert with document provenance. Idempotent on content_hash.",
+        request: z.object({
+            corpus: z.string().describe("Target brain @-pointer. Authority-walked (write_corpus)."),
+            source_ref: z.string().optional().describe("Drive file id or URL — the stable key for tombstones + hash-gate."),
+            document_url: z.string().optional().describe("Fetch URL for the document."),
+            raw_text: z.string().optional().describe("Inline markdown/text/html."),
+            mime_type: z.string().optional(),
+            content_hash: z.string().optional(),
+            title: z.string().optional(),
+            tags: z.array(z.string()).optional(),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            corpus: z.string().optional(),
+            source_ref: z.string().optional(),
+            content_hash: z.string().optional(),
+            chunks: z.number().optional(),
+            skipped: z.boolean().optional().describe("True when content_hash matched (no re-embed)."),
+            reason: z.string().optional(),
+        }),
+        effect: "ask", auth: "write_corpus", cost: { fixed: 1 }, reversible: false, idempotent: true,
+    }),
+    "brain:provision": receiver({
+        receiver: "brain:provision",
+        summary: "Idempotently create a workspace or personal brain: a corpus thing @<slug>-brain contained by the owning group. Safe to call repeatedly (put). Auth walks the workspace group (the corpus does not exist yet).",
+        request: z.object({
+            slug: z.string().describe("Target workspace or personal slug."),
+            kind: z.enum(["workspace", "personal"]).optional().default("workspace"),
+            actorId: z.string().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            corpus: z.string().optional().describe("The provisioned @-pointer, e.g. @acme-brain."),
+            slug: z.string().optional(),
+            kind: z.string().optional(),
+            reason: z.string().optional(),
+        }),
+        effect: "ask", auth: "write_corpus", cost: "free", reversible: false, idempotent: true,
+    }),
+    "brain:tombstone": receiver({
+        receiver: "brain:tombstone",
+        summary: "Remove a deleted source document's chunks from a corpus, keyed by source_ref (Drive file id or URL). Fired by ingest-tick when a previously-known file no longer appears in a folder listing.",
+        request: z.object({
+            corpus: z.string().describe("Target brain @-pointer. Authority-walked (write_corpus)."),
+            source_ref: z.string().describe("The stable key used at ingest — Drive file id or URL."),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            corpus: z.string().optional(),
+            source_ref: z.string().optional(),
+            removed: z.number().optional().describe("Chunk rows deleted."),
+            reason: z.string().optional(),
+        }),
+        effect: "ask", auth: "write_corpus", cost: "free", reversible: false, idempotent: true,
+    }),
+    "rag:promote": receiver({
+        receiver: "rag:promote",
+        summary: "Distill repeat retrieval winners into typed fact. Sweeps retrieval_outcomes for chunks with >=5 mark and 0 warn in a 14-day window, extracts a verbatim statement (no synthesis), and writes it via memory:remember into the chunk's owning group. Fired by the promote-tick cron trigger; safe to call anonymously — the target group is derived from data, never a caller-supplied workspace.",
+        request: z.object({}),
+        response: z.object({
+            ok: z.boolean(),
+            promoted: z.number().optional(),
+            skipped: z.number().optional(),
+            reason: z.string().optional(),
+        }),
+        effect: "ask", auth: "public", cost: "free", reversible: false, idempotent: true,
+    }),
     // ── seo — handlers in resolvers/seo.ts (C1 live; C2 async) ─────────────────
     "seo:backlinks-summary": receiver({
         receiver: "seo:backlinks-summary",