Project Source Map
This map describes the current repository. AGENTS.md is the working-instructions entry point; this guide explains where information belongs. Neither grants tool permissions.
| Subject | Maintained home | Derived result or check |
|---|---|---|
| Chapter text and stable IDs | docs/; chapter conventions | Astro reads these files directly; filename and chapter number determine order |
| Terminology and writing | Glossary, contribution guide | Editorial review |
| Tutorial intent and rationale | Specification register, dated design decisions | Owner review; proposed details remain open |
| Procedure examples | Showcase sources | Fixed handbook and review chart; separate browser practice copies |
| Structured records and rules | Requirement guide, contract records and schema | Explicitly configured processors and validation tests |
| Website and learning components | Site guide, site/src/ | Astro check, build, and site tests |
| Presentation definitions | Presentation guide | HTML slides and notes generated during site build |
| Automation and release | Automation guide, .github/workflows/ | PR checks, artifacts, Pages deployment |
| History and operational evidence | Measurement guide, data/features.json | Build-time dashboard snapshots; fixed historical charts remain unchanged |
Authority and Identity
Chapter IDs survive reordering; their current convention lives in CONTRIBUTING.md. Record schemas define permitted fields and relationship types for their own datasets, not for every file in the repository. A generated report, browser practice edit, or decision proposal does not replace its maintained source.
The decision register records the owner-supplied design direction on 19 October 2026. It is not a reconstructed history of earlier architecture approvals. The current architecture can also be inspected in Chapter 11.
Route a Maintenance Task
For a chapter change, start with its docs/ file, then inspect relevant linked examples, diagram sources, and presentation citations. For a schema change, identify the processor that loads it and the selected record files before editing. Consult the verification instructions, run affected tests, and report changed, checked-unchanged, and unverified items.