container-superposition 0.1.6 → 0.1.8

package/docs/specs/005-cuda-overlay/spec.md

@@ -0,0 +1,101 @@
+# Feature Specification: CUDA (NVIDIA GPU) Overlay
+
+**Feature Branch**: `copilot/add-cuda-overlay-for-gpu`
+**Created**: 2026-03-22
+**Status**: Final
+**Input**: Add a `cuda` overlay to enable NVIDIA GPU-accelerated workloads inside a dev container.
+
+## Review & Approval _(mandatory before implementation)_
+
+- **Spec Path**: `docs/specs/005-cuda-overlay/spec.md`
+- **Commit Status**: Committed
+- **Review Status**: Approved
+- **Implementation Gate**: No implementation code may begin until this spec is committed and reviewed.
+
+## User Scenarios & Testing _(mandatory)_
+
+### User Story 1 - GPU passthrough for ML/inference workloads (Priority: P1)
+
+A developer wants to run NVIDIA GPU-accelerated workloads (ML training, inference, CUDA compute) inside a dev container without manually configuring Docker runtime flags.
+
+**Why this priority**: GPU-accelerated dev containers require specific Docker runtime flags (`--gpus=all`) and VS Code devcontainer host requirements (`gpu: true`) that must be set correctly for the container to access the GPU. Without the overlay, users must add these manually and correctly every time.
+
+**Independent Test**: Select the `cuda` overlay, rebuild the container, and confirm that `nvidia-smi` exits 0 and reports the GPU correctly.
+
+**Acceptance Scenarios**:
+
+1. **Given** a user selects the `cuda` overlay, **When** the devcontainer is built, **Then** `devcontainer.json` includes `"runArgs": ["--gpus=all"]` and `"hostRequirements": {"gpu": true}`.
+2. **Given** the NVIDIA Container Toolkit is installed on the host, **When** the devcontainer starts, **Then** `nvidia-smi` is accessible inside the container.
+3. **Given** the container is running, **When** `setup.sh` executes, **Then** it reports whether `nvidia-smi` is available and prints a helpful message if it is not.
+
+---
+
+### User Story 2 - Conflict enforcement between cuda and rocm (Priority: P1)
+
+A user selects both `cuda` and `rocm` and expects the tool to report a conflict, because only one GPU compute framework can be active at a time.
+
+**Why this priority**: CUDA (NVIDIA) and ROCm (AMD) are mutually exclusive GPU compute frameworks. Allowing both would produce an incoherent configuration.
+
+**Independent Test**: Attempt to generate a devcontainer with both `cuda` and `rocm` selected and confirm the tool surfaces a conflict and blocks generation.
+
+**Acceptance Scenarios**:
+
+1. **Given** a user selects both `cuda` and `rocm`, **When** they run `container-superposition init`, **Then** the tool reports a conflict and prevents generation.
+2. **Given** `cuda` lists `rocm` in `conflicts`, **When** `rocm` is added in the future, **Then** `rocm` must also list `cuda` in its `conflicts` (bidirectional enforcement). Note: `rocm` does not exist yet; when it is added the reciprocal conflict must be declared in `overlays/rocm/overlay.yml`.
+
+---
+
+## Design
+
+### overlay.yml
+
+```yaml
+id: cuda
+name: CUDA (NVIDIA GPU)
+description: NVIDIA CUDA libraries and GPU passthrough for containerized ML/inference workloads
+category: dev
+supports: []
+requires: []
+suggests: []
+conflicts:
+    - rocm
+tags:
+    - gpu
+    - cuda
+    - nvidia
+    - ml
+    - inference
+ports: []
+```
+
+### devcontainer.patch.json
+
+Set `runArgs` for GPU passthrough and `hostRequirements` to signal GPU need:
+
+```json
+{
+    "runArgs": ["--gpus=all"],
+    "hostRequirements": { "gpu": true }
+}
+```
+
+### setup.sh
+
+- Check whether `nvidia-smi` is reachable inside the container.
+- Print a helpful message if it is not (host driver / toolkit not configured).
+
+### verify.sh
+
+- Assert `nvidia-smi` exits 0 (used by the `doctor` command).
+
+### README.md
+
+- Clear prerequisites section (host drivers, NVIDIA Container Toolkit).
+- Troubleshooting tips for common failure modes.
+- Note that the overlay does not replace or install host drivers.
+
+## Out of Scope
+
+- Installing or replacing host NVIDIA drivers.
+- Guaranteeing version alignment between CUDA user-space libraries and the host kernel module.
+- ROCm (AMD GPU) support — tracked separately.

package/docs/specs/006-rocm-overlay/spec.md

@@ -0,0 +1,109 @@
+# Feature Specification: ROCm (AMD GPU) Overlay
+
+**Feature Branch**: `copilot/add-rocm-overlay`
+**Created**: 2026-03-22
+**Status**: Accepted
+**Input**: Add a `rocm` overlay to enable AMD GPU-accelerated workloads inside a dev container.
+
+## Review & Approval _(mandatory before implementation)_
+
+- **Spec Path**: `docs/specs/006-rocm-overlay/spec.md`
+- **Commit Status**: Committed
+- **Review Status**: Approved
+- **Implementation Gate**: No implementation code may begin until this spec is committed and reviewed.
+
+## Overview
+
+Add a `rocm` overlay to enable AMD GPU-accelerated workloads inside a dev container using the ROCm open software platform.
+
+> **Note:** ROCm-in-container is a supported but more fragile path than CUDA. It depends heavily on the host kernel version, AMD driver stack, specific device support, and container runtime configuration. Treat this as a separate supported profile — not a drop-in equivalent of CUDA.
+
+## User Scenarios & Testing _(mandatory)_
+
+### User Story 1 - AMD GPU passthrough for ML/inference workloads (Priority: P1)
+
+1. **Given** a user selects the `rocm` overlay, **When** the devcontainer is built, **Then** `devcontainer.json` includes `"runArgs": ["--device=/dev/kfd", "--device=/dev/dri", "--group-add=video", "--group-add=render"]`.
+2. **Given** the AMD GPU drivers and ROCm runtime are installed on the host, **When** the devcontainer starts, **Then** `rocm-smi` is accessible inside the container.
+3. **Given** the container is running, **When** `setup.sh` executes, **Then** it reports whether `rocm-smi` is available and prints a helpful message if it is not.
+4. **Given** `rocm-smi` is not available, **When** `verify.sh` executes, **Then** it exits 1 for the `doctor` command.
+
+---
+
+## Prerequisites (host-side — out of scope for this overlay)
+
+1. Supported AMD GPU hardware (RDNA 2+, most CDNA — check [ROCm hardware support matrix](https://rocm.docs.amd.com/en/latest/compatibility/compatibility-matrix.html))
+2. AMD GPU drivers (`amdgpu`) installed on the host
+3. ROCm runtime installed on the host (or the container image bundles it)
+4. User added to the `render` and `video` groups, or appropriate device permissions set
+5. `/dev/kfd` and `/dev/dri` devices accessible in the container
+
+## Design
+
+### overlay.yml
+
+```yaml
+id: rocm
+name: ROCm (AMD GPU)
+description: AMD ROCm libraries and GPU passthrough for containerized ML/inference workloads
+category: dev
+supports: []
+requires: []
+suggests: []
+conflicts:
+    - cuda
+tags:
+    - dev
+    - gpu
+    - rocm
+    - amd
+    - ml
+    - inference
+ports: []
+```
+
+### devcontainer.patch.json
+
+Set `runArgs` for AMD GPU device passthrough:
+
+```json
+{
+    "runArgs": ["--device=/dev/kfd", "--device=/dev/dri", "--group-add=video", "--group-add=render"]
+}
+```
+
+- `/dev/kfd` — AMD Kernel Fusion Driver; required for ROCm compute
+- `/dev/dri` — Direct Rendering Infrastructure; gives access to GPU render nodes
+- `--group-add=video` and `--group-add=render` — add the container user to the groups that own the GPU device nodes
+
+### setup.sh
+
+- Check whether `rocm-smi` or `rocminfo` is reachable inside the container.
+- Print a helpful message if neither is found (host driver / ROCm not configured).
+
+### verify.sh
+
+- Assert `rocm-smi` exits 0 (used by the `doctor` command).
+
+### README.md
+
+Must include:
+
+- Prominent prerequisites section
+- Known limitations (kernel version coupling, device node names may vary)
+- ROCm framework wheels (PyTorch ROCm, TensorFlow ROCm)
+- Troubleshooting section
+- Link to ROCm compatibility matrix
+- Clear note that this overlay does not replace host drivers
+
+## Relationship to CUDA Overlay
+
+- `cuda` and `rocm` must list each other in `conflicts` (bidirectional, per project rules)
+- The `cuda` overlay already declares `rocm` in its `conflicts`
+- CUDA is considered the primary GPU path; ROCm is a supported secondary path
+
+## Known Constraints and Caveats
+
+- ROCm version support is tightly coupled to kernel and driver versions
+- Device node names (`/dev/dri/renderD128`) may differ per host
+- Some frameworks publish separate ROCm wheels
+- Less forgiving than CUDA during setup — detailed troubleshooting is essential

package/docs/specs/007-init-project-file/spec.md

@@ -0,0 +1,66 @@
+# Feature Specification: `init --project-file`
+
+**Feature Branch**: `copilot/sub-pr-121`
+**Created**: 2026-03-23
+**Status**: Final
+**Input**: Extend the `init` command with a `--project-file` flag that persists the chosen init configuration into a repository-root project config file (creating `.superposition.yml` by default or updating an existing supported project config), aligning init runs with the project-config workflow.
+
+## Review & Approval _(mandatory before implementation)_
+
+- **Spec Path**: `docs/specs/007-init-project-file/spec.md`
+- **Commit Status**: Committed
+- **Review Status**: Approved
+- **Implementation Gate**: No implementation code may begin until this spec is committed and reviewed.
+
+## Summary
+
+Allow `container-superposition init` to optionally write a repository-root
+project config file (`.superposition.yml` by default, or the existing supported
+project config path when one already exists) alongside the normal init output.
+
+## Requirements
+
+- `init` MUST accept a `--project-file` flag.
+- When `--project-file` is set, `init` MUST write a repository-root project
+  config that reflects the final selected configuration for that run.
+- If the repository already contains exactly one supported project config file,
+  `init --project-file` MUST update that file instead of creating a second one.
+- If no project config file exists, `init --project-file` MUST write
+  `.superposition.yml` at the repository root.
+- The written project config MUST include supported fields represented by the
+  final init answers, including stack, base image, overlays, output path,
+  target, minimal mode, editor profile, preset, and preset choices.
+- `init --project-file` MUST continue to write `superposition.json` the same way
+  current `init` runs do.
+- Project config write errors MUST NOT suppress devcontainer generation success; they MUST be reported separately.
+
+## User Scenarios & Testing _(mandatory)_
+
+### User Story 1 - Write project config alongside devcontainer generation (Priority: P1)
+
+A developer wants to run `init` once and have both a `.devcontainer/` folder and a root-level project config file created, so they can commit the project config and regenerate consistently later.
+
+**Why this priority**: The `--project-file` flag is the primary new capability. Without it working correctly for a fresh project, the feature has no value.
+
+**Independent Test**: Run `init --project-file` in a directory with no existing project config, then confirm that `.superposition.yml` is created at the repo root and reflects the chosen stack and overlays.
+
+**Acceptance Scenarios**:
+
+1. **Given** a repository with no project config file, **When** the user runs `init --project-file`, **Then** `.superposition.yml` is created at the repository root with the selected stack, base image, overlays, and other init options.
+2. **Given** a repository with an existing `.superposition.yml`, **When** the user runs `init --project-file`, **Then** the existing file is updated (not a new file created) to reflect the newly selected configuration.
+3. **Given** the project config write fails (e.g., permission error), **When** `init --project-file` is run, **Then** the devcontainer generation still completes successfully and a clear error message is shown for the project-file failure only.
+
+---
+
+### User Story 2 - Update existing project config (Priority: P2)
+
+A developer has an existing `superposition.yml` and wants to update it to reflect a changed overlay selection after re-running `init`.
+
+**Why this priority**: Round-trip consistency (init → project config → regen) is the main value of the project-config workflow.
+
+**Independent Test**: Create a `superposition.yml`, run `init --project-file` with different overlays, and confirm that the file is updated rather than a second file being created.
+
+**Acceptance Scenarios**:
+
+1. **Given** a repository with exactly one supported project config file, **When** the user runs `init --project-file` with new overlay selections, **Then** only that existing file is updated and no second project config is created.
+2. **Given** two supported project config files exist simultaneously, **When** the user runs `init --project-file`, **Then** the command prints an error explaining that only one project config file should exist and does not proceed with the write.

package/docs/specs/007-target-aware-generation/spec.md

@@ -0,0 +1,126 @@
+# Feature Specification: Target-Aware Generation
+
+**Feature Branch**: `copilot/feat-target-aware-generation`  
+**Created**: 2026-03-23  
+**Status**: Final  
+**Input**: Issue [feat] Target-aware generation — produce workspace artifacts and guidance for codespaces, gitpod, and devpod
+
+## Review & Approval _(mandatory before implementation)_
+
+- **Spec Path**: `docs/specs/007-target-aware-generation/spec.md`
+- **Commit Status**: Committed
+- **Review Status**: APPROVED
+- **Implementation Gate**: No implementation code may begin until this spec is committed and reviewed.
+
+## User Scenarios & Testing _(mandatory)_
+
+### User Story 1 — Generate codespaces artifacts (Priority: P1)
+
+A user generates with `--target codespaces` and expects to receive Codespaces-specific files and
+guidance alongside the normal devcontainer output.
+
+**Acceptance:**
+
+1. `--target codespaces` → `devcontainer.json` extended with `hostRequirements`, `CODESPACES.md` written to `.devcontainer/`.
+2. `--target local` or no `--target` → no `CODESPACES.md`, no `hostRequirements` in devcontainer.
+
+### User Story 2 — Generate gitpod artifacts (Priority: P1)
+
+A user generates with `--target gitpod` and expects a `.gitpod.yml` in the project root and
+setup guidance inside `.devcontainer/`.
+
+**Acceptance:**
+
+1. `--target gitpod` → `.gitpod.yml` at project root with tasks and port exposures from selected overlays; `GITPOD.md` written to `.devcontainer/`.
+2. `--target local` → no `.gitpod.yml`, no `GITPOD.md`.
+
+### User Story 3 — Generate devpod artifacts (Priority: P1)
+
+A user generates with `--target devpod` and expects a `devpod.yaml` at the project root and
+setup guidance inside `.devcontainer/`.
+
+**Acceptance:**
+
+1. `--target devpod` → `devpod.yaml` at project root; `DEVPOD.md` written to `.devcontainer/`.
+2. `--target local` → no `devpod.yaml`, no `DEVPOD.md`.
+
+### User Story 4 — Local generation unchanged (Priority: P1)
+
+When a user generates without specifying a target, or with `--target local`, the output must
+not contain any non-local artifacts.
+
+**Acceptance:**
+
+1. No `--target` flag → output identical to current behavior; no new files written.
+2. `--target local` (explicit) → same output as omitting `--target`.
+
+### User Story 5 — Regeneration from manifest with target (Priority: P2)
+
+A user regenerates from an existing `superposition.json` that includes `"target": "gitpod"` and
+expects the same Gitpod-specific artifacts without being prompted again.
+
+**Acceptance:**
+
+1. Manifest with `target: gitpod` → regen produces `.gitpod.yml` and `GITPOD.md`.
+2. Manifest with no `target` or `target: local` → regen produces no target-specific artifacts.
+
+### User Story 6 — Target switching cleans up stale artifacts (Priority: P2)
+
+A user regenerates with a different `--target` value and expects the previous target's
+project-root artifacts to be removed.
+
+**Acceptance:**
+
+1. Previous run was `--target gitpod` (`.gitpod.yml` exists); regeneration with `--target codespaces` → `.gitpod.yml` removed, `CODESPACES.md` written.
+2. Previous run was `--target devpod`; regeneration with `--target local` → `devpod.yaml` removed.
+
+## Technical Design
+
+### `TargetRule` interface
+
+A `TargetRule` encapsulates everything about generating artifacts for one deployment target:
+
+```typescript
+interface TargetRule {
+    target: DeploymentTarget;
+    /** Extra fields merged into devcontainer.json */
+    devcontainerPatch(context: TargetRuleContext): Partial<DevContainer>;
+    /** Files to write; keys are relative to outputPath, '../<name>' writes to project root */
+    generateFiles(context: TargetRuleContext): Map<string, string>;
+    /** All relative paths owned by this rule (for stale-cleanup on target switch) */
+    ownedFiles(): string[];
+}
+```
+
+### Per-target rules
+
+| Target       | devcontainer.json change | Files in `.devcontainer/` | Files at project root |
+| ------------ | ------------------------ | ------------------------- | --------------------- |
+| `local`      | none                     | none                      | none                  |
+| `codespaces` | `hostRequirements`       | `CODESPACES.md`           | none                  |
+| `gitpod`     | none                     | `GITPOD.md`               | `.gitpod.yml`         |
+| `devpod`     | none                     | `DEVPOD.md`               | `devpod.yaml`         |
+
+### `SuperpositionManifest` update
+
+Add `target?: DeploymentTarget` so regeneration reproduces the correct artifacts without
+re-prompting.
+
+### Stale-artifact cleanup
+
+On each generation, before writing new target artifacts:
+
+1. Read existing `superposition.json` from `outputPath` (if it exists).
+2. If `manifest.target !== answers.target`, identify previous target's owned project-root
+   files (e.g., `.gitpod.yml`) and remove them from the project root.
+
+The `.devcontainer/`-local files are already handled by `cleanupStaleFiles` via `FileRegistry`.
+
+## Functional Requirements (from issue)
+
+- **FR-001**: Target is a real generation input that changes produced artifacts.
+- **FR-002**: `codespaces`, `gitpod`, `devpod` produce target-specific workspace artifacts.
+- **FR-003**: `local` (explicit or default) produces no additional artifacts.
+- **FR-009**: Regeneration from manifest reproduces target-aware output automatically.
+- **FR-010**: Target switch between runs removes stale artifacts from the previous target.
+- **FR-011**: Backward compatible — manifests without `target` or with `target: local` unchanged.

package/docs/specs/008-project-file-canonical/spec.md

@@ -0,0 +1,83 @@
+---
+Feature Branch: copilot/make-superposition-yml-canonical-input
+Created: 2026-03-26
+Status: Implementing
+Input: GitHub issue #134
+---
+
+# Spec: Make superposition.yml the Canonical Input
+
+## Overview
+
+Make `superposition.yml` (the project config file) the required, canonical input for all
+generation and regeneration flows. `superposition.json` (the manifest) becomes an output-only
+artifact — a generated receipt, not an input source.
+
+## Motivation
+
+Three entry points currently disagree on which file is authoritative, creating user confusion
+and dead code paths. The newest code path (`generate`) already writes `superposition.yml`
+first. This spec promotes that pattern to all entry points.
+
+## Behavioral Changes
+
+### `init` — Always writes `superposition.yml`
+
+- Remove `--project-file` flag; writing the project config is now the default.
+- Add `--no-scaffold` flag to skip generating `.devcontainer/` (for project-file-only runs).
+- Scaffold (`.devcontainer/` generation) remains the default for backward compatibility.
+- The project file is written before scaffolding; a scaffold failure does not lose the config.
+
+### `regen` — Reads `superposition.yml` only
+
+- Default input: the project config file auto-discovered in the repository root.
+- `--from-manifest <path>` is retained as a **deprecated hidden flag** that emits a warning
+  pointing toward `cs migrate`. Existing CI scripts that rely on it will still work but
+  receive a deprecation notice.
+- If no project file exists and `superposition.json` is present: error with actionable
+  migration guidance: `Run 'cs migrate' to create a project file from your existing manifest.`
+- If neither file exists: error with creation guidance.
+
+### `superposition.json` — Output only
+
+- Still written by `composeDevContainer` / `generateManifestOnly` as before.
+- No longer read as a generation input in the standard flow.
+- Still read by `doctor` for diagnostics and drift detection.
+
+## New Commands
+
+### `cs migrate`
+
+One-time migration from manifest-only repositories:
+
+1. Discovers or accepts `--from-manifest <path>` to locate `superposition.json`.
+2. Loads and validates the manifest (with auto-migration for old versions).
+3. Converts manifest to `ProjectConfigSelection` via the existing
+   `buildAnswersFromManifest → mergeAnswers → buildProjectConfigSelectionFromAnswers` pipeline.
+4. Discovers the output path for the project file (uses existing file if present, otherwise
+   defaults to `.superposition.yml`); `--force` to overwrite.
+5. Writes the project config YAML.
+6. Prints a success message with next-step guidance (`regen` to regenerate).
+
+## `doctor` Drift Detection
+
+Once the project file is canonical, `doctor` can compare the two files:
+
+- Load project file overlays (via `loadProjectConfig`).
+- Load last-generated manifest overlays (via existing manifest loading).
+- Report a new `project-file-drift` finding when the overlay sets differ.
+- Suggest `regen` to reconcile.
+
+## Migration Considerations
+
+| Repo state                    | Impact                            | Action                           |
+| ----------------------------- | --------------------------------- | -------------------------------- |
+| Has `superposition.yml` only  | None — already correct            | —                                |
+| Has `superposition.json` only | `regen` errors                    | Run `cs migrate` once            |
+| Has both (consistent)         | None — regen prefers project file | —                                |
+| CI using `--from-manifest`    | Warning on each run               | Switch to `cs migrate` + `regen` |
+
+## Review & Approval Gate
+
+Implementation proceeds with this spec committed. No further approval required for the
+behavioral changes listed above.

package/docs/specs/009-project-env/spec.md

@@ -0,0 +1,147 @@
+# Feature Specification: Unified Project-Level Environment Variables
+
+**Feature Branch**: `codex/project-env`
+**Created**: 2026-03-29
+**Status**: Implementing
+**Input**: User request
+
+## Review & Approval _(mandatory before implementation)_
+
+- **Spec Path**: `docs/specs/009-project-env/spec.md`
+- **Commit Status**: Committed
+- **Review Status**: Pending
+- **Implementation Gate**: No implementation code may begin until this spec is committed and reviewed.
+
+## User Scenarios & Testing _(mandatory)_
+
+### User Story 1 — Define environment variables once for plain stack (Priority: P1)
+
+A developer adds an `env:` block to `superposition.yml` on a `plain` stack and expects the
+variables to appear in `devcontainer.json → remoteEnv` after regeneration.
+
+**Why this priority**: The most common use case is a plain-stack project needing a handful of
+environment variables visible inside the devcontainer without manually editing JSON files.
+
+**Independent Test**: Create a `superposition.yml` with `stack: plain` and `env: {APP_NAME: my-app}`,
+run `regen`, and confirm that `devcontainer.json` contains `"remoteEnv": {"APP_NAME": "my-app"}`.
+
+**Acceptance Scenarios**:
+
+1. **Given** `superposition.yml` has `env: {APP_NAME: my-app}`, **When** generation runs with `stack: plain`, **Then** `devcontainer.json` includes `remoteEnv.APP_NAME: my-app`.
+2. **Given** `env:` uses the long form (`{value: "foo", target: auto}` — an object with a required `value` string and optional `target` routing hint), **When** generation runs with `stack: plain`, **Then** the variable is written to `remoteEnv` identical to the string shorthand.
+
+---
+
+### User Story 2 — Define environment variables once for compose stack (Priority: P1)
+
+A developer adds an `env:` block to `superposition.yml` on a `compose` stack and expects the
+variables to appear in `docker-compose.yml → services.devcontainer.environment` after regeneration.
+
+**Why this priority**: Compose-stack users currently must split env configuration across
+`customizations.devcontainerPatch.remoteEnv` and `customizations.dockerComposePatch`, which is
+error-prone and hard to discover.
+
+**Independent Test**: Create a `superposition.yml` with `stack: compose` and
+`env: {DB_HOST: postgres}`, run `regen`, and confirm the variable appears under
+`services.devcontainer.environment` in the generated `docker-compose.yml`.
+
+**Acceptance Scenarios**:
+
+1. **Given** `superposition.yml` has `env: {DB_HOST: postgres}` on a compose stack, **When** generation runs, **Then** `docker-compose.yml` contains `services.devcontainer.environment.DB_HOST: postgres`.
+2. **Given** `target: composeEnv` is specified, **When** generation runs with `stack: plain`, **Then** generation errors with a clear message about compose-only targets.
+
+---
+
+### User Story 3 — Explicit target overrides auto-routing (Priority: P2)
+
+A developer uses `target: remoteEnv` on a compose-stack project to force a variable into
+`devcontainer.json` instead of `docker-compose.yml`.
+
+**Why this priority**: Power users occasionally need fine-grained control over where a variable
+lands, especially for VS Code-specific settings that must be in `remoteEnv`.
+
+**Independent Test**: Set `target: remoteEnv` on a variable in a compose-stack project, run
+`regen`, and confirm the variable is in `devcontainer.json → remoteEnv` (not in
+`docker-compose.yml → services.devcontainer.environment`).
+
+**Acceptance Scenarios**:
+
+1. **Given** `{value: "bar", target: remoteEnv}` in `env:` on a compose stack, **When** generation runs, **Then** the variable is written to `devcontainer.json → remoteEnv` only.
+
+---
+
+## Overview
+
+Add a first-class `env` field to `superposition.yml` so a project can define
+environment variables once and have them land in the correct generated output:
+
+- `remoteEnv` for `plain` stacks
+- `services.devcontainer.environment` in `docker-compose.yml` for `compose` stacks
+
+This removes the need to split simple container environment variables across
+`customizations.devcontainerPatch.remoteEnv` and
+`customizations.dockerComposePatch`.
+
+## Project File Shape
+
+```yaml
+env:
+    APP_NAME: my-app
+    API_BASE_URL:
+        value: ${API_BASE_URL:-http://localhost:3000}
+        target: auto
+```
+
+Rules:
+
+- `env` is a map keyed by variable name.
+- A value may be:
+    - a string shorthand, equivalent to `{ value: "<string>", target: auto }`
+    - an object with:
+        - `value: string` required
+        - `target: auto | remoteEnv | composeEnv` optional, default `auto`
+
+## Generation Behavior
+
+### `target: auto`
+
+- `plain` stack: write the variable to `devcontainer.json -> remoteEnv`
+- `compose` stack: write the variable to
+  `docker-compose.yml -> services.devcontainer.environment`
+
+### Explicit targets
+
+- `remoteEnv`: always write to `devcontainer.json -> remoteEnv`
+- `composeEnv`: write to `docker-compose.yml -> services.devcontainer.environment`
+  and error on non-compose stacks
+
+### Precedence
+
+- Project-level `env` is applied before `customizations.devcontainerPatch` and
+  `customizations.dockerComposePatch`.
+- Custom patch files remain the escape hatch and may override project-level env.
+
+## Root `.env` Expansion Bridge
+
+When a compose-targeted project env value references `${NAME}` or
+`${NAME:-default}`, generation should preserve that expression in
+`docker-compose.yml` and also mirror matching keys from the project root `.env`
+into `.devcontainer/.env`.
+
+This allows:
+
+1. the repository root `.env` to remain the human-edited source of truth
+2. Docker Compose to resolve variables from `.devcontainer/.env`
+3. generated `docker-compose.yml` to avoid embedding resolved secret values
+
+Bridge rules:
+
+- only referenced variable names are copied
+- existing unrelated entries in `.devcontainer/.env` are preserved
+- missing root variables are not invented; Docker Compose defaults still work
+
+## Non-Goals
+
+- No new syntax for targeting arbitrary non-devcontainer services
+- No replacement for advanced compose patches; those remain under
+  `customizations.dockerComposePatch`