native-update 1.4.9 → 3.1.0

package/docs/project-knowledge-base/05-docs-corpus-inventory.md

@@ -0,0 +1,256 @@
+# Native Update Docs Corpus Inventory
+
+## Metadata
+
+- **Reference Date:** 2026-05-18
+- **Last Updated:** 2026-05-18
+- **Goal:** Enumerate the current `/docs` folder so AI tools know what documentation already exists before planning, writing, or duplicating work
+
+## Coverage Note
+
+This file inventories the docs currently present in `/docs`. It is a high-context index, not a replacement for reading the source documents when exact wording or implementation detail is needed.
+
+There is also a separate **public Docusaurus site** at the sibling repo `native-update-docs/` (deployed to Firebase Hosting). That site mirrors the curated user-facing subset (Tutorials, How-to, Reference, Explanation — Diátaxis), and is not duplicated here.
+
+## Root-Level Docs
+
+| Path | Purpose / Notes |
+|------|------------------|
+| `docs/README.md` | Main docs landing page and public docs overview |
+| `docs/APP_REVIEW_GUIDE.md` | Review-related guide content |
+| `docs/BUNDLE_SIGNING.md` | Signing workflow and bundle security guidance |
+| `docs/CHANGELOG.md` | Project change history |
+| `docs/COMPREHENSIVE_AUDIT_REPORT.md` | Broad audit/reporting artifact |
+| `docs/EXAMPLE_APPS_SIMPLIFICATION_PLAN.md` | Plan for simplifying example apps |
+| `docs/EXAMPLE_APPS_SIMPLIFICATION_TRACKER.md` | Tracking file for example-app simplification |
+| `docs/KNOWN_LIMITATIONS.md` | Explicit limitations and caveats |
+| `docs/LIVE_UPDATES_GUIDE.md` | OTA/live update guidance |
+| `docs/archive/MARKETING_WEBSITE_PLAN.md` | Marketing website planning document — SUPERSEDED, archived 2026-05-18 (also removed from public sitemap + website/public/package-docs/ mirror) |
+| `docs/MARKETING_WEBSITE_TRACKER.md` | Marketing website progress tracker (SUPERSEDED — kept in `docs/` because the 2026-05-11 audit-batch entry in CLAUDE.md still references it; the SUPERSEDED notice in the file body explains why) |
+| `docs/MIGRATION.md` | Migration information (includes v2 → v3.0.0 breaking-change notes for the Firestore removal) |
+| `docs/NATIVE_UPDATES_GUIDE.md` | Native app update guidance |
+| `docs/PERFORMANCE.md` | Real-world OTA framing + microbenchmark targets + hot-paths map |
+| `docs/PROJECT_COMPLETION_TRACKER.md` | Completion/progress tracker |
+| `docs/QUICK_START.md` | Fast-start implementation guidance |
+| `docs/README.md` | Top-level docs overview |
+| `docs/REMAINING_FEATURES.md` | Remaining or planned feature notes |
+| `docs/ROADMAP.md` | Roadmap/status file |
+| `docs/SECURITY.md` | High-level security documentation |
+| `docs/SECURITY-IF-REPO-PUBLIC.md` | Preventive runbook for the day this repo goes public (secret-rotation table + history-scrub commands) |
+| `docs/TESTING_REQUIREMENTS.md` | Testing expectations and requirements |
+| `docs/analytics-tracking.md` | Analytics tracking conventions |
+| `docs/background-updates.md` | Background update feature guide |
+| `docs/capacitor-official-plugins.md` | Official Capacitor plugin status registry |
+| `docs/capawesome-plugins.md` | Capawesome plugin status registry |
+| `docs/cli-reference.md` | CLI usage reference |
+| `docs/error-handling-tracking.md` | Error handling + tracking registry |
+| `docs/package-audit.md` | Dependency audit notes |
+| `docs/production-readiness.md` | Production readiness checklist/context (refreshed 2026-05-18) |
+| `docs/rules-tracker.md` | Generic Project Rules application tracker |
+| `docs/seo-aeo-rules.json` | SEO/AEO rules JSON |
+| `docs/server-requirements.md` | Backend/server requirement notes |
+
+Note: `docs/play-console-rejection-rules.json` is intentionally NOT kept here — the canonical file lives at `~/.claude/play-console-rejection-rules.json`. Old local copies were removed per the IRON-SOLID rule in CLAUDE.md.
+
+## API Docs
+
+| Path | Purpose / Notes |
+|------|------------------|
+| `docs/api/API.md` | Top-level API overview |
+| `docs/api/FEATURES.md` | Feature-oriented API/behavior summary |
+| `docs/api/app-review-api.md` | App review API surface |
+| `docs/api/app-update-api.md` | App update API surface |
+| `docs/api/background-update-api.md` | Background update API surface |
+| `docs/api/events-api.md` | Event listener and event model reference |
+| `docs/api/live-update-api.md` | OTA/live update API reference |
+
+## Getting Started Docs
+
+| Path | Purpose / Notes |
+|------|------------------|
+| `docs/getting-started/configuration.md` | Config options and setup details |
+| `docs/getting-started/installation.md` | Installation steps |
+| `docs/getting-started/quick-start.md` | Quick implementation guide |
+
+## Feature Docs
+
+| Path | Purpose / Notes |
+|------|------------------|
+| `docs/features/app-reviews.md` | In-app review feature details |
+| `docs/features/app-updates.md` | Native app update feature details |
+| `docs/features/live-updates.md` | OTA/live update feature details |
+| `docs/features/laravel-nova-backend/ASSESSMENT-SUMMARY.md` | Laravel + Nova backend assessment summary |
+| `docs/features/laravel-nova-backend/IMPLEMENTATION-PLAN.md` | Laravel + Nova implementation plan |
+| `docs/features/laravel-nova-backend/progress-tracker.json` | Laravel + Nova progress tracker |
+| `docs/features/laravel-nova-backend/credentials.ignore.md` | gitignored credentials reference (not committed) |
+
+## Guide Docs
+
+| Path | Purpose / Notes |
+|------|------------------|
+| `docs/guides/BACKEND_TEMPLATES_GUIDE.md` | How backend templates are intended to be used |
+| `docs/guides/admin-panel.md` | Admin panel/dashboard usage |
+| `docs/guides/channel-management.md` | Channel setup and usage |
+| `docs/guides/dashboard-guide.md` | Dashboard usage guide |
+| `docs/guides/deployment-guide.md` | Deployment guidance |
+| `docs/guides/end-to-end-workflow.md` | Full workflow from setup to production |
+| `docs/guides/key-management.md` | Key generation and management |
+| `docs/guides/migration-from-codepush.md` | CodePush migration guide |
+| `docs/guides/security-best-practices.md` | Secure update implementation guidance |
+| `docs/guides/testing-guide.md` | Testing procedures and expectations |
+| `docs/guides/troubleshooting.md` | Troubleshooting and issue resolution guide |
+
+Note: `no-cost-firestore-google-drive-backend.md` and `no-cost-backend-implementation-plan.md` were removed on 2026-05-18 — the no-cost Firestore + Drive architecture was deliberately abandoned in v3.0.0 (Laravel + MySQL is the only backend now).
+
+## Examples Docs
+
+| Path | Purpose / Notes |
+|------|------------------|
+| `docs/examples/advanced-scenarios.md` | More advanced use cases and patterns |
+| `docs/examples/android-manifest-example.xml` | Android manifest example |
+| `docs/examples/basic-usage.md` | Basic implementation examples |
+| `docs/examples/node-express-backend-example.md` | Node/Express backend example |
+| `docs/examples/react-capacitor-example.md` | React + Capacitor frontend example |
+
+Note: `firebase-backend-example.md` was removed during post-closure cleanup (commit `3a8dda6`).
+
+## Plans
+
+| Path | Purpose / Notes |
+|------|------------------|
+| `docs/plans/PLANNING_COMPLETE_SUMMARY.md` | Summary of planning phase |
+| `docs/plans/TASK_1_ANDROID_EXAMPLE_APP.md` | Android example-app planning task |
+| `docs/plans/TASK_2_API_ENDPOINTS.md` | API endpoint planning |
+| `docs/plans/TASK_2_DASHBOARD_UI_UX.md` | Dashboard UX planning |
+| `docs/plans/TASK_2_DATABASE_SCHEMA.md` | Database schema planning (historical — may pre-date Laravel + MySQL adoption) |
+| `docs/plans/TASK_2_GOOGLE_DRIVE_INTEGRATION.md` | Drive integration planning |
+| `docs/plans/TASK_2_SAAS_ARCHITECTURE.md` | SaaS architecture planning |
+| `docs/plans/TASK_2_USER_AUTHENTICATION.md` | Auth planning (historical — predates the Socialite + Sanctum swap) |
+
+## Reports
+
+Historical status, audit, and verification reports. Useful as timeline artifacts; not authoritative for current state.
+
+| Path | Purpose / Notes |
+|------|------------------|
+| `docs/reports/AUDIT_SUMMARY_2025-12-26.md` | Historical audit summary |
+| `docs/reports/CLAUDE-CODE-COMPLETION-PROMPT.md` | Internal prompt/report artifact |
+| `docs/reports/CLAUDE_CODE_PROMPT.md` | Internal prompt/report artifact |
+| `docs/reports/CODEBASE_STATUS_REPORT.md` | Codebase status report |
+| `docs/reports/COMPLETE_VERIFICATION.md` | Verification report |
+| `docs/reports/COMPREHENSIVE-PROJECT-AUDIT-2026-02-24.md` | Detailed later audit report |
+| `docs/reports/EVENT_FLOW_VERIFICATION.md` | Event flow verification notes |
+| `docs/reports/EXAMPLE_APPS_SIMPLIFICATION_COMPLETE.md` | Completion note for example-app simplification |
+| `docs/reports/FINAL_STATUS.md` | Status summary |
+| `docs/reports/FINAL_VERIFICATION_CHECKLIST.md` | Release/readiness checklist |
+| `docs/reports/MARKETING_WEBSITE_COMPLETE.md` | Website completion report |
+| `docs/reports/PACKAGE_COMPLETENESS_REPORT.md` | Package completeness analysis |
+| `docs/reports/PRODUCTION_STATUS.md` | Historical production-status report; contains older readiness framing |
+| `docs/reports/PROJECT_RESTRUCTURE_2025-12-27.md` | Restructure report |
+| `docs/reports/PROJECT_RESTRUCTURE_FINAL_SUMMARY.md` | Final restructure summary |
+| `docs/reports/PUBLISHING_VERIFICATION.md` | Publishing/release verification |
+| `docs/reports/RELEASE_READY_SUMMARY.md` | Release readiness summary |
+| `docs/reports/claude-completion.json` | JSON status/report artifact |
+
+## Security Subfolder
+
+| Path | Purpose / Notes |
+|------|------------------|
+| `docs/security/certificate-pinning.md` | Certificate pinning details |
+| `docs/security/PRE-LAUNCH-PENTEST-CHECKLIST.md` | DIY pentest checklist (dep hygiene, authN/authZ, CORS/CSRF, bundle integrity, file safety, data handling, operational safety, mobile platform, 9 specific attack paths) |
+
+## Deployment Subfolder
+
+| Path | Purpose / Notes |
+|------|------------------|
+| `docs/deployment/PRODUCTION-DEPLOY-CHECKLIST.md` | Production deploy runbook |
+| `docs/deployment/HOSTINGER_DEPLOY.md` | Hostinger-specific deploy notes |
+
+## Docs Site Subfolder
+
+| Path | Purpose / Notes |
+|------|------------------|
+| `docs/docs-site/scope.md` | Public Docusaurus site scope |
+| `docs/docs-site/plan.md` | Public Docusaurus site plan (10-batch flow) |
+| `docs/docs-site/tracker.json` | Public Docusaurus site progress tracker (status: COMPLETE; 7-day cooldown) |
+
+## Project Audit Subfolder
+
+| Path | Purpose / Notes |
+|------|------------------|
+| `docs/project-audit/PRODUCTION-READINESS-AUDIT-2026-05-08.md` | Production-readiness audit findings (39 items + 5 roadmap) |
+| `docs/project-audit/BATCH-PLAN.md` | 10-batch production-readiness fix plan |
+| `docs/project-audit/MARKETING-WEBSITE-FINDINGS-2026-05-11.md` | Marketing-website specific findings |
+| `docs/project-audit/2026-05-16/` | Finalization audit for Play Store publishing (10 batches, all complete) |
+
+## Tracking Subfolder
+
+| Path | Purpose / Notes |
+|------|------------------|
+| `docs/tracking/IMPLEMENTATION_TRACKER.md` | Implementation tracking |
+| `docs/tracking/capacitor-rollout-note-2026-03-01.md` | Rollout note / dated tracking artifact |
+| `docs/tracking/completion-tracker-2026-02-24.json` | JSON completion tracker |
+| `docs/tracking/full-audit-tracker.json` | Retired full-audit tracker (superseded by production-readiness tracker) |
+| `docs/tracking/production-readiness-audit-tracker.json` | Authoritative production-readiness audit tracker |
+| `docs/tracking/finalization-2026-05-16-tracker.json` | Finalization-audit tracker (status: COMPLETE) |
+| `docs/tracking/seo-checklist-tracker.json` | SEO checklist tracker |
+
+## Social Media Marketing Subfolder
+
+| Path | Purpose / Notes |
+|------|------------------|
+| `docs/social-media-marketing/README.md` | Per-file/batch policy + run history + char-limit + content-honesty rules |
+| `docs/social-media-marketing/posts-batch-01.md` | 10 LinkedIn/Facebook posts (2700–2900 chars each) |
+| `docs/social-media-marketing/posts-batch-02.md` | 10 LinkedIn/Facebook posts |
+| `docs/social-media-marketing/whatsapp-messages-batch-01.md` | 30 WhatsApp messages (400–600 chars) |
+| `docs/social-media-marketing/whatsapp-status-batch-01.md` | 30 WhatsApp status messages (240–400 chars) |
+
+## Existing Project Profile and AI-Oriented Docs
+
+| Path | Purpose / Notes |
+|------|------------------|
+| `docs/project-profiles/native-update-capacitor-update-platform-project-profile-last-updated-2026-05-19.md` | Current dated project profile (refreshed 2026-05-19 after v3.0.0 + Sanctum swap + finalization audit + Phase A purge); older 2026-03-* dated profiles deleted in the same commit per the weekly-refresh-with-history-cap rule |
+
+## How AI Should Use The Docs Corpus
+
+### For Implementation
+
+- Start with `docs/getting-started/*`, `docs/api/*`, `docs/features/*`, and `docs/guides/*`
+
+### For Product Positioning
+
+- Use `docs/README.md`, feature docs, dashboard guides, website pages, and the most recent project profile
+
+### For Architecture or Backend Planning
+
+- Use `docs/features/laravel-nova-backend/*`, `docs/api/*`, `docs/deployment/*`, and the live Laravel codebase at `backend/`
+- DO NOT use the historical `docs/plans/TASK_2_*` files as architectural truth — they predate the Laravel adoption
+
+### For Testing
+
+- Use `docs/TESTING_REQUIREMENTS.md`, `docs/guides/testing-guide.md`, verification reports, and test files in source
+
+### For Historical Context
+
+- Use `docs/plans/*`, `docs/reports/*`, and tracking files
+
+### For Legal / Compliance / Security
+
+- Use `docs/SECURITY.md`, `docs/SECURITY-IF-REPO-PUBLIC.md`, `docs/security/*`, `docs/guides/security-best-practices.md`, website legal pages, and `docs/production-readiness.md`
+
+## Important Interpretation Rule
+
+The `/docs` folder mixes:
+
+- user-facing docs
+- implementation docs
+- planning artifacts
+- historical reports
+- status snapshots
+
+AI tools should not treat all documents as equally current. For current technical truth, validate against:
+
+1. Source code (`src/`, `website/src/`, `backend/`)
+2. The newest dated documents (look at file dates and dated audit folders)
+3. This knowledge base (refreshed 2026-05-18)
+4. The root `CLAUDE.md` Audit Record table

package/docs/project-knowledge-base/06-operations-testing-legal-content.md

@@ -0,0 +1,208 @@
+# Native Update Operations, Testing, Legal, and Content Context
+
+## Metadata
+
+- **Reference Date:** 2026-05-18
+- **Last Updated:** 2026-05-18
+
+## Operations Context
+
+### Release and Delivery Model
+
+- Plugin code ships via npm as `native-update`
+- Dashboard supports browser-driven ZIP upload workflows
+- Google Drive stores release bundles (server-side OAuth, encrypted tokens on the User row)
+- Laravel + MySQL stores user accounts, apps, API keys, signing keys, builds, rollouts, subscriptions, and analytics events
+- Nova admin at `/nova` provides full CRUD + custom actions over the same MySQL data
+
+### Channel Model
+
+- production
+- staging
+- development
+
+Observed product messaging and docs position these as the primary update channels.
+
+### Rollout Model
+
+- percentage-based rollout
+- pause/resume support
+- gradual or scheduled rollout concepts in schema/docs
+- rollout configuration stored on the Build row (`rollout_enabled`, `rollout_percentage`, `rollout_start_time`, `rollout_end_time`, `target_segments`)
+
+### Deployment Model
+
+- **Backend (Laravel):** deployed to any PHP 8.2+ host. Runbook in `docs/deployment/PRODUCTION-DEPLOY-CHECKLIST.md`. Hostinger-specific notes in `docs/deployment/HOSTINGER_DEPLOY.md`. Queue worker required for async jobs (systemd unit template included).
+- **Website (React SPA):** deployed to Firebase Hosting via the `website/firebase.json` config. Firebase Hosting is the ONLY Firebase usage; there is no Firestore, no Firebase Auth, no Firebase Functions in the live architecture.
+- **Public docs site (Docusaurus):** sibling repo `native-update-docs/`, also Firebase Hosting (same hosting-only pattern).
+- **Mobile dashboard wrapper:** website Capacitor-wrapped for Play Store publishing (see `docs/project-audit/2026-05-16/` for the publishing flow).
+
+## Testing Context
+
+### Test Layers Present In Repo
+
+- Backend Pest/PHPUnit tests under `backend/tests/` (~136 passing including OAuth + Sanctum + Spatie + UpdateBuildRequest FormRequest + PayPal webhook + BundleUpload + UserLicense)
+- iOS XCTest files under `ios/Tests/NativeUpdateTests/`
+- Android JUnit/Kotlin tests under `android/src/test/java/com/aoneahsan/nativeupdate/`
+
+### Testing Documentation Present
+
+- `docs/TESTING_REQUIREMENTS.md`
+- `docs/guides/testing-guide.md`
+- `docs/PERFORMANCE.md` (microbenchmark targets + regression workflow)
+- verification and audit reports under `docs/reports/`
+
+## Security Context
+
+### Security Themes Repeated Across Repo
+
+- SHA-256 checksum validation
+- RSA-SHA256 signing and verification
+- HTTPS enforcement
+- certificate pinning support
+- manifest/file integrity
+- secure update delivery
+- fail-closed on integrity violation; fail-open on availability (documented philosophy in the Docusaurus site `error-handling-philosophy.md`)
+- private keys never leave the Laravel host
+- Drive OAuth tokens encrypted at rest (Laravel encrypter)
+- Sanctum tokens hashed at rest; plain-text shown once on issuance
+- ProGuard/R8 + signing config on Android release builds
+
+### Security Docs Present
+
+- `docs/SECURITY.md`
+- `docs/SECURITY-IF-REPO-PUBLIC.md` (preventive runbook for the day the repo flips public — secret-rotation table + history-scrub commands)
+- `docs/BUNDLE_SIGNING.md`
+- `docs/security/certificate-pinning.md`
+- `docs/security/PRE-LAUNCH-PENTEST-CHECKLIST.md` (10-section DIY pentest checklist)
+- `docs/guides/security-best-practices.md`
+- SecurityPage on website
+
+## Legal and Compliance Surfaces
+
+### Website Legal Pages
+
+- `/privacy`
+- `/terms`
+- `/cookies`
+- `/data-deletion`
+- `/security`
+- `/contact`
+
+These pages are explicitly called out in `website/CLAUDE.md` as important and app-store-relevant. They were updated in 2026-05-16 Batch 7 to reflect the Sanctum + Laravel stack (Firebase Auth references removed).
+
+### Legal Messaging Themes In Website
+
+- privacy handling
+- account deletion path (revokes Sanctum tokens, soft-deletes User row, clears encrypted Drive tokens, cascades to apps/builds)
+- support/contact identity
+- security positioning (no fabricated SOC/ISO/SLA claims — removed in 2026-05-16 Batch 7)
+- ownership/control messaging around Google Drive files
+
+### Play Store Compliance Notes
+
+- Merged AndroidManifest at `android/app/build/intermediates/merged_manifests/*/AndroidManifest.xml` MUST be inspected before every AAB upload — Capacitor/Cordova plugins auto-inject permissions
+- Sensitive permissions (CAMERA, RECORD_AUDIO, ACCESS_FINE_LOCATION, READ_CONTACTS, etc.) require: matching privacy-policy section + Data Safety row + runtime-prompt UX + non-permission fallback
+- Branded launcher icons (15 PNGs), splash (11 PNGs), 3 Play Store graphics rendered from SVG via rsvg-convert in 2026-05-16 Batch 9
+- Play Store rejection rules: read from `~/.claude/play-console-rejection-rules.json` (single global source — never copy into project)
+
+## Content and SEO Context
+
+### Built-In Public Content Surfaces
+
+- Home page
+- Features page (1492+ words, FAQ schema, HowTo schema, SoftwareApplication schema)
+- Pricing page (1457+ words, Product schema with real $0/$29/$199 Offers)
+- About page (1913+ words, Person + FAQPage schema)
+- Docs page
+- Examples page
+- Feed page
+- Sitemap page
+- Contact page
+
+### Built-In Discovery Files
+
+- `robots.txt` (30+ AI bots allow-listed)
+- `sitemap.xml` (auto-generated, every public URL with `<lastmod>`)
+- `sitemap-index.json`
+- `feed.xml` (RSS 2.0 with runtime `lastBuildDate`)
+- `llms.txt` (Jeremy Howard spec)
+- `llms-full.txt` (long-form AI profile)
+- `ai.txt` (training/citation policy)
+- `humans.txt`
+- `.well-known/security.txt` (RFC 9116)
+- `pricing.md` (machine-readable pricing for AI buying agents)
+
+### Social/Portfolio Context Already Added
+
+- Project profile exists under `docs/project-profiles/`
+- Portfolio info file at root: `NATIVE-UPDATE_portfolio-info_YYYY-MM-DD.md` (weekly refresh)
+- Social-media marketing content under `docs/social-media-marketing/` (posts, WhatsApp messages, status)
+- This knowledge base supports future content generation with technical accuracy
+
+### Best Content Angles
+
+- open-source Capacitor infrastructure
+- OTA update engineering
+- secure mobile release workflows
+- dashboard and release-ops UX
+- Laravel + Nova self-hostable backend (CodePush alternative without vendor lock-in)
+- cross-platform engineering across TypeScript, Swift, Kotlin, PHP, and React
+- AI-ready docs and developer enablement (llms.txt, JSON-LD, machine-readable pricing)
+
+## Planning and Decision-Making Rules For AI
+
+- Do not invent user counts, stars, revenue, or adoption metrics.
+- Prefer current source code and route definitions over older historical reports.
+- Treat roadmap items as future-facing unless code confirms they are already shipped.
+- When recommending changes for the website, consider sitemap/feed/legal page maintenance.
+- When recommending backend changes, propose them against the Laravel codebase at `backend/`. The no-cost Firestore + Drive architecture was abandoned in v3.0.0 — do not resurrect it.
+- When recommending storage changes, prefer Google Drive (already wired with server-side OAuth) or FilesHub (already wired for misc user assets). Don't propose S3 or Firebase Storage.
+
+## Known Constraints and Notes
+
+- The repo contains both current and historical status documents.
+- Some legacy docs describe earlier incomplete states.
+- Admin access is determined through `spatie/laravel-permission` role assignment, not a `users.is_admin` boolean.
+- `super-admin` role bypasses every `can:` gate via `Gate::before`.
+- The dashboard is optimized for authenticated operators, not end users.
+- The website `DocsPage.tsx` was refactored 2026-05-19 from 1,406 lines into a 166-line shell + 2 helpers (`docs-page/components/`) + 13 per-section components (`docs-page/sections/`). All files now satisfy the workspace 500-line max; largest sub-file is `ExamplesSection.tsx` at 157 lines.
+
+## AI Usage Recommendations By Category
+
+### For Development
+
+- Use this knowledge base first
+- then inspect source modules and exact docs files tied to the feature
+- For backend work: read `backend/app/Http/Controllers/Dashboard/<thing>` + its FormRequest + its test before proposing changes
+
+### For Testing
+
+- map the feature to its page/module/native component
+- use testing docs plus test files to derive coverage strategy
+- backend test pattern: `backend/tests/Feature/<Thing>Test.php` (Pest); run via `php artisan test`
+
+### For Legal or Policy Work
+
+- review legal pages and security/privacy docs together
+- do not rely only on marketing copy
+- when scoping data-handling claims, validate against the actual Laravel models + migrations
+
+### For Marketing or Social Content
+
+- use product profile + this knowledge base + current website messaging
+- avoid unsupported performance or adoption claims
+- per `docs/social-media-marketing/README.md`: max 7 hashtags per post; honesty rules apply; only describe features that exist in the live codebase
+
+### For Planning
+
+- check roadmap, remaining-features docs, plans, and code reality together
+- per-feature trackers live in `docs/features/<feature-slug>/00-tracker.json` (resumable JSON schema)
+
+## Maintenance Rule For This Knowledge Base
+
+- Update this folder every 2 weeks while the project is active
+- Update sooner when routes, forms, data models, docs, modules, legal pages, or backend assumptions change
+- Keep `Reference Date` and `Last Updated` current in each file
+- Keep this folder aligned with actual repo state, not just historical docs
+- When the Laravel schema changes (new migration), update `04-data-models-integrations.md` in the same task

package/docs/project-knowledge-base/README.md

@@ -0,0 +1,103 @@
+# Native Update AI Knowledge Base
+
+## Metadata
+
+- **Project:** Native Update
+- **Knowledge Base Purpose:** High-context reference set for AI tools, planning, development, QA, legal review, content generation, and portfolio/social reuse
+- **Coverage Goal:** Provide a practical, current map of the product, codebase, docs corpus, routes, forms, users, modules, integrations, and operating assumptions
+- **Reference Date:** 2026-05-18
+- **Last Updated:** 2026-05-18
+- **Update Cadence:** Every 2 weeks minimum while the project is active, plus any time major product or docs changes land
+- **History Policy:** Keep update history in this file and keep only the latest 10 entries
+
+## Folder Purpose
+
+This folder is the canonical high-context AI reference set for the Native Update project. It is meant to answer questions like:
+
+- What does the product do?
+- What features exist now?
+- Which users exist?
+- Which pages, routes, and forms are present?
+- Which services, stores, modules, and native layers exist?
+- What is the recommended backend and data model?
+- Which docs already exist in `/docs` and what do they cover?
+- What legal, marketing, testing, and planning context is already documented?
+
+This folder is intentionally different from the public docs. Public docs explain usage. This knowledge base explains the whole project to an AI system or future collaborator.
+
+## File Map
+
+- `01-system-overview.md`
+  Product scope, capabilities, platform coverage, user types, URLs, and decision context.
+
+- `02-routes-pages-forms-users.md`
+  Website routes, dashboard/admin routes, page purposes, major interactions, forms, and access rules.
+
+- `03-tech-stack-modules-services.md`
+  Repo architecture, package structure, frontend services, stores, plugin modules, CLI commands, native modules, and backend components.
+
+- `04-data-models-integrations.md`
+  MySQL schema, model purposes, authentication model (Sanctum + Spatie RBAC), Google Drive flow, manifest publishing flow, and system boundaries.
+
+- `05-docs-corpus-inventory.md`
+  Full inventory of the current `/docs` folder, grouped and described so AI can understand what knowledge already exists.
+
+- `06-operations-testing-legal-content.md`
+  Testing posture, production/release considerations, legal pages, SEO/content context, and known constraints for planning or messaging.
+
+## Primary Project URLs
+
+- Marketing website: `https://nativeupdate.aoneahsan.com`
+- Docs entry: `https://nativeupdate.aoneahsan.com/docs`
+- Public docs site (Docusaurus): `https://nativeupdate-docs.aoneahsan.com`
+- Contact page: `https://nativeupdate.aoneahsan.com/contact`
+- NPM package page: `https://www.npmjs.com/package/native-update`
+
+## High-Level Product Definition
+
+Native Update is an open-source Capacitor update platform. It combines:
+
+- OTA/live updates for web assets
+- native app update handling
+- in-app review prompting
+- background update checks
+- release manifests and rollout control
+- security validation and signing support
+- a Laravel 11 + Nova 5 web dashboard for app/build management
+- example backends (Node.js + Express) and example apps (React + Capacitor)
+- CLI tooling for release workflows
+
+## Backend Architecture (v3.0.0+)
+
+The hosted SaaS and self-host paths both run the same Laravel backend at `backend/`. There is no Firestore branch. The plugin SDK no longer ships any Firestore code.
+
+- Identity: Google OAuth via `laravel/socialite` → Sanctum personal access tokens
+- RBAC: `spatie/laravel-permission` with `sanctum` guard; roles `super-admin`, `admin`, `user`
+- Persistence: MySQL (Laravel migrations + Eloquent)
+- Admin UI: Laravel Nova 5
+- Storage: Google Drive (server-side OAuth, encrypted tokens) + FilesHub for misc user assets
+- Mobile API key plane: per-app API keys via `ValidateApiKey` middleware (separate from Sanctum)
+
+## Recommended Use Of This Folder
+
+- Use this folder as the first-stop AI context before generating plans, code proposals, QA checklists, legal summaries, portfolio content, SEO drafts, social content, or roadmap suggestions.
+- Use the public `/docs` folder when exact implementation or end-user guidance is needed.
+- If any detail in this folder and the source code conflict, the source code is the stronger authority and this folder should be updated.
+
+## Update Checklist
+
+- Re-check all routes in `website/src/router.tsx`
+- Re-check user/auth/admin assumptions in `backend/app/Http/Controllers/Auth/` + the spatie permission seeder
+- Re-check forms and fields on dashboard pages
+- Re-check package versions and tech stack across root, `website/`, `backend/`, `cli/`
+- Re-check MySQL schema in `backend/database/migrations/`
+- Re-check `/docs` inventory for added/removed files
+- Re-check any new `CLAUDE.md` files in nested subprojects
+- Update `Reference Date`, `Last Updated`, and `Update History`
+
+## Update History
+
+| Date | Summary |
+|------|---------|
+| 2026-05-18 | Full regeneration after v3.0.0 (Firestore removed) + 2026-05-11 auth swap (Firebase Auth → Socialite + Sanctum + Spatie RBAC). Removed all Firebase/Firestore references; rewrote tech-stack, data-model, routes, and operations files against the live Laravel + MySQL + Nova architecture. |
+| 2026-03-16 | Initial AI knowledge-base folder created with project-wide coverage across product, routes, forms, modules, data models, docs corpus, and operations context. |

package/docs/project-profiles/native-update-capacitor-update-platform-project-profile-last-updated-2026-05-19.md

@@ -0,0 +1,81 @@
+# Native Update - Capacitor Update Platform Project Profile
+
+## Document Metadata
+
+- **Project Name:** Native Update
+- **Project Type:** Open-source Capacitor plugin + Laravel-backed update management platform
+- **Primary Domain:** Mobile app infrastructure / developer tooling / OTA delivery
+- **Owner / Creator:** Ahsan Mahmood
+- **Primary Contact:** aoneahsan@gmail.com
+- **Package Name:** `native-update`
+- **Current Package Version Reference:** `3.0.1`
+- **License:** MIT
+- **Primary Website:** `https://nativeupdate.aoneahsan.com`
+- **Public Docs Site:** `https://nativeupdate-docs.aoneahsan.com` (Docusaurus, sibling repo `native-update-docs`)
+- **Reference Date:** 2026-05-19
+- **Last Updated:** 2026-05-19
+- **Filename Rule:** Always keep `last-updated-YYYY-MM-DD` in the filename
+- **Status Reference:** This profile reflects the repository state visible on 2026-05-19 from package metadata, source layout, docs, tests, dashboard docs, example apps, public Docusaurus docs site, and the 2026-05-16 finalization-audit closure.
+
+## Verification Snapshot
+
+- **Tests (root TypeScript):** `yarn test:run` — **62/62 passing** (Vitest)
+- **Tests (backend Laravel):** `php artisan test` — **136/136 passing** (Pest/PHPUnit)
+- **Build:** `yarn build` exit 0 (root plugin Rollup + website Vite + Docusaurus docs site); `yarn lint` exit 0 across root + website
+- **Capacitor sync:** `npx cap sync android` clean; gradle config parses
+- **Architecture:** v3.0.0 (2026-05-04) removed Firestore; Laravel 11 + Nova 5 + MySQL is the only backend. 2026-05-11 swapped Firebase Auth for Laravel Socialite + Sanctum personal access tokens + `spatie/laravel-permission` RBAC. 2026-05-16 finalization audit closed Play Store publishability end-to-end. 2026-05-18 Phase A cleanup purged the last Firebase/Firestore content references.
+
+## Executive Summary
+
+Native Update is a full update-management solution for Capacitor apps. It combines over-the-air web asset updates, native app store update flows, in-app review prompts, background update checks, security tooling, CLI utilities, two reference example apps, a public Docusaurus documentation site, and a Capacitor-wrapped React dashboard backed by a Laravel 11 + Nova 5 SaaS into one ecosystem. The project is positioned as both a reusable plugin and a broader release-operations platform for hybrid mobile products. After the v3.0.0 architectural simplification and the 2026-05-11 auth swap, the project runs on a single Laravel backend with Sanctum-token dashboard auth and Spatie RBAC — no Firebase backend.
+
+## Current Positioning
+
+Native Update helps Capacitor teams ship fixes faster, manage native store updates more intelligently, improve review prompting, and centralize release operations through a dashboard-driven workflow. It is stronger than a simple plugin because it includes the operational layer around updates — not just device APIs — and ships with a complete self-hosting story (Laravel + Nova + MySQL backend + Capacitor-wrapped dashboard + public Docusaurus docs site).
+
+## Core Product Value
+
+- **Speed:** OTA delivery for faster fixes and content changes
+- **Control:** Channels, percentage rollouts, pause/resume, rollback support, target-segment hooks, and update-strategy choices
+- **Security:** RSA-SHA256 signing, SHA-256 checksums, HTTPS posture, certificate pinning, encrypted Drive token storage, hashed-at-rest Sanctum tokens, fail-closed integrity rules
+- **Productivity:** CLI tooling (8 commands), 58-page Diátaxis docs site, two reference example apps, dashboard with TanStack Query-backed admin pages
+- **Ownership:** Open-source MIT-licensed plugin; self-hostable Laravel + Nova backend; private signing keys never leave the host
+
+## Proof Points In Current Repo State
+
+- Native Android (Kotlin) and iOS (Swift) implementations are present and tested (XCTest + JUnit)
+- CLI package present at `cli/` with 8 commands; `monitor` has signal handling + failure bail
+- Two reference example apps under `example-apps/`: `react-capacitor` (with app-update / app-review / background-update capability cards), `node-express` (minimal manifest-endpoint backend)
+- Capacitor-wrapped React dashboard at `website/` with TanStack Query data plane + Radix Dialog + URL-state forms
+- Laravel 11 + Nova 5 backend at `backend/` with full Pest test coverage (OAuth, Sanctum, Spatie, FormRequests, PayPal webhook, BundleUpload, UserLicense)
+- Public Docusaurus docs site at sibling repo `native-update-docs`: 58 pages, ~76k words, Diátaxis-organized, Firebase Hosting deploy-ready with 7 discovery files (robots / llms / llms-full / humans / security / sitemap-index / sitemap) and 3 JSON-LD blocks per page
+- Vitest-bench microbenchmark scaffold at `tools/bench/` for security-critical hot paths (SHA-256 + RSA-SHA256 verify)
+- 3 GitHub Actions workflows: `ci.yml`, `release.yml` (tag-driven npm publish with provenance), `example-bundle.yml` (release+manual+weekly-cron signed bundle attached to GitHub Release)
+- Android release readiness: signingConfigs + ProGuard/R8 + network_security_config + 10-section BUILD_FOR_PLAY_STORE.md runbook + 15 branded launcher PNGs + 11 splash PNGs + 3 Play Store graphics + screenshots/CAPTURE-GUIDE.md
+- Pre-launch DIY pentest checklist at `docs/security/PRE-LAUNCH-PENTEST-CHECKLIST.md` (10 sections + 9 specific attack paths)
+- Preventive repo-goes-public runbook at `docs/SECURITY-IF-REPO-PUBLIC.md`
+- Current automated verification passed cleanly on 2026-05-19
+
+## Resume / CV Summary
+
+Built **Native Update**, an open-source Capacitor update platform (v3.0.1, MIT-licensed) that unifies OTA delivery, native app updates, in-app reviews, RSA signing and SHA-256 checksum verification, an 8-command CLI for release operations, two reference example apps, a Laravel 11 + Nova 5 SaaS backend with Sanctum-token + Spatie-RBAC dashboard auth, a Capacitor-wrapped React dashboard, a public 58-page Docusaurus docs site, and a Play-Store-publishable Android distribution.
+
+## Resume-Ready Achievement Bullets
+
+- Built and ship `native-update` v3.0.1 on NPM — an open-source Capacitor update platform combining OTA updates, app-store update flows, and in-app reviews, with native Kotlin/Swift implementations, 62 passing root TypeScript tests, 136 passing backend Pest tests, and a Detox E2E suite.
+- Shipped a v3.0.0 BREAKING release that removed Firestore as a backend (~3000+ deletions) and routed all device → server traffic through a single Laravel HTTP API — cleaner ops, single source of truth, simpler reasoning for integrators.
+- Swapped Firebase popup auth for Laravel Socialite + Sanctum personal access tokens + `spatie/laravel-permission` RBAC (super-admin / admin / user roles, `Gate::before` super-admin bypass, per-route `can:` middleware) in a single 2026-05-11 cutover — production-shape auth without Firebase lock-in.
+- Built an entire ecosystem around the plugin: a Laravel 11 + Nova 5 SaaS backend, an 8-command CLI for release management, two reference example apps (React + Capacitor, Node.js + Express), and a React 19 + Vite 7 marketing/dashboard site (Capacitor-wrapped for Play Store) with full observability (Sentry + Clarity + Amplitude + page-view auto-track).
+- Shipped a public Docusaurus documentation site (`native-update-docs` sibling repo, Firebase Hosting) with 58 Diátaxis-organized pages (~76k words), 7 discovery files (robots / llms / llms-full / humans / security / sitemap-index / sitemap), and 3 JSON-LD blocks per page — measurably AI-citable.
+- Closed a 10-batch finalization audit on 2026-05-16 that made the Capacitor-wrapped dashboard Play-Store-publishable end-to-end: signingConfigs.release + ProGuard/R8 + network_security_config + 10-section BUILD_FOR_PLAY_STORE runbook + 15 branded launcher PNGs + 11 splash PNGs + Data Safety form + 4 rewritten legal pages.
+- Adopted `native-update` as the canonical OTA strategy across the Ahsan project portfolio, eliminating store-resubmission cycles for content-only updates.
+- Gated full-codebase audits behind a 7-day cooldown tracker to keep audit churn out of the commit log while preserving reproducible quality.
+
+## Update History
+
+| Date | Type | Notes |
+| --- | --- | --- |
+| 2026-05-19 | Material refresh | Major regeneration after 4 months of architecture change: covers v3.0.0 Firestore removal (2026-05-04), 2026-05-11 auth swap (Firebase Auth → Socialite + Sanctum + Spatie RBAC), 2026-05-11 public Docusaurus docs site shipped (58 pages, ~76k words), 2026-05-16 finalization audit closure (Play Store publishability), and 2026-05-18 Phase A Firebase/Firestore residue purge. Updated version 1.4.9 → 3.0.1, test counts 81 → 62/62 root + 136/136 backend, added public docs site URL, refreshed proof points to reflect Laravel + Nova + Capacitor-wrapped dashboard + GitHub Actions CI/CD + Android release readiness. Older dated profiles (2026-03-25, 2026-03-24, 2026-03-16) deleted in the same commit per user direction; this is the first dated profile for v3.x. |
+| 2026-03-25 | Remediation | Updated verification snapshot to the Yarn-only root package workflow after removing npm and pnpm from the root package path. (file deleted 2026-05-19) |
+| 2026-03-24 | Refreshed | Updated metadata, verification snapshot, and repo-state summary to match current package state. (file deleted 2026-05-19) |
+| 2026-03-16 | Previous | Prior project profile version. (file deleted 2026-05-19) |