native-update 1.4.9 → 3.1.0

package/docs/project-audit/PRODUCTION-READINESS-AUDIT-2026-05-08.md

@@ -0,0 +1,275 @@
+# Production-Readiness Audit — native-update Monorepo
+
+**Date:** 2026-05-08
+**Auditor:** Claude Code (Opus 4.7, 1M context)
+**Scope:** Whole monorepo (root plugin + cli + android + ios + backend + website + example-apps + docs)
+**Method:** Six parallel scoped audit agents (plugin/native, website UI, SEO/AEO, backend, examples+roadmap, security/env). Findings cross-verified against source files before recording here.
+**Companion files:**
+- Batch plan: `docs/project-audit/BATCH-PLAN.md`
+- Tracker (resumeable, 7-day cooldown): `docs/tracking/production-readiness-audit-tracker.json`
+
+---
+
+## Verdict
+
+The monorepo is **~85% production-ready**. Three real npm-publish-blockers + several backend hardening gaps + per-page SEO content gaps are the main risks. No active secret exposure, no banned packages, no broken builds in the root plugin or website.
+
+**Severity legend:** **B** = Blocker (must fix before next release / public push). **I** = Important (fix before production cutover). **N** = Nit / polish.
+
+---
+
+## 1. Banned-Package Phase 0 Check
+
+`grep -nE "@capacitor-firebase/(crashlytics|performance)|@capawesome/capacitor-torch" package.json **/package.json` → **zero matches**. ✅ No bans violated.
+
+---
+
+## 2. Findings — Plugin Source / CLI / Native (root, src/, cli/, android/, ios/)
+
+### Blockers
+
+- **B1 — `package.json` `files` array is missing `android/manifest-additions.xml`**
+  File: `package.json:13-26`. The file exists at `android/manifest-additions.xml` and is required at install-time by Capacitor's manifest merger. Without it in the npm package, downstream Android builds will be missing the additions block. **Fix:** add `"android/manifest-additions.xml"` to the `files` array.
+
+- **B2 — `cli/commands/backend-create.js` ships placeholder TODOs in scaffolded backend templates**
+  File: `cli/commands/backend-create.js:144,176,177,290,309,310,493,494`. Eight `TODO` markers in Express/Vercel/Firebase scaffolding for: bundle lookup, file storage, DB save. The CLI generates these as ready-to-deploy code, but they are not. **Fix:** either (a) implement the missing logic and wire to `node-express` example as the canonical scaffold, or (b) prepend each generated file with a clear `// SCAFFOLD — implement before deploying` banner and document expected wiring.
+
+- **B3 — `cli/commands/monitor.js` has unmanaged `setInterval` + spinner-leak on exit**
+  File: `cli/commands/monitor.js:14-62`. `setInterval` fires every 5s with an async callback; failures stack indefinitely. `ora` spinner is started but never stopped on exit/failure — terminal is left in undefined state. **Fix:** capture interval ID, install `SIGINT`/`SIGTERM` handlers that `clearInterval` + `spinner.stop()`; bail the loop on consecutive failures.
+
+### Important
+
+- **I1 — Direct `console.*` in plugin source (violates centralized-logger convention)**
+  Files: `src/web.ts` (18 calls), `src/core/event-emitter.ts:52`. Plugin already has a `Logger` singleton; security paths (checksum, signature) and event-emitter error path bypass it. **Fix:** replace `console.{warn,error,log}` with `Logger.{warn,error,info}` everywhere outside the logger module itself. Note: this is the *plugin's* logger, separate from website logger.
+
+- **I2 — `ios/Plugin/NativeUpdatePlugin.swift:72-75` calls `disableBackgroundUpdatesInternal()` to bypass inaccessible Capacitor SDK constructors**
+  Workaround for SDK API surface, fragile if the SDK changes. **Fix:** add a `// CAPACITOR-SDK-WORKAROUND:` comment block referencing the SDK version this assumes, and a `// TODO: revisit on Capacitor 8.x update` line so future bumps don't silently break.
+
+- **I3 — `cli/commands/backend-create.js` file-list completeness vs `node-express` template**
+  Several runtime concerns (signature verify, rollout cohort logic, channel filtering) live in docs only, not in the scaffold. **Fix (low-risk):** ensure `cli/templates/express/` mirrors `example-apps/node-express/` structure 1:1 so users get a working scaffold by default.
+
+### Nits
+
+- **N1 — `rollup.config.js:61,63` duplicate `comments` key in terser format**
+  Line 63 silently overrides line 61. Functional but a typo. **Fix:** delete the earlier line.
+
+### State-vs-claim notes
+
+- All 28+ public methods in `src/definitions.ts` have matching implementations in `src/web.ts`, `ios/Plugin/`, `android/src/main/`. **API parity ✓**.
+- HTTPS enforcement, SHA-256 checksum + RSA/ECDSA signature paths are well-implemented and fail-closed. **Crypto correct ✓**.
+- TypeScript `strict: true`, Vitest 89/89 green. **Build clean ✓**.
+
+---
+
+## 3. Findings — Website (`website/`)
+
+### Blockers
+
+None. `yarn typecheck` + `yarn build` complete cleanly; sitemap + postbuild SEO HTML generation succeed across all 16 routes.
+
+### Important
+
+- **I4 — Custom `Dialog.tsx` lacks key a11y primitives**
+  File: `website/src/components/ui/Dialog.tsx`. Missing `role="dialog"` + `aria-modal="true"` on `DialogContent`, no ESC-key handler on overlay, no focus restore on close, no focus trap. **Fix:** either migrate to `@radix-ui/react-dialog` (already a transitive dep via other Radix primitives in package.json) — strongly recommended per project's Radix-first rule — or harden the custom one with `aria-labelledby`, ESC handler, focus trap, focus restore.
+
+- **I5 — Dashboard dialog state held in `useState` instead of URL search params (violates URL-State-Preservation rule)**
+  File: `website/src/pages/dashboard/AppsPage.tsx:50,55`. `deleteDialog` and `formDialog` open-state both in `useState`. Refresh closes them — wrong UX. **Fix:** convert to `?deleteId=ID` and `?formMode=create|edit&appId=ID` per project rule. Audit all other dashboard pages for the same pattern.
+
+- **I6 — TanStack Query: per-page `staleTime` overrides not audited**
+  Global default in `App.tsx` is 30s + `gcTime: 5m`. Spot-check individual `useQuery` sites in `src/hooks/` and `src/pages/dashboard/` for ad-hoc overrides that disable cache. **Fix:** sweep, document the project-wide cache contract, set `queryKey` factories per resource (already mostly done).
+
+### Nits
+
+- BootLoader present (✓), 7-option Theme Customizer present (✓), URL state hooks present (`useUrlState.ts`-style), 47 aria-* attributes across components.
+- `vite-env.d.ts` is minimal (only `__APP_VERSION__`) — env types are validated through `src/config/env.ts` `getMissingRequiredEnv()` at boot. ✓.
+
+---
+
+## 4. Findings — SEO / AEO / AIO (`website/`)
+
+Today is 2026-05-08; last full SEO pass was 2026-04-24 (14 days ago — within commit-delta gate window).
+
+### Blockers
+
+None on infrastructure — robots.txt allows GPTBot/ClaudeBot/PerplexityBot/Google-Extended/Bingbot/etc., sitemap.xml + feed.xml + llms.txt + llms-full.txt + ai.txt + humans.txt + security.txt all present.
+
+### Important
+
+- **I7 — Per-page-uniqueness floor not met on three core marketing pages**
+  Files: `website/src/pages/FeaturesPage.tsx` (~150 words, 0 FAQ, 0 use cases, 0 HowTo), `website/src/pages/AboutPage.tsx` (~400 words, 0 FAQ), `website/src/pages/PricingPage.tsx` (~100 words, 0 FAQ). Global rule (`~/.claude/rules/seo-aeo-ranking.md` §2) requires ≥1000 unique words + 5–8 FAQ + 3–5 use cases + 4–6 HowTo steps + 2–3 examples + 3–6 tips + author + lastUpdated per page. **Fix:** rewrite via `ai-seo` + `copywriting` skills; treat as one batch, not per-page commits.
+
+- **I8 — `pricing.md` machine-readable file missing at site root**
+  Global rule §5 requires `/pricing.md` for AI buying agents when paid tiers exist. Project has Free + Pro + Enterprise (PayPal plans referenced in backend/.env.example). **Fix:** create `website/public/pricing.md` with tiers, limits, features, FAQ in plain markdown.
+
+- **I9 — `feed.xml` `<lastBuildDate>` lags actual build**
+  Generator emits a stale date instead of `new Date().toUTCString()` at run time. **Fix:** in `website/scripts/generate-sitemap.mjs` (or wherever feed is emitted), replace literal date with runtime stamp; ensure sitemap `<lastmod>` does the same.
+
+### Nits
+
+- **N2 — Docs sub-routes (`/docs/*`) lack per-route static prerender** — they rely on runtime SEO + Googlebot JS rendering; AI crawlers may not render JS. Tracked in `seo-url-coverage.json` already as a known issue. **Fix (later):** extend `postbuild-seo.ts` to walk `public/package-docs/` and emit `dist/docs/<slug>/index.html`.
+- **N3 — `og:image` is the same `/og-image.svg` site-wide.** Per-page OG images would lift social sharing. Defer.
+- All discovery-file dates timestamped 2026-05-02 (6 days old — within 14-day spec, refresh on next batch commit).
+
+---
+
+## 5. Findings — Backend (Laravel 11 + Nova 5, `backend/`)
+
+### Blockers
+
+- **B4 — Nova resources lack policy-backed authorization gates**
+  Files: `backend/app/Nova/*.php` (User, App, Build, ApiKey, SigningKey). Missing `canViewAny()`, `canCreate()`, `canUpdate()`, `canDelete()` guards backed by App\Policies. **Fix:** add per-Resource policies + register in `AuthServiceProvider`; reject non-admin / non-owner access on each verb.
+
+- **B5 — No Feature test for the bundle-upload + signature-verify flow**
+  Folder: `backend/tests/Feature/`. The most security-critical endpoint (build upload) has no test for: signature verify, monotonic version enforcement, channel scoping, duplicate detection, chunk merging. **Fix:** add `tests/Feature/Build/BundleUploadTest.php` covering the full path.
+
+- **B6 — `backend/.env` (local) has `APP_DEBUG=true` + `LOG_LEVEL=debug`** *(documentation gap, not active leak)*
+  This is correct for local dev, BUT no deployment runbook documents flipping these for production. `.env.example` correctly defaults to `APP_DEBUG=false`/`LOG_LEVEL=warning`. **Fix:** add `backend/docs/DEPLOYMENT-CHECKLIST.md` listing `APP_DEBUG=false`, `LOG_LEVEL=warning`, `APP_ENV=production`, `php artisan config:cache`, `migrate --force`, `composer install --no-dev`, queue worker daemonization.
+
+### Important
+
+- **I10 — `ValidateFirebaseToken` middleware auto-creates User on first valid token**
+  File: `backend/app/Http/Middleware/ValidateFirebaseToken.php:41-48`. `firstOrCreate` is open-signup; fine for free tier, risky for invite-only / enterprise. **Fix:** keep open by default but document; add config flag `auth.firebase.auto_create=true|false`.
+
+- **I11 — Controllers validate inline; no FormRequest classes**
+  Files: `backend/app/Http/Controllers/Dashboard/*.php`. Reduces reuse + makes policy gating awkward. **Fix:** extract validators into `app/Http/Requests/*Request.php`; use `$this->authorize()` from inside the request.
+
+- **I12 — Nova User admin panels (Suspend, License, Custom Limits) lack `canSee` gates**
+  File: `backend/app/Nova/User.php:64-65`. Any Nova-authenticated user could touch admin fields. **Fix:** wrap with `Panel::make(...)->canSee(fn ($req) => $req->user()->isAdmin())`.
+
+- **I13 — No `config/cors.php` — relies on Laravel default**
+  Production must lock origins to `nativeupdate.aoneahsan.com` (and dashboard host). **Fix:** publish CORS config, set `paths` → `['api/*']`, `allowed_origins` → explicit list, `supports_credentials` → true.
+
+- **I14 — License-check tests missing**
+  `User::hasValidLicense()` and license-expiry enforcement on API endpoints are not exercised by tests. **Fix:** add Feature test wrapping a paid-tier endpoint.
+
+- **I15 — PayPal webhook CSRF status not explicit**
+  File: `backend/routes/api.php:155-156`. Confirm webhook is in CSRF exception list (Laravel 11 default API routes are CSRF-exempt because they're stateless, but document this and add test).
+
+### Nits
+
+- **N4 — `CACHE_STORE=database` in `.env.example`** — fine for boot, but Redis is recommended for production rate-limiting performance. Add a `# Recommended for production: CACHE_STORE=redis` comment.
+- **N5 — `QUEUE_CONNECTION=database`** — requires `php artisan queue:work` daemon. Document in deployment checklist.
+
+### Notes
+
+- All models use `$fillable` (not `$guarded`); secrets (`password`, `google_drive_token`, `key_hash`) are in `$hidden`. ✓
+- Migration timestamps clean, no out-of-order. ✓
+- File storage uses FilesHub via `FilesHubService` (no AWS S3 hardcoded). ✓
+- `composer.lock` present + reproducible. ✓
+- `.env.example` has [REQUIRED] tags on most blocks. Some PayPal/Google sub-vars could use a one-line reason each (minor).
+
+---
+
+## 6. Findings — Example Apps (`example-apps/`)
+
+### Blockers
+
+- **B7 — `example-apps/react-capacitor` `yarn build` fails (lockfile / workspace ref unresolved)**
+  Error: "This package doesn't seem to be present in your lockfile". Yarn 4 + workspace pointer `"native-update": "file:../.."` not registered in root lockfile. **Fix:** run `yarn install` at root with the example workspaces included; verify root `package.json` declares workspaces (it currently does NOT — example-apps live as ad-hoc projects). Either declare workspaces or document that `cd example-apps/react-capacitor && yarn install` is required separately.
+
+- **B8 — Stale `firebase-backend/` references in `example-apps/react-capacitor/README.md`**
+  Lines: `14`, `101`, `210`. `firebase-backend` was deleted in v3.0.0 but README still recommends it as an option. **Fix:** delete those lines / replace with `node-express` only.
+
+### Important
+
+- **I16 — `react-capacitor` example demos only `checkForUpdate()`**
+  File: `example-apps/react-capacitor/src/App.tsx:1-72`. v3 plugin has 28+ public methods; example covers ~5%. **Fix (incremental):** add tabs/sections demonstrating: `downloadUpdate`, `applyUpdate`, app-update check, app-review prompt, background-update toggle, signature verification of a downloaded bundle. One section per method; gated by feature-flag if Android/iOS-only.
+
+- **I17 — `react-capacitor` pinned to React 18 while `website/` is React 19**
+  Files: `example-apps/react-capacitor/package.json:20`. **Fix:** decide intent. Either bump to 19 to track current website + plugin tests, or add a comment in README declaring 18 is the "stable downstream" target.
+
+### Notes
+
+- `node-express` correctly implements the v3 HTTP-only backend contract. ✓
+- `node_modules` of `react-capacitor` contains stale `native-update@1.3.1` tarball — harmless but worth cleaning on next install.
+
+---
+
+## 7. Findings — Security / Secrets / Env (cross-cutting)
+
+### Critical
+
+None. `yarn npm audit --severity high --recursive` → "No audit suggestions". No hardcoded secrets in source (only in non-public-checked-in `.env` files; root `.gitignore` declares the repo as private with intentional .env-in-git policy — mirror this in any future public split).
+
+### High
+
+- **H1 — Backend has no `config/cors.php`** (duplicates I13). Must lock origins before public deploy.
+- **H2 — Repo is private with `.env` in git.** If repo ever flips public, immediately add `*.env`, `*.env.local`, `*.env.production`, `backend/storage/firebase-credentials.json`, `android/keystores/` to `.gitignore` and rotate every committed secret. **Fix (preventive):** add `docs/SECURITY-IF-REPO-PUBLIC.md` runbook so this isn't forgotten under pressure.
+
+### Medium
+
+- **M1 — `backend/.env.example` `[REQUIRED]` reason comments** — present on FilesHub/Firebase/Google/PayPal blocks (✓). Minor: each *individual sub-var* (e.g. `PAYPAL_LIVE_APP_ID`) could use a one-line "where to find it" note for first-time deployers.
+- **M2 — `website/.env.example` missing two optional docs-snippet vars** that exist in `ConfigPage.tsx`: `VITE_NATIVE_UPDATE_PUBLIC_BACKEND_URL`, `VITE_NATIVE_UPDATE_API_KEY`, `VITE_NATIVE_UPDATE_PUBLIC_KEY`. **Fix:** add as `[OPTIONAL]` rows.
+
+### Notes
+
+- Firebase Web API keys (in website/.env) are PUBLIC by design — not a leak.
+- Auth tokens stored only in Firebase SDK in-memory — no localStorage leak.
+- `firestore.rules` properly tiered (auth-required + admin-via-custom-claim, with public read only on `/manifests/{id}` which is intentional).
+- LICENSE present (MIT) and consistent. ✓
+- Capacitor `appId` stable: `com.aoneahsan.nativeupdate`. ✓
+- No keystores committed (`android/keystores/` does not exist yet). ✓
+
+---
+
+## 8. Roadmap Delta (Planned Features Not Yet Done — Practical-for-Release)
+
+Mined from `docs/REMAINING_FEATURES.md`, `docs/ROADMAP.md`, `docs/PROJECT_COMPLETION_TRACKER.md`, `docs/MARKETING_WEBSITE_TRACKER.md`, `docs/plans/`, `docs/features/laravel-nova-backend/IMPLEMENTATION-PLAN.md`.
+
+### Practical for v3.x release (this audit will tackle in batches)
+
+- **R1** — Performance benchmarking suite scaffold (placeholder exists; needed for SaaS credibility claims).
+- **R2** — Pre-launch security pen-test checklist (light: dependency scan + manual review; not a paid pentest).
+- **R3** — CI/CD integration templates (GitHub Actions): release workflow for the npm plugin + bundle-create + sign + upload step.
+- **R4** — Expand `react-capacitor` example coverage (also tracked as I16 above).
+- **R5** — Marketing-website tracker: 50+ items still `[ ]` in `docs/MARKETING_WEBSITE_TRACKER.md`. Filter for ones that are actually rendered on live pages but unfinished (e.g. screenshots, code-snippet copy refresh, dashboard onboarding flow polish).
+
+### Defer to v3.1+ (not blocking release)
+
+- A/B testing support
+- Staged rollouts with percentage targeting (DB schema exists in backend; UI/CLI surfaces incomplete)
+- Geographic targeting
+- Update scheduling
+- Delta-update WASM optimization
+- Multi-tenant SaaS, enterprise SSO, SLA monitoring
+- Vue / Angular / Svelte / Python / Java example apps
+- Video tutorials, community plugins directory
+
+---
+
+## 9. Verification Commands
+
+After each batch, run from repo root:
+
+```bash
+# Plugin
+yarn lint
+yarn typecheck   # alias for `yarn tsc`
+yarn build
+yarn test:run
+
+# Website
+cd website && yarn typecheck && yarn lint && yarn build && cd ..
+
+# Backend (Laravel)
+cd backend && composer install --no-interaction && php artisan test && cd ..
+
+# Cross-cutting
+grep -rEn "TODO|FIXME" src/ cli/ website/src/ backend/app/ --include="*.ts" --include="*.tsx" --include="*.js" --include="*.php" | wc -l   # track count down over batches
+yarn npm audit --severity high --recursive
+```
+
+---
+
+## 10. Total Issue Count
+
+| Severity | Plugin | Website | SEO | Backend | Examples | Security | Roadmap | **Total** |
+|---|---|---|---|---|---|---|---|---|
+| Blocker | 3 | 0 | 0 | 3 | 2 | 0 | 0 | **8** |
+| Important | 3 | 3 | 3 | 6 | 2 | 0 | 0 | **17** |
+| Nit | 1 | 0 | 2 | 2 | 0 | 0 | 0 | **5** |
+| Sec High | — | — | — | — | — | 2 | — | **2** |
+| Sec Med | — | — | — | — | — | 2 | — | **2** |
+| Roadmap | — | — | — | — | — | — | 5 | **5** |
+
+Grand total: **39 actionable items** across the audit + 5 roadmap items. See `BATCH-PLAN.md` for the execution plan.

package/docs/project-finalization/00-tracker.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "project-finalization-tracker",
+  "description": "Resumable production-finalization tracker for native-update (Capacitor OTA plugin + Laravel/Nova SaaS backend + React marketing site/dashboard + CLI + Docusaurus docs site). The first phase/sub-task with status 'pending' or 'in_progress' is the next thing to work on.",
+  "project": "native-update",
+  "type": "capacitor-plugin-monorepo + saas-backend + marketing-website + cli + docs-site",
+  "repo": "github.com/aoneahsan/native-update (PRIVATE)",
+  "docsRepo": "github.com/aoneahsan/native-update-docs (PRIVATE)",
+  "npm": "native-update@3.1.0 (published)",
+  "homepage": "https://nativeupdate.aoneahsan.com",
+  "createdAt": "2026-06-22",
+  "lastUpdated": "2026-07-02",
+  "readiness": 99,
+  "stackOverride": {
+    "note": "The fleet finalization spec assumes a Firestore + Google Drive website backend. native-update DELIBERATELY chose a Laravel 13 + Nova 5 + MySQL + Google Drive backend (v3.0.0+). Per the Per-Project Stack Override rule, the project's chosen stack wins. Zero-cost / no-Firebase-Functions still honored: this project's own backend uses NO Firebase Functions/Storage (the CLI's firebase-functions strings live only inside a user-choice backend-template GENERATOR).",
+    "websiteBackend": "Laravel 13 + Nova 5 + MySQL + Google Drive (NOT Firestore)",
+    "auth": "Laravel Socialite (Google OAuth) + Sanctum tokens + spatie/laravel-permission RBAC (Firebase Auth removed in v3.0.0)"
+  },
+  "verifyGates": {
+    "pluginBuild": "yarn build -> 0 errors (clean + tsc + rollup, ~4s)",
+    "pluginTypecheck": "yarn tsc --noEmit -> 0 errors",
+    "pluginLint": "yarn lint -> 0 warnings",
+    "websiteTypecheck": "yarn typecheck (tsc -b) -> 0 errors",
+    "websiteBuild": "yarn build -> 0 errors (61-URL sitemap + feed + 16 SEO routes + 9 discovery files)",
+    "websiteLint": "yarn lint -> 0 warnings",
+    "docsBuild": "native-update-docs: yarn build (Docusaurus) -> see runHistory",
+    "verifiedAt": "2026-06-22"
+  },
+  "phases": [
+    { "id": "phase0", "title": "Setup: skills, remote/branch, read scope, scaffold tracker + MANUAL-TASKS, refresh CLAUDE/AGENTS", "status": "complete", "completedAt": "2026-06-22" },
+    { "id": "phase1", "title": "Privacy gate + env/secret audit (repo PRIVATE; force-add git-ignored env; never keystores)", "status": "complete", "completedAt": "2026-06-22",
+      "subTasks": [
+        { "id": "phase1.1", "title": "gh repo view: main + docs repos confirmed PRIVATE", "status": "complete" },
+        { "id": "phase1.2", "title": "Force-add git-ignored backend/.env + website/.env (private repo; root .gitignore documents team-access intent; never published to npm via files[])", "status": "complete" },
+        { "id": "phase1.3", "title": "No keystores in tree; none added", "status": "complete" }
+      ] },
+    { "id": "phase2", "title": "Gap audit: real code vs intended scope + docs promises", "status": "complete", "completedAt": "2026-06-22",
+      "subTasks": [
+        { "id": "phase2.1", "title": "Plugin src/ TODO/stub scan: clean (3 false positives — field names + a docstring)", "status": "complete" },
+        { "id": "phase2.2", "title": "CLI scaffolding TODO[SCAFFOLD-IMPLEMENT-BEFORE-DEPLOY] markers are INTENTIONAL generated-template placeholders (BACKEND_TEMPLATES_GUIDE.md) — by design, not a gap", "status": "complete" },
+        { "id": "phase2.3", "title": "Website console.* hits are inside documentation code-example strings, not real logging; no innerHTML in new code", "status": "complete" }
+      ] },
+    { "id": "phase3", "title": "Build automatable gaps", "status": "complete", "completedAt": "2026-06-22",
+      "note": "No automatable code gaps found. The project is genuinely production-complete (v3.1.0 on npm, 134 backend PHPUnit tests, complete iOS/Android/CLI/website/backend/docs). The only real fix was doc-drift: REMAINING_FEATURES.md item #5 (DocsPage.tsx 1406-line refactor) was already done (now 166 lines + docs-page/sections/)." },
+    { "id": "phaseD", "title": "Verify/finish native-update-docs (Docusaurus, sibling repo)", "status": "complete", "completedAt": "2026-06-22" },
+    { "id": "phaseN1", "title": "Manual-task consolidation (npm publish, deploys, device verify, backend DB/test verify)", "status": "complete", "completedAt": "2026-06-22" },
+    { "id": "phaseN2", "title": "Finalize: final verify gates + tracker + git in-sync (both repos)", "status": "complete", "completedAt": "2026-06-22" }
+  ],
+  "gapInventory": [
+    { "id": "G1", "title": "Delta-update WASM (bsdiff/bspatch) optimization", "classification": "ROADMAP-OPTIONAL", "status": "deferred", "note": "delta-processor.ts already ships a working JS-level file-patching strategy; WASM is a performance enhancement, not a missing feature. Documented in REMAINING_FEATURES.md." },
+    { "id": "G2", "title": "A/B testing, calendar update scheduling, geographic targeting", "classification": "PRODUCT-DECISION", "status": "deferred", "note": "Large speculative features the user has not scoped. Percentage rollouts + pause/resume + targetSegments already shipped on the builds table." },
+    { "id": "G3", "title": "Additional framework example apps (Vue / Angular / Svelte / Python / Java)", "classification": "PRODUCT-DECISION", "status": "deferred", "note": "React+Capacitor and Node/Express examples already ship. Which (if any) to add next is a product decision." },
+    { "id": "G4", "title": "Enterprise: multi-tenant/org accounts, SAML/OIDC SSO, white-label branding, audit-log UI", "classification": "PRODUCT-DECISION", "status": "deferred", "note": "Roadmap; current model is single-user. Raw audit events already persist via analytics_events + Nova." },
+    { "id": "G5", "title": "website page components marginally over 500-line soft guideline (FeaturesPage 578, ExamplesPage 523, AnalyticsPage 519)", "classification": "COSMETIC-OPTIONAL", "status": "deferred", "note": "500 lines is a soft guideline; these are cohesive content-heavy single pages that build clean. Not a finalization blocker." }
+  ],
+  "runHistory": [
+    { "date": "2026-06-22", "phase": "all", "summary": "Owner-agent finalization pass. Verified package (build/tsc/lint = 0), website (typecheck/build/lint = 0; 61-URL sitemap + 16 SEO routes), and docs site build. Confirmed both repos PRIVATE; force-added git-ignored backend/.env + website/.env (never published to npm). Plugin/native/CLI/backend genuinely complete; no automatable code gaps. Fixed stale REMAINING_FEATURES.md DocsPage item. Scaffolded this tracker; refreshed CLAUDE.md/AGENTS.md + MANUAL-TASKS + sitemap/feed lastmod to 2026-06-22.", "commit": "pending" },
+    { "date": "2026-07-02", "phase": "v3.1.0-release", "summary": "v3.1.0 audit + optimize + release session (Fable 5 plan + Opus 4.8 execution). Plugin: package.json exports map, web.ts validateUpdate reuses downloaded bytes (no double download), 10 dead comment lines removed, cli 3.1.0. Website: HomePage LazyMotion (framer-motion off first-paint), .env.production (prod backend URL always baked), root firebase.json consolidated w/ cache headers (website/firebase.json+.firebaserc deleted), 9 dead Firebase-era env keys removed. Backend: update-check writes deferred to dispatch()->afterResponse(), App::getLatestBuildForChannel cached 45s w/ Build model-event invalidation, additive covering index builds(app_id,channel,status,created_at), analytics:cleanup now prunes analytics_events, CORS supports_credentials=false, 2 scaffold ExampleTests removed (134 PHPUnit pass). Docs: CHANGELOG + RELEASE-NOTES 3.1.0, Laravel-11->13 / Pest->PHPUnit / api-host drift fixed, HOSTINGER deploy notes refreshed (PHP>=8.3, scheduler required, v3.1.0 migration, X-Sendfile note). Released: npm publish native-update@3.1.0 + firebase deploy website. INCIDENT: live backend https://nativeupdatebe.aoneahsan.com returns HTTP 500 on all routes (pre-existing, deploy-side — flagged as MANUAL-TASKS row 1, likely PHP<8.3). Deferred: native streaming-hash perf, file splits, X-Sendfile impl, docs-site deploy.", "commit": "pending" }
+  ],
+  "resumeInstructions": "1) Read this tracker. 2) All phases complete. 3) If re-run: confirm verify gates still pass, check whether the user has scoped any gapInventory ROADMAP/PRODUCT-DECISION item, and update lastUpdated. NEVER auto-build the deferred product-decision features without the user scoping them."
+}

package/docs/project-knowledge-base/01-system-overview.md

@@ -0,0 +1,227 @@
+# Native Update System Overview
+
+## Metadata
+
+- **Reference Date:** 2026-05-18
+- **Last Updated:** 2026-05-18
+
+## Project Identity
+
+- **Name:** Native Update
+- **Package:** `native-update`
+- **Type:** Open-source Capacitor plugin plus self-hostable update management platform
+- **Primary Creator:** Ahsan Mahmood
+- **Primary Contact:** aoneahsan@gmail.com
+- **License:** MIT
+
+## Core Mission
+
+Native Update exists to reduce the operational complexity of shipping updates in Capacitor apps. It unifies OTA updates, native app update flows, in-app reviews, release manifests, rollout controls, and management tooling into one ecosystem.
+
+## Core Product Layers
+
+### 1. Plugin Layer
+
+The plugin provides the runtime capabilities inside a Capacitor app:
+
+- OTA/live update checks and bundle handling
+- app update checks and prompts
+- in-app review requests
+- background update scheduling
+- security validation logic (SHA-256 checksums + RSA-SHA256 signatures)
+- HTTP-based manifest reading from any user-controlled backend
+
+### 2. Dashboard Layer
+
+The website provides a management surface for:
+
+- user auth (Google OAuth via Laravel Socialite + Sanctum bearer tokens)
+- app creation and app management
+- build uploads (browser → Laravel → Google Drive)
+- rollout visibility and control
+- analytics review
+- Google Drive connection and storage management
+- configuration generation
+- admin-only oversight pages (Spatie permission-gated)
+
+### 3. Docs Layer
+
+The docs explain:
+
+- installation and setup
+- features and APIs
+- examples and advanced scenarios
+- security, deployment, testing, and troubleshooting
+- migration from other approaches (CodePush, Capacitor Live Updates)
+- planning, tracking, roadmap, audit, and report history
+
+In addition to the in-repo `/docs` folder, a public Docusaurus site lives at the sibling repo `native-update-docs` and is deployed to Firebase Hosting (hosting-only — no Firebase backend).
+
+### 4. Tooling Layer
+
+The project includes:
+
+- CLI commands (`init`, `bundle-create`, `bundle-sign`, `bundle-verify`, `keys-generate`, `backend-create`, `server-start`, `monitor`)
+- bundle creation/signing/verification utilities
+- backend scaffolding templates
+- local development server
+
+## What The Product Solves
+
+Capacitor teams often need several disconnected systems to handle:
+
+- web asset updates
+- store version upgrades
+- review prompts
+- release rollout control
+- security verification
+- app/build administration
+
+Native Update consolidates those concerns into one project with a common mental model.
+
+## Main Feature Areas
+
+### Live / OTA Updates
+
+- Deliver JavaScript, HTML, and CSS changes without app store review
+- Support update channels (production / staging / development)
+- Manage version checks and bundle downloads
+- Support checksum and signature validation
+- Enable rollback-aware update flows
+- Support delta patch concepts and file manifests
+
+### Native App Updates
+
+- Check for newer native binary versions
+- Support immediate and flexible update strategies
+- Integrate with Android Play Core update + iOS App Store update behavior
+
+### In-App Reviews
+
+- Request native reviews via Play Review API + StoreKit `SKStoreReviewController`
+- respect timing/rate limiting logic
+- support user-experience-aware prompting
+
+### Background Updates
+
+- Schedule checks while app is not active (Android WorkManager, iOS BGTaskScheduler)
+- support native notification behavior
+- provide background configuration hooks
+
+### Security
+
+- RSA-SHA256 signing of bundles
+- SHA-256 checksum verification
+- HTTPS-first posture
+- certificate pinning support
+- validation helpers
+- fail-closed on integrity violations
+
+### Release Operations
+
+- upload build ZIPs through the dashboard
+- generate file manifests
+- publish app-facing manifests
+- configure rollout percentages
+- manage app/channel/build metadata via Nova admin or REST API
+
+## Current Product Surfaces
+
+### Public Website
+
+- `/`
+- `/features`
+- `/pricing`
+- `/docs`
+- `/docs/*`
+- `/examples`
+- `/about`
+- `/contact`
+- `/privacy`
+- `/terms`
+- `/data-deletion`
+- `/cookies`
+- `/security`
+- `/sitemap`
+- `/feed`
+
+### Auth Pages
+
+- `/login` (Google sign-in via Laravel Socialite redirect)
+- `/signup` (same flow as `/login`; account is created on first callback)
+- `/auth/callback` (SPA receives the Sanctum token from the Laravel OAuth callback)
+
+### Protected Dashboard
+
+- `/dashboard`
+- `/dashboard/apps`
+- `/dashboard/apps/:appId`
+- `/dashboard/builds`
+- `/dashboard/builds/:buildId`
+- `/dashboard/upload`
+- `/dashboard/drive`
+- `/dashboard/config`
+- `/dashboard/settings`
+- `/dashboard/rollouts`
+- `/dashboard/analytics`
+
+### Admin Area
+
+- `/admin`
+- `/admin/users`
+- `/admin/apps`
+- `/admin/builds`
+- Laravel Nova admin lives at `/nova` on the backend host (separate UI; same MySQL store)
+
+## User Types
+
+### Public Visitor
+
+Can browse marketing, docs, legal, contact, sitemap, and feed pages.
+
+### Authenticated User
+
+Holds a Sanctum personal access token, has a row in the MySQL `users` table keyed by `google_id`, and the `user` role from `spatie/laravel-permission`. Can manage their own apps, builds, Drive connection, settings, and release operations.
+
+### Admin User
+
+A signed-in user assigned the `admin` or `super-admin` role in MySQL via `spatie/laravel-permission`. Super-admins bypass all `can:` middleware checks via a `Gate::before` hook. Admin assignment happens via `php artisan native-update:role-assign <email> <role>` or automatically when the email is in the `ADMIN_EMAILS` env list.
+
+### Mobile App Client
+
+Not a dashboard user, but an app-side runtime consumer of manifests, update metadata, and plugin APIs. Authenticates with the mobile API plane via a per-app API key (separate from Sanctum).
+
+### Developer / Maintainer
+
+Works in the codebase, docs, CLI, native code, example apps, and release infrastructure.
+
+## Access Model
+
+- Public routes are open.
+- Dashboard routes are wrapped by `ProtectedRoute` on the SPA AND protected by `auth:sanctum` middleware on every Laravel `/api/dashboard/*` route.
+- Admin routes are wrapped by `AdminRoute` on the SPA AND protected by `can:<permission>` middleware on every Laravel `/api/admin/*` route.
+- Google sign-in (via Laravel Socialite) is the only auth flow.
+- Admin privilege comes from Spatie role assignment, not a `users.is_admin` boolean.
+
+## Product Positioning Notes
+
+- The repo positions Native Update as more than a plugin; it is a platform direction.
+- The website presents a complete update solution with dashboard and docs.
+- The repo also contains older historical docs from pre-production phases. These should be treated as timeline artifacts, not always the newest truth.
+- All mentions of "Firebase Auth", "Firestore", or "Firebase backend" in older docs are historical — the architecture switched to Laravel + Sanctum on 2026-05-11.
+
+## Recommended Decision Assumptions For AI Tools
+
+- Treat the project as a cross-platform mobile infrastructure product.
+- Treat the website as both a marketing site and operations dashboard.
+- Treat the Laravel backend at `backend/` as the canonical persistence + auth layer for the dashboard.
+- Treat Google Drive as the canonical storage destination for uploaded bundle ZIPs; tokens are encrypted server-side by Laravel.
+- Treat the dashboard as owner/operator tooling, not end-user mobile UI.
+- Treat security, rollout control, and documentation quality as important project values.
+
+## Important Known Context
+
+- The project contains current docs plus historical reports and planning files.
+- Some documents disagree on production readiness because they were written at different times.
+- For technical state, prefer current source code, route definitions, type definitions, package files, and newer roadmap/report files.
+- The "no-cost Firestore + Google Drive backend" architecture was deliberately abandoned in v3.0.0 (2026-05-04). Any document still describing it is historical-only.