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.
| Reader | Start with |
|---|---|
| New reader / non-technical reviewer | Brochures |
| Project reviewer | ARCHITECTURE.md, software architecture diagrams, then RFCs |
| New contributor | ../CONTRIBUTING.md, ../GOVERNANCE.md, then GLOSSARY.md |
| Deployment reviewer | Unified deployment model, deployment roles, then designs/README.md |
| First-product reviewer | First adoptable product, then operations portal |
| City/network planner | designs/README.md, cost model, civil OSR-ALN format |
| Rolling-stock engineer | rolling-stock/light-metro-3car/README.md |
| Mechanical/CAD reviewer | mechanical-py/README.md and mechanical-py/catalog/ |
| Hardware reviewer | hardware/README.md and hardware/rolling-stock-integration.md |
| Operator/maintainer / production planner | operations/README.md, operations portal, OSR Ops Core |
| Safety/certification reviewer | certification/README.md, safety-case/README.md, formal/tla/README.md |
| v0.2 contributor | ROADMAP.md |
| Release reviewer | v0.2 release pack |
| 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 |
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