# Tools Reference

This page documents host-side scripts under `tools/`. Use `make` targets when
available; call scripts directly for diagnostics or non-default arguments.

## Build And Packaging Tools

`tools/build_mutineer_basic.py`

- Purpose: tokenize standalone Atari BASIC modules from `source/text/` into
  `source/tokenized/`.
- Arguments: `--source-dir`, `--build-dir`.
- Used by: `make mutineer-basic`.

`tools/tokenize_atari_basic.py`

- Purpose: tokenize one Atari BASIC source.
- Arguments: optional source path, `-o/--output`.
- Used by: `tools/build_mutineer_basic.py`.

`tools/write_mms_version_inc.py`

- Purpose: increment `MMS_VERSION` patch and generate `mms/src/version.inc`.
- Used by MMS assembly targets.

`tools/build_mms_apps.py`

- Purpose: compile `source/config/MMSAPPS.CFG` into fixed-record
  `MMSAPPS.DAT`.
- Arguments: `--config`, `--output`, `--generation`.
- Output default: `source/stage/ATARI-MUTINEER/MMSAPPS.DAT`.

`tools/package_mutineer_atr.py`

- Purpose: stage the full BBS tree and create a versioned SDX ATR.
- Arguments: `--out`, `--no-version-bump`, `--size`, `--manual-start`,
  `--startup-name`.
- Env: `MUTINEER_MMS_COM` overrides the staged MMS binary.
- Outputs: `source/stage/ATARI-MUTINEER/` and `source/atr/atari-mutineer-v*.atr`.

`tools/package_door_game.py`

- Purpose: package a separate door game ATR from `source/doorgames/<GAME>/`.
- Arguments: optional `game` name, `--size`.
- Output: `source/atr/doors/atari-mutineer-door-<game>-v*.atr`.

`tools/extract_dos2_atr.py`

- Purpose: extract simple DOS 2.x single-density ATR contents.
- Arguments: ATR path and optional output directory.
- This is a utility for inspection, not the normal SDX packaging path.

`tools/versioning.py`

- Purpose: shared helpers for reading and incrementing `VERSION`.
- Used by package/build targets.

## Altirra And Emulator Tools

`tools/run_altirra_850.py`

- Purpose: launch Altirra under Wine with generated 850/modem profile.
- Env: `MUTINEER_ATR`, `MUTINEER_MODEM_PORT`, `MUTINEER_CONNECT_RATE`,
  `MUTINEER_TELNET`, `MUTINEER_TELNETLF`, `MUTINEER_USE_SDX`,
  `MUTINEER_CART`, `MUTINEER_CART_MAPPER`, `MUTINEER_EXTRA_DISK`,
  `MUTINEER_ALTIRRA_DEBUG_LOG`.
- Outputs: profile under `results/altirra-850/`, copied to
  `tools/altirra/4.40/Altirra.ini`.

`tools/run_atari800_rdevice_probe.py`

- Purpose: probe atari800 native network R: behavior.
- Env: `SDX_CART`, `BASIC_PARSER`.
- This is not the default Mutineer acceptance path.

## Probe And Acceptance Tools

`tools/package_mms_hatabs_probe_atr.py`

- Purpose: build tiny SDX ATRs for focused MMS HATABS probes.
- Argument: `--mode` with `api`, `mixed`, `input`, `sysop`, `donly`,
  `dmodem`, `dstep`, or `full`.
- Env: `MMS_PROBE_DIAL_HOST`, `MMS_PROBE_DIAL_PORT`,
  `MMS_PROBE_BASIC_COMMAND`, `MMS_PROBE_ECHO_BOOT`, `MUTINEER_MODEM_PORT`,
  `MUTINEER_MMS_COM`.
- Outputs: `source/atr/mms-hatabs-probe-<mode>.atr`.

`tools/run_mms_hatabs_probe.py`

- Purpose: run a probe ATR under Altirra and capture host telnet output.
- Argument: `--mode` with the same choices as the package tool.
- Env: `MMS_HATABS_PROBE_MODE`, `MUTINEER_MODEM_PORT`,
  `MMS_HATABS_PROBE_TIMEOUT`, `MMS_HATABS_PROBE_CONNECT_DELAY`,
  `MMS_HATABS_PROBE_CONNECT_MODE`, `MUTINEER_MMS_COM`,
  `MUTINEER_ALTIRRA_DEBUG`.
- Outputs: `results/mms-hatabs-probe/<mode>/<timestamp>/`.

`tools/run_mutineer_telnet_test.py`

- Purpose: run scripted telnet coverage through Altirra's modem listener.
- Env: `MUTINEER_MODEM_PORT`, `MUTINEER_TEST_TIMEOUT`,
  `MUTINEER_CONNECT_DELAY`, `MUTINEER_SEND_DELAY`,
  `MUTINEER_TEST_SCENARIO`, `MUTINEER_LINE_ENDING`, `MUTINEER_CLIENT`,
  `MUTINEER_ATR`, `MUTINEER_USE_SDX`, `MUTINEER_CART`,
  `MUTINEER_CART_MAPPER`, `MUTINEER_EXTRA_DISK`, `MUTINEER_TELNETLF`,
  `MUTINEER_ALTIRRA_DEBUG`, `MUTINEER_MMS_COM`.
- Outputs: `results/mutineer-telnet/<timestamp>/`.

`tools/run_mutineer_xmodem_test.py`

- Purpose: run scripted XMODEM upload/download coverage through Altirra.
- Env: `MUTINEER_MODEM_PORT`, `MUTINEER_XMODEM_TIMEOUT`,
  `MUTINEER_CONNECT_DELAY`, `MUTINEER_ATR`, `MUTINEER_ALTIRRA_DEBUG`.
- Outputs: `results/mutineer-xmodem/<timestamp>/`.

`tools/run_mutineer_regression_test.py`

- Purpose: verify normalized transcript markers from a telnet test run.
- Arguments: `--run-dir`, `--out`, `--markers`.
- Output default: `build/mutineer-regression.json`.

`tools/mutineer_evidence.py`

- Purpose: collect acceptance outputs into one evidence manifest.
- Argument: `--out`.
- Output default: `results/mutineer-evidence.json`.

## Inspection And Audit Tools

`tools/inspect_mutineer_atr.py`

- Purpose: inspect packaged ATR contents and emit acceptance evidence.
- Arguments: `--atr`, `--out`.
- Output default: `build/mutineer-atr-manifest.json`.

`tools/mms_abi_check.py`

- Purpose: compare assembled MMS listings against expected public ABI and
  HATABS resident-size limits.
- Arguments: `--listing`, `--hatabs-listing`, `--basic`, `--out`.
- Output default: `build/mms-abi.json`.

`tools/docs_audit.py`

- Purpose: check required docs pages, local Markdown links, documented Make
  target names, and documented `tools/*.py` references.
- Used by: `make docs-audit`.