feat: consume the project's symbol map

.gitignore

@@ -18,6 +18,11 @@ apps/benchmark/results/*.log
 apps/benchmark/results/*.part*.json
 # CI-fetched toolchains + pinned m2c (.github/workflows/benchmark.yml)
 .deps/
+# bench-owned toolchains fetched by `pnpm bench setup` (gcc 2.7.2 + binutils 2.6 releases)
+apps/benchmark/toolchains/
+# bench-owned project checkouts materialized by `pnpm bench setup` (disposable clones the
+# harness may build in — the sibling WORKSPACE checkouts stay untouched)
+apps/benchmark/checkouts/
 # per-tier intermediates regenerated by every `bench run` (results.json stays committed)
 apps/benchmark/results/synthetic.json
 apps/benchmark/results/real.json

README.md

@@ -68,6 +68,12 @@ tools:
     # Possible values: agbcc, ido7.1, gcc2.7.2kmc, mwcc_242_81
     target: agbcc
 
+    # Optional. The project's built ELF. asmlift reads its symbol table and debug info to
+    # name the globals and struct fields the assembly only addresses, recover callee
+    # signatures, and adopt the project's address-cast macro names. How to produce a good
+    # one is covered in the CLI documentation linked below.
+    elf: rom.elf
+
     # Optional. Used only for the `--score-against`
     compiler: |
       arm-none-eabi-cpp -nostdinc -I tools/agbcc/include {{inputPath}} -o {{outputPath}}.i

apps/benchmark/README.md

@@ -128,9 +128,37 @@ key derivation is in `src/cache.ts`; the m2c side fails closed on a dirty m2c ch
 
 Harness path defaults live in `src/config.ts`, following the sibling-checkout WORKSPACE
 convention: `ASMLIFT_M2C_DIR` overrides the m2c checkout; `ASMLIFT_CPP` names the GNU cpp used
-for real-tier preprocessing (Apple's `/usr/bin/cpp` ignores `-o`). Real-tier manifests carry NO machine paths — each project resolves as
-`WORKSPACE/<repoDir>`, overridable per project via `ASMLIFT_PROJ_<PROJECT>`; projects missing on
-this machine are skipped with one aggregated warning.
+for real-tier preprocessing (Apple's `/usr/bin/cpp` ignores `-o`). Real-tier manifests carry NO
+machine paths — each project's checkout resolves in order: `ASMLIFT_PROJ_<PROJECT>` env override
+
+> bench-owned checkout (`apps/benchmark/checkouts/<repoDir>`, materialized by `pnpm bench
+setup`) > sibling `WORKSPACE/<repoDir>`; projects missing on this machine are skipped with one
+> aggregated warning.
+
+### Bench-owned checkouts (`pnpm bench setup [--build]`)
+
+`bench setup` materializes a HARNESS-OWNED workspace under the gitignored
+`apps/benchmark/checkouts/`: every real-tier fork is cloned at its pinned branch (submodules
+included; ssh submodule URLs are rewritten to https), baseroms are copied in from the sibling
+user checkout when present, and each project's preparation recipe runs
+(`src/cases/project-setup.ts`: agbcc builds, venvs, splat splits, generated sources).
+`--build` then runs every project's full build through its own byte-compare gate (plus its
+`elfMake` symbol-ELF target). These clones are disposable and freely mutated by the harness;
+NON-bench-owned checkouts (env override or sibling WORKSPACE) are only ever reported — setup
+never mutates them.
+
+Host prerequisites (macOS; verified empirically):
+
+- Xcode CLT (`/usr/bin/cc` — host tools build with `/usr/bin` ahead of homebrew, several
+  projects' host tools miscompile under homebrew gcc), plus homebrew `gmake`, `wget`, `libpng`
+- an `arm-none-eabi` toolchain on PATH (GBA projects: pokeemerald, sa3, kleod)
+- python >= 3.11 first on PATH for kleod's `setup.sh`; any python3 for the others
+- big-endian `mips-linux-gnu` binutils under `/opt/cross` (af), and Rosetta
+  (`softwareupdate --install-rosetta` — af's IDO recomp and marioparty3's KMC gcc are x86_64)
+- Docker (snowboardkids2 builds inside a linux/amd64 container; the `asmlift-elf` DWARF
+  sidecar targets also fall back to Docker when no host `mips-linux-gnu-gcc` exists)
+- baseroms: setup copies them from the sibling user checkouts when found; otherwise place them
+  manually (the status table names the missing file and destination)
 
 ## Harness layout (`src/`)