container-superposition 0.1.6 → 0.1.8

package/README.md

@@ -15,7 +15,7 @@ written.
 ## Quickstart
 
 ```bash
-# Guided questionnaire
+# Guided questionnaire — always writes superposition.yml
 npx container-superposition init
 
 # Declarative project config committed in the repo
@@ -25,13 +25,15 @@ language:
   - nodejs
 database:
   - postgres
+env:
+  APP_ENV: development
 customizations:
-  environment:
-    APP_ENV: development
+  envTemplate:
+    POSTGRES_PASSWORD: postgres
 YAML
 npx container-superposition init --no-interactive
 
-# Regenerate from the repository project file
+# Regenerate from the repository project file (superposition.yml is required)
 npx container-superposition regen
 
 # Or select the project file explicitly
@@ -40,14 +42,17 @@ npx container-superposition regen --from-project
 # Non-interactive example
 npx container-superposition init --stack compose --language nodejs --database postgres
 
+# Write only superposition.yml without generating .devcontainer/
+npx container-superposition init --stack compose --language nodejs --no-scaffold
+
 # Preview before writing files
 npx container-superposition plan --stack compose --overlays nodejs,postgres,grafana
 
 # Explain why dependencies were included
 npx container-superposition plan --stack compose --overlays grafana --verbose
 
-# Explain an existing manifest without re-entering overlays
-npx container-superposition plan --from-manifest .devcontainer/superposition.json --verbose
+# Migrate a manifest-only repo to the project-file model
+npx container-superposition migrate
 ```
 
 ## What It Does
@@ -55,26 +60,30 @@ npx container-superposition plan --from-manifest .devcontainer/superposition.jso
 - Base templates: `plain` (single image) and `compose` (multi-service).
 - Overlays: add languages, databases, observability, cloud tools, dev tools.
 - Composition: merges overlays into a standard `.devcontainer/` you can edit freely.
-- Project config: commit `.superposition.yml` or `superposition.yml` to make team and CI generation declarative.
-    - `regen` uses that project file by default when present
-    - `--from-project` selects it explicitly
-    - conflicting source combinations fail early
-    - `init` stays the editable flow; `regen` is the deterministic replay flow
+- Project config: `superposition.yml` (or `.superposition.yml`) is the **canonical input** for all
+  generation and regeneration flows. Commit it to your repo for reproducible team and CI builds.
+    - `init` always writes `superposition.yml` as its primary output
+    - `regen` reads only the project file — `superposition.json` is an output-only receipt
+    - Repos without a project file should run `cs migrate` once to create one from their manifest
+    - `doctor` compares the project file against the last-generated manifest and reports drift
 
 ## Core Commands
 
-- `init` — generate or modify a devcontainer, optionally starting from a project file or manifest
+- `init` — run the interactive questionnaire; always writes `superposition.yml` and (by default) scaffolds `.devcontainer/`
+    - Add `--no-scaffold` to write only the project file without generating `.devcontainer/`
     - Add `--project-root <path>` to resolve persisted input from a different repository root
-- `regen` — deterministically replay the repository project file or a manifest
+- `regen` — deterministically replay the repository project file (`superposition.yml` required)
     - Add `--project-root <path>` to resolve persisted input from a different repository root
-- `adopt` — migrate an existing `.devcontainer/` to the overlay-based workflow, optionally emitting a repository-root project file
+- `migrate` — one-time migration: creates `superposition.yml` from an existing `superposition.json`
+    - Required for repos that ran `init` before this project-file-first model was introduced
+- `adopt` — migrate an existing `.devcontainer/` to the overlay-based workflow
 - `list` — browse overlays
 - `explain` — overlay details
 - `plan` — preview output
     - Add `--verbose` to narrate dependency resolution and inclusion reasons
     - Add `--from-manifest <path>` to preview an existing manifest with the same explanation model
 - `hash` — deterministic environment fingerprint
-- `doctor` — validate environment
+- `doctor` — validate environment and detect project-file drift
 
 ## Documentation