umpordez 1.3.2 → 1.5.0

package/.claude/settings.local.json

@@ -49,7 +49,15 @@
       "Bash(npm pack *)",
       "Read(//Users/ligeiro/dev/dropa/**)",
       "Read(//Users/ligeiro/dev/growerheleper-v2/app/**)",
-      "Bash(git mv *)"
+      "Bash(git mv *)",
+      "Bash(npm view *)",
+      "Bash(tar -xzf expo-57.0.4.tgz package/bundledNativeModules.json package/package.json)",
+      "Bash(npx expo-doctor *)",
+      "Bash(pkill -f \"expo start --port 8090\")",
+      "Bash(git *)",
+      "Bash(npm init *)",
+      "Bash(awk 'NR>=383 && NR<=386 {print NR\": \"substr\\($0,1,120\\)}' '/Users/ligeiro/dev/umpordez-cli/template/mobile/{{PROJECT_SLUG}}/src/pages/auth/AuthLanding.tsx')",
+      "Bash(awk 'NR>=394 && NR<=410 {print NR\": \"substr\\($0,1,100\\)}' '/Users/ligeiro/dev/umpordez-cli/template/mobile/{{PROJECT_SLUG}}/src/pages/auth/AuthLanding.tsx')"
     ]
   }
 }

package/cli.mjs

@@ -41,7 +41,7 @@ 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('>')} Pick components one-by-one: server API / admin webapp / site / 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)`);

package/create.mjs

@@ -7,7 +7,10 @@ import { fileURLToPath } from 'node:url';
 import {
     buildReplacements,
     APP_LANDING_SWAPS,
-    SITE_VARIANT_DIR
+    SITE_VARIANT_DIR,
+    includesForComponents,
+    rootFilesForComponents,
+    presetNameForComponents
 } from './template-variables.mjs';
 import { generateIcons } from './icons.mjs';
 import { writeInitialManifest } from './update.mjs';
@@ -28,71 +31,12 @@ const BINARY_EXTENSIONS = new Set([
     '.pdf', '.mp3', '.mp4', '.webm', '.ogg',
 ]);
 
-// Presets describe which top-level template directories ship in a new
-// project. The CLI scrubs the rest after copying — keeps the template
-// structure unconditional and the create-time logic dead simple.
-const PRESETS = {
-    everything: {
-        label: 'Everything (server + admin UI + site + mobile)',
-        includes: ['server', 'ui/admin', 'ui/site', 'mobile', 'misc',
-                   'scripts', 'doc'],
-        wantsMobile: true,
-        wantsServer: true,
-        wantsAdminUi: true,
-        wantsSite: true,
-    },
-    'web-only': {
-        label: 'Web only (server + admin UI + site, no mobile)',
-        includes: ['server', 'ui/admin', 'ui/site', 'misc', 'doc'],
-        wantsMobile: false,
-        wantsServer: true,
-        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'],
-        wantsMobile: true,
-        wantsServer: true,
-        wantsAdminUi: false,
-        wantsSite: false,
-    },
-    'just-mobile': {
-        label: 'Just mobile (assumes external API)',
-        includes: ['mobile', 'scripts', 'doc'],
-        wantsMobile: true,
-        wantsServer: false,
-        wantsAdminUi: false,
-        wantsSite: false,
-    },
-};
-
-const ROOT_FILES_BY_PRESET = {
-    everything:           ['CLAUDE.md', 'AGENTS.md', 'README.md',
-                           'architecture.md', 'code.md',
-                           'install.sh', 'seed.sh', 'dev.sh'],
-    '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'],
-    'just-mobile':        ['CLAUDE.md', 'README.md', 'code.md',
-                           'install.sh', 'dev.sh'],
-};
+// A project is any combination of four components picked one-by-one
+// at create time (see template-variables.mjs for the component →
+// template-paths mapping shared with `umpordez update`). The CLI
+// copies the whole template then scrubs what wasn't picked — keeps
+// the template structure unconditional and the create-time logic
+// dead simple.
 
 function slugify(text) {
     return text
@@ -113,23 +57,135 @@ function toReverseDomain(domain) {
     return parts.reverse().join('.');
 }
 
+// Ask for each component one-by-one instead of a fixed preset list.
+// The questions adapt to earlier answers:
+//   - the server API pitch changes when a mobile app was picked (a
+//     mobile-only backend for auth / IAP validation / file serving
+//     is a first-class use case, not "everything minus stuff")
+//   - the admin webapp is only offered when there's an API for it
+//   - the landing-page flavor is only asked when it's genuinely
+//     ambiguous (site + mobile + admin webapp)
+async function promptComponents() {
+    const { mobile } = await inquirer.prompt([{
+        type: 'confirm',
+        name: 'mobile',
+        message: 'Mobile app? (Expo + React Native + offline SQLite '
+            + '+ IAP)',
+        default: true,
+    }]);
+
+    const { server } = await inquirer.prompt([{
+        type: 'confirm',
+        name: 'server',
+        message: mobile
+            ? 'Server API? (Express + PostgreSQL — powers auth, '
+                + 'IAP validation, file serving and backups for the '
+                + 'app)'
+            : 'Server API? (Express + PostgreSQL, multi-tenant auth)',
+        default: true,
+    }]);
+
+    let adminUi = false;
+    if (server) {
+        ({ adminUi } = await inquirer.prompt([{
+            type: 'confirm',
+            name: 'adminUi',
+            message: 'Admin webapp? (React SPA + shadcn/ui, '
+                + 'role-based)',
+            default: true,
+        }]));
+    } else {
+        console.log(dim(
+            '    (admin webapp skipped — it needs the server API)'
+        ));
+    }
+
+    const { site } = await inquirer.prompt([{
+        type: 'confirm',
+        name: 'site',
+        message: 'Public site? (EJS + i18n + SEO landing page)',
+        default: true,
+    }]);
+
+    const components = { server, adminUi, site, mobile };
+
+    if (!server && !adminUi && !site && !mobile) {
+        console.log(red('  Pick at least one component.'));
+        console.log('');
+        return promptComponents();
+    }
+
+    // Landing flavor. Only ambiguous when the site coexists with
+    // both an app to advertise and an admin webapp to sign up into.
+    let appLanding = false;
+    if (site && mobile && !adminUi) {
+        appLanding = true;
+        console.log(dim(
+            '    (landing page: app-store flavor — download CTAs, '
+            + 'no signup to point at)'
+        ));
+    } else if (site && mobile && adminUi) {
+        const { landing } = await inquirer.prompt([{
+            type: 'list',
+            name: 'landing',
+            message: 'Landing page flavor:',
+            choices: [
+                { name: 'SaaS (CTAs → admin signup)', value: 'saas' },
+                { name: 'App store (download buttons + pricing)',
+                    value: 'app' },
+            ],
+            default: 'saas',
+        }]);
+        appLanding = landing === 'app';
+    }
+
+    // Sign-in providers for the mobile app. Email+password always
+    // ships; Apple and Google are opt-out. Disabling Apple also
+    // strips the entitlement + config plugin from app.json so local
+    // iOS builds don't require the capability on the provisioning
+    // profile.
+    let authApple = true;
+    let authGoogle = true;
+    let iap = true;
+    if (mobile) {
+        ({ authApple } = await inquirer.prompt([{
+            type: 'confirm',
+            name: 'authApple',
+            message: 'Mobile sign-in with Apple? (email+password '
+                + 'always included)',
+            default: true,
+        }]));
+        ({ authGoogle } = await inquirer.prompt([{
+            type: 'confirm',
+            name: 'authGoogle',
+            message: 'Mobile sign-in with Google? (server-side '
+                + 'OAuth flow)',
+            default: true,
+        }]));
+        // Disabling IAP strips the expo-iap dependency, its config
+        // plugin and the Android BILLING permission — PremiumGate
+        // then renders everything unlocked (a fully free app).
+        ({ iap } = await inquirer.prompt([{
+            type: 'confirm',
+            name: 'iap',
+            message: 'In-app purchases? (premium subscriptions via '
+                + 'expo-iap + server receipt validation)',
+            default: true,
+        }]));
+    }
+
+    return { components, appLanding, authApple, authGoogle, iap };
+}
+
 async function promptProjectDetails() {
     console.log(green.bold('  Project Setup'));
     console.log(chalk.hex('#2c2c2c')('  ' + '─'.repeat(40)));
     console.log('');
 
-    const { preset } = await inquirer.prompt([{
-        type: 'list',
-        name: 'preset',
-        message: 'What do you want to generate?',
-        choices: Object.entries(PRESETS).map(([value, def]) => ({
-            name: def.label,
-            value,
-        })),
-        default: 'everything',
-    }]);
-
-    const presetDef = PRESETS[preset];
+    const {
+        components, appLanding, authApple, authGoogle, iap
+    } = await promptComponents();
+    const preset = presetNameForComponents(components);
 
     const { name } = await inquirer.prompt([{
         type: 'input',
@@ -165,7 +221,7 @@ async function promptProjectDetails() {
         },
     ];
 
-    const serverQuestions = !presetDef.wantsServer ? [] : [
+    const serverQuestions = !components.server ? [] : [
         {
             type: 'input',
             name: 'dbName',
@@ -204,7 +260,7 @@ async function promptProjectDetails() {
         },
     ];
 
-    const webUiQuestions = !presetDef.wantsAdminUi ? [] : [
+    const webUiQuestions = !components.adminUi ? [] : [
         {
             type: 'input',
             name: 'adminUiPort',
@@ -214,7 +270,7 @@ async function promptProjectDetails() {
         },
     ];
 
-    const siteQuestions = !presetDef.wantsSite ? [] : [
+    const siteQuestions = !components.site ? [] : [
         {
             type: 'input',
             name: 'sitePort',
@@ -254,7 +310,7 @@ async function promptProjectDetails() {
         },
     ];
 
-    const mobileQuestions = !presetDef.wantsMobile ? [] : [
+    const mobileQuestions = !components.mobile ? [] : [
         {
             type: 'input',
             name: 'iosBundleId',
@@ -306,7 +362,11 @@ async function promptProjectDetails() {
 
     return {
         preset,
-        presetDef,
+        components,
+        appLanding,
+        authApple,
+        authGoogle,
+        iap,
         name: name.trim(),
         // Defaults for the parts the user didn't see — they're still
         // referenced by replacements (some unconditionally), so we fill
@@ -334,54 +394,70 @@ function validatePort(v) {
         : 'Must be a valid port number';
 }
 
+function componentsLabel(c) {
+    const parts = [];
+    if (c.server)  parts.push('server API');
+    if (c.adminUi) parts.push('admin webapp');
+    if (c.site)    parts.push('site');
+    if (c.mobile)  parts.push('mobile');
+    return parts.join(' + ');
+}
+
 function showSummary(details) {
-    const { presetDef } = details;
+    const c = details.components;
     console.log('');
     console.log(green.bold('  Project Summary'));
     console.log(chalk.hex('#2c2c2c')('  ' + '─'.repeat(40)));
     console.log('');
-    console.log(`  ${chalk.bold('Preset:')}       ${cyan(presetDef.label)}`);
+    console.log(`  ${chalk.bold('Components:')}   ${cyan(componentsLabel(c))}`);
     console.log(`  ${chalk.bold('Name:')}         ${cyan(details.name)}`);
     console.log(`  ${chalk.bold('Slug:')}         ${details.slug}`);
     console.log(`  ${chalk.bold('Description:')}  ${details.description || dim('(none)')}`);
     console.log(`  ${chalk.bold('Domain:')}       ${cyan(details.domain)}`);
-    if (presetDef.wantsServer) {
+    if (c.server) {
         console.log(`  ${chalk.bold('Database:')}     ${details.dbName}`);
         console.log(`  ${chalk.bold('Admin:')}        ${details.adminEmail}`);
     }
     console.log(`  ${chalk.bold('Output:')}       ${details.outputDir}`);
     const ports = [];
-    if (presetDef.wantsServer)  ports.push(`API ${cyan(details.apiPort)} | Site API ${cyan(details.siteApiPort)}`);
-    if (presetDef.wantsAdminUi) ports.push(`Admin ${cyan(details.adminUiPort)}`);
-    if (presetDef.wantsSite)    ports.push(`Site ${cyan(details.sitePort)}`);
+    if (c.server)  ports.push(`API ${cyan(details.apiPort)} | Site API ${cyan(details.siteApiPort)}`);
+    if (c.adminUi) ports.push(`Admin ${cyan(details.adminUiPort)}`);
+    if (c.site)    ports.push(`Site ${cyan(details.sitePort)}`);
     if (ports.length) {
         console.log(`  ${chalk.bold('Ports:')}        ${ports.join(' | ')}`);
     }
     console.log(`  ${chalk.bold('Color:')}        ${chalk.hex(details.primaryColor)('██')} ${details.primaryColor}`);
     console.log(`  ${chalk.bold('Theme:')}        ${details.defaultTheme}`);
-    if (presetDef.wantsSite) {
+    if (c.site) {
         console.log(`  ${chalk.bold('Landing:')}      ${cyan(
-            presetDef.appLanding ? 'app store (download)' : 'SaaS (signup)'
+            details.appLanding ? 'app store (download)' : 'SaaS (signup)'
         )}`);
     }
-    if (presetDef.wantsMobile) {
+    if (c.mobile) {
         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'}`);
+        const providers = ['email+password'];
+        if (details.authApple)  providers.push('Apple');
+        if (details.authGoogle) providers.push('Google');
+        console.log(`  ${chalk.bold('Sign-in:')}      ${providers.join(' | ')}`);
+        console.log(`  ${chalk.bold('IAP:')}          ${details.iap
+            ? 'premium subscriptions (expo-iap)'
+            : 'none (all features unlocked)'}`);
     }
     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('>')} ${presetDef.appLanding
+    if (c.server)  console.log(dim(`  ${green('>')} Admin API + Site API (Express + TS)`));
+    if (c.adminUi) console.log(dim(`  ${green('>')} React admin panel (Vite + shadcn/ui)`));
+    if (c.site)    console.log(dim(`  ${green('>')} ${details.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`));
+    if (c.mobile)  console.log(dim(`  ${green('>')} Mobile app (Expo + TS + auth + theme)`));
+    if (c.mobile)  console.log(dim(`  ${green('>')} Store launch kit (listing, copy, changelog, screenshots)`));
+    if (c.server)  console.log(dim(`  ${green('>')} PostgreSQL migrations + seed`));
     console.log('');
 }
 
@@ -428,12 +504,12 @@ const ALWAYS_KEEP = new Set(['.claude']);
 // renamed back to `.gitignore` during the file-rename pass below.
 const ALWAYS_KEEP_FILES = new Set(['gitignore', '.editorconfig']);
 
-export async function copyTemplate(outputDir, preset) {
-    const presetDef = PRESETS[preset];
+export async function copyTemplate(outputDir, components, appLanding) {
+    const includes = includesForComponents(components);
     await fs.promises.cp(TEMPLATE_DIR, outputDir, { recursive: true });
 
     // Top-level dirs to keep
-    const keep = new Set([...presetDef.includes, ...ALWAYS_KEEP]);
+    const keep = new Set([...includes, ...ALWAYS_KEEP]);
     const entries = await fs.promises.readdir(outputDir, { withFileTypes: true });
 
     for (const entry of entries) {
@@ -442,7 +518,7 @@ export async function copyTemplate(outputDir, preset) {
         }
         // Special-case ui/: keep only the requested children
         if (entry.name === 'ui') {
-            const wantedChildren = presetDef.includes
+            const wantedChildren = includes
                 .filter(p => p.startsWith('ui/'))
                 .map(p => p.slice('ui/'.length));
             if (wantedChildren.length === 0) {
@@ -475,7 +551,7 @@ export async function copyTemplate(outputDir, preset) {
     }
 
     // Top-level files: drop dev.sh / seed.sh etc. when not relevant
-    const allowedFiles = new Set(ROOT_FILES_BY_PRESET[preset] ?? []);
+    const allowedFiles = new Set(rootFilesForComponents(components));
     const rootEntries = await fs.promises.readdir(outputDir, {
         withFileTypes: true
     });
@@ -489,11 +565,11 @@ export async function copyTemplate(outputDir, preset) {
         }
     }
 
-    // Landing-page variant swap. App-focused presets replace the SaaS
+    // Landing-page variant swap. App-focused projects 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) {
+    if (appLanding) {
         for (const [variant, canonical] of APP_LANDING_SWAPS) {
             const from = path.join(outputDir, variant);
             const to = path.join(outputDir, canonical);
@@ -551,9 +627,11 @@ export async function createProject() {
 
     console.log('');
 
-    // [1/5] Copy template (preset-aware pruning)
+    // [1/5] Copy template (component-aware pruning)
     console.log(green('[1/5]') + ' Copying template files...');
-    await copyTemplate(outputDir, details.preset);
+    await copyTemplate(
+        outputDir, details.components, details.appLanding
+    );
 
     // [2/5] Replace placeholders
     const files = await getAllFiles(outputDir);
@@ -604,7 +682,7 @@ export async function createProject() {
     // primary color + first letter of the project name. A failure
     // here is fatal (without these files, expo prebuild + the app
     // splash both break), so we surface the error instead of swallowing.
-    if (details.presetDef.wantsMobile) {
+    if (details.components.mobile) {
         const mobileAssets = path.join(
             outputDir, 'mobile', details.slug, 'assets'
         );
@@ -629,7 +707,7 @@ export async function createProject() {
         'seed.sh',
         'server/knex.sh',
     ];
-    if (details.presetDef.wantsMobile) {
+    if (details.components.mobile) {
         scripts.push(
             'scripts/bump-version.sh',
             'scripts/prebuild.sh',
@@ -641,7 +719,7 @@ export async function createProject() {
             'scripts/screenshots-capture.sh'
         );
     }
-    if (details.presetDef.wantsServer) {
+    if (details.components.server) {
         scripts.push('misc/build-local.sh');
     }
 
@@ -706,10 +784,10 @@ async function renameDirs(root, slug) {
 }
 
 function showNextSteps(details) {
-    const { presetDef } = details;
+    const c = details.components;
     console.log(chalk.bold('  Next steps:'));
     console.log(`  ${green('1.')} cd ${details.outputDir}`);
-    if (presetDef.wantsServer) {
+    if (c.server) {
         console.log(`  ${green('2.')} ./install.sh`);
         console.log(`  ${green('3.')} ./seed.sh`);
         console.log(`  ${green('4.')} ./dev.sh`);
@@ -720,16 +798,16 @@ function showNextSteps(details) {
         console.log(`  ${green('3.')} ./dev.sh`);
     }
     console.log('');
-    if (presetDef.wantsAdminUi) {
+    if (c.adminUi) {
         console.log(dim(`  Admin panel:  ${cyan(`http://localhost:${details.adminUiPort}`)}`));
     }
-    if (presetDef.wantsServer) {
+    if (c.server) {
         console.log(dim(`  Admin API:    ${cyan(`http://localhost:${details.apiPort}`)}`));
     }
-    if (presetDef.wantsSite) {
+    if (c.site) {
         console.log(dim(`  Site:         ${cyan(`http://localhost:${details.sitePort}`)}`));
     }
-    if (presetDef.wantsMobile) {
+    if (c.mobile) {
         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`));
     }

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "umpordez",
     "type": "module",
-    "version": "1.3.2",
+    "version": "1.5.0",
     "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

@@ -312,7 +312,7 @@ if (!ok) return;
 - **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`
+- Native-module crash in Expo Go (e.g. `expo-iap`) — lazy-load with `try/require`
 - Never `expo prebuild --clean` (wipes native code; use `scripts/prebuild.sh`)
 
 ### i18n Coverage

package/template/CLAUDE.md

@@ -55,10 +55,11 @@ URLs:
 └── .claude/settings.json   Permission allowlist for routine commands
 ```
 
-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-site / mobile-and-server / just-mobile).
+Folders the scaffold didn't ship are simply absent. Components
+(server API / admin webapp / public site / mobile app) are picked
+one-by-one at create time; `dev.sh` and `install.sh` guard on
+existence per directory, so the same script works for every
+combination.
 
 ## Multi-tenancy model
 
@@ -96,7 +97,7 @@ HTTP request builds a fresh `Context` with every model instantiated
 | 1 | auth flows, theme, navigation, splash, toasts, typed fetch |
 | 2 | offline SQLite (USER vs SHARED tables), cloud backup/restore |
 | 3 | server-driven content sync + HMAC-signed presigned asset URLs |
-| 4 | IAP via `react-native-iap`, premium gate, foreground re-check |
+| 4 | IAP via `expo-iap` (optional at scaffold), premium gate, foreground re-check |
 | 5 | custom-native local notifications with cold-start tap dispatch |
 | 6 | Apple Health + Android Health Connect unified surface |
 | 7 | native cookbook (Hello iOS/Android + Live Activity scaffold) |

package/template/README.md

@@ -16,7 +16,7 @@ integrations.
 ```bash
 ./install.sh           # install all node deps + scaffold .env files
 ./seed.sh              # create db + run migrations + seed admin user
-./dev.sh               # start every web service this preset shipped
+./dev.sh               # start every service this project shipped
 ./dev.sh --mobile      # also start Expo Metro
 ```
 
@@ -60,9 +60,9 @@ URLs (web):
 └── misc/                 systemd units, nginx samples
 ```
 
-Folders the preset didn't ship are simply absent — `dev.sh` /
+Folders the scaffold didn't ship are simply absent — `dev.sh` /
 `install.sh` guard on directory existence so the scripts work for
-every preset.
+every component combination.
 
 ## Multi-tenancy model
 
@@ -112,7 +112,7 @@ HTTP request builds a fresh `Context` with every model instantiated
 | 1 | auth flows, theme, navigation, splash, toasts, typed fetch |
 | 2 | offline SQLite (USER vs SHARED tables), cloud backup/restore via S3 |
 | 3 | server-driven content sync + HMAC-signed presigned asset URLs |
-| 4 | IAP (`react-native-iap`), receipt validation, premium gate, foreground re-check |
+| 4 | IAP (`expo-iap`, optional at scaffold), receipt validation, premium gate, foreground re-check |
 | 5 | custom-native local notifications with cold-start tap dispatch |
 | 6 | Apple Health + Android Health Connect unified surface |
 | 7 | native modules cookbook (Hello iOS/Android + Live Activity scaffold + gotchas) |

package/template/doc/index.html

@@ -514,8 +514,11 @@ POST /api/logout</code></pre>
         <section id="iap">
             <h2>IAP &amp; premium <span class="badge">Phase 4</span></h2>
             <p>
-                <code>react-native-iap</code> v15 lazy-loaded with
-                try/require so Expo Go gets graceful no-ops.
+                <code>expo-iap</code> lazy-loaded with try/require so
+                Expo Go gets graceful no-ops. Optional at scaffold
+                time &mdash; when disabled, the dependency ships
+                stripped and PremiumGate renders everything
+                unlocked.
             </p>
             <pre><code>const { activatePremium } = useAuth();
 const purchase = await purchaseSubscription(PRODUCT_IDS.annual);

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

@@ -25,9 +25,8 @@ src/
 │   ├── db/                    SQLite (USER_TABLES vs SHARED_TABLES)
 │   ├── backup/                Two-phase S3 backup (premium)
 │   ├── content/               Versioned catalog + HMAC-signed URLs
-│   ├── iap/                   react-native-iap wrapped lazily
-│   ├── notifications/         Custom-native, cold-start tap dispatch
-│   └── health/                Apple Health + Health Connect unified
+│   ├── iap/                   expo-iap wrapped lazily (optional)
+│   └── notifications/         Custom-native, cold-start tap dispatch
 └── components/
     ├── AnimatedSplash.tsx
     ├── ToastConfig.tsx
@@ -87,14 +86,27 @@ hasCompletedOnboarding
 - **Every user-facing string goes through `t()`.** Even pt-BR
   default strings. No bare strings in JSX.
 
-- **NitroModules + Expo Go = crash on import.** Anything using
-  nitro (e.g. `react-native-iap` v15) must be lazy-loaded with
-  `try/require`. See `services/iap/index.ts`.
+- **Native modules + Expo Go = crash on import.** Anything whose
+  native side isn't bundled in Expo Go (e.g. `expo-iap`) must be
+  lazy-loaded with `try/require`. See `services/iap/index.ts`.
+  IAP itself is optional at scaffold time: `config.iap === false`
+  means the expo-iap dependency was never installed and PremiumGate
+  renders everything unlocked.
 
 - **`expo prebuild --clean` will silently delete native code.**
   Use `./scripts/prebuild.sh` (refuses --clean). To genuinely
   reset, move customizations into `plugins/` first.
 
+- **Dependency versions follow the Expo SDK.** Never bump
+  `react`, `react-native`, or any `expo-*` / `react-native-*`
+  native package by hand — run `npx expo install --check` (or
+  `--fix`) so everything stays on the SDK's bundled versions.
+  `typescript` is intentionally in `expo.install.exclude`
+  (package.json): the SDK wants TS 6 but `react-i18next@15`
+  peer-requires TS 5 — keep `~5.9.x` until react-i18next is
+  bumped to v17+ (which drags i18next to v26 and drops the
+  `compatibilityJSON: 'v3'` Hermes escape hatch in `src/i18n/`).
+
 ## Splash
 
 `config.ts` exports `SPLASH_ANIMATED` (set at scaffold time). When