fix(ce-polish): install riffrec@^2.2.1 from npm instead of the git pin (EveryInc#1778)

Author: kieranklaassen

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

@@ -4,26 +4,24 @@ Load this from `references/live-start.md` when the detect script shows the app i
 
 ## Where riffrec comes from
 
-`RIFFREC_MIN_COMMIT` = `1393c17082e3b6a5b04d219fc6ae9083018c96a2`
-`RIFFREC_MIN_VERSION` = unset (no npm release carries live mode yet)
+`RIFFREC_MIN_VERSION` = `2.2.1`
 
-Live mode with the seeing interviewer (clicks announced, `look_at_screen`, no zip once the endpoint confirmed Done) is complete on riffrec's GitHub `main` from `RIFFREC_MIN_COMMIT` on, and the tree ships its built `dist/`, so a git install pinned to that commit is the install path (step 1). The registry is the future switch: when riffrec publishes a release that carries live mode, that release becomes `RIFFREC_MIN_VERSION` and a new setup commit replaces the git pin with the registry range `^RIFFREC_MIN_VERSION`. Until then nothing here reads the registry, and `RIFFREC_MIN_VERSION` being unset neither blocks nor gates the install. Name the pinned commit in the setup commit message and in the report.
+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.
-   - **Git install, pinned (the path today):** one command, the manager's own add verb followed by the git spec with the full SHA: `<add verb> kieranklaassen/riffrec#1393c17082e3b6a5b04d219fc6ae9083018c96a2`, where the add verb is `npm install`, `pnpm add`, `yarn add`, or `bun add` for the manager the detect output named. Write the SHA out in full; a shortened ref is a different, nonexistent revision to the manager. An existing `riffrec` entry that points anywhere else (a registry range, an older commit, `#main`) is replaced by the pin. The repository declares only a `prepack` build, which git installs never run, and ships its built `dist/` in the tree, so what you get is exactly the committed `dist/`.
-   - **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 pin like any other stale entry. If `live_build` is false the install did not resolve to the pin (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.
-   - **Future switch (not this session):** when riffrec publishes a release that carries live mode, `RIFFREC_MIN_VERSION` names it and a new setup commit swaps the git pin for `riffrec@^<min>` with the same add verb.
+   - **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_COMMIT` 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.
+   `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.
@@ -34,4 +32,4 @@ Commit the dependency change, the lockfile, and the mount edit as one setup comm
 
 ## 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 pinned commit.
+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.

tests/skills/ce-polish-live-prose.test.ts

@@ -15,8 +15,10 @@ const referencesDir = path.join(skillDir, "references")
 const scriptsDir = path.join(skillDir, "scripts")
 const SKILL_MD_BYTE_CEILING = 8000
 
-// riffrec main commit the fixtures, contract mirror, and install pin all refer to (tests/fixtures/ce-polish-live/SOURCE.md).
+// riffrec main commit the fixtures and contract mirror refer to (tests/fixtures/ce-polish-live/SOURCE.md).
 const RIFFREC_REFERENCE_SHA = "1393c17082e3b6a5b04d219fc6ae9083018c96a2"
+// First npm release of riffrec that carries live mode; install-riffrec.md installs `riffrec@^` this.
+const RIFFREC_MIN_VERSION = "2.2.1"
 
 const LIVE_FILES = ["live-start.md", "live-loop.md", "live-remote.md", "install-riffrec.md", "live-stream-contract.md"]
 
@@ -129,17 +131,19 @@ describe("ce-polish live-mode prose", () => {
     expect(loop).toContain("ce-commit")
   })
 
-  test("install-riffrec.md mounts live={{}} with forceEnable, pins the GitHub install to the reference commit, and keeps the registry range as the future switch (I5, KTD20)", async () => {
+  test("install-riffrec.md mounts live={{}} with forceEnable and installs the npm release that carries live mode (I5, KTD20)", async () => {
     const install = await read("references/install-riffrec.md")
     expect(install).toContain("<RiffrecProvider forceEnable live={{}}>")
-    expect(install).toContain("RIFFREC_MIN_VERSION")
-    expect(install).toContain("RIFFREC_MIN_COMMIT")
-    expect(install).toContain(RIFFREC_REFERENCE_SHA)
-    expect(install).toMatch(/kieranklaassen\/riffrec#/)
+    expect(install).toContain(`\`RIFFREC_MIN_VERSION\` = \`${RIFFREC_MIN_VERSION}\``)
+    expect(install).toContain(`<add verb> riffrec@^${RIFFREC_MIN_VERSION}`)
+    // The git pin is gone; a leftover git spec in the host app is replaced, not installed.
+    expect(install).not.toContain("RIFFREC_MIN_COMMIT")
+    expect(install).not.toContain(RIFFREC_REFERENCE_SHA)
+    expect(install).not.toMatch(/<add verb> kieranklaassen\/riffrec#/)
+    // The detect step still proves the installed build, not the declared range.
     expect(install).toMatch(/dist\/index\.d\.ts/)
-    // The registry range is the documented future switch, not a gate on today's git install.
-    expect(install).toMatch(/riffrec@\^<min>/)
-    expect(install).toMatch(/future switch/i)
+    expect(install).toContain("RiffrecLiveConfig")
+    expect(install).toContain("LOOK_AT_SCREEN_TOOL")
     expect(install).toMatch(/`installed` and `live_build` must both be true/)
     expect(install).toMatch(/setup commit/i)
     // The endpoint origin is never written into source or config (KTD20).