@ultimat3/cli 1.2.0 → 3.0.0

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

@@ -0,0 +1,221 @@
+// The slash commands `x new` writes into `.claude/commands/`: the three workflows every audited
+// repo re-invented by hand — build a feature, plan one, run the gate. Deliberately NOT one command
+// per generator: `x g <kind>` already is that command, and a slash wrapper over a shipped CLI
+// command is the second path axiom 1 forbids.
+
+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 \`x verify\`.
+argument-hint: <what you want built or fixed, plain language>
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Agent, Skill
+---
+
+# /feature
+
+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 \`x verify\` green.** A passing unit test is not done. A working \`x dev\` is not done.
+Report what you actually ran, never what you assume passed.
+
+## Request
+$ARGUMENTS
+
+**The prompt is the context.** Scope, autonomy, whether to commit: read it from the words. Stop for
+a real blocker — a destructive migration, a request that needs a ninth primitive, a dependency you
+cannot justify. You cannot ask a subagent's user anything, so decide and flag it, or stop and say
+why.
+
+## 1. Name the primitive first
+
+Eight, closed: \`entity\` · \`policy\` · \`action\` · \`mutator\` · \`query\` · \`job\` · \`route\` · \`task\`.
+
+| The ask sounds like | It is |
+|---|---|
+| "store a …", "a … has fields" | \`entity\` |
+| "only the owner may …" | \`policy\` |
+| "when the user clicks submit …" | \`action\` (writes) / \`mutator\` (writes one entity) |
+| "show me the list of …" | \`query\` |
+| "send it afterwards", "retry until it works" | \`job\` |
+| "a page at /…" | \`route\` |
+| "every night at 3am" | \`task\` |
+
+A request that fits none is not one feature — split it until every piece is one of the eight. There
+is no ninth: a new capability is a **function that returns** one of these, never a new kind of thing.
+Say which primitive and which slice out loud before you write a file. When the answer is not
+obvious, hand the request to the \`shape\` subagent — that pass is the whole reason it exists.
+
+## 2. Generate it — do not hand-write it
+
+\`\`\`sh
+x g <kind> <name> --feature <slice>     # 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
+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
+SQL into \`packages/db/migrations/\`.
+
+## 3. Wire it inside the boundaries
+
+| Boundary | The rule | What breaks without it |
+|---|---|---|
+| \`apps/web/site/\` | 0kb JS, may not import \`apps/web/app/\` | the static path pays the app's bundle |
+| \`apps/web/app/\` | authed, streaming, hydrated | — |
+| \`apps/web/api/\` | actions only, \`route.ts\` | a second HTTP surface |
+| \`apps/web/shared/\` | a leaf: imports nothing of yours | an import cycle across surfaces |
+| \`repo.ts\` | the only file that touches the database | authz bypassed by a raw read |
+| routes | call actions and queries, never a repo | policy skipped |
+
+Route files: \`page.tsx\` under \`site/\`/\`app/\`, \`route.ts\` 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>\`.
+
+## 4. Gate it
+
+\`\`\`sh
+x verify                # the gate. green = shippable
+x verify --json         # the same steps, machine-readable
+\`\`\`
+
+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
+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.
+
+While you iterate, narrow the *feedback*, not the gate:
+
+| | Command |
+|---|---|
+| 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\` |
+| lint the files you touched | \`bunx biome check --write <paths>\` |
+| types, once, when otherwise done | \`bun run typecheck\` |
+| a broken environment | \`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.
+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
+ISO code, never a float. Bun only.
+
+## Output
+
+\`\`\`
+Primitive:  <which of the eight>    Slice: <dir>
+Generated:  <the x g invocations you ran>
+Changed:    <files>
+Gate:       x verify ✓ | ✗ <failing steps>
+Deferred:   <what you did not do, and why>      [never omit this line]
+\`\`\`
+`;
+
+const planx = (app: NameSet): string => `---
+description: Write a short, self-contained plan for ${app.kebab} to docs/plans/, for another agent to execute.
+argument-hint: [what you want done]
+allowed-tools: Read, Glob, Grep, Bash, Write, Agent
+---
+
+# /planx
+
+Plan only. No implementation, no edits outside the plan file.
+
+## Goal
+$ARGUMENTS
+
+## Steps
+
+1. **Read the code before planning against it.** If a claim in the ask is already false in the tree,
+   say so under *Risks* with the \`file:line\` that disproves it, and plan what is actually true.
+2. **Resolve the path.** The date comes from Bun in a named zone, never from the host's ambient one —
+   \`date +%F\` gives a different answer on two machines at the same instant, and this app formats no
+   date without an explicit IANA time zone.
+
+   \`\`\`sh
+   bun -e "console.log(new Intl.DateTimeFormat('en-CA', { timeZone: 'Etc/UTC' }).format(new Date()))"
+   \`\`\`
+
+   Then \`docs/plans/<YYYY-MM-DD>-<slug>.md\`. Slug is kebab-case, five words maximum. One file — a
+   plan split across a directory is a plan nobody reads to the end.
+3. **Write it.** Sections, in this order:
+
+\`\`\`markdown
+# <Title>
+
+## Goal
+One or two sentences: what, and why.
+
+## Primitive
+Which of the eight (\`entity · policy · action · mutator · query · job · route · task\`) and which
+slice it lives in. If it fits none, the design is wrong — say so here instead of planning a ninth.
+
+## Files to change
+- \`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.
+
+## Tests
+- What to add, next to the source as \`<file>.test.ts\`. Command to run it.
+
+## Done when
+- Acceptance criteria, ending in \`x verify\` green.
+
+## Risks
+- Anything the executor must decide, and every claim in the ask the code disproves.
+\`\`\`
+
+## Rules
+
+- Fragments over sentences. \`file:line\` refs over prose. Tables for anything with three or more rows.
+- Reference-only: point at the code, never re-explain it.
+- 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 \`x verify\` green as the last line of *Done when*.
+
+## Output
+
+\`\`\`
+✓ docs/plans/<YYYY-MM-DD>-<slug>.md
+Next: run it, or /feature it.
+\`\`\`
+`;
+
+const verify = (): string => `---
+description: Run the gate and fix everything it reports.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# /verify
+
+Run \`x verify\`.
+
+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. \`x verify --json\` gives the same steps machine-readably; \`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,
+loosening a compiler flag, or deleting an assertion is the same evasion. Fix the code.
+
+Report one line per fix: the code, the file, what changed.
+`;
+
+/** The three workflows, in the order a new app meets them. */
+export function claudeCommandFiles(app: NameSet): readonly GeneratedFile[] {
+  return [
+    { path: '.claude/commands/feature.md', contents: feature(app) },
+    { path: '.claude/commands/planx.md', contents: planx(app) },
+    { path: '.claude/commands/verify.md', contents: verify() },
+  ];
+}

package/src/templates/scaffold-claude.ts

@@ -0,0 +1,134 @@
+// The `.claude/` directory `x new` writes: the harness half of what an agent reads, next to the
+// `AGENTS.md`/`CLAUDE.md` half that already shipped. Every file lands in the app's own repo, shows
+// up in the scaffold's diff and is deletable in one line — the framework ships the mechanism, the
+// app keeps or replaces the convention. Nothing here reaches outside the project directory.
+
+import type { GeneratedFile, NameSet } from './naming';
+import { claudeAgentFiles } from './scaffold-claude-agents';
+import { claudeCommandFiles } from './scaffold-claude-commands';
+
+/**
+ * Read-only commands and the two write commands whose blast radius is a file the gate checks.
+ * 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.
+ *
+ * The hook is the one part of the bundle that ACTS: `--write` rewrites the file just edited, in
+ * place. JSON takes no comment (the lesson `scaffold-repo.ts`'s `biome.json` already paid for), so
+ * the disclosure lives in `.claude/README.md` under "The hook" — and a test pins it there.
+ */
+const settings = (): string => `{
+  "permissions": {
+    "allow": [
+      "Bash(bun install)",
+      "Bash(bun test:*)",
+      "Bash(bun run typecheck)",
+      "Bash(bun run lint)",
+      "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 ls:*)",
+      "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(git status)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)"
+    ]
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bunx biome check --no-errors-on-unmatched --write \\"$CLAUDE_FILE_PATHS\\" 2>/dev/null || true"
+          }
+        ]
+      }
+    ]
+  }
+}
+`;
+
+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.
+
+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
+own — see [The hook](#the-hook), and delete the \`hooks\` block if you would rather format by hand.
+
+| Path | What it costs | When you pay it |
+|---|---|---|
+| \`settings.json\` | nothing in context | read once per session; the hook runs per edit |
+| \`commands/*.md\` | nothing until invoked | the file is read when you type \`/<name>\` |
+| \`agents/*.md\` | one \`description\` line each | the body is read only when that agent is dispatched |
+
+So the whole bundle is three description lines of standing cost. The rest is paid on use.
+
+## What is here
+
+| File | For |
+|---|---|
+| \`commands/feature.md\` | \`/feature\` — build or fix one thing end to end, gated on \`x 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" |
+| \`agents/data.md\` | \`packages/db/\`, \`entity.ts\`, \`repo.ts\` |
+| \`agents/server.md\` | actions, mutators, queries, jobs, tasks, policies, \`apps/web/api/\` |
+| \`agents/web.md\` | \`apps/web/site/\`, pages, \`packages/ui/\`, tokens, i18n |
+
+The agents are scoped by **boundary**, not by role — each one's brief is a file set it may write and
+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
+the only list of kinds — a slash command restating it is a second copy that drifts the first time a
+kind is added.
+
+**No size budget on this directory.** How much your app writes down is your convention, not the
+framework's.
+
+## The hook
+
+One \`PostToolUse\` hook: \`bunx biome check --write\` on the file that was just edited. **\`--write\`
+means it rewrites that file in place** — the same safe fixes \`biome check --write .\` would make
+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\`
+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.
+
+## Where the rules live
+
+\`AGENTS.md\` at the repo root — the conventions. \`.claude/\` is only the harness that reads them.
+`;
+
+/** The agent harness for a new app: three commands, four boundary agents, settings, and a map. */
+export function claudeFiles(app: NameSet): readonly GeneratedFile[] {
+  return [
+    { path: '.claude/README.md', contents: readme(app) },
+    { path: '.claude/settings.json', contents: settings() },
+    ...claudeCommandFiles(app),
+    ...claudeAgentFiles(app),
+  ];
+}

package/src/templates/scaffold-container.ts

@@ -91,6 +91,11 @@ const composeProd = (
 # What \`x deploy --method compose\` runs. migrate runs to completion before anything serves.
 #
 #   IMAGE=ghcr.io/you/${app.kebab}:1.2.3 x deploy --image ghcr.io/you/${app.kebab}:1.2.3
+#
+# A published host port has exactly one binder, so \`web\` and \`sync\` run at 1 here. Compose is one
+# box; horizontal scaling of those two belongs to an orchestrator (copy \`docker/helm\` from the
+# framework repo). To scale them on one box anyway, drop \`ports:\` and put your own proxy on this
+# network — the service name resolves to every replica over the compose DNS round robin.
 name: ${app.kebab}
 
 x-image: &image
@@ -120,13 +125,33 @@ services:
     environment: [ROLE=migrate]
     restart: 'no'
 
+  # Run-once, AFTER the new version serves. Deliberately NOT part of the release gate: a slow
+  # UPDATE there holds the deploy open against a database still serving the previous version.
+  # Dry run is the default, so \`--write\` is explicit.
+  backfill:
+    <<: *image
+    # The image's ENTRYPOINT is \`bun apps/web/server.ts\`, and that entry reads ROLE and PORT and
+    # NOTHING ELSE — argv never reaches a parser. A bare \`command:\` is appended to it and silently
+    # discarded, so this service used to serve HTTP as ROLE=web under a name that said otherwise.
+    # Overriding the entrypoint is what makes the words below a command. The file path, not
+    # \`node_modules/.bin/x\`: it needs no bin symlink and no executable bit inside the image.
+    entrypoint: ['bun', 'node_modules/@ultimat3/cli/src/bin.ts']
+    command: ['db', 'backfill', '--all', '--write', '--json']
+    depends_on:
+      db: { condition: service_healthy }
+      migrate: { condition: service_completed_successfully }
+      # The barrier, not the ordering. \`docker compose up -d\` returns when a container STARTS, so
+      # listing this last would only look like "after". The image's HEALTHCHECK is what makes it true.
+      web: { condition: service_healthy }
+    restart: 'no'
+
   web:
     <<: *image
     environment: [ROLE=web]
     depends_on:
       db: { condition: service_healthy }
       migrate: { condition: service_completed_successfully }
-    deploy: { replicas: 2 } # stateless: scales on RPS
+    deploy: { replicas: 1 } # stateless, scales on RPS — pinned by the published port
     ports: ['3000:3000']
 
   sync:
@@ -135,7 +160,8 @@ services:
     depends_on:
       db: { condition: service_healthy }
       migrate: { condition: service_completed_successfully }
-    deploy: { replicas: 1 } # scales on concurrent websockets; no sticky sessions
+    deploy: { replicas: 1 } # scales on concurrent websockets, no sticky sessions — pinned by the port
+    # The sync role binds PORT + 1. PORT is unset here, so it is 3000 and this listens on 3001.
     ports: ['3001:3001']
 
   worker:
@@ -190,6 +216,11 @@ docker compose -f docker/docker-compose.prod.yml up -d      # db → migrate →
 x deploy --image ${app.kebab}:dev --dry-run --json           # the same plan, printed
 \`\`\`
 
+\`web\` and \`sync\` publish a host port, so both sit at \`replicas: 1\`: one host port has exactly one
+binder, and a second container dies on \`port is already allocated\`. \`worker\` publishes nothing and
+scales freely. To scale the two serving roles on one box, delete their \`ports:\` lines and put your
+own proxy on the compose network. To scale them properly, use an orchestrator — see below.
+
 ## The other two build targets
 
 \`\`\`sh
@@ -235,6 +266,19 @@ that no longer matches an applied migration stops the release instead of corrupt
 There is no \`x db migrate\` in that list on purpose: it is the developer's command and it needs the
 toolchain, while the release phase runs the shipped image and nothing else.
 
+### One-off commands need a new entrypoint, not arguments
+
+\`ENTRYPOINT\` is \`bun apps/web/server.ts\`, and that entry reads \`ROLE\` and \`PORT\` and **nothing
+else** — argv never reaches a parser. So arguments appended to it are discarded in silence:
+
+\`\`\`sh
+docker run ${app.kebab}:dev db backfill --all --write     # serves ROLE=web, forever
+docker run --entrypoint bun ${app.kebab}:dev node_modules/@ultimat3/cli/src/bin.ts db backfill --all --write --json
+\`\`\`
+
+The \`backfill\` service in \`docker-compose.prod.yml\` is the second form. A Kubernetes \`Job\` running
+a one-off command sets \`command:\` (the entrypoint) as well as \`args:\`, for the same reason.
+
 ## Environment
 
 | Key | Meaning | Unset means |

package/src/templates/scaffold-db-package.ts

@@ -0,0 +1,91 @@
+// The generated app's `packages/db`: the entity re-export list the migration generator reads and
+// the deterministic seed. No business logic — that is the package's own stated boundary, and it is
+// why `example` reaches only the two files describing the slice's table.
+//
+// No migration. `x db gen` is the ONE writer of `packages/db/migrations`, and a scaffold that hand-
+// wrote `0000_initial.sql` was a second one: it declared a `posts` table the generator had never
+// diffed, so the first `x db gen` saw a schema the ledger already claimed and the two disagreed
+// about what "initial" meant. `x db gen "initial"` is the app's first command instead — it writes
+// the `.sql`, the `.snapshot.json` and the `.hash` together, which no hand-written file can.
+
+import type { GeneratedFile, NameSet } from './naming';
+import { packageShapeFiles, workspacePackageJson } from './scaffold-package-shape';
+
+const DESCRIPTION = 'Entity re-exports and SQL migrations, no business logic';
+
+const dbIndex =
+  (): string => `// Schema and migrations only — no business logic lives in this package. The client itself is
+// @ultimat3/db's: one connection pool, sized by ROLE, shared by every package in the app.
+export type { DbClient, SqlFragment } from '@ultimat3/db';
+export { db, sql, withTransaction } from '@ultimat3/db';
+export * as schema from './schema';
+`;
+
+// The four pieces below describe the example slice's table. Under `--no-example` that slice is
+// never written, so each one ships its empty counterpart instead of a reference to a file that is
+// not there — `export { post } from …` alone made `x new --no-example` an app that cannot compile.
+
+const SCHEMA_HEADER = `// Every entity the app declares, re-exported here. This list is what the migration generator
+// reads, so an entity that is not exported here does not exist as far as the database is concerned.`;
+
+/**
+ * `bun run db:seed`'s entry point. Identical either way — only the rows differ. Interpolated, not
+ * nested, so it carries exactly the escaping a single template literal needs.
+ */
+const SEED_MAIN = `
+
+if (import.meta.main) {
+  const count = await seed();
+  // Bun's stdout, not process.stdout: one runtime, one API. Awaited because the write resolves
+  // asynchronously, and this JSON line is the whole output of \`bun run db:seed\`.
+  await Bun.stdout.write(\`\${JSON.stringify({ ok: true, seeded: count })}\\n\`);
+}
+`;
+
+const dbSchema = (app: NameSet, example: boolean): string =>
+  example
+    ? `${SCHEMA_HEADER}
+export { post } from '@${app.kebab}/web/app/post/entity';
+`
+    : `${SCHEMA_HEADER}
+// \`x g entity <name>\` writes the entity; add its export here so the database learns about it.
+export {};
+`;
+
+const dbSeed = (app: NameSet, example: boolean): string =>
+  example
+    ? `// Deterministic seed: same rows every time, so a test and a demo see the same database.
+import { db, sql } from '@ultimat3/db';
+
+const ORG = '00000000-0000-0000-0000-000000000002';
+
+export async function seed(): Promise<number> {
+  const rows = [
+    { id: '00000000-0000-0000-0000-000000000101', title: 'Hello ${app.pascal}', minor: 0 },
+    { id: '00000000-0000-0000-0000-000000000102', title: 'Second post', minor: 1900 },
+  ];
+  for (const row of rows) {
+    // Idempotent by primary key, so re-seeding a branch database is a no-op rather than a crash.
+    await db().execute(sql\`
+      insert into posts (id, org_id, title, price_minor, price_currency)
+      values (\${row.id}, \${ORG}, \${row.title}, \${row.minor}, 'USD')
+      on conflict (id) do nothing\`);
+  }
+  return rows.length;
+}${SEED_MAIN}`
+    : `// Deterministic seed: same rows every time, so a test and a demo see the same database.
+// No entity is declared yet, so there is nothing to insert — the shape stays, so the first
+// \`x g entity\` has one obvious place to seed from.
+
+export async function seed(): Promise<number> {
+  return 0;
+}${SEED_MAIN}`;
+
+/** Every file the `packages/db` workspace ships, in the order `x new` writes them. */
+export const dbPackageFiles = (app: NameSet, example: boolean): readonly GeneratedFile[] => [
+  { path: 'packages/db/package.json', contents: workspacePackageJson(app, 'db', DESCRIPTION) },
+  ...packageShapeFiles(app, 'db', DESCRIPTION),
+  { path: 'packages/db/src/index.ts', contents: dbIndex() },
+  { path: 'packages/db/src/schema.ts', contents: dbSchema(app, example) },
+  { path: 'packages/db/src/seed.ts', contents: dbSeed(app, example) },
+];

package/src/templates/scaffold-docs.ts

@@ -1,9 +1,11 @@
 // The human-authored half of what `x new` writes: the READMEs, the agent-facing convention files,
 // the bin/ shims and the optional dev compose. Separated from the config half so neither file has
 // to be scrolled to find the other — one file, one job applies to templates too. The image, its
-// ignore file, the production topology and the deploy page are `scaffold-container.ts`.
+// ignore file, the production topology and the deploy page are `scaffold-container.ts`; the
+// `.claude/` harness that reads AGENTS.md is `scaffold-claude.ts`.
 
 import type { GeneratedFile, NameSet } from './naming';
+import { claudeFiles } from './scaffold-claude';
 import { containerFiles } from './scaffold-container';
 
 const agents = (app: NameSet): string => `# AGENTS.md
@@ -23,7 +25,7 @@ agent cannot infer from the code.
 | Strings | every user-facing string goes through \`t()\` |
 | Colour | semantic tokens only, never a raw hex |
 
-Commands: \`x dev\`, \`x verify\`, \`x g <primitive>\`, \`x db branch <name>\`, \`x doctor\`.
+Commands: \`x dev\`, \`x verify\`, \`x g <primitive>\`, \`x db branch create <name>\`, \`x doctor\`.
 
 Project notes for ${app.kebab}: replace this line with the conventions a newcomer could not guess.
 `;
@@ -33,9 +35,14 @@ const claude = (app: NameSet): string => `# CLAUDE.md
 ${app.kebab} — Ultimate app. Read AGENTS.md first; it is the same content in the same order.
 
 - Gate: \`x verify\` (add \`--json\` for machine output).
-- Scaffold, do not hand-write: \`x g resource|action|job|route|policy|entity|query|task\`.
-- Destructive DB work goes in a branch: \`x db branch <name>\`, never the shared dev DB.
+- Scaffold, do not hand-write: \`x g <kind> <name>\` — \`x g --help\` lists every kind, and is the
+  only place that list is stated.
+- Destructive DB work goes in a branch: \`x db branch create <name>\`, never the shared dev DB.
 - \`x doctor\` explains a broken environment and prints the fix command for every finding.
+
+\`.claude/\` holds the harness that reads this file: \`/feature\`, \`/planx\`, \`/verify\` and four
+boundary-scoped subagents. It is yours — \`.claude/README.md\` says what each one costs, and every
+file in it is deletable.
 `;
 
 const readme = (app: NameSet): string => `# ${app.pascal}
@@ -45,11 +52,15 @@ Built with [Ultimate](https://ultimate.dev). Bun-only, Postgres, SolidJS.
 ## 🚀 Start
 
 \`\`\`sh
-bin/setup     # prerequisites, deps, env, migrate, seed
+bin/setup     # prerequisites, deps, env, the first migration, migrate, seed
 x dev         # all roles in one process, embedded Postgres, /_x mounted
 x verify      # the gate: typecheck, lint, boundaries, tests, drift, budgets
 \`\`\`
 
+\`packages/db/migrations\` starts empty and \`x db gen\` is its only writer — \`bin/setup\` runs
+\`x db gen "initial"\` for you on a fresh clone. Until it has, \`x verify\`'s \`drift\` step is red
+with \`X_DB_DRIFT\`, and that is the fix it names.
+
 ## 🗺 Layout
 
 | Path | Holds |
@@ -71,6 +82,11 @@ cd "$(dirname "$0")/.."
 command -v bun >/dev/null || { echo "X_BUN_MISSING: install bun — https://bun.sh"; exit 1; }
 bun install
 [ -f .env.development.local ] || printf '# per-box secrets, gitignored, wins over .env.development\\n' > .env.development.local
+# \`x db gen\` is the ONE writer of packages/db/migrations — the scaffold no longer hand-writes a
+# 0000_initial.sql, because a second writer is how the source and the ledger ended up disagreeing
+# about what "initial" meant. Guarded on the directory rather than on the generator being a no-op:
+# this script is documented idempotent, and the guard is what makes that true here.
+ls packages/db/migrations/*.sql >/dev/null 2>&1 || bunx x db gen "initial"
 bunx x db migrate "$@"
 bun run db:seed
 echo "setup complete — next: x dev"
@@ -126,6 +142,9 @@ export function docsFiles(app: NameSet): readonly GeneratedFile[] {
     { path: 'bin/dev', contents: binDev() },
     { path: 'bin/check', contents: binCheck() },
     { path: 'docker/docker-compose.dev.yml', contents: composeDev(app) },
+    // The harness half of the same job AGENTS.md does. It lands in the app's own repo rather than
+    // in a global config, so it is visible in the scaffold's diff and deletable in one line.
+    ...claudeFiles(app),
     ...containerFiles(app),
   ];
 }