@mushi-mushi/svelte 0.9.0 → 1.0.1

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,24 +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.
-
-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**.
-
-### Known CI/CD quirks and their automatic safeguards
+   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.
 
-A handful of GitHub-Actions × Changesets edge cases have caused release-pipeline stalls in the past. Each is now caught automatically — keep these in mind when you see the symptom:
-
-| Symptom | Root cause | Automatic safeguard |
-| --- | --- | --- |
-| The `Build & Test` required check never registers on the `chore: version packages` PR — the PR stays "Required check missing" forever | `changeset-release/master` is pushed by `github-actions[bot]`. GitHub silently drops the downstream `pull_request` event to prevent bot loops (observed on PR #45, #102, #124). | `ci.yml` now also triggers on `push` to `changeset-release/master`, so `Build & Test` reports against the head commit directly. No empty-commit nudge needed. |
-| Release workflow fails with `No commits between master and changeset-release/master` after merging a PR with a new changeset. | A `.changeset/*.md` file whose YAML frontmatter only targets packages listed in `.changeset/config.json#ignore` (e.g. `@mushi-mushi/server`, `@mushi-mushi/admin`). `changeset version` produces no bumps, the version PR is empty, the next push errors (PR #102 / #121, 2026-05-19). | `pnpm check:changeset-orphans` runs in both `ci.yml` and `release.yml`. PR CI fails with an actionable message naming the orphan file *before* it can reach master. If you legitimately need to record an internal-only change, omit the changeset entirely — the diff lives in git history. |
-| Release workflow's `Audit signatures of installed dependencies` step fails with `npm ETARGET / No matching version found for @mushi-mushi/<pkg>@<ver>` seconds after the publish step succeeded. | npm's registry CDN can take up to ~30s to propagate a freshly-published manifest. The audit step shells out to `npm install` against the just-published version and races the CDN (observed 2026-05-20, run 26149167393). | The audit step retries with exponential backoff (1, 2, 4, 8, 16, 32s — 63s total) before failing. Sigstore signatures are written at publish time, so a one-off audit failure never indicates a corrupted package — `pnpm view <pkg> version` is the ground truth. |
-| Push to `master` after merging a PR doesn't fire the `Release` workflow. | Same anti-loop protection: when a squash merge is attributed to `github-actions[bot]`, GitHub may suppress the downstream `push` trigger. Sporadic — observed twice in the last 60 days. | `release.yml` keeps `workflow_dispatch` as the manual fallback. Recovery: **Actions → Release → Run workflow → master**. The `Build & Verify` job re-runs identically to the auto-fired path. |
+```bash
+gh workflow run release.yml --ref master
+```
 
 ### Adding a brand-new publishable package
 
@@ -157,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,31 +1,58 @@
 # @mushi-mushi/svelte
 
+> **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.
+
 Svelte SDK for Mushi Mushi bug reporting. **API-only** — captures errors and submits reports but does not include the widget UI. Add `@mushi-mushi/web` alongside this package for the full Shadow DOM widget experience.
 
 > **One-command setup:** `npx mushi-mushi` auto-detects Svelte / SvelteKit and installs this package + `@mushi-mushi/web`.
 >
 > **Other frameworks:** [`@mushi-mushi/react`](https://npmjs.com/package/@mushi-mushi/react) · [`@mushi-mushi/vue`](https://npmjs.com/package/@mushi-mushi/vue) · [`@mushi-mushi/angular`](https://npmjs.com/package/@mushi-mushi/angular) · [`@mushi-mushi/react-native`](https://npmjs.com/package/@mushi-mushi/react-native) · [`@mushi-mushi/capacitor`](https://npmjs.com/package/@mushi-mushi/capacitor) · [`@mushi-mushi/web`](https://npmjs.com/package/@mushi-mushi/web) (vanilla JS)
 
+## Install
+
+```bash
+npm install @mushi-mushi/svelte @mushi-mushi/web
+# or: npx mushi-mushi
+```
+
+## Environment variables
+
+| Stack | Project ID | API key |
+| --- | --- | --- |
+| Vite / SvelteKit | `VITE_MUSHI_PROJECT_ID` | `VITE_MUSHI_API_KEY` |
+
+See [Project ID & API keys](https://docs.mushimushi.dev/concepts/credentials).
+
 ## Usage
 
 ```ts
 import { initMushi, getMushi } from '@mushi-mushi/svelte'
 
-initMushi({ projectId: 'proj_xxx', apiKey: 'mushi_xxx' })
+initMushi({
+  projectId: import.meta.env.VITE_MUSHI_PROJECT_ID,
+  apiKey: import.meta.env.VITE_MUSHI_API_KEY,
+})
 
-// Later
 const mushi = getMushi()
 mushi.submitReport({ title: 'broken', description: '...' })
 ```
 
-### With Widget UI
+### With widget UI
 
 ```ts
 import { initMushi } from '@mushi-mushi/svelte'
 import { Mushi } from '@mushi-mushi/web'
 
-initMushi({ projectId: 'proj_xxx', apiKey: 'mushi_xxx' })
-Mushi.init({ projectId: 'proj_xxx', apiKey: 'mushi_xxx' })
+initMushi({
+  projectId: import.meta.env.VITE_MUSHI_PROJECT_ID,
+  apiKey: import.meta.env.VITE_MUSHI_API_KEY,
+})
+
+Mushi.init({
+  projectId: import.meta.env.VITE_MUSHI_PROJECT_ID,
+  apiKey: import.meta.env.VITE_MUSHI_API_KEY,
+})
 ```
 
 ### SvelteKit error handler
@@ -36,7 +63,15 @@ import { createMushiErrorHandler } from '@mushi-mushi/svelte'
 export const handleError = createMushiErrorHandler()
 ```
 
-## Peer Dependencies
+## API
+
+| Export | Purpose |
+| --- | --- |
+| `initMushi(config)` | Initialize once at app startup |
+| `getMushi()` | Access the SDK instance |
+| `createMushiErrorHandler()` | SvelteKit `handleError` integration |
+
+## Peer dependencies
 
 - `svelte` >= 4
 

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@mushi-mushi/svelte",
-  "version": "0.9.0",
+  "version": "1.0.1",
   "license": "MIT",
   "description": "Svelte SDK for Mushi Mushi — context-based init, SvelteKit error hook integration",
-  "main": "./dist/index.js",
+  "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "peerDependencies": {
     "svelte": ">=4"
   },
   "dependencies": {
-    "@mushi-mushi/core": "^1.5.0",
-    "@mushi-mushi/web": "^1.5.0"
+    "@mushi-mushi/core": "^1.16.0",
+    "@mushi-mushi/web": "^1.16.0"
   },
   "devDependencies": {
     "eslint": "^10.3.0",