native-update 1.4.9 → 3.1.0

package/docs/docs-site/plan.md

@@ -0,0 +1,201 @@
+# Documentation Site — Batch Plan
+
+**Goal**: Ship a complete, public, SEO-ready Docusaurus documentation site for `native-update` v3.x in 10 batches. Each batch = one prompt = one commit per affected repo. Resumable via `tracker.json`.
+
+**Two repos affected**:
+1. `native-update/` (this repo) — owns the plan + tracker. Single planning commit per batch.
+2. `native-update-docs/` (sibling, separate public GitHub repo) — owns the actual docs site. One commit per batch in this repo.
+
+**Cooldown after final batch**: 7 days. After all 10 batches complete, this prompt becomes a no-op until 7 days have passed (matches the project-wide `production-readiness-audit-tracker.json` pattern).
+
+---
+
+## Skill bindings (apply per batch where listed)
+
+| Domain | Skill |
+|---|---|
+| Diátaxis info architecture | `documentation-writer` |
+| Technical writing voice | `technical-writing` |
+| AI-citable structure | `ai-seo` |
+| Marketing landing copy | `copywriting` |
+| Broad SEO + GSC | `seo` |
+| Firebase Hosting setup | `firebase-hosting-basics` |
+| Firebase config/CLI | `firebase-basics` |
+
+Invoke matching skills BEFORE the first Edit/Write of each batch.
+
+---
+
+## Batch 1 — Foundation & first pages ✅ (this batch)
+
+**Skills**: `documentation-writer`, `ai-seo`, `copywriting`
+
+**In `native-update`**:
+- `docs/docs-site/scope.md` — what we document, locked
+- `docs/docs-site/plan.md` — this file
+- `docs/docs-site/tracker.json` — JSON status, resumable
+- Update root `CLAUDE.md` + `AGENTS.md` with a "Docs Site" record pointing at the tracker
+
+**In `native-update-docs/` (new sibling)**:
+- Init: `package.json`, `tsconfig.json`, `.gitignore`, `.editorconfig`
+- `docusaurus.config.ts` — brand metadata, SEO defaults, OG image, Ahsan author footer
+- `sidebars.ts` — full target structure (placeholders for sections written in later batches)
+- `src/css/custom.css` — brand color palette + dark-mode tuning
+- `src/pages/index.tsx` — homepage (hero + features + CTA)
+- `static/img/logo.svg`, `static/img/favicon.svg`, `static/img/social-card.svg`
+- `static/robots.txt` (skeleton — full allow-list ships in Batch 10)
+- `docs/intro.md` — "What is native-update?" (definition-first, 600+ words)
+- `docs/getting-started/installation.md` — install steps, peer-dep note, platform setup quick reference
+- `docs/getting-started/quick-start.md` — 5-minute first OTA update tutorial
+- `docs/about-the-author.md` — Ahsan Mahmood credits page (links, contact)
+- `README.md`, `CLAUDE.md`, `AGENTS.md` — repo metadata + freshness rules
+- `yarn install`, `git init`, first commit
+- `~/.dev-ports.json` — register port 5960
+
+**Verification**: `yarn build` (in sibling) exits 0; `yarn typecheck` (if available) exits 0; tracker updated.
+
+---
+
+## Batch 2 — SDK Reference: Live Update (OTA)
+
+**Skills**: `documentation-writer`, `ai-seo`
+
+Write `docs/reference/sdk/live-update/`:
+- `overview.md` — what live-update does, when to use it
+- `methods.md` — all 20 methods grouped (lifecycle, channels, downloads, validation, cancellation), each with TypeScript signature + parameters table + return type + example + errors thrown
+- `types.md` — `BundleInfo`, `SyncOptions`, `SyncResult`, `DownloadOptions`, `LatestVersion`, `DeleteOptions`, `ValidateOptions`, `ValidationResult`, `CheckForUpdateResult`, `DownloadUpdateOptions`
+- `enums.md` — `UpdateStrategy`, `UpdateMode`, `BundleStatus`, `SyncStatus`
+- `events.md` — `downloadProgress`, `updateStateChanged`
+- `config.md` — `LiveUpdateConfig` field-by-field
+
+Estimated: 8–10 pages, ~6,000 words total.
+
+---
+
+## Batch 3 — SDK Reference: App Update + App Review
+
+**Skills**: `documentation-writer`, `ai-seo`
+
+Write `docs/reference/sdk/app-update/` (5 methods, AppUpdateInfo, OpenAppStoreOptions, InstallStatus enum, 6 events) and `docs/reference/sdk/app-review/` (2 methods, AppReviewConfig, ReviewResult, CanRequestReviewResult, throttling rules).
+
+Estimated: 7–8 pages.
+
+---
+
+## Batch 4 — SDK Reference: Background Updates + Security + Core
+
+**Skills**: `documentation-writer`, `ai-seo`
+
+Write `docs/reference/sdk/background-update/` (8 methods, BackgroundUpdateConfig, NotificationPreferences, 2 events, BackgroundUpdateType + NotificationPriority enums), `docs/reference/sdk/security/` (getSecurityInfo, SecurityConfig, ChecksumAlgorithm, CertificatePinning, UpdateErrorCode 20+ codes), `docs/reference/sdk/core/` (initialize/isInitialized/reset/cleanup/configure + PluginInitConfig).
+
+Estimated: 9–11 pages.
+
+---
+
+## Batch 5 — CLI Reference
+
+**Skills**: `documentation-writer`, `technical-writing`
+
+Write `docs/reference/cli/`:
+- `overview.md` — install, global flags, exit codes
+- `init.md`, `keys-generate.md`, `bundle-create.md`, `bundle-sign.md`, `bundle-verify.md`, `server-start.md`, `monitor.md`, `backend-create.md`
+
+Each command page: synopsis, flags table, examples, common errors.
+
+Estimated: 9 pages.
+
+---
+
+## Batch 6 — Backend setup guides
+
+**Skills**: `documentation-writer`, `technical-writing`
+
+Write `docs/backend/`:
+- `overview.md` — when to self-host, hosted SaaS comparison
+- `laravel-nova-self-host.md` — full setup (env, migrations, queues, signing keys, Nova auth, Firebase token verification)
+- `node-express-minimal.md` — based on `example-apps/node-express`
+- `api-contract.md` — every public endpoint, request/response shape, signing
+- `nova-admin-overview.md` — what each Nova resource manages
+
+Estimated: 5 pages, dense.
+
+---
+
+## Batch 7 — Platform guides
+
+**Skills**: `documentation-writer`, `technical-writing`
+
+Write `docs/platforms/`:
+- `android.md` — manifest additions, permissions, ProGuard rules, WorkManager constraints, signing setup
+- `ios.md` — Info.plist keys, capabilities, background modes, App Store Review setup
+- `web.md` — browser dev fallback, limitations, when to use
+
+Estimated: 3 long pages (~2,000 words each).
+
+---
+
+## Batch 8 — Tutorials & how-to guides
+
+**Skills**: `documentation-writer`, `ai-seo`, `copywriting`
+
+Write `docs/tutorials/` and `docs/how-to/`:
+- Tutorial: end-to-end first OTA update (install → keypair → bundle → sign → upload → device verifies → applies)
+- Tutorial: backend-first walkthrough (Laravel install → first app → first build → first device check)
+- How-to: manage release channels (production/staging/beta)
+- How-to: rotate signing keys without breaking active bundles
+- How-to: roll back a bad bundle
+- How-to: migrate from CodePush
+- How-to: integrate with CI/CD (GitHub Actions example)
+- How-to: test bundles in development
+
+Estimated: 8 pages.
+
+---
+
+## Batch 9 — Concepts & explanations
+
+**Skills**: `documentation-writer`, `ai-seo`
+
+Write `docs/concepts/`:
+- `how-ota-updates-work.md`
+- `bundle-integrity-and-signing.md`
+- `update-strategies-compared.md` (immediate vs background vs manual)
+- `architecture.md` (with mermaid diagrams)
+- `security-model.md`
+- `error-handling-philosophy.md`
+
+Estimated: 6 pages, deeper writing.
+
+---
+
+## Batch 10 — SEO + Firebase deploy + GitHub publish
+
+**Skills**: `seo`, `ai-seo`, `firebase-hosting-basics`, `firebase-basics`
+
+- Per-page meta head injection (canonical, OG, Twitter Card) via `docusaurus.config.ts`
+- `static/robots.txt` final form (full AI-bot allow list)
+- `static/llms.txt` + `static/llms-full.txt`
+- `static/humans.txt`, `static/.well-known/security.txt`
+- `static/sitemap-index.json`
+- JSON-LD injection per page (TechArticle + FAQPage where applicable)
+- `firebase.json`, `.firebaserc`, hosting config
+- GitHub Actions workflow: build + deploy on push to `main`
+- README publish instructions (GH + Firebase + Search Console + Bing Webmaster)
+- Update tracker `last_run.completed_at` and `next_allowed_run_after` (today + 7 days)
+- Final commit in both repos
+
+Estimated: 1 dense pass.
+
+---
+
+## Resumability protocol (for future runs of this prompt)
+
+When this prompt is re-run:
+
+1. Read `docs/docs-site/tracker.json`.
+2. If `last_run.status == "complete"` AND today < `last_run.next_allowed_run_after` → SKIP. Tell the user "Docs site is complete; next allowed run after `<date>`. Use the docs site or open an issue if anything is missing."
+3. If `last_run.status == "in_progress"` → find the lowest-indexed batch with `status != "completed"` in `batches[]` and resume there. Do NOT redo earlier batches.
+4. After completing each batch: append a row to `batches[]`, update `current_batch` and `progress_pct`. ONE commit per batch in each affected repo.
+5. After Batch 10: set `last_run.status = "complete"`, `last_run.completed_at = today`, `last_run.next_allowed_run_after = today + 7 days`.
+
+**Override conditions** (run a fix-only batch even within cooldown): explicit user bypass; broken `yarn build` in sibling repo; production incident; published page returns 404 or 5xx; Lighthouse SEO drops below 95.

package/docs/docs-site/scope.md

@@ -0,0 +1,127 @@
+# Documentation Site — Scope
+
+**Project**: Public Docusaurus documentation site for the `native-update` Capacitor plugin.
+**Repo location**: `/home/ahsan/Documents/01-code/projects/native-update-docs/` (sibling, separate public GitHub repo)
+**Hosting**: Dedicated Firebase project (TBD in Batch 10)
+**Versioning**: Single version — latest only (no version dropdown for v1)
+**Theme**: Default Docusaurus `classic` preset + brand colors + logo + dark mode
+**Author credit**: Ahsan Mahmood (aoneahsan@gmail.com, https://aoneahsan.com, https://linkedin.com/in/aoneahsan) — surfaced on every page footer + about/credits page + JSON-LD `author`
+
+## Reference date
+
+**Scope locked**: 2026-05-10
+**Source of truth**: `native-update` plugin v3.0.0 (`package.json`)
+
+---
+
+## What we're documenting (surface area)
+
+### 1. Plugin SDK — TypeScript API (`src/`)
+
+**~30 public methods**, **~50 types/interfaces**, **11 events**, **10 enums**, split across 6 feature areas:
+
+| Area | Methods | Notes |
+|---|---|---|
+| Live Update (OTA) | 20 — `sync`, `download`, `set`, `reload`, `reset`, `current`, `list`, `delete`, `notifyAppReady`, `getLatest`, `setChannel`, `setUpdateUrl`, `validateUpdate`, `checkForUpdate`, `downloadUpdate`, `applyUpdate`, `cancelDownload`, `cancelAllDownloads`, `isDownloading`, `getActiveDownloadCount` | Largest feature surface. Bundle lifecycle, channels, signing, rollback. |
+| App Update (in-app, store-driven) | 5 — `getAppUpdateInfo`, `performImmediateUpdate`, `startFlexibleUpdate`, `completeFlexibleUpdate`, `openAppStore` | Wraps Play In-App Updates and iOS App Store check. |
+| App Review | 2 — `requestReview`, `canRequestReview` | Wraps Play In-App Review and SKStoreReviewController. |
+| Background Update | 8 — `enableBackgroundUpdates`, `disableBackgroundUpdates`, `getBackgroundUpdateStatus`, `scheduleBackgroundCheck`, `triggerBackgroundCheck`, `setNotificationPreferences`, `getNotificationPermissions`, `requestNotificationPermissions` | Battery-aware, network-aware silent updates. |
+| Security | 1 — `getSecurityInfo` (+ ChecksumAlgorithm enum, certificate pinning config, 20+ error codes) | Bundle integrity, signing, HTTPS enforcement. |
+| Core | 5 — `initialize`, `isInitialized`, `reset`, `cleanup`, `configure` | Plugin lifecycle. |
+
+**Events** (via `addListener()`): `downloadProgress`, `updateStateChanged`, `backgroundUpdateProgress`, `backgroundUpdateNotification`, `appUpdateStateChanged`, `appUpdateProgress`, `appUpdateAvailable`, `appUpdateReady`, `appUpdateFailed`, `appUpdateNotificationClicked`, `appUpdateInstallClicked`.
+
+**Power-user exports** (`src/index.ts`): `ConfigManager`, `Logger`, `SecurityValidator`, `PluginManager`, `CacheManager`, `BundleManager`, `DownloadManager`, `VersionManager`, `UpdateManager`, error classes (`NativeUpdateError`, `ConfigurationError`, `DownloadError`, `ValidationError`, `StorageError`, `UpdateErrorClass`), rollout/device-info types.
+
+### 2. CLI (`cli/commands/`) — 8 commands
+
+| Command | Purpose |
+|---|---|
+| `init` | Scaffold native-update into an existing Capacitor project |
+| `keys generate` | Generate RSA/ECDSA keypair for bundle signing |
+| `bundle create` | Build a ZIP bundle from a built app dir (excludes node_modules, .git, .env) |
+| `bundle sign` | Sign bundle with private key (SHA-256/512 + RSA/ECDSA) |
+| `bundle verify` | Verify bundle signature with public key |
+| `server start` | Start a local Express dev server for testing updates |
+| `monitor` | Poll an update server and print available updates |
+| `backend create` | Scaffold a Laravel + Nova backend (with greppable `TODO[SCAFFOLD-IMPLEMENT-BEFORE-DEPLOY]` markers) |
+
+### 3. Backend (`backend/` — Laravel 11 + Nova 5)
+
+**API routes** (top-level groups):
+- `/health` — liveness check
+- `/v1/updates/check` — update check (public, signed)
+- `/v1/analytics/{mau,download,install}` — anonymous usage telemetry
+- `/v1/bundles/{build}/download` — bundle download (signed URL)
+- `/dashboard/*` — admin panel (Firebase token required) — apps, builds, api-keys, signing-keys, stats, license management
+- `/admin/*` — internal admin
+- `/webhooks/paypal` — PayPal subscription webhook
+
+**Nova resources** (22): App, User, Build, ApiKey, SigningKey, BuildChannel, BuildStatusFilter, UserStatusFilter, UserPlanFilter, ApiKeyStatusFilter, SigningKeyStatusFilter, ArchiveBuild, ActivateBuild, AssignLicense, DeprecateApiKey, RevokeApiKey, RevokeSigningKey, RotateSigningKey, SetCustomLimits, SuspendUser, UnsuspendUser, Resource (base).
+
+### 4. Platform-native implementations
+
+- **Android** — 10 Kotlin files at `android/src/main/java/com/aoneahsan/nativeupdate/` (NativeUpdatePlugin, LiveUpdatePlugin, AppUpdatePlugin, AppReviewPlugin, BackgroundUpdatePlugin, SecurityManager, BackgroundUpdateWorker, BackgroundUpdateManager, BackgroundNotificationManager, NotificationActionReceiver). Manifest additions documented in `android/manifest-additions.xml`.
+- **iOS** — 8 Swift files at `ios/Plugin/` (NativeUpdatePlugin, LiveUpdatePlugin, AppUpdatePlugin, AppReviewPlugin, BackgroundUpdatePlugin, SecurityManager, BackgroundNotificationManager, WebViewConfiguration). Pod published as `NativeUpdate.podspec`.
+- **Web** — `src/web.ts` (browser fallback for development).
+
+### 5. Example apps (`example-apps/`)
+
+| App | Stack | Demonstrates |
+|---|---|---|
+| `react-capacitor` | React + Vite + Capacitor 8 | Mobile OTA bundle workflow end-to-end |
+| `node-express` | Node.js + Express | Minimal HTTP backend (`/api/updates/check`, `/api/bundles/upload`, bundle serving) |
+
+---
+
+## What we're NOT documenting in v1
+
+- The hosted SaaS dashboard (https://nativeupdate.aoneahsan.com) — that's a marketing surface owned by `website/`, not the SDK docs.
+- Internal Nova action implementation details — Nova is the user-facing surface; how each action is coded is implementation detail.
+- Backend Laravel class internals beyond config + endpoints + setup — the backend is "reference implementation", not a teaching project.
+- v1 / v2 history — single-version site, v3.x only. Migration documented in one page; older API never re-documented.
+
+---
+
+## Information architecture (Diátaxis-aligned)
+
+| Quadrant | Section | Content |
+|---|---|---|
+| Tutorials (learning) | `tutorials/` | End-to-end first-update walkthrough; backend-first walkthrough |
+| How-to guides (problems) | `how-to/` | Channel management; key rotation; rollback; CodePush migration; testing strategy; CI/CD pipelines |
+| Reference (information) | `reference/sdk/`, `reference/cli/`, `reference/backend-api/` | Every method, type, event, command, endpoint |
+| Explanation (understanding) | `concepts/` | How OTA updates work; bundle integrity; update strategies compared; architecture; security model |
+
+Plus three top-level sections: `getting-started/` (intro, installation, quick start, configuration), `platforms/` (Android, iOS, Web specifics), `backend/` (Laravel self-host + Node-Express minimal).
+
+---
+
+## SEO / AEO targets
+
+- **AI bots allowed in robots.txt** (GPTBot, ChatGPT-User, ClaudeBot, anthropic-ai, PerplexityBot, Google-Extended, CCBot, Applebot, Bingbot)
+- `llms.txt` + `llms-full.txt` at site root
+- Per-page JSON-LD: `WebSite`, `Organization`, `BreadcrumbList`, `TechArticle` (with `author`), `FAQPage` (where applicable), `HowTo` (tutorials)
+- Sitemap auto-generated by `@docusaurus/plugin-sitemap`
+- Open Graph + Twitter Card per page (Docusaurus config)
+- Public GitHub repo (boosts crawl discoverability per the `seo-aeo-ranking.md` Wikipedia/GitHub presence rule)
+
+---
+
+## Author credits surfacing
+
+Required everywhere a reader sees brand:
+- Footer: "Built by [Ahsan Mahmood](https://aoneahsan.com)" with linkedin.com/in/aoneahsan, GitHub, npm links
+- About / Credits page (`docs/about-the-author.md`)
+- JSON-LD `author` on every TechArticle
+- `package.json` author + `meta.author` Docusaurus tag
+- README footer
+- Hosted site footer
+
+---
+
+## Out-of-scope items the user has signalled future interest in
+
+- Custom theme matching `website/` design system (deferred — chose default + brand colors for v1)
+- Versioning (deferred until v4 ships)
+- Internationalisation (no signal yet)
+- Custom search beyond Docusaurus default — Algolia DocSearch can be added later

package/docs/docs-site/tracker.json

@@ -0,0 +1,235 @@
+{
+  "$schema": "docs-site-tracker-v1",
+  "description": "Resumable tracker for the native-update Docusaurus documentation site project. Read first on every re-run of the docs-site prompt; honours the 7-day cooldown after full completion.",
+  "project": "native-update",
+  "docs_repo_path": "/home/ahsan/Documents/01-code/projects/native-update-docs/",
+  "docs_repo_remote": "TBD — created in Batch 10 (will be a public GitHub repo)",
+  "hosting": {
+    "platform": "Firebase Hosting (dedicated project)",
+    "firebase_project_id": "TBD — created in Batch 10",
+    "live_url": "TBD"
+  },
+  "scope_doc": "docs/docs-site/scope.md",
+  "plan_doc": "docs/docs-site/plan.md",
+  "total_batches": 10,
+  "current_batch": 10,
+  "progress_pct": 100,
+  "last_run": {
+    "started_at": "2026-05-10",
+    "status": "complete",
+    "completed_at": "2026-05-11",
+    "next_allowed_run_after": "2026-05-18",
+    "cooldown_days": 7,
+    "notes": "All 10 batches complete. Docs site is feature-complete with 58 pages plus deploy-ready discovery + SEO infrastructure. The Firebase Hosting deploy and the public GitHub repo creation are documented in native-update-docs/DEPLOY.md as user-actions — they require `firebase login` and `gh auth` against the user's accounts and cannot be automated from CI/agent context. Cooldown: 7-day soft gate before re-running this prompt. Override conditions: broken yarn build in sibling, published page 404/5xx, Lighthouse SEO drops below 95, production incident."
+  },
+  "batches": [
+    {
+      "id": 1,
+      "title": "Foundation & first pages",
+      "status": "completed",
+      "started_at": "2026-05-10",
+      "completed_at": "2026-05-10",
+      "skills_invoked": ["documentation-writer", "ai-seo", "copywriting"],
+      "deliverables": [
+        "native-update: docs/docs-site/scope.md",
+        "native-update: docs/docs-site/plan.md",
+        "native-update: docs/docs-site/tracker.json (this file)",
+        "native-update: root CLAUDE.md + AGENTS.md docs-site record",
+        "native-update-docs: package.json, tsconfig.json, docusaurus.config.ts, sidebars.ts, .gitignore, .editorconfig",
+        "native-update-docs: src/css/custom.css (brand palette + dark mode)",
+        "native-update-docs: src/pages/index.tsx (homepage)",
+        "native-update-docs: static/img/logo.svg, favicon.svg, social-card.svg",
+        "native-update-docs: static/robots.txt (skeleton)",
+        "native-update-docs: docs/intro.md, docs/getting-started/installation.md, docs/getting-started/quick-start.md",
+        "native-update-docs: docs/about-the-author.md",
+        "native-update-docs: README.md, CLAUDE.md, AGENTS.md",
+        "native-update-docs: git init + first commit",
+        "~/.dev-ports.json: register port 5960"
+      ],
+      "verification": "yarn build in sibling exits 0; folder structure matches sidebars.ts; homepage renders Ahsan author block",
+      "commit_native_update": "TBD",
+      "commit_docs_repo": "TBD"
+    },
+    {
+      "id": 2,
+      "title": "SDK Reference: Live Update (OTA)",
+      "status": "completed",
+      "started_at": "2026-05-10",
+      "completed_at": "2026-05-10",
+      "skills_invoked": ["documentation-writer", "ai-seo"],
+      "deliverables": [
+        "native-update-docs: docs/reference/sdk/live-update/overview.md (~1100 words, mental model, FAQ, mermaid state diagram)",
+        "native-update-docs: docs/reference/sdk/live-update/methods.md (~2500 words, all 20 methods grouped: sync/check, download, apply/rollback, inspect, configure, maintenance; signatures verbatim from src/definitions.ts)",
+        "native-update-docs: docs/reference/sdk/live-update/types.md (10 types: SyncOptions, SyncResult, DownloadOptions, DownloadUpdateOptions, BundleInfo, DeleteOptions, LatestVersion, CheckForUpdateResult, ValidateOptions, ValidationResult)",
+        "native-update-docs: docs/reference/sdk/live-update/enums.md (UpdateStrategy, UpdateMode, ChecksumAlgorithm, SyncStatus, BundleStatus + Live-Update subset of UpdateErrorCode)",
+        "native-update-docs: docs/reference/sdk/live-update/events.md (downloadProgress + updateStateChanged with cleanup pattern)",
+        "native-update-docs: docs/reference/sdk/live-update/config.md (LiveUpdateConfig field-by-field + recommended prod/dev examples)",
+        "native-update-docs: sidebars.ts — SDK Reference > Live Update (OTA) category active"
+      ],
+      "verification": "yarn build clean (no broken anchors after 2 explicit-id fixes); 6 pages reachable at /reference/sdk/live-update/*; explicit anchor IDs added for setChannel, setUpdateUrl, UpdateErrorCode to make slugs stable"
+    },
+    {
+      "id": 3,
+      "title": "SDK Reference: App Update + App Review",
+      "status": "completed",
+      "started_at": "2026-05-10",
+      "completed_at": "2026-05-10",
+      "skills_invoked": ["documentation-writer", "ai-seo"],
+      "deliverables": [
+        "native-update-docs: docs/reference/sdk/app-update/overview.md (mental model, when-to-use matrix, platform behaviour matrix Android/iOS/Web, Play priority 0-5 table, mermaid sequence diagram, 6-entry FAQ block)",
+        "native-update-docs: docs/reference/sdk/app-update/methods.md (all 5 methods: getAppUpdateInfo, performImmediateUpdate, startFlexibleUpdate, completeFlexibleUpdate, openAppStore — with platform notes, throws, examples)",
+        "native-update-docs: docs/reference/sdk/app-update/types.md (AppUpdateInfo with 10 fields + decision-matrix code; OpenAppStoreOptions)",
+        "native-update-docs: docs/reference/sdk/app-update/events.md (7 events: appUpdateStateChanged + appUpdateProgress + appUpdateAvailable + appUpdateReady + appUpdateFailed + appUpdateNotificationClicked + appUpdateInstallClicked; embeds InstallStatus enum reference)",
+        "native-update-docs: docs/reference/sdk/app-update/config.md (AppUpdateConfig field-by-field with prod recipe)",
+        "native-update-docs: docs/reference/sdk/app-review/overview.md (Apple 3-per-365 rule explained, default throttling table, mental model, 6-entry FAQ block)",
+        "native-update-docs: docs/reference/sdk/app-review/methods.md (canRequestReview + requestReview with the recommended call-site pattern; ReviewResult + CanRequestReviewResult inline)",
+        "native-update-docs: docs/reference/sdk/app-review/config.md (AppReviewConfig field-by-field; prod + dev recipes; Apple-throttle warning admonition)",
+        "native-update-docs: sidebars.ts — App Update + App Review categories activated under SDK Reference"
+      ],
+      "verification": "yarn build clean (one broken-link to Batch 4 background-update/overview was fixed by converting to italic placeholder); 8 new pages reachable at /reference/sdk/app-update/* and /reference/sdk/app-review/*"
+    },
+    {
+      "id": 4,
+      "title": "SDK Reference: Background Updates + Security + Core",
+      "status": "completed",
+      "started_at": "2026-05-11",
+      "completed_at": "2026-05-11",
+      "skills_invoked": ["documentation-writer", "ai-seo"],
+      "deliverables": [
+        "native-update-docs: docs/reference/sdk/background-update/overview.md (mental model, when-to-use matrix, platform behaviour matrix Android WorkManager / iOS BGTaskScheduler / Web, mermaid flowchart of OS-fired task gates, sample wiring, 6-entry FAQ explaining 'how often does this actually run')",
+        "native-update-docs: docs/reference/sdk/background-update/methods.md (all 8 methods: enableBackgroundUpdates, disableBackgroundUpdates, getBackgroundUpdateStatus, scheduleBackgroundCheck, triggerBackgroundCheck, setNotificationPreferences, getNotificationPermissions, requestNotificationPermissions; embedded BackgroundUpdateStatus + BackgroundCheckResult + NotificationPermissionStatus type tables)",
+        "native-update-docs: docs/reference/sdk/background-update/config.md (BackgroundUpdateConfig 12 fields + NotificationPreferences 10 fields + BackgroundUpdateType + NotificationPriority enums; production recipe; iOS Info.plist BGTaskSchedulerPermittedIdentifiers note)",
+        "native-update-docs: docs/reference/sdk/background-update/events.md (backgroundUpdateProgress + backgroundUpdateNotification with payloads, lifecycle, action flow; 'apply update on tap' example)",
+        "native-update-docs: docs/reference/sdk/security/overview.md (3-layer security model table, getSecurityInfo + SecurityInfo type, SecurityConfig field-by-field with deprecated secureStorage call-out, threat-model coverage table, 6-entry FAQ on key rotation + clock skew + at-rest encryption)",
+        "native-update-docs: docs/reference/sdk/security/error-codes.md (full UpdateErrorCode catalogue grouped by domain: network, download, security, install, permission, app-update, app-review, config; mapping to typed Error classes for instanceof checks)",
+        "native-update-docs: docs/reference/sdk/security/certificate-pinning.md (CertificatePinning + CertificatePin types, working OpenSSL recipe to extract SHA-256 SPKI pins, operational checklist with the two-pin rule, when-NOT-to-use guidance, 5-entry FAQ on Let's Encrypt + HPKP + captive portals)",
+        "native-update-docs: docs/reference/sdk/core/lifecycle.md (initialize, isInitialized, configure, reset, cleanup with mermaid state diagram of allowed transitions; clarification of the dual-meaning reset())",
+        "native-update-docs: docs/reference/sdk/core/config.md (PluginInitConfig — 24 fields grouped: server, live-update shorthand, download tuning, security, filesystem injection, native app-update/review, logging; ms-vs-seconds units gotcha highlighted; production recipe)",
+        "native-update-docs: sidebars.ts — Background Update + Security + Core categories activated under SDK Reference (SDK Reference section now complete)",
+        "native-update-docs: app-update/events.md — restored real link to background-update/overview (was Batch-3 italic placeholder)"
+      ],
+      "verification": "yarn build clean; 9 new pages render at /reference/sdk/background-update/* and /reference/sdk/security/* and /reference/sdk/core/*; total docs site now 27 pages; SDK Reference section feature-complete"
+    },
+    {
+      "id": 5,
+      "title": "CLI Reference",
+      "status": "completed",
+      "started_at": "2026-05-11",
+      "completed_at": "2026-05-11",
+      "skills_invoked": ["documentation-writer", "ai-seo"],
+      "deliverables": [
+        "native-update-docs: docs/reference/cli/overview.md (~1100 words — when-to-use matrix, install, quick-start workflow, exit codes, output conventions, default-artifact-locations table, what-the-CLI-does-NOT-do, FAQ)",
+        "native-update-docs: docs/reference/cli/init.md (interactive 4-prompt walkthrough, --example + --backend flags, generated config shape, common errors, limitations)",
+        "native-update-docs: docs/reference/cli/keys-generate.md (RSA 2048/4096 + EC P-256/P-384 matrix, output filenames + chmod 600, algorithm-choice guidance, rotation policy, install-public-key recipe)",
+        "native-update-docs: docs/reference/cli/bundle-create.md (flags table, examples, what-the-bundle-contains, safety refused-bundle list (node_modules/.git/.env*), reproducibility note, success output sample)",
+        "native-update-docs: docs/reference/cli/bundle-sign.md (RSA-SHA256, .sig sidecar JSON shape, signing in CI, common PEM errors, why backend must serve the sidecar)",
+        "native-update-docs: docs/reference/cli/bundle-verify.md (sidecar lookup convention, valid vs invalid output, CI release-gate pattern, how-verification-works step-by-step, limitations)",
+        "native-update-docs: docs/reference/cli/server-start.md (4 endpoints documented: /api/latest, /api/bundles, /bundles/<file>, /health; localhost-vs-LAN caveat; what-it-does-NOT-do block; stopping convention)",
+        "native-update-docs: docs/reference/cli/monitor.md (dashboard preview, expected /api/stats response shape, 5s polling + 5-failure bailout, SIGINT/SIGTERM handling, headless-mode limitation)",
+        "native-update-docs: docs/reference/cli/backend-create.md (express/firebase/vercel, SCAFFOLD_BANNER explained, TODO[SCAFFOLD-IMPLEMENT-BEFORE-DEPLOY] grep workflow, when-NOT-to-use guidance steering to example-apps/node-express + backend/)",
+        "native-update-docs: sidebars.ts — CLI Reference category active under SDK Reference; removed commented-out Batch-5 placeholder block"
+      ],
+      "verification": "yarn build clean (no broken-link errors after build); 9 new pages reachable at /reference/cli/*; build output verified via ls of build/reference/cli/ — all 9 .html files present"
+    },
+    {
+      "id": 6,
+      "title": "Backend setup guides",
+      "status": "completed",
+      "started_at": "2026-05-11",
+      "completed_at": "2026-05-11",
+      "skills_invoked": ["documentation-writer", "technical-writing"],
+      "deliverables": [
+        "native-update-docs: docs/backend/overview.md (~1300 words — what-the-backend-does endpoint table, three options matrix (Hosted SaaS / Self-host Laravel / Roll your own), how-to-choose chooser table, what-stays-the-same regardless of backend invariants block, next-steps fork)",
+        "native-update-docs: docs/backend/laravel-nova-self-host.md (~2400 words — what-you're-deploying overview, prerequisites (PHP 8.2+, MySQL/Postgres, Redis, supervisor), clone+install+build, env walk-through (APP_KEY / CORS / FIREBASE / NATIVE_UPDATE_FIREBASE_AUTO_CREATE / PAYPAL / ADMIN_EMAILS), schema notes (~14 tables — users/apps/builds/api_keys/signing_keys/analytics), four storage backends (FilesHub default, Drive, S3/R2, local), queue worker with sample systemd unit, optimize-cache sequence, Firebase token verification + clock-skew warning, Nova license auth.json, sample nginx vhost, smoke-test commands)",
+        "native-update-docs: docs/backend/node-express-minimal.md (~1700 words — what-it-implements vs what-it-doesn't (skips analytics), running locally, contract mapping endpoint-by-endpoint with code snippets pulled from the actual repo, what production needs vs what the example has (signing URLs, checksums, signatures, rate limiting), framework-translation guidance for Hono/Fastify/etc., when-to-graduate-from-this-example triggers)",
+        "native-update-docs: docs/backend/api-contract.md (~2100 words — full wire spec for 6 endpoints (health, /updates/check, /bundles/{id}/download, /analytics/mau, /analytics/download, /analytics/install), auth schemes table (API-key vs signed URL vs Firebase token), header tables, response shapes with field semantics, error envelope convention, field-naming-reminder block listing the 11 canonical fields that custom backends must NOT rename)",
+        "native-update-docs: docs/backend/nova-admin-overview.md (~1700 words — group structure (Content vs Security), tour of 5 resources (User/App/Build/ApiKey/SigningKey) with fields + relationships + actions + when-to-come-here use-cases, 10 Nova Actions reference table, AuthServiceProvider + admin-bypass `before` hooks pattern documented, what-Nova-is-NOT-for boundary block)",
+        "native-update-docs: sidebars.ts — Backend category activated; commented Batch-6 placeholder removed"
+      ],
+      "verification": "yarn build clean (no broken-link errors); 5 new pages reachable at /backend/*; ls of build/backend/ confirms api-contract.html + laravel-nova-self-host.html + node-express-minimal.html + nova-admin-overview.html + overview.html all generated"
+    },
+    {
+      "id": 7,
+      "title": "Platform guides (Android, iOS, Web)",
+      "status": "completed",
+      "started_at": "2026-05-11",
+      "completed_at": "2026-05-11",
+      "skills_invoked": ["documentation-writer", "technical-writing", "capacitor-best-practices"],
+      "deliverables": [
+        "native-update-docs: docs/platforms/android.md (~2100 words — Capacitor + gradle versions, 6 required permissions with sensitive vs non-sensitive breakdown and tools:node='remove' opt-out for non-background-update apps, manifest-additions <service> + <receiver> with explanation of tools:node='merge' and exported=false, WorkManager constraints (NetworkType.UNMETERED / setRequiresBatteryNotLow / setRequiresCharging) with Doze + App Standby caveats, Play Core 2.1.0 + Play Review 2.0.1 with internal-testing-track gotcha, network security config for cleartext localhost, ProGuard rules + likely failure modes, signing setup, Play Console rejection rules (merged-manifest sensitive permissions + foreground service notification requirement), edge-to-edge note, smoke-test commands with adb logcat filters)",
+        "native-update-docs: docs/platforms/ios.md (~2400 words — deployment target iOS 14, SPM vs CocoaPods, BGTaskSchedulerPermittedIdentifiers with two identifiers, UIBackgroundModes for background-app-refresh + background-processing, NSAppTransportSecurity with localhost exception pattern, PrivacyInfo.xcprivacy template covering UserDefaults CA92.1 + FileTimestamp C617.1, SKStoreReviewController throttling (Apple 3/365 + plugin's launches/days/lastPrompt knobs), App Store Review Guideline 2.5.2 compliance with rejection-reason examples and how the OTA flow stays inside the JS-in-WKWebView carve-out, Keychain accessibility level explanation, TestFlight + Xcode debugging tips with BGTaskScheduler LLDB simulate command, what-the-plugin-does-NOT-do block (no APNs, no force-update on iOS, no Watch/tvOS), smoke-test commands)",
+        "native-update-docs: docs/platforms/web.md (~1500 words — when web target activates, what-works method-by-method (configure/getSecurityInfo/current/list/delete/notifyAppReady/reload/setChannel/getLatest/openAppStore/requestReview), what's-stubbed throwing PLATFORM_NOT_SUPPORTED, service-worker update path with full register+message-passing code, three legitimate use cases (dev fallback, PWA deployment, E2E tests), three when-NOT-to-use callouts, configuration that affects web vs ignored fields, browser support matrix, smoke-test snippet)",
+        "native-update-docs: sidebars.ts — Platforms category activated; commented Batch-7 placeholder removed"
+      ],
+      "verification": "yarn build clean (no broken-link errors); 3 new pages reachable at /platforms/*; ls of build/platforms/ confirms android.html + ios.html + web.html generated; total docs site now 44 pages."
+    },
+    {
+      "id": 8,
+      "title": "Tutorials & how-to guides",
+      "status": "completed",
+      "started_at": "2026-05-11",
+      "completed_at": "2026-05-11",
+      "skills_invoked": ["documentation-writer", "ai-seo", "copywriting"],
+      "deliverables": [
+        "native-update-docs: docs/tutorials/first-ota-update.md (~1900 words — 10-step happy-path walkthrough: install plugin → keys generate → scaffold config → wire SDK into boot code → sign up on SaaS + create app + paste API key + register public key → bundle → sign → upload → device install + verify → ship a real visible-change update; explicit what-you-did-not-do block calling out channels/rollouts/CI/key-rotation/rollback as separate how-tos)",
+        "native-update-docs: docs/tutorials/backend-first-walkthrough.md (~1900 words — 13-step self-hosted Laravel + Nova walkthrough: clone+install → DB setup → .env walk-through → migrate → optimise+serve → Nova login with tinker-seed-admin-user pattern → first App + ApiKey + SigningKey → wire app to LAN → bundle/sign/upload → verify device trace through Laravel log; covers 10.0.2.2 vs localhost vs LAN-IP nuances)",
+        "native-update-docs: docs/how-to/manage-channels.md (~1100 words — channel model with production/staging/beta/canary table, declare channels on App, tag bundles at build time with --channel, switch device at runtime via setChannel(), build channel UI for internal users, promote-between-channels via re-upload vs re-tag, common pitfalls including reset()-after-setChannel and case-sensitive matching)",
+        "native-update-docs: docs/how-to/rotate-signing-keys.md (~1700 words — scheduled-rotation vs emergency-revoke split with how-the-installed-binary-pins-the-trusted-key explanation; 7-step multi-key transition with publicKey-as-array approach + 95%-app-store-adoption gate; 5-step emergency-revoke path with App Store / Play Store expedited-review note; three how-NOT-to-rotate anti-patterns)",
+        "native-update-docs: docs/how-to/roll-back-bundle.md (~1300 words — 3-layer strategy: automatic crash-rollback via notifyAppReady() 60s window, cohort-wide rollback via Rollout%=0 or Is_Active=false or downgrade-as-latest, explicit per-device NativeUpdate.rollback() with code; what gets recorded in the Build counters; what rollback does NOT do — native code, offline devices, downstream data)",
+        "native-update-docs: docs/how-to/migrate-from-codepush.md (~1700 words — App Center retirement context, concept-mapping table (deployment→channel, deployment-key→api-key, mandatoryInstallMode→bundle.mandatory etc.), 6-step migration with side-by-side phase, sync-option mapping table, common gotchas (mandatory updates work differently, no bundle diffs, signing now mandatory))",
+        "native-update-docs: docs/how-to/ci-cd-github-actions.md (~1600 words — production GitHub Actions workflow: secrets setup, full .github/workflows/ota-release.yml with concurrency block + umask + verify-as-release-gate + cleanup-always + workflow_dispatch channel chooser; manual-approval pattern via GitHub Environments; cache wisdom + gotchas; what's-not-included block — tests, versioning, notifications, rollback automation)",
+        "native-update-docs: docs/how-to/test-bundles-locally.md (~1500 words — three local-test loops in increasing fidelity: bundle-verify smoke test → native-update server start dev server → full LAN test with real backend; per-loop what-catches vs what-skips matrix; LAN setup with macOS+Linux IP discovery, Android cleartext config, iOS NSAllowsLocalNetworking; iteration-speed tips including version-badge component)",
+        "native-update-docs: sidebars.ts — Tutorials + How-to guides categories activated; commented Batch-8 placeholder removed"
+      ],
+      "verification": "yarn build clean (no broken-link errors); 8 new pages reachable at /tutorials/* + /how-to/*; ls of build/tutorials/ + build/how-to/ confirms all 8 .html files generated; total docs site now 52 pages."
+    },
+    {
+      "id": 9,
+      "title": "Concepts & explanations",
+      "status": "completed",
+      "started_at": "2026-05-11",
+      "completed_at": "2026-05-11",
+      "skills_invoked": ["documentation-writer", "ai-seo"],
+      "deliverables": [
+        "native-update-docs: docs/concepts/how-ota-updates-work.md (~2200 words — five-moving-parts framing, 11-step lifecycle from package→sign→upload→sync→server-decision→download→checksum→signature-verify→stage→atomic-swap→verify-or-rollback, why-this-design-not-simpler covering integrity+atomicity+reversibility constraints, what-OTA-gives-you-over-web-deployment)",
+        "native-update-docs: docs/concepts/bundle-integrity-and-signing.md (~1900 words — envelope-and-bag metaphor for two-layer model, what SHA-256 alone catches (bitflips, CDN swaps, server confusion), what SHA-256 does NOT (server-attested-checksum-attack), what signing adds, five-entity trust chain breakdown, what signing does NOT protect (private-key compromise, buggy bundles, replay, native code, leaked-but-unrevoked key, side channels), algorithm-choice rationale (RSA universal+deterministic+small-overhead))",
+        "native-update-docs: docs/concepts/update-strategies-compared.md (~1900 words — four-strategy comparison table with one-line decision tree, immediate/on-app-start/on-app-resume/manual deep-dives with user-experience consequences and three-legitimate-use-cases per strategy, background-updates-orthogonal-to-strategies explanation, what's-not-in-the-model (no minimum-age-before-apply, no must-apply-by deadline))",
+        "native-update-docs: docs/concepts/architecture.md (~2200 words — five-component overview (CLI, backend, object store, device SDK, dashboard), three mermaid diagrams (build-time flowchart, deploy-time sequence, runtime sequence), trust-boundaries diagram with four-zone breakdown (your-control / semi-exposed / device / hostile), how-the-pieces-version-together explaining SDK-via-app-store vs backend-via-redeploy intersection rule)",
+        "native-update-docs: docs/concepts/security-model.md (~2000 words — three-class threat model (passive observer / active MITM / compromised infrastructure), three-layer defense (transport HTTPS+pinning / content checksum+signature / runtime crash-rollback), explicit what's-in-scope vs what's-out-of-scope (private key compromise, dashboard auth compromise, malicious-but-signed bundles, supply-chain via deps, jailbroken devices, side channels, DoS), six operational assumptions the model depends on, regulated-industries note on FIPS+SOC2+air-gapped)",
+        "native-update-docs: docs/concepts/error-handling-philosophy.md (~1800 words — fail-closed-on-correctness vs fail-open-on-availability framing, list of what-fails-closed (signature, checksum, HTTPS-in-prod, plugin-not-initialised, required-fields) vs what-fails-open (analytics writes, background scheduling, notification rendering, optional callbacks), typed-error-codes-everywhere with switch-on-code example, host-app-must-keep-running rule with safeBootstrapOta pattern, calibration rationale for 60s notifyAppReady window + 30min signed-URL TTL)",
+        "native-update-docs: sidebars.ts — Concepts category activated; commented Batch-9 placeholder removed"
+      ],
+      "verification": "yarn build clean (no broken-link errors); 6 new pages reachable at /concepts/*; ls of build/concepts/ confirms architecture.html + bundle-integrity-and-signing.html + error-handling-philosophy.html + how-ota-updates-work.html + security-model.html + update-strategies-compared.html generated; mermaid diagrams rendered (theme already enabled in docusaurus.config.ts); total docs site now 58 pages."
+    },
+    {
+      "id": 10,
+      "title": "SEO + Firebase deploy + GitHub publish",
+      "status": "completed",
+      "started_at": "2026-05-11",
+      "completed_at": "2026-05-11",
+      "skills_invoked": ["ai-seo", "firebase-hosting-basics"],
+      "deliverables": [
+        "native-update-docs: static/robots.txt — 30+ AI-bot allow list (Googlebot, Bingbot, DuckDuckBot, Applebot, YandexBot, Baiduspider, Slurp, GPTBot, ChatGPT-User, OAI-SearchBot, ClaudeBot, anthropic-ai, Claude-Web, PerplexityBot, Perplexity-User, Google-Extended, Applebot-Extended, YouBot, CCBot, Diffbot, cohere-ai/cohere-training-data-crawler, Meta-ExternalAgent, FacebookBot, Amazonbot, MistralAI-User) + 8-bot block list (Ahrefs/Semrush/MJ12/Dot/BLEX/Petal/serpstat/SiteAudit) + Sitemap directive",
+        "native-update-docs: static/llms.txt (9.6 KB) — llmstxt.org-format structured index covering all 58 pages grouped by Diátaxis quadrant (Tutorials, How-to, SDK Reference subsections, CLI Reference, Backend, Platforms, Concepts), with absolute URLs ready for LLM consumption",
+        "native-update-docs: static/llms-full.txt (15.4 KB) — single-document long-form summary covering project facts, four feature areas, 11-step OTA lifecycle, wire contract, CLI commands, three backend options, platform requirements per Android/iOS/Web, security model, update strategies, error handling philosophy, performance defaults, CodePush migration mapping, author contact",
+        "native-update-docs: static/humans.txt — team/thanks/site credits per humanstxt.org convention",
+        "native-update-docs: static/.well-known/security.txt (RFC 9116) — Contact / Expires (2027-05-11) / Preferred-Languages / Canonical / Policy fields plus inline responsible-disclosure policy",
+        "native-update-docs: static/sitemap-index.json — machine-readable section index complementing sitemap.xml; lists 8 content hubs with page counts and Diátaxis-type tags; discovery file URLs for sitemap/robots/llms/humans/security",
+        "native-update-docs: docusaurus.config.ts — headTags array with canonical link, RSS alternate, theme-color, application-name + 3 application/ld+json blocks (WebSite with publisher Person, SoftwareApplication with offers + softwareVersion 3.0.0 + license, Organization with sameAs network); themeConfig.metadata extended with description fallback, expanded keywords (15 terms), max-image-preview:large robots meta, twitter:site, og:locale, og:image:width/height, article:author",
+        "native-update-docs: firebase.json — public=build, cleanUrls, SPA-style 404 rewrite, Cache-Control immutable for assets (jpg|png|svg|js|css|woff2 = 1 year), HTML 5min, robots/sitemap/llms.txt 1hr, security headers (X-Content-Type-Options nosniff, Referrer-Policy strict-origin-when-cross-origin, Permissions-Policy, Strict-Transport-Security HSTS 1yr+preload)",
+        "native-update-docs: .firebaserc — default project 'native-update-docs'",
+        "native-update-docs: package.json — added firebase:emulate / firebase:deploy / firebase:deploy:preview yarn scripts (use npx -y firebase-tools@latest per global CLAUDE.md Firebase rule); removed default docusaurus deploy script (Firebase replaces GitHub Pages)",
+        "native-update-docs: DEPLOY.md — 6-section deploy runbook covering prerequisites, one-time GitHub publish via gh CLI, one-time Firebase project create + custom domain DNS, recurring deploy workflow with preview channels, post-deploy Google Search Console + Bing Webmaster Tools submission, healthcheck curl commands, freshness cycle, troubleshooting for 5 common failure modes"
+      ],
+      "verification": "yarn typecheck clean; yarn build clean — 6 discovery files materialised in build/ (robots.txt 2.6KB, llms.txt 9.7KB, llms-full.txt 15.4KB, humans.txt 0.9KB, sitemap.xml 10.6KB, sitemap-index.json 2.9KB) plus build/.well-known/security.txt; build/index.html contains 3 application/ld+json blocks (WebSite + SoftwareApplication + Organization) + canonical link + new robots/theme-color/twitter:site meta tags verified by grep. Firebase deploy + GitHub publish are user-actions documented in DEPLOY.md (require user-account auth)."
+    }
+  ],
+  "resume_protocol": "On every re-run of the docs-site prompt: read this file FIRST. If last_run.status=='complete' AND today<next_allowed_run_after, skip and tell the user the date. If 'in_progress', find lowest-indexed batch with status!='completed' and resume there. After Batch 10, set status='complete', completed_at=today, next_allowed_run_after=today+7d.",
+  "override_conditions": [
+    "Explicit user bypass",
+    "yarn build broken in sibling repo",
+    "Published page returns 404 or 5xx",
+    "Lighthouse SEO drops below 95",
+    "Production incident affecting users"
+  ]
+}

package/docs/error-handling-tracking.md

@@ -0,0 +1,37 @@
+# Error Handling Tracking (R-023)
+
+This registry lists every component, page, hook, or service that wires errors into the centralised `trackError` (`website/src/lib/errorTracking.ts`). Every new feature added MUST add itself here.
+
+**Service:** `website/src/lib/errorTracking.ts`
+**Destinations:** Firebase Analytics (always on if Firebase keys present) + Sentry / Microsoft Clarity / Amplitude (off until their env keys are set)
+
+**Last audited:** 2026-04-25
+
+| Path | Type | Wired? | Notes |
+|---|---|---|---|
+| `src/components/ErrorBoundary.tsx` | Component | Pending | Top-level error boundary should call `trackError` in `componentDidCatch` — incremental migration. |
+| `src/services/auth-service.ts` | Service | Pending | Wrap Firebase auth errors. |
+| `src/services/google-drive-service.ts` | Service | Pending | OAuth + Drive API errors. |
+| `src/services/bundle-upload-service.ts` | Service | Pending | Upload failures, integrity verification failures. |
+| `src/services/manifest-generator.ts` | Service | Pending | Manifest assembly errors. |
+| `src/lib/analytics.ts` | Service | N/A | Analytics; uses its own internal logger swallow. |
+| `src/lib/firebase.ts` | Service | N/A | Init-time only — failure here is rendered by the app shell. |
+
+## How to wire a new module
+
+```ts
+import { trackError } from '@/lib/errorTracking';
+
+try {
+  await doRiskyThing();
+} catch (err) {
+  trackError(err, { surface: 'upload', step: 'verify_checksum' });
+  throw err; // rethrow so callers see the failure too
+}
+```
+
+## Env keys
+
+- `VITE_SENTRY_DSN` — when set + `@sentry/browser` installed, errors flow to Sentry
+- `VITE_CLARITY_PROJECT_ID` — when set + Clarity script loaded, last error pinned to session
+- `VITE_AMPLITUDE_API_KEY` — when set + Amplitude script loaded, errors emitted as `app_error` events