docs(installer): record Phase 0 progress and the overlay manifest #82

wtclaude · 2026-08-04T14:30:34Z

wtclaude commented

2026-08-04 14:30:34 +00:00

What & why

Companion to servuo-plugins#7 (Phase 0 item 1) and installer#1 (repo bootstrap). Records what actually landed, and corrects the parts of the plan that doing the work proved wrong or stale.

Progress

A Phase 0 status table at the top, so the plan states where it is instead of making a reader reconstruct it from PR links.
Phase 0 item 1 (§5) now records the release workflow as built, including its three deviations from link's copy — structural gates instead of build gates, no bump commit and therefore no push to main, and overlay.toml as the home for the declared protocol version. Plus the fixed tarball prefix and the reason for it: a versioned prefix would make the installer parse the version it's trying to read.
New §7.0 documents the overlay manifest as generated, and states plainly the two things about it that carry weight beyond documentation:
- protocol is hand-maintained and has to be — nothing in CI can derive it, which is exactly why §7.1's gate 1 has something to compare in the first place.
- files is what lets doctor distinguish "the operator edited a deployed file" from "the overlay moved on".

Corrections

§	Change
2.6	The plugin's protocol version now has a home (`overlay.toml`); `servuo-plugins` now has a release workflow.
7.2	The dispatch step into the bundle CI is deliberately deferred to Phase 0 item 3, with the reason.
7.4	No longer "open risk" — the v3 cutover merged. The rule it motivated (never hardcode a protocol version) is restated as permanent, not as a workaround for a mid-flight cutover. That distinction matters at the next bump.
8	Open question 4 (branch targeting) resolved: servuo-plugins#6 merged, `main` == `edge`, everything targets `main`.

One factual fix worth calling out

§3, §5 and §7.1 gave uo-link example versions of v3.x.y / 3.0.1 — conflating the release version with the protocol version. link is actually at v0.3.0; the two are independent, and the bundle names release versions. An example implying they track each other is actively misleading for the one document whose job is explaining how compatibility is resolved. Now uses real values throughout (link 0.3.0, overlay 0.1.0, 30 overlay files).

How it was tested

Documentation only. Cross-checked every claim against the repos rather than against the plan's own prose: link's actual tags (v0.1.0/v0.2.0/v0.3.0), PROTOCOL_VERSION = 3 in link/sidecar/src/main.rs, the merged state of servuo-plugins#6, and the real overlay file count and manifest output from a local run of the new release workflow.

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 (Claude Opus 5). Every change has been reviewed and is understood. 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 Companion to [servuo-plugins#7](https://gitea.whitlocktech.com/RunicGateway/servuo-plugins/pulls/7) (Phase 0 item 1) and [installer#1](https://gitea.whitlocktech.com/RunicGateway/installer/pulls/1) (repo bootstrap). Records what actually landed, and corrects the parts of the plan that doing the work proved wrong or stale. ### Progress - **A Phase 0 status table at the top**, so the plan states where it is instead of making a reader reconstruct it from PR links. - **Phase 0 item 1 (§5)** now records the release workflow *as built*, including its three deviations from `link`'s copy — structural gates instead of build gates, no bump commit and therefore no push to `main`, and `overlay.toml` as the home for the declared protocol version. Plus the fixed tarball prefix and the reason for it: a versioned prefix would make the installer parse the version it's trying to read. - **New §7.0 documents the overlay manifest as generated**, and states plainly the two things about it that carry weight beyond documentation: - `protocol` is hand-maintained **and has to be** — nothing in CI can derive it, which is exactly why §7.1's gate 1 has something to compare in the first place. - `files` is what lets `doctor` distinguish *"the operator edited a deployed file"* from *"the overlay moved on"*. ### Corrections | § | Change | |---|---| | 2.6 | The plugin's protocol version now has a home (`overlay.toml`); `servuo-plugins` now has a release workflow. | | 7.2 | The dispatch step into the bundle CI is deliberately deferred to Phase 0 item 3, with the reason. | | 7.4 | No longer "open risk" — the v3 cutover merged. The rule it motivated (never hardcode a protocol version) is restated as **permanent**, not as a workaround for a mid-flight cutover. That distinction matters at the *next* bump. | | 8 | Open question 4 (branch targeting) resolved: servuo-plugins#6 merged, `main` == `edge`, everything targets `main`. | ### One factual fix worth calling out §3, §5 and §7.1 gave `uo-link` example versions of `v3.x.y` / `3.0.1` — conflating the **release** version with the **protocol** version. `link` is actually at **v0.3.0**; the two are independent, and the bundle names release versions. An example implying they track each other is actively misleading for the one document whose job is explaining how compatibility is resolved. Now uses real values throughout (link `0.3.0`, overlay `0.1.0`, 30 overlay files). ## How it was tested Documentation only. Cross-checked every claim against the repos rather than against the plan's own prose: `link`'s actual tags (`v0.1.0`/`v0.2.0`/`v0.3.0`), `PROTOCOL_VERSION = 3` in `link/sidecar/src/main.rs`, the merged state of servuo-plugins#6, and the real overlay file count and manifest output from a local run of the new release workflow. ## 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 (Claude Opus 5)`. Every change has been reviewed and is understood. 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-04 14:30:36 +00:00

docs(installer): record Phase 0 progress and the overlay manifest f0975df598

Tracks what actually landed while starting the installer plan, and corrects
the parts of the plan that the work proved wrong or stale.

Progress:

  A Phase 0 status table at the top, so the plan says where it is rather
  than needing a reader to reconstruct it from PR links.

  Phase 0 item 1 (§5) now records the release workflow as built, including
  its three deviations from link's copy — structural gates instead of build
  gates, no bump commit and therefore no push to main, and overlay.toml as
  the home for the declared protocol version. Plus the fixed tarball prefix
  and why: the installer would otherwise have to parse the version it is
  trying to read.

New §7.0 documents the overlay manifest as generated, and states plainly the
two things about it that carry weight: `protocol` is hand-maintained and has
to be (nothing in CI can derive it, which is exactly why §7.1's gate 1 has
something to compare), and `files` is what lets `doctor` distinguish
"operator edited a deployed file" from "the overlay moved on".

Corrections:

  §2.6 the plugin's protocol version now has a home (overlay.toml), and
        servuo-plugins now has a release workflow.
  §7.2  the dispatch step is deliberately deferred to Phase 0 item 3.
  §7.4  no longer "open risk" — the v3 cutover merged. The rule it motivated
        (never hardcode a protocol version) is restated as permanent rather
        than as a workaround for a mid-flight cutover.
  §8    open question 4 (branch targeting) resolved: servuo-plugins#6 merged,
        main == edge, everything targets main.

Version examples in §3, §5 and §7.1 said uo-link v3.x.y / 3.0.1, conflating
the release version with the protocol version. link is actually at v0.3.0 —
the two are independent, and the bundle names release versions, so an example
implying they track each other is actively misleading. Now uses the real
values (link 0.3.0, overlay 0.1.0, 30 overlay files).

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

whitlocktech merged commit e1608bb280 into main

2026-08-04 15:29:19 +00:00

whitlocktech deleted branch docs/installer-phase0

2026-08-04 15:29:20 +00:00

whitlocktech referenced this issue from a commit

2026-08-04 15:29:20 +00:00

Merge pull request 'docs(installer): record Phase 0 progress and the overlay manifest' (#82) from docs/installer-phase0 into main

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/docs#82