@mhosaic/feedback-cli 0.13.0 → 0.14.1

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

@@ -0,0 +1,87 @@
+# Consumer install — SvelteKit
+
+The CLI's auto-wrap is React-only; for SvelteKit you paste the snippet into the root layout.
+
+---
+
+## Step 1 — Env vars
+
+SvelteKit uses Vite's env system but with the `PUBLIC_` prefix for client-readable values. Open `.env.local` and rename:
+
+```diff
+- VITE_FEEDBACK_API_KEY=pk_proj_…
+- VITE_FEEDBACK_ENDPOINT=https://…
++ PUBLIC_FEEDBACK_API_KEY=pk_proj_…
++ PUBLIC_FEEDBACK_ENDPOINT=https://…
+```
+
+---
+
+## Step 2 — Mount in `+layout.svelte`
+
+Edit `src/routes/+layout.svelte`:
+
+```svelte
+<script lang="ts">
+  import { onMount } from 'svelte'
+  import { env } from '$env/dynamic/public'
+  import { createFeedback } from '@mhosaic/feedback'
+  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
+
+  onMount(() => {
+    const apiKey = env.PUBLIC_FEEDBACK_API_KEY
+    const endpoint = env.PUBLIC_FEEDBACK_ENDPOINT
+    if (!apiKey || !endpoint) return
+    fb = withErrorTracking(
+      withReplay(
+        withWebVitals(createFeedback({ apiKey, endpoint, env: import.meta.env.PROD ? 'prod' : 'dev' }))
+      )
+    )
+  })
+</script>
+
+<slot />
+```
+
+`onMount` is client-only by definition in Svelte — no SSR import needed.
+
+---
+
+## 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:
+
+```svelte
+<script lang="ts">
+  import { page } from '$app/stores'
+  // ... existing imports
+
+  $: if (fb) {
+    const user = $page.data.user
+    if (user) fb.identify({ id: user.id, email: user.email, name: user.name })
+    else fb.identify({ id: '', email: '', name: '' })
+  }
+</script>
+```
+
+For Supabase/Firebase/custom JWT setups, use the snippet from `references/identify-snippets.md` and call it inside the same `onMount` that creates `fb`.
+
+---
+
+## Gotchas
+
+- **SSR + window:** the widget touches `window`. Always init inside `onMount` (or after `if (browser) {…}` from `$app/environment`). Never at module top-level.
+- **`$env/dynamic/public` vs `$env/static/public`:** dynamic reads at runtime (works with multiple deploy targets); static inlines at build (better for tree-shaking). Either works for the widget — pick the one your app already uses.
+- **adapter-static / SSG:** the widget hydrates at runtime, so SSG-rendered pages render without the FAB until JS hydrates. Same caveat as Next.js.
+
+---
+
+## Verifying
+
+```bash
+npx @mhosaic/feedback-cli@latest verify --origin http://localhost:5173 --with-test-report
+```

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

@@ -0,0 +1,100 @@
+# Consumer install — Vite + React
+
+The CLI auto-wires this configuration. Your job is to **verify** the auto-wrap landed, not write the snippet yourself.
+
+---
+
+## 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
+
+Read `src/main.tsx` and confirm you see:
+
+```typescript
+// === mhosaic-feedback:import:start ===
+import { FeedbackProvider } from '@mhosaic/feedback/react'
+// === mhosaic-feedback:import:end ===
+
+// ... existing imports
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  {/* === mhosaic-feedback:wrap:start === */}
+  <FeedbackProvider
+    apiKey={import.meta.env.VITE_FEEDBACK_API_KEY}
+    endpoint={import.meta.env.VITE_FEEDBACK_ENDPOINT}
+    env="prod"
+  >
+  {/* === mhosaic-feedback:wrap:end === */}
+    <App />
+  {/* === mhosaic-feedback:wrap:start === */}
+  </FeedbackProvider>
+  {/* === mhosaic-feedback:wrap:end === */}
+)
+```
+
+If any of those markers is missing, the auto-wrap failed (rare — usually because the entry file's structure didn't match the regex). Run `npx @mhosaic/feedback-cli@latest doctor` to confirm. If doctor reports a wiring miss, paste the snippet above into `src/main.tsx` manually, or open an issue on the feedback-tool-mhosaic repo.
+
+---
+
+## Optional: auto-capture middleware
+
+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:
+
+```typescript
+// src/feedback.ts
+import { createFeedback } from '@mhosaic/feedback'
+import { withErrorTracking } from '@mhosaic/feedback/error-tracking'
+import { withReplay } from '@mhosaic/feedback/replay'
+import { withWebVitals } from '@mhosaic/feedback/webvitals'
+
+export 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',
+    }))
+  )
+)
+```
+
+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
+```
+
+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.
+
+---
+
+## Env vars
+
+```
+VITE_FEEDBACK_API_KEY=pk_proj_…
+VITE_FEEDBACK_ENDPOINT=https://software-factory-3tbbu.ondigitalocean.app
+```
+
+Vite inlines `import.meta.env.VITE_*` at build time. Don't try to read these at runtime from `process.env` — Vite doesn't expose `process` in browser code.
+
+---
+
+## Gotchas
+
+- **`.env.local` is build-time only.** Changes require restarting `pnpm dev`.
+- **Shadow DOM clipping:** the widget mounts to `document.body`. If your app uses `overflow: hidden` on `html` or `body`, the FAB and screen capture may behave oddly. Add a `position: fixed; z-index: 9999;` shim to a root container.
+- **Strict Mode double-effect:** React 18's `<StrictMode>` runs effects twice in dev. The widget is idempotent — second mount is a no-op — but you may see two "widget loaded" console messages in dev. Harmless.
+
+---
+
+## Verifying
+
+```bash
+npx @mhosaic/feedback-cli@latest doctor
+npx @mhosaic/feedback-cli@latest verify --origin http://localhost:5173 --with-test-report
+```

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

@@ -0,0 +1,92 @@
+# Consumer install — Vue 3 + Vite
+
+The CLI's auto-wrap is React-only; for Vue you paste the snippet into `src/main.ts`.
+
+---
+
+## Step 1 — Env vars
+
+The CLI already wrote Vite-flavored env vars. Vue + Vite uses the same `VITE_*` prefix, so **no rename needed**:
+
+```
+VITE_FEEDBACK_API_KEY=pk_proj_…
+VITE_FEEDBACK_ENDPOINT=https://software-factory-3tbbu.ondigitalocean.app
+```
+
+---
+
+## Step 2 — Initialize at app boot
+
+Edit `src/main.ts`:
+
+```typescript
+import { createApp } from 'vue'
+import App from './App.vue'
+
+import { createFeedback } from '@mhosaic/feedback'
+import { withErrorTracking } from '@mhosaic/feedback/error-tracking'
+import { withReplay } from '@mhosaic/feedback/replay'
+import { withWebVitals } from '@mhosaic/feedback/webvitals'
+
+const 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',
+    }))
+  )
+)
+
+const app = createApp(App)
+// Optional: expose `this.$feedback` in components and `inject('feedback')` in composables
+app.provide('feedback', fb)
+app.mount('#app')
+
+// Export for use in other modules (e.g. your auth store)
+export { fb }
+```
+
+The widget mounts itself to its own Shadow DOM container outside Vue's root. Calling `createFeedback()` once at module load is sufficient — there's no Vue plugin to install.
+
+---
+
+## 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:
+
+```typescript
+// src/composables/useAuthIdentity.ts
+import { watchEffect } from 'vue'
+import { useAuthStore } from '@/stores/auth'
+import { fb } from '@/main'
+
+export function useFeedbackIdentity() {
+  const auth = useAuthStore()
+  watchEffect(() => {
+    if (auth.user) {
+      fb.identify({ id: auth.user.id, email: auth.user.email, name: auth.user.name })
+    } else {
+      fb.identify({ id: '', email: '', name: '' })
+    }
+  })
+}
+```
+
+Call `useFeedbackIdentity()` once from a top-level component (e.g. inside `App.vue`'s `<script setup>`).
+
+---
+
+## Gotchas
+
+- **Vue Devtools collisions:** none observed in practice; the widget runs in its own Shadow DOM.
+- **`<KeepAlive>` and route changes:** the widget mounts once at module load and persists across all route changes. You don't need to re-mount it.
+- **Nuxt 3:** if the user is on Nuxt (not bare Vue + Vite), surface that — Nuxt has its own SSR rules and the snippet should go in a `client.ts` plugin (`plugins/feedback.client.ts`) instead of `main.ts`. The `.client.ts` suffix tells Nuxt to bundle it as client-only.
+
+---
+
+## Verifying
+
+```bash
+npx @mhosaic/feedback-cli@latest verify --origin http://localhost:5173 --with-test-report
+```

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

@@ -0,0 +1,185 @@
+# Consumer mode — installing the widget
+
+You are guiding a teammate through installing the @mhosaic/feedback widget into their host app, given a handoff payload from the operator.
+
+---
+
+## Step 1 — Parse the handoff payload
+
+Ask the user to paste the handoff payload as plain Markdown. Extract:
+
+- `Endpoint:` the backend URL
+- `Public widget key:` the `pk_proj_…` token
+- `Allowed origin(s):` the comma-separated list (used to verify CORS later)
+- `Project slug:` (optional; used only for human-readable error messages)
+
+If the user can't find the payload, walk them through asking the operator for it. The format is documented in `SKILL.md` under "handoff payload format".
+
+---
+
+## Step 2 — Classify the host app
+
+`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."
+3. **Neither package.json nor any obvious template root** → ask the user with plain text: "I don't see a `package.json` or a template folder. Are you in your host app's project root? What kind of app is this — JS framework, server-rendered (Django/Rails/Hugo), or something else?" Branch based on the answer.
+
+---
+
+## 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.
+
+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 |
+
+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).
+
+---
+
+## Step 4 — Run the CLI init (non-interactive)
+
+Run from the user's project root:
+
+```bash
+npx @mhosaic/feedback-cli@latest init \
+  --api-key <pk_proj_…> \
+  --endpoint <endpoint> \
+  --yes
+```
+
+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`)
+
+---
+
+## Step 5 — Framework-specific wiring
+
+Open the per-framework reference document and follow it verbatim:
+
+- Vite + React: `consumer-install-vite.md` (verify the auto-wrap)
+- Next.js: `consumer-install-next.md`
+- Remix: `consumer-install-remix.md`
+- Vue: `consumer-install-vue.md`
+- SvelteKit: `consumer-install-svelte.md`
+- 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)
+4. Gotchas (SSR, hydration, client-only)
+
+Use the `Edit` tool to make the changes if the user agrees, OR print the snippet and ask the user to apply it manually if they prefer hand control.
+
+---
+
+## Step 6 — Wire identify()
+
+Read `references/identify-snippets.md`. Detect the user's auth provider from their dependencies (`@auth0/auth0-react`, `@clerk/clerk-react`, `@supabase/supabase-js`, `firebase`, `next-auth`, `django` session via fetch, custom JWT, anonymous). Paste the matching snippet (with `Edit` tool) into the right place.
+
+If you can't detect the auth provider from `package.json`, ask the user explicitly with `AskUserQuestion`.
+
+---
+
+## Step 7 — (Optional but recommended) Wire the auto-capture modules
+
+`AskUserQuestion`:
+- question: `Wire the auto-capture modules?`
+- 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.`
+
+For each `Yes`, modify the consumer's widget init to chain the wrappers. The pattern:
+
+```typescript
+import { createFeedback } from '@mhosaic/feedback'
+import { withErrorTracking } from '@mhosaic/feedback/error-tracking'
+import { withReplay } from '@mhosaic/feedback/replay'
+import { withWebVitals } from '@mhosaic/feedback/webvitals'
+
+const fb = withErrorTracking(
+  withReplay(
+    withWebVitals(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).
+
+---
+
+## Step 8 — Run `verify`
+
+```bash
+npx @mhosaic/feedback-cli@latest verify \
+  --origin <consumer-dev-origin> \
+  --with-test-report
+```
+
+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.
+
+Stop on red and surface the hint. Don't proceed to step 9 until verify is green.
+
+---
+
+## Step 9 — Live smoke test in Chrome
+
+Follow `references/verify-install.md` for the full end-to-end smoke test:
+
+1. Start the consumer's dev server (`pnpm dev` / `npm run dev`)
+2. Drive Chrome to the dev URL
+3. Screenshot — confirm the FAB renders (bottom-right corner)
+4. Click the FAB, fill the form with `[INTEGRATE-FEEDBACK SMOKE TEST]`, submit
+5. Drive Chrome to `https://software-factory-3tbbu.ondigitalocean.app/reports` and confirm the report landed
+
+Both verify (step 8) and smoke test (step 9) write to the report stream — the operator can clean them up after a successful integration (admin SPA → /reports → filter by description → bulk delete).
+
+---
+
+## Step 10 — Done
+
+Summarize for the user:
+
+- Widget installed ✓
+- FAB renders ✓
+- Smoke-test report received ✓
+- Optional modules wired: [error-tracking / replay / web-vitals / 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
+
+If a follow-up question comes up (e.g. "how do I add another origin?"), point them to the operator's `/integrate-feedback` provisioning mode (operator can re-run it with the same project slug to update origins) OR direct the operator to edit the project in the admin SPA at `/projects/<id>`.

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

@@ -0,0 +1,218 @@
+# identify() recipes per auth provider
+
+The widget's FAB is hidden until `fb.identify()` is called with a non-empty `id`. Each snippet below is the minimum-viable wiring for one auth provider. Pick the one that matches the consumer's `package.json`.
+
+**General rule:** call `identify()` from a reactive scope that runs *after* the auth SDK resolves the user. Never at module top level. Each snippet below honors that.
+
+---
+
+## 1. Auth0 (`@auth0/auth0-react`)
+
+```tsx
+// src/components/FeedbackIdentity.tsx
+'use client'  // for Next.js App Router; omit for Vite/Remix
+
+import { useEffect } from 'react'
+import { useAuth0 } from '@auth0/auth0-react'
+import { useFeedback } from '@mhosaic/feedback/react'
+
+export function FeedbackIdentity() {
+  const { user, isAuthenticated, isLoading } = useAuth0()
+  const fb = useFeedback()
+  useEffect(() => {
+    if (isLoading) return
+    if (isAuthenticated && user) {
+      fb.identify({ id: user.sub ?? '', email: user.email, name: user.name })
+    } else {
+      fb.identify({ id: '', email: '', name: '' })
+    }
+  }, [fb, isAuthenticated, isLoading, user])
+  return null
+}
+```
+
+Mount `<FeedbackIdentity />` once inside both `<Auth0Provider>` and `<FeedbackProvider>` (or wherever you instantiated the widget). Hides the FAB on logout, re-identifies on token refresh.
+
+---
+
+## 2. Clerk (`@clerk/clerk-react`)
+
+```tsx
+import { useEffect } from 'react'
+import { useUser } from '@clerk/clerk-react'
+import { useFeedback } from '@mhosaic/feedback/react'
+
+export function FeedbackIdentity() {
+  const { isLoaded, isSignedIn, user } = useUser()
+  const fb = useFeedback()
+  useEffect(() => {
+    if (!isLoaded) return
+    if (isSignedIn && user) {
+      fb.identify({
+        id: user.id,
+        email: user.primaryEmailAddress?.emailAddress,
+        name: user.fullName ?? user.username ?? undefined,
+      })
+    } else fb.identify({ id: '', email: '', name: '' })
+  }, [fb, isLoaded, isSignedIn, user])
+  return null
+}
+```
+
+Mount under both `<ClerkProvider>` and your widget provider.
+
+---
+
+## 3. Supabase Auth
+
+```typescript
+// src/lib/feedback.ts (or wherever you instantiated `fb`)
+import { supabase } from './supabaseClient'
+import { fb } from './feedback'  // your createFeedback() result
+
+supabase.auth.onAuthStateChange((_event, session) => {
+  const u = session?.user
+  if (u) {
+    fb.identify({
+      id: u.id,
+      email: u.email,
+      name: (u.user_metadata?.full_name as string) ?? u.email,
+    })
+  } else {
+    fb.identify({ id: '', email: '', name: '' })
+  }
+})
+```
+
+Place this at app boot, after `createFeedback()`. The callback fires once on subscribe with the current session — no separate `getSession()` needed.
+
+---
+
+## 4. Firebase Auth
+
+```typescript
+import { getAuth, onAuthStateChanged } from 'firebase/auth'
+import { fb } from './feedback'
+
+onAuthStateChanged(getAuth(), (u) => {
+  if (u) {
+    fb.identify({
+      id: u.uid,
+      email: u.email ?? undefined,
+      name: u.displayName ?? undefined,
+    })
+  } else {
+    fb.identify({ id: '', email: '', name: '' })
+  }
+})
+```
+
+Place after `initializeApp()` and `createFeedback()`. The callback fires immediately with the current user (or `null`).
+
+---
+
+## 5. NextAuth.js / Auth.js (client component)
+
+```tsx
+'use client'
+
+import { useEffect } from 'react'
+import { useSession } from 'next-auth/react'
+import { useFeedback } from '@mhosaic/feedback/react'
+
+export function FeedbackIdentity() {
+  const { data: session, status } = useSession()
+  const fb = useFeedback()
+  useEffect(() => {
+    if (status === 'loading') return
+    const u = session?.user
+    if (u) {
+      fb.identify({
+        id: (u as { id?: string }).id ?? u.email ?? '',
+        email: u.email ?? undefined,
+        name: u.name ?? undefined,
+      })
+    } else fb.identify({ id: '', email: '', name: '' })
+  }, [fb, session, status])
+  return null
+}
+```
+
+Mount under `<SessionProvider>`. NextAuth's default `session.user` has no `id` — either add one via the `session` callback in your `[...nextauth]/route.ts`, or fall back to `email` (as above).
+
+---
+
+## 6. Django session-based auth
+
+```typescript
+import { fb } from './feedback'
+
+async function syncFeedbackIdentity() {
+  try {
+    const res = await fetch('/api/auth/me/', { credentials: 'include' })
+    if (!res.ok) { fb.identify({ id: '', email: '', name: '' }); return }
+    const u = await res.json()
+    fb.identify({ id: String(u.id), email: u.email, name: u.name })
+  } catch {
+    fb.identify({ id: '', email: '', name: '' })
+  }
+}
+syncFeedbackIdentity()
+// Re-call from your login-success + logout handlers
+```
+
+No push channel from Django sessions — you call this at boot, on login, on logout. If you have a SWR/React Query hook for `/api/auth/me/`, mirror the identity call into the same hook's `onSuccess`.
+
+---
+
+## 7. Custom JWT in `localStorage`
+
+```typescript
+import { fb } from './feedback'
+
+function decodeJwt(t: string): { sub?: string; email?: string; name?: string; exp?: number } {
+  return JSON.parse(atob(t.split('.')[1]!))
+}
+
+function syncIdentity() {
+  const token = localStorage.getItem('jwt')
+  if (!token) return fb.identify({ id: '', email: '', name: '' })
+  try {
+    const { sub, email, name, exp } = decodeJwt(token)
+    if (exp && exp * 1000 < Date.now()) return fb.identify({ id: '', email: '', name: '' })
+    fb.identify({ id: String(sub ?? ''), email, name })
+  } catch { fb.identify({ id: '', email: '', name: '' }) }
+}
+syncIdentity()
+window.addEventListener('storage', (e) => { if (e.key === 'jwt') syncIdentity() })
+```
+
+The `storage` listener catches logout-in-another-tab. Decoding without verification is fine because the widget identity is not a trust boundary — the backend re-verifies on report submission. For attested identity (`userHash` + `exp` HMAC), compute the envelope server-side and pass it through verbatim.
+
+---
+
+## 8. Anonymous-only (no auth)
+
+```typescript
+import { fb } from './feedback'
+
+// FAB only renders for non-empty `id`. Use a stable browser id so reports
+// from the same anonymous visitor cluster together on the dashboard.
+const id = localStorage.getItem('mhosaic-anon-id')
+  ?? (() => {
+    const fresh = `anon-${crypto.randomUUID()}`
+    localStorage.setItem('mhosaic-anon-id', fresh)
+    return fresh
+  })()
+fb.identify({ id, name: 'Anonymous' })
+```
+
+Place immediately after `createFeedback()`. Module-top-level is fine here — no async wait needed.
+
+---
+
+## Notes
+
+- **Hide the FAB on logout:** every snippet calls `identify({id: '', …})` on the logged-out branch. The widget's visibility gate (see `packages/core/src/core.ts:154`) hides the FAB whenever `id` is empty.
+- **Re-identify on token refresh is free.** Each call swaps the closure-held user reference; there's no remount overhead.
+- **Signed identity (`userHash` + `exp`) is not covered here** because it requires the host backend to compute an HMAC envelope with the project's signing secret. Issue the secret via `python manage.py feedback_issue_signing_secret --project <slug>`, store it in the host's vault, sign on every page render, and pass `userHash` + `exp` through to `identify()` verbatim alongside `id` / `email` / `name`.