native-update 2.0.0 → 3.1.0

package/docs/deployment/HOSTINGER_DEPLOY.md

@@ -19,8 +19,7 @@ Tested against Hostinger hPanel, shared Business plan, PHP 8.2, MySQL.
 | PayPal subscription plans | PayPal Dashboard → Subscriptions → Plans (create Pro + Enterprise, copy the `P-...` IDs) |
 | PayPal webhook ID | Set up in step 4, skip for now |
 | FilesHub API key | fileshub.zaions.com admin |
-| Firebase service account JSON | console.firebase.google.com → Project settings → Service accounts → Generate private key |
-| Google OAuth client | console.cloud.google.com → APIs & Services → Credentials |
+| Google OAuth client | console.cloud.google.com → APIs & Services → Credentials (used for both dashboard sign-in and Google Drive) |
 
 ---
 
@@ -78,9 +77,9 @@ The zip is ~67 MB. Upload it to Hostinger via SFTP to `~/uploads/`.
 3. **SSH**. hPanel → Advanced → SSH Access → Enable (if not already).
    Note the port (usually 65002) and username.
 
-4. **Upload secrets** via hPanel File Manager (or SFTP):
-   - Upload `firebase-credentials.json` to `~/` (not public_html). We'll
-     move it in step 3.
+4. **Upload the deploy zip** via hPanel File Manager (or SFTP) to
+   `~/uploads/`. (No Firebase credentials file is needed — auth is Google
+   Socialite + Sanctum, configured entirely via `.env`.)
 
 ---
 
@@ -108,14 +107,6 @@ rm -rf public_html
 ln -s app/public public_html
 ```
 
-Drop in the Firebase credentials file:
-
-```bash
-mkdir -p ~/domains/nativeupdatebe.aoneahsan.com/app/storage
-mv ~/firebase-credentials.json ~/domains/nativeupdatebe.aoneahsan.com/app/storage/
-chmod 600 ~/domains/nativeupdatebe.aoneahsan.com/app/storage/firebase-credentials.json
-```
-
 Configure the environment:
 
 ```bash
@@ -150,14 +141,17 @@ FILESHUB_BASE_URL=https://fileshub.zaions.com
 FILESHUB_API_KEY=_________
 FILESHUB_APP_ID=native-update
 
-# Firebase
-FIREBASE_PROJECT_ID=_________
-FIREBASE_CREDENTIALS_PATH=storage/firebase-credentials.json
+# Sanctum (OAuth-issued bearer tokens)
+SANCTUM_TOKEN_EXPIRATION=10080      # minutes (7 days)
+
+# Frontend (for OAuth redirect back to the dashboard SPA)
+FRONTEND_URL=https://nativeupdate.aoneahsan.com
 
-# Google OAuth (for Google Drive integration in dashboard)
+# Google OAuth — sign-in (Socialite) AND Google Drive integration
 GOOGLE_CLIENT_ID=_________
 GOOGLE_CLIENT_SECRET=_________
-GOOGLE_REDIRECT_URI=${APP_URL}/api/dashboard/google-drive/callback
+GOOGLE_REDIRECT_URI=${APP_URL}/api/auth/google/callback
+GOOGLE_DRIVE_REDIRECT_URI=${APP_URL}/api/dashboard/google-drive/callback
 
 # PayPal (live)
 PAYPAL_MODE=live
@@ -182,9 +176,13 @@ php artisan key:generate --force
 find . -type d -exec chmod 755 {} \;
 find . -type f -exec chmod 644 {} \;
 chmod -R 775 storage bootstrap/cache
-chmod 600 .env storage/firebase-credentials.json
+chmod 600 .env
 ```
 
+> The full, authoritative env contract (every `[REQUIRED]`/`[OPTIONAL]` key with its purpose)
+> is `backend/.env.example`. Populate the server `.env` from it — an incomplete `.env` (missing
+> a required key) is a common cause of a booting-but-500 backend.
+
 Run migrations and cache config for production:
 
 ```bash
@@ -204,9 +202,10 @@ curl -sS https://nativeupdatebe.aoneahsan.com/api/health
 ```
 
 Log in to Nova at `https://nativeupdatebe.aoneahsan.com/nova` with an
-email listed in `ADMIN_EMAILS` (Firebase-authenticated via the website
-dashboard) and verify the Apps / Builds / ApiKeys / SigningKeys /
-Subscriptions resources render.
+email listed in `ADMIN_EMAILS` (sign in via Google — Socialite issues the
+Sanctum session; the first sign-in by an `ADMIN_EMAILS` address is granted
+the `super-admin` role) and verify the Apps / Builds / ApiKeys /
+SigningKeys / Subscriptions resources render.
 
 ---
 
@@ -243,12 +242,15 @@ Should contain `PayPal webhook received` or `PayPal subscription activated`.
 
 ---
 
-## 5. (Optional) Cron for scheduled tasks
+## 5. Cron for scheduled tasks (REQUIRED as of v3.1.0)
 
-The current backend has no scheduled jobs. Add a cron only if/when
-`app/Console/Kernel.php` grows `$schedule` entries.
+The backend now runs a scheduled job: `analytics:cleanup` (defined in
+`routes/console.php`) prunes old `device_activities` **and**
+`analytics_events` rows monthly. Without the scheduler cron below those
+tables grow unbounded, so this cron is now required, not optional.
 
-hPanel → Advanced → Cron Jobs → Add:
+hPanel → Advanced → Cron Jobs → Add (runs every minute; Laravel's
+scheduler decides internally when each job is actually due):
 
 ```
 * * * * * cd ~/domains/nativeupdatebe.aoneahsan.com/app && php artisan schedule:run >/dev/null 2>&1
@@ -270,16 +272,15 @@ mv app app.old
 mkdir app && cd app
 unzip -q ~/uploads/nu-backend-NEW.zip -d .
 
-# Carry over secrets + credentials
+# Carry over secrets + stored files
 cp ../app.old/.env .env
-cp ../app.old/storage/firebase-credentials.json storage/firebase-credentials.json
 cp -a ../app.old/storage/app storage/ 2>/dev/null || true
 
 # Fix perms
 find . -type d -exec chmod 755 {} \;
 find . -type f -exec chmod 644 {} \;
 chmod -R 775 storage bootstrap/cache
-chmod 600 .env storage/firebase-credentials.json
+chmod 600 .env
 
 # Rebuild caches + apply migrations
 php artisan migrate --force
@@ -318,12 +319,52 @@ Migrations that were applied on the new release may need a manual
 
 ## 8. Known Hostinger constraints
 
-- **No persistent queue workers.** The backend uses `QUEUE_CONNECTION=database`
-  and currently dispatches nothing async. If that changes, add a 1-minute
-  cron running `php artisan queue:work --stop-when-empty`.
-- **No Redis.** Cache + sessions use the MySQL `CACHE_STORE=database` driver.
-- **PHP 8.2 is the stable default.** PHP 8.3 is available but untested.
+- **No persistent queue workers needed.** The backend uses
+  `QUEUE_CONNECTION=database`, but the only async work — the update-check
+  device-activity + analytics writes — is dispatched with
+  `dispatch(...)->afterResponse()`, which runs **in-process** during the
+  request's terminating phase (no `queue:work` daemon required). If a
+  future feature dispatches a real queued job, add a 1-minute cron running
+  `php artisan queue:work --stop-when-empty`.
+- **No Redis.** Cache + sessions use the MySQL `CACHE_STORE=database`
+  driver. The v3.1.0 latest-build cache (`App::getLatestBuildForChannel`,
+  45s TTL) works with any driver, including `database` and `file`.
+- **PHP 8.3+ is required** (Laravel 13 / `composer.json` `php: ^8.3`).
+  Select PHP 8.3 or newer in hPanel → Advanced → PHP Configuration before
+  deploying; PHP 8.2 will fail to boot the framework.
 - **Node/npm are not available via SSH on all plans.** The Vite build step
   runs locally; the zip ships pre-built `public/build/` assets.
 - **Nova admin assets** are served from `public/vendor/nova/...` after
   `php artisan nova:publish` — re-run after every deploy.
+
+---
+
+## 9. v3.1.0 deploy notes
+
+This release adds one migration and shifts two hot-path writes; nothing in
+the standard deploy flow above changes, but confirm each of these:
+
+1. **Run the new migration.** `php artisan migrate --force` applies
+   `2026_07_02_000001_extend_builds_channel_index` (adds a covering index
+   `builds_channel_lookup_idx` on `builds(app_id, channel, status,
+   created_at)`). Purely additive — no data change, safe to run live.
+2. **Re-cache config/routes/views** after the swap (already in the deploy
+   steps): `php artisan config:cache && php artisan route:cache &&
+   php artisan view:cache`.
+3. **Confirm the scheduler cron** from section 5 exists — `analytics:cleanup`
+   now also prunes `analytics_events`, so the monthly run matters.
+4. **No queue worker required** — see section 8 (the update-check writes run
+   via `afterResponse()`).
+
+### Large bundle downloads (optional)
+
+`BundleController@download` streams bundle files through PHP (a
+`StreamedResponse`). This is deliberate: it keeps the signed-URL / auth
+check as the single chokepoint in front of every download. On a server with
+`mod_xsendfile` (Apache) or `X-Accel-Redirect` (nginx), that streaming can
+be offloaded to the web server after the auth check by returning an
+`X-Sendfile` / `X-Accel-Redirect` header instead of the file body — freeing
+the PHP-FPM worker for the duration of the transfer. This is a documented
+option only; it is **not implemented** (Hostinger shared hosting does not
+expose the needed web-server config, and the current streaming approach is
+correct and safe as-is).

package/docs/deployment/PRODUCTION-DEPLOY-CHECKLIST.md

@@ -0,0 +1,184 @@
+# Production Deployment Checklist — Native Update Backend (Laravel 13 + Nova 5)
+
+**Last updated:** 2026-07-02
+**Scope:** `backend/` only. The plugin (`/`) and website (`website/`) ship via npm/Firebase Hosting respectively and have their own pipelines.
+**Companion:** `docs/deployment/HOSTINGER_DEPLOY.md` (host-specific steps for Hostinger).
+
+This checklist is the source of truth for "is this deploy safe to ship?". Run through it on every release until automation in `.github/workflows/release.yml` (Batch 8) replaces the manual gates.
+
+> **v3.1.0 deploy notes:** (1) Requires **PHP ≥ 8.3** (Laravel 13). (2) Runs one new migration
+> `2026_07_02_000001_extend_builds_channel_index` (additive covering index — safe live). (3) The
+> latest-build cache (`App::getLatestBuildForChannel`, 45s TTL) works with any `CACHE_STORE` incl.
+> `database`/`file`. (4) The update-check device/analytics writes use `dispatch(...)->afterResponse()`
+> — in-process, **no queue worker required**. (5) `analytics:cleanup` now prunes `analytics_events`
+> too, so the scheduler cron (§5) is **required**, not optional.
+
+---
+
+## 0 · Pre-flight (local machine, before pushing the deploy zip)
+
+- [ ] `git status` is clean on the branch you're shipping from.
+- [ ] `git pull --rebase` against the deploy branch — no unmerged remote work.
+- [ ] `composer install --no-interaction` succeeds.
+- [ ] `php artisan test` is **green** (all Feature + Unit tests pass).
+- [ ] `php artisan route:list --except-vendor` shows the routes you expect (no accidental new public routes).
+- [ ] `php -l app/` and `php -l routes/` report no syntax errors.
+
+---
+
+## 1 · `.env` for production (NOT committed; copied to server)
+
+The committed `.env.example` has `[REQUIRED]` tags on every var. On the server, populate a real `.env` with the production values. Verify each of these is set correctly:
+
+- [ ] `APP_ENV=production`
+- [ ] `APP_DEBUG=false` — **never** `true` in production (leaks stack traces, env, DB creds).
+- [ ] `APP_KEY` — generated once via `php artisan key:generate` on the server (or copied from a sealed vault). Never re-rotate without re-encrypting cookies/sessions.
+- [ ] `APP_URL=https://nativeupdatebe.aoneahsan.com`
+- [ ] `LOG_CHANNEL=daily`, `LOG_LEVEL=warning` (or `error`) — `debug` floods disk and leaks request shapes.
+- [ ] `CORS_ALLOWED_ORIGINS=https://nativeupdate.aoneahsan.com[,...]` — explicit list, no wildcards.
+- [ ] DB creds (`DB_HOST`, `DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD`) — production DB, not staging.
+- [ ] FilesHub: `FILESHUB_API_KEY`, `FILESHUB_BASE_URL`, `FILESHUB_APP_ID=native-update`.
+- [ ] Sanctum: `SANCTUM_TOKEN_EXPIRATION=10080` (minutes — 7 days; tune for security/UX trade-off).
+- [ ] Google OAuth (Socialite sign-in + Drive picker): `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `GOOGLE_REDIRECT_URI=${APP_URL}/api/auth/google/callback`, `GOOGLE_DRIVE_REDIRECT_URI=${APP_URL}/api/dashboard/google-drive/callback`. Both redirect URIs must be registered in Google Cloud Console for the OAuth client.
+- [ ] PayPal: `PAYPAL_MODE=live`, `PAYPAL_LIVE_*` filled, `PAYPAL_PLAN_PRO`, `PAYPAL_PLAN_ENTERPRISE`, `PAYPAL_WEBHOOK_ID`.
+- [ ] RBAC bootstrap: `ADMIN_EMAILS=ahsan@…[,…]` — first sign-in by any of these emails auto-assigns `super-admin` via spatie/laravel-permission.
+- [ ] Cache + queue: `CACHE_STORE=redis` (recommended for prod), `QUEUE_CONNECTION=redis` if Redis is available. Keep `database` only on tiny single-server deploys, and ensure `queue:work` is daemonized (see step 4).
+- [ ] File permissions on `.env`: `chmod 640` and owner = web user. NEVER world-readable.
+
+---
+
+## 2 · Deploy artifact (zip)
+
+The `backend/CLAUDE.md` "Production Deployment Zip Standard" section is the canonical zip recipe. Quick version:
+
+```bash
+cd backend
+php artisan optimize:clear
+composer install --no-dev --optimize-autoloader --classmap-authoritative
+npm ci && npm run build      # builds Vite assets if Nova-themed
+# zip into ../production-deploy/backend-production-YYYYMMDD-HHMMSS.zip
+```
+
+After zipping:
+```bash
+composer install              # restore dev deps locally so tests still work
+```
+
+- [ ] Zip excludes `tests/`, `node_modules/`, `.git/`, `*.sqlite`, `storage/logs/*.log`, `storage/framework/{cache/data,sessions,views}/*`.
+- [ ] Zip includes `vendor/` (production-only), built `public/build/` Vite assets, `composer.lock`, `package-lock.json`.
+
+---
+
+## 3 · On-server deploy (after upload + extract)
+
+Run these in order on the server, as the web user:
+
+```bash
+# 1. Install production deps if you didn't ship vendor/
+composer install --no-dev --optimize-autoloader
+
+# 2. Build front-end assets if not pre-built (yarn, not npm; usually pre-built in the zip)
+yarn install && yarn build
+
+# 3. Run migrations against production DB (forced — no prompt)
+php artisan migrate --force
+
+# 4. Symlink storage if first deploy
+php artisan storage:link
+
+# 5. Cache config + routes + views (don't skip — speeds boot 5–10x)
+php artisan config:cache
+php artisan route:cache
+php artisan view:cache
+
+# 6. Refresh permissions on storage + bootstrap/cache
+chown -R www-data:www-data storage bootstrap/cache
+chmod -R u+rwX,g+rX,o-rwx storage bootstrap/cache
+```
+
+- [ ] `php artisan about` reports `APP_DEBUG=false`, correct DB, correct queue/cache drivers.
+- [ ] `php artisan health-check` (or hit `/up`) returns 200.
+- [ ] Curl an API endpoint with a known-bad token — expect `401`, not a stack trace.
+
+---
+
+## 4 · Long-running processes (must be daemonized)
+
+`QUEUE_CONNECTION=database` (or `redis`) means jobs only run when a worker is alive. Without this, PayPal webhook handling, future analytics rollups, etc. will pile up silently.
+
+- [ ] systemd unit OR supervisor entry that runs `php artisan queue:work --tries=3 --max-time=3600` on boot.
+- [ ] Worker auto-restarts on failure.
+- [ ] Worker reload on deploy: `php artisan queue:restart` is run at end of step 3.
+- [ ] Log rotation configured for `storage/logs/laravel-*.log` (Laravel's `daily` channel rotates by date but doesn't prune).
+
+If using Horizon (Redis):
+- [ ] `horizon` service is up.
+- [ ] `/horizon` route is admin-gated (NOT publicly accessible).
+
+---
+
+## 5 · Scheduler cron (if using `app/Console/Kernel.php` schedule)
+
+Every Laravel project that uses `Schedule::command(...)` needs:
+
+```cron
+* * * * * cd /var/www/nativeupdatebe && php artisan schedule:run >> /dev/null 2>&1
+```
+
+- [ ] Cron entry exists for the web user.
+- [ ] `php artisan schedule:list` shows the expected scheduled jobs.
+
+---
+
+## 6 · Security gates
+
+- [ ] HTTPS is forced at the web-server level (nginx 301 from `:80`, or Cloudflare full-strict).
+- [ ] HSTS header is set with `max-age=31536000; includeSubDomains; preload`.
+- [ ] `/.env`, `/storage/`, `/.git/`, `/composer.json` return 404 over HTTP (not the file). Test with `curl -I`.
+- [ ] `/nova` is reachable but rejects non-super-admin users (test with a `user`-role account → redirect / 403).
+- [ ] `/horizon` (if used) is admin-gated.
+- [ ] PayPal webhook (`/api/webhooks/paypal`) verifies signatures — test by POSTing junk; expect 401.
+- [ ] Rate-limit on `/api/v1/updates/check` (configured via `throttle:` middleware) — verify by sending 60+ requests; expect 429.
+- [ ] CORS preflight: `curl -X OPTIONS -H "Origin: https://evil.example" https://nativeupdatebe.aoneahsan.com/api/v1/updates/check` returns no `Access-Control-Allow-Origin` for the bogus origin (config/cors.php uses an explicit allowlist).
+- [ ] RBAC bootstrap: every email listed in `ADMIN_EMAILS` will auto-receive the `super-admin` role on first sign-in. Verify the list matches the product stance (invite-only via `ADMIN_EMAILS` + manual `php artisan native-update:role-assign` for adds; open signup = leave `ADMIN_EMAILS` empty so everyone joins as `user`).
+
+---
+
+## 7 · Post-deploy smoke
+
+- [ ] Sign in via Google OAuth on the website dashboard — token issued, Nova accessible for any `super-admin`.
+- [ ] Create an App in the dashboard — row appears in DB.
+- [ ] Generate an API key — works.
+- [ ] Hit `/api/v1/updates/check` from a real device or curl with a valid `X-API-Key` and `X-Device-ID` — returns 200 + manifest.
+- [ ] Trigger a PayPal sandbox subscription end-to-end (in sandbox mode) and verify the webhook lands as a row update.
+- [ ] Tail `storage/logs/laravel-$(date +%F).log` for 5 minutes — no `error`/`emergency` lines.
+
+---
+
+## 8 · Rollback plan
+
+- [ ] Previous deploy's zip is preserved in `production-deploy/` (immutable artifact name).
+- [ ] DB migrations were reversible OR a snapshot was taken pre-migration.
+- [ ] Rollback procedure is one of: `(a)` swap symlinks back to the prior release dir, `(b)` re-extract the prior zip.
+- [ ] `queue:restart` is run after rollback so workers pick up the prior code path.
+
+---
+
+## 9 · Sign-off
+
+| Field | Value |
+|---|---|
+| Release tag | _e.g. `backend-v1.4.0`_ |
+| Deployed at | _UTC timestamp_ |
+| Deployed by | _name + git commit SHA_ |
+| Database snapshot | _path / id_ |
+| Smoke-test result | _link to log_ |
+| Approver | _name_ |
+
+Append this row to `docs/deployment/DEPLOY-LOG.md` after each deploy.
+
+---
+
+## Future automation (Batch 8)
+
+This manual checklist will be reduced once `.github/workflows/release.yml` automates: artifact build, test gate, deployment-zip creation, and tag-pinned publish. Items in §1 (env), §6 (security gates), and §7 (post-deploy smoke) will remain manual because they touch live secrets and live traffic.

package/docs/docs-site/plan.md

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