---
type: types/instruction.md
name: preflight
description: 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](setup-instance.md) and
  [bootstrap.md](bootstrap.md) both start here.
- After every stack update ([upgrade-instance.md](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:

   ```bash
   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:

   ```bash
   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](setup-instance.md).