container-superposition 0.1.4 → 0.1.6

package/overlays/pandoc/README.md

@@ -0,0 +1,279 @@
+# Pandoc PDF Overlay
+
+Adds a complete Markdown → PDF pipeline to your devcontainer, powered by Pandoc, XeLaTeX, and optional Mermaid diagram rendering.
+
+## Features
+
+- **Pandoc 3.x** — Latest release binary from GitHub (not the outdated apt version)
+- **TeX Live / XeLaTeX** — Full Unicode-capable PDF engine (`texlive-xetex`, `texlive-fonts-extra`, `texlive-latex-extra`)
+- **Quality fonts** — Carlito (body), JetBrains Mono (code), Noto Sans Symbols 2 (Unicode fallback) via system packages
+    - Uses the `cross-distro-packages` feature with fallback package names for Carlito (`fonts-carlito|fonts-crosextra-carlito`)
+- **`diagram.lua`** — Lua filter from [pandoc-ext/diagram](https://github.com/pandoc-ext/diagram) for rendering code-block diagrams
+- **Mermaid CLI (`mmdc`)** — Installed when the `nodejs` overlay is present; skipped gracefully otherwise
+- **`~/.pandoc/pandoc.yaml`** — Ready-to-use defaults file (XeLaTeX engine, font settings, table tweaks)
+- **VS Code Extensions:** Markdown All in One (`yzhang.markdown-all-in-one`), markdownlint (`DavidAnson.vscode-markdownlint`)
+
+## How It Works
+
+System packages are installed through the `cross-distro-packages` feature, which handles package-manager detection and now supports fallback package names for distro variants. The setup script then downloads the official Pandoc `.deb` from GitHub releases (Pandoc 3.x is required for `diagram.lua`'s `Figure` AST element). Chromium is installed system-wide to serve as Puppeteer's browser for Mermaid headless rendering.
+
+The pipeline:
+
+```text
+Markdown
+  -> pandoc
+    -> diagram.lua (Lua filter, optional)
+      -> mmdc (Mermaid CLI, headless Chromium)
+    -> XeLaTeX
+      -> PDF
+```
+
+Font discovery is updated with `fc-cache -fv` after installation so XeLaTeX can locate the apt-installed fonts.
+
+## Common Commands
+
+### Basic PDF export
+
+```bash
+# Use the default pandoc.yaml
+pandoc -d ~/.pandoc/pandoc.yaml document.md -o document.pdf
+
+# Override the output font on the fly
+pandoc -d ~/.pandoc/pandoc.yaml -V mainfont="DejaVu Serif" document.md -o document.pdf
+```
+
+### PDF with Mermaid diagrams (requires nodejs overlay)
+
+```bash
+pandoc -d ~/.pandoc/pandoc.yaml \
+  --lua-filter ~/.pandoc/filters/diagram.lua \
+  document.md -o document.pdf
+```
+
+### Inspect installed fonts
+
+```bash
+fc-list | grep -i carlito
+fc-list | grep -i jetbrains
+fc-list | grep -i "noto sans symbols"
+```
+
+### Check Pandoc version
+
+```bash
+pandoc --version
+```
+
+## Mermaid Diagram Usage
+
+Add fenced `mermaid` code blocks to your Markdown:
+
+````markdown
+```mermaid
+graph TD
+    A[Start] --> B{Decision}
+    B -->|Yes| C[Action]
+    B -->|No| D[End]
+```
+````
+
+Render with the `diagram.lua` filter:
+
+```bash
+pandoc -d ~/.pandoc/pandoc.yaml \
+  --lua-filter ~/.pandoc/filters/diagram.lua \
+  document.md -o document.pdf
+```
+
+The filter invokes `mmdc` for each `mermaid` block, producing a PNG that XeLaTeX embeds in the PDF. The Puppeteer configuration at `~/.config/mermaid/puppeteer-config.json` points `mmdc` at the system Chromium with `--no-sandbox`, which is required inside containers.
+
+## Configuration
+
+### Default `~/.pandoc/pandoc.yaml`
+
+The setup script writes a defaults file with proven settings:
+
+```yaml
+pdf-engine: xelatex
+
+variables:
+    mainfont: 'Carlito'
+    monofont: 'JetBrains Mono'
+    fallbackfont: 'Noto Sans Symbols 2'
+    fontsize: 11pt
+    linestretch: 1.15
+    geometry:
+        - top=16mm
+        - bottom=16mm
+        - left=14mm
+        - right=14mm
+    header-includes:
+        - |
+            \usepackage{etoolbox}
+            \setlength{\tabcolsep}{3pt}
+            \renewcommand{\arraystretch}{1.05}
+            \AtBeginEnvironment{longtable}{\small}
+            \AtBeginEnvironment{tabular}{\small}
+```
+
+### Per-project override
+
+Create a `pandoc.yaml` in your project directory to override the defaults:
+
+```yaml
+# project/pandoc.yaml
+pdf-engine: xelatex
+variables:
+    mainfont: 'DejaVu Serif'
+    fontsize: 12pt
+toc: true
+toc-depth: 3
+number-sections: true
+lua-filter:
+    - ~/.pandoc/filters/diagram.lua
+```
+
+Then build with:
+
+```bash
+pandoc -d pandoc.yaml document.md -o document.pdf
+```
+
+### Enable TOC and section numbering
+
+Uncomment the relevant lines in `~/.pandoc/pandoc.yaml`:
+
+```yaml
+toc: true
+toc-depth: 3
+number-sections: true
+```
+
+### Enable Mermaid rendering by default
+
+Uncomment in `~/.pandoc/pandoc.yaml`:
+
+```yaml
+lua-filter:
+    - ~/.pandoc/filters/diagram.lua
+```
+
+## Unicode and Emoji
+
+XeLaTeX handles Unicode well with the Noto and Carlito fonts, but emoji (🎉 🚀) require a colour emoji font (e.g. `fonts-noto-color-emoji`) which is not installed by default due to size. For documents with emoji, either:
+
+1. Replace emoji with text equivalents before generating the PDF:
+
+    ```bash
+    sed 's/🎉/[celebration]/g; s/🚀/[rocket]/g' doc.md | pandoc -d ~/.pandoc/pandoc.yaml -o doc.pdf
+    ```
+
+2. Install `fonts-noto-color-emoji` and add `\setmainfont{Noto Color Emoji}` for the emoji font fallback in your `header-includes`.
+
+## Use Cases
+
+- **Architecture documentation** — Architecture Decision Records (ADRs), system design docs
+- **API specifications** — OpenAPI-style documentation with code samples
+- **Technical reports** — Multi-section documents with tables and diagrams
+- **README to PDF** — Convert project READMEs to distributable PDF format
+
+**Integrates well with:**
+
+- `nodejs` overlay — Enables Mermaid CLI for diagram rendering
+- `git-helpers` overlay — Commit generated PDFs alongside source Markdown
+- `modern-cli-tools` overlay — Use `bat` to preview Markdown, `rg` to search documents
+
+## Troubleshooting
+
+### `xelatex: command not found`
+
+TeX Live was not installed correctly. Re-run the setup script:
+
+```bash
+bash .devcontainer/scripts/setup-pandoc.sh
+```
+
+### Missing glyph warnings / blank characters in PDF
+
+The font does not include that glyph. For common Unicode symbols, Noto Sans Symbols 2 covers most cases. Verify it is installed:
+
+```bash
+fc-list | grep -i "noto sans symbols 2"
+```
+
+If not found, rebuild the font cache:
+
+```bash
+sudo fc-cache -fv
+```
+
+### Wide tables overflow page margins
+
+The `header-includes` in `pandoc.yaml` applies `\small` inside `longtable` and `tabular` environments. For very wide tables, also add `\tiny` or use column width constraints in your Markdown:
+
+```markdown
+| Col 1 | Col 2 | Col 3 |
+| :---- | :---- | :---- |
+| data  | data  | data  |
+```
+
+### Mermaid: Chromium crashes or `--no-sandbox` error
+
+The Puppeteer config at `~/.config/mermaid/puppeteer-config.json` must set `--no-sandbox`:
+
+```json
+{
+    "executablePath": "/usr/bin/chromium",
+    "args": ["--no-sandbox", "--disable-setuid-sandbox"]
+}
+```
+
+Verify the file exists and contains the correct content:
+
+```bash
+cat ~/.config/mermaid/puppeteer-config.json
+```
+
+### `mmdc` not found
+
+The `nodejs` overlay must be selected to install Mermaid CLI. Check if Node.js is available:
+
+```bash
+node --version
+npm --version
+mmdc --version
+```
+
+If Node.js is present but `mmdc` is missing, install it manually:
+
+```bash
+npm install -g @mermaid-js/mermaid-cli
+```
+
+### Upgrading Pandoc
+
+To upgrade to a newer Pandoc release, update `PANDOC_VERSION` in `setup.sh` and re-run it:
+
+```bash
+PANDOC_VERSION=3.7.0  # update as needed
+ARCH=$(dpkg --print-architecture)
+PANDOC_DEB="pandoc-${PANDOC_VERSION}-1-${ARCH}.deb"
+curl -fsSL "https://github.com/jgm/pandoc/releases/download/${PANDOC_VERSION}/${PANDOC_DEB}" \
+    -o "/tmp/${PANDOC_DEB}"
+sudo dpkg -i "/tmp/${PANDOC_DEB}"
+rm "/tmp/${PANDOC_DEB}"
+```
+
+## References
+
+- [Pandoc releases](https://github.com/jgm/pandoc/releases)
+- [pandoc-ext/diagram Lua filter](https://github.com/pandoc-ext/diagram)
+- [Mermaid CLI](https://github.com/mermaid-js/mermaid-cli)
+- [Puppeteer in containers](https://pptr.dev/troubleshooting#running-puppeteer-in-docker)
+- [TeX Live packages](https://packages.debian.org/search?keywords=texlive)
+
+**Related Overlays:**
+
+- `nodejs` — Required for Mermaid diagram rendering via `mmdc`
+- `git-helpers` — Secure Git operations for committing generated docs
+- `modern-cli-tools` — Productivity tools for Markdown authoring workflows

package/overlays/pandoc/devcontainer.patch.json

@@ -0,0 +1,14 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "features": {
+        "./features/cross-distro-packages": {
+            "apt": "texlive-xetex texlive-fonts-recommended texlive-fonts-extra texlive-latex-extra texlive-lang-european fonts-carlito|fonts-crosextra-carlito fonts-noto fonts-noto-extra fonts-noto-mono fonts-jetbrains-mono fontconfig perl chromium",
+            "apk": "fontconfig perl chromium"
+        }
+    },
+    "customizations": {
+        "vscode": {
+            "extensions": ["yzhang.markdown-all-in-one", "DavidAnson.vscode-markdownlint"]
+        }
+    }
+}

package/overlays/pandoc/overlay.yml

@@ -0,0 +1,19 @@
+id: pandoc
+name: Pandoc PDF
+description: Pandoc with XeLaTeX, Mermaid diagrams, and quality fonts for Markdown-to-PDF export
+category: dev
+supports: []
+requires: []
+suggests:
+    - nodejs
+conflicts: []
+tags:
+    - dev
+    - pandoc
+    - pdf
+    - latex
+    - markdown
+    - docs
+    - mermaid
+ports: []
+order: 25

package/overlays/pandoc/setup.sh

@@ -0,0 +1,94 @@
+#!/bin/bash
+# pandoc overlay setup — Markdown -> PDF pipeline
+
+set -e
+
+echo "📦 Refreshing font cache..."
+sudo fc-cache -fv
+
+echo "📦 Installing Pandoc (latest release)..."
+PANDOC_VERSION="3.6.4"
+
+if command -v apt-get > /dev/null 2>&1; then
+    # Debian/Ubuntu — install official .deb from GitHub releases
+    ARCH=$(dpkg --print-architecture)
+    PANDOC_DEB="pandoc-${PANDOC_VERSION}-1-${ARCH}.deb"
+    curl -fsSL "https://github.com/jgm/pandoc/releases/download/${PANDOC_VERSION}/${PANDOC_DEB}" \
+        -o "/tmp/${PANDOC_DEB}"
+    sudo dpkg -i "/tmp/${PANDOC_DEB}"
+    rm "/tmp/${PANDOC_DEB}"
+elif command -v apk > /dev/null 2>&1; then
+    # Alpine Linux — install via apk (version may differ from pinned release)
+    echo "⚠  Alpine detected: installing pandoc via apk (version may differ from ${PANDOC_VERSION})"
+    apk add --no-cache pandoc
+else
+    echo "❌ Unsupported distro: neither apt-get nor apk found. Cannot install Pandoc."
+    exit 1
+fi
+
+echo "✓ pandoc $(pandoc --version | head -1)"
+
+echo "📦 Installing diagram.lua Lua filter..."
+mkdir -p "$HOME/.pandoc/filters"
+curl -fsSL \
+    "https://raw.githubusercontent.com/pandoc-ext/diagram/main/_extensions/diagram/diagram.lua" \
+    -o "$HOME/.pandoc/filters/diagram.lua"
+
+echo "📦 Installing Mermaid CLI (requires Node.js)..."
+if command -v npm &>/dev/null; then
+    npm install -g @mermaid-js/mermaid-cli
+    # Point mmdc at the system Chromium (avoids Puppeteer downloading its own)
+    mkdir -p "$HOME/.config/mermaid"
+    cat > "$HOME/.config/mermaid/puppeteer-config.json" <<'EOF'
+{
+  "executablePath": "/usr/bin/chromium",
+  "args": ["--no-sandbox", "--disable-setuid-sandbox"]
+}
+EOF
+    if command -v mmdc >/dev/null 2>&1; then
+        echo "✓ Mermaid CLI installed: $(command -v mmdc)"
+    else
+        echo "⚠  Mermaid CLI install completed but mmdc is not on PATH yet"
+    fi
+else
+    echo "⚠  Node.js not found — Mermaid CLI skipped. Add the nodejs overlay for diagram support."
+fi
+
+echo "📦 Writing default pandoc.yaml..."
+mkdir -p "$HOME/.pandoc"
+cat > "$HOME/.pandoc/pandoc.yaml" <<'EOF'
+pdf-engine: xelatex
+
+variables:
+  mainfont: "Carlito"
+  monofont: "JetBrains Mono"
+  fallbackfont: "Noto Sans Symbols 2"
+  fontsize: 11pt
+  linestretch: 1.15
+  geometry:
+    - top=16mm
+    - bottom=16mm
+    - left=14mm
+    - right=14mm
+  header-includes:
+    - |
+      \usepackage{etoolbox}
+      \setlength{\tabcolsep}{3pt}
+      \renewcommand{\arraystretch}{1.05}
+      \AtBeginEnvironment{longtable}{\small}
+      \AtBeginEnvironment{tabular}{\small}
+
+# Uncomment to enable TOC and section numbering:
+# toc: true
+# toc-depth: 3
+# number-sections: true
+
+# Uncomment to enable Mermaid/diagram rendering (requires nodejs overlay):
+# lua-filter:
+#   - ~/.pandoc/filters/diagram.lua
+EOF
+
+echo ""
+echo "✓ pandoc overlay setup complete"
+echo "ℹ️  Build a PDF:  pandoc -d ~/.pandoc/pandoc.yaml doc.md -o doc.pdf"
+echo "ℹ️  With Mermaid: pandoc -d ~/.pandoc/pandoc.yaml --lua-filter ~/.pandoc/filters/diagram.lua doc.md -o doc.pdf"

package/overlays/pandoc/verify.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+set -e
+command -v pandoc  || { echo "✗ pandoc not found"; exit 1; }
+command -v xelatex || { echo "✗ xelatex not found"; exit 1; }
+[ -f "$HOME/.pandoc/filters/diagram.lua" ] || { echo "✗ diagram.lua not found"; exit 1; }
+[ -f "$HOME/.pandoc/pandoc.yaml" ]         || { echo "✗ pandoc.yaml not found"; exit 1; }
+
+# Smoke test: render a trivial PDF
+echo "# Test" | pandoc --pdf-engine=xelatex -o /tmp/pandoc-verify-test.pdf && \
+    echo "✓ pandoc PDF smoke test passed" || { echo "✗ pandoc PDF render failed"; exit 1; }
+
+rm -f /tmp/pandoc-verify-test.pdf
+echo "✓ pandoc overlay: OK"

package/overlays/spec-kit/README.md

@@ -0,0 +1,181 @@
+# Spec Kit (SDD) Overlay
+
+Installs the `specify` CLI and its prerequisites (`uv`) for **Spec-Driven Development** — a disciplined workflow that elevates specifications to first-class artifacts driving AI-powered implementation.
+
+## Features
+
+- **`specify` CLI** — Interactive SDD workflow commands for any supported AI coding agent
+- **`uv`** — Fast Python package manager used to install and run `specify`
+- **20+ AI agent integrations** — Works with Codex, Claude Code, Gemini CLI, GitHub Copilot, Cursor, Windsurf, Amp, and more
+
+## What is Spec-Driven Development?
+
+Spec-Driven Development (SDD) flips the traditional workflow: instead of vibe-coding, you author rich specifications that become executable artifacts driving AI agents through a disciplined multi-step process:
+
+| Step | Command                 | Description                               |
+| ---- | ----------------------- | ----------------------------------------- |
+| 1    | `/speckit.constitution` | Create project governing principles       |
+| 2    | `/speckit.specify`      | Define requirements (what & why, not how) |
+| 3    | `/speckit.clarify`      | Clarify underspecified areas              |
+| 4    | `/speckit.plan`         | Create a technical implementation plan    |
+| 5    | `/speckit.analyze`      | Cross-artifact consistency analysis       |
+| 6    | `/speckit.tasks`        | Break plan into actionable tasks          |
+| 7    | `/speckit.implement`    | Execute tasks with an AI agent            |
+
+## How It Works
+
+This overlay:
+
+1. Installs `uv` (Astral's fast Python package manager) if not already present
+2. Uses `uv tool install` to install `specify-cli` from the [github/spec-kit](https://github.com/github/spec-kit) repository
+3. Makes `specify` available on the PATH inside the devcontainer
+
+**Why `uv`?** Spec Kit uses `uv` as its package manager for fast, isolated tool installation — it avoids the overhead of creating a full virtual environment while keeping `specify` globally accessible.
+
+## Common Commands
+
+### Initialize a project
+
+```bash
+# Initialize SDD for a project with a specific AI agent
+specify init . --here --ai codex
+specify init . --here --ai claude
+specify init . --here --ai gemini
+specify init . --here --ai copilot
+specify init . --here --ai amp
+```
+
+### SDD Workflow
+
+```bash
+# After initializing, use the installed slash commands in your AI agent:
+# /speckit.constitution  — Define project principles
+# /speckit.specify       — Author requirements spec
+# /speckit.clarify       — Clarify ambiguities
+# /speckit.plan          — Generate implementation plan
+# /speckit.analyze       — Check consistency
+# /speckit.tasks         — Break into tasks
+# /speckit.implement     — Implement with AI
+```
+
+### Utility Commands
+
+```bash
+# Check specify is available
+specify --version
+
+# List supported agents
+specify --help
+```
+
+## Supported AI Agents
+
+The `specify` CLI supports the following agents (pass as `--ai <agent>`):
+
+| Agent                 | `--ai` flag    | Notes                                   |
+| --------------------- | -------------- | --------------------------------------- |
+| OpenAI Codex          | `codex`        | Requires `codex` overlay                |
+| Anthropic Claude Code | `claude`       | Requires `claude-code` overlay          |
+| Google Gemini CLI     | `gemini`       | Requires `gemini-cli` overlay           |
+| GitHub Copilot        | `copilot`      | IDE-integrated, no extra overlay needed |
+| Cursor Agent          | `cursor-agent` | IDE-integrated                          |
+| Codeium Windsurf      | `windsurf`     | Requires `windsurf-cli` overlay         |
+| Sourcegraph Amp       | `amp`          | Requires `amp` overlay                  |
+| opencode              | `opencode`     | Requires `opencode` overlay             |
+| Roo Code              | `roo-code`     | IDE-integrated                          |
+| Kiro CLI              | `kiro`         | Check upstream docs                     |
+| Generic (BYOA)        | `generic`      | Bring your own agent                    |
+
+For the full list see the [spec-kit supported agents documentation](https://github.com/github/spec-kit#-supported-ai-agents).
+
+## Use Cases
+
+- **Greenfield projects** — Start with a specification before writing any code
+- **Feature development** — Spec out new features before asking AI to implement them
+- **Team alignment** — Share specifications as structured artifacts
+- **AI-assisted refactoring** — Spec the desired end state, let AI plan the migration
+- **Documentation-driven development** — Specifications become living documentation
+
+**Integrates well with:**
+
+- `codex` — OpenAI Codex CLI (most common with SDD)
+- `claude-code` — Anthropic Claude Code
+- `gemini-cli` — Google Gemini CLI
+- `amp` — Sourcegraph Amp
+- `git-helpers` — Git integration for specification artifacts
+- `pre-commit` — Quality gates for specification files
+
+## Configuration
+
+The `specify` tool stores its slash-command templates in your project directory after running `specify init`. These files are committed to your repository.
+
+**Environment variable (optional):**
+
+```bash
+# Set a default AI agent to avoid passing --ai on every command
+export SPECIFY_AI_AGENT=codex
+```
+
+## Verification
+
+After setup, run the verification script to ensure proper installation:
+
+```bash
+bash .devcontainer/scripts/verify-spec-kit.sh
+```
+
+This checks:
+
+- `uv` is installed
+- `specify` CLI is available on PATH
+
+## Troubleshooting
+
+### `specify` command not found
+
+**Solution:**
+
+Ensure `$HOME/.local/bin` is on your PATH:
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+
+# Or add to your shell profile:
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
+```
+
+### `uv` not found
+
+**Solution:**
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+### `specify` fails to install
+
+**Solution:**
+
+Check internet connectivity and try reinstalling:
+
+```bash
+uv tool install specify-cli --from git+https://github.com/github/spec-kit.git --force
+```
+
+## References
+
+- [Spec Kit GitHub](https://github.com/github/spec-kit)
+- [Spec-Driven Development Methodology](https://github.com/github/spec-kit/blob/main/spec-driven.md)
+- [Specify CLI Reference](https://github.com/github/spec-kit#-specify-cli-reference)
+- [Supported AI Agents](https://github.com/github/spec-kit#-supported-ai-agents)
+- [uv Documentation](https://docs.astral.sh/uv/)
+
+**Related Overlays:**
+
+- `codex` — OpenAI Codex CLI
+- `claude-code` — Anthropic Claude Code
+- `gemini-cli` — Google Gemini CLI
+- `amp` — Sourcegraph Amp
+- `opencode` — opencode CLI
+- `windsurf-cli` — Codeium Windsurf CLI

package/overlays/spec-kit/devcontainer.patch.json

@@ -0,0 +1,6 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "remoteEnv": {
+        "PATH": "${containerEnv:PATH}:${containerEnv:HOME}/.local/bin"
+    }
+}

package/overlays/spec-kit/overlay.yml

@@ -0,0 +1,19 @@
+id: spec-kit
+name: Spec Kit (SDD)
+description: Specify CLI for Spec-Driven Development with any AI coding agent
+category: dev
+supports: []
+requires: []
+suggests:
+    - python
+    - codex
+conflicts: []
+tags:
+    - dev
+    - ai
+    - sdd
+    - spec-driven
+    - specify
+    - spec-kit
+ports: []
+order: 20

package/overlays/spec-kit/setup.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+# spec-kit setup — install specify-cli for Spec-Driven Development
+
+set -e
+
+echo "📦 Installing prerequisites for spec-kit..."
+
+# Ensure uv tool bin directory is always on PATH (uv puts shims here regardless
+# of whether uv itself was pre-installed or freshly installed in this script)
+export PATH="$HOME/.local/bin:$PATH"
+
+# Ensure uv is available (fast Python package manager)
+if ! command -v uv &>/dev/null; then
+    echo "  Installing uv..."
+    curl -LsSf https://astral.sh/uv/install.sh | sh
+    # Re-source in case the installer wrote to a non-standard location
+    export PATH="$HOME/.cargo/bin:$HOME/.local/bin:$PATH"
+fi
+
+echo "📦 Installing specify-cli..."
+# Pin to a uv-managed Python (avoids broken system Python 3.13 on Debian trixie
+# where stdlib modules like shutil/os can be missing due to Debian's split packages)
+UV_PYTHON_VERSION="3.12"
+echo "  Ensuring uv-managed Python ${UV_PYTHON_VERSION} is available..."
+uv python install "${UV_PYTHON_VERSION}"
+
+# Install specify-cli using the uv-managed Python, not the system interpreter
+uv tool install specify-cli --from git+https://github.com/github/spec-kit.git \
+    --python "${UV_PYTHON_VERSION}"
+
+# Verify — use the full path as a fallback in case the shim dir is not yet in PATH
+SPECIFY_BIN="$(uv tool dir 2>/dev/null)/specify-cli/bin/specify"
+if command -v specify &>/dev/null; then
+    echo "✓ specify-cli installed: $(specify --version 2>/dev/null || echo 'ok')"
+elif [ -x "$SPECIFY_BIN" ]; then
+    echo "✓ specify-cli installed at $SPECIFY_BIN (add ~/.local/bin to PATH)"
+else
+    echo "✗ specify-cli installation failed"
+    exit 1
+fi
+
+echo "✓ spec-kit setup complete"
+echo "ℹ️  Spec Kit: https://github.com/github/spec-kit"
+echo "ℹ️  Usage:  specify init <PROJECT_NAME> --ai <agent>"
+echo "ℹ️  Agents: codex, claude, gemini, copilot, cursor-agent, windsurf, amp, ..."