Documentation gaps
Documentation gaps
The doc site follows the Diátaxis structure required by section 5.2.1.1 of the Theseus Platform Vision design document. The structure is ahead of the content: this page lists what is still missing so contributors can see the plan at a glance. Pages marked stub exist with front-matter and a scope note; the others have no page yet. When a gap is filled, it moves to Recently filled rather than silently vanishing.
Recently filled
| Page | Quadrant | What it covers |
|---|---|---|
| Add database migrations to your service | Tutorial | From schema-at-startup to versioned, reversible migrations run by the migrator init container: author, validate, apply, roll back, package, wire |
| Run database migrations with migrator | How-to | Validate and round-trip in CI, build the derived image, declare the init container, adopt an existing database, rollback, exit codes |
| bench CLI | Reference | Quickstart and command reference for bench: init, check, assembly/service create, scaffold, and build |
| Onboard to Release Framework | How-to | From a YAML entry in infra-mgmt to a merged, provisioned project |
| Pass application configuration via Fairway | How-to | spec.values.appConfig per environment, including the forward-looking Cells injection flow |
| Modify the values and secrets passed to your service | How-to | Deploy-time value overrides and the Vault-backed secrets lifecycle |
| Go service template (exemplar) | Reference | The live reference implementation to read alongside every guide |
| Release Framework | Reference | Component page, plus architecture and internals in Explanation |
| Update your service template | How-to | copier update, conflict handling, and migrations — exercised daily by the update-migration journey test |
| Modular feature test isolation | Strategies | Contract-edge testing with in-process fakes and Caproni-provided infrastructure, with a companion how-to grounded in the exemplar’s acceptance suite |
| Get distributed tracing on Runway | How-to | From scaffold to spans in Cloud Trace: LabKit v2 tracer wiring, Runway’s injected GITLAB_TRACING, domain spans, sampling, and local verification |
| Get structured logging on Runway | How-to | The JSON-on-stderr contract: LabKit v2 logger defaults, the node agent’s parsing and enrichment, querying ClickHouse in Grafana, and level tuning |
| Get Prometheus metrics on Runway | How-to | LabKit v2’s /-/metrics on the probe port, spec.metrics in Fairway, the per-deployment ServiceMonitor switch, and querying Mimir in Grafana |
| Read the release manifest | How-to | Fetching the record and a catalog entry, reading module versions, validating against the JSON Schema, and interpreting absence |
Tutorials
| Gap | Status | Intended scope |
|---|---|---|
| Deploy your first service to production | not started | End-to-end walkthrough: scaffold, register the project, merge the provisioner MR, and watch the first deploy land |
| Local development deep-dive with Caproni | not started | Hot-reload, debugging, and working against in-cluster dependencies from gitlab-dev-stack |
How-to guides
| Gap | Status | Intended scope |
|---|---|---|
| Run your service locally with Caproni | stub | caproni up / caproni run against a generated service |
| Deploy a service with Runway | stub | From .runway/fairway.yaml to a production deployment; configuration, values, and secrets flows are now covered by the guides above — the deployment-pipeline walkthrough itself remains |
| Generate PREP evidence | not started | Using bench prep to produce a readiness report (blocked on
bench prep shipping) |
| Register a project with infra-mgmt | not started | Branch protections, approval rules, and CI/CD tokens through automation; the Release Framework path is covered by Onboard to Release Framework — the general path remains |
Operate
Incident-time procedures live in Operate. These rows are the holes that section makes visible; each is owned outside Theseus and the page links the tracking issue.
| Gap | Status | Intended scope |
|---|---|---|
| Versioned rollback on the Runway Kubernetes runtime | blocked on Runway work item 983 | Replace “retry the last good pipeline” in Roll back a deployment with the Run pipeline rollback form once it ships |
| Per-cell deploy path for a modular service | blocked on Delivery work item 22155 | Fill the “On Cells” parts of See what is running, Roll a deployment and Roll back a deployment with the real procedure |
| Cell identity on metrics, not only alerts | blocked on Test Cells Observability | Document the label and a per-cell query in Know which cell is affected |
Reference
| Gap | Status | Intended scope |
|---|---|---|
| Fairway manifest schema | stub | Full FairwayManifest field reference, including the infrastructure dependency block; the appConfig and secrets-related values fields are demonstrated practically in the how-to guides — the field reference remains |
| Docs front-matter schema | not started | The validated front-matter convention (alert IDs, SLO references, severity, on-call routing) required by the handbook; the validation tooling is also still to be built |
Explanation
| Gap | Status | Intended scope |
|---|---|---|
| Cellular architecture | stub | Full treatment of Cells as the isolation primitive; summarised today under Platform bindings, with the Cells config-injection flow sketched in Pass application configuration via Fairway |
| The PREP connection | not started | How Theseus turns PREP categories into evidence; partially covered in Vision |
| The three-layer service model | not started | Inbound / Business Logic / Outbound, and what the framework owns versus the developer |
| Multi-target deployment beyond bindings | not started | SMF (Omnibus) and FedRAMP / Dedicated for Government positioning (handbook sections 4.4–4.5) |
Last updated on