@buivietphi/skill-mobile-mt 1.0.0 → 1.1.0

package/AGENTS.md

@@ -53,6 +53,7 @@ skill-mobile-mt/
     ├── platform-excellence.md       ← iOS 18+ vs Android 15+ UX (1,500 tokens)
     ├── version-management.md        ← SDK compat matrix + release testing (3,500 tokens)
     ├── observability.md             ← Sessions as 4th pillar (3,000 tokens)
+    ├── architecture-intelligence.md ← Patterns from 30+ production repos (4,500 tokens)
     ├── common-pitfalls.md           ← Known issue patterns (1,160 tokens)
     ├── release-checklist.md         ← App Store/Play Store checklist (587 tokens)
     │

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: skill-mobile-mt
-description: "Master Senior Mobile Engineer. Use when: building mobile features, fixing mobile bugs, reviewing mobile code, mobile architecture, React Native, Flutter, iOS Swift, Android Kotlin, mobile performance, mobile security audit, mobile code review, app release. Two modes: (1) default = pre-built production patterns, (2) 'project' = reads current project and adapts."
-version: "1.0.0"
+description: "Master Senior Mobile Engineer. Patterns from 30+ production repos (200k+ GitHub stars: Ignite, Expensify, Mattermost, Immich, AppFlowy, Now in Android, TCA). Use when: building mobile features, fixing mobile bugs, reviewing mobile code, mobile architecture, React Native, Flutter, iOS Swift, Android Kotlin, mobile performance, mobile security audit, mobile code review, app release. Two modes: (1) default = pre-built production patterns, (2) 'project' = reads current project and adapts."
+version: "1.1.0"
 author: buivietphi
 priority: high
 user-invocable: true
@@ -72,7 +72,9 @@ USER REQUEST                    → ACTION (Read tool required)
 
 "Add X to existing Y"           → MODIFY existing files, don't create new structure
 
-"Setup project / architecture"  → Read platform file first (see Smart Loading below)
+"Setup project / architecture"  → Read: shared/architecture-intelligence.md
+                                  then: Read platform file (see Smart Loading below)
+                                  then: suggest structure based on project size + stack
 
 "Fix / debug X"                 → Read: shared/bug-detection.md
                                   then: read code → find root cause → fix → verify

package/bin/install.mjs

@@ -6,7 +6,7 @@
  * Installs skill-mobile-mt/ folder with subfolders for each platform.
  *
  * Usage:
- *   npx @buivietphi/skill-mobile              # Interactive
+ *   npx @buivietphi/skill-mobile              # Interactive checkbox UI
  *   npx @buivietphi/skill-mobile --all        # All detected agents
  *   npx @buivietphi/skill-mobile --claude     # Claude Code only
  *   npx @buivietphi/skill-mobile --gemini     # Gemini CLI
@@ -20,7 +20,6 @@ import { existsSync, mkdirSync, cpSync, readFileSync } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
-import { createInterface } from 'node:readline';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = resolve(__dirname, '..');
@@ -35,29 +34,29 @@ const SUBFOLDERS = {
   'flutter':      ['flutter.md'],
   'ios':          ['ios-native.md'],
   'android':      ['android-native.md'],
-  'shared':       ['code-review.md', 'bug-detection.md', 'prompt-engineering.md', 'release-checklist.md', 'common-pitfalls.md', 'error-recovery.md', 'document-analysis.md', 'anti-patterns.md', 'performance-prediction.md', 'platform-excellence.md', 'version-management.md', 'observability.md', 'claude-md-template.md', 'agent-rules-template.md'],
+  'shared':       ['code-review.md', 'bug-detection.md', 'prompt-engineering.md', 'release-checklist.md', 'common-pitfalls.md', 'error-recovery.md', 'document-analysis.md', 'anti-patterns.md', 'performance-prediction.md', 'platform-excellence.md', 'version-management.md', 'observability.md', 'architecture-intelligence.md', 'claude-md-template.md', 'agent-rules-template.md'],
 };
 
 const AGENTS = {
-  claude:       { name: 'Claude Code',     dir: join(HOME, '.claude', 'skills'),   detect: () => existsSync(join(HOME, '.claude')) },
-  codex:        { name: 'Codex',           dir: join(HOME, '.codex', 'skills'),    detect: () => existsSync(join(HOME, '.codex')) },
-  gemini:       { name: 'Gemini CLI',      dir: join(HOME, '.gemini', 'skills'),   detect: () => existsSync(join(HOME, '.gemini')) },
-  kimi:         { name: 'Kimi',            dir: join(HOME, '.kimi', 'skills'),     detect: () => existsSync(join(HOME, '.kimi')) },
-  antigravity:  { name: 'Antigravity',     dir: join(HOME, '.agents', 'skills'),   detect: () => existsSync(join(HOME, '.agents')) },
-  cursor:       { name: 'Cursor',          dir: join(HOME, '.cursor', 'skills'),   detect: () => existsSync(join(HOME, '.cursor')) },
-  windsurf:     { name: 'Windsurf',        dir: join(HOME, '.windsurf', 'skills'), detect: () => existsSync(join(HOME, '.windsurf')) },
-  copilot:      { name: 'Copilot',         dir: join(HOME, '.copilot', 'skills'),  detect: () => existsSync(join(HOME, '.copilot')) },
+  claude:       { name: 'Claude Code',  dir: join(HOME, '.claude', 'skills'),   detect: () => existsSync(join(HOME, '.claude')) },
+  cursor:       { name: 'Cursor',       dir: join(HOME, '.cursor', 'skills'),   detect: () => existsSync(join(HOME, '.cursor')) },
+  windsurf:     { name: 'Windsurf',     dir: join(HOME, '.windsurf', 'skills'), detect: () => existsSync(join(HOME, '.windsurf')) },
+  copilot:      { name: 'Copilot',      dir: join(HOME, '.copilot', 'skills'),  detect: () => existsSync(join(HOME, '.copilot')) },
+  codex:        { name: 'Codex',        dir: join(HOME, '.codex', 'skills'),    detect: () => existsSync(join(HOME, '.codex')) },
+  gemini:       { name: 'Gemini CLI',   dir: join(HOME, '.gemini', 'skills'),   detect: () => existsSync(join(HOME, '.gemini')) },
+  kimi:         { name: 'Kimi',         dir: join(HOME, '.kimi', 'skills'),     detect: () => existsSync(join(HOME, '.kimi')) },
+  antigravity:  { name: 'Antigravity',  dir: join(HOME, '.agents', 'skills'),   detect: () => existsSync(join(HOME, '.agents')) },
 };
 
-const c = { reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m', green: '\x1b[32m', yellow: '\x1b[33m', blue: '\x1b[34m', magenta: '\x1b[35m', cyan: '\x1b[36m', red: '\x1b[31m' };
-const log = m => console.log(m);
-const ok = m => log(`  ${c.green}✓${c.reset} ${m}`);
+const c = { reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m', green: '\x1b[32m', yellow: '\x1b[33m', blue: '\x1b[34m', cyan: '\x1b[36m', red: '\x1b[31m' };
+const log = m => process.stdout.write(m + '\n');
+const ok  = m => log(`  ${c.green}✓${c.reset} ${m}`);
 const info = m => log(`  ${c.blue}ℹ${c.reset} ${m}`);
 const fail = m => log(`  ${c.red}✗${c.reset} ${m}`);
 
 function banner() {
   log(`\n${c.bold}${c.cyan}  ┌──────────────────────────────────────────────┐`);
-  log(`  │  📱 @buivietphi/skill-mobile-mt v1.0.0       │`);
+  log(`  │  📱 @buivietphi/skill-mobile-mt v1.1.0       │`);
   log(`  │  Master Senior Mobile Engineer                │`);
   log(`  │                                              │`);
   log(`  │  Claude · Codex · Gemini · Kimi              │`);
@@ -72,26 +71,19 @@ function tokenCount(filePath) {
 }
 
 function showContext() {
-  log(`${c.bold}  📊 Context:${c.reset}`);
+  log(`${c.bold}  📊 Context budget:${c.reset}`);
   let total = 0;
-
-  // Root files
   for (const f of ROOT_FILES) {
     const t = tokenCount(join(PKG_ROOT, f));
     total += t;
     log(`  ${c.dim}  ${f.padEnd(30)} ~${t.toLocaleString()} tokens${c.reset}`);
   }
-
-  // Subfolders
   for (const [folder, files] of Object.entries(SUBFOLDERS)) {
-    let folderTotal = 0;
-    for (const f of files) {
-      folderTotal += tokenCount(join(PKG_ROOT, folder, f));
-    }
-    total += folderTotal;
-    log(`  ${c.dim}  ${(folder + '/').padEnd(30)} ~${folderTotal.toLocaleString()} tokens${c.reset}`);
+    let ft = 0;
+    for (const f of files) ft += tokenCount(join(PKG_ROOT, folder, f));
+    total += ft;
+    log(`  ${c.dim}  ${(folder + '/').padEnd(30)} ~${ft.toLocaleString()} tokens${c.reset}`);
   }
-
   log(`${c.dim}  ─────────────────────────────────────────${c.reset}`);
   log(`  ${c.bold}  All loaded:${c.reset}                    ~${total.toLocaleString()} tokens`);
   log(`  ${c.green}  Smart load (1 platform):${c.reset}       ~${Math.ceil(total * 0.55).toLocaleString()} tokens\n`);
@@ -101,16 +93,12 @@ function install(baseDir, agentName) {
   const dst = join(baseDir, SKILL_NAME);
   mkdirSync(dst, { recursive: true });
   let n = 0;
-
-  // Copy root files
   for (const f of ROOT_FILES) {
     const src = join(PKG_ROOT, f);
     if (!existsSync(src)) continue;
     cpSync(src, join(dst, f), { force: true });
     n++;
   }
-
-  // Copy subfolders
   for (const [folder, files] of Object.entries(SUBFOLDERS)) {
     const dstFolder = join(dst, folder);
     mkdirSync(dstFolder, { recursive: true });
@@ -121,18 +109,95 @@ function install(baseDir, agentName) {
       n++;
     }
   }
-
   ok(`${c.bold}${SKILL_NAME}/${c.reset} → ${agentName} ${c.dim}(${dst})${c.reset}`);
   return n;
 }
 
-async function ask(q) {
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise(r => { rl.question(q, a => { rl.close(); r(a.trim()); }); });
+// ─── Checkbox UI ─────────────────────────────────────────────────────────────
+
+async function selectAgents(detected) {
+  if (!process.stdin.isTTY) {
+    return detected.length ? detected : ['claude'];
+  }
+
+  const keys    = Object.keys(AGENTS);
+  const selected = new Set(detected); // pre-tick detected agents
+  let cursor    = 0;
+
+  const UP       = '\x1b[A';
+  const DOWN     = '\x1b[B';
+  const ERASE_DN = '\x1b[J';
+  const HIDE_CUR = '\x1b[?25l';
+  const SHOW_CUR = '\x1b[?25h';
+  const moveUp   = n => `\x1b[${n}A`;
+
+  // header = 3 lines (title + hint + blank), items = keys.length
+  const TOTAL_LINES = 3 + keys.length;
+
+  function render(first) {
+    if (!first) process.stdout.write(moveUp(TOTAL_LINES) + ERASE_DN);
+
+    process.stdout.write(`\n${c.bold}  Select agents to install:${c.reset}\n`);
+    process.stdout.write(`  ${c.dim}↑↓ navigate   Space toggle   A select all   Enter confirm   Q cancel${c.reset}\n`);
+
+    for (let i = 0; i < keys.length; i++) {
+      const k     = keys[i];
+      const agent = AGENTS[k];
+      const isCur = i === cursor;
+      const isSel = selected.has(k);
+      const isDet = detected.includes(k);
+
+      const ptr   = isCur ? `${c.cyan}›${c.reset}` : ' ';
+      const box   = isSel ? `${c.green}◉${c.reset}` : `${c.dim}◯${c.reset}`;
+      const name  = isCur ? `${c.bold}${c.cyan}${agent.name}${c.reset}` : agent.name;
+      const badge = isDet ? ` ${c.green}[detected]${c.reset}` : `${c.dim} [not found]${c.reset}`;
+
+      process.stdout.write(`  ${ptr} ${box} ${name.padEnd(14)}${badge}\n`);
+    }
+  }
+
+  process.stdout.write(HIDE_CUR);
+  render(true);
+
+  return new Promise(resolve => {
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding('utf8');
+
+    const onKey = key => {
+      const done = result => {
+        process.stdin.setRawMode(false);
+        process.stdin.pause();
+        process.stdin.off('data', onKey);
+        process.stdout.write(SHOW_CUR + '\n');
+        resolve(result);
+      };
+
+      if (key === '\x03') { done(null); process.exit(0); }      // Ctrl+C
+      if (key === 'q' || key === 'Q' || key === '\x1b') { done([]); return; } // quit
+      if (key === '\r' || key === '\n') { done([...selected]); return; }      // Enter
+
+      if (key === UP)    cursor = (cursor - 1 + keys.length) % keys.length;
+      else if (key === DOWN) cursor = (cursor + 1) % keys.length;
+      else if (key === ' ') {
+        if (selected.has(keys[cursor])) selected.delete(keys[cursor]);
+        else selected.add(keys[cursor]);
+      } else if (key === 'a' || key === 'A') {
+        if (selected.size === keys.length) selected.clear();
+        else keys.forEach(k => selected.add(k));
+      }
+
+      render(false);
+    };
+
+    process.stdin.on('data', onKey);
+  });
 }
 
+// ─── Main ─────────────────────────────────────────────────────────────────────
+
 async function main() {
-  const args = process.argv.slice(2);
+  const args  = process.argv.slice(2);
   const flags = new Set(args.map(a => a.replace(/^--?/, '')));
 
   banner();
@@ -140,28 +205,31 @@ async function main() {
 
   let targets = [];
 
-  if (flags.has('all')) targets = Object.keys(AGENTS);
-  else if (flags.has('auto')) {
+  if (flags.has('all')) {
+    targets = Object.keys(AGENTS);
+  } else if (flags.has('auto')) {
     targets = Object.keys(AGENTS).filter(k => AGENTS[k].detect());
     if (!targets.length) { info('No agents found. Using Claude.'); targets = ['claude']; }
   } else if (flags.has('path')) {
     const p = args[args.indexOf('--path') + 1];
-    if (!p) { fail('--path needs dir'); process.exit(1); }
+    if (!p) { fail('--path needs a directory'); process.exit(1); }
     install(resolve(p), 'Custom');
-    log(`\n${c.green}${c.bold}  ✅ Done!${c.reset}\n`); return;
+    log(`\n${c.green}${c.bold}  ✅ Done!${c.reset}\n`);
+    return;
   } else {
     for (const k of Object.keys(AGENTS)) if (flags.has(k)) targets.push(k);
   }
 
+  // Interactive checkbox when no flag given
   if (!targets.length) {
-    const det = Object.keys(AGENTS).filter(k => AGENTS[k].detect());
-    log(`${c.bold}  Detected agents:${c.reset}`);
-    det.forEach(k => log(`    ${c.green}●${c.reset} ${AGENTS[k].name}`));
-    Object.keys(AGENTS).filter(k => !det.includes(k)).forEach(k => log(`    ${c.dim}○ ${AGENTS[k].name}${c.reset}`));
-    log('');
-    const a = await ask('  Install to detected agents? [Y/n] ');
-    if (a.toLowerCase() === 'n') { info('Cancelled.'); return; }
-    targets = det.length ? det : ['claude'];
+    const detected = Object.keys(AGENTS).filter(k => AGENTS[k].detect());
+    const chosen   = await selectAgents(detected);
+
+    if (!chosen || chosen.length === 0) {
+      info('Cancelled.');
+      return;
+    }
+    targets = chosen;
   }
 
   log(`\n${c.bold}  Installing...${c.reset}\n`);
@@ -171,29 +239,11 @@ async function main() {
   log(`  ${c.bold}Usage:${c.reset}`);
   log(`    ${c.cyan}@skill-mobile-mt${c.reset}         Pre-built patterns (18 production apps)`);
   log(`    ${c.cyan}@skill-mobile-mt project${c.reset} Read current project, adapt to it\n`);
-  log(`  ${c.bold}Installed structure:${c.reset}`);
-  log(`    ${SKILL_NAME}/`);
-  log(`    ├── SKILL.md                    Entry point + auto-detect`);
-  log(`    ├── AGENTS.md                   Multi-agent config`);
-  log(`    ├── react-native/`);
-  log(`    │   └── react-native.md         React Native patterns`);
-  log(`    ├── flutter/`);
-  log(`    │   └── flutter.md              Flutter patterns`);
-  log(`    ├── ios/`);
-  log(`    │   └── ios-native.md           iOS Swift patterns`);
-  log(`    ├── android/`);
-  log(`    │   └── android-native.md       Android Kotlin patterns`);
-  log(`    └── shared/`);
-  log(`        ├── code-review.md          Review checklist`);
-  log(`        ├── bug-detection.md        Bug scanner`);
-  log(`        ├── prompt-engineering.md   Auto-think`);
-  log(`        ├── anti-patterns.md        PII/cardinality detection`);
-  log(`        ├── performance-prediction.md  Frame budget calculator`);
-  log(`        ├── platform-excellence.md  iOS 18+ vs Android 15+`);
-  log(`        ├── version-management.md   SDK compatibility matrix`);
-  log(`        ├── observability.md        Sessions as 4th pillar`);
-  log(`        ├── claude-md-template.md   CLAUDE.md template for Claude Code`);
-  log(`        └── agent-rules-template.md Rules template for ALL agents\n`);
+  log(`  ${c.bold}Installed to:${c.reset}`);
+  for (const k of targets) {
+    log(`    ${c.green}●${c.reset} ${AGENTS[k].name.padEnd(14)} ${c.dim}${AGENTS[k].dir}/${SKILL_NAME}${c.reset}`);
+  }
+  log('');
 }
 
 main().catch(e => { fail(e.message); process.exit(1); });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buivietphi/skill-mobile-mt",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Master Senior Mobile Engineer skill for AI agents. Pre-built patterns from 18 production apps + local project adaptation. React Native, Flutter, iOS, Android. Supports Claude, Gemini, Kimi, Cursor, Copilot, Antigravity.",
   "author": "buivietphi",
   "license": "MIT",

package/shared/architecture-intelligence.md

@@ -0,0 +1,416 @@
+# Architecture Intelligence — Patterns from 30+ Production Repos
+
+> On-demand. Load when: "architecture", "structure", "setup project", "best practices", "how to organize"
+> Source: Analyzed 30+ open-source production mobile apps (total 200k+ GitHub stars)
+
+---
+
+## Reference Repos (by platform)
+
+| Platform | Repo | Stars | Key Pattern |
+|----------|------|-------|-------------|
+| **RN** | Ignite (infinitered) | 19.7k | MST + MMKV + generators |
+| **RN** | Obytes Template | 4k | Zustand + TanStack Query + Expo Router |
+| **RN** | Expensify/App | 4.7k | Onyx custom state + centralized constants |
+| **RN** | Mattermost Mobile | 2.6k | WatermelonDB + offline-first + WebSocket |
+| **RN** | Artsy Eigen | 3.8k | Relay/GraphQL + Scene pattern |
+| **Flutter** | Immich | 93.5k | Riverpod + drift + auto_route + clean arch |
+| **Flutter** | AppFlowy | 68.2k | BLoC + GetIt + startup/ pattern |
+| **Flutter** | Spotube | 44.6k | Riverpod + Hooks + custom hooks folder |
+| **Flutter** | Hiddify | 26.7k | Riverpod + go_router + bootstrap.dart |
+| **Flutter** | Ente Photos | 24.8k | Melos monorepo + gateway pattern |
+| **iOS** | TCA (Point-Free) | 14.4k | Unidirectional + TestStore + @Dependency |
+| **iOS** | Clean Arch SwiftUI | 6.5k | Redux state + @Environment DI |
+| **iOS** | Modern Clean Arch | 4.1k | Tuist + 5-layer DDD + MVVM+TCA coexist |
+| **Android** | Now in Android | 20.7k | Official Google arch + no-mock testing |
+| **Android** | Android Showcase | 6.7k | Konsist validation + Koin DI |
+| **Android** | Mihon | 18.8k | Plugin/extension arch + MVI |
+
+---
+
+## Cross-Platform Architecture Patterns
+
+### 1. Dual State Management (Client + Server)
+
+**The pattern:** Separate client state (UI, forms) from server state (API cache).
+
+| Platform | Client State | Server State |
+|----------|-------------|--------------|
+| React Native | Zustand / MST | TanStack Query |
+| Flutter | Riverpod | Riverpod + drift |
+| iOS | @Observable / TCA | URLSession cache |
+| Android | ViewModel + Flow | Repository + Room |
+
+```typescript
+// RN: Zustand for client + TanStack Query for server
+const useAuthStore = create((set) => ({
+  token: null,
+  setToken: (t) => set({ token: t }),
+}));
+
+const { data, isLoading } = useQuery({
+  queryKey: ['products'],
+  queryFn: () => api.getProducts(),
+  staleTime: 5 * 60 * 1000,
+});
+```
+
+```dart
+// Flutter: Riverpod for both, but separated
+@riverpod
+class AuthNotifier extends _$AuthNotifier { ... } // client
+
+@riverpod
+Future<List<Product>> products(Ref ref) async { ... } // server
+```
+
+### 2. Feature-Based Module Organization
+
+**Every top repo (100%) uses feature-based organization, NOT type-based.**
+
+```
+// ✅ CORRECT: Feature-based (Immich, Obytes, Hiddify, Now in Android)
+src/features/
+  auth/
+    domain/         # entities, use cases, repo interfaces
+    data/           # repo impl, API, DTOs, mappers
+    presentation/   # screens, widgets, viewmodels
+
+// ❌ WRONG: Type-based (no production app uses this)
+src/
+  models/
+  services/
+  screens/
+  widgets/
+```
+
+### 3. Centralized Constants Pattern (Expensify)
+
+```typescript
+// src/ROUTES.ts — Prevents string duplication
+const ROUTES = {
+  HOME: 'home',
+  SETTINGS: 'settings',
+  PROFILE: 'profile/:id',
+} as const;
+
+// src/SCREENS.ts — Screen component names
+const SCREENS = {
+  HOME: 'HomeScreen',
+  SETTINGS: 'SettingsScreen',
+} as const;
+```
+
+### 4. Bootstrap / Startup Pattern (Hiddify, AppFlowy)
+
+```dart
+// bootstrap.dart — Clean app initialization
+Future<void> bootstrap() async {
+  WidgetsFlutterBinding.ensureInitialized();
+
+  // 1. Core services
+  await Firebase.initializeApp();
+  await Hive.initFlutter();
+
+  // 2. DI registration
+  setupServiceLocator();
+
+  // 3. Run app
+  runApp(
+    ProviderScope(
+      observers: [RiverpodObserver()],
+      child: const App(),
+    ),
+  );
+}
+
+// main.dart
+void main() => bootstrap();
+
+// main_prod.dart — Production flavor
+void main() {
+  const env = Environment.production;
+  bootstrap(env: env);
+}
+```
+
+### 5. Draft Pairs for Forms (Expensify)
+
+```typescript
+// Every form has FORM + FORM_DRAFT for unsaved changes
+const ONYX_KEYS = {
+  WORKSPACE_SETTINGS_FORM: 'workspaceSettingsForm',
+  WORKSPACE_SETTINGS_FORM_DRAFT: 'workspaceSettingsFormDraft',
+} as const;
+
+// Save draft on every keystroke → restore on crash/back
+// Only commit FORM when user explicitly saves
+```
+
+### 6. Database Subscription Pattern (Mattermost)
+
+```
+database/
+  models/         # WatermelonDB model definitions
+  schema/         # DB structure + versioning
+  migration/      # Schema migrations
+  operator/       # Complex query logic (keeps models clean)
+  subscription/   # Reactive UI updates from DB changes
+  exceptions/     # Custom error classes
+  manager/        # DB lifecycle (create, reset, destroy)
+```
+
+### 7. Functional Error Handling (Flutter — dartz)
+
+```dart
+// Instead of try/catch everywhere, use Either<Failure, Success>
+Future<Either<AppException, User>> getUser(String id) async {
+  try {
+    final response = await dio.get('/users/$id');
+    return Right(User.fromJson(response.data));
+  } on DioException catch (e) {
+    return Left(NetworkException(e.message));
+  }
+}
+
+// Usage — forces caller to handle both cases
+final result = await getUser('123');
+result.fold(
+  (failure) => showError(failure.message),
+  (user) => showProfile(user),
+);
+```
+
+### 8. Architecture Validation (Android Showcase — Konsist)
+
+```kotlin
+// Programmatically enforce architecture rules
+@Test
+fun `domain layer should not depend on data layer`() {
+  Konsist.scopeFromModule("feature-album/domain")
+    .classes()
+    .assertFalse { it.hasImport { import -> import.hasNameContaining("data") } }
+}
+
+@Test
+fun `use cases should have 'UseCase' suffix`() {
+  Konsist.scopeFromModule("feature-album/domain")
+    .classes()
+    .withNameContaining("UseCase")
+    .assertTrue { it.hasPublicFunction("invoke") }
+}
+```
+
+---
+
+## Platform-Specific Intelligence
+
+### React Native — Must-Know Patterns
+
+| Pattern | Old Way | New Way (2024-2025) | Source |
+|---------|---------|---------------------|--------|
+| Storage | AsyncStorage | MMKV (60x faster) | Ignite, Obytes |
+| Routing | React Navigation | Expo Router (file-based) | Obytes |
+| Server state | Redux + thunk | TanStack Query | Obytes, TCM |
+| Client state | Redux | Zustand | Obytes |
+| E2E testing | Detox | Maestro | Ignite, Obytes |
+| Forms | Formik + Yup | TanStack Form + Zod | Obytes |
+| Styling | StyleSheet | NativeWind (TailwindCSS) | Obytes |
+| Animations | Animated API | Reanimated 3 | All |
+| Images | Image | expo-image / FastImage | All |
+
+### Flutter — Must-Know Patterns
+
+| Pattern | Old Way | New Way (2024-2025) | Source |
+|---------|---------|---------------------|--------|
+| State | setState / Provider | Riverpod + code-gen | Immich, Hiddify, Spotube |
+| State (alt) | BLoC manual | BLoC + freezed | AppFlowy |
+| Navigation | Navigator 2.0 | auto_route / go_router | Immich / Hiddify |
+| Database | sqflite | drift (type-safe ORM) | Immich, Spotube |
+| Models | manual fromJson | freezed + json_serializable | All |
+| i18n | .arb files | slang (type-safe, generated) | Hiddify |
+| HTTP | http package | dio + smart_retry | Hiddify |
+| HTTP (perf) | dio on all | cronet (Android) + cupertino_http (iOS) | Immich |
+| Monorepo | N/A | Melos | Ente |
+| DI | manual | Riverpod providers / GetIt | Immich / AppFlowy |
+
+### iOS Swift — Must-Know Patterns
+
+| Pattern | Traditional | Modern (2024-2025) | Source |
+|---------|-------------|---------------------|--------|
+| Architecture | MVVM manual | TCA (macro-driven) | Point-Free |
+| DI | Swinject | @Dependency (Point-Free) / @Environment | TCA / nalexn |
+| Testing | XCTest + mocks | TestStore (deterministic) | TCA |
+| Navigation | NavigationView | NavigationStack + Coordinator | sergdort |
+| Modularization | One target | Tuist multi-module | sergdort |
+| Data binding | Combine | @Observable macro | iOS 17+ |
+| SwiftUI testing | None | ViewInspector | nalexn |
+| Concurrency | GCD / Combine | async/await + actors | All |
+
+### Android Kotlin — Must-Know Patterns
+
+| Pattern | Traditional | Modern (2024-2025) | Source |
+|---------|-------------|---------------------|--------|
+| UI | XML Views | Jetpack Compose | All |
+| Architecture | MVVM | MVVM + UDF (Now in Android) | Google |
+| DI | Dagger 2 | Hilt | Now in Android |
+| DI (lightweight) | N/A | Koin | Android Showcase |
+| Testing | Mockito | No-mock test doubles | Now in Android |
+| Arch validation | Manual review | Konsist | Android Showcase |
+| Performance | ProGuard | Baseline Profiles + R8 | Now in Android |
+| Navigation | Fragment nav | Compose Navigation (type-safe) | All |
+| Build config | build.gradle | Convention Plugins | Now in Android |
+| Screenshot test | None | Roborazzi | Now in Android |
+
+---
+
+## Production Folder Structure Templates
+
+### React Native (Expo Router — based on Obytes)
+
+```
+src/
+  app/                    # Expo Router file-based routes
+    (app)/                # Authenticated group
+      _layout.tsx
+      (tabs)/             # Tab navigator
+    login.tsx
+    onboarding.tsx
+    _layout.tsx           # Root layout
+  features/               # Feature modules
+    auth/
+      hooks/
+      components/
+      services/
+      types.ts
+    products/
+      hooks/
+      components/
+      services/
+  components/
+    ui/                   # Design system (Button, Input, Card)
+  lib/
+    api/                  # Axios + TanStack Query setup
+    auth/                 # Token management (Zustand + MMKV)
+    hooks/                # Shared hooks
+    i18n/                 # Internationalization
+    storage.ts            # MMKV wrapper
+    utils.ts              # Utilities
+  translations/           # Language files
+```
+
+### Flutter (Riverpod + Clean — based on Immich)
+
+```
+lib/
+  main.dart
+  bootstrap.dart          # App initialization
+  app/
+    app.dart              # MaterialApp.router
+    router.dart           # auto_route / go_router config
+    theme/
+  features/
+    auth/
+      domain/             # Entities, use cases, repo interfaces
+      data/               # Repo impl, datasources, DTOs
+      presentation/       # Screens + widgets
+      providers/          # Riverpod providers
+    [feature]/
+  shared/
+    widgets/              # Reusable UI
+    extensions/           # Dart extensions
+    constants/            # App-wide constants
+    interfaces/           # Abstract contracts
+    models/               # Shared DTOs
+    utils/                # Utilities
+  l10n/                   # Localization
+```
+
+### iOS SwiftUI (TCA — based on Point-Free + sergdort)
+
+```
+App/
+  AppDelegate.swift
+  AppModule.swift         # Composition root
+Features/
+  Auth/
+    AuthFeature.swift     # @Reducer
+    AuthView.swift        # SwiftUI View
+    AuthClient.swift      # @Dependency
+  Home/
+    HomeFeature.swift
+    HomeView.swift
+  Settings/
+Shared/
+  Models/
+  Extensions/
+  UI/                     # Shared SwiftUI components
+  Clients/                # API, Storage, Keychain
+Platform/
+  Networking/
+  Persistence/
+Tests/
+  AuthFeatureTests.swift  # TestStore tests
+```
+
+### Android Kotlin (Now in Android — based on Google reference)
+
+```
+app/                      # Main application
+core/
+  common/                 # Shared utilities
+  data/                   # Repository implementations
+  database/               # Room database
+  datastore/              # Proto DataStore
+  network/                # Retrofit + OkHttp
+  model/                  # Core models
+  ui/                     # Shared Compose components
+  testing/                # Test utilities
+feature/
+  auth/
+    src/main/
+      AuthScreen.kt       # Compose UI
+      AuthViewModel.kt    # ViewModel
+      AuthUiState.kt      # UI state sealed class
+      navigation/          # Feature nav graph
+  home/
+  settings/
+build-logic/              # Convention plugins
+  convention/
+    AndroidApplicationConventionPlugin.kt
+    AndroidFeatureConventionPlugin.kt
+```
+
+---
+
+## Decision Matrix — When to Use What
+
+### State Management
+
+| Condition | RN | Flutter | iOS | Android |
+|-----------|-----|---------|-----|---------|
+| Simple app (<10 screens) | Zustand | Riverpod | @Observable | ViewModel + StateFlow |
+| Complex app (10-50 screens) | Zustand + TanStack Query | Riverpod + freezed | TCA | MVVM + Hilt + Flow |
+| Enterprise (50+ screens) | Onyx (custom) / Redux Toolkit | BLoC + GetIt | TCA + Tuist | MVVM + Hilt + Convention Plugins |
+| Offline-first | TanStack Query + WatermelonDB | Riverpod + drift | TCA + SwiftData | Room + WorkManager |
+
+### Navigation
+
+| Condition | RN | Flutter | iOS | Android |
+|-----------|-----|---------|-----|---------|
+| Expo project | Expo Router | — | — | — |
+| RN CLI project | React Navigation | — | — | — |
+| Type-safe routes | — | auto_route | NavigationStack | Compose Navigation |
+| Declarative | Expo Router | go_router | NavigationStack | Compose Navigation |
+| Deep linking | Expo Linking | app_links | Universal Links | App Links |
+
+### Testing
+
+| What | RN | Flutter | iOS | Android |
+|------|-----|---------|-----|---------|
+| Unit | Jest | test + mocktail | XCTest / TestStore | JUnit + no-mock doubles |
+| Widget/Component | React Testing Library | widget test | ViewInspector | Compose Testing |
+| E2E | Maestro | integration_test | XCUITest | Macrobenchmark |
+| Screenshot | — | golden_toolkit | — | Roborazzi |
+| Architecture | Dependency Cruiser | — | — | Konsist |
+| Performance | Reassure | DevTools | Instruments | Baseline Profiles |