dsh-compound-engineering 0.0.0-stage → 0.1.1

package/skills/ce-polish/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: ce-polish
+description: "Polish a working feature through user-directed live browser feedback. Use when a functional feature needs focused UX refinement before shipping."
+disable-model-invocation: true
+argument-hint: "[PR number, branch name, or blank for current branch]"
+---
+
+# Polish
+
+Put a working feature in front of the user and turn their live observations into focused UX fixes on the running page. Two ways to collect those observations: **traditional**, where the user types what could be better; and **live**, where they talk and draw on the page while a voice interviewer turns speech into units and you act on them at checkpoints.
+
+**Done:** the user ends the polish loop, every requested fix is reflected in the live feature or reported as blocked, and the in-scope changes are saved in local commit(s). A live session also ends with a residual list of the units that were not applied and the path of its session log. A server or checkout blocker also ends the run when it is reported with the evidence needed to resume.
+
+**Boundaries:** the user drives what to inspect and change; do not invent an autonomous checklist or expand into general QA. Never work on the repository's default branch. This workflow may edit and locally commit the requested polish, and in live mode the disclosed riffrec setup commit, but it never pushes or opens a PR.
+
+## Run
+
+1. **Ask live or traditional.** Ask once, before any server starts. Include this disclosure with the question: live mode needs an OpenAI key in the environment, runs a voice interviewer in the page that hears the user, is told what they click and draw on, and looks at their screen when they point at something or ask it to, streams the session to a local endpoint this skill runs, and, when riffrec is not yet in the app, adds the riffrec dependency and a provider mount as a setup commit on the current branch that stays after the session. Traditional continues with steps 2–5 unchanged. Live: read `references/live-start.md`; it owns preconditions, install, the endpoint, and the URL handoff, applies the workspace and server rules of `references/run.md` itself, then routes to `references/live-loop.md` for the session and its close. Steps 2–5 do not run for a live session.
+2. **Get the live page ready.** Read `references/run.md` before resolving the requested ref or starting anything. It owns existing-worktree safety, dev-server discovery, the bundled-script calls, reachability, and the browser handoff.
+3. **Wait for observations.** Tell the user where the server is running and ask what could be better. Do not start a review pass while they browse.
+4. **Iterate.** For each requested change, inspect only as needed, edit the in-scope surface, and let hot reload update the page. When the user asks you to inspect the result, use a browser capability available in the active harness; if none exists, ask them to describe what they see.
+5. **Close locally.** When the user says they are done, invoke `ce-commit` for the polish changes, then report the commit(s), the still-running server URL, and any residual blocker.

package/skills/ce-polish/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/skills/ce-polish/references/dev-server-astro.md

@@ -0,0 +1,58 @@
+# Astro dev-server recipe (auto-detect fallback)
+
+Loaded when `detect-project-type.sh` returns `astro` and the startup tuple still lacks a command.
+
+## Signature
+
+- `astro.config.js`, `astro.config.mjs`, or `astro.config.ts` exists
+- `package.json` contains an `astro` dependency
+
+## Start command
+
+Standard:
+
+```bash
+npm run dev
+```
+
+The `dev` script in `package.json` typically wraps `astro dev`. Also valid (read `package.json` scripts to confirm which the project uses):
+
+```bash
+pnpm dev
+yarn dev
+bun run dev
+```
+
+Prefer the package manager indicated by the lockfile:
+- `pnpm-lock.yaml` -> `pnpm dev`
+- `yarn.lock` -> `yarn dev`
+- `bun.lock` / `bun.lockb` -> `bun run dev`
+- `package-lock.json` or none -> `npm run dev`
+
+## Port
+
+Default: `4321`. Astro respects `--port <port>` and the `server.port` field in `astro.config.*`. Overrides follow the cascade in `references/dev-server-detection.md`.
+
+## Stub generation
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Astro dev",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["run", "dev"],
+      "port": 4321
+    }
+  ]
+}
+```
+
+Substitute the resolved package manager (`npm` / `pnpm` / `yarn` / `bun`) and port.
+
+## Common gotchas
+
+- **SSR vs SSG:** `astro dev` runs identically for both output modes; the difference only matters at build time. Polish does not need to distinguish between them.
+- **Astro config takes precedence over Vite config:** Astro uses Vite under the hood but ships its own config file. The `astro` type takes precedence over `vite` when both `astro.config.*` and `vite.config.*` exist. This is rare -- Astro projects do not usually have a separate Vite config file.
+- **Dev toolbar (Astro 4+):** Astro 4+ includes a dev toolbar that adds overlay UI in the browser. It does not affect port binding or URL routing -- polish can ignore it.

package/skills/ce-polish/references/dev-server-detection.md

@@ -0,0 +1,40 @@
+# Dev-server port detection
+
+Port resolution runs via `scripts/resolve-port.sh`. This document explains the probe order, framework defaults, and the script's intentional parsing choices.
+
+This cascade runs only while the startup tuple's port remains unresolved. A numeric port from the selected launch configuration completes that fact and skips this cascade. When the cascade is needed, it supplies only the port; it never replaces a selected command, working directory, or environment.
+
+## Priority order
+
+1. **Explicit `--port` flag** -- if the caller passed `--port <n>`, use it directly.
+2. **Framework config files** -- `next.config.*`, `vite.config.*`, `nuxt.config.*`, `astro.config.*` scanned with a conservative regex matching only numeric literal port values. Variable references (`process.env.PORT`, `getPort()`) are deliberately not matched.
+3. **Rails `config/puma.rb`** -- grep for `port <n>`.
+4. **`Procfile.dev`** -- web line scanned for `-p <n>` / `--port <n>` / `-p=<n>` / `--port=<n>`.
+5. **`docker-compose.yml`** -- line-anchored grep for `"<n>:<n>"` port mapping patterns. Not full YAML parsing.
+6. **`package.json`** -- `dev`/`start` scripts scanned for `--port <n>` / `-p <n>` / `--port=<n>` / `-p=<n>`.
+7. **`.env` files** -- checked in override order: `.env.local` -> `.env.development` -> `.env` (first hit wins). Parses `PORT=<n>` with quote stripping and comment truncation.
+8. **Framework default lookup table** -- see table below.
+
+## Framework defaults
+
+| Framework | Default port |
+|-----------|-------------|
+| Rails | 3000 |
+| Next.js | 3000 |
+| Nuxt | 3000 |
+| Remix (classic) | 3000 |
+| Vite | 5173 |
+| SvelteKit | 5173 |
+| Astro | 4321 |
+| Procfile | 3000 |
+| Unknown | 3000 |
+
+## `.env` parsing choices
+
+`resolve-port.sh` makes two deliberate parsing choices for real-world `.env` files; do not "simplify" them away:
+
+**(a) Quote stripping on `.env` values.** Strips surrounding `"` and `'` from `PORT=` values (so `PORT="3001"` resolves to `3001`), because quoting is common in real `.env` files.
+
+**(b) Comment stripping on `.env` values.** Truncates at `#` after trimming whitespace (so `PORT=3001 # dev only` resolves to `3001`), because inline comments are common.
+
+**(c) No instruction-file port grep.** The script does not grep `AGENTS.md`/`CLAUDE.md` for port references. Instruction files carry natural language that may mention ports in contexts unrelated to the dev server (documentation, examples, troubleshooting), producing false positives that are hard to debug; the filename is also harness-specific. Framework config files and `.env` are the reliable sources of truth. The agent may still honor a dev-server port it reads from its in-context project instructions, but the script does not shell-grep named instruction files.

package/skills/ce-polish/references/dev-server-next.md

@@ -0,0 +1,61 @@
+# Next.js dev-server recipe (auto-detect fallback)
+
+Loaded when `detect-project-type.sh` returns `next` and the startup tuple still lacks a command.
+
+## Signature
+
+- `next.config.js`, `next.config.mjs`, `next.config.ts`, or `next.config.cjs` exists
+- `package.json` contains a `next` dependency
+
+## Start command
+
+Standard:
+
+```bash
+npm run dev
+```
+
+Also valid (read `package.json` scripts to confirm which the project uses):
+
+```bash
+pnpm dev
+yarn dev
+bun run dev
+```
+
+Prefer the package manager indicated by the lockfile:
+- `pnpm-lock.yaml` -> `pnpm dev`
+- `yarn.lock` -> `yarn dev`
+- `bun.lock` / `bun.lockb` -> `bun run dev`
+- `package-lock.json` or none -> `npm run dev`
+
+## Port
+
+Default: `3000`. Next.js respects `-p <port>` / `--port <port>` and the `PORT` env var. Overrides follow the cascade in `references/dev-server-detection.md`.
+
+## Turbopack
+
+Next.js 14+ supports `--turbo` (and 15+ makes it default). If the `dev` script in `package.json` includes `--turbo`, preserve it. Turbopack changes reload behavior but not port or URL conventions.
+
+## Stub generation
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Next dev",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["run", "dev"],
+      "port": 3000
+    }
+  ]
+}
+```
+
+Substitute the resolved package manager (`npm` / `pnpm` / `yarn` / `bun`) and port.
+
+## Common gotchas
+
+- **Monorepo roots:** in a pnpm/Turborepo monorepo, `npm run dev` at the root typically fans out to multiple packages. Users should set `cwd` in the repo-root launch configuration to the specific Next app (`cwd: "apps/web"`).
+- **Env loading:** `.env.local` is loaded automatically by Next; polish does not need to export it.

package/skills/ce-polish/references/dev-server-nuxt.md

@@ -0,0 +1,58 @@
+# Nuxt dev-server recipe (auto-detect fallback)
+
+Loaded when `detect-project-type.sh` returns `nuxt` and the startup tuple still lacks a command.
+
+## Signature
+
+- `nuxt.config.js`, `nuxt.config.mjs`, or `nuxt.config.ts` exists
+- `package.json` contains a `nuxt` dependency
+
+## Start command
+
+Standard:
+
+```bash
+npm run dev
+```
+
+Also valid (read `package.json` scripts to confirm which the project uses):
+
+```bash
+pnpm dev
+yarn dev
+bun run dev
+```
+
+Prefer the package manager indicated by the lockfile:
+- `pnpm-lock.yaml` -> `pnpm dev`
+- `yarn.lock` -> `yarn dev`
+- `bun.lock` / `bun.lockb` -> `bun run dev`
+- `package-lock.json` or none -> `npm run dev`
+
+## Port
+
+Default: `3000`. Nuxt respects `--port <port>` and the `PORT` env var. Overrides follow the cascade in `references/dev-server-detection.md`.
+
+## Stub generation
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Nuxt dev",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["run", "dev"],
+      "port": 3000
+    }
+  ]
+}
+```
+
+Substitute the resolved package manager (`npm` / `pnpm` / `yarn` / `bun`) and port.
+
+## Common gotchas
+
+- **Nitro server engine:** Nitro (Nuxt's server engine) adds its own dev server behind Nuxt's; polish only cares about the Nuxt port. Do not probe the Nitro internal port separately.
+- **Port auto-increment:** Nuxt may move to another port when 3000 is occupied. If the resolved URL does not answer, use the server log to let the user correct the start configuration.
+- **Nuxt 3 vs Nuxt 2:** Nuxt 3 uses `nuxt.config.ts`, Nuxt 2 uses `nuxt.config.js` -- both are detected by the signature check. The dev-server command and port defaults are the same across both versions.

package/skills/ce-polish/references/dev-server-procfile.md

@@ -0,0 +1,59 @@
+# Procfile / Overmind dev-server recipe (auto-detect fallback)
+
+Loaded when `detect-project-type.sh` returns `procfile` and the startup tuple still lacks a command. Rails apps with `bin/dev` take precedence over the bare Procfile path (see `dev-server-rails.md`).
+
+## Signature
+
+- `Procfile` or `Procfile.dev` exists at the repo root
+- `bin/dev` is **not** present (if it is, use the Rails recipe)
+
+## Start command
+
+Prefer `overmind` when available — it handles socket files, supports hot-restart per process, and is the community default for multi-process dev:
+
+```bash
+overmind start -f Procfile.dev
+```
+
+Fallback to `foreman` when `overmind` is not installed:
+
+```bash
+foreman start -f Procfile.dev
+```
+
+If both are missing, prompt the user for the start command rather than guessing.
+
+## Port
+
+Default: `3000`. Procfile-based projects list their processes in `Procfile.dev`, so the authoritative port comes from the `web:` line:
+
+```
+web: bundle exec puma -p 3000 -C config/puma.rb
+worker: bundle exec sidekiq
+```
+
+Parse the `web:` line for `-p <n>` or `--port <n>`. If neither is present, fall through to the cascade in `references/dev-server-detection.md`.
+
+## Stub generation
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Overmind dev",
+      "runtimeExecutable": "overmind",
+      "runtimeArgs": ["start", "-f", "Procfile.dev"],
+      "port": 3000
+    }
+  ]
+}
+```
+
+Substitute `foreman` if `overmind` is unavailable on the user's machine — the stub represents what the user will run, not a canonical recipe.
+
+## Common gotchas
+
+- **Socket files:** `overmind` writes a socket to `.overmind.sock` by default. If another instance or a stale socket prevents startup, report the log evidence and let the user decide whether to reuse that process or correct the start configuration. The `OVERMIND_SOCKET` env var can redirect the socket to a per-run path when the project already uses that convention.
+- **Procfile vs Procfile.dev:** production and development Procfiles often differ. Always prefer `Procfile.dev` for polish.
+- **Multiple web processes:** some Procfiles split web traffic across multiple processes (API + frontend). Polish can only open one URL — users with multi-web setups should author a repo-root launch configuration explicitly to select which process is "the dev server" for polish.

package/skills/ce-polish/references/dev-server-rails.md

@@ -0,0 +1,50 @@
+# Rails dev-server recipe (auto-detect fallback)
+
+Loaded when `detect-project-type.sh` returns `rails` and the startup tuple still lacks a command.
+
+## Signature
+
+- `bin/dev` exists and is executable
+- `Gemfile` exists
+
+## Start command
+
+```bash
+bin/dev
+```
+
+`bin/dev` is the Rails 7+ convention for "start everything" (web + assets watcher + optional workers). It is a one-liner script that invokes `foreman start -f Procfile.dev` under the hood, so `Procfile.dev` is the canonical place to read the *actual* command if `bin/dev` is missing or non-executable.
+
+## Port
+
+Default: `3000`. Overrides follow the cascade in `references/dev-server-detection.md`:
+1. `Procfile.dev` `web:` line may contain `-p <n>`
+2. `config/puma.rb` may bind to a non-default port
+3. `.env` / `.env.development` `PORT=<n>`
+4. a dev-server port explicitly stated in the project's active instructions in context (not grepped from instruction files)
+
+## Stub generation for `launch.json`
+
+When the user accepts saving the launch configuration, emit the Rails stub from `launch-json-schema.md`:
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Rails dev",
+      "runtimeExecutable": "bin/dev",
+      "runtimeArgs": [],
+      "port": 3000
+    }
+  ]
+}
+```
+
+If the cascade resolved a non-3000 port, substitute it in the stub's `port` field before writing.
+
+## Common gotchas
+
+- **Bundler path:** some machines require `bundle exec bin/dev`. If `bin/dev` fails with a load-path error, fall back to `bundle exec bin/dev`.
+- **Foreman vs overmind:** `Procfile` vs `Procfile.dev` often both exist. Rails' `bin/dev` resolves to `Procfile.dev`; if the project uses `overmind` explicitly, prefer `overmind start -f Procfile.dev` (see `dev-server-procfile.md`).
+- **SSL dev server:** `rails s --ssl` serves over `https://`. Treat server output or a user correction as evidence that replaces the default HTTP candidate, then verify that HTTPS URL against the selected instance before handoff. The launch configuration needs no URL field; an explicit `port` still helps identify the intended endpoint without locking its scheme.

package/skills/ce-polish/references/dev-server-remix.md

@@ -0,0 +1,58 @@
+# Remix dev-server recipe (auto-detect fallback)
+
+Loaded when `detect-project-type.sh` returns `remix` and the startup tuple still lacks a command.
+
+## Signature
+
+- `remix.config.js` or `remix.config.ts` exists (classic Remix)
+- Remix 2.x+ on Vite has no `remix.config.*` -- it uses `vite.config.ts` with the Remix plugin, so it resolves as `vite` type, not `remix`
+
+## Start command
+
+Standard:
+
+```bash
+npm run dev
+```
+
+The `dev` script in `package.json` typically wraps `remix dev`. Also valid (read `package.json` scripts to confirm which the project uses):
+
+```bash
+pnpm dev
+yarn dev
+bun run dev
+```
+
+Prefer the package manager indicated by the lockfile:
+- `pnpm-lock.yaml` -> `pnpm dev`
+- `yarn.lock` -> `yarn dev`
+- `bun.lock` / `bun.lockb` -> `bun run dev`
+- `package-lock.json` or none -> `npm run dev`
+
+## Port
+
+Default: `3000`. Remix respects `--port <port>` flag. Classic Remix dev server also reads the `PORT` env var. Overrides follow the cascade in `references/dev-server-detection.md`.
+
+## Stub generation
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Remix dev",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["run", "dev"],
+      "port": 3000
+    }
+  ]
+}
+```
+
+Substitute the resolved package manager (`npm` / `pnpm` / `yarn` / `bun`) and port.
+
+## Common gotchas
+
+- **Classic vs Vite:** Classic Remix uses `remix.config.js`; new Remix (v2+) uses Vite -- detected as `vite` type, not `remix`. The `remix` type is specifically for classic Remix projects that still have a `remix.config.*` file.
+- **Remix v1 vs v2 dev server:** `remix dev` in v2 starts an Express-based dev server that binds a port; `remix dev` in v1 was a watcher only (no server). Polish needs v2+ for the dev server to bind a port and respond to reachability probes.
+- **Remix on Vite inherits Vite's port:** When Remix runs on Vite (no `remix.config.*`), the default port is 5173 (Vite's default), not 3000. That case is handled by the `vite` recipe, not this one.

package/skills/ce-polish/references/dev-server-sveltekit.md

@@ -0,0 +1,58 @@
+# SvelteKit dev-server recipe (auto-detect fallback)
+
+Loaded when `detect-project-type.sh` returns `sveltekit` and the startup tuple still lacks a command.
+
+## Signature
+
+- `svelte.config.js`, `svelte.config.mjs`, or `svelte.config.ts` exists
+- `package.json` contains a `@sveltejs/kit` dependency
+
+## Start command
+
+Standard:
+
+```bash
+npm run dev
+```
+
+The `dev` script in `package.json` typically wraps `vite dev` via SvelteKit. Also valid (read `package.json` scripts to confirm which the project uses):
+
+```bash
+pnpm dev
+yarn dev
+bun run dev
+```
+
+Prefer the package manager indicated by the lockfile:
+- `pnpm-lock.yaml` -> `pnpm dev`
+- `yarn.lock` -> `yarn dev`
+- `bun.lock` / `bun.lockb` -> `bun run dev`
+- `package-lock.json` or none -> `npm run dev`
+
+## Port
+
+Default: `5173` (inherited from Vite). SvelteKit respects `--port <port>` flag and Vite's `server.port` config in `vite.config.ts`. Overrides follow the cascade in `references/dev-server-detection.md`.
+
+## Stub generation
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "SvelteKit dev",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["run", "dev"],
+      "port": 5173
+    }
+  ]
+}
+```
+
+Substitute the resolved package manager (`npm` / `pnpm` / `yarn` / `bun`) and port.
+
+## Common gotchas
+
+- **Vite under the hood:** SvelteKit uses Vite internally -- same port default (5173), same HMR behavior. The `sveltekit` type exists because `svelte.config.js` is a more precise signal than a generic `vite.config.ts`, allowing polish to generate a SvelteKit-specific stub name and label.
+- **Adapter does not matter for dev:** `adapter-auto`, `adapter-node`, `adapter-static`, and other adapters all produce the same dev server. The adapter only affects the production build output.
+- **`svelte.config.js` is the primary signature:** `svelte.config.js` always exists in SvelteKit projects, even when `vite.config.ts` also exists. This is the file that distinguishes a SvelteKit project from a plain Vite project.

package/skills/ce-polish/references/dev-server-vite.md

@@ -0,0 +1,48 @@
+# Vite dev-server recipe (auto-detect fallback)
+
+Loaded when `detect-project-type.sh` returns `vite` and the startup tuple still lacks a command.
+
+## Signature
+
+- `vite.config.js`, `vite.config.ts`, `vite.config.mjs`, or `vite.config.cjs` exists
+
+## Start command
+
+Standard:
+
+```bash
+npm run dev
+```
+
+The `dev` script in `package.json` typically wraps `vite` directly. Prefer the package manager indicated by the lockfile (see the Next.js recipe for the lockfile → command mapping).
+
+## Port
+
+Default: `5173`. Vite respects `--port <n>` and the `VITE_PORT` env var. The cascade in `references/dev-server-detection.md` picks up `--port` from `package.json` scripts and `PORT` from `.env*`.
+
+Vite's `--strictPort` flag causes the dev server to fail rather than increment to the next available port when the requested port is in use. Without it, an occupied port may move the server away from the URL polish probes; treat that reachability failure as a start-configuration decision for the user.
+
+## Host binding
+
+Vite binds to `127.0.0.1` by default. For polish running inside a devcontainer or WSL, users may need `--host 0.0.0.0` in `runtimeArgs`.
+
+## Stub generation
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Vite dev",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["run", "dev"],
+      "port": 5173
+    }
+  ]
+}
+```
+
+## Common gotchas
+
+- **HMR websocket port:** Vite's HMR uses a separate websocket that inherits the dev-server port by default. If the project pins `server.hmr.port` in `vite.config.ts`, the polish reachability probe against the dev-server port still works, but the embedded browser may need additional configuration to reach HMR.
+- **Framework on top of Vite:** SvelteKit, SolidStart, Qwik City, and Astro all use Vite but add their own dev scripts. The `vite` signature catches them, and `npm run dev` is the right command for all of them. Different default ports apply (SvelteKit: 5173, Astro: 4321, Qwik: 5173) — rely on the cascade to pick up the actual port from `package.json` or `.env`.

package/skills/ce-polish/references/install-riffrec.md

@@ -0,0 +1,35 @@
+# Install riffrec live mode into the host app
+
+Load this from `references/live-start.md` when the detect script shows the app is missing the riffrec dependency, has no installed live-capable build, or has no live-capable provider mount. The result is one setup commit on the current feature branch that leaves the app able to run a live session; the riffer already accepted this when they chose live mode, so do not ask again.
+
+## Where riffrec comes from
+
+`RIFFREC_MIN_VERSION` = `2.2.1`
+
+Live mode with the seeing interviewer (clicks announced, `look_at_screen`, no zip once the endpoint confirmed Done) ships in the npm package `riffrec` from `RIFFREC_MIN_VERSION` on, so the registry range `riffrec@^2.2.1` is the install path (step 1). Name the installed version in the setup commit message and in the report.
+
+## What to change
+
+Three edits, together, in the project root the detect script inspected:
+
+1. **Dependency.** Use the package manager the detect output named (`package_manager`; when null the project has no `package.json` and live mode cannot host riffrec — report that and offer traditional). Let the manager update its lockfile; do not edit the lockfile by hand.
+   - **Registry install:** one command, the manager's own add verb followed by the registry range: `<add verb> riffrec@^2.2.1`, where the add verb is `npm install`, `pnpm add`, `yarn add`, or `bun add` for the manager the detect output named. Quote the spec in shells that expand `^`. An existing `riffrec` entry that allows anything older than `RIFFREC_MIN_VERSION` (an older range, or a git spec such as `kieranklaassen/riffrec#<sha>` or `#main`) is replaced by the range.
+   - **Check the build.** Re-run the detect script: `installed` and `live_build` must both be true. `live_build` requires the installed `dist/index.d.ts` to name both `RiffrecLiveConfig` (the live provider) and `LOOK_AT_SCREEN_TOOL` (the page-side handler for the screen tool the endpoint advertises to the interviewer); an older live-capable build has the first without the second and would leave the interviewer's screen requests unanswered, so it fails this check and is replaced by the range like any other stale entry. If `live_build` is false the install did not resolve to `RIFFREC_MIN_VERSION` or later (a lockfile still holding an older resolution, a manager cache); fix the resolution and reinstall rather than building inside `node_modules`. Still false after that: stop, report the command output, and offer traditional. The detect script's `version` is informational (it reads the installed `package.json`, not a registry); the probe in `references/live-start.md` (the consent screen appears) is what proves live mode is present.
+2. **Mount.** Wrap the root of the React tree once in the provider, imported from `riffrec`:
+
+   ```tsx
+   <RiffrecProvider forceEnable live={{}}>
+   ```
+
+   `live` enables live mode. Its `autoStart` default is fragment-gated in riffrec from `RIFFREC_MIN_VERSION` on: the consent step opens by itself only when the page carries live credentials (the `#riffrec_live=…` fragment on the handoff URL, or stored credentials after a reload), and an ordinary visit stays quiet, so leave `autoStart` unset. The root is wherever the framework renders the whole app: the Vite entry that calls `createRoot`, the Remix `root.tsx` layout, the component Inertia's `createInertiaApp` renders, or, on the Next app router, a client component the root layout renders (the provider uses browser APIs, so it cannot sit directly in a server component). When a `RiffrecProvider` mount already exists, add the `live` prop to it and keep its other props. That prop is the whole configuration: the endpoint origin and the session token reach the page through the URL fragment at session start, so nothing about the endpoint is written into source, environment files, or config, and the mount is safe to commit.
+3. **Verify.** Re-run the detect script from `references/live-start.md`. It must now report `dependency`, `installed`, and `live_build` true, and `mount` true (`live=` on the tag; the detect script looks for a real JSX opening element, not the prop's value). If the mount edit does not show, the file you edited is not the rendered root; find the one that is.
+
+Follow riffrec's own README when it names a different mount point for the framework in front of you; the README is the source of truth for the package, this file only for what polish needs from it.
+
+## Commit
+
+Commit the dependency change, the lockfile, and the mount edit as one setup commit on the current branch through `ce-commit`, with a message that says it adds riffrec live mode for polish sessions. Keep its hash: the live-mode report names it, including when the riffer later declines the consent screen and no session runs (the commit stays; riffrec remains in the app after the session, as disclosed).
+
+## When it fails
+
+An install or mount edit that cannot complete leaves no setup commit. Undo only the edits this step made, report what failed with the command output, and offer traditional polish. Do not retry with a different package manager or a different riffrec source than the `riffrec@^2.2.1` registry range.