container-superposition 0.1.7 → 0.1.8

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`

package/docs/specs/010-compose-env-materialization/spec.md

@@ -0,0 +1,130 @@
+# Feature Specification: Compose Env Materialization and Env Template Naming
+
+**Feature Branch**: `codex/compose-env-materialization`
+**Created**: 2026-03-29
+**Status**: Implementing
+**Input**: User request
+
+## Review & Approval _(mandatory before implementation)_
+
+- **Spec Path**: `docs/specs/010-compose-env-materialization/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 — Compose env values materialize into .devcontainer/.env (Priority: P1)
+
+A developer sets concrete env values in `superposition.yml` on a `compose` stack and expects
+them to be written to `.devcontainer/.env` (not embedded in `docker-compose.yml`) so that
+secrets are not committed to source control inside generated YAML.
+
+**Why this priority**: Embedding resolved values directly in `docker-compose.yml` would expose
+secrets or host-specific values in generated files that are typically committed to source control.
+Materializing them into `.devcontainer/.env` keeps generated config template-only.
+
+**Independent Test**: Set `env: {SECRET_KEY: supersecret}` on a compose-stack project, run
+`regen`, and confirm: (a) `docker-compose.yml` contains
+`services.devcontainer.environment.SECRET_KEY: ${SECRET_KEY}`, (b) `.devcontainer/.env` contains
+`SECRET_KEY=supersecret`, and (c) the literal value `supersecret` does not appear in
+`docker-compose.yml`.
+
+**Acceptance Scenarios**:
+
+1. **Given** `env: {API_KEY: abc123}` on a compose stack, **When** generation runs, **Then** `docker-compose.yml` has `API_KEY: ${API_KEY}` and `.devcontainer/.env` has `API_KEY=abc123`.
+2. **Given** `env: {NAME: ${NAME:-default}}`, **When** generation runs with a root `.env` that sets `NAME=prod`, **Then** `.devcontainer/.env` receives `NAME=prod`.
+3. **Given** `env: {NAME: ${NAME}}` and no root `.env` entry for `NAME`, **When** generation runs, **Then** `.devcontainer/.env` does not include `NAME=` and Docker Compose shell fallback still works.
+
+---
+
+### User Story 2 — Configure env template entries with clearly named project-file field (Priority: P1)
+
+A developer updates their `superposition.yml` to use `customizations.envTemplate` (instead of
+the previously named `customizations.environment`) and expects the generated `.env.example`
+content to be identical to what the old field produced.
+
+**Why this priority**: The existing `environment` key is misleading — it writes to `.env.example`
+(a template), not to the runtime container environment. Renaming it clarifies intent and prevents
+confusion with the new `env:` field.
+
+**Independent Test**: Replace `customizations.environment` with `customizations.envTemplate` in a
+project file, run `regen`, and confirm the generated `.env.example` is byte-for-byte identical to
+the output produced with the old key.
+
+**Acceptance Scenarios**:
+
+1. **Given** `customizations.envTemplate: {FOO: bar}`, **When** generation runs, **Then** `.devcontainer/.env.example` contains `FOO=bar`.
+2. **Given** `customizations.environment: {FOO: bar}` (deprecated alias), **When** generation runs, **Then** `.devcontainer/.env.example` still contains `FOO=bar` (backward-compatible).
+3. **Given** a project file using `environment`, **When** it is read by the project loader, **Then** a deprecation warning is emitted directing users to rename the key.
+
+---
+
+### User Story 3 — remoteEnv wiring for compose env entries (Priority: P2)
+
+A developer on a compose stack expects that compose-targeted env variables are also accessible
+via `${containerEnv:KEY}` in `devcontainer.json → remoteEnv` so VS Code settings and
+extensions can reference them.
+
+**Why this priority**: Without a `remoteEnv` entry, VS Code extensions that read `process.env`
+at startup may not see the variable, even though the container process will.
+
+**Independent Test**: Set a compose-stack env variable, run `regen`, and confirm
+`devcontainer.json → remoteEnv` includes `KEY: ${containerEnv:KEY}` alongside the
+`docker-compose.yml` entry.
+
+**Acceptance Scenarios**:
+
+1. **Given** `env: {DB_URL: postgres://localhost/dev}` on a compose stack, **When** generation runs, **Then** `devcontainer.json` contains `remoteEnv.DB_URL: ${containerEnv:DB_URL}`.
+
+---
+
+## Overview
+
+Refine project-file environment semantics so compose-based projects do not
+embed resolved env values directly in generated `docker-compose.yml` or
+`devcontainer.json`.
+
+At the same time, rename the project-file field
+`customizations.environment` to `customizations.envTemplate` to make its
+purpose explicit: it writes template variables to `.env.example`, not runtime
+container environment.
+
+## Behavior
+
+### `env:` on `stack: compose`
+
+For compose-targeted project env entries:
+
+1. Materialize concrete values into `.devcontainer/.env`
+2. Write `docker-compose.yml -> services.devcontainer.environment.KEY: ${KEY}`
+3. Write `devcontainer.json -> remoteEnv.KEY: ${containerEnv:KEY}`
+
+This keeps generated config free of resolved secret values while still making
+the variables available inside the devcontainer.
+
+### Value Resolution
+
+- literals are written as-is to `.devcontainer/.env`
+- `${NAME}` resolves from the repository root `.env` when present
+- `${NAME:-default}` resolves from the repository root `.env`, otherwise uses
+  the inline default
+- unresolved `${NAME}` values are omitted from `.devcontainer/.env` so shell
+  environment fallback remains possible
+
+### `env:` on `stack: plain`
+
+No change: values still land directly in `devcontainer.json -> remoteEnv`.
+
+## `customizations.envTemplate`
+
+- `customizations.envTemplate` is the canonical project-file field for values
+  that should be written to `.env.example`
+- `customizations.environment` is retained as a deprecated backward-compatible
+  alias
+- serializers should emit `envTemplate`
+
+## Non-Goals
+
+- no change to `.devcontainer/custom/environment.env`
+- no support for targeting arbitrary compose sidecar services from `env:`

package/docs/specs/011-overlay-parameters/spec.md

@@ -0,0 +1,235 @@
+# Feature Specification: Overlay Parameters with Safe Substitution
+
+**Feature Branch**: `011-overlay-parameters`
+**Created**: 2026-03-30
+**Status**: Final
+**Input**: Issue — Introduce overlay parameters with safe, namespaced substitution — no conflicts with Docker/shell/VS Code
+
+## Review & Approval _(mandatory before implementation)_
+
+- **Spec Path**: `docs/specs/011-overlay-parameters/spec.md`
+- **Commit Status**: Committed
+- **Review Status**: APPROVED
+- **Implementation Gate**: No implementation code may begin until this spec is committed and reviewed.
+
+## Summary
+
+Add first-class **parameters** to overlays so users can configure environment-specific values
+(credentials, database names, ports, paths) without forking overlays or hand-editing generated
+files.
+
+Parameters use the `{{cs.PARAM_NAME}}` substitution syntax, which does not collide with Docker
+Compose (`${VAR}`), shell (`$VAR`, `${VAR}`), VS Code (`${localWorkspaceFolder}`), or GitHub
+Actions (`${{ }}`).
+
+This is **parameter substitution only** — no loops, no conditionals, no embedded logic.
+If `string.replace()` can't do it, it doesn't belong here.
+
+---
+
+## Design
+
+### Syntax
+
+```
+{{cs.PARAM_NAME}}
+```
+
+- **Safe**: does not collide with `${VAR}` (Docker/shell), `${env:VAR}` (VS Code), or `${{ }}` (GitHub Actions)
+- **Consistent**: extends the existing `{{parameters.<key>.id}}` preset convention
+- **Explicit**: clearly owned by container-superposition
+- **Simple**: resolved by a single `string.replace()` regex, no parser needed
+
+### Overlay parameter declarations (`overlay.yml`)
+
+Overlays declare parameters in `overlay.yml`:
+
+```yaml
+id: postgres
+name: PostgreSQL
+category: database
+parameters:
+    POSTGRES_DB:
+        description: Database name
+        default: app
+    POSTGRES_USER:
+        description: Database user
+        default: postgres
+    POSTGRES_PASSWORD:
+        description: Database password
+        default: postgres
+        sensitive: true
+    POSTGRES_PORT:
+        description: Host-mapped port
+        default: '5432'
+```
+
+Fields:
+
+- `description` (required) — human-readable explanation shown in interactive prompts
+- `default` (optional) — default value; absence marks the parameter as _required_
+- `sensitive` (optional, boolean) — indicates secrets; hidden in interactive prompts and redacted from plan output
+
+### Usage in overlay files
+
+Overlay patches and compose files reference parameters using `{{cs.PARAM_NAME}}`:
+
+```json
+{
+    "remoteEnv": {
+        "DATABASE_URL": "postgres://{{cs.POSTGRES_USER}}:{{cs.POSTGRES_PASSWORD}}@postgres:5432/{{cs.POSTGRES_DB}}"
+    }
+}
+```
+
+```yaml
+# docker-compose.yml — generation-time substitution coexists with Docker runtime substitution
+services:
+    postgres:
+        environment:
+            POSTGRES_DB: '{{cs.POSTGRES_DB}}'
+            POSTGRES_USER: '{{cs.POSTGRES_USER}}'
+            POSTGRES_PASSWORD: '{{cs.POSTGRES_PASSWORD}}'
+        ports:
+            - '${POSTGRES_PORT:-{{cs.POSTGRES_PORT}}}:5432'
+```
+
+### Parameters in `superposition.yml`
+
+```yaml
+overlays:
+    - postgres
+    - redis
+
+parameters:
+    POSTGRES_DB: myapp
+    POSTGRES_USER: veggerby
+    REDIS_PORT: '6380'
+```
+
+### Resolution order (highest wins)
+
+1. CLI overrides (`--param POSTGRES_DB=foo`)
+2. Project file (`superposition.yml` `parameters:` section)
+3. Overlay defaults (`overlay.yml` `parameters[KEY].default`)
+
+### Validation rules
+
+| Condition                                                  | Behaviour                             |
+| ---------------------------------------------------------- | ------------------------------------- |
+| Missing required parameter (no default, no value supplied) | **Hard error** before generation      |
+| Unknown parameter (not declared by any selected overlay)   | **Warning** (proceed)                 |
+| Unresolved `{{cs.*}}` in final output                      | **Hard error** (catch-all safety net) |
+
+### Pass-through guarantee
+
+The substitution engine MUST NOT touch:
+
+- Docker Compose expressions: `${VAR}`, `${VAR:-default}`, `$VAR`
+- VS Code/devcontainer variables: `${localWorkspaceFolder}`, `${containerWorkspaceFolder}`, `${env:VAR}`
+- GitHub Actions expressions: `${{ github.* }}`
+- Shell variables in scripts: `$FOO`, `${FOO}`, `${FOO:-default}`
+
+Only tokens matching exactly `{{cs.[A-Z0-9_]+}}` are substituted.
+
+---
+
+## Implementation Scope
+
+### Types (`tool/schema/types.ts`)
+
+```typescript
+export interface OverlayParameterDefinition {
+    description: string;
+    default?: string;
+    sensitive?: boolean;
+}
+```
+
+Add to `OverlayMetadata`:
+
+```typescript
+parameters?: Record<string, OverlayParameterDefinition>;
+```
+
+Add to `ProjectConfigSelection`:
+
+```typescript
+parameters?: Record<string, string>;
+```
+
+Add to `QuestionnaireAnswers`:
+
+```typescript
+overlayParameters?: Record<string, string>;
+```
+
+### Parameter engine (`tool/utils/parameters.ts`)
+
+- `collectOverlayParameters(overlayIds, allOverlayDefs)` — collect all declared parameters from selected overlays with their defaults
+- `resolveParameters(declared, supplied)` — apply resolution order, return resolved map and errors
+- `substituteParameters(content, resolved)` — replace `{{cs.KEY}}` tokens in a string
+- `validateFinalContent(content)` — error if any `{{cs.*}}` remain after substitution
+
+### Composer (`tool/questionnaire/composer.ts`)
+
+After all overlay files are read and before they are written to disk:
+
+1. Collect parameter declarations from selected overlays
+2. Merge with `answers.overlayParameters` values
+3. Validate — error on missing required parameters
+4. Apply substitution to all file content strings (devcontainer.json, docker-compose.yml, .env.example, scripts)
+5. Validate — error on any unresolved `{{cs.*}}` tokens remaining in output
+
+### Project config (`tool/schema/project-config.ts`)
+
+Parse `parameters:` YAML map as `Record<string, string>` (string values only).
+Propagate to `selection.parameters` → `answers.overlayParameters`.
+
+### Init (`scripts/init.ts`)
+
+When overlay declares parameters, interactive questionnaire prompts for values.
+Sensitive parameters use masked input. Pre-filled with defaults.
+
+---
+
+## Non-goals
+
+- Conditional logic (`{{if ...}}`)
+- Loops or iteration
+- Programmable overlays or JS execution
+- Dynamic file generation
+- Templating engine integration (Handlebars, Jinja, EJS, etc.)
+
+---
+
+## User Scenarios & Testing _(mandatory)_
+
+### User Story 1 — Postgres with custom database name (P1)
+
+A user scaffolds a compose stack with the postgres overlay and wants their database named `myapp`
+instead of the default `devdb`.
+
+**Acceptance scenarios**:
+
+1. **Given** a `superposition.yml` with `parameters: { POSTGRES_DB: myapp }`, **When** generation runs, **Then** the generated `.devcontainer/docker-compose.yml` and `remoteEnv` in `devcontainer.json` reference `myapp` instead of `devdb`.
+2. **Given** an overlay with a required parameter (no default), **When** generation is run without providing the parameter value, **Then** the tool exits with a clear error message before writing any files.
+3. **Given** generated files contain no `{{cs.*}}` tokens, **When** output is validated, **Then** no error is raised and Docker Compose `${VAR}` expressions are preserved unmodified.
+4. **Given** a user runs `init` interactively with the postgres overlay, **When** the questionnaire reaches parameters, **Then** the user is prompted for each declared parameter with the default pre-filled.
+
+### User Story 2 — Sensitive parameter (P2)
+
+A user provides a database password via parameter. The password must not appear in plan output in cleartext.
+
+**Acceptance scenarios**:
+
+1. **Given** a parameter has `sensitive: true`, **When** the plan command shows parameter values, **Then** the value is displayed as `***`.
+2. **Given** a parameter has `sensitive: true`, **When** the interactive questionnaire prompts for it, **Then** the input is masked.
+
+### User Story 3 — Unknown parameter warning (P3)
+
+A user adds a parameter in `superposition.yml` that is not declared by any selected overlay.
+
+**Acceptance scenarios**:
+
+1. **Given** `parameters: { UNKNOWN_PARAM: foo }` in `superposition.yml`, **When** generation runs, **Then** a warning is printed but generation succeeds.

package/overlays/.shared/README.md

@@ -10,6 +10,7 @@ This directory contains reusable configuration fragments that can be imported by
 │   ├── instrumentation.env            # OTEL SDK env vars for instrumentation
 │   └── otel-base-config.yaml          # Base OTEL collector pipeline config
 ├── compose/                           # Docker Compose patterns
+│   ├── nvidia-gpu-devcontainer.yml    # NVIDIA GPU passthrough for the devcontainer service
 │   └── common-healthchecks.md         # Standard healthcheck patterns (reference — not importable)
 └── vscode/                            # VS Code extension sets
     └── recommended-extensions.json    # Commonly recommended extensions (devcontainer patch)
@@ -44,6 +45,20 @@ This directory contains reusable configuration fragments that can be imported by
 
 ---
 
+### `compose/nvidia-gpu-devcontainer.yml`
+
+**Purpose:** Adds the `deploy.resources.reservations.devices` block to the `devcontainer` service, giving the devcontainer itself direct NVIDIA GPU access. This enables GPU-accelerated tooling (`torch`, `tensorflow`, CUDA CLIs, `nvidia-smi`) to work directly in the dev environment.
+
+**Format:** Docker Compose service fragment (services.devcontainer only).
+
+**Merge type:** `compose_imports:` — deep-merged into the final `docker-compose.yml` before the overlay's own `docker-compose.yml`.
+
+**Imported by:** `ollama`
+
+**Prerequisites:** NVIDIA Container Toolkit must be installed on the host.
+
+---
+
 ### `compose/common-healthchecks.md`
 
 **Purpose:** Reference library of standard Docker Compose healthcheck patterns for common services (HTTP, PostgreSQL, Redis, MongoDB, MySQL).
@@ -64,7 +79,7 @@ This directory contains reusable configuration fragments that can be imported by
 
 ## Usage
 
-Reference shared fragments in `overlay.yml` via the `imports` field:
+Reference shared devcontainer fragments in `overlay.yml` via the `imports` field:
 
 ```yaml
 id: my-overlay
@@ -73,11 +88,21 @@ imports:
     - .shared/vscode/recommended-extensions.json
 ```
 
+Reference shared docker-compose fragments via the `compose_imports` field:
+
+```yaml
+id: my-overlay
+compose_imports:
+    - .shared/compose/nvidia-gpu-devcontainer.yml
+```
+
 **Rules:**
 
 - All paths must begin with `.shared/`
 - Paths are relative to `overlays/`
-- Imports are applied in declaration order, then the overlay's own `devcontainer.patch.json` (overlay wins on conflict)
+- `imports` fragments are applied in declaration order, then the overlay's own `devcontainer.patch.json` (overlay wins on conflict)
+- `compose_imports` fragments are deep-merged into `docker-compose.yml` before the overlay's own `docker-compose.yml` (overlay wins on conflict)
+- `compose_imports` files must be `.yml` or `.yaml`
 
 ## Creating New Fragments
 

package/overlays/.shared/compose/nvidia-gpu-devcontainer.yml

@@ -0,0 +1,22 @@
+# Shared Docker Compose fragment: NVIDIA GPU passthrough for the devcontainer service.
+#
+# Adds the deploy.resources.reservations.devices block to the devcontainer service so
+# GPU-accelerated tooling (torch, tensorflow, CUDA CLIs, etc.) works directly in the
+# dev environment alongside any GPU-enabled sidecar services.
+#
+# Requirements: NVIDIA Container Toolkit must be installed on the host.
+#   https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html
+#
+# Used by: ollama
+# Import via compose_imports in overlay.yml:
+#   compose_imports:
+#     - .shared/compose/nvidia-gpu-devcontainer.yml
+services:
+    devcontainer:
+        deploy:
+            resources:
+                reservations:
+                    devices:
+                        - driver: nvidia
+                          count: all
+                          capabilities: [gpu]