@mushi-mushi/react-native 0.15.2 → 0.17.0

package/CONTRIBUTING.md

@@ -58,12 +58,12 @@ packages/
   react-native/  React Native SDK (MIT)
   cli/           CLI tool (MIT)
   mcp/           MCP server for coding agents (MIT)
-  server/        Supabase Edge Functions (BSL)
-  agents/        Agentic fix pipeline (BSL)
-  verify/        Fix verification (BSL)
+  server/        Supabase Edge Functions (AGPLv3)
+  agents/        Agentic fix pipeline (AGPLv3)
+  verify/        Fix verification (AGPLv3)
 apps/
   admin/         Admin dashboard (React + Tailwind)
-  docs/          Documentation site (planned)
+  docs/          Documentation site (Nextra — apps/docs)
 tooling/
   eslint-config/ Shared ESLint flat config
   tsconfig/      Shared TypeScript configs
@@ -81,6 +81,30 @@ tooling/
    ```
 6. Open a pull request
 
+### Documentation (docs-as-code)
+
+If your PR changes **user-visible SDK or CLI behavior**, update docs in the **same PR**:
+
+| Surface | When to update |
+| --- | --- |
+| `packages/*/README.md` | npm-facing install/API/config changes for that package |
+| `apps/docs/content/**/*.mdx` | Long-form guides, quickstarts, admin console docs |
+| Root `README.md` | Marketing stats only when counts change — run `pnpm check:docs-stats` |
+
+Guardrails (run locally before pushing):
+
+```bash
+pnpm check:docs-stats          # root README stat badges
+pnpm check:sdk-version-matrix  # apps/docs/content/sdks/index.mdx versions
+pnpm check:internal-doc-links  # dead /foo links in MDX
+pnpm check:onboarding-drift    # phantom MCP env vars / stale tool names
+pnpm check:bundle-docs         # @mushi-mushi/web size-limit vs README
+pnpm gen:llms-txt              # regenerate apps/docs/public/llms.txt after nav changes
+pnpm gen:mcp-tools-doc         # regenerate sdks/mcp-tools.generated.mdx from catalog.ts
+```
+
+README changes on npm packages only appear on [npmjs.com](https://www.npmjs.com) after the next **Changesets publish**.
+
 ## Changesets
 
 We use [Changesets](https://github.com/changesets/changesets) for versioning. If your PR modifies a published package (`core`, `web`, `react`, `vue`, `svelte`, `angular`, `react-native`, `cli`, `mcp`), add a changeset:
@@ -93,13 +117,30 @@ Select the affected packages, the semver bump type, and write a summary. The cha
 
 ## Release flow
 
-Releases are fully automated. Maintainers don't run `npm publish` by hand.
+Releases are fully automated once the version PR is merged. Maintainers don't run
+`npm publish` by hand for routine bumps. See **[`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md)**
+for the full production runbook (edge functions, admin SPA, docs site, migrations).
 
 1. PRs land on `master` with one or more changeset files in `.changeset/`.
-2. `release.yml` runs on every push to `master`. It opens (or updates) a `chore: version packages` PR that bumps every affected `package.json`, rolls up the changelogs, and deletes the consumed changesets.
-3. Merging that "Version Packages" PR re-fires `release.yml`. The publish step authenticates to npm via **OpenID Connect (OIDC) Trusted Publishers** — no long-lived `NPM_TOKEN` is exchanged — and every tarball ships with a **Sigstore provenance attestation** uploaded to the public transparency log.
+   Orphaned changesets (only ignored packages) fail `pnpm check:changeset-orphans`.
+2. `release.yml` runs on every push to `master`. It opens (or updates) a
+   **`chore: version packages`** PR on `changeset-release/master` that bumps
+   affected `package.json` files, rolls up changelogs, and deletes consumed
+   changesets.
+3. **Wait for CI on the version PR.** If checks don't appear (bot-branch
+   suppression), push an empty commit to `changeset-release/master`. If
+   `check:sdk-version-matrix` fails, run `pnpm gen:sdk-version-matrix` on that
+   branch and commit `apps/docs/content/sdks/index.mdx`.
+4. Merge the version PR. The publish step uses **OIDC Trusted Publishers** +
+   Sigstore provenance (with `NPM_TOKEN` only for brand-new package bootstrap).
+5. **Manually dispatch Release** unless a run starts within ~2 minutes:
+   **Actions → Release → Run workflow → `master`**. Squash-merges attributed to
+   `github-actions[bot]` usually suppress the auto `push` trigger — manual
+   dispatch is the normal path, not a fallback of last resort.
 
-If GitHub's anti-loop protection suppresses the auto re-fire (the squash merge can be attributed to `github-actions[bot]`), trigger the workflow manually: **Actions → release → Run workflow → master**.
+```bash
+gh workflow run release.yml --ref master
+```
 
 ### Adding a brand-new publishable package
 
@@ -146,7 +187,7 @@ chore: bump dependencies
 ## License
 
 - SDK packages are MIT — your contributions will be MIT-licensed
-- Server/agents/verify are BSL 1.1 — contributions to those packages fall under BSL
+- Server/agents/verify are AGPLv3 — contributions to those packages fall under AGPLv3
 
 ## Questions?
 

package/README.md

@@ -1,5 +1,8 @@
 # @mushi-mushi/react-native
 
+> **Your AI wrote it. Mushi tells you why it broke.**
+> Plain-English diagnosis + a paste-ready fix, right inside Cursor. MIT-licensed SDKs · self-hostable · no second LLM key.
+
 React Native SDK for [Mushi Mushi](https://www.npmjs.com/package/mushi-mushi) — shake-to-report widget, offline queue, and the closed-loop lesson layer for iOS + Android.
 
 > **One-command setup:** `npx mushi-mushi` auto-detects React Native / Expo and installs this package with the right env vars.
@@ -91,27 +94,59 @@ import { MushiBottomSheet, MushiFloatingButton } from '@mushi-mushi/react-native
 
 ## What gets captured
 
-- Device info (platform, OS version, screen dimensions)
+- Device info (platform, OS version, screen dimensions) + a stable device `fingerprintHash`
+- A per-launch `sessionId` so every report from the same run is grouped
+- `sdkPackage` / `sdkVersion` / `appVersion` so the console can flag outdated installs
 - Console logs (monkey-patched `console.*`)
 - Network requests (fetch interceptor, headers redacted)
 - Navigation events (React Navigation integration, optional)
+- A 50-entry breadcrumb ring buffer → sent as `breadcrumbs` + a derived repro `timeline` (SDK lifecycle, screen changes via `setScreen`, and host crumbs via `addBreadcrumb`)
+- Screenshot of the current screen (optional — see below)
 - Offline queue via `@react-native-async-storage/async-storage` — reports survive force-close
 
+## Screenshots
+
+When `react-native-view-shot` is installed, the SDK captures the current screen **before** the report sheet overlays it, and shows the user a thumbnail they can remove before submitting. Enabled by default; turn off with `capture: { screenshot: false }`.
+
+```bash
+npx expo install react-native-view-shot   # v4+ on Expo SDK 55; v5+ for Fabric / New Architecture
+```
+
+> **Masking sensitive screens.** `captureScreen()` grabs whatever is on screen, which on a finance/health app can include balances or PII. The user always reviews and can remove the thumbnail before submit, but for screens that should never be captured, set `capture: { screenshot: false }` while they're focused, or use `expo-screen-capture` to mark the view secure. Field-level masking is on the roadmap.
+
+## Identifying the reporter
+
+Call `identify()` / `setUser()` whenever auth state changes so reports show a human name instead of an anonymous token in the console:
+
+```tsx
+const mushi = useMushi()
+mushi.identify(user.id, { email: user.email, name: user.displayName, provider: 'supabase' })
+// or, web-SDK style:
+mushi.setUser({ id: user.id, email: user.email, name: user.displayName, provider: 'supabase' })
+```
+
+Mushi stores only a SHA-256 hash of the email (the host app owns the raw PII) and shows the `name` as the reporter's display name.
+
 ## Peer dependencies
 
 - `react` >= 18
 - `react-native` >= 0.72
 - `@react-navigation/native` >= 6 (optional — navigation capture)
 - `@react-native-async-storage/async-storage` >= 1.19 (optional — offline queue)
+- `react-native-view-shot` >= 3.8 (optional — screenshot capture; v5+ for New Architecture / Fabric)
 - `expo-sensors` (optional — shake trigger only)
 
 ## Changelog highlights
 
+- **v0.17.0** — Report payload parity with the web SDK: nested `metadata.user` identity (fixes the anonymous-token reporter on the server), `setUser()` alias, per-launch `sessionId`, `sdkPackage`/`sdkVersion`/`appVersion`, device `fingerprintHash`, and a breadcrumb ring buffer → `breadcrumbs` + repro `timeline`. `capture.screenshot` toggle + `addBreadcrumb()`. Bottom sheet restyled to match the web widget.
 - **v0.11.0** — Hermes compatibility fix: replaced `new Function()` dynamic imports with lazy `require()` for `@react-native-community/netinfo` and `expo-sensors`. Enables `trigger: 'button'` safely on all RN 0.84+ Hermes/AOT builds. Adds `MushiTrigger` headless component.
 - **v0.8.x** — Shake-to-report listener, offline queue, navigation capture.
 
 See the full [CHANGELOG](https://github.com/kensaurus/mushi-mushi/blob/master/packages/react-native/CHANGELOG.md).
 
+Maintainers: report ingest contract and empty-state semantics are documented in
+[`docs/report-ingest-contract.md`](../../docs/report-ingest-contract.md).
+
 ## License
 
 MIT
@@ -120,4 +155,4 @@ MIT
 <!-- mushi-readme-stats-footer -->
 ---
 
-<sub>Monorepo scale (June 2026): 43 edge functions · 234 SQL migrations · 13 outbound plugins · 11 inbound adapters. Canonical counts: <a href="https://github.com/kensaurus/mushi-mushi/blob/master/docs/stats.md">docs/stats.md</a> · <code>pnpm docs-stats</code></sub>
+<sub>Monorepo scale (June 2026): 47 edge functions · 256 SQL migrations · 13 outbound plugins · 11 inbound adapters · 18 pipeline agents. Canonical counts: <a href="https://github.com/kensaurus/mushi-mushi/blob/master/docs/stats.md">docs/stats.md</a> · <code>pnpm docs-stats</code></sub>