[HaoZeke]

CLI reference synopsis

What and why

docs/orgmode/reference/cli.org described every stack oom flag in prose.
The usage block in the stack-command synopsis stopped at --job-memory and did not name --hooks, --parallel, --max-parallel, or the --mib-per-job alias.
The stack oom section had a worked example and no usage block.

Outside the stack oom section, the command map listed stack gap twice, once as a classification and once as a per-route tab-separated values (TSV) file.
campaign finding claim and campaign finding resolve shared one campaign finding ... row.

stack oom now has one usage block, in the stack synopsis and at the start of its section.
The command map has one stack gap row, and each campaign finding subcommand has its own row.
llms-full.txt follows the Org manual, and tests/cli_reference.rs locks the map and the usage block.

Before

eb-stack stack oom \
  (--easystack EASYSTACK.yml... | --node CORES:MEMORY_MIB[:TARGET]...) \
  [--arch x86_64/amd/zen4]... \
  [--easyconfigs TREE]... \
  [--installed INSTALLED.txt] \
  [--profile BUILD-MEMORY.toml] \
  [--resources BOT-RESOURCES.toml] \
  [--job-memory JOB-MEMORY.toml]

| stack gap | Classify site modules the stack lacks and name the recipe that closes each |
| stack gap | Route each site module the stack lacks, and write one TSV per route |
| campaign finding ... | Claim and resolve typed build findings |

After

eb-stack stack oom \
  [--arch x86_64/amd/zen4]... \
  [--easystack EASYSTACK.yml]... \
  [--easyconfigs TREE]... \
  [--installed INSTALLED.txt] \
  [--profile BUILD-MEMORY.toml] \
  [--resources BOT-RESOURCES.toml] \
  [--node CORES:MEMORY_MIB[:TARGET]]... \
  [--job-memory JOB-MEMORY.toml | --mib-per-job JOB-MEMORY.toml] \
  [--hooks eb_hooks.py] \
  [--parallel N] \
  [--max-parallel N]

| stack gap | Route each site module the stack lacks, name the recipe that closes it, and write one TSV per route |
| campaign finding claim | Claim an open finding for one worker |
| campaign finding resolve | Resolve a claimed finding with an action, evidence, and the paths it changed |

The documented stack oom example keeps its output.
The binary prints the libxc warning and oom=1 fits=1 builds=5 nodes=2, and exits 0:

libxc-7.0.0-GCC-15.2.0.eb may run out of memory on x86_64/amd/zen4 (eessi-bot-mc-aws amd-zen4): 8 x 6.4 GiB = 51.2 GiB, the job has 32.0 GiB (software-layer #1772, software-layer-scripts #337)
oom=1 fits=1 builds=5 nodes=2

Tests

• Formatting: cargo +stable fmt --all --check exited 0.
• Lints: cargo +stable clippy --locked --all-targets -- -D warnings exited 0.
• Full suite: cargo +stable test --locked --all-targets exited 0, with 93 suites, 1504 passed, 0 failed, 10 ignored.
• Packaging: cargo +stable package --locked exited 0.
• Hooks: uvx prek run -a exited 0.
• Documentation: pixi run -e docs mkrst, scripts/gen-rust-api.sh, scripts/sphinx-build-docs.sh, and scripts/check-doc-links.sh exited 0, and lychee 0.24.2 reported 0 errors.
• Generated text: python3 scripts/gen-llms-txt.py --check exited 0.

Repro

cargo +stable test --locked --test cli_reference -- --exact the_command_map_and_oom_synopsis_match_the_cli
cargo +stable build --locked
./target/debug/eb-stack stack oom \
  --arch x86_64/amd/zen4 \
  --easystack tests/oom_profile_fixtures/easystacks/pr1772-eessi-2026.06-eb-5.4.0-2026.1.yml

---

Note

Medium Risk
Medium risk from changes to dependency-order graph walking (--installed leaves) and arch source-probe classification; fetch script pagination affects pr-overlap inputs but is read-only against GitHub.

Overview
Adds stack order --installed (and eb_stack_order installed) so build orders treat site modules as leaves: listed modules and their already-installed dependency subtrees are omitted, --filter-deps still runs first, stdout reports installed=N, and ordering uses the same GCC-family hierarchy as before. Core logic lives in new build_order_against_installed / graph helpers in build_order.rs, wired through workflows::stack_order and module inventory parsing shared with stack gap.

Both examples/*/fetch-prs.sh scripts now page open PRs and changed files 100 at a time (no implicit stop at 500 open PRs), handle GitHub’s 3000-file cap by keeping the PR JSON with file_list_truncated, and add regression tests for >500 PRs and capped file lists.

stack arch --probe-sources with two --arch flags compares only those families when classifying sources as arch-missing vs unreachable. Documentation and tests cover the two-arch case; llms-full.txt, README, and CHANGELOG are updated alongside.

CLI/MCP reference work: deduplicated stack gap in the command map, split campaign finding claim / resolve rows, added a full stack oom usage synopsis (including --hooks, --parallel, --mib-per-job), expanded mcp.org with a 51-tool command↔tool table, and added tests that mcp.org and tools/list stay aligned.

^{Reviewed by Cursor Bugbot for commit 114a869. Bugbot is set up for automated code reviews on this repo. Configure here.}