container-superposition 0.1.4 → 0.1.5

package/docs/README.md

@@ -2,6 +2,11 @@
 
 Complete documentation for the container-superposition devcontainer scaffolding system.
 
+## Spec-First Development
+
+Feature work is governed by specs committed under `docs/specs/`. Implementation
+must not begin until the relevant spec is committed and reviewed.
+
 ## 📚 Documentation Index
 
 ### Getting Started
@@ -19,10 +24,15 @@ Complete documentation for the container-superposition devcontainer scaffolding
 
 ### User Guides
 
+- **[Adopt Command](adopt.md)** - Migrate an existing `.devcontainer/` to the overlay-based workflow
+- **[Hash Command](hash.md)** - Deterministic environment fingerprint for drift detection and reproducibility
 - **[Presets Guide](presets.md)** - Using stack presets for common development scenarios
 - **[Messaging Comparison](messaging-comparison.md)** - Choosing between RabbitMQ, Redpanda, and NATS
 - **[Messaging Quick Start](messaging-quick-start.md)** - Getting started with messaging overlays
 - **[Observability Workflow](observability-workflow.md)** - Setting up monitoring and tracing
+- **[Workflows and Regeneration](workflows.md)** - Regeneration, backups, and manifest-based workflows
+- **[Filesystem Contract](filesystem-contract.md)** - What the tool writes and what to edit
+- **[Security Considerations](security.md)** - Development-only risks and best practices
 
 ### Development
 
@@ -209,7 +219,7 @@ When published to npm, includes:
 - ✅ Type definitions and schema (`tool/schema/`)
 - ✅ Documentation
 
-**Package size**: ~122 KB compressed, ~462 KB unpacked
+**Package size**: Varies by release (use `npm pack --dry-run`)
 
 ## 🤝 Contributing
 
@@ -228,7 +238,7 @@ MIT - See [LICENSE](../LICENSE)
 
 - **Repository**: <https://github.com/veggerby/container-superposition>
 - **Issues**: <https://github.com/veggerby/container-superposition/issues>
-- **npm Package**: <https://www.npmjs.com/package/container-superposition> (once published)
+- **npm Package**: <https://www.npmjs.com/package/container-superposition>
 
 ## 🆘 Support
 

package/docs/adopt.md

@@ -0,0 +1,196 @@
+# Adopt Command
+
+The `adopt` command helps you **migrate an existing `.devcontainer/` configuration** to Container Superposition's overlay-based workflow.
+
+It scans your current `devcontainer.json` and any linked `docker-compose.yml` files, matches their contents against all available overlays, and produces:
+
+1. **`superposition.json`** — the manifest written to the **project root** (next to your `src/`, `package.json`, etc.), ready to commit and share with your team
+2. **`.devcontainer/custom/devcontainer.patch.json`** — any config that has no overlay equivalent (custom features, extensions, mounts, remoteEnv, etc.)
+3. **`.devcontainer/custom/docker-compose.patch.yml`** — any compose services that have no overlay equivalent
+
+The custom patches in `custom/` are automatically merged on every `regen`, so your project-specific configuration is never lost.
+
+## Quick Start
+
+```bash
+# Analyse your existing .devcontainer/ (prints a report, writes nothing)
+npx container-superposition adopt --dry-run
+
+# Run the analysis and write the generated files
+npx container-superposition adopt
+
+# Force-overwrite any existing superposition.json / custom/ files
+npx container-superposition adopt --force
+```
+
+## Docker Compose Devcontainers
+
+`adopt` fully supports compose-based devcontainers. It reads the
+`dockerComposeFile` field in `devcontainer.json` to locate the right compose
+file(s), including:
+
+- **Single file** (string): `"dockerComposeFile": "docker-compose.yml"`
+- **Multiple files** (array): `"dockerComposeFile": ["base.yml", "override.yml"]`
+- **Relative paths** pointing outside the `.devcontainer/` directory:
+  `"dockerComposeFile": "../docker-compose.yml"`
+
+All referenced compose files are analysed. Every service with a recognised
+image (postgres, redis, grafana, jaeger, …) is mapped to the corresponding
+overlay. Services with no overlay equivalent are written to
+`custom/docker-compose.patch.yml` so they are preserved across regenerations.
+
+## How It Works
+
+### Detection
+
+The command builds its detection tables **dynamically from the overlay registry** — there are no hardcoded overlay names. For every overlay it reads:
+
+| Source                                                         | What is extracted         |
+| -------------------------------------------------------------- | ------------------------- |
+| `devcontainer.patch.json` → `features`                         | Feature URI → overlay ID  |
+| `devcontainer.patch.json` → `customizations.vscode.extensions` | Extension ID → overlay ID |
+| `docker-compose.yml` → service `image`                         | Image prefix → overlay ID |
+
+When multiple overlays share the same feature (e.g. both `nodejs` and `bun`
+include the Node.js devcontainer feature), the one whose ID best matches the
+feature's own name wins.
+
+### Detection signals (in priority order)
+
+1. **Devcontainer features** — e.g. `ghcr.io/devcontainers/features/node:1` → `nodejs` (confidence: **exact**)
+2. **Docker Compose service images** — e.g. `postgres:16-alpine` → `postgres` (confidence: **exact**)
+3. **VS Code extensions** — e.g. `ms-python.python` → `python` (confidence: **heuristic**)
+4. **Remote environment variables** — e.g. `POSTGRES_*` → `postgres` (confidence: **heuristic**)
+
+### Unmatched items → `custom/`
+
+Anything that cannot be mapped to an overlay is preserved in the `custom/`
+directory, which is merged automatically on every `regen`:
+
+| Unmatched item                                  | Written to                                                            |
+| ----------------------------------------------- | --------------------------------------------------------------------- |
+| Unknown features                                | `custom/devcontainer.patch.json` → `features`                         |
+| Unknown VS Code extensions                      | `custom/devcontainer.patch.json` → `customizations.vscode.extensions` |
+| Custom `mounts`                                 | `custom/devcontainer.patch.json` → `mounts`                           |
+| Non-default `remoteUser`                        | `custom/devcontainer.patch.json` → `remoteUser`                       |
+| Custom `postCreateCommand` / `postStartCommand` | `custom/devcontainer.patch.json`                                      |
+| Unknown compose services                        | `custom/docker-compose.patch.yml` → `services`                        |
+
+## Backup Behaviour
+
+The same backup logic as `regen` is used:
+
+| Condition                    | What happens                   |
+| ---------------------------- | ------------------------------ |
+| Inside a git repo (default)  | No backup — git tracks history |
+| Outside a git repo (default) | Backup created automatically   |
+| `--backup` flag              | Backup always created          |
+| `--no-backup` flag           | Backup always skipped          |
+
+Backups are placed next to the `.devcontainer/` directory as
+`.devcontainer.backup-<timestamp>/`, and the corresponding glob patterns are
+automatically added to `.gitignore`.
+
+## Options
+
+| Option                | Description                                                                  |
+| --------------------- | ---------------------------------------------------------------------------- |
+| `-d, --dir <path>`    | Path to the existing `.devcontainer/` directory (default: `./.devcontainer`) |
+| `--dry-run`           | Print the analysis without writing any files                                 |
+| `--force`             | Overwrite existing `superposition.json` / `custom/` files                    |
+| `--backup`            | Force a backup even when inside a git repo                                   |
+| `--no-backup`         | Disable backup creation even when it would normally be performed             |
+| `--backup-dir <path>` | Custom backup directory location                                             |
+| `--json`              | Output analysis as JSON (useful for scripting)                               |
+
+## Example Output
+
+```
+╭──────────────────────╮
+│  🔍 Adopt Analysis   │
+╰──────────────────────╯
+
+Analysing .devcontainer/devcontainer.json...
+Analysing .devcontainer/docker-compose.yml...
+
+Detected features / services → suggested overlays
+────────────────────────────────────────────────────────────────────────────────
+Source                                                    →   Overlay               Confidence
+────────────────────────────────────────────────────────────────────────────────────────────────
+ghcr.io/devcontainers/features/node:1                     →   nodejs                exact
+service: postgres (image: postgres:16-alpine)             →   postgres              exact
+service: redis (image: redis:7-alpine)                    →   redis                 exact
+
+Items with no overlay equivalent → custom/
+────────────────────────────────────────────────────────────────────────────────
+Source                                                      Action
+────────────────────────────────────────────────────────────────────────────────────────────────
+ghcr.io/corp/internal-tools:1                               No overlay covers this feature — preserve in custom/devcontainer.patch.json
+service: my-app (image: my-registry/my-app:latest)          No overlay covers this service — preserve in custom/docker-compose.patch.yml
+
+Suggested command:
+  container-superposition init --stack compose --language nodejs --database postgres,redis
+
+💡 Custom patches will be written to .devcontainer/custom/ to preserve
+   any configuration that has no overlay equivalent.
+```
+
+## After Adopt
+
+Once `adopt` has run:
+
+1. **Review `superposition.json`** — verify the detected overlays are correct; add or remove as needed.
+2. **Review `custom/` patches** — inspect what was preserved and trim anything no longer needed.
+3. **Regenerate** — rebuild your `.devcontainer/` from the manifest:
+    ```bash
+    npx container-superposition regen
+    ```
+4. **Commit `superposition.json`** and, if applicable, `custom/` patches.
+
+## JSON Output
+
+Use `--json` to get machine-readable output for scripting or CI workflows:
+
+```bash
+npx container-superposition adopt --dry-run --json | jq .suggestedOverlays
+```
+
+The JSON object contains:
+
+```jsonc
+{
+    "dir": "/absolute/path/to/.devcontainer",
+    "detections": [
+        {
+            "source": "ghcr.io/devcontainers/features/node:1",
+            "overlayId": "nodejs",
+            "confidence": "exact",
+            "sourceType": "feature",
+        },
+        // ...
+    ],
+    "unmatchedItems": [
+        {
+            "source": "ghcr.io/corp/internal-tools:1",
+            "reason": "No overlay covers this feature — preserve in custom/devcontainer.patch.json",
+        },
+        // ...
+    ],
+    "customDevcontainerPatch": {
+        /* or null */
+    },
+    "customComposePatch": {
+        /* or null */
+    },
+    "suggestedStack": "compose",
+    "suggestedOverlays": ["nodejs", "postgres", "redis"],
+    "suggestedCommand": "container-superposition init --stack compose --language nodejs --database postgres,redis",
+}
+```
+
+## See Also
+
+- [Team Workflow](team-workflow.md) — Manifest-first team collaboration workflow
+- [Custom Patches](custom-patches.md) — How `custom/` patches are merged
+- [Workflows and Regeneration](workflows.md) — Regeneration and backup details
+- [Quick Reference](quick-reference.md) — All commands at a glance

package/docs/custom-patches.md

@@ -417,7 +417,7 @@ The `superposition.json` manifest tracks whether customizations are present:
 
 ```json
 {
-    "version": "0.1.0",
+    "version": "X.Y.Z",
     "baseTemplate": "compose",
     "overlays": ["nodejs", "postgres"],
     "customizations": {

package/docs/discovery-commands.md

@@ -223,6 +223,9 @@ The `plan` command shows a dry-run preview of what will be generated, including
 ```bash
 # Preview generation for postgres and grafana
 npx container-superposition plan --stack compose --overlays postgres,grafana
+
+# Preview generation from an existing manifest
+npx container-superposition plan --from-manifest .devcontainer/superposition.json
 ```
 
 **Output:**
@@ -265,12 +268,18 @@ Files to Create/Modify:
 
 ### Required Options
 
-- `--stack <type>` - Base template: `plain` or `compose`
+- `--stack <type>` - Base template: `plain` or `compose` when planning from explicit overlays
 - `--overlays <list>` - Comma-separated list of overlay IDs
 
+### Manifest Input
+
+- `--from-manifest <path>` - Load stack and overlay roots from an existing `superposition.json`
+- Use either `--overlays` or `--from-manifest` for a given `plan` invocation
+
 ### Optional Options
 
 - `--port-offset <number>` - Add offset to all exposed ports
+- `--verbose` - Explain why each overlay was included in the resolved plan
 - `--json` - Output as JSON
 
 ### Port Offset Example
@@ -308,6 +317,35 @@ Auto-Added Dependencies:
   + prometheus (Prometheus)
 ```
 
+### Verbose Dependency Narration
+
+Add `--verbose` when you want the plan to explain why each overlay appears in the final result:
+
+```bash
+npx container-superposition plan --stack compose --overlays grafana --verbose
+```
+
+**Additional output:**
+
+```text
+Dependency Resolution:
+  grafana (Grafana)
+    - selected directly by the user
+  prometheus (Prometheus)
+    - required by grafana
+    - path: grafana -> prometheus
+```
+
+This keeps the standard summary intact and adds the reasoning behind direct selections, auto-added dependencies, and failure notes when resolution cannot complete cleanly.
+
+The same verbose explanation works for existing manifests:
+
+```bash
+npx container-superposition plan --from-manifest .devcontainer/superposition.json --verbose
+```
+
+In manifest mode, overlays loaded from `superposition.json` are treated as the explicit root set and auto-added dependencies are still explained separately.
+
 ### Conflict Detection
 
 The `plan` command detects conflicts before generation:
@@ -334,6 +372,12 @@ npx container-superposition plan --stack compose --overlays docker-in-docker,doc
 ```bash
 # Get plan as JSON
 npx container-superposition plan --stack compose --overlays postgres --json
+
+# Include structured dependency explanations
+npx container-superposition plan --stack compose --overlays grafana --json --verbose
+
+# Include structured dependency explanations from a manifest
+npx container-superposition plan --from-manifest .devcontainer/superposition.json --json --verbose
 ```
 
 **Example output:**
@@ -357,11 +401,19 @@ npx container-superposition plan --stack compose --overlays postgres --json
         ".devcontainer/docker-compose.yml",
         ".devcontainer/.env.example",
         ".devcontainer/README.md"
-    ],
-    "portOffset": 0
+    ]
 }
 ```
 
+When `--verbose` is also present, the JSON output includes a `verbose` object with:
+
+- one entry per included overlay
+- direct-vs-dependency selection type
+- input mode metadata for overlay-list vs manifest planning
+- parent reasons for inclusion
+- ordered dependency paths for transitive inclusions
+- resolution notes for skipped overlays or conflicts
+
 ## Scripting Examples
 
 ### Export All Overlays to JSON

package/docs/examples.md

@@ -10,6 +10,37 @@ npm run init
 
 Follow the prompts to select your stack, database, tools, and output location.
 
+## Declarative Project Config
+
+```yaml
+stack: compose
+language:
+    - nodejs
+database:
+    - postgres
+outputPath: ./.devcontainer
+customizations:
+    environment:
+        APP_ENV: development
+    devcontainerPatch:
+        features:
+            ghcr.io/devcontainers-extra/features/apt-get-packages:1:
+                packages: jq
+```
+
+```bash
+npm run init -- --no-interactive
+```
+
+Creates the same generated output you would get from equivalent clean-generation
+input, while keeping the setup intent in version control.
+
+```bash
+npm run init -- regen
+```
+
+Regenerates from the repository project file by default when one exists.
+
 ## Non-Interactive Examples
 
 ### .NET with PostgreSQL
@@ -411,11 +442,14 @@ npm run init -- --from-manifest ./superposition.json
 
 ### Non-Interactive Regeneration
 
-Regenerate exact same setup (useful for updating to latest overlay versions):
+Use `regen` when you want deterministic replay of a persisted source:
 
 ```bash
-# Regenerate with exact same selections, skip confirmation, no backup
-npm run init -- --from-manifest ./superposition.json --yes --no-backup
+# Regenerate with exact same selections from a manifest, no backup
+npm run init -- regen --from-manifest ./superposition.json --no-backup
+
+# Or let regen use the repository project file when present
+npm run init -- regen
 ```
 
 **Use cases:**
@@ -463,7 +497,7 @@ git push
 # Developer 2: Clone and regenerate from manifest
 git clone <repo>
 npm install
-npm run init -- --from-manifest ./superposition.json --yes
+npm run init -- regen --from-manifest ./superposition.json
 # Gets exact same devcontainer setup
 ```
 
@@ -481,7 +515,7 @@ The manifest stores and restores:
 
 ```json
 {
-    "version": "0.1.0",
+    "version": "X.Y.Z",
     "generated": "2026-02-08T10:00:00Z",
     "baseTemplate": "compose",
     "baseImage": "bookworm",
@@ -572,5 +606,5 @@ mv prod/superposition.json prod-superposition.json
 
 # Now you have three manifests for different environments
 # Regenerate any environment from its manifest
-npm run init -- --from-manifest ./dev-superposition.json --yes --output ./dev
+npm run init -- regen --from-manifest ./dev-superposition.json --output ./dev
 ```

package/docs/filesystem-contract.md

@@ -0,0 +1,58 @@
+# Filesystem Contract
+
+This describes what the tool writes and which files are safe to edit.
+
+## What Gets Written
+
+```
+your-project/
+├── .devcontainer/               # Main devcontainer directory
+│   ├── devcontainer.json        # Container configuration
+│   ├── docker-compose.yml       # Services (compose stack only)
+│   ├── .env.example             # Environment variable templates
+│   ├── ports.json               # Port documentation and connection strings
+│   ├── scripts/                 # Setup and verification scripts
+│   │   ├── post-create.sh       # Runs once when container is created
+│   │   └── post-start.sh        # Runs every time container starts
+│   └── custom/                  # Your customizations (preserved across regen)
+│       ├── devcontainer.patch.json
+│       └── docker-compose.patch.yml
+├── superposition.json           # Manifest file (enables regeneration)
+└── .devcontainer.backup-*/      # Automatic backups (gitignored)
+```
+
+## Files You Should Customize
+
+- `.devcontainer/.env` or `.env` (copied from `.env.example`)
+- `.devcontainer/custom/` (your patches and scripts)
+
+## Files Safe to Edit Directly
+
+- `.devcontainer/custom/devcontainer.patch.json`
+- `.devcontainer/custom/docker-compose.patch.yml`
+- `.devcontainer/custom/environment.env`
+- `.devcontainer/custom/scripts/*`
+
+## Files Regenerated (Do Not Edit Directly)
+
+- `.devcontainer/devcontainer.json`
+- `.devcontainer/docker-compose.yml`
+- `.devcontainer/scripts/*`
+
+## Files You Should Commit
+
+- `superposition.json`
+- `.devcontainer/` (generated configuration)
+- `.devcontainer/custom/` (project-specific patches)
+- `.devcontainer/.env.example`
+
+## Files in .gitignore
+
+```
+# Environment secrets (never commit)
+.env
+.devcontainer/.env
+
+# Regeneration backups (local only)
+.devcontainer.backup-*
+```

package/docs/hash.md

@@ -0,0 +1,183 @@
+# Hash Command
+
+The `hash` command produces a stable, deterministic fingerprint for a devcontainer configuration.
+It lets you verify that two environments are equivalent, detect drift in CI, and commit a reproducible
+stamp alongside your `superposition.json` manifest.
+
+## Overview
+
+```bash
+# From CLI options
+npx container-superposition hash --stack compose --overlays dotnet,postgres,redis
+
+# Reading from an existing manifest (auto-discovers superposition.json)
+npx container-superposition hash
+
+# Machine-readable output
+npx container-superposition hash --stack compose --overlays dotnet,postgres,redis --json
+
+# Write full hash to .devcontainer/superposition.hash
+npx container-superposition hash --write
+```
+
+## What Is Hashed
+
+The fingerprint is a SHA-256 digest of a canonical JSON object with the following fields:
+
+| Field      | Source                                        | Notes                                                  |
+| ---------- | --------------------------------------------- | ------------------------------------------------------ |
+| `stack`    | `--stack` flag or manifest `baseTemplate`     | `plain` or `compose`                                   |
+| `overlays` | Resolved overlay list (alphabetically sorted) | Includes auto-resolved dependencies                    |
+| `preset`   | `--preset` flag or manifest `preset`          | `null` when no preset                                  |
+| `base`     | `--base` flag or manifest `baseImage`         | e.g. `bookworm`, `alpine`                              |
+| `tool`     | Tool version (major.minor only)               | Stable across patch releases; truncated before hashing |
+
+Keys in the canonical object are sorted alphabetically and the overlay list is sorted before hashing,
+so the result is identical regardless of the order overlays are provided.
+
+## Output
+
+### Text Output (default)
+
+```
+╭ Environment Fingerprint ──────────────────────────╮
+│                                                   │
+│   stack        compose                            │
+│   overlays     dotnet, postgres, redis            │
+│   preset       (none)                             │
+│   base         bookworm                           │
+│   tool         0.1.3                              │
+│                                                   │
+│   hash         53ed972d                           │
+│                                                   │
+╰───────────────────────────────────────────────────╯
+```
+
+Auto-resolved dependencies are shown with an `(auto)` label:
+
+```
+overlays     grafana, prometheus (auto)
+```
+
+### JSON Output (`--json`)
+
+```json
+{
+    "stack": "compose",
+    "overlays": ["dotnet", "postgres", "redis"],
+    "preset": null,
+    "base": "bookworm",
+    "tool": "0.1.3",
+    "hash": "53ed972d",
+    "hashFull": "53ed972da2ba0712ae15b4003aa46234e7eeba2e977e7a397453740202ebbea4"
+}
+```
+
+- `hash` — first 8 hex characters, suitable for display and badges
+- `hashFull` — full 64-character SHA-256 hex digest, recommended for CI comparisons
+
+## Options
+
+| Option                | Description                                        |
+| --------------------- | -------------------------------------------------- |
+| `--stack <type>`      | Base template: `plain` or `compose`                |
+| `--overlays <list>`   | Comma-separated overlay IDs                        |
+| `--preset <id>`       | Preset ID (optional, reflected in hash)            |
+| `--base <image>`      | Base image/distro (e.g. `bookworm`, `alpine`)      |
+| `--manifest <path>`   | Path to a specific `superposition.json`            |
+| `-o, --output <path>` | Directory to write hash file (used with `--write`) |
+| `--write`             | Write hash to `.devcontainer/superposition.hash`   |
+| `--json`              | Output as JSON for scripting                       |
+
+When `--stack`/`--overlays` are omitted the command searches for `superposition.json` in:
+
+1. Current directory (`superposition.json`)
+2. `.devcontainer/superposition.json`
+3. Parent directory (`../superposition.json`)
+
+## The `--write` Flag
+
+```bash
+npx container-superposition hash --write
+```
+
+Writes the **full** 64-character hash to `.devcontainer/superposition.hash` (one line, no trailing
+whitespace). Commit this file alongside `superposition.json`:
+
+```
+.devcontainer/
+├── devcontainer.json
+├── superposition.json
+└── superposition.hash   ← commit this
+```
+
+Use a custom output directory with `-o`:
+
+```bash
+npx container-superposition hash --write -o ./infra/.devcontainer
+```
+
+## CI Drift Detection
+
+Detect when the environment has changed since the last commit:
+
+```yaml
+- name: Verify environment fingerprint
+  run: |
+      EXPECTED=$(cat .devcontainer/superposition.hash)
+      ACTUAL=$(npx container-superposition hash --json | jq -r .hashFull)
+      [ "$EXPECTED" = "$ACTUAL" ] || (echo "Environment drift detected" && exit 1)
+```
+
+Or using the short hash stored in a badge/README:
+
+```yaml
+- name: Verify short fingerprint
+  run: |
+      EXPECTED="53ed972d"
+      ACTUAL=$(npx container-superposition hash --json | jq -r .hash)
+      [ "$EXPECTED" = "$ACTUAL" ] || (echo "Environment drift detected" && exit 1)
+```
+
+## Stability Guarantees
+
+- **Same inputs → same hash** — guaranteed for any given tool version series
+- **Overlay order is irrelevant** — `postgres,redis` hashes identically to `redis,postgres`
+- **Dependencies are included** — auto-resolved dependencies affect the hash (as they affect the environment)
+- **Patch versions are ignored** — `0.1.3` and `0.1.99` produce the same hash; `0.2.0` does not
+- **Hash changes when any input changes** — stack, overlays, preset, base image, or minor/major tool version
+
+## Examples
+
+### Fingerprint a Standard Web API Stack
+
+```bash
+npx container-superposition hash \
+  --stack compose \
+  --overlays nodejs,postgres,redis
+```
+
+### Read from Manifest and Write Hash File
+
+```bash
+# Run from the project root (manifest at .devcontainer/superposition.json)
+npx container-superposition hash --write
+```
+
+### Compare Two Configurations
+
+```bash
+# Project A
+HASH_A=$(npx container-superposition hash --stack compose --overlays nodejs,postgres --json | jq -r .hash)
+
+# Project B
+HASH_B=$(npx container-superposition hash --manifest ./project-b/.devcontainer/superposition.json --json | jq -r .hash)
+
+[ "$HASH_A" = "$HASH_B" ] && echo "Environments are equivalent" || echo "Environments differ"
+```
+
+## Related Commands
+
+- [`plan`](discovery-commands.md#plan-command) — Preview what will be generated
+- [`list`](discovery-commands.md#list-command) — Browse available overlays
+- [`explain`](discovery-commands.md#explain-command) — Deep dive into a specific overlay

package/docs/minimal-and-editor.md

@@ -243,7 +243,7 @@ Both settings are stored in `superposition.json`:
 
 ```json
 {
-    "version": "0.1.0",
+    "version": "X.Y.Z",
     "generated": "2026-02-13T09:00:00.000Z",
     "minimal": true,
     "editor": "none",