umpordez 1.1.0 → 1.3.1

package/.claude/settings.local.json

@@ -46,7 +46,9 @@
       "Bash(md5 /tmp/umptest/everything/mobile/testapp/assets/icon.png /Users/ligeiro/dev/tranqs/app/mobile/tranqs/assets/icon.png)",
       "Bash(git merge *)",
       "Bash(git tag *)",
-      "Bash(npm pack *)"
+      "Bash(npm pack *)",
+      "Read(//Users/ligeiro/dev/dropa/**)",
+      "Read(//Users/ligeiro/dev/growerheleper-v2/app/**)"
     ]
   }
 }

package/README.md

@@ -98,11 +98,19 @@ It asks **what to generate** first:
 |---|---|
 | everything          | server + admin UI + site + mobile |
 | web-only            | server + admin UI + site (no mobile) |
+| mobile-and-site     | mobile app + app-store landing page (no server, no admin) |
 | mobile-and-server   | server + mobile (no UI) |
 | just-mobile         | mobile only (assumes external API) |
 
+The **public site** ships two landing flavors and the CLI picks by
+preset: a **SaaS landing** (CTAs → admin signup) for server/admin
+presets, and an **app-store landing** (App Store / Play buttons,
+pricing, download) for `mobile-and-site`, branded from your primary
+color.
+
 Then a few questions (name, domain, ports, primary color, mobile
-bundle ID if applicable). After scaffold:
+bundle ID + **splash style** — instant show-up or animated — if
+applicable). After scaffold:
 
 ```bash
 cd my-project
@@ -198,6 +206,39 @@ umpordez --version                check version
 | Uploads    | AWS S3 with signed URLs |
 | Email      | Nodemailer + HTML templates |
 
+## What changed in 1.2
+
+- **Non-Negotiables** section in AGENTS.md — codifies rules per layer
+  (server, admin UI, site, mobile) so teams don't have to rediscover
+  them.
+- **Key Patterns (TL;DR)** — quick reference for adding entities,
+  context DI, route handlers, and transactions.
+- **i18n Coverage** table — shows which layers speak which
+  languages at a glance.
+- **Anonymous-first mobile** — synthetic device-account on first
+  boot, never gate behind sign-in.
+- **fetch-api** now supports PUT and PATCH methods plus safer
+  URL parameter filtering (skips null/undefined values).
+
+## What's new in 1.3
+
+Ship a mobile app + its marketing site in one shot:
+
+- **`mobile-and-site` preset** — mobile app + app-store landing page,
+  no server or admin. The "indie mobile app" shape.
+- **App-store landing** — App Store / Play buttons, phone mockup,
+  pricing, download CTAs; branded from your primary color. The CLI
+  picks SaaS vs app landing by preset (and `umpordez update` keeps
+  the right flavor).
+- **Splash choice** — instant show-up (default; native splash hides on
+  font load) or the animated splash, chosen at scaffold time.
+- **Store launch kit** (every mobile preset) — `CHANGELOG.md` +
+  `docs/store-listing.md`, `store-copy.md`, `releases.md`,
+  `screenshots.md`.
+- **Screenshot + release automation** — `frame-shots.mjs`,
+  `gen-mockups.mjs`, `screenshots-capture.sh` + Maestro flow,
+  `appstore-resize.sh`, and `misc/build-local.sh`.
+
 ## What changed in 1.1
 
 The big one. v1.0.x was server + web only. v1.1 adds:

package/cli.mjs

@@ -41,13 +41,15 @@ function showHelp() {
     console.log(`  umpordez --version               ${dim('Show version')}`);
     console.log('');
     console.log(green.bold('What you get:'));
+    console.log(`  ${green('>')} Presets: everything / web-only / mobile+site / mobile+server / just-mobile`);
     console.log(`  ${green('>')} Multi-tenant auth (cookie-based JWT)`);
     console.log(`  ${green('>')} Admin API + Site API (Express)`);
     console.log(`  ${green('>')} React admin panel (Vite + shadcn/ui)`);
     console.log(`  ${green('>')} PostgreSQL + Knex.js migrations`);
     console.log(`  ${green('>')} S3 file uploads with signed URLs`);
-    console.log(`  ${green('>')} EJS-based public site`);
-    console.log(`  ${green('>')} Console task runner`);
+    console.log(`  ${green('>')} Public site — SaaS or app-store landing (EJS + i18n + SEO)`);
+    console.log(`  ${green('>')} Mobile app (Expo + TS) — instant or animated splash`);
+    console.log(`  ${green('>')} Store launch kit (listing, copy, changelog, screenshots)`);
     console.log(`  ${green('>')} Role-based access (admin/owner/manager/user)`);
     console.log(`  ${green('>')} Production build system with versioning`);
     console.log('');

package/create.mjs

@@ -4,7 +4,11 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { execSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { buildReplacements } from './template-variables.mjs';
+import {
+    buildReplacements,
+    APP_LANDING_SWAPS,
+    SITE_VARIANT_DIR
+} from './template-variables.mjs';
 import { generateIcons } from './icons.mjs';
 import { writeInitialManifest } from './update.mjs';
 
@@ -45,6 +49,17 @@ const PRESETS = {
         wantsAdminUi: true,
         wantsSite: true,
     },
+    'mobile-and-site': {
+        label: 'Mobile app + landing page (no server, no admin)',
+        includes: ['mobile', 'ui/site', 'scripts', 'doc'],
+        wantsMobile: true,
+        wantsServer: false,
+        wantsAdminUi: false,
+        wantsSite: true,
+        // Swaps the SaaS landing for the app-marketing landing
+        // (App Store / Play buttons, pricing, download CTA).
+        appLanding: true,
+    },
     'mobile-and-server': {
         label: 'Mobile + server only (no admin UI, no site)',
         includes: ['server', 'mobile', 'misc', 'scripts', 'doc'],
@@ -70,6 +85,8 @@ const ROOT_FILES_BY_PRESET = {
     'web-only':           ['CLAUDE.md', 'AGENTS.md', 'README.md',
                            'architecture.md', 'code.md',
                            'install.sh', 'seed.sh', 'dev.sh'],
+    'mobile-and-site':    ['CLAUDE.md', 'AGENTS.md', 'README.md',
+                           'code.md', 'install.sh', 'dev.sh'],
     'mobile-and-server':  ['CLAUDE.md', 'AGENTS.md', 'README.md',
                            'architecture.md', 'code.md',
                            'install.sh', 'seed.sh', 'dev.sh'],
@@ -266,6 +283,16 @@ async function promptProjectDetails() {
                 ? true
                 : 'Lowercase alphanumeric, dashes allowed',
         },
+        {
+            type: 'list',
+            name: 'splashStyle',
+            message: 'Splash screen:',
+            choices: [
+                { name: 'Instant show-up (recommended)', value: 'instant' },
+                { name: 'Animated (glow + logo + pulse)', value: 'animated' },
+            ],
+            default: 'instant',
+        },
     ];
 
     const answers = await inquirer.prompt([
@@ -296,6 +323,7 @@ async function promptProjectDetails() {
         androidPackage: answers.androidPackage
             ?? toReverseDomain(answers.domain),
         mobileScheme:   answers.mobileScheme ?? answers.slug,
+        splashStyle:    answers.splashStyle  ?? 'instant',
         ...answers,
     };
 }
@@ -331,17 +359,28 @@ function showSummary(details) {
     }
     console.log(`  ${chalk.bold('Color:')}        ${chalk.hex(details.primaryColor)('██')} ${details.primaryColor}`);
     console.log(`  ${chalk.bold('Theme:')}        ${details.defaultTheme}`);
+    if (presetDef.wantsSite) {
+        console.log(`  ${chalk.bold('Landing:')}      ${cyan(
+            presetDef.appLanding ? 'app store (download)' : 'SaaS (signup)'
+        )}`);
+    }
     if (presetDef.wantsMobile) {
         console.log(`  ${chalk.bold('iOS:')}          ${details.iosBundleId}`);
         console.log(`  ${chalk.bold('Android:')}      ${details.androidPackage}`);
         console.log(`  ${chalk.bold('Scheme:')}       ${details.mobileScheme}://`);
+        console.log(`  ${chalk.bold('Splash:')}       ${details.splashStyle === 'animated'
+            ? 'animated (glow + logo)'
+            : 'instant show-up'}`);
     }
     console.log('');
     console.log(dim('  Generates:'));
     if (presetDef.wantsServer)  console.log(dim(`  ${green('>')} Admin API + Site API (Express + TS)`));
     if (presetDef.wantsAdminUi) console.log(dim(`  ${green('>')} React admin panel (Vite + shadcn/ui)`));
-    if (presetDef.wantsSite)    console.log(dim(`  ${green('>')} Public site (EJS + Tailwind)`));
+    if (presetDef.wantsSite)    console.log(dim(`  ${green('>')} ${presetDef.appLanding
+        ? 'App landing page (store buttons + pricing)'
+        : 'Public site (EJS + Tailwind)'}`));
     if (presetDef.wantsMobile)  console.log(dim(`  ${green('>')} Mobile app (Expo + TS + auth + theme)`));
+    if (presetDef.wantsMobile)  console.log(dim(`  ${green('>')} Store launch kit (listing, copy, changelog, screenshots)`));
     if (presetDef.wantsServer)  console.log(dim(`  ${green('>')} PostgreSQL migrations + seed`));
     console.log('');
 }
@@ -383,7 +422,7 @@ function replacePlaceholders(content, replacements) {
 // config, git ignore) doesn't belong to any single sub-app.
 const ALWAYS_KEEP = new Set(['.claude']);
 
-async function copyTemplate(outputDir, preset) {
+export async function copyTemplate(outputDir, preset) {
     const presetDef = PRESETS[preset];
     await fs.promises.cp(TEMPLATE_DIR, outputDir, { recursive: true });
 
@@ -442,6 +481,25 @@ async function copyTemplate(outputDir, preset) {
             await fs.promises.rm(path.join(outputDir, entry.name));
         }
     }
+
+    // Landing-page variant swap. App-focused presets replace the SaaS
+    // landing with the app-marketing one before placeholder replacement
+    // runs (so the swapped files get their placeholders filled too). The
+    // _variants staging dir is always removed — it never ships.
+    if (presetDef.appLanding) {
+        for (const [variant, canonical] of APP_LANDING_SWAPS) {
+            const from = path.join(outputDir, variant);
+            const to = path.join(outputDir, canonical);
+            if (fs.existsSync(from)) {
+                await fs.promises.rm(to, { force: true });
+                await fs.promises.rename(from, to);
+            }
+        }
+    }
+    await fs.promises.rm(
+        path.join(outputDir, SITE_VARIANT_DIR),
+        { recursive: true, force: true }
+    );
 }
 
 export async function createProject() {
@@ -565,9 +623,14 @@ export async function createProject() {
             'scripts/run-ios.sh',
             'scripts/release-android.sh',
             'scripts/generate-icons.sh',
-            'scripts/install-native.sh'
+            'scripts/install-native.sh',
+            'scripts/appstore-resize.sh',
+            'scripts/screenshots-capture.sh'
         );
     }
+    if (details.presetDef.wantsServer) {
+        scripts.push('misc/build-local.sh');
+    }
 
     for (const script of scripts) {
         const scriptPath = path.join(outputDir, script);
@@ -638,8 +701,10 @@ function showNextSteps(details) {
         console.log(`  ${green('3.')} ./seed.sh`);
         console.log(`  ${green('4.')} ./dev.sh`);
     } else {
-        console.log(`  ${green('2.')} cd mobile/${details.slug} && npm install`);
-        console.log(`  ${green('3.')} npm run start`);
+        // No DB to seed, but install.sh + dev.sh still orchestrate the
+        // site + mobile (they guard on directory existence).
+        console.log(`  ${green('2.')} ./install.sh`);
+        console.log(`  ${green('3.')} ./dev.sh`);
     }
     console.log('');
     if (presetDef.wantsAdminUi) {
@@ -653,6 +718,7 @@ function showNextSteps(details) {
     }
     if (presetDef.wantsMobile) {
         console.log(dim(`  Mobile:       cd mobile/${details.slug} && npm run ios | android | web`));
+        console.log(dim(`  Store kit:    mobile/${details.slug}/docs/ (listing, copy, screenshots) + CHANGELOG.md`));
     }
     console.log('');
     console.log(dim('  Happy hacking! - ') + cyan('youtube.com/ligeiro'));

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "umpordez",
     "type": "module",
-    "version": "1.1.0",
+    "version": "1.3.1",
     "description": "SaaS starter kit generator — server, admin SPA, public site (i18n), mobile app (offline-first, IAP, native push)",
     "main": "cli.mjs",
     "scripts": {

package/template/AGENTS.md

@@ -276,7 +276,86 @@ const ok = await confirm({
 if (!ok) return;
 ```
 
-## Multi-Tenancy
+## Non-Negotiables
+
+### Code Style
+- 4-space indent, semicolons, max 80 cols, LF, always braces
+- TypeScript strict (no `any`, use `unknown`)
+- Code in English; user-facing strings in Portuguese (pt-BR)
+- Path aliases: `#core/*`, `#shared/*`, `#api/*` (server), `@/*` (admin UI / mobile)
+- No relative paths beyond single `../`
+
+### Server
+- Routes go through models (never `req.context.knex()` in routes)
+- `buildHandler()` wraps every async handler; Zod validates input
+- Raw SQL in migrations (`knex.schema.raw()`)
+- Models extend `BaseModel` — get `this.knex`, `this.context`, `this.db`
+- Errors: `ValidationError` (400), `NotFoundError` (404), `ConflictError` (409), `ForbiddenError` (403)
+- Pagination: `{ rows, total, page, limit, totalPages }`
+- Every table: `id UUID`, `utc_created_on`, `utc_updated_on`; multi-tenant tables also `account_id`
+
+### Admin UI
+- `fetchApi()` for every API call (handles cookies, JSON, FormData)
+- React Query for all server state; `keepPreviousData` on paginated queries
+- Query keys centralized in `lib/query-keys.ts`
+- shadcn/ui primitives under `components/ui/` (compose, don't fork)
+- `useConfirm()` instead of `window.confirm()`, `toast` from sonner
+
+### Site
+- Every string through `t()` — no bare text in templates
+- URL strategy: `/` → pt-BR, `/en/...` → English (middleware strips prefix)
+- Hreflang alternates + canonical + sitemap.xml on every page
+
+### Mobile
+- **Free-first**: never gate behind sign-in; anonymous usage is the default
+- **Anonymous-first**: synthetic UUID device-account on first boot, never gate behind login
+- **Services own data access** — pages never call `getDb()` directly
+- **User-scoped writes check `demandSigned()`** — reads always work, writes no-op when gate closed
+- Every string through `t()` — no bare text in JSX
+- NitroModules crash in Expo Go — lazy-load with `try/require`
+- Never `expo prebuild --clean` (wipes native code; use `scripts/prebuild.sh`)
+
+### i18n Coverage
+| Layer | pt-BR | en | Additional |
+|-------|-------|----|------------|
+| Server | ✓ | ✓ | Extensible via i18next |
+| Admin UI | ✓ | ✗ | pt-BR only (Brazil market) |
+| Site | ✓ | ✓ | URL-prefixed (/ vs /en/) |
+| Mobile | ✓ | ✓ | Extensible per project |
+
+## Key Patterns (TL;DR)
+
+### Adding a domain entity
+1. `migrations/YYYYMMDDHHMMSS_create-thing.ts` — raw SQL
+2. `core/models/thing.ts` — extends `BaseModel`
+3. Register on `Context` in `core/context.ts`
+4. `apps/api/routes/thing.ts` — `buildHandler()` + Zod
+5. Admin UI: page + `hooks/queries/use-thing.ts`
+6. Mobile (optional): `src/services/thing/`
+
+### Context DI
+```typescript
+const users = await req.context.user.list({ page: 1 });
+this.user = new UserModel(this);  // in context.ts
+```
+
+### Route handler
+```typescript
+router.post('/things', buildHandler(async (req, res) => {
+    const data = z.object({ name: z.string().min(1) }).parse(req.body);
+    const result = await req.context.thing.create(req.accountId!, data);
+    res.json({ ok: true, result });
+}));
+```
+
+### Transaction
+```typescript
+await req.context.knexTransaction(async () => {
+    const user = await req.context.user.create(data);
+    await req.context.account.addMember(accountId, { ... });
+});
+```
+
 
 ```
 users (global identity) → user_in_accounts (many-to-many + role) → accounts (tenant) → [domain entities]

package/template/CLAUDE.md

@@ -58,7 +58,7 @@ URLs:
 Folders that the preset didn't ship are simply absent. `dev.sh`
 and `install.sh` guard on existence per directory, so the same
 script works for every preset (everything / web-only /
-mobile-and-server / just-mobile).
+mobile-and-site / mobile-and-server / just-mobile).
 
 ## Multi-tenancy model
 

package/template/misc/build-local.sh

@@ -0,0 +1,82 @@
+#!/bin/bash
+#
+# build-local — produce a production build of every web sub-project this
+# repo ships (server, admin SPA, public site) into a sibling `builds/`
+# directory, bump a build number and (optionally) commit + push it.
+#
+# Layout produced (matches CLAUDE.md → Deployment):
+#   ../builds/server/         server `npm run build` output + deps
+#   ../builds/ui/admin/dist/  Vite build (nginx serves this)
+#   ../builds/ui/site/        compiled site + views + public
+#
+# Usage (from the project root):
+#   ./misc/build-local.sh            # build into ../builds
+#   ./misc/build-local.sh --push     # also git commit + tag + push builds
+#
+# Each block is guarded on directory existence, so the same script works
+# whatever preset generated this project.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT"
+
+BUILD_DIR="${BUILD_DIR:-../builds}"
+PUSH=0
+for arg in "$@"; do
+    case "$arg" in
+        --push) PUSH=1 ;;
+    esac
+done
+
+mkdir -p "$BUILD_DIR"
+
+# ── Build number ────────────────────────────────────────────────────
+NUM_FILE="$BUILD_DIR/build-number"
+number=$(cat "$NUM_FILE" 2>/dev/null || echo 0)
+next=$((number + 1))
+
+# ── Server ──────────────────────────────────────────────────────────
+if [ -d server ]; then
+    echo "==> Building server…"
+    (cd server && npm run build)
+    mkdir -p "$BUILD_DIR/server"
+    rsync -a --delete \
+        --exclude node_modules --exclude .env \
+        server/dist/ "$BUILD_DIR/server/dist/" 2>/dev/null || true
+    cp server/package.json server/package-lock.json "$BUILD_DIR/server/" 2>/dev/null || true
+fi
+
+# ── Admin SPA ───────────────────────────────────────────────────────
+if [ -d ui/admin ]; then
+    echo "==> Building admin SPA…"
+    (cd ui/admin && npm run build)
+    mkdir -p "$BUILD_DIR/ui/admin"
+    rsync -a --delete ui/admin/dist/ "$BUILD_DIR/ui/admin/dist/"
+fi
+
+# ── Public site ─────────────────────────────────────────────────────
+if [ -d ui/site ]; then
+    echo "==> Building public site…"
+    (cd ui/site && npm run build)
+    mkdir -p "$BUILD_DIR/ui/site"
+    rsync -a --delete \
+        --exclude node_modules --exclude .env \
+        ui/site/build/ "$BUILD_DIR/ui/site/build/" 2>/dev/null || true
+    cp ui/site/package.json "$BUILD_DIR/ui/site/" 2>/dev/null || true
+    cp -R ui/site/views "$BUILD_DIR/ui/site/" 2>/dev/null || true
+    cp -R ui/site/public "$BUILD_DIR/ui/site/" 2>/dev/null || true
+fi
+
+echo "$next" > "$NUM_FILE"
+echo ""
+echo "Build #$next written to $BUILD_DIR"
+
+# ── Optional: commit + push the builds repo ─────────────────────────
+if [ "$PUSH" = "1" ] && [ -d "$BUILD_DIR/.git" ]; then
+    echo "==> Committing + pushing builds…"
+    (cd "$BUILD_DIR" \
+        && git add . \
+        && git commit -m "build: #$next" \
+        && git tag -a "$next" -m "#$next" \
+        && git push && git push origin --tags)
+fi

package/template/mobile/{{PROJECT_SLUG}}/App.tsx

@@ -1,6 +1,7 @@
 import { useEffect, useState } from 'react';
 import { AppState } from 'react-native';
 import { SafeAreaProvider } from 'react-native-safe-area-context';
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
 import Toast from 'react-native-toast-message';
 import * as SplashScreen from 'expo-splash-screen';
 
@@ -14,13 +15,16 @@ import AnimatedSplash from './src/components/AnimatedSplash';
 import { toastConfig } from './src/components/ToastConfig';
 import { initDb } from './src/services/db';
 import { syncAllContent } from './src/services/content';
+import { SPLASH_ANIMATED } from './src/config';
 
 // Hide the native splash screen so our AnimatedSplash takes over the
 // transition. Best-effort — if the call fails (rare), we just continue.
 SplashScreen.preventAutoHideAsync().catch(() => { /* best-effort */ });
 
 export default function App() {
-    const [splashDone, setSplashDone] = useState<boolean>(false);
+    // Instant show-up (SPLASH_ANIMATED = false) starts already "done" so
+    // no overlay ever mounts — the app appears the moment fonts load.
+    const [splashDone, setSplashDone] = useState<boolean>(!SPLASH_ANIMATED);
 
     useEffect(() => {
         // Init runs in the background. App rendering doesn't wait on
@@ -28,6 +32,13 @@ export default function App() {
         // `splashDone` flips, and screens read from SQLite which
         // serves cached data while the network sync runs.
         SplashScreen.hideAsync().catch(() => { /* best-effort */ });
+
+        // Force-hide the splash after 5s no matter what, so a stuck
+        // animation never keeps the user out of the app. In Release
+        // there's no red box — without this timeout a render-time
+        // crash is invisible.
+        const fallback = setTimeout(() => setSplashDone(true), 5000);
+
         (async () => {
             try {
                 await initDb();
@@ -55,21 +66,26 @@ export default function App() {
                 });
             }
         });
-        return () => sub.remove();
+        return () => {
+            sub.remove();
+            clearTimeout(fallback);
+        };
     }, []);
 
     return (
-        <SafeAreaProvider>
-            <ThemeProvider>
-                <AuthProvider>
-                    <Routes />
-                    <Toast config={toastConfig} />
-                </AuthProvider>
-            </ThemeProvider>
+        <GestureHandlerRootView style={{ flex: 1 }}>
+            <SafeAreaProvider>
+                <ThemeProvider>
+                    <AuthProvider>
+                        <Routes />
+                        <Toast config={toastConfig} />
+                    </AuthProvider>
+                </ThemeProvider>
 
-            {!splashDone && (
-                <AnimatedSplash onDone={() => setSplashDone(true)} />
-            )}
-        </SafeAreaProvider>
+                {SPLASH_ANIMATED && !splashDone && (
+                    <AnimatedSplash onDone={() => setSplashDone(true)} />
+                )}
+            </SafeAreaProvider>
+        </GestureHandlerRootView>
     );
 }

package/template/mobile/{{PROJECT_SLUG}}/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to **{{PROJECT_NAME}}** (the mobile app). This is the
+source of truth for what shipped; store "What's New" copy is derived from
+it in [`docs/releases.md`](./docs/releases.md).
+
+Format loosely follows [Keep a Changelog](https://keepachangelog.com);
+versions match `app.json` (`version` / `ios.buildNumber` /
+`android.versionCode`).
+
+## [Unreleased]
+
+### Added
+- First public build.
+
+### Changed
+-
+
+### Fixed
+-
+
+<!--
+When you cut a release:
+  1. `../../scripts/bump-version.sh patch|minor|major`
+  2. Move the items above under a new `## [x.y.z] - YYYY-MM-DD` heading.
+  3. Reset [Unreleased] to empty Added/Changed/Fixed.
+  4. Translate the highlights into store copy in docs/releases.md.
+-->

package/template/mobile/{{PROJECT_SLUG}}/CLAUDE.md

@@ -6,7 +6,7 @@ auth, 5-tab navigator, offline SQLite, custom-native modules.
 ```
 src/
 ├── App.tsx, index.ts
-├── config.ts                  API base URL + provider client IDs
+├── config.ts                  API base URL + client IDs + SPLASH_ANIMATED
 ├── theme/colors.ts            Palette generated from primary color
 ├── i18n/                      pt-BR default + en (react-i18next)
 ├── contexts/
@@ -63,10 +63,17 @@ hasCompletedOnboarding
   render an "auth required" screen at the entry point. Wrap
   premium features in `<PremiumGate onUpgrade={openAuth} />`.
 
-- **Routes go through models** — same rule as server. Mobile
+- **Anonymous-first.** `AuthContext` fabricates a synthetic device-
+  account on first boot (`services/auth/anonymous.ts` returns a
+  UUID v4 stored in AsyncStorage). `signed: true` always;
+  `isAnonymous: true` for the default state. Never gate app entry
+  behind sign-in. The opt-in AuthStack lives in Profile's footer
+  link only.
+
+- **Services own data access** — same rule as server. Mobile
   doesn't have models; the equivalent is: **services own data
-  access**. Pages call `getContentByType('post')`, not
-  `getDb().getAllAsync(...)`. New SQLite reads/writes go in the
+  access**. Pages call `services/crops`, `services/events`, … —
+  never `getDb()` directly. New SQLite reads/writes go in the
   matching `services/<thing>/` folder.
 
 - **User-scoped writes check `demandSigned()`** at the top of the
@@ -88,6 +95,15 @@ hasCompletedOnboarding
   Use `./scripts/prebuild.sh` (refuses --clean). To genuinely
   reset, move customizations into `plugins/` first.
 
+## Splash
+
+`config.ts` exports `SPLASH_ANIMATED` (set at scaffold time). When
+`false` (instant show-up, the default) the native splash hides the
+moment fonts load and the app appears immediately — `AnimatedSplash`
+never mounts. When `true`, `App.tsx` overlays `AnimatedSplash`
+(glow + logo + pulse ring, ~2s) until it finishes. The component ships
+either way; flip the flag to switch behavior.
+
 ## Adding a screen
 
 1. **Page** — `src/pages/<scope>/<Name>.tsx`. Typed via
@@ -150,7 +166,7 @@ Client → /api/auth/google/app
 ```
 
 `signOut()` clears auth + onboarding state so the next user starts
-from Welcome (matches tranqs's pattern; onboarding is per-account).
+from Welcome (onboarding is per-account).
 
 ## Premium
 

package/template/mobile/{{PROJECT_SLUG}}/app.json

@@ -48,6 +48,9 @@
                 {
                     "android": {
                         "minSdkVersion": 26
+                    },
+                    "ios": {
+                        "deploymentTarget": "17.0"
                     }
                 }
             ],