@satanwagen/reviewkit 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -0,0 +1,158 @@
+# Changelog
+
+## 0.1.4 — 2026-09-02
+
+### Added
+
+- **`reviewkit` terminal CLI** (in `@satanwagen/reviewkit-cli`, zero deps,
+  Node 21+): `cd repo && reviewkit` opens an interactive live view of every
+  review item across the site's pages: presence (who is online, in their
+  colours), arrow-key navigation, Enter for actions (detail, apply with
+  Claude Code, copy prompt, set status, delete), `a` to hand all open items
+  to Claude Code, filters, live toasts for new / changed / deleted items.
+  Piped output falls back to a plain table plus event stream. `list`, `show`,
+  `status`, `delete`, `watch`, `export`, `prompt`, `rooms`, `projects`, `key`.
+  Project resolution: `-p name` → `.reviewkit/project.json` (walks up from
+  cwd) → `.reviewkit/emblema-sync.json` → global active project.
+- **One-click pairing.** `reviewkit setup` detects the site's sync settings in
+  the repo, listens on loopback (127.0.0.1:48780–48783) and the review panel's
+  new **Connect terminal / agent…** dialog finds it and pushes the connection.
+  Nothing to copy. A copyable `rkc_…` key remains for remote machines
+  (`reviewkit connect <key>`). CSP: the panel needs `connect-src
+  http://127.0.0.1:*` for this (already required by the Emblema bridge).
+- **MCP bridge for coding agents.** `reviewkit mcp` is a stdio MCP server
+  with `reviewkit_prompt`, `reviewkit_list`, `reviewkit_show`,
+  `reviewkit_set_status`, `reviewkit_delete`, `reviewkit_export`,
+  `reviewkit_rooms`, `reviewkit_projects`. `setup` / `mcp-install` register it
+  in Claude Code (`claude mcp add`) and Cursor (`~/.cursor/mcp.json`).
+  Statuses set by the agent appear live in reviewers' browsers.
+- **Sync server: `rooms` request** (protocol v1, additive). Returns the routes
+  of the connection's origin that have review data, live or on disk, with item
+  counts and online peers. Needed by the CLI. Deployed on the satanwagen
+  server, reachable again at `wss://2-59-219-26.sslip.io/rk-sync` (sslip.io
+  hostname, no domain to expire) — and the client's default `syncUrl` again.
+- Panel gear menu: **Connect terminal / agent…** (enabled when live sync is on).
+
+### Changed
+
+- **One word does everything: `<ReviewKit token="…" />`.** Live collaboration
+  is on by default: `syncUrl` defaults to the public ReviewKit server
+  `wss://2-59-219-26.sslip.io/rk-sync` (sslip.io hostname → VPS IP, nothing to
+  expire) and `syncToken` defaults to `token`. The server is now
+  **self-serve**: any token of at least 8 characters gets its own private set
+  of rooms (keyed by origin + route + hash(token)), so no account and no
+  server-side step exist. New prop `sync={false}` forces solo mode;
+  `syncToken` stays as an override when the room secret should differ from
+  the review link. Existing installs that set `token` but no `syncToken`
+  start syncing on upgrade — pass `sync={false}` to keep the old solo mode.
+  Same in the CLI: `init --sync-url` is optional, state files still carrying
+  the retired host fall back to the default with a warning, and `reviewkit
+  setup` picks up the review token from the repo as the room secret.
+- `@satanwagen/reviewkit-cli` now ships two tools. `npx -y
+  @satanwagen/reviewkit-cli …` runs `reviewkit`; the Emblema agent is
+  `npx -p @satanwagen/reviewkit-cli reviewkit-emblema …` (docs and in-app
+  hints updated).
+
+## 0.1.3 — 2026-09-02
+
+Defaults tightened so a production build behaves the way its code reads.
+Several changes are breaking for hosts that relied on the old conveniences;
+each has a one-line migration below.
+
+### Breaking
+
+- **No activation without a token.** Previously an unset `token` meant "any
+  `?review=x` turns the layer on" (plus the `reviewkit` localStorage flag).
+  Now, without `token`, nothing activates. Migration: pass `token`. For a
+  reviewer-less dev loop pass `devAutoOn`.
+- **No `NODE_ENV === 'development'` auto-on.** The library never reads the
+  host's NODE_ENV any more. Migration:
+  `devAutoOn={import.meta.env.DEV}` (Vite) or
+  `devAutoOn={process.env.NODE_ENV === 'development'}` (Next/webpack).
+- **No default `syncUrl`.** The former default
+  `wss://agropolio.fucking.style/rk-sync` pointed at an expired domain. Sync
+  now runs only when **both** `syncUrl` and `syncToken` are set; otherwise
+  the layer is local-only, no socket. Migration: set `syncUrl` explicitly.
+  Same for the CLI: `reviewkit-emblema init --sync-url …` (the room bridge
+  stays disabled until both `--sync-url` and `--sync-token` are configured).
+- **CLI moved to `@satanwagen/reviewkit-cli`.** The main package no longer
+  ships a `bin`, so a host `npm install` does not pull the Emblema agent.
+  Migration: `npx -p @satanwagen/reviewkit-cli reviewkit-emblema init …` / `serve` (the command
+  inside is still `reviewkit-emblema`).
+- **`emblema.repoPath` is optional.** The repo path is Emblema's local
+  knowledge (advertised in its `/intake/ping` answer, and present in
+  `.reviewkit/emblema-sync.json` for the agent) and no longer belongs in host
+  code. `emblema={{}}` now enables the bridge. The v1 dispatch payload keeps
+  `v: 1`, but `repoPath` became optional: an intake with a strict "required"
+  validator must relax it and fall back to its active project.
+- **Effect sounds moved off the expired domain.** `/ondro` now fetches
+  `rick.mp3` from `https://2-59-219-26.sslip.io/rk-assets` (the same VPS,
+  reached through a sslip.io hostname so no domain renewal can break it).
+  New prop `fxAssetsUrl` overrides the base for self-hosting. Add the origin
+  to CSP `media-src` if you send a policy.
+- Legacy activation keys (`review-kit:active`, `reviewkit`) are still cleaned
+  up on load but never consulted.
+- **Emblema intake must accept a batch without `repoPath`.** An Emblema build
+  that still validates it as required answers HTTP 400; the panel now shows
+  that as `emblema rejected` (new push status) instead of `emblema offline`.
+- **CLI:** a `.reviewkit/emblema-sync.json` written by 0.1.2 still carries the
+  retired default sync host. `serve` now detects it, logs a re-init hint and
+  runs with the bridge disabled instead of reconnecting forever; the local
+  `/status` endpoint reports `realtime.state: 'off'` whenever either sync
+  setting is missing (previously it said `connecting` with no URL).
+
+### Added
+
+- `enabled?: boolean` master switch (default `true`) so a wrapper can write
+  `<ReviewKit enabled={Boolean(TOKEN)} token={TOKEN} />` instead of
+  `if (!TOKEN) return null`.
+- `devAutoOn?: boolean` — host-controlled "always on for this load". Still
+  subject to `enabled`, `allowedHosts` and `?review=off`.
+- **`@satanwagen/reviewkit/next`** — `'use client'` component: render it from
+  a server `layout.tsx`; it evaluates URL + sticky session after mount and
+  only then dynamically imports the core. `examples/next-demo` shows it
+  together with the CSP headers.
+- **`@satanwagen/reviewkit/lazy`** — the same code-split component for Vite
+  and friends; no more hand-rolled `React.lazy` + `Suspense` gate.
+- **`@satanwagen/reviewkit/activate`** — `shouldActivate({ token, enabled,
+  allowedHosts, devAutoOn })`, React-free, ~200 B. The supported way for a
+  host to gate its own lazy import; the sessionStorage format stays private.
+- One-time console warning when a URL token activates the layer on a
+  non-loopback hostname with no `allowedHosts` (see README "Production
+  recipe").
+- The `/` command effects (~40 KB of source) load as a separate chunk on
+  first use instead of shipping in the core chunk.
+- `probeEmblema()` returns `{ port, repoPath? }`; `pingEmblema()` stays as a
+  port-only wrapper.
+- Activation matrix tests (`test/activate.test.mjs`) run against `dist/`
+  (`npm test` builds first via `pretest`).
+- A one-time console warning when `?review=<x>` does not match the configured
+  token (kept from 0.1.2, now also emitted by `shouldActivate`).
+- `/lazy` and `/next` are effectively ESM entries: the CJS builds exist for
+  `require()` consumers but inline the core (esbuild has no CJS code
+  splitting). Every modern bundler picks the ESM build.
+- README: activation-state table, CSP requirements, production recipe.
+
+### Bundle audit (unminified ESM, `dist/`)
+
+| Chunk | 0.1.2 | 0.1.3 |
+| --- | ---: | ---: |
+| core client chunk | 313 KB | 267 KB |
+| effects (lazy, on first `/command`) | in core | 41 KB |
+| `activate` entry | — | 0.2 KB |
+
+Largest remaining inputs: `styles.ts` (53 KB), `Panel.tsx` (46 KB). Schema
+validation and IndexedDB persistence are under 10 KB each and were not the
+weight.
+
+## 0.1.2
+
+- Delete endpoint for Emblema findings, idempotent for unknown ids.
+
+## 0.1.1
+
+- `reopen` status verb; realtime health in local state.
+
+## 0.1.0
+
+- First scoped release as `@satanwagen/reviewkit`.

package/README.md

@@ -13,35 +13,104 @@ npm install @satanwagen/reviewkit
 ## Two-line integration
 
 ```tsx
-import { ReviewKit } from '@satanwagen/reviewkit/client';
+import { ReviewKit } from '@satanwagen/reviewkit/lazy';   // Vite, CRA, Remix …
+// import { ReviewKit } from '@satanwagen/reviewkit/next'; // Next.js App Router ('use client' built in)
 
 // anywhere in your tree, rendered once:
-<ReviewKit />
+<ReviewKit token="pick-any-word" />
 ```
 
-That's it. The component renders `null` unless review mode is active, and all UI lives in a shadow root appended to `document.body` — your CSS never leaks in, reviewkit's CSS never leaks out. Safe to ship in production builds.
+That's it — one word. Reviewers open `https://your-site/?review=pick-any-word`; the same word is also the secret of your private rooms on the public ReviewKit sync server, so presence, live cursors, shared items, the terminal CLI and the Claude Code bridge all work with no server-side step. The component renders `null` unless review mode is active, and all UI lives in a shadow root appended to `document.body` — your CSS never leaks in, reviewkit's CSS never leaks out. Safe to ship in production builds. Want it offline? `sync={false}`.
+
+Three entries, same props:
+
+| Entry | What it is | Use when |
+| --- | --- | --- |
+| `@satanwagen/reviewkit/lazy` | Component that decides after mount (URL + sticky session) and only then `import()`s the core chunk. | Vite / CRA / Remix / any client bundler. Visitors without a review link never download the core. |
+| `@satanwagen/reviewkit/next` | Same, with `'use client'` baked into the built file so a server `layout.tsx` can render it directly. | Next.js App Router. See `examples/next-demo`. |
+| `@satanwagen/reviewkit/client` | The core itself, eager. | You already have your own lazy boundary, or you want everything in one chunk. |
+
+The code split only exists in the ESM builds (what Vite, Next, webpack 5 pick); the CJS files of `/lazy` and `/next` inline the core for `require()` consumers.
+
+And a React-free helper for hosts that gate their own lazy import:
+
+```ts
+import { shouldActivate } from '@satanwagen/reviewkit/activate'; // ~200 B, no React, SSR-safe (false)
+if (shouldActivate({ token: TOKEN })) void import('./reviewHost');
+```
+
+`shouldActivate` is the supported API for "should this page load show review?"; the sessionStorage format behind the sticky session is private and may change. Its only side effect: `?review=off` clears the sticky opt-in.
 
 ### Props
 
 | Prop | Type | Description |
 | --- | --- | --- |
-| `token` | `string` | Restricts URL activation to `?review=<token>`. Without it, any `?review=x` activates (with a console warning). |
-| `syncToken` | `string` | Enables live collaboration via the realtime sync server (`realtime/`): presence avatars, live cursors, remote selections and instantly shared items. Unset = solo mode, no network. The value is public in the browser bundle by nature — treat it as a gate against casual visitors, not a secret. Keep it in the lazy review chunk of the host app, never in the main bundle. |
+| `token` | `string` | **Required for any activation.** The layer turns on only via `?review=<token>` (or the per-tab session such a link starts). Without it nothing activates, whatever the URL says. |
+| `enabled` | `boolean` | Master switch, default `true`. `false` renders nothing, installs nothing. Lets you write `enabled={Boolean(TOKEN)}` instead of `if (!TOKEN) return null`. |
+| `devAutoOn` | `boolean` | Force the layer on for this page load, no link needed. Host-controlled dev convenience (`devAutoOn={import.meta.env.DEV}`); the library never reads `NODE_ENV`. Still subject to `enabled`, `allowedHosts` and `?review=off`. |
+| `allowedHosts` | `string[]` | Hostname allowlist with `*` wildcards (`['localhost', '*.staging.example']`). Outside it nothing activates, token or not. Unset = any host (with a one-time console warning on URL activation on a public host). |
+| `syncUrl` | `string` | WebSocket endpoint of the sync server. Default: the public ReviewKit server `wss://2-59-219-26.sslip.io/rk-sync`, so live collaboration needs no server of your own. Override for a self-hosted `realtime/server`. |
+| `sync` | `boolean` | Live collaboration switch, default `true`. `false` = solo mode, no network. |
+| `syncToken` | `string` | Secret of your rooms on the sync server, **defaults to `token`**. Any string of 8+ characters gets its own private rooms on the public server. Override only if the room secret should differ from the review link. Public in the bundle by nature. |
+| `emblema` | `{ repoPath?: string; port?: number }` | Enables the Emblema bridge (`emblema={{}}` is enough). See "Pairing with Emblema". |
 | `defaultAuthor` | `string` | Pre-fills the reviewer name. |
+| `fxAssetsUrl` | `string` | Base URL for the `/` effect soundtracks (`<base>/rick.mp3` for `/ondro`). Default: the public ReviewKit assets host `https://2-59-219-26.sslip.io/rk-assets`. Override to self-host. Needs `media-src` in CSP. |
 | `position` | `'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'` | Initial corner of the floating badge (default `bottom-right`; draggable, persisted). |
 | `storageKey` | `string` | Persistence key (default: page origin). |
 | `onSessionChange` | `(session: ReviewSession) => void` | Called (debounced) whenever the session changes. |
 
 ## How the layer activates
 
-**With a `token` configured (the production setup) the rules are strict:**
+Rules, in order; the first that applies wins. No environment sniffing anywhere.
+
+| # | Condition | Result |
+| --- | --- | --- |
+| 1 | `enabled={false}` | off |
+| 2 | hostname not in `allowedHosts` (when given) | off |
+| 3 | `?review=off` in the URL | off, and the in-tab sticky session is cleared |
+| 4 | `devAutoOn` | **on** |
+| 5 | no `token` configured | off (`?review=x` logs a one-time warning and stays off) |
+| 6 | `?review=<token>` matches | **on**, starts the per-tab sticky session |
+| 7 | `?review=<something else>` | off |
+| 8 | valid sticky session (same token, < 4 h since last active load) | **on**, expiry renewed |
+| 9 | otherwise | off |
+
+Activation-state matrix for the common cases:
+
+| token | build | URL | sticky | result |
+| --- | --- | --- | --- | --- |
+| unset | dev or prod | none / `?review=x` | any | off |
+| unset | dev, with `devAutoOn` | any except `off` | any | on |
+| set | prod | `?review=<token>` | — | on (sticky starts) |
+| set | prod | none | valid | on |
+| set | prod | none | none / expired / other token | off |
+| set | prod | `?review=wrong` | valid | off |
+| set | any | `?review=off` | valid | off, sticky cleared |
+
+The sticky session is per tab (`sessionStorage`), bound to the token and renewed on every active load, so a reviewer who opened a review link keeps reviewing across full page loads on other routes. The gear menu's **Keep review on in this tab** toggles it explicitly; **End review** (or `?review=off`) clears everything and returns the clean site. Leftover keys from pre-0.1.3 versions (`review-kit:active`, `reviewkit`) are removed on load and never consulted.
+
+### Production recipe
+
+```tsx
+<ReviewKit
+  enabled={Boolean(TOKEN)}
+  token={TOKEN}
+  allowedHosts={['staging.your-site.tld', '*.preview.your-site.tld']}
+/>
+```
+
+`token` + `allowedHosts` together: the token says *who*, the allowlist says *where*. Without `allowedHosts` a URL activation on a non-loopback host logs one console warning. `TOKEN` is public in the bundle by design; use the `/lazy` or `/next` entry so it at least lives in the review chunk, not the main one.
+
+### CSP
+
+If the host sends a `Content-Security-Policy`, `connect-src` must allow:
 
-1. `?review=<token>` in the URL — the only automatic way in.
-2. The reviewer's explicit **“Keep on in this tab”** toggle in the panel — a per-tab, token-bound opt-in that expires after ~4 hours. Nothing persists silently.
+- the sync server origin: `https://2-59-219-26.sslip.io` for the default server (or your own `syncUrl` origin / `ws:` in dev),
+- `http://127.0.0.1:*` when the `emblema` prop is set (intake ports 48752–48755, pairing agent 48770–48773).
 
-Anything else shows nothing: no badge, no listeners, no WebSocket. **“End review”** in the panel (or `?review=off`) clears all persisted state and returns the clean site. Leftover activation keys from pre-strict versions (`review-kit:active`, `reviewkit`) are silently removed on the first token-less load.
+and `media-src` must allow `https://2-59-219-26.sslip.io` (or your `fxAssetsUrl`) for the `/` effect sounds; without it the effects run silent.
 
-**Without a token** (zero-config/dev) the conveniences remain: any `?review=x` value (console warning), the in-tab opt-in, a `reviewkit` localStorage flag, or a dev build (`NODE_ENV === 'development'`).
+With `connect-src 'self'` alone the WebSocket is blocked and the layer silently stays local-only. `examples/next-demo/next.config.ts` has a complete header.
 
 ## Using it (reviewer flow)
 
@@ -121,70 +190,64 @@ Programmatic helpers are exported too: `parseSessionJson` / `parseSession` (vali
 // src/main.tsx
 import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
-import { ReviewKit } from '@satanwagen/reviewkit/client';
+import { ReviewKit } from '@satanwagen/reviewkit/lazy';
 import { App } from './App';
 
 createRoot(document.getElementById('root')!).render(
   <StrictMode>
     <App />
-    <ReviewKit token={import.meta.env.VITE_REVIEW_TOKEN} />
+    <ReviewKit token={import.meta.env.VITE_REVIEW_TOKEN} devAutoOn={import.meta.env.DEV} />
   </StrictMode>,
 );
 ```
 
-No Vite config changes are needed — `reviewkit` ships prebuilt ESM/CJS with types. In dev the layer is always on; in production reviewers open `https://your-site.tld/?review=<token>`.
+No Vite config changes are needed — `reviewkit` ships prebuilt ESM/CJS with types. In `vite dev` the layer is on thanks to `devAutoOn`; in production reviewers open `https://your-site.tld/?review=<token>`, and visitors without the link never download the review chunk (the `/lazy` entry splits it automatically).
 
-Until the npm release lands you can also depend on it via a file path — this is exactly what the demo does:
+Until the npm release lands you can also depend on it via a file path — this is exactly what the demos do:
 
 ```jsonc
 // package.json
 "dependencies": { "@satanwagen/reviewkit": "file:../path/to/ReviewKit" }
 ```
 
-npm symlinks the folder, so after editing reviewkit run `npm run build` in it and restart/reload Vite. Note that the deployed site only picks up library changes after a rebuild + deploy of the host app (Fable has `npm run deploy` for the whole chain) — the live sync server only carries review data, never code. Run `npm run build` in `ReviewKit/` at least once before installing, since the package resolves to `dist/`.
+npm symlinks the folder, so after editing reviewkit run `npm run build` in it and restart/reload Vite. With React 18 add `resolve: { dedupe: ['react', 'react-dom'] }` to `vite.config.ts` so the linked package's own `node_modules` cannot introduce a second React. Run `npm run build` in `ReviewKit/` at least once before installing, since the package resolves to `dist/`.
 
-### Real-world example: token-only activation + lazy loading (Agropolio landing page)
+### Gating a hand-rolled lazy boundary
 
-The Agropolio landing page (`../Agropolio/Fable` relative to this repo) integrates reviewkit so that **only** `?review=agropolio` ever activates it — dev-build auto-activation is bypassed, and without the token the library code isn't even downloaded (separate lazy chunk):
+If you keep your own wrapper (for example to keep `syncToken` in a chunk you control), gate it with `shouldActivate` instead of reading ReviewKit's storage keys:
 
-```jsonc
-// Fable/package.json
-"dependencies": { "@satanwagen/reviewkit": "file:../../ReviewKit" }
-```
+```tsx
+// ReviewLayer.tsx
+import { lazy, Suspense, useEffect, useState } from 'react';
+import { shouldActivate } from '@satanwagen/reviewkit/activate';
 
-```ts
-// Fable/vite.config.ts — the linked package has its own node_modules,
-// dedupe guarantees a single React instance (Fable is on React 18):
-resolve: { dedupe: ['react', 'react-dom'] }
-```
+const TOKEN = import.meta.env.VITE_REVIEW_TOKEN;
+const ReviewHost = lazy(() => import('./reviewHost')); // renders <ReviewKit token={TOKEN} syncUrl=… syncToken=… />
 
-```tsx
-// Fable/src/ReviewLayer.tsx (rendered next to <App /> in main.tsx)
-import { lazy, Suspense, useEffect, useState } from 'react'
-
-const TOKEN = 'agropolio'
-const SESSION_KEY = 'review-kit:active' // same key reviewkit uses internally
-
-function shouldLoad(): boolean {
-  try {
-    const param = new URLSearchParams(window.location.search).get('review')
-    if (param === 'off') { window.sessionStorage.removeItem(SESSION_KEY); return false }
-    if (param === TOKEN) return true
-    return window.sessionStorage.getItem(SESSION_KEY) === '1' // survive reloads in-tab
-  } catch { return false }
+export function ReviewLayer() {
+  const [load, setLoad] = useState(false);
+  useEffect(() => { if (shouldActivate({ token: TOKEN })) setLoad(true); }, []);
+  return load ? <Suspense fallback={null}><ReviewHost /></Suspense> : null;
 }
+```
 
-const ReviewKit = lazy(() => import('@satanwagen/reviewkit/client').then((m) => ({ default: m.ReviewKit })))
+## Integrating into a Next.js site (App Router)
 
-export function ReviewLayer() {
-  const [load, setLoad] = useState(false)
-  useEffect(() => { if (shouldLoad()) setLoad(true) }, [])
-  if (!load) return null
-  return <Suspense fallback={null}><ReviewKit token={TOKEN} /></Suspense>
+```tsx
+// app/layout.tsx (a server component — that's fine)
+import { ReviewKit } from '@satanwagen/reviewkit/next';
+
+export default function RootLayout({ children }) {
+  return (
+    <html><body>
+      {children}
+      <ReviewKit token={process.env.NEXT_PUBLIC_REVIEW_TOKEN} devAutoOn={process.env.NODE_ENV === 'development'} />
+    </body></html>
+  );
 }
 ```
 
-The gate outside `<ReviewKit />` is what keeps the layer invisible to normal visitors: no token → the wrapper renders `null`, no shadow root, no listeners, no network request for the reviewkit chunk.
+The `/next` entry is a client component; it renders nothing on the server and evaluates the URL/sticky session after mount before importing the core. Add the CSP `connect-src` entries above if you send a policy. Full example: `examples/next-demo`.
 
 ## Adding ReviewKit to another site (with live collaboration)
 
@@ -203,19 +266,19 @@ Step by step, for any site on any hosting (nginx, IIS, Vercel, …).
 
 Run `npm run build` inside ReviewKit at least once for the `file:`/git variants (the package resolves to `dist/`). With React 18 add `resolve.dedupe: ['react','react-dom']` to your bundler config when using a `file:` link.
 
-**2. Integrate — two lines, done. Live collaboration included:**
+**2. Integrate — one line, done:**
 
 ```tsx
-import { ReviewKit } from '@satanwagen/reviewkit/client';
+import { ReviewKit } from '@satanwagen/reviewkit/lazy';
 
-<ReviewKit token="my-site-token" syncToken="<the sync server's shared secret>" />
+<ReviewKit token="my-site-token" />
 ```
 
-That's the whole setup. `syncUrl` **defaults to the always-on ReviewKit sync server** (`wss://agropolio.fucking.style/rk-sync`), so presence, live cursors and instantly-shared items work on any site with no server-side step at all — no allowlist entry, no restart, nothing. Rooms are keyed by the page's origin + path, so different sites never see each other's feedback or presence. If the server is unreachable the tool silently runs local-only (no console errors); omit `syncToken` to disable networking entirely.
+Live collaboration (presence, live cursors, instantly shared items) is on by default: `syncUrl` points at the public ReviewKit server `wss://2-59-219-26.sslip.io/rk-sync` and the room secret is your `token` (8+ characters; `syncToken` overrides it). The server is self-serve: every token gets its own private rooms, no account, no registration. Rooms are keyed by the page's origin + path, so different sites never see each other's feedback or presence. If the server is unreachable the tool silently runs local-only (no console errors); omit either prop to disable networking entirely.
 
-**What the open server implies (honesty section):** the token and `syncToken` are readable in the browser bundle, so anyone holding a review URL can join and create rooms. The server is meant for the operator's own sites, not as a public service; it is guarded by the shared token, per-connection rate limits (40 msg/s, burst 80), 1 MiB frame cap, 16 clients and 2000 items per room, and a live-room ceiling (`RK_SYNC_MAX_ROOMS`, default 500).
+**What a shared server implies (honesty section):** the token is readable in the browser bundle and in every review link, so anyone holding the link can join your rooms — that is the point of a review link. Rooms of different tokens never mix. The public server is guarded by per-connection rate limits (40 msg/s, burst 80), 1 MiB frame cap, 16 clients and 2000 items per room, and a live-room ceiling (`RK_SYNC_MAX_ROOMS`, default 500).
 
-**3. Advanced: run your own sync server** (optional) — `realtime/server/`: `npm run build`, run `dist/server.js` with `RK_SYNC_TOKEN` (+ optional `RK_SYNC_PORT`, `RK_SYNC_DATA`, `RK_SYNC_MAX_ROOMS`, and `RK_SYNC_ORIGINS` if you *want* an origin allowlist — empty/unset means any origin, which is the default deployment) as a service, point `syncUrl` at it, then put a WebSocket-aware reverse proxy in front:
+**3. Run the sync server** — `realtime/server/`: `npm run build`, run `dist/server.js` with `RK_SYNC_TOKEN` (+ optional `RK_SYNC_PORT`, `RK_SYNC_DATA`, `RK_SYNC_MAX_ROOMS`, and `RK_SYNC_ORIGINS` if you *want* an origin allowlist — empty/unset means any origin, which is the default deployment) as a service, point `syncUrl` at it, then put a WebSocket-aware reverse proxy in front:
 
   *nginx* (as deployed on satan):
 
@@ -233,23 +296,49 @@ That's the whole setup. `syncUrl` **defaults to the always-on ReviewKit sync ser
 
   With an `RK_SYNC_ORIGINS` allowlist active, rejected origins are logged (`[origin] rejected …`) and closed with code 4005; the client quietly stays local.
 
-**4. Token caveat:** don't reuse secrets that protect anything else, and keep tokens out of the main bundle (load ReviewKit in a lazy chunk like the Agropolio integration does).
+**4. Token caveat:** don't reuse secrets that protect anything else, and keep tokens out of the main bundle (use the `/lazy` or `/next` entry). Add `allowedHosts` in production (see "Production recipe").
 
 **5. Verify it works:** open `https://your-site/?review=<token>` — the Review badge appears; the panel header shows **live** (green dot) when the sync server accepted you, or *local only* when not. In the Network tab you should see one WebSocket to `/rk-sync` with a `welcome` frame. Open the same URL in a second browser: avatars, live cursors and instantly-appearing items confirm collaboration.
 
+## Terminal & coding agents (`reviewkit` CLI)
+
+Review comments do not have to stay in the browser. The `reviewkit` CLI reads the same live rooms, and doubles as the MCP bridge for Claude Code, Cursor and any other MCP client, so an agent can read every comment and mark items applied while reviewers watch the status flip live.
+
+```sh
+npm install -g @satanwagen/reviewkit-cli
+cd my-site
+reviewkit          # first run pairs the repo (one click in the review panel), then the live view
+```
+
+**Pairing is one click, no copy-paste.** Bare `reviewkit` in an unpaired repo runs `setup` first; it detects the site's `token` (and a custom `syncToken` / `syncUrl`, if any) in the repo, opens a loopback port and waits. In the browser open the review panel → gear → **Connect terminal / agent…** → **Connect**: the panel finds the waiting terminal and pushes the connection into `<repo>/.reviewkit/project.json` (gitignored). `setup` also registers the MCP server in Claude Code and Cursor when it finds them. The dialog keeps a copyable key as the fallback for a terminal on another machine.
+
+The live view is interactive: arrow keys walk the items, Enter opens actions (detail, apply this item with Claude Code, copy as prompt, mark applied / accepted / rejected / reopen, delete), `a` hands every open item to Claude Code in the repo, and the header shows who is reviewing right now in their own colours. Everything is the shared room state, so a status flipped in the terminal or by an agent changes in reviewers' browsers instantly, and vice versa.
+
+Everyday commands: `reviewkit list --status open`, `reviewkit show <id>`, `reviewkit status <id> applied`, `reviewkit watch`, `reviewkit export -o review.json`, `reviewkit prompt` (agent-ready work list), `reviewkit rooms`, `reviewkit projects` / `-p <name>` to act on another paired site. Full table in [`cli/README.md`](./cli/README.md).
+
+**Agents.** With the bridge registered, "apply the reviewkit feedback" is enough: the agent calls `reviewkit_prompt`, edits code, then `reviewkit_set_status(id, "applied")` per item. Manual registration:
+
+```sh
+claude mcp add --scope user reviewkit -- npx -y @satanwagen/reviewkit-cli mcp
+```
+
+Requirements: the site has live sync on (the default), Node 21+. The CLI reads shared rooms, never a reviewer's local browser storage. The sync server gained a `rooms` request (protocol v1, additive) so the CLI can find every page with review data; run the 0.1.4 server build.
+
 ## Pairing with Emblema
 
 ReviewKit pairs with the [Emblema](https://emblema.app) desktop app: once paired, the local sync agent streams review items to Emblema, and the paired Emblema shows them as findings in its ReviewKit tile (statuses flow back to the page).
 
-Sync is automatic and realtime — no manual step. With `emblema` set in the `ReviewKit` config, the browser itself pushes every added or edited open item to a locally running Emblema (debounced 500 ms, silent-fail: an unreachable Emblema never blocks the reviewer; the panel header shows a small `emblema` status dot). The session menu keeps **Resend all to Emblema** as a one-click fallback that re-dispatches every open item on the page.
+Sync is automatic and realtime — no manual step. With `emblema={{}}` in the `ReviewKit` config, the browser itself pushes every added or edited open item to a locally running Emblema (debounced 500 ms, silent-fail: an unreachable Emblema never blocks the reviewer; the panel header shows a small `emblema` status dot). The session menu keeps **Resend all to Emblema** as a one-click fallback that re-dispatches every open item on the page.
+
+**Which repo gets edited** is Emblema's knowledge, not the website's: the intake advertises its `repoPath` in the `/intake/ping` answer, and the local agent has it in `.reviewkit/emblema-sync.json` (`init --repo`, default: the directory you ran it in). `emblema.repoPath` remains as an optional override only; an absolute path from a reviewer's laptop has no place in host code.
 
 **Where the key lives:** the pairing key and state are stored by the local sync agent in `<project>/.reviewkit/emblema-sync.json`. The key (`emk_…`) is a secret — the panel only ever displays it shortened (`emk_…last4`) and puts the full value on the clipboard.
 
-**Set up and generate a key** (in the project repo):
+**Set up and generate a key** (in the project repo; the CLI is its own package so host installs stay CLI-free):
 
 ```sh
-npx reviewkit-emblema init --origin https://your-site   # creates the state file, prints the key
-npx reviewkit-emblema serve                             # runs the local API + realtime bridge
+npx -p @satanwagen/reviewkit-cli reviewkit-emblema init --origin https://your-site --sync-url wss://your-site/rk-sync --sync-token <secret>
+npx -p @satanwagen/reviewkit-cli reviewkit-emblema serve      # local API + realtime bridge (bridge needs both sync flags)
 ```
 
 Paste the printed key into Emblema. From the page UI the same lives in the panel's gear menu → **Connect to Emblema…** — the menu entry shows the live pairing status at a glance (green dot = paired, amber = the local agent isn't answering, red = key revoked, grey = not paired), and the dialog has **New key (rotate)**, **Copy key** and **Delete key (revoke)**.
@@ -257,22 +346,24 @@ Paste the printed key into Emblema. From the page UI the same lives in the panel
 **Rotate / revoke from the CLI:**
 
 ```sh
-npx reviewkit-emblema key      # print the current key
-npx reviewkit-emblema rotate   # issue a new secret — the old key stops working immediately
-npx reviewkit-emblema revoke   # disable the pairing entirely (rotate re-enables)
+npx -p @satanwagen/reviewkit-cli reviewkit-emblema key      # print the current key
+npx -p @satanwagen/reviewkit-cli reviewkit-emblema rotate   # issue a new secret — the old key stops working immediately
+npx -p @satanwagen/reviewkit-cli reviewkit-emblema revoke   # disable the pairing entirely (rotate re-enables)
 ```
 
 Rotate and revoke take effect immediately, including against an already-running `serve` process — authenticated requests always check the current on-disk key, so a rotated or revoked key can never keep authenticating.
 
-## Demo
+If the host sends a CSP, the bridge needs `connect-src http://127.0.0.1:*` (see "CSP").
+
+## Demos
 
 ```sh
 cd examples/vite-demo
 npm install
-npm run dev   # http://localhost:3010 — dev build, so the layer is active immediately
+npm run dev   # http://localhost:3010 — devAutoOn keeps the layer on in dev
 ```
 
-Also try `http://localhost:3010/?review=demo` to exercise URL activation.
+Also try `http://localhost:3010/?review=demo-review` to exercise URL activation. `examples/next-demo` is the same site on Next.js (App Router, `/next` entry, CSP headers) on port 3011.
 
 ## Development
 
@@ -281,4 +372,7 @@ npm install
 npm run typecheck
 npm run lint
 npm run build   # tsup → dist/ (ESM + CJS + d.ts)
+npm test        # CLI tests + activation matrix (needs dist/)
 ```
+
+See `CHANGELOG.md` for the 0.1.3 default changes and migration notes.