diff --git a/docs/PROJECT-STRUCTURE.md b/docs/PROJECT-STRUCTURE.md
index 248ee30..eb9972c 100644
--- a/docs/PROJECT-STRUCTURE.md
+++ b/docs/PROJECT-STRUCTURE.md
@@ -37,6 +37,9 @@ S:\Game Hacking\Eushully\Himegari\           ← workspace root (three siblings)
     │   ├── opcodes_build.py                    generator/linter: vm-map/opcodes.toml -> the 4 artifacts below
     │   ├── opcodes_model.py                    load + lint (dangling-ref, confidence-ceiling, vocab) + dependents
     │   ├── age_opcodes_himegari.py             GENERATED from opcodes.toml (do not hand-edit)
+    │   ├── globals_build.py                    generator/linter: vm-map/globals.toml (+auto map) -> build/globals.json, docs/global-reference.md
+    │   ├── story_flags.py                      static story-flag miner (branch-condition) -> build/story-flags-candidates.json; --bootstrap
+    │   ├── test_globals.py, test_opcodes.py    unit tests for the globals / opcode tooling
     │   ├── vm0.py                              headless Python VM (Phase A0); `--test` = RECOVER unit test
     │   ├── extract_phase2.py                   batch: disasm + text + data extraction
     │   ├── extract_init.py, global_map.py …    *INIT parsers, global-var map builder
@@ -50,6 +53,8 @@ S:\Game Hacking\Eushully\Himegari\           ← workspace root (three siblings)
     ├── vm-map/                               VM / reverse-engineering reference artifacts
     │   ├── opcodes.toml                        ★ CANONICAL opcode reference (hand-edited: ABI + semantics
     │   │                                        + provenance + depends_on). Single source of truth for opcodes.
+    │   ├── globals.toml                        ★ CANONICAL global-variable registry (hand-edited: name + category
+    │   │                                        + value_domain + provenance). Single source of truth for globals/story-flags.
     │   ├── kelebek1-age-shared.cpp / -disassembler.cpp   upstream opcode-table source
     │   └── opcode-leads.json, small-script-listings.md
     │
@@ -62,10 +67,11 @@ S:\Game Hacking\Eushully\Himegari\           ← workspace root (three siblings)
     │   ├── phase-a-slice-plan.md               the current slice (A0/A1/A2)
     │   ├── vm-mapping-plan.md                  the phased decode plan
     │   ├── himegari-port-reference.md          master reference + engine background
-    │   ├── name-resolution.md                  call-script + global-var name recovery
+    │   ├── name-resolution.md                  call-script + global-var name recovery (+ globals.toml registry)
     │   ├── sys4-format-notes.md                byte-level container format
     │   ├── script-inventory.md                 what the 481 scripts are
-    │   └── opcode-reference.md                 GENERATED from opcodes.toml (human-readable opcode reference)
+    │   ├── opcode-reference.md                 GENERATED from opcodes.toml (human-readable opcode reference)
+    │   └── global-reference.md                 GENERATED from globals.toml (human-readable global registry)
     │
     ├── build/                               DERIVED (our-work-side) — generated by tools/; disposable
     │   ├── disasm/                            <NAME>.asm — human-readable disassembly, one per script
@@ -78,7 +84,9 @@ S:\Game Hacking\Eushully\Himegari\           ← workspace root (three siblings)
     │   ├── textures/                          AGF→BMP stills (convert_agf.py) — feeds the Godot render
     │   ├── engine-dump/                       UNPACKED engine dump (frida/dump_engine.py): range_<base>.bin + manifest.json
     │   ├── asset-index.json, asset-sections.json   asset resolver data (parse_sys4ini / resolve_asset)
-    │   ├── global-var-map.{json,md}           partial global-variable name map
+    │   ├── global-var-map.{json,md}           partial global-variable name map (auto shape inference; feeds globals.toml merge)
+    │   ├── globals.json                        GENERATED from globals.toml merged over global-var-map (sys4load labels + C# VM)
+    │   ├── story-flags-candidates.json         GENERATED by story_flags.py (ranked story-flag review surface)
     │   ├── opcodes.json                        GENERATED from opcodes.toml (machine view for the C# VM)
     │   └── manifest.json, opcode-coverage.md   (opcode-coverage.md GENERATED from opcodes.toml)
     │
@@ -107,6 +115,10 @@ S:\Game Hacking\Eushully\Himegari\           ← workspace root (three siblings)
   `depends_on`). Run `tools/opcodes_build.py --build` to regenerate the shim (`tools/age_opcodes_himegari.py`),
   machine JSON (`build/opcodes.json`), reference (`docs/opcode-reference.md`), and coverage. `--lint`
   checks dangling deps / confidence-ceiling / vocabulary. Kelebek's `tools/age_opcodes.py` stays pristine.
+- **Global-variable knowledge is edited ONLY in `vm-map/globals.toml`** (name + category + value_domain +
+  provenance). Run `tools/globals_build.py --build` to regenerate `build/globals.json` (sys4load labels) and
+  `docs/global-reference.md`; `--lint` checks vocabulary / auto-shape≠high / dangling deps. Curated entries
+  override the auto shape map (`build/global-var-map.json`). Discover story-flag candidates with `tools/story_flags.py`.
 - **Encoding:** all generated text is UTF-8 (source strings are cp932/Shift-JIS, decoded on
   extraction). Run Python as `py -3.11 -X utf8`.
 - **The game install is a runnable unit** — do not relocate `AGE.EXE`/`*.ALF`/DLLs relative to each