@oneie/sdk 0.14.12 → 0.14.13

package/dist/receivers.js

@@ -9,6 +9,19 @@ import { GroupEntitySchema } from "./generated/schemas/index.js";
 export function receiver(r) {
     return r;
 }
+/**
+ * Receiver name → derived MCP tool name (`video:create-room` → `video_create_room`).
+ *
+ * ONE rule, two consumers — this module (to decide which receivers need an
+ * explicit `surfaces.mcp.name` override) and `mcpToolsFromRegistry()` in
+ * `@oneie/mcp`. A second copy is how the derived name and the registered name
+ * drift apart, which `check:tools` would then report as a missing tool.
+ *
+ * Deliberately NOT the channels rule (`/[^a-zA-Z0-9_-]/g`, which keeps hyphens):
+ * MCP tool names permit hyphens, but every one of the 101 hand-written MCP tools
+ * is underscore-only, so this matches the surface it feeds.
+ */
+export const mcpToolName = (receiver) => receiver.replace(/[^a-zA-Z0-9_]/g, "_");
 const ok = z.object({ ok: z.boolean() });
 /**
  * The receiver catalog — one source of truth for capability. Object-literal keys
@@ -29,6 +42,7 @@ export const RECEIVERS = {
     }),
     "agent:own-link": receiver({
         receiver: "agent:own-link",
+        surfaces: { mcp: { name: "own_me" } },
         summary: "Generate a signed ownership invitation link for a registered agent; optionally deliver it as a native button on Telegram or Discord",
         request: z.object({
             agent_id: z.string().describe("The agent's actor ID (aid from world_actors / actorId from auth.md registration)"),
@@ -83,8 +97,11 @@ export const RECEIVERS = {
     }),
     "auth:agent": receiver({
         receiver: "auth:agent",
-        summary: "Become an actor — mint a uid, wallet, and scoped API key",
-        request: z.object({ name: z.string().optional(), uid: z.string().optional(), kind: z.string().optional() }),
+        // `wallet` is a PUBLIC receiving address the caller derived in its own process.
+        // Nothing here generates keys: the address is stored on the TypeDB actor and
+        // registered through wallet:create, which is first-write-wins per chain.
+        summary: "Become an actor — mint a uid and a scoped API key, and register a wallets row (a public address if you supply one, an empty shell if not)",
+        request: z.object({ name: z.string().optional(), uid: z.string().optional(), kind: z.string().optional(), wallet: z.string().optional() }),
         response: z.object({
             uid: z.string(), name: z.string(), kind: z.string(),
             wallet: z.string().nullable(), apiKey: z.string(), keyId: z.string(), returning: z.boolean(),
@@ -95,6 +112,7 @@ export const RECEIVERS = {
     }),
     "agents:sync": receiver({
         receiver: "agents:sync",
+        surfaces: { mcp: { name: "sync_agent" } },
         summary: "Declare capability — sync agent definitions, skills, and memberships",
         // Accepts a single markdown body or a structured multi-agent world payload.
         request: z.union([
@@ -166,7 +184,7 @@ export const RECEIVERS = {
         summary: "Invite a human member to a workspace; email optional — returns inviteUrl when omitted",
         request: z.object({ workspace: z.string(), email: z.string().email().optional(), role: z.string().optional() }),
         response: z.object({ ok: z.boolean(), uid: z.string(), token: z.string(), inviteUrl: z.string().optional() }),
-        effect: "ask", auth: "manage_members",
+        effect: "ask", auth: "manage_members", roleAction: "invite_member",
     }),
     "world:invite-agent": receiver({
         receiver: "world:invite-agent",
@@ -204,6 +222,7 @@ export const RECEIVERS = {
     }),
     "world:create-group": receiver({
         receiver: "world:create-group",
+        surfaces: { mcp: true },
         summary: "Create a group in the caller's workspace",
         request: z.object({
             name: z.string(),
@@ -215,17 +234,19 @@ export const RECEIVERS = {
     }),
     "world:update-group": receiver({
         receiver: "world:update-group",
+        surfaces: { mcp: true },
         summary: "Update a group's name, tags, or meta",
         request: z.object({ gid: z.string(), name: z.string().optional(), tags: z.array(z.string()).optional(), meta: z.unknown().optional() }),
-        response: ok, effect: "ask", auth: "manage_groups",
+        response: ok, effect: "ask", auth: "manage_groups", roleAction: "update_group",
     }),
     "world:remove-group": receiver({
         receiver: "world:remove-group",
         summary: "Delete a group",
-        request: z.object({ gid: z.string() }), response: ok, effect: "ask", auth: "manage_groups", reversible: false,
+        request: z.object({ gid: z.string() }), response: ok, effect: "ask", auth: "manage_groups", roleAction: "delete_group", reversible: false,
     }),
     "world:create-actor": receiver({
         receiver: "world:create-actor",
+        surfaces: { mcp: true },
         summary: "Create an actor (agent or human) in the world",
         request: z.object({
             name: z.string(), type: z.string(), group: z.string().optional(),
@@ -237,6 +258,7 @@ export const RECEIVERS = {
     }),
     "world:update-actor": receiver({
         receiver: "world:update-actor",
+        surfaces: { mcp: true },
         summary: "Update an actor's name, tags, prompt, model, or custom meta fields",
         request: z.object({ aid: z.string(), name: z.string().optional(), tags: z.array(z.string()).optional(), prompt: z.string().optional(), model: z.string().optional(), meta: z.unknown().optional() }),
         response: ok, effect: "ask", auth: "manage_actors",
@@ -390,6 +412,26 @@ export const RECEIVERS = {
         effect: "ask", auth: "manage_lifecycle", reversible: false,
         examples: [{ slug: "acme", lifecycle: "marketing", def: { id: "marketing", name: "Marketing Funnel", version: 1, stages: [], transitions: [], arcs: [], monotonic: true } }],
     }),
+    "lifecycle:of": receiver({
+        receiver: "lifecycle:of",
+        surfaces: { mcp: true },
+        summary: "Read another actor's lifecycle stage_transition history — authority-walked: the caller must control that actor's slug in the owners tree",
+        request: z.object({ actorId: z.string(), lifecycle: z.string().optional() }),
+        response: z.object({
+            ok: z.boolean(),
+            rows: z.array(z.object({
+                from_stage: z.string().nullable(),
+                to_stage: z.string(),
+                at: z.number(),
+                by: z.string(),
+                source: z.string(),
+            })).optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", auth: "manage_lifecycle", roleAction: "manage_lifecycle",
+        cost: "free", idempotent: true, reversible: true,
+        examples: [{ actorId: "acme-agent", lifecycle: "wallet" }],
+    }),
     "tools:connect": receiver({
         receiver: "tools:connect",
         summary: "Connect a Composio API-KEY toolkit to a workspace headlessly (OAuth stays in the browser flow)",
@@ -408,12 +450,14 @@ export const RECEIVERS = {
     }),
     "world:create-thing": receiver({
         receiver: "world:create-thing",
+        surfaces: { mcp: true },
         summary: "Create a thing (skill, token, product) in the world",
         request: z.object({ name: z.string(), type: z.string(), group: z.string().optional(), tags: z.array(z.string()).optional(), price: z.number().optional(), meta: z.unknown().optional() }),
         response: z.object({ tid: z.string() }), effect: "ask", auth: "manage_things",
     }),
     "world:update-thing": receiver({
         receiver: "world:update-thing",
+        surfaces: { mcp: true },
         summary: "Update a thing's name, tags, price, or meta",
         request: z.object({ tid: z.string(), name: z.string().optional(), tags: z.array(z.string()).optional(), price: z.number().optional(), meta: z.unknown().optional() }),
         response: ok, effect: "ask", auth: "manage_things",
@@ -432,6 +476,7 @@ export const RECEIVERS = {
     }),
     "world:list-things": receiver({
         receiver: "world:list-things",
+        surfaces: { mcp: true },
         summary: "List things of a given type — relation pickers (browse, first 100 by name) and name resolution (pass `ids` to resolve exactly those, uncapped)",
         request: z.object({ group: z.string(), type: z.string(), ids: z.array(z.string()).optional() }),
         response: z.object({ items: z.array(z.object({ tid: z.string(), name: z.string() })) }),
@@ -439,6 +484,7 @@ export const RECEIVERS = {
     }),
     "world:list-actors": receiver({
         receiver: "world:list-actors",
+        surfaces: { mcp: true },
         summary: "List actors of a given type — relation pickers (browse, first 100 by name) and name resolution (pass `ids` to resolve exactly those, uncapped)",
         request: z.object({ group: z.string(), type: z.string(), ids: z.array(z.string()).optional() }),
         response: z.object({ items: z.array(z.object({ aid: z.string(), name: z.string() })) }),
@@ -572,6 +618,7 @@ export const RECEIVERS = {
     // ── identity ──
     "identity:address": receiver({
         receiver: "identity:address",
+        surfaces: { mcp: true },
         summary: "Resolve an actor's wallet address",
         request: z.object({ uid: z.string() }),
         response: z.object({ uid: z.string(), address: z.string() }),
@@ -592,6 +639,7 @@ export const RECEIVERS = {
     // ── groups ──
     "groups:join": receiver({
         receiver: "groups:join",
+        surfaces: { mcp: true },
         summary: "Join a group",
         request: z.object({ gid: z.string() }),
         response: z.object({ ok: z.boolean(), gid: z.string(), role: z.string() }),
@@ -599,6 +647,7 @@ export const RECEIVERS = {
     }),
     "groups:leave": receiver({
         receiver: "groups:leave",
+        surfaces: { mcp: true },
         summary: "Leave a group",
         request: z.object({ gid: z.string() }),
         response: ok,
@@ -613,6 +662,7 @@ export const RECEIVERS = {
     }),
     "groups:members": receiver({
         receiver: "groups:members",
+        surfaces: { mcp: true },
         summary: "List a group's members",
         request: z.object({ gid: z.string() }),
         response: z.object({
@@ -647,7 +697,16 @@ export const RECEIVERS = {
         receiver: "subscriptions:register",
         summary: "Subscribe to a receiver's events by tag",
         request: z.object({
-            receiver: z.string(),
+            // OPTIONAL, and the default is the common case. `subscriptions.ts` reads
+            // this as `data['receiver'] || 'world:announce'` — an agent staking on
+            // tags omits it, which is how every `subscribes:` frontmatter seam works.
+            // Declaring it required was harmless while nothing validated the request;
+            // once `bind-receiver` began enforcing the declared schema it started
+            // rejecting the documented call with a 400 at the edge, before the
+            // resolver's default could apply. Caught by tests/e2e/marketplace.test.ts,
+            // which is the marketplace promise's proof observable — the seller's
+            // stake never registered, so no deal opened.
+            receiver: z.string().optional(),
             tags: z.array(z.string()),
             scope: z.enum(["private", "public"]).optional(),
             // Shared cross-tenant board — the one workspace two different ctx.ownerSlug
@@ -779,6 +838,7 @@ export const RECEIVERS = {
     }),
     "tasks:announce": receiver({
         receiver: "tasks:announce",
+        surfaces: { mcp: true },
         summary: "Announce a task into the world by its tags — the first caller of world:announce",
         request: z.object({
             taskId: z.string(),
@@ -792,6 +852,7 @@ export const RECEIVERS = {
     }),
     "tasks:mine": receiver({
         receiver: "tasks:mine",
+        surfaces: { mcp: true },
         summary: "My work queue: the open tasks whose words match what I subscribed to, ranked by learned weight (context-strength), not static priority",
         // `workspace` is not decoration — /api/ask reads a SERVICE caller's nominated slug off
         // validation.payload.slug|workspace, and zod .object() STRIPS unknown keys. Omitting the
@@ -822,6 +883,7 @@ export const RECEIVERS = {
     }),
     "tasks:everywhere": receiver({
         receiver: "tasks:everywhere",
+        surfaces: { mcp: true },
         summary: "Every workspace I belong to, one queue: open+picked tasks visible by assignment/follow/ownership, with claimable + mine + offeredByMe flags; closed:true returns the logbook (done/verified, newest first)",
         // See tasks:mine — a service caller nominates its workspace here, and zod strips any
         // field the schema does not declare.
@@ -953,6 +1015,7 @@ export const RECEIVERS = {
     }),
     "tasks:create": receiver({
         receiver: "tasks:create",
+        surfaces: { mcp: true },
         summary: "Write one open task to the substrate and announce it by its tags in the same act — the quick-add entry point",
         request: z.object({
             title: z.string(),
@@ -972,6 +1035,7 @@ export const RECEIVERS = {
     }),
     "tasks:claim": receiver({
         receiver: "tasks:claim",
+        surfaces: { mcp: true },
         summary: "Take a task off the queue: blocker-gate → status picked → tag the claimant @<slug>. Address it by tid, or by the /do slug the task was created under. The claimant is the attested caller, never a body field",
         // Addressable two ways, and BOTH must be optional here. The resolver has always
         // supported slug (resolveTaskBySlug) because create returns a random task:<traceId>
@@ -997,8 +1061,308 @@ export const RECEIVERS = {
         }),
         effect: "ask", idempotent: true,
     }),
+    "tasks:reap": receiver({
+        receiver: "tasks:reap",
+        surfaces: { mcp: true },
+        summary: "Sweep stranded claim leases in a workspace: every `picked` task whose newest updated-at-ms is older than the 45-minute TTL goes back to `open`, its @claimant tags are stripped, and the abandoned path is warned",
+        // The other half of the claim seam. tasks:claim is atomic, so two workers can
+        // never double-lease — but a lease whose OWNER DIED is `picked` forever:
+        // `claimable` requires `status === 'open' && ats.length === 0`, so the view
+        // never surfaces it, so `leaseIsStale` (called only inside claim) is never
+        // reached on the rows it was written for. Meanwhile ready-tasks blocks every
+        // dependent on a `picked` blocker. This receiver queries `picked` DIRECTLY —
+        // that is the whole point; asking the claimable view returns nothing.
+        request: z.object({
+            // Viewed workspace — same authorization contract as tasks:claim's workspace.
+            workspace: z.string().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean().optional(),
+            workspace: z.string().optional(),
+            scanned: z.number().optional(),
+            reaped: z.array(z.string()).optional(),
+            failed: z.array(z.string()).optional(),
+            error: z.string().optional(),
+        }),
+        // Idempotent: a second sweep finds nothing left stale and reaps nothing.
+        effect: "ask", idempotent: true,
+    }),
+    // ── The rest of the board's verbs ────────────────────────────────────────────
+    //
+    // These twelve shipped as RESOLVERS ONLY (`tasksResolvers`, one.ie/web) and were
+    // absent from this registry, so `bindReceiver` had no request schema to validate
+    // and no auth label to apply — every one of them reached its handler with an
+    // unchecked payload. They are also what the UI's detail pane, status menu, tag
+    // chips and Gantt call, so the contract that was missing is the contract for most
+    // of the board. `auth: "member"` is the label the family already resolves to
+    // (an absent label falls to `authenticated`, same class) — stated, not changed.
+    //
+    // Every one takes an optional `workspace`, and it means the same thing here as on
+    // tasks:create: the VIEWED workspace, honoured only when the caller is staff or
+    // controls that tree, otherwise ignored in favour of the caller's own slug
+    // (`effectiveWorkspace`). Declaring it is not decoration — zod `.object()` strips
+    // undeclared keys, which is exactly how tasks:mine/everywhere were silently
+    // un-nominatable until 2026-07-25.
+    "tasks:status": receiver({
+        receiver: "tasks:status",
+        surfaces: { mcp: true },
+        summary: "Move a task through the board: open · blocked · picked · done · verified · failed · dissolved. `verified` is refused for the claimant — it asserts a second pair of eyes. A `repeat:` tagged task that reaches done re-arms itself with the next due date instead of closing",
+        request: z.object({
+            tid: z.string(),
+            status: z.enum(["open", "blocked", "picked", "done", "verified", "failed", "dissolved"]),
+            workspace: z.string().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean().optional(),
+            tid: z.string().optional(),
+            status: z.string().optional(),
+            // Set when a repeating task re-armed rather than closed.
+            recurred: z.boolean().optional(),
+            dueAt: z.string().optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", idempotent: true, auth: "member",
+    }),
+    "tasks:rename": receiver({
+        receiver: "tasks:rename",
+        surfaces: { mcp: true },
+        summary: "Retitle a task in place. The tid is unchanged, so every link, blocker and follow survives the rename",
+        request: z.object({
+            tid: z.string(),
+            title: z.string(),
+            workspace: z.string().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean().optional(),
+            tid: z.string().optional(),
+            title: z.string().optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", idempotent: true, auth: "member",
+    }),
+    "tasks:list": receiver({
+        receiver: "tasks:list",
+        surfaces: { mcp: true },
+        summary: "Every task carrying a tag, with its task-status — the read that lets a plan's checkboxes be a PROJECTION of task state instead of a second copy. Scoped to the caller's workspace on the server",
+        request: z.object({
+            tag: z.string(),
+            workspace: z.string().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean().optional(),
+            tag: z.string().optional(),
+            tasks: z.array(z.object({
+                tid: z.string(),
+                status: z.string(),
+                name: z.string().optional(),
+            })).optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", idempotent: true, auth: "member",
+    }),
+    "tasks:notes": receiver({
+        receiver: "tasks:notes",
+        surfaces: { mcp: true },
+        summary: "Set or clear a task's notes — the prose goal a puller reads to know what done means. An empty/absent `notes` CLEARS them, so never send the field unless you mean to change it",
+        request: z.object({
+            tid: z.string(),
+            notes: z.string().nullable().optional(),
+            workspace: z.string().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean().optional(),
+            tid: z.string().optional(),
+            notes: z.string().nullable().optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", idempotent: true, auth: "member",
+    }),
+    "tasks:priority": receiver({
+        receiver: "tasks:priority",
+        surfaces: { mcp: true },
+        summary: "Set a task's priority from the 1–100 slider. Stored as the 0–1 `task-priority` attribute (slider/100), which is what the board's ranking reads",
+        request: z.object({
+            tid: z.string(),
+            priority: z.number(),
+            workspace: z.string().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean().optional(),
+            tid: z.string().optional(),
+            // The stored 0–1 value, not the 1–100 slider that was sent.
+            priority: z.number().optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", idempotent: true, auth: "member",
+    }),
+    "tasks:schedule": receiver({
+        receiver: "tasks:schedule",
+        surfaces: { mcp: true },
+        summary: "Set or clear a task's start/due dates — what the Gantt reads. PRESENCE of a field decides whether it is touched; an empty value clears it. An inverted range (start after due) is refused before any DB access",
+        request: z.object({
+            tid: z.string(),
+            dueAt: z.string().nullable().optional(),
+            startAt: z.string().nullable().optional(),
+            workspace: z.string().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean().optional(),
+            tid: z.string().optional(),
+            dueAt: z.string().nullable().optional(),
+            startAt: z.string().nullable().optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", idempotent: true, auth: "member",
+    }),
+    "tasks:tag": receiver({
+        receiver: "tasks:tag",
+        surfaces: { mcp: true },
+        summary: "Add and/or remove board tags on a task. Plain words only — the `workspace:` and `@` namespaces are system-owned and are silently dropped, because they decide tenancy and assignment",
+        request: z.object({
+            tid: z.string(),
+            add: z.array(z.string()).optional(),
+            remove: z.array(z.string()).optional(),
+            workspace: z.string().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean().optional(),
+            tid: z.string().optional(),
+            add: z.array(z.string()).optional(),
+            remove: z.array(z.string()).optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", idempotent: true, auth: "member",
+    }),
+    "tasks:reassign": receiver({
+        receiver: "tasks:reassign",
+        surfaces: { mcp: true },
+        summary: "Move one task to a different assignee IN PLACE — swaps the `@<slug>` tag and announces on the new tag set. An empty assignee unassigns it, and moves a `picked` task back to `open` so it is genuinely claimable again (claimable = open AND unassigned). This is the verb the task sheet's Reassign button was missing: it resolved through `buildAssign` to tasks:create and filed a duplicate `Handle: <title>` task instead",
+        request: z.object({
+            tid: z.string(),
+            // Actor slug. Empty/null unassigns. A leading '@' is accepted and stripped.
+            assignee: z.string().nullable().optional(),
+            workspace: z.string().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean().optional(),
+            tid: z.string().optional(),
+            assignee: z.string().nullable().optional(),
+            // Who held it before, so the caller can say "moved from X to Y" without a re-read.
+            previous: z.string().nullable().optional(),
+            tags: z.array(z.string()).optional(),
+            unchanged: z.boolean().optional(),
+            // Set only when unassigning reopened a `picked` task.
+            status: z.string().optional(),
+            reopened: z.boolean().optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", idempotent: true, auth: "member",
+    }),
+    "tasks:comment": receiver({
+        receiver: "tasks:comment",
+        surfaces: { mcp: true },
+        summary: "Post a comment on a task's thread, or read the thread back when `body` is omitted. An @mention in the body subscribes that actor to the task. A reader (viewer) may comment even where it cannot move the task. Address by tid, or by the /do slug — same two-way contract as claim/link, so a wave-close heartbeat does not need the generated tid",
+        request: z.object({
+            tid: z.string().optional(),
+            slug: z.string().optional(),
+            body: z.string().optional(),
+            workspace: z.string().optional(),
+        }).refine((v) => !!v.tid || !!v.slug, {
+            message: "address the task by tid or slug",
+            path: ["tid"],
+        }),
+        response: z.object({
+            ok: z.boolean().optional(),
+            tid: z.string().optional(),
+            messages: z.array(z.record(z.string(), z.unknown())).optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", idempotent: false, auth: "member",
+    }),
+    "tasks:subtask": receiver({
+        receiver: "tasks:subtask",
+        surfaces: { mcp: true },
+        summary: "Create a child task and hang it under its parent with `containment` in one write. Reuses create's insert path — there is no second task-insert anywhere",
+        request: z.object({
+            parent: z.string(),
+            title: z.string(),
+            tags: z.array(z.string()).optional(),
+            assignee: z.string().optional(),
+            workspace: z.string().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean().optional(),
+            tid: z.string().optional(),
+            parent: z.string().optional(),
+            tags: z.array(z.string()).optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", idempotent: false, auth: "member",
+    }),
+    "tasks:depend": receiver({
+        receiver: "tasks:depend",
+        surfaces: { mcp: true },
+        summary: "Record that a task is blocked by another — the `blocks` edge the claim gate reads. Refuses a self-edge and a reverse edge (cycle); both ends must be in the caller's workspace",
+        request: z.object({
+            tid: z.string(),
+            blockedBy: z.string(),
+            workspace: z.string().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean().optional(),
+            tid: z.string().optional(),
+            blockedBy: z.string().optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", idempotent: true, auth: "member",
+    }),
+    "tasks:follow": receiver({
+        receiver: "tasks:follow",
+        surfaces: { mcp: true },
+        summary: "Follow one task — a task-grain subscription (a `follows` row with receiver `tasks:announce`), so its announcements reach the caller's inbox. Refused across tenants",
+        request: z.object({
+            tid: z.string(),
+            workspace: z.string().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean().optional(),
+            tid: z.string().optional(),
+            tags: z.array(z.string()).optional(),
+            actor: z.string().optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", idempotent: true, auth: "member",
+    }),
+    "tasks:unfollow": receiver({
+        receiver: "tasks:unfollow",
+        surfaces: { mcp: true },
+        summary: "Stop following one task — deletes exactly that task-grain subscription row, leaving tag-level subscriptions alone",
+        request: z.object({
+            tid: z.string(),
+            workspace: z.string().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean().optional(),
+            tid: z.string().optional(),
+            actor: z.string().optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", idempotent: true, auth: "member",
+    }),
+    "tasks:follows": receiver({
+        receiver: "tasks:follows",
+        summary: "List the tasks the caller follows (task-grain subscriptions only, newest first, cap 100)",
+        request: z.object({
+            workspace: z.string().optional(),
+        }),
+        response: z.object({
+            follows: z.array(z.record(z.string(), z.unknown())),
+        }),
+        effect: "ask", idempotent: true, auth: "member",
+    }),
     "tasks:undepend": receiver({
         receiver: "tasks:undepend",
+        surfaces: { mcp: true },
         summary: "Remove one blocks edge — the inverse of tasks:depend. Deletes exactly the (blockedBy → tid) pair; does not touch task status. Auth: attested caller only, both ends in the caller's workspace",
         request: z.object({
             tid: z.string(),
@@ -1033,6 +1397,7 @@ export const RECEIVERS = {
     }),
     "tasks:link": receiver({
         receiver: "tasks:link",
+        surfaces: { mcp: true },
         summary: "Close the handoff: record that a claimed task was built via /do <slug> — append a provenance line to the task's notes (the id back-ref + doc stems) and move it to done. Auth: attested caller only",
         // The slug IS the handle here — the resolver requires it and resolves the origin tid
         // from the `slug:` tag, treating an explicit tid as an optional override for direct
@@ -1057,18 +1422,31 @@ export const RECEIVERS = {
         effect: "ask", idempotent: true,
     }),
     // ── agents (TRADE / lifecycle) ──
+    // THE PUBLIC DOOR. An arriving agent joins here with no human in the loop and
+    // no prior credential, and gets a SCOPED rung: it may list capabilities and be
+    // paid; it may not spend the compute float until one x402 challenge is
+    // satisfied, and it may never touch another workspace.
+    //
+    // `uid` is OPTIONAL and is never authority. An anonymous caller's identity is
+    // MINTED by the handler and its `uid` is ignored outright; an attested caller
+    // may only name an identity it already controls (callerControlsWorkspace).
+    // That is the whole IDOR rule: the subject is derived, never declared.
     "agents:register": receiver({
         receiver: "agents:register",
-        summary: "Register an agent as a sellable actor with capabilities",
+        surfaces: { mcp: { name: "register" } },
+        summary: "Register as a sellable actor with capabilities. Public: call it with no credential and it mints a scoped identity (returns actorId + apiKey, compute float locked until one x402 payment).",
         request: z.object({
-            uid: z.string(),
+            /** Omit when anonymous — the handler mints one. Naming another agent's uid is refused. */
+            uid: z.string().optional(),
+            /** Display handle for a fresh anonymous registration. Never authority. */
+            name: z.string().optional(),
             kind: z.string().optional(),
             capabilities: z.array(z.object({ skill: z.string(), price: z.number().optional() })).optional(),
             wallet: z.string().optional(),
             chain: z.string().optional(),
         }),
         response: RegisterResponseSchema,
-        effect: "ask", idempotent: true,
+        effect: "ask", auth: "public", idempotent: true,
     }),
     "agents:commend": receiver({
         receiver: "agents:commend",
@@ -1102,26 +1480,35 @@ export const RECEIVERS = {
     // ── pay (TRANSACT — onchain settlement) ──
     "pay:weight": receiver({
         receiver: "pay:weight",
+        surfaces: { mcp: { name: "pay" } },
         summary: "Pay for a task by weighting the path between two actors",
-        request: z.object({ from: z.string(), to: z.string(), task: z.string(), amount: z.number() }),
+        request: z.object({
+            // DERIVED, never sent: the handler sets `from = ctx.ownerSlug` and never reads
+            // data.from. Declaring it required made the binder reject every valid call
+            // before the handler could derive it — and before its own auth check ran.
+            from: z.string().optional(),
+            to: z.string(), task: z.string(), amount: z.number(),
+        }),
         response: PayResponseSchema,
         effect: "ask", cost: "variable", settles: "onchain", reversible: false, simulatable: true,
     }),
     "tasks:stake": receiver({
         receiver: "tasks:stake",
-        summary: "Stake SUI against a task on-chain to raise its priority weight. 0.1 SUI = +1 weight unit. Irreversible — conviction signal, not a deposit.",
+        summary: "Record a visitor-signed stake_on_tags burn on Sui testnet. Caller signs in their wallet (0.1 SUI per weight); the worker verifies the digest and marks the path. No server key. Irreversible. Not a SUI deposit against a Task object.",
         request: z.object({
-            taskObjectId: z.string().regex(/^0x[a-fA-F0-9]{64}$/, "Sui object ID"),
-            units: z.number().int().positive().default(1),
+            tags: z.array(z.string().min(1)).min(1).max(8),
+            addWeight: z.number().int().optional(),
+            digest: z.string().min(20),
         }),
         response: z.object({
             ok: z.boolean(),
             digest: z.string().optional(),
-            weightBefore: z.number().optional(),
-            weightAfter: z.number().optional(),
-            suiSpent: z.number().optional(),
+            newWeight: z.number().optional(),
+            tags: z.array(z.string()).optional(),
+            error: z.string().optional(),
         }),
-        effect: "ask", cost: "variable", settles: "onchain", reversible: false, simulatable: false,
+        effect: "ask", auth: "required", cost: "variable", settles: "onchain", reversible: false, simulatable: false,
+        examples: [{ tags: ["engineering", "ontology", "marketing"], addWeight: 20, digest: "VisitorSignedDigestFromSuiTestnetTx" }],
     }),
     // ── market (A2A negotiation, C2) ──
     "market:offer": receiver({
@@ -1266,7 +1653,11 @@ export const RECEIVERS = {
         receiver: "market:bounty",
         summary: "Post a bounty for a skill, backed by an escrow",
         request: z.object({
-            skillId: z.string(), sellerUid: z.string(), posterUid: z.string(), price: z.number(),
+            skillId: z.string(), sellerUid: z.string(),
+            // DERIVED, never sent: the handler sets `posterUid = ctx.ownerSlug`
+            // (resolvers/market.ts). Required here, it rejected every valid post.
+            posterUid: z.string().optional(),
+            price: z.number(),
             tags: z.array(z.string()).optional(),
             content: z.record(z.string(), z.unknown()).optional(),
             rubric: z.object({
@@ -1301,6 +1692,32 @@ export const RECEIVERS = {
         ]),
         effect: "ask", cost: "free", reversible: false, idempotent: false,
     }),
+    "market:search": receiver({
+        receiver: "market:search",
+        summary: "Search the whole marketplace catalog — agents, skills, plugins, live listings and open bounties — and get back named, card-shaped results",
+        request: z.object({
+            q: z.string().describe("What the shopper is looking for, in their own words"),
+            kind: z.enum(["agent", "skill", "plugin", "listing", "bounty"]).optional(),
+            limit: z.number().int().positive().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            total: z.number(),
+            matched: z.number(),
+            results: z.array(z.object({
+                kind: z.string(), ref: z.string(), title: z.string(), blurb: z.string(),
+                tags: z.array(z.string()),
+                // null means "carries no price" — never render it as 0. `priceLabel` is
+                // the honest string for a card ("from 25 credits", "$49", or null).
+                price: z.number().nullable(), unit: z.string().nullable(),
+                sellers: z.number(), priceLabel: z.string().nullable(), url: z.string(),
+            })),
+        }),
+        // Browse is public on /marketplace and public here — the concierge answers
+        // "who sells X" for a signed-out visitor, which is the whole point.
+        auth: "open",
+        effect: "ask", cost: "free", idempotent: true,
+    }),
     "market:list": receiver({
         receiver: "market:list",
         summary: "List the capability market",
@@ -1313,7 +1730,13 @@ export const RECEIVERS = {
         receiver: "capabilities:publish",
         summary: "Publish a capability (skill listing) to the market",
         request: z.object({
-            skillId: z.string(), name: z.string(), price: z.number(),
+            skillId: z.string(), name: z.string(),
+            // OPTIONAL — `market.ts` reads it as `Math.max(0, num(...))`, so an
+            // omitted price is a free listing, not a refusal. Declaring it required
+            // meant the edge rejected a call the resolver was written to accept, the
+            // same drift that took `subscriptions:register` down once bind-receiver
+            // began enforcing declared schemas.
+            price: z.number().optional(),
             mode: z.string().optional(), visibility: z.string().optional(), scope: z.string().optional(), entitlement: z.string().optional(),
             tags: z.array(z.string()).optional(),
             rubricThresholds: z.object({
@@ -1341,6 +1764,7 @@ export const RECEIVERS = {
     }),
     "stats:current": receiver({
         receiver: "stats:current",
+        surfaces: { mcp: { name: "stats" } },
         summary: "Current world stats — units, skills, highways, revenue, signals",
         request: z.object({}),
         response: StatsSchema,
@@ -1371,6 +1795,7 @@ export const RECEIVERS = {
     // ════════════════════════════════════════════════════════════════════════
     "meta:catalog": receiver({
         receiver: "meta:catalog",
+        surfaces: { mcp: true },
         summary: "List every receiver the caller can use (with cost/reversibility/settlement), or a goal's recipe",
         request: z.object({ goal: z.enum(["spine", "build", "trade", "transact"]).optional() }),
         response: z.union([
@@ -1385,6 +1810,7 @@ export const RECEIVERS = {
     }),
     "meta:schema": receiver({
         receiver: "meta:schema",
+        surfaces: { mcp: true },
         summary: "JSON Schema for one receiver's request + response — read it before you call",
         request: z.object({ receiver: z.string() }),
         response: z.object({
@@ -1395,6 +1821,7 @@ export const RECEIVERS = {
     }),
     "meta:recall": receiver({
         receiver: "meta:recall",
+        surfaces: { mcp: true },
         summary: "Recall the caller's hypotheses (memory), optionally filtered by a search term",
         request: z.object({ match: z.string().optional(), limit: z.number().optional() }),
         response: z.object({
@@ -1422,6 +1849,7 @@ export const RECEIVERS = {
     }),
     "meta:types": receiver({
         receiver: "meta:types",
+        surfaces: { mcp: true },
         summary: "Read the resource-type manifest for the caller's workspace, plus the built-in industry templates",
         request: z.object({}),
         response: z.object({
@@ -1542,6 +1970,13 @@ export const RECEIVERS = {
     }),
     "notify": receiver({
         receiver: "notify",
+        // NOT surfaces.mcp — the curated `message` tool in packages/mcp/src/tools/
+        // messaging.ts already fronts this receiver and carries shaping the registry
+        // cannot infer: it defaults `kind: "message"` and names the argument
+        // `content` in a description written for a sender, not a schema. Flagging it
+        // produced two tools called `message`, of which the curated one won
+        // registration and the derived one was dead weight. Curated survives here;
+        // the registry does not claim a surface something else already serves.
         summary: "Notify any actor (human or agent) by uid — channels routes the door (Telegram/Discord/peer inbox), mirrors into the web inbox, nudges an open client live, and sends a web push if the recipient subscribed. One verb, both actor kinds. An optional action renders as one tap-through link.",
         request: z.object({
             receiver: z.string(),
@@ -1971,14 +2406,30 @@ export const RECEIVERS = {
             images: z.array(z.string()).optional(),
             product_type: z.string().optional(), // default 'one_time'
             collection: z.string().optional(),
+            // Same stripped-at-the-edge trap as the two artifact fields below, and it
+            // cost more: resolvers/commerce.ts has read `data.status` since it shipped,
+            // but the key was never declared here, so zod dropped it and EVERY product
+            // created through this receiver came back 'draft'. Proven behaviourally
+            // 2026-08-23 — POST with status:"active" returned 200, the row read 'draft'.
+            // An agent could list a product and had no way to make it sellable.
+            status: z.enum(["draft", "active", "archived"]).optional(),
+            // The ARTIFACT listing door. Declared here because validateReceiver returns
+            // zod's PARSED output, so an undeclared key is stripped at the HTTP edge and
+            // never reaches the handler. `delivery_r2_key` is accepted ONLY as a
+            // `{kind}:{ref}` install descriptor — the plain-R2-key write door stays shut.
+            product_kind: z.literal("artifact").optional(),
+            delivery_r2_key: z.string().optional(),
         }),
         response: z.object({ pid: z.string().optional(), ppid: z.string().optional(), name: z.string().optional(), workspace: z.string().optional(), error: z.string().optional() }),
         effect: "ask", cost: "free", reversible: true, idempotent: false, auth: "member",
     }),
     "products:update": receiver({
         receiver: "products:update",
-        summary: "Update a product's name, description, images, or collection",
-        request: z.object({ slug: z.string(), pid: z.string(), name: z.string().optional(), description: z.string().optional(), images: z.array(z.string()).optional(), collection: z.string().optional() }),
+        summary: "Update a product's name, description, images, collection, or status",
+        // `status` carries the same history as on products:create — the resolver has
+        // always read it, the declaration never listed it, so zod stripped it and a
+        // draft product could not be published through this receiver either.
+        request: z.object({ slug: z.string(), pid: z.string(), name: z.string().optional(), description: z.string().optional(), images: z.array(z.string()).optional(), collection: z.string().optional(), status: z.enum(["draft", "active", "archived"]).optional(), product_kind: z.literal("artifact").optional(), delivery_r2_key: z.string().optional() }),
         response: z.object({ pid: z.string().optional(), workspace: z.string().optional(), error: z.string().optional() }),
         effect: "ask", cost: "free", reversible: false, idempotent: true, auth: "member",
     }),
@@ -2003,6 +2454,429 @@ export const RECEIVERS = {
         response: z.object({ pid: z.string().optional(), workspace: z.string().optional(), status: z.string().optional(), error: z.string().optional() }),
         effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
     }),
+    // ── variants (product options: size/colour) — handlers in resolvers/commerce.ts ─
+    // stock IS NULL means UNTRACKED, never zero: a service or digital product is
+    // never blocked by an inventory check it did not opt into. On update, an ABSENT
+    // stock field leaves the value unchanged; an explicit null sets untracked.
+    "variants:list": receiver({
+        receiver: "variants:list",
+        summary: "List a product's active variants with SKU, price, weight and stock (public)",
+        request: z.object({ slug: z.string(), pid: z.string() }),
+        response: z.object({ variants: z.array(z.record(z.string(), z.unknown())).optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "public",
+    }),
+    "variants:create": receiver({
+        receiver: "variants:create",
+        summary: "Add a variant to a product — its own SKU, price, weight and stock",
+        request: z.object({
+            slug: z.string(),
+            pid: z.string(),
+            title: z.string(), // "Blue / M"
+            unit_amount: z.number().int(), // cents
+            sku: z.string().optional(),
+            options: z.record(z.string(), z.string()).optional(),
+            currency: z.string().optional(), // default 'usd'
+            weight_grams: z.number().int().optional(),
+            stock: z.number().int().nullable().optional(), // null/absent = untracked
+            position: z.number().int().optional(),
+        }),
+        response: z.object({ vid: z.string().optional(), pid: z.string().optional(), workspace: z.string().optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: false, auth: "member",
+    }),
+    "variants:update": receiver({
+        receiver: "variants:update",
+        summary: "Update a variant — omit stock to leave it unchanged, send null to make it untracked",
+        request: z.object({
+            slug: z.string(),
+            vid: z.string(),
+            title: z.string().optional(),
+            unit_amount: z.number().int().optional(),
+            sku: z.string().optional(),
+            options: z.record(z.string(), z.string()).optional(),
+            currency: z.string().optional(),
+            weight_grams: z.number().int().optional(),
+            stock: z.number().int().nullable().optional(), // absent is not null: absent leaves it unchanged
+            position: z.number().int().optional(),
+            active: z.boolean().optional(),
+        }),
+        response: z.object({ vid: z.string().optional(), workspace: z.string().optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
+    }),
+    "variants:archive": receiver({
+        receiver: "variants:archive",
+        summary: "Archive a variant (reversible via variants:update { active: true })",
+        request: z.object({ slug: z.string(), vid: z.string() }),
+        response: z.object({ vid: z.string().optional(), workspace: z.string().optional(), active: z.number().optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
+    }),
+    // ── cart (server-truth basket) — handlers land in resolvers/cart.ts (C3) ───────
+    // Registered here, not by C3: signals-parity counts RECEIVERS against
+    // text/signals-catalog.md and is a live accept: on another kept promise.
+    // `cid` is a server-minted bearer capability (never client-chosen), which is
+    // what makes an anonymous cart safe at auth: "public". No request carries a
+    // unit_amount — every line is re-priced server-side from D1 by ppid/vid.
+    "cart:get": receiver({
+        receiver: "cart:get",
+        summary: "Read a cart and its lines by server-minted cart id",
+        request: z.object({ slug: z.string(), cid: z.string() }),
+        response: z.object({ cart: z.record(z.string(), z.unknown()).nullable().optional(), items: z.array(z.record(z.string(), z.unknown())).optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "public",
+    }),
+    "cart:add": receiver({
+        receiver: "cart:add",
+        summary: "Add a product (or variant) line to a cart, minting the cart when cid is absent — price is read server-side, never sent",
+        request: z.object({
+            slug: z.string(),
+            pid: z.string(),
+            cid: z.string().optional(), // absent mints a new cart
+            ppid: z.string().optional(),
+            vid: z.string().optional(),
+            quantity: z.number().int().positive().optional(), // default 1
+        }),
+        response: z.object({ cid: z.string().optional(), ciid: z.string().optional(), items: z.array(z.record(z.string(), z.unknown())).optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: false, auth: "public",
+    }),
+    "cart:update": receiver({
+        receiver: "cart:update",
+        summary: "Set a cart line's quantity (0 removes the line)",
+        request: z.object({ slug: z.string(), cid: z.string(), ciid: z.string(), quantity: z.number().int().min(0) }),
+        response: z.object({ cid: z.string().optional(), items: z.array(z.record(z.string(), z.unknown())).optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "public",
+    }),
+    "cart:remove": receiver({
+        receiver: "cart:remove",
+        summary: "Remove one line from a cart",
+        request: z.object({ slug: z.string(), cid: z.string(), ciid: z.string() }),
+        response: z.object({ cid: z.string().optional(), items: z.array(z.record(z.string(), z.unknown())).optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: false, idempotent: true, auth: "public",
+    }),
+    "cart:clear": receiver({
+        receiver: "cart:clear",
+        summary: "Empty a cart, keeping the cart itself",
+        request: z.object({ slug: z.string(), cid: z.string() }),
+        response: z.object({ cid: z.string().optional(), cleared: z.number().optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: false, idempotent: true, auth: "public",
+    }),
+    // ── orders (the one operator write door) — handler lands in resolvers (C5) ─────
+    // data-bindings.ts:62 marks `order` create/update/archive as null by design:
+    // orders are webhook-minted and otherwise read-only. This is the deliberate
+    // exception. `status` is z.string(), not an enum — the D1 column is bare TEXT
+    // (0118_orders.sql:15) and C5's resolver owns the allowlist.
+    "orders:status": receiver({
+        receiver: "orders:status",
+        summary: "Set an order's status — the one operator write on a webhook-minted record",
+        request: z.object({ slug: z.string(), oid: z.string(), status: z.string() }),
+        response: z.object({ oid: z.string().optional(), workspace: z.string().optional(), status: z.string().optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
+    }),
+    // ── order:claim — the buyer's delivery door (handler: resolvers/commerce.ts) ──
+    // Declared so the route's envelope guard fires: an undeclared receiver skips
+    // the `envelope_missing` check, and a flat body silently validates as {}.
+    // `auth: "public"` because an anonymous buyer claims with the order's own
+    // session_id as bearer proof; the handler holds the real attestation (session
+    // match OR ctx-attested workspace control), never a body-supplied identity.
+    "order:claim": receiver({
+        receiver: "order:claim",
+        summary: "Claim a paid order's delivery — returns a scoped download URL for the digital good",
+        request: z.object({
+            oid: z.string(),
+            workspace: z.string().optional(),
+            session_id: z.string().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean().optional(),
+            url: z.string().optional(),
+            name: z.string().optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "none", auth: "public",
+        examples: [{ oid: "ord_1", session_id: "cs_test_1" }],
+    }),
+    // ── order:install — the buyer's ARTIFACT door (handler: resolvers/install.ts) ──
+    // The sibling of order:claim, and deliberately NOT the same receiver. order:claim
+    // is `auth: "public"` because it hands back a FILE: knowing (oid, session_id) is
+    // the whole proof, which is right for a crypto buyer who never signs in. Install
+    // inverts the direction of authority — a SELLER's product causes a WRITE into a
+    // BUYER's workspace — so it is the IDOR shape ~80 workspace routes were already
+    // fixed for, and it gets a tenant-class label (`manage_things`) so bind-receiver's
+    // AUTH_POLICY floor is ENFORCED before the handler runs. The handler then walks
+    // the destination with callerControlsWorkspace(ctx.ownerSlug, …); `workspace` in
+    // the body NAMES a target, it never authorizes one. order:claim is untouched.
+    "order:install": receiver({
+        receiver: "order:install",
+        summary: "Install a paid artifact order into a workspace the caller controls — routes to skill:save / world:publish-agent / workflow:create / view:create by the delivery descriptor's kind",
+        request: z.object({
+            oid: z.string(),
+            workspace: z.string().optional(), // destination; defaults to the attested caller
+            session_id: z.string().optional(), // the order's own receipt, as in order:claim
+        }),
+        response: z.object({
+            ok: z.boolean().optional(),
+            kind: z.enum(["skill", "agent", "workflow", "view", "playbook"]).optional(),
+            ref: z.string().optional(),
+            workspace: z.string().optional(),
+            installed: z.record(z.string(), z.unknown()).optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", reversible: false, idempotent: false, settles: "none", auth: "manage_things",
+        examples: [{ oid: "ord_1", session_id: "cs_test_1" }, { oid: "ord_1", workspace: "elitemoversca" }],
+    }),
+    // ── wallet:create — register RECEIVING ADDRESSES only (handler: resolvers/wallet.ts) ──
+    // Custody invariant: `addresses` carries public addresses and nothing else. No
+    // field here accepts a private key or a mnemonic, and none is emitted back.
+    // Omitting `addresses` provisions an address-less row (the pre-existing
+    // idempotent path); supplying it merges first-write-wins per chain.
+    "wallet:create": receiver({
+        receiver: "wallet:create",
+        summary: "Provision a wallet row for an actor and register its public receiving addresses (first-write-wins per chain)",
+        request: z.object({
+            workspace: z.string().optional(),
+            actor: z.string().optional(),
+            kind: z.enum(["human", "agent"]).optional(),
+            addresses: z.object({
+                sui: z.string().nullable().optional(),
+                evm: z.string().nullable().optional(),
+                solana: z.string().nullable().optional(),
+                btc: z.string().nullable().optional(),
+            }).optional(),
+        }),
+        response: z.object({
+            ok: z.boolean().optional(),
+            actor: z.string().optional(),
+            workspace: z.string().optional(),
+            kind: z.string().optional(),
+            addresses: z.object({
+                sui: z.string().nullable().optional(),
+                evm: z.string().nullable().optional(),
+                solana: z.string().nullable().optional(),
+                btc: z.string().nullable().optional(),
+            }).optional(),
+            error: z.string().optional(),
+            field: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", reversible: false, idempotent: true, settles: "none", auth: "member",
+        examples: [{ workspace: "acme", kind: "human", addresses: { sui: "0xabc", evm: "0xdef" } }],
+    }),
+    // ── wallet:rehearse — READ a TESTNET transaction back (handler: resolvers/wallet.ts) ──
+    // The rehearsal step of the /u/one funnel: a visitor sends play money on Sui
+    // testnet from their own derived address, and this reads the digest back so the
+    // chat can say what actually happened on chain.
+    //
+    // IT GRANTS NOTHING, and that is the whole contract — `credits` is a
+    // z.literal(0), so the response schema itself forbids a grant. The reason is
+    // not squeamishness: `currentBalance` (web/src/lib/credits.ts) sums
+    // `credit_grants` with NO `test_mode` filter, so a credit granted for testnet
+    // money would be real, fully spendable credit minted out of play money.
+    //
+    // `network` is a z.literal("testnet") on BOTH sides. There is deliberately no
+    // parameter by which a caller could point this at mainnet — the resolver
+    // hardcodes the testnet RPC. A mainnet read belongs to the settling rail
+    // (pay's payment_link_claim), which moves money and therefore takes attestation.
+    //
+    // auth "public" because it neither writes nor grants: a chain read with a rate
+    // limit, placed in front of anonymous workspace-root traffic. The resolver
+    // limits per ATTESTED `ctx.visitorHash` — the shape `movers:funnel-provision`
+    // already uses. A caller may name an address; it can never name a spend.
+    "wallet:rehearse": receiver({
+        receiver: "wallet:rehearse",
+        summary: "Read a TESTNET Sui transaction back and report it. Grants nothing, settles nothing, never writes a credit_grants row.",
+        request: z.object({
+            chain: z.literal("sui"),
+            network: z.literal("testnet"),
+            digest: z.string().min(1).describe("The transaction digest the sender broadcast"),
+            address: z.string().optional().describe("The sender address — PUBLIC only, never a key"),
+        }),
+        response: z.object({
+            verified: z.boolean(),
+            network: z.literal("testnet"),
+            credits: z.literal(0).describe("Always 0. Testnet money buys nothing."),
+            amount: z.string().nullable().optional(),
+            sender: z.string().nullable().optional(),
+            explorerUrl: z.string().nullable().optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "none", auth: "public",
+        examples: [{ chain: "sui", network: "testnet", digest: "8xKvQ1", address: "0xabc" }],
+    }),
+    // ── The wallet estate, declared ────────────────────────────────────────────
+    //
+    // wallet:get / :send / :transactions / :invoice have run in production since
+    // wallets-workspace shipped (handlers: resolvers/wallet.ts:643) with NO entry
+    // here at all. Undeclared, they were invisible to `meta:catalog`, absent from
+    // MCP, and passed through the /api/ask edge with no schema gate whatsoever.
+    //
+    // DECLARING A LIVE RECEIVER IS NOT FREE. The ask route dispatches
+    // `validation.payload` — zod's PARSED output (pages/api/ask/[...receiver].ts:358)
+    // — so a field a real caller sends and a schema here omits is SILENTLY
+    // STRIPPED before the handler reads it. Every field below was read back off
+    // the resolver and off its callers (packages/cli/src/wallet.ts,
+    // template/site/src/pages/wallet.astro). Add a field to a handler ⇒ add it
+    // here in the same diff, or the handler stops seeing it.
+    //
+    // `surfaces: { mcp: true }` is what actually creates the MCP tool.
+    // `mcpToolsFromRegistry()` is default-closed (`if (!mcp) continue`,
+    // packages/mcp/src/tools/from-registry.ts:79), so the declaration alone would
+    // have left MCP with zero wallet tools — the exact gap this cycle closes.
+    "wallet:get": receiver({
+        receiver: "wallet:get",
+        surfaces: { mcp: true },
+        summary: "Read one workspace's wallet estate — credits, spend ceiling, wallet rows with payTo, live chain balances, delegated wallets",
+        request: z.object({
+            workspace: z.string().optional().describe("Defaults to the attested caller's workspace"),
+            actor: z.string().optional().describe("Actor whose spend ceiling is read; defaults to the workspace"),
+        }),
+        response: z.object({
+            workspace: z.string().optional(),
+            actor: z.string().optional(),
+            credits: z.number().optional(),
+            wallets: z.array(z.record(z.string(), z.unknown())).optional(),
+            spendCeiling: z.object({
+                limitCredits: z.number(), spentCredits: z.number(), remainingCredits: z.number(),
+            }).nullable().optional(),
+            balances: z.array(z.object({
+                actor: z.string(), chain: z.string(), address: z.string(), balance: z.string().nullable(),
+            })).optional(),
+            addresses: z.array(z.object({ actor: z.string(), chain: z.string(), address: z.string() })).optional(),
+            delegated: z.array(z.record(z.string(), z.unknown())).optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "none", auth: "member",
+        examples: [{}, { workspace: "acme" }, { workspace: "acme", actor: "agent:scout" }],
+    }),
+    "wallet:transactions": receiver({
+        receiver: "wallet:transactions",
+        surfaces: { mcp: true },
+        summary: "The unified settlement feed for one workspace — every rail, money in and out, newest first",
+        request: z.object({
+            workspace: z.string().optional().describe("Defaults to the attested caller's workspace"),
+            limit: z.number().optional().describe("Rows to return; the handler caps at 500"),
+        }),
+        response: z.object({
+            transactions: z.array(z.object({
+                ts: z.number(), rail: z.string(), direction: z.enum(["in", "out"]), counterparty: z.string(),
+                amountCents: z.number(), currency: z.string(), ref: z.string(), status: z.string(),
+            })).optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "none", auth: "member",
+        examples: [{ limit: 20 }, { workspace: "acme", limit: 100 }],
+    }),
+    // The caller signs and broadcasts the transfer CLIENT-SIDE and passes the
+    // resulting `paymentTx`; this composes pay.one.ie's create → quote → claim and
+    // never holds a key. It VERIFIES that an on-chain transfer settled, so it
+    // declares `settles: "onchain"` and `reversible: false`. A catalog that said
+    // otherwise would put a lie where the omission used to be.
+    "wallet:send": receiver({
+        receiver: "wallet:send",
+        surfaces: { mcp: true },
+        summary: "Settle a crypto transfer the caller already signed and broadcast — mints, prices and claims a pay.one.ie link. Never signs; no private key crosses this boundary",
+        request: z.object({
+            to: z.string().describe("Recipient address — public only"),
+            chain: z.string().describe("SOL | ETH | BASE | ARB | OPT | BTC | SUI"),
+            amount: z.number().describe("Must be > 0"),
+            paymentTx: z.string().describe("The tx hash from signing and broadcasting client-side"),
+            workspace: z.string().optional().describe("Source workspace; falls back to `from`, then the attested caller"),
+            from: z.string().optional().describe("Alias for `workspace` — the source the authority walk runs against"),
+            unit: z.enum(["usd", "token"]).optional(),
+            currency: z.enum(["NATIVE", "USDC"]).optional(),
+            userAddress: z.string().optional().describe("Sender address; defaults to `to`"),
+            memo: z.string().optional(),
+            product: z.string().optional().describe("Falls back to `memo`, then a generated transfer label"),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            from: z.string().optional(),
+            to: z.string().optional(),
+            chain: z.string().optional(),
+            amount: z.number().optional(),
+            link: z.string().optional(),
+            quoteId: z.string().optional(),
+            paymentTx: z.string().optional(),
+            treasury: z.string().optional(),
+            receipt: z.object({ id: z.string(), url: z.string() }).optional(),
+            claimed: z.boolean().optional(),
+            stage: z.string().optional().describe("Which pay call failed: create | quote | claim"),
+            error: z.string().optional(),
+        }),
+        effect: "ask", cost: "variable", reversible: false, idempotent: false, settles: "onchain", auth: "manage_workspace",
+        examples: [{ to: "0xabc", chain: "SUI", amount: 5, paymentTx: "8xKvQ1" }],
+    }),
+    // A pending, attributed `settlements` row is written before a cent moves —
+    // INSERT OR IGNORE keyed on the pay link id, so a retry with the same link is a
+    // no-op. An unpayable actor is a clean refusal: no link minted, no row written.
+    "wallet:invoice": receiver({
+        receiver: "wallet:invoice",
+        surfaces: { mcp: true },
+        summary: "Hand a payable actor a working payment link, with the money attributed to it before a cent moves",
+        request: z.object({
+            actor: z.string().describe("The actor being paid — attributed here even when custody is via-treasury"),
+            amountCents: z.number().describe("Must be > 0"),
+            workspace: z.string().optional().describe("Defaults to the attested caller's workspace"),
+            currency: z.string().optional().describe("Defaults to usd"),
+        }),
+        response: z.object({
+            url: z.string().optional(),
+            linkId: z.string().optional(),
+            payTo: z.object({
+                // An OPEN string, never an enum. 'self' | 'via-treasury' | 'none' today;
+                // wallet-authority's ScopedWallet adds 'scoped' (payee = an object id,
+                // no chain), and that must not need a registry change to be
+                // representable. An UNKNOWN value is refused BY NAME at payee resolution
+                // (`unsupported_custody:<value>`, resolvers/wallet.ts) — never a crash,
+                // never a silent fallback to 'self' or to the SUI rail.
+                custody: z.string(),
+                chain: z.string().optional(),
+                address: z.string().optional(),
+                attributeTo: z.string().optional(),
+            }).optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "none", auth: "manage_workspace",
+        examples: [
+            { actor: "agent:scout", amountCents: 2500 },
+            { workspace: "acme", actor: "agent:scout", amountCents: 2500, currency: "usd" },
+        ],
+    }),
+    // wallet:portfolio — the authority walk projected onto wallet rows. One call
+    // answers "what does my whole estate hold", which no client could ask before:
+    // every wallet read was scoped to one workspace at a time.
+    //
+    // Deliberately NO chain balances. `wallet:get` fans out one RPC per address,
+    // which is right for one workspace and quadratic across an estate. Portfolio
+    // NAMES the estate; `wallet:get` prices one workspace in it.
+    "wallet:portfolio": receiver({
+        receiver: "wallet:portfolio",
+        surfaces: { mcp: true },
+        summary: "Every wallet row in every workspace the caller controls — one call, no per-address chain reads",
+        request: z.object({
+            limit: z.number().optional().describe("Max child workspaces to include; capped at 100"),
+        }),
+        response: z.object({
+            caller: z.string().optional(),
+            workspaces: z.array(z.object({
+                workspace: z.string(),
+                wallets: z.array(z.record(z.string(), z.unknown())),
+            })).optional(),
+            count: z.number().optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "none", auth: "member",
+        examples: [{}, { limit: 25 }],
+    }),
+    // The door that lets a workspace open its own shop. Until this existed, the
+    // only writers of `owners.storefront_enabled` lived under the Stripe Connect
+    // OAuth callbacks, so selling anything required a human with a browser and a
+    // business — including on the crypto rail, which needs no Stripe account at
+    // all (deriveRails gives a treasury-only seller the crypto rail already).
+    // Authorized by the owners-tree walk, so a parent can open a client's shop.
+    "storefront:enable": receiver({
+        receiver: "storefront:enable",
+        summary: "Open (or close) a workspace's storefront — the gate every checkout mint reads",
+        request: z.object({ slug: z.string().optional(), enabled: z.boolean().optional() }),
+        response: z.object({ ok: z.boolean().optional(), slug: z.string().optional(), enabled: z.boolean().optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
+        examples: [{ slug: "acme" }, { slug: "acme", enabled: false }],
+    }),
     "storefront:stats": receiver({
         receiver: "storefront:stats",
         summary: "Storefront funnel stats — views, checkouts, purchases, revenue, per-product breakdown",
@@ -2020,6 +2894,7 @@ export const RECEIVERS = {
     // ── view:* — saved views (custom-views C1). A view is a workspace-scoped Thing (world_things type 'view'). ──
     "view:create": receiver({
         receiver: "view:create",
+        surfaces: { mcp: { name: "create_view" } },
         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() }),
@@ -2027,6 +2902,7 @@ export const RECEIVERS = {
     }),
     "view:list": receiver({
         receiver: "view:list",
+        surfaces: { mcp: { name: "list_views" } },
         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() })) }),
@@ -2056,6 +2932,7 @@ export const RECEIVERS = {
     // ── pages + workspace settings — handlers in resolvers/pages.ts ────────────────
     "pages:create": receiver({
         receiver: "pages:create",
+        surfaces: { mcp: true },
         summary: "Create a workspace page (draft) from a title + sections",
         request: z.object({ slug: z.string(), title: z.string(), sections: z.array(z.object({ component: z.string(), props: z.record(z.string(), z.unknown()) })), pageSlug: z.string().optional() }),
         response: z.object({ ok: z.boolean(), slug: z.string().optional(), title: z.string().optional(), url: z.string().optional(), status: z.string().optional(), error: z.string().optional() }),
@@ -2070,6 +2947,7 @@ export const RECEIVERS = {
     }),
     "pages:list": receiver({
         receiver: "pages:list",
+        surfaces: { mcp: true },
         summary: "List a workspace's pages with status",
         request: z.object({ slug: z.string() }),
         response: z.object({ pages: z.array(z.object({ slug: z.string(), title: z.string(), status: z.string() })) }),
@@ -2180,10 +3058,24 @@ export const RECEIVERS = {
         response: z.object({ ok: z.boolean(), slug: z.string().optional(), message: z.string().optional(), error: z.string().optional() }),
         effect: "ask", cost: "free", reversible: true, idempotent: false, auth: "member",
     }),
+    "settings:set-home-page": receiver({
+        receiver: "settings:set-home-page",
+        summary: "Name which published page a workspace serves at its root",
+        request: z.object({ slug: z.string(), page: z.string() }),
+        response: z.object({ ok: z.boolean(), page: z.string().optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
+    }),
     "domain:set": receiver({
         receiver: "domain:set",
         summary: "Bind a custom domain to a workspace — returns the verification TXT/CNAME records to add",
-        request: z.object({ slug: z.string(), actorId: z.string(), host: z.string() }),
+        request: z.object({
+            slug: z.string(),
+            // DERIVED, never sent: "the body used to carry `actorId`" — it was removed
+            // by the IDOR fix in resolvers/pages.ts, which authorizes from the ATTESTED
+            // caller only. Requiring it here demanded a field the fix stopped trusting.
+            actorId: z.string().optional(),
+            host: z.string(),
+        }),
         response: z.object({ ok: z.boolean(), intent: z.string().optional(), host: z.string().optional(), verifyToken: z.string().optional(), txtRecord: z.string().optional(), cnameTarget: z.string().optional(), reason: z.string().optional() }),
         effect: "ask", cost: "free", reversible: true, idempotent: false, auth: "verify_domain",
     }),
@@ -2244,6 +3136,159 @@ export const RECEIVERS = {
         response: z.object({ ok: z.boolean(), skillRef: z.string().optional() }),
         effect: "ask", cost: "free", reversible: true, idempotent: false, auth: "member",
     }),
+    // ── company — the COMPANY WORKFLOW's crawl steps, handlers in resolvers/company.ts ──
+    //
+    // The crawl ladder underneath these is plain fetch -> Cloudflare Browser Rendering
+    // (only when the page is a JS shell). `via` names the rung that answered and
+    // `degraded` names why a lower one did, so a caller is never told a partial read
+    // was a full one. None of them writes; foundation:save is the single write.
+    "company:render": receiver({
+        receiver: "company:render",
+        summary: "Read ONE page of a company's site and extract what it says about the company — plain fetch first, Cloudflare Browser Rendering only for a JS shell. Returns a Foundation patch plus provenance-fenced page text; never fabricates a field",
+        request: z.object({ url: z.string(), waitFor: z.number().int().optional() }),
+        response: z.object({
+            ok: z.boolean(),
+            url: z.string().optional(),
+            finalUrl: z.string().optional(),
+            domain: z.string().optional(),
+            via: z.enum(["fetch", "cloudflare"]).optional(),
+            degraded: z.string().optional(),
+            patch: z.unknown().optional(),
+            evidence: z.string().optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "public",
+    }),
+    "company:map": receiver({
+        receiver: "company:map",
+        summary: "Discover a site's structure from its homepage anchors and classify them (pricing/about/product/blog/contact/legal). Depth 1 — this is NOT a crawl and starts no crawl job",
+        request: z.object({ url: z.string(), limit: z.number().int().min(1).max(50).optional() }),
+        response: z.object({
+            ok: z.boolean(),
+            url: z.string().optional(),
+            via: z.enum(["fetch", "cloudflare"]).optional(),
+            degraded: z.string().optional(),
+            links: z.unknown().optional(),
+            priority: z.array(z.string()).optional(),
+            count: z.number().optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "public",
+    }),
+    "company:seo": receiver({
+        receiver: "company:seo",
+        summary: "Read the SEO surface for a domain (keywords, backlinks, AI visibility) via DataForSEO and return it as a Foundation patch. SPENDS REAL CREDIT, so it skips itself with {ok:true,patch:{},skipped:'no_workspace'} when there is no attested workspace",
+        request: z.object({ domain: z.string(), slug: z.string().optional() }),
+        response: z.object({
+            ok: z.boolean(),
+            patch: z.unknown().optional(),
+            domain: z.string().optional(),
+            skipped: z.string().optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", cost: "variable", reversible: true, idempotent: false, auth: "member",
+    }),
+    // ── foundation — handlers in resolvers/foundation.ts ──────────────────────────
+    "foundation:deep": receiver({
+        receiver: "foundation:deep",
+        summary: "Run the 10-skill FOUNDATION sequence — each elevate-foundation-* SKILL.md body is loaded from the workspace's skill catalog and executed, and every field it produces is merged at inferred/scrape provenance so it can never outrank a human-confirmed one",
+        request: z.object({
+            slug: z.string().optional(),
+            source: z.enum(["inferred", "scrape"]).optional(),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            slug: z.string().optional(),
+            error: z.string().optional(),
+            skillsRun: z.number().optional(),
+            // EMITTED, not written: a field already at chat/document rank is emitted and
+            // then refused by the merge guard. Naming it "written" would overstate it.
+            fieldsEmitted: z.number().optional(),
+            // Per-skill receipt: what each skill actually did. `outcome` distinguishes
+            // "emitted N fields" from "returned nothing" from "the answer did not parse".
+            skills: z.array(z.object({
+                skill: z.string(),
+                outcome: z.enum(["ok", "empty", "parse_failed", "llm_error"]),
+                bodyFound: z.boolean(),
+                fieldsEmitted: z.number(),
+                fields: z.array(z.string()).optional(),
+                dropped: z.array(z.string()).optional(),
+                status: z.number().optional(),
+            })).optional(),
+        }),
+        effect: "ask", cost: "variable", reversible: false, idempotent: false, auth: "member",
+    }),
+    "foundation:start": receiver({
+        receiver: "foundation:start",
+        summary: "Fill the Foundation's spine fields with one bounded LLM call over the workspace's own context. Refuses to overwrite a human-confirmed field; writes at chat/0.75",
+        request: z.object({ slug: z.string().optional() }),
+        response: z.object({ ok: z.boolean(), slug: z.string().optional(), fields: z.number().optional(), error: z.string().optional() }),
+        effect: "ask", cost: "variable", reversible: false, idempotent: false, auth: "member",
+    }),
+    "foundation:read": receiver({
+        receiver: "foundation:read",
+        summary: "Read the workspace's Foundation as stored (null when nothing has been written yet)",
+        request: z.object({ slug: z.string().optional() }),
+        response: z.object({ ok: z.boolean(), slug: z.string().optional(), foundation: z.unknown().optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
+    }),
+    "foundation:derive": receiver({
+        receiver: "foundation:derive",
+        summary: "Turn the stored Foundation into DRAFT products and DRAFT ELEVATE playbook chapters. Insert-only (never overwrites a human edit), no price is ever guessed, and confidence is inherited from the weakest source fact",
+        request: z.object({}),
+        response: z.object({
+            ok: z.boolean(),
+            slug: z.string().optional(),
+            products: z.unknown().optional(),
+            playbook: z.unknown().optional(),
+            error: z.string().optional(),
+            hint: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", reversible: false, idempotent: false, auth: "member",
+    }),
+    "foundation:extract": receiver({
+        receiver: "foundation:extract",
+        summary: "Fold every rendered page into ONE provenance-tracked Foundation patch, and report the spine paths still unanswered. Pure — no network, no LLM, no cost, no write. Its fencedEvidence is already wrapped by the provenance fence, so a downstream prompt cannot interpolate crawled text unfenced",
+        request: z.object({ home: z.unknown().optional(), pages: z.unknown().optional(), siteMap: z.unknown().optional() }),
+        response: z.object({
+            ok: z.boolean(),
+            patch: z.unknown().optional(),
+            found: z.unknown().optional(),
+            gaps: z.array(z.string()).optional(),
+            pagesRead: z.number().optional(),
+            pagesFailed: z.number().optional(),
+            degraded: z.string().optional(),
+            fencedEvidence: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "public",
+    }),
+    "foundation:save": receiver({
+        receiver: "foundation:save",
+        summary: "The single write of the company workflow. With an attested workspace it merges into workspace_settings.foundation provenance-aware; without one it holds the profile as an opaque 1h KV draft to be promoted at signup — an anonymous caller never writes a workspace",
+        request: z.object({
+            patch: z.unknown().optional(),
+            fill: z.unknown().optional(),
+            seo: z.unknown().optional(),
+            draftToken: z.string().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            stored: z.enum(["workspace", "draft", "none"]).optional(),
+            slug: z.string().optional(),
+            draftToken: z.string().optional(),
+            fields: z.number().optional(),
+            gaps: z.array(z.string()).optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", reversible: false, idempotent: false, auth: "public",
+    }),
+    "foundation:promote-draft": receiver({
+        receiver: "foundation:promote-draft",
+        summary: "Carry an anonymous onboarding draft into the caller's workspace at signup and delete the KV key. Provenance survives, so a scraped field still loses to the human's later edit",
+        request: z.object({ draftToken: z.string() }),
+        response: z.object({ ok: z.boolean(), slug: z.string().optional(), fields: z.number().optional(), gaps: z.array(z.string()).optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: false, idempotent: true, auth: "member",
+    }),
     // ── social + crawl — handlers in resolvers/social.ts ───────────────────────────
     "social:publish": receiver({
         receiver: "social:publish",
@@ -2305,7 +3350,7 @@ export const RECEIVERS = {
     }),
     "billing:topup": receiver({
         receiver: "billing:topup",
-        summary: "Top up workspace AI credits — returns a checkout URL for the amount",
+        summary: "Top up workspace AI credits — returns a checkout URL for the amount. Credits are prepaid, NON-WITHDRAWABLE service units: they buy work on ONE (AI replies, tool and skill calls, agent runs, storage, API requests) and there is no payout, withdraw or cash-out rail against a credits balance",
         request: z.object({ slug: z.string(), actorId: z.string(), amount: z.number(), currency: z.string().optional() }),
         response: z.object({ ok: z.boolean(), intent: z.string().optional(), checkoutUrl: z.string().optional(), amount: z.number().optional(), currency: z.string().optional(), reason: z.string().optional() }),
         effect: "ask", cost: "free", reversible: false, idempotent: false, auth: "update_group",
@@ -2456,7 +3501,10 @@ export const RECEIVERS = {
         receiver: "booking:list-bookings",
         summary: "Provider-gated: list a workspace's bookings for a month (customer, time, service, status)",
         request: z.object({
-            slug: z.string(), // workspace (informational; gate re-scopes to caller)
+            // Optional: the comment below is the point — the handler does
+            // `const slug = ctx.ownerSlug` and never reads data.slug. Required, the
+            // binder rejected every call that correctly omitted it.
+            slug: z.string().optional(), // workspace (informational; gate re-scopes to caller)
             month: z.string().optional(), // 'YYYY-MM'; omitted → current month
         }),
         response: z.object({
@@ -2521,6 +3569,7 @@ export const RECEIVERS = {
     // and commits nothing — the chat-authoring preview path.
     "workflow:list": receiver({
         receiver: "workflow:list",
+        surfaces: { mcp: true },
         summary: "List a workspace's workflows (D1 mirror); pass templates=true for the public SOP catalog",
         request: z.object({
             slug: z.string().optional(),
@@ -2538,6 +3587,7 @@ export const RECEIVERS = {
     }),
     "workflow:get": receiver({
         receiver: "workflow:get",
+        surfaces: { mcp: true },
         summary: "Fetch one workflow's full graph — steps (kind, config, position) and edges (with conditions)",
         request: z.object({ workflowId: z.string() }),
         response: z.object({
@@ -2558,6 +3608,7 @@ export const RECEIVERS = {
     }),
     "workflow:runs": receiver({
         receiver: "workflow:runs",
+        surfaces: { mcp: true },
         summary: "List recent runs of a workflow (D1 workflow_run) for the monitor + history surfaces",
         request: z.object({ workflowId: z.string(), runId: z.string().optional(), limit: z.number().int().min(1).max(200).optional() }),
         response: z.object({
@@ -2574,6 +3625,25 @@ export const RECEIVERS = {
         effect: "ask", cost: "free", idempotent: true, simulatable: false, auth: "view_workflows",
         examples: [{ workflowId: "wf_abc", limit: 20 }, { workflowId: "wf_abc", runId: "run_1" }],
     }),
+    "workflow:step-stats": receiver({
+        receiver: "workflow:step-stats",
+        surfaces: { mcp: true },
+        summary: "Per-step run counts and latency for one workflow (aggregated over D1 workflow_run_event) — what the canvas prints on each step card",
+        request: z.object({ workflowId: z.string(), sinceMs: z.number().int().optional() }),
+        response: z.object({
+            stats: z.array(z.object({
+                stepId: z.string(),
+                runs: z.number().int(),
+                failures: z.number().int(),
+                avgMs: z.number().nullable(),
+                maxMs: z.number().nullable(),
+                lastAt: z.number().nullable(),
+            })),
+            error: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", idempotent: true, simulatable: false, auth: "view_workflows",
+        examples: [{ workflowId: "wf_abc" }],
+    }),
     "workflow:preview-step": receiver({
         receiver: "workflow:preview-step",
         summary: "Resolve one step's receiver + args through the real substitution code, with an optional mock trigger/step payload standing in for run history — never dispatches, reads no run history",
@@ -2593,6 +3663,7 @@ export const RECEIVERS = {
     }),
     "workflow:create": receiver({
         receiver: "workflow:create",
+        surfaces: { mcp: true },
         summary: "Create a blank workflow (group group-type=workflow) — optionally cloned from a template",
         request: z.object({
             slug: z.string().optional(),
@@ -2625,6 +3696,7 @@ export const RECEIVERS = {
     }),
     "workflow:apply-diff": receiver({
         receiver: "workflow:apply-diff",
+        surfaces: { mcp: true },
         summary: "Apply a WorkflowDiff (add/remove/connect/disconnect/update). simulate=true validates the DAG without persisting",
         request: z.object({
             workflowId: z.string(),
@@ -2645,6 +3717,7 @@ export const RECEIVERS = {
     }),
     "workflow:validate": receiver({
         receiver: "workflow:validate",
+        surfaces: { mcp: true },
         summary: "Run the §9 gate on a WorkflowDiff without persisting — kinds/config shapes, exactly-one-trigger, edges reference real steps, chain cycles; advisories ride back as warnings (grammar: code | code:stepId, never block). Every save door calls this.",
         request: z.object({
             workflowId: z.string(),
@@ -2662,6 +3735,7 @@ export const RECEIVERS = {
     }),
     "workflow:run": receiver({
         receiver: "workflow:run",
+        surfaces: { mcp: true },
         summary: "Start a run — spawns the WorkflowRun DO, executes each step, marks path strength on traversed edges",
         request: z.object({
             workflowId: z.string(),
@@ -2778,6 +3852,7 @@ export const RECEIVERS = {
     }),
     "workflow:stop": receiver({
         receiver: "workflow:stop",
+        surfaces: { mcp: true },
         summary: "Park a live run at its current step (status → paused); preserves the resume cursor so human:resolve or a re-run continues it",
         request: z.object({ runId: z.string() }),
         response: z.object({ ok: z.boolean(), status: z.string().optional(), error: z.string().optional() }),
@@ -2786,6 +3861,7 @@ export const RECEIVERS = {
     }),
     "workflow:trigger": receiver({
         receiver: "workflow:trigger",
+        surfaces: { mcp: true },
         summary: "Fire every workspace workflow whose trigger step matches a channel source (e.g. webhook:telegram)",
         request: z.object({
             source: z.string(),
@@ -2806,6 +3882,7 @@ export const RECEIVERS = {
     }),
     "workflow:update": receiver({
         receiver: "workflow:update",
+        surfaces: { mcp: true },
         summary: "Rename a workflow or change its status (draft|active|paused)",
         request: z.object({ workflowId: z.string(), name: z.string().optional(), status: z.enum(["draft", "active", "paused"]).optional() }),
         response: z.object({ ok: z.boolean(), error: z.string().optional() }),
@@ -2820,11 +3897,44 @@ export const RECEIVERS = {
         effect: "ask", cost: "free", reversible: false, idempotent: false, auth: "manage_workflows",
         examples: [{ workflowId: "wf_abc" }, { rate: 0.1 }, {}],
     }),
+    // ── The .tql text form of a workflow (workflows-tql). Export/import as a
+    //    single-insert TypeQL document — the graph a canvas draws, as text an
+    //    agent can read, diff and hand back. apply-tql never writes D1 itself: it
+    //    parses, gates the whole document as an all-add diff, reconciles against
+    //    what is persisted, and goes through workflow:apply-diff — the one door.
+    "workflow:tql": receiver({
+        receiver: "workflow:tql",
+        surfaces: { mcp: true },
+        summary: "Emit one workflow as its .tql text form — a single-insert TypeQL document (group header + step things + path edges) that round-trips back through workflow:apply-tql",
+        request: z.object({ workflowId: z.string() }),
+        response: z.object({ ok: z.boolean(), tql: z.string().optional(), version: z.number().optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", idempotent: true, simulatable: false, auth: "view_workflows",
+        examples: [{ workflowId: "wf_abc" }],
+    }),
+    "workflow:apply-tql": receiver({
+        receiver: "workflow:apply-tql",
+        surfaces: { mcp: true },
+        summary: "Parse a .tql workflow document and apply it to an existing workflow THROUGH workflow:apply-diff — the sole validated persist door, so the import inherits the DAG check, the one-trigger law, the config gate and the authority walk. simulate:true validates and persists nothing",
+        request: z.object({ workflowId: z.string(), tql: z.string(), simulate: z.boolean().optional(), version: z.number().optional() }),
+        response: z.object({
+            ok: z.boolean(),
+            stepCount: z.number().optional(),
+            idMap: z.record(z.string(), z.string()).optional(),
+            warnings: z.array(z.string()).optional(),
+            notes: z.array(z.string()).optional(),
+            error: z.string().optional(),
+            line: z.number().optional(),
+            detail: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", reversible: false, idempotent: false, simulatable: true, auth: "manage_workflows",
+        examples: [{ workflowId: "wf_abc", tql: "insert\n$w isa group, has gid \"group:wf-wf_abc\", has name \"Demo\", has group-type \"team\";\n", simulate: true }],
+    }),
     // ── 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).
     "skills:list": receiver({
         receiver: "skills:list",
+        surfaces: { mcp: true },
         summary: "List the caller's workspace skill catalog (R2) — powers the canvas SkillPicker",
         request: z.object({ name: z.string().optional() }),
         response: z.object({
@@ -2843,6 +3953,7 @@ export const RECEIVERS = {
     }),
     "skill:run": receiver({
         receiver: "skill:run",
+        surfaces: { mcp: true },
         summary: "Run a workspace skill — loads its body from R2, runs one bounded turn via channels, returns { text }",
         request: z.object({ skill: z.string() }).catchall(z.unknown()), // extra keys = the skill's input
         response: z.object({ ok: z.boolean(), text: z.string().optional(), skill: z.string().optional(), error: z.string().optional() }),
@@ -2851,9 +3962,12 @@ export const RECEIVERS = {
     }),
     "agent:run": receiver({
         receiver: "agent:run",
+        surfaces: { mcp: true },
         summary: "Invoke a bound actor (optionally skill-constrained) for one bounded turn via channels; returns { text }",
         request: z.object({
-            actorId: z.string(),
+            // Optional by design: an omitted actorId resolves to the workspace CEO
+            // (C9). Required here, the binder rejected the very call that default exists to serve.
+            actorId: z.string().optional(),
             skill: z.string().optional(),
             instructions: z.string().optional(),
         }).catchall(z.unknown()), // extra keys = the agent's input
@@ -2889,10 +4003,11 @@ export const RECEIVERS = {
         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 },
+        surfaces: { chat: true, mcp: { name: "create_room" } },
     }),
     "video:delete-room": receiver({
         receiver: "video:delete-room",
+        surfaces: { mcp: { name: "delete_room" } },
         summary: "Disable a video room and its 100ms counterpart; room is no longer joinable",
         request: z.object({ workspace: z.string(), roomSlug: z.string() }),
         response: z.object({ ok: z.boolean(), error: z.string().optional() }),
@@ -2901,6 +4016,7 @@ export const RECEIVERS = {
     }),
     "video:contact-call": receiver({
         receiver: "video:contact-call",
+        surfaces: { mcp: { name: "contact_call" } },
         summary: "Provision a one-to-one video room for a contact; links the room thread to the contact CRM record",
         request: z.object({
             workspace: z.string(),
@@ -2920,6 +4036,7 @@ export const RECEIVERS = {
     }),
     "video:invite": receiver({
         receiver: "video:invite",
+        surfaces: { mcp: { name: "invite_to_call" } },
         summary: "Generate a tracked /go/ join link for an actor into an existing room",
         request: z.object({
             workspace: z.string(),
@@ -2952,10 +4069,11 @@ 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)
+        surfaces: { chat: true, mcp: { name: "schedule_webinar" } }, // fan-out: chat (actions-fan-out C5) + MCP (agent-native C1)
     }),
     "video:create-session": receiver({
         receiver: "video:create-session",
+        surfaces: { mcp: { name: "create_session" } },
         summary: "Create a video session with host + guest tracked join links; optionally schedules the call",
         request: z.object({
             workspace: z.string(),
@@ -2991,7 +4109,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)
+        surfaces: { chat: true, mcp: { name: "video_summary" } }, // fan-out: chat (actions-fan-out C5) + MCP (agent-native C1)
     }),
     "video:quick-room": receiver({
         receiver: "video:quick-room",
@@ -3012,7 +4130,43 @@ 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 },
+        surfaces: { chat: true, mcp: { name: "quick_call" } },
+    }),
+    // The human-handoff door. A visitor in chat asks for a person; the agent fires
+    // this ONE receiver, which creates (or reuses) the meeting room, drops the
+    // reason into the room's thread, and notifies the workspace wherever it
+    // listens — Telegram/Discord/web inbox/web push, all through `notify`. It is
+    // idempotent per CONVERSATION: the same chat asking twice joins the same room
+    // instead of provisioning a second one.
+    "video:request-meeting": receiver({
+        receiver: "video:request-meeting",
+        summary: "Visitor asks to meet a human: creates/reuses a meeting room for this conversation and notifies the workspace",
+        request: z.object({
+            workspace: z.string(),
+            conversation: z.string().optional(), // chat group/thread id — the idempotency key
+            roomSlug: z.string().optional(), // an EXISTING room to send them to (the standing front desk); never creates
+            visitorName: z.string().optional(),
+            reason: z.string().optional(), // what they want to talk about
+            channel: z.string().optional(), // web | telegram | discord | api
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            roomSlug: z.string().optional(),
+            workspace: z.string().optional(),
+            name: z.string().optional(),
+            threadId: z.string().nullable().optional(),
+            path: z.string().optional(), // /u/<workspace>/meet/<roomSlug>
+            reused: z.boolean().optional(), // an existing room for this conversation
+            notified: z.boolean().optional(),
+            error: z.string().optional(), // 'invalid_request' | 'forbidden' | 'rate_limited' | …
+        }),
+        effect: "ask", cost: "free", idempotent: true, auth: "manage_clients",
+        examples: [{ workspace: "acme", conversation: "conv:abc123", visitorName: "Sarah", reason: "pricing for 20 seats" }],
+        // Deliberately NOT `surfaces: { chat: true }`. The registry-derived tool
+        // (from-registry.ts) would be a second, unshaped door onto the same
+        // receiver — no `public` flag (so no visitor could reach it), no room block
+        // on the way back, and a name the model would pick by accident. The curated
+        // `meet_human` (channels/src/tools/meetings.ts) is the chat surface.
     }),
     "video:join-event": receiver({
         receiver: "video:join-event",
@@ -3038,7 +4192,29 @@ 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)
+        surfaces: { chat: true, mcp: { name: "start_recording" } }, // fan-out: chat (actions-fan-out C5) + MCP (agent-native C1)
+    }),
+    // video:room-status — the presence read, one lib function behind two doors.
+    // NOT flagged surfaces.mcp on purpose: packages/mcp still hand-writes
+    // `get_room_status` over this receiver, and flagging it here would derive a
+    // second tool of the same name. Flag it in the same change that deletes that file.
+    "video:room-status": receiver({
+        receiver: "video:room-status",
+        summary: "Who is in a room right now — staff names, a count of everyone else, and when the first staff peer joined",
+        request: z.object({ workspace: z.string(), roomSlug: z.string() }),
+        response: z.object({
+            ok: z.boolean(),
+            // `unknown` is a first-class answer: an upstream that could not be read is
+            // never reported as an empty room.
+            state: z.enum(["live", "empty", "unknown"]).optional(),
+            staff: z.array(z.string()).optional(),
+            others: z.number().optional(),
+            since: z.string().nullable().optional(),
+            reason: z.string().optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", idempotent: true, auth: "manage_clients",
+        examples: [{ workspace: "acme", roomSlug: "meeting" }],
     }),
     "video:start-stream": receiver({
         receiver: "video:start-stream",
@@ -3055,7 +4231,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)
+        surfaces: { chat: true, mcp: { name: "start_stream" } }, // fan-out: chat (actions-fan-out C5) + MCP (agent-native C1)
     }),
     // connect:channel — token-paste connect for a channel (Connect plan C7). The
     // typed contract over the shipped /api/connect/telegram route: the caller pastes
@@ -3108,6 +4284,7 @@ export const RECEIVERS = {
     // ── Broadcast (newsletter) ────────────────────────────────────────────────
     "broadcast:create": receiver({
         receiver: "broadcast:create",
+        surfaces: { mcp: true },
         summary: "Create a broadcast draft — subject, body_md, audience_tag, channel",
         request: z.object({ workspace: z.string(), subject: z.string().optional(), body_md: z.string().optional(), audience_tag: z.string().optional(), channel: z.enum(["email", "sms", "whatsapp"]).optional() }),
         response: z.object({ broadcastId: z.string() }),
@@ -3115,6 +4292,7 @@ export const RECEIVERS = {
     }),
     "broadcast:update": receiver({
         receiver: "broadcast:update",
+        surfaces: { mcp: { name: "newsletter_update" } },
         summary: "Update a broadcast draft — subject, body, audience, schedule",
         request: z.object({ workspace: z.string(), broadcastId: z.string(), subject: z.string().optional(), body_md: z.string().optional(), audience_tag: z.string().optional(), scheduled_at: z.number().optional() }),
         response: z.object({ ok: z.boolean() }),
@@ -3122,6 +4300,7 @@ export const RECEIVERS = {
     }),
     "broadcast:list": receiver({
         receiver: "broadcast:list",
+        surfaces: { mcp: true },
         summary: "List broadcasts for a workspace with status and sent_at",
         request: z.object({ workspace: z.string(), status: z.enum(["draft", "scheduled", "sending", "sent", "cancelled"]).optional(), limit: z.number().int().max(100).optional() }),
         response: z.object({ broadcasts: z.array(z.object({ id: z.string(), subject: z.string(), status: z.string(), sent_at: z.number().nullable(), audience_tag: z.string().nullable() })) }),
@@ -3129,6 +4308,7 @@ export const RECEIVERS = {
     }),
     "broadcast:get": receiver({
         receiver: "broadcast:get",
+        surfaces: { mcp: true },
         summary: "Get a single broadcast with recipient counts",
         request: z.object({ workspace: z.string(), broadcastId: z.string() }),
         response: z.object({ broadcast: z.record(z.string(), z.unknown()) }),
@@ -3150,6 +4330,7 @@ export const RECEIVERS = {
     }),
     "segment:list": receiver({
         receiver: "segment:list",
+        surfaces: { mcp: true },
         summary: "List audience segments for a workspace",
         request: z.object({ workspace: z.string() }),
         response: z.object({ segments: z.array(z.record(z.string(), z.unknown())) }),
@@ -3157,6 +4338,7 @@ export const RECEIVERS = {
     }),
     "segment:get": receiver({
         receiver: "segment:get",
+        surfaces: { mcp: true },
         summary: "Get one audience segment with its rule definition",
         request: z.object({ workspace: z.string(), id: z.string() }),
         response: z.object({ segment: z.record(z.string(), z.unknown()) }),
@@ -3164,6 +4346,7 @@ export const RECEIVERS = {
     }),
     "segment:preview": receiver({
         receiver: "segment:preview",
+        surfaces: { mcp: true },
         summary: "Preview an audience segment — live count + up to 10 sample addresses (read-only)",
         request: z.object({ workspace: z.string(), definition: z.record(z.string(), z.unknown()), channel: z.enum(["email", "sms", "whatsapp"]).optional() }),
         response: z.object({ count: z.number(), sample: z.array(z.string()) }),
@@ -3185,6 +4368,7 @@ export const RECEIVERS = {
     }),
     "broadcast:send": receiver({
         receiver: "broadcast:send",
+        surfaces: { mcp: true },
         summary: "Seed recipients from audience tag, apply suppression, enqueue the send batch",
         request: z.object({ workspace: z.string(), broadcastId: z.string() }),
         response: z.object({ enqueued: z.number() }),
@@ -3287,18 +4471,21 @@ export const RECEIVERS = {
     // ── Send Link — actor-bound tracked URL (CRM personalisation) ──────────────
     "links:create": receiver({
         receiver: "links:create",
-        summary: "Create an actor-bound tracked link. On click `/go/:id` elevates the contact to rung-4 identity, pre-warms their snapshot, and personalises the page + chat. Creation is gated: the caller must hold authority over the target contact's workspace; `createdBy` is stamped from the attested session, never the body.",
+        summary: "Create a tracked link in one of two shapes. ACTOR-BOUND (`actorId` given): the click elevates that contact to rung-4 identity at `/go/:id`, pre-warms their snapshot, and personalises the page + chat; the caller must hold authority over the contact's workspace. CAMPAIGN-ONLY (`campaignId` given, no `actorId`): the shape cold ad traffic needs, since an ad click is anonymous by definition and can never name a contact at mint time — the contact-owner walk is skipped, `actor_id` is stored null, and the click is attributed to the campaign alone. Exactly one of `actorId` / `campaignId` is required; supplying neither is refused. Minting is authed in both shapes; only the CLICK is anonymous. `slug` and `createdBy` are stamped from the attested session, never the body.",
         request: z.object({
-            actorId: z.string().describe("Contact (actor) the link is bound to — must belong to the caller's workspace or a descendant"),
+            actorId: z.string().optional().describe("Contact (actor) the link is bound to — must belong to the caller's workspace or a descendant. Omit for cold ad traffic, in which case `campaignId` is REQUIRED so the click is never fully unattributed"),
             destination: z.string().optional().describe("Path the click lands on (must start with '/'); default '/'"),
             context: z.string().optional().describe("Extra context injected into the agent's system prompt for this session"),
             greeting: z.string().optional().describe("Override the chat agent's opening line"),
-            campaignId: z.string().optional().describe("Group clicks under a campaign for the learning loop"),
+            campaignId: z.string().optional().describe("Group clicks under a campaign for the learning loop. REQUIRED when `actorId` is absent. Forwarded onto the destination URL as `utm_campaign` so the landing page and the click row report the same campaign; capped at 128 chars"),
             expiresInDays: z.number().optional().describe("Link TTL in days; omitted = never expires"),
         }),
         response: z.object({ id: z.string(), sig: z.string(), url: z.string() }),
         effect: "ask", cost: "free", reversible: false, idempotent: false, auth: "member",
-        examples: [{ actorId: "u-123", destination: "/pricing", expiresInDays: 90 }],
+        examples: [
+            { actorId: "u-123", destination: "/pricing", expiresInDays: 90 },
+            { campaignId: "spring-ads", destination: "/movers", expiresInDays: 30 },
+        ],
     }),
     "links:bulk-create": receiver({
         receiver: "links:bulk-create",
@@ -3483,6 +4670,7 @@ export const RECEIVERS = {
     // ── seo — handlers in resolvers/seo.ts (C1 live; C2 async) ─────────────────
     "seo:backlinks-summary": receiver({
         receiver: "seo:backlinks-summary",
+        surfaces: { mcp: { name: "seo_backlinks" } },
         summary: "Pull live backlink summary for a domain via DataForSEO; marks domain→seo:backlinks path",
         request: z.object({ target: z.string(), limit: z.number().int().min(1).max(1000).optional() }),
         response: z.object({ ok: z.boolean(), data: z.unknown().optional(), error: z.string().optional() }),
@@ -3491,6 +4679,7 @@ export const RECEIVERS = {
     }),
     "seo:llm-mentions": receiver({
         receiver: "seo:llm-mentions",
+        surfaces: { mcp: { name: "seo_ai_visibility" } },
         summary: "Pull live AI-visibility (LLM mentions) data for a domain via DataForSEO; marks domain→seo:llm-mentions path",
         request: z.object({ target: z.string() }),
         response: z.object({ ok: z.boolean(), data: z.unknown().optional(), error: z.string().optional() }),
@@ -3499,6 +4688,7 @@ export const RECEIVERS = {
     }),
     "seo:keywords-for-keyword": receiver({
         receiver: "seo:keywords-for-keyword",
+        surfaces: { mcp: { name: "seo_research_keywords" } },
         summary: "Return related keyword suggestions for a seed keyword via DataForSEO Google Ads; marks keyword→seo:keywords path",
         request: z.object({ keyword: z.string(), location_code: z.number().int().optional(), language_code: z.string().optional() }),
         response: z.object({ ok: z.boolean(), data: z.unknown().optional(), error: z.string().optional() }),
@@ -3507,6 +4697,7 @@ export const RECEIVERS = {
     }),
     "seo:serp": receiver({
         receiver: "seo:serp",
+        surfaces: { mcp: true },
         summary: "Return full Google Organic SERP for a keyword via DataForSEO async task (submit→poll); marks keyword→seo:serp path",
         request: z.object({ keyword: z.string(), location_code: z.number().int().optional(), language_code: z.string().optional(), device: z.string().optional() }),
         response: z.object({ ok: z.boolean(), data: z.unknown().optional(), error: z.string().optional() }),
@@ -3515,6 +4706,7 @@ export const RECEIVERS = {
     }),
     "seo:keyword-metrics": receiver({
         receiver: "seo:keyword-metrics",
+        surfaces: { mcp: true },
         summary: "Return monthly search volume, CPC, and competition for a list of keywords via DataForSEO async task",
         request: z.object({ keywords: z.array(z.string()), location_code: z.number().int().optional(), language_code: z.string().optional() }),
         response: z.object({ ok: z.boolean(), data: z.unknown().optional(), error: z.string().optional() }),
@@ -3523,6 +4715,7 @@ export const RECEIVERS = {
     }),
     "seo:gsc-performance": receiver({
         receiver: "seo:gsc-performance",
+        surfaces: { mcp: { name: "seo_gsc" } },
         summary: "Return Google Search Console click/impression/CTR/position data for a site via Composio GSC toolkit",
         request: z.object({ site_url: z.string(), start_date: z.string(), end_date: z.string(), dimensions: z.array(z.string()).optional(), row_limit: z.number().int().optional() }),
         response: z.object({ ok: z.boolean(), data: z.unknown().optional(), error: z.string().optional() }),