Twenty documentation pages: Getting started (7) and Administration (13), the
journey no existing document owns end to end because the repositories are
organised by component and an operator is not.
Four decisions of record, taken before anything was written (D34–D37, PLAN.md
§10 "How phase 7 built the documentation journey"):
- D34 one PR for all twenty pages.
- D35 the install page is SELF-CONTAINED: it prints a complete Compose file and
a complete .env that an operator copies without visiting another repository.
That is a copy of somebody else's file, so it is checked rather than trusted —
scripts/checkQuickstart.mjs re-reads website main:docker-compose.yml and
main:.env.example over the Gitea API and fails on any disagreement, in both
directions: a value that drifts fails, and a service or variable that appears
upstream fails until it is either included or recorded as deliberately omitted
with a reason. Its first run found two stale entries.
- D36 every Administration screen was walked on a real deployment before it was
described — the rig being the quickstart itself, against the published image,
so one run proved the install page and produced the detail the admin pages
needed.
- D37 a thirteenth Administration page, Content, so that every admin nav row has
a home without organising the docs by the app's menu.
What the live deployment disproved, all three now documented:
- The documented Compose deploy does not boot. SECRET_ENC_KEY is required in
production (utils/secretBox.js throws at require time) and is missing from
website's ROOT .env.example — the file Compose reads. It is present in
server/.env.example, which is why dev never hits it. The quickstart carries it,
declared as an upstream omission so the check fails the day it is fixed.
- The installer points operators at a screen that no longer exists: it prints
<site>/admin/shard, and INSTALL.md §5 repeats it, but since the module cutover
the screen is /admin/uo/link. Both the binary and the guide are stale.
- The admin Restart button opens a window.confirm whose text is the honest
warning that a deployment with no supervisor does not come back — which is why
`restart: unless-stopped` is called out as load-bearing rather than left as
boilerplate.
And the defect only a look found, three phases running: the .env block's prose
promised that every highlighted line must be changed, while `mark` given the
variable names highlighted the names alone and left the values unmarked. Every
check passed on a page that was wrong about its own highlighting.
verify green: 890 internal links, 52 branch links, 19 facts, 59 quickstart
checks, 0 astro-check errors.
Co-Authored-By: Claude <noreply@anthropic.com>
