docs(installer): record Phase 4 — doctor, update and uninstall as built #93

wtclaude · 2026-08-05T08:02:11Z

wtclaude commented

2026-08-05 08:02:11 +00:00

What & why

The docs half of installer#7, which implements Phase 4. Two of these edits are corrections rather than records: the plan and the guide had drifted apart in ways the implementation made impossible to ignore.

`installer/PLAN.md`

Status header — Phases 1–4 are on edge; the edge → main cutover now cuts a binary that does everything INSTALL.md describes, with Phase 5 being packaging polish rather than capability.
Phase 4 "as built" — why update is the install pipeline in a different mode rather than a second implementation; why it neither reprints the token nor stays quiet about a protocol change; the tier's scope under update (re-resolve what was applied without re-asking, name what is new); how doctor asks the binary under the environment the service pins; the exit-code rule, and why a stopped shard is a ⚠ while a running one that has not dialed in is a ✗.
§5's uninstall table — the cached patch set and patches/originals/ move from Removed to Kept. The report that command prints tells the operator to diff against those originals, so deleting them made the advice impossible to follow within one command's own output. --purge removes them.

`installer/INSTALL.md`

§2 — exit codes stated (doctor and uninstall use 1 for a completed run that found something wrong); --patches now applies to update; --yes means yes on uninstall; --purge covers the patch cache.
§7 doctor — the real row set, what ✓/⚠/✗ mean, and that it writes nothing and is safe to run with the shard up (which is the only state in which the last row can be ✓).
§7 update — it updates the tree install.json names, needs the shard stopped, does not reprint the token, calls out a protocol change, and what it does and does not do with the patch tier.
§7 uninstall — what survives, that files edited since deployment are flagged in the listing, the confirmation's default, and where the report file lands.

How it was tested

Prose only. Every claim was checked against the behaviour in installer#7 rather than against the design: the doctor sample is the shape of a real run's output, the exit codes and marks are what the code returns, and the uninstall table matches what a --purge and a non---purge run actually leave on disk (both exercised on this machine).

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)

No AI tools were used to produce this contribution.
AI tools were used. Tool(s): Claude Code (Opus 5). 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 The docs half of **installer#7**, which implements Phase 4. Two of these edits are corrections rather than records: the plan and the guide had drifted apart in ways the implementation made impossible to ignore. ### `installer/PLAN.md` - **Status header** — Phases 1–4 are on `edge`; the `edge → main` cutover now cuts a binary that does everything `INSTALL.md` describes, with Phase 5 being packaging polish rather than capability. - **Phase 4 "as built"** — why `update` is the `install` pipeline in a different mode rather than a second implementation; why it neither reprints the token nor stays quiet about a protocol change; the tier's scope under `update` (re-resolve what was applied without re-asking, name what is new); how `doctor` asks the binary under the environment the *service* pins; the exit-code rule, and why a stopped shard is a `⚠` while a running one that has not dialed in is a `✗`. - **§5's uninstall table** — the cached patch set and `patches/originals/` move from **Removed** to **Kept**. The report that command prints tells the operator to diff against those originals, so deleting them made the advice impossible to follow within one command's own output. `--purge` removes them. ### `installer/INSTALL.md` - **§2** — exit codes stated (`doctor` and `uninstall` use `1` for a *completed* run that found something wrong); `--patches` now applies to `update`; `--yes` means yes on `uninstall`; `--purge` covers the patch cache. - **§7 `doctor`** — the real row set, what `✓`/`⚠`/`✗` mean, and that it writes nothing and is safe to run with the shard up (which is the only state in which the last row can be `✓`). - **§7 `update`** — it updates the tree `install.json` names, needs the shard stopped, does not reprint the token, calls out a protocol change, and what it does and does not do with the patch tier. - **§7 `uninstall`** — what survives, that files edited since deployment are flagged in the listing, the confirmation's default, and where the report file lands. ## How it was tested Prose only. Every claim was checked against the behaviour in installer#7 rather than against the design: the doctor sample is the shape of a real run's output, the exit codes and marks are what the code returns, and the uninstall table matches what a `--purge` and a non-`--purge` run actually leave on disk (both exercised on this machine). ## 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) - [ ] No AI tools were used to produce this contribution. - [x] AI tools were used. Tool(s): `Claude Code (Opus 5)`. 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-05 08:02:13 +00:00

docs(installer): record Phase 4 — doctor, update and uninstall as built ecef87f120

The installer crate now implements the whole command surface INSTALL.md
published before the binary existed, so this records what Phase 4 turned
out to be and corrects two places where the plan and the guide had drifted
apart.

PLAN.md
  - Status header: Phases 1–4 are on `edge`; the edge → main cutover now
    cuts a binary that does everything INSTALL.md describes, with Phase 5
    being packaging polish rather than capability.
  - A Phase 4 "as built" section: why `update` is the install pipeline in
    a different mode rather than a second implementation, why it neither
    reprints the token nor stays quiet about a protocol change, the tier's
    scope under `update` (re-resolve what was applied, without re-asking;
    name what is new), how `doctor` asks the binary the way the service
    does, the exit-code rule and why a stopped shard is a ⚠ while a
    running one that has not dialed in is a ✗.
  - §5's uninstall table: the cached patch set and patches/originals/ move
    from "removed" to "kept". The report that command prints tells the
    operator to diff against those originals — deleting them made the
    advice impossible to follow within one command's output. `--purge`
    removes them.

INSTALL.md
  - §2: exit codes stated (`doctor` and `uninstall` use 1 for a completed
    run that found something wrong), `--patches` now applies to `update`,
    `--yes` means yes on `uninstall`, `--purge` covers the patch cache.
  - §7 doctor: the real row set, what ✓/⚠/✗ mean, that it writes nothing
    and is safe to run with the shard up.
  - §7 update: it updates the tree install.json names, needs the shard
    stopped, does not reprint the token, calls out a protocol change, and
    what it does and does not do with the patch tier.
  - §7 uninstall: what survives, that edited files are flagged in the
    listing, the confirmation's default, and where the report file lands.

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

whitlocktech merged commit 1dc6084bf7 into main

2026-08-05 08:49:17 +00:00

whitlocktech deleted branch docs/installer-phase4

2026-08-05 08:49:18 +00:00

whitlocktech referenced this issue from a commit

2026-08-05 08:49:19 +00:00

Merge pull request 'docs(installer): record Phase 4 — doctor, update and uninstall as built' (#93) from docs/installer-phase4 into main

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/docs#93