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

wtclaude · 2026-08-24T16:40:08Z

wtclaude commented

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

main is currently red, by design. This is the follow-up phase 7 promised — plus the version bump that followed from fixing the release that was blocking it.

The check did its job

All three defects phase 7 found are now fixed and merged upstream — website#163, installer#22, docs#174.

website#163 added SECRET_ENC_KEY to the root .env.example, and checkQuickstart went red here on the next run:

✗ env SECRET_ENC_KEY
    is now in website main:.env.example — remove it from notInUpstreamEnvExample,
    and re-read the prose that describes it as missing

That is exactly what the declaration was built to do — it fails the moment a declared key appears upstream, so a note calling something an upstream omission cannot outlive the defect it describes. The entry is deleted; notInUpstreamEnvExample is now empty. The export stays (like PLANNED_ROUTES before it) so the next divergence gets an entry rather than passing quietly, and the comment records what it caught and why it was safe to delete.

Nothing else moved: SECRET_ENC_KEY is fill: true, so its placeholder was never value-compared, and the two variables the install page tells you to read twice are unchanged.

A fourth finding: installer's release pipeline left an orphan tag

Writing the stale-path note, I went to say "fixed in v0.1.1" and found there was no such release.

installer run 75 built everything and then failed at the last step: steps 1–12 green including Push the release tag, then Create Gitea release and upload assets took a 500 from POST /releases and exited 22 — one second after the tag push. So the repo had an orphan tag v0.1.1 at 9cc1099, no release, no binaries, and installer#22's handoff fix had reached nobody.

Re-running the workflow published it, taking the orphan-tag recovery path the plan step already has, with all four assets unchanged. So the 500 was a race with the tag push, not structural — Gitea had not finished processing the pushed tag when the release POST arrived.

Two things are still worth hardening in installer (not here, and not in this PR): the step uses curl -sSf, which discards the response body, which is the only reason the cause had to be inferred rather than read; and the POST has no retry against exactly this race. Both are one-line-ish changes to release.yml. Note that file is link's release.yml retargeted, so the same two gaps likely exist there and in servuo-plugins.

The stale-path note, pinned to a version

The Aside on Connect a game server said the installer "prints an older path", open-endedly. Now:

v0.1.0 prints the old path, v0.1.1 prints the real one. That phrasing stays true however many releases follow — the first draft of this said "v0.1.0 is still the current download", which my own re-run made false within the hour.
It says why the old path is worse than a 404 — the SPA has no route for it, so it redirects to the dashboard, the link looks like it worked, and the four values the operator was just told to paste have nowhere to go.

The version bump, which the checks demanded

Publishing v0.1.1 moved the platform under this branch, and checkFacts went red:

FAIL  release installer
      platform.json says : v0.1.0
      installer releases/latest says : v0.1.1

platform.json and PLAN.md's version table move to v0.1.1, and every page quoting the value was re-read, per the check's own instruction.

Also recovers a lost commit

084ee0b was pushed to feat/phase-7-docs after PR #10 had already merged f499f2b, so the PR page showed it as the head ref but the merge commit never contained it. Its content is folded in here, revised — it described the installer fixes as "open", and they are merged and released.

Verification

npm run verify green end to end: 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, both test suites pass.

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

🤖 Generated with Claude Code

`main` is currently **red**, by design. This is the follow-up phase 7 promised — plus the version bump that followed from fixing the release that was blocking it. ## The check did its job All three defects phase 7 found are now fixed and merged upstream — **website#163**, **installer#22**, **docs#174**. `website#163` added `SECRET_ENC_KEY` to the root `.env.example`, and `checkQuickstart` went red here on the next run: ``` ✗ env SECRET_ENC_KEY is now in website main:.env.example — remove it from notInUpstreamEnvExample, and re-read the prose that describes it as missing ``` That is exactly what the declaration was built to do — it fails the moment a declared key appears upstream, so a note calling something an upstream omission **cannot outlive the defect it describes**. The entry is deleted; `notInUpstreamEnvExample` is now empty. The export stays (like `PLANNED_ROUTES` before it) so the next divergence gets an entry rather than passing quietly, and the comment records what it caught and why it was safe to delete. Nothing else moved: `SECRET_ENC_KEY` is `fill: true`, so its placeholder was never value-compared, and the two variables the install page tells you to read twice are unchanged. ## A fourth finding: installer's release pipeline left an orphan tag Writing the stale-path note, I went to say "fixed in v0.1.1" and found there was no such release. `installer` run 75 **built everything and then failed at the last step**: steps 1–12 green including *Push the release tag*, then *Create Gitea release and upload assets* took a `500` from `POST /releases` and exited 22 — one second after the tag push. So the repo had an orphan tag `v0.1.1` at `9cc1099`, no release, no binaries, and installer#22's handoff fix had reached nobody. **Re-running the workflow published it**, taking the orphan-tag recovery path the plan step already has, with all four assets unchanged. So the 500 was a **race with the tag push**, not structural — Gitea had not finished processing the pushed tag when the release POST arrived. Two things are still worth hardening in `installer` (not here, and not in this PR): the step uses `curl -sSf`, which **discards the response body**, which is the only reason the cause had to be inferred rather than read; and the POST has no retry against exactly this race. Both are one-line-ish changes to `release.yml`. Note that file is `link`'s `release.yml` retargeted, so the same two gaps likely exist there and in `servuo-plugins`. ## The stale-path note, pinned to a version The `Aside` on *Connect a game server* said the installer "prints an older path", open-endedly. Now: - **v0.1.0 prints the old path, v0.1.1 prints the real one.** That phrasing stays true however many releases follow — the first draft of this said "v0.1.0 is still the current download", which my own re-run made false within the hour. - It says **why the old path is worse than a 404** — the SPA has no route for it, so it redirects to the dashboard, the link looks like it worked, and the four values the operator was just told to paste have nowhere to go. ## The version bump, which the checks demanded Publishing v0.1.1 moved the platform under this branch, and `checkFacts` went red: ``` FAIL release installer platform.json says : v0.1.0 installer releases/latest says : v0.1.1 ``` `platform.json` and PLAN.md's version table move to **v0.1.1**, and every page quoting the value was re-read, per the check's own instruction. ## Also recovers a lost commit `084ee0b` was pushed to `feat/phase-7-docs` *after* PR #10 had already merged `f499f2b`, so the PR page showed it as the head ref but the merge commit never contained it. Its content is folded in here, revised — it described the installer fixes as "open", and they are merged and released. ## Verification `npm run verify` green end to end: **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, both test suites pass. --- AI-assisted: written with Claude Code (Opus 5). 🤖 Generated with [Claude Code](https://claude.com/claude-code)

wtclaude added 1 commit 2026-08-24 16:40:09 +00:00

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

PR checks / checks (pull_request) Successful in 1m1s

Details

a993b872ac

The three defects phase 7 found are fixed and merged: website#163
(SECRET_ENC_KEY missing from the root .env.example, plus BOT_INTERNAL_KEY in
the README's "set at least" list) and installer#22 + docs#174 (the handoff
printing /admin/shard).

website#163 turned checkQuickstart red here, which is precisely what the
declaration was built to do -- it fails the moment a declared key appears
upstream, so the note describing the omission cannot outlive the defect. The
SECRET_ENC_KEY entry is deleted and notInUpstreamEnvExample is now empty; the
export stays so the next divergence gets an entry rather than passing quietly.

The stale-path Aside on Connect a game server is pinned to v0.1.0 rather than
calling the installer permanently wrong, and now says WHY the old path is worse
than a 404: the SPA has no route for it, so it redirects to the dashboard and
the link looks like it worked.

v0.1.0 is still the current download, and not only because releases lag. The
release run for installer#22 built every artifact and pushed tag v0.1.1, then
took a 500 creating the release -- so the tag is orphaned and no binaries were
published. Raised on installer; nothing is worked around here.

This also recovers 084ee0b, which was pushed to feat/phase-7-docs after PR #10
had already merged f499f2b, and so never reached main.

Co-Authored-By: Claude <noreply@anthropic.com>

wtclaude added 1 commit 2026-08-24 16:50:43 +00:00

fix(facts): installer v0.1.1 is released, so the note names a version

PR checks / checks (pull_request) Successful in 9m22s

Details

e8cb6061fe

Recovering installer's orphan tag published v0.1.1, which moved the platform
under this branch and turned checkFacts red -- the check working exactly as it
should, since a version this site quotes had changed.

  FAIL  release installer
        platform.json says : v0.1.0
        installer releases/latest says : v0.1.1

The 500 that orphaned the tag was a race with the tag push one second earlier,
not a structural failure: re-running the workflow took the built-in orphan-tag
recovery path and published all four assets unchanged.

So the stale-path Aside stops saying "v0.1.0 is still the current download",
which is no longer true, and says the durable thing instead -- v0.1.0 prints
the old path, v0.1.1 prints the real one -- which stays correct however many
releases follow. platform.json and the PLAN.md version table move to v0.1.1,
and the phase 7 findings record the pipeline defect as a fourth finding.

Co-Authored-By: Claude <noreply@anthropic.com>

wtclaude referenced this pull request

2026-08-24 17:18:08 +00:00

docs(builder): phase 8 — modules, architecture and reference #12

whitlocktech approved these changes 2026-08-24 17:32:45 +00:00

whitlocktech merged commit b3cb6bf1eb into main

2026-08-24 17:32:51 +00:00

whitlocktech referenced this issue from a commit

2026-08-24 17:32:52 +00:00

Merge pull request 'fix(docs): clear the quickstart drift the upstream fixes caused' (#11) from fix/quickstart-drift-and-installer-note into main

whitlocktech deleted branch fix/quickstart-drift-and-installer-note

2026-08-24 17:32:52 +00:00

Sign in to join this conversation.