@ultimat3/cli 24.0.0 → 25.1.0

package/src/templates/github/ci.yml.ts

@@ -1,19 +1,25 @@
-// The CI half of what `x new` writes: one workflow that runs the app's OWN two commands.
+// The CI half of what `x new` writes: the gate workflow that runs the app's OWN two commands, and
+// the image workflow (`image.yml.ts`) that publishes only what that gate passed.
 //
 // Nothing under `templates/` emitted `.github` until this file, so every scaffolded app started
-// life with a gate that ran on exactly one machine — the author's. The two commands are `bin/setup`
-// and `bin/check` and NOT a restatement of their steps: a workflow that spelled out `bun install`,
-// `x db migrate`, `x build` and `x verify` is a second definition of the gate, free to drift from
-// the scripts a human runs, and axiom 1 has one way to do each thing. `bin/check` is also not a
-// synonym for `x verify` — it BUILDS first, and the build is what makes the gate's `budgets` step
+// life with a gate that ran on exactly one machine — the author's. The two commands are
+// `bun run setup` and `bun run check` and NOT a restatement of their steps: a workflow that spelled
+// out `bun install`, `x db migrate`, `x build` and `x verify` is a second definition of the gate,
+// free to drift from the scripts a human runs, and axiom 1 has one way to do each thing.
+// `bun run check` is also not a synonym for `x verify` — it BUILDS first, and the build is what makes the gate's `budgets` step
 // measurable rather than X_BUDGET_UNMEASURED.
 
 import { REQUIRED_BUN } from '../../app-root';
 import type { GeneratedFile, NameSet } from '../naming';
+import { IMAGE_WORKFLOW_PATH, imageWorkflow } from './image.yml';
+import { RUNS_ON } from './runner';
 
 /** Where the workflow lands. GitHub reads this path and no other. */
 export const CI_WORKFLOW_PATH = '.github/workflows/ci.yml';
 
+/** The workflow's `name:` — what `image.yml`'s `workflow_run` trigger waits on, spelled once. */
+const CI_WORKFLOW_NAME = 'ci';
+
 /**
  * Pinned by commit SHA with the version in the trailing comment, because this step runs before any
  * code of yours does and `@v2` is a tag its owner can move. `actions/*` follows its major tag
@@ -22,19 +28,19 @@ export const CI_WORKFLOW_PATH = '.github/workflows/ci.yml';
  */
 const SETUP_BUN = 'oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0';
 
-const ci = (app: NameSet): string => `name: ci
+const ci = (app: NameSet): string => `name: ${CI_WORKFLOW_NAME}
 
 # The gate for ${app.kebab}: the same two commands \`README.md\` tells a human to run, in the same
 # order, on a machine that has never seen this repository. A check that exists only in CI is one
 # nobody can reproduce locally, and a CI file that restates the gate's steps is a second gate.
 #
-# \`bin/check\` is \`x build --target static\` and THEN \`x verify\`. The build is not a convenience:
-# the gate's \`budgets\` step compares declared limits against measured bytes in
+# \`bun run check\` is \`x build --target static\` and THEN \`x verify\`. The build is not a
+# convenience: the gate's \`budgets\` step compares declared limits against measured bytes in
 # \`.x/build-stats.json\`, so a run with no build reports X_BUDGET_UNMEASURED. Run \`x verify\` here
 # instead and this workflow is red for a reason that has nothing to do with the commit.
 #
-# No \`services:\` block, deliberately — \`bin/setup\` brings up embedded Postgres in-process, so
-# there is nothing to provision and nothing to wait on. Add one the day this app needs a real
+# No \`services:\` block, deliberately — \`bun run setup\` brings up embedded Postgres in-process,
+# so there is nothing to provision and nothing to wait on. Add one the day this app needs a real
 # server, beside the \`DATABASE_URL\` that selects it.
 
 # EVERY push, not just the default branch's. \`x new\` runs a plain \`git init\` and takes whatever
@@ -61,7 +67,8 @@ jobs:
     # the push run already gates that exact tree — so the pull_request run is skipped, not paid for
     # twice. A pull request from a FORK fires no push here, and it still runs.
     if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository
-    runs-on: ubuntu-latest
+    # A free GitHub-hosted runner unless the repository variable \`CI_RUNNER\` names another label.
+    runs-on: ${RUNS_ON}
     # A bound on a HANG, not on cost: a step that never returns holds a runner until GitHub's
     # six-hour default expires, and the failure is invisible for all six of them.
     timeout-minutes: 20
@@ -74,19 +81,22 @@ jobs:
           # whoever took the app at its word. Never \`latest\`: a Bun minor landing unannounced is a
           # runtime change nobody chose.
           bun-version: '${REQUIRED_BUN}'
-      # Bun's download cache, keyed on the lockfile: \`bin/setup\`'s install then links from disk
-      # instead of fetching every package again on every run.
+      # Bun's download cache, keyed on the lockfile: \`bun run setup\`'s install then links from
+      # disk instead of fetching every package again on every run.
       - uses: actions/cache@v6
         with:
           path: ~/.bun/install/cache
           key: bun-\${{ runner.os }}-\${{ hashFiles('bun.lock') }}
           restore-keys: bun-\${{ runner.os }}-
       # Two steps rather than one \`&&\`, so the log names which half failed and times each.
-      - run: bin/setup
-      - run: bin/check
+      - run: bun run setup
+      - run: bun run check
 `;
 
-/** The CI a new app is born with, in the order a reader meets it. */
+/** The CI a new app is born with, in the order a reader meets it: the gate, then the image. */
 export function githubFiles(app: NameSet): readonly GeneratedFile[] {
-  return [{ path: CI_WORKFLOW_PATH, contents: ci(app) }];
+  return [
+    { path: CI_WORKFLOW_PATH, contents: ci(app) },
+    { path: IMAGE_WORKFLOW_PATH, contents: imageWorkflow(CI_WORKFLOW_NAME) },
+  ];
 }

package/src/templates/github/image.yml.ts

@@ -0,0 +1,92 @@
+// The image half of what `x new` writes under `.github/`: publish `docker/Dockerfile` to the
+// repository's own GitHub Container Registry, only for a commit `ci.yml` already passed on the
+// default branch. It runs no gate of its own — a second gate is a second definition of one — and
+// it deploys nothing: the image digest is the handoff, axiom 7's one deploy artifact.
+
+import { DEFAULT_RUNNER } from './runner';
+
+/** Where the workflow lands, beside the gate it waits on. */
+export const IMAGE_WORKFLOW_PATH = '.github/workflows/image.yml';
+
+/** The Dockerfile `containerFiles` writes — the one image every role runs. */
+export const IMAGE_DOCKERFILE = 'docker/Dockerfile';
+
+/** `gate` is the `name:` of the workflow whose verdict this one waits on — `ci.yml`'s own. */
+export const imageWorkflow = (gate: string): string => `name: image
+
+# Builds ${IMAGE_DOCKERFILE} and pushes it to ghcr.io/<owner>/<repo>, tagged \`sha-<7>\` and the full
+# commit SHA — never \`latest\`, a pointer a late run moves backwards. Only GITHUB_TOKEN: GHCR takes
+# the job's own token, so there is no secret to create.
+#
+# Triggered by \`${gate}\` FINISHING, never by the push both would start from: a second
+# workflow on the same push is not a dependency, and this one must publish only what the gate
+# judged. A \`workflow_run\` has no branch filter here for the reason ci.yml's \`on:\` has none —
+# \`x new\` never decided what the default branch is called — so the job's \`if:\` asks GitHub.
+on:
+  workflow_run:
+    workflows: [${gate}]
+    types: [completed]
+
+# One publish per commit, never cancelled mid-push: a half-pushed manifest is worse than a queue.
+concurrency:
+  group: image-\${{ github.event.workflow_run.head_sha }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  publish:
+    # A green gate, from a push (never a fork's pull request, whose head would build with a
+    # registry token in scope), to the default branch of THIS repository.
+    if: >-
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.event == 'push' &&
+      github.event.workflow_run.head_branch == github.event.repository.default_branch &&
+      github.event.workflow_run.head_repository.full_name == github.repository
+    # NOT \`vars.CI_RUNNER\`: the gate may move to any runner, but this job needs bash (\`\${SHA::7}\`,
+    # \`\${GITHUB_REPOSITORY,,}\`) and a Docker daemon, and a Windows or self-hosted label may have
+    # neither — a green gate would then publish nothing. The free GitHub-hosted Linux runner has both.
+    runs-on: ${DEFAULT_RUNNER}
+    defaults:
+      run:
+        shell: bash
+    timeout-minutes: 30
+    steps:
+      # The commit the gate judged, not the tip of the branch when this run started.
+      - uses: actions/checkout@v7
+        with:
+          ref: \${{ github.event.workflow_run.head_sha }}
+          persist-credentials: false
+      # GHCR refuses an upper-case repository path, and \`github.repository\` keeps the owner's case.
+      - name: name the image
+        id: image
+        env:
+          SHA: \${{ github.event.workflow_run.head_sha }}
+        run: |
+          repo="ghcr.io/\${GITHUB_REPOSITORY,,}"
+          {
+            echo "short=\${repo}:sha-\${SHA::7}"
+            echo "full=\${repo}:\${SHA}"
+          } >> "$GITHUB_OUTPUT"
+      # The plain docker CLI every GitHub-hosted runner ships — no third-party action holds the
+      # token. BUILD_ID is the commit, the stamp ${IMAGE_DOCKERFILE} documents.
+      - name: log in to ghcr.io
+        env:
+          TOKEN: \${{ github.token }}
+        run: printf '%s' "$TOKEN" | docker login ghcr.io -u "$GITHUB_ACTOR" --password-stdin
+      - name: build
+        env:
+          SHA: \${{ github.event.workflow_run.head_sha }}
+          SHORT: \${{ steps.image.outputs.short }}
+          FULL: \${{ steps.image.outputs.full }}
+        run: docker build -f ${IMAGE_DOCKERFILE} --build-arg "BUILD_ID=$SHA" -t "$SHORT" -t "$FULL" .
+      - name: push
+        env:
+          SHORT: \${{ steps.image.outputs.short }}
+          FULL: \${{ steps.image.outputs.full }}
+        run: |
+          docker push "$SHORT"
+          docker push "$FULL"
+`;

package/src/templates/github/runner.ts

@@ -0,0 +1,18 @@
+// The `runs-on:` the workflows `x new` writes: the gate on a free GitHub-hosted runner unless the
+// repository says otherwise, the image build always on that default — it needs bash and Docker,
+// which a configured label need not have. Spelled once so the two cannot drift.
+
+/** The repository variable that overrides the runner — Settings → Secrets and variables → Actions. */
+export const RUNNER_VARIABLE = 'CI_RUNNER';
+
+/**
+ * The default label. GitHub-hosted and free for a public repository; a paid or self-hosted runner
+ * is a choice an owner makes by setting the variable, never one a scaffold makes for them.
+ */
+export const DEFAULT_RUNNER = 'ubuntu-latest';
+
+/**
+ * `vars.*` is an expression context `runs-on` accepts, and an unset variable reads as `''`, so the
+ * `||` falls through to the default on every repository that never set one.
+ */
+export const RUNS_ON = `\${{ vars.${RUNNER_VARIABLE} || '${DEFAULT_RUNNER}' }}`;

package/src/templates/guard-bare-error.ts

@@ -28,9 +28,11 @@ const CODE = '${CODE}';
 /**
  * A THROW, never a construction. \`new Error(…)\` handed to something as INPUT is legitimate — a
  * test fixture, an \`AbortSignal\` reason, a rejection this module is passing along — and only the
- * throw is this module stating its own verdict.
+ * throw is this module stating its own verdict. \`new\` is optional — \`throw Error(…)\` builds the
+ * same bare error — and every builtin class is listed: each carries no code, cause or fix.
  */
-const BARE_THROW = /\\bthrow\\s+new\\s+(Error|TypeError|RangeError|SyntaxError)\\s*\\(/g;
+const BARE_THROW =
+  /\\bthrow\\s+(?:new\\s+)?(Error|TypeError|RangeError|SyntaxError|ReferenceError|EvalError|URIError|AggregateError)\\s*\\(/g;
 
 export interface SourceFile {
   /** App-root-relative POSIX path, so the finding names the file an author opens. */
@@ -101,6 +103,18 @@ unitTest('TypeError and RangeError are the same rule', () => {
   expect(bareThrows(file("throw new RangeError('x');"))).toHaveLength(1);
 });
 
+unitTest('a throw with no \`new\` builds the same bare Error', () => {
+  expect(bareThrows(file("throw Error('no post');"))).toHaveLength(1);
+  expect(bareThrows(file("throw TypeError('x');"))).toHaveLength(1);
+});
+
+unitTest('every builtin Error class is the same rule', () => {
+  for (const name of ['SyntaxError', 'ReferenceError', 'EvalError', 'URIError', 'AggregateError']) {
+    expect(bareThrows(file(\`throw new \${name}('x');\`))).toHaveLength(1);
+  }
+  expect(bareThrows(file("throw new MyTypeError('x');"))).toEqual([]);
+});
+
 unitTest('an UltimateError subclass is what the rule asks for', () => {
   expect(bareThrows(file('throw new PostError(missingPost(id));'))).toEqual([]);
 });

package/src/templates/guard-unzoned-date.ts

@@ -25,8 +25,29 @@ import type { Finding, Guard } from '@ultimat3/cli';
 /** The app owns the codes its own conventions raise — this one is named for the guard. */
 const CODE = '${CODE}';
 
-/** Every call whose output depends on a zone. The \`(\` is the start of the argument list. */
-const FORMATTER = /(?:\\.toLocale(?:Date|Time)?String|Intl\\.DateTimeFormat)\\s*\\(/g;
+/**
+ * Every call whose output depends on a zone. The \`(\` is the start of the argument list.
+ * \`.toDateString()\` / \`.toTimeString()\` take no options at all: always the host's zone.
+ */
+const FORMATTER =
+  /(?:\\.toLocale(?:Date|Time)?String|\\.to(?:Date|Time)String|Intl\\.DateTimeFormat)\\s*\\(/g;
+
+/**
+ * A \`timeZone\` KEY — written \`timeZone: z\`, the shorthand \`{ timeZone }\`, or quoted
+ * \`{ 'timeZone': z }\`, which is the same property. A substring test read \`timeZoneName\`, which
+ * only labels the zone the host already chose, as a zone. A quoted key takes only \`:\` — a
+ * quoted \`'timeZone',\` is a string in a list, not an option.
+ */
+const ZONED = /\\btimeZone\\s*[:,}]|(['"])timeZone\\1\\s*:/;
+
+/**
+ * The zoned call that replaces a formatter with no zone option. A \`Map\`, not an object: an
+ * object literal's prototype answers \`toLocaleString\`, and the bare call would read as one.
+ */
+const ZONED_FORM: ReadonlyMap<string, string> = new Map([
+  ['toDateString', 'toLocaleDateString'],
+  ['toTimeString', 'toLocaleTimeString'],
+]);
 
 export interface SourceFile {
   /** App-root-relative POSIX path, so the finding names the file an author opens. */
@@ -72,19 +93,24 @@ export function unzonedDates(files: readonly SourceFile[]): readonly Finding[] {
     const text = blank(file.source);
     for (const match of text.matchAll(FORMATTER)) {
       const open = match.index + match[0].length - 1;
-      if (argumentsOf(text, open).includes('timeZone')) continue;
+      if (ZONED.test(argumentsOf(text, open))) continue;
       const line = lineOf(text, match.index);
       // The bare \`.toLocaleString(\` is ALSO \`Number.prototype.toLocaleString\`, and a regex cannot
       // tell a count from a date. The match stands — a date formatted this way is the defect this
       // guard exists for — but the fix names the number exit too, because \`{ timeZone }\` is not
       // one: a number ignores it, and an author following the fix verbatim would ship a lie.
       const bare = match[0].trim() === '.toLocaleString(';
+      const called = match[0].replaceAll(/[.(\\s]/g, '');
+      const zoned = ZONED_FORM.get(called);
       findings.push({
         code: CODE,
         cause: \`\${file.path}:\${line} calls \${match[0].trim()}) with no timeZone — it formats in whatever zone the process happens to run in, so one row reads as two different days across two containers\`,
-        fix: bare
-          ? \`in \${file.path}: a Date → pass an explicit IANA zone, at.toLocaleString(locale, { timeZone: 'UTC' }); a NUMBER → new Intl.NumberFormat(locale).format(n) instead — then: x verify\`
-          : \`pass an explicit IANA zone in \${file.path} — toLocaleDateString(locale, { timeZone: 'UTC' }) — then: x verify\`,
+        fix:
+          zoned !== undefined
+            ? \`\${called}() has no zone option — in \${file.path} call \${zoned}(locale, { timeZone: 'UTC' }) instead — then: x verify\`
+            : bare
+              ? \`in \${file.path}: a Date → pass an explicit IANA zone, at.toLocaleString(locale, { timeZone: 'UTC' }); a NUMBER → new Intl.NumberFormat(locale).format(n) instead — then: x verify\`
+              : \`pass an explicit IANA zone in \${file.path} — toLocaleDateString(locale, { timeZone: 'UTC' }) — then: x verify\`,
         at: file.path,
       });
     }
@@ -143,6 +169,30 @@ unitTest('the bare toLocaleString names the number exit, since a count matches i
   expect(dated[0]?.fix).not.toContain('Intl.NumberFormat');
 });
 
+unitTest('timeZoneName labels the zone, it does not choose one', () => {
+  const named = "at.toLocaleString('en-US', { timeZoneName: 'short' });";
+  expect(unzonedDates(file(named))).toHaveLength(1);
+  const shorthand =
+    "new Intl.DateTimeFormat('en-US', { timeZoneName: 'short', timeZone }).format(at);";
+  expect(unzonedDates(file(shorthand))).toEqual([]);
+});
+
+unitTest('a quoted key is the same key, and a quoted timeZoneName is still only a label', () => {
+  expect(unzonedDates(file("at.toLocaleString('en-US', { 'timeZone': 'UTC' });"))).toEqual([]);
+  expect(unzonedDates(file('at.toLocaleString("en-US", { "timeZone": zone });'))).toEqual([]);
+  const label = "at.toLocaleString('en-US', { 'timeZoneName': 'short' });";
+  expect(unzonedDates(file(label))).toHaveLength(1);
+});
+
+unitTest('toDateString and toTimeString name the zoned call', () => {
+  const date = unzonedDates(file('const shown = at.toDateString();'));
+  expect(date).toHaveLength(1);
+  expect(date[0]?.fix).toContain('toLocaleDateString(locale');
+  const time = unzonedDates(file('const shown = at.toTimeString();'));
+  expect(time).toHaveLength(1);
+  expect(time[0]?.fix).toContain('toLocaleTimeString(locale');
+});
+
 unitTest('a commented-out call is a note, not a call', () => {
   expect(unzonedDates(file("// at.toLocaleDateString('en-US');"))).toEqual([]);
 });

package/src/templates/index.ts

@@ -40,7 +40,7 @@ export { claudeAgentFiles } from './scaffold-claude-agents';
 export { claudeCommandFiles } from './scaffold-claude-commands';
 export { containerFiles } from './scaffold-container';
 export { dashboardFiles } from './scaffold-dashboard';
-export { docsFiles, EXECUTABLE_FILES } from './scaffold-docs';
+export { docsFiles } from './scaffold-docs';
 export { entryFiles } from './scaffold-entries';
 export { errorPageFiles, PWA_COLORS } from './scaffold-errors';
 // The guards `x new` ships — `SHIPPED_GUARD_NAMES` is the list — distinct from `guardFiles` above,

package/src/templates/job-body-test.ts

@@ -28,7 +28,7 @@ const HEADER = (
 const storedRowTest = (name: NameSet): string => `
 unitTest('a stored row is loaded, then processed, once each', async ({ runJobs }) => {
   const draft = { orgId, title: 'kept', price: { minor: 0, currency: 'USD' } };
-  const row = await runWithContext(createContext({ actor: member }), () => repo.insert(draft));
+  const row = await runWithContext(ctxOf({ actor: member }), () => repo.insert(draft));
   const trace = await runJobs(${name.camel}, { id: row.id, orgId });
   expect(trace.executions.map((run) => run.outcome)).toEqual(['completed']);
   expect(trace.executions[0]?.result).toEqual({ skipped: false });
@@ -41,7 +41,7 @@ const scopedBodyTest = (name: NameSet, shape: JobBodyShape): string => `${HEADER
 ${sortedImports([
   ...(shape.storesRow
     ? [
-        "import { createContext, runWithContext } from '@ultimat3/core';",
+        "import { ctxOf, runWithContext } from '@ultimat3/core';",
         "import { testActor } from '@ultimat3/policy';",
         "import { afterEach, expect, unitTest } from '@ultimat3/testing';",
         `import { driver } from '${shape.dbModule}';`,

package/src/templates/job.ts

@@ -129,7 +129,7 @@ const jobTest = (
   name: NameSet,
 ): string => `// ${name.camel} against a real driver: enqueue, drain, assert. Retries and the dead-letter path
 // are the framework's, so what this pins is that THIS job's steps run and are idempotent.
-import { createMemoryDriver, resetJobDriver, setJobDriver } from '@ultimat3/jobs';
+import { memoryJobDriver, resetJobDriver, setJobDriver } from '@ultimat3/jobs';
 import { afterAll, beforeAll, expect, jobTest } from '@ultimat3/testing';
 import { ${name.camel} } from './${name.kebab}';
 
@@ -143,7 +143,7 @@ const expectedKey = \`${name.kebab}:\${id}\`;
 // The driver is process-global, so it is installed and released around this file rather than
 // left behind for whichever test happens to run next.
 beforeAll(() => {
-  setJobDriver(createMemoryDriver());
+  setJobDriver(memoryJobDriver());
 });
 afterAll(resetJobDriver);
 
@@ -186,7 +186,7 @@ const neutralJobTest = (
   name: NameSet,
 ): string => `// ${name.camel} against a real driver: enqueue, drain, assert. Retries and the dead-letter path
 // are the framework's, so what this pins is that THIS job's steps run and are idempotent.
-import { createMemoryDriver, resetJobDriver, setJobDriver } from '@ultimat3/jobs';
+import { memoryJobDriver, resetJobDriver, setJobDriver } from '@ultimat3/jobs';
 import { afterAll, beforeAll, expect, jobTest } from '@ultimat3/testing';
 import { ${name.camel} } from './${name.kebab}';
 
@@ -199,7 +199,7 @@ const expectedKey = \`${name.kebab}:\${id}\`;
 // The driver is process-global, so it is installed and released around this file rather than
 // left behind for whichever test happens to run next.
 beforeAll(() => {
-  setJobDriver(createMemoryDriver());
+  setJobDriver(memoryJobDriver());
 });
 afterAll(resetJobDriver);
 
@@ -243,13 +243,13 @@ const taskTest = (
   jobName: NameSet,
 ): string => `// ${name.camel}: the schedule it declares, the timezone it declares it in, and the job it
 // enqueues. A cron with no explicit IANA zone fires at a different hour twice a year.
-import { createMemoryDriver, resetJobDriver, setJobDriver } from '@ultimat3/jobs';
+import { memoryJobDriver, resetJobDriver, setJobDriver } from '@ultimat3/jobs';
 import { afterAll, beforeAll, expect, jobTest } from '@ultimat3/testing';
 import { ${jobName.camel} } from '../jobs/${jobName.kebab}';
 import { ${name.camel} } from './${name.kebab}';
 
 beforeAll(() => {
-  setJobDriver(createMemoryDriver());
+  setJobDriver(memoryJobDriver());
 });
 afterAll(resetJobDriver);
 

package/src/templates/query.ts

@@ -63,7 +63,7 @@ const queryTest = (name: NameSet, feature: NameSet, shape: ReadShape): string =>
   const subscribes = live && shape.storesRow;
   const imports = subscribes
     ? [
-        "import { createContext, frozenClock, runWithContext } from '@ultimat3/core';",
+        "import { ctxOf, frozenClock, runWithContext } from '@ultimat3/core';",
         `import { afterEach, expect, ${wrapper} } from '@ultimat3/testing';`,
         `import { driver } from '${shape.dbModule}';`,
       ]
@@ -128,10 +128,11 @@ ${wrapper}('${name.camel} denies an orgless actor before a read', async () => {
   expect(denied).toBeUltimateError('X_FORBIDDEN');
 });
 
-${wrapper}('${name.camel} exposes one MCP tool that reads, and never writes', () => {
-  // Same policy object on both surfaces — an agent cannot reach a different authz path.
-  expect(target.tool().policy).toBe(target.policy);
-  expect(target.tool().mutates).toBe(false);
+${wrapper}('${name.camel} is offered to agents as a read', () => {
+  // \`@ultimat3/mcp\`'s \`toolFrom\` serves this block as a read (\`mutates: false\`), through
+  // \`.as()\` under this same policy — an agent cannot reach a different authz path.
+  expect(target.kind).toBe('query');
+  expect(target.mcp?.expose).toBe(true);
 });
 ${subscribes ? subscribeTest(name, feature) : ''}`;
 };
@@ -160,7 +161,7 @@ const clock = frozenClock('2026-01-01T00:00:00.000Z');
 
 const store = (org: string, title: string) => {
   const draft = { orgId: org, title, price: { minor: 0, currency: 'USD' } };
-  const writer = createContext({ actor: testActor('writer', { orgId: org }).actor, clock });
+  const writer = ctxOf({ actor: testActor('writer', { orgId: org }).actor, clock });
   return runWithContext(writer, () => repo.insert(draft));
 };
 
@@ -224,7 +225,7 @@ const clock = frozenClock('2026-01-01T00:00:00.000Z');
 
 const store = (owner: string, title: string) => {
   const draft = { orgId: owner, title, price: { minor: 0, currency: 'USD' } };
-  const writer = createContext({ actor: testActor('writer', { orgId: owner }).actor, clock });
+  const writer = ctxOf({ actor: testActor('writer', { orgId: owner }).actor, clock });
   return runWithContext(writer, () => repo.insert(draft));
 };
 
@@ -287,7 +288,7 @@ ${shape.storesRow ? storedRowsTest() : ''}`;
 /** The imports the read cases need, over whatever the file they land in already imports. */
 const readImports = (shape: ReadShape, testing: readonly string[]): readonly string[] => [
   ...(shape.storesRow
-    ? ["import { createContext, frozenClock, runWithContext } from '@ultimat3/core';"]
+    ? ["import { ctxOf, frozenClock, runWithContext } from '@ultimat3/core';"]
     : []),
   `import { ${[...(shape.storesRow ? ['afterEach'] : []), ...testing].join(', ')} } from '@ultimat3/testing';`,
   ...(shape.storesRow ? [`import { driver } from '${shape.dbModule}';`] : []),

package/src/templates/resource-page.ts

@@ -12,15 +12,17 @@ import { LINE_WIDTH } from './wrap';
 
 /**
  * The page's JS budget — MEASURED, never a ceiling picked to pass. `x build --target static` on a
- * fresh `x new` app with `x g resource widget`, Bun 1.4.0 (CI's pin), 2026-10-01: 58,522 B — the
- * form island 57,667 + the `visible` hydration runtime 855. 64kb is 65,536: the headroom is Bun's
- * own movement on one source — a patch release that keeps core's declared modules measured +3.0 kB
- * on the scaffold's theme island, and the tree-shaker flaps by up to 1.1 kB between runs. An app
+ * fresh `x new` app with `x g resource widget` under CI's `file:` links, Bun 1.4.2 (CI's pin),
+ * 2026-10-05: 59,679 B — the form island 58,824 + the `visible` hydration runtime 855 (57,667 + 855
+ * on 1.4.0). 64kb is 65,536: the headroom is Bun's own movement on one source between releases —
+ * 1.4.0 → 1.4.2 moved this island +1,157 B, and a patch release that keeps core's declared modules
+ * measured +3.0 kB on the scaffold's theme island. Two builds of one source are
+ * byte-identical since 1.4.1 (issue #354), so no headroom is held for run-to-run movement. An app
  * that adds per-document scripts (`navigation: { client: [...] }` charges its router, ~18 kB, to
  * every `app/` page) is over it on its first build, and `nextSteps` sends the author there.
  */
 export const RESOURCE_PAGE_BUDGET = '64kb';
-export const RESOURCE_PAGE_MEASURED = '58,522 B';
+export const RESOURCE_PAGE_MEASURED = '59,679 B';
 
 /** How the page reaches a string — the same rule `route.ts` states, for the same issue (#249). */
 const catalogImport = (module: string | undefined): string =>
@@ -186,7 +188,7 @@ const pageTest = (options: ResourcePageOptions): string => {
 ${sortedImports([
   catalogImport(options.catalogModule),
   `import { driver } from '${options.dbModule}';`,
-  "import { createContext, frozenClock, runWithContext } from '@ultimat3/core';",
+  "import { ctxOf, frozenClock, runWithContext } from '@ultimat3/core';",
   "import { testActor } from '@ultimat3/policy';",
   "import { afterEach, expect, renderRoute, unitTest } from '@ultimat3/testing';",
 ])}
@@ -209,7 +211,7 @@ const clock = frozenClock('2026-01-01T00:00:00.000Z');
 
 const store = (title: string) => {
   const draft = { orgId, title, price: { minor: 1200, currency: 'USD' } };
-  return runWithContext(createContext({ actor: member, clock }), () => repo.insert(draft));
+  return runWithContext(ctxOf({ actor: member, clock }), () => repo.insert(draft));
 };
 
 // One store per process: without this, one test's rows are the next test's fixtures.

package/src/templates/resource-service.ts

@@ -43,7 +43,7 @@ const serviceTest = (
 ): string => `// The ${feature.kebab} service against the in-memory driver, and its failure, pinned: a code an
 // agent can match on, a cause naming the row, and a fix that is an instruction.
 ${sortedImports([
-  "import { createContext, runWithContext } from '@ultimat3/core';",
+  "import { ctxOf, runWithContext } from '@ultimat3/core';",
   "import { testActor } from '@ultimat3/policy';",
   "import { afterEach, expect, unitTest } from '@ultimat3/testing';",
   `import { driver } from '${dbModule}';`,
@@ -57,7 +57,7 @@ const draft = { orgId, title: 'First', price: { minor: 1200, currency: 'USD' } }
 
 /** What a request is to the repo underneath: an actor, whose org every statement runs under. */
 const inOrg = <T>(run: () => Promise<T>): Promise<T> =>
-  runWithContext(createContext({ actor: testActor('member', { orgId }).actor }), run);
+  runWithContext(ctxOf({ actor: testActor('member', { orgId }).actor }), run);
 
 // One store per process: without this, one test's rows are the next test's fixtures.
 afterEach(() => {

package/src/templates/route.ts

@@ -51,13 +51,13 @@ const DYNAMIC_SEGMENT = /^\[(?<spread>\.\.\.)?(?<name>[^\]]+)\]$/;
 /**
  * One URL segment. `kebab()` strips `[` and `]` along with every other non-alphanumeric, so
  * `x g route "posts/[slug]"` scaffolded `apps/web/app/posts/slug/page.tsx` — a different, STATIC
- * route — and reported `ok:true` with no warning. Only the parameter NAME is kebabed now.
+ * route — and reported `ok:true` with no warning. A dynamic segment is now kept exactly as the
+ * author wrote it: its name is the key the router puts in `params`, so kebabing it renamed
+ * `[orderId]` to `[order-id]` behind the author's back — the page read `params.orderId` and got
+ * `undefined`.
  */
-export const routeSegment = (part: string): string => {
-  const match = DYNAMIC_SEGMENT.exec(part);
-  if (match === null) return kebab(part);
-  return `[${match.groups?.['spread'] ?? ''}${kebab(match.groups?.['name'] ?? '')}]`;
-};
+export const routeSegment = (part: string): string =>
+  DYNAMIC_SEGMENT.test(part) ? part : kebab(part);
 
 const segmentsOf = (path: string): readonly string[] =>
   path
@@ -154,11 +154,26 @@ const sampleUrl = (path: string): string =>
     })
     .join('/');
 
-/** The params object that URL implies. `{}` was a lie for every dynamic route. */
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+
+/**
+ * A single-quoted TS string literal — the repo's (and the scaffold's Biome config's) quote style,
+ * so the generated file passes `lint` as written. `JSON.stringify` does the escaping.
+ */
+const singleQuoted = (value: string): string =>
+  `'${JSON.stringify(value).slice(1, -1).replaceAll('\\"', '"').replaceAll("'", "\\'")}'`;
+
+/** An object key as TS accepts it: bare when it is an identifier, quoted when it is not. */
+const objectKey = (name: string): string => (IDENTIFIER.test(name) ? name : singleQuoted(name));
+
+/**
+ * The params object that URL implies. `{}` was a lie for every dynamic route; a bare
+ * `order-id:` key was a syntax error in the test of every kebab-named param.
+ */
 const paramsLiteral = (path: string): string => {
   const params = routeParams(path);
   if (params.length === 0) return '{}';
-  return `{ ${params.map((name) => `${name}: '${sampleValue(name)}'`).join(', ')} }`;
+  return `{ ${params.map((name) => `${objectKey(name)}: ${singleQuoted(sampleValue(name))}`).join(', ')} }`;
 };
 
 const routeTest = (

package/src/templates/scaffold-api.ts

@@ -41,9 +41,8 @@ contractTest('health is an action exposed over MCP', () => {
   expect(target.mcp?.expose).toBe(true);
 });
 
-contractTest('health projects one MCP tool and one OpenAPI operation', () => {
-  // Same policy object on both surfaces — a public action says so once, not once per surface.
-  expect(target.tool().policy).toBe(target.policy);
+contractTest('health projects one OpenAPI operation under its export name', () => {
+  // The MCP tool is \`@ultimat3/mcp\`'s \`toolFrom\`, served from the \`mcp\` block above.
   expect(target.openapi().operationId).toBe('health');
 });
 `;

package/src/templates/scaffold-app.ts

@@ -200,7 +200,8 @@ import './global';
 
 unitTest('importing shared/global registers the one global stylesheet', () => {
   const sheets = registeredStylesheets().filter((sheet) => sheet.global);
-  expect(sheets.map((sheet) => sheet.file.split('/').slice(-3).join('/'))).toEqual([
+  // Split on either separator: \`file\` is a host path, \`D:\\…\\global.scss\` on Windows.
+  expect(sheets.map((sheet) => sheet.file.split(/[\\\\/]/).slice(-3).join('/'))).toEqual([
     'web/shared/global.scss',
   ]);
   // The custom properties themselves, declared once on the root — what \`tokens.role()\` refers to.