Documentation
These pages are the project’s own markdown, rendered here so you can read them without leaving the site. Every page links back to its source file — fix a line there and it appears here on the next build.
Start here
Concepts
Reference
- Scenario schemaThe complete scenario.yaml reference: components, checks, parameters.
- CLI referenceInstall, global flags, and the map of every labctl command.
- Lifecycle & environmentinit, doctor, the cluster, snapshots, and reading back what labctl did.
- Applications & servicesBuild, deploy and destroy apps; install the services they depend on.
- PlatformInstall, remove and inspect the infrastructure the lab runs on.
- Scenario commandsActivate, grade, reset and validate scenarios.
- Incident commandsInject reversible faults, run game days, and score the fix.
- TrafficGenerate realistic in-cluster load with k6.
- Learning & challengesGuided paths and timed, auto-graded assessments.
- Server, metrics & authRun the web UI and API, expose metrics, and enable team mode.
- TestingThe four mandatory test layers and the CI gates.
Authoring
Decisions
- ADR 0001 — Cut cloud runtimes and commercial surfacesArchitecture decision records — why it was built this way.
- ADR 0002 — SQLite (pure Go) for persistenceArchitecture decision records — why it was built this way.
- ADR 0003 — A durable run engine over shell scripts, not a Kubernetes operatorArchitecture decision records — why it was built this way.
- ADR 0004 — Exclusive lock keys; reject conflicting runsArchitecture decision records — why it was built this way.
- ADR 0005 — Module at the repo root; service-layer architectureArchitecture decision records — why it was built this way.
- ADR 0006 — API v2: versioned, problem+json, cursor streamingArchitecture decision records — why it was built this way.
- ADR 0007 — UI stack: React Router, TanStack Query, Tailwind, RadixArchitecture decision records — why it was built this way.
- ADR 0008 — Content paths and an extension seam instead of a marketplaceArchitecture decision records — why it was built this way.
- ADR 0009 — JSON Schemas for authoring, Go loaders for validationArchitecture decision records — why it was built this way.
- ADR 0010 — Platform values are the single source of truth for a componentArchitecture decision records — why it was built this way.
- ADR 0011 — Pin every chart; migrate off the deprecated Grafana chartsArchitecture decision records — why it was built this way.
- ADR 0012 — Grafana Alloy as the trace collector; Promtail retained for logsArchitecture decision records — why it was built this way.
- ADR 0013 — Remove the unversioned /api aliasArchitecture decision records — why it was built this way.
Runbooks
- R00 — Environment & BuildHands-on validation a human performs before a wave merges.
- R01 — Run Engine & CancellationHands-on validation a human performs before a wave merges.
- R02 — Doctor & PreflightHands-on validation a human performs before a wave merges.
- R03 — Content authoring & validationHands-on validation a human performs before a wave merges.
- R04 — Lab lifecycle reliabilityHands-on validation a human performs before a wave merges.
- R05 — Platform componentsHands-on validation a human performs before a wave merges.
- R06 — Multi-Env Promotion (Dev → Staging → Prod)Hands-on validation a human performs before a wave merges.
- R13 — Observability pipeline: metrics, logs and tracesHands-on validation a human performs before a wave merges.
Project
- ContributingGolden rules, the PR bar and the review checklist.
- RoadmapThe wave plan, exit criteria and Definition of Done.
- ReleasingHow a versioned release is cut.
- Security policyHow to report a vulnerability.
- GovernanceHow decisions get made.
- Code of conductThe behaviour expected of everyone in the project.
Looking for something that is not here? The repository has more — ADR templates, RFCs, test fixtures and the full commit history. Browse it on GitHub.