Add repository front door

README.md

@@ -0,0 +1,47 @@
+# AGE engine reimplementation
+
+Open reimplementation of Eushully's AGE engine with first-class modding. The first target is
+*Himegari Dungeon Meister* (SYS4, 2009); the runtime is Godot 4.7 .NET plus a platform-neutral C# VM.
+
+This repository contains only authored engine, tooling, native-boundary, test, and documentation files.
+It does not contain the original game. Supply a legally obtained AGE installation separately; never copy
+original game data into this repository.
+
+## Start here
+
+Prerequisites for the current Windows development workflow are Python 3.11, the .NET 8 SDK, Godot 4.7
+.NET, and a Himegari install containing `SYS4INI.BIN`. Pass paths explicitly or configure
+`AGE_GODOT_CONSOLE` and `AGE_GAME_ROOT`.
+
+```powershell
+# Verify and display the resolved development environment without launching.
+.\run-godot.ps1 -Doctor -GodotConsole <godot-console.exe> -GameRoot <Himegari-install>
+
+# Run source-only/core validation. The default validation level is the complete workspace/runtime suite.
+py -3.11 -X utf8 tools\validate.py --level core
+
+# Build and launch the natural SYSTEM4 → title → game route.
+.\run-godot.ps1 -GodotConsole <godot-console.exe> -GameRoot <Himegari-install>
+```
+
+`workspace` and `full` validation additionally require the extracted script corpus and disposable derived
+inputs described by the tools reference. `runtime` and `full` require Godot plus a valid game root. A
+selected requirement that is unavailable is an error, not a silent skip.
+
+## Canonical references
+
+- [Architecture and roadmap](docs/remake-architecture-and-roadmap.md) — direction, phases, and the current
+  codebase-consolidation effort.
+- [Project structure](docs/PROJECT-STRUCTURE.md) — source/original/derived ownership and directory layout.
+- [Tools reference](docs/tools-reference.md) — exact commands, prerequisites, inputs, and outputs.
+- [Phase B framework](docs/phase-b-framework.md) — boot, menu, session, and gameplay execution order.
+- [Engine reverse engineering](docs/engine-re.md) — native AGE findings and provenance.
+
+Follow the repository's canonical-document map when recording new knowledge: extend the existing owner and
+cross-link it instead of duplicating facts here.
+
+## Generated data
+
+`build/` is disposable and ignored. Generated references identify their canonical source in their header;
+edit that source and run its owning generator rather than patching generated output. The original game
+install and extracted archives remain sibling directories outside this Git repository.

docs/PROJECT-STRUCTURE.md

@@ -28,6 +28,7 @@ S:\Game Hacking\Eushully\Himegari\           ← workspace root (three siblings)
 │
 └── age-reimpl/                              ← OUR WORK (everything we made lives here)
     │
+    ├── README.md                             navigation-only repository front door; canonical facts stay in docs/
     ├── run-godot.ps1 / run-godot.cmd         tracked development launcher + Windows wrapper;
     │                                          resolves Godot/game-root from parameters, environment,
     │                                          PATH, and the conventional sibling install

docs/remake-architecture-and-roadmap.md

@@ -524,8 +524,8 @@ requirements.
 
 #### Planned maintenance slice — codebase consolidation
 
-**Status (2026-08-02): planned; step 1 is next.** The runtime and tooling now have enough independent
+**Status (2026-08-02): step 1 complete; step 2 is next.** The runtime and tooling now have enough independent
-regression coverage to support behavior-preserving cleanup: 590 engine tests, ten directly runnable Python
+regression coverage to support behavior-preserving cleanup: 590 engine tests, eleven directly runnable Python
 tool suites, the Godot build/self-test, and the installed-corpus gates. The project layout itself is sound,
 but a few files have become navigation and ownership bottlenecks: `VirtualMachine.cs`, `GfxState.cs`,
 `Main.cs`, `GodotAdvHost.cs`, and `extract_init.py`. Repository entry points are also partly machine-local,
@@ -536,7 +536,8 @@ compatibility, current command paths, generated-file ownership, and the one-engi
 Each step should land in bounded commits with the full validation level appropriate to the touched boundary;
 do not mix mechanical moves with semantic changes.
 
-1. **Create a reproducible project front door.** Replace the locally excluded, machine-path-specific
+1. **Create a reproducible project front door — completed 2026-08-02.** Replace the locally excluded,
+   machine-path-specific
    `run-godot.ps1`/`.cmd` workflow with a tracked launcher whose explicit parameters and documented
    environment fallbacks select Godot and the game root. Implement the already-listed one-command
    validation driver from `docs/tools-reference.md`, with named levels that distinguish hermetic/core,
@@ -927,8 +928,8 @@ layer's rendering diverges from ADV; save layout.
 ---
 
 ## 8. Immediate next step
-Begin step 1 of the **codebase consolidation** maintenance slice: land the tracked parameterized Godot
+Begin step 2 of the **codebase consolidation** maintenance slice: behavior-neutral physical splits backed
-launcher, then the layered one-command validation driver, then the navigation-only repository README.
+by the tracked launcher and layered validation driver. Start with the embedded `Main` self-test surface,
-The launcher and validator establish the reproducible safety boundary needed before physical file splits.
+then move one existing domain at a time while preserving public types, commands, and generated output.
 Concrete playthrough blockers may still preempt this bounded maintenance work; the consolidation effort does
 not replace Phase B gameplay validation or the open cross-platform gates.