@ultimat3/cli 29.4.0 → 30.1.0

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

@@ -18,28 +18,32 @@ const domainIndex = (
 ): string => `// Pure types and constants. No I/O of any kind: no fs, no network, no database, no env reads.
 // \`Money\` is @ultimat3/schema's, re-exported and never restated: one declaration of
 // { minor, currency } is what makes an entity column, a form field and this module the same type.
-import { UltimateError } from '@ultimat3/core';
+import { defineError } from '@ultimat3/core';
 import type { MoneyValue as Money } from '@ultimat3/schema';
 
 export type { MoneyValue as Money } from '@ultimat3/schema';
 
+interface CurrencyPair {
+  readonly left: string;
+  readonly right: string;
+}
+
 /**
  * Never a bare Error: an agent reading the failure needs the code, the cause and the exact command
  * that resolves it. Adding across currencies is a bug in the caller's data, not a runtime hiccup,
- * so the fix names the conversion that has to happen first.
- *
- * No \`docs:\`: \`UltimateError\` resolves the link from the code's registered descriptor, so it has
- * one home. A per-code URL written here is a page that does not exist.
+ * so it answers 422 and the fix names the conversion that has to happen first. One declaration
+ * — \`defineError\` — holds the title, the status and the class; \`guards/error-declared.ts\` keeps
+ * it the only way. No \`docs:\`: the link resolves from the code's registered descriptor.
  */
-export class ${app.pascal}CurrencyMismatchError extends UltimateError {
-  constructor(input: { readonly left: string; readonly right: string }) {
-    super({
-      code: '${currencyCode(app)}',
-      cause: \`cannot add \${input.left} to \${input.right}: Money is only additive inside one currency\`,
-      fix: \`bun test packages/domain/src/index.test.ts   # add() is defined only inside one currency — convert \${input.right} to \${input.left} before calling it\`,
-    });
-  }
-}
+export const ${app.pascal}CurrencyMismatchError = defineError<CurrencyPair>({
+  code: '${currencyCode(app)}',
+  title: 'money added across two currencies',
+  status: 422,
+  cause: (pair) =>
+    \`cannot add \${pair.left} to \${pair.right}: Money is only additive inside one currency\`,
+  fix: (pair) =>
+    \`bun test packages/domain/src/index.test.ts   # add() is defined only inside one currency — convert \${pair.right} to \${pair.left} before calling it\`,
+});
 
 export const zero = (currency: string): Money => ({ minor: 0, currency });
 

package/src/templates/scaffold-entries.ts

@@ -91,8 +91,10 @@ const origin = Bun.env.SITE_ORIGIN;
  * from the CDN and from the container.
  *
  * A DYNAMIC route contributes exactly the URLs this build emitted for it, read back off the report:
- * the sitemap then cannot name a page the artifact does not contain. \`prerender()\` is asked again
- * only for what each page says of itself — its \`lastmod\`, the \`locales\` it is listed in.
+ * the sitemap then cannot name a page the artifact does not contain. What each page says of itself —
+ * its \`lastmod\`, the \`locales\` it is listed in — is \`report.entries\`: the build's own
+ * \`prerender()\` answers, so a route that lists its pages off the app's queries is never asked again
+ * once the build has stopped answering them.
  *
  * With \`seo.sitemap.sections\` the answer is an index and its parts: \`/sitemap.xml\` plus
  * \`/sitemaps/<name>-<n>.xml\`, every one written here.
@@ -110,9 +112,12 @@ async function writeSeoFiles(report: PrerenderReport): Promise<readonly string[]
     disallow: settings.disallow,
     robotsGroups: settings.robotsGroups,
     sitemap: settings.sitemap,
+    llms: settings.llms,
     root,
     pagesFor: (route) =>
       report.pages.filter((page) => page.route === route).map((page) => page.path),
+    entries: report.entries,
+    llmsPages: report.llmsPages,
   });
   return await writeSiteSeo(out, seo);
 }

package/src/templates/scaffold-exercise.ts

@@ -0,0 +1,37 @@
+// `apps/web/exercise.ts`: the app's overrides for `x exercise`, empty. Written by `x new` so the
+// file every `X_CONTRACT_EXERCISE_UNREACHED` fix names exists before the first line is pasted in.
+
+import type { GeneratedFile } from './naming';
+
+const exercise =
+  (): string => `// What \`x exercise\` cannot guess about this app: an input a primitive needs bound to a real
+// row, an actor its policy permits, or a primitive that must not run in the pass and why. Empty
+// runs every action, query and job as generated. \`x exercise --json\` prints the entry to paste
+// for each one it could not reach; each value is the \`exercise\` option \`.contract()\` takes.
+import { defineExercise } from '@ultimat3/testing';
+
+export const exercise = defineExercise({});
+`;
+
+// The import IS the check: `defineExercise` refuses a blank `off` as the module loads, so a reason
+// deleted from an entry fails `bun test` here, before the gate's `exercise` step runs at all.
+const exerciseTest =
+  (): string => `// The overrides load, and every primitive they turn off says why.
+import { expect, unitTest } from '@ultimat3/testing';
+import { exercise } from './exercise';
+
+unitTest('apps/web/exercise.ts loads, and every off entry names its reason', () => {
+  for (const [name, entry] of exercise.entries) {
+    if ('off' in entry) {
+      expect({ name, blank: entry.off.trim() === '' }).toEqual({ name, blank: false });
+    }
+  }
+  expect(exercise.entries).toBeInstanceOf(Map);
+});
+`;
+
+/** Written by `x new`, with or without the example slice: the gate's `exercise` step reads it. */
+export const exerciseFiles = (): readonly GeneratedFile[] => [
+  { path: 'apps/web/exercise.ts', contents: exercise() },
+  { path: 'apps/web/exercise.test.ts', contents: exerciseTest() },
+];

package/src/templates/scaffold-guards.ts

@@ -18,15 +18,23 @@
 // design system's rules a scaffolded app's gate held.
 //
 // And one is about DATA: a `repo.ts` reads through the typed handle. It ships because the generator
-// used to emit string SQL, and every app that started from it copied the shape.
+// used to emit string SQL, and every app that started from it copied the shape. One is about the
+// NETWORK: a server `fetch(` carries a signal, or is `outbound()` from `@ultimat3/core/outbound`. `error-declared`
+// is `bare-error`'s second half: an app code is declared once, with core's `defineError`. One is
+// about the TAB: an island polls with `visibleInterval()`, which a hidden tab and a lost session stop.
+// One is about the QUESTION: a destructive act asks through `ConfirmDialog`, never `confirm(`.
 
 import { animatedLayoutPropertyGuardFiles } from './guard-animated-layout-property';
 import { bareErrorGuardFiles } from './guard-bare-error';
+import { errorDeclaredGuardFiles } from './guard-error-declared';
 import { focusVisibleGuardFiles } from './guard-focus-visible';
 import { imageDimensionsGuardFiles } from './guard-image-dimensions';
 import { islandWithoutStatesGuardFiles } from './guard-island-without-states';
+import { nativeConfirmGuardFiles } from './guard-native-confirm';
 import { rawBreakpointGuardFiles } from './guard-raw-breakpoint';
 import { rawColourGuardFiles } from './guard-raw-colour';
+import { rawFetchGuardFiles } from './guard-raw-fetch';
+import { rawIntervalGuardFiles } from './guard-raw-interval';
 import { rawLengthGuardFiles } from './guard-raw-length';
 import { rawMotionGuardFiles } from './guard-raw-motion';
 import { rawShadowGuardFiles } from './guard-raw-shadow';
@@ -48,11 +56,15 @@ import type { GeneratedFile } from './naming';
 const SHIPPED: readonly (readonly [string, () => readonly GeneratedFile[]])[] = [
   ['animated-layout-property', animatedLayoutPropertyGuardFiles],
   ['bare-error', bareErrorGuardFiles],
+  ['error-declared', errorDeclaredGuardFiles],
   ['focus-visible', focusVisibleGuardFiles],
   ['image-dimensions', imageDimensionsGuardFiles],
   ['island-without-states', islandWithoutStatesGuardFiles],
+  ['native-confirm', nativeConfirmGuardFiles],
   ['raw-breakpoint', rawBreakpointGuardFiles],
   ['raw-colour', rawColourGuardFiles],
+  ['raw-fetch', rawFetchGuardFiles],
+  ['raw-interval', rawIntervalGuardFiles],
   ['raw-length', rawLengthGuardFiles],
   ['raw-motion', rawMotionGuardFiles],
   ['raw-shadow', rawShadowGuardFiles],

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

@@ -0,0 +1,234 @@
+// The monitoring objects every Ultimate chart ships: the scrape object and the alert rules. The
+// rules are one table, rendered as the chart's PrometheusRule template and as plain rule groups for
+// a loader outside Kubernetes. Only mechanism ships — a stalled queue, a dead letter, a lost lease,
+// a dropped frame, a 5xx share, a dead target; a latency target is the app's (axiom 8).
+import type { GeneratedFile, NameSet } from './naming';
+
+/** How an expression names a series and groups its result, per renderer. */
+export interface AlertScope {
+  /** `name{matchers}` — the scope's own matchers, then `extra`. */
+  readonly series: (name: string, extra?: string) => string;
+  /** The labels every rule groups by, so one release (or one job) fires one alert. */
+  readonly by: string;
+  /** The label naming a scrape target's role. */
+  readonly component: string;
+  /** The rule's threshold, as the renderer spells it: a value lookup or the default. */
+  readonly threshold: (fallback: number) => string;
+}
+
+export interface ChartAlert {
+  readonly alert: string;
+  readonly expr: (scope: AlertScope) => string;
+  /** The default `alerts.rules.<alert>.threshold`, for a rule whose comparison is a number. */
+  readonly threshold?: number;
+  readonly for: string;
+  readonly severity: 'warning' | 'critical';
+  readonly summary: string;
+  /** The heading in `docs/ops/06-runbooks.md` the rule's `runbook_url` lands on. */
+  readonly anchor: string;
+}
+
+const rule = (alert: Omit<ChartAlert, 'anchor'>): ChartAlert => ({
+  ...alert,
+  anchor: alert.alert.toLowerCase(),
+});
+
+export const CHART_ALERTS: readonly ChartAlert[] = [
+  rule({
+    alert: 'UltimateQueueStalled',
+    threshold: 300,
+    expr: (s) =>
+      `max by (${s.by}, queue) (${s.series('queue_oldest_ready_seconds')}) > ${s.threshold(300)}`,
+    for: '5m',
+    severity: 'warning',
+    summary: 'A queue has a due job nothing has claimed for longer than the threshold',
+  }),
+  rule({
+    alert: 'UltimateDeadLetters',
+    expr: (s) => `max by (${s.by}, queue) (${s.series('queue_dead_jobs')}) > 0`,
+    for: '5m',
+    severity: 'warning',
+    summary: 'A queue holds dead-lettered jobs',
+  }),
+  rule({
+    alert: 'UltimateLeaseLost',
+    expr: (s) => `sum by (${s.by}, queue) (rate(${s.series('job_leases_lost_total')}[5m])) > 0`,
+    for: '5m',
+    severity: 'warning',
+    summary: 'Job leases are lapsing while their jobs still run, so jobs run twice',
+  }),
+  rule({
+    alert: 'UltimateFramesDropped',
+    expr: (s) => `sum by (${s.by}) (rate(${s.series('channel_frames_dropped_total')}[5m])) > 0`,
+    for: '5m',
+    severity: 'warning',
+    summary: 'Sync nodes are dropping channel frames to socket backpressure',
+  }),
+  rule({
+    alert: 'UltimateServerErrors',
+    threshold: 0.05,
+    expr: (s) =>
+      `sum by (${s.by}) (rate(${s.series('http_requests_total', 'status="5xx"')}[5m])) / ` +
+      `sum by (${s.by}) (rate(${s.series('http_requests_total')}[5m])) > ${s.threshold(0.05)}`,
+    for: '10m',
+    severity: 'critical',
+    summary: 'The share of requests answered 5xx is above the threshold',
+  }),
+  rule({
+    alert: 'UltimateTargetDown',
+    expr: (s) => `count by (${s.by}, ${s.component}) (${s.series('up')} == 0) > 0`,
+    for: '5m',
+    severity: 'critical',
+    summary: 'A role has a scrape target that is down',
+  }),
+];
+
+/** Where `runbook_url` points unless `alerts.runbookBase` says otherwise. */
+export const RUNBOOK_BASE =
+  'https://github.com/developerz-ai/ultimate/blob/main/docs/ops/06-runbooks.md';
+
+const matchers = (own: string, extra?: string): string =>
+  [own, extra].filter((part) => part !== undefined && part !== '').join(',');
+
+/**
+ * The chart's scope: one release in one namespace, the two labels the ServiceMonitor's
+ * `targetLabels` and the operator put on every series. A threshold reads the rule's value.
+ */
+export const K8S_SCOPE: AlertScope = {
+  series: (name, extra) =>
+    `${name}{${matchers('namespace="{{ $.Release.Namespace }}",app_kubernetes_io_instance="{{ $.Release.Name }}"', extra)}}`,
+  by: 'namespace, app_kubernetes_io_instance',
+  component: 'app_kubernetes_io_component',
+  threshold: (fallback) => `{{ ternary $r.threshold ${fallback} (hasKey $r "threshold") }}`,
+};
+
+const plainScope = (own: string): AlertScope => ({
+  series: (name, extra) => {
+    const inner = matchers(own, extra);
+    return inner === '' ? name : `${name}{${inner}}`;
+  },
+  by: 'job',
+  component: 'instance',
+  threshold: (fallback) => String(fallback),
+});
+
+/** The rules as one plain Prometheus rule group, defaults in place, scoped by `own` matchers. */
+export function alertRuleGroups(own = ''): string {
+  const scope = plainScope(own);
+  const rules = CHART_ALERTS.map(
+    (a) => `      - alert: ${a.alert}
+        expr: >-
+          ${a.expr(scope)}
+        for: ${a.for}
+        labels:
+          severity: ${a.severity}
+        annotations:
+          summary: ${JSON.stringify(a.summary)}
+          runbook_url: ${JSON.stringify(`${RUNBOOK_BASE}#${a.anchor}`)}
+`,
+  ).join('');
+  return `groups:\n  - name: ultimate\n    rules:\n${rules}`;
+}
+
+/** One rule of the chart template: every field a value under `alerts.rules.<alert>` may replace. */
+const chartRule = (
+  a: ChartAlert,
+): string => `        {{- $r := index $rules "${a.alert}" | default dict }}
+        {{- if ne (toString $r.enabled) "false" }}
+        - alert: ${a.alert}
+          expr: >-
+            ${a.expr(K8S_SCOPE)}
+          for: {{ $r.for | default "${a.for}" }}
+          labels:
+            severity: {{ $r.severity | default "${a.severity}" }}
+          annotations:
+            summary: ${JSON.stringify(a.summary)}
+            runbook_url: {{ printf "%s#${a.anchor}" $base | quote }}
+        {{- end }}
+`;
+
+/**
+ * The `enabled` switch both monitoring objects share: `auto` (and a values file with no such block)
+ * renders when the cluster serves the operator's kind, `true` forces it, `false` declines it.
+ */
+const operatorGate = (
+  key: string,
+  kind: string,
+): string => `{{- $cfg := .Values.${key} | default dict }}
+{{- $mode := toString (ternary $cfg.enabled "auto" (hasKey $cfg "enabled")) }}
+{{- if not (has $mode (list "auto" "true" "false")) }}
+{{- fail (printf "${key}.enabled is %q — set it to auto (render when the cluster serves monitoring.coreos.com/v1/${kind}), true or false" $mode) }}
+{{- end }}
+{{- if or (eq $mode "true") (and (eq $mode "auto") (.Capabilities.APIVersions.Has "monitoring.coreos.com/v1/${kind}")) }}`;
+
+const alertRulesTemplate = (chart: string): string => `{{/*
+The alert rules for this release's own series, written from @ultimat3/cli's rule table. Each rule
+reads alerts.rules.<alert> for threshold, for, severity and enabled; its runbook_url is
+alerts.runbookBase plus the rule's anchor. Rendered by capability, like servicemonitor.yaml.
+*/}}
+${operatorGate('alerts', 'PrometheusRule')}
+{{- $rules := $cfg.rules | default dict }}
+{{- $base := $cfg.runbookBase | default "${RUNBOOK_BASE}" }}
+apiVersion: monitoring.coreos.com/v1
+kind: PrometheusRule
+metadata:
+  name: {{ include "${chart}.fullname" . }}
+  labels:
+    {{- include "${chart}.labels" . | nindent 4 }}
+    {{- with $cfg.labels }}
+    {{- toYaml . | nindent 4 }}
+    {{- end }}
+spec:
+  groups:
+    - name: {{ include "${chart}.fullname" . }}.ultimate
+      rules:
+${CHART_ALERTS.map(chartRule).join('')}{{- end }}
+`;
+
+const serviceMonitorTemplate = (chart: string): string => `{{/*
+Prometheus-operator discovery for the scrape listener every serving role opens, rendered by
+capability: serviceMonitor.enabled auto (the default, and a values file with no such block) renders
+it when the cluster serves the kind, so a cluster without the operator still installs. ONE object
+for the release: every role's Service publishes the same \`metrics\` port name. targetLabels carry
+the role and the release onto every series, which is what alert-rules.yaml and an HPA key on.
+*/}}
+${operatorGate('serviceMonitor', 'ServiceMonitor')}
+apiVersion: monitoring.coreos.com/v1
+kind: ServiceMonitor
+metadata:
+  name: {{ include "${chart}.fullname" . }}
+  labels:
+    {{- include "${chart}.labels" . | nindent 4 }}
+    {{- with $cfg.labels }}
+    {{- toYaml . | nindent 4 }}
+    {{- end }}
+spec:
+  selector:
+    matchLabels:
+      app.kubernetes.io/name: {{ include "${chart}.name" . }}
+      app.kubernetes.io/instance: {{ .Release.Name }}
+  targetLabels:
+    - app.kubernetes.io/component
+    - app.kubernetes.io/instance
+  endpoints:
+    # The Service port NAME, never the integer: moving metricsPort moves nothing here.
+    - port: metrics
+      path: /metrics
+      interval: {{ $cfg.interval | default "15s" }}
+      scrapeTimeout: {{ $cfg.scrapeTimeout | default "10s" }}
+{{- end }}
+`;
+
+/**
+ * The chart's two monitoring templates. The framework chart's copies (\`docker/helm/templates/\`)
+ * are these bytes for the chart named \`ultimate\`, held by \`scaffold-helm-parity.test.ts\`.
+ */
+export function helmMonitoringFiles(app: NameSet): readonly GeneratedFile[] {
+  return [
+    {
+      path: 'docker/helm/templates/servicemonitor.yaml',
+      contents: serviceMonitorTemplate(app.kebab),
+    },
+    { path: 'docker/helm/templates/alert-rules.yaml', contents: alertRulesTemplate(app.kebab) },
+  ];
+}

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

@@ -3,6 +3,7 @@
 // Split from scaffold-helm.ts, which holds the chart's INPUTS (Chart.yaml, values.yaml).
 
 import type { GeneratedFile, NameSet } from './naming';
+import { helmMonitoringFiles } from './scaffold-helm-alerts';
 import { helmFenceFiles } from './scaffold-helm-fences';
 
 const helpers = (
@@ -169,7 +170,7 @@ nobody bound. Derived here rather than stated twice in values.yaml, where the tw
     periodSeconds: 15
     failureThreshold: 4
   {{- /*
-  The worker's retire, opt-in: roles.worker.retireSeconds > 0. The preStop sends PID 1 SIGUSR2 —
+  The worker's retire, on by default: roles.worker.retireSeconds > 0. The preStop sends PID 1 SIGUSR2 —
   the framework's retire: stop claiming, finish every held job however long it takes, abort
   nothing, then drain and exit 0 — and waits until PID 1 is gone, so the SIGTERM that follows finds
   nothing left to cut off. It re-sends the signal every 5 s while it waits: PID 1 has no default
@@ -185,7 +186,7 @@ nobody bound. Derived here rather than stated twice in values.yaml, where the tw
         command:
           - bun
           - -e
-          - "process.kill(1, 'SIGUSR2'); for (let n = 1; ; n++) { try { process.kill(1, n % 5 === 0 ? 'SIGUSR2' : 0); } catch { break; } await Bun.sleep(1000); }"
+          - "process.kill(1, 'SIGUSR2'); const end = Date.now() + {{ int $cfg.retireSeconds }} * 1000; for (let n = 1; Date.now() < end; n++) { try { process.kill(1, n % 5 === 0 ? 'SIGUSR2' : 0); } catch { break; } await Bun.sleep(1000); }"
   {{- end }}
   {{- end }}
   resources: {{- toYaml $cfg.resources | nindent 4 }}
@@ -196,7 +197,7 @@ nobody bound. Derived here rather than stated twice in values.yaml, where the tw
 
 {{/*
 A role's terminationGracePeriodSeconds, in the order the kubelet's budget is spent: the preStop
-sleep (web and sync, 1.30+), the worker's opt-in retire (roles.worker.retireSeconds), the
+sleep (web and sync, 1.30+), the worker's retire (roles.worker.retireSeconds), the
 readiness grace (web and sync — every other role drains with none), the drain budget (app.config.ts drain.deadlineMs, every role;
 the worker's is drain.workerDeadlineSeconds instead when > 0, from drain.workerDeadlineMs) and the teardown margin.
 Defaults: 45s web/sync (40s below 1.30), 35s the rest. x deploy --method helm sets
@@ -408,7 +409,7 @@ holds at minReplicas, which is why these are opt-in rather than a default nobody
 
 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
+count: queue_demand is that shape, because every serving worker publishes the same number, 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 }}
@@ -430,7 +431,7 @@ spec:
   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) }}
+  {{- 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_demand)" $role $type) }}
   {{- end }}
   metrics:
     {{- if eq $type "External" }}
@@ -469,5 +470,6 @@ export function helmTemplateFiles(app: NameSet): readonly GeneratedFile[] {
     { path: 'docker/helm/templates/ingress.yaml', contents: ingress(app) },
     { path: 'docker/helm/templates/hpa.yaml', contents: hpa(app) },
     ...helmFenceFiles(app),
+    ...helmMonitoringFiles(app),
   ];
 }

package/src/templates/scaffold-helm.ts

@@ -6,6 +6,7 @@
 // scaffold-helm-templates.ts.
 
 import type { GeneratedFile, NameSet } from './naming';
+import { RUNBOOK_BASE } from './scaffold-helm-alerts';
 import { helmTemplateFiles } from './scaffold-helm-templates';
 
 /**
@@ -17,6 +18,37 @@ import { helmTemplateFiles } from './scaffold-helm-templates';
  */
 export const RUNTIME_UID = 1000;
 
+/**
+ * The two monitoring blocks of `values.yaml`, each a top-level key with its comment. Exported
+ * because `x g chart-alerts` appends whichever one an existing app's `values.yaml` lacks: one
+ * copy of the bytes, here, for the scaffold and the backfill.
+ */
+export const SERVICE_MONITOR_VALUES = `# Prometheus-operator discovery for that port (templates/servicemonitor.yaml) and the alert rules on
+# the series it scrapes (templates/alert-rules.yaml). \`enabled\` on each:
+#   auto   render when the cluster serves the operator's kind, so a cluster without it still
+#          installs. \`helm template\` answers from \`--api-versions\`: an offline render (GitOps) gets
+#          neither unless it passes --api-versions monitoring.coreos.com/v1/ServiceMonitor and
+#          --api-versions monitoring.coreos.com/v1/PrometheusRule
+#   true   always render; \`helm install\` fails where the CRD is missing
+#   false  never render
+serviceMonitor:
+  enabled: auto
+  interval: 15s
+  scrapeTimeout: 10s
+  labels: {}         # what your operator's serviceMonitorSelector matches, if it uses one
+
+`;
+
+export const ALERTS_VALUES = `# Each rule's runbook_url is runbookBase#<alert, lower-cased>. Per rule, under rules.<alert>:
+# threshold, for, severity, enabled — e.g. rules: { UltimateQueueStalled: { threshold: 600 } }.
+alerts:
+  enabled: auto
+  runbookBase: ${RUNBOOK_BASE}
+  labels: {}         # what your operator's ruleSelector matches, if it uses one
+  rules: {}
+
+`;
+
 /**
  * `appVersion` is the default image tag (`image.tag: ""` below), so it must name a tag that can
  * exist. `x deploy --image <ref>` overrides both keys, which is the path that actually ships.
@@ -80,7 +112,7 @@ networkPolicy:
 # METRICS_PORT in the container; move one and the other follows.
 metricsPort: 9090
 
-# The image's \`bun\` user, the same uid as the Dockerfile's USER: move one and the other follows.
+${SERVICE_MONITOR_VALUES}${ALERTS_VALUES}# The image's \`bun\` user, the same uid as the Dockerfile's USER: move one and the other follows.
 podSecurityContext:
   runAsNonRoot: true
   runAsUser: ${RUNTIME_UID}
@@ -167,11 +199,12 @@ roles:
   worker:
     enabled: true
     replicas: 2
-    # The retire, OFF at 0. Set to the longest a held job may run, in seconds, and the worker's
-    # preStop sends its PID 1 SIGUSR2: stop claiming, finish every held job, abort nothing, exit 0
-    # — for a job whose side effect must happen at most once and may outlast its drain budget.
-    # Added to this role's terminationGracePeriodSeconds, which the kubelet counts the preStop against.
-    retireSeconds: 0
+    # The retire, ON: a deploy or a scale-down never cuts a job it could wait out. app.config.ts
+    # drain.workerRetireMs / 1000, set by x deploy, and 0 turns it off. The worker's preStop sends
+    # its PID 1 SIGUSR2: stop claiming, finish every held job, abort nothing, exit 0. An idle worker
+    # exits at once, and a Terminating pod does not hold a rollout back. Added to this role's
+    # terminationGracePeriodSeconds, which the kubelet counts the preStop against.
+    retireSeconds: 3600
     resources:
       requests: { cpu: 200m, memory: 256Mi }
       limits: { memory: 1Gi }
@@ -179,11 +212,12 @@ roles:
       enabled: false
       minReplicas: 1
       maxReplicas: 50
-      # External: every worker publishes the SAME global backlog, so averaged as a Pods metric it
+      # External: every serving worker publishes the SAME number, 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.
+      # max by (queue) (queue_demand), never sum, which would multiply it by the pod count again.
       type: External
-      metric: queue_depth       # jobs waiting, exported by the worker role
+      metric: queue_demand      # jobs held by serving workers plus jobs due, per queue
+      # Set it to one pod's jobs.maxInFlight; x deploy --method helm sets it when app.config.ts declares it.
       targetAverageValue: "100"
 
   scheduler:
@@ -213,9 +247,9 @@ ingress:
 `;
 
 /**
- * The chart for a new app: six kinds of object, all of them core Kubernetes. A ServiceMonitor and
- * a PodDisruptionBudget are deliberately absent — the first needs a CRD `helm install` fails on
- * where no Prometheus operator is installed, and both are cluster policy rather than app topology.
+ * The chart for a new app: core Kubernetes objects, plus a ServiceMonitor and a PrometheusRule that
+ * render only where the cluster serves those kinds. A PodDisruptionBudget is deliberately absent:
+ * it is cluster policy rather than app topology.
  */
 export function helmFiles(app: NameSet): readonly GeneratedFile[] {
   return [

package/src/templates/scaffold-i18n.ts

@@ -143,8 +143,12 @@ const i18nCatalog = (app: NameSet): string =>
     'app.dashboard.statToday': 'Created today',
     'app.dashboard.hintToday': 'so far, UTC',
     'app.dashboard.chartTitle': 'Posts per day',
-    'app.dashboard.chartRange': 'Last 14 days, UTC',
-    'app.dashboard.chartLabel': 'Posts created per day over the last 14 days',
+    'app.dashboard.chartRange': 'Per UTC day, over the window you pick',
+    'app.dashboard.rangeLabel': 'Chart window',
+    'app.dashboard.rangeWeek': 'Last 7 days',
+    'app.dashboard.rangeFortnight': 'Last 14 days',
+    'app.dashboard.rangeMonth': 'Last 30 days',
+    'app.dashboard.chartLabel': 'Posts created per day over the chosen window',
     'app.dashboard.tableTitle': 'Latest posts',
     'app.dashboard.tableCaption': 'The ten newest posts',
     'app.dashboard.columnTitle': 'Title',