diff --git a/docs/superpowers/plans/2026-08-21-clean-room-vm.md b/docs/superpowers/plans/2026-08-21-clean-room-vm.md
new file mode 100644
index 00000000..268a0182
--- /dev/null
+++ b/docs/superpowers/plans/2026-08-21-clean-room-vm.md
@@ -0,0 +1,2290 @@
+# L7 Clean-Room Testing (VM golden images + scripted walkthrough + second-user smoke) 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:** Ship `rt-tray/vm/` — golden macOS VM images (14 + 26), a scripted first-install → five-screen setup → `rt verify` → Sparkle vN→vN+1 walkthrough that archives screenshots + logs per run, a second-macOS-user smoke script, and `scripts/e2e-cleanroom.sh` that runs the CI headless install recipe locally — so ruling 12's layers (a), (b), (c) exist and the release gate ((a)+(b) green) is runnable.
+
+**Architecture:** Everything is bash + one tiny Bun helper, orchestrated from the host. Tart (Apple Virtualization.framework) owns VM lifecycle; the golden VM is never run after it is built — every run is `tart clone` (APFS copy-on-write) → drive → `tart delete`. Host ↔ guest is ssh (key installed at golden time) plus a `--dir` virtiofs share that IS the run's artifacts directory, so every screenshot and log lands on the host as it is produced. The UI is driven by AppleScript/System Events UI scripting over ssh (Xcode-free fallback, first) with an XCUITest mode (`xcodebuild test` inside an `-xcode` golden) gated on Xcode existing. Screenshots are captured on the HOST from the Tart window (in-guest `screencapture` over ssh is unreliable on macOS 15+). Every phase writes a `pass|fail|skip` line with a reason; nothing is marked green on a guess.
+
+**Tech Stack:** Tart ≥ 2.x (`brew install openai/tools/tart`; FSL-1.1-ALv2 — see constraints), cirruslabs `macos-{sonoma,tahoe}-vanilla` OCI images, bash 3.2 (`/bin/bash` — macOS stock), `sshpass` (golden build only), `osascript` / System Events, `screencapture`, `hdiutil`, `ditto`, `PlistBuddy`, Bun (compiles `appcast-server`), Sparkle `generate_appcast` (update phase only), `gh` (test team, host only).
+
+**Spec:** `docs/superpowers/specs/2026-08-20-mattstack-app-installer-design.md` (§2 ruling 12 + invariants, §3–4 flow/screens, §9 permissions, §11 distribution, §12.2 testing, §13 lanes); contract `docs/superpowers/specs/2026-08-21-rt-setup-contract.md`; research `docs/superpowers/specs/research/2026-08-20-mattstack-app/research-onboarding-permissions-ux.md`, `research-sparkle-install-launchd.md`.
+
+**Execution worktree:** `/Users/matt/Documents/GitHub/repo-tools-l7-wt`, branch `goodwinmattheweric/mat-383-clean-room` off `origin/main`. Commit prefix `MAT-383:`; trailer `Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>`. No monitor agent — every implementer runs `bash -n` and the task's dry-run themselves before committing.
+
+**Execution order** (binding; from `docs/superpowers/plans/2026-08-21-cross-plan-review.md` §3): Phase A — Tasks 1, 2, 4, 5, 7, 9, 10, 11, 14 (all under `rt-tray/vm/`) and Task 3 with its own recipes (re-pointed at `scripts/release/*` after L4 T6 merges). Phase B — Task 6 AFTER L3 T12–T16 merge (the AXIDs exist; ids are already written to L3's `AccessibilityIDs.swift` below and fail fast when missing); Task 8 AFTER L3 T10 merges (`--allow-appcast-override`); Task 12 after the CLI is agreed with L4 T8 (positional artifact — fixed in the review); Task 13 AFTER L3 T19 merges and Xcode exists. Merge order to main: L4 phase A → L3 T1–T11 → L1 → L4 T4/T5/T8 → L1 (rest) → L3 T12–T19 → **L7 (all)** → L4 T12 → L1 T31–T32 → MATT gates. L7 owns `rt-tray/vm/**` and `scripts/e2e-cleanroom.sh` (interface fixed by the review, §5 #46); `.github/workflows/release.yml` is L4's and only calls the script.
+
+## Global Constraints
+
+Copied from the spec; every task's requirements include these.
+
+- **macOS 14 floor; arm64-only** (ruling 13, §11). Golden images: macOS 14 (Sonoma) and 26 (Tahoe); 15 (Sequoia) optional. Host is Apple Silicon, macOS 26.6.1.
+- **Identity frozen:** `com.mattstack.app` / `com.mattstack.app.dev`; agents `com.mattstack.daemon` / `.dev`, `com.mattstack.deck`; bundle `mattstack.app`; `~/.mattstack`; `~/.local/bin/rt` is a symlink into the bundle (ruling 13, §11). Tests assert these names, never `rt-tray.app` / `com.rt.daemon` / `~/.rt` ("pure canonical, no compat").
+- **Install location:** DMG target `/Applications`, fallback `~/Applications` when not writable; the app records `mattstack.appPath` (V3).
+- **Permissions:** Full Disk Access + Login Items required; Notifications optional; no Accessibility/Screen Recording/Automation are requested by the APP (ruling 10). (The VM test *driver* needs Accessibility — that is granted to `sshd-keygen-wrapper`/`osascript` in the guest, never to mattstack.app.)
+- **Honesty over magic:** every checklist row / phase reports what was actually checked; nothing is marked ready on a guess (invariant). Phases that cannot run say `skip` + reason, never `pass`.
+- **rt owns mechanics, the app owns ceremony:** the walkthrough asserts through `rt verify --json`, `rt setup status --json`, and tray.sock routes (`GET /version`, `GET /services`, `GET /permissions`) — never by parsing UI text alone.
+- **No user or employer data on mattstack-hosted infra; the relay sees ciphertext + timestamps only.** The test team uses a throwaway GitHub org; the PAT comes from env and is never written to the repo or to artifacts.
+- **rt repo stealth:** rt never writes into target repos; all state under `~/.mattstack/`. The VM layer writes only under `rt-tray/vm/artifacts/` (gitignored) and `rt-tray/vm/.cache/` (gitignored) on the host.
+- **Clean-room definition (ruling 12):** no Apple CLT, no Homebrew, one standard user, no Apple ID.
+- **Release gate:** layers (a) GitHub Actions headless install + `rt verify --ci` and (b) VM walkthrough green on the candidate.
+- **Clean-code comments rule** (`~/.claude/rules/clean-code-comments.md`): comments only for constraints the code cannot show; no task numbers/process narration in source. Decision records go in this plan / README, not scripts.
+- **Logging:** scripts log to the run's artifacts dir; no new logging inside rt.
+- **Rebase onto `origin/main` before every merge** (cross-plan review §3); L7 merges after L3 T12–T19. L7 edits only `rt-tray/vm/**`, `scripts/e2e-cleanroom.sh` and an appended section of `scripts/README.md` (L4 T6 appends its own section; whoever merges second rebases).
+- **Artifacts are L4's names:** `mattstack-<ver>.dmg`, `mattstack-<ver>.zip`, `appcast.xml` (a GitHub Release asset at `https://github.com/m4ttstack/rt/releases/latest/download/appcast.xml` in prod; served on loopback in the VM), `*.delta`, `SHA256SUMS`. There is no `rt-darwin-arm64-*.tar.gz` any more — the zip is the headless artifact. `CFBundleVersion` is numeric `major*1000000+minor*1000+patch` (2.8.0 → `2008000`).
+- **Tart licence constraint:** Tart's `LICENSE` on `main` is **Functional Source License 1.1 (ALv2 future licence), "Copyright 2022-2026 OpenAI"** — permitted purposes include "internal use and access"; tart.run/licensing: "Usage on personal computers including personal workstations is royalty-free"; organisations are free up to **100 CPU cores** for Tart, paid tiers above (Gold $12k/yr 500 cores…). Matt's single workstation is inside the free tier. Record in README; if L7 ever moves to a shared self-hosted fleet, recount cores.
+
+## Research record (what the scripts rely on — cited)
+
+- Tart now lives at `github.com/openai/tart`; brew tap `openai/tools/tart` (README on main). Older docs say `cirruslabs/cli/tart`; use the new tap, fall back to the old if brew can't find it.
+- Images (tart.run quick-start): `ghcr.io/cirruslabs/macos-{tahoe,sequoia,sonoma}-{vanilla,base,xcode}:latest`; creds `admin`/`admin` for GUI and ssh. `macos-sonoma-vanilla:latest` = 14.8.7 (published ~3 months ago, still updated). **Use `-vanilla`**, not `-base`: `base` preinstalls Homebrew + gh/jq/node/rbenv + the tart guest agent (templates `base.pkr.hcl`); `vanilla` has none of that. The `vanilla-sequoia` template DOES run `softwareupdate --install 'Command Line Tools for Xcode-*'`, so the golden provisioner must remove CLT (`/Library/Developer/CommandLineTools`) on every image and verify with `xcode-select -p` failing.
+- Vanilla templates preconfigure: auto-login `admin` (`/etc/kcpassword` + `autoLoginUser`), passwordless sudo (`/etc/sudoers.d/admin-nopasswd`), screensaver off, `systemsetup -setsleep Off`, `sysadminctl -screenLock off`, Remote Login + Screen Sharing ON, `defaults write NSGlobalDomain AppleKeyboardUIMode -int 3`, **Gatekeeper DISABLED** (`sudo spctl --global-disable` + Settings toggle). The golden must re-enable Gatekeeper (`sudo spctl --global-enable`, verify `spctl --status` = "assessments enabled") so the DMG path is real.
+- `tart clone` = file copy on APFS → copy-on-write ("a cloned VM won't actually claim all the space right away"), so restore-per-run = clone from golden, delete after. `--stacked` needs macOS 27; not used.
+- `tart run` flags used: `--no-graphics`, `--dir=<name>:<host path>[:ro]` (guest automount `/Volumes/My Shared Files/<name>`; host+guest ≥ 13), `--no-audio`, `--vnc` (Screen Sharing), `--net-softnet` (NOT used: blocks guest→host). Default NAT: host reachable from guest at the router IP (`route -n get default` in the guest).
+- `tart exec` needs the tart-guest-agent, which ships only in non-vanilla images → **ssh only** in this plan. `tart ip <vm>` gives the guest IP. Commands available: clone create delete exec export get import ip list login logout prune pull push rename run set stop suspend — **no screenshot command**.
+- Nested virtualisation: Virtualization.framework supports it only for Linux guests on M3+/macOS 15 → GitHub-hosted macOS runners (themselves VMs) cannot run Tart macOS VMs. Local only; a self-hosted Apple-Silicon runner later.
+- UI scripting over ssh: `osascript … tell application "System Events"` fails with "not allowed assistive access" until `/usr/libexec/sshd-keygen-wrapper` (and `/usr/bin/osascript`) are in Privacy & Security → **Accessibility**, and the **Automation** ("sshd-keygen-wrapper wants to control System Events") prompt is approved once for the ssh user. TCC cannot be pre-approved from a script (`tccutil` can only *reset*; PPPC profiles need MDM) → **one-time manual click in the guest GUI at golden-image time**, then every clone inherits it. macOS 26.1/26.2 had a bug adding CLI tools to Accessibility (fixed 26.3); the golden verifier probes it.
+- `screencapture` over ssh on macOS 15+ prompts/returns blank even with Screen Recording granted to sshd-keygen-wrapper (Apple forum thread 764789) → **capture on the host** from the Tart window (`screencapture -x -l <windowID>`; host Terminal needs Screen Recording once — MATT step).
+- `launchctl bootstrap gui/<uid>` needs a logged-in GUI session ("Bootstrap failed: 5" otherwise) → second-user smoke requires the second user to be logged in (Fast User Switching) before `rt daemon install` can register; `su -l` alone can install files but the daemon row reports not-booted.
+- Sparkle: feed override via `SPUUpdaterDelegate feedURLString(for:)`; http feeds need `NSAppTransportSecurity` → `NSAllowsLocalNetworking` (loopback/.local) — serving from the HOST at 192.168.64.x would additionally trigger Sequoia's Local Network Privacy prompt (Sparkle discussion #2732), so the appcast is served **inside the guest on 127.0.0.1**. Enclosures must be EdDSA-signed with the key matching the build's `SUPublicEDKey`; Sparkle compares numeric `CFBundleVersion`.
+- `rt --post-install` (current `commands/post-install.ts`) installs `~/.local/bin/rt`, copies `mattstack.app` → `~/Applications`, **launches the app with `open`**, then `rt daemon install` (→ tray socket `/daemon/start`, SMAppService). Running it on a host whose console user already has mattstack registered would launch a second tray under the same bundle id → `scripts/e2e-cleanroom.sh` refuses that by default. (L1 T27 replaces the body with legacy sweep + headless `rt setup apply`; `--no-launch` is explicit and implied by `--ci`/`CI=true` — Task 12 passes it.)
+- `rt verify --ci` (commands/verify.ts) = human output, no colour, exit 1 on any critical fail; daemon-not-booted is a *warn* under `CI=true`.
+- VirtualBuddy (insidegui): GUI only, no CLI; APFS duplicate via Finder ⌘D; guest app for clipboard/sharing. Documented as the manual alternative, not scripted.
+
+## Dependencies on other lanes (the walkthrough is built to the contract; phases `skip` with the reason until these land)
+
+| Need | Lane | Walkthrough phase that skips without it |
+|---|---|---|
+| DMG + zip + appcast artifacts (`mattstack-<ver>.dmg`, `mattstack-<ver>.zip`), Sparkle in the app, `SUPublicEDKey`; build accepts `SPARKLE_PUBLIC_ED_KEY` override for test keys | L4 | update (P7); install uses `vm/run/make-dmg.sh` from a locally built `.app` meanwhile |
+| Five screens + AXIdentifiers from the L3 plan's `rt-tray/Sources/Setup/AccessibilityIDs.swift` (`2026-08-21-mattstack-app-shell.md` T12; the same plan defines the XCUITest target `mattstackUITests` and the stub envs `RT_STUB_SCENARIO`/`RT_STUB_PATH` (required)/`RT_STUB_BUN`/`RT_STUB_STATE_DIR`): screens `setup.<welcome\|team\|checklist\|install\|done>.screen`; `setup.<screen>.continue`, `setup.<screen>.back`, `setup.checklist.continueLimited`; team `setup.team.card.create\|join\|restore`, `setup.team.create.name\|others\|useGh\|owner\|remote`, `setup.team.join.code`, `setup.team.restore.repo\|key`; checklist `setup.checklist.row.<rowId>`, `.row.<rowId>.action`, `.row.<rowId>.status`, `setup.checklist.recheck`, `setup.checklist.relaunch`, `setup.checklist.connect.field.<name>`, `setup.checklist.connect.submit\|cancel`; install `setup.install.step.<id>`, `setup.install.retry`; done `setup.done.continue`, `setup.done.openBoard`, `setup.done.invite`. Row ids are L1's (`perm.fda`, `perm.login-items`, `perm.notifications`, `account.github`, `tool.clt`, …). Also from L3: `MATTSTACK_APPCAST_URL` honoured only for dev builds or when launched with `--allow-appcast-override` (T10), ATS `NSAllowsLocalNetworking`, `GET /version` (`build` numeric) on tray.sock | L3 | screens (P5), update (P7) |
+| `rt setup plan/status/apply --json`, `rt --post-install --non-interactive --team-of-one --no-launch` (`--no-launch` also implied by `--ci`/`CI=true`), `rt team invite/join` | L1 | assert (P6 uses `rt verify --json` today), invite scenario |
+| `/v1/invites*` on the shared relay | L6 | join scenario (stub until then) |
+
+---
+
+## File structure
+
+```
+rt-tray/vm/
+  README.md                      what the layer verifies / cannot; how to run; MATT steps; licence note
+  .gitignore                     artifacts/ .cache/
+  lib/common.sh                  shared bash: logging, phase ledger, tart/ssh helpers, run dirs
+  golden/build-golden.sh         host: pull vanilla image → mattstack-golden-<ver> → provision → verify
+  golden/provision-guest.sh      guest (as admin): no CLT, no brew, Gatekeeper on, tester user, ssh keys, sleep/lock off
+  golden/verify-golden.sh        host: asserts every golden property over ssh incl. the manual TCC grants
+  run/walkthrough.sh             host orchestrator: clone → boot → stage → install → screens → assert → update → teardown → report
+  run/guest/install-app.sh       guest: quarantine DMG, mount, copy to /Applications (admin) , launch as tester with env
+  run/guest/ax.sh                guest: osascript helpers (find by AXIdentifier, click, type, wait, admin-auth, notification prompts)
+  run/guest/drive-setup.sh       guest: screens 1–5 + FDA/Login Items/Notifications dances, screenshot hooks
+  run/guest/assert-installed.sh  guest: rt verify --json, tray.sock /version, daemon pid/label, symlink target
+  run/guest/trigger-update.sh    guest: loopback appcast server, POST /update/check, drive Sparkle, assert vN+1 + daemon restart
+  run/host/capture.sh            host: screenshot the Tart window into the run dir
+  run/host/winid.swift           host: CGWindowList lookup of the Tart window id
+  run/helpers/appcast-server.ts  Bun static file server (compiled per run, copied into the guest)
+  run/make-dmg.sh                host: wrap a built mattstack.app in a DMG (pre-L4 runs)
+  run/make-appcast.sh            host: bump CFBundleVersion copy → zip → generate_appcast with a test EdDSA key
+  run/team-setup.sh              host, ORCHESTRATOR/MATT: reset the throwaway org's repos; mint invite (real or stub)
+  run/second-user.sh             host: layer (c) — run e2e-cleanroom as the second macOS user (MATT creates the user)
+  run/xcuitest.sh                host: layer (b) XCUITest mode, gated on Xcode + the -xcode golden
+  artifacts/                     gitignored; <run-id>/ per run: screenshots/, logs/, phases.jsonl, report.md
+scripts/e2e-cleanroom.sh         layer (a) locally: artifact → extract → rt --post-install → rt daemon install → rt verify --ci
+```
+
+Phase ledger format (`artifacts/<run>/phases.jsonl`, one object per phase, appended by `vm_phase_end`):
+`{"phase":"install","status":"pass|fail|skip","reason":"…","at":"<ISO>","seconds":12,"screenshots":["screenshots/03-install.png"]}`.
+`report.md` is rendered from it at teardown. A run's exit code is 1 if any phase failed, 0 if all passed or skipped, and the summary line states the skips so a skip never reads as green.
+
+---
+
+### Task 1: Scaffold `rt-tray/vm/` — README skeleton, gitignore, `lib/common.sh`
+
+**Files:**
+- Create: `rt-tray/vm/README.md`
+- Create: `rt-tray/vm/.gitignore`
+- Create: `rt-tray/vm/lib/common.sh`
+- Create: `rt-tray/vm/lib/__tests__/common.test.sh`
+
+**Interfaces:**
+- Produces (sourced by every later script via `source "$(dirname "$0")/../lib/common.sh"` or `…/lib/common.sh`):
+  - `VM_ROOT` (abs path of `rt-tray/vm`), `VM_ARTIFACTS` (`$VM_ROOT/artifacts`), `VM_CACHE` (`$VM_ROOT/.cache`)
+  - `vm_log <msg>`, `vm_warn <msg>`, `vm_die <msg>` (exit 1)
+  - `vm_require_cmd <cmd> [<install hint>]`
+  - `vm_golden_name <ver>` → `mattstack-golden-<ver>`; `vm_image_for <ver>` → OCI ref (14→sonoma-vanilla, 15→sequoia-vanilla, 26→tahoe-vanilla)
+  - `vm_run_init <label>` → sets `VM_RUN_ID`, `VM_RUN_DIR`, creates `screenshots/ logs/ in/`, writes `run.json`
+  - `vm_phase_begin <name>`, `vm_phase_end <name> <pass|fail|skip> [<reason>] [<screenshot…>]` → appends to `phases.jsonl`; `vm_phases_failed` → count
+  - `vm_ip <vm>` (retries), `vm_ssh <user> <vm> <cmd…>`, `vm_scp <user> <vm> <src> <dest>`, `vm_wait_ssh <user> <vm> <timeout_s>` — all key-based using `$VM_CACHE/id_ed25519`
+  - `vm_ssh_pw <user> <pass> <vm> <cmd…>` (sshpass; golden build only)
+  - `vm_render_report` → `report.md` from `phases.jsonl`
+
+- [ ] **Step 1: Write `rt-tray/vm/.gitignore`**
+
+```gitignore
+artifacts/
+.cache/
+```
+
+- [ ] **Step 2: Write the failing test `rt-tray/vm/lib/__tests__/common.test.sh`**
+
+```bash
+#!/bin/bash
+# Exercises lib/common.sh without tart: names, run dirs, phase ledger, report.
+set -euo pipefail
+HERE="$(cd "$(dirname "$0")" && pwd)"
+source "$HERE/../common.sh"
+
+fails=0
+check() { if eval "$2"; then echo "  ok   $1"; else echo "  FAIL $1"; fails=$((fails+1)); fi; }
+
+check "golden name"            '[ "$(vm_golden_name 26)" = "mattstack-golden-26" ]'
+check "image for 14"           '[ "$(vm_image_for 14)" = "ghcr.io/cirruslabs/macos-sonoma-vanilla:latest" ]'
+check "image for 15"           '[ "$(vm_image_for 15)" = "ghcr.io/cirruslabs/macos-sequoia-vanilla:latest" ]'
+check "image for 26"           '[ "$(vm_image_for 26)" = "ghcr.io/cirruslabs/macos-tahoe-vanilla:latest" ]'
+check "image for 99 dies"      '! vm_image_for 99 2>/dev/null'
+
+export VM_ARTIFACTS="$(mktemp -d)"
+vm_run_init unit
+check "run dir created"        '[ -d "$VM_RUN_DIR/screenshots" ] && [ -d "$VM_RUN_DIR/logs" ] && [ -d "$VM_RUN_DIR/in" ]'
+check "run.json written"       'grep -q "\"label\": *\"unit\"" "$VM_RUN_DIR/run.json"'
+
+vm_phase_begin alpha; vm_phase_end alpha pass
+vm_phase_begin beta;  vm_phase_end beta skip "no dmg given" "screenshots/x.png"
+vm_phase_begin gamma; vm_phase_end gamma fail "boom"
+check "three ledger lines"     '[ "$(wc -l < "$VM_RUN_DIR/phases.jsonl")" -eq 3 ]'
+check "skip carries reason"    'grep -q "\"phase\":\"beta\",\"status\":\"skip\",\"reason\":\"no dmg given\"" "$VM_RUN_DIR/phases.jsonl"'
+check "skip carries shot"      'grep -q "\"screenshots\":\[\"screenshots/x.png\"\]" "$VM_RUN_DIR/phases.jsonl"'
+check "failed count is 1"      '[ "$(vm_phases_failed)" -eq 1 ]'
+vm_render_report
+check "report lists skip"      'grep -q "beta.*skip.*no dmg given" "$VM_RUN_DIR/report.md"'
+check "report says 1 failed"   'grep -q "1 failed" "$VM_RUN_DIR/report.md"'
+
+rm -rf "$VM_ARTIFACTS"
+[ "$fails" -eq 0 ] && echo "common.test.sh: all ok" || { echo "common.test.sh: $fails failed"; exit 1; }
+```
+
+- [ ] **Step 3: Run it to see it fail**
+
+Run: `bash rt-tray/vm/lib/__tests__/common.test.sh`
+Expected: `No such file or directory` for `common.sh` (exit ≠ 0).
+
+- [ ] **Step 4: Write `rt-tray/vm/lib/common.sh`**
+
+```bash
+#!/bin/bash
+# Shared helpers for rt-tray/vm scripts. Source, don't execute.
+# bash 3.2 compatible (macOS stock /bin/bash): no associative arrays, no ${var,,}.
+
+VM_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+: "${VM_ARTIFACTS:=$VM_ROOT/artifacts}"
+: "${VM_CACHE:=$VM_ROOT/.cache}"
+: "${VM_SSH_KEY:=$VM_CACHE/id_ed25519}"
+: "${VM_ADMIN_USER:=admin}"
+: "${VM_ADMIN_PASS:=admin}"
+: "${VM_TESTER_USER:=tester}"
+: "${VM_TESTER_PASS:=tester}"
+
+VM_SSH_OPTS=(-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o LogLevel=ERROR -o ConnectTimeout=5)
+
+vm_log()  { printf '  %s\n' "$*" >&2; }
+vm_warn() { printf '  ! %s\n' "$*" >&2; }
+vm_die()  { printf '  ✗ %s\n' "$*" >&2; exit 1; }
+vm_now()  { date -u +%Y-%m-%dT%H:%M:%SZ; }
+
+vm_require_cmd() {
+  command -v "$1" >/dev/null 2>&1 || vm_die "missing command: $1${2:+ — $2}"
+}
+
+vm_golden_name() { printf 'mattstack-golden-%s' "$1"; }
+
+vm_image_for() {
+  case "$1" in
+    14) printf 'ghcr.io/cirruslabs/macos-sonoma-vanilla:latest' ;;
+    15) printf 'ghcr.io/cirruslabs/macos-sequoia-vanilla:latest' ;;
+    26) printf 'ghcr.io/cirruslabs/macos-tahoe-vanilla:latest' ;;
+    *)  vm_die "no image mapping for macOS $1 (known: 14 15 26)" ;;
+  esac
+}
+
+# ── run directories + phase ledger ──────────────────────────────────────────
+
+vm_run_init() {
+  local label="$1"
+  VM_RUN_ID="$(date +%Y%m%d-%H%M%S)-$label"
+  VM_RUN_DIR="$VM_ARTIFACTS/$VM_RUN_ID"
+  mkdir -p "$VM_RUN_DIR/screenshots" "$VM_RUN_DIR/logs" "$VM_RUN_DIR/in"
+  printf '{\n  "id": "%s",\n  "label": "%s",\n  "startedAt": "%s",\n  "host": "%s"\n}\n' \
+    "$VM_RUN_ID" "$label" "$(vm_now)" "$(sw_vers -productVersion 2>/dev/null || echo unknown)" > "$VM_RUN_DIR/run.json"
+  export VM_RUN_ID VM_RUN_DIR
+  vm_log "run $VM_RUN_ID → $VM_RUN_DIR"
+}
+
+_vm_phase_started=0
+vm_phase_begin() {
+  _vm_phase_started=$(date +%s)
+  vm_log "── phase: $1"
+}
+
+# vm_phase_end <name> <pass|fail|skip> [reason] [screenshot...]
+vm_phase_end() {
+  local name="$1" status="$2" reason="${3:-}"; shift 3 2>/dev/null || shift $#
+  local shots="" s
+  for s in "$@"; do shots="$shots${shots:+,}\"$s\""; done
+  local secs=$(( $(date +%s) - _vm_phase_started ))
+  local esc_reason; esc_reason=$(printf '%s' "$reason" | sed 's/\\/\\\\/g; s/"/\\"/g')
+  printf '{"phase":"%s","status":"%s","reason":"%s","at":"%s","seconds":%d,"screenshots":[%s]}\n' \
+    "$name" "$status" "$esc_reason" "$(vm_now)" "$secs" "$shots" >> "$VM_RUN_DIR/phases.jsonl"
+  case "$status" in
+    pass) vm_log "   ✓ $name" ;;
+    skip) vm_warn "   – $name skipped: $reason" ;;
+    fail) vm_warn "   ✗ $name FAILED: $reason" ;;
+    *)    vm_die "vm_phase_end: bad status '$status'" ;;
+  esac
+}
+
+vm_phases_failed() { grep -c '"status":"fail"' "$VM_RUN_DIR/phases.jsonl" 2>/dev/null || true; }
+
+vm_render_report() {
+  local f="$VM_RUN_DIR/phases.jsonl" out="$VM_RUN_DIR/report.md"
+  local total pass fail skip
+  total=$(wc -l < "$f" | tr -d ' '); pass=$(grep -c '"status":"pass"' "$f" || true)
+  fail=$(grep -c '"status":"fail"' "$f" || true); skip=$(grep -c '"status":"skip"' "$f" || true)
+  {
+    echo "# clean-room run $VM_RUN_ID"
+    echo
+    echo "$total phases: $pass passed, $fail failed, $skip skipped."
+    [ "$skip" -gt 0 ] && echo "**Skipped phases are not green** — see reasons below."
+    echo
+    echo "| phase | status | seconds | reason | screenshots |"
+    echo "|---|---|---|---|---|"
+    sed -E 's/^\{"phase":"([^"]*)","status":"([^"]*)","reason":"([^"]*)","at":"[^"]*","seconds":([0-9]+),"screenshots":\[([^]]*)\]\}$/| \1 | \2 | \4 | \3 | \5 |/' "$f"
+    echo
+    echo "Logs: \`logs/\` · Screenshots: \`screenshots/\` · Ledger: \`phases.jsonl\`"
+  } > "$out"
+  vm_log "report → $out"
+}
+
+# ── tart / ssh ──────────────────────────────────────────────────────────────
+
+vm_ip() {
+  local vm="$1" tries="${2:-60}" ip=""
+  while [ "$tries" -gt 0 ]; do
+    ip=$(tart ip "$vm" 2>/dev/null || true)
+    [ -n "$ip" ] && { printf '%s' "$ip"; return 0; }
+    sleep 2; tries=$((tries-1))
+  done
+  return 1
+}
+
+vm_ssh() {
+  local user="$1" vm="$2"; shift 2
+  local ip; ip=$(vm_ip "$vm" 1) || vm_die "no ip for $vm"
+  ssh "${VM_SSH_OPTS[@]}" -i "$VM_SSH_KEY" "$user@$ip" "$@"
+}
+
+vm_scp() {
+  local user="$1" vm="$2" src="$3" dest="$4"
+  local ip; ip=$(vm_ip "$vm" 1) || vm_die "no ip for $vm"
+  scp -r "${VM_SSH_OPTS[@]}" -i "$VM_SSH_KEY" "$src" "$user@$ip:$dest"
+}
+
+vm_ssh_pw() {
+  local user="$1" pass="$2" vm="$3"; shift 3
+  vm_require_cmd sshpass "brew install cirruslabs/cli/sshpass"
+  local ip; ip=$(vm_ip "$vm" 1) || vm_die "no ip for $vm"
+  sshpass -p "$pass" ssh "${VM_SSH_OPTS[@]}" "$user@$ip" "$@"
+}
+
+vm_wait_ssh() {
+  local user="$1" vm="$2" timeout="${3:-300}" start; start=$(date +%s)
+  while :; do
+    if vm_ssh "$user" "$vm" true 2>/dev/null; then return 0; fi
+    [ $(( $(date +%s) - start )) -ge "$timeout" ] && return 1
+    sleep 3
+  done
+}
+```
+
+- [ ] **Step 5: Run the test, expect all ok**
+
+Run: `bash -n rt-tray/vm/lib/common.sh && bash rt-tray/vm/lib/__tests__/common.test.sh`
+Expected: every line `ok`, final `common.test.sh: all ok`.
+
+- [ ] **Step 6: Write the README skeleton `rt-tray/vm/README.md`** (Task 14 finishes it; the headings and the can/can't table are written now so every task can point at it)
+
+```markdown
+# rt-tray/vm — clean-room testing (installer spec ruling 12, lane L7)
+
+Golden macOS VM images, a scripted walkthrough of the mattstack.app installer,
+a second-macOS-user smoke, and a local runner for the CI headless install.
+Every run's deliverable is `artifacts/<run-id>/` (screenshots, logs,
+`phases.jsonl`, `report.md`). Skipped phases are reported as skipped, never green.
+
+## What this layer verifies — and cannot
+
+| Layer | Verifies | Cannot verify / not automated |
+|---|---|---|
+| (a) `scripts/e2e-cleanroom.sh` (same recipe as the release workflow's `test-install` job) | artifact extracts; `rt --post-install` installs `~/.local/bin/rt`, the app, the daemon config; `rt verify --ci` exit 0 | anything needing a GUI session or approval (daemon boot is a warn under CI), Gatekeeper (no quarantine on CI downloads) |
+| (b) `run/walkthrough.sh` (Tart clone of a golden image) | real DMG → /Applications → first launch under Gatekeeper; five setup screens; FDA + Login Items + Notifications dances; `rt verify --json` green; tray.sock `/version`; Sparkle vN→vN+1 and daemon restart; screenshots per screen | the **"Background Items Added" notification** (a banner, not a dialog — it is neither clicked nor asserted; the Login Items row is asserted through `GET /services` / `rt setup status` instead); the **FDA relaunch** is driven (the app's own "Relaunch" button) but the OS applying FDA is asserted only via the app's probe row; notarisation/stapling of Matt's signing (a locally built DMG is unnotarised → run with `--no-quarantine`, reported in the ledger) |
+| (c) `run/second-user.sh` | layer (a) under a second real macOS user on Matt's Mac, with a live GUI session so SMAppService registration is real | nothing about the five screens; the user must be created and logged in once by Matt |
+
+(rest of the README is written in Task 14)
+```
+
+- [ ] **Step 7: Commit**
+
+```bash
+cd /Users/matt/Documents/GitHub/repo-tools-l7-wt
+git add rt-tray/vm/.gitignore rt-tray/vm/README.md rt-tray/vm/lib/common.sh rt-tray/vm/lib/__tests__/common.test.sh
+git commit -m "MAT-383: vm — scaffold rt-tray/vm with shared bash helpers and phase ledger
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 2: Golden image build — `golden/build-golden.sh`, `golden/provision-guest.sh`, `golden/verify-golden.sh`
+
+**Files:**
+- Create: `rt-tray/vm/golden/build-golden.sh`
+- Create: `rt-tray/vm/golden/provision-guest.sh`
+- Create: `rt-tray/vm/golden/verify-golden.sh`
+
+**Interfaces:**
+- Consumes: `lib/common.sh` (`vm_image_for`, `vm_golden_name`, `vm_ssh_pw`, `vm_ssh`, `vm_wait_ssh`, `VM_SSH_KEY`).
+- Produces: a stopped Tart VM `mattstack-golden-<ver>` with: users `admin` (admin, NOPASSWD sudo, ssh key) and `tester` (standard, password `tester`, ssh key, **auto-login console user**); no CLT; no Homebrew; Gatekeeper enabled; sleep/screensaver/screen-lock off; Remote Login on for all users; the driver TCC grants (Accessibility for `/usr/libexec/sshd-keygen-wrapper` + `/usr/bin/osascript`; Automation → System Events approved for tester) — the **one manual step**, verified by `verify-golden.sh`. Marker file `/Users/Shared/mattstack-golden.json` `{ "ver": "26", "builtAt": "...", "provisionRev": 1 }` read by `walkthrough.sh` preflight.
+- Key: `$VM_CACHE/id_ed25519` (+ `.pub`), generated if missing; installed for both users.
+
+> **ORCHESTRATOR/MATT:** this task downloads ~25–27 GB per image (≈50 GB disk each once expanded) and needs `brew install openai/tools/tart` + `brew install cirruslabs/cli/sshpass`. Implementers write and `bash -n`/`--dry-run` the scripts; Matt (or the orchestrator, with consent) runs `build-golden.sh 26` then `build-golden.sh 14` and performs the manual TCC clicks when the script pauses.
+
+- [ ] **Step 1: Write `rt-tray/vm/golden/provision-guest.sh`** (copied into the guest and run as `admin` over ssh)
+
+```bash
+#!/bin/bash
+# Runs INSIDE the guest as admin (NOPASSWD sudo). Idempotent.
+# Args: <ver> <tester_pass> <pubkey>
+set -euo pipefail
+VER="$1"; TESTER_PASS="$2"; PUBKEY="$3"
+TESTER=tester
+
+say() { printf '  [guest] %s\n' "$*"; }
+
+# 1. No Apple command line tools (the vanilla templates install them).
+if [ -d /Library/Developer/CommandLineTools ]; then
+  sudo rm -rf /Library/Developer/CommandLineTools
+  sudo pkgutil --forget com.apple.pkg.CLTools_Executables 2>/dev/null || true
+  say "removed CommandLineTools"
+fi
+if xcode-select -p >/dev/null 2>&1; then echo "CLT still present" >&2; exit 1; fi
+
+# 2. No Homebrew.
+for d in /opt/homebrew /usr/local/Homebrew; do
+  [ -d "$d" ] && { sudo rm -rf "$d"; say "removed $d"; }
+done
+command -v brew >/dev/null 2>&1 && { echo "brew still on PATH" >&2; exit 1; }
+sed -i '' '/brew shellenv/d' ~/.zprofile 2>/dev/null || true
+
+# 3. Gatekeeper back ON (vanilla images disable it).
+sudo spctl --global-enable 2>/dev/null || true
+spctl --status | grep -q 'assessments enabled' || { echo "Gatekeeper still disabled" >&2; exit 1; }
+
+# 4. Standard user 'tester' = the console/auto-login user the walkthrough drives.
+if ! id "$TESTER" >/dev/null 2>&1; then
+  sudo sysadminctl -addUser "$TESTER" -fullName "mattstack tester" -password "$TESTER_PASS" 2>/dev/null
+  say "created standard user $TESTER"
+fi
+dseditgroup -o checkmember -m "$TESTER" admin | grep -q "is a member" && { echo "tester must not be admin" >&2; exit 1; }
+sudo mkdir -p "/Users/$TESTER/.ssh"
+echo "$PUBKEY" | sudo tee "/Users/$TESTER/.ssh/authorized_keys" >/dev/null
+sudo chown -R "$TESTER:staff" "/Users/$TESTER/.ssh"; sudo chmod 700 "/Users/$TESTER/.ssh"; sudo chmod 600 "/Users/$TESTER/.ssh/authorized_keys"
+mkdir -p ~/.ssh; echo "$PUBKEY" > ~/.ssh/authorized_keys; chmod 700 ~/.ssh; chmod 600 ~/.ssh/authorized_keys
+
+# Remote Login for everyone (vanilla enables it for admin only by default group).
+sudo systemsetup -setremotelogin on >/dev/null 2>&1 || true
+sudo dseditgroup -o edit -a "$TESTER" -t user com.apple.access_ssh 2>/dev/null || true
+
+# 5. Auto-login as tester; no sleep, no screensaver, no lock.
+# kcpassword holds the XOR-obfuscated password; the vanilla image wrote admin's.
+/usr/bin/python3 -c 'pass' >/dev/null 2>&1 && { echo "python3 resolved — CLT?" >&2; exit 1; }
+sudo defaults write /Library/Preferences/com.apple.loginwindow autoLoginUser "$TESTER"
+sudo /bin/sh -c "$(cat <<'EOS'
+kc() { # kcpassword encoder, pure sh: XOR with Apple's 11-byte key, pad to 12.
+  key="7d 89 52 23 d2 bc dd ea a3 b9 1f"; pw="$1"; out=""; i=0
+  pwlen=${#pw}; padded=$(( (pwlen/12+1)*12 ))
+  while [ $i -lt $padded ]; do
+    ch=0; [ $i -lt $pwlen ] && ch=$(printf '%d' "'$(printf '%s' "$pw" | cut -c$((i+1)))")
+    k=$(echo $key | cut -d' ' -f$((i%11+1))); out="$out$(printf '%02x' $(( ch ^ 0x$k )))"; i=$((i+1))
+  done
+  printf '%s' "$out"
+}
+printf '%s' "$(kc "$1")" | xxd -r -p > /etc/kcpassword; chmod 600 /etc/kcpassword
+EOS
+)" sh "$TESTER_PASS"
+sudo systemsetup -setsleep Off >/dev/null 2>&1 || true
+sudo systemsetup -setcomputersleep Off >/dev/null 2>&1 || true
+sudo defaults write /Library/Preferences/com.apple.screensaver loginWindowIdleTime 0
+sudo -u "$TESTER" defaults -currentHost write com.apple.screensaver idleTime 0
+sudo -u "$TESTER" defaults write NSGlobalDomain AppleKeyboardUIMode -int 3
+# screenLock off must run in the user's session; done post-login by build-golden via ssh-as-tester.
+
+# 6. Marker.
+printf '{ "ver": "%s", "builtAt": "%s", "provisionRev": 1, "consoleUser": "%s" }\n' \
+  "$VER" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$TESTER" | sudo tee /Users/Shared/mattstack-golden.json >/dev/null
+say "provisioned (ver $VER)"
+```
+
+Note for the implementer: `xxd` ships in macOS base (it is part of vim's package under `/usr/bin/xxd`), not CLT — verify in the guest with `command -v xxd` during the dry-run; if absent on 14, replace the encoder's last line with `perl -e 'print pack("H*", $ARGV[0])' "$(kc "$1")"` (perl ships in macOS base through 26).
+
+- [ ] **Step 2: Write `rt-tray/vm/golden/verify-golden.sh`** (host; asserts the golden over ssh; used both at build end and by `walkthrough.sh --verify-golden`)
+
+```bash
+#!/bin/bash
+# Usage: verify-golden.sh <ver> [<vm-name>]   (the VM must be running)
+set -euo pipefail
+source "$(cd "$(dirname "$0")/.." && pwd)/lib/common.sh"
+VER="$1"; VM="${2:-$(vm_golden_name "$VER")}"
+fails=0
+ok()   { vm_log "  ✓ $1"; }
+bad()  { vm_warn "  ✗ $1"; fails=$((fails+1)); }
+t()    { if vm_ssh "$VM_TESTER_USER" "$VM" "$2" >/dev/null 2>&1; then ok "$1"; else bad "$1"; fi; }
+a()    { if vm_ssh "$VM_ADMIN_USER" "$VM" "$2" >/dev/null 2>&1; then ok "$1"; else bad "$1"; fi; }
+
+a "ssh as admin (key)"                 'true'
+t "ssh as tester (key)"                'true'
+t "tester is not admin"                '! dseditgroup -o checkmember -m tester admin | grep -q "is a member"'
+t "no CLT"                             '! xcode-select -p'
+t "no brew"                            '! command -v brew && [ ! -d /opt/homebrew ]'
+t "Gatekeeper enabled"                 'spctl --status | grep -q "assessments enabled"'
+t "auto-login user is tester"          '[ "$(defaults read /Library/Preferences/com.apple.loginwindow autoLoginUser)" = tester ]'
+t "console user is tester"             '[ "$(stat -f%Su /dev/console)" = tester ]'
+t "sleep off"                          'pmset -g | grep -E "^ *sleep" | grep -q " 0"'
+t "screen lock off"                    '[ "$(sysadminctl -screenLock status 2>&1 | grep -c off)" -ge 1 ]'
+t "marker present"                     "grep -q '\"ver\": \"$VER\"' /Users/Shared/mattstack-golden.json"
+t "macOS major matches"                "[ \"\$(sw_vers -productVersion | cut -d. -f1)\" = $VER ]"
+# The manual TCC grants: UI scripting from an ssh session must work as tester.
+t "UI scripting allowed (Accessibility + Automation for sshd-keygen-wrapper)" \
+  'osascript -e "tell application \"System Events\" to get name of first process whose frontmost is true"'
+t "screenshots dir writable (virtiofs share optional at verify time)" 'true'
+
+[ "$fails" -eq 0 ] && { vm_log "golden $VM verified"; exit 0; }
+vm_die "golden $VM: $fails check(s) failed"
+```
+
+- [ ] **Step 3: Write `rt-tray/vm/golden/build-golden.sh`**
+
+```bash
+#!/bin/bash
+# Build mattstack-golden-<ver> from the cirruslabs vanilla image.
+# Usage: build-golden.sh <14|15|26> [--dry-run] [--rebuild]
+# ORCHESTRATOR/MATT: downloads ~25 GB per image; pauses once for manual TCC clicks.
+set -euo pipefail
+source "$(cd "$(dirname "$0")/.." && pwd)/lib/common.sh"
+
+VER="${1:-}"; shift || true
+[ -n "$VER" ] || vm_die "usage: build-golden.sh <14|15|26> [--dry-run] [--rebuild]"
+DRY=0; REBUILD=0
+for a in "$@"; do case "$a" in --dry-run) DRY=1;; --rebuild) REBUILD=1;; *) vm_die "unknown arg $a";; esac; done
+
+IMAGE=$(vm_image_for "$VER"); GOLDEN=$(vm_golden_name "$VER")
+run() { if [ "$DRY" = 1 ]; then vm_log "[dry-run] $*"; else "$@"; fi; }
+
+vm_log "golden: $GOLDEN ← $IMAGE"
+if [ "$DRY" = 0 ]; then
+  vm_require_cmd tart "brew install openai/tools/tart   (old tap: cirruslabs/cli/tart)"
+  vm_require_cmd sshpass "brew install cirruslabs/cli/sshpass"
+  mkdir -p "$VM_CACHE" "$VM_ARTIFACTS"
+  [ -f "$VM_SSH_KEY" ] || ssh-keygen -q -t ed25519 -N '' -C mattstack-vm -f "$VM_SSH_KEY"
+  if tart list 2>/dev/null | awk '{print $2}' | grep -qx "$GOLDEN"; then
+    [ "$REBUILD" = 1 ] || vm_die "$GOLDEN exists; pass --rebuild to replace it"
+    tart stop "$GOLDEN" 2>/dev/null || true; tart delete "$GOLDEN"
+  fi
+fi
+
+run tart clone "$IMAGE" "$GOLDEN"
+run tart set "$GOLDEN" --cpu 4 --memory 8192 --display 1600x1000
+
+if [ "$DRY" = 1 ]; then
+  vm_log "[dry-run] would: tart run $GOLDEN (with graphics) → provision-guest.sh over ssh → pause for TCC clicks → verify-golden.sh → tart stop"
+  exit 0
+fi
+
+tart run "$GOLDEN" --no-audio > "$VM_ARTIFACTS/golden-$VER-tart.log" 2>&1 &
+TART_PID=$!
+trap 'kill $TART_PID 2>/dev/null || true' EXIT
+vm_log "waiting for ssh as admin (password)…"
+start=$(date +%s)
+until vm_ssh_pw "$VM_ADMIN_USER" "$VM_ADMIN_PASS" "$GOLDEN" true 2>/dev/null; do
+  [ $(( $(date +%s) - start )) -gt 600 ] && vm_die "ssh never came up"
+  sleep 5
+done
+
+PUB=$(cat "$VM_SSH_KEY.pub")
+vm_ssh_pw "$VM_ADMIN_USER" "$VM_ADMIN_PASS" "$GOLDEN" "cat > /tmp/provision-guest.sh" < "$VM_ROOT/golden/provision-guest.sh"
+vm_ssh_pw "$VM_ADMIN_USER" "$VM_ADMIN_PASS" "$GOLDEN" "bash /tmp/provision-guest.sh '$VER' '$VM_TESTER_PASS' '$PUB'"
+
+vm_log "rebooting into tester's auto-login session…"
+vm_ssh "$VM_ADMIN_USER" "$GOLDEN" "sudo reboot" || true
+sleep 20
+vm_wait_ssh "$VM_TESTER_USER" "$GOLDEN" 600 || vm_die "tester ssh never came up after reboot"
+vm_ssh "$VM_TESTER_USER" "$GOLDEN" "sysadminctl -screenLock off -password '$VM_TESTER_PASS'" || true
+
+cat <<EOF
+
+  ┌─ MANUAL STEP (once per golden) ─────────────────────────────────────────┐
+  │ In the Tart window (logged in as tester):                                │
+  │  1. System Settings → Privacy & Security → Accessibility → "+" →         │
+  │     ⌘⇧G, add /usr/libexec/sshd-keygen-wrapper, then /usr/bin/osascript;  │
+  │     toggle both ON (authenticate with admin / admin).                    │
+  │  2. Back in this terminal press Enter; the script sends one osascript    │
+  │     over ssh — approve the "sshd-keygen-wrapper wants to control         │
+  │     System Events" Automation prompt in the VM with OK.                  │
+  └──────────────────────────────────────────────────────────────────────────┘
+EOF
+read -r -p "  Press Enter after step 1… " _
+vm_ssh "$VM_TESTER_USER" "$GOLDEN" 'osascript -e "tell application \"System Events\" to get name of first process whose frontmost is true"' || true
+read -r -p "  Approved the Automation prompt? Press Enter to verify… " _
+
+"$VM_ROOT/golden/verify-golden.sh" "$VER" "$GOLDEN"
+vm_log "stopping $GOLDEN (never run the golden again; clone it)"
+tart stop "$GOLDEN"
+wait $TART_PID 2>/dev/null || true
+trap - EXIT
+vm_log "golden $GOLDEN ready"
+```
+
+- [ ] **Step 4: Syntax-check + dry-run**
+
+Run:
+```bash
+bash -n rt-tray/vm/golden/build-golden.sh rt-tray/vm/golden/provision-guest.sh rt-tray/vm/golden/verify-golden.sh
+bash rt-tray/vm/golden/build-golden.sh 26 --dry-run
+bash rt-tray/vm/golden/build-golden.sh 99 --dry-run; echo "exit=$?"
+```
+Expected: no syntax errors; dry-run prints the `tart clone`/`tart set` lines and the "would:" line; `99` prints `no image mapping` and exit 1.
+
+- [ ] **Step 5 (MATT / ORCHESTRATOR with consent): real build**
+
+Run: `brew install openai/tools/tart cirruslabs/cli/sshpass && bash rt-tray/vm/golden/build-golden.sh 26 && bash rt-tray/vm/golden/build-golden.sh 14`
+Expected: each ends with `golden mattstack-golden-<ver> ready` after `verify-golden.sh` prints all ✓. Record the `tart-pull` duration and disk use in the README's "Costs" section (Task 14). If `tart clone` of the 14 image fails, try `15` (`build-golden.sh 15`) and record it.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add rt-tray/vm/golden
+git commit -m "MAT-383: vm — golden image build, guest provisioner, golden verifier
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 3: Artifact helpers — `run/make-dmg.sh`, `run/helpers/appcast-server.ts`, `run/make-appcast.sh`
+
+**Files:**
+- Create: `rt-tray/vm/run/make-dmg.sh`
+- Create: `rt-tray/vm/run/helpers/appcast-server.ts`
+- Create: `rt-tray/vm/run/helpers/__tests__/appcast-server.test.ts`
+- Create: `rt-tray/vm/run/make-appcast.sh`
+
+**Interfaces:**
+- `make-dmg.sh <path/to/mattstack.app> <out.dmg>` → read-only UDZO DMG named `mattstack` containing the app + `/Applications` symlink (what L4 will ship; lets L7 run before L4).
+- `appcast-server` (compiled with `bun build --compile`): `appcast-server <dir> <port>` serves files from `<dir>` on `127.0.0.1:<port>`, logs one line per request to stderr, exits on SIGTERM. Used by `trigger-update.sh` inside the guest.
+- `make-appcast.sh <path/to/mattstack.app> <new-version> <ed-key-file> <out-dir>` → `<out-dir>/mattstack-<new-version>.zip` + `<out-dir>/appcast.xml` (download URL prefix `http://127.0.0.1:8765/`). `CFBundleVersion` is computed from `<new-version>` with L4's scheme `major*1000000+minor*1000+patch` (no separate build arg — Sparkle compares this number, so it must stay monotonic with real releases). Requires `generate_appcast` (Sparkle tools) on `PATH` or at `$SPARKLE_BIN`; dies with the download hint otherwise.
+- Re-point (AFTER L4 T6 merges): when `scripts/release/make-zip.sh` / `scripts/release/make-dmg.sh` exist, `make-dmg.sh` and `make-appcast.sh` call them for the DMG/zip so the artifact under test is L4's recipe; only the loopback `generate_appcast` call stays local. Until then the inline `hdiutil`/`ditto` fallbacks below stand.
+
+- [ ] **Step 1: Write `rt-tray/vm/run/make-dmg.sh`**
+
+```bash
+#!/bin/bash
+# Wrap a built mattstack.app in a DMG shaped like the release artifact.
+# Usage: make-dmg.sh <mattstack.app> <out.dmg>
+set -euo pipefail
+source "$(cd "$(dirname "$0")/.." && pwd)/lib/common.sh"
+APP="${1:-}"; OUT="${2:-}"
+[ -d "$APP" ] && [ -n "$OUT" ] || vm_die "usage: make-dmg.sh <mattstack.app> <out.dmg>"
+[ "$(basename "$APP")" = "mattstack.app" ] || vm_die "bundle must be named mattstack.app (got $(basename "$APP"))"
+REL="$VM_ROOT/../../scripts/release"
+if [ -x "$REL/make-dmg.sh" ]; then
+  # L4's recipe is the artifact under test once it exists.
+  "$REL/make-dmg.sh" "$APP" "$OUT"
+else
+  STAGE=$(mktemp -d); trap 'rm -rf "$STAGE"' EXIT
+  ditto "$APP" "$STAGE/mattstack.app"
+  ln -s /Applications "$STAGE/Applications"
+  rm -f "$OUT"
+  hdiutil create -quiet -volname mattstack -srcfolder "$STAGE" -ov -format UDZO "$OUT"
+fi
+vm_log "dmg → $OUT ($(du -h "$OUT" | cut -f1))"
+```
+
+- [ ] **Step 2: Write the failing test `rt-tray/vm/run/helpers/__tests__/appcast-server.test.ts`**
+
+```ts
+import { describe, test, expect, afterAll } from "bun:test";
+import { mkdtempSync, writeFileSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+
+const dir = mkdtempSync(join(tmpdir(), "appcast-"));
+writeFileSync(join(dir, "appcast.xml"), "<rss/>");
+writeFileSync(join(dir, "mattstack-9.9.9.zip"), "zipbytes");
+const port = 18765 + Math.floor(Math.random() * 1000);
+const proc = Bun.spawn(["bun", join(import.meta.dir, "..", "appcast-server.ts"), dir, String(port)], {
+  stdout: "pipe", stderr: "pipe",
+});
+afterAll(() => proc.kill());
+
+async function ready() {
+  for (let i = 0; i < 50; i++) {
+    try { await fetch(`http://127.0.0.1:${port}/appcast.xml`); return; } catch { await Bun.sleep(100); }
+  }
+  throw new Error("server never came up");
+}
+
+describe("appcast-server", () => {
+  test("serves files from dir with content types", async () => {
+    await ready();
+    const r = await fetch(`http://127.0.0.1:${port}/appcast.xml`);
+    expect(r.status).toBe(200);
+    expect(r.headers.get("content-type")).toContain("application/rss+xml");
+    expect(await r.text()).toBe("<rss/>");
+    const z = await fetch(`http://127.0.0.1:${port}/mattstack-9.9.9.zip`);
+    expect(z.status).toBe(200);
+    expect(z.headers.get("content-type")).toBe("application/zip");
+    expect(z.headers.get("content-length")).toBe("8");
+  });
+  test("404 for missing and refuses path traversal", async () => {
+    expect((await fetch(`http://127.0.0.1:${port}/nope.xml`)).status).toBe(404);
+    expect((await fetch(`http://127.0.0.1:${port}/../appcast.xml`)).status).toBe(404);
+  });
+});
+```
+
+- [ ] **Step 3: Run it to see it fail**
+
+Run: `bun test rt-tray/vm/run/helpers/__tests__/appcast-server.test.ts`
+Expected: fails — `server never came up` (file missing).
+
+- [ ] **Step 4: Write `rt-tray/vm/run/helpers/appcast-server.ts`**
+
+```ts
+// Static file server for the in-guest Sparkle appcast. Loopback only, so the
+// guest never crosses macOS 15's Local Network Privacy boundary to the host.
+import { existsSync, statSync } from "fs";
+import { join, normalize, resolve, extname } from "path";
+
+const [dir, portArg] = process.argv.slice(2);
+if (!dir || !portArg) {
+  console.error("usage: appcast-server <dir> <port>");
+  process.exit(2);
+}
+const root = resolve(dir);
+const port = Number(portArg);
+const types: Record<string, string> = {
+  ".xml": "application/rss+xml; charset=utf-8",
+  ".zip": "application/zip",
+  ".dmg": "application/x-apple-diskimage",
+  ".delta": "application/octet-stream",
+  ".txt": "text/plain; charset=utf-8",
+  ".html": "text/html; charset=utf-8",
+};
+
+const server = Bun.serve({
+  hostname: "127.0.0.1",
+  port,
+  fetch(req) {
+    const path = normalize(decodeURIComponent(new URL(req.url).pathname));
+    const file = join(root, path);
+    const ok = file.startsWith(root + "/") && existsSync(file) && statSync(file).isFile();
+    console.error(`${new Date().toISOString()} ${req.method} ${path} → ${ok ? 200 : 404}`);
+    if (!ok) return new Response("not found", { status: 404 });
+    const size = statSync(file).size;
+    return new Response(Bun.file(file), {
+      headers: {
+        "content-type": types[extname(file)] ?? "application/octet-stream",
+        "content-length": String(size),
+        "cache-control": "no-store",
+      },
+    });
+  },
+});
+console.error(`appcast-server: serving ${root} on http://127.0.0.1:${server.port}/`);
+process.on("SIGTERM", () => { server.stop(); process.exit(0); });
+process.on("SIGINT", () => { server.stop(); process.exit(0); });
+```
+
+- [ ] **Step 5: Run the test, expect pass; compile once to prove `--compile` works**
+
+Run:
+```bash
+bun test rt-tray/vm/run/helpers/__tests__/appcast-server.test.ts
+mkdir -p rt-tray/vm/.cache && bun build --compile rt-tray/vm/run/helpers/appcast-server.ts --outfile rt-tray/vm/.cache/appcast-server && file rt-tray/vm/.cache/appcast-server | grep -q Mach-O && echo compiled-ok
+```
+Expected: 2 pass; `compiled-ok`.
+
+- [ ] **Step 6: Write `rt-tray/vm/run/make-appcast.sh`**
+
+```bash
+#!/bin/bash
+# Build the vN+1 Sparkle enclosure + appcast from a built app, for the update phase.
+# Usage: make-appcast.sh <mattstack.app> <new-version> <ed-private-key-file> <out-dir> [--sign <identity>]
+# The app's SUPublicEDKey must match the private key (L4 build: SPARKLE_PUBLIC_ED_KEY override).
+# CFBundleVersion = major*1000000 + minor*1000 + patch — the same scheme as the release build, so
+# Sparkle's numeric comparison stays monotonic against real releases.
+set -euo pipefail
+source "$(cd "$(dirname "$0")/.." && pwd)/lib/common.sh"
+APP="${1:-}"; NEWV="${2:-}"; KEY="${3:-}"; OUT="${4:-}"; shift 4 2>/dev/null || true
+SIGN="-"
+while [ $# -gt 0 ]; do case "$1" in --sign) SIGN="$2"; shift 2;; *) vm_die "unknown arg $1";; esac; done
+[ -d "$APP" ] && [ -n "$NEWV" ] && [ -f "$KEY" ] && [ -n "$OUT" ] \
+  || vm_die "usage: make-appcast.sh <mattstack.app> <new-version> <ed-key-file> <out-dir> [--sign <identity>]"
+echo "$NEWV" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$' || vm_die "new-version must be X.Y.Z (got $NEWV)"
+NEWB=$(echo "$NEWV" | awk -F. '{ printf "%d", $1*1000000 + $2*1000 + $3 }')
+
+GEN="${SPARKLE_BIN:+$SPARKLE_BIN/}generate_appcast"
+command -v "$GEN" >/dev/null 2>&1 || vm_die "generate_appcast not found — download Sparkle-<ver>.tar.xz from https://github.com/sparkle-project/Sparkle/releases, extract, and set SPARKLE_BIN=<extracted>/bin"
+
+mkdir -p "$OUT"; STAGE=$(mktemp -d); trap 'rm -rf "$STAGE"' EXIT
+ditto "$APP" "$STAGE/mattstack.app"
+PL="$STAGE/mattstack.app/Contents/Info.plist"
+/usr/libexec/PlistBuddy -c "Set :CFBundleShortVersionString $NEWV" "$PL"
+/usr/libexec/PlistBuddy -c "Set :CFBundleVersion $NEWB" "$PL"
+# Inside-out re-sign: every nested Mach-O first, then the bundle (never --deep).
+find "$STAGE/mattstack.app/Contents" -type f -perm -u+x -not -path '*/Info.plist' | while read -r f; do
+  file -b "$f" | grep -q Mach-O && codesign --force --options runtime --timestamp=none --sign "$SIGN" "$f" 2>/dev/null || true
+done
+codesign --force --options runtime --timestamp=none --sign "$SIGN" "$STAGE/mattstack.app"
+rm -f "$OUT"/mattstack-*.zip "$OUT"/appcast.xml
+REL="$VM_ROOT/../../scripts/release"
+if [ -x "$REL/make-zip.sh" ]; then
+  "$REL/make-zip.sh" "$STAGE/mattstack.app" "$OUT/mattstack-$NEWV.zip"
+else
+  (cd "$STAGE" && ditto -c -k --sequesterRsrc --keepParent mattstack.app "$OUT/mattstack-$NEWV.zip")
+fi
+"$GEN" --ed-key-file "$KEY" --download-url-prefix "http://127.0.0.1:8765/" -o "$OUT/appcast.xml" "$OUT"
+vm_log "appcast → $OUT/appcast.xml (enclosure mattstack-$NEWV.zip, build $NEWB)"
+```
+
+- [ ] **Step 7: Syntax-check + dry-run `make-dmg.sh` against the checked-in prod bundle**
+
+Run:
+```bash
+bash -n rt-tray/vm/run/make-dmg.sh rt-tray/vm/run/make-appcast.sh
+ls -d rt-tray/mattstack.app >/dev/null 2>&1 || (cd rt-tray && ./build.sh release)
+bash rt-tray/vm/run/make-dmg.sh rt-tray/mattstack.app rt-tray/vm/.cache/mattstack-local.dmg && hdiutil imageinfo rt-tray/vm/.cache/mattstack-local.dmg | grep -q "Format: UDZO" && echo dmg-ok
+bash rt-tray/vm/run/make-appcast.sh rt-tray/mattstack.app 0.0.1 /dev/null /tmp/x; echo "exit=$?"
+bash rt-tray/vm/run/make-appcast.sh rt-tray/mattstack.app 2.8 /dev/null /tmp/x; echo "exit=$?"
+```
+Expected: `dmg-ok`; the first make-appcast exits 1 with the `generate_appcast not found` hint (or the usage line if `/dev/null` fails `-f` — `-f /dev/null` is true, so the hint is the expected message); the second exits 1 with `new-version must be X.Y.Z`. (Sanity: `echo 2.8.0 | awk -F. '{ printf "%d", $1*1000000 + $2*1000 + $3 }'` prints `2008000`.)
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add rt-tray/vm/run/make-dmg.sh rt-tray/vm/run/make-appcast.sh rt-tray/vm/run/helpers
+git commit -m "MAT-383: vm — DMG/appcast builders and the loopback appcast server
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 4: Host-side screenshot — `run/host/winid.swift` + `run/host/capture.sh`
+
+**Files:**
+- Create: `rt-tray/vm/run/host/winid.swift`
+- Create: `rt-tray/vm/run/host/capture.sh`
+
+**Interfaces:**
+- `winid.swift <vm-name>` → prints the CGWindowID of the Tart window titled `<vm-name>` (exit 1 if none). Run via `swift run/host/winid.swift …` (CLT `swift` exists on Matt's host — `rt-tray/build.sh` already depends on it).
+- `capture.sh <vm-name> <out.png>` → `screencapture -x -l <id> <out.png>`; exit 0 + file, or exit 1 with a reason printed. Needs Screen Recording for the host terminal app (MATT one-time; the script detects an all-black/0-byte result and says so).
+
+- [ ] **Step 1: Write `rt-tray/vm/run/host/winid.swift`**
+
+```swift
+import CoreGraphics
+import Foundation
+
+let args = CommandLine.arguments
+guard args.count == 2 else {
+    FileHandle.standardError.write("usage: winid <window title>\n".data(using: .utf8)!)
+    exit(2)
+}
+let wanted = args[1]
+let list = CGWindowListCopyWindowInfo([.optionOnScreenOnly, .excludeDesktopElements], kCGNullWindowID) as? [[String: Any]] ?? []
+for w in list {
+    let owner = w[kCGWindowOwnerName as String] as? String ?? ""
+    let name = w[kCGWindowName as String] as? String ?? ""
+    let layer = w[kCGWindowLayer as String] as? Int ?? 0
+    if owner.lowercased() == "tart" && name == wanted && layer == 0, let id = w[kCGWindowNumber as String] as? Int {
+        print(id)
+        exit(0)
+    }
+}
+FileHandle.standardError.write("no on-screen tart window titled \(wanted)\n".data(using: .utf8)!)
+exit(1)
+```
+
+- [ ] **Step 2: Write `rt-tray/vm/run/host/capture.sh`**
+
+```bash
+#!/bin/bash
+# Screenshot the Tart window of <vm> into <out.png>, from the host.
+# Usage: capture.sh <vm-name> <out.png>
+set -euo pipefail
+source "$(cd "$(dirname "$0")/../.." && pwd)/lib/common.sh"
+VM="${1:-}"; OUT="${2:-}"
+[ -n "$VM" ] && [ -n "$OUT" ] || vm_die "usage: capture.sh <vm-name> <out.png>"
+WINID_BIN="$VM_CACHE/winid"
+if [ ! -x "$WINID_BIN" ] || [ "$VM_ROOT/run/host/winid.swift" -nt "$WINID_BIN" ]; then
+  mkdir -p "$VM_CACHE"
+  swiftc -O -o "$WINID_BIN" "$VM_ROOT/run/host/winid.swift" 2>/dev/null || vm_die "swiftc failed — Apple CLT required on the host"
+fi
+WID=$("$WINID_BIN" "$VM") || vm_die "no Tart window for $VM (running with --no-graphics? then screenshots are unavailable)"
+screencapture -x -o -l "$WID" "$OUT" || vm_die "screencapture failed"
+[ -s "$OUT" ] || vm_die "empty screenshot — grant Screen Recording to your terminal app (System Settings → Privacy & Security → Screen & System Audio Recording) and retry"
+# A capture without Screen Recording permission is a solid desktop-coloured image; detect the degenerate 1-colour case.
+if command -v sips >/dev/null 2>&1; then
+  W=$(sips -g pixelWidth "$OUT" 2>/dev/null | awk '/pixelWidth/{print $2}')
+  [ "${W:-0}" -gt 100 ] || vm_die "screenshot too small ($W px) — window minimised?"
+fi
+vm_log "screenshot → $OUT"
+```
+
+- [ ] **Step 3: Syntax-check + compile + negative run**
+
+Run:
+```bash
+bash -n rt-tray/vm/run/host/capture.sh
+mkdir -p rt-tray/vm/.cache && swiftc -O -o rt-tray/vm/.cache/winid rt-tray/vm/run/host/winid.swift && echo winid-compiled
+rt-tray/vm/.cache/winid no-such-vm; echo "exit=$?"
+bash rt-tray/vm/run/host/capture.sh no-such-vm /tmp/x.png; echo "exit=$?"
+```
+Expected: `winid-compiled`; `no on-screen tart window titled no-such-vm` exit 1; capture.sh prints the `no Tart window` reason, exit 1.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add rt-tray/vm/run/host
+git commit -m "MAT-383: vm — host-side Tart window capture
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 5: Guest install — `run/guest/install-app.sh`
+
+**Files:**
+- Create: `rt-tray/vm/run/guest/install-app.sh`
+
+**Interfaces:**
+- Runs in the guest. Invoked twice by `walkthrough.sh`: `install-app.sh copy <dmg> [--quarantine|--no-quarantine]` as **admin** (mount, copy to `/Applications` like Finder-with-admin-auth does, detach), then `install-app.sh launch [--env KEY=VAL …] [--arg <launch-arg> …]` as **tester** (`open --env K=V "$APP" --args <launch-args>`, wait for the process + menu bar item, report). Exit codes: 0 ok, 2 Gatekeeper blocked (dialog detected), 1 other. The update phase launches the **prod** app with `--env MATTSTACK_APPCAST_URL=http://127.0.0.1:8765/appcast.xml --arg --allow-appcast-override` — L3 T10 honours the env only for dev builds or with that argument; every driver-initiated relaunch repeats the same env + arg.
+- Writes `$GUEST_RUN/logs/install-app.log` where `GUEST_RUN=/Volumes/My Shared Files/run` (the host run dir).
+
+- [ ] **Step 1: Write `rt-tray/vm/run/guest/install-app.sh`**
+
+```bash
+#!/bin/bash
+# Guest side of the install phase. See header of each subcommand.
+set -euo pipefail
+GUEST_RUN="${GUEST_RUN:-/Volumes/My Shared Files/run}"
+LOG="$GUEST_RUN/logs/install-app.log"; mkdir -p "$(dirname "$LOG")"
+say() { printf '%s %s\n' "$(date -u +%H:%M:%S)" "$*" | tee -a "$LOG" >&2; }
+APP=/Applications/mattstack.app
+
+cmd="${1:-}"; shift || true
+case "$cmd" in
+  copy)
+    DMG="${1:-}"; shift || true; Q=1
+    for a in "$@"; do case "$a" in --quarantine) Q=1;; --no-quarantine) Q=0;; esac; done
+    [ -f "$DMG" ] || { say "no dmg at $DMG"; exit 1; }
+    if [ "$Q" = 1 ]; then
+      # Simulate a browser download so Gatekeeper assesses the app on first open.
+      xattr -w com.apple.quarantine "0083;$(printf '%x' "$(date +%s)");Safari;$(uuidgen)" "$DMG"
+      say "quarantine set on $(basename "$DMG")"
+    else
+      xattr -d com.apple.quarantine "$DMG" 2>/dev/null || true
+      say "quarantine NOT set (unnotarised build mode)"
+    fi
+    hdiutil detach /Volumes/mattstack -quiet 2>/dev/null || true
+    hdiutil attach "$DMG" -nobrowse -quiet -mountpoint /Volumes/mattstack
+    [ -d /Volumes/mattstack/mattstack.app ] || { say "dmg has no mattstack.app"; hdiutil detach /Volumes/mattstack -quiet; exit 1; }
+    sudo rm -rf "$APP"
+    sudo ditto /Volumes/mattstack/mattstack.app "$APP"   # preserves xattrs incl. quarantine, like Finder
+    sudo chown -R root:admin "$APP"
+    hdiutil detach /Volumes/mattstack -quiet
+    say "copied to $APP ($(/usr/libexec/PlistBuddy -c 'Print :CFBundleShortVersionString' "$APP/Contents/Info.plist"))"
+    codesign --verify --deep --strict "$APP" 2>>"$LOG" && say "codesign verifies" || say "codesign does NOT verify (ad-hoc/dev build?)"
+    spctl --assess --type execute "$APP" 2>>"$LOG" && say "spctl: accepted" || say "spctl: rejected (expect a Gatekeeper dialog if quarantined)"
+    ;;
+  launch)
+    ENVS=(); ARGS=()
+    while [ $# -gt 0 ]; do case "$1" in --env) ENVS+=("--env" "$2"); shift 2;; --arg) ARGS+=("$2"); shift 2;; *) shift;; esac; done
+    [ -d "$APP" ] || { say "no app at $APP"; exit 1; }
+    # `open`: env flags before the app path, the app's own argv after --args.
+    if [ "${#ARGS[@]}" -gt 0 ]; then open ${ENVS[@]+"${ENVS[@]}"} "$APP" --args "${ARGS[@]}"
+    else open ${ENVS[@]+"${ENVS[@]}"} "$APP"; fi
+    for i in $(seq 1 30); do
+      sleep 1
+      if pgrep -x mattstack >/dev/null; then say "process up after ${i}s"; break; fi
+      # Gatekeeper refusal shows a CoreServicesUIAgent alert; detect and report, don't dismiss.
+      if osascript -e 'tell application "System Events" to exists (window 1 of process "CoreServicesUIAgent")' 2>/dev/null | grep -q true; then
+        say "Gatekeeper dialog present — app blocked"; exit 2
+      fi
+    done
+    pgrep -x mattstack >/dev/null || { say "mattstack never started"; exit 1; }
+    # Menu bar extra = the app's own status item; give it a few seconds to appear.
+    for i in $(seq 1 20); do
+      if osascript -e 'tell application "System Events" to tell process "mattstack" to count menu bar items of menu bar 2' 2>/dev/null | grep -qE '^[1-9]'; then
+        say "menu bar item present"; exit 0; fi
+      sleep 1
+    done
+    say "no menu bar item after 20s (app running)"; exit 0
+    ;;
+  *) echo "usage: install-app.sh copy <dmg> [--quarantine|--no-quarantine] | launch [--env K=V]... [--arg <launch-arg>]..." >&2; exit 1;;
+esac
+```
+
+- [ ] **Step 2: Syntax-check + host-only dry run of the parser**
+
+Run: `bash -n rt-tray/vm/run/guest/install-app.sh && GUEST_RUN=/tmp/gr bash rt-tray/vm/run/guest/install-app.sh copy /nonexistent.dmg; echo "exit=$?"; bash rt-tray/vm/run/guest/install-app.sh; echo "exit=$?"`
+Expected: `no dmg at /nonexistent.dmg` exit 1; usage exit 1. (Never run `launch` on the host — it would `open` the real `/Applications/mattstack.app`.)
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add rt-tray/vm/run/guest/install-app.sh
+git commit -m "MAT-383: vm — guest DMG install and first launch
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 6: UI-scripting library + the five screens — `run/guest/ax.sh`, `run/guest/drive-setup.sh`
+
+**AFTER L3 T12–T16 merge** (the AXIDs below come from L3's `AccessibilityIDs.swift`; the scripts can be written now and fail fast on any missing id until the app ships them).
+
+**Files:**
+- Create: `rt-tray/vm/run/guest/ax.sh`
+- Create: `rt-tray/vm/run/guest/drive-setup.sh`
+
+**Interfaces:**
+- `ax.sh` (sourced in the guest): `ax_app` = `mattstack`; `ax_wait_window <title-substr> <timeout>`; `ax_wait_screen <screen> <timeout>` (waits for `setup.<screen>.screen`); `ax_find <axid>` → prints AppleScript reference or fails; `ax_click <axid>`; `ax_click_button_named <name> [<process>]`; `ax_type <text>` (keystroke into focused field); `ax_set_field <axid> <text>`; `ax_status <rowId>` → the row's status text (`ready|missing|needs-you|…` via the `setup.checklist.row.<id>.status` AXIdentifier `value`/`description`); `ax_wait_status <rowId> <status> <timeout>`; `ax_admin_auth` (fills the SecurityAgent dialog with `admin`/`$VM_ADMIN_PASS`); `ax_allow_notifications` (clicks Allow in the UNC prompt if present); `ax_shot <name>` → asks the HOST to capture by touching `$GUEST_RUN/in/shot-<name>.req` and waiting for `.done` (host loop in `walkthrough.sh`); `ax_fail <msg>` → shot + exit 1.
+- `drive-setup.sh <scenario> [--team-slug vmtest] [--pat-env MATTSTACK_VMTEST_PAT] [--invite-code-file <path>]` runs the five screens; per-screen functions `screen_welcome`, `screen_team`, `screen_readiness`, `screen_install`, `screen_done`; exit 0 when "Done" is reached and Finish clicked; exit 1 with the failing screen in the last log line. Scenarios: `create` (default), `join` (needs invite code file), `restore` (reserved; exits 3 "not implemented"). Env `DRIVER_LAUNCH_ARGS` (set by `walkthrough.sh`; the `install-app.sh launch` flags) is replayed on any driver-initiated relaunch so `MATTSTACK_APPCAST_URL` + `--allow-appcast-override` survive.
+- AXIdentifiers are L3's `AccessibilityIDs.swift` names (cross-plan review §5 #43): screens `setup.<welcome|team|checklist|install|done>.screen`; `setup.<screen>.continue`; team `setup.team.card.create|join`, `setup.team.create.name`, `setup.team.join.code`; checklist `setup.checklist.row.<rowId>[.action|.status]`, `setup.checklist.connect.field.token`, `setup.checklist.connect.submit`, `setup.checklist.relaunch`; install `setup.install.retry`, `setup.install.step.<id>`; done `setup.done.continue`. Row ids are L1's (`perm.login-items`, not `perm.loginItems`). Until the app ships them, every `ax_find` fails fast with `axid not found: <id>` and the phase is a clean `fail`, never a hang.
+
+- [ ] **Step 1: Write `rt-tray/vm/run/guest/ax.sh`**
+
+```bash
+#!/bin/bash
+# osascript/System Events helpers for driving mattstack.app in the guest.
+# Source only. Requires Accessibility + Automation granted to sshd-keygen-wrapper (golden step).
+GUEST_RUN="${GUEST_RUN:-/Volumes/My Shared Files/run}"
+AX_APP="${AX_APP:-mattstack}"
+: "${VM_ADMIN_USER:=admin}"; : "${VM_ADMIN_PASS:=admin}"
+AX_LOG="$GUEST_RUN/logs/drive.log"; mkdir -p "$(dirname "$AX_LOG")" 2>/dev/null || true
+
+ax_log()  { printf '%s %s\n' "$(date -u +%H:%M:%S)" "$*" | tee -a "$AX_LOG" >&2; }
+ax_osa()  { osascript -e "$1" 2>>"$AX_LOG"; }
+
+# Host-side capture handshake: the host watches in/ for *.req files.
+ax_shot() {
+  local name="$1" req="$GUEST_RUN/in/shot-$name.req" done="$GUEST_RUN/in/shot-$name.done"
+  rm -f "$done"; : > "$req"
+  for _ in $(seq 1 40); do [ -f "$done" ] && { ax_log "shot $name"; return 0; }; sleep 0.5; done
+  ax_log "shot $name: host did not respond (no graphics?)"; return 0
+}
+ax_fail() { ax_log "FAIL: $*"; ax_shot "fail-$(date +%s)"; exit 1; }
+
+ax_wait_window() {  # <title-substring> <timeout-s>
+  local t="$1" n="${2:-30}"
+  while [ "$n" -gt 0 ]; do
+    ax_osa "tell application \"System Events\" to tell process \"$AX_APP\" to get name of every window" 2>/dev/null | grep -q "$t" && return 0
+    sleep 1; n=$((n-1))
+  done
+  return 1
+}
+
+ax_wait_screen() {  # <welcome|team|checklist|install|done> <timeout-s> — waits for setup.<screen>.screen
+  local n="${2:-30}"
+  while [ "$n" -gt 0 ]; do
+    ax_find "setup.$1.screen" >/dev/null 2>&1 && return 0
+    sleep 1; n=$((n-1))
+  done
+  return 1
+}
+
+# Find a UI element by AXIdentifier anywhere under window 1; prints a reference path usable in `tell`.
+ax_find() {  # <axid>
+  ax_osa "
+    on walk(el, wanted)
+      try
+        if (value of attribute \"AXIdentifier\" of el) is wanted then return el
+      end try
+      try
+        repeat with c in UI elements of el
+          set r to my walk(c, wanted)
+          if r is not missing value then return r
+        end repeat
+      end try
+      return missing value
+    end walk
+    tell application \"System Events\" to tell process \"$AX_APP\"
+      set r to my walk(window 1, \"$1\")
+      if r is missing value then error \"axid not found: $1\"
+      return (r as text)
+    end tell" 2>/dev/null
+}
+
+ax_click() {  # <axid>
+  ax_osa "
+    on walk(el, wanted)
+      try
+        if (value of attribute \"AXIdentifier\" of el) is wanted then return el
+      end try
+      try
+        repeat with c in UI elements of el
+          set r to my walk(c, wanted)
+          if r is not missing value then return r
+        end repeat
+      end try
+      return missing value
+    end walk
+    tell application \"System Events\" to tell process \"$AX_APP\"
+      set frontmost to true
+      set r to my walk(window 1, \"$1\")
+      if r is missing value then error \"axid not found: $1\"
+      click r
+    end tell" || ax_fail "click $1"
+  ax_log "clicked $1"
+}
+
+ax_click_button_named() {  # <name> [<process>]
+  local p="${2:-$AX_APP}"
+  ax_osa "tell application \"System Events\" to tell process \"$p\" to click (first button of window 1 whose name is \"$1\")" >/dev/null || return 1
+  ax_log "clicked button '$1' in $p"
+}
+
+ax_set_field() {  # <axid> <text>   (text never logged)
+  ax_osa "
+    on walk(el, wanted)
+      try
+        if (value of attribute \"AXIdentifier\" of el) is wanted then return el
+      end try
+      try
+        repeat with c in UI elements of el
+          set r to my walk(c, wanted)
+          if r is not missing value then return r
+        end repeat
+      end try
+      return missing value
+    end walk
+    tell application \"System Events\" to tell process \"$AX_APP\"
+      set frontmost to true
+      set r to my walk(window 1, \"$1\")
+      if r is missing value then error \"axid not found: $1\"
+      set focused of r to true
+      keystroke \"a\" using command down
+      keystroke \"$2\"
+    end tell" || ax_fail "set field $1"
+  ax_log "filled $1"
+}
+
+ax_status() {  # <rowId> → status string (the app exposes it as the row status element's value)
+  ax_osa "
+    on walk(el, wanted)
+      try
+        if (value of attribute \"AXIdentifier\" of el) is wanted then return el
+      end try
+      try
+        repeat with c in UI elements of el
+          set r to my walk(c, wanted)
+          if r is not missing value then return r
+        end repeat
+      end try
+      return missing value
+    end walk
+    tell application \"System Events\" to tell process \"$AX_APP\"
+      set r to my walk(window 1, \"setup.checklist.row.$1.status\")
+      if r is missing value then error \"axid not found: setup.checklist.row.$1.status\"
+      try
+        return value of r as text
+      on error
+        return description of r as text
+      end try
+    end tell" 2>/dev/null
+}
+
+ax_wait_status() {  # <rowId> <status> <timeout-s>
+  local n="${3:-60}" s
+  while [ "$n" -gt 0 ]; do
+    s=$(ax_status "$1" || true)
+    [ "$s" = "$2" ] && { ax_log "row $1 = $2"; return 0; }
+    sleep 1; n=$((n-1))
+  done
+  ax_log "row $1 stuck at '${s:-?}' (wanted $2)"; return 1
+}
+
+# SecurityAgent admin prompt (privileged step, FDA/Login Items toggles by a standard user).
+ax_admin_auth() {
+  local n=30
+  while [ "$n" -gt 0 ]; do
+    if ax_osa 'tell application "System Events" to exists window 1 of process "SecurityAgent"' 2>/dev/null | grep -q true; then
+      ax_osa "tell application \"System Events\" to tell process \"SecurityAgent\" to tell window 1
+        set value of text field 1 to \"$VM_ADMIN_USER\"
+        set value of text field 2 to \"$VM_ADMIN_PASS\"
+        click (first button whose name is \"OK\" or name is \"Unlock\" or name is \"Modify Settings\" or name is \"Install Helper\")
+      end tell" >/dev/null && { ax_log "admin auth filled"; return 0; }
+    fi
+    sleep 1; n=$((n-1))
+  done
+  return 1
+}
+
+ax_allow_notifications() {
+  ax_osa 'tell application "System Events" to tell process "UserNotificationCenter" to click (first button of window 1 whose name is "Allow")' >/dev/null 2>&1 \
+    && ax_log "notifications: Allow clicked" || ax_log "notifications: no prompt visible"
+}
+
+# System Settings: toggle the app's switch in a Privacy pane opened by the app's button.
+ax_toggle_in_system_settings() {  # <row label e.g. mattstack>
+  ax_osa "tell application \"System Events\" to tell process \"System Settings\"
+    repeat 20 times
+      if exists window 1 then exit repeat
+      delay 0.5
+    end repeat
+    tell window 1
+      set tgt to first checkbox of (first group whose name contains \"$1\" or description contains \"$1\") of (first scroll area of group 1 of splitter group 1 of group 1)
+      if value of tgt is 0 then click tgt
+    end tell
+  end tell" >/dev/null 2>&1 || {
+    # Layout differs across 14/15/26; fall back to a breadth-first search for a checkbox near a static text with the label.
+    ax_osa "tell application \"System Events\" to tell process \"System Settings\" to tell window 1
+      set cbs to every checkbox of entire contents
+      repeat with cb in cbs
+        try
+          if (name of cb contains \"$1\") or (description of cb contains \"$1\") then
+            if value of cb is 0 then click cb
+            return
+          end if
+        end try
+      end repeat
+      error \"no checkbox for $1\"
+    end tell" >/dev/null || return 1
+  }
+  ax_log "System Settings: toggled $1"
+  ax_admin_auth || true
+  ax_osa 'tell application "System Settings" to quit' >/dev/null 2>&1 || true
+}
+```
+
+- [ ] **Step 2: Write `rt-tray/vm/run/guest/drive-setup.sh`**
+
+```bash
+#!/bin/bash
+# Drive the five setup screens of mattstack.app (spec §4) in the guest as tester.
+# Usage: drive-setup.sh <create|join|restore> [--team-slug vmtest] [--pat-env MATTSTACK_VMTEST_PAT] [--invite-code-file <p>]
+set -euo pipefail
+HERE="$(cd "$(dirname "$0")" && pwd)"; source "$HERE/ax.sh"
+SCENARIO="${1:-create}"; shift || true
+SLUG=vmtest; PAT_ENV=MATTSTACK_VMTEST_PAT; CODE_FILE=""
+while [ $# -gt 0 ]; do case "$1" in
+  --team-slug) SLUG="$2"; shift 2;; --pat-env) PAT_ENV="$2"; shift 2;; --invite-code-file) CODE_FILE="$2"; shift 2;;
+  *) ax_fail "unknown arg $1";; esac; done
+PAT="${!PAT_ENV:-}"
+RT="$HOME/.local/bin/rt"
+DRIVER_LAUNCH_ARGS="${DRIVER_LAUNCH_ARGS:-}"
+
+# If the app has to be relaunched by the driver, replay the exact launch env/args (appcast override).
+relaunch_app() {
+  # shellcheck disable=SC2086
+  bash "$HERE/install-app.sh" launch $DRIVER_LAUNCH_ARGS >>"$AX_LOG" 2>&1 || return 1
+}
+
+screen_welcome() {
+  ax_wait_window "mattstack" 60 || ax_fail "setup window never appeared"
+  ax_wait_screen welcome 10 || ax_fail "setup.welcome.screen axid missing (L3 AccessibilityIDs)"
+  ax_shot 01-welcome
+  ax_click setup.welcome.continue
+}
+
+screen_team() {
+  ax_wait_screen team 10 || ax_fail "setup.team.screen did not appear"
+  case "$SCENARIO" in
+    create)
+      ax_click setup.team.card.create
+      ax_set_field setup.team.create.name "$SLUG"
+      ax_shot 02-team-create
+      ;;
+    join)
+      [ -n "$CODE_FILE" ] && [ -f "$CODE_FILE" ] || ax_fail "join needs --invite-code-file"
+      ax_click setup.team.card.join
+      ax_set_field setup.team.join.code "$(tr -d '\n' < "$CODE_FILE")"
+      ax_shot 02-team-join
+      ;;
+    restore) ax_log "restore scenario not implemented"; exit 3;;
+  esac
+  ax_click setup.team.continue
+  # Continue validates the remote(s) with git ls-remote; allow time, then the checklist must appear.
+  ax_wait_screen checklist 60 || ax_fail "setup.checklist.screen did not appear after team Continue"
+}
+
+screen_readiness() {
+  ax_shot 03-readiness-initial
+  # Accounts → GitHub token (the guest has no gh; the PAT is typed, never logged, masked on screen).
+  if ax_find setup.checklist.row.account.github >/dev/null 2>&1; then
+    [ -n "$PAT" ] || ax_fail "account.github row present but \$$PAT_ENV is empty on the host"
+    ax_click setup.checklist.row.account.github.action
+    ax_set_field setup.checklist.connect.field.token "$PAT"
+    ax_click setup.checklist.connect.submit
+    ax_wait_status account.github ready 60 || ax_fail "github row not ready"
+  fi
+  # Full Disk Access: button → System Settings → toggle (admin auth for a standard user) → Relaunch.
+  if [ "$(ax_status perm.fda || true)" != ready ]; then
+    ax_click setup.checklist.row.perm.fda.action
+    ax_toggle_in_system_settings mattstack || ax_fail "could not toggle FDA in System Settings"
+    ax_shot 03-fda-toggled
+    # The checklist now offers "Relaunch mattstack" (setup.checklist.relaunch); the app re-execs itself
+    # with its current arguments + environment (L3 T10/T18), so the appcast override survives.
+    ax_wait_status perm.fda needs-you 20 || true
+    ax_click setup.checklist.relaunch
+    sleep 3
+    if ! ax_wait_window "mattstack" 60; then
+      ax_log "app did not come back by itself after FDA relaunch — relaunching with the driver's env/args"
+      relaunch_app || ax_fail "app did not come back after FDA relaunch"
+      ax_wait_window "mattstack" 60 || ax_fail "app did not come back after FDA relaunch"
+    fi
+    ax_wait_screen checklist 30 || ax_fail "checklist did not return after FDA relaunch"
+    ax_wait_status perm.fda ready 30 || ax_fail "FDA not applied after relaunch"
+  fi
+  # Background services (Login Items): register → if requiresApproval, open pane and toggle.
+  if [ "$(ax_status perm.login-items || true)" != ready ]; then
+    ax_click setup.checklist.row.perm.login-items.action
+    sleep 2
+    if [ "$(ax_status perm.login-items || true)" != ready ]; then
+      ax_toggle_in_system_settings mattstack || ax_log "login items toggle not found (may already be enabled)"
+    fi
+    ax_wait_status perm.login-items ready 60 || ax_fail "login items row not ready"
+  fi
+  ax_log "note: the 'Background Items Added' banner is not asserted; row status comes from SMAppService"
+  # Notifications (optional): Allow the system prompt if the row asks.
+  if ax_find setup.checklist.row.perm.notifications >/dev/null 2>&1 && [ "$(ax_status perm.notifications || true)" != ready ]; then
+    ax_click setup.checklist.row.perm.notifications.action; sleep 2; ax_allow_notifications
+  fi
+  # Apple CLT row: the clean room has none; the app's Install… triggers Apple's dialog — a real network install (~minutes).
+  if [ "$(ax_status tool.clt || true)" != ready ]; then
+    ax_click setup.checklist.row.tool.clt.action
+    ax_osa 'tell application "System Events" to tell process "Install Command Line Developer Tools" to click (first button of window 1 whose name is "Install")' >/dev/null 2>&1 || true
+    ax_osa 'tell application "System Events" to tell process "Install Command Line Developer Tools" to click (first button of window 1 whose name is "Agree")' >/dev/null 2>&1 || true
+    ax_wait_status tool.clt ready 1200 || ax_fail "CLT install did not finish in 20 min"
+    ax_shot 03-clt-installed
+  fi
+  ax_shot 03-readiness-final
+  ax_find setup.checklist.continue >/dev/null || ax_fail "setup.checklist.continue axid missing"
+  ax_click setup.checklist.continue
+}
+
+screen_install() {
+  ax_wait_screen install 10 || ax_fail "setup.install.screen did not appear"
+  ax_shot 04-install-start
+  # Steps stream; a privileged step raises the admin prompt (standard user → admin creds).
+  local n=900 failed
+  while [ "$n" -gt 0 ]; do
+    ax_admin_auth 2>/dev/null && ax_shot 04-admin-auth || true
+    if ax_wait_window "mattstack" 1 && ax_find setup.done.continue >/dev/null 2>&1; then ax_shot 04-install-done; return 0; fi
+    # Failure = the Retry button is present; name the failing step from the per-step status elements.
+    if ax_find setup.install.retry >/dev/null 2>&1; then
+      failed=$(ax_osa "tell application \"System Events\" to tell process \"$AX_APP\" to get value of attribute \"AXIdentifier\" of every UI element of entire contents of window 1" 2>/dev/null | tr ',' '\n' | grep -o 'setup\.install\.step\.[A-Za-z0-9._-]*' | head -1)
+      ax_fail "install step failed (${failed:-see setup.install.retry}); log: setup.install.log.copy"
+    fi
+    sleep 2; n=$((n-2))
+  done
+  ax_fail "install did not reach Done in 15 min"
+}
+
+screen_done() {
+  ax_wait_screen done 10 || ax_fail "setup.done.screen did not appear"
+  ax_shot 05-done
+  ax_click setup.done.continue
+}
+
+ax_log "scenario=$SCENARIO slug=$SLUG"
+screen_welcome; screen_team; screen_readiness; screen_install; screen_done
+ax_log "five screens complete"
+```
+
+- [ ] **Step 3: Syntax-check and a host-side negative run (no window → fast fail)**
+
+Run:
+```bash
+bash -n rt-tray/vm/run/guest/ax.sh rt-tray/vm/run/guest/drive-setup.sh
+GUEST_RUN=/tmp/gr AX_APP=definitely-not-running bash -c 'source rt-tray/vm/run/guest/ax.sh; ax_wait_window x 2; echo "wait exit=$?"; ax_find setup.welcome.screen; echo "find exit=$?"; ax_wait_screen welcome 2; echo "screen exit=$?"'
+```
+Expected: `wait exit=1`, `find exit=1`, `screen exit=1` (osascript errors go to the log), within ~8 s. (On the host this may ALSO prompt for Automation permission for your terminal — decline; it is not needed on the host.)
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add rt-tray/vm/run/guest/ax.sh rt-tray/vm/run/guest/drive-setup.sh
+git commit -m "MAT-383: vm — UI-scripting helpers and the five-screen setup driver
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 7: Guest assertions — `run/guest/assert-installed.sh`
+
+**Files:**
+- Create: `rt-tray/vm/run/guest/assert-installed.sh`
+
+**Interfaces:**
+- Runs in the guest as tester after the five screens (or after the headless install). `assert-installed.sh [--expect-version <v>] [--headless]` → writes `$GUEST_RUN/logs/verify.json`, `$GUEST_RUN/logs/tray-version.json`, `$GUEST_RUN/logs/tray-services.json`, `$GUEST_RUN/logs/tray-permissions.json`, `$GUEST_RUN/logs/launchctl.txt`; prints one `ASSERT ok|FAIL <name>` line per check; exit 1 on any FAIL. Checks: `~/.local/bin/rt` is a symlink into `/Applications/mattstack.app` (or `~/Applications`); `rt --version`; `rt verify --json` `passed:true`; tray.sock `GET /version` matches `--expect-version`; tray.sock `GET /services` reports the daemon (and deck when bundled) and `GET /permissions` answers (the Global Constraints promise: assert through rt + tray.sock routes); `rt settings get mattstack.appPath --scope machine` equals `/Applications/mattstack.app` (V3; or `~/Applications/mattstack.app` on the fallback path); `launchctl print gui/$UID/com.mattstack.daemon` shows a pid; `~/.mattstack` exists and is a git repo (V5) unless `--headless`; no `~/.rt`, no `rt-tray.app`, no `com.rt.daemon` job (pure canonical).
+
+- [ ] **Step 1: Write it**
+
+```bash
+#!/bin/bash
+# Assert the installed state in the guest, through rt and tray.sock (never UI text).
+# Usage: assert-installed.sh [--expect-version <v>] [--headless]
+set -uo pipefail
+GUEST_RUN="${GUEST_RUN:-/Volumes/My Shared Files/run}"; LOGS="$GUEST_RUN/logs"; mkdir -p "$LOGS"
+EXPECT=""; HEADLESS=0
+while [ $# -gt 0 ]; do case "$1" in --expect-version) EXPECT="$2"; shift 2;; --headless) HEADLESS=1; shift;; *) shift;; esac; done
+export PATH="$HOME/.local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+fails=0
+ok()   { echo "ASSERT ok   $1"; }
+bad()  { echo "ASSERT FAIL $1"; fails=$((fails+1)); }
+SOCK="$HOME/.mattstack/rt/tray.sock"
+
+# rt on PATH, symlink into the bundle
+if [ -L "$HOME/.local/bin/rt" ]; then
+  tgt=$(readlink "$HOME/.local/bin/rt")
+  case "$tgt" in /Applications/mattstack.app/*|"$HOME"/Applications/mattstack.app/*) ok "rt symlink → $tgt";; *) bad "rt symlink points outside the bundle: $tgt";; esac
+elif [ -x "$HOME/.local/bin/rt" ]; then
+  ok "rt installed as a binary (pre-L4 layout)"
+else
+  bad "no ~/.local/bin/rt"
+fi
+V=$(rt --version 2>/dev/null | tr -d '\n'); [ -n "$V" ] && ok "rt --version = $V" || bad "rt --version"
+
+# rt verify --json
+if rt verify --json > "$LOGS/verify.json" 2>"$LOGS/verify.stderr"; then
+  grep -q '"passed": *true' "$LOGS/verify.json" && ok "rt verify passed" || bad "rt verify passed:false"
+else
+  bad "rt verify exited $? (see logs/verify.json)"
+fi
+grep -E '"status": *"(fail|warn)"' -B2 "$LOGS/verify.json" | grep '"name"' | sed 's/^/  verify: /' || true
+
+# tray.sock /version
+if [ -S "$SOCK" ]; then
+  curl -s --max-time 5 --unix-socket "$SOCK" http://localhost/version > "$LOGS/tray-version.json" 2>/dev/null
+  if [ -s "$LOGS/tray-version.json" ]; then
+    ok "tray.sock /version → $(tr -d '\n' < "$LOGS/tray-version.json")"
+    if [ -n "$EXPECT" ]; then
+      grep -q "\"version\": *\"$EXPECT\"" "$LOGS/tray-version.json" && ok "version == $EXPECT" || bad "version != $EXPECT"
+    fi
+  else
+    bad "tray.sock /version empty (route not implemented yet?)"
+  fi
+  # /services: daemon always; deck only when the bundle ships Contents/Helpers/deck (L1 registers it conditionally).
+  curl -s --max-time 5 --unix-socket "$SOCK" http://localhost/services > "$LOGS/tray-services.json" 2>/dev/null
+  if grep -q '"com.mattstack.daemon' "$LOGS/tray-services.json" 2>/dev/null; then
+    ok "tray.sock /services lists the daemon ($(tr -d '\n ' < "$LOGS/tray-services.json" | cut -c1-160))"
+    if [ -x /Applications/mattstack.app/Contents/Helpers/deck ]; then
+      grep -q '"com.mattstack.deck' "$LOGS/tray-services.json" && ok "tray.sock /services lists deck" || bad "deck is bundled but /services does not list com.mattstack.deck"
+    else
+      ok "deck not bundled — not expected in /services"
+    fi
+  else
+    bad "tray.sock /services does not list com.mattstack.daemon"
+  fi
+  curl -s --max-time 5 --unix-socket "$SOCK" http://localhost/permissions > "$LOGS/tray-permissions.json" 2>/dev/null
+  grep -q '"fda"' "$LOGS/tray-permissions.json" 2>/dev/null && ok "tray.sock /permissions → $(tr -d '\n ' < "$LOGS/tray-permissions.json" | cut -c1-160)" || bad "tray.sock /permissions empty or missing fda"
+else
+  bad "no tray socket at $SOCK"
+fi
+
+# mattstack.appPath (V3): the app records where it runs from.
+AP=$(rt settings get mattstack.appPath --scope machine 2>/dev/null | tr -d '\n"')
+case "$AP" in /Applications/mattstack.app|"$HOME"/Applications/mattstack.app) ok "mattstack.appPath = $AP";; *) bad "mattstack.appPath is '${AP:-unset}' (wanted /Applications/mattstack.app)";; esac
+
+# daemon registered + running under the canonical label
+launchctl print "gui/$(id -u)/com.mattstack.daemon" > "$LOGS/launchctl.txt" 2>&1
+if grep -qE 'pid = [0-9]+' "$LOGS/launchctl.txt"; then ok "com.mattstack.daemon running (pid $(grep -oE 'pid = [0-9]+' "$LOGS/launchctl.txt" | head -1 | awk '{print $3}'))"; else bad "com.mattstack.daemon not running"; fi
+launchctl print "gui/$(id -u)/com.rt.daemon" >/dev/null 2>&1 && bad "legacy com.rt.daemon job present" || ok "no legacy com.rt.daemon job"
+[ -e "$HOME/.rt" ] && bad "~/.rt exists (legacy)" || ok "no ~/.rt"
+ls -d /Applications/rt-tray.app "$HOME/Applications/rt-tray.app" >/dev/null 2>&1 && bad "rt-tray.app present (legacy)" || ok "no rt-tray.app"
+
+if [ "$HEADLESS" = 0 ]; then
+  [ -d "$HOME/.mattstack/.git" ] && ok "~/.mattstack is the home repo" || bad "~/.mattstack is not a git repo (V5)"
+fi
+echo "$fails" > "$LOGS/assert-fails.txt"
+[ "$fails" -eq 0 ]
+```
+
+- [ ] **Step 2: Syntax-check + run on the host against a throwaway HOME (proves the script is honest when nothing is installed)**
+
+Run: `bash -n rt-tray/vm/run/guest/assert-installed.sh && HOME=$(mktemp -d) GUEST_RUN=/tmp/gr bash rt-tray/vm/run/guest/assert-installed.sh --headless; echo "exit=$?"`
+Expected: several `ASSERT FAIL` lines (no rt, no socket, no daemon), `exit=1`.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add rt-tray/vm/run/guest/assert-installed.sh
+git commit -m "MAT-383: vm — installed-state assertions through rt and tray.sock
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 8: Update phase — `run/guest/trigger-update.sh`
+
+**AFTER L3 T10 merges** (`--allow-appcast-override` + the `MATTSTACK_APPCAST_URL` hook; the post-FDA self-relaunch re-execs with the current arguments + environment).
+
+**Files:**
+- Create: `rt-tray/vm/run/guest/trigger-update.sh`
+
+**Interfaces:**
+- Runs in the guest as tester: `trigger-update.sh <update-dir> <expect-new-version>` where `<update-dir>` holds `appcast.xml` + `mattstack-<v>.zip` + the compiled `appcast-server`. Starts the server on `127.0.0.1:8765` (background, pid file, killed at exit), records pre-update daemon pid + `/version`, `POST /update/check` on tray.sock, drives Sparkle's "Install and Relaunch" via UI scripting (gentle reminder → menu item "Update available…" → Sparkle window), waits for `/version` to equal `<expect-new-version>`, asserts `/version.build` equals L4's numeric `major*1000000+minor*1000+patch` of that version, asserts the daemon pid changed and `rt --version` equals the new version. Output/exit like `assert-installed.sh`.
+- Preconditions asserted first (and reported as the skip reason by the host when false): the app honours `MATTSTACK_APPCAST_URL` — for a **prod** build only when launched with `--allow-appcast-override` (L3 T10), so the host launches with `open --env MATTSTACK_APPCAST_URL=http://127.0.0.1:8765/appcast.xml "$APP" --args --allow-appcast-override` (via `install-app.sh launch --env … --arg --allow-appcast-override`) whenever an update dir is supplied, and every driver-initiated relaunch repeats the same env + arg (`DRIVER_LAUNCH_ARGS`, Task 6).
+
+- [ ] **Step 1: Write it**
+
+```bash
+#!/bin/bash
+# Sparkle vN → vN+1 inside the guest, with the appcast served on loopback.
+# Usage: trigger-update.sh <update-dir> <expect-new-version>
+set -uo pipefail
+HERE="$(cd "$(dirname "$0")" && pwd)"; source "$HERE/ax.sh"
+UPD="${1:-}"; NEWV="${2:-}"
+[ -d "$UPD" ] && [ -f "$UPD/appcast.xml" ] && [ -x "$UPD/appcast-server" ] && [ -n "$NEWV" ] \
+  || { echo "usage: trigger-update.sh <update-dir with appcast.xml + zip + appcast-server> <new-version>"; exit 1; }
+LOGS="$GUEST_RUN/logs"; export PATH="$HOME/.local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+SOCK="$HOME/.mattstack/rt/tray.sock"
+fails=0; ok() { echo "ASSERT ok   $1"; }; bad() { echo "ASSERT FAIL $1"; fails=$((fails+1)); }
+
+"$UPD/appcast-server" "$UPD" 8765 2>>"$LOGS/appcast-server.log" &
+SRV=$!; trap 'kill $SRV 2>/dev/null || true' EXIT
+sleep 1
+curl -s --max-time 3 http://127.0.0.1:8765/appcast.xml | grep -q '<rss' && ok "appcast served on loopback" || { bad "appcast server not reachable"; exit 1; }
+
+before_pid=$(launchctl print "gui/$(id -u)/com.mattstack.daemon" 2>/dev/null | grep -oE 'pid = [0-9]+' | awk '{print $3}')
+before_ver=$(curl -s --unix-socket "$SOCK" http://localhost/version 2>/dev/null | tr -d '\n')
+ax_log "before: daemon pid=${before_pid:-none} version=${before_ver:-?}"
+
+curl -s --max-time 10 --unix-socket "$SOCK" -X POST http://localhost/update/check > "$LOGS/update-check.json" 2>/dev/null
+grep -q '"ok": *true' "$LOGS/update-check.json" && ok "POST /update/check" || bad "POST /update/check failed: $(cat "$LOGS/update-check.json")"
+ax_shot 06-update-check
+
+# Sparkle UI: the status-item menu shows "Update available…"; clicking it opens Sparkle's window.
+for _ in $(seq 1 30); do
+  if ax_osa 'tell application "System Events" to tell process "mattstack" to click menu bar item 1 of menu bar 2' >/dev/null 2>&1; then
+    if ax_osa 'tell application "System Events" to tell process "mattstack" to click (first menu item of menu 1 of menu bar item 1 of menu bar 2 whose name contains "Update available")' >/dev/null 2>&1; then
+      ax_log "opened Sparkle from the menu"; break
+    fi
+    ax_osa 'tell application "System Events" to key code 53' >/dev/null 2>&1   # escape the menu
+  fi
+  sleep 2
+done
+# Sparkle's update window: "Install Update" then "Install and Relaunch" (names are Sparkle's).
+for _ in $(seq 1 60); do
+  ax_click_button_named "Install Update" mattstack 2>/dev/null && break
+  ax_click_button_named "Install and Relaunch" mattstack 2>/dev/null && break
+  sleep 2
+done
+ax_shot 06-update-installing
+for _ in $(seq 1 30); do ax_click_button_named "Install and Relaunch" mattstack 2>/dev/null && break; sleep 2; done
+
+# Wait for the new version on the socket (the app relaunches; the socket disappears then returns).
+new_ver=""
+for _ in $(seq 1 120); do
+  new_ver=$(curl -s --max-time 2 --unix-socket "$SOCK" http://localhost/version 2>/dev/null | grep -oE '"version": *"[^"]+"' | cut -d'"' -f4)
+  [ "$new_ver" = "$NEWV" ] && break
+  sleep 2
+done
+[ "$new_ver" = "$NEWV" ] && ok "tray /version == $NEWV" || bad "tray /version is '${new_ver:-?}', wanted $NEWV"
+# CFBundleVersion is numeric major*1000000+minor*1000+patch (L4 scheme); /version.build is a number.
+want_build=$(echo "$NEWV" | awk -F. '{ printf "%d", $1*1000000 + $2*1000 + $3 }')
+got_build=$(curl -s --max-time 2 --unix-socket "$SOCK" http://localhost/version 2>/dev/null | grep -oE '"build": *[0-9]+' | grep -oE '[0-9]+$')
+[ "${got_build:-}" = "$want_build" ] && ok "tray /version.build == $want_build" || bad "tray /version.build is '${got_build:-?}', wanted $want_build"
+ax_shot 06-update-done
+
+after_pid=$(launchctl print "gui/$(id -u)/com.mattstack.daemon" 2>/dev/null | grep -oE 'pid = [0-9]+' | awk '{print $3}')
+[ -n "$after_pid" ] && [ "$after_pid" != "${before_pid:-}" ] && ok "daemon restarted (pid $before_pid → $after_pid)" || bad "daemon did not restart (pid ${before_pid:-none} → ${after_pid:-none})"
+rv=$(rt --version 2>/dev/null | tr -d '\n'); [ "$rv" = "$NEWV" ] && ok "rt --version == $NEWV" || bad "rt --version is '$rv'"
+cp "$LOGS/appcast-server.log" "$LOGS/appcast-server.final.log" 2>/dev/null || true
+echo "$fails" > "$LOGS/update-fails.txt"
+[ "$fails" -eq 0 ]
+```
+
+- [ ] **Step 2: Syntax-check + usage run**
+
+Run: `bash -n rt-tray/vm/run/guest/trigger-update.sh && GUEST_RUN=/tmp/gr bash rt-tray/vm/run/guest/trigger-update.sh /nonexistent 1.2.3; echo "exit=$?"`
+Expected: usage line, `exit=1`.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add rt-tray/vm/run/guest/trigger-update.sh
+git commit -m "MAT-383: vm — Sparkle vN→vN+1 phase with a loopback appcast
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 9: The orchestrator — `run/walkthrough.sh`
+
+**Files:**
+- Create: `rt-tray/vm/run/walkthrough.sh`
+
+**Interfaces:**
+- Consumes: everything from Tasks 1–8.
+- CLI:
+  ```
+  walkthrough.sh --ver <14|15|26> (--dmg <path> | --app <mattstack.app>)
+                 [--scenario create|join|headless] [--team-slug vmtest] [--pat-env MATTSTACK_VMTEST_PAT]
+                 [--invite-code-file <p>] [--update-dir <dir with appcast.xml+zip>] [--update-version <v>]
+                 [--no-quarantine] [--no-graphics] [--keep] [--dry-run] [--verify-golden]
+  ```
+- Phases, in order, each `pass|fail|skip` in the ledger: `preflight`, `clone`, `boot`, `stage`, `install`, `launch`, `screens` (skipped under `--scenario headless`, which instead runs `scripts/e2e-cleanroom.sh` in the guest — see Task 12), `assert`, `update` (skipped without `--update-dir`), `teardown`. Exit 1 iff a phase failed; the last line is the ledger summary and the path to `report.md`.
+- Host screenshot loop: while the guest runs, a background watcher turns `$VM_RUN_DIR/in/shot-<name>.req` into `screenshots/<name>.png` via `run/host/capture.sh` and touches `.done`.
+
+- [ ] **Step 1: Write `rt-tray/vm/run/walkthrough.sh`**
+
+```bash
+#!/bin/bash
+# Clean-room walkthrough: clone golden → install DMG → five screens → assert → Sparkle update → teardown.
+set -uo pipefail
+source "$(cd "$(dirname "$0")/.." && pwd)/lib/common.sh"
+
+usage() { sed -n '2,3p' "$0"; cat <<'EOF'
+usage: walkthrough.sh --ver <14|15|26> (--dmg <path> | --app <mattstack.app>)
+         [--scenario create|join|headless] [--team-slug vmtest] [--pat-env MATTSTACK_VMTEST_PAT]
+         [--invite-code-file <p>] [--update-dir <dir>] [--update-version <v>]
+         [--no-quarantine] [--no-graphics] [--keep] [--dry-run] [--verify-golden]
+EOF
+exit 2; }
+
+VER=""; DMG=""; APP=""; SCENARIO=create; SLUG=vmtest; PAT_ENV=MATTSTACK_VMTEST_PAT; CODE_FILE=""
+UPD=""; UPDV=""; QUAR=1; GRAPHICS=1; KEEP=0; DRY=0; VERIFY_GOLDEN=0
+while [ $# -gt 0 ]; do case "$1" in
+  --ver) VER="$2"; shift 2;; --dmg) DMG="$2"; shift 2;; --app) APP="$2"; shift 2;;
+  --scenario) SCENARIO="$2"; shift 2;; --team-slug) SLUG="$2"; shift 2;; --pat-env) PAT_ENV="$2"; shift 2;;
+  --invite-code-file) CODE_FILE="$2"; shift 2;; --update-dir) UPD="$2"; shift 2;; --update-version) UPDV="$2"; shift 2;;
+  --no-quarantine) QUAR=0; shift;; --no-graphics) GRAPHICS=0; shift;; --keep) KEEP=1; shift;; --dry-run) DRY=1; shift;;
+  --verify-golden) VERIFY_GOLDEN=1; shift;; -h|--help) usage;; *) vm_warn "unknown arg $1"; usage;; esac; done
+[ -n "$VER" ] || usage
+[ -n "$DMG" ] || [ -n "$APP" ] || usage
+
+GOLDEN=$(vm_golden_name "$VER")
+vm_run_init "walk-$VER-$SCENARIO"
+RUN_VM="mattstack-run-$VER-$(date +%H%M%S)"
+GUEST_RUN="/Volumes/My Shared Files/run"
+GUEST_BIN="/Users/$VM_TESTER_USER/vmrun"
+TART_PID=""; SHOT_PID=""
+APP_VERSION=""
+
+cleanup() {
+  [ -n "$SHOT_PID" ] && kill "$SHOT_PID" 2>/dev/null
+  if [ "$DRY" = 0 ]; then
+    collect_logs || true
+    if [ "$KEEP" = 1 ]; then vm_warn "keeping $RUN_VM running (--keep); stop with: tart stop $RUN_VM && tart delete $RUN_VM"
+    else tart stop "$RUN_VM" 2>/dev/null || true; [ -n "$TART_PID" ] && wait "$TART_PID" 2>/dev/null; tart delete "$RUN_VM" 2>/dev/null || true; fi
+  fi
+  vm_render_report
+  local f; f=$(vm_phases_failed)
+  vm_log "done: $(grep -c '"status":"pass"' "$VM_RUN_DIR/phases.jsonl" || true) passed, $f failed, $(grep -c '"status":"skip"' "$VM_RUN_DIR/phases.jsonl" || true) skipped → $VM_RUN_DIR/report.md"
+  exit "$([ "${f:-0}" -eq 0 ] && echo 0 || echo 1)"
+}
+trap cleanup EXIT
+
+collect_logs() {
+  vm_ssh "$VM_TESTER_USER" "$RUN_VM" 'tar -C "$HOME" -czf - .mattstack/rt/logs .mattstack/deck/logs Library/Logs/mattstack 2>/dev/null' > "$VM_RUN_DIR/logs/guest-home-logs.tgz" 2>/dev/null || true
+  vm_ssh "$VM_TESTER_USER" "$RUN_VM" 'log show --last 45m --predicate '"'"'process == "mattstack" OR process == "rt" OR subsystem CONTAINS "com.mattstack" OR process == "smd" OR process == "backgroundtaskmanagementd"'"'"' --style compact 2>/dev/null | tail -5000' > "$VM_RUN_DIR/logs/guest-unified.log" 2>/dev/null || true
+  vm_ssh "$VM_TESTER_USER" "$RUN_VM" 'launchctl print gui/$(id -u) 2>/dev/null | grep -iE "mattstack|com\.rt\." ' > "$VM_RUN_DIR/logs/guest-launchctl-grep.txt" 2>/dev/null || true
+}
+
+shot_watcher() {  # host loop: in/shot-<name>.req → screenshots/<name>.png
+  while :; do
+    for req in "$VM_RUN_DIR"/in/shot-*.req; do
+      [ -e "$req" ] || continue
+      name=$(basename "$req" .req); name=${name#shot-}
+      "$VM_ROOT/run/host/capture.sh" "$RUN_VM" "$VM_RUN_DIR/screenshots/$name.png" >>"$VM_RUN_DIR/logs/capture.log" 2>&1 || true
+      rm -f "$req"; : > "$VM_RUN_DIR/in/shot-$name.done"
+    done
+    sleep 0.5
+  done
+}
+
+skip_if_dry() { [ "$DRY" = 1 ] && { vm_phase_end "$1" skip "dry-run"; return 0; }; return 1; }
+
+# ── preflight ────────────────────────────────────────────────────────────────
+vm_phase_begin preflight
+if [ "$DRY" = 0 ]; then
+  vm_require_cmd tart "brew install openai/tools/tart"
+  tart list 2>/dev/null | awk '{print $2}' | grep -qx "$GOLDEN" || { vm_phase_end preflight fail "golden $GOLDEN missing — run golden/build-golden.sh $VER"; exit 1; }
+  [ -f "$VM_SSH_KEY" ] || { vm_phase_end preflight fail "no ssh key at $VM_SSH_KEY (built by build-golden.sh)"; exit 1; }
+fi
+if [ -z "$DMG" ]; then
+  DMG="$VM_RUN_DIR/in/mattstack.dmg"
+  [ "$DRY" = 1 ] || "$VM_ROOT/run/make-dmg.sh" "$APP" "$DMG" || { vm_phase_end preflight fail "make-dmg failed"; exit 1; }
+fi
+[ "$DRY" = 1 ] || [ -f "$DMG" ] || { vm_phase_end preflight fail "no dmg at $DMG"; exit 1; }
+if [ "$DRY" = 0 ]; then
+  cp "$DMG" "$VM_RUN_DIR/in/mattstack.dmg" 2>/dev/null || true
+  T=$(mktemp -d); hdiutil attach "$DMG" -nobrowse -quiet -mountpoint "$T/m" && APP_VERSION=$(/usr/libexec/PlistBuddy -c 'Print :CFBundleShortVersionString' "$T/m/mattstack.app/Contents/Info.plist" 2>/dev/null); hdiutil detach "$T/m" -quiet 2>/dev/null; rm -rf "$T"
+fi
+if [ -n "$UPD" ]; then
+  if [ ! -f "$UPD/appcast.xml" ] || ! ls "$UPD"/mattstack-*.zip >/dev/null 2>&1 || [ -z "$UPDV" ]; then
+    vm_phase_end preflight fail "--update-dir needs appcast.xml + mattstack-<v>.zip and --update-version"; exit 1; fi
+  if [ "$DRY" = 0 ]; then
+    mkdir -p "$VM_RUN_DIR/in/update"; cp "$UPD"/appcast.xml "$UPD"/mattstack-*.zip "$VM_RUN_DIR/in/update/"
+    bun build --compile "$VM_ROOT/run/helpers/appcast-server.ts" --outfile "$VM_RUN_DIR/in/update/appcast-server" >/dev/null 2>&1 || { vm_phase_end preflight fail "bun build --compile appcast-server failed"; exit 1; }
+  fi
+fi
+[ "$SCENARIO" = join ] && [ ! -f "${CODE_FILE:-/nonexistent}" ] && { vm_phase_end preflight fail "join needs --invite-code-file"; exit 1; }
+if [ "$SCENARIO" != headless ] && [ -z "${!PAT_ENV:-}" ]; then vm_warn "\$$PAT_ENV empty — the GitHub account row cannot be connected; the screens phase will fail there if the app shows it"; fi
+cp -R "$VM_ROOT/run/guest" "$VM_RUN_DIR/in/guest"; cp "$VM_ROOT/../../scripts/e2e-cleanroom.sh" "$VM_RUN_DIR/in/guest/" 2>/dev/null || true
+printf '{"ver":"%s","scenario":"%s","dmg":"%s","appVersion":"%s","updateVersion":"%s","quarantine":%s,"graphics":%s}\n' \
+  "$VER" "$SCENARIO" "$DMG" "$APP_VERSION" "$UPDV" "$QUAR" "$GRAPHICS" > "$VM_RUN_DIR/in/params.json"
+vm_phase_end preflight pass
+if [ "$DRY" = 1 ]; then
+  vm_log "[dry-run] would: tart clone $GOLDEN $RUN_VM; tart run $RUN_VM --dir=run:$VM_RUN_DIR $([ $GRAPHICS = 0 ] && echo --no-graphics); wait ssh; stage; install; $([ $SCENARIO = headless ] && echo e2e-cleanroom || echo 'five screens'); assert; $([ -n "$UPD" ] && echo update || echo 'update(skip)'); teardown"
+  for p in clone boot stage install launch screens assert update teardown; do vm_phase_begin $p; skip_if_dry $p; done
+  exit 0
+fi
+
+# ── clone + boot ─────────────────────────────────────────────────────────────
+vm_phase_begin clone
+tart clone "$GOLDEN" "$RUN_VM" >>"$VM_RUN_DIR/logs/tart.log" 2>&1 && vm_phase_end clone pass || { vm_phase_end clone fail "tart clone failed (see logs/tart.log)"; exit 1; }
+
+vm_phase_begin boot
+RUN_ARGS=(--no-audio "--dir=run:$VM_RUN_DIR"); [ "$GRAPHICS" = 0 ] && RUN_ARGS+=(--no-graphics)
+tart run "$RUN_VM" "${RUN_ARGS[@]}" >>"$VM_RUN_DIR/logs/tart.log" 2>&1 &
+TART_PID=$!
+if vm_wait_ssh "$VM_TESTER_USER" "$RUN_VM" 420; then
+  [ "$GRAPHICS" = 1 ] && { shot_watcher & SHOT_PID=$!; }
+  if [ "$VERIFY_GOLDEN" = 1 ]; then "$VM_ROOT/golden/verify-golden.sh" "$VER" "$RUN_VM" >>"$VM_RUN_DIR/logs/verify-golden.log" 2>&1 || { vm_phase_end boot fail "golden verification failed in the clone"; exit 1; }; fi
+  vm_phase_end boot pass
+else vm_phase_end boot fail "ssh as tester never came up"; exit 1; fi
+
+# ── stage ────────────────────────────────────────────────────────────────────
+vm_phase_begin stage
+vm_ssh "$VM_TESTER_USER" "$RUN_VM" "mkdir -p $GUEST_BIN && cp -R '$GUEST_RUN/in/guest/.' $GUEST_BIN/ && chmod +x $GUEST_BIN/*.sh && test -f '$GUEST_RUN/in/mattstack.dmg'" \
+  && vm_phase_end stage pass || { vm_phase_end stage fail "virtiofs share not visible in guest"; exit 1; }
+
+# ── install (admin copies) + launch (tester) ─────────────────────────────────
+vm_phase_begin install
+QFLAG=--quarantine; [ "$QUAR" = 0 ] && QFLAG=--no-quarantine
+vm_ssh "$VM_ADMIN_USER" "$RUN_VM" "GUEST_RUN='$GUEST_RUN' bash '$GUEST_RUN/in/guest/install-app.sh' copy '$GUEST_RUN/in/mattstack.dmg' $QFLAG" >>"$VM_RUN_DIR/logs/install.log" 2>&1 \
+  && vm_phase_end install pass || { vm_phase_end install fail "copy failed (logs/install.log)"; exit 1; }
+
+vm_phase_begin launch
+# Prod builds honour MATTSTACK_APPCAST_URL only with --allow-appcast-override (L3 T10); the same env/arg is
+# replayed by drive-setup.sh on any driver-initiated relaunch (DRIVER_LAUNCH_ARGS).
+LAUNCH_ARGS=""; [ -n "$UPD" ] && LAUNCH_ARGS="--env MATTSTACK_APPCAST_URL=http://127.0.0.1:8765/appcast.xml --arg --allow-appcast-override"
+vm_ssh "$VM_TESTER_USER" "$RUN_VM" "GUEST_RUN='$GUEST_RUN' bash $GUEST_BIN/install-app.sh launch $LAUNCH_ARGS" >>"$VM_RUN_DIR/logs/install.log" 2>&1
+rc=$?
+: > "$VM_RUN_DIR/in/shot-00-first-launch.req"; sleep 3
+case $rc in
+  0) vm_phase_end launch pass "" screenshots/00-first-launch.png ;;
+  2) vm_phase_end launch fail "Gatekeeper blocked the app (unnotarised build? rerun with --no-quarantine)" screenshots/00-first-launch.png; exit 1 ;;
+  *) vm_phase_end launch fail "app did not start (logs/install.log)" screenshots/00-first-launch.png; exit 1 ;;
+esac
+
+# ── screens / headless ───────────────────────────────────────────────────────
+vm_phase_begin screens
+if [ "$SCENARIO" = headless ]; then
+  if vm_ssh "$VM_TESTER_USER" "$RUN_VM" "GUEST_RUN='$GUEST_RUN' bash $GUEST_BIN/e2e-cleanroom.sh --app /Applications/mattstack.app --allow-existing-install --artifacts-dir '$GUEST_RUN/logs/cleanroom'" >>"$VM_RUN_DIR/logs/screens.log" 2>&1; then
+    vm_phase_end screens pass "headless: scripts/e2e-cleanroom.sh in guest"
+  else vm_phase_end screens fail "headless recipe failed (logs/screens.log)"; fi
+else
+  CODE_ARG=""; [ -n "$CODE_FILE" ] && { cp "$CODE_FILE" "$VM_RUN_DIR/in/invite-code.txt"; CODE_ARG="--invite-code-file '$GUEST_RUN/in/invite-code.txt'"; }
+  if vm_ssh "$VM_TESTER_USER" "$RUN_VM" "GUEST_RUN='$GUEST_RUN' VM_ADMIN_PASS='$VM_ADMIN_PASS' DRIVER_LAUNCH_ARGS='$LAUNCH_ARGS' $PAT_ENV='${!PAT_ENV:-}' bash $GUEST_BIN/drive-setup.sh $SCENARIO --team-slug $SLUG --pat-env $PAT_ENV $CODE_ARG" >>"$VM_RUN_DIR/logs/screens.log" 2>&1; then
+    vm_phase_end screens pass "" $(cd "$VM_RUN_DIR" && ls screenshots/0[1-5]-*.png 2>/dev/null)
+  else
+    vm_phase_end screens fail "$(tail -1 "$VM_RUN_DIR/logs/drive.log" 2>/dev/null || echo 'see logs/screens.log')" $(cd "$VM_RUN_DIR" && ls screenshots/*.png 2>/dev/null)
+  fi
+fi
+
+# ── assert ───────────────────────────────────────────────────────────────────
+vm_phase_begin assert
+HFLAG=""; [ "$SCENARIO" = headless ] && HFLAG=--headless
+if vm_ssh "$VM_TESTER_USER" "$RUN_VM" "GUEST_RUN='$GUEST_RUN' bash $GUEST_BIN/assert-installed.sh --expect-version '$APP_VERSION' $HFLAG" >"$VM_RUN_DIR/logs/assert.log" 2>&1; then
+  vm_phase_end assert pass
+else vm_phase_end assert fail "$(grep -c 'ASSERT FAIL' "$VM_RUN_DIR/logs/assert.log") assertion(s) failed (logs/assert.log)"; fi
+
+# ── update ───────────────────────────────────────────────────────────────────
+vm_phase_begin update
+if [ -z "$UPD" ]; then vm_phase_end update skip "no --update-dir (L4 artifacts + L3 MATTSTACK_APPCAST_URL hook required)"
+elif [ "$(vm_phases_failed)" -gt 0 ]; then vm_phase_end update skip "earlier phase failed"
+else
+  if vm_ssh "$VM_TESTER_USER" "$RUN_VM" "GUEST_RUN='$GUEST_RUN' bash $GUEST_BIN/trigger-update.sh '$GUEST_RUN/in/update' '$UPDV'" >"$VM_RUN_DIR/logs/update.log" 2>&1; then
+    vm_phase_end update pass "" $(cd "$VM_RUN_DIR" && ls screenshots/06-*.png 2>/dev/null)
+  else vm_phase_end update fail "$(grep -c 'ASSERT FAIL' "$VM_RUN_DIR/logs/update.log") assertion(s) failed (logs/update.log)" $(cd "$VM_RUN_DIR" && ls screenshots/06-*.png 2>/dev/null); fi
+fi
+
+vm_phase_begin teardown
+vm_phase_end teardown pass
+```
+
+- [ ] **Step 2: Syntax-check + dry-run**
+
+Run:
+```bash
+bash -n rt-tray/vm/run/walkthrough.sh
+bash rt-tray/vm/run/walkthrough.sh --ver 26 --app rt-tray/mattstack.app --dry-run; echo "exit=$?"
+bash rt-tray/vm/run/walkthrough.sh --ver 26 --app rt-tray/mattstack.app --update-dir /tmp --dry-run; echo "exit=$?"
+bash rt-tray/vm/run/walkthrough.sh; echo "exit=$?"
+```
+Expected: run 1 → a run dir under `rt-tray/vm/artifacts/`, `preflight pass`, nine `skip dry-run` lines, `report.md` rendered, `exit=0`; run 2 → `preflight fail --update-dir needs…`, `exit=1`; run 3 → usage, `exit=2`. Check `cat rt-tray/vm/artifacts/*/report.md | head -20` reads sensibly.
+
+- [ ] **Step 3 (MATT / ORCHESTRATOR, after Task 2's goldens exist): first real run with today's app**
+
+Run: `cd rt-tray && ./build.sh release && cd .. && bash rt-tray/vm/run/walkthrough.sh --ver 26 --app rt-tray/mattstack.app --no-quarantine --keep`
+Expected today (pre-L3): `clone/boot/stage/install/launch` pass (menu bar `m` appears), `screens` fails with `setup.welcome.screen axid missing (L3 AccessibilityIDs)`, `assert` fails on the socket/daemon rows (no setup ran), `update` skipped. Screenshot `00-first-launch.png` exists. Attach the run dir path to the MAT-383 ticket as the L7 baseline; then `tart stop`/`delete` the kept VM.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add rt-tray/vm/run/walkthrough.sh
+git commit -m "MAT-383: vm — walkthrough orchestrator with phase ledger and host screenshots
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 10: Test team + invite scenario — `run/team-setup.sh`
+
+**Files:**
+- Create: `rt-tray/vm/run/team-setup.sh`
+
+**Interfaces:**
+- Host-only. `team-setup.sh reset` deletes + recreates the throwaway repos; `team-setup.sh invite --handle <forge-handle> --out <code-file>` mints an invite (real `rt team invite` when the verb exists and the relay answers, else the stub code) and writes the code to `<code-file>` (mode 600, under `$VM_RUN_DIR/in` or `$VM_CACHE`, never in git); `team-setup.sh status` prints the org/repos/PAT presence without printing the PAT.
+- Env: `MATTSTACK_VMTEST_ORG` (default `mattstack-vmtest`), `MATTSTACK_VMTEST_PAT` (fine-grained PAT scoped to that org: Administration RW, Contents RW, Metadata R — **MATT creates the org and the PAT; never stored in the repo**), `MATTSTACK_VMTEST_HOME_REPO` (default `mattstack-vmtest-home`), `MATTSTACK_VMTEST_TEAM_REPO` (default `mattstack-vmtest-team`).
+- Note on names: the wizard's gh one-click path names repos `<owner>/mattstack-home` and `<owner>/mattstack-team-<slug>`; `reset` therefore also deletes those two (`mattstack-home`, `mattstack-team-<slug>`) so the `create` scenario starts clean. The brief's pair (`*-home`, `*-team`) is what the **URL-paste path** and the **join** scenario use.
+
+- [ ] **Step 1: Write it**
+
+```bash
+#!/bin/bash
+# Throwaway GitHub org for the VM walkthrough. ORCHESTRATOR/MATT: needs MATTSTACK_VMTEST_PAT in env.
+# Usage: team-setup.sh reset [--slug vmtest] | invite --handle <h> --out <file> [--slug vmtest] | status
+set -euo pipefail
+source "$(cd "$(dirname "$0")/.." && pwd)/lib/common.sh"
+ORG="${MATTSTACK_VMTEST_ORG:-mattstack-vmtest}"
+HOME_REPO="${MATTSTACK_VMTEST_HOME_REPO:-mattstack-vmtest-home}"
+TEAM_REPO="${MATTSTACK_VMTEST_TEAM_REPO:-mattstack-vmtest-team}"
+PAT="${MATTSTACK_VMTEST_PAT:-}"
+cmd="${1:-}"; shift || true
+SLUG=vmtest; HANDLE=""; OUT=""
+while [ $# -gt 0 ]; do case "$1" in --slug) SLUG="$2"; shift 2;; --handle) HANDLE="$2"; shift 2;; --out) OUT="$2"; shift 2;; *) vm_die "unknown arg $1";; esac; done
+vm_require_cmd gh "brew install gh"
+ghp() { GH_TOKEN="$PAT" gh "$@"; }
+need_pat() { [ -n "$PAT" ] || vm_die "MATTSTACK_VMTEST_PAT is empty — export a fine-grained PAT scoped to org $ORG (MATT step; never commit it)"; }
+
+case "$cmd" in
+  status)
+    vm_log "org=$ORG home=$HOME_REPO team=$TEAM_REPO pat=$([ -n "$PAT" ] && echo present || echo MISSING)"
+    [ -n "$PAT" ] && ghp repo list "$ORG" --limit 20 --json name -q '.[].name' | sed 's/^/  repo: /' || true
+    ;;
+  reset)
+    need_pat
+    for r in "$HOME_REPO" "$TEAM_REPO" mattstack-home "mattstack-team-$SLUG"; do
+      if ghp repo view "$ORG/$r" >/dev/null 2>&1; then ghp repo delete "$ORG/$r" --yes && vm_log "deleted $ORG/$r"; fi
+    done
+    ghp repo create "$ORG/$HOME_REPO" --private --description "mattstack VM test home repo (throwaway)" >/dev/null && vm_log "created $ORG/$HOME_REPO"
+    ghp repo create "$ORG/$TEAM_REPO" --private --description "mattstack VM test team repo (throwaway)" >/dev/null && vm_log "created $ORG/$TEAM_REPO"
+    ;;
+  invite)
+    need_pat; [ -n "$HANDLE" ] && [ -n "$OUT" ] || vm_die "invite needs --handle and --out"
+    mkdir -p "$(dirname "$OUT")"; umask 077
+    if rt team invite --help >/dev/null 2>&1; then
+      # Real path: owner mints against the shared relay (L1 + L6). Team must exist locally: rt team create … first.
+      if ! rt team create "$SLUG" --remote "https://github.com/$ORG/$TEAM_REPO.git" --others --json >/dev/null 2>&1; then vm_warn "rt team create returned non-zero (team may already exist)"; fi
+      rt team publish --remote "https://github.com/$ORG/$TEAM_REPO.git" --json >/dev/null 2>&1 || true
+      if out=$(rt team invite --handle "$HANDLE" --json 2>"$VM_CACHE/invite.err"); then
+        printf '%s' "$out" | sed -n 's/.*"code": *"\([^"]*\)".*/\1/p' > "$OUT"
+        [ -s "$OUT" ] || vm_die "rt team invite returned no code: $(cat "$VM_CACHE/invite.err")"
+        vm_log "invite minted (real) → $OUT  expires: $(printf '%s' "$out" | sed -n 's/.*"expiresAt": *"\([^"]*\)".*/\1/p')"
+      else
+        vm_die "rt team invite failed (relay down? L6 not deployed?): $(cat "$VM_CACHE/invite.err")"
+      fi
+    else
+      # Stub path until L1/L6 land: a syntactically valid code the app's DEBUG stub (RT_STUB_SCENARIO=join-happy) accepts.
+      printf 'STUB-%s-%s\n' "$SLUG" "$(date +%s)" > "$OUT"
+      vm_log "invite code is a STUB (rt team invite not available) → $OUT; join scenario needs a DEBUG app launched with RT_STUB_SCENARIO=join-happy RT_STUB_PATH=<repo>/rt-tray/Tests/stub-rt/stub.ts (L3 plan)"
+    fi
+    ;;
+  *) vm_die "usage: team-setup.sh reset|invite|status";;
+esac
+```
+
+- [ ] **Step 2: Syntax-check + status without PAT**
+
+Run: `bash -n rt-tray/vm/run/team-setup.sh && MATTSTACK_VMTEST_PAT= bash rt-tray/vm/run/team-setup.sh status && MATTSTACK_VMTEST_PAT= bash rt-tray/vm/run/team-setup.sh reset; echo "exit=$?"`
+Expected: status prints `pat=MISSING`; reset dies with the PAT hint, `exit=1`.
+
+- [ ] **Step 3 (MATT): create the org + PAT; run `reset` once**
+
+MATT: create GitHub org `mattstack-vmtest` (free), a fine-grained PAT (resource owner = the org; repository permissions Administration RW, Contents RW, Metadata R; org permission Members R), `export MATTSTACK_VMTEST_PAT=…` in the shell that runs the walkthrough. Run: `bash rt-tray/vm/run/team-setup.sh reset && bash rt-tray/vm/run/team-setup.sh status`. Expected: two repos listed.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add rt-tray/vm/run/team-setup.sh
+git commit -m "MAT-383: vm — throwaway test org reset and invite minting (real or stub)
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 11: Layer (c) — `run/second-user.sh`
+
+**Files:**
+- Create: `rt-tray/vm/run/second-user.sh`
+
+**Interfaces:**
+- `second-user.sh create` (prints the exact `sysadminctl` command for MATT to run with sudo — the script never creates users itself), `second-user.sh check` (user exists? logged in with a GUI session? — `launchctl print gui/<uid>` succeeds), `second-user.sh run --artifact <mattstack-*.zip|.dmg>` (runs `scripts/e2e-cleanroom.sh` as that user via `sudo -iu`, copying the artifact into the user's home first; the artifacts dir is `rt-tray/vm/artifacts/<run>/` on Matt's side, readable by both), `second-user.sh switch` (prints the `CGSession -switchToUserID` command).
+- Env: `MATTSTACK_SMOKE_USER` (default `mstest`).
+
+- [ ] **Step 1: Write it**
+
+```bash
+#!/bin/bash
+# Layer (c): daily smoke as a second macOS user on this Mac.
+# Usage: second-user.sh create | check | switch | run --artifact <mattstack-*.zip|mattstack-*.dmg>
+set -euo pipefail
+source "$(cd "$(dirname "$0")/.." && pwd)/lib/common.sh"
+U="${MATTSTACK_SMOKE_USER:-mstest}"
+cmd="${1:-}"; shift || true
+ART=""
+while [ $# -gt 0 ]; do case "$1" in --artifact) ART="$2"; shift 2;; *) vm_die "unknown arg $1";; esac; done
+
+case "$cmd" in
+  create)
+    cat <<EOF
+  MATT step — run in your own terminal (creates a standard user; choose the password interactively):
+    sudo sysadminctl -addUser $U -fullName "mattstack smoke" -password -
+  Then log the user in once so a GUI session exists (Fast User Switching; required for launchd gui/\$UID):
+    $0 switch
+  and switch back to your account.
+EOF
+    ;;
+  switch)
+    uid=$(id -u "$U" 2>/dev/null) || vm_die "user $U does not exist — $0 create"
+    echo "  '/System/Library/CoreServices/Menu Extras/User.menu/Contents/Resources/CGSession' -switchToUserID $uid"
+    ;;
+  check)
+    uid=$(id -u "$U" 2>/dev/null) || vm_die "user $U does not exist — $0 create"
+    vm_log "user $U uid=$uid"
+    if sudo -n launchctl print "gui/$uid" >/dev/null 2>&1; then vm_log "GUI session present (gui/$uid) — SMAppService registration will work"
+    elif launchctl print "gui/$uid" >/dev/null 2>&1; then vm_log "GUI session present (gui/$uid)"
+    else vm_warn "no GUI session for $U — log the user in once ($0 switch); daemon will report not-booted otherwise"; exit 1; fi
+    ;;
+  run)
+    [ -n "$ART" ] && [ -f "$ART" ] || vm_die "run needs --artifact <file>"
+    id -u "$U" >/dev/null 2>&1 || vm_die "user $U does not exist — $0 create"
+    vm_run_init "second-user"
+    HOME2=$(dscl . -read "/Users/$U" NFSHomeDirectory | awk '{print $2}')
+    sudo install -d -o "$U" -m 700 "$HOME2/mattstack-smoke"
+    sudo install -o "$U" -m 600 "$ART" "$HOME2/mattstack-smoke/$(basename "$ART")"
+    sudo install -o "$U" -m 700 "$VM_ROOT/../../scripts/e2e-cleanroom.sh" "$HOME2/mattstack-smoke/e2e-cleanroom.sh"
+    sudo install -o "$U" -m 700 -d "$HOME2/mattstack-smoke/artifacts"
+    chmod 777 "$VM_RUN_DIR" "$VM_RUN_DIR/logs"
+    # sudo -iu gives the user's login env; the user is (ideally) logged in so `open`/SMAppService land in gui/<uid>.
+    if sudo -iu "$U" bash -lc "cd ~/mattstack-smoke && ./e2e-cleanroom.sh --artifact ~/mattstack-smoke/$(basename "$ART") --home \$HOME --artifacts-dir ~/mattstack-smoke/artifacts --allow-existing-install" > "$VM_RUN_DIR/logs/second-user.log" 2>&1; then
+      vm_phase_begin second-user; vm_phase_end second-user pass
+    else
+      vm_phase_begin second-user; vm_phase_end second-user fail "e2e-cleanroom exited non-zero (logs/second-user.log)"
+    fi
+    sudo cp -R "$HOME2/mattstack-smoke/artifacts/." "$VM_RUN_DIR/logs/" 2>/dev/null || true
+    sudo chown -R "$(id -u):$(id -g)" "$VM_RUN_DIR"
+    vm_render_report
+    [ "$(vm_phases_failed)" -eq 0 ]
+    ;;
+  *) vm_die "usage: second-user.sh create|check|switch|run --artifact <file>";;
+esac
+```
+
+- [ ] **Step 2: Syntax-check + `create`/`check` without the user**
+
+Run: `bash -n rt-tray/vm/run/second-user.sh && bash rt-tray/vm/run/second-user.sh create && bash rt-tray/vm/run/second-user.sh check; echo "exit=$?"`
+Expected: create prints the sysadminctl line; check dies `user mstest does not exist`, `exit=1`.
+
+- [ ] **Step 3 (MATT): create + log in the smoke user, then run once**
+
+Run (MATT): the printed `sysadminctl` line, then `switch`, log in, switch back; then `bash rt-tray/vm/run/second-user.sh check && bash rt-tray/vm/run/second-user.sh run --artifact <path to mattstack-*.zip>` (download one with `gh release download <tag> -R m4ttstack/rt -p 'mattstack-*.zip' -D rt-tray/vm/.cache`). Expected: `second-user pass`, and `logs/second-user.log` ends with `rt verify --ci` output (daemon running, since the user has a GUI session).
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add rt-tray/vm/run/second-user.sh
+git commit -m "MAT-383: vm — second-macOS-user smoke runner (layer c)
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 12: Layer (a) locally — `scripts/e2e-cleanroom.sh`
+
+**CLI agreed with L4 T8** (cross-plan review §5 #36/#46): `release.yml` calls `scripts/e2e-cleanroom.sh "<zip>"` positionally — the positional form is accepted and means `--artifact`. Merge after L4 T8 is on main only matters for the CI job going green; the script itself is L7's.
+
+**Files:**
+- Create: `scripts/e2e-cleanroom.sh`
+- Modify: `scripts/README.md` (append a section; L4 T6 appends its own `scripts/release/*` section — whoever merges second rebases)
+
+**Interfaces:**
+- `e2e-cleanroom.sh [<mattstack-*.zip|.dmg|mattstack.app>] (--artifact <mattstack-*.zip|.dmg> | --tag vX.Y.Z | --app </Applications/mattstack.app>) [--home <dir>] [--artifacts-dir <dir>] [--allow-existing-install] [--post-install-args "<args>"]`. A single positional path is `--artifact` (or `--app` when it ends in `.app`) — L4 T8 calls it that way with the release zip. `--tag` downloads `mattstack-*.zip` (`gh release download <tag> -R m4ttstack/rt -p 'mattstack-*.zip'`); there is no tarball artifact any more (L4 Decision 2). Mirrors `.github/workflows/release.yml` `test-install` step for step: extract (`ditto -x -k` for the zip, `hdiutil attach` + `ditto` for a DMG) → `<work>/release/mattstack.app/Contents/MacOS/rt --version` → `rt --post-install $PIA` (default `--post-install-args "--non-interactive --team-of-one --no-launch"` — L1 T27: `rt --post-install` = legacy sweep + headless `rt setup apply`; `--no-launch` is also implied by `--ci`/`CI=true`) → `~/.local/bin/rt --version` → `rt daemon install` (writes `daemon.json`; under L1 `services.register` is skipped honestly when no app is reachable) → `sleep 3` → `rt verify --ci` → `rt-tray/check-bundle.sh --app <app>` if that script is present in the checkout (L4's sparse checkout may be `scripts` only). `--app` skips extraction and uses `<app>/Contents/MacOS/rt`. `CI=true` is exported (matches the runner: daemon-not-booted = warn — never assert the daemon is running in CI).
+- Guard: refuses to run when the invoking user already has mattstack registered (`launchctl print gui/$UID/com.mattstack.daemon` succeeds or `~/.mattstack/rt/daemon.json` exists in the REAL home) unless `--allow-existing-install` — because `rt --post-install` without `--no-launch`/`CI` launches the app, which would register a second `com.mattstack.app` login item for the same user. Intended callers: the VM guest, the second user, CI.
+- Output: `<artifacts-dir>/cleanroom-<ts>/{steps.log,verify-ci.txt,versions.txt}`; exit code = `rt verify --ci`'s.
+
+- [ ] **Step 1: Write it**
+
+```bash
+#!/bin/bash
+# Layer (a) of the clean-room matrix, locally: the release workflow's test-install recipe.
+# See .github/workflows/release.yml (job test-install) — keep the two in step.
+set -uo pipefail
+usage() { cat <<'EOF'
+usage: e2e-cleanroom.sh [<mattstack-*.zip|.dmg|mattstack.app>]
+         (--artifact <mattstack-*.zip|.dmg> | --tag <vX.Y.Z> | --app <mattstack.app>)
+         [--home <dir>] [--artifacts-dir <dir>] [--allow-existing-install] [--post-install-args "<args>"]
+EOF
+exit 2; }
+ART=""; TAG=""; APP=""; HOME_DIR=""; OUTDIR=""; ALLOW=0; PIA="--non-interactive --team-of-one --no-launch"
+while [ $# -gt 0 ]; do case "$1" in
+  --artifact) ART="$2"; shift 2;; --tag) TAG="$2"; shift 2;; --app) APP="$2"; shift 2;;
+  --home) HOME_DIR="$2"; shift 2;; --artifacts-dir) OUTDIR="$2"; shift 2;; --allow-existing-install) ALLOW=1; shift;;
+  --post-install-args) PIA="$2"; shift 2;; -h|--help) usage;;
+  -*) echo "unknown arg $1" >&2; usage;;
+  *) case "$1" in *.app) APP="$1";; *) ART="$1";; esac; shift;;   # positional: release.yml passes the zip
+  esac; done
+[ -n "$ART$TAG$APP" ] || usage
+
+REAL_HOME="$HOME"
+if [ "$ALLOW" = 0 ]; then
+  if launchctl print "gui/$(id -u)/com.mattstack.daemon" >/dev/null 2>&1 || [ -f "$REAL_HOME/.mattstack/rt/daemon.json" ]; then
+    echo "  ✗ this user already has mattstack installed/registered; rt --post-install would launch a second com.mattstack.app." >&2
+    echo "    Run inside the VM (rt-tray/vm/run/walkthrough.sh --scenario headless), as the smoke user (rt-tray/vm/run/second-user.sh), or pass --allow-existing-install." >&2
+    exit 3
+  fi
+fi
+
+TS=$(date +%Y%m%d-%H%M%S)
+OUTDIR="${OUTDIR:-$(cd "$(dirname "$0")/.." && pwd)/rt-tray/vm/artifacts}/cleanroom-$TS"
+mkdir -p "$OUTDIR"
+LOG="$OUTDIR/steps.log"
+step() { printf '\n== %s ==\n' "$*" | tee -a "$LOG"; }
+run()  { "$@" 2>&1 | tee -a "$LOG"; return "${PIPESTATUS[0]}"; }
+
+WORK=$(mktemp -d)
+if [ -n "$TAG" ]; then
+  step "gh release download $TAG"
+  run gh release download "$TAG" -R m4ttstack/rt -p 'mattstack-*.zip' -D "$WORK" || exit 1
+  ART=$(ls "$WORK"/mattstack-*.zip | head -1)
+fi
+if [ -n "$ART" ]; then
+  step "extract $(basename "$ART")"
+  mkdir -p "$WORK/release"
+  case "$ART" in
+    *.zip) run ditto -x -k "$ART" "$WORK/release" || exit 1 ;;
+    *.dmg) MNT=$(mktemp -d); run hdiutil attach "$ART" -nobrowse -quiet -mountpoint "$MNT" || exit 1
+           run ditto "$MNT/mattstack.app" "$WORK/release/mattstack.app"; hdiutil detach "$MNT" -quiet ;;
+    *) echo "unknown artifact type: $ART (expected mattstack-<ver>.zip or .dmg)" >&2; exit 1 ;;
+  esac
+  run ls -la "$WORK/release"
+  APP="$WORK/release/mattstack.app"
+fi
+RT="$APP/Contents/MacOS/rt"
+[ -x "${RT:-}" ] || { echo "no rt binary at $APP/Contents/MacOS/rt" >&2; exit 1; }
+
+export CI=true
+if [ -n "$HOME_DIR" ]; then export HOME="$HOME_DIR"; mkdir -p "$HOME"; fi
+export PATH="$HOME/.local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/homebrew/bin:/usr/local/bin"
+step "rt --version (from artifact)";   run "$RT" --version | tee "$OUTDIR/versions.txt" >/dev/null || exit 1
+step "rt --post-install $PIA";          run "$RT" --post-install $PIA || exit 1
+step "installed rt on PATH";            run test -x "$HOME/.local/bin/rt" && run rt --version || exit 1
+step "rt daemon install";               run rt daemon install; sleep 3
+step "rt verify --ci";                  rt verify --ci 2>&1 | tee "$OUTDIR/verify-ci.txt" | tee -a "$LOG"
+RC=${PIPESTATUS[0]}
+CHECK="$(cd "$(dirname "$0")/.." && pwd)/rt-tray/check-bundle.sh"
+if [ -x "$CHECK" ]; then
+  step "check-bundle.sh --app";         run "$CHECK" --app "$APP" || RC=1
+else
+  step "check-bundle.sh";               echo "skipped: rt-tray/check-bundle.sh not in this checkout" | tee -a "$LOG"
+fi
+printf '\nexit=%s\nartifacts=%s\n' "$RC" "$OUTDIR" | tee -a "$LOG"
+exit "$RC"
+```
+
+- [ ] **Step 2: Append to `scripts/README.md`**
+
+```markdown
+## e2e-cleanroom.sh
+
+The release workflow's `test-install` recipe (extract the zip → `rt --post-install --non-interactive --team-of-one --no-launch` → `rt daemon install` → `rt verify --ci` → `rt-tray/check-bundle.sh --app` when present), runnable locally against a release tag, a `mattstack-<ver>.zip`/`.dmg`, or an installed `mattstack.app`. `release.yml` calls it with the zip as a single positional argument. Refuses to run as a user who already has mattstack registered (without `--no-launch` the post-install would launch a second app) — use it inside the VM walkthrough (`rt-tray/vm/run/walkthrough.sh --scenario headless`), as the smoke user (`rt-tray/vm/run/second-user.sh run`), or on CI. Output lands in `rt-tray/vm/artifacts/cleanroom-<ts>/`. Under `CI=true` a daemon that is not booted is a warning, not a failure.
+
+```sh
+scripts/e2e-cleanroom.sh --tag v2.8.0
+scripts/e2e-cleanroom.sh ~/Downloads/mattstack-2.8.0.zip --home "$(mktemp -d)"
+scripts/e2e-cleanroom.sh --artifact ~/Downloads/mattstack-2.8.0.dmg --home "$(mktemp -d)"
+```
+```
+
+- [ ] **Step 3: Syntax-check + guard + usage**
+
+Run:
+```bash
+bash -n scripts/e2e-cleanroom.sh
+bash scripts/e2e-cleanroom.sh; echo "exit=$?"
+bash scripts/e2e-cleanroom.sh /nonexistent.zip; echo "exit=$?"
+bash scripts/e2e-cleanroom.sh --artifact /nonexistent.zip; echo "exit=$?"
+```
+Expected: usage `exit=2`; on Matt's machine the second and third print the "already has mattstack installed" guard and `exit=3` (on a clean machine they would fail at extract with exit 1). The positional and `--artifact` forms behave identically.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add scripts/e2e-cleanroom.sh scripts/README.md
+git commit -m "MAT-383: scripts/e2e-cleanroom.sh — the CI headless install recipe, runnable locally
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 13: XCUITest mode (gated on Xcode) — `run/xcuitest.sh`
+
+**AFTER L3 T19 merges** (the `mattstackUITests` target + `project.yml`) and only once Xcode exists on the host; the gate below keeps it an honest `skip` until then.
+
+**Files:**
+- Create: `rt-tray/vm/run/xcuitest.sh`
+- Modify: `rt-tray/vm/golden/build-golden.sh` (`--xcode` flag)
+- Modify: `rt-tray/vm/golden/provision-guest.sh` (`SKIP_CLEANROOM`)
+- Modify: `rt-tray/vm/golden/verify-golden.sh` (`"xcode"` marker-conditional checks)
+
+**Interfaces:**
+- `xcuitest.sh --ver <26> --dmg <path> [--keep]`: same clone/boot/stage/install as the walkthrough but on a golden named `mattstack-golden-<ver>-xcode` (built by `build-golden.sh <ver> --xcode`, which pulls `ghcr.io/cirruslabs/macos-<name>-xcode:latest` and skips the no-CLT/no-brew steps — that golden is NOT a clean room for the Tools rows and the README says so), copies the repo's `rt-tray/` sources + `project.yml` into the guest, runs `xcodebuild test -project mattstack.xcodeproj -scheme mattstack -only-testing:mattstackUITests -destination 'platform=macOS' -resultBundlePath "$GUEST_RUN/logs/xcuitest.xcresult"` (target/scheme names from the L3 plan `2026-08-21-mattstack-app-shell.md`: targets `mattstack`, `mattstack-dev`, `MattstackCoreTests`, `mattstackUITests`) and exports screenshots with `xcrun xcresulttool`. Gated: exits `skip` immediately when the host has no Xcode (`xcode-select -p` not under `/Applications/Xcode*.app`) or the `-xcode` golden does not exist, and when `rt-tray/project.yml` (L3 deliverable) is absent.
+- This task also adds the `--xcode` flag to `golden/build-golden.sh` (image `macos-<name>-xcode`, golden name suffix `-xcode`, provisioner env `SKIP_CLEANROOM=1` which skips steps 1–3 in `provision-guest.sh`).
+
+- [ ] **Step 1: Extend `golden/build-golden.sh` and `golden/provision-guest.sh`**
+
+In `build-golden.sh`, after the arg loop add `XCODE=0` handling: `--xcode) XCODE=1;;`; then:
+```bash
+if [ "$XCODE" = 1 ]; then
+  IMAGE=$(vm_image_for "$VER" | sed 's/-vanilla:/-xcode:/'); GOLDEN="$(vm_golden_name "$VER")-xcode"
+fi
+```
+and pass `SKIP_CLEANROOM=$XCODE` into the provisioner invocation: `"SKIP_CLEANROOM=$XCODE bash /tmp/provision-guest.sh …"`. In `provision-guest.sh`, wrap steps 1–3 in `if [ "${SKIP_CLEANROOM:-0}" != 1 ]; then … fi`. In `verify-golden.sh`, make the `no CLT`/`no brew`/`Gatekeeper` checks conditional on the marker's `"xcode": false` (write `"xcode": true|false` into the marker from `SKIP_CLEANROOM`).
+
+- [ ] **Step 2: Write `rt-tray/vm/run/xcuitest.sh`**
+
+```bash
+#!/bin/bash
+# XCUITest-driven walkthrough inside an -xcode golden. Gated on Xcode + L3's project.yml.
+# Usage: xcuitest.sh --ver <14|15|26> --dmg <path> [--keep]
+set -uo pipefail
+source "$(cd "$(dirname "$0")/.." && pwd)/lib/common.sh"
+VER=""; DMG=""; KEEP=0
+while [ $# -gt 0 ]; do case "$1" in --ver) VER="$2"; shift 2;; --dmg) DMG="$2"; shift 2;; --keep) KEEP=1; shift;; *) vm_die "unknown arg $1";; esac; done
+[ -n "$VER" ] && [ -f "${DMG:-}" ] || vm_die "usage: xcuitest.sh --ver <v> --dmg <path> [--keep]"
+vm_run_init "xcuitest-$VER"
+GOLDEN="$(vm_golden_name "$VER")-xcode"; RUN_VM="mattstack-xcui-$VER-$(date +%H%M%S)"
+GUEST_RUN="/Volumes/My Shared Files/run"
+vm_phase_begin gate
+case "$(xcode-select -p 2>/dev/null)" in /Applications/Xcode*.app/*) ;; *) vm_phase_end gate skip "Xcode not installed on the host (xcode-select -p)"; vm_render_report; exit 0;; esac
+[ -f "$VM_ROOT/../project.yml" ] || { vm_phase_end gate skip "rt-tray/project.yml absent (L3 deliverable)"; vm_render_report; exit 0; }
+tart list 2>/dev/null | awk '{print $2}' | grep -qx "$GOLDEN" || { vm_phase_end gate skip "golden $GOLDEN missing — build-golden.sh $VER --xcode"; vm_render_report; exit 0; }
+vm_phase_end gate pass
+
+TART_PID=""
+cleanup() { [ "$KEEP" = 1 ] || { tart stop "$RUN_VM" 2>/dev/null; [ -n "$TART_PID" ] && wait "$TART_PID" 2>/dev/null; tart delete "$RUN_VM" 2>/dev/null; }; vm_render_report; exit "$([ "$(vm_phases_failed)" -eq 0 ] && echo 0 || echo 1)"; }
+trap cleanup EXIT
+
+vm_phase_begin clone; tart clone "$GOLDEN" "$RUN_VM" >>"$VM_RUN_DIR/logs/tart.log" 2>&1 && vm_phase_end clone pass || { vm_phase_end clone fail "tart clone"; exit 1; }
+vm_phase_begin boot
+tart run "$RUN_VM" --no-audio "--dir=run:$VM_RUN_DIR" >>"$VM_RUN_DIR/logs/tart.log" 2>&1 & TART_PID=$!
+vm_wait_ssh "$VM_TESTER_USER" "$RUN_VM" 420 && vm_phase_end boot pass || { vm_phase_end boot fail "ssh"; exit 1; }
+
+vm_phase_begin stage
+cp "$DMG" "$VM_RUN_DIR/in/mattstack.dmg"; cp -R "$VM_ROOT/run/guest" "$VM_RUN_DIR/in/guest"
+mkdir -p "$VM_RUN_DIR/in/src"; rsync -a --exclude .build --exclude '*.app' --exclude vm "$VM_ROOT/../" "$VM_RUN_DIR/in/src/rt-tray/"
+vm_ssh "$VM_TESTER_USER" "$RUN_VM" "rm -rf ~/src && cp -R '$GUEST_RUN/in/src' ~/src && cd ~/src/rt-tray && (command -v xcodegen >/dev/null || brew install xcodegen) && xcodegen generate" >>"$VM_RUN_DIR/logs/stage.log" 2>&1 \
+  && vm_phase_end stage pass || { vm_phase_end stage fail "xcodegen generate failed (logs/stage.log)"; exit 1; }
+
+vm_phase_begin install
+vm_ssh "$VM_ADMIN_USER" "$RUN_VM" "GUEST_RUN='$GUEST_RUN' bash '$GUEST_RUN/in/guest/install-app.sh' copy '$GUEST_RUN/in/mattstack.dmg' --no-quarantine" >>"$VM_RUN_DIR/logs/install.log" 2>&1 \
+  && vm_phase_end install pass || { vm_phase_end install fail "copy (logs/install.log)"; exit 1; }
+
+vm_phase_begin xcuitest
+if vm_ssh "$VM_TESTER_USER" "$RUN_VM" "cd ~/src/rt-tray && xcodebuild test -project mattstack.xcodeproj -scheme mattstack -only-testing:mattstackUITests -destination 'platform=macOS' -resultBundlePath '$GUEST_RUN/logs/xcuitest.xcresult' MATTSTACK_UITEST_REAL_APP=/Applications/mattstack.app" >"$VM_RUN_DIR/logs/xcodebuild.log" 2>&1; then
+  vm_phase_end xcuitest pass
+else vm_phase_end xcuitest fail "xcodebuild test failed (logs/xcodebuild.log)"; fi
+vm_ssh "$VM_TESTER_USER" "$RUN_VM" "xcrun xcresulttool export attachments --path '$GUEST_RUN/logs/xcuitest.xcresult' --output-path '$GUEST_RUN/screenshots' 2>/dev/null || true" >/dev/null 2>&1
+
+vm_phase_begin assert
+vm_ssh "$VM_TESTER_USER" "$RUN_VM" "GUEST_RUN='$GUEST_RUN' bash '$GUEST_RUN/in/guest/assert-installed.sh'" >"$VM_RUN_DIR/logs/assert.log" 2>&1 && vm_phase_end assert pass || vm_phase_end assert fail "see logs/assert.log"
+```
+
+- [ ] **Step 3: Syntax-check + gate run (no Xcode on the host today → skip)**
+
+Run: `bash -n rt-tray/vm/run/xcuitest.sh rt-tray/vm/golden/build-golden.sh rt-tray/vm/golden/provision-guest.sh rt-tray/vm/golden/verify-golden.sh && touch /tmp/fake.dmg && bash rt-tray/vm/run/xcuitest.sh --ver 26 --dmg /tmp/fake.dmg; echo "exit=$?"; bash rt-tray/vm/golden/build-golden.sh 26 --xcode --dry-run`
+Expected: `gate skipped: Xcode not installed on the host`, report rendered, `exit=0`; dry-run prints `tart clone ghcr.io/cirruslabs/macos-tahoe-xcode:latest mattstack-golden-26-xcode`.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add rt-tray/vm/run/xcuitest.sh rt-tray/vm/golden
+git commit -m "MAT-383: vm — XCUITest mode gated on Xcode and the -xcode golden
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 14: README, run-everything dry check, wrap-up
+
+**Files:**
+- Modify: `rt-tray/vm/README.md` (complete it)
+- Create: `rt-tray/vm/check-vm-scripts.sh` (the offline check every implementer and reviewer can run: `bash -n` on every script + the unit tests + every `--dry-run`)
+
+- [ ] **Step 1: Complete `rt-tray/vm/README.md`** (keep the Task 1 table; append)
+
+```markdown
+## Layout
+
+(paste the tree from the plan's "File structure" section)
+
+## Prerequisites (host, Apple Silicon)
+
+- `brew install openai/tools/tart` (Tart is **FSL-1.1-ALv2**, © OpenAI; tart.run/licensing: free on personal workstations and for orgs up to 100 CPU cores — this Mac is inside the free tier; recount if L7 ever moves to a shared fleet). Old tap: `cirruslabs/cli/tart`.
+- `brew install cirruslabs/cli/sshpass` (golden build only — the first password login; everything after is key-based).
+- Apple CLT (`swiftc`, for `run/host/winid.swift`) and Bun (compiles `appcast-server`).
+- Screen Recording for your terminal app (System Settings → Privacy & Security → Screen & System Audio Recording) — host-side screenshots of the Tart window. One-time.
+- ~60 GB free disk per golden (25–27 GB download, 50 GB virtual disk, APFS-sparse). Clones are copy-on-write.
+- GitHub-hosted runners cannot run this (no nested macOS virtualisation); local only, or a self-hosted Apple-Silicon runner later.
+
+## Golden images (built once, never run again — every run is a clone)
+
+`golden/build-golden.sh 26` and `golden/build-golden.sh 14` (`15` optional; `--xcode` for the XCUITest flavour, which keeps CLT/brew and is therefore not a clean room for the Tools rows).
+Image source: `ghcr.io/cirruslabs/macos-{sonoma,sequoia,tahoe}-vanilla:latest` (no brew, no guest agent → ssh only). Provisioning: remove Apple CLT (the vanilla template installs it), assert no brew, re-enable Gatekeeper (the image ships it disabled), create standard user `tester`/`tester` as the auto-login console user (`admin`/`admin` keeps NOPASSWD sudo for provisioning and plays the "admin credentials" role in the installer's privileged step), Remote Login for all users, ssh key for both, sleep/screensaver/screen-lock off, marker `/Users/Shared/mattstack-golden.json`.
+**One manual step per golden** (TCC cannot be pre-approved by script; `tccutil` only resets; PPPC needs MDM): in the VM, Privacy & Security → Accessibility → add `/usr/libexec/sshd-keygen-wrapper` and `/usr/bin/osascript`; then approve the Automation prompt for System Events when the script sends its probe. `golden/verify-golden.sh` proves it (the probe fails with "not allowed assistive access" until done). macOS 26.1/26.2 had a bug adding CLI tools there; the tahoe image is ≥ 26.3.
+
+## Runs
+
+```
+run/walkthrough.sh --ver 26 --dmg dist/mattstack-2.9.0.dmg \
+   --update-dir dist/update --update-version 2.9.1 \
+   --scenario create --team-slug vmtest --pat-env MATTSTACK_VMTEST_PAT
+run/walkthrough.sh --ver 14 --app rt-tray/mattstack.app --no-quarantine --scenario headless
+run/second-user.sh run --artifact ~/Downloads/mattstack-2.9.0.zip
+../../scripts/e2e-cleanroom.sh --tag v2.9.0   # refuses on a user that already runs mattstack
+../../scripts/e2e-cleanroom.sh ~/Downloads/mattstack-2.9.0.zip --home "$(mktemp -d)"   # what release.yml runs
+```
+Phases: preflight · clone · boot · stage · install · launch · screens · assert · update · teardown. Each is `pass|fail|skip` with a reason in `artifacts/<run>/phases.jsonl`; `report.md` is the human summary; `screenshots/` are numbered per screen (`00-first-launch`, `01-welcome`, `02-team-*`, `03-readiness-*`, `04-install-*`, `05-done`, `06-update-*`); `logs/` holds guest logs (`~/.mattstack/rt/logs`, unified log slice for mattstack/smd/backgroundtaskmanagementd, `launchctl print` grep, `rt verify --json`, tray `/version`). Exit 1 iff any phase failed; skips are reported, never counted green.
+
+## What is not automated (and how the scripts treat it)
+
+- **"Background Items Added"** banner: not clicked, not asserted (it is a notification). The Login Items row is asserted through `GET /services` / `rt setup status`; if SMAppService returns `.requiresApproval`, the driver opens Login Items and toggles the app (admin auth as a standard user).
+- **FDA relaunch**: the driver clicks "Relaunch mattstack" (`setup.checklist.relaunch`) and waits for the window to return (the app re-execs with its own args + env, so the appcast override survives; if it does not come back the driver relaunches it with the same `--env`/`--arg`); FDA taking effect is asserted only through the app's probe row (`perm.fda` = ready). No `tccutil` is used in the guest.
+- **Gatekeeper with unnotarised builds**: a locally built DMG is quarantined by default to exercise the real path; it will be blocked (`launch fail`, screenshot of the dialog). Use `--no-quarantine` for local builds and say so in the ticket.
+- **Apple CLT install** in the clean room is real (Apple's dialog, network, minutes); the driver clicks Install/Agree and waits up to 20 min.
+- **Sparkle update** needs L4's signed zip + appcast and L3's `MATTSTACK_APPCAST_URL` hook (prod builds honour it only when launched with `--allow-appcast-override`); until then the phase is `skip` with that reason. The appcast is served on **loopback inside the guest** to stay clear of macOS 15's Local Network Privacy prompt; the real feed is the GitHub Release asset `https://github.com/m4ttstack/rt/releases/latest/download/appcast.xml`. `CFBundleVersion` follows L4's `major*1000000+minor*1000+patch`.
+- **Invite/join** needs L1 + L6; `run/team-setup.sh invite` mints a stub code until then (only a DEBUG app with `RT_STUB_SCENARIO=join-happy` accepts it).
+- **Second user**: Matt creates the user and logs it in once (launchd `gui/<uid>` needs a GUI session); the script never creates users.
+
+## Test team
+
+Throwaway GitHub org `mattstack-vmtest` (repos `mattstack-vmtest-home`, `mattstack-vmtest-team`, plus the wizard's own `mattstack-home` / `mattstack-team-<slug>`), fine-grained PAT in `MATTSTACK_VMTEST_PAT` (env only; never in the repo or artifacts). `run/team-setup.sh reset` before a `create` run. No real team data ever enters this org.
+
+## Costs (fill in after the first builds)
+
+| image | pull | disk | golden build | walkthrough (create) |
+|---|---|---|---|---|
+| 26 | | | | |
+| 14 | | | | |
+
+## Manual alternative
+
+VirtualBuddy (GUI, no CLI): duplicate the library VM with ⌘D (APFS clone), drag the DMG in via its shared folder, run `run/guest/*.sh` by hand from a Terminal in the guest with `GUEST_RUN` pointed at a shared folder. Same scripts, no host orchestration.
+```
+
+- [ ] **Step 2: Write `rt-tray/vm/check-vm-scripts.sh`**
+
+```bash
+#!/bin/bash
+# Offline check of everything under rt-tray/vm: syntax, unit tests, dry-runs. No tart, no network.
+set -uo pipefail
+HERE="$(cd "$(dirname "$0")" && pwd)"; cd "$HERE"
+fails=0
+t() { printf '  %-48s' "$1"; shift; if "$@" >/tmp/vmcheck.out 2>&1; then echo ok; else echo FAIL; sed 's/^/      /' /tmp/vmcheck.out | head -20; fails=$((fails+1)); fi; }
+for f in lib/common.sh golden/*.sh run/*.sh run/guest/*.sh run/host/*.sh ../../scripts/e2e-cleanroom.sh check-vm-scripts.sh; do
+  t "bash -n $f" bash -n "$f"
+done
+t "common.test.sh"               bash lib/__tests__/common.test.sh
+t "appcast-server.test.ts"       bun test run/helpers/__tests__/appcast-server.test.ts
+t "build-golden --dry-run"       bash golden/build-golden.sh 26 --dry-run
+t "build-golden --xcode dry"     bash golden/build-golden.sh 26 --xcode --dry-run
+t "walkthrough --dry-run"        env VM_ARTIFACTS=/tmp/vmcheck-art bash run/walkthrough.sh --ver 26 --app ../mattstack.app --dry-run
+t "walkthrough usage"            bash -c '! bash run/walkthrough.sh >/dev/null 2>&1'
+t "xcuitest gate"                bash -c 'touch /tmp/vmcheck.dmg; VM_ARTIFACTS=/tmp/vmcheck-art bash run/xcuitest.sh --ver 26 --dmg /tmp/vmcheck.dmg'
+t "team-setup status (no pat)"   env MATTSTACK_VMTEST_PAT= bash run/team-setup.sh status
+t "second-user create"           bash run/second-user.sh create
+t "e2e-cleanroom usage"          bash -c '! bash ../../scripts/e2e-cleanroom.sh >/dev/null 2>&1'
+t "winid compiles"               swiftc -O -o /tmp/vmcheck-winid run/host/winid.swift
+t "appcast-server compiles"      bun build --compile run/helpers/appcast-server.ts --outfile /tmp/vmcheck-appcast
+rm -rf /tmp/vmcheck-art /tmp/vmcheck-winid /tmp/vmcheck-appcast /tmp/vmcheck.dmg /tmp/vmcheck.out
+echo; [ "$fails" -eq 0 ] && echo "  all vm checks ok" || { echo "  $fails check(s) failed"; exit 1; }
+```
+
+- [ ] **Step 3: Run the whole offline check**
+
+Run: `ls rt-tray/mattstack.app >/dev/null 2>&1 || (cd rt-tray && ./build.sh release); bash rt-tray/vm/check-vm-scripts.sh`
+Expected: every line `ok`, `all vm checks ok`. (The `walkthrough --dry-run` line needs `rt-tray/mattstack.app` to exist; `build.sh release` needs a compiled rt — `bun run build` first if `dist/rt` is missing.)
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add rt-tray/vm/README.md rt-tray/vm/check-vm-scripts.sh
+git commit -m "MAT-383: vm — README (what the layer verifies, MATT steps, costs) and offline check runner
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+- [ ] **Step 5 (MATT / ORCHESTRATOR): the real gate, once L3/L4 land**
+
+Run: `bash rt-tray/vm/run/walkthrough.sh --ver 26 --dmg <L4 dmg> --update-dir <L4 update dir> --update-version <vN+1> --scenario create` and the same with `--ver 14`; then `bash rt-tray/vm/run/second-user.sh run --artifact <L4 mattstack-<ver>.zip>`. Expected: all phases `pass`, screenshots 00–06 present, both report.md attached to the release candidate. Fill in the README "Costs" table from the run durations.
+
+---
+
+## Self-review checklist (done by the plan author; implementers re-run the bits they touch)
+
+**1. Spec coverage (ruling 12, §11.2, §12.2, §13 L7):**
+- (a) GitHub Actions headless install + `rt verify --ci` → Task 12 (`scripts/e2e-cleanroom.sh`, same recipe as `release.yml` `test-install`; the workflow is NOT modified here — L4 owns it and should switch the job to call the script; noted in Open questions).
+- (b) `rt-tray/vm/` golden recipe (Tart, macOS 14 + 26, no CLT/brew, Apple-ID-free standard user) → Task 2; `walkthrough.sh` restores (clones), mounts DMG, launches with `RT_STUB_SCENARIO` unset, test team on a throwaway org → Tasks 5, 9, 10; drives the five screens incl. the FDA/Login Items dance → Task 6 (UI scripting) + Task 13 (XCUITest, gated); Sparkle vN→vN+1 from a local appcast → Tasks 3, 8; screenshots archived per run → Tasks 4, 9.
+- (c) second macOS user smoke → Task 11.
+- Release gate = (a)+(b) green → Task 14 Step 5 + README.
+- `launchctl kickstart -k` across 14/15/26 (§14 risk "must be verified in the VM layer") → asserted by Task 8's "daemon restarted (pid changed)" check after the update.
+- Artifacts/logs as the deliverable of every run → `vm_run_init`/ledger/report (Task 1) used everywhere.
+- What cannot be automated (BTM banner, FDA relaunch) → README (Task 14) + the driver's explicit log lines (Task 6).
+
+**2. Placeholder scan:** no TBD/TODO; every script is written in full; the only "fill in later" is the README Costs table, which by design records measurements from Matt's real runs. Tasks marked MATT/ORCHESTRATOR state exactly what to run.
+
+**3. Consistency:** names used across tasks — `vm_golden_name`, `vm_image_for`, `vm_run_init`, `vm_phase_begin/end`, `vm_phases_failed`, `vm_render_report`, `vm_ssh`, `vm_scp`, `vm_ssh_pw`, `vm_wait_ssh`, `VM_RUN_DIR`, `VM_CACHE`, `VM_SSH_KEY`, `VM_TESTER_USER/PASS`, `VM_ADMIN_USER/PASS` (Task 1) ↔ Tasks 2, 3, 4, 9, 10, 11, 13; `GUEST_RUN=/Volumes/My Shared Files/run` and `in/`, `logs/`, `screenshots/` (Tasks 1, 5, 6, 7, 8, 9, 13); `ax_shot` handshake `in/shot-<name>.req/.done` (Task 6) ↔ `shot_watcher` (Task 9); `install-app.sh copy|launch` exit 2 = Gatekeeper (Task 5) ↔ launch phase (Task 9); `assert-installed.sh --expect-version/--headless` (Task 7) ↔ Task 9/13; `trigger-update.sh <dir> <v>` with `appcast-server` inside `<dir>` (Task 8) ↔ preflight compiles it into `in/update/` (Task 9); `e2e-cleanroom.sh --app … --allow-existing-install --artifacts-dir` (Task 12) ↔ headless scenario (Task 9) and `second-user.sh run` (Task 11), positional `<zip>` ↔ L4 T8's `release.yml` call; `install-app.sh launch --env … --arg --allow-appcast-override` (Task 5) ↔ `LAUNCH_ARGS`/`DRIVER_LAUNCH_ARGS` (Tasks 6, 8, 9); AXIdentifier names (Task 6) ↔ L3's `AccessibilityIDs.swift` as listed in the "Dependencies on other lanes" table; `make-appcast.sh` build number ↔ L4's `major*1000000+minor*1000+patch` (Tasks 3, 8).
+
+## Open questions
+
+1. ~~AXIdentifiers + `MATTSTACK_APPCAST_URL` + ATS exception are L3 asks~~ **Closed by the cross-plan review (§5 #43/#44/#49):** L3's `AccessibilityIDs.swift` (T12) is the contract and this plan now uses those names (Dependencies table, Task 6); `MATTSTACK_APPCAST_URL` is honoured by L3 T10 with `--allow-appcast-override` for prod builds (Tasks 5, 8, 9); ATS `NSAllowsLocalNetworking` is in L3 T2's Info.plist; `SPARKLE_PUBLIC_ED_KEY` and `mattstack-<ver>.dmg/.zip` are L4's (Task 3 re-points at `scripts/release/*` after L4 T6). No separate contract amendment to file. Until those lanes merge, `screens` and `update` still fail/skip honestly.
+2. **Ad-hoc-signed local builds and Sparkle:** Sparkle compares the incoming bundle's code signature with the installed one; whether two ad-hoc builds pass its check (no Team ID) is unverified. The update phase is specified for Developer-ID builds; if local ad-hoc runs are wanted, this needs an empirical check on the first run.
+3. **Standard-user choice:** the walkthrough drives a *standard* user (`tester`) with `admin` credentials typed at privileged prompts (FDA/Login Items toggles, proxy step). Most teammates are admins on their Macs; should a second scenario (`--console-user admin`) be added so both paths are exercised? (Cheap: a golden-build flag that sets `autoLoginUser admin`.)
+4. ~~`rt --post-install` launches the app unconditionally~~ **Closed:** L1 T27 makes `rt --post-install` = legacy sweep + `rt setup apply --non-interactive --team-of-one …`, with `--no-launch` explicit and implied by `--ci`/`CI=true`; Task 12 passes `--no-launch` by default. The "already registered" guard stays as defence in depth.
+5. ~~`release.yml` `test-install` job → call `scripts/e2e-cleanroom.sh`?~~ **Closed:** L4 T8 calls `scripts/e2e-cleanroom.sh "<zip>"` positionally (cross-plan review §5 #36); Task 12 accepts the positional form.
+6. **Tart licence ownership change:** the repo and brew tap moved to `openai/*`, licence FSL-1.1 © OpenAI, tart.run still states the Cirrus Labs free tier. Fine for one workstation; re-check before any fleet use.
+7. **macOS 14 golden:** the `macos-sonoma-vanilla` image is 14.8.7 (3 months old, still published). If the pull fails or the image disappears, the fallback is `15` per the brief — confirm with Matt that a 14+26 matrix remains the target rather than 15+26.
+8. **In-guest CLT install** during the clean-room run is network-bound and slow (~5–15 min). Acceptable for the release gate, or should the `create` scenario be split into "clean room until the Tools group" and "pre-CLT golden" for daily runs?
diff --git a/docs/superpowers/plans/2026-08-21-cross-plan-review.md b/docs/superpowers/plans/2026-08-21-cross-plan-review.md
new file mode 100644
index 00000000..e2453dd8
--- /dev/null
+++ b/docs/superpowers/plans/2026-08-21-cross-plan-review.md
@@ -0,0 +1,334 @@
+# Cross-plan review — L1 / L3 / L4 / L7 (MAT-383 installer program)
+
+Read-only review of the four plans written in parallel, against the spec
+(`specs/2026-08-20-mattstack-app-installer-design.md`), the binding contract
+(`specs/2026-08-21-rt-setup-contract.md`) and the settings-lane spec
+(`specs/2026-08-20-suite-settings-migration.md`). Line numbers are into each
+plan file as of 2026-08-21. Plans: **L1** `plans/2026-08-21-rt-setup-verbs.md`,
+**L3** `plans/2026-08-21-mattstack-app-shell.md`, **L4**
+`plans/2026-08-21-release-pipeline.md`, **L7** `plans/2026-08-21-clean-room-vm.md`.
+
+Verdict in one line: no two plans can be executed as written without
+collisions on ~20 files and ~25 interface mismatches; every one below has a
+mechanical fix. Nothing requires a redesign. Five items need a ruling from
+Matt (marked **RULING NEEDED**).
+
+---
+
+## 0. Top findings (ordered by blast radius)
+
+1. **`need` reply protocol is incompatible between L1 and L3.** L1 T22 polls
+   `GET /setup/need/<id>` expecting "404 = not yet" and a body `{ok, detail}`
+   (L1:955-959, test L1:963 "returns 404 twice then 200 {ok:true,…}"). L3 T9 (and
+   the contract) serve **200 `{state:"pending"|"done"|"failed", detail}` for every
+   id, never 404** (L3:2769 "unknown/unstarted id is pending — rt keeps polling",
+   L3:2850-2855). As written L1 treats the first 200 `pending` as a reply with
+   `ok` undefined → step fails instantly. Fix L1 T22 (§5 #1).
+2. **L1's uninstall `need` types and action ids are not understood by L3.** L1
+   emits `{type:"app-unregister-services"}` and `{type:"app-privileged", op:"proxy-remove"}`
+   (L1:143-145, 1124); L3's NeedBroker handles only `app-register-services` and
+   `app-privileged/proxy-install`, everything else → `failed: unknown need type`
+   (L3:2879-2891); `PrivilegedInstalling` has no `proxyRemove()` (L3:2549-2551).
+   L3's stub uses action ids `deck.managed`, `plugins.remove` and lacks
+   `shell.remove`, `extension.uninstall`, `data` (L3:1471-1477) vs L1's
+   `UninstallActionId` (L1:147). Fix L3 T8/T9/T4 + contract (§5 #12-14).
+3. **`~/.local/bin/rt`, `mattstack.appPath`, legacy sweep and the vsix path are
+   implemented twice** — L4 T9 rewrites `commands/post-install.ts`
+   (`recordAppPath`, `installRtBinaryStep(root)`, `runLegacySweep(root)`,
+   `runPostInstall(opts:{bundleRoot})`, L4:1991-2127) while L1 T27 rewrites the
+   same file into "sweep → `setupApply([...])`" with `runPostInstall(args)`
+   (L1:1065, 1080) and L1 T24 `settings.seed`/`path.link` re-implement appPath +
+   link. Same file, same functions, different signatures. Ruling §1 row 1.
+4. **`commands/update.ts`, `commands/verify.ts`, `cli.ts`, `README.md` are each
+   rewritten by both L1 and L4** with different semantics (`rt update` exit 1 vs
+   exit 2 + `--json`; verify = new ad-hoc checks vs verify = validator rows).
+   Rulings §1 rows 2-5.
+5. **rt-tray build surface is split three ways with contradictory values.**
+   `Package.swift`, `build.sh`, `check-bundle.sh`, `Info.plist`, `LaunchAgent.plist`
+   are edited by L3 T1/T2/T10 and L4 T3/T4/T5. Concrete contradictions:
+   `SUFeedURL` `https://m4ttstack.github.io/rt/appcast.xml` (L3:633-634, 735) vs
+   `https://github.com/m4ttstack/rt/releases/latest/download/appcast.xml` (L4:947,
+   1348); `SUScheduledCheckInterval` 86400 (L3:643) vs 21600 (L4:24, 1127);
+   `CFBundleURLName` `@@BUNDLE_ID@@.join` (L3:622-632) vs `@@BUNDLE_ID@@.url`
+   (L4:637-650); prod `KeepAlive` `{SuccessfulExit:false}` (L3:557-558, spec §8) vs
+   `bool true` (L4:1098, check-bundle L4:789); agent `EnvironmentVariables.PATH`
+   `/usr/bin:/bin:/usr/sbin:/sbin` (L3:574) vs
+   `/Applications/$APP_NAME.app/Contents/Helpers:/usr/bin:/bin:/usr/sbin:/sbin`
+   (L4:1102-1103, asserted L4:1251) vs spec §7 "`PATH=<app>/Contents/Helpers:/usr/bin:/bin`
+   plus `~/.local/bin`". L4's build.sh `PlistBuddy Add :SU*`/`Add :EnvironmentVariables`
+   fails if L3's templates already contain the keys. L4 ships **only the daemon
+   plist** (L4:55, 2550, OQ8); L3 ships daemon + deck via `scripts/render-launchagents.sh`
+   (L3:561-562); L1 `servicePlists` asks the app to register **both**
+   (L1:951) and L3 reports `ok` only when every plist registers → `services.register`
+   fails on every L4-built bundle. Rulings §1 rows 12-19, drift §2 #8-#11.
+6. **Bundle-resolution contract is duplicated and disagrees on layout.** L4 T1
+   `lib/bundle-layout.ts` (`appBundleRoot`, `bundledHelperPath`, `bundledExec`,
+   deps.lock-driven; `node` is a dir `Helpers/node/bin/node`, fast-browser is
+   `[node, Helpers/fast-browser/bin/fast-browser.mjs]`, L4:52-53, 168, 317) vs L1
+   T5 `lib/deps/resolve.ts` (`HELPER_TOOLS` flat `Contents/Helpers/<tool>` incl.
+   `node`, `fast-browser`; `bundledToolPath`; `link()` = symlink only, L1:389-407).
+   L4 explicitly says "L1's `rt deps link` renders the wrapper in `~/.local/bin`
+   from `exec`" (L4:41) — L1 has no wrapper rendering. Fix L1 T5/T8/T21 to consume
+   bundle-layout (§5 #4-#6).
+7. **L7's accessibility identifiers do not exist in L3.** L7 drives
+   `setup.window`, `setup.continue`, `setup.install`, `setup.finish`,
+   `setup.card.create|join`, `setup.field.teamName|inviteCode`, `row.<id>`,
+   `row.<id>.action|.status`, `connect.field.token`, `connect.submit`,
+   `row.install.failedStep.status` (L7:55, 1164-1244); L3 defines
+   `setup.welcome.screen`, `setup.<screen>.continue`, `setup.team.card.create|join`,
+   `setup.team.create.name`, `setup.team.join.code`, `setup.checklist.row.<id>[.action|.status]`,
+   `setup.checklist.connect.field.<name>`, `setup.checklist.connect.submit`,
+   `setup.install.retry`, `setup.done.continue`, `setup.checklist.relaunch`
+   (L3:3714-3779). L7 itself says "not yet in the L3 plan" (L7:55) — it was written
+   before L3's AXID file. Fix L7 T6 (§5 #30).
+8. **Restore card performs no restore.** L3 T13 runs only
+   `rt restore <repo> --dry-run --json` with stdin `{"ageKey"}` (L3:4286-4287)
+   and never `rt setup intent restore`; L1 `home.restore` "never runs restore
+   itself" and fails with remedy "Run `rt restore …`" (L1:1009). Nobody clones the
+   home repo. **RULING NEEDED** on owner (§5 #17).
+9. **`scripts/e2e-cleanroom.sh` CLI disagrees with its only CI caller.** L4 T8
+   calls `scripts/e2e-cleanroom.sh "<zip>"` positionally (L4:1781, 1784); L7 T12
+   requires `--artifact <tar.gz|zip> | --tag | --app` (L7:1872), its `--tag` path
+   downloads `rt-darwin-arm64-*.tar.gz` (L7:1901-1902) which L4 no longer publishes
+   (L4:19, Decision 2), it runs `rt daemon install` after `--post-install`
+   (L7:1927) and passes no `--no-launch` (only via `--post-install-args`, L7:1925).
+   Fix L7 T12 (§5 #34).
+10. **`rt team create`, `rt setup github status`, `rt team status`,
+    `rt uninstall --yes`, `rt settings dev-mode`, `rt setup slack create-app`
+    argv drift between L3 and L1/rt.** L3: `--remote gh:<owner>/<repo>` (L3:4270-4272)
+    vs L1 `--create-repo <owner>` (L1:762); L3 expects `setup github status` →
+    `{status, handle, owners}` (L3:4253) vs L1 `{integration,status,detail,scopesSeen}`
+    (L1:618); L3 `team status --json` → `{name,slug,remote,lastPush,members}`
+    (L3:5069) — no such verb in L1 or the contract; L3 `uninstall --delete-data --json`
+    without `--yes` (L3:5091) → L1 exits 2 `confirm-required` on non-TTY (L1:1126);
+    L3 `settings dev-mode on|off` (L3:5201) vs the real verb `dev-mode <dev|prod>`
+    with `requiresTTY: true` (lib/command-tree-def.ts:682-689); L3 sends
+    `--config-token-stdin` **and** JSON `{configToken}` (L3:4509, 4526) while L1
+    reads a raw token line when the flag is present (L1:629). §5 #15-#21.
+
+Cross-cutting: **none of the four plans states a rebase/merge order relative
+to the others** (L1 only rebases onto `origin/main`; L3/L4/L7 have no statement).
+The order in §3 is mandatory, not advisory.
+
+---
+
+## 1. File-ownership conflict matrix
+
+Legend: **Owner** = the lane whose edit stands; others **drop**, **consume**
+(use the owner's API, no edit), or **rebase-after** (keep a disjoint edit but
+apply it on top of the owner's). Task numbers are the ones to amend.
+
+| # | File | L1 | L3 | L4 | L7 | Overlap | RULING |
+|---|---|---|---|---|---|---|---|
+| 1 | `commands/post-install.ts` | T8 (import `detectEditors` from `lib/editors.ts`), **T27** (entry only: sweep + `setupApply([...])`; deletes `installRtBinaryStep/installTrayApp/installExtensions/installDaemon`; `runPostInstall(args)`) | — | **T9** (replace `installRtBinaryStep`+`installTrayApp` with `recordAppPath(root)`+`installRtBinaryStep(root)`, `findVsix(root)`, `runLegacySweep(root)`, `runPostInstall(opts:{bundleRoot})`, keeps `installDaemon`, `open`) | — | **Overlapping** (same functions, incompatible signatures) | **L1 owns.** L4 T9 drops `commands/post-install.ts` and `lib/__tests__/post-install-sweep.test.ts` from its Files; keeps `lib/dev-mode.ts`, `lib/rt-paths.ts` + their tests. L1 T27 absorbs verbatim: L4's `appPathIsTransient`/exit-2 refusal (L4:1993-2006, 2107), L4's `runLegacySweep(root)` body (L4:2064-2092) and its new test case (L4:1928-1937), and a `bundleRoot` override: `runPostInstall(args: string[], opts: { bundleRoot?: string \| null } = {})`. L1 T24 `settings.seed` derives `appPath` via `bundleRootFromExec()` (L4 T1), not its own regex. |
+| 2 | `commands/update.ts` | **T30** (rewrite: `POST /update/check` via `trayRequest`; exit 2 + `--json` envelope `{error:{code:"app-not-running"}}`; tree description) | — | **T10** (rewrite: `trayQuery`; exit 1; no `--json`; `deps` injectable) | — | **Overlapping** (both full rewrites) | **L1 owns** (contract exit codes: `2` user-actionable, `--json`). L4 T10 **dropped** (update.ts, its test, the cli.ts comment). L1 T30 adopts L4's injectable `deps` shape + the `res.ok === false` "app predates CLI-triggered updates" branch (L4:2244-2247) and the `RELEASES_URL` constant. L4 T12 regenerates `website/docs/reference/update.mdx` **after** L1 T30 lands (rebase-after). |
+| 3 | `commands/verify.ts` | T7 (move `checkRtContextExtension`), **T11** (replace `runChecks` with `rowsToChecks(composePlan)`; delete old check bodies) | — | **T11** (replace fzf block; add `"rt link"` + `"bundled extension"` checks after the tray block, L4:2361-2398) | — | **Overlapping** (L1 deletes the block L4 edits) | **L1 owns.** L4 T11 drops the `commands/verify.ts` edit (keeps `lib/fzf.ts`, `lib/notifier.ts` + tests). L1 T7 adds two rows to the rt-health table so nothing is lost: `tool.rt-link` (required:false; prod only; `readlink(~/.local/bin/rt) === join(appBundlePath, "Contents/MacOS/rt")` → ready, else needs-you "run: rt setup apply --from path.link") and `tool.vsix` (required:false; `<app>/Contents/Resources/rt-context.vsix` exists); `tool.fzf` detail uses L4's `resolveFzf()` ("bundled \| PATH"). |
+| 4 | `cli.ts` | **T10** (first-run hook: hint instead of auto-setup; skip list), **T27** (`--post-install` passes `args.slice(1)`) | — | T10 (lines 118-122 comment only) | — | Overlapping (L1 rewrites the block) | **L1 owns.** L4 T10 drops (already dropped by row 2). |
+| 5 | `README.md` | T31 ("replace the brew/tmux/zellij/terminal-notifier lines with 'Install mattstack.app from the DMG; rt is inside'") | — | **T12** (rewrites `## Install`, `### What Gets Installed`, `### Upgrade`, `## Requirements`, `### Testing the installer`, `### rt-tray`, `### Release process`) | — | **Overlapping** (same sections) | **L4 owns.** L1 T31 drops its README edit; L1 T31 only regenerates reference pages (`bun run docs:gen`/`docs:check`) and **rebases after L4 T12**; L1's grep for `tmux\|zellij\|terminal-notifier\|brew install fzf` becomes an assertion that L4 already removed them. |
+| 6 | `website/docs/**` | T31 (regenerate reference pages for new verbs) | — | T12 (`getting-started/install.mdx`; regenerate `reference/update.mdx`) | — | Disjoint files; both run `docs:gen` | Whoever merges second re-runs `bun run docs:gen && bun run docs:check` (rebase-after). No ruling needed. |
+| 7 | `scripts/README.md` | — | — | T6 (document `scripts/release/*` + `fetch-deps.sh`) | T12 (append `## e2e-cleanroom.sh`) | Disjoint appends | Both append; second to merge rebases. L7 T12's text must say "zip" not "tarball" (see §2 #25). |
+| 8 | `.gitignore` (root) | — | T1 (`rt-tray/*.xcodeproj/`, `rt-tray/Generated/`, `rt-tray/Tests/stub-rt/.state/`) | T2 (`rt-tray/deps/`, `rt-tray/out/`, `rt-tray/.build-xcode/`, and again `rt-tray/*.xcodeproj/` at L4:585-591) | — | One duplicate line | **L3 owns** `rt-tray/*.xcodeproj/`; L4 T2 drops that line (L4 OQ7 resolved: L3 regenerates the project). Rest disjoint, rebase-after. |
+| 9 | `lib/rt-paths.ts` | consumes (`installedTrayAppPath`, `TRAY_APP_BUNDLE`) | — | **T9** (`trayAppPath(exists?)`/`devTrayAppPath(exists?)` → `installedTrayAppPath(...) ?? /Applications/...`; `legacyUserAppPath()`) | — | None (L1 consumes) | **L4 owns.** L1 T5 `appBundlePath()` must be `appBundleRoot()` from `lib/bundle-layout.ts` (which already calls `installedTrayAppPath`, which already reads `mattstack.appPath` — verified in `lib/rt-paths.ts:144-158` on main). L1 T5 **after** L4 T1+T9. |
+| 10 | `lib/dev-mode.ts` | consumes (`currentMode`, `rtBinaryPath`) | — | **T9** (`installRtBinary(src)` → atomic symlink) | — | None | **L4 owns.** L1 T5 `link(p,"rt")` calls `installRtBinary(target)` (atomic link-then-rename) instead of a bare `p.symlink`; `isOurLink` unchanged. |
+| 11 | `lib/fzf.ts`, `lib/notifier.ts` | — | — | **T11** | — | None | L4 owns. L1 T7 `tool.fzf` uses `resolveFzf()`. |
+| 12 | `rt-tray/Package.swift` | — | **T1** (full rewrite: tools 5.9, `.macOS(.v14)`, MattstackCore/checks/XCTest targets), **T10** (Sparkle `from: "2.9.6"`, rpaths, `Package.resolved`) | T3 (`.macOS(.v13)`→`.v14` one-liner), T5 (Sparkle dep + rpath, `Package.resolved`; "skip if L3 has already added") | — | **Overlapping** | **L3 owns.** L4 T3 drops the Package.swift edit; L4 T5 drops the Package.swift/Package.resolved edit unconditionally and becomes "requires L3 T10 merged" (its `check_sparkle` assertions stay). **Mandatory order:** L3 T1 + T10 merged before L4 T4/T5 run. |
+| 13 | `rt-tray/build.sh` | — | T10 ("fenced stopgap": Sparkle copy+sign, **plus** `render-launchagents.sh` call replacing the sed/KeepAlive block, L3:3243-3271) | T3 (minimal: `rt-daemon`→`rt`, `-i rt`, `numeric_build`), **T4** (full rewrite) | — | **Overlapping** (L4 T4 deletes L3's stopgap) | **L4 owns.** L3 T10's stopgap is permitted only while L4 T4 has not merged and must be fenced exactly as L3 writes it; L4 T4's rewrite **must** (a) call `"$SCRIPT_DIR/scripts/render-launchagents.sh" <prod\|dev> "$CONTENTS/Library/LaunchAgents"` instead of its own `sed`+`PlistBuddy` block (L4:1093-1104), (b) keep `embed_sparkle` + inside-out Sparkle signing, (c) use `PlistBuddy Set` (not `Add`) for every key L3's Info.plist template already declares. |
+| 14 | `rt-tray/check-bundle.sh` | — | T10 (UpdateChecker awk → `UpdatePolicy.shouldStartUpdater` grep; `assert_bin_has "silent dev updater"`; `KA_PRINT` both flavors expect `SuccessfulExit`, L3:3229-3273) | **T3** (full rewrite), T4 (Helpers section), T5 (Sparkle section) | — | **Overlapping** | **L4 owns.** L4 T3's rewrite must carry L3's three assertions and flip L4:789 (prod `KeepAlive=true`) to `KeepAlive:SuccessfulExit=false` for both flavors; add a deck-plist assertion (`Contents/Library/LaunchAgents/com.mattstack.deck[.dev].plist`, Label, `BundleProgram Contents/Helpers/deck`); change the PATH assertion (L4:1251) to whatever §2 #9 rules. L3 T10 drops its check-bundle edit **if** L4 T3 has merged; otherwise L4 absorbs at rebase. L4's Swift source gates (L4:856-866: `forInfoDictionaryKey: "MSDaemonLabel"`, `defaultDaemonLabel = "com.mattstack.daemon"`, literal `path == "/flavor/retire"`, socket guard before `AppDelegate()` in `main.swift`) become explicit requirements of L3 T9 (TrayServer refactor) and T18 (main.swift). |
+| 15 | `rt-tray/Info.plist` (template) | — | **T2** (`LSMinimumSystemVersion 14.0`, `CFBundleURLTypes` name `@@BUNDLE_ID@@.join`, `SUFeedURL`, `SUPublicEDKey` placeholder `REPLACE_WITH_RELEASE_PUBLIC_ED_KEY`, `SUEnableAutomaticChecks`, `SUAutomaticallyUpdate`, `SUVerifyUpdateBeforeExtraction`, `SUScheduledCheckInterval 86400`, `NSAppTransportSecurity.NSAllowsLocalNetworking`) | T3 (`LSMinimumSystemVersion 14.0`, `CFBundleURLTypes` name `@@BUNDLE_ID@@.url`); T4 build.sh `PlistBuddy Add :SU*` | — | **Overlapping, contradictory values** | **L3 owns the template** (and `project.yml` `info.properties` — one source). L4 T3 drops its Info.plist edit. Values in L3 T2 are corrected to L4's canon: `SUFeedURL = https://github.com/m4ttstack/rt/releases/latest/download/appcast.xml`, `SUScheduledCheckInterval = 21600` (pending §4 #1 ruling on the host). L4 T4 build.sh writes `SUFeedURL`, `SUPublicEDKey`, `SUEnableAutomaticChecks` with `Set` (create-if-missing helper), dev flavor `Set :SUEnableAutomaticChecks false`. |
+| 16 | `rt-tray/LaunchAgent.plist` (template) | — | **T2** (`EnvironmentVariables.PATH`, KeepAlive via render script; "keep everything else as is") | T3 (`BundleProgram`/`ProgramArguments` → `Contents/MacOS/rt`; Label comment); T4 build.sh `Add :EnvironmentVariables:PATH`, KeepAlive by flavor | — | **Overlapping** | **L3 owns.** L3 T2 additionally applies L4 T3's rename in the template (`BundleProgram Contents/MacOS/rt`, `ProgramArguments [Contents/MacOS/rt, --daemon]`, comment "Label: com.mattstack.daemon (prod) / com.mattstack.daemon.dev (dev)"). L4 T3 drops the LaunchAgent.plist edit; L4 T4 renders via the script (row 13). PATH value: §2 #9. |
+| 17 | `rt-tray/LaunchAgent-deck.plist`, `rt-tray/scripts/render-launchagents.sh`, `rt-tray/project.yml`, `rt-tray/entitlements/mattstack.entitlements` | — | **T2** create | consumes `project.yml` (T4 `xcodegen generate --spec`, schemes `mattstack`/`mattstack-dev` — names match L3:937-941/L3 targets) | — | None | L3 owns; L4 T4 consumes `render-launchagents.sh` (row 13) and bundles **both** plists; L4 OQ8 ("deck plist is L3/L5's") is closed: L3 ships it, L4 copies it. |
+| 18 | `rt-tray/Sources/AppDelegate.swift` | — | **T10**, **T18** (major) | T3 (`:331` `rt-daemon`→`rt`) | — | Overlapping | **L3 owns `rt-tray/Sources/**`.** L4 T3 drops all four Swift edits; L3 T3 already resolves `Contents/MacOS/rt` first (L3:1215) — L3 T18 adds the `AppDelegate.swift:331` string change; `DaemonLifecycle.swift:8,17-18` and `Sources-daemon-shim/main.swift:4,26` comment edits move to L3 T18 (or L3 T3). |
+| 19 | `rt-tray/Sources/UpdateChecker.swift` | — | **T10** deletes | T3 modifies `:164` | — | Delete vs modify | L3 deletes; L4 T3 drops. |
+| 20 | `rt-tray/Sources/TrayServer.swift`, `main.swift`, `TrayState.swift`, `ProcessPanelView.swift` | — | T9, T18 | (check-bundle source gates only) | — | None | L3 owns; see row 14 for the gates L3 must preserve. |
+| 21 | `commands/settings.ts:462-471`, `lib/__tests__/dev-mode-handoff.test.ts`, `scripts/entitlements.plist` | — | — | T3, T9 | — | None | L4 owns. (L3 T2 creates a second entitlements file `rt-tray/entitlements/mattstack.entitlements` for xcodebuild; L4 build.sh signs the outer app with an inline plist — same content `app-sandbox=false`; fine, note only.) |
+| 22 | `lib/command-tree-def.ts`, `lib/module-registry.ts`, `lib/daemon-client.ts`, `lib/daemon.ts`, `lib/shell-integration.ts`, `lib/secrets/*`, `lib/home/age-key.ts`, `commands/secrets.ts`, `commands/extension.ts`, `lib/editors.ts`, `e2e/tests/setup.test.ts` | L1 (many tasks) | — | — (L4 T10 consumed `trayQuery`, now dropped) | — | None | L1 owns. |
+| 23 | `lib/bundle-layout.ts` (L4 T1) vs `lib/deps/resolve.ts`, `lib/deps/links.ts` (L1 T5) | T5 | — | T1 | — | Different files, **same responsibility** | **L4 T1 is the substrate; L1 T5 consumes it** (§5 #4-#6). L1 T5 runs after L4 T1 merges. |
+| 24 | `.github/workflows/release.yml` | — | — | **T8** | consumes (`scripts/e2e-cleanroom.sh`) | None | L4 owns; L7 T12's script must accept L4's call shape (§5 #34). |
+| 25 | `scripts/e2e-cleanroom.sh` | — | — | calls | **T12** | Interface only | L7 owns; interface fixed in §5 #34. |
+| 26 | `rt-tray/vm/run/make-dmg.sh`, `make-appcast.sh` (L7 T3) vs `scripts/release/make-zip.sh`, `make-dmg.sh`, `appcast.sh` (L4 T6) | — | — | T6 | T3 | Duplicate recipes (different files) | Both stand (L7 needs a pre-L4 path and a loopback appcast). L7 T3 must call `scripts/release/make-zip.sh`/`make-dmg.sh` when they exist (§5 #33) so the DMG under test is L4's recipe. |
+| 27 | `docs/superpowers/specs/2026-08-21-rt-setup-contract.md` (+ spec, research dir) | **T13** ("the only spec edit this plan makes": team-scope secrets layout heading) | **T0** (copies spec + contract + research into the L3 branch) | — | — | Docs branch collision | **Neither lane commits spec files in its branch.** Merge `docs/mattstack-app-installer-spec` (from `repo-tools-appspec-wt`) into `main` before execution; L3 T0 Step 2 is dropped; L1 T13's layout note is applied to the contract in the appspec branch (as one of the amendments in §5) and L1 only references it. |
+| 28 | `rt-tray/vm/golden/{build-golden,provision-guest,verify-golden}.sh` | — | — | — | T2 create; **T13 edits all three** but lists only `run/xcuitest.sh` | Within-lane only | L7 T13 Files block must list the three golden scripts (plan hygiene; no cross-lane effect). |
+
+No other file appears in two plans' Files blocks. (`lib/__tests__/post-install-sweep.test.ts`: L1 T27 "keep green" + L4 T9 new case → covered by row 1.)
+
+---
+
+## 2. Interface drift (producer → consumer)
+
+Each item: what A produces, what B consumes, mismatch, fix (which plan/task).
+
+1. **`GET /setup/need/<id>` reply.** L3 T9 / contract: 200 `{state:"pending"|"done"|"failed", detail}`, `POST` → 405, empty id → 400 (L3:2765-2782, 2850-2855). L1 T22 `awaitNeed`: 404 = not yet; 200 body `{ok, detail}` (L1:953-959, 963). **Fix L1 T22:** poll until `state !== "pending"`; `done` → `{ok:true, detail}`, `failed` → `{ok:false, detail}`; treat 404 as pending too (tolerant); keep "status 0 ×3 → app-gone". Contract already says this; L1 OQ1 is resolved by L3's implementation.
+2. **Need types.** L1 emits `app-register-services`, `app-unregister-services`, `app-privileged {op: proxy-install | proxy-remove}` (L1:143-145); L3 handles `app-register-services`, `app-privileged/proxy-install` only (L3:2879-2891); `PrivilegedInstalling` lacks `proxyRemove` (L3:2549). **Fix L3 T8/T9**: add `proxyRemove()` (helper arg `remove`) and `app-unregister-services` → `services.unregister(plists:)` (SMAppService `unregister()`); **contract**: add both types to the `need` list.
+3. **Uninstall event ids.** L1 `UninstallActionId` = `services.unregister | deck.managed-remove | proxy.remove | path.unlink | shell.remove | extension.uninstall | plugins.uninstall | data | app.trash` (L1:147); L3 stub `deck.managed`, `plugins.remove`, no `shell.remove/extension.uninstall/data` (L3:1471-1481). **Fix L3 T4** stub to L1's ids; **contract**: list the ids under `rt uninstall`.
+4. **`rt uninstall` confirmation.** L1 T29: "`--delete-data` without `--yes` on non-TTY → exit 2 `confirm-required`" (L1:1126); L3 T17 streams `uninstall --keep-data|--delete-data --json` without `--yes` (L3:5091). **Fix L3 T17:** append `--yes` (the app's sheet is the confirmation). L1 T29: non-TTY + `--keep-data` needs no `--yes` (already implied; state it).
+5. **`rt team create` remote spelling.** L3 T13: `["team","create",name,"--remote", useGhRepo ? "gh:\(ghRepoPreview)" : remoteURL, ("--others"), "--json"]` (L3:4270-4272); L1 T16: `--remote <url> | --create-repo <owner> [--others] [--json]` (L1:762). **Fix L3 T13** to `--create-repo <owner>` (repo name `mattstack-team-<slug>` is L1's, matches L3's preview L3:4237). L3 OQ3 closed.
+6. **`rt setup github status --json` shape.** L3 T13 decodes `{status, handle, owners}` (L3:4253); L1 T12 prints `{integration, status, detail, scopesSeen}` (L1:618). **Fix L1 T12:** github status adds `handle` (`gh api user` login) and `owners` (`[handle, …gh api user/orgs[].login]`) when gh is authenticated; **contract** adds them.
+7. **`rt team status --json`.** L3 T17 runs it (L3:5069) expecting `{name, slug, remote, lastPush, members}`; absent from L1 and contract. **Fix L1 T19** (add `teamStatus` in `commands/team.ts`: slug/name from `readTeamSnapshot`, remote masked is L3's job, `lastPush` = `git -C teams/<slug> log -1 --format=%cI origin/main` or null, `members` = `board.members` usernames); **contract** adds the verb.
+8. **`rt settings dev-mode`.** L3 T17 `["settings","dev-mode", isDev ? "off" : "on"]` (L3:5201); real verb takes `dev|prod` and is `requiresTTY: true` (tree L682-689). **Fix L3 T17** → `["settings","dev-mode", isDevBuild ? "prod" : "dev"]`; **L1 (new micro-step in T31):** drop `requiresTTY` when a Target arg is given (prompt only when omitted).
+9. **`rt setup slack create-app` stdin.** L3 T14 passes `--config-token-stdin` **and** stdin JSON `{configToken}` (L3:4509, 4526); L1 T12: flag ⇒ raw token line, no flag ⇒ JSON (L1:629). **Fix L3 T14:** drop the flag when sending JSON. (L1 may additionally accept JSON under the flag when the line parses as an object — optional hardening.)
+10. **`rt team join --dry-run` failure shape.** L1 T18 returns exit 0 result `{access:"denied"|"unreachable", message}` per contract (L1:819-823); L3 stub `join-no-access` exits 2 `{error:{code:"no-access"}}` (L3:1465) and TeamChoiceModel renders the user error. **Fix L3 T4 + T13:** stub returns exit 0 `{access:"denied", message:"You don't have access yet: ask matt …"}`; model renders `access != "ok"` from the result (keep exit-2 handling for `invite-unknown`/`invite-malformed`, which L1 does throw).
+11. **`mattstack.appPath` key write.** L3 T18 `rt settings set mattstack.appPath "<json string>" --scope machine` — matches the real tree (`set <Key> <Value> --scope`). ✓ No change. (Both the app and L1 `settings.seed`/L4 write the same value; harmless.)
+12. **`GET /version.build` type.** Contract: `"build": 2080` (number); L4: CFBundleVersion = `major*1e6+minor*1e3+patch` → `2008000` (L4:23, OQ2); L3 T9/T18 emits `build: CFBundleVersion ?? "0"` as a **string** (L3:5759); stub `"build": "0"` (L3:1485). L7 asserts only `version` (L7:1329). **Fix contract** example → `"build": 2008000`; **L3 T9/T18**: `build: Int(CFBundleVersion) ?? 0`; stub `build: 0`.
+13. **Sparkle feed URL / interval.** L3 `https://m4ttstack.github.io/rt/appcast.xml`, 86400 (L3:633-644, 735-742); L4 `…/releases/latest/download/appcast.xml`, 21600 (L4:947, 1127; check-bundle L4:1348). **Fix L3 T2** (Info.plist + project.yml) to L4's values, subject to §4 #1.
+14. **`MATTSTACK_APPCAST_URL`.** L3 honours it only when `MSDevBuild` is true **or** launched with `--allow-appcast-override` (L3:3028, 3074-3086); L7 launches the **prod** app with `open --env MATTSTACK_APPCAST_URL=…` and no arg (L7:899-901, 1606) → ignored. Also the FDA step relaunches the app (L7:1204-1208) and the env may not survive. **Fix L7 T5/T8:** `open --env MATTSTACK_APPCAST_URL=… --args --allow-appcast-override` and re-apply on every launch the driver performs; **L3 T18:** the self-relaunch after FDA re-execs with the current `ProcessInfo.arguments` + environment (state it).
+15. **Agent plist set.** L1 `servicePlists(mode)` = `[com.mattstack.daemon[.dev].plist, com.mattstack.deck[.dev].plist]` (L1:951-952); L3 registers whatever is in `Contents/Library/LaunchAgents` and `services.register` is `ok` only if **every** requested plist registers (L3:2879-2891, 2946-2950); L4 bundles only the daemon plist (L4:55) and `deck` is `pending` (L4:54) → deck plist (L3) registers a missing `Contents/Helpers/deck` → `.notFound`/error → step fails. **Fix:** L4 T4 bundles both plists (row 13/17); **L1 T22/T25**: request the deck plist only when `resolveTool(p,"deck").chosen` is non-null (log "deck not bundled yet — not registered"); **L3 T7**: a plist whose `BundleProgram` does not exist registers as `notFound` and is reported `ok:false, status:"notFound"` — L1 then decides; keep.
+16. **Bundle layout / helper exec.** L4 T1: `Helpers/node/bin/node`, `Helpers/fast-browser/bin/fast-browser.mjs`, `bundledExec("fast-browser") = [node, mjs]`, `bundledHelperPath(name)` from deps.lock (L4:52-53, 297-318); L1 T5: `HELPER_TOOLS` flat files incl. `node`, `fast-browser`; `bundledToolPath`; `link()` symlink only; T8 `tool.fast-browser` execs `<chosen> doctor --json`; T21 `setupTool("fast-browser")` execs `[chosen, "setup"]`. **Fix L1 T5/T8/T21** (§5 #4-#6): `ToolResolution.exec: string[] | null`; symlink for single-file tools, **tagged wrapper** for multi-argv tools; `isOurLink` recognises both; rows/steps spawn `[...exec, "doctor","--json"]`.
+17. **`~/.local/bin/rt` install.** L4 T9 `installRtBinary(src)` = atomic symlink (L4:1953-1961); L1 T5 `link(p,"rt")` = `p.symlink` + "dev-mode-owns-rt" refusal (L1:404-405). **Fix L1 T5:** `link("rt")` calls `installRtBinary(target)`.
+18. **AX identifiers** (L7 → L3): see Top #7. **Fix L7 T6** with the mapping in §5 #30. Row ids used by L7: `perm.loginItems` → L1's `perm.login-items` (L1:433); `account.github`, `perm.fda`, `perm.notifications`, `tool.clt` ✓.
+19. **Stub row ids vs real ids.** L3 stub `perm.loginItems`, `access.teamRepo`, `tool.fastbrowser`, `info.path` (L3:1368-1393) vs L1 `perm.login-items`, `access.team-repo`, `tool.fast-browser`, `tool.path` (L1:433-444, 492, 532). **Fix L3 T4** (XCUITest uses only `perm.fda`, unaffected).
+20. **Stub env.** Contract names only `RT_STUB_SCENARIO`; L3 requires `RT_STUB_PATH` (absolute path to `stub.ts`), optional `RT_STUB_BUN` (default `~/.bun/bin/bun`), `RT_STUB_STATE_DIR` (L3:1203-1207, 1247); L7 knows PATH/BUN (L7:55). **Fix contract** §Stub: list all four.
+21. **`--post-install` flags.** L1 T27: `runPostInstall(args)` = sweep → `setupApply(["--non-interactive","--team-of-one", ...args])`; `--no-launch` implied by `--ci`/`CI=true` (L1:1073-1080); L4 T8 (via L7) passes `--post-install --non-interactive --team-of-one --no-launch` (L4:30, 1784) ✓; L7 T12 passes only `--post-install $PIA` with `--post-install-args` (L7:1925) and `CI=true` (L7:1921). Works (CI implies no-launch) but **fix L7 T12** to default `PIA="--non-interactive --team-of-one --no-launch"`.
+22. **`scripts/e2e-cleanroom.sh` invocation.** L4 T8: `scripts/e2e-cleanroom.sh "$(ls … mattstack-*.zip | head -1)"` positional (L4:1781); L7 T12 usage `(--artifact <tar.gz|zip> | --tag <vX.Y.Z> | --app <app>)` (L7:1872); `--tag` downloads `rt-darwin-arm64-*.tar.gz` (L7:1901-1902, dropped by L4); extracts a bare `rt` or `Contents/MacOS/rt-daemon` fallbacks (L7:1914-1917). **Fix L7 T12:** accept a single positional path as `--artifact`; `--tag` downloads `mattstack-*.zip`; drop tarball/`rt-daemon` branches; after `ditto -x -k` the app root is `<work>/release/mattstack.app` and rt is `…/Contents/MacOS/rt`; also run `rt-tray/check-bundle.sh --app` only if present (L4's sparse checkout is `scripts` only — L4 T8 may widen to `scripts rt-tray`).
+23. **`rt daemon install` in the headless recipe.** L7 T12 runs it after `--post-install` (L7:1927); under L1, `services.register` is skipped honestly when no app is reachable (`no-app` + non-interactive, L1:1030), so `daemon.json` is absent and `rt daemon install` (existing verb) is what writes it. Consistent; keep, but L7 must not assert daemon running in CI (it doesn't: `rt verify --ci` warns).
+24. **`rt verify --json` shape.** L7 greps `"passed": *true` and per-check `"status"`/`"name"` (L7:1317-1321); L1 T11 keeps `{passed, summary, checks}` and adds `plan` (L1:600) ✓.
+25. **Artifact names.** L4 `mattstack-<version>.dmg/.zip`, `appcast.xml`, `*.delta`, `SHA256SUMS` (L4:19, 1578); L7 expects `mattstack-<ver>.dmg/.zip` ✓ but its README/usage still say `rt-darwin-arm64-*.tar.gz` (L7:1840, 1942-1943, 1779). **Fix L7 T11/T12/T14** wording → zip.
+26. **`SPARKLE_PUBLIC_ED_KEY` override**: L4 build.sh honours it (L4:897, 1122-1136) ✓ L7 (L7:54, 718) ✓.
+27. **CFBundleVersion bump in L7 `make-appcast.sh`** takes an arbitrary `<new-build>` (L7:586, 734); must follow L4's numeric scheme to stay monotonic for Sparkle. **Fix L7 T3:** compute `new-build` from `<new-version>` with L4's formula (drop the arg).
+28. **`mattstack-proxy-install` helper.** L3 T8 runs `Contents/Helpers/mattstack-proxy-install install`, expects `MATTSTACK_EXIT=<n>` trailer (L3:2558, 2585, 2645); L4 deps.lock has no row and no build step (L4 bundle contract L4:45-59); L1 `proxy.install` only waits (L1:1031). **Gap:** nobody builds it. **Fix L4 T2:** add a `status:"pending"` deps.lock row `mattstack-proxy-install` (`bundlePath: Contents/Helpers/mattstack-proxy-install`, `exec` likewise) so check-bundle tolerates absence and L3 reports "helper not bundled" honestly until L5 ships it; record in L5's handoff.
+29. **Agent plist `EnvironmentVariables.PATH`.** L3 template `/usr/bin:/bin:/usr/sbin:/sbin` + "rt and deck prepend their own bundle" (L3:574-577); L4 build.sh `/Applications/$APP_NAME.app/Contents/Helpers:/usr/bin:/bin:/usr/sbin:/sbin` (L4:1102-1103; asserted L4:1251) — wrong under `~/Applications` and wrong for the dev bundle; L4:1215 "`~/.local/bin` for herdr/claude is appended by L1's service plists" — L1 has no such plists. Spec §7: `PATH=<app>/Contents/Helpers:/usr/bin:/bin` + `~/.local/bin`. **RULING NEEDED** (§4 #3). Recommended: plist PATH stays static (`/usr/bin:/bin:/usr/sbin:/sbin`), and the daemon (L1, `lib/daemon.ts` boot) and deck prepend `<appBundleRoot()>/Contents/Helpers` and `$HOME/.local/bin` to `process.env.PATH` at boot (Bun PATH-snapshot gotcha: children spawned with `env: process.env` inherit it). L4 check-bundle then asserts the static value.
+30. **KeepAlive prod.** L3 render script: dict `SuccessfulExit=false` both flavors (L3:557-558) = spec §8; L4 build.sh prod `bool true` (L4:1098) + check-bundle (L4:789). **Fix L4 T3/T4** to the dict.
+31. **`rt home init` / `rt restore` flags** (settings lane → L3/L1): L3 T13 runs `home init --dry-run --json` (L3:4297) and `restore <repo> --dry-run --json` with stdin `{"ageKey"}` (L3:4286-4287); L1 T24 `home.init` runs `rt home init` (gh only; OQ6 asks for `--remote <url>`); L1 T25 `home.restore` never runs restore. The settings-lane verbs (`rt home init [--dry-run]`, `rt restore <org>/<repo>`) have no documented `--json`, no `--remote`, no stdin key. **Dependency to confirm when main lands**; see §5 #17 for the restore ownership ruling.
+
+---
+
+## 3. Execution order
+
+Four worktrees, each off `origin/main` **after** (a) the settings lane's
+overnight merge and (b) the appspec docs branch is merged (row 27). Concurrency
+below is safe because the file sets are disjoint after the §1 rulings.
+
+**Phase A — substrate (parallel, no cross-file overlap):**
+- L4 T1 (`lib/bundle-layout.ts`), T2 (`deps.lock`, `fetch-deps.sh`, `.gitignore` minus the xcodeproj line), T6 (`scripts/release/*`), T7 (MATT key), T9-trimmed (`lib/dev-mode.ts`, `lib/rt-paths.ts` + tests only), T11-trimmed (`lib/fzf.ts`, `lib/notifier.ts` + tests), T3-trimmed (`commands/settings.ts`, `dev-mode-handoff.test.ts`, `scripts/entitlements.plist`, `check-bundle.sh` rewrite carrying L3's assertions).
+- L3 T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11 (all inside `rt-tray/`, `Sources-core/`, `Tests/`), with T4 stub ids/shapes corrected per §5.
+- L1 T1, T2, T3, T4, T6, T9, T13, T14, T15, T16(ex-`--create-repo` unchanged), T17, T18, T19 (pure new files + tree/registry).
+- L7 T1, T2, T4, T5, T7, T9, T10, T11, T14 (all `rt-tray/vm/`), T3 (own recipes; re-point later).
+
+**Phase B — dependent (mandatory rebases):**
+- **L1 T5** after L4 T1 + T9 merged (consume `appBundleRoot`, `bundledHelperPath`, `bundledExec`, `installRtBinary`, `installedTrayAppPath`).
+- **L1 T7, T8, T10, T11, T21** after L1 T5 and L4 T11 (`resolveFzf`); L1 T11 (verify rewrite) after L4's verify.ts edit is **dropped** (row 3) — no rebase then.
+- **L1 T22** after the contract amendment for `/setup/need` (§5 #1) — or simply implement per L3 T9 now.
+- **L1 T24, T27** after L4 T9-trimmed (for `bundleRootFromExec`, `installRtBinary`, `legacyUserAppPath`) — L1 T27 absorbs L4's post-install bodies (row 1).
+- **L1 T30** (update.ts) independent once L4 T10 is dropped.
+- **L4 T4, T5** after **L3 T1 + T2 + T10 merged** (Package.swift/Sparkle/templates/render script are L3's) — mandatory; L4 T5's "skip if L3 has" becomes "requires".
+- **L4 T8** any time (calls L7's script by contract); green only after L7 T12 and the §5 #34 CLI fix.
+- **L4 T12** (README/docs) after L1 T30/T31 for `update.mdx`; L1 T31 after L4 T12 (row 5). Sequence: L4 T12 → L1 T31.
+- **L3 T12–T18** (screens, Settings, AppDelegate) after L3 T1–T11; **L3 T13/T14/T17** implement the §5 argv fixes (#15-#21); **L3 T18** carries L4's Swift string edits (row 18).
+- **L7 T6** after L3 T12–T16 (AXIDs exist) — or edit ids now from L3:3714-3779 (§5 #30) and keep "fail fast on missing id"; **L7 T8** after L3 T10 (`--allow-appcast-override`) ; **L7 T3** re-point after L4 T6; **L7 T12** after agreeing the CLI with L4 T8; **L7 T13** after Xcode (and L3 T19).
+
+**Phase C — orchestrator/MATT gates:** L4 T13 (entitlements), T14 (Xcode cutover, after L3 T2 `project.yml`), L3 T20, L1 T33, L7 goldens/real runs, L4 T15 (dry run → tag; clean-room green requires L7 T12 + L1 T27's `--no-launch`).
+
+**Merge order to main (recommended):** L4-phase-A → L3 (T1–T11) → L1 (T1–T4, T6, T9, T13–T19) → L4 T4/T5/T8 → L1 T5, T7–T12, T20–T30 → L3 T12–T19 → L7 (all) → L4 T12 → L1 T31–T32 → MATT gates. Every lane rebases onto `origin/main` before each merge (only L1 states this today; add the rule to L3/L4/L7 headers).
+
+**Settings-lane dependencies (flag; not yet on main at plan time):**
+- `rt.cron` machine key migration — L1 T20 `installCronTrigger` guards `isMigrated` ✓ (honest `written:false`).
+- `rt home init --remote <url>` (L1 OQ6) — wizard's "paste a URL" home-repo path has no verb; L3 T13 only dry-runs `home init`. Needs the settings lane (or L1 T24 passes `--remote` when the tree has it).
+- `rt restore <org>/<repo>` with `--json` + key on stdin (`{"ageKey"}` per L3:4287 or `--key-stdin`) — L3 T13 and the §5 #17 ruling depend on it.
+- `rt home snapshot push` — L1 T26 falls back to `git add/commit/push` when absent ✓.
+- `board.triage` key — L1 T25 guards `getDef` ✓; `board.members` entry shape (L1 OQ7).
+- `claude.marketplaces`/`claude.plugins`, `mattstack.appPath`, `mattstack.integrations`, `mattstack.tracking` — landed (registry PR #5); L1 T9/T26 read them ✓; `installedTrayAppPath` already reads `mattstack.appPath` ✓.
+- `rt settings dev-mode` `requiresTTY` (§2 #8) — small rt change, assign to L1 T31.
+
+---
+
+## 4. Spec drift (plan vs spec/contract)
+
+1. **Appcast host.** Spec §11: "publishes the appcast to GitHub Pages". L4 Decision 1: GitHub Release asset at `…/releases/latest/download/appcast.xml` (L4:36, 947) with gh-pages as fallback (OQ1). L3 still encodes github.io. **RULING NEEDED** (recommend accept L4; amend spec §11 + L3 T2).
+2. **`rt-darwin-*.tar.gz`.** Spec §11: "remains as the internal headless artifact (a zip of the app is equivalent…)". L4 Decision 2 drops it (zip is the headless artifact). Acceptable; L7 T12/T11/T14 must switch to the zip (§2 #22, #25).
+3. **Agent plist PATH.** Spec §7/§8: explicit `<app>/Contents/Helpers:/usr/bin:/bin` + `~/.local/bin`; L3 ships a static PATH and defers to the programs; L4 hardcodes `/Applications`; neither adds `~/.local/bin`. **RULING NEEDED** (§2 #29 recommendation).
+4. **KeepAlive.** Spec §8 `{SuccessfulExit:false}`; L4 prod `true` (L4:1098, 789). Fix L4.
+5. **`xcodebuild archive/export`.** Spec §11; L4 Decision 3 uses `xcodebuild build … CODE_SIGNING_ALLOWED=NO` + own inside-out signing. Acceptable; note in spec.
+6. **Restore ceremony.** Spec §4.2: the restore card "`rt restore <org>/<repo>` clones it to `~/.mattstack`, installs the key in the Keychain, and materializes". L3 only dry-runs; L1 `home.restore` only verifies. Gap (Top #8). **RULING NEEDED**: recommend L3 runs the real `rt restore` at Continue (key on stdin) then `rt setup intent restore <org>/<repo>`; L1 `home.restore` stays a verifier.
+7. **First-run auto-setup.** Spec §11: `rt --post-install` is the headless entry; spec is silent on `cli.ts` auto-running it. L1 T10 replaces the silent auto-install with a one-line hint (L1 OQ9) because the new apply creates GitHub repos. Behaviour change for `rt verify`-after-install; accept and note in docs (L4 T12 README "Testing the installer" must not promise auto-setup).
+8. **Invite code length.** Spec §6.3 "~40 chars"; contract + L1 77 chars (16-byte id ‖ 32-byte key). Contract wins; fix spec §6.3 wording (L1 OQ2 stays a UX question for Matt).
+9. **`GET /version.build`.** Contract example `2080` vs L4's scheme `2008000` (L4 OQ2). Fix contract example (§5 #11).
+10. **Clean-room layer (b) driver.** Spec §12.2 "drives XCUITest for the five screens"; L7 drives AppleScript UI scripting first, XCUITest gated on Xcode (L7 T6/T13). Acceptable deviation; note in spec §12.2.
+11. **Team-of-one headless defaults** (L1 OQ11: `RT_TEAM_NAME`/`RT_TEAM_REMOTE`, gh-created `<login>/mattstack-team-personal`) — spec silent; the clean-room runner has no gh auth, so L1 T24 `team.create` will fail `remote-required` in CI unless `--team-of-one` tolerates "no remote yet" (skip team.create with detail) — **amend L1 T24** (§5 #10).
+12. **Contract `action.type` list** in spec §5.2 (`use-gh`, `none`) differs from the contract file (`link-bundled`, `oauth`, `owner-once`, `steps`, `run`); L1/L3 follow the contract ✓; fix spec §5.2 text.
+13. **L3 `SUScheduledCheckInterval` 86400 vs L4 21600** — spec silent; take L4's (check-bundle asserts it).
+14. **Dev flavor bundles Helpers** (L4 OQ5) — spec silent; fine.
+15. **L3 Done screen** shows the `verify` step's detail rather than running `rt verify` (L3:4953-4957) — spec §4.5 "verify summary (N checks)" satisfied by the step detail "N checks passed" (L1:1055) ✓.
+
+---
+
+## 5. Concrete amendments (apply mechanically; plan + task + change)
+
+**L1 — `plans/2026-08-21-rt-setup-verbs.md`**
+1. **T22** `awaitNeed`: replace "(404 = not yet)" and `NeedReply` polling with: GET returns 200 `{state, detail}`; `pending` (or 404) → keep polling; `done` → `{ok:true, detail}`; `failed` → `{ok:false, detail}`; test: "200 `{state:"pending"}` twice then `{state:"done", detail:"registered"}` → reply". Update the docblock at L1:954-957.
+2. **T22** `servicePlists` / **T25** `services.register`: request `com.mattstack.deck[.dev].plist` only when `resolveTool(p,"deck").chosen` is non-null; else log "deck not bundled yet — only the daemon is registered".
+3. **T1** `NeedRequest`: keep both uninstall types; add a sentence "L3 NeedBroker must handle `app-unregister-services` and `op:"proxy-remove"`" (tracked in §5 #12-13).
+4. **T5** `lib/deps/resolve.ts`: drop `HELPER_TOOLS`; `appBundlePath(p)` → returns `appBundleRoot()` (`lib/bundle-layout.ts`); `bundledToolPath(p,tool)` → `tool === "rt" ? join(root, RT_BUNDLE_PATH) : bundledHelperPath(tool, root, p.exists)`; add `bundledToolExec(p,tool): string[]|null` → `bundledExec(tool, root, p.exists)`; `ToolResolution` gains `exec: string[] | null` (`bundled` stays the first exec entry/path for display). Mark T5 "after L4 T1 + T9".
+5. **T5** `lib/deps/links.ts`: `link()` — if `exec.length === 1` symlink (for `rt` via `installRtBinary(target)`); else write a tagged wrapper `#!/bin/sh\n# mattstack-link: <tool>\nexec "<exec0>" "<exec1…>" "$@"\n` (0755); `isOurLink` = symlink into the bundle **or** regular file whose second line starts with `# mattstack-link:`; `unlink`/`reconcile` honour both. Tests: fast-browser link writes the wrapper; `isOurLink` true for it.
+6. **T8** `tool.fast-browser` and **T21** `setupTool("fast-browser")` / **T26** `fastbrowser.setup`: spawn `[...resolveTool(p,"fast-browser").exec, "doctor","--json"]` / `[..., "setup"]` (no `chosen` as argv0).
+7. **T7** rt-health table: add rows `tool.rt-link` (required:false, prod only: `p.readlink(~/.local/bin/rt) === join(appBundlePath,"Contents/MacOS/rt")` → ready "linked into the bundle"; else needs-you "not a link into mattstack.app — run: rt setup apply --from path.link") and `tool.vsix` (required:false: `<app>/Contents/Resources/rt-context.vsix` exists → ready; missing → skipped "extension not bundled (pre-bundle build)"); `tool.fzf` detail from `resolveFzf()` → "fzf <v> (bundled|PATH)".
+8. **T12** github `integrationStatus`: when gh is authenticated add `handle` (`gh api user` → `.login`) and `owners: [handle, ...(gh api user/orgs → .login)]` to the envelope; doc in the contract.
+9. **T19** (or T16): add `teamStatus(args)` → `rt team status [--team <slug>] --json` → `envelope({slug, name, remote, lastPush, members:[{username}]})`; tree node `team.status`.
+10. **T24** `team.create` under `teamOfOne` with no gh auth and no `RT_TEAM_REMOTE`: skipped "no git remote available (set RT_TEAM_REMOTE or run gh auth login)" instead of failed, so the headless clean-room job passes `verify`.
+11. **T24** `settings.seed`: derive `appPath` with `bundleRootFromExec()` (L4 T1); refuse `/Volumes/`/`AppTranslocation` paths (exit 2 in `--post-install`, failed step with remedy in apply) — port L4:1993-2006.
+12. **T27** `commands/post-install.ts`: signature `runPostInstall(args: string[], opts: { bundleRoot?: string | null } = {})`; adopt L4's `runLegacySweep(root)` body (L4:2064-2092) and the new sweep test case (L4:1928-1937); `recordAppPath`/`installRtBinaryStep` are NOT re-implemented here (they are `settings.seed`/`path.link` steps) — note that `rt --post-install` on a non-bundle `dist/rt` takes the "not running from inside the app" branches.
+13. **T29** `commands/uninstall.ts`: state "non-TTY + `--keep-data` needs no `--yes`; `--delete-data` needs `--yes` (the app passes it)".
+14. **T30** `runUpdate`: adopt L4's injectable `deps` (`tray`, `currentMode`, `log`, `exit`) and add the `res.ok === false` branch ("this mattstack.app can't be asked from the CLI — use the menu bar"); exit codes stay 2/`--json` per contract; `RELEASES_URL = https://github.com/m4ttstack/rt/releases/latest`.
+15. **T31**: remove the README edit; add: `rt settings dev-mode <dev|prod>` drops `requiresTTY` when Target is given; regenerate docs **after** L4 T12 merges.
+16. **T13**: the contract paragraph ("Team-scope secrets layout") is applied in the appspec branch, not committed from the L1 worktree; T13 references it.
+17. **T25** `home.restore` — keep as verifier; add: "L3 runs the real `rt restore` (key on stdin) at screen 2 and then `rt setup intent restore <org>/<repo>`; this step verifies clone + key" (**pending Matt's ruling**, §4 #6).
+18. **Global constraints**: add "rebase onto `origin/main` after L4 T1/T9/T11 merge before starting T5/T7/T24/T27" and "do not edit `commands/verify.ts`/`update.ts`/`cli.ts`/`README.md` from any other lane" (mirrors §1).
+19. **T10** cli.ts skip-list: also skip the first-run hint when `args[0] === "--post-install"` (it is already, via the earlier branch) — no change; state it.
+
+**L3 — `plans/2026-08-21-mattstack-app-shell.md`**
+20. **T0 Step 2**: drop (spec/contract are merged to main first).
+21. **T2** Info.plist + project.yml: `SUFeedURL = https://github.com/m4ttstack/rt/releases/latest/download/appcast.xml`; `SUScheduledCheckInterval = 21600`; keep `CFBundleURLName @@BUNDLE_ID@@.join` (L4 drops `.url`); note "build.sh (L4) overwrites SU* values with `Set`".
+22. **T2** LaunchAgent.plist template: also apply `BundleProgram Contents/MacOS/rt`, `ProgramArguments [Contents/MacOS/rt, --daemon]`, Label comment (from L4 T3 L4:624-635). PATH value per §4 #3 ruling.
+23. **T4** stub: uninstall ids → `services.unregister, deck.managed-remove, proxy.remove, path.unlink, shell.remove, extension.uninstall, plugins.uninstall, data (only with --delete-data), app.trash`; row ids `perm.login-items`, `access.team-repo`, `tool.fast-browser`, `tool.path` (kind `info`); `team join --dry-run` no-access → exit 0 `{access:"denied", message}`; `version` → `build: 0` (number); `team status --json` and `setup github status --json` (`{status, handle, owners}`) canned answers; `uninstall` requires `--yes` with `--delete-data`.
+24. **T8**: `PrivilegedInstalling` gains `proxyRemove()` (helper arg `remove`); **T9** NeedBroker: `app-unregister-services` → `services.unregister(plists:)`; `app-privileged op:"proxy-remove"` → `privileged.proxyRemove()`; `GET /version` → `build: Int(CFBundleVersion) ?? 0`.
+25. **T9/T18**: preserve L4's check-bundle source gates (`forInfoDictionaryKey: "MSDaemonLabel"`, `defaultDaemonLabel = "com.mattstack.daemon"`, literal `path == "/flavor/retire"` in TrayServer, socket guard before `AppDelegate()` in `main.swift`).
+26. **T10**: label the build.sh stopgap "deleted by L4 T4's rewrite; L4 T4 must call `scripts/render-launchagents.sh`"; drop the check-bundle edit if L4 T3 has merged (else L4 absorbs); **UpdaterController**: the post-FDA self-relaunch re-execs with current arguments + environment (so `--allow-appcast-override`/`MATTSTACK_APPCAST_URL` survive).
+27. **T13**: create → `["team","create",name] + (useGhRepo ? ["--create-repo", owner] : ["--remote", remoteURL]) + (others ? ["--others"] : []) + ["--json"]`; restore → real `["restore", repo, "--json"]` with stdin `{"ageKey"}` then `["setup","intent","restore", repo, "--json"]` (pending §4 #6; dry-run only if the settings lane ships `--dry-run --json`).
+28. **T14**: owner-once → `["setup", integration, "create-app", "--json"]` with stdin `{"configToken"}` (drop `--config-token-stdin`).
+29. **T17**: uninstall stream → `["uninstall", keepData ? "--keep-data" : "--delete-data", "--yes", "--json"]`; dev-mode → `["settings","dev-mode", isDevBuild ? "prod" : "dev"]`; Team pane uses `rt team status --json` (now defined, §5 #9).
+30. **T18**: add L4 T3's Swift edits (`AppDelegate.swift:331` → `Contents/MacOS/rt`; `DaemonLifecycle.swift:8,17-18`; `Sources-daemon-shim/main.swift:4,26`). 
+31. **Header**: add "rebase onto `origin/main` before each merge; `build.sh`/`check-bundle.sh` are L4's after T10; `Package.swift`, templates, `project.yml`, `Sources/**` are L3's".
+
+**L4 — `plans/2026-08-21-release-pipeline.md`**
+32. **T2**: `.gitignore` — drop `rt-tray/*.xcodeproj/` (L3 T1 adds it); add a `status:"pending"` deps.lock row `mattstack-proxy-install` (`bundlePath`/`exec` `Contents/Helpers/mattstack-proxy-install`, `entitlements:"none"`, `exposeByDefault:false`).
+33. **T3**: drop edits to `rt-tray/Package.swift`, `rt-tray/Info.plist`, `rt-tray/LaunchAgent.plist`, the four Swift files; keep `commands/settings.ts`, `dev-mode-handoff.test.ts`, `scripts/entitlements.plist`, `build.sh` minimal, `check-bundle.sh` rewrite — and in the rewrite: KeepAlive `SuccessfulExit=false` both flavors (replace L4:789-790), add the L3 assertions (`UpdatePolicy.shouldStartUpdater(isDevBuild: isDevBuild` grep in `Sources/Updates/UpdaterController.swift`; `assert_bin_has "silent dev updater" "update check skipped (dev build)"`), add a deck-plist assertion, make the PATH assertion match §4 #3.
+34. **T4** build.sh: replace L4:1093-1104 with `"$SCRIPT_DIR/scripts/render-launchagents.sh" "$([ "$IS_DEV" = true ] && echo dev || echo prod)" "$CONTENTS/Library/LaunchAgents"` (both plists, KeepAlive from the script); Info.plist SU*/`LSMinimumSystemVersion`/`CFBundleURLTypes` writes use `Set` (with create-if-missing); `SU_FEED_URL` unchanged; state "requires L3 T1/T2/T10 merged".
+35. **T5**: drop the Package.swift/Package.resolved edit; keep `check_sparkle`; "requires L3 T10 merged".
+36. **T8**: `scripts/e2e-cleanroom.sh --artifact "<zip>"` (or keep positional and L7 accepts it — pick one; recommended: L7 accepts positional); optionally `sparse-checkout: scripts rt-tray` so the script can run `check-bundle.sh --app`.
+37. **T9**: drop `commands/post-install.ts` and `lib/__tests__/post-install-sweep.test.ts` from Files (bodies move to L1 T24/T27 per §5 #11-12); keep `lib/dev-mode.ts`, `lib/rt-paths.ts` + tests; "Produces: post-install exit 2 on DMG path" moves to L1.
+38. **T10**: drop entirely (L1 T30 owns `commands/update.ts`; L1 T10 owns `cli.ts`).
+39. **T11**: drop the `commands/verify.ts` edit (L1 T7 carries the rows); keep `lib/fzf.ts`, `lib/notifier.ts`; note `e2e/tests/verify.test.ts` unaffected.
+40. **T12**: README "Testing the installer" must describe `rt --post-install` = headless `rt setup apply --non-interactive --team-of-one` (no auto-setup on first `rt` run); regenerate `update.mdx` after L1 T30; `release-workflow.test.ts` — add `yaml` to devDependencies (or parse with Bun's YAML) — state it.
+41. **OQ2/OQ7/OQ8**: close per above (contract example → 2008000; L3 regenerates the project; L3 ships the deck plist, L4 copies it).
+42. **Header**: add "rebase onto `origin/main` before each merge; T4/T5 after L3 T1/T2/T10".
+
+**L7 — `plans/2026-08-21-clean-room-vm.md`**
+43. **T6** `ax.sh`/`drive-setup.sh` id mapping (L3 `AccessibilityIDs.swift`, L3:3714-3779): `setup.window` → `setup.welcome.screen` (and per-screen `setup.<screen>.screen` for waits); `setup.continue` → `setup.<screen>.continue` (`welcome|team|checklist|install|done`); `setup.install` → `setup.checklist.continue`; `setup.finish` → `setup.done.continue`; `setup.card.create|join` → `setup.team.card.create|join`; `setup.field.teamName` → `setup.team.create.name`; `setup.field.inviteCode` → `setup.team.join.code`; `row.<id>` / `.action` / `.status` → `setup.checklist.row.<id>[.action|.status]`; `connect.field.token` → `setup.checklist.connect.field.token`; `connect.submit` → `setup.checklist.connect.submit`; FDA relaunch button → `setup.checklist.relaunch`; install failure → presence of `setup.install.retry` (+ `setup.install.step.<id>.status`); row ids: `perm.loginItems` → `perm.login-items`. Update the L55 table accordingly.
+44. **T5/T8**: launch the prod app with `open --env MATTSTACK_APPCAST_URL=http://127.0.0.1:8765/appcast.xml --args --allow-appcast-override "$APP"` and repeat the env/arg on any driver-initiated relaunch; `trigger-update.sh` asserts `/version.version` (as today) and may also assert `build` equals L4's numeric value.
+45. **T3** `make-appcast.sh`: compute `<new-build>` from `<new-version>` with `major*1000000+minor*1000+patch` (drop the arg); when `scripts/release/make-zip.sh`/`make-dmg.sh` exist, call them for the zip/DMG (keep the loopback `generate_appcast` call local).
+46. **T12** `scripts/e2e-cleanroom.sh`: accept a positional `<zip|dmg|app>` as `--artifact`; `--tag` downloads `mattstack-*.zip` (`gh release download <tag> -R m4ttstack/rt -p 'mattstack-*.zip'`); `ditto -x -k` → `<work>/release/mattstack.app/Contents/MacOS/rt`; delete the tarball and `rt-daemon` branches; default `--post-install-args "--non-interactive --team-of-one --no-launch"`; keep `CI=true`, `rt daemon install`, `rt verify --ci`; README section and `second-user.sh` usage text say zip.
+47. **T13** Files: list `golden/build-golden.sh`, `golden/provision-guest.sh`, `golden/verify-golden.sh`.
+48. **T7** `assert-installed.sh`: add `curl --unix-socket … /services` (daemon + deck status) and `/permissions` (the plan's L24/L322 promise), and `rt settings get mattstack.appPath --scope machine` equals `/Applications/mattstack.app`.
+49. **Header/OQ1**: replace "not yet in the L3 plan" with the L3 AXID list; rebase statement.
+
+**Contract — `specs/2026-08-21-rt-setup-contract.md`** (apply in the appspec branch)
+50. `GET /setup/need/<id>` → state it is always 200 `{state, detail}` (`pending` for unknown ids), POST → 405; rt polls until `done|failed`.
+51. `need.request.type` list: add `app-unregister-services {plists}` and `app-privileged {op: "proxy-install" | "proxy-remove"}`.
+52. `rt uninstall`: list action ids (`services.unregister, deck.managed-remove, proxy.remove, path.unlink, shell.remove, extension.uninstall, plugins.uninstall, data, app.trash`); add `--yes`.
+53. `GET /version` example `"build": 2008000` (numeric CFBundleVersion = `major*1e6+minor*1e3+patch`).
+54. Add `rt team status --json` → `{contract, slug, name, remote, lastPush, members:[{username}]}` and `rt setup github status --json` extra fields `handle`, `owners`.
+55. `rt team create` flags: `--remote <url> | --create-repo <owner> [--others]`; `rt setup intent restore <org>/<repo>`; `rt restore` key on stdin `{"ageKey"}` (pending settings lane).
+56. Stub: `RT_STUB_SCENARIO`, `RT_STUB_PATH` (required), `RT_STUB_BUN`, `RT_STUB_STATE_DIR`.
+57. Team-scope secrets layout paragraph from L1 T13 (`teams/<slug>/.sops.yaml`, `teams/<slug>/mattstack/secrets/<domain>.json`, domains `board`/`rt`).
+58. Apply step `services.register` plists: "daemon always; deck when bundled".
+
+**Spec — `specs/2026-08-20-mattstack-app-installer-design.md`** (after Matt's rulings)
+59. §11 appcast host; §7/§8 plist PATH; §6.3 code length; §5.2 `action.type` list; §12.2(b) UI-scripting driver; §11 tarball sentence.
+
+---
+
+## Rulings needed from Matt (blocking the corresponding amendments)
+
+- **R1** Appcast host: GitHub Release asset (L4) vs GitHub Pages (spec). → affects #21, #34, spec §11.
+- **R2** Agent plist PATH: static + programs prepend (L3) vs hardcoded Helpers dir (L4) vs spec wording; who adds `~/.local/bin`. → #22, #33, #34.
+- **R3** Restore ownership: the app runs the real `rt restore` at screen 2 (recommended) vs L1 apply step. → #17, #27.
+- **R4** `rt update` exit code: 2 + `--json` (contract, L1) vs 1 (L4). Recommended L1. → #14, #38.
+- **R5** Invite code length 77 (contract/L1) vs "~40" (spec §6.3 UX). Recommended keep 77.
diff --git a/docs/superpowers/plans/2026-08-21-mattstack-app-shell.md b/docs/superpowers/plans/2026-08-21-mattstack-app-shell.md
new file mode 100644
index 00000000..4b9c2dfc
--- /dev/null
+++ b/docs/superpowers/plans/2026-08-21-mattstack-app-shell.md
@@ -0,0 +1,6086 @@
+# MAT-383 L3 — mattstack.app shell 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:** Turn `rt-tray` into the mattstack.app installer shell: an xcodegen project beside a still-valid `Package.swift`, a testable `MattstackCore` module (contract models, readiness/install models, permission and service logic, tray.sock routes), the five-screen Setup window, the Settings window, Sparkle, SMAppService for N agents, the admin-prompt proxy step, the `mattstack://join` link, the new tray.sock routes, and a stub `rt` that carries the L1 contract for tests.
+
+**Architecture:** Thin native shell over rt verbs (ruling 5). Everything that can be reasoned about without a window lives in a SwiftPM library target `MattstackCore` (`rt-tray/Sources-core/`, Foundation + Combine only) and is exercised by a CLT-runnable check harness; the AppKit/SwiftUI shell (`rt-tray/Sources/`) binds those models to windows, `NSWorkspace`, `SMAppService`, `UNUserNotificationCenter`, AuthorizationServices and Sparkle. The app never parses a store file and never invents a checklist row: it spawns the bundled `rt` by absolute path with `--json`, renders what comes back, and answers rt's callbacks on `tray.sock`.
+
+**Tech Stack:** Swift 5 language mode on the Swift 6.3.1 toolchain (tools-version 5.9), AppKit lifecycle + SwiftUI views, SwiftPM (CLT-buildable) + xcodegen `project.yml` (Xcode-buildable), Sparkle 2.9.6 via SPM, ServiceManagement (`SMAppService`), UserNotifications, AuthorizationServices, Bun for the stub rt.
+
+**Spec:** `docs/superpowers/specs/2026-08-20-mattstack-app-installer-design.md` (§2 rulings 5/6/7/9/10/12/13/15, V2/V3; §3; §4 all screens; §5.1/5.3; §8; §9; §11; §12) and `docs/superpowers/specs/2026-08-21-rt-setup-contract.md` (the JSON + tray.sock routes this plan renders and serves). Research: `docs/superpowers/specs/research/2026-08-20-mattstack-app/research-onboarding-permissions-ux.md`, `research-sparkle-install-launchd.md`, `research-local-inventory.md`. On conflict the spec wins, then the contract.
+
+**Worktree for execution:** `/Users/matt/Documents/GitHub/repo-tools-l3-wt`, branch `goodwinmattheweric/mat-383-app-shell` off `origin/main`. Main checkout `/Users/matt/Documents/GitHub/repo-tools` is read-only reference. Every path below is relative to the worktree root unless absolute.
+
+**Execution order (cross-plan review, `docs/superpowers/plans/2026-08-21-cross-plan-review.md` §3 — mandatory):** the worktree is cut off `origin/main` only after the settings lane's merge and the appspec docs branch (spec + contract) are on main. **Phase A:** T1–T11 (all inside `rt-tray/`, `Sources-core/`, `Tests/`), with T4's stub ids/shapes as corrected below; these merge before L4 T4/T5 run (L4's `build.sh`/`check-bundle.sh` rewrites consume L3's `Package.swift`, templates and `render-launchagents.sh`). **Phase B:** T12–T18 AFTER T1–T11; T13/T14/T17 carry the argv fixes (§5 #27–#29), T18 carries L4 T3's Swift string edits (§5 #30). **Merge order to main:** L4 phase A → L3 T1–T11 → L1 phase A → L4 T4/T5/T8 → L1 T5, T7–T12, T20–T30 → L3 T12–T19 → L7 → L4 T12 → L1 T31–T32 → MATT gates. Rebase onto `origin/main` before every merge.
+
+## Machine facts (binding on task order and on what "verified" means)
+
+- macOS 26.6.1. **Swift 6.3.1 via Command Line Tools only; Xcode 26 is NOT installed** (Matt installs it later). `xcodebuild` on this machine is the CLT stub and cannot build an app target. `xcodegen` 2.46.0 IS installed at `/opt/homebrew/bin/xcodegen` (it needs no Xcode to *generate*).
+- **Neither `XCTest` nor swift-testing (`import Testing`) is importable under CLT-only** — verified 2026-08-21: `swift test` fails with `no such module 'XCTest'`. Therefore unit tests in this plan are written ONCE as a `MattstackCoreChecks` library (a 60-line harness, Task 1) run by the `mattstack-checks` executable: **`swift run mattstack-checks` is the unit-test gate implementers run under CLT today.** An XCTest target (`MattstackCoreTests`, one test that runs the same checks and reports each failure with `XCTFail`) is also declared so `swift test` / `xcodebuild test` work the moment Xcode is installed — zero duplicated assertions. Tasks marked **needs Xcode — blocked until installed** (xcodebuild archive, XCUITest runs) still have their code written; only the run is deferred.
+- There is no monitor; implementers run `swift build`, `swift run mattstack-checks`, `bun Tests/stub-rt/stub.ts …` and `xcodegen generate` themselves and paste the output into their report.
+- `swift build` must keep working on every commit: `Package.swift` builds the same sources the generated project builds. Sparkle comes through SPM (`from: "2.9.6"`), rpath `@executable_path/../Frameworks`; the framework is copied from `.build/artifacts/sparkle/Sparkle/Sparkle.xcframework/macos-arm64_x86_64/Sparkle.framework` into `Contents/Frameworks` and signed inside-out, never `--deep`. The build-script halves of that belong to L4; this plan adds only the Package.swift dependency, `UpdaterController`, and the **minimum** build.sh stopgap that lets a locally built bundle launch at all (Task 10, clearly fenced).
+- **Live-machine steps are ORCHESTRATOR-ONLY** (installing the built app, launching it, granting real permissions, registering real agents). They are marked as such. **MAT-383 T5/T6 lesson:** no unit check may be able to touch `pkill`, `launchctl`, `tccutil`, `open`, or `osascript`. Every process spawn in the shell goes through the `CommandRunner` seam (Task 7) or `RtRunning` (Task 3); checks use recording fakes; a source-guard check (Task 7) fails the build if a check file names any of those binaries.
+
+## Global Constraints (binding on every task; from the spec)
+
+- **No user or employer data ever lands on mattstack-hosted infrastructure.** The app talks to no relay; only rt verbs do.
+- **rt owns mechanics, the app owns ceremony; every ceremony has a CLI equivalent.** The app never does something `rt setup` cannot. It never invents rows or steps; it renders `rt setup plan/status/apply` and calls the action's verb.
+- **Honesty over magic:** every checklist row reports what was actually checked; nothing is marked ready on a guess. Permission rows show the app's own probe result and say so.
+- **Settings are read and written only through the RT-47 stores via `rt settings`; state only through each app's state.db. The app has no config files of its own beyond UserDefaults for window/UI state** (plus `lastLaunchedVersion`, the login-item opt-out, last Settings pane).
+- **The installer never copies a user's `~/.claude/settings.json` or hooks**; the app never edits `~/.claude.json`.
+- **Pure canonical, no compat:** `rt-tray.app`, `com.rt.daemon`, `~/.rt`, brew paths are swept by rt, never honored by the app.
+- **The app owns ceremony — setup and restore**; Deck does not.
+- Ruling 6 (build tooling): Xcode project generated from a committed `project.yml` (xcodegen); `build.sh` wraps `xcodebuild` (L4); `check-bundle.sh` keeps asserting the bundle contract. Matt installs Xcode 26.
+- Ruling 7 (distribution): the app IS the release; `~/.local/bin/rt` is a symlink into the bundle; **the app re-registers + kickstarts agents when its version changes**; `rt update` asks the app; **arm64-only**.
+- Ruling 9 (services): SMAppService registers rt daemon + deck (one plist each in `Contents/Library/LaunchAgents`, one Login Items switch, FDA inherits); deck supervises board + gitq; plist PATH set explicitly to the bundle's helper dir; the portless proxy is a root LaunchDaemon owned by the privileged step (one admin prompt raised by the app).
+- Ruling 10 (permissions): **Full Disk Access + Login Items required; Notifications optional. No Accessibility / Screen Recording / Automation.**
+- Ruling 13 (identity, frozen): `com.mattstack.app` / `com.mattstack.app.dev`; agents `com.mattstack.daemon` / `.dev`, `com.mattstack.deck`; embedded binary `rt` (L4 renames `rt-daemon` → `rt`); product name `mattstack`; TLD `.mattstack`; `~/.mattstack`; **macOS 14 floor** (`LSMinimumSystemVersion 14.0`).
+- Ruling 15 (UI): five screens + Settings with four panes. **Stock macOS 26 controls, `Form(.grouped)` rows, `.controlSize(.large)`, Return = Continue, ~560 pt fixed window, no close/minimize while setup is incomplete (Quit stays in the menu), custom `enum Step` page model with push transitions, "Step n of 5" indicator.** Status glyphs: `checkmark.circle.fill` green ready · `xmark.circle` red failed · `exclamationmark.triangle` yellow needs-you · `circle.dotted` grey not checked / optional skipped · small `ProgressView` while checking. Buttons that open System Settings end with an ellipsis. **GPL apps (Ice/AltTab/Loop) are design reference only — no code copying; Rectangle/inket (MIT) may be adapted with attribution** (the FDA probe's path list is adapted from inket/FullDiskAccess + MacPaw/PermissionsKit, MIT; say so in the file header).
+- V2: default-exposed tools `rt`, `fast-browser`, `gitq`, `deck` (rt links them; the app never touches PATH).
+- V3: DMG target `/Applications`, fallback `~/Applications`; **the app records its bundle path in the machine store (`mattstack.appPath`) at launch** through `rt settings set mattstack.appPath <json-string> --scope machine`.
+- Dev flavor (`mattstack-dev.app`, `MSDevBuild=true`) keeps working from the same sources: Sparkle disabled, setup window runs against the real `rt` from the checkout (`~/.local/bin/rt` wrapper) or the stub (`RT_STUB_SCENARIO`, DEBUG builds only).
+- Existing process panel / gear menu / daemon polling behaviour stays untouched except for the additive menu items listed in Task 18.
+- Clean-code comments only: a comment states a constraint the code cannot show; no narration, no ticket numbers, no decision history in source.
+- Commits: prefix `MAT-383:`; trailer `Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>`. Do not commit `mattstack.xcodeproj` (generated) or `.build/`.
+- **Cross-lane file ownership (cross-plan review §1):** rebase onto `origin/main` before every merge. `rt-tray/build.sh` and `rt-tray/check-bundle.sh` are **L4's** after Task 10 (L4 T3/T4 rewrite both; L3's Task 10 edits to them are a fenced stopgap that L4's rewrite deletes/absorbs). `rt-tray/Package.swift` (+ `Package.resolved`), the plist templates (`Info.plist`, `LaunchAgent.plist`, `LaunchAgent-deck.plist`), `rt-tray/project.yml`, `rt-tray/scripts/render-launchagents.sh`, `rt-tray/entitlements/*` and `rt-tray/Sources/**` are **L3's** (L4 T3 drops its edits to them; L4 T4/T5 consume them and wait for L3 T1/T2/T10 to merge). The root `.gitignore` line `rt-tray/*.xcodeproj/` is L3's (L4 T2 drops it). Spec/contract files under `docs/superpowers/specs/` are never committed from this branch (they merge to main first).
+
+---
+
+## File structure (what exists after the plan)
+
+```
+rt-tray/
+  Package.swift                       modified: macOS 14, MattstackCore lib, checks lib+exe, XCTest target, Sparkle dep, rpath
+  project.yml                         NEW: xcodegen — targets MattstackCore (framework), mattstack, mattstack-dev, MattstackCoreTests, mattstackUITests
+  Info.plist                          modified template: LSMinimumSystemVersion 14.0, CFBundleURLTypes, SU* keys
+  LaunchAgent.plist                   modified template: PATH env, KeepAlive dict for both flavors (build.sh keeps injecting)
+  LaunchAgent-deck.plist              NEW template: com.mattstack.deck[.dev]
+  scripts/render-launchagents.sh      NEW: templates → Contents/Library/LaunchAgents for a flavor (xcodegen prebuild; L4 build.sh may call it)
+  build.sh                            modified (fenced stopgap only; L4 T4's rewrite deletes it): copy + sign Sparkle.framework, render both agent plists
+  check-bundle.sh                     modified (L4 T3 owns the rewrite; absorbs these assertions): the UpdateChecker dev-silence grep now points at UpdaterController
+  Sources-core/                       NEW library target MattstackCore (Foundation + Combine only)
+    Contract/PlanModels.swift         Plan/PlanGroup/PlanRow/RowAction… (contract v1)
+    Contract/ApplyEvents.swift        ApplyEvent, StepInfo, NeedRequest, NDJSON decoding
+    Contract/OtherResults.swift       ConnectResult, TeamJoinResult, InviteResult, UninstallPlan, VersionInfo, RtUserError
+    Rt/NDJSONSplitter.swift
+    Rt/RtClient.swift                 RtRunning protocol, RtClient (Process), RtResult
+    Rt/RtBinaryLocator.swift          bundled rt / dev wrapper / stub resolution
+    Readiness/ReadinessModel.swift    plan → rows; enablement; recheck policy; timers
+    Readiness/StatusGlyph.swift       RowStatus → SF Symbol + tint name
+    Readiness/RowActionDispatcher.swift
+    Permissions/PermissionSnapshot.swift  states + JSON per contract + row overlay mapping
+    Permissions/FDAProbe.swift        pure probe over an injected open() (inket/MacPaw paths, MIT attribution)
+    Permissions/SystemSettingsLinks.swift
+    Services/CommandRunner.swift      seam for launchctl/tccutil/helpers (+ RecordingCommandRunner for checks)
+    Services/ServicePlists.swift      scan Contents/Library/LaunchAgents, labels, kickstart args
+    Services/VersionChangeDetector.swift
+    Services/ServiceModels.swift      ServiceStatusEntry, ServiceRegisterResult, ServicesProviding…
+    Needs/NeedBroker.swift            idempotent per-id execution of `need` events
+    Routes/TrayRoutes.swift           the new tray.sock routes as a pure router
+    Install/InstallRunModel.swift     apply stream → step list, logs, need handling, retry-from
+    Setup/SetupFlowModel.swift        enum SetupStep + navigation
+    Setup/TeamChoiceModel.swift       create/join/restore state + rt calls + failure copy
+    Launch/LaunchGuard.swift          translocation/DMG guard, first-run detector, join-link parser, appPath args
+    Settings/RemoteMasker.swift
+    Updates/UpdatePolicy.swift
+  Sources/                            existing executable target rt-tray (app shell), new files:
+    Rt/RtClientFactory.swift
+    Permissions/PermissionsService.swift
+    Services/ServicesRegistrar.swift
+    Services/PrivilegedInstaller.swift
+    Updates/UpdaterController.swift   (UpdateChecker.swift DELETED)
+    Setup/SetupWindowController.swift
+    Setup/SetupView.swift
+    Setup/Screens/WelcomeScreen.swift TeamScreen.swift ChecklistScreen.swift InstallScreen.swift DoneScreen.swift
+    Setup/Components/StatusBadge.swift RowView.swift ConnectSheet.swift StepsSheet.swift LogSheet.swift
+    Settings/SettingsWindowController.swift SettingsView.swift GeneralPane.swift PermissionsPane.swift TeamPane.swift UninstallPane.swift
+    AppDelegate.swift TrayServer.swift main.swift TrayState.swift  (modified)
+  Tests/
+    MattstackCoreChecks/              NEW library: Harness.swift, AllChecks.swift, one *Checks.swift per Core module
+    mattstack-checks/main.swift       NEW executable: runs the checks, exit 1 on failure  ← CLT gate
+    MattstackCoreTests/CoreChecksXCTest.swift  NEW XCTest bridge (needs Xcode to run)
+    stub-rt/stub.ts                   NEW Bun stub rt (scenarios from the contract)
+    mattstackUITests/SetupFlowUITests.swift    NEW XCUITest (needs Xcode to run)
+```
+
+Naming rules used throughout: Core types are `public`; the app target `@testable`-free imports `MattstackCore`. Every process spawn goes through `RtRunning` (rt) or `CommandRunner` (everything else). Checks never construct `SystemCommandRunner` or a real `RtClient` pointed at anything but `/bin/sh` scripts written into a temp dir.
+
+---
+
+### Task 0: Worktree + branch (orchestrator or first implementer)
+
+- [ ] **Step 1: Create the worktree off origin/main**
+
+```bash
+cd /Users/matt/Documents/GitHub/repo-tools
+git fetch origin
+git worktree add -b goodwinmattheweric/mat-383-app-shell /Users/matt/Documents/GitHub/repo-tools-l3-wt origin/main
+cd /Users/matt/Documents/GitHub/repo-tools-l3-wt/rt-tray
+swift build 2>&1 | tail -3
+```
+Expected: `Build complete!` (baseline builds before any change).
+
+- [ ] **Step 2:** Dropped — spec/contract are merged to main first (cross-plan review §1 row 27); the worktree is cut after that merge, so the files are already present.
+
+---
+
+### Task 1: Package.swift restructure — MattstackCore, checks harness, XCTest bridge, macOS 14 floor
+
+**Files:**
+- Modify: `rt-tray/Package.swift`
+- Create: `rt-tray/Sources-core/Contract/PlanModels.swift`
+- Create: `rt-tray/Tests/MattstackCoreChecks/Harness.swift`, `rt-tray/Tests/MattstackCoreChecks/AllChecks.swift`, `rt-tray/Tests/MattstackCoreChecks/PlanModelsChecks.swift`
+- Create: `rt-tray/Tests/mattstack-checks/main.swift`
+- Create: `rt-tray/Tests/MattstackCoreTests/CoreChecksXCTest.swift`
+- Modify: `.gitignore` (root) — add `rt-tray/*.xcodeproj/` and `rt-tray/Generated/`
+
+**Interfaces:**
+- Produces: module `MattstackCore`; `Plan`, `PlanGroup`, `PlanRow`, `RowAction`, `RowStatus`, `RowKind`, `RecheckPolicy`, `ActionType`, `ActionField`, `ActionAlternative`, `TeamInfo`, `TeamMode` (all `public`, `Codable`, `Equatable`); the check harness API `Check`, `CheckContext.expect/expectEqual/fail`, `runAllChecks() async -> CheckReport`; the `allChecks` registry every later task appends to.
+
+- [ ] **Step 1: Write the harness**
+
+`rt-tray/Tests/MattstackCoreChecks/Harness.swift`:
+```swift
+import Foundation
+
+public struct CheckFailure: Sendable {
+    public let check: String
+    public let message: String
+    public let file: String
+    public let line: Int
+}
+
+public struct Check: Sendable {
+    public let name: String
+    public let body: @Sendable (CheckContext) async throws -> Void
+    public init(_ name: String, _ body: @escaping @Sendable (CheckContext) async throws -> Void) {
+        self.name = name
+        self.body = body
+    }
+}
+
+public final class CheckContext: @unchecked Sendable {
+    public let name: String
+    public private(set) var failures: [CheckFailure] = []
+    private let lock = NSLock()
+    init(name: String) { self.name = name }
+
+    public func expect(_ condition: Bool, _ message: @autoclosure () -> String = "expected true",
+                       file: String = #filePath, line: Int = #line) {
+        guard !condition else { return }
+        record(message(), file, line)
+    }
+    public func expectEqual<T: Equatable>(_ actual: T, _ expected: T, _ message: @autoclosure () -> String = "",
+                                          file: String = #filePath, line: Int = #line) {
+        guard actual != expected else { return }
+        record("\(message()) expected \(expected) got \(actual)", file, line)
+    }
+    public func fail(_ message: String, file: String = #filePath, line: Int = #line) { record(message, file, line) }
+
+    private func record(_ message: String, _ file: String, _ line: Int) {
+        lock.lock(); defer { lock.unlock() }
+        failures.append(CheckFailure(check: name, message: message, file: file, line: line))
+    }
+}
+
+public struct CheckReport: Sendable {
+    public let passed: Int
+    public let failures: [CheckFailure]
+    public var ok: Bool { failures.isEmpty }
+}
+
+public func runAllChecks(filter: String? = nil) async -> CheckReport {
+    var passed = 0
+    var failures: [CheckFailure] = []
+    for check in allChecks where filter == nil || check.name.contains(filter!) {
+        let ctx = CheckContext(name: check.name)
+        do { try await check.body(ctx) } catch {
+            ctx.fail("threw \(error)")
+        }
+        if ctx.failures.isEmpty { passed += 1 } else { failures.append(contentsOf: ctx.failures) }
+    }
+    return CheckReport(passed: passed, failures: failures)
+}
+```
+
+`rt-tray/Tests/MattstackCoreChecks/AllChecks.swift`:
+```swift
+/// Explicit registry — no reflection. Each *Checks.swift file exposes one
+/// array; append it here when you add a file.
+let allChecks: [Check] = planModelsChecks
+```
+
+`rt-tray/Tests/mattstack-checks/main.swift`:
+```swift
+import Foundation
+import MattstackCoreChecks
+
+let filter = CommandLine.arguments.dropFirst().first
+let report = await runAllChecks(filter: filter)
+for f in report.failures {
+    FileHandle.standardError.write(Data("FAIL \(f.check): \(f.message) (\(f.file):\(f.line))\n".utf8))
+}
+print("checks: \(report.passed) passed, \(report.failures.count) failed")
+exit(report.ok ? 0 : 1)
+```
+
+`rt-tray/Tests/MattstackCoreTests/CoreChecksXCTest.swift` (runs only once Xcode exists; `swift build` never compiles test targets):
+```swift
+import XCTest
+import MattstackCoreChecks
+
+final class CoreChecksXCTest: XCTestCase {
+    func testAllCoreChecksPass() async {
+        let report = await runAllChecks()
+        for f in report.failures {
+            XCTFail("\(f.check) [\(f.file):\(f.line)]: \(f.message)")
+        }
+        XCTAssertGreaterThan(report.passed, 0)
+    }
+}
+```
+
+- [ ] **Step 2: Write the first failing check — contract plan decoding**
+
+`rt-tray/Tests/MattstackCoreChecks/PlanModelsChecks.swift`:
+```swift
+import Foundation
+import MattstackCore
+
+let samplePlanJSON = """
+{ "contract": 1, "at": "2026-08-21T04:00:00Z",
+  "team": { "slug": "assured", "name": "Assured", "mode": "join" },
+  "groups": [
+    { "id": "mac", "title": "Your Mac", "rows": [
+      { "id": "perm.fda", "kind": "permission", "title": "Full Disk Access",
+        "why": "Reads your repositories' git state so the daemon can show branch and MR status.",
+        "required": true, "optionalNote": null, "status": "needs-you", "detail": "Not granted",
+        "action": { "type": "open-settings", "label": "Open Full Disk Access Settings…", "target": "fda" },
+        "recheck": "on-activate" },
+      { "id": "tool.clt", "kind": "tool", "title": "Apple command line tools", "why": "git and python3.",
+        "required": true, "optionalNote": null, "status": "ready", "detail": "git 2.50.1", "action": null, "recheck": "on-change" } ] },
+    { "id": "accounts", "title": "Accounts", "rows": [
+      { "id": "account.gitlab", "kind": "account", "title": "GitLab", "why": "MRs live on gitlab.assured.com.",
+        "required": true, "optionalNote": null, "status": "missing", "detail": null,
+        "action": { "type": "connect", "label": "Connect", "integration": "gitlab",
+                    "fields": [ { "name": "token", "label": "Personal access token", "secret": true, "hint": "scopes: read_api, read_user" } ],
+                    "alternatives": [ { "id": "use-gh", "label": "Use gh login" } ] },
+        "recheck": "on-change" },
+      { "id": "tool.chrome", "kind": "tool", "title": "Google Chrome", "why": "Evidence capture.",
+        "required": false, "optionalNote": "Works without this.", "status": "skipped", "detail": null,
+        "action": { "type": "future-thing", "label": "?" }, "recheck": "manual" } ] } ],
+  "canInstall": false, "requiredMissing": ["perm.fda", "account.gitlab"] }
+"""
+
+let planModelsChecks: [Check] = [
+    Check("Plan decodes the contract sample") { c in
+        let plan = try JSONDecoder().decode(Plan.self, from: Data(samplePlanJSON.utf8))
+        c.expectEqual(plan.contract, 1)
+        c.expectEqual(plan.team.mode, .join)
+        c.expectEqual(plan.groups.count, 2)
+        c.expectEqual(plan.groups[0].rows[0].status, .needsYou)
+        c.expectEqual(plan.groups[0].rows[0].action?.type, .openSettings)
+        c.expectEqual(plan.groups[0].rows[0].action?.target, "fda")
+        c.expectEqual(plan.groups[0].rows[0].recheck, .onActivate)
+        c.expectEqual(plan.groups[1].rows[0].action?.fields?.first?.secret, true)
+        c.expectEqual(plan.groups[1].rows[0].action?.alternatives?.first?.id, "use-gh")
+        c.expectEqual(plan.requiredMissing, ["perm.fda", "account.gitlab"])
+        c.expectEqual(plan.canInstall, false)
+    },
+    Check("unknown action type and status degrade instead of failing the whole plan") { c in
+        let plan = try JSONDecoder().decode(Plan.self, from: Data(samplePlanJSON.utf8))
+        let chrome = plan.groups[1].rows[1]
+        c.expectEqual(chrome.action?.type, .unknown)
+        var lenient = samplePlanJSON
+        lenient = lenient.replacingOccurrences(of: "\"status\": \"skipped\"", with: "\"status\": \"brand-new\"")
+        let plan2 = try JSONDecoder().decode(Plan.self, from: Data(lenient.utf8))
+        c.expectEqual(plan2.groups[1].rows[1].status, .error)
+    },
+    Check("Plan round-trips through the encoder") { c in
+        let plan = try JSONDecoder().decode(Plan.self, from: Data(samplePlanJSON.utf8))
+        let data = try JSONEncoder().encode(plan)
+        let again = try JSONDecoder().decode(Plan.self, from: data)
+        c.expectEqual(again, plan)
+    },
+]
+```
+
+- [ ] **Step 3: Rewrite Package.swift**
+
+```swift
+// swift-tools-version:5.9
+import PackageDescription
+
+let package = Package(
+    name: "rt-tray",
+    platforms: [
+        .macOS(.v14)
+    ],
+    targets: [
+        .target(
+            name: "MattstackCore",
+            path: "Sources-core"
+        ),
+        .executableTarget(
+            name: "rt-tray",
+            dependencies: ["MattstackCore"],
+            path: "Sources",
+            swiftSettings: [
+                .define("DEBUG", .when(configuration: .debug)),
+            ],
+            linkerSettings: [
+                .linkedFramework("AppKit"),
+                .linkedFramework("UserNotifications"),
+                .linkedFramework("ServiceManagement"),
+            ]
+        ),
+        .executableTarget(
+            name: "rt-daemon-shim",
+            path: "Sources-daemon-shim"
+        ),
+        .target(
+            name: "MattstackCoreChecks",
+            dependencies: ["MattstackCore"],
+            path: "Tests/MattstackCoreChecks"
+        ),
+        .executableTarget(
+            name: "mattstack-checks",
+            dependencies: ["MattstackCoreChecks"],
+            path: "Tests/mattstack-checks"
+        ),
+        .testTarget(
+            name: "MattstackCoreTests",
+            dependencies: ["MattstackCoreChecks"],
+            path: "Tests/MattstackCoreTests"
+        ),
+    ]
+)
+```
+(Sparkle and the rpath linker flags arrive in Task 10, so Task 1's build needs no network.)
+
+- [ ] **Step 4: Run the checks to verify they fail to compile (no `Plan` yet)**
+
+Run: `cd rt-tray && swift run mattstack-checks 2>&1 | tail -5`
+Expected: `error: cannot find type 'Plan' in scope`.
+
+- [ ] **Step 5: Write the contract models**
+
+`rt-tray/Sources-core/Contract/PlanModels.swift`:
+```swift
+import Foundation
+
+public enum TeamMode: String, Codable, Equatable, Sendable { case join, create, restore, none }
+
+public struct TeamInfo: Codable, Equatable, Sendable {
+    public var slug: String?
+    public var name: String?
+    public var mode: TeamMode
+    public init(slug: String? = nil, name: String? = nil, mode: TeamMode) {
+        self.slug = slug; self.name = name; self.mode = mode
+    }
+}
+
+public enum RowKind: String, Codable, Equatable, Sendable { case permission, tool, account, access, info }
+
+/// Unknown values decode as `.error` so one new status from a newer rt
+/// cannot blank the whole checklist.
+public enum RowStatus: String, Codable, Equatable, Sendable {
+    case ready, missing, invalid, checking, skipped, error
+    case needsYou = "needs-you"
+
+    public init(from decoder: Decoder) throws {
+        let raw = try decoder.singleValueContainer().decode(String.self)
+        self = RowStatus(rawValue: raw) ?? .error
+    }
+}
+
+public enum RecheckPolicy: String, Codable, Equatable, Sendable {
+    case onActivate = "on-activate"
+    case onChange = "on-change"
+    case manual
+    public init(from decoder: Decoder) throws {
+        let raw = try decoder.singleValueContainer().decode(String.self)
+        self = RecheckPolicy(rawValue: raw) ?? .manual
+    }
+}
+
+public enum ActionType: String, Codable, Equatable, Sendable {
+    case openSettings = "open-settings"
+    case requestPermission = "request-permission"
+    case connect, oauth, install, steps, run
+    case ownerOnce = "owner-once"
+    case linkBundled = "link-bundled"
+    case openURL = "open-url"
+    case unknown
+    public init(from decoder: Decoder) throws {
+        let raw = try decoder.singleValueContainer().decode(String.self)
+        self = ActionType(rawValue: raw) ?? .unknown
+    }
+}
+
+public struct ActionField: Codable, Equatable, Sendable {
+    public var name: String
+    public var label: String
+    public var secret: Bool
+    public var hint: String?
+    public init(name: String, label: String, secret: Bool, hint: String? = nil) {
+        self.name = name; self.label = label; self.secret = secret; self.hint = hint
+    }
+}
+
+public struct ActionAlternative: Codable, Equatable, Sendable {
+    public var id: String
+    public var label: String
+    public init(id: String, label: String) { self.id = id; self.label = label }
+}
+
+/// One shape for every contract action; which optionals are present is
+/// discriminated by `type`. Kept flat so rt can add a field without a
+/// decoder change here.
+public struct RowAction: Codable, Equatable, Sendable {
+    public var type: ActionType
+    public var label: String
+    public var target: String?
+    public var which: String?
+    public var integration: String?
+    public var fields: [ActionField]?
+    public var alternatives: [ActionAlternative]?
+    public var verb: [String]?
+    public var tool: String?
+    public var via: String?
+    public var steps: [String]?
+    public var url: String?
+    public init(type: ActionType, label: String, target: String? = nil, which: String? = nil,
+                integration: String? = nil, fields: [ActionField]? = nil,
+                alternatives: [ActionAlternative]? = nil, verb: [String]? = nil, tool: String? = nil,
+                via: String? = nil, steps: [String]? = nil, url: String? = nil) {
+        self.type = type; self.label = label; self.target = target; self.which = which
+        self.integration = integration; self.fields = fields; self.alternatives = alternatives
+        self.verb = verb; self.tool = tool; self.via = via; self.steps = steps; self.url = url
+    }
+}
+
+public struct PlanRow: Codable, Equatable, Identifiable, Sendable {
+    public var id: String
+    public var kind: RowKind
+    public var title: String
+    public var why: String
+    public var required: Bool
+    public var optionalNote: String?
+    public var status: RowStatus
+    public var detail: String?
+    public var action: RowAction?
+    public var recheck: RecheckPolicy
+    public init(id: String, kind: RowKind, title: String, why: String, required: Bool,
+                optionalNote: String? = nil, status: RowStatus, detail: String? = nil,
+                action: RowAction? = nil, recheck: RecheckPolicy) {
+        self.id = id; self.kind = kind; self.title = title; self.why = why; self.required = required
+        self.optionalNote = optionalNote; self.status = status; self.detail = detail
+        self.action = action; self.recheck = recheck
+    }
+}
+
+public struct PlanGroup: Codable, Equatable, Identifiable, Sendable {
+    public var id: String
+    public var title: String
+    public var rows: [PlanRow]
+    public init(id: String, title: String, rows: [PlanRow]) { self.id = id; self.title = title; self.rows = rows }
+}
+
+public struct Plan: Codable, Equatable, Sendable {
+    public var contract: Int
+    public var at: String
+    public var team: TeamInfo
+    public var groups: [PlanGroup]
+    public var canInstall: Bool
+    public var requiredMissing: [String]
+    public init(contract: Int = 1, at: String, team: TeamInfo, groups: [PlanGroup],
+                canInstall: Bool, requiredMissing: [String]) {
+        self.contract = contract; self.at = at; self.team = team; self.groups = groups
+        self.canInstall = canInstall; self.requiredMissing = requiredMissing
+    }
+}
+```
+
+- [ ] **Step 6: Run the checks**
+
+Run: `cd rt-tray && swift run mattstack-checks 2>&1 | tail -3`
+Expected: `checks: 3 passed, 0 failed`, exit 0. Also run `swift build 2>&1 | tail -1` → `Build complete!` (app target still compiles with the dependency added).
+
+- [ ] **Step 7: .gitignore + commit**
+
+Append to root `.gitignore`:
+```
+rt-tray/*.xcodeproj/
+rt-tray/Generated/
+rt-tray/Tests/stub-rt/.state/
+```
+```bash
+git add .gitignore rt-tray/Package.swift rt-tray/Sources-core rt-tray/Tests
+git commit -m "MAT-383: MattstackCore library, CLT-runnable check harness, contract plan models
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 2: xcodegen `project.yml`, Info.plist keys, LaunchAgent templates, render script
+
+**Files:**
+- Create: `rt-tray/project.yml`
+- Modify: `rt-tray/Info.plist` (template used by build.sh; same keys as project.yml's `info.properties`)
+- Modify: `rt-tray/LaunchAgent.plist`
+- Create: `rt-tray/LaunchAgent-deck.plist`
+- Create: `rt-tray/scripts/render-launchagents.sh`
+- Create: `rt-tray/entitlements/mattstack.entitlements`
+
+**Interfaces:**
+- Produces: two app targets `mattstack` / `mattstack-dev` with Info.plist keys `MSDaemonLabel`, `MSDevBuild`, `CFBundleURLTypes` (`mattstack`), `LSMinimumSystemVersion 14.0`, `SUFeedURL`, `SUPublicEDKey`, `SUEnableAutomaticChecks`, `SUAutomaticallyUpdate`, `SUVerifyUpdateBeforeExtraction`, `SUScheduledCheckInterval`, `NSAppTransportSecurity.NSAllowsLocalNetworking`; LaunchAgent files `com.mattstack.daemon[.dev].plist` + `com.mattstack.deck[.dev].plist` under `Contents/Library/LaunchAgents` (ServicesRegistrar enumerates that directory, Task 7).
+
+- [ ] **Step 1: Write the render script (the one place that knows a flavor's labels for the agents)**
+
+`rt-tray/scripts/render-launchagents.sh`:
+```bash
+#!/bin/bash
+# Render the LaunchAgent templates for one flavor into a directory.
+# Usage: render-launchagents.sh prod|dev <out-dir>
+set -euo pipefail
+FLAVOR="$1"; OUT="$2"
+HERE="$(cd "$(dirname "$0")/.." && pwd)"
+case "$FLAVOR" in
+    prod) BUNDLE_ID="com.mattstack.app";     DAEMON_LABEL="com.mattstack.daemon";     DECK_LABEL="com.mattstack.deck" ;;
+    dev)  BUNDLE_ID="com.mattstack.app.dev"; DAEMON_LABEL="com.mattstack.daemon.dev"; DECK_LABEL="com.mattstack.deck.dev" ;;
+    *) echo "flavor must be prod|dev" >&2; exit 2 ;;
+esac
+mkdir -p "$OUT"
+render() { # template label out
+    sed -e "s/@@DAEMON_LABEL@@/$DAEMON_LABEL/g" -e "s/@@DECK_LABEL@@/$DECK_LABEL/g" \
+        -e "s/@@BUNDLE_ID@@/$BUNDLE_ID/g" "$1" > "$2"
+    /usr/libexec/PlistBuddy -c "Add :KeepAlive dict" "$2"
+    /usr/libexec/PlistBuddy -c "Add :KeepAlive:SuccessfulExit bool false" "$2"
+    plutil -lint "$2" >/dev/null
+}
+render "$HERE/LaunchAgent.plist"      "$OUT/$DAEMON_LABEL.plist"
+render "$HERE/LaunchAgent-deck.plist" "$OUT/$DECK_LABEL.plist"
+echo "rendered $DAEMON_LABEL.plist $DECK_LABEL.plist → $OUT"
+```
+`chmod +x rt-tray/scripts/render-launchagents.sh`. (KeepAlive `{SuccessfulExit:false}` for both flavors per spec §8; build.sh's prod `KeepAlive true` branch is L4's to retire — leave build.sh alone here.)
+
+- [ ] **Step 2: Update the daemon template and add the deck template**
+
+`rt-tray/LaunchAgent.plist` — (a) rename the program (L4 renames the embedded binary `rt-daemon` → `rt`): `BundleProgram` → `Contents/MacOS/rt`, `ProgramArguments` → `[Contents/MacOS/rt, --daemon]`, and the Label comment → "Label: com.mattstack.daemon (prod) / com.mattstack.daemon.dev (dev)"; (b) replace the KeepAlive comment with "KeepAlive is injected by `scripts/render-launchagents.sh` as `{SuccessfulExit:false}` for both flavors"; (c) add, after `ThrottleInterval`, an explicit PATH (spec §8: "explicit EnvironmentVariables.PATH … nothing is captured from the user's shell"); keep everything else as is:
+```xml
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>/usr/bin:/bin:/usr/sbin:/sbin</string>
+    </dict>
+```
+**Ruling R2 (cross-plan review):** the plist PATH is this STATIC system list — never a hardcoded `/Applications/…` path and never `~/.local/bin` (launchd does not expand variables inside `EnvironmentVariables`, and SMAppService reads the plist verbatim from the bundle, so neither the bundle's absolute `Contents/Helpers` nor `$HOME` can be written here at build time). rt and deck prepend `<bundleRoot>/Contents/Helpers` (derived at runtime from their own `execPath`) and `$HOME/.local/bin` (HOME from the environment) to their `PATH` at process start; L4's `check-bundle.sh` asserts the static value.
+
+`rt-tray/LaunchAgent-deck.plist`:
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>@@DECK_LABEL@@</string>
+    <key>BundleProgram</key>
+    <string>Contents/Helpers/deck</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>Contents/Helpers/deck</string>
+        <string>serve</string>
+    </array>
+    <key>AssociatedBundleIdentifiers</key>
+    <array>
+        <string>@@BUNDLE_ID@@</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>ThrottleInterval</key>
+    <integer>10</integer>
+    <key>ExitTimeOut</key>
+    <integer>30</integer>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>/usr/bin:/bin:/usr/sbin:/sbin</string>
+    </dict>
+    <key>LimitLoadToSessionType</key>
+    <string>Aqua</string>
+    <key>ProcessType</key>
+    <string>Interactive</string>
+</dict>
+</plist>
+```
+(Dev flavor's deck binary location — `~/.mattstack/deck/bin/deck` per DECK-13 — is an L4/L5 bundling decision; the template names the bundled path, and an absent helper simply registers as `.notFound`, which the Background services row reports honestly.)
+
+- [ ] **Step 3: Update the Info.plist template**
+
+In `rt-tray/Info.plist` change `LSMinimumSystemVersion` to `14.0` and add before `</dict>`:
+```xml
+    <key>CFBundleURLTypes</key>
+    <array>
+        <dict>
+            <key>CFBundleURLName</key>
+            <string>@@BUNDLE_ID@@.join</string>
+            <key>CFBundleURLSchemes</key>
+            <array>
+                <string>mattstack</string>
+            </array>
+        </dict>
+    </array>
+    <key>SUFeedURL</key>
+    <string>https://github.com/m4ttstack/rt/releases/latest/download/appcast.xml</string>
+    <key>SUPublicEDKey</key>
+    <string>REPLACE_WITH_RELEASE_PUBLIC_ED_KEY</string>
+    <key>SUEnableAutomaticChecks</key>
+    <true/>
+    <key>SUAutomaticallyUpdate</key>
+    <true/>
+    <key>SUVerifyUpdateBeforeExtraction</key>
+    <true/>
+    <key>SUScheduledCheckInterval</key>
+    <integer>21600</integer>
+    <key>NSAppTransportSecurity</key>
+    <dict>
+        <key>NSAllowsLocalNetworking</key>
+        <true/>
+    </dict>
+```
+(`NSAllowsLocalNetworking` lets the clean-room VM (L7) serve a loopback appcast via `MATTSTACK_APPCAST_URL` — Task 10. `SUPublicEDKey` is a placeholder by design — L4's release job owns the real key; `UpdatePolicy` in Task 10 refuses to start Sparkle while the placeholder is present, so a local build never phones a feed it cannot verify. The appcast is a GitHub Release asset (ruling R1), hence the `releases/latest/download` URL and the 21600 s interval — both are L4's canon and `check-bundle.sh` asserts them. `CFBundleURLName` stays `@@BUNDLE_ID@@.join` (L4 drops its `.url` spelling). **L4's `build.sh` overwrites the `SU*` values with PlistBuddy `Set` (create-if-missing; dev flavor `SUEnableAutomaticChecks false`) — it never `Add`s a key this template already declares.**)
+
+- [ ] **Step 4: Entitlements file** `rt-tray/entitlements/mattstack.entitlements`:
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>com.apple.security.app-sandbox</key>
+    <false/>
+</dict>
+</plist>
+```
+
+- [ ] **Step 5: Write project.yml**
+
+`rt-tray/project.yml`:
+```yaml
+name: mattstack
+options:
+  bundleIdPrefix: com.mattstack
+  deploymentTarget:
+    macOS: "14.0"
+  createIntermediateGroups: true
+  generateEmptyDirectories: true
+  xcodeVersion: "26.0"
+settings:
+  base:
+    SWIFT_VERSION: "5.0"
+    MACOSX_DEPLOYMENT_TARGET: "14.0"
+    ARCHS: arm64
+    ONLY_ACTIVE_ARCH: YES
+    ENABLE_HARDENED_RUNTIME: YES
+    CODE_SIGN_STYLE: Manual
+    DEVELOPMENT_TEAM: 5BF66B3X4V
+    MARKETING_VERSION: "2.8.0"
+    CURRENT_PROJECT_VERSION: 1
+    LD_RUNPATH_SEARCH_PATHS: "@executable_path/../Frameworks"
+  configs:
+    Debug:
+      SWIFT_ACTIVE_COMPILATION_CONDITIONS: DEBUG
+packages:
+  Sparkle:
+    url: https://github.com/sparkle-project/Sparkle
+    from: "2.9.6"
+
+targetTemplates:
+  MattstackApp:
+    type: application
+    platform: macOS
+    sources:
+      - path: Sources
+        excludes: ["**/.DS_Store"]
+    dependencies:
+      - target: MattstackCore
+        embed: true
+      - package: Sparkle
+    preBuildScripts:
+      - name: Render LaunchAgents
+        script: |
+          "${SRCROOT}/scripts/render-launchagents.sh" "${MS_FLAVOR}" "${SRCROOT}/Generated/LaunchAgents-${MS_FLAVOR}"
+        outputFiles:
+          - "${SRCROOT}/Generated/LaunchAgents-${MS_FLAVOR}/${MS_DAEMON_LABEL}.plist"
+          - "${SRCROOT}/Generated/LaunchAgents-${MS_FLAVOR}/${MS_DECK_LABEL}.plist"
+    postCompileScripts:
+      - name: Copy LaunchAgents into bundle
+        script: |
+          DEST="${BUILT_PRODUCTS_DIR}/${CONTENTS_FOLDER_PATH}/Library/LaunchAgents"
+          mkdir -p "$DEST"
+          cp "${SRCROOT}/Generated/LaunchAgents-${MS_FLAVOR}/"*.plist "$DEST/"
+    settings:
+      base:
+        CODE_SIGN_ENTITLEMENTS: entitlements/mattstack.entitlements
+        INFOPLIST_KEY_LSUIElement: YES
+    info:
+      properties:
+        CFBundleIconFile: AppIcon
+        CFBundlePackageType: APPL
+        LSUIElement: true
+        LSMinimumSystemVersion: "14.0"
+        NSUserNotificationAlertStyle: alert
+        CFBundleURLTypes:
+          - CFBundleURLName: "$(PRODUCT_BUNDLE_IDENTIFIER).join"
+            CFBundleURLSchemes: [mattstack]
+        SUFeedURL: https://github.com/m4ttstack/rt/releases/latest/download/appcast.xml
+        SUPublicEDKey: REPLACE_WITH_RELEASE_PUBLIC_ED_KEY
+        SUEnableAutomaticChecks: true
+        SUAutomaticallyUpdate: true
+        SUVerifyUpdateBeforeExtraction: true
+        SUScheduledCheckInterval: 21600
+        NSAppTransportSecurity:
+          NSAllowsLocalNetworking: true
+
+targets:
+  MattstackCore:
+    type: framework
+    platform: macOS
+    sources: [Sources-core]
+    settings:
+      base:
+        PRODUCT_BUNDLE_IDENTIFIER: com.mattstack.core
+        SKIP_INSTALL: YES
+
+  mattstack:
+    templates: [MattstackApp]
+    settings:
+      base:
+        PRODUCT_NAME: mattstack
+        PRODUCT_BUNDLE_IDENTIFIER: com.mattstack.app
+        MS_FLAVOR: prod
+        MS_DAEMON_LABEL: com.mattstack.daemon
+        MS_DECK_LABEL: com.mattstack.deck
+    info:
+      path: Generated/mattstack-Info.plist
+      properties:
+        CFBundleName: mattstack
+        CFBundleDisplayName: mattstack
+        CFBundleExecutable: mattstack
+        MSDaemonLabel: com.mattstack.daemon
+        MSDevBuild: false
+
+  mattstack-dev:
+    templates: [MattstackApp]
+    settings:
+      base:
+        PRODUCT_NAME: mattstack-dev
+        PRODUCT_BUNDLE_IDENTIFIER: com.mattstack.app.dev
+        MS_FLAVOR: dev
+        MS_DAEMON_LABEL: com.mattstack.daemon.dev
+        MS_DECK_LABEL: com.mattstack.deck.dev
+    info:
+      path: Generated/mattstack-dev-Info.plist
+      properties:
+        CFBundleName: mattstack-dev
+        CFBundleDisplayName: mattstack-dev
+        CFBundleExecutable: mattstack-dev
+        MSDaemonLabel: com.mattstack.daemon.dev
+        MSDevBuild: true
+
+  MattstackCoreChecks:
+    type: framework
+    platform: macOS
+    sources: [Tests/MattstackCoreChecks]
+    dependencies:
+      - target: MattstackCore
+    settings:
+      base:
+        PRODUCT_BUNDLE_IDENTIFIER: com.mattstack.core.checks
+
+  MattstackCoreTests:
+    type: bundle.unit-test
+    platform: macOS
+    sources: [Tests/MattstackCoreTests]
+    dependencies:
+      - target: MattstackCoreChecks
+      - target: MattstackCore
+
+  mattstackUITests:
+    type: bundle.ui-testing
+    platform: macOS
+    sources: [Tests/mattstackUITests]
+    dependencies:
+      - target: mattstack
+    settings:
+      base:
+        TEST_TARGET_NAME: mattstack
+
+schemes:
+  mattstack:
+    build:
+      targets:
+        mattstack: all
+    run:
+      config: Debug
+    test:
+      config: Debug
+      targets: [MattstackCoreTests, mattstackUITests]
+    archive:
+      config: Release
+  mattstack-dev:
+    build:
+      targets:
+        mattstack-dev: all
+    run:
+      config: Debug
+    test:
+      config: Debug
+      targets: [MattstackCoreTests]
+```
+(The info `properties` on the template merge with the per-target ones in xcodegen; `Generated/` is gitignored. The `AppIcon.icns` copy into Resources is an L4 build phase — no asset catalog, so nothing here needs Icon Composer. The `Contents/MacOS/rt` + `Contents/Helpers/*` copy phases are L4.)
+
+- [ ] **Step 6: Verify generation (no Xcode needed) and render the agents**
+
+```bash
+cd rt-tray
+./scripts/render-launchagents.sh prod /tmp/la-prod && plutil -p /tmp/la-prod/com.mattstack.daemon.plist | grep -E "Label|KeepAlive|SuccessfulExit|PATH"
+./scripts/render-launchagents.sh dev  /tmp/la-dev  && ls /tmp/la-dev
+xcodegen generate --spec project.yml 2>&1 | tail -3
+plutil -lint mattstack.xcodeproj/project.pbxproj
+grep -c "MSDaemonLabel" mattstack.xcodeproj/project.pbxproj
+swift build 2>&1 | tail -1
+```
+Expected: both renders list the two plists with `SuccessfulExit => 0`; `xcodegen generate` prints `Created project at …mattstack.xcodeproj`; the lint is OK; `swift build` still `Build complete!`. **`xcodebuild -scheme mattstack build` — needs Xcode — blocked until installed** (record that it was not run).
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add rt-tray/project.yml rt-tray/Info.plist rt-tray/LaunchAgent.plist rt-tray/LaunchAgent-deck.plist rt-tray/scripts/render-launchagents.sh rt-tray/entitlements
+git commit -m "MAT-383: xcodegen project.yml (mattstack + mattstack-dev), Info.plist keys, two LaunchAgent templates
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 3: RtClient — spawn the bundled rt, NDJSON streaming, binary resolution
+
+**Files:**
+- Create: `rt-tray/Sources-core/Rt/NDJSONSplitter.swift`, `rt-tray/Sources-core/Rt/RtClient.swift`, `rt-tray/Sources-core/Rt/RtBinaryLocator.swift`, `rt-tray/Sources-core/Contract/OtherResults.swift`
+- Create: `rt-tray/Tests/MattstackCoreChecks/RtClientChecks.swift`
+- Modify: `rt-tray/Tests/MattstackCoreChecks/AllChecks.swift`
+
+**Interfaces:**
+- Produces:
+  - `public protocol RtRunning: Sendable { func run(_ args: [String], stdin: Data?) async throws -> RtResult; func stream(_ args: [String], stdin: Data?) -> AsyncThrowingStream<String, Error> }`
+  - `public struct RtResult { exitCode: Int32; stdout: Data; stderr: Data; func decode<T: Decodable>(_:) throws -> T; var userError: RtUserError? }`
+  - `public struct RtUserError: Codable, Error, Equatable { code: String?; message: String }` (decoded from `{"error":{...}}` on exit 2)
+  - `public final class RtClient: RtRunning` — `init(location: RtLocation, environment: [String: String])`
+  - `public struct RtLocation: Equatable { executable: URL; argumentPrefix: [String]; source: RtSource }`, `public enum RtSource { bundled, legacyBundled, devWrapper, stub }`
+  - `public enum RtBinaryLocator { static func resolve(bundlePath: String, isDevBuild: Bool, isDebugBuild: Bool, environment: [String: String], home: String, fileExists: (String) -> Bool) -> RtLocation? }`
+  - `public struct NDJSONSplitter { mutating func feed(_ data: Data) -> [String]; mutating func flush() -> String? }`
+  - `ConnectResult`, `TeamJoinResult`, `InviteResult`, `UninstallPlan`, `VersionInfo` (contract result shapes, Codable).
+
+- [ ] **Step 1: Write the failing checks**
+
+`rt-tray/Tests/MattstackCoreChecks/RtClientChecks.swift`:
+```swift
+import Foundation
+import MattstackCore
+
+/// Writes an executable shell script into a temp dir; checks spawn THAT and
+/// nothing else — never a real rt, never launchctl/pkill.
+private func fakeExecutable(_ body: String) throws -> URL {
+    let dir = FileManager.default.temporaryDirectory.appendingPathComponent("rt-checks-\(UUID().uuidString)")
+    try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+    let url = dir.appendingPathComponent("fake-rt")
+    try ("#!/bin/sh\n" + body + "\n").write(to: url, atomically: true, encoding: .utf8)
+    try FileManager.default.setAttributes([.posixPermissions: 0o755], ofItemAtPath: url.path)
+    return url
+}
+
+let rtClientChecks: [Check] = [
+    Check("NDJSONSplitter yields complete lines and keeps partial tails") { c in
+        var s = NDJSONSplitter()
+        c.expectEqual(s.feed(Data("{\"a\":1}\n{\"b\"".utf8)), ["{\"a\":1}"])
+        c.expectEqual(s.feed(Data(":2}\n\n{\"c\":3}".utf8)), ["{\"b\":2}"])
+        c.expectEqual(s.flush(), "{\"c\":3}")
+        c.expectEqual(s.flush(), nil)
+    },
+    Check("RtClient.run captures stdout, exit code, and passes stdin + RT_APP_SOCKET") { c in
+        let exe = try fakeExecutable(#"read line; printf '{"contract":1,"echo":"%s","sock":"%s","args":"%s"}' "$line" "$RT_APP_SOCKET" "$*"; exit 0"#)
+        let client = RtClient(location: RtLocation(executable: exe, argumentPrefix: [], source: .bundled),
+                              environment: ["RT_APP_SOCKET": "/tmp/x.sock"])
+        let result = try await client.run(["setup", "plan", "--json"], stdin: Data("{\"code\":\"abc\"}\n".utf8))
+        c.expectEqual(result.exitCode, 0)
+        struct Echo: Decodable { let echo: String; let sock: String; let args: String }
+        let echo: Echo = try result.decode(Echo.self)
+        c.expectEqual(echo.echo, "{\"code\":\"abc\"}")
+        c.expectEqual(echo.sock, "/tmp/x.sock")
+        c.expectEqual(echo.args, "setup plan --json")
+    },
+    Check("exit 2 with {error:{}} surfaces as RtUserError") { c in
+        let exe = try fakeExecutable(#"printf '{"contract":1,"error":{"code":"no-access","message":"ask the owner"}}'; exit 2"#)
+        let client = RtClient(location: RtLocation(executable: exe, argumentPrefix: [], source: .bundled), environment: [:])
+        let result = try await client.run(["team", "join"], stdin: nil)
+        c.expectEqual(result.exitCode, 2)
+        c.expectEqual(result.userError, RtUserError(code: "no-access", message: "ask the owner"))
+    },
+    Check("stream yields one element per NDJSON line and finishes") { c in
+        let exe = try fakeExecutable(#"printf '{"event":"plan","steps":[]}\n{"event":"done","ok":true}\n'"#)
+        let client = RtClient(location: RtLocation(executable: exe, argumentPrefix: [], source: .bundled), environment: [:])
+        var lines: [String] = []
+        for try await line in client.stream(["setup", "apply", "--json"], stdin: nil) { lines.append(line) }
+        c.expectEqual(lines.count, 2)
+        c.expect(lines[1].contains("\"done\""))
+    },
+    Check("stream throws when the process exits non-zero and non-2") { c in
+        let exe = try fakeExecutable("exit 1")
+        let client = RtClient(location: RtLocation(executable: exe, argumentPrefix: [], source: .bundled), environment: [:])
+        var threw = false
+        do { for try await _ in client.stream(["x"], stdin: nil) {} } catch { threw = true }
+        c.expect(threw, "expected a throw on exit 1")
+    },
+    Check("argumentPrefix is prepended (stub runs as bun <stub.ts> <args>)") { c in
+        let exe = try fakeExecutable(#"printf '{"contract":1,"args":"%s"}' "$*""#)
+        let client = RtClient(location: RtLocation(executable: exe, argumentPrefix: ["/stub.ts"], source: .stub), environment: [:])
+        struct A: Decodable { let args: String }
+        let a: A = try await client.run(["version"], stdin: nil).decode(A.self)
+        c.expectEqual(a.args, "/stub.ts version")
+    },
+    Check("locator: prod bundle → Contents/MacOS/rt, falling back to rt-daemon until L4 renames") { c in
+        let exists: (String) -> Bool = { $0 == "/Applications/mattstack.app/Contents/MacOS/rt-daemon" }
+        let loc = RtBinaryLocator.resolve(bundlePath: "/Applications/mattstack.app", isDevBuild: false, isDebugBuild: false,
+                                          environment: [:], home: "/Users/u", fileExists: exists)
+        c.expectEqual(loc?.source, .legacyBundled)
+        c.expectEqual(loc?.executable.path, "/Applications/mattstack.app/Contents/MacOS/rt-daemon")
+        let both: (String) -> Bool = { $0.hasSuffix("/rt") || $0.hasSuffix("/rt-daemon") }
+        let loc2 = RtBinaryLocator.resolve(bundlePath: "/Applications/mattstack.app", isDevBuild: false, isDebugBuild: false,
+                                           environment: [:], home: "/Users/u", fileExists: both)
+        c.expectEqual(loc2?.source, .bundled)
+        c.expectEqual(loc2?.executable.path, "/Applications/mattstack.app/Contents/MacOS/rt")
+    },
+    Check("locator: dev flavor prefers the ~/.local/bin/rt wrapper; stub only in DEBUG with both env vars") { c in
+        let all: (String) -> Bool = { _ in true }
+        let dev = RtBinaryLocator.resolve(bundlePath: "/x/mattstack-dev.app", isDevBuild: true, isDebugBuild: false,
+                                          environment: [:], home: "/Users/u", fileExists: all)
+        c.expectEqual(dev?.source, .devWrapper)
+        c.expectEqual(dev?.executable.path, "/Users/u/.local/bin/rt")
+        let env = ["RT_STUB_SCENARIO": "join-happy", "RT_STUB_PATH": "/repo/rt-tray/Tests/stub-rt/stub.ts"]
+        let stub = RtBinaryLocator.resolve(bundlePath: "/x/mattstack.app", isDevBuild: false, isDebugBuild: true,
+                                           environment: env, home: "/Users/u", fileExists: all)
+        c.expectEqual(stub?.source, .stub)
+        c.expectEqual(stub?.executable.path, "/Users/u/.bun/bin/bun")
+        c.expectEqual(stub?.argumentPrefix, ["/repo/rt-tray/Tests/stub-rt/stub.ts"])
+        let release = RtBinaryLocator.resolve(bundlePath: "/x/mattstack.app", isDevBuild: false, isDebugBuild: false,
+                                              environment: env, home: "/Users/u", fileExists: all)
+        c.expectEqual(release?.source, .bundled, "release builds ignore RT_STUB_SCENARIO")
+        let noPath = RtBinaryLocator.resolve(bundlePath: "/x/mattstack.app", isDevBuild: false, isDebugBuild: true,
+                                             environment: ["RT_STUB_SCENARIO": "x"], home: "/Users/u", fileExists: all)
+        c.expectEqual(noPath?.source, .bundled, "scenario without RT_STUB_PATH is ignored")
+        let none = RtBinaryLocator.resolve(bundlePath: "/x/mattstack.app", isDevBuild: false, isDebugBuild: false,
+                                           environment: [:], home: "/Users/u", fileExists: { _ in false })
+        c.expect(none == nil, "no rt anywhere → nil, never a guess")
+    },
+]
+```
+Register: `let allChecks: [Check] = planModelsChecks + rtClientChecks`.
+
+- [ ] **Step 2: Run → compile failure** (`cannot find 'NDJSONSplitter'`).
+
+- [ ] **Step 3: Implement**
+
+`rt-tray/Sources-core/Rt/NDJSONSplitter.swift`:
+```swift
+import Foundation
+
+public struct NDJSONSplitter: Sendable {
+    private var buffer = Data()
+    public init() {}
+
+    public mutating func feed(_ data: Data) -> [String] {
+        buffer.append(data)
+        var lines: [String] = []
+        while let nl = buffer.firstIndex(of: UInt8(ascii: "\n")) {
+            let chunk = buffer.subdata(in: buffer.startIndex..<nl)
+            buffer.removeSubrange(buffer.startIndex...nl)
+            if let s = String(data: chunk, encoding: .utf8)?.trimmingCharacters(in: .whitespaces), !s.isEmpty {
+                lines.append(s)
+            }
+        }
+        return lines
+    }
+
+    public mutating func flush() -> String? {
+        defer { buffer.removeAll() }
+        guard let s = String(data: buffer, encoding: .utf8)?.trimmingCharacters(in: .whitespacesAndNewlines),
+              !s.isEmpty else { return nil }
+        return s
+    }
+}
+```
+
+`rt-tray/Sources-core/Contract/OtherResults.swift`:
+```swift
+import Foundation
+
+public struct RtUserError: Codable, Error, Equatable, Sendable {
+    public var code: String?
+    public var message: String
+    public init(code: String? = nil, message: String) { self.code = code; self.message = message }
+}
+
+struct ErrorEnvelope: Decodable { let error: RtUserError }
+
+public struct ConnectResult: Codable, Equatable, Sendable {
+    public var integration: String
+    public var status: RowStatus
+    public var detail: String?
+    public var scopesSeen: [String]?
+}
+
+public struct TeamJoinResult: Codable, Equatable, Sendable {
+    public struct Team: Codable, Equatable, Sendable { public var slug: String; public var name: String; public var owner: String? }
+    public var team: Team?
+    public var access: String      // ok | denied | unreachable
+    public var peering: String?    // applied | idle | unavailable
+    public var message: String?
+}
+
+public struct InviteResult: Codable, Equatable, Sendable {
+    public var code: String
+    public var expiresAt: String
+    public var pasteBlock: String
+    public var forgeAccess: String    // granted | manual | skipped
+    public var manualSteps: [String]?
+}
+
+public struct UninstallPlan: Codable, Equatable, Sendable {
+    public struct Action: Codable, Equatable, Identifiable, Sendable { public var id: String; public var title: String }
+    public var actions: [Action]
+}
+
+public struct VersionInfo: Codable, Equatable, Sendable {
+    public var version: String
+    public var build: Int        // numeric CFBundleVersion: major*1e6 + minor*1e3 + patch (L4 scheme; 2.8.0 → 2008000)
+    public var flavor: String   // prod | dev
+    public var path: String
+    public init(version: String, build: Int, flavor: String, path: String) {
+        self.version = version; self.build = build; self.flavor = flavor; self.path = path
+    }
+}
+```
+
+`rt-tray/Sources-core/Rt/RtClient.swift`:
+```swift
+import Foundation
+
+public struct RtResult: Sendable {
+    public let exitCode: Int32
+    public let stdout: Data
+    public let stderr: Data
+
+    public func decode<T: Decodable>(_ type: T.Type) throws -> T {
+        try JSONDecoder().decode(T.self, from: stdout)
+    }
+    /// Exit 2 carries `{ "error": {...} }` on stdout.
+    public var userError: RtUserError? {
+        guard exitCode == 2 else { return nil }
+        return (try? JSONDecoder().decode(ErrorEnvelope.self, from: stdout))?.error
+            ?? RtUserError(code: nil, message: String(decoding: stderr.prefix(2000), as: UTF8.self))
+    }
+}
+
+public enum RtClientError: Error, Equatable {
+    case spawnFailed(String)
+    case exited(Int32, stderr: String)
+}
+
+public protocol RtRunning: Sendable {
+    func run(_ args: [String], stdin: Data?) async throws -> RtResult
+    func stream(_ args: [String], stdin: Data?) -> AsyncThrowingStream<String, Error>
+}
+
+public enum RtSource: Equatable, Sendable { case bundled, legacyBundled, devWrapper, stub }
+
+public struct RtLocation: Equatable, Sendable {
+    public let executable: URL
+    public let argumentPrefix: [String]
+    public let source: RtSource
+    public init(executable: URL, argumentPrefix: [String], source: RtSource) {
+        self.executable = executable; self.argumentPrefix = argumentPrefix; self.source = source
+    }
+}
+
+/// Spawns rt by absolute path. Secrets travel on stdin only; nothing here
+/// ever puts a token or code into argv.
+public final class RtClient: RtRunning, @unchecked Sendable {
+    public let location: RtLocation
+    private let environment: [String: String]
+
+    public init(location: RtLocation, environment: [String: String]) {
+        self.location = location
+        self.environment = environment
+    }
+
+    private func makeProcess(_ args: [String]) -> Process {
+        let p = Process()
+        p.executableURL = location.executable
+        p.arguments = location.argumentPrefix + args
+        var env = ProcessInfo.processInfo.environment
+        for (k, v) in environment { env[k] = v }
+        p.environment = env
+        return p
+    }
+
+    public func run(_ args: [String], stdin: Data?) async throws -> RtResult {
+        let p = makeProcess(args)
+        let out = Pipe(), err = Pipe(), inPipe = Pipe()
+        p.standardOutput = out; p.standardError = err; p.standardInput = inPipe
+        do { try p.run() } catch { throw RtClientError.spawnFailed(String(describing: error)) }
+        if let stdin { inPipe.fileHandleForWriting.write(stdin) }
+        try? inPipe.fileHandleForWriting.close()
+        // Drain both pipes off the calling thread before waiting, or a chatty
+        // child fills a pipe and we deadlock on waitUntilExit.
+        async let stdoutData = Task.detached { out.fileHandleForReading.readDataToEndOfFile() }.value
+        async let stderrData = Task.detached { err.fileHandleForReading.readDataToEndOfFile() }.value
+        let (o, e) = await (stdoutData, stderrData)
+        p.waitUntilExit()
+        return RtResult(exitCode: p.terminationStatus, stdout: o, stderr: e)
+    }
+
+    public func stream(_ args: [String], stdin: Data?) -> AsyncThrowingStream<String, Error> {
+        AsyncThrowingStream { continuation in
+            let p = makeProcess(args)
+            let out = Pipe(), err = Pipe(), inPipe = Pipe()
+            p.standardOutput = out; p.standardError = err; p.standardInput = inPipe
+            var splitter = NDJSONSplitter()
+            let lock = NSLock()
+            out.fileHandleForReading.readabilityHandler = { handle in
+                let data = handle.availableData
+                lock.lock(); defer { lock.unlock() }
+                if data.isEmpty {
+                    handle.readabilityHandler = nil
+                    if let tail = splitter.flush() { continuation.yield(tail) }
+                    return
+                }
+                for line in splitter.feed(data) { continuation.yield(line) }
+            }
+            p.terminationHandler = { proc in
+                lock.lock()
+                let tail = splitter.flush()
+                lock.unlock()
+                if let tail { continuation.yield(tail) }
+                let stderr = String(decoding: err.fileHandleForReading.readDataToEndOfFile().prefix(4000), as: UTF8.self)
+                switch proc.terminationStatus {
+                case 0, 2: continuation.finish()
+                default: continuation.finish(throwing: RtClientError.exited(proc.terminationStatus, stderr: stderr))
+                }
+            }
+            do { try p.run() } catch {
+                continuation.finish(throwing: RtClientError.spawnFailed(String(describing: error)))
+                return
+            }
+            if let stdin { inPipe.fileHandleForWriting.write(stdin) }
+            try? inPipe.fileHandleForWriting.close()
+            continuation.onTermination = { _ in if p.isRunning { p.terminate() } }
+        }
+    }
+}
+```
+
+`rt-tray/Sources-core/Rt/RtBinaryLocator.swift`:
+```swift
+import Foundation
+
+/// Where the app's rt lives. Order: the DEBUG-only stub override, the dev
+/// flavor's source wrapper, the bundled binary, the pre-rename bundled
+/// binary. Returns nil rather than guessing at a PATH lookup.
+public enum RtBinaryLocator {
+    public static func resolve(bundlePath: String, isDevBuild: Bool, isDebugBuild: Bool,
+                               environment: [String: String], home: String,
+                               fileExists: (String) -> Bool) -> RtLocation? {
+        if isDebugBuild,
+           let scenario = environment["RT_STUB_SCENARIO"], !scenario.isEmpty,
+           let stub = environment["RT_STUB_PATH"], !stub.isEmpty {
+            let bun = environment["RT_STUB_BUN"] ?? "\(home)/.bun/bin/bun"
+            return RtLocation(executable: URL(fileURLWithPath: bun), argumentPrefix: [stub], source: .stub)
+        }
+        if isDevBuild {
+            let wrapper = "\(home)/.local/bin/rt"
+            if fileExists(wrapper) {
+                return RtLocation(executable: URL(fileURLWithPath: wrapper), argumentPrefix: [], source: .devWrapper)
+            }
+        }
+        let bundled = "\(bundlePath)/Contents/MacOS/rt"
+        if fileExists(bundled) {
+            return RtLocation(executable: URL(fileURLWithPath: bundled), argumentPrefix: [], source: .bundled)
+        }
+        let legacy = "\(bundlePath)/Contents/MacOS/rt-daemon"
+        if fileExists(legacy) {
+            return RtLocation(executable: URL(fileURLWithPath: legacy), argumentPrefix: [], source: .legacyBundled)
+        }
+        return nil
+    }
+}
+```
+
+- [ ] **Step 4: Run** `swift run mattstack-checks` → `checks: 11 passed, 0 failed`.
+
+- [ ] **Step 5: Commit**
+```bash
+git add rt-tray/Sources-core rt-tray/Tests
+git commit -m "MAT-383: RtClient — absolute-path spawn, NDJSON stream, stdin-only secrets, binary locator
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 4: The stub rt (Bun) — canned contract responses per scenario
+
+**Files:**
+- Create: `rt-tray/Tests/stub-rt/stub.ts`
+- Create: `rt-tray/Tests/stub-rt/stub.test.ts`
+
+**Interfaces:**
+- Produces: `bun rt-tray/Tests/stub-rt/stub.ts <rt args…>` honouring `RT_STUB_SCENARIO` ∈ `create-happy | join-happy | join-no-access | perm-denied-then-granted | apply-fail-retry | restore | uninstall`, `RT_STUB_STATE_DIR` (default `rt-tray/Tests/stub-rt/.state/<scenario>`) for cross-invocation state, `RT_APP_SOCKET` (read, never required). (The app side reads `RT_STUB_PATH` — absolute path to `stub.ts`, required — and `RT_STUB_BUN`, default `~/.bun/bin/bun`, in `RtBinaryLocator` (Task 3); the contract's Stub section lists all four variables.) Verbs: `setup plan`, `setup status`, `setup apply [--from id]`, `setup <integration> status|connect` (`setup github status` adds `handle`/`owners`), `team create`, `team join [--dry-run]`, `team invite`, `team status`, `uninstall [--dry-run] [--keep-data|--delete-data] [--yes]`, `settings set`, `restore`, `setup intent restore`, `home init`, `version`. Row ids, uninstall action ids and result shapes are L1's (contract): `perm.login-items`, `access.team-repo`, `tool.fast-browser`, `tool.path`; `team join --dry-run` no-access is exit 0 `{access:"denied", message}`. Exit codes per contract. Used by Task 19's XCUITests and by hand with the dev app.
+
+- [ ] **Step 1: Write the failing bun test**
+
+`rt-tray/Tests/stub-rt/stub.test.ts`:
+```ts
+import { test, expect } from "bun:test";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const STUB = join(import.meta.dir, "stub.ts");
+
+async function run(scenario: string, args: string[], stdin = "", stateDir?: string) {
+  const proc = Bun.spawn(["bun", STUB, ...args], {
+    env: { ...process.env, RT_STUB_SCENARIO: scenario, RT_STUB_STATE_DIR: stateDir ?? mkdtempSync(join(tmpdir(), "stub-")) },
+    stdin: new Blob([stdin]),
+    stdout: "pipe",
+  });
+  const out = await new Response(proc.stdout).text();
+  const code = await proc.exited;
+  return { code, out, lines: out.trim().split("\n").filter(Boolean).map((l) => JSON.parse(l)) };
+}
+
+test("setup plan: join-happy is installable, perm-denied is not", async () => {
+  const ok = await run("join-happy", ["setup", "plan", "--json"]);
+  expect(ok.code).toBe(0);
+  expect(ok.lines[0].contract).toBe(1);
+  expect(ok.lines[0].canInstall).toBe(true);
+  const denied = await run("perm-denied-then-granted", ["setup", "plan", "--json"]);
+  expect(denied.lines[0].canInstall).toBe(false);
+  expect(denied.lines[0].requiredMissing).toContain("perm.fda");
+});
+
+test("perm-denied-then-granted: plan flips to installable on the second call", async () => {
+  const state = mkdtempSync(join(tmpdir(), "stub-"));
+  const first = await run("perm-denied-then-granted", ["setup", "plan", "--json"], "", state);
+  const second = await run("perm-denied-then-granted", ["setup", "plan", "--json"], "", state);
+  expect(first.lines[0].canInstall).toBe(false);
+  expect(second.lines[0].canInstall).toBe(true);
+});
+
+test("team join --dry-run reads the code from stdin; no-access is exit 0 {access:'denied'} with a specific message", async () => {
+  const happy = await run("join-happy", ["team", "join", "--dry-run", "--json"], JSON.stringify({ code: "ABCD-EFGH" }));
+  expect(happy.code).toBe(0);
+  expect(happy.lines[0].access).toBe("ok");
+  expect(happy.lines[0].team.name).toBe("Assured");
+  const denied = await run("join-no-access", ["team", "join", "--dry-run", "--json"], JSON.stringify({ code: "ABCD-EFGH" }));
+  expect(denied.code).toBe(0);
+  expect(denied.lines[0].access).toBe("denied");
+  expect(denied.lines[0].message).toContain("ask");
+  const malformed = await run("join-happy", ["team", "join", "--dry-run", "--json"], JSON.stringify({ code: "" }));
+  expect(malformed.code).toBe(2);
+  expect(malformed.lines[0].error.code).toBe("invite-malformed");
+});
+
+test("setup apply streams plan/step/need/done; apply-fail-retry fails once then succeeds with --from", async () => {
+  const state = mkdtempSync(join(tmpdir(), "stub-"));
+  const first = await run("apply-fail-retry", ["setup", "apply", "--json"], "", state);
+  const events = first.lines.map((e) => e.event);
+  expect(events[0]).toBe("plan");
+  expect(events).toContain("need");
+  const done = first.lines.at(-1);
+  expect(done.event).toBe("done");
+  expect(done.ok).toBe(false);
+  expect(done.failedStep).toBe("plugins.install");
+  const retry = await run("apply-fail-retry", ["setup", "apply", "--from", "plugins.install", "--json"], "", state);
+  expect(retry.lines[0].steps[0].id).toBe("plugins.install");
+  expect(retry.lines.at(-1).ok).toBe(true);
+});
+
+test("uninstall --dry-run lists L1's action ids; --delete-data needs --yes; version build is numeric", async () => {
+  const dry = await run("uninstall", ["uninstall", "--dry-run", "--json"]);
+  expect(dry.lines[0].actions.map((a) => a.id)).toEqual(["services.unregister", "deck.managed-remove", "proxy.remove", "path.unlink", "shell.remove", "extension.uninstall", "plugins.uninstall", "app.trash"]);
+  const dryDelete = await run("uninstall", ["uninstall", "--dry-run", "--delete-data", "--json"]);
+  expect(dryDelete.lines[0].actions.map((a) => a.id)).toContain("data");
+  const noYes = await run("uninstall", ["uninstall", "--delete-data", "--json"]);
+  expect(noYes.code).toBe(2);
+  expect(noYes.lines[0].error.code).toBe("confirm-required");
+  const v = await run("join-happy", ["version", "--json"]);
+  expect(v.lines[0].version).toBeDefined();
+  expect(v.lines[0].build).toBe(0);
+});
+
+test("team status and setup github status answer the contract shapes", async () => {
+  const ts = await run("join-happy", ["team", "status", "--json"]);
+  expect(ts.lines[0].slug).toBe("assured");
+  expect(ts.lines[0].members[0].username).toBe("matt");
+  const gh = await run("join-happy", ["setup", "github", "status", "--json"]);
+  expect(gh.lines[0].handle).toBe("matt");
+  expect(gh.lines[0].owners).toContain("assured");
+});
+```
+
+- [ ] **Step 2: Run** `cd rt-tray && bun test Tests/stub-rt/` → fails (`stub.ts` missing).
+
+- [ ] **Step 3: Write the stub**
+
+`rt-tray/Tests/stub-rt/stub.ts`:
+```ts
+#!/usr/bin/env bun
+// Stub rt for app tests: canned contract-v1 answers per RT_STUB_SCENARIO.
+// State that must change between invocations (a permission granted, a step
+// retried) lives in RT_STUB_STATE_DIR so every call is a fresh process like
+// the real rt.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const scenario = process.env.RT_STUB_SCENARIO ?? "join-happy";
+const stateDir = process.env.RT_STUB_STATE_DIR ?? join(import.meta.dir, ".state", scenario);
+mkdirSync(stateDir, { recursive: true });
+const at = new Date().toISOString();
+const args = process.argv.slice(2).filter((a) => a !== "--json");
+
+function stateGet(key: string, fallback = 0): number {
+  const p = join(stateDir, key);
+  return existsSync(p) ? Number(readFileSync(p, "utf8")) : fallback;
+}
+function stateBump(key: string): number {
+  const n = stateGet(key) + 1;
+  writeFileSync(join(stateDir, key), String(n));
+  return n;
+}
+function emit(obj: unknown) { process.stdout.write(JSON.stringify({ contract: 1, at, ...(obj as object) }) + "\n"); }
+function fail(code: string, message: string): never { emit({ error: { code, message } }); process.exit(2); }
+async function readStdinJSON(): Promise<Record<string, unknown>> {
+  const text = await new Response(Bun.stdin.stream()).text();
+  try { return text.trim() ? JSON.parse(text) : {}; } catch { return {}; }
+}
+
+const row = (id: string, kind: string, title: string, why: string, required: boolean, status: string,
+             detail: string | null, action: unknown, recheck = "on-change", optionalNote: string | null = null) =>
+  ({ id, kind, title, why, required, optionalNote, status, detail, action, recheck });
+
+function plan(): unknown {
+  const fdaCalls = stateBump("plan-calls");
+  const fdaGranted = scenario !== "perm-denied-then-granted" || fdaCalls >= 2;
+  const mode = scenario === "create-happy" ? "create" : scenario === "restore" ? "restore" : "join";
+  const mac = [
+    row("perm.fda", "permission", "Full Disk Access",
+        "Reads your repositories' git state so the daemon can show branch and MR status.", true,
+        fdaGranted ? "ready" : "needs-you", fdaGranted ? "Granted" : "Not granted",
+        fdaGranted ? null : { type: "open-settings", label: "Open Full Disk Access Settings…", target: "fda" }, "on-activate"),
+    row("perm.login-items", "permission", "Background services",
+        "rt daemon and deck run in the background as login items.", true, "ready", "Enabled", null, "on-activate"),
+    row("perm.notifications", "permission", "Notifications", "Pipeline and review alerts.", false, "skipped", "Not decided",
+        { type: "request-permission", label: "Allow", which: "notifications" }, "on-activate",
+        "Works without this; you'll see menu-bar badges instead."),
+    row("tool.clt", "tool", "Apple command line tools", "git and python3 come from here.", true, "ready", "git 2.50.1", null),
+    row("tool.path", "info", "~/.local/bin first on PATH", "Install adds one PATH line to your shell rc.", true, "ready", "Fixed by Install", null),
+  ];
+  const accounts = [
+    row("account.gitlab", "account", "GitLab", "The team's merge requests live on gitlab.assured.com.", true,
+        stateGet("gitlab-connected") ? "ready" : "missing", stateGet("gitlab-connected") ? "token can see group assured" : null,
+        { type: "connect", label: "Connect", integration: "gitlab",
+          fields: [{ name: "token", label: "Personal access token", secret: true, hint: "scopes: read_api, read_user" }],
+          alternatives: [] }),
+  ];
+  const access = [row("access.team-repo", "access", "Team repo reachable", "github.com/assured/mattstack-team-assured", true, "ready", "ls-remote ok", null)];
+  const tools = [
+    row("tool.herdr", "tool", "herdr", "Runs the agents that do the work.", true, "ready", "0.9.2", null),
+    row("tool.fast-browser", "tool", "Fast Browser", "Browser automation for evidence.", true, "needs-you", "extension not loaded",
+        { type: "steps", label: "Show steps…", steps: ["Open chrome://extensions", "Turn on Developer mode", "Load unpacked → ~/.fast-browser/extension/current/unpacked"] }),
+    row("tool.chrome", "tool", "Google Chrome", "Evidence capture.", false, "skipped", null,
+        { type: "open-url", label: "Download", url: "https://www.google.com/chrome/" }, "manual", "Works without this."),
+  ];
+  const required = [...mac, ...accounts, ...access, ...tools].filter((r) => r.required && r.status !== "ready").map((r) => r.id);
+  // join-happy and create-happy are installable out of the box so flows can reach Install without connecting anything.
+  const installableScenario = ["join-happy", "create-happy", "apply-fail-retry", "restore", "uninstall"].includes(scenario);
+  const requiredMissing = installableScenario ? [] : required;
+  if (installableScenario) { accounts[0].status = "ready"; accounts[0].detail = "token can see group assured"; tools[1].status = "ready"; tools[1].detail = "extension loaded"; }
+  return {
+    team: { slug: "assured", name: "Assured", mode },
+    groups: [
+      { id: "mac", title: "Your Mac", rows: mac },
+      { id: "accounts", title: "Accounts", rows: accounts },
+      { id: "access", title: "Access", rows: access },
+      { id: "tools", title: "Tools", rows: tools },
+    ],
+    canInstall: requiredMissing.length === 0,
+    requiredMissing,
+  };
+}
+
+const STEPS = [
+  ["home.init", "Create your settings home repo", "rt"], ["team.join", "Join the team", "rt"],
+  ["secrets.write", "Store the tokens you entered", "rt"], ["path.link", "Link rt, fast-browser, gitq, deck into ~/.local/bin", "rt"],
+  ["settings.seed", "Write machine settings", "rt"], ["repos.clone", "Clone the team's repositories", "rt"],
+  ["services.register", "Register the rt daemon and deck", "app"], ["proxy.install", "Install the local HTTPS proxy", "privileged"],
+  ["plugins.install", "Install the mattstack skills into Claude Code", "rt"], ["services.start", "Start services", "rt"],
+  ["verify", "Verify everything", "rt"],
+] as const;
+
+async function apply() {
+  const fromIdx = Math.max(0, args.indexOf("--from"));
+  const fromId = fromIdx > 0 ? args[fromIdx + 1] : null;
+  const start = fromId ? STEPS.findIndex((s) => s[0] === fromId) : 0;
+  const steps = STEPS.slice(start < 0 ? 0 : start);
+  const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+  const line = (o: unknown) => process.stdout.write(JSON.stringify(o) + "\n");
+  line({ event: "plan", steps: steps.map(([id, title, kind]) => ({ id, title, kind })) });
+  for (const [id, , kind] of steps) {
+    line({ event: "step", id, state: "running" });
+    await sleep(120);
+    if (kind === "app") {
+      line({ event: "need", id, request: { type: "app-register-services", plists: ["com.mattstack.daemon.plist", "com.mattstack.deck.plist"] } });
+    } else if (kind === "privileged") {
+      line({ event: "need", id, request: { type: "app-privileged", op: "proxy-install" } });
+    } else {
+      line({ event: "log", id, line: `${id}: working…` });
+    }
+    if (scenario === "apply-fail-retry" && id === "plugins.install" && stateBump("plugins-attempts") === 1) {
+      line({ event: "step", id, state: "failed", detail: "claude plugin install exited 1",
+             remedy: "Open Claude Code once so it finishes first-run, then Retry." });
+      line({ event: "done", ok: false, failedStep: id });
+      return;
+    }
+    line({ event: "step", id, state: "done", detail: kind === "rt" ? "ok" : "done by the app" });
+  }
+  line({ event: "done", ok: true, failedStep: null });
+}
+
+const [a0, a1, a2] = args;
+if (a0 === "setup" && (a1 === "plan" || a1 === "status")) emit(plan());
+else if (a0 === "setup" && a1 === "apply") await apply();
+else if (a0 === "setup" && a1 === "github" && a2 === "status") emit({ integration: "github", status: "ready", detail: "gh authenticated as matt", scopesSeen: ["repo", "read:org"], handle: "matt", owners: ["matt", "assured"] });
+else if (a0 === "setup" && a1 === "intent" && a2 === "restore") emit({ ok: true, intent: "restore", repo: args[3] });
+else if (a0 === "setup" && a2 === "status") emit({ integration: a1, status: stateGet(`${a1}-connected`) ? "ready" : "missing", detail: null });
+else if (a0 === "setup" && a2 === "connect") {
+  const body = await readStdinJSON();
+  if (!body.token && !body.useGh) fail("no-token", "Paste a token or use gh.");
+  stateBump(`${a1}-connected`);
+  emit({ integration: a1, status: "ready", detail: "token can see group assured", scopesSeen: ["read_api"] });
+}
+else if (a0 === "team" && a1 === "create") emit({ team: { slug: "my-team", name: args[2] ?? "My team" }, remote: "ok" });
+else if (a0 === "team" && a1 === "join") {
+  const body = await readStdinJSON();
+  if (!body.code) fail("invite-malformed", "Paste an invite code.");
+  if (scenario === "join-no-access") emit({ team: { slug: "assured", name: "Assured", owner: "matt" }, access: "denied", peering: "idle", message: "You don't have access yet: ask matt to grant you access to Assured." });
+  else emit({ team: { slug: "assured", name: "Assured", owner: "matt" }, access: "ok", peering: "idle", message: "Joining Assured (owner matt)" });
+}
+else if (a0 === "team" && a1 === "status") emit({ slug: "assured", name: "Assured", remote: "git@github.com:assured/mattstack-team-assured.git", lastPush: "2026-08-21T03:00:00Z", members: [{ username: "matt" }, { username: "bob" }] });
+else if (a0 === "team" && a1 === "invite") emit({ code: "ABCD-EFGH-IJKL-MNOP-QRST-UVWX-YZ23-4567", expiresAt: "2026-08-28T00:00:00Z",
+  pasteBlock: "Install mattstack from https://github.com/m4ttstack/rt/releases, then open mattstack://join/ABCD-EFGH-IJKL-MNOP-QRST-UVWX-YZ23-4567 or paste the code into Setup → Join a team.",
+  forgeAccess: "granted", manualSteps: [] });
+else if (a0 === "uninstall" && args.includes("--dry-run")) emit({ actions: [
+  { id: "services.unregister", title: "Stop and remove the rt daemon and deck services" },
+  { id: "deck.managed-remove", title: "Remove board and gitq from deck" },
+  { id: "proxy.remove", title: "Remove the local HTTPS proxy (admin prompt)" },
+  { id: "path.unlink", title: "Remove ~/.local/bin links" },
+  { id: "shell.remove", title: "Remove the shell rc block" },
+  { id: "extension.uninstall", title: "Uninstall the rt-context editor extension" },
+  { id: "plugins.uninstall", title: "Uninstall the mattstack plugins from Claude Code" },
+  ...(args.includes("--delete-data") ? [{ id: "data", title: "Delete ~/.mattstack (settings, state, logs)" }] : []),
+  { id: "app.trash", title: "Move mattstack.app to the Trash" } ] });
+else if (a0 === "uninstall") {
+  if (args.includes("--delete-data") && !args.includes("--yes")) fail("confirm-required", "--delete-data needs --yes when not on a TTY.");
+  for (const id of ["services.unregister", "path.unlink", "app.trash"]) {
+  process.stdout.write(JSON.stringify({ event: "step", id, state: "running" }) + "\n");
+  process.stdout.write(JSON.stringify({ event: "step", id, state: "done" }) + "\n"); }
+  process.stdout.write(JSON.stringify({ event: "done", ok: true }) + "\n"); }
+else if (a0 === "settings" && a1 === "set") emit({ ok: true, key: a2 });
+else if (a0 === "restore") emit({ ok: true, repo: a1 });
+else if (a0 === "home" && a1 === "init") emit({ ok: true });
+else if (a0 === "version" || a0 === "--version") emit({ version: "2.8.0-stub", build: 0 });
+else fail("unknown-verb", `stub has no answer for: ${args.join(" ")}`);
+```
+
+- [ ] **Step 4: Run** `cd rt-tray && bun test Tests/stub-rt/` → 6 pass. Also `RT_STUB_SCENARIO=join-happy bun Tests/stub-rt/stub.ts setup plan --json | head -c 200`.
+
+- [ ] **Step 5: Commit**
+```bash
+git add rt-tray/Tests/stub-rt
+git commit -m "MAT-383: stub rt — contract v1 scenarios for app tests
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 5: ReadinessModel — plan → rows, enablement, recheck policy, timers, permission overlay
+
+**Files:**
+- Create: `rt-tray/Sources-core/Readiness/ReadinessModel.swift`, `rt-tray/Sources-core/Readiness/StatusGlyph.swift`, `rt-tray/Sources-core/Permissions/PermissionSnapshot.swift`
+- Create: `rt-tray/Tests/MattstackCoreChecks/ReadinessModelChecks.swift`
+- Modify: `AllChecks.swift`
+
+**Interfaces:**
+- Consumes: `Plan`, `PlanRow` (Task 1).
+- Produces:
+  - `public protocol PlanSource: Sendable { func fetchPlan() async throws -> Plan }`
+  - `public protocol PermissionProbing: Sendable { func snapshot() async -> PermissionSnapshot }`
+  - `public protocol TickerScheduling: Sendable { func schedule(every seconds: TimeInterval, _ tick: @escaping @Sendable () -> Void) -> TickerHandle }`, `public final class TickerHandle { init(_ cancel: @escaping @Sendable () -> Void); let cancel: @Sendable () -> Void }`
+  - `public struct PermissionSnapshot: Codable, Equatable, Sendable { fda: FDAState; notifications: NotificationsState; loginItems: LoginItemsState }` with nested `status` strings per contract, `PermissionSnapshot.unknown`
+  - `public enum PermissionRowOverlay { static func status(for rowId: String, in snapshot: PermissionSnapshot) -> (RowStatus, String)? }` — rows `perm.fda`, `perm.login-items`, `perm.notifications`
+  - `@MainActor public final class ReadinessModel: ObservableObject` — `init(plans: PlanSource, permissions: PermissionProbing, ticker: TickerScheduling)`; `@Published groups: [PlanGroup]`, `team: TeamInfo?`, `canInstall: Bool`, `requiredMissing: [String]`, `isLoading: Bool`, `lastError: String?`, `checkingRowIds: Set<String>`; `var limitedModeAvailable: Bool`; `func load() async`; `func becameVisible()`, `becameHidden()`, `didBecomeActive()`; `func afterAction(rowId: String) async`; `func recheckAll() async`; `func row(_ id: String) -> PlanRow?`
+  - `public enum StatusGlyph { static func symbol(for: RowStatus) -> String; static func tint(for: RowStatus) -> GlyphTint }`, `public enum GlyphTint { green, red, yellow, grey, none }`
+
+- [ ] **Step 1: Write the failing checks**
+
+`rt-tray/Tests/MattstackCoreChecks/ReadinessModelChecks.swift`:
+```swift
+import Foundation
+import MattstackCore
+
+final class FakePlans: PlanSource, @unchecked Sendable {
+    var plans: [Plan]
+    private(set) var fetches = 0
+    init(_ plans: [Plan]) { self.plans = plans }
+    func fetchPlan() async throws -> Plan {
+        fetches += 1
+        return plans.count > 1 ? plans.removeFirst() : plans[0]
+    }
+}
+final class FakePermissions: PermissionProbing, @unchecked Sendable {
+    var snapshot = PermissionSnapshot.unknown
+    private(set) var probes = 0
+    func snapshot() async -> PermissionSnapshot { probes += 1; return snapshot }
+}
+final class FakeTicker: TickerScheduling, @unchecked Sendable {
+    var ticks: [@Sendable () -> Void] = []
+    var cancelled = 0
+    func schedule(every seconds: TimeInterval, _ tick: @escaping @Sendable () -> Void) -> TickerHandle {
+        ticks.append(tick)
+        return TickerHandle { [self] in cancelled += 1 }
+    }
+    func fire() { ticks.forEach { $0() } }
+}
+
+func makePlan(fda: RowStatus = .needsYou, gitlab: RowStatus = .missing, chrome: RowStatus = .skipped) -> Plan {
+    let rows1 = [
+        PlanRow(id: "perm.fda", kind: .permission, title: "Full Disk Access", why: "w", required: true, status: fda,
+                action: RowAction(type: .openSettings, label: "Open Full Disk Access Settings…", target: "fda"), recheck: .onActivate),
+        PlanRow(id: "perm.notifications", kind: .permission, title: "Notifications", why: "w", required: false,
+                optionalNote: "Works without this.", status: .skipped, recheck: .onActivate),
+    ]
+    let rows2 = [
+        PlanRow(id: "account.gitlab", kind: .account, title: "GitLab", why: "w", required: true, status: gitlab,
+                action: RowAction(type: .connect, label: "Connect", integration: "gitlab"), recheck: .onChange),
+        PlanRow(id: "tool.chrome", kind: .tool, title: "Chrome", why: "w", required: false, optionalNote: "Works without this.",
+                status: chrome, recheck: .manual),
+    ]
+    let missing = (rows1 + rows2).filter { $0.required && $0.status != .ready }.map(\.id)
+    return Plan(at: "t", team: TeamInfo(slug: "assured", name: "Assured", mode: .join),
+                groups: [PlanGroup(id: "mac", title: "Your Mac", rows: rows1), PlanGroup(id: "accounts", title: "Accounts", rows: rows2)],
+                canInstall: missing.isEmpty, requiredMissing: missing)
+}
+
+let readinessModelChecks: [Check] = [
+    Check("load renders groups and enablement from the plan") { c in
+        let plans = FakePlans([makePlan()])
+        let m = await MainActor.run { ReadinessModel(plans: plans, permissions: FakePermissions(), ticker: FakeTicker()) }
+        await m.load()
+        await MainActor.run {
+            c.expectEqual(m.groups.count, 2)
+            c.expectEqual(m.team?.mode, .join)
+            c.expectEqual(m.canInstall, false)
+            c.expectEqual(m.requiredMissing, ["perm.fda", "account.gitlab"])
+            c.expectEqual(m.limitedModeAvailable, false)
+        }
+    },
+    Check("limited mode only when every required row is ready and some optional row is not") { c in
+        let plans = FakePlans([makePlan(fda: .ready, gitlab: .ready, chrome: .skipped)])
+        let m = await MainActor.run { ReadinessModel(plans: plans, permissions: FakePermissions(), ticker: FakeTicker()) }
+        await m.load()
+        await MainActor.run {
+            c.expectEqual(m.canInstall, true)
+            c.expectEqual(m.limitedModeAvailable, true)
+        }
+        let plans2 = FakePlans([makePlan(fda: .ready, gitlab: .ready, chrome: .ready)])
+        let m2 = await MainActor.run { ReadinessModel(plans: plans2, permissions: FakePermissions(), ticker: FakeTicker()) }
+        await m2.load()
+        await MainActor.run { c.expectEqual(m2.limitedModeAvailable, false, "notifications optional row is 'skipped' → still limited") }
+    },
+    Check("visible → 1s ticker probes permissions and overlays permission rows; hidden cancels") { c in
+        let plans = FakePlans([makePlan()])
+        let perms = FakePermissions()
+        let ticker = FakeTicker()
+        let m = await MainActor.run { ReadinessModel(plans: plans, permissions: perms, ticker: ticker) }
+        await m.load()
+        await MainActor.run { m.becameVisible() }
+        c.expectEqual(ticker.ticks.count, 1)
+        perms.snapshot = PermissionSnapshot(fda: .init(status: "granted", detail: "probe read ~/Library/Containers/com.apple.stocks"),
+                                            notifications: .init(status: "authorized"),
+                                            loginItems: .init(status: "requiresApproval"))
+        ticker.fire()
+        try await Task.sleep(nanoseconds: 100_000_000)
+        await MainActor.run {
+            c.expectEqual(m.row("perm.fda")?.status, .ready)
+            c.expectEqual(m.row("perm.fda")?.detail, "probe read ~/Library/Containers/com.apple.stocks")
+            c.expectEqual(m.row("perm.notifications")?.status, .ready)
+            c.expectEqual(m.requiredMissing, ["account.gitlab"], "overlay recomputes enablement")
+            m.becameHidden()
+        }
+        c.expectEqual(ticker.cancelled, 1)
+        c.expectEqual(plans.fetches, 1, "the 1s ticker never spawns rt; it probes locally")
+    },
+    Check("didBecomeActive refetches the plan; afterAction marks the row checking then refetches") { c in
+        let plans = FakePlans([makePlan(), makePlan(gitlab: .ready), makePlan(gitlab: .ready)])
+        let m = await MainActor.run { ReadinessModel(plans: plans, permissions: FakePermissions(), ticker: FakeTicker()) }
+        await m.load()
+        await MainActor.run { m.didBecomeActive() }
+        try await Task.sleep(nanoseconds: 100_000_000)
+        c.expectEqual(plans.fetches, 2)
+        await m.afterAction(rowId: "account.gitlab")
+        await MainActor.run {
+            c.expectEqual(m.row("account.gitlab")?.status, .ready)
+            c.expect(m.checkingRowIds.isEmpty)
+        }
+        c.expectEqual(plans.fetches, 3)
+    },
+    Check("a failing plan fetch keeps the last rows and records the error") { c in
+        final class Boom: PlanSource, @unchecked Sendable {
+            var n = 0
+            func fetchPlan() async throws -> Plan { n += 1; if n == 1 { return makePlan() }; throw RtClientError.exited(1, stderr: "boom") }
+        }
+        let m = await MainActor.run { ReadinessModel(plans: Boom(), permissions: FakePermissions(), ticker: FakeTicker()) }
+        await m.load()
+        await m.recheckAll()
+        await MainActor.run {
+            c.expectEqual(m.groups.count, 2)
+            c.expect(m.lastError?.contains("boom") == true)
+        }
+    },
+    Check("PermissionRowOverlay maps contract statuses to row statuses") { c in
+        let s = PermissionSnapshot(fda: .init(status: "denied", detail: "EPERM"), notifications: .init(status: "denied"),
+                                   loginItems: .init(status: "notRegistered"))
+        c.expectEqual(PermissionRowOverlay.status(for: "perm.fda", in: s)?.0, .needsYou)
+        c.expectEqual(PermissionRowOverlay.status(for: "perm.notifications", in: s)?.0, .needsYou)
+        c.expectEqual(PermissionRowOverlay.status(for: "perm.login-items", in: s)?.0, .missing)
+        let u = PermissionSnapshot.unknown
+        c.expectEqual(PermissionRowOverlay.status(for: "perm.fda", in: u)?.0, .checking)
+        c.expect(PermissionRowOverlay.status(for: "tool.clt", in: s) == nil)
+        let ok = PermissionSnapshot(fda: .init(status: "granted", detail: ""), notifications: .init(status: "provisional"),
+                                    loginItems: .init(status: "enabled"))
+        c.expectEqual(PermissionRowOverlay.status(for: "perm.login-items", in: ok)?.0, .ready)
+        c.expectEqual(PermissionRowOverlay.status(for: "perm.notifications", in: ok)?.0, .ready)
+        let approval = PermissionSnapshot(fda: .init(status: "granted", detail: ""), notifications: .init(status: "notDetermined"),
+                                          loginItems: .init(status: "requiresApproval"))
+        c.expectEqual(PermissionRowOverlay.status(for: "perm.login-items", in: approval)?.0, .needsYou)
+        c.expectEqual(PermissionRowOverlay.status(for: "perm.notifications", in: approval)?.0, .skipped)
+    },
+    Check("StatusGlyph follows the spec's symbols") { c in
+        c.expectEqual(StatusGlyph.symbol(for: .ready), "checkmark.circle.fill")
+        c.expectEqual(StatusGlyph.symbol(for: .error), "xmark.circle")
+        c.expectEqual(StatusGlyph.symbol(for: .invalid), "xmark.circle")
+        c.expectEqual(StatusGlyph.symbol(for: .needsYou), "exclamationmark.triangle")
+        c.expectEqual(StatusGlyph.symbol(for: .missing), "exclamationmark.triangle")
+        c.expectEqual(StatusGlyph.symbol(for: .skipped), "circle.dotted")
+        c.expectEqual(StatusGlyph.symbol(for: .checking), "progress")
+        c.expectEqual(StatusGlyph.tint(for: .ready), .green)
+        c.expectEqual(StatusGlyph.tint(for: .needsYou), .yellow)
+    },
+]
+```
+Register in `AllChecks.swift` (`+ readinessModelChecks`).
+
+- [ ] **Step 2: Run → compile failure.**
+
+- [ ] **Step 3: Implement**
+
+`rt-tray/Sources-core/Permissions/PermissionSnapshot.swift`:
+```swift
+import Foundation
+
+/// The three permission rows as the app measures them. Wire format is the
+/// contract's `GET /permissions` body.
+public struct PermissionSnapshot: Codable, Equatable, Sendable {
+    public struct FDAState: Codable, Equatable, Sendable {
+        public var status: String   // granted | denied | unknown
+        public var detail: String
+        public init(status: String, detail: String) { self.status = status; self.detail = detail }
+    }
+    public struct NotificationsState: Codable, Equatable, Sendable {
+        public var status: String   // authorized | denied | notDetermined | provisional
+        public init(status: String) { self.status = status }
+    }
+    public struct LoginItemsState: Codable, Equatable, Sendable {
+        public var status: String   // enabled | requiresApproval | notRegistered | notFound
+        public init(status: String) { self.status = status }
+    }
+    public var fda: FDAState
+    public var notifications: NotificationsState
+    public var loginItems: LoginItemsState
+    public init(fda: FDAState, notifications: NotificationsState, loginItems: LoginItemsState) {
+        self.fda = fda; self.notifications = notifications; self.loginItems = loginItems
+    }
+    public static let unknown = PermissionSnapshot(fda: .init(status: "unknown", detail: "not probed yet"),
+                                                   notifications: .init(status: "notDetermined"),
+                                                   loginItems: .init(status: "notRegistered"))
+}
+
+public enum PermissionRowOverlay {
+    public static let fdaRow = "perm.fda"
+    public static let loginItemsRow = "perm.login-items"
+    public static let notificationsRow = "perm.notifications"
+
+    public static func status(for rowId: String, in s: PermissionSnapshot) -> (RowStatus, String)? {
+        switch rowId {
+        case fdaRow:
+            switch s.fda.status {
+            case "granted": return (.ready, s.fda.detail)
+            case "denied":  return (.needsYou, "Not granted")
+            default:        return (.checking, s.fda.detail)
+            }
+        case loginItemsRow:
+            switch s.loginItems.status {
+            case "enabled":          return (.ready, "Enabled")
+            case "requiresApproval": return (.needsYou, "Needs approval in Login Items")
+            case "notFound":         return (.error, "Agent plist not found in the bundle")
+            default:                 return (.missing, "Not registered")
+            }
+        case notificationsRow:
+            switch s.notifications.status {
+            case "authorized", "provisional": return (.ready, "Allowed")
+            case "denied":                    return (.needsYou, "Denied in System Settings")
+            default:                          return (.skipped, "Not decided")
+            }
+        default:
+            return nil
+        }
+    }
+}
+```
+
+`rt-tray/Sources-core/Readiness/StatusGlyph.swift`:
+```swift
+import Foundation
+
+public enum GlyphTint: Equatable, Sendable { case green, red, yellow, grey, none }
+
+public enum StatusGlyph {
+    /// "progress" is the sentinel the view turns into a small ProgressView.
+    public static func symbol(for status: RowStatus) -> String {
+        switch status {
+        case .ready: return "checkmark.circle.fill"
+        case .error, .invalid: return "xmark.circle"
+        case .needsYou, .missing: return "exclamationmark.triangle"
+        case .skipped: return "circle.dotted"
+        case .checking: return "progress"
+        }
+    }
+    public static func tint(for status: RowStatus) -> GlyphTint {
+        switch status {
+        case .ready: return .green
+        case .error, .invalid: return .red
+        case .needsYou, .missing: return .yellow
+        case .skipped: return .grey
+        case .checking: return .none
+        }
+    }
+}
+```
+
+`rt-tray/Sources-core/Readiness/ReadinessModel.swift`:
+```swift
+import Foundation
+import Combine
+
+public protocol PlanSource: Sendable { func fetchPlan() async throws -> Plan }
+public protocol PermissionProbing: Sendable { func snapshot() async -> PermissionSnapshot }
+
+public final class TickerHandle: Sendable {
+    public let cancel: @Sendable () -> Void
+    public init(_ cancel: @escaping @Sendable () -> Void) { self.cancel = cancel }
+}
+public protocol TickerScheduling: Sendable {
+    func schedule(every seconds: TimeInterval, _ tick: @escaping @Sendable () -> Void) -> TickerHandle
+}
+
+/// The checklist's view state. Rows come only from rt; the three permission
+/// rows are overlaid from the app's own probe (the same probe rt folds in
+/// via GET /permissions), so the 1 s visible-timer never spawns rt.
+@MainActor
+public final class ReadinessModel: ObservableObject {
+    @Published public private(set) var groups: [PlanGroup] = []
+    @Published public private(set) var team: TeamInfo?
+    @Published public private(set) var canInstall = false
+    @Published public private(set) var requiredMissing: [String] = []
+    @Published public private(set) var isLoading = false
+    @Published public private(set) var lastError: String?
+    @Published public private(set) var checkingRowIds: Set<String> = []
+
+    public static let permissionTickSeconds: TimeInterval = 1
+
+    private let plans: PlanSource
+    private let permissions: PermissionProbing
+    private let ticker: TickerScheduling
+    private var tick: TickerHandle?
+    private var lastSnapshot = PermissionSnapshot.unknown
+
+    public init(plans: PlanSource, permissions: PermissionProbing, ticker: TickerScheduling) {
+        self.plans = plans; self.permissions = permissions; self.ticker = ticker
+    }
+
+    public var allRows: [PlanRow] { groups.flatMap(\.rows) }
+    public func row(_ id: String) -> PlanRow? { allRows.first { $0.id == id } }
+
+    /// Every required row ready, at least one optional row not ready.
+    public var limitedModeAvailable: Bool {
+        canInstall && allRows.contains { !$0.required && $0.status != .ready }
+    }
+
+    public func load() async { await fetch() }
+    public func recheckAll() async { await fetch() }
+
+    public func afterAction(rowId: String) async {
+        checkingRowIds.insert(rowId)
+        await fetch()
+        checkingRowIds.remove(rowId)
+    }
+
+    public func becameVisible() {
+        tick?.cancel()
+        tick = ticker.schedule(every: Self.permissionTickSeconds) { [weak self] in
+            Task { @MainActor [weak self] in await self?.probePermissions() }
+        }
+        Task { await probePermissions() }
+    }
+
+    public func becameHidden() {
+        tick?.cancel()
+        tick = nil
+    }
+
+    public func didBecomeActive() {
+        Task { await probePermissions(); await fetch() }
+    }
+
+    private func fetch() async {
+        isLoading = true
+        defer { isLoading = false }
+        do {
+            let plan = try await plans.fetchPlan()
+            team = plan.team
+            groups = plan.groups
+            lastError = nil
+            overlay(lastSnapshot)
+        } catch {
+            lastError = String(describing: error)
+        }
+    }
+
+    private func probePermissions() async {
+        let snap = await permissions.snapshot()
+        lastSnapshot = snap
+        overlay(snap)
+    }
+
+    private func overlay(_ snap: PermissionSnapshot) {
+        for g in groups.indices {
+            for r in groups[g].rows.indices where groups[g].rows[r].kind == .permission {
+                if let (status, detail) = PermissionRowOverlay.status(for: groups[g].rows[r].id, in: snap) {
+                    groups[g].rows[r].status = status
+                    groups[g].rows[r].detail = detail
+                }
+            }
+        }
+        requiredMissing = allRows.filter { $0.required && $0.status != .ready }.map(\.id)
+        canInstall = requiredMissing.isEmpty
+    }
+}
+```
+
+- [ ] **Step 4: Run** `swift run mattstack-checks` → all pass (`checks: 18 passed`).
+
+- [ ] **Step 5: Commit**
+```bash
+git add rt-tray/Sources-core rt-tray/Tests
+git commit -m "MAT-383: ReadinessModel — plan rows, enablement, recheck policy, local permission overlay
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 6: PermissionsService — FDA probe, Notifications, Login Items, deep links, Reset & re-request
+
+**Files:**
+- Create: `rt-tray/Sources-core/Permissions/FDAProbe.swift`, `rt-tray/Sources-core/Permissions/SystemSettingsLinks.swift`, `rt-tray/Sources-core/Services/CommandRunner.swift`
+- Create: `rt-tray/Sources/Permissions/PermissionsService.swift`
+- Create: `rt-tray/Tests/MattstackCoreChecks/PermissionsChecks.swift`; modify `AllChecks.swift`
+
+**Interfaces:**
+- Produces (Core):
+  - `public enum FDAProbeOutcome { readable, permissionDenied, missing, otherError(Int32) }`
+  - `public enum FDAProbe { static let probePaths: [String] (tilde-relative); static func evaluate(home: String, open: (String) -> FDAProbeOutcome) -> PermissionSnapshot.FDAState }`
+  - `public enum SystemSettingsLinks { static let fullDiskAccess: URL; static let notifications(bundleId:) -> URL; static let keyboard: URL; static let loginItems: URL }`
+  - `public protocol CommandRunner: Sendable { func run(_ executable: String, _ args: [String]) async -> CommandOutcome }`, `public struct CommandOutcome: Equatable { exitCode: Int32; stdout: String; stderr: String; var ok: Bool }`, `public final class RecordingCommandRunner: CommandRunner` (`calls: [(String,[String])]`, `responses: [String: CommandOutcome]` keyed by executable basename), `public struct SystemCommandRunner: CommandRunner` (the only place that spawns arbitrary binaries; **never constructed in checks**).
+  - `public enum TCCReset { static func arguments(bundleId: String) -> (String, [String]) }` → `("/usr/bin/tccutil", ["reset", "All", bundleId])`
+- Produces (app): `final class PermissionsService: PermissionProbing, PermissionsProviding` — `init(bundleId: String, agentStatuses: @escaping @Sendable () -> [SMAppService.Status], runner: CommandRunner)`; `static func combinedLoginItems(_ statuses: [SMAppService.Status]) -> String` (worst status wins: notFound > requiresApproval > notRegistered > enabled; empty → notRegistered); `func snapshot() async -> PermissionSnapshot`; `func request(_ which: String) async -> Bool` (`"notifications"` → `requestAuthorization`; anything else → false); `func openSettings(_ target: String)` (`fda`/`login-items`/`notifications`/`keyboard`); `func resetAndReRequest() async -> Bool` (tccutil via runner, then `request("notifications")` and a relaunch hint); `var fdaNeedsRelaunch: Bool` (true once a probe flipped denied→granted in this process — macOS applies FDA at next launch).
+
+- [ ] **Step 1: Failing checks**
+
+`rt-tray/Tests/MattstackCoreChecks/PermissionsChecks.swift`:
+```swift
+import Foundation
+import MattstackCore
+
+let permissionsChecks: [Check] = [
+    Check("FDAProbe: first readable path → granted with the path in detail") { c in
+        let s = FDAProbe.evaluate(home: "/Users/u") { path in path.hasSuffix("com.apple.stocks") ? .readable : .missing }
+        c.expectEqual(s.status, "granted")
+        c.expect(s.detail.contains("com.apple.stocks"))
+    },
+    Check("FDAProbe: EPERM/EACCES on any probe path → denied; all missing → unknown") { c in
+        let denied = FDAProbe.evaluate(home: "/Users/u") { _ in .permissionDenied }
+        c.expectEqual(denied.status, "denied")
+        let unknown = FDAProbe.evaluate(home: "/Users/u") { _ in .missing }
+        c.expectEqual(unknown.status, "unknown")
+        // a missing first path must fall through to the MacPaw list
+        let second = FDAProbe.evaluate(home: "/Users/u") { path in path.hasSuffix("CloudTabs.db") ? .permissionDenied : .missing }
+        c.expectEqual(second.status, "denied")
+    },
+    Check("FDAProbe paths are expanded against the given home, not the process's") { c in
+        var seen: [String] = []
+        _ = FDAProbe.evaluate(home: "/Users/zed") { seen.append($0); return .missing }
+        c.expect(seen.allSatisfy { $0.hasPrefix("/Users/zed/") || $0.hasPrefix("/Library/") })
+        c.expectEqual(seen.first, "/Users/zed/Library/Containers/com.apple.stocks")
+    },
+    Check("SystemSettingsLinks are the documented deep links") { c in
+        c.expectEqual(SystemSettingsLinks.fullDiskAccess.absoluteString, "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles")
+        c.expectEqual(SystemSettingsLinks.notifications(bundleId: "com.mattstack.app").absoluteString,
+                      "x-apple.systempreferences:com.apple.Notifications-Settings.extension?id=com.mattstack.app")
+        c.expectEqual(SystemSettingsLinks.loginItems.absoluteString, "x-apple.systempreferences:com.apple.LoginItems-Settings.extension")
+        c.expectEqual(SystemSettingsLinks.keyboard.absoluteString, "x-apple.systempreferences:com.apple.Keyboard-Settings.extension?Shortcuts")
+    },
+    Check("TCCReset builds tccutil reset All <bundle id>") { c in
+        let (exe, args) = TCCReset.arguments(bundleId: "com.mattstack.app.dev")
+        c.expect(exe.hasPrefix("/usr/bin/") && exe.hasSuffix("util"), "the reset tool lives in /usr/bin (name kept out of check sources by the source guard)")
+        c.expectEqual(args, ["reset", "All", "com.mattstack.app.dev"])
+    },
+    Check("RecordingCommandRunner records and answers by basename") { c in
+        let r = RecordingCommandRunner()
+        r.responses["fake-tool"] = CommandOutcome(exitCode: 0, stdout: "", stderr: "")
+        let out = await r.run("/usr/bin/fake-tool", ["reset", "All", "x"])
+        c.expect(out.ok)
+        c.expectEqual(r.calls.count, 1)
+        c.expectEqual(r.calls[0].args, ["reset", "All", "x"])
+        let unknown = await r.run("/bin/nothing", [])
+        c.expectEqual(unknown.exitCode, 127)
+    },
+]
+```
+
+- [ ] **Step 2: Run → compile failure.**
+
+- [ ] **Step 3: Implement Core**
+
+`rt-tray/Sources-core/Services/CommandRunner.swift`:
+```swift
+import Foundation
+
+public struct CommandOutcome: Equatable, Sendable {
+    public let exitCode: Int32
+    public let stdout: String
+    public let stderr: String
+    public var ok: Bool { exitCode == 0 }
+    public init(exitCode: Int32, stdout: String, stderr: String) {
+        self.exitCode = exitCode; self.stdout = stdout; self.stderr = stderr
+    }
+}
+
+/// The one seam every non-rt subprocess goes through (launchctl, tccutil,
+/// the privileged helper, deck). Checks use RecordingCommandRunner; nothing
+/// under Tests/ may construct SystemCommandRunner.
+public protocol CommandRunner: Sendable {
+    func run(_ executable: String, _ args: [String]) async -> CommandOutcome
+}
+
+public final class RecordingCommandRunner: CommandRunner, @unchecked Sendable {
+    public struct Call: Equatable, Sendable { public let executable: String; public let args: [String] }
+    public private(set) var calls: [Call] = []
+    public var responses: [String: CommandOutcome] = [:]
+    private let lock = NSLock()
+    public init() {}
+    public func run(_ executable: String, _ args: [String]) async -> CommandOutcome {
+        lock.lock(); defer { lock.unlock() }
+        calls.append(Call(executable: executable, args: args))
+        let key = (executable as NSString).lastPathComponent
+        return responses[key] ?? CommandOutcome(exitCode: 127, stdout: "", stderr: "no canned response for \(key)")
+    }
+}
+
+public struct SystemCommandRunner: CommandRunner {
+    public init() {}
+    public func run(_ executable: String, _ args: [String]) async -> CommandOutcome {
+        await withCheckedContinuation { cont in
+            let p = Process()
+            p.executableURL = URL(fileURLWithPath: executable)
+            p.arguments = args
+            let out = Pipe(), err = Pipe()
+            p.standardOutput = out; p.standardError = err
+            p.terminationHandler = { proc in
+                let o = String(decoding: out.fileHandleForReading.readDataToEndOfFile(), as: UTF8.self)
+                let e = String(decoding: err.fileHandleForReading.readDataToEndOfFile(), as: UTF8.self)
+                cont.resume(returning: CommandOutcome(exitCode: proc.terminationStatus, stdout: o, stderr: e))
+            }
+            do { try p.run() } catch {
+                cont.resume(returning: CommandOutcome(exitCode: 127, stdout: "", stderr: String(describing: error)))
+            }
+        }
+    }
+}
+
+public enum TCCReset {
+    public static func arguments(bundleId: String) -> (String, [String]) {
+        ("/usr/bin/tccutil", ["reset", "All", bundleId])
+    }
+}
+```
+
+`rt-tray/Sources-core/Permissions/FDAProbe.swift`:
+```swift
+import Foundation
+
+// Probe-path list adapted from inket/FullDiskAccess and MacPaw/PermissionsKit
+// (both MIT). Reading any of these succeeds only with Full Disk Access; the
+// attempt itself adds the app to the FDA pane so the user only flips a switch.
+
+public enum FDAProbeOutcome: Equatable, Sendable { case readable, permissionDenied, missing, otherError(Int32) }
+
+public enum FDAProbe {
+    public static let probePaths: [String] = [
+        "~/Library/Containers/com.apple.stocks",
+        "~/Library/Safari/CloudTabs.db",
+        "~/Library/Safari/Bookmarks.plist",
+        "~/Library/Application Support/com.apple.TCC/TCC.db",
+        "/Library/Preferences/com.apple.TimeMachine.plist",
+    ]
+
+    public static func expanded(_ path: String, home: String) -> String {
+        path.hasPrefix("~/") ? home + String(path.dropFirst(1)) : path
+    }
+
+    public static func evaluate(home: String, open: (String) -> FDAProbeOutcome) -> PermissionSnapshot.FDAState {
+        for raw in probePaths {
+            let path = expanded(raw, home: home)
+            switch open(path) {
+            case .readable:         return .init(status: "granted", detail: "probe read \(raw)")
+            case .permissionDenied: return .init(status: "denied", detail: "probe read \(raw) refused")
+            case .missing, .otherError: continue
+            }
+        }
+        return .init(status: "unknown", detail: "no probe path exists on this Mac")
+    }
+
+    /// The real open(2) attempt; lives here so the app target stays free of errno handling.
+    public static func systemOpen(_ path: String) -> FDAProbeOutcome {
+        let fd = Darwin.open(path, O_RDONLY)
+        if fd >= 0 { Darwin.close(fd); return .readable }
+        switch errno {
+        case EPERM, EACCES: return .permissionDenied
+        case ENOENT: return .missing
+        default: return .otherError(errno)
+        }
+    }
+}
+```
+
+`rt-tray/Sources-core/Permissions/SystemSettingsLinks.swift`:
+```swift
+import Foundation
+
+public enum SystemSettingsLinks {
+    public static let fullDiskAccess = URL(string: "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles")!
+    public static let loginItems = URL(string: "x-apple.systempreferences:com.apple.LoginItems-Settings.extension")!
+    public static let keyboard = URL(string: "x-apple.systempreferences:com.apple.Keyboard-Settings.extension?Shortcuts")!
+    public static func notifications(bundleId: String) -> URL {
+        URL(string: "x-apple.systempreferences:com.apple.Notifications-Settings.extension?id=\(bundleId)")!
+    }
+    public static func url(forTarget target: String, bundleId: String) -> URL? {
+        switch target {
+        case "fda": return fullDiskAccess
+        case "login-items": return loginItems
+        case "notifications": return notifications(bundleId: bundleId)
+        case "keyboard": return keyboard
+        default: return nil
+        }
+    }
+}
+```
+
+- [ ] **Step 4: Run checks → pass.** `swift run mattstack-checks`.
+
+- [ ] **Step 5: Implement the app-side service**
+
+`rt-tray/Sources/Permissions/PermissionsService.swift`:
+```swift
+import AppKit
+import UserNotifications
+import ServiceManagement
+import MattstackCore
+
+/// App-side truth for the three permission rows (spec §9). Pure mapping is
+/// in MattstackCore; this class only touches the frameworks.
+final class PermissionsService: PermissionProbing, PermissionsProviding, @unchecked Sendable {
+    private let bundleId: String
+    private let agentStatuses: @Sendable () -> [SMAppService.Status]
+    private let runner: CommandRunner
+    private let home = NSHomeDirectory()
+    private var lastFDA = "unknown"
+    private(set) var fdaNeedsRelaunch = false
+
+    init(bundleId: String, agentStatuses: @escaping @Sendable () -> [SMAppService.Status], runner: CommandRunner) {
+        self.bundleId = bundleId
+        self.agentStatuses = agentStatuses
+        self.runner = runner
+    }
+
+    func snapshot() async -> PermissionSnapshot {
+        let fda = FDAProbe.evaluate(home: home, open: FDAProbe.systemOpen)
+        if lastFDA == "denied", fda.status == "granted" { fdaNeedsRelaunch = true }
+        lastFDA = fda.status
+        let settings = await UNUserNotificationCenter.current().notificationSettings()
+        let notif: String
+        switch settings.authorizationStatus {
+        case .authorized: notif = "authorized"
+        case .denied: notif = "denied"
+        case .provisional: notif = "provisional"
+        default: notif = "notDetermined"
+        }
+        return PermissionSnapshot(fda: fda,
+                                  notifications: .init(status: notif),
+                                  loginItems: .init(status: Self.combinedLoginItems(agentStatuses())))
+    }
+
+    /// One switch covers every agent: the worst status wins so the row never
+    /// says "enabled" while one agent still needs approval.
+    static func combinedLoginItems(_ statuses: [SMAppService.Status]) -> String {
+        if statuses.isEmpty { return "notRegistered" }
+        if statuses.contains(.notFound) { return "notFound" }
+        if statuses.contains(.requiresApproval) { return "requiresApproval" }
+        if statuses.contains(.notRegistered) { return "notRegistered" }
+        return "enabled"
+    }
+
+    func request(_ which: String) async -> Bool {
+        guard which == "notifications" else { return false }
+        return (try? await UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .sound, .badge])) ?? false
+    }
+
+    @MainActor
+    func openSettings(_ target: String) {
+        if target == "login-items" { SMAppService.openSystemSettingsLoginItems(); return }
+        if let url = SystemSettingsLinks.url(forTarget: target, bundleId: bundleId) { NSWorkspace.shared.open(url) }
+    }
+
+    func resetAndReRequest() async -> Bool {
+        let (exe, args) = TCCReset.arguments(bundleId: bundleId)
+        let out = await runner.run(exe, args)
+        if !out.ok { TrayLog.warn("tccutil reset failed", ["stderr": out.stderr]) }
+        _ = await request("notifications")
+        return out.ok
+    }
+}
+```
+(`PermissionsProviding` is declared in Task 9's `TrayRoutes`; to keep this task compiling on its own, declare it now in Core — `rt-tray/Sources-core/Routes/Providers.swift`:)
+```swift
+import Foundation
+
+public protocol PermissionsProviding: Sendable {
+    func snapshot() async -> PermissionSnapshot
+    func request(_ which: String) async -> Bool
+}
+```
+
+- [ ] **Step 6: Build** `swift build 2>&1 | tail -1` → `Build complete!`; checks pass.
+
+- [ ] **Step 7: Commit**
+```bash
+git add rt-tray/Sources-core rt-tray/Sources/Permissions rt-tray/Tests
+git commit -m "MAT-383: PermissionsService — FDA probe, notifications, login items, deep links, tccutil reset seam
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 7: ServicesRegistrar — N plists, register-all, statuses, version-change restart, source guard
+
+**Files:**
+- Create: `rt-tray/Sources-core/Services/ServicePlists.swift`, `rt-tray/Sources-core/Services/VersionChangeDetector.swift`, `rt-tray/Sources-core/Services/ServiceModels.swift`
+- Create: `rt-tray/Sources/Services/ServicesRegistrar.swift`
+- Create: `rt-tray/Tests/MattstackCoreChecks/ServicesChecks.swift`, `rt-tray/Tests/MattstackCoreChecks/SourceGuardChecks.swift`; modify `AllChecks.swift`
+
+**Interfaces:**
+- Produces (Core):
+  - `public struct AgentPlist: Equatable { label: String; fileName: String }`; `public enum ServicePlistScanner { static func scan(directory: String, list: (String) -> [String], readLabel: (String) -> String?) -> [AgentPlist] }` (sorted by fileName; skips files whose Label is unreadable)
+  - `public enum Kickstart { static func arguments(label: String, uid: uid_t) -> (String, [String]) }` → `("/bin/launchctl", ["kickstart", "-k", "gui/<uid>/<label>"])`
+  - `public enum DeckRestart { static func arguments(deckPath: String) -> (String, [String]) }` → `(deckPath, ["restart", "--managed"])`
+  - `public protocol KeyValueStore { func string(forKey:) -> String?; func set(_ value: String?, forKey:) }` + `public final class MemoryKeyValueStore`
+  - `public enum VersionChange: Equatable { firstLaunch, unchanged, changed(from: String, to: String) }`; `public enum VersionChangeDetector { static let key = "MSLastLaunchedVersion"; static func evaluate(current: String, store: KeyValueStore) -> VersionChange; static func record(current: String, store: KeyValueStore) }`
+  - `public struct ServiceStatusEntry: Codable, Equatable { label: String; status: String }`, `public struct ServiceRegisterResult: Codable, Equatable { plist: String; ok: Bool; status: String; error: String? }`
+  - `public protocol ServicesProviding: Sendable { func statuses() async -> [ServiceStatusEntry]; func register(plists: [String]) async -> [ServiceRegisterResult]; func unregister(plists: [String]) async -> [ServiceRegisterResult]; func restart(label: String) async -> Bool }` — `unregister` serves L1's `app-unregister-services` need (`rt uninstall` → `services.unregister`), via `SMAppService.unregister()`; a plist whose `BundleProgram` does not exist in the bundle registers as `notFound` and is reported `ok:false, status:"notFound"` — the app never hides it; L1 decides (it requests the deck plist only when deck is bundled).
+- Produces (app): `final class ServicesRegistrar: ServicesProviding` — `init(bundlePath: String, runner: CommandRunner, uid: uid_t = getuid())`; `var agents: [AgentPlist]`; `func registerAll() -> [ServiceRegisterResult]`; `func smStatuses() -> [SMAppService.Status]`; `func restartAll() async`; `func handleVersionChange(current: String, store: KeyValueStore) async -> VersionChange` (changed → registerAll + restartAll + deck restart + record).
+
+- [ ] **Step 1: Failing checks**
+
+`rt-tray/Tests/MattstackCoreChecks/ServicesChecks.swift`:
+```swift
+import Foundation
+import MattstackCore
+
+let servicesChecks: [Check] = [
+    Check("ServicePlistScanner lists every plist in Contents/Library/LaunchAgents with its Label") { c in
+        let dir = "/App.app/Contents/Library/LaunchAgents"
+        let agents = ServicePlistScanner.scan(directory: dir,
+            list: { _ in ["com.mattstack.deck.plist", "com.mattstack.daemon.plist", "README.txt", "broken.plist"] },
+            readLabel: { path in
+                switch (path as NSString).lastPathComponent {
+                case "com.mattstack.daemon.plist": return "com.mattstack.daemon"
+                case "com.mattstack.deck.plist": return "com.mattstack.deck"
+                default: return nil
+                }
+            })
+        c.expectEqual(agents, [AgentPlist(label: "com.mattstack.daemon", fileName: "com.mattstack.daemon.plist"),
+                               AgentPlist(label: "com.mattstack.deck", fileName: "com.mattstack.deck.plist")])
+    },
+    Check("Kickstart and DeckRestart build the exact argv") { c in
+        let (exe, args) = Kickstart.arguments(label: "com.mattstack.daemon.dev", uid: 501)
+        c.expect(exe.hasPrefix("/bin/") && exe.hasSuffix("ctl"), "launchd's control tool, by absolute path (name kept out of check sources by the source guard)")
+        c.expectEqual(args, ["kickstart", "-k", "gui/501/com.mattstack.daemon.dev"])
+        let (d, dargs) = DeckRestart.arguments(deckPath: "/Applications/mattstack.app/Contents/Helpers/deck")
+        c.expectEqual(d, "/Applications/mattstack.app/Contents/Helpers/deck")
+        c.expectEqual(dargs, ["restart", "--managed"])
+    },
+    Check("VersionChangeDetector: first launch, unchanged, changed; record persists") { c in
+        let store = MemoryKeyValueStore()
+        c.expectEqual(VersionChangeDetector.evaluate(current: "2.8.0", store: store), .firstLaunch)
+        VersionChangeDetector.record(current: "2.8.0", store: store)
+        c.expectEqual(VersionChangeDetector.evaluate(current: "2.8.0", store: store), .unchanged)
+        c.expectEqual(VersionChangeDetector.evaluate(current: "2.9.0", store: store), .changed(from: "2.8.0", to: "2.9.0"))
+        c.expectEqual(store.string(forKey: VersionChangeDetector.key), "2.8.0")
+    },
+    Check("ServiceStatusEntry / ServiceRegisterResult encode per contract") { c in
+        let data = try JSONEncoder().encode([ServiceStatusEntry(label: "com.mattstack.daemon", status: "enabled")])
+        c.expect(String(decoding: data, as: UTF8.self).contains("\"status\":\"enabled\""))
+        let r = ServiceRegisterResult(plist: "com.mattstack.deck.plist", ok: false, status: "notFound", error: "plist missing")
+        let j = String(decoding: try JSONEncoder().encode(r), as: UTF8.self)
+        c.expect(j.contains("\"ok\":false"))
+    },
+]
+```
+
+`rt-tray/Tests/MattstackCoreChecks/SourceGuardChecks.swift` — the T5/T6 guard:
+```swift
+import Foundation
+import MattstackCore
+
+/// No check file may name a process we must never spawn from a test, and
+/// none may construct the real runner. Paths are relative to this file.
+let sourceGuardChecks: [Check] = [
+    Check("checks never name launchctl/pkill/tccutil/osascript/open(1) or SystemCommandRunner") { c in
+        let here = URL(fileURLWithPath: #filePath).deletingLastPathComponent()
+        let files = try FileManager.default.contentsOfDirectory(atPath: here.path).filter { $0.hasSuffix(".swift") && $0 != "SourceGuardChecks.swift" }
+        let forbidden = ["/bin/launchctl", "launchctl ", "pkill", "tccutil", "osascript", "/usr/bin/open", "SystemCommandRunner("]
+        for f in files {
+            let text = try String(contentsOfFile: here.appendingPathComponent(f).path, encoding: .utf8)
+            for needle in forbidden where text.contains(needle) {
+                c.fail("\(f) mentions forbidden '\(needle)'")
+            }
+        }
+        c.expect(files.count >= 5)
+    },
+]
+```
+(Check files assert on `hasPrefix`/`hasSuffix` of those executables rather than spelling the names, so the guard above stays clean.)
+
+Register `+ servicesChecks + sourceGuardChecks`.
+
+- [ ] **Step 2: Run → compile failure.**
+
+- [ ] **Step 3: Implement Core**
+
+`rt-tray/Sources-core/Services/ServicePlists.swift`:
+```swift
+import Foundation
+
+public struct AgentPlist: Equatable, Sendable {
+    public let label: String
+    public let fileName: String
+    public init(label: String, fileName: String) { self.label = label; self.fileName = fileName }
+}
+
+public enum ServicePlistScanner {
+    public static func scan(directory: String, list: (String) -> [String], readLabel: (String) -> String?) -> [AgentPlist] {
+        list(directory).sorted().compactMap { file in
+            guard file.hasSuffix(".plist"), let label = readLabel(directory + "/" + file) else { return nil }
+            return AgentPlist(label: label, fileName: file)
+        }
+    }
+    public static func systemList(_ dir: String) -> [String] {
+        (try? FileManager.default.contentsOfDirectory(atPath: dir)) ?? []
+    }
+    public static func systemReadLabel(_ path: String) -> String? {
+        guard let data = FileManager.default.contents(atPath: path),
+              let dict = try? PropertyListSerialization.propertyList(from: data, format: nil) as? [String: Any]
+        else { return nil }
+        return dict["Label"] as? String
+    }
+}
+
+public enum Kickstart {
+    public static func arguments(label: String, uid: uid_t) -> (String, [String]) {
+        ("/bin/launchctl", ["kickstart", "-k", "gui/\(uid)/\(label)"])
+    }
+}
+
+public enum DeckRestart {
+    public static func arguments(deckPath: String) -> (String, [String]) { (deckPath, ["restart", "--managed"]) }
+}
+```
+
+`rt-tray/Sources-core/Services/VersionChangeDetector.swift`:
+```swift
+import Foundation
+
+public protocol KeyValueStore: Sendable {
+    func string(forKey key: String) -> String?
+    func set(_ value: String?, forKey key: String)
+}
+
+public final class MemoryKeyValueStore: KeyValueStore, @unchecked Sendable {
+    private var dict: [String: String] = [:]
+    public init() {}
+    public func string(forKey key: String) -> String? { dict[key] }
+    public func set(_ value: String?, forKey key: String) { dict[key] = value }
+}
+
+public enum VersionChange: Equatable, Sendable {
+    case firstLaunch
+    case unchanged
+    case changed(from: String, to: String)
+}
+
+/// Sparkle swaps the bundle but launchd keeps running the old inodes; the
+/// app must notice its own version changed and restart the agents.
+public enum VersionChangeDetector {
+    public static let key = "MSLastLaunchedVersion"
+    public static func evaluate(current: String, store: KeyValueStore) -> VersionChange {
+        guard let last = store.string(forKey: key) else { return .firstLaunch }
+        return last == current ? .unchanged : .changed(from: last, to: current)
+    }
+    public static func record(current: String, store: KeyValueStore) { store.set(current, forKey: key) }
+}
+```
+
+`rt-tray/Sources-core/Services/ServiceModels.swift`:
+```swift
+import Foundation
+
+public struct ServiceStatusEntry: Codable, Equatable, Sendable {
+    public var label: String
+    public var status: String
+    public init(label: String, status: String) { self.label = label; self.status = status }
+}
+
+public struct ServiceRegisterResult: Codable, Equatable, Sendable {
+    public var plist: String
+    public var ok: Bool
+    public var status: String
+    public var error: String?
+    public init(plist: String, ok: Bool, status: String, error: String? = nil) {
+        self.plist = plist; self.ok = ok; self.status = status; self.error = error
+    }
+}
+
+public protocol ServicesProviding: Sendable {
+    func statuses() async -> [ServiceStatusEntry]
+    func register(plists: [String]) async -> [ServiceRegisterResult]
+    func unregister(plists: [String]) async -> [ServiceRegisterResult]
+    func restart(label: String) async -> Bool
+}
+```
+
+- [ ] **Step 4: Run checks → pass.**
+
+- [ ] **Step 5: Implement the app-side registrar**
+
+`rt-tray/Sources/Services/ServicesRegistrar.swift`:
+```swift
+import Foundation
+import ServiceManagement
+import MattstackCore
+
+/// Registers every agent plist the bundle ships (spec §8/§9) and restarts
+/// them when the app's version changes. Spawns only through CommandRunner.
+final class ServicesRegistrar: ServicesProviding, @unchecked Sendable {
+    let bundlePath: String
+    let agents: [AgentPlist]
+    private let runner: CommandRunner
+    private let uid: uid_t
+
+    init(bundlePath: String, runner: CommandRunner, uid: uid_t = getuid()) {
+        self.bundlePath = bundlePath
+        self.runner = runner
+        self.uid = uid
+        let dir = bundlePath + "/Contents/Library/LaunchAgents"
+        agents = ServicePlistScanner.scan(directory: dir, list: ServicePlistScanner.systemList,
+                                          readLabel: ServicePlistScanner.systemReadLabel)
+    }
+
+    private func service(_ plist: AgentPlist) -> SMAppService { SMAppService.agent(plistName: plist.fileName) }
+
+    func smStatuses() -> [SMAppService.Status] { agents.map { service($0).status } }
+
+    @discardableResult
+    func registerAll() -> [ServiceRegisterResult] { registerSync(plists: agents.map(\.fileName)) }
+
+    private func registerSync(plists: [String]) -> [ServiceRegisterResult] {
+        plists.map { name in
+            guard let plist = agents.first(where: { $0.fileName == name }) else {
+                return ServiceRegisterResult(plist: name, ok: false, status: "notFound", error: "not shipped in this bundle")
+            }
+            let svc = service(plist)
+            do {
+                try svc.register()
+                TrayLog.info("agent registered", ["label": plist.label, "status": TrayServer.statusName(svc.status)])
+                return ServiceRegisterResult(plist: name, ok: true, status: TrayServer.statusName(svc.status))
+            } catch {
+                let already = (error as NSError).code == kSMErrorAlreadyRegistered
+                if !already { TrayLog.error("agent register failed", ["label": plist.label, "err": String(describing: error)]) }
+                return ServiceRegisterResult(plist: name, ok: already, status: TrayServer.statusName(svc.status),
+                                             error: already ? nil : String(describing: error))
+            }
+        }
+    }
+
+    func statuses() async -> [ServiceStatusEntry] {
+        agents.map { ServiceStatusEntry(label: $0.label, status: TrayServer.statusName(service($0).status)) }
+    }
+
+    func register(plists: [String]) async -> [ServiceRegisterResult] {
+        await MainActor.run { registerSync(plists: plists) }
+    }
+
+    func unregister(plists: [String]) async -> [ServiceRegisterResult] {
+        await MainActor.run {
+            plists.map { name in
+                guard let plist = agents.first(where: { $0.fileName == name }) else {
+                    return ServiceRegisterResult(plist: name, ok: false, status: "notFound", error: "not shipped in this bundle")
+                }
+                let svc = service(plist)
+                do {
+                    try svc.unregister()
+                    TrayLog.info("agent unregistered", ["label": plist.label])
+                    return ServiceRegisterResult(plist: name, ok: true, status: TrayServer.statusName(svc.status))
+                } catch {
+                    let gone = svc.status == .notRegistered
+                    if !gone { TrayLog.error("agent unregister failed", ["label": plist.label, "err": String(describing: error)]) }
+                    return ServiceRegisterResult(plist: name, ok: gone, status: TrayServer.statusName(svc.status),
+                                                 error: gone ? nil : String(describing: error))
+                }
+            }
+        }
+    }
+
+    func restart(label: String) async -> Bool {
+        let (exe, args) = Kickstart.arguments(label: label, uid: uid)
+        let out = await runner.run(exe, args)
+        if !out.ok { TrayLog.warn("kickstart failed", ["label": label, "stderr": out.stderr]) }
+        return out.ok
+    }
+
+    func restartAll() async {
+        for agent in agents { _ = await restart(label: agent.label) }
+        let deck = bundlePath + "/Contents/Helpers/deck"
+        guard FileManager.default.isExecutableFile(atPath: deck) else {
+            TrayLog.info("deck helper not bundled; skipping managed-app restart")
+            return
+        }
+        let (exe, args) = DeckRestart.arguments(deckPath: deck)
+        let out = await runner.run(exe, args)
+        if !out.ok { TrayLog.warn("deck restart --managed failed", ["stderr": out.stderr]) }
+    }
+
+    /// Called once per launch. On a version change: re-register (idempotent),
+    /// kickstart every agent, ask deck to restart its managed apps.
+    func handleVersionChange(current: String, store: KeyValueStore) async -> VersionChange {
+        let change = VersionChangeDetector.evaluate(current: current, store: store)
+        if case .changed(let from, let to) = change {
+            TrayLog.info("app version changed; restarting agents", ["from": from, "to": to])
+            _ = await MainActor.run { registerAll() }
+            await restartAll()
+        }
+        VersionChangeDetector.record(current: current, store: store)
+        return change
+    }
+}
+
+extension UserDefaults: KeyValueStore {}
+```
+(`UserDefaults.string(forKey:)` and `set(_:forKey:)` already match the protocol; `@retroactive` conformance warning is acceptable under Swift 5 mode — if the compiler insists, write `extension UserDefaults: @retroactive KeyValueStore {}`.)
+
+- [ ] **Step 6: `swift build` → Build complete; checks pass. Commit**
+```bash
+git add rt-tray/Sources-core rt-tray/Sources/Services rt-tray/Tests
+git commit -m "MAT-383: ServicesRegistrar — N agent plists, register-all, version-change kickstart, command seam + source guard
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 8: PrivilegedInstaller — one admin prompt running the bundled proxy-install helper
+
+**Files:**
+- Create: `rt-tray/Sources-core/Needs/NeedModels.swift`
+- Create: `rt-tray/Sources/Services/PrivilegedInstaller.swift`
+- Create: `rt-tray/Tests/MattstackCoreChecks/NeedModelsChecks.swift`; modify `AllChecks.swift`
+
+**Interfaces:**
+- Produces (Core): `public struct NeedResult: Codable, Equatable { ok: Bool; detail: String }`; `public protocol PrivilegedInstalling: Sendable { func proxyInstall() async -> NeedResult; func proxyRemove() async -> NeedResult }` (`proxyRemove` serves L1's `app-privileged {op:"proxy-remove"}` need from `rt uninstall`; helper arg `remove`); `public enum ProxyHelper { static let relativePath = "Contents/Helpers/mattstack-proxy-install"; static func path(bundlePath:) -> String; static let promptText = "mattstack needs administrator access once to install the local HTTPS proxy (portless) for the board and deck." }`; `public protocol PrivilegeEscalator: Sendable { func runAsAdmin(executable: String, args: [String], prompt: String) async -> CommandOutcome }`
+- Produces (app): `final class PrivilegedInstaller: PrivilegedInstalling` — `init(bundlePath: String, escalator: PrivilegeEscalator, fileExists: @escaping (String) -> Bool = FileManager.default.isExecutableFile(atPath:))`; `struct AuthorizationServicesEscalator: PrivilegeEscalator` (the real admin prompt).
+
+- [ ] **Step 1: Failing checks**
+
+`rt-tray/Tests/MattstackCoreChecks/NeedModelsChecks.swift`:
+```swift
+import Foundation
+import MattstackCore
+
+let needModelsChecks: [Check] = [
+    Check("ProxyHelper path and prompt") { c in
+        c.expectEqual(ProxyHelper.path(bundlePath: "/Applications/mattstack.app"),
+                      "/Applications/mattstack.app/Contents/Helpers/mattstack-proxy-install")
+        c.expect(ProxyHelper.promptText.contains("administrator"))
+    },
+    Check("NeedResult encodes {ok, detail}") { c in
+        let j = String(decoding: try JSONEncoder().encode(NeedResult(ok: true, detail: "proxy installed")), as: UTF8.self)
+        c.expect(j.contains("\"ok\":true") && j.contains("\"detail\":\"proxy installed\""))
+    },
+]
+```
+
+- [ ] **Step 2: Run → compile failure.**
+
+- [ ] **Step 3: Implement**
+
+`rt-tray/Sources-core/Needs/NeedModels.swift`:
+```swift
+import Foundation
+
+public struct NeedResult: Codable, Equatable, Sendable {
+    public var ok: Bool
+    public var detail: String
+    public init(ok: Bool, detail: String) { self.ok = ok; self.detail = detail }
+}
+
+public protocol PrivilegedInstalling: Sendable {
+    func proxyInstall() async -> NeedResult
+    func proxyRemove() async -> NeedResult
+}
+
+public protocol PrivilegeEscalator: Sendable {
+    func runAsAdmin(executable: String, args: [String], prompt: String) async -> CommandOutcome
+}
+
+public enum ProxyHelper {
+    public static let relativePath = "Contents/Helpers/mattstack-proxy-install"
+    public static func path(bundlePath: String) -> String { bundlePath + "/" + relativePath }
+    public static let promptText = "mattstack needs administrator access once to install the local HTTPS proxy (portless) for the board and deck."
+}
+```
+
+`rt-tray/Sources/Services/PrivilegedInstaller.swift`:
+```swift
+import Foundation
+import Security
+import MattstackCore
+
+final class PrivilegedInstaller: PrivilegedInstalling, @unchecked Sendable {
+    private let bundlePath: String
+    private let escalator: PrivilegeEscalator
+    private let fileExists: @Sendable (String) -> Bool
+
+    init(bundlePath: String, escalator: PrivilegeEscalator,
+         fileExists: @escaping @Sendable (String) -> Bool = { FileManager.default.isExecutableFile(atPath: $0) }) {
+        self.bundlePath = bundlePath; self.escalator = escalator; self.fileExists = fileExists
+    }
+
+    func proxyInstall() async -> NeedResult { await run(op: "install") }
+    func proxyRemove() async -> NeedResult { await run(op: "remove") }
+
+    private func run(op: String) async -> NeedResult {
+        let helper = ProxyHelper.path(bundlePath: bundlePath)
+        guard fileExists(helper) else {
+            return NeedResult(ok: false, detail: "proxy-install helper is not bundled at \(ProxyHelper.relativePath)")
+        }
+        let out = await escalator.runAsAdmin(executable: helper, args: [op], prompt: ProxyHelper.promptText)
+        if out.ok { TrayLog.info("proxy helper ran", ["stdout": String(out.stdout.suffix(500))]) }
+        else { TrayLog.warn("proxy helper failed", ["exit": Int(out.exitCode), "stderr": String(out.stderr.suffix(1000))]) }
+        return NeedResult(ok: out.ok, detail: out.ok ? out.stdout.trimmingCharacters(in: .whitespacesAndNewlines)
+                                                     : (out.stderr.isEmpty ? "exit \(out.exitCode)" : out.stderr))
+    }
+}
+
+/// The one admin prompt (spec §7 "Privileged"). AuthorizationServices shows
+/// the system dialog with our prompt; the helper then runs as root through
+/// AuthorizationExecuteWithPrivileges, resolved at runtime because the
+/// symbol is deprecated-but-supported and has no Swift overlay.
+struct AuthorizationServicesEscalator: PrivilegeEscalator {
+    private typealias ExecFn = @convention(c) (AuthorizationRef, UnsafePointer<CChar>, AuthorizationFlags,
+                                               UnsafePointer<UnsafeMutablePointer<CChar>?>?,
+                                               UnsafeMutablePointer<UnsafeMutablePointer<FILE>?>?) -> OSStatus
+
+    func runAsAdmin(executable: String, args: [String], prompt: String) async -> CommandOutcome {
+        await withCheckedContinuation { cont in
+            DispatchQueue.global(qos: .userInitiated).async { cont.resume(returning: Self.runBlocking(executable, args, prompt)) }
+        }
+    }
+
+    private static func runBlocking(_ executable: String, _ args: [String], _ prompt: String) -> CommandOutcome {
+        var authRef: AuthorizationRef?
+        guard AuthorizationCreate(nil, nil, [], &authRef) == errAuthorizationSuccess, let auth = authRef else {
+            return CommandOutcome(exitCode: 1, stdout: "", stderr: "AuthorizationCreate failed")
+        }
+        defer { AuthorizationFree(auth, [.destroyRights]) }
+
+        var item = kAuthorizationRightExecute.withCString { name in
+            AuthorizationItem(name: name, valueLength: 0, value: nil, flags: 0)
+        }
+        var rights = AuthorizationItem_withRights(&item)
+        var promptCopy = Array(prompt.utf8CString)
+        var envItem = promptCopy.withUnsafeMutableBufferPointer { buf in
+            AuthorizationItem(name: kAuthorizationEnvironmentPrompt, valueLength: buf.count - 1, value: buf.baseAddress, flags: 0)
+        }
+        var env = AuthorizationItem_withRights(&envItem)
+        let flags: AuthorizationFlags = [.interactionAllowed, .extendRights, .preAuthorize]
+        let status = AuthorizationCopyRights(auth, &rights, &env, flags, nil)
+        guard status == errAuthorizationSuccess else {
+            return CommandOutcome(exitCode: Int32(status), stdout: "", stderr: status == errAuthorizationCanceled ? "cancelled" : "authorization denied (\(status))")
+        }
+
+        guard let sym = dlsym(UnsafeMutableRawPointer(bitPattern: -2), "AuthorizationExecuteWithPrivileges") else {
+            return CommandOutcome(exitCode: 1, stdout: "", stderr: "AuthorizationExecuteWithPrivileges unavailable")
+        }
+        let exec = unsafeBitCast(sym, to: ExecFn.self)
+        var cArgs: [UnsafeMutablePointer<CChar>?] = args.map { strdup($0) } + [nil]
+        defer { cArgs.forEach { free($0) } }
+        var pipe: UnsafeMutablePointer<FILE>?
+        let rc = executable.withCString { exe in exec(auth, exe, [], &cArgs, &pipe) }
+        guard rc == errAuthorizationSuccess, let fp = pipe else {
+            return CommandOutcome(exitCode: Int32(rc), stdout: "", stderr: "exec failed (\(rc))")
+        }
+        var output = ""
+        var buf = [CChar](repeating: 0, count: 4096)
+        while fgets(&buf, Int32(buf.count), fp) != nil { output += String(cString: buf) }
+        fclose(fp)
+        // The helper prints "MATTSTACK_EXIT=<n>" as its last line so the
+        // caller learns the real status (the API does not report it).
+        let exit = output.split(separator: "\n").last.flatMap { $0.hasPrefix("MATTSTACK_EXIT=") ? Int32($0.dropFirst("MATTSTACK_EXIT=".count)) : nil } ?? 0
+        return CommandOutcome(exitCode: exit, stdout: output, stderr: exit == 0 ? "" : output)
+    }
+
+    private static func AuthorizationItem_withRights(_ item: inout AuthorizationItem) -> AuthorizationRights {
+        withUnsafeMutablePointer(to: &item) { AuthorizationRights(count: 1, items: $0) }
+    }
+}
+```
+(The helper's `MATTSTACK_EXIT=` trailer is a contract L4/L5 must honour; record it in Open questions. L4 T2 carries a `status:"pending"` deps.lock row for `mattstack-proxy-install` so `check-bundle.sh` tolerates its absence until L5 ships it; until then this class honestly reports "helper is not bundled". If the compiler rejects the pointer gymnastics, fall back to `osascript -e 'do shell script … with administrator privileges'` through `CommandRunner` — same prompt, same one-time ask — and note the swap in the report.)
+
+- [ ] **Step 4: `swift build`; checks pass. Commit**
+```bash
+git add rt-tray/Sources-core rt-tray/Sources/Services rt-tray/Tests
+git commit -m "MAT-383: PrivilegedInstaller — one admin prompt for the bundled proxy-install helper
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 9: NeedBroker + TrayRoutes — the new tray.sock routes as a pure router, wired into TrayServer
+
+**Files:**
+- Create: `rt-tray/Sources-core/Needs/NeedBroker.swift`, `rt-tray/Sources-core/Routes/TrayRoutes.swift`; modify `rt-tray/Sources-core/Routes/Providers.swift`
+- Modify: `rt-tray/Sources/TrayServer.swift`
+- Create: `rt-tray/Tests/MattstackCoreChecks/TrayRoutesChecks.swift`; modify `AllChecks.swift`
+
+**Interfaces:**
+- Consumes: `PermissionsProviding` (Task 6), `ServicesProviding`, `ServiceStatusEntry`, `ServiceRegisterResult` (Task 7), `PrivilegedInstalling`, `NeedResult` (Task 8), `NeedRequest` (defined here in Core `Contract/ApplyEvents.swift` — Task 11 reuses it), `VersionInfo` (Task 3).
+- Produces:
+  - `public struct NeedRequest: Codable, Equatable { type: String; plists: [String]?; op: String? }` (in `Contract/ApplyEvents.swift`, created now with only this type; Task 11 fills the rest). NeedBroker handles every type L1 emits (contract): `app-register-services {plists}` → `services.register`, `app-unregister-services {plists}` → `services.unregister`, `app-privileged {op:"proxy-install"|"proxy-remove"}` → `privileged.proxyInstall()/proxyRemove()`; anything else → `failed: unknown need type`.
+  - `public struct NeedOutcome: Codable, Equatable { state: String /* pending | done | failed */; detail: String }` — the body rt polls at `GET /setup/need/<id>` (contract, 2026-08-21 update: rt polls every 1 s, 10-minute timeout; the app never POSTs a reply).
+  - `public actor NeedBroker { init(services: ServicesProviding, privileged: PrivilegedInstalling); func perform(id: String, request: NeedRequest) async -> NeedResult; func outcome(id: String) -> NeedOutcome; func forget(id:); func forgetAll() }` — one execution per id; concurrent callers await the same result; `outcome` is `pending` while running (or before the app has read the `need` line), then `done`/`failed` with the detail. Unknown ids report `pending` — rt keeps polling until its own timeout; the app never fabricates a result.
+  - `public protocol UpdateChecking: Sendable { func checkForUpdates() async -> Bool }`, `public protocol VersionProviding: Sendable { func versionInfo() -> VersionInfo }`
+  - `public struct RouteResponse: Equatable { status: Int; body: String }`
+  - `public struct TrayRoutes: Sendable { init(permissions:, services:, privileged:, needs: NeedBroker, updater: UpdateChecking, version: VersionProviding); func handle(method: String, path: String, body: Data?) async -> RouteResponse? }` — nil = not one of the new routes (TrayServer keeps its existing chain for those).
+- TrayServer change: after parsing method/path/body, `if let r = await routes?.handle(...)` send it; else the existing if/else chain. `TrayServer.shared.routes: TrayRoutes?` is set by AppDelegate (Task 18).
+
+- [ ] **Step 1: Failing checks**
+
+`rt-tray/Tests/MattstackCoreChecks/TrayRoutesChecks.swift`:
+```swift
+import Foundation
+import MattstackCore
+
+final class FakePerms: PermissionsProviding, @unchecked Sendable {
+    var snap = PermissionSnapshot(fda: .init(status: "granted", detail: "probe read ~/Library/Containers/com.apple.stocks"),
+                                  notifications: .init(status: "notDetermined"), loginItems: .init(status: "enabled"))
+    var requested: [String] = []
+    func snapshot() async -> PermissionSnapshot { snap }
+    func request(_ which: String) async -> Bool { requested.append(which); return which == "notifications" }
+}
+final class FakeServices: ServicesProviding, @unchecked Sendable {
+    var registered: [[String]] = []
+    var unregistered: [[String]] = []
+    var restarted: [String] = []
+    var registerDelayNs: UInt64 = 0
+    func statuses() async -> [ServiceStatusEntry] { [ServiceStatusEntry(label: "com.mattstack.daemon", status: "enabled")] }
+    func register(plists: [String]) async -> [ServiceRegisterResult] {
+        if registerDelayNs > 0 { try? await Task.sleep(nanoseconds: registerDelayNs) }
+        registered.append(plists)
+        return plists.map { ServiceRegisterResult(plist: $0, ok: true, status: "enabled") }
+    }
+    func unregister(plists: [String]) async -> [ServiceRegisterResult] {
+        unregistered.append(plists)
+        return plists.map { ServiceRegisterResult(plist: $0, ok: true, status: "notRegistered") }
+    }
+    func restart(label: String) async -> Bool { restarted.append(label); return true }
+}
+final class FakePrivileged: PrivilegedInstalling, @unchecked Sendable {
+    var calls = 0
+    var removes = 0
+    func proxyInstall() async -> NeedResult { calls += 1; return NeedResult(ok: true, detail: "proxy installed") }
+    func proxyRemove() async -> NeedResult { removes += 1; return NeedResult(ok: true, detail: "proxy removed") }
+}
+final class FakeUpdater: UpdateChecking, @unchecked Sendable { var checks = 0; func checkForUpdates() async -> Bool { checks += 1; return true } }
+struct FakeVersion: VersionProviding {
+    func versionInfo() -> VersionInfo { VersionInfo(version: "2.8.0", build: 2008000, flavor: "dev", path: "/Applications/mattstack-dev.app") }
+}
+
+func makeRoutes() -> (TrayRoutes, FakePerms, FakeServices, FakePrivileged, FakeUpdater, NeedBroker) {
+    let p = FakePerms(), s = FakeServices(), pr = FakePrivileged(), u = FakeUpdater()
+    let broker = NeedBroker(services: s, privileged: pr)
+    return (TrayRoutes(permissions: p, services: s, privileged: pr, needs: broker, updater: u, version: FakeVersion()), p, s, pr, u, broker)
+}
+func json(_ body: String) -> [String: Any] { (try? JSONSerialization.jsonObject(with: Data(body.utf8))) as? [String: Any] ?? [:] }
+
+let trayRoutesChecks: [Check] = [
+    Check("GET /permissions returns the contract body") { c in
+        let (r, _, _, _, _, _) = makeRoutes()
+        let resp = await r.handle(method: "GET", path: "/permissions", body: nil)
+        c.expectEqual(resp?.status, 200)
+        let j = json(resp!.body)
+        c.expectEqual((j["fda"] as? [String: Any])?["status"] as? String, "granted")
+        c.expectEqual((j["loginItems"] as? [String: Any])?["status"] as? String, "enabled")
+    },
+    Check("POST /permissions/request {which} → {ok}") { c in
+        let (r, p, _, _, _, _) = makeRoutes()
+        let resp = await r.handle(method: "POST", path: "/permissions/request", body: Data("{\"which\":\"notifications\"}".utf8))
+        c.expectEqual(resp?.status, 200)
+        c.expectEqual(json(resp!.body)["ok"] as? Bool, true)
+        c.expectEqual(p.requested, ["notifications"])
+        let bad = await r.handle(method: "POST", path: "/permissions/request", body: Data("{}".utf8))
+        c.expectEqual(bad?.status, 400)
+    },
+    Check("GET /services, POST /services/register, POST /services/restart") { c in
+        let (r, _, s, _, _, _) = makeRoutes()
+        let list = await r.handle(method: "GET", path: "/services", body: nil)
+        c.expect(list!.body.contains("\"agents\""))
+        let reg = await r.handle(method: "POST", path: "/services/register", body: Data("{\"plists\":[\"com.mattstack.daemon.plist\"]}".utf8))
+        c.expectEqual(reg?.status, 200)
+        c.expectEqual(s.registered, [["com.mattstack.daemon.plist"]])
+        c.expect(reg!.body.contains("\"results\""))
+        let rs = await r.handle(method: "POST", path: "/services/restart", body: Data("{\"label\":\"com.mattstack.deck\"}".utf8))
+        c.expectEqual(rs?.status, 200)
+        c.expectEqual(s.restarted, ["com.mattstack.deck"])
+    },
+    Check("POST /privileged/proxy-install → NeedResult") { c in
+        let (r, _, _, pr, _, _) = makeRoutes()
+        let resp = await r.handle(method: "POST", path: "/privileged/proxy-install", body: nil)
+        c.expectEqual(resp?.status, 200)
+        c.expectEqual(json(resp!.body)["ok"] as? Bool, true)
+        c.expectEqual(pr.calls, 1)
+    },
+    Check("GET /setup/need/<id> serves the app-recorded outcome: pending → done/failed; never a POST") { c in
+        let (r, _, s, _, _, broker) = makeRoutes()
+        let before = await r.handle(method: "GET", path: "/setup/need/services.register", body: nil)
+        c.expectEqual(before?.status, 200)
+        c.expectEqual(json(before!.body)["state"] as? String, "pending", "unknown/unstarted id is pending — rt keeps polling")
+        let req = NeedRequest(type: "app-register-services", plists: ["com.mattstack.daemon.plist", "com.mattstack.deck.plist"], op: nil)
+        _ = await broker.perform(id: "services.register", request: req)
+        let after = await r.handle(method: "GET", path: "/setup/need/services.register", body: nil)
+        let j = json(after!.body)
+        c.expectEqual(j["state"] as? String, "done")
+        c.expect((j["detail"] as? String)?.contains("com.mattstack.daemon.plist") == true)
+        c.expectEqual(s.registered.count, 1)
+        _ = await broker.perform(id: "x", request: NeedRequest(type: "teleport", plists: nil, op: nil))
+        let failed = await r.handle(method: "GET", path: "/setup/need/x", body: nil)
+        c.expectEqual(json(failed!.body)["state"] as? String, "failed")
+        let posted = await r.handle(method: "POST", path: "/setup/need/x", body: Data("{}".utf8))
+        c.expectEqual(posted?.status, 405, "the contract has no POST reply")
+        let empty = await r.handle(method: "GET", path: "/setup/need/", body: nil)
+        c.expectEqual(empty?.status, 400)
+    },
+    Check("NeedBroker: concurrent callers for one id share one execution; outcome is pending while running") { c in
+        let s = FakeServices(); s.registerDelayNs = 80_000_000
+        let broker = NeedBroker(services: s, privileged: FakePrivileged())
+        let req = NeedRequest(type: "app-register-services", plists: ["a.plist"], op: nil)
+        async let x = broker.perform(id: "services.register", request: req)
+        try await Task.sleep(nanoseconds: 10_000_000)
+        c.expectEqual(await broker.outcome(id: "services.register").state, "pending")
+        async let y = broker.perform(id: "services.register", request: req)
+        let (rx, ry) = await (x, y)
+        c.expectEqual(rx, ry)
+        c.expectEqual(s.registered.count, 1)
+        c.expectEqual(await broker.outcome(id: "services.register").state, "done")
+        let privileged = await broker.perform(id: "proxy.install", request: NeedRequest(type: "app-privileged", plists: nil, op: "proxy-install"))
+        c.expectEqual(privileged.detail, "proxy installed")
+        await broker.forget(id: "proxy.install")
+        c.expectEqual(await broker.outcome(id: "proxy.install").state, "pending", "a retry must be able to redo the step")
+    },
+    Check("NeedBroker: uninstall needs — app-unregister-services and app-privileged/proxy-remove (L1 rt uninstall)") { c in
+        let s = FakeServices(), pr = FakePrivileged()
+        let broker = NeedBroker(services: s, privileged: pr)
+        let un = await broker.perform(id: "services.unregister", request: NeedRequest(type: "app-unregister-services", plists: ["com.mattstack.daemon.plist", "com.mattstack.deck.plist"], op: nil))
+        c.expectEqual(un.ok, true)
+        c.expectEqual(s.unregistered, [["com.mattstack.daemon.plist", "com.mattstack.deck.plist"]])
+        let rm = await broker.perform(id: "proxy.remove", request: NeedRequest(type: "app-privileged", plists: nil, op: "proxy-remove"))
+        c.expectEqual(rm.detail, "proxy removed")
+        c.expectEqual(pr.removes, 1)
+    },
+    Check("POST /update/check and GET /version") { c in
+        let (r, _, _, _, u, _) = makeRoutes()
+        let up = await r.handle(method: "POST", path: "/update/check", body: nil)
+        c.expectEqual(json(up!.body)["ok"] as? Bool, true)
+        c.expectEqual(u.checks, 1)
+        let v = await r.handle(method: "GET", path: "/version", body: nil)
+        let j = json(v!.body)
+        c.expectEqual(j["version"] as? String, "2.8.0")
+        c.expectEqual(j["build"] as? Int, 2008000, "build is the numeric CFBundleVersion, never a string")
+        c.expectEqual(j["flavor"] as? String, "dev")
+        c.expectEqual(j["path"] as? String, "/Applications/mattstack-dev.app")
+    },
+    Check("unknown paths return nil so the legacy chain handles them") { c in
+        let (r, _, _, _, _, _) = makeRoutes()
+        let legacy = await r.handle(method: "GET", path: "/health", body: nil)
+        c.expect(legacy == nil)
+        let wrongMethod = await r.handle(method: "GET", path: "/update/check", body: nil)
+        c.expectEqual(wrongMethod?.status, 405)
+    },
+]
+```
+
+- [ ] **Step 2: Run → compile failure.**
+
+- [ ] **Step 3: Implement**
+
+`rt-tray/Sources-core/Contract/ApplyEvents.swift` (first slice; Task 11 adds `ApplyEvent`):
+```swift
+import Foundation
+
+public struct NeedRequest: Codable, Equatable, Sendable {
+    public var type: String      // app-register-services | app-unregister-services | app-privileged
+    public var plists: [String]?
+    public var op: String?       // proxy-install | proxy-remove
+    public init(type: String, plists: [String]?, op: String?) { self.type = type; self.plists = plists; self.op = op }
+}
+```
+
+`rt-tray/Sources-core/Routes/Providers.swift` (append):
+```swift
+public protocol UpdateChecking: Sendable { func checkForUpdates() async -> Bool }
+public protocol VersionProviding: Sendable { func versionInfo() -> VersionInfo }
+```
+
+`rt-tray/Sources-core/Needs/NeedBroker.swift`:
+```swift
+import Foundation
+
+/// What rt polls at `GET /setup/need/<id>` while it waits for the app.
+public struct NeedOutcome: Codable, Equatable, Sendable {
+    public var state: String   // pending | done | failed
+    public var detail: String
+    public init(state: String, detail: String) { self.state = state; self.detail = detail }
+    public static let pending = NeedOutcome(state: "pending", detail: "waiting for the app")
+}
+
+/// Executes rt's `need` events exactly once per step id and records the
+/// outcome for rt's 1 s poll. Concurrent callers for one id join the same
+/// execution; an id nobody has performed yet reads as pending so rt keeps
+/// polling until its own 10-minute timeout instead of being told a story.
+public actor NeedBroker {
+    private let services: ServicesProviding
+    private let privileged: PrivilegedInstalling
+    private var inFlight: [String: Task<NeedResult, Never>] = [:]
+    private var outcomes: [String: NeedOutcome] = [:]
+
+    public init(services: ServicesProviding, privileged: PrivilegedInstalling) {
+        self.services = services
+        self.privileged = privileged
+    }
+
+    public func outcome(id: String) -> NeedOutcome { outcomes[id] ?? .pending }
+
+    public func perform(id: String, request: NeedRequest) async -> NeedResult {
+        if let task = inFlight[id] { return await task.value }
+        outcomes[id] = .pending
+        let services = self.services, privileged = self.privileged
+        let task = Task<NeedResult, Never> {
+            switch request.type {
+            case "app-register-services":
+                let results = await services.register(plists: request.plists ?? [])
+                let failed = results.filter { !$0.ok }
+                if failed.isEmpty {
+                    return NeedResult(ok: true, detail: results.map { "\($0.plist): \($0.status)" }.joined(separator: ", "))
+                }
+                return NeedResult(ok: false, detail: failed.map { "\($0.plist): \($0.error ?? $0.status)" }.joined(separator: "; "))
+            case "app-unregister-services":
+                let results = await services.unregister(plists: request.plists ?? [])
+                let failed = results.filter { !$0.ok }
+                if failed.isEmpty {
+                    return NeedResult(ok: true, detail: results.map { "\($0.plist): \($0.status)" }.joined(separator: ", "))
+                }
+                return NeedResult(ok: false, detail: failed.map { "\($0.plist): \($0.error ?? $0.status)" }.joined(separator: "; "))
+            case "app-privileged" where request.op == "proxy-install":
+                return await privileged.proxyInstall()
+            case "app-privileged" where request.op == "proxy-remove":
+                return await privileged.proxyRemove()
+            default:
+                return NeedResult(ok: false, detail: "unknown need type \(request.type)\(request.op.map { "/\($0)" } ?? "")")
+            }
+        }
+        inFlight[id] = task
+        let result = await task.value
+        outcomes[id] = NeedOutcome(state: result.ok ? "done" : "failed", detail: result.detail)
+        return result
+    }
+
+    /// A retry (`setup apply --from`) must be allowed to redo a step.
+    public func forget(id: String) { inFlight[id] = nil; outcomes[id] = nil }
+    public func forgetAll() { inFlight.removeAll(); outcomes.removeAll() }
+}
+```
+
+`rt-tray/Sources-core/Routes/TrayRoutes.swift`:
+```swift
+import Foundation
+
+public struct RouteResponse: Equatable, Sendable {
+    public let status: Int
+    public let body: String
+    public init(status: Int, body: String) { self.status = status; self.body = body }
+}
+
+/// The contract's tray.sock additions (§5.3). Pure: providers are injected,
+/// HTTP framing stays in TrayServer.
+public struct TrayRoutes: Sendable {
+    private let permissions: PermissionsProviding
+    private let services: ServicesProviding
+    private let privileged: PrivilegedInstalling
+    private let needs: NeedBroker
+    private let updater: UpdateChecking
+    private let version: VersionProviding
+
+    public init(permissions: PermissionsProviding, services: ServicesProviding, privileged: PrivilegedInstalling,
+                needs: NeedBroker, updater: UpdateChecking, version: VersionProviding) {
+        self.permissions = permissions; self.services = services; self.privileged = privileged
+        self.needs = needs; self.updater = updater; self.version = version
+    }
+
+    public static let paths: Set<String> = ["/permissions", "/permissions/request", "/services", "/services/register",
+                                            "/services/restart", "/privileged/proxy-install", "/update/check", "/version"]
+
+    public func handle(method: String, path: String, body: Data?) async -> RouteResponse? {
+        let isNeed = path.hasPrefix("/setup/need/")
+        guard Self.paths.contains(path) || isNeed else { return nil }
+        switch (method, path) {
+        case ("GET", "/permissions"):
+            return encode(await permissions.snapshot())
+        case ("POST", "/permissions/request"):
+            guard let which = field("which", in: body) else { return bad("which is required") }
+            let ok = await permissions.request(which)
+            return RouteResponse(status: 200, body: "{\"ok\":\(ok)}")
+        case ("GET", "/services"):
+            return encode(["agents": await services.statuses()])
+        case ("POST", "/services/register"):
+            guard let plists = list("plists", in: body) else { return bad("plists is required") }
+            let results = await services.register(plists: plists)
+            struct Reply: Encodable { let ok: Bool; let results: [ServiceRegisterResult] }
+            return encode(Reply(ok: results.allSatisfy(\.ok), results: results))
+        case ("POST", "/services/restart"):
+            guard let label = field("label", in: body) else { return bad("label is required") }
+            return RouteResponse(status: 200, body: "{\"ok\":\(await services.restart(label: label))}")
+        case ("POST", "/privileged/proxy-install"):
+            return encode(await privileged.proxyInstall())
+        case ("GET", _) where isNeed:
+            let id = String(path.dropFirst("/setup/need/".count))
+            guard !id.isEmpty else { return bad("need id is required") }
+            return encode(await needs.outcome(id: id))
+        case ("POST", "/update/check"):
+            return RouteResponse(status: 200, body: "{\"ok\":\(await updater.checkForUpdates())}")
+        case ("GET", "/version"):
+            return encode(version.versionInfo())
+        default:
+            return RouteResponse(status: 405, body: "{\"ok\":false,\"error\":\"method not allowed\"}")
+        }
+    }
+
+    private func encode<T: Encodable>(_ value: T) -> RouteResponse {
+        let enc = JSONEncoder(); enc.outputFormatting = [.sortedKeys]
+        guard let data = try? enc.encode(value) else { return RouteResponse(status: 500, body: "{\"ok\":false,\"error\":\"encode\"}") }
+        return RouteResponse(status: 200, body: String(decoding: data, as: UTF8.self))
+    }
+    private func bad(_ msg: String) -> RouteResponse { RouteResponse(status: 400, body: "{\"ok\":false,\"error\":\"\(msg)\"}") }
+    private func object(_ body: Data?) -> [String: Any]? {
+        guard let body else { return nil }
+        return (try? JSONSerialization.jsonObject(with: body)) as? [String: Any]
+    }
+    private func field(_ name: String, in body: Data?) -> String? { object(body)?[name] as? String }
+    private func list(_ name: String, in body: Data?) -> [String]? { object(body)?[name] as? [String] }
+}
+```
+
+- [ ] **Step 4: Run checks → pass.**
+
+- [ ] **Step 5: Wire TrayServer**
+
+In `rt-tray/Sources/TrayServer.swift`:
+- add `import MattstackCore` and a property `var routes: TrayRoutes?` next to `daemonLifecycle`.
+- In `handleConnection`, right after `let path = parts.count > 1 ? parts[1] : ""`, insert:
+```swift
+            let bodyData: Data? = str.range(of: "\r\n\r\n").map { Data(String(str[$0.upperBound...]).utf8) }
+            if let routes = self.routes {
+                Task {
+                    if let reply = await routes.handle(method: method, path: path, body: bodyData) {
+                        self.sendResponse(connection: connection, status: reply.status, body: reply.body, path: path)
+                    } else {
+                        self.handleLegacy(method: method, path: path, str: str, connection: connection)
+                    }
+                }
+                return
+            }
+            self.handleLegacy(method: method, path: path, str: str, connection: connection)
+```
+and move the existing if/else chain (from `if method == "POST" && path == "/notify"` through the final 404) into a new `private func handleLegacy(method: String, path: String, str: String, connection: NWConnection)` unchanged. Add `case 405: statusText = "Method Not Allowed"` and `case 500: statusText = "Error"` to `sendResponse`. Existing routes keep their behaviour; `check-bundle.sh`'s awk over the `/flavor/retire` block still matches because that block moves verbatim. **L4 `check-bundle.sh` source gates this refactor must preserve (cross-plan review §1 row 14):** the literal `path == "/flavor/retire"` in `TrayServer.swift`; `forInfoDictionaryKey: "MSDaemonLabel"` and `defaultDaemonLabel = "com.mattstack.daemon"` in `Sources/` (today `BundleFlavor.swift`); and in `main.swift` the socket guard stays before `let delegate = AppDelegate()` (Task 18).
+
+- [ ] **Step 6: `swift build`; checks pass. Commit**
+```bash
+git add rt-tray/Sources-core rt-tray/Sources/TrayServer.swift rt-tray/Tests
+git commit -m "MAT-383: tray.sock routes (/permissions, /services, /privileged, GET /setup/need polling, /update/check, /version) + NeedBroker
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 10: UpdaterController — Sparkle via SPM, gentle reminders, dev flavor off, build.sh launch stopgap
+
+**Files:**
+- Modify: `rt-tray/Package.swift` (Sparkle dep + rpath)
+- Create: `rt-tray/Sources-core/Updates/UpdatePolicy.swift`
+- Create: `rt-tray/Sources/Updates/UpdaterController.swift`
+- Delete: `rt-tray/Sources/UpdateChecker.swift`
+- Modify: `rt-tray/Sources/AppDelegate.swift` (swap UpdateChecker → UpdaterController), `rt-tray/Sources/TrayState.swift` (doc comment only), `rt-tray/check-bundle.sh` (one assertion — **drop this edit if L4 T3's rewrite has already merged; otherwise L4 absorbs it at rebase**), `rt-tray/build.sh` (**fenced stopgap — deleted by L4 T4's rewrite; L4 T4 must call `scripts/render-launchagents.sh`**)
+- Create: `rt-tray/Tests/MattstackCoreChecks/UpdatePolicyChecks.swift`; modify `AllChecks.swift`
+
+**Interfaces:**
+- Produces (Core): `public enum UpdatePolicy { static let placeholderKey = "REPLACE_WITH_RELEASE_PUBLIC_ED_KEY"; static let overrideEnv = "MATTSTACK_APPCAST_URL"; static let overrideFlag = "--allow-appcast-override"; static func feedOverride(environment: [String: String], arguments: [String], isDevBuild: Bool) -> String?; static func shouldStartUpdater(isDevBuild: Bool, publicEDKey: String?, feedURL: String?, feedOverride: String?) -> Bool; static func allowsImmediateInstall(setupRunning: Bool, windowsOpen: Int) -> Bool }`. **Decision (L7 request):** the env override is honoured when `MSDevBuild` is true OR the process was launched with `--allow-appcast-override`; with an override present the updater starts even in the dev flavor (that is the VM's Sparkle vN→vN+1 rehearsal), but the EdDSA key must still be real — the app never talks to a feed it cannot verify.
+- Produces (app): `final class UpdaterController: NSObject, UpdateChecking, SPUUpdaterDelegate, SPUStandardUserDriverDelegate` — `init(isDevBuild: Bool, isBusy: @escaping () -> Bool)`; `var canCheckForUpdates: Bool` (KVO-published via `@objc dynamic`); `func checkForUpdates() async -> Bool`; `@objc func checkForUpdatesFromMenu()`; `var onUpdateAvailable: ((String) -> Void)?` (feeds `TrayState.updateAvailable`); `var automaticallyChecks: Bool { get set }`.
+
+- [ ] **Step 1: Failing checks**
+
+`rt-tray/Tests/MattstackCoreChecks/UpdatePolicyChecks.swift`:
+```swift
+import Foundation
+import MattstackCore
+
+let updatePolicyChecks: [Check] = [
+    Check("Sparkle starts only for prod builds with a real key and feed") { c in
+        c.expectEqual(UpdatePolicy.shouldStartUpdater(isDevBuild: true, publicEDKey: "abc", feedURL: "https://x/appcast.xml", feedOverride: nil), false)
+        c.expectEqual(UpdatePolicy.shouldStartUpdater(isDevBuild: false, publicEDKey: UpdatePolicy.placeholderKey, feedURL: "https://x/appcast.xml", feedOverride: nil), false)
+        c.expectEqual(UpdatePolicy.shouldStartUpdater(isDevBuild: false, publicEDKey: "", feedURL: "https://x/appcast.xml", feedOverride: nil), false)
+        c.expectEqual(UpdatePolicy.shouldStartUpdater(isDevBuild: false, publicEDKey: "abc", feedURL: nil, feedOverride: nil), false)
+        c.expectEqual(UpdatePolicy.shouldStartUpdater(isDevBuild: false, publicEDKey: "abc", feedURL: "https://x/appcast.xml", feedOverride: nil), true)
+    },
+    Check("appcast override: env honoured only in dev flavor or with --allow-appcast-override; starts the updater but never without a real key") { c in
+        let env = [UpdatePolicy.overrideEnv: "http://127.0.0.1:8000/appcast.xml"]
+        c.expectEqual(UpdatePolicy.feedOverride(environment: env, arguments: ["mattstack"], isDevBuild: false), nil)
+        c.expectEqual(UpdatePolicy.feedOverride(environment: env, arguments: ["mattstack"], isDevBuild: true), "http://127.0.0.1:8000/appcast.xml")
+        c.expectEqual(UpdatePolicy.feedOverride(environment: env, arguments: ["mattstack", UpdatePolicy.overrideFlag], isDevBuild: false), "http://127.0.0.1:8000/appcast.xml")
+        c.expectEqual(UpdatePolicy.feedOverride(environment: [:], arguments: [UpdatePolicy.overrideFlag], isDevBuild: true), nil)
+        c.expectEqual(UpdatePolicy.shouldStartUpdater(isDevBuild: true, publicEDKey: "abc", feedURL: nil, feedOverride: "http://127.0.0.1:8000/appcast.xml"), true)
+        c.expectEqual(UpdatePolicy.shouldStartUpdater(isDevBuild: true, publicEDKey: UpdatePolicy.placeholderKey, feedURL: nil, feedOverride: "http://127.0.0.1:8000/appcast.xml"), false)
+    },
+    Check("immediate install only when idle: no setup running, no windows") { c in
+        c.expectEqual(UpdatePolicy.allowsImmediateInstall(setupRunning: false, windowsOpen: 0), true)
+        c.expectEqual(UpdatePolicy.allowsImmediateInstall(setupRunning: true, windowsOpen: 0), false)
+        c.expectEqual(UpdatePolicy.allowsImmediateInstall(setupRunning: false, windowsOpen: 1), false)
+    },
+]
+```
+
+- [ ] **Step 2: Run → compile failure.** Implement `rt-tray/Sources-core/Updates/UpdatePolicy.swift`:
+```swift
+import Foundation
+
+public enum UpdatePolicy {
+    public static let placeholderKey = "REPLACE_WITH_RELEASE_PUBLIC_ED_KEY"
+    public static let overrideEnv = "MATTSTACK_APPCAST_URL"
+    public static let overrideFlag = "--allow-appcast-override"
+
+    /// The clean-room VM points the app at a loopback appcast. Only the dev
+    /// flavor, or a launch that opted in on the command line, may be redirected.
+    public static func feedOverride(environment: [String: String], arguments: [String], isDevBuild: Bool) -> String? {
+        guard let url = environment[overrideEnv], !url.isEmpty else { return nil }
+        return (isDevBuild || arguments.contains(overrideFlag)) ? url : nil
+    }
+
+    /// Dev flavor never checks unless a feed override is in force; a build
+    /// without a real EdDSA key must not talk to any feed it cannot verify.
+    public static func shouldStartUpdater(isDevBuild: Bool, publicEDKey: String?, feedURL: String?, feedOverride: String?) -> Bool {
+        guard let key = publicEDKey, !key.isEmpty, key != placeholderKey else { return false }
+        if let o = feedOverride, !o.isEmpty { return true }
+        guard !isDevBuild, let feed = feedURL, !feed.isEmpty else { return false }
+        return true
+    }
+
+    public static func allowsImmediateInstall(setupRunning: Bool, windowsOpen: Int) -> Bool {
+        !setupRunning && windowsOpen == 0
+    }
+}
+```
+Run checks → pass.
+
+- [ ] **Step 3: Add Sparkle to Package.swift**
+
+In `rt-tray/Package.swift` add at package level:
+```swift
+    dependencies: [
+        .package(url: "https://github.com/sparkle-project/Sparkle", from: "2.9.6"),
+    ],
+```
+and on the `rt-tray` executable target:
+```swift
+            dependencies: [
+                "MattstackCore",
+                .product(name: "Sparkle", package: "Sparkle"),
+            ],
+            ...
+            linkerSettings: [
+                .linkedFramework("AppKit"),
+                .linkedFramework("UserNotifications"),
+                .linkedFramework("ServiceManagement"),
+                .unsafeFlags(["-Xlinker", "-rpath", "-Xlinker", "@executable_path/../Frameworks"]),
+                .unsafeFlags(["-Xlinker", "-rpath", "-Xlinker",
+                              "@executable_path/../../artifacts/sparkle/Sparkle/Sparkle.xcframework/macos-arm64_x86_64"]),
+            ]
+```
+(The second rpath lets the unbundled `.build/<triple>/debug/rt-tray` find the downloaded framework for `swift run`; harmless in the bundle.) `MattstackCore` must NOT depend on Sparkle — `swift run mattstack-checks` stays framework-free.
+
+Run `swift build 2>&1 | tail -3` → Sparkle is fetched (network) and the build completes. If the artifact download is blocked, record it and continue; the rest of the task still compiles only with Sparkle present, so stop and report rather than stubbing.
+
+- [ ] **Step 4: Write UpdaterController**
+
+`rt-tray/Sources/Updates/UpdaterController.swift`:
+```swift
+import AppKit
+import Sparkle
+import MattstackCore
+
+/// Sparkle for an LSUIElement app: gentle reminders instead of a window
+/// stealing focus, a menu item bound to canCheckForUpdates, silent install
+/// when idle, and nothing at all in the dev flavor.
+final class UpdaterController: NSObject, UpdateChecking, SPUUpdaterDelegate, SPUStandardUserDriverDelegate, @unchecked Sendable {
+    @objc dynamic private(set) var canCheckForUpdates = false
+    var onUpdateAvailable: ((String) -> Void)?
+    private let isBusy: () -> Bool
+    private let enabled: Bool
+    private var controller: SPUStandardUpdaterController?
+    private var observation: NSKeyValueObservation?
+
+    private let feedOverride: String?
+
+    init(isDevBuild: Bool, isBusy: @escaping () -> Bool) {
+        self.isBusy = isBusy
+        let info = Bundle.main.infoDictionary
+        feedOverride = UpdatePolicy.feedOverride(environment: ProcessInfo.processInfo.environment,
+                                                 arguments: CommandLine.arguments, isDevBuild: isDevBuild)
+        enabled = UpdatePolicy.shouldStartUpdater(isDevBuild: isDevBuild,
+                                                  publicEDKey: info?["SUPublicEDKey"] as? String,
+                                                  feedURL: info?["SUFeedURL"] as? String,
+                                                  feedOverride: feedOverride)
+        if let feedOverride { TrayLog.info("appcast override in force", ["url": feedOverride]) }
+        super.init()
+        guard enabled else {
+            TrayLog.info("update check skipped (dev build)", ["dev": isDevBuild])
+            return
+        }
+        let c = SPUStandardUpdaterController(startingUpdater: true, updaterDelegate: self, userDriverDelegate: self)
+        controller = c
+        observation = c.updater.observe(\.canCheckForUpdates, options: [.initial, .new]) { [weak self] updater, _ in
+            self?.canCheckForUpdates = updater.canCheckForUpdates
+        }
+    }
+
+    var automaticallyChecks: Bool {
+        get { controller?.updater.automaticallyChecksForUpdates ?? false }
+        set { controller?.updater.automaticallyChecksForUpdates = newValue }
+    }
+    var isEnabled: Bool { enabled }
+
+    @objc func checkForUpdatesFromMenu() { controller?.checkForUpdates(nil) }
+
+    func checkForUpdates() async -> Bool {
+        guard let c = controller else { return false }
+        await MainActor.run { c.updater.checkForUpdates() }
+        return true
+    }
+
+    // MARK: SPUStandardUserDriverDelegate — gentle reminders
+
+    var supportsGentleScheduledUpdateReminders: Bool { true }
+
+    func standardUserDriverShouldHandleShowingScheduledUpdate(_ update: SUAppcastItem, andInImmediateFocus immediateFocus: Bool) -> Bool {
+        immediateFocus
+    }
+
+    func standardUserDriverWillHandleShowingUpdate(_ handleShowingUpdate: Bool, forUpdate update: SUAppcastItem, state: SPUUserUpdateState) {
+        if !handleShowingUpdate || state.userInitiated == false {
+            DispatchQueue.main.async { self.onUpdateAvailable?(update.displayVersionString) }
+        }
+    }
+
+    func standardUserDriverWillFinishUpdateSession() {
+        DispatchQueue.main.async { self.onUpdateAvailable?("") }
+    }
+
+    // MARK: SPUUpdaterDelegate — feed override, install when idle
+
+    func feedURLString(for updater: SPUUpdater) -> String? { feedOverride }
+
+    func updater(_ updater: SPUUpdater, willInstallUpdateOnQuit item: SUAppcastItem,
+                 immediateInstallationBlock immediateInstallHandler: @escaping () -> Void) -> Bool {
+        let idle = UpdatePolicy.allowsImmediateInstall(setupRunning: isBusy(),
+                                                       windowsOpen: NSApp.windows.filter { $0.isVisible }.count)
+        if idle { DispatchQueue.main.async { immediateInstallHandler() } }
+        return idle
+    }
+}
+```
+The `onUpdateAvailable("")` clears the menu badge; AppDelegate maps empty → nil.
+
+- [ ] **Step 5: Rewire AppDelegate; delete UpdateChecker.swift**
+
+In `rt-tray/Sources/AppDelegate.swift`:
+- replace `private let updateChecker = UpdateChecker.shared` with `let updater = UpdaterController(isDevBuild: BundleFlavor.isDevBuild, isBusy: { SetupSession.isRunning })` — `SetupSession` arrives in Task 12; until then use `isBusy: { false }` and replace it in Task 12.
+- `setupAutoUpdate()` becomes:
+```swift
+    private func setupAutoUpdate() {
+        updater.onUpdateAvailable = { version in
+            TrayState.shared.updateAvailable = version.isEmpty ? nil : version
+        }
+    }
+```
+- `checkForUpdates()` becomes `updater.checkForUpdatesFromMenu()`.
+- delete `handleUpdateAvailable(_:)` and the `applicationWillTerminate` line `updateChecker.stopChecking()`.
+- `git rm rt-tray/Sources/UpdateChecker.swift`.
+- In `rt-tray/Sources/ProcessPanelView.swift` `updateMenuTitle` keeps working (`trayState.updateAvailable`). Leave it.
+- `rt-tray/check-bundle.sh` lines 322–327: replace the `awk '/func checkForUpdates/,/let urlString/' Sources/UpdateChecker.swift` block with
+```bash
+if grep -q 'UpdatePolicy.shouldStartUpdater(isDevBuild: isDevBuild' Sources/Updates/UpdaterController.swift; then
+    pass "UpdaterController gates Sparkle on the dev flavor"
+else
+    fail "UpdaterController does not gate Sparkle on BundleFlavor.isDevBuild"
+fi
+```
+(`assert_bin_has "silent dev updater" "update check skipped (dev build)"` still holds — the string survives in UpdaterController. L4 T3's `check-bundle.sh` rewrite carries both assertions — the `UpdatePolicy.shouldStartUpdater(isDevBuild: isDevBuild` grep and `assert_bin_has "silent dev updater"` — so if L4 T3 has merged before this task runs, skip the check-bundle edit here; if not, L4 absorbs it at rebase.)
+
+**Relaunch survival (L7):** every self-relaunch the app performs (the post-FDA "Relaunch mattstack" in Task 14, or any future one) re-execs with the current `ProcessInfo.processInfo.arguments` and environment, so `--allow-appcast-override` and `MATTSTACK_APPCAST_URL` survive the relaunch and the clean-room Sparkle rehearsal keeps pointing at the loopback appcast. Task 14's `relaunch()` implements it (`open -n <app> --env MATTSTACK_APPCAST_URL=… --args <current args>`).
+
+- [ ] **Step 6: build.sh stopgap (fenced stopgap — deleted by L4 T4's rewrite; L4 T4 must call `scripts/render-launchagents.sh` itself, keep `embed_sparkle` + the inside-out Sparkle signing, and use PlistBuddy `Set` for every key the Info.plist template already declares)**
+
+After the `cp "$BINARY" "$APP_BUNDLE/Contents/MacOS/$APP_NAME"` line in `rt-tray/build.sh` insert:
+```bash
+# ─── Sparkle.framework (stopgap until build.sh wraps xcodebuild) ───────────
+# The binary links Sparkle via SPM with rpath @executable_path/../Frameworks;
+# without the framework in the bundle the app fails at dyld. Copied with
+# ditto (symlinks preserved) and signed inside-out below, never --deep.
+SPARKLE_SRC="$SCRIPT_DIR/.build/artifacts/sparkle/Sparkle/Sparkle.xcframework/macos-arm64_x86_64/Sparkle.framework"
+if [ -d "$SPARKLE_SRC" ]; then
+    mkdir -p "$APP_BUNDLE/Contents/Frameworks"
+    ditto "$SPARKLE_SRC" "$APP_BUNDLE/Contents/Frameworks/Sparkle.framework"
+    echo "  ✓ Sparkle.framework embedded"
+else
+    echo "  ✗ Sparkle.framework not found under .build/artifacts — run swift build first"
+    exit 1
+fi
+```
+and in the signing section, before "2. Outer .app bundle", insert:
+```bash
+# 1b. Sparkle, inside-out (XPC services → Autoupdate → Updater.app → framework)
+SPK="$APP_BUNDLE/Contents/Frameworks/Sparkle.framework"
+for xpc in "$SPK"/Versions/B/XPCServices/*.xpc; do
+    [ -d "$xpc" ] && codesign "${SIGN_FLAGS[@]}" --preserve-metadata=entitlements "$xpc"
+done
+codesign "${SIGN_FLAGS[@]}" "$SPK/Versions/B/Autoupdate"
+codesign "${SIGN_FLAGS[@]}" "$SPK/Versions/B/Updater.app"
+codesign "${SIGN_FLAGS[@]}" "$SPK"
+echo "  ✓ Signed Sparkle.framework inside-out"
+```
+Also add the rendered agent plists: replace the single-plist `AGENT_PLIST` sed block + its KeepAlive PlistBuddy lines with
+```bash
+"$SCRIPT_DIR/scripts/render-launchagents.sh" "$([ "$IS_DEV" = true ] && echo dev || echo prod)" "$APP_BUNDLE/Contents/Library/LaunchAgents"
+```
+(check-bundle.sh's KeepAlive assertion for prod expects `true`; it now sees `SuccessfulExit=false` for both flavors per spec §8 — update that assertion too: search for the `KA_PRINT` block and make both flavors expect `SuccessfulExit`. L4 T3's rewrite carries the same flip; same drop-if-merged rule as above.)
+
+- [ ] **Step 7: Verify**
+```bash
+cd rt-tray && swift build 2>&1 | tail -1 && swift run mattstack-checks | tail -1
+./build.sh dev 2>&1 | tail -8      # bundle assembles, Sparkle embedded + signed, two agent plists
+ls mattstack-dev.app/Contents/Frameworks mattstack-dev.app/Contents/Library/LaunchAgents
+codesign --verify --strict mattstack-dev.app && echo SIGN_OK
+```
+Expected: `Build complete!`, checks pass, `Sparkle.framework`, `com.mattstack.daemon.dev.plist com.mattstack.deck.dev.plist`, `SIGN_OK`. Do NOT launch the app (orchestrator-only, Task 20).
+
+- [ ] **Step 8: Commit**
+```bash
+git add -A rt-tray/Package.swift rt-tray/Package.resolved rt-tray/Sources rt-tray/Sources-core rt-tray/Tests rt-tray/build.sh rt-tray/check-bundle.sh
+git commit -m "MAT-383: Sparkle UpdaterController (gentle reminders, idle install, dev off); UpdateChecker retired; bundle launch stopgap
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 11: InstallRunModel — apply stream → step list, logs, need handling, retry-from
+
+**Files:**
+- Modify: `rt-tray/Sources-core/Contract/ApplyEvents.swift` (add `ApplyEvent`, `StepInfo`, `StepKind`, `StepState`)
+- Create: `rt-tray/Sources-core/Install/InstallRunModel.swift`
+- Create: `rt-tray/Tests/MattstackCoreChecks/InstallRunChecks.swift`; modify `AllChecks.swift`
+
+**Interfaces:**
+- Produces:
+  - `public enum StepKind: String, Codable { rt, app, privileged }`, `public enum StepState: String, Codable { pending, running, done, failed, skipped }`, `public struct StepInfo: Codable, Equatable, Identifiable { id, title, kind }`
+  - `public enum ApplyEvent: Equatable { plan([StepInfo]); step(id: String, state: StepState, detail: String?, remedy: String?); log(id: String, line: String); need(id: String, request: NeedRequest); done(ok: Bool, failedStep: String?); unknown(String) }` + `public static func decode(_ line: String) throws -> ApplyEvent`
+  - `public typealias ApplyStreamFactory = @Sendable (_ from: String?) -> AsyncThrowingStream<String, Error>`
+  - `public struct InstallStep: Equatable, Identifiable { info: StepInfo; state: StepState; detail: String?; remedy: String?; waitingOnYou: Bool; var id: String }`
+  - `@MainActor public final class InstallRunModel: ObservableObject` — `init(stream: @escaping ApplyStreamFactory, needs: NeedBroker)`; `@Published steps: [InstallStep]`, `phase: Phase` (`idle | running | succeeded | failed(stepId: String, remedy: String?) | streamError(String)`), `logs: [String: [String]]`; `func start(from: String? = nil)`; `func retryFromFailure()`; `func logLines(for id: String) -> [String]`; `var failedStepId: String?`; `var isRunning: Bool`; `static func apply(_ event: ApplyEvent, to steps: inout [InstallStep])` (pure reducer).
+
+- [ ] **Step 1: Failing checks**
+
+`rt-tray/Tests/MattstackCoreChecks/InstallRunChecks.swift`:
+```swift
+import Foundation
+import MattstackCore
+
+func lines(_ s: [String]) -> AsyncThrowingStream<String, Error> {
+    AsyncThrowingStream { cont in for l in s { cont.yield(l) }; cont.finish() }
+}
+let planLine = #"{"event":"plan","steps":[{"id":"home.init","title":"Home repo","kind":"rt"},{"id":"services.register","title":"Register services","kind":"app"},{"id":"plugins.install","title":"Plugins","kind":"rt"}]}"#
+
+let installRunChecks: [Check] = [
+    Check("ApplyEvent decodes every contract event and tolerates unknown ones") { c in
+        c.expectEqual(try ApplyEvent.decode(#"{"event":"step","id":"home.init","state":"running"}"#), .step(id: "home.init", state: .running, detail: nil, remedy: nil))
+        c.expectEqual(try ApplyEvent.decode(#"{"event":"log","id":"home.init","line":"gh repo create"}"#), .log(id: "home.init", line: "gh repo create"))
+        c.expectEqual(try ApplyEvent.decode(#"{"event":"need","id":"proxy.install","request":{"type":"app-privileged","op":"proxy-install"}}"#),
+                      .need(id: "proxy.install", request: NeedRequest(type: "app-privileged", plists: nil, op: "proxy-install")))
+        c.expectEqual(try ApplyEvent.decode(#"{"event":"done","ok":false,"failedStep":"plugins.install"}"#), .done(ok: false, failedStep: "plugins.install"))
+        c.expectEqual(try ApplyEvent.decode(#"{"event":"spark","x":1}"#), .unknown("spark"))
+        if case .plan(let steps) = try ApplyEvent.decode(planLine) { c.expectEqual(steps.count, 3); c.expectEqual(steps[1].kind, .app) } else { c.fail("plan") }
+    },
+    Check("reducer: plan seeds pending steps; step events update state/detail/remedy") { c in
+        var steps: [InstallStep] = []
+        InstallRunModel.apply(try ApplyEvent.decode(planLine), to: &steps)
+        c.expectEqual(steps.map(\.state), [.pending, .pending, .pending])
+        InstallRunModel.apply(.step(id: "home.init", state: .running, detail: nil, remedy: nil), to: &steps)
+        InstallRunModel.apply(.step(id: "home.init", state: .done, detail: "pushed main", remedy: nil), to: &steps)
+        InstallRunModel.apply(.step(id: "plugins.install", state: .failed, detail: "exit 1", remedy: "Open Claude Code once, then Retry."), to: &steps)
+        c.expectEqual(steps[0].state, .done); c.expectEqual(steps[0].detail, "pushed main")
+        c.expectEqual(steps[2].state, .failed); c.expectEqual(steps[2].remedy, "Open Claude Code once, then Retry.")
+        InstallRunModel.apply(.need(id: "services.register", request: NeedRequest(type: "app-register-services", plists: ["a"], op: nil)), to: &steps)
+        c.expectEqual(steps[1].waitingOnYou, true)
+    },
+    Check("a full happy stream ends succeeded, need events are performed through the broker, logs are kept per step") { c in
+        let services = FakeServices(), privileged = FakePrivileged()
+        let broker = NeedBroker(services: services, privileged: privileged)
+        let stream: ApplyStreamFactory = { _ in lines([
+            planLine,
+            #"{"event":"step","id":"home.init","state":"running"}"#,
+            #"{"event":"log","id":"home.init","line":"gh repo create"}"#,
+            #"{"event":"step","id":"home.init","state":"done","detail":"pushed main"}"#,
+            #"{"event":"step","id":"services.register","state":"running"}"#,
+            #"{"event":"need","id":"services.register","request":{"type":"app-register-services","plists":["com.mattstack.daemon.plist"]}}"#,
+            #"{"event":"step","id":"services.register","state":"done"}"#,
+            #"{"event":"step","id":"plugins.install","state":"running"}"#,
+            #"{"event":"step","id":"plugins.install","state":"done"}"#,
+            #"{"event":"done","ok":true,"failedStep":null}"#,
+        ]) }
+        let m = await MainActor.run { InstallRunModel(stream: stream, needs: broker) }
+        await MainActor.run { m.start() }
+        for _ in 0..<50 { if await MainActor.run(body: { m.phase == .succeeded }) { break }; try await Task.sleep(nanoseconds: 20_000_000) }
+        await MainActor.run {
+            c.expectEqual(m.phase, .succeeded)
+            c.expectEqual(m.logLines(for: "home.init"), ["gh repo create"])
+            c.expectEqual(m.steps.map(\.state), [.done, .done, .done])
+        }
+        c.expectEqual(services.registered, [["com.mattstack.daemon.plist"]])
+    },
+    Check("a failed step stops the run with its remedy; retryFromFailure re-streams with --from and forgets the need") { c in
+        final class Count: @unchecked Sendable { var froms: [String?] = [] }
+        let count = Count()
+        let broker = NeedBroker(services: FakeServices(), privileged: FakePrivileged())
+        let stream: ApplyStreamFactory = { from in
+            count.froms.append(from)
+            if from == nil {
+                return lines([planLine,
+                              #"{"event":"step","id":"plugins.install","state":"failed","detail":"exit 1","remedy":"Open Claude Code once, then Retry."}"#,
+                              #"{"event":"done","ok":false,"failedStep":"plugins.install"}"#])
+            }
+            return lines([#"{"event":"plan","steps":[{"id":"plugins.install","title":"Plugins","kind":"rt"}]}"#,
+                          #"{"event":"step","id":"plugins.install","state":"done"}"#,
+                          #"{"event":"done","ok":true,"failedStep":null}"#])
+        }
+        let m = await MainActor.run { InstallRunModel(stream: stream, needs: broker) }
+        await MainActor.run { m.start() }
+        for _ in 0..<50 { if await MainActor.run(body: { m.failedStepId != nil }) { break }; try await Task.sleep(nanoseconds: 20_000_000) }
+        await MainActor.run {
+            c.expectEqual(m.phase, .failed(stepId: "plugins.install", remedy: "Open Claude Code once, then Retry."))
+            m.retryFromFailure()
+        }
+        for _ in 0..<50 { if await MainActor.run(body: { m.phase == .succeeded }) { break }; try await Task.sleep(nanoseconds: 20_000_000) }
+        await MainActor.run {
+            c.expectEqual(m.phase, .succeeded)
+            c.expectEqual(m.steps.map(\.id), ["home.init", "services.register", "plugins.install"], "earlier steps keep their rows")
+            c.expectEqual(m.steps[2].state, .done)
+        }
+        c.expectEqual(count.froms, [nil, "plugins.install"])
+    },
+    Check("a stream error surfaces as streamError") { c in
+        let stream: ApplyStreamFactory = { _ in AsyncThrowingStream { $0.finish(throwing: RtClientError.exited(1, stderr: "boom")) } }
+        let m = await MainActor.run { InstallRunModel(stream: stream, needs: NeedBroker(services: FakeServices(), privileged: FakePrivileged())) }
+        await MainActor.run { m.start() }
+        for _ in 0..<50 { if await MainActor.run(body: { if case .streamError = m.phase { return true }; return false }) { break }; try await Task.sleep(nanoseconds: 20_000_000) }
+        await MainActor.run { if case .streamError(let s) = m.phase { c.expect(s.contains("boom")) } else { c.fail("expected streamError, got \(m.phase)") } }
+    },
+]
+```
+
+- [ ] **Step 2: Run → compile failure.**
+
+- [ ] **Step 3: Implement**
+
+Append to `rt-tray/Sources-core/Contract/ApplyEvents.swift`:
+```swift
+public enum StepKind: String, Codable, Equatable, Sendable { case rt, app, privileged }
+public enum StepState: String, Codable, Equatable, Sendable { case pending, running, done, failed, skipped }
+
+public struct StepInfo: Codable, Equatable, Identifiable, Sendable {
+    public var id: String
+    public var title: String
+    public var kind: StepKind
+    public init(id: String, title: String, kind: StepKind) { self.id = id; self.title = title; self.kind = kind }
+}
+
+public enum ApplyEvent: Equatable, Sendable {
+    case plan([StepInfo])
+    case step(id: String, state: StepState, detail: String?, remedy: String?)
+    case log(id: String, line: String)
+    case need(id: String, request: NeedRequest)
+    case done(ok: Bool, failedStep: String?)
+    case unknown(String)
+
+    private struct Raw: Decodable {
+        let event: String
+        let steps: [StepInfo]?
+        let id: String?
+        let state: StepState?
+        let detail: String?
+        let remedy: String?
+        let line: String?
+        let request: NeedRequest?
+        let ok: Bool?
+        let failedStep: String?
+    }
+
+    public static func decode(_ line: String) throws -> ApplyEvent {
+        let r = try JSONDecoder().decode(Raw.self, from: Data(line.utf8))
+        switch r.event {
+        case "plan": return .plan(r.steps ?? [])
+        case "step": return .step(id: r.id ?? "", state: r.state ?? .pending, detail: r.detail, remedy: r.remedy)
+        case "log": return .log(id: r.id ?? "", line: r.line ?? "")
+        case "need": return .need(id: r.id ?? "", request: r.request ?? NeedRequest(type: "", plists: nil, op: nil))
+        case "done": return .done(ok: r.ok ?? false, failedStep: r.failedStep)
+        default: return .unknown(r.event)
+        }
+    }
+}
+```
+
+`rt-tray/Sources-core/Install/InstallRunModel.swift`:
+```swift
+import Foundation
+import Combine
+
+public typealias ApplyStreamFactory = @Sendable (_ from: String?) -> AsyncThrowingStream<String, Error>
+
+public struct InstallStep: Equatable, Identifiable, Sendable {
+    public var info: StepInfo
+    public var state: StepState
+    public var detail: String?
+    public var remedy: String?
+    public var waitingOnYou: Bool
+    public var id: String { info.id }
+    public init(info: StepInfo, state: StepState = .pending, detail: String? = nil, remedy: String? = nil, waitingOnYou: Bool = false) {
+        self.info = info; self.state = state; self.detail = detail; self.remedy = remedy; self.waitingOnYou = waitingOnYou
+    }
+}
+
+/// Renders `rt setup apply --json`. Steps come only from the stream's plan
+/// event; the app executes `need` events through NeedBroker and otherwise
+/// just shows what rt says. Retry resumes from the failed step and keeps
+/// the earlier rows so the list never "forgets" what already happened.
+@MainActor
+public final class InstallRunModel: ObservableObject {
+    public enum Phase: Equatable, Sendable {
+        case idle, running, succeeded
+        case failed(stepId: String, remedy: String?)
+        case streamError(String)
+    }
+
+    @Published public private(set) var steps: [InstallStep] = []
+    @Published public private(set) var phase: Phase = .idle
+    @Published public private(set) var logs: [String: [String]] = [:]
+
+    private let stream: ApplyStreamFactory
+    private let needs: NeedBroker
+    private var task: Task<Void, Never>?
+    public static let logCapPerStep = 500
+
+    public init(stream: @escaping ApplyStreamFactory, needs: NeedBroker) {
+        self.stream = stream
+        self.needs = needs
+    }
+
+    public var isRunning: Bool { phase == .running }
+    public var failedStepId: String? { if case .failed(let id, _) = phase { return id }; return nil }
+    public func logLines(for id: String) -> [String] { logs[id] ?? [] }
+
+    public func start(from: String? = nil) {
+        task?.cancel()
+        phase = .running
+        if from == nil { steps = []; logs = [:] }
+        let stream = self.stream(from)
+        task = Task { [weak self] in
+            do {
+                for try await line in stream {
+                    guard let self else { return }
+                    let event: ApplyEvent
+                    do { event = try ApplyEvent.decode(line) } catch { self.append(log: "unparsed: \(line)", to: "_stream"); continue }
+                    await self.handle(event)
+                }
+                guard let self, self.phase == .running else { return }
+                self.phase = .streamError("rt setup apply ended without a done event")
+            } catch {
+                self?.phase = .streamError(String(describing: error))
+            }
+        }
+    }
+
+    public func retryFromFailure() {
+        guard let id = failedStepId else { return }
+        Task { await needs.forget(id: id) }
+        start(from: id)
+    }
+
+    private func handle(_ event: ApplyEvent) async {
+        Self.apply(event, to: &steps)
+        switch event {
+        case .log(let id, let line):
+            append(log: line, to: id)
+        case .need(let id, let request):
+            let result = await needs.perform(id: id, request: request)
+            append(log: "\(request.type): \(result.detail)", to: id)
+            if let i = steps.firstIndex(where: { $0.id == id }) {
+                steps[i].waitingOnYou = false
+                if !result.ok { steps[i].detail = result.detail }
+            }
+        case .done(let ok, let failedStep):
+            if ok { phase = .succeeded }
+            else {
+                let id = failedStep ?? steps.last(where: { $0.state == .failed })?.id ?? "?"
+                phase = .failed(stepId: id, remedy: steps.first(where: { $0.id == id })?.remedy)
+            }
+        default:
+            break
+        }
+    }
+
+    private func append(log line: String, to id: String) {
+        var arr = logs[id] ?? []
+        arr.append(line)
+        if arr.count > Self.logCapPerStep { arr.removeFirst(arr.count - Self.logCapPerStep) }
+        logs[id] = arr
+    }
+
+    /// Pure reducer, shared with the checks. A `plan` after a retry merges by
+    /// id: existing rows keep their place, new ids append.
+    public static func apply(_ event: ApplyEvent, to steps: inout [InstallStep]) {
+        switch event {
+        case .plan(let infos):
+            for info in infos {
+                if let i = steps.firstIndex(where: { $0.id == info.id }) {
+                    steps[i].info = info
+                    steps[i].state = .pending
+                    steps[i].remedy = nil
+                    steps[i].waitingOnYou = false
+                } else {
+                    steps.append(InstallStep(info: info))
+                }
+            }
+        case .step(let id, let state, let detail, let remedy):
+            guard let i = steps.firstIndex(where: { $0.id == id }) else { return }
+            steps[i].state = state
+            if let detail { steps[i].detail = detail }
+            if let remedy { steps[i].remedy = remedy }
+            if state != .running { steps[i].waitingOnYou = false }
+        case .need(let id, _):
+            if let i = steps.firstIndex(where: { $0.id == id }) { steps[i].waitingOnYou = true }
+        case .log, .done, .unknown:
+            break
+        }
+    }
+}
+```
+(`FakeServices`/`FakePrivileged` are reused from Task 9's check file — same module, no duplication.)
+
+- [ ] **Step 4: Run checks → pass. Commit**
+```bash
+git add rt-tray/Sources-core rt-tray/Tests
+git commit -m "MAT-383: InstallRunModel — apply NDJSON → live step list, need execution, retry-from-failed
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 12: Setup window shell — flow model, fixed window, footer, Welcome screen
+
+**Files:**
+- Create: `rt-tray/Sources-core/Setup/SetupFlowModel.swift`
+- Create: `rt-tray/Sources/AccessibilityIDs.swift`, `rt-tray/Sources/Setup/SetupSession.swift`, `rt-tray/Sources/Setup/SetupWindowController.swift`, `rt-tray/Sources/Setup/SetupView.swift`, `rt-tray/Sources/Setup/Screens/WelcomeScreen.swift`, `rt-tray/Sources/Setup/Components/StatusBadge.swift`
+- Create: `rt-tray/Tests/MattstackCoreChecks/SetupFlowChecks.swift`; modify `AllChecks.swift`
+
+**Interfaces:**
+- Produces (Core): `public enum SetupStep: Int, CaseIterable, Sendable { welcome, team, checklist, install, done }` with `title: String`, `indicator: String` ("Step n of 5"); `@MainActor public final class SetupFlowModel: ObservableObject` — `@Published step: SetupStep`, `@Published isInstalling: Bool`; `var canGoBack: Bool` (false on welcome, install-while-running, done), `var continueTitle: String` ("Continue" / "Install" on checklist / "Finish" on done), `func next()`, `func back()`, `func jump(to:)`, `var windowMayClose: Bool` (only on done).
+- Produces (app): `enum AXID` — **the single list of accessibility identifiers** every interactive control and row in the Setup and Settings windows carries (L7 drives the UI through System Events until Xcode exists and reads the same names from this file). Convention `setup.<screen>.<element>` / `settings.<pane>.<element>`; dynamic rows use functions (`AXID.checklistRow("perm.fda")` → `setup.checklist.row.perm.fda`, `.checklistRowAction(...)` → `…action`, `.checklistRowStatus(...)` → `…status`, `.installStep(id)`, `.installStepLog(id)`, `.connectField(name)`, `.connectAlternative(id)`, `.settingsPermissionAction(id)`). Screen-level continue/back are per screen: `setup.<screen>.continue`, `setup.<screen>.back`, `setup.checklist.continueLimited`. `enum SetupSession { static var isRunning: Bool }` (true while the Setup window exists and step != done — the updater's idle gate); `final class SetupWindowController: NSWindowController` — `init(environment: SetupEnvironment)`; `func show(step: SetupStep? = nil, joinCode: String? = nil)`; `let flow: SetupFlowModel`, `let team: TeamChoiceModel`; `struct SetupEnvironment { rt: RtRunning; readiness: ReadinessModel; install: InstallRunModel; permissions: PermissionsService; isDevBuild: Bool; bundleId: String; bundlePath: String }`; `struct SetupView: View`; `struct StatusBadge: View` (RowStatus → glyph per spec); `struct SetupFooter: View` (Back / Continue `.keyboardShortcut(.defaultAction)` `.controlSize(.large)`).
+
+- [ ] **Step 1: Failing checks**
+
+`rt-tray/Tests/MattstackCoreChecks/SetupFlowChecks.swift`:
+```swift
+import Foundation
+import MattstackCore
+
+let setupFlowChecks: [Check] = [
+    Check("SetupStep order, titles, indicator") { c in
+        c.expectEqual(SetupStep.allCases.map(\.rawValue), [0, 1, 2, 3, 4])
+        c.expectEqual(SetupStep.checklist.indicator, "Step 3 of 5")
+        c.expectEqual(SetupStep.team.title, "Your team")
+        c.expectEqual(SetupStep.checklist.title, "Before we begin")
+    },
+    Check("flow: next/back bounds, continue titles, back disabled on welcome/install-running/done, close only on done") { c in
+        await MainActor.run {
+            let f = SetupFlowModel()
+            c.expectEqual(f.step, .welcome)
+            c.expectEqual(f.canGoBack, false)
+            c.expectEqual(f.windowMayClose, false)
+            f.back(); c.expectEqual(f.step, .welcome)
+            f.next(); c.expectEqual(f.step, .team); c.expectEqual(f.canGoBack, true)
+            f.next(); c.expectEqual(f.step, .checklist); c.expectEqual(f.continueTitle, "Install")
+            f.next(); c.expectEqual(f.step, .install)
+            f.isInstalling = true; c.expectEqual(f.canGoBack, false)
+            f.isInstalling = false; c.expectEqual(f.canGoBack, true)
+            f.next(); c.expectEqual(f.step, .done); c.expectEqual(f.continueTitle, "Finish")
+            c.expectEqual(f.canGoBack, false); c.expectEqual(f.windowMayClose, true)
+            f.next(); c.expectEqual(f.step, .done)
+            f.jump(to: .team); c.expectEqual(f.step, .team)
+        }
+    },
+]
+```
+
+- [ ] **Step 2: Run → compile failure. Implement Core**
+
+`rt-tray/Sources-core/Setup/SetupFlowModel.swift`:
+```swift
+import Foundation
+import Combine
+
+public enum SetupStep: Int, CaseIterable, Sendable {
+    case welcome, team, checklist, install, done
+
+    public var title: String {
+        switch self {
+        case .welcome: return "Welcome to mattstack"
+        case .team: return "Your team"
+        case .checklist: return "Before we begin"
+        case .install: return "Installing"
+        case .done: return "Everything's working"
+        }
+    }
+    public var indicator: String { "Step \(rawValue + 1) of \(SetupStep.allCases.count)" }
+}
+
+/// Custom page model (spec §4): push transitions, Back never dismisses,
+/// the window only closes once setup is done.
+@MainActor
+public final class SetupFlowModel: ObservableObject {
+    @Published public var step: SetupStep = .welcome
+    @Published public var isInstalling = false
+    public init() {}
+
+    public var canGoBack: Bool {
+        switch step {
+        case .welcome, .done: return false
+        case .install: return !isInstalling
+        default: return true
+        }
+    }
+    public var continueTitle: String {
+        switch step {
+        case .checklist: return "Install"
+        case .done: return "Finish"
+        default: return "Continue"
+        }
+    }
+    public var windowMayClose: Bool { step == .done }
+
+    public func next() { if let n = SetupStep(rawValue: step.rawValue + 1) { step = n } }
+    public func back() { guard canGoBack, let p = SetupStep(rawValue: step.rawValue - 1) else { return }; step = p }
+    public func jump(to s: SetupStep) { step = s }
+}
+```
+Run checks → pass.
+
+- [ ] **Step 3: App shell — accessibility ids, session flag, window controller, view, footer, welcome**
+
+`rt-tray/Sources/AccessibilityIDs.swift` (every id in the app lives here; add, never inline a literal):
+```swift
+import Foundation
+
+/// Stable accessibility identifiers. L7's clean-room walkthrough drives the
+/// UI by these names through System Events, so they are a contract: rename
+/// only with L7.
+enum AXID {
+    // Setup window chrome
+    static let stepIndicator = "setup.window.stepIndicator"
+    static func `continue`(_ screen: String) -> String { "setup.\(screen).continue" }
+    static func back(_ screen: String) -> String { "setup.\(screen).back" }
+    static let continueLimited = "setup.checklist.continueLimited"
+
+    // Screens (the root view of each)
+    static let welcomeScreen = "setup.welcome.screen"
+    static let teamScreen = "setup.team.screen"
+    static let checklistScreen = "setup.checklist.screen"
+    static let installScreen = "setup.install.screen"
+    static let doneScreen = "setup.done.screen"
+
+    // Your team
+    static let teamCardCreate = "setup.team.card.create"
+    static let teamCardJoin = "setup.team.card.join"
+    static let teamCardRestore = "setup.team.card.restore"
+    static let teamCreateName = "setup.team.create.name"
+    static let teamCreateOthers = "setup.team.create.others"
+    static let teamCreateUseGh = "setup.team.create.useGh"
+    static let teamCreateOwner = "setup.team.create.owner"
+    static let teamCreateRemote = "setup.team.create.remote"
+    static let teamJoinCode = "setup.team.join.code"
+    static let teamRestoreRepo = "setup.team.restore.repo"
+    static let teamRestoreKey = "setup.team.restore.key"
+
+    // Checklist
+    static func checklistRow(_ id: String) -> String { "setup.checklist.row.\(id)" }
+    static func checklistRowAction(_ id: String) -> String { "setup.checklist.row.\(id).action" }
+    static func checklistRowStatus(_ id: String) -> String { "setup.checklist.row.\(id).status" }
+    static let checklistRecheck = "setup.checklist.recheck"
+    static let checklistRelaunch = "setup.checklist.relaunch"
+    static func connectField(_ name: String) -> String { "setup.checklist.connect.field.\(name)" }
+    static func connectAlternative(_ id: String) -> String { "setup.checklist.connect.alt.\(id)" }
+    static let connectSubmit = "setup.checklist.connect.submit"
+    static let connectCancel = "setup.checklist.connect.cancel"
+    static let stepsDone = "setup.checklist.steps.done"
+
+    // Install
+    static func installStep(_ id: String) -> String { "setup.install.step.\(id)" }
+    static func installStepLog(_ id: String) -> String { "setup.install.step.\(id).log" }
+    static let installRetry = "setup.install.retry"
+    static let installRetryStream = "setup.install.retryStream"
+    static let logCopy = "setup.install.log.copy"
+    static let logDone = "setup.install.log.done"
+
+    // Done
+    static let doneOpenBoard = "setup.done.openBoard"
+    static let doneInvite = "setup.done.invite"
+
+    // Settings
+    static let settingsGeneralStartAtLogin = "settings.general.startAtLogin"
+    static let settingsGeneralAutoUpdates = "settings.general.autoUpdates"
+    static let settingsGeneralCheckNow = "settings.general.checkNow"
+    static let settingsGeneralDevMode = "settings.general.devMode"
+    static func settingsPermissionAction(_ id: String) -> String { "settings.permissions.row.\(id).action" }
+    static let settingsPermissionsReset = "settings.permissions.reset"
+    static let settingsTeamInviteHandle = "settings.team.inviteHandle"
+    static let settingsTeamInvite = "settings.team.invite"
+    static let settingsTeamCopyPaste = "settings.team.copyPasteBlock"
+    static let settingsTeamJoinAnother = "settings.team.joinAnother"
+    static let settingsUninstall = "settings.uninstall.button"
+    static let settingsUninstallConfirm = "settings.uninstall.confirm"
+    static let settingsUninstallKeepData = "settings.uninstall.keepData"
+}
+```
+
+`rt-tray/Sources/Setup/SetupSession.swift`:
+```swift
+import Foundation
+
+/// Process-wide "setup is in progress" flag: the updater's idle gate reads it
+/// and the window controller owns it.
+enum SetupSession {
+    static var isRunning = false
+}
+```
+
+`rt-tray/Sources/Setup/Components/StatusBadge.swift`:
+```swift
+import SwiftUI
+import MattstackCore
+
+struct StatusBadge: View {
+    let status: RowStatus
+    var id: String? = nil
+    var body: some View {
+        let symbol = StatusGlyph.symbol(for: status)
+        Group {
+            if symbol == "progress" {
+                ProgressView().controlSize(.small)
+            } else {
+                Image(systemName: symbol).foregroundStyle(color)
+            }
+        }
+        .frame(width: 20, height: 20)
+        .accessibilityLabel(Text(status.rawValue))
+        .accessibilityValue(Text(status.rawValue))
+        .accessibilityIdentifier(id ?? "")
+    }
+    private var color: Color {
+        switch StatusGlyph.tint(for: status) {
+        case .green: return .green
+        case .red: return .red
+        case .yellow: return .yellow
+        case .grey: return .secondary
+        case .none: return .primary
+        }
+    }
+}
+```
+
+`rt-tray/Sources/Setup/SetupWindowController.swift`:
+```swift
+import AppKit
+import SwiftUI
+import Combine
+import MattstackCore
+
+struct SetupEnvironment {
+    let rt: RtRunning
+    let readiness: ReadinessModel
+    let install: InstallRunModel
+    let permissions: PermissionsService
+    let isDevBuild: Bool
+    let bundleId: String
+    let bundlePath: String
+}
+
+/// One dedicated NSWindow hosting SwiftUI (AppKit lifecycle stays). ~560 pt
+/// wide, fixed; close/minimize appear only once setup is done.
+final class SetupWindowController: NSWindowController, NSWindowDelegate {
+    static let width: CGFloat = 560
+    let flow = SetupFlowModel()
+    let team: TeamChoiceModel
+    private let environment: SetupEnvironment
+    private var activeObserver: Any?
+    private var cancellables = Set<AnyCancellable>()
+
+    init(environment: SetupEnvironment) {
+        self.environment = environment
+        self.team = TeamChoiceModel(rt: environment.rt)
+        let window = NSWindow(contentRect: NSRect(x: 0, y: 0, width: Self.width, height: 620),
+                              styleMask: [.titled], backing: .buffered, defer: false)
+        window.title = "mattstack Setup"
+        window.isReleasedWhenClosed = false
+        window.center()
+        super.init(window: window)
+        window.delegate = self
+        let root = SetupView(flow: flow, team: team, readiness: environment.readiness, install: environment.install,
+                             permissions: environment.permissions, env: environment)
+        window.contentViewController = NSHostingController(rootView: root)
+        window.setContentSize(NSSize(width: Self.width, height: 620))
+        flow.objectWillChange.sink { [weak self] _ in DispatchQueue.main.async { self?.applyStyle() } }
+            .store(in: &cancellables)
+    }
+    required init?(coder: NSCoder) { fatalError("not supported") }
+
+    func show(step: SetupStep? = nil, joinCode: String? = nil) {
+        if let step { flow.jump(to: step) }
+        if let joinCode { team.choice = .join; team.inviteCode = joinCode }
+        SetupSession.isRunning = true
+        applyStyle()
+        showWindow(nil)
+        window?.makeKeyAndOrderFront(nil)
+        NSApp.activate(ignoringOtherApps: true)
+        activeObserver = NotificationCenter.default.addObserver(forName: NSApplication.didBecomeActiveNotification, object: nil, queue: .main) { [weak self] _ in
+            self?.environment.readiness.didBecomeActive()
+        }
+    }
+
+    private func applyStyle() {
+        guard let window else { return }
+        var mask: NSWindow.StyleMask = [.titled]
+        if flow.windowMayClose { mask.insert([.closable, .miniaturizable]) }
+        window.styleMask = mask
+        SetupSession.isRunning = !flow.windowMayClose
+    }
+
+    func windowWillClose(_ notification: Notification) {
+        SetupSession.isRunning = false
+        environment.readiness.becameHidden()
+        if let o = activeObserver { NotificationCenter.default.removeObserver(o) }
+    }
+}
+```
+
+`rt-tray/Sources/Setup/SetupView.swift`:
+```swift
+import SwiftUI
+import MattstackCore
+
+struct SetupView: View {
+    @ObservedObject var flow: SetupFlowModel
+    @ObservedObject var team: TeamChoiceModel
+    @ObservedObject var readiness: ReadinessModel
+    @ObservedObject var install: InstallRunModel
+    let permissions: PermissionsService
+    let env: SetupEnvironment
+    @State private var busy = false
+    @State private var errorText: String?
+
+    var body: some View {
+        VStack(spacing: 0) {
+            header
+            Divider()
+            ZStack {
+                switch flow.step {
+                case .welcome: WelcomeScreen().transition(pushTransition)
+                case .team: TeamScreen(model: team).transition(pushTransition)
+                case .checklist: ChecklistScreen(model: readiness, permissions: permissions, rt: env.rt, bundleId: env.bundleId).transition(pushTransition)
+                case .install: InstallScreen(model: install).transition(pushTransition)
+                case .done: DoneScreen(install: install, isOwner: team.choice == .create, onInvite: { NotificationCenter.default.post(name: .rtShowSettingsTeam, object: nil) }).transition(pushTransition)
+                }
+            }
+            .animation(.easeInOut(duration: 0.22), value: flow.step)
+            .frame(maxWidth: .infinity, maxHeight: .infinity)
+            Divider()
+            footer
+        }
+        .frame(width: SetupWindowController.width)
+        .frame(minHeight: 560)
+        .controlSize(.large)
+        .onChange(of: flow.step) { _, step in
+            if step == .checklist { readiness.becameVisible(); Task { await readiness.load() } } else { readiness.becameHidden() }
+            if step == .install { flow.isInstalling = true; install.start() }
+        }
+        .onChange(of: install.phase) { _, phase in
+            flow.isInstalling = (phase == .running)
+            if phase == .succeeded { flow.next() }
+        }
+    }
+
+    private var pushTransition: AnyTransition {
+        .asymmetric(insertion: .move(edge: .trailing).combined(with: .opacity), removal: .move(edge: .leading).combined(with: .opacity))
+    }
+
+    private var header: some View {
+        HStack {
+            Text(flow.step.title).font(.title2.weight(.semibold))
+            Spacer()
+            Text(flow.step.indicator).font(.caption).foregroundStyle(.secondary)
+                .accessibilityIdentifier(AXID.stepIndicator)
+        }
+        .padding(.horizontal, 20).padding(.vertical, 14)
+    }
+
+    private var footer: some View {
+        HStack {
+            if let errorText { Text(errorText).font(.caption).foregroundStyle(.red).lineLimit(2) }
+            Spacer()
+            if flow.canGoBack {
+                Button("Back") { flow.back() }.accessibilityIdentifier(AXID.back(screenName))
+            }
+            if flow.step == .checklist, readiness.limitedModeAvailable {
+                Button("Continue in limited mode") { flow.next() }.accessibilityIdentifier(AXID.continueLimited)
+            }
+            Button(flow.continueTitle) { Task { await advance() } }
+                .keyboardShortcut(.defaultAction)
+                .disabled(!continueEnabled || busy)
+                .accessibilityIdentifier(AXID.continue(screenName))
+        }
+        .padding(.horizontal, 20).padding(.vertical, 12)
+    }
+
+    private var screenName: String { String(describing: flow.step) }
+
+    private var continueEnabled: Bool {
+        switch flow.step {
+        case .welcome: return true
+        case .team: return team.canContinue
+        case .checklist: return readiness.canInstall
+        case .install: return install.phase == .succeeded
+        case .done: return true
+        }
+    }
+
+    private func advance() async {
+        errorText = nil
+        switch flow.step {
+        case .team:
+            busy = true; defer { busy = false }
+            if let err = await team.validateAndPrepare() { errorText = err; return }
+            flow.next()
+        case .done:
+            NSApp.keyWindow?.close()
+        default:
+            flow.next()
+        }
+    }
+}
+
+extension Notification.Name {
+    static let rtShowSettingsTeam = Notification.Name("rtShowSettingsTeam")
+}
+```
+(`TeamScreen`, `ChecklistScreen`, `InstallScreen`, `DoneScreen`, `TeamChoiceModel` arrive in Tasks 13–16. To keep this task building, create them as minimal placeholders in their final files now — `struct TeamScreen: View { @ObservedObject var model: TeamChoiceModel; var body: some View { Text("team") } }` etc. — and `TeamChoiceModel` with `choice`, `inviteCode`, `canContinue`, `validateAndPrepare()` stubs returning nil — each replaced wholesale in its own task. Stubs must be committed with a one-line `// replaced in Task N` marker so the reviewer of this task knows they are scaffolding; the later task deletes the marker.)
+
+`rt-tray/Sources/Setup/Screens/WelcomeScreen.swift`:
+```swift
+import SwiftUI
+
+struct WelcomeScreen: View {
+    private let bullets: [(String, String)] = [
+        ("terminal", "Install the rt command into ~/.local/bin and add one PATH line to your shell rc."),
+        ("gearshape.2", "Run background services: the rt daemon, deck, board, and gitq."),
+        ("sparkles", "Install the mattstack skills into Claude Code."),
+        ("puzzlepiece.extension", "Install the editor extension."),
+        ("lock.shield", "Ask for Full Disk Access and background-item approval."),
+    ]
+    var body: some View {
+        VStack(alignment: .leading, spacing: 18) {
+            HStack(spacing: 12) {
+                Image(nsImage: NSApp.applicationIconImage).resizable().frame(width: 56, height: 56)
+                Text("mattstack sets up your Mac for the team: one app, one menu-bar item, everything else underneath.")
+                    .font(.body)
+            }
+            Text("Setup will:").font(.headline)
+            ForEach(bullets, id: \.1) { b in
+                Label { Text(b.1) } icon: { Image(systemName: b.0).frame(width: 20) }
+            }
+            Spacer()
+            Text("Everything here is reversible from Settings → Uninstall.").font(.callout).foregroundStyle(.secondary)
+        }
+        .padding(24)
+        .accessibilityIdentifier(AXID.welcomeScreen)
+    }
+}
+```
+
+- [ ] **Step 4: `swift build` → Build complete; checks pass. Commit**
+```bash
+git add rt-tray/Sources-core rt-tray/Sources/Setup rt-tray/Tests
+git commit -m "MAT-383: Setup window shell — flow model, fixed 560pt window, footer, Welcome screen
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 13: "Your team" screen — create / join / restore cards, rt-validated Continue
+
+**Files:**
+- Create: `rt-tray/Sources-core/Setup/TeamChoiceModel.swift` (replaces the Task 12 stub), `rt-tray/Sources-core/Setup/Slug.swift`
+- Create/replace: `rt-tray/Sources/Setup/Screens/TeamScreen.swift`
+- Create: `rt-tray/Tests/MattstackCoreChecks/TeamChoiceChecks.swift`; modify `AllChecks.swift`
+
+**Interfaces:**
+- Produces (Core):
+  - `public enum Slug { static func make(_ name: String) -> String }` (lowercase, `[a-z0-9-]`, collapse dashes, trim)
+  - `public enum TeamChoice: Equatable, Sendable { create, join, restore }`
+  - `public struct GitHubStatus: Codable { status: RowStatus; handle: String?; owners: [String]? }` (from `rt setup github status --json`)
+  - `@MainActor public final class TeamChoiceModel: ObservableObject` — `init(rt: RtRunning)`; `@Published choice: TeamChoice = .create`, `teamName`, `othersWillJoin = true`, `useGhRepo: Bool`, `ghOwner: String?`, `ghOwners: [String]`, `ghHandle: String?`, `remoteURL`, `inviteCode`, `restoreRepo`, `restoreAgeKey`, `joinSummary: String?`, `isChecking`; `var slugPreview: String`; `var canContinue: Bool`; `func loadGitHubStatus() async`; `func validateAndPrepare() async -> String?` (nil = ok; otherwise the specific failure copy); `static func joinFailureCopy(_ error: RtUserError, owner: String?, team: String?) -> String`; `static let inviteCodeLength = 77`.
+  - Verbs called (contract): `rt setup github status --json` → `{status, handle, owners, …}` (L1 T12 adds `handle`/`owners`); `rt team create <name> (--remote <url> | --create-repo <owner>) [--others] --json` (create; with `useGhRepo` the app passes `--create-repo <owner>` and L1 names the repo `mattstack-team-<slug>`, which matches `ghRepoPreview`); `rt team join --dry-run --json` with stdin `{"code": "..."}` (exit 0 `{access:"ok"|"denied"|"unreachable", message}`; exit 2 only for `invite-unknown`/`invite-malformed`); **restore (ruling R3): the app runs the REAL `rt restore <org>/<repo> --json` with stdin `{"ageKey": "..."}` when the user presses Continue, then `rt setup intent restore <org>/<repo> --json`** (L1's `home.restore` apply step only verifies the clone + key; a `--dry-run` is used only if the settings lane ships `rt restore --dry-run --json`); `rt home init --dry-run --json` for the home-repo remote check (create and join both need the home repo).
+
+- [ ] **Step 1: Failing checks**
+
+`rt-tray/Tests/MattstackCoreChecks/TeamChoiceChecks.swift`:
+```swift
+import Foundation
+import MattstackCore
+
+final class ScriptedRt: RtRunning, @unchecked Sendable {
+    var answers: [String: (Int32, String)] = [:]   // key: args joined by space
+    var calls: [(args: [String], stdin: String?)] = []
+    func run(_ args: [String], stdin: Data?) async throws -> RtResult {
+        calls.append((args, stdin.map { String(decoding: $0, as: UTF8.self) }))
+        let key = args.joined(separator: " ")
+        let (code, out) = answers.first { key.hasPrefix($0.key) }?.value ?? (1, "")
+        return RtResult(exitCode: code, stdout: Data(out.utf8), stderr: Data())
+    }
+    func stream(_ args: [String], stdin: Data?) -> AsyncThrowingStream<String, Error> { AsyncThrowingStream { $0.finish() } }
+}
+
+let teamChoiceChecks: [Check] = [
+    Check("Slug.make") { c in
+        c.expectEqual(Slug.make("Assured Claims!"), "assured-claims")
+        c.expectEqual(Slug.make("  My  Team -- 2 "), "my-team-2")
+        c.expectEqual(Slug.make(""), "")
+    },
+    Check("create: slug preview, gh owner picker from github status, canContinue needs name + remote") { c in
+        let rt = ScriptedRt()
+        rt.answers["setup github status"] = (0, #"{"contract":1,"status":"ready","handle":"m4ttheweric","owners":["m4ttheweric","assured"]}"#)
+        let m = await MainActor.run { TeamChoiceModel(rt: rt) }
+        await m.loadGitHubStatus()
+        await MainActor.run {
+            c.expectEqual(m.ghHandle, "m4ttheweric")
+            c.expectEqual(m.ghOwners, ["m4ttheweric", "assured"])
+            c.expectEqual(m.useGhRepo, true)
+            c.expectEqual(m.ghOwner, "m4ttheweric")
+            c.expectEqual(m.canContinue, false)
+            m.teamName = "Assured Claims"
+            c.expectEqual(m.slugPreview, "assured-claims")
+            c.expectEqual(m.ghRepoPreview, "m4ttheweric/mattstack-team-assured-claims")
+            c.expectEqual(m.canContinue, true)
+            m.useGhRepo = false
+            c.expectEqual(m.canContinue, false, "URL field now required")
+            m.remoteURL = "git@gitlab.assured.com:tools/mattstack-team.git"
+            c.expectEqual(m.canContinue, true)
+        }
+    },
+    Check("create: validateAndPrepare calls home init --dry-run then team create, never with secrets on argv") { c in
+        let rt = ScriptedRt()
+        rt.answers["home init --dry-run"] = (0, #"{"contract":1,"ok":true}"#)
+        rt.answers["team create"] = (0, #"{"contract":1,"team":{"slug":"assured-claims","name":"Assured Claims"},"remote":"ok"}"#)
+        let m = await MainActor.run { TeamChoiceModel(rt: rt) }
+        await MainActor.run { m.choice = .create; m.teamName = "Assured Claims"; m.useGhRepo = false; m.remoteURL = "https://example.com/t.git" }
+        let err = await m.validateAndPrepare()
+        c.expect(err == nil, "got \(err ?? "")")
+        c.expectEqual(rt.calls[0].args.prefix(3), ["home", "init", "--dry-run"])
+        c.expectEqual(rt.calls[1].args, ["team", "create", "Assured Claims", "--remote", "https://example.com/t.git", "--others", "--json"])
+        let gh = ScriptedRt()
+        gh.answers["home init --dry-run"] = (0, #"{"contract":1,"ok":true}"#)
+        gh.answers["team create"] = (0, #"{"contract":1,"team":{"slug":"assured-claims","name":"Assured Claims"},"remote":"ok"}"#)
+        let m2 = await MainActor.run { TeamChoiceModel(rt: gh) }
+        await MainActor.run { m2.choice = .create; m2.teamName = "Assured Claims"; m2.useGhRepo = true; m2.ghOwner = "assured"; m2.othersWillJoin = false }
+        c.expect(await m2.validateAndPrepare() == nil)
+        c.expectEqual(gh.calls[1].args, ["team", "create", "Assured Claims", "--create-repo", "assured", "--json"])
+    },
+    Check("join: code goes on stdin; success summary; failure copy is specific") { c in
+        let rt = ScriptedRt()
+        rt.answers["team join --dry-run"] = (0, #"{"contract":1,"team":{"slug":"assured","name":"Assured","owner":"matt"},"access":"ok","peering":"idle","message":"Joining Assured (owner matt)"}"#)
+        rt.answers["home init --dry-run"] = (0, #"{"contract":1,"ok":true}"#)
+        let m = await MainActor.run { TeamChoiceModel(rt: rt) }
+        await MainActor.run { m.choice = .join; m.inviteCode = "ABCD-EFGH" }
+        let err = await m.validateAndPrepare()
+        c.expect(err == nil)
+        c.expectEqual(rt.calls[0].args, ["team", "join", "--dry-run", "--json"])
+        c.expectEqual(rt.calls[0].stdin, "{\"code\":\"ABCD-EFGH\"}")
+        c.expect(rt.calls.allSatisfy { !$0.args.contains("ABCD-EFGH") }, "code never on argv")
+        await MainActor.run { c.expectEqual(m.joinSummary, "Joining Assured (owner matt)") }
+        let denied = ScriptedRt()
+        denied.answers["team join --dry-run"] = (0, #"{"contract":1,"team":{"slug":"assured","name":"Assured","owner":"matt"},"access":"denied","peering":"idle","message":"You don't have access yet: ask matt to grant you access to Assured."}"#)
+        let m2 = await MainActor.run { TeamChoiceModel(rt: denied) }
+        await MainActor.run { m2.choice = .join; m2.inviteCode = "X" }
+        let e2 = await m2.validateAndPrepare()
+        c.expectEqual(e2, "You don't have access yet: ask matt to grant you access to Assured.", "access != ok comes back as an exit-0 result, not a user error")
+        let unknown = ScriptedRt()
+        unknown.answers["team join --dry-run"] = (2, #"{"contract":1,"error":{"code":"invite-unknown","message":""}}"#)
+        let m3 = await MainActor.run { TeamChoiceModel(rt: unknown) }
+        await MainActor.run { m3.choice = .join; m3.inviteCode = "X" }
+        c.expectEqual(await m3.validateAndPrepare(), "Invite not recognized or expired: ask the team owner for a new one.")
+        c.expectEqual(TeamChoiceModel.joinFailureCopy(RtUserError(code: "expired", message: ""), owner: "matt", team: nil),
+                      "Invite not recognized or expired: ask matt for a new one.")
+        c.expectEqual(TeamChoiceModel.joinFailureCopy(RtUserError(code: "wrong-account", message: ""), owner: nil, team: nil),
+                      "This code is for a different forge account than you're signed into.")
+    },
+    Check("join: invite field accepts pasted codes with whitespace/newlines; ~77 chars; no per-char validation") { c in
+        let m = await MainActor.run { TeamChoiceModel(rt: ScriptedRt()) }
+        await MainActor.run {
+            m.choice = .join
+            m.inviteCode = " ABCD-EFGH-\nIJKL "
+            c.expectEqual(m.normalizedInviteCode, "ABCD-EFGH-IJKL")
+            c.expectEqual(m.canContinue, true)
+            m.inviteCode = "   "
+            c.expectEqual(m.canContinue, false)
+            c.expectEqual(TeamChoiceModel.inviteCodeLength, 77)
+        }
+    },
+    Check("restore: repo + key required; the real rt restore runs with the key on stdin, then setup intent restore") { c in
+        let rt = ScriptedRt()
+        rt.answers["restore"] = (0, #"{"contract":1,"ok":true,"repo":"m4ttheweric/mattstack-home"}"#)
+        rt.answers["setup intent restore"] = (0, #"{"contract":1,"ok":true,"intent":"restore","repo":"m4ttheweric/mattstack-home"}"#)
+        let m = await MainActor.run { TeamChoiceModel(rt: rt) }
+        await MainActor.run { m.choice = .restore; m.restoreRepo = "m4ttheweric/mattstack-home"; c.expectEqual(m.canContinue, false); m.restoreAgeKey = "AGE-SECRET-KEY-1XYZ"; c.expectEqual(m.canContinue, true) }
+        let err = await m.validateAndPrepare()
+        c.expect(err == nil)
+        c.expectEqual(rt.calls[0].args, ["restore", "m4ttheweric/mattstack-home", "--json"])
+        c.expectEqual(rt.calls[0].stdin, "{\"ageKey\":\"AGE-SECRET-KEY-1XYZ\"}")
+        c.expectEqual(rt.calls[1].args, ["setup", "intent", "restore", "m4ttheweric/mattstack-home", "--json"])
+        c.expect(rt.calls.allSatisfy { !$0.args.contains("AGE-SECRET-KEY-1XYZ") }, "key never on argv")
+    },
+]
+```
+
+- [ ] **Step 2: Run → compile failure. Implement Core**
+
+`rt-tray/Sources-core/Setup/Slug.swift`:
+```swift
+import Foundation
+
+public enum Slug {
+    public static func make(_ name: String) -> String {
+        let lowered = name.lowercased()
+        var out = ""
+        var lastDash = true
+        for ch in lowered {
+            if ch.isLetter || ch.isNumber, ch.isASCII {
+                out.append(ch); lastDash = false
+            } else if !lastDash {
+                out.append("-"); lastDash = true
+            }
+        }
+        while out.hasSuffix("-") { out.removeLast() }
+        return out
+    }
+}
+```
+
+`rt-tray/Sources-core/Setup/TeamChoiceModel.swift`:
+```swift
+import Foundation
+import Combine
+
+public enum TeamChoice: Equatable, Sendable { case create, join, restore }
+
+public struct GitHubStatus: Codable, Equatable, Sendable {
+    public var status: RowStatus
+    public var handle: String?
+    public var owners: [String]?
+}
+
+/// Screen 2 state. Every validation is an rt verb; codes and keys travel on
+/// stdin; nothing is pushed until Install.
+@MainActor
+public final class TeamChoiceModel: ObservableObject {
+    public static let inviteCodeLength = 77
+    public static let explainer = "mattstack keeps your team settings in git. That keeps them safe and gives you a paper trail: skill edits and every change are visible in history. The same goes for your own settings home repo, created by the same step."
+
+    @Published public var choice: TeamChoice = .create
+    @Published public var teamName = ""
+    @Published public var othersWillJoin = true
+    @Published public var useGhRepo = false
+    @Published public var ghOwner: String?
+    @Published public private(set) var ghOwners: [String] = []
+    @Published public private(set) var ghHandle: String?
+    @Published public var remoteURL = ""
+    @Published public var inviteCode = ""
+    @Published public var restoreRepo = ""
+    @Published public var restoreAgeKey = ""
+    @Published public private(set) var joinSummary: String?
+    @Published public private(set) var isChecking = false
+
+    private let rt: RtRunning
+    public init(rt: RtRunning) { self.rt = rt }
+
+    public var slugPreview: String { Slug.make(teamName) }
+    public var ghRepoPreview: String { "\(ghOwner ?? ghHandle ?? "you")/mattstack-team-\(slugPreview)" }
+    public var normalizedInviteCode: String { inviteCode.filter { !$0.isWhitespace && !$0.isNewline } }
+
+    public var canContinue: Bool {
+        switch choice {
+        case .create:
+            guard !slugPreview.isEmpty else { return false }
+            return useGhRepo ? (ghHandle != nil) : !remoteURL.trimmingCharacters(in: .whitespaces).isEmpty
+        case .join:
+            return !normalizedInviteCode.isEmpty
+        case .restore:
+            return !restoreRepo.trimmingCharacters(in: .whitespaces).isEmpty && !restoreAgeKey.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+        }
+    }
+
+    public func loadGitHubStatus() async {
+        guard let result = try? await rt.run(["setup", "github", "status", "--json"], stdin: nil),
+              let status = try? result.decode(GitHubStatus.self), status.status == .ready else { return }
+        ghHandle = status.handle
+        ghOwners = status.owners ?? [status.handle].compactMap { $0 }
+        ghOwner = ghOwners.first
+        useGhRepo = true
+    }
+
+    /// Runs the dry-run verbs for the chosen card. Returns nil on success or
+    /// the exact sentence to show under the fields.
+    public func validateAndPrepare() async -> String? {
+        isChecking = true
+        defer { isChecking = false }
+        do {
+            switch choice {
+            case .create:
+                if let e = await homeInitCheck() { return e }
+                var args = ["team", "create", teamName]
+                args += useGhRepo ? ["--create-repo", ghOwner ?? ghHandle ?? ""] : ["--remote", remoteURL.trimmingCharacters(in: .whitespaces)]
+                if othersWillJoin { args.append("--others") }
+                args.append("--json")
+                let r = try await rt.run(args, stdin: nil)
+                if let e = r.userError { return e.message }
+                guard r.exitCode == 0 else { return "rt team create failed (exit \(r.exitCode))." }
+                return nil
+            case .join:
+                let stdin = try JSONEncoder().encode(["code": normalizedInviteCode])
+                let r = try await rt.run(["team", "join", "--dry-run", "--json"], stdin: stdin)
+                if let e = r.userError { return Self.joinFailureCopy(e, owner: nil, team: nil) }
+                guard r.exitCode == 0, let j = try? r.decode(TeamJoinResult.self) else { return "rt team join failed (exit \(r.exitCode))." }
+                guard j.access == "ok" else { return Self.joinFailureCopy(RtUserError(code: j.access == "denied" ? "no-access" : "unreachable", message: j.message ?? ""), owner: j.team?.owner, team: j.team?.name) }
+                joinSummary = j.message ?? "Joining \(j.team?.name ?? "") (owner \(j.team?.owner ?? ""))"
+                return await homeInitCheck()
+            case .restore:
+                // Ruling R3: the app runs the real restore at Continue (clone
+                // + key into the Keychain), then records the intent so
+                // `setup apply`'s home.restore step only verifies.
+                let repo = restoreRepo.trimmingCharacters(in: .whitespaces)
+                let stdin = try JSONEncoder().encode(["ageKey": restoreAgeKey.trimmingCharacters(in: .whitespacesAndNewlines)])
+                let r = try await rt.run(["restore", repo, "--json"], stdin: stdin)
+                if let e = r.userError { return e.message }
+                guard r.exitCode == 0 else { return "rt restore failed (exit \(r.exitCode))." }
+                let intent = try await rt.run(["setup", "intent", "restore", repo, "--json"], stdin: nil)
+                if let e = intent.userError { return e.message }
+                return intent.exitCode == 0 ? nil : "rt setup intent restore failed (exit \(intent.exitCode))."
+            }
+        } catch {
+            return "Could not run rt: \(error)"
+        }
+    }
+
+    private func homeInitCheck() async -> String? {
+        guard let r = try? await rt.run(["home", "init", "--dry-run", "--json"], stdin: nil) else { return "Could not run rt home init." }
+        if let e = r.userError { return e.message }
+        return r.exitCode == 0 ? nil : "rt home init --dry-run failed (exit \(r.exitCode))."
+    }
+
+    public static func joinFailureCopy(_ error: RtUserError, owner: String?, team: String?) -> String {
+        let who = owner ?? "the team owner"
+        switch error.code {
+        case "no-access": return error.message.isEmpty ? "You don't have access yet: ask \(who) to grant you access to \(team ?? "the team")." : error.message
+        case "expired", "not-found", "redeemed", "invite-unknown": return "Invite not recognized or expired: ask \(who) for a new one."
+        case "invite-malformed": return "That doesn't look like an invite code — paste the whole code (about \(inviteCodeLength) characters)."
+        case "wrong-account": return "This code is for a different forge account than you're signed into."
+        default: return error.message.isEmpty ? "Couldn't redeem the invite." : error.message
+        }
+    }
+}
+```
+(Delete the Task 12 stub `TeamChoiceModel` from the app target — the real one lives in Core now.)
+
+- [ ] **Step 3: Run checks → pass.**
+
+- [ ] **Step 4: The screen**
+
+`rt-tray/Sources/Setup/Screens/TeamScreen.swift`:
+```swift
+import SwiftUI
+import MattstackCore
+
+struct TeamScreen: View {
+    @ObservedObject var model: TeamChoiceModel
+
+    var body: some View {
+        ScrollView {
+            VStack(alignment: .leading, spacing: 14) {
+                card(.create, title: "Create a team", systemImage: "person.3") { createFields }
+                card(.join, title: "Join a team", systemImage: "person.crop.circle.badge.plus") { joinFields }
+                card(.restore, title: "Already have mattstack settings?", systemImage: "arrow.counterclockwise.icloud", compact: true) { restoreFields }
+            }
+            .padding(20)
+        }
+        .task { await model.loadGitHubStatus() }
+        .accessibilityIdentifier(AXID.teamScreen)
+    }
+
+    @ViewBuilder
+    private func card<Content: View>(_ choice: TeamChoice, title: String, systemImage: String, compact: Bool = false,
+                                     @ViewBuilder content: () -> Content) -> some View {
+        let selected = model.choice == choice
+        VStack(alignment: .leading, spacing: 10) {
+            Button { model.choice = choice } label: {
+                HStack {
+                    Image(systemName: selected ? "largecircle.fill.circle" : "circle")
+                    Label(title, systemImage: systemImage).font(compact ? .body : .headline)
+                    Spacer()
+                }
+            }
+            .buttonStyle(.plain)
+            .accessibilityIdentifier(cardID(choice))
+            if selected { content().padding(.leading, 24) }
+        }
+        .padding(14)
+        .background(RoundedRectangle(cornerRadius: 10).fill(Color(nsColor: .controlBackgroundColor)))
+        .overlay(RoundedRectangle(cornerRadius: 10).stroke(selected ? Color.accentColor : Color.clear, lineWidth: 1))
+    }
+
+    private func cardID(_ c: TeamChoice) -> String {
+        switch c { case .create: return AXID.teamCardCreate; case .join: return AXID.teamCardJoin; case .restore: return AXID.teamCardRestore }
+    }
+
+    private var createFields: some View {
+        Form {
+            TextField("Team name", text: $model.teamName, prompt: Text("Assured")).accessibilityIdentifier(AXID.teamCreateName)
+            LabeledContent("Slug") { Text(model.slugPreview.isEmpty ? "—" : model.slugPreview).foregroundStyle(.secondary) }
+            Toggle("Others will join later", isOn: $model.othersWillJoin).accessibilityIdentifier(AXID.teamCreateOthers)
+            if model.ghHandle != nil {
+                Toggle("Create a private GitHub repo \(model.ghRepoPreview)", isOn: $model.useGhRepo).accessibilityIdentifier(AXID.teamCreateUseGh)
+                if model.useGhRepo {
+                    Picker("Owner", selection: Binding(get: { model.ghOwner ?? "" }, set: { model.ghOwner = $0 })) {
+                        ForEach(model.ghOwners, id: \.self) { Text($0).tag($0) }
+                    }
+                    .accessibilityIdentifier(AXID.teamCreateOwner)
+                }
+            }
+            if !model.useGhRepo {
+                TextField("Repository URL", text: $model.remoteURL, prompt: Text("paste an empty repo's URL; GitHub, GitLab, anything git can push to"))
+                    .accessibilityIdentifier(AXID.teamCreateRemote)
+            }
+            Text(TeamChoiceModel.explainer).font(.callout).foregroundStyle(.secondary)
+        }
+        .formStyle(.grouped)
+        .scrollDisabled(true)
+    }
+
+    private var joinFields: some View {
+        Form {
+            VStack(alignment: .leading, spacing: 4) {
+                Text("Invite code")
+                TextEditor(text: $model.inviteCode)
+                    .font(.system(.body, design: .monospaced))
+                    .frame(minHeight: 54)
+                    .overlay(RoundedRectangle(cornerRadius: 6).stroke(Color.secondary.opacity(0.3)))
+                    .accessibilityIdentifier(AXID.teamJoinCode)
+                Text("Paste the whole code (about \(TeamChoiceModel.inviteCodeLength) characters) or open the mattstack://join link you were sent.")
+                    .font(.caption).foregroundStyle(.secondary)
+            }
+            if let s = model.joinSummary { Label(s, systemImage: "checkmark.circle.fill").foregroundStyle(.green) }
+            Text(TeamChoiceModel.explainer).font(.callout).foregroundStyle(.secondary)
+        }
+        .formStyle(.grouped)
+        .scrollDisabled(true)
+    }
+
+    private var restoreFields: some View {
+        Form {
+            TextField("Home repo", text: $model.restoreRepo, prompt: Text("<org>/<repo>")).accessibilityIdentifier(AXID.teamRestoreRepo)
+            SecureField("Age key (from your password manager)", text: $model.restoreAgeKey).accessibilityIdentifier(AXID.teamRestoreKey)
+            Text("Clones your settings to ~/.mattstack, installs the key in the Keychain, and replays your teams and packs during Install.")
+                .font(.caption).foregroundStyle(.secondary)
+        }
+        .formStyle(.grouped)
+        .scrollDisabled(true)
+    }
+}
+```
+
+- [ ] **Step 5: `swift build`; checks pass. Commit**
+```bash
+git add rt-tray/Sources-core rt-tray/Sources/Setup rt-tray/Tests
+git commit -m "MAT-383: Your team screen — create/join/restore cards, rt-validated Continue, codes on stdin
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 14: Readiness checklist screen — grouped rows, one action each, Install gating, action dispatch
+
+**Files:**
+- Create: `rt-tray/Sources-core/Readiness/RowActionDispatcher.swift`
+- Create/replace: `rt-tray/Sources/Setup/Screens/ChecklistScreen.swift`, `rt-tray/Sources/Setup/Components/RowView.swift`, `rt-tray/Sources/Setup/Components/ConnectSheet.swift`, `rt-tray/Sources/Setup/Components/StepsSheet.swift`
+- Create: `rt-tray/Tests/MattstackCoreChecks/RowActionChecks.swift`; modify `AllChecks.swift`
+
+**Interfaces:**
+- Produces (Core): `public enum DispatchedAction: Equatable { openSettings(target: String); requestPermission(which: String); rtVerb(args: [String], stdin: Data?); openURL(URL); showSteps([String]); collectFields([ActionField], integration: String, alternatives: [ActionAlternative]); none }`; `public enum RowActionDispatcher { static func dispatch(_ action: RowAction, fieldValues: [String: String]?, alternative: String?) -> DispatchedAction }` — `connect` without values → `collectFields`; with values → `rtVerb(["setup", integration, "connect", "--json"], stdin: JSON of values)`; alternative `use-gh` → stdin `{"useGh":true}`; `oauth` → `rtVerb(verb + ["--json"])`; `owner-once` → collect then `rtVerb(["setup","slack","create-app","--json"], stdin: JSON `{"configToken":…}`)` (no `--config-token-stdin` flag — L1 reads a raw token line under that flag and JSON without it); `install` → `["tools","install",tool,"--json"]`; `link-bundled` → `["deps","link",tool,"--json"]`; `run` → verb + `--json`; `steps` → showSteps; `open-url` → openURL; `open-settings`/`request-permission` native; `unknown` → none.
+- Produces (app): `ChecklistScreen(model:permissions:rt:bundleId:)`, `RowView`, `ConnectSheet` (SecureField per secret field, hint text, "Use gh login" alternative button), `StepsSheet`.
+
+- [ ] **Step 1: Failing checks**
+
+`rt-tray/Tests/MattstackCoreChecks/RowActionChecks.swift`:
+```swift
+import Foundation
+import MattstackCore
+
+let rowActionChecks: [Check] = [
+    Check("native actions") { c in
+        c.expectEqual(RowActionDispatcher.dispatch(RowAction(type: .openSettings, label: "Open…", target: "fda"), fieldValues: nil, alternative: nil), .openSettings(target: "fda"))
+        c.expectEqual(RowActionDispatcher.dispatch(RowAction(type: .requestPermission, label: "Allow", which: "notifications"), fieldValues: nil, alternative: nil), .requestPermission(which: "notifications"))
+    },
+    Check("connect: collect first, then rt setup <integration> connect with JSON on stdin; use-gh alternative") { c in
+        let fields = [ActionField(name: "token", label: "Token", secret: true, hint: "read_api")]
+        let a = RowAction(type: .connect, label: "Connect", integration: "gitlab", fields: fields, alternatives: [ActionAlternative(id: "use-gh", label: "Use gh login")])
+        c.expectEqual(RowActionDispatcher.dispatch(a, fieldValues: nil, alternative: nil), .collectFields(fields, integration: "gitlab", alternatives: a.alternatives!))
+        let d = RowActionDispatcher.dispatch(a, fieldValues: ["token": "glpat-xyz"], alternative: nil)
+        c.expectEqual(d, .rtVerb(args: ["setup", "gitlab", "connect", "--json"], stdin: Data("{\"token\":\"glpat-xyz\"}".utf8)))
+        c.expectEqual(RowActionDispatcher.dispatch(a, fieldValues: nil, alternative: "use-gh"), .rtVerb(args: ["setup", "gitlab", "connect", "--json"], stdin: Data("{\"useGh\":true}".utf8)))
+    },
+    Check("oauth / owner-once / install / link-bundled / run / steps / open-url / unknown") { c in
+        c.expectEqual(RowActionDispatcher.dispatch(RowAction(type: .oauth, label: "Connect", integration: "slack", verb: ["setup", "slack", "connect"]), fieldValues: nil, alternative: nil), .rtVerb(args: ["setup", "slack", "connect", "--json"], stdin: nil))
+        let owner = RowAction(type: .ownerOnce, label: "Create…", integration: "slack", fields: [ActionField(name: "configToken", label: "App configuration token", secret: true)])
+        c.expectEqual(RowActionDispatcher.dispatch(owner, fieldValues: ["configToken": "xoxe-1"], alternative: nil),
+                      .rtVerb(args: ["setup", "slack", "create-app", "--json"], stdin: Data("{\"configToken\":\"xoxe-1\"}".utf8)))
+        c.expectEqual(RowActionDispatcher.dispatch(RowAction(type: .install, label: "Install", tool: "herdr", via: "brew"), fieldValues: nil, alternative: nil), .rtVerb(args: ["tools", "install", "herdr", "--json"], stdin: nil))
+        c.expectEqual(RowActionDispatcher.dispatch(RowAction(type: .linkBundled, label: "Use mattstack's", tool: "gh"), fieldValues: nil, alternative: nil), .rtVerb(args: ["deps", "link", "gh", "--json"], stdin: nil))
+        c.expectEqual(RowActionDispatcher.dispatch(RowAction(type: .run, label: "Re-check", verb: ["setup", "status"]), fieldValues: nil, alternative: nil), .rtVerb(args: ["setup", "status", "--json"], stdin: nil))
+        c.expectEqual(RowActionDispatcher.dispatch(RowAction(type: .steps, label: "Show steps…", steps: ["a", "b"]), fieldValues: nil, alternative: nil), .showSteps(["a", "b"]))
+        c.expectEqual(RowActionDispatcher.dispatch(RowAction(type: .openURL, label: "Download", url: "https://claude.ai/download"), fieldValues: nil, alternative: nil), .openURL(URL(string: "https://claude.ai/download")!))
+        c.expectEqual(RowActionDispatcher.dispatch(RowAction(type: .unknown, label: "?"), fieldValues: nil, alternative: nil), .none)
+        c.expectEqual(RowActionDispatcher.dispatch(RowAction(type: .openURL, label: "x", url: "not a url at all ::"), fieldValues: nil, alternative: nil), .none)
+    },
+]
+```
+
+- [ ] **Step 2: Run → compile failure. Implement**
+
+`rt-tray/Sources-core/Readiness/RowActionDispatcher.swift`:
+```swift
+import Foundation
+
+public enum DispatchedAction: Equatable, Sendable {
+    case openSettings(target: String)
+    case requestPermission(which: String)
+    case rtVerb(args: [String], stdin: Data?)
+    case openURL(URL)
+    case showSteps([String])
+    case collectFields([ActionField], integration: String, alternatives: [ActionAlternative])
+    case none
+}
+
+/// Maps a contract action to what the app does. Native for the two
+/// permission kinds; everything else is an rt verb, with any collected
+/// values on stdin as JSON (sorted keys so the payload is deterministic).
+public enum RowActionDispatcher {
+    public static func dispatch(_ action: RowAction, fieldValues: [String: String]?, alternative: String?) -> DispatchedAction {
+        switch action.type {
+        case .openSettings: return .openSettings(target: action.target ?? "")
+        case .requestPermission: return .requestPermission(which: action.which ?? "")
+        case .connect:
+            guard let integration = action.integration else { return .none }
+            if alternative == "use-gh" { return .rtVerb(args: ["setup", integration, "connect", "--json"], stdin: json(["useGh": true])) }
+            if let values = fieldValues { return .rtVerb(args: ["setup", integration, "connect", "--json"], stdin: json(values)) }
+            return .collectFields(action.fields ?? [], integration: integration, alternatives: action.alternatives ?? [])
+        case .ownerOnce:
+            guard let integration = action.integration else { return .none }
+            if let values = fieldValues { return .rtVerb(args: ["setup", integration, "create-app", "--json"], stdin: json(values)) }
+            return .collectFields(action.fields ?? [], integration: integration, alternatives: [])
+        case .oauth, .run:
+            guard let verb = action.verb, !verb.isEmpty else { return .none }
+            return .rtVerb(args: verb + ["--json"], stdin: nil)
+        case .install:
+            guard let tool = action.tool else { return .none }
+            return .rtVerb(args: ["tools", "install", tool, "--json"], stdin: nil)
+        case .linkBundled:
+            guard let tool = action.tool else { return .none }
+            return .rtVerb(args: ["deps", "link", tool, "--json"], stdin: nil)
+        case .steps: return .showSteps(action.steps ?? [])
+        case .openURL:
+            guard let s = action.url, let u = URL(string: s), u.scheme?.hasPrefix("http") == true else { return .none }
+            return .openURL(u)
+        case .unknown: return .none
+        }
+    }
+
+    private static func json<T: Encodable>(_ value: T) -> Data? {
+        let enc = JSONEncoder(); enc.outputFormatting = [.sortedKeys]
+        return try? enc.encode(value)
+    }
+}
+```
+Run checks → pass.
+
+- [ ] **Step 3: The screen and components**
+
+`rt-tray/Sources/Setup/Components/RowView.swift`:
+```swift
+import SwiftUI
+import MattstackCore
+
+struct RowView: View {
+    let row: PlanRow
+    let isChecking: Bool
+    var rowID: String? = nil       // Settings → Permissions passes its own ids
+    var actionID: String? = nil
+    var statusID: String? = nil
+    let onAction: () -> Void
+
+    var body: some View {
+        HStack(alignment: .top, spacing: 12) {
+            Image(systemName: symbol(for: row.kind)).frame(width: 22).foregroundStyle(.secondary).padding(.top, 2)
+            VStack(alignment: .leading, spacing: 3) {
+                HStack(spacing: 6) {
+                    Text(row.title).fontWeight(.medium)
+                    if !row.required { Text("optional").font(.caption2).padding(.horizontal, 5).padding(.vertical, 1)
+                        .background(Capsule().fill(Color.secondary.opacity(0.15))) }
+                }
+                Text(row.why).font(.callout).foregroundStyle(.secondary).fixedSize(horizontal: false, vertical: true)
+                if let d = row.detail, !d.isEmpty { Text(d).font(.caption).foregroundStyle(.secondary) }
+                if let n = row.optionalNote { Text(n).font(.caption).foregroundStyle(.secondary) }
+            }
+            Spacer(minLength: 8)
+            StatusBadge(status: isChecking ? .checking : row.status, id: statusID ?? AXID.checklistRowStatus(row.id))
+            if let action = row.action, action.type != .unknown {
+                Button(action.label, action: onAction)
+                    .controlSize(.regular)
+                    .accessibilityIdentifier(actionID ?? AXID.checklistRowAction(row.id))
+            }
+        }
+        .padding(.vertical, 4)
+        .accessibilityElement(children: .contain)
+        .accessibilityIdentifier(rowID ?? AXID.checklistRow(row.id))
+    }
+
+    private func symbol(for kind: RowKind) -> String {
+        switch kind {
+        case .permission: return "lock.shield"
+        case .tool: return "wrench.and.screwdriver"
+        case .account: return "person.crop.circle"
+        case .access: return "network"
+        case .info: return "info.circle"
+        }
+    }
+}
+```
+
+`rt-tray/Sources/Setup/Components/ConnectSheet.swift`:
+```swift
+import SwiftUI
+import MattstackCore
+
+struct ConnectSheet: View {
+    let integration: String
+    let fields: [ActionField]
+    let alternatives: [ActionAlternative]
+    let onSubmit: ([String: String]?, String?) -> Void   // (values, alternativeId)
+    @State private var values: [String: String] = [:]
+    @Environment(\.dismiss) private var dismiss
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 14) {
+            Text("Connect \(integration.capitalized)").font(.headline)
+            Form {
+                ForEach(fields, id: \.name) { f in
+                    VStack(alignment: .leading, spacing: 2) {
+                        if f.secret {
+                            SecureField(f.label, text: binding(f.name)).accessibilityIdentifier(AXID.connectField(f.name))
+                        } else {
+                            TextField(f.label, text: binding(f.name)).accessibilityIdentifier(AXID.connectField(f.name))
+                        }
+                        if let h = f.hint { Text(h).font(.caption).foregroundStyle(.secondary) }
+                    }
+                }
+            }
+            .formStyle(.grouped)
+            HStack {
+                ForEach(alternatives, id: \.id) { alt in
+                    Button(alt.label) { onSubmit(nil, alt.id); dismiss() }.accessibilityIdentifier(AXID.connectAlternative(alt.id))
+                }
+                Spacer()
+                Button("Cancel") { dismiss() }.keyboardShortcut(.cancelAction).accessibilityIdentifier(AXID.connectCancel)
+                Button("Connect") { onSubmit(values, nil); dismiss() }
+                    .keyboardShortcut(.defaultAction)
+                    .disabled(fields.contains { (values[$0.name] ?? "").isEmpty })
+                    .accessibilityIdentifier(AXID.connectSubmit)
+            }
+        }
+        .padding(20)
+        .frame(width: 420)
+    }
+
+    private func binding(_ name: String) -> Binding<String> {
+        Binding(get: { values[name] ?? "" }, set: { values[name] = $0 })
+    }
+}
+```
+
+`rt-tray/Sources/Setup/Components/StepsSheet.swift`:
+```swift
+import SwiftUI
+
+struct StepsSheet: View {
+    let title: String
+    let steps: [String]
+    @Environment(\.dismiss) private var dismiss
+    var body: some View {
+        VStack(alignment: .leading, spacing: 12) {
+            Text(title).font(.headline)
+            ForEach(Array(steps.enumerated()), id: \.offset) { i, s in
+                HStack(alignment: .top) { Text("\(i + 1).").monospacedDigit(); Text(s).textSelection(.enabled) }
+            }
+            HStack { Spacer(); Button("Done") { dismiss() }.keyboardShortcut(.defaultAction).accessibilityIdentifier(AXID.stepsDone) }
+        }
+        .padding(20).frame(width: 440)
+    }
+}
+```
+
+`rt-tray/Sources/Setup/Screens/ChecklistScreen.swift`:
+```swift
+import SwiftUI
+import MattstackCore
+
+struct ChecklistScreen: View {
+    @ObservedObject var model: ReadinessModel
+    let permissions: PermissionsService
+    let rt: RtRunning
+    let bundleId: String
+    @State private var connect: (row: PlanRow, fields: [ActionField], integration: String, alternatives: [ActionAlternative])?
+    @State private var steps: (title: String, steps: [String])?
+    @State private var relaunchHint = false
+
+    var body: some View {
+        VStack(spacing: 0) {
+            if let e = model.lastError {
+                Label("Couldn't compute the checklist: \(e)", systemImage: "exclamationmark.triangle").font(.caption).foregroundStyle(.red).padding(8)
+            }
+            Form {
+                ForEach(model.groups) { group in
+                    Section(group.title) {
+                        ForEach(group.rows) { row in
+                            RowView(row: row, isChecking: model.checkingRowIds.contains(row.id)) { perform(row) }
+                        }
+                        if group.id == "mac", relaunchHint || permissions.fdaNeedsRelaunch {
+                            HStack {
+                                Text("Full Disk Access was granted. Relaunch mattstack to apply it.").font(.caption)
+                                Spacer()
+                                Button("Relaunch mattstack") { relaunch() }.accessibilityIdentifier(AXID.checklistRelaunch)
+                            }
+                        }
+                    }
+                }
+            }
+            .formStyle(.grouped)
+            HStack {
+                Text(model.canInstall ? "Everything required is ready." : "\(model.requiredMissing.count) required item(s) left.")
+                    .font(.caption).foregroundStyle(.secondary)
+                Spacer()
+                Button("Re-check") { Task { await model.recheckAll() } }.controlSize(.small).accessibilityIdentifier(AXID.checklistRecheck)
+            }
+            .padding(.horizontal, 20).padding(.vertical, 6)
+        }
+        .sheet(isPresented: Binding(get: { connect != nil }, set: { if !$0 { connect = nil } })) {
+            if let c = connect {
+                ConnectSheet(integration: c.integration, fields: c.fields, alternatives: c.alternatives) { values, alt in
+                    run(RowActionDispatcher.dispatch(c.row.action!, fieldValues: values, alternative: alt), for: c.row)
+                }
+            }
+        }
+        .sheet(isPresented: Binding(get: { steps != nil }, set: { if !$0 { steps = nil } })) {
+            if let s = steps { StepsSheet(title: s.title, steps: s.steps) }
+        }
+        .accessibilityIdentifier(AXID.checklistScreen)
+    }
+
+    private func perform(_ row: PlanRow) {
+        guard let action = row.action else { return }
+        run(RowActionDispatcher.dispatch(action, fieldValues: nil, alternative: nil), for: row)
+    }
+
+    private func run(_ dispatched: DispatchedAction, for row: PlanRow) {
+        switch dispatched {
+        case .openSettings(let target):
+            permissions.openSettings(target)
+            if target == "fda" { relaunchHint = false }
+        case .requestPermission(let which):
+            Task { _ = await permissions.request(which); await model.afterAction(rowId: row.id) }
+        case .rtVerb(let args, let stdin):
+            Task {
+                let result = try? await rt.run(args, stdin: stdin)
+                if let e = result?.userError { TrayLog.warn("row action failed", ["row": row.id, "err": e.message]) }
+                await model.afterAction(rowId: row.id)
+            }
+        case .openURL(let url):
+            NSWorkspace.shared.open(url)
+        case .showSteps(let list):
+            steps = (row.title, list)
+        case .collectFields(let fields, let integration, let alternatives):
+            connect = (row, fields, integration, alternatives)
+        case .none:
+            break
+        }
+    }
+
+    private func relaunch() {
+        let path = Bundle.main.bundlePath
+        let task = Process()
+        task.executableURL = URL(fileURLWithPath: "/usr/bin/open")
+        // Re-exec with the current arguments + environment so a clean-room
+        // launch (`MATTSTACK_APPCAST_URL` + `--allow-appcast-override`)
+        // survives the relaunch; `open` does not inherit either on its own.
+        var args = ["-n", path]
+        if let feed = ProcessInfo.processInfo.environment[UpdatePolicy.overrideEnv] { args += ["--env", "\(UpdatePolicy.overrideEnv)=\(feed)"] }
+        let passthrough = Array(CommandLine.arguments.dropFirst())
+        if !passthrough.isEmpty { args += ["--args"] + passthrough }
+        task.arguments = args
+        try? task.run()
+        NSApp.terminate(nil)
+    }
+}
+```
+(`relaunch()` is the one `open` spawn outside the seam; it is UI-only and unreachable from checks. Row `why`/`detail` text is rt's; the app never writes its own status copy for non-permission rows.)
+
+- [ ] **Step 4: `swift build`; checks pass. Commit**
+```bash
+git add rt-tray/Sources-core rt-tray/Sources/Setup rt-tray/Tests
+git commit -m "MAT-383: Readiness checklist screen — grouped rows, one action each, connect sheet, Install gating
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 15: Install screen — live step list, need rows, failure + Show log + Retry
+
+**Files:**
+- Create/replace: `rt-tray/Sources/Setup/Screens/InstallScreen.swift`, `rt-tray/Sources/Setup/Components/LogSheet.swift`
+
+**Interfaces:**
+- Consumes: `InstallRunModel` (Task 11), `StatusBadge`.
+- Produces: `InstallScreen(model:)`; `LogSheet(title:lines:)`.
+
+- [ ] **Step 1: Write the views**
+
+`rt-tray/Sources/Setup/Components/LogSheet.swift`:
+```swift
+import SwiftUI
+
+struct LogSheet: View {
+    let title: String
+    let lines: [String]
+    @Environment(\.dismiss) private var dismiss
+    var body: some View {
+        VStack(alignment: .leading, spacing: 10) {
+            Text(title).font(.headline)
+            ScrollView {
+                Text(lines.isEmpty ? "(no log lines)" : lines.joined(separator: "\n"))
+                    .font(.system(.caption, design: .monospaced))
+                    .textSelection(.enabled)
+                    .frame(maxWidth: .infinity, alignment: .leading)
+            }
+            .frame(height: 260)
+            .background(Color(nsColor: .textBackgroundColor))
+            HStack {
+                Button("Copy") { NSPasteboard.general.clearContents(); NSPasteboard.general.setString(lines.joined(separator: "\n"), forType: .string) }
+                    .accessibilityIdentifier(AXID.logCopy)
+                Spacer()
+                Button("Done") { dismiss() }.keyboardShortcut(.defaultAction).accessibilityIdentifier(AXID.logDone)
+            }
+        }
+        .padding(20).frame(width: 520)
+    }
+}
+```
+
+`rt-tray/Sources/Setup/Screens/InstallScreen.swift`:
+```swift
+import SwiftUI
+import MattstackCore
+
+struct InstallScreen: View {
+    @ObservedObject var model: InstallRunModel
+    @State private var logFor: InstallStep?
+
+    var body: some View {
+        VStack(spacing: 0) {
+            Form {
+                Section {
+                    ForEach(model.steps) { step in stepRow(step) }
+                } header: {
+                    Text(headerText)
+                }
+            }
+            .formStyle(.grouped)
+            if case .streamError(let e) = model.phase {
+                HStack {
+                    Label("Install stopped: \(e)", systemImage: "xmark.circle").foregroundStyle(.red).font(.callout)
+                    Spacer()
+                    Button("Retry") { model.start() }.accessibilityIdentifier(AXID.installRetryStream)
+                }
+                .padding(.horizontal, 20).padding(.vertical, 8)
+            }
+        }
+        .sheet(item: $logFor) { s in LogSheet(title: s.info.title, lines: model.logLines(for: s.id)) }
+        .accessibilityIdentifier(AXID.installScreen)
+    }
+
+    private var headerText: String {
+        switch model.phase {
+        case .idle: return "Ready to install."
+        case .running: return "Installing… nothing runs that isn't listed here."
+        case .succeeded: return "Installed."
+        case .failed(let id, _): return "Stopped at \(model.steps.first { $0.id == id }?.info.title ?? id)."
+        case .streamError: return "Install stopped."
+        }
+    }
+
+    @ViewBuilder
+    private func stepRow(_ step: InstallStep) -> some View {
+        VStack(alignment: .leading, spacing: 4) {
+            HStack(spacing: 10) {
+                StatusBadge(status: badge(step), id: AXID.installStep(step.id) + ".status")
+                VStack(alignment: .leading, spacing: 2) {
+                    Text(step.info.title)
+                    if step.waitingOnYou {
+                        Text(step.info.kind == .privileged ? "Waiting for you — an administrator prompt is open." : "Waiting for you — approve mattstack in Login Items if asked.")
+                            .font(.caption).foregroundStyle(.orange)
+                    } else if let d = step.detail, !d.isEmpty {
+                        Text(d).font(.caption).foregroundStyle(step.state == .failed ? .red : .secondary)
+                    }
+                }
+                Spacer()
+                if !model.logLines(for: step.id).isEmpty {
+                    Button("Show log") { logFor = step }.controlSize(.small).accessibilityIdentifier(AXID.installStepLog(step.id))
+                }
+            }
+            if step.state == .failed, model.failedStepId == step.id {
+                HStack(alignment: .top) {
+                    if let r = step.remedy { Text(r).font(.callout) }
+                    Spacer()
+                    Button("Retry from here") { model.retryFromFailure() }
+                        .keyboardShortcut(.defaultAction)
+                        .accessibilityIdentifier(AXID.installRetry)
+                }
+                .padding(.top, 2)
+            }
+        }
+        .accessibilityIdentifier(AXID.installStep(step.id))
+    }
+
+    private func badge(_ step: InstallStep) -> RowStatus {
+        switch step.state {
+        case .pending: return .skipped
+        case .running: return step.waitingOnYou ? .needsYou : .checking
+        case .done: return .ready
+        case .failed: return .error
+        case .skipped: return .skipped
+        }
+    }
+}
+```
+(`InstallStep` must be `Identifiable` for `.sheet(item:)` — it is, via `id`.)
+
+- [ ] **Step 2: `swift build` → Build complete. Commit**
+```bash
+git add rt-tray/Sources/Setup
+git commit -m "MAT-383: Install screen — live step list, need rows, failure remedy, Show log, Retry from here
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 16: Done screen
+
+**Files:**
+- Create/replace: `rt-tray/Sources/Setup/Screens/DoneScreen.swift`
+
+- [ ] **Step 1: Write the view**
+
+```swift
+import SwiftUI
+import MattstackCore
+
+struct DoneScreen: View {
+    @ObservedObject var install: InstallRunModel
+    let isOwner: Bool
+    let onInvite: () -> Void
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 18) {
+            HStack(spacing: 12) {
+                Image(systemName: "checkmark.seal.fill").font(.system(size: 40)).foregroundStyle(.green)
+                VStack(alignment: .leading) {
+                    Text("Everything's working").font(.title3.weight(.semibold))
+                    Text(verifySummary).foregroundStyle(.secondary)
+                }
+            }
+            Form {
+                Section("Where things live") {
+                    LabeledContent("Menu bar") { Text("the m at the top right") }
+                    LabeledContent("Terminal") { Text("rt — open a new terminal window").font(.system(.body, design: .monospaced)) }
+                    LabeledContent("Board") { Link("https://board.mattstack", destination: URL(string: "https://board.mattstack")!) }
+                }
+            }
+            .formStyle(.grouped).scrollDisabled(true)
+            HStack {
+                Button("Open the board") { NSWorkspace.shared.open(URL(string: "https://board.mattstack")!) }.accessibilityIdentifier(AXID.doneOpenBoard)
+                if isOwner { Button("Invite teammates…", action: onInvite).accessibilityIdentifier(AXID.doneInvite) }
+                Spacer()
+            }
+            Spacer()
+        }
+        .padding(24)
+        .accessibilityIdentifier(AXID.doneScreen)
+    }
+
+    private var verifySummary: String {
+        let verify = install.steps.first { $0.id == "verify" }
+        let n = install.steps.filter { $0.state == .done }.count
+        return verify?.detail.map { "\($0) · \(n) steps done" } ?? "\(n) steps done"
+    }
+}
+```
+(Finish is the footer's Continue on this step — it closes the window, Task 12. Close/minimize buttons appear because `flow.windowMayClose` is true on `.done`.)
+
+- [ ] **Step 2: `swift build`; commit**
+```bash
+git add rt-tray/Sources/Setup/Screens/DoneScreen.swift
+git commit -m "MAT-383: Done screen — verify summary, where things live, Open the board / Invite teammates
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 17: Settings window (⌘,) — General / Permissions / Team / Uninstall
+
+**Files:**
+- Create: `rt-tray/Sources-core/Settings/RemoteMasker.swift`, `rt-tray/Sources-core/Settings/TeamSettingsModel.swift`
+- Create: `rt-tray/Sources/Settings/SettingsWindowController.swift`, `SettingsView.swift`, `GeneralPane.swift`, `PermissionsPane.swift`, `TeamPane.swift`, `UninstallPane.swift`
+- Create: `rt-tray/Tests/MattstackCoreChecks/SettingsChecks.swift`; modify `AllChecks.swift`
+
+**Interfaces:**
+- Produces (Core): `public enum RemoteMasker { static func mask(_ remote: String) -> String }` (`git@gitlab.assured.com:tools/team.git` → `gitlab.assured.com/tools/team`; `https://github.com/o/r.git` → `github.com/o/r`; garbage → as-is); `public struct TeamSettingsInfo: Codable { name: String?; slug: String?; remote: String?; lastPush: String?; members: [Member]? }` with `Member { username: String }` (from `rt team status [--team <slug>] --json` → `{contract, slug, name, remote, lastPush, members:[{username}]}` — L1 T19 / contract); `@MainActor public final class TeamSettingsModel: ObservableObject` — `init(rt: RtRunning)`; `@Published info: TeamSettingsInfo?`, `invite: InviteResult?`, `error: String?`, `uninstallPlan: UninstallPlan?`; `func load() async`; `func mintInvite(handle: String) async`; `func loadUninstallPlan() async`; `func uninstall(keepData: Bool) -> AsyncThrowingStream<String, Error>`.
+- Produces (app): `SettingsWindowController` (`show(pane:)`, remembers last pane in UserDefaults `MSSettingsPane`), `SettingsView` with `TabView` of the four panes, `enum SettingsPane: String { general, permissions, team, uninstall }`.
+
+- [ ] **Step 1: Failing checks**
+
+`rt-tray/Tests/MattstackCoreChecks/SettingsChecks.swift`:
+```swift
+import Foundation
+import MattstackCore
+
+let settingsChecks: [Check] = [
+    Check("RemoteMasker shows host + repo only") { c in
+        c.expectEqual(RemoteMasker.mask("git@gitlab.assured.com:tools/mattstack-team.git"), "gitlab.assured.com/tools/mattstack-team")
+        c.expectEqual(RemoteMasker.mask("https://user:token@github.com/m4ttheweric/mattstack-home.git"), "github.com/m4ttheweric/mattstack-home")
+        c.expectEqual(RemoteMasker.mask("ssh://git@github.com:22/o/r"), "github.com/o/r")
+        c.expectEqual(RemoteMasker.mask("weird"), "weird")
+    },
+    Check("TeamSettingsModel loads status, mints invites through rt, loads the uninstall dry-run") { c in
+        let rt = ScriptedRt()
+        rt.answers["team status"] = (0, #"{"contract":1,"name":"Assured","slug":"assured","remote":"git@github.com:assured/mattstack-team-assured.git","lastPush":"2026-08-21T03:00:00Z","members":[{"username":"matt"},{"username":"bob"}]}"#)
+        rt.answers["team invite --handle bob"] = (0, #"{"contract":1,"code":"ABCD","expiresAt":"2026-08-28T00:00:00Z","pasteBlock":"Install mattstack…","forgeAccess":"granted","manualSteps":[]}"#)
+        rt.answers["uninstall --dry-run"] = (0, #"{"contract":1,"actions":[{"id":"services.unregister","title":"Stop services"}]}"#)
+        let m = await MainActor.run { TeamSettingsModel(rt: rt) }
+        await m.load()
+        await MainActor.run {
+            c.expectEqual(m.info?.name, "Assured")
+            c.expectEqual(m.maskedRemote, "github.com/assured/mattstack-team-assured")
+        }
+        await m.mintInvite(handle: "bob")
+        await MainActor.run { c.expectEqual(m.invite?.code, "ABCD") }
+        c.expectEqual(rt.calls[1].args, ["team", "invite", "--handle", "bob", "--json"])
+        await m.loadUninstallPlan()
+        await MainActor.run { c.expectEqual(m.uninstallPlan?.actions.first?.id, "services.unregister") }
+    },
+]
+```
+
+- [ ] **Step 2: Run → compile failure. Implement Core**
+
+`rt-tray/Sources-core/Settings/RemoteMasker.swift`:
+```swift
+import Foundation
+
+/// Team pane shows where the repo is, never credentials or the full URL.
+public enum RemoteMasker {
+    public static func mask(_ remote: String) -> String {
+        var s = remote.trimmingCharacters(in: .whitespacesAndNewlines)
+        if let r = s.range(of: "://") { s = String(s[r.upperBound...]) }          // strip scheme
+        if let at = s.lastIndex(of: "@") { s = String(s[s.index(after: at)...]) }    // strip user[:token]@
+        // scp-like host:path → host/path ; host:port/path → host/path
+        if let colon = s.firstIndex(of: ":") {
+            let after = s[s.index(after: colon)...]
+            let port = after.prefix { $0.isNumber }
+            let rest = after.dropFirst(port.count)
+            s = String(s[..<colon]) + (rest.hasPrefix("/") ? String(rest) : "/" + rest)
+        }
+        if s.hasSuffix(".git") { s.removeLast(4) }
+        while s.hasSuffix("/") { s.removeLast() }
+        return s.contains("/") ? s : remote
+    }
+}
+```
+
+`rt-tray/Sources-core/Settings/TeamSettingsModel.swift`:
+```swift
+import Foundation
+import Combine
+
+public struct TeamSettingsInfo: Codable, Equatable, Sendable {
+    public struct Member: Codable, Equatable, Sendable { public var username: String }
+    public var name: String?
+    public var slug: String?
+    public var remote: String?
+    public var lastPush: String?
+    public var members: [Member]?
+}
+
+@MainActor
+public final class TeamSettingsModel: ObservableObject {
+    @Published public private(set) var info: TeamSettingsInfo?
+    @Published public private(set) var invite: InviteResult?
+    @Published public private(set) var uninstallPlan: UninstallPlan?
+    @Published public private(set) var error: String?
+    private let rt: RtRunning
+    public init(rt: RtRunning) { self.rt = rt }
+
+    public var maskedRemote: String { info?.remote.map(RemoteMasker.mask) ?? "—" }
+
+    public func load() async {
+        do {
+            let r = try await rt.run(["team", "status", "--json"], stdin: nil)
+            if let e = r.userError { error = e.message; return }
+            info = try r.decode(TeamSettingsInfo.self)
+        } catch { self.error = String(describing: error) }
+    }
+
+    public func mintInvite(handle: String) async {
+        do {
+            let r = try await rt.run(["team", "invite", "--handle", handle, "--json"], stdin: nil)
+            if let e = r.userError { error = e.message; return }
+            invite = try r.decode(InviteResult.self)
+        } catch { self.error = String(describing: error) }
+    }
+
+    public func loadUninstallPlan() async {
+        do {
+            let r = try await rt.run(["uninstall", "--dry-run", "--json"], stdin: nil)
+            uninstallPlan = try r.decode(UninstallPlan.self)
+        } catch { self.error = String(describing: error) }
+    }
+
+    /// `--yes`: the Uninstall pane's sheet is the confirmation; without it
+    /// rt exits 2 `confirm-required` for `--delete-data` on a non-TTY.
+    public func uninstall(keepData: Bool) -> AsyncThrowingStream<String, Error> {
+        rt.stream(["uninstall", keepData ? "--keep-data" : "--delete-data", "--yes", "--json"], stdin: nil)
+    }
+}
+```
+Run checks → pass.
+
+- [ ] **Step 3: Window + panes**
+
+`rt-tray/Sources/Settings/SettingsWindowController.swift`:
+```swift
+import AppKit
+import SwiftUI
+import MattstackCore
+
+enum SettingsPane: String, CaseIterable { case general, permissions, team, uninstall }
+
+final class SettingsWindowController: NSWindowController {
+    private static let paneKey = "MSSettingsPane"
+    let pane = PaneSelection()
+    final class PaneSelection: ObservableObject { @Published var current: SettingsPane = .general }
+
+    init(env: SettingsEnvironment) {
+        let window = NSWindow(contentRect: NSRect(x: 0, y: 0, width: 560, height: 440),
+                              styleMask: [.titled, .closable], backing: .buffered, defer: false)
+        window.title = "mattstack Settings"
+        window.isReleasedWhenClosed = false
+        window.center()
+        super.init(window: window)
+        pane.current = SettingsPane(rawValue: UserDefaults.standard.string(forKey: Self.paneKey) ?? "") ?? .general
+        window.contentViewController = NSHostingController(rootView: SettingsView(pane: pane, env: env))
+    }
+    required init?(coder: NSCoder) { fatalError("not supported") }
+
+    func show(pane p: SettingsPane? = nil) {
+        if let p { pane.current = p }
+        UserDefaults.standard.set(pane.current.rawValue, forKey: Self.paneKey)
+        showWindow(nil)
+        window?.makeKeyAndOrderFront(nil)
+        NSApp.activate(ignoringOtherApps: true)
+    }
+}
+
+struct SettingsEnvironment {
+    let rt: RtRunning
+    let permissions: PermissionsService
+    let readiness: ReadinessModel
+    let updater: UpdaterController
+    let team: TeamSettingsModel
+    let isDevBuild: Bool
+    let version: String
+    let onJoinAnotherTeam: () -> Void
+    let onQuitForUninstall: () -> Void
+}
+```
+
+`rt-tray/Sources/Settings/SettingsView.swift`:
+```swift
+import SwiftUI
+import MattstackCore
+
+struct SettingsView: View {
+    @ObservedObject var pane: SettingsWindowController.PaneSelection
+    let env: SettingsEnvironment
+    var body: some View {
+        TabView(selection: $pane.current) {
+            GeneralPane(env: env).tabItem { Label("General", systemImage: "gearshape") }.tag(SettingsPane.general)
+            PermissionsPane(env: env).tabItem { Label("Permissions", systemImage: "lock.shield") }.tag(SettingsPane.permissions)
+            TeamPane(env: env).tabItem { Label("Team", systemImage: "person.3") }.tag(SettingsPane.team)
+            UninstallPane(env: env).tabItem { Label("Uninstall", systemImage: "trash") }.tag(SettingsPane.uninstall)
+        }
+        .frame(width: 560, height: 440)
+        .onChange(of: pane.current) { _, p in UserDefaults.standard.set(p.rawValue, forKey: "MSSettingsPane") }
+    }
+}
+```
+
+`rt-tray/Sources/Settings/GeneralPane.swift`:
+```swift
+import SwiftUI
+import ServiceManagement
+import MattstackCore
+
+struct GeneralPane: View {
+    let env: SettingsEnvironment
+    @State private var startAtLogin = SMAppService.mainApp.status == .enabled
+    @State private var autoUpdates = false
+    @State private var devModeBusy = false
+
+    var body: some View {
+        Form {
+            Section("Startup") {
+                Toggle("Start mattstack at login", isOn: $startAtLogin)
+                    .onChange(of: startAtLogin) { _, on in toggleLogin(on) }
+                    .accessibilityIdentifier(AXID.settingsGeneralStartAtLogin)
+            }
+            Section("Updates") {
+                Toggle("Check for updates automatically", isOn: $autoUpdates)
+                    .disabled(!env.updater.isEnabled)
+                    .onChange(of: autoUpdates) { _, on in env.updater.automaticallyChecks = on }
+                    .accessibilityIdentifier(AXID.settingsGeneralAutoUpdates)
+                HStack {
+                    Button("Check Now") { env.updater.checkForUpdatesFromMenu() }.disabled(!env.updater.canCheckForUpdates)
+                        .accessibilityIdentifier(AXID.settingsGeneralCheckNow)
+                    if !env.updater.isEnabled { Text(env.isDevBuild ? "Updates are off in the dev flavor." : "Updates are off in this build.").font(.caption).foregroundStyle(.secondary) }
+                }
+            }
+            Section("Developer") {
+                LabeledContent("Flavor") { Text(env.isDevBuild ? "dev (mattstack-dev.app)" : "prod (mattstack.app)") }
+                Button(env.isDevBuild ? "Switch to the installed app (dev mode off)…" : "Switch to the dev app (dev mode on)…") {
+                    devModeBusy = true
+                    Task { _ = try? await env.rt.run(["settings", "dev-mode", env.isDevBuild ? "prod" : "dev"], stdin: nil); devModeBusy = false }
+                }
+                .disabled(devModeBusy)
+                .accessibilityIdentifier(AXID.settingsGeneralDevMode)
+                Text("The handoff quits this app and launches the other flavor.").font(.caption).foregroundStyle(.secondary)
+                // `rt settings dev-mode <dev|prod>`: L1 T31 drops `requiresTTY` when the target is given, so the app can spawn it.
+            }
+            Section { LabeledContent("Version") { Text(env.version) } }
+        }
+        .formStyle(.grouped)
+        .onAppear { autoUpdates = env.updater.automaticallyChecks }
+    }
+
+    private func toggleLogin(_ on: Bool) {
+        do {
+            if on { try SMAppService.mainApp.register(); LoginItemPreference.isOptedOut = false }
+            else { try SMAppService.mainApp.unregister(); LoginItemPreference.isOptedOut = true }
+        } catch { TrayLog.error("login item toggle failed", ["err": String(describing: error)]) }
+        startAtLogin = SMAppService.mainApp.status == .enabled
+    }
+}
+```
+
+`rt-tray/Sources/Settings/PermissionsPane.swift`:
+```swift
+import SwiftUI
+import MattstackCore
+
+struct PermissionsPane: View {
+    let env: SettingsEnvironment
+    @State private var snapshot = PermissionSnapshot.unknown
+    @State private var timer: Timer?
+    @State private var resetting = false
+
+    private var rows: [(String, String, String, Bool, String)] {  // id, title, why, required, settings target
+        [(PermissionRowOverlay.fdaRow, "Full Disk Access", "Reads your repositories' git state so the daemon can show branch and MR status.", true, "fda"),
+         (PermissionRowOverlay.loginItemsRow, "Background services", "rt daemon and deck run in the background as login items.", true, "login-items"),
+         (PermissionRowOverlay.notificationsRow, "Notifications", "Pipeline and review alerts; works without this.", false, "notifications")]
+    }
+
+    var body: some View {
+        Form {
+            Section {
+                ForEach(rows, id: \.0) { r in
+                    let (status, detail) = PermissionRowOverlay.status(for: r.0, in: snapshot) ?? (.checking, "")
+                    RowView(row: PlanRow(id: r.0, kind: .permission, title: r.1, why: r.2, required: r.3, status: status, detail: detail,
+                                         action: RowAction(type: .openSettings, label: buttonLabel(r.0, status), target: r.4), recheck: .onActivate),
+                            isChecking: false,
+                            rowID: "settings.permissions.row.\(r.0)",
+                            actionID: AXID.settingsPermissionAction(r.0),
+                            statusID: "settings.permissions.row.\(r.0).status") { act(r.0, status, r.4) }
+                }
+            }
+            Section {
+                HStack {
+                    Button(resetting ? "Resetting…" : "Reset & re-request…") { resetting = true; Task { _ = await env.permissions.resetAndReRequest(); resetting = false } }
+                        .disabled(resetting)
+                        .accessibilityIdentifier(AXID.settingsPermissionsReset)
+                    Text("Clears this app's permission records (for a moved app or stale signature) and asks again.").font(.caption).foregroundStyle(.secondary)
+                }
+            }
+        }
+        .formStyle(.grouped)
+        .onAppear { probe(); timer = Timer.scheduledTimer(withTimeInterval: 1, repeats: true) { _ in probe() } }
+        .onDisappear { timer?.invalidate(); timer = nil }
+    }
+
+    private func buttonLabel(_ id: String, _ status: RowStatus) -> String {
+        switch (id, status) {
+        case (PermissionRowOverlay.fdaRow, _): return "Open Full Disk Access Settings…"
+        case (PermissionRowOverlay.loginItemsRow, _): return "Open Login Items…"
+        case (PermissionRowOverlay.notificationsRow, .skipped): return "Allow"
+        default: return "Open Notification Settings…"
+        }
+    }
+    private func act(_ id: String, _ status: RowStatus, _ target: String) {
+        if id == PermissionRowOverlay.notificationsRow, status == .skipped { Task { _ = await env.permissions.request("notifications"); probe() }; return }
+        env.permissions.openSettings(target)
+    }
+    private func probe() { Task { snapshot = await env.permissions.snapshot() } }
+}
+```
+
+`rt-tray/Sources/Settings/TeamPane.swift`:
+```swift
+import SwiftUI
+import MattstackCore
+
+struct TeamPane: View {
+    let env: SettingsEnvironment
+    @ObservedObject private var model: TeamSettingsModel
+    @State private var handle = ""
+    init(env: SettingsEnvironment) { self.env = env; self.model = env.team }
+
+    var body: some View {
+        Form {
+            Section("Team") {
+                LabeledContent("Name") { Text(model.info?.name ?? "—") }
+                LabeledContent("Remote") {
+                    HStack { Text(model.maskedRemote).textSelection(.enabled)
+                        Button { NSPasteboard.general.clearContents(); NSPasteboard.general.setString(model.info?.remote ?? "", forType: .string) } label: { Image(systemName: "doc.on.doc") }.buttonStyle(.borderless) }
+                }
+                LabeledContent("Backup") { Text(model.info?.lastPush.map { "last push \($0)" } ?? "no push recorded") }
+            }
+            Section("Members with access") {
+                if let m = model.info?.members, !m.isEmpty { ForEach(m, id: \.username) { Text($0.username) } }
+                else { Text("Not visible with the current token.").foregroundStyle(.secondary) }
+            }
+            Section("Invite") {
+                HStack {
+                    TextField("Forge handle", text: $handle, prompt: Text("teammate's GitHub/GitLab handle")).accessibilityIdentifier(AXID.settingsTeamInviteHandle)
+                    Button("Invite…") { Task { await model.mintInvite(handle: handle) } }.disabled(handle.trimmingCharacters(in: .whitespaces).isEmpty)
+                        .accessibilityIdentifier(AXID.settingsTeamInvite)
+                }
+                if let inv = model.invite {
+                    VStack(alignment: .leading, spacing: 6) {
+                        Text(inv.pasteBlock).font(.system(.caption, design: .monospaced)).textSelection(.enabled)
+                        HStack {
+                            Button("Copy paste block") { NSPasteboard.general.clearContents(); NSPasteboard.general.setString(inv.pasteBlock, forType: .string) }
+                                .accessibilityIdentifier(AXID.settingsTeamCopyPaste)
+                            Text("expires \(inv.expiresAt) · forge access: \(inv.forgeAccess)").font(.caption).foregroundStyle(.secondary)
+                        }
+                        if let steps = inv.manualSteps, !steps.isEmpty { ForEach(steps, id: \.self) { Text("• \($0)").font(.caption) } }
+                    }
+                }
+            }
+            Section { Button("Join another team…", action: env.onJoinAnotherTeam).accessibilityIdentifier(AXID.settingsTeamJoinAnother) }
+            if let e = model.error { Text(e).font(.caption).foregroundStyle(.red) }
+        }
+        .formStyle(.grouped)
+        .task { await model.load() }
+    }
+}
+```
+
+`rt-tray/Sources/Settings/UninstallPane.swift`:
+```swift
+import SwiftUI
+import MattstackCore
+
+struct UninstallPane: View {
+    let env: SettingsEnvironment
+    @ObservedObject private var model: TeamSettingsModel
+    @State private var confirming = false
+    @State private var keepData = true
+    @State private var progress: [String] = []
+    @State private var running = false
+    init(env: SettingsEnvironment) { self.env = env; self.model = env.team }
+
+    var body: some View {
+        Form {
+            Section("Uninstall mattstack") {
+                Text("Reverses everything the installer did: services, the proxy, ~/.local/bin links and the shell rc block, the editor extension, the Claude Code plugins we added; then moves the app to the Trash.")
+                    .font(.callout)
+                Button("Uninstall mattstack…") { Task { await model.loadUninstallPlan(); confirming = true } }
+                    .accessibilityIdentifier(AXID.settingsUninstall)
+            }
+            if !progress.isEmpty {
+                Section("Progress") { ForEach(progress, id: \.self) { Text($0).font(.system(.caption, design: .monospaced)) } }
+            }
+        }
+        .formStyle(.grouped)
+        .sheet(isPresented: $confirming) {
+            VStack(alignment: .leading, spacing: 12) {
+                Text("This will:").font(.headline)
+                ForEach(model.uninstallPlan?.actions ?? []) { a in Label(a.title, systemImage: "minus.circle") }
+                Toggle("Keep ~/.mattstack (your settings home repo and data)", isOn: $keepData).accessibilityIdentifier(AXID.settingsUninstallKeepData)
+                HStack {
+                    Spacer()
+                    Button("Cancel") { confirming = false }.keyboardShortcut(.cancelAction)
+                    Button("Uninstall", role: .destructive) { confirming = false; run() }.keyboardShortcut(.defaultAction).disabled(running)
+                        .accessibilityIdentifier(AXID.settingsUninstallConfirm)
+                }
+            }
+            .padding(20).frame(width: 460)
+        }
+    }
+
+    private func run() {
+        running = true
+        progress = []
+        Task {
+            do {
+                for try await line in model.uninstall(keepData: keepData) {
+                    if let ev = try? ApplyEvent.decode(line) {
+                        switch ev {
+                        case .step(let id, let state, let detail, _): progress.append("\(id): \(state.rawValue)\(detail.map { " — \($0)" } ?? "")")
+                        case .done(let ok, _): progress.append(ok ? "done — mattstack will quit now" : "stopped"); if ok { env.onQuitForUninstall() }
+                        default: break
+                        }
+                    }
+                }
+            } catch { progress.append("error: \(error)") }
+            running = false
+        }
+    }
+}
+```
+
+- [ ] **Step 4: `swift build`; checks pass. Commit**
+```bash
+git add rt-tray/Sources-core rt-tray/Sources/Settings rt-tray/Tests
+git commit -m "MAT-383: Settings window — General, Permissions (Reset & re-request), Team (Invite…), Uninstall
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 18: AppDelegate integration — launch guard, appPath, first-run, deep link, menu, routes, version-change
+
+**Files:**
+- Create: `rt-tray/Sources-core/Launch/LaunchGuard.swift`, `rt-tray/Sources/Rt/RtClientFactory.swift`, `rt-tray/Sources/Setup/SetupCoordinator.swift`
+- Modify: `rt-tray/Sources/AppDelegate.swift`, `rt-tray/Sources/main.swift`, `rt-tray/Sources/TrayState.swift`, `rt-tray/Sources/ProcessPanelView.swift` (gear-menu additions only), `rt-tray/Sources/DaemonLifecycle.swift` + `rt-tray/Sources-daemon-shim/main.swift` (L4 T3's string/comment edits, carried here — `rt-tray/Sources/**` is L3's)
+- Create: `rt-tray/Tests/MattstackCoreChecks/LaunchChecks.swift`; modify `AllChecks.swift`
+
+**Interfaces:**
+- Produces (Core):
+  - `public enum LaunchGuard { static func isTranslocatedOrOnRemovableVolume(bundlePath: String) -> Bool }` — true for paths containing `/AppTranslocation/` or starting with `/Volumes/`
+  - `public enum FirstRunDetector { static func needsSetup(home: String, fileExists: (String) -> Bool) -> Bool }` — `!fileExists("\(home)/.mattstack/rt/daemon.json")`
+  - `public enum JoinLink { static func code(from url: URL) -> String? }` — `mattstack://join/<code>` (host `join`, one path component, trims whitespace, rejects others/empty)
+  - `public enum AppPathSetting { static func arguments(bundlePath: String) -> [String] }` → `["settings", "set", "mattstack.appPath", "\"<path>\"", "--scope", "machine"]` (the value is a JSON string literal because `rt settings set` takes `<json-value>`)
+- Produces (app):
+  - `enum RtClientFactory { static func make() -> RtClient? }` (BundleFlavor + `#if DEBUG` + `RT_APP_SOCKET=TrayServer.socketPath`)
+  - `final class SetupCoordinator` — owns `SetupWindowController`, `SettingsWindowController`, `ReadinessModel`, `InstallRunModel`, `TeamSettingsModel`; `func showSetup(step:joinCode:)`, `func showSettings(pane:)`, `func handleJoin(code:)` (setup incomplete → Setup screen 2 prefilled; complete → Settings → Team), `func openSetupStatus()` (screen 3 as health view: `ReadinessModel` over `rt setup status --json`).
+  - AppDelegate: `applicationDidFinishLaunching` order = launch guard → build services (`PermissionsService`, `ServicesRegistrar`, `PrivilegedInstaller`, `NeedBroker`, `TrayRoutes` → `TrayServer.shared.routes`) → existing setup (menu bar, notifications, tray server, polling, updater) → `servicesRegistrar.registerAll()` (replaces `daemonLifecycle.startDaemon()` — the daemon plist is one of the N) → version-change handling → `mattstack.appPath` write → first-run detection → open Setup. URL handling via `NSAppleEventManager` `kAEGetURL` registered in `applicationWillFinishLaunching`. Main menu with App menu: "Settings…" ⌘, "Quit mattstack" ⌘Q (so ⌘, works whenever a window is key). Gear-menu additions in `ProcessPanelView.makeGearMenu()`: "Setup status…", "Settings…", "Uninstall mattstack…" posting `.rtShowSetupStatus`, `.rtShowSettings`, `.rtShowUninstall`; "Check for Updates…" title stays bound to `trayState.updateAvailable` and its enabled state to `updater.canCheckForUpdates` via `TrayState.canCheckForUpdates`.
+
+- [ ] **Step 1: Failing checks**
+
+`rt-tray/Tests/MattstackCoreChecks/LaunchChecks.swift`:
+```swift
+import Foundation
+import MattstackCore
+
+let launchChecks: [Check] = [
+    Check("LaunchGuard flags translocated and volume paths") { c in
+        c.expect(LaunchGuard.isTranslocatedOrOnRemovableVolume(bundlePath: "/private/var/folders/zz/T/AppTranslocation/ABC/d/mattstack.app"))
+        c.expect(LaunchGuard.isTranslocatedOrOnRemovableVolume(bundlePath: "/Volumes/mattstack-2.8.0/mattstack.app"))
+        c.expect(!LaunchGuard.isTranslocatedOrOnRemovableVolume(bundlePath: "/Applications/mattstack.app"))
+        c.expect(!LaunchGuard.isTranslocatedOrOnRemovableVolume(bundlePath: "/Users/u/Applications/mattstack-dev.app"))
+    },
+    Check("FirstRunDetector keys off ~/.mattstack/rt/daemon.json") { c in
+        c.expect(FirstRunDetector.needsSetup(home: "/Users/u") { _ in false })
+        c.expect(!FirstRunDetector.needsSetup(home: "/Users/u") { $0 == "/Users/u/.mattstack/rt/daemon.json" })
+    },
+    Check("JoinLink parses mattstack://join/<code> only") { c in
+        c.expectEqual(JoinLink.code(from: URL(string: "mattstack://join/ABCD-EFGH-IJKL")!), "ABCD-EFGH-IJKL")
+        c.expectEqual(JoinLink.code(from: URL(string: "mattstack://join/ABCD-EFGH-IJKL/")!), "ABCD-EFGH-IJKL")
+        c.expectEqual(JoinLink.code(from: URL(string: "mattstack://join/")!), nil)
+        c.expectEqual(JoinLink.code(from: URL(string: "mattstack://settings/team")!), nil)
+        c.expectEqual(JoinLink.code(from: URL(string: "https://mattstack.dev/join#ABCD")!), nil)
+    },
+    Check("AppPathSetting writes a JSON string through rt settings set --scope machine") { c in
+        c.expectEqual(AppPathSetting.arguments(bundlePath: "/Applications/mattstack.app"),
+                      ["settings", "set", "mattstack.appPath", "\"/Applications/mattstack.app\"", "--scope", "machine"])
+        c.expectEqual(AppPathSetting.arguments(bundlePath: "/Users/u/My \"Apps\"/mattstack.app")[3], "\"/Users/u/My \\\"Apps\\\"/mattstack.app\"")
+    },
+]
+```
+
+- [ ] **Step 2: Run → compile failure. Implement Core**
+
+`rt-tray/Sources-core/Launch/LaunchGuard.swift`:
+```swift
+import Foundation
+
+public enum LaunchGuard {
+    /// Gatekeeper runs a quarantined app from a random read-only mount; a
+    /// DMG is a volume. Either way SMAppService and Sparkle cannot work.
+    public static func isTranslocatedOrOnRemovableVolume(bundlePath: String) -> Bool {
+        bundlePath.contains("/AppTranslocation/") || bundlePath.hasPrefix("/Volumes/")
+    }
+}
+
+public enum FirstRunDetector {
+    public static func needsSetup(home: String, fileExists: (String) -> Bool) -> Bool {
+        !fileExists("\(home)/.mattstack/rt/daemon.json")
+    }
+}
+
+public enum JoinLink {
+    public static func code(from url: URL) -> String? {
+        guard url.scheme?.lowercased() == "mattstack", url.host?.lowercased() == "join" else { return nil }
+        let parts = url.pathComponents.filter { $0 != "/" }
+        guard parts.count == 1 else { return nil }
+        let code = parts[0].trimmingCharacters(in: .whitespacesAndNewlines)
+        return code.isEmpty ? nil : code
+    }
+}
+
+public enum AppPathSetting {
+    public static func arguments(bundlePath: String) -> [String] {
+        let json = String(decoding: (try? JSONEncoder().encode(bundlePath)) ?? Data("\"\"".utf8), as: UTF8.self)
+        return ["settings", "set", "mattstack.appPath", json, "--scope", "machine"]
+    }
+}
+```
+Run checks → pass.
+
+- [ ] **Step 3: App wiring**
+
+`rt-tray/Sources/Rt/RtClientFactory.swift`:
+```swift
+import Foundation
+import MattstackCore
+
+enum RtClientFactory {
+    static func make() -> RtClient? {
+        #if DEBUG
+        let debug = true
+        #else
+        let debug = false
+        #endif
+        guard let loc = RtBinaryLocator.resolve(bundlePath: Bundle.main.bundlePath, isDevBuild: BundleFlavor.isDevBuild,
+                                                isDebugBuild: debug, environment: ProcessInfo.processInfo.environment,
+                                                home: NSHomeDirectory(), fileExists: { FileManager.default.isExecutableFile(atPath: $0) })
+        else {
+            TrayLog.error("no rt binary found for this bundle", ["bundle": Bundle.main.bundlePath])
+            return nil
+        }
+        TrayLog.info("rt resolved", ["path": loc.executable.path, "source": String(describing: loc.source)])
+        return RtClient(location: loc, environment: ["RT_APP_SOCKET": TrayServer.socketPath])
+    }
+}
+```
+
+`rt-tray/Sources/Setup/SetupCoordinator.swift`:
+```swift
+import AppKit
+import MattstackCore
+
+/// Owns the Setup and Settings windows and the models behind them. One
+/// instance per process, created by AppDelegate after the services exist.
+@MainActor
+final class SetupCoordinator {
+    private let rt: RtRunning
+    private let permissions: PermissionsService
+    private let needs: NeedBroker
+    private let updater: UpdaterController
+    private let readiness: ReadinessModel
+    private let install: InstallRunModel
+    private let teamSettings: TeamSettingsModel
+    private var setupWindow: SetupWindowController?
+    private var settingsWindow: SettingsWindowController?
+
+    init(rt: RtRunning, permissions: PermissionsService, needs: NeedBroker, updater: UpdaterController) {
+        self.rt = rt; self.permissions = permissions; self.needs = needs; self.updater = updater
+        readiness = ReadinessModel(plans: RtPlanSource(rt: rt, verb: ["setup", "plan", "--json"]),
+                                   permissions: permissions, ticker: MainTicker())
+        install = InstallRunModel(stream: { from in
+            var args = ["setup", "apply"]
+            if let from { args += ["--from", from] }
+            return rt.stream(args + ["--json"], stdin: nil)
+        }, needs: needs)
+        teamSettings = TeamSettingsModel(rt: rt)
+    }
+
+    var setupIsComplete: Bool {
+        !FirstRunDetector.needsSetup(home: NSHomeDirectory()) { FileManager.default.fileExists(atPath: $0) }
+    }
+
+    func showSetup(step: SetupStep? = nil, joinCode: String? = nil) {
+        if setupWindow == nil {
+            let env = SetupEnvironment(rt: rt, readiness: readiness, install: install, permissions: permissions,
+                                       isDevBuild: BundleFlavor.isDevBuild, bundleId: Bundle.main.bundleIdentifier ?? "com.mattstack.app",
+                                       bundlePath: Bundle.main.bundlePath)
+            setupWindow = SetupWindowController(environment: env)
+        }
+        setupWindow?.show(step: step, joinCode: joinCode)
+    }
+
+    /// "Setup status…": screen 3 as a health view over `rt setup status`.
+    func openSetupStatus() {
+        let status = ReadinessModel(plans: RtPlanSource(rt: rt, verb: ["setup", "status", "--json"]), permissions: permissions, ticker: MainTicker())
+        let env = SetupEnvironment(rt: rt, readiness: status, install: install, permissions: permissions,
+                                   isDevBuild: BundleFlavor.isDevBuild, bundleId: Bundle.main.bundleIdentifier ?? "com.mattstack.app",
+                                   bundlePath: Bundle.main.bundlePath)
+        let wc = SetupWindowController(environment: env)
+        wc.flow.jump(to: .checklist)
+        wc.flow.isInstalling = false
+        wc.show(step: .checklist)
+        wc.window?.styleMask.insert(.closable)
+        wc.window?.title = "mattstack Setup status"
+        setupWindow = wc
+    }
+
+    func showSettings(pane: SettingsPane? = nil) {
+        if settingsWindow == nil {
+            let env = SettingsEnvironment(rt: rt, permissions: permissions, readiness: readiness, updater: updater, team: teamSettings,
+                                          isDevBuild: BundleFlavor.isDevBuild,
+                                          version: Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String ?? "dev",
+                                          onJoinAnotherTeam: { [weak self] in self?.showSetup(step: .team) },
+                                          onQuitForUninstall: { NSApp.terminate(nil) })
+            settingsWindow = SettingsWindowController(env: env)
+        }
+        settingsWindow?.show(pane: pane)
+    }
+
+    func handleJoin(code: String) {
+        if setupIsComplete { showSettings(pane: .team); showSetup(step: .team, joinCode: code) }
+        else { showSetup(step: .team, joinCode: code) }
+    }
+}
+
+struct RtPlanSource: PlanSource {
+    let rt: RtRunning
+    let verb: [String]
+    func fetchPlan() async throws -> Plan {
+        let r = try await rt.run(verb, stdin: nil)
+        if let e = r.userError { throw e }
+        return try r.decode(Plan.self)
+    }
+}
+
+/// Timer-backed ticker on the main run loop.
+struct MainTicker: TickerScheduling {
+    func schedule(every seconds: TimeInterval, _ tick: @escaping @Sendable () -> Void) -> TickerHandle {
+        let timer = Timer.scheduledTimer(withTimeInterval: seconds, repeats: true) { _ in tick() }
+        return TickerHandle { timer.invalidate() }
+    }
+}
+```
+
+`rt-tray/Sources/TrayState.swift` — add `@Published var canCheckForUpdates: Bool = false` and notification names:
+```swift
+    static let rtShowSetupStatus = Notification.Name("rtShowSetupStatus")
+    static let rtShowSettings    = Notification.Name("rtShowSettings")
+    static let rtShowUninstall   = Notification.Name("rtShowUninstall")
+```
+
+`rt-tray/Sources/ProcessPanelView.swift` `makeGearMenu()` — insert after the `View Logs…` separator:
+```swift
+        menu.addItem(ActionMenuItem("Setup status…") { NotificationCenter.default.post(name: .rtShowSetupStatus, object: nil) })
+        menu.addItem(ActionMenuItem("Settings…") { NotificationCenter.default.post(name: .rtShowSettings, object: nil) })
+        menu.addItem(.separator())
+```
+and before `Quit mattstack`:
+```swift
+        menu.addItem(ActionMenuItem("Uninstall mattstack…") { NotificationCenter.default.post(name: .rtShowUninstall, object: nil) })
+        menu.addItem(.separator())
+```
+and make the update item reflect Sparkle: `let updateItem = ActionMenuItem(updateMenuTitle) { … }; updateItem.isEnabled = trayState.canCheckForUpdates || trayState.updateAvailable != nil; menu.addItem(updateItem)`. Nothing else in the panel changes.
+
+`rt-tray/Sources/main.swift` — unchanged except the activation policy stays `.accessory`; the URL handler must be registered before the first event, so AppDelegate implements `applicationWillFinishLaunching`. **L4 `check-bundle.sh` source gates (keep verbatim):** the tray.sock single-instance guard stays *before* `let delegate = AppDelegate()` in `main.swift`; `BundleFlavor.swift` keeps `Bundle.main.object(forInfoDictionaryKey: "MSDaemonLabel")` and `static let defaultDaemonLabel = "com.mattstack.daemon"`; `TrayServer.swift` keeps the literal `path == "/flavor/retire"`.
+
+**L4 T3's Swift edits (absorbed here — L4 T3 drops them):** `rt-tray/Sources/AppDelegate.swift:331` `Bundle.main.bundlePath + "/Contents/MacOS/rt-daemon"` → `"/Contents/MacOS/rt"` (the bundled binary is `rt` after L4's rename; Task 3's `RtBinaryLocator` already prefers it); `rt-tray/Sources/DaemonLifecycle.swift:8,17-18` doc comments `Contents/MacOS/rt-daemon` → `Contents/MacOS/rt`; `rt-tray/Sources-daemon-shim/main.swift:4,26` comments "dev bundle's `Contents/MacOS/rt-daemon`" → `Contents/MacOS/rt` and "`-i rt-daemon`" → "`-i rt`".
+
+`rt-tray/Sources/AppDelegate.swift` changes:
+```swift
+    // properties
+    private var permissionsService: PermissionsService!
+    private var servicesRegistrar: ServicesRegistrar!
+    private var needBroker: NeedBroker!
+    private var coordinator: SetupCoordinator?
+    private var rtClient: RtClient?
+    let updater = UpdaterController(isDevBuild: BundleFlavor.isDevBuild, isBusy: { SetupSession.isRunning })
+    private var updaterObservation: NSKeyValueObservation?
+
+    func applicationWillFinishLaunching(_ notification: Notification) {
+        NSAppleEventManager.shared().setEventHandler(self, andSelector: #selector(handleGetURL(_:with:)),
+                                                     forEventClass: AEEventClass(kInternetEventClass), andEventID: AEEventID(kAEGetURL))
+    }
+
+    func applicationDidFinishLaunching(_ notification: Notification) {
+        if LaunchGuard.isTranslocatedOrOnRemovableVolume(bundlePath: Bundle.main.bundlePath) {
+            showMoveToApplicationsAlert()
+            return
+        }
+        buildServices()
+        installMainMenu()
+        setupMenuBar()
+        setupNotifications()
+        setupTrayServer()
+        startPolling()
+        setupAutoUpdate()
+        // …existing observers unchanged…
+        NotificationCenter.default.addObserver(self, selector: #selector(showSetupStatus), name: .rtShowSetupStatus, object: nil)
+        NotificationCenter.default.addObserver(self, selector: #selector(showSettings), name: .rtShowSettings, object: nil)
+        NotificationCenter.default.addObserver(self, selector: #selector(showUninstall), name: .rtShowUninstall, object: nil)
+        checkMissionControlConflict()
+        autoRegisterLoginItem()
+
+        Task { @MainActor in
+            setHealth(.starting)
+            servicesRegistrar.registerAll()
+            let version = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String ?? "dev"
+            let change = await servicesRegistrar.handleVersionChange(current: version, store: UserDefaults.standard)
+            TrayLog.info("version change evaluated", ["change": String(describing: change)])
+            await recordAppPath()
+            for _ in 0..<8 {
+                try? await Task.sleep(nanoseconds: 500_000_000)
+                if await daemonClient.isReachable() { break }
+            }
+            await refreshStatus()
+            await drainPendingNotifications()
+            if let coordinator, !coordinator.setupIsComplete { coordinator.showSetup() }
+        }
+    }
+
+    private func buildServices() {
+        permissionsService = PermissionsService(bundleId: Bundle.main.bundleIdentifier ?? "com.mattstack.app",
+                                                agentStatuses: { [weak self] in self?.servicesRegistrar.smStatuses() ?? [] },
+                                                runner: SystemCommandRunner())
+        servicesRegistrar = ServicesRegistrar(bundlePath: Bundle.main.bundlePath, runner: SystemCommandRunner())
+        let privileged = PrivilegedInstaller(bundlePath: Bundle.main.bundlePath, escalator: AuthorizationServicesEscalator())
+        needBroker = NeedBroker(services: servicesRegistrar, privileged: privileged)
+        TrayServer.shared.routes = TrayRoutes(permissions: permissionsService, services: servicesRegistrar, privileged: privileged,
+                                              needs: needBroker, updater: updater, version: self)
+        rtClient = RtClientFactory.make()
+        if let rt = rtClient {
+            coordinator = SetupCoordinator(rt: rt, permissions: permissionsService, needs: needBroker, updater: updater)
+        }
+        updaterObservation = updater.observe(\.canCheckForUpdates, options: [.initial, .new]) { u, _ in
+            DispatchQueue.main.async { TrayState.shared.canCheckForUpdates = u.canCheckForUpdates }
+        }
+    }
+
+    /// V3: the machine store learns where this bundle lives, every launch.
+    private func recordAppPath() async {
+        guard let rt = rtClient else { return }
+        let r = try? await rt.run(AppPathSetting.arguments(bundlePath: Bundle.main.bundlePath), stdin: nil)
+        if let r, r.exitCode != 0 { TrayLog.warn("mattstack.appPath write failed", ["exit": Int(r.exitCode), "err": r.userError?.message ?? ""]) }
+    }
+
+    private func installMainMenu() {
+        let main = NSMenu()
+        let appItem = NSMenuItem(); main.addItem(appItem)
+        let appMenu = NSMenu()
+        appMenu.addItem(withTitle: "Settings…", action: #selector(showSettings), keyEquivalent: ",")
+        appMenu.addItem(.separator())
+        appMenu.addItem(withTitle: "Quit mattstack", action: #selector(NSApplication.terminate(_:)), keyEquivalent: "q")
+        appItem.submenu = appMenu
+        let editItem = NSMenuItem(); main.addItem(editItem)
+        let edit = NSMenu(title: "Edit")
+        edit.addItem(withTitle: "Cut", action: #selector(NSText.cut(_:)), keyEquivalent: "x")
+        edit.addItem(withTitle: "Copy", action: #selector(NSText.copy(_:)), keyEquivalent: "c")
+        edit.addItem(withTitle: "Paste", action: #selector(NSText.paste(_:)), keyEquivalent: "v")
+        edit.addItem(withTitle: "Select All", action: #selector(NSText.selectAll(_:)), keyEquivalent: "a")
+        editItem.submenu = edit
+        NSApp.mainMenu = main
+    }
+
+    private func showMoveToApplicationsAlert() {
+        let alert = NSAlert()
+        alert.messageText = "Move mattstack to Applications"
+        alert.informativeText = "mattstack is running from a disk image or a temporary location, so it can't register its background services. Drag mattstack.app to /Applications (or ~/Applications) and open it from there."
+        alert.addButton(withTitle: "Quit")
+        alert.runModal()
+        NSApp.terminate(nil)
+    }
+
+    @objc private func handleGetURL(_ event: NSAppleEventDescriptor, with reply: NSAppleEventDescriptor) {
+        guard let s = event.paramDescriptor(forKeyword: AEKeyword(keyDirectObject))?.stringValue, let url = URL(string: s) else { return }
+        guard let code = JoinLink.code(from: url) else { TrayLog.warn("ignored URL", ["url": s]); return }
+        Task { @MainActor in coordinator?.handleJoin(code: code) }
+    }
+
+    @objc private func showSetupStatus() { Task { @MainActor in coordinator?.openSetupStatus() } }
+    @objc private func showSettings() { Task { @MainActor in coordinator?.showSettings() } }
+    @objc private func showUninstall() { Task { @MainActor in coordinator?.showSettings(pane: .uninstall) } }
+```
+and `extension AppDelegate: VersionProviding { func versionInfo() -> VersionInfo { VersionInfo(version: Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String ?? "dev", build: (Bundle.main.infoDictionary?["CFBundleVersion"] as? String).flatMap(Int.init) ?? 0, flavor: BundleFlavor.isDevBuild ? "dev" : "prod", path: Bundle.main.bundlePath) } }` (`build` is the numeric CFBundleVersion L4 writes — `major*1e6+minor*1e3+patch`, e.g. `2008000` — never a string; a non-numeric or missing value reads as `0`).
+Keep `daemonLifecycle` for the existing stop/restart/retire routes; `registerAll()` now covers its plist (idempotent). Remove the old `daemonLifecycle.startDaemon()` call in the launch task. Replace the Task 10 placeholder `isBusy: { false }` with `{ SetupSession.isRunning }` (shown above). Also handle `.rtShowSettingsTeam` (posted by the Done screen): `NotificationCenter.default.addObserver(forName: .rtShowSettingsTeam, …) { coordinator?.showSettings(pane: .team) }`.
+
+- [ ] **Step 4: `swift build` → Build complete; `swift run mattstack-checks` → pass; `./build.sh dev` assembles. Commit**
+```bash
+git add rt-tray/Sources-core rt-tray/Sources rt-tray/Tests
+git commit -m "MAT-383: AppDelegate integration — launch guard, appPath write, first-run setup, mattstack://join, menu, routes, version-change restart; rt-daemon → rt strings
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+(`git add` also `rt-tray/Sources/DaemonLifecycle.swift rt-tray/Sources-daemon-shim/main.swift` for the L4 T3 string edits.)
+
+---
+
+### Task 19: XCUITest flows against the stub rt — **needs Xcode — blocked until installed** (code written now)
+
+**Files:**
+- Create: `rt-tray/Tests/mattstackUITests/SetupFlowUITests.swift`
+
+**Interfaces:**
+- Consumes: `AXID` names (Task 12), stub scenarios (Task 4). The test runner sets `RT_STUB_SCENARIO`, `RT_STUB_PATH` (absolute path to `Tests/stub-rt/stub.ts` derived from `#filePath`), `RT_STUB_STATE_DIR` (fresh temp dir per test), `HOME` (a temp dir, so `daemon.json` is absent → Setup opens and `~/.mattstack/rt/logs` is throwaway). The app under test is the Debug `mattstack` target, so the stub override is honoured.
+- Scenarios (spec §12.2): `create-happy`, `join-happy`, `join-no-access`, `perm-denied-then-granted`, `apply-fail-retry`, `uninstall`.
+
+- [ ] **Step 1: Write the tests** (AXID literals are repeated here as strings because the UI test bundle cannot import the app target's types; keep them in sync with `AccessibilityIDs.swift`)
+
+```swift
+import XCTest
+
+final class SetupFlowUITests: XCTestCase {
+    private var app: XCUIApplication!
+    private var stateDir: URL!
+    private var home: URL!
+
+    private func launch(_ scenario: String) {
+        app = XCUIApplication()
+        stateDir = FileManager.default.temporaryDirectory.appendingPathComponent("stub-\(UUID().uuidString)")
+        home = FileManager.default.temporaryDirectory.appendingPathComponent("home-\(UUID().uuidString)")
+        try? FileManager.default.createDirectory(at: home, withIntermediateDirectories: true)
+        let stub = URL(fileURLWithPath: #filePath).deletingLastPathComponent().deletingLastPathComponent()
+            .appendingPathComponent("stub-rt/stub.ts").path
+        app.launchEnvironment["RT_STUB_SCENARIO"] = scenario
+        app.launchEnvironment["RT_STUB_PATH"] = stub
+        app.launchEnvironment["RT_STUB_STATE_DIR"] = stateDir.path
+        app.launchEnvironment["HOME"] = home.path
+        app.launch()
+    }
+
+    private func el(_ id: String) -> XCUIElement { app.descendants(matching: .any)[id] }
+    private func waitFor(_ id: String, _ timeout: TimeInterval = 10) {
+        XCTAssertTrue(el(id).waitForExistence(timeout: timeout), "missing \(id)")
+    }
+
+    func testJoinHappyWalksAllFiveScreens() {
+        launch("join-happy")
+        waitFor("setup.welcome.screen")
+        el("setup.welcome.continue").click()
+        waitFor("setup.team.screen")
+        el("setup.team.card.join").click()
+        el("setup.team.join.code").click()
+        el("setup.team.join.code").typeText("ABCD-EFGH-IJKL-MNOP-QRST-UVWX-YZ23-4567-89AB-CDEF-GHJK-MNPQ-RSTV-WXYZ-2345-6789-ABCD-EFGH")
+        el("setup.team.continue").click()
+        waitFor("setup.checklist.screen")
+        waitFor("setup.checklist.row.perm.fda")
+        XCTAssertTrue(el("setup.checklist.continue").waitForExistence(timeout: 10))
+        XCTAssertTrue(el("setup.checklist.continue").isEnabled, "join-happy plan is installable")
+        el("setup.checklist.continue").click()
+        waitFor("setup.install.screen")
+        waitFor("setup.install.step.verify", 30)
+        waitFor("setup.done.screen", 60)
+        el("setup.done.openBoard").click()
+        el("setup.done.continue").click()
+    }
+
+    func testCreateHappyShowsSlugAndReachesChecklist() {
+        launch("create-happy")
+        el("setup.welcome.continue").click()
+        waitFor("setup.team.screen")
+        el("setup.team.card.create").click()
+        el("setup.team.create.name").click()
+        el("setup.team.create.name").typeText("Assured Claims")
+        XCTAssertTrue(app.staticTexts["assured-claims"].waitForExistence(timeout: 3))
+        el("setup.team.create.remote").click()
+        el("setup.team.create.remote").typeText("https://example.com/empty.git")
+        el("setup.team.continue").click()
+        waitFor("setup.checklist.screen")
+    }
+
+    func testJoinNoAccessShowsSpecificFailure() {
+        launch("join-no-access")
+        el("setup.welcome.continue").click()
+        el("setup.team.card.join").click()
+        el("setup.team.join.code").click()
+        el("setup.team.join.code").typeText("ABCD")
+        el("setup.team.continue").click()
+        XCTAssertTrue(app.staticTexts["You don't have access yet: ask matt to grant you access to Assured."].waitForExistence(timeout: 10))
+        XCTAssertFalse(el("setup.checklist.screen").exists)
+    }
+
+    func testPermissionDeniedThenGrantedEnablesInstall() {
+        launch("perm-denied-then-granted")
+        el("setup.welcome.continue").click()
+        el("setup.team.card.join").click()
+        el("setup.team.join.code").click(); el("setup.team.join.code").typeText("ABCD")
+        el("setup.team.continue").click()
+        waitFor("setup.checklist.screen")
+        XCTAssertFalse(el("setup.checklist.continue").isEnabled)
+        // The real FDA probe runs against a temp HOME, so the overlay reports
+        // "unknown" → checking; the plan's second fetch (Re-check) flips the stub's row.
+        el("setup.checklist.recheck").click()
+        let enabled = NSPredicate(format: "isEnabled == true")
+        expectation(for: enabled, evaluatedWith: el("setup.checklist.continue"))
+        waitForExpectations(timeout: 15)
+    }
+
+    func testApplyFailureShowsRemedyAndRetryCompletes() {
+        launch("apply-fail-retry")
+        el("setup.welcome.continue").click()
+        el("setup.team.card.join").click()
+        el("setup.team.join.code").click(); el("setup.team.join.code").typeText("ABCD")
+        el("setup.team.continue").click()
+        waitFor("setup.checklist.screen")
+        el("setup.checklist.continue").click()
+        waitFor("setup.install.retry", 30)
+        XCTAssertTrue(app.staticTexts["Open Claude Code once so it finishes first-run, then Retry."].exists)
+        el("setup.install.retry").click()
+        waitFor("setup.done.screen", 60)
+    }
+
+    func testUninstallFromSettingsShowsDryRunList() {
+        launch("uninstall")
+        // Settings is reachable with ⌘, once a window is key; the setup window is.
+        waitFor("setup.welcome.screen")
+        app.typeKey(",", modifierFlags: .command)
+        waitFor("settings.uninstall.button", 10)
+        el("settings.uninstall.button").click()
+        waitFor("settings.uninstall.confirm")
+        XCTAssertTrue(app.staticTexts["Stop and remove the rt daemon and deck services"].exists)
+    }
+}
+```
+(The permission-row overlay in a UI test reads the real Mac's FDA state for the test host — the `perm-denied-then-granted` flow therefore asserts on the *Install button*, which the stub controls via its other required rows, not on the FDA glyph. The real FDA/Login Items dance is L7's VM walkthrough.)
+
+- [ ] **Step 2: Commit the test source (cannot run here)**
+```bash
+git add rt-tray/Tests/mattstackUITests
+git commit -m "MAT-383: XCUITest flows against the stub rt (create/join/no-access/perm/retry/uninstall) — runs once Xcode is installed
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+Record in the task report: "NOT RUN — needs Xcode (`xcodebuild test -scheme mattstack -only-testing:mattstackUITests`)". When Xcode lands: `xcodegen generate && xcodebuild test -scheme mattstack -destination 'platform=macOS'`.
+
+---
+
+### Task 20: Live-machine smoke — **ORCHESTRATOR-ONLY**
+
+Not for implementer subagents. Matt's machine, dev flavor only, after Task 18 is merged into the worktree branch.
+
+- [ ] `cd rt-tray && swift build && swift run mattstack-checks && bun test Tests/stub-rt && ./build.sh dev` — all green.
+- [ ] Stub-driven run without touching real machine state. `RT_STUB_SCENARIO` is honoured only by DEBUG builds, and `build.sh dev` is a Release build, so run the debug binary directly (env passes through because it is not launched via `open`):
+  `cd rt-tray && swift build && RT_STUB_SCENARIO=join-happy RT_STUB_PATH=$PWD/Tests/stub-rt/stub.ts RT_STUB_STATE_DIR=$(mktemp -d) HOME=$(mktemp -d) .build/debug/rt-tray` (foreground; ⌃C to stop; the second rpath makes Sparkle resolvable; unbundled SMAppService calls fail and log — expected). Walk the five screens; confirm the stub's plan renders, Install streams, `need` rows show "Waiting for you", the run finishes on Done.
+- [ ] Real dev run (`~/.local/bin/rt` wrapper): `rt settings dev-mode dev` handoff as today, then confirm in the dev app: menu shows the new items; ⌘, opens Settings; Settings → Permissions rows match `rt setup status` (once L1 ships `setup status`; before that the pane still renders from the app's own probe); `GET /version` via `curl --unix-socket ~/.mattstack/rt/tray.sock http://x/version` shows `"flavor":"dev"` and the bundle path; `GET /permissions` shows the three statuses; `rt settings get mattstack.appPath --scope machine` (or `rt settings show`) reflects `~/Applications/mattstack-dev.app` (note: the dev bundle writes its own path — V3 says one key; confirm with the settings lane that dev writing it is acceptable or gate the write on `!isDevBuild` — Open questions).
+- [ ] Real permissions: Settings → Permissions → Open Full Disk Access Settings… (the probe has already listed the dev app); toggle; row says relaunch; Reset & re-request runs `tccutil` for `com.mattstack.app.dev` only.
+- [ ] `mattstack://join/TESTCODE` via `open "mattstack://join/TESTCODE"` → Setup opens on screen 2 with the code filled (setup incomplete on a temp HOME) or Settings → Team (complete).
+- [ ] Version-change: bump `CFBundleShortVersionString` with PlistBuddy on the dev bundle, relaunch, tray log shows "app version changed; restarting agents" and `launchctl print gui/$UID/com.mattstack.daemon.dev` shows a fresh pid.
+
+---
+
+## Self-review checklist (run before handing the plan over)
+
+**Spec coverage**
+- §3 flow: first launch → Setup (Task 18 FirstRunDetector); re-entry "Setup status…" (Task 18 `openSetupStatus`), Settings ⌘, (Task 17/18), `mattstack://join` (Task 18 JoinLink + coordinator). ✔
+- §4 window: 560 pt fixed, no close/minimize until done, Back/Continue bottom-right, Return = Continue, `.controlSize(.large)`, enum Step + push transitions, "Step n of 5", `Form(.grouped)`, status glyphs, ellipsis on System Settings buttons (Tasks 12, 14, 6 labels). ✔
+- §4.1 Welcome copy (Task 12). ✔ §4.2 three cards incl. restore, slug preview, gh owner picker vs URL, explainer, join failure copy, code on stdin, ~77-char paste field (Task 13). ✔ §4.3 groups from rt, row anatomy, optional note, permission 1 s timer + didBecomeActive, Install gating, limited mode, Re-check (Tasks 5, 14). ✔ §4.4 live list, need handling, failure row + Show log + Retry-from (Tasks 11, 15). ✔ §4.5 Done (Task 16). ✔ §4.6 Settings four panes incl. Reset & re-request, Invite…, Join another team…, Uninstall sheet (Task 17). ✔
+- §5.1 components all present; §5.3 routes all present incl. the 2026-08-21 contract update (GET /setup/need polling, `/version.path`) (Task 9). ✔
+- §8 services: N plists, register every launch, `.requiresApproval` surfaced, version-change kickstart + `deck restart --managed`, plist PATH explicit (Tasks 2, 7). ✔
+- §9 permissions table: probe paths, deep links, relaunch hint, tccutil reset, combined Login Items status (Tasks 5, 6). ✔
+- §11 Sparkle keys, gentle reminders, idle install, dev off, feed override for L7, ATS local networking, translocation guard, appPath write (Tasks 2, 10, 18). ✔
+- §12 stub rt + scenarios (Task 4), XCTest (harness + bridge, Task 1 onward), XCUITest (Task 19), dev flavor unchanged (Tasks 2, 3, 10). ✔
+- Ruling 13: identities are read from Info.plist (BundleFlavor) and the LaunchAgents directory, never compiled in; macOS 14 floor in Package.swift + project.yml + Info.plist. ✔
+- L7 requests: AXID file + convention (Task 12 and every view), appcast override + ATS (Tasks 2, 10), `/version.path` (Task 9). ✔
+
+**Placeholder scan** — no "TBD/TODO"; the only "placeholder" words are `SUPublicEDKey`'s release-owned value (by design, gated by `UpdatePolicy`) and the Task 12 scaffolding stubs for Tasks 13–16, each replaced wholesale in its own task.
+
+**Type consistency** — `RtRunning.run(_:stdin:)` / `.stream(_:stdin:)` used identically in Tasks 3, 13, 17, 18; `NeedBroker.perform(id:request:)`/`outcome(id:)` in Tasks 9, 11; `PermissionSnapshot` field names match the contract in Tasks 5, 6, 9; `ServicesProviding` signatures match between Task 7 and the Task 9 fakes; `UpdatePolicy.shouldStartUpdater` has the 4-argument form everywhere after the L7 amendment; `AXID` names in Task 19 strings equal the Task 12 definitions (`setup.<screen>.continue`, `setup.team.card.join`, `setup.checklist.row.perm.fda`, `setup.install.retry`, `setup.done.openBoard`, `settings.uninstall.button/confirm`).
+
+**Known deliberate deviations from the brief**
+- Unit tests are a CLT-runnable check harness + an XCTest bridge rather than XCTest-only (XCTest is not importable under CLT on this machine — verified). Same assertions, one source.
+- `build.sh` gets the minimum Sparkle copy/sign + rendered-agents stopgap (Task 10) so a locally built bundle can launch; L4 still owns the xcodebuild rewrite.
+- `UpdateChecker.swift` is deleted (superseded by Sparkle per ruling 7); `check-bundle.sh` gets a one-assertion update so it keeps passing.
+
+## Open questions (for the orchestrator / L1 / L4 / settings lane)
+
+1. **Need-event stdout race:** rt emits the `need` line then polls `GET /setup/need/<id>`; the app performs the step when it reads the line. If rt ever polls before flushing stdout, the app answers `pending` until the line arrives — fine, but L1 should flush the `need` line before the first poll so there's no 1 s wobble.
+2. **Restore card inputs:** CLOSED (ruling R3, cross-plan review): the app runs the real `rt restore <org>/<repo> --json` (key on stdin `{"ageKey"}`) at Continue, then `rt setup intent restore <org>/<repo> --json`; L1's `home.restore` apply step only verifies (Task 13). `rt team create` / `rt team join --dry-run` at Continue leave the pending choice where `apply` finds it (L1 `setup intent`). Still pending on the settings lane: `rt restore --json` + key on stdin, and `--dry-run --json` if it ever ships.
+3. **`rt setup github status --json` shape:** CLOSED — L1 T12 adds `handle` + `owners`; the contract lists them. gh-created repo is `rt team create <name> --create-repo <owner>` (L1 names it `mattstack-team-<slug>`); the `--remote gh:` spelling is gone (Task 13).
+4. **`rt team status --json`:** CLOSED — L1 T19 adds it: `{contract, slug, name, remote, lastPush, members:[{username}]}` (Task 17).
+5. **Proxy helper exit trailer:** `AuthorizationExecuteWithPrivileges` does not return the child's exit status; the plan has the helper print `MATTSTACK_EXIT=<n>` as its last stdout line. L4/L5 must honour that (or the app falls back to the `osascript … with administrator privileges` path noted in Task 8).
+6. **Agent plist PATH:** CLOSED (ruling R2): the templates ship the static `/usr/bin:/bin:/usr/sbin:/sbin`; rt and deck prepend `<bundleRoot>/Contents/Helpers` (from their own execPath) and `$HOME/.local/bin` at process start; no plist hardcodes `/Applications/…`; L4's `check-bundle.sh` asserts the static value (Task 2).
+7. **Dev flavor writing `mattstack.appPath`:** V3 says the app records its path at launch; with two flavors on one Mac the key holds whichever launched last. rt's `installedTrayAppPath(bundle:)` already guards on basename, so this is safe, but confirm the settings lane is fine with the dev bundle writing it (else gate on `!isDevBuild`).
+8. **Sparkle under CLT:** `swift build` fetching the Sparkle xcframework via SPM without Xcode is expected to work (binaryTarget + ld64 from CLT) but was not exercised before the plan was written; Task 10 says stop and report if it does not.
+9. **rpath for the unbundled debug binary:** the second rpath in Package.swift targets `.build/<triple>/debug/../../artifacts/...`; if `swift run` of the app still can't load Sparkle, set `DYLD_FRAMEWORK_PATH` for that run — cosmetic, the bundle is the real target.
+10. **`KeepAlive` in prod:** CLOSED — L4 T3/T4 adopt `{SuccessfulExit:false}` for both flavors (render script + check-bundle); Task 10's stopgap is deleted by L4 T4's rewrite.
+11. **`rt settings dev-mode` from Settings → General:** the button spawns `rt settings dev-mode <dev|prod>` (L1 T31 drops `requiresTTY` when the target is given); the handoff quits this app (expected). Confirm that's acceptable UX or hide the button behind the dev flavor only.
+12. **Uninstall on the dev flavor / self-trash:** `rt uninstall` trashes the app; from the dev bundle that would trash `mattstack-dev.app` — the plan shows the same pane in both flavors; consider disabling in dev.
+13. **XCUITest needs Xcode; `swift test` needs Xcode:** both gates stay red on this machine until Xcode 26 is installed; `swift run mattstack-checks` is the only automated gate today and is green by construction of Tasks 1–18.
+14. **`PermissionsService.combinedLoginItems` with zero agents:** reports `notRegistered`; in a bundle missing its LaunchAgents dir the row will honestly say "Not registered" — but `ServicesRegistrar.registerAll()` will have registered nothing. CLOSED on the L4 side: L4 T4 bundles both plists via `scripts/render-launchagents.sh` (Task 2 is the source); L1 requests the deck plist only when deck is bundled, and a missing `BundleProgram` reports `notFound` honestly (Task 7).
+15. **Sparkle feed/interval and `CFBundleURLName`:** CLOSED — `SUFeedURL` is the GitHub Release asset `https://github.com/m4ttstack/rt/releases/latest/download/appcast.xml` (ruling R1), `SUScheduledCheckInterval` 21600, `CFBundleURLName` `@@BUNDLE_ID@@.join`; L4's build.sh `Set`s the `SU*` keys (Task 2).
diff --git a/docs/superpowers/plans/2026-08-21-release-pipeline.md b/docs/superpowers/plans/2026-08-21-release-pipeline.md
new file mode 100644
index 00000000..e11719df
--- /dev/null
+++ b/docs/superpowers/plans/2026-08-21-release-pipeline.md
@@ -0,0 +1,2249 @@
+# MAT-383 L4 — Release Pipeline, Bundling, Identity Freeze 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:** Make mattstack.app *the* release: one tag on m4ttstack/rt builds rt (arm64), bundles the pinned helpers per `deps.lock`, freezes the app's identity (`Contents/MacOS/rt`, macOS 14 floor, `mattstack://`), signs inside-out, notarizes, ships a DMG + Sparkle zip + signed appcast, and proves the result in a headless clean-room job; rt stops copying binaries around and simply links into the bundle.
+
+**Architecture:** Three layers. (1) A data contract — `rt-tray/deps.lock` + the bundle layout (`Contents/MacOS/rt`, `Contents/Helpers/<tool>`, `Contents/Resources/deps.lock`) — shared by the build, the checks, and rt at runtime (`lib/bundle-layout.ts`, which L1's `rt deps` consumes). (2) Build scripts — `rt-tray/build.sh` (swift-build today, xcodebuild when Xcode 26 lands; both converge on one assemble-and-sign path), `scripts/fetch-deps.sh`, `scripts/release/{notarize,make-zip,make-dmg,appcast}.sh`, and a rewritten `check-bundle.sh` that asserts the contract. (3) The train — `.github/workflows/release.yml` (release job + clean-room job) and the rt-side library pieces L1 consumes (`installRtBinary` symlink, `trayAppPath` via `mattstack.appPath`, `legacyUserAppPath`, `resolveFzf`), plus docs. After the cross-plan review, `rt update`, `commands/post-install.ts` (sweep + `setupApply`) and the `rt verify` rows are L1's (T30, T27/T24, T7/T11).
+
+**Tech Stack:** bash (build/release scripts), Bun/TypeScript (rt), GitHub Actions (`macos-latest`), Sparkle 2.9.6 (`generate_appcast`, EdDSA), `codesign`/`notarytool`/`stapler`/`hdiutil`/`ditto`.
+
+**Spec:** `docs/superpowers/specs/2026-08-20-mattstack-app-installer-design.md` (§2 rulings 6/7/8/13 + V2/V3, §7, §8, §11, §12.2 layer (a), §14) and `docs/superpowers/specs/2026-08-21-rt-setup-contract.md` (`GET /version`, `POST /update/check`). Research: `docs/superpowers/specs/research/2026-08-20-mattstack-app/research-{sparkle-install-launchd,dependency-inventory,local-inventory}.md`. On conflict, the spec wins.
+
+**Worktree / branch:** execute in `/Users/matt/Documents/GitHub/repo-tools-l4-wt`, branch `goodwinmattheweric/mat-383-release-pipeline` off `origin/main`. Commit prefix `MAT-383:`; every commit body ends with `Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>`.
+
+**Execution order (binding; see `docs/superpowers/plans/2026-08-21-cross-plan-review.md` §3):** Phase A (parallel with L1/L3/L7, no cross-file overlap): T1, T2, T6, T7, T9-trimmed (`lib/dev-mode.ts`, `lib/rt-paths.ts` + tests only), T11-trimmed (`lib/fzf.ts`, `lib/notifier.ts` + tests), T3-trimmed (`commands/settings.ts`, `dev-mode-handoff.test.ts`, `scripts/entitlements.plist`, `build.sh` minimal, `check-bundle.sh` rewrite). Phase B: T4 and T5 AFTER L3 T1 + T2 + T10 merge (Package.swift, Sparkle, plist templates, `render-launchagents.sh` are L3's); T8 any time (green only after L7 T12 lands); T12 AFTER L1 T30 + T31 merge (`update.mdx`/docs), then L1 T31 regenerates docs on top. Phase C: T13 (entitlements), T14 (Xcode cutover, after L3 T2 `project.yml`), T15 (dry run → tag; clean-room green requires L7 T12 + L1 T27). T10 is dropped. Merge order to main: L4 Phase A → L3 T1–T11 → L1 Phase A → L4 T4/T5/T8 → L1 Phase B → L3 T12–T19 → L7 → L4 T12 → L1 T31–T32 → MATT gates.
+
+## Global Constraints
+
+- **Rebase onto `origin/main` before every merge.** T4/T5 start only after L3 T1/T2/T10 have merged; T12 after L1 T30/T31.
+- **File ownership (cross-plan review §1):** L4 owns `rt-tray/build.sh`, `rt-tray/check-bundle.sh`, `lib/bundle-layout.ts`, `lib/rt-paths.ts`, `lib/dev-mode.ts`, `lib/fzf.ts`, `lib/notifier.ts`, `README.md`, `.github/workflows/release.yml`, `scripts/release/*`, `scripts/fetch-deps.sh`, `rt-tray/deps.lock`. L4 does **not** edit `commands/post-install.ts`, `commands/update.ts`, `commands/verify.ts`, `cli.ts` (L1), nor `rt-tray/Package.swift`, `rt-tray/Info.plist`, `rt-tray/LaunchAgent.plist`, `rt-tray/LaunchAgent-deck.plist`, `rt-tray/project.yml`, `rt-tray/scripts/render-launchagents.sh`, `rt-tray/Sources/**`, `rt-tray/Sources-daemon-shim/**` (L3). `build.sh` consumes L3's templates and render script; `check-bundle.sh` asserts what they produce.
+
+- **Identity frozen (ruling 13):** bundle ids `com.mattstack.app` / `com.mattstack.app.dev`; daemon labels `com.mattstack.daemon` / `com.mattstack.daemon.dev` (unchanged); embedded binary is `Contents/MacOS/rt` with codesign identifier `rt` (both flavors — the dev shim is also named `rt`); product name `mattstack`; `LSMinimumSystemVersion 14.0`; `CFBundleURLTypes` for `mattstack://`; `NSUserNotificationAlertStyle` kept; no `LSFileQuarantineEnabled`.
+- **arm64-only** (ruling 7). No x64 artifacts anywhere.
+- **The app IS the release (ruling 7):** `mattstack-<ver>.dmg` (first install, notarized + stapled), `mattstack-<ver>.zip` (Sparkle enclosure, `ditto -c -k --sequesterRsrc --keepParent`), `appcast.xml` (EdDSA-signed in CI), deltas. The `rt-darwin-*.tar.gz` tarball is **dropped** — the zip is the headless artifact (`ditto -x -k` + `<app>/Contents/MacOS/rt --post-install`).
+- **Appcast host:** GitHub Release asset, fed through the stable URL `https://github.com/m4ttstack/rt/releases/latest/download/appcast.xml` (justification in "Decisions" below; ruled R1 in the cross-plan review — L3's Info.plist template and spec §11 carry the same URL).
+- **Dependency policy (ruling 8 / §7):** BUNDLE into `Contents/Helpers/` pinned by `rt-tray/deps.lock` (name, version, url, sha256, license, bundlePath, exposeByDefault); suite uses them by absolute path; default-exposed set is `rt`, `fast-browser`, `gitq`, `deck` (V2; linking is L1's `rt deps link`). `deck`/`board`/`gitq` are `status: "pending"` until L5 publishes. tmux/zellij/terminal-notifier dropped.
+- **Signing:** hardened runtime + timestamp on every Mach-O, inside-out, never `--deep`. Bun-based executables get `scripts/entitlements.plist` = `com.apple.security.cs.allow-jit` **only**; `allow-unsigned-executable-memory` is added per tool only after the measurement task shows a crash. Team ID, labels, and each helper's signing identifier stay stable across releases.
+- **CFBundleVersion** is numeric and monotonic: `major*1_000_000 + minor*1_000 + patch` (2.8.0 → `2008000`); `CFBundleShortVersionString` is the semver without `v`.
+- **Sparkle plist:** `SUFeedURL`, `SUPublicEDKey` (from the committed `rt-tray/SUPublicEDKey` file), `SUEnableAutomaticChecks` (prod true / dev false), `SUScheduledCheckInterval 21600`, `SUAutomaticallyUpdate true`, `SUVerifyUpdateBeforeExtraction true`; no `SUEnable*Service` keys.
+- **Install on the user's machine (§11, V3):** app lives in `/Applications` (fallback `~/Applications`); `~/.local/bin/rt` is a **symlink** to `<appPath>/Contents/MacOS/rt`; dev mode overwrites it with the wrapper script; `currentMode()` reads through links; rt reads `mattstack.appPath` (machine store) first, then `/Applications`, then `~/Applications`; legacy sweep also removes a stale `~/Applications/mattstack.app` and boots out the ghost `com.rt.daemon` unconditionally. (The sweep body and the `/Volumes/`/AppTranslocation exit-2 refusal live in L1 T27/T24's `commands/post-install.ts`; L4 supplies `installRtBinary`, `legacyUserAppPath`, `bundleRootFromExec` only.)
+- **Agent plist PATH (ruling R2):** `EnvironmentVariables.PATH` in both LaunchAgent plists is the **static** `/usr/bin:/bin:/usr/sbin:/sbin`; rt and deck prepend `<bundleRoot>/Contents/Helpers` (derived at runtime from their own execPath) and `$HOME/.local/bin` at process start. No `/Applications/...` path is ever written into a plist; `build.sh` does not touch `EnvironmentVariables` (the plists are rendered by L3's `rt-tray/scripts/render-launchagents.sh`); `check-bundle.sh` asserts the static value. `KeepAlive` is `{SuccessfulExit: false}` in **both** flavors (spec §8).
+- **Both agent plists ship:** `Contents/Library/LaunchAgents/com.mattstack.daemon[.dev].plist` and `com.mattstack.deck[.dev].plist` (L3 T2 owns the templates + render script; `build.sh` calls the script; `check-bundle.sh` asserts both). `Contents/Helpers/deck` itself stays absent until L5 publishes — the deck plist registers as `notFound` until then, which L1's `services.register` handles by requesting the deck plist only when the helper is bundled.
+- **build.sh never notarizes** (CI-only, in `scripts/release/notarize.sh`); `check-bundle.sh` keeps asserting that.
+- **rt repo stealth / honesty:** rt never writes into target repos; nothing is marked ready on a guess; every tool resolution says where it found the binary.
+- **Clean-code comments:** comments state constraints only; no process artifacts, task numbers, or decision history in source. Put rationale in commit bodies.
+- **Verification is local:** implementers run `bun test`, `bunx tsc --noEmit`, `bash -n <script>`, and `rt-tray/check-bundle.sh` themselves. Tasks needing Xcode 26, Apple notary, GitHub secrets, or the live machine are marked **ORCHESTRATOR-ONLY / MATT**.
+- **Cross-lane requirements folded in (from L7 clean room and L1):** (a) `SPARKLE_PUBLIC_ED_KEY` env overrides the committed `rt-tray/SUPublicEDKey` at build time so local/VM builds can use a throwaway key pair; (b) artifact names are fixed: `mattstack-<version>.dmg`, `mattstack-<version>.zip` (zip = Sparkle enclosure); (c) the post-release job calls `scripts/e2e-cleanroom.sh <zip>` (owned by L7; zip → `ditto -x -k` → `<app>/Contents/MacOS/rt --post-install --non-interactive --team-of-one --no-launch` → `rt verify --ci`) — this plan wires the invocation and does not write that script; (d) `--no-launch` / `--non-interactive` / `--team-of-one` are L1's flags on `rt --post-install` (today `cli.ts` ignores extra args after `--post-install`, so passing them is harmless until L1 lands); (e) nothing in the release artifacts may assume Homebrew on the target machine (L7's Tart images are vanilla).
+
+---
+
+## Decisions recorded by this plan
+
+1. **Appcast on the Release, not gh-pages.** m4ttstack/rt has no Pages site and no `gh-pages` branch today (verified: both API calls 404). Putting `appcast.xml` on each Release and pointing `SUFeedURL` at `…/releases/latest/download/appcast.xml` needs no extra branch, no extra commit, no Pages enablement, and keeps feed + enclosures + deltas on one host with one set of permissions (`contents: write` already present). GitHub serves it over HTTPS with a 302 that `NSURLSession` follows. Cost: a few-second window during release creation where `latest` resolves before `appcast.xml` is attached (Sparkle just retries next interval); and a pre-release never becomes `latest` (correct). **Ruled R1 (cross-plan review):** Release asset is the host; spec §11 and L3 T2 are amended to match. gh-pages is a documented escape hatch only (Open question 1, closed).
+2. **No tarball.** The clean-room job and any future headless install use the zip. `rt update`'s tarball path is deleted (by L1 T30, which owns `commands/update.ts`).
+3. **xcodebuild as a *builder*, not a signer.** Nested code (rt, Helpers, LaunchAgents, vsix, deps.lock) is added after the Swift build, which would invalidate any archive/export signature, so the xcodebuild path runs `xcodebuild build … CODE_SIGNING_ALLOWED=NO` and then the same assemble-and-sign function as the swift-build path. One signing path, one bundle contract, whichever compiler produced the tray binary.
+4. **Sparkle tools come from `deps.lock` too** (`kind: "buildtool"`, `Sparkle-2.9.6.tar.xz`, pinned sha256) — no third-party GitHub Action.
+5. **`bun` pinned to 1.3.13** in both `deps.lock` and the CI `setup-bun` step (1.3.12 is unsignable; 1.3.13 is what Matt runs).
+6. **fast-browser is bundled from its npm tarball** (`@mattstack/fast-browser@0.1.0-alpha.11`, zero runtime dependencies, MIT) as a package directory executed by the private node: `exec: ["Contents/Helpers/node/bin/node", "Contents/Helpers/fast-browser/bin/fast-browser.mjs"]`. No launcher scripts inside the bundle; L1's `rt deps link` renders the wrapper in `~/.local/bin` from `exec`.
+
+## Bundle layout contract (the L1 ↔ L4 interface)
+
+```
+mattstack.app/Contents/
+  Info.plist                              identity + Sparkle keys (build.sh is the only writer of identity values)
+  MacOS/mattstack                         tray executable (CFBundleExecutable)
+  MacOS/rt                                the rt binary (prod) / the dev source-runner shim (dev); codesign identifier "rt"
+  Frameworks/Sparkle.framework
+  Helpers/fzf  Helpers/jq  Helpers/gh  Helpers/glab  Helpers/bun      single Mach-O files
+  Helpers/node/                           node dist (bin/node, lib/node_modules/npm, …)
+  Helpers/fast-browser/                   npm package contents (bin/fast-browser.mjs, …)
+  Helpers/deck  Helpers/board  Helpers/gitq                           ABSENT until L5 publishes (deps.lock status "pending")
+  Library/LaunchAgents/com.mattstack.daemon[.dev].plist                BundleProgram Contents/MacOS/rt   (rendered by L3's render-launchagents.sh)
+  Library/LaunchAgents/com.mattstack.deck[.dev].plist                  BundleProgram Contents/Helpers/deck (same script; deck helper absent until L5)
+  Helpers/mattstack-proxy-install                                       ABSENT until L5 (deps.lock status "pending"; L3 T8's privileged helper)
+  Resources/deps.lock                     byte-identical copy of rt-tray/deps.lock
+  Resources/rt-context.vsix               the editor extension
+  Resources/AppIcon.icns, *.caf, mission-control-screenshot.png
+```
+
+`lib/bundle-layout.ts` (Task 1) exposes this to rt: `bundleRootFromExec()`, `appBundleRoot()`, `readDepsLock(root)`, `bundledHelperPath(name, root)`, `bundledExec(name, root)`. L1's `rt deps resolve|link` builds on these; nothing in L4 shells out to `rt deps`.
+
+---
+
+### Task 1: `lib/bundle-layout.ts` — the layout + deps.lock contract in TypeScript
+
+**Files:**
+- Create: `lib/bundle-layout.ts`
+- Create: `lib/__tests__/bundle-layout.test.ts`
+
+**Interfaces:**
+- Consumes: `installedTrayAppPath`, `TRAY_APP_BUNDLE`, `DEV_TRAY_APP_BUNDLE` from `lib/rt-paths.ts`; `currentMode` from `lib/dev-mode.ts`.
+- Produces (used by Tasks 2, 10, 11, 12 and by L1):
+  - `type DepsLockTool = { name; version; license; url; sha256; archive: "raw"|"tar.gz"|"tar.xz"|"zip"|"npm"; extract: string; bundlePath: string; exec: string[]; exposeByDefault: boolean; entitlements: "none"|"jit"; status: "bundled"|"pending"; kind: "helper"|"buildtool" }`
+  - `type DepsLock = { schema: 1; arch: "arm64"; tools: DepsLockTool[] }`
+  - `const DEPS_LOCK_BUNDLE_PATH = "Contents/Resources/deps.lock"`, `const HELPERS_DIR = "Contents/Helpers"`, `const RT_BUNDLE_PATH = "Contents/MacOS/rt"`
+  - `parseDepsLock(text: string): DepsLock` (throws on schema violations)
+  - `bundleRootFromExec(execPath?: string): string | null`
+  - `appBundleRoot(exists?: (p: string) => boolean): string | null`
+  - `readDepsLock(root: string): DepsLock | null`
+  - `bundledHelperPath(name: string, root?: string | null, exists?): string | null`
+  - `bundledExec(name: string, root?: string | null, exists?): string[] | null`
+
+- [ ] **Step 1: Write the failing tests**
+
+```ts
+// lib/__tests__/bundle-layout.test.ts
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import {
+  bundleRootFromExec, bundledExec, bundledHelperPath, parseDepsLock, readDepsLock,
+  DEPS_LOCK_BUNDLE_PATH,
+} from "../bundle-layout.ts";
+
+const LOCK = {
+  schema: 1,
+  arch: "arm64",
+  tools: [
+    { name: "fzf", version: "0.74.3", license: "MIT", url: "https://x/fzf.tar.gz", sha256: "a".repeat(64),
+      archive: "tar.gz", extract: "fzf", bundlePath: "Contents/Helpers/fzf", exec: ["Contents/Helpers/fzf"],
+      exposeByDefault: false, entitlements: "none", status: "bundled", kind: "helper" },
+    { name: "fast-browser", version: "0.1.0-alpha.11", license: "MIT", url: "https://x/fb.tgz", sha256: "b".repeat(64),
+      archive: "npm", extract: "package", bundlePath: "Contents/Helpers/fast-browser",
+      exec: ["Contents/Helpers/node/bin/node", "Contents/Helpers/fast-browser/bin/fast-browser.mjs"],
+      exposeByDefault: true, entitlements: "none", status: "bundled", kind: "helper" },
+    { name: "deck", version: "", license: "MIT", url: "", sha256: "", archive: "raw", extract: "",
+      bundlePath: "Contents/Helpers/deck", exec: ["Contents/Helpers/deck"],
+      exposeByDefault: true, entitlements: "jit", status: "pending", kind: "helper" },
+  ],
+};
+
+function fakeApp(): string {
+  const root = join(mkdtempSync(join(tmpdir(), "rt-bundle-")), "mattstack.app");
+  mkdirSync(join(root, "Contents", "MacOS"), { recursive: true });
+  mkdirSync(join(root, "Contents", "Resources"), { recursive: true });
+  mkdirSync(join(root, "Contents", "Helpers"), { recursive: true });
+  writeFileSync(join(root, "Contents", "Info.plist"), "<plist/>");
+  writeFileSync(join(root, "Contents", "MacOS", "rt"), "");
+  writeFileSync(join(root, DEPS_LOCK_BUNDLE_PATH), JSON.stringify(LOCK));
+  writeFileSync(join(root, "Contents", "Helpers", "fzf"), "");
+  return root;
+}
+
+describe("parseDepsLock", () => {
+  test("accepts the schema and keeps tool order", () => {
+    const lock = parseDepsLock(JSON.stringify(LOCK));
+    expect(lock.tools.map((t) => t.name)).toEqual(["fzf", "fast-browser", "deck"]);
+  });
+  test("rejects duplicate names, bundled tools without url/sha256, and pending tools with a url", () => {
+    const dup = { ...LOCK, tools: [LOCK.tools[0], LOCK.tools[0]] };
+    expect(() => parseDepsLock(JSON.stringify(dup))).toThrow(/duplicate/);
+    const noSha = { ...LOCK, tools: [{ ...LOCK.tools[0], sha256: "" }] };
+    expect(() => parseDepsLock(JSON.stringify(noSha))).toThrow(/sha256/);
+    const pendingUrl = { ...LOCK, tools: [{ ...LOCK.tools[2], url: "https://x" }] };
+    expect(() => parseDepsLock(JSON.stringify(pendingUrl))).toThrow(/pending/);
+  });
+  test("rejects a bundlePath outside Contents/Helpers for helpers", () => {
+    const bad = { ...LOCK, tools: [{ ...LOCK.tools[0], bundlePath: "Contents/MacOS/fzf" }] };
+    expect(() => parseDepsLock(JSON.stringify(bad))).toThrow(/Contents\/Helpers/);
+  });
+});
+
+describe("bundleRootFromExec", () => {
+  test("finds the .app root from Contents/MacOS/<bin>", () => {
+    const root = fakeApp();
+    expect(bundleRootFromExec(join(root, "Contents", "MacOS", "rt"))).toBe(root);
+  });
+  test("null for a binary that is not inside a bundle", () => {
+    expect(bundleRootFromExec("/usr/bin/true")).toBeNull();
+  });
+});
+
+describe("bundledHelperPath / bundledExec", () => {
+  test("resolve a bundled helper to its absolute path", () => {
+    const root = fakeApp();
+    expect(bundledHelperPath("fzf", root)).toBe(join(root, "Contents", "Helpers", "fzf"));
+    expect(bundledExec("fzf", root)).toEqual([join(root, "Contents", "Helpers", "fzf")]);
+  });
+  test("null for a pending tool, an unknown tool, and a bundled tool whose file is missing", () => {
+    const root = fakeApp();
+    expect(bundledHelperPath("deck", root)).toBeNull();
+    expect(bundledHelperPath("nope", root)).toBeNull();
+    expect(bundledHelperPath("fast-browser", root)).toBeNull();
+  });
+  test("null when there is no bundle root", () => {
+    expect(bundledHelperPath("fzf", null)).toBeNull();
+    expect(readDepsLock("/nonexistent.app")).toBeNull();
+  });
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `bun test lib/__tests__/bundle-layout.test.ts`
+Expected: FAIL — `Cannot find module '../bundle-layout.ts'`.
+
+- [ ] **Step 3: Implement**
+
+```ts
+// lib/bundle-layout.ts
+/**
+ * The mattstack.app bundle layout and deps.lock schema, as rt sees them.
+ * build.sh writes this layout; check-bundle.sh asserts it; `rt deps` (L1)
+ * and the fzf resolver read it through here. Paths are relative to the .app
+ * root unless a function says "absolute".
+ */
+import { existsSync, readFileSync, realpathSync } from "fs";
+import { basename, dirname, join } from "path";
+import { currentMode } from "./dev-mode.ts";
+import { DEV_TRAY_APP_BUNDLE, TRAY_APP_BUNDLE, installedTrayAppPath } from "./rt-paths.ts";
+
+export type DepsLockArchive = "raw" | "tar.gz" | "tar.xz" | "zip" | "npm";
+export type DepsLockEntitlements = "none" | "jit";
+export type DepsLockStatus = "bundled" | "pending";
+export type DepsLockKind = "helper" | "buildtool";
+
+export interface DepsLockTool {
+  name: string;
+  version: string;
+  license: string;
+  url: string;
+  sha256: string;
+  archive: DepsLockArchive;
+  /** Path inside the archive to copy into bundlePath; "" for a raw binary. */
+  extract: string;
+  /** Bundle-relative destination (file or directory). */
+  bundlePath: string;
+  /** Bundle-relative argv prefix that runs the tool. */
+  exec: string[];
+  exposeByDefault: boolean;
+  entitlements: DepsLockEntitlements;
+  status: DepsLockStatus;
+  kind: DepsLockKind;
+}
+
+export interface DepsLock {
+  schema: 1;
+  arch: "arm64";
+  tools: DepsLockTool[];
+}
+
+export const DEPS_LOCK_BUNDLE_PATH = "Contents/Resources/deps.lock";
+export const HELPERS_DIR = "Contents/Helpers";
+export const RT_BUNDLE_PATH = "Contents/MacOS/rt";
+
+const ARCHIVES = new Set<DepsLockArchive>(["raw", "tar.gz", "tar.xz", "zip", "npm"]);
+const SHA256 = /^[0-9a-f]{64}$/;
+
+export function parseDepsLock(text: string): DepsLock {
+  const raw = JSON.parse(text) as DepsLock;
+  if (raw.schema !== 1) throw new Error(`deps.lock: unsupported schema ${String(raw.schema)}`);
+  if (raw.arch !== "arm64") throw new Error(`deps.lock: arch must be arm64, got ${String(raw.arch)}`);
+  if (!Array.isArray(raw.tools)) throw new Error("deps.lock: tools must be an array");
+  const seen = new Set<string>();
+  for (const t of raw.tools) {
+    if (!t.name) throw new Error("deps.lock: tool without a name");
+    if (seen.has(t.name)) throw new Error(`deps.lock: duplicate tool ${t.name}`);
+    seen.add(t.name);
+    if (!ARCHIVES.has(t.archive)) throw new Error(`deps.lock: ${t.name} has unknown archive ${String(t.archive)}`);
+    if (t.kind !== "helper" && t.kind !== "buildtool") throw new Error(`deps.lock: ${t.name} has unknown kind`);
+    if (t.status !== "bundled" && t.status !== "pending") throw new Error(`deps.lock: ${t.name} has unknown status`);
+    if (t.entitlements !== "none" && t.entitlements !== "jit") throw new Error(`deps.lock: ${t.name} has unknown entitlements`);
+    if (typeof t.exposeByDefault !== "boolean") throw new Error(`deps.lock: ${t.name} exposeByDefault must be boolean`);
+    if (!Array.isArray(t.exec) || t.exec.length === 0) throw new Error(`deps.lock: ${t.name} needs a non-empty exec`);
+    if (t.kind === "helper" && !t.bundlePath.startsWith(`${HELPERS_DIR}/`)) {
+      throw new Error(`deps.lock: ${t.name} bundlePath must live under ${HELPERS_DIR}/`);
+    }
+    if (t.status === "bundled") {
+      if (!t.url) throw new Error(`deps.lock: bundled tool ${t.name} needs a url`);
+      if (!SHA256.test(t.sha256)) throw new Error(`deps.lock: bundled tool ${t.name} needs a 64-hex sha256`);
+      if (!t.version) throw new Error(`deps.lock: bundled tool ${t.name} needs a version`);
+    } else if (t.url || t.sha256) {
+      throw new Error(`deps.lock: pending tool ${t.name} must not carry a url or sha256`);
+    }
+  }
+  return raw;
+}
+
+/** The .app root containing execPath (resolved through symlinks), or null. */
+export function bundleRootFromExec(execPath: string = process.execPath): string | null {
+  let real: string;
+  try { real = realpathSync(execPath); } catch { return null; }
+  const macos = dirname(real);
+  const contents = dirname(macos);
+  const root = dirname(contents);
+  if (basename(macos) !== "MacOS" || basename(contents) !== "Contents") return null;
+  if (!root.endsWith(".app") || !existsSync(join(contents, "Info.plist"))) return null;
+  return root;
+}
+
+/** The bundle rt belongs to: the one it runs from, else the installed active flavor. */
+export function appBundleRoot(exists: (p: string) => boolean = existsSync): string | null {
+  const fromExec = bundleRootFromExec();
+  if (fromExec) return fromExec;
+  const bundle = currentMode() === "dev" ? DEV_TRAY_APP_BUNDLE : TRAY_APP_BUNDLE;
+  return installedTrayAppPath(bundle, exists);
+}
+
+export function readDepsLock(root: string): DepsLock | null {
+  try {
+    return parseDepsLock(readFileSync(join(root, DEPS_LOCK_BUNDLE_PATH), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function bundledTool(name: string, root: string | null): { tool: DepsLockTool; root: string } | null {
+  if (!root) return null;
+  const lock = readDepsLock(root);
+  const tool = lock?.tools.find((t) => t.name === name);
+  if (!tool || tool.status !== "bundled") return null;
+  return { tool, root };
+}
+
+/** Absolute path of a bundled helper's bundlePath, only if it exists on disk. */
+export function bundledHelperPath(
+  name: string,
+  root: string | null = appBundleRoot(),
+  exists: (p: string) => boolean = existsSync,
+): string | null {
+  const found = bundledTool(name, root);
+  if (!found) return null;
+  const abs = join(found.root, found.tool.bundlePath);
+  return exists(abs) ? abs : null;
+}
+
+/** Absolute argv prefix that runs a bundled helper, only if every exec path exists. */
+export function bundledExec(
+  name: string,
+  root: string | null = appBundleRoot(),
+  exists: (p: string) => boolean = existsSync,
+): string[] | null {
+  const found = bundledTool(name, root);
+  if (!found) return null;
+  const argv = found.tool.exec.map((p) => join(found.root, p));
+  return argv.every(exists) ? argv : null;
+}
+```
+
+- [ ] **Step 4: Run tests + typecheck**
+
+Run: `bun test lib/__tests__/bundle-layout.test.ts && bunx tsc --noEmit`
+Expected: PASS, tsc clean.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lib/bundle-layout.ts lib/__tests__/bundle-layout.test.ts
+git commit -m "MAT-383: lib/bundle-layout — deps.lock schema + bundle paths as rt sees them
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 2: `rt-tray/deps.lock` + `scripts/fetch-deps.sh` + `scripts/lib/deps-lock.ts`
+
+**Files:**
+- Create: `rt-tray/deps.lock`
+- Create: `scripts/lib/deps-lock.ts` (TSV emitter for bash consumers)
+- Create: `scripts/fetch-deps.sh`
+- Modify: `.gitignore` (add `rt-tray/deps/`, `rt-tray/out/`, `rt-tray/.build-xcode/` — `rt-tray/*.xcodeproj/` is L3 T1's line; do not add it here)
+- Create: `lib/__tests__/deps-lock-file.test.ts`
+
+**Interfaces:**
+- Consumes: `parseDepsLock` from Task 1.
+- Produces: `rt-tray/deps/arm64/<name>` (file) or `rt-tray/deps/arm64/<name>/` (dir) per bundled helper; `rt-tray/deps/tools/sparkle/bin/{generate_appcast,sign_update,generate_keys}`; `bun scripts/lib/deps-lock.ts [--kind helper|buildtool] [--status bundled|pending]` prints TSV rows `name\tversion\turl\tsha256\tarchive\textract\tbundlePath\tentitlements\tstatus\tkind\texposeByDefault`. `scripts/fetch-deps.sh [arm64]` exit 0 with everything present and verified; `scripts/fetch-deps.sh --lock` fills empty `sha256` fields from fresh downloads and rewrites the lock (only for adding tools later).
+
+- [ ] **Step 1: Write the lock**
+
+```json
+{
+  "schema": 1,
+  "arch": "arm64",
+  "tools": [
+    { "name": "fzf", "version": "0.74.3", "license": "MIT",
+      "url": "https://github.com/junegunn/fzf/releases/download/v0.74.3/fzf-0.74.3-darwin_arm64.tar.gz",
+      "sha256": "1f8501cea4f9c0c2d6110d0ff75d0ec9451cd9d7524d9a26244a154ea89f3bd5",
+      "archive": "tar.gz", "extract": "fzf", "bundlePath": "Contents/Helpers/fzf", "exec": ["Contents/Helpers/fzf"],
+      "exposeByDefault": false, "entitlements": "none", "status": "bundled", "kind": "helper" },
+    { "name": "jq", "version": "1.8.2", "license": "MIT",
+      "url": "https://github.com/jqlang/jq/releases/download/jq-1.8.2/jq-macos-arm64",
+      "sha256": "2d75340ba57a4b4b4c8708a21c2dc8e958a48aaa8bba13b27f77f6e4c0eca07e",
+      "archive": "raw", "extract": "", "bundlePath": "Contents/Helpers/jq", "exec": ["Contents/Helpers/jq"],
+      "exposeByDefault": false, "entitlements": "none", "status": "bundled", "kind": "helper" },
+    { "name": "gh", "version": "2.98.0", "license": "MIT",
+      "url": "https://github.com/cli/cli/releases/download/v2.98.0/gh_2.98.0_macOS_arm64.zip",
+      "sha256": "8cfb027cc5310675f2b830eac8f9865c1155a45ffcf9757f699fdd5a22046ca4",
+      "archive": "zip", "extract": "gh_2.98.0_macOS_arm64/bin/gh", "bundlePath": "Contents/Helpers/gh", "exec": ["Contents/Helpers/gh"],
+      "exposeByDefault": false, "entitlements": "none", "status": "bundled", "kind": "helper" },
+    { "name": "glab", "version": "1.114.0", "license": "MIT",
+      "url": "https://gitlab.com/api/v4/projects/gitlab-org%2Fcli/packages/generic/glab/1.114.0/glab_1.114.0_darwin_arm64.tar.gz",
+      "sha256": "d60d76cc0176cd7e7efe9c9fae0e57979048dad78fdd24903ba986ded1c82a01",
+      "archive": "tar.gz", "extract": "bin/glab", "bundlePath": "Contents/Helpers/glab", "exec": ["Contents/Helpers/glab"],
+      "exposeByDefault": false, "entitlements": "none", "status": "bundled", "kind": "helper" },
+    { "name": "bun", "version": "1.3.13", "license": "MIT",
+      "url": "https://github.com/oven-sh/bun/releases/download/bun-v1.3.13/bun-darwin-aarch64.zip",
+      "sha256": "5467e3f65dba526b9fea98f0cce04efafc0c63e169733ec27b876a3ad32da190",
+      "archive": "zip", "extract": "bun-darwin-aarch64/bun", "bundlePath": "Contents/Helpers/bun", "exec": ["Contents/Helpers/bun"],
+      "exposeByDefault": false, "entitlements": "jit", "status": "bundled", "kind": "helper" },
+    { "name": "node", "version": "24.19.0", "license": "MIT",
+      "url": "https://nodejs.org/dist/v24.19.0/node-v24.19.0-darwin-arm64.tar.gz",
+      "sha256": "8294b7aa9b03997481c06babf1e8b270c859358f27da57a11509afe537ac381d",
+      "archive": "tar.gz", "extract": "node-v24.19.0-darwin-arm64", "bundlePath": "Contents/Helpers/node", "exec": ["Contents/Helpers/node/bin/node"],
+      "exposeByDefault": false, "entitlements": "jit", "status": "bundled", "kind": "helper" },
+    { "name": "fast-browser", "version": "0.1.0-alpha.11", "license": "MIT",
+      "url": "https://registry.npmjs.org/@mattstack/fast-browser/-/fast-browser-0.1.0-alpha.11.tgz",
+      "sha256": "43d0faf99e78d0a4ac5a72fcb201557ddb1fa1fe1180bb0e01a1e6df0286b728",
+      "archive": "npm", "extract": "package", "bundlePath": "Contents/Helpers/fast-browser",
+      "exec": ["Contents/Helpers/node/bin/node", "Contents/Helpers/fast-browser/bin/fast-browser.mjs"],
+      "exposeByDefault": true, "entitlements": "none", "status": "bundled", "kind": "helper" },
+    { "name": "deck", "version": "", "license": "MIT", "url": "", "sha256": "",
+      "archive": "raw", "extract": "", "bundlePath": "Contents/Helpers/deck", "exec": ["Contents/Helpers/deck"],
+      "exposeByDefault": true, "entitlements": "jit", "status": "pending", "kind": "helper" },
+    { "name": "board", "version": "", "license": "MIT", "url": "", "sha256": "",
+      "archive": "raw", "extract": "", "bundlePath": "Contents/Helpers/board", "exec": ["Contents/Helpers/board"],
+      "exposeByDefault": false, "entitlements": "jit", "status": "pending", "kind": "helper" },
+    { "name": "gitq", "version": "", "license": "MIT", "url": "", "sha256": "",
+      "archive": "raw", "extract": "", "bundlePath": "Contents/Helpers/gitq", "exec": ["Contents/Helpers/gitq"],
+      "exposeByDefault": true, "entitlements": "jit", "status": "pending", "kind": "helper" },
+    { "name": "mattstack-proxy-install", "version": "", "license": "MIT", "url": "", "sha256": "",
+      "archive": "raw", "extract": "", "bundlePath": "Contents/Helpers/mattstack-proxy-install", "exec": ["Contents/Helpers/mattstack-proxy-install"],
+      "exposeByDefault": false, "entitlements": "none", "status": "pending", "kind": "helper" },
+    { "name": "sparkle", "version": "2.9.6", "license": "MIT",
+      "url": "https://github.com/sparkle-project/Sparkle/releases/download/2.9.6/Sparkle-2.9.6.tar.xz",
+      "sha256": "52bf9e88cdd972fc0c81501377a880e90d47031bd8ca5462488f843e2609e192",
+      "archive": "tar.xz", "extract": "", "bundlePath": "tools/sparkle", "exec": ["tools/sparkle/bin/generate_appcast"],
+      "exposeByDefault": false, "entitlements": "none", "status": "bundled", "kind": "buildtool" }
+  ]
+}
+```
+
+(The sha256 values above were computed on 2026-08-21 from the exact URLs; `fetch-deps.sh` re-verifies every download.)
+
+`mattstack-proxy-install` is the privileged proxy helper L3 T8 execs from `Contents/Helpers/` (cross-plan review §2 #28). Nobody builds it in this program — it ships with L5. The `pending` row makes `check-bundle.sh` tolerate its absence and lets L3 report "helper not bundled" honestly; record it in L5's handoff.
+
+- [ ] **Step 2: Write the failing lock-file test**
+
+```ts
+// lib/__tests__/deps-lock-file.test.ts
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "fs";
+import { join } from "path";
+import { parseDepsLock } from "../bundle-layout.ts";
+
+const LOCK_PATH = join(import.meta.dir, "..", "..", "rt-tray", "deps.lock");
+
+describe("rt-tray/deps.lock", () => {
+  const lock = parseDepsLock(readFileSync(LOCK_PATH, "utf8"));
+
+  test("parses under the schema", () => {
+    expect(lock.schema).toBe(1);
+    expect(lock.arch).toBe("arm64");
+  });
+  test("carries the ruling-8 bundle set, with deck/board/gitq pending until L5", () => {
+    const by = Object.fromEntries(lock.tools.map((t) => [t.name, t]));
+    for (const n of ["fzf", "jq", "gh", "glab", "bun", "node", "fast-browser"]) expect(by[n]?.status).toBe("bundled");
+    for (const n of ["deck", "board", "gitq", "mattstack-proxy-install"]) expect(by[n]?.status).toBe("pending");
+    expect(by["sparkle"]?.kind).toBe("buildtool");
+  });
+  test("default-exposed set is exactly fast-browser, gitq, deck (rt is exposed by the binary link, not a helper)", () => {
+    const exposed = lock.tools.filter((t) => t.exposeByDefault).map((t) => t.name).sort();
+    expect(exposed).toEqual(["deck", "fast-browser", "gitq"]);
+  });
+  test("bun-based helpers declare jit entitlements; Go/C helpers declare none", () => {
+    const by = Object.fromEntries(lock.tools.map((t) => [t.name, t]));
+    expect(by["bun"].entitlements).toBe("jit");
+    expect(by["node"].entitlements).toBe("jit");
+    for (const n of ["fzf", "jq", "gh", "glab"]) expect(by[n].entitlements).toBe("none");
+  });
+});
+```
+
+Run: `bun test lib/__tests__/deps-lock-file.test.ts` → FAIL (file missing) until Step 1's JSON is saved at `rt-tray/deps.lock`; then PASS.
+
+- [ ] **Step 3: TSV emitter for bash**
+
+```ts
+// scripts/lib/deps-lock.ts
+// Prints rt-tray/deps.lock as TSV so build.sh / fetch-deps.sh / check-bundle.sh
+// never parse JSON in bash. Usage: bun scripts/lib/deps-lock.ts [--kind K] [--status S]
+import { readFileSync } from "fs";
+import { join } from "path";
+import { parseDepsLock } from "../../lib/bundle-layout.ts";
+
+const args = process.argv.slice(2);
+const opt = (flag: string): string | null => { const i = args.indexOf(flag); return i >= 0 ? args[i + 1] ?? null : null; };
+const kind = opt("--kind");
+const status = opt("--status");
+
+const lock = parseDepsLock(readFileSync(join(import.meta.dir, "..", "..", "rt-tray", "deps.lock"), "utf8"));
+for (const t of lock.tools) {
+  if (kind && t.kind !== kind) continue;
+  if (status && t.status !== status) continue;
+  console.log([t.name, t.version, t.url, t.sha256, t.archive, t.extract, t.bundlePath, t.entitlements, t.status, t.kind, String(t.exposeByDefault)].join("\t"));
+}
+```
+
+Run: `bun scripts/lib/deps-lock.ts --kind helper --status bundled | wc -l` → `7`.
+
+- [ ] **Step 4: fetch-deps.sh**
+
+```bash
+#!/bin/bash
+# scripts/fetch-deps.sh [arm64] [--lock]
+# Downloads every bundled tool in rt-tray/deps.lock, verifies sha256, and
+# unpacks it into rt-tray/deps/<arch>/<name> (helpers) or
+# rt-tray/deps/tools/<name> (build tools). --lock fills EMPTY sha256 fields
+# from the downloads and rewrites deps.lock (for adding a tool); it never
+# overwrites a non-empty hash.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+ARCH="arm64"
+WRITE_LOCK=false
+for a in "$@"; do
+  case "$a" in
+    arm64) ARCH=arm64 ;;
+    --lock) WRITE_LOCK=true ;;
+    *) echo "usage: $0 [arm64] [--lock]" >&2; exit 2 ;;
+  esac
+done
+
+LOCK="$ROOT/rt-tray/deps.lock"
+DEPS="$ROOT/rt-tray/deps/$ARCH"
+TOOLS="$ROOT/rt-tray/deps/tools"
+CACHE="${RT_DEPS_CACHE:-$HOME/Library/Caches/mattstack-deps}"
+mkdir -p "$DEPS" "$TOOLS" "$CACHE"
+
+sha() { shasum -a 256 "$1" | cut -d' ' -f1; }
+
+fetch() { # url sha → prints cached path
+  local url="$1" want="$2" name dest
+  name="$(basename "$url")"
+  dest="$CACHE/${want:-nohash}-$name"
+  if [ ! -f "$dest" ]; then
+    curl -fsSL --retry 3 -o "$dest.part" "$url"
+    mv "$dest.part" "$dest"
+  fi
+  if [ -n "$want" ] && [ "$(sha "$dest")" != "$want" ]; then
+    echo "  ✗ sha256 mismatch for $name (want $want, got $(sha "$dest"))" >&2
+    rm -f "$dest"; exit 1
+  fi
+  echo "$dest"
+}
+
+unpack() { # archive-file archive-kind extract-path dest
+  local file="$1" kind="$2" extract="$3" dest="$4" tmp
+  rm -rf "$dest"
+  mkdir -p "$(dirname "$dest")"
+  case "$kind" in
+    raw) cp "$file" "$dest"; chmod 755 "$dest" ;;
+    tar.gz|tar.xz|npm)
+      tmp="$(mktemp -d)"
+      tar -xf "$file" -C "$tmp"
+      if [ -n "$extract" ]; then cp -R "$tmp/$extract" "$dest"; else cp -R "$tmp" "$dest"; fi
+      rm -rf "$tmp" ;;
+    zip)
+      tmp="$(mktemp -d)"
+      ditto -x -k "$file" "$tmp"
+      cp -R "$tmp/$extract" "$dest"
+      rm -rf "$tmp" ;;
+    *) echo "  ✗ unknown archive kind $kind" >&2; exit 1 ;;
+  esac
+  [ -d "$dest" ] || chmod 755 "$dest"
+}
+
+NEW_HASHES=()
+while IFS=$'\t' read -r name version url sha archive extract bundlePath ent status kind expose; do
+  [ "$status" = "bundled" ] || { echo "  · $name: pending (not bundled in this build)"; continue; }
+  if [ "$kind" = "buildtool" ]; then dest="$TOOLS/$name"; else dest="$DEPS/$name"; fi
+  if [ -z "$sha" ]; then
+    $WRITE_LOCK || { echo "  ✗ $name has no sha256 in deps.lock — run $0 --lock" >&2; exit 1; }
+    file="$(fetch "$url" "")"
+    sha="$(sha "$file")"
+    NEW_HASHES+=("$name=$sha")
+  else
+    file="$(fetch "$url" "$sha")"
+  fi
+  unpack "$file" "$archive" "$extract" "$dest"
+  echo "  ✓ $name $version → ${dest#$ROOT/}"
+done < <(bun "$ROOT/scripts/lib/deps-lock.ts")
+
+if $WRITE_LOCK && [ ${#NEW_HASHES[@]} -gt 0 ]; then
+  for kv in "${NEW_HASHES[@]}"; do
+    n="${kv%%=*}"; h="${kv#*=}"
+    bun -e '
+      const [path, name, hash] = Bun.argv.slice(2);
+      const lock = JSON.parse(await Bun.file(path).text());
+      const t = lock.tools.find((x) => x.name === name); t.sha256 = hash;
+      await Bun.write(path, JSON.stringify(lock, null, 2) + "\n");
+    ' "$LOCK" "$n" "$h"
+    echo "  ✓ wrote sha256 for $n into deps.lock"
+  done
+fi
+
+# Sparkle's tools are an xz tarball with bin/ at its root; --help proves they run.
+[ -x "$TOOLS/sparkle/bin/generate_appcast" ] && "$TOOLS/sparkle/bin/generate_appcast" --help >/dev/null 2>&1 \
+  && echo "  ✓ sparkle tools runnable"
+echo "  Done."
+```
+
+Run: `bash -n scripts/fetch-deps.sh && chmod +x scripts/fetch-deps.sh && scripts/fetch-deps.sh arm64`
+Expected: seven `✓` helper lines + `sparkle`, `rt-tray/deps/arm64/{fzf,jq,gh,glab,bun,node/,fast-browser/}` present, `rt-tray/deps/tools/sparkle/bin/generate_appcast` runnable, `file rt-tray/deps/arm64/fzf` says Mach-O arm64. Then `rt-tray/deps/arm64/fzf --version`, `rt-tray/deps/arm64/jq --version`, `rt-tray/deps/arm64/gh --version`, `rt-tray/deps/arm64/glab --version`, `rt-tray/deps/arm64/bun --version` (prints 1.3.13), `rt-tray/deps/arm64/node/bin/node --version` (v24.19.0), `rt-tray/deps/arm64/node/bin/node rt-tray/deps/arm64/fast-browser/bin/fast-browser.mjs --help` exits 0.
+
+- [ ] **Step 5: .gitignore**
+
+Append to `.gitignore`:
+```
+rt-tray/deps/
+rt-tray/out/
+rt-tray/.build-xcode/
+```
+(`rt-tray/*.xcodeproj/` is added by L3 T1 — L3's `project.yml` regenerates the project; cross-plan review §1 row 8. Rebase-after if L3 merged first; the three lines above are disjoint.)
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add rt-tray/deps.lock scripts/lib/deps-lock.ts scripts/fetch-deps.sh .gitignore lib/__tests__/deps-lock-file.test.ts
+git commit -m "MAT-383: deps.lock + fetch-deps.sh — pinned, sha256-verified helpers for the bundle
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 3: Identity freeze — `rt-daemon` → `rt`, plist keys, numeric build, jit-only entitlements
+
+**Trimmed by the cross-plan review (§1 rows 12, 15, 16, 18, 19):** the plist templates, `Package.swift`, and every Swift file are L3's. This task keeps only the rt-side edits, the minimal `build.sh` edits, and the `check-bundle.sh` rewrite.
+
+**Files:**
+- ~~Modify: `rt-tray/LaunchAgent.plist`~~ — Dropped — owned by L3 T2 (cross-plan review); L3 T2 applies the `BundleProgram Contents/MacOS/rt` / `ProgramArguments` / Label-comment edit in its template.
+- ~~Modify: `rt-tray/Info.plist`~~ — Dropped — owned by L3 T2 (cross-plan review); `CFBundleURLName` is `@@BUNDLE_ID@@.join` (L3's value; L4's `.url` is withdrawn).
+- ~~Modify: `rt-tray/Package.swift`~~ — Dropped — owned by L3 T1 (cross-plan review); L3 T1 sets `.macOS(.v14)`.
+- Modify: `rt-tray/build.sh` (embed as `Contents/MacOS/rt`, sign `-i rt`, numeric CFBundleVersion; full rewrite lands in Task 4 — this task makes the minimal edits listed here)
+- ~~Modify: `rt-tray/Sources/AppDelegate.swift:331`, `rt-tray/Sources/UpdateChecker.swift:164`, `rt-tray/Sources/DaemonLifecycle.swift:8`, `rt-tray/Sources-daemon-shim/main.swift:4,26`~~ — Dropped — owned by L3 T18 (`AppDelegate.swift`, `DaemonLifecycle.swift`, `Sources-daemon-shim/main.swift` string/comment edits) and L3 T10 (`UpdateChecker.swift` is deleted) (cross-plan review).
+- Modify: `commands/settings.ts:462-471` (`disableDevMode` reads `Contents/MacOS/rt`)
+- Modify: `lib/__tests__/dev-mode-handoff.test.ts:185-188`
+- Modify: `scripts/entitlements.plist` (allow-jit only)
+- Modify: `rt-tray/check-bundle.sh` (full rewrite, below)
+
+**Interfaces:**
+- Produces: identifier `rt` on the embedded binary; `numeric_build()` bash function in build.sh (`2.8.0 → 2008000`); `scripts/entitlements.plist` = jit only; `check-bundle.sh` exit 0 = contract holds. The bundle path `Contents/MacOS/rt` itself is produced by L3 T2's templates + L3 T18's Swift edits; this task's check-bundle asserts it.
+- Consumes: nothing from earlier tasks (Helpers/Sparkle assertions are added by Tasks 4–5). The check-bundle Swift-source gates (Step 5, last section) are explicit requirements on L3 T9 (`TrayServer` keeps the literal `path == "/flavor/retire"`) and L3 T18 (`forInfoDictionaryKey: "MSDaemonLabel"`, `defaultDaemonLabel = "com.mattstack.daemon"`, socket guard before `AppDelegate()` in `main.swift`, `UpdatePolicy.shouldStartUpdater(isDevBuild: isDevBuild` in `Sources/Updates/UpdaterController.swift`, the string `update check skipped (dev build)`).
+
+- [ ] **Step 1: Plists + Package.swift**
+
+Dropped — owned by L3 T2 (templates: `BundleProgram Contents/MacOS/rt`, `ProgramArguments [Contents/MacOS/rt, --daemon]`, Label comment, `LSMinimumSystemVersion 14.0`, `CFBundleURLTypes` with `CFBundleURLName @@BUNDLE_ID@@.join`) and L3 T1 (`Package.swift` `.macOS(.v14)`) (cross-plan review §1 rows 12, 15, 16).
+
+- [ ] **Step 2: Swift + TS references**
+
+Swift edits dropped — owned by L3 T18 (`AppDelegate.swift:331` → `Bundle.main.bundlePath + "/Contents/MacOS/rt"`; `DaemonLifecycle.swift:8,17-18`; `Sources-daemon-shim/main.swift:4,26`) and L3 T10 (`UpdateChecker.swift` deleted) (cross-plan review §1 rows 18, 19). TS edits stay:
+
+- `commands/settings.ts` docblock line 462: `…carries at Contents/MacOS/rt`; line 471: `const prodBinary = join(prodAppPath, "Contents", "MacOS", "rt");`
+- `lib/__tests__/dev-mode-handoff.test.ts:185-188`: replace `"rt-daemon"` with `"rt"` in both the comment and the `writeFileSync` path.
+
+- [ ] **Step 3: Entitlements**
+
+`scripts/entitlements.plist` becomes:
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <!-- JavaScriptCore / V8 JIT under the hardened runtime. Add
+       com.apple.security.cs.allow-unsigned-executable-memory for a specific
+       tool only if that signed tool crashes at launch (see deps.lock). -->
+  <key>com.apple.security.cs.allow-jit</key><true/>
+</dict>
+</plist>
+```
+Sanity: `bun build --compile ./cli.ts --outfile /tmp/rt-jit && codesign --force --sign - --entitlements scripts/entitlements.plist /tmp/rt-jit && /tmp/rt-jit --version` prints the version (ad-hoc + jit-only runs; the Developer-ID measurement is Task 14).
+
+- [ ] **Step 4: build.sh minimal edits (pre-rewrite)**
+
+In `rt-tray/build.sh`: every `Contents/MacOS/rt-daemon` → `Contents/MacOS/rt`; `DAEMON_BIN="$APP_BUNDLE/Contents/MacOS/rt"`; both codesign calls on it use `-i rt`; replace the version block (lines 244-250) with:
+```bash
+numeric_build() {
+    local v="${1#v}"
+    if [[ "$v" =~ ^([0-9]+)\.([0-9]+)\.([0-9]+) ]]; then
+        echo $(( BASH_REMATCH[1] * 1000000 + BASH_REMATCH[2] * 1000 + BASH_REMATCH[3] ))
+    else
+        echo 0
+    fi
+}
+RT_VERSION=$(cd "$SCRIPT_DIR/.." && git describe --tags --abbrev=0 2>/dev/null || echo "dev")
+RT_VERSION="${RT_VERSION#v}"
+if [ "$RT_VERSION" != "dev" ]; then
+    /usr/libexec/PlistBuddy -c "Set :CFBundleShortVersionString $RT_VERSION" "$APP_BUNDLE/Contents/Info.plist"
+    /usr/libexec/PlistBuddy -c "Set :CFBundleVersion $(numeric_build "$RT_VERSION")" "$APP_BUNDLE/Contents/Info.plist"
+    echo "  ✓ Version set to $RT_VERSION (build $(numeric_build "$RT_VERSION"))"
+fi
+```
+`RT_VERSION` may also be passed in by CI as `RT_VERSION=v2.8.0 rt-tray/build.sh release` — change the first line to `RT_VERSION="${RT_VERSION:-$(cd "$SCRIPT_DIR/.." && git describe --tags --abbrev=0 2>/dev/null || echo dev)}"`.
+
+- [ ] **Step 5: Rewrite `rt-tray/check-bundle.sh`**
+
+```bash
+#!/bin/bash
+# rt-tray/check-bundle.sh — asserts the mattstack.app bundle contract for BOTH
+# flavors. Builds them via build.sh (no notarization; that is CI-only), then
+# checks identity, layout, signing, Helpers, Sparkle, and the dev shim's exit
+# codes. Exit 0 only when every assertion passes.
+#
+# Usage:
+#   RT_DAEMON_BIN=../dist/rt ./check-bundle.sh     # embed a compiled rt (a
+#                                                  # dev-mode machine's `rt`
+#                                                  # on PATH is a script)
+#   ./check-bundle.sh --app /Applications/mattstack.app   # assert an INSTALLED
+#                                                         # prod bundle, no build
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+cd "$SCRIPT_DIR"
+
+PASS=0; FAIL=0
+pass() { echo "  ✓ $1"; PASS=$((PASS + 1)); }
+fail() { echo "  ✗ $1"; FAIL=$((FAIL + 1)); }
+assert_eq() {
+    local desc="$1" expected="$2" actual="$3"
+    if [ "$expected" = "$actual" ]; then pass "$desc = $actual"; else fail "$desc: expected [$expected], got [$actual]"; fi
+}
+plist() { /usr/libexec/PlistBuddy -c "Print :$2" "$1" 2>/dev/null; }
+
+PROD="$SCRIPT_DIR/mattstack.app"
+DEV="$SCRIPT_DIR/mattstack-dev.app"
+INSTALLED_ONLY=false
+if [ "${1:-}" = "--app" ]; then
+    INSTALLED_ONLY=true
+    PROD="$2"
+    DEV=""
+else
+    echo "== Building prod flavor (release) =="; ./build.sh release; echo ""
+    echo "== Building dev flavor (dev) ==";      ./build.sh dev;     echo ""
+fi
+echo "== Assertions =="
+
+[ -d "$PROD" ] || fail "prod bundle not found at $PROD"
+[ -z "$DEV" ] || [ -d "$DEV" ] || fail "dev bundle not found at $DEV"
+
+# ─── build.sh never notarizes, never --deep signs ───────────────────────────
+if grep -qi notarize build.sh; then fail "build.sh contains a notarize step (CI-only: scripts/release/notarize.sh)"; else pass "build.sh has no local notarize step"; fi
+if grep -E 'codesign.*--deep' build.sh | grep -vq '^ *#'; then fail "build.sh signs with --deep (forbidden: corrupts nested Sparkle XPC signatures)"; else pass "build.sh never signs with --deep"; fi
+
+# ─── Identity (ruling 13) ──────────────────────────────────────────────────
+check_identity() { # app bundle-id exe label devbuild
+    local app="$1" bid="$2" exe="$3" label="$4" devbuild="$5" info="$1/Contents/Info.plist"
+    assert_eq "$exe CFBundleIdentifier" "$bid" "$(plist "$info" CFBundleIdentifier)"
+    assert_eq "$exe CFBundleExecutable" "$exe" "$(plist "$info" CFBundleExecutable)"
+    assert_eq "$exe CFBundleDisplayName" "$exe" "$(plist "$info" CFBundleDisplayName)"
+    assert_eq "$exe MSDaemonLabel" "$label" "$(plist "$info" MSDaemonLabel)"
+    assert_eq "$exe MSDevBuild" "$devbuild" "$(plist "$info" MSDevBuild)"
+    assert_eq "$exe LSMinimumSystemVersion" "14.0" "$(plist "$info" LSMinimumSystemVersion)"
+    assert_eq "$exe LSUIElement" "true" "$(plist "$info" LSUIElement)"
+    assert_eq "$exe URL scheme" "mattstack" "$(plist "$info" 'CFBundleURLTypes:0:CFBundleURLSchemes:0')"
+    if plist "$info" LSFileQuarantineEnabled >/dev/null; then fail "$exe sets LSFileQuarantineEnabled (must be absent)"; else pass "$exe has no LSFileQuarantineEnabled"; fi
+    local short build
+    short="$(plist "$info" CFBundleShortVersionString)"; build="$(plist "$info" CFBundleVersion)"
+    if [[ "$build" =~ ^[0-9]+$ ]]; then pass "$exe CFBundleVersion is numeric ($build)"; else fail "$exe CFBundleVersion not numeric: $build"; fi
+    if [[ "$short" =~ ^([0-9]+)\.([0-9]+)\.([0-9]+)$ ]]; then
+        assert_eq "$exe CFBundleVersion = major*1e6+minor*1e3+patch" "$(( BASH_REMATCH[1]*1000000 + BASH_REMATCH[2]*1000 + BASH_REMATCH[3] ))" "$build"
+    fi
+    # Embedded rt: present, executable, identifier "rt", no rt-daemon anywhere.
+    local rt="$app/Contents/MacOS/rt"
+    [ -x "$rt" ] && pass "$exe ships Contents/MacOS/rt" || fail "$exe missing Contents/MacOS/rt"
+    assert_eq "$exe rt codesign identifier" "Identifier=rt" "$(codesign -dv "$rt" 2>&1 | grep '^Identifier=' || true)"
+    [ -z "$(find "$app" -name 'rt-daemon*' 2>/dev/null)" ] && pass "$exe has no rt-daemon artifacts" || fail "$exe still contains rt-daemon artifacts"
+    # Agent plist.
+    local agent="$app/Contents/Library/LaunchAgents/$label.plist"
+    if [ -f "$agent" ]; then
+        pass "$exe agent plist named $label.plist"
+        assert_eq "$exe agent Label" "$label" "$(plist "$agent" Label)"
+        assert_eq "$exe agent BundleProgram" "Contents/MacOS/rt" "$(plist "$agent" BundleProgram)"
+        assert_eq "$exe agent AssociatedBundleIdentifiers[0]" "$bid" "$(plist "$agent" 'AssociatedBundleIdentifiers:0')"
+        if plist "$agent" StandardOutPath >/dev/null || plist "$agent" StandardErrorPath >/dev/null; then fail "$exe agent sets Std*Path (macOS 26 \$(HOME) breakage)"; else pass "$exe agent has no Std*Path"; fi
+    else
+        fail "$exe agent plist missing at $agent"
+    fi
+    # Deck agent plist (rendered by the same script; Contents/Helpers/deck is absent until L5 — the plist ships regardless).
+    local decklabel="${label/daemon/deck}" deck="$app/Contents/Library/LaunchAgents/${label/daemon/deck}.plist"
+    if [ -f "$deck" ]; then
+        pass "$exe deck plist named $decklabel.plist"
+        assert_eq "$exe deck Label" "$decklabel" "$(plist "$deck" Label)"
+        assert_eq "$exe deck BundleProgram" "Contents/Helpers/deck" "$(plist "$deck" BundleProgram)"
+        assert_eq "$exe deck AssociatedBundleIdentifiers[0]" "$bid" "$(plist "$deck" 'AssociatedBundleIdentifiers:0')"
+    else
+        fail "$exe deck plist missing at $deck"
+    fi
+    # Both agents: KeepAlive { SuccessfulExit = false } (spec §8) and the static PATH (ruling R2 —
+    # rt/deck prepend their own Helpers dir and ~/.local/bin at process start; no /Applications in plists).
+    for a in "$agent" "$deck"; do
+        [ -f "$a" ] || continue
+        assert_eq "$exe $(basename "$a") KeepAlive:SuccessfulExit" "false" "$(plist "$a" 'KeepAlive:SuccessfulExit')"
+        assert_eq "$exe $(basename "$a") EnvironmentVariables.PATH" "/usr/bin:/bin:/usr/sbin:/sbin" "$(plist "$a" 'EnvironmentVariables:PATH')"
+        if plist "$a" EnvironmentVariables:PATH 2>/dev/null | grep -q '/Applications/'; then fail "$exe $(basename "$a") hardcodes /Applications in PATH"; fi
+    done
+}
+check_identity "$PROD" "com.mattstack.app" "mattstack" "com.mattstack.daemon" "false"
+[ -n "$DEV" ] && check_identity "$DEV" "com.mattstack.app.dev" "mattstack-dev" "com.mattstack.daemon.dev" "true"
+
+if [ -n "$DEV" ]; then
+    # Dev rt IS the shim: small Swift binary; prod rt is the compiled daemon (MB).
+    DEV_RT_SIZE=$(stat -f%z "$DEV/Contents/MacOS/rt" 2>/dev/null || echo 0)
+    [ "$DEV_RT_SIZE" -lt 1000000 ] && pass "dev rt is the shim ($DEV_RT_SIZE bytes)" || fail "dev rt is not the shim ($DEV_RT_SIZE bytes)"
+    [ -z "$(find "$PROD" -iname '*rt-daemon-shim*')" ] && pass "prod bundle has no shim artifacts" || fail "prod bundle contains shim artifacts"
+fi
+PROD_RT_SIZE=$(stat -f%z "$PROD/Contents/MacOS/rt" 2>/dev/null || echo 0)
+if [ "$PROD_RT_SIZE" -gt 1000000 ]; then pass "prod rt looks compiled ($PROD_RT_SIZE bytes)"; else echo "  ⚠ prod rt is $PROD_RT_SIZE bytes — pass RT_DAEMON_BIN=<compiled rt> for a meaningful check"; fi
+
+# ─── Signing: every Mach-O signed, hardened runtime when Developer ID, jit-only entitlements ───
+sign_flags() { codesign -dvv "$1" 2>&1 | grep -E '^(flags|Authority)=' | head -2 | tr '\n' ' '; }
+has_runtime() { codesign -dvv "$1" 2>&1 | grep -q 'flags=.*runtime'; }
+is_devid() { codesign -dvv "$1" 2>&1 | grep -q 'Authority=Developer ID Application'; }
+ent_has() { codesign -d --entitlements - --xml "$1" 2>/dev/null | grep -q "$2"; }
+check_signed() { # path label want-ent(none|jit)
+    local p="$1" label="$2" want="$3"
+    codesign --verify --strict "$p" 2>/dev/null && pass "$label signature verifies" || fail "$label signature does not verify"
+    if is_devid "$p"; then has_runtime "$p" && pass "$label has hardened runtime" || fail "$label lacks hardened runtime ($(sign_flags "$p"))"; fi
+    if ent_has "$p" 'allow-jit'; then [ "$want" = jit ] && pass "$label has allow-jit" || fail "$label unexpectedly has allow-jit"; else [ "$want" = none ] && pass "$label has no jit entitlement" || fail "$label missing allow-jit"; fi
+    ent_has "$p" 'allow-unsigned-executable-memory' && fail "$label carries allow-unsigned-executable-memory (only after the measurement task says so)" || pass "$label has no allow-unsigned-executable-memory"
+}
+for app in "$PROD" $DEV; do
+    exe="$(plist "$app/Contents/Info.plist" CFBundleExecutable)"
+    codesign --verify --deep --strict "$app" 2>/dev/null && pass "$exe bundle verifies (--deep --strict)" || fail "$exe bundle fails codesign --verify --deep --strict"
+    check_signed "$app/Contents/MacOS/rt" "$exe rt" jit
+    check_signed "$app/Contents/MacOS/$exe" "$exe tray" none
+    # Inner/outer identity must match (no nested ad-hoc inside a Developer ID bundle).
+    assert_eq "$exe inner/outer signing authority" "$(codesign -dvv "$app" 2>&1 | grep '^Authority=' | head -1)" "$(codesign -dvv "$app/Contents/MacOS/rt" 2>&1 | grep '^Authority=' | head -1)"
+done
+
+# ─── Icons ──────────────────────────────────────────────────────────────────
+[ -f "$PROD/Contents/Resources/AppIcon.icns" ] && pass "prod ships AppIcon.icns" || fail "prod missing AppIcon.icns"
+if [ -n "$DEV" ]; then
+    [ -f "$DEV/Contents/Resources/AppIcon.icns" ] && pass "dev ships AppIcon.icns" || fail "dev missing AppIcon.icns"
+    cmp -s "$PROD/Contents/Resources/AppIcon.icns" "$DEV/Contents/Resources/AppIcon.icns" && fail "prod/dev icons identical (dev tint missing)" || pass "prod/dev icons differ"
+fi
+
+# ═══ Helpers (deps.lock) — section appended by Task 4 ═══
+# ═══ Sparkle — section appended by Task 5 ═══
+
+# ─── Dev shim exit-code contract ────────────────────────────────────────────
+if [ -n "$DEV" ]; then
+    SHIM="$DEV/Contents/MacOS/rt"
+    SHIM_TMP=$(mktemp -d /tmp/mat383-shim.XXXXXX)
+    trap 'rm -rf "$SHIM_TMP"' EXIT
+    shim_case() {
+        local desc="$1" expected_code="$2" home="$3" out rc
+        out=$(env -i HOME="$home" "$SHIM" --daemon 2>&1); rc=$?
+        if [ "$rc" -ne "$expected_code" ]; then fail "$desc: expected exit $expected_code, got $rc (${out:-<empty>})"; return; fi
+        if [ "$expected_code" -eq 0 ] && [ "$(printf '%s' "$out" | grep -c 'standing down' || true)" -ne 1 ]; then fail "$desc: exit 0 but not exactly one stand-down line"; return; fi
+        pass "$desc → exit $rc"
+    }
+    H1="$SHIM_TMP/no-config"; mkdir -p "$H1/.mattstack/rt"; shim_case "shim: missing dev-mode.json" 0 "$H1"
+    H2="$SHIM_TMP/no-sourcepath"; mkdir -p "$H2/.mattstack/rt"; echo '{"bunPath":"/nope/bun"}' > "$H2/.mattstack/rt/dev-mode.json"; shim_case "shim: config without sourcePath" 0 "$H2"
+    H3="$SHIM_TMP/no-bun"; mkdir -p "$H3/.mattstack/rt"; echo "{\"sourcePath\":\"$SHIM_TMP/src\",\"bunPath\":\"$SHIM_TMP/absent-bun\"}" > "$H3/.mattstack/rt/dev-mode.json"; shim_case "shim: bun missing" 0 "$H3"
+    H4="$SHIM_TMP/no-source"; mkdir -p "$H4/.mattstack/rt"; echo "{\"sourcePath\":\"$SHIM_TMP/gone\",\"bunPath\":\"/bin/echo\"}" > "$H4/.mattstack/rt/dev-mode.json"; shim_case "shim: sourcePath gone" 0 "$H4"
+    OUT5=$(env -i "$SHIM" --daemon 2>&1); RC5=$?
+    [ "$RC5" -eq 0 ] && printf '%s' "$OUT5" | grep -q 'standing down: HOME not set' && pass "shim: HOME unset → exit 0" || fail "shim: HOME unset → got $RC5"
+    H6="$SHIM_TMP/exec-fail"; mkdir -p "$H6/.mattstack/rt" "$SHIM_TMP/realsrc/lib"
+    echo 'x' > "$SHIM_TMP/realsrc/lib/daemon.ts"; printf '#no\n' > "$SHIM_TMP/fake-bun"; chmod 644 "$SHIM_TMP/fake-bun"
+    echo "{\"sourcePath\":\"$SHIM_TMP/realsrc\",\"bunPath\":\"$SHIM_TMP/fake-bun\"}" > "$H6/.mattstack/rt/dev-mode.json"
+    env -i HOME="$H6" "$SHIM" --daemon >/dev/null 2>&1; RC6=$?
+    [ "$RC6" -ne 0 ] && grep -q 'error: execv' "$H6/.mattstack/rt/logs/daemon-stderr.log" 2>/dev/null && pass "shim: genuine execv failure → exit $RC6" || fail "shim: execv failure should exit nonzero with an error line (got $RC6)"
+fi
+
+# ─── Swift source gates that survive the rename ─────────────────────────────
+if ! $INSTALLED_ONLY; then
+    grep_src() { grep -R --include='*.swift' -q "$1" Sources Sources-daemon-shim; }
+    grep_src 'forInfoDictionaryKey: "MSDaemonLabel"' && pass "BundleFlavor reads MSDaemonLabel" || fail "BundleFlavor does not read MSDaemonLabel"
+    grep_src 'defaultDaemonLabel = "com.mattstack.daemon"' && pass "BundleFlavor falls back to com.mattstack.daemon" || fail "BundleFlavor fallback label wrong"
+    grep_src 'Contents/MacOS/rt-daemon' && fail "Swift still references Contents/MacOS/rt-daemon" || pass "no Swift reference to Contents/MacOS/rt-daemon"
+    grep_src 'path == "/flavor/retire"' && pass "/flavor/retire endpoint present" || fail "/flavor/retire endpoint missing"
+    GUARD_LINE=$(grep -n 'TrayServer.exitIfAnotherTrayOwnsSocket()' Sources/main.swift | head -1 | cut -d: -f1)
+    DELEGATE_LINE=$(grep -n 'AppDelegate()' Sources/main.swift | head -1 | cut -d: -f1)
+    [ -n "$GUARD_LINE" ] && [ -n "$DELEGATE_LINE" ] && [ "$GUARD_LINE" -lt "$DELEGATE_LINE" ] && pass "socket guard precedes AppDelegate" || fail "socket guard does not precede AppDelegate"
+    # Sparkle gating (L3 T10 replaces UpdateChecker with UpdaterController + UpdatePolicy).
+    if grep -q 'UpdatePolicy.shouldStartUpdater(isDevBuild: isDevBuild' Sources/Updates/UpdaterController.swift 2>/dev/null; then
+        pass "UpdaterController gates Sparkle on the dev flavor"
+    else
+        fail "UpdaterController does not gate Sparkle on BundleFlavor.isDevBuild"
+    fi
+    TRAY_STRINGS=$(mktemp /tmp/mat383-strings.XXXXXX)
+    strings "$PROD/Contents/MacOS/$(plist "$PROD/Contents/Info.plist" CFBundleExecutable)" > "$TRAY_STRINGS" 2>/dev/null
+    assert_bin_has() { # desc needle
+        if grep -qF "$2" "$TRAY_STRINGS"; then pass "built tray binary contains: $2"; else fail "built tray binary is missing: $2 ($1)"; fi
+    }
+    assert_bin_has "silent dev updater" "update check skipped (dev build)"
+    rm -f "$TRAY_STRINGS"
+fi
+
+echo ""
+echo "  $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ]
+```
+
+- [ ] **Step 6: Run everything**
+
+Run: `bun test && bunx tsc --noEmit && bash -n rt-tray/build.sh rt-tray/check-bundle.sh && (bun build --compile ./cli.ts --outfile dist/rt && cd rt-tray && RT_DAEMON_BIN=../dist/rt ./check-bundle.sh)`
+Expected: bun tests green (handoff test now fakes `Contents/MacOS/rt`); check-bundle `0 failed` once L3 T1/T2/T10/T18 have merged (ad-hoc signatures: the Developer-ID-only assertions are skipped by `is_devid`). Before L3 merges, the template/Swift assertions fail by design — that is the dependency signal; do not patch them out.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add rt-tray/build.sh rt-tray/check-bundle.sh commands/settings.ts lib/__tests__/dev-mode-handoff.test.ts scripts/entitlements.plist
+git commit -m "MAT-383: identity freeze — rt side reads Contents/MacOS/rt, numeric build, jit-only entitlements, check-bundle asserts the contract
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 4: `rt-tray/build.sh` rewrite — Helpers, Resources, Sparkle keys, inside-out signing, xcodebuild-or-swift-build
+
+**AFTER L3 T1 + T2 + T10 merge.** This rewrite deletes L3 T10's fenced build.sh stopgap and depends on L3's `Package.swift` (Sparkle), `Info.plist`/`LaunchAgent.plist`/`LaunchAgent-deck.plist` templates, `project.yml`, and `rt-tray/scripts/render-launchagents.sh` (cross-plan review §1 rows 12–17).
+
+**Files:**
+- Rewrite: `rt-tray/build.sh`
+- Modify: `rt-tray/check-bundle.sh` (append the Helpers section at the `Task 4` marker)
+
+**Interfaces:**
+- Consumes: `rt-tray/deps.lock` via `bun scripts/lib/deps-lock.ts` (Task 2); `rt-tray/deps/arm64/<name>` (Task 2); `numeric_build` + identity vars (Task 3); `scripts/entitlements.plist` (jit-only); L3 T2's `rt-tray/scripts/render-launchagents.sh <prod|dev> <outdir>` (renders **both** agent plists — daemon + deck — with `KeepAlive {SuccessfulExit:false}` and the static `EnvironmentVariables.PATH`); L3 T2's `Info.plist` template (already declares `LSMinimumSystemVersion`, `CFBundleURLTypes` with `CFBundleURLName @@BUNDLE_ID@@.join`, and the `SU*` keys with placeholder values — build.sh overwrites them with `Set`, never `Add`).
+- Environment contract (used by Task 8's workflow): `RT_DAEMON_BIN` (compiled rt; required in release mode unless `dist/rt` exists), `RT_VSIX` (path to the `.vsix`; optional), `RT_VERSION` (e.g. `v2.8.0`; default `git describe`), `RT_REQUIRE_DEPS=1` (missing `rt-tray/deps/arm64` is fatal; CI sets it), `SPARKLE_PUBLIC_ED_KEY` (overrides `rt-tray/SUPublicEDKey`), `RT_BUILD_TOOL=swift|xcode` (default: `xcode` when `xcodebuild -version` succeeds AND `rt-tray/project.yml` exists, else `swift`).
+- Produces: `rt-tray/mattstack.app` / `rt-tray/mattstack-dev.app` matching the layout contract; functions `assemble_common`, `sign_bundle`, `embed_sparkle`, `bundle_helpers` (all internal to build.sh).
+
+- [ ] **Step 1: Write the new build.sh**
+
+```bash
+#!/bin/bash
+set -euo pipefail
+
+# ─── mattstack.app build ─────────────────────────────────────────────────────
+# Usage:
+#   ./build.sh            debug: swift build only, no bundle
+#   ./build.sh release    mattstack.app (prod)
+#   ./build.sh dev        mattstack-dev.app (dev; Contents/MacOS/rt is the source-runner shim)
+#   ./build.sh install    release + copy to /Applications + launch
+#
+# Env: RT_DAEMON_BIN RT_VSIX RT_VERSION RT_REQUIRE_DEPS SPARKLE_PUBLIC_ED_KEY RT_BUILD_TOOL
+#
+# The bundle id, daemon label, and display name live ONLY here; Info.plist is a
+# sed template and the LaunchAgent plists come from scripts/render-launchagents.sh.
+# The tray binary comes from xcodebuild (when Xcode + project.yml exist) or
+# swift build; both feed the SAME assemble + sign path, so the bundle contract
+# (check-bundle.sh) is identical.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+cd "$SCRIPT_DIR"
+
+MODE="${1:-debug}"
+PRODUCT_NAME="rt-tray"
+
+case "$MODE" in
+    debug)            IS_DEV=false; BUILD_CONFIG="debug" ;;
+    dev)              IS_DEV=true;  BUILD_CONFIG="release" ;;
+    release|install)  IS_DEV=false; BUILD_CONFIG="release" ;;
+    *) echo "  ✗ Unknown mode: $MODE (expected debug|release|dev|install)" >&2; exit 1 ;;
+esac
+
+if [ "$IS_DEV" = true ]; then
+    APP_NAME="mattstack-dev"; DISPLAY_NAME="mattstack-dev"
+    BUNDLE_ID="com.mattstack.app.dev"; DAEMON_LABEL="com.mattstack.daemon.dev"
+    SCHEME="mattstack-dev"
+else
+    APP_NAME="mattstack"; DISPLAY_NAME="mattstack"
+    BUNDLE_ID="com.mattstack.app"; DAEMON_LABEL="com.mattstack.daemon"
+    SCHEME="mattstack"
+fi
+
+APP_BUNDLE="$SCRIPT_DIR/$APP_NAME.app"
+CONTENTS="$APP_BUNDLE/Contents"
+DEPS_DIR="$SCRIPT_DIR/deps/arm64"
+SU_FEED_URL="https://github.com/m4ttstack/rt/releases/latest/download/appcast.xml"
+ENTITLEMENTS_JIT="$REPO_DIR/scripts/entitlements.plist"
+
+numeric_build() {
+    local v="${1#v}"
+    if [[ "$v" =~ ^([0-9]+)\.([0-9]+)\.([0-9]+) ]]; then
+        echo $(( BASH_REMATCH[1] * 1000000 + BASH_REMATCH[2] * 1000 + BASH_REMATCH[3] ))
+    else
+        echo 0
+    fi
+}
+
+# ─── Which compiler ──────────────────────────────────────────────────────────
+if [ -z "${RT_BUILD_TOOL:-}" ]; then
+    if xcodebuild -version >/dev/null 2>&1 && [ -f "$SCRIPT_DIR/project.yml" ]; then RT_BUILD_TOOL=xcode; else RT_BUILD_TOOL=swift; fi
+fi
+echo "  Building $APP_NAME ($MODE) with $RT_BUILD_TOOL..."
+
+XCODE_APP=""
+if [ "$RT_BUILD_TOOL" = xcode ]; then
+    command -v xcodegen >/dev/null || { echo "  ✗ xcodegen not found (brew install xcodegen)"; exit 1; }
+    xcodegen generate --spec "$SCRIPT_DIR/project.yml" --project "$SCRIPT_DIR" >/dev/null
+    DERIVED="$SCRIPT_DIR/.build-xcode"
+    xcodebuild -project "$SCRIPT_DIR/mattstack.xcodeproj" -scheme "$SCHEME" -configuration Release \
+        -derivedDataPath "$DERIVED" -destination 'platform=macOS,arch=arm64' \
+        CODE_SIGNING_ALLOWED=NO CODE_SIGNING_REQUIRED=NO build 2>&1 | sed 's/^/  /'
+    XCODE_APP="$DERIVED/Build/Products/Release/$APP_NAME.app"
+    [ -d "$XCODE_APP" ] || { echo "  ✗ xcodebuild produced no $XCODE_APP"; exit 1; }
+    BINARY="$XCODE_APP/Contents/MacOS/$APP_NAME"
+    if [ "$IS_DEV" = true ]; then
+        swift build -c release --product rt-daemon-shim 2>&1 | sed 's/^/  /'
+        SHIM_BINARY="$SCRIPT_DIR/.build/release/rt-daemon-shim"
+    fi
+else
+    if [ "$BUILD_CONFIG" = "debug" ]; then
+        swift build 2>&1 | sed 's/^/  /'
+        BINARY="$SCRIPT_DIR/.build/debug/$PRODUCT_NAME"
+    elif [ "$IS_DEV" = true ]; then
+        swift build -c release 2>&1 | sed 's/^/  /'
+        BINARY="$SCRIPT_DIR/.build/release/$PRODUCT_NAME"
+        SHIM_BINARY="$SCRIPT_DIR/.build/release/rt-daemon-shim"
+    else
+        swift build -c release --product "$PRODUCT_NAME" 2>&1 | sed 's/^/  /'
+        BINARY="$SCRIPT_DIR/.build/release/$PRODUCT_NAME"
+    fi
+fi
+[ -f "$BINARY" ] || { echo "  ✗ Build failed — binary not found at $BINARY"; exit 1; }
+echo "  ✓ Build succeeded"
+
+if [ "$BUILD_CONFIG" = "debug" ]; then
+    echo "  Skipping .app bundle assembly for debug build."
+    echo "  Run: $BINARY"
+    exit 0
+fi
+
+# ─── Assemble ────────────────────────────────────────────────────────────────
+echo "  Assembling $APP_NAME.app..."
+rm -rf "$APP_BUNDLE"
+if [ -n "$XCODE_APP" ]; then
+    ditto "$XCODE_APP" "$APP_BUNDLE"
+    find "$APP_BUNDLE" -name '_CodeSignature' -prune -exec rm -rf {} + 2>/dev/null || true
+else
+    mkdir -p "$CONTENTS/MacOS"
+    cp "$BINARY" "$CONTENTS/MacOS/$APP_NAME"
+fi
+mkdir -p "$CONTENTS/Resources" "$CONTENTS/Helpers" "$CONTENTS/Frameworks" "$CONTENTS/Library/LaunchAgents"
+
+# Icons (make-icon.swift emits both flavors; bundle-internal name is always AppIcon.icns).
+if [ ! -f "$SCRIPT_DIR/AppIcon.icns" ] || [ ! -f "$SCRIPT_DIR/AppIcon-dev.icns" ]; then
+    echo "  Generating AppIcon.icns + AppIcon-dev.icns..."; swift "$SCRIPT_DIR/make-icon.swift"
+fi
+ICON_SRC="$SCRIPT_DIR/AppIcon.icns"; [ "$IS_DEV" = true ] && ICON_SRC="$SCRIPT_DIR/AppIcon-dev.icns"
+[ -f "$ICON_SRC" ] && cp "$ICON_SRC" "$CONTENTS/Resources/AppIcon.icns" && echo "  ✓ $(basename "$ICON_SRC") → AppIcon.icns"
+
+# Notification sounds (UNNotificationSound needs caf inside Resources).
+if [ -d "$REPO_DIR/sounds" ]; then
+    for mp3 in "$REPO_DIR"/sounds/*.mp3; do
+        [ -f "$mp3" ] || continue
+        afconvert -d LEI16@44100 -f caff "$mp3" "$CONTENTS/Resources/$(basename "$mp3" .mp3).caf" 2>/dev/null && echo "  ✓ $(basename "$mp3" .mp3).caf"
+    done
+fi
+[ -f "$SCRIPT_DIR/mission-control-screenshot.png" ] && cp "$SCRIPT_DIR/mission-control-screenshot.png" "$CONTENTS/Resources/" && xattr -cr "$CONTENTS/Resources/mission-control-screenshot.png" 2>/dev/null || true
+
+# ─── Embed rt (Contents/MacOS/rt) ────────────────────────────────────────────
+# Prod: the compiled rt. Dev: the shim, permanently (the dev flavor runs the
+# daemon from source). A script is never a valid prod daemon.
+if [ "$IS_DEV" = true ]; then
+    [ -f "$SHIM_BINARY" ] || { echo "  ✗ rt-daemon-shim not built"; exit 1; }
+    cp "$SHIM_BINARY" "$CONTENTS/MacOS/rt"; chmod +x "$CONTENTS/MacOS/rt"
+    echo "  ✓ Embedded the source-runner shim as Contents/MacOS/rt"
+else
+    DAEMON_SRC="${RT_DAEMON_BIN:-}"
+    [ -z "$DAEMON_SRC" ] && [ -f "$REPO_DIR/dist/rt" ] && DAEMON_SRC="$REPO_DIR/dist/rt"
+    [ -z "$DAEMON_SRC" ] && DAEMON_SRC="$(command -v rt 2>/dev/null || true)"
+    if [ -n "$DAEMON_SRC" ] && [ -f "$DAEMON_SRC" ] && ! file -b "$DAEMON_SRC" | grep -q "Mach-O"; then
+        echo "  ✗ $DAEMON_SRC is not a compiled binary (dev-mode wrapper?) — bun run build, or set RT_DAEMON_BIN"; exit 1
+    fi
+    if [ -n "$DAEMON_SRC" ] && [ -f "$DAEMON_SRC" ]; then
+        cp "$DAEMON_SRC" "$CONTENTS/MacOS/rt"; chmod +x "$CONTENTS/MacOS/rt"
+        echo "  ✓ Embedded rt from $DAEMON_SRC"
+    else
+        echo "  ⚠ rt binary not found — Contents/MacOS/rt will be missing (set RT_DAEMON_BIN)"
+    fi
+fi
+
+# ─── Helpers from deps.lock ──────────────────────────────────────────────────
+HELPER_ENTITLEMENTS=()   # "path<TAB>jit|none" for the signing pass
+bundle_helpers() {
+    if [ ! -d "$DEPS_DIR" ]; then
+        if [ "${RT_REQUIRE_DEPS:-0}" = 1 ]; then echo "  ✗ $DEPS_DIR missing — run scripts/fetch-deps.sh arm64"; exit 1; fi
+        echo "  ⚠ $DEPS_DIR missing — Helpers skipped (scripts/fetch-deps.sh arm64 to bundle them)"
+        return
+    fi
+    while IFS=$'\t' read -r name version url sha archive extract bundlePath ent status kind expose; do
+        [ "$kind" = helper ] || continue
+        if [ "$status" != bundled ]; then echo "  · $name: pending, not in this build"; continue; fi
+        src="$DEPS_DIR/$name"
+        [ -e "$src" ] || { echo "  ✗ $name not fetched at $src — run scripts/fetch-deps.sh arm64"; exit 1; }
+        dest="$APP_BUNDLE/$bundlePath"
+        rm -rf "$dest"; mkdir -p "$(dirname "$dest")"
+        cp -R "$src" "$dest"
+        xattr -cr "$dest" 2>/dev/null || true
+        HELPER_ENTITLEMENTS+=("$dest	$ent")
+        echo "  ✓ Helpers/$name $version"
+    done < <(bun "$REPO_DIR/scripts/lib/deps-lock.ts")
+    cp "$SCRIPT_DIR/deps.lock" "$CONTENTS/Resources/deps.lock"
+}
+bundle_helpers
+
+# ─── Extension ───────────────────────────────────────────────────────────────
+if [ -n "${RT_VSIX:-}" ]; then
+    [ -f "$RT_VSIX" ] || { echo "  ✗ RT_VSIX=$RT_VSIX not found"; exit 1; }
+    cp "$RT_VSIX" "$CONTENTS/Resources/rt-context.vsix" && echo "  ✓ rt-context.vsix"
+fi
+
+# ─── Sparkle framework (swift-build path copies the SPM artifact; xcodebuild embeds it itself) ───
+embed_sparkle() {
+    [ -d "$CONTENTS/Frameworks/Sparkle.framework" ] && { echo "  ✓ Sparkle.framework (embedded by xcodebuild)"; return; }
+    local fw
+    fw="$(find "$SCRIPT_DIR/.build/artifacts" -type d -name 'Sparkle.framework' -path '*macos-arm64*' 2>/dev/null | head -1)"
+    if [ -z "$fw" ]; then echo "  ⚠ Sparkle.framework not in .build/artifacts — Package.swift has no Sparkle dependency yet; updater disabled in this build"; return; fi
+    ditto "$fw" "$CONTENTS/Frameworks/Sparkle.framework"
+    echo "  ✓ Sparkle.framework → Contents/Frameworks"
+}
+embed_sparkle
+
+# ─── LaunchAgent plists (daemon + deck; rendered by the template script) ─────
+# Both plists carry KeepAlive {SuccessfulExit:false} and the static PATH
+# /usr/bin:/bin:/usr/sbin:/sbin — rt and deck prepend their own bundle's
+# Contents/Helpers and $HOME/.local/bin at process start, so no install
+# location is ever baked into a plist.
+mkdir -p "$CONTENTS/Library/LaunchAgents"
+"$SCRIPT_DIR/scripts/render-launchagents.sh" "$([ "$IS_DEV" = true ] && echo dev || echo prod)" "$CONTENTS/Library/LaunchAgents"
+echo "  ✓ LaunchAgent plists ($DAEMON_LABEL.plist, ${DAEMON_LABEL/daemon/deck}.plist)"
+
+# ─── Info.plist: identity (template) + version + Sparkle keys ─────────────────
+INFO="$CONTENTS/Info.plist"
+sed -e "s/@@APP_NAME@@/$APP_NAME/g" -e "s/@@BUNDLE_ID@@/$BUNDLE_ID/g" \
+    -e "s/@@DISPLAY_NAME@@/$DISPLAY_NAME/g" -e "s/@@DAEMON_LABEL@@/$DAEMON_LABEL/g" \
+    "$SCRIPT_DIR/Info.plist" > "$INFO"
+# The template already declares LSMinimumSystemVersion, CFBundleURLTypes and the
+# SU* keys; PlistBuddy "Add" fails on an existing key, so every write below goes
+# through plist_set (Set, creating the key only when the template lacks it).
+plist_set() { # key type value
+    /usr/libexec/PlistBuddy -c "Set :$1 $3" "$INFO" 2>/dev/null || /usr/libexec/PlistBuddy -c "Add :$1 $2 $3" "$INFO"
+}
+plist_set MSDevBuild bool "$IS_DEV"
+plist_set LSMinimumSystemVersion string 14.0
+
+RT_VERSION="${RT_VERSION:-$(cd "$REPO_DIR" && git describe --tags --abbrev=0 2>/dev/null || echo dev)}"
+RT_VERSION="${RT_VERSION#v}"
+if [ "$RT_VERSION" != "dev" ]; then
+    /usr/libexec/PlistBuddy -c "Set :CFBundleShortVersionString $RT_VERSION" "$INFO"
+    /usr/libexec/PlistBuddy -c "Set :CFBundleVersion $(numeric_build "$RT_VERSION")" "$INFO"
+    echo "  ✓ Version $RT_VERSION (build $(numeric_build "$RT_VERSION"))"
+fi
+
+PUBLIC_KEY="${SPARKLE_PUBLIC_ED_KEY:-}"
+[ -z "$PUBLIC_KEY" ] && [ -f "$SCRIPT_DIR/SUPublicEDKey" ] && PUBLIC_KEY="$(tr -d '[:space:]' < "$SCRIPT_DIR/SUPublicEDKey")"
+if [ "$IS_DEV" = true ]; then
+    plist_set SUEnableAutomaticChecks bool false
+else
+    plist_set SUFeedURL string "$SU_FEED_URL"
+    plist_set SUEnableAutomaticChecks bool true
+    plist_set SUScheduledCheckInterval integer 21600
+    plist_set SUAutomaticallyUpdate bool true
+    plist_set SUVerifyUpdateBeforeExtraction bool true
+fi
+if [ -n "$PUBLIC_KEY" ]; then
+    plist_set SUPublicEDKey string "$PUBLIC_KEY"
+    echo "  ✓ SUPublicEDKey set"
+else
+    echo "  ⚠ no Sparkle public key (rt-tray/SUPublicEDKey or SPARKLE_PUBLIC_ED_KEY) — updates cannot be verified by this build"
+fi
+echo -n "APPL????" > "$CONTENTS/PkgInfo"
+echo "  ✓ App bundle assembled at $APP_BUNDLE"
+
+# ─── Sign, inside-out ────────────────────────────────────────────────────────
+# Order: Sparkle XPCs → Autoupdate → Updater.app → Sparkle.framework →
+# Helpers → Contents/MacOS/rt → outer app. Never --deep (it rewrites the
+# Sparkle XPC signatures and breaks updates while notarization still passes).
+SIGNING_IDENTITY=""
+if security find-identity -v -p codesigning 2>/dev/null | grep -q "Developer ID Application"; then
+    SIGNING_IDENTITY=$(security find-identity -v -p codesigning 2>/dev/null | grep "Developer ID Application" | head -1 | awk -F'"' '{print $2}')
+    echo "  Signing with: $SIGNING_IDENTITY"
+    SIGN_FLAGS=(--force --sign "$SIGNING_IDENTITY" --options runtime --timestamp)
+else
+    echo "  No Developer ID found — ad-hoc signing"
+    SIGN_FLAGS=(--force --sign -)
+fi
+sign() { codesign "${SIGN_FLAGS[@]}" "$@"; }
+
+SPARKLE_FW="$CONTENTS/Frameworks/Sparkle.framework"
+if [ -d "$SPARKLE_FW" ]; then
+    V="$SPARKLE_FW/Versions/B"
+    sign "$V/XPCServices/Installer.xpc"
+    sign --preserve-metadata=entitlements "$V/XPCServices/Downloader.xpc"
+    sign "$V/Autoupdate"
+    sign "$V/Updater.app"
+    sign "$SPARKLE_FW"
+    echo "  ✓ Signed Sparkle.framework (inside-out)"
+fi
+
+sign_helper_tree() { # root ent — signs every Mach-O under root (files or a dir like node/)
+    local root="$1" ent="$2" f
+    while IFS= read -r -d '' f; do
+        if file -b "$f" | grep -q "Mach-O"; then
+            if [ "$ent" = jit ]; then sign -i "com.mattstack.helper.$(basename "$f")" --entitlements "$ENTITLEMENTS_JIT" "$f"
+            else sign -i "com.mattstack.helper.$(basename "$f")" "$f"; fi
+        fi
+    done < <(find "$root" -type f -print0)
+}
+for entry in "${HELPER_ENTITLEMENTS[@]+"${HELPER_ENTITLEMENTS[@]}"}"; do
+    path="${entry%%	*}"; ent="${entry##*	}"
+    sign_helper_tree "$path" "$ent"
+    echo "  ✓ Signed Helpers/$(basename "$path") ($ent)"
+done
+
+if [ -f "$CONTENTS/MacOS/rt" ]; then
+    sign -i rt --entitlements "$ENTITLEMENTS_JIT" "$CONTENTS/MacOS/rt"
+    echo "  ✓ Signed Contents/MacOS/rt (identifier rt, jit)"
+fi
+
+sign --entitlements /dev/stdin <<EOF "$APP_BUNDLE"
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>com.apple.security.app-sandbox</key>
+    <false/>
+</dict>
+</plist>
+EOF
+echo "  ✓ Signed app bundle"
+codesign --verify --deep --strict "$APP_BUNDLE" 2>/dev/null && echo "  ✓ Signature verified (--deep --strict)" || { echo "  ✗ Signature verification failed"; exit 1; }
+
+# ─── Install ─────────────────────────────────────────────────────────────────
+if [ "$MODE" = "install" ]; then
+    INSTALL_DIR="/Applications"
+    if pkill -f "$APP_NAME.app/Contents/MacOS/$APP_NAME" 2>/dev/null; then
+        for _ in $(seq 1 20); do pgrep -f "$APP_NAME.app/Contents/MacOS/$APP_NAME" >/dev/null 2>&1 || break; sleep 0.1; done
+    fi
+    rm -rf "$INSTALL_DIR/$APP_NAME.app"
+    ditto "$APP_BUNDLE" "$INSTALL_DIR/$APP_NAME.app"
+    echo "  ✓ Installed to $INSTALL_DIR/$APP_NAME.app"
+    open "$INSTALL_DIR/$APP_NAME.app"
+fi
+echo ""
+echo "  Done."
+```
+
+Notes for the implementer: `sign` wraps `codesign` so the Developer-ID flags are never duplicated; `HELPER_ENTITLEMENTS` uses a literal TAB as separator; the `${arr[@]+"${arr[@]}"}` form keeps `set -u` happy on bash 3.2 when no helpers were bundled; the agent plists are L3's (`render-launchagents.sh` renders daemon + deck from `LaunchAgent.plist`/`LaunchAgent-deck.plist`, KeepAlive `{SuccessfulExit:false}` in both flavors) and their `EnvironmentVariables.PATH` is the static `/usr/bin:/bin:/usr/sbin:/sbin` (ruling R2 — rt's daemon boot and deck prepend `<bundleRoot>/Contents/Helpers` and `$HOME/.local/bin` themselves; build.sh never writes a PATH); `plist_set` exists because L3's Info.plist template already declares the `LSMinimumSystemVersion`/`CFBundleURLTypes`/`SU*` keys and PlistBuddy `Add` fails on an existing key. `CFBundleURLName` stays the template's `@@BUNDLE_ID@@.join` (L4's earlier `.url` is withdrawn).
+
+- [ ] **Step 2: Append the Helpers section to check-bundle.sh** (replace the `# ═══ Helpers (deps.lock) — section appended by Task 4 ═══` line)
+
+```bash
+# ═══ Helpers (deps.lock) ═══
+LOCK_TSV="$(bun "$SCRIPT_DIR/../scripts/lib/deps-lock.ts" --kind helper)"
+check_helpers() { # app
+    local app="$1" exe; exe="$(plist "$app/Contents/Info.plist" CFBundleExecutable)"
+    if [ ! -d "$SCRIPT_DIR/deps/arm64" ] && ! $INSTALLED_ONLY; then echo "  ⚠ $exe: rt-tray/deps/arm64 absent — Helpers assertions skipped (scripts/fetch-deps.sh arm64)"; return; fi
+    cmp -s "$SCRIPT_DIR/deps.lock" "$app/Contents/Resources/deps.lock" && pass "$exe Resources/deps.lock matches rt-tray/deps.lock" || fail "$exe Resources/deps.lock missing or stale"
+    while IFS=$'\t' read -r name version url sha archive extract bundlePath ent status kind expose; do
+        local p="$app/$bundlePath"
+        if [ "$status" = pending ]; then
+            [ -e "$p" ] && fail "$exe ships $name although deps.lock says pending" || pass "$exe: $name absent (pending until L5)"
+            continue
+        fi
+        [ -e "$p" ] || { fail "$exe missing Helpers/$name at $bundlePath"; continue; }
+        pass "$exe ships Helpers/$name"
+        while IFS= read -r -d '' f; do
+            file -b "$f" | grep -q "Mach-O" || continue
+            check_signed "$f" "$exe Helpers/$name/$(basename "$f")" "$ent"
+            assert_eq "$exe $name identifier" "Identifier=com.mattstack.helper.$(basename "$f")" "$(codesign -dv "$f" 2>&1 | grep '^Identifier=' || true)"
+        done < <(find "$p" -type f -print0)
+        [ -z "$(find "$p" -name '.*' -maxdepth 1 2>/dev/null | grep -v '/\.$' )" ] || true
+    done <<< "$LOCK_TSV"
+    # Every bundled helper answers --version from inside the bundle (signed, entitled).
+    [ -x "$app/Contents/Helpers/fzf" ] && "$app/Contents/Helpers/fzf" --version >/dev/null 2>&1 && pass "$exe Helpers/fzf runs" || fail "$exe Helpers/fzf does not run"
+    [ -x "$app/Contents/Helpers/jq" ] && "$app/Contents/Helpers/jq" --version >/dev/null 2>&1 && pass "$exe Helpers/jq runs" || fail "$exe Helpers/jq does not run"
+    [ -x "$app/Contents/Helpers/bun" ] && "$app/Contents/Helpers/bun" --version >/dev/null 2>&1 && pass "$exe Helpers/bun runs (jit entitlement sufficient)" || fail "$exe Helpers/bun does not run under its entitlements"
+    [ -x "$app/Contents/Helpers/node/bin/node" ] && "$app/Contents/Helpers/node/bin/node" -e 'process.exit(0)' >/dev/null 2>&1 && pass "$exe Helpers/node runs" || fail "$exe Helpers/node does not run under its entitlements"
+    [ -f "$app/Contents/Helpers/fast-browser/bin/fast-browser.mjs" ] && pass "$exe Helpers/fast-browser package present" || fail "$exe Helpers/fast-browser package missing"
+}
+check_helpers "$PROD"
+[ -n "$DEV" ] && check_helpers "$DEV"
+# Agent PATH is the static system set (asserted per plist in check_identity); services never
+# capture a shell PATH and never bake in an install location — rt/deck prepend their own Helpers dir.
+```
+
+- [ ] **Step 3: Run**
+
+Run: `bash -n rt-tray/build.sh rt-tray/check-bundle.sh && scripts/fetch-deps.sh arm64 && bun build --compile ./cli.ts --outfile dist/rt && cd rt-tray && RT_DAEMON_BIN=../dist/rt ./check-bundle.sh`
+Expected: `0 failed`; `ls rt-tray/mattstack.app/Contents/Helpers` shows `bun fast-browser fzf gh glab jq node`; `ls rt-tray/mattstack.app/Contents/Library/LaunchAgents` shows `com.mattstack.daemon.plist com.mattstack.deck.plist`; `du -sh rt-tray/mattstack.app` (expect roughly 300–400 MB — record the number in the commit body).
+Also: `RT_REQUIRE_DEPS=1 rt-tray/build.sh release` with `rt-tray/deps` moved aside exits 1 with the fetch hint (then move it back).
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add rt-tray/build.sh rt-tray/check-bundle.sh
+git commit -m "MAT-383: build.sh — Helpers from deps.lock, Resources, rendered agent plists, Sparkle keys, inside-out signing, xcodebuild-or-swift-build
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 5: Sparkle framework — embed, rpath check, signing assertions
+
+**AFTER L3 T10 merges** (L3 T10 adds the Sparkle SPM dependency, rpath, and `Package.resolved`; cross-plan review §1 row 12). "Skip if L3 has already added" is now "requires".
+
+**Files:**
+- ~~Modify: `rt-tray/Package.swift` + `rt-tray/Package.resolved`~~ — Dropped — owned by L3 T10 (cross-plan review).
+- Modify: `rt-tray/check-bundle.sh` (replace the `# ═══ Sparkle — section appended by Task 5 ═══` marker)
+
+**Interfaces:**
+- Consumes: `embed_sparkle` + the Sparkle signing block in build.sh (Task 4).
+- Produces: `Contents/Frameworks/Sparkle.framework` in both flavors, signed inside-out; tray binary carries `@rpath/Sparkle.framework/Versions/B/Sparkle` + an `@executable_path/../Frameworks` rpath.
+
+- [ ] **Step 1: Package.swift**
+
+Dropped — owned by L3 T10 (cross-plan review): L3's `Package.swift` declares `.package(url: "https://github.com/sparkle-project/Sparkle", from: "2.9.6")`, the `Sparkle` product dependency, and the `@executable_path/../Frameworks` rpath; `project.yml` carries the same package for the xcodebuild path. Verify before Step 2 that `rt-tray/Package.swift` names `2.9.6` or newer and `rt-tray/Package.resolved` is committed; do not edit either here — report a mismatch to L3 instead.
+
+- [ ] **Step 2: Build + inspect**
+
+Run: `cd rt-tray && swift package resolve && ./build.sh release && otool -L mattstack.app/Contents/MacOS/mattstack | grep Sparkle && otool -l mattstack.app/Contents/MacOS/mattstack | grep -A2 LC_RPATH | grep Frameworks && ls mattstack.app/Contents/Frameworks/Sparkle.framework/Versions/B/XPCServices`
+Expected: `@rpath/Sparkle.framework/Versions/B/Sparkle`, an rpath `@executable_path/../Frameworks`, and `Downloader.xpc Installer.xpc`. `open mattstack.app` launches (menu-bar "m" appears) — the app links Sparkle even before L3 wires `SPUStandardUpdaterController`.
+
+- [ ] **Step 3: check-bundle Sparkle section**
+
+```bash
+# ═══ Sparkle ═══
+check_sparkle() { # app
+    local app="$1" exe fw; exe="$(plist "$app/Contents/Info.plist" CFBundleExecutable)"; fw="$app/Contents/Frameworks/Sparkle.framework"
+    [ -d "$fw" ] || { fail "$exe missing Contents/Frameworks/Sparkle.framework"; return; }
+    pass "$exe ships Sparkle.framework"
+    otool -L "$app/Contents/MacOS/$exe" | grep -q '@rpath/Sparkle.framework' && pass "$exe tray links Sparkle via @rpath" || fail "$exe tray does not link Sparkle"
+    otool -l "$app/Contents/MacOS/$exe" | grep -A2 LC_RPATH | grep -q '@executable_path/../Frameworks' && pass "$exe tray has the Frameworks rpath" || fail "$exe tray lacks the @executable_path/../Frameworks rpath"
+    codesign --verify --deep --strict "$fw" 2>/dev/null && pass "$exe Sparkle.framework verifies (inside-out signed)" || fail "$exe Sparkle.framework signature broken"
+    for xpc in Installer Downloader; do
+        codesign --verify --strict "$fw/Versions/B/XPCServices/$xpc.xpc" 2>/dev/null && pass "$exe $xpc.xpc verifies" || fail "$exe $xpc.xpc signature broken"
+    done
+    assert_eq "$exe Sparkle signing authority matches app" "$(codesign -dvv "$app" 2>&1 | grep '^Authority=' | head -1)" "$(codesign -dvv "$fw" 2>&1 | grep '^Authority=' | head -1)"
+    # Plist keys.
+    local info="$app/Contents/Info.plist"
+    if [ "$(plist "$info" MSDevBuild)" = "true" ]; then
+        assert_eq "$exe SUEnableAutomaticChecks (dev)" "false" "$(plist "$info" SUEnableAutomaticChecks)"
+    else
+        assert_eq "$exe SUFeedURL" "https://github.com/m4ttstack/rt/releases/latest/download/appcast.xml" "$(plist "$info" SUFeedURL)"
+        assert_eq "$exe SUEnableAutomaticChecks" "true" "$(plist "$info" SUEnableAutomaticChecks)"
+        assert_eq "$exe SUScheduledCheckInterval" "21600" "$(plist "$info" SUScheduledCheckInterval)"
+        assert_eq "$exe SUAutomaticallyUpdate" "true" "$(plist "$info" SUAutomaticallyUpdate)"
+        assert_eq "$exe SUVerifyUpdateBeforeExtraction" "true" "$(plist "$info" SUVerifyUpdateBeforeExtraction)"
+    fi
+    for k in SUEnableInstallerLauncherService SUEnableDownloaderService SUEnableInstallerConnectionService SUEnableInstallerStatusService; do
+        plist "$info" "$k" >/dev/null && fail "$exe sets $k (sandbox-only, must be absent)"
+    done
+    if [ -n "${SPARKLE_PUBLIC_ED_KEY:-}" ]; then
+        assert_eq "$exe SUPublicEDKey (env override)" "$SPARKLE_PUBLIC_ED_KEY" "$(plist "$info" SUPublicEDKey)"
+    elif [ -f "$SCRIPT_DIR/SUPublicEDKey" ]; then
+        assert_eq "$exe SUPublicEDKey (committed file)" "$(tr -d '[:space:]' < "$SCRIPT_DIR/SUPublicEDKey")" "$(plist "$info" SUPublicEDKey)"
+    else
+        echo "  ⚠ $exe: no Sparkle public key available to assert (rt-tray/SUPublicEDKey or SPARKLE_PUBLIC_ED_KEY)"
+    fi
+}
+check_sparkle "$PROD"
+[ -n "$DEV" ] && check_sparkle "$DEV"
+```
+
+- [ ] **Step 4: Run + commit**
+
+Run: `cd rt-tray && RT_DAEMON_BIN=../dist/rt SPARKLE_PUBLIC_ED_KEY=$(openssl rand -base64 32) ./check-bundle.sh` → `0 failed` (the throwaway key proves the env override path end to end).
+
+```bash
+git add rt-tray/check-bundle.sh
+git commit -m "MAT-383: Sparkle — embedded framework + rpath + inside-out signature assertions in check-bundle
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 6: `scripts/release/` — zip, DMG, notarize, appcast
+
+**Files:**
+- Create: `scripts/release/make-zip.sh`
+- Create: `scripts/release/make-dmg.sh`
+- Create: `scripts/release/notarize.sh`
+- Create: `scripts/release/appcast.sh`
+- Modify: `scripts/README.md` (document the four + `fetch-deps.sh`)
+
+**Interfaces:**
+- `make-zip.sh <app> <out.zip>` → `ditto -c -k --sequesterRsrc --keepParent`; exit 0, zip exists.
+- `make-dmg.sh <app> <out.dmg> [signing-identity]` → APFS/LZFSE DMG named `mattstack` with an `Applications` symlink; signed when an identity is given.
+- `notarize.sh <path.app|path.dmg>` → needs `APPLE_ID`, `APPLE_ID_PASSWORD`, `APPLE_TEAM_ID`; submits (`.app` via a temporary zip), waits, prints the notary log on failure, staples and validates the target. **ORCHESTRATOR-ONLY to run**; implementers only `bash -n`.
+- `appcast.sh <archives-dir> <tag>` → needs `SPARKLE_ED_KEY` (private EdDSA key, the exact content of `generate_keys -x`'s file) and `rt-tray/deps/tools/sparkle/bin/generate_appcast`; pulls the previous `appcast.xml` + up to 2 previous zips into `<archives-dir>` so deltas are generated, runs `generate_appcast --download-url-prefix https://github.com/m4ttstack/rt/releases/download/<tag>/ --maximum-versions 3`, then deletes the downloaded old zips so only new files get uploaded. Output: `<archives-dir>/appcast.xml`, `<archives-dir>/*.delta`.
+
+- [ ] **Step 1: make-zip.sh**
+
+```bash
+#!/bin/bash
+# scripts/release/make-zip.sh <app> <out.zip> — the Sparkle enclosure.
+set -euo pipefail
+APP="$1"; OUT="$2"
+[ -d "$APP" ] || { echo "✗ no app at $APP" >&2; exit 1; }
+rm -f "$OUT"; mkdir -p "$(dirname "$OUT")"
+ditto -c -k --sequesterRsrc --keepParent "$APP" "$OUT"
+echo "✓ $(du -h "$OUT" | cut -f1) $OUT"
+```
+
+- [ ] **Step 2: make-dmg.sh**
+
+```bash
+#!/bin/bash
+# scripts/release/make-dmg.sh <app> <out.dmg> [signing-identity]
+# First-install disk image: APFS, LZFSE, volume "mattstack", drag-to-Applications.
+set -euo pipefail
+APP="$1"; OUT="$2"; IDENTITY="${3:-}"
+[ -d "$APP" ] || { echo "✗ no app at $APP" >&2; exit 1; }
+STAGE="$(mktemp -d)"
+trap 'rm -rf "$STAGE"' EXIT
+ditto "$APP" "$STAGE/$(basename "$APP")"
+ln -s /Applications "$STAGE/Applications"
+rm -f "$OUT"; mkdir -p "$(dirname "$OUT")"
+hdiutil create -volname "mattstack" -srcfolder "$STAGE" -ov -fs APFS -format ULFO -quiet "$OUT"
+if [ -n "$IDENTITY" ]; then
+    codesign --force --sign "$IDENTITY" --timestamp "$OUT"
+    echo "✓ signed $OUT"
+fi
+echo "✓ $(du -h "$OUT" | cut -f1) $OUT"
+```
+
+- [ ] **Step 3: notarize.sh**
+
+```bash
+#!/bin/bash
+# scripts/release/notarize.sh <target.app|target.dmg>
+# Submits to Apple's notary service, waits, staples, validates. Env:
+# APPLE_ID APPLE_ID_PASSWORD APPLE_TEAM_ID. On rejection prints the notary log.
+set -euo pipefail
+TARGET="$1"
+: "${APPLE_ID:?}" "${APPLE_ID_PASSWORD:?}" "${APPLE_TEAM_ID:?}"
+[ -e "$TARGET" ] || { echo "✗ no such target $TARGET" >&2; exit 1; }
+
+SUBMIT="$TARGET"
+TMP=""
+case "$TARGET" in
+    *.app)
+        TMP="$(mktemp -d)"; SUBMIT="$TMP/$(basename "$TARGET" .app).zip"
+        ditto -c -k --keepParent "$TARGET" "$SUBMIT" ;;
+    *.dmg) ;;
+    *) echo "✗ notarize.sh handles .app and .dmg only" >&2; exit 2 ;;
+esac
+trap '[ -n "$TMP" ] && rm -rf "$TMP"' EXIT
+
+echo "→ submitting $(basename "$SUBMIT") for notarization…"
+RESULT="$(xcrun notarytool submit "$SUBMIT" --apple-id "$APPLE_ID" --password "$APPLE_ID_PASSWORD" --team-id "$APPLE_TEAM_ID" --wait --timeout 45m --output-format json)"
+ID="$(printf '%s' "$RESULT" | /usr/bin/plutil -extract id raw -o - - 2>/dev/null || printf '%s' "$RESULT" | sed -n 's/.*"id" *: *"\([^"]*\)".*/\1/p' | head -1)"
+STATUS="$(printf '%s' "$RESULT" | sed -n 's/.*"status" *: *"\([^"]*\)".*/\1/p' | head -1)"
+echo "  submission $ID → $STATUS"
+if [ "$STATUS" != "Accepted" ]; then
+    xcrun notarytool log "$ID" --apple-id "$APPLE_ID" --password "$APPLE_ID_PASSWORD" --team-id "$APPLE_TEAM_ID" || true
+    exit 1
+fi
+xcrun stapler staple "$TARGET"
+xcrun stapler validate "$TARGET"
+echo "✓ notarized + stapled $TARGET"
+```
+
+- [ ] **Step 4: appcast.sh**
+
+```bash
+#!/bin/bash
+# scripts/release/appcast.sh <archives-dir> <tag>
+# Generates/updates appcast.xml for the zip in <archives-dir>. Pulls the
+# previous feed + up to two previous enclosures (for deltas) from the
+# latest GitHub Release, signs with SPARKLE_ED_KEY (stdin to generate_appcast),
+# and leaves only NEW files in <archives-dir>: the new zip, *.delta, appcast.xml.
+set -euo pipefail
+ARCHIVES="$1"; TAG="$2"
+: "${SPARKLE_ED_KEY:?private EdDSA key required}"
+ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+GEN="$ROOT/rt-tray/deps/tools/sparkle/bin/generate_appcast"
+[ -x "$GEN" ] || { echo "✗ $GEN missing — run scripts/fetch-deps.sh" >&2; exit 1; }
+REPO="${GITHUB_REPOSITORY:-m4ttstack/rt}"
+PREFIX="https://github.com/$REPO/releases/download/$TAG/"
+
+NEW_ZIP="$(ls "$ARCHIVES"/mattstack-*.zip | head -1)"
+[ -f "$NEW_ZIP" ] || { echo "✗ no mattstack-*.zip in $ARCHIVES" >&2; exit 1; }
+
+OLD_FILES=()
+if curl -fsSL -o "$ARCHIVES/appcast.xml" "https://github.com/$REPO/releases/latest/download/appcast.xml"; then
+    echo "→ previous appcast fetched"
+    # Enclosure URLs, newest first; the two newest become delta sources.
+    for url in $(grep -o 'url="[^"]*\.zip"' "$ARCHIVES/appcast.xml" | sed 's/url="//; s/"$//' | head -2); do
+        f="$ARCHIVES/$(basename "$url")"
+        if [ "$f" != "$NEW_ZIP" ] && curl -fsSL -o "$f" "$url"; then OLD_FILES+=("$f"); echo "  fetched $(basename "$f") for deltas"; fi
+    done
+else
+    rm -f "$ARCHIVES/appcast.xml"
+    echo "→ no previous appcast (first release)"
+fi
+
+printf '%s' "$SPARKLE_ED_KEY" | "$GEN" --ed-key-file - \
+    --download-url-prefix "$PREFIX" \
+    --maximum-versions 3 \
+    --link "https://github.com/$REPO/releases" \
+    "$ARCHIVES"
+
+for f in "${OLD_FILES[@]+"${OLD_FILES[@]}"}"; do rm -f "$f"; done
+rm -rf "$ARCHIVES/old_updates"
+grep -q "$(basename "$NEW_ZIP")" "$ARCHIVES/appcast.xml" || { echo "✗ appcast.xml does not reference $(basename "$NEW_ZIP")" >&2; exit 1; }
+echo "✓ appcast.xml updated; deltas: $(ls "$ARCHIVES"/*.delta 2>/dev/null | wc -l | tr -d ' ')"
+```
+
+- [ ] **Step 5: Local dry run of the two runnable scripts + syntax of all**
+
+Run: `chmod +x scripts/release/*.sh && bash -n scripts/release/*.sh && scripts/release/make-zip.sh rt-tray/mattstack.app rt-tray/out/mattstack-0.0.0.zip && scripts/release/make-dmg.sh rt-tray/mattstack.app rt-tray/out/mattstack-0.0.0.dmg && hdiutil attach rt-tray/out/mattstack-0.0.0.dmg -quiet -mountpoint /tmp/ms-dmg && ls /tmp/ms-dmg && hdiutil detach /tmp/ms-dmg -quiet`
+Expected: zip and dmg exist; the mounted DMG lists `Applications mattstack.app`. Then a local appcast run with a throwaway key (no network needed for the generate step when no previous appcast exists — `curl` to the release URL fails gracefully): `cd rt-tray && SPARKLE_ED_KEY="$(deps/tools/sparkle/bin/generate_keys -x /dev/stdout 2>/dev/null || true)"` — if the Keychain prompt is undesirable, skip this and rely on Task 15 (ORCHESTRATOR) for the first real appcast. `bash -n` and the zip/dmg runs are the required local evidence.
+
+- [ ] **Step 6: scripts/README.md** — add a `## release/` section listing the four scripts with one line each and `## fetch-deps.sh` (one line: fetch + verify helpers per `rt-tray/deps.lock`).
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add scripts/release scripts/README.md
+git commit -m "MAT-383: release scripts — zip enclosure, APFS DMG, notarize+staple, Sparkle appcast with deltas
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 7 (MATT): Sparkle EdDSA key pair → 1Password + `SPARKLE_ED_KEY` secret + committed public key
+
+**Files:**
+- Create: `rt-tray/SUPublicEDKey` (one line: the base64 public key)
+
+**Interfaces:**
+- Produces: GitHub secret `SPARKLE_ED_KEY` on m4ttstack/rt (private key file content); `rt-tray/SUPublicEDKey` consumed by build.sh (Task 4) and check-bundle (Task 5).
+
+- [ ] **Step 1 (MATT, on the live machine):**
+
+```bash
+cd /Users/matt/Documents/GitHub/repo-tools-l4-wt
+scripts/fetch-deps.sh arm64                                # brings rt-tray/deps/tools/sparkle
+rt-tray/deps/tools/sparkle/bin/generate_keys               # creates the key in the login Keychain, prints the public key
+rt-tray/deps/tools/sparkle/bin/generate_keys -p > rt-tray/SUPublicEDKey
+rt-tray/deps/tools/sparkle/bin/generate_keys -x "$HOME/Desktop/mattstack-sparkle-private.key"
+# → store mattstack-sparkle-private.key in 1Password (item "mattstack Sparkle EdDSA private key"), then:
+gh secret set SPARKLE_ED_KEY -R m4ttstack/rt < "$HOME/Desktop/mattstack-sparkle-private.key"
+rm -P "$HOME/Desktop/mattstack-sparkle-private.key"
+```
+
+- [ ] **Step 2: Verify + commit**
+
+`cat rt-tray/SUPublicEDKey` is a single base64 line (44 chars). `gh secret list -R m4ttstack/rt` lists `SPARKLE_ED_KEY`.
+
+```bash
+git add rt-tray/SUPublicEDKey
+git commit -m "MAT-383: Sparkle public EdDSA key for mattstack.app
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+(A lost private key means every installed app must be reinstalled by hand — the 1Password copy is the only backup. Never commit it; never echo it in CI logs.)
+
+---
+
+### Task 8: `.github/workflows/release.yml` rewrite — release job + clean-room job, tag or dry run
+
+**Files:**
+- Rewrite: `.github/workflows/release.yml`
+- Create: `lib/__tests__/release-workflow.test.ts` (shape assertions on the YAML)
+
+**Interfaces:**
+- Consumes: `scripts/fetch-deps.sh`, `rt-tray/build.sh` (env contract of Task 4), `scripts/release/*.sh` (Task 6), secrets `APPLE_CERT_P12_BASE64`, `APPLE_CERT_P12_PASSWORD`, `APPLE_ID`, `APPLE_ID_PASSWORD`, `APPLE_TEAM_ID`, `SPARKLE_ED_KEY`.
+- Consumes (L7): `scripts/e2e-cleanroom.sh <zip>` — the clean-room job calls it; L7 owns it.
+- Produces: Release assets `mattstack-<ver>.dmg`, `mattstack-<ver>.zip`, `*.delta`, `appcast.xml`, `SHA256SUMS`; on `workflow_dispatch` (dry run) the same files as a workflow artifact named `release-dry-run` and no Release.
+
+- [ ] **Step 1: Write the workflow**
+
+```yaml
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  release:
+    runs-on: macos-latest
+    outputs:
+      version: ${{ steps.meta.outputs.version }}
+      tag: ${{ steps.meta.outputs.tag }}
+      publish: ${{ steps.meta.outputs.publish }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Release metadata
+        id: meta
+        run: |
+          if [ "${GITHUB_EVENT_NAME}" = "push" ]; then
+            TAG="${GITHUB_REF_NAME}"; PUBLISH=true
+          else
+            TAG="v0.0.0-ci${GITHUB_RUN_NUMBER}"; PUBLISH=false
+          fi
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+          echo "version=${TAG#v}" >> "$GITHUB_OUTPUT"
+          echo "publish=$PUBLISH" >> "$GITHUB_OUTPUT"
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.13
+      - name: Install dependencies
+        run: bun install
+
+      # ── Developer ID (required on a tag; ad-hoc on a dry run) ────────────────
+      - name: Check signing secrets
+        id: signing
+        env:
+          CERT_B64: ${{ secrets.APPLE_CERT_P12_BASE64 }}
+          PUBLISH: ${{ steps.meta.outputs.publish }}
+        run: |
+          if [ -n "$CERT_B64" ]; then
+            echo "available=true" >> $GITHUB_OUTPUT
+          elif [ "$PUBLISH" = "true" ]; then
+            echo "::error::Developer ID secrets missing — a tagged release must be signed and notarized"; exit 1
+          else
+            echo "available=false" >> $GITHUB_OUTPUT
+            echo "::warning::Developer ID secrets not configured — dry run will be ad-hoc signed"
+          fi
+
+      - name: Import Developer ID certificate
+        if: steps.signing.outputs.available == 'true'
+        env:
+          APPLE_CERT_P12_BASE64: ${{ secrets.APPLE_CERT_P12_BASE64 }}
+          APPLE_CERT_P12_PASSWORD: ${{ secrets.APPLE_CERT_P12_PASSWORD }}
+        run: |
+          KEYCHAIN_PATH="$RUNNER_TEMP/rt-signing.keychain-db"
+          KEYCHAIN_PASSWORD=$(openssl rand -base64 24)
+          CERT_PATH="$RUNNER_TEMP/cert.p12"
+          echo "$APPLE_CERT_P12_BASE64" | base64 --decode > "$CERT_PATH"
+          security create-keychain -p "$KEYCHAIN_PASSWORD" "$KEYCHAIN_PATH"
+          security set-keychain-settings -lut 21600 "$KEYCHAIN_PATH"
+          security unlock-keychain -p "$KEYCHAIN_PASSWORD" "$KEYCHAIN_PATH"
+          security import "$CERT_PATH" -P "$APPLE_CERT_P12_PASSWORD" -A -t cert -f pkcs12 -k "$KEYCHAIN_PATH"
+          security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k "$KEYCHAIN_PASSWORD" "$KEYCHAIN_PATH"
+          security list-keychains -d user -s "$KEYCHAIN_PATH" $(security list-keychains -d user | tr -d '"')
+          SIGNING_IDENTITY=$(security find-identity -v -p codesigning "$KEYCHAIN_PATH" | grep "Developer ID Application" | head -1 | awk -F'"' '{print $2}')
+          [ -n "$SIGNING_IDENTITY" ] || { echo "::error::Developer ID Application certificate not found"; exit 1; }
+          echo "SIGNING_IDENTITY=$SIGNING_IDENTITY" >> $GITHUB_ENV
+          echo "KEYCHAIN_PATH=$KEYCHAIN_PATH" >> $GITHUB_ENV
+          rm -f "$CERT_PATH"
+
+      # ── Inputs to the bundle ─────────────────────────────────────────────────
+      - name: Compile rt (arm64)
+        run: bun build --compile --target=bun-darwin-arm64 ./cli.ts --outfile dist/rt --define RT_VERSION='"${{ steps.meta.outputs.tag }}"'
+
+      - name: Fetch bundled dependencies
+        run: scripts/fetch-deps.sh arm64
+
+      - name: Build extension
+        run: |
+          cd extensions/vscode/rt-context
+          bun install
+          bun run package
+          echo "RT_VSIX=$(ls "$PWD"/*.vsix | head -1)" >> $GITHUB_ENV
+
+      # ── The app (build.sh signs inside-out with the imported identity) ───────
+      - name: Build mattstack.app
+        env:
+          RT_DAEMON_BIN: ${{ github.workspace }}/dist/rt
+          RT_VERSION: ${{ steps.meta.outputs.tag }}
+          RT_REQUIRE_DEPS: "1"
+          RT_BUILD_TOOL: swift
+        run: rt-tray/build.sh release
+
+      - name: Assert the bundle contract
+        run: rt-tray/check-bundle.sh --app rt-tray/mattstack.app
+
+      - name: Notarize and staple the app
+        if: steps.signing.outputs.available == 'true'
+        env:
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_ID_PASSWORD: ${{ secrets.APPLE_ID_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+        run: scripts/release/notarize.sh rt-tray/mattstack.app
+
+      # ── Artifacts ────────────────────────────────────────────────────────────
+      - name: Zip enclosure + DMG
+        env:
+          VERSION: ${{ steps.meta.outputs.version }}
+        run: |
+          mkdir -p out
+          scripts/release/make-zip.sh rt-tray/mattstack.app "out/mattstack-${VERSION}.zip"
+          scripts/release/make-dmg.sh rt-tray/mattstack.app "out/mattstack-${VERSION}.dmg" "${SIGNING_IDENTITY:-}"
+
+      - name: Notarize and staple the DMG
+        if: steps.signing.outputs.available == 'true'
+        env:
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_ID_PASSWORD: ${{ secrets.APPLE_ID_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+          VERSION: ${{ steps.meta.outputs.version }}
+        run: scripts/release/notarize.sh "out/mattstack-${VERSION}.dmg"
+
+      - name: Appcast (signed, with deltas)
+        if: steps.meta.outputs.publish == 'true'
+        env:
+          SPARKLE_ED_KEY: ${{ secrets.SPARKLE_ED_KEY }}
+        run: |
+          [ -n "$SPARKLE_ED_KEY" ] || { echo "::error::SPARKLE_ED_KEY secret missing"; exit 1; }
+          scripts/release/appcast.sh out "${{ steps.meta.outputs.tag }}"
+
+      - name: Checksums
+        run: cd out && shasum -a 256 mattstack-*.dmg mattstack-*.zip *.delta appcast.xml 2>/dev/null > SHA256SUMS; cat out/SHA256SUMS
+
+      - name: Cleanup keychain
+        if: always() && env.KEYCHAIN_PATH != ''
+        run: security delete-keychain "$KEYCHAIN_PATH" || true
+
+      # ── Publish ──────────────────────────────────────────────────────────────
+      - name: Ensure release notes exist
+        if: steps.meta.outputs.publish == 'true'
+        run: '[ -f RELEASE_NOTES.md ] || echo "Release ${GITHUB_REF_NAME}." > RELEASE_NOTES.md'
+
+      - name: Create Release
+        if: steps.meta.outputs.publish == 'true'
+        uses: softprops/action-gh-release@v2
+        with:
+          body_path: RELEASE_NOTES.md
+          files: |
+            out/mattstack-*.dmg
+            out/mattstack-*.zip
+            out/*.delta
+            out/appcast.xml
+            out/SHA256SUMS
+
+      - name: Upload dry-run artifacts
+        if: steps.meta.outputs.publish != 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dry-run
+          path: out/
+          retention-days: 7
+
+  # ── Clean room (spec §12.2 layer a): a fresh runner installs from the zip ───
+  clean-room:
+    needs: release
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          sparse-checkout: |
+            scripts
+            rt-tray
+
+      - name: Download the app zip (release)
+        if: needs.release.outputs.publish == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          mkdir -p "$RUNNER_TEMP/dl"
+          gh release download "${{ needs.release.outputs.tag }}" -R "$GITHUB_REPOSITORY" -p "mattstack-*.zip" -D "$RUNNER_TEMP/dl"
+
+      - name: Download the app zip (dry run)
+        if: needs.release.outputs.publish != 'true'
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dry-run
+          path: ${{ runner.temp }}/dl
+
+      - name: Headless install + verify
+        run: scripts/e2e-cleanroom.sh "$(ls "$RUNNER_TEMP"/dl/mattstack-*.zip | head -1)"
+```
+
+The clean-room job's contract with L7's `scripts/e2e-cleanroom.sh` (cross-plan review §5 #36/#46): the job passes the zip **positionally** (`scripts/e2e-cleanroom.sh "<zip>"`) and L7's script accepts a positional `<zip|dmg|app>` as `--artifact`; the script does `ditto -x -k` into `/Applications`, runs `/Applications/mattstack.app/Contents/MacOS/rt --post-install --non-interactive --team-of-one --no-launch` (its defaults; `CI=true` also implies `--no-launch`), puts `~/.local/bin` on PATH, `rt --version`, `rt daemon install`, `rt verify --ci`, and runs `rt-tray/check-bundle.sh --app /Applications/mattstack.app` when present — the sparse checkout above includes `rt-tray` for that reason. Until L7's script lands, the job fails with "No such file" — that is the intended dependency signal, not something to paper over with an inline copy.
+
+- [ ] **Step 2: Shape test (keeps the job names/steps honest without running CI)**
+
+```ts
+// lib/__tests__/release-workflow.test.ts
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "fs";
+import { join } from "path";
+import { parse } from "yaml";
+
+const wf = parse(readFileSync(join(import.meta.dir, "..", "..", ".github", "workflows", "release.yml"), "utf8"));
+const stepNames = (job: string): string[] => wf.jobs[job].steps.map((s: any) => s.name ?? s.uses);
+
+describe("release.yml", () => {
+  test("triggers on v* tags and manual dispatch; two jobs", () => {
+    expect(wf.on.push.tags).toEqual(["v*"]);
+    expect(wf.on).toHaveProperty("workflow_dispatch");
+    expect(Object.keys(wf.jobs)).toEqual(["release", "clean-room"]);
+    expect(wf.jobs["clean-room"].needs).toBe("release");
+  });
+  test("arm64 only — no x64 compile, no tarballs", () => {
+    const text = JSON.stringify(wf);
+    expect(text).not.toContain("bun-darwin-x64");
+    expect(text).not.toContain("tar.gz");
+    expect(text).toContain("bun-darwin-arm64");
+  });
+  test("the train is ordered: compile → deps → build → contract → notarize app → zip/dmg → notarize dmg → appcast → release", () => {
+    const names = stepNames("release");
+    const idx = (n: string) => names.findIndex((s) => s.startsWith(n));
+    expect(idx("Compile rt")).toBeLessThan(idx("Fetch bundled dependencies"));
+    expect(idx("Fetch bundled dependencies")).toBeLessThan(idx("Build mattstack.app"));
+    expect(idx("Build mattstack.app")).toBeLessThan(idx("Assert the bundle contract"));
+    expect(idx("Assert the bundle contract")).toBeLessThan(idx("Notarize and staple the app"));
+    expect(idx("Notarize and staple the app")).toBeLessThan(idx("Zip enclosure + DMG"));
+    expect(idx("Zip enclosure + DMG")).toBeLessThan(idx("Notarize and staple the DMG"));
+    expect(idx("Notarize and staple the DMG")).toBeLessThan(idx("Appcast"));
+    expect(idx("Appcast")).toBeLessThan(idx("Create Release"));
+  });
+  test("release assets are the dmg, the zip, deltas, appcast, checksums", () => {
+    const step = wf.jobs.release.steps.find((s: any) => s.name === "Create Release");
+    expect(step.with.files).toContain("out/mattstack-*.dmg");
+    expect(step.with.files).toContain("out/mattstack-*.zip");
+    expect(step.with.files).toContain("out/appcast.xml");
+    expect(step.with.files).toContain("out/*.delta");
+  });
+  test("clean room runs L7's script, not inline steps, and never installs brew packages", () => {
+    const text = JSON.stringify(wf.jobs["clean-room"]);
+    expect(text).toContain("scripts/e2e-cleanroom.sh");
+    expect(text).not.toContain("brew install");
+  });
+  test("bun is pinned to the deps.lock version", () => {
+    const lock = JSON.parse(readFileSync(join(import.meta.dir, "..", "..", "rt-tray", "deps.lock"), "utf8"));
+    const bun = lock.tools.find((t: any) => t.name === "bun").version;
+    const setup = wf.jobs.release.steps.find((s: any) => String(s.uses ?? "").startsWith("oven-sh/setup-bun"));
+    expect(setup.with["bun-version"]).toBe(bun);
+  });
+});
+```
+
+Run: `bun test lib/__tests__/release-workflow.test.ts` → PASS.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add .github/workflows/release.yml lib/__tests__/release-workflow.test.ts
+git commit -m "MAT-383: release.yml — arm64 app train (deps, build, notarize, dmg, zip, appcast) + clean-room job; tarballs gone
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 9: rt side — `installRtBinary` symlink, `trayAppPath` via `mattstack.appPath`, `legacyUserAppPath`
+
+**Trimmed by the cross-plan review (§1 row 1):** `commands/post-install.ts` and `lib/__tests__/post-install-sweep.test.ts` are L1 T27/T24's. L1 T27 absorbs verbatim the `appPathIsTransient`/exit-2 refusal, the `runLegacySweep(root)` body and its new sweep test case that this task previously carried (they live in this file at commit `4d36c2d`, L4:1928-1937 and L4:1985-2127); L1 T24 `settings.seed` records `mattstack.appPath` via `bundleRootFromExec()`; L1 T5 `path.link` calls `installRtBinary`. This task now ships only the two library modules L1 consumes.
+
+**Files:**
+- Modify: `lib/dev-mode.ts:37-50` (`installRtBinary` → atomic symlink)
+- Modify: `lib/rt-paths.ts:116-131` (`trayAppPath`/`devTrayAppPath` read the machine key, default `/Applications`; `legacyUserAppPath()`)
+- ~~Modify: `commands/post-install.ts`~~ — Dropped — owned by L1 T27/T24 (cross-plan review).
+- Modify: `lib/__tests__/dev-mode.test.ts`, `lib/__tests__/rt-paths.test.ts:160-180`, `lib/__tests__/dev-mode-handoff.test.ts` (fake bundle path)
+- ~~Modify: `lib/__tests__/post-install-sweep.test.ts`~~ — Dropped — owned by L1 T27 (cross-plan review).
+
+**Interfaces:**
+- Consumes: `installedTrayAppPath` (existing; already reads `mattstack.appPath`).
+- Produces: `installRtBinary(src): string` now creates `~/.local/bin/rt -> src` (symlink, link-then-rename); `trayAppPath(exists?)`, `devTrayAppPath(exists?)`; `legacyUserAppPath()`. (Post-install exit code 2 on a DMG/translocated path is produced by L1 T27/T24.)
+
+- [ ] **Step 1: Failing tests**
+
+Add to `lib/__tests__/dev-mode.test.ts`:
+```ts
+import { lstatSync, readlinkSync, realpathSync } from "fs";
+import { installRtBinary } from "../dev-mode.ts";
+
+describe("installRtBinary", () => {
+  const BIN = join(process.env.HOME!, ".local", "bin");
+  afterEach(() => { try { rmSync(join(BIN, "rt")); } catch { /* absent */ } });
+
+  test("creates ~/.local/bin/rt as a symlink to the given binary", () => {
+    const src = join(process.env.HOME!, "mattstack.app", "Contents", "MacOS", "rt");
+    mkdirSync(dirname(src), { recursive: true });
+    writeFileSync(src, Buffer.from([0xcf, 0xfa, 0xed, 0xfe]), { mode: 0o755 });
+    const dest = installRtBinary(src);
+    expect(lstatSync(dest).isSymbolicLink()).toBe(true);
+    expect(readlinkSync(dest)).toBe(src);
+    expect(currentMode()).toBe("prod");
+  });
+
+  test("replaces an existing regular file (the dev wrapper) and an existing link atomically", () => {
+    mkdirSync(BIN, { recursive: true });
+    writeFileSync(join(BIN, "rt"), "#!/bin/sh\nexit 0\n", { mode: 0o755 });
+    const src = join(process.env.HOME!, "app-a", "Contents", "MacOS", "rt");
+    mkdirSync(dirname(src), { recursive: true }); writeFileSync(src, "", { mode: 0o755 });
+    installRtBinary(src);
+    expect(realpathSync(join(BIN, "rt"))).toBe(realpathSync(src));
+    const src2 = join(process.env.HOME!, "app-b", "Contents", "MacOS", "rt");
+    mkdirSync(dirname(src2), { recursive: true }); writeFileSync(src2, "", { mode: 0o755 });
+    installRtBinary(src2);
+    expect(readlinkSync(join(BIN, "rt"))).toBe(src2);
+  });
+
+  test("currentMode reads through the link: a link to a script is dev, to a Mach-O is prod", () => {
+    const script = join(process.env.HOME!, "wrapper.sh");
+    writeFileSync(script, "#!/bin/zsh\nexit 0\n", { mode: 0o755 });
+    installRtBinary(script);
+    expect(currentMode()).toBe("dev");
+  });
+});
+```
+(add `dirname` to the `path` import and `lstatSync, readlinkSync, realpathSync` to the `fs` import.)
+
+Replace `lib/__tests__/rt-paths.test.ts` tests at lines 167-180 with:
+```ts
+  test("trayAppPath prefers the installed bundle (machine key, /Applications, ~/Applications) and defaults to /Applications", () => {
+    const none = () => false;
+    expect(trayAppPath(none)).toBe("/Applications/mattstack.app");
+    expect(devTrayAppPath(none)).toBe("/Applications/mattstack-dev.app");
+    const userOnly = (p: string) => p === join(process.env.HOME!, "Applications", "mattstack.app");
+    expect(trayAppPath(userOnly)).toBe(join(process.env.HOME!, "Applications", "mattstack.app"));
+  });
+```
+
+In `lib/__tests__/dev-mode-handoff.test.ts`: define `const FAKE_PROD_APP = join(HOME, "Applications", TRAY_APP_BUNDLE)` and `const FAKE_DEV_APP = join(HOME, "Applications", DEV_TRAY_APP_BUNDLE)` (import the two constants from `../rt-paths.ts` instead of `trayAppPath`/`devTrayAppPath`), and use them wherever the test previously called `trayAppPath()`/`devTrayAppPath()` (the `mkdirSync`/`writeFileSync` of the fake bundles and the `expect(openLine).toContain(...)` assertions). `isolatedExists` already denies `/Applications/`, so `installedTrayAppPath(..., isolatedExists)` finds the fake under `~/Applications`.
+
+(The `post-install-sweep.test.ts` case for the stale `~/Applications/mattstack.app` copy + unconditional `com.rt.daemon` bootout is L1 T27's — Dropped here, cross-plan review §1 row 1.)
+
+Run: `bun test lib/__tests__/dev-mode.test.ts lib/__tests__/rt-paths.test.ts` → FAIL (symlink, signature).
+
+- [ ] **Step 2: Implement `lib/dev-mode.ts`**
+
+```ts
+import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readSync, renameSync, rmSync, symlinkSync } from "fs";
+…
+/**
+ * Link ~/.local/bin/rt at `src` (the rt inside the app bundle). Link-then-
+ * rename so a process executing the old target keeps its mapped pages and
+ * the switch is atomic whether the old entry was a file or a link.
+ */
+export function installRtBinary(src: string): string {
+  const dest = rtBinaryPath();
+  mkdirSync(dirname(dest), { recursive: true });
+  const tmp = `${dest}.new`;
+  rmSync(tmp, { force: true });
+  symlinkSync(src, tmp);
+  renameSync(tmp, dest);
+  return dest;
+}
+```
+(`copyFileSync`/`chmodSync` imports drop out if now unused.) `currentMode()` is unchanged — `existsSync`/`openSync` follow symlinks, which is the "reads through links" requirement.
+
+- [ ] **Step 3: Implement `lib/rt-paths.ts`**
+
+```ts
+/** Where the prod bundle is: the machine key / /Applications / ~/Applications, defaulting to /Applications (V3). */
+export function trayAppPath(exists: (path: string) => boolean = existsSync): string {
+  return installedTrayAppPath(TRAY_APP_BUNDLE, exists) ?? join("/Applications", TRAY_APP_BUNDLE);
+}
+
+/** Same for the dev bundle. */
+export function devTrayAppPath(exists: (path: string) => boolean = existsSync): string {
+  return installedTrayAppPath(DEV_TRAY_APP_BUNDLE, exists) ?? join("/Applications", DEV_TRAY_APP_BUNDLE);
+}
+
+/** The phase-1 install location, swept when the app now lives elsewhere (V3). */
+export function legacyUserAppPath(): string {
+  return join(home(), "Applications", TRAY_APP_BUNDLE);
+}
+```
+`installedTrayAppPath` must be declared before use — move the two functions below it or leave hoisting to do its job (function declarations hoist; fine). Update the docblock above them: "Where a bundle is ACTUALLY installed…" now applies to both.
+
+- [ ] **Step 4: Implement `commands/post-install.ts` changes**
+
+Dropped — owned by L1 T27/T24 (cross-plan review): L1 T27 rewrites `commands/post-install.ts` as sweep → `setupApply([...])` with `runPostInstall(args: string[], opts: { bundleRoot?: string | null } = {})`, absorbing this task's former `appPathIsTransient` exit-2 refusal and `runLegacySweep(root)` body; `recordAppPath`/`installRtBinaryStep`/`findVsix` become L1's `settings.seed`/`path.link`/`extension.install` apply steps. L1 T27 runs AFTER this task merges (it imports `installRtBinary`, `legacyUserAppPath`, `bundleRootFromExec`).
+
+- [ ] **Step 5: Run + typecheck + commit**
+
+Run: `bun test && bunx tsc --noEmit` → green (`commands/post-install.ts` still calls `installRtBinary(src)` with the same signature, so the existing `post-install-sweep.test.ts` stays green untouched until L1 T27 rewrites both).
+
+```bash
+git add lib/dev-mode.ts lib/rt-paths.ts lib/__tests__/dev-mode.test.ts lib/__tests__/rt-paths.test.ts lib/__tests__/dev-mode-handoff.test.ts
+git commit -m "MAT-383: installRtBinary links into the bundle; trayAppPath honours mattstack.appPath; legacyUserAppPath
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 10: `rt update` is thin — ask the app (`POST /update/check`)
+
+Dropped — owned by L1 T30 (`commands/update.ts`: `POST /update/check` via `trayRequest`, exit **2** + `--json` envelope per the contract — ruling R4) and L1 T10 (`cli.ts` first-run hook) (cross-plan review §1 rows 2, 4). L1 T30 adopts this task's injectable `deps` shape (`tray`, `currentMode`, `log`, `exit`), the `res.ok === false` "this mattstack.app predates CLI-triggered updates — use the menu bar" branch, and `RELEASES_URL = https://github.com/m4ttstack/rt/releases/latest`; the former body is in this file at commit `4d36c2d` (L4:2146-2266). Task 12 regenerates `website/docs/reference/update.mdx` after L1 T30 merges.
+
+---
+
+### Task 11: Bundled fzf first, terminal-notifier dropped (`rt verify` rows are L1's)
+
+**Files:**
+- Modify: `lib/fzf.ts`
+- Modify: `lib/__tests__/fzf.test.ts`
+- ~~Modify: `commands/verify.ts`~~ — Dropped — owned by L1 T7/T11 (cross-plan review §1 row 3): L1 T7 adds the `tool.rt-link` and `tool.vsix` rows to the rt-health table and makes `tool.fzf` report `resolveFzf()`'s "bundled | PATH"; L1 T11 turns the table into `rt verify`'s rows. Nothing from this task's former verify.ts edit is lost.
+- Modify: `lib/notifier.ts:225-296` (osascript only), `lib/__tests__/notifier-fallback.test.ts`
+- `e2e/tests/verify.test.ts` unaffected (no check name changes here).
+
+**Interfaces:**
+- Consumes: `bundledHelperPath("fzf")`, `appBundleRoot()` (Task 1).
+- Produces: `resolveFzf(which?, bundled?)` — bundled path first, then PATH (L1 T7 consumes it for the `tool.fzf` row); `FZF_MISSING_MESSAGE` names the bundle; `__test__.setFallbackNotifier(argv0 | null)` replaces `setTerminalNotifierPath`.
+
+- [ ] **Step 1: fzf tests (replace the file)**
+
+```ts
+import { describe, test, expect } from "bun:test";
+import { resolveFzf, ensureFzf, FZF_MISSING_MESSAGE } from "../fzf.ts";
+
+describe("resolveFzf", () => {
+  test("prefers the fzf bundled inside mattstack.app", () => {
+    expect(resolveFzf(() => "/opt/homebrew/bin/fzf", () => "/Applications/mattstack.app/Contents/Helpers/fzf"))
+      .toBe("/Applications/mattstack.app/Contents/Helpers/fzf");
+  });
+  test("falls back to PATH when nothing is bundled (source runs, dev mode)", () => {
+    expect(resolveFzf(() => "/opt/homebrew/bin/fzf", () => null)).toBe("/opt/homebrew/bin/fzf");
+  });
+  test("null when neither exists", () => {
+    expect(resolveFzf(() => null, () => null)).toBeNull();
+  });
+});
+
+describe("ensureFzf", () => {
+  test("returns the resolved path when present", () => {
+    expect(ensureFzf(() => null, (msg) => { throw new Error(msg); }, () => "/x/fzf")).toBe("/x/fzf");
+  });
+  test("fails with an actionable message naming the bundle when missing", () => {
+    let captured = "";
+    expect(() => ensureFzf(() => null, (msg) => { captured = msg; throw new Error("would-exit"); }, () => null)).toThrow("would-exit");
+    expect(captured).toContain("fzf not found");
+    expect(captured).toContain("mattstack.app");
+  });
+});
+
+describe("FZF_MISSING_MESSAGE", () => {
+  test("says where rt looks and what to do", () => {
+    expect(FZF_MISSING_MESSAGE).toContain("Contents/Helpers/fzf");
+    expect(FZF_MISSING_MESSAGE).toContain("brew install fzf");
+  });
+});
+```
+
+- [ ] **Step 2: `lib/fzf.ts`**
+
+```ts
+/**
+ * fzf is a hard dependency of rt: every interactive picker shells out to it.
+ * rt uses the copy bundled inside mattstack.app by absolute path (ruling 8)
+ * and only falls back to PATH when it is not running from an install
+ * (source checkout, dev mode). Every fzf spawn site calls ensureFzf() first.
+ */
+import { bundledHelperPath } from "./bundle-layout.ts";
+import { bold, dim, yellow, reset } from "./tui.ts";
+
+type Which = (bin: string) => string | null;
+type Bundled = () => string | null;
+const defaultWhich: Which = (b) => Bun.which(b);
+const defaultBundled: Bundled = () => bundledHelperPath("fzf");
+
+/** Bundled fzf first, then PATH; null when neither. Injectable for tests. */
+export function resolveFzf(which: Which = defaultWhich, bundled: Bundled = defaultBundled): string | null {
+  return bundled() ?? which("fzf");
+}
+
+export const FZF_MISSING_MESSAGE =
+  `\n  ${yellow}fzf not found${reset}\n` +
+  `  ${dim}rt uses the fzf inside mattstack.app (Contents/Helpers/fzf) and found neither it nor an fzf on PATH.${reset}\n` +
+  `  ${dim}Reinstall mattstack.app, or${reset} ${bold}brew install fzf${reset}${dim} to use your own copy, then re-run.${reset}\n`;
+
+export function ensureFzf(
+  which: Which = defaultWhich,
+  fail: (msg: string) => never = (msg) => { console.error(msg); process.exit(1); },
+  bundled: Bundled = defaultBundled,
+): string {
+  const path = resolveFzf(which, bundled);
+  if (path) return path;
+  return fail(FZF_MISSING_MESSAGE);
+}
+```
+Check every `ensureFzf(` caller compiles unchanged (`grep -rn "ensureFzf(" lib commands`) — the new parameter is last and optional.
+
+- [ ] **Step 3: `commands/verify.ts`**
+
+Dropped — owned by L1 T7 (`tool.rt-link`, `tool.vsix`, `tool.fzf` rows in the rt-health table; remedy text "run: rt setup apply --from path.link") and L1 T11 (verify = validator rows) (cross-plan review). L1 T7 runs after this task merges so `resolveFzf()` exists.
+
+- [ ] **Step 4: `lib/notifier.ts` — osascript only**
+
+Delete `_terminalNotifierPath`, `resolveTerminalNotifier`, and the Homebrew candidate list. `notifyFallback` becomes:
+```ts
+/** Fallback notifier executable; replaceable in tests with a fake that hangs. */
+let fallbackNotifier = "osascript";
+
+/** Direct notification via osascript (no queue); fire-and-forget with a kill escalation (MAT-222). */
+function notifyFallback(title: string, message: string, _url?: string): void {
+  const body = `${title}: ${message}`;
+  const argv = [fallbackNotifier, "-e", `display notification "${escapeAppleScript(body)}" with title "rt"`];
+  try {
+    const proc = Bun.spawn(argv, { stdin: "ignore", stdout: "ignore", stderr: "ignore" });
+    const term = setTimeout(() => { try { proc.kill("SIGTERM"); } catch { /* exited */ } }, FALLBACK_TERM_MS);
+    const kill = setTimeout(() => { try { proc.kill("SIGKILL"); } catch { /* exited */ } }, FALLBACK_KILL_MS);
+    void proc.exited.finally(() => { clearTimeout(term); clearTimeout(kill); });
+  } catch { /* notification is best-effort */ }
+}
+```
+and in `__test__`: replace `setTerminalNotifierPath` with
+```ts
+  setFallbackNotifier(path: string | null): void { fallbackNotifier = path ?? "osascript"; },
+```
+Update the module docblock line 12 (`terminal-notifier/osascript` → `osascript`) and line 301. In `lib/__tests__/notifier-fallback.test.ts`: `__test__.setFallbackNotifier(fakeHangingNotifier(15))` / `afterEach(() => __test__.setFallbackNotifier(null))`; rename the fake file to `osascript` inside `fakeHangingNotifier` (the name is cosmetic — the path is passed explicitly).
+
+- [ ] **Step 5: Run + commit**
+
+Run: `bun test lib/__tests__/fzf.test.ts lib/__tests__/notifier-fallback.test.ts lib/__tests__/notifier.test.ts && bunx tsc --noEmit && grep -rn "terminal-notifier" lib commands | wc -l` → tests PASS; grep count `0` (the README mention goes in Task 12).
+
+```bash
+git add lib/fzf.ts lib/__tests__/fzf.test.ts lib/notifier.ts lib/__tests__/notifier-fallback.test.ts
+git commit -m "MAT-383: bundled fzf by absolute path (resolveFzf), terminal-notifier dropped
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 12: Docs — README install/upgrade/requirements, CLAUDE.md, website install page, rt-release skill
+
+**AFTER L1 T30 + T31 merge** (`update.mdx` is regenerated from L1's new `rt update` tree description; L1 T31 then rebases onto this task for the final `bun run docs:gen && bun run docs:check` — cross-plan review §1 rows 5–6, §3). L4 owns `README.md`; L1 T31 only asserts that the brew/tmux/zellij/terminal-notifier lines are gone.
+
+**Files:**
+- Modify: `README.md` (`## Install`, `### What Gets Installed`, `### Upgrade`, `## Requirements`, `### Testing the installer`, `### rt-tray`, `### Release process`)
+- Modify: `CLAUDE.md:3` (distribution sentence)
+- Modify: `website/docs/getting-started/install.mdx`
+- Modify: `skills/rt-release/SKILL.md`
+- Regenerate: `website/docs/reference/update.mdx` via `bun run docs:gen`
+
+**Interfaces:** none (prose). Every statement must match Tasks 1–11 (no tarballs, no tap, no tmux/terminal-notifier, DMG + `rt update` asks the app).
+
+- [ ] **Step 1: README**
+
+`## Install` becomes:
+```markdown
+## Install
+
+Download `mattstack-<version>.dmg` from the latest
+[GitHub Release](https://github.com/m4ttstack/rt/releases/latest), open it, and
+drag **mattstack.app** to `/Applications`. Launch it once: the menu-bar "m"
+appears and the setup window walks you through the rest (rt on your PATH, the
+daemon, the editor extension, permissions, your team).
+
+Headless (CI, a fresh machine over SSH):
+
+```bash
+ditto -x -k mattstack-<version>.zip /Applications
+/Applications/mattstack.app/Contents/MacOS/rt --post-install
+rt verify
+```
+
+`~/.local/bin/rt` is a symlink into the app bundle; `rt verify` reports the
+health of each piece.
+```
+`### What Gets Installed` table: `rt` binary → "Symlink `~/.local/bin/rt` → `mattstack.app/Contents/MacOS/rt`"; `rt-tray.app` row → `mattstack.app` "Menu bar app: setup, daemon health, notifications, Sparkle updates"; `fzf` + `tmux` row → "Bundled tools | `fzf`, `jq`, `gh`, `glab`, `bun`, a private `node`, `fast-browser` inside `Contents/Helpers` — used by rt by absolute path; none are put on your PATH unless you ask"; drop `tmux`.
+`### Upgrade`: "mattstack.app updates itself (Sparkle) and restarts its services when its version changes. `rt update` just asks the app to check now."
+`## Requirements`: macOS 14 or newer, Apple Silicon; Xcode Command Line Tools (git); `fzf` row → "bundled; a `brew install fzf` copy is used only when rt runs from source"; delete the `tmux` row; keep `chafa`/`kitten` optional rows.
+`### Testing the installer`: `rt --post-install` is the headless entry — it runs the legacy sweep and then `rt setup apply --non-interactive --team-of-one` (L1 T27), which records `mattstack.appPath`, links `~/.local/bin/rt`, installs `rt-context.vsix` from `Contents/Resources`, registers the services when the app is reachable, writes shell integration. State explicitly that a first `rt` invocation no longer auto-runs setup (L1 T10 prints a one-line hint instead — `rt verify` after a bare install reports what is missing); do not promise auto-setup anywhere in the README.
+`### rt-tray`: add `scripts/fetch-deps.sh arm64` before `./build.sh release`, mention `RT_DAEMON_BIN=../dist/rt ./check-bundle.sh`, `./build.sh install` → `/Applications`.
+`### Release process`: "Push a version tag (`skills/rt-release`); CI compiles rt (arm64), fetches the pinned helpers, builds + signs + notarizes mattstack.app, produces `mattstack-<ver>.dmg` / `.zip`, signs the Sparkle appcast, publishes the Release, then installs from the zip on a fresh runner and runs `rt verify --ci`."
+
+- [ ] **Step 2: CLAUDE.md line 3**
+
+`Personal developer CLI built with Bun. Compiled to a standalone binary via \`bun build --compile\` and shipped inside mattstack.app (DMG first install, Sparkle updates); \`~/.local/bin/rt\` is a symlink into the bundle.`
+
+- [ ] **Step 3: website install.mdx** — mirror the README `## Install` + `## Upgrade` text (DMG, headless zip, `rt update` asks the app); table rows as in Step 1. Then `bun run docs:gen && bun run docs:check` (regenerates `reference/update.mdx` from the command tree as L1 T30 left it — exit 2 + `--json`; if `docs:check` flags drift elsewhere, fix only what this plan changed). L1 T31 re-runs both after merging on top of this task.
+
+- [ ] **Step 4: skills/rt-release/SKILL.md**
+
+- Intro paragraph: "…builds mattstack.app (arm64), notarizes it, attaches `mattstack-<ver>.dmg`, `mattstack-<ver>.zip`, the deltas, `appcast.xml` and `SHA256SUMS`, then installs from the zip on a fresh runner."
+- Step 1 gains two preconditions: `rt-tray/SUPublicEDKey` is committed and `gh secret list -R m4ttstack/rt` shows `APPLE_*` + `SPARKLE_ED_KEY`; if either is missing, stop and say so.
+- Step 8: assets to confirm are the five above; also "the `clean-room` job is green (the headless install proved `rt verify --ci`)" and "`curl -fsSL https://github.com/m4ttstack/rt/releases/latest/download/appcast.xml | grep sparkle:version` shows the new build number".
+- Guardrails: add "Never re-run `generate_appcast` by hand against a published release — CI is the only appcast writer; if a release is broken, cut the next tag."
+- Delete every `rt-darwin-*.tar.gz` mention.
+
+Also (for Task 8's `lib/__tests__/release-workflow.test.ts`, which does `import { parse } from "yaml"`): add `yaml` to `devDependencies` in `package.json` (`bun add -d yaml`) — or switch the test to Bun's built-in YAML parser if one is available in the pinned Bun — and say which in the commit body.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add README.md CLAUDE.md website/docs skills/rt-release/SKILL.md package.json bun.lock
+git commit -m "MAT-383: docs — DMG install, Sparkle upgrade, bundled tools, new release train
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 13 (ORCHESTRATOR-ONLY / MATT): Entitlement measurement on a Developer-ID-signed build
+
+**Why:** §14 risk 1 and ruling-8 "start allow-jit only, test". Ad-hoc signatures do not enforce the hardened runtime, so only a Developer-ID build answers this.
+
+- [ ] **Step 1 (live machine, Developer ID in the login keychain):**
+```bash
+cd /Users/matt/Documents/GitHub/repo-tools-l4-wt
+bun build --compile ./cli.ts --outfile dist/rt && scripts/fetch-deps.sh arm64
+RT_DAEMON_BIN=$PWD/dist/rt rt-tray/build.sh release        # signs with Developer ID
+A=rt-tray/mattstack.app/Contents
+"$A/MacOS/rt" --version && "$A/MacOS/rt" verify --json >/dev/null; echo "rt exit $?"
+"$A/Helpers/bun" --version; "$A/Helpers/bun" -e 'console.log(1+1)'
+"$A/Helpers/node/bin/node" -e 'console.log(process.versions.node)'
+"$A/Helpers/node/bin/node" "$A/Helpers/fast-browser/bin/fast-browser.mjs" --help >/dev/null; echo "fb exit $?"
+for t in fzf jq gh glab; do "$A/Helpers/$t" --version >/dev/null && echo "$t ok"; done
+HOME=$(mktemp -d) "$A/MacOS/rt" nav --help >/dev/null 2>&1; echo "picker path exit $?"
+```
+- [ ] **Step 2:** If any Bun/Node binary dies with `SIGKILL`/`Code Signature Invalid`/`mmap` errors in Console, add `com.apple.security.cs.allow-unsigned-executable-memory` **for that tool only**: introduce `scripts/entitlements-jit-unsigned.plist` (jit + unsigned-exec-mem), a new `entitlements: "jit-unsigned"` value in `deps.lock` + `lib/bundle-layout.ts` (`DepsLockEntitlements`), build.sh's `sign_helper_tree` mapping it, and check-bundle's `check_signed` accepting it for that tool. If `rt` itself needs it, swap `ENTITLEMENTS_JIT` for rt only. Record the measured outcome per tool in the commit body.
+- [ ] **Step 3:** `RT_DAEMON_BIN=$PWD/dist/rt rt-tray/check-bundle.sh` → 0 failed with Developer ID (the runtime-flag assertions now execute). Commit `MAT-383: entitlements measured on a Developer ID build — <outcome>`.
+
+### Task 14 (ORCHESTRATOR-ONLY / MATT): Xcode 26 path + Matt's machine cutover
+
+**AFTER L3 T2 merges** (`rt-tray/project.yml` is L3's; `xcodegen generate --spec` consumes it).
+
+- [ ] After Matt installs Xcode 26 and L3's `rt-tray/project.yml` exists: `sudo xcode-select -s /Applications/Xcode.app && cd rt-tray && RT_DAEMON_BIN=../dist/rt ./check-bundle.sh` — build.sh must pick `xcode` automatically (log line "with xcode"), and both flavors must pass the same assertions as the swift path. Then `RT_BUILD_TOOL=swift ./check-bundle.sh` must still pass (the CLT path stays the CI default until the Xcode path has produced one green release).
+- [ ] Cutover of the live machine (identifier `rt-daemon` → `rt` invalidates launchd's cached launch constraints for the old job): `rt-tray/build.sh install` (prod) then `rt daemon install`; if the agent fails with `EX_CONFIG`/"launch constraint", `launchctl bootout gui/$UID/com.mattstack.daemon; sfltool resetbtm` then re-open the app and approve it in Login Items once. Re-grant Full Disk Access to `/Applications/mattstack.app` (V3). Run `rt verify`.
+
+### Task 15 (ORCHESTRATOR-ONLY): Dry run, then the first tagged release
+
+- [ ] `gh workflow run release.yml -R m4ttstack/rt --ref goodwinmattheweric/mat-383-release-pipeline` (dry run) — the `release` job must reach "Upload dry-run artifacts"; `clean-room` depends on L7's `scripts/e2e-cleanroom.sh` (fails with "No such file" until L7 merges; that failure is expected and reported, not patched around).
+- [ ] Merge order: L3's `project.yml` is not required for the swift path; L7's script is required for a green clean-room job; Task 7's key is required for a tag.
+- [ ] First tag via `skills/rt-release`; confirm assets, `appcast.xml` reachable at the `latest/download` URL, `clean-room` green, and one manual Sparkle update on Matt's machine from the previous build (VM layer b is L7's).
+
+---
+
+## Self-review
+
+**Spec coverage (L4 scope items 1–8 from the brief, against §2/§7/§8/§11/§12.2/§14):**
+1. Identity freeze — Task 3 (rt identifier, numeric CFBundleVersion, jit-only entitlements, check-bundle asserts the whole contract); the plist templates, `Package.swift` floor and Swift string edits are L3 T1/T2/T18's (cross-plan review). ✔
+2. deps.lock + fetch-deps.sh + Helpers bundling + per-helper signing/entitlements, pending placeholders — Tasks 2, 4, 13. ✔
+3. build.sh wraps xcodebuild with CLT fallback; Sparkle embed + rpath + inside-out signing; SUFeedURL/SUPublicEDKey injection (file or `SPARKLE_PUBLIC_ED_KEY`) — Tasks 4, 5, 14. ✔
+4. DMG + notarize + staple; zip enclosure via ditto — Task 6 (+ Task 8 wiring). ✔
+5. generate_appcast in CI with `SPARKLE_ED_KEY`, last 3 zips for deltas, host decided (Release asset via `latest/download`), DMG+zip uploaded — Tasks 6, 7, 8. ✔
+6. release.yml rewrite incl. clean-room job (calls L7's script with `--post-install --non-interactive --team-of-one --no-launch`; `rt verify --ci`) — Task 8. ✔ Tarball dropped (Decision 2). ✔
+7. `installRtBinary` → symlink; `trayAppPath` via `mattstack.appPath`; `legacyUserAppPath` — Task 9 (trimmed). `rt update` thin (exit 2 + `--json`), `commands/post-install.ts` (sweep + `setupApply`, exit 2 on a DMG path), `rt verify` rows — L1 T30 / T27+T24 / T7+T11 (cross-plan review; L4 T10 dropped). check-bundle asserts the new layout — Task 3. ✔ fzf by absolute path, terminal-notifier drop — Task 11. ✔
+8. README/CLAUDE.md/website/rt-release skill; tap references gone — Task 12. ✔
+Coordinator additions (a)–(e) — Global Constraints + Tasks 4, 5, 8. ✔
+§8 agent plists: rendered by L3's `render-launchagents.sh` (daemon + deck, `KeepAlive {SuccessfulExit:false}`, static `EnvironmentVariables.PATH` per ruling R2 — rt/deck prepend their Helpers dir and `~/.local/bin` themselves) — Task 4 calls it, Task 3's check-bundle asserts both plists. §14 risk 1 — Task 13. ✔
+
+**Placeholder scan:** the only deferred values are the outcomes of ORCHESTRATOR tasks (entitlement measurement, first notarized run) and L7's script, each named explicitly. `deps.lock` carries real hashes computed from the real URLs.
+
+**Type/name consistency:** `bundleRootFromExec`/`appBundleRoot`/`bundledHelperPath`/`bundledExec`/`readDepsLock`/`RT_BUNDLE_PATH`/`DEPS_LOCK_BUNDLE_PATH` (Task 1) are the names L1 T5/T24/T27 consume; `installRtBinary(src)` keeps its signature (Task 9 ↔ settings.ts:478; L1 T5 `link("rt")` calls it); `trayAppPath(exists?)`/`devTrayAppPath(exists?)` (Task 9) match the handoff test rewrite; `resolveFzf` (Task 11 ↔ L1 T7); `__test__.setFallbackNotifier` (Task 11); build.sh env names `RT_DAEMON_BIN RT_VSIX RT_VERSION RT_REQUIRE_DEPS SPARKLE_PUBLIC_ED_KEY RT_BUILD_TOOL` (Task 4 ↔ Task 8); artifact names `mattstack-<ver>.{dmg,zip}` (Tasks 6, 8, 12); `check-bundle.sh --app <path>` (Task 3 ↔ Task 8 ↔ L7 T12); `render-launchagents.sh <prod|dev> <outdir>` (L3 T2 ↔ Task 4); CFBundleVersion `major*1e6+minor*1e3+patch` (Tasks 3/4 ↔ contract `GET /version` example `2008000` ↔ L3 `build: Int(CFBundleVersion) ?? 0` ↔ L7 `make-appcast.sh`).
+
+## Open questions
+
+1. **Appcast host.** CLOSED (ruling R1, cross-plan review): GitHub Release asset via `latest/download` is the host; spec §11 and L3's Info.plist template carry the same URL. Escape hatch only: if the redirect ever misbehaves for Sparkle (or pre-release channels are wanted), GitHub Pages is one constant (`SU_FEED_URL`) + one `actions/deploy-pages` step + the check-bundle assertion.
+2. **CFBundleVersion scheme vs. the contract's example.** CLOSED (cross-plan review §5 #53): the contract example is `"build": 2008000` (`major*1e6+minor*1e3+patch`); L3's `GET /version` returns `Int(CFBundleVersion) ?? 0` (a number); L7's `make-appcast.sh` computes the build with the same formula.
+3. **xcodebuild archive/export vs. build.** Ruling 6 says "build.sh wraps xcodebuild"; this plan wraps `xcodebuild build` and keeps our own inside-out signing (Decision 3). If Matt wants an `.xcarchive` for symbolication, add `-archivePath` to the same command later; signing still stays in build.sh.
+4. **fast-browser artifact.** Bundled from npm `0.1.0-alpha.11` today; L5 may publish a different artifact (e.g. a tarball with the Playwright runtime). When it does, only the `deps.lock` row changes. Its runtime setup (`~/.fast-browser/runtime`, extension side-load) remains L1's `fastbrowser.setup` step.
+5. **Dev flavor Helpers.** The plan bundles Helpers into `mattstack-dev.app` too (same code path, realistic dev testing, ~300 MB extra on disk). If that is unwanted, gate `bundle_helpers` on `IS_DEV=false` and relax the dev assertions in check-bundle.
+6. **`--no-launch` / `--non-interactive` / `--team-of-one`** are L1's flags (L1 T27: `--no-launch` is also implied by `--ci`/`CI=true`); L7's script passes them by default and the workflow passes the zip positionally. Until L1 lands, `--post-install` on a runner still `open`s the app (as today's `test-install` does); harmless, but the clean-room job's daemon checks stay at "warn".
+7. **`rt-tray/*.xcodeproj/` in .gitignore.** CLOSED (cross-plan review §1 row 8): L3 T1 adds the line (L3 regenerates the project from `project.yml`); Task 2 does not.
+8. **Deck's LaunchAgent plist.** CLOSED (cross-plan review §1 row 17): L3 T2 ships `LaunchAgent-deck.plist` and `render-launchagents.sh` renders both plists; Task 4's build.sh copies both, Task 3's check-bundle asserts both. `Contents/Helpers/deck` stays absent until L5; L1's `services.register` requests the deck plist only when the helper is bundled.
+9. **Local `appcast.sh` dry run** needs a throwaway EdDSA key (`generate_keys` writes to the login Keychain and prompts). Task 6 leaves the first real appcast run to Task 15 rather than prompting implementers' keychains.
diff --git a/docs/superpowers/plans/2026-08-21-rt-setup-verbs.md b/docs/superpowers/plans/2026-08-21-rt-setup-verbs.md
new file mode 100644
index 00000000..db104d5c
--- /dev/null
+++ b/docs/superpowers/plans/2026-08-21-rt-setup-verbs.md
@@ -0,0 +1,1269 @@
+# rt setup verbs (L1) 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:** Give mattstack.app (and the terminal) the rt verbs behind the installer: a readiness plan computed from real validators, an NDJSON apply stream of idempotent install steps, team create/join/invite/publish with opaque relay invites, bundled-tool resolution and tagged PATH links, team-scope secrets, services/permissions facades over tray.sock, uninstall, and a thin `rt update` — with `rt verify` running the very same validators.
+
+**Architecture:** Everything new lives in `lib/setup/` (contract types, probes seam, validators, plan composition, apply engine + steps, need protocol, uninstall), `lib/team/` (create/publish/invite/join/members, invite crypto, relay client), `lib/deps/` (bundled-tool resolution + tagged links), `lib/secrets/team-store.ts` (N-recipient team secrets), and thin command modules (`commands/setup.ts`, `team.ts`, `deps.ts`, `repos.ts`, `skills.ts`, `cron.ts`, `tools.ts`, `services.ts`, `uninstall.ts`). Every external effect (exec, fs, fetch, tray.sock, daemon) goes through one injectable `Probes` seam so every unit test runs with fakes; the real seam is assembled once in `lib/setup/probes.ts`. The JSON contract (`2026-08-21-rt-setup-contract.md`) is implemented byte-for-byte by `lib/setup/contract.ts` and pinned by tests.
+
+**Tech Stack:** Bun/TypeScript; `@mattstack/rt-client` settings module (`getSetting`/`setSetting`, suite registry); `lib/secrets/store.ts` (sops/age); WebCrypto AES-256-GCM (Bun) for invite pointers; `gh`/`glab`/`git`/`claude`/`herdr`/`sops` CLIs behind the exec seam; tray.sock over `fetch({unix})`.
+
+**Spec:** `docs/superpowers/specs/2026-08-20-mattstack-app-installer-design.md` (§4.3/4.4/5.2/5.3/5.3b/6/7/9/10/12.3/13) and the binding contract `docs/superpowers/specs/2026-08-21-rt-setup-contract.md`. Settings substrate: `docs/superpowers/specs/2026-08-20-suite-settings-migration.md`, `docs/superpowers/plans/2026-08-20-home-repo-foundation.md`, the in-flight keys wave (`repo-tools-rt50b-wt/docs/superpowers/plans/2026-08-20-rt-keys-wave.md`), and `~/.mattstack/user/local/reply-2026-08-20-settings-lane-to-installer.md`.
+
+**Execution order (cross-plan):** this plan is one of four lanes (L1 this, L3 app shell, L4 release pipeline, L7 clean-room VM); the binding phase/merge order is `docs/superpowers/plans/2026-08-21-cross-plan-review.md` §3. For L1: **Phase A** (no cross-lane dependency) = Tasks 1–4, 6, 9, 13–19. **Phase B** = Task 5 AFTER L4 T1 + T9 merge (consumes `lib/bundle-layout.ts`, `installRtBinary`, `installedTrayAppPath`); Tasks 7, 8, 10, 11, 21 AFTER L1 T5 and L4 T11 (`resolveFzf`) merge; Task 22 implements the `/setup/need` reply protocol exactly as L3 T9 / the contract state it; Tasks 24 and 27 AFTER L4 T9 merge (`bundleRootFromExec`, `installRtBinary`, `legacyUserAppPath`); Task 30 is independent (L4's competing `rt update` edit is dropped); Task 31 AFTER L4 T12 merge (README/docs are L4's). Merge order to main: L4 phase A → L3 T1–T11 → L1 T1–T4, T6, T9, T13–T19 → L4 T4/T5/T8 → L1 T5, T7–T12, T20–T30 → L3 T12–T19 → L7 → L4 T12 → L1 T31–T32 → MATT gates.
+
+## Global Constraints
+
+Copied from the spec's invariants (§2 "Invariants") and the lane rules — every task's requirements include these:
+
+- **No user or employer data ever lands on mattstack-hosted infrastructure.** The shared relay sees ciphertext and timestamps only; pointers are encrypted client-side; no plaintext field is ever posted.
+- **rt owns mechanics, the app owns ceremony; every ceremony has a CLI equivalent.** The wizard never does something `rt setup` cannot.
+- **Honesty over magic:** every checklist row reports what was actually checked; nothing is marked ready on a guess. A probe that cannot run reports `error`/`checking`, never `ready`.
+- **Settings are read and written only through `@mattstack/rt-client`'s settings module** (`getSetting`/`setSetting`/`listTeams` via the `lib/settings/*` barrels); state only through each app's state.db / `~/.mattstack/rt` runtime files. rt never parses a store file by hand.
+- **The installer never copies a user's `~/.claude/settings.json` or hooks; it adds marketplaces and plugins only** (and never edits `~/.claude.json`).
+- **Pure canonical, no compat:** `rt-tray.app`, `com.rt.daemon`, `~/.rt`, brew paths are swept, never honored.
+- **`~/.mattstack` is the home repo** (gitignore is the layer boundary); team clones nest under `~/.mattstack/teams/<slug>/`; runtime under `~/.mattstack/rt/`.
+- **Clean-code comments:** a comment only states a constraint the code cannot show; no narration, no task/ticket references, no review/decision history in source.
+- Contract fidelity: JSON shapes, step ids, statuses, action types, exit codes (`0` ok · `2` user-actionable `{error}` · `1` bug), envelope `{contract:1, at}` exactly as the contract file states. Secrets (tokens, invite codes) travel on stdin or env, never argv.
+- Every new `module:` in `lib/command-tree-def.ts` gets its `lib/module-registry.ts` import + entry **in the same commit** (`lib/__tests__/module-registry.test.ts` enforces it).
+- Tests: bunfig preload repoints HOME (never remove); tests never touch the real HOME, keychain, network, tray.sock, or daemon — every seam is injectable; any spawn passes `env: process.env` (Bun PATH-snapshot gotcha).
+- **NO monitor exists. Implementers run the tests themselves** (`bun test lib commands packages`, `bun x tsc --noEmit`), never wait for results to arrive.
+- Worktree `/Users/matt/Documents/GitHub/repo-tools-l1-wt`, branch `goodwinmattheweric/mat-383-rt-setup-verbs` off `origin/main`. The settings lane lands more on main overnight (keys wave, H2 snapshot daemon, R restore, deck/board/gitq lanes): **rebase onto `origin/main` before every merge** (Task 0 and Task 33 say how), and **rebase onto `origin/main` after L4 T1/T9/T11 merge before starting Tasks 5/7/24/27**. Never touch the main checkout.
+- **File ownership (cross-plan review §1):** `commands/verify.ts`, `commands/update.ts`, `cli.ts`, `commands/post-install.ts` are L1's — no other lane edits them. `README.md` is L4's (L1 does not edit it). `lib/rt-paths.ts`, `lib/dev-mode.ts`, `lib/fzf.ts`, `lib/notifier.ts`, `lib/bundle-layout.ts` are L4's — L1 consumes their exports (`appBundleRoot`, `bundleRootFromExec`, `bundledHelperPath`, `bundledExec`, `RT_BUNDLE_PATH`, `installRtBinary`, `installedTrayAppPath`, `legacyUserAppPath`, `resolveFzf`) and never edits them. `rt-tray/**` is L3's/L4's. Spec and contract files (`docs/superpowers/specs/*`) are edited only in the appspec branch, never committed from this worktree.
+- Commit messages prefixed `MAT-383:`; every commit ends with the trailer `Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>`.
+- ORCHESTRATOR-ONLY tasks (marked) need the live machine (real tray.sock, keychain, gh auth); implementer subagents never run them.
+
+---
+
+## File structure (locked)
+
+```
+lib/setup/
+  contract.ts          Plan/Row/Action/ApplyEvent types, CONTRACT_VERSION, envelope(), finalizePlan(), rowStatusRank
+  errors.ts            UserActionableError + exitUserError(json) → exit 2
+  emit.ts              Emit type; stdout NDJSON emitter; human emitter for TTY
+  probes.ts            Probes seam (exec/fs/fetch/tray/daemon/env) + createRealProbes()
+  intent.ts            setup-intent.json (runtime, 0600): mode + team/join/restore inputs
+  staging.ts           staged secrets before the age key exists (rt/setup-staging/*.json, 0600)
+  state.ts             setup-state.json: what apply installed (plugins, marketplaces, links, editors)
+  requirements.ts      pack-side requirements.jsonc reader (tools/integrations/why)
+  integrations.ts      per-integration connect/validate table (fields, secret domain/key, validator)
+  permissions.ts       GET /permissions → perm.* rows
+  validators/mac.ts    perm.*, tool.macos, tool.clt, tool.path
+  validators/rt-health.ts  tool.rt, tool.legacy-dirs, tool.intercepts, tool.fzf, tool.app, tool.extension, tool.shell, tool.daemon
+  validators/tools.ts  tool.herdr, tool.claude, tool.fast-browser, tool.editor, tool.chrome, tool.mission-control, team tools, pack.*
+  validators/accounts.ts account.* rows (+ owner-once slack-app, switchboard)
+  validators/access.ts access.* rows
+  plan.ts              composePlan(): groups in order, merges permissions, finalizePlan
+  need.ts              awaitNeed(): the need-event wait over tray.sock
+  apply.ts             runApply(): engine (plan event, --from resume, stop-on-fail, done)
+  steps/index.ts       ordered StepDef[] (contract step ids)
+  steps/home.ts steps/team.ts steps/secrets.ts steps/path.ts steps/settings.ts steps/repos.ts
+  steps/services.ts steps/deck.ts steps/skills.ts steps/plugins.ts steps/tools.ts steps/verify.ts
+  uninstall.ts         computeUninstallActions() + runUninstall()
+  slack-app.ts         manifest generation + app creation via Slack API
+  tools-install.ts     brew|vendor|apple-clt installs; tool-owned setup wrappers
+  __tests__/fakes.ts   fakeProbes(), FakeTray, recorded exec scripts
+lib/deps/
+  resolve.ts           appBundlePath() (= L4 appBundleRoot), bundledToolPath(), bundledToolExec(), userCopyOnPath(), resolveTool()
+  links.ts             tagged links (symlink or "# mattstack-link:" wrapper): isOurLink(), link(), unlink(), reconcile(), DEFAULT_EXPOSED
+lib/team/
+  slug.ts              slugify()
+  invite-crypto.ts     AES-256-GCM seal/open, code encode/decode (base32 crockford)
+  relay-client.ts      POST/GET/redeem/reply/DELETE /v1/invites
+  create.ts            scaffold team zone + remote (+ gh repo create)
+  publish.ts           push / set-url
+  invite.ts            mint: pointer, forge grant, roster, code, paste block
+  join.ts              dry-run + redeem + clone + reply blob + peering
+  members.ts           sync (collect reply keys → recipients) / remove (ACL revoke + rotate)
+  forge.ts             forge grant/revoke via gh/glab api
+lib/secrets/team-store.ts   teams/<slug>/mattstack/secrets/<domain>.json, N-recipient .sops.yaml
+commands/setup.ts commands/team.ts commands/deps.ts commands/repos.ts commands/skills.ts
+commands/cron.ts commands/tools.ts commands/services.ts commands/uninstall.ts
+commands/update.ts (rewritten thin) commands/verify.ts (refactored) commands/post-install.ts (entry only)
+lib/daemon-client.ts (+ traySocketPath(), trayRequest())
+lib/command-tree-def.ts + lib/module-registry.ts (every new module)
+```
+
+## Conventions every task follows
+
+- Verbs that emit JSON accept `--json`; without it they print human lines via `lib/tui.ts` colors. JSON results are `envelope({...})`. Streaming verbs write one `JSON.stringify(ev)` per line to stdout, nothing else on stdout.
+- A user-actionable failure throws `UserActionableError(code, message, extra?)`; the command's top level catches it and calls `exitUserError(err, json)` → prints `envelope({ error: { code, message, ...extra } })` (JSON) or `rt <verb>: <message>` (human) and `process.exit(2)`. Anything else propagates (exit 1 via the CLI crash seam).
+- Command functions take `(args: string[], ctx: CommandContext = {}, deps = realDeps())` so tests call them directly with fakes; tests assert on a captured `print` seam, never on console.
+- Secrets and invite codes: read from stdin (`readStdinJson()` in `lib/setup/probes.ts`) or a no-echo prompt (reuse `promptSecretValue` pattern from `commands/secrets.ts`, exported from a shared helper `lib/setup/prompt-secret.ts` created in Task 1).
+
+---
+
+### Task 0 (ORCHESTRATOR-ONLY): worktree + branch
+
+- [ ] `cd /Users/matt/Documents/GitHub/repo-tools && git fetch origin && git worktree add -b goodwinmattheweric/mat-383-rt-setup-verbs /Users/matt/Documents/GitHub/repo-tools-l1-wt origin/main && cd /Users/matt/Documents/GitHub/repo-tools-l1-wt && bun install`
+- [ ] Baseline: `bun x tsc --noEmit` → 0 errors; `bun test lib commands packages` green. Record which of these are already on main (it changes overnight): `grep -n '"rt.cron"\|"rt.repoTracking"' -A6 packages/rt-client/src/settings/registry-defs.ts | grep migrated`, `ls commands/restore.ts lib/daemon/snapshot* 2>/dev/null`. Steps that depend on them (Task 21 `cron install`, Task 25 `home.restore`) carry honest guards, so nothing blocks on the answer.
+- [ ] Rebase rule for every later merge checkpoint: `git fetch origin && git rebase origin/main`, rerun both gates, fix conflicts in this branch only.
+
+---
+
+### Task 1: Contract types, envelope, errors, emitters, secret prompt
+
+**Files:**
+- Create: `lib/setup/contract.ts`, `lib/setup/errors.ts`, `lib/setup/emit.ts`, `lib/setup/prompt-secret.ts`
+- Test: `lib/setup/__tests__/contract.test.ts`, `lib/setup/__tests__/emit.test.ts`
+- Modify: `commands/secrets.ts` (import `promptSecretValue` from the new helper instead of its private copy; behavior unchanged)
+
+**Interfaces:**
+- Produces (all later tasks consume):
+
+```ts
+// lib/setup/contract.ts
+export const CONTRACT_VERSION = 1 as const;
+export type RowStatus = "ready" | "missing" | "invalid" | "needs-you" | "checking" | "skipped" | "error";
+export type RowKind = "permission" | "tool" | "account" | "access" | "info";
+export type Recheck = "on-activate" | "on-change" | "manual";
+export type GroupId = "mac" | "accounts" | "access" | "tools";
+export type Integration = "github" | "gitlab" | "linear" | "slack" | "switchboard" | "sdm" | "doppler" | "ldcli";
+export interface ConnectField { name: string; label: string; secret: boolean; hint?: string }
+export type Action =
+  | { type: "open-settings"; label: string; target: "fda" | "login-items" | "notifications" | "keyboard" }
+  | { type: "request-permission"; label: string; which: "notifications" }
+  | { type: "connect"; label: string; integration: Integration; fields: ConnectField[]; alternatives?: { id: string; label: string }[] }
+  | { type: "oauth"; label: string; integration: Integration; verb: string[] }
+  | { type: "owner-once"; label: string; integration: Integration; fields: ConnectField[] }
+  | { type: "install"; label: string; tool: string; via: "brew" | "vendor" | "apple-clt" | "bundled-link" }
+  | { type: "link-bundled"; label: string; tool: string }
+  | { type: "steps"; label: string; steps: string[] }
+  | { type: "open-url"; label: string; url: string }
+  | { type: "run"; label: string; verb: string[] };
+export interface Row { id: string; kind: RowKind; title: string; why: string; required: boolean; optionalNote: string | null; status: RowStatus; detail: string; action: Action | null; recheck: Recheck }
+export interface Group { id: GroupId; title: string; rows: Row[] }
+export type TeamMode = "join" | "create" | "restore" | "none";
+export interface TeamRef { slug: string; name: string; mode: TeamMode }
+export interface Plan { contract: 1; at: string; team: TeamRef; groups: Group[]; canInstall: boolean; requiredMissing: string[] }
+export const GROUP_TITLES: Record<GroupId, string> = { mac: "Your Mac", accounts: "Accounts", access: "Access", tools: "Tools" };
+export type StepKind = "rt" | "app" | "privileged";
+export type StepState = "pending" | "running" | "done" | "failed" | "skipped";
+export const STEP_IDS = ["home.init","home.restore","team.create","team.join","secrets.write","path.link","intercepts.install","settings.seed","repos.clone","services.register","proxy.install","deck.managed","skills.materialize","board.keys","cron.triage","plugins.install","fastbrowser.setup","herdr.integration","extension.install","services.start","snapshot.push","verify"] as const;
+export type StepId = (typeof STEP_IDS)[number];
+export type NeedRequest =
+  | { type: "app-register-services"; plists: string[] }
+  | { type: "app-unregister-services"; plists: string[] }
+  | { type: "app-privileged"; op: "proxy-install" | "proxy-remove" };
+/** Uninstall streams the same event shapes with these ids (contract §uninstall: "NDJSON like apply"). */
+export type UninstallActionId = "services.unregister" | "deck.managed-remove" | "proxy.remove" | "path.unlink" | "shell.remove" | "extension.uninstall" | "plugins.uninstall" | "data" | "app.trash";
+export type EventId = StepId | UninstallActionId;
+export type ApplyEvent =
+  | { event: "plan"; steps: { id: EventId; title: string; kind: StepKind }[] }
+  | { event: "step"; id: EventId; state: StepState; detail?: string; remedy?: string }
+  | { event: "log"; id: EventId; line: string }
+  | { event: "need"; id: EventId; request: NeedRequest }
+  | { event: "done"; ok: boolean; failedStep?: EventId };
+export function envelope<T extends object>(body: T, now: Date = new Date()): T & { contract: 1; at: string } {
+  return { contract: CONTRACT_VERSION, at: now.toISOString(), ...body };
+}
+export function row(r: Omit<Row, "optionalNote" | "action" | "recheck"> & Partial<Pick<Row, "optionalNote" | "action" | "recheck">>): Row {
+  return { optionalNote: null, action: null, recheck: "on-change", ...r };
+}
+/** Install enables only when every required row is ready; requiredMissing lists the others in group order. */
+export function finalizePlan(team: TeamRef, groups: Group[], now: Date = new Date()): Plan {
+  const requiredMissing = groups.flatMap((g) => g.rows.filter((r) => r.required && r.status !== "ready").map((r) => r.id));
+  return envelope({ team, groups, canInstall: requiredMissing.length === 0, requiredMissing }, now);
+}
+```
+`NeedRequest` keeps both uninstall types: L3's NeedBroker must handle `app-unregister-services` and `app-privileged` with `op:"proxy-remove"` (tracked in the cross-plan review §5 #12-13 / #24; the contract lists both).
+
+```ts
+// lib/setup/errors.ts
+export class UserActionableError extends Error {
+  constructor(public readonly code: string, message: string, public readonly extra: Record<string, unknown> = {}) { super(message); }
+}
+export function userErrorPayload(err: UserActionableError, now = new Date()) {
+  return envelope({ error: { code: err.code, message: err.message, ...err.extra } }, now);
+}
+/** Prints the contract's exit-2 payload (JSON) or a one-line human message, then exits 2. */
+export function exitUserError(err: UserActionableError, json: boolean, verb: string, print: (s: string) => void = console.log): never {
+  print(json ? JSON.stringify(userErrorPayload(err)) : `rt ${verb}: ${err.message}`);
+  process.exit(2);
+}
+```
+
+```ts
+// lib/setup/emit.ts
+export type Emit = (ev: ApplyEvent) => void;
+export function createNdjsonEmitter(write: (line: string) => void = (l) => process.stdout.write(l)): Emit {
+  return (ev) => write(`${JSON.stringify(ev)}\n`);
+}
+/** TTY rendering of the same stream: one line per step transition, log lines dimmed. */
+export function createHumanEmitter(print: (s: string) => void = console.log): Emit {
+  const glyph: Record<StepState, string> = { pending: "·", running: "…", done: "✓", failed: "✗", skipped: "–" };
+  return (ev) => {
+    if (ev.event === "plan") print(`  ${ev.steps.length} steps`);
+    else if (ev.event === "step") print(`  ${glyph[ev.state]} ${ev.id}${ev.detail ? `  ${ev.detail}` : ""}${ev.remedy ? `\n      → ${ev.remedy}` : ""}`);
+    else if (ev.event === "log") print(`      ${ev.line}`);
+    else if (ev.event === "need") print(`  ? ${ev.id} — waiting for mattstack.app (${ev.request.type})`);
+    else print(ev.ok ? "  ✓ done" : `  ✗ stopped at ${ev.failedStep}`);
+  };
+}
+```
+
+```ts
+// lib/setup/prompt-secret.ts
+export function promptSecretValue(message: string): Promise<string>  // moved verbatim from commands/secrets.ts (raw-mode no-echo; rejects when !isTTY)
+export async function readStdinJson<T>(): Promise<T | null>           // reads all of stdin, JSON.parse; null on empty; throws UserActionableError("bad-stdin") on parse failure
+```
+
+- [ ] **Step 1: Failing tests.** `contract.test.ts`: `finalizePlan` with rows `[required ready, required missing, optional missing]` → `canInstall:false`, `requiredMissing` exactly the required-missing id; all-required-ready → `canInstall:true`, `requiredMissing:[]`; `envelope({x:1}, new Date("2026-08-21T04:00:00Z"))` deep-equals `{contract:1, at:"2026-08-21T04:00:00.000Z", x:1}`; `row({...})` fills `optionalNote:null, action:null, recheck:"on-change"`; `STEP_IDS` equals the contract's 22 ids in order (literal array in the test). `emit.test.ts`: the ndjson emitter writes exactly one line per event and `JSON.parse` round-trips; the human emitter prints a `→ remedy` line for a failed step.
+- [ ] **Step 2:** `bun test lib/setup/` → fails (module not found).
+- [ ] **Step 3:** Implement the four files as specified; move `promptSecretValue` out of `commands/secrets.ts` (keep `CTRL_C`/`DEL` handling identical) and import it back.
+- [ ] **Step 4:** `bun test lib/setup/ commands/` green; `bun x tsc --noEmit` 0.
+- [ ] **Step 5: Commit** `MAT-383: setup contract types, envelope, error + NDJSON seams`
+
+---
+
+### Task 2: Probes seam + tray client
+
+**Files:**
+- Create: `lib/setup/probes.ts`, `lib/setup/__tests__/fakes.ts`
+- Modify: `lib/daemon-client.ts` (add `traySocketPath()`, `trayRequest()`)
+- Test: `lib/setup/__tests__/probes.test.ts`, `lib/__tests__/daemon-client-tray.test.ts`
+
+**Interfaces:**
+- Produces:
+
+```ts
+// lib/daemon-client.ts additions
+/** RT_APP_SOCKET (set by the app when it spawns rt) wins over the default tray.sock path. */
+export function traySocketPath(): string { return process.env.RT_APP_SOCKET || TRAY_SOCK_PATH; }
+export interface TrayReply<T = unknown> { status: number; json: T | null }   // status 0 = socket absent / connection failed / timed out
+export async function trayRequest<T = unknown>(path: string, init: { method: "GET" | "POST"; body?: unknown; timeoutMs?: number } = { method: "GET" }): Promise<TrayReply<T>>
+export type TrayClient = typeof trayRequest;
+```
+
+```ts
+// lib/setup/probes.ts
+export interface ExecResult { code: number; stdout: string; stderr: string }
+export interface Probes {
+  /** Never throws: a missing binary yields code 127 with stderr "ENOENT: <argv0>"; timeout yields 124. `inherit` hands the child the TTY (interactive logins) — stdout/stderr then come back empty. */
+  exec(argv: string[], opts?: { cwd?: string; timeoutMs?: number; env?: Record<string, string>; input?: string; inherit?: boolean }): Promise<ExecResult>;
+  exists(path: string): boolean;
+  readFile(path: string): string | null;
+  readDir(path: string): string[];
+  readlink(path: string): string | null;           // null when not a symlink / missing
+  writeFile(path: string, content: string, mode?: number): void;
+  removeFile(path: string): void;                  // best-effort
+  removeDir(path: string): void;                   // rm -rf semantics, best-effort
+  symlink(target: string, path: string): void;
+  mkdirp(path: string, mode?: number): void;
+  /** Never throws: network failure yields status 0, body "", headers {}. Header names are lowercased. */
+  fetch(url: string, init?: { method?: string; headers?: Record<string, string>; body?: string; timeoutMs?: number }): Promise<{ status: number; body: string; headers: Record<string, string> }>;
+  tray: TrayClient;
+  daemon(cmd: string, payload?: Record<string, unknown>, timeoutMs?: number): Promise<DaemonResponse | null>;
+  env: Record<string, string | undefined>;
+  home: string;
+  now(): Date;
+  /** Spawns this same rt (process.execPath) with args; stdin from `input`. Never throws. */
+  runRt(args: string[], opts?: { input?: string; timeoutMs?: number }): Promise<ExecResult>;
+}
+export function createRealProbes(): Probes
+```
+
+```ts
+// lib/setup/__tests__/fakes.ts
+export type ExecScript = (argv: string[], opts?: Parameters<Probes["exec"]>[1]) => ExecResult | Promise<ExecResult>;
+export interface FakeProbesOpts { files?: Record<string, string>; dirs?: Record<string, string[]>; links?: Record<string, string>; exec?: ExecScript; fetch?: Probes["fetch"]; tray?: TrayClient; daemon?: Probes["daemon"]; env?: Record<string, string>; home?: string; now?: Date; runRt?: Probes["runRt"] }
+export function fakeProbes(opts?: FakeProbesOpts): Probes & { calls: { exec: string[][]; fetch: string[]; tray: string[]; writes: Record<string, string>; removed: string[]; symlinks: Record<string, string> } }
+export function fakeTray(routes: Record<string, (body?: unknown) => { status: number; json: unknown }>): TrayClient   // key "GET /permissions"
+export const ok = (stdout = ""): ExecResult => ({ code: 0, stdout, stderr: "" });
+export const missing = (bin: string): ExecResult => ({ code: 127, stdout: "", stderr: `ENOENT: ${bin}` });
+```
+
+- [ ] **Step 1: Failing tests.** `probes.test.ts`: `createRealProbes().exec(["/nonexistent/bin"])` resolves `{code:127}` (no throw); `exec(["sh","-c","echo hi"])` → `{code:0, stdout:"hi\n"}`; `exec(["sh","-c","sleep 5"],{timeoutMs:100})` → code 124; `fetch("http://127.0.0.1:1")` → `{status:0}`; `fakeProbes({files:{"/a":"x"}}).readFile("/a")==="x"`, `.exists("/b")===false`, `.calls.exec` records argv. `daemon-client-tray.test.ts`: with `process.env.RT_APP_SOCKET="/nonexistent.sock"`, `trayRequest("/health")` → `{status:0,json:null}`; `traySocketPath()` returns the env value; unset → ends with `/.mattstack/rt/tray.sock`.
+- [ ] **Step 2:** run, fail.
+- [ ] **Step 3: Implement.** Real `exec` uses `Bun.spawn(argv, { cwd, env: { ...process.env, ...opts?.env }, stdin: input ? "pipe" : "ignore", stdout: "pipe", stderr: "pipe" })` in a try/catch (ENOENT → 127), timer kill → 124. `trayRequest` mirrors `trayQuery` but with `body: JSON.stringify(body)` + `Content-Type: application/json`, parses JSON when the response has a body (tolerate non-JSON → `json:null`), catches to `{status:0,json:null}`. `runRt` spawns `process.execPath` with `env: process.env` and `RT_SKIP_SETUP: "1"`.
+- [ ] **Step 4:** green; tsc 0. **Step 5: Commit** `MAT-383: probes seam + tray.sock request client`
+
+---
+
+### Task 3: Setup intent, staged secrets, setup state
+
+**Files:**
+- Create: `lib/setup/intent.ts`, `lib/setup/staging.ts`, `lib/setup/state.ts`
+- Test: `lib/setup/__tests__/intent.test.ts`, `lib/setup/__tests__/staging.test.ts`, `lib/setup/__tests__/state.test.ts`
+
+**Interfaces:**
+- Produces:
+
+```ts
+// lib/setup/intent.ts  — ~/.mattstack/rt/setup-intent.json (0600; runtime, gitignored)
+export interface InvitePointer { v: 1; team: string; name: string; remote: string; owner: string; forge: string; createdAt: string }
+export interface SetupIntent {
+  v: 1; at: string; mode: "create" | "join" | "restore";
+  team?: { slug: string; name: string; remote: string; others: boolean };          // create
+  join?: { id: string; keyB64: string; pointer: InvitePointer };                    // join (pointer already decrypted at dry-run)
+  restore?: { homeRepo: string };                                                   // restore (age key is never persisted)
+}
+export function intentPath(home: string): string                                     // join(home, ".mattstack", "rt", "setup-intent.json")
+export function readIntent(p: Pick<Probes, "readFile" | "home">): SetupIntent | null // null when absent or unparseable
+export function writeIntent(p: Pick<Probes, "writeFile" | "mkdirp" | "home">, intent: SetupIntent): void  // mode 0o600
+export function clearIntent(p: Pick<Probes, "removeFile" | "home">): void
+export function teamRefFromIntent(intent: SetupIntent | null, teams: string[]): TeamRef
+//   create → {slug, name, mode:"create"}; join → {slug: pointer.team, name: pointer.name, mode:"join"}; restore → {slug: teams[0] ?? "", name: teams[0] ?? "", mode:"restore"};
+//   null → teams.length ? {slug: teams[0], name: teams[0], mode:"none"} : {slug:"", name:"", mode:"none"}  (multi-team: first alphabetical; picker is a §14 follow-up)
+```
+
+```ts
+// lib/setup/staging.ts — ~/.mattstack/rt/setup-staging/<domain>.json (0600), consumed by the secrets.write step
+export function stagingDir(home: string): string
+export function stageSecret(p: Probes, domain: string, key: string, value: string): void      // merge into the domain file, 0600
+export function listStaged(p: Probes): { domain: string; key: string }[]                      // names only
+export function drainStaged(p: Probes, write: (domain: string, key: string, value: string) => Promise<void>): Promise<number>  // writes each, removes the file after ALL keys of that domain succeeded; returns count
+```
+
+```ts
+// lib/setup/state.ts — ~/.mattstack/rt/setup-state.json
+export interface SetupState { v: 1; marketplaces: string[]; plugins: string[]; links: string[]; extensionEditors: string[]; lastApplyAt?: string }
+export function readSetupState(p: Pick<Probes, "readFile" | "home">): SetupState                  // defaults to empty arrays
+export function updateSetupState(p: Pick<Probes, "readFile" | "writeFile" | "mkdirp" | "home">, patch: (s: SetupState) => SetupState): SetupState
+```
+
+- [ ] **Step 1: Failing tests** using `fakeProbes`: write→read round-trip of each shape; `writeIntent` records mode 0o600 (`calls.writes` plus a `modes` record — add `modes: Record<string, number>` to the fake's calls); `readIntent` on garbage → null; `teamRefFromIntent` table (5 cases above); `stageSecret` twice in one domain merges keys; `drainStaged` with a `write` that throws on the second key leaves the domain file in place and rethrows; `updateSetupState` dedupes arrays (`[...new Set]`).
+- [ ] **Step 2:** fail. **Step 3:** implement. **Step 4:** green; tsc 0.
+- [ ] **Step 5: Commit** `MAT-383: setup intent, staged secrets, setup state`
+
+---
+
+### Task 4: Pack requirements reader + integrations table
+
+**Files:**
+- Create: `lib/setup/requirements.ts`, `lib/setup/integrations.ts`
+- Test: `lib/setup/__tests__/requirements.test.ts`, `lib/setup/__tests__/integrations.test.ts`
+
+**Interfaces:**
+- Produces:
+
+```ts
+// lib/setup/requirements.ts — pack-side requirements.jsonc: teams/<slug>/**/requirements.jsonc (depth ≤ 4, e.g. mattstack/packs/<pack>/requirements.jsonc)
+export interface ToolRequirement { name: string; floor?: string; why: string; install?: { brew?: string; url?: string }; connect?: { integration: Integration } | { verb: string[]; label: string }; optional?: boolean }
+export interface PackRequirements { pack: string; tools: ToolRequirement[]; integrations: Integration[]; chrome?: { required: boolean; signedIntoApp?: string } ; workType?: string }
+export function readPackRequirements(p: Pick<Probes, "readDir" | "readFile" | "exists" | "home">, teamSlug: string): PackRequirements[]   // [] when none; a malformed file yields one entry {pack, tools:[], integrations:[], error} — add `error?: string`
+export function parseRequirements(packName: string, text: string): PackRequirements   // stripJsonc (lib/jsonc.ts) + shape validation; unknown integration names dropped with error text
+```
+
+```ts
+// lib/setup/integrations.ts
+export interface IntegrationDef {
+  id: Integration; title: string; why: (teamHost: string | null) => string;
+  fields: ConnectField[]; alternatives?: { id: "use-gh"; label: string }[];
+  secret: { domain: "rt" | "board"; key: string };       // where connect stores the credential (user-scope secrets)
+  /** Calls the API with the token; ready only when the token can see the team's resources. Network via probes.fetch/exec only. */
+  validate(p: Probes, token: string, ctx: { host: string | null; team: { slug: string; remote: string | null } }): Promise<{ status: "ready" | "invalid"; detail: string; scopesSeen: string[] }>;
+}
+export const INTEGRATIONS: Record<Integration, IntegrationDef>
+export function integrationDef(id: string): IntegrationDef   // throws UserActionableError("unknown-integration") on a bad id
+```
+
+Table (pin in code; all network through `p.fetch` or `p.exec`):
+
+| id | fields | secret | validate |
+|---|---|---|---|
+| github | token (secret; hint "repo, read:org") ; alternatives `use-gh` | rt.githubToken | `GET https://api.github.com/user` with `Authorization: Bearer`; scopes from the `x-oauth-scopes` response header; if `ctx.team.remote` is a GitHub URL, `GET /repos/<owner>/<repo>` must be 200 → ready, 404 → invalid "token can't see <owner>/<repo>" |
+| gitlab | token (secret; hint "read_api, read_user") | rt.gitlabToken | `GET https://<host>/api/v4/user` with `PRIVATE-TOKEN`; then `GET /api/v4/personal_access_tokens/self` → scopes; team project from remote → `GET /api/v4/projects/<urlencoded path>` 200 → ready |
+| linear | apiKey (secret; hint "lin_api_…") | rt.linearApiKey | GraphQL `{ viewer { id } teams { nodes { key } } }`; ready when `mattstack.integrations.linear.teamKey` (passed in ctx as `linearTeamKey`) is among teams (or no teamKey declared → ready "viewer ok") |
+| slack | (oauth; no fields) | board.slackUserToken | `POST https://slack.com/api/auth.test` with Bearer → `ok:true` → ready (team name in detail) |
+| switchboard | token (secret) | rt.switchboardToken | `GET <url>/health` with Bearer → 200 |
+| sdm | email (not secret) | rt.sdmEmail | `p.exec(["sdm","status"])` code 0 and stdout contains the email → ready; 127 → invalid "sdm not installed" |
+| doppler | (no fields; connect = run `doppler login`) | — | `p.exec(["doppler","me","--json"])` code 0 → ready |
+| ldcli | (no fields; connect = run `ldcli login`) | — | `p.exec(["ldcli","config","--list"])` code 0 → ready |
+
+- [ ] **Step 1: Failing tests.** `parseRequirements("claimview", '{ "tools":[{"name":"doppler","floor":"3.0.0","why":"secrets","install":{"brew":"dopplerhq/cli/doppler"},"connect":{"integration":"doppler"}}], "integrations":["gitlab","linear","bogus"] }')` → one tool, integrations `["gitlab","linear"]`, `error` mentions `bogus`; `readPackRequirements` with fake dirs `teams/claimview/mattstack/packs/claimview/requirements.jsonc` finds it, and with none returns `[]`. `integrations.test.ts`: gitlab `validate` with a fake fetch returning 200 for `/user`, `{scopes:["read_api"]}` for `/personal_access_tokens/self`, 404 for the project → `{status:"invalid", detail: contains "can't see", scopesSeen:["read_api"]}`; github 200/200 → ready; linear teamKey mismatch → invalid; every def has non-empty `why(null)`.
+- [ ] **Step 2:** fail. **Step 3:** implement. **Step 4:** green; tsc 0.
+- [ ] **Step 5: Commit** `MAT-383: pack requirements reader + integrations table`
+
+---
+
+### Task 5: deps — bundled tool resolution + tagged links + `rt deps`
+
+**AFTER L4 T1 + L4 T9 merge** (rebase onto `origin/main` first): this task consumes `lib/bundle-layout.ts` (`appBundleRoot`, `bundleRootFromExec`, `bundledHelperPath`, `bundledExec`, `RT_BUNDLE_PATH`) and `installRtBinary` (`lib/dev-mode.ts`) / `installedTrayAppPath` (`lib/rt-paths.ts`) — L4 owns those files; L1 never edits them.
+
+**Files:**
+- Create: `lib/deps/resolve.ts`, `lib/deps/links.ts`, `commands/deps.ts`
+- Test: `lib/deps/__tests__/resolve.test.ts`, `lib/deps/__tests__/links.test.ts`, `commands/__tests__/deps.test.ts`
+- Modify: `lib/command-tree-def.ts` (new `deps` node), `lib/module-registry.ts` (`./commands/deps.ts`), `lib/daemon.ts` (boot: `await reconcileLinks(createRealProbes())` inside a try/catch that logs at warn — one call next to the existing boot reconcile; and, per the plist-PATH ruling, prepend `<appBundleRoot()>/Contents/Helpers` and `$HOME/.local/bin` to `process.env.PATH` at daemon boot — the agent plist's `EnvironmentVariables.PATH` is the static `/usr/bin:/bin:/usr/sbin:/sbin`, so rt derives the bundle dir from its own execPath; children spawned with `env: process.env` inherit it)
+
+**Interfaces:**
+- Consumes (L4 T1 `lib/bundle-layout.ts`): `appBundleRoot(exists?)`, `bundleRootFromExec(execPath?)`, `bundledHelperPath(name, root?, exists?)`, `bundledExec(name, root?, exists?)` (argv prefix from deps.lock — e.g. fast-browser = `[<root>/Contents/Helpers/node/bin/node, <root>/Contents/Helpers/fast-browser/bin/fast-browser.mjs]`), `RT_BUNDLE_PATH` (`Contents/MacOS/rt`); (L4 T9) `installRtBinary(src)` (atomic link-then-rename of `~/.local/bin/rt`).
+- Produces:
+
+```ts
+// lib/deps/resolve.ts  — no HELPER_TOOLS list: which helpers exist comes from the bundle's deps.lock via bundle-layout
+export function appBundlePath(p: Pick<Probes, "exists" | "home">): string | null      // = appBundleRoot(p.exists) (bundle rt runs from, else installed active flavor — which already reads mattstack.appPath)
+export function bundledToolPath(p: Pick<Probes, "exists" | "home">, tool: string): string | null   // tool === "rt" ? join(root, RT_BUNDLE_PATH) : bundledHelperPath(tool, root, p.exists); null when no app or absent
+export function bundledToolExec(p: Pick<Probes, "exists" | "home">, tool: string): string[] | null // tool === "rt" ? [join(root, RT_BUNDLE_PATH)] : bundledExec(tool, root, p.exists)
+export function userCopyOnPath(p: Pick<Probes, "exists" | "readlink" | "env" | "home">, tool: string): string | null  // first PATH entry holding an executable `tool` that is NOT our tagged link
+export interface ToolResolution { tool: string; bundled: string | null /* first exec entry / path, for display */; exec: string[] | null /* bundled exec argv prefix, else [userCopy], else null */; userCopy: string | null; linked: boolean; chosen: string | null /* bundled ?? userCopy */ }
+export function resolveTool(p: Probes, tool: string): ToolResolution
+```
+
+```ts
+// lib/deps/links.ts
+export const DEFAULT_EXPOSED = ["rt","fast-browser","gitq","deck"] as const;
+export const LINK_TAG = "# mattstack-link:";
+export function linkPath(home: string, tool: string): string                         // ~/.local/bin/<tool>
+/** A link is ours iff it is a symlink whose target lies inside the app bundle (Contents/Helpers or Contents/MacOS), OR a regular file whose second line starts with `# mattstack-link:` (the tagged wrapper for multi-argv tools). */
+export function isOurLink(p: Pick<Probes, "readlink" | "readFile" | "exists" | "home">, tool: string): boolean
+export type LinkOutcome = { ok: true; path: string; state: "linked" | "already" } | { ok: false; reason: "no-bundle" | "user-copy" | "dev-mode-owns-rt" | "occupied"; detail: string }
+export function link(p: Probes, tool: string, opts?: { force?: boolean }): LinkOutcome
+//  exec = bundledToolExec(p, tool) (null → no-bundle); exec.length === 1 → symlink (for "rt": installRtBinary(target) — atomic link-then-rename — never a bare p.symlink); exec.length > 1 → write the tagged wrapper
+//  `#!/bin/sh\n# mattstack-link: <tool>\nexec "<exec0>" "<exec1…>" "$@"\n` (mode 0755); refuses "user-copy" unless force; rt in dev mode → dev-mode-owns-rt; a non-ours regular file at the path → occupied
+export function unlink(p: Probes, tool: string): { removed: boolean }                       // only removes our links (symlink or tagged wrapper)
+export function reconcile(p: Probes): { removed: string[]; kept: string[] }                 // every our-link (either form) whose tool now has a user copy elsewhere on PATH is removed (auto-unlink)
+```
+
+`commands/deps.ts`: `depsResolve(args)` → `rt deps resolve <tool> --json` prints `envelope(resolveTool(...))`; `depsLink(args)` → `rt deps link <tool> [--force] [--json]`; `depsUnlink(args)`; `depsReconcile(args)` → `rt deps reconcile [--json]`. Tree: `deps: { description: "Bundled tools: resolve by absolute path, expose on PATH with tagged links", subcommands: { resolve, link, unlink, reconcile } }` each with `module: "./commands/deps.ts"`, fn names as above, `args` with Tool text + `--json` boolean (+ `--force` on link).
+
+- [ ] **Step 1: Failing tests.** `resolve.test.ts`: with HOME store seeded `mattstack.appPath` → `/Applications/mattstack.app` (use `setSetting("mattstack.appPath","/Applications/mattstack.app","machine")` against the test HOME), a fake `Contents/Resources/deps.lock` listing `gh` (`bundlePath: Contents/Helpers/gh`, `exec: [Contents/Helpers/gh]`, `status: bundled`) and `fast-browser` (`exec: [Contents/Helpers/node/bin/node, Contents/Helpers/fast-browser/bin/fast-browser.mjs]`), and fake `exists` true for those paths → `bundledToolPath(p,"gh")` equals `/Applications/mattstack.app/Contents/Helpers/gh`; `"rt"` → `.../Contents/MacOS/rt`; `bundledToolExec(p,"fast-browser")` is the two-entry argv; `resolveTool(p,"fast-browser").exec` equals it and `.bundled` is its first entry; `userCopyOnPath` with `env.PATH="/opt/homebrew/bin:/Users/x/.local/bin"`, `exists("/opt/homebrew/bin/gh")` → returns that; when the only hit is `~/.local/bin/gh` and `readlink` says it points into the bundle → null. `links.test.ts`: `link("gh")` creates a symlink target=bundled path (assert `calls.symlinks`); `link("rt")` goes through `installRtBinary` (assert the atomic `<dest>.new` → rename, via an injectable seam), never a bare symlink; `link("fast-browser")` writes the tagged wrapper file (second line `# mattstack-link: fast-browser`, exec line quoting both argv entries, mode 0755) and `isOurLink(p,"fast-browser")` is true for it; second call → `already`; `link("gh")` when a user copy exists → `{ok:false, reason:"user-copy"}`; with `{force:true}` → links; `link("rt")` when `~/.local/bin/rt` starts with `#!` and has no `# mattstack-link:` second line → `dev-mode-owns-rt` (fake `readFile`); `unlink` removes both forms; `reconcile` removes the gh link once `/opt/homebrew/bin/gh` appears, keeps `rt`. `deps.test.ts`: `depsResolve(["gh","--json"])` prints an envelope with `contract:1` and an `exec` array.
+- [ ] **Step 2:** fail. **Step 3:** implement; tree + registry in the same change. **Step 4:** green (incl. `lib/__tests__/module-registry.test.ts`); tsc 0.
+- [ ] **Step 5: Commit** `MAT-383: rt deps — bundled resolution, tagged links, reconcile`
+
+---
+
+### Task 6: Validators — mac group + permissions merge
+
+**Files:**
+- Create: `lib/setup/permissions.ts`, `lib/setup/validators/mac.ts`
+- Test: `lib/setup/__tests__/permissions.test.ts`, `lib/setup/__tests__/validators-mac.test.ts`
+
+**Interfaces:**
+- Produces:
+
+```ts
+// lib/setup/permissions.ts
+export interface PermissionsReply { fda: { status: "granted"|"denied"|"unknown"; detail?: string }; notifications: { status: "authorized"|"denied"|"notDetermined"|"provisional" }; loginItems: { status: "enabled"|"requiresApproval"|"notRegistered"|"notFound" } }
+export async function fetchPermissions(tray: TrayClient): Promise<PermissionsReply | null>   // GET /permissions; null when status !== 200
+export function permissionRows(reply: PermissionsReply | null, daemonTcc: { blocked: number; total: number } | null): Row[]
+```
+Row mapping (ids `perm.fda`, `perm.login-items`, `perm.notifications`; `kind:"permission"`, `recheck:"on-activate"`):
+- fda: granted → ready "Granted"; denied → needs-you "Not granted", action `{type:"open-settings", label:"Open Full Disk Access Settings…", target:"fda"}`; unknown → needs-you "Could not verify", same action. reply null: daemonTcc `{blocked:0,total>0}` → ready "Daemon reads all N repos (checked via the daemon)"; `{blocked>0}` → needs-you with the same action; else → error "mattstack.app not running — permission status unavailable" with action `{type:"run", label:"Re-check", verb:["setup","status"]}`. required:true. why: "Reads your repositories' git state so the daemon can show branch and MR status."
+- login-items: enabled → ready; requiresApproval → needs-you "Approve in Login Items", action `{type:"open-settings", label:"Open Login Items…", target:"login-items"}`; notRegistered/notFound → missing "Not registered yet (Install registers it)", action null; reply null → error as above. required:true.
+- notifications: authorized/provisional → ready; notDetermined → needs-you "Not requested", action `{type:"request-permission", label:"Allow", which:"notifications"}`; denied → needs-you, action `{type:"open-settings", label:"Open Notification Settings…", target:"notifications"}`; null → skipped "not checked (app not running)". required:false, optionalNote "Works without this; you'll see menu-bar badges instead."
+
+```ts
+// lib/setup/validators/mac.ts
+export async function macRows(p: Probes): Promise<Row[]>   // tool.macos, tool.clt, tool.path  (perm rows come from permissions.ts; plan.ts concatenates)
+```
+- `tool.macos`: `p.exec(["sw_vers","-productVersion"])`; major ≥ 14 → ready "macOS <v>"; else invalid "macOS 14 or newer required"; required:true; action null.
+- `tool.clt`: `p.exec(["xcode-select","-p"])` code 0 AND `p.exec(["git","--version"])` code 0 → ready "git <v>"; else missing "Apple command line tools not installed", action `{type:"install", label:"Install…", tool:"apple-clt", via:"apple-clt"}`; required:true.
+- `tool.path`: kind "info", required:false (informational, Install fixes it): PATH order check — first entry of `p.env.PATH` that exists is `~/.local/bin` AND `~/.zshenv` contains the precedence block marker `# mattstack — PATH precedence` → ready; shell rc has the block but not first → needs-you "~/.local/bin is on PATH but not first — team intercept shims may not fire"; absent → missing "Install adds ~/.local/bin to PATH"; detail names the rc file. No action (fixed by path.link).
+
+- [ ] **Step 1: Failing tests.** `permissionRows` table-driven for all 11 mappings above (assert id/status/action.type/target/required). `macRows` with fake exec: sw_vers "15.6" → ready; "13.7" → invalid; xcode-select 127 → missing with install action via apple-clt; PATH starting with `/opt/homebrew/bin` and a rc block present → needs-you.
+- [ ] **Step 2:** fail. **Step 3:** implement. **Step 4:** green; tsc 0. **Step 5: Commit** `MAT-383: mac validators + permission rows from tray.sock`
+
+---
+
+### Task 7: Validators — rt health (the existing `rt verify` checks as rows)
+
+**AFTER L1 T5 and L4 T11 merge** (`resolveFzf()` in `lib/fzf.ts` is L4's; rebase onto `origin/main` first). L4's competing `commands/verify.ts` edit ("rt link" + "bundled extension" checks) is dropped — the two rows below carry it.
+
+**Files:**
+- Create: `lib/setup/validators/rt-health.ts`
+- Test: `lib/setup/__tests__/validators-rt-health.test.ts`
+
+**Interfaces:**
+- Consumes: `resolveFzf()` (`lib/fzf.ts`, L4 T11 — bundled path first, then PATH); `appBundlePath` (Task 5), `RT_BUNDLE_PATH` (`lib/bundle-layout.ts`).
+- Produces: `export async function rtHealthRows(p: Probes, opts: { ci: boolean }): Promise<Row[]>` with rows in this order and these ids (all `kind:"tool"`, group `tools`):
+
+| id | required | ready when | otherwise |
+|---|---|---|---|
+| tool.rt | true | `p.exec(["rt","--version"])` code 0 (detail = stdout) | missing "rt not found on PATH" (action `{type:"link-bundled", label:"Use mattstack's", tool:"rt"}`) |
+| tool.rt-link | false | prod mode only (`currentMode()==="prod"`; dev → skipped "dev mode owns ~/.local/bin/rt"): `p.readlink(~/.local/bin/rt) === join(appBundlePath(p), "Contents/MacOS/rt")` → ready "linked into the bundle" | needs-you "not a link into mattstack.app — run: rt setup apply --from path.link"; no app → skipped |
+| tool.legacy-dirs | true | `legacyDirsPresent()` real=[] (symlinks → ready with detail "compat symlink still present: …") | invalid "real legacy dir present: … — rt reads only ~/.mattstack/rt" |
+| tool.intercepts | false | `shimReport()` all installed+current and `~/.local/bin` on PATH and `staleIntercepts().stale===false` (no rules → skipped "no intercepts declared") | needs-you with the same messages verify prints today, action `{type:"run", label:"Re-install shims", verb:["intercept","install"]}` |
+| tool.fzf | true | `resolveFzf()` non-null → detail `fzf <version> (bundled|PATH)` (bundled when the resolved path is inside the bundle) | missing "fzf not found" action link-bundled fzf |
+| tool.app | true | `appBundlePath(p)` non-null (detail path + CFBundleShortVersionString via `p.exec(["/usr/libexec/PlistBuddy","-c","Print CFBundleShortVersionString",<plist>])`) ; legacy `rt-tray.app` present → detail appends "legacy rt-tray.app still present" | missing "mattstack.app not found in /Applications or ~/Applications" |
+| tool.vsix | false | `p.exists(<app>/Contents/Resources/rt-context.vsix)` → ready "bundled extension present" | missing → skipped "extension not bundled (pre-bundle build)"; no app → skipped |
+| tool.extension | false | `checkRtContextExtension(home)` (moved from verify.ts to this module) pass | warn→needs-you with action `{type:"run", label:"Install extension", verb:["tools","setup","extension"]}`; no editors → skipped |
+| tool.shell | false | rc file contains `rtcd` | needs-you "shell integration missing — Install writes it" |
+| tool.daemon | true | `isDaemonInstalled()` and `p.daemon("ping")` ok; detail from `status` (pid/uptime/watched) | not installed → missing "run Install (registers the daemon)"; installed but down → ci ? needs-you "not booted (expected in CI)" : needs-you "installed but not responding — approve in Login Items", action open-settings login-items |
+
+Both `tool.daemon` sub-facts (launchd label via `p.exec(["launchctl","list",activeLaunchdLabel()])`, `worktrees` endpoint) fold into `detail`, not separate rows. `tcc:check` is consumed by Task 6's `perm.fda` fallback (plan.ts passes it in), not here.
+
+- [ ] **Step 1: Failing tests** (fake probes; HOME is the test temp dir): rt --version ok → `tool.rt` ready with detail; `tool.rt-link` ready when `readlink` returns the bundle's `Contents/MacOS/rt`, needs-you when it points elsewhere, skipped in dev mode; `tool.vsix` ready/skipped by `exists`; `tool.fzf` detail says "bundled" when `resolveFzf` (injected) returns a path under the bundle; `legacyDirsPresent` via a real `.rt` dir created under the test HOME → invalid; daemon not installed (no daemon.json in test HOME) → `tool.daemon` missing; `ci:true` + installed + ping null → needs-you containing "CI"; app missing → missing. Also an order test: ids equal the table order.
+- [ ] **Step 2:** fail. **Step 3:** implement (move `checkRtContextExtension` here; re-export it from `commands/verify.ts` so `commands/__tests__/verify.test.ts` keeps passing unchanged). **Step 4:** green; tsc 0. **Step 5: Commit** `MAT-383: rt health validators (verify checks become rows)`
+
+---
+
+### Task 8: Validators — tools group (provisioned, bundled, team-declared, packs)
+
+**AFTER L1 T5 and L4 T11 merge** (uses `resolveTool(...).exec` from Task 5; rebase onto `origin/main` first). `commands/post-install.ts` is L1-owned (L4 T9 dropped its edit of that file); the `detectEditors` import change here is the only Task-8 touch of it.
+
+**Files:**
+- Create: `lib/setup/validators/tools.ts`, `lib/setup/semver.ts`, `lib/editors.ts`
+- Modify: `commands/extension.ts`, `commands/post-install.ts` (import `detectEditors`/`EDITOR_PATTERNS` from `lib/editors.ts`)
+- Test: `lib/setup/__tests__/validators-tools.test.ts`, `lib/setup/__tests__/semver.test.ts`
+
+**Interfaces:**
+- Produces: `export function atLeast(version: string, floor: string): boolean` (numeric dotted compare, ignores leading "v" and suffixes); `export async function toolRows(p: Probes, reqs: PackRequirements[], opts: { hasBrew: boolean }): Promise<Row[]>`:
+
+| id | required | probe | ready | otherwise |
+|---|---|---|---|---|
+| tool.herdr | true | `herdr --version` (floor `0.7.5`) + `herdr integration status` | version ≥ floor and integration stdout contains "claude" → detail "herdr <v>, Claude integration installed"; integration missing → needs-you action `{type:"run", label:"Install integration", verb:["tools","setup","herdr"]}` | 127 → missing, action `{type:"install", label:"Install", tool:"herdr", via: hasBrew ? "brew" : "vendor"}`; below floor → invalid "herdr <v> < 0.7.5" |
+| tool.claude | true | `claude --version`; sign-in: `claude auth status` code 0 → signed in; unknown subcommand (stderr contains "unknown") → detail "installed (sign-in not checked)" ready | ready | 127 → missing, action install via brew/vendor; auth status code ≠0 (and known) → needs-you "sign in: run claude once", action `{type:"steps", label:"Show steps…", steps:["Open a terminal","Run: claude","Follow the sign-in prompt"]}` |
+| tool.fast-browser | true | `p.exec([...resolveTool(p,"fast-browser").exec, "doctor", "--json"])` (the bundled exec is `[node, fast-browser.mjs]`, never `chosen` as argv0) → parse `{runtime:{ok}, extension:{loaded}, pairing:{ok}}` (tolerate missing keys) | runtime ok AND extension loaded | extension not loaded → needs-you action `{type:"steps", label:"Show steps…", steps:["Open chrome://extensions","Turn on Developer mode","Load unpacked → ~/.fast-browser/extension/current/unpacked"]}`; `exec` null → missing (bundled-link action); doctor parse failure → error with stderr head |
+| tool.editor | false | `detectEditors()` — moved with `EDITOR_PATTERNS` into a new `lib/editors.ts` (this task; `commands/extension.ts` and `commands/post-install.ts` import it from there, behavior unchanged) | ≥1 editor → detail names | skipped "no editor found (works without this)" |
+| tool.chrome | required iff any `reqs[].chrome?.required` | `p.exists("/Applications/Google Chrome.app")` or `~/Applications/...` | ready | missing, action `{type:"open-url", label:"Download", url:"https://www.google.com/chrome/"}`; optional otherwise; a pack `signedIntoApp` adds a needs-you row `tool.chrome-signin` with steps |
+| tool.mission-control | false | `defaults read com.apple.symbolichotkeys AppleSymbolicHotKeys` → key "32" → `enabled` 0 | unbound → ready | bound → needs-you "Control+Up is bound to Mission Control (rt nav uses it)", action `{type:"open-settings", label:"Open Keyboard Settings…", target:"keyboard"}`; exec fails → skipped |
+| tool.<name> (per `reqs[].tools`) | !optional | `<name> --version` | present (and ≥ floor when given) → detail version; `connect` present and row "connect" unresolved → stays ready (connect is an account row) | missing → action install via brew when `install.brew` and hasBrew, else `open-url install.url` when given, else `steps`; why = requirement.why |
+| pack.<pack> | true | `claude plugin list` stdout contains `<pack>@` | ready "installed" | missing "installed by Install (plugins.install)"; claude missing → skipped |
+
+- [ ] **Step 1: Failing tests.** semver: `atLeast("0.8.0","0.7.5")` true, `atLeast("v0.7.4","0.7.5")` false, `atLeast("24.19.0","24")` true. tools: fake exec script keyed on argv[0]; herdr 127 + hasBrew → install via brew; herdr "0.8.0" + integration "claude: installed" → ready; fast-browser with `exec=[node, mjs]` → recorded argv is `[node, mjs, "doctor", "--json"]` and doctor `{"runtime":{"ok":true},"extension":{"loaded":false}}` → needs-you with 3 steps; team tool `doppler` missing with brew formula → install action `tool:"doppler", via:"brew"`; pack row from `reqs=[{pack:"claimview",...}]` with plugin list containing `claimview@assured` → ready.
+- [ ] **Step 2:** fail. **Step 3:** implement. **Step 4:** green; tsc 0. **Step 5: Commit** `MAT-383: tools validators (provisioned, bundled, team-declared, packs)`
+
+---
+
+### Task 9: Validators — accounts + access
+
+**Files:**
+- Create: `lib/setup/validators/accounts.ts`, `lib/setup/validators/access.ts`, `lib/setup/team-settings.ts`
+- Test: `lib/setup/__tests__/validators-accounts.test.ts`, `lib/setup/__tests__/validators-access.test.ts`
+
+**Interfaces:**
+- Produces:
+
+```ts
+// lib/setup/team-settings.ts — the only place plan/apply read team keys (through getSetting)
+export interface TeamIntegrations { forge?: { host: string; provider: "github" | "gitlab" }; slack?: { appId?: string; clientId?: string; channel?: string; callbackPort?: number }; linear?: { teamKey: string }; switchboard?: { url: string } }
+export interface TeamSnapshot { slug: string; integrations: TeamIntegrations; trackingIdentities: string[]; marketplaces: string[]; plugins: string[]; remote: string | null }
+export function readTeamSnapshot(p: Probes, slug: string): TeamSnapshot   // getSetting("mattstack.integrations"), getSetting("mattstack.tracking") → Object.keys(repos), claude.marketplaces/plugins; remote via p.readFile(teams/<slug>/.git/config) + parseOriginUrl
+export function forgeFromRemote(remote: string): { host: string; provider: "github" | "gitlab" } | null   // github.com → github; anything else → gitlab (self-hosted assumption), null when unparsable
+```
+
+```ts
+// lib/setup/validators/accounts.ts
+export interface SecretPresence { has(domain: string, key: string): Promise<string | null> }   // reads user-scope secrets (lib/secrets/store.readSecret) — null when no key yet (NoAgeKeyError → treated as absent) — plus staged values (staging.ts)
+export async function accountRows(p: Probes, team: TeamSnapshot, reqs: PackRequirements[], secrets: SecretPresence, intent: SetupIntent | null): Promise<Row[]>
+```
+Rows: one `account.<integration>` per declared integration — declared = `team.integrations.forge.provider` (always) ∪ `linear` if `team.integrations.linear` ∪ `slack` if `team.integrations.slack?.clientId` ∪ `switchboard` if `team.integrations.switchboard` ∪ every `reqs[].integrations` ∪ `reqs[].tools[].connect.integration`. Status: secret absent (and no gh auth for github) → missing with `connect` action from `INTEGRATIONS[id]` (github adds `alternatives:[{id:"use-gh",label:"Use gh login"}]` when `p.exec(["gh","auth","status"])` code 0, and when gh IS authenticated and no token stored → ready "via gh (<user>)"); present → call `def.validate` → ready/invalid (detail from validator; `recheck:"on-change"`). Slack action is `{type:"oauth", label:"Connect", integration:"slack", verb:["setup","slack","connect"]}`. Owner-once `account.slack-app` (before `account.slack`) appears when `slack` is wanted by a pack (`reqs[].integrations` includes slack) but `team.integrations.slack?.clientId` is absent AND `intent?.mode === "create"` (or no intent and the user is the team owner: `board.members[0]?.username` equals the forge login — keep simple: mode create or none with a single team); action `{type:"owner-once", label:"Create the team's Slack app…", integration:"slack", fields:[{name:"configToken", label:"App configuration token", secret:true}]}`; status missing; required true. `account.switchboard` detail "redeemed during Join" when intent.mode==="join" and secret present → ready.
+
+```ts
+// lib/setup/validators/access.ts
+export async function accessRows(p: Probes, team: TeamSnapshot, intent: SetupIntent | null): Promise<Row[]>
+```
+- `access.team-repo` (required): remote = `intent?.team?.remote ?? intent?.join?.pointer.remote ?? team.remote`; `p.exec(["git","ls-remote","--exit-code",remote,"HEAD"],{timeoutMs:15000, env:{GIT_TERMINAL_PROMPT:"0"}})` code 0 → ready "reachable"; code 2 → ready "empty repo (will be initialized)"; 128 + stderr matches /Authentication|403|Permission denied|could not read Username/ → needs-you "you don't have access yet: ask the owner to grant you access" (never prints the URL); other → error "unreachable: <first stderr line>"; no remote → missing "no team remote yet (screen 2)".
+- `access.forge` (required): `p.fetch("https://<host>/", {method:"HEAD", timeoutMs:5000})` status > 0 → ready.
+- `access.repo.<slug>` per `team.trackingIdentities` (required:false, optionalNote "Works without this; the board won't show this repo"): `git ls-remote --exit-code https://<identity>.git HEAD` → ready / needs-you (auth) / error.
+- `access.switchboard` (required:false) when `team.integrations.switchboard` → `GET <url>/health` 200.
+
+- [ ] **Step 1: Failing tests.** accounts: team forge gitlab + no secret → `account.gitlab` missing with `connect` action fields `[{name:"token",...}]`; secret present + validator 200s → ready; github with gh authenticated and no token → ready "via gh"; reqs wanting slack + create intent + no clientId → `account.slack-app` owner-once row precedes `account.slack`; linear declared → row present, not declared → absent. access: ls-remote 0 → ready; stderr "Authentication failed" → needs-you and detail does not contain the remote URL; tracking identities produce `access.repo.<slug>` rows with slug = identity with `/`→`-`.
+- [ ] **Step 2:** fail. **Step 3:** implement. **Step 4:** green; tsc 0. **Step 5: Commit** `MAT-383: accounts + access validators`
+
+---
+
+### Task 10: Plan composition + `rt setup plan|status` + `setup` node
+
+**AFTER L1 T5 and L4 T11 merge** (composes Tasks 7–9). `cli.ts` is L1-owned (L4 T10's comment-only edit is dropped).
+
+**Files:**
+- Create: `lib/setup/plan.ts`, `commands/setup.ts`
+- Test: `lib/setup/__tests__/plan.test.ts`, `commands/__tests__/setup-plan.test.ts`
+- Modify: `lib/command-tree-def.ts` (new `setup` node), `lib/module-registry.ts` (`./commands/setup.ts`), `cli.ts` (first-run hook, see Step 3)
+
+**Interfaces:**
+- Produces:
+
+```ts
+// lib/setup/plan.ts
+export interface PlanInputs { p: Probes; secrets: SecretPresence; ci: boolean; teamOverride?: string }
+export async function composePlan(i: PlanInputs): Promise<Plan>
+//  1. intent = readIntent(p); teams = listTeams(); team = teamRefFromIntent(intent, teams) (teamOverride wins when it names a cloned team)
+//  2. snapshot = team.slug ? readTeamSnapshot(p, team.slug) : empty; reqs = readPackRequirements(p, team.slug)
+//  3. rows: mac = [...permissionRows(await fetchPermissions(p.tray), tcc), ...await macRows(p)]  (tcc = p.daemon("tcc:check") → {blocked, total})
+//     accounts = await accountRows(...); access = await accessRows(...); tools = [...await toolRows(p, reqs, {hasBrew}), ...await rtHealthRows(p,{ci})]
+//  4. finalizePlan(team, [mac, accounts, access, tools] as Groups with GROUP_TITLES, p.now())
+export function realSecretPresence(): SecretPresence   // readSecret over real seams; NoAgeKeyError → null; also consults staging
+```
+
+```ts
+// commands/setup.ts (this task: plan/status only; later tasks add the rest)
+export async function setupPlan(args: string[], _ctx?: CommandContext, deps = realSetupDeps()): Promise<void>     // --json | human table; --team <name>
+export async function setupStatus(args: string[], _ctx?: CommandContext, deps = realSetupDeps()): Promise<void>   // same plan; human header "rt setup status"
+export interface SetupDeps { probes: Probes; secrets: SecretPresence; print: (s: string) => void }
+export function realSetupDeps(): SetupDeps
+export function renderPlanHuman(plan: Plan): string[]   // group headers + "  <glyph> <title>  <detail>" + footer "Install: ready|blocked by: …"; glyphs ✓ ready · ✗ missing/invalid/error · ! needs-you · – skipped · … checking
+```
+Tree node (exact):
+```ts
+setup: {
+  description: "Set this Mac up for mattstack: readiness plan, install steps, account connections",
+  module: "./commands/setup.ts", fn: "setupInteractive",            // this task: setupInteractive === setupStatus; Task 27 gives it the interactive walk
+  args: [{ name: "JSON", flag: "--json", type: "boolean", default: false, hint: "Machine-readable plan" }],
+  subcommands: {
+    plan:   { description: "Compute the readiness checklist", module: "./commands/setup.ts", fn: "setupPlan",   args: [{ name: "Team", flag: "--team", type: "text", placeholder: "claimview", hint: "Which cloned team to plan for" }, { name: "JSON", flag: "--json", type: "boolean", default: false, hint: "Machine-readable plan" }] },
+    status: { description: "The same checklist as a post-install health view", module: "./commands/setup.ts", fn: "setupStatus", args: [{ name: "JSON", flag: "--json", type: "boolean", default: false, hint: "Machine-readable plan" }] },
+    // apply + intent (Task 27), pack (Task 28), <integration> + slack create-app (Task 12) are added by their tasks
+  },
+},
+```
+
+- [ ] **Step 1: Failing tests.** `plan.test.ts`: with fake probes (tray `GET /permissions` → all granted; exec script answering every probe the validators make with "ready" shapes; no intent; no teams) → plan has 4 groups in order `mac, accounts, access, tools`, `team.mode==="none"`, `perm.fda` ready; with tray status 0 and daemon tcc `{blocked:0,total:2}` → `perm.fda` ready with "via the daemon" detail; with an intent `{mode:"create", team:{slug:"acme",...remote:"https://github.com/o/r.git"}}` → `team` is `{slug:"acme", name:"Acme", mode:"create"}` and `account.github` exists. `setup-plan.test.ts`: `setupPlan(["--json"], {}, deps)` prints exactly one line that parses to a Plan with `contract:1`; human mode prints "Your Mac".
+- [ ] **Step 2:** fail. **Step 3:** implement; `setupInteractive` this task = `setupStatus` (replaced in Task 28). **cli.ts first-run hook**: the `daemon.json`-absent branch no longer auto-runs post-install; it prints `  rt is not set up yet — open mattstack.app, or run: rt setup` (once, to stderr) and continues, and it is skipped entirely when `args[0]` ∈ `setup, team, deps, services, tools, repos, skills, cron, uninstall, home, secrets, restore, verify` or `RT_APP_SOCKET` is set. `args[0] === "--post-install"` never reaches the hint: the earlier `--post-install` branch in `cli.ts` dispatches before the first-run hook runs (no change needed; stated so nobody adds it to the skip list twice). Keep `RT_SKIP_SETUP`/`CI` respected. `verify` keeps its direct-dispatch branch.
+- [ ] **Step 4:** green (module-registry test included); tsc 0.
+- [ ] **Step 5: Commit** `MAT-383: rt setup plan|status — plan composition over the validators`
+
+---
+
+### Task 11: `rt verify` runs the validators
+
+**AFTER L1 T5 and L4 T11 merge.** `commands/verify.ts` is L1-owned: L4 T11's edit of it (fzf block, "rt link", "bundled extension" checks) is dropped; Task 7's `tool.fzf`/`tool.rt-link`/`tool.vsix` rows carry that content, so no rebase conflict arises here.
+
+**Files:**
+- Modify: `commands/verify.ts` (replace `runChecks` with a mapping over `composePlan`), keep `printHuman`/`printJSON` shapes
+- Test: `commands/__tests__/verify-mapping.test.ts`; existing `commands/__tests__/verify.test.ts` untouched
+
+**Interfaces:**
+- Produces: `export function rowsToChecks(plan: Plan, opts: { ci: boolean }): CheckResult[]` (exported for tests) with mapping: ready → pass; skipped/checking → skip; missing/invalid/error/needs-you → required ? fail(critical) : warn; exceptions: `perm.*` rows in `ci` mode are never critical (downgrade to warn); `tool.daemon` needs-you in ci → warn (existing behavior). `name` = row.id, `detail` = row.detail (+ ` — ${action.label}` hint when an action exists). `runVerify(args)`: `--json` prints `{passed, summary, checks, plan}` (adds the raw plan — additive); exit 1 when any critical fail.
+- [ ] **Step 1: Failing tests** for `rowsToChecks`: required missing → fail critical; optional missing → warn; `perm.fda` needs-you with ci → warn; ready → pass; the JSON summary counts.
+- [ ] **Step 2:** fail. **Step 3:** implement; delete the old `cmd()`/check bodies (they now live in validators). Keep `checkRtContextExtension` re-export. **Step 4:** green; tsc 0; `bun run cli.ts verify --json` from the worktree prints JSON (a smoke, not a test). **Step 5: Commit** `MAT-383: rt verify = the setup validators, one implementation`
+
+---
+
+### Task 12: `rt setup <integration> status|connect` + `rt setup slack create-app`
+
+**Files:**
+- Create: `lib/setup/slack-app.ts`
+- Modify: `commands/setup.ts` (add `integrationVerb` factory + 16 exports + `setupSlackCreateApp`), `lib/command-tree-def.ts` (integration nodes under `setup`)
+- Test: `commands/__tests__/setup-connect.test.ts`, `lib/setup/__tests__/slack-app.test.ts`
+
+**Interfaces:**
+- Produces:
+
+```ts
+// commands/setup.ts
+export async function integrationStatus(id: Integration, args: string[], deps: SetupDeps): Promise<void>   // prints envelope({integration, status, detail, scopesSeen}) from accountRows-equivalent single-row evaluation
+//  github only: when gh is authenticated (`gh auth status` code 0) the envelope also carries `handle` (`gh api user` → .login) and `owners: [handle, ...(gh api user/orgs → [].login)]` — the app's Create-team card reads them (contract: `rt setup github status --json`)
+export async function integrationConnect(id: Integration, args: string[], deps: SetupDeps & { stdin: () => Promise<unknown> }): Promise<void>
+//  stdin JSON {"token": "..."} | {"useGh": true} | {"email": "..."} (field names = def.fields[].name); --token-stdin reads a raw token line; TTY without stdin → promptSecretValue per secret field
+//  1. validate via def.validate → invalid → print envelope + exit 2 (code "invalid-credential")
+//  2. store: age key present → writeSecret(domain,key,value) ; absent → stageSecret (detail "staged until Install creates your key")
+//  3. print envelope({ integration, status:"ready", detail, scopesSeen })
+//  useGh: token = p.exec(["gh","auth","token"]) stdout; stored like a token; detail "via gh"
+//  doppler/ldcli: connect = p.exec(["doppler","login"]) / (["ldcli","login"]) inheriting the TTY (probes.exec with opts.inherit:true — add to Probes) then re-validate
+//  slack: connect = OAuth: build https://slack.com/oauth/v2/authorize?client_id=<team.integrations.slack.clientId>&user_scope=<scopes>&redirect_uri=http://localhost:<callbackPort>/callback ; open it (p.exec(["open", url])); listen on callbackPort (Bun.serve, injectable `deps.listen`) for one request; exchange code at https://slack.com/api/oauth.v2.access with clientId + client secret (team secret board.slackClientSecret via readTeamSecret — Task 13; absent → exit 2 "slack-app-missing"); store authed_user.access_token as board.slackUserToken (user scope)
+export const setupGithubStatus = (a: string[], c?: CommandContext, d = realConnectDeps()) => integrationStatus("github", a, d);   // … ×8 ids × {Status, Connect}
+export async function setupSlackCreateApp(args: string[], _ctx?: CommandContext, deps = realConnectDeps()): Promise<void>
+//  --config-token-stdin ⇒ a raw token line on stdin; no flag ⇒ stdin JSON {"configToken"} (the app sends JSON without the flag); hardening: under the flag, a line that parses as a JSON object is read as {"configToken"} too. Builds manifest via buildSlackManifest(); POST https://slack.com/api/apps.manifest.create (Bearer config token) → {app_id, credentials:{client_id, client_secret, signing_secret}}
+//  writes mattstack.integrations.slack {appId, clientId, callbackPort} via setSetting(..., "team", {team: slug}) (deep-merge preserves forge/linear); writes team secrets board.slackClientSecret + board.slackSigningSecret via writeTeamSecret (Task 13 — executed before this task, see the execution-order note at the end)
+```
+
+```ts
+// lib/setup/slack-app.ts
+export interface SlackScopeNeeds { bot: string[]; user: string[] }
+export const DEFAULT_SCOPE_NEEDS: SlackScopeNeeds = { bot: ["chat:write","reactions:write","channels:read","users:read"], user: ["reactions:write","chat:write"] }
+export function buildSlackManifest(opts: { name: string; callbackPort: number; scopes: SlackScopeNeeds }): object   // display_information, oauth_config.redirect_urls [http://localhost:<port>/callback], scopes, settings.org_deploy_enabled false
+export const DEFAULT_CALLBACK_PORT = 11234
+```
+Tree: for each id in `github gitlab linear slack switchboard sdm doppler ldcli`: `setup.subcommands[id] = { description: "<Title>: check or connect this account", subcommands: { status: { module, fn: "setup<Id>Status", args:[json] }, connect: { module, fn: "setup<Id>Connect", args:[json, {name:"Token on stdin", flag:"--token-stdin", type:"boolean"}, {name:"Use gh", flag:"--use-gh", type:"boolean"}] } } }`; `slack` adds `"create-app": { fn:"setupSlackCreateApp", args:[{flag:"--config-token-stdin"...}, json] }`. Generate these nodes with a local helper in command-tree-def.ts (`integrationNode(id, title)`), keeping the module side-effect free.
+
+- [ ] **Step 1: Failing tests.** `setup-connect.test.ts`: gitlab connect with stdin `{"token":"glpat-x"}` and a fake fetch making validate ready, no age key (fake `SecretPresence`/writer seam reports `hasKey:false`) → prints `{...,"status":"ready"}` and the staging file `rt/setup-staging/rt.json` contains `gitlabToken` (assert via fake `writes`); validate invalid → exit code 2 captured (stub `process.exit` via a `deps.exit` seam — add `exit: (code:number)=>never` to SetupDeps) and payload `error.code==="invalid-credential"`; `--use-gh` → exec `["gh","auth","token"]` called and token stored; `setupGithubStatus(["--json"])` with gh authenticated (fake `gh api user` → `{"login":"matt"}`, `gh api user/orgs` → `[{"login":"m4ttstack"}]`) → envelope has `handle:"matt"`, `owners:["matt","m4ttstack"]`; gh unauthenticated → no `handle`/`owners` keys. `slack-app.test.ts`: manifest has redirect url with the port and both scope lists; `setupSlackCreateApp` with fake fetch returning credentials → `setSetting` called (spy on a `writeSetting` seam in deps) with `mattstack.integrations` containing `{slack:{appId,clientId,callbackPort}}` and team secrets written for clientSecret+signingSecret (fake team-secret writer records).
+- [ ] **Step 2:** fail. **Step 3:** implement. **Step 4:** green; tsc 0; module-registry test green. **Step 5: Commit** `MAT-383: rt setup <integration> status|connect, slack create-app`
+
+---
+
+### Task 13: Team-scope secrets (N-recipient) + `rt secrets … --team`
+
+**Files:**
+- Create: `lib/secrets/team-store.ts`
+- Modify: `lib/secrets/store.ts` (factor a `SecretsLocation` so encrypt/decrypt helpers take `{filePath, filenameOverride, cwd}`; public `readSecret/writeSecret/rotateSecret/listSecretNames` signatures unchanged), `commands/secrets.ts` (`--team <slug>` on set/list/rotate; `rotate --team <slug>` with no key = re-encrypt all domains), `lib/command-tree-def.ts` (args), `lib/home/age-key.ts` (export `renderSopsYamlFor(pathRegex: string, recipients: string[]): string`)
+- Test: `lib/secrets/__tests__/team-store.test.ts`, extend `lib/secrets/__tests__/store.test.ts` (locations refactor keeps every existing assertion)
+
+**Interfaces:**
+- Produces:
+
+```ts
+// lib/secrets/team-store.ts
+export function teamSecretsFile(slug: string, domain: string): string        // ~/.mattstack/teams/<slug>/mattstack/secrets/<domain>.json
+export function teamSopsYamlPath(slug: string): string                        // ~/.mattstack/teams/<slug>/.sops.yaml  (path_regex: mattstack/secrets/.*)
+export function readTeamRecipients(slug: string, seams: SecretsSeams): string[]           // parses the age: list (comma/newline separated) — [] when absent
+export function writeTeamRecipients(slug: string, recipients: string[], seams: SecretsSeams): void   // renders renderSopsYamlFor("mattstack/secrets/.*", recipients) — sorted, deduped
+export async function readTeamSecret(slug: string, domain: string, key: string, seams: SecretsSeams): Promise<string | null>
+export async function writeTeamSecret(slug: string, domain: string, key: string, value: string, seams: SecretsSeams): Promise<void>   // requires ≥1 recipient (else throws NoTeamRecipientsError with "run rt team members sync"); cwd pinned to the team clone so sops finds the team .sops.yaml
+export async function addTeamRecipient(slug: string, publicKey: string, seams: SecretsSeams): Promise<{ added: boolean; reencrypted: string[] }>   // write recipients, then `sops updatekeys -y <file>` for every domain file
+export async function removeTeamRecipient(slug: string, publicKey: string, seams: SecretsSeams): Promise<{ removed: boolean; reencrypted: string[] }>
+export async function reencryptTeamSecrets(slug: string, seams: SecretsSeams): Promise<string[]>   // `sops updatekeys -y` per file — the `rt secrets rotate --team` mechanic; note in the command's output that removed members keep their old copies (documented residue)
+```
+Layout note for the settings lane — already applied to `docs/superpowers/specs/2026-08-21-rt-setup-contract.md` under the "Team-scope secrets layout" heading in the appspec branch (merged to main before this lane executes); this task only references it and commits **no** spec/contract file from the L1 worktree: `teams/<slug>/.sops.yaml` (N `age:` recipients, `path_regex: mattstack/secrets/.*`), files at `teams/<slug>/mattstack/secrets/<domain>.json`, domains `board` (slackClientSecret, slackSigningSecret) and `rt` (switchboardAdminToken, shared service tokens a pack declares).
+
+- [ ] **Step 1: Failing tests** (fake exec seam as in store.test.ts): `writeTeamRecipients` renders a `.sops.yaml` with both keys and the team path_regex; `writeTeamSecret` argv pins `--filename-override mattstack/secrets/board.json` and spawn cwd = team clone (assert via `buildSecretsSpawnOptions`-style builder exported as `buildTeamSpawnOptions(slug)`); zero recipients → throws; `addTeamRecipient` runs `["sops","updatekeys","-y",<file>]` once per existing domain file; `removeTeamRecipient` rewrites without the key and re-encrypts; existing store tests unchanged and green after the locations refactor.
+- [ ] **Step 2:** fail. **Step 3:** implement. `rt secrets set <domain> <key> --team <slug>` / `list --team` / `rotate --team <slug> [<domain> <key>]`: with domain+key = rotate that value; with none = `reencryptTeamSecrets`. **Step 4:** green; tsc 0. **Step 5: Commit** `MAT-383: team-scope secrets — N-recipient sops, rotate --team`
+
+---
+
+### Task 14: Invite crypto + code encoding
+
+**Files:**
+- Create: `lib/team/invite-crypto.ts`, `lib/team/slug.ts`
+- Test: `lib/team/__tests__/invite-crypto.test.ts`, `lib/team/__tests__/slug.test.ts`
+
+**Interfaces:**
+- Produces:
+
+```ts
+// lib/team/slug.ts
+export function slugify(name: string): string   // lowercase, [^a-z0-9]+ → "-", trim "-", max 40; throws UserActionableError("bad-team-name") when empty
+// lib/team/invite-crypto.ts  (WebCrypto AES-256-GCM; pinned: 32-byte key, 12-byte IV, ciphertext = base64(iv ‖ ct‖tag))
+export const INVITE_ID_BYTES = 16;            // relay ids are 16 random bytes, transported as 32 lowercase hex chars (L6 contract)
+export function generateKey(): Uint8Array     // crypto.getRandomValues 32 bytes
+export async function seal(pointer: InvitePointer, key: Uint8Array): Promise<string>          // base64 string
+export async function open(ciphertextB64: string, key: Uint8Array): Promise<InvitePointer>    // throws UserActionableError("invite-unreadable") on auth failure / bad JSON / v !== 1
+export function encodeCode(idHex: string, key: Uint8Array): string      // base32 Crockford (no padding) of idBytes(16)‖key(32) = 77 chars, chunked "XXXXX-XXXXX-…" (groups of 5, dash-separated)
+export function decodeCode(code: string): { idHex: string; key: Uint8Array }   // strips dashes/whitespace, case-insensitive, maps Crockford aliases (O→0, I/L→1); throws UserActionableError("invite-malformed") on wrong length/alphabet
+export async function sealReply(reply: { v: 1; agePublicKey: string; handle?: string }, key: Uint8Array): Promise<string>   // same AEAD, for the invitee→owner blob
+export async function openReply(b64: string, key: Uint8Array): Promise<{ v: 1; agePublicKey: string; handle?: string }>
+```
+
+- [ ] **Step 1: Failing tests.** seal→open round-trips a pointer; tampering one byte of the ciphertext → `open` throws with code `invite-unreadable`; wrong key → throws; `encodeCode`/`decodeCode` round-trip with random id/key, lowercased and with dashes removed both decode; a 76-char code → `invite-malformed`; `slugify("Acme Claims!")==="acme-claims"`; `slugify("!!!")` throws.
+- [ ] **Step 2:** fail. **Step 3:** implement (`crypto.subtle.importKey("raw", key, "AES-GCM", false, ["encrypt","decrypt"])`; IV via `crypto.getRandomValues(new Uint8Array(12))`). **Step 4:** green; tsc 0. **Step 5: Commit** `MAT-383: opaque invite crypto (AES-256-GCM) + invite code encoding`
+
+---
+
+### Task 15: Relay client
+
+**Files:**
+- Create: `lib/team/relay-client.ts`
+- Test: `lib/team/__tests__/relay-client.test.ts`
+
+**Interfaces:**
+- Produces:
+
+```ts
+export const DEFAULT_INVITE_RELAY_URL = "https://switchboard.mattstack.dev";   // overridable: process.env.RT_INVITE_RELAY_URL
+export function inviteRelayUrl(env: Record<string, string | undefined>): string
+export interface RelayClient {
+  create(ciphertext: string, expiresAt: string): Promise<{ id: string; creatorSecret: string }>;    // POST /v1/invites {ciphertext, expiresAt}
+  fetch(id: string): Promise<{ ciphertext: string } | "gone">;                                       // GET /v1/invites/:id — 404/410 → "gone"
+  redeem(id: string): Promise<"redeemed" | "already">;                                             // POST /v1/invites/:id/redeem — 200 | 409
+  reply(id: string, blob: string): Promise<void>;                                                   // POST /v1/invites/:id/reply {blob}
+  readReply(id: string, creatorSecret: string): Promise<{ blob: string } | "none">;                 // GET /v1/invites/:id/reply (Authorization: Bearer creatorSecret) — 404 → "none"
+  delete(id: string, creatorSecret: string): Promise<void>;                                         // DELETE /v1/invites/:id
+}
+export function createRelayClient(fetchFn: Probes["fetch"], baseUrl: string): RelayClient   // every non-2xx not listed above → UserActionableError("relay-error", "<status> <path>") ; status 0 → UserActionableError("relay-unreachable")
+```
+Owner-side persisted mint record (so `members sync` can read replies): `~/.mattstack/rt/invites/<slug>.json` (0600) `{ [handle]: { id, creatorSecret, keyB64, expiresAt } }` — `lib/team/invite-records.ts` with `readInviteRecords(slug)`, `upsertInviteRecord(slug, handle, rec)`, `removeInviteRecord(slug, handle)` (same shape as intent.ts helpers; include in this task).
+
+- [ ] **Step 1: Failing tests** with a fake `fetch` recording `{url, method, body, headers}`: `create` posts JSON and returns id/creatorSecret; `fetch` 410 → "gone"; `redeem` 409 → "already"; `readReply` sends Bearer creatorSecret; 500 → `relay-error`; status 0 → `relay-unreachable`; `inviteRelayUrl({RT_INVITE_RELAY_URL:"http://localhost:9"})` honors the override. Invite records round-trip (0600).
+- [ ] **Step 2:** fail. **Step 3:** implement. **Step 4:** green; tsc 0. **Step 5: Commit** `MAT-383: invite relay client + owner-side mint records`
+
+---
+
+### Task 16: `rt team create` + `rt team publish`
+
+**Files:**
+- Create: `lib/team/create.ts`, `lib/team/publish.ts`, `commands/team.ts`
+- Test: `lib/team/__tests__/create.test.ts`, `lib/team/__tests__/publish.test.ts`, `commands/__tests__/team.test.ts`
+- Modify: `lib/command-tree-def.ts` (`team` node: create, publish; join/invite/members added by Tasks 17–19), `lib/module-registry.ts` (`./commands/team.ts`)
+
+**Interfaces:**
+- Produces:
+
+```ts
+// lib/team/create.ts
+export interface CreateTeamOpts { name: string; remote: string | null; createRepoOwner?: string; others: boolean }
+export interface CreateTeamResult { slug: string; name: string; remote: string; dir: string; created: boolean /* false when the dir already existed with the same remote */ }
+export function scaffoldFiles(slug: string, name: string, remote: string): Record<string, string>
+//  "mattstack/mattstack.jsonc": { role:"team", namespace:<slug>, org:<owner-from-remote or slug> }
+//  "mattstack/settings.jsonc":  { "mattstack.integrations": { forge: forgeFromRemote(remote) }, "board.gitlabHost": <host when gitlab>, "board.projects": [], "board.members": [], "board.title": <name> }   (written as JSONC text with a one-line header comment)
+//  ".claude-plugin/marketplace.json": { name: <slug>, owner: { name: <name> }, plugins: [] }
+//  ".sops.yaml": renderSopsYamlFor("mattstack/secrets/.*", [])   — recipients filled by members sync / home key
+//  ".gitignore": "mattstack/secrets/*.tmp\n.DS_Store\n"
+export async function createTeam(p: Probes, opts: CreateTeamOpts): Promise<CreateTeamResult>
+//  1. slug = slugify(name); dir = teams/<slug>; if dir exists and its origin URL equals remote → created:false (idempotent); exists with a different remote → UserActionableError("team-exists")
+//  2. remote: opts.remote ?? (createRepoOwner ? p.exec(["gh","repo","create",`${owner}/mattstack-team-${slug}`,"--private"]) first stdout line : throw UserActionableError("remote-required", "a git remote is required (gh-created or pasted)"))
+//  3. git init -b main; write scaffold files; git add -A; git commit -m "team: scaffold <slug>"; git remote add origin <remote>   (NO push — apply's team.create step pushes)
+//  4. write intent {mode:"create", team:{slug,name,remote,others}}
+// lib/team/publish.ts
+export async function publishTeam(p: Probes, slug: string, remote: string | null): Promise<{ remote: string; pushed: boolean; detail: string }>
+//  remote given → `git remote set-url origin <remote>` (or add); then `git push -u origin main`; 128 + auth stderr → UserActionableError("push-denied", message without the URL)
+```
+`commands/team.ts`: `teamCreate(args)` → `rt team create <name> --remote <url> | --create-repo <owner> [--others] [--json]` prints `envelope(result)`; `teamPublish(args)` → `rt team publish [--team <slug>] --remote <url> [--json]`. Tree: `team: { description: "Team repo: create, join, invite, publish, members", subcommands: { create: {...}, publish: {...} } }`.
+
+- [ ] **Step 1: Failing tests.** `scaffoldFiles("acme","Acme","https://gitlab.example.com/g/acme.git")` → settings has `mattstack.integrations.forge.host==="gitlab.example.com"` and `board.gitlabHost`; github remote → no `board.gitlabHost` key; `createTeam` records argv sequence `git init -b main` → (writes) → `git add -A` → `git commit` → `git remote add origin`, never `push`; intent written; missing remote without createRepoOwner → `remote-required`; `--create-repo o` → `gh repo create o/mattstack-team-acme --private` and the printed URL becomes the remote; second call same remote → `created:false` and zero git calls. `publishTeam` runs `set-url` then `push -u origin main`; auth failure message excludes the URL.
+- [ ] **Step 2:** fail. **Step 3:** implement. **Step 4:** green; tsc 0; registry test. **Step 5: Commit** `MAT-383: rt team create|publish — scaffolded team zone, push at Install`
+
+---
+
+### Task 17: `rt team invite` (mint) + forge grant
+
+**Files:**
+- Create: `lib/team/forge.ts`, `lib/team/invite.ts`
+- Modify: `commands/team.ts` (`teamInvite`), `lib/command-tree-def.ts` (`team invite`)
+- Test: `lib/team/__tests__/forge.test.ts`, `lib/team/__tests__/invite.test.ts`
+
+**Interfaces:**
+- Produces:
+
+```ts
+// lib/team/forge.ts
+export type ForgeAccess = "granted" | "manual" | "skipped";
+export async function grantRead(p: Probes, remote: string, handle: string): Promise<{ access: ForgeAccess; manualSteps: string[] }>
+//  github: p.exec(["gh","api","-X","PUT",`/repos/${owner}/${repo}/collaborators/${handle}`,"-f","permission=pull"]) code 0 → granted; 127/non-0 → manual with steps ["Open https://github.com/<o>/<r>/settings/access","Invite <handle> with Read"]
+//  gitlab: id = p.exec(["glab","api",`users?username=${handle}`]) → [{id}]; p.exec(["glab","api","-X","POST",`projects/${encodeURIComponent(path)}/members`,"-f",`user_id=${id}`,"-f","access_level=20"]) → granted; else manual steps for the GitLab members page
+//  unparsable remote → skipped
+export async function revokeRead(p: Probes, remote: string, handle: string): Promise<{ access: ForgeAccess; manualSteps: string[] }>   // DELETE collaborator / members/<id>
+export async function forgeLogin(p: Probes, provider: "github" | "gitlab", host: string): Promise<string | null>   // gh api user → login ; glab api user → username
+// lib/team/invite.ts
+export const INVITE_TTL_DAYS = 7;
+export function pasteBlock(code: string, downloadUrl = "https://github.com/m4ttstack/rt/releases/latest"): string
+//  `Install mattstack from ${downloadUrl}, then open mattstack://join/${code} or paste the code into Setup → Join a team.\n\nInvite code:\n${code}`
+export interface InviteResult { code: string; expiresAt: string; pasteBlock: string; forgeAccess: ForgeAccess; manualSteps: string[] }
+export async function mintInvite(p: Probes, relay: RelayClient, opts: { slug: string; handle: string; now: Date }): Promise<InviteResult>
+//  1. snapshot = readTeamSnapshot(p, slug); remote required (UserActionableError("no-team-remote")); owner = forgeLogin(...) ?? p.env.USER
+//  2. pointer = {v:1, team:slug, name:<board.title or slug>, remote, owner, forge:host, createdAt}
+//  3. existing record for handle → relay.delete(old id, creatorSecret) (replace-on-mint; ignore "gone")
+//  4. key = generateKey(); ct = seal(pointer,key); {id, creatorSecret} = relay.create(ct, expiresAt= now+7d)
+//  5. grantRead(...); roster: setSetting("board.members", [...existing, {username: handle}], "team", {team: slug}) unless already present
+//  6. upsertInviteRecord(slug, handle, {id, creatorSecret, keyB64, expiresAt}); return {code: encodeCode(id,key), ...}
+```
+`commands/team.ts`: `teamInvite(args)` → `rt team invite --handle <h> [--team <slug>] [--json]`; human output prints the paste block and the manual steps when `forgeAccess !== "granted"`.
+
+- [ ] **Step 1: Failing tests.** forge: github remote → exact gh argv; gitlab → users lookup then members POST with `access_level=20`; gh 127 → manual with the settings URL. invite: fake relay records `create` body has `ciphertext` (base64, not containing "remote" or the host plaintext — assert `!body.includes(host)`), `expiresAt` = now+7d ISO; roster write via a `writeSetting` seam spied to receive `board.members` with the handle appended; replace-on-mint deletes the prior id; result code decodes back to the relay id and opens the pointer; paste block contains `mattstack://join/`.
+- [ ] **Step 2:** fail. **Step 3:** implement. **Step 4:** green; tsc 0. **Step 5: Commit** `MAT-383: rt team invite — opaque relay invite, forge grant at mint`
+
+---
+
+### Task 18: `rt team join` (dry-run + redeem)
+
+**Files:**
+- Create: `lib/team/join.ts`
+- Modify: `commands/team.ts` (`teamJoin`), `lib/command-tree-def.ts` (`team join`)
+- Test: `lib/team/__tests__/join.test.ts`, `commands/__tests__/team-join.test.ts`
+
+**Interfaces:**
+- Produces:
+
+```ts
+export interface JoinResult { team: { slug: string; name: string; owner: string }; access: "ok" | "denied" | "unreachable"; peering: "applied" | "idle" | "unavailable"; message: string }
+export async function joinDryRun(p: Probes, relay: RelayClient, code: string): Promise<JoinResult>
+//  decodeCode → relay.fetch(id) ("gone" → UserActionableError("invite-unknown", "invite not recognized or expired: ask the team owner for a new one")) → open(ct,key) (bad → same message) → git ls-remote --exit-code <pointer.remote> HEAD (GIT_TERMINAL_PROMPT=0):
+//  0/2 → access ok; auth stderr → "denied" with message "you don't have access yet: ask <owner> to grant you access to <name>" (no URL, no git output); else "unreachable"
+//  on ok: writeIntent({mode:"join", join:{id, keyB64, pointer}}); peering:"idle" (dry-run never applies); message "Joining <name> (owner <owner>)"
+export async function joinRedeem(p: Probes, relay: RelayClient, secrets: SecretsSeams, opts: { code?: string }): Promise<JoinResult>
+//  source = opts.code ? decode+fetch+open : readIntent().join (UserActionableError("no-join-intent") when neither)
+//  1. clone: dir = teams/<pointer.team>; exists with same origin → skip; else `git clone <remote> <dir>`; auth failure → access denied result (exit 2 payload carries it)
+//  2. relay.redeem(id) → "already" → UserActionableError("invite-used", "this invite was already used: ask <owner> for a new one") — but only when the clone did NOT already exist (re-running after a crash must not brick)
+//  3. materialize: claude.marketplaces/claude.plugins from the team store are applied by apply's plugins.install step (not here); `rt skills materialize` runs in apply; here only record intent done
+//  4. peering: snapshot.integrations.switchboard?.url and a team secret rt.switchboardAdminToken readable (readTeamSecret) → POST <url>/peer/join {member: forgeLogin} with Bearer admin token → "applied"; url absent → "idle"; request fails → "unavailable"
+//  5. reply blob: publicKey from ensureAgeKey (lib/home/age-key.ts — mints if absent; requires keychain) → sealReply({v:1, agePublicKey, handle: forgeLogin}, key) → relay.reply(id, blob)
+//  6. clearIntent() only when called from apply (opts.fromApply) — the CLI form clears at the end too
+```
+`commands/team.ts`: `teamJoin(args)` → `rt team join [--dry-run] [--json]`; code from stdin JSON `{"code"}` or a no-echo prompt on TTY; **never from argv** (an argv code → UserActionableError("code-on-argv", "pass the invite code on stdin, never as an argument")). Tree: `join: { description: "Redeem an invite (code on stdin, never an argument)", args: [{flag:"--dry-run"...}, json] }`.
+
+- [ ] **Step 1: Failing tests.** dry-run: fake relay returns the sealed pointer → result `access:"ok"`, message "Joining Acme (owner matt)", intent written with the pointer and key; relay "gone" → `invite-unknown`; ls-remote auth stderr → `access:"denied"`, message has no URL; redeem: `git clone` argv recorded; `relay.redeem` called after clone; reply blob posted (fake relay records; `openReply` with the key yields the fake public key); switchboard url + admin token → `peering:"applied"` with `POST <url>/peer/join`; no url → "idle"; `teamJoin(["ABC"])` → exit 2 `code-on-argv`.
+- [ ] **Step 2:** fail. **Step 3:** implement. **Step 4:** green; tsc 0. **Step 5: Commit** `MAT-383: rt team join — dry-run validation, redeem, reply key exchange, peering`
+
+---
+
+### Task 19: `rt team members sync|remove` + `rt team status`
+
+**Files:**
+- Create: `lib/team/members.ts`
+- Modify: `commands/team.ts` (`teamMembersSync`, `teamMembersRemove`, `teamStatus`), `lib/command-tree-def.ts` (`team members sync|remove`, `team status`)
+- Test: `lib/team/__tests__/members.test.ts`, `commands/__tests__/team-status.test.ts`
+
+**Interfaces:**
+- Produces:
+
+```ts
+export async function membersSync(p: Probes, relay: RelayClient, secrets: SecretsSeams, slug: string): Promise<{ added: string[]; pending: string[]; reencrypted: string[] }>
+//  for each invite record: relay.readReply(id, creatorSecret) → openReply(blob, key) → addTeamRecipient(slug, agePublicKey) → removeInviteRecord; "none" → pending
+//  also ensures the OWNER's own key is a recipient (ensureAgeKey publicKey) — a fresh team has zero recipients until this runs
+export async function membersRemove(p: Probes, secrets: SecretsSeams, slug: string, handle: string, agePublicKey?: string): Promise<{ forgeAccess: ForgeAccess; manualSteps: string[]; reencrypted: string[]; rosterRemoved: boolean; residueNote: string }>
+//  revokeRead(remote, handle); roster: setSetting board.members without the handle; recipient: removeTeamRecipient when agePublicKey given (else when the roster entry carries `agePublicKey` — membersSync stores it on the roster entry {username, agePublicKey}); reencryptTeamSecrets; residueNote = "Removed members keep any secrets they already decrypted; rotate the values themselves with `rt secrets rotate --team <slug> <domain> <key>`."
+```
+Tree: `members: { description: "Roster: collect invitee keys / remove a member", subcommands: { sync: {fn:"teamMembersSync", args:[team, json]}, remove: {fn:"teamMembersRemove", args:[{name:"Handle", type:"text"}, team, json]} } }`.
+
+`teamStatus(args)` → `rt team status [--team <slug>] --json` (the app's Settings → Team pane reads it; contract verb) prints `envelope({ slug, name, remote, lastPush, members: [{username}] })`: `slug`/`name` from `readTeamSnapshot` (`name` = `board.title` ?? slug), `remote` = the raw origin URL (masking is the app's job), `lastPush` = `p.exec(["git","-C",teams/<slug>,"log","-1","--format=%cI","origin/main"])` stdout trimmed or `null` when it fails, `members` = `getSetting("board.members").value ?? []` mapped to `{username}`; no team cloned → UserActionableError("no-team"). Tree node `team.status: { description: "Team summary (name, remote, last push, members)", fn: "teamStatus", args: [team, json] }`.
+
+- [ ] **Step 1: Failing tests.** sync with one record whose reply exists → `added:["<key>"]`, `sops updatekeys` called, record removed; no reply → pending; owner key always present afterwards. remove → revoke argv, roster write without the handle, updatekeys run, residueNote non-empty. `team-status.test.ts`: `teamStatus(["--json"])` with a fake snapshot + `git log` stdout `2026-08-21T10:00:00+00:00` → envelope `{slug, name, remote, lastPush, members:[{username:"matt"}]}`; `git log` failing → `lastPush:null`; no team → exit 2 `no-team`.
+- [ ] **Step 2:** fail. **Step 3:** implement. **Step 4:** green; tsc 0; registry. **Step 5: Commit** `MAT-383: rt team members sync|remove + team status — recipients follow the roster`
+
+---
+
+### Task 20: `rt repos register`, `rt skills materialize`, `rt cron install`
+
+**Files:**
+- Create: `commands/repos.ts`, `commands/skills.ts`, `commands/cron.ts`, `lib/setup/skills-materialize.ts`, `lib/setup/cron-install.ts`
+- Modify: `lib/command-tree-def.ts` (`repos`, `skills`, `cron` nodes), `lib/module-registry.ts` (three entries)
+- Test: `commands/__tests__/repos.test.ts`, `lib/setup/__tests__/skills-materialize.test.ts`, `lib/setup/__tests__/cron-install.test.ts`
+
+**Interfaces:**
+- Produces:
+
+```ts
+// commands/repos.ts
+export async function reposRegister(args: string[], _ctx?: CommandContext, deps = realRegisterDeps()): Promise<void>
+//  rt repos register <path…> [--track live|poll] [--caches branches,project-mrs] [--json]
+//  per path: name = basename(realpath); updateRepoIndex(name, path) (lib/repo-index.ts); --track → loadRepoTracking()/saveRepoTracking() with {mode, caches} (signatures stable across the keys wave); prints envelope({registered:[{name,path,tracking}]})
+// lib/setup/skills-materialize.ts
+export function findMergeManifests(p: Pick<Probes,"readDir"|"exists"|"home"|"env">): string | null
+//  RT_MERGE_MANIFESTS env, else highest semver dir under ~/.claude/plugins/cache/mattstack/mattstack/*/plugin/skills/parameterized-skills/scripts/merge-manifests.sh
+export async function materializeSkills(p: Probes, opts: { repo?: string }): Promise<{ repos: { name: string; path: string; ok: boolean; detail: string }[] }>
+//  targets = opts.repo ? [that registered repo] : getKnownRepos(); for each: p.exec(["bash", script, "--repo", path], {env:{MATTSTACK_HOME: ~/.mattstack}}) — exit 2 ("no git remote") → ok:false detail from stderr (not fatal); script missing → UserActionableError("merge-manifests-missing", "install the mattstack plugin first (plugins.install)")
+// commands/skills.ts: skillsMaterialize(args) → rt skills materialize [--repo <name>] [--json]
+// lib/setup/cron-install.ts
+export interface TriageTrigger { name: "board-triage"; event: "project-mrs"; run: string[]; debounceMs: 5000 }
+export function triageTrigger(boardBinary: string): TriageTrigger   // run: [boardBinary, "triage", "--once"]
+export function installCronTrigger(trigger: { name: string; event: string; run: string[]; repoName?: string; debounceMs?: number }): { written: boolean; reason?: string }
+//  def = getDef("rt.cron"); !isMigrated(def) → {written:false, reason:"rt.cron is not migrated to the settings stores yet (settings lane in flight)"}; else current = getSetting("rt.cron").value ?? {triggers:[]}; replace-by-name; setSetting("rt.cron", {triggers}, "machine"); print "restart the daemon to apply: rt daemon restart"
+// commands/cron.ts: cronInstall(args) → rt cron install <trigger> [--json]  (trigger ∈ "board-triage"; binary from resolveTool(p,"board").chosen — UserActionableError("board-missing") when null)
+```
+Tree nodes: `repos: { description: "Register repos with rt (index + tracking)", subcommands: { register: {...} } }`; `skills: { description: "Skill bindings", subcommands: { materialize: {...} } }`; `cron: { description: "Daemon cron triggers", subcommands: { install: { args:[{name:"Trigger", type:"select", options:[{value:"board-triage", label:"board-triage"}]}, json] } } }`.
+
+- [ ] **Step 1: Failing tests.** `reposRegister` with a temp git repo under the test HOME → repos.json (test HOME) contains the name; `--track poll --caches branches,project-mrs` → `loadRepoTracking()` shows the entry. `findMergeManifests` picks `0.4.1` over `0.3.1` from fake dirs; `materializeSkills` records `bash <script> --repo <path>` with `MATTSTACK_HOME`. `installCronTrigger` when `isMigrated(getDef("rt.cron"))` is false → `{written:false}` (spy `isMigrated` via a seam param `deps.isMigrated`); when true → `setSetting` seam called with machine scope and the trigger replaced by name.
+- [ ] **Step 2:** fail. **Step 3:** implement. **Step 4:** green; tsc 0; registry test. **Step 5: Commit** `MAT-383: rt repos register, rt skills materialize, rt cron install`
+
+---
+
+### Task 21: `rt tools install|setup`
+
+**AFTER L1 T5 and L4 T11 merge** (uses `resolveTool(...).exec` / `link` from Task 5).
+
+**Files:**
+- Create: `lib/setup/tools-install.ts`, `commands/tools.ts`
+- Modify: `lib/command-tree-def.ts` (`tools` node), `lib/module-registry.ts`
+- Test: `lib/setup/__tests__/tools-install.test.ts`
+
+**Interfaces:**
+- Produces:
+
+```ts
+export const VENDOR_INSTALLERS: Record<string, string[]> = {
+  herdr:  ["sh","-c","curl -fsSL https://herdr.dev/install.sh | sh"],
+  claude: ["sh","-c","curl -fsSL https://claude.ai/install.sh | bash"],
+};
+export const BREW_FORMULAE: Record<string, string> = { herdr: "herdr", claude: "claude-code" };
+export async function installTool(p: Probes, tool: string, reqs: PackRequirements[]): Promise<{ via: "brew" | "vendor" | "apple-clt" | "bundled-link"; ok: boolean; detail: string }>
+//  apple-clt → p.exec(["xcode-select","--install"]) (code 1 "already installed" → ok)
+//  bundledToolExec(p, tool) non-null (the bundle's deps.lock lists it) → link(p, tool) (via bundled-link)
+//  brew present (p.exec(["brew","--version"]) code 0) and formula known (BREW_FORMULAE or reqs tool.install.brew) → ["brew","install",formula]
+//  else VENDOR_INSTALLERS[tool] or reqs tool.install.url → ["sh","-c",`curl -fsSL ${url} | sh`]
+//  else UserActionableError("no-installer", "no install method known for <tool>")
+export async function setupTool(p: Probes, tool: string, opts: { configDirs: string[] }): Promise<{ ok: boolean; detail: string }>
+//  "fast-browser": p.exec([...resolveTool(p,"fast-browser").exec!, "setup"]) — the exec argv prefix ([node, fast-browser.mjs] when bundled), never `chosen` as argv0 (UserActionableError("tool-missing") when exec is null)
+//  "herdr": for each dir: p.exec(["herdr","integration","install","claude"], {env:{CLAUDE_CONFIG_DIR: dir}})
+//  "extension": installExtensionsHeadless(p) — moved from commands/post-install.ts's installExtensions (vsix found at `<appPath>/Contents/Resources/rt-context.vsix` first, then next to the binary) — returns installed editor names and records them in setup-state
+//  else UserActionableError("unknown-tool-setup")
+export function claudeConfigDirs(p: Pick<Probes,"env"|"home">, extra: string[]): string[]   // [CLAUDE_CONFIG_DIR env ?? ~/.claude, ...extra] deduped
+```
+`commands/tools.ts`: `toolsInstall(args)` → `rt tools install <tool> [--json]`; `toolsSetup(args)` → `rt tools setup <tool> [--config-dir <dir>]… [--json]`.
+
+- [ ] **Step 1: Failing tests.** herdr with brew present → `brew install herdr`; without brew → the vendor sh -c line; team tool with `install.brew` → that formula; `gh` → link via bundled-link; apple-clt → xcode-select argv; `setupTool("fast-browser")` with `exec=[node, mjs]` records argv `[node, mjs, "setup"]`; `setupTool("herdr",{configDirs:[a,b]})` runs twice with the env var; extension setup records editors in setup-state.
+- [ ] **Step 2:** fail. **Step 3:** implement (`detectEditors` imported from commands/extension.ts; the headless vsix install uses `p.exec([cli,"--install-extension",vsix,"--force"],{timeoutMs:30000})`). **Step 4:** green; tsc 0; registry test. **Step 5: Commit** `MAT-383: rt tools install|setup — brew/vendor/CLT installs, tool-owned setup`
+
+---
+
+### Task 22: `rt services` facade + need protocol
+
+**Files:**
+- Create: `commands/services.ts`, `lib/setup/need.ts`
+- Modify: `lib/command-tree-def.ts` (`services` node), `lib/module-registry.ts`
+- Test: `commands/__tests__/services.test.ts`, `lib/setup/__tests__/need.test.ts`
+
+**Interfaces:**
+- Produces:
+
+```ts
+// commands/services.ts — every verb: tray status 0 → UserActionableError("app-not-running", "mattstack.app is not running — open it, then retry")
+export async function servicesList(args, _ctx?, deps = realServicesDeps()): Promise<void>       // GET /services → envelope({agents})
+export async function servicesRegister(args, _ctx?, deps?): Promise<void>                          // --plist <name> (repeatable; default servicePlists(currentMode(), p)) → POST /services/register {plists}
+export async function servicesRestart(args, _ctx?, deps?): Promise<void>                           // <label> → POST /services/restart {label}
+// lib/setup/need.ts
+export const SERVICE_PLISTS = ["com.mattstack.daemon.plist", "com.mattstack.deck.plist"] as const;   // dev flavor: ".dev" inserted before ".plist" when currentMode()==="dev"
+export function servicePlists(mode: "dev" | "prod", p: Pick<Probes, "exists" | "home">): string[]  // lives here (lib), consumed by commands/services.ts and steps/services.ts
+//  daemon plist always; the deck plist ONLY when `resolveTool(p,"deck").chosen` is non-null (deck bundled) — otherwise it is omitted and the caller logs "deck not bundled yet — only the daemon is registered" (the app reports ok only when every requested plist registers, so a missing helper must not be requested)
+export interface NeedReply { ok: boolean; detail?: string }
+/**
+ * rt emits the need event on stdout, then polls GET /setup/need/<id> on tray.sock. The app always answers 200
+ * {state: "pending" | "done" | "failed", detail?} (unknown/unstarted ids are "pending"); rt keeps polling while
+ * state is "pending" (a 404 is tolerated as pending too), maps "done" → {ok:true, detail} and "failed" →
+ * {ok:false, detail}. Works identically whether the app answers instantly or holds the GET open.
+ */
+export async function awaitNeed(tray: TrayClient, id: StepId, opts: { timeoutMs?: number; pollMs?: number; sleep?: (ms: number) => Promise<void>; now?: () => number } = {}): Promise<NeedReply | "timeout" | "app-gone">
+//  timeoutMs default 600_000; pollMs 1_000; each GET timeoutMs 30_000; status 0 three times in a row → "app-gone"
+```
+Tree: `services: { description: "App-registered services (daemon, deck) via mattstack.app", subcommands: { list, register, restart } }`.
+
+- [ ] **Step 1: Failing tests.** list with fake tray → envelope with agents; tray 0 → exit 2 `app-not-running`; register default plists body; `servicePlists("dev", p)` with deck resolvable → `com.mattstack.daemon.dev.plist`, `com.mattstack.deck.dev.plist`; with deck not bundled → only `com.mattstack.daemon.dev.plist`. need: fake tray returns 200 `{state:"pending"}` twice then 200 `{state:"done", detail:"registered"}` with a fake sleep → `{ok:true, detail:"registered"}`; 200 `{state:"failed", detail:"denied"}` → `{ok:false, detail:"denied"}`; a 404 followed by `done` → reply (404 tolerated as pending); always `pending` with fake clock past 10 min → "timeout"; status 0 ×3 → "app-gone".
+- [ ] **Step 2:** fail. **Step 3:** implement. **Step 4:** green; tsc 0; registry. **Step 5: Commit** `MAT-383: rt services facade + need-event wait over tray.sock`
+
+---
+
+### Task 23: Apply engine
+
+**Files:**
+- Create: `lib/setup/apply.ts`, `lib/setup/steps/index.ts` (ordered registry; step bodies come in Tasks 24–26 — this task registers a `stubStep(id,title,kind)` for each id that returns `{state:"skipped", detail:"not implemented"}` so the engine is testable; each later task REPLACES its stubs)
+- Test: `lib/setup/__tests__/apply.test.ts`
+
+**Interfaces:**
+- Produces:
+
+```ts
+export type StepOutcome = { state: "done"; detail?: string } | { state: "skipped"; detail: string } | { state: "failed"; detail: string; remedy?: string };
+export interface ApplyContext {
+  p: Probes; emit: Emit; log(id: StepId, line: string): void;
+  intent: SetupIntent | null; team: TeamRef; snapshot: TeamSnapshot | null; reqs: PackRequirements[];
+  nonInteractive: boolean; teamOfOne: boolean; appPath: string | null; ci: boolean;
+  secrets: SecretsSeams; relay: RelayClient;
+  need(id: StepId, request: NeedRequest): Promise<NeedReply | "timeout" | "app-gone" | "no-app">;   // no-app when tray unreachable and nonInteractive → steps skip honestly
+}
+export interface StepDef { id: StepId; title: string; kind: StepKind; applies(ctx: ApplyContext): boolean; run(ctx: ApplyContext): Promise<StepOutcome> }
+export const STEPS: StepDef[]   // contract order; exactly one def per STEP_IDS entry (test asserts)
+export async function runApply(ctx: ApplyContext, opts: { from?: StepId }): Promise<{ ok: boolean; failedStep?: StepId }>
+//  steps = STEPS.filter(s => s.applies(ctx)); emit plan; for each: before `from` → emit step skipped "before --from"; else emit running → run → emit outcome; failed → emit done {ok:false, failedStep}, return; after all → updateSetupState lastApplyAt, clearIntent when ok, emit done {ok:true}
+//  a step that THROWS: UserActionableError → failed {detail: message, remedy: extra.remedy}; other Error → failed {detail:`bug: ${message}`} and rethrow AFTER emitting done (exit 1 semantics preserved)
+export function createApplyContext(deps: { probes: Probes; emit: Emit; secrets: SecretsSeams; relay: RelayClient; flags: { nonInteractive: boolean; teamOfOne: boolean; ci: boolean } }): Promise<ApplyContext>
+```
+
+- [ ] **Step 1: Failing tests.** With a test-only STEPS override (export `runApplyWith(steps, ctx, opts)`): three fake steps → events in order `plan, step running, step done, …, done ok:true`; second step fails → third never runs, `done {ok:false, failedStep}`; `--from` second → first emitted skipped "before --from"; a step throwing `UserActionableError("x","msg",{remedy:"do y"})` → failed with remedy; a step throwing `Error` → done emitted then rethrown; `STEPS.map(s=>s.id)` deep-equals `STEP_IDS`.
+- [ ] **Step 2:** fail. **Step 3:** implement. **Step 4:** green; tsc 0. **Step 5: Commit** `MAT-383: apply engine — NDJSON stream, resume, stop-on-fail`
+
+---
+
+### Task 24: Apply steps A — home, team, secrets, path, intercepts, settings, repos
+
+**AFTER L4 T9 merges** (`bundleRootFromExec` from `lib/bundle-layout.ts` (L4 T1), `installRtBinary` from `lib/dev-mode.ts`, `legacyUserAppPath` from `lib/rt-paths.ts`; rebase onto `origin/main` first).
+
+**Files:**
+- Create: `lib/setup/steps/home.ts`, `steps/team.ts`, `steps/secrets.ts`, `steps/path.ts`, `steps/settings.ts`, `steps/repos.ts`
+- Modify: `lib/setup/steps/index.ts` (replace stubs), `lib/shell-integration.ts` (add `ZSHENV_MARKER`, `installZshenvPrecedence()`, `removeShellIntegration()`, `removeZshenvPrecedence()`; an END marker `# rt — end` is now appended to new blocks)
+- Test: `lib/setup/__tests__/steps-a.test.ts`, `lib/__tests__/shell-integration-remove.test.ts`
+
+Step bodies (exact):
+
+- `home.init` (kind rt; applies: `intent?.mode !== "restore"`): `p.exists(~/.mattstack/.git)` and `readAgeKey` has key → done "already initialized"; else `p.runRt(["home","init"])` (gh path) → code 0 → done (detail last stdout line); else failed, detail stderr head, remedy "Run `gh auth login`, then Retry".
+- `home.restore` (applies: mode restore): **verifier only** — the app (L3 T13) runs the real `rt restore <org>/<repo>` (age key on stdin `{"ageKey"}`) when the user presses Continue on the restore card and then `rt setup intent restore <org>/<repo>`; this step checks that the clone exists (`~/.mattstack/.git` with origin containing `intent.restore.homeRepo`) and the key is present → done "restored"; else failed, remedy "Run `rt restore <org>/<repo>` (pastes your age key), then Retry" — never runs restore itself.
+- `team.create` (applies: mode create OR (teamOfOne && no intent && teams=[])): teamOfOne without intent → `createTeam(p, { name: p.env.RT_TEAM_NAME ?? "personal", remote: p.env.RT_TEAM_REMOTE ?? null, createRepoOwner: p.env.RT_TEAM_REMOTE ? undefined : (await forgeLogin(p,"github","github.com")) ?? undefined, others:false })`; then `publishTeam(p, slug, null)`; failed with remedy on `push-denied`. **Team-of-one with no remote source** (no `RT_TEAM_REMOTE` and `forgeLogin` null because gh is not authenticated — the headless clean-room job) → **skipped** "no git remote available (set RT_TEAM_REMOTE or run gh auth login)" instead of failed, so the run reaches `verify`; `remote-required` is a failure only when an intent explicitly asked for create.
+- `team.join` (applies: mode join): `joinRedeem(p, ctx.relay, ctx.secrets, {fromApply:true})`; access denied → failed "you don't have access yet: ask <owner>…", remedy "Ask the owner to grant access, then Retry".
+- `secrets.write`: `drainStaged(p, (d,k,v) => writeSecret(d,k,v,ctx.secrets))` → done "N staged secrets written" (0 → done "nothing staged"); `NoAgeKeyError` → failed remedy "home.init did not mint a key — Retry from home.init".
+- `path.link`: for tool of DEFAULT_EXPOSED: `link(p, tool)` (rt → `installRtBinary`'s atomic symlink; multi-argv tools → tagged wrapper; dev-mode-owns-rt → log line, not failure; user-copy → skipped per tool with log line); `installShellIntegration()`; `installZshenvPrecedence()` (writes to `~/.zshenv`: `# mattstack — PATH precedence` + `export PATH="$HOME/.local/bin:$PATH"` + end marker, idempotent); done detail "linked: a,b · skipped: c".
+- `intercepts.install`: `installShims()` → done "N shims" ("no commands to shim" when 0).
+- `settings.seed`: `mattstack.appPath` ← `ctx.appPath` (derived: `bundleRootFromExec()` from `lib/bundle-layout.ts` (L4 T1) — no regex of our own — else `getSetting` value if present, else `installedTrayAppPath`) via `setSetting("mattstack.appPath", path, "machine")` when non-null; a transient root (`root.startsWith("/Volumes/") || root.includes("/AppTranslocation/")` — the DMG or a translocated copy, ported from L4's `appPathIsTransient`) is **refused**: in apply → failed "running from <root> — drag mattstack.app to /Applications, then Retry" (remedy "Move mattstack.app to /Applications and relaunch it"), never written; `rt --post-install` exits 2 on it (Task 27); `rt.repoRoots` ← existing ?? detected roots (`~/Documents/GitHub`, `~/GitHub`, `~/code`, `~/src` that exist) via setSetting machine (only when currently unset); done lists what was written.
+- `repos.clone`: root = `getSetting("rt.repoRoots").value?.[0]` (failed "no repo root" otherwise); for each identity in `snapshot.trackingIdentities` (minus `p.env.RT_SKIP_REPOS` comma list — the deselect channel): dest = `<root>/<basename>`; exists → log "present"; else `git clone https://<identity>.git <dest>` (auth failure → log + continue; counted); then `updateRepoIndex(basename, dest)`; done "cloned N, present M, failed K" (failed>0 → still done; detail says so — tracking activates only for resolvable clones).
+
+- [ ] **Step 1: Failing tests** (fake probes + seams; setSetting against the test HOME): `home.init` runs `runRt(["home","init"])` only when `.git` missing; `path.link` records symlinks for fast-browser/gitq/deck and skips `rt` in dev mode; `.zshenv` gets the precedence block once (second call no duplicate); `removeShellIntegration()` strips the block written by `installShellIntegration()` exactly (before/after equality on a fixture with unrelated lines) and returns `{removed:false, manual:true}` for a legacy block without end marker; `settings.seed` writes `mattstack.appPath` (read back via getSetting) from an execPath inside a bundle (inject `bundleRootFromExec` via a seam), and with root `/Volumes/mattstack/mattstack.app` → failed with the drag-to-Applications remedy and nothing written; `team.create` under `teamOfOne` with no `RT_TEAM_REMOTE` and gh unauthenticated → skipped with the "no git remote available" detail; `repos.clone` argv `git clone https://gitlab.com/assured/assured-dev.git <root>/assured-dev` and skips an existing dir; `secrets.write` drains staged values through a fake writer.
+- [ ] **Step 2:** fail. **Step 3:** implement. **Step 4:** green; tsc 0. **Step 5: Commit** `MAT-383: apply steps — home, team, secrets, path, intercepts, settings, repos`
+
+---
+
+### Task 25: Apply steps B — services.register, proxy.install, deck.managed, skills.materialize, board.keys, cron.triage
+
+**Files:**
+- Create: `lib/setup/steps/services.ts`, `steps/deck.ts`, `steps/skills.ts` (skills.materialize + board.keys + cron.triage live here with skills-materialize/cron-install helpers)
+- Test: `lib/setup/__tests__/steps-b.test.ts`
+
+Step bodies:
+- `services.register` (kind app): `ctx.need("services.register", {type:"app-register-services", plists: servicePlists(currentMode(), p)})` — the daemon plist always, the deck plist only when `resolveTool(p,"deck").chosen` is non-null (else `ctx.log` "deck not bundled yet — only the daemon is registered"; the app answers `ok:false` for a plist whose `BundleProgram` is missing, so it must not be requested) → reply ok → done (detail); `"no-app"` → skipped "mattstack.app not running — open it to register services" (nonInteractive) or failed with remedy "Open mattstack.app, then Retry" (interactive); "timeout"/"app-gone" → failed remedy "Retry with mattstack.app running"; then `markDaemonInstalled()` (lib/daemon-config.ts) on done.
+- `proxy.install` (kind privileged): `need(…, {type:"app-privileged", op:"proxy-install"})` same handling; the app runs the bundled installer helper (L3/L5) — rt only waits.
+- `deck.managed`: deck = `resolveTool(p,"deck").chosen` (null → skipped "deck not bundled yet"); for app of `[{name:"board", hostname:"board.mattstack", bin: resolveTool(p,"board").chosen}, {name:"gitq", hostname:"gitq.mattstack", bin: resolveTool(p,"gitq").chosen}]`: bin null → log skip; else `p.exec([deck,"add",name,"--cmd",bin,"--managed-by","mattstack","--host",hostname])` — exit code 0 or stderr /already/ → ok; done "registered: board, gitq". (MAT-384 argv is stubbed behind this one call site; a test pins the argv so the change is one line.)
+- `skills.materialize`: `materializeSkills(p,{})` → done with per-repo summary; `merge-manifests-missing` → skipped "mattstack plugin not installed yet" (plugins.install runs later; `rt skills materialize` is re-run by the verify step? No — honest: skipped with detail; `rt setup pack` re-materializes).
+- `board.keys`: machine-scope keys: `board.rtRepos` ← names of registered repos whose identity ∈ tracking; `board.cwds` ← `{ review: <root>/<first repo>, respond: same, doctor: same }` only when unset; `gitq.board` ← `{ repos: [...same names], port: 11008 }` when unset; `gitq.workSlots` ← `{ workSlotLocation: <root>/.gitq-slots, maxWorkSlots: 3 }` when unset — every write via `setSetting(key, value, "machine")`, each guarded by `getDef(key)` existing and `isMigrated` (missing def → log "key not in registry yet" and continue); done lists written keys.
+- `cron.triage`: applies when `getSetting("board.triage").value?.enabled === true` (key from the board lane; `getDef` missing → skipped "board.triage not registered"); `installCronTrigger(triageTrigger(resolveTool(p,"board").chosen!))` → done / skipped with its reason.
+
+- [ ] **Step 1: Failing tests.** services.register: fake `need` returning `{ok:true}` → done and daemon.json written in test HOME; with deck not bundled the need request's `plists` holds only the daemon plist and a log line mentions "deck not bundled"; "no-app" + nonInteractive → skipped; interactive → failed with remedy. deck.managed: argv pinned for both apps; board missing → detail names only gitq. board.keys: writes `board.rtRepos` via setSetting (read back) and skips `board.cwds` when already set. cron.triage: `board.triage` unset → skipped.
+- [ ] **Step 2:** fail. **Step 3:** implement. **Step 4:** green; tsc 0. **Step 5: Commit** `MAT-383: apply steps — services, proxy, deck managed apps, skills, board/gitq keys, triage cron`
+
+---
+
+### Task 26: Apply steps C — plugins, fast-browser, herdr, extension, services.start, snapshot.push, verify
+
+**Files:**
+- Create: `lib/setup/steps/plugins.ts`, `steps/tools.ts`, `steps/verify.ts`
+- Test: `lib/setup/__tests__/steps-c.test.ts`
+
+Step bodies:
+- `plugins.install`: claude present (`resolveTool`/PATH) else failed remedy "Install Claude Code (Tools row), then Retry". marketplaces = `getSetting("claude.marketplaces").value ?? []` ∪ `[MATTSTACK_MARKETPLACE_SOURCE]` (constant `"https://github.com/m4ttstack/mattstack-marketplace"`, overridable by `RT_MATTSTACK_MARKETPLACE` — see open question 13) ∪ (team slug ? [`~/.mattstack/teams/<slug>`] : []); plugins = `getSetting("claude.plugins").value ?? []` ∪ `["mattstack@mattstack","fast-browser@mattstack"]` ∪ team marketplace plugins (parse `teams/<slug>/.claude-plugin/marketplace.json` → `<plugin.name>@<marketplace.name>`). For each config dir (`claudeConfigDirs(p, [])`): `claude plugin marketplace add <src>` (stderr /already/ → ok), `claude plugin install <p>` (already → ok), `claude plugin enable <p>` (unknown subcommand → ignore). Record in setup-state. Any non-already failure → failed, detail "claude plugin install exited N", remedy "Open Claude Code once so it finishes first-run, then Retry." (the contract's example).
+- `fastbrowser.setup`: `setupTool(p,"fast-browser",…)` (spawns `[...resolveTool(p,"fast-browser").exec, "setup"]`) → done/failed (remedy: "Run `fast-browser setup` in a terminal for details"); `exec` null → skipped "fast-browser not bundled".
+- `herdr.integration`: herdr on PATH → `setupTool(p,"herdr",{configDirs})` → done; missing → skipped "herdr not installed (Tools row)".
+- `extension.install`: `setupTool(p,"extension",…)` → done "installed in …" / skipped "no editor found" / vsix missing → skipped "extension not bundled".
+- `services.start`: `p.tray("/daemon/start",{method:"POST"})` status 200 → poll `isDaemonRunning()` up to 12×250 ms → done "daemon running" / failed remedy "Approve the background item in Login Items, then Retry"; tray 0 → nonInteractive ? skipped : failed remedy "Open mattstack.app".
+- `snapshot.push`: `p.runRt(["home","snapshot","push"])` when that verb exists in the tree (`TREE.home.subcommands.snapshot`) else `git -C ~/.mattstack add -A && commit -m "setup: snapshot" (allow empty → skip) && push` via p.exec; done/failed (remedy "check `git -C ~/.mattstack status`").
+- `verify`: `composePlan({p, secrets: realSecretPresence(), ci: ctx.ci})` → `rowsToChecks` → any critical fail → failed detail "N checks failed: ids" remedy "Run `rt verify` for details"; else done "N checks passed".
+
+- [ ] **Step 1: Failing tests.** plugins: argv sequence per config dir (`marketplace add` ×3, `install` ×3 for one config dir), "already installed" stderr tolerated, exit 1 → failed with the contract remedy text; fast-browser/herdr/extension skip paths; services.start: tray 200 + daemon ping ok → done; snapshot.push uses git fallback when no snapshot verb; verify: a fake plan with one required missing → failed.
+- [ ] **Step 2:** fail. **Step 3:** implement. **Step 4:** green; tsc 0. **Step 5: Commit** `MAT-383: apply steps — plugins, fast-browser, herdr, extension, start, snapshot, verify`
+
+---
+
+### Task 27: `rt setup apply`, `rt setup` (TTY walk), `rt setup intent`, `--post-install` entry
+
+**AFTER L4 T9 merges** (`bundleRootFromExec`, `legacyUserAppPath`; rebase onto `origin/main` first). `commands/post-install.ts` and `lib/__tests__/post-install-sweep.test.ts` are **L1-owned**: L4 T9 dropped them from its Files; their L4 bodies (`appPathIsTransient` refusal, `runLegacySweep(root)`, the new sweep test case, the `bundleRoot` override) are absorbed here verbatim, while `recordAppPath`/`installRtBinaryStep` are **not** re-implemented (they are the `settings.seed` / `path.link` steps).
+
+**Files:**
+- Modify: `commands/setup.ts` (`setupApply`, `setupInteractive` real, `setupIntent`), `commands/post-install.ts` (entry only: legacy sweep + transient-path refusal + `setupApply(["--non-interactive","--team-of-one",...args])`), `cli.ts` (`--post-install` passes remaining args), `lib/command-tree-def.ts` (`setup apply`, `setup intent` hidden)
+- Test: `commands/__tests__/setup-apply.test.ts`, `lib/__tests__/post-install-sweep.test.ts` (existing; keep green — sweep functions are retained — plus the new stale-`~/Applications` case below)
+
+**Interfaces:**
+- Produces:
+
+```ts
+export async function setupApply(args: string[], _ctx?: CommandContext, deps = realApplyDeps()): Promise<void>
+//  --json → NDJSON emitter; else human emitter; --from <stepId> (unknown id → exit 2 "bad-step"); --non-interactive; --team-of-one; --ci; --no-launch
+//  --no-launch (implied by --ci or CI=true): never `open` the app or launch anything GUI — the clean-room runner (L7) and release.yml's headless job depend on this
+//  exit code: done ok → 0; failed → 2 (the stream already carries the payload); bug → 1
+export async function setupInteractive(args: string[], _ctx?: CommandContext, deps = realApplyDeps()): Promise<void>
+//  TTY: print the plan (renderPlanHuman); if !canInstall → list requiredMissing with their action labels and exit 2 (code "not-ready") unless --force; else confirm (lib/rt-render confirm) "Install now?" → setupApply([]) ; non-TTY → behaves as `setup status`
+export async function setupIntent(args: string[], _ctx?, deps?): Promise<void>   // hidden: rt setup intent restore <org>/<repo> | rt setup intent clear  → writes/clears intent; --json envelope
+```
+`commands/post-install.ts` (entry only; signature and bodies ported from L4 T9):
+
+```ts
+export interface PostInstallOptions { bundleRoot?: string | null }   // test override; production passes nothing
+export async function runPostInstall(args: string[], opts: PostInstallOptions = {}): Promise<void>
+//  root = opts.bundleRoot !== undefined ? opts.bundleRoot : bundleRootFromExec()   (lib/bundle-layout.ts)
+//  1. runLegacySweep(root)  2. appPathIsTransient(root) → print "running from <root> — drag mattstack.app to /Applications and run this again" and process.exit(2)
+//  3. setupApply(["--non-interactive","--team-of-one", ...args])   (no recordAppPath / installRtBinaryStep here — settings.seed and path.link are the steps)
+function appPathIsTransient(root: string | null): boolean { return !!root && (root.startsWith("/Volumes/") || root.includes("/AppTranslocation/")); }
+function runLegacySweep(root: string | null): boolean
+//  runs on every post-install, idempotent, BEFORE anything launches or registers:
+//  - unconditional `launchctl bootout gui/<uid>/com.rt.daemon` (ignore failures)
+//  - legacyTrayAppPaths() that exist → osascript quit "rt-tray" (3 s timeout), `pkill -x rt-tray`, `rm -rf` each → swept
+//  - stale = legacyUserAppPath() (~/Applications/mattstack.app): when root && root !== stale && exists(stale) → osascript quit <TRAY_APP_NAME>, `pkill -x <TRAY_APP_NAME>`, `launchctl bootout gui/<uid>/com.mattstack.daemon` (its BundleProgram points into the bundle being deleted; apply re-registers), `rm -rf stale` → swept
+//  every spawnSync passes env: process.env; reportMigrationOutcome() runs when swept
+```
+`root === null` (e.g. `dist/rt` outside a bundle) takes the "not running from inside the app" branches: no sweep of `~/Applications`, no transient refusal, and `settings.seed`/`path.link` report honestly ("not running from inside the app"). `installRtBinaryStep/installTrayApp/installExtensions/installDaemon` bodies are deleted (replaced by steps); `repairShellWrapper` stays (moved into `path.link` as a log-only repair — call it there).
+
+- [ ] **Step 1: Failing tests.** `setupApply(["--json"], {}, deps)` with a fake STEPS override emitting one stub step → stdout lines parse as `plan, step, step, done`; failed step → process exit seam called with 2; `--from bogus` → exit 2 `bad-step`; `setupInteractive` non-TTY prints the status table; `setupIntent(["restore","o/r"])` writes intent mode restore. `post-install-sweep.test.ts` gains L4's case (same fake-bin harness): stale `~/Applications/mattstack.app` under the test HOME + `runPostInstall([], { bundleRoot: "/Applications/mattstack.app" })` → the fake log shows `launchctl bootout … com.rt.daemon`, `rm -rf <stale>`, and `launchctl bootout … com.mattstack.daemon`; and `runPostInstall([], { bundleRoot: "/Volumes/mattstack/mattstack.app" })` → exit seam 2 with the drag-to-Applications message and no apply.
+- [ ] **Step 2:** fail. **Step 3:** implement; `cli.ts`: `--post-install` → `runPostInstall(args.slice(1))`. **Step 4:** green; tsc 0. **Step 5: Commit** `MAT-383: rt setup apply + interactive walk; --post-install is headless apply`
+
+---
+
+### Task 28: `rt setup pack`
+
+**Files:**
+- Create: `lib/setup/pack.ts`
+- Modify: `commands/setup.ts` (`setupPack`), `lib/command-tree-def.ts`
+- Test: `lib/setup/__tests__/pack.test.ts`
+
+**Interfaces:**
+- Produces:
+
+```ts
+export async function setupPackFlow(ctx: ApplyContext): Promise<{ ok: boolean; stage?: string; detail: string }>
+//  1. run the plugins.install step body (export it as installPlugins(ctx)) ; 2. materializeSkills ; 3. pipeline-resolves check: workType = reqs[0]?.workType ?? "feature";
+//  manifest = first registered repo's ~/.mattstack/repos/<slug>/skills.jsonc (p.readFile); pipelines[workType].stages each must resolve to a binding (every stage name appears under bindings with a non-empty value) — missing → {ok:false, stage, detail:`stage "<s>" is unresolved`}
+export async function setupPack(args, _ctx?, deps?): Promise<void>   // --json; unresolved → exit 2 code "stage-unresolved" with {stage}
+```
+- [ ] **Step 1: Failing tests.** manifest with all stages bound → ok; one stage unbound → `stage-unresolved` with the stage name; no manifest → detail "no per-repo manifest yet" ok:false code "no-manifest".
+- [ ] **Step 2:** fail. **Step 3:** implement. **Step 4:** green; tsc 0. **Step 5: Commit** `MAT-383: rt setup pack — plugins + bindings + pipeline-resolves check`
+
+---
+
+### Task 29: `rt uninstall`
+
+**Files:**
+- Create: `lib/setup/uninstall.ts`, `commands/uninstall.ts`
+- Modify: `lib/command-tree-def.ts` (`uninstall` root node), `lib/module-registry.ts`
+- Test: `lib/setup/__tests__/uninstall.test.ts`
+
+**Interfaces:**
+- Produces:
+
+```ts
+import type { UninstallActionId } from "../setup/contract.ts";   // defined in Task 1
+export interface UninstallAction { id: UninstallActionId; title: string; kind: StepKind }
+export function computeUninstallActions(p: Probes, opts: { keepData: boolean }): UninstallAction[]
+//  always: services.unregister (app) "Stop and remove the rt daemon and deck services"; deck.managed-remove when deck resolves; proxy.remove (privileged) when /Library/LaunchDaemons/sh.portless.proxy.plist exists; path.unlink when any our-link exists; shell.remove when rc has the marker; extension.uninstall when setup-state.extensionEditors non-empty or detectEditors finds one; plugins.uninstall when setup-state has plugins/marketplaces; data (only when !keepData) "Delete ~/.mattstack (settings, teams, secrets)"; app.trash when appBundlePath resolves
+export async function runUninstall(ctx: ApplyContext, actions: UninstallAction[]): Promise<{ ok: boolean; failed?: UninstallActionId; stayed: string[] }>
+//  NDJSON via ctx.emit with the action ids as event ids (ApplyEvent.id is EventId = StepId | UninstallActionId); services.unregister → need {type:"app-unregister-services", plists}; deck: `deck remove --managed board`, `… gitq`; proxy.remove → need {type:"app-privileged", op:"proxy-remove"}; path.unlink → unlink each DEFAULT_EXPOSED + every our-link; shell.remove → removeShellIntegration()+removeZshenvPrecedence() (manual → stayed entry); extension.uninstall → `<cli> --uninstall-extension local.rt-context` per editor; plugins.uninstall → `claude plugin uninstall <p>` then `claude plugin marketplace remove <m>` per config dir (only what setup-state recorded); data → p.removeDir(~/.mattstack); app.trash → `osascript -e 'tell application "Finder" to delete POSIX file "<app>"'`; stayed: data when kept, anything manual
+```
+`commands/uninstall.ts`: `runUninstallCommand(args)` → `rt uninstall [--keep-data|--delete-data] [--dry-run] [--json] [--yes]`; dry-run prints `envelope({actions})`; real run on a TTY without `--yes` → confirm prompt listing actions; default keep-data. Confirmation rule: non-TTY + `--keep-data` (or no data flag) needs **no** `--yes`; `--delete-data` needs `--yes` — on non-TTY without it → exit 2 "confirm-required" (the app's Settings sheet is the confirmation, so the app always passes `--yes` with `--delete-data`).
+
+- [ ] **Step 1: Failing tests.** actions list for a fully-installed fake state has all ids except `data` (keepData true); `--delete-data` adds `data`; `runUninstall` argv pins: `deck remove --managed board`, `claude plugin uninstall mattstack@mattstack`, `--uninstall-extension local.rt-context`, Finder osascript; need requests emitted for services/proxy; stayed includes "~/.mattstack (kept)".
+- [ ] **Step 2:** fail. **Step 3:** implement. **Step 4:** green; tsc 0; registry. **Step 5: Commit** `MAT-383: rt uninstall — reverses what the installer did, asks about ~/.mattstack`
+
+---
+
+### Task 30: `rt update` thin
+
+Independent of other lanes: `commands/update.ts` is **L1-owned** (L4's competing rewrite, L4 T10, is dropped; exit codes follow the contract — `2` user-actionable with `--json`, not L4's `1`). L4 T12 regenerates `website/docs/reference/update.mdx` after this task lands.
+
+**Files:**
+- Modify: `commands/update.ts` (rewrite), `lib/command-tree-def.ts` (description "Check for updates via mattstack.app"; `--json` arg)
+- Test: `commands/__tests__/update.test.ts`
+
+**Interfaces:**
+- Produces (deps shape adopted from L4 T10 so its test harness ports unchanged):
+
+```ts
+export const RELEASES_URL = "https://github.com/m4ttstack/rt/releases/latest";
+export interface UpdateDeps {
+  tray: (endpoint: string, method: "GET" | "POST") => Promise<{ ok: boolean; error?: string } | null>;   // trayRequest over tray.sock; null when the app is not running
+  currentMode: () => "dev" | "prod";
+  log: (line: string) => void;
+  exit: (code: number) => never;
+}
+export async function runUpdate(args: string[], _ctx?: CommandContext, deps: UpdateDeps = realDeps): Promise<void>
+```
+Branches: dev mode → message unchanged ("dev mode is active — switch to prod first: rt settings dev-mode prod"), exit 2 (`--json` → `envelope({error:{code:"dev-mode"}})`), never calls the tray; `POST /update/check` → `{ok:true}` → "asked mattstack.app to check for updates (Sparkle) — watch the menu bar" exit 0 (`--json` → `envelope({asked:true})`); tray `null` (app not running) → "Updates come from mattstack.app (Sparkle). Open the app to check, or download the latest DMG: <RELEASES_URL>" and exit 2 with `--json` envelope `{error:{code:"app-not-running"}}`; `res.ok === false` (an older app that predates the route) → "this mattstack.app can't be asked from the CLI (<error>) — use the menu bar: mattstack → Check for Updates…" exit 2 (`--json` `{error:{code:"app-too-old"}}`). Delete `RELEASES_API`, `releaseAssetName`, the tarball download and the `--post-install` re-exec.
+- [ ] **Step 1: Failing tests** for the four branches via the injectable `deps` (harness records `${method} ${endpoint}` calls, log lines, exit code; asserts `POST /update/check`, the releases URL in the not-running branch, "Check for Updates" in the `ok:false` branch, no tray call in dev mode, and exit 2 + `app-not-running` JSON with `--json`). **Step 2:** fail. **Step 3:** implement. **Step 4:** green; tsc 0. **Step 5: Commit** `MAT-383: rt update asks the app`
+
+---
+
+### Task 31: Human TTY polish + `dev-mode` TTY relaxation + reference regeneration
+
+**AFTER L4 T12 merges** (`README.md` and `website/docs/getting-started/install.mdx` are L4's; L1 does **not** edit README). Rebase onto `origin/main` first; whoever merges second re-runs `docs:gen`/`docs:check`.
+
+**Files:**
+- Modify: `commands/setup.ts` (`renderPlanHuman` uses tui colors; `rt setup status` footer names `rt setup <integration> connect` for missing accounts), `lib/command-tree-def.ts` (`settings dev-mode`: drop `requiresTTY` when the `<dev|prod>` Target arg is given — the app's Settings pane runs `rt settings dev-mode dev|prod` non-interactively; prompt only when Target is omitted), regenerate docs: `bun scripts/gen-docs.ts`, `bun scripts/check-docs.ts`
+- Test: `commands/__tests__/settings-dev-mode.test.ts` (non-TTY + explicit Target → no prompt, switches; non-TTY + no Target → exit 2 "target-required")
+- [ ] Run `bun run docs:gen` → reference pages for every new verb exist (incl. `team status`, `update`); `bun run docs:check` clean; **assert** (do not edit) that L4 T12 already removed `tmux|zellij|terminal-notifier|brew install fzf` from README/website docs: `grep -rn 'tmux\|zellij\|terminal-notifier\|brew install fzf' README.md website/docs` → no hits (a hit means L4 T12 has not merged — stop and rebase, don't patch README here).
+- [ ] Commit `MAT-383: docs + reference pages for the setup verbs`
+
+---
+
+### Task 32: e2e + full gates
+
+**Files:**
+- Create: `e2e/tests/setup.test.ts` (spawns `dist/rt` with an isolated HOME, `RT_SKIP_SETUP=1`, `CI=true`, `RT_APP_SOCKET=/nonexistent.sock`): `rt setup plan --json` exits 0, one JSON line, `contract===1`, groups ids in order, `perm.fda` status `error` (no app) with the `run` action; `rt setup apply --json --non-interactive --team-of-one --from verify` streams `plan` then `step verify …` then `done`; `rt deps resolve fzf --json` parses; `rt team join` with a code on argv exits 2 with `code-on-argv`; `rt uninstall --dry-run --json` lists actions; `rt update --json` exits 2 `app-not-running`.
+- [ ] `rm -f dist/rt && bun run build` (whatever `scripts`/README says builds `dist/rt` — check `package.json`/README for the compile command; typically `bun build --compile cli.ts --outfile dist/rt`) then `bun run test:all` green; `bun x tsc --noEmit` 0.
+- [ ] Rebase onto `origin/main` (settings lane landed overnight): resolve, rerun all gates.
+- [ ] Commit `MAT-383: e2e — setup verbs end to end from the compiled binary`
+
+---
+
+### Task 33 (ORCHESTRATOR-ONLY, live machine): smoke against the real tray + keychain
+
+Not a subagent task. From the worktree with the real HOME:
+1. `bun run cli.ts setup plan --json | jq .` — rows render; `perm.*` come from the live app once L3 serves `GET /permissions` (until then they report `error` with the re-check action — expected and honest).
+2. `bun run cli.ts verify` — same verdicts as before the refactor for daemon/app/fzf/extension/shell/intercepts (compare against a pre-branch `rt verify` run saved in the scratchpad).
+3. `bun run cli.ts deps resolve fzf --json`; `… deps link gh` (expect `user-copy` refusal on Matt's machine — brew gh exists).
+4. `bun run cli.ts team create demo-team --remote <empty throwaway repo URL> --json` on a throwaway GitHub repo, then `team invite --handle <matt's handle>`, then from a second HOME (`HOME=/tmp/h2 bun run cli.ts team join --dry-run` with the code on stdin) — expect `access:"ok"` once L6's relay is deployed; until then `relay-unreachable` exit 2 is the expected honest result. Delete the throwaway team dir afterwards.
+5. Merge checkpoint: rebase onto `origin/main`, gates green, open the PR (Matt's checkpoint).
+
+---
+
+## Execution order note
+
+Tasks are numbered for reading; execute in this order to honor in-lane dependencies: 0 → 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 → 11 → **13 (team secrets) before 12** → 12 → 14 → 15 → 16 → 17 → 18 → 19 → 20 → 21 → 22 → 23 → 24 → 25 → 26 → 27 → 28 → 29 → 30 → 31 → 32 → 33.
+
+Cross-lane gates (binding; see the "Execution order (cross-plan)" paragraph at the top and `2026-08-21-cross-plan-review.md` §3): Phase A = 1–4, 6, 9, 13–19 can start immediately off `origin/main`; **Task 5 waits for L4 T1 + T9**; **Tasks 7, 8, 10, 11, 21 wait for Task 5 and L4 T11**; **Tasks 24, 27 wait for L4 T9**; **Task 31 waits for L4 T12**; Tasks 22, 23, 25, 26, 28–30, 32 have no external gate. Rebase onto `origin/main` before every merge. In practice this means Phase A first (T1–T4, T6, T9, T13–T19 — T13 before T12 still holds, so T12 joins the second wave), then the rest in numeric order once the L4 gates have merged.
+
+## Self-review
+
+**Spec coverage (§ → task):** §4.3 rows: mac (6, 8), accounts incl. owner-once Slack + switchboard + team-declared connects (9, 12), access (9), tools incl. herdr/claude/fast-browser/editor/Chrome/Control+Up/team tools/MCP-inside-pack (8); permission merge via GET /permissions (6); §4.4 every listed install step (24–26) in the contract's order (23); failed-step remedy + `--from` resume (23, 27); §4.2 create/join/restore inputs (16, 18, 27 intent), join failure strings (18), `--dry-run` with code on stdin (18); §5.2 verb table: setup plan/status/connect/slack create-app/pack/apply/TTY (10, 12, 27, 28), team create/join/invite/members/publish/status (16–19), repos register (20), skills materialize (20), cron install (20), tools setup (21), deps resolve/link/unlink (5), services (22), update (30), uninstall (29), verify (11); §5.3 routes consumed: /permissions (6), /services* (22), /setup/need (22), /update/check (30); §6 invite model (14, 15, 17, 18), replace-on-mint, 7-day expiry, roster, reply key exchange (17–19); §7 four-way policy: bundled by absolute path + default-exposed links + auto-unlink reconcile on verify/daemon start (5, 7), provision via brew/vendor (21), CLT (6, 21), team-declared (4, 8, 21); §9 rows + honest fallback (6); §10 team-scope secrets N recipients + rotate --team + residue note (13, 19); §11 `--post-install` → headless apply (27), `rt update` thin (30); §12.3 uninstall list (29); §13 L1 contents all present; contract envelope/exit codes/step ids/NDJSON/stdin-only secrets (1, 2, 27). **Gaps:** `rt restore` itself, `rt home snapshot push`, board/gitq/deck binaries, the relay endpoints, the app's routes — all other lanes; L1 consumes them behind honest guards (24, 26).
+
+**Placeholder scan:** no TBD/TODO; every step has code or exact argv/assertions; the Task 23 stubs are explicitly replaced by 24–26 (the `STEPS` id test enforces completeness); "similar to" is not used — each step body is spelled out.
+
+**Type consistency:** `Row/Plan/Action/ApplyEvent/StepId/NeedRequest` defined once in Task 1 and used by name in 6–11, 22–29; `Probes`/`TrayClient` from Task 2 everywhere; `SetupIntent/InvitePointer` (3) used by 9, 16, 18, 24, 27; `TeamSnapshot` (9) used by 17, 23, 25; `RelayClient` (15) by 17–19, 23; `SecretsSeams` is the existing store type; `resolveTool/link/reconcile` (5) by 7, 8, 21, 24, 25, 29; `StepOutcome/ApplyContext/STEPS` (23) by 24–29; `rowsToChecks` (11) by 26; `servicePlists` (22) by 25, 29; `setupTool/installTool` (21) by 26; `materializeSkills/installCronTrigger` (20) by 25, 28.
+
+## Open questions (spec gaps found while planning)
+
+1. **`need` reply direction — RESOLVED** (cross-plan review, L3 T9 + contract): rt polls `GET /setup/need/<id>` on tray.sock; the app always answers 200 `{state: pending|done|failed, detail}` (unknown ids are `pending`, `POST` → 405); rt keeps polling until `done|failed` and tolerates a 404 as pending. Task 22 implements exactly this.
+2. **Invite code length — RULED (R5): stays 77 chars.** 16-byte id + 32-byte key = 77 base32 chars (chunked); L6 returns 16-byte ids (32 hex). The spec's "~40 chars" wording is amended to 77 in the appspec branch.
+3. **Relay base URL.** Not in the spec; pinned `https://switchboard.mattstack.dev` with `RT_INVITE_RELAY_URL` override. L6 to confirm (and whether `GET /v1/invites/:id/reply` + a creator-secret Bearer is the agreed owner read path — the spec only names the reply POST).
+4. **Join-intent persistence.** The decrypted pointer + invite key live in `~/.mattstack/rt/setup-intent.json` (0600, runtime) between screen 2 and Install. Alternative: the app re-supplies `{"code"}` on apply's stdin. The plan uses the file; confirm.
+5. **Restore card protocol — RULED (R3):** the app (L3 T13) runs the real `rt restore <org>/<repo>` (age key on stdin `{"ageKey"}`) when the user presses Continue on the restore card, then `rt setup intent restore <org>/<repo>`; L1's `home.restore` step only verifies (Task 24). Still open with the settings lane: the exact `rt restore --json` / stdin-key flags once R lands, and whether it materializes plugins itself (then `plugins.install` is idempotent anyway).
+6. **Home remote without gh.** `rt home init` is gh-only today; the wizard's "paste a URL" path for the home repo needs a `--remote <url>` on `rt home init` (settings lane) — L1 passes it through when it exists.
+7. **`board.members` entry shape** (`{username}` + `agePublicKey` added by members sync) and `board.triage.enabled` as the triage-cron gate — board lane to confirm key shapes; guarded by `getDef` so nothing breaks if they differ.
+8. **`deck add` argv for managed apps** (`--managed-by mattstack --host board.mattstack`) is MAT-384's; pinned in one call site + one test.
+9. **First-run auto-setup** in `cli.ts` no longer auto-runs a full install (it would create GitHub repos silently); it now prints a one-line hint. Accepted by the cross-plan review (§4 #7): L4 T12's README "Testing the installer" describes `rt --post-install` as the headless `rt setup apply --non-interactive --team-of-one` and does not promise auto-setup on first `rt` run.
+10. **Multi-team machines:** `rt setup plan` takes the first cloned team alphabetically unless `--team`; the picker is deferred (spec §14).
+11. **Headless `--team-of-one` defaults:** team name `personal`, gh-created `<login>/mattstack-team-personal` unless `RT_TEAM_NAME`/`RT_TEAM_REMOTE` are set. The clean-room runner has no gh auth and sets neither env var, so `team.create` is **skipped** with detail (Task 24) rather than failed — the headless job reaches `verify`.
+12. **Team-scope secrets file layout** (`teams/<slug>/.sops.yaml` + `teams/<slug>/mattstack/secrets/<domain>.json`) must be acknowledged by the settings lane before Task 13 merges (spec §14 coordination note).
+13. **Mattstack marketplace source.** The MAT-360 meta repo URL is not final; pinned as `https://github.com/m4ttstack/mattstack-marketplace` behind `RT_MATTSTACK_MARKETPLACE`. L5 to confirm, and to confirm `claude plugin marketplace add <git-url>` is the supported form (today's marketplace is a local directory).
+14. **`claude plugin list` / `claude auth status` output shapes** are probed defensively (unknown subcommand → "not checked", honest detail); if Claude Code exposes `--json` for these, tighten the parsers in Task 8.
diff --git a/docs/superpowers/specs/2026-08-20-mattstack-app-installer-design.md b/docs/superpowers/specs/2026-08-20-mattstack-app-installer-design.md
new file mode 100644
index 00000000..6e5bef49
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-20-mattstack-app-installer-design.md
@@ -0,0 +1,742 @@
+# mattstack.app: suite installer, onboarding, permissions, updater
+
+Status: design, ratified decision-by-decision with Matt on 2026-08-20 (sixteen
+forms; answers recorded in §2), then validated against every Linear ruling and
+a full local setup survey the same day (rulings V1–V4 added; gaps folded in;
+ticket amendments listed in §13.3). Supersedes the board wizard (MAT-382 r.5 face)
+and the curl front door (MAT-360). Extends MAT-383 (phase 1 rebrand shipped
+2026-08-20) into phase 2. Research records that ground this design live in
+`research/2026-08-20-mattstack-app/` next to this file: Linear rulings, local
+inventory, dependency inventory, macOS onboarding/permissions UX, Sparkle/
+install/launchd conventions.
+
+## 1. Purpose and scope
+
+mattstack.app (the rebranded rt-tray, `com.mattstack.app`) becomes the one way
+the suite is installed, set up, kept permitted, and updated. A person downloads
+a DMG, opens the app, and a setup window walks them to a working machine: rt on
+PATH and its daemon running, deck/board/gitq running as services, the mattstack
+skills pack and their team's pack installed into Claude Code, the editor
+extension installed, macOS permissions granted, accounts connected, team joined
+or created, and `rt verify` green. From then on the app keeps itself and every
+bundled tool current via Sparkle.
+
+Audience, from day one: (a) Matt's teammates, invited by Matt, who never see a
+git remote; (b) cold users with no team who create a team of one; (c) Matt in
+dev mode. **One build target.** Team dogfood is a release gate, not a phase.
+Public release follows dogfood without a rewrite.
+
+In scope: the setup window and its five screens, the readiness checklist model
+and its rt verbs, team create/join and the invite system, the dependency
+bundling policy, launchd service registration, the permission rows, secrets via
+RT-32, distribution (DMG + Sparkle), identity freeze, dev mode, clean-room
+testing, uninstall, and the work lanes. Out of scope: redesigning the tray's
+day-to-day UI (process panel, menu), the board/gitq/deck products themselves
+beyond giving them releasable artifacts, and the peering relay's encryption
+(recorded as a constraint on that lane).
+
+## 2. Rulings (locked 2026-08-20)
+
+| # | Decision | Ruling |
+|---|---|---|
+| 1 | Milestones | One build target, public-ready; dogfood = release gate. |
+| 2 | Install shape | Suite-only (MAT-379 r.1 stands). Team settings decide what is *live*; no component checkboxes; unused services show as idle, not absent. |
+| 3a | Invites | Shared mattstack switchboard (Railway) hosts **opaque** invites: client-encrypted team pointer, relay stores ciphertext + timestamps only; code = id + key; one-time, 7-day expiry, replace = revoke; static landing page `mattstack.dev/join#<code>`. |
+| 3b | Git remotes | **Required up front** for both user and team repos, explained in the wizard: mattstack keeps your settings in git for safety and for a paper trail (skill edits and every change visible in history). `gh` one-click private repo when authenticated, else paste a URL. |
+| 4 | Checklist | The readiness checklist is the wizard's spine: rt computes it (`rt setup plan --json`); every row has a real validator; Install is disabled until required rows are green; bare `rt setup` and `rt verify` run the same validators. |
+| 5 | Architecture | Thin native shell over rt verbs. Swift owns menu bar, windows, Sparkle, SMAppService, tray-socket API; every mechanic is an rt verb; permission status flows back to rt over the socket. The relay is something rt's invite verbs talk to, never an app runtime dependency. |
+| 6 | Build tooling | Xcode project generated from a committed `project.yml` (xcodegen); `build.sh` wraps `xcodebuild`; `check-bundle.sh` keeps asserting the bundle contract. Matt installs Xcode 26. |
+| 7 | Distribution | The app IS the release (rt + helpers + suite binaries + extension inside). Notarized, stapled DMG for first install; zip enclosure + CI-signed appcast for Sparkle 2.9; `~/.local/bin/rt` is a symlink into the bundle; app re-registers + kickstarts agents when its version changes; `rt update` asks the app. **arm64-only** for now. |
+| 8 | Dependencies | Four-way policy (§7): BUNDLE for internal use by absolute path; PATH exposure per tool opt-in, tagged, yields to the user's copy — **except the default-exposed set `rt`, `fast-browser`, `gitq`, `deck` (V2), linked by Install because shipped skills call them bare**; PROVISION herdr + Claude Code via brew-if-present else vendor installer, version floors only; SYSTEM git/python3 via Apple CLT; TEAM-DECLARED tools from the pack's requirements. Deck's proxy via **one admin prompt**. tmux/zellij/terminal-notifier dropped. |
+| 9 | Services | SMAppService registers rt daemon + deck (one plist each in the bundle, one Login Items switch, FDA inherits); deck supervises board + gitq as managed deck apps (MAT-384); app monitors deck like the daemon; plist `EnvironmentVariables.PATH` is static (`/usr/bin:/bin:/usr/sbin:/sbin`; no hardcoded `/Applications/…`) and rt + deck prepend `<bundleRoot>/Contents/Helpers` (from their own execPath) and `$HOME/.local/bin` at process start; portless proxy is a root LaunchDaemon owned by the privileged step. |
+| 10 | Permissions | Full Disk Access + Login Items required; Notifications optional. No Accessibility/Screen Recording/Automation. |
+| 11 | Secrets | RT-32 as ruled: sops/age-encrypted in the user repo, age key generated at setup into the macOS Keychain, plaintext never in git; `secrets.json` is a one-time migration source; invitee's age public key is added as a recipient for team-scoped secrets. |
+| 12 | Dev + testing | Dev identity stays (mattstack-dev.app). XCTest + XCUITest against a stub rt; rt verbs under bun test. Clean room = (a) GitHub Actions macOS runner headless install + `rt verify --ci`; (b) local Apple-Silicon VM (Tart/VirtualBuddy) golden image, restored per run, scripted walkthrough; (c) second macOS user account as daily smoke. Release gate = (a) + (b) green. |
+| 13 | Identity | Frozen before the first teammate installs: `com.mattstack.app` / `.app.dev`; `com.mattstack.daemon` / `.dev`; `com.mattstack.deck`; embedded binary renamed `rt-daemon` → `rt` now; product name mattstack; TLD `.mattstack`; `~/.mattstack`; **macOS 14 floor**. |
+| 14 | Uninstall | Settings → "Uninstall mattstack…" and `rt uninstall`, same rt code path; shows the list, reverses everything the installer did, asks about `~/.mattstack` (default keep), trashes the app. |
+| 15 | UI | Five screens + Settings with four panes (§4). Stock macOS 26 controls, `Form(.grouped)` rows, Ice/AltTab shape. GPL sources are design reference only; Rectangle/inket (MIT) borrowable. |
+| 16 | Lanes | Seven lanes (§13); start L7 + L3 + L1/L2 now; L4/L5/L6 next. |
+| V1 | Auto-snapshot | **RT-30 joins lane L2**: rt commits every settings/secrets write to the user or team repo and pushes in the background (daemon timer + on-write); Team pane shows last push; conflicts surface as a needs-you row. The "paper trail" promise is backed by this. |
+| V2 | PATH defaults | Default-exposed: `rt`, `fast-browser`, `gitq`, `deck` (tagged links, still yielding to a user copy). Everything else internal + opt-in. |
+| V3 | App location | DMG target `/Applications`, fallback `~/Applications` when not writable; the app records its bundle path in the machine store (`mattstack.appPath`) at launch and rt reads that; legacy sweep covers `~/Applications/mattstack.app`; Matt's machine re-grants FDA once. |
+| V4 | Schema home | Ruled by the settings lane (reply 2026-08-20 16:45, spec `2026-08-20-suite-settings-migration.md`): `mattstack.integrations` (team), `mattstack.tracking` (team, identity-keyed; merged under machine `rt.repoTracking`), pack-side `requirements.jsonc` (not a key), `claude.marketplaces`/`claude.plugins` (user+team), `mattstack.appPath` (machine), `rt.cron` (machine), full `deck.*`/`board.*`/`gitq.*` tables — all in ONE suite registry in `@mattstack/rt-client`; **apps read in-process via the shared module** (not through the daemon). Registry merged to main 2026-08-20 (PR #5). |
+| V5 | Home repo (settings lane, ratified by Matt) | `~/.mattstack` **is** the git-backed home repo (`rt home init`, private `mattstack-home` via gh); mattstack-prefs folded in as `user/`; team clones nested and ignored; secrets at `user/secrets/<domain>.json` sops/age-encrypted to the Keychain-held age key; `rt home key export` → the user's password manager is the key-migration channel; `rt restore <org>/<repo>` = clone + key paste + materialize (RT-31); H2 snapshot daemon = RT-30. All live on Matt's machine as of 2026-08-20 evening. This supersedes this spec's earlier "container" wording. |
+
+### Invariants (binding on every lane)
+
+- **No user or employer data ever lands on mattstack-hosted infrastructure.**
+  Team data lives on the team's own forge. The shared relay sees ciphertext and
+  timestamps. Peering envelopes (which carry MR URLs) must be end-to-end
+  encrypted before they may traverse a shared relay; until then teams run their
+  own relay as today.
+- rt owns mechanics, the app owns ceremony; every ceremony has a CLI equivalent
+  (MAT-374 r.6). The wizard never does something `rt setup` cannot.
+- Honesty over magic: every checklist row reports what was actually checked;
+  nothing is marked ready on a guess.
+- Settings are read and written only through the RT-47 stores via `rt settings`;
+  state only through each app's state.db. The app has no config files of its
+  own beyond UserDefaults for window/UI state.
+- The installer never copies a user's `~/.claude/settings.json` or hooks; it
+  adds marketplaces and plugins only.
+- Pure canonical, no compat: `rt-tray.app`, `com.rt.daemon`, `~/.rt`, brew paths
+  are swept, never honored.
+- The **app owns ceremony — setup and restore**; Deck does not (supersedes the
+  "Deck owns ceremony" wording of MAT-374 r.6, DECK-56's skin, MAT-372's
+  framing; DECK-56's snapshot-timeline *view* may still live in Deck).
+- `~/.mattstack` **is the home repo** (V5): the gitignore is the layer
+  boundary — tracked = declarative (`user/`, `skills.jsonc`,
+  `snapshot-owners.jsonc`), encrypted-tracked = `user/secrets/`, ignored =
+  runtime (`rt/`, `deck/`, `repos/`, `teams/`, `user/local/`,
+  `settings.local.jsonc`). "User repo" below means the home repo.
+- Third-party tools may write their own Claude Code hooks (herdr's
+  `integration install claude`); the installer itself never edits
+  `settings.json`.
+
+## 3. The flow
+
+```
+DMG → drag to Applications → open
+  └─ app launches; menu-bar "m" appears; no daemon.json → Setup window opens
+       1 Welcome ──► 2 Your team ──► 3 Readiness checklist ──► 4 Install ──► 5 Done
+       (create or join)   (rt setup plan)       (rt setup apply)   (rt verify)
+```
+
+Re-entry: menu "Setup status…" reopens screen 3 as a health view; Settings (⌘,)
+exposes Permissions, Team (Invite…), General, Uninstall. A `mattstack://join/<code>`
+link opens the app on screen 2 with the code filled in; if setup is already
+complete it opens Settings → Team → Join.
+
+## 4. The screens
+
+Window: one dedicated `NSWindow` hosting SwiftUI (AppKit lifecycle stays),
+~560 pt wide, fixed, no close/minimize buttons while setup is incomplete (Quit
+remains available from the menu), Back/Continue bottom-right, Continue bound to
+Return, `.controlSize(.large)`, custom `enum Step` page model with push
+transitions (not `NavigationStack`), a subtle "Step n of 5" indicator. Rows use
+`Form(.grouped)` / `LabeledContent`. Stock macOS 26 controls; no custom design
+system. Status glyphs: `checkmark.circle.fill` green ready · `xmark.circle` red
+failed · `exclamationmark.triangle` yellow needs you · `circle.dotted` grey not
+checked/optional-skipped · `ProgressView` small while checking. Buttons that
+open System Settings end with an ellipsis.
+
+### 4.1 Welcome
+
+Brand mark, one sentence, then a plain list of what setup will do to this Mac
+(install the `rt` command into `~/.local/bin` and add one PATH line to the
+shell rc; run background services: rt daemon, deck, board, gitq; install the
+mattstack skills into Claude Code; install the editor extension; ask for Full
+Disk Access and background-item approval). One line that everything is
+reversible from Settings → Uninstall. Continue.
+
+### 4.2 Your team
+
+Two cards.
+
+**Create a team.** Fields: team name (slug preview shown), "Others will join
+later" checkbox (default on). Remote: if `gh auth status` succeeds, a checked
+box "Create a private GitHub repo `<owner>/mattstack-team-<slug>`" with the
+owner selectable (user or an org the token can see); otherwise a URL field
+("paste an empty repo's URL; GitHub, GitLab, anything git can push to"). A short
+explainer under the fields: *mattstack keeps your team settings in git. That
+keeps them safe and gives you a paper trail: skill edits and every change are
+visible in history.* The same explainer covers the **home repo**, created by
+the same step (`rt home init`: `~/.mattstack` becomes the clone of a private
+`<owner>/mattstack-home`, the age key is generated into the Keychain, and
+`rt home key export` is offered once so the user can store the key in their
+password manager — the documented channel for a second machine).
+Continue validates both remotes with `git ls-remote` using the user's
+credentials and moves on; nothing is pushed until Install. Create scaffolds the
+team repo as a proper mattstack zone: `mattstack/mattstack.jsonc` (`role:
+team`, `namespace`, `org` — editable), `mattstack/settings.jsonc` seeded with
+`mattstack.integrations` (forge from the remote) and the team-scope `board.*`
+keys (`board.gitlabHost`, `board.projects`, `board.members` — the roster —
+`board.title`; the team store IS the team layer, per the settings lane; there
+is no `team.jsonc`/`config.team.json`), and a root `.claude-plugin/marketplace.json`
+so the team repo *is* the team's marketplace. A team of one has no pack; `mattstack:*` skills are the default.
+`rt home init` owns the home-repo layout (`user/mattstack.jsonc` role marker,
+`prefs/`, `skills/`, `local/`, the boundary gitignore).
+
+**Already have mattstack settings?** (third, smaller card — the restore path,
+RT-31): paste the home repo (`<org>/<repo>`, or pick it via gh) and paste the
+age key from your password manager. On Continue the app runs the real
+`rt restore <org>/<repo> --json` (key on stdin), which clones it to
+`~/.mattstack`, installs the key in the Keychain, and materializes, then
+`rt setup intent restore <org>/<repo>`; Install's `home.restore` step only
+verifies the clone and key. The team(s)
+recorded in the home repo (`claude.marketplaces`/`claude.plugins`, tracking)
+are cloned by Install and their packs replayed. This is Matt-on-a-new-Mac and
+any reinstall.
+
+**Join a team.** One field: invite code (prefilled from a deep link). Continue
+redeems it through rt (`rt team join --dry-run`, code passed on stdin, never
+as a process argument): decodes, fetches the
+ciphertext from the relay, decrypts, and checks `git ls-remote` on the team
+remote with the user's credentials. Success shows "Joining *<team>* (owner
+*<handle>*)". Failure states are specific: *invite not recognized or expired:
+ask <owner> for a new one*; *you don't have access yet: ask <owner> to grant you
+access to <team>* (no git output, the remote URL is not shown); *code is for a
+different forge account than you're signed into*. The user repo is created here
+too, remote required, same explainer.
+
+### 4.3 Readiness checklist ("Before we begin")
+
+Rendered from `rt setup plan --json` (§5). Groups in order:
+
+- **Your Mac** — macOS version ≥ 14; Apple command line tools (git, python3)
+  → *Install…* runs `xcode-select --install` (Apple's dialog); `~/.local/bin`
+  **first** on PATH, including non-interactive shells (informational, fixed by
+  Install: rc block + `.zshenv` precedence block; `rt verify` checks order, not
+  presence, so team intercept shims like `doppler` actually fire); **Full Disk
+  Access** →
+  *Open Full Disk Access Settings…*; **Background services** → *Open Login
+  Items…* when `.requiresApproval`; **Notifications** (optional) → *Allow*
+  (system prompt; if denied → *Open Notification Settings…*).
+- **Accounts** — only what the team declares (team-of-one default: the forge
+  of the team remote). GitHub: *Use gh* when `gh auth status` is good, else
+  token field (also signs the bundled `gh` in); GitLab token (also signs the
+  bundled `glab` in); Linear key (the team key comes from
+  `mattstack.integrations.linear.teamKey`; `rt settings linear team` is deleted
+  by the settings lane); Slack → *Connect*
+  (per-user OAuth in the browser against the **team's** Slack app; the
+  callback port is a team setting). For an **owner**, Slack shows the
+  owner-once row first: *Create the team's Slack app* (`rt setup slack
+  create-app`: app-config token → generated manifest from the declared scope
+  needs → client id/secret into team-scoped secrets); the Collaborators
+  question (MAT-382) stays open and is a §14 risk. Switchboard board token
+  (when the team has a relay) is redeemed as part of Join, shown here as a
+  status row. Team-declared connects (Doppler login, StrongDM email + login,
+  ldcli auth) render from the pack's requirements. "Ready" means the validator
+  called the API and confirmed the token can see the team's resources
+  (group/org membership, the team repo).
+- **Access** — team repo reachable; each repo the team lists is visible with
+  those credentials; forge host reachable; switchboard (if the team has one)
+  answers.
+- **Tools** — herdr ≥ floor (present → version shown; missing → *Install*:
+  brew if present else vendor installer) and its Claude integration
+  (`herdr integration status`; herdr writes its own hook); Claude Code (same)
+  and signed in; Fast Browser (runtime present, **unpacked extension loaded in
+  Chrome** — a needs-you row with the exact steps, `fast-browser doctor --json`
+  as validator; pairing token optional); an editor we can install the
+  extension into (optional); Google Chrome (optional unless the team's pack
+  requires it; a pack may add "signed into <team app>" as a needs-you row);
+  Mission Control Control+Up unbound (optional, for `rt nav`); **team-declared tools** from the pack's requirements (doppler, sdm,
+  ldcli, pnpm, Postgres…) each with *Install* / *Connect* and the pack's
+  one-line why. MCP servers a pack needs ship inside the pack's plugin
+  (`.mcp.json`) and arrive with the plugin install; the installer never edits
+  `~/.claude.json`.
+
+Row anatomy: symbol · title · one sentence why · status badge · one button.
+Required vs optional is visible (optional rows say "works without this").
+Permission rows re-check on a 1 s timer while the window is visible and on
+`didBecomeActive`; other rows re-validate on change and on *Re-check*. Continue
+(labelled **Install**) enables when every required row is ready. A *Continue
+in limited mode* path exists only when all required rows are green and optional
+ones are not. Permission status for the three permission rows is computed by
+the app (§9) and merged into the plan by rt via `GET /permissions` on tray.sock,
+so the terminal `rt setup` shows identical rows.
+
+### 4.4 Install
+
+A live list driven by `rt setup apply --json` (NDJSON stream): each step has
+title, state (pending/running/done/failed/skipped), detail, and a log handle.
+Steps (order is rt's; shown here for the reader): `rt home init` (home repo +
+boundary + age key + push) — or `rt restore` (clone + key paste) for the
+restore card; create team repo (scaffolded zone) + push / clone team repo;
+write collected secrets with `rt secrets set <domain> <key>` (sops/age,
+`user/secrets/`); link the
+default-exposed tools (`rt`, `fast-browser`, `gitq`, `deck`) into
+`~/.local/bin` (+ rc PATH block, `.zshenv` precedence block, shell integration
+block); `rt intercept install` (team intercept shims); write machine settings
+(`rt.repoRoots` seeded, detected roots offered; `mattstack.appPath`); clone the
+team's repos into `<repoRoot>` (default on for every repo in
+`mattstack.tracking`, each deselectable — tracking intent only activates for
+repos the repo index can resolve locally, so this is what makes the board
+populate);
+register rt daemon + deck (app, via socket request from rt); privileged step:
+install the private node+portless, write the proxy LaunchDaemon plist
+ourselves (absolute `~/.mattstack/deck/` paths, `PORTLESS_TLD=localhost,mattstack`,
+portless ≥ 0.15.5), CA trust, sudoers (one admin prompt, raised by the app);
+register board + gitq as managed deck apps; materialize bindings
+(`merge-manifests` → `~/.mattstack/repos/<slug>/skills.jsonc`); write the
+machine-scope board/gitq keys the installer knows (`board.rtRepos`,
+`board.cwds`, `gitq.board`, `gitq.workSlots`) — board/gitq read the stores
+in-process, nothing is materialized into their checkouts; register the board's
+triage trigger (`rt.cron`, machine) when the team enables triage; install
+marketplaces + plugins (mattstack, fast-browser, team pack — MCPs arrive inside
+the pack's plugin) per Claude config dir; run fast-browser's own setup from the
+bundled artifact (runtime, extension unpack, macros); `herdr integration
+install claude` per config dir; install editor extension; start services;
+auto-snapshot push (RT-30); `rt verify`. A failed step stops
+the list on that row with remediation text and *Show log*; *Retry* resumes from
+the failed step (steps are idempotent). Nothing runs that was not listed.
+
+### 4.5 Done
+
+"Everything's working" with the verify summary (N checks), where things live
+(the `m` in the menu bar; `rt` in a new terminal; `https://board.mattstack`),
+buttons *Open the board*, *Invite teammates…* (owners), *Finish*. Closing the
+window is now allowed.
+
+### 4.6 Settings (⌘,)
+
+- **General**: start at login (SMAppService.mainApp), automatic updates
+  (Sparkle), check now, dev mode (prod/dev handoff as today), version.
+- **Permissions**: the three rows from §4.3 plus *Reset & re-request* (runs
+  `tccutil reset` for our bundle id and reprompts; for the stale-grant case).
+- **Team**: name, remote (masked to host + repo, copy), backup status (last
+  push), members with access (from the forge, when the token can see it),
+  *Invite…* (§6), *Join another team…*.
+- **Uninstall…** (§12).
+
+## 5. Architecture and the rt contract
+
+### 5.1 Components
+
+- `mattstack.app` (Swift, Xcode project): `AppDelegate` (menu bar, health
+  polling, notifications as today), `SetupWindowController` + SwiftUI
+  `SetupView` (screens), `ReadinessModel` (renders plan JSON, owns timers),
+  `PermissionsService` (§9), `ServicesRegistrar` (SMAppService for N plists,
+  version-change restart), `PrivilegedInstaller` (AuthorizationServices admin
+  prompt for the proxy step), `UpdaterController` (Sparkle), `TrayServer`
+  (routes below), `RtClient` (spawns the bundled `rt` by absolute path with
+  `--json`, streams NDJSON).
+- `rt` (TypeScript): `commands/setup/*` verbs, `lib/setup/plan.ts`
+  (requirements + validators), `lib/setup/apply.ts` (steps), `lib/team/*`
+  (create/join/publish/invite), `lib/secrets/*` (RT-32), `lib/deps/*`
+  (bundled-tool resolution, tagged PATH links), `commands/uninstall.ts`.
+- The shared switchboard (mr-board repo `switchboard/`): opaque invite
+  endpoints (§6.3).
+
+### 5.2 rt verbs (the contract the app drives)
+
+All JSON-emitting verbs accept `--json`; streaming verbs emit NDJSON lines of
+`{event, ...}`. Exit codes: 0 ok, 2 user-actionable failure (payload says
+what), 1 bug.
+
+| Verb | Purpose |
+|---|---|
+| `rt setup plan [--team <name>] --json` | Compute the readiness plan for the current (or given) team. |
+| `rt setup status --json` | Same rows, post-install, as health (used by "Setup status…" and `rt verify` reuses validators). |
+| `rt setup <integration> status\|connect [--token-stdin] --json` | MAT-382 r.4 shape: `setup github\|gitlab\|linear\|slack\|switchboard\|sdm\|doppler …`; connect validates + stores the credential via RT-32; `--use-gh` borrows gh auth. |
+| `rt setup slack create-app --config-token-stdin --json` | Owner-once: generated manifest from declared scope needs → app; client id/secret → team-scoped secrets; callback port recorded in team settings. |
+| `rt setup pack --json` | Marketplace add + plugin install + enable, materialize bindings, then the pipeline-resolves check for the team's default work type (exit 2 `stage-unresolved`). |
+| `rt setup apply [--from <stepId>] --json` | Run the install steps (NDJSON). |
+| `rt setup` (TTY) | Interactive walk of the same plan; the headless/catastrophe path. |
+| `rt team create <name> (--remote <url> \| --create-repo <owner>) [--others] --json` · `rt team status [--team <slug>] --json` | Init team repo with starter `mattstack/settings.jsonc`, set remote; push happens in apply. |
+| `rt team join [--dry-run] --json` | Code on stdin (no-echo prompt when TTY; never a process argument). Redeem invite (relay fetch + decrypt), clone under `~/.mattstack/teams/<name>/`, apply the board-peering invite when the team has a relay, report the invitee's age public key back (§6.3). |
+| `rt team invite --handle <forge-handle> --json` | Mint an invite: grant forge read access to the team repo (handle required when the repo is private), encrypt pointer, POST to relay, add roster entry; prints code + paste block. |
+| `rt team members sync\|remove <handle> --json` | Roster = `board.members` (team scope). Sync: collect invitee keys and add them as recipients. Remove: forge ACL revoke + `rt secrets rotate --team` re-encrypt to the remaining keys. |
+| `rt repos register <path…> / rt daemon track` | Register + track repos per team intent (existing `track` verb reused). |
+| `rt skills materialize [--repo]` | Bindings merge → `~/.mattstack/repos/<slug>/skills.jsonc`. |
+| `rt cron install <trigger>` | Register a trigger (board triage) with bundled binary paths. |
+| `rt tools setup <tool>` | Tool-owned setup wrappers (fast-browser setup, herdr integration). |
+| `rt team publish --remote <url> --json` | Push a team repo to a remote (also used when a remote must change). |
+| `rt home init [--dry-run]` / `rt home key export` (exist, settings lane) | Home repo provisioning + boundary + age key; key export once to the password manager. |
+| `rt restore <org>/<repo>` (settings lane R) | Clone home repo, key paste → Keychain, materialize (replays `claude.*`, tracking, packs). |
+| `rt secrets set\|list\|rotate` (exist, settings lane) | Domains `rt`, `deck`, `board` (+ team-scope in L2); `setup <integration> connect` writes through this. |
+| `rt secrets init/set/get/rotate` | RT-32 surface; `setup connect` uses it. |
+| `rt deps resolve <tool> --json` | Absolute path of the bundled tool + whether a user copy exists; used by rt internally and by the Tools rows. |
+| `rt deps link <tool> / unlink` | Opt-in PATH exposure (tagged symlink), auto-unlink when a user copy appears. |
+| `rt services list/register/restart --json` | Facade over tray.sock for the app-registered agents + deck-managed apps. |
+| `rt update [--json]` | `POST /update/check` on tray.sock; if the app is not running, exit 2 (`{error:{code:"app-not-running"}}` with `--json`) and prints where updates come from. |
+| `rt uninstall [--keep-data|--delete-data] [--yes] --json` | §12; `--delete-data` needs `--yes` (the app's sheet is the consent). |
+| `rt verify [--json]` | Existing command; its checks become the plan's validators (one implementation). |
+
+`rt install` (MAT-360's "internal package mechanism") is absorbed by `rt setup
+apply` steps + `rt deps`; no separate verb.
+
+Plan JSON (abridged):
+
+```json
+{ "team": {"name":"assured","mode":"join"},
+  "groups": [{ "id":"mac", "title":"Your Mac", "rows":[
+     { "id":"perm.fda", "kind":"permission", "title":"Full Disk Access",
+       "why":"Reads your repositories' git state so the daemon can show branch and MR status.",
+       "required":true, "status":"needs-you", "detail":"Not granted",
+       "action":{"type":"open-settings","target":"fda"} },
+     { "id":"tool.clt", "kind":"tool", "title":"Apple command line tools", "required":true,
+       "status":"ready", "detail":"git 2.50.1", "action":null } ]},
+    { "id":"accounts", "title":"Accounts", "rows":[
+     { "id":"account.gitlab", "kind":"account", "title":"GitLab",
+       "why":"The team's merge requests live on gitlab.assured.com.",
+       "required":true, "status":"missing", "action":{"type":"connect","integration":"gitlab","fields":[{"name":"token","secret":true,"hint":"read_api, read_user"}]} } ]} ],
+  "canInstall": false, "requiredMissing": ["perm.fda","account.gitlab"] }
+```
+
+`status` ∈ `ready | missing | invalid | needs-you | checking | skipped | error`;
+`action.type` ∈ `open-settings | request-permission | connect | oauth |
+owner-once | install | link-bundled | steps | open-url | run` (or `action: null`;
+the contract file is authoritative — `use-gh` is a `connect` alternative, not
+a type). The app never invents rows; it renders what rt sends
+and calls the action's verb. Permission rows are the exception in *evaluation*
+only: rt asks the app (`GET /permissions`) and folds the answer in, so one
+plan serves wizard and terminal.
+
+### 5.3 tray.sock routes (additions)
+
+`GET /permissions` → `{fda, notifications, loginItems}` each
+`{status, detail}`; `POST /permissions/request` `{which}`; `GET /services` →
+registered agents + status; `POST /services/register` `{plist}` /
+`/restart` `{label}`; `POST /privileged/proxy-install` (app raises the admin
+prompt, runs the bundled installer helper, returns result); `GET /setup/need/<id>`
+→ 200 `{state: pending|done|failed, detail}` always (rt polls until
+done/failed); `POST /update/check`; `GET /version` (`build` = numeric
+`CFBundleVersion`). Existing routes unchanged.
+
+### 5.3b Settings and secrets substrate (settings lane)
+
+Every read/write goes through `@mattstack/rt-client`'s settings module (the
+RT-47 resolver + the one suite registry) and `lib/secrets` (sops/age over
+`user/secrets/<domain>.json`). The app never parses a store file; it asks rt.
+The home repo (`rt home init`), snapshot daemon (H2), and restore (R) are that
+lane's; this spec's verbs sit on top of them.
+
+### 5.4 Where logic lives
+
+Validators, step logic, team/invite crypto, secrets, dependency resolution:
+TypeScript, unit-tested with bun, no Swift. Swift holds view state, timers,
+permission probes, SMAppService calls, the admin prompt, Sparkle, and the
+socket server. The stub rt used by XCUITest is a tiny Bun script emitting
+canned plan/apply JSON for named scenarios (`RT_STUB_SCENARIO=join-happy`),
+selected by an env var the app honours only in DEBUG builds.
+
+## 6. Team and invite model
+
+### 6.1 Everyone has a team
+
+`~/.mattstack/teams/<slug>/` is a git clone (nested inside the home repo,
+ignored by it) with `mattstack/settings.jsonc` (team scope of the RT-47
+resolver — `mattstack.integrations`, `mattstack.tracking`, team-scope `board.*`,
+`claude.*`) and the team's pack(s). A team of one is the same shape. The home
+repo `~/.mattstack` holds user-scope settings (`user/settings.jsonc`) and the
+encrypted secrets (`user/secrets/`). Both have remotes from creation (ruling
+3b); the wizard explains why in plain words and never asks the user to run git.
+
+### 6.2 Create
+
+`rt team create` writes the starter settings (forge host inferred from the
+remote, integrations empty), sets the remote; `rt user init` likewise; Install
+pushes both. If `gh` is authenticated, the app offers to create the private
+repos in one click (owner = user or an org); otherwise URL fields. The team's
+"declared integrations" start as what the remote implies (GitHub → github;
+GitLab host → gitlab) and grow when the owner connects more in Settings → Team
+or via the pack.
+
+### 6.3 Invites (opaque, shared relay)
+
+Owner side (`rt team invite`):
+
+1. Pointer = `{v:1, team:<slug>, name, remote, owner:<forge handle>, forge:<host>, createdAt}`.
+2. Generate 32-byte key; encrypt pointer (XChaCha20-Poly1305 or AES-256-GCM);
+   `POST /v1/invites` to the relay with `{ciphertext, expiresAt}` → `{id}`.
+   Relay stores `id`, ciphertext, created/expires/redeemed timestamps only.
+3. Code = base32(id ‖ key) chunked for reading (~77 chars; Crockford base32 of
+   16 + 32 bytes). Paste block: "Install
+   mattstack from <download url>, then open `mattstack://join/<code>` or paste
+   the code into Setup → Join a team."
+4. Forge access is **granted at mint** (the handle is required when the team
+   repo is private; `gh api` / GitLab API with the owner's token) and
+   **verified at redeem** — MAT-379 phase C's "first step is forge access"
+   maps to exactly this. The invitee is added to the roster (`board.members`,
+   team scope) so the redeem can report back. Age recipient for team-scoped secrets is added when the invitee
+   reports their public key (redeem posts it to the relay as a second opaque
+   blob keyed by the same id, readable once by the owner's next
+   `rt team members sync`).
+5. Replace-on-mint: a new invite for the same handle replaces the old id (the
+   relay deletes it). Expiry 7 days. Relay prunes hourly.
+
+Teammate side (`rt team join`): decode → `GET /v1/invites/<id>` → decrypt → `git
+ls-remote <remote>` with the user's credentials → clone → mark redeemed (`POST
+/v1/invites/<id>/redeem`, one-time) → materialize (pack marketplace add +
+install, bindings; settings now resolve at team scope; tracking activates as
+team repos are cloned)
+→ if the team settings carry a relay URL + team-scoped admin token, mint and
+apply the board-peering invite for this member (peering row otherwise shows
+idle) → post the member's age public key as the reply blob. Failure messages
+in §4.2.
+
+Relay (mr-board `switchboard/`, Railway, `mattstack` shared instance):
+`POST /v1/invites` (any client; rate-limited), `GET /v1/invites/:id` (returns
+ciphertext if unexpired and unredeemed), `POST /v1/invites/:id/redeem` (CAS),
+`POST /v1/invites/:id/reply` (second opaque blob, once), `DELETE` by the
+creator (holds a creator secret returned on create). No admin token needed for
+team invites; board-peering invites keep today's admin-minted flow on a team's
+own relay until peering envelopes are E2E encrypted. The invariant: no field on
+the relay is ever plaintext employer data.
+
+Landing page: `https://mattstack.dev/join#<code>` — static; reads the fragment
+client-side, shows Download + "Open in mattstack" (`mattstack://join/<code>`).
+The fragment never leaves the browser.
+
+## 7. Dependencies
+
+Policy (ruling 8), derived from the full inventory (research/dependency
+inventory):
+
+| Class | Tools | How |
+|---|---|---|
+| **Bundle** (Contents/Helpers, signed, pinned via `deps.lock` in CI with sha256) | rt (Contents/MacOS/rt), fzf, jq, bun, gh, glab, private node (for fast-browser + portless only), fast-browser, deck, board, gitq | Used by the suite **by absolute path**. `rt`, `fast-browser`, `gitq`, `deck` are linked into `~/.local/bin` by Install (V2; shipped skills call them bare); every other tool's PATH exposure is opt-in from the Tools row ("Use mattstack's"). Links are tagged symlinks that rt removes automatically when a non-ours copy appears on PATH (`rt deps` reconciles on `rt verify`, daemon start, app launch). Version floors apply to internal use only; the user's copies are never judged. |
+| **Provision** | herdr (≥ floor), Claude Code | Present → floor check. Missing → *Install*: `brew install` if brew is on the machine, else the vendor installer (`herdr.dev/install.sh`, `claude.ai/install.sh`) into `~/.local/bin`. Their own updaters own them thereafter. Never bundled (self-updaters, proprietary). |
+| **System** | git, python3 (stdlib only), shells, launchctl/osascript/security/etc. | Apple CLT; the row's *Install…* triggers `xcode-select --install`. |
+| **Team-declared** | doppler, sdm, ldcli, pnpm, Postgres, Linear/local-db MCPs, Chrome-for-evidence… | The pack manifest declares `tools: [{name, floor, why, install:{brew, url}, connect?}]`; rows render from it; nothing of the team's is bundled. |
+| **Dropped** | tmux, zellij (no callers), terminal-notifier (osascript fallback) | Removed from README/verify. |
+| **Privileged** | portless ≥ 0.15.5 proxy: root LaunchDaemon on :443 + local CA trust + `/etc/sudoers.d/mattstack-proxy-restart` | One admin prompt (AuthorizationServices) raised by the app at the Install step; installs the bundled node+portless privately under `~/.mattstack/deck/`, **writes the LaunchDaemon plist itself** (absolute paths, `PORTLESS_TLD=localhost,mattstack`; closes DECK-55's note and DECK-58's fnm-path baking), trusts the CA, writes sudoers. A deck ticket evaluates absorbing the proxy later. |
+
+Accounts-bearing tools (gh, glab, doppler) keep their auth in the user's
+`~/.config`, so whether the bundled or the user's binary runs, login happens
+once. Services' plists set a static `PATH=/usr/bin:/bin:/usr/sbin:/sbin`; rt
+and deck prepend `<bundleRoot>/Contents/Helpers` (derived at process start
+from their own execPath, so `/Applications`, `~/Applications` and the dev
+bundle all work) and `$HOME/.local/bin` (for herdr/claude) to their own
+`PATH` before spawning anything; nothing is captured from the user's shell.
+
+Consequences for other repos (lane L5): board and gitq ship as `bun --compile`
+binaries with published rt-client (no `file:` deps), read their config from
+the stores in-process via rt-client's settings module (no `config.json`, no
+`.env`; secrets via the shared secrets module; state in their own state.db —
+the settings half is the settings lane's deck/board/gitq lanes), and their
+skills move into
+plugins (no `~/.claude/skills` symlinks); deck publishes releases and its
+platform registration moves to the app's SMAppService plist (`deck setup`
+narrows to registry/proxy; `deck uninstall` leaves the agent to the app);
+fast-browser publishes its artifact and fixes its default marketplace source;
+the mattstack marketplace becomes the MAT-360 public meta repo (pruned plugin
+tree) instead of a directory of symlinks; the claimview pack declares its
+requirements, gets a writer for `dev-ports.state.json` (the path fix alone does
+not restore bearer capture), and `local-db-mcp` either gets a distributable
+home or leaves the pack; the rt-context extension reads secrets through the
+daemon before RT-32 deletes `secrets.json`. rt's two latent `bun`-on-PATH
+branches (`lib/enrich.ts`, `bunx pino-pretty`) switch to the bundled bun.
+
+## 8. Services and launchd
+
+- Bundle ships `Contents/Library/LaunchAgents/com.mattstack.daemon.plist` and
+  `com.mattstack.deck.plist` (dev flavor: `.dev` labels), `BundleProgram` under
+  `Contents/MacOS`/`Contents/Helpers`, `KeepAlive {SuccessfulExit:false}`,
+  `ThrottleInterval 10`, static `EnvironmentVariables.PATH`
+  (`/usr/bin:/bin:/usr/sbin:/sbin`; the programs prepend the bundle's Helpers
+  dir and `~/.local/bin` themselves, §7), no stdout/err
+  paths (macOS 26 `$(HOME)` breakage; logs go to `~/.mattstack/rt/logs` and
+  `~/.mattstack/deck/logs` by the programs themselves). `AssociatedBundleIdentifiers`
+  kept (harmless; needed only for legacy plists).
+- `ServicesRegistrar` registers both on first run and on every launch
+  (idempotent), surfaces `.requiresApproval` as the Background services row,
+  and on a version change (UserDefaults `lastLaunchedVersion` ≠ bundle version)
+  re-registers then `launchctl kickstart -k gui/$UID/<label>` for each, then
+  asks deck to restart its managed apps (`deck restart --managed`).
+- Deck registers board and gitq as managed apps (`managedBy: mattstack`) with
+  their binaries' absolute paths inside the bundle and hostnames
+  `board.mattstack` / `gitq.mattstack` (MAT-384). The app polls deck's API for
+  liveness like the daemon and surfaces it in the menu (plumbing only).
+- Labels, Team ID, and each helper's code-signing identifier stay stable across
+  releases (launchd pins them). The embedded `rt-daemon` → `rt` rename happens
+  once, now, before any teammate installs.
+- The stale `com.rt.daemon` BTM record found on Matt's machine is booted out
+  unconditionally by the one-shot legacy sweep (it currently only fires when
+  `rt-tray.app` exists); the sweep also covers `~/Applications/mattstack.app`
+  from phase 1 (V3: the app now lives in `/Applications`, with `~/Applications`
+  as the non-writable fallback, and records `mattstack.appPath`).
+- Dev flavor: the deck binary must not live under `~/Documents` (DECK-13 TCC
+  wedge); the dev app points at `~/.mattstack/deck/bin/deck` or the dev
+  bundle's copy.
+
+## 9. Permissions
+
+| Row | Required | Detect | Request | Re-check |
+|---|---|---|---|---|
+| Full Disk Access | yes | Probe read of `~/Library/Containers/com.apple.stocks` (macOS 12+; fallback list from MacPaw) — the probe itself lists the app in the FDA pane; `EPERM/EACCES` ⇒ not granted | *Open Full Disk Access Settings…* (`x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles`); after the toggle, row says "Relaunch mattstack to apply" with a button (macOS applies FDA on next launch) | timer while visible + `didBecomeActive` |
+| Background services | yes | `SMAppService.agent(...).status` for both plists | `register()`; `.requiresApproval` → *Open Login Items…* (`openSystemSettingsLoginItems()`); copy warns about the "Background Items Added" notification | same |
+| Notifications | no | `UNUserNotificationCenter.notificationSettings().authorizationStatus` | `.notDetermined` → `requestAuthorization`; `.denied` → *Open Notification Settings…* (`…Notifications-Settings.extension?id=com.mattstack.app`) | same |
+
+Pre-request explanation screens follow the HIG (single Continue). The app is
+signed with a stable Developer ID (dev flavor with Apple Development) so grants
+survive updates; Settings → Permissions → *Reset & re-request* runs `tccutil
+reset All com.mattstack.app` for the moved-app/stale-signature case. The daemon
+and deck inherit FDA through SMAppService attribution; board/gitq read through
+rt and need none.
+
+## 10. Secrets (RT-32)
+
+`rt home init` generates the age key into the login Keychain (settings lane,
+live today); setup writes every collected secret into `user/secrets/<domain>.json`
+via `rt secrets set` (sops/age; domains `rt`, `deck`, `board`), and the
+snapshot daemon commits + pushes. Readers use the shared secrets module
+in-process; the daemon's grant-gated `secrets:forge-token` stays the
+out-of-process path (gitq precedent). **Team-scoped secrets** (the team's
+switchboard admin token, Slack client secret, shared service tokens the pack
+declares) are this spec's addition: `teams/<slug>/mattstack/secrets/*.json`
+encrypted to every member's public key (`.sops.yaml` in the team repo with N
+recipients); invite redeem contributes the invitee's key (§6.3). The plaintext inventory (`~/.mattstack/rt/secrets.json`, board `.env`
+Slack values, deck `platform.json` CF token/zone + session secret + password
+hashes) is imported and retired by the settings lane (workstream S; `rt` domain
+already live). Board/gitq/deck read through the shared module; key names stay. Member removal = forge ACL
+revoke + `rt secrets rotate --team` (the residue — a removed member's old
+copies — is documented, not hidden). Plaintext never touches git; lanes/pods
+never receive the key. Auto-snapshot (RT-30, V1) commits and pushes these
+writes in the background.
+
+Deck's *publish* features (cloudflared tunnel, Cloudflare token/zone, CF
+Access, public domains) are out of scope for the installer; their secrets'
+home is the user-scope RT-32 layer, which is where MAT-384 moves them.
+
+## 11. Distribution, update, identity
+
+- **Release train** (m4ttstack/rt is public, so its Releases host the
+  artifacts; the MAT-360 meta repo's role narrows to "the marketplace"): one
+  tag on m4ttstack/rt builds rt (arm64), bundles helpers
+  per `deps.lock`, builds the app (`xcodebuild build … CODE_SIGNING_ALLOWED=NO`
+  then `build.sh`'s own inside-out Developer ID signing — not
+  `archive/export`; hardened runtime, entitlements: `allow-jit` first; add
+  `allow-unsigned-executable-memory` only if the bundled rt crashes), notarizes
+  + staples, produces `mattstack-<ver>.dmg` (first install) and
+  `mattstack-<ver>.zip` (`ditto --sequesterRsrc --keepParent`) for Sparkle,
+  runs `generate_appcast` (EdDSA key from a CI secret, last 3 zips for deltas),
+  uploads DMG + zip + `appcast.xml` (+ deltas, `SHA256SUMS`) as GitHub Release
+  assets — the feed URL is
+  `https://github.com/m4ttstack/rt/releases/latest/download/appcast.xml`
+  (not GitHub Pages) — then the headless clean-room job (§12.2 layer a).
+- **Sparkle**: SPM dependency, `SUFeedURL`, `SUPublicEDKey`, numeric increasing
+  `CFBundleVersion` = `major*1e6 + minor*1e3 + patch` (2.8.0 → 2008000),
+  `SUScheduledCheckInterval 21600`, `SUEnableAutomaticChecks`, `SUAutomaticallyUpdate`,
+  `SUVerifyUpdateBeforeExtraction`; no sandbox XPC keys; gentle reminders
+  (menu item "Update available") since the app is `LSUIElement`; sign inside-out,
+  never `--deep`; dev flavor disables checks.
+- **Install on the user's machine**: DMG drag to `/Applications` (fallback
+  `~/Applications`); first launch guard "running from a DMG/translocated path —
+  please move me to Applications"; the app records `mattstack.appPath`.
+  `~/.local/bin/rt` → `<appPath>/Contents/MacOS/rt` symlink (dev mode overwrites
+  with the wrapper script as today; `currentMode()` reads through the link).
+  `rt update` → `POST /update/check`.
+- **Identity** (ruling 13): frozen; macOS 14 floor; arm64-only; Info.plist gains
+  `LSMinimumSystemVersion 14.0`, `CFBundleURLTypes` for `mattstack://`,
+  `NSUserNotificationAlertStyle` kept, no `LSFileQuarantineEnabled`.
+- The `rt-darwin-*.tar.gz` is dropped; `mattstack-<ver>.zip` is the headless
+  artifact (`ditto -x -k` + `<app>/Contents/MacOS/rt --post-install`);
+  `rt --post-install` becomes the headless entry into `rt setup apply`
+  (`--non-interactive --team-of-one`; a plain first `rt` run only prints a
+  hint to run `rt setup`, it does not auto-install).
+
+## 12. Dev mode, testing, uninstall
+
+### 12.1 Dev mode
+Unchanged from MAT-383: `mattstack-dev.app` / `com.mattstack.app.dev`,
+source-runner daemon shim, `rt settings dev-mode` handoff. The Xcode project
+has two schemes (mattstack, mattstack-dev) producing the two bundles; both
+flavors build from `project.yml`. The dev app's setup window runs against the
+real `rt` from the checkout or the stub (env).
+
+### 12.2 Testing
+- Swift: XCTest for `ReadinessModel` (plan JSON → rows → enablement), step
+  stream rendering, version-change restart logic, permission status mapping.
+  XCUITest flows against the stub rt: create-happy, join-happy, join-no-access,
+  permission-denied-then-granted, install-step-failure-retry, uninstall.
+- rt: bun tests for validators (network mocked), plan composition from team
+  settings, team create/join/invite crypto, relay client, apply idempotency,
+  deps resolution/link/unlink, uninstall plan.
+- Clean room (ruling 12): (a) release workflow job on `macos-latest`: download
+  the zip, `ditto`, `<app>/Contents/MacOS/rt --post-install --non-interactive
+  --team-of-one`, `rt verify --ci`; (b) `rt-tray/vm/` holds the golden-image
+  recipe (Tart or VirtualBuddy, macOS 14 and 26 images, no CLT/brew, a
+  throwaway Apple ID-free user) and `walkthrough.sh` which restores the
+  snapshot, mounts the DMG, launches the app with `RT_STUB_SCENARIO` unset and
+  a test team on a throwaway forge org, drives the five screens by
+  AppleScript UI scripting against the app's accessibility identifiers
+  (XCUITest runner gated on Xcode being installed in the guest; including the
+  real FDA/Login Items dance) and then Sparkle vN→vN+1 from a local appcast
+  (`MATTSTACK_APPCAST_URL` + `--allow-appcast-override`); screenshots are
+  archived per run; (c) a second macOS user on Matt's Mac for daily smoke.
+  Release gate: (a) and (b) green on the candidate.
+
+### 12.3 Uninstall
+`rt uninstall` computes and shows the list, then: unregister daemon + deck
+(SMAppService via socket), `deck remove --managed` board/gitq, privileged
+removal of proxy daemon + CA + sudoers (admin prompt), remove tagged
+`~/.local/bin` links and the shell-rc block, `--uninstall-extension` in each
+editor, `claude plugin uninstall` + marketplace remove for what we added (per
+config dir), ask about `~/.mattstack` (default keep), move the app to Trash,
+print what stayed. The Settings menu item calls the same verb with a
+confirmation sheet.
+
+## 13. Lanes, sequencing, dependencies
+
+| Lane | Team | Contents | Depends on |
+|---|---|---|---|
+| L1 rt setup verbs | RT | §5.2 verbs, validators, plan/apply, team create/join/invite/publish, deps resolve/link, uninstall, permissions merge, `--post-install` → apply | L2 for account rows; MAT-384 for deck managed-app steps (stubbed behind the contract until then); RT-50 keys the tray reads |
+| L2 team secrets | RT | **Shrunk**: RT-32 core, RT-30 snapshot (V1) and RT-31 restore are the settings lane's (S, H2, R). L2 = team-scope recipients (`teams/<slug>/mattstack/secrets/`, N-recipient `.sops.yaml`), the invite-reply key exchange, `rt secrets rotate --team`, `rt team members sync\|remove` | settings lane S (merged) |
+| L3 app | MAT | xcodegen project + schemes, Sparkle, setup window + 5 screens, Settings panes, PermissionsService, ServicesRegistrar, PrivilegedInstaller, tray.sock routes, RtClient, stub rt, XCTest/XCUITest | L1 contract (JSON shapes agreed first; stub carries it) |
+| L4 release | RT/MAT | deps.lock + helper bundling, rt-daemon→rt rename, DMG, appcast, notarization, headless install job, thin `rt update`, README/verify sweep | L3 project |
+| L5 suite artifacts | BOARD/GITQ/DECK/SKILLS/FB | board + gitq `bun --compile` binaries with published rt-client (their settings/secrets reads are the settings lane's deck/board/gitq lanes; their state.db adoption is a follow-on), skills as plugins (no `~/.claude/skills` symlinks), deck release + SMAppService-owned platform registration + private node/portless + privileged helper + our own proxy plist, fast-browser artifact + own setup + marketplace source fix, mattstack marketplace = MAT-360 meta repo, claimview pack `requirements.jsonc` + `dev-ports.state.json` writer + local-db-mcp decision | MAT-384 for TLD/managed apps; settings lane's deck/board/gitq lanes for config reads |
+| L6 relay invites | BOARD | `/v1/invites*` opaque endpoints on the shared Railway relay; rate limiting; prune | — (matt-gated deploy) |
+| L7 clean room | MAT | `rt-tray/vm/` golden images + walkthrough, second-user smoke notes | — |
+
+### 13.2 What the settings lane ruled and ships (V4/V5)
+
+Reply file: `~/.mattstack/user/local/reply-2026-08-20-settings-lane-to-installer.md`;
+program spec: `docs/superpowers/specs/2026-08-20-suite-settings-migration.md`.
+Ruled and merged (PR #5, 2026-08-20): one suite registry in `@mattstack/rt-client`
+with `mattstack.integrations` `{forge:{host,provider}, slack?:{appId,clientId,channel,callbackPort}, linear?:{teamKey}, switchboard?:{url}}` (team),
+`mattstack.tracking` `{repos:{"<host/group/repo>":{caches}}}` (team, merged under machine
+`rt.repoTracking`), `mattstack.appPath` (machine), `claude.marketplaces`/`claude.plugins`
+(user+team), `deck.*`/`board.*`/`gitq.*`; pack requirements are pack-side
+`requirements.jsonc`; apps read in-process; `rt home init`, `rt home key
+export`, `rt secrets set|list|rotate` live. In flight overnight (their mandate:
+run to completion, merge as green): rt keys wave (incl. `rt.cron` to machine,
+legacy rung deletion, `rt settings llm` deletion), deck/board/gitq settings
+lanes (incl. the rt-context extension off `secrets.json`), H2 snapshot daemon,
+R restore. L1 reads these keys directly; nothing is stubbed.
+
+### 13.3 Ticket amendments to file (superseded or refined by this spec)
+
+MAT-382 (verb shape adopted as ruled; Slack create-app lives in the app's
+owner path; wizard is the app), MAT-379 (r.3 hosted relay now *opaque-invite
+only*, peering needs E2E first; phase C = forge access granted at mint,
+verified at redeem; invite via stdin/prompt never argv), MAT-374 (r.2
+container; r.6 app owns ceremony incl. restore), RT-30 (container wording;
+auto-snapshot in L2), RT-31 (restore ceremony is the app's "already have
+settings" path; materialize contract), RT-32 (team-scope recipients + reply
+key exchange), MAT-383 (ruling 4 label superseded by `com.mattstack.daemon`;
+x64 dropped; phase-1 spec gets a "superseded by" banner; `/Applications`),
+MAT-360 (artifact host = m4ttstack/rt Releases; meta repo = marketplace;
+`rt install` absorbed), MAT-384 (deck platform registration moves to the app;
+CF secrets home), DECK-1/4/7/11/56 (no curl installer, no `deck update`, no
+"declined" fallback, no installer hosting DNS; restore is the app's), DECK-13
+(dev-flavor deck path), MAT-372 (close: superseded), MAT-331 (native app exempt
+from the design system), FB-33 (satisfied by V2), SKILLS-39 (`onboard` retires
+in favour of the wizard), working-agreement DoD (curl line).
+
+### 13.4 Start order
+
+Start now, in parallel: L7, L3, L1/L2 (worktrees; main belongs to the settings
+migration lane). Then L4, L5, L6. The app ships to teammates only when L1–L7
+are green and MAT-384 has landed (board/gitq reachable at their `.mattstack`
+names). Tickets: one per lane in its product team, linked to MAT-383; releases,
+DNS (`mattstack.dev/join`), Railway, and Apple steps carry `matt-gated`.
+
+## 14. Risks and open items
+
+- Bun hardened-runtime entitlement minimum must be verified on the first
+  notarized build (start with `allow-jit`).
+- `launchctl kickstart -k` against SMAppService agents on 14/15/26 must be
+  verified in the VM layer; fallback is unregister/sleep/register.
+- macOS 26's background-task prompt behaviour for SMAppService agents is not
+  fully characterised; the Background services row copy may need a second
+  state.
+- Peering over the shared relay stays blocked on E2E envelope encryption
+  (recorded for the board lane).
+- Deck's proxy decision (absorb vs bundle portless) is deferred behind the one
+  admin prompt; a deck ticket tracks it.
+- `gh`-less GitHub users and GitLab-only teams exercise the URL path for repo
+  creation; both must be in the XCUITest matrix.
+- Product name "mattstack" is frozen by ruling 13; a rename after dogfood
+  would reopen bundle ids, labels, TLD and directories.
+- Slack app *Collaborators* (MAT-382 open question): whether the owner wizard
+  needs a guided add-collaborators step is unresolved; the create-app row may
+  gain a manual sub-step.
+- Multi-team machines: `rt setup plan` needs a "current team" selector; the
+  first implementation assumes one team per machine and surfaces a picker only
+  when more exist.
+- Team-scope secrets (N-recipient `.sops.yaml` in the team repo) extend the
+  settings lane's single-recipient model; coordinate the file layout with that
+  lane before L2 lands.
+- `local-db-mcp` has no distributable source; capture-evidence/query flows in
+  the claimview pack depend on it.
diff --git a/docs/superpowers/specs/2026-08-21-rt-setup-contract.md b/docs/superpowers/specs/2026-08-21-rt-setup-contract.md
new file mode 100644
index 00000000..0f3e791c
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-21-rt-setup-contract.md
@@ -0,0 +1,207 @@
+# rt ↔ mattstack.app setup contract (v1)
+
+The JSON the app renders and the verbs it drives. Companion to
+`2026-08-20-mattstack-app-installer-design.md` §5.2–5.3. L1 (rt) implements
+it; L3 (app) renders it; the XCUITest stub emits it. Changes bump `contract`.
+
+## Invocation
+
+The app spawns the bundled `rt` by absolute path with `--json` and reads
+stdout. Streaming verbs emit NDJSON (one JSON object per line). Exit codes:
+`0` ok · `2` user-actionable failure (stdout carries `{ "error": {...} }`) ·
+`1` bug. The app passes `RT_APP_SOCKET=<tray.sock>` so rt can call back for
+permission status; rt passes nothing back on argv that is secret (codes and
+tokens travel on stdin).
+
+Common envelope on every JSON result: `{ "contract": 1, "at": "<ISO-8601>", ... }`.
+
+## `rt setup plan --json` → Plan
+
+```jsonc
+{
+  "contract": 1,
+  "at": "2026-08-21T04:00:00Z",
+  "team": { "slug": "assured", "name": "Assured", "mode": "join" | "create" | "restore" | "none" },
+  "groups": [
+    { "id": "mac" | "accounts" | "access" | "tools",
+      "title": "Your Mac",
+      "rows": [ Row, ... ] }
+  ],
+  "canInstall": false,
+  "requiredMissing": ["perm.fda", "account.gitlab"]
+}
+```
+
+Row:
+
+```jsonc
+{
+  "id": "perm.fda",                       // stable, dotted; namespaces: perm.*, tool.*, account.*, access.*, pack.*
+  "kind": "permission" | "tool" | "account" | "access" | "info",
+  "title": "Full Disk Access",
+  "why": "Reads your repositories' git state so the daemon can show branch and MR status.",
+  "required": true,
+  "optionalNote": null | "Works without this; you'll see menu-bar badges instead.",
+  "status": "ready" | "missing" | "invalid" | "needs-you" | "checking" | "skipped" | "error",
+  "detail": "Not granted" | "git 2.50.1" | "token can't see group assured",
+  "action": null | Action,
+  "recheck": "on-activate" | "on-change" | "manual"   // how the app refreshes this row
+}
+```
+
+Action (exactly one shape, discriminated by `type`):
+
+```jsonc
+{ "type": "open-settings", "label": "Open Full Disk Access Settings…", "target": "fda" | "login-items" | "notifications" | "keyboard" }
+{ "type": "request-permission", "label": "Allow", "which": "notifications" }
+{ "type": "connect", "label": "Connect", "integration": "gitlab" | "github" | "linear" | "slack" | "switchboard" | "sdm" | "doppler" | "ldcli",
+  "fields": [ { "name": "token", "label": "Personal access token", "secret": true, "hint": "scopes: read_api, read_user" } ],
+  "alternatives": [ { "id": "use-gh", "label": "Use gh login" } ] }
+{ "type": "oauth", "label": "Connect", "integration": "slack", "verb": ["setup","slack","connect"] }   // rt opens the browser and completes the flow
+{ "type": "owner-once", "label": "Create the team's Slack app…", "integration": "slack", "fields": [ { "name": "configToken", "label": "App configuration token", "secret": true } ] }
+{ "type": "install", "label": "Install", "tool": "herdr", "via": "brew" | "vendor" | "apple-clt" | "bundled-link" }
+{ "type": "link-bundled", "label": "Use mattstack's", "tool": "gh" }
+{ "type": "steps", "label": "Show steps…", "steps": ["Open chrome://extensions", "Turn on Developer mode", "Load unpacked → ~/.fast-browser/extension/current/unpacked"] }
+{ "type": "open-url", "label": "Download", "url": "https://claude.ai/download" }
+{ "type": "run", "label": "Re-check", "verb": ["setup","status"] }
+```
+
+The app maps actions to behaviour: `open-settings`/`request-permission` are
+handled natively (PermissionsService); every other action spawns the named rt
+verb (`connect` → `rt setup <integration> connect` with fields on stdin as
+JSON; `install` → `rt tools install <tool>`; `link-bundled` → `rt deps link
+<tool>`; `run` → the given verb) and then re-requests the plan.
+
+## `rt setup status --json` → Plan
+
+Same shape; `team.mode` reflects the installed state; used post-install and by
+`rt verify`.
+
+## `rt setup <integration> connect --json` (stdin: `{"token": "..."}` or `{"useGh": true}`)
+
+→ `{ "contract":1, "integration":"gitlab", "status":"ready"|"invalid", "detail":"...", "scopesSeen":["read_api"] }`
+
+## `rt setup <integration> status --json`
+
+Same envelope as `connect`. For `github`, when gh is authenticated the
+envelope also carries `"handle": "<gh login>"` and `"owners": ["<handle>",
+"<org>", ...]` (the handle plus `gh api user/orgs[].login`) — the app's
+team-create card offers them as `--create-repo` owners.
+
+## `rt setup <integration> create-app --json` (owner-once; stdin: `{"configToken": "..."}`)
+
+The app sends the token as JSON on stdin (no `--config-token-stdin` flag).
+
+## `rt setup apply [--from <stepId>] --json` → NDJSON stream
+
+```jsonc
+{ "event": "plan",  "steps": [ { "id": "home.init", "title": "Create your settings home repo", "kind": "rt" | "app" | "privileged" } , ... ] }
+{ "event": "step",  "id": "home.init", "state": "running" }
+{ "event": "log",   "id": "home.init", "line": "gh repo create m4ttheweric/mattstack-home --private" }
+{ "event": "step",  "id": "home.init", "state": "done", "detail": "pushed main" }
+{ "event": "need",  "id": "services.register", "request": { "type": "app-register-services", "plists": ["com.mattstack.daemon.plist","com.mattstack.deck.plist"] } }   // rt asks the app to do a native thing; app replies via tray.sock and rt continues
+{ "event": "need",  "id": "proxy.install", "request": { "type": "app-privileged", "op": "proxy-install" } }
+{ "event": "step",  "id": "pack.install", "state": "failed", "detail": "claude plugin install exited 1", "remedy": "Open Claude Code once so it finishes first-run, then Retry." }
+{ "event": "done",  "ok": false, "failedStep": "pack.install" }
+```
+
+`kind: "app"` and `"privileged"` steps are executed by the app when the `need`
+event arrives (ServicesRegistrar / PrivilegedInstaller). The app records the
+outcome and serves it at `GET /setup/need/<id>` on tray.sock as
+`{ "state": "pending" | "done" | "failed", "detail": "..." }`. That route
+always answers 200 with that body — an unknown or not-yet-started id is
+`pending`, never 404 (rt tolerates a 404 as `pending` anyway); `POST` → 405,
+empty id → 400. rt polls (1 s) until `done`/`failed`, with a 10-minute
+timeout; `done` → the step succeeds with `detail`, `failed` → the step fails
+with `detail`. Steps are idempotent; `--from` resumes.
+
+`need.request.type` (v1): `app-register-services { plists }` ·
+`app-unregister-services { plists }` · `app-privileged { op: "proxy-install" |
+"proxy-remove" }`. The app's NeedBroker must handle all three; anything else
+is recorded `failed: unknown need type`.
+
+`services.register` plists: `com.mattstack.daemon[.dev].plist` always;
+`com.mattstack.deck[.dev].plist` only when `deck` is bundled (rt checks
+`Contents/Helpers/deck` and logs "deck not bundled yet — only the daemon is
+registered" otherwise). The app reports a plist whose `BundleProgram` is
+missing as `ok:false, status:"notFound"`; rt decides.
+
+Invite codes are copy-paste/deep-link only (16-byte id ‖ 32-byte key,
+Crockford base32, ~77 chars, chunked for display). Relay base URL defaults to
+`https://switchboard.mattstack.dev` (matt-gated DNS; `RT_INVITE_RELAY_URL`
+overrides).
+
+Team-scope secrets layout (in the home repo): `teams/<slug>/.sops.yaml` and
+`teams/<slug>/mattstack/secrets/<domain>.json`, domains `board` and `rt`
+(`secrets.write` writes them; `rt team join` materializes them).
+
+## Step ids (v1, in rt's order)
+
+`home.init` | `home.restore` · `team.create` | `team.join` · `secrets.write` ·
+`path.link` · `intercepts.install` · `settings.seed` · `repos.clone` ·
+`services.register` (app) · `proxy.install` (privileged) · `deck.managed` ·
+`skills.materialize` · `board.keys` · `cron.triage` · `plugins.install` ·
+`fastbrowser.setup` · `herdr.integration` · `extension.install` ·
+`services.start` · `snapshot.push` · `verify`
+
+## tray.sock (app → rt callbacks and app-side truth)
+
+`GET /permissions` → `{ "fda": {"status":"granted"|"denied"|"unknown","detail":"..."}, "notifications": {"status":"authorized"|"denied"|"notDetermined"|"provisional"}, "loginItems": {"status":"enabled"|"requiresApproval"|"notRegistered"|"notFound"} }`
+`POST /permissions/request` `{ "which": "notifications" }` → `{ ok }`
+`GET /services` → `{ "agents": [ { "label": "com.mattstack.daemon", "status": "enabled"|"requiresApproval"|"notRegistered"|"notFound" } ] }`
+`POST /services/register` `{ "plists": [...] }` → `{ ok, results }` · `POST /services/restart` `{ "label" }`
+`POST /privileged/proxy-install` → `{ ok, detail }` (raises the admin prompt)
+`GET /setup/need/<id>` → 200 `{ state, detail }` always (`pending` for unknown ids; app-recorded outcome of a `need` event; rt polls until `done`|`failed`) · `POST` → 405
+`POST /update/check` → `{ ok }` · `GET /version` → `{ "version": "2.8.0", "build": 2008000, "flavor": "prod"|"dev", "path": "/Applications/mattstack.app" }` — `build` is the numeric `CFBundleVersion` = `major*1e6 + minor*1e3 + patch` (2.8.0 → 2008000)
+
+## `rt team create <name> (--remote <url> | --create-repo <owner>) [--others] --json`
+
+→ `{ "contract":1, "slug", "name", "remote", "created": true|false }`
+(`created:false` when the team zone already exists for that remote).
+`--create-repo <owner>` creates `<owner>/mattstack-team-<slug>` with gh and
+uses its URL as the remote; `--remote <url>` uses an existing empty repo.
+`--others` marks the team as having members beyond the creator. Missing both
+→ exit 2 `remote-required`.
+
+## `rt team status [--team <slug>] --json`
+
+→ `{ "contract":1, "slug", "name", "remote", "lastPush": "<ISO-8601>"|null, "members": [ { "username" } ] }`
+
+## `rt setup intent restore <org>/<repo> --json`
+
+Records the restore intent after the app has run the real `rt restore
+<org>/<repo> --json` (age key on stdin as `{"ageKey": "..."}`; the settings
+lane owns that verb). `rt setup apply`'s `home.restore` step then only
+verifies the clone and the Keychain key.
+
+## `rt team join --json` (stdin: `{"code": "..."}`) / `--dry-run`
+
+→ `{ "contract":1, "team": {"slug","name","owner"}, "access": "ok"|"denied"|"unreachable", "peering": "applied"|"idle"|"unavailable", "message": "..." }`
+(exit 0 even when `access` is `denied`/`unreachable`; exit 2 only for
+`invite-unknown`/`invite-malformed`).
+
+## `rt team invite --handle <h> --json`
+
+→ `{ "contract":1, "code": "...", "expiresAt": "...", "pasteBlock": "Install mattstack from … then open mattstack://join/… or paste …", "forgeAccess": "granted"|"manual"|"skipped", "manualSteps": [...] }`
+
+## `rt uninstall --json [--keep-data|--delete-data] [--yes] [--dry-run]`
+
+→ dry-run: `{ "contract":1, "actions": [ { "id":"services.unregister", "title":"Stop and remove the rt daemon and deck services" }, ... ] }`; real run: NDJSON like `apply`.
+
+Action ids (v1, in order): `services.unregister` · `deck.managed-remove` ·
+`proxy.remove` · `path.unlink` · `shell.remove` · `extension.uninstall` ·
+`plugins.uninstall` · `data` (only with `--delete-data`) · `app.trash`.
+`--delete-data` requires `--yes` (non-TTY without it → exit 2
+`confirm-required`; the app's confirmation sheet is the consent, so the app
+always passes `--yes`). `--keep-data` needs no `--yes`.
+
+## Stub
+
+`RT_STUB_SCENARIO=<name>` (DEBUG builds only) makes the app spawn
+`rt-tray/Tests/stub-rt/stub.ts` instead of the bundled rt. Companion env:
+`RT_STUB_PATH` (required; absolute path to `stub.ts`), `RT_STUB_BUN`
+(optional; default `~/.bun/bin/bun`), `RT_STUB_STATE_DIR` (optional; where
+scenario state such as "granted after first check" persists). Scenarios ship
+canned responses for every verb above: `create-happy`, `join-happy`,
+`join-no-access`, `perm-denied-then-granted`, `apply-fail-retry`, `restore`,
+`uninstall`.
diff --git a/docs/superpowers/specs/research/2026-08-20-mattstack-app/research-dependency-inventory.md b/docs/superpowers/specs/research/2026-08-20-mattstack-app/research-dependency-inventory.md
new file mode 100644
index 00000000..030b6239
--- /dev/null
+++ b/docs/superpowers/specs/research/2026-08-20-mattstack-app/research-dependency-inventory.md
@@ -0,0 +1,40 @@
+# Suite external dependency inventory (2026-08-20 15:28) — distilled
+
+## Hard, suite-core
+- git: everything; /usr/bin/git via Xcode CLT (GPL) → CLT install.
+- fzf ≥0.71: all rt pickers; brew today; MIT static → bundle.
+- bun 1.3.x: RUNTIME for mr-board (bun run from checkout), gitq (#!/usr/bin/env bun), claimview rt-dev-hook.ts (pack script), rt-client consumers, rt dev-mode; build-only for rt/deck. MIT static → bundle (packs may ship bun scripts) + compile board/gitq.
+- rt + mattstack.app: own.
+- herdr ≥0.7.5: rt herdr-agent/launch, tray HerdrBridge, mr-board, gitq, shepherdr, claimview dev-servers; H for shepherdr/board launches, O elsewhere (guarded by socket/HERDR_ENV/command -v). ~/.local/bin/herdr 0.8.0 upstream release binary (Rust static); self-updates; installers: curl herdr.dev/install.sh | sh, brew, mise. → provision via its installer (not bundled: self-update would break bundle seal).
+- Claude Code: every skill; plugin mgmt; native installer ~/.local/bin/claude; proprietary → provision via official installer (checklist row).
+- jq: mattstack resolve-args.sh (15 copies), ci-*.sh, claimview gql/query, statusline; /usr/bin/jq on macOS 26 only; MIT static → bundle.
+- shells/coreutils + macOS tools (open lsof ps launchctl xattr osascript pbcopy security plutil PlistBuddy mdfind afplay caffeinate sudo): system.
+- node ≥24: fast-browser (MCP+CLI, Playwright fork), portless (deck), Linear MCP (npx mcp-remote), local-db-mcp, claimview token-capture.cjs; fnm today → bundle private pinned node for suite-internal use (fast-browser, portless); team dev needs its own node anyway.
+- Google Chrome: fast-browser/claimview evidence (H there), rt sdm (O) → Tools row (optional unless team requires).
+- fast-browser: plugin + CLI + pinned Playwright runtime (GH release tarball from m4ttheweric/playwright → ~/.fast-browser/runtime) + Chrome extension side-load + keychain token; CLI shim currently → dev checkout → needs published artifact (npm @mattstack/fast-browser exists).
+- portless ≥0.15.5: deck H; npm-global under node 24; root LaunchDaemon sh.portless.proxy + local CA; deck proxy-restart needs /etc/sudoers.d/local-apps-proxy-restart.
+- deck: ~/.local/bin/deck bun-compiled, built locally, no published release; supervises mrs/gitq/... plists.
+- python3 stdlib: shepherdr (herd DB sqlite/JSON), hooks (guarded), claimview resolve-target.py + inline; brew python today; CLT provides python3 → fine once CLT installed; could port to bun.
+- Claude plugins: mattstack@mattstack (directory marketplace = symlinks to checkouts!), claimview@assured (directory = team clone), fast-browser, current-time, superpowers. mr-board/gitq skills symlinked into ~/.claude/skills. → need published marketplace (MAT-360).
+
+## Optional
+- gh (GitHub flows; static) / glab (GitLab; T/H for GitLab teams; static) → bundle both, expose per team forge + auth rows.
+- terminal-notifier MISSING (osascript fallback) → drop.
+- lnav/logdy (log viewers), chafa/kitten/fd/bat/eza/delta (rt nav/commit previews), tmux/zellij (README stale, NO callers) → not installed; degrade.
+- Editors (Cursor/VS Code) + CLIs → Tools row optional; extension install via app bundle CLIs.
+- codex, Ollama, cloudflared (deck publish; needs tunnel login + CF token) → optional.
+- cswap (Matt-only; uv tool install -e checkout), GitKraken gk hooks in ~/.claude/settings.json (Matt-only; would spray errors if copied).
+
+## Team-specific (claimview/assured)
+- doppler (brew + rt intercept shim; shim must precede /opt/homebrew/bin), sdm (cask + SAML), ldcli (brew tap), pnpm, Postgres local, Linear MCP, local-db-mcp, Figma/FullStory MCP. → pack declares; checklist rows with Install/Connect.
+
+## Runtimes
+bun: runtime for board/gitq/claimview hook → compile board/gitq; bundle bun for pack scripts + rt-client consumers. node: fast-browser, portless, MCPs → bundle private node. python3: CLT. Rust/zig: no (herdr release binary). Swift/Xcode: build only.
+
+## Surprises / breakers on a clean Mac
+1. Source-checkout coupling: ~/.local/bin/rt dev wrapper; fast-browser shim → checkout; directory marketplaces symlink checkouts; skills symlinks; cswap editable; gitq bun link; hand-edited ~/.claude.json MCPs. Need published artifacts: mattstack plugin, fast-browser, claimview pack, gitq (stale dist), mr-board (no package), deck (no release).
+2. mr-board: file: deps tui-kit + rt-client; absolute paths in deck plists; triage via rt cron with absolute bun path.
+3. rt verify/README stale (tmux/zellij); rt daemon install needs tray running.
+4. launchd PATH capture (deck bakes PATH; rt daemon reconstructs via $SHELL -ilc); doppler shim shadowing.
+5. Root pieces: portless daemon + CA; sudoers; keychain; FDA; Chrome ext side-load; xattr.
+6. jq assumed system (26 only). 7. python3 brew (CLT stub prompts). 8. claimview pack stale paths (dev-ports.state.json never created post-RT-28 → get-bearer-token/query broken; feature-flags mentions @assured/dev-ports; mr-board-doctor-api ci-triage.sh path). gitq dist stale reads ~/.rt/secrets.json. 9. plugin version drift. 10. Matt-only hooks in global settings. 11. Auth no installer can bundle (GitLab token, glab/gh auth, doppler, sdm, cloudflared, Linear, fast-browser pairing, Slack, Chrome Auth0). 12. rt prod latent bun branches (lib/enrich.ts:540, bunx pino-pretty, commands/plugin.ts).
diff --git a/docs/superpowers/specs/research/2026-08-20-mattstack-app/research-linear-rulings.md b/docs/superpowers/specs/research/2026-08-20-mattstack-app/research-linear-rulings.md
new file mode 100644
index 00000000..37444cc3
--- /dev/null
+++ b/docs/superpowers/specs/research/2026-08-20-mattstack-app/research-linear-rulings.md
@@ -0,0 +1,41 @@
+# Linear sweep — distribution + mac app rulings (2026-08-20 14:41)
+
+## Binding rulings (sources in parens)
+- Front door = signed Mac app, not curl; rt-tray → mattstack = installer AND onboarding wizard (MAT-383). Board's onboarding role shrinks to "opens populated at the end" (MAT-382/383).
+- Downloading mattstack.app installs the whole suite (rt + deck + board w/ switchboard peering + skills pack + fast-browser); invited teammate lands fully wired (roadmap doc 017c24a92fcf).
+- Curl front door retired to internal bootstrap machinery; deck's separate installer door folds into the app (MAT-360 amendment).
+- Homebrew retired; app installs AND updates rt from m4ttstack/rt GitHub releases; app self-updates via Sparkle (or equivalent); `rt update` thin (MAT-383 c.3; MAT-360). GitHub releases = single publish target, app = single consumer. Updater-drift rule: installer + updater read the SAME releases.
+- Identity: com.mattstack.app, on-disk mattstack.app; daemon label ruled com.rt.daemon (SUPERSEDED by smoke: com.mattstack.daemon[.dev], ratified by form 2026-08-20). m4ttstack = GitHub org slug; brand = mattstack (mattstack.dev owned).
+- Migration from old rt-tray in scope (quit, unregister stale SMAppService, remove, install+register).
+- Dev mode: separate dev identity (mattstack-dev.app / com.mattstack.app.dev), dev daemon = source runner, `rt settings dev-mode` switches which app is registered; update checks off in dev. CLI wrapper at ~/.local/bin/rt unchanged.
+- Implementer notes: delete cached AppIcon.icns; osascript/pkill names track CFBundleExecutable; x64 notarization leg is copy-not-submit.
+- MAT-384: board + gitq = MANAGED deck apps (registry managedBy), board.mattstack / gitq.mattstack, no compat aliases; tray monitors deck (liveness + restart/notify), plumbing only; sequenced after RT-50.
+- Suite install model: "rung ladder dead; install is suite-only (MAT-379 ruling 1, reaffirmed 2026-08-19); `rt install` internal machinery never user-facing; no a-la-carte install path" (roadmap, MAT-360). v1 suite = rt + deck + board + skills pack + fast-browser. "mattstack requires rt; rt always present."
+- MAT-374 ruling 6: rt owns mechanics, Deck (now app) owns ceremony; catastrophe restore on bare machine = installer → rt → `rt restore`; RULE: every ceremony has a CLI equivalent.
+- Team/invite: team definition lives in the team repo; switchboard relay-only; encrypted-blob registry cancelled; invite redemption first step = get forge access to team repo (MAT-379 phase C amended). Team's domain pack comes pre-installed and running for an invited member; pack must be a plugin a machine can install (MAT-382).
+- MAT-382 r.3: personal credentials per user; team config eliminates team-level questions only; every declared integration runs its personal step (gitlab PAT, github token or borrowed gh auth, linear key, slack OAuth click). r.4: `rt setup` verb tree = setup → gitlab/github/linear/slack/team/home; each integration status + connect; bare `rt setup` = state-driven walk (headless fallback). r.5: wizard compiles step list from team's declared integration set and drives one `rt setup` leaf per step so CLI and wizard cannot drift; owner path = same wizard leading with create-a-team incl. slack create-app and inviting teammates. Invite accepted via prompt, not shell arg (key exposure).
+- Settings/state: four stores one resolver; app reads/writes via `rt settings`; one state.db per app; RT-50: ~/.mattstack/rt = runtime only; RT-46 installer creates folded ~/.mattstack from day zero; RT-49 installer seeds rt.repoRoots (`rt settings set rt.repoRoots '["~/Documents/GitHub"]' --scope machine`). MAT-384: deck platform.json CF token is plaintext secret → secrets layer (RT-32).
+- Release: v2.8.0 waits for rebrand; ships resolver+repoRoots+state.db+rebrand together.
+- Process: consensus before execution; no mattstack work without a ticket in the product's team; matt-gated label for pushes/releases/DNS/accounts. MAT-374 r.8: config = defaults always user-overridable; binding lives in pack skill text.
+
+## Requirements (installer scope)
+rt binary + daemon + registration; deck; board + gitq as managed deck apps; skills: mattstack@mattstack plugin + team's domain pack via Claude marketplaces (`claude plugin marketplace add` + `claude plugin install`); fast-browser command on PATH (FB-33); folded ~/.mattstack layout; seed rt.repoRoots; shell integration blocks, ~/.local/bin shims, Claude marketplaces/enabledPlugins (settings-inventory doc). VSIX install not ruled anywhere in Linear (rt verify's brew vsix check deleted rather than fixed).
+Installer flow (MAT-383): fresh download → bootstrap suite → permission walkthrough → invite redemption → hand off to populated board.
+Permissions named: notifications, login items, security/privacy grants, Full Disk Access; dev bundle id gets own grants. DECK-13: binaries under ~/Documents wedge launchd agents (TCC/dyld) → install to ~/.local/bin.
+RT-31 pattern to generalize: doctor → remediation table → interview → verify every claim.
+rt verify must be green: legacy-dir canary, shim installed, PATH precedence of ~/.local/bin (known minor: presence not order).
+
+## Deck/board/gitq today
+Deck: compiled bun binary at ~/.local/bin/deck; `deck setup` installs platform LaunchAgent; labels com.mattstack.deck.*; state ~/.mattstack/deck (settings/access/platform/registry/api .json); ports 11000-11999; platform at deck.mattstack; edge via portless (root LaunchDaemon sh.portless.proxy binding 443, --tld localhost --tld mattstack, local CA certs, /etc/hosts sync); cloudflared tunnel + CF Access for public; installer curl deck.mattstack.dev|sh (DECK-7 unshipped; DECK-11 ceremony matt-gated). Landmines: DECK-10 kickstart doesn't re-read plist (bootout+bootstrap), DECK-13 TCC wedge, DECK-57 stale interpreter path, DECK-58 portless bakes fnm path, DECK-9 allocator bind-probe, DECK-14/15/12.
+mr-board: deck entry mrs port 11006 label com.mattstack.deck.mrs at mrs.localhost; rt-client (socket + relay 9401); team config from team repo team.jsonc on boot; Slack per-user OAuth via `bun run setup`.
+gitq: gitq.localhost; rt-client; secrets via rt daemon; state ~/.cache/gitq/work.
+
+## Dependencies
+RT-47/48/49 DONE. RT-50 (other agent): notifications.json/panel-columns.json → settings keys (tray reads panel-columns + notification settings). MAT-384 after RT-50. RT-32 secrets backlog (tokens to ~/.mattstack/rt/secrets.json 644 meanwhile). MAT-382 `rt setup` tree NOT BUILT. MAT-379 phase C not started. MAT-360 meta repo/marketplace not started. DECK-11/DECK-7 deck release artifact needed. SKILLS-39 last.
+
+## Open questions flagged
+container-vs-clone for ~/.mattstack (MAT-374; RT-30); ~40 personal items outside ~/.mattstack; Slack collaborators spike; invite exposure; app-config-token ergonomics; MAT-372 deck-vs-rt front door (superseded by MAT-383 but not closed); mr-board name call; RT-50 rt hooks/rt plugin; events.db merge; Sparkle not pinned; DECK-13 deck dev-mode; design system unscheduled.
+
+## Phase plan (roadmap)
+1a rt house DONE. 1b front door NOT STARTED (MAT-360 meta repo/marketplace/one release; app = front door; folded layout day zero; org housekeeping). 2 onboarding NOT STARTED (MAT-382 rt setup tree; app wizard MAT-383; invite flow MAT-379 C). 3 safety net (RT-30/32/31, SKILLS-34). 4 pipeline depth. Last: SKILLS-39.
+MAT-383 phase 1 = rebrand (done today); phase 2 = installer/updater duties + wizard (inferred).
diff --git a/docs/superpowers/specs/research/2026-08-20-mattstack-app/research-local-inventory.md b/docs/superpowers/specs/research/2026-08-20-mattstack-app/research-local-inventory.md
new file mode 100644
index 00000000..60cb90cc
--- /dev/null
+++ b/docs/superpowers/specs/research/2026-08-20-mattstack-app/research-local-inventory.md
@@ -0,0 +1,48 @@
+# Local inventory — tray app + suite install mechanics (2026-08-20 14:44)
+
+## mattstack.app today (repo-tools/rt-tray)
+- ~4.5k lines Swift, AppKit shell (accessory app, NSStatusItem, NSPopover/NSWindow, NSMenu, NSOutlineView) hosting SwiftUI (ProcessPanelView, KeyboardConflictView). NO onboarding/permissions/wizard UI. Package.swift: tools 5.9, macOS 13+, no external deps, targets rt-tray + rt-daemon-shim.
+- Files: main.swift (socket guard before SMAppService), AppDelegate (590: menu bar "m"+dev mark+health dot, polling 10s/30s, notifications setup, autoRegisterLoginItem, daemon start), TrayServer (352: unix-socket HTTP at ~/.mattstack/rt/tray.sock: POST /notify, GET /health, POST /daemon/start|stop|restart, POST /flavor/retire, GET /daemon/status), DaemonLifecycle (89: SMAppService.agent(plistName), kickstart), BundleFlavor (MSDaemonLabel/MSDevBuild, login-item opt-out), UpdateChecker (200: polls GitHub latest; alert "run rt update"; no self-update), TrayLog, NotificationManager (388: UN auth, categories, sounds via NSSound), DaemonClient (HTTP :9401 then rt.sock), TrayState, ProcessPanel{View,Controller,Data}, ProcessOutlineView (976), HerdrBridge, MissionControlCheck, KeyboardConflictView, shim main.swift (exit 0 unconfigured / 70 failure).
+- build.sh (345): modes debug|release|dev|install; identity vars; swift build; icons via make-icon.swift (+amber dev); afconvert sounds; embed daemon (prod: RT_DAEMON_BIN ∥ dist/rt, rejects non-Mach-O; dev: shim); LaunchAgent plist templating (@@DAEMON_LABEL@@/@@BUNDLE_ID@@, KeepAlive prod true / dev SuccessfulExit=false); Info.plist templating + MSDevBuild + version from git describe; signing inside-out (Developer ID if present else ad-hoc; daemon w/ scripts/entitlements.plist = JIT, unsigned-exec-mem, disable-exec-page-protection, dyld-env, disable-library-validation); install mode pkill+cp+open. No notarization locally (CI only).
+- Info.plist: LSUIElement true, LSMinimumSystemVersion 13.0, MSDaemonLabel, no usage-description keys. LaunchAgent: BundleProgram Contents/MacOS/rt-daemon --daemon, AssociatedBundleIdentifiers [bundle id] (FDA inheritance), RunAtLoad, ThrottleInterval 10, no Std paths (macOS 26 broke $(HOME) in SMAppService plists).
+- check-bundle.sh (443) asserts identity templating + source-shape.
+- CI release.yml: Dev ID p12 import, sign rt w/ entitlements, build.sh release per arch, vsix, notarize+staple app (notarytool), tarballs rt-darwin-{arm64,x64}-<tag>.tar.gz = rt + mattstack.app + rt-context.vsix, GH release, test-install from tarball.
+
+## Permissions actually needed
+- Full Disk Access on mattstack.app (daemon inherits via AssociatedBundleIdentifiers) — daemon reads repos under rt.repoRoots; `rt --grant-fda` deep link x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles; daemon `tcc:check` handler (readdir each repo → EPERM = blocked).
+- Notifications (UNUserNotificationCenter requestAuthorization alert/sound/badge).
+- Login Items / BTM: SMAppService.agent + mainApp; requiresApproval → open x-apple.systempreferences:com.apple.LoginItems-Settings.extension.
+- Apple Events: osascript quit from CLI only (no NSAppleEventsUsageDescription).
+- Keyboard: Mission Control Control+Up conflict check (reads symbolichotkeys) → Keyboard settings pane. No Accessibility/Input Monitoring.
+- Bun JIT entitlements on daemon.
+
+## rt verify checks (order): rt binary (critical) → legacy dirs → intercept shims + ~/.local/bin on PATH → fzf → mattstack.app active flavor exists (+legacy rt-tray warn) → rt-context extension (warn) → shell integration rtcd (warn) → daemon installed daemon.json (fail) → daemon launchd label listed (warn) → daemon running (fail; Login Items hint) → status detail → daemon api worktrees → tcc access (fail; rt --grant-fda).
+
+## rt install surface
+- post-install: legacy sweep (if rt-tray.app) → installRtBinaryStep (→ ~/.local/bin/rt unless dev mode / not from release dir) → installTrayApp (quit, cp to ~/Applications, xattr -cr) → installExtensions (vsix via editor CLIs: Cursor, VS Code, Insiders, VSCodium, Antigravity, Windsurf) → open app + 2s → rt daemon install (tray /daemon/start, poll; requiresApproval → open Login Items) → shell integration (~/.zshrc/.bash_profile/fish conf.d: PATH ~/.local/bin, rt-cd/rtcd, history hook) → repair wrapper → tcc check → migration outcome.
+- dev-mode: wrapper script at ~/.local/bin/rt (script = dev), dev-mode.json {sourcePath,bunPath}, preload; disableDevMode installs app's rt-daemon binary; handoff: precondition → /flavor/retire → quit → poll → open incoming.
+- daemon-config: API_PORT 9401, tray.sock, rt.sock, daemon.json, labels com.mattstack.daemon[.dev].
+- rt update (new): GH latest → tarball → extracted rt --post-install.
+
+## deck (repo ~/Documents/GitHub/local-apps, product Deck, GitHub m4ttheweric/deck)
+- Bun-compiled binary at ~/.local/bin/deck (63MB); `deck setup` registers platform (label com.mattstack.deck, serve, PORT 11007; gateway :7950; :7942); writes its own plists to ~/Library/LaunchAgents (RunAtLoad+KeepAlive+captured PATH+PORT). Prereqs: **Node 24+ and portless** (`npm i -g portless && portless trust && portless service install` → root LaunchDaemon /Library/LaunchDaemons/sh.portless.proxy.plist binding :443, local CA, routes ~/.portless/routes.json). curl installer scripts/install.sh (deck.mattstack.dev; downloads deck-darwin-<arch> to ~/.mattstack/deck/bin/deck, PATH, deck setup). `deck update` from GH latest. `deck uninstall` leaves portless + app plists.
+- Verbs: status|list, add (--port external / --cmd --dir supervised), remove, restart, logs, override, publish, password, access, domain, migrate, serve|setup|uninstall|update.
+- Config ~/.mattstack/deck: registry.json (apps.<name>: managedBy user|deck|registrar, port, kind, label, command, workingDirectory, env; remove refused unless caller==managedBy), settings.json, platform.json (publicDomain, tlds [localhost, mattstack], secrets.cfApiToken/cfZoneId PLAINTEXT), access.json, api.json.
+- TLD: *.localhost native; .mattstack only partially wired (4 /etc/hosts hand entries; proxy.tlds empty). Public via cloudflared tunnel LaunchAgent com.matthewgoodwin.m4tthew-apps-tunnel.
+- Registered: mrs 11006 (mr-board), gitq 11008, deck 11007, + 8 others; board 11997 external grandfathered DOWN.
+
+## mr-board / gitq
+- mr-board: Bun app run from checkout (`bun src/server.ts`, PORT 11006 via deck label com.mattstack.deck.mrs, caffeinate wrapper); config IN REPO (config.json, config.team.json, .env) + reads ~/.mattstack/rt/secrets.json, repos.json, ~/.mattstack/repos/<slug>; deps rt-client file:../repo-tools/packages/rt-client, tui-kit file:../tui-kit. No binary, no release artifact, no self-install.
+- gitq: @mattstack/gitq 0.1.1 npm (bin/gitq.mjs), board `bun run serve` from checkout PORT 11008 (com.mattstack.deck.gitq); config.json in repo; state ~/.config/gitq; skills via symlink script (also in mattstack plugin). No release artifact for the board.
+
+## skills/plugins
+- Marketplaces: mattstack (directory ~/Documents/GitHub/mattstack-marketplace; plugins mattstack [symlink → mattstack-skills, 0.4.9], fast-browser, current-time), assured (directory ~/.mattstack/teams/claimview → packs/claimview 0.2.14). Installer must: ensure marketplace dirs (clone), `claude plugin marketplace add <dir>`, `claude plugin install <plugin>@<marketplace>` per CLAUDE_CONFIG_DIR (cswap: 4 accounts). Plugin state not declarative.
+
+## Live machine
+- macOS 26.6.1; Swift 6.3.1 via Command Line Tools ONLY (no xcodebuild); bun 1.3.13; node 24.19 (fnm).
+- ~/Applications: mattstack.app (2.7.0, Dev ID signed team 5BF66B3X4V, NOT notarized locally; embedded rt-daemon prints "rt e2e-test"), mattstack-dev.app. Dev mode active (wrapper script), com.mattstack.daemon.dev running.
+- GHOST: `com.rt.daemon` BTM record, exit 78 EX_CONFIG, parent bundle com.mattstack.app — stale; sweep only boots it out when rt-tray.app exists → needs unconditional cleanup.
+- ~/.mattstack: ci-attendants deck repos rt shepherdr teams user work settings.local.jsonc skills.jsonc.
+
+## Gaps for the design
+No in-app onboarding/permissions; updater = CLI only; deck needs Node 24 + portless (npm global + root LaunchDaemon + local CA trust) — heavy external prereqs; mr-board/gitq have no distributable artifact (run from checkouts, config in repo); plugin install per account; stale com.rt.daemon record.
diff --git a/docs/superpowers/specs/research/2026-08-20-mattstack-app/research-onboarding-permissions-ux.md b/docs/superpowers/specs/research/2026-08-20-mattstack-app/research-onboarding-permissions-ux.md
new file mode 100644
index 00000000..a8724a58
--- /dev/null
+++ b/docs/superpowers/specs/research/2026-08-20-mattstack-app/research-onboarding-permissions-ux.md
@@ -0,0 +1,52 @@
+# Web research — macOS onboarding + permissions UX (2026-08-20 14:50)
+
+## HIG
+- Onboarding: fast, optional unless required; integrate permission requests into onboarding if the app needs them to function; postpone nonessential setup; no licensing text. No HIG "setup assistant" layout page.
+- Privacy: request only when needed; purpose strings = brief active-voice sentence with period; pre-alert explanation screen: ONLY a Continue/Next button, no way to leave without viewing the system alert.
+- Sheets: modal; avoid for prolonged flows; Back navigates steps, never dismisses; never Cancel+Done+Back together.
+- Buttons: primary responds to Return; trailing ellipsis when opening another window/app ("Open System Settings…"); style not size distinguishes preferred; start label with verb.
+- Menu bar extras: show a MENU not a popover; let people choose whether to show the extra — offer during setup; template images.
+- Settings: Cmd-, ; toolbar panes; restore last pane.
+
+## Exemplars
+- Ice (SwiftUI, macOS 14+, GPL): dedicated Window scene at launch, hiddenTitleBar + contentSize resizability, no close/minimize; header icon+title 36pt; trust line; one box per permission (title, "needs this to:" bullets, Grant Permission → green Permission Granted; optional ones note "limited mode"); footer Quit / Continue (.large), Continue disabled until required granted; yellow "Continue in Limited Mode"; poll 1s.
+- AltTab (AppKit, GPL): PermissionsWindow; per-row SF icon + bold title + one-line why + "Open X Settings…" + status "● Allowed/Not allowed/Skipped" tinted; checkbox to use without optional perm; poll 0.5s visible/5s pre-start/60s backstop + distributed notif; later menubar "Grant permission" callout only when a feature needs it.
+- Rectangle (AppKit, MIT — borrowable): welcome window (choice), then single-permission Accessibility window, polls 0.3s, auto-closes on grant.
+- Loop (SwiftUI, GPL): tccutil reset before prompting (stale signature); NSAlert then AX prompt; observes com.apple.accessibility.api distributed notif with 250ms delay; tintProminence .primary on macOS 26.
+- Raycast: first-launch setup (hotkey, Accessibility), "Show Onboarding" + "Walkthrough" with progress; contextual re-asks per feature.
+- CleanShot/Bartender: sequential prompts + public permission explainer pages + troubleshooting (re-grant).
+- Shottr FAQ: moving the app after grant leaves stale TCC entry.
+- Tailscale: explains sysext approval per OS version. Docker: one admin prompt, default vs advanced. OrbStack: admin prompt, graceful degrade switch. Warp: sign-in optional. Arc: 28-screen account-gated = anti-pattern.
+- Pattern: dedicated fixed-size non-resizable window before main UI; one row per permission (icon, title, one-sentence why, status badge, button to exact pane); live re-check while visible; required vs optional with limited-mode path; Quit as only other exit.
+
+## Technical per permission
+- Notifications: requestAuthorization prompts once; status via notificationSettings().authorizationStatus; cannot re-prompt once denied; deep link x-apple.systempreferences:com.apple.Notifications-Settings.extension?id=<bundleID>; .provisional = quiet, no prompt; needs real bundle + binary in Contents/MacOS; LSUIElement apps fine.
+- FDA: no API, no prompt; deep link …security?Privacy_AllFiles; probe read of protected path (inket: ~/Library/Containers/com.apple.stocks on 12+; MacPaw: ~/Library/Safari/CloudTabs.db, Bookmarks.plist, TCC.db, /Library/Preferences/com.apple.TimeMachine.plist); the probe itself ADDS the app to the FDA list (user just flips toggle); System Settings says app won't have FDA until quit → Quit & Reopen; responsible-process attribution (Terminal's FDA covers CLI; app's FDA covers helpers); keyed to signing identity (+bundle id, path) → sign with stable identity (Apple Development for dev, Developer ID for dist), moving app leaves stale entry; tccutil reset <Service> <bundleID>.
+- Accessibility: AXIsProcessTrustedWithOptions(prompt: true); deep link Privacy_Accessibility; poll; undocumented com.apple.accessibility.api notif (unreliable; fails for unsigned on 15+); stale value right after toggle on 13+ (Settings offers quit+relaunch).
+- Automation: AEDeterminePermissionToAutomateTarget (target must be running), NSAppleEventsUsageDescription required, deep link Privacy_Automation.
+- Login items/BTM: SMAppService.mainApp register/unregister/status (.requiresApproval) + openSystemSettingsLoginItems(); one BTM notification; macOS 26 may prompt re background tasks; "Allow in the Background" entries can't be removed programmatically; read status on appear + appearsActive.
+- Screen recording: not needed.
+- Re-check: timer 0.5–1s ONLY while window visible + NSApplication.didBecomeActiveNotification / appearsActive + AX notif as bonus. No push API for FDA/Notif/Automation.
+- Deep links: FDA Privacy_AllFiles; Accessibility Privacy_Accessibility; Automation Privacy_Automation; Notifications-Settings.extension?id=; LoginItems-Settings.extension (prefer API).
+
+## Libraries
+- jaywcjlove/PermissionFlow (+SystemSettingsKit) MIT, v2.11.2 2026-08-16, macOS 13+, SPM, SwiftUI+AppKit; typed deep links useful; drag-panel UX non-standard; 4 months old → pin.
+- MacPaw/PermissionsKit MIT ObjC, FDA probe reference only. inket/FullDiskAccess MIT ~150 lines, copy probe.
+- sindresorhus/LaunchAtLogin-Modern MIT (2023) thin SMAppService wrapper; no requiresApproval → write 20 lines instead.
+- sindresorhus/Settings: redundant on 13+ (Settings scene + TabView).
+- Sparkle 2.9.6 MIT-style.
+- CodeEdit WelcomeWindow (document launchpad, wrong shape); OnboardingKit / SwiftUI-Onboarding (iOS idiom, 15+) skip. Ice/Loop/AltTab = GPL design reference only; Rectangle MIT borrowable. Luminare skip.
+- Bonus: KeyboardShortcuts, Defaults, MenuBarExtraAccess (MIT, control SwiftUI MenuBarExtra/NSStatusItem).
+- Verdict: no macOS package gives a HIG-shaped native checklist; write ~200 lines (Permission model: title, why, isRequired, check(), request(), settingsURL; manager polls while visible; SwiftUI rows).
+
+## Design-system bits
+- SF Symbols: checkmark.circle.fill green / xmark.circle red / exclamationmark.triangle yellow / grey optional; Ice checkmark.shield.
+- Form(.grouped) macOS 13+ for native grouped rows; LabeledContent rows.
+- Settings scene + TabView with Tab(systemImage:); Window scene + openWindow(id:); .windowResizability(.contentSize); .windowStyle(.hiddenTitleBar); custom enum Step + switch + .transition(.push) instead of NavigationStack (toolbar chevron wrong idiom); bottom-trailing Back/Continue, Continue .keyboardShortcut(.defaultAction), .controlSize(.large); subtle step indicator.
+- MenuBarExtra (13+) .menu|.window; auto-terminate if removed unless LSUIElement; gaps: can't dismiss .window programmatically; MenuBarExtraAccess patches; HIG: menu not popover.
+- Liquid Glass/macOS 26: standard controls pick it up when built with Xcode 26 SDK; avoid overuse; template status icon; tintProminence.
+
+## Recommendations (agent)
+(a) One dedicated Window scene "onboarding" (re-openable "Show Onboarding…"), contentSize resizability, hiddenTitleBar or title-less, fixed width ~520–600pt; custom page model; 2–3 screens max; offer menu-bar-extra opt-in; pre-alert screens single Continue; allow closing but keep a menu-bar callout (AltTab) — degrade not nag.
+(b) Checklist: header icon + "needs a few permissions" + trust line; rows ordered by necessity: symbol · Title · one sentence why · status badge · action button (ellipsis); optional rows "works without this"; per-permission behaviors above; FDA row: probe adds app to list, then "Relaunch" after toggle; login item: requiresApproval badge + openSystemSettingsLoginItems + copy warning about the BTM notification; re-check timer while visible + didBecomeActive; Continue enabled when required satisfied; "Continue in limited mode"; Quit; same rows in Settings → Permissions + "Reset & re-request".
+(c) Take: Sparkle; maybe SystemSettingsKit (pin); MenuBarExtraAccess if SwiftUI MenuBarExtra; KeyboardShortcuts if hotkey. Write: Permission model + manager + rows (~200 lines; FDA probe from inket MIT). Skip the rest.
diff --git a/docs/superpowers/specs/research/2026-08-20-mattstack-app/research-sparkle-install-launchd.md b/docs/superpowers/specs/research/2026-08-20-mattstack-app/research-sparkle-install-launchd.md
new file mode 100644
index 00000000..c3a0a161
--- /dev/null
+++ b/docs/superpowers/specs/research/2026-08-20-mattstack-app/research-sparkle-install-launchd.md
@@ -0,0 +1,37 @@
+# Web research — Sparkle, self-install, launchd, signing, uninstall (2026-08-20 14:47)
+
+## Sparkle 2
+- Latest 2.9.6 (2026-08-17), security fixes in 2.9.5/6; macOS 12+ (SPM binaryTarget). 2.9.0: signed feeds (SURequireSignedFeed), markdown notes, hardwareRequirements, minimumUpdateVersion; sparkle-cli removed from binary dist.
+- SPM: `.package(url: "https://github.com/sparkle-project/Sparkle", from: "2.9.6")`, product "Sparkle". Non-Xcode gotchas: link flag `-Xlinker -rpath -Xlinker @executable_path/../Frameworks`; copy `.build/artifacts/sparkle/Sparkle/Sparkle.xcframework/macos-arm64_x86_64/Sparkle.framework` → Contents/Frameworks with `cp -R`/ditto (preserve symlinks; never unzip); per-arch swift build + lipo for universal (openclaw, CodexBar, symfony-cli-menubar, muxy do this). Missing rpath → dyld Library not loaded.
+- Signing: inside-out, NO --deep (corrupts XPC sigs; notarization passes but updates fail): Installer.xpc → Downloader.xpc (--preserve-metadata=entitlements) → Autoupdate → Updater.app → Sparkle.framework → helpers → app; all `-o runtime --timestamp`. Don't rename Sparkle XPC bundle ids. Non-sandboxed: may delete Versions/B/XPCServices.
+- Info.plist: SUFeedURL (https), SUPublicEDKey, numeric increasing CFBundleVersion (Sparkle compares this!), SUEnableAutomaticChecks, SUScheduledCheckInterval (≥3600), SUAutomaticallyUpdate (silent download, install on quit), SUVerifyUpdateBeforeExtraction=YES, optional SURequireSignedFeed. Do NOT set SUEnable*Service keys (sandbox-only).
+- LSUIElement apps: use gentle reminders (SPUStandardUserDriverDelegate supportsGentleScheduledUpdateReminders etc.) → show "Update available" in status menu/notification. Driver: SPUStandardUpdaterController(startingUpdater:updaterDelegate:userDriverDelegate:), bind menu item to publisher(for: \.canCheckForUpdates). Immediate install hook: updater(_:willInstallUpdateOnQuit:immediateInstallationBlock:).
+- Keys/appcast/CI: generate_keys (-x/-f export/import); CI secret → --ed-key-file; generate_appcast <dir> --download-url-prefix <gh release url>/ -o appcast.xml (deltas if previous zips present; v4 delta default); enclosures zip (`ditto -c -k --sequesterRsrc --keepParent`) or APFS+lzfse DMG; GH Actions jozefizso/setup-sparkle@v2. Patterns: CodexBar/openclaw commit appcast.xml to main served raw; Presentify → GitHub Pages; Ghostty own host. Homebrew cask: auto_updates true + livecheck :sparkle.
+- Sparkle does NOT manage launchd agents; after update the agents still run OLD binaries (old inodes). Convention: on app launch, if bundle version changed → register() each agent (idempotent) then `launchctl kickstart -k gui/$UID/<label>`. Installer strips quarantine, validates signature/Team ID before swap.
+- Alternatives: Squirrel.Mac (Electron only), mxcl/AppUpdater (DMG-on-GH-releases only, tiny), custom checkers (notify only). Sparkle = standard (Tailscale standalone, Ghostty, CodexBar...).
+
+## Self-install / artifact / CLI on PATH
+- LetsMove dormant (ObjC, no SPM, 2020). DMG makes it moot; add ~40-line guard "running from DMG/translocated → move me".
+- Notary accepts zip/DMG/pkg; staple app/DMG/pkg (not zip). Convention: DMG for first install (create-dmg or hdiutil APFS ULFO + codesign + notarize + staple), zip for Sparkle. pkg only if root installs. Homebrew CASK is an expected secondary channel for dev tools (app, binary stanza, auto_updates, uninstall launchctl/quit, zap trash).
+- CLI on PATH survey: old-era editors symlink /usr/local/bin via osascript admin (VS Code, Zed w/ unprivileged-first, GitHub Desktop, Nova, Tower); CLI-first modern tools use user bin dir + rc PATH line (OrbStack ~/.orbstack/bin + compat symlinks, Docker ≥4.18 ~/.docker/bin option, Cursor agent ~/.local/bin, Claude Code ~/.local/bin + ~/.zshrc, Warp). Ghostty: no symlink, sets PATH for own shells. Recommendation: ~/.local/bin symlink without prompt + guarded PATH line with consent; /usr/local/bin opt-in via Zed pattern.
+- Claude Code precedent: ~/.local/bin/claude symlink → ~/.local/share/claude/versions/.
+
+## SMAppService / launchd
+- API macOS 13+: agent(plistName:) — plist in Contents/Library/LaunchAgents; BundleProgram (bundle-relative; Contents/MacOS safest); register() bootstraps immediately + each login (kSMErrorAlreadyRegistered if already; kSMErrorLaunchDeniedByUser); unregister() terminates running job; status notRegistered/enabled/requiresApproval/notFound; openSystemSettingsLoginItems().
+- Multiple agents per app: yes, one plist each; all show as ONE switch under the app in Login Items & Extensions; bundled agents auto-associate (AssociatedBundleIdentifiers is for legacy plists; harmless). One "Background Items Added" notification/day; macOS 26 additionally prompts about background tasks continuing after quit (uncertain UX). MDM pre-approval possible. `sfltool resetbtm` resets DB.
+- Restart: no API; unregister→register needs ~500ms sleep (EPERM otherwise) and kills job; `launchctl kickstart -k gui/$UID/<label>` restarts in place (DTS recommends kickstart for starting; widely used; not formally "the SMAppService way"). Don't mix SMAppService with launchctl bootstrap of same plist. After update: register() once then kickstart -k.
+- Upgrade trap: keep Label, Team ID, and helper code-signing identifier stable (launch constraint violation otherwise — Mozilla VPN). Bundle-id change: BTM keyed by bundle id/Team ID/path/UUID; stale entries linger until sfltool resetbtm + reboot; unregister BEFORE renaming.
+- KeepAlive: true unconditional (ThrottleInterval default 10s); {SuccessfulExit:false} restart on non-zero; Crashed; PathState; RunAtLoad.
+- TCC: app that registered via SMAppService = responsible code → FDA on app flows to its agents (since 11.4 helpers don't inherit via ad-hoc parentage); children spawned by agent stay in chain; daemonizing/re-exec can break it.
+
+## Signing / notarization / Bun
+- Flow: sign all Mach-O inside-out Dev ID `--options runtime --timestamp`; ditto zip; notarytool submit --wait; stapler staple app/dmg; zip can't staple (staple app, re-zip). Hardened runtime on every executable incl. rt; no get-task-allow; XML entitlements.
+- Bun entitlements: template has 5 keys; actually needed: allow-jit (JSC MAP_JIT); allow-unsigned-executable-memory maybe; disable-library-validation only for non-Team dylibs/native addons; dyld-env only for DYLD_*. Recommend start allow-jit only, test; Bun ≥1.2.4 signing; 1.3.12 unsignable (fixed 1.3.13).
+- Quarantine: downloads by a non-sandboxed app are NOT quarantined unless LSFileQuarantineEnabled=YES (don't set). Browser zip → translocation until moved; DMG avoids. `ditto -x -k` to avoid ._* pollution.
+
+## Uninstall conventions
+- Docker: in-app Troubleshoot ▸ Uninstall + CLI uninstall binary; OrbStack: manual list; Tailscale: trash + manual; VS Code/Nova/GH Desktop: "Uninstall CLI" buttons; Homebrew cask zap. Expectation: "Uninstall mattstack…" menu item AND `rt uninstall`: unregister agents → remove ~/.local/bin symlinks + PATH line → uninstall VS Code ext → optional data wipe → trash app.
+
+## Recommended stack (agent)
+Sparkle 2.9.x via SPM (steps above), DMG first install + zip enclosure, appcast on GH Pages/raw main from CI (setup-sparkle, ed-key secret, generate_appcast with last ~3 zips for deltas), gentle reminders in menu, immediate-install hook when idle; agent restart on version change; ~/.local/bin symlink + consented PATH line; one plist per service in Contents/Library/LaunchAgents (rt-daemon, deck, board, gitq) BundleProgram in Contents/MacOS, KeepAlive {SuccessfulExit:false}; register all first run, requiresApproval → openSystemSettingsLoginItems; uninstall menu + verb; Homebrew cask secondary.
+Verify empirically: minimal Bun entitlements; kickstart -k on SMAppService across 14/15/26; --maximum-deltas default; macOS 26 background-task prompt.