container-superposition 0.1.6 → 0.1.8

package/docs/overlays.md

@@ -69,12 +69,13 @@ Jupyter notebook server for interactive computing and data science
 
 Material for MkDocs - professional documentation generator
 
-| Property     | Value                               |
-| ------------ | ----------------------------------- |
-| **Category** | language                            |
-| **Requires** | `python`                            |
-| **Tags**     | `documentation`, `mkdocs`, `python` |
-| **Ports**    | 8000                                |
+| Property      | Value                               |
+| ------------- | ----------------------------------- |
+| **Category**  | language                            |
+| **Requires**  | `python`                            |
+| **Conflicts** | `mkdocs2`                           |
+| **Tags**      | `documentation`, `mkdocs`, `python` |
+| **Ports**     | 8000                                |
 
 ### Node.js (`nodejs`)
 
@@ -145,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`)
 
@@ -167,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`)
 
@@ -189,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`)
 
@@ -200,7 +227,7 @@ Redis 7 cache
 | **Category** | database                     |
 | **Supports** | compose                      |
 | **Tags**     | `database`, `cache`, `redis` |
-| **Ports**    | [object Object]              |
+| **Ports**    | 6379/tcp                     |
 
 ### Redpanda (`redpanda`)
 
@@ -241,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`)
 
@@ -259,7 +286,7 @@ Log aggregation system
 | **Supports** | compose                         |
 | **Suggests** | `promtail`                      |
 | **Tags**     | `observability`, `logs`, `loki` |
-| **Ports**    | [object Object]                 |
+| **Ports**    | 3100/http                       |
 
 ### Prometheus (`prometheus`)
 
@@ -271,7 +298,7 @@ Metrics collection and monitoring
 | **Supports** | compose                                  |
 | **Suggests** | `alertmanager`                           |
 | **Tags**     | `observability`, `metrics`, `prometheus` |
-| **Ports**    | [object Object]                          |
+| **Ports**    | 9090/http                                |
 
 ### Tempo (`tempo`)
 
@@ -332,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`)
 
@@ -389,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
@@ -502,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
@@ -513,6 +564,26 @@ Conventional commits validation for automated releases
 | **Suggests** | `pre-commit`                                |
 | **Tags**     | `dev`, `git`, `commits`, `semantic-release` |
 
+### CUDA (NVIDIA GPU) (`cuda`)
+
+NVIDIA CUDA libraries and GPU passthrough for containerized ML/inference workloads
+
+| Property      | Value                                             |
+| ------------- | ------------------------------------------------- |
+| **Category**  | dev                                               |
+| **Conflicts** | `rocm`                                            |
+| **Tags**      | `dev`, `gpu`, `cuda`, `nvidia`, `ml`, `inference` |
+
+### Dev Container CLI (`devcontainer-cli`)
+
+Official devcontainer CLI for building and testing devcontainer configurations
+
+| Property     | Value                                   |
+| ------------ | --------------------------------------- |
+| **Category** | dev                                     |
+| **Suggests** | `docker-sock`, `docker-in-docker`       |
+| **Tags**     | `dev`, `devcontainer`, `cli`, `testing` |
+
 ### direnv (`direnv`)
 
 Per-directory environment variable management
@@ -589,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`)
 
@@ -600,7 +671,19 @@ 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`)
+
+MkDocs 2.0 pre-release (encode/mkdocs) — smart, simple website design tool
+
+| Property      | Value                                      |
+| ------------- | ------------------------------------------ |
+| **Category**  | dev                                        |
+| **Requires**  | `python`                                   |
+| **Conflicts** | `mkdocs`                                   |
+| **Tags**      | `dev`, `documentation`, `mkdocs`, `python` |
+| **Ports**     | 8000                                       |
 
 ### Modern CLI Tools (`modern-cli-tools`)
 
@@ -622,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
@@ -662,6 +769,27 @@ Automated code quality gates with pre-commit hooks
 | **Suggests** | `commitlint`                     |
 | **Tags**     | `dev`, `git`, `quality`, `hooks` |
 
+### ROCm (AMD GPU) (`rocm`)
+
+AMD ROCm libraries and GPU passthrough for containerized ML/inference workloads
+
+| Property      | Value                                          |
+| ------------- | ---------------------------------------------- |
+| **Category**  | dev                                            |
+| **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/quick-reference.md

@@ -162,6 +162,105 @@ npm run init -- \
   --cloud-tools aws-cli,azure-cli,kubectl-helm
 ```
 
+## Doctor Command
+
+The `doctor` command validates the current environment and devcontainer configuration.
+
+### Basic Diagnostics
+
+```bash
+# Run diagnostics against the default .devcontainer/
+container-superposition doctor
+
+# Specify a custom path
+container-superposition doctor --output ./my-project/.devcontainer
+
+# Point to a manifest file directly (outputPath is derived from the manifest)
+container-superposition doctor --from-manifest ./superposition.json
+
+# Load the output path from the repository project file (superposition.yml)
+container-superposition doctor --from-project
+
+# Run discovery relative to a different repository root
+container-superposition doctor --project-root /path/to/repo
+
+# Machine-readable JSON output
+container-superposition doctor --json
+```
+
+### Auto-Repair with `--fix`
+
+The `--fix` flag runs the full diagnosis and then attempts to automatically repair
+any fixable issues:
+
+```bash
+# Interactive auto-repair (text output)
+container-superposition doctor --fix
+
+# Machine-readable repair output (for CI/scripting)
+container-superposition doctor --fix --json
+```
+
+**Fix run output vocabulary:**
+
+| Outcome                  | Meaning                                              |
+| ------------------------ | ---------------------------------------------------- |
+| `fixed`                  | Tool changed the environment; re-check now passes    |
+| `already compliant`      | No change needed — check already passed              |
+| `skipped`                | Not attempted (prerequisite step failed)             |
+| `requires manual action` | Automation unsafe/unavailable; manual steps provided |
+
+**Fixable issue classes:**
+
+| Issue                                        | Auto-fix condition                                         |
+| -------------------------------------------- | ---------------------------------------------------------- |
+| Stale / legacy `superposition.json` manifest | Always — migrate to current schema                         |
+| Missing or corrupt `devcontainer.json`       | When a valid manifest is present — regenerate              |
+| Unsupported Node.js runtime                  | Only when `nvm`, `fnm`, or `volta` is installed            |
+| Docker daemon not accessible                 | Manual only — platform-specific restart instructions shown |
+
+**Remediation ordering:** Manifest migration always runs before devcontainer regeneration.
+If migration fails, regeneration is skipped and marked as `skipped`.
+
+**Safety:** All file mutations use atomic write (write to `.tmp`, then rename).
+A timestamped backup is created before any manifest is modified.
+
+**Exit codes:**
+
+- `0` — all findings resolved (success or already-compliant)
+- `0` — some findings require manual action (`repaired-with-warnings`)
+- `1` — unresolved failures remain after fix run
+
+### JSON Fix Run Structure
+
+```json
+{
+  "outputPath": "./.devcontainer",
+  "requestedJson": true,
+  "initialFindings": [...],
+  "executions": [
+    {
+      "findingId": "manifest-version",
+      "remediationKey": "manifest-migration",
+      "attempted": true,
+      "outcome": "fixed",
+      "reason": "Manifest migrated to current schema version",
+      "changedFiles": [".devcontainer/superposition.json"],
+      "backupPath": ".devcontainer/superposition.json.backup-2026-03-19-..."
+    }
+  ],
+  "finalFindings": [...],
+  "summary": {
+    "fixed": 1,
+    "alreadyCompliant": 3,
+    "skipped": 0,
+    "requiresManualAction": 0,
+    "total": 4
+  },
+  "exitDisposition": "success"
+}
+```
+
 ## Output Structure
 
 ### Minimal (plain + language)

package/docs/specs/003-mkdocs2-overlay/spec.md

@@ -0,0 +1,114 @@
+# Feature Specification: MkDocs 2.x Overlay
+
+**Feature Branch**: `copilot/add-mkdocs2-overlay`
+**Created**: 2026-03-16
+**Status**: Final
+**Input**: Add a new `mkdocs2` overlay that installs MkDocs 2.x with the Material theme via direct `pip` install, keeping the existing `mkdocs` (MkDocs 1.x) overlay untouched for backward compatibility.
+
+## Review & Approval _(mandatory before implementation)_
+
+- **Spec Path**: `docs/specs/003-mkdocs2-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 - Use MkDocs 2.x in a devcontainer (Priority: P1)
+
+A developer wants to write documentation using MkDocs 2.x with the Material theme inside a devcontainer without manually managing Python packages.
+
+**Why this priority**: MkDocs 2.x is the currently maintained release. Users starting new documentation projects need a working overlay that installs the supported version.
+
+**Independent Test**: Select the `mkdocs2` overlay (with `python` as a required dependency), rebuild the container, and confirm that `mkdocs --version` reports a 2.x release, `mkdocs new .` succeeds, and `mkdocs serve` starts the dev server on port 8000.
+
+**Acceptance Scenarios**:
+
+1. **Given** a user selects the `mkdocs2` overlay, **When** the devcontainer is built, **Then** `mkdocs --version` reports a version matching `2.x`.
+2. **Given** the container is running, **When** the user runs `mkdocs serve`, **Then** the development server starts on port 8000 and VS Code forwards the port automatically.
+3. **Given** a `mkdocs.yml` with `theme: {name: material}`, **When** the user runs `mkdocs build`, **Then** the site is generated without errors into the `site/` directory.
+
+---
+
+### User Story 2 - Conflict enforcement between mkdocs and mkdocs2 (Priority: P1)
+
+A user selects both `mkdocs` (1.x) and `mkdocs2` (2.x) and expects the tool to report a conflict.
+
+**Why this priority**: Both overlays install incompatible versions of the `mkdocs` command into the same environment. Allowing both would produce unpredictable results.
+
+**Independent Test**: Attempt to generate a devcontainer with both `mkdocs` and `mkdocs2` selected and confirm the tool surfaces a conflict and blocks generation.
+
+**Acceptance Scenarios**:
+
+1. **Given** a user selects `mkdocs` and `mkdocs2` simultaneously, **When** the questionnaire processes the selection, **Then** a conflict is reported and the user is prompted to choose one.
+2. **Given** `mkdocs` conflicts with `mkdocs2` in `overlays/mkdocs/overlay.yml`, **When** the overlay loader reads both manifests, **Then** the conflict is recognised bidirectionally.
+
+---
+
+### User Story 3 - Backward compatibility for existing mkdocs users (Priority: P2)
+
+An existing user who already has the `mkdocs` overlay selected is unaffected by the addition of the new overlay.
+
+**Why this priority**: Introducing a new overlay must not break users who rely on the existing one.
+
+**Independent Test**: Generate a devcontainer using only the `mkdocs` overlay and confirm the output is identical to what it was before `mkdocs2` was added.
+
+**Acceptance Scenarios**:
+
+1. **Given** a user's `superposition.json` references only `mkdocs`, **When** they run `regen`, **Then** the output is identical to before and contains no `mkdocs2`-related changes.
+
+---
+
+## Design
+
+### Installation Method
+
+The `mkdocs2` overlay installs packages via `pip` directly into the workspace
+`.venv` virtual environment (created by the `python` overlay, which is a hard
+dependency). The overlay's `setup.sh` creates the `.venv` if it does not exist
+yet, so it is self-contained even when run before the `python` overlay's setup
+script completes.
+
+```bash
+pip install --no-cache-dir \
+    "mkdocs>=2.0,<3.0" \
+    "mkdocs-material>=9.0" \
+    "mkdocs-minify-plugin" \
+    "mkdocs-redirects" \
+    "pymdown-extensions"
+```
+
+This approach is preferred over the `ghcr.io/devcontainers-extra/features/mkdocs:2`
+devcontainer feature because it gives precise version control and installs into
+the same virtual environment used by the rest of the project.
+
+### Category
+
+`dev` — MkDocs is a documentation tool, not a language runtime. This differs
+from the legacy `mkdocs` overlay which uses `language` for historical reasons.
+
+### Conflict Model
+
+`mkdocs` ↔ `mkdocs2` conflict is bidirectional:
+
+- `overlays/mkdocs/overlay.yml`: `conflicts: [mkdocs2]`
+- `overlays/mkdocs2/overlay.yml`: `conflicts: [mkdocs]`
+
+### TypeScript Type
+
+`mkdocs2` is added to the `DevTool` union in `tool/schema/types.ts`, making it
+part of the `OverlayId` union used throughout the type system.
+
+---
+
+## Files
+
+| File                                       | Description                                        |
+| ------------------------------------------ | -------------------------------------------------- |
+| `overlays/mkdocs2/overlay.yml`             | Overlay manifest                                   |
+| `overlays/mkdocs2/devcontainer.patch.json` | Port 8000 forwarding + VS Code Markdown extensions |
+| `overlays/mkdocs2/setup.sh`                | Pip install into `.venv`                           |
+| `overlays/mkdocs2/verify.sh`               | Confirms MkDocs 2.x is installed                   |
+| `overlays/mkdocs2/README.md`               | User documentation                                 |
+| `overlays/mkdocs/overlay.yml`              | Updated to add bidirectional conflict              |
+| `tool/schema/types.ts`                     | Adds `mkdocs2` to `DevTool`                        |

package/docs/specs/004-doctor-fix/spec.md

@@ -0,0 +1,70 @@
+# Feature Specification: `doctor --fix` — Interactive Auto-Repair
+
+**Feature Branch**: `004-doctor-fix`
+**Created**: 2026-03-19
+**Status**: Final
+**Input**: GitHub issue: Implement `doctor --fix` — interactive auto-repair for environment issues
+
+## Review & Approval _(mandatory before implementation)_
+
+- **Spec Path**: `docs/specs/004-doctor-fix/spec.md`
+- **Commit Status**: Committed
+- **Review Status**: APPROVED
+- **Implementation Gate**: No implementation code may begin until this spec is committed and reviewed.
+
+## Summary
+
+The `doctor` command validates the environment. The `--fix` path was a placeholder. This spec
+describes the full implementation of an interactive, safe, deterministic auto-repair flow for
+common environment issues.
+
+## Initial Auto-Fix Scope
+
+| #   | Issue class                                                   | Automation condition                                              |
+| --- | ------------------------------------------------------------- | ----------------------------------------------------------------- |
+| 1   | Stale or legacy `superposition.json` metadata                 | Always supported (manifest migration)                             |
+| 2   | Derived `.devcontainer/` drift or missing generated artifacts | Supported when a valid manifest is present (regeneration)         |
+| 3   | Unsupported Node runtime                                      | Supported only when `nvm`, `fnm`, or `volta` is already available |
+| 4   | Docker / Compose tooling drift                                | Supported only when a known safe host repair command is available |
+
+## Outcome Vocabulary
+
+Every finding evaluated by the fix flow resolves to exactly one of:
+
+- **`fixed`** — tool changed the environment and targeted re-check now passes
+- **`already compliant`** — fix path found no change was needed
+- **`skipped`** — not attempted because an earlier failure or prerequisite blocked it
+- **`requires manual action`** — issue remains; automation is unsafe or unavailable
+
+## Data Model
+
+### `DiagnosticFinding`
+
+Fields: `id`, `category`, `name`, `status`, `message`, `details?`, `fixEligibility`, `remediationKey?`, `recheckScope`
+
+### `RemediationAction`
+
+Fields: `key`, `findingId`, `safetyClass`, `executionKind`, `preconditions`, `plannedChanges`, `manualFallback`
+
+### `FixExecution`
+
+Fields: `findingId`, `remediationKey`, `attempted`, `outcome`, `reason`, `commands?`, `changedFiles?`, `backupPath?`, `rechecked`
+
+### `FixRun`
+
+Fields: `outputPath`, `requestedJson`, `initialFindings`, `executions`, `finalFindings`, `summary`, `exitDisposition`
+
+## CLI Contract
+
+- `doctor` without `--fix` — no change to current diagnostics behavior
+- `doctor --fix` — diagnose → remediate in stable order → re-check → print summary
+- `doctor --fix --json` — same flow, machine-readable JSON output
+
+## Remediation Ordering
+
+Prerequisites before dependents:
+
+1. Stale manifest migration (must complete before regeneration)
+2. Missing artifacts / devcontainer drift (regeneration from manifest)
+3. Node version fix (only if version manager available)
+4. Docker tooling fix (only if repair command available)