personal-os-setup: Skill for Claude Code

Adding a system action or package manager backend

This repo's TUI is entirely data-driven from src/personal_os_setup/tasks/factory.py::get_system_action_sections(). Never wire a button directly in frontend/app.py — add it to a section builder in factory.py instead. The frontend renders whatever sections/actions the factory returns generically (one TabPane per section, one Button per action), except for two special-cased sections it knows by name: "Sync dotfiles" (renders the chezmoi tree/toolbar) and "🚀 Start" (renders the onboarding markdown before the doc-link buttons).

For anything involving the chezmoi source tree itself (config/chezmoi/) — adding a run_* script, or explaining why a synced file's companion script didn't fire — see [[chezmoi-scripts]] first; the dotfiles tree's targeted-apply scoping is easy to get wrong.

⚠️ Every SystemAction.run you write or edit here is a real system-mutating command (installs a package, edits/overwrites a config file, changes the default shell, touches drivers, etc.) once a user clicks it in the running app. That's expected — it's the app's whole purpose — but when you (as the coding agent) are implementing/testing one of these, never invoke it against the real host yourself to "check it works." Read the code, run it through the unit-test mocks (see [[run-tests]]), and if you genuinely need to exercise the real command, confirm the exact command with the user first. See CLAUDE.md § "Safety: always confirm before system-mutating actions".

Adding a new action to an existing section

1. Find the right per-domain builder function in factory.py (e.g. _dotfiles_section, _system_section, _wsl_section) — sections are independently unit-tested in tests/unit/test_factory.py, one test class per section.
2. Append a SystemAction(...) to that builder's returned list. Fields available: label (button text), run: Callable[[], TaskResult], run_with_prompt/prompt_label/prompt_initial (for free-text input actions), confirm/confirm_message (for destructive actions), backup_target: Path | None (file gets copied with a timestamp suffix before run executes), group: str | None (adjacent actions sharing a group render on one row).
3. The actual logic (run callable) lives in tasks/system/<domain>.py, not in factory.py — factory.py only assembles SystemActions and returns TaskResults from imported functions.
4. Add/extend a test in tests/unit/test_factory.py using the existing _actions_in(system, distro, section_name) / _action_in(...) helpers — these call get_system_action_sections directly, no App instantiation needed.