@codeyam/codeyam-cli 0.1.0-staging.b8b17a5 → 0.1.0-staging.b8ee127

package/codeyam-cli/templates/expo-react-native/package.json

@@ -7,32 +7,48 @@
     "setup": "npm install",
     "dev": "expo start --web",
     "start": "expo start",
-    "android": "expo start --android",
-    "ios": "expo start --ios",
-    "build:web": "expo export --platform web"
+    "android": "expo run:android",
+    "ios": "expo run:ios",
+    "build:web": "expo export --platform web",
+    "test": "jest",
+    "postinstall": "patch-package"
   },
   "dependencies": {
-    "expo": "~55.0.5",
-    "expo-router": "~55.0.4",
-    "expo-status-bar": "~55.0.4",
-    "expo-linking": "~55.0.7",
-    "expo-constants": "~55.0.7",
-    "react": "19.2.0",
-    "react-dom": "19.2.0",
-    "react-native": "0.83.2",
+    "expo": "~54.0.0",
+    "expo-router": "~6.0.23",
+    "expo-status-bar": "~3.0.9",
+    "expo-linking": "~8.0.11",
+    "expo-constants": "~18.0.13",
+    "expo-font": "~14.0.11",
+    "react": "19.1.0",
+    "react-dom": "19.1.0",
+    "react-native": "0.81.5",
     "react-native-web": "^0.21.0",
     "react-native-safe-area-context": "~5.6.2",
-    "react-native-screens": "~4.23.0",
+    "react-native-screens": "~4.16.0",
+    "react-native-reanimated": "^4.3.0",
+    "react-native-worklets": "^0.8.1",
+    "react-refresh": "^0.18.0",
     "@react-navigation/native": "^7.1.33",
     "@expo/vector-icons": "^15.0.2",
     "@react-native-async-storage/async-storage": "2.2.0",
     "nativewind": "^4.2.2",
     "tailwindcss": "^3.4.19",
-    "react-native-reanimated": "4.2.1"
+    "patch-package": "^8.0.0"
   },
   "devDependencies": {
-    "@types/react": "~19.2.2",
-    "babel-preset-expo": "^55.0.10",
-    "typescript": "~5.9.2"
+    "@types/react": "~19.1.10",
+    "babel-preset-expo": "~54.0.10",
+    "sharp": "^0.33.0",
+    "typescript": "~5.9.2",
+    "jest": "^29.7.0",
+    "jest-expo": "~54.0.17",
+    "@testing-library/react-native": "^13.2.0"
+  },
+  "jest": {
+    "preset": "jest-expo",
+    "transformIgnorePatterns": [
+      "node_modules/(?!((jest-)?react-native|@react-native(-community)?)|expo(nent)?|@expo(nent)?/.*|@expo-google-fonts/.*|react-navigation|@react-navigation/.*|nativewind|react-native-reanimated|react-native-worklets)"
+    ]
   }
 }

package/codeyam-cli/templates/expo-react-native/patches/expo-modules-autolinking+3.0.24.patch

@@ -0,0 +1,29 @@
+diff --git a/node_modules/expo-modules-autolinking/build/platforms/apple/apple.js b/node_modules/expo-modules-autolinking/build/platforms/apple/apple.js
+index 47487c0..58a6069 100644
+--- a/node_modules/expo-modules-autolinking/build/platforms/apple/apple.js
++++ b/node_modules/expo-modules-autolinking/build/platforms/apple/apple.js
+@@ -113,7 +113,7 @@ async function generatePackageListFileContentAsync(modules, className, entitleme
+  * but only these that are written in Swift and use the new API for creating Expo modules.
+  */
+
+-import ExpoModulesCore
++public import ExpoModulesCore
+ ${generateCommonImportList(swiftModules)}
+ ${generateDebugOnlyImportList(debugOnlySwiftModules)}
+ @objc(${className})
+@@ -137,13 +137,13 @@ ${generateReactDelegateHandlers(reactDelegateHandlerModules, debugOnlyReactDeleg
+ `;
+ }
+ function generateCommonImportList(swiftModules) {
+-    return swiftModules.map((moduleName) => `import ${moduleName}`).join('\n');
++    return swiftModules.map((moduleName) => `public import ${moduleName}`).join('\n');
+ }
+ function generateDebugOnlyImportList(swiftModules) {
+     if (!swiftModules.length) {
+         return '';
+     }
+-    return (wrapInDebugConfigurationCheck(0, swiftModules.map((moduleName) => `import ${moduleName}`).join('\n')) + '\n');
++    return (wrapInDebugConfigurationCheck(0, swiftModules.map((moduleName) => `public import ${moduleName}`).join('\n')) + '\n');
+ }
+ function generateModuleClasses(classNames, debugOnlyClassName) {
+     const commonClassNames = formatArrayOfClassNames(classNames);

package/codeyam-cli/templates/isolation-route/expo-router.tsx.template

@@ -0,0 +1,54 @@
+/**
+ * CodeYam Isolation Route — Expo Router
+ *
+ * Place this file at: app/isolated-components/ComponentName.tsx
+ * URL: /isolated-components/ComponentName?s=ScenarioName
+ *
+ * This route renders a single component with scenario-specific props,
+ * enabling isolated component preview and screenshot capture.
+ */
+
+import { useLocalSearchParams } from 'expo-router';
+import { View, Text } from 'react-native';
+import { theme } from '@/lib/theme';
+// import YourComponent from '@/app/components/YourComponent';
+
+// Define scenarios: map scenario names to component props
+const scenarios: Record<string, Record<string, unknown>> = {
+  Default: {
+    // props for the default scenario
+  },
+  // Add more scenarios here
+};
+
+export default function ComponentIsolation() {
+  const { s } = useLocalSearchParams<{ s: string }>();
+  const scenarioName = s || 'Default';
+  const props = scenarios[scenarioName];
+
+  if (!props) {
+    return (
+      <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
+        <Text style={{ fontFamily: theme.fontFamily.mono, color: '#e74c3c' }}>
+          Unknown scenario: {scenarioName}
+        </Text>
+      </View>
+    );
+  }
+
+  return (
+    <View
+      style={{
+        flex: 1,
+        justifyContent: 'center',
+        alignItems: 'center',
+        backgroundColor: theme.colors.bgBase,
+      }}
+    >
+      <View nativeID="codeyam-capture" style={{ maxWidth: 384 }}>
+        {/* <YourComponent {...props} /> */}
+        <Text>Replace with your component</Text>
+      </View>
+    </View>
+  );
+}

package/codeyam-cli/templates/nextjs-prisma-sqlite/seed-adapter.ts

@@ -37,49 +37,62 @@ async function main() {
   const data = JSON.parse(raw);
   const seed = data.seed || data;
 
-  console.log(`Seeding tables: ${Object.keys(seed).join(', ')}`);
+  // Discover ALL models from the Prisma schema — not just the tables in the seed data.
+  // This ensures FK-dependent tables (e.g., Passenger → Flight) are cleared even when
+  // the seed only contains the parent table's data.
+  const allModels = Prisma.dmmf.datamodel.models.map(
+    (m) => m.name.charAt(0).toLowerCase() + m.name.slice(1),
+  );
 
-  // Wipe all tables in reverse order (to respect foreign keys)
-  const tableNames = Object.keys(seed);
-  for (const table of [...tableNames].reverse()) {
-    try {
-      await (prisma as any)[table].deleteMany();
-      console.log(`  Cleared ${table}`);
-    } catch (err) {
-      console.warn(
-        `  Could not clear ${table}: ${err instanceof Error ? err.message : err}`,
-      );
+  // Run everything in a single transaction for atomicity and speed.
+  // SQLite auto-commits each statement by default — wrapping in a transaction
+  // avoids per-statement fsync and is significantly faster for bulk operations.
+  await prisma.$transaction(async (tx) => {
+    // Disable foreign key checks during wipe+insert — allows deleting in any
+    // order and avoids FK constraint errors during the brief window between
+    // clearing parent and child tables.
+    await tx.$executeRawUnsafe('PRAGMA foreign_keys = OFF');
+
+    // Wipe ALL tables in the schema (not just seeded ones)
+    for (const table of [...allModels].reverse()) {
+      try {
+        await (tx as any)[table].deleteMany();
+      } catch {
+        // Table may not exist in current schema — skip
+      }
     }
-  }
 
-  // Reset auto-increment counters so IDs start from 1 after each re-seed.
-  // Without this, SQLite IDs keep climbing (1, 2, ... then 9, 10, ...)
-  // across scenario switches, causing hardcoded URLs like /drinks/1 to 404.
-  for (const table of tableNames) {
+    // Batch-reset auto-increment counters for ALL tables.
+    // Without this, SQLite IDs keep climbing across scenario switches,
+    // causing hardcoded URLs like /drinks/1 to 404.
+    const seqNames = allModels
+      .flatMap((t) => [`'${t}'`, `'${t.charAt(0).toUpperCase() + t.slice(1)}'`])
+      .join(', ');
     try {
-      // Prisma uses PascalCase model names; sqlite_sequence stores the actual table name.
-      // Try both the seed key (which matches the Prisma model) and common casings.
-      await prisma.$executeRawUnsafe(
-        `DELETE FROM sqlite_sequence WHERE name = '${table}' OR name = '${table.charAt(0).toUpperCase() + table.slice(1)}'`,
+      await tx.$executeRawUnsafe(
+        `DELETE FROM sqlite_sequence WHERE name IN (${seqNames})`,
       );
     } catch {
-      // sqlite_sequence may not exist if no autoincrement columns — safe to ignore
+      // sqlite_sequence may not exist — safe to ignore
     }
-  }
 
-  // Insert seed data
-  for (const [table, rows] of Object.entries(seed)) {
-    if (!Array.isArray(rows) || rows.length === 0) continue;
-    try {
-      await (prisma as any)[table].createMany({ data: rows });
-      console.log(`  Seeded ${rows.length} rows into ${table}`);
-    } catch (err) {
-      console.error(
-        `  Failed to seed ${table}: ${err instanceof Error ? err.message : err}`,
-      );
-      process.exit(1);
+    // Insert seed data
+    for (const [table, rows] of Object.entries(seed)) {
+      if (!Array.isArray(rows) || rows.length === 0) continue;
+      try {
+        await (tx as any)[table].createMany({ data: rows });
+        console.log(`  Seeded ${rows.length} rows into ${table}`);
+      } catch (err) {
+        console.error(
+          `  Failed to seed ${table}: ${err instanceof Error ? err.message : err}`,
+        );
+        process.exit(1);
+      }
     }
-  }
+
+    // Re-enable foreign key checks
+    await tx.$executeRawUnsafe('PRAGMA foreign_keys = ON');
+  });
 
   console.log('Seed complete');
 }

package/codeyam-cli/templates/seed-adapters/supabase.ts

@@ -10,16 +10,19 @@
  *   "tableName": [{ "column": "value", ... }, ...],
  *   "_auth": {                          // optional
  *     "email": "alice@example.com",
- *     "password": "test123"
+ *     "password": "test123"             // optional — default used if omitted
  *   }
  * }
  *
  * When _auth is present, the adapter:
  * 1. Creates the user if they don't exist (auto-confirms email)
- * 2. Signs in with signInWithPassword to get a valid session
- * 3. Writes session cookies to .codeyam/tmp/seed-session.json
+ * 2. Builds a synthetic JWT with far-future expiry (no real sign-in needed)
+ * 3. Writes session cookies + auth mocks to .codeyam/tmp/seed-session.json
  *    so the CodeYam proxy can inject them into the browser
  *
+ * The password field is optional — if omitted, a default dev password is used.
+ * No real JWTs are stored; the preload module intercepts all auth API calls.
+ *
  * Requirements:
  * - A Supabase project URL (https://<ref>.supabase.co) in any env var
  * - A secret key (sb_secret_... or legacy eyJ... service_role JWT) in any env var
@@ -28,6 +31,7 @@
  */
 
 import { createClient } from '@supabase/supabase-js';
+import { Prisma } from '@prisma/client';
 import * as fs from 'fs';
 import * as path from 'path';
 
@@ -65,7 +69,6 @@ const supabaseUrl = findAllEnvByPattern(
 
 // New-format keys are unambiguous by prefix
 const newSecretKey = findAllEnvByPattern(/^sb_secret_/)[0];
-const newAnonKey = findAllEnvByPattern(/^sb_publishable_/)[0];
 
 // Legacy JWT keys — disambiguate by decoding the role claim
 const legacyJwts = findAllEnvByPattern(
@@ -74,10 +77,8 @@ const legacyJwts = findAllEnvByPattern(
 const legacyServiceRole = legacyJwts.find(
   (jwt) => getJwtRole(jwt) === 'service_role',
 );
-const legacyAnon = legacyJwts.find((jwt) => getJwtRole(jwt) === 'anon');
 
 const secretKey = newSecretKey || legacyServiceRole;
-const anonKey = newAnonKey || legacyAnon;
 
 if (!supabaseUrl || !secretKey) {
   console.error(
@@ -108,14 +109,42 @@ function getProjectRef(): string {
   }
 }
 
+/**
+ * Build a mapping from lowercased seed-data keys to actual PostgreSQL table names.
+ * Prisma creates tables with the model name (PascalCase) unless @@map is used.
+ * PostgREST requires the exact table name, so we need this translation.
+ */
+function buildTableNameMap(): Record<string, string> {
+  const map: Record<string, string> = {};
+  for (const model of Prisma.dmmf.datamodel.models) {
+    // dbName is set when @@map is used, otherwise null → use model name
+    const dbName = (model as any).dbName || model.name;
+    // Map lowercased model name → actual table name
+    const lowered = model.name.charAt(0).toLowerCase() + model.name.slice(1);
+    map[lowered] = dbName;
+    map[model.name] = dbName; // Also map PascalCase for safety
+  }
+  return map;
+}
+
 async function seedTables(seed: Record<string, unknown[]>) {
-  const tableNames = Object.keys(seed);
-  if (tableNames.length === 0) return;
+  if (Object.keys(seed).length === 0) return;
+
+  const tableMap = buildTableNameMap();
+
+  // Discover ALL models from the Prisma schema — not just the tables in the seed data.
+  // This ensures FK-dependent tables are cleared even when the seed only contains
+  // the parent table's data. Every editor project has Prisma installed.
+  const allTables = Prisma.dmmf.datamodel.models.map(
+    (m) => (m as any).dbName || m.name,
+  );
 
-  console.log(`Seeding tables: ${tableNames.join(', ')}`);
+  console.log(
+    `Clearing ${allTables.length} tables, seeding: ${Object.keys(seed).join(', ')}`,
+  );
 
-  // Wipe tables in reverse order (to respect foreign keys)
-  for (const table of [...tableNames].reverse()) {
+  // Clear ALL tables in reverse order (children before parents for FK safety)
+  for (const table of [...allTables].reverse()) {
     const { error } = await supabase.from(table).delete().gte('id', 0);
     if (error) {
       const { error: error2 } = await supabase
@@ -132,9 +161,10 @@ async function seedTables(seed: Record<string, unknown[]>) {
     }
   }
 
-  // Insert seed data
-  for (const [table, rows] of Object.entries(seed)) {
+  // Insert seed data — translate seed keys to actual table names
+  for (const [seedKey, rows] of Object.entries(seed)) {
     if (!Array.isArray(rows) || rows.length === 0) continue;
+    const table = tableMap[seedKey] || seedKey;
     const { error } = await supabase.from(table).insert(rows);
     if (error) {
       console.error(`  Failed to seed ${table}: ${error.message}`);
@@ -145,16 +175,60 @@ async function seedTables(seed: Record<string, unknown[]>) {
 }
 
 /**
- * Handle auth: create user, sign in, write session cookies.
+ * Build a minimal JWT with a far-future expiry.
+ * The signature is fake — it doesn't matter because the CodeYam preload module
+ * intercepts the Supabase auth validation endpoint and returns mock data.
+ */
+function buildFakeJwt(userId: string, email: string): string {
+  const header = { alg: 'HS256', typ: 'JWT' };
+  const payload = {
+    sub: userId,
+    email,
+    role: 'authenticated',
+    aud: 'authenticated',
+    exp: 9999999999,
+    iat: Math.floor(Date.now() / 1000),
+  };
+  const encode = (obj: object) =>
+    Buffer.from(JSON.stringify(obj)).toString('base64url');
+  return `${encode(header)}.${encode(payload)}.codeyam-mock-signature`;
+}
+
+/**
+ * Build a Supabase user response object matching the /auth/v1/user endpoint format.
+ */
+function buildUserResponse(user: { id: string; email?: string }) {
+  return {
+    id: user.id,
+    aud: 'authenticated',
+    role: 'authenticated',
+    email: user.email || '',
+    email_confirmed_at: new Date().toISOString(),
+    app_metadata: { provider: 'email', providers: ['email'] },
+    user_metadata: {},
+    created_at: new Date().toISOString(),
+  };
+}
+
+const DEFAULT_AUTH_PASSWORD = 'codeyam-dev-password-123!';
+
+/**
+ * Handle auth: create user, build synthetic session, write session cookies.
  * Returns the user ID so callers can replace __AUTH_USER_ID__ placeholders in seed data.
+ *
+ * No real sign-in is performed — the session cookie uses a synthetic JWT with
+ * far-future expiry, and externalApis mocks intercept all Supabase auth API calls.
+ * This avoids storing real tokens (security risk + expiration) in scenario files.
  */
 async function handleAuth(auth: {
   email: string;
-  password: string;
+  password?: string;
 }): Promise<string> {
-  const { email, password } = auth;
+  const email = auth.email;
+  const password = auth.password || DEFAULT_AUTH_PASSWORD;
 
-  // Create user if they don't exist (auto-confirm email so sign-in works)
+  // Create user if they don't exist (auto-confirm email)
+  // We still need the auth.users row for PostgREST FK relationships.
   const { data: createData, error: createError } =
     await supabase.auth.admin.createUser({
       email,
@@ -162,72 +236,79 @@ async function handleAuth(auth: {
       email_confirm: true,
     });
 
+  let userId: string;
+
   if (createError) {
     if (createError.message.includes('already been registered')) {
-      // User exists — update their password so sign-in works even if the
-      // scenario specifies a different password than a previous run.
+      // User exists — look up their ID
       const { data: listData } = await supabase.auth.admin.listUsers();
       const existingUser = listData?.users?.find((u) => u.email === email);
       if (existingUser) {
-        await supabase.auth.admin.updateUserById(existingUser.id, {
-          password,
-        });
-        console.log(`  Updated password for existing user ${email}`);
+        userId = existingUser.id;
+        console.log(`  Found existing user ${email} (user: ${userId})`);
+      } else {
+        console.error(
+          `  User ${email} reported as registered but not found in listUsers`,
+        );
+        process.exit(1);
       }
     } else {
       console.error(`  Failed to create auth user: ${createError.message}`);
       process.exit(1);
     }
+  } else {
+    userId = createData!.user.id;
+    console.log(`  Created user ${email} (user: ${userId})`);
   }
 
-  // Sign in to get a valid session
-  // Use a separate client with the publishable/anon key for sign-in (if available)
-  const signInClient =
-    anonKey && anonKey !== secretKey
-      ? createClient(supabaseUrl!, anonKey, {
-          auth: { autoRefreshToken: false, persistSession: false },
-        })
-      : supabase;
-
-  const { data: signInData, error: signInError } =
-    await signInClient.auth.signInWithPassword({ email, password });
-
-  if (signInError || !signInData.session) {
-    console.error(
-      `  Failed to sign in as ${email}: ${signInError?.message || 'no session returned'}`,
-    );
-    process.exit(1);
-  }
-
-  const userId = signInData.user.id;
-  console.log(`  Signed in as ${email} (user: ${userId})`);
+  // Build synthetic JWT and mock responses — no real sign-in needed.
+  // The preload module intercepts server-side getUser() calls so Next.js
+  // middleware returns the mock user without hitting real Supabase.
+  const fakeJwt = buildFakeJwt(userId!, email);
+  const userResponse = buildUserResponse({ id: userId!, email });
 
-  // Write session cookies for the proxy to inject
   const projectRef = getProjectRef();
   const sessionOutput = {
     cookies: [
       {
         name: `sb-${projectRef}-auth-token`,
         value: JSON.stringify({
-          access_token: signInData.session.access_token,
-          refresh_token: signInData.session.refresh_token,
+          access_token: fakeJwt,
+          refresh_token: 'codeyam-mock-refresh-token',
           token_type: 'bearer',
-          expires_in: signInData.session.expires_in,
-          expires_at: signInData.session.expires_at,
+          expires_in: 315360000,
+          expires_at: 9999999999,
         }),
         path: '/',
         sameSite: 'Lax' as const,
       },
     ],
+    externalApis: {
+      [`${supabaseUrl}/auth/v1/user`]: {
+        body: userResponse,
+        status: 200,
+      },
+      [`${supabaseUrl}/auth/v1/token`]: {
+        body: {
+          access_token: fakeJwt,
+          token_type: 'bearer',
+          expires_in: 315360000,
+          expires_at: 9999999999,
+          refresh_token: 'codeyam-mock-refresh-token',
+          user: userResponse,
+        },
+        status: 200,
+      },
+    },
   };
 
   const outputDir = path.join(process.cwd(), '.codeyam', 'tmp');
   fs.mkdirSync(outputDir, { recursive: true });
   const outputPath = path.join(outputDir, 'seed-session.json');
   fs.writeFileSync(outputPath, JSON.stringify(sessionOutput, null, 2));
-  console.log(`  Session cookies written to ${outputPath}`);
+  console.log(`  Session cookies + auth mocks written to ${outputPath}`);
 
-  return userId;
+  return userId!;
 }
 
 /**
@@ -266,7 +347,7 @@ async function main() {
   // in seed data (e.g. for user_id foreign key columns with Supabase RLS)
   if (auth) {
     const userId = await handleAuth(
-      auth as { email: string; password: string },
+      auth as { email: string; password?: string },
     );
     seed = replaceAuthPlaceholders(seed, userId);
   }

package/codeyam-cli/templates/skills/codeyam-editor/SKILL.md

@@ -16,6 +16,15 @@ You MUST follow a step-by-step workflow driven by `codeyam editor` commands. Eac
 
 **The rule:** After completing what a command tells you to do, run the NEXT command it specifies. The commands are your instructions — follow them one at a time.
 
+## TASK Directive
+
+Some `codeyam editor N` commands output a `━━━ TASK ━━━` section with an `EXACT_TASK_TITLE:` line. When you see one:
+
+1. Delete ALL existing tasks: run TaskList, then run TaskUpdate with status "deleted" for every task returned
+2. Run TaskCreate with the EXACT title from the `EXACT_TASK_TITLE:` line — copy it character-for-character, do NOT paraphrase
+
+This ensures only one task is ever visible. Do NOT create tasks on your own. Only create them when a `━━━ TASK ━━━` directive tells you to.
+
 ## Migration Mode
 
 When `codeyam editor steps` shows **"Project Migration"** instead of "Feature Cycle", the project is being migrated from an existing codebase. Follow the `codeyam editor migrate` commands instead of the normal 13-step cycle.
@@ -117,6 +126,9 @@ This command gives you the post-change checklist (re-register scenarios, re-run
 ## Key Rules
 
 - **Run the commands** — they ARE your instructions, not suggestions
+- **One step at a time** — run each `codeyam editor N` command, read its FULL output, complete every checklist item, then advance. The CLI enforces a minimum time per step.
+- **NEVER batch-run steps** — `for step in 5 6 7 8; do codeyam editor $step; done` or piping to `head` defeats the entire workflow. Each step has unique instructions you must read and follow.
+- **NEVER delegate multiple steps to a subagent** — each step must be run, read, and completed in the main conversation. You MAY use subagents for parallelizable work _within_ a single step (e.g. extracting components + writing tests in step 5).
 - **Every feature gets scenarios** — this is the core value of CodeYam
 - **Always scaffold with a database** (Prisma + SQLite)
 - **Build real API routes** — the proxy handles scenario data transparently
@@ -163,6 +175,21 @@ Isolation routes are committed to git (not gitignored). They are protected by a
 
 When a collaborator clones the repo and runs `codeyam editor`, scenarios are auto-imported from `scenarios-manifest.json`. Run `codeyam editor sync` to manually re-sync after pulling new changes.
 
+## Expo / React Native Projects
+
+When working with an Expo project (tech stack `expo-react-native`):
+
+- Use `<View>`, `<Text>`, `<ScrollView>`, `<Pressable>` from `react-native` — **never use HTML elements** (`<div>`, `<span>`, `<h1>`, etc.)
+- Do NOT use `'use client'` — this is a Next.js directive that has no meaning in Expo
+- Do NOT import from `next/navigation`, `next/router`, or any `next/*` package
+- Use `expo-router` for navigation: `useRouter()`, `useLocalSearchParams()`, `<Link>`
+- Use `@/lib/theme` for all design tokens — not CSS custom properties (`var(--token)` does not work in React Native)
+- AsyncStorage maps to localStorage on web — CodeYam's `localStorage` injection in scenarios works automatically
+- Test with `npx jest`, not `npx vitest`
+- Isolation routes use Expo Router: `app/isolated-components/ComponentName.tsx` (not a `/page.tsx` subdirectory)
+- Capture wrappers use `nativeID="codeyam-capture"` (not `id="codeyam-capture"`) — `nativeID` maps to `id` on web
+- The preview renders via react-native-web in a browser — some visual differences from native devices are expected (fonts, SafeAreaView, shadows). See `MOBILE_SETUP.md` for details.
+
 ## Quick Reference
 
 ```bash
@@ -176,7 +203,13 @@ codeyam editor register '{"name":"Full Catalog","type":"application","url":"/","
 # Register app scenario with localStorage (for apps using client-side storage instead of a database)
 codeyam editor register '{"name":"Full Library","type":"application","url":"/","dimensions":["<name from screenSizes>"],"localStorage":{"articles":[...],"collections":[...]}}'
 
-# For large seed/localStorage data, write JSON to a temp file and use @ prefix:
+# BULK REGISTRATION (preferred — register all scenarios at once):
+# Write an array of scenarios to a temp file, then register with @ prefix.
+# This is faster and avoids repeated screenshot capture overhead.
+# File format: [{"name":"...","type":"...","url":"...","seed":{...}}, ...]
+codeyam editor register @.codeyam/tmp/scenarios.json
+
+# Single scenario from file (for large seed/localStorage data):
 codeyam editor register @/tmp/scenario-data.json
 
 # Journal entry (one per feature, references scenario names)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codeyam/codeyam-cli",
-  "version": "0.1.0-staging.b8b17a5",
+  "version": "0.1.0-staging.b8ee127",
   "description": "Local development CLI for CodeYam analysis",
   "type": "module",
   "bin": {