native-update 1.4.9 → 3.1.0

package/docs/features/laravel-nova-backend/progress-tracker.json

@@ -0,0 +1,184 @@
+{
+  "feature": "Laravel + Nova Backend for Native Update",
+  "created": "2026-03-28",
+  "lastUpdated": "2026-03-28",
+  "status": "in_progress",
+  "estimatedWeeks": 5,
+  "currentPhase": 3,
+  "phases": [
+    {
+      "id": 1,
+      "name": "Laravel Project Setup",
+      "status": "completed",
+      "completedAt": "2026-03-28",
+      "estimatedDays": 5,
+      "tasks": [
+        { "task": "Create Laravel 11 project", "status": "completed" },
+        { "task": "Install and configure Nova 5", "status": "completed" },
+        { "task": "Configure MySQL database", "status": "completed", "note": "Using SQLite for dev, MySQL for production" },
+        { "task": "Set up Firebase token validation middleware", "status": "completed" },
+        { "task": "Configure S3/Cloudflare R2 storage", "status": "partial", "note": "Config added, needs keys" },
+        { "task": "Set up development environment (.env)", "status": "completed" }
+      ]
+    },
+    {
+      "id": 2,
+      "name": "Database Schema & Models",
+      "status": "completed",
+      "completedAt": "2026-03-28",
+      "estimatedDays": 4,
+      "tasks": [
+        { "task": "Create users migration and model", "status": "completed" },
+        { "task": "Create apps migration and model", "status": "completed" },
+        { "task": "Create builds migration and model", "status": "completed" },
+        { "task": "Create api_keys migration and model", "status": "completed" },
+        { "task": "Create subscriptions migration and model", "status": "completed" },
+        { "task": "Create device_activities migration and model", "status": "completed" },
+        { "task": "Create signing_keys migration and model", "status": "completed" },
+        { "task": "Set up model relationships", "status": "completed" }
+      ]
+    },
+    {
+      "id": 3,
+      "name": "API Endpoints",
+      "status": "in_progress",
+      "estimatedDays": 5,
+      "tasks": [
+        { "task": "Create ValidateApiKey middleware", "status": "completed" },
+        { "task": "Create ValidateFirebaseToken middleware", "status": "completed" },
+        { "task": "Create UpdateController (check for updates)", "status": "completed" },
+        { "task": "Create BundleController (upload, download)", "status": "completed" },
+        { "task": "Create AnalyticsController (MAU ping)", "status": "completed" },
+        { "task": "Create AppController (dashboard CRUD)", "status": "pending" },
+        { "task": "Create ApiKeyController (key management)", "status": "pending" },
+        { "task": "Create SubscriptionController (billing)", "status": "pending" },
+        { "task": "Set up API routes", "status": "completed" },
+        { "task": "Add rate limiting", "status": "pending" }
+      ]
+    },
+    {
+      "id": 4,
+      "name": "Stripe Integration",
+      "status": "partial",
+      "estimatedDays": 4,
+      "tasks": [
+        { "task": "Install Laravel Cashier", "status": "completed" },
+        { "task": "Configure Stripe API keys", "status": "pending", "note": "Config added, needs keys" },
+        { "task": "Create pricing plans in Stripe", "status": "pending" },
+        { "task": "Implement checkout session creation", "status": "pending" },
+        { "task": "Implement customer portal redirect", "status": "pending" },
+        { "task": "Create webhook handler", "status": "pending" },
+        { "task": "Handle subscription lifecycle events", "status": "pending" },
+        { "task": "Implement MAU overage billing", "status": "pending" }
+      ]
+    },
+    {
+      "id": 5,
+      "name": "Bundle Signing & Security",
+      "status": "completed",
+      "completedAt": "2026-03-28",
+      "estimatedDays": 4,
+      "tasks": [
+        { "task": "Create BundleSigningService", "status": "completed", "note": "In SigningKey model" },
+        { "task": "Implement RSA key pair generation", "status": "completed" },
+        { "task": "Implement RSA-PSS signing", "status": "completed" },
+        { "task": "Create SignedUrlService", "status": "completed", "note": "Using Laravel's built-in signed URLs" },
+        { "task": "Implement time-limited download URLs", "status": "completed" },
+        { "task": "Add device binding to URLs", "status": "completed" },
+        { "task": "Implement one-time download tokens", "status": "pending" },
+        { "task": "Add request signature validation (replay protection)", "status": "pending" }
+      ]
+    },
+    {
+      "id": 6,
+      "name": "Nova Admin Panel",
+      "status": "pending",
+      "estimatedDays": 4,
+      "tasks": [
+        { "task": "Create User Nova resource", "status": "completed", "note": "Auto-generated by Nova install" },
+        { "task": "Create App Nova resource", "status": "pending" },
+        { "task": "Create Build Nova resource", "status": "pending" },
+        { "task": "Create Subscription Nova resource", "status": "pending" },
+        { "task": "Create ApiKey Nova resource", "status": "pending" },
+        { "task": "Create Main dashboard (revenue, usage)", "status": "pending" },
+        { "task": "Add admin actions (suspend, adjust plan)", "status": "pending" },
+        { "task": "Add metrics cards and charts", "status": "pending" }
+      ]
+    },
+    {
+      "id": 7,
+      "name": "Plugin Updates",
+      "status": "pending",
+      "estimatedDays": 3,
+      "tasks": [
+        { "task": "Add apiKey to PluginInitConfig in definitions.ts", "status": "pending" },
+        { "task": "Add X-API-Key header to HTTP requests in plugin.ts", "status": "pending" },
+        { "task": "Add MAU ping endpoint call", "status": "pending" },
+        { "task": "Update iOS SecureStorage for API key", "status": "pending" },
+        { "task": "Update Android SecureStorage for API key", "status": "pending" },
+        { "task": "Update documentation", "status": "pending" }
+      ]
+    },
+    {
+      "id": 8,
+      "name": "Migration & Testing",
+      "status": "pending",
+      "estimatedDays": 5,
+      "tasks": [
+        { "task": "Write unit tests for API key validation", "status": "pending" },
+        { "task": "Write unit tests for bundle signing", "status": "pending" },
+        { "task": "Write unit tests for MAU calculation", "status": "pending" },
+        { "task": "Write integration tests for upload flow", "status": "pending" },
+        { "task": "Write integration tests for download flow", "status": "pending" },
+        { "task": "Write integration tests for Stripe flow", "status": "pending" },
+        { "task": "Create Firebase user sync script", "status": "pending" },
+        { "task": "Deploy to staging environment", "status": "pending" },
+        { "task": "Perform end-to-end testing", "status": "pending" },
+        { "task": "Deploy to production", "status": "pending" },
+        { "task": "Monitor and fix issues", "status": "pending" }
+      ]
+    }
+  ],
+  "decisions": {
+    "keepFirebaseAuth": true,
+    "keepGoogleDrive": "optional-free-tier",
+    "primaryStorage": "s3-or-r2",
+    "adminPanel": "laravel-nova",
+    "paymentProcessor": "stripe",
+    "mauTracking": "device-hash-monthly"
+  },
+  "pricingTiers": [
+    { "name": "Free", "price": 0, "mauLimit": 1000, "appsLimit": 1 },
+    { "name": "Pro", "price": 29, "mauLimit": 10000, "appsLimit": 5 },
+    { "name": "Enterprise", "price": 199, "mauLimit": 100000, "appsLimit": -1 }
+  ],
+  "securityFeatures": [
+    "api-key-authentication",
+    "firebase-token-validation",
+    "rsa-pss-bundle-signing",
+    "signed-download-urls",
+    "device-binding",
+    "rate-limiting",
+    "replay-attack-prevention"
+  ],
+  "completedToday": [
+    "Laravel 11 + Nova 5 project created in /backend",
+    "All database migrations created and run",
+    "All models with relationships created",
+    "API key validation middleware created",
+    "Firebase token validation middleware created",
+    "Update check API endpoint created",
+    "Bundle download API with signed URLs created",
+    "Analytics/MAU tracking API created",
+    "RSA key generation and signing in SigningKey model",
+    "Laravel Cashier, Firebase SDK, AWS SDK installed"
+  ],
+  "blockers": [],
+  "notes": [
+    "Nova license configured globally",
+    "Stripe API keys needed",
+    "Firebase service account JSON needed",
+    "S3/R2 bucket and keys needed",
+    "Current plugin already supports HTTP backend - minimal changes needed"
+  ]
+}

package/docs/guides/testing-guide.md

@@ -1,36 +1,10 @@
 # Comprehensive Testing Guide
 
-This guide covers all testing approaches for the Capacitor Native Update plugin.
+This guide covers the manual and on-device testing approaches for the Capacitor Native Update plugin. Verification is done in actual/live apps using the plugin rather than an automated JS test runner.
 
 ## Testing Levels
 
-### 1. Unit Testing
-
-The plugin includes unit tests for core functionality:
-
-```bash
-# Run all tests
-yarn test
-
-# Run with coverage
-yarn test:coverage
-
-# Watch mode for development
-yarn test:watch
-```
-
-#### Test Structure
-
-```
-src/__tests__/
-├── security.test.ts      # Security validation tests
-├── version-manager.test.ts # Version comparison tests
-├── bundle-manager.test.ts  # Bundle management tests
-├── config.test.ts         # Configuration tests
-└── integration.test.ts    # Integration tests
-```
-
-### 2. Integration Testing
+### 1. Integration Testing
 
 #### Web Platform Testing
 
@@ -103,7 +77,7 @@ src/__tests__/
    - In-app update UI
    - Rollback functionality
 
-### 3. Security Testing
+### 2. Security Testing
 
 #### Certificate Validation
 ```typescript
@@ -130,7 +104,7 @@ const isValid = await NativeUpdate.validateUpdate({
 });
 ```
 
-### 4. Performance Testing
+### 3. Performance Testing
 
 #### Download Performance
 ```typescript
@@ -146,7 +120,7 @@ NativeUpdate.addListener('downloadProgress', (progress) => {
 - Test with large bundles (50MB+)
 - Verify cleanup of old bundles
 
-### 5. End-to-End Testing
+### 4. End-to-End Testing
 
 #### Complete Update Cycle
 
@@ -189,7 +163,7 @@ NativeUpdate.addListener('downloadProgress', (progress) => {
    }
    ```
 
-### 6. Error Handling Testing
+### 5. Error Handling Testing
 
 #### Network Failures
 ```typescript
@@ -211,7 +185,7 @@ await NativeUpdate.download({
   });
 ```
 
-### 7. Rollback Testing
+### 6. Rollback Testing
 
 ```typescript
 // Test rollback mechanism
@@ -228,7 +202,7 @@ async function testRollback() {
 }
 ```
 
-### 8. Platform-Specific Testing
+### 7. Platform-Specific Testing
 
 #### iOS Specific
 - Test with different iOS versions (13+)
@@ -242,26 +216,26 @@ async function testRollback() {
 - Test notification permissions
 - Check WorkManager scheduling
 
-### 9. Automated Testing
+### 8. Automated Verification
 
 #### CI/CD Integration
 ```yaml
-# .github/workflows/test.yml
-name: Test
+# .github/workflows/ci.yml
+name: CI
 on: [push, pull_request]
 
 jobs:
-  test:
+  build:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
       - uses: actions/setup-node@v2
       - run: yarn install
-      - run: yarn test
-      - run: yarn test:e2e
+      - run: yarn lint
+      - run: yarn build
 ```
 
-### 10. Manual Testing Checklist
+### 9. Manual Testing Checklist
 
 - [ ] **Configuration**
   - [ ] Valid HTTPS URL required

package/docs/package-audit.md

@@ -0,0 +1,41 @@
+# Package Audit
+
+Per R-010 (Clean package.json). Records unused dependencies removed and the reason.
+
+**Last audited:** 2026-04-25
+
+## Root (`package.json`)
+
+All listed dependencies and devDependencies are imported somewhere in the build pipeline (Rollup, TypeScript, ESLint). No removals.
+
+## Website (`website/package.json`)
+
+| Package | Version | Action | Reason |
+|---|---|---|---|
+| `react-syntax-highlighter` | ^16.1.1 | **Removed** | Not imported anywhere in `website/src/`. The docs markdown page uses `react-markdown` + `remark-gfm` for rendering. Code highlighting is not currently a feature. Re-add when needed for code-fenced content. |
+| `@types/react-syntax-highlighter` | ^15.5.13 | **Removed** | Unused (paired with the package above). |
+
+After removal, run `yarn install` in `website/` to update `yarn.lock`. Until then, the lockfile keeps the (no-longer-listed) entries — harmless but tidy with the next install.
+
+All other website deps verified imported:
+- Capacitor + Capawesome plugins → used by mobile build flow
+- Radix UI primitives → used in `src/components/ui/*` and across pages
+- `framer-motion` → used in 11 files
+- `lucide-react` → used in 32 files
+- `jszip` → used by bundle upload service
+- `d3` + `@types/d3` → present for chart rendering (admin/dashboard analytics)
+- `firebase`, `react-hook-form`, `zod`, `@hookform/resolvers`, `react-router-dom`, `react-markdown`, `remark-gfm`, `tailwind-merge`, `class-variance-authority`, `clsx`, `zustand` → all imported
+
+## CLI (`cli/package.json`)
+
+All deps are CLI-essential (`commander`, `chalk`, `ora`, `axios`, `archiver`, etc.). No removals.
+
+## Backend (`backend/package.json`)
+
+Tiny dev-only package.json (Vite + Tailwind + Laravel Vite plugin). No removals. Note: `package-lock.json` removed in this run per yarn-only policy. Run `yarn install` in `backend/` to generate `yarn.lock` if backend is actively developed.
+
+## Example apps
+
+- `react-capacitor`: Capacitor + React deps. Verified.
+- `node-express`: Express + dotenv. Verified.
+- `firebase-backend`: Firebase Admin + Express. Verified.

package/docs/play-store/ASO-METADATA.md

@@ -0,0 +1,5 @@
+# ASO Metadata — Native Update (Internal Reference)
+
+Populate via `~/.claude/rules/play-store-submission.md` (Phase 3) when preparing a release.
+
+Internal brand/ASO reference — keywords, competitor analysis, category strategy. Not store-facing copy.

package/docs/play-store/DATA-SAFETY.md

@@ -0,0 +1,5 @@
+# Data Safety — Native Update
+
+Populate via `~/.claude/rules/play-store-submission.md` (Phase 2) when preparing a release.
+
+Full Data Safety form answers: data types collected, required/optional, shared/not shared, purposes, encryption-in-transit, deletion URL.

package/docs/play-store/DECLARATIONS.md

@@ -0,0 +1,5 @@
+# Play App-Content Declarations — Native Update
+
+Populate via `~/.claude/rules/play-store-submission.md` (Phase 2) when preparing a release.
+
+All 10 declarations must be answered from the real Phase-0 code audit before any Play Console submission.

package/docs/play-store/README.md

@@ -0,0 +1,27 @@
+# Play Store Docs — Native Update
+
+Start here. Every Play Store submission file is linked below.
+
+**App:** Native Update · `com.aoneahsan.nativeupdate` · v3.0.1  
+**Play Store:** https://play.google.com/store/apps/details?id=com.aoneahsan.nativeupdate  
+**Full spec:** `~/.claude/rules/play-store-submission.md`
+
+---
+
+## Files in this folder
+
+| File | Purpose |
+|------|---------|
+| [RELEASE-NOTES.md](./RELEASE-NOTES.md) | **Play Store "What's New" — open this first.** Per-version release notes, latest-first. Copy the latest entry into Play Console. |
+| [STORE-LISTING.md](./STORE-LISTING.md) | App title, short description, full description. |
+| [DECLARATIONS.md](./DECLARATIONS.md) | All 10 Play "App content" declarations (answer key). |
+| [DATA-SAFETY.md](./DATA-SAFETY.md) | Data Safety form answers. |
+| [RELEASE-STEPS.md](./RELEASE-STEPS.md) | User-only build + Play Console upload steps. |
+| [SUBMISSION-CHECKLIST.md](./SUBMISSION-CHECKLIST.md) | Pre-upload checklist. |
+| [ASO-METADATA.md](./ASO-METADATA.md) | Internal brand/ASO reference (not store-facing). |
+
+## Related
+
+- **Raw image assets:** `app-publish-assets/` (icons, feature graphics, screenshots) — _not yet created; see `~/.claude/rules/play-store-submission.md` Phase 5._
+- **Resumable tracker:** `docs/features/play-store-submission/00-tracker.json` — _not yet created._
+- **Developer changelog:** [docs/CHANGELOG.md](../CHANGELOG.md)

package/docs/play-store/RELEASE-NOTES.md

@@ -0,0 +1,99 @@
+# Release Notes — Native Update (Play Store "What's New")
+
+Per-version Play Store release notes, latest-first.
+Single source of truth — copy the latest entry into the Play Console "What's New" field (≤500 chars).
+
+Related: developer changelog at [docs/CHANGELOG.md](../CHANGELOG.md).
+
+---
+
+## v3.1.0 — July 2026
+
+- Faster update checks: server hot path optimized (deferred analytics writes, cached build lookup, covering index).
+- Web platform no longer re-downloads a bundle to validate it after download.
+- Modern package exports map — cleaner imports in every bundler, deep imports still work.
+- Faster website landing page (animation engine now loads in the background).
+- Maintenance: analytics data pruning, dependency/config cleanup, documentation fixes.
+
+---
+
+## v3.0.1 — May 2026
+
+- New public documentation site at docs.nativeupdate.aoneahsan.com (58 pages: SDK reference, CLI, backend, tutorials).
+- Security checklist and performance benchmark docs added.
+- CI workflow now builds, signs, and publishes an example OTA bundle on every GitHub Release.
+- Example app demonstrates App Update, App Review, and Background Update features.
+- Minor website fix: removed a stale example card that linked to a deleted directory.
+
+---
+
+## v3.0.0 — May 2026
+
+- Backend simplified: Firestore backend removed. Plugin now speaks HTTP to a single backend (serverUrl + apiKey).
+- Breaking: apps using the Firestore branch must migrate to serverUrl — see MIGRATION.md.
+- Website dashboard auth migrated to Laravel Socialite (Google OAuth) + Sanctum bearer tokens.
+
+---
+
+## v2.0.0 — April 2026
+
+- Boot-time bundle re-verification: on every cold start the plugin re-hashes the active OTA bundle. Mismatch triggers automatic rollback.
+- Channel-based encryption removed; signature + checksum verification is the integrity model.
+- setUpdateUrl() deprecated (no-op); pass serverUrl to initialize() instead.
+
+---
+
+## v1.4.9 — March 2026
+
+- Firestore-backed manifest reads via backendType: 'firestore'.
+- Secure manifest lookup via apiKeys/{apiKey}/manifests/{channel}.
+- No-cost backend guide: website + Firestore + Google Drive.
+
+---
+
+## v1.4.5 — February 2026
+
+- All dependencies updated to latest versions.
+- Full verification suite passing (81 tests, 0 lint warnings).
+- Android Gradle build verified. Release-ready state confirmed.
+
+---
+
+## v1.0.7 — January 2025
+
+- Fixed critical Android build issues: Google Play app-update library version pinned to 2.1.0.
+- Resolved kotlinVersion resolution errors.
+- All Google Play Services dependencies now use explicit versions.
+
+---
+
+## v1.0.6 — January 2025
+
+- Android build fixes: corrected Play app-update library version, fixed kotlinVersion MissingPropertyException.
+- Documentation corrections: API method signatures, event names, and broken links fixed.
+
+---
+
+## v1.4.0 — January 2025
+
+- Complete TypeScript rewrite with strict typing and modular architecture.
+- Comprehensive error handling, security validation framework, and bundle management.
+- Background update support. Plugin initialization system.
+
+---
+
+## v0.0.2 — December 2024
+
+- Bundle signing and security utilities.
+- CI/CD pipeline with GitHub Actions.
+- Example update-server implementation. TypeScript strict mode. ESLint v9 flat config.
+
+---
+
+## v0.0.1 — January 2024
+
+- Initial release.
+- Live/OTA update: download, bundle management, update strategies (immediate, background, manual), delta updates, automatic rollback, update channels, end-to-end encryption, SHA-256/512 checksums.
+- Native app update: Play Store version checking, immediate and flexible update flows, direct app store navigation.
+- In-app review: native review prompts with smart triggering and rate limiting.
+- iOS (Swift) and Android (Kotlin) implementations. Web fallback.

package/docs/play-store/RELEASE-STEPS.md

@@ -0,0 +1,6 @@
+# Release Steps — Native Update (User-Only)
+
+Populate via `~/.claude/rules/play-store-submission.md` (Phase 6) when preparing a release.
+
+This file lists user-only build + Play Console upload steps (commands and clicks, not release-note text).
+The agent prepares all data, copy, and assets; the user performs the signed AAB build + Play Console upload.

package/docs/play-store/STORE-LISTING.md

@@ -0,0 +1,7 @@
+# Store Listing — Native Update
+
+Populate via `~/.claude/rules/play-store-submission.md` (Phase 3) when preparing a release.
+
+Includes: app name (≤30 chars), short description (≤80 chars), full description, and a link to RELEASE-NOTES.md for "What's New".
+
+See [RELEASE-NOTES.md](./RELEASE-NOTES.md) for the latest "What's New" entry.

package/docs/play-store/SUBMISSION-CHECKLIST.md

@@ -0,0 +1,5 @@
+# Submission Checklist — Native Update
+
+Populate via `~/.claude/rules/play-store-submission.md` (Phase 7) when preparing a release.
+
+Pre-upload checklist covering: permissions, store listing, declarations, assets, legal pages, and release build.

package/docs/production-readiness.md

@@ -29,7 +29,7 @@
 >    - Private key management (for bundle signing)
 >    - Encryption key management (for encrypted bundles)
 >
-> **GETTING STARTED**: See the example backends in `/example-apps/node-express` and `/example-apps/firebase-backend` for reference implementations.
+> **GETTING STARTED**: For reference implementations see [`/example-apps/node-express`](../example-apps/node-express) (lean Node.js / Express reference) and [`/backend`](../backend) (Laravel 13 + Nova canonical SaaS backend powering the hosted Native Update service — usable as managed or self-hosted).
 
 This comprehensive checklist ensures your Capacitor Native Update implementation is ready for production deployment. Follow these guidelines to deliver a secure, reliable, and performant update system.
 

package/docs/project-audit/2026-05-16/00-FINALIZATION-PLAN.md

@@ -0,0 +1,123 @@
+# Native Update — Project Finalization Plan
+
+**Date opened:** 2026-05-16
+**Goal:** Get the Native Update repo (plugin + website + backend + Android wrap) production-ready for a fresh Google Play Store listing of the website wrapped via Capacitor, with the marketing site live, the Laravel SaaS backend deploy-ready, and the NPM plugin shippable.
+
+**Audit owner:** Claude (Opus 4.7) in continuous-batch mode under the user's `01-code` workspace rules.
+
+---
+
+## What the user asked for
+
+1. **Audit the entire project**, ignoring the previous audit's 7-day cooldown.
+2. **Fix everything** that's wrong, missing, or partial — no TODOs, no "coming soon", no deferred items.
+3. **Complete every feature** end-to-end across web, Android, backend, and plugin.
+4. **Polish UI/UX** for the website + admin/dashboard so the Android wrap feels native.
+5. **Confirm SEO/AEO** + static content quality on the marketing site.
+6. **Comply with the Generic Project Rules master prompt** at `~/Documents/ahsan-notebook/static/assets/txt-files-important/generic-project-rules.md` where they apply to this project.
+7. **Batch the work** at 40–60 minutes per batch with 1–3 tasks each, validation + verification + commit + push per batch.
+8. **Resume-safe** with markdown plans + JSON tracker + per-batch session reports.
+9. **Use the right skills** at every batch boundary (planning, working, validating).
+
+## Key user-confirmed constraints
+
+| Constraint | Value |
+|---|---|
+| Android publish target | **The website wrapped via Capacitor** (NEW Play Store listing, fresh keystore). NOT example-apps. |
+| Backend deployment | **Deploy-ready only** — code complete, runbook clean, user does the actual deploy. |
+| Auth verification | **First batch** — Google OAuth + Sanctum + Spatie RBAC was just swapped (commit 8eaf4de, 2026-05-11). Verify end-to-end. |
+| Play Console state | **Fresh listing** — no existing keystore reuse. |
+
+---
+
+## Scope: what's in / out
+
+### IN scope this run
+
+- **`backend/`** (Laravel 11 + Nova 5 + Sanctum + Spatie + Socialite) — deploy-readiness fixes, tests for the new auth, FormRequest consistency, stale Firebase reference cleanup.
+- **`website/`** (React + Vite + Radix + TanStack Query + Capacitor 8.3.1) — ESLint hooks-rules fixes, Capacitor Preferences token storage, admin page TanStack-Query migration, console.* cleanup, Play-Store metadata cleanup, signing config + ProGuard, branded icons, SEO date refresh, legal page refresh.
+- **Root plugin (`src/`, `android/`, `ios/`)** — integration test localStorage fix, version + JSON-LD sync.
+- **Play Store launch assets** under `website/app-publish-assets/` — Firestore references purged, screenshots-capture runbook documented.
+- **Master CLAUDE.md + AGENTS.md** synchronisation at root and `website/`.
+
+### OUT of scope this run
+
+- Actual `firebase deploy` of the website (user does it after batches close).
+- Actual production-host SSH deploy of Laravel (deploy-ready only).
+- Generating real screenshot PNGs (user captures from a running emulator/device).
+- Generating a release keystore file (user does that locally with `keytool`).
+- iOS publishing (Android is the only platform requested this session).
+- Docs site at `native-update-docs/` (closed-out 2026-05-11, separate cooldown).
+
+---
+
+## Batch summary
+
+10 batches, each 40–60 min, 1–4 concrete tasks. Full task list with file paths in [`01-BATCH-PLAN.md`](./01-BATCH-PLAN.md).
+
+| # | Batch | Focus | Verification |
+|---|---|---|---|
+| 1 | Auth + critical backend fixes | Sanctum expiry, `/me` gating, LOG_LEVEL, stale Firebase comments | `php artisan test` green |
+| 2 | Website build fixes | 4 ESLint hooks-rules errors + 9 plugin test failures | `yarn build` + `yarn lint` + `yarn test:run` green |
+| 3 | Auth token via Capacitor Preferences | Token storage swap, 401 auto-redirect | yarn typecheck + manual auth walkthrough |
+| 4 | Backend coverage tests | OAuth, Sanctum, Roles tests + UpdateBuildRequest FormRequest | `php artisan test` higher count, all green |
+| 5 | Admin pages → TanStack Query | 3 admin pages + 2 dashboard pages | yarn build clean, query keys consistent |
+| 6 | Console.* cleanup | 2 ExamplesPage call sites + Firebase comment sweep | grep proves zero real violations |
+| 7 | Play Store metadata + legal pages | Strip Firestore refs, refresh Privacy/Terms/Cookies/Security | grep zero "firestore" in metadata + legal |
+| 8 | Android signing + ProGuard + build guide | build.gradle signing block, minifyEnabled, BUILD_FOR_PLAY_STORE.md | `./gradlew assembleDebug` clean |
+| 9 | App icons + splash + screenshot guide | Branded mipmap-* icons, splash bg, screenshot capture runbook | `cap sync` + visual check |
+| 10 | SEO refresh + final verification + audit closure | Dates bump, JSON-LD version sync, sitemap regen, CLAUDE.md update | All 3 build commands green |
+
+---
+
+## Skills invoked per phase
+
+Per RULE #0 (highest priority), the matching skill is invoked **before** any code edits in each phase:
+
+| Phase | Skills |
+|---|---|
+| Planning (this doc) | `writing-plans`, `stack-audit` |
+| Batch 1 — auth + backend | `laravel-specialist`, `firebase-auth-basics` (legacy ref check), `security-best-practices` |
+| Batch 2 — build fixes | `react-best-practices`, `react-19` (rules-of-hooks), `vitest` |
+| Batch 3 — Capacitor Preferences | `capacitor-best-practices`, `capacitor-plugins`, `capacitor-offline-first` |
+| Batch 4 — backend tests | `laravel-specialist`, `security-best-practices` |
+| Batch 5 — TanStack migration | `tanstack-query-best-practices`, `react-best-practices` |
+| Batch 6 — console cleanup | (trivial — covered by file-edit pre-check) |
+| Batch 7 — metadata + legal | `copywriting`, `web-design-guidelines` |
+| Batch 8 — Android signing | `capacitor-app-store`, `capacitor-android`, `security-best-practices` |
+| Batch 9 — icons + splash | `capacitor-splash-screen`, `frontend-design` |
+| Batch 10 — SEO closure | `ai-seo`, `seo`, `stack-audit` |
+
+---
+
+## Resume contract
+
+If this conversation is compacted or restarted:
+
+1. Read `docs/tracking/finalization-2026-05-16-tracker.json` (single source of truth for resume state).
+2. Find the lowest-numbered batch with `status != "completed"` in `batches[]`. That's where we resume.
+3. Read this plan (`00-FINALIZATION-PLAN.md`) + the batch plan (`01-BATCH-PLAN.md`) + the matching session report under `sessions/`.
+4. Invoke the matching skills for the batch domain (per the table above).
+5. Apply the batch's fixes per `01-BATCH-PLAN.md`.
+6. Run that batch's verification command list.
+7. ONE commit per batch with the message specified in the batch plan.
+8. Update the tracker (`status: "completed"`, `completed_at: today`, append `runHistory[]` row with commit SHA + 2–3 line summary).
+9. Write the session report under `docs/project-audit/2026-05-16/sessions/batch-NN.md`.
+
+Do **NOT** redo batches that are already `status: "completed"`. The tracker is authoritative — trust it.
+
+---
+
+## Definition of done (whole audit)
+
+- All 10 batches `status: "completed"` in the tracker
+- `yarn build` (root + website) returns exit 0 with no warnings beyond the documented 3rd-party suppressions
+- `yarn lint` (root + website) returns exit 0
+- `yarn test:run` (root) returns all-green
+- `php artisan test` (backend) returns all-green with strictly more tests than the baseline
+- `./gradlew assembleDebug` (website/android) returns success
+- A signed `app-release.aab` can be produced by following `website/BUILD_FOR_PLAY_STORE.md` (user runs this step)
+- Zero `console.*` calls outside `src/utils/logger.ts` / `src/lib/logger.ts` (excluding doc code blocks)
+- Zero `Firestore` / `Firebase Auth` references in `app-publish-assets/` and current legal pages
+- Updated portfolio info file, CLAUDE.md + AGENTS.md, and tracker close-out
+- ONE commit per batch, all pushed to `main`