@cohortapp/agent-sdk 2.9.1 → 2.11.0

package/lib/org/protocol.mjs

@@ -76,6 +76,34 @@ export const FAMILIES = Object.freeze([
   // seat can PERSIST one it learned rather than re-deriving it every session.
   // The chain rows carry subject + domain + key only — never the value.
   "preference",
+  // GENESIS (2026-08): the founder's pre-commit workspace draft — the ten-stage
+  // run, its editable sections, and the conversational planner over them. The
+  // family exists so an agent reaches the SAME draft the founder's own form
+  // does; every method is a thin shell over the server action behind the
+  // button, never a second implementation of its gates.
+  //
+  // Its chain rows land in the DRAFTING org — the tenant the founder is signed
+  // into while they draft — and say only that a mutation happened, by whom, to
+  // which section. The content-level provenance is a different spine: the
+  // action's own `GenesisFieldEdit` rows, which `bufferGenesisAudit` replays
+  // into the NEW workspace's chain at commit. Both are true and neither
+  // replaces the other.
+  "genesis",
+  // ARCHITECTURE (2026-08): the four tier review decisions and the one whole-
+  // architecture approval that gate a Genesis commit. Split from `genesis`
+  // because these are REVIEW acts over a draft rather than edits to it, and
+  // because the same surface outlives the run — the Org › Architecture view
+  // reads this state for a workspace that has long since committed.
+  "architecture",
+  // RESOURCE (2026-08): the venture-deliverable catalogue — `OrgResource`, the
+  // workspace's own index of what it has to show for itself (site, deck,
+  // one-pager, memo, brand book, film, brand assets, repo). The table has been
+  // written by the portal and rendered by `/resources` since the three-tier
+  // workforce migration and was reachable from NO agent code path at all: zero
+  // hits across hq's methods/, mcp/ and llm-responder/ trees, so the venture's
+  // own colleagues could not list, add, correct, reorder or remove one of
+  // their own deliverables. This family is that surface.
+  "resource",
 ]);
 
 /**
@@ -292,7 +320,35 @@ export const METHODS = Object.freeze({
   //     the transactional lane. Still messaging.write scope: faking "X is
   //     composing" in a room is a social write a read-only key must not have. ---
   "messaging.typing": { family: "messaging", scope: "messaging.write", sideEffecting: false },
+  // --- messaging.synthesizeVoiceNote (2026-08): a colleague SPEAKS when asked
+  //     to. hq could already synthesise an agent's voice note, but only as a
+  //     reflex — it answered a HUMAN's spoken note in kind and nothing else —
+  //     so an agent asked in TEXT ("send me a voicenote with this update")
+  //     truthfully answered that it could not. This is the verb that makes the
+  //     ability reachable: it records the acting seat's OWN designed voice and
+  //     returns the READY fileId, which `messaging.send` then attaches like any
+  //     other file (same ACL, same outbound gate, same redacted audit row — no
+  //     parallel send path). Split in two deliberately: synthesis is a provider
+  //     round-trip with a 20s timeout and cannot ride hq's 5s transactional
+  //     lane, so this half is sideEffecting:false and self-audits its own
+  //     `files`/`media.voice.synthesized` chain row, exactly as `books.ask`
+  //     does for its model call. messaging.write scope, not read: putting words
+  //     in a named colleague's mouth is a social write of the first order. ---
+  "messaging.synthesizeVoiceNote": { family: "messaging", scope: "messaging.write", sideEffecting: false },
   "messaging.channels": { family: "messaging", scope: "messaging.read", sideEffecting: false },
+  // --- messaging.electResponder (2026-08): the SERVER-SIDE "should anyone answer,
+  //     and who?" election for a multi-participant channel. A fleet daemon calls it
+  //     with just {messageId, channelId}; hq assembles the RouteInput server-side
+  //     (roster/trigger/channel, org from the KEY) and runs the SAME response
+  //     planner the in-process responder uses, returning ONE verdict every seat
+  //     converges on — replacing each daemon's local, room-blind directed_at_agent
+  //     gate. messaging.read scope (every paired seat may ask; in DEFAULT_AGENT_
+  //     SCOPES). Declared sideEffecting:false though it appends: the verdict is a
+  //     write-once ledger event ("responder"/"responder.election", keyed on
+  //     messageId) and a CACHE HIT must return with ZERO appends — which the
+  //     side-effecting exactly-one-append contract forbids — so it self-audits its
+  //     own chain row like messaging.synthesizeVoiceNote and books.ask do. ---
+  "messaging.electResponder": { family: "messaging", scope: "messaging.read", sideEffecting: false },
   // --- calling (SP3): call lifecycle in the human app. NOT reserved-admin. ---
   "calling.start": { family: "calling", scope: "calling.write", sideEffecting: true },
   "calling.join": { family: "calling", scope: "calling.write", sideEffecting: true },
@@ -424,7 +480,12 @@ export const METHODS = Object.freeze({
   // --- file ---
   "file.pin": { family: "file", scope: "org.write", sideEffecting: true, idempotent: true },
   "file.unpin": { family: "file", scope: "org.write", sideEffecting: true },
-  "file.addComment": { family: "file", scope: "org.write", sideEffecting: true },
+  // idempotent: a COMMENT CREATE keyed on the caller's message id. Without
+  // the flag hq ignores `x-idempotency-key` entirely (dispatch.ts replays only
+  // for `def.idempotent === true`), so a daemon retry after a timeout-post-
+  // commit posts the same comment two or three times on the thread. Same
+  // reasoning as messaging.send, which has carried the flag from the start.
+  "file.addComment": { family: "file", scope: "org.write", sideEffecting: true, idempotent: true },
   "file.listComments": { family: "file", scope: "org.read", sideEffecting: false },
   "file.listPinned": { family: "file", scope: "org.read", sideEffecting: false },
   // --- memory ---
@@ -458,7 +519,7 @@ export const METHODS = Object.freeze({
   "notification.updatePreferences": { family: "notification", scope: "org.write", sideEffecting: true },
   "notification.getPreferences": { family: "notification", scope: "org.read", sideEffecting: false },
   // --- decision ---
-  "decision.comment": { family: "decision", scope: "decision.write", sideEffecting: true },
+  "decision.comment": { family: "decision", scope: "decision.write", sideEffecting: true, idempotent: true },
   "decision.sign": { family: "decision", scope: "decision.write", sideEffecting: true },
   "decision.reverse": { family: "decision", scope: "decision.write", sideEffecting: true },
   "decision.requestAdjustment": { family: "decision", scope: "decision.write", sideEffecting: true },
@@ -479,7 +540,7 @@ export const METHODS = Object.freeze({
   "board.updateTask": { family: "board", scope: "board.write", sideEffecting: true },
   "board.moveTask": { family: "board", scope: "board.write", sideEffecting: true },
   "board.assignTask": { family: "board", scope: "board.write", sideEffecting: true },
-  "board.addTaskComment": { family: "board", scope: "board.write", sideEffecting: true },
+  "board.addTaskComment": { family: "board", scope: "board.write", sideEffecting: true, idempotent: true },
   "board.addTaskAttachment": { family: "board", scope: "board.write", sideEffecting: true, idempotent: true },
   "board.updateTaskAttachment": { family: "board", scope: "board.write", sideEffecting: true },
   "board.removeTaskAttachment": { family: "board", scope: "board.write", sideEffecting: true },
@@ -933,6 +994,118 @@ export const METHODS = Object.freeze({
   // dispatcher cannot keep: the protocol advertises the method, callers get
   // through scope resolution, and the call 500s. Register it in the same change
   // that adds src/server/methods/escalation/answer.ts.
+  // --- GENESIS + ARCHITECTURE (2026-08): the pre-commit workspace draft and the
+  //     review gates over it. 1:1 with the founder's own form surface — the ask
+  //     was parity, so the bar is EQUAL power, never more.
+  //
+  //     SCOPES REUSE `org.read` / `org.write` rather than minting a genesis.*
+  //     pair. `org.write` is already defined as "EDITOR-equivalent: write
+  //     org-structural content (members, teams, personas, ... reporting lines,
+  //     chart layout)" and already sits in DEFAULT_AGENT_SCOPES under the
+  //     comment "agent UI-parity". A Genesis draft IS that content, one commit
+  //     earlier; a private scope would be a second name for a permission the
+  //     org already grants, and every operator who had reasoned about who may
+  //     edit their structure would have to reason about it twice.
+  //
+  //     WHY REGISTERING THEM AT ALL IS THE FIX. `scopeForMethod()` resolves an
+  //     UNKNOWN method to `admin`, and `admin` is in neither
+  //     HUMAN_DEFAULT_SCOPES nor DEFAULT_AGENT_SCOPES — so an undeclared method
+  //     is not merely undocumented, it is unreachable by every principal that
+  //     exists. That default is correct and it was firing: the handlers shipped
+  //     without descriptors and could not serve one request.
+  //
+  //     EVERY WRITE IS `sideEffecting:true` AND APPENDS ONE CHAIN EVENT, which
+  //     is not bookkeeping — dispatch REQUIRES exactly one append from a
+  //     side-effecting handler and throws INTERNAL on zero. The tempting escape
+  //     (declare a durable write `sideEffecting:false` so the requirement never
+  //     applies) would buy a green test with a lie the whole protocol reads:
+  //     no chain row, no idempotency replay, and `READS`-shaped callers free to
+  //     retry a mutation they were told was safe.
+  //
+  //     `idempotent:true` on the writes is opt-in at the caller (it engages only
+  //     when an idempotencyKey is sent) and it is the honest answer for this
+  //     family: every write already carries an `(attemptId, editSeq)` base and a
+  //     replay of a committed op is refused CONFLICT by the stale-base gate, so
+  //     without the cache a dropped response turns a SUCCEEDED edit into a
+  //     confusing conflict the caller cannot distinguish from a real race.
+  //
+  //     genesis.plan is a READ that spends tokens: it asks a model to turn an
+  //     instruction into ops and mutates nothing. Whether it costs money is not
+  //     what `sideEffecting` means. ---
+  "genesis.outline": { family: "genesis", scope: "org.read", sideEffecting: false },
+  "genesis.entity": { family: "genesis", scope: "org.read", sideEffecting: false },
+  "genesis.grid": { family: "genesis", scope: "org.read", sideEffecting: false },
+  "genesis.plan": { family: "genesis", scope: "org.read", sideEffecting: false },
+  "genesis.set": { family: "genesis", scope: "org.write", sideEffecting: true, idempotent: true },
+  "genesis.insert": { family: "genesis", scope: "org.write", sideEffecting: true, idempotent: true },
+  "genesis.remove": { family: "genesis", scope: "org.write", sideEffecting: true, idempotent: true },
+  "genesis.reorder": { family: "genesis", scope: "org.write", sideEffecting: true, idempotent: true },
+  "genesis.revert": { family: "genesis", scope: "org.write", sideEffecting: true, idempotent: true },
+  "genesis.applyPlan": { family: "genesis", scope: "org.write", sideEffecting: true, idempotent: true },
+  "architecture.status": { family: "architecture", scope: "org.read", sideEffecting: false },
+  "architecture.accept": { family: "architecture", scope: "org.write", sideEffecting: true, idempotent: true },
+  "architecture.approve": { family: "architecture", scope: "org.write", sideEffecting: true, idempotent: true },
+  // --- resource (2026-08): THE VENTURE-DELIVERABLE CATALOGUE. `OrgResource` is
+  //     the org-scoped index of a venture's own artifacts — one row per
+  //     deliverable, keyed `(orgId, slug)`, provisioned by the portal
+  //     (`source:"ftlab-portal"`), by Genesis, by the artifact ingest, or by
+  //     hand. Eight methods: list/get (reads) and create/update/delete/reorder
+  //     + attachFile/detachFile (writes).
+  //
+  //     SCOPES REUSE `org.read` / `org.write` rather than minting a
+  //     `resource.*` pair — the subagent/genesis precedent, and here it is also
+  //     the whole ACCESS-LEVEL point. A catalogue card is org-structural
+  //     authored content exactly like a persona, an SOP or an annotation, which
+  //     is what `org.write` already names; `org.read` is in hq's VIEWER tier
+  //     (src/server/auth/role-scopes.ts) and both are in DEFAULT_AGENT_SCOPES.
+  //     So on the day these descriptors land, every seat that exists can READ
+  //     its venture's catalogue and every EDITOR seat can maintain it, with no
+  //     key reminted and no tier table edited. A private scope pair would have
+  //     to be threaded through SCOPES, DEFAULT_AGENT_SCOPES and the VIEWER tier
+  //     before ONE existing credential could reach the family — which is the
+  //     same unreachable-on-arrival failure this declaration exists to end.
+  //     (`org.write` is deliberately NOT in hq's HUMAN_DEFAULT_SCOPES: the
+  //     human mobile bearer is intentionally narrower than an agent, and the
+  //     founder's own catalogue editing runs through the web app's server
+  //     actions under `requireOrgContext()`, never this bearer.)
+  //
+  //     THE FILES BRIDGE IS A POINTER, NOT A SECOND DRIVE. The artifact ingest
+  //     files a venture's artifacts as real `WorkspaceFile` rows and stamps
+  //     `OrgResource.fileId`. `resource.*` returns that id and the card's own
+  //     columns and NOTHING derived from the drive row — no bytes, no content,
+  //     no name, size, version or share list. That is a share boundary, not
+  //     tidiness: the catalogue is ORG-WIDE under `org.read` while the drive is
+  //     SEAT-scoped by `driveVisibilityWhere` (hq methods/files/list.ts), so a
+  //     `resource.*` that re-served file content would be a one-call bypass of
+  //     the share filter — the exact defect that handler's docblock warns
+  //     about. A card is a citation; `files.get` / `files.docRead` /
+  //     `files.exportRequest` are the retrieval path and already exist.
+  //     `resource.attachFile` is the ONE place the families touch, and it
+  //     resolves the file through the drive's own `getFileOrThrow` (org pin +
+  //     `canSeeDriveFile`, NOT_FOUND either way) so it can neither cite another
+  //     tenant's file nor act as an existence oracle for one this seat cannot
+  //     see. `files.uploadRegister`'s `.strict()` schema is untouched.
+  //
+  //     TENANCY, twice over. Slug-addressed rows go through the compound unique
+  //     `orgId_slug` — the tenant is PART OF THE KEY, so another org's card is
+  //     unaddressable. Id-addressed rows go through `ctx.scopeWhere({ id })` on
+  //     findFirst/updateMany/deleteMany, never `findUnique({ where: { id } })`,
+  //     which would cross tenants.
+  //
+  //     Writes are `sideEffecting:true` and append exactly ONE chain event each
+  //     under `family:"resource"`; `idempotent:true` is opt-in at the caller.
+  //     `resource.delete` removes the CARD only — the `WorkspaceFile` keeps its
+  //     own 30-day soft-delete lane, which is why `fileId` is a plain String
+  //     and not a relation (schema.prisma: a cascade would lose the record that
+  //     the venture ever had a deck). ---
+  "resource.list": { family: "resource", scope: "org.read", sideEffecting: false },
+  "resource.get": { family: "resource", scope: "org.read", sideEffecting: false },
+  "resource.create": { family: "resource", scope: "org.write", sideEffecting: true, idempotent: true },
+  "resource.update": { family: "resource", scope: "org.write", sideEffecting: true, idempotent: true },
+  "resource.delete": { family: "resource", scope: "org.write", sideEffecting: true, idempotent: true },
+  "resource.reorder": { family: "resource", scope: "org.write", sideEffecting: true, idempotent: true },
+  "resource.attachFile": { family: "resource", scope: "org.write", sideEffecting: true, idempotent: true },
+  "resource.detachFile": { family: "resource", scope: "org.write", sideEffecting: true, idempotent: true },
 });
 
 /**

package/lib/org/protocol.test.mjs

@@ -134,7 +134,16 @@ test("protocol: frozen family + method counts (additive evolution guard)", () =>
   // The 2026-08 protocol-convergence pass adds 4: subagent (the org-scoped
   // sub-agent registry), agent (the agent.wait control lane), mandate (the
   // MANDATE spine) and preference (member-scoped preferences) → 51.
-  assert.equal(FAMILIES.length, 51, "family count");
+  // The 2026-08 Genesis agent-surface pass adds 2: genesis (the founder's
+  // pre-commit workspace draft — the ten-stage run and its editable sections)
+  // and architecture (the four tier review decisions and the one whole-
+  // architecture approval, which outlive the run as the Org › Architecture
+  // view) → 53.
+  // The 2026-08 venture-deliverable pass adds 1: resource (the OrgResource
+  // catalogue — a venture's own deliverables). The table predates every agent
+  // plane and was reachable from none of them, so a venture's colleagues could
+  // not list, add, correct, reorder or remove one of their own artifacts → 54.
+  assert.equal(FAMILIES.length, 54, "family count");
   // 357 = the mesh-protocol + agent UI-parity + calling + branding + email
   // methods, plus the Live Integrations surface: integration.toolsetVersion +
   // integration.listAgentTools (SP1) and integration.invokeTool (SP5, execute a
@@ -176,7 +185,27 @@ test("protocol: frozen family + method counts (additive evolution guard)", () =>
   // `server/work/ledger.ts` directly, the daemon reaches it over this wire, so
   // the threshold and the idempotency cannot fork → 461.
   // the descriptors; the checksum (read at runtime) is the primary drift guard.
-  assert.equal(Object.keys(METHODS).length, 461, "method count");
+  // The 2026-08 Genesis agent-surface pass adds 13, the 1:1 programmatic
+  // parity for the founder's own Generate surface: genesis 10 (outline/entity/
+  // grid/plan reads + set/insert/remove/reorder/revert/applyPlan writes) and
+  // architecture 3 (status read + accept/approve review gates). The handlers
+  // had shipped WITHOUT descriptors, which made all 13 unreachable — dispatch
+  // rejects unknown methods and scopeForMethod resolves them to `admin`, which
+  // no principal holds → 474.
+  // The 2026-08 voice-capability pass adds 1: messaging.synthesizeVoiceNote —
+  // hq could always synthesise a colleague's voice note but only as a REFLEX
+  // (answering a human's spoken note in kind), so an agent asked in text for a
+  // voice note truthfully answered that it could not. This is the verb that
+  // makes it askable on every plane; the POST stays plain messaging.send → 475.
+  // The 2026-08 venture-deliverable pass adds 8: resource.list/get (reads) and
+  // resource.create/update/delete/reorder/attachFile/detachFile (writes). Both
+  // reads ride `org.read` and every write `org.write`, so the family is
+  // reachable by the VIEWER and EDITOR tiers that already exist rather than by
+  // a scope nobody has been minted. attachFile/detachFile are the ONLY bridge
+  // to `files.*`: a card carries a fileId POINTER and the drive keeps its own
+  // seat-scoped read surface → 483. Then +1: messaging.electResponder (the
+  // fleet's server-side respond-election) → 484.
+  assert.equal(Object.keys(METHODS).length, 484, "method count");
 });
 
 test("protocol SP3: messaging + calling families/methods/scopes", async () => {

package/lib/org/resource-tools.mjs

@@ -0,0 +1,317 @@
+/**
+ * lib/org/resource-tools.mjs — the `resource_*` desk tools, GENERATED.
+ *
+ * THE FAMILY. `OrgResource` is a venture's own deliverable catalogue: one
+ * org-scoped card per artifact (deck, one-pager, film, site, data room…),
+ * keyed `(orgId, slug)`, written by the FTLAB portal, by Genesis, by the
+ * artifact ingest, or by hand, and rendered to humans at `/resources`. Until
+ * this wave it was reachable from NO agent code path in either plane — a
+ * venture's own AI colleagues could not list, add, correct, reorder or remove
+ * a single one of the venture's deliverables. Eight protocol methods now
+ * exist; these are their curated tools.
+ *
+ * WHY THIS FILE IS A GENERATOR AND NOT A TABLE. hq's responder desks expose
+ * 239 ops across 11 families; maestro's curated table exposed 69 desk tools
+ * across 9 — files 29 vs 7, crm 44 vs 8. That divergence has one cause: the two
+ * tool tables are hand-written twice, so they drift the moment one side moves
+ * and nobody hand-copies the delta. This family refuses to be able to drift the
+ * same way. The tool NAME, the ACCESS TIER, the BINDING and the DESK TAG are
+ * all DERIVED from the vendored protocol declaration — the same declaration
+ * hq's handlers are registered from — and the only thing a human writes here is
+ * PRESENTATION: the title, the description, and the input schema. Add a ninth
+ * `resource.*` method to `lib/org/protocol.mjs` and sync it, and a ninth tool
+ * appears on the next import with no edit to this file; `resource-tools.test.mjs`
+ * then goes red until someone gives it a real description. The capability is
+ * never dark and the gap is never quiet — which is the whole thesis of the
+ * wave that shipped the family.
+ *
+ * ACCESS. `expectedAccessFor` derives the tier from the method's protocol
+ * SCOPE, never from a literal typed here: `resource.list` / `resource.get` ride
+ * `org.read` → `access:"read"` (every tier's lookup set, including
+ * least-privilege "default"); the six writes ride `org.write` →
+ * `access:"write"` (ceo + leadership). NONE is `access:"admin"` — that is the
+ * CEO-only escape-hatch tier, and a venture's colleagues are default- and
+ * leadership-tier agents, so parking their own deliverables there would ship
+ * this family exactly as dark as it was before. See lib/org/tool-access.mjs.
+ *
+ * NO `outbound` FLAG ANYWHERE IN THIS BLOCK. A card is org-internal metadata;
+ * nothing here puts free text a human reads onto an outbound channel, and the
+ * send-gate lane stays exactly messaging_send / email_send / email_draft_send /
+ * org_call_share_step.
+ *
+ * THE FILES BRIDGE IS A POINTER, NOT A SECOND DRIVE. A card returns its own
+ * columns plus a `fileId`, and NOTHING derived from the `WorkspaceFile` — no
+ * bytes, name, mime, size, version or share list. The catalogue is org-wide
+ * under `org.read` while the drive is seat-scoped by `driveVisibilityWhere`, so
+ * a resource tool that re-served file content would be a one-call bypass of the
+ * share filter. Bytes are read with `files_get` / `files_doc_read` /
+ * `org_rpc files.exportRequest`. `resource_attach_file` is the one seam, and hq
+ * resolves the id through the drive's own `getFileOrThrow` (org pin +
+ * `canSeeDriveFile`, NOT_FOUND either way), so it can neither cite another
+ * tenant's file nor act as an existence oracle for one this seat cannot see.
+ *
+ * Node builtins only. ESM.
+ *
+ * @module lib/org/resource-tools
+ */
+
+"use strict";
+
+import { METHODS } from "./protocol.mjs";
+import { expectedAccessFor } from "./tool-access.mjs";
+
+/** The protocol family these tools are generated from. */
+export const RESOURCE_FAMILY = "resource";
+
+/** The desk tag every generated entry carries (gates on DESK_PROBES.resource). */
+export const RESOURCE_DESK = "resource";
+
+// Schema helpers — same shapes tool-surface.mjs builds its entries with.
+const S = (properties, required = []) => ({ type: "object", properties, required });
+const str = (description) => ({ type: "string", description });
+const num = (description) => ({ type: "number", description });
+const bool = (description) => ({ type: "boolean", description });
+const obj = (description) => ({ type: "object", description });
+const arr = (items, description) => ({ type: "array", items, description });
+
+/**
+ * PRESENTATION ONLY, keyed by protocol method. No `name`, no `access`, no
+ * `binding`, no `desk` — those four are derived, and a literal here would be
+ * the hand-copy this file exists to prevent.
+ *
+ * Each description carries what the schema cannot: the semantics an agent gets
+ * wrong on the first try (total-vs-partial reorder, shallow-merge metadata,
+ * what survives a delete) and the refusals it will otherwise learn by
+ * BAD_REQUEST.
+ * @type {Readonly<Record<string, {title: string, description: string, input_schema: object}>>}
+ */
+export const RESOURCE_PRESENTATION = Object.freeze({
+  "resource.list": {
+    title: "List venture deliverables",
+    description:
+      "This venture's deliverable catalogue (resource.list) — the same cards, in the same " +
+      "order, that humans see at /resources: sortOrder asc, then createdAt asc. Each card is " +
+      "{id, slug, kind, title, description, url, previewImageUrl, source, fileId, metadata, " +
+      "sortOrder, createdAt, updatedAt}. `source` says who put it there — \"ftlab-portal\" " +
+      "(pushed by the venture portal and re-upserted on every push), \"genesis\", or " +
+      "\"manual\" (created through this desk). `fileId` non-null means the artifact is also " +
+      "filed in the workspace drive: read it with files_get / files_doc_read, NOT from here — " +
+      "this desk returns the card's own columns and nothing about the file itself. Filters: " +
+      "`kind`, `source`, free-text `q` (matches title OR description, case-insensitive), " +
+      "`hasFile` (true = only drive-backed cards, false = only link-only cards, omit = both). " +
+      "No cursor — raise `limit` (max 200) if the catalogue is long.",
+    input_schema: S({
+      kind: str("Filter by card kind, e.g. \"deck\", \"one-pager\", \"film\", \"site\" (≤64 chars)."),
+      source: str("Filter by provenance: \"ftlab-portal\" | \"genesis\" | \"manual\" (≤64 chars)."),
+      q: str("Free text; matches title OR description, case-insensitive (≤200 chars)."),
+      hasFile: bool("true = only cards with a drive fileId; false = only link-only cards; omit = both."),
+      limit: num("Max cards 1..200 (default 100)."),
+    }),
+  },
+  "resource.get": {
+    title: "Get one deliverable",
+    description:
+      "One catalogue card by `slug` (the stable org-scoped natural key the portal, the " +
+      "/resources page and every tool here use) or by `resourceId` — pass EXACTLY ONE; " +
+      "neither or both is a BAD_REQUEST. Returns the card's own columns only. A card in " +
+      "another workspace answers NOT_FOUND identically to one that never existed, so this is " +
+      "not an existence oracle — do not read NOT_FOUND as \"it belongs to someone else\".",
+    input_schema: S({
+      slug: str("Card slug, e.g. \"deck-seed-round\" (preferred — stable across re-pushes)."),
+      resourceId: str("Card id (cuid). Alternative to slug; never pass both."),
+    }),
+  },
+  "resource.create": {
+    title: "Add a deliverable",
+    description:
+      "Add a card to the venture's catalogue (resource.create). `url` OR `fileId` must be " +
+      "present — a card pointing nowhere is the exact state this desk exists to end. Omit " +
+      "`slug` and the server derives one from kind + title (and suffixes -2, -3 on collision) " +
+      "using the SAME transform the portal uses, so a portal push and an agent create agree. " +
+      "`source` is NOT an input: the server stamps \"manual\", so an agent cannot relabel its " +
+      "own card as portal-provenance. This is NOT an upsert — an existing slug answers " +
+      "CONFLICT rather than overwriting a portal row someone guessed the slug of; correct an " +
+      "existing card with resource_update. `metadata` is free JSON (object only, ≤16KB) for " +
+      "provenance such as sha256/runId/documentVersion — NEVER put a credential in it; only " +
+      "its KEY NAMES ride the event chain.",
+    input_schema: S(
+      {
+        kind: str("Card kind, e.g. \"deck\" | \"one-pager\" | \"film\" | \"site\" (≤64 chars)."),
+        title: str("Human title as it appears at /resources (≤200 chars)."),
+        url: str("Public https URL (≤2048) or an in-app path like \"/files/abc123\". Required unless fileId is given."),
+        fileId: str("Workspace drive file id to cite. Required unless url is given; must be a file this seat can already see."),
+        slug: str("Optional explicit slug: lowercase a-z0-9 words joined by single hyphens, ≤64. Omit to let the server derive it."),
+        description: str("One or two sentences a human reads under the title (≤2000 chars)."),
+        previewImageUrl: str("Thumbnail URL (≤2048)."),
+        metadata: obj("Free-JSON provenance object, ≤16KB serialized. No secrets."),
+        sortOrder: num("Position 0..10000 (ties break on createdAt asc). Omit to append."),
+      },
+      ["kind", "title"],
+    ),
+  },
+  "resource.update": {
+    title: "Correct a deliverable",
+    description:
+      "Edit an existing card (resource.update), addressed by EXACTLY ONE of `slug` or " +
+      "`resourceId`. At least one mutable field is required, else BAD_REQUEST. `metadata` is a " +
+      "SHALLOW MERGE over what is already there — {...prior, ...patch} — and a key you pass as " +
+      "null is DELETED. It is deliberately not a whole-object replace: the artifact ingest " +
+      "writes sha256/runId/documentVersion/byteState/driveUrl into metadata, and a replace " +
+      "would let a one-field edit destroy the delivery provenance. Three fields are NOT " +
+      "editable here, each on purpose: `slug` (it is the ref AND the portal's re-sync key — " +
+      "renaming it would orphan the upsert and duplicate the card on the next push), `fileId` " +
+      "(re-pointing a card at a different drive row is a separately-audited act — use " +
+      "resource_attach_file), and `source` (provenance is server-owned).",
+    input_schema: S({
+      slug: str("Card slug to edit (preferred). Never pass both slug and resourceId."),
+      resourceId: str("Card id (cuid). Alternative to slug."),
+      kind: str("New kind (≤64 chars)."),
+      title: str("New title (≤200 chars)."),
+      description: str("New description (≤2000 chars); null clears it."),
+      url: str("New https URL (≤2048) or in-app path."),
+      previewImageUrl: str("New thumbnail URL (≤2048); null clears it."),
+      metadata: obj("Metadata PATCH — shallow-merged; a key set to null is removed. ≤16KB serialized."),
+      sortOrder: num("New position 0..10000. This is the PARTIAL nudge; resource_reorder is the total re-sort."),
+    }),
+  },
+  "resource.delete": {
+    title: "Remove a deliverable",
+    description:
+      "Remove a card from the catalogue (resource.delete), addressed by EXACTLY ONE of `slug` " +
+      "or `resourceId`. THE CARD ONLY: the WorkspaceFile it cited is NOT deleted and not even " +
+      "soft-deleted — the drive owns its own 30-day recovery lane — which is why the reply " +
+      "carries `fileRetained: true`. Relay that truth; do not tell a human the file is gone. " +
+      "The card's Cortex SOURCES entry goes with it, so a removed deliverable stops being " +
+      "discoverable. CAVEAT worth saying out loud: deleting a card whose `source` is " +
+      "\"ftlab-portal\" is not permanent — the next portal push re-upserts it on its natural " +
+      "key. If a portal card is wrong, fix it upstream or correct it with resource_update.",
+    input_schema: S({
+      slug: str("Card slug to remove (preferred). Never pass both slug and resourceId."),
+      resourceId: str("Card id (cuid). Alternative to slug."),
+    }),
+  },
+  "resource.reorder": {
+    title: "Re-sort the catalogue",
+    description:
+      "Set the whole catalogue's order (resource.reorder) — this is what changes what a human " +
+      "sees FIRST at /resources. TOTAL, not partial: `slugs` must name EVERY card in this " +
+      "workspace exactly once, and each gets sortOrder = its index. Anything else is a " +
+      "CONFLICT that names the missing, unknown and duplicated slugs back to you — which is " +
+      "the feature, not the friction: a card created by the portal while you were composing " +
+      "the list surfaces as a refusal instead of silently scrambling the order. So list first " +
+      "(resource_list), reorder from THAT list, and re-list if it refuses. To nudge one card " +
+      "without touching the rest, use resource_update { sortOrder } instead. Returns the full " +
+      "catalogue in its new order — no re-list needed.",
+    input_schema: S(
+      {
+        slugs: arr(
+          { type: "string" },
+          "Every slug in the workspace, exactly once, in the order you want (1..500).",
+        ),
+      },
+      ["slugs"],
+    ),
+  },
+  "resource.attachFile": {
+    title: "Cite a drive file on a card",
+    description:
+      "Point a catalogue card at a workspace drive file (resource.attachFile), addressed by " +
+      "EXACTLY ONE of `slug` or `resourceId`. This is a LINK write, not a byte write: it sets " +
+      "fileId and merges {driveUrl:\"/files/<fileId>\"} into metadata. hq resolves the file " +
+      "through the drive's own permission check, so you may only cite a file this seat can " +
+      "already see, and a file you cannot see answers NOT_FOUND exactly like one that does not " +
+      "exist. `setUrl` defaults to FALSE and should usually stay there: a deck, one-pager or " +
+      "film keeps its public URL because the venture's own site and outreach link that object " +
+      "— pass setUrl:true only when the card's destination really should become the in-app " +
+      "file. Attaching does not copy, move or re-share the file.",
+    input_schema: S(
+      {
+        fileId: str("Workspace drive file id to cite."),
+        slug: str("Card slug (preferred). Never pass both slug and resourceId."),
+        resourceId: str("Card id (cuid). Alternative to slug."),
+        setUrl: bool("Also rewrite the card's url to /files/<fileId>. Default false — an external URL is usually load-bearing."),
+      },
+      ["fileId"],
+    ),
+  },
+  "resource.detachFile": {
+    title: "Stop citing a drive file",
+    description:
+      "Clear a card's drive citation (resource.detachFile), addressed by EXACTLY ONE of `slug` " +
+      "or `resourceId`: fileId → null and the `driveUrl` key drops out of metadata. The " +
+      "WorkspaceFile is untouched. The card's `url` is left exactly as it was UNLESS you pass " +
+      "a replacement `url`. One guard: if the card's only destination IS the file being " +
+      "detached (its url is /files/<fileId>), `url` is REQUIRED and the call answers CONFLICT " +
+      "without it — otherwise this verb would manufacture the dead card the whole family " +
+      "exists to prevent.",
+    input_schema: S({
+      slug: str("Card slug (preferred). Never pass both slug and resourceId."),
+      resourceId: str("Card id (cuid). Alternative to slug."),
+      url: str("Replacement destination — required when the card's url is the /files/<fileId> being detached."),
+    }),
+  },
+});
+
+/**
+ * `resource.attachFile` → `resource_attach_file`. Dots become underscores and
+ * camelCase humps split, so the tool name is a pure function of the protocol
+ * name and cannot be typed differently from it.
+ * @param {string} method
+ * @returns {string}
+ */
+export function toolNameForMethod(method) {
+  return String(method)
+    .replace(/\./g, "_")
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .toLowerCase();
+}
+
+/**
+ * Build the curated `resource_*` entries from the VENDORED protocol table.
+ *
+ * Order follows the protocol declaration, so the tool block reads in the order
+ * the family was designed in. Returns `[]` when the vendored protocol carries
+ * no `resource` family at all — an older protocol degrades cleanly, exactly
+ * like the desk gates.
+ *
+ * A family method with no presentation entry still gets a tool, built from the
+ * descriptor: an under-described capability is a documentation bug, but a
+ * MISSING one is the failure this whole wave was called to fix, so drift
+ * surfaces as a red test (resource-tools.test.mjs asserts the presentation
+ * table covers the family exactly) and never as a dark verb.
+ *
+ * @param {Record<string, {family?:string, scope?:string, sideEffecting?:boolean}>} [methods]
+ * @returns {Array<object>}
+ */
+export function buildResourceTools(methods = METHODS) {
+  const out = [];
+  for (const [method, def] of Object.entries(methods || {})) {
+    if (!def || def.family !== RESOURCE_FAMILY) continue;
+    // Scope is the authority (it is what hq gates on). The `??` arm only fires
+    // for a method the REAL vendored table does not carry — i.e. a synthetic
+    // table under test — and mirrors sideEffecting so such a row still lands on
+    // the correct side of the read/write line rather than defaulting open.
+    const access = expectedAccessFor(method) ?? (def.sideEffecting ? "write" : "read");
+    const p = RESOURCE_PRESENTATION[method];
+    out.push({
+      name: toolNameForMethod(method),
+      title: p ? p.title : method,
+      description: p
+        ? p.description
+        : `Undocumented ${RESOURCE_FAMILY} verb (${method}) — generated from the protocol ` +
+          `declaration so the capability is reachable; add a presentation entry in ` +
+          `lib/org/resource-tools.mjs.`,
+      input_schema: p ? p.input_schema : S({}),
+      access,
+      desk: RESOURCE_DESK,
+      binding: { kind: "rpc", method },
+    });
+  }
+  return out;
+}
+
+/**
+ * The generated block, spliced into `ORG_TOOLS` by lib/org/tool-surface.mjs.
+ * @type {ReadonlyArray<object>}
+ */
+export const RESOURCE_TOOLS = Object.freeze(buildResourceTools());