@ultimat3/cli 21.0.0 → 22.0.0

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

@@ -0,0 +1,184 @@
+// The production topology `x new` writes: one compose service per role, one image. Split from
+// scaffold-container.ts, which holds the image and the page that explains it; this file is what
+// `x deploy --method compose` runs, and the single-node rung of the scale ladder.
+
+import type { NameSet } from './naming';
+
+/**
+ * The production env file, relative to the app root. Named once because two readers must agree:
+ * the compose file's \`env_file:\` (what the containers see) and \`x deploy\`'s \`--env-file\` (what
+ * compose interpolates \`\${VAR:?…}\` from). Two spellings would let them drift apart silently.
+ */
+export const PROD_ENV_FILE = '.env.production';
+
+/** The production topology `x new` writes at `docker/docker-compose.prod.yml`. */
+export const composeProdFile = (
+  app: NameSet,
+): string => `# The production topology: one service per role, one image, differing only by ROLE and replicas.
+# 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
+#
+# 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.
+#
+#   docker compose --env-file ${PROD_ENV_FILE} -f docker/docker-compose.prod.yml up -d
+#
+# 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 — \`docker/helm\`, beside this
+# file, is the chart \`x deploy --method helm\` installs. 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}
+
+# Every service's logs, rotated. Docker's default json-file driver never rotates, so a chatty role
+# on a long-lived box fills the disk the database lives on; 3 x 10 MB per container is the ceiling.
+x-logging: &logging
+  driver: json-file
+  options: { max-size: 10m, max-file: '3' }
+
+x-image: &image
+  image: \${IMAGE:-${app.kebab}:dev}
+  env_file: [../${PROD_ENV_FILE}]
+  restart: unless-stopped
+  logging: *logging
+  # SIGTERM → /readyz answers 503 for the readiness grace (5s outside local environments), then the
+  # drain of in-flight requests, jobs and sockets (25s). 40s leaves 10s before Docker SIGKILLs.
+  stop_grace_period: 40s
+  # What the chart's securityContext applies, on the rung that had none: a read-only root
+  # 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.
+  read_only: true
+  tmpfs: [/tmp, /app/.x]
+  cap_drop: [ALL]
+  security_opt: ['no-new-privileges:true']
+  mem_limit: 1g
+  depends_on:
+    db: { condition: service_healthy }
+
+# The image's own HEALTHCHECK fetches \`/readyz\` on $PORT, and only \`web\` and \`sync\` open an HTTP
+# socket — every other role gets the scrape listener and nothing else. A service that inherits that
+# probe is fetching a port it never binds: it reports \`unhealthy\` for its whole life and anything
+# gated on it never starts. Probes follow the role here, exactly as they do in \`docker/helm\`.
+x-metrics-probe: &metrics-probe
+  test: ['CMD', 'bun', '--eval', "fetch('http://127.0.0.1:'+(process.env.METRICS_PORT||9090)+'/metrics').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"]
+  interval: 10s
+  timeout: 3s
+  start_period: 30s
+  retries: 3
+
+# Run-once services exit. A probe against an exited container reports \`unhealthy\` forever, and
+# nothing waits on their health — \`service_completed_successfully\` is what the others gate on.
+x-run-once-probe: &run-once-probe
+  disable: true
+
+services:
+  db:
+    image: postgres:17-alpine
+    environment:
+      POSTGRES_PASSWORD: \${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}
+      POSTGRES_DB: ${app.kebab}
+    volumes: ['pgdata:/var/lib/postgresql/data']
+    healthcheck:
+      test: ['CMD-SHELL', 'pg_isready -U postgres']
+      interval: 5s
+    restart: unless-stopped
+    logging: *logging
+
+  # The release phase. Applies pending migrations under an advisory lock and exits; every serving
+  # role waits for it to complete, so no replica ever serves against a schema it does not ship.
+  migrate:
+    <<: *image
+    environment: [ROLE=migrate]
+    restart: 'no'
+    healthcheck: *run-once-probe
+
+  # 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'
+    healthcheck: *run-once-probe
+
+  web:
+    <<: *image
+    # The page dials SYNC_URL; unset, it dials /_x/sync on :3000, which web does not serve here.
+    # Set it in ${PROD_ENV_FILE}: \`--env-file\` (header) is what lets this line read it there.
+    environment: [ROLE=web, 'SYNC_URL=\${SYNC_URL:?set SYNC_URL=ws://<host>:3001/_x/sync, see wiki/Deployment.md}']
+    depends_on:
+      db: { condition: service_healthy }
+      migrate: { condition: service_completed_successfully }
+    deploy: { replicas: 1 } # stateless, scales on RPS — pinned by the published port
+    ports: ['3000:3000']
+
+  sync:
+    <<: *image
+    environment: [ROLE=sync]
+    depends_on:
+      db: { condition: service_healthy }
+      migrate: { condition: service_completed_successfully }
+    # OFF by default (zero replicas). A sync node on this database hears committed changes only
+    # from a replicator it can reach, and this file runs none: booted anyway it is refused
+    # (X_REALTIME_TOPOLOGY). To turn live queries and channels on: declare realtime: { enabled:
+    # true, transport: 'nats', urlEnv: 'NATS_URL' } in app.config.ts, add a NATS service and set the
+    # SAME NATS_URL for web, sync and a replicator service (ROLE=replicator, exactly one), start
+    # Postgres with wal_level=logical and a publication for the entity tables, then set replicas: 1.
+    # A NATS_URL under transport 'memory' refuses the boot (X_CONFIG_INVALID), and so does 'nats'
+    # without one.
+    deploy: { replicas: 0 } # when on: scales on concurrent websockets — pinned to 1 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']
+    # ...which is why the image's own HEALTHCHECK cannot be inherited here. It fetches $PORT —
+    # 3000 — and this role never binds it, so the container reports \`unhealthy\` from
+    # \`start_period\` onward and never recovers, and anything gated on \`sync: service_healthy\`
+    # would never start. Literal 3001 rather than an expression, for the same reason \`ports:\`
+    # above is literal: PORT is unset in this file, and two ways of saying one number drift.
+    # \`docker/helm\` states the same rule as \`PORT = .port - 1\`.
+    healthcheck:
+      test: ['CMD', 'bun', '--eval', "fetch('http://127.0.0.1:3001/readyz').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"]
+      interval: 10s
+      timeout: 3s
+      start_period: 30s
+      retries: 3
+
+  worker:
+    <<: *image
+    environment: [ROLE=worker]
+    depends_on:
+      db: { condition: service_healthy }
+      migrate: { condition: service_completed_successfully }
+    healthcheck: *metrics-probe
+    deploy: { replicas: 1 } # scales on queue depth
+
+  scheduler:
+    <<: *image
+    environment: [ROLE=scheduler]
+    depends_on:
+      db: { condition: service_healthy }
+      migrate: { condition: service_completed_successfully }
+    # Fixed 1. Leadership is an EXPIRING LEASE ROW in \`x_scheduler_leader\` (role-start.ts,
+    # driver-pg-ddl.ts), NOT an advisory lock: that grant belongs to the session, not to the
+    # process — it outlives every transaction and no pooled node can renew it or prove it still
+    # holds one. A second instance is harmless but idle.
+    healthcheck: *metrics-probe
+    deploy: { replicas: 1 }
+
+volumes:
+  pgdata:
+`;

package/src/templates/scaffold-container.ts

@@ -8,6 +8,7 @@
 
 import { SECRETS_KEY_FILE } from '@ultimat3/core';
 import type { GeneratedFile, NameSet } from './naming';
+import { composeProdFile, PROD_ENV_FILE } from './scaffold-container-compose';
 import { helmFiles } from './scaffold-helm';
 
 const dockerfile = (
@@ -21,13 +22,24 @@ const dockerfile = (
 #
 # syntax=docker/dockerfile:1
 
-# ---------- deps: runtime dependencies only, cached on the workspace manifests ----------
+# ---------- manifests: every workspace package.json, and nothing else ----------
+# The install below must be keyed on the MANIFESTS, not on the source: copying \`apps\` and
+# \`packages\` ahead of \`bun install\` made every edit to a page a full reinstall. The set is derived
+# from the context rather than listed, so a workspace glob added later is not a lockfile the frozen
+# install refuses. \`bunfig.toml\` survives because its \`[install]\` section is input to the install,
+# and so does a \`.tgz\`: a \`file:\` tarball dependency (a vendored or private package) is resolved
+# from the file itself, and without it the frozen install cannot find what the lockfile names.
+FROM oven/bun:1.4-alpine AS manifests
+WORKDIR /app
+COPY . .
+RUN find . ! -type d ! -name package.json ! -name bunfig.toml ! -name '*.tgz' -delete \\
+ && find . -type d -empty -delete
+
+# ---------- deps: runtime dependencies only, cached on the lockfile and the manifests ----------
 FROM oven/bun:1.4-alpine AS deps
 WORKDIR /app
-COPY package.json bun.lock ./
-# The workspace members' manifests are what \`bun install\` resolves against; their sources are not.
-COPY apps ./apps
-COPY packages ./packages
+COPY --from=manifests /app ./
+COPY bun.lock ./
 RUN bun install --frozen-lockfile --production
 
 # ---------- runtime ----------
@@ -35,9 +47,13 @@ RUN bun install --frozen-lockfile --production
 # before it ever calls \`docker build\`. Re-running typecheck and lint here would need the
 # devDependencies the \`--production\` install above deliberately leaves out — which is exactly how
 # a build stage came to run \`tsc\` and \`biome\` against a tree that had neither.
-FROM oven/bun:1.4-alpine AS runtime
+#
+# Built ON the install stage, so the WHOLE installed tree comes with it — Bun's isolated linker
+# links a workspace's dependencies under that workspace's own \`node_modules\`, and copying only the
+# root one left \`apps/web\`'s behind — and the source lands on top (the ignore file drops every host
+# \`node_modules\`, so the two merge). The layer cache is the same as a COPY from it would be.
+FROM deps AS runtime
 WORKDIR /app
-COPY --from=deps /app/node_modules ./node_modules
 COPY . .
 
 # The immutable content hash this image serves. Stamped by CI (\`--build-arg BUILD_ID=$(git rev-parse HEAD)\`);
@@ -112,157 +128,6 @@ coverage
 **/playwright-report
 `;
 
-/**
- * The production env file, relative to the app root. Named once because two readers must agree:
- * the compose file's \`env_file:\` (what the containers see) and \`x deploy\`'s \`--env-file\` (what
- * compose interpolates \`\${VAR:?…}\` from). Two spellings would let them drift apart silently.
- */
-export const PROD_ENV_FILE = '.env.production';
-
-const composeProd = (
-  app: NameSet,
-): string => `# The production topology: one service per role, one image, differing only by ROLE and replicas.
-# 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
-#
-# 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.
-#
-#   docker compose --env-file ${PROD_ENV_FILE} -f docker/docker-compose.prod.yml up -d
-#
-# 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 — \`docker/helm\`, beside this
-# file, is the chart \`x deploy --method helm\` installs. 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
-  image: \${IMAGE:-${app.kebab}:dev}
-  env_file: [../${PROD_ENV_FILE}]
-  restart: unless-stopped
-  stop_grace_period: 30s # SIGTERM → drain in-flight requests, jobs and sockets
-  depends_on:
-    db: { condition: service_healthy }
-
-# The image's own HEALTHCHECK fetches \`/readyz\` on $PORT, and only \`web\` and \`sync\` open an HTTP
-# socket — every other role gets the scrape listener and nothing else. A service that inherits that
-# probe is fetching a port it never binds: it reports \`unhealthy\` for its whole life and anything
-# gated on it never starts. Probes follow the role here, exactly as they do in \`docker/helm\`.
-x-metrics-probe: &metrics-probe
-  test: ['CMD', 'bun', '--eval', "fetch('http://127.0.0.1:'+(process.env.METRICS_PORT||9090)+'/metrics').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"]
-  interval: 10s
-  timeout: 3s
-  start_period: 30s
-  retries: 3
-
-# Run-once services exit. A probe against an exited container reports \`unhealthy\` forever, and
-# nothing waits on their health — \`service_completed_successfully\` is what the others gate on.
-x-run-once-probe: &run-once-probe
-  disable: true
-
-services:
-  db:
-    image: postgres:17-alpine
-    environment:
-      POSTGRES_PASSWORD: \${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}
-      POSTGRES_DB: ${app.kebab}
-    volumes: ['pgdata:/var/lib/postgresql/data']
-    healthcheck:
-      test: ['CMD-SHELL', 'pg_isready -U postgres']
-      interval: 5s
-    restart: unless-stopped
-
-  # The release phase. Applies pending migrations under an advisory lock and exits; every serving
-  # role waits for it to complete, so no replica ever serves against a schema it does not ship.
-  migrate:
-    <<: *image
-    environment: [ROLE=migrate]
-    restart: 'no'
-    healthcheck: *run-once-probe
-
-  # 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'
-    healthcheck: *run-once-probe
-
-  web:
-    <<: *image
-    # The page dials SYNC_URL; unset, it dials /_x/sync on :3000, which web does not serve here.
-    # Set it in ${PROD_ENV_FILE}: \`--env-file\` (header) is what lets this line read it there.
-    environment: [ROLE=web, 'SYNC_URL=\${SYNC_URL:?set SYNC_URL=ws://<host>:3001/_x/sync, see wiki/Deployment.md}']
-    depends_on:
-      db: { condition: service_healthy }
-      migrate: { condition: service_completed_successfully }
-    deploy: { replicas: 1 } # stateless, scales on RPS — pinned by the published port
-    ports: ['3000:3000']
-
-  sync:
-    <<: *image
-    environment: [ROLE=sync]
-    depends_on:
-      db: { condition: service_healthy }
-      migrate: { condition: service_completed_successfully }
-    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']
-    # ...which is why the image's own HEALTHCHECK cannot be inherited here. It fetches $PORT —
-    # 3000 — and this role never binds it, so the container reports \`unhealthy\` from
-    # \`start_period\` onward and never recovers, and anything gated on \`sync: service_healthy\`
-    # would never start. Literal 3001 rather than an expression, for the same reason \`ports:\`
-    # above is literal: PORT is unset in this file, and two ways of saying one number drift.
-    # \`docker/helm\` states the same rule as \`PORT = .port - 1\`.
-    healthcheck:
-      test: ['CMD', 'bun', '--eval', "fetch('http://127.0.0.1:3001/readyz').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"]
-      interval: 10s
-      timeout: 3s
-      start_period: 30s
-      retries: 3
-
-  worker:
-    <<: *image
-    environment: [ROLE=worker]
-    depends_on:
-      db: { condition: service_healthy }
-      migrate: { condition: service_completed_successfully }
-    healthcheck: *metrics-probe
-    deploy: { replicas: 1 } # scales on queue depth
-
-  scheduler:
-    <<: *image
-    environment: [ROLE=scheduler]
-    depends_on:
-      db: { condition: service_healthy }
-      migrate: { condition: service_completed_successfully }
-    # Fixed 1. Leadership is an EXPIRING LEASE ROW in \`x_scheduler_leader\` (dev-roles.ts,
-    # driver-pg-ddl.ts), NOT an advisory lock: that grant belongs to the session, not to the
-    # process — it outlives every transaction and no pooled node can renew it or prove it still
-    # holds one. A second instance is harmless but idle.
-    healthcheck: *metrics-probe
-    deploy: { replicas: 1 }
-
-volumes:
-  pgdata:
-`;
-
 const readme = (app: NameSet): string => `# docker
 
 One image, every role. \`ROLE\` selects behaviour at start, so there is one artifact to promote and
@@ -398,7 +263,7 @@ export function containerFiles(app: NameSet): readonly GeneratedFile[] {
   return [
     { path: 'docker/Dockerfile', contents: dockerfile(app) },
     { path: 'docker/Dockerfile.dockerignore', contents: dockerignore() },
-    { path: 'docker/docker-compose.prod.yml', contents: composeProd(app) },
+    { path: 'docker/docker-compose.prod.yml', contents: composeProdFile(app) },
     { path: 'docker/README.md', contents: readme(app) },
     // The other deploy method's topology, on the same terms as the compose file above: `x deploy`
     // is one `helm upgrade --install` against this directory, and a chart that shipped in no npm

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

@@ -19,7 +19,6 @@ const examplePage = (
 ${sortedImports([
   `import { useT } from '@${app.kebab}/i18n';`,
   "import { isUltimateError } from '@ultimat3/core';",
-  "import { seedId } from '@ultimat3/entity';",
   "import { currentLocale } from '@ultimat3/i18n';",
   "import { defineRoute, island } from '@ultimat3/render';",
   [
@@ -35,6 +34,7 @@ ${sortedImports([
     "} from '@ultimat3/ui';",
   ].join('\n'),
 ])}
+import { DEMO_ORG_ID } from '../../shared/demo-org';
 import { Shell } from '../../shared/shell';
 import * as repo from '../post/repo';
 import {
@@ -53,7 +53,7 @@ import styles from './page.module.scss';
  * one \`packages/db/src/seed.ts\` writes. The day sessions exist, this becomes the actor's org and
  * the read becomes \`postList.as(actor, …)\` — the query already declares the tenancy rule.
  */
-const DEMO_ORG = seedId('org:demo');
+const DEMO_ORG = DEMO_ORG_ID;
 
 /** The stat row counts what it can see. Past this many posts, write an aggregate query. */
 const ROW_LIMIT = 500;

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

@@ -94,6 +94,19 @@ export {};
  *
  * `x db seed` owns the connection, the tier and the per-seed transaction. One runner, one answer.
  */
+/**
+ * The seed's two package imports in the order Biome sorts them: the app's own scope can sort on
+ * either side of \`@ultimat3\`, and a fixed order is a lint failure for half of all app names.
+ */
+const seedImports = (app: NameSet): string =>
+  [
+    [`@${app.kebab}/web/shared/demo-org`, 'DEMO_ORG_LABEL'],
+    ['@ultimat3/entity', 'defineSeed'],
+  ]
+    .sort(([a = ''], [b = '']) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([from, name]) => `import { ${name} } from '${from}';`)
+    .join('\n');
+
 const dbSeed = (app: NameSet, example: boolean): string =>
   example
     ? `// Deterministic fixtures: the same rows every time, so a test, a demo and a branch database
@@ -104,7 +117,7 @@ const dbSeed = (app: NameSet, example: boolean): string =>
 // included), and wraps each seed in its own transaction. Never a plain \`bun run\` script: that
 // reaches the database through \`db()\`, which needs a \`postgres:\` \`DATABASE_URL\` and so cannot
 // see the embedded database at all.
-import { defineSeed } from '@ultimat3/entity';
+${seedImports(app)}
 import { post } from './schema';
 
 /** Stable across runs: \`id('post:hello')\` is a UUID v5 of the label, not a random one. */
@@ -112,13 +125,13 @@ export const ${app.camel}Seed = defineSeed('${app.kebab}', async ({ insert, id }
   await insert(post, [
     {
       id: id('post:hello'),
-      orgId: id('org:demo'),
+      orgId: id(DEMO_ORG_LABEL),
       title: 'Hello ${app.pascal}',
       price: { minor: 0, currency: 'USD' },
     },
     {
       id: id('post:second'),
-      orgId: id('org:demo'),
+      orgId: id(DEMO_ORG_LABEL),
       title: 'Second post',
       price: { minor: 1900, currency: 'USD' },
     },

package/src/templates/scaffold-demo-org.ts

@@ -0,0 +1,41 @@
+// `apps/web/shared/demo-org.ts`: the ONE org this app has until it issues sessions. The dev actor
+// named `'dev-org'`, the seed wrote `id('org:demo')` and the dashboard computed a third copy — so a
+// generated tenant policy (`actor.orgId === input.orgId`, a `t.uuid`) could never pass for the dev
+// actor, and every generated write answered 403 under a green gate.
+
+import type { GeneratedFile } from './naming';
+
+const demoOrg =
+  (): string => `// The org every development-only fact belongs to: the dev actor's \`orgId\`, the org the seed
+// writes its rows under, and the org the dashboard aggregates. One constant, so the three cannot
+// disagree — a policy deciding \`actor.orgId === input.orgId\` passes for the dev actor on the rows
+// the seed wrote. Replace its readers when this app issues real sessions.
+import { seedId } from '@ultimat3/entity';
+
+/** The label \`defineSeed\`'s \`id()\` derives the uuid from — the same uuid on every run. */
+export const DEMO_ORG_LABEL = 'org:demo';
+
+/** \`seedId(DEMO_ORG_LABEL)\`: a uuid v5, exactly what the seed's \`id(DEMO_ORG_LABEL)\` answers. */
+export const DEMO_ORG_ID = seedId(DEMO_ORG_LABEL);
+`;
+
+const demoOrgTest =
+  (): string => `// The dev actor, the seed and the dashboard all read DEMO_ORG_ID. If it stops being the uuid the
+// seed's \`id()\` derives, a generated tenant policy denies the dev actor again.
+import { seedId } from '@ultimat3/entity';
+import { expect, unitTest } from '@ultimat3/testing';
+import { DEMO_ORG_ID, DEMO_ORG_LABEL } from './demo-org';
+
+const UUID_V5 = /^[0-9a-f]{8}-[0-9a-f]{4}-5[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+unitTest('the demo org is the uuid the seed writes', () => {
+  expect(DEMO_ORG_ID).toBe(seedId(DEMO_ORG_LABEL));
+  expect(DEMO_ORG_ID).toMatch(UUID_V5);
+});
+`;
+
+/** Written by `x new`, with or without the example slice: the dev actor always reads it. */
+export const demoOrgFiles = (): readonly GeneratedFile[] => [
+  { path: 'apps/web/shared/demo-org.ts', contents: demoOrg() },
+  { path: 'apps/web/shared/demo-org.test.ts', contents: demoOrgTest() },
+];

package/src/templates/scaffold-entries.ts

@@ -15,7 +15,7 @@ const server =
 // shares the host's network namespace (\`--network host\`), or through a sidecar and \`ssh -L\`.
 
 import { join } from 'node:path';
-import { runRole } from '@ultimat3/cli';
+import { runRole } from '@ultimat3/cli/serve';
 
 // MORE THAN ONE REPLICA? Add these two lines, above \`runRole\`:
 //