Version 0.1.13

[0.1.13] - 2026-07-27

Added

• Versioned private overlay and preset catalogs — superposition.yml now supports project-declared external catalogs with immutable git/archive pinning or repo-relative path sources, namespace-qualified external IDs such as acme/web-api, strict no-override collision behavior in v1, shared catalog resolution across init/regen/doctor/list/explain/plan, and generated manifest receipts that record the resolved catalog identities used for replay

• fuseki overlay seed loading — Apache Jena Fuseki projects can now opt into automatic RDF seed imports from one file or one directory during devcontainer creation, with append-or-replace modes, optional named-graph targeting, content-type auto-detection/override, and a reusable .devcontainer/seed-fuseki.sh helper for reruns

• GitHub Copilot CLI overlay — the overlay catalog now includes copilot-cli, a terminal-first GitHub Copilot CLI install for devcontainers with configurable npm versioning, post-create installation, verification guidance, and authentication setup via copilot login or supported token environment variables

• Root Taskfile contributor workflow — the repository now ships a repo-root Taskfile.yml with thin wrappers over the existing npm scripts plus mandatory task validate and broader task validate:generated flows, so contributors have one discoverable entrypoint that runs lint:fix before lint and aligns local validation guidance with existing CI contracts

• Named multi-instance compose overlays for repeatable services — superposition.yml now accepts mixed overlays: entries so compose projects can keep legacy string singletons and add named object-form instances with per-entry parameter overrides. Top-level parameters: remain the shared default layer, manifests now record overlaySelections as a compatibility receipt for repeated intent, interactive init safely bails out instead of flattening existing named instances, generated services.md guidance now keeps repeated service hostnames instance-aware, and the audited repeatable compose catalog now includes postgres, redis, fuseki, sqlserver, and nats while deferred overlays still fail closed.

• Deterministic compose port rendering and optional env files — tool-owned compose port bindings are now written with final numeric host ports instead of ${...} host-port expressions, user-authored project ports remain verbatim, compose-targeted project env: now renders directly into generated docker-compose.yml even when env artifacts are off, and .devcontainer/.env plus .devcontainer/.env.example are opt-in artifacts only via --compose-env-files or composeEnvFiles: true. plan, doctor, generated summaries, and related help now follow the same persisted intent.

• Project-specific compose network names — compose-based generated projects now default docker-compose.yml -> networks.devnet.name from the repository folder name instead of one host-global devnet, support explicit composeNetworkName overrides in shared superposition.yml, preserve the logical devnet key inside overlays, and reject compose-network configuration on plain stacks

• Four project-local contributor Pi skills — the repo now includes /skill:cli-command-delivery, /skill:canonical-docs-alignment, /skill:workflow-sync, and /skill:dogfooding-safety so contributors and agents can discover required workflows, validation commands, prohibited shortcuts, and escalation rules for CLI command work, documentation alignment, spec/index/changelog/Pi synchronization, and generated-artifact safety directly from Pi, without reconstructing guidance from scattered authority docs.

• Project-local overlay discovery and requirements-capture Pi workflow — the repo now includes /skill:overlay-requirements-capture, /overlay-spec, /skill:overlay-solution-discovery, /overlay-discover, and /overlay-write-loop so contributors can start from a rough technology idea or plain-language need, capture a short overlay brief, check whether an existing overlay or preset already solves it, check whether a maintained published Dev Container Feature should be reused before writing bespoke install logic, and hand approved discovery output into the existing overlay creation/review loop.

• Repo-owned Behave overlay acceptance workflow — the repository now ships npm run test:bdd / task test:bdd, a shared Behave harness with automatic discovery of tests/behave/**/*.feature plus overlays/<id>/tests/behave/**/*.feature, CI wiring, repo-owned runtime bootstrap, semantic assertions for generated JSON/YAML/Compose/script output (including PATH/export checks), inline workspace fixtures for small scenario-local project files, and aligned contributor/overlay-authoring guidance for when to keep setup inline versus promote it to reusable fixture directories

• superposition.local.yml can now resolve local port conflicts without touching shared config — local config now supports portOffset and full ports replacement, including meaningful ports: [] to suppress shared project ports for one developer. init, regen, and doctor dry-compose generation honor those local-only overrides, while shared superposition.yml, plan, and generated superposition.json stay shared-only.

• Init-only user-scoped global defaults — eligible fresh init runs can now read personal home-directory defaults from preferred ~/.superposition.yml or legacy ~/.container-superposition.yml (with the legacy-specific file winning when both exist), opt out with --ignore-global-defaults, and scaffold a first superposition.local.yml from either a legacy localConfigTemplate or a stack-aware common / plain / compose template without affecting regen, doctor, plan, project-file replay, or manifest replay. The bootstrap initDefaults surface now explicitly includes existing devcontainerGitignore support plus stack, composeEnvFiles, and customImage, while still normalizing customImage away unless baseImage: custom and composeEnvFiles away unless stack: compose

• Stable prerelease npm tag in publish automation — successful prerelease publish runs now keep the exact version, publish directly with the shared prerelease dist-tag in the primary npm publish step, and advertise exact-version plus @prerelease install/regen commands in workflow summaries and PR comments without any PR-specific pr-{number} tag

Changed

• Overlay catalog audit remediation — compose overlays now rely on generator-owned final network naming, use overlay.yml serviceOrder as the documented startup-order source of truth, pin audited image defaults away from moving latest aliases (with the documented comfyui flavor exception), keep .shared inventory truthful, and record explicit bespoke-vs-reuse dispositions for the current tool/runtime decision set

• CLI UX model unified across init/regen/list/explain/plan/hash/doctor/adopt/migrate — human-readable command output now starts from shared framing, preview/review, and single next-step guidance built from normalized semantics instead of command-local copy. init/regen now omit placeholder next-step/manual-review output on clean runs, remove duplicate preflight intro boxes, prefer review generated diff after clean changed replay, and only suggest doctor when the outcome leaves a real warning to follow up. list now keeps workflow teaching in-body without a duplicate footer; explain lets Preview this change own the follow-up action; plan/hash keep footer guidance only when it is concrete and state-aware; doctor omits healthy-run placeholder guidance and avoids duplicate diagnosis/fix routing; adopt/migrate teach canonical vs compatibility vs preservation artifact roles without repeating the same replay action across frame, checklist, and footer.

• Second-pass read-only and conversion UX pass — list, explain, plan, hash, doctor, adopt, and migrate now show clearer first-screen context such as Current setup, project-vs-catalog scope, lane selection, planned changes, watch-outs, comparison meaning, and ordered next checklists. plan can now label reconciliation previews as Replay canonical intent; doctor defaults to project-health framing while --all-overlays is explicitly maintainer-style catalog validation.

Fixed

• Read-only CLI JSON output and overlay explain semantics are now stable in automation — list --json, explain --json, and adopt --json no longer risk truncated piped stdout before JSON consumers can parse it, cs explain postgres --json now reports normalized compose service IDs without template suffix tokens, and the Behave validation workflow now runs on main-branch pushes as well as pull requests
• cs explain now renders rich overlay ports readably — human-readable explain output no longer shows [object Object] for structured port metadata, now reuses one normalized port token across What it adds, What to watch out for, and Files, services, and ports, and keeps legacy numeric ports compact
• services.md no longer trips doctor reproducibility right after regen — generated service reference output is now deterministic by default instead of embedding wall-clock time, so cs doctor no longer reports services.md as out of date immediately after cs regen
• Doctor now checks Git-tracking safety for generated output and local-only config — cs doctor now warns when devcontainerGitignore: true output is still tracked, warns when superposition.local.yml is tracked, and doctor --fix can safely append superposition.local.yml to root .gitignore without mutating Git index
• Guided write review now gates init, doctor, and adopt mutations — init now starts with lane or shortcut entry points and requires explic...

Version 0.1.12

[0.1.12] - 2026-06-09

Fixed

• Ad-hoc project parameters now resolve correctly — superposition.yml parameters: keys not
  declared by any selected overlay (e.g. API_PORT, WEB_DEV_PORT) are now included in the
  resolved parameter map and available for {{cs.KEY}} substitution in env: values and
  overlay file content. Previously they triggered a hard Unresolved parameter token error.

Changed

• Publish workflow release guidance — successful npm publish runs now render exact npm install and npx container-superposition@<version> regen commands in the workflow summary; prerelease runs do same, and final releases also comment on associated PRs when one is found

• Console output for unlisted parameters — the ⚠️ Unknown overlay parameters … warning
  (yellow, comma-separated) is replaced by a neutral ⚙️ Project-only parameters (not declared by any selected overlay): informational block using the same KEY=VALUE per-line format as
  overlay parameters.

• Doctor check 4 wording — renamed from "Unknown parameters in project file" to
  "Project-only parameters (not declared by any selected overlay)"; findingId changed to
  project-only-parameters; guidance updated to explain these keys are resolved and valid,
  rather than advising removal.

• validateEnvTokensResolved() error message — second line now reads
  Resolved parameters: … instead of Declared parameters for selected overlays: …, accurately
  reflecting that both overlay-declared and project-only keys appear in the resolved map.

Added

• Parameter tokens ({{cs.KEY}}) in env: values — superposition.yml (and
  superposition.local.yml) env: values now support {{cs.KEY}} parameter tokens.
  Tokens are resolved in-memory at generation time using the fully resolved parameters: map
  (CLI > project parameters > overlay defaults). The project file is never modified.
  Unknown tokens cause a hard error before any files are written, reporting the env.KEY field
  and the list of declared parameters.
  This eliminates duplication between parameters: and env: — e.g.:

  env:
      DATABASE_URL: 'postgresql://{{cs.POSTGRES_USER}}:{{cs.POSTGRES_PORT}}/{{cs.POSTGRES_DB}}'

• Doctor: sensitive parameter checks — new doctor findings:

  • sensitive-params-project-file (warn) — fires when a parameter declared sensitive: true
    by an overlay has a literal (non-${VAR}) value in superposition.yml parameters:. Suppressed
    when the value equals the overlay default.
  • sensitive-params-devcontainer-env (warn) — fires when a sensitive parameter appears as
    plain text in .devcontainer/.env after generation. Skipped when .devcontainer/.env is absent
    (plain stack). Suppressed when value equals overlay default.

• Doctor: first-class property promotion suggestions — new doctor findings suggest
  migrating customizations usage to first-class fields:

  • customizations-env-promote — customizations.devcontainerPatch.remoteEnv set but env: absent
  • customizations-mounts-promote — customizations.devcontainerPatch.mounts set but mounts: absent
  • customizations-ports-promote — customizations.dockerComposePatch contains port bindings but ports: absent

• Docs: variable precedence and parameter token section — docs/superposition-yml.md now
  includes a "Parameter tokens ({{cs.KEY}})" section with syntax reference, supported fields
  table, pass-through guarantee table, and worked examples. The env: section now documents
  the two-tier generation-time vs runtime substitution model with a decision tree.

• Stable doctor finding IDs — internal CheckResult gains an optional findingId field;
  checksToFindings() prefers it over the name-slugified ID when present. Makes doctor --fix
  routing and test assertions stable across name changes.

• superposition.local.yml local config — optional repository-root local config for machine-specific env, mounts, shell, and customizations enrichment during generated devcontainer output creation, with schema support and Git safety warnings for unignored or already-tracked generated output.

• devcontainerGitignore project-file option — when enabled in superposition.yml,
  generation writes outputPath/.gitignore with:

  • *

• ports field in superposition.yml — first-class project port declarations with stack-specific semantics

  • stack: plain: write a container port expression (${VAR:-default} or a number, no colon); resolved at generation time with superposition.yml env taking priority over root .env, then inline default
  • stack: compose: write a full HOST:CONTAINER binding; written verbatim to docker-compose.yml (no ${VAR} expansion — Compose resolves at container startup); container port extracted best-effort for forwardPorts
  • portsAttributes keyed by container port (not host port)
  • Superposition.yml env entry simultaneously drives remoteEnv and plain-stack port resolution — single source of truth
  • Project ports entries are intentionally not shifted by portOffset

Changed

• ports semantics corrected — BREAKING for any superposition.yml that uses ports on stack: compose

  • Plain stack: value may be a bare container port expression (no colon) or a HOST:CONTAINER binding (e.g. "9001:8080"). When host ≠ container port, the tool adds -p HOST:CONTAINER to devcontainer.json runArgs. ${VAR} references are resolved at generation time.
  • Compose stack: value is now written verbatim to docker-compose.yml; ${VAR} references are no longer expanded by the tool. portsAttributes key is now the extracted container port, not the host port.
  • Migration for compose stacks: existing "8080:8080" entries work as before. Bare port expressions on compose stacks (no colon) now throw an error — add the host side: "8080" → "8080:8080".

• PR prerelease publishing — draft PRs publish npm prereleases only when labeled publish-prerelease; ready-for-review PRs continue publishing automatically.

Fixed

• fuseki overlay — added hostname: fuseki to the Docker Compose service to fix a startup failure where Fuseki could not resolve its own hostname

Version 0.1.11

[0.1.11] - 2026-05-27

Added

• pi overlay — adds the Pi minimal terminal coding agent (@earendil-works/pi-coding-agent) with multi-provider LLM support (Anthropic, OpenAI, Gemini, DeepSeek, and more)

• JSON Schema for superposition.yml — machine-readable schema enables editor auto-complete and inline validation when authoring project files

  • Schema is generated automatically from the overlay registry and TypeScript types via npm run schema:generate
  • Generated superposition.yml files now include a $schema line pointing to the stable URL: https://raw.githubusercontent.com/veggerby/container-superposition/main/tool/schema/superposition.schema.json
  • Schema file (tool/schema/superposition.schema.json) is committed to the repository, kept in sync by CI, and uploaded as a release asset with each GitHub release
  • Keeping the schema up to date is part of the Definition of Done: run npm run schema:generate after adding overlays or changing ProjectConfigSelection types

Fixed

• Generated README reproducibility — consolidated generated README.md files no longer embed the current date in their header, so repeated cs regen runs remain deterministic and cs doctor does not report false-positive drift from a day rollover alone

Version 0.1.10

[0.1.10] - 2026-05-05

Added

• task overlay — Adds Taskfile CLI (task) for declarative project automation
  • Installs architecture-specific Task binary (amd64/arm64) from official releases in setup.sh
  • Includes verify.sh smoke check wired to postStartCommand
  • Suggests modern-cli-tools and kubectl-helm for broader developer workflows
• mounts field in superposition.yml — First-class filesystem mount support with structured entries and raw-string fallback; stack-agnostic by design so the same config works unchanged when swapping between plain and compose
  • Structured form supports source, destination, optional type, cached, consistency, readOnly, and target
  • Named map syntax is supported (e.g. mounts: { codex: { source: ..., destination: ... } }) in addition to list syntax
  • Raw-string and { value: "..." } forms remain available as an escape hatch for advanced mount specs; value and source/destination cannot be combined in the same entry
  • target: auto (default) and target: devcontainerMount always route to devcontainer.json mounts[] regardless of stack
  • target: composeVolume is an explicit opt-in to route to docker-compose.yml services.devcontainer.volumes[] (compose only; error on plain)
  • Applied before customizations.devcontainerPatch / customizations.dockerComposePatch so patch overrides remain respected
• superposition.yml authoring guide (docs/superposition-yml.md) — comprehensive reference covering every field, routing tables, and a complete annotated example; README.md updated to reference it
• ansible overlay — Adds Ansible automation tooling (ansible, ansible-playbook, ansible-galaxy) with ansible-lint, plus the VS Code Red Hat Ansible extension (redhat.ansible)
  • Installs via the shared cross-distro-packages feature with distro fallback package names
  • Suggests aws-cli, azure-cli, gcloud, and terraform for end-to-end infrastructure automation workflows
• argocd overlay — Adds Argo CD CLI for GitOps application workflows
  • Installs architecture-specific argocd binary from official Argo CD releases in setup.sh
  • Includes verify.sh smoke check wired to postStartCommand
  • Suggests kubectl-helm, k3d, and kind for Kubernetes/GitOps development workflows
• shell field in superposition.yml — First-class shell profile customizations for aliases and snippets
  • Supports shell.aliases and shell.snippets
  • Generates .devcontainer/custom/shell-init.sh
  • Adds an idempotent postCreate hook that manages a marked source block in ~/.bashrc and ~/.zshrc
  • env remains the canonical place for environment variables/exports

Version 0.1.9

[0.1.9] - 2026-04-29

Added

• doctor overlay dependency checks — cs doctor now validates that all overlay requires: dependencies are present in the project file, flags unknown overlay IDs (typos, removed overlays), and surfaces suggests: entries as informational warnings; doctor --fix auto-adds missing required overlays and regenerates
• doctor port cross-validation — cs doctor cross-checks devcontainer.json forwardPorts against the ports actually exposed by Docker Compose services; reports fail for forwarded ports with no backing service and warn for compose-bound ports absent from forwardPorts; not auto-fixable (requires overlay-level changes)
• doctor .env.example drift detection — cs doctor detects when .env.example is stale: fail for parameters declared by selected overlays that are missing from the file; warn for keys in the file not declared by any overlay; doctor --fix regenerates .env.example via a full cs regen
• doctor reproducibility check — cs doctor dry-composes the devcontainer to a temp directory and compares it file-by-file against the current output; reports fail when a generated file is missing or has drifted from what cs regen would produce; doctor --fix regenerates the affected files
• doctor --fix --dry-run — New flag combination that previews what doctor --fix would change without writing any files; prints a numbered plan of each auto-fixable action with its remediationKey, safetyClass, and plannedChanges; exits with code 1 when any findings exist (auto-fixable or manual) so CI can detect "fix needed" without applying changes; --dry-run without --fix is an error; --format json is supported and adds dryRun: true and plannedActions to the output
• doctor parameter checks — cs doctor now validates overlay parameter configuration against the project file and generated output. Five new checks in a dedicated "Parameters" section:
  • Unresolved {{cs.*}} tokens — scans devcontainer.json, docker-compose.yml, and .env.example for substitution tokens that were never replaced; reported as a failure
  • Sensitive parameters in plain text — detects sensitive: true parameters whose values appear as literal strings in devcontainer.json remoteEnv instead of being referenced via ${VAR:-default}; reported as a warning
  • Missing .env.example — warns when a compose-stack project has parameterised overlays but no .env.example was generated
  • Unknown parameter keys — warns when the project file's parameters: section contains keys not declared by any selected overlay (stale entries from removed overlays)
  • Missing required parameters — fails when an overlay declares a required parameter (no default value) that is absent from the project file parameters: section
  • doctor --fix resolves the automatic checks by adding missing parameters with their overlay defaults to the project file then re-running cs regen
• local-llm preset — New preset for local LLM inference: always selects ollama + ollama-cli + open-webui; optional gpu parameter adds cuda or rocm overlay; pre-sets OLLAMA_HOST environment variable
• full-observability preset — New preset that bolts a complete monitoring stack onto any project: prometheus, grafana, loki, otel-collector, alertmanager, promtail always included; tracing parameter selects Jaeger, Tempo, both, or none; pre-sets all OTel SDK environment variables
• vector-ai preset — New preset for RAG pipeline development: qdrant + ollama + ollama-cli + python always included; optional gpu and chat_ui (Open WebUI) parameters; pre-sets QDRANT_URL, OLLAMA_HOST, and EMBEDDING_MODEL
• k8s-dev preset — New preset for local Kubernetes development: kubectl-helm + docker-in-docker + modern-cli-tools always included; cluster parameter selects k3d (default) or kind; devloop parameter selects Tilt (default), Skaffold, or none
• .shared/vscode/markdown-extensions.json — New shared VS Code fragment containing yzhang.markdown-all-in-one and DavidAnson.vscode-markdownlint; imported by mkdocs, mkdocs2, and pandoc overlays, removing duplicated extension entries from their patches
• fuseki overlay — New overlay for Apache Fuseki (Apache Jena SPARQL server); runs stain/jena-fuseki with a TDB2-backed persistent dataset, exposes port 3030 for the SPARQL endpoint and admin UI, and injects FUSEKI_HOST, FUSEKI_PORT, FUSEKI_DATASET, FUSEKI_URL, and FUSEKI_ADMIN_PASSWORD into the devcontainer environment
• parameters: sections on infrastructure overlays — mysql, mongodb, redis, rabbitmq, nats, minio, sqlserver, and localstack now declare all configurable values (version, port(s), credentials) as first-class parameters visible to the questionnaire and documentation system; password fields are marked sensitive: true
• serviceOrder field in overlay.yml — Service startup ordering is now declared as serviceOrder: <number> in overlay.yml rather than the non-standard _serviceOrder field in devcontainer.patch.json, eliminating VS Code JSON schema validation warnings; mergeRunServices() reads the value from the overlay manifest; convention is 0 = infrastructure, 1 = observability backends, 2 = middleware, 3 = UI tier, 4 = demo apps
• messaging overlay category — rabbitmq, nats, and redpanda are now categorised as messaging instead of database; the interactive questionnaire shows a dedicated "Messaging" section; a MessagingOverlay type alias is exported from tool/schema/types.ts
• .shared/vscode/js-ts-settings.json — New shared VS Code settings fragment providing Prettier/ESLint extensions and formatOnSave for TypeScript and JavaScript; imported by nodejs and bun overlays, removing duplicated configuration from their patches

Fixed

• cross-distro-packages feature deleted on regen — When cleanupStaleDirFiles was introduced to remove stale scripts within registered directories, it also recursed into the features/ directory and deleted cross-distro-packages/devcontainer-feature.json and install.sh because those files were never added to the file registry. The composer now registers every file in the copied feature directory, so devcontainer build can locate the local feature.
• Stale scripts/ files not removed on regen — When an overlay with a setup.sh or verify.sh was removed from a project and cs regen was run, any scripts that belonged only to the removed overlay (e.g. scripts/setup-rabbitmq.sh) were left behind on disk if at least one other overlay still contributed scripts. The cleanup pass now recurses into registered subdirectories and removes individual stale files within them, not just entire unregistered directories. Additionally, scripts/ is no longer created eagerly before determining whether any overlay in the current run requires it.
• messaging overlays rejected by project file validator on regen — After rabbitmq, nats, and redpanda were moved to the messaging category, any project file using the legacy database: list field to declare them caused a ProjectConfigError that silently aborted cs regen before any files were written — leaving the previous docker-compose.yml intact. The database predicate in buildCategoryLookup now accepts both database and messaging category overlays so existing project files continue to work without migration.
• Port conflict declarations — Added bidirectional conflicts: entries for all overlays sharing host ports, preventing silent Docker bind failures at startup:
  • Port 3000: grafana, open-webui, nodejs, bun, rust
  • Port 8080: mysql, redpanda, otel-demo-nodejs, nodejs, bun, go, java, dotnet
  • Port 8081: mongodb, redpanda, otel-demo-python, go, java
• grafana and otel-collector depends_on — Removed hardcoded depends_on entries for services declared as suggests (optional); grafana now only depends on prometheus (its sole requires); otel-collector's depends_on block removed entirely
• minio / localstack conflict — Added bidirectional conflict between minio and localstack (both provide S3-compatible storage and inject conflicting AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY); minio env var unified from AWS_REGION to AWS_DEFAULT_REGION
• Redundant feature installs — pre-commit no longer re-installs the Python devcontainer feature (already provided by requires: [python]); commitlint no longer re-installs Node (already provided by requires: [nodejs]); playwright now declares requires: [nodejs] and no longer installs Node independently
• Observability restart: unless-stopped — Added restart policy to all 8 observability compose services (prometheus, grafana, loki, tempo, jaeger, alertmanager, promtail, otel-collector)
• Observability healthchecks — Added HTTP healthchecks to all 8 observability services; grafana's healthcheck uses /api/health, prometheus and alertmanager use /-/ready, others use /ready or the collector's / health endpoint
• redis healthcheck — Added redis-cli ping healthcheck matching the pattern in .shared/compose/common-healthchecks.md
• mysql and mongodb healthcheck start_period — Added start_period: 30s to mysql and start_period: 20s to mongodb to prevent spurious failures during slow storage-engine initialisation
• qdrant version pinning — Default QDRANT_VERSION changed from latest to v1.9.0 for reproducible builds
• mkdocs category — Changed from language to dev, matching mkdocs2 and reflecting that documentation generators are dev tools, not language runtimes
• comfyui GPU devcontainer support — A...

Version 0.1.8

[0.1.8] - 2026-04-11

Added

• open-webui overlay — Browser-based chat UI for Ollama and OpenAI-compatible LLM backends, running as a Docker Compose sidecar

  • Serves the Open WebUI at port 3000 (mapped from container port 8080); auto-forwarded and opened in the browser
  • Pre-configured OLLAMA_BASE_URL=http://ollama:11434 so it connects automatically when the ollama overlay is also selected
  • Persistent open-webui-data volume preserves conversation history and settings across container rebuilds
  • Supports any OpenAI-compatible backend via OLLAMA_BASE_URL; not limited to Ollama
  • Suggests the ollama overlay as its natural LLM backend

• qdrant overlay — High-performance vector database for similarity search and embeddings, running as a Docker Compose service

  • REST API on port 6333, gRPC on port 6334; both ports forwarded from the devcontainer
  • QDRANT_HOST, QDRANT_PORT, and QDRANT_URL pre-set in the container environment for zero-config SDK usage
  • Persistent qdrant-data volume and health check via /readyz endpoint
  • Suggests ollama, python, and nodejs overlays for embedding-generation workflows

• pgvector overlay — PostgreSQL 16 with the pgvector extension pre-installed, running as a Docker Compose service

  • Uses the official pgvector/pgvector:pg16 image; CREATE EXTENSION vector; works immediately with no manual setup
  • postgresql-client installed in the devcontainer; PGHOST, PGPORT, PGDATABASE, and PGUSER pre-set for seamless psql usage
  • Conflicts with the postgres overlay (both provide a PostgreSQL service on port 5432 — choose one)
  • Fully parameterised: PGVECTOR_DB, PGVECTOR_USER, PGVECTOR_PASSWORD, PGVECTOR_PORT, PGVECTOR_VERSION configurable via superposition.yml or --param
  • Suggests ollama, python, and nodejs overlays for RAG and embedding workflows

• k3d overlay — Lightweight local Kubernetes clusters running k3s in Docker, with faster startup and lower resource usage than kind

  • Installs the k3d binary via setup.sh; supports amd64 and arm64
  • Requires docker-in-docker (auto-resolved dependency) to launch k3s nodes as Docker containers
  • Conflicts with kind (both provision local Kubernetes clusters — choose one)
  • Suggests kubectl-helm for interacting with clusters via kubectl and Helm
  • README includes a k3d vs kind comparison table

• skaffold overlay — Continuous build-test-deploy pipeline for Kubernetes applications

  • Installs the skaffold binary via setup.sh; supports amd64 and arm64
  • Supports multiple builders (Docker, Buildpacks, Jib) and deployers (kubectl, Helm, Kustomize) via declarative skaffold.yaml
  • Conflicts with tilt (both serve the Kubernetes inner-loop development role — choose one)
  • Suggests kubectl-helm, kind, and k3d overlays for a complete local Kubernetes workflow
  • README includes a skaffold vs tilt comparison table

• Overlay parameters with safe {{cs.KEY}} substitution — Overlays can now declare configurable parameters that are resolved at generation time without colliding with Docker Compose ${VAR}, shell $VAR, VS Code ${localWorkspaceFolder}, or GitHub Actions ${{ }} syntax

  • Overlays declare parameters in overlay.yml under a parameters: map, each with a description, optional default, and optional sensitive: true flag
  • Users supply values in superposition.yml under a top-level parameters: section, or via --param KEY=value on the CLI (repeatable)
  • Resolution order: CLI overrides → project file → overlay defaults
  • Missing required parameters (no default, no supplied value) → hard error before generation
  • Unresolved {{cs.*}} tokens in final output → hard error (catch-all safety net)
  • Unknown parameters supplied in superposition.yml → warning only (generation continues)
  • Docker Compose ${VAR:-default}, shell, VS Code, and GitHub Actions variable expressions pass through completely untouched
  • The {{cs.*}} syntax can be nested inside Docker Compose defaults: ${POSTGRES_PORT:-{{cs.POSTGRES_PORT}}} — cs resolves the inner token at generation time, Docker resolves the outer at runtime
  • Interactive questionnaire prompts for each declared parameter (sensitive parameters use masked input)
  • postgres overlay converted to use parameters as proof-of-concept: POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_PORT, POSTGRES_VERSION are now fully configurable without forking the overlay
  • Spec committed under docs/specs/011-overlay-parameters/spec.md

• First-class project env in superposition.yml — Container environment variables can now be declared once in the project file and routed automatically by stack

  • stack: plain writes project env entries to devcontainer.json -> remoteEnv
  • stack: compose materializes project env entries into .devcontainer/.env, writes docker-compose.yml -> services.devcontainer.environment as ${KEY}, and exposes the same values to the devcontainer via devcontainer.json -> remoteEnv.KEY = ${containerEnv:KEY}
  • Supports string shorthand (FOO: bar) and object form with explicit target override (target: auto | remoteEnv | composeEnv)
  • Compose values that reference ${NAME} or ${NAME:-default} resolve from the repository root .env when available before being written to .devcontainer/.env
  • customizations.envTemplate is now the canonical project-file field for variables written to .env.example; customizations.environment remains as a deprecated read-compatible alias, but newly written project files normalize to envTemplate

• JetBrains IDE support (--editor jetbrains) — Generates JetBrains project artifacts alongside the devcontainer configuration

  • Adds customizations.jetbrains.backend to devcontainer.json, selecting the IDE automatically from the primary language overlay (WebStorm for Node.js/Bun, PyCharm for Python, GoLand for Go, Rider for .NET, RustRover for Rust, IntelliJIdea for Java or generic)
  • Generates .idea/.gitignore at the project root, marking shared settings as VCS-tracked and excluding user-local entries
  • Generates language-specific run configuration XML files under .idea/runConfigurations/ (npm_dev.xml for npm run dev / Node.js, bun_dev.xml for Bun, mkdocs_serve.xml for mkdocs serve, python_main.xml for python main.py, go_run.xml for go run ./..., dotnet_run.xml for dotnet run, java_run.xml for a Java Application, rust_run.xml for cargo run)
  • Existing .idea/ files are never overwritten — only missing files are written, preserving any user customisations
  • Falls back to a minimal .idea/ scaffold with IntelliJIdea backend when no language overlay is selected
  • Editor profile question added to the interactive questionnaire (? Editor profile: VS Code / JetBrains / None)
  • editor field persisted to superposition.json manifest for reproducible regen

• cs command alias — npm install -g container-superposition now registers both container-superposition and the shorter cs command; all existing cs <subcommand> usage in docs and examples works without a separate install

• ollama overlay — Local LLM inference server via Ollama, running as a Docker Compose sidecar

  • Serves the Ollama REST API on port 11434; OpenAI-compatible endpoint available at /v1/
  • Ollama CLI installed in devcontainer — setup.sh now prefers copying /usr/bin/ollama from the local ollama/ollama sidecar image, avoiding a second multi-gigabyte download during setup; when Docker is unavailable it falls back to the current official Linux release archives (prefers .tar.zst, falls back to legacy .tgz, and installs zstd when required) instead of via ollama.com/install.sh
  • OLLAMA_HOST pre-configured — Set as a containerEnv variable to http://ollama:11434 so ollama pull / run / list / rm target the sidecar automatically with no manual setup
  • GPU passthrough built-in — Both the ollama sidecar and the devcontainer service receive all NVIDIA GPUs via deploy.resources.reservations.devices; enables GPU-accelerated tooling (torch, tensorflow, CUDA CLIs) directly in the dev environment
  • Mounts the host's ~/.ollama directory by default so models pulled on the host are immediately available — no re-download on rebuild; models pulled inside the devcontainer are also persisted to the host
  • OLLAMA_MODELS_PATH env var overrides the host model path (useful for external drives or Windows users)
  • verify.sh checks CLI is installed, OLLAMA_HOST is set, smoke-tests the REST API, and lists available models via the CLI
  • Suggests codex, claude-code, and amp overlays for AI-assisted workflows
  • README documents the Ollama CLI UX, GPU prerequisites (NVIDIA Container Toolkit), and links to the cuda overlay

• Target-aware generation — --target now produces workspace artifacts and setup guidance tailored to the selected deployment environment, not just compatibility warnings

  • --target codespaces → extends devcontainer.json with hostRequirements (machine-size recommendation based on service count) and writes CODESPACES.md with Codespaces-specific setup guidance
  • --target gitpod → generates .gitpod.yml at the project root (with tasks and port exposures from selected overlays) and writes GITPOD.md with Gitpod badge and usage notes
  • --target devpod → generates devpod.yaml at the project root (referencing the devcontainer) and writes DEVPOD.md with devpod up instructions
  • --target local (explicit or default) → no change to existing behavior; no extra files writt...

Version 0.1.7

[0.1.7] - 2026-03-23

Added

• Shared overlay imports — Overlays can now declare imports: in their overlay.yml to reuse fragments from overlays/.shared/, reducing copy-paste duplication across the overlay catalogue

  • Supported types: .json and .yaml/.yml fragments are deep-merged into the devcontainer patch; .env fragments are appended to .env.example with a # from .shared/… comment
  • Imports are applied in declaration order, followed by the overlay's own devcontainer.patch.json; the overlay's own patch always wins on key conflict
  • Path traversal prevention: any import path that does not begin with .shared/ or resolves outside overlays/.shared/ is rejected before generation starts
  • Missing files, unsupported types, and traversal attempts all fail with an error that names the overlay and the bad reference
  • explain <overlay> now shows the overlay's imports list under a Shared Imports section
  • doctor validates import paths (existence, type, and path traversal) for every overlay

• otel-collector, prometheus, and jaeger overlays converted — These three overlays now import .shared/otel/instrumentation.env, so their generated .env.example includes the OTEL SDK environment variables without duplication

• overlays/.shared/vscode/recommended-extensions.json reformatted — Now a valid devcontainer patch (customizations.vscode.extensions array) that can be merged directly when imported

• doctor --fix — Interactive repair flow for common environment problems

  • Can fix stale manifests, missing devcontainer regeneration, Node.js version mismatches, and Docker daemon issues
  • Re-runs checks after remediation and reports a structured outcome summary; use --fix --json for machine-readable output

• Shared setup utilities — A generated scripts/setup-utils.sh is now included automatically when any overlay provides a setup.sh

  • Centralises apt locking, architecture detection, binary installation helpers, npm environment setup, and quieter script output
  • Eliminates apt-lock races between parallel postCreateCommand scripts and reduces boilerplate across overlay setup scripts

• all overlay — Meta-overlay that expands to all non-preset overlays; useful for integration testing; hidden from the interactive questionnaire

• cuda overlay — NVIDIA CUDA GPU passthrough for containerized ML/inference workloads

  • Injects "runArgs": ["--gpus=all"] and "hostRequirements": {"gpu": true} into devcontainer.json
  • setup.sh probes nvidia-smi on container start and prints step-by-step remediation guidance when GPU access is unavailable
  • verify.sh asserts nvidia-smi exits 0 for doctor checks
  • Conflicts with rocm (the companion AMD GPU overlay)

• rocm overlay — AMD ROCm GPU passthrough for containerized ML/inference workloads

  • Injects --device=/dev/kfd, --device=/dev/dri, --group-add=video, and --group-add=render into runArgs
  • setup.sh probes rocm-smi / rocminfo on container start and prints actionable host-setup guidance when GPU access is unavailable
  • verify.sh asserts rocm-smi exits 0 for doctor checks
  • Conflicts with cuda (bidirectional); treated as a separate supported profile, not a CUDA drop-in replacement

• devcontainer-cli overlay — Installs @devcontainers/cli globally for building and managing devcontainers from the terminal

• Port conflict auto-resolution — init and regen now detect host-port collisions across selected overlays and remap conflicting ports automatically, with a before/after warning in the output

Changed

• Flat overlays field in project config — Project files now use a single overlays array instead of per-category keys (language, database, devTools, etc.); old category keys are still accepted for backward compatibility
• doctor command — --from-manifest, --from-project, and --project-root flags added, bringing doctor into parity with init and regen for project-file and manifest selection
• direnv overlay — Package installation moved to cross-distro-packages devcontainer feature (runs at image-build time); setup.sh now handles only shell hook configuration
• modern-cli-tools overlay — Core packages (jq, ripgrep, fd-find, bat) moved to cross-distro-packages; setup.sh now only installs yq and creates platform symlinks (fdfind→fd, batcat→bat)
• git-lfs feature — autoPull set to false in the git-helpers overlay; prevents container creation failures in repos with no LFS remote configured

Fixed

• ${containerEnv:HOME} in mount targets — Replaced with absolute path /home/vscode/.codex; Docker cannot resolve container env vars at mount time
• pandoc overlay — Added missing lmodern package required by the default LaTeX template on Trixie; emoji-fallback.lua filter extended to cover BMP symbol blocks (Dingbats U+2700–U+27BF, Miscellaneous Symbols U+2600–U+26FF) — ✅ ⚠ ❌ and similar characters are now routed to \textfallback{} (Noto Sans Symbols 2) so they render as proper glyphs instead of generating XeLaTeX [WARNING] Missing character messages
• tilt overlay — Replaced pipe-to-bash installer with direct binary download; fixes sudo mv: No such file or directory on some systems
• minio overlay — Fixed hardcoded amd64-only download URL; now correctly selects the aarch64 binary
• just overlay — Removed hardcoded SHA256 checksums that were incorrect for aarch64
• mongodb overlay — Replaced standard-repo feature (package not in default repos) with a setup.sh that adds the official MongoDB apt repository
• gcloud overlay — Replaced deprecated apt-key-based feature with a setup.sh using gpg --dearmor
• nats overlay — Fixed latest-alpine tag not existing on Docker Hub; default version is now 2
• windsurf-cli overlay — Replaced non-existent npm package with binary download from GitHub releases; verify script now exits gracefully on unsupported platforms (arm64)
• powershell overlay — Fixed hang on interactive NuGet provider prompt; Install-PackageProvider is now skipped on PowerShell 7+ where the provider is built-in
• playwright overlay — Browser install moved to a setup.sh that holds the shared apt lock, preventing E: Could not get lock races with other parallel setup scripts; noisy apt and download progress output suppressed
• keycloak overlay — Health-check URL corrected to port 9000 (management port) instead of 8180; verify timeout increased to cover the full container startup window; depends_on now waits for postgres to be healthy (condition: service_healthy) so Keycloak no longer starts before its database is ready
• postgres overlay — Added pg_isready healthcheck to the service definition so dependent overlays (e.g. Keycloak) can use condition: service_healthy
• sqlserver overlay — Verify script replaced docker exec (which requires Docker socket access) with a two-path strategy: docker exec via the container's ancestor image when available, TCP port check (/dev/tcp) as an automatic fallback when the Docker socket is not mounted
• redpanda overlay — Fixed YAML indentation in the Console config that caused the schema-registry URL to be silently ignored
• pre-commit overlay — Installation now prefers pipx to avoid conflicts with active virtualenvs
• direnv overlay — direnv allow now also runs on container rebuilds when .envrc already exists, fixing the "blocked" error on subsequent opens
• bun overlay — PATH entry persisted to shell profiles; verify script falls back to ~/.bun/bin/bun when the binary is not yet on PATH in a non-interactive shell
• alertmanager / otel-collector overlays — Fixed workspace-root detection; scripts now locate .devcontainer/ relative to their own path, eliminating failures when LOCAL_WORKSPACE_FOLDER is a host-only path
• alertmanager, promtail, tempo, otel-demo-nodejs, otel-demo-python overlays — Verify scripts now use the service's HTTP health endpoint as the primary readiness check instead of docker ps; eliminates false failures when the Docker socket is not accessible from inside the devcontainer
• mysql overlay — Verify script timeout increased to 90 seconds to match the container healthcheck window
• Duplicate postCreateCommand entries — duckdb, kind, openapi-tools, tilt, and playwright overlay patches were causing setup scripts to run twice; redundant entries removed
• Parallel apt contention — Setup scripts now coordinate through the shared apt lock, eliminating E: Could not get lock failures during parallel postCreateCommand execution
• Escape sequences in apt output — DEBIAN_FRONTEND=noninteractive and TERM=dumb are now passed explicitly on sudo apt-get invocations; prevents cursor-probe escape sequences appearing in devcontainer build logs

Version 0.1.6

[0.1.6] - 2026-03-16

Added

• pandoc overlay — Complete Markdown → PDF pipeline with Pandoc, XeLaTeX, and optional Mermaid diagram rendering
  • Installs Pandoc 3.x from the official GitHub release (not the outdated apt version)
  • TeX Live / XeLaTeX with Carlito, JetBrains Mono, and Noto Sans Symbols 2 fonts for clean Unicode output
  • diagram.lua Lua filter from pandoc-ext/diagram for fenced mermaid code block rendering
  • Mermaid CLI (mmdc) installed automatically when the nodejs overlay is present; skipped gracefully otherwise
  • System Chromium wired to Puppeteer with --no-sandbox for headless Mermaid rendering inside containers
  • Ready-to-use ~/.pandoc/pandoc.yaml defaults file with XeLaTeX engine, font, and table settings
• Adopt project-file output — adopt --project-file now writes a repository-root project config alongside the manifest
  • Reuses an existing .superposition.yml or superposition.yml when present to avoid dual-file ambiguity
  • Carries inferred output path, container name, overlay selections, and supported customizations into the generated project file
• Project-root selection for persisted input — init and regen now accept --project-root <path>
  • Lets you load a repository project file or discover a manifest from another directory without changing shells first
  • Relative output paths from the selected project file continue to resolve from that repository root
• minimal-trixie example — Lightweight project-file-driven example using Debian Trixie with Codex and a ~/.codex host mount
• kitchen-sink example — Comprehensive reference example exercising every superposition.yml field: preset with parameter choices, additional overlays, port offset, deployment target, editor profile, and the full customizations block (patches, environment, scripts, files)

Fixed

• cross-distro-packages feature — Package declarations can now use fallback names like pkgA|pkgB
  • Allows overlays such as pandoc to handle Debian-vs-Ubuntu package-name differences without embedding apt-specific detection logic in setup scripts

Version 0.1.5

[0.1.5] - 2026-03-11

Added

• Project config generation — Standard init can now read a repository-root .superposition.yml or superposition.yml
  • Lets teams and CI run generation from committed declarative defaults instead of reconstructing long CLI commands
  • regen now supports --from-project, uses the repository project file by default when present, and consistently behaves as deterministic replay across project-file and manifest-based persisted sources
  • init remains the editable flow, so persisted sources can still prefill the questionnaire when you want to modify a generated setup instead of replaying it exactly
  • Direct CLI flags still override the project config for one run, while explicit --from-manifest regeneration remains isolated
  • Conflicting persisted-input source combinations such as --from-project --from-manifest or source mode plus structural selection flags now fail before generation with a clear source-conflict error
  • Supports parity for the existing clean-generation surface, including custom images, container naming, minimal/editor settings, environment variables, and additional generated features declared through custom patches
• Verbose plan narration — plan --verbose now explains why each overlay was included
  • Shows direct selections, required dependencies, and dependency paths in the terminal output
  • Supports plan --from-manifest <path> --verbose so existing manifests get the same explanation model as explicit overlay lists
  • Adds structured inclusion reasons to plan --json --verbose without changing the default JSON shape
  • Calls out skipped overlays and conflict boundaries so dependency resolution is easier to audit
• spec-kit overlay — Spec-Driven Development with the specify CLI and any supported AI coding agent
  • Installs uv (Astral's fast Python package manager) and specify-cli from github/spec-kit
  • Supports 20+ AI agents: Codex, Claude Code, Gemini CLI, GitHub Copilot, Cursor, Windsurf, Amp, opencode, and more
  • Usage: specify init . --here --ai <agent> after overlay setup
• claude-code overlay — Anthropic Claude Code CLI (@anthropic-ai/claude-code) for AI-powered terminal development
• gemini-cli overlay — Google Gemini CLI (@google/gemini-cli) for AI-powered terminal development
• amp overlay — Sourcegraph Amp CLI (@sourcegraph/amp) for AI-powered terminal development
• windsurf-cli overlay — Codeium Windsurf CLI for AI-powered terminal development
• opencode overlay — opencode AI coding agent (opencode-ai) for multi-provider terminal development
• sdd preset — Spec-Driven Development meta-preset bundling spec-kit with a user-selectable AI agent CLI
  • Prompts users to choose from: Codex, Claude Code, Gemini CLI, Amp, Windsurf, opencode, or GitHub Copilot (IDE-integrated)
  • Sets SPECIFY_AI_AGENT environment variable automatically to match the chosen agent
• hash command — Deterministic environment fingerprint for drift detection and reproducibility
  • Produces a stable SHA-256 fingerprint from stack, resolved overlays, preset, base image, and tool version
  • Auto-resolves overlay dependencies (same logic as plan) so the hash includes transitively required overlays
  • Works standalone (--stack/--overlays flags) or reads directly from an existing superposition.json manifest
  • --json flag emits machine-readable JSON with both a short 8-character hash (for display/badges) and the full 64-character hashFull (for CI comparison)
  • --write flag writes the full hash to .devcontainer/superposition.hash alongside the manifest
  • Hash is version-stable across patch releases (uses major.minor of the tool version only)
  • Full documentation at docs/hash.md
• adopt command — Adopt an existing .devcontainer/ into the overlay-based model
  • Reads devcontainer.json and any linked docker-compose.yml files and analyses their contents
  • Resolves the dockerComposeFile field (string or array, relative paths) to support Docker Compose-based devcontainers where the compose file lives outside the .devcontainer/ directory
  • Maps detected devcontainer features, Docker Compose service images, VS Code extensions, and remoteEnv variables to equivalent overlay IDs
  • Detection tables are built dynamically from the overlay registry — no hardcoded overlay names, every overlay is automatically supported
  • Best-match scoring ensures a feature used by multiple overlays (e.g. the Node.js feature shared by nodejs and bun) is assigned to the most appropriate one
  • Displays a table showing each detected signal → suggested overlay with a confidence level (exact or heuristic)
  • Prints the equivalent container-superposition init command to reproduce the configuration, using correct CLI flags per overlay category (--language, --database, --observability, --cloud-tools, --dev-tools)
  • Unmatched items (features, services, extensions not covered by any overlay) are surfaced separately; a custom/devcontainer.patch.json / custom/docker-compose.patch.yml is written to preserve them across regenerations
  • Backup support using the same auto-detect logic as regen — skipped in git repos by default; use --backup / --no-backup / --backup-dir to override
  • --dry-run flag prints the analysis without writing any files
  • Prompts to generate superposition.json (and optionally custom/ patch files) from the suggestions
  • --force flag allows overwriting existing generated files
  • --json flag for machine-readable output (suitable for scripting)
  • Gracefully handles configs with no recognisable overlay patterns
  • Full documentation at docs/adopt.md

Version 0.1.4

[0.1.4] - 2026-02-26

Added

• Keycloak overlay — Open-source identity and access management for local OAuth2/OIDC development

  • Runs as a Docker Compose service on port 8180 (avoids collision with common app servers)
  • Automatically requires and integrates with the postgres overlay as its database backend
  • Exposes OIDC discovery at /realms/master/.well-known/openid-configuration
  • KEYCLOAK_HOST, KEYCLOAK_PORT, and KEYCLOAK_ISSUER wired into the dev container via remoteEnv

• Mailpit overlay — Email testing tool that captures all outbound email locally

  • SMTP server on port 1025 (no authentication required in dev mode)
  • Web UI on port 8025 for browsing captured emails
  • REST API at /api/v1/messages for automated test assertions
  • SMTP_HOST, SMTP_PORT, and MAILPIT_URL wired into the dev container via remoteEnv

• gRPC Tools overlay — Protocol Buffers and gRPC development toolchain

  • Installs protoc (via system packages), buf CLI, and grpcurl (from official GitHub releases, multi-arch)
  • VS Code extensions: vscode-proto3 and vscode-buf
  • Works with all base stacks (plain and compose)

• Cloudflared overlay — Cloudflare Tunnel for securely exposing local services to the internet

  • Anonymous tunnels work immediately with no account required
  • Named tunnels support persistent URLs with a Cloudflare account
  • Conflicts with ngrok overlay (bidirectional — both overlays declare the conflict)
  • Pinned to a specific release version for reproducibility

• Service reference exports — Two convenience files are now auto-generated during init and regen for projects that include service overlays

  • services.md — Consolidated service reference with connection info, connection strings (URIs), code examples (Node.js, Python) for common services, common CLI commands, port offset documentation, and a troubleshooting section
  • env.local.example — Optional-overrides template derived from each overlay's .env.example, with all values commented out and grouped by service — copy to .env and uncomment only what you need to customize
  • Both files are tracked in the file registry and cleaned up on regeneration alongside other generated files

• Git-aware backup defaults — Backups are now skipped automatically when the target directory is inside a git repository (git already tracks history), and created by default when it is not

  • --backup flag forces a backup even inside a git repo
  • --no-backup flag suppresses a backup even outside a git repo
  • Auto-detection uses git rev-parse --git-dir; falls back to walking up the directory tree looking for a .git folder when the git command is unavailable

• Automatic .gitignore management — Generated projects now include tool-specific .gitignore entries automatically; overlay-provided patterns are merged into your project root .gitignore at generation time

  • Entries from each overlay are grouped under a labelled comment for easy identification
  • Running generation again never duplicates patterns already in your .gitignore
  • Overlay-provided ignore rules are always applied to the project root .gitignore (never to files inside .devcontainer/), keeping generated configuration isolated from your application's source ignores

• direnv overlay: secrets and env files are gitignored automatically — .envrc.local, .env, .env.local, and .direnv/ are now excluded from git immediately after generation — no need to start the container first

• Python overlay: workspace virtual environment (.venv) — The Python overlay now sets up a .venv virtual environment in your project root on container creation

  • VS Code automatically uses the workspace .venv as the Python interpreter
  • All project dependencies are installed into the venv (requirements.txt, requirements-dev.txt, pyproject.toml, setup.py)
  • .venv/, __pycache__/, *.pyc, and other Python artifacts are added to .gitignore automatically

• Preset parameterization — Customize presets with high-level choices without micro-managing individual overlays

  • New parameters field in preset definitions maps choices to sets of overlays
  • web-api preset now parameterized: database, cache, broker, observability slots
  • microservice preset now parameterized: broker, observability slots
  • Interactive questionnaire asks for each parameter value with descriptions and defaults
  • --preset <id> CLI flag pre-selects a preset and skips the preset selection prompt
  • --preset-param <key=value> CLI flag pre-fills parameter values (repeatable)
  • Pre-filled parameters skip their interactive prompt; unfilled ones are still asked
  • Invalid parameter values produce helpful error messages listing valid options
  • explain <preset-id> now shows parameters, options, defaults, and usage examples
  • Example: container-superposition init --preset web-api --preset-param broker=nats --preset-param observability=full

• plan --diff — Compare planned output vs existing .devcontainer/ configuration before applying changes

  • Shows files to be created, modified, unchanged, and removed
  • Generates colored unified diff for devcontainer.json (loads base template + applies overlay patches)
  • Detects overlay changes (added/removed) by comparing with existing superposition.json manifest
  • Detects port changes (added/removed) derived from overlay comparison
  • Lists preserved custom files in custom/ directory
  • --output <path> to compare against a custom existing config path (default: ./.devcontainer)
  • --diff-format json for machine-readable output (also via --json)
  • --diff-context <lines> to control diff context lines (default: 3)
  • Example: container-superposition plan --stack compose --overlays postgres,redis --diff