@mhosaic/feedback-cli 0.14.0 → 0.16.1

package/skills/integrate-feedback/SKILL.md

@@ -1,99 +1,138 @@
 ---
 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.
+description: Full guide for integrating @mhosaic/feedback. Covers operator-side provisioning (Company/Project/pk_proj_ key creation via the admin SPA), consumer-side install (CLI run + framework-specific wiring + identify() recipes + smoke test), and every common question a teammate might ask — what permissions are needed, where to run from, how the operator→consumer handoff works, what Chrome MCP is for, external clients vs internal apps, why the FAB isn't appearing, CORS errors, etc. Use whenever the user mentions: the Mhosaic feedback widget, adding feedback to an app, onboarding a new client/app, getting a pk_proj_ key, deploying for a company, configuring identify(), CORS errors on the widget, or any troubleshooting around the integration. Equally useful as a slash-command runbook and as a reference Claude reads to answer ad-hoc questions.
+user-invocable: true
 ---
 
 # /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:
+End-to-end flow for getting the **@mhosaic/feedback** widget into a host app. There are two phases, run in two separate places:
 
-- **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.
+1. **Operator phase** — provisions Company / Project / `pk_proj_…` key on the Mhosaic backend (https://software-factory-3tbbu.ondigitalocean.app). Run from **inside `feedback-tool-mhosaic`**. The skill drives Chrome at the admin SPA, no filesystem changes. At the end, it outputs a Markdown handoff payload and offers to install itself globally so phase 2 is invokable in the client's repo.
 
-**Both modes are guided. Never assume — confirm at every checkpoint.**
+2. **Consumer phase** — installs the widget in the host app. Run from **inside the client's app directory** (NOT feedback-tool-mhosaic). The skill detects the framework, runs the CLI's `init`, pastes the right entry-point snippet, wires `identify()` against the client's auth provider, and runs a live smoke test in Chrome.
+
+This skill is **both** a slash-command runbook AND a reference doc. When the user invokes `/integrate-feedback`, run the procedural flow. When they just ask an integration question, answer from the Q&A below.
 
 ---
 
-## Step 0: Identify the mode
+## Quick Q&A
 
-Ask the user which mode they're in. Use `AskUserQuestion` with:
+**"What does this skill do?"**
+End-to-end widget integration. Operator phase: creates Company/Project/key on the backend. Consumer phase: installs the widget in a host app + runs a smoke test that confirms a report lands in admin. Framework-aware (Vite/Next/Nuxt/Astro/Remix/Vue/SvelteKit/plain HTML). Auth-aware (Auth0/Clerk/Supabase/Firebase/NextAuth/Django/JWT/anonymous).
 
-- 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.`
+**"Do I need to install anything first?"**
 
-Branch on the answer. Each branch is documented in detail under `references/`.
+- Inside `feedback-tool-mhosaic`: no. The skill is committed under `.claude/skills/integrate-feedback/`; `/integrate-feedback` works directly.
+- In the client's repo: optional. If you want `/integrate-feedback` invokable there too (recommended for the consumer phase), the operator phase will offer to install it globally for you (one shell command, `npx @mhosaic/feedback-cli@latest install-skill`). Skip the install and the consumer phase can still happen — you just run `npx @mhosaic/feedback-cli@latest init …` directly in the client's repo and follow the framework-specific snippet from `references/`.
 
----
+**"Where do I run `/integrate-feedback` from?"**
+
+- Operator phase: **inside `feedback-tool-mhosaic`** (any directory in the monorepo).
+- Consumer phase: **inside the client's app's project root**.
+- Don't run consumer phase inside `feedback-tool-mhosaic` — the CLI would install the widget into our own monorepo. The skill detects this (via `package.json` name check) and refuses.
 
-## Operator mode — provisioning
+**"What permissions do I need on the backend?"**
 
-**Goal:** end-to-end, produce a Markdown "handoff payload" the teammate can paste into Claude Code (or follow manually) to install the widget.
+- Login: Feedback Django group.
+- Create a Project/key under an existing company: Feedback group + Membership for that company.
+- Create a brand-new Company (external client): `is_staff=True` + `is_superuser=True`. Held by the platform maintainers.
 
-**Read** the full step-by-step procedure at:
+**"What's Chrome MCP and why do I need it?"**
+A Claude Code MCP server that lets the skill drive a real Chrome tab. Operator phase uses it to call our admin API from the authenticated browser session (no token paste). Consumer phase uses it for the smoke test. If MCP isn't configured, operator phase stops at Step 0.5 with an install hint; consumer phase degrades to "open the dev URL yourself and confirm visually."
 
-- `references/operator-provision.md`
+**"How does the handoff between phases work?"**
+End of operator phase produces a Markdown payload (endpoint, `pk_proj_…`, slug, allowed origins). The skill prints it AND offers to install itself globally. The operator then closes this Claude session, `cd`s into the client's repo, opens a fresh `claude`, runs `/integrate-feedback`, picks "Install (consumer)", and pastes the payload as the first message.
 
-The procedure walks through:
+**"My FAB isn't appearing — what's wrong?"**
+The FAB stays hidden until `fb.identify({id: 'something'})` runs with a non-empty `id`. Check `references/identify-snippets.md` for your auth provider's recipe. For testing, hardcode `fb.identify({id: 'test'})` to force-render.
 
-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
+**"CORS errors / 403 / origin not allowed."**
+The project's `allowed_origins` doesn't include the URL the request comes from. Usual causes: forgot the dev URL (e.g. `http://localhost:5173`), trailing slash, path included, wildcard (rejected by design). Operator opens admin SPA → Edit project → adds the missing origin.
 
-**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.
+**"External client vs internal Mhosaic app?"**
 
-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).
+- Internal: use existing companies (`mhosaic`, `arime`, `norag`); create a new project under one. Needs Feedback group + Membership.
+- External: create a brand-new Company. Needs `is_staff=True`. The client can't log into software-factory (it's @mhosaic.com-only SSO); Mhosaic acts as report-viewer for v1.
+
+**"Do clients get email digests?"**
+Not by default — notification dispatcher is `NoopDispatcher` on prod. Ping the operator if the client wants the weekly digest (it's a backend env var change).
+
+**"Where's the human-readable doc?"**
+`docs/INTEGRATING.md` in this repo. Covers the skill, the manual fallback, the CLI command reference, and a troubleshooting matrix.
 
 ---
 
-## Consumer mode — installing
+## Step 0 — Identify the phase
+
+`AskUserQuestion`:
 
-**Goal:** end-to-end, the widget loads on the host app and a smoke-test report lands in the admin.
+- question: `Which phase are you running?`
+- header: `Phase`
+- options:
+  - label: `Provision (operator)`, description: `Create a new Company/Project/key on the Mhosaic backend. Run this from inside feedback-tool-mhosaic.`
+  - label: `Install (consumer)`, description: `Install the widget into a host app. Run this from inside the client's app directory, with the handoff payload from the operator phase.`
+
+Branch on the answer.
+
+---
 
-**Read** the framework-aware install procedure at:
+## Step 0.5 — Pre-flight
 
-- `references/consumer-install.md`
+**For operator phase:** confirm Chrome MCP is configured. Call `mcp__claude-in-chrome__tabs_context_mcp` once. If the tool isn't available, tell the user:
 
-The procedure walks through:
+> "Operator phase needs Chrome MCP. 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` (open the admin SPA, create the project, mint the key)."
 
-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
+Stop. Don't continue without MCP.
 
-The smoke-test workflow lives at:
+**For consumer phase:** read `package.json` in the cwd. If its `name` is `@mhosaic/feedback-tool-mhosaic` or any of our own monorepo packages, the user is inside our own repo — refuse and redirect:
 
-- `references/verify-install.md`
+> "Looks like we're inside `feedback-tool-mhosaic`. The consumer phase writes to the current directory; running it here would install the widget into our own monorepo. Close Claude and re-open in the client app's root, then run `/integrate-feedback` again."
+
+Stop. Don't continue.
 
 ---
 
-## Principles to follow
+## Operator phase
 
-- **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.
+Read **`references/operator-provision.md`** and follow it step by step:
+
+1. Confirm operator is SSO-logged-in to software-factory in Chrome.
+2. Collect: company (existing or new), project name + slug, allowed origins, `share_reports_with_widget`.
+3. Drive Chrome MCP to the admin SPA, refresh the JWT via `/api/auth/token/refresh/`, call `POST /companies/`, `POST /projects/`, `POST /project-keys/create/` from the in-tab `fetch()` (uses the existing cookies).
+4. Capture the plaintext `pk_proj_…` from the keys response.
+5. Verify the project + key show up in the admin SPA.
+6. Print the Markdown handoff payload (format below).
+7. Offer to install the skill globally so the operator can run `/integrate-feedback` in the client's repo for the consumer phase. The full offer logic is at the end of `references/operator-provision.md`.
+
+After this phase the operator has: (a) the handoff payload on their clipboard / in the chat, (b) optionally `/integrate-feedback` available globally so the next `claude` in the client repo picks it up.
+
+---
+
+## Consumer phase
+
+Read **`references/consumer-install.md`** and follow it step by step:
+
+1. Confirm cwd is the client app's root (NOT feedback-tool-mhosaic — see Step 0.5).
+2. Parse the pasted handoff payload (endpoint, key, origins).
+3. Detect the framework from `package.json` → route to `references/consumer-install-<framework>.md` (Vite, Next, Nuxt, Astro, Remix, Vue, SvelteKit, or plain/CDN).
+4. Run `npx @mhosaic/feedback-cli@latest init --api-key=… --endpoint=… --yes`.
+5. Apply the framework-specific snippet (CLI auto-wraps Vite+React; other frameworks need a manual paste — Claude does this via `Edit`).
+6. Wire `fb.identify()` per `references/identify-snippets.md` — pick the recipe matching the client's auth provider.
+7. Run `mhosaic-feedback verify --origin <dev-url> --with-test-report` — all 6 checks must be green before proceeding.
+8. Start the dev server, drive Chrome to the dev URL, screenshot the FAB, submit a `[INTEGRATE-FEEDBACK SMOKE TEST]` report.
+9. Drive Chrome to software-factory `/reports`, confirm the report landed.
+
+Smoke test details + diagnostic table: **`references/verify-install.md`**.
 
 ---
 
 ## 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:
+Always print this Markdown block at the end of operator phase:
 
 ````markdown
 ## Mhosaic Feedback handoff
@@ -103,7 +142,8 @@ Always produce this Markdown block at the end of operator mode. The consumer pas
 **Public widget key:** `pk_proj_xxxxxxxxxxxxxxxxxxxxxxxxxx`
 **Allowed origin(s):** `https://your-app.example.com`, `http://localhost:5173`
 
-To install:
+To install (from the client's app directory):
+
 ```bash
 npx @mhosaic/feedback-cli@latest init \
   --api-key pk_proj_xxxxxxxxxxxxxxxxxxxxxxxxxx \
@@ -111,28 +151,33 @@ npx @mhosaic/feedback-cli@latest init \
   --yes
 ```
 
-Then verify:
-```bash
-npx @mhosaic/feedback-cli@latest verify \
-  --origin http://localhost:5173 \
-  --with-test-report
-```
+Or for the full guided flow: `/integrate-feedback` → "Install (consumer)" → paste this block as your first message.
 ````
 
-The skill's consumer mode parses this block automatically when pasted as input.
+---
+
+## Principles
+
+- **Never commit the API key to git. Ever.** Even `pk_proj_…` "public" keys. Full rules + scenario table at the top of `references/consumer-install.md` under "CRITICAL: API key handling". If the user asks "can I commit this?" the answer is NO; do not rationalize. If `.env.local` is excluded from the host's build context (common with Docker), use the deploy-platform's env-var UI, NOT a tracked `.env`.
+- **Confirm at every fork.** Never assume a default. Use `AskUserQuestion` for choices, plain text 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.
+- **Stop on first red.** If the smoke test fails, don't silently retry. Read `references/verify-install.md`'s diagnostic table, narrow the cause, fix it.
+- **Don't claim "done" without proof.** End the workflow with a screenshot of the smoke-test report landing in admin OR an enumerated checklist of what's still broken.
 
 ---
 
 ## Skill files
 
 ```
-skills/integrate-feedback/
-├── SKILL.md                              # this file (mode router)
+.claude/skills/integrate-feedback/
+├── SKILL.md                              # this file (phase 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

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/loader'
+      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

@@ -27,7 +27,7 @@ Create a new file `app/components/FeedbackMount.tsx`:
 'use client'
 
 import { useEffect } from 'react'
-import { createFeedback } from '@mhosaic/feedback'
+import { createFeedback } from '@mhosaic/feedback/loader'
 import { withErrorTracking } from '@mhosaic/feedback/error-tracking'
 import { withReplay } from '@mhosaic/feedback/replay'
 import { withWebVitals } from '@mhosaic/feedback/webvitals'
@@ -76,7 +76,7 @@ Edit `pages/_app.tsx`:
 ```typescript
 import { useEffect } from 'react'
 import type { AppProps } from 'next/app'
-import { createFeedback } from '@mhosaic/feedback'
+import { createFeedback } from '@mhosaic/feedback/loader'
 import { withErrorTracking } from '@mhosaic/feedback/error-tracking'
 import { withReplay } from '@mhosaic/feedback/replay'
 import { withWebVitals } from '@mhosaic/feedback/webvitals'

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/loader'
+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

@@ -1,17 +1,17 @@
 # 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.
+For host apps without a JS bundler (Django templates, Rails ERB, Hugo, plain `.html` files served statically, etc.), drop in the CDN-hosted loader. No npm install needed.
 
----
+The loader is the **manifest-driven thin client** — it's tiny (~4 KB gzipped) and never changes. The actual widget bundle is fetched at runtime from a Mhosaic-controlled manifest URL, so once you've installed the tag below, **you never edit it again** — Mhosaic publishes a new release row and your next page load picks up the new widget bundle.
 
-## 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:
+## Step 1 — Insert one script tag, forever
 
 ```html
 <script
-  src="https://cdn.jsdelivr.net/npm/@mhosaic/feedback@<VERSION>/dist/embed.min.js"
-  integrity="sha384-<HASH>"
+  src="https://cdn.jsdelivr.net/npm/@mhosaic/feedback@1/dist/loader.min.js"
+  integrity="sha384-<LOADER_SRI_HASH>"
   crossorigin="anonymous"
   data-key="pk_proj_…"
   data-endpoint="https://software-factory-3tbbu.ondigitalocean.app"
@@ -20,30 +20,34 @@ The bundle is published to jsDelivr from the npm release. Get the current versio
 ></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.
-
----
+- **Version pin (`@1`):** pin to the LOADER's major version, not a patch version. The loader's API is stable within v1; we'll never break it. Patch updates to the loader propagate via jsDelivr's caches automatically.
+- **SRI:** the loader file is tiny and changes rarely. Get the current SRI from the latest GitHub Release notes for `feedback-tool-mhosaic` (or compute with `curl -s https://cdn.jsdelivr.net/npm/@mhosaic/feedback@1/dist/loader.min.js | openssl dgst -sha384 -binary | openssl base64 -A`).
+- **The widget bundle SRI is NOT in this snippet.** That hash is delivered to the loader at runtime via the manifest endpoint, and the loader injects the widget bundle with its own (current) SRI on the fly. So the bundle is always integrity-checked, but the host never has to update its SRI when the widget version changes.
 
-## 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.
+Drop the 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)
+
+- `script-src https://cdn.jsdelivr.net` (for both the loader and the widget bundle)
+- `connect-src https://software-factory-3tbbu.ondigitalocean.app` (for the manifest endpoint + report submissions)
+- `worker-src 'blob:'` (only if the operator-enabled replay module is in use)
 
 ---
 
-## Step 3 — Wire identify() via the queue API
+## Step 2 — 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:
+The loader exposes a global `window.Feedback` queue function. Drop this **before** the `<script src=…>` tag so the queue exists when the loader initializes:
 
 ```html
 <script>
-  window.Feedback = window.Feedback || function () {
-    (window.Feedback.q = window.Feedback.q || []).push(arguments)
-  }
+  window.Feedback =
+    window.Feedback ||
+    function () {
+      ;(window.Feedback.q = window.Feedback.q || []).push({
+        name: arguments[0],
+        args: Array.prototype.slice.call(arguments, 1),
+      })
+    }
 </script>
 ```
 
@@ -65,20 +69,40 @@ For anonymous-only deployments, pass a stable placeholder id so the FAB still re
 
 ```html
 <script>
-  Feedback('identify', { id: 'anon-' + (localStorage.getItem('anonId') || (localStorage.setItem('anonId', crypto.randomUUID()), localStorage.getItem('anonId'))), name: 'Anonymous' })
+  var anonId =
+    localStorage.getItem('anonId') ||
+    (function () {
+      var id = 'anon-' + crypto.randomUUID()
+      localStorage.setItem('anonId', id)
+      return id
+    })()
+  Feedback('identify', { id: anonId, name: 'Anonymous' })
 </script>
 ```
 
 ---
 
+## How updates work after install
+
+Mhosaic ships a new widget release (new bundle URL + SRI in the Release table). The next time any user loads any page on your site, the loader:
+
+1. Fetches `<endpoint>/api/feedback/v1/widget-manifest/?pk=<your_pk>` (with a 60-second cache header so subsequent page loads in the same minute don't re-fetch).
+2. Reads the response: `{version, bundle_url, sri_hash}`.
+3. Injects `<script src="<bundle_url>" integrity="<sri_hash>" crossorigin="anonymous">` — the browser refuses to run the bundle if its bytes don't match.
+4. Widget mounts. Done.
+
+No host action required. No PRs to merge. No SRI hash to update. The manifest endpoint is the trust root (it's on your Mhosaic backend, served over HTTPS), and SRI on the injected bundle protects against jsDelivr compromise between the manifest lookup and the script load.
+
+If Mhosaic ever needs to disable the widget on your project (kill switch), they flip `Project.widget_enabled = False` in the admin — the next page load gets `{enabled: false}` and the loader silently bails. Your site doesn't crash.
+
+If you need to **pin to a specific widget version** (e.g. before a critical launch), the operator sets `Project.pinned_version = <release>` — your site stays on that exact version regardless of new releases until they unset the pin.
+
+---
+
 ## 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.
+- **No auto-capture modules in the CDN install yet.** `withErrorTracking` / `withReplay` / `withWebVitals` are middleware wrappers that ship via the npm path. The CDN install gives you the bare manual-submit FAB. If the client wants automatic error capture, they have to switch to the bundled (npm) install — drop the `<script>` tag and follow the framework-specific reference instead.
+- **CDN cache lag for new LOADER releases:** new loader patch versions can take up to an hour to propagate across jsDelivr's edge. Bundle updates (the actual widget code) are NOT affected by this — they're pinned with a unique URL per version, so caching is per-version.
 
 ---
 
@@ -86,7 +110,8 @@ For anonymous-only deployments, pass a stable placeholder id so the FAB still re
 
 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)
+1. The loader `<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`)
+3. The bundle gets fetched (DevTools network → a second request to jsDelivr for `widget.min.js`)
+4. The FAB renders (visual check; bottom-right corner)
+5. Submitting a test report lands in `/reports` (see `references/verify-install.md`)

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

@@ -23,7 +23,7 @@ In `app/root.tsx`, add a loader that surfaces the values to the client window:
 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 { createFeedback } from '@mhosaic/feedback/loader'
 import { withErrorTracking } from '@mhosaic/feedback/error-tracking'
 import { withReplay } from '@mhosaic/feedback/replay'
 import { withWebVitals } from '@mhosaic/feedback/webvitals'

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

@@ -25,7 +25,7 @@ Edit `src/routes/+layout.svelte`:
 <script lang="ts">
   import { onMount } from 'svelte'
   import { env } from '$env/dynamic/public'
-  import { createFeedback } from '@mhosaic/feedback'
+  import { createFeedback } from '@mhosaic/feedback/loader'
   import { withErrorTracking } from '@mhosaic/feedback/error-tracking'
   import { withReplay } from '@mhosaic/feedback/replay'
   import { withWebVitals } from '@mhosaic/feedback/webvitals'