@ultimat3/cli 29.3.2 → 30.0.0

package/src/templates/scaffold-claude-commands.ts

@@ -6,7 +6,7 @@
 import type { GeneratedFile, NameSet } from './naming';
 
 const feature = (app: NameSet): string => `---
-description: Build or fix one thing in ${app.kebab} end to end — name the primitive, generate it, wire it inside the boundaries, gate it with \`bun run check\`.
+description: Build or fix one thing in ${app.kebab} end to end — name the primitive, generate it, wire it inside the boundaries, gate it with \`bun run verify\`.
 argument-hint: <what you want built or fixed, plain language>
 allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Agent, Skill
 ---
@@ -16,7 +16,7 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Agent, Skill
 You are a senior engineer on **${app.kebab}**, an Ultimate app. Read \`AGENTS.md\` before designing
 anything — it is the short form of every rule below, and it wins where the two disagree.
 
-**Done means \`bun run check\` green.** A passing unit test is not done. A working \`x dev\` is not done.
+**Done means \`bun run verify\` green.** A passing unit test is not done. A working \`bunx x dev\` is not done.
 Report what you actually ran, never what you assume passed.
 
 ## Request
@@ -49,15 +49,15 @@ obvious, hand the request to the \`shape\` subagent — that pass is the whole r
 ## 2. Generate it — do not hand-write it
 
 \`\`\`sh
-x g <kind> <name> --feature <slice>     # x g --help is the only list of kinds
+bunx x g <kind> <name> --feature <slice>     # bunx x g --help is the only list of kinds
 \`\`\`
 
 The generator writes the source, its test and its i18n keys as one unit and registers it. A
-hand-written primitive compiles and then goes missing from \`x routes\`, \`x actions\`, \`x queries\`,
-\`x jobs\`, \`x tasks\`, \`x policy list\` and \`x.manifest.json\` — every surface that is supposed to
+hand-written primitive compiles and then goes missing from \`bunx x routes\`, \`bunx x actions\`, \`bunx x queries\`,
+\`bunx x jobs\`, \`bunx x tasks\`, \`bunx x policy list\` and \`x.manifest.json\` — every surface that is supposed to
 project it. Edit what the generator wrote; never reproduce it.
 
-Schema changes are generated too: edit \`entity.ts\`, then \`x db gen "what changed"\`. Never hand-write
+Schema changes are generated too: edit \`entity.ts\`, then \`bunx x db gen "what changed"\`. Never hand-write
 SQL into \`packages/db/migrations/\`.
 
 ## 3. Wire it inside the boundaries
@@ -72,23 +72,21 @@ SQL into \`packages/db/migrations/\`.
 | routes | call actions and queries, never a repo | policy skipped |
 
 Route files: \`page.tsx\` under \`site/\`/\`app/\`, and none under \`api/\`. **The directory is the URL** —
-the filename never is. One interactive control on a 0kb page is an island: \`x g island <name> --at <dir>\`.
+the filename never is. One interactive control on a 0kb page is an island: \`bunx x g island <name> --at <dir>\`.
 
 ## 4. Gate it
 
 \`\`\`sh
-bun run check           # the gate. green = shippable
-bun run check --json    # the same, machine-readable
+bun run verify          # the gate. green = shippable
+bun run verify --json   # the same, machine-readable
 \`\`\`
 
-\`bun run check\` is \`x build --target static\` and THEN \`x verify\`, and the order is the whole point:
-the \`budgets\` step measures \`.x/build-stats.json\`, which only a build writes, so \`x verify\` on
-its own reports X_BUDGET_UNMEASURED on a tree that is fine. \`--json\` is forwarded to both halves;
-a machine consumer takes the last line. CI runs this same script — \`.github/workflows/ci.yml\` is
-\`bun run setup\` and then \`bun run check\`, nothing else.
+\`bun run verify\` is \`bunx x verify\`, the whole gate: its \`budgets\` step builds what it weighs when
+\`.x/build-stats.json\` is missing or older than the source. CI runs this same script —
+\`.github/workflows/ci.yml\` is \`bun run setup\` and then \`bun run verify\`, nothing else.
 
 Red is instructions, not a verdict: **every finding carries an executable \`fix:\` — run it verbatim
-before improvising**, and \`x errors explain <CODE>\` expands any code it names. Never narrow the gate
+before improvising**, and \`bunx x errors explain <CODE>\` expands any code it names. Never narrow the gate
 to make it pass: there is no \`--only\` and no \`--skip\`, on purpose, and disabling a lint rule or
 loosening a compiler flag is the same move wearing a different hat.
 
@@ -98,15 +96,16 @@ While you iterate, narrow the *feedback*, not the gate:
 |---|---|
 | one test file | \`bun test <path>/<file>.test.ts\` |
 | one test by name | \`bun test -t '<name>'\` |
-| a whole type | \`x test unit\` · \`x test contract\` · \`x test e2e\` |
+| a whole type | \`bunx x test unit\` · \`bunx x test contract\` · \`bunx x test e2e\` |
 | lint the files you touched | \`bunx biome check --write <paths>\` |
 | types, once, when otherwise done | \`bun run typecheck\` |
-| a broken environment | \`x doctor\` |
+| a broken environment | \`bunx x doctor\` |
 
 ## 5. Hard rules
 
-Never a bare \`throw new Error\` — subclass \`UltimateError\` with a stable code, a cause and a
-runnable \`fix:\`. No \`any\`; use \`unknown\` and parse. Named exports only. \`import type\` for types.
+Never a bare \`throw new Error\` — declare each code once with \`defineError\` from \`@ultimat3/core\`:
+a stable code, a title, a status, a cause and a runnable \`fix:\`.
+No \`any\`; use \`unknown\` and parse. Named exports only. \`import type\` for types.
 Tests next to the source as \`<file>.test.ts\`, failure case first — a test that cannot fail is not a
 test. One file, one job. Every user-facing string through \`t()\`. Semantic tokens, never a raw
 colour. Every date formatted with an explicit IANA time zone. Money is integer minor units plus an
@@ -116,9 +115,9 @@ ISO code, never a float. Bun only.
 
 \`\`\`
 Primitive:  <which of the eight>    Slice: <dir>
-Generated:  <the x g invocations you ran>
+Generated:  <every \`bunx x g\` command you ran>
 Changed:    <files>
-Gate:       bun run check ✓ | ✗ <failing steps>
+Gate:       bun run verify ✓ | ✗ <failing steps>
 Deferred:   <what you did not do, and why>      [never omit this line]
 \`\`\`
 `;
@@ -166,13 +165,13 @@ slice it lives in. If it fits none, the design is wrong — say so here instead
 - \`path:line\` — what changes, and why.
 
 ## Steps
-1. Ordered, concrete. Name the \`x g\` invocation where one applies. Point at code, do not paste it.
+1. Ordered, concrete. Name the \`bunx x g\` invocation where one applies. Point at code, do not paste it.
 
 ## Tests
 - What to add, next to the source as \`<file>.test.ts\`. Command to run it.
 
 ## Done when
-- Acceptance criteria, ending in \`bun run check\` green.
+- Acceptance criteria, ending in \`bun run verify\` green.
 
 ## Risks
 - Anything the executor must decide, and every claim in the ask the code disproves.
@@ -185,7 +184,7 @@ slice it lives in. If it fits none, the design is wrong — say so here instead
 - No checkboxes. The plan is a map, not a tracker.
 - The plan must obey the app's own rules — one way to do each thing, generators over hand-written
   files, imports that never cross a surface boundary, a stable error code with a runnable \`fix:\` for
-  every new failure, and \`bun run check\` green as the last line of *Done when*.
+  every new failure, and \`bun run verify\` green as the last line of *Done when*.
 
 ## Output
 
@@ -202,18 +201,16 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash
 
 # /verify
 
-Run \`bun run check\`.
+Run \`bun run verify\`.
 
-It is \`x build --target static\` and then \`x verify\`, and it is THE gate — the one CI runs
-(\`.github/workflows/ci.yml\`) and the one \`README.md\` names. \`x verify\` alone is half of it:
-the \`budgets\` step measures \`.x/build-stats.json\`, which only the build writes, so a bare
-\`x verify\` reports X_BUDGET_UNMEASURED on a tree with nothing wrong with it.
+It is \`bunx x verify\`, and it is THE gate — the one CI runs (\`.github/workflows/ci.yml\`) and the
+one \`README.md\` names. Its \`budgets\` step builds what it weighs, so nothing runs before it.
 
 Green: say so and stop.
 
 Red: fix every finding, then re-run until green. Each finding carries a stable code, a cause and an
-executable \`fix:\` — **run the \`fix:\` verbatim before improvising**, and use \`x errors explain <CODE>\`
-when the cause is not enough. \`bun run check --json\` gives the same steps machine-readably; \`x doctor\`
+executable \`fix:\` — **run the \`fix:\` verbatim before improvising**, and use \`bunx x errors explain <CODE>\`
+when the cause is not enough. \`bun run verify --json\` gives the same steps machine-readably; \`bunx x doctor\`
 covers the case where the environment, not the code, is what is broken.
 
 Do not narrow the gate to make it pass. There is no \`--only\` and no \`--skip\`; disabling a lint rule,

package/src/templates/scaffold-claude.ts

@@ -9,6 +9,7 @@ import { claudeCommandFiles } from './scaffold-claude-commands';
 
 /**
  * Read-only commands and the two write commands whose blast radius is a file the gate checks.
+ * Spelled `bunx x`, the form that runs with no global `x` and the one the generators print.
  * Deliberately absent: `x db reset`, `x db backfill --write`, `x secrets`, `x deploy` — each is
  * destructive or reaches production, and an allowlist that covers them is a prompt nobody reads.
  *
@@ -23,26 +24,28 @@ const settings = (): string => `{
       "Bash(bun test:*)",
       "Bash(bun run typecheck)",
       "Bash(bun run lint)",
+      "Bash(bun run verify:*)",
       "Bash(bunx biome check:*)",
-      "Bash(x verify:*)",
-      "Bash(x test:*)",
-      "Bash(x doctor:*)",
-      "Bash(x g:*)",
-      "Bash(x routes:*)",
-      "Bash(x actions:*)",
-      "Bash(x queries:*)",
-      "Bash(x entities:*)",
-      "Bash(x jobs list:*)",
-      "Bash(x jobs show:*)",
-      "Bash(x tasks:*)",
-      "Bash(x policy:*)",
-      "Bash(x i18n check:*)",
-      "Bash(x errors:*)",
-      "Bash(x env check:*)",
-      "Bash(x manifest:*)",
-      "Bash(x db gen:*)",
-      "Bash(x db migrate:*)",
-      "Bash(x db branch:*)",
+      "Bash(bunx x verify:*)",
+      "Bash(bunx x test:*)",
+      "Bash(bunx x doctor:*)",
+      "Bash(bunx x g:*)",
+      "Bash(bunx x routes:*)",
+      "Bash(bunx x actions:*)",
+      "Bash(bunx x queries:*)",
+      "Bash(bunx x entities:*)",
+      "Bash(bunx x jobs list:*)",
+      "Bash(bunx x jobs show:*)",
+      "Bash(bunx x tasks:*)",
+      "Bash(bunx x policy:*)",
+      "Bash(bunx x i18n check:*)",
+      "Bash(bunx x errors:*)",
+      "Bash(bunx x docs:*)",
+      "Bash(bunx x env check:*)",
+      "Bash(bunx x manifest:*)",
+      "Bash(bunx x db gen:*)",
+      "Bash(bunx x db migrate:*)",
+      "Bash(bunx x db branch:*)",
       "Bash(git status)",
       "Bash(git diff:*)",
       "Bash(git log:*)"
@@ -68,7 +71,7 @@ const readme = (app: NameSet): string => `# .claude/
 
 What Claude Code reads when it works on ${app.kebab}. Written by \`x new\`, owned by you from the
 moment it lands: edit any file, or delete any file, and nothing in the app breaks. Nothing here is
-enforced by \`x verify\`, and nothing here reaches outside this repository.
+enforced by \`bunx x verify\`, and nothing here reaches outside this repository.
 
 One thing in it does *write*: the \`PostToolUse\` hook in \`settings.json\` reformats each file an agent
 edits, in place, the moment it is saved. That is the only thing here that touches your code on its
@@ -86,7 +89,7 @@ So the whole bundle is three description lines of standing cost. The rest is pai
 
 | File | For |
 |---|---|
-| \`commands/feature.md\` | \`/feature\` — build or fix one thing end to end, gated on \`x verify\` |
+| \`commands/feature.md\` | \`/feature\` — build or fix one thing end to end, gated on \`bun run verify\` |
 | \`commands/planx.md\` | \`/planx\` — write a plan to \`docs/plans/\` for another agent to execute |
 | \`commands/verify.md\` | \`/verify\` — run the gate and fix what it reports |
 | \`agents/shape.md\` | the idea-stage pass: which primitive, which slice, or "do not build this" |
@@ -99,7 +102,7 @@ a line it may not cross. That is what makes two of them safe to run at once.
 
 ## What is deliberately not here
 
-**No command that wraps \`x g\`.** \`x g <kind> <name>\` already is that command, and \`x g --help\` is
+**No command that wraps \`bunx x g\`.** \`bunx x g <kind> <name>\` already is that command, and \`bunx x g --help\` is
 the only list of kinds — a slash command restating it is a second copy that drifts the first time a
 kind is added.
 
@@ -113,7 +116,7 @@ means it rewrites that file in place** — the same safe fixes \`biome check --w
 repo-wide, but your working tree does change after every agent edit. Scoped to one file, so it costs
 milliseconds, and it settles formatting arguments before they reach a diff.
 
-It is not a typecheck, because a *scoped* one does not exist: \`tsc\` needs the project, and \`x verify\`
+It is not a typecheck, because a *scoped* one does not exist: \`tsc\` needs the project, and \`bunx x verify\`
 takes no \`--only\` and no \`--skip\` by design — narrowing the gate would make "green" mean whatever
 the caller chose. If you want types on every edit, \`bun run typecheck\` is the whole project and you
 are choosing to pay for it.

package/src/templates/scaffold-container-compose.ts

@@ -3,6 +3,7 @@
 // `x deploy --method compose` runs, and the single-node rung of the scale ladder.
 
 import type { NameSet } from './naming';
+import { RUNTIME_UID } from './scaffold-helm';
 
 /**
  * The production env file, relative to the app root. Named once because two readers must agree:
@@ -19,6 +20,8 @@ export const composeProdFile = (
 #
 #   IMAGE=ghcr.io/you/${app.kebab}:1.2.3 x deploy --image ghcr.io/you/${app.kebab}:1.2.3
 #
+# ${PROD_ENV_FILE} first: \`x env init --production\` writes every value below with fresh secrets.
+#
 # By hand, always with \`--env-file ${PROD_ENV_FILE}\`: Compose fills \`\${VAR:?…}\` below from the shell
 # and \`--env-file\` only, NEVER from \`env_file:\`, so without it a value set only in that file is
 # "missing" and the parse fails. \`x deploy\` passes it on every step.
@@ -55,8 +58,10 @@ x-image: &image
   # filesystem, no Linux capabilities (nothing here binds below 1024), no setuid escalation, and a
   # memory ceiling so one runaway role takes down its container rather than the box. /tmp and .x/
   # are tmpfs — .x/ is where a still-embedded binding keeps state, which production never relies on.
+  # A tmpfs mounts root-owned and hides the image's chown, so .x/ names the image's USER: without
+  # it every role refuses at boot (X_STORAGE_UNWRITABLE, EACCES mkdir '/app/.x/storage').
   read_only: true
-  tmpfs: [/tmp, /app/.x]
+  tmpfs: [/tmp, '/app/.x:uid=${RUNTIME_UID},gid=${RUNTIME_UID}']
   cap_drop: [ALL]
   security_opt: ['no-new-privileges:true']
   mem_limit: 1g

package/src/templates/scaffold-container.ts

@@ -121,6 +121,10 @@ ENTRYPOINT ["bun", "apps/web/server.ts"]
  * has ever produced ignoring a filename nothing writes, which reads as a rule still in force.
  * `scripts/image-contract.ts` holds every ignore file IN THIS TREE to the same line; a generated
  * app's copy is this template's, and `scaffold-container.test.ts` is where it is judged.
+ *
+ * Tests and the root `docs/` go for a different reason: `COPY . .` sits above the prebuilt step, so
+ * an edit to a file no boot reads reran Babel and Sass. No `*.fixture.ts` line: non-test source can
+ * reach a fixture, and a missing module at boot is a worse failure than a few kilobytes.
  */
 const dockerignore = (): string => `**/.env
 **/.env.*
@@ -143,6 +147,11 @@ node_modules
 coverage
 **/test-results
 **/playwright-report
+# Tests run in CI, never in a container, and an edit to one would rerun every line below COPY . .
+**/*.test.ts
+**/*.test.tsx
+# Anchored: a package may hold a docs/ it reads at run time. See "What the image leaves out" in README.
+docs
 `;
 
 const readme = (app: NameSet): string => `# docker
@@ -175,6 +184,12 @@ compiled stylesheet is made once, there, by the image's own Bun — so a pod bui
 Without that line every boot runs Babel and Sass over the whole app and logs
 \`X_IMAGE_NOT_PREBUILT\`, naming it.
 
+### What the image leaves out
+
+\`docker/Dockerfile.dockerignore\` drops \`*.test.ts\`, \`*.test.tsx\` and the root \`docs/\`: no boot
+reads them, and an edit to one leaves the prebuilt layer cached. An app that serves a file from
+\`docs/\` re-includes it with \`!docs/<path>\`, on a line after \`docs\`.
+
 ## One box, every role
 
 \`\`\`sh
@@ -276,10 +291,15 @@ somebody else's repository is a command that cannot run. \`--image\` sets \`imag
 | Job | release | \`ROLE=migrate\`, a \`pre-install,pre-upgrade\` hook — it runs to completion first |
 | Ingress | release | off by default; routes \`/_x/sync\` to sync and \`/\` to web |
 | HorizontalPodAutoscaler | role, opt-in | rps, websocket connections, queue depth — never CPU |
-
-No ServiceMonitor and no PodDisruptionBudget: the first needs a CRD \`helm install\` fails on in a
-cluster with no Prometheus operator, and both are cluster policy rather than this app's topology.
-Every role already answers \`/metrics\` on \`metricsPort\`.
+| ServiceMonitor | release | scrapes \`/metrics\` on \`metricsPort\`, every serving role |
+| PrometheusRule | release | stalled queue, dead letters, lost leases, dropped frames, 5xx share, target down |
+
+The last two render only where the cluster serves the Prometheus operator's kinds
+(\`serviceMonitor.enabled\` and \`alerts.enabled\` are \`auto\`), so \`helm install\` still succeeds on a
+cluster without it; \`true\` forces them, \`false\` declines. Each rule's threshold, \`for\` and
+severity are values under \`alerts.rules.<alert>\`. Outside Kubernetes, \`x g chart-alerts --print\`
+prints the same rules for any Prometheus rule loader. No PodDisruptionBudget: that is cluster
+policy rather than this app's topology.
 `;
 
 /** The container files for a new app, in the order a reader meets them. */

package/src/templates/scaffold-dashboard-bare.ts

@@ -203,7 +203,7 @@ afterAll(clearRoutes);
 
 unitTest('the dashboard is gated, renders per request, and hydrates one island', async () => {
   const view = await renderRoute(page, { url });
-  expect(page.config.render).toBe('ssr');
+  expect(page.config.render).toBe('stream');
   expect(page.config.policy?.permission).toBe('dashboard:read');
   expect(page.config.offline).toBe('runtime');
   expect(page.config.budget.js).toBe('60kb');
@@ -230,12 +230,12 @@ unitTest('the table is the route table: path, surface and render mode per route'
   expect([...row.matchAll(/([^>]*)<\\/td>/g)].map((cell) => cell[1])).toEqual([
     '/dashboard',
     'app',
-    'ssr',
+    'stream',
   ]);
   expect(view.text).toContain(t('app.dashboard.routesCaption'));
   expect(view.meta.title).toBe(t('app.dashboard.title'));
   // The sidebar knows where it is.
-  expect(view.html).toMatch(/<a href="\\/dashboard" aria-current="page"/);
+  expect(view.html).toMatch(/<a [^>]*href="\\/dashboard" aria-current="page"/);
 });
 `;
 

package/src/templates/scaffold-dashboard-example-tests.ts

@@ -12,6 +12,8 @@ export const exampleViewTest =
 import { expect, unitTest } from '@ultimat3/testing';
 import {
   bucketByDay,
+  CHART_MAX_DAYS,
+  chartDays,
   formatCount,
   type PostRow,
   postStats,
@@ -43,9 +45,14 @@ unitTest('postStats counts the week, compares it with the prior one, and counts
   expect(postStats([...rows, row('d', 0.25)], NOW).today).toBe(1);
 });
 
-unitTest('a zero baseline yields no delta, and no rows count nothing', () => {
-  expect(postStats([row('a', 1)], NOW).delta).toBeUndefined();
-  expect(postStats([], NOW)).toEqual({ total: 0, lastWeek: 0, delta: undefined, today: 0 });
+unitTest('from a zero baseline the chip is the difference, and no rows count nothing', () => {
+  expect(postStats([row('a', 1)], NOW).delta).toEqual({ text: '+1', trend: 'up' });
+  expect(postStats([], NOW)).toEqual({
+    total: 0,
+    lastWeek: 0,
+    delta: { text: '0', trend: 'flat' },
+    today: 0,
+  });
 });
 
 unitTest('bucketByDay is one bar per day, oldest first, quiet days included', () => {
@@ -53,12 +60,27 @@ unitTest('bucketByDay is one bar per day, oldest first, quiet days included', ()
   expect(points).toHaveLength(14);
   expect(points.at(-1)?.key).toBe('03-15');
   expect(points[0]?.key).toBe('03-02');
-  expect(points.reduce((sum, point) => sum + point.value, 0)).toBe(3);
+  expect(points.reduce((sum, point) => sum + (point.value ?? 0), 0)).toBe(3);
   // Eight days ago is 03-07: inside a 14-day window, so the bar is there.
   expect(points.find((point) => point.key === '03-07')?.value).toBe(1);
   expect(bucketByDay([], NOW, 3).map((point) => point.value)).toEqual([0, 0, 0]);
 });
 
+unitTest('a capped read leaves the days before its oldest row unknown — null, never 0', () => {
+  const values = bucketByDay([row('a', 1), row('b', 3)], NOW, 5, { capped: true }).map(
+    (point) => point.value,
+  );
+  // 03-11 is before the oldest row the capped read saw (03-12): unknown. 03-13 is a quiet day: 0.
+  expect(values).toEqual([null, 1, 0, 1, 0]);
+});
+
+unitTest('chartDays is the window in whole days, never zero and never past the cap', () => {
+  expect(chartDays(new Date(NOW.getTime() - 7 * DAY_MS), NOW)).toBe(7);
+  expect(chartDays(new Date(NOW.getTime() - DAY_MS / 2), NOW)).toBe(1);
+  // A URL may ask for ten years: the chart draws at most this many bars.
+  expect(chartDays(new Date(NOW.getTime() - 3650 * DAY_MS), NOW)).toBe(CHART_MAX_DAYS);
+});
+
 unitTest('toPostRow serialises a Date, passes ISO text through, and keeps the price whole', () => {
   const at = new Date('2026-01-02T03:04:05.000Z');
   const price = { minor: 1900, currency: 'USD' };
@@ -139,7 +161,7 @@ afterEach(() => {
 
 unitTest('the dashboard is gated, renders per request, and hydrates one island', async () => {
   const view = await renderRoute(page, { url, actor: viewer });
-  expect(page.config.render).toBe('ssr');
+  expect(page.config.render).toBe('stream');
   expect(page.config.policy?.permission).toBe('dashboard:read');
   expect(page.config.offline).toBe('runtime');
   expect(page.config.budget.js).toBe('60kb');
@@ -169,8 +191,11 @@ unitTest('it counts and lists the posts of the org that is looking', async () =>
   expect(view.html.match(/data-segment="/g)).toHaveLength(2);
   expect(view.html).toContain('role="meter"');
   expect(view.text).toContain('This week');
+  // The chart's window is the default two weeks, and every preset is a link.
+  expect(view.html).toContain('href="/dashboard?range=week"');
+  expect(view.html).toContain('href="/dashboard?range=month"');
   // The sidebar knows where it is.
-  expect(view.html).toMatch(/<a href="\\/dashboard" aria-current="page"/);
+  expect(view.html).toMatch(/<a [^>]*href="\\/dashboard" aria-current="page"/);
 });
 
 unitTest('another org sees none of them: the page says so instead of an empty table', async () => {
@@ -185,6 +210,18 @@ unitTest('another org sees none of them: the page says so instead of an empty ta
   expect(view.meta.description).toBe(t('app.dashboard.description'));
 });
 
+unitTest('the chart window is read from the URL and survives as a link', async () => {
+  await post('This week', 3);
+  const week = await renderRoute(page, { url: \`\${url}?range=week\`, actor: viewer });
+  expect(week.data.url).toBe(\`\${url}?range=week\`);
+  // Seven bars for the week; the default window draws fourteen.
+  const keys = (html: string): number =>
+    html.match(/<th[^>]*scope="row"[^>]*>\\d{2}-\\d{2}</g)?.length ?? 0;
+  const fortnight = await renderRoute(page, { url, actor: viewer });
+  expect(keys(week.html)).toBe(7);
+  expect(keys(fortnight.html)).toBe(14);
+});
+
 unitTest('a viewer the post read refuses is refused, never shown the org’s posts', async () => {
   await post('Not for them', 0);
   // In the org, onto the page, without \`post:read\`: the query's policy decides, not the page's.
@@ -195,14 +232,17 @@ unitTest('a viewer the post read refuses is refused, never shown the org’s pos
 });
 
 unitTest('the build measures the empty page: no database is not a failure there', async () => {
-  const measured = await page.dashboardData(() => Promise.reject(dbUnavailable('no database')));
+  const measured = await page.dashboardData(
+    () => Promise.reject(dbUnavailable('no database')),
+    url,
+  );
   // The clock is frozen under test, so the instant the windows are cut at is this one.
-  expect(measured).toEqual({ rows: [], now: new Date().toISOString() });
+  expect(measured).toEqual({ rows: [], now: new Date().toISOString(), url });
 });
 
 unitTest('any other failure of the read propagates', async () => {
   const cause = new TypeError('the read broke');
   const read = (): Promise<never> => Promise.reject(cause);
-  expect(await page.dashboardData(read).catch((error: unknown) => error)).toBe(cause);
+  expect(await page.dashboardData(read, url).catch((error: unknown) => error)).toBe(cause);
 });
 `;

package/src/templates/scaffold-dashboard-example-view.ts

@@ -0,0 +1,156 @@
+// The `--example` dashboard's view module, `dashboard-view.ts`: the pure numbers behind the page —
+// stats, per-day buckets, the chart's window presets and its day bound. Split from
+// `scaffold-dashboard-example.ts`, which keeps the page that reads it.
+
+export const exampleView =
+  (): string => `// The dashboard's numbers, apart from its markup: pure functions over the rows the page loaded,
+// so the server render and a test cannot disagree about a figure. No I/O, no \`t()\`, no JSX.
+
+import type { Money } from '@ultimat3/money';
+import { type ChartPoint, deltaOf, type StatDelta } from '@ultimat3/ui';
+
+/**
+ * The chart's windows, shortest first. The list is this app's — "last 24 hours" or "this quarter"
+ * is a business decision — and \`timeRangeUrl\` is the one rule that reads it from the URL.
+ */
+export const CHART_RANGES = [
+  { id: 'week', days: 7 },
+  { id: 'fortnight', days: 14 },
+  { id: 'month', days: 30 },
+] as const;
+
+export const DEFAULT_CHART_RANGE = 'fortnight';
+
+/** The chart buckets UTC days, so a custom window's wall-clock times are UTC too: one zone. */
+export const CHART_ZONE = 'UTC';
+
+/** The most bars a custom window draws: one per day, so this bounds the markup a URL can ask for. */
+export const CHART_MAX_DAYS = 92;
+
+const DAY_MS = 86_400_000;
+
+/** Whole days a window covers, at least one and at most \`CHART_MAX_DAYS\`. */
+export function chartDays(from: Date, to: Date): number {
+  const days = Math.ceil((to.getTime() - from.getTime()) / DAY_MS);
+  return Math.min(CHART_MAX_DAYS, Math.max(1, days));
+}
+
+/** One post as the page reads it. \`createdAt\` is ISO text: a \`Date\` cannot cross a JSON seam. */
+export interface PostRow {
+  readonly id: string;
+  readonly title: string;
+  /** Integer minor units plus an ISO code, never a float — the entity's \`money()\` column. */
+  readonly price: Money;
+  readonly createdAt: string;
+}
+
+/**
+ * Duck-typed rather than the entity's own row: the page only ever reads these four columns. The
+ * query reads through the typed handle, so \`createdAt\` arrives as the \`Date\` the entity declares.
+ */
+export function toPostRow(row: {
+  readonly id: string;
+  readonly title: string;
+  readonly price: Money;
+  readonly createdAt: Date | string;
+}): PostRow {
+  const at = row.createdAt;
+  return {
+    id: row.id,
+    title: row.title,
+    price: row.price,
+    createdAt: at instanceof Date ? at.toISOString() : at,
+  };
+}
+
+/** Free (a zero price) against paid, over every row loaded — the two halves of the ring. */
+export interface PriceMix {
+  readonly free: number;
+  readonly paid: number;
+}
+
+export function priceMix(rows: readonly PostRow[]): PriceMix {
+  const paid = rows.filter((row) => row.price.minor > 0).length;
+  return { free: rows.length - paid, paid };
+}
+
+/**
+ * The dearest price per currency, in minor units — what each row's in-cell bar is a share of.
+ * Per currency because 1,900 cents and 1,900 yen are not the same height.
+ */
+export function priceCeilings(rows: readonly PostRow[]): ReadonlyMap<string, number> {
+  const ceilings = new Map<string, number>();
+  for (const row of rows) {
+    const { currency, minor } = row.price;
+    ceilings.set(currency, Math.max(ceilings.get(currency) ?? 0, minor));
+  }
+  return ceilings;
+}
+
+export interface PostStats {
+  readonly total: number;
+  /** Created in the seven days ending at \`now\`. */
+  readonly lastWeek: number;
+  /** \`lastWeek\` against the seven days before it: a percentage, or the difference from zero. */
+  readonly delta: StatDelta | undefined;
+  /** Created in the UTC day \`now\` falls in — a partial day, so it carries no delta. */
+  readonly today: number;
+}
+
+const createdAtOf = (row: PostRow): number => Date.parse(row.createdAt);
+
+const within = (rows: readonly PostRow[], from: number, to: number): number =>
+  rows.filter((row) => {
+    const at = createdAtOf(row);
+    return Number.isFinite(at) && at > from && at <= to;
+  }).length;
+
+export function postStats(rows: readonly PostRow[], now: Date): PostStats {
+  const end = now.getTime();
+  const weekAgo = end - 7 * DAY_MS;
+  const dayStart = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
+  const lastWeek = within(rows, weekAgo, end);
+  return {
+    total: rows.length,
+    lastWeek,
+    delta: deltaOf(lastWeek, within(rows, weekAgo - 7 * DAY_MS, weekAgo)),
+    today: within(rows, dayStart - 1, end),
+  };
+}
+
+/** \`MM-DD\` of a UTC day. ISO, never \`toLocaleDateString\`: the chart's axis is data, not prose. */
+const dayKey = (at: number): string => new Date(at).toISOString().slice(5, 10);
+
+/**
+ * One bucket per UTC day, the last one being the day \`now\` falls in, oldest first — the shape
+ * \`BarChart\` draws. Every day is present even when nothing was created on it: a chart with the
+ * quiet days removed reads as busier than the app is. A quiet day is 0; a day the read could not
+ * see — before the oldest row of a \`capped\` read — is \`null\`, a gap, never a zero.
+ */
+export function bucketByDay(
+  rows: readonly PostRow[],
+  now: Date,
+  days: number,
+  options: { readonly capped?: boolean } = {},
+): readonly ChartPoint[] {
+  const today = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
+  const start = today - (days - 1) * DAY_MS;
+  const counts: number[] = Array.from({ length: days }, () => 0);
+  for (const row of rows) {
+    const at = createdAtOf(row);
+    if (!Number.isFinite(at)) continue;
+    const index = Math.floor((at - start) / DAY_MS);
+    if (index >= 0 && index < days) counts[index] = (counts[index] ?? 0) + 1;
+  }
+  const oldest = Math.min(...rows.map(createdAtOf).filter(Number.isFinite));
+  const seenFrom = options.capped === true ? Math.floor((oldest - start) / DAY_MS) : 0;
+  return counts.map((value, index) => ({
+    key: dayKey(start + index * DAY_MS),
+    value: index < seenFrom ? null : value,
+  }));
+}
+
+/** A figure for a tile, in the page's locale. \`Intl.NumberFormat\` needs no time zone. */
+export const formatCount = (value: number, locale: string): string =>
+  new Intl.NumberFormat(locale).format(value);
+`;