@mhosaic/feedback-cli 0.13.0 → 0.14.0

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

@@ -0,0 +1,179 @@
+# 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 — Verify we're in a JS/TS project
+
+`Read` the user's `package.json`. If the file doesn't exist, stop and ask:
+
+> "I don't see a `package.json` in `<cwd>`. Are you in your host app's project root? cd there and re-run `/integrate-feedback`."
+
+---
+
+## 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 |
+| `@remix-run/react` | `remix` | `consumer-install-remix.md` | ❌ paste snippet |
+| `vue` ≥ 3 | `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 |
+
+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`.

package/skills/integrate-feedback/references/operator-provision.md

@@ -0,0 +1,233 @@
+# Operator mode — provisioning a new project
+
+You are guiding the platform operator (Victor or a delegate) through creating a new **Company → Project → public widget key** on the Mhosaic backend, then assembling a handoff payload the consumer pastes into their own integration flow.
+
+**Strategy:** drive the operator's already-authenticated Chrome session at the software-factory admin SPA. For the API calls themselves, use `mcp__claude-in-chrome__javascript_tool` to invoke `fetch()` *from within* the browser tab — that way every call goes through the SPA's auth cookies, hits the DRF stack with full middleware (CSRF, permissions, audit), and never requires copying tokens into shell `curl` commands.
+
+The admin SPA is at https://software-factory-3tbbu.ondigitalocean.app.
+
+---
+
+## Step 1 — Confirm Chrome MCP is available
+
+Before anything else, call `mcp__claude-in-chrome__tabs_context_mcp` to discover what tabs exist. If you don't see a tab pointed at `software-factory-3tbbu.ondigitalocean.app`, create one with `mcp__claude-in-chrome__tabs_create_mcp`.
+
+If `tabs_context_mcp` errors with "no MCP tab group", call it again with `createIfEmpty: true` — that opens a fresh window for the skill to use without disturbing the operator's existing browsing.
+
+---
+
+## Step 2 — Verify operator is logged in
+
+Navigate the chosen tab to `https://software-factory-3tbbu.ondigitalocean.app/`. Take a screenshot. If the page shows `/login`, walk the operator through the SSO flow:
+
+> "You're not logged in. Click 'Continuer avec Google' and pick your @mhosaic.com account. When you land on /, tell me 'ready'."
+
+Wait for the operator to confirm. Then re-screenshot to verify the dashboard is showing.
+
+---
+
+## Step 3 — Collect the project inputs
+
+Use `AskUserQuestion` for **each** of these, one at a time. Always confirm before proceeding.
+
+1. **Company:** existing or new?
+   - Use `AskUserQuestion` with options `Use existing company` and `Create new company`.
+   - If existing: fetch the list with the JS snippet in step 4 and present a multi-choice question.
+   - If new: ask for the company name (plain text). Auto-slugify it (lowercase, hyphens, strip accents — see `apps/admin/src/features/companies/NewCompanyForm.tsx:14-22`).
+
+2. **Project name** (plain text, e.g. `"NoRag Production"`).
+
+3. **Project slug** (plain text, auto-slugified default from name). Must be unique within the company. Lowercase, hyphens, ≤ 80 chars.
+
+4. **Allowed origins** (plain text, comma- or space-separated list). Each must be a full `https?://host[:port]` URL. Rules:
+   - Wildcards (`*`) are rejected.
+   - `http://` is only permitted for localhost / 127.0.0.1 / ::1.
+   - Path is forbidden (e.g. `https://app.example.com/widget` — drop the path).
+   - Strongly recommend including BOTH the prod URL **and** the dev URL (e.g. `https://app.acme.com, http://localhost:5173`) so the teammate can test locally before deploying.
+
+5. **Share reports with widget board?** (`AskUserQuestion`, default No).
+   - `Yes — every authenticated end-user sees every report` (good for internal tools)
+   - `No — strict submitter-only view` (default, safer for public-facing apps)
+
+6. **(Optional) Repo/staging/prod URLs** — surface in admin UI but not load-bearing. Skip unless the operator volunteers.
+
+Display the collected values as a summary table and confirm with `AskUserQuestion` "Proceed?" before mutating anything.
+
+---
+
+## Step 4 — Provision via the browser's fetch()
+
+You'll execute small JavaScript snippets in the admin SPA tab via `mcp__claude-in-chrome__javascript_tool`. The SPA's session cookies authenticate the requests automatically.
+
+### Get a fresh access token
+
+The SPA holds its access token in memory (not localStorage — see `apps/admin/src/api/tokenStore.ts`). To get one from outside the SPA's React state, hit the cookie-backed refresh endpoint: the browser auto-sends the HttpOnly refresh cookie, and the response body returns a fresh access token.
+
+```javascript
+fetch('/api/auth/token/refresh/', { method: 'POST', credentials: 'include' })
+  .then(r => r.json())
+  .then(d => JSON.stringify({ access: d.access ?? d.access_token ?? null }))
+```
+
+If `access` is null and the response was 401, the operator's session is fully expired — re-do step 2 (re-SSO). Otherwise capture the token and use it for `Authorization: Bearer <token>` on subsequent calls.
+
+For the rest of this procedure, treat the captured token as a shell variable `TOKEN`. Each snippet below uses `TOKEN` literally — substitute it before sending to `mcp__claude-in-chrome__javascript_tool`.
+
+### Look up or create the company
+
+To list companies (response wraps them in `{items: [...]}`):
+
+```javascript
+fetch('/api/feedback/v1/companies/', {
+  headers: { 'Authorization': 'Bearer TOKEN' }
+}).then(r => r.json()).then(d => JSON.stringify(d.items ?? d))
+```
+
+Each item has `{id, slug, name}`. Filter client-side by slug if you're looking up an existing company.
+
+To create a new company:
+
+```javascript
+fetch('/api/feedback/v1/companies/', {
+  method: 'POST',
+  headers: {
+    'Authorization': 'Bearer TOKEN',
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({ name: 'COMPANY_NAME', slug: 'company-slug' })
+}).then(r => r.json()).then(d => JSON.stringify(d))
+```
+
+Capture the company `id` (UUID) from the response.
+
+### Create the project
+
+```javascript
+fetch('/api/feedback/v1/projects/', {
+  method: 'POST',
+  headers: {
+    'Authorization': 'Bearer TOKEN',
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    company: 'COMPANY_UUID',
+    name: 'PROJECT_NAME',
+    slug: 'project-slug',
+    allowed_origins: ['https://app.example.com', 'http://localhost:5173'],
+    share_reports_with_widget: false
+  })
+}).then(r => r.json()).then(d => JSON.stringify(d))
+```
+
+If you get a 400 with `allowed_origins` validation error: parse the message, walk the operator through fixing the offending URL, and retry. Common reasons:
+- `http://` in prod (use `https://`)
+- trailing slash or path on the URL (strip it)
+- wildcard `*` (not supported by design)
+
+If you get a 400 with slug collision: append `-2`, `-3`, … and retry. Confirm the new slug with the operator first.
+
+Capture the project `id` from the response.
+
+### Mint the public widget key
+
+```javascript
+fetch('/api/feedback/v1/project-keys/create/', {
+  method: 'POST',
+  headers: {
+    'Authorization': 'Bearer TOKEN',
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    project_id: 'PROJECT_UUID',
+    kind: 'public',
+    label: 'Production widget key — minted by /integrate-feedback'
+  })
+}).then(r => r.json()).then(d => JSON.stringify(d))
+```
+
+The response includes `key: "pk_proj_…"` in plaintext. **This is the only time the plaintext key is ever returned.** Capture it immediately and treat it as a secret in your subsequent skill state (don't echo it more than necessary).
+
+---
+
+## Step 5 — Assemble the handoff payload
+
+Construct this Markdown block and present it to the operator as the deliverable:
+
+````markdown
+## Mhosaic Feedback handoff
+
+**Project slug:** `<project-slug>`
+**Project ID:** `<project-uuid>`
+**Endpoint:** `https://software-factory-3tbbu.ondigitalocean.app`
+**Public widget key:** `<pk_proj_…>`
+**Allowed origin(s):** `<origin1>`, `<origin2>`, …
+**Reports visibility:** `<submitter-only | shared with widget board>`
+
+### Send to your teammate
+
+To install:
+```bash
+npx @mhosaic/feedback-cli@latest init \
+  --api-key <pk_proj_…> \
+  --endpoint https://software-factory-3tbbu.ondigitalocean.app \
+  --yes
+```
+
+To verify after install:
+```bash
+npx @mhosaic/feedback-cli@latest verify \
+  --origin <consumer dev origin> \
+  --with-test-report
+```
+
+Or guide them with Claude Code:
+```
+/integrate-feedback
+```
+(then paste the block above as their first message)
+````
+
+Print this to the chat. Encourage the operator to share it via a secure channel (1Password, Slack DM, signed email) — **not in public channels or git**.
+
+---
+
+## Step 6 — Verify the project really exists
+
+Drive Chrome to `https://software-factory-3tbbu.ondigitalocean.app/companies/<company-slug>` and screenshot. The operator should see the project listed. Then drive to `/settings/widget-keys` and confirm the key shows up there (masked — the plaintext is gone after this point).
+
+If the project doesn't appear: something silently failed (browser cache, deploy mid-rollout, race condition). Open browser DevTools network tab via `mcp__claude-in-chrome__read_network_requests` filtered to `/api/feedback/v1/projects/` and inspect the actual POST response. Surface the diagnostic to the operator and stop.
+
+---
+
+## Step 7 — Offer to continue into consumer mode
+
+`AskUserQuestion`:
+- question: `Want to install the widget into a consumer app right now?`
+- options:
+  - `Yes — continue here`, description: `Move to consumer mode using the handoff payload we just built.`
+  - `No — I'll send the payload to my teammate`, description: `Stop here.`
+
+If yes, follow `references/consumer-install.md` from step 1, pre-filling the handoff payload values.
+
+---
+
+## Rollback / undo
+
+If the operator wants to undo what was just provisioned:
+
+1. **Revoke the key** — admin SPA at `/settings/widget-keys` → find the row → click "Révoquer". This breaks the widget immediately for anyone using it.
+2. **Delete the project** — currently no UI button; instruct the operator to use the DO Console → backend pod → `python manage.py shell -c "from mhosaic_feedback.models import Project; Project.objects.filter(slug='<slug>').delete()"`. This cascades to keys, reports, etc. — only do this if no real reports have been created against the project.
+
+---
+
+## Error catalog
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `fetch` returns 401 | JWT expired | Re-do step 2 (re-login via SSO) |
+| `fetch` returns 403 on companies POST | Not staff | Operator's user lacks `is_staff` — provision via `/admin/` or `python manage.py shell` |
+| `fetch` returns 400 on projects POST with `allowed_origins` | Origin format invalid | Parse server error, walk operator through fixing the URL, retry |
+| `fetch` returns 400 with `slug` collision | Slug already exists in this company | Append `-2`, confirm with operator, retry |
+| Plaintext key not in response | Wrong endpoint (used `/api/feedback/v1/projects/<id>/keys/` instead of `/api/feedback/v1/project-keys/create/`) | Use the correct endpoint per `packages/backend/mhosaic_feedback/views_project_keys.py:36` |
+| `mcp__claude-in-chrome__javascript_tool` returns null/undefined | Snippet didn't return a value | All snippets above end with `JSON.stringify(...)` — verify the snippet's last expression is a JSON-serializable value |
+| Operator says "I don't see the new project" | Browser cache | Hard reload (Cmd+Shift+R). If still missing, network tab → check POST returned 201 |