chemenu/instructions/preflight.md

type, name, description

type	name	description
types/instruction.md	preflight	Run the preflight before any wikitool command in a new, cloned, moved or updated checkout - it checks Python, git and ripgrep, records their paths in .wikitool-tools.json and sets up tools/.venv; on exit 42 show its output verbatim and wait for the user, never install or work around anything yourself.

Check the machine before anything else runs

tools/wikitool does not start in a checkout the preflight has not passed in. It stops with exit 42 and names this procedure instead - so there is no skipping it, only running it early or being sent back to it.

The preflight is a shell script, not a wikitool command, because it has to work before Python is known to exist. It does three things, all inside the install folder:

• checks the tools listed in tools/prerequisites.txt - Python 3.11 or newer, git, ripgrep (rg) - and, on Windows, that the install folder is short enough for Windows' path limit;
• records the absolute path of each tool in .wikitool-tools.json, which wikitool then starts them from instead of trusting whatever PATH a session inherited;
• creates tools/.venv from the recorded Python and installs tools/requirements.txt into it.

When to run

• First step of every installation procedure: setup-instance.md and bootstrap.md both start here.
• After every stack update (upgrade-instance.md) - a release can change what the machine needs, or the requirements the venv holds.
• Whenever tools/wikitool exits 42 and names the preflight, and whenever tools/wikitool doctor reports tool-paths or install-dir as FAIL.

It is safe to run at any time: a second run on a ready checkout changes nothing and exits 0.

Steps

1. Run it from the root of the checkout:

   tools/preflight.sh
   

   This covers Linux, macOS and Git Bash on Windows, which is where Claude Code runs its commands there.

2. Read the exit code.

   Exit	Meaning	What you do
   0	Everything is in place	Continue with the procedure that sent you here
   42	The user has to act	Step 3
   1	Called wrongly, or tools/prerequisites.txt is missing next to the script	Report the exact command and output to the user; do not retry blindly

3. On exit 42, show the output to the user exactly as it is, then stop and wait. It is written for someone without an IT background: each numbered block says what is missing, why it matters, the command that fixes it, and what happens next. When the user's language is not the language of the output, add a translation below it - never instead of it, since the commands inside have to reach them unchanged.

   While you wait, install nothing, and work around nothing - not with the user's consent either. No package manager call, no other Python, no WSL, no hand-written .wikitool-tools.json, no wikitool command "to see whether it works anyway". The command in the output is for the user to run; how their machine is administered is theirs to decide.

4. When the user says it is done, run the preflight again. Repeat steps 2-4 until it exits 0.

   When the user tells you where a tool is installed instead, pass the path on:

   tools/preflight.sh --set rg=/opt/ripgrep/rg
   

   --set <tool>=<path> may be given several times. A path that does not work is refused with exit 42 and nothing is written; a working one is recorded and kept on later runs, even though the tool is still not on PATH.

Decision points

• The output names a folder that is too long. Only on Windows with long paths off: the install folder may be at most 95 characters, because every file of the wiki below it has to stay within 259. Moving the wiki to a shorter folder is the user's step; do not try to shorten paths inside the wiki instead.
• The venv or its libraries could not be installed. The output carries the last lines of what Python or pip said. A network, proxy or security-product cause is for the user - or whoever administers their machine - to resolve; do not retry with other flags.
• .wikitool-tools.json looks wrong. Never edit it. Run the preflight again, with --set for a path the user names; doctor reports whether the result holds.

Scope

Not a wiki content procedure - it touches nothing under kb/, raw/, work/ or reports/. It does not configure identity, remotes or the harness either; those are later steps of setup-instance.md.