This is the documentation front door. The repository intentionally keeps source code, generated city designs, mechanical CAD, hardware, and safety evidence in separate top-level areas; this page links those areas without duplicating them.
For a single catalogue of every Markdown file in the repository, use the generated Markdown documentation index.
| Folder | Contents |
|---|---|
| rfcs/ | Design decisions and standards for architecture, rolling stock, track, stations, depots, driverless operation, hardware, energy, and safety |
| brochures/ | Short PDF introductions and presentation-style summaries |
| deployment-model.md | Unified city/deployment pipeline; Samawah is an instance, not a special fork |
| deployment-roles.md | Owner/operator, prime integrator, assessor, insurer, EPC, workshop, finance, and regulator responsibilities |
| first-adoptable-product.md | Ops Core + simulator + asset register + QA/maintenance/evidence portal as the first low-risk deployment wedge |
| rolling-stock/ | Light-metro trainset package: GA, body, bogie, traction, BOM, fabrication plan, drawing register, compliance |
| civil/ | Alignment interchange format and civil tool bridge docs |
| stations/ | Station design material |
| operations/ | Rulebook and operating procedures |
| operations-portal/ | Browser portal for asset registers, manufacturing schedule, QA gates, maintenance schedule, Ops Core work orders, defects/NCR, audit, SQLite storage, and reconciliation |
| certification/ | EN 62267 pre-submission pack: system description, hazards, safety requirements, evidence, compliance matrix |
| safety-case/ | GSN safety-case source and generated views |
| hardware/ | Hardware bring-up docs |
| releases/ | Release packs, assets, metadata, and publication checklists |
| screenshots/ | Generated UI/CAD screenshots used by READMEs |
| Artifact | Location |
|---|---|
| City design catalogue and reviewed references | designs/README.md |
| City source list | lib/city-batches/world-sample.toml |
| Mechanical FreeCAD review artifacts | mechanical-py/catalog/ |
| Rolling-stock BOM | rolling-stock/light-metro-3car/bom-skeleton.md |
| BOM export command | python3 scripts/export-light-metro-bom.py (writes under build/bom/) |
| Generated station BOMs and travelers | mechanical-py/catalog/buildable-stations/ |
| Hardware host-class matrix | hardware/rolling-stock-integration.md |
| Deployment roles | deployment-roles.md |
| First adoptable product | first-adoptable-product.md |
| Software architecture diagrams | software-architecture-diagrams.md |
| Hardware release checklist | hardware/release-checklist.md |
| Rolling-stock v2 release checklist | rolling-stock/light-metro-3car/v2-release-checklist.md |
| Certification release gaps | certification/release-gap-register.md |
| Civil deployment release gates | civil/deployment-release-checklist.md |
| Open-source engineering toolchain and remaining execution plan | engineering-design-simulation-plan.md |
| OpenTrack vs SUMO/native operations-simulation decision | opentrack-evaluation.md |
| Operations validation gates | operations/validation-checklist.md |
| Operations portal | operations-portal/README.md |
| Ops Core operating model | operations-portal/ops-core.md |
| Acceptance/accreditation evidence status | certification/evidence-status.md |
| Construction QA system | rfcs/0028-construction-quality-assurance.md |
| Maintenance schedule system | rfcs/0029-maintenance-schedule-system.md |
| Manufacturing schedule system | rfcs/0030-manufacturing-schedule-system.md |
| Reader-edition PDF | python3 scripts/build-doc-book.py → build/releases/ |
| Introduction brochure | brochures/open-source-rail-introduction.html |
| v0.2 roadmap | ROADMAP.md |
| Next release checklist | releases/next.md |
| GitHub metadata | ../.github/repository-metadata.yml |
Use the root README for the common commands. The short version:
scripts/regenerate-city.sh samawah
PYTHONPATH=mechanical-py/src python3 -m osr_mech.catalog --out mechanical-py/catalog
PYTHONPATH=mechanical-py/src mechanical-py/scripts/freecad_trainset.sh --family light-metro-3car
python3 scripts/repo-health.py --quiet
python3 scripts/generate-doc-index.py