Repository Tour

Repository Tour

The public tree separates offline translation, native runtime behavior, reference execution, verification, and project governance.

Area	Purpose	Editing boundary
tools/	ELF/PRX loading, import reconstruction, analysis, code generation, tests, audits, and verification gates.	Human-authored Python and fixtures; add focused tests with behavior changes.
src/rt/	Native runtime, HLE, scheduler, memory helpers, filesystem, media, and renderer backends.	Human-authored C; preserve the shared ABI and fail-closed behavior.
src/ref/	Separate C++ reference interpreter and selftests for differential/local-consistency work.	Verification/reference implementation, not the normal game executable.
fixtures/	Source-owned synthetic and PSPDEV probe inputs that can be redistributed with the public source.	Keep fixtures public-safe; never substitute proprietary title inputs.
assets/vfpu/	Pinned VFPU lookup tables with upstream provenance.	Preserve provenance and notices.
font/	Replacement-font material and its provenance boundary.	Do not infer redistribution clearance from neighboring files.
interface/	Optional Next.js dashboard/prototype.	Separate from the native HST build.
docs/	Maintained setup, architecture, debugging, verification, governance, and provenance records.	Prefer maintained guides over dated investigations.
Makefile and hst_manager.ps1	Build and run orchestration.	Keep the two-phase generated-code build model intact.
build/	Generated local output created by local builds; it is Git-ignored.	Never edit or publish generated output.

Where to start a change

• Translation behavior: tools/codegen.py, tools/analyze.py, tools/imports.py, or tools/prxload.py, plus a focused synthetic regression.
• Runtime behavior: the relevant file under src/rt/, its public header, and a production-path or source-owned selftest.
• Verification: the matching gate under tools/, src/ref/, or the renderer/audio selftest route.
• Documentation and governance: the maintained page listed by docs/README.md.

Generated files are outputs, not source ownership boundaries. If a generated artifact disagrees with source, regenerate from a clean/known-complete pipeline and inspect the source/tooling change.