Toolkit setup runbook

The rule

You change the user's machine only as far as the user's task says. Look first; report; wait. A missing or broken runtime is a thing to tell the user about, not a thing to fix on your own. If the task does not say, in so many words, that you may install a named runtime at an exact version, you do not install anything.

Steps

1. Read the authorization. The task's first paragraph contains one sentence starting Host-software installs:. NOT AUTHORIZED (or no such sentence) means no installs at all. Otherwise it lists items of the form python=<winget id>==<exact version> (runtime python, git or node, then =, the id, == and the version, with no spaces; items are separated by commas). Only these winget ids are ever accepted: Python.Python.3.<minor> for python (3.10 or newer, and the version must be that minor's), Git.Git for git, and OpenJS.NodeJS or OpenJS.NodeJS.LTS for node. Any other id authorizes nothing. Anything else, a JDK, .NET or Blender included, is never covered: give the user manual steps.
2. Inventory by launching. If any Python is available, run python tools/inventory-runtimes.py inventory (here and below, python means whichever of py -3, python or python3 starts; on Linux and macOS it is usually python3). It finds every candidate on PATH and runs each with --version only. If no Python runs at all, do the same by hand: py -3 --version, python --version, python3 --version, git --version, node --version, and look at the output, not at whether the command was found. A Windows Store alias answers with a Store message, not a version: that is not an installed Python.
3. Plan. Save the user's whole task message, unchanged, to a temporary file outside the toolkit folder, and run python tools/inventory-runtimes.py plan --auth-file <that file>. Never pass a sentence you picked out of it: a denial anywhere in the user's text must be able to void an authorization, and the tool can only see that if it reads all of it. Delete the file afterwards. For each runtime the plan gives one action:
   • none: nothing to do.
   • report: it is there but too old, broken or hung. Do not upgrade, repair, reinstall or remove it. Tell the user what you found and the manual steps printed, then stop and wait.
   • manual: it is missing and you are not authorized. Print the manual steps for the user and wait.
   • install-authorized: it is missing, the user authorized exactly this id and version, and the command below is printed. Run only a command the plan printed, unchanged.
4. Verify by launching again after any install the user or you performed. If the new runtime is not on PATH yet, say so and ask the user to open a new terminal; do not retry installs.
5. Then run bash setup.sh (Windows: from Git Bash). Never pass it a flag that installs software.

House Carl is a separate optional install, not part of core setup. For an authorized integration, follow docs/housecarl.md and skill toolkit-housecarl; identify the load-order authority separately from deployment, then use its explicit setup command. Missing .NET prerequisites remain manual steps.

What an install command looks like

winget install --id <Id> --exact --version <V> --no-upgrade --accept-package-agreements --accept-source-agreements

<Id> and <V> come from the user's authorization, never from your memory. Only Windows with winget present is covered; on any other system the answer is always manual.

Never

• Never run a package manager's upgrade, repair, reinstall or uninstall for a runtime, and never use a force, no-confirm or "latest" form.
• Never download and run an installer you were not given, and never pipe a download into a shell.
• Never install a runtime to make a failing check pass; say what failed.
• Never edit the user's PATH, environment variables or registry.

Why Git matters

The toolkit's hooks run under Git Bash on Windows, and a hook that cannot start lets some agents run the command anyway. A missing Git is therefore a safety gap, not a convenience: tell the user.