docs(installer): lead with the installer now that it is released #102

wtclaude · 2026-08-07T21:06:43Z

wtclaude commented

2026-08-07 21:06:43 +00:00

What & why

installer v0.1.0 shipped on 2026-08-07 (release, cutover installer#17), publishing linux-x86_64, linux-aarch64, windows-x86_64.exe and SHA256SUMS. Every operator-facing doc still said the opposite. installer#17's own body called this out as the follow-up: "Makes INSTALL.md's status banner wrong — it still says the binary is unreleased."

The org lead's call on the by-hand path: the installer is the preferred, easy-mode path; hand deployment stays supported, including on the dev side. Nothing is deleted here — Appendix A is reframed, not retired.

`installer/INSTALL.md`

Replaces the pre-release banner ("the installer binary is not released yet… Phases 1 to 3… doctor, update and uninstall are still missing" — all four of those are released) with a short "start at §1" opener.
Appendix A is reframed as supported, not deprecated: for a host that cannot run the binary, an operator who wants to place every file themselves, and development from a working tree — plus its existing role as the reference for what the installer does under the hood.

`installer/PLAN.md`

Status → Shipped, with both cutover gates recorded as met, including the Windows SCM half: sc start failed 1053 on its first real run, needed a sidecar fix (link#29, v1.2.0), then passed 13/13. Worth keeping in the record — it is exactly the class of bug the "verify on a real host" gate existed to catch.
Phase 5 table: arm64 and backup-before-upgrade → merged; §5.4 ("documentation the release layout invalidates", previously Pending) → done, which is this PR.
The Phase 0 note that Appendix A "is useful before the installer exists" now says it outlives it.

`README.md`

Index entry for INSTALL.md said "Includes the by-hand path, which works today" — now leads with the installer, and a "Setting up a shard?" pointer sits under the layout block.

`link/link-README.md`

Marked as the historical snapshot it is (from before the bridge split into link + servuo-plugins) and pointed at INSTALL.md. It was presented in the index without a date and told readers to deploy with deploy.ps1.

Companion PRs, same branch name in each repo: installer, link, servuo-plugins, website.

How it was tested

Docs-only. Verified against reality rather than assumed:

Release v0.1.0 and its four assets confirmed via the Gitea API — they match what INSTALL.md §1 already documents, so the download section needed no change.
Every anchor introduced or relied on checked against its heading (#1-download-and-verify, #7-day-two, #appendix-a--installing-by-hand, #a2-deploy-the-plugin-overlay, #a3-install-the-sidecar).
INSTALL.md already documented --no-backup, the backup directories and the aarch64 download line, so §5.4's other two items were already satisfied; only the status content was stale.

Checklist

I have read CONTRIBUTING.md.
The change builds and existing tests/checks pass locally.
I have added or updated tests/docs where it makes sense.
My commits are reasonably scoped with clear messages.

AI-assisted contributions (required)

AI tools were used. Tool(s): Claude Code. I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a Co-Authored-By trailer.

License

I agree that my contribution is licensed under this project's license (GNU GPL v3.0 or later), and I have the right to contribute it.

## What & why `installer` **v0.1.0** shipped on 2026-08-07 ([release](https://gitea.whitlocktech.com/RunicGateway/installer/releases/tag/v0.1.0), cutover [installer#17](https://gitea.whitlocktech.com/RunicGateway/installer/pulls/17)), publishing `linux-x86_64`, `linux-aarch64`, `windows-x86_64.exe` and `SHA256SUMS`. Every operator-facing doc still said the opposite. installer#17's own body called this out as the follow-up: *"Makes INSTALL.md's status banner wrong — it still says the binary is unreleased."* The org lead's call on the by-hand path: **the installer is the preferred, easy-mode path; hand deployment stays supported, including on the dev side.** Nothing is deleted here — Appendix A is reframed, not retired. ### `installer/INSTALL.md` - Replaces the pre-release banner (*"the installer binary is not released yet… Phases 1 to 3… `doctor`, `update` and `uninstall` are still missing"* — all four of those are released) with a short "start at §1" opener. - Appendix A is reframed as **supported, not deprecated**: for a host that cannot run the binary, an operator who wants to place every file themselves, and development from a working tree — plus its existing role as the reference for what the installer does under the hood. ### `installer/PLAN.md` - Status → **Shipped**, with both cutover gates recorded as met, including the Windows SCM half: `sc start` failed **1053** on its first real run, needed a sidecar fix ([link#29](https://gitea.whitlocktech.com/RunicGateway/link/pulls/29), v1.2.0), then passed 13/13. Worth keeping in the record — it is exactly the class of bug the "verify on a real host" gate existed to catch. - Phase 5 table: arm64 and backup-before-upgrade → merged; §5.4 (*"documentation the release layout invalidates"*, previously **Pending**) → done, which is this PR. - The Phase 0 note that Appendix A "is useful before the installer exists" now says it outlives it. ### `README.md` - Index entry for INSTALL.md said *"Includes the by-hand path, which works today"* — now leads with the installer, and a "Setting up a shard?" pointer sits under the layout block. ### `link/link-README.md` - Marked as the **historical snapshot** it is (from before the bridge split into `link` + `servuo-plugins`) and pointed at INSTALL.md. It was presented in the index without a date and told readers to deploy with `deploy.ps1`. Companion PRs, same branch name in each repo: installer, link, servuo-plugins, website. ## How it was tested Docs-only. Verified against reality rather than assumed: - Release **v0.1.0** and its four assets confirmed via the Gitea API — they match what INSTALL.md §1 already documents, so the download section needed no change. - Every anchor introduced or relied on checked against its heading (`#1-download-and-verify`, `#7-day-two`, `#appendix-a--installing-by-hand`, `#a2-deploy-the-plugin-overlay`, `#a3-install-the-sidecar`). - INSTALL.md already documented `--no-backup`, the backup directories and the `aarch64` download line, so §5.4's other two items were already satisfied; only the status content was stale. ## Checklist - [x] I have read [CONTRIBUTING.md](CONTRIBUTING.md). - [x] The change builds and existing tests/checks pass locally. - [x] I have added or updated tests/docs where it makes sense. - [x] My commits are reasonably scoped with clear messages. ## AI-assisted contributions (required) - [x] AI tools were used. Tool(s): `Claude Code`. I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a `Co-Authored-By` trailer. ## License - [x] I agree that my contribution is licensed under this project's license (**GNU GPL v3.0 or later**), and I have the right to contribute it.

wtclaude added 1 commit 2026-08-07 21:06:45 +00:00

docs(installer): lead with the installer now that it is released 5197c2c281

v0.1.0 shipped on 2026-08-07, so every doc that said "not released yet"
was wrong the moment the cutover merged.

- INSTALL.md: replace the pre-release status banner. The installer is the
  path the guide leads with; Appendix A is reframed as supported-not-
  deprecated, for hosts that cannot run the binary, operators who want to
  place files themselves, and development from a working tree.
- PLAN.md: status is Shipped, both cutover gates recorded as met (incl.
  the Windows 1053 handshake bug the real SCM run found), Phase 5 table
  and 5.4 closed out.
- README.md: point anyone setting up a shard at INSTALL.md first.
- link/link-README.md: mark the pre-split snapshot as historical, so its
  deploy.ps1 instructions stop reading as the setup path.

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

whitlocktech approved these changes 2026-08-07 21:34:19 +00:00

whitlocktech merged commit 6d25279b32 into main

2026-08-07 21:34:28 +00:00

whitlocktech deleted branch docs/installer-first-setup

2026-08-07 21:34:28 +00:00

whitlocktech referenced this issue from a commit

2026-08-07 21:34:29 +00:00

Merge pull request 'docs(installer): lead with the installer now that it is released' (#102) from docs/installer-first-setup into main

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/docs#102