container-superposition 0.1.7 → 0.1.8

package/docs/overlay-imports.md

@@ -6,7 +6,10 @@ Overlays can import shared configuration fragments from `overlays/.shared/` to r
 
 The import mechanism allows overlays to reference common configuration files instead of duplicating them. This promotes DRY principles and makes it easier to maintain consistent patterns.
 
-Imports are declared in the overlay's `overlay.yml` manifest and applied **before** the overlay's own `devcontainer.patch.json`, so each overlay can specialize on top of a shared baseline.
+Two import fields are supported in `overlay.yml`:
+
+- **`imports:`** — shared devcontainer patch fragments (`.json`, `.yaml`, `.env`) applied before the overlay's own `devcontainer.patch.json`
+- **`compose_imports:`** — shared docker-compose YAML fragments (`.yml`, `.yaml`) deep-merged into `docker-compose.yml` before the overlay's own `docker-compose.yml`
 
 ## Shared Directory Structure
 
@@ -15,21 +18,25 @@ overlays/
 ├── .shared/
 │   ├── README.md
 │   ├── otel/
-│   │   ├── instrumentation.env        # OTEL SDK env vars — imported by otel-collector, prometheus, jaeger
-│   │   └── otel-base-config.yaml      # Base OTEL collector pipeline config
+│   │   ├── instrumentation.env              # OTEL SDK env vars — imported by otel-collector, prometheus, jaeger
+│   │   └── otel-base-config.yaml            # Base OTEL collector pipeline config
 │   ├── compose/
-│   │   └── common-healthchecks.yml    # Standard Docker Compose healthcheck patterns
+│   │   ├── nvidia-gpu-devcontainer.yml      # NVIDIA GPU passthrough for the devcontainer service
+│   │   └── common-healthchecks.md           # Standard Docker Compose healthcheck patterns (reference only)
 │   └── vscode/
-│       └── recommended-extensions.json # Commonly recommended VS Code extensions (devcontainer patch format)
+│       └── recommended-extensions.json      # Commonly recommended VS Code extensions (devcontainer patch format)
 ├── prometheus/
-│   ├── overlay.yml                    # imports: [.shared/otel/instrumentation.env]
+│   ├── overlay.yml                          # imports: [.shared/otel/instrumentation.env]
+│   └── devcontainer.patch.json
+├── jaeger/
+│   ├── overlay.yml                          # imports: [.shared/otel/instrumentation.env]
 │   └── devcontainer.patch.json
-└── jaeger/
-    ├── overlay.yml                    # imports: [.shared/otel/instrumentation.env]
-    └── devcontainer.patch.json
+└── ollama/
+    ├── overlay.yml                          # compose_imports: [.shared/compose/nvidia-gpu-devcontainer.yml]
+    └── docker-compose.yml
 ```
 
-## Using Imports
+## Using `imports` (devcontainer patch fragments)
 
 Add the `imports` field to your `overlay.yml` manifest:
 
@@ -60,7 +67,28 @@ imports:
 - Order is significant — fragments are applied in declaration order, then the overlay's own `devcontainer.patch.json`
 - Missing files, unsupported types, or path traversal attempts cause generation to fail with a message identifying the overlay and the broken reference
 
-## Supported File Types and Merge Behavior
+## Using `compose_imports` (docker-compose fragments)
+
+Add the `compose_imports` field to your `overlay.yml` manifest to merge shared docker-compose YAML fragments into the generated `docker-compose.yml`:
+
+```yaml
+id: ollama
+name: Ollama
+# ... other fields ...
+compose_imports:
+    - .shared/compose/nvidia-gpu-devcontainer.yml
+```
+
+**Rules:**
+
+- All paths **must** begin with `.shared/` (same path traversal rules as `imports`)
+- Files must be `.yml` or `.yaml`
+- Fragments are deep-merged in declaration order, then the overlay's own `docker-compose.yml` is merged last (overlay wins on conflict)
+- Missing files, wrong types, or traversal attempts cause generation to fail
+
+## Supported File Types
+
+### `imports:` — devcontainer patch fragments
 
 | Extension        | How it is merged                                                               |
 | ---------------- | ------------------------------------------------------------------------------ |
@@ -69,6 +97,13 @@ imports:
 | `.env`           | Concatenated into `.env.example` with a `# from .shared/…` comment header      |
 | Anything else    | Rejected with a clear unsupported-type error                                   |
 
+### `compose_imports:` — docker-compose fragments
+
+| Extension        | How it is merged                                                            |
+| ---------------- | --------------------------------------------------------------------------- |
+| `.yaml` / `.yml` | Deep-merged into `docker-compose.yml` before the overlay's own compose file |
+| Anything else    | Rejected with a clear unsupported-type error                                |
+
 ### JSON import example
 
 ```jsonc
@@ -87,7 +122,7 @@ imports:
 }
 ```
 
-### YAML import example
+### YAML devcontainer import example
 
 ```yaml
 # overlays/.shared/otel/otel-base-config.yaml
@@ -119,8 +154,27 @@ OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
 ...
 ```
 
+### YAML compose_import example
+
+```yaml
+# overlays/.shared/compose/nvidia-gpu-devcontainer.yml
+services:
+    devcontainer:
+        deploy:
+            resources:
+                reservations:
+                    devices:
+                        - driver: nvidia
+                          count: all
+                          capabilities: [gpu]
+```
+
+When this fragment is imported via `compose_imports`, the generated `docker-compose.yml` will include the `deploy` block on the `devcontainer` service merged with contributions from all other overlays.
+
 ## Import Ordering and Conflict Resolution
 
+### `imports` ordering
+
 Imports are applied in declaration order, then the overlay's own `devcontainer.patch.json` is applied last:
 
 ```
@@ -132,6 +186,17 @@ Imports are applied in declaration order, then the overlay's own `devcontainer.p
 
 This means overlays can intentionally override shared defaults by setting the same key in their `devcontainer.patch.json`.
 
+### `compose_imports` ordering
+
+For each overlay, compose fragments are merged before the overlay's own `docker-compose.yml`, in this order:
+
+```
+[base template compose] → [overlay 1 compose_imports] → [overlay 1 docker-compose.yml] → [overlay 2 compose_imports] → [overlay 2 docker-compose.yml] → …
+```
+
+- Each overlay's `docker-compose.yml` wins over its own `compose_imports`
+- Later overlays win over earlier overlays on key conflict
+
 ## Worked Example: OTEL Instrumentation
 
 Many observability overlays need OTEL environment variables. With imports, these are defined once:
@@ -183,7 +248,8 @@ Checks performed:
 - Import path starts with `.shared/` (path traversal check)
 - Import path resolves within `overlays/.shared/` (traversal check)
 - Import file exists on disk
-- File type is one of `.json`, `.yaml`, `.yml`, `.env`
+- File type is one of `.json`, `.yaml`, `.yml`, `.env` (for `imports:`)
+- File type is one of `.yaml`, `.yml` (for `compose_imports:`)
 
 Broken references are reported with the overlay ID and the bad path so maintainers can fix them quickly.
 
@@ -201,11 +267,23 @@ Shared Imports:
   📎 .shared/otel/instrumentation.env
 ```
 
+When an overlay has compose_imports, they are also shown:
+
+```bash
+container-superposition explain ollama
+```
+
+```
+Shared Compose Imports:
+  (docker-compose fragments from overlays/.shared/ merged before this overlay)
+  🐳 .shared/compose/nvidia-gpu-devcontainer.yml
+```
+
 ## Creating Shared Configurations
 
 1. **Identify common patterns** across multiple overlays
 2. **Create `overlays/.shared/<category>/<name>.<ext>`** — use descriptive paths, one concern per file
-3. **Update overlays** to reference the fragment via `imports:` in their `overlay.yml`
+3. **Update overlays** to reference the fragment via `imports:` or `compose_imports:` in their `overlay.yml`
 4. **Update `.shared/README.md`** to document the fragment's purpose and which overlays use it
 5. **Test** with `npm test` and `container-superposition doctor` to verify
 

package/docs/overlays.md

@@ -146,18 +146,18 @@ MongoDB 8 with Mongo Express web UI
 | **Category** | database                                   |
 | **Supports** | compose                                    |
 | **Tags**     | `database`, `nosql`, `mongodb`, `document` |
-| **Ports**    | [object Object], [object Object]           |
+| **Ports**    | 27017/tcp, 8081/http                       |
 
 ### MySQL (`mysql`)
 
 MySQL 8 with phpMyAdmin web UI
 
-| Property     | Value                            |
-| ------------ | -------------------------------- |
-| **Category** | database                         |
-| **Supports** | compose                          |
-| **Tags**     | `database`, `sql`, `mysql`       |
-| **Ports**    | [object Object], [object Object] |
+| Property     | Value                      |
+| ------------ | -------------------------- |
+| **Category** | database                   |
+| **Supports** | compose                    |
+| **Tags**     | `database`, `sql`, `mysql` |
+| **Ports**    | 3306/tcp, 8080/http        |
 
 ### NATS (`nats`)
 
@@ -168,18 +168,44 @@ Lightweight pub/sub messaging with JetStream
 | **Category** | database                                               |
 | **Supports** | compose                                                |
 | **Tags**     | `database`, `messaging`, `pubsub`, `nats`, `jetstream` |
-| **Ports**    | [object Object], [object Object]                       |
+| **Ports**    | 4222/tcp, 8222/http                                    |
+
+### pgvector (PostgreSQL + vector) (`pgvector`)
+
+PostgreSQL 16 with the pgvector extension for vector similarity search
+
+| Property      | Value                                                             |
+| ------------- | ----------------------------------------------------------------- |
+| **Category**  | database                                                          |
+| **Supports**  | compose                                                           |
+| **Suggests**  | `ollama`, `python`, `nodejs`                                      |
+| **Conflicts** | `postgres`                                                        |
+| **Tags**      | `database`, `sql`, `vector`, `embeddings`, `postgres`, `pgvector` |
+| **Ports**     | 5432/tcp                                                          |
 
 ### PostgreSQL (`postgres`)
 
 PostgreSQL 16 database
 
-| Property     | Value                         |
-| ------------ | ----------------------------- |
-| **Category** | database                      |
-| **Supports** | compose                       |
-| **Tags**     | `database`, `sql`, `postgres` |
-| **Ports**    | [object Object]               |
+| Property      | Value                         |
+| ------------- | ----------------------------- |
+| **Category**  | database                      |
+| **Supports**  | compose                       |
+| **Conflicts** | `pgvector`                    |
+| **Tags**      | `database`, `sql`, `postgres` |
+| **Ports**     | 5432/tcp                      |
+
+### Qdrant (`qdrant`)
+
+High-performance vector database for similarity search and embeddings
+
+| Property     | Value                                                  |
+| ------------ | ------------------------------------------------------ |
+| **Category** | database                                               |
+| **Supports** | compose                                                |
+| **Suggests** | `ollama`, `python`, `nodejs`                           |
+| **Tags**     | `database`, `vector`, `embeddings`, `search`, `qdrant` |
+| **Ports**    | 6333/http, 6334/grpc                                   |
 
 ### RabbitMQ (`rabbitmq`)
 
@@ -190,7 +216,7 @@ Message broker with AMQP protocol and management UI
 | **Category** | database                                             |
 | **Supports** | compose                                              |
 | **Tags**     | `database`, `messaging`, `queue`, `rabbitmq`, `amqp` |
-| **Ports**    | [object Object], [object Object]                     |
+| **Ports**    | 5672/tcp, 15672/http                                 |
 
 ### Redis (`redis`)
 
@@ -201,7 +227,7 @@ Redis 7 cache
 | **Category** | database                     |
 | **Supports** | compose                      |
 | **Tags**     | `database`, `cache`, `redis` |
-| **Ports**    | [object Object]              |
+| **Ports**    | 6379/tcp                     |
 
 ### Redpanda (`redpanda`)
 
@@ -242,13 +268,13 @@ SQLite with litecli and VS Code extensions
 
 Distributed tracing backend
 
-| Property      | Value                                             |
-| ------------- | ------------------------------------------------- |
-| **Category**  | observability                                     |
-| **Supports**  | compose                                           |
-| **Conflicts** | `tempo`                                           |
-| **Tags**      | `observability`, `tracing`, `jaeger`              |
-| **Ports**     | [object Object], [object Object], [object Object] |
+| Property      | Value                                |
+| ------------- | ------------------------------------ |
+| **Category**  | observability                        |
+| **Supports**  | compose                              |
+| **Conflicts** | `tempo`                              |
+| **Tags**      | `observability`, `tracing`, `jaeger` |
+| **Ports**     | 16686/http, 14250/grpc, 14268/http   |
 
 ### Loki (`loki`)
 
@@ -260,7 +286,7 @@ Log aggregation system
 | **Supports** | compose                         |
 | **Suggests** | `promtail`                      |
 | **Tags**     | `observability`, `logs`, `loki` |
-| **Ports**    | [object Object]                 |
+| **Ports**    | 3100/http                       |
 
 ### Prometheus (`prometheus`)
 
@@ -272,7 +298,7 @@ Metrics collection and monitoring
 | **Supports** | compose                                  |
 | **Suggests** | `alertmanager`                           |
 | **Tags**     | `observability`, `metrics`, `prometheus` |
-| **Ports**    | [object Object]                          |
+| **Ports**    | 9090/http                                |
 
 ### Tempo (`tempo`)
 
@@ -333,7 +359,7 @@ Observability visualization dashboard with auto-provisioning
 | **Requires** | `prometheus`                           |
 | **Suggests** | `loki`, `jaeger`, `tempo`, `promtail`  |
 | **Tags**     | `observability`, `ui`, `visualization` |
-| **Ports**    | [object Object]                        |
+| **Ports**    | 3000/http                              |
 
 ### OTel Demo (Node.js) (`otel-demo-nodejs`)
 
@@ -390,6 +416,18 @@ Google Cloud Platform command-line tools (gcloud, gsutil, bq)
 | **Category** | cloud                           |
 | **Tags**     | `cloud`, `gcp`, `google`, `cli` |
 
+### k3d (`k3d`)
+
+Lightweight local Kubernetes clusters using k3s in Docker
+
+| Property      | Value                                                 |
+| ------------- | ----------------------------------------------------- |
+| **Category**  | cloud                                                 |
+| **Requires**  | `docker-in-docker`                                    |
+| **Suggests**  | `kubectl-helm`                                        |
+| **Conflicts** | `kind`                                                |
+| **Tags**      | `cloud`, `kubernetes`, `k8s`, `k3d`, `k3s`, `testing` |
+
 ### kind (Kubernetes in Docker) (`kind`)
 
 Local Kubernetes cluster for development and testing
@@ -503,6 +541,18 @@ OpenAI Codex CLI for AI-powered code generation and assistance
 | **Requires** | `nodejs`                       |
 | **Tags**     | `dev`, `ai`, `code-generation` |
 
+### ComfyUI (`comfyui`)
+
+Node-based image/video generation UI for Stable Diffusion and generative AI workflows
+
+| Property     | Value                                                          |
+| ------------ | -------------------------------------------------------------- |
+| **Category** | dev                                                            |
+| **Supports** | compose                                                        |
+| **Suggests** | `cuda`, `python`, `ollama`                                     |
+| **Tags**     | `dev`, `ai`, `image-generation`, `stable-diffusion`, `comfyui` |
+| **Ports**    | 8188                                                           |
+
 ### Commitlint (`commitlint`)
 
 Conventional commits validation for automated releases
@@ -610,7 +660,7 @@ Open-source identity and access management (OIDC/OAuth2)
 | **Supports** | compose                                     |
 | **Requires** | `postgres`                                  |
 | **Tags**     | `dev`, `auth`, `oidc`, `oauth2`, `identity` |
-| **Ports**    | [object Object]                             |
+| **Ports**    | 8180/http                                   |
 
 ### Mailpit (`mailpit`)
 
@@ -621,7 +671,7 @@ Email testing tool with web UI and SMTP server
 | **Category** | dev                               |
 | **Supports** | compose                           |
 | **Tags**     | `dev`, `email`, `smtp`, `testing` |
-| **Ports**    | [object Object], [object Object]  |
+| **Ports**    | 8025/http, 1025/tcp               |
 
 ### MkDocs 2 (`mkdocs2`)
 
@@ -655,6 +705,30 @@ Secure tunneling for webhook testing and external access
 | **Tags**      | `dev`, `tunneling`, `webhooks` |
 | **Ports**     | 4040                           |
 
+### Ollama (`ollama`)
+
+Local LLM inference server with OpenAI-compatible API
+
+| Property     | Value                                     |
+| ------------ | ----------------------------------------- |
+| **Category** | dev                                       |
+| **Supports** | compose                                   |
+| **Suggests** | `codex`, `claude-code`, `amp`             |
+| **Tags**     | `dev`, `ai`, `llm`, `inference`, `ollama` |
+| **Ports**    | 11434                                     |
+
+### Open WebUI (`open-webui`)
+
+Browser-based chat UI for Ollama and OpenAI-compatible LLM backends
+
+| Property     | Value                                         |
+| ------------ | --------------------------------------------- |
+| **Category** | dev                                           |
+| **Supports** | compose                                       |
+| **Suggests** | `ollama`                                      |
+| **Tags**     | `dev`, `ai`, `llm`, `ui`, `chat`, `openwebui` |
+| **Ports**    | 3000/http                                     |
+
 ### OpenAPI Tools (`openapi-tools`)
 
 OpenAPI/Swagger tooling for API development and documentation
@@ -705,6 +779,17 @@ AMD ROCm libraries and GPU passthrough for containerized ML/inference workloads
 | **Conflicts** | `cuda`                                         |
 | **Tags**      | `dev`, `gpu`, `rocm`, `amd`, `ml`, `inference` |
 
+### Skaffold (`skaffold`)
+
+Continuous development and deployment pipeline for Kubernetes applications
+
+| Property      | Value                                                        |
+| ------------- | ------------------------------------------------------------ |
+| **Category**  | dev                                                          |
+| **Suggests**  | `kubectl-helm`, `kind`, `k3d`                                |
+| **Conflicts** | `tilt`                                                       |
+| **Tags**      | `dev`, `kubernetes`, `k8s`, `cicd`, `deployment`, `skaffold` |
+
 ### Tilt (`tilt`)
 
 Live update and orchestration for Kubernetes development

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.