Documentation is organized by responsibility: each category answers one class of
question. This mirrors the layout used across open-strata and hydra-merlin,
so the three repositories read the same way.
When a summary disagrees with the implementation, the implementation wins and the summary is a bug. When a summary disagrees with architecture/WORKSPACE.md about structure, the contract wins — structural changes go there first, in their own PR.
| Category | Answers | Start here |
|---|---|---|
| architecture/ | How the workspace is structured: bundle identities, dependency directions, artifact naming. | WORKSPACE.md |
| guides/ | How to accomplish a task. | INSTALL.md |
| reference/ | Factual contracts: what is supported, on what. | CAPABILITY_MATRIX.md |
| roadmap/ | What is planned next (only incomplete work). | README.md |
| releases/ | Immutable per-version release records. | README.md |
| design/ | Why significant decisions were made. | DESIGN_POLICY.md |
| reports/ | Evidence from real runs: the ost dogfooding series and the delivery log. |
README.md |
| contributing/ | Contributor procedures. | RELEASE_NOTES_TEMPLATE.md |
- design/DESIGN_POLICY.md is the long-form design & development policy for the importer — the source of truth for Product P0–P6 and for the import / evaluation / simulation boundary.
- design/MOTION_ARCHITECTURE_POLICY.md
is the policy for everything below the importer —
.vrmaimport, the vendor-neutral motion core, retargeting, and the OpenExec runtime. Source of truth for Motion Phase A–H. It extends DESIGN_POLICY §10 and restructures §17-P4; where the two overlap, the motion policy wins. - architecture/WORKSPACE.md is the binding workspace contract — the source of truth for bundle identities, dependency directions, artifact naming, and Workspace Phase 0–8.
The three phase systems are separate and always qualified; see roadmap/README.md.
Bundle-specific docs live with their bundle, not here:
| Bundle | Docs |
|---|---|
vrmSchema |
README · SCHEMA_CONTRACT.md |
usdVrmFileFormat |
README · DIAGNOSTICS.md · CORPUS.md |
usdVrmPackageResolver |
README |
vrmContainer |
README |