docs(journey): phase 7 — the installation path and administration #10

wtclaude · 2026-08-24T13:35:43Z

wtclaude commented

2026-08-24 13:35:43 +00:00

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. PLAN.md calls the installation path "the priority of the whole project".

The four decisions (D34–D37)

Taken before anything was written; recorded in PLAN.md §10, How phase 7 built the documentation journey. The count of record is now thirty-seven.

#	Decision
D34	One PR for all twenty pages, rather than splitting Getting started from Administration
D35	The install page is self-contained — it prints a complete Compose file and `.env`, checked against upstream rather than trusted
D36	Every Administration screen was walked on a real deployment before it was described
D37	A thirteenth Administration page, Content, so every admin nav row has a home

D35 and the check it needs

/docs/getting-started/install-the-site/ prints both files verbatim, which is the one place this site knowingly copies another repo's file — exactly what §1 warns about. So it is checked, not trusted:

scripts/checkQuickstart.mjs re-reads website main:docker-compose.yml and main:.env.example over the Gitea API and fails the build on any disagreement, in both directions:

every value the quickstart states must match upstream's;
every service and variable upstream has must be either included or listed as deliberately omitted, with a reason — so a new variable in .env.example turns this repo red until someone decides whether a first install needs it;
an entry in either omission list that upstream no longer has fails too, so the lists cannot rot into permanent exemptions.

It found two stale entries on its first run (TOTP_ISSUER and MODULES are commented suggestions upstream, not keys). Wired into verify and CI, using the same REGISTRY_TOKEN mapping as the facts check.

What the live deployment disproved

The D36 rig was the quickstart itself — the exact two files from this page, against the published image — so one run proved the install page and produced the detail the admin pages needed. Three findings, all now documented, none of which any check could have caught:

The documented Compose deploy does not boot. SECRET_ENC_KEY is required in production (utils/secretBox.js throws at require time, so the container crash-loops before it listens) and is missing from website's root .env.example — the file Compose actually reads. It is present in server/.env.example, which is why local development 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 (installer main:src/sidecar.rs), and INSTALL.md §5 repeats it. Since the module cutover the screen is /admin/uo/link, labelled Shard (uo-link). Both the binary and the guide are stale.
The admin "Restart the server" 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 on the install page rather than left as boilerplate.

Findings 1 and 2 are defects in other repositories and are deliberately not fixed here — see the question below.

The defect only a look found — three phases running

The .env block's prose promised every highlighted line must be changed, while mark given the variable names highlighted the names alone and left the values a reader must replace unmarked. Every check passed on a page that was wrong about its own highlighting. Marking the whole KEY=value string fixed it. Same lesson as phase 4 (cascade), phase 5 (literal backticks) and phase 6 (the card void).

Verification

npm run verify green: 890 internal links resolve, 52 repository links point at a branch, 19 facts agree with their authorities, 59 quickstart checks pass against website main, astro check 0 errors / 0 warnings.

For the org lead

Findings 1 and 2 are real bugs elsewhere (website's .env.example; the installer binary plus docs/installer/INSTALL.md). Both are outside this phase's scope, so nothing was widened to fix them — say the word and they are two small PRs.

AI-assisted: written with Claude Code (Opus 5).

🤖 Generated with Claude Code

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. PLAN.md calls the installation path "the priority of the whole project". ## The four decisions (D34–D37) Taken before anything was written; recorded in PLAN.md §10, *How phase 7 built the documentation journey*. The count of record is now **thirty-seven**. | # | Decision | |---|---| | **D34** | One PR for all twenty pages, rather than splitting Getting started from Administration | | **D35** | The install page is **self-contained** — it prints a complete Compose file and `.env`, checked against upstream rather than trusted | | **D36** | **Every Administration screen was walked on a real deployment** before it was described | | **D37** | A **thirteenth** Administration page, *Content*, so every admin nav row has a home | ## D35 and the check it needs `/docs/getting-started/install-the-site/` prints both files verbatim, which is the one place this site knowingly copies another repo's file — exactly what §1 warns about. So it is checked, not trusted: `scripts/checkQuickstart.mjs` re-reads `website` `main:docker-compose.yml` and `main:.env.example` over the Gitea API and fails the build on any disagreement, **in both directions**: - every value the quickstart states must match upstream's; - every service and variable upstream has must be **either included or listed as deliberately omitted, with a reason** — so a new variable in `.env.example` turns this repo red until someone decides whether a first install needs it; - an entry in either omission list that upstream no longer has fails too, so the lists cannot rot into permanent exemptions. It found two stale entries on its first run (`TOTP_ISSUER` and `MODULES` are commented *suggestions* upstream, not keys). Wired into `verify` and CI, using the same `REGISTRY_TOKEN` mapping as the facts check. ## What the live deployment disproved The D36 rig was the quickstart itself — the exact two files from this page, against the published image — so one run proved the install page and produced the detail the admin pages needed. Three findings, all now documented, **none of which any check could have caught**: 1. **The documented Compose deploy does not boot.** `SECRET_ENC_KEY` is required in production (`utils/secretBox.js` throws at require time, so the container crash-loops before it listens) and is **missing from website's root `.env.example`** — the file Compose actually reads. It is present in `server/.env.example`, which is why local development never hits it. The quickstart carries it, declared as an upstream omission so the check fails the day it is fixed. 2. **The installer points operators at a screen that no longer exists.** It prints `<site>/admin/shard` (`installer` `main:src/sidecar.rs`), and `INSTALL.md` §5 repeats it. Since the module cutover the screen is **`/admin/uo/link`**, labelled *Shard (uo-link)*. Both the binary and the guide are stale. 3. **The admin "Restart the server" 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 on the install page rather than left as boilerplate. Findings 1 and 2 are defects in **other repositories** and are deliberately not fixed here — see the question below. ## The defect only a look found — three phases running The `.env` block's prose promised *every highlighted line must be changed*, while `mark` given the variable **names** highlighted the names alone and left the values a reader must replace unmarked. Every check passed on a page that was wrong about its own highlighting. Marking the whole `KEY=value` string fixed it. Same lesson as phase 4 (cascade), phase 5 (literal backticks) and phase 6 (the card void). ## Verification `npm run verify` green: **890** internal links resolve, **52** repository links point at a branch, **19** facts agree with their authorities, **59** quickstart checks pass against `website main`, `astro check` 0 errors / 0 warnings. ## For the org lead Findings 1 and 2 are real bugs elsewhere (`website`'s `.env.example`; the `installer` binary plus `docs/installer/INSTALL.md`). Both are outside this phase's scope, so nothing was widened to fix them — say the word and they are two small PRs. --- AI-assisted: written with Claude Code (Opus 5). 🤖 Generated with [Claude Code](https://claude.com/claude-code)

wtclaude added 1 commit 2026-08-24 13:35:46 +00:00

docs(journey): phase 7 — the installation path and administration

PR checks / checks (pull_request) Successful in 9m25s

Details

f499f2b72b

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>

whitlocktech merged commit bcb633403f into main

2026-08-24 15:24:20 +00:00

whitlocktech deleted branch feat/phase-7-docs

2026-08-24 15:24:20 +00:00

whitlocktech referenced this issue from a commit

2026-08-24 15:24:22 +00:00

Merge pull request 'docs(journey): phase 7 — the installation path and administration' (#10) from feat/phase-7-docs into main

wtclaude referenced this issue from a commit

2026-08-24 16:39:46 +00:00

fix(docs): clear the quickstart drift the upstream fixes caused

wtclaude referenced this pull request

2026-08-24 16:40:08 +00:00