From 32e17246a22859d2e11e650fc29f9865f7bb1077 Mon Sep 17 00:00:00 2001 From: codex-bot-andresmgsl Date: Mon, 20 Jul 2026 17:30:11 +0000 Subject: [PATCH 1/3] docs: align README quick start with main --- README.md | 16 ++--- .../2026-07-20-readme-install-channel.md | 69 +++++++++++++++++++ ...026-07-20-readme-install-channel-design.md | 36 ++++++++++ test/cli.sh | 4 ++ 4 files changed, 114 insertions(+), 11 deletions(-) create mode 100644 docs/superpowers/plans/2026-07-20-readme-install-channel.md create mode 100644 docs/superpowers/specs/2026-07-20-readme-install-channel-design.md diff --git a/README.md b/README.md index 0521698..2dcdc33 100644 --- a/README.md +++ b/README.md @@ -15,13 +15,13 @@ takes arguments, does its work, and stores no credential, ever. ## Install ```sh -curl -fsSL https://raw.githubusercontent.com/heavy-duty/rig/main/install.sh | bash +curl -fsSL https://raw.githubusercontent.com/heavy-duty/rig/main/install.sh | RIG_REF=main bash ``` -That installs the **latest release**: the installer resolves the newest tag -by following GitHub's `releases/latest` redirect (no API, no token) and -downloads that tag's source tarball — which, for a pure-bash tree, *is* the -package. Three channels from the same script; `RIG_REF` picks: +This README tracks `main`, so the quick start installs that same development +tree. To install a stable version instead, use the latest-release or pinned-tag +channel and follow the documentation shipped with that version. Three channels +come from the same script; `RIG_REF` picks: ```sh curl -fsSL .../install.sh | bash # the latest release @@ -32,12 +32,6 @@ curl -fsSL .../install.sh | RIG_REF=main bash # the development tree A tag outranks a branch of the same name (the pin must win); anything that is not a tag falls back to `refs/heads/`. -> **Transitional, until 0.1.0 is cut** (right after rig#32 lands): rig has -> no GitHub release yet, so the default channel has nothing to resolve — -> it **fails loudly** naming `RIG_REF=main` as the way to install today, -> and never silently falls back to main. Once 0.1.0 exists, the plain -> `curl | bash` above is the normal path. - The layout, under the install root (`~/.local/share/rig`): ``` diff --git a/docs/superpowers/plans/2026-07-20-readme-install-channel.md b/docs/superpowers/plans/2026-07-20-readme-install-channel.md new file mode 100644 index 0000000..e5f076f --- /dev/null +++ b/docs/superpowers/plans/2026-07-20-readme-install-channel.md @@ -0,0 +1,69 @@ +# README Install-Channel Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Ensure the `main` README installs the same development tree whose CLI it documents. + +**Architecture:** Keep installer channel behavior unchanged and correct the documentation entry point. Add one source-level regression assertion to the existing dependency-free CLI suite. + +**Tech Stack:** Bash, Markdown, the existing `test/cli.sh` assertion harness. + +## Global Constraints + +- The stable latest-release and pinned-tag channels remain documented. +- No compatibility aliases or installer behavior changes. +- The regression must run inside the existing `bash test/cli.sh` CI step. + +--- + +### Task 1: Align the README install channel + +**Files:** +- Modify: `README.md` +- Test: `test/cli.sh` + +**Interfaces:** +- Consumes: The existing `check` helper in `test/cli.sh`. +- Produces: A README quick-start command containing `RIG_REF=main bash`. + +- [ ] **Step 1: Write the failing regression test** + +Add this assertion near the existing README checks in `test/cli.sh`: + +```bash +check "README: the main-branch quick start installs the documented tree" 0 "" \ + grep -qF 'curl -fsSL https://raw.githubusercontent.com/heavy-duty/rig/main/install.sh | RIG_REF=main bash' "$ROOT/README.md" +``` + +- [ ] **Step 2: Verify the test fails for the reported mismatch** + +Run: `bash test/cli.sh` + +Expected: one failure named `README: the main-branch quick start installs the documented tree` because the full command lacks `RIG_REF=main`. + +- [ ] **Step 3: Make the minimal README correction** + +Change the primary install command to: + +```sh +curl -fsSL https://raw.githubusercontent.com/heavy-duty/rig/main/install.sh | RIG_REF=main bash +``` + +Explain that the README tracks `main`; retain examples for the default latest-release and pinned-tag channels, and delete the obsolete transitional notice about cutting 0.1.0. + +- [ ] **Step 4: Verify the focused and full suites pass** + +Run: `bash test/cli.sh` + +Expected: all CLI assertions pass with zero failures. + +Run: `bash test/release.sh` + +Expected: all release assertions pass with zero failures. + +- [ ] **Step 5: Commit** + +```bash +git add README.md test/cli.sh +git commit -m "docs: align README quick start with main" +``` diff --git a/docs/superpowers/specs/2026-07-20-readme-install-channel-design.md b/docs/superpowers/specs/2026-07-20-readme-install-channel-design.md new file mode 100644 index 0000000..de04e19 --- /dev/null +++ b/docs/superpowers/specs/2026-07-20-readme-install-channel-design.md @@ -0,0 +1,36 @@ +# README install-channel alignment + +## Problem + +The landing-page README describes the unreleased CLI on `main`, including +the `*-server` and `*-box` role names, but its first install command selects +the latest release. At present that is 0.2.0, whose CLI accepts the retired +role names instead. A reader following the quick start therefore installs a +CLI that rejects the README's examples. + +## Decision + +The README is documentation for the branch that contains it. Its primary +install command will explicitly set `RIG_REF=main`, making the installed tree +match the commands documented below it. The stable channel remains documented +next to the development and pinned channels, but is no longer presented as the +matching prerequisite for the `main` README's quick start. + +The obsolete pre-0.1.0 transitional notice will be removed. No installer +behavior, role compatibility aliases, or release process will change. + +## Regression protection + +The dependency-free CLI test suite will assert that the README's full GitHub +installer command opts into `RIG_REF=main`. This directly protects the broken +onboarding path without trying to infer semantic compatibility between every +README example and every historical release. + +## Acceptance criteria + +- The first complete installer command in `README.md` installs `main`. +- The README still explains how to install the latest release and a pinned tag. +- The stale “until 0.1.0 is cut” notice is absent. +- `bash test/cli.sh` fails on the old README and passes after the documentation + correction. + diff --git a/test/cli.sh b/test/cli.sh index f7b6695..b490e7f 100644 --- a/test/cli.sh +++ b/test/cli.sh @@ -428,6 +428,10 @@ check "bootstrap: --users does not reach the tenant roles" 2 "unknown flag" \ check "bootstrap: usage explains why tenants take no --users" 0 "box-minted GUEST" \ "$ROOT/commands/bootstrap.sh" --help # --- README: the box rename (#12) -------------------------------------------- +# The README on main documents main's CLI, so its first full install command +# must opt into that tree instead of silently selecting an older release. +check "README: the main-branch quick start installs the documented tree" 0 "" \ + grep -qF 'curl -fsSL https://raw.githubusercontent.com/heavy-duty/rig/main/install.sh | RIG_REF=main bash' "$ROOT/README.md" # The philosophy line must point at heavy-duty/box — the old claudebox slug # only works through a GitHub redirect that one squatted rename away from # breaking (box's own installer was already bitten by the rename once). A -- 2.45.2 From b88495105df68177cd9fb5c6369fbab354163f1d Mon Sep 17 00:00:00 2001 From: codex-bot-andresmgsl Date: Mon, 20 Jul 2026 17:32:43 +0000 Subject: [PATCH 2/3] test: tighten README channel contract --- README.md | 6 +- .../2026-07-20-readme-install-channel.md | 69 ------------------- ...026-07-20-readme-install-channel-design.md | 36 ---------- test/cli.sh | 16 ++++- 4 files changed, 16 insertions(+), 111 deletions(-) delete mode 100644 docs/superpowers/plans/2026-07-20-readme-install-channel.md delete mode 100644 docs/superpowers/specs/2026-07-20-readme-install-channel-design.md diff --git a/README.md b/README.md index 2dcdc33..73e0d12 100644 --- a/README.md +++ b/README.md @@ -458,9 +458,9 @@ command is exactly who that refusal catches (it names the new spelling). > above.** The seed preinstalls rig via its curl installer, which resolves > `RIG_REPO`/`RIG_REF` — and since rig#32 the installer defaults to the > **latest release**, with `RIG_REF=` the pin and `RIG_REF=main` the -> dev channel. Until rig cuts 0.1.0 there is no release to resolve, so the -> seed must set `RIG_REF=main` explicitly (the default channel fails loudly -> rather than falling back). That inverts the install edge on this page: +> dev channel. A seed that needs main must set `RIG_REF=main` explicitly; +> the default channel never silently falls back to a development branch. +> That inverts the install edge on this page: > rig installs box on VM-hosting machines, and box guests now install rig. > `RIG_REPO`/`RIG_REF` are the pin points, or point them at a frozen branch > of your own fork. The seed side of this edge is box#81's to document. diff --git a/docs/superpowers/plans/2026-07-20-readme-install-channel.md b/docs/superpowers/plans/2026-07-20-readme-install-channel.md deleted file mode 100644 index e5f076f..0000000 --- a/docs/superpowers/plans/2026-07-20-readme-install-channel.md +++ /dev/null @@ -1,69 +0,0 @@ -# README Install-Channel Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Ensure the `main` README installs the same development tree whose CLI it documents. - -**Architecture:** Keep installer channel behavior unchanged and correct the documentation entry point. Add one source-level regression assertion to the existing dependency-free CLI suite. - -**Tech Stack:** Bash, Markdown, the existing `test/cli.sh` assertion harness. - -## Global Constraints - -- The stable latest-release and pinned-tag channels remain documented. -- No compatibility aliases or installer behavior changes. -- The regression must run inside the existing `bash test/cli.sh` CI step. - ---- - -### Task 1: Align the README install channel - -**Files:** -- Modify: `README.md` -- Test: `test/cli.sh` - -**Interfaces:** -- Consumes: The existing `check` helper in `test/cli.sh`. -- Produces: A README quick-start command containing `RIG_REF=main bash`. - -- [ ] **Step 1: Write the failing regression test** - -Add this assertion near the existing README checks in `test/cli.sh`: - -```bash -check "README: the main-branch quick start installs the documented tree" 0 "" \ - grep -qF 'curl -fsSL https://raw.githubusercontent.com/heavy-duty/rig/main/install.sh | RIG_REF=main bash' "$ROOT/README.md" -``` - -- [ ] **Step 2: Verify the test fails for the reported mismatch** - -Run: `bash test/cli.sh` - -Expected: one failure named `README: the main-branch quick start installs the documented tree` because the full command lacks `RIG_REF=main`. - -- [ ] **Step 3: Make the minimal README correction** - -Change the primary install command to: - -```sh -curl -fsSL https://raw.githubusercontent.com/heavy-duty/rig/main/install.sh | RIG_REF=main bash -``` - -Explain that the README tracks `main`; retain examples for the default latest-release and pinned-tag channels, and delete the obsolete transitional notice about cutting 0.1.0. - -- [ ] **Step 4: Verify the focused and full suites pass** - -Run: `bash test/cli.sh` - -Expected: all CLI assertions pass with zero failures. - -Run: `bash test/release.sh` - -Expected: all release assertions pass with zero failures. - -- [ ] **Step 5: Commit** - -```bash -git add README.md test/cli.sh -git commit -m "docs: align README quick start with main" -``` diff --git a/docs/superpowers/specs/2026-07-20-readme-install-channel-design.md b/docs/superpowers/specs/2026-07-20-readme-install-channel-design.md deleted file mode 100644 index de04e19..0000000 --- a/docs/superpowers/specs/2026-07-20-readme-install-channel-design.md +++ /dev/null @@ -1,36 +0,0 @@ -# README install-channel alignment - -## Problem - -The landing-page README describes the unreleased CLI on `main`, including -the `*-server` and `*-box` role names, but its first install command selects -the latest release. At present that is 0.2.0, whose CLI accepts the retired -role names instead. A reader following the quick start therefore installs a -CLI that rejects the README's examples. - -## Decision - -The README is documentation for the branch that contains it. Its primary -install command will explicitly set `RIG_REF=main`, making the installed tree -match the commands documented below it. The stable channel remains documented -next to the development and pinned channels, but is no longer presented as the -matching prerequisite for the `main` README's quick start. - -The obsolete pre-0.1.0 transitional notice will be removed. No installer -behavior, role compatibility aliases, or release process will change. - -## Regression protection - -The dependency-free CLI test suite will assert that the README's full GitHub -installer command opts into `RIG_REF=main`. This directly protects the broken -onboarding path without trying to infer semantic compatibility between every -README example and every historical release. - -## Acceptance criteria - -- The first complete installer command in `README.md` installs `main`. -- The README still explains how to install the latest release and a pinned tag. -- The stale “until 0.1.0 is cut” notice is absent. -- `bash test/cli.sh` fails on the old README and passes after the documentation - correction. - diff --git a/test/cli.sh b/test/cli.sh index b490e7f..a2173d7 100644 --- a/test/cli.sh +++ b/test/cli.sh @@ -427,11 +427,21 @@ check "bootstrap: --users does not reach the tenant roles" 2 "unknown flag" \ "$ROOT/commands/bootstrap.sh" claude-box --users "$BOOT_USERS/ok" check "bootstrap: usage explains why tenants take no --users" 0 "box-minted GUEST" \ "$ROOT/commands/bootstrap.sh" --help -# --- README: the box rename (#12) -------------------------------------------- -# The README on main documents main's CLI, so its first full install command +# --- README: install channels (#89) ------------------------------------------ +# The README on main documents main's CLI, so its FIRST full install command # must opt into that tree instead of silently selecting an older release. +readme_first_full_install="$(grep -m1 -F 'curl -fsSL https://raw.githubusercontent.com/heavy-duty/rig/main/install.sh' "$ROOT/README.md")" check "README: the main-branch quick start installs the documented tree" 0 "" \ - grep -qF 'curl -fsSL https://raw.githubusercontent.com/heavy-duty/rig/main/install.sh | RIG_REF=main bash' "$ROOT/README.md" + test "$readme_first_full_install" = \ + 'curl -fsSL https://raw.githubusercontent.com/heavy-duty/rig/main/install.sh | RIG_REF=main bash' +check "README: no stale pre-0.1.0 release notice" 1 "" \ + grep -qF 'Until rig cuts 0.1.0' "$ROOT/README.md" +check "README: still documents the latest-release channel" 0 "" \ + grep -qF 'curl -fsSL .../install.sh | bash # the latest release' "$ROOT/README.md" +check "README: still documents the pinned-tag channel" 0 "" \ + grep -qF 'curl -fsSL .../install.sh | RIG_REF=0.1.0 bash # pinned to a release' "$ROOT/README.md" + +# --- README: the box rename (#12) -------------------------------------------- # The philosophy line must point at heavy-duty/box — the old claudebox slug # only works through a GitHub redirect that one squatted rename away from # breaking (box's own installer was already bitten by the rename once). A -- 2.45.2 From 491055c4cffb057622ac685664ff504c4f4c02db Mon Sep 17 00:00:00 2001 From: codex-bot-andresmgsl Date: Mon, 20 Jul 2026 17:50:18 +0000 Subject: [PATCH 3/3] docs: point stable installs at matching README --- README.md | 8 +++++--- test/cli.sh | 8 ++++++-- 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 73e0d12..6c453fd 100644 --- a/README.md +++ b/README.md @@ -20,12 +20,14 @@ curl -fsSL https://raw.githubusercontent.com/heavy-duty/rig/main/install.sh | RI This README tracks `main`, so the quick start installs that same development tree. To install a stable version instead, use the latest-release or pinned-tag -channel and follow the documentation shipped with that version. Three channels -come from the same script; `RIG_REF` picks: +channel and read the documentation shipped with it at +`$RIG_HOME/current/README.md` (`~/.local/share/rig/current/README.md` with the +default install root). Three channels come from the same script; `RIG_REF` +picks: ```sh curl -fsSL .../install.sh | bash # the latest release -curl -fsSL .../install.sh | RIG_REF=0.1.0 bash # pinned to a release +curl -fsSL .../install.sh | RIG_REF=0.2.0 bash # pinned to a release curl -fsSL .../install.sh | RIG_REF=main bash # the development tree ``` diff --git a/test/cli.sh b/test/cli.sh index a2173d7..a0af5ab 100644 --- a/test/cli.sh +++ b/test/cli.sh @@ -438,8 +438,12 @@ check "README: no stale pre-0.1.0 release notice" 1 "" \ grep -qF 'Until rig cuts 0.1.0' "$ROOT/README.md" check "README: still documents the latest-release channel" 0 "" \ grep -qF 'curl -fsSL .../install.sh | bash # the latest release' "$ROOT/README.md" -check "README: still documents the pinned-tag channel" 0 "" \ - grep -qF 'curl -fsSL .../install.sh | RIG_REF=0.1.0 bash # pinned to a release' "$ROOT/README.md" +# $RIG_HOME is the literal path spelling the README must show operators. +# shellcheck disable=SC2016 +check "README: names the stable channel's installed documentation" 0 "" \ + grep -qF '$RIG_HOME/current/README.md' "$ROOT/README.md" +check "README: still documents a pinned semver-tag channel" 0 "" \ + grep -Eq '^curl -fsSL \.\.\./install\.sh \| RIG_REF=[0-9]+\.[0-9]+\.[0-9]+ bash +# pinned to a release$' "$ROOT/README.md" # --- README: the box rename (#12) -------------------------------------------- # The philosophy line must point at heavy-duty/box — the old claudebox slug -- 2.45.2