docs: align README quick start with main

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/<ref>`.
 
-> **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`):
 
 ```

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"
+```

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.
+

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