@impetik/xeer-mcp 0.2.5 → 0.2.6

package/vendor/spec/actions.js

@@ -0,0 +1,805 @@
+/** Stable protocol for the action catalogue consumed by CLI, MCP, and agent context surfaces. */
+import { REVIEW_RECEIPT_ID_SOURCE } from './review.js';
+export const ACTION_REGISTRY_PROTOCOL = 'xeer.actions.v0';
+export const XEER_MCP_PROFILES = ['author', 'operator'];
+export const XEER_ARTIFACT_ID_PATTERN = '^sha256:[a-f0-9]{64}$';
+export const MCP_INPUT_SCHEMA_DRAFT = 'http://json-schema.org/draft-07/schema#';
+const NOT_EXPOSED_V0 = 'Not exposed through MCP v0; use the CLI deliberately.';
+const HUMAN_IDENTITY = 'Human identity and project ownership decisions are not delegated through MCP.';
+const SECRET_VALUES = 'Secret values are intentionally unreachable through MCP; env pull returns plaintext.';
+const SERVICE_CREDENTIALS = 'Service credential issuance and revocation are intentionally CLI-only.';
+const DESTRUCTIVE_STATE = 'Destructive state replacement requires an explicit CLI invocation.';
+const PREVIEW_ONLY = 'MCP exposes a separate preview-only deploy action; direct production deploy stays CLI-only.';
+const OPERATOR_ONLY = 'MCP promotion is a separate action available only when the server starts in operator profile.';
+const PROJECT_DIRECTORY_INPUT = {
+    description: 'Project directory. Relative paths resolve against the server root; defaults to it.',
+    type: 'string',
+};
+const CONTROL_URL_INPUT = { description: 'Allowed control-plane origin override.', type: 'string' };
+const SESSION_ID_INPUT = { description: 'Optional when only one session exists.', type: 'string' };
+const ARTIFACT_ID_INPUT = {
+    description: 'Exact artifact id to promote: sha256: followed by 64 lowercase hexadecimal characters.',
+    type: 'string',
+    minLength: 71,
+    maxLength: 71,
+    pattern: XEER_ARTIFACT_ID_PATTERN,
+};
+const REVIEW_RECEIPT_ID_INPUT = {
+    description: 'Versioned receipt returned by the exact reviewed preview deployment.',
+    type: 'string',
+    minLength: 19,
+    maxLength: 103,
+    pattern: REVIEW_RECEIPT_ID_SOURCE,
+};
+const MCP_PRESENTATION = {
+    check: {
+        mcpTitle: 'Check a Xeer project',
+        mcpDescription: [
+            'Validate a Xeer project and return its diagnostics as JSON. This is the repair loop:',
+            'read diagnostics, apply the smallest edit each one names, run it again, converge on ok: true.',
+            'Runs the manifest stage and, if that passes, the module-graph/zone/operations/type analysis.',
+            'Envelope: { protocol: "xeer.command.v0", command: "check", ok, diagnostics: Diagnostic[],',
+            'result?: { manifest } }. Diagnostic codes are stable — look one up with xeer_diagnostics.',
+        ].join(' '),
+    },
+    build: {
+        mcpTitle: 'Build a Xeer project',
+        mcpDescription: [
+            'Build the content-addressed artifact. Runs check first, so build diagnostics are a superset',
+            'of check diagnostics plus bundling, budget, and asset codes (XE14xx, XE15xx).',
+            'On success result is { artifactId, outputDirectory, modules, assets, operations }.',
+            'Run xeer_test before this to prove the application behaves, not just that it compiles.',
+        ].join(' '),
+    },
+    test: {
+        mcpTitle: 'Run a Xeer project\'s tests',
+        mcpDescription: [
+            'Run the application\'s own tests: build, type-check tests/**/*.test.ts against the generated',
+            'contract, boot the verified artifact in workerd with fresh isolated state, run every test, tear',
+            'down. This is the convergence check — a green check proves the project compiles, a green test',
+            'proves it behaves. Returns { ok, total, passed, failed, cases, diagnostics, events }.',
+            'Each failed case carries a Diagnostic-shaped failure with matcher, expected, actual, and the',
+            'project-relative test location: XE1904 assertion, XE1905 threw or unexpectedly refused call,',
+            'XE1906 timeout. Compiler diagnostics abort the run before any test boots.',
+            'Tests call as(\'alice\'|\'bob\'|\'guest\'), so ownership and authorization are directly testable.',
+        ].join(' '),
+    },
+    new: {
+        mcpTitle: 'Scaffold a Xeer project',
+        mcpDescription: 'Create a new Xeer project in an empty or non-existent directory. '
+            + 'Every template checks, tests, and builds clean, so use one as the starting point rather '
+            + 'than writing a manifest by hand. "notes" (the default) and "todo" are per-user apps, "blog" '
+            + 'is public to read and private to write, and "personal-site" has no database at all. None of '
+            + 'them scaffolds sign-in UI. result is { directory, name, template, files }; an unknown '
+            + 'template is XE3002 and writes nothing.',
+    },
+    doctor: {
+        mcpTitle: 'Diagnose the Xeer toolchain',
+        mcpDescription: 'Check the local toolchain and generated-file state. Use it when a command fails for '
+            + 'a reason no project edit explains. result is { checks, summary }; failures also appear as XE4001 '
+            + 'diagnostics.',
+    },
+    deploy: {
+        mcpTitle: 'Deploy a Xeer preview',
+        mcpDescription: 'Build, verify, and upload the artifact to the preview environment. This tool never '
+            + 'changes production. Requires a builder '
+            + 'credential: XE5002 means a human must run `xeer auth login` first. result is '
+            + '{ application, url, ... } for the app\'s side-by-side preview URL; production keeps serving, '
+            + 'and preview has its own disposable state.',
+    },
+    promote: {
+        mcpTitle: 'Promote an exact preview artifact (operator)',
+        mcpDescription: 'Make the version currently on the app\'s preview URL live on production — the same '
+            + 'bundle, not a rebuild, with production\'s own environment values. The second half of the '
+            + '"deploy to preview, look at it, then ship it" loop. XE5175 means nothing has been deployed to '
+            + 'preview yet. The exact artifact id is required. This tool exists only when the server starts '
+            + 'with XEER_MCP_PROFILE=operator. result is { artifactId, replaced, url, ... }.',
+    },
+    'auth.status': {
+        mcpTitle: 'Report builder sign-in status',
+        mcpDescription: 'Report whether a builder credential is available for deployment. Sign-in itself is '
+            + 'interactive and cannot be completed by an agent; XE5002 means ask the human to run '
+            + '`xeer auth login`.',
+    },
+    inspect: {
+        mcpTitle: 'Inspect a running preview',
+        mcpDescription: 'Read the inspector API of a running dev or preview server: normalized manifest '
+            + '(manifest), per-table record counts (state), the bounded structured log ring (logs), or '
+            + 'every stored record with the schema that describes it (export). Use the URLs from '
+            + 'xeer_dev_status.preview.',
+    },
+    'dev.start': {
+        mcpTitle: 'Start a dev session',
+        mcpDescription: [
+            'Start `xeer dev --json` and return the xeer.dev.v0 events it emitted up to the point it settled.',
+            'Returns when preview.ready arrives (status "ready"), or when the first compile fails',
+            '(status "compile_failed", openDiagnostics populated). Port 0 by default, so the real URL is in',
+            'preview.ready. Keep the returned cursor and pass it to xeer_dev_status after each edit.',
+            'You do not need a dev session to repair diagnostics: xeer_check is the same compiler.',
+        ].join(' '),
+    },
+    'dev.status': {
+        mcpTitle: 'Read new dev-session events',
+        mcpDescription: [
+            'Read the xeer.dev.v0 events emitted since `cursor`, then return the session summary.',
+            'After editing a file, call this with waitMilliseconds set: the CLI coalesces changes behind a',
+            '75 ms quiet window, rebuilds, and emits compile.start, any compile.diagnostic, and compile.ready',
+            'when the rebuild is accepted. openDiagnostics is the outcome of the latest attempt, so an empty',
+            'openDiagnostics with a higher generation means the edit was accepted.',
+        ].join(' '),
+    },
+    'dev.stop': {
+        mcpTitle: 'Stop a dev session',
+        mcpDescription: 'Stop a dev session over the documented xeer.dev.control.v0 IPC shutdown, releasing '
+            + 'the local state lease. Always stop sessions you started: the lease is per project and mode, '
+            + 'so a leaked session blocks the next dev run with XE1812.',
+    },
+    diagnostics: {
+        mcpTitle: 'Look up Xeer diagnostic codes',
+        mcpDescription: 'Explain a diagnostic code: what the platform observed and which edit closes it. '
+            + 'Omit `code` for the whole generated reference. This is the same catalogue the compiler emits '
+            + 'from, so it cannot drift from the codes you receive.',
+    },
+};
+const actions = [
+    {
+        id: 'check', command: ['check'], summary: 'Validate a project and report structured diagnostics.',
+        usage: ['check [directory] [--json]'], helpOrder: 10,
+        outputProtocol: 'xeer.command.v0', effects: ['read-source', 'write-generated'],
+        idempotent: true, reversible: true, destructive: false, humanPrerequisites: [],
+        pathPolicy: 'project-relative', surfaces: {
+            cli: true, mcpTool: 'xeer_check', mcpProfiles: XEER_MCP_PROFILES,
+            ...MCP_PRESENTATION.check,
+            mcpInputSchema: { type: 'object', properties: { directory: PROJECT_DIRECTORY_INPUT } },
+        },
+    },
+    {
+        id: 'build', command: ['build'], summary: 'Build and verify a content-addressed application artifact.',
+        usage: ['build [directory] [--json]'], helpOrder: 40,
+        outputProtocol: 'xeer.command.v0', effects: ['read-source', 'write-generated', 'run-local'],
+        idempotent: true, reversible: true, destructive: false, humanPrerequisites: [],
+        pathPolicy: 'project-relative', surfaces: {
+            cli: true, mcpTool: 'xeer_build', mcpProfiles: XEER_MCP_PROFILES,
+            ...MCP_PRESENTATION.build,
+            mcpInputSchema: { type: 'object', properties: { directory: PROJECT_DIRECTORY_INPUT } },
+        },
+    },
+    {
+        id: 'test', command: ['test'], summary: 'Run application tests against fresh isolated local state.',
+        usage: ['test [directory] [--host <host>] [--json]'], helpOrder: 250, outputProtocol: 'xeer.dev.v0',
+        effects: ['read-source', 'write-generated', 'run-local', 'write-state'],
+        idempotent: true, reversible: true, destructive: false, humanPrerequisites: [],
+        pathPolicy: 'project-relative', surfaces: {
+            cli: true, mcpTool: 'xeer_test', mcpProfiles: XEER_MCP_PROFILES,
+            ...MCP_PRESENTATION.test,
+            mcpInputSchema: { type: 'object', properties: {
+                    directory: PROJECT_DIRECTORY_INPUT,
+                    timeoutMilliseconds: { type: 'integer', minimum: 1_000, maximum: 1_800_000 },
+                } },
+        },
+    },
+    {
+        id: 'new', command: ['new'], summary: 'Create a new project from a supported scaffold.',
+        usage: ['new <directory> [--template {{templates}}] [--json]'], helpOrder: 30,
+        outputProtocol: 'xeer.command.v0', effects: ['write-source'], idempotent: false,
+        reversible: true, destructive: false, humanPrerequisites: [], pathPolicy: 'project-relative',
+        surfaces: {
+            cli: true, mcpTool: 'xeer_new', mcpProfiles: XEER_MCP_PROFILES,
+            ...MCP_PRESENTATION.new,
+            mcpInputSchema: {
+                type: 'object',
+                properties: {
+                    directory: {
+                        type: 'string', description: 'Target directory, relative to the server root. Must be empty or absent.',
+                    },
+                    template: {
+                        description: 'Which scaffold to write. Defaults to notes.', type: 'string',
+                        enum: ['notes', 'todo', 'blog', 'personal-site'],
+                    },
+                },
+                required: ['directory'],
+            },
+        },
+    },
+    {
+        id: 'agent.setup', command: ['agent', 'setup'],
+        summary: 'Install or verify project-confined agent adapters.',
+        usage: ['agent setup [directory] [--target auto|agents|claude|codex|cursor|vscode|mcp] [--check] [--json]'],
+        helpOrder: 35, outputProtocol: 'xeer.command.v0', effects: ['read-source', 'write-source'],
+        idempotent: true, reversible: true, destructive: false, humanPrerequisites: [],
+        pathPolicy: 'project-relative', surfaces: { cli: true, mcpExclusion: NOT_EXPOSED_V0 },
+    },
+    {
+        id: 'agent.context', command: ['agent', 'context'],
+        summary: 'Read normalized project facts, operations, diagnostics, tests, and safe next actions.',
+        usage: ['agent context [directory] [--json]'], helpOrder: 34,
+        outputProtocol: 'xeer.agent-context.v0', effects: ['read-source'],
+        idempotent: true, reversible: true, destructive: false, humanPrerequisites: [],
+        pathPolicy: 'project-relative', surfaces: {
+            cli: true, mcpTool: 'xeer_agent_context', mcpProfiles: XEER_MCP_PROFILES,
+            mcpTitle: 'Read normalized Xeer project context',
+            mcpDescription: 'Read the bounded, deterministic, versioned project context without writing generated files. Returns normalized manifest facts, source zones, operations, diagnostics, tests, safe next actions, resources, and a stable content hash.',
+            mcpInputSchema: { type: 'object', properties: { directory: PROJECT_DIRECTORY_INPUT } },
+        },
+    },
+    {
+        id: 'docs.search', command: ['docs', 'search'],
+        summary: 'Search the installed-version Xeer documentation index.',
+        usage: ['docs search <query> [--limit <n>] [--json]'], helpOrder: 36,
+        outputProtocol: 'xeer.docs-search.v0', effects: [],
+        idempotent: true, reversible: true, destructive: false, humanPrerequisites: [],
+        pathPolicy: 'none', surfaces: {
+            cli: true, mcpTool: 'xeer_docs_search', mcpProfiles: XEER_MCP_PROFILES,
+            mcpTitle: 'Search installed Xeer documentation',
+            mcpDescription: 'Run deterministic lexical search over the compact index bundled with this exact framework version. Returns matching resource URIs and content hashes; read the selected xeer://docs/<path> resource on demand.',
+            mcpInputSchema: { type: 'object', properties: {
+                    query: { type: 'string', minLength: 1, maxLength: 500, description: 'Terms or phrase to search for.' },
+                    limit: { type: 'integer', minimum: 1, maximum: 20, default: 5, description: 'Maximum result count.' },
+                }, required: ['query'] },
+        },
+    },
+    {
+        id: 'doctor', command: ['doctor'], summary: 'Diagnose the toolchain and generated project state.',
+        usage: ['doctor [directory] [--json]'], helpOrder: 20,
+        outputProtocol: 'xeer.command.v0', effects: ['read-source', 'write-generated'],
+        idempotent: true, reversible: true, destructive: false, humanPrerequisites: [],
+        pathPolicy: 'project-relative', surfaces: {
+            cli: true, mcpTool: 'xeer_doctor', mcpProfiles: XEER_MCP_PROFILES,
+            ...MCP_PRESENTATION.doctor,
+            mcpInputSchema: { type: 'object', properties: { directory: PROJECT_DIRECTORY_INPUT } },
+        },
+    },
+    {
+        id: 'deploy', command: ['deploy'], summary: 'Build and deploy an application artifact.',
+        usage: ['deploy [directory] [--environment prod|preview] [--control-url <url>] [--json]'], helpOrder: 50,
+        outputProtocol: 'xeer.command.v0',
+        effects: ['read-source', 'write-generated', 'run-local', 'network-read', 'network-write', 'production-change'],
+        idempotent: false, reversible: true, destructive: false,
+        humanPrerequisites: ['A human must establish the builder credential with xeer auth login.'],
+        pathPolicy: 'project-relative', surfaces: { cli: true, mcpExclusion: PREVIEW_ONLY },
+    },
+    {
+        id: 'promote', command: ['promote'], summary: 'Promote a preview artifact to production.',
+        usage: ['promote [app|directory] [--receipt <receiptId> | --from-artifact <artifactId>] '
+                + '[--control-url <url>] [--json]'], helpOrder: 80,
+        outputProtocol: 'xeer.command.v0', effects: ['network-read', 'network-write', 'production-change'],
+        idempotent: false, reversible: true, destructive: false,
+        humanPrerequisites: ['The preview artifact must be reviewed before production promotion.'],
+        pathPolicy: 'project-or-url', surfaces: { cli: true, mcpExclusion: OPERATOR_ONLY },
+    },
+    {
+        id: 'deploy.preview', command: ['deploy'], summary: 'Build and deploy an artifact to preview only.',
+        usage: [], outputProtocol: 'xeer.command.v0',
+        effects: ['read-source', 'write-generated', 'run-local', 'network-read', 'network-write'],
+        idempotent: false, reversible: true, destructive: false,
+        humanPrerequisites: ['A human must establish the builder credential with xeer auth login.'],
+        pathPolicy: 'project-relative', surfaces: {
+            cli: false, mcpTool: 'xeer_deploy_preview', mcpProfiles: ['author', 'operator'],
+            ...MCP_PRESENTATION.deploy,
+            mcpInputSchema: { type: 'object', properties: {
+                    directory: PROJECT_DIRECTORY_INPUT,
+                    controlUrl: {
+                        description: 'Allowed control-plane origin override. The hosted Xeer origin is allowed by default; '
+                            + 'additional exact HTTPS or loopback development origins must be preconfigured.',
+                        type: 'string',
+                    },
+                } },
+        },
+    },
+    {
+        id: 'promote.operator', command: ['promote'], summary: 'Promote an exact review receipt in operator mode.',
+        usage: [], outputProtocol: 'xeer.command.v0', effects: ['network-read', 'network-write', 'production-change'],
+        idempotent: false, reversible: true, destructive: false,
+        humanPrerequisites: [
+            'A human must review the exact artifact and start xeer-mcp with XEER_MCP_PROFILE=operator.',
+        ],
+        pathPolicy: 'project-or-url', surfaces: {
+            cli: false, mcpTool: 'xeer_promote', mcpProfiles: ['operator'],
+            ...MCP_PRESENTATION.promote,
+            mcpInputSchema: { type: 'object', properties: {
+                    directory: PROJECT_DIRECTORY_INPUT,
+                    receiptId: REVIEW_RECEIPT_ID_INPUT,
+                    controlUrl: CONTROL_URL_INPUT,
+                }, required: ['receiptId'] },
+        },
+    },
+    {
+        id: 'auth.status', command: ['auth', 'status'], summary: 'Report builder credential metadata.',
+        usage: ['auth status [--control-url <url>] [--json]'], helpOrder: 180,
+        outputProtocol: 'xeer.command.v0', effects: ['network-read', 'secret-metadata'], idempotent: true,
+        reversible: true, destructive: false, humanPrerequisites: [], pathPolicy: 'none',
+        surfaces: {
+            cli: true, mcpTool: 'xeer_auth_status', mcpProfiles: XEER_MCP_PROFILES,
+            ...MCP_PRESENTATION['auth.status'],
+            mcpInputSchema: { type: 'object', properties: { controlUrl: CONTROL_URL_INPUT } },
+        },
+    },
+    {
+        id: 'inspect', command: ['inspect'], summary: 'Read a running application manifest.',
+        usage: ['inspect <local-url|app> [--environment prod|preview] [--control-url <url>] [--json]'], helpOrder: 230,
+        outputProtocol: 'xeer.command.v0', effects: ['network-read', 'read-state'], idempotent: true,
+        reversible: true, destructive: false, humanPrerequisites: [], pathPolicy: 'app-or-url',
+        surfaces: {
+            cli: true, mcpTool: 'xeer_inspect', mcpProfiles: XEER_MCP_PROFILES,
+            ...MCP_PRESENTATION.inspect,
+            mcpInputSchema: {
+                type: 'object',
+                properties: {
+                    previewUrl: {
+                        type: 'string', description: 'Loopback URL from preview.ready, hosted https://<app>.xeer.run origin, '
+                            + 'application name, or appId.',
+                    },
+                    view: { default: 'manifest', type: 'string', enum: ['manifest', 'state', 'logs', 'export'] },
+                    after: { description: 'Log cursor, for view: "logs".', type: 'string' },
+                },
+                required: ['previewUrl'],
+            },
+        },
+    },
+    {
+        id: 'dev.start', command: ['dev'], summary: 'Start a local development session.',
+        usage: ['dev [directory] [--host <host>] [--port <port>] [--json]'], helpOrder: 220,
+        outputProtocol: 'xeer.dev.v0', effects: ['read-source', 'write-generated', 'run-local', 'write-state'],
+        idempotent: false, reversible: true, destructive: false, humanPrerequisites: [],
+        pathPolicy: 'project-relative', surfaces: {
+            cli: true, mcpTool: 'xeer_dev_start', mcpProfiles: XEER_MCP_PROFILES,
+            ...MCP_PRESENTATION['dev.start'],
+            mcpInputSchema: { type: 'object', properties: {
+                    directory: PROJECT_DIRECTORY_INPUT,
+                    host: { description: 'Defaults to 127.0.0.1.', type: 'string' },
+                    port: { description: 'Defaults to 0 (OS-assigned).', type: 'integer', minimum: 0, maximum: 65_535 },
+                    timeoutMilliseconds: { type: 'integer', minimum: 1_000, maximum: 600_000 },
+                } },
+        },
+    },
+    {
+        id: 'dev.status', command: ['dev'], summary: 'Read new events from a local development session.',
+        usage: [], outputProtocol: 'xeer.dev.v0', effects: [], idempotent: true, reversible: true,
+        destructive: false, humanPrerequisites: [], pathPolicy: 'none',
+        surfaces: {
+            cli: false, mcpTool: 'xeer_dev_status', mcpProfiles: XEER_MCP_PROFILES,
+            ...MCP_PRESENTATION['dev.status'],
+            mcpInputSchema: { type: 'object', properties: {
+                    sessionId: SESSION_ID_INPUT,
+                    cursor: {
+                        default: 0, description: 'Last seq you have already read.', type: 'integer',
+                        minimum: 0, maximum: Number.MAX_SAFE_INTEGER,
+                    },
+                    waitMilliseconds: {
+                        default: 0, description: 'Wait up to this long for new events to arrive and settle.',
+                        type: 'integer', minimum: 0, maximum: 600_000,
+                    },
+                    limit: { default: 200, type: 'integer', minimum: 1, maximum: 1_000 },
+                } },
+        },
+    },
+    {
+        id: 'dev.stop', command: ['dev'], summary: 'Stop a local development session and release its lease.',
+        usage: [], outputProtocol: 'xeer.dev.v0', effects: ['run-local'], idempotent: true,
+        reversible: true, destructive: false, humanPrerequisites: [], pathPolicy: 'none',
+        surfaces: {
+            cli: false, mcpTool: 'xeer_dev_stop', mcpProfiles: XEER_MCP_PROFILES,
+            ...MCP_PRESENTATION['dev.stop'],
+            mcpInputSchema: { type: 'object', properties: {
+                    sessionId: SESSION_ID_INPUT,
+                    cursor: { default: 0, type: 'integer', minimum: 0, maximum: Number.MAX_SAFE_INTEGER },
+                } },
+        },
+    },
+    {
+        id: 'diagnostics', command: [], summary: 'Read the generated diagnostic catalogue.',
+        usage: [], outputProtocol: 'unversioned', effects: [], idempotent: true, reversible: true,
+        destructive: false, humanPrerequisites: [], pathPolicy: 'none',
+        surfaces: {
+            cli: false, mcpTool: 'xeer_diagnostics', mcpProfiles: XEER_MCP_PROFILES,
+            ...MCP_PRESENTATION.diagnostics,
+            mcpInputSchema: { type: 'object', properties: {
+                    code: { description: 'An XE#### code, e.g. XE1202.', type: 'string' },
+                } },
+        },
+    },
+    {
+        id: 'link', command: ['link'], summary: 'Link a checkout to an application the builder owns.',
+        usage: ['link [directory] [--app <appId>] [--new] [--control-url <url>] [--json]'], helpOrder: 60,
+        outputProtocol: 'xeer.command.v0', effects: ['read-source', 'write-source', 'network-read', 'network-write'],
+        idempotent: false, reversible: true, destructive: false,
+        humanPrerequisites: ['A human must choose which hosted application this checkout controls.'],
+        pathPolicy: 'project-relative', surfaces: { cli: true, mcpExclusion: HUMAN_IDENTITY },
+    },
+    {
+        id: 'deployments', command: ['deployments'], summary: 'List deployment history for an application.',
+        usage: ['deployments [app|directory] [--limit <n>] [--control-url <url>] [--json]'], helpOrder: 70,
+        outputProtocol: 'xeer.command.v0', effects: ['network-read', 'read-state', 'secret-metadata'],
+        idempotent: true, reversible: true, destructive: false,
+        humanPrerequisites: ['A human must establish the builder credential with xeer auth login.'],
+        pathPolicy: 'project-or-url', surfaces: { cli: true, mcpExclusion: NOT_EXPOSED_V0 },
+    },
+    {
+        id: 'rollback', command: ['rollback'], summary: 'Redeploy a previously deployed artifact.',
+        usage: ['rollback [app|directory] <artifactId> [--environment prod|preview] [--control-url <url>] [--json]'],
+        helpOrder: 90, outputProtocol: 'xeer.command.v0',
+        effects: ['network-read', 'network-write', 'production-change'], idempotent: false,
+        reversible: true, destructive: false,
+        humanPrerequisites: ['A human must choose the artifact and deployment environment to restore.'],
+        pathPolicy: 'project-or-url', surfaces: { cli: true, mcpExclusion: NOT_EXPOSED_V0 },
+    },
+    {
+        id: 'disable', command: ['disable'], summary: 'Take an application offline without deleting its data.',
+        usage: ['disable [app|directory] [--control-url <url>] [--json]'], helpOrder: 100,
+        outputProtocol: 'xeer.command.v0', effects: ['network-read', 'network-write', 'production-change'],
+        idempotent: true, reversible: true, destructive: false,
+        humanPrerequisites: ['A human must authorize taking the production application offline.'],
+        pathPolicy: 'project-or-url', surfaces: { cli: true, mcpExclusion: NOT_EXPOSED_V0 },
+    },
+    {
+        id: 'enable', command: ['enable'], summary: 'Restore a disabled application to service.',
+        usage: ['enable [app|directory] [--control-url <url>] [--json]'], helpOrder: 110,
+        outputProtocol: 'xeer.command.v0', effects: ['network-read', 'network-write', 'production-change'],
+        idempotent: true, reversible: true, destructive: false,
+        humanPrerequisites: ['A human must authorize restoring the production application.'],
+        pathPolicy: 'project-or-url', surfaces: { cli: true, mcpExclusion: NOT_EXPOSED_V0 },
+    },
+    {
+        id: 'delete', command: ['delete'], summary: 'Permanently delete an application and all of its data.',
+        usage: ['delete [app|directory] --confirm <application> [--control-url <url>] [--json]'], helpOrder: 120,
+        outputProtocol: 'xeer.command.v0', effects: ['network-read', 'network-write', 'write-state', 'production-change'],
+        idempotent: false, reversible: false, destructive: true,
+        humanPrerequisites: ['A human must provide the exact application name as irreversible confirmation.'],
+        pathPolicy: 'project-or-url', surfaces: { cli: true, mcpExclusion: NOT_EXPOSED_V0 },
+    },
+    {
+        id: 'domains.add', command: ['domains', 'add'], summary: 'Attach a customer-owned hostname to an application.',
+        usage: ['domains add <hostname> [app|directory] [--control-url <url>] [--json]'], helpOrder: 125,
+        outputProtocol: 'xeer.command.v0', effects: ['network-read', 'network-write', 'production-change'],
+        idempotent: true, reversible: true, destructive: false,
+        humanPrerequisites: ['A human must control the hostname DNS and authorize production routing.'],
+        pathPolicy: 'project-or-url', surfaces: { cli: true, mcpExclusion: NOT_EXPOSED_V0 },
+    },
+    {
+        id: 'domains.ls', command: ['domains', 'ls'], aliases: [['domains', 'list']],
+        summary: 'List an application\'s platform and custom domains.',
+        usage: ['domains ls [app|directory] [--control-url <url>] [--json]'], helpOrder: 126,
+        outputProtocol: 'xeer.command.v0', effects: ['network-read'], idempotent: true,
+        reversible: true, destructive: false, humanPrerequisites: [], pathPolicy: 'project-or-url',
+        surfaces: { cli: true, mcpExclusion: NOT_EXPOSED_V0 },
+    },
+    {
+        id: 'domains.status', command: ['domains', 'status'], summary: 'Refresh hostname and certificate validation.',
+        usage: ['domains status <hostname> [app|directory] [--control-url <url>] [--json]'], helpOrder: 127,
+        outputProtocol: 'xeer.command.v0', effects: ['network-read', 'network-write', 'production-change'], idempotent: true,
+        reversible: true, destructive: false,
+        humanPrerequisites: ['A human must control the hostname DNS and authorize activating production routing.'],
+        pathPolicy: 'project-or-url',
+        surfaces: { cli: true, mcpExclusion: NOT_EXPOSED_V0 },
+    },
+    {
+        id: 'domains.remove', command: ['domains', 'remove'], aliases: [['domains', 'rm']],
+        summary: 'Detach a custom hostname and delete its provider certificate.',
+        usage: ['domains remove <hostname> [app|directory] [--control-url <url>] [--json]'], helpOrder: 128,
+        outputProtocol: 'xeer.command.v0', effects: ['network-read', 'network-write', 'production-change'],
+        idempotent: true, reversible: true, destructive: true,
+        humanPrerequisites: ['A human must authorize removing production routing for the hostname.'],
+        pathPolicy: 'project-or-url', surfaces: { cli: true, mcpExclusion: NOT_EXPOSED_V0 },
+    },
+    {
+        id: 'preview', command: ['preview'], summary: 'Run a verified artifact in a local preview server.',
+        usage: ['preview [directory] [--host <host>] [--port <port>] [--json]'], helpOrder: 240,
+        outputProtocol: 'xeer.dev.v0', effects: ['read-source', 'write-generated', 'run-local', 'write-state'],
+        idempotent: false, reversible: true, destructive: false, humanPrerequisites: [],
+        pathPolicy: 'project-relative', surfaces: { cli: true, mcpExclusion: NOT_EXPOSED_V0 },
+    },
+    {
+        id: 'state.read', command: ['state'], summary: 'Read record counts from a running application.',
+        usage: ['state <local-url|app> [--environment prod|preview] [--control-url <url>] [--json]'], helpOrder: 260,
+        outputProtocol: 'xeer.command.v0', effects: ['network-read', 'read-state'], idempotent: true,
+        reversible: true, destructive: false, humanPrerequisites: [], pathPolicy: 'app-or-url',
+        surfaces: { cli: true, mcpExclusion: NOT_EXPOSED_V0 },
+    },
+    {
+        id: 'state.reset', command: ['state', 'reset'], summary: 'Permanently reset local environment state.',
+        usage: ['state reset [directory] --state <dev|preview|test> --confirm <application> [--json]'], helpOrder: 270,
+        outputProtocol: 'xeer.command.v0', effects: ['read-source', 'write-state'], idempotent: false,
+        reversible: false, destructive: true,
+        humanPrerequisites: ['A human must provide the exact application name as destructive confirmation.'],
+        pathPolicy: 'project-relative', surfaces: { cli: true, mcpExclusion: DESTRUCTIVE_STATE },
+    },
+    {
+        id: 'logs', command: ['logs'], summary: 'Read the bounded log ring of a running application.',
+        usage: ['logs <local-url|app> [--environment prod|preview] [--after <cursor>] [--control-url <url>] [--json]'],
+        helpOrder: 280, outputProtocol: 'xeer.command.v0', effects: ['network-read', 'read-state'],
+        idempotent: true, reversible: true, destructive: false, humanPrerequisites: [], pathPolicy: 'app-or-url',
+        surfaces: { cli: true, mcpExclusion: NOT_EXPOSED_V0 },
+    },
+    {
+        id: 'export', command: ['export'], summary: 'Export application state to a document.',
+        usage: [
+            'export <local-url|app> [--environment prod|preview] [--out <file>] [--control-url <url>] [--json]',
+            'export --state <dev|preview> [directory] [--out <file>] [--json]',
+        ],
+        helpOrder: 290, outputProtocol: 'xeer.command.v0', effects: ['network-read', 'read-state', 'write-file'],
+        idempotent: true, reversible: true, destructive: false, humanPrerequisites: [],
+        pathPolicy: 'project-or-url', surfaces: { cli: true, mcpExclusion: NOT_EXPOSED_V0 },
+    },
+    {
+        id: 'import', command: ['import'], summary: 'Replace local or preview state from an export document.',
+        usage: [
+            'import <preview-url> <file> [--json]',
+            'import --state <dev|preview> [directory] <file> [--json]',
+        ],
+        helpOrder: 300, outputProtocol: 'xeer.command.v0',
+        effects: ['read-source', 'network-write', 'write-state'], idempotent: false,
+        reversible: false, destructive: true,
+        humanPrerequisites: ['A human must choose the export document that replaces existing state.'],
+        pathPolicy: 'project-or-url', surfaces: { cli: true, mcpExclusion: DESTRUCTIVE_STATE },
+    },
+    {
+        id: 'auth.login', command: ['auth', 'login'], summary: 'Establish a human builder credential.',
+        usage: ['auth login [--control-url <url>] [--no-open] [--json]'], helpOrder: 170,
+        outputProtocol: 'xeer.command.v0', effects: ['network-read', 'network-write', 'secret-write'],
+        idempotent: false, reversible: true, destructive: false,
+        humanPrerequisites: ['A human must approve the exact browser verification code.'],
+        pathPolicy: 'none', surfaces: { cli: true, mcpExclusion: HUMAN_IDENTITY },
+    },
+    {
+        id: 'auth.logout', command: ['auth', 'logout'], summary: 'Remove the local builder credential.',
+        usage: ['auth logout [--control-url <url>] [--json]'], helpOrder: 190,
+        outputProtocol: 'xeer.command.v0', effects: ['network-write', 'secret-write'], idempotent: true,
+        reversible: true, destructive: false, humanPrerequisites: [], pathPolicy: 'none',
+        surfaces: { cli: true, mcpExclusion: HUMAN_IDENTITY },
+    },
+    {
+        id: 'auth.as', command: ['auth', 'as'], summary: 'Select a deterministic local development persona.',
+        usage: ['auth as <alice|bob> [directory] [--workspace <id>]... [--json]'], helpOrder: 200,
+        outputProtocol: 'xeer.command.v0', effects: ['write-state'], idempotent: true,
+        reversible: true, destructive: false, humanPrerequisites: [], pathPolicy: 'project-relative',
+        surfaces: { cli: true, mcpExclusion: NOT_EXPOSED_V0 },
+    },
+    {
+        id: 'auth.clear', command: ['auth', 'clear'], summary: 'Reset the local development persona.',
+        usage: ['auth clear [directory] [--json]'], helpOrder: 210,
+        outputProtocol: 'xeer.command.v0', effects: ['write-state'], idempotent: true,
+        reversible: true, destructive: false, humanPrerequisites: [], pathPolicy: 'project-relative',
+        surfaces: { cli: true, mcpExclusion: NOT_EXPOSED_V0 },
+    },
+    {
+        id: 'env.set', command: ['env', 'set'], summary: 'Set an environment value or secret.',
+        usage: ['env set <NAME> [value] [--environment prod|preview|dev] [--dir <directory>] [--control-url <url>] [--json]'],
+        helpOrder: 130,
+        outputProtocol: 'xeer.command.v0', effects: ['network-write', 'write-state', 'secret-write'],
+        idempotent: true, reversible: true, destructive: false,
+        humanPrerequisites: ['A human must deliberately provide the secret value.'],
+        pathPolicy: 'project-relative', surfaces: { cli: true, mcpExclusion: SECRET_VALUES },
+    },
+    {
+        id: 'env.ls', command: ['env', 'ls'], aliases: [['env', 'list']],
+        summary: 'List environment variable names and metadata.',
+        usage: ['env ls [--environment prod|preview|dev] [--dir <directory>] [--control-url <url>] [--json]'],
+        helpOrder: 140,
+        outputProtocol: 'xeer.command.v0', effects: ['network-read', 'secret-metadata'], idempotent: true,
+        reversible: true, destructive: false, humanPrerequisites: [], pathPolicy: 'project-relative',
+        surfaces: { cli: true, mcpExclusion: SECRET_VALUES },
+    },
+    {
+        id: 'env.rm', command: ['env', 'rm'], aliases: [['env', 'remove']],
+        summary: 'Remove an environment value or secret.',
+        usage: ['env rm <NAME> [--environment prod|preview|dev] [--dir <directory>] [--control-url <url>] [--json]'],
+        helpOrder: 150,
+        outputProtocol: 'xeer.command.v0', effects: ['network-write', 'write-state', 'secret-write'],
+        idempotent: true, reversible: false, destructive: true,
+        humanPrerequisites: ['A human must choose the secret name to remove.'],
+        pathPolicy: 'project-relative', surfaces: { cli: true, mcpExclusion: SECRET_VALUES },
+    },
+    {
+        id: 'env.pull', command: ['env', 'pull'], summary: 'Write development secrets to a local file.',
+        usage: ['env pull [--environment prod|preview|dev] [--dir <directory>] [--control-url <url>] [--json]'],
+        helpOrder: 160,
+        outputProtocol: 'xeer.command.v0', effects: ['network-read', 'write-file', 'secret-read'],
+        idempotent: true, reversible: true, destructive: false,
+        humanPrerequisites: ['A human must authorize writing plaintext secrets to the checkout.'],
+        pathPolicy: 'project-relative', surfaces: { cli: true, mcpExclusion: SECRET_VALUES },
+    },
+    {
+        id: 'token.create', command: ['token', 'create'], summary: 'Issue a service builder token.',
+        usage: ['token create --name <label> [--control-url <url>] [--json]'], hiddenFromHelp: true,
+        outputProtocol: 'xeer.command.v0', effects: ['network-write', 'secret-write'], idempotent: false,
+        reversible: true, destructive: false,
+        humanPrerequisites: ['A human service builder must store the one-time plaintext token securely.'],
+        pathPolicy: 'none', surfaces: { cli: true, mcpExclusion: SERVICE_CREDENTIALS },
+    },
+    {
+        id: 'token.ls', command: ['token', 'ls'], aliases: [['token', 'list']],
+        summary: 'List service token metadata.', usage: ['token ls [--control-url <url>] [--json]'],
+        hiddenFromHelp: true, outputProtocol: 'xeer.command.v0', effects: ['network-read', 'secret-metadata'],
+        idempotent: true, reversible: true, destructive: false, humanPrerequisites: [], pathPolicy: 'none',
+        surfaces: { cli: true, mcpExclusion: SERVICE_CREDENTIALS },
+    },
+    {
+        id: 'token.revoke', command: ['token', 'revoke'], summary: 'Revoke a service builder token.',
+        usage: ['token revoke <tokenId> [--reason <why>] [--control-url <url>] [--json]'], hiddenFromHelp: true,
+        outputProtocol: 'xeer.command.v0', effects: ['network-write', 'secret-write'], idempotent: true,
+        reversible: false, destructive: true,
+        humanPrerequisites: ['A human service builder must choose the credential to revoke.'],
+        pathPolicy: 'none', surfaces: { cli: true, mcpExclusion: SERVICE_CREDENTIALS },
+    },
+    {
+        id: 'actions', command: ['actions'], summary: 'Print the machine-readable action and safety catalogue.',
+        usage: ['actions [--json]'], helpOrder: 310, outputProtocol: 'xeer.command.v0', effects: [],
+        idempotent: true, reversible: true, destructive: false, humanPrerequisites: [], pathPolicy: 'none',
+        surfaces: { cli: true, mcpExclusion: NOT_EXPOSED_V0 },
+    },
+    {
+        id: 'db.tables', command: ['db', 'tables'], summary: 'List the tables of a running application database.',
+        usage: ['db tables [directory] [--state <dev|preview>] [--json]'], helpOrder: 320,
+        outputProtocol: 'xeer.command.v0', effects: ['read-state'], idempotent: true, reversible: true,
+        destructive: false, humanPrerequisites: [], pathPolicy: 'project-relative',
+        surfaces: { cli: true, mcpExclusion: NOT_EXPOSED_V0 },
+    },
+    {
+        id: 'db.schema', command: ['db', 'schema'], summary: 'Print the declared schema of a running application database.',
+        usage: ['db schema [directory] [--state <dev|preview>] [--json]'], helpOrder: 330,
+        outputProtocol: 'xeer.command.v0', effects: ['read-state'], idempotent: true, reversible: true,
+        destructive: false, humanPrerequisites: [], pathPolicy: 'project-relative',
+        surfaces: { cli: true, mcpExclusion: NOT_EXPOSED_V0 },
+    },
+    {
+        // Not idempotent and not reversible, because `--write` admits UPDATE and DELETE and the action
+        // catalogue describes what an invocation may do rather than what a particular statement does.
+        // `destructive: false` all the same: a destructive action here is one that discards state
+        // wholesale, and this refuses DDL outright — the worst a statement can do is edit rows the
+        // schema still constrains.
+        id: 'db.exec', command: ['db', 'exec'], summary: 'Run one SQL statement against a running application database.',
+        usage: ['db exec [directory] <sql> [--state <dev|preview>] [--write] [--json]'], helpOrder: 340,
+        outputProtocol: 'xeer.command.v0', effects: ['read-state', 'write-state'], idempotent: false,
+        reversible: false, destructive: false,
+        humanPrerequisites: ['A human must pass --write before any statement that modifies rows.'],
+        pathPolicy: 'project-relative', surfaces: { cli: true, mcpExclusion: DESTRUCTIVE_STATE },
+    },
+];
+export const XEER_ACTIONS = Object.freeze(actions);
+export function actionDefinition(id) {
+    return XEER_ACTIONS.find((action) => action.id === id);
+}
+export function mcpActions(profile) {
+    return XEER_ACTIONS.filter((action) => action.surfaces.mcpTool
+        && action.surfaces.mcpProfiles?.includes(profile));
+}
+export function cliHelpActions() {
+    return XEER_ACTIONS
+        .filter((action) => action.surfaces.cli && !action.hiddenFromHelp)
+        .sort((left, right) => (left.helpOrder ?? Number.MAX_SAFE_INTEGER) - (right.helpOrder ?? Number.MAX_SAFE_INTEGER));
+}
+/**
+ * Extract the CLI option contract from the same usage strings that generate `xeer --help`.
+ * An option followed by a documented value token takes one; a closing bracket or end-of-line
+ * denotes a boolean flag. Keeping this derived means help, dispatch validation, and aliases cannot
+ * acquire separate hand-maintained allowlists.
+ */
+export function cliOptionDefinitions(action) {
+    const definitions = new Map();
+    for (const usage of action.usage) {
+        for (const match of usage.matchAll(/--[a-z][a-z-]*/gu)) {
+            const name = match[0];
+            const tail = usage.slice((match.index ?? 0) + name.length);
+            const takesValue = /^[ \t]+(?:<|[A-Za-z0-9{])/u.test(tail);
+            const existing = definitions.get(name);
+            if (existing !== undefined && existing !== takesValue) {
+                throw new Error(`CLI option ${name} has inconsistent usage in ${action.id}.`);
+            }
+            definitions.set(name, takesValue);
+        }
+    }
+    return [...definitions].map(([name, takesValue]) => ({ name, takesValue }));
+}
+/** Resolves canonical and alias command prefixes, preferring `state reset` over the `state` target action. */
+export function cliActionForTokens(tokens) {
+    let result;
+    let matchedLength = -1;
+    for (const action of XEER_ACTIONS) {
+        if (!action.surfaces.cli)
+            continue;
+        for (const command of [action.command, ...(action.aliases ?? [])]) {
+            if (command.length <= matchedLength)
+                continue;
+            if (command.every((token, index) => tokens[index] === token)) {
+                result = action;
+                matchedLength = command.length;
+            }
+        }
+    }
+    return result;
+}
+const WRITE_EFFECTS = new Set([
+    'write-source', 'write-file', 'write-generated', 'run-local', 'write-state', 'network-write',
+    'production-change', 'secret-write',
+]);
+export function mcpAnnotations(action) {
+    return Object.freeze({
+        readOnlyHint: !action.effects.some((effect) => WRITE_EFFECTS.has(effect)),
+        destructiveHint: action.destructive,
+        idempotentHint: action.idempotent,
+        openWorldHint: action.effects.includes('network-read') || action.effects.includes('network-write'),
+    });
+}
+/** Exact Draft-07 object the MCP SDK must advertise for a registered tool. */
+export function mcpInputJsonSchema(action) {
+    const schema = action.surfaces.mcpInputSchema;
+    if (!schema)
+        return undefined;
+    return Object.freeze({ ...schema, $schema: MCP_INPUT_SCHEMA_DRAFT });
+}
+export const ACTION_REFERENCE_START = '<!-- xeer-action-reference:start -->';
+export const ACTION_REFERENCE_END = '<!-- xeer-action-reference:end -->';
+export const ACTION_REFERENCE_TARGETS = [
+    'docs/AGENTS.md',
+    'packages/website/content/guides/agents.md',
+    '.agents/skills/xeer/SKILL.md',
+    'packages/mcp/README.md',
+    'packages/website/content/reference/cli.md',
+];
+function code(value) {
+    return `\`${String(value).replaceAll('|', '\\|')}\``;
+}
+function effects(action) {
+    return action.effects.length === 0 ? 'none' : action.effects.map(code).join('<br>');
+}
+function safety(action) {
+    const annotations = mcpAnnotations(action);
+    return [
+        annotations.readOnlyHint ? 'read-only' : 'writes',
+        action.idempotent ? 'idempotent' : 'non-idempotent',
+        action.reversible ? 'reversible' : 'irreversible',
+        action.destructive ? 'destructive' : 'non-destructive',
+    ].join('; ');
+}
+function inputs(action) {
+    const schema = action.surfaces.mcpInputSchema;
+    if (!schema || Object.keys(schema.properties).length === 0)
+        return 'none';
+    const required = new Set(schema.required ?? []);
+    return Object.entries(schema.properties).map(([name, property]) => {
+        const kind = property.enum
+            ? property.enum.map(code).join(' / ')
+            : code(property.type);
+        const bounds = property.minimum === undefined && property.maximum === undefined
+            ? ''
+            : ` [${property.minimum ?? '-inf'}..${property.maximum ?? 'inf'}]`;
+        const fallback = property.default === undefined ? '' : `; default ${code(property.default)}`;
+        return `${code(`${name}${required.has(name) ? '' : '?'}`)}: ${kind}${bounds}${fallback}`;
+    }).join('<br>');
+}
+function prerequisites(action) {
+    return action.humanPrerequisites.length === 0
+        ? 'none'
+        : action.humanPrerequisites.map((value) => value.replaceAll('|', '\\|')).join('<br>');
+}
+/** One generated block is embedded in every agent-facing action-policy surface. */
+export function renderActionReference() {
+    const mcp = XEER_ACTIONS.filter((action) => action.surfaces.mcpTool);
+    const authorCount = mcpActions('author').length;
+    const operatorCount = mcpActions('operator').length;
+    const excluded = XEER_ACTIONS.filter((action) => action.surfaces.cli && !action.surfaces.mcpTool);
+    return [
+        ACTION_REFERENCE_START,
+        '<!-- Generated from packages/spec/src/actions.ts by `pnpm generate:agent-reference`. Do not edit. -->',
+        '',
+        `**MCP tools (${mcp.length} total; ${authorCount} author, ${operatorCount} operator).** `
+            + 'Inputs ending in `?` are optional.',
+        '',
+        '| Tool | Action | Profiles | Summary | Inputs | Effects | Safety | Path policy | Output | Human prerequisite |',
+        '| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |',
+        ...mcp.map((action) => `| ${code(action.surfaces.mcpTool)} | ${code(action.id)} | `
+            + `${action.surfaces.mcpProfiles.map(code).join(' / ')} | `
+            + `${action.summary.replaceAll('|', '\\|')} | ${inputs(action)} | `
+            + `${effects(action)} | ${safety(action)} | ${code(action.pathPolicy)} | ${code(action.outputProtocol)} | `
+            + `${prerequisites(action)} |`),
+        '',
+        `**CLI actions intentionally excluded from MCP (${excluded.length}).**`,
+        '',
+        '| CLI action | Action | Summary | Effects | Safety | Path policy | Output | Why no MCP tool |',
+        '| --- | --- | --- | --- | --- | --- | --- | --- |',
+        ...excluded.map((action) => `| ${code(`xeer ${action.command.join(' ')}`)} | ${code(action.id)} | ${action.summary.replaceAll('|', '\\|')} | `
+            + `${effects(action)} | ${safety(action)} | ${code(action.pathPolicy)} | ${code(action.outputProtocol)} | `
+            + `${action.surfaces.mcpExclusion.replaceAll('|', '\\|')} |`),
+        ACTION_REFERENCE_END,
+    ].join('\n');
+}