@opengroundplan/core 0.1.1

package/templates/layers/docker/files/.dockerignore

@@ -0,0 +1,80 @@
+# Everything the image build does not need. A small context builds faster and keeps
+# local secrets and host-built artifacts out of the layer cache.
+
+.git
+.gitignore
+.gitattributes
+.github
+.gitlab-ci.yml
+.vscode
+.idea
+
+# Secrets. The image reads configuration from the environment, never from a baked file.
+.env
+.env.*
+!.env.example
+!.env.docker.example
+*.pem
+*.key
+*.pfx
+secrets/
+
+# Container and orchestration files. The Dockerfile reaches the daemon over -f, not the context.
+Dockerfile*
+compose.yaml
+compose.*.yaml
+docker-compose*.yml
+.dockerignore
+k8s/
+charts/
+
+# Docs and specs. README stays: Python and Node manifests reference it at build time.
+docs/
+specs/
+.agent/
+*.md
+!README.md
+
+# Node / TypeScript
+node_modules/
+dist/
+build/
+.next/
+out/
+coverage/
+.turbo/
+.pnpm-store/
+.yarn/cache/
+.eslintcache
+*.tsbuildinfo
+
+# Python
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+htmlcov/
+
+# Go
+vendor/
+
+# .NET
+bin/
+obj/
+*.user
+TestResults/
+
+# Rust / Java
+target/
+.gradle/
+
+# Local state and OS noise
+data/
+*.db
+*.sqlite3
+*.log
+.DS_Store
+Thumbs.db

package/templates/layers/docker/files/.env.docker.example

@@ -0,0 +1,17 @@
+# Compose reads .env from the repo root. Copy this file to .env to override any of it.
+# These keys configure the container, not the application — application settings live in the
+# base's own .env.example and are read by the app's config module inside the image.
+
+# Image tag and the version baked in at build time.
+APP_VERSION=dev
+
+# Host port published in front of the container's {{ dockerPort }}.
+APP_HOST_PORT={{ dockerPort }}
+
+# Resource ceiling for the local run.
+APP_CPU_LIMIT=1.0
+APP_MEMORY_LIMIT=512M
+
+# Log rotation for the json-file driver.
+APP_LOG_MAX_SIZE=10m
+APP_LOG_MAX_FILES=3

package/templates/layers/docker/files/Dockerfile.dotnet

@@ -0,0 +1,38 @@
+# syntax=docker/dockerfile:1
+# ASP.NET Core service. The runtime image is Ubuntu Chiseled: distroless-class, no shell and
+# no package manager, and it already defines the non-root `app` account as $APP_UID.
+
+ARG SDK_IMAGE=mcr.microsoft.com/dotnet/sdk:10.0
+ARG RUNTIME_IMAGE=mcr.microsoft.com/dotnet/aspnet:10.0-noble-chiseled
+# dotnet-aspire names its projects with pascal casing; override when the path differs.
+ARG PROJECT_PATH=src/{{ solutionName | dot }}.Api/{{ solutionName | dot }}.Api.csproj
+
+FROM ${SDK_IMAGE} AS build
+ARG PROJECT_PATH
+WORKDIR /src
+
+# Whole context first: a project-file-only copy cannot restore a solution whose projects
+# reference each other, which is exactly the Aspire layout.
+COPY . .
+RUN dotnet restore "${PROJECT_PATH}"
+# UseAppHost=false: `dotnet <dll>` is the entrypoint, so the native launcher is dead weight.
+RUN dotnet publish "${PROJECT_PATH}" -c Release -o /app/publish --no-restore -p:UseAppHost=false
+
+FROM ${RUNTIME_IMAGE} AS runtime
+WORKDIR /app
+
+ENV ASPNETCORE_ENVIRONMENT=Production \
+    ASPNETCORE_HTTP_PORTS={{ dockerPort }} \
+    DOTNET_RUNNING_IN_CONTAINER=true
+
+# No chown: published output is read-only to the runtime, and world-readable already.
+COPY --from=build /app/publish .
+
+EXPOSE {{ dockerPort }}
+USER $APP_UID
+
+# No HEALTHCHECK: chiseled images ship no shell or curl. Point the orchestrator's own probe
+# at {{ dockerHealthPath }} instead.
+# Exec form cannot expand a build arg, so the assembly name is written literally — change it
+# here if the API project is renamed.
+ENTRYPOINT ["dotnet", "{{ solutionName | dot }}.Api.dll"]

package/templates/layers/docker/files/Dockerfile.go

@@ -0,0 +1,40 @@
+# syntax=docker/dockerfile:1
+# Go service. CGO is off and the binary is statically linked, so the runtime image can be
+# distroless/static: no libc, no shell, no package manager — a kernel-facing binary and certs.
+
+ARG GO_VERSION=1.26
+ARG BUILDER_IMAGE=golang:${GO_VERSION}
+ARG RUNTIME_IMAGE=gcr.io/distroless/static-debian13:nonroot
+# uid of the `nonroot` account baked into the distroless image.
+ARG RUNTIME_UID=65532
+
+FROM ${BUILDER_IMAGE} AS build
+WORKDIR /src
+
+# go.sum only exists after `go mod tidy`; the glob keeps a fresh checkout building.
+COPY go.mod go.sum* ./
+RUN --mount=type=cache,target=/go/pkg/mod go mod download
+
+COPY . .
+# Set by buildx; empty under a plain `docker build`, which then targets the host platform.
+ARG TARGETOS
+ARG TARGETARCH
+RUN --mount=type=cache,target=/go/pkg/mod --mount=type=cache,target=/root/.cache/go-build \
+    CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} \
+    go build -trimpath -ldflags="-s -w" -o /out/app ./cmd/{{ solutionName | kebab }}
+
+FROM ${RUNTIME_IMAGE} AS runtime
+ARG RUNTIME_UID
+
+# Host and port are read by internal/config; this only supplies the values.
+ENV {{ solutionName | upperSnake }}_HTTP_HOST=0.0.0.0 \
+    {{ solutionName | upperSnake }}_HTTP_PORT={{ dockerPort }}
+
+COPY --from=build --chown=${RUNTIME_UID}:${RUNTIME_UID} /out/app /app
+
+EXPOSE {{ dockerPort }}
+USER ${RUNTIME_UID}:${RUNTIME_UID}
+
+# No HEALTHCHECK: the image has no shell or HTTP client to run one. Point the orchestrator's
+# own probe at {{ dockerHealthPath }} instead — Kubernetes and ECS probe over HTTP directly.
+ENTRYPOINT ["/app"]

package/templates/layers/docker/files/Dockerfile.nextjs

@@ -0,0 +1,42 @@
+# syntax=docker/dockerfile:1
+# Next.js standalone output. `next build` traces the modules the server actually imports, so
+# the runtime image carries neither node_modules nor the Next CLI — just the traced bundle.
+
+ARG NODE_VERSION=24
+ARG BUILDER_IMAGE=node:${NODE_VERSION}-slim
+ARG RUNTIME_IMAGE=gcr.io/distroless/nodejs${NODE_VERSION}-debian13:nonroot
+# uid of the `nonroot` account baked into the distroless image.
+ARG RUNTIME_UID=65532
+
+FROM ${BUILDER_IMAGE} AS build
+WORKDIR /app
+
+COPY package.json package-lock.json* pnpm-lock.yaml* yarn.lock* bun.lockb* ./
+RUN {{ dockerNodeInstallCommand }}
+
+COPY . .
+# public/ is optional in a fresh app but the runtime COPY below is not.
+RUN mkdir -p public
+ENV NEXT_TELEMETRY_DISABLED=1
+RUN {{ dockerNodeBuildCommand }}
+
+FROM ${RUNTIME_IMAGE} AS runtime
+ARG RUNTIME_UID
+WORKDIR /app
+
+ENV NODE_ENV=production \
+    HOSTNAME=0.0.0.0 \
+    PORT={{ dockerPort }} \
+    NEXT_TELEMETRY_DISABLED=1
+
+COPY --from=build --chown=${RUNTIME_UID}:${RUNTIME_UID} /app/.next/standalone ./
+COPY --from=build --chown=${RUNTIME_UID}:${RUNTIME_UID} /app/.next/static ./.next/static
+COPY --from=build --chown=${RUNTIME_UID}:${RUNTIME_UID} /app/public ./public
+
+EXPOSE {{ dockerPort }}
+USER ${RUNTIME_UID}:${RUNTIME_UID}
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=15s --retries=3 \
+  CMD ["/nodejs/bin/node", "-e", "fetch('http://127.0.0.1:{{ dockerPort }}{{ dockerHealthPath }}').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+
+CMD ["server.js"]

package/templates/layers/docker/files/Dockerfile.nodejs

@@ -0,0 +1,46 @@
+# syntax=docker/dockerfile:1
+# Compiled Node service. The runtime image is distroless: no shell, no package manager,
+# no npm — only a node binary and the production dependency tree.
+
+# Every tunable of this build lives in this one block; override with --build-arg.
+ARG NODE_VERSION=24
+ARG BUILDER_IMAGE=node:${NODE_VERSION}-slim
+ARG RUNTIME_IMAGE=gcr.io/distroless/nodejs${NODE_VERSION}-debian13:nonroot
+# uid of the `nonroot` account baked into the distroless image.
+ARG RUNTIME_UID=65532
+
+FROM ${BUILDER_IMAGE} AS build
+WORKDIR /app
+
+# Manifests first: dependencies only reinstall when a lockfile actually changes.
+# The lockfile globs are optional matches, so any package manager works.
+COPY package.json package-lock.json* pnpm-lock.yaml* yarn.lock* bun.lockb* ./
+RUN {{ dockerNodeInstallCommand }}
+
+COPY . .
+RUN {{ dockerNodeBuildCommand }}
+# devDependencies would otherwise travel into the runtime image with node_modules.
+RUN {{ dockerNodePruneCommand }}
+
+FROM ${RUNTIME_IMAGE} AS runtime
+ARG RUNTIME_UID
+WORKDIR /app
+
+# Host and port are read by the app's own config module — this only supplies the values.
+ENV NODE_ENV=production \
+    HOST=0.0.0.0 \
+    PORT={{ dockerPort }}
+
+COPY --from=build --chown=${RUNTIME_UID}:${RUNTIME_UID} /app/node_modules ./node_modules
+COPY --from=build --chown=${RUNTIME_UID}:${RUNTIME_UID} /app/dist ./dist
+COPY --from=build --chown=${RUNTIME_UID}:${RUNTIME_UID} /app/package.json ./package.json
+
+EXPOSE {{ dockerPort }}
+USER ${RUNTIME_UID}:${RUNTIME_UID}
+
+# Exec form with an absolute path: the image has no shell to expand anything.
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
+  CMD ["/nodejs/bin/node", "-e", "fetch('http://127.0.0.1:{{ dockerPort }}{{ dockerHealthPath }}').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+
+# The distroless entrypoint is already `node`, so CMD is just the script.
+CMD ["{{ dockerNodeEntry }}"]

package/templates/layers/docker/files/Dockerfile.python

@@ -0,0 +1,52 @@
+# syntax=docker/dockerfile:1
+# Python ASGI service. uv resolves and installs into a virtualenv in the builder stage; the
+# runtime stage is a plain slim image carrying that venv and the source, with no build tools.
+# (Distroless has no Python variant that tracks releases, so slim + an explicit non-root user
+# is the safe equivalent here.)
+
+ARG PYTHON_VERSION=3.14
+ARG BASE_IMAGE=python:${PYTHON_VERSION}-slim
+ARG UV_IMAGE=ghcr.io/astral-sh/uv:0.11.29
+# Static uid so volume ownership stays stable across rebuilds.
+ARG APP_UID=10001
+
+# Named stage rather than `COPY --from=${UV_IMAGE}`: FROM expands build args reliably.
+FROM ${UV_IMAGE} AS uv
+
+FROM ${BASE_IMAGE} AS build
+COPY --from=uv /uv /uvx /bin/
+
+ENV UV_COMPILE_BYTECODE=1 \
+    UV_LINK_MODE=copy \
+    UV_PROJECT_ENVIRONMENT=/app/.venv
+WORKDIR /app
+
+# README is copied because the project manifest declares it — the build backend reads it.
+COPY pyproject.toml uv.lock* README.md ./
+COPY src ./src
+RUN --mount=type=cache,target=/root/.cache/uv {{ dockerPythonInstallCommand }}
+
+FROM ${BASE_IMAGE} AS runtime
+ARG APP_UID
+# Matching uid and gid so the numeric USER below resolves to a real account either way.
+RUN groupadd --system --gid ${APP_UID} app \
+ && useradd --system --uid ${APP_UID} --gid ${APP_UID} --no-create-home app
+WORKDIR /app
+
+COPY --from=build --chown=${APP_UID}:${APP_UID} /app /app
+
+# Host and port are read by the service's own settings module; this only supplies the values.
+ENV PATH=/app/.venv/bin:$PATH \
+    PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    {{ solutionName | upperSnake }}_HOST=0.0.0.0 \
+    {{ solutionName | upperSnake }}_PORT={{ dockerPort }}
+
+EXPOSE {{ dockerPort }}
+USER ${APP_UID}:${APP_UID}
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
+  CMD ["python", "-c", "import sys,urllib.request; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:{{ dockerPort }}{{ dockerHealthPath }}', timeout=3).status == 200 else 1)"]
+
+# The console script the project manifest declares; it reads settings and starts uvicorn.
+CMD ["{{ solutionName | kebab }}"]

package/templates/layers/docker/files/Dockerfile.spa

@@ -0,0 +1,30 @@
+# syntax=docker/dockerfile:1
+# Static SPA. The runtime image is nginx-unprivileged: it already runs as a non-root user
+# and writes only to /tmp, so no chown or user creation is needed here.
+
+ARG NODE_VERSION=24
+ARG BUILDER_IMAGE=node:${NODE_VERSION}-slim
+ARG RUNTIME_IMAGE=nginxinc/nginx-unprivileged:1.30-alpine
+
+FROM ${BUILDER_IMAGE} AS build
+WORKDIR /app
+
+COPY package.json package-lock.json* pnpm-lock.yaml* yarn.lock* bun.lockb* ./
+RUN {{ dockerNodeInstallCommand }}
+
+COPY . .
+# Vite inlines VITE_* at build time, so anything the browser needs must be passed here.
+ARG VITE_API_BASE_URL
+RUN {{ dockerNodeBuildCommand }}
+
+FROM ${RUNTIME_IMAGE} AS runtime
+
+# Routing, caching, and security headers live in this file — nothing is inlined above.
+COPY docker/nginx.conf /etc/nginx/conf.d/default.conf
+COPY --from=build /app/dist /usr/share/nginx/html
+
+# Unprivileged nginx cannot bind below 1024; keep this above that.
+EXPOSE {{ dockerPort }}
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD ["wget", "--quiet", "--spider", "http://127.0.0.1:{{ dockerPort }}/healthz"]

package/templates/layers/docker/files/compose.yaml

@@ -0,0 +1,35 @@
+# Local harness for the production image — the same artifact that ships, run on your machine.
+# It is not a dev-server replacement: use the base's own dev command for hot reload.
+name: {{ solutionName | kebab }}
+
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile.{{ dockerTarget }}
+      args:
+        APP_VERSION: ${APP_VERSION:-dev}
+    image: {{ solutionName | kebab }}:${APP_VERSION:-dev}
+    # The image already defines a non-root USER; nothing here may escalate past it.
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    ports:
+      - "${APP_HOST_PORT:-{{ dockerPort }}}:{{ dockerPort }}"
+    env_file:
+      # Optional so a fresh clone runs before anyone has written a .env.
+      - path: .env
+        required: false
+    restart: unless-stopped
+    # Bounded so one runaway container cannot take the host down.
+    deploy:
+      resources:
+        limits:
+          cpus: "${APP_CPU_LIMIT:-1.0}"
+          memory: ${APP_MEMORY_LIMIT:-512M}
+    logging:
+      driver: json-file
+      options:
+        max-size: ${APP_LOG_MAX_SIZE:-10m}
+        max-file: "${APP_LOG_MAX_FILES:-3}"

package/templates/layers/docker/files/docker/nginx.conf

@@ -0,0 +1,44 @@
+# Serving policy for the built SPA. Every tunable this image has is in this file.
+
+server {
+    listen {{ dockerPort }};
+    server_name _;
+    root /usr/share/nginx/html;
+    index index.html;
+
+    # The upstream proxy or CDN decides what to advertise; the origin should not leak a version.
+    server_tokens off;
+
+    add_header X-Content-Type-Options nosniff always;
+    add_header X-Frame-Options DENY always;
+    add_header Referrer-Policy strict-origin-when-cross-origin always;
+
+    gzip on;
+    gzip_vary on;
+    gzip_min_length 1024;
+    gzip_types text/plain text/css application/javascript application/json image/svg+xml;
+
+    # Probe target for the image HEALTHCHECK — cheap and never touches the filesystem.
+    location = /healthz {
+        access_log off;
+        add_header Content-Type text/plain;
+        return 200 "ok\n";
+    }
+
+    # Vite fingerprints these filenames, so a stale copy can never shadow a new build.
+    location /assets/ {
+        expires 1y;
+        add_header Cache-Control "public, max-age=31536000, immutable";
+        try_files $uri =404;
+    }
+
+    # index.html is the routing table; caching it strands users on an old bundle.
+    location = /index.html {
+        add_header Cache-Control "no-cache";
+    }
+
+    # Client-side routing: unknown paths are app routes, not 404s.
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+}

package/templates/layers/docker/files/docs/docker.md

@@ -0,0 +1,115 @@
+# Containers
+
+{{ solutionName | title }} builds to a single production image. The build is multi-stage: the
+compiler, package manager, and dev dependencies live in a builder stage and never reach the
+image that ships. The runtime stage is distroless (or slim, where no distroless variant tracks
+the language release) and runs as a non-root user.
+
+## Files
+
+| File | Role |
+|---|---|
+| `Dockerfile.{{ dockerTarget }}` | The image build. Every tunable is an `ARG` in the first block. |
+| `.dockerignore` | What never enters the build context — secrets, caches, host-built artifacts. |
+| `compose.yaml` | Runs the built image locally with resource and privilege limits. |
+| `.env.docker.example` | Container-level knobs for Compose. Copy to `.env`. |
+
+The Dockerfile keeps a target suffix because one repository can grow more than one image, and
+because the generator writes exactly the one that matches this stack. If your deploy platform
+auto-detects a bare `Dockerfile`, rename it:
+
+```bash
+git mv Dockerfile.{{ dockerTarget }} Dockerfile
+```
+
+Then drop the `dockerfile:` line from `compose.yaml`.
+
+## Build and run
+
+```bash
+docker build -f Dockerfile.{{ dockerTarget }} -t {{ solutionName | kebab }}:dev .
+docker run --rm -p {{ dockerPort }}:{{ dockerPort }} {{ solutionName | kebab }}:dev
+```
+
+Or through Compose, which also applies the privilege and resource limits:
+
+```bash
+docker compose up --build
+```
+
+The service answers on <http://localhost:{{ dockerPort }}> and reports liveness at
+`{{ dockerHealthPath }}`.
+
+## Configuration
+
+Nothing is configured by editing the Dockerfile. Two layers of override exist:
+
+**Build time** — every image tag, language version, and build path is an `ARG` declared once at
+the top of the Dockerfile:
+
+```bash
+docker build -f Dockerfile.{{ dockerTarget }} --build-arg RUNTIME_IMAGE=my-registry/base:pinned .
+```
+
+Pin the digest rather than the tag for reproducible builds:
+`--build-arg RUNTIME_IMAGE=gcr.io/distroless/static-debian13@sha256:...`
+
+**Run time** — the image sets host and port as environment variables that the application's own
+config module reads. Everything else the app needs is supplied the same way, by the platform:
+
+```bash
+docker run --rm -p {{ dockerPort }}:{{ dockerPort }} --env-file .env {{ solutionName | kebab }}:dev
+```
+
+Never bake a secret into a layer. `docker history` shows every `ARG` and `ENV` value to anyone
+who can pull the image.
+
+## Non-root
+
+The runtime stage declares an explicit `USER`, and copied files are chowned to that uid in the
+same `COPY` that brings them in — a later `RUN chown` would duplicate the whole tree into a new
+layer. The container therefore cannot write anywhere outside a mounted volume, which is the
+intended posture: state belongs in a database or an object store, not in the image.
+
+If the process needs scratch space, mount it rather than relaxing the user:
+
+```yaml
+tmpfs:
+  - /tmp
+```
+
+## Health checks
+
+Distroless and chiseled images contain no shell and no HTTP client, so an in-image
+`HEALTHCHECK` is only defined where the runtime can execute one itself (the Node targets probe
+with `node -e`, the Python target with `urllib`, the SPA target with `wget`). For the Go and
+.NET targets there is nothing in the image to run, which is not a gap: Kubernetes, ECS, and
+Cloud Run probe over HTTP from outside the container. Point their probe at
+`{{ dockerHealthPath }}`.
+
+## Hardening beyond the defaults
+
+`compose.yaml` already drops all capabilities and forbids privilege escalation. Two further
+steps depend on whether the app writes to disk:
+
+```yaml
+read_only: true
+tmpfs:
+  - /tmp
+```
+
+Turn these on and run the test suite against the container before relying on them — a framework
+that writes a cache directory at startup will fail immediately, which is what you want to find
+out locally.
+
+## Image size
+
+Check what actually shipped before optimizing:
+
+```bash
+docker image inspect {{ solutionName | kebab }}:dev --format '\{{.Size\}}'
+docker history {{ solutionName | kebab }}:dev
+```
+
+If a layer is larger than expected, the usual cause is a path that `.dockerignore` does not
+exclude reaching the build context.

package/templates/layers/docker/files/next.config.ts

@@ -0,0 +1,11 @@
+import type { NextConfig } from 'next';
+
+const nextConfig: NextConfig = {
+  // Fail the build on type errors instead of silently shipping them.
+  typescript: { ignoreBuildErrors: false },
+  // Emits .next/standalone — a self-contained server plus only the traced dependencies,
+  // which is what the container image copies instead of the whole node_modules tree.
+  output: 'standalone',
+};
+
+export default nextConfig;

package/templates/layers/docker-compose/blueprint.yaml

@@ -0,0 +1,118 @@
+id: docker-compose
+kind: layer
+name: Local Compose stack
+description: >-
+  One `docker compose up -d` that starts the whole local backing stack: the chosen
+  database, cache, and message broker on a single named network, each with a real
+  healthcheck so an app can gate on `service_healthy`. Every image tag, host port,
+  and credential is an environment override with a single default.
+
+tags: [docker, compose, local-development, infrastructure, database, cache, queue]
+
+# Stack-agnostic on purpose: this layer writes no application code, only container
+# definitions, so it composes with every base including ones with no runtime at all.
+requires: []
+
+# Nothing to declare. A future `dev-devcontainer` or `dev-podman` layer must name
+# `docker-compose` from its own blueprint — naming an id that does not exist yet makes
+# the whole catalog fail to load (loader.assertReferencesResolve), and conflicts are
+# symmetric anyway. The db-*/cache-* layers ship single-service compose files under
+# their own names, so no path is contested; docs/local-stack.md explains which to keep.
+conflicts: []
+
+# Virtual capabilities other layers key off rather than naming this layer directly.
+provides: [local-stack, container-runtime, dev-services, compose-network]
+
+# Container wiring is an infrastructure concern, not a layout concern.
+supportsArchitectures: []
+
+# Three questions, one per slot. Per-service tuning (ports, images, credentials) is
+# deliberately NOT asked here: each value is a `${VAR:-default}` interpolation in the
+# fragment that owns it, so the compose file is the single default table and .env is
+# the override surface. Adding variables for them would duplicate every default.
+variables:
+  - name: composeDb
+    prompt: Database service for the local stack
+    type: select
+    default: postgres
+    required: true
+    choices:
+      - { value: postgres, label: 'PostgreSQL' }
+      - { value: mysql, label: 'MySQL (8.4 LTS)' }
+      - { value: mongo, label: 'MongoDB (single-node replica set)' }
+      - { value: none, label: 'None — no database container' }
+
+  - name: composeCache
+    prompt: Cache service for the local stack
+    type: select
+    default: redis
+    required: true
+    choices:
+      - { value: redis, label: 'Redis' }
+      - { value: valkey, label: 'Valkey (BSD-licensed Redis fork)' }
+      - { value: none, label: 'None — no cache container' }
+
+  - name: composeQueue
+    prompt: Message broker for the local stack
+    type: select
+    default: none
+    required: true
+    choices:
+      - { value: none, label: 'None — no broker container' }
+      - { value: rabbitmq, label: 'RabbitMQ (with management UI)' }
+      - { value: nats, label: 'NATS (with JetStream)' }
+      - { value: kafka, label: 'Apache Kafka (KRaft, no ZooKeeper)' }
+
+files:
+  # Root entry point. Its `include:` list is token-rendered to the three fragments
+  # below, so exactly one file per slot must always exist on disk — hence the
+  # `-none` fragments, which are valid empty compose files rather than omissions.
+  - from: files/docker-compose.yml
+    to: .
+  - from: files/.env.compose.example
+    to: .
+  - from: files/docs/local-stack.md
+    to: .
+
+  # ── database slot ───────────────────────────────────────────────────────────
+  - from: files/compose/db-postgres.yml
+    to: .
+    when: "composeDb == 'postgres'"
+  - from: files/compose/db-mysql.yml
+    to: .
+    when: "composeDb == 'mysql'"
+  - from: files/compose/db-mongo.yml
+    to: .
+    when: "composeDb == 'mongo'"
+  - from: files/compose/db-none.yml
+    to: .
+    when: "composeDb == 'none'"
+
+  # ── cache slot ──────────────────────────────────────────────────────────────
+  - from: files/compose/cache-redis.yml
+    to: .
+    when: "composeCache == 'redis'"
+  - from: files/compose/cache-valkey.yml
+    to: .
+    when: "composeCache == 'valkey'"
+  - from: files/compose/cache-none.yml
+    to: .
+    when: "composeCache == 'none'"
+
+  # ── queue slot ──────────────────────────────────────────────────────────────
+  - from: files/compose/queue-rabbitmq.yml
+    to: .
+    when: "composeQueue == 'rabbitmq'"
+  - from: files/compose/queue-nats.yml
+    to: .
+    when: "composeQueue == 'nats'"
+  - from: files/compose/queue-kafka.yml
+    to: .
+    when: "composeQueue == 'kafka'"
+  - from: files/compose/queue-none.yml
+    to: .
+    when: "composeQueue == 'none'"
+
+# No postApply: nothing to install, and pulling images on generate would make a
+# repo un-scaffoldable offline. docs/local-stack.md carries the one command.
+postApply: []