devstuff 1.18.0__tar.gz → 2.0.0__tar.gz

{devstuff-1.18.0 → devstuff-2.0.0}/.claude/skills/run-stuff/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: run-stuff
-description: Run, build, test, and smoke-test the dev-setup CLI; exercise list/catalog/install commands
+description: Run, build, test, and smoke-test the devstuff CLI; exercise list/catalog/install commands
 ---
 
-`dev-setup` is a Python CLI that manages a Linux dev environment. It is driven directly via `uv run dev-setup <command>` — no GUI, no server, no browser. The smoke script at `.claude/skills/run-stuff/smoke.sh` is the primary agent harness.
+`devstuff` is a Python CLI that manages a Linux dev environment. It is driven directly via `uv run devstuff <command>` — no GUI, no server, no browser. The smoke script at `.claude/skills/run-stuff/smoke.sh` is the primary agent harness.
 
 ## Prerequisites
 
@@ -29,14 +29,14 @@ It exercises `version`, `list` (all variants), `catalog path`, `catalog export`,
 To exercise a specific command directly:
 
 ```bash
-uv run dev-setup version
-uv run dev-setup list
-uv run dev-setup list core
-uv run dev-setup list --installed
-uv run dev-setup list --available
-uv run dev-setup catalog path
-uv run dev-setup catalog export /tmp/export.yaml
-uv run dev-setup --help
+uv run devstuff version
+uv run devstuff list
+uv run devstuff list core
+uv run devstuff list --installed
+uv run devstuff list --available
+uv run devstuff catalog path
+uv run devstuff catalog export /tmp/export.yaml
+uv run devstuff --help
 ```
 
 Interactive commands (`install`, `remove`, `add`, `delete`) require a TTY and are not smoke-testable without mocking. To test them, run the app directly in a terminal.
@@ -44,8 +44,8 @@ Interactive commands (`install`, `remove`, `add`, `delete`) require a TTY and ar
 ## Run (human path)
 
 ```bash
-./dev-setup list        # bash wrapper — bootstraps .venv on first run
-./dev-setup install     # interactive multi-select picker
+./devstuff list        # bash wrapper — bootstraps .venv on first run
+./devstuff install     # interactive multi-select picker
 ```
 
 ## Test suite
@@ -59,7 +59,7 @@ All 6 unit tests pass in ~0.3s.
 
 ## Gotchas
 
-- `dev-setup` is not on `$PATH` directly in the dev environment — `uv run dev-setup` is the reliable invocation path. The `./dev-setup` bash wrapper also works from repo root and bootstraps its own `.venv`.
+- `devstuff` is not on `$PATH` directly in the dev environment — `uv run devstuff` is the reliable invocation path. The `./devstuff` bash wrapper also works from repo root and bootstraps its own `.venv`.
 - `pip` is not available in this environment; `uv pip install` is the substitute.
 - Interactive commands (`install`, `add`) open questionary/click prompts that hang in non-TTY shells. Pipe input only if you know the exact prompt sequence.
 - `catalog export` writes to a path argument; without an argument it prints to stdout. Check the README for the exact signature.

devstuff-2.0.0/.claude/skills/run-stuff/smoke.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# Smoke test for devstuff CLI. Run from repo root.
+set -euo pipefail
+
+PASS=0
+FAIL=0
+
+check() {
+  local label="$1"; shift
+  if output=$("$@" 2>&1); then
+    echo "  ✔  $label"
+    PASS=$((PASS+1))
+  else
+    echo "  ✘  $label"
+    echo "     Output: $output"
+    FAIL=$((FAIL+1))
+  fi
+}
+
+check_output() {
+  local label="$1"; local expected="$2"; shift 2
+  output=$("$@" 2>&1)
+  if echo "$output" | grep -q "$expected"; then
+    echo "  ✔  $label"
+    PASS=$((PASS+1))
+  else
+    echo "  ✘  $label (expected '$expected' in output)"
+    echo "     Got: $output"
+    FAIL=$((FAIL+1))
+  fi
+}
+
+echo ""
+echo "=== devstuff smoke tests ==="
+echo ""
+
+check "version" uv run devstuff version
+check_output "version number" "1\." uv run devstuff version
+check "list (all)" uv run devstuff list
+check "list core" uv run devstuff list core
+check "list tools" uv run devstuff list tools
+check "list --installed" uv run devstuff list --installed
+check "list --available" uv run devstuff list --available
+check "catalog path" uv run devstuff catalog path
+check_output "catalog path output" ".config/devstuff" uv run devstuff catalog path
+check "catalog export" uv run devstuff catalog export /tmp/devstuff-smoke-export.yaml
+check_output "help flag" "Commands:" uv run devstuff --help
+
+echo ""
+if [ "$FAIL" -eq 0 ]; then
+  echo "All $PASS checks passed."
+else
+  echo "$FAIL/$((PASS+FAIL)) checks failed."
+  exit 1
+fi

{devstuff-1.18.0 → devstuff-2.0.0}/.github/workflows/test-installs.yml

@@ -24,22 +24,22 @@ jobs:
         run: uv build
 
       # Two-step docker build matching the local dev workflow:
-      #   dev/Dockerfile        → dev-setup-sandbox  (minimal system + wheel installed)
-      #   dev/Dockerfile.ci     → dev-setup-ci       (+ pytest + test files baked in)
+      #   dev/Dockerfile        → devstuff-sandbox  (minimal system + wheel installed)
+      #   dev/Dockerfile.ci     → devstuff-ci       (+ pytest + test files baked in)
       - name: Build sandbox image
-        run: docker build -f dev/Dockerfile -t dev-setup-sandbox .
+        run: docker build -f dev/Dockerfile -t devstuff-sandbox .
 
       - name: Build CI test image
-        run: docker build -f dev/Dockerfile.ci -t dev-setup-ci .
+        run: docker build -f dev/Dockerfile.ci -t devstuff-ci .
 
       - name: Export image archive
-        run: docker save dev-setup-ci | gzip > dev-setup-ci.tar.gz
+        run: docker save devstuff-ci | gzip > devstuff-ci.tar.gz
 
       - name: Upload image artifact
         uses: actions/upload-artifact@v4
         with:
           name: docker-image
-          path: dev-setup-ci.tar.gz
+          path: devstuff-ci.tar.gz
           retention-days: 1
 
   # ─── Stage 2: one isolated container per tool, all run in parallel ───────────
@@ -81,12 +81,12 @@ jobs:
           name: docker-image
 
       - name: Load image
-        run: docker load < dev-setup-ci.tar.gz
+        run: docker load < devstuff-ci.tar.gz
 
       - name: Test ${{ matrix.tool }} installs
         run: |
           set +e
-          docker run --rm dev-setup-ci \
+          docker run --rm devstuff-ci \
             pytest "tests/integration/test_tools.py::test_install[${{ matrix.tool }}]" \
               -v --tb=short 2>&1 | tee test-output.txt
           RESULT=${PIPESTATUS[0]}

{devstuff-1.18.0 → devstuff-2.0.0}/CHANGELOG.md

@@ -1,3 +1,22 @@
+## v2.0.0 (2026-08-04)
+
+### BREAKING CHANGE
+
+- the `dev-setup` command alias is removed. Config/data moved
+from ~/.config/dev-setup and ~/.local/share/dev-setup to the devstuff
+equivalents. bashrc block markers renamed (dev-setup: bat -> devstuff: bat,
+dev-setup-fn:<key> -> devstuff-fn:<key>). Existing users run `devstuff
+doctor --fix` to migrate.
+
+### Features
+
+- drop dev-setup alias, rename paths to devstuff, add doctor command
+- **configure**: add pre-commit, docker, bat, ansible and lazygit wizards
+
+### Bug Fixes
+
+- **dev**: copy the devstuff wheel, not the stale dev_setup name
+
 ## v1.18.0 (2026-08-01)
 
 ### Features

{devstuff-1.18.0 → devstuff-2.0.0}/CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## What this is
 
-`dev-setup` is a Python CLI (Click + Rich + questionary) that installs, removes, and tracks
+`devstuff` is a Python CLI (Click + Rich + questionary) that installs, removes, and tracks
 developer tools on Linux. There is no per-tool Python code — every tool (built-in or
 user-added) is a data record in a YAML catalog, executed by one generic engine
 (`GenericTool` in `src/dev_setup/generic.py`). Adding a tool is a YAML edit, not a code change;
@@ -13,8 +13,8 @@ adding a new *install mechanism* (a "type") is a code change touched in ~5 place
 ## Commands
 
 ```bash
-uv run dev-setup <cmd>       # run from source (repo root)
-./dev-setup <cmd>            # bash wrapper — bootstraps .venv on first run, then execs Python
+uv run devstuff <cmd>       # run from source (repo root)
+./devstuff <cmd>            # bash wrapper — bootstraps .venv on first run, then execs Python
 uv run pytest                # unit tests only (integration tests skipped by default, ~0.3s)
 uv run pytest -m integration # real installs — requires sudo + network, run inside Docker (see below)
 uv run pytest tests/test_catalog.py::test_user_catalog_overrides_bundled_tool_in_place  # single test
@@ -67,7 +67,7 @@ src/dev_setup/
 ```
 
 **Catalog precedence** (`catalog.load_effective_catalog`): bundled `tools.yaml` loads first →
-user YAML at `~/.config/dev-setup/tools.yaml` overrides matching keys in place and appends
+user YAML at `~/.config/devstuff/tools.yaml` overrides matching keys in place and appends
 new ones. `registry.py` turns that merged dict into `GenericTool` instances; a tool is
 `builtin` only if it came from bundled and has no user override.
 
@@ -77,13 +77,13 @@ new ones. `registry.py` turns that merged dict into `GenericTool` instances; a t
 `generic.py`) rather than an if/elif chain, and shell out via `subprocess`. `install()` raises
 `RuntimeError`/`CalledProcessError` on failure — there's no result enum, command handlers just
 catch and report. `bash`-type scripts are written to a temp file and run with `bash <file>` for
-full parsing fidelity (not `bash -c "<string>"`). `dev-setup update` reuses the same dispatch
+full parsing fidelity (not `bash -c "<string>"`). `devstuff update` reuses the same dispatch
 pattern for upgrading an already-installed tool (latest or a pinned version); for `script`/
 `bash` types "update" is a full reinstall, since there's no narrower mechanism, so the command
 layer confirms before re-running it.
 
 **Two ways a tool gets defined**: built-in (an entry added directly to `src/dev_setup/tools.yaml`,
-`builtin=True`) or custom (created via the `dev-setup add` wizard, `dev-setup catalog import`,
+`builtin=True`) or custom (created via the `devstuff add` wizard, `devstuff catalog import`,
 or hand-edited YAML, landing in the user catalog). Both use the identical schema — the only
 difference is which file the key lives in and `category`.
 
@@ -123,7 +123,7 @@ installing PHP packages via Composer as their own first-class type (analogous to
 
 `src/dev_setup/functions.yaml` + `functions_catalog.py` + `functions_registry.py` +
 `function_runner.py` are a parallel, independent catalog/registry from tools — functions
-aren't installed/removed, they're invoked (`dev-setup run <key>`), so they get their own
+aren't installed/removed, they're invoked (`devstuff run <key>`), so they get their own
 schema instead of overloading `GenericTool`. Some duplication with `catalog.py`/`registry.py`
 is deliberate (see "Key design decisions" below).
 
@@ -133,18 +133,18 @@ loaded or enforced at runtime (no `jsonschema` dependency), so if you add/change
 a constraint in `functions_catalog.py`'s `validate_catalog()`, update the schema file too or
 they'll silently drift apart.
 
-**Why two function `type`s exist**: a `dev-setup` command is its own child process, so
+**Why two function `type`s exist**: a `devstuff` command is its own child process, so
 anything it does with `subprocess` (env vars, `cd`, aliases) is invisible to the shell that
 invoked it the moment the process exits. `type: script` is for functions that don't need to
 mutate the calling shell (runs as a subprocess, like a tool's `install_script`). `type:
 shell-eval` is for functions that must (`ssh-agent`, `nvm use`-style tools) — it has two
 `register` modes:
-- `register: bashrc` (default) — `dev-setup functions enable <key>` patches a real shell
+- `register: bashrc` (default) — `devstuff functions enable <key>` patches a real shell
   function into `~/.bashrc` via `base.patch_bashrc`; the user calls it directly by name in a
-  new shell afterward. `dev-setup run` refuses to run these directly (there's nothing it
+  new shell afterward. `devstuff run` refuses to run these directly (there's nothing it
   *can* do) and points at `functions enable` instead.
-- `register: eval` — `dev-setup run <key>` prints resolved shell code to stdout for
-  `eval "$(dev-setup run key args)"`. This path must never print anything else to stdout
+- `register: eval` — `devstuff run <key>` prints resolved shell code to stdout for
+  `eval "$(devstuff run key args)"`. This path must never print anything else to stdout
   (no `ui.*` calls, no prompts) since it would corrupt what gets `eval`'d — missing required
   params are reported on stderr and exit non-zero instead of being prompted for.
 
@@ -161,7 +161,7 @@ make `functions disable` orphan everything after it — closing brace included.
 
 Functions have a `category` field (defaults to `custom`, freeform — not an enum) that
 `functions list` groups/sorts by, mirroring tools. A `script`-type function that shells out to
-another CLI should guard on `command -v <tool>` and point at `dev-setup install <tool>` in the
+another CLI should guard on `command -v <tool>` and point at `devstuff install <tool>` in the
 error rather than let a raw "command not found" surface — see `validate-yaml`/`aws-saml-reauth`
 in `functions.yaml`. If that CLI is only reachable via nvm (like `pi`), source
 `"$HOME/.nvm/nvm.sh"` first (see `acc-check`) — `script`-type functions run via a non-login,
@@ -173,9 +173,27 @@ 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. There are two:
-`configure/starship/{model,render,preview,wizard}.py` and
-`configure/commitizen/{model,render,detect,validate,wizard}.py`.
+in a `CONFIGURATORS` dict keyed by catalog tool key. There are seven:
+`configure/starship/{model,render,preview,fonts,wizard}.py`,
+`configure/commitizen/{model,render,detect,validate,wizard}.py`,
+`configure/precommit/{model,render,detect,validate,wizard}.py` (the package can't be named
+`pre-commit`, so the hyphenated catalog key maps to the `precommit` package in `CONFIGURATORS`),
+`configure/docker/{model,render,detect,validate,wizard}.py`,
+`configure/bat/{model,render,detect,preview,wizard}.py`,
+`configure/ansible/{model,render,detect,validate,wizard}.py` and
+`configure/lazygit/{model,render,detect,validate,wizard}.py`.
+
+**The pattern they all share, and the one thing that matters most when adding another:**
+*measure the tool, don't recall it.* Every configurator's `model.py` was built by interrogating
+the installed binary, and in every single case that turned up something a plausible-sounding
+memory would have got wrong — see each one's "things learned" block below. If you are adding a
+configurator and you have not run the tool, you are guessing.
+
+**The second shared pattern: work out what the tool's own validator does *not* check.** All four
+of the newer wizards found their reason to exist there. `dockerd --validate`, `pre-commit
+validate-config`, `ansible-config validate` and lazygit's startup check each accept configs that
+are silently broken, and each in a different way. Establishing that boundary — by writing a
+deliberately broken config and seeing what happens — is the first thing to do, not the last.
 
 **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
@@ -282,9 +300,157 @@ other edit. Full reasoning in `docs/specs/commitizen-config/`.
   time — not on every redraw (~3s, unlike starship's millisecond preview) — and a disagreement
   *warns*, it never vetoes a save. Keep that distinction in the comments.
 
-Not yet built: configurators for anything other than starship and commitizen, and round-tripping an
-existing hand-edited config back into wizard state (the timestamped backup is the safety net
-instead).
+**Within the pre-commit configurator, the object being configured is a curated catalog of hooks,
+not arbitrary YAML.** `REPOS`/`HOOKS`/`PRESETS` in `model.py` are ordered and everything else reads
+them — adding a hook is one `Hook` record and it reaches the picker, any preset naming it, the
+language detector, the emitter and the preview with no other edit. Full reasoning in
+`docs/specs/precommit-config/`.
+
+**Things learned from the real binary — don't "simplify" these away:**
+- **`default_install_hook_types` is derived from the selected hooks' stages, never asked.**
+  `pre-commit install` installs *only* the `pre-commit` git hook unless given `--install-hook-types`,
+  so a `commit-msg` hook (commitizen's) without this yields a config that validates, an install
+  that reports success, and a hook that never fires. `install_hook_types()` feeds three places: the
+  emitted key, the `pre-commit install --hook-type` flags, and a check in `verify()`. Verified end
+  to end — with it, `git commit -m "oops no convention"` is rejected.
+- **`pre-commit validate-config` does not check hook ids.** It reads the file's shape and never
+  opens a repository, so a mistyped id passes and fails on the user's next commit. That is why
+  `validate.resolve()` (`pre-commit install-hooks`, network, minutes) exists as a separate level
+  from `verify()` (offline, milliseconds, runs before every save). Don't collapse them.
+- **Quoting asks the YAML parser rather than a rules table** (`render._str`): a scalar is written
+  bare only if `yaml.safe_load(value) == value`. This is what keeps shfmt's indent width `'2'` a
+  string, which pre-commit's schema requires, and a rev like `1.0` from becoming a float.
+- **`repos:` with nothing under it parses as null, not `[]`,** and pre-commit rejects it — the
+  emitter special-cases `repos: []`. Found by the round-trip assertion, not by reasoning.
+- **The emitter writes YAML by hand for the comments, and `render.matches()` parses it back and
+  compares against `render.data()`.** Those two representations must stay in sync; the round-trip
+  test over every preset is what enforces it. Don't swap in `yaml.safe_dump` (loses the comments)
+  or ruamel (a new runtime dependency for one wizard).
+- **`pre-commit autoupdate` can move a pin to a prerelease** (observed: isort `8.0.1` → `9.0.0b1`),
+  so "refresh the revs" shows a diff and confirms rather than applying silently. The GitHub tags
+  API is *not* version-ordered and disagreed with autoupdate in both directions — every rev in
+  `REPOS` is what autoupdate itself resolved.
+- **`ruff-check` carries `--exit-non-zero-on-fix` deliberately.** Without it the hook exits 0
+  having rewritten files, and the fixes silently miss the commit that triggered them.
+- **`Hook.needs` is load-bearing, not documentation.** It surfaces prerequisites on the review
+  screen *and* derives the pre-commit.ci `skip` list — pre-commit.ci has no Docker daemon, so
+  every `language: docker` hook must be skipped there or the whole CI run fails.
+- **Language detection goes through `git ls-files`** so gitignored content can't decide the
+  answer, and needs two files before a language counts — one stray `.sh` in a Python repo must not
+  pull in two Docker-backed hooks.
+- **The commitizen hook is only suggested when a commitizen config exists.** It runs `cz check`,
+  which fails *every* commit without one.
+- Conflicting hook pairs (`ruff-format` + `black`) are **warned about, not refused** — but no
+  shipped preset may contain one, which is a test.
+
+**Within the docker configurator, the object being configured is a daemon that has to be
+restarted before anything takes effect.** Full reasoning in `docs/specs/docker-config/`.
+
+**Things learned from the real binary — don't "simplify" these away:**
+- **`dockerd --validate` accepts five configs that break every container.** Measured: an
+  unloadable log driver, an unknown log option for the chosen driver, `compress: "true"` with
+  `max-file: "1"`, an address pool `size` below its base prefix, and `hosts` alongside a systemd
+  unit passing `-H`. The daemon starts healthy and every `docker run` then fails with an error
+  that never mentions daemon.json. `validate.py` runs `--validate` *and* those checks; do not
+  collapse it into "the tool already validates this".
+- **Per-driver `log-opts` are measured, and two contradict the obvious guess.** `local` *does*
+  take `tag`/`labels`/`env`; `journald` does *not* take `max-size`/`max-file`/`compress`. So
+  `log_opts()` filters by driver rather than emitting whatever was set.
+- **`none` is not in `docker info`'s `Plugins.Log`** — it is built into the daemon. The plugin
+  list is "drivers that certainly exist", not "all valid drivers", hence `BUILTIN_DRIVERS`.
+- **Only non-default values are written.** A config restating a default freezes it across
+  daemon upgrades. This makes `Setting.default` and the `DockerConfig` field default a pair that
+  must agree — which is a test, not a convention.
+- **daemon.json has no comment syntax**, so it cannot carry a "generated by" marker (an unknown
+  key is rejected — measured). The overwrite path shows a unified diff instead, which answers a
+  better question anyway.
+- **The restart is a separate confirmation and reads the daemon's *current* live-restore state**,
+  not the new config's: turning live-restore on protects the *next* restart, not the one applying
+  it.
+- Writes go through `sudo install` staged via a temp file, never a redirect — a truncating
+  redirect that fails leaves the daemon with half a config.
+
+**Within the bat configurator, the preview is the deliverable** — it is the closest sibling to
+starship's. Full reasoning in `docs/specs/bat-config/`.
+
+**Things learned from the real binary — don't "simplify" these away:**
+- **A bad theme is a warning and exit 0.** bat prints `[bat warning]: Unknown theme` to stderr —
+  which a pager swallows — and carries on with the default forever. Every theme named is checked
+  against `bat --list-themes`. A bad `--style` component, by contrast, is a hard error and needs
+  no help; the checks are asymmetric on purpose.
+- **The theme list is read at run time, not tabled.** `bat cache --build` lets users add their
+  own. The shipped table is the offline fallback plus the light/dark metadata bat does not
+  expose — and a test asserts every shipped name still exists, so the fallback can't rot.
+- **Classifying themes by foreground luminance is wrong for Solarized.** Both variants share one
+  palette by design and measure identically; three more (`ansi`, `base16`, `base16-256`) emit no
+  true colour at all. Hence three modes, hand-corrected against the measurement.
+- **Unquoted values containing spaces are split into arguments** — `--theme=Solarized (dark)`
+  makes bat try to open a file called `(dark)`. Every value is quoted.
+- **`rule` is a subset of `grid`** and bat says so. Found when the live check rejected a
+  "turn everything on" preset; all 21 component pairs were then swept and this is the only one.
+- The preview clears every `BAT_*` variable, because they beat the config file — otherwise it
+  would render the environment's theme while claiming to show the candidate's.
+
+**Within the ansible configurator, the check that matters is "did ansible *read* this",
+not "is this valid".** Full reasoning in `docs/specs/ansible-config/`.
+
+**Things learned from the real binary — don't "simplify" these away:**
+- **`[ssh_connection]` is not a section ansible-core reads.** `pipelining` moved to `[defaults]`.
+  Verified both ways: under `[ssh_connection]` nothing appears in `ansible-config dump
+  --only-changed`; under `[defaults]` it appears as `ANSIBLE_PIPELINING`. That stanza is the most
+  copy-pasted three lines in Ansible and it is inert.
+- **So the load-bearing check is the dump comparison**, not `ansible-config validate`. Every
+  setting written must appear in `ansible-config dump --only-changed` sourced from our file. A
+  test proves the check can *fail* by moving `pipelining` back into `[ssh_connection]`.
+- **The `yaml` stdout callback was removed** — superseded by `callback_result_format`. Setting
+  `stdout_callback = yaml` passes every check and produces JSON. The first draft of the `project`
+  preset did exactly this.
+- **`ansible-config validate` rejects a working setting.** `callback_result_format` is a
+  callback-*plugin* option and the validator only knows core settings. So it is unreliable in
+  both directions. Hence `Setting.dump_type`, the discounted complaint (stated in the check's own
+  detail, never silent), and the warning telling the user what they will see.
+- **Plugin options dump under `-t <type>` and in lowercase**, unlike core settings' SHOUTING_CASE.
+- **Values are never quoted.** `inventory = "./inv"` becomes a path containing quotes, and
+  `pipelining = "True"` is read as **False** — quoting a boolean inverts it. The reader coerces
+  the way ansible does, not the way `configparser` would.
+- **A retired section is preserved and reported, never migrated.** The wizard cannot know whether
+  an older ansible elsewhere still reads it.
+- **ansible ignores `./ansible.cfg` in a world-writable directory** — warned about before the
+  questions and again after the save.
+
+**Within the lazygit configurator, the tool provides no usable way to check a config's keys.**
+Full reasoning in `docs/specs/lazygit-config/`.
+
+**Things learned from the real binary — don't "simplify" these away:**
+- **lazygit rejects wrong *types* and silently ignores unknown *keys* and invalid enum values.**
+  Everything in the package follows from that split. Two live tests assert both halves, so a
+  future lazygit changing either is caught.
+- **`lazygit --config` is not a key list.** It omits every setting with no default, including
+  `git.paging.pager` — the delta integration everyone wants. Treating it as authoritative would
+  have made the wizard refuse to write the most-wanted setting there is.
+- **Keys were verified with a type probe**: set the key to a value of obviously the wrong type
+  and start lazygit; a real key errors, an unknown one is ignored. The method is recorded in
+  `model.py` so the table can be re-derived. It is what found `git.paging.useConfig` dead.
+- **The defaults dump *is* used for values**, and `default_drift()` compares it against the
+  model — which caught `gui.sidePanelWidth` being modelled as a string when it is a float. A
+  setting absent from the dump is explicitly *not* drift.
+- **PyYAML cannot load lazygit's own default config.** `expandAll: =` hits YAML's
+  `tag:yaml.org,2002:value` and `safe_load` raises. All parsing goes through `render.load()`, and
+  `=` is quoted on the way out.
+- **A list of mappings must not be hand-emitted.** The first emitter stringified
+  `customCommands` — the user data this wizard most promises not to damage. Carried-over
+  structures go through `yaml.safe_dump` and are re-indented; only settings the wizard authors
+  are hand-emitted, because only those need comments.
+- **Icons reuse `configure/starship/fonts.detect()`**, including its `None` — "cannot tell" is
+  not "no", and inverting that would nag every user without fontconfig.
+
+Not yet built: configurators for anything other than starship, commitizen, pre-commit, docker,
+bat, ansible and lazygit; `repo: local` pre-commit hook authoring and hooks outside the curated
+catalog; lazygit keybindings and `customCommands` authoring (both preserved, never edited);
+ansible fact-caching backends; and — for pre-commit and commitizen only — round-tripping an
+existing hand-edited config back into wizard state. The four newer configurators *do* round-trip,
+because JSON, INI, bat's flag list and lazygit's YAML are all flat enough to preserve faithfully;
+pre-commit's is not, and that asymmetry is deliberate (see each spec's stack-decisions).
 
 ## Specs (`docs/specs/`)
 
@@ -321,7 +487,7 @@ strategy-dispatch pattern as `_INSTALLERS` in `generic.py`.
   deliberately not disabled by `--yolo`. The prompt is a human attention filter; attention
   degrades over a session, the denylist does not.
 - Credential dirs are blocked for **read** as well as write — exfiltrating an SSH key into a model
-  context is as bad as overwriting one. `~/.config/dev-setup` is readable but not writable, so
+  context is as bad as overwriting one. `~/.config/devstuff` is readable but not writable, so
   the agent cannot author catalogs (FR-14a).
 - `assess()` (the launch guard) is advisory UX, not a control. Keep that distinction in comments;
   the risk is a future reader mistaking a warning for enforcement.