@ultimat3/cli 20.2.1 → 22.0.0

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,142 +128,6 @@ coverage
 **/playwright-report
 `;
 
-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
-#
-# 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: [../.env.production]
-  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
-    environment: [ROLE=web]
-    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
@@ -276,7 +156,7 @@ docker run -p 3000:3000 -e DATABASE_URL=postgres://... ${app.kebab}:dev
 ## One box, every role
 
 \`\`\`sh
-docker compose -f docker/docker-compose.prod.yml up -d      # db → migrate → the rest
+docker compose --env-file ${PROD_ENV_FILE} -f docker/docker-compose.prod.yml up -d   # db → migrate → the rest
 x deploy --image ${app.kebab}:dev --dry-run --json           # the same plan, printed
 \`\`\`
 
@@ -383,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\`:
 //

package/src/templates/scaffold-env.ts

@@ -29,6 +29,12 @@ export const SCAFFOLD_ENV_SCHEMA = {
     role: 'sync',
     description: 'Realtime fan-out cluster. Only the sync role is asked for it.',
   },
+  SYNC_URL: {
+    type: 'string',
+    required: false,
+    role: 'web',
+    description: 'Where a page dials the sync socket. Compose: ws://<host>:3001/_x/sync',
+  },
   SESSION_SECRET: {
     type: 'string',
     required: false,

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

@@ -12,8 +12,18 @@ const helpers = (
 {{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" -}}
 {{- end -}}
 
+{{/*
+helm create's rule: a release whose name already contains the chart's is the full name on its own.
+x deploy --method helm names the release after the app, which IS the chart name, so without it
+every object would be ${app.kebab}-${app.kebab}-web.
+*/}}
 {{- define "${app.kebab}.fullname" -}}
-{{- printf "%s-%s" .Release.Name (include "${app.kebab}.name" .) | trunc 63 | trimSuffix "-" -}}
+{{- $name := include "${app.kebab}.name" . -}}
+{{- if contains $name .Release.Name -}}
+{{- .Release.Name | trunc 63 | trimSuffix "-" -}}
+{{- else -}}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
 {{- end -}}
 
 {{/*
@@ -92,15 +102,38 @@ nobody bound. Derived here rather than stated twice in values.yaml, where the tw
   HTTP and get both. worker, scheduler and replicator open no HTTP socket at all — the scrape
   listener is their only port — so they take liveness on it and NO readiness: nothing routes to
   them, and a readiness flap would drop the pod out of the Service and so out of the scrape.
+
+  Every one of them takes a startupProbe too, because no listener opens early: the server builds
+  the app's islands before any role binds a port, and a liveness probe counting from container
+  start restarts a pod that is merely booting. 30 x 5s = 150s of boot, then the ordinary checks.
   */}}
   {{- if $cfg.port }}
+  startupProbe:
+    httpGet: { path: /healthz, port: http }
+    periodSeconds: 5
+    failureThreshold: 30
   readinessProbe:
     httpGet: { path: /readyz, port: http }
     periodSeconds: 5
   livenessProbe:
     httpGet: { path: /healthz, port: http }
     periodSeconds: 15
+  {{- /*
+  Holds SIGTERM back while the pod is already out of its Service's endpoints, so a proxy that has
+  not caught up still reaches a listener that answers. lifecycle.preStop.sleep exists from
+  Kubernetes 1.30 and this chart's floor is 1.27, so it renders only where the API server knows it;
+  below that the framework's own readiness grace (/readyz at 503, listener still open) covers it.
+  */}}
+  {{- if semverCompare ">=1.30-0" $root.Capabilities.KubeVersion.Version }}
+  lifecycle:
+    preStop:
+      sleep: { seconds: {{ $root.Values.drain.preStopSleepSeconds | int }} }
+  {{- end }}
   {{- else if $scraped }}
+  startupProbe:
+    httpGet: { path: /metrics, port: metrics }
+    periodSeconds: 5
+    failureThreshold: 30
   livenessProbe:
     httpGet: { path: /metrics, port: metrics }
     periodSeconds: 15
@@ -114,8 +147,9 @@ nobody bound. Derived here rather than stated twice in values.yaml, where the tw
 `;
 
 const deployments = (app: NameSet): string => `{{/*
-One Deployment per enabled role, from one image. terminationGracePeriodSeconds matches the
-framework's SIGTERM drain: in-flight requests, open websockets and running job steps finish.
+One Deployment per enabled role, from one image. terminationGracePeriodSeconds covers the preStop
+sleep, the framework's readiness grace and its SIGTERM drain: in-flight requests, open websockets
+and running job steps finish.
 */}}
 {{- range $role, $cfg := .Values.roles }}
 {{- if $cfg.enabled }}
@@ -151,9 +185,11 @@ spec:
       code that reaches the filesystem, which for a web role is one path traversal. */}}
       automountServiceAccountToken: false
       securityContext: {{- toYaml $.Values.podSecurityContext | nindent 8 }}
-      {{/* At least the framework's drain deadline (25s by default), which is what
-      X_SHUTDOWN_TIMEOUT's fix line tells an operator. Raise this WITH configureLifecycle({
-      deadlineMs }), never instead of it: the drain abandons its hooks at its own deadline. */}}
+      {{/* Spent in order: the preStop sleep (drain.preStopSleepSeconds, 1.30+), the framework's
+      readiness grace (5s outside local environments) and its drain deadline (25s, which is what
+      X_SHUTDOWN_TIMEOUT's fix line names) — 35s, so 45 leaves 10s before SIGKILL. Raise this WITH
+      configureLifecycle({ deadlineMs, readinessGraceMs }), never instead of it: the drain
+      abandons its hooks at its own deadline. */}}
       terminationGracePeriodSeconds: 45
       containers:
         {{- include "${app.kebab}.container" (dict "role" $role "cfg" $cfg "root" $) | nindent 8 }}
@@ -259,12 +295,16 @@ spec:
         paths:
           {{- /* The path the sync node actually serves. Routing /_sync instead sends every
           websocket to the web role, which answers no upgrade. */}}
+          {{- /* Only when the sync role runs: a rule naming a Service the chart did not render is an
+          ingress that 503s every websocket instead of letting it reach nothing at all. */}}
+          {{- if .Values.roles.sync.enabled }}
           - path: /_x/sync
             pathType: Prefix
             backend:
               service:
                 name: {{ include "${app.kebab}.fullname" . }}-sync
                 port: { name: http }
+          {{- end }}
           - path: /
             pathType: Prefix
             backend:
@@ -277,8 +317,13 @@ spec:
 const hpa = (app: NameSet): string => `{{/*
 Per-role autoscalers, off until you turn one on. Each role scales on the signal that predicts ITS
 saturation — CPU is a lagging proxy for all three and scales the wrong thing at the wrong time.
-A Pods metric needs a metrics adapter in the cluster; without one the HPA reads <unknown> and
+Either metric type needs a metrics adapter in the cluster; without one the HPA reads <unknown> and
 holds at minReplicas, which is why these are opt-in rather than a default nobody wired.
+
+autoscaling.type says whose number it is. Pods (the default) is a per-pod series — rps, open
+sockets — averaged across pods. External is ONE series for the whole role, divided by the replica
+count: queue_depth is that shape, because every worker publishes the same global backlog, and read
+as Pods it asked for N times the workers the queue needed. Any other type fails the render.
 */}}
 {{- range $role, $cfg := .Values.roles }}
 {{- if and $cfg.enabled $cfg.autoscaling $cfg.autoscaling.enabled }}
@@ -297,7 +342,20 @@ spec:
     name: {{ include "${app.kebab}.fullname" $ }}-{{ $role }}
   minReplicas: {{ $cfg.autoscaling.minReplicas }}
   maxReplicas: {{ $cfg.autoscaling.maxReplicas }}
+  {{- $type := default "Pods" $cfg.autoscaling.type }}
+  {{- if not (has $type (list "Pods" "External")) }}
+  {{- fail (printf "roles.%s.autoscaling.type is %q — set it to Pods (a per-pod series) or External (one series for the whole role, e.g. queue_depth)" $role $type) }}
+  {{- end }}
   metrics:
+    {{- if eq $type "External" }}
+    - type: External
+      external:
+        metric:
+          name: {{ $cfg.autoscaling.metric }}
+        target:
+          type: AverageValue
+          averageValue: {{ $cfg.autoscaling.targetAverageValue | quote }}
+    {{- else }}
     - type: Pods
       pods:
         metric:
@@ -305,6 +363,7 @@ spec:
         target:
           type: AverageValue
           averageValue: {{ $cfg.autoscaling.targetAverageValue | quote }}
+    {{- end }}
   behavior:
     scaleUp:
       stabilizationWindowSeconds: 30

package/src/templates/scaffold-helm.ts

@@ -34,7 +34,7 @@ image:
 env:
   NODE_ENV: production
 
-existingSecret: ${app.kebab}-secrets   # DATABASE_URL, NATS_URL, S3_*, AUTH_SECRET
+existingSecret: ${app.kebab}-secrets   # DATABASE_URL, NATS_URL, S3_*, AUTH_SECRET, ULTIMATE_CURSOR_SECRET
 
 # The scrape listener every serving role opens, on its own port and never the app's: the ingress
 # routes / to web, so /metrics beside /healthz on 3000 is /metrics on the internet. This is
@@ -51,6 +51,12 @@ securityContext:
   readOnlyRootFilesystem: true
   capabilities: { drop: [ALL] }
 
+# The stop sequence: out of the Service, then this preStop sleep (Kubernetes 1.30+ only), then
+# SIGTERM, then the framework's readiness grace and drain. terminationGracePeriodSeconds in
+# templates/deployments.yaml is sized to all three, so move them together.
+drain:
+  preStopSleepSeconds: 5
+
 # The release phase. Runs to completion before any serving role starts.
 migrate:
   enabled: true
@@ -63,8 +69,10 @@ migrate:
 # PORT: they differ for sync, which binds PORT + 1, and the chart derives the env from this number
 # so there is only ever one to move.
 #
-# Autoscaling is off until you wire a metrics adapter — each \`metric\` below is a Pods metric the
-# role exports, and an HPA with no adapter behind it reads <unknown> and holds at minReplicas.
+# Autoscaling is off until you wire a metrics adapter — each \`metric\` below is a series the role
+# exports, and an HPA with no adapter behind it reads <unknown> and holds at minReplicas.
+# \`type\` is Pods (the default: a per-pod series averaged across pods) or External (one series for
+# the whole role, divided by the replica count).
 roles:
   web:
     enabled: true
@@ -81,7 +89,14 @@ roles:
       targetAverageValue: "50"
 
   sync:
-    enabled: true
+    # OFF by default. A sync pod on a real database hears committed changes only from a replicator
+    # it can reach, and a fresh deploy has 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 (a NATS_URL under transport 'memory' is refused, and
+    # 'nats' without it is too); run NATS and set the SAME NATS_URL for web, sync and the
+    # replicator; enable exactly one replicator (below) against a Postgres started with
+    # wal_level=logical and a publication for the entity tables; then set this to true.
+    enabled: false
     replicas: 2
     port: 3001
     resources:
@@ -104,6 +119,10 @@ roles:
       enabled: false
       minReplicas: 1
       maxReplicas: 50
+      # External: every worker publishes the SAME global backlog, so averaged as a Pods metric it
+      # asked for N times the workers the queue needed. Expose it from your adapter deduplicated —
+      # max(queue_depth), never sum, which would multiply it by the pod count again.
+      type: External
       metric: queue_depth       # jobs waiting, exported by the worker role
       targetAverageValue: "100"
 
@@ -112,9 +131,12 @@ roles:
     # Fixed 1, and a second replica is safe but pointless: leadership is an expiring row in
     # x_scheduler_leader, so the extra pod stands by.
     replicas: 1
+    # 512Mi, not 256Mi: a scaffolded app measured ~325 MiB at boot as ROLE=scheduler (2026-09-23),
+    # when every role still built the app's islands first; at 256Mi the pod was OOMKilled on every
+    # boot. Only web builds islands now, so the peak is lower but unmeasured, and the limit stays.
     resources:
       requests: { cpu: 50m, memory: 128Mi }
-      limits: { memory: 256Mi }
+      limits: { memory: 512Mi }
 
   replicator:
     enabled: false              # exactly one per database; enable when the change feed is in use

package/src/templates/scaffold-i18n.ts

@@ -28,27 +28,31 @@ const i18nPackage = (app: NameSet, version: string): string => `{
 `;
 
 /**
- * `en` first, then every other locale alphabetically — a stable order so a diff shows only the
- * locale a run actually added, never a reshuffle. `en` is always included: `default: 'en'` below
- * requires it to be a registered locale, and every real catalog set already has one from `x new`
- * scaffold time.
+ * The default locale first, then every other one alphabetically — a stable order so a diff shows
+ * only the locale a run actually added. The default is `en` when the set holds it (and when the set
+ * is empty, which is `x new`), else the first tag: importing an `en.json` the app does not have is
+ * a file that does not compile.
  */
+export const defaultLocaleOf = (locales: readonly string[]): string =>
+  locales.length === 0 || locales.includes('en') ? 'en' : ([...locales].sort()[0] ?? 'en');
+
 const orderedLocales = (locales: readonly string[]): readonly string[] => {
+  const first = defaultLocaleOf(locales);
   const rest = new Set(locales);
-  rest.delete('en');
-  return ['en', ...[...rest].sort()];
+  rest.delete(first);
+  return [first, ...[...rest].sort()];
 };
 
 /** A locale tag is not always a valid JS binding (`zh-hant`) — `camel()` is the one identifier
  * derivation every generated file already uses for names, so the import agrees with the rest of
  * the app's own naming instead of inventing a second casing rule. */
-const localeImport = (locale: string): string =>
+export const localeImport = (locale: string): string =>
   `import ${camel(locale)} from '../catalogs/${locale}.json';`;
 
 /** The object-literal entry for one locale: shorthand when the binding IS the tag (`en`, `es`, …),
  * `'tag': binding` when `camel()` had to reshape it (`zh-hant` → `zhHant`) — `defineCatalogs` reads
  * the locale from the key, never the identifier, so the quoted form is what keeps it addressable. */
-const localeEntry = (locale: string): string => {
+export const localeEntry = (locale: string): string => {
   const binding = camel(locale);
   return binding === locale ? binding : `'${locale}': ${binding}`;
 };
@@ -61,6 +65,7 @@ const localeEntry = (locale: string): string => {
  */
 export function i18nIndex(locales: readonly string[]): string {
   const ordered = orderedLocales(locales);
+  const fallback = defaultLocaleOf(locales);
   const imports = ordered.map(localeImport).join('\n');
   const entries = ordered.map(localeEntry).join(', ');
   return `// The app's catalog, registered once and typed against English. Every surface resolves strings
@@ -75,13 +80,13 @@ import {
 } from '@ultimat3/i18n';
 ${imports}
 
-export const catalogs = defineCatalogs({ default: 'en', locales: { ${entries} } });
+export const catalogs = defineCatalogs({ default: '${fallback}', locales: { ${entries} } });
 
 /**
  * English is the source of truth for the key space — a second locale must match it exactly, or
  * \`x verify\` fails.
  */
-export type AppCatalog = typeof en;
+export type AppCatalog = typeof ${camel(fallback)};
 
 /** Every key this app's catalog defines — dot-paths, plus the stem of each plural family. */
 export type TranslationKey = KeyOf<AppCatalog>;