@oneie/sdk 0.13.2 → 0.13.4

package/dist/receivers.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { AgentActionResponseSchema, AgentStatusResponseSchema, CapabilityItemSchema, PayResponseSchema, RegisterResponseSchema, StatsSchema, StepKind, WorkflowDiffSchema, } from "./schemas.js";
+import { ResourceTypeSchema } from "./types.js";
 /**
  * Declare a receiver contract. Identity at runtime — its only job is to pin the
  * `Req`/`Res` generics so the catalog infers payload + outcome types.
@@ -197,6 +198,22 @@ export const RECEIVERS = {
         request: z.object({ aid: z.string(), name: z.string().optional(), tags: z.array(z.string()).optional(), prompt: z.string().optional(), model: z.string().optional() }),
         response: ok, effect: "ask", auth: "manage_actors",
     }),
+    "visitor:promote": receiver({
+        receiver: "visitor:promote",
+        summary: "Promote a tracked anonymous visitor to a TypeDB actor (anon:<hash12>) so it surfaces in People; binds rung-1 visitor_hash→aid. Idempotent.",
+        request: z.object({ visitorHash: z.string() }),
+        response: z.object({
+            ok: z.boolean(),
+            aid: z.string().optional(),
+            promoted: z.boolean().optional(),
+            region: z.string().optional(),
+            reason: z.string().optional(),
+        }),
+        effect: "ask",
+        auth: "manage_actors",
+        idempotent: true,
+        examples: [{ visitorHash: "9f2a1c7b4e0d8a3f5c6b" }],
+    }),
     "world:update-contact": receiver({
         receiver: "world:update-contact",
         summary: "Update an actor's contact/profile attributes — identity, contact details, professional, personal, CRM metrics",
@@ -279,6 +296,12 @@ export const RECEIVERS = {
         summary: "Revoke an API key",
         request: z.object({ keyId: z.string() }), response: ok, effect: "ask", auth: "member", reversible: false,
     }),
+    "world:declare-types": receiver({
+        receiver: "world:declare-types",
+        summary: "Persist a resource-type manifest for the caller's workspace; pass a template name (e.g. ecommerce) to seed from a built-in, or explicit types",
+        request: z.object({ group: z.string(), types: z.array(ResourceTypeSchema).optional(), template: z.string().optional() }),
+        response: z.object({ ok: z.literal(true), count: z.number() }), effect: "ask", auth: "manage_things",
+    }),
     "world:create-thing": receiver({
         receiver: "world:create-thing",
         summary: "Create a thing (skill, token, product) in the world",
@@ -296,6 +319,13 @@ export const RECEIVERS = {
         summary: "Delete a thing",
         request: z.object({ tid: z.string() }), response: ok, effect: "ask", auth: "manage_things", reversible: false,
     }),
+    "world:list-things": receiver({
+        receiver: "world:list-things",
+        summary: "List things of a given type in a workspace — used by relation-field pickers",
+        request: z.object({ group: z.string(), type: z.string() }),
+        response: z.object({ items: z.array(z.object({ tid: z.string(), name: z.string() })) }),
+        effect: "ask", auth: "member", cost: "free", idempotent: true,
+    }),
     "world:freeze-path": receiver({
         receiver: "world:freeze-path",
         summary: "Freeze a path so decay cannot weaken it",
@@ -740,6 +770,16 @@ export const RECEIVERS = {
         }),
         effect: "ask", cost: "free", idempotent: true,
     }),
+    "meta:types": receiver({
+        receiver: "meta:types",
+        summary: "Read the resource-type manifest for the caller's workspace, plus the built-in industry templates",
+        request: z.object({}),
+        response: z.object({
+            types: z.array(ResourceTypeSchema),
+            templates: z.record(z.string(), z.array(ResourceTypeSchema)),
+        }),
+        effect: "ask", cost: "free", idempotent: true,
+    }),
     // ── actor discovery + messaging ──────────────────────────────────────────
     "actors:find": receiver({
         receiver: "actors:find",
@@ -764,6 +804,130 @@ export const RECEIVERS = {
         response: z.object({ ok: z.boolean(), id: z.string().optional(), ts: z.number().optional(), to: z.string().optional(), from: z.string().optional(), error: z.string().optional() }),
         effect: "ask", idempotent: false,
     }),
+    "notify": receiver({
+        receiver: "notify",
+        summary: "Notify any actor (human or agent) by uid — channels routes the door (Telegram/Discord/peer inbox), mirrors into the web inbox, and nudges an open client live. One verb, both actor kinds.",
+        request: z.object({
+            receiver: z.string(),
+            kind: z.string().optional(),
+            body: z.union([z.string(), z.record(z.string(), z.unknown())]).optional(),
+            content: z.string().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            id: z.string().optional(),
+            ts: z.number().optional(),
+            to: z.string().optional(),
+            from: z.string().optional(),
+            kind: z.string().optional(),
+            delivered: z.array(z.string()).optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", idempotent: false,
+    }),
+    "notify:count": receiver({
+        receiver: "notify:count",
+        summary: "Unread thread count for the caller's inbox (a thread is unread when its last message is newer than the caller's read marker).",
+        request: z.object({}),
+        response: z.object({ unread: z.number() }),
+        effect: "ask", idempotent: true,
+    }),
+    "notify:list": receiver({
+        receiver: "notify:list",
+        summary: "The caller's unread threads, newest first, each with a short preview.",
+        request: z.object({ limit: z.number().optional() }),
+        response: z.object({ unread: z.array(z.object({ id: z.string(), ts: z.number(), preview: z.string() })) }),
+        effect: "ask", idempotent: true,
+    }),
+    "notify:read": receiver({
+        receiver: "notify:read",
+        summary: "Mark one thread (threadId) or all of the caller's threads (all:true) as read; nudges the inbox live.",
+        request: z.object({ threadId: z.string().optional(), id: z.string().optional(), all: z.boolean().optional() }),
+        response: z.object({ ok: z.boolean(), ts: z.number().optional(), error: z.string().optional() }),
+        effect: "ask", idempotent: true,
+    }),
+    "thread:append": receiver({
+        receiver: "thread:append",
+        summary: "Gateway-callable write into web threads — carries tags into entity_tags so slug/in renders every channel by tag. Called by the channels bridge after every inbound signal.",
+        request: z.object({
+            slug: z.string(),
+            group: z.string(),
+            sender: z.string(),
+            label: z.string().optional(),
+            chatName: z.string().optional(),
+            content: z.string(),
+            ts: z.number().optional(),
+            tags: z.array(z.string()).optional(),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            threadId: z.string().optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask",
+        idempotent: false,
+    }),
+    "space:post": receiver({
+        receiver: "space:post",
+        summary: "Post a message to a Space — authenticated member or public Space; stamps space:<slug> tag so the message appears in the Space's thread on slug/in alongside every channel's conversation",
+        request: z.object({
+            space: z.string(),
+            content: z.string(),
+            tags: z.array(z.string()).optional(),
+            replyTo: z.string().optional(), // parent message id → cascading reply (channels persists the edge)
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            id: z.string().optional(),
+            ts: z.number().optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask",
+        idempotent: false,
+    }),
+    "space:create": receiver({
+        receiver: "space:create",
+        summary: "Create a new Space — registers the channel_link inbox door in channels so every inbound signal is mirrored to the workspace thread read model; private flag restricts posting to members",
+        request: z.object({
+            slug: z.string(),
+            name: z.string().optional(),
+            private: z.boolean().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            space: z.string().optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask",
+        idempotent: false,
+    }),
+    "space:join": receiver({
+        receiver: "space:join",
+        summary: "Join a public Space — caller begins receiving its signals and their posts are stamped with the space tag",
+        request: z.object({ space: z.string() }),
+        response: z.object({
+            ok: z.boolean(),
+            error: z.string().optional(),
+        }),
+        effect: "ask",
+        idempotent: true,
+    }),
+    "space:invite": receiver({
+        receiver: "space:invite",
+        summary: "Invite an actor to a private Space — grants membership so they can read and post; requires the caller to be a member or admin of the Space",
+        request: z.object({
+            space: z.string(),
+            who: z.string(),
+            role: z.string().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            verdict: z.string().optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask",
+        idempotent: false,
+    }),
     "chat:send": receiver({
         receiver: "chat:send",
         summary: "Send a message to a group the caller is a member of — sender is always the authenticated caller",
@@ -776,7 +940,449 @@ export const RECEIVERS = {
         response: z.object({ ok: z.boolean(), reply: z.string().optional(), error: z.string().optional() }),
         effect: "ask", auth: "member",
     }),
+    // ── chat-context — the threaded #staff fabric: grade · context · harden · lens
+    // (text/chat-context.md). `space:post` (the post verb) is declared above. Handlers
+    // in resolvers/{messaging,entity}.ts; all IDOR-gated off ctx.ownerSlug. ──────────
+    // chat:context — the agent skin: a budget-bounded context pack for one message in
+    // a thread (spine + pins + budget-filled siblings + summary tail), returned both
+    // structured and serialized for a model. What an agent reads instead of the thread.
+    "chat:context": receiver({
+        receiver: "chat:context",
+        summary: "Assemble a budget-bounded context pack (spine + pins + siblings + summary) for a thread message — structured + serialized for an agent",
+        request: z.object({
+            entityId: z.string().optional(), // thread id (alias: id)
+            targetId: z.string().optional(), // anchor message (default: latest)
+            maxTokens: z.number().int().optional(), // budget, clamped 1..8000 (default 1500)
+            asActor: z.string().optional(), // serialize from this actor's vantage
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            pack: z.object({
+                spine: z.array(z.unknown()),
+                pins: z.array(z.unknown()),
+                siblings: z.array(z.unknown()),
+                summary: z.string(),
+            }).optional(),
+            serialized: z.string().optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
+    }),
+    // chat:grade — reinforcement on a message (1..5). Persists the score and closes
+    // the loop onto the locked verbs: mark(>=4) strengthens the responder's path,
+    // warn(<=2) adds resistance, 3 neutral. Re-grading the same score is a no-op.
+    "chat:grade": receiver({
+        receiver: "chat:grade",
+        summary: "Grade a chat message 1..5 — mark(>=4)/warn(<=2) the responder's path so routing learns who answers well",
+        request: z.object({
+            messageId: z.string(), // alias: id
+            score: z.number().int().min(1).max(5),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            score: z.number().optional(),
+            reinforced: z.string().optional(), // 'mark' | 'warn' | 'unchanged' | undefined (neutral)
+            target: z.string().optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", reversible: false, idempotent: true, auth: "member",
+    }),
+    // chat:harden — crystallise a resolved thread (#decision or grade>=4 #answer) into
+    // a dim-6 learning. Composes assertHypothesis; marks the spine. Refuses unresolved.
+    "chat:harden": receiver({
+        receiver: "chat:harden",
+        summary: "Harden a resolved thread into a dim-6 learning — talk → grade → harden → knowledge; refuses an unresolved thread",
+        request: z.object({
+            entityId: z.string().optional(), // thread id (alias: id)
+            claim: z.string().optional(), // explicit statement; else derived from the thread
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            hid: z.string().optional(), // hypothesis id
+            statement: z.string().optional(),
+            error: z.string().optional(), // 'not_resolved' if no decision/answer to harden
+        }),
+        effect: "ask", cost: "free", reversible: false, idempotent: false, auth: "member",
+    }),
+    // lens:run — browse a thread's forest by tag (AND / not) + recency or salience.
+    "lens:run": receiver({
+        receiver: "lens:run",
+        summary: "Browse a thread's forest by tag query (tags AND, not exclude) ordered by recency or salience",
+        request: z.object({
+            entityId: z.string().optional(), // thread id (alias: id)
+            tags: z.array(z.string()).optional(), // AND-match
+            not: z.array(z.string()).optional(), // exclude
+            order: z.enum(["recency", "salience"]).optional(),
+            limit: z.number().int().optional(),
+        }),
+        response: z.object({ ok: z.boolean(), count: z.number().optional(), messages: z.array(z.unknown()).optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
+    }),
+    // lens:save — persist a named tag-query for the workspace (upsert by name), so a
+    // frequent browse becomes a one-name re-run / a feed to follow.
+    "lens:save": receiver({
+        receiver: "lens:save",
+        summary: "Save a named tag-query lens for the workspace (upsert by name) — a reusable browse / followable feed",
+        request: z.object({
+            name: z.string(),
+            tags: z.array(z.string()).optional(),
+            not: z.array(z.string()).optional(),
+            order: z.enum(["recency", "salience"]).optional(),
+            limit: z.number().int().optional(),
+        }),
+        response: z.object({ ok: z.boolean(), lens: z.unknown().optional(), count: z.number().optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
+    }),
+    // lens:list — the workspace's saved lenses.
+    "lens:list": receiver({
+        receiver: "lens:list",
+        summary: "List the workspace's saved lenses",
+        request: z.object({}),
+        response: z.object({ ok: z.boolean(), lenses: z.array(z.unknown()).optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
+    }),
+    // lens:delete — remove a saved lens by name.
+    "lens:delete": receiver({
+        receiver: "lens:delete",
+        summary: "Delete a saved lens by name",
+        request: z.object({ name: z.string() }),
+        response: z.object({ ok: z.boolean(), removed: z.number().optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: false, idempotent: true, auth: "member",
+    }),
+    // ── entity (inbox collaboration) — operate on one conversation/entity: reply,
+    // tag/stage-move, profile meta, person link, rename, participants
+    // (text/inbox-collaboration-plan.md). Handlers in resolvers/entity.ts; all
+    // IDOR-gated off ctx.ownerSlug and re-check the row's workspace. ────────────────
+    // entity:reply — the single outbound send. Persists an operator/agent reply, mirrors
+    // it to the customer's channel when the thread isn't web, supersedes a pending draft.
+    // kind='note' stays internal (no egress). replyTo cascades within the thread only.
+    "entity:reply": receiver({
+        receiver: "entity:reply",
+        summary: "Reply to a conversation — persists the message, delivers to the customer's channel (telegram/discord) when not web, clears the pending draft; kind:'note' stays internal",
+        request: z.object({
+            entityId: z.string(), // conv/session/thread id (alias: id)
+            content: z.string(),
+            kind: z.enum(["send", "note"]).optional(), // 'send' (default, egresses) | 'note' (internal)
+            author: z.enum(["staff", "agent"]).optional(), // who speaks (default 'staff')
+            replyTo: z.string().optional(), // parent message id — must be in this thread
+            tags: z.array(z.string()).optional(), // ride the message for the forest's salience axis (≤16)
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            delivered: z.string().optional(), // 'web' | 'telegram' | 'discord' | 'failed'
+            kind: z.string().optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", reversible: false, idempotent: false, auth: "member",
+    }),
+    // entity:tag — add/remove free tags, or move an entity between lifecycle stages
+    // (the single stage_transition writer — emits move/rejected/failed receipts).
+    "entity:tag": receiver({
+        receiver: "entity:tag",
+        summary: "Tag a conversation/entity (add/remove) or move it between lifecycle stages — the sole stage_transition writer",
+        request: z.object({
+            id: z.string(),
+            add: z.array(z.string()).optional(),
+            remove: z.array(z.string()).optional(),
+            move: z.object({
+                lifecycle: z.string(),
+                from: z.string().optional(),
+                to: z.string(),
+                by: z.string().optional(),
+                source: z.string().optional(),
+            }).optional(),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            tags: z.array(z.string()).optional(),
+            moved: z.object({ lifecycle: z.string(), from: z.string().optional(), to: z.string() }).optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", reversible: true, idempotent: false, auth: "member",
+    }),
+    // entity:meta — editable profile fields for an entity (website, industry, location, …).
+    "entity:meta": receiver({
+        receiver: "entity:meta",
+        summary: "Patch an entity's profile fields (website, industry, location, city, country, size, description, phone, email) — empty value clears the field",
+        request: z.object({ id: z.string(), meta: z.record(z.string(), z.unknown()) }),
+        response: z.object({ ok: z.boolean(), meta: z.record(z.string(), z.string()).optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
+    }),
+    // entity:connect — link/unlink an inbox entity to one known person (omit person → unlink).
+    "entity:connect": receiver({
+        receiver: "entity:connect",
+        summary: "Link an inbox conversation to a known person (by uid or label); omit both to unlink",
+        request: z.object({ id: z.string(), personUid: z.string().optional(), personLabel: z.string().optional() }),
+        response: z.object({ ok: z.boolean(), personUid: z.string().nullable().optional(), personLabel: z.string().optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
+    }),
+    // entity:rename — set/clear an inbox entity's subject line (empty → clear).
+    "entity:rename": receiver({
+        receiver: "entity:rename",
+        summary: "Set or clear a conversation's subject line (≤140 chars; empty clears)",
+        request: z.object({ id: z.string(), subject: z.string().optional() }),
+        response: z.object({ ok: z.boolean(), subject: z.string().nullable().optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
+    }),
+    // entity:participant — add/remove an actor on one conversation (remove by uid).
+    "entity:participant": receiver({
+        receiver: "entity:participant",
+        summary: "Add or remove an actor on a conversation (pass remove:<uid> to remove, or uid/kind/label to add)",
+        request: z.object({
+            id: z.string(),
+            uid: z.string().optional(),
+            kind: z.string().optional(),
+            label: z.string().optional(),
+            remove: z.string().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            participant: z.object({ uid: z.string(), kind: z.string(), label: z.string() }).optional(),
+            removed: z.string().optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
+    }),
+    // ── Deliberately NOT contracted (internal plumbing, not an agent capability):
+    //   reply:web · reply:telegram · reply:discord — channel egress fan-out, driven by
+    //     entity:reply, never called directly by an agent.
+    //   conversation:autonomy — read by the channels worker per inbound turn (send vs
+    //     draft), not an operator/agent verb.
+    //   member:invited — an internal event hook, not a callable capability.
+    //   ui:campaigns:compile · ui:campaigns:approve — UI build-pipeline steps.
+    // These have live resolvers but no RECEIVERS entry by design — keep it that way.
+    // ── commerce (storefront products) — handlers in resolvers/commerce.ts ─────────
+    "products:create": receiver({
+        receiver: "products:create",
+        summary: "Create a storefront product with one or more prices",
+        request: z.object({
+            slug: z.string(),
+            name: z.string(),
+            prices: z.array(z.object({
+                unit_amount: z.number(),
+                currency: z.string().optional(),
+                price_type: z.string().optional(),
+                interval: z.string().optional(),
+            })),
+            description: z.string().optional(),
+            images: z.array(z.string()).optional(),
+            product_type: z.string().optional(), // default 'one_time'
+            collection: 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() }),
+        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",
+    }),
+    "products:list": receiver({
+        receiver: "products:list",
+        summary: "List a workspace's storefront products with their prices (public)",
+        request: z.object({ slug: z.string().optional() }),
+        response: z.object({ products: z.array(z.record(z.string(), z.unknown())).optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "public",
+    }),
+    "products:archive": receiver({
+        receiver: "products:archive",
+        summary: "Archive a product (reversible via products:update)",
+        request: z.object({ slug: z.string(), pid: z.string() }),
+        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",
+    }),
+    "storefront:stats": receiver({
+        receiver: "storefront:stats",
+        summary: "Storefront funnel stats — views, checkouts, purchases, revenue, per-product breakdown",
+        request: z.object({ slug: z.string().optional() }),
+        response: z.object({
+            views: z.number().optional(),
+            checkouts: z.number().optional(),
+            purchases: z.number().optional(),
+            revenue_cents: z.number().optional(),
+            byProduct: z.array(z.record(z.string(), z.unknown())).optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
+    }),
+    // ── pages + workspace settings — handlers in resolvers/pages.ts ────────────────
+    "pages:create": receiver({
+        receiver: "pages:create",
+        summary: "Create a workspace page (draft) from a title + sections",
+        request: z.object({ slug: z.string(), title: z.string(), sections: 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() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: false, auth: "member",
+    }),
+    "pages:edit": receiver({
+        receiver: "pages:edit",
+        summary: "Edit a workspace page's title or sections",
+        request: z.object({ slug: z.string(), page: z.string(), title: z.string().optional(), sections: z.record(z.string(), z.unknown()).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() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: false, auth: "member",
+    }),
+    "pages:list": receiver({
+        receiver: "pages:list",
+        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() })) }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
+    }),
+    "pages:publish": receiver({
+        receiver: "pages:publish",
+        summary: "Publish a workspace page",
+        request: z.object({ slug: z.string(), page: z.string() }),
+        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() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
+    }),
+    "settings:write": receiver({
+        receiver: "settings:write",
+        summary: "Write a workspace setting value (caller or authorized descendant)",
+        request: z.object({ slug: z.string().optional(), name: z.string().optional(), description: z.string().optional(), value: z.string() }),
+        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",
+    }),
+    "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() }),
+        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",
+    }),
+    // ── courses + playbook — handlers in resolvers/courses.ts ──────────────────────
+    "course:save": receiver({
+        receiver: "course:save",
+        summary: "Create or update a course (upsert by courseId)",
+        request: z.object({ courseId: z.string(), title: z.string().optional(), description: z.string().optional(), published: z.boolean().optional(), price_cents: z.number().optional() }),
+        response: z.object({ ok: z.boolean(), courseId: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: false, idempotent: true, auth: "member",
+    }),
+    "course:get": receiver({
+        receiver: "course:get",
+        summary: "Get a course with its lessons (lesson bodies redacted unless enrolled or owner)",
+        request: z.object({ workspace: z.string().optional(), slug: z.string().optional(), courseId: z.string() }),
+        response: z.object({ course: z.record(z.string(), z.unknown()).optional(), lessons: z.array(z.record(z.string(), z.unknown())).optional(), enrolled: z.boolean().optional() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "public",
+    }),
+    "course:list": receiver({
+        receiver: "course:list",
+        summary: "List a workspace's courses (published for others, all for the owner)",
+        request: z.object({ workspace: z.string().optional(), slug: z.string().optional() }),
+        response: z.object({ courses: z.array(z.record(z.string(), z.unknown())).optional() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "public",
+    }),
+    "course:enroll": receiver({
+        receiver: "course:enroll",
+        summary: "Enroll the caller in a course (payment_required if priced and not comped)",
+        request: z.object({ workspace: z.string().optional(), slug: z.string().optional(), courseId: z.string() }),
+        response: z.object({ ok: z.boolean(), enrolled: z.boolean().optional() }),
+        effect: "ask", cost: "variable", reversible: false, idempotent: true, auth: "member",
+    }),
+    "course:lessons-save": receiver({
+        receiver: "course:lessons-save",
+        summary: "Upsert one or more lessons on a course",
+        request: z.object({ courseId: z.string(), lessons: z.union([z.array(z.record(z.string(), z.unknown())), z.record(z.string(), z.unknown())]) }),
+        response: z.object({ ok: z.boolean(), saved: z.number().optional() }),
+        effect: "ask", cost: "free", reversible: false, idempotent: true, auth: "member",
+    }),
+    "playbook:save": receiver({
+        receiver: "playbook:save",
+        summary: "Save a learner's playbook entry for a course lesson (upsert)",
+        request: z.object({ course: z.string(), lesson: z.string(), content: z.string().optional() }),
+        response: z.object({ ok: z.boolean() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "public",
+    }),
+    "playbook:get": receiver({
+        receiver: "playbook:get",
+        summary: "Get the caller's playbook entries (optionally scoped to one course)",
+        request: z.object({ course: z.string().optional() }),
+        response: z.object({ entries: z.array(z.record(z.string(), z.unknown())).optional() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "public",
+    }),
+    "playbook:promote": receiver({
+        receiver: "playbook:promote",
+        summary: "Promote a completed playbook into a reusable skill in the workspace's content repo",
+        request: z.object({ course: z.string() }),
+        response: z.object({ ok: z.boolean(), skillRef: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: false, auth: "member",
+    }),
+    // ── social + crawl — handlers in resolvers/social.ts ───────────────────────────
+    "social:publish": receiver({
+        receiver: "social:publish",
+        summary: "Publish a drafted social post to its platform",
+        request: z.object({ slug: z.string(), actorId: z.string(), id: z.string() }),
+        response: z.object({ ok: z.boolean(), id: z.string().optional(), status: z.string().optional(), reason: z.string().optional() }),
+        effect: "ask", cost: "variable", reversible: false, idempotent: false, auth: "update_group",
+    }),
+    "social:news-to-drafts": receiver({
+        receiver: "social:news-to-drafts",
+        summary: "Turn fresh news items into platform-specific social post drafts",
+        request: z.object({ groupId: z.string().optional(), maxItems: z.number().int().max(10).optional(), platforms: z.array(z.string()).optional() }),
+        response: z.object({ ok: z.boolean(), draftsCreated: z.number().optional(), total: z.number().optional(), fresh: z.number().optional() }),
+        effect: "ask", cost: "variable", reversible: false, idempotent: false, auth: "member",
+    }),
+    "web:crawl": receiver({
+        receiver: "web:crawl",
+        summary: "Fetch a URL and extract domain, name, description, and readable text (public)",
+        request: z.object({ url: z.string() }),
+        response: z.object({ ok: z.boolean(), url: z.string().optional(), domain: z.string().optional(), name: z.string().optional(), description: z.string().optional(), text: z.string().optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "public",
+    }),
+    // ── people / companies / conversation — handlers in resolvers/groups.ts ────────
+    "people:create": receiver({
+        receiver: "people:create",
+        summary: "Create a person actor in the workspace",
+        request: z.object({ name: z.string(), email: z.string().optional() }),
+        response: z.object({ ok: z.boolean(), aid: z.string().optional(), name: z.string().optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: false, auth: "member",
+    }),
+    "companies:create": receiver({
+        receiver: "companies:create",
+        summary: "Create a company group in the workspace",
+        request: z.object({ name: z.string() }),
+        response: z.object({ ok: z.boolean(), gid: z.string().optional(), name: z.string().optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: false, auth: "member",
+    }),
+    "conversation:start": receiver({
+        receiver: "conversation:start",
+        summary: "Start a new conversation thread (optionally seeded with a message, function lens, or recipient)",
+        request: z.object({ message: z.string().optional(), fn: z.string().optional(), actorId: z.string().optional(), to: z.string().optional() }),
+        response: z.object({ ok: z.boolean(), threadId: z.string().optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: false, idempotent: false, auth: "member",
+    }),
+    // ── billing — handlers in resolvers/market.ts ──────────────────────────────────
+    "billing:plan": receiver({
+        receiver: "billing:plan",
+        summary: "Change a workspace's plan — returns a checkout URL to complete the upgrade",
+        request: z.object({ slug: z.string(), actorId: z.string(), plan: z.enum(["pro", "agency", "scale"]) }),
+        response: z.object({ ok: z.boolean(), intent: z.string().optional(), checkoutUrl: z.string().optional(), plan: z.string().optional(), reason: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: false, idempotent: false, auth: "update_group",
+    }),
+    "billing:topup": receiver({
+        receiver: "billing:topup",
+        summary: "Top up workspace AI credits — returns a checkout URL for the amount",
+        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",
+    }),
+    // ── video — handler in resolvers/video.ts ──────────────────────────────────────
+    "video:ensure-defaults": receiver({
+        receiver: "video:ensure-defaults",
+        summary: "Ensure a workspace's default video rooms exist — returns which were created vs already present",
+        request: z.object({ workspace: z.string().optional(), slug: z.string().optional() }),
+        response: z.object({ ok: z.boolean(), created: z.array(z.string()).optional(), existing: z.array(z.string()).optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
+    }),
     // ── booking — one calendar, two doors (text/booking-plan.md §5) ───────────────
+    // booking:confirm-payment (public) finalises a paid booking by payment ref.
+    "booking:confirm-payment": receiver({
+        receiver: "booking:confirm-payment",
+        summary: "Confirm a booking after payment settles, by payment reference (public)",
+        request: z.object({ paymentRef: z.string() }),
+        response: z.object({ ok: z.boolean(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "public",
+    }),
     // Both public-bookable: a customer with no account books a slot. The provider
     // side (configure a service) is the separate, gated booking:configure.
     "booking:list-slots": receiver({