devstuff 1.16.0__tar.gz → 1.17.0__tar.gz

{devstuff-1.16.0 → devstuff-1.17.0}/.github/workflows/test-installs.yml

@@ -61,6 +61,7 @@ jobs:
           - java
           - lazygit
           - mkcert
+          - nerd-font
           - nvm
           - php
           - pi          # installs nvm first via its declared `requires`

{devstuff-1.16.0 → devstuff-1.17.0}/CHANGELOG.md

@@ -1,3 +1,10 @@
+## v1.17.0 (2026-07-31)
+
+### Feat
+
+- starship config font validation and install
+- **configure**: add a starship prompt setup wizard with live preview
+
 ## v1.16.0 (2026-07-24)
 
 ### Feat

{devstuff-1.16.0 → devstuff-1.17.0}/CLAUDE.md

@@ -21,8 +21,10 @@ uv run pytest tests/test_catalog.py::test_user_catalog_overrides_bundled_tool_in
 ```
 
 `pip` is not available in this dev environment — `uv pip install -e .` / `uv run` are the way in.
-Interactive commands (`install`, `add`, `remove`, `delete`) open questionary/click prompts and
-hang in non-TTY shells; don't try to drive them from a piped/non-interactive shell.
+Interactive commands (`install`, `add`, `remove`, `delete`, `configure`) open questionary/click
+prompts and hang in non-TTY shells; don't try to drive them from a piped/non-interactive shell.
+To exercise one end-to-end anyway, fork a pty (`pty.fork()`) and write keystrokes to the fd —
+that is how the starship wizard's full flow was verified.
 
 ### Integration tests (real installs, Docker-isolated)
 
@@ -60,6 +62,7 @@ src/dev_setup/
 ├── generic.py       # GenericTool — the ONE engine that implements every install type
 ├── tools.yaml       # Bundled built-in catalog (core/tools/languages categories)
 ├── ui.py            # Rich console + questionary wrappers (spinners, prompts, styled output)
+├── configure/       # Per-tool setup wizards (see "Configurators" below)
 └── commands/        # One Click command per file: list, install, remove, add, delete, docs, catalog
 ```
 
@@ -167,6 +170,83 @@ non-interactive `bash <tmpfile>`, so `~/.bashrc`/nvm's shell init never runs on
 Not yet built: an `add` wizard and `catalog import`/`export` for functions, analogous to the
 ones tools already have.
 
+## Configurators (`configure/`) — tool-specific wizards, deliberately *not* catalog-driven
+
+`src/dev_setup/configure/` holds per-tool setup wizards (`devstuff configure <tool>`), registered
+in a `CONFIGURATORS` dict keyed by catalog tool key. `starship` is the first one:
+`configure/starship/{model,render,preview,wizard}.py`.
+
+**Why this one breaks the YAML-catalog rule.** Installation generalises into ~7 mechanisms, which
+is what makes `GenericTool` possible. Configuration does not: starship's config is a TOML file of
+format strings, palette tables and powerline transition glyphs; another tool's would be shell
+exports or `git config` calls. Expressing this wizard in YAML would need conditional questions, an
+ordered section model with colour roles, and a template language — a programming language spelled
+in YAML. So configurators are Python, dispatched from a dict, the same shape as `_INSTALLERS` in
+`generic.py`. Full reasoning in `docs/specs/starship-config/stack-decisions.md` (SD-1).
+
+A configurator that finds a missing *prerequisite* should offer to install it through
+`install_cmd.install_by_key(key)` rather than telling the user to run a second command — that is
+what the starship wizard does for `nerd-font`.
+
+**Adding a configurator** — a new module plus one dict entry. The module must expose
+`run(*, target: Path | None = None)` (returns `None` if the user cancelled; writes nothing until
+they confirm) and `config_path() -> Path`. Everything generic — the picker, install-state check,
+`--list`/`--path`/`--output`, and the post-install offer in `install_cmd.py` — reads the registry,
+so none of it needs touching. There is deliberately **no `configure:` field in `tools.yaml`**: user
+catalogs are strictly validated, so a catalog naming a nonexistent configurator would add a
+load-time failure mode for nothing.
+
+**Within the starship configurator, `model.py` is the data and everything else reads it.**
+`SECTIONS` (ordered — declaration order *is* prompt order), `PALETTES` and `PRESETS` drive both the
+TOML emitter and the offline preview, which is what stops those two from drifting. Adding a section
+or palette is one entry; no other file changes.
+
+**Things learned from the real binary — don't "simplify" these away:**
+- `symbol` is emitted for every section whose body contains `$symbol`, *including as an empty
+  string*. Omit it and starship's built-in Nerd Font glyph leaks into the `plain` preset. The
+  converse is unit-tested: a section carrying an icon its body can't render is a bug (that's why
+  `directory`, which has no `symbol` key at all, has no icon).
+- Not every module spells the colour key `style` — hence `Section.style_key` (`username` wants
+  `style_user`). `battery` is deliberately absent: it accepts neither `style` nor `symbol` (both
+  live in its `[[battery.display]]` array), so it would cost three quirk fields for one section.
+- `kubernetes`, `time`, `azure`, `status` and `shlvl` ship *disabled*; listing them in `format`
+  isn't enough, they need `disabled = false`. `os` and `git_metrics` are absent for the same
+  reason `battery` is: `os` takes its symbol from an `[os.symbols]` distro table, `git_metrics`
+  has `added_style`/`deleted_style` instead of `style`.
+- Format strings are emitted as TOML **literal** strings (`'…'`) so starship's `$`, `[`, and `\[`
+  grammar needs no escaping. The multi-line top-level `format` is the one basic string, and it
+  contains no backslashes of its own beyond the line continuations.
+- Powerline transitions are emitted per **run of consecutive sections sharing a palette role**, not
+  per section — otherwise two adjacent language segments draw an arrow between two identical
+  backgrounds. The three powerline presets differ *only* in the four glyphs in their `Powerline`
+  record (`POWERLINES` in `model.py`); nothing in the emitter knows which variant it is drawing.
+- Any literal text the emitter writes into a format string is escaped with `_escape_format()`.
+  This is not theoretical: `success_symbol = '[$](bold fg:ok)'` made starship read `$` as the start
+  of a variable name, so the `plain` preset shipped with *no prompt symbol at all* until it was
+  caught by sweeping every combination and asserting empty stderr.
+- A custom module (`custom.compose`) is a normal `Section`, but its dotted key has to be written
+  `${custom.compose}` in `format` — hence `Section.ref`. It also runs a shell command on **every**
+  prompt, so it carries a `when` guard, and anything needing the network is disqualified.
+- Symbols for new sections come from `starship print-config --default` — the module's own shipped
+  glyph — rather than being picked from a Nerd Font chart that can't be verified without the font.
+- The sample project must never gain a `bun.lock`: starship's `nodejs` module lists it as a
+  *negative* detector, so it silently switches the Node section off in previews.
+- The live preview runs `starship prompt` with `STARSHIP_SHELL=nu`, not `bash`: for bash, starship
+  wraps escapes in readline's `\[`/`\]` markers, which are invisible inside a `PS1` and print
+  literally anywhere else. It also overrides `PWD` (starship prefers it over the real cwd) and
+  makes a second `--right` call, since `right_format` is not part of the left prompt.
+- Every preview failure path returns `None` and degrades to the offline renderer. A preview must
+  never be able to end the wizard.
+- The Nerd Font gate (`configure/starship/fonts.py`) is allowed to answer "don't know": without
+  fontconfig there is nothing to enumerate, and `None` means *stay silent* rather than warn. It
+  also refuses to install over SSH — the glyphs are drawn by the client's terminal — and always
+  says that installing a font does not repoint the terminal at it. The install itself goes through
+  the ordinary catalog path (`nerd-font` in `tools.yaml` → `install_cmd.install_by_key`), never a
+  private download (SD-10).
+
+Not yet built: configurators for anything other than starship, and round-tripping an existing
+hand-edited config back into wizard state (the timestamped backup is the safety net instead).
+
 ## Specs (`docs/specs/`)
 
 Design documents live in `docs/specs/<feature>/` — `specifications.md` (numbered, testable
@@ -258,6 +338,12 @@ Not yet built: an `add` wizard for agent tools, and `catalog import`/`export` fo
 - **No new runtime dependencies for the agent.** The Ollama transport is stdlib `urllib` against
   `/api/chat`; the REPL uses `prompt_toolkit`, already vendored via questionary. devstuff is a
   globally installed CLI, so every dependency is a cost paid by users who never run `agent`.
+- **Configuration is Python, installation is YAML.** The no-per-tool-code rule covers *install
+  mechanisms*, which generalise; per-tool config formats don't. `configure/` is a registry of
+  Python wizards on purpose — see the section above before trying to fold it into `tools.yaml`.
+- **A config wizard previews with the real binary, not an approximation.** `starship prompt`
+  against a temp config in a throwaway project is the source of truth; the offline renderer is a
+  labelled fallback for when the tool isn't installed (and is what unit tests exercise).
 - **Functions get a parallel catalog/registry instead of extending `GenericTool`.** The
   schemas diverge enough (no `requires` inference, a `params` list, no install/remove
   lifecycle) that folding them into the tool catalog would be lossy; some duplication with

{devstuff-1.16.0 → devstuff-1.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devstuff
-Version: 1.16.0
+Version: 1.17.0
 Summary: Development environment setup CLI for Linux
 Project-URL: Repository, https://github.com/thesawdawg/dev-setup-py
 Author-email: Sawyer <sawyerksu@gmail.com>
@@ -188,6 +188,105 @@ for confirmation before doing this.
 
 ---
 
+### `configure`
+
+Set up an installed tool through a guided wizard, previewing the result before anything is
+written. Installing a tool that has a wizard also offers to run it there and then.
+
+```bash
+devstuff configure                       # pick from the tools that have a wizard
+devstuff configure starship              # run starship's prompt wizard
+devstuff configure --list                # which tools have a wizard
+devstuff configure starship --path       # print the config file path
+devstuff configure starship --output /tmp/try.toml   # write elsewhere, leave the live config alone
+```
+
+| Tool | What it configures |
+|------|-------------------|
+| `starship` | Prompt style, colour palette, which sections appear, and layout |
+
+#### Starship prompt wizard
+
+Four questions, with the prompt re-rendered after each one:
+
+| Step | Options |
+|------|---------|
+| **Style** | `Plain text` · `Bracketed segments` (both ASCII, any font) · `Icons` · `Icons, bracketed` (Nerd Font glyphs) · `Powerline`, `Powerline, rounded`, `Powerline, slanted` (solid colour bars) |
+| **Palette** | `Terminal colours` (inherits your terminal theme) · Catppuccin Mocha · Nord · Gruvbox Dark · Tokyo Night · Dracula · Rosé Pine · Catppuccin Latte (light) |
+| **Sections** | Grouped checkbox over ~35 modules — see the table below |
+| **Layout** | Single line · Two lines · Two lines with shell info right-aligned (needs zsh/fish/nushell — bash has no right prompt) |
+
+| Group | Sections |
+|-------|----------|
+| **Context** | username, hostname (over SSH), container (Docker/toolbox/distrobox) |
+| **Location** | current directory |
+| **Git** | branch, commit hash (when detached), status (dirty/ahead/behind), operation in progress |
+| **Languages** | Node.js, Deno, Bun, Python, Rust, Go, Java, PHP, Ruby, Elixir, .NET, package version |
+| **Infrastructure** | Docker context, **Docker Compose project**, Kubernetes context, AWS profile, Google Cloud project, Azure subscription, Terraform workspace, Nix shell |
+| **Shell** | command duration, exit code of the last command, background jobs, nested shell depth, clock |
+
+The review menu adds two content toggles: the blank line between prompts, and whether language
+sections show **version numbers** or just the runtime's symbol.
+
+If you pick a style that needs a Nerd Font and there isn't one on the machine, the wizard says
+so in the style list itself (`Needs a Nerd Font — none installed here.`) and offers to install
+`nerd-font` right there — once per run, whether you say yes or no. Two cases it handles rather
+than pretending otherwise: over SSH it points you at [nerdfonts.com](https://www.nerdfonts.com/)
+instead, because the glyphs are drawn by the terminal on *your* machine, not the one you're
+configuring; and after installing it reminds you to actually select the font in your terminal's
+settings, which is a preference no shell can change for you. Without `fontconfig` there is no way
+to enumerate fonts, so the wizard says nothing rather than guessing.
+
+The Compose section is a starship [custom module](https://starship.rs/config/#custom-commands)
+rather than a built-in one — it reports the project name `docker compose` in that directory would
+actually use (`$COMPOSE_PROJECT_NAME`, else a top-level `name:` in the compose file, else the
+lowercased directory name), and it only runs at all when there is a compose file next to you.
+
+The preview is the real thing: the candidate config is written to a temp file and rendered by
+your installed `starship` binary inside a throwaway sample project (a git repo with language
+marker files), so what you see is the bytes your prompt will produce. Without starship installed
+the wizard still works and falls back to a labelled approximation.
+
+A review menu then lets you revisit any answer, dump the generated TOML, or save. On save:
+
+- Written to `$STARSHIP_CONFIG`, or `~/.config/starship.toml`.
+- Any existing file is copied to `starship.toml.bak.<timestamp>` first — and if it wasn't written
+  by this wizard, you're asked before it's replaced.
+- If `~/.bashrc` has no starship hook, you're offered one (using the same marker
+  `devstuff install starship` uses, so `devstuff remove starship` still cleans up).
+
+The output is meant to be hand-edited afterwards: it's commented, ordered, and colours are
+referenced through nine semantic palette roles (`dir`, `git`, `lang`, `infra`, `shell`, `ok`,
+`err`, `muted`, `bar_text`), so retheming everything is nine edits in one table.
+
+```toml
+# Starship prompt configuration
+# Generated by `devstuff configure starship` — edit freely, or re-run the wizard.
+# Style: Powerline · Palette: Nord · Layout: Two lines
+# Module reference: https://starship.rs/config/
+"$schema" = 'https://starship.rs/config-schema.json'
+
+add_newline = true
+palette = 'nord'
+
+format = """
+[](fg:dir)\
+$directory\
+[](fg:dir bg:git)\
+$git_branch\
+[](fg:git)\
+$line_break\
+$character"""
+
+# Semantic colour roles — swap these to retheme every section at once.
+[palettes.nord]
+dir = '#81a1c1'
+git = '#a3be8c'
+# …
+```
+
+---
+
 ### `add`
 
 Guided wizard to register a new custom package. Supports six install types:
@@ -590,12 +689,13 @@ Optional utilities you may want on some machines.
 | `gh` | GitHub CLI | GitHub's official CLI | `gh --help` |
 | `htop` | htop | Interactive process and resource monitor | `man htop` |
 | `mkcert` | mkcert | Zero-config local HTTPS certificates | `mkcert --help` |
+| `nerd-font` | JetBrainsMono Nerd Font | Patched font supplying the icons Starship and other CLI tools draw | `fc-list \| grep -i "nerd font"` |
 | `ollama` | Ollama | Run large language models locally | `ollama --help` |
 | `php` | PHP 8.4 | PHP 8.4 + common extensions via ondrej/php PPA | `php --help` |
 | `pi` | Pi Coding Agent | AI coding agent npm package | `pi --help` |
 | `pre-commit` | pre-commit | Git hook manager for automated code quality checks | `pre-commit --help` |
 | `saml2aws` | saml2aws | SAML → AWS STS credentials CLI (Versent) | `saml2aws --help` |
-| `starship` | Starship | Fast, cross-shell customizable prompt | `starship --help` |
+| `starship` | Starship | Fast, cross-shell customizable prompt (`devstuff configure starship`) | `starship --help` |
 | `yq` | yq | Portable command-line YAML/JSON/XML processor | `yq --help` |
 
 ### Languages
@@ -740,6 +840,13 @@ dev-setup-py/
         ├── functions_registry.py # Loads bundled + user YAML into the live function registry
         ├── function_runner.py    # Param resolution + script/eval/bashrc rendering & execution
         ├── functions.yaml        # Bundled built-in function catalog
+        ├── configure/              # Per-tool setup wizards (see "configure" above)
+        │   ├── __init__.py         # CONFIGURATORS registry: tool key -> wizard module
+        │   └── starship/
+        │       ├── model.py        # presets, palettes, sections, StarshipConfig
+        │       ├── render.py       # starship.toml emitter + offline preview renderer
+        │       ├── preview.py      # live preview via `starship prompt` in a sample project
+        │       └── wizard.py       # the interactive flow, backup + save
         ├── agent_tools.yaml       # Bundled agent tool catalog
         ├── agent/                 # Local-model agent (see "Agent" above)
         │   ├── config.py          # agent.yaml load/validate/save

{devstuff-1.16.0 → devstuff-1.17.0}/README.md

@@ -161,6 +161,105 @@ for confirmation before doing this.
 
 ---
 
+### `configure`
+
+Set up an installed tool through a guided wizard, previewing the result before anything is
+written. Installing a tool that has a wizard also offers to run it there and then.
+
+```bash
+devstuff configure                       # pick from the tools that have a wizard
+devstuff configure starship              # run starship's prompt wizard
+devstuff configure --list                # which tools have a wizard
+devstuff configure starship --path       # print the config file path
+devstuff configure starship --output /tmp/try.toml   # write elsewhere, leave the live config alone
+```
+
+| Tool | What it configures |
+|------|-------------------|
+| `starship` | Prompt style, colour palette, which sections appear, and layout |
+
+#### Starship prompt wizard
+
+Four questions, with the prompt re-rendered after each one:
+
+| Step | Options |
+|------|---------|
+| **Style** | `Plain text` · `Bracketed segments` (both ASCII, any font) · `Icons` · `Icons, bracketed` (Nerd Font glyphs) · `Powerline`, `Powerline, rounded`, `Powerline, slanted` (solid colour bars) |
+| **Palette** | `Terminal colours` (inherits your terminal theme) · Catppuccin Mocha · Nord · Gruvbox Dark · Tokyo Night · Dracula · Rosé Pine · Catppuccin Latte (light) |
+| **Sections** | Grouped checkbox over ~35 modules — see the table below |
+| **Layout** | Single line · Two lines · Two lines with shell info right-aligned (needs zsh/fish/nushell — bash has no right prompt) |
+
+| Group | Sections |
+|-------|----------|
+| **Context** | username, hostname (over SSH), container (Docker/toolbox/distrobox) |
+| **Location** | current directory |
+| **Git** | branch, commit hash (when detached), status (dirty/ahead/behind), operation in progress |
+| **Languages** | Node.js, Deno, Bun, Python, Rust, Go, Java, PHP, Ruby, Elixir, .NET, package version |
+| **Infrastructure** | Docker context, **Docker Compose project**, Kubernetes context, AWS profile, Google Cloud project, Azure subscription, Terraform workspace, Nix shell |
+| **Shell** | command duration, exit code of the last command, background jobs, nested shell depth, clock |
+
+The review menu adds two content toggles: the blank line between prompts, and whether language
+sections show **version numbers** or just the runtime's symbol.
+
+If you pick a style that needs a Nerd Font and there isn't one on the machine, the wizard says
+so in the style list itself (`Needs a Nerd Font — none installed here.`) and offers to install
+`nerd-font` right there — once per run, whether you say yes or no. Two cases it handles rather
+than pretending otherwise: over SSH it points you at [nerdfonts.com](https://www.nerdfonts.com/)
+instead, because the glyphs are drawn by the terminal on *your* machine, not the one you're
+configuring; and after installing it reminds you to actually select the font in your terminal's
+settings, which is a preference no shell can change for you. Without `fontconfig` there is no way
+to enumerate fonts, so the wizard says nothing rather than guessing.
+
+The Compose section is a starship [custom module](https://starship.rs/config/#custom-commands)
+rather than a built-in one — it reports the project name `docker compose` in that directory would
+actually use (`$COMPOSE_PROJECT_NAME`, else a top-level `name:` in the compose file, else the
+lowercased directory name), and it only runs at all when there is a compose file next to you.
+
+The preview is the real thing: the candidate config is written to a temp file and rendered by
+your installed `starship` binary inside a throwaway sample project (a git repo with language
+marker files), so what you see is the bytes your prompt will produce. Without starship installed
+the wizard still works and falls back to a labelled approximation.
+
+A review menu then lets you revisit any answer, dump the generated TOML, or save. On save:
+
+- Written to `$STARSHIP_CONFIG`, or `~/.config/starship.toml`.
+- Any existing file is copied to `starship.toml.bak.<timestamp>` first — and if it wasn't written
+  by this wizard, you're asked before it's replaced.
+- If `~/.bashrc` has no starship hook, you're offered one (using the same marker
+  `devstuff install starship` uses, so `devstuff remove starship` still cleans up).
+
+The output is meant to be hand-edited afterwards: it's commented, ordered, and colours are
+referenced through nine semantic palette roles (`dir`, `git`, `lang`, `infra`, `shell`, `ok`,
+`err`, `muted`, `bar_text`), so retheming everything is nine edits in one table.
+
+```toml
+# Starship prompt configuration
+# Generated by `devstuff configure starship` — edit freely, or re-run the wizard.
+# Style: Powerline · Palette: Nord · Layout: Two lines
+# Module reference: https://starship.rs/config/
+"$schema" = 'https://starship.rs/config-schema.json'
+
+add_newline = true
+palette = 'nord'
+
+format = """
+[](fg:dir)\
+$directory\
+[](fg:dir bg:git)\
+$git_branch\
+[](fg:git)\
+$line_break\
+$character"""
+
+# Semantic colour roles — swap these to retheme every section at once.
+[palettes.nord]
+dir = '#81a1c1'
+git = '#a3be8c'
+# …
+```
+
+---
+
 ### `add`
 
 Guided wizard to register a new custom package. Supports six install types:
@@ -563,12 +662,13 @@ Optional utilities you may want on some machines.
 | `gh` | GitHub CLI | GitHub's official CLI | `gh --help` |
 | `htop` | htop | Interactive process and resource monitor | `man htop` |
 | `mkcert` | mkcert | Zero-config local HTTPS certificates | `mkcert --help` |
+| `nerd-font` | JetBrainsMono Nerd Font | Patched font supplying the icons Starship and other CLI tools draw | `fc-list \| grep -i "nerd font"` |
 | `ollama` | Ollama | Run large language models locally | `ollama --help` |
 | `php` | PHP 8.4 | PHP 8.4 + common extensions via ondrej/php PPA | `php --help` |
 | `pi` | Pi Coding Agent | AI coding agent npm package | `pi --help` |
 | `pre-commit` | pre-commit | Git hook manager for automated code quality checks | `pre-commit --help` |
 | `saml2aws` | saml2aws | SAML → AWS STS credentials CLI (Versent) | `saml2aws --help` |
-| `starship` | Starship | Fast, cross-shell customizable prompt | `starship --help` |
+| `starship` | Starship | Fast, cross-shell customizable prompt (`devstuff configure starship`) | `starship --help` |
 | `yq` | yq | Portable command-line YAML/JSON/XML processor | `yq --help` |
 
 ### Languages
@@ -713,6 +813,13 @@ dev-setup-py/
         ├── functions_registry.py # Loads bundled + user YAML into the live function registry
         ├── function_runner.py    # Param resolution + script/eval/bashrc rendering & execution
         ├── functions.yaml        # Bundled built-in function catalog
+        ├── configure/              # Per-tool setup wizards (see "configure" above)
+        │   ├── __init__.py         # CONFIGURATORS registry: tool key -> wizard module
+        │   └── starship/
+        │       ├── model.py        # presets, palettes, sections, StarshipConfig
+        │       ├── render.py       # starship.toml emitter + offline preview renderer
+        │       ├── preview.py      # live preview via `starship prompt` in a sample project
+        │       └── wizard.py       # the interactive flow, backup + save
         ├── agent_tools.yaml       # Bundled agent tool catalog
         ├── agent/                 # Local-model agent (see "Agent" above)
         │   ├── config.py          # agent.yaml load/validate/save

{devstuff-1.16.0 → devstuff-1.17.0}/docs/specs/README.md

@@ -39,3 +39,4 @@ They are most useful when they capture:
 | Feature | Status |
 |---------|--------|
 | [`agent/`](agent/) — `devstuff agent`, the local-model agent | Complete (v1) |
+| [`starship-config/`](starship-config/) — `devstuff configure starship`, the prompt wizard | Complete (v1) |

devstuff-1.17.0/docs/specs/starship-config/development-plan.md

@@ -0,0 +1,74 @@
+# Development Plan: `devstuff configure starship`
+
+**Date:** 2026-07-30
+**Status:** Milestones 1–6 complete
+
+---
+
+## Milestones
+
+| # | Milestone | Deliverable | Done when |
+|---|-----------|-------------|-----------|
+| 1 | Data model | `configure/starship/model.py` — `Preset`, `Palette`, `Section`, `StarshipConfig`, the ordered `SECTIONS` tuple | Defaults produce a coherent config with no I/O |
+| 2 | TOML emitter | `configure/starship/render.py` `to_toml()` | Output parses under `tomllib` for every preset × palette × layout combination, and `starship print-config` accepts it |
+| 3 | Preview | `configure/starship/preview.py` (live, via `starship prompt` in a sample project) + `render.sample_markup()` (offline fallback) | Live path prints ANSI for a real config; offline path renders every selected section with starship absent |
+| 4 | Wizard + command | `configure/starship/wizard.py`, `commands/configure_cmd.py`, registry in `configure/__init__.py`, CLI wiring | `devstuff configure starship` walks the steps, previews after each, saves with a backup |
+| 5 | Integration + docs | post-install offer in `install_cmd.py`, help text, README, CLAUDE.md, this spec | `devstuff install starship` offers the wizard; docs describe how to add a configurator |
+| 6 | Preset + section expansion (v2) | `POWERLINES` glyph sets, bracketed presets, three more palettes, `show_versions`, custom modules (`custom.compose`) and 10 further sections | Every preset × palette × layout × versions combination is accepted by the real binary with **no stderr output**, and the compose command resolves the same name Compose would |
+
+## Testing Strategy
+
+`tests/test_configure_starship.py` — unit only, no starship required (NFR-5):
+
+- **Emitter validity:** every `preset × palette × layout` combination parses under `tomllib`;
+  spot-check that `format`, `palette`, `add_newline` and the expected module tables exist.
+- **Section selection:** unselected modules get no table and never appear in `format`; selected
+  ones appear in canonical order regardless of the order the checkbox returned them in.
+- **Symbol handling:** `plain` preset emits `symbol = ''` for icon-bearing sections (regression
+  guard for starship's default glyph leaking through); `icons`/`powerline` emit the Nerd Font one.
+- **Powerline runs:** consecutive same-role sections produce one bar run — the transition count
+  equals the number of role changes, not the number of sections.
+- **Defaults on by default:** `disabled = false` is emitted for `kubernetes`/`time` when selected
+  (FR-16) and never for modules starship already enables.
+- **Layout:** `two_line`/`two_line_right` place `$line_break` before `$character`; `single` does
+  not; `two_line_right` moves Shell-group sections into `right_format` and out of `format`.
+- **Offline renderer:** `sample_markup()` mentions every selected section's sample value and is
+  valid Rich markup (rendered through a `Console` without raising).
+- **Save path:** `save()` honours `STARSHIP_CONFIG`, backs an existing file up to a timestamped
+  name, and leaves the backup byte-identical to the original.
+- **Wizard flow:** scripted `ui.*` prompts (the `FakePrompts` pattern from `test_agent_wizard.py`)
+  drive a full run and assert the written file reflects every choice; a cancel writes nothing.
+- **Registry:** `configure.get()` / `keys()` resolve starship and reject unknown keys.
+
+- **Presets as data:** every preset's `powerline` is one of the declared glyph sets; a preset with
+  no bars emits none of those glyphs anywhere in the file; each powerline preset's own four glyphs
+  appear in the expected counts (one cap, one transition per role change, one closing separator).
+- **Brackets / versions:** bracketed presets wrap every body except the one that brackets itself;
+  hiding versions drops `$version` and the symbol's trailing space, and is recorded in the header.
+- **Custom modules:** `${custom.compose}` is braced in `format`, the table is nested under
+  `custom`, and the shell script round-trips byte for byte through the multi-line literal string.
+- **Prompt symbol escaping:** the plain presets emit `[\$]`, not `[$]` (FR-20).
+
+Verification against the real binary (not in CI, which has no starship — run from the repo when
+touching the emitter):
+
+```python
+# for every preset × palette × layout × show_versions, with every section selected:
+#   starship print-config, starship prompt, starship prompt --right
+#   assert returncode == 0 and stderr == ""     # a *warning* is a failure here
+```
+
+That sweep is 1008 invocations and is how the `character`-module bug in §6a was found; a config
+that merely parses is not enough, since starship degrades unknown keys and bad format strings to
+a stderr warning and an empty render. Plus a visual check of the live preview per preset.
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| `starship prompt` flags differ across versions (`--terminal-width`, `--jobs`) | Try the full flag set, retry with a minimal one, then give up to the offline renderer. Never fatal (NFR-4). |
+| Nerd Font glyphs wrong or absent in the user's terminal | Glyphs are defined as explicit `\uXXXX` escapes with the Nerd Font name in a comment, so they are reviewable; the `plain` preset is the escape hatch and the two Nerd Font presets say so at the point of choosing. |
+| Preview subprocess hangs | 5 s timeout; timeout is treated as a failed render. |
+| Overwriting a hand-tuned `starship.toml` | Timestamped backup before write, path reported; the wizard warns when replacing a file it did not generate (no devstuff header). |
+| Sample project creation fails (no `git`) | Wrapped in try/except; git sections then simply do not render in the live preview, which is the same degradation as running outside a repo. |
+| Emitter and offline renderer drifting apart | Both consume the same `SECTIONS`/`PALETTES` tables; neither hard-codes a module list. |