container-superposition 0.1.6 → 0.1.7

package/docs/overlay-imports.md

@@ -4,25 +4,28 @@ Overlays can import shared configuration fragments from `overlays/.shared/` to r
 
 ## Overview
 
-Import functionality allows overlays to reference common configuration files instead of duplicating them in every overlay. This promotes DRY (Don't Repeat Yourself) principles and makes it easier to maintain consistent patterns.
+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.
 
 ## Shared Directory Structure
 
 ```
 overlays/
 ├── .shared/
-│   ├── otel/                           # OpenTelemetry configurations
-│   │   ├── otel-base-config.yaml      # Base OTEL collector config
-│   │   └── instrumentation.env        # Common env vars for instrumentation
-│   ├── compose/                        # Docker Compose patterns
-│   │   └── common-healthchecks.yml    # Standard healthcheck configurations
-│   └── vscode/                         # VS Code extension sets
-│       └── recommended-extensions.json # Commonly recommended extensions
+│   ├── README.md
+│   ├── otel/
+│   │   ├── 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
+│   └── vscode/
+│       └── recommended-extensions.json # Commonly recommended VS Code extensions (devcontainer patch format)
 ├── prometheus/
-│   ├── overlay.yml                     # Can import from .shared/
+│   ├── overlay.yml                    # imports: [.shared/otel/instrumentation.env]
 │   └── devcontainer.patch.json
 └── jaeger/
-    ├── overlay.yml                     # Can import from .shared/
+    ├── overlay.yml                    # imports: [.shared/otel/instrumentation.env]
     └── devcontainer.patch.json
 ```
 
@@ -48,101 +51,128 @@ ports:
     - 9090
 imports:
     - .shared/otel/instrumentation.env
-    - .shared/compose/common-healthchecks.yml
 ```
 
-## Supported File Types
+**Rules:**
+
+- All paths **must** begin with `.shared/` — references outside `.shared/` are rejected (path traversal prevention)
+- Paths are relative to `overlays/`
+- 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
 
-### JSON Files (`.json`)
+## Supported File Types and Merge Behavior
 
-Merged as devcontainer patches, just like `devcontainer.patch.json`.
+| Extension        | How it is merged                                                               |
+| ---------------- | ------------------------------------------------------------------------------ |
+| `.json`          | Deep-merged into `devcontainer.json` patch (same as `devcontainer.patch.json`) |
+| `.yaml` / `.yml` | Loaded and deep-merged into `devcontainer.json` patch                          |
+| `.env`           | Concatenated into `.env.example` with a `# from .shared/…` comment header      |
+| Anything else    | Rejected with a clear unsupported-type error                                   |
 
-**Example: `.shared/vscode/recommended-extensions.json`**
+### JSON import example
 
-```json
+```jsonc
+// overlays/.shared/vscode/recommended-extensions.json
 {
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
     "customizations": {
         "vscode": {
             "extensions": [
                 "streetsidesoftware.code-spell-checker",
                 "usernamehw.errorlens",
-                "editorconfig.editorconfig"
-            ]
-        }
-    }
+                "eamodio.gitlens",
+            ],
+        },
+    },
 }
 ```
 
-### YAML Files (`.yaml`, `.yml`)
-
-Loaded and merged as devcontainer patches. Useful for complex configurations.
-
-**Example: `.shared/otel/otel-base-config.yaml`**
+### YAML import example
 
 ```yaml
-receivers:
-    otlp:
-        protocols:
-            grpc:
-                endpoint: 0.0.0.0:4317
-            http:
-                endpoint: 0.0.0.0:4318
+# overlays/.shared/otel/otel-base-config.yaml
+remoteEnv:
+    OTEL_SERVICE_NAME: my-service
+    OTEL_EXPORTER_OTLP_ENDPOINT: http://otel-collector:4317
 ```
 
-### Environment Files (`.env`)
+### ENV import example
 
-Merged into `.env.example` with a comment indicating the import source.
+```bash
+# overlays/.shared/otel/instrumentation.env
+# OpenTelemetry SDK Configuration
+OTEL_SERVICE_NAME=my-service
+OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
+OTEL_EXPORTER_OTLP_PROTOCOL=grpc
+OTEL_TRACES_SAMPLER=always_on
+OTEL_TRACES_EXPORTER=otlp
+OTEL_METRICS_EXPORTER=otlp
+OTEL_LOGS_EXPORTER=otlp
+```
 
-**Example: `.shared/otel/instrumentation.env`**
+When this `.env` fragment is imported, the generated `.env.example` will contain:
 
 ```bash
-# OpenTelemetry Configuration
+# from .shared/otel/instrumentation.env
 OTEL_SERVICE_NAME=my-service
 OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
-OTEL_TRACES_SAMPLER=always_on
+...
 ```
 
-## How Imports Work
+## Import Ordering and Conflict Resolution
 
-1. **Resolution**: Imports are resolved relative to the `overlays/` directory
-2. **Order**: Imports are applied in the order listed, then the overlay's own files
-3. **Merging**:
-    - JSON/YAML: Deep merged into devcontainer configuration
-    - ENV: Concatenated into `.env.example` with source comments
-4. **Validation**: Doctor command validates that all imports exist and are valid
+Imports are applied in declaration order, then the overlay's own `devcontainer.patch.json` is applied last:
 
-## Benefits
+```
+[import 1] → [import 2] → … → [import N] → [overlay own patch]
+```
 
-### Reduced Duplication
+- The **second** import wins over the first on key conflict
+- The **overlay's own patch always wins** over any shared fragment
 
-Before imports:
+This means overlays can intentionally override shared defaults by setting the same key in their `devcontainer.patch.json`.
 
-```
-prometheus/devcontainer.patch.json  (200 lines with OTEL config)
-jaeger/devcontainer.patch.json      (200 lines with OTEL config)
-grafana/devcontainer.patch.json     (200 lines with OTEL config)
+## Worked Example: OTEL Instrumentation
+
+Many observability overlays need OTEL environment variables. With imports, these are defined once:
+
+**`overlays/.shared/otel/instrumentation.env`** — shared once
+
+**`overlays/otel-collector/overlay.yml`:**
+
+```yaml
+imports:
+    - .shared/otel/instrumentation.env
 ```
 
-After imports:
+**`overlays/prometheus/overlay.yml`:**
 
+```yaml
+imports:
+    - .shared/otel/instrumentation.env
 ```
-.shared/otel/otel-base-config.yaml  (50 lines, shared)
-prometheus/overlay.yml              (imports: [.shared/otel/otel-base-config.yaml])
-jaeger/overlay.yml                  (imports: [.shared/otel/otel-base-config.yaml])
-grafana/overlay.yml                 (imports: [.shared/otel/otel-base-config.yaml])
+
+**`overlays/jaeger/overlay.yml`:**
+
+```yaml
+imports:
+    - .shared/otel/instrumentation.env
 ```
 
-### Consistency
+When any of these overlays is used, the generated `.env.example` will contain the OTEL environment variables with a comment indicating they came from the shared fragment.
+
+## Security: Path Traversal Prevention
 
-All overlays using the same shared config stay in sync automatically.
+Import paths are validated before any file is read:
 
-### Maintainability
+1. The path **must** begin with `.shared/`
+2. The resolved absolute path **must** remain inside `overlays/.shared/`
 
-Update shared configuration once, all importing overlays benefit.
+Any import that fails either check causes generation to abort with an error identifying the overlay and the rejected path. References like `../secret.json`, `/etc/passwd`, or `other-overlay/file.json` are all rejected.
 
-## Validation
+## Validation via Doctor
 
-The `doctor` command validates imports:
+The `doctor` command validates all imports for every overlay:
 
 ```bash
 container-superposition doctor
@@ -150,60 +180,53 @@ container-superposition doctor
 
 Checks performed:
 
-- Import files exist
-- File types are supported (`.json`, `.yaml`, `.yml`, `.env`)
-- No broken import references
-
-## Creating Shared Configurations
-
-1. **Identify common patterns** across overlays
-2. **Extract to `.shared/` subdirectory** with descriptive path
-3. **Update overlays** to import the shared file
-4. **Test** that composition works correctly
-5. **Document** the shared file's purpose in `.shared/README.md`
+- 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`
 
-## Example: OTEL Instrumentation
+Broken references are reported with the overlay ID and the bad path so maintainers can fix them quickly.
 
-Many observability overlays need OTEL instrumentation. Instead of duplicating these environment variables:
+## Viewing Imports in `explain`
 
-**Create:** `overlays/.shared/otel/instrumentation.env`
+When an overlay has imports, they are shown in the `explain` output:
 
 ```bash
-# OpenTelemetry SDK Configuration
-OTEL_SERVICE_NAME=my-service
-OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
-OTEL_EXPORTER_OTLP_PROTOCOL=grpc
-OTEL_RESOURCE_ATTRIBUTES=deployment.environment=development
-OTEL_TRACES_SAMPLER=always_on
-OTEL_TRACES_EXPORTER=otlp
-OTEL_METRICS_EXPORTER=otlp
-OTEL_LOGS_EXPORTER=otlp
+container-superposition explain prometheus
 ```
 
-**Import in overlays:**
+```
+Shared Imports:
+  (Fragments from overlays/.shared/ applied before this overlay)
+  📎 .shared/otel/instrumentation.env
+```
 
-```yaml
-# overlays/prometheus/overlay.yml
-imports:
-    - .shared/otel/instrumentation.env
+## Creating Shared Configurations
 
-# overlays/jaeger/overlay.yml
-imports:
-    - .shared/otel/instrumentation.env
-```
+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`
+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
+
+## Downstream Impact Awareness
+
+A single change to a shared fragment affects every overlay that imports it. Before editing a shared fragment:
 
-Now all OTEL-compatible overlays share the same instrumentation configuration!
+- Check `.shared/README.md` to see which overlays import it
+- Use `grep -r "fragment-name" overlays/*/overlay.yml` to find all importers
+- Run the full test suite after any shared fragment change
 
 ## Best Practices
 
-1. **Keep shared files focused** - One concern per file
-2. **Use descriptive paths** - `.shared/otel/instrumentation.env` not `.shared/env1.env`
-3. **Document shared files** - Add comments explaining purpose and usage
-4. **Version carefully** - Changes to shared files affect all importing overlays
-5. **Test imports** - Verify overlay composition works after adding imports
+1. **One concern per file** — `instrumentation.env` not `all-the-things.env`
+2. **Descriptive category paths** — `.shared/otel/` not `.shared/misc/`
+3. **Comment your fragments** — explain purpose and usage at the top of each file
+4. **Keep fragments small** — big shared files create tight coupling
+5. **Overlay-specific overrides are fine** — an overlay's own patch always wins; diverging from a shared baseline is expected and supported
 
 ## See Also
 
 - [Creating Overlays](creating-overlays.md)
-- [Overlay Metadata](overlay-metadata-archive.md)
-- [Doctor Command](../README.md#doctor-command)
+- `overlays/.shared/README.md` — shared fragment catalogue with usage details
+- CONTRIBUTING.md — overlay authoring guide

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`)
 
@@ -513,6 +514,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
@@ -602,6 +623,18 @@ Email testing tool with web UI and SMTP server
 | **Tags**     | `dev`, `email`, `smtp`, `testing` |
 | **Ports**    | [object Object], [object Object]  |
 
+### 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`)
 
 jq, yq, ripgrep, fd, bat - Essential modern command-line tools
@@ -662,6 +695,16 @@ 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` |
+
 ### 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`                        |