@impetik/xeer-mcp 0.2.29 → 0.2.32

package/README.md

@@ -63,7 +63,7 @@ The generated registry is the complete MCP tool and exclusion surface:
 | `xeer_check` | `check` | `author` / `operator` | Validate a project and report structured diagnostics. | `directory?`: `string` | `read-source`<br>`write-generated` | writes; idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | none |
 | `xeer_build` | `build` | `author` / `operator` | Build and verify a content-addressed project artifact. | `directory?`: `string` | `read-source`<br>`write-generated`<br>`run-local` | writes; idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | none |
 | `xeer_test` | `test` | `author` / `operator` | Run the project test suite and record review evidence. | `directory?`: `string`<br>`timeoutMilliseconds?`: `integer` [1000..1800000] | `read-source`<br>`write-generated`<br>`run-local`<br>`write-state` | writes; idempotent; reversible; non-destructive | `project-relative` | `xeer.dev.v0` | none |
-| `xeer_new` | `new` | `author` / `operator` | Create a new project from a supported scaffold. | `directory`: `string`<br>`template?`: `string`<br>`framework?`: `sveltekit`<br>`ui?`: `preact` / `react` | `write-source`<br>`network-read` | writes; non-idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | none |
+| `xeer_new` | `new` | `author` / `operator` | Create a new project from a supported scaffold. | `directory`: `string`<br>`template?`: `string`<br>`framework?`: `sveltekit` / `astro`<br>`ui?`: `preact` / `react` | `write-source`<br>`network-read` | writes; non-idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | none |
 | `xeer_agent_context` | `agent.context` | `author` / `operator` | Read normalized project facts, operations, diagnostics, tests, and safe next actions. | `directory?`: `string` | `read-source` | read-only; idempotent; reversible; non-destructive | `project-relative` | `xeer.agent-context.v0` | none |
 | `xeer_docs_search` | `docs.search` | `author` / `operator` | Search the installed-version Xeer documentation index. | `query`: `string`<br>`limit?`: `integer` [1..20]; default `5` | none | read-only; idempotent; reversible; non-destructive | `none` | `xeer.docs-search.v0` | none |
 | `xeer_doctor` | `doctor` | `author` / `operator` | Diagnose the toolchain and generated project state. | `directory?`: `string` | `read-source`<br>`write-generated` | writes; idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | none |
@@ -76,11 +76,12 @@ The generated registry is the complete MCP tool and exclusion surface:
 | `xeer_dev_stop` | `dev.stop` | `author` / `operator` | Stop a local development session and release its lease. | `sessionId?`: `string`<br>`cursor?`: `integer` [0..9007199254740991]; default `0` | `run-local` | writes; idempotent; reversible; non-destructive | `none` | `xeer.dev.v0` | none |
 | `xeer_diagnostics` | `diagnostics` | `author` / `operator` | Explain one emitted diagnostic code. | `code`: `string` | none | read-only; idempotent; reversible; non-destructive | `none` | `xeer.command.v0` | none |
 
-**CLI actions intentionally excluded from MCP (36).**
+**CLI actions intentionally excluded from MCP (39).**
 
 | CLI action | Action | Summary | Effects | Safety | Path policy | Output | Why no MCP tool |
 | --- | --- | --- | --- | --- | --- | --- | --- |
-| `xeer init` | `init` | Initialize Xeer in an existing SvelteKit project. | `read-source`<br>`write-source`<br>`run-local`<br>`network-read` | writes; idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | Not exposed through MCP v0; use the CLI deliberately. |
+| `xeer init` | `init` | Initialize Xeer in an existing SvelteKit or Astro project. | `read-source`<br>`write-source`<br>`run-local`<br>`network-read` | writes; idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | Not exposed through MCP v0; use the CLI deliberately. |
+| `xeer bootstrap` | `bootstrap` | Open owner-only EmDash setup for a deployed Astro project. | `read-source`<br>`network-read`<br>`network-write` | writes; non-idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | Not exposed through MCP v0; use the CLI deliberately. |
 | `xeer agent setup` | `agent.setup` | Install or verify project-confined agent adapters. | `read-source`<br>`write-source` | writes; idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | Not exposed through MCP v0; use the CLI deliberately. |
 | `xeer deploy` | `deploy` | Build and deploy a project artifact. | `read-source`<br>`write-generated`<br>`run-local`<br>`network-read`<br>`network-write`<br>`production-change` | writes; non-idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | MCP exposes a separate preview-only deploy action; direct production deploy stays CLI-only. |
 | `xeer promote` | `promote` | Promote a preview artifact to production. | `network-read`<br>`network-write`<br>`production-change` | writes; non-idempotent; reversible; non-destructive | `project-or-url` | `xeer.command.v0` | MCP promotion is a separate action available only when the server starts in operator profile. |
@@ -115,7 +116,9 @@ The generated registry is the complete MCP tool and exclusion surface:
 | `xeer actions` | `actions` | Print the machine-readable action and safety catalogue. | none | read-only; idempotent; reversible; non-destructive | `none` | `xeer.command.v0` | Not exposed through MCP v0; use the CLI deliberately. |
 | `xeer db tables` | `db.tables` | List the tables of a running application database. | `read-state` | read-only; idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | Not exposed through MCP v0; use the CLI deliberately. |
 | `xeer db schema` | `db.schema` | Print the declared schema of a running application database. | `read-state` | read-only; idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | Not exposed through MCP v0; use the CLI deliberately. |
-| `xeer db exec` | `db.exec` | Run one SQL statement against a running application database. | `read-state`<br>`write-state` | writes; non-idempotent; irreversible; non-destructive | `project-relative` | `xeer.command.v0` | Destructive state replacement requires an explicit CLI invocation. |
+| `xeer db exec` | `db.exec` | Run SQL against a running or deployed application database. | `read-state`<br>`write-state`<br>`network-read`<br>`network-write` | writes; non-idempotent; irreversible; destructive | `project-relative` | `xeer.command.v0` | Destructive state replacement requires an explicit CLI invocation. |
+| `xeer db bookmark` | `db.bookmark` | Print the current Time Travel bookmark of a deployed application database. | `network-read` | read-only; idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | Not exposed through MCP v0; use the CLI deliberately. |
+| `xeer db restore` | `db.restore` | Restore a deployed application database to a bookmark or a time. | `network-write`<br>`write-state` | writes; non-idempotent; reversible; destructive | `project-relative` | `xeer.command.v0` | Destructive state replacement requires an explicit CLI invocation. |
 <!-- xeer-action-reference:end -->
 
 Every tool returns `{ protocol: "xeer.mcp-result.v0", action, ok, result?, error? }` both as

package/dist/dev-session.d.ts

@@ -25,6 +25,10 @@ export type DevSessionStatus = 'starting' | 'ready' | 'compile_failed' | 'stoppe
  */
 export interface PreviewUrls {
     url: string;
+    /** A framework project's framework, `sveltekit` or `astro`; absent for a Xeer application. */
+    framework?: string;
+    /** An EmDash project's local admin, on `localhost` because passkeys refuse an IP address. */
+    adminUrl?: string;
     healthUrl?: string;
     inspectorUrl?: string;
     debugUrl?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@impetik/xeer-mcp",
-  "version": "0.2.29",
+  "version": "0.2.32",
   "type": "module",
   "description": "Model Context Protocol server for Xeer project context, diagnostics, scaffold, check, test, dev, build, and preview deployment.",
   "license": "MIT",
@@ -47,7 +47,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.0.10",
-    "@impetik/xeer": "0.2.29"
+    "@impetik/xeer": "0.2.32"
   },
   "devDependencies": {
     "@types/node": "^24.1.0"

package/vendor/spec/actions.d.ts

@@ -194,7 +194,7 @@ declare const actions: readonly [{
     readonly command: readonly ["new"];
     readonly summary: "Create a new project from a supported scaffold.";
     readonly description: string;
-    readonly usage: readonly ["new [directory] [--template <id>] [--framework sveltekit] [--ui preact|react] [--json]"];
+    readonly usage: readonly ["new [directory] [--template <id>] [--framework sveltekit|astro] [--ui preact|react] [--json]"];
     readonly helpOrder: 30;
     readonly outputProtocol: "xeer.command.v0";
     readonly effects: readonly ["write-source", "network-read"];
@@ -218,7 +218,7 @@ declare const actions: readonly [{
                 readonly framework: {
                     readonly description: string;
                     readonly type: "string";
-                    readonly enum: readonly ["sveltekit"];
+                    readonly enum: readonly ["sveltekit", "astro"];
                 };
                 readonly ui: {
                     readonly description: string;
@@ -237,7 +237,7 @@ declare const actions: readonly [{
 }, {
     readonly id: "init";
     readonly command: readonly ["init"];
-    readonly summary: "Initialize Xeer in an existing SvelteKit project.";
+    readonly summary: "Initialize Xeer in an existing SvelteKit or Astro project.";
     readonly description: string;
     readonly usage: readonly ["init [directory] [--dry-run] [--json]"];
     readonly helpOrder: 32;
@@ -252,6 +252,24 @@ declare const actions: readonly [{
         readonly cli: true;
         readonly mcpExclusion: "Not exposed through MCP v0; use the CLI deliberately.";
     };
+}, {
+    readonly id: "bootstrap";
+    readonly command: readonly ["bootstrap"];
+    readonly summary: "Open owner-only EmDash setup for a deployed Astro project.";
+    readonly description: string;
+    readonly usage: readonly ["bootstrap [directory] [--environment prod|preview] [--control-url <url>] [--no-open] [--json]"];
+    readonly helpOrder: 51;
+    readonly outputProtocol: "xeer.command.v0";
+    readonly effects: readonly ["read-source", "network-read", "network-write"];
+    readonly idempotent: false;
+    readonly reversible: true;
+    readonly destructive: false;
+    readonly humanPrerequisites: readonly [string];
+    readonly pathPolicy: "project-relative";
+    readonly surfaces: {
+        readonly cli: true;
+        readonly mcpExclusion: "Not exposed through MCP v0; use the CLI deliberately.";
+    };
 }, {
     readonly id: "agent.setup";
     readonly command: readonly ["agent", "setup"];
@@ -1247,15 +1265,52 @@ declare const actions: readonly [{
 }, {
     readonly id: "db.exec";
     readonly command: readonly ["db", "exec"];
-    readonly summary: "Run one SQL statement against a running application database.";
-    readonly usage: readonly ["db exec [directory] <sql> [--state <dev|preview>] [--write] [--json]"];
+    readonly summary: "Run SQL against a running or deployed application database.";
+    readonly description: string;
+    readonly usage: readonly ["db exec [directory] <sql> [--state <dev|preview>] [--write] [--json]", "db exec [directory] <sql> --remote --environment <prod|preview> [--param <value>]... [--control-url <url>] [--json]", "db exec [directory] --remote --environment <prod|preview> --file <batch.json> [--control-url <url>] [--json]"];
     readonly helpOrder: 340;
     readonly outputProtocol: "xeer.command.v0";
-    readonly effects: readonly ["read-state", "write-state"];
+    readonly effects: readonly ["read-state", "write-state", "network-read", "network-write"];
     readonly idempotent: false;
     readonly reversible: false;
+    readonly destructive: true;
+    readonly humanPrerequisites: readonly ["Locally, a human must pass --write before any statement that modifies rows.", string];
+    readonly pathPolicy: "project-relative";
+    readonly surfaces: {
+        readonly cli: true;
+        readonly mcpExclusion: "Destructive state replacement requires an explicit CLI invocation.";
+    };
+}, {
+    readonly id: "db.bookmark";
+    readonly command: readonly ["db", "bookmark"];
+    readonly summary: "Print the current Time Travel bookmark of a deployed application database.";
+    readonly description: string;
+    readonly usage: readonly ["db bookmark [directory] --remote --environment <prod|preview> [--control-url <url>] [--json]"];
+    readonly helpOrder: 345;
+    readonly outputProtocol: "xeer.command.v0";
+    readonly effects: readonly ["network-read"];
+    readonly idempotent: true;
+    readonly reversible: true;
     readonly destructive: false;
-    readonly humanPrerequisites: readonly ["A human must pass --write before any statement that modifies rows."];
+    readonly humanPrerequisites: readonly [string];
+    readonly pathPolicy: "project-relative";
+    readonly surfaces: {
+        readonly cli: true;
+        readonly mcpExclusion: "Not exposed through MCP v0; use the CLI deliberately.";
+    };
+}, {
+    readonly id: "db.restore";
+    readonly command: readonly ["db", "restore"];
+    readonly summary: "Restore a deployed application database to a bookmark or a time.";
+    readonly description: string;
+    readonly usage: readonly ["db restore [directory] --remote --environment <prod|preview> --to <bookmark|time> [--control-url <url>] [--json]"];
+    readonly helpOrder: 346;
+    readonly outputProtocol: "xeer.command.v0";
+    readonly effects: readonly ["network-write", "write-state"];
+    readonly idempotent: false;
+    readonly reversible: true;
+    readonly destructive: true;
+    readonly humanPrerequisites: readonly [string];
     readonly pathPolicy: "project-relative";
     readonly surfaces: {
         readonly cli: true;

package/vendor/spec/actions.js

@@ -1,6 +1,6 @@
 /** Stable protocol for the action catalogue consumed by CLI, MCP, and agent context surfaces. */
 import { REVIEW_RECEIPT_ID_SOURCE } from './review.js';
-import { FRAMEWORK_NAMES } from './scaffold-names.js';
+import { SCAFFOLDABLE_FRAMEWORK_NAMES } from './scaffold-names.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}$';
@@ -17,7 +17,7 @@ export const XEER_CLI_COMMAND_GROUPS = Object.freeze([
     { command: 'state', summary: 'Inspect running application state or reset local state.' },
     { command: 'env', summary: 'Manage application environment values and secrets.' },
     { command: 'token', summary: 'Manage service builder tokens.' },
-    { command: 'db', summary: 'Inspect and query a running application database.' },
+    { command: 'db', summary: 'Inspect, query and restore a running or deployed application database.' },
 ]);
 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.';
@@ -216,12 +216,14 @@ const actions = [
             + 'scaffold sign-in UI: every visitor already has a verified identity, and the generated README '
             + 'explains how to opt in to a persistent account. The four bundled starter names resolve '
             + 'offline and accept `--ui`; every other exact template id resolves through the public catalog '
-            + 'and owns its renderer. `--framework sveltekit` writes a framework '
-            + 'project instead: SvelteKit owns the renderer and the routes, Xeer owns `xeer.config.json` '
-            + 'and the deployment, so `result.framework` replaces both fields, `--ui` does not apply and '
-            + 'is refused with `XE3004`, and `--template` alongside it is `XE3005`. To adopt a framework '
+            + 'and owns its renderer. `--template emdash` is the bundled EmDash blog: a complete Astro '
+            + 'framework project that resolves offline, declares `integration: "emdash"`, and refuses `--ui` '
+            + 'with `XE3013`. `--framework sveltekit|astro` writes a plain framework project instead: the '
+            + 'framework owns the renderer and the routes, Xeer owns `xeer.config.json` and the '
+            + 'deployment, so `result.framework` replaces both fields, `--ui` does not apply and is '
+            + 'refused with `XE3004`, and `--template` alongside it is `XE3005`. To adopt a framework '
             + 'project that already exists, use `xeer init` rather than this command.',
-        usage: ['new [directory] [--template <id>] [--framework sveltekit] [--ui preact|react] [--json]'],
+        usage: ['new [directory] [--template <id>] [--framework sveltekit|astro] [--ui preact|react] [--json]'],
         helpOrder: 30,
         outputProtocol: 'xeer.command.v0', effects: ['write-source', 'network-read'], idempotent: false,
         reversible: true, destructive: false, humanPrerequisites: [], pathPolicy: 'project-relative',
@@ -235,15 +237,16 @@ const actions = [
                         type: 'string', description: 'Target directory, relative to the server root. Must be empty or absent.',
                     },
                     template: {
-                        description: 'A bundled starter name or exact template catalog id. Defaults to notes. '
-                            + 'Bundled starters resolve offline. Exclusive with framework, which is refused with XE3005.',
+                        description: 'A bundled starter name, the bundled emdash framework template, or an exact template '
+                            + 'catalog id. Defaults to notes. Bundled names resolve offline. Exclusive with framework, '
+                            + 'which is refused with XE3005.',
                         type: 'string',
                     },
                     framework: {
                         description: 'Scaffold a fresh project for this framework instead of a Xeer '
                             + 'application: it declares xeer.config.json, owns its own renderer and routes, and '
                             + 'delegates check, dev, test, and build to its package scripts. Exclusive with template and ui.',
-                        type: 'string', enum: FRAMEWORK_NAMES,
+                        type: 'string', enum: SCAFFOLDABLE_FRAMEWORK_NAMES,
                     },
                     ui: {
                         description: 'Which UI provider the written manifest selects. Defaults to preact, and '
@@ -257,7 +260,7 @@ const actions = [
         },
     },
     {
-        id: 'init', command: ['init'], summary: 'Initialize Xeer in an existing SvelteKit project.',
+        id: 'init', command: ['init'], summary: 'Initialize Xeer in an existing SvelteKit or Astro project.',
         description: 'Detects an existing SvelteKit project, runs Wrangler setup when Cloudflare is not '
             + 'configured, preserves the project\'s native dev/check/test/build scripts and application '
             + 'source, and creates the Xeer framework configuration. Use --dry-run to inspect the '
@@ -267,6 +270,19 @@ const actions = [
         idempotent: true, reversible: true, destructive: false, humanPrerequisites: [],
         pathPolicy: 'project-relative', surfaces: { cli: true, mcpExclusion: NOT_EXPOSED_V0 },
     },
+    {
+        id: 'bootstrap', command: ['bootstrap'], summary: 'Open owner-only EmDash setup for a deployed Astro project.',
+        description: 'Verifies builder ownership, obtains a private setup grant, then polls the deployed '
+            + 'site\x27s read-only `GET /_emdash/api/setup/status` for up to 240 seconds so a cold EmDash '
+            + 'database can finish its migrations. A ready site returns `setup: "required"` with the private '
+            + 'setup URL, or `setup: "complete"` with the admin URL once an owner exists. If the site is '
+            + 'still initializing when the wait ends, the command exits 1 with `XE5135` and a '
+            + '`readiness: "pending"` result naming the retry command. `--json` never opens a browser.',
+        usage: ['bootstrap [directory] [--environment prod|preview] [--control-url <url>] [--no-open] [--json]'],
+        helpOrder: 51, outputProtocol: 'xeer.command.v0', effects: ['read-source', 'network-read', 'network-write'],
+        idempotent: false, reversible: true, destructive: false, humanPrerequisites: [BUILDER_CREDENTIAL],
+        pathPolicy: 'project-relative', surfaces: { cli: true, mcpExclusion: NOT_EXPOSED_V0 },
+    },
     {
         id: 'agent.setup', command: ['agent', 'setup'],
         summary: 'Install or verify project-confined agent adapters.',
@@ -755,16 +771,48 @@ const actions = [
     {
         // 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.'],
+        // Destructive because `--remote` runs any SQL the owner sends, DDL included: on a deployed
+        // database the owner may do anything to their own data, and `db restore` is the undo.
+        id: 'db.exec', command: ['db', 'exec'], summary: 'Run SQL against a running or deployed application database.',
+        description: 'Locally (`--state`), runs one statement against a running `xeer dev` or `xeer preview`: '
+            + 'reads by default, row writes with --write, and never DDL. With --remote it runs as the owner '
+            + 'against the D1 database of a deployed framework project, in the --environment named (there is no '
+            + 'default), through the control plane: any SQL, one statement or a --file batch (a JSON array of '
+            + '{"sql","params"}) that runs as one transaction, so a failing statement rolls every statement '
+            + 'back. Undo with `xeer db restore --remote`.',
+        usage: ['db exec [directory] <sql> [--state <dev|preview>] [--write] [--json]',
+            'db exec [directory] <sql> --remote --environment <prod|preview> [--param <value>]... [--control-url <url>] [--json]',
+            'db exec [directory] --remote --environment <prod|preview> --file <batch.json> [--control-url <url>] [--json]'],
+        helpOrder: 340,
+        outputProtocol: 'xeer.command.v0', effects: ['read-state', 'write-state', 'network-read', 'network-write'],
+        idempotent: false, reversible: false, destructive: true,
+        humanPrerequisites: ['Locally, a human must pass --write before any statement that modifies rows.',
+            BUILDER_CREDENTIAL],
         pathPolicy: 'project-relative', surfaces: { cli: true, mcpExclusion: DESTRUCTIVE_STATE },
     },
+    {
+        id: 'db.bookmark', command: ['db', 'bookmark'],
+        summary: 'Print the current Time Travel bookmark of a deployed application database.',
+        description: 'The bookmark names the database as it is now; `xeer db restore --remote --to <bookmark>` '
+            + 'returns to it for 30 days (7 on the Workers Free plan).',
+        usage: ['db bookmark [directory] --remote --environment <prod|preview> [--control-url <url>] [--json]'], helpOrder: 345,
+        outputProtocol: 'xeer.command.v0', effects: ['network-read'], idempotent: true, reversible: true,
+        destructive: false, humanPrerequisites: [BUILDER_CREDENTIAL], pathPolicy: 'project-relative',
+        surfaces: { cli: true, mcpExclusion: NOT_EXPOSED_V0 },
+    },
+    {
+        // Reversible although destructive: the answer carries previousBookmark, and restoring to it
+        // brings back everything this restore discarded.
+        id: 'db.restore', command: ['db', 'restore'],
+        summary: 'Restore a deployed application database to a bookmark or a time.',
+        description: 'Replaces the whole database in --environment with its state at the bookmark or ISO time '
+            + '(with a zone) given to --to. Every later write is discarded, including the owner writes; uploaded '
+            + 'media, code and sessions are not touched. The previousBookmark in the result undoes the restore.',
+        usage: ['db restore [directory] --remote --environment <prod|preview> --to <bookmark|time> [--control-url <url>] [--json]'],
+        helpOrder: 346, outputProtocol: 'xeer.command.v0', effects: ['network-write', 'write-state'], idempotent: false,
+        reversible: true, destructive: true, humanPrerequisites: [BUILDER_CREDENTIAL], pathPolicy: 'project-relative',
+        surfaces: { cli: true, mcpExclusion: DESTRUCTIVE_STATE },
+    },
 ];
 export const XEER_ACTIONS = Object.freeze(actions);
 export function actionDefinition(id) {

package/vendor/spec/admin-sql.js

@@ -24,8 +24,13 @@
  * change enforcement at all.
  */
 import { ADMIN_PROTOCOL } from './admin.js';
-/** Statements that only read. `EXPLAIN` is here because it plans a statement without running it. */
-const READ_VERBS = new Set(['SELECT', 'WITH', 'VALUES', 'EXPLAIN']);
+/**
+ * Statements that only read. A strict allowlist of leading verbs: `WITH` and `EXPLAIN` are not here
+ * because the verb after them decides what they do — `WITH x AS (SELECT 1) UPDATE posts …` writes
+ * without `--write`, and `EXPLAIN PRAGMA ignore_check_constraints=ON` sets the pragma while the
+ * statement is prepared.
+ */
+const READ_VERBS = new Set(['SELECT', 'VALUES']);
 const WRITE_VERBS = new Set(['INSERT', 'UPDATE', 'DELETE', 'REPLACE']);
 /**
  * Pragmas that only report. An allowlist rather than a denylist, because the case that must never

package/vendor/spec/diagnostics.d.ts

@@ -13,7 +13,7 @@
  * undocumented and a retired code cannot linger here.
  */
 /** Where an agent observes a code, in the vocabulary of the CLI commands. */
-export type DiagnosticSurface = 'any' | 'check' | 'build' | 'dev' | 'preview' | 'test' | 'new' | 'init' | 'agent' | 'doctor' | 'inspect' | 'state' | 'auth' | 'deploy' | 'deployments' | 'promote' | 'rollback' | 'disable' | 'enable' | 'delete' | 'link' | 'env' | 'token' | 'domains' | 'export' | 'import' | 'db';
+export type DiagnosticSurface = 'any' | 'check' | 'build' | 'dev' | 'preview' | 'test' | 'new' | 'init' | 'agent' | 'doctor' | 'inspect' | 'state' | 'auth' | 'deploy' | 'deployments' | 'promote' | 'rollback' | 'disable' | 'enable' | 'delete' | 'link' | 'env' | 'bootstrap' | 'token' | 'domains' | 'export' | 'import' | 'db';
 export interface DiagnosticFamily {
     /** Numeric prefix the family owns, as it appears in a code. */
     readonly prefix: string;

package/vendor/spec/diagnostics.js

@@ -357,6 +357,12 @@ export const DIAGNOSTIC_DEFINITIONS = [
     define('XE1841', 'The running server published no admin session secret, so its database surface is '
         + 'not reachable. The secret is minted per run and shared through the state lease.', 'Restart the server with a build that publishes one; a server older than this CLI does not.', ['db']),
     define('XE1842', 'The server answered the database request with a protocol this CLI does not know.', 'The CLI and the running server are different versions. Restart the server from this checkout.', ['db']),
+    define('XE1843', 'The control plane refused, or did not complete, a `xeer db --remote` request.', 'Read `message` and `hint`: they carry the refusal verbatim. `sql_error` means the whole batch was '
+        + 'rolled back; an unknown outcome means it may have been applied, so read before running writes again.', ['db']),
+    define('XE1844', 'The control plane returned a database response the CLI will not trust.', 'Retry the read; if it persists the control plane and CLI versions are incompatible.', ['db']),
+    define('XE1845', 'A `xeer db --remote` invocation is wrong: no --remote, no --environment, a --state '
+        + 'alongside it, an unreadable --file, a bad --to, or no linked application.', 'Pass --remote --environment prod|preview in the project directory. A --file batch is a JSON array '
+        + 'of {"sql","params"}; --to takes a bookmark or an ISO time with a zone.', ['db']),
     define('XE1821', 'The export file could not be read or written.', 'Read `message`: usually a missing path or permissions. `--out` creates parent directories.', ['export', 'import']),
     define('XE1822', 'The document is not a usable xeer.state-export.v0 export: wrong protocol, or it '
         + 'contradicts itself (counts, schema, or an encoded value).', 'Import the unmodified file `xeer export --out` produced. `detail.code` names the exact defect.', ['export', 'import']),
@@ -404,15 +410,16 @@ export const DIAGNOSTIC_DEFINITIONS = [
         + 'fix: wait out the advertised retry and read again. '
         + "Quote `detail.errorId` when correlating with the Worker's console output.", ['inspect', 'state', 'export']),
     define('XE3001', 'xeer new could not scaffold the project — most often a non-empty target directory.', 'Choose an empty or non-existent directory.', ['new']),
-    define('XE3002', '`--template` named neither a bundled starter nor an exact id in the reachable catalog.', 'Check the exact catalog id, use a bundled starter, or omit --template for the default. A framework '
-        + 'scaffold is selected with `--framework`.', ['new']),
+    define('XE3002', '`--template` named neither a bundled starter nor an exact id in the reachable catalog.', 'Check the exact catalog id, use a bundled name (notes, todo, blog, personal-site, or the emdash '
+        + 'framework template), or omit --template for the default. A plain framework scaffold is '
+        + 'selected with `--framework`.', ['new']),
     define('XE3003', '`--ui` named a UI provider that does not exist. Refused before the target '
         + 'directory is read, so nothing was written.', 'Use preact or react, or omit --ui for the default (preact). The choice is orthogonal to '
         + '--template for every Xeer application template: each scaffolds on either provider from the '
         + 'same client sources.', ['new']),
     define('XE3004', '`--ui` was passed with `--framework`, and a framework renders through its own '
         + 'toolchain rather than through a Xeer UI provider. Refused before the target directory is '
-        + 'read, so nothing was written.', 'Drop --ui. `--framework sveltekit` owns its renderer: it writes no client.runtime.provider to '
+        + 'read, so nothing was written.', 'Drop --ui. A framework project owns its renderer: it writes no client.runtime.provider to '
         + 'select, and no value of --ui would change a file it writes.', ['new']),
     define('XE3005', '`--template` and `--framework` were passed together. They are two exclusive '
         + 'axes: one writes a Xeer application, the other a project Xeer runs rather than compiles. '
@@ -427,7 +434,8 @@ export const DIAGNOSTIC_DEFINITIONS = [
     define('XE3010', 'The downloaded template archive does not match the catalog SHA-256.', 'Do not use the bytes. Repeat later or report the template artifact.', ['new']),
     define('XE3011', 'The downloaded template archive contains unsafe or unsupported content.', 'Report the template artifact and choose another template.', ['new']),
     define('XE3012', 'The extracted project root does not match the project metadata declared by the catalog.', 'Report the template artifact and choose another template.', ['new']),
-    define('XE3013', '`--ui` was passed with a catalog template, which owns its project kind and renderer.', 'Drop --ui and install the catalog template unchanged.', ['new']),
+    define('XE3013', '`--ui` was passed with a template that owns its renderer: a catalog template, or the '
+        + 'bundled emdash framework template. Refused before the target directory is read, so nothing was written.', 'Drop --ui and create the template unchanged.', ['new']),
     define('XE3101', 'Agent setup check found one or more generated files missing or stale. No files were written.', 'Run `xeer agent setup`, then repeat `xeer agent setup --check --json`.', ['agent']),
     define('XE3102', 'Agent setup found a path owned by the user or another tool. The entire write was refused.', 'Move, rename, or deliberately remove the conflicting path; setup never overwrites an unowned file.', ['agent']),
     define('XE3103', '`--target` named an agent adapter that Xeer does not support.', 'Use auto, agents, claude, codex, cursor, vscode, or mcp.', ['agent']),
@@ -509,6 +517,11 @@ export const DIAGNOSTIC_DEFINITIONS = [
         + 'entries have names or values a local run cannot load — so `ctx.env` is missing them.', 'Read `message`: it names the file and the exact problem — the shape to write is '
         + '{"format": "xeer.env-local.v0", "values": {"NAME": "value"}} with UPPER_SNAKE_CASE names '
         + 'and string values. `xeer env pull` writes the file correctly.', ['dev', 'preview', 'test']),
+    define('XE5135', 'xeer bootstrap could not confirm EmDash setup readiness within its fixed 240-second wait: '
+        + 'the deployed site never answered `GET /_emdash/api/setup/status` with a ready response. A fresh '
+        + 'database can take several minutes to run its migrations; no probe has a shorter deadline than what remains of that budget.', 'Wait for the site to finish initializing, then run the `retry` command from the result. The result '
+        + 'carries `readiness: "pending"` and `retryable: true`; no setup URL was returned, and a retry obtains a '
+        + 'fresh grant. Do not release a migration lock while initialization is still running.', ['bootstrap']),
     define('XE5139', 'xeer env failed without a more specific code.', 'Read `message`; it is the underlying error verbatim.', ['env']),
     define('XE5140', 'An `xeer deployments` invocation is wrong: an unusable --limit, or a directory that '
         + 'declares no app identity.', 'Read `message`. --limit takes a positive integer up to 200. In a directory with no appId, run '

package/vendor/spec/framework-config.d.ts

@@ -1,18 +1,53 @@
 import { z } from 'zod';
 export declare const FRAMEWORK_CONFIG_SCHEMA_URL: "https://docs.xeer.run/config-v0.schema.json";
 export declare const FRAMEWORK_CONFIG_FORMAT: "xeer.config.v0";
+/**
+ * What an EmDash deployment must bind. EmDash's own adapters fix the D1 and R2 binding names, its
+ * sign-in needs Astro's session KV, and its scheduled publishing needs the platform's one supported
+ * schedule. Stated once here so the config, the build, and the control plane refuse the same shape.
+ */
+export declare const EMDASH_DEPLOYMENT: Readonly<{
+    readonly framework: "astro";
+    readonly database: "DB";
+    readonly storage: "MEDIA";
+    readonly schedule: "* * * * *";
+}>;
 declare const frameworkConfigSchema: z.ZodObject<{
     $schema: z.ZodOptional<z.ZodString>;
     format: z.ZodLiteral<"xeer.config.v0">;
     name: z.ZodString;
     framework: z.ZodEnum<{
+        astro: "astro";
         sveltekit: "sveltekit";
     }>;
+    integration: z.ZodOptional<z.ZodEnum<{
+        emdash: "emdash";
+    }>>;
     capabilities: z.ZodObject<{
         auth: z.ZodOptional<z.ZodObject<{}, z.core.$strict>>;
+        database: z.ZodOptional<z.ZodObject<{}, z.core.$strict>>;
+        storage: z.ZodOptional<z.ZodObject<{}, z.core.$strict>>;
     }, z.core.$strict>;
 }, z.core.$strict>;
 export type FrameworkConfigV0 = z.infer<typeof frameworkConfigSchema>;
 export declare const frameworkConfigJsonSchema: Readonly<Record<string, unknown>>;
 export declare function parseFrameworkConfig(value: unknown): FrameworkConfigV0;
+declare const frameworkDeploymentSchema: z.ZodObject<{
+    framework: z.ZodOptional<z.ZodEnum<{
+        astro: "astro";
+        sveltekit: "sveltekit";
+    }>>;
+    integration: z.ZodOptional<z.ZodEnum<{
+        emdash: "emdash";
+    }>>;
+    bindings: z.ZodOptional<z.ZodObject<{
+        database: z.ZodOptional<z.ZodString>;
+        storage: z.ZodOptional<z.ZodString>;
+        session: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    schedule: z.ZodOptional<z.ZodLiteral<"* * * * *">>;
+}, z.core.$strip>;
+export type FrameworkDeployment = z.infer<typeof frameworkDeploymentSchema>;
+export type FrameworkBindings = NonNullable<FrameworkDeployment['bindings']>;
+export declare function parseFrameworkDeployment(value: unknown): FrameworkDeployment;
 export {};

package/vendor/spec/framework-config.js

@@ -1,16 +1,37 @@
 import { z } from 'zod';
-import { FRAMEWORK_NAMES } from './scaffold-names.js';
+import { FRAMEWORK_NAMES, INTEGRATION_NAMES } from './scaffold-names.js';
 export const FRAMEWORK_CONFIG_SCHEMA_URL = 'https://docs.xeer.run/config-v0.schema.json';
 export const FRAMEWORK_CONFIG_FORMAT = 'xeer.config.v0';
+/**
+ * What an EmDash deployment must bind. EmDash's own adapters fix the D1 and R2 binding names, its
+ * sign-in needs Astro's session KV, and its scheduled publishing needs the platform's one supported
+ * schedule. Stated once here so the config, the build, and the control plane refuse the same shape.
+ */
+export const EMDASH_DEPLOYMENT = Object.freeze({
+    framework: 'astro', database: 'DB', storage: 'MEDIA', schedule: '* * * * *',
+});
+function requireIntegrationFramework(value, context) {
+    if (value.integration === 'emdash' && value.framework !== 'astro') {
+        context.addIssue({ code: 'custom', message: 'The emdash integration requires the astro framework.' });
+    }
+}
 const frameworkConfigSchema = z.object({
     $schema: z.string().url().optional(),
     format: z.literal(FRAMEWORK_CONFIG_FORMAT),
     name: z.string().regex(/^[a-z][a-z0-9-]{0,61}[a-z0-9]$/u),
     framework: z.enum(FRAMEWORK_NAMES),
+    integration: z.enum(INTEGRATION_NAMES).optional(),
     capabilities: z.object({
         auth: z.object({}).strict().optional(),
+        database: z.object({}).strict().optional(),
+        storage: z.object({}).strict().optional(),
     }).strict(),
-}).strict();
+}).strict().superRefine((value, context) => {
+    requireIntegrationFramework(value, context);
+    if (value.integration === 'emdash' && (!value.capabilities.database || !value.capabilities.storage)) {
+        context.addIssue({ code: 'custom', message: 'The emdash integration requires database and storage capabilities.' });
+    }
+});
 export const frameworkConfigJsonSchema = Object.freeze({
     ...z.toJSONSchema(frameworkConfigSchema),
     $id: FRAMEWORK_CONFIG_SCHEMA_URL,
@@ -20,3 +41,29 @@ export const frameworkConfigJsonSchema = Object.freeze({
 export function parseFrameworkConfig(value) {
     return frameworkConfigSchema.parse(value);
 }
+const bindingName = z.string().regex(/^[A-Za-z_][A-Za-z0-9_]{0,62}$/u)
+    .refine((name) => !name.startsWith('XEER_') && !['ASSETS', 'XeerState'].includes(name), 'Binding names must not shadow platform bindings.');
+const frameworkDeploymentSchema = z.object({
+    framework: z.enum(FRAMEWORK_NAMES).optional(),
+    integration: z.enum(INTEGRATION_NAMES).optional(),
+    bindings: z.object({ database: bindingName.optional(), storage: bindingName.optional(),
+        session: bindingName.optional() }).strict().optional(),
+    schedule: z.literal('* * * * *').optional(),
+}).superRefine((value, context) => {
+    const names = Object.values(value.bindings ?? {});
+    if (new Set(names).size !== names.length)
+        context.addIssue({ code: 'custom', message: 'Binding names must be distinct.' });
+    if ((value.bindings !== undefined || value.schedule !== undefined) && value.framework !== 'astro') {
+        context.addIssue({ code: 'custom', message: 'Declared bindings and schedules require an Astro framework bundle.' });
+    }
+    requireIntegrationFramework(value, context);
+    if (value.integration === 'emdash' && (value.bindings?.database !== EMDASH_DEPLOYMENT.database
+        || value.bindings.storage !== EMDASH_DEPLOYMENT.storage || value.bindings.session === undefined
+        || value.schedule !== EMDASH_DEPLOYMENT.schedule)) {
+        context.addIssue({ code: 'custom', message: 'The emdash integration requires the DB database binding, the '
+                + 'MEDIA storage binding, a session binding, and the * * * * * schedule.' });
+    }
+});
+export function parseFrameworkDeployment(value) {
+    return frameworkDeploymentSchema.parse(value);
+}

package/vendor/spec/index.d.ts

@@ -26,3 +26,4 @@ export * from './framework-config.js';
 export * from './tunnel.js';
 export * from './type-check-profile.js';
 export * from './editor-settings.js';
+export * from './platform-grants.js';

package/vendor/spec/index.js

@@ -26,3 +26,4 @@ export * from './framework-config.js';
 export * from './tunnel.js';
 export * from './type-check-profile.js';
 export * from './editor-settings.js';
+export * from './platform-grants.js';

package/vendor/spec/platform-grants.d.ts

@@ -0,0 +1,25 @@
+/** Fixed by the endpoint, never selected by an incoming grant. */
+export declare const PLATFORM_GRANTS: Readonly<{
+    inspector: Readonly<{
+        audience: "xeer-inspector";
+        maxTtlSeconds: 60;
+    }>;
+    scheduler: Readonly<{
+        audience: "xeer-scheduler";
+        maxTtlSeconds: 60;
+    }>;
+    bootstrap: Readonly<{
+        audience: "xeer-bootstrap";
+        maxTtlSeconds: 1800;
+    }>;
+}>;
+export type PlatformGrantScope = keyof typeof PLATFORM_GRANTS;
+export type PlatformGrantEnvironment = 'production' | 'preview';
+/** Includes cold framework migrations; four batches remain below a cron event's 15-minute lifetime. */
+export declare const PLATFORM_SCHEDULE: Readonly<{
+    invocationDeadlineMs: 180000;
+    dispatchTimeoutMs: 185000;
+    leaseMs: 210000;
+    maxApplications: 20;
+    concurrency: 5;
+}>;

package/vendor/spec/platform-grants.js

@@ -0,0 +1,14 @@
+/** Fixed by the endpoint, never selected by an incoming grant. */
+export const PLATFORM_GRANTS = Object.freeze({
+    inspector: Object.freeze({ audience: 'xeer-inspector', maxTtlSeconds: 60 }),
+    scheduler: Object.freeze({ audience: 'xeer-scheduler', maxTtlSeconds: 60 }),
+    bootstrap: Object.freeze({ audience: 'xeer-bootstrap', maxTtlSeconds: 1800 }),
+});
+/** Includes cold framework migrations; four batches remain below a cron event's 15-minute lifetime. */
+export const PLATFORM_SCHEDULE = Object.freeze({
+    invocationDeadlineMs: 180_000,
+    dispatchTimeoutMs: 185_000,
+    leaseMs: 210_000,
+    maxApplications: 20,
+    concurrency: 5,
+});

package/vendor/spec/route.js

@@ -110,6 +110,7 @@ export const LIVE_STREAM_PATH = '/__xeer/events';
 export const PUBLIC_RESERVED_ROUTES = new Set([
     '/__xeer/health',
     '/__xeer/identity',
+    '/__xeer/bootstrap',
     '/__xeer/rpc/query',
     '/__xeer/rpc/mutation',
     LIVE_STREAM_PATH,

package/vendor/spec/scaffold-names.d.ts

@@ -13,6 +13,19 @@
  */
 export declare const BUNDLED_TEMPLATES: readonly ["notes", "todo", "blog", "personal-site"];
 export type BundledTemplateName = (typeof BUNDLED_TEMPLATES)[number];
+/**
+ * The bundled framework templates: a complete framework project, written offline like the
+ * application starters above, but holding `xeer.config.json` and declaring which framework runs it.
+ *
+ * A template rather than a framework name because EmDash is an Astro application, not another
+ * runtime: `--template emdash` writes an Astro project whose config declares `framework: "astro"`
+ * and `integration: "emdash"`. Kept apart from {@link BUNDLED_TEMPLATES} because the two write
+ * different root contracts, and every application-only consumer of that list must stay narrow.
+ */
+export declare const BUNDLED_FRAMEWORK_TEMPLATES: Readonly<{
+    readonly emdash: "astro";
+}>;
+export type BundledFrameworkTemplateName = keyof typeof BUNDLED_FRAMEWORK_TEMPLATES;
 /**
  * The frameworks Xeer runs rather than compiles: a `xeer.config.json` beside a project whose own
  * toolchain owns the renderer, the routes, and the build.
@@ -21,5 +34,14 @@ export type BundledTemplateName = (typeof BUNDLED_TEMPLATES)[number];
  * and every later command dispatches on which one is present. `--framework` selects one for a fresh
  * project; `xeer init` adopts an existing one; `xeer.config.json` declares which one a directory is.
  */
-export declare const FRAMEWORK_NAMES: readonly ["sveltekit"];
+export declare const FRAMEWORK_NAMES: readonly ["sveltekit", "astro"];
 export type FrameworkName = (typeof FRAMEWORK_NAMES)[number];
+export declare const SCAFFOLDABLE_FRAMEWORK_NAMES: readonly ["sveltekit", "astro"];
+export type ScaffoldableFrameworkName = (typeof SCAFFOLDABLE_FRAMEWORK_NAMES)[number];
+/**
+ * The integrations a framework project may declare on top of its framework. One today: EmDash, an
+ * Astro CMS whose deployment needs a fixed binding set and a computed site URL. Declared explicitly
+ * in `xeer.config.json`, never inferred from packages, routes, or resource names.
+ */
+export declare const INTEGRATION_NAMES: readonly ["emdash"];
+export type IntegrationName = (typeof INTEGRATION_NAMES)[number];

package/vendor/spec/scaffold-names.js

@@ -12,6 +12,16 @@
  * it names. Offline, deterministic, and resolved before any catalog request.
  */
 export const BUNDLED_TEMPLATES = Object.freeze(['notes', 'todo', 'blog', 'personal-site']);
+/**
+ * The bundled framework templates: a complete framework project, written offline like the
+ * application starters above, but holding `xeer.config.json` and declaring which framework runs it.
+ *
+ * A template rather than a framework name because EmDash is an Astro application, not another
+ * runtime: `--template emdash` writes an Astro project whose config declares `framework: "astro"`
+ * and `integration: "emdash"`. Kept apart from {@link BUNDLED_TEMPLATES} because the two write
+ * different root contracts, and every application-only consumer of that list must stay narrow.
+ */
+export const BUNDLED_FRAMEWORK_TEMPLATES = Object.freeze({ emdash: 'astro' });
 /**
  * The frameworks Xeer runs rather than compiles: a `xeer.config.json` beside a project whose own
  * toolchain owns the renderer, the routes, and the build.
@@ -20,4 +30,11 @@ export const BUNDLED_TEMPLATES = Object.freeze(['notes', 'todo', 'blog', 'person
  * and every later command dispatches on which one is present. `--framework` selects one for a fresh
  * project; `xeer init` adopts an existing one; `xeer.config.json` declares which one a directory is.
  */
-export const FRAMEWORK_NAMES = Object.freeze(['sveltekit']);
+export const FRAMEWORK_NAMES = Object.freeze(['sveltekit', 'astro']);
+export const SCAFFOLDABLE_FRAMEWORK_NAMES = Object.freeze(['sveltekit', 'astro']);
+/**
+ * The integrations a framework project may declare on top of its framework. One today: EmDash, an
+ * Astro CMS whose deployment needs a fixed binding set and a computed site URL. Declared explicitly
+ * in `xeer.config.json`, never inferred from packages, routes, or resource names.
+ */
+export const INTEGRATION_NAMES = Object.freeze(['emdash']);

package/vendor/spec/template-distribution.d.ts

@@ -34,6 +34,15 @@ export declare const templateDistributionEntrySchema: z.ZodObject<{
         url: z.ZodString;
         sha256: z.ZodString;
     }, z.core.$strict>;
+    admin: z.ZodOptional<z.ZodObject<{
+        path: z.ZodString;
+        signIn: z.ZodEnum<{
+            code: "code";
+            owner: "owner";
+        }>;
+        codeSecret: z.ZodOptional<z.ZodString>;
+        tasks: z.ZodString;
+    }, z.core.$strict>>;
     author: z.ZodObject<{
         name: z.ZodString;
         url: z.ZodOptional<z.ZodString>;
@@ -63,8 +72,12 @@ export declare const templateDistributionEntrySchema: z.ZodObject<{
             "xeer-application": "xeer-application";
         }>;
         framework: z.ZodOptional<z.ZodEnum<{
+            astro: "astro";
             sveltekit: "sveltekit";
         }>>;
+        integration: z.ZodOptional<z.ZodEnum<{
+            emdash: "emdash";
+        }>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export type TemplateDistributionEntryV0 = z.infer<typeof templateDistributionEntrySchema>;
@@ -86,6 +99,15 @@ export declare const templateDistributionCatalogSchema: z.ZodObject<{
             url: z.ZodString;
             sha256: z.ZodString;
         }, z.core.$strict>;
+        admin: z.ZodOptional<z.ZodObject<{
+            path: z.ZodString;
+            signIn: z.ZodEnum<{
+                code: "code";
+                owner: "owner";
+            }>;
+            codeSecret: z.ZodOptional<z.ZodString>;
+            tasks: z.ZodString;
+        }, z.core.$strict>>;
         author: z.ZodObject<{
             name: z.ZodString;
             url: z.ZodOptional<z.ZodString>;
@@ -115,8 +137,12 @@ export declare const templateDistributionCatalogSchema: z.ZodObject<{
                 "xeer-application": "xeer-application";
             }>;
             framework: z.ZodOptional<z.ZodEnum<{
+                astro: "astro";
                 sveltekit: "sveltekit";
             }>>;
+            integration: z.ZodOptional<z.ZodEnum<{
+                emdash: "emdash";
+            }>>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;

package/vendor/spec/template-distribution.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { FRAMEWORK_NAMES } from './scaffold-names.js';
-import { checkTemplateMetadataUniqueness, templateAltTextSchema, templateIdentityShape, templateMetadataShape, templateSlugSchema, } from './template.js';
+import { FRAMEWORK_NAMES, INTEGRATION_NAMES } from './scaffold-names.js';
+import { checkTemplateMetadataUniqueness, templateAdminPathSchema, templateAdminTasksSchema, templateAltTextSchema, templateIdentityShape, templateMetadataShape, templateSlugSchema, } from './template.js';
 export const TEMPLATE_DISTRIBUTION_CATALOG_FORMAT = 'xeer.template-distribution-catalog.v0';
 export const TEMPLATE_DISTRIBUTION_CATALOG_SCHEMA_URL = 'https://docs.xeer.run/template-distribution-catalog-v0.schema.json';
 /** Exact semantic version: no range operator, no `v` prefix, no wildcard. */
@@ -40,7 +40,12 @@ export const TEMPLATE_PROJECT_KINDS = ['xeer-application', 'framework'];
 const templateProjectSchema = z.strictObject({
     kind: z.enum(TEMPLATE_PROJECT_KINDS),
     framework: z.enum(FRAMEWORK_NAMES).optional(),
+    /** Copied from the framework configuration; EmDash is the only integration, and it runs on Astro. */
+    integration: z.enum(INTEGRATION_NAMES).optional(),
 }).superRefine((project, ctx) => {
+    if (project.integration === 'emdash' && project.framework !== 'astro') {
+        ctx.addIssue({ code: 'custom', path: ['integration'], message: 'the emdash integration runs on the astro framework' });
+    }
     if ((project.framework !== undefined) === (project.kind === 'framework'))
         return;
     ctx.addIssue({
@@ -51,6 +56,17 @@ const templateProjectSchema = z.strictObject({
             : `only a framework project names a framework; a ${project.kind} project does not`,
     });
 });
+/**
+ * The Site admin an entry resolves to: an owner dashboard unlocked by one of the entry's invite codes
+ * (`code`), or EmDash's admin, which the owner opens through the platform's owner sign-in (`owner`).
+ * Authored in `template.json` for the first, derived from the EmDash integration for the second.
+ */
+const distributedAdminSchema = z.strictObject({
+    path: templateAdminPathSchema,
+    signIn: z.enum(['code', 'owner']),
+    codeSecret: z.string().optional(),
+    tasks: templateAdminTasksSchema,
+});
 /**
  * One published template. The authored metadata is copied verbatim from `template.json`; everything
  * else is produced by the release job that packed, deployed, and verified this exact artifact.
@@ -77,7 +93,29 @@ export const templateDistributionEntrySchema = z.strictObject({
     /** Release version of the template artifact itself, independent of the platform version. */
     artifactVersion: exactVersion,
     sourceArchive: sourceArchiveSchema,
-}).superRefine(checkTemplateMetadataUniqueness);
+    /** Absent for a template without an admin, and on every entry published before the field existed. */
+    admin: distributedAdminSchema.optional(),
+}).superRefine((entry, ctx) => {
+    checkTemplateMetadataUniqueness(entry, ctx);
+    const { admin } = entry;
+    const emdash = entry.project?.integration === 'emdash';
+    if (emdash && admin?.signIn !== 'owner') {
+        ctx.addIssue({ code: 'custom', path: ['admin'], message: 'an emdash project carries the owner admin' });
+    }
+    if (!admin)
+        return;
+    if (admin.signIn === 'owner' && !emdash) {
+        ctx.addIssue({ code: 'custom', path: ['admin', 'signIn'], message: 'the owner sign-in belongs to an emdash project' });
+    }
+    if ((admin.codeSecret !== undefined) !== (admin.signIn === 'code')) {
+        ctx.addIssue({ code: 'custom', path: ['admin', 'codeSecret'],
+            message: 'a code admin names its codeSecret, and only a code admin does' });
+    }
+    else if (admin.codeSecret !== undefined && !entry.requiredSecrets.some((secret) => secret.name === admin.codeSecret)) {
+        ctx.addIssue({ code: 'custom', path: ['admin', 'codeSecret'],
+            message: 'admin codeSecret must name one of the entry requiredSecrets' });
+    }
+});
 /**
  * Versioned distribution catalog published atomically after a platform release. Entries are keyed by
  * template id, sorted by codepoint so a regenerated catalog is byte-stable, and a template with no

package/vendor/spec/template.d.ts

@@ -3,6 +3,13 @@ export declare const TEMPLATE_FORMAT: "xeer.template.v0";
 export declare const TEMPLATE_MANIFEST_SCHEMA_URL: "https://docs.xeer.run/template-v0.schema.json";
 /** Catalog identifier shape shared by template directory names and categories. */
 export declare const templateSlugSchema: z.ZodString;
+/**
+ * Where a template's own admin lives, relative to the site's origin: one absolute path, nothing that
+ * could leave the origin (`//host`) or carry a query or fragment.
+ */
+export declare const templateAdminPathSchema: z.ZodString;
+/** What the owner does in the admin, shown next to its button: one short sentence. */
+export declare const templateAdminTasksSchema: z.ZodString;
 /** Alt text carried by a gallery image in either the source or the distribution catalog. */
 export declare const templateAltTextSchema: z.ZodString;
 /**
@@ -50,6 +57,12 @@ export declare function checkTemplateMetadataUniqueness(metadata: {
     }[];
 }, ctx: z.RefinementCtx): void;
 export declare const templateManifestSchema: z.ZodObject<{
+    admin: z.ZodOptional<z.ZodObject<{
+        path: z.ZodOptional<z.ZodString>;
+        signIn: z.ZodOptional<z.ZodLiteral<"code">>;
+        codeSecret: z.ZodOptional<z.ZodString>;
+        tasks: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
     author: z.ZodObject<{
         name: z.ZodString;
         url: z.ZodOptional<z.ZodString>;

package/vendor/spec/template.js

@@ -18,6 +18,27 @@ const requiredSecretSchema = z.strictObject({
     name: environmentName,
     description: trimmed(200),
 });
+/**
+ * Where a template's own admin lives, relative to the site's origin: one absolute path, nothing that
+ * could leave the origin (`//host`) or carry a query or fragment.
+ */
+export const templateAdminPathSchema = z.string().max(200)
+    .regex(/^\/(?!\/)[^\s?#\\]*$/u, 'admin path must be a plain site path starting with one "/"');
+/** What the owner does in the admin, shown next to its button: one short sentence. */
+export const templateAdminTasksSchema = trimmed(140)
+    .regex(/^[^.!?]*(?:[.!?](?! )[^.!?]*)*\.$/u, 'admin tasks must be one short sentence ending in a full stop');
+/**
+ * The Site admin a template offers. An application template authors all of it: the path of its owner
+ * dashboard, and the invite code (one of its `requiredSecrets`) that unlocks it. An EmDash template's
+ * admin is derived from its integration by the catalog, so there only `tasks` may be authored; which
+ * of the two applies is known only to the catalog generator, which reads the root contract.
+ */
+const templateAdminSchema = z.strictObject({
+    path: templateAdminPathSchema.optional(),
+    signIn: z.literal('code').optional(),
+    codeSecret: environmentName.optional(),
+    tasks: templateAdminTasksSchema.optional(),
+});
 /** Alt text carried by a gallery image in either the source or the distribution catalog. */
 export const templateAltTextSchema = trimmed(200);
 const screenshotSchema = z.strictObject({
@@ -70,7 +91,21 @@ export const templateManifestSchema = z.strictObject({
     ...templateMetadataShape,
     screenshots: z.array(screenshotSchema).min(1).max(8),
     ...templateIdentityShape,
-}).superRefine(checkTemplateMetadataUniqueness);
+    admin: templateAdminSchema.optional(),
+}).superRefine((manifest, ctx) => {
+    checkTemplateMetadataUniqueness(manifest, ctx);
+    const { admin } = manifest;
+    if (!admin)
+        return;
+    const code = [admin.path, admin.signIn, admin.codeSecret];
+    if (code.some((value) => value !== undefined) && code.some((value) => value === undefined)) {
+        ctx.addIssue({ code: 'custom', path: ['admin'], message: 'admin needs path, signIn, and codeSecret together' });
+    }
+    if (admin.codeSecret !== undefined && !manifest.requiredSecrets.some((secret) => secret.name === admin.codeSecret)) {
+        ctx.addIssue({ code: 'custom', path: ['admin', 'codeSecret'],
+            message: 'admin codeSecret must name one of the template requiredSecrets' });
+    }
+});
 const generatedTemplateManifestJsonSchema = z.toJSONSchema(templateManifestSchema);
 const generatedProperties = generatedTemplateManifestJsonSchema.properties;
 export const templateManifestJsonSchema = Object.freeze({