I1511 — The documentation surface answers in a checkout that has not built the site
Make /docs/ say what it needs rather than fail, so that a developer entering a fresh worktree does not meet a broken documentation surface as their first impression of the runtime.
DONE wave 0 · p2 · implementation profile · parallel safe
Part of development-runtime — The runtime has a development surface.
Objective
Make /docs/ say what it needs rather than fail, so that a developer entering a fresh worktree does not meet a broken documentation surface as their first impression of the runtime.
Why
F4 of the audit's failure table. /docs/ is served from target/web/docs, which is a build output, so in any checkout that has not built the site the surface returns 503. Every other error this server produces is a model of what an error should say — the 404 body names the route and points at /openapi.json — and this one is the exception. It matters more than its size suggests because a fresh linked worktree is exactly where a new worker starts, and a documentation surface that is down is indistinguishable from a documentation surface that does not exist.
Current state
GET /docs/ returns 503 with a 251-byte JSON body in a checkout whose site has not been built. Nothing on the way in says the surface has a build step.
Desired state
The surface either answers from something every checkout has, or returns an error that names the one command that would make it answer.
Scope
- apps/majordomus-cli/src/web
- docs/COCKPIT.md
- test/cases
Out of scope
- Building the site as a side effect of serving. A read surface that triggers a build is the class of side effect the repository's own diagnostics rule forbids.
Dependencies
None. This issue is a root of the graph.
Acceptance criteria
- A checkout that has not built the site gets an answer or an error naming the command that fixes it
- Nothing builds anything as a side effect of a GET
Validation
- bash test/run.sh
Evidence required
- unbuilt_checkout_gets_a_useful_answer
Evidence
| covers | type | command | result | at commit |
|---|---|---|---|---|
| unbuilt_checkout_gets_a_useful_answer | test | cargo test --locked --manifest-path apps/majordomus-cli/Cargo.toml --lib a_surface_whose_producer_has_not_run_says_what_to_run | test result: ok. 1 passed; 0 failed (run 2026-10-14 between 07:40Z and 07:58Z on master ce5959db59) | ce5959d |
Risk
Low.
Timeline
- started
- 2026-10-14T07:58:52Z
- verified
- —
- completed
- 2026-10-14T07:58:59Z
Those three fields, the evidence above and the state of the dependencies are all the status is made of. There is no status field to disagree with them.
Canonical record: .ai/repo/project/issues/I1511.yaml. Read it back with majordomus plan show I1511.