docs: short README and docs sorted into folders

.github/ISSUE_TEMPLATE/help-wanted.md

@@ -14,5 +14,5 @@ assignees: ''
 
 **Your setup**
 
-- Disc: USA v1.01 (`SCUS_972.68`), SHA-256 matching docs/BUILDING.md? 
+- Disc: USA v1.01 (`SCUS_972.68`), SHA-256 matching docs/build/building.md? 
 - Host: (macOS / Linux / Windows + WSL), Docker or native

.github/pull_request_template.md

@@ -5,4 +5,4 @@
 ## Checked
 
 <!-- The commands you ran and what they printed, e.g. `tools/build.py all`: 28 programs OK;
-how many functions this adds (leave `progress/report.json` and the README table out: they are regenerated on master). Say what you did not run. -->
+how many functions this adds (leave `progress/report.json` out: it is regenerated on master). Say what you did not run. -->

.github/workflows/progress.yml

@@ -1,5 +1,5 @@
 # ByteMatch progress reports (https://bytematch.dev/OpenRAC/rac2-decomp), as rac1-decomp
-# publishes its own. One per release (docs/VERSIONS.md):
+# publishes its own. One per release (docs/build/versions.md):
 #
 #   SCUS_972.68     USA v1.01 (the primary target)  progress/report.json      -> SCUS_972.68_report
 #   SCES_516.07     Europe/Australia v1.00          progress/pal/report.json  -> SCES_516.07_report

.gitignore

@@ -4,6 +4,7 @@
 .venv/
 reference/
 assets/
+!docs/assets/
 asm/
 asm_pp/
 build/

AGENTS.md

@@ -1,8 +1,8 @@
 # Instructions for agents
 
 This file is for AI agents (Claude, Codex, Qwen or others) working in this repository. Read it
-completely before changing anything; then read README.md, CONTRIBUTING.md, docs/BUILDING.md and
-docs/LEVELS.md. The repository follows the same structure as rac1-decomp and the other OpenRAC
+completely before changing anything; then read README.md, CONTRIBUTING.md, docs/build/building.md and
+docs/build/levels.md. The repository follows the same structure as rac1-decomp and the other OpenRAC
 decompilations: keep it that way.
 
 Also read `CLAUDE.md` and `.claude/CLAUDE.md` when present, and follow their applicable
@@ -24,7 +24,7 @@ equals the retail programs.
 | `config/cflags.txt` | compiler flags per file | by hand, when a whole file needs other flags |
 | `include/` | headers shared with rac1-decomp | by hand |
 | `nonmatching/` | near misses, never linked | you |
-| `progress/report.json`, the README table | progress | `tools/progress.py` only, on `master` by a maintainer |
+| `progress/report.json` | progress | `tools/progress.py` only, on `master` by a maintainer |
 | `tools/` | disc reader, build, check, progress, compiler recipes | by hand, with tests |
 | `docs/` | how to build, the level format, the compiler, game research | by hand |
 | `baserom/`, `build/`, `toolchain/`, `work/` | game data, build output, proprietary tools, scratch | never committed |
@@ -111,13 +111,13 @@ attempt; OpenRAC's `docs/port/BACKFILL.md` has the measurements and the full pro
 - **Out of budget.** About ten compiles without getting closer.
 
 Then stop: put the marker back, leave the attempt in `nonmatching/<area>/` with what differs and
-what would unblock it, and let it go up one model tier (docs/AGENT_WORKFLOW.md). Stopping is a
+what would unblock it, and let it go up one model tier (docs/agents/agent-workflow.md). Stopping is a
 normal result. C that behaves like the function without matching it is useful to the native port,
 never to `src/` or the progress report.
 
 ## Shared blocker knowledge
 
-[`docs/MATCHING-BLOCKERS.md`](docs/MATCHING-BLOCKERS.md) is the shared reference for
+[`docs/contributing/matching-blockers.md`](docs/contributing/matching-blockers.md) is the shared reference for
 blockers, measured attempts and verified remedies. **Every contributor may edit any
 entry through a normal fork/topic branch and pull request**, including entries originally
 written by someone else. Maintainers review merges; they do not own all knowledge edits.
@@ -129,7 +129,7 @@ read the relevant entry and retained source, and check cited fixes against curre
 `origin/master`. Do not repeat recorded attempts without a new hypothesis or changed input.
 
 When you find a blocker, useful evidence or a solution, update the existing entry in
-`docs/MATCHING-BLOCKERS.md` in your branch and include it in the relevant PR. Keep it concise:
+`docs/contributing/matching-blockers.md` in your branch and include it in the relevant PR. Keep it concise:
 
 - Identify the target/family, release, compiler/assembler profile and placement coverage.
 - Record the hypothesis, measured result, remaining difference and next useful experiment.
@@ -161,7 +161,7 @@ side by side instead of one after another:
 - Start long steps in the background and keep working; do not sit on a build.
 
 The exception: never run two builds of the same program in the same checkout at once. Workers
-each have their own worktree for that reason (docs/AGENT_WORKFLOW.md).
+each have their own worktree for that reason (docs/agents/agent-workflow.md).
 
 ## Rules
 
@@ -207,7 +207,7 @@ each have their own worktree for that reason (docs/AGENT_WORKFLOW.md).
   permitted when the EE ABI preserves each register bank's argument order, count and
   widths, stack arguments, return contract and side effects. Do not invent accesses or
   change the callee's physical interface to influence allocation. See
-  [the examples and limits](docs/COMPILER-NOTES.md#source-methods-shared-with-rac1).
+  [the examples and limits](docs/build/compiler-notes.md#source-methods-shared-with-rac1).
 - **English.** Everything that lands here is in English: code, comments, commit messages,
   issues, pull requests, reviews, and the notes kept in `nonmatching/`. Translate before it is
   published.
@@ -268,22 +268,22 @@ work in. It was removed on purpose. Do not recreate any of it:
   for an isolated fix, an independent change that needs separate review, or the final
   remainder of a batch. Do not combine unrelated work or delay a necessary fix just
   to reach five. Every batch must still pass the required checks before publication.
-- Leave `progress/report.json` and the README table out of your commits (see "The progress
+- Leave `progress/report.json` out of your commits (see "The progress
   report").
 
 ## The progress report
 
-`progress/report.json` and the README table are generated, and every pull request that
-regenerates them conflicts with every other one. So pull requests do not touch them:
+`progress/report.json` is generated, and every pull request that regenerates it conflicts
+with every other one. So pull requests do not touch it:
 
 - In a pull request, say what `tools/build.py all` printed and how many functions you added.
   `tools/progress.py --check` passes with the report behind; it only fails if the report counts
   something that is no longer C.
 - After merging, a maintainer runs `tools/build.py all` and `tools/progress.py` on `master` and
-  commits the two files alone (`chore(progress): N of 9,101 functions`). Several merged pull
+  commits it alone (`chore(progress): N of 9,101 functions`). Several merged pull
   requests can share one regeneration.
-- If your branch already has the two files changed, restore them before pushing:
-  `git checkout origin/master -- progress/report.json README.md`.
+- If your branch already has it changed, restore it before pushing:
+  `git checkout origin/master -- progress/report.json`.
 
 ## Pushing changes
 
@@ -306,7 +306,7 @@ reservation files.
 
 ## Which model does what
 
-docs/AGENT_WORKFLOW.md is the whole procedure. In short, sort by size with `python3 tools/todo.py`:
+docs/agents/agent-workflow.md is the whole procedure. In short, sort by size with `python3 tools/todo.py`:
 
 - **Haiku 5.5**: small functions, up to 400 bytes, many workers at once.
 - **Sonnet 5.5**: 401 to 1,000 bytes, and what Haiku gave up on.

CONTRIBUTING.md

@@ -2,7 +2,7 @@
 
 ## Matching a function
 
-1. Set up the build once ([docs/BUILDING.md](docs/BUILDING.md)) and run `tools/build.py all`.
+1. Set up the build once ([docs/build/building.md](docs/build/building.md)) and run `tools/build.py all`.
 2. Pick a function from `config/boot/functions.tsv` or `config/levels/functions.tsv`. A level
    function's row lists all its places; one definition serves them all.
 3. Find its `INCLUDE_ASM` line in `src/` (`grep -rn func_XXXXXXXX src`) and replace it with
@@ -15,14 +15,43 @@
 5. `tools/build.py` the programs that have it (`boot`, `level 4`, or `all`). It places the
    function everywhere the catalogue says and prints `OK` per program, or why a place does
    not match. A function counts once its C links into a program that equals the retail one.
-6. Leave `progress/report.json` and the README table alone: a maintainer regenerates them on
+6. Leave `progress/report.json` alone: a maintainer regenerates it on
    `master` after merging, so pull requests do not conflict on them (AGENTS.md, "The progress report").
 
 Close but not matching: put it in `nonmatching/` with a line in its README.
 
+## Tracking
+
+- **Reservations.** Before you start, reserve the functions, files or levels you will work on
+  in [issue #152](https://github.com/OpenRAC/rac2-decomp/issues/152): one comment per
+  contributor, edited in place, at most 500 unfinished functions. Read the other comments
+  first and do not overlap them. Release what you finish or drop. [AGENTS.md](AGENTS.md) has
+  the exact rules.
+- **What is left.** `python3 tools/todo.py` lists the functions still to match by size
+  (`--min`, `--max`, `--kind boot|shared|level`, `--limit`). Before you start one, look for it
+  in [`nonmatching/README.md`](nonmatching/README.md): an earlier near miss and its notes may
+  be there.
+- **Near misses.** C that does not match goes into `nonmatching/` with a row in its README,
+  and the function keeps its `INCLUDE_ASM` marker in `src/`.
+- **The progress report.** `progress/report.json` is generated. Only a
+  maintainer refreshes it, on `master`, after merging. Leave it out of your pull request;
+  if you ran `tools/progress.py`, undo it with
+  `git checkout origin/master -- progress/report.json`.
+  `python3 tools/progress.py --check` passes while the report is behind and prints how many
+  new functions wait for the refresh.
+- **Before a pull request**, all must pass:
+  ```sh
+  python3 tools/build.py all --strict          # and with --version pal, --version us2
+  python3 -m unittest discover -s tests
+  python3 tests/check_repository.py
+  python3 tools/progress.py --check
+  ```
+  A function that matches in v1.01 but not in another release stays assembly there:
+  `tools/carry.py --version pal --demote` ([`docs/build/versions.md`](docs/build/versions.md)).
+
 ## Improving shared knowledge
 
-Every contributor can edit any entry in [`docs/MATCHING-BLOCKERS.md`](docs/MATCHING-BLOCKERS.md)
+Every contributor can edit any entry in [`docs/contributing/matching-blockers.md`](docs/contributing/matching-blockers.md)
 using a fork/topic branch and a normal PR, even when another person wrote the original note.
 Maintainers review the merge; they are not the sole authors. A coding AI edits this Markdown
 file in the same checkout, with no separate wiki clone or browser automation.
@@ -38,7 +67,7 @@ issue #157 is retired and kept only as historical provenance. Reservations stay
 Branch from `master`, commit, push the branch and open a pull request to `master`. In the pull
 request, give the commands you ran and what they printed (`tools/build.py all --strict`,
 `tools/progress.py`, the tests). CI runs the tests and the repository check; a maintainer merges.
-Never push to `master` and never force-push a shared branch. AGENTS.md has the full rules and docs/AGENT_WORKFLOW.md says which model takes which functions, for
+Never push to `master` and never force-push a shared branch. AGENTS.md has the full rules and docs/agents/agent-workflow.md says which model takes which functions, for
 people as much as for agents.
 
 Use `--strict` for the final build before pushing: it fails if any C function falls back