@mhosaic/feedback-cli 0.13.0 → 0.14.1

package/skills/integrate-feedback/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: integrate-feedback
+description: Walk a teammate through integrating @mhosaic/feedback — either provisioning a project as the platform operator, or installing the widget in a host app as the consumer. Use when the user mentions adding the Mhosaic feedback widget, onboarding a new app, getting a public key, or wiring the widget into their codebase.
+---
+
+# /integrate-feedback — guided widget integration
+
+You are guiding a teammate through integrating the **@mhosaic/feedback** widget into a project. The workflow splits into two modes:
+
+- **Operator mode** — the platform admin (Victor or a delegate). Provisions a new Company / Project / public key on the Mhosaic backend. Has admin access to the software-factory admin SPA.
+- **Consumer mode** — a teammate. Installs the widget in their own app, given a key + endpoint from the operator.
+
+**Both modes are guided. Never assume — confirm at every checkpoint.**
+
+---
+
+## Step 0: Identify the mode
+
+Ask the user which mode they're in. Use `AskUserQuestion` with:
+
+- question: `Which side of the integration are you working on?`
+- header: `Mode`
+- options:
+  - label: `Provision (operator)`, description: `Create a new Company/Project/key in the Mhosaic backend. Requires admin SPA access.`
+  - label: `Install (consumer)`, description: `Add the widget to a host app. You already have a pk_proj_… key + endpoint from the operator.`
+  - label: `Both — start with operator, then consumer`, description: `Provision first, then keep going.`
+
+Branch on the answer. Each branch is documented in detail under `references/`.
+
+---
+
+## Step 0.5: Pre-flight (operator mode only)
+
+If the user picked operator (or "Both"), confirm Chrome MCP is configured before going further. Operator mode hard-depends on `mcp__claude-in-chrome__*` tools — without them, the API-driving step at the heart of `references/operator-provision.md` can't run.
+
+Check: call `mcp__claude-in-chrome__tabs_context_mcp` once. Possible outcomes:
+
+- **Tool returns a tab list (even an empty one)** — Chrome MCP is installed. Proceed.
+- **Tool isn't available / errors with "tool not found"** — Chrome MCP isn't configured on this Claude Code install. Tell the user:
+
+  > "Operator mode needs the Chrome MCP server (`@anthropic/claude-in-chrome` or equivalent). Without it, the skill can't drive the admin SPA programmatically. Two options:
+  > 1. Install Chrome MCP (Claude Code → MCP settings → add the chrome connector), then re-run `/integrate-feedback`.
+  > 2. Provision manually via `docs/INTEGRATING.md` (operator-side: open the admin SPA, create the project, mint the key) and then re-run `/integrate-feedback` in consumer mode with the resulting handoff payload."
+
+  Stop. Don't continue operator mode without MCP.
+
+Consumer mode (install) does NOT need Chrome MCP for the install itself — only for the live smoke test in `references/verify-install.md`. If MCP isn't available, the skill can still do everything up to step 9 of consumer-install.md, and the smoke test degrades to "open this URL in your browser yourself and confirm the FAB renders."
+
+---
+
+## Operator mode — provisioning
+
+**Goal:** end-to-end, produce a Markdown "handoff payload" the teammate can paste into Claude Code (or follow manually) to install the widget.
+
+**Read** the full step-by-step procedure at:
+
+- `references/operator-provision.md`
+
+The procedure walks through:
+
+1. Confirming the company exists (or creating it)
+2. Collecting the project name, slug, and `allowed_origins` (the teammate's deployment URL[s])
+3. Driving Chrome MCP to the admin SPA at https://software-factory-3tbbu.ondigitalocean.app
+4. Calling the DRF API from the *already-authenticated* browser context (no token copy-paste)
+5. Minting a `pk_proj_…` widget key and capturing its plaintext value
+6. Assembling and printing the handoff payload
+
+**Crucial:** the operator must already be SSO-logged-in to software-factory before the skill drives Chrome. If they're not, the skill detects this and walks them through `/login` first.
+
+After the operator branch finishes, ask whether they want to continue into consumer mode in the same conversation (helpful when they're integrating into one of their own apps).
+
+---
+
+## Consumer mode — installing
+
+**Goal:** end-to-end, the widget loads on the host app and a smoke-test report lands in the admin.
+
+**Read** the framework-aware install procedure at:
+
+- `references/consumer-install.md`
+
+The procedure walks through:
+
+1. Verifying we're in a JS/TS project (reads `package.json`)
+2. Detecting the framework (Vite/Next/Remix/Vue/SvelteKit/CDN)
+3. Accepting the handoff payload — either pasted verbatim or via `--from-clipboard`
+4. Running `npx @mhosaic/feedback-cli init --api-key=… --endpoint=… --yes` (non-interactive)
+5. For non-Vite-React frameworks: pasting the framework-specific snippet from `references/consumer-install-<framework>.md` and asking the user to apply it
+6. Wiring `fb.identify()` against the consumer's auth provider — recipes in `references/identify-snippets.md`
+7. Optionally wiring `withErrorTracking` + `withReplay` + `withWebVitals`
+8. Running `mhosaic-feedback verify --origin <consumer dev origin>` to confirm CORS, key, and endpoint
+9. Starting the consumer's dev server and driving Chrome to verify the FAB renders
+10. Submitting a `[INTEGRATE-FEEDBACK SMOKE TEST]` synthetic report from the FAB
+11. Driving Chrome to software-factory's `/reports` and confirming the smoke-test report appears
+
+The smoke-test workflow lives at:
+
+- `references/verify-install.md`
+
+---
+
+## Principles to follow
+
+- **Confirm at every fork.** Never assume a default. Use `AskUserQuestion` for choices, plain text questions for free-form input.
+- **Show, don't tell.** When you can run a command and show output, run it. When you can drive Chrome and screenshot, drive Chrome.
+- **Idempotent and reversible.** Every state-changing step has a stated rollback (e.g. revoke key in admin SPA, run `mhosaic-feedback eject`). Surface that to the user.
+- **Stop on first red.** If the smoke test fails, do not silently retry. Read `references/verify-install.md`'s diagnostic table, narrow the cause, fix it, then re-run from the failing step.
+- **Don't paste secret keys into git.** Walk the user through adding `.env.local` to `.gitignore` (CLI does this automatically; double-check).
+- **Don't claim "done" without proof.** End the workflow with a screenshot of the smoke-test report landing in admin OR with a clearly enumerated red checklist of what's still broken.
+
+---
+
+## Operator → consumer handoff payload format
+
+Always produce this Markdown block at the end of operator mode. The consumer pastes it as the very first message to Claude after running `/integrate-feedback` in their own repo:
+
+````markdown
+## Mhosaic Feedback handoff
+
+**Project slug:** `your-project-slug`
+**Endpoint:** `https://software-factory-3tbbu.ondigitalocean.app`
+**Public widget key:** `pk_proj_xxxxxxxxxxxxxxxxxxxxxxxxxx`
+**Allowed origin(s):** `https://your-app.example.com`, `http://localhost:5173`
+
+To install:
+```bash
+npx @mhosaic/feedback-cli@latest init \
+  --api-key pk_proj_xxxxxxxxxxxxxxxxxxxxxxxxxx \
+  --endpoint https://software-factory-3tbbu.ondigitalocean.app \
+  --yes
+```
+
+Then verify:
+```bash
+npx @mhosaic/feedback-cli@latest verify \
+  --origin http://localhost:5173 \
+  --with-test-report
+```
+````
+
+The skill's consumer mode parses this block automatically when pasted as input.
+
+---
+
+## Skill files
+
+```
+skills/integrate-feedback/
+├── SKILL.md                              # this file (mode router)
+├── references/
+│   ├── operator-provision.md             # Chrome MCP → admin SPA → DRF
+│   ├── consumer-install.md               # framework router
+│   ├── consumer-install-vite.md          # Vite + React (CLI auto-wires)
+│   ├── consumer-install-next.md          # Next.js App Router + Pages
+│   ├── consumer-install-nuxt.md          # Nuxt 3 (client plugin)
+│   ├── consumer-install-astro.md         # Astro (<script> in Layout)
+│   ├── consumer-install-remix.md         # Remix root.tsx
+│   ├── consumer-install-vue.md           # Vue 3 + Vite
+│   ├── consumer-install-svelte.md        # SvelteKit
+│   ├── consumer-install-plain.md         # CDN <script> tag
+│   ├── identify-snippets.md              # fb.identify() per auth provider
+│   └── verify-install.md                 # smoke test + diagnostics
+```

package/skills/integrate-feedback/references/consumer-install-astro.md

@@ -0,0 +1,83 @@
+# Consumer install — Astro
+
+The CLI's auto-wrap is React-only; for Astro you'll wire the widget into a client-only Astro component (or via the renderer of your choice).
+
+---
+
+## Step 1 — Env vars
+
+Astro uses Vite under the hood. Env vars meant for the browser need the `PUBLIC_` prefix:
+
+```diff
+- VITE_FEEDBACK_API_KEY=pk_proj_…
+- VITE_FEEDBACK_ENDPOINT=https://…
++ PUBLIC_FEEDBACK_API_KEY=pk_proj_…
++ PUBLIC_FEEDBACK_ENDPOINT=https://software-factory-3tbbu.ondigitalocean.app
+```
+
+---
+
+## Step 2 — Add a client-only widget mount
+
+Astro doesn't ship JS by default; you have to opt-in with `client:*` directives or via `<script>` blocks. The cleanest path is a `<script>` block in your shared layout:
+
+```astro
+---
+// src/layouts/Layout.astro
+const apiKey = import.meta.env.PUBLIC_FEEDBACK_API_KEY
+const endpoint = import.meta.env.PUBLIC_FEEDBACK_ENDPOINT
+---
+<html>
+  <head><slot name="head" /></head>
+  <body>
+    <slot />
+
+    <script>
+      import { createFeedback } from '@mhosaic/feedback'
+      import { withErrorTracking } from '@mhosaic/feedback/error-tracking'
+      import { withReplay } from '@mhosaic/feedback/replay'
+      import { withWebVitals } from '@mhosaic/feedback/webvitals'
+
+      const apiKey = import.meta.env.PUBLIC_FEEDBACK_API_KEY
+      const endpoint = import.meta.env.PUBLIC_FEEDBACK_ENDPOINT
+      if (apiKey && endpoint) {
+        withErrorTracking(withReplay(withWebVitals(createFeedback({
+          apiKey, endpoint, env: import.meta.env.PROD ? 'prod' : 'dev',
+        }))))
+      }
+    </script>
+  </body>
+</html>
+```
+
+Astro will bundle the script and run it on the client. The widget mounts to its own Shadow DOM, independent of Astro's island hydration.
+
+---
+
+## Step 3 — Wire identify()
+
+How you do this depends on what auth backs your Astro site:
+
+- **Astro auth integration (e.g. `@auth/astro`, Lucia)** — call `fb.identify()` from a client-only component that reads the session via the matching SDK.
+- **Server-rendered session passed to client via cookies / `window.ENV` pattern** — same trick as Remix: in `Layout.astro` render a small inline `<script>` that surfaces the user via `window.__USER`, then call `fb.identify(window.__USER)` from the import-script block.
+- **Anonymous-only / mostly-static site** — use the anonymous snippet from `references/identify-snippets.md` so the FAB renders for everyone.
+
+If the site is mostly static (marketing, docs), anonymous is the typical pick — visitors aren't logged in.
+
+---
+
+## Gotchas
+
+- **No SSR window:** Astro's component code runs on the server. Only code inside `<script>` blocks (or `client:*`-hydrated components) runs in the browser. Always wrap the widget init inside `<script>`.
+- **View Transitions API:** if you use Astro's `<ViewTransitions />`, the widget mount survives navigations (it's outside Astro's routed area, in `<body>`). Good — no re-mount churn.
+- **Build output type:** the widget needs `output: 'server'` or `output: 'hybrid'` only if you want the SSR-side env injection; for static (`output: 'static'`), env vars are inlined at build time and the widget still works.
+
+---
+
+## Verifying
+
+```bash
+npx @mhosaic/feedback-cli@latest verify --origin http://localhost:4321 --with-test-report
+```
+
+Astro dev defaults to port 4321.

package/skills/integrate-feedback/references/consumer-install-next.md

@@ -0,0 +1,133 @@
+# Consumer install — Next.js
+
+The CLI's auto-wrap is Vite+React only. For Next.js you'll paste the snippet manually. Detect whether the user has the **App Router** (`app/` directory) or the **Pages Router** (`pages/` directory) and branch.
+
+---
+
+## Step 1 — Rename env vars
+
+The CLI wrote `VITE_FEEDBACK_API_KEY` + `VITE_FEEDBACK_ENDPOINT`. Next.js needs the `NEXT_PUBLIC_` prefix for client-readable env vars. Open `.env.local` and rename both keys:
+
+```diff
+- VITE_FEEDBACK_API_KEY=pk_proj_…
+- VITE_FEEDBACK_ENDPOINT=https://…
++ NEXT_PUBLIC_FEEDBACK_API_KEY=pk_proj_…
++ NEXT_PUBLIC_FEEDBACK_ENDPOINT=https://…
+```
+
+Use the `Edit` tool to make the change.
+
+---
+
+## Step 2 — App Router (Next.js 13+) — paste the client component
+
+Create a new file `app/components/FeedbackMount.tsx`:
+
+```typescript
+'use client'
+
+import { useEffect } from 'react'
+import { createFeedback } from '@mhosaic/feedback'
+import { withErrorTracking } from '@mhosaic/feedback/error-tracking'
+import { withReplay } from '@mhosaic/feedback/replay'
+import { withWebVitals } from '@mhosaic/feedback/webvitals'
+
+export function FeedbackMount() {
+  useEffect(() => {
+    const apiKey = process.env.NEXT_PUBLIC_FEEDBACK_API_KEY
+    const endpoint = process.env.NEXT_PUBLIC_FEEDBACK_ENDPOINT
+    if (!apiKey || !endpoint) return
+
+    withErrorTracking(
+      withReplay(
+        withWebVitals(createFeedback({ apiKey, endpoint, env: process.env.NODE_ENV === 'development' ? 'dev' : 'prod' }))
+      )
+    )
+  }, [])
+  return null
+}
+```
+
+Then mount it in `app/layout.tsx` (a Server Component):
+
+```typescript
+import { FeedbackMount } from './components/FeedbackMount'
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html>
+      <body>
+        <FeedbackMount />
+        {children}
+      </body>
+    </html>
+  )
+}
+```
+
+The `'use client'` directive in `FeedbackMount.tsx` is critical — it tells Next.js to ship this component to the browser. Without it, the widget never mounts (the effect never runs on the server).
+
+---
+
+## Step 3 — Pages Router (Next.js 12 or App-Router-free 13+)
+
+Edit `pages/_app.tsx`:
+
+```typescript
+import { useEffect } from 'react'
+import type { AppProps } from 'next/app'
+import { createFeedback } from '@mhosaic/feedback'
+import { withErrorTracking } from '@mhosaic/feedback/error-tracking'
+import { withReplay } from '@mhosaic/feedback/replay'
+import { withWebVitals } from '@mhosaic/feedback/webvitals'
+
+export default function App({ Component, pageProps }: AppProps) {
+  useEffect(() => {
+    const apiKey = process.env.NEXT_PUBLIC_FEEDBACK_API_KEY
+    const endpoint = process.env.NEXT_PUBLIC_FEEDBACK_ENDPOINT
+    if (!apiKey || !endpoint) return
+    withErrorTracking(withReplay(withWebVitals(createFeedback({
+      apiKey, endpoint, env: process.env.NODE_ENV === 'development' ? 'dev' : 'prod'
+    }))))
+  }, [])
+  return <Component {...pageProps} />
+}
+```
+
+---
+
+## Step 4 — Wire identify()
+
+See `references/identify-snippets.md`. Most Next.js apps use NextAuth or Clerk; both snippets there assume a client component with `useSession()` / `useUser()`.
+
+If you're using NextAuth, the cleanest pattern is to add a `<FeedbackIdentity />` client component as a sibling of `<FeedbackMount />` in `app/layout.tsx`.
+
+---
+
+## Gotchas
+
+- **Server Components can't mount the widget.** Any module that touches the DOM (the widget's mount routine, rrweb's MutationObserver) must run on the client. Either wrap in `'use client'` or call inside a `useEffect`.
+- **Static generation:** if you use `getStaticProps` or App Router's static rendering, the widget's identity will only attach on hydration. Server-rendered pages will briefly show *without* the FAB until the client effect fires. That's expected.
+- **Edge runtime:** the widget assumes `window` exists. Don't import it from anything that runs on the Edge runtime (middleware, route handlers with `runtime = 'edge'`).
+- **CSP:** if your `next.config.js` sets a strict CSP, you'll need to allow `connect-src` to the feedback endpoint and `worker-src 'blob:'` for rrweb. The widget docs cover this; cite them when CSP errors appear in DevTools.
+
+---
+
+## Env vars
+
+```
+NEXT_PUBLIC_FEEDBACK_API_KEY=pk_proj_…
+NEXT_PUBLIC_FEEDBACK_ENDPOINT=https://software-factory-3tbbu.ondigitalocean.app
+```
+
+`NEXT_PUBLIC_*` are inlined at build time. To change them, restart `next dev`.
+
+---
+
+## Verifying
+
+```bash
+npx @mhosaic/feedback-cli@latest verify --origin http://localhost:3000 --with-test-report
+```
+
+The default Next.js dev port is 3000 (not Vite's 5173). Adjust `--origin` to match.

package/skills/integrate-feedback/references/consumer-install-nuxt.md

@@ -0,0 +1,108 @@
+# Consumer install — Nuxt 3
+
+The CLI's auto-wrap is React-only; for Nuxt you paste the snippet into a client-only plugin.
+
+---
+
+## Step 1 — Env vars
+
+Nuxt 3 exposes env vars via `runtimeConfig`. Open `.env` (or `.env.local` — Nuxt reads both) and rename:
+
+```diff
+- VITE_FEEDBACK_API_KEY=pk_proj_…
+- VITE_FEEDBACK_ENDPOINT=https://…
++ NUXT_PUBLIC_FEEDBACK_API_KEY=pk_proj_…
++ NUXT_PUBLIC_FEEDBACK_ENDPOINT=https://software-factory-3tbbu.ondigitalocean.app
+```
+
+Add the matching `runtimeConfig.public` entries to `nuxt.config.ts`:
+
+```typescript
+export default defineNuxtConfig({
+  runtimeConfig: {
+    public: {
+      feedbackApiKey: '',
+      feedbackEndpoint: '',
+    },
+  },
+})
+```
+
+Nuxt auto-binds `NUXT_PUBLIC_*` env vars to the matching `runtimeConfig.public.*` keys at runtime.
+
+---
+
+## Step 2 — Add a client-only plugin
+
+Create `plugins/feedback.client.ts` (the `.client.ts` suffix tells Nuxt to bundle this only for the browser, not SSR):
+
+```typescript
+import { createFeedback } from '@mhosaic/feedback'
+import { withErrorTracking } from '@mhosaic/feedback/error-tracking'
+import { withReplay } from '@mhosaic/feedback/replay'
+import { withWebVitals } from '@mhosaic/feedback/webvitals'
+
+export default defineNuxtPlugin(() => {
+  const config = useRuntimeConfig()
+  const fb = withErrorTracking(
+    withReplay(
+      withWebVitals(createFeedback({
+        apiKey: config.public.feedbackApiKey as string,
+        endpoint: config.public.feedbackEndpoint as string,
+        env: process.dev ? 'dev' : 'prod',
+      }))
+    )
+  )
+  return { provide: { feedback: fb } }
+})
+```
+
+Now `useNuxtApp().$feedback` is available across the app.
+
+---
+
+## Step 3 — Wire identify()
+
+Nuxt's auth is whatever you bolt on (sidebase/nuxt-auth, custom, Supabase, etc.). Use the matching snippet from `references/identify-snippets.md`, called from a `watchEffect` inside `app.vue` or a top-level `<script setup>` that re-runs on auth state changes:
+
+```vue
+<!-- app.vue -->
+<script setup lang="ts">
+import { useAuthStore } from '~/stores/auth'  // adapt to your auth source
+
+const auth = useAuthStore()
+const { $feedback } = useNuxtApp()
+
+watchEffect(() => {
+  if (auth.user) {
+    $feedback.identify({ id: auth.user.id, email: auth.user.email, name: auth.user.name })
+  } else {
+    $feedback.identify({ id: '', email: '', name: '' })
+  }
+})
+</script>
+
+<template>
+  <NuxtLayout>
+    <NuxtPage />
+  </NuxtLayout>
+</template>
+```
+
+---
+
+## Gotchas
+
+- **SSR + window:** Nuxt SSRs everything by default. The `.client.ts` suffix on the plugin ensures the widget code never runs on the Nitro server (where `window` doesn't exist).
+- **`useRuntimeConfig()` returns empty strings on first render** if the env vars weren't set — Nuxt warns at startup. Verify your `.env` has the right `NUXT_PUBLIC_*` keys.
+- **Static site mode (`nuxt generate`):** the widget hydrates at runtime, same as Next.js. Generated pages render without the FAB until JS hydrates.
+
+---
+
+## Verifying
+
+```bash
+npx @mhosaic/feedback-cli@latest verify --origin http://localhost:3000 --with-test-report
+```
+
+Nuxt dev defaults to port 3000.

package/skills/integrate-feedback/references/consumer-install-plain.md

@@ -0,0 +1,92 @@
+# Consumer install — plain HTML / CDN (no bundler)
+
+For host apps without a JS bundler (Django templates, Rails ERB, Hugo, plain `.html` files served statically, etc.), use the CDN-hosted IIFE bundle. No npm install needed.
+
+---
+
+## Step 1 — Find the latest version + SRI hash
+
+The bundle is published to jsDelivr from the npm release. Get the current version + integrity hash from the top-level `README.md` of the feedback-tool-mhosaic repo (or from the operator). The format is:
+
+```html
+<script
+  src="https://cdn.jsdelivr.net/npm/@mhosaic/feedback@<VERSION>/dist/embed.min.js"
+  integrity="sha384-<HASH>"
+  crossorigin="anonymous"
+  data-key="pk_proj_…"
+  data-endpoint="https://software-factory-3tbbu.ondigitalocean.app"
+  data-env="prod"
+  defer
+></script>
+```
+
+Pin the **exact** version. Don't use `@latest` — that breaks SRI and gives you no rollback story. The operator can update the version on a deploy cycle.
+
+---
+
+## Step 2 — Insert into your template
+
+Drop the `<script>` tag near the closing `</body>` of every page that should show the FAB. For Django: `templates/base.html`. For Rails: `app/views/layouts/application.html.erb`. For static sites: the page template / partial that's shared across pages.
+
+If your app has a Content Security Policy, you'll need to allow:
+- `script-src https://cdn.jsdelivr.net 'sha384-<HASH>'`
+- `connect-src https://software-factory-3tbbu.ondigitalocean.app`
+- `worker-src 'blob:'` (only if you'll later upgrade to a version that ships rrweb replay)
+
+---
+
+## Step 3 — Wire identify() via the queue API
+
+The CDN bundle exposes a global function `window.Feedback` that queues calls until the bundle finishes loading. Drop this **before** the `<script src=…>` tag so the queue exists when the bundle initializes:
+
+```html
+<script>
+  window.Feedback = window.Feedback || function () {
+    (window.Feedback.q = window.Feedback.q || []).push(arguments)
+  }
+</script>
+```
+
+Then, anywhere after your auth resolves, call:
+
+```html
+<script>
+  Feedback('identify', {
+    id: '<%= current_user.id %>',
+    email: '<%= current_user.email %>',
+    name: '<%= current_user.name %>',
+  })
+</script>
+```
+
+(Substitute your template language's interpolation: `{{ }}` for Django, `<%= %>` for ERB, etc.)
+
+For anonymous-only deployments, pass a stable placeholder id so the FAB still renders:
+
+```html
+<script>
+  Feedback('identify', { id: 'anon-' + (localStorage.getItem('anonId') || (localStorage.setItem('anonId', crypto.randomUUID()), localStorage.getItem('anonId'))), name: 'Anonymous' })
+</script>
+```
+
+---
+
+## Gotchas
+
+- **No auto-capture modules on the CDN bundle.** The CDN IIFE is the bare widget. `withErrorTracking` / `withReplay` / `withWebVitals` are available only via npm import. If the user wants those, they must switch to the bundled (npm) install — drop the `<script>` tag and follow the framework-specific reference instead.
+- **SRI hash must match the bytes** at the pinned version. If you bump the version, regenerate the hash:
+  ```bash
+  curl -s https://cdn.jsdelivr.net/npm/@mhosaic/feedback@<VERSION>/dist/embed.min.js | openssl dgst -sha384 -binary | openssl base64 -A
+  ```
+- **CDN cache lag:** new versions can take up to an hour to propagate across jsDelivr's edge. If you just published and the version 404s, wait or use `https://cdn.jsdelivr.net/npm/@mhosaic/feedback/dist/embed.min.js` (without `@VERSION`, but breaks SRI) for a one-off test, then pin properly.
+
+---
+
+## Verifying
+
+The `verify` CLI command reads `.env.local`, which the CDN install doesn't use. To verify the CDN install, drive Chrome to your page and check:
+
+1. The `<script>` tag loads (DevTools network → no 404 / SRI error)
+2. `window.Feedback` exists (DevTools console: `typeof Feedback`)
+3. The FAB renders (visual check; bottom-right corner)
+4. Submitting a test report lands in `/reports` (see `references/verify-install.md`)

package/skills/integrate-feedback/references/consumer-install-remix.md

@@ -0,0 +1,93 @@
+# Consumer install — Remix
+
+The CLI's auto-wrap is Vite+React only; Remix needs the snippet pasted manually.
+
+---
+
+## Step 1 — Rename env vars
+
+Remix exposes env vars to the client via a loader on the root route, not a build-time prefix. Open `.env.local`, **drop the `VITE_` prefix** (you'll surface these through a loader instead):
+
+```
+FEEDBACK_API_KEY=pk_proj_…
+FEEDBACK_ENDPOINT=https://software-factory-3tbbu.ondigitalocean.app
+```
+
+---
+
+## Step 2 — Expose env via the root loader
+
+In `app/root.tsx`, add a loader that surfaces the values to the client window:
+
+```typescript
+import type { LoaderFunctionArgs } from '@remix-run/node'
+import { json, useLoaderData, Outlet, Scripts } from '@remix-run/react'
+import { useEffect } from 'react'
+import { createFeedback } from '@mhosaic/feedback'
+import { withErrorTracking } from '@mhosaic/feedback/error-tracking'
+import { withReplay } from '@mhosaic/feedback/replay'
+import { withWebVitals } from '@mhosaic/feedback/webvitals'
+
+export async function loader({ request }: LoaderFunctionArgs) {
+  return json({
+    ENV: {
+      FEEDBACK_API_KEY: process.env.FEEDBACK_API_KEY,
+      FEEDBACK_ENDPOINT: process.env.FEEDBACK_ENDPOINT,
+    },
+  })
+}
+
+export default function App() {
+  const data = useLoaderData<typeof loader>()
+  useEffect(() => {
+    const { FEEDBACK_API_KEY, FEEDBACK_ENDPOINT } = data.ENV
+    if (!FEEDBACK_API_KEY || !FEEDBACK_ENDPOINT) return
+    withErrorTracking(withReplay(withWebVitals(createFeedback({
+      apiKey: FEEDBACK_API_KEY,
+      endpoint: FEEDBACK_ENDPOINT,
+      env: process.env.NODE_ENV === 'development' ? 'dev' : 'prod',
+    }))))
+  }, [data.ENV])
+
+  return (
+    <html>
+      <head><title>Your app</title></head>
+      <body>
+        <Outlet />
+        <script
+          dangerouslySetInnerHTML={{
+            __html: `window.ENV = ${JSON.stringify(data.ENV)}`,
+          }}
+        />
+        <Scripts />
+      </body>
+    </html>
+  )
+}
+```
+
+The `window.ENV` script tag is Remix's idiomatic env-passing pattern. If your app already has a root loader doing this, just add the two FEEDBACK_* keys to the existing `ENV` object instead of duplicating the loader.
+
+---
+
+## Step 3 — Wire identify()
+
+See `references/identify-snippets.md`. Remix apps usually authenticate via cookies + a loader-returned user; the identify call belongs in a `useEffect` on whichever route boundary returns the user object (usually root).
+
+---
+
+## Gotchas
+
+- **Loader runs on every request.** Putting the widget mount in `useEffect` with `[data.ENV]` as a dep ensures it runs once on the client and not on re-renders.
+- **SSR + rrweb:** rrweb touches `MutationObserver` and `document`; never import the widget at module-top-level — keep it inside the `useEffect`. The pattern above does that.
+- **Catch boundaries:** if your root route errors, the widget won't mount. That's fine — errors will be visible from the error UI, and once the operator fixes the underlying issue, the widget comes back.
+
+---
+
+## Verifying
+
+```bash
+npx @mhosaic/feedback-cli@latest verify --origin http://localhost:3000 --with-test-report
+```
+
+Remix dev's default port is 3000.