docs(agents): tooling + architecture-upkeep rules, with tool tests (#24)

Merged PR #24: tooling + architecture-upkeep rules, tool tests

Co-authored-by: Zwitschi <zwitschi82@gmail.com>

AGENTS.md

@@ -110,6 +110,59 @@ Keep entries short and dated, with the evidence: the command, the log line, or t
 
 Memory edits on an agent's branch are not shared live. Communicate important findings to the coordinator during work and reconcile them into the shared `main` copy when integrating.
 
+## Python and shell tooling
+
+Every committed asset and every measured claim in this repository is produced by a script. Tools live in `Tools/` (Unreal, network, repository), `Geo/tools/` (projection, OSM/DEM parsing, metadata) and `Art/blender/*/` (Blender-side builders, next to their output).
+
+**Fix the tool, not the artefact.** If an asset is corrected by hand, script the correction (or regenerate it) in the same change. A second manual fix of the same kind means the tool is missing a step.
+
+**Improve over fork.** Extend the existing tool rather than adding a near-duplicate. When two or three scripts start sharing logic, factor the shared part into `Tools/_common.py`, `Geo/tools/osm_common.py` or `Art/blender/common.py`; keep the single metres→centimetres conversion where it already lives.
+
+Rules that keep tools reusable and reviewable:
+
+- **One script, one job.** Every input is an argument; no interactive prompts; deterministic output paths.
+- **Fail loudly.** A tool that cannot do its job exits non-zero with a message. Never leave a partially written asset and a success code.
+- **Result files for Unreal.** Unreal commandlets swallow `print()`; write the outcome to `/tmp/gigline/<tool>.txt` and read that instead of trusting the exit code alone.
+- **Absolute paths into sandboxes.** Blender Flatpak (`LD_LIBRARY_PATH="$B/blender/lib"`) and Unreal do not share the repo's working directory; pass absolute paths.
+- **Clean worktree for generators.** Tools that rewrite committed assets (site/street/hero builders, importers, map builders) run from a clean worktree; inspect the LFS diff before committing. Note that `.blend` and `.umap` check out read-only — `chmod u+w` first or the save silently fails.
+- **Network and paid-API tools are human-triggered.** `Tools/commons_fetch.py`, `Tools/page_image_fetch.py`, `Tools/judge_screenshot.py` (OpenRouter) and anything similar never sit in a gate or CI. Handle HTTP 429 with back-off rather than retrying immediately.
+- **Measure, don't assert.** Verification tools print the sampled numbers — counts, holes, Z ranges, worst step and its location, frame-time percentiles — so a claim in `TODO.md`, `CHANGELOG.md` or `Docs/` can be re-checked by re-running the command.
+
+**Document every tool.** A new or changed tool gets a row in the inventory table of the README beside it: [`Tools/README.md`](Tools/README.md), [`Geo/README.md`](Geo/README.md), or [`Art/blender/README.md`](Art/blender/README.md). What it does, its arguments, and a typical command. A tool without a README row is unfinished.
+
+**Test the pure parts.** `Tools/tests/` holds stdlib `unittest` tests (no Blender or Unreal process; they must not start a game or editor). Extract the testable core — argument parsing, geometry maths, licence gating, report formatting — into functions that a test can call directly.
+
+```bash
+python3 -m unittest discover -s Tools/tests -t Tools -p 'test_*.py'
+```
+
+Keep the tools standard-library-only where practical; if a third-party import is genuinely needed, add it to `requirements-tools.txt` with a version floor and mention it in the tool's README row.
+
+## Architecture documentation
+
+[`Docs/Architecture/`](Docs/Architecture/) is the arc42 documentation: twelve numbered section files, `about-arc42.md`, and the combined [`architecture.md`](Docs/Architecture/architecture.md). **Markdown is canonical** — the `.adoc` sources were removed on 2026-11-08.
+
+Keep it current **in the same change as the implementation**, not in a later documentation pass. When work alters any of the following, edit the matching section:
+
+| Change | Section |
+| --- | --- |
+| A new or restructured module, tool, data source or external interface | `05_building_block_view.md` |
+| A runtime flow, tick/order dependency, or lifecycle (possession, map load, QA self-test) | `06_runtime_view.md` |
+| Packaging, engine pin, checkout/build/launch procedure | `07_deployment_view.md` |
+| A pattern, convention or cross-cutting rule (units, collision policy, provenance) | `08_concepts.md` |
+| A decision that constrains future work | new ADR in `09_architecture_decisions.md` |
+| A quality goal or a measured budget (frame time, traversal coverage) | `10_quality_requirements.md` |
+| A known risk or a risk that retired | `11_technical_risks.md` |
+| A new term, tool or abbreviation | `12_glossary.md` |
+
+Rules:
+
+- **Describe what exists.** No aspirational architecture: anything planned belongs in `ROADMAP.md` and `TODO.md`. Every structural claim names the file, script or flag that implements it.
+- **ADRs are append-only.** Never rewrite an accepted decision; supersede it with a new ADR that says what it replaces and why.
+- **Keep the combined document in sync.** `architecture.md` mirrors the section files; when a section changes, update the combined document too.
+- **Images** live in `Docs/Architecture/images/` and are referenced, not duplicated.
+- **Verify:** all Markdown must pass `prettier --check` (config in `.prettierrc`), and a command you quote must still run.
+
 ## Geographic & Art Pipeline
 
 1. Save a versioned OSM extract; document date, bounds, and source.