@impetik/xeer-mcp 0.2.18 → 0.2.20

package/README.md

@@ -63,11 +63,11 @@ 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 application 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 application tests against fresh isolated local state. | `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?`: `notes` / `todo` / `blog` / `personal-site` | `write-source` | 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?`: `notes` / `todo` / `blog` / `personal-site`<br>`ui?`: `preact` / `react` | `write-source` | 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 |
-| `xeer_deploy_preview` | `deploy.preview` | `author` / `operator` | Build and deploy an artifact to preview only. | `directory?`: `string`<br>`controlUrl?`: `string` | `read-source`<br>`write-generated`<br>`run-local`<br>`network-read`<br>`network-write` | writes; non-idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | A human must establish the builder credential with xeer auth login. |
+| `xeer_deploy_preview` | `deploy.preview` | `author` / `operator` | Build and deploy an artifact to preview only. | `directory?`: `string`<br>`controlUrl?`: `string` | `read-source`<br>`write-generated`<br>`run-local`<br>`network-read`<br>`network-write` | writes; non-idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | A human must establish the builder credential with xeer auth login, or issue the service token supplied in XEER_SERVICE_TOKEN. |
 | `xeer_promote` | `promote.operator` | `operator` | Promote an exact review receipt in operator mode. | `directory?`: `string`<br>`receiptId`: `string`<br>`controlUrl?`: `string` | `network-read`<br>`network-write`<br>`production-change` | writes; non-idempotent; reversible; non-destructive | `project-or-url` | `xeer.command.v0` | A human must review the exact artifact and start xeer-mcp with XEER_MCP_PROFILE=operator. |
 | `xeer_auth_status` | `auth.status` | `author` / `operator` | Report builder credential metadata. | `controlUrl?`: `string` | `network-read`<br>`secret-metadata` | read-only; idempotent; reversible; non-destructive | `none` | `xeer.command.v0` | none |
 | `xeer_inspect` | `inspect` | `author` / `operator` | Read a running application manifest. | `previewUrl`: `string`<br>`view?`: `manifest` / `state` / `logs` / `export`; default `manifest`<br>`after?`: `string` | `network-read`<br>`read-state` | read-only; idempotent; reversible; non-destructive | `app-or-url` | `xeer.command.v0` | none |

package/dist/server.js

@@ -369,7 +369,10 @@ export function createXeerMcpServer(options = {}) {
     server.registerTool('xeer_new', {
         ...toolPolicy('new'),
         outputSchema: commandOutput,
-    }, async ({ directory, template }) => withDirectory(directory, 'new', (resolved) => commandTool('new', ['new', resolved, ...(template === undefined ? [] : ['--template', template])], projectRoot())));
+    }, async ({ directory, template, ui }) => withDirectory(directory, 'new', (resolved) => commandTool('new', ['new', resolved,
+        ...(template === undefined ? [] : ['--template', template]),
+        ...(ui === undefined ? [] : ['--ui', ui]),
+    ], projectRoot())));
     server.registerTool('xeer_doctor', {
         ...toolPolicy('doctor'),
         outputSchema: commandOutput,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@impetik/xeer-mcp",
-  "version": "0.2.18",
+  "version": "0.2.20",
   "type": "module",
   "description": "Model Context Protocol server for Xeer: the scaffold, check, dev, build, and deploy loop as agent tools.",
   "license": "MIT",
@@ -47,7 +47,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.0.10",
-    "@impetik/xeer": "0.2.18"
+    "@impetik/xeer": "0.2.20"
   },
   "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 {{templates}}] [--json]"];
+    readonly usage: readonly ["new <directory> [--template {{templates}}] [--ui preact|react] [--json]"];
     readonly helpOrder: 30;
     readonly outputProtocol: "xeer.command.v0";
     readonly effects: readonly ["write-source"];
@@ -216,6 +216,11 @@ declare const actions: readonly [{
                     readonly type: "string";
                     readonly enum: readonly ["notes", "todo", "blog", "personal-site"];
                 };
+                readonly ui: {
+                    readonly description: string;
+                    readonly type: "string";
+                    readonly enum: readonly ["preact", "react"];
+                };
             };
             readonly required: readonly ["directory"];
         };
@@ -351,7 +356,7 @@ declare const actions: readonly [{
     readonly idempotent: false;
     readonly reversible: true;
     readonly destructive: false;
-    readonly humanPrerequisites: readonly ["A human must establish the builder credential with xeer auth login."];
+    readonly humanPrerequisites: readonly [string];
     readonly pathPolicy: "project-relative";
     readonly surfaces: {
         readonly cli: true;
@@ -385,7 +390,7 @@ declare const actions: readonly [{
     readonly idempotent: false;
     readonly reversible: true;
     readonly destructive: false;
-    readonly humanPrerequisites: readonly ["A human must establish the builder credential with xeer auth login."];
+    readonly humanPrerequisites: readonly [string];
     readonly pathPolicy: "project-relative";
     readonly surfaces: {
         readonly mcpInputSchema: {
@@ -576,7 +581,7 @@ declare const actions: readonly [{
     readonly idempotent: false;
     readonly reversible: true;
     readonly destructive: false;
-    readonly humanPrerequisites: readonly ["A human must sign in and deliberately keep the public tunnel process running."];
+    readonly humanPrerequisites: readonly [string, "A human must deliberately keep the public tunnel process running."];
     readonly pathPolicy: "none";
     readonly surfaces: {
         readonly cli: true;
@@ -723,7 +728,7 @@ declare const actions: readonly [{
     readonly idempotent: true;
     readonly reversible: true;
     readonly destructive: false;
-    readonly humanPrerequisites: readonly ["A human must establish the builder credential with xeer auth login."];
+    readonly humanPrerequisites: readonly [string];
     readonly pathPolicy: "project-or-url";
     readonly surfaces: {
         readonly cli: true;

package/vendor/spec/actions.js

@@ -25,6 +25,11 @@ const SERVICE_CREDENTIALS = 'Service credential issuance and revocation are inte
 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.';
+// Both ways an invocation comes to hold a builder credential, written once because it is one rule:
+// either a person signed in here, or a person issued the service token this environment presents.
+// Neither branch produces a credential no human authorized, which is what the prerequisite is for.
+const BUILDER_CREDENTIAL = 'A human must establish the builder credential with xeer auth login, '
+    + 'or issue the service token supplied in XEER_SERVICE_TOKEN.';
 const PROJECT_DIRECTORY_INPUT = {
     description: 'Project directory. Relative paths resolve against the server root; defaults to it.',
     type: 'string',
@@ -86,8 +91,10 @@ const MCP_PRESENTATION = {
             + '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.',
+            + 'them scaffolds sign-in UI. "ui" selects the UI provider independently of the template — '
+            + '"preact" (the default) or "react" — and changes the manifest rather than any source file. '
+            + 'result is { directory, name, template, ui, files }; an unknown template is XE3002, an '
+            + 'unknown ui is XE3003, and either writes nothing.',
     },
     doctor: {
         mcpTitle: 'Diagnose the Xeer toolchain',
@@ -197,8 +204,11 @@ const actions = [
         id: 'new', command: ['new'], summary: 'Create a new project from a supported scaffold.',
         description: 'Creates a complete project that checks, tests, and builds clean. Templates do not '
             + 'scaffold sign-in UI: every visitor already has a verified identity, and the generated README '
-            + 'explains how to opt in to a persistent account.',
-        usage: ['new <directory> [--template {{templates}}] [--json]'], helpOrder: 30,
+            + 'explains how to opt in to a persistent account. `--template` and `--ui` are orthogonal: the '
+            + 'template decides what the app does, the UI provider decides which renderer the identical '
+            + 'client sources compile against. `result.template` and `result.ui` report both, so neither '
+            + 'has to be inferred from the written files.',
+        usage: ['new <directory> [--template {{templates}}] [--ui preact|react] [--json]'], helpOrder: 30,
         outputProtocol: 'xeer.command.v0', effects: ['write-source'], idempotent: false,
         reversible: true, destructive: false, humanPrerequisites: [], pathPolicy: 'project-relative',
         surfaces: {
@@ -214,6 +224,11 @@ const actions = [
                         description: 'Which scaffold to write. Defaults to notes.', type: 'string',
                         enum: ['notes', 'todo', 'blog', 'personal-site'],
                     },
+                    ui: {
+                        description: 'Which UI provider the written manifest selects. Defaults to preact, and '
+                            + 'omitting it writes no client block at all. Orthogonal to template.',
+                        type: 'string', enum: ['preact', 'react'],
+                    },
                 },
                 required: ['directory'],
             },
@@ -275,7 +290,7 @@ const actions = [
         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.'],
+        humanPrerequisites: [BUILDER_CREDENTIAL],
         pathPolicy: 'project-relative', surfaces: { cli: true, mcpExclusion: PREVIEW_ONLY },
     },
     {
@@ -295,7 +310,7 @@ const actions = [
         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.'],
+        humanPrerequisites: [BUILDER_CREDENTIAL],
         pathPolicy: 'project-relative', surfaces: {
             cli: false, mcpTool: 'xeer_deploy_preview', mcpProfiles: ['author', 'operator'],
             ...MCP_PRESENTATION.deploy,
@@ -391,7 +406,7 @@ const actions = [
         helpOrder: 225, outputProtocol: 'xeer.tunnel.cli.v0',
         effects: ['run-local', 'network-read', 'network-write'], idempotent: false,
         reversible: true, destructive: false,
-        humanPrerequisites: ['A human must sign in and deliberately keep the public tunnel process running.'],
+        humanPrerequisites: [BUILDER_CREDENTIAL, 'A human must deliberately keep the public tunnel process running.'],
         pathPolicy: 'none', surfaces: { cli: true, mcpExclusion: NOT_EXPOSED_V0 },
     },
     {
@@ -456,7 +471,7 @@ const actions = [
         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.'],
+        humanPrerequisites: [BUILDER_CREDENTIAL],
         pathPolicy: 'project-or-url', surfaces: { cli: true, mcpExclusion: NOT_EXPOSED_V0 },
     },
     {

package/vendor/spec/diagnostics.js

@@ -12,7 +12,45 @@
  * catalogue disagree in either direction, so a new code cannot ship
  * undocumented and a retired code cannot linger here.
  */
-import { CLIENT_BUNDLE_ADVISORY_BUDGET_BYTES, CLIENT_BUNDLE_ERROR_BUDGET_BYTES, CLIENT_IMPORT_POLICY, SERVER_IMPORT_POLICY, } from './import-policy.js';
+import { CLIENT_BUNDLE_ADVISORY_BUDGET_BYTES, CLIENT_BUNDLE_ERROR_BUDGET_BYTES, CLIENT_IMPORT_POLICY, CLIENT_RUNTIME_PROVIDERS, SERVER_IMPORT_POLICY, clientImportPolicy, } from './import-policy.js';
+/**
+ * The client zone's managed renderer surface, stated for every provider, derived from the policies
+ * rather than written out.
+ *
+ * A catalogue entry is static text answering a question that arrives with no project attached:
+ * `xeer diagnostics XE1202` is handed a code and nothing else, and the agent reference is rendered
+ * offline by `pnpm generate:agent-reference`. Neither can know which provider an application
+ * selected, so an entry that describes one of them describes the wrong one half the time — and the
+ * sentence this replaced named Preact alone, which under the React provider is an accurate account
+ * of the policy the application is *not* under.
+ *
+ * The diagnostic a compile actually emits does better and should: `zoneRejectionHint` and
+ * `foreignFamilyHint` build its `hint` from `clientImportPolicy(provider)` at the point of refusal,
+ * so an agent reading the refusal itself already gets the selected provider's rule. This is the
+ * fallback surface an agent reaches when it asks about the code alone.
+ */
+const MANAGED_RENDERER_SURFACE = CLIENT_RUNTIME_PROVIDERS.map((provider) => {
+    const policy = clientImportPolicy(provider);
+    const anchors = policy.managedFamilies.flatMap((family) => [...family.anchorPackages]);
+    const aliases = policy.managedFamilies.flatMap((family) => [...family.compatAliases.values()]);
+    // One alias target names the whole compatibility surface: every React-ecosystem specifier under
+    // Preact lands on a subpath of it, and restating each mapping here would restate the alias table.
+    const compat = aliases.length === 0 ? ''
+        : `, with the React-ecosystem specifiers aliased onto ${aliases[0].split('/').slice(0, 2).join('/')}`;
+    const foreign = policy.foreignFamilies.flatMap((family) => [...family.anchorPackages]);
+    const refused = foreign.length === 0 ? ''
+        : `, and ${prose(foreign)} refused as the unselected renderer`;
+    const surface = anchors.length === 1
+        ? `${anchors[0]} with its supported entrypoints`
+        : `${prose(anchors)} with their supported entrypoints`;
+    return `under ${provider}, ${surface}${compat}${refused}`;
+}).join('; ');
+/** A list as a sentence reads it: "a", "a and b", "a, b and c". */
+function prose(items) {
+    if (items.length < 2)
+        return items.join('');
+    return `${items.slice(0, -1).join(', ')} and ${items[items.length - 1]}`;
+}
 export const DIAGNOSTIC_FAMILIES = [
     {
         prefix: 'XE00',
@@ -156,8 +194,8 @@ export const DIAGNOSTIC_DEFINITIONS = [
         + 'source, or a package family the other zone owns — the renderer (preact, react, react-dom, '
         + 'scheduler) in the server zone. It is not reported for an ordinary npm package in either zone: '
         + 'both admit any declared and installed dependency.', `The client zone admits ${CLIENT_IMPORT_POLICY.platformModules.join(', ')} and the `
-        + 'platform-managed renderer surface (preact and its supported entrypoints, plus '
-        + 'React-ecosystem imports aliased onto preact/compat); the server zone admits '
+        + `platform-managed renderer surface, which is whichever provider client.runtime.provider `
+        + `selects — ${MANAGED_RENDERER_SURFACE}; the server zone admits `
         + `${SERVER_IMPORT_POLICY.platformModules.join(', ')}. Both zones additionally admit any npm `
         + 'package declared in package.json dependencies and installed. Node builtins and native addons '
         + 'are never importable anywhere: the client runs in a browser and the server runs in workerd, '
@@ -187,6 +225,36 @@ export const DIAGNOSTIC_DEFINITIONS = [
         + 'type-checks in every zone, but only the client bundler has a loader that turns one into a URL.', 'Import images, fonts, and wasm only from client modules; the server bundle has no asset stage. '
         + 'A server handler that needs the bytes should read them from public/ or receive the URL from '
         + 'the client.', CHECKED_BY_EVERY_COMPILE),
+    define('XE1210', 'package.json declares a package the platform provides — the renderer selected by '
+        + '`client.runtime.provider`, or one of the React-family names that resolve to it. The '
+        + 'declaration has no effect on what the application bundles: every one of those specifiers is '
+        + 'pinned to the platform\'s copy, for application code and for dependencies alike. A warning '
+        + 'rather than an error, so an application that already carries the declaration keeps building.', 'Remove the package from "dependencies". A library that peer-depends on the renderer is already '
+        + 'satisfied by the platform copy, so the declaration buys nothing — and it gives the package '
+        + 'manager a second copy to reconcile, which is how an unrelated later install starts failing.', CHECKED_BY_EVERY_COMPILE),
+    define('XE1211', 'The renderer a package manager resolves for this project is a different version '
+        + 'from the one the platform bundles. The message names both versions and which of them ships. '
+        + 'A second copy usually arrives when a package manager hoists an older peer of some dependency '
+        + 'to the project root; nothing in the application selected it, and nothing in the application '
+        + 'is served by it.', 'Nothing is required — the artifact contains the platform copy either way. To make the tree '
+        + 'agree with the artifact, remove any renderer package from "dependencies" and reinstall.', CHECKED_BY_EVERY_COMPILE),
+    define('XE1212', 'xeer.app.json acknowledges a dependency as untyped that package.json does not '
+        + 'declare in dependencies. The acknowledgment describes the type declarations of a package this '
+        + 'application never said it uses, so either the declaration is missing or the acknowledgment '
+        + 'outlived the dependency it was written for.', 'Declare the package in package.json "dependencies" if the application imports it, or remove it '
+        + 'from "untypedDependencies" in xeer.app.json if it does not.', CHECKED_BY_EVERY_COMPILE),
+    define('XE1213', 'xeer.app.json acknowledges a dependency as untyped, but it already resolves to '
+        + 'TypeScript declarations — its own, or a separately installed @types companion. The '
+        + 'acknowledgment is ignored rather than applied, because generating an ambient declaration for '
+        + 'it would not be redundant: an ambient declaration overrides module resolution, so it would '
+        + 'replace real declarations with `any` and a call with the wrong argument types would compile '
+        + 'clean. The real declarations still apply.', 'Remove the package from "untypedDependencies" in xeer.app.json. Its own declarations are what '
+        + 'the application is being checked against either way.', CHECKED_BY_EVERY_COMPILE),
+    define('XE1214', 'xeer.app.json acknowledges a dependency as shipping no TypeScript declarations, '
+        + 'so it and every subpath under it are typed as `any`. Informational, and emitted on every '
+        + 'check for as long as the acknowledgment stands: the acknowledgment is a deliberate hole in '
+        + 'type safety, and one that is never reported is one nobody removes.', 'Nothing is required. If declarations are published — conventionally at @types/<name>, with a '
+        + 'scope flattened as @types/scope__name — install them and remove the acknowledgment.', CHECKED_BY_EVERY_COMPILE),
     define('XE1300', 'The default server export is not a statically inspectable defineServer({...}) call, '
         + 'or an operation group is not a literal object.', 'Export `default defineServer({ queries: {...}, mutations: {...}, endpoints: {...} })` with literal '
         + 'object members: no spreads, shorthand, computed keys, or wrappers.', CHECKED_BY_EVERY_COMPILE),
@@ -210,9 +278,11 @@ export const DIAGNOSTIC_DEFINITIONS = [
         + '`budgets.clientBundleBytes` when declared. The message attributes bytes to the packages that '
         + 'contributed them.', 'Read the attribution in the message and remove or replace the heaviest dependency, or raise '
         + '`budgets.clientBundleBytes` (bounded by the 10 MiB module ceiling) if the size is intended.', BUILT_BY_EVERY_BUILD),
-    define('XE1406', 'The minified client JavaScript bundle exceeds the fixed '
-        + `${Math.round(CLIENT_BUNDLE_ADVISORY_BUDGET_BYTES / 1024)} KiB advisory tier. The build still `
-        + 'succeeds; this is a warning with per-package byte attribution.', 'Nothing is required. If the growth is unintended, the attribution in the message names the '
+    define('XE1406', 'The application\'s own share of the minified client JavaScript bundle exceeds '
+        + `the fixed ${Math.round(CLIENT_BUNDLE_ADVISORY_BUDGET_BYTES / 1024)} KiB advisory tier — the `
+        + 'bundle minus the platform-selected renderer, which an application neither declares nor can '
+        + 'remove. The build still succeeds; this is a warning with per-package byte attribution. The '
+        + 'error tier (XE1405) is measured over the whole bundle instead.', 'Nothing is required. If the growth is unintended, the attribution in the message names the '
         + 'packages to reconsider before the error tier is reached.', BUILT_BY_EVERY_BUILD),
     define('XE1501', 'Bundling failed after the module graph and types were accepted.', 'Read the bundler message in `message`. It usually names a syntax construct the target does not '
         + 'support, rather than a Xeer rule.', BUILT_BY_EVERY_BUILD),
@@ -224,11 +294,15 @@ export const DIAGNOSTIC_DEFINITIONS = [
         + 'Neither zone has Node builtins to offer, so the platform refuses the bundle rather than '
         + 'shipping one that throws at load time. This is a property of the dependency chain and so is '
         + 'found at build, not at check.', BUILT_BY_EVERY_BUILD),
-    define('XE1503', 'The client bundle would contain a second physical copy of the managed renderer. '
-        + 'Bare renderer imports are pinned to the platform anchor, so a second copy means a path-based '
-        + 'escape: a relative or absolute import reaching into some node_modules copy of the renderer.', 'Import the renderer by its bare specifier (preact, preact/hooks, react, …) so the platform pins '
-        + 'it to one instance. Two renderer copies means two options singletons — hooks and components '
-        + 'silently stop sharing state.', 
+    define('XE1503', 'The client bundle would contain a renderer it must not: a second physical copy '
+        + 'of the one the application selected, or the one it did not. Bare renderer imports are pinned '
+        + 'to the platform anchor, so a second copy means a path-based escape — a relative or absolute '
+        + 'import reaching into some node_modules copy of the renderer. The unselected renderer is '
+        + 'installed by the platform whichever provider an application chooses, so only this rule keeps '
+        + 'it out of the bundle.', 'Import the renderer by its bare specifier (preact, preact/hooks, react, …) so the platform pins '
+        + 'it to one instance, and import only the renderer client.runtime.provider selects. Two copies '
+        + 'of one renderer means two options singletons — hooks and components silently stop sharing '
+        + 'state; two different renderers means two reconcilers rendering into one tree.', 
     // The analyzer admits path imports against the managed-renderer roots, so the escape is reported
     // at the user's own import during `check`; the build's metafile verification reports the same
     // code for the same defect one stage later, when it survives as a second bundled copy.
@@ -240,6 +314,10 @@ export const DIAGNOSTIC_DEFINITIONS = [
     define('XE1604', 'The manifest could not be watched for changes, so edits to it will not rebuild the '
         + 'preview. Everything already serving keeps serving.', 'On Linux this is normally an exhausted inotify allowance: raise `fs.inotify.max_user_watches` and '
         + '`fs.inotify.max_user_instances`. Restart `xeer dev` afterwards.', ['dev']),
+    define('XE1605', 'A rebuild changed `client.runtime` — the UI provider — under a running dev server. '
+        + 'The preview keeps serving the renderer it started with rather than serving the new manifest '
+        + 'through the old one.', 'Stop and restart `xeer dev`. The dev server resolves its JSX runtime, its renderer aliases, and '
+        + 'its Fast Refresh transform once, at startup; `xeer build` and `xeer preview` need no restart.', ['dev']),
     // `xeer build` runs the same verification `preview`, `test` and `deploy` gate on, against the
     // artifact it has just written, so these four codes are build surfaces too: a build that cannot
     // be previewed is reported as a failed build rather than a success (issue #56).
@@ -322,6 +400,9 @@ export const DIAGNOSTIC_DEFINITIONS = [
     define('XE3002', '`--template` named a scaffold that does not exist. Refused before the target '
         + 'directory is read, so nothing was written.', 'Use one of the names the message lists, or omit --template for the default. `xeer --help` '
         + 'describes each template.', ['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: every template scaffolds on either provider from the same client sources.', ['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']),
@@ -330,6 +411,9 @@ export const DIAGNOSTIC_DEFINITIONS = [
     define('XE5000', 'An auth subcommand was invoked with wrong arguments.', 'Use `xeer auth <login|status|logout|as|clear>`; `auth as` takes alice or bob.', ['auth']),
     define('XE5001', 'The --control-url value is not an exact HTTP(S) origin, or is plain HTTP off localhost.', 'Pass an origin such as https://control.example.com with no path.', ['auth', 'deploy']),
     define('XE5002', 'No valid builder credential is stored.', 'A human must run `xeer auth login` and approve the shown code. An agent cannot complete sign-in.', ['auth', 'deploy']),
+    define('XE5003', 'XEER_SERVICE_TOKEN is set to something that is not a service token, so no command '
+        + 'that authenticates can present a credential. The value is never echoed; it is a live secret.', 'Set it to `xst_` followed by 43 characters — `xeer token create --name <label>` issues one — or '
+        + 'unset it to fall back to the credential `xeer auth login` stored on this machine.', ['auth', 'deploy']),
     define('XE5004', 'The control plane returned a response the CLI will not trust.', 'Retry; if it persists the control plane is misconfigured or unreachable. Not a project defect.', ['auth']),
     define('XE5005', 'The device authorization expired before sign-in completed.', 'Run `xeer auth login` again and approve promptly.', ['auth']),
     define('XE5008', 'The stored CLI credential file is unreadable or invalid.', 'Run `xeer auth logout` and sign in again.', ['auth', 'deploy']),

package/vendor/spec/editor-settings.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The editor settings a scaffolded application carries.
+ *
+ * Separate from the type-check profile beside it, and the split is about what each answers. That
+ * module states the compiler *options* both tools enforce; this one states which tsserver binary the
+ * editor runs them with. `tsconfig.json` already makes the editor and `xeer check` apply the same
+ * rules — this is what makes them apply those rules with the same compiler, which matters because
+ * TypeScript changes inference, narrowing, and its check set in every minor.
+ *
+ * The settings file is only half of that. An editor can only offer a workspace TypeScript that
+ * exists, and under pnpm's isolated layout `node_modules/typescript` exists *only* because the
+ * application declares `typescript` as a direct devDependency. Without that declaration the path
+ * below names nothing.
+ *
+ * Both spellings of both settings, because the names moved. VS Code renamed `typescript.tsdk` and
+ * `typescript.enablePromptUseWorkspaceTsdk` to `js/ts.tsdk.path` and
+ * `js/ts.tsdk.promptToUseWorkspaceVersion`, keeping a deprecation alias — so the pairs cannot
+ * disagree — while the forks lag the rename. Writing one pair alone either leaves a deprecation
+ * squiggle in current VS Code or leaves the setting inert in a fork.
+ *
+ * Serialized here rather than returned as an object, for the same reason `applicationTsconfigDocument`
+ * is: what has to match is the file, and two callers stringifying one object with different options
+ * produce two different files.
+ */
+export declare const APPLICATION_TSDK_PATH: "node_modules/typescript/lib";
+export declare function vscodeSettingsDocument(): string;

package/vendor/spec/editor-settings.js

@@ -0,0 +1,33 @@
+/**
+ * The editor settings a scaffolded application carries.
+ *
+ * Separate from the type-check profile beside it, and the split is about what each answers. That
+ * module states the compiler *options* both tools enforce; this one states which tsserver binary the
+ * editor runs them with. `tsconfig.json` already makes the editor and `xeer check` apply the same
+ * rules — this is what makes them apply those rules with the same compiler, which matters because
+ * TypeScript changes inference, narrowing, and its check set in every minor.
+ *
+ * The settings file is only half of that. An editor can only offer a workspace TypeScript that
+ * exists, and under pnpm's isolated layout `node_modules/typescript` exists *only* because the
+ * application declares `typescript` as a direct devDependency. Without that declaration the path
+ * below names nothing.
+ *
+ * Both spellings of both settings, because the names moved. VS Code renamed `typescript.tsdk` and
+ * `typescript.enablePromptUseWorkspaceTsdk` to `js/ts.tsdk.path` and
+ * `js/ts.tsdk.promptToUseWorkspaceVersion`, keeping a deprecation alias — so the pairs cannot
+ * disagree — while the forks lag the rename. Writing one pair alone either leaves a deprecation
+ * squiggle in current VS Code or leaves the setting inert in a fork.
+ *
+ * Serialized here rather than returned as an object, for the same reason `applicationTsconfigDocument`
+ * is: what has to match is the file, and two callers stringifying one object with different options
+ * produce two different files.
+ */
+export const APPLICATION_TSDK_PATH = 'node_modules/typescript/lib';
+export function vscodeSettingsDocument() {
+    return `${JSON.stringify({
+        'js/ts.tsdk.path': APPLICATION_TSDK_PATH,
+        'js/ts.tsdk.promptToUseWorkspaceVersion': true,
+        'typescript.tsdk': APPLICATION_TSDK_PATH,
+        'typescript.enablePromptUseWorkspaceTsdk': true,
+    }, null, 2)}\n`;
+}