permdock 0.3.1 → 0.5.0

package/schemas/support-session-v1.json

@@ -0,0 +1,111 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://permdock.com/schemas/support-session-v1.json",
+  "title": "PermDock support session",
+  "description": "The claims of a vnd.permdock.support-session+jwt, wire format v1: sub is the viewed principal, act the support actor, jti the session id. exp is after iat, by at most one day.",
+  "type": "object",
+  "required": [
+    "v",
+    "iss",
+    "sub",
+    "aud",
+    "jti",
+    "iat",
+    "exp",
+    "act",
+    "tenant",
+    "reason",
+    "permissions"
+  ],
+  "properties": {
+    "v": {
+      "const": 1
+    },
+    "iss": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "sub": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "aud": {
+      "anyOf": [
+        {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 256
+          },
+          "minItems": 1
+        }
+      ]
+    },
+    "jti": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "iat": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "exp": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "act": {
+      "type": "object",
+      "required": ["sub", "kind"],
+      "additionalProperties": false,
+      "properties": {
+        "sub": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "kind": {
+          "const": "support"
+        }
+      }
+    },
+    "tenant": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "reason": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1000
+    },
+    "permissions": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 256
+      },
+      "minItems": 1,
+      "maxItems": 64
+    },
+    "approved_by": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "reference": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256
+    }
+  }
+}

package/skills/permdock/SKILL.md

@@ -32,26 +32,30 @@ PermDock is typed permissions for TypeScript apps, APIs, databases and AI agents
 
 1. **Pick the skill.** Install the one the task needs with `npx skills add ScaleDockHQ/PermDock --skill <name>` (or all of them with `npx skills add ScaleDockHQ/PermDock`, or `pnpm exec permdock skills install` to match the installed package version):
 
-   | Task                                                    | Skill                  |
-   | ------------------------------------------------------- | ---------------------- |
-   | Add PermDock, first guard, limits, plans, CLI checks    | `permdock-wire`        |
-   | Review an app or a pull request                         | `permdock-audit`       |
-   | Agent tool calls, actors, delegation, A2A, WebMCP       | `permdock-agents`      |
-   | Human approval, approvers, quorum, resume               | `permdock-approvals`   |
-   | Named scopes, memberships, ownership, custom roles      | `permdock-tenancy`     |
-   | ORM queries, generated RLS, relationship graphs, parity | `permdock-data`        |
-   | Access tokens, API keys, service accounts, share links  | `permdock-credentials` |
+   | Task                                                                  | Skill                  |
+   | --------------------------------------------------------------------- | ---------------------- |
+   | Add PermDock, first guard, limits, plans, CLI checks                  | `permdock-wire`        |
+   | Review an app or a pull request                                       | `permdock-audit`       |
+   | Agent tool calls, actors, delegation, A2A, WebMCP                     | `permdock-agents`      |
+   | Automations, workflow runs, chat bots and chat commands               | `permdock-agents`      |
+   | Human approval, approvers, quorum, resume, delegation, access reviews | `permdock-approvals`   |
+   | Approval prompts and notices by email or chat (delivery)              | `permdock-approvals`   |
+   | Named scopes, memberships, ownership, custom roles                    | `permdock-tenancy`     |
+   | ORM queries, generated RLS, relationship graphs, parity               | `permdock-data`        |
+   | Access tokens, API keys, service accounts, feed keys, share links     | `permdock-credentials` |
 
    ✓ The skill for the task is loaded, and `permdock-wire` has run first if the app has no factory file.
 
-2. **Look identifiers up, never guess them.** Read the owning page through the docs MCP (`https://permdock.com/mcp`, tools `search`, `list_pages` and `get_page`), or append `.md` to any `https://permdock.com/docs/...` URL. Every public name follows the [naming convention](https://permdock.com/docs/getting-started/naming).
+2. **Look identifiers up, never guess them.** Read the owning page through the docs MCP (`https://permdock.com/docs/mcp`, tools `search`, `list_pages` and `get_page`), or append `.md` to any `https://permdock.com/docs/...` URL. Every public name follows the [naming convention](https://permdock.com/docs/getting-started/naming).
    ✓ Each identifier written into the app appears on a docs page or in `node_modules/permdock`.
 3. **Read a decision.** `decide()` returns `{ outcome, denials: [{ reason, ... }], alternatives }`. `reason` is one of the closed list on [decisions](https://permdock.com/docs/concepts/decisions); `alternatives` are permissions on the same resource the subject does hold. HTTP adapters answer RFC 9457 Problem Details ([errors](https://permdock.com/docs/concepts/errors)); for the format, defer to the `problem-details` spec skill (`npx skills add ScaleDockHQ/scaledock-skills --skill problem-details`).
    ✓ Each denial the user asked about is named by its reason.
 4. **Explain an unexpected denial.** Run `permdock.explain(permission, data)` in a test or a script. `trace.denies[0]` is the deny that won (give denies a `name` so it reads as a rule), `trace.allows` the allows it overrode, `trace.skipped` the grants passed over and why ([explain](https://permdock.com/docs/concepts/decisions#explain)). The trace never reaches the decision log. To preview a plan before acting, `simulate([[permission, data], ...])` returns every decision.
    ✓ The cause is a named grant, condition or missing input, not a guess.
-5. **Check the project.** Run `pnpm exec permdock doctor` (`--json` for machine output). Each finding has a stable `PD0xx` code and a one-line fix ([doctor](https://permdock.com/docs/cli/doctor)); the topic skills name the codes for their area.
+5. **Check the project.** Run `pnpm exec permdock doctor`. Each finding has a stable `PD0xx` code and a one-line fix ([doctor](https://permdock.com/docs/cli/doctor)); the topic skills name the codes for their area. When an agent runs it, every `permdock` command prints one JSON result: the report is in `data`. Exit `3` means the command needs input, a login or the person's consent: show the person `error.detail`, and after they agree run the command `next` gives, with its `--confirm` token. Never add `--confirm` or `--force` on your own ([agent mode](https://permdock.com/docs/cli/agent-mode)).
    ✓ `permdock doctor` reports no error.
+6. **Upgrade across a rename release.** After raising `permdock` to 0.5, run `pnpm exec permdock codemod 0.5 --dry-run`, then without `--dry-run`. It renames imported identifiers and lists each call site whose shape changed, and each option or method key to edit by hand, as `file:line:column` ([codemod](https://permdock.com/docs/cli/codemod)). Work through that list, then run `tsc` and the step 5 check.
+   ✓ The codemod's second run reports no changes, and every follow-up it listed is edited.
 
 ## Verify before done
 
@@ -63,4 +67,4 @@ PermDock is typed permissions for TypeScript apps, APIs, databases and AI agents
 ## Reference index
 
 - Skills: `permdock-wire`, `permdock-audit`, `permdock-agents`, `permdock-approvals`, `permdock-tenancy`, `permdock-data`, `permdock-credentials`, all from `npx skills add ScaleDockHQ/PermDock --skill <name>`.
-- Docs: [for AI agents](https://permdock.com/docs/for-ai-agents), [naming](https://permdock.com/docs/getting-started/naming), [policies](https://permdock.com/docs/concepts/policies), [decisions](https://permdock.com/docs/concepts/decisions), [threat model](https://permdock.com/docs/security/threat-model), [doctor](https://permdock.com/docs/cli/doctor), `https://permdock.com/llms.txt`.
+- Docs: [for AI agents](https://permdock.com/docs/for-ai-agents), [naming](https://permdock.com/docs/getting-started/naming), [policies](https://permdock.com/docs/concepts/policies), [decisions](https://permdock.com/docs/concepts/decisions), [threat model](https://permdock.com/docs/security/threat-model), [doctor](https://permdock.com/docs/cli/doctor), [codemod](https://permdock.com/docs/cli/codemod), `https://permdock.com/llms.txt`.

package/skills/permdock-agents/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: permdock-agents
-description: Guards AI agent tool calls with PermDock subjects, actors and delegation. Use when wiring tool maps in permdock/ai-sdk, permdock/claude-agent, permdock/openai, permdock/eve or permdock/mcp, separating the user (principal) from the agent (actor), declaring a delegation option or policy delegations, publishing an A2A Agent Card with permdock/a2a, registering WebMCP tools with permdock/webmcp, verifying Web Bot Auth signers as actors, or when agent calls are denied with no-delegation or not-delegated.
+description: Guards AI agent tool calls, automations and chat commands with PermDock operations, subjects, actors and delegation. Use when declaring defineOperations, wiring operations in permdock/agent, permdock/ai-sdk, permdock/claude-agent, permdock/openai, permdock/eve or permdock/mcp, gating models or filtering tool results, running published automations with permdock/workflow or permdock/workflow-sdk, protecting chat commands and approval buttons with permdock/chat or permdock/chat-sdk, separating the user (principal) from the agent (actor), declaring a delegation option or policy delegations, publishing an A2A Agent Card with permdock/a2a, registering WebMCP tools with permdock/webmcp, verifying Web Bot Auth signers as actors, or when agent calls are denied with no-delegation or not-delegated.
 license: MIT
 metadata:
   author: ScaleDockHQ
@@ -10,33 +10,40 @@ metadata:
 
 # PermDock agents
 
-An agent call has a principal (the user whose grants are evaluated), an actor (the agent making the call) and a delegation (what the user handed over). The decision is the principal's grants intersected with the delegation ([delegation](https://permdock.com/docs/security/delegation)). Set up `permissions.ts`, `policy.ts` and the factory first with the `permdock-wire` skill (`npx skills add ScaleDockHQ/PermDock --skill permdock-wire`).
+An agent call has a principal (the user whose grants are evaluated), an actor (the agent making the call) and a delegation (what the user handed over). The decision is the principal's grants intersected with the delegation ([delegation](https://permdock.com/docs/security/delegation)). Agent tools, automations and chat commands read one table from `defineOperations` ([operations](https://permdock.com/docs/concepts/operations)). Set up `permissions.ts`, `policy.ts` and the factory first with the `permdock-wire` skill (`npx skills add ScaleDockHQ/PermDock --skill permdock-wire`).
 
 ## Inputs (find out, or ask before starting)
 
-- Runtimes in use: AI SDK, Claude Agent SDK, OpenAI Agents SDK, Eve, an MCP server, an A2A agent, WebMCP tools in a web page, signed bot traffic over HTTP.
-- Where the principal comes from: the host session, a verified token, the runtime's session (Eve).
+- Runtimes in use: AI SDK, Claude Agent SDK, OpenAI Agents SDK, Eve, another agent runtime, an MCP server, an A2A agent, WebMCP tools in a web page, signed bot traffic over HTTP.
+- Automations: who publishes them, whether they run as the publisher or a service principal, and the runner (Workflow SDK, Trigger.dev, Inngest, Temporal, Vercel Queues, pgmq).
+- Chat bots: the platform, the workspace id, and where the app stores the link from a chat user id to a principal.
+- Where the principal comes from: the host session, a verified token, the runtime's session (Eve), a run ticket, a linked chat author.
 - Where the actor id comes from: runtime context, `authInfo.clientId`, an Agent Card, a request signature.
 - What the user delegates, per call (scopes, `authorizationDetails`, GNAP `access`) or as standing policy ("members let the Eve agent read and update posts").
-- Which tools are destructive or move money.
+- Which operations are destructive or move money, and which models each plan may use.
 
 ## Invariants
 
 1. Subject and actor come from the host session or verified transport auth, never from tool arguments, a task body, a header the client sets, or model output.
 2. An actor with no delegation is denied every check with `no-delegation`. Delegate explicit scopes, never the principal's whole role.
 3. Delegation only narrows. A policy delegation is a ceiling, a token delegation on the same call must also cover the permission, and a `deny` or an `approval` still applies.
-4. One permission per tool. An instance action loads its row through `data` from parsed arguments; a collection permission (`list`, `create`) on a handler that reads `args.id` is a bug.
-5. Tool lists are hints. `capabilityMiddleware`, `guardTools`, MCP list filtering, the A2A extended card, `mayUse` and WebMCP registration hide tools; the server adapter still decides each call.
-6. A failed Web Bot Auth signature throws `InvalidSignatureError`; it never becomes an anonymous actor.
-7. Protocol rules come from the spec skills (`npx skills add ScaleDockHQ/scaledock-skills --skill <name>`): `mcp-authorization` for MCP auth, `a2a` for Agent Cards, `webmcp` for page tools, `web-bot-auth` for signatures, `owasp-agentic` for the threat checklist.
+4. An `agent` actor with a `tools` list calls only those tools: any other is denied with `agent-tool-not-delegated`. An actor with `readOnly: true` is denied every write with `not-delegated`.
+5. One permission per operation. An instance action loads its row through `data` from parsed input; a collection permission (`list`, `create`) on a handler that reads `args.id` is a bug. `meta` labels an operation and never decides.
+6. Tool lists are hints. `allowedOperations`, `capabilityMiddleware`, `guardTools`, MCP list filtering, the A2A extended card, `mayUse` and WebMCP registration hide tools; the server still decides each call.
+7. A trigger never grants. A run reads its principal's rights live on every step through `getPermDock(ticket)`; only the run ticket (`vnd.permdock.run+jwt`) travels between steps.
+8. An unlinked chat author is anonymous. A `ChatAuthor` comes only from a verified platform event and its user id, never an email or display name; an approval button carries the request id, never the token.
+9. A failed Web Bot Auth signature throws `InvalidSignatureError`; it never becomes an anonymous actor.
+10. Protocol rules come from the spec skills (`npx skills add ScaleDockHQ/scaledock-skills --skill <name>`): `mcp-authorization` for MCP auth, `a2a` for Agent Cards, `webmcp` for page tools, `web-bot-auth` for signatures, `owasp-agentic` for the threat checklist.
 
 ## Workflow
 
-1. **Name the three parts per surface.** Write down the principal source, the actor source and the delegation source for each runtime from the Inputs. The adapter table on [delegation](https://permdock.com/docs/security/delegation#how-adapters-fill-actor-and-delegation) shows what each adapter fills itself (MCP and A2A read token scopes; in-process runtimes take a `delegation` option).
-   ✓ Every surface has all three, and none reads from model-controlled input.
-2. **Map the tools.** Use the runtime's `createPermDock` with `subject`, `actor` and a `tools` map, and pass the returned hook to the runtime. -> [references/runtimes.md](references/runtimes.md)
-   ✓ Every tool the agent can call has a `permission`, and every instance permission has a `data` loader that parses its arguments.
-3. **Delegate.** Per call, return `{ scopes: [permissions.post.update.scope] }` (or `authorizationDetails`) from the `delegation` option. As standing policy, declare it once on the policy:
+1. **Name the three parts per surface.** Write down the principal source, the actor source and the delegation source for each surface from the Inputs. The adapter table on [delegation](https://permdock.com/docs/security/delegation#how-adapters-fill-actor-and-delegation) shows what each adapter fills itself (MCP and A2A read token scopes; in-process runtimes take a `delegation` option). An automation run's actor is `automation` and its delegation is its operations' permissions; a chat command's principal is the linked author.
+   ✓ Every surface has all three, and none reads from model-controlled input or a trigger payload.
+2. **Define the operations.** One `defineOperations(permissions, { name: { permission, data?, results?, meta? } })` module for the app, with names in MCP tool-name characters and `meta: { risk, effects, title }` on destructive operations. -> [references/operations-automations-chat.md](references/operations-automations-chat.md#operations-defineoperations-from-permdock)
+   ✓ Every operation names a leaf of the tree, and every instance permission has a `data` loader that parses its input.
+3. **Map the agent tools.** Use the runtime's `createPermDock` with `subject`, `actor`, `delegation` and `operations`, and pass the returned hook to the runtime. For a runtime with no adapter, use `createPermDock` from `permdock/agent` and call `decideOperation(name, input, ctx)` per call. Add `models` for a model gate and `filterResults` on list tools. -> [references/runtimes.md](references/runtimes.md), [agent contract](references/operations-automations-chat.md#agent-contract-permdockagent)
+   ✓ Every tool the agent can call is an operation, and an unnamed tool is denied unless `unmapped: 'allow'` is deliberate.
+4. **Delegate.** Per call, return `{ scopes: [permissions.post.update.scope] }` (or `authorizationDetails`) from the `delegation` option. As standing policy, declare it once on the policy:
 
    ```ts
    definePolicy(permissions, {
@@ -55,23 +62,33 @@ An agent call has a principal (the user whose grants are evaluated), an actor (t
    `from` takes a role, `authenticated()`, a plan or `assurance()`. `to` is an actor kind, or `{ kind, id }` for one agent. A permission outside the ceiling is denied with `not-delegated`.
    ✓ The agent is granted a delegated tool, and denied with `not-delegated` or `no-delegation` for anything else.
 
-4. **Gate destructive tools.** Put `approval: { by }` on each destructive or money-moving grant and pass a `store` to the adapter. Follow the `permdock-approvals` skill (`npx skills add ScaleDockHQ/PermDock --skill permdock-approvals`).
-   ✓ A destructive tool returns the runtime's approval outcome instead of running.
-5. **Wire the agent-facing surfaces.** A2A: serve `agentCard()` publicly, `extendedAgentCard(auth)` behind auth, and `protectSkill` on the task endpoint. WebMCP: `registerTools` from a snapshot, with the server re-checking. Web Bot Auth: `webBotAuth: (request) => verifyWebBotAuth(request, { verify: true, keys })` on the HTTP adapter. -> [references/runtimes.md](references/runtimes.md)
+5. **Gate destructive operations.** Put `approval: { by }` on each destructive or money-moving grant and pass a `store` to the adapter. Follow the `permdock-approvals` skill (`npx skills add ScaleDockHQ/PermDock --skill permdock-approvals`).
+   ✓ A destructive operation returns the runtime's approval outcome instead of running.
+6. **Run automations.** Publish with `decideAutomation(permdock, request)` and store the `Automation` record. Start runs with `start(id, { caller, trigger })` from the `permdock/workflow` factory, call `getPermDock(ticket)` at the top of every step, and wait with `awaitApproval` or `openApproval` plus `resumeApproval`. On the Workflow SDK use `startAutomation`, `workflowSdkWaiter` and `authorizeHook` from `permdock/workflow-sdk`. -> [references/operations-automations-chat.md](references/operations-automations-chat.md#automations-permdockworkflow)
+   ✓ A demoted publisher's next step denies, and a caller without the automation's `run` permission starts nothing.
+7. **Protect chat commands.** Use `createPermDock` from `permdock/chat` with `principals` and `approvals`, wrap each command with `protect(operation, handler)`, and apply buttons with `resolveAction`. On the Chat SDK, build authors with `chatSdkAuthor` and render `approvalCard` with `approvalActions`. -> [references/operations-automations-chat.md](references/operations-automations-chat.md#chat-permdockchat)
+   ✓ An unlinked author is denied with `anonymous`, and the requester's own click on an approval card is refused.
+8. **Wire the agent-facing surfaces.** A2A: serve `agentCard()` publicly, `extendedAgentCard(auth)` behind auth, and `protectSkill` on the task endpoint. WebMCP: `registerTools` from a snapshot, with the server re-checking. Web Bot Auth: `webBotAuth: webBotAuthVerifier({ verify: true, keys })` on the HTTP adapter. -> [references/runtimes.md](references/runtimes.md)
    ✓ Each surface passes the Verify list of its spec skill.
-6. **Test.** Add scenario tests with `permdock/testing` for one delegated grant, one `not-delegated` denial and one approval per destructive tool ([scenario testing](https://permdock.com/docs/guides/scenario-testing)). Then review with the `permdock-audit` skill, which reports ASI02 and ASI03 per adapter.
+9. **Test.** Add scenario tests with `permdock/testing` for one delegated grant, one `not-delegated` denial and one approval per destructive operation ([scenario testing](https://permdock.com/docs/guides/scenario-testing)). Run `testAgentRuntime` against a `permdock/agent` integration. Then review with the `permdock-audit` skill, which reports ASI02 and ASI03 per adapter.
    ✓ The tests pass and the audit has no blocker.
 
 ## Verify before done
 
-- [ ] No `subject`, `actor`, tenant or approval token is read from tool arguments, a task body or model output.
+- [ ] No `subject`, `actor`, tenant or approval token is read from tool arguments, a task body, a trigger payload or model output.
 - [ ] Every in-process agent adapter sets `delegation`, or a policy `delegations` entry covers its actor kind.
-- [ ] Every instance tool has a `data` loader; no collection permission guards a handler that reads one row.
+- [ ] Agent adapters, automations and chat commands read one `defineOperations` map; no adapter keeps its own tool-to-permission table.
+- [ ] Every instance operation has a `data` loader; no collection permission guards a handler that reads one row.
+- [ ] List and search operations whose backend does not filter by subject declare `results` and go through `filterResults`.
+- [ ] A `models` map gates every model the agent may call, when plans or roles price models.
 - [ ] MCP servers set `resource` to their own URL; Claude Agent `mcp__` tools come only from `mcpSources`.
-- [ ] WebMCP and capability filtering are backed by a server-side check on the same permission.
-- [ ] Every destructive tool returns `approval-required`, and the `permdock-approvals` Verify list passes.
+- [ ] WebMCP, capability filtering and `allowedOperations` are backed by a server-side check on the same permission.
+- [ ] Every automation step calls `getPermDock(ticket)` itself, `version` changes on every edit, and an approval wait resumes through `resumeApproval` or `awaitApproval`, never from the wake-up payload.
+- [ ] Chat authors come from verified platform events through `subjectFromChat` or `chatSdkAuthor`, and approval buttons carry the request id.
+- [ ] Every destructive operation returns `approval-required`, and the `permdock-approvals` Verify list passes.
 
 ## Reference index
 
 - [references/runtimes.md](references/runtimes.md): factory shapes and outcome mapping for AI SDK, Claude Agent SDK, Eve, OpenAI Agents SDK, MCP, A2A, WebMCP, Web Bot Auth and `permdock/terminal`.
-- Docs: [delegation](https://permdock.com/docs/security/delegation), [subject](https://permdock.com/docs/concepts/subject), [OWASP Agentic mapping](https://permdock.com/docs/security/owasp-agentic), adapter pages under `https://permdock.com/docs/adapters/<name>`.
+- [references/operations-automations-chat.md](references/operations-automations-chat.md): `defineOperations`, the `permdock/agent` contract, `permdock/workflow` and `permdock/workflow-sdk`, `permdock/chat` and `permdock/chat-sdk`.
+- Docs: [delegation](https://permdock.com/docs/security/delegation), [subject](https://permdock.com/docs/concepts/subject), [operations](https://permdock.com/docs/concepts/operations), [agents](https://permdock.com/docs/concepts/agents), [automations](https://permdock.com/docs/concepts/automations), [chat](https://permdock.com/docs/concepts/chat), [OWASP Agentic mapping](https://permdock.com/docs/security/owasp-agentic), adapter pages under `https://permdock.com/docs/adapters/<name>`.

package/skills/permdock-agents/references/operations-automations-chat.md

@@ -0,0 +1,221 @@
+# Operations, automations and chat
+
+One operation table feeds agent tools, automations and chat commands. `permdock/agent`, `permdock/workflow` and `permdock/chat` are the runtime-neutral contracts; `permdock/ai-sdk`, `permdock/openai`, `permdock/claude-agent`, `permdock/eve`, `permdock/workflow-sdk` and `permdock/chat-sdk` implement them for one runtime.
+
+## Operations: `defineOperations` from `permdock`
+
+```ts
+import { defineOperations } from "permdock";
+
+export const operations = defineOperations(permissions, {
+  send_invoice: {
+    permission: permissions.billing.invoice.submit,
+    data: (input: { id: string }) => db.invoice.find(input.id),
+    meta: {
+      risk: "high",
+      effects: ["send", "external"],
+      title: "Send invoice",
+    },
+  },
+  list_invoices: {
+    permission: permissions.billing.invoice.read,
+    results: permissions.billing.invoice.read,
+  },
+});
+```
+
+It returns a frozen `OperationMap`; each entry is a frozen `Operation` `{ name, permission, data?, results?, meta }`.
+
+| Field        | Meaning                                                                       |
+| ------------ | ----------------------------------------------------------------------------- |
+| `permission` | The leaf a caller must hold to run the operation                              |
+| `data`       | Loads the row the check runs on from the input                                |
+| `results`    | The leaf each result row is filtered by                                       |
+| `meta`       | `{ risk?, effects?, title? }`, `{}` when absent; PermDock never decides on it |
+
+- `risk` is one of `low`, `medium`, `high`, `critical`. `effects` lists distinct values of `read`, `write`, `delete`, `send`, `spend`, `external`.
+- A name is 1 to 128 of `A-Z a-z 0-9 _ . -` (the MCP tool-name characters), so it works as a tool name unchanged. Names that differ only in case throw.
+- `defineOperations` also throws for a `permission` or `results` outside `permissions` and for a `data` that is not a function.
+- The row `data` returns is validated against the resource schema like any request-derived data. Parse the input before loading.
+- With `operations: "./src/operations.ts"` in `permdock.config.ts`, `permdock collect` writes the map to the catalog, and doctor PD067 reports a key the permissions module does not declare.
+
+Every agent adapter takes this map as `operations` ([operations](https://permdock.com/docs/concepts/operations)).
+
+## Agent contract: `permdock/agent`
+
+`permdock/ai-sdk`, `permdock/openai`, `permdock/claude-agent` and `permdock/eve` build on this contract and return its members next to their runtime hooks. Use `permdock/agent` directly for a runtime PermDock has no adapter for.
+
+```ts
+import { createPermDock } from "permdock/agent";
+
+const agent = createPermDock(policy, {
+  subject: (ctx: Context) => ctx.user,
+  actor: (ctx) => ({ id: ctx.agentId, kind: "agent" }),
+  delegation: (ctx) => ({ scopes: ctx.scopes }),
+  operations,
+  models: {
+    "openai/gpt-5.2": permissions.model.frontier,
+    "openai/gpt-5.2-mini": permissions.model.standard,
+  },
+  store, // ApprovalStore, for approval-required operations
+});
+```
+
+| Member                                           | What it does                                                                                                                |
+| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
+| `decideOperation(name, input, ctx)`              | Loads the row through `data`, validates, decides and resumes an approval; never throws                                      |
+| `allowedOperations(ctx)`                         | Names the subject could be granted for some row: a listing hint for the tool list, never a decision                         |
+| `decideModel(id, ctx)`                           | The decision for one model; a model `models` does not name is denied                                                        |
+| `permittedModels(ctx)`                           | Granted model ids in declaration order                                                                                      |
+| `filterResults(name, rows, ctx)`                 | Keeps the rows the subject may see by the operation's `results`; rows unchanged without `results`; none for an unknown name |
+| `gatewayOptions(ctx)`                            | `providerOptions.gateway` for the Vercel AI Gateway: principal id as `user`, `tenant:<id>` and `actor:<kind>` as `tags`     |
+| `getPermDock(ctx)`, `tokenFor(name, input, ctx)` | The instance for a context, and the approval token a call would park under                                                  |
+
+An operation `operations` does not name is denied unless `unmapped: 'allow'`. `gatewayOptions` carries identifiers only, never a decision. Use `filterResults` on search and list tools whose backend does not filter by subject.
+
+Test an implementation with `testAgentRuntime({ name, mount, skip? })` from `permdock/testing`. `mount(domain)` returns `{ agent, close? }`, an `AgentPermDock` built from `domain.subject`, `domain.operations`, `domain.models` and `domain.store` ([agents](https://permdock.com/docs/concepts/agents), [testing](https://permdock.com/docs/adapters/testing)).
+
+## Automations: `permdock/workflow`
+
+A run acts as the automation's principal with live rights, narrowed to the automation's operations and to any policy delegation to `actor('automation')`. The trigger only needs the automation's `run` permission to start a run; it is recorded in `subject.context.trigger` and lends the run nothing.
+
+### Publish
+
+```ts
+import { decideAutomation } from "permdock";
+const decision = await decideAutomation(permdock, {
+  id: "weekly-overdue",
+  version: 1,
+  operations: [operations.read_invoice, operations.send_invoice],
+  run: permissions.report.run,
+  name: "Overdue invoices",
+});
+if (decision.outcome === "granted") await automations.save(decision.automation);
+```
+
+`decideAutomation` checks that the publisher may use each operation's permission in the tenant, and returns an `Automation` record. A link, feed, contact, API key or run-ticket subject cannot publish.
+
+| `mode`                | The run acts as                                                                                      |
+| --------------------- | ---------------------------------------------------------------------------------------------------- |
+| `publisher` (default) | The publisher, with their rights as of each run                                                      |
+| `service`             | A `kind: 'service'` principal holding `roles` in `tenant`, capped at what the publisher could assign |
+
+Bump `version` on every edit: a run ticket for another version is refused. `AutomationSource` is the live record store, read on every run; `memoryAutomationSource` is the in-process default.
+
+### Run
+
+```ts
+import { createPermDock, pollingApprovalWaiter } from "permdock/workflow";
+
+const workflow = createPermDock(policy, {
+  signer, // TokenSigner for run tickets
+  verifier, // TokenVerifier for run tickets
+  principals, // PrincipalSource, read live on every step
+  automations, // AutomationSource
+  store: store,
+  waiter: pollingApprovalWaiter({ store }),
+  sink,
+});
+
+const started = await workflow.start("weekly-overdue", {
+  caller: permdock,
+  trigger: event,
+});
+// pass started.ticket as the job payload; in each step:
+const run = await workflow.getPermDock(ticket);
+run.can(permissions.invoice.send, invoice);
+```
+
+- `start(id, { caller, trigger })` reads the live automation, checks the caller's `run` permission and signs a run ticket (`vnd.permdock.run+jwt`, 24 hours by default). Without `caller`, only server code starts it.
+- `getPermDock(ticket)` rebuilds the run on every step. A new version, a revoked automation or a publisher who is gone gives an instance that denies everything.
+- `awaitApproval(ticket, permission, row)` decides, parks on the `waiter` while `approval-required`, then decides again with the token against the publisher's rights as of then.
+- `openApproval(ticket, permission, row)` and `resumeApproval(ticket, permission, token, row)` are the two halves, for runners that wait outside the call. A request still pending denies with reason `approval`.
+- `pollingApprovalWaiter({ store, interval })` polls every `interval` milliseconds (5,000 by default).
+
+For Trigger.dev, Inngest, Temporal, Vercel Queues and pgmq: call `start` where the trigger arrives, pass the ticket as the payload, call `getPermDock(ticket)` at the top of each step, `openApproval` before the wait and `resumeApproval` after it. A wake-up carries no verdict ([automations](https://permdock.com/docs/concepts/automations)).
+
+### Workflow SDK: `permdock/workflow-sdk`
+
+```ts
+import {
+  authorizeHook,
+  startAutomation,
+  workflowSdkWaiter,
+} from "permdock/workflow-sdk";
+import { createHook, sleep } from "workflow";
+import { resumeHook, start } from "workflow/api";
+
+const waiter = workflowSdkWaiter({ createHook, resumeHook, sleep });
+
+const started = await startAutomation(
+  workflow,
+  start,
+  sendOverdue,
+  "weekly-overdue",
+  [invoiceId],
+  { caller: permdock, trigger: event },
+);
+```
+
+- `startAutomation(workflow, start, fn, id, args, options)` starts the Workflow SDK run with the ticket as the first argument only when `workflow.start` is granted.
+- `waiter.wait(token)` parks inside the `"use workflow"` function; `openApproval` and `resumeApproval` run as `"use step"` functions around it. The approver handler calls `waiter.wake(token)` after `resolveApproval`.
+- `authorizeHook(resumeHook, caller, permission, row, token, payload)` resumes any other hook only when `caller.decide(permission, row)` is granted. A hook token alone is not an identity ([Workflow SDK adapter](https://permdock.com/docs/adapters/workflow-sdk)).
+
+## Chat: `permdock/chat`
+
+A chat command runs an operation as the principal the verified chat author links to.
+
+```ts
+import { createPermDock } from "permdock/chat";
+
+const chatPermDock = createPermDock(policy, {
+  principals,
+  memberships,
+  store: store,
+});
+
+const pay = chatPermDock.protect(
+  operations["invoice.pay"],
+  async ({ input }) => {
+    await invoices.pay(input.id);
+    return `Paid ${input.id}.`;
+  },
+);
+
+const result = await pay(author, { id: "inv_42" });
+```
+
+- A `ChatAuthor` is `{ provider, userId, workspace? }`, built only from an event whose platform signature the transport verified.
+- `subjectFromChat(author, { principals })` resolves it through `principals.principalByIdentity({ kind: 'chat', provider, value: userId, workspace })`. A missing, malformed or unlinked author is anonymous, so every check denies with `anonymous`. It never throws.
+- The identity link is app data, written when a signed-in user connects their chat account. `memoryPrincipalSource({ principals, identities })` holds links in process.
+- `protect(operation, handler)` resolves `granted` with the handler's `value`, `denied` with the decision, or `approval-required` with an `ApprovalPrompt` (`null` without `approvals`). An approved request runs the handler once.
+- `resolveAction(author, { approval, status, note? })` applies `approved` or `rejected` as the clicking author through `resolveApproval`. The button carries the request id, never the token. The requester never approves their own request ([chat](https://permdock.com/docs/concepts/chat)).
+
+### Chat SDK: `permdock/chat-sdk`
+
+`chat` here is the Chat SDK `Chat` instance.
+
+```ts
+import {
+  approvalActions,
+  approvalCard,
+  chatSdkAuthor,
+} from "permdock/chat-sdk";
+
+chat.onNewMention(async (thread, message) => {
+  const author = chatSdkAuthor(message.author, thread.adapter, {
+    workspace: "T0ACME",
+  });
+  const result = await pay(author, { id: "inv_42" });
+  await thread.post(
+    result.outcome === "granted" ? result.value : "Not allowed.",
+  );
+});
+
+const actions = approvalActions(chatPermDock, { workspace: "T0ACME" });
+chat.onAction([...actions.actionIds], actions.onAction);
+```
+
+- `chatSdkAuthor(user, adapter, { workspace? })` reads only `userId`, never the email or display name, and returns `null` for a bot, the bot itself or the platform.
+- `approvalCard(prompt, { approvalUrl, buttons? })` renders the prompt with a Review link and Approve and Reject buttons; `buttons: false` leaves only the link.
+- `approvalActions(chatPermDock, { workspace?, onResult? })` routes the clicks to `resolveAction` ([Chat SDK adapter](https://permdock.com/docs/adapters/chat-sdk)).