@mhosaic/feedback-cli 0.14.1 → 0.17.0

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.** `withErrorTracking` / `withReplay` / `withWebVitals` are middleware wrappers that ship via the npm path — and on that path **error-tracking is now on by default** (uncaught errors + unhandled rejections auto-file as synthetic reports). The CDN `<script>` install is the bare manual-submit FAB only; it has no error-tracking. 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

@@ -17,16 +17,14 @@ 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:
+In `app/root.tsx`, add a loader that surfaces the values to the client window. Error-tracking is **on by default** — the mount wraps `withErrorTracking` so uncaught errors + unhandled rejections auto-file as synthetic reports:
 
 ```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 { 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 async function loader({ request }: LoaderFunctionArgs) {
   return json({
@@ -42,11 +40,11 @@ export default function App() {
   useEffect(() => {
     const { FEEDBACK_API_KEY, FEEDBACK_ENDPOINT } = data.ENV
     if (!FEEDBACK_API_KEY || !FEEDBACK_ENDPOINT) return
-    withErrorTracking(withReplay(withWebVitals(createFeedback({
+    withErrorTracking(createFeedback({
       apiKey: FEEDBACK_API_KEY,
       endpoint: FEEDBACK_ENDPOINT,
       env: process.env.NODE_ENV === 'development' ? 'dev' : 'prod',
-    }))))
+    }))
   }, [data.ENV])
 
   return (
@@ -66,7 +64,34 @@ export default function App() {
 }
 ```
 
-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.
+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.
+
+---
+
+## 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 the `useEffect` above with:
+
+```typescript
+import { withReplay } from '@mhosaic/feedback/replay'
+import { withWebVitals } from '@mhosaic/feedback/webvitals'
+
+withReplay(
+  withWebVitals(
+    withErrorTracking(
+      createFeedback({
+        apiKey: FEEDBACK_API_KEY,
+        endpoint: FEEDBACK_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.
 
 ---
 

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

@@ -19,16 +19,14 @@ SvelteKit uses Vite's env system but with the `PUBLIC_` prefix for client-readab
 
 ## Step 2 — Mount in `+layout.svelte`
 
-Edit `src/routes/+layout.svelte`:
+Edit `src/routes/+layout.svelte`. Error-tracking is **on by default** — the mount wraps `withErrorTracking` so uncaught errors + unhandled rejections auto-file as synthetic reports:
 
 ```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'
 
   let fb: ReturnType<typeof createFeedback> | undefined
 
@@ -37,9 +35,7 @@ Edit `src/routes/+layout.svelte`:
     const endpoint = env.PUBLIC_FEEDBACK_ENDPOINT
     if (!apiKey || !endpoint) return
     fb = withErrorTracking(
-      withReplay(
-        withWebVitals(createFeedback({ apiKey, endpoint, env: import.meta.env.PROD ? 'prod' : 'dev' }))
-      )
+      createFeedback({ apiKey, endpoint, env: import.meta.env.PROD ? 'prod' : 'dev' })
     )
   })
 </script>
@@ -51,6 +47,30 @@ Edit `src/routes/+layout.svelte`:
 
 ---
 
+## 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:
+
+```svelte
+<script lang="ts">
+  import { withReplay } from '@mhosaic/feedback/replay'
+  import { withWebVitals } from '@mhosaic/feedback/webvitals'
+
+  // inside onMount, replacing the default wrap:
+  fb = 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 assign 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()
 
 If your app uses SvelteKit's `+layout.server.ts` to return the user, surface that to the client via the layout `data` and watch it with a `$:` block:

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

@@ -7,6 +7,7 @@ The CLI auto-wires this configuration. Your job is to **verify** the auto-wrap l
 ## After `mhosaic-feedback init` ran
 
 The CLI should have:
+
 1. Installed `@mhosaic/feedback`
 2. Written `.env.local` with `VITE_FEEDBACK_API_KEY=…` and `VITE_FEEDBACK_ENDPOINT=…`
 3. Wrapped `src/main.tsx` with `<FeedbackProvider>` between the marker comments
@@ -15,7 +16,7 @@ Read `src/main.tsx` and confirm you see:
 
 ```typescript
 // === mhosaic-feedback:import:start ===
-import { FeedbackProvider } from '@mhosaic/feedback/react'
+import { FeedbackProvider } from '@mhosaic/feedback/loader/react'
 // === mhosaic-feedback:import:end ===
 
 // ... existing imports
@@ -39,37 +40,45 @@ If any of those markers is missing, the auto-wrap failed (rare — usually becau
 
 ---
 
-## Optional: auto-capture middleware
+## Auto-capture modules
+
+`<FeedbackProvider>` arms **error-tracking by default** — the `errorTracking` prop defaults to `true`, so uncaught errors + unhandled rejections auto-file as synthetic reports with nothing extra to wire. Opt out (collect-on-consent posture) with:
+
+```tsx
+<FeedbackProvider apiKey={apiKey} endpoint={endpoint} errorTracking={false}>
+```
 
-The default wrap uses `<FeedbackProvider>`, which doesn't expose the wrapper-chain pattern. To add `withErrorTracking` / `withReplay` / `withWebVitals` on a Vite+React project, replace `<FeedbackProvider>` with a manual `createFeedback()` call in a small client-only module:
+To also add **web-vitals / replay** (still opt-in, heavier), drop the provider's auto-wrap and build the instance manually in a small client-only module:
 
 ```typescript
 // src/feedback.ts
-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 const fb = withErrorTracking(
-  withReplay(
-    withWebVitals(createFeedback({
-      apiKey: import.meta.env.VITE_FEEDBACK_API_KEY,
-      endpoint: import.meta.env.VITE_FEEDBACK_ENDPOINT,
-      env: import.meta.env.PROD ? 'prod' : 'dev',
-    }))
-  )
+export const fb = withReplay(
+  withWebVitals(
+    withErrorTracking(
+      createFeedback({
+        apiKey: import.meta.env.VITE_FEEDBACK_API_KEY,
+        endpoint: import.meta.env.VITE_FEEDBACK_ENDPOINT,
+        env: import.meta.env.PROD ? 'prod' : 'dev',
+      }),
+    ),
+  ),
 )
 ```
 
 Then in `src/main.tsx` replace the `<FeedbackProvider>` wrap with an import of `./feedback` at the top — so the side effect (widget mount + auto-capture) runs once at module load:
 
 ```typescript
-import './feedback'  // mounts the widget + arms error/replay/webvitals
+import './feedback' // mounts the widget + arms error/replay/webvitals
 ```
 
 And remove the `<FeedbackProvider>` JSX wrap. The widget mounts itself to its own Shadow DOM container; there's no React provider needed unless you want to call `useFeedback()` from components.
 
-If you do want `useFeedback()`, keep `<FeedbackProvider>` *and* the manual `createFeedback()` — they cooperate. See `packages/core/src/react/FeedbackProvider.tsx` for the contract.
+If you do want `useFeedback()`, keep `<FeedbackProvider>` _and_ the manual `createFeedback()` — they cooperate. See `packages/core/src/react/FeedbackProvider.tsx` for the contract.
 
 ---
 

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

@@ -17,25 +17,21 @@ VITE_FEEDBACK_ENDPOINT=https://software-factory-3tbbu.ondigitalocean.app
 
 ## Step 2 — Initialize at app boot
 
-Edit `src/main.ts`:
+Edit `src/main.ts`. Error-tracking is **on by default** — the boot wraps `withErrorTracking` so uncaught errors + unhandled rejections auto-file as synthetic reports:
 
 ```typescript
 import { createApp } from 'vue'
 import App from './App.vue'
 
-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 fb = withErrorTracking(
-  withReplay(
-    withWebVitals(createFeedback({
-      apiKey: import.meta.env.VITE_FEEDBACK_API_KEY,
-      endpoint: import.meta.env.VITE_FEEDBACK_ENDPOINT,
-      env: import.meta.env.PROD ? 'prod' : 'dev',
-    }))
-  )
+  createFeedback({
+    apiKey: import.meta.env.VITE_FEEDBACK_API_KEY,
+    endpoint: import.meta.env.VITE_FEEDBACK_ENDPOINT,
+    env: import.meta.env.PROD ? 'prod' : 'dev',
+  }),
 )
 
 const app = createApp(App)
@@ -51,6 +47,33 @@ The widget mounts itself to its own Shadow DOM container outside Vue's root. Cal
 
 ---
 
+## 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: import.meta.env.VITE_FEEDBACK_API_KEY,
+        endpoint: import.meta.env.VITE_FEEDBACK_ENDPOINT,
+        env: import.meta.env.PROD ? 'prod' : 'dev',
+      }),
+    ),
+  ),
+)
+```
+
+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 assign 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()
 
 Use the Supabase / Firebase / custom JWT recipe from `references/identify-snippets.md`. Vue 3's `watchEffect` is the idiomatic place to call `fb.identify()` from a Pinia/Vuex store or a composable:

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

@@ -4,6 +4,36 @@ You are guiding a teammate through installing the @mhosaic/feedback widget into
 
 ---
 
+## CRITICAL: API key handling — read this before doing anything
+
+The `pk_proj_…` public widget key is **NOT safe to commit to git**. Even though it's a "public" key (it ends up in the browser-side bundle at runtime), committing it is wrong for several concrete reasons:
+
+- Git history is permanent. If the key needs rotation (compromise, audit finding, project transfer), you can't actually remove it — every clone of the repo still has it.
+- GitHub's secret scanners flag any `pk_proj_…` literal in a public repo and notify the org. Even private repos can leak via accidental fork or contributor offboarding.
+- The key is tied to a specific project's `allowed_origins` allow-list — if it leaks and gets used from a domain the operator forgot to lock down, you get garbage reports from the wild.
+
+**Rules. NO exceptions.**
+
+1. **NEVER commit the API key to any tracked file.** Not `.env`, not `.env.example`, not `config.ts`, not a comment, not a README. Not even "temporarily, I'll rotate later."
+2. **If the user asks "can I commit this?" — the answer is NO.** Don't rationalize "it's public anyway" or "it's bundled into the JS at build time so what's the harm." Both are true; neither matters. Refer them to this section.
+3. **If the host's deploy pipeline excludes `.env.local`** (common with Docker builds — Dockerfile `COPY` of `frontend/` typically skips `.env*.local` via `.dockerignore`, or the build context only includes specific files), the key MUST come from **deploy-platform env vars** (DO App Platform > component > Environment Variables; Vercel > Project Settings > Env Vars; etc.), NOT from a tracked file. Pause and tell the user. Do NOT switch to `.env` (which IS tracked) as a workaround.
+4. **`.env.local` (or framework equivalent) must be in `.gitignore`.** The CLI's `init` command verifies this. If you're editing files manually because the CLI failed, you verify it yourself before writing the key anywhere.
+5. **The endpoint URL (`https://software-factory-…`) IS safe to commit** — it's a public URL with no auth on its surface. Only the API key matters.
+
+**Per-environment-variable destination table** (which file gets the key for which scenario):
+
+| Scenario                                                   | API key goes in                                                                    | Tracked by git?                 |
+| ---------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------- |
+| Local dev, Vite/Next/Nuxt/etc. without Docker              | `.env.local`                                                                       | No (gitignored)                 |
+| Local dev with Docker Compose (host-side build)            | `.env.local`                                                                       | No                              |
+| Production deploy (DO App Platform, Vercel, Netlify, etc.) | Platform env vars UI                                                               | No (lives only on the platform) |
+| Docker build where `.env.local` is excluded from context   | Platform env vars (passed in at build time via `--build-arg` or runtime injection) | No                              |
+| CI build for staging/prod                                  | CI secret (GH Actions secrets, etc.), surfaced as env var to the build             | No                              |
+
+If a scenario isn't in the table and you're unsure, **stop and ask the operator**. Do not improvise toward a tracked file.
+
+---
+
 ## Step 1 — Parse the handoff payload
 
 Ask the user to paste the handoff payload as plain Markdown. Extract:
@@ -19,7 +49,17 @@ If the user can't find the payload, walk them through asking the operator for it
 
 ## Step 2 — Classify the host app
 
-`Read` the user's `package.json`. Three branches:
+Before anything else, **confirm the cwd is actually the target.** This is the most common operator footgun: someone runs `/integrate-feedback` inside `feedback-tool-mhosaic` (where the skill is conveniently invokable) and the consumer phase silently writes the widget into our own monorepo. Two cheap checks:
+
+- Read `package.json`. If its `name` is `@mhosaic/feedback-tool-mhosaic`, `@mhosaic/feedback`, `@mhosaic/feedback-admin`, `@mhosaic/feedback-cli`, or contains the literal string `mhosaic/feedback`: **STOP**. The user is inside our own monorepo, not their host app. Tell them:
+
+  > "Looks like we're inside `feedback-tool-mhosaic` itself. The consumer install writes to the current directory; running it here would install the widget into our own monorepo. Either pass `--cwd <target-app-path>` to the CLI, or close Claude and re-open it inside the target app's root, then re-run `/integrate-feedback` and pick 'Install (consumer)'."
+
+  Wait for the user to confirm they've moved before continuing.
+
+- If `package.json` is missing AND the cwd contains `packages/cli/skills/integrate-feedback/` (we're inside the skill's own source), same stop-and-redirect.
+
+Now `Read` the user's `package.json`. Three branches:
 
 1. **package.json exists with `dependencies`** → continue to Step 3 (framework detection).
 2. **No package.json, but `index.html` / `templates/` / `app/views/` / similar template directory exists** → this is a non-JS host app (Django, Rails, Hugo, plain HTML/static site, etc.). Skip Steps 3-5 and go directly to **`references/consumer-install-plain.md`** (CDN `<script>` flow). Tell the user: "I see this isn't a JS/TS app — the CDN path is the right one. The npm-package + framework-snippet flow doesn't apply."
@@ -29,22 +69,22 @@ If the user can't find the payload, walk them through asking the operator for it
 
 ## Step 3 — Detect the framework
 
-The CLI does framework detection itself, but you should know the result *before* running it so you can decide which post-install snippet (if any) the user needs to apply.
+The CLI does framework detection itself, but you should know the result _before_ running it so you can decide which post-install snippet (if any) the user needs to apply.
 
 Read `package.json`'s `dependencies` + `devDependencies` and classify:
 
-| Found | Framework | Reference doc | CLI auto-wires entry? |
-|---|---|---|---|
-| `vite` + `react` + `@vitejs/plugin-react` | `vite-react` | `consumer-install-vite.md` | ✅ yes |
-| `next` | `nextjs` (App or Pages Router — sniff `app/` vs `pages/`) | `consumer-install-next.md` | ❌ paste snippet |
-| `nuxt` | `nuxt` | `consumer-install-nuxt.md` | ❌ paste snippet |
-| `astro` | `astro` | `consumer-install-astro.md` | ❌ paste snippet |
-| `@remix-run/react` | `remix` | `consumer-install-remix.md` | ❌ paste snippet |
-| `vue` ≥ 3 (no `nuxt`) | `vue` | `consumer-install-vue.md` | ❌ paste snippet |
-| `@sveltejs/kit` | `sveltekit` | `consumer-install-svelte.md` | ❌ paste snippet |
-| none of the above | `plain` / `unknown` | `consumer-install-plain.md` | ❌ CDN snippet |
+| Found                                     | Framework                                                 | Reference doc                | CLI auto-wires entry? |
+| ----------------------------------------- | --------------------------------------------------------- | ---------------------------- | --------------------- |
+| `vite` + `react` + `@vitejs/plugin-react` | `vite-react`                                              | `consumer-install-vite.md`   | ✅ yes                |
+| `next`                                    | `nextjs` (App or Pages Router — sniff `app/` vs `pages/`) | `consumer-install-next.md`   | ❌ paste snippet      |
+| `nuxt`                                    | `nuxt`                                                    | `consumer-install-nuxt.md`   | ❌ paste snippet      |
+| `astro`                                   | `astro`                                                   | `consumer-install-astro.md`  | ❌ paste snippet      |
+| `@remix-run/react`                        | `remix`                                                   | `consumer-install-remix.md`  | ❌ paste snippet      |
+| `vue` ≥ 3 (no `nuxt`)                     | `vue`                                                     | `consumer-install-vue.md`    | ❌ paste snippet      |
+| `@sveltejs/kit`                           | `sveltekit`                                               | `consumer-install-svelte.md` | ❌ paste snippet      |
+| none of the above                         | `plain` / `unknown`                                       | `consumer-install-plain.md`  | ❌ CDN snippet        |
 
-Order matters: check for `nuxt` *before* generic `vue`, since Nuxt apps have both. Same for `astro` vs the underlying renderer (Astro apps can also have React/Vue/Svelte).
+Order matters: check for `nuxt` _before_ generic `vue`, since Nuxt apps have both. Same for `astro` vs the underlying renderer (Astro apps can also have React/Vue/Svelte).
 
 Tell the user which framework you detected. Confirm with `AskUserQuestion` (especially if Next.js, since App vs Pages Router branches differently).
 
@@ -62,12 +102,14 @@ npx @mhosaic/feedback-cli@latest init \
 ```
 
 This will:
+
 - `npm install @mhosaic/feedback` (using the project's package manager)
 - Write `.env.local` with `VITE_FEEDBACK_API_KEY=…` + `VITE_FEEDBACK_ENDPOINT=…` (Vite-flavored names; rename per framework if Next/Vue/etc. — see framework references)
 - Ensure `.env.local` is in `.gitignore`
 - If `vite-react`: auto-wrap `src/main.tsx` with `<FeedbackProvider>`
 
 Surface the CLI's output verbatim. If install fails, stop and read the error message; common causes:
+
 - No internet
 - Lockfile conflict (offer to delete `pnpm-lock.yaml` / `yarn.lock` / `package-lock.json` and retry)
 - Wrong directory (no `package.json`)
@@ -86,6 +128,7 @@ Open the per-framework reference document and follow it verbatim:
 - Plain HTML / CDN: `consumer-install-plain.md`
 
 Each reference doc gives:
+
 1. The env-var prefix (e.g. `NEXT_PUBLIC_FEEDBACK_API_KEY` for Next.js — the CLI's default `VITE_FEEDBACK_*` needs renaming)
 2. The entry-point snippet to paste (with import + provider/init call)
 3. Where to put it (exact file path)
@@ -103,31 +146,32 @@ If you can't detect the auth provider from `package.json`, ask the user explicit
 
 ---
 
-## Step 7 — (Optional but recommended) Wire the auto-capture modules
+## Step 7 — Auto-capture modules (error-tracking is on by default)
+
+**Error-tracking ships on by default.** `<FeedbackProvider>` arms it automatically (the `errorTracking` prop defaults to `true`), and every non-React snippet in this skill wraps `withErrorTracking` by default. It auto-files synthetic reports for `window.onerror` + `unhandledrejection` — this is the telemetry that feeds the platform's frontend-error Issue scan, so **leave it on** unless the consumer has a specific reason not to. There's nothing to wire for the default case.
+
+Two heavier modules stay opt-in (more overhead / more sensitive data):
 
 `AskUserQuestion`:
-- question: `Wire the auto-capture modules?`
+
+- question: `Add the heavier auto-capture modules? (error-tracking is already on)`
 - options:
-  - `Yes — all three (error-tracking, web-vitals, replay)`, description: `Captures runtime errors, Core Web Vitals, and session replay. ~30 KiB gzip overhead.`
-  - `Yes — error-tracking only`, description: `Smallest add. Auto-files synthetic reports for window.onerror + unhandledrejection.`
-  - `No — keep it minimal`, description: `Just the manual-submit FAB.`
+  - `No — error-tracking only (recommended)`, description: `Keep the default. Smallest footprint.`
+  - `Add web-vitals`, description: `Core Web Vitals (LCP/INP/CLS) as telemetry. Small.`
+  - `Add web-vitals + replay`, description: `Also session replay (rrweb), ~30 KiB gzip — captures DOM, confirm the privacy posture first.`
 
-For each `Yes`, modify the consumer's widget init to chain the wrappers. The pattern:
+To add the opt-in modules, chain their wrappers around the instance (error-tracking innermost so it arms first):
 
 ```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'
 
-const fb = withErrorTracking(
-  withReplay(
-    withWebVitals(createFeedback({ apiKey, endpoint }))
-  )
-)
+const fb = withReplay(withWebVitals(withErrorTracking(createFeedback({ apiKey, endpoint }))))
 ```
 
-The CLI's auto-wrap uses `<FeedbackProvider>` (a React-specific helper) — for non-Vite-React frameworks the snippet above is the direct equivalent. Match the framework's import style (CommonJS vs ESM, top-level await vs inside an effect).
+**Opting out of error-tracking** (collect-on-consent posture): pass `<FeedbackProvider errorTracking={false}>`, or on the `createFeedback` path simply omit the `withErrorTracking` wrap. Note it POSTs error messages + stack traces — fine for the vast majority of apps, but flag it if the consumer's error strings can carry end-user PII.
 
 ---
 
@@ -140,12 +184,14 @@ npx @mhosaic/feedback-cli@latest verify \
 ```
 
 This is a lightweight check; it confirms:
+
 - `.env.local` has the right shape
 - The endpoint resolves and responds
 - CORS allows the consumer's origin
 - The public key is accepted (POSTs a `[mhosaic-feedback verify]` synthetic report)
 
 If anything is red, the verify command prints a hint. Common hints:
+
 - `add this origin to the project's allowed_origins (admin SPA: Edit project)` → operator needs to add the dev/prod origin.
 - `key invalid or revoked` → operator needs to mint a new key.
 
@@ -174,10 +220,11 @@ Summarize for the user:
 - Widget installed ✓
 - FAB renders ✓
 - Smoke-test report received ✓
-- Optional modules wired: [error-tracking / replay / web-vitals / none]
+- Error-tracking: on by default ✓ (or `errorTracking={false}` if the consumer opted out) · extra modules wired: [web-vitals / replay / none]
 - Next: deploy to staging, add the staging URL to `allowed_origins` (operator action — DM them the URL)
 
 Encourage them to:
+
 - Commit the change (sans `.env.local`)
 - Tell the operator the smoke test passed
 - Delete the smoke-test reports from `/reports` in admin once it lands

package/skills/integrate-feedback/references/identify-snippets.md

@@ -14,7 +14,7 @@ The widget's FAB is hidden until `fb.identify()` is called with a non-empty `id`
 
 import { useEffect } from 'react'
 import { useAuth0 } from '@auth0/auth0-react'
-import { useFeedback } from '@mhosaic/feedback/react'
+import { useFeedback } from '@mhosaic/feedback/loader/react'
 
 export function FeedbackIdentity() {
   const { user, isAuthenticated, isLoading } = useAuth0()
@@ -40,7 +40,7 @@ Mount `<FeedbackIdentity />` once inside both `<Auth0Provider>` and `<FeedbackPr
 ```tsx
 import { useEffect } from 'react'
 import { useUser } from '@clerk/clerk-react'
-import { useFeedback } from '@mhosaic/feedback/react'
+import { useFeedback } from '@mhosaic/feedback/loader/react'
 
 export function FeedbackIdentity() {
   const { isLoaded, isSignedIn, user } = useUser()
@@ -118,7 +118,7 @@ Place after `initializeApp()` and `createFeedback()`. The callback fires immedia
 
 import { useEffect } from 'react'
 import { useSession } from 'next-auth/react'
-import { useFeedback } from '@mhosaic/feedback/react'
+import { useFeedback } from '@mhosaic/feedback/loader/react'
 
 export function FeedbackIdentity() {
   const { data: session, status } = useSession()