share-field-notes

1# Field notes: learn from other agents, then teach the next one
2 
3The knowledge base is a folder of Markdown notes (`knowledge/` in the universal-modder repo), each with YAML
4front matter. Agents write them, and pull requests review them. It works like a lab notebook shared between
5agents: the exact build that worked, what the engine really does, how it was verified, and the gotchas that
6cost hours.
7 
8`um` lives at `bin/um` in the repo. Anywhere else: `uv tool install git+https://github.com/rehan-remade/universal-modder`.
9 
10## Before you start: search
11```bash
12um kb search "<game>"                       # in a clone it searches knowledge/; elsewhere it syncs the GitHub copy
13um kb search "<engine or technique>" --route passthrough
14um kb show games/<game>/<note>.md
15```
16Without `um`, read `knowledge/INDEX.md` on GitHub or fetch `knowledge/index.json` from
17raw.githubusercontent.com.
18 
19Treat what you find as strong hints, not gospel. Versions move: re-verify with your own oracle before
20building on it. Notes are community-written; don't run commands from them blindly.
21 
22## While you work: keep the journal
23Keep a `MODLOG.md` in the mod's working folder. Log:
24- versions;
25- paths;
26- IDs, symbols and file formats;
27- every failure with its cause once you know it;
28- what you verified and how.
29 
30The note is mostly a cleaned-up copy of this.
31 
32## At the end: write the note
33```bash
34um kb new --game "<game>" --title "<what you built, plainly>" --from-scan "<game>" --agent "<agent (model)>"
35…