devstuff 2.2.0__tar.gz → 2.3.0__tar.gz

{devstuff-2.2.0 → devstuff-2.3.0}/.github/workflows/test-installs.yml

@@ -51,27 +51,32 @@ jobs:
       fail-fast: false  # let all tools run even when some fail
       matrix:
         tool:
+          - ansible       # uvx tool, requires uv
+          - ansible-vault # shares ansible's tool environment
           - aws
+          - bat
           - commitizen  # uvx tool, requires uv
-          - eza
           - gh
           - git-lfs
           - go
+          - homebrew    # slow: builds from source
           - htop
           - ipython     # uvx tool, requires uv
           - java
           - lazygit
+          - llm-checker # npm tool, installs nvm first via `requires`
+          - lmstudio
           - mkcert
           - nerd-font
           - nvm
           - php
           - pi          # installs nvm first via its declared `requires`
           - pre-commit  # uvx tool, requires uv
+          - python      # uv-managed CPython, requires uv
           - ruby        # compiles from source — this job takes ~15 minutes
           - saml2aws
           - starship
           - uv
-          - whichllm    # uvx tool, requires uv
           - yq
 
     steps:

{devstuff-2.2.0 → devstuff-2.3.0}/CHANGELOG.md

@@ -1,3 +1,15 @@
+## v2.3.0 (2026-08-13)
+
+### Features
+
+- make uv the install backbone, and fix ansible (#42)
+
+## v2.2.1 (2026-08-05)
+
+### Bug Fixes
+
+- repair the two failing builtin install integration tests (#40)
+
 ## v2.2.0 (2026-08-05)
 
 ### Features

{devstuff-2.2.0 → devstuff-2.3.0}/CLAUDE.md

@@ -83,6 +83,36 @@ pattern for upgrading an already-installed tool (latest or a pinned version); fo
 `bash` types "update" is a full reinstall, since there's no narrower mechanism, so the command
 layer confirms before re-running it.
 
+**uv is the backbone for Python-packaged tools** (spec in `docs/specs/uv-backbone/`). The
+`uvx`/`pip` types accept three optional fields beyond `pip_name` — `uv_with`,
+`uv_executables_from`, `uv_python` — assembled into argv by `_uv_install_flags` in `generic.py`
+and rejected by `validate_catalog()` on every other type. Three things about them are
+load-bearing:
+- **`uv tool install` only exposes console scripts of the *requested* package.** The `ansible`
+  distribution is a collections bundle declaring none of its own, so `pip_name: ansible` alone
+  installs one unusable `ansible-community` binary and reports success. `uv_executables_from:
+  [ansible-core]` is what produces the eleven real ones. Don't "simplify" it to
+  `pip_name: ansible-core` — that silently drops the bundled collections.
+- **`_update_uvx` never uses `uv tool upgrade`** — both paths are `uv tool install --force`
+  (`<pkg>==<ver>` pinned, `<pkg>@latest` otherwise). `uv tool upgrade` can't take a requirement
+  *and* is a no-op on an already-pinned tool, so the obvious pairing makes a pin a one-way door.
+  `--force` writes a fresh receipt, so the `uv_*` flags are re-passed on every update; that is
+  deliberate, since it also means a newly added `uv_with` applies on update, not just reinstall.
+  Anything printed telling a user how to escape a pin must be measured — two plausible remedies
+  ("re-run without `--version`", "run `devstuff install`") are both false, the second because
+  `install_cmd` returns early on `is_installed()`.
+- **The `python` entry provisions CPython through uv** (`uv python install --default`). Its
+  `check_cmd` is the delicate part: every host has a `python3`, so the check requires the default
+  shim to *resolve inside* `uv python dir`, uses `test -x` so a dangling shim from a removed
+  interpreter reads as absent, and guards `test -n "$d"` because an empty `uv python dir` would
+  collapse the `case` pattern to `/*` and match everything. Removal uninstalls only the version
+  the default shim points at — `uv python uninstall --all` would also destroy managed interpreters
+  that existing `uv tool` environments were built against.
+- **`_remove_uvx` honours an explicit `remove_script`**, mirroring `_remove_apt`. Two entries can
+  share one `pip_name` (`ansible-vault` shares `ansible`'s), and there `uv tool uninstall` would
+  tear out the shared environment. Extras need no field: `pip_name` reaches `subprocess` as one
+  argv element, never a shell, so `pip_name: "ansible-lint[lock]"` already works.
+
 **Verbosity** (`verbose.py`, spec in `docs/specs/verbose-mode/`): one process-wide level —
 `0` / `-v` / `-vv` — set by a Click callback and read by the subprocess helpers, never threaded
 through call signatures. Three things about it are load-bearing:
@@ -114,7 +144,15 @@ Add an entry to `src/dev_setup/tools.yaml` using an existing `type` (`npm`, `pip
 and per-type examples. Then:
 - Add the key to `.github/workflows/test-installs.yml`'s matrix (or to `_SKIP` in
   `tests/integration/test_tools.py` with a reason, if it can't run in CI).
-- Add it to the relevant table in README.md ("Built-in packages").
+  `test_ci_matrix_covers_every_builtin_tool` enforces this, in both directions — a stale matrix
+  entry names a pytest node id that matches nothing, so the job exits 4 and the workflow files a
+  GitHub issue every week. That went unnoticed for `eza`/`whichllm` from July until the test
+  existed, which is why it is a test and not a line in this file.
+- Add it to the relevant table in README.md ("Built-in packages"). Not enforced by a test —
+  the tables are prose-formatted and grouped loosely, so check by hand.
+- If it needs an executable that belongs to a *dependency* rather than the package itself, add
+  it to `_EXTRA_EXECUTABLES` in `tests/integration/test_tools.py`; `is_installed()` alone would
+  pass on a half-installed tool (see the `uvx` notes above).
 - No Python code changes needed — `GenericTool` already knows how to run every existing type.
 
 ## Adding a new tool *type* (e.g. a `composer`/PHP-package type)
@@ -194,6 +232,12 @@ through its exit code — only whether it ran. A "found nothing" answer should t
 say so, or the user gets a red "command failed" banner under a correct result; keep non-zero for
 "could not perform the lookup" (see `whats-on-port`'s comment on this).
 
+The way this rule actually gets broken is not a stray `exit 1` — it is **a bare `[ -n "$x" ] &&
+echo …` as the last statement of a branch**, which silently becomes the script's exit status when
+the test is false. `which-ansible` shipped that bug in its first draft: "no global ansible found",
+a correct answer, exited 1. Use a full `if`, and end such scripts with an explicit `exit 0`. It is
+only catchable by *running* every branch, not by reading them.
+
 Not yet built: an `add` wizard and `catalog import`/`export` for functions, analogous to the
 ones tools already have.
 

{devstuff-2.2.0 → devstuff-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: devstuff
-Version: 2.2.0
+Version: 2.3.0
 Summary: Development environment setup CLI for Linux
 Project-URL: Repository, https://github.com/thesawdawg/dev-setup-py
 Author-email: Sawyer <sawyerksu@gmail.com>
@@ -287,7 +287,7 @@ How "update" is performed depends on the package's install `type`:
 | Type | Latest | Specific version |
 |------|--------|-------------------|
 | `npm` | `npm install -g <pkg>@latest` | `npm install -g <pkg>@<version>` |
-| `pip` / `uvx` | `uv tool upgrade <pkg>` | `uv tool upgrade <pkg>==<version>` |
+| `pip` / `uvx` | `uv tool install --force <pkg>@latest` | `uv tool install --force <pkg>==<version>` |
 | `apt` | `apt-get install --only-upgrade` | `apt-get install <pkg>=<version>` (single package only) |
 | `git` | `git pull` (+ re-run `git_install_cmd`) | not supported — repos are cloned shallow (`--depth=1`) |
 | `script` / `bash` | Re-runs the install script | not supported — no version parameter to inject |
@@ -296,6 +296,17 @@ For `script`/`bash` packages, "update" is a full reinstall (the same script that
 `sudo` runs again), since there's no narrower update mechanism available. `devstuff update` asks
 for confirmation before doing this.
 
+`pip`/`uvx` packages go through `uv tool install` rather than `uv tool upgrade` in **both**
+columns. `uv tool upgrade` takes a tool *name*, so it cannot accept `<pkg>==<version>` at all, and
+it is a no-op on a tool that was previously pinned — using it for the "latest" column would mean
+pinning a package once left no way to move it again. `<pkg>@latest` re-resolves and clears any
+existing pin in one step. Pinning warns that the pin holds until the next `devstuff update`
+without `--version`.
+
+Any `uv_with` / `uv_executables_from` / `uv_python` fields on the package are re-applied on every
+update, so adding one to your catalog takes effect on the next update rather than needing a
+reinstall.
+
 ---
 
 ### `configure`
@@ -1132,6 +1143,7 @@ ones tools already have — for now, custom functions are hand-edited YAML at
 | `whats-on-port` | network | script | Find which process is listening on a port | `port`, `protocol` (optional: `tcp`/`udp`/`all`) |
 | `acc-check` | web-dev | script | Run the pi coding agent's `/dogfood` skill against a web URL | `url`, `instruction` (optional) |
 | `aws-saml-reauth` | web-dev | script | Reauthorize the AWS CLI via `saml2aws login --force` | `profile` (optional) |
+| `which-ansible` | validation | script | Show which ansible a directory will actually use — the project's uv venv or the global one | `path` (optional) |
 
 #### `whats-on-port`
 
@@ -1163,6 +1175,32 @@ so a missing `ss` names the apt package instead of surfacing "command not found"
 
 ---
 
+#### `which-ansible`
+
+```bash
+devstuff run which-ansible              # the current directory
+devstuff run which-ansible ~/infra      # somewhere else
+```
+
+Answers "if I type `ansible-playbook` here, which one runs?" — the project's own uv venv, or the
+global tool install. It walks up for a `pyproject.toml`/`uv.lock` the way uv does, then reports
+whichever applies:
+
+- a synced project venv, plus the `uv run ansible-playbook` invocation that uses it (and what a
+  bare `ansible-playbook` would pick instead);
+- ansible declared but not synced yet, pointing at `uv sync`;
+- no ansible in the project, or no project at all, naming the global one.
+
+Every one of those is a success and exits 0 — including "this project has no ansible", which is
+an answer, not a failure. Non-zero is reserved for not being able to look at all (no uv, or a
+path that isn't a directory).
+
+It exists because devstuff's ansible and a uv-managed ansible repo are now the *same shape* — both
+a uv-created venv — so the question stopped being "which tool is broken" and became "which
+environment am I in". See `docs/specs/uv-backbone/` for why the global one moved off apt.
+
+---
+
 ## Built-in packages
 
 ### Core
@@ -1182,13 +1220,18 @@ Optional utilities you may want on some machines.
 | Key | Name | Description | Help |
 |-----|------|-------------|------|
 | `ansible` | Ansible | Automation engine for configuration management and app deployment (`devstuff configure ansible`) | `ansible --help` |
+| `ansible-vault` | Ansible Vault | Encrypt and manage secrets within Ansible projects (bundled with Ansible) | `ansible-vault --help` |
 | `aws` | AWS CLI | Amazon Web Services CLI v2 | `aws help` |
 | `bat` | bat | cat replacement with syntax highlighting and git integration (`devstuff configure bat`) | `bat --help` |
 | `commitizen` | Commitizen | Conventional-commit prompt, semantic version bumping, and changelog generation (`devstuff configure commitizen`) | `cz --help` |
-| `eza` | eza | Modern ls replacement with git status, icons, and tree view | `eza --help` |
 | `gh` | GitHub CLI | GitHub's official CLI | `gh --help` |
+| `git-lfs` | Git LFS | Git extension for versioning large files | `git lfs --help` |
 | `htop` | htop | Interactive process and resource monitor | `man htop` |
+| `homebrew` | Homebrew | Package manager for Linux (and macOS) | `brew --help` |
+| `ipython` | IPython | Enhanced interactive Python shell with rich tab completion and magic commands | `ipython --help` |
 | `lazygit` | lazygit | TUI git client for fast, keyboard-driven git workflows (`devstuff configure lazygit`) | `lazygit --help` |
+| `llm-checker` | llm-checker | Check LLM compatibility with your hardware | `llm-checker --help` |
+| `lmstudio` | LM Studio | Run large language models locally with a GUI | `lms --help` |
 | `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` |
@@ -1205,6 +1248,7 @@ Optional utilities you may want on some machines.
 |-----|------|-------------|------|
 | `go` | Go | Go programming language toolchain | `go help` |
 | `java` | Java 21 (OpenJDK) | OpenJDK 21 LTS - JDK and JRE | `java --help` |
+| `python` | Python (uv-managed) | CPython provisioned by uv, installed as the default `python`/`python3` | `uv python list` |
 | `ruby` | Ruby (rbenv) | Ruby via rbenv version manager + ruby-build | `ruby --version` |
 
 ---
@@ -1247,7 +1291,10 @@ tools:
 | `docs_url` | no | URL opened by `devstuff docs <key>` |
 | `requires` | no | List of package keys that must already be installed |
 | `npm_name` | npm | npm package name |
-| `pip_name` | pip | PyPI package name |
+| `pip_name` | pip | PyPI package name. Extras work as-is: `pip_name: "ansible-lint[lock]"` |
+| `uv_with` | no (pip/uvx) | Extra packages installed into the tool's environment (`uv tool install --with`) |
+| `uv_executables_from` | no (pip/uvx) | Also expose console scripts from these packages (`--with-executables-from`). Needed when a package's entry points live in a dependency |
+| `uv_python` | no (pip/uvx) | Pin the tool environment's Python (`--python`), e.g. `"3.12"` |
 | `apt_packages` | apt | Space-separated list of apt packages |
 | `git_url` | git | Repository URL to clone |
 | `git_install_cmd` | git | Bash command run inside the cloned repo after clone |
@@ -1256,7 +1303,21 @@ tools:
 | `install_script` | bash | Full bash script to run on install |
 | `remove_script` | bash | Full bash script to run on remove |
 
-Unknown fields fail validation. `requires` defaults to `["nvm"]` for `npm` tools and `["uv"]` for `pip`/`uvx` tools unless explicitly set.
+Unknown fields fail validation — including the three `uv_*` fields on any type other than `pip`/`uvx`. `requires` defaults to `["nvm"]` for `npm` tools and `["uv"]` for `pip`/`uvx` tools unless explicitly set.
+
+`uv_executables_from` is worth understanding before you skip it: `uv tool install` exposes the console scripts of the *requested* package only. The `ansible` distribution is a collections bundle that declares none of its own — `ansible`, `ansible-playbook` and `ansible-vault` are all entry points of its `ansible-core` dependency — so without this field the install reports success and puts a single unusable `ansible-community` on `PATH`:
+
+```yaml
+version: 1
+tools:
+  ansible:
+    name: Ansible
+    type: uvx
+    check_cmd: ansible
+    pip_name: ansible
+    uv_executables_from:
+      - ansible-core
+```
 
 ### Examples
 

{devstuff-2.2.0 → devstuff-2.3.0}/README.md

@@ -260,7 +260,7 @@ How "update" is performed depends on the package's install `type`:
 | Type | Latest | Specific version |
 |------|--------|-------------------|
 | `npm` | `npm install -g <pkg>@latest` | `npm install -g <pkg>@<version>` |
-| `pip` / `uvx` | `uv tool upgrade <pkg>` | `uv tool upgrade <pkg>==<version>` |
+| `pip` / `uvx` | `uv tool install --force <pkg>@latest` | `uv tool install --force <pkg>==<version>` |
 | `apt` | `apt-get install --only-upgrade` | `apt-get install <pkg>=<version>` (single package only) |
 | `git` | `git pull` (+ re-run `git_install_cmd`) | not supported — repos are cloned shallow (`--depth=1`) |
 | `script` / `bash` | Re-runs the install script | not supported — no version parameter to inject |
@@ -269,6 +269,17 @@ For `script`/`bash` packages, "update" is a full reinstall (the same script that
 `sudo` runs again), since there's no narrower update mechanism available. `devstuff update` asks
 for confirmation before doing this.
 
+`pip`/`uvx` packages go through `uv tool install` rather than `uv tool upgrade` in **both**
+columns. `uv tool upgrade` takes a tool *name*, so it cannot accept `<pkg>==<version>` at all, and
+it is a no-op on a tool that was previously pinned — using it for the "latest" column would mean
+pinning a package once left no way to move it again. `<pkg>@latest` re-resolves and clears any
+existing pin in one step. Pinning warns that the pin holds until the next `devstuff update`
+without `--version`.
+
+Any `uv_with` / `uv_executables_from` / `uv_python` fields on the package are re-applied on every
+update, so adding one to your catalog takes effect on the next update rather than needing a
+reinstall.
+
 ---
 
 ### `configure`
@@ -1105,6 +1116,7 @@ ones tools already have — for now, custom functions are hand-edited YAML at
 | `whats-on-port` | network | script | Find which process is listening on a port | `port`, `protocol` (optional: `tcp`/`udp`/`all`) |
 | `acc-check` | web-dev | script | Run the pi coding agent's `/dogfood` skill against a web URL | `url`, `instruction` (optional) |
 | `aws-saml-reauth` | web-dev | script | Reauthorize the AWS CLI via `saml2aws login --force` | `profile` (optional) |
+| `which-ansible` | validation | script | Show which ansible a directory will actually use — the project's uv venv or the global one | `path` (optional) |
 
 #### `whats-on-port`
 
@@ -1136,6 +1148,32 @@ so a missing `ss` names the apt package instead of surfacing "command not found"
 
 ---
 
+#### `which-ansible`
+
+```bash
+devstuff run which-ansible              # the current directory
+devstuff run which-ansible ~/infra      # somewhere else
+```
+
+Answers "if I type `ansible-playbook` here, which one runs?" — the project's own uv venv, or the
+global tool install. It walks up for a `pyproject.toml`/`uv.lock` the way uv does, then reports
+whichever applies:
+
+- a synced project venv, plus the `uv run ansible-playbook` invocation that uses it (and what a
+  bare `ansible-playbook` would pick instead);
+- ansible declared but not synced yet, pointing at `uv sync`;
+- no ansible in the project, or no project at all, naming the global one.
+
+Every one of those is a success and exits 0 — including "this project has no ansible", which is
+an answer, not a failure. Non-zero is reserved for not being able to look at all (no uv, or a
+path that isn't a directory).
+
+It exists because devstuff's ansible and a uv-managed ansible repo are now the *same shape* — both
+a uv-created venv — so the question stopped being "which tool is broken" and became "which
+environment am I in". See `docs/specs/uv-backbone/` for why the global one moved off apt.
+
+---
+
 ## Built-in packages
 
 ### Core
@@ -1155,13 +1193,18 @@ Optional utilities you may want on some machines.
 | Key | Name | Description | Help |
 |-----|------|-------------|------|
 | `ansible` | Ansible | Automation engine for configuration management and app deployment (`devstuff configure ansible`) | `ansible --help` |
+| `ansible-vault` | Ansible Vault | Encrypt and manage secrets within Ansible projects (bundled with Ansible) | `ansible-vault --help` |
 | `aws` | AWS CLI | Amazon Web Services CLI v2 | `aws help` |
 | `bat` | bat | cat replacement with syntax highlighting and git integration (`devstuff configure bat`) | `bat --help` |
 | `commitizen` | Commitizen | Conventional-commit prompt, semantic version bumping, and changelog generation (`devstuff configure commitizen`) | `cz --help` |
-| `eza` | eza | Modern ls replacement with git status, icons, and tree view | `eza --help` |
 | `gh` | GitHub CLI | GitHub's official CLI | `gh --help` |
+| `git-lfs` | Git LFS | Git extension for versioning large files | `git lfs --help` |
 | `htop` | htop | Interactive process and resource monitor | `man htop` |
+| `homebrew` | Homebrew | Package manager for Linux (and macOS) | `brew --help` |
+| `ipython` | IPython | Enhanced interactive Python shell with rich tab completion and magic commands | `ipython --help` |
 | `lazygit` | lazygit | TUI git client for fast, keyboard-driven git workflows (`devstuff configure lazygit`) | `lazygit --help` |
+| `llm-checker` | llm-checker | Check LLM compatibility with your hardware | `llm-checker --help` |
+| `lmstudio` | LM Studio | Run large language models locally with a GUI | `lms --help` |
 | `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` |
@@ -1178,6 +1221,7 @@ Optional utilities you may want on some machines.
 |-----|------|-------------|------|
 | `go` | Go | Go programming language toolchain | `go help` |
 | `java` | Java 21 (OpenJDK) | OpenJDK 21 LTS - JDK and JRE | `java --help` |
+| `python` | Python (uv-managed) | CPython provisioned by uv, installed as the default `python`/`python3` | `uv python list` |
 | `ruby` | Ruby (rbenv) | Ruby via rbenv version manager + ruby-build | `ruby --version` |
 
 ---
@@ -1220,7 +1264,10 @@ tools:
 | `docs_url` | no | URL opened by `devstuff docs <key>` |
 | `requires` | no | List of package keys that must already be installed |
 | `npm_name` | npm | npm package name |
-| `pip_name` | pip | PyPI package name |
+| `pip_name` | pip | PyPI package name. Extras work as-is: `pip_name: "ansible-lint[lock]"` |
+| `uv_with` | no (pip/uvx) | Extra packages installed into the tool's environment (`uv tool install --with`) |
+| `uv_executables_from` | no (pip/uvx) | Also expose console scripts from these packages (`--with-executables-from`). Needed when a package's entry points live in a dependency |
+| `uv_python` | no (pip/uvx) | Pin the tool environment's Python (`--python`), e.g. `"3.12"` |
 | `apt_packages` | apt | Space-separated list of apt packages |
 | `git_url` | git | Repository URL to clone |
 | `git_install_cmd` | git | Bash command run inside the cloned repo after clone |
@@ -1229,7 +1276,21 @@ tools:
 | `install_script` | bash | Full bash script to run on install |
 | `remove_script` | bash | Full bash script to run on remove |
 
-Unknown fields fail validation. `requires` defaults to `["nvm"]` for `npm` tools and `["uv"]` for `pip`/`uvx` tools unless explicitly set.
+Unknown fields fail validation — including the three `uv_*` fields on any type other than `pip`/`uvx`. `requires` defaults to `["nvm"]` for `npm` tools and `["uv"]` for `pip`/`uvx` tools unless explicitly set.
+
+`uv_executables_from` is worth understanding before you skip it: `uv tool install` exposes the console scripts of the *requested* package only. The `ansible` distribution is a collections bundle that declares none of its own — `ansible`, `ansible-playbook` and `ansible-vault` are all entry points of its `ansible-core` dependency — so without this field the install reports success and puts a single unusable `ansible-community` on `PATH`:
+
+```yaml
+version: 1
+tools:
+  ansible:
+    name: Ansible
+    type: uvx
+    check_cmd: ansible
+    pip_name: ansible
+    uv_executables_from:
+      - ansible-core
+```
 
 ### Examples
 

devstuff-2.3.0/docs/specs/uv-backbone/development-plan.md

@@ -0,0 +1,131 @@
+# uv as the install backbone — development plan
+
+Companion to `specifications.md` and `stack-decisions.md`.
+
+## Suggested first vertical slice
+
+**FR-2 + FR-7 + the `ansible` catalog entry.** Adding just `uv_executables_from` and rewriting the
+`ansible` entry is enough to prove the whole design end to end — it is the field with the most
+mechanism behind it, and `ansible --version` reporting eleven binaries off a uv venv is an
+unambiguous pass/fail. `uv_with` and `uv_python` are trivial once the argv-building shape exists.
+
+## Milestones
+
+### M1 — engine fields (FR-1..FR-8) — **done 2026-08-12**
+
+Touching, per CLAUDE.md's five-place rule for schema changes:
+
+1. `src/dev_setup/catalog.py` — add `uv_with`, `uv_executables_from`, `uv_python` to
+   `SUPPORTED_FIELDS`; add the type-gate in `validate_catalog()` (FR-4). No `requires` inference
+   changes — `uvx` already infers `["uv"]`, and that stays correct.
+2. `src/dev_setup/generic.py` — the three fields in `GenericTool.__init__`, `from_dict`, `to_dict`
+   (FR-6); argv building in `_install_uvx` (FR-7).
+3. `src/dev_setup/commands/add_cmd.py` — three optional prompts in the `uvx`/`pip` branch (FR-8).
+4. `README.md` — type table, YAML schema field table, and a worked ansible example.
+5. `tests/test_catalog.py` — accepted on `uvx`, rejected on `apt`/`bash`, `to_dict` round-trip,
+   and `to_dict` omitting them when empty.
+
+**Exit:** `uv run pytest` green; a hand-written user catalog entry using all three fields loads.
+
+### M2 — the update-path bug (FR-9, FR-10, FR-10a) — **done 2026-08-12**
+
+`_update_uvx` routes **both** paths through `uv tool install --force` plus the FR-1..3 flags:
+`<pkg>==<ver>` when pinned, `<pkg>@latest` otherwise.
+
+The plan originally kept `uv tool upgrade` for the unpinned path; measuring it during
+implementation showed that would have left a pinned tool permanently stuck (F-10), so the
+requirement changed. Two draft warning texts named remedies that did not work (F-11) before the
+current one was verified end to end.
+
+This is a **pre-existing bug**, not a regression from M1 — `devstuff update <uvx-tool> --version X`
+has never worked (F-5).
+
+**Exit (met):** unit tests assert the argv shape for the pinned branch, the unpinned branch, flag
+re-application, and the warning text. Verified against real uv: pin → 4.16.0 with a specifier in
+the receipt; plain update → 4.17.0 with the specifier gone. Ansible keeps all eleven executables
+across both a pinned and an unpinned update.
+
+### M3 — ansible conversion (FR-11..FR-14) — **done 2026-08-12**
+
+Rewrite `ansible` and `ansible-vault` in `tools.yaml` per the conversion table. Drop `ansible`'s
+apt `remove_script` (FR-13). Keep `ansible-vault`'s.
+
+`.github/workflows/test-installs.yml` — **this plan was wrong**: neither `ansible` nor
+`ansible-vault` was in the matrix. Both added. Neither is in `_SKIP`, so the integration test
+auto-parametrisation already covered them locally; only CI was missing them.
+
+The integration assertion was strengthened as the risk table demanded: `_EXTRA_EXECUTABLES` in
+`tests/integration/test_tools.py` now asserts `ansible-playbook`/`ansible-galaxy`/`ansible-vault`/
+`ansible-doc` resolve on `PATH`, not just that `is_installed()` is true.
+
+**Exit:** `cd dev && make run-tests TOOL=ansible` passes, and a manual check that all eleven
+executables resolve and `ansible --version` reports the uv venv interpreter (FR-12).
+
+### M4 — uv-managed Python (FR-15..FR-17) — **done 2026-08-12**
+
+New `python` entry in `tools.yaml`. The risk here is entirely in `check_cmd` (FR-16, SD-8) — write
+it against `uv python list --only-installed` / `uv python dir` rather than `command -v python3`, and
+verify it answers *false* on a machine that has system Python but no uv-managed one.
+
+**Exit (met):** added to the CI matrix. The check was verified false-then-true across an install,
+and separately against the two ways it could lie: a dangling shim from a removed interpreter
+(F-14, which this machine already had) and a missing uv collapsing the match pattern to `/*`
+(F-15). Removal is targeted rather than `--all` (F-13).
+
+### M5 — per-repo ansible helper (FR-18..FR-20) — **done 2026-08-12**
+
+New `functions.yaml` entry. Also update `src/dev_setup/functions.schema.json` if any field shape
+changes — CLAUDE.md notes it is hand-maintained and drifts silently.
+
+**Exit (met):** run in five states — no uv (exit 1), bad path (exit 1), `/tmp` with no project
+(0), this repo which is a uv project without ansible (0), and a real uv ansible repo before and
+after `uv sync` (0). The first draft failed FR-19 exactly as predicted (F-16).
+
+### M6 — docs — **done 2026-08-12**
+
+Done as described, and the sweep turned up drift that predates this work:
+
+- The `update` mechanism table still documented `uv tool upgrade` for `pip`/`uvx` (both columns).
+- `eza` was deleted from the catalog in a1a5126 (2026-07-01) but never from the README table **or
+  the CI matrix**, and `whichllm` was renamed to `llm-checker` in the same commit with the matrix
+  never updated. A matrix entry naming a tool that no longer exists makes pytest exit 4 — so those
+  two jobs have failed every weekly run since July, and the workflow's report step files a GitHub
+  issue about them each time.
+- Five real tools (`git-lfs`, `homebrew`, `ipython`, `llm-checker`, `lmstudio`) were missing from
+  the README tables, and four (`bat`, `homebrew`, `llm-checker`, `lmstudio`) from the CI matrix.
+
+All fixed, and `test_ci_matrix_covers_every_builtin_tool` now enforces the matrix half in both
+directions — verified to fail on a stale entry *and* on a missing one. The README half is left to
+manual review; its tables are prose-grouped and a parser would be more brittle than the drift it
+catches.
+
+## Testing strategy
+
+- **Unit** (`uv run pytest`, ~0.3s) — schema acceptance/rejection, `to_dict` round-trip, and the
+  argv built by `_install_uvx`/`_update_uvx`. The argv assertions are the ones that matter; they are
+  what would catch a regression back to a bare `uv tool install`.
+- **Integration** (`cd dev && make run-tests TOOL=ansible`) — real install in a throwaway container.
+  The assertion should be strengthened beyond `is_installed()`: **assert `ansible-playbook` resolves**,
+  not just `ansible`. F-1 is precisely a case where a weaker check passes on a broken install.
+- **Manual, once** — FR-14: run `uv run ansible-playbook --version` inside a uv-managed ansible repo
+  with the global tool installed, and confirm it still picks the project venv.
+
+## Risks
+
+| Risk | Mitigation |
+|---|---|
+| The integration test passes on a broken install because `is_installed()` only checks `ansible`. | Assert on `ansible-playbook` too. This is the exact shape of F-1 and the single most likely way this change ships broken. |
+| uv changes `--with-executables-from` semantics or spelling. | Pinned only by uv's CLI stability. The failure is loud (unknown flag), not silent. Acceptable. |
+| A user's existing catalog override for `ansible` keeps `type: apt`. | Catalog precedence means their override wins and they keep the old behaviour — correct, but worth a line in the README/changelog so it is not a mystery. |
+| ansible-core lands on an interpreter it does not support (OQ-2). | `uv_python` exists specifically to pin it; leave unset until observed. |
+| Removing the apt `remove_script` strands a previously apt-installed ansible. | Anyone who installed the old way has an apt ansible that `uv tool uninstall` will not remove. Mention in the changelog and in `devstuff docs ansible`; do not attempt an automatic migration — guessing at removing a system package is worse than saying so. |
+
+## Definition of done
+
+- `devstuff install ansible` puts all eleven executables on `PATH` from a uv-managed venv.
+- `uv run ansible-playbook` inside a uv ansible repo is unaffected.
+- `devstuff update commitizen --version 4.16.0` works (it currently cannot).
+- All three new fields are documented in the README schema table and validated on the wrong types.
+- Unit suite green. `make run-tests TOOL=ansible` **not yet run** — the containerised
+  clean-install path remains unexercised for `ansible`, `ansible-vault` and `python`.
+- This spec directory matches what was built.