@oneie/sdk 0.15.0 → 0.16.0

package/dist/receivers.js

@@ -226,17 +226,45 @@ export const RECEIVERS = {
         request: z.object({ workspace: z.string() }),
         response: ok, effect: "ask", auth: "manage_workspace",
     }),
+    /**
+     * TWO PATHS, ONE RECEIVER — and the second one is why `slug`/`parent` exist.
+     *
+     * Bare (`name` + `type`, no `groupSlug`, no `parent`): unchanged legacy behaviour —
+     * a random gid in D1 `world_groups`. That is what a campaign or a collection
+     * is, and every existing caller stays on it byte for byte.
+     *
+     * Substrate (`groupSlug` + `parent`, BOTH required together): the real group unit —
+     * a TypeDB `group`, a `hierarchy` edge to the parent, an owner `membership`
+     * for the attested caller, and the D1 `owners` row — written by `createGroup`
+     * in `one.ie/web/src/lib/group-unit.ts`. Measured 2026-09-16: no shipped
+     * receiver could write a group with a PARENT and a chosen slug, so a personal
+     * group under a world root had to be typed by hand.
+     *
+     * The gid's SHAPE differs by path and that is the contract change callers
+     * notice: `generateTraceId()` on the bare path, deterministic `group:<slug>`
+     * on the substrate one.
+     *
+     * `parent` NAMES a target; it never authorizes one. The handler walks the
+     * caller's control of the parent workspace and refuses otherwise, and the
+     * owner it writes is the ATTESTED caller — never a body field.
+     */
     "world:create-group": receiver({
         receiver: "world:create-group",
         surfaces: { mcp: true },
-        summary: "Create a group in the caller's workspace",
+        summary: "Create a group — a D1 campaign/collection row, or (with groupSlug+parent) a substrate group under a parent the caller controls",
         request: z.object({
             name: z.string(),
             // "group" is the D1 group_type for campaigns/collections; absent from the TypeDB enum
-            type: GroupEntitySchema.shape["group-type"].or(z.literal("group")),
+            type: GroupEntitySchema.shape["group-type"].or(z.literal("group"))
+                .describe("One of the nine group-type values in schema/one.tql, or the D1-only \"group\". The substrate path (groupSlug+parent) accepts ONLY the nine — TypeDB's @values constraint refuses anything else and that write would fail silently."),
+            groupSlug: z.string().optional()
+                .describe("Bare slug for a SUBSTRATE group; the gid is always `group:<groupSlug>`. Requires `parent` — a slug with no parent would mint an unparented root workspace and is refused. NOT named `slug`: on the service lane `/api/ask` reads `payload.slug ?? payload.workspace` as the workspace the caller NOMINATES for itself, so a field called `slug` here would silently re-identify the caller as the group it is trying to create."),
+            parent: z.string().optional()
+                .describe("gid of the parent group, e.g. \"group:one\". Requires `groupSlug`. It NAMES a target and never authorizes one: the caller must control the parent workspace or the call is refused."),
             tags: z.array(z.string()).optional(),
         }),
-        response: z.object({ gid: z.string() }), effect: "ask", auth: "manage_groups",
+        response: z.object({ gid: z.string().describe("`group:<groupSlug>` on the substrate path; a random trace id on the bare D1 path") }),
+        effect: "ask", auth: "manage_groups",
     }),
     "world:update-group": receiver({
         receiver: "world:update-group",
@@ -376,6 +404,7 @@ export const RECEIVERS = {
             nickname: z.string().optional(),
             title: z.string().optional(),
             avatar: z.string().optional(),
+            cover: z.string().optional(),
             bio: z.string().optional(),
             // contact
             email: z.string().optional(),
@@ -974,8 +1003,23 @@ export const RECEIVERS = {
             board: z.literal("marketplace").optional(),
             slug: z.string().optional(),
             workspace: z.string().optional(),
+            // Rides through unchanged to buildMessage (string field, unaffected)
+            // and is what lets an inbox card show a title instead of a bare tid.
+            title: z.string().optional(),
+            // The structured envelope (`web/src/lib/signal-meta.ts SignalMeta`) —
+            // an object, so buildMessage's string/number-only flatten drops it from
+            // the text body by construction. Declared loosely here (not the exact
+            // shape) because this is the ONE cross-cutting schema every announce
+            // caller reuses; a stricter zod object would have to be kept in lockstep
+            // with the TS type by hand.
+            meta: z.record(z.string(), z.unknown()).optional(),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            taskId: z.string().optional(),
+            matched: z.number().optional().describe("REACH, NEVER DELIVERY. This is `actors.length` from the fan-out (`resolvers/subscriptions.ts:1245`) — how many staked actors the tags MATCHED, not how many received it, read it, or acted on it. Each matched actor got an inbox row; whether any of them moved the task is one `tasks:claim` away and this number cannot see it. A digest that quotes this as 'N people are on it' is reporting a fan-out as a delivery."),
+            actors: z.array(z.string()).optional().describe("The actor ids the fan-out reached — the same reach `matched` counts, itemised. Reaching is not acting."),
         }),
-        response: z.object({ ok: z.boolean(), taskId: z.string().optional(), matched: z.number().optional(), actors: z.array(z.string()).optional() }),
         effect: "ask",
     }),
     "tasks:mine": receiver({
@@ -1028,6 +1072,11 @@ export const RECEIVERS = {
                 name: z.string(),
                 tags: z.array(z.string()),
                 weight: z.number(),
+                // Shipped by the resolver (subscriptions.ts § tasks:everywhere) and undeclared
+                // until now. The response check is WARN-only (bind-receiver.ts:247), so the
+                // field arrived while the contract denied it — and every reader generated FROM
+                // the contract (metaSchema, the MCP tool schema, OpenAPI) could not see it.
+                priority: z.number().optional().describe("Task priority; the ranking input behind `weight`"),
                 notes: z.string().optional(),
                 contextDocs: z.array(z.string()).optional(),
                 workspace: z.string(),
@@ -1039,6 +1088,10 @@ export const RECEIVERS = {
                 offeredByMe: z.boolean(),
                 closedAt: z.string().optional(),
             })),
+            // A cap that reports itself (the /api/things standard). The old 200 clamp
+            // was silent: a 595-row queue came back as 200 rows and read as complete.
+            total: z.number().optional().describe("Visible rows before the limit was applied"),
+            truncated: z.boolean().optional().describe("true = more rows exist than were returned; raise limit or use tasks:board"),
         }),
         effect: "ask", idempotent: true,
     }),
@@ -1321,6 +1374,63 @@ export const RECEIVERS = {
         // a dedupe. The RUN row dedupes (INSERT OR IGNORE); the events do not.
         effect: "ask", idempotent: false,
     }),
+    // ── ehc: ───────────────────────────────────────────────────────────────────
+    //
+    // The first member of this namespace, and it sets the convention: an `ehc:`
+    // receiver acts on ONE named child's plan, and the child's address comes from
+    // the case registry (`one.ie/web/src/lib/ehc/address.ts`), never from a string
+    // a caller typed.
+    //
+    // Read the summary as a limit, not a feature list. This door cannot record a
+    // CYP's own words \u2014 it accepts no voice key, so every record it writes is a
+    // proxy record and renders as MARKED INTERPRETATION naming the adult. A child
+    // speaks through the page that minted their credential. An agent-class caller
+    // is refused outright: Section A is what a child said or an adult's marked
+    // account of what a child communicated, and a generated sentence is neither.
+    "ehc:voice-record": receiver({
+        receiver: "ehc:voice-record",
+        summary: "Record what a child or young person communicated into Section A of their EHC plan, as MARKED INTERPRETATION attributed to the attested adult who recorded it. Authorship is derived from the credential and never from the payload; an agent-class caller is refused (machines do not speak for children); a case that is not synthetic is refused pending a data-residency decision (Article 9 special category data)",
+        request: z.object({
+            cyp: z.string(), // case id, e.g. 'cyp-005' \u2014 resolved through the registry
+            body: z.string(), // exactly what was communicated. Never smoothed.
+            proxyRole: z.string().optional(), // 'parent' | 'keyworker' | 'advocate' \u2014 shown to every reader
+            prompt: z.string().optional(), // which portal question this answers
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            id: z.string().optional(),
+            provenance: z.string().optional(), // always 'proxy-observed' from this door
+            saidAt: z.string().optional(),
+            error: z.string().optional(), // 'not_found' | 'residency_undecided' | 'machines_do_not_speak_for_children' | 'no_voice' | 'empty' | 'too_long'
+            detail: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", reversible: false, idempotent: false, auth: "session",
+    }),
+    // The event a provision's `verification.closesOn` names (cases/cyp-001.ts H1).
+    // A receiver cannot be per-child, so the child rides in `cyp` and the instance
+    // name `ehc:<cyp>:meal-served` is what the event row carries. It records a
+    // human tick that a meal was SERVED — never that one was ordered.
+    "ehc:meal-served": receiver({
+        receiver: "ehc:meal-served",
+        summary: "A named adult ticks that a child was served a meal. Writes one event row named by the provision's closesOn (e.g. ehc:cyp-001:meal-served) attributed to the attested caller, never a payload field; refuses an agent-class caller, an unknown case, a non-synthetic case, and a case with no meal provision",
+        request: z.object({
+            cyp: z.string(), // case id, e.g. 'cyp-001' — resolved through the registry
+            meal: z.enum(["breakfast", "lunch", "tea"]),
+            servedOn: z.string().optional(), // YYYY-MM-DD; defaults to today (UTC)
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            id: z.string().optional(),
+            event: z.string().optional(),
+            provision: z.string().optional(),
+            meal: z.string().optional(),
+            servedOn: z.string().optional(),
+            adult: z.string().optional(),
+            error: z.string().optional(),
+            detail: z.string().optional(),
+        }),
+        effect: "signal", cost: "free", reversible: false, idempotent: false, auth: "session",
+    }),
     "story:chain": receiver({
         receiver: "story:chain",
         summary: "The stories, counted: sets of two or more signals sharing one `origin`, read from the D1 lineage ledger (migrations/0244_story_link.sql). A story is a COUNT over a shared origin, not an entity \u2014 zero new types, zero new dimensions. The number moves as a side effect of signals that already flow; nobody types a row. `count` is the whole qualifying population, `stories` a page of at most 50 ordered by members desc \u2014 a capped count would plateau exactly when the substrate got busy. Zero is a real answer, never an error",
@@ -1472,6 +1582,11 @@ export const RECEIVERS = {
             // task. Without it the task is an orphan: on the board, unreachable from any plan.
             // Refused unless the caller has operate access to the parent.
             parent: z.string().optional(),
+            // 0..1, the same fraction tasks:priority stores. Added 2026-09-14: without it this
+            // door could not express a priority, so every row it filed was invisible to the only
+            // sort the board pages by — 407 of 730 on the day it was added. Omit to leave the
+            // attribute ABSENT (never judged), which is distinct from 0 (judged unimportant).
+            priority: z.number().min(0).max(1).optional(),
             // The viewed /u/<slug> workspace to file the task under. Honored only when the
             // caller is authorized for it (attested staff or owner-tree control); otherwise
             // the resolver falls back to the caller's own slug. Reconciles the create tag
@@ -1851,6 +1966,232 @@ export const RECEIVERS = {
         }),
         effect: "ask", idempotent: true, auth: "member",
     }),
+    // tasks:board — the ONE-REQUEST read of a whole board, with the context a planner needs.
+    //
+    // WHY. Measured 2026-09-13: an agent asked for the board, hit a 200-row page
+    // (the MCP tool's documented cap; `tasks:everywhere` clamps to 200), paged by six
+    // tags, found 353 more rows by NAME ONLY, and never learned the real total.
+    // `tasks:list` has no cap but refuses without a `tag`, so the unfiltered
+    // question — "every task in this group" — had no door at all.
+    //
+    // CONTRACT. (1) `total` is the count that matched the filters BEFORE paging, and
+    // is never an estimate; a partial page carries `nextCursor`, and any budget the
+    // underlying read could not honour is named in `truncated` — a short answer
+    // always says it is short. (2) `summary` is computed over ALL matched rows, not
+    // the page, so a planner can reason about 2,000 tasks while reading 0 of them.
+    // (3) Rows are compact by default; `include` widens them. (4) Served from the
+    // edge snapshot (KV memo of the board, `asOf` stamps it) — never a live TypeDB
+    // read per call (CLAUDE.md § The brain and the edge). `fresh: true` asks for a
+    // rebuild and is honoured at most once per memo window.
+    "tasks:board": receiver({
+        receiver: "tasks:board",
+        surfaces: { mcp: true },
+        summary: "The whole task board in ONE request: every task in a group (or its whole subtree with scope:'tree'), filtered in RAM, with `total` before paging, a `nextCursor` when there is more, `truncated` naming any budget that bit, and a `summary` over ALL matched rows — counts by status/tag/assignee/workspace, the ready set, the blocked set, overdue, unassigned, orphans, no-notes. Use this to plan; use tasks:bulk to act on what it shows.",
+        request: z.object({
+            workspace: z.string().optional().describe("Group slug. Omit for your own. Honoured only if you may read it."),
+            scope: z.enum(["own", "tree"]).optional().describe("tree = this group AND every descendant group (the CEO / agency lens). Default own."),
+            status: z.union([z.string(), z.array(z.string())]).optional()
+                .describe("open | blocked | picked | done | verified | failed | dissolved, one or many. 'active' = open+blocked+picked (the default). 'all' = every status."),
+            tags: z.array(z.string()).optional().describe("Row must carry EVERY tag (AND)."),
+            anyTags: z.array(z.string()).optional().describe("Row must carry AT LEAST ONE of these tags (OR)."),
+            assignee: z.string().optional().describe("Actor slug. '' = unassigned only."),
+            parent: z.string().optional().describe("Only direct children of this task id. '' = top-level rows (no parent)."),
+            search: z.string().optional().describe("Case-insensitive substring on the task name."),
+            ready: z.boolean().optional().describe("true = only rows claimable now (open, and every blocker closed). false = only rows that are NOT claimable now (not open, or at least one blocker still open). Omit for both."),
+            include: z.array(z.enum(["notes", "graph", "dates", "thread"])).optional()
+                .describe("Widen each row. notes = the prose goal, CLIPPED to the first 2000 chars per row (read the whole text one task at a time); graph = children + blocks (the reverse edges); dates = startAt/createdAt/closedAt; thread = the task's inbox conversation (id, comment count, last message). Compact rows already carry parent, blockedBy, dueAt."),
+            view: z.enum(["rows", "summary", "both"]).optional().describe("summary = counts and sets only, no rows (cheapest way to see a 2,000-row board). Default both."),
+            sort: z.enum(["priority", "due-at", "updated-at", "created-at", "name"]).optional().describe("Default priority (desc)."),
+            dir: z.enum(["asc", "desc"]).optional(),
+            limit: z.number().int().min(1).max(2000).optional().describe("Rows per page. Default 500, max 2000."),
+            cursor: z.string().optional().describe("The nextCursor from the previous page."),
+            fresh: z.boolean().optional().describe("Rebuild the snapshot instead of reading the memo. Rate-limited to once per memo window."),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            workspace: z.string().optional(),
+            workspaces: z.array(z.string()).optional().describe("Every group the rows were read from (scope:'tree')."),
+            asOf: z.string().optional().describe("ISO time the snapshot was built. Rows are at most this stale."),
+            cached: z.boolean().optional(),
+            total: z.number().optional().describe("Rows matching the filters, before paging. Exact — UNLESS `truncated.rows` is present, in which case the snapshot itself was capped and total is a floor."),
+            returned: z.number().optional(),
+            nextCursor: z.string().optional().describe("Present iff more rows match. Absent = you have them all."),
+            truncated: z.object({
+                rows: z.number().optional().describe("The snapshot hit its row budget; this many unique rows were read. total is a floor."),
+                edges: z.boolean().optional().describe("parent/blockedBy edges were capped — a row may read as unblocked or orphaned when it is not."),
+                tags: z.number().optional().describe("This many returned rows may be missing tags."),
+            }).optional().describe("Absent = nothing was cut. Present = say so before you plan on it."),
+            summary: z.object({
+                byStatus: z.record(z.string(), z.number()),
+                byTag: z.record(z.string(), z.number()).describe("Bare tags only (no workspace:/slug:/@ namespaces), top 100 by count."),
+                byAssignee: z.record(z.string(), z.number()).describe("'' key = unassigned."),
+                byWorkspace: z.record(z.string(), z.number()),
+                ready: z.number().describe("Open with every blocker closed — claimable now."),
+                blocked: z.number().describe("Has at least one open blocker, or status blocked."),
+                overdue: z.number(),
+                unassigned: z.number(),
+                orphans: z.number().describe("No parent — unreachable from any plan's containment walk."),
+                noNotes: z.number().describe("No prose goal — the rows a puller cannot act on."),
+                readyIds: z.array(z.string()).describe("Top 50 ready rows by priority."),
+                blockedIds: z.array(z.string()).describe("Top 50 blocked rows by priority."),
+            }).optional(),
+            tasks: z.array(z.object({
+                tid: z.string(),
+                name: z.string(),
+                status: z.string(),
+                priority: z.number(),
+                tags: z.array(z.string()).describe("Bare tags; workspace:/@assignee are lifted into their own fields."),
+                assignee: z.string().optional(),
+                workspace: z.string(),
+                parent: z.string().optional(),
+                blockedBy: z.array(z.string()).optional(),
+                openBlockers: z.number().optional().describe("How many of blockedBy are not yet done/verified/dissolved."),
+                ready: z.boolean(),
+                dueAt: z.string().optional(),
+                overdue: z.boolean().optional(),
+                // include: dates
+                startAt: z.string().optional(),
+                createdAt: z.string().optional(),
+                closedAt: z.string().optional(),
+                // include: notes
+                notes: z.string().optional(),
+                // include: graph
+                children: z.array(z.string()).optional(),
+                blocks: z.array(z.string()).optional(),
+                // include: thread — the same D1 conversation tasks:comment writes and /in lists
+                thread: z.object({
+                    threadId: z.string().optional().describe("The inbox thread id; absent = nobody has commented yet."),
+                    comments: z.number(),
+                    lastAt: z.string().optional(),
+                    lastAuthor: z.string().optional(),
+                    lastBody: z.string().optional().describe("First 280 chars of the latest message."),
+                }).optional(),
+            })).optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", idempotent: true, auth: "member",
+        examples: [
+            { workspace: "one", view: "summary" },
+            { workspace: "one", scope: "tree", status: "active", ready: true, limit: 100 },
+            { workspace: "one", anyTags: ["launch", "story"], include: ["notes", "graph"] },
+        ],
+    }),
+    // tasks:bulk — the ONE-REQUEST door for N task mutations.
+    //
+    // Every other task write here takes a single `tid`, so refining a 595-row board
+    // (measured, workspace `one`, 2026-09-11) costs 595+ round trips. That is the
+    // reason the board has never been refined. This takes up to 25 rows and reports
+    // a receipt PER ROW — never a single top-level ok that hides a partial run.
+    //
+    // It reimplements no write: the resolver loops and calls the existing
+    // single-tid resolvers with the SAME attested ctx, so authority, the status
+    // gates and the D1 tag mirror are all inherited rather than re-derived. The
+    // `workspace` field (envelope or per row) is a REQUEST, exactly as on every
+    // single-tid write — effectiveWorkspace downgrades it when the caller is
+    // neither staff nor in control of it.
+    "tasks:bulk": receiver({
+        receiver: "tasks:bulk",
+        surfaces: { mcp: true },
+        summary: "Plan and act on many tasks in ONE request. Three modes, combinable: `creates` files up to 25 new tasks (with `ref` handles so rows in the same call can parent/block each other — a whole plan tree in one call); `edits` changes up to 25 named rows (title/status/priority/notes/assignee/tags/dates/dependencies/parent/comment — `parent` MOVES a row under another, the one door that writes `containment` after birth, and an empty string makes it a root again); `where`+`set` applies ONE edit to every row a tasks:board filter matches (dryRun defaults TRUE — the preview returns the matched ROWS themselves in `rows`, not just their tids, so you read the ≤25 rows you are about to change and then re-send the identical call with dryRun:false; applies 25 per call and returns `nextCursor` to continue). Returns a receipt PER ROW (ok, per-field reason, retryable) plus total/attempted/applied/failed — a row never attempted says so by name, so a partial run can never read as a success.",
+        request: z.object({
+            edits: z.array(z.object({
+                tid: z.string(),
+                title: z.string().optional(),
+                status: z.string().optional().describe("open | blocked | picked | done | verified | failed | dissolved"),
+                priority: z.number().optional().describe("1-100 slider, same scale as tasks:priority"),
+                notes: z.string().optional().describe("Prose goal; empty string clears"),
+                parent: z.string().optional().describe("MOVE this row under another — the only door that writes a `containment` edge AFTER birth (tasks:create and tasks:subtask write one only at birth, which is why a story could never be made a sub-story of another). An existing task id, or a `ref` created EARLIER in `creates`. EMPTY STRING CLEARS: the row becomes a root again, and clearing a row that already had no parent is a silent success. Refused by name, never silently: `cycle` if the new parent is this row or any row beneath it (walked transitively, and a walk that could not FINISH answers `undetermined` and is refused — never guessed at); `not_found` if the parent does not exist, OR the caller lacks operate access to it, OR the row's CURRENT parent is one the caller cannot operate (detaching changes that tree too) — the same rule, and the same word, tasks:create's `parent` uses; `cross_workspace` if the two ends live in different workspaces and the caller is not staff. CLAIM-GATE CONSEQUENCE — this is not only a tree edit: `tasks:claim` refuses `picked` while an OPEN `containment` child exists, so hanging an open row under a claimable parent makes that parent UNCLAIMABLE, and moving the last open child away makes it claimable again. Deliberately absent from `set`: a filter-driven mass re-parent moves whole subtrees at once — and multiplies that claim-gate consequence by the match count — so this is per-row only."),
+                assignee: z.string().optional().describe("Actor slug; empty string unassigns"),
+                addTags: z.array(z.string()).optional().describe("Bare words only — no ':' and no leading '@'"),
+                removeTags: z.array(z.string()).optional(),
+                dueAt: z.string().nullable().optional().describe("ISO date; null or '' clears. Same semantics as tasks:schedule"),
+                startAt: z.string().nullable().optional(),
+                addBlockedBy: z.array(z.string()).optional().describe("Task ids (or `ref`s from `creates`) this row must wait for — tasks:depend per id"),
+                removeBlockedBy: z.array(z.string()).optional().describe("tasks:undepend per id"),
+                comment: z.string().optional().describe("Post to the task's inbox thread (tasks:comment) — say WHY you changed it, so the humans watching the thread see the decision"),
+                workspace: z.string().optional().describe("Per-row override of the envelope workspace. A request, never a grant."),
+            })).max(25).optional(),
+            creates: z.array(z.object({
+                ref: z.string().optional().describe("A local handle, e.g. 'a'. Other rows in THIS call may name it in parent/blockedBy/addBlockedBy; the receipt maps ref → tid."),
+                title: z.string(),
+                notes: z.string().optional(),
+                tags: z.array(z.string()).optional(),
+                assignee: z.string().optional(),
+                priority: z.number().optional(),
+                parent: z.string().optional().describe("Existing task id or a ref created EARLIER in this array"),
+                blockedBy: z.array(z.string()).optional().describe("Existing task ids or refs created earlier in this array"),
+                dueAt: z.string().optional(),
+                workspace: z.string().optional(),
+            })).max(25).optional(),
+            where: z.object({
+                status: z.union([z.string(), z.array(z.string())]).optional(),
+                tags: z.array(z.string()).optional(),
+                anyTags: z.array(z.string()).optional(),
+                assignee: z.string().optional(),
+                parent: z.string().optional(),
+                search: z.string().optional(),
+                ready: z.boolean().optional(),
+                scope: z.enum(["own", "tree"]).optional(),
+            }).optional().describe("A tasks:board filter. Requires `set`. Matches are read from the same snapshot tasks:board serves."),
+            set: z.object({
+                status: z.string().optional(),
+                priority: z.number().optional(),
+                assignee: z.string().optional(),
+                addTags: z.array(z.string()).optional(),
+                removeTags: z.array(z.string()).optional(),
+                dueAt: z.string().nullable().optional(),
+                comment: z.string().optional(),
+            }).optional().describe("The ONE edit applied to every `where` match. title/notes are deliberately absent — those are per-row. TWO ROUTES, AND THIS IS THE NARROWER ONE. `assignee` here is the DIRECT route: you decide the owner, for work whose owner is not in doubt. The DEFAULT is the other route — `tasks:announce` (or `signal(\"world\", {tags})`) walks the weighted tag→receiver paths to whoever STAKED those tags, marks the delivery, and the next route is smarter for it; the CEO is an observer there, not a bottleneck. Prefer the stake route and keep this one for the unambiguous case. And when you read the announce back: its `matched` is reach, never delivery."),
+            dryRun: z.boolean().optional().describe("For `where`: defaults TRUE. Pass false to apply. Ignored by edits/creates."),
+            cursor: z.string().optional().describe("For `where`: the nextCursor from the previous call"),
+            workspace: z.string().optional().describe("Workspace to act in, for every row. Honoured only if you are staff or control it."),
+        }).refine((v) => (v.edits?.length ?? 0) + (v.creates?.length ?? 0) > 0 || (!!v.where && !!v.set), {
+            message: "send edits, creates, or where+set",
+            path: ["edits"],
+        }).refine((v) => !v.where === !v.set, { message: "where and set go together", path: ["where"] }),
+        response: z.object({
+            ok: z.boolean().describe("The CALL's outcome, not the rows'. Read applied/failed."),
+            total: z.number().optional(),
+            attempted: z.number().optional(),
+            applied: z.number().optional(),
+            failed: z.number().optional(),
+            notAttempted: z.number().optional(),
+            error: z.string().optional(),
+            detail: z.string().optional(),
+            created: z.record(z.string(), z.string()).optional().describe("ref → tid for every `creates` row that landed"),
+            matched: z.number().optional().describe("`where`: rows the filter matched in total, across all pages. EXACT — unless `truncated` is present, and then it is a FLOOR. Quote it as 'at least N'."),
+            truncated: z.object({
+                rows: z.number().optional().describe("The board snapshot hit its row budget; this many unique rows were read. `matched` is a FLOOR — rows exist that the filter never saw, so the set you are previewing is a subset of the set you asked for."),
+                edges: z.boolean().optional().describe("The dependency branch was capped. `where:{ready:true}` is computed from `blockedBy`, so a row can match as ready while it is in fact blocked."),
+                tags: z.number().optional().describe("The tag branch was capped; this many rows have uncertain tags. A `tags`/`anyTags` filter may have MISSED rows, and the `tags` on the rows returned above may be short."),
+            }).optional().describe("`where`: the budget that bit, named — the same word and the same shape tasks:board serves, because it is the same snapshot. Three budgets, independent, each key present only when THAT one bit. ABSENT MEANS NOTHING WAS CUT — absent and `false` are different answers, so branch on the key's presence and never on its value. This is the field to read rather than the prose in `detail`: `detail` is for a human reading a log, and on an aborted run it is overwritten by the abort reason, while this survives. A receiver that caps, pages or samples names the budget that bit, in the response, every time."),
+            matchedIds: z.array(z.string()).optional().describe("`where`: the tids this call covers (the ones it would apply, on dryRun)"),
+            rows: z.array(z.record(z.string(), z.unknown())).optional().describe("`where`, DRY RUN ONLY: the matched rows THEMSELVES — `matchedIds` with its contents attached. Same rows, same order (rows[i].tid === matchedIds[i], element for element), same shape tasks:board serves: tid · name · status · priority · tags · assignee · workspace · parent · blockedBy · dueAt · startAt · createdAt · closedAt · updatedAt · notes. This is what makes the dry run a READ you can judge instead of a count you must take on faith: you see the ≤25 rows you are about to change — their owners, their blockers, their tags — and then re-send the IDENTICAL call with dryRun:false. One filter expression, not two that can disagree about what the set is. Costs nothing: these are the rows the match was computed from, already in hand. ABSENT on an apply — `results` carries a receipt per tid there, and a second copy of the rows is the larger answer to the smaller question. TWO TRAPS. (1) `tags` is the BARE lens — namespaced words (`plan:…`, `cycle:…`, `workspace:…`) and the `@slug` assignee tag are stripped, and `assignee`/`workspace` are DERIVED from the stripped ones. `tags: []` therefore means NO ROUTING WORDS, never 'no tags on this row': measured 2026-09-15, rows carrying six tags each report `tags: []`. (2) A row here is at most `asOf` stale (the 60s board memo) and describes the row BEFORE `set` — never read it back as the result of the write."),
+            dryRun: z.boolean().optional(),
+            nextCursor: z.string().optional().describe("`where`: present iff more matches remain — resend the same call with this cursor"),
+            results: z.array(z.object({
+                tid: z.string(),
+                ref: z.string().optional(),
+                ok: z.boolean(),
+                reason: z.string().optional(),
+                retryable: z.boolean().optional(),
+                fields: z.array(z.object({
+                    field: z.string(),
+                    ok: z.boolean(),
+                    reason: z.string().optional(),
+                    detail: z.string().optional(),
+                    retryable: z.boolean().optional(),
+                })).optional(),
+            })).optional(),
+        }),
+        effect: "ask", idempotent: false, auth: "member",
+        examples: [
+            { edits: [{ tid: "task:abc", status: "dissolved", comment: "Superseded by task:def" }, { tid: "task:def", notes: "Done when X", addTags: ["planning"] }], workspace: "one" },
+            { creates: [{ ref: "plan", title: "Launch the pricing page" }, { ref: "copy", title: "Write pricing copy", parent: "plan" }, { title: "Ship pricing page", parent: "plan", blockedBy: ["copy"] }], workspace: "one" },
+            { where: { status: "open", tags: ["launch"], assignee: "" }, set: { assignee: "cmo", comment: "Routing unowned launch work to marketing" }, dryRun: true, workspace: "one" },
+            { creates: [{ ref: "arc", title: "The story we are actually telling", tags: ["story"] }], edits: [{ tid: "task:oldstory", parent: "arc", comment: "Nested under the main story" }, { tid: "task:looseplan", parent: "" }], workspace: "one" },
+        ],
+    }),
     "tasks:follow": receiver({
         receiver: "tasks:follow",
         surfaces: { mcp: true },
@@ -2667,6 +3008,10 @@ export const RECEIVERS = {
             // author (resolver-body-actorId-not-identity) and needs an attestation
             // decision, not a schema line.
             role: z.enum(["user", "assistant"]).optional(),
+            // The structured envelope forwarded from `/signal/:group` — see
+            // `web/src/lib/signal-meta.ts SignalMeta`. Loose on purpose (see
+            // tasks:announce's `meta` field for why).
+            meta: z.record(z.string(), z.unknown()).optional(),
         }),
         response: z.object({
             ok: z.boolean(),
@@ -2879,6 +3224,7 @@ export const RECEIVERS = {
         response: z.object({
             ok: z.boolean(),
             delivered: z.string().optional(), // 'web' | 'telegram' | 'discord' | 'failed'
+            deliveryError: z.string().optional(), // present iff delivered==='failed' — the platform's own words; the reply IS still persisted
             kind: z.string().optional(),
             error: z.string().optional(),
         }),
@@ -3659,7 +4005,14 @@ export const RECEIVERS = {
         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() })) }),
+        response: z.object({ pages: z.array(z.object({
+                slug: z.string(),
+                title: z.string(),
+                status: z.string(),
+                url: z.string().optional().describe("The page's public path, /p/<slug>"),
+                updated_at: z.number().optional().describe("Last modified, epoch ms"),
+                views: z.number().nullable().optional().describe("Pageviews from the analytics pixel. NULL means no pageview row exists — render it as '—', NOT as 0. A page live for five minutes with no visitors and a page nothing is measuring must not read the same."),
+            })) }),
         effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
     }),
     "pages:publish": receiver({
@@ -3676,6 +4029,55 @@ export const RECEIVERS = {
         response: z.object({ ok: z.boolean(), published: z.number().optional(), error: z.string().optional() }),
         effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
     }),
+    // WHY THIS IS DECLARED. `pages:delete` shipped as a resolver with no registry
+    // row, so it reached the handler only through the undeclared-receiver escape
+    // hatch — no edge zod parsing, no auth floor. Its two live callers send
+    // `{slug, page}` (`scripts/demo-instantiate-movers.ts`) and
+    // `{slug, actorId, page}` (`channels/src/tools/pages.ts`). `actorId` is NOT
+    // declared here on purpose: `pagesDenyReason` authorizes off `ctx` alone and
+    // has never read it, so declaring it would publish a field nothing consumes
+    // and invite a caller to think it authorizes something.
+    //
+    // `auth: "member"` matches every sibling in this family. A tighter floor
+    // reasoned out fresh would break the channels tool, and the break would look
+    // like a bug in whatever called it.
+    "pages:delete": receiver({
+        receiver: "pages:delete",
+        summary: "Permanently delete a workspace page. NOT REVERSIBLE — pages:restore only UPDATEs an existing row and cannot re-insert a deleted one, so nothing that ships can undo this.",
+        request: z.object({ slug: z.string(), page: z.string() }),
+        response: z.object({ ok: z.boolean(), slug: z.string().optional(), title: z.string().optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: false, idempotent: true, auth: "member",
+    }),
+    "pages:unpublish": receiver({
+        receiver: "pages:unpublish",
+        summary: "Take a published page back to draft — the inverse of pages:publish. Writes no version snapshot (no content changes) and leaves published_at as the record of when it last went live.",
+        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",
+    }),
+    "pages:bulk": receiver({
+        receiver: "pages:bulk",
+        summary: "Apply ONE op (publish | unpublish | delete) to an EXPLICIT list of pages — one authority walk, one round trip, a per-row answer.",
+        request: z.object({
+            slug: z.string(),
+            op: z.enum(["publish", "unpublish", "delete"]),
+            pages: z.array(z.string()).min(1).max(100).describe("Page slugs, REQUIRED and non-empty. There is deliberately no omitted-means-all case: pages:publish-pack has one, and an implicit whole-workspace scope is exactly what a selection UI must never be able to send. Over 100 is refused BY NAME (`too_many:N>100`), never truncated."),
+        }),
+        response: z.object({
+            ok: z.boolean().describe("Describes THE CALL, not the rows. A run where every row failed still answers ok:true — read `changed` and `failed`, never this, to report what happened."),
+            op: z.string().optional(),
+            requested: z.number().optional().describe("Rows attempted, after de-duplication."),
+            changed: z.number().optional().describe("Rows the op actually changed. This is the number to quote."),
+            failed: z.number().optional().describe("requested - changed. Present even when 0, so a caller cannot miss it."),
+            results: z.array(z.object({
+                slug: z.string(), ok: z.boolean(), title: z.string().optional(), error: z.string().optional(),
+            })).optional().describe("Per-row outcome, in the order attempted. A failed row names its own reason (`not_found`, `no_db`)."),
+            error: z.string().optional(),
+        }),
+        // `reversible: false` because delete is one of the three ops and the
+        // envelope cannot be conditional. publish/unpublish are each other's undo.
+        effect: "ask", cost: "free", reversible: false, idempotent: true, auth: "member",
+    }),
     "pages:fill-pack": receiver({
         receiver: "pages:fill-pack",
         summary: "Fill a pack's instantiated pages with real business facts — one call, still drafts. Never fabricates a testimonial; pricing derives from one rate, not typed per page.",
@@ -4017,7 +4419,17 @@ export const RECEIVERS = {
         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() }),
+        response: z.object({
+            ok: z.boolean(),
+            url: z.string().optional().describe("The URL that ANSWERED, not the one asked for — a crawl of an apex that 301s to www reports the www URL here"),
+            domain: z.string().optional(),
+            name: z.string().optional(),
+            description: z.string().optional(),
+            text: z.string().optional(),
+            error: z.string().optional().describe("NAMED, never a single catch-all. invalid_url · https_required · dns_unresolved · blocked_host · redirect_no_location · redirect_invalid_url · redirect_blocked:<ssrf reason> · too_many_redirects · fetch_failed:<status> · not_html · timeout · fetch_error. Until 2026-09-15 every network cause collapsed into `fetch_error`, so a 301 apex->www and an origin refusing the fetch outright were indistinguishable — read `detail` beside this."),
+            detail: z.string().optional().describe("The underlying cause in words, ≤200 chars — the exception class and message, the blocked hop, or the content-type that was refused. Present on most errors, never on success."),
+            redirects: z.number().optional().describe("Hops followed before the answer. Redirects are followed MANUALLY, at most 4, and the SSRF guard re-runs on every hop — a public URL that redirects to a private address is refused at that hop with redirect_blocked."),
+        }),
         effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "public",
     }),
     // ── people / companies / conversation — handlers in resolvers/groups.ts ────────
@@ -4319,7 +4731,7 @@ export const RECEIVERS = {
         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() }),
+        request: z.object({ workflowId: z.string(), runId: z.string().optional(), limit: z.number().int().min(1).max(200).optional(), stepId: z.string().optional(), stepLimit: z.number().int().min(1).max(100).optional() }),
         response: z.object({
             runs: z.array(z.object({
                 id: z.string(), status: z.string(),
@@ -5510,6 +5922,325 @@ export const RECEIVERS = {
         reversible: false, idempotent: false, settles: "none",
         examples: [{ slug: "story:demo", kept: false }],
     }),
+    // ── duty: — provision that was PROMISED, recorded as delivered or missed ──
+    // (resolvers/duty.ts · migrations/0245_duties.sql · lib/ehc/duty.ts)
+    //
+    // The family exists because `promise:*` inverts wrong for a statutory duty:
+    // `promises.ts:96` lets the maker settle its own promise, and `:112` defaults
+    // a missing verdict to KEPT. Here the certifier is a DIFFERENT actor, refused
+    // at write time by `CHECK (certifier <> holder)`, and NO caller supplies a
+    // verdict at all — the state is computed from counts and the clock, so a
+    // window that lapsed with nothing recorded reads as `breached`, not as blank.
+    // Spec: text/ehc-substrate-plan.md §3.1.
+    "duty:make": receiver({
+        receiver: "duty:make",
+        summary: "State a duty you OWE — terms, one observable, an owed count, a due_at, and a certifier who must not be you. The holder is the attested caller, never a body field; certifier === holder is refused by the resolver and by a D1 CHECK",
+        request: z.object({
+            slug: z.string().describe("Stable id, e.g. ehc:cyp-005:H2. [A-Za-z0-9_:/-], max 128"),
+            terms: z.string().describe("What is owed — hashed verbatim into terms_hash"),
+            observable: z.string().describe("What ONE delivery looks like: 'a meal, on a date, received' — not 'a meal service was commissioned'"),
+            certifier: z.string().describe("Who may attest delivery. MUST NOT be the holder — the duty-holder never grades its own homework"),
+            owed: z.number().int().describe("How many deliveries are owed. 0 means not yet quantified and computes to state 'unknown', never 'met'"),
+            due_at: z.number().optional().describe("Epoch ms the window closes. ABSENT IS UNKNOWN, never 'no deadline' — an unwritten window computes to 'unknown', never to on-track"),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            slug: z.string().optional(),
+            version: z.number().optional(),
+            state: z.enum(["unknown", "owed", "part-met", "met", "breached"]).optional(),
+            terms_hash: z.string().optional(),
+            certifier: z.string().optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", auth: "member",
+        reversible: false, idempotent: true, settles: "none",
+        examples: [{ slug: "ehc:cyp-005:H2", terms: "A hot meal every weekday, including school holidays", observable: "A meal, on a date, received", certifier: "ehc-social-worker", owed: 45 }],
+    }),
+    "duty:amend": receiver({
+        receiver: "duty:amend",
+        summary: "Amend by LINEAGE — writes a new row at version+1 with `supersedes`; the prior version is never mutated and never deleted. Holder only today: an amendment against the holder's will needs a tribunal rung that does not exist yet (§3.3 Q3) and is refused by name",
+        request: z.object({
+            slug: z.string(),
+            terms: z.string().optional(),
+            observable: z.string().optional(),
+            certifier: z.string().optional().describe("Still must not equal the holder"),
+            owed: z.number().int().optional(),
+            due_at: z.number().nullable().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            slug: z.string().optional(),
+            version: z.number().optional(),
+            supersedes: z.string().nullable().optional(),
+            state: z.enum(["unknown", "owed", "part-met", "met", "breached"]).optional(),
+            terms_hash: z.string().optional(),
+            blocked_on: z.string().optional().describe("'tribunal-rung' — the missing authority, named rather than silently allowed"),
+            error: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", auth: "member",
+        reversible: false, idempotent: false, settles: "none",
+        examples: [{ slug: "ehc:cyp-005:H2", owed: 190, terms: "A hot meal every weekday of the YEAR, holidays included" }],
+    }),
+    "duty:evidence": receiver({
+        receiver: "duty:evidence",
+        summary: "File ONE delivery against the current version — the CERTIFIER only, matched against the persisted certifier from the attested caller. Idempotent by sha256(slug‖version‖ref), so a re-file changes nothing. A new delivery MARKS the holder's path",
+        request: z.object({
+            slug: z.string(),
+            ref: z.string().describe("The delivery, named: 'meal 2026-09-12', 'SLT session note wk37'"),
+            version: z.number().int().optional().describe("Defaults to the current version; an older one is refused, not back-filed quietly"),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            slug: z.string().optional(),
+            version: z.number().optional(),
+            id: z.string().optional(),
+            evidenced: z.number().optional().describe("A COUNT over duty_evidence, never a stored column"),
+            owed: z.number().optional(),
+            state: z.enum(["unknown", "owed", "part-met", "met", "breached"]).optional(),
+            recorded: z.boolean().optional().describe("false ⇒ this exact delivery was already on record"),
+            error: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", auth: "member",
+        reversible: false, idempotent: true, settles: "none",
+        examples: [{ slug: "ehc:cyp-005:H2", ref: "hot meal received 2026-09-12" }],
+    }),
+    "duty:breach": receiver({
+        receiver: "duty:breach",
+        summary: "Compute the verdict and land it in the record. SILENCE IS BREACH: owed > count(evidence) with the window closed is `breached`, and no caller supplies a verdict. Warns the holder's path on the transition into breach — once, because the TRANSITION is the event. `breached` is NOT terminal: late evidence recomputes to `met`",
+        request: z.object({ slug: z.string() }),
+        response: z.object({
+            ok: z.boolean(),
+            slug: z.string().optional(),
+            version: z.number().optional(),
+            state: z.enum(["unknown", "owed", "part-met", "met", "breached"]).optional(),
+            changed: z.boolean().optional(),
+            owed: z.number().optional(),
+            evidenced: z.number().optional(),
+            due_at: z.number().nullable().optional(),
+            holder: z.string().optional(),
+            breached: z.boolean().optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", auth: "member",
+        reversible: true, idempotent: true, settles: "none",
+        examples: [{ slug: "ehc:cyp-005:H2" }],
+    }),
+    "duty:get": receiver({
+        receiver: "duty:get",
+        summary: "Read a duty with its state COMPUTED, writing nothing — the read a plan surface makes. NOT public (a duty names a child): holder, certifier or platform staff only. The family's own rung is not modelled yet",
+        request: z.object({ slug: z.string() }),
+        response: z.object({
+            ok: z.boolean(),
+            slug: z.string().optional(),
+            version: z.number().optional(),
+            supersedes: z.string().nullable().optional(),
+            holder: z.string().optional(),
+            certifier: z.string().optional(),
+            terms: z.string().optional(),
+            observable: z.string().optional(),
+            owed: z.number().optional(),
+            evidenced: z.number().optional(),
+            due_at: z.number().nullable().optional(),
+            state: z.enum(["unknown", "owed", "part-met", "met", "breached"]).optional(),
+            stored_state: z.string().optional().describe("The cached column. It should equal `state`; a divergence means nothing has recomputed since the window closed"),
+            error: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", auth: "member",
+        reversible: true, idempotent: true, settles: "none",
+        examples: [{ slug: "ehc:cyp-005:H2" }],
+    }),
+    // ── ui: — an agent's hand on the operator's own browser ───────────────────
+    //
+    // The ONLY receiver in the registry whose effect is a MOVE OF A HUMAN'S
+    // SCREEN, so it is the only one where "authority off ctx, never the payload"
+    // is not hygiene but the whole feature. Given a target-viewer field, this
+    // receiver is a machine for pushing any actor's reader anywhere — so there is
+    // no such field, and a payload that names one is REFUSED rather than ignored
+    // (silently stripping it would answer ok:true to a caller whose model of the
+    // world is wrong, and teach it the call worked).
+    "ui:navigate": receiver({
+        receiver: "ui:navigate",
+        summary: "Move the CALLER'S OWN reader to a same-origin path. Two independent checks, because one of them runs in code an untrusted caller can reach: (1) the SERVER addresses only the session that made this call — authority comes off the attested ctx, there is NO field naming a principal — `viewer`, `viewerId`, `actorId`, `actor`, `target`, `targetViewer`, `targetActor`, `session`, `sessionId`, `userId`, `uid`, `ownerSlug`, `audience` — and a payload carrying any of them is REFUSED outright rather than silently stripped (`workspace`/`slug` are NOT refused: they scope, they cannot name a reader); (2) the BROWSER independently drops any command that did not arrive on a stream it opened itself, so a command that somehow escaped (1) still moves nobody. Same-origin PATHS only — an absolute URL, a scheme, or a protocol-relative href is refused, never rewritten.",
+        request: z
+            .object({
+            href: z
+                .string()
+                .min(1)
+                .describe("Where to. A SAME-ORIGIN PATH: one leading '/', e.g. '/u/one/in'. Refused, never sanitised: an absolute URL ('https://evil.com/x'), any scheme ('javascript:', 'data:'), a protocol-relative href ('//evil.com'), the backslash form ('/\\evil.com'), a bare host ('evil.com/x'), and any href containing a tab/CR/LF. Measured against node's WHATWG parser: new URL('//evil.com', 'https://one.ie'), new URL('/\\evil.com', …) and new URL('/<TAB>/evil.com', …) ALL resolve to https://evil.com/ — the parser strips tab/CR/LF anywhere in the input, so the tab form is a real bypass of a naive startsWith('/') check. A navigate receiver that accepts arbitrary hrefs is an open redirect with an agent attached."),
+            reason: z
+                .enum(["select", "command", "agent"])
+                .optional()
+                .describe("Why the move happened, for the host's own judgment. Mirrors NavigateRequest.reason in one.ie/web/src/lib/navigate.ts, and is ECHOED back on the response so the transport has something to forward. CALLER-ASSERTED and carrying NO authority: an agent is free to send 'select', which reads as 'an operator clicked'. Nothing gates on it, and a host must not read it as evidence that a human was there."),
+            replace: z
+                .boolean()
+                .optional()
+                .describe("Replace the current history entry instead of pushing a new one. Default false: collapsing the entry deletes the operator's way back, so it is opt-in."),
+        })
+            .describe("There is deliberately no field naming WHO to move. The reader moved is always the caller's own, resolved from the attested session server-side. If you find yourself wanting a target, that is the defect arriving."),
+        response: z.object({
+            ok: z.boolean(),
+            href: z.string().optional().describe("The href as accepted — byte-identical to the request, never a rewritten one"),
+            replace: z.boolean().optional(),
+            reason: z
+                .enum(["select", "command", "agent"])
+                .optional()
+                .describe("The request's `reason`, echoed unchanged. Caller-asserted — never evidence of a human"),
+            audience: z
+                .string()
+                .optional()
+                .describe("The caller's OWN attested slug — echoed so a caller can see whose reader it addressed. Never a value the caller supplied"),
+            delivered: z
+                .boolean()
+                .optional()
+                .describe("Whether the command actually reached a browser. FALSE today for every call: the receiver validates and addresses, and the transport that carries it to the reader is a separate row (task:01a0a3789956c0b2d78d2487). A receiver that reached nobody must say so rather than answer a bare ok:true — the route:to-* namespace is the standing example of what the other choice costs"),
+            note: z.string().optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask",
+        cost: "free",
+        auth: "session",
+        reversible: true,
+        idempotent: false,
+        settles: "none",
+        examples: [{ href: "/u/one/in", reason: "agent" }],
+    }),
+    // ── media:* ─────────────────────────────────────────────────────────────────
+    // THE WORKSPACE MEDIA LIBRARY, for an agent.
+    //
+    // WHY. Measured 2026-09-16 over this file: 362 receivers, and not one touched a
+    // stored asset. `video:*` (14) is rooms, sessions and recordings — a call, never a
+    // file. So the media console at `/u/<slug>/media` was HTTP-only: a human could list,
+    // upload and generate; an agent could not reach any of it, from any surface.
+    //
+    // THE ONE AUTHORITY RULE, and it is not either HTTP door's. `workspace` is a SCOPE
+    // REQUEST on all three — never an identity, never a default. It is honoured only
+    // through the owner-tree walk, and a request the caller cannot clear is REFUSED BY
+    // NAME. The three HTTP write doors (`api/media/generate.ts:35`, storefront
+    // image-upload/image-generate) instead derive from `locals.slug` and IGNORE the
+    // workspace handed to them, so an agency uploading at `/u/client/media` files into
+    // the AGENCY's library while the grid shows the CLIENT's — and answers 200. These
+    // receivers do not inherit that: a silent downgrade is a success you cannot audit.
+    // Resolver: `one.ie/web/src/lib/resolvers/media.ts`.
+    "media:list": receiver({
+        receiver: "media:list",
+        surfaces: { mcp: true, chat: true },
+        summary: "Every image and video a workspace owns, as typed rows — ONE R2 scan of `{workspace}/` filtered to the seven prefixes the reader will actually serve (media, chat, ads, products, pages, brand, courses), so generated chat images and ad creative are visible, not just hand-uploads. Carries `scanned` (how much of the page was not media), `truncated` (the budget that bit) and `nextCursor`. Each row's `url` is the one door that reads bytes.",
+        request: z.object({
+            workspace: z.string().optional().describe("Group slug. Omit for your own. Honoured only if you may read it."),
+            kind: z.enum(["image", "video"]).optional().describe("Omit for both. Filters the rows on this page; it does not change what is scanned."),
+            prefix: z.enum(["media", "chat", "ads", "products", "pages", "brand", "courses"]).optional()
+                .describe("Only assets under this top-level namespace. media = hand-uploads and library generations; chat = images/videos an agent made in a conversation; ads = creative; products/pages/courses/brand = assets filed beside the thing they illustrate."),
+            limit: z.number().int().min(1).max(1000).optional()
+                .describe("R2 objects to SCAN on this page BEFORE prefix/kind filtering — not a row count. Default 500, max 1000 (R2's own ceiling). A workspace whose bucket is mostly non-media can return few rows from a full scan; that is what `scanned` reports."),
+            cursor: z.string().optional().describe("The nextCursor from the previous page."),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            workspace: z.string().optional().describe("The workspace actually read — always the one you asked for, because a request you may not read is refused rather than downgraded."),
+            items: z.array(z.object({
+                key: z.string().describe("The R2 object key, `{workspace}/{prefix}/…` — the handle every other media receiver takes."),
+                url: z.string().describe("`/api/product-image/{workspace}/{path}` — THE reader. Range-forwarding, prefix-allowlisted, refuses SVG by stored contentType."),
+                kind: z.enum(["image", "video"]),
+                prefix: z.string().describe("Top-level namespace, no trailing slash."),
+                contentType: z.string(),
+                size: z.number().nullable().describe("Bytes, or null when R2 did not report it."),
+                uploaded: z.string().nullable().describe("ISO time, or null."),
+            })).optional(),
+            total: z.number().optional()
+                .describe("Media rows in THIS answer, after the kind/prefix filter. NOT a pre-paging count — an R2 scan cannot know one without walking every page. A FLOOR whenever `truncated` is present: say 'at least N'."),
+            scanned: z.number().optional()
+                .describe("Objects R2 listed on this page BEFORE filtering. `scanned` far above `total` means most of the page was not media — follow the cursor rather than concluding the workspace is empty."),
+            byPrefix: z.record(z.string(), z.number()).optional().describe("What each namespace contributed to THIS page — never a workspace total."),
+            prefixes: z.array(z.string()).optional().describe("Every prefix this door will ever return, so a caller can offer the filter without hardcoding the list."),
+            truncated: z.object({
+                rows: z.number().optional(),
+                scanned: z.number().optional(),
+                limit: z.number().optional().describe("The scan budget that bit."),
+                reason: z.string().optional(),
+            }).optional().describe("ABSENT IS NOT FALSE — a complete answer carries no such key. Present = R2 reported more objects under this workspace, `total` is a floor, and you must say so before planning on it."),
+            nextCursor: z.string().optional().describe("Present iff `truncated` is. Follow it or you have not seen the bucket."),
+            error: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", idempotent: true, reversible: true, settles: "none", auth: "member",
+        examples: [
+            { workspace: "one" },
+            { workspace: "one", kind: "video" },
+            { prefix: "ads", limit: 1000 },
+        ],
+    }),
+    // media:upload — bytes in, one key out, under `{workspace}/media/`.
+    //
+    // TWO SHAPES BECAUSE AN AGENT HAS NEITHER A FILE PICKER NOR A MULTIPART BODY. The
+    // HTTP door takes multipart and nothing else, so this is not a wrapper: the R2 write
+    // and the magic-byte sniff are reimplemented at the same 5 MiB cap.
+    //
+    // `url` IS A NEW OUTBOUND-FETCH SURFACE and is treated as one — the shared SSRF guard
+    // (shape + DNS, fail-closed) runs BEFORE the fetch, `redirect:'error'` so a public
+    // host cannot 302 the worker onto a metadata address, and the body is read against a
+    // hard byte budget rather than trusting `content-length`.
+    "media:upload": receiver({
+        receiver: "media:upload",
+        surfaces: { mcp: true, chat: true },
+        summary: "Put ONE raster image into a workspace's media library and get back the key and the url that serves it. Name exactly one source: `base64` (bytes you hold) or `url` (a public https address the server fetches under an SSRF guard, no redirects, 5 MiB hard cap). The stored content type comes from the MAGIC BYTES, never from what you declare — SVG is refused deliberately, and video is not accepted here.",
+        request: z.object({
+            workspace: z.string().optional().describe("Group slug. Omit for your own. Honoured only if you may read it."),
+            url: z.string().optional().describe("Public https address to fetch. Alternative to `base64`, never both. Private, loopback, link-local and CGNAT addresses are refused, as is any redirect."),
+            base64: z.string().optional().describe("The image bytes, base64. A `data:` prefix is accepted and stripped. Alternative to `url`, never both."),
+            filename: z.string().optional().describe("A LABEL for the key, not a path — separators are stripped and the extension always comes from the sniffed bytes, so `../` and a `.svg` suffix are both inert. Omit and the key is a bare uuid."),
+            contentType: z.string().optional().describe("A HINT only. The stored value is decided by the magic bytes, because the public reader serves the stored value verbatim under nosniff."),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            workspace: z.string().optional(),
+            key: z.string().optional().describe("`{workspace}/media/…` — the handle media:list returns."),
+            url: z.string().optional().describe("`/api/product-image/{workspace}/{path}` — THE reader."),
+            kind: z.literal("image").optional().describe("Always image. Video is a 5 MiB-cap and multipart-shape decision this door does not make; PUT /api/media/video-upload is the door that does."),
+            contentType: z.string().optional().describe("Sniffed, not declared."),
+            size: z.number().optional().describe("Bytes actually stored."),
+            error: z.string().optional().describe("Named: forbidden · too_large · unsupported_type · blocked_url · fetch_failed · storage_error. A refusal is never a downgrade to your own workspace."),
+        }),
+        effect: "ask", cost: "free", idempotent: false, reversible: false, settles: "none", auth: "member",
+        examples: [
+            { workspace: "one", url: "https://example.com/logo.png", filename: "logo" },
+            { base64: "iVBORw0KGgo…" },
+        ],
+    }),
+    // media:generate — one image from a prompt, straight into `{workspace}/media/`.
+    //
+    // DELIBERATELY NOT `surfaces.chat`. Chat already ships a curated `generate_image`
+    // (`channels/src/aitools.ts:376`): three providers, aspect/width/height, per-call
+    // billing and a spend-shaped approval gate — strictly more capable there, and it
+    // files under `{ws}/chat/`. Flagging this for chat too would offer a model TWO image
+    // generators with different prefixes and no way to choose between them, and the names
+    // differ (`generate_image` vs `media_generate`) so the curated-wins precedence in
+    // `channels/src/tools/from-registry.ts` would not suppress it. MCP has no such tool;
+    // that is where this one earns its place.
+    //
+    // `context` is a PROMPT QUALIFIER, not a key prefix. A library is THE prefix, not a
+    // context — the distinction `api/media/generate.ts`'s header argues out against the
+    // contextual storefront door. Nothing this receiver writes lands outside `media/`.
+    "media:generate": receiver({
+        receiver: "media:generate",
+        surfaces: { mcp: true },
+        summary: "Generate ONE image from a prompt and file it in the workspace's media library. Keyless — flux-1-schnell on the Cloudflare AI binding. Returns the key and the url that serves it. Unlike the storefront generator this takes no destination: it always writes `{workspace}/media/`, because a library is a prefix and not a context.",
+        request: z.object({
+            workspace: z.string().optional().describe("Group slug. Omit for your own. Honoured only if you may read it."),
+            prompt: z.string().min(1).describe("What to draw. Truncated at 2000 chars after `context` is folded in."),
+            context: z.string().optional().describe("Extra prompt material — brand, palette, subject. A QUALIFIER appended to the prompt, NOT a destination: it never changes the key prefix."),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            workspace: z.string().optional(),
+            key: z.string().optional().describe("`{workspace}/media/{uuid}.{ext}` — a uuid, never a timestamp: the url it names is served by a PUBLIC reader, so the name is the only thing standing between the object and a stranger."),
+            url: z.string().optional().describe("`/api/product-image/{workspace}/{path}` — THE reader."),
+            kind: z.literal("image").optional(),
+            contentType: z.string().optional().describe("Sniffed from the returned bytes — flux returns JPEG today and returned PNG when the storefront door was written."),
+            size: z.number().optional(),
+            error: z.string().optional().describe("Named: forbidden · not_configured (no AI or CONTENT binding) · generation_failed · storage_error."),
+        }),
+        effect: "ask", cost: "variable", idempotent: false, reversible: false, settles: "none", auth: "member",
+        examples: [{ workspace: "one", prompt: "a wide banner of a quiet harbour at dawn, muted palette" }],
+    }),
 };
 /**
  * RECIPES — the four agent journeys as typed, ordered receiver sequences (C6).