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 script, not a wikitool command, because it has to work before Python is known to exist: tools/preflight.sh for POSIX shells, tools/preflight.ps1 for PowerShell 7 on Windows. The two answer the same questions from the same list and write the same .wikitool-tools.json. 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 and (PowerShell only) that the execution policy and the files' Mark of the Web let tools/wikitool.ps1 start;
• 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.

Contents

• When to run
• Steps
• Decision points
• Scope

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, install-dir, execution-policy or script-marks 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, with the script for the shell the session runs in:

   tools/preflight.sh
   

   This covers Linux, macOS and Git Bash on Windows, which is where Claude Code runs its commands there. From PowerShell 7 on Windows (GitHub Copilot CLI, for one) use the twin, and always with exactly this prefix:

   pwsh -NoProfile -ExecutionPolicy Bypass -File tools/preflight.ps1
   

   The bypass holds for that one process only and changes no setting; it is what lets the script run at all when the checkout carries a Mark of the Web, so that it can report that itself. Windows PowerShell 5.1 is not supported.

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
   

   pwsh -NoProfile -ExecutionPolicy Bypass -File tools/preflight.ps1 --set rg=C:\Tools\rg\rg.exe
   

   --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 output names the PowerShell execution policy (Restricted or AllSigned). The fix is a line the user runs in a PowerShell 7 window; it changes a setting of their account, so it is theirs to run. When a group policy sets it, nothing on this computer can override it: the output says to ask whoever administers the machine - or to use tools/wikitool from Git Bash instead. Do not suggest a workaround that evades the policy.
• The output names scripts with a Mark of the Web. The checkout was downloaded with a browser and unpacked in Explorer, so Windows marks every file as coming from the internet. The command in the output (Unblock-File over the folder) is the user's to run; a download by Invoke-WebRequest, git clone or tar carries no mark.
• 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.