@mhosaic/feedback-cli 0.14.1 → 0.17.0

package/skills/integrate-feedback/SKILL.md

@@ -1,118 +1,139 @@
 ---
 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?"**
 
-## Step 0.5: Pre-flight (operator mode only)
+- 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.
 
-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.
+**"What permissions do I need on the backend?"**
 
-Check: call `mcp__claude-in-chrome__tabs_context_mcp` once. Possible outcomes:
+- 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.
 
-- **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:
+**"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."
 
-  > "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."
+**"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.
 
-  Stop. Don't continue operator mode without MCP.
+**"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.
 
-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."
+**"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.
 
----
+**"External client vs internal Mhosaic app?"**
 
-## Operator mode — provisioning
+- 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.
 
-**Goal:** end-to-end, produce a Markdown "handoff payload" the teammate can paste into Claude Code (or follow manually) to install the widget.
+**"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).
 
-**Read** the full step-by-step procedure at:
+**"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.
 
-- `references/operator-provision.md`
+---
 
-The procedure walks through:
+## Step 0 — Identify the phase
 
-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
+`AskUserQuestion`:
 
-**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.
+- 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.`
 
-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).
+Branch on the answer.
 
 ---
 
-## Consumer mode — installing
+## Step 0.5 — Pre-flight
 
-**Goal:** end-to-end, the widget loads on the host app and a smoke-test report lands in the admin.
+**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:
 
-**Read** the framework-aware install procedure at:
+> "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)."
 
-- `references/consumer-install.md`
+Stop. Don't continue without MCP.
+
+**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:
+
+> "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.
+
+---
 
-The procedure walks through:
+## Operator phase
 
-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
+Read **`references/operator-provision.md`** and follow it step by step:
 
-The smoke-test workflow lives at:
+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. **(Optional, gated)** Offer server-log forwarding into the Observabilité tab: confirm the client is DO-hosted + pass the governance gate (internal/dogfood or signed DPA), call `POST /projects/<id>/observability/enable/`, then hand the client's DevOps a `log_destinations` block for their DO app spec. Details in `references/operator-provision.md` Step 5.5.
+8. 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`.
 
-- `references/verify-install.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.
 
 ---
 
-## Principles to follow
+## Consumer 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/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
@@ -122,7 +143,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 \
@@ -130,23 +152,26 @@ 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

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

@@ -19,7 +19,7 @@ Astro uses Vite under the hood. Env vars meant for the browser need the `PUBLIC_
 
 ## 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 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. Error-tracking is **on by default** — the script wraps `withErrorTracking` so uncaught errors + unhandled rejections auto-file as synthetic reports:
 
 ```astro
 ---
@@ -33,17 +33,15 @@ const endpoint = import.meta.env.PUBLIC_FEEDBACK_ENDPOINT
     <slot />
 
     <script>
-      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'
 
       const apiKey = import.meta.env.PUBLIC_FEEDBACK_API_KEY
       const endpoint = import.meta.env.PUBLIC_FEEDBACK_ENDPOINT
       if (apiKey && endpoint) {
-        withErrorTracking(withReplay(withWebVitals(createFeedback({
+        withErrorTracking(createFeedback({
           apiKey, endpoint, env: import.meta.env.PROD ? 'prod' : 'dev',
-        }))))
+        }))
       }
     </script>
   </body>
@@ -54,6 +52,28 @@ Astro will bundle the script and run it on the client. The widget mounts to its
 
 ---
 
+## Optional — add web-vitals / replay
+
+`withWebVitals` and `withReplay` stay **opt-in** (heavier / more sensitive). Add them inside the `<script>` block by chaining around the default instance, error-tracking innermost so it arms first:
+
+```astro
+<script>
+  import { withReplay } from '@mhosaic/feedback/replay'
+  import { withWebVitals } from '@mhosaic/feedback/webvitals'
+
+  // replacing the default wrap:
+  withReplay(withWebVitals(withErrorTracking(createFeedback({
+    apiKey, endpoint, env: import.meta.env.PROD ? 'prod' : 'dev',
+  }))))
+</script>
+```
+
+Replay (rrweb, ~30 KiB gzip) captures DOM — confirm the privacy posture before enabling it.
+
+**Opting out of error-tracking** (collect-on-consent posture): omit the `withErrorTracking` wrap and pass the bare `createFeedback(...)` instance. Note error-tracking POSTs error messages + stack traces — fine for most apps, but flag it if your error strings can carry end-user PII.
+
+---
+
 ## Step 3 — Wire identify()
 
 How you do this depends on what auth backs your Astro site:

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

@@ -21,16 +21,14 @@ 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`:
+Create a new file `app/components/FeedbackMount.tsx`. Error-tracking is **on by default** — the default mount wraps `withErrorTracking` so uncaught errors + unhandled rejections auto-file as synthetic reports:
 
 ```typescript
 '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'
 
 export function FeedbackMount() {
   useEffect(() => {
@@ -39,9 +37,11 @@ export function FeedbackMount() {
     if (!apiKey || !endpoint) return
 
     withErrorTracking(
-      withReplay(
-        withWebVitals(createFeedback({ apiKey, endpoint, env: process.env.NODE_ENV === 'development' ? 'dev' : 'prod' }))
-      )
+      createFeedback({
+        apiKey,
+        endpoint,
+        env: process.env.NODE_ENV === 'development' ? 'dev' : 'prod',
+      }),
     )
   }, [])
   return null
@@ -71,24 +71,22 @@ The `'use client'` directive in `FeedbackMount.tsx` is critical — it tells Nex
 
 ## Step 3 — Pages Router (Next.js 12 or App-Router-free 13+)
 
-Edit `pages/_app.tsx`:
+Edit `pages/_app.tsx` (same default — `withErrorTracking` on by default):
 
 ```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'
 
 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({
+    withErrorTracking(createFeedback({
       apiKey, endpoint, env: process.env.NODE_ENV === 'development' ? 'dev' : 'prod'
-    }))))
+    }))
   }, [])
   return <Component {...pageProps} />
 }
@@ -96,6 +94,33 @@ export default function App({ Component, pageProps }: AppProps) {
 
 ---
 
+## Optional — add web-vitals / replay
+
+`withWebVitals` and `withReplay` stay **opt-in** (heavier / more sensitive). Add them by chaining around the default instance, error-tracking innermost so it arms first. Import the extra wrappers and replace the `withErrorTracking(createFeedback(...))` call (in either router's snippet) with:
+
+```typescript
+import { withReplay } from '@mhosaic/feedback/replay'
+import { withWebVitals } from '@mhosaic/feedback/webvitals'
+
+withReplay(
+  withWebVitals(
+    withErrorTracking(
+      createFeedback({
+        apiKey,
+        endpoint,
+        env: process.env.NODE_ENV === 'development' ? 'dev' : 'prod',
+      }),
+    ),
+  ),
+)
+```
+
+Replay (rrweb, ~30 KiB gzip) captures DOM — confirm the privacy posture before enabling it.
+
+**Opting out of error-tracking** (collect-on-consent posture): omit the `withErrorTracking` wrap and pass the bare `createFeedback(...)` instance. Note error-tracking POSTs error messages + stack traces — fine for most apps, but flag it if your error strings can carry end-user PII.
+
+---
+
 ## 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()`.
@@ -107,7 +132,7 @@ If you're using NextAuth, the cleanest pattern is to add a `<FeedbackIdentity />
 ## 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.
+- **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.
 

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

@@ -34,24 +34,20 @@ Nuxt auto-binds `NUXT_PUBLIC_*` env vars to the matching `runtimeConfig.public.*
 
 ## 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):
+Create `plugins/feedback.client.ts` (the `.client.ts` suffix tells Nuxt to bundle this only for the browser, not SSR). Error-tracking is **on by default** — the plugin wraps `withErrorTracking` so uncaught errors + unhandled rejections auto-file as synthetic reports:
 
 ```typescript
-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'
 
 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',
-      }))
-    )
+    createFeedback({
+      apiKey: config.public.feedbackApiKey as string,
+      endpoint: config.public.feedbackEndpoint as string,
+      env: process.dev ? 'dev' : 'prod',
+    }),
   )
   return { provide: { feedback: fb } }
 })
@@ -61,6 +57,33 @@ Now `useNuxtApp().$feedback` is available across the app.
 
 ---
 
+## Optional — add web-vitals / replay
+
+`withWebVitals` and `withReplay` stay **opt-in** (heavier / more sensitive). Add them by chaining around the default instance, error-tracking innermost so it arms first:
+
+```typescript
+import { withReplay } from '@mhosaic/feedback/replay'
+import { withWebVitals } from '@mhosaic/feedback/webvitals'
+
+const fb = withReplay(
+  withWebVitals(
+    withErrorTracking(
+      createFeedback({
+        apiKey: config.public.feedbackApiKey as string,
+        endpoint: config.public.feedbackEndpoint as string,
+        env: process.dev ? 'dev' : 'prod',
+      }),
+    ),
+  ),
+)
+```
+
+Replay (rrweb, ~30 KiB gzip) captures DOM — confirm the privacy posture before enabling it.
+
+**Opting out of error-tracking** (collect-on-consent posture): omit the `withErrorTracking` wrap and provide the bare `createFeedback(...)` instance. Note error-tracking POSTs error messages + stack traces — fine for most apps, but flag it if your error strings can carry end-user PII.
+
+---
+
 ## 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:
@@ -68,7 +91,7 @@ Nuxt's auth is whatever you bolt on (sidebase/nuxt-auth, custom, Supabase, etc.)
 ```vue
 <!-- app.vue -->
 <script setup lang="ts">
-import { useAuthStore } from '~/stores/auth'  // adapt to your auth source
+import { useAuthStore } from '~/stores/auth' // adapt to your auth source
 
 const auth = useAuthStore()
 const { $feedback } = useNuxtApp()