container-superposition 0.1.8 → 0.1.9

package/docs/specs/taxonomy.md

@@ -0,0 +1,186 @@
+# Feature Taxonomy
+
+This index maps all specs to their feature categories. Maintained by the `tool-pm` agent — update whenever a new spec is added.
+
+## Taxonomy categories
+
+```
+OVERLAY          — Adding or modifying individual overlays
+  OVERLAY-NEW    — New overlay
+  OVERLAY-ENRICH — Enriching an existing overlay
+  OVERLAY-FIX    — Correctness fix to an overlay
+
+PRESET           — Preset bundles
+  PRESET-NEW     — New preset
+  PRESET-ENRICH  — Enriching an existing preset
+
+COMPOSER         — Core composition pipeline (composer.ts, merge logic, imports)
+  COMPOSER-FEAT  — New composition behaviour
+  COMPOSER-FIX   — Bug fix
+
+SCHEMA           — Overlay manifest schema, types, validation
+  SCHEMA-FIELD   — New field in overlay.yml or related types
+  SCHEMA-VALID   — New validation rule
+
+CLI              — Command-line interface (init, regen, adopt, doctor)
+  CLI-COMMAND    — New command or subcommand
+  CLI-FLAG       — New flag on existing command
+  CLI-UX         — Interactive prompt or output improvement
+
+QUESTIONNAIRE    — Overlay selection logic
+  QUEST-SECTION  — New questionnaire section
+  QUEST-LOGIC    — Selection / dependency resolution logic
+
+DOCS             — Documentation
+  DOCS-SPEC      — Spec meta
+  DOCS-GUIDE     — Developer or user guide
+  DOCS-API       — Generated reference
+
+INFRA            — Project infrastructure (tests, CI, tooling)
+  INFRA-TEST     — Test coverage
+  INFRA-LINT     — Lint / formatter
+  INFRA-BUILD    — Build system
+```
+
+---
+
+## OVERLAY — Individual overlays
+
+### OVERLAY-NEW
+
+| Spec                                                     | Title                                 | Status |
+| -------------------------------------------------------- | ------------------------------------- | ------ |
+| [003-mkdocs2-overlay](003-mkdocs2-overlay/spec.md)       | MkDocs 2.x Overlay                    | Final  |
+| [005-cuda-overlay](005-cuda-overlay/spec.md)             | CUDA (NVIDIA GPU) Overlay             | Final  |
+| [006-rocm-overlay](006-rocm-overlay/spec.md)             | ROCm (AMD GPU) Overlay                | Final  |
+| [012-ollama-cli-overlay](012-ollama-cli-overlay/spec.md) | Split Ollama Service and CLI Overlays | Final  |
+
+### OVERLAY-ENRICH
+
+_No specs yet._
+
+### OVERLAY-FIX
+
+_No specs yet._
+
+---
+
+## PRESET — Preset bundles
+
+### PRESET-NEW
+
+_No specs yet._
+
+### PRESET-ENRICH
+
+_No specs yet._
+
+---
+
+## COMPOSER — Composition pipeline
+
+### COMPOSER-FEAT
+
+| Spec                                                                       | Title                                               | Status   |
+| -------------------------------------------------------------------------- | --------------------------------------------------- | -------- |
+| [010-compose-env-materialization](010-compose-env-materialization/spec.md) | Compose Env Materialization and Env Template Naming | Approved |
+
+### COMPOSER-FIX
+
+_No specs yet._
+
+---
+
+## SCHEMA — Overlay manifest schema
+
+### SCHEMA-FIELD
+
+| Spec                                                     | Title                                     | Status |
+| -------------------------------------------------------- | ----------------------------------------- | ------ |
+| [011-overlay-parameters](011-overlay-parameters/spec.md) | Overlay Parameters with Safe Substitution | Final  |
+
+### SCHEMA-VALID
+
+_No specs yet._
+
+---
+
+## CLI — Command-line interface
+
+### CLI-COMMAND
+
+| Spec                                     | Title                                    | Status |
+| ---------------------------------------- | ---------------------------------------- | ------ |
+| [004-doctor-fix](004-doctor-fix/spec.md) | `doctor --fix` — Interactive Auto-Repair | Final  |
+
+### CLI-FLAG
+
+| Spec                                                               | Title                         | Status |
+| ------------------------------------------------------------------ | ----------------------------- | ------ |
+| [007-target-aware-generation](007-target-aware-generation/spec.md) | Target-Aware Generation       | Final  |
+| [017-doctor-dry-run](017-doctor-dry-run/spec.md)                   | Doctor `--fix --dry-run` Flag | Draft  |
+
+### CLI-UX
+
+| Spec                                                                                         | Title                                      | Status |
+| -------------------------------------------------------------------------------------------- | ------------------------------------------ | ------ |
+| [001-verbose-plan-graph](001-verbose-plan-graph/spec.md)                                     | Verbose Plan Graph                         | Final  |
+| [013-doctor-dependency-check](013-doctor-dependency-check/spec.md)                           | Doctor Overlay Dependency Resolution Check | Draft  |
+| [014-doctor-compose-port-cross-validation](014-doctor-compose-port-cross-validation/spec.md) | Doctor Compose / Port Cross-Validation     | Draft  |
+| [015-doctor-env-example-drift](015-doctor-env-example-drift/spec.md)                         | Doctor `.env.example` Drift Detection      | Draft  |
+| [016-doctor-reproducibility-check](016-doctor-reproducibility-check/spec.md)                 | Doctor Reproducibility Check               | Draft  |
+
+---
+
+## QUESTIONNAIRE — Overlay selection
+
+### QUEST-SECTION
+
+_No specs yet._
+
+### QUEST-LOGIC
+
+_No specs yet._
+
+---
+
+## DOCS — Documentation
+
+### DOCS-SPEC
+
+_No specs yet._
+
+### DOCS-GUIDE
+
+_No specs yet._
+
+### DOCS-API
+
+_No specs yet._
+
+---
+
+## INFRA — Project infrastructure
+
+### INFRA-TEST
+
+_No specs yet._
+
+### INFRA-LINT
+
+_No specs yet._
+
+### INFRA-BUILD
+
+_No specs yet._
+
+---
+
+## PROJECT — Project-level configuration
+
+| Spec                                                                   | Title                                       | Status   |
+| ---------------------------------------------------------------------- | ------------------------------------------- | -------- |
+| [002-superposition-config-file](002-superposition-config-file/spec.md) | Project Configuration File                  | Final    |
+| [008-project-file-canonical](008-project-file-canonical/spec.md)       | Project File Canonical Form                 | Approved |
+| [009-project-env](009-project-env/spec.md)                             | Unified Project-Level Environment Variables | Approved |
+| [018-init-project-file](018-init-project-file/spec.md)                 | `init --project-file`                       | Final    |

package/overlays/.presets/full-observability.yml

@@ -0,0 +1,113 @@
+# Full Observability Stack Preset
+# Complete metrics, logs, traces, and alerting for any project
+
+id: full-observability
+name: Full Observability Stack
+description: Prometheus, Grafana, Loki, Jaeger/Tempo, OpenTelemetry Collector, Alertmanager, and Promtail — bolt-on monitoring for any project
+type: meta
+category: preset
+supports: [compose] # Requires Docker Compose for all sidecar services
+tags: [preset, observability, monitoring, metrics, logging, tracing, prometheus, grafana, loki]
+
+selects:
+    required:
+        - prometheus
+        - grafana
+        - loki
+        - otel-collector
+        - alertmanager
+        - promtail
+
+    userChoice: {}
+
+parameters:
+    tracing:
+        description: 'Distributed tracing backend'
+        default: jaeger
+        options:
+            - id: jaeger
+              overlays: [jaeger]
+              description: 'Jaeger — battle-tested, native OTLP support, built-in UI'
+            - id: tempo
+              overlays: [tempo]
+              description: 'Grafana Tempo — stores traces in object storage, integrates with Grafana'
+            - id: both
+              overlays: [jaeger, tempo]
+              description: 'Both Jaeger and Tempo (useful for migration)'
+            - id: none
+              overlays: []
+              description: 'No tracing backend — collector still accepts spans'
+
+glueConfig:
+    environment:
+        OTEL_EXPORTER_OTLP_ENDPOINT: 'http://otel-collector:4317'
+        OTEL_METRICS_EXPORTER: 'otlp'
+        OTEL_TRACES_EXPORTER: 'otlp'
+        OTEL_LOGS_EXPORTER: 'otlp'
+
+    portMappings:
+        grafana: 3000
+        prometheus: 9090
+        jaeger-ui: 16686
+        alertmanager: 9093
+        otel-grpc: 4317
+        otel-http: 4318
+
+    readme: |
+        ## Full Observability Stack
+
+        This devcontainer adds a complete observability platform alongside your existing services.
+
+        ### Services
+
+        | Service | Port | Purpose |
+        |---------|------|---------|
+        | Grafana | 3000 | Unified dashboards (metrics + logs + traces) |
+        | Prometheus | 9090 | Metrics collection and storage |
+        | Loki | 3100 | Log aggregation |
+        | Promtail | — | Log shipping agent (reads container logs) |
+        | OTel Collector | 4317 / 4318 | Telemetry pipeline (gRPC / HTTP) |
+        | Alertmanager | 9093 | Alert routing and silencing |
+        | Jaeger / Tempo | 16686 | Distributed tracing UI / backend |
+
+        ### Access
+
+        - **Grafana**: http://localhost:3000 — default login `admin` / `admin`
+        - **Prometheus**: http://localhost:9090
+        - **Alertmanager**: http://localhost:9093
+        - **Jaeger UI** _(if selected)_: http://localhost:16686
+
+        ### Instrumenting Your Application
+
+        Configure your service to send telemetry to the OTel Collector:
+
+        ```bash
+        # Already set in your environment:
+        OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4317"
+        OTEL_METRICS_EXPORTER="otlp"
+        OTEL_TRACES_EXPORTER="otlp"
+        OTEL_LOGS_EXPORTER="otlp"
+        ```
+
+        Install the OpenTelemetry SDK for your language, then traces and metrics
+        will flow automatically: App → OTel Collector → Jaeger / Prometheus / Loki.
+
+        ### Grafana Datasources
+
+        The following datasources are pre-configured in Grafana:
+
+        - Prometheus (metrics)
+        - Loki (logs)
+        - Jaeger or Tempo (traces, if selected)
+
+        ### Alertmanager
+
+        Add alert rules to Prometheus by creating a `prometheus-rules.yml` file
+        and mounting it into the Prometheus service, or use the Grafana alerting UI.
+
+        ### Next Steps
+
+        - Browse the Grafana Explore tab to query logs and traces
+        - Import community dashboards from grafana.com/grafana/dashboards
+        - Configure Alertmanager routes in `.devcontainer/alertmanager.yml`
+        - Add your service's metrics endpoint to `prometheus-scrape-configs.yml`

package/overlays/.presets/k8s-dev.yml

@@ -0,0 +1,174 @@
+# Kubernetes Development Preset
+# Local Kubernetes cluster + dev loop tooling, language-agnostic
+
+id: k8s-dev
+name: Kubernetes Development
+description: Local Kubernetes cluster with fast inner-loop tooling — choose your cluster provider and dev-loop tool
+type: meta
+category: preset
+supports: [] # Works with both plain and compose
+tags: [preset, kubernetes, k8s, kind, k3d, skaffold, tilt, devloop, kubectl, helm]
+
+selects:
+    required:
+        - kubectl-helm
+        - docker-in-docker
+        - modern-cli-tools
+
+    userChoice: {}
+
+parameters:
+    cluster:
+        description: 'Local Kubernetes cluster provider'
+        default: k3d
+        options:
+            - id: k3d
+              overlays: [k3d]
+              description: 'k3d (k3s in Docker) — fastest startup, lowest memory, ideal for CI'
+            - id: kind
+              overlays: [kind]
+              description: 'kind (Kubernetes in Docker) — official CNCF tool, most compatible'
+
+    devloop:
+        description: 'Inner-loop dev tool (watch → build → deploy on save)'
+        default: tilt
+        options:
+            - id: tilt
+              overlays: [tilt]
+              description: 'Tilt — live UI, smart rebuilds, port-forward management'
+            - id: skaffold
+              overlays: [skaffold]
+              description: 'Skaffold — declarative YAML, CI-compatible, multi-deployer support'
+            - id: none
+              overlays: []
+              description: 'No dev-loop tool — use kubectl directly'
+
+glueConfig:
+    environment:
+        KUBECONFIG: '/home/vscode/.kube/config'
+        KUBECTL_CONTEXT: 'local'
+
+    portMappings:
+        app: 8080
+        tilt-ui: 10350
+
+    readme: |
+        ## Kubernetes Development Stack
+
+        This devcontainer provides a complete local Kubernetes development environment.
+
+        ### Tools
+
+        | Tool | Purpose |
+        |------|---------|
+        | kubectl + Helm | Kubernetes CLI and package manager |
+        | docker-in-docker | Run Docker inside the devcontainer to build images |
+        | k3d / kind | Provision a local Kubernetes cluster |
+        | Tilt / Skaffold | Watch → build → deploy inner loop |
+        | Modern CLI tools | `jq`, `yq`, `bat`, `fd`, `rg` for working with manifests |
+
+        ### Cluster Management
+
+        #### k3d (default)
+
+        ```bash
+        # Create cluster
+        k3d cluster create dev --port "8080:80@loadbalancer"
+
+        # List clusters
+        k3d cluster list
+
+        # Delete cluster
+        k3d cluster delete dev
+        ```
+
+        #### kind
+
+        ```bash
+        # Create cluster
+        kind create cluster --name dev
+
+        # List clusters
+        kind get clusters
+
+        # Delete cluster
+        kind delete cluster --name dev
+        ```
+
+        ### Inner-Loop Workflow
+
+        #### Tilt
+
+        Create a `Tiltfile` in your project root:
+
+        ```python
+        # Tiltfile
+        docker_build('my-app', '.')
+        k8s_yaml('k8s/')
+        k8s_resource('my-app', port_forwards=8080)
+        ```
+
+        Then run:
+
+        ```bash
+        tilt up
+        # Open http://localhost:10350 for the Tilt UI
+        ```
+
+        #### Skaffold
+
+        Create a `skaffold.yaml` in your project root:
+
+        ```yaml
+        apiVersion: skaffold/v4beta11
+        kind: Config
+        build:
+            artifacts:
+                - image: my-app
+        manifests:
+            rawYaml:
+                - k8s/*.yaml
+        ```
+
+        Then run:
+
+        ```bash
+        skaffold dev
+        ```
+
+        ### Helm Quick Start
+
+        ```bash
+        # Add a chart repository
+        helm repo add bitnami https://charts.bitnami.com/bitnami
+        helm repo update
+
+        # Install a chart
+        helm install my-release bitnami/postgresql
+
+        # Upgrade
+        helm upgrade my-release bitnami/postgresql --set auth.password=secret
+        ```
+
+        ### kubectl Tips
+
+        ```bash
+        # Watch all resources
+        kubectl get all -A -w
+
+        # Port-forward a service
+        kubectl port-forward svc/my-app 8080:80
+
+        # Inspect manifest with yq
+        kubectl get deployment my-app -o yaml | yq '.spec.template.spec.containers[0]'
+
+        # Live logs
+        kubectl logs -f -l app=my-app
+        ```
+
+        ### Next Steps
+
+        - Add a language overlay (`nodejs`, `go`, `python`, etc.) for your application runtime
+        - Add the `k8s-operator-dev` preset if you are building Kubernetes operators
+        - Configure image registry credentials for pushing built images
+        - Add Prometheus + Grafana overlays for in-cluster monitoring

package/overlays/.presets/local-llm.yml

@@ -0,0 +1,105 @@
+# Local LLM Stack Preset
+# Run local language models with a browser chat UI
+
+id: local-llm
+name: Local LLM Stack
+description: Local inference with Ollama and Open WebUI — pull any model and chat without an API key
+type: meta
+category: preset
+supports: [compose] # Requires Docker Compose for Ollama service
+tags: [preset, ai, llm, ollama, open-webui, local-inference]
+
+selects:
+    required:
+        - ollama
+        - ollama-cli
+        - open-webui
+
+    userChoice: {}
+
+parameters:
+    gpu:
+        description: 'GPU acceleration (optional — CPU works without it)'
+        default: none
+        options:
+            - id: none
+              overlays: []
+              description: 'CPU only — works on any machine, slower for large models'
+            - id: nvidia
+              overlays: [cuda]
+              description: 'Nvidia GPU via CUDA'
+            - id: amd
+              overlays: [rocm]
+              description: 'AMD GPU via ROCm'
+
+glueConfig:
+    environment:
+        OLLAMA_HOST: 'http://ollama:11434'
+
+    portMappings:
+        ollama-api: 11434
+        open-webui: 3000
+
+    readme: |
+        ## Local LLM Stack
+
+        This devcontainer runs a full local LLM environment — no API key required.
+
+        ### Services
+
+        - **Ollama** — LLM runtime serving models on port 11434
+        - **Open WebUI** — Browser-based chat UI at http://localhost:3000
+        - **ollama-cli** — `ollama` command available in the terminal
+
+        ### Quick Start
+
+        1. Open http://localhost:3000 in your browser
+        2. Sign up with any email (local only — no data leaves your machine)
+        3. Pull a model via the terminal or the UI:
+
+        ```bash
+        # Pull a model
+        ollama pull llama3.2
+
+        # Run interactively in the terminal
+        ollama run llama3.2
+
+        # List pulled models
+        ollama list
+        ```
+
+        ### Recommended Models
+
+        | Model | Size | Use case |
+        |-------|------|----------|
+        | `llama3.2` | 2–8 B | General purpose, fast |
+        | `mistral` | 7 B | Strong reasoning |
+        | `codellama` | 7–34 B | Code generation |
+        | `nomic-embed-text` | 137 M | Embeddings for RAG |
+        | `phi4` | 14 B | Microsoft research model |
+
+        ### Using the API
+
+        ```bash
+        # Chat completion
+        curl http://localhost:11434/api/chat -d '{
+          "model": "llama3.2",
+          "messages": [{"role": "user", "content": "Hello!"}]
+        }'
+
+        # Generate embeddings
+        curl http://localhost:11434/api/embeddings -d '{
+          "model": "nomic-embed-text",
+          "prompt": "Hello world"
+        }'
+        ```
+
+        ### GPU Acceleration
+
+        If you selected a GPU option, ensure the relevant drivers are installed on the host.
+        CPU-only mode works on any machine — expect ~10–30 tokens/sec for 7 B models.
+
+        ### Next Steps
+
+        - Add the `qdrant` overlay and `vector-ai` preset for a full RAG pipeline
+        - Add the `python` overlay to build LLM-powered apps