@codeyam/codeyam-cli 0.1.0-staging.b8f4f94 → 0.1.0-staging.ba3f279

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

@@ -0,0 +1,374 @@
+/**
+ * CodeYam Seed Adapter for Supabase.
+ *
+ * Seeds the database and optionally signs in a user for authenticated scenarios.
+ *
+ * Usage: npx tsx .codeyam/seed-adapter.ts <path-to-seed-data.json>
+ *
+ * Input JSON format:
+ * {
+ *   "tableName": [{ "column": "value", ... }, ...],
+ *   "_auth": {                          // optional
+ *     "email": "alice@example.com",
+ *     "password": "test123"
+ *   }
+ * }
+ *
+ * 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
+ *    so the CodeYam proxy can inject them into the browser
+ *
+ * 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
+ *
+ * The adapter scans ALL env vars by value pattern — no specific naming required.
+ */
+
+import { createClient } from '@supabase/supabase-js';
+import { Prisma } from '@prisma/client';
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Scan all env vars for values matching a pattern.
+ * Returns ALL unique matches (not just the first) so callers can disambiguate.
+ */
+function findAllEnvByPattern(pattern: RegExp): string[] {
+  const matches = new Set<string>();
+  for (const value of Object.values(process.env)) {
+    if (value && pattern.test(value)) matches.add(value);
+  }
+  return [...matches];
+}
+
+/**
+ * For legacy Supabase JWTs, decode the payload to check the `role` claim.
+ * Returns the role string ("service_role", "anon", etc.) or undefined.
+ */
+function getJwtRole(jwt: string): string | undefined {
+  try {
+    const payload = jwt.split('.')[1];
+    const decoded = JSON.parse(Buffer.from(payload, 'base64url').toString());
+    return decoded.role;
+  } catch {
+    return undefined;
+  }
+}
+
+// Detect Supabase credentials by value pattern, not env var name.
+// This works regardless of what the user named their env vars.
+const supabaseUrl = findAllEnvByPattern(
+  /^https:\/\/[a-z0-9]+\.supabase\.co\b/,
+)[0];
+
+// 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(
+  /^eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/,
+);
+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(
+    'Could not find Supabase credentials in environment variables.',
+  );
+  console.error(
+    'Looking for: a URL matching https://<ref>.supabase.co and a key starting with sb_secret_ (or a service_role JWT)',
+  );
+  console.error(
+    'Add them to .env.local — the seed adapter scans all env vars by value pattern.',
+  );
+  process.exit(1);
+}
+
+// Admin client for user management (uses secret key to bypass RLS)
+const supabase = createClient(supabaseUrl, secretKey, {
+  auth: { autoRefreshToken: false, persistSession: false },
+});
+
+// Derive the project ref from the URL for cookie naming
+// e.g. "https://abcdefgh.supabase.co" → "abcdefgh"
+function getProjectRef(): string {
+  try {
+    const hostname = new URL(supabaseUrl!).hostname;
+    return hostname.split('.')[0];
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * 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[]>) {
+  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(
+    `Clearing ${allTables.length} tables, seeding: ${Object.keys(seed).join(', ')}`,
+  );
+
+  // 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
+        .from(table)
+        .delete()
+        .not('id', 'is', null);
+      if (error2) {
+        console.warn(`  Could not clear ${table}: ${error2.message}`);
+      } else {
+        console.log(`  Cleared ${table}`);
+      }
+    } else {
+      console.log(`  Cleared ${table}`);
+    }
+  }
+
+  // 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}`);
+      process.exit(1);
+    }
+    console.log(`  Seeded ${rows.length} rows into ${table}`);
+  }
+}
+
+/**
+ * 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(),
+  };
+}
+
+/**
+ * Handle auth: create user, sign in, write session cookies.
+ * Returns the user ID so callers can replace __AUTH_USER_ID__ placeholders in seed data.
+ */
+async function handleAuth(auth: {
+  email: string;
+  password: string;
+}): Promise<string> {
+  const { email, password } = auth;
+
+  // Create user if they don't exist (auto-confirm email so sign-in works)
+  const { data: createData, error: createError } =
+    await supabase.auth.admin.createUser({
+      email,
+      password,
+      email_confirm: true,
+    });
+
+  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.
+      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}`);
+      }
+    } else {
+      console.error(`  Failed to create auth user: ${createError.message}`);
+      process.exit(1);
+    }
+  }
+
+  // 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})`);
+
+  // Use the REAL JWT from Supabase sign-in for the session cookie so auth
+  // works immediately against the real Supabase API. The externalApis below
+  // provide a fallback for when the CLI supports preload-based auth
+  // interception (no real Supabase calls needed at render time).
+  const fakeJwt = buildFakeJwt(userId, email);
+  const userResponse = buildUserResponse(signInData.user);
+
+  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,
+          token_type: 'bearer',
+          expires_in: signInData.session.expires_in,
+          expires_at: signInData.session.expires_at,
+        }),
+        path: '/',
+        sameSite: 'Lax' as const,
+      },
+    ],
+    // External API mocks — when the CLI supports propagating these, the
+    // preload module will intercept server-side getUser() calls so Next.js
+    // middleware returns the mock user without hitting real Supabase.
+    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 + auth mocks written to ${outputPath}`);
+
+  return userId;
+}
+
+/**
+ * Replace __AUTH_USER_ID__ placeholders in seed data with the actual Supabase user ID.
+ * This lets scenarios reference the authenticated user in foreign key columns (e.g. user_id)
+ * without knowing the UUID ahead of time.
+ */
+function replaceAuthPlaceholders(
+  seed: Record<string, unknown[]>,
+  userId: string,
+): Record<string, unknown[]> {
+  const json = JSON.stringify(seed);
+  const replaced = json.replace(/__AUTH_USER_ID__/g, userId);
+  return JSON.parse(replaced);
+}
+
+async function main() {
+  const seedDataPath = process.argv[2];
+  if (!seedDataPath) {
+    console.error('Usage: npx tsx .codeyam/seed-adapter.ts <seed-data.json>');
+    process.exit(1);
+  }
+
+  const raw = fs.readFileSync(seedDataPath, 'utf-8');
+  const data = JSON.parse(raw);
+
+  // Separate auth config from table data
+  const auth = data._auth;
+  let seed: Record<string, unknown[]> = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (key === '_auth') continue;
+    seed[key] = value as unknown[];
+  }
+
+  // Auth first: we need the user ID to replace __AUTH_USER_ID__ placeholders
+  // 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 },
+    );
+    seed = replaceAuthPlaceholders(seed, userId);
+  }
+
+  await seedTables(seed);
+
+  console.log('Seed complete');
+}
+
+main().catch((e) => {
+  console.error('Seed adapter error:', e);
+  process.exit(1);
+});

package/codeyam-cli/templates/skills/codeyam-dev-mode/SKILL.md

@@ -53,7 +53,7 @@ Then present a **concise** overview to the user:
 
 1. **Component Summary** — 2-3 sentences on what the component does and the current scenario being previewed.
 
-2. **Suggested Tests** — Compare the component's code paths (conditionals, edge cases, visual states) against the existing scenarios from the database. Recommend 2-4 specific ways to test the component that are **not yet covered** by saved scenarios. Focus on interesting visual states — e.g. "What does this look like with a very long title?", "What happens when the list is empty?", "How does the error state render?". Be specific to this component, not generic.
+2. **Suggested Tests** — Compare the component's code paths (conditionals, edge cases, visual states) against the existing scenarios from the database. Recommend 2-4 specific ways to test the component that are **not yet covered** by saved scenarios. Focus on interesting visual states — e.g. "What does this look like with a very long title?", "What happens when the list is empty?", "How does the error state render?". Also suggest ways to enrich the _existing_ scenario's data to better exercise the component (more realistic content, populated optional fields, diverse values). Be specific to this component, not generic.
 
 Keep it brief — no tables, no exhaustive attribute lists. The user can see the preview and wants actionable suggestions, not a data dump.
 
@@ -229,7 +229,7 @@ tail -50 <server log path from context file>
 ## Tips
 
 - **NEVER modify shimmed component files** (`*_Scenario.tsx`) to change rendering behavior — only edit `MockData_*.tsx` files to change what the component displays. Shimmed components are auto-generated; functional changes to them won't persist and can't be saved as scenarios.
-- Keep edits small and incremental so the user can see changes in the preview as you go
+- **Refresh the preview frequently** — the user is watching the preview panel as you work. Make small changes, then refresh so they see visual progress. Don't batch multiple edits into one big refresh at the end. Aim for a refresh after every meaningful edit (new data values, layout changes, style tweaks).
 - **Always add `[CY-DEBUG]` logging before refreshing** — never refresh without a way to verify the result
 - Mock data files are TypeScript (`.tsx`) — they export scenario-specific props/data
 - The database at `.codeyam/db.sqlite3` has entity and scenario metadata if you need deeper investigation

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

@@ -16,6 +16,77 @@ 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.
+
+Migration uses a different command set:
+
+```
+codeyam editor migrate        → Survey the project (explore pages, confirm order)
+codeyam editor migrate 1-8    → Run migration step N for the current page
+codeyam editor migrate next   → Advance to the next page
+codeyam editor migrate status → Show migration progress
+```
+
+**The same rule applies:** run the command shown in the output, follow its checklist, then run the next command it specifies. Migration steps are 1-8 per page: Capture → Preview → Discuss → Decompose → Extract → Recapture → Journal → Present. Steps 4-6 (Decompose/Extract/Recapture) are optional — the user decides at step 3 whether to decompose or skip to step 7. After all pages are migrated, the project transitions to the normal feature cycle.
+
+**IMPORTANT:** When `codeyam editor steps` tells you to run a `codeyam editor migrate` command, run THAT command — do NOT run `codeyam editor 1` or any other normal step command.
+
+### Migration Survey (codeyam editor migrate)
+
+When you run `codeyam editor migrate` with no arguments and no existing migration state, follow this survey checklist:
+
+1. Read `package.json` — understand the framework, dependencies, and scripts
+2. Explore the project structure — find all page/route files
+   - Next.js App Router: `app/**/page.tsx` | Pages Router: `pages/**/*.tsx`
+   - Check for other patterns: `src/` directory, custom routing, etc.
+3. Read each page/route to assess complexity and data flow
+4. Identify how the dev server starts (check `scripts` in package.json)
+5. Note any environment variables, databases, or external services needed
+6. Present a numbered list of all pages with:
+   - Page name and route
+   - File path
+   - Complexity assessment (simple / moderate / complex)
+7. Suggest a migration order — **start with the most complex pages** (dashboards, analytics, etc.) as they best demonstrate CodeYam's value and have rich decomposition opportunities
+8. Wait for user confirmation of the order
+
+**After user confirms**, write `.codeyam/migration-state.json`:
+
+```json
+{
+  "status": "surveyed",
+  "startedAt": "<ISO>",
+  "completedAt": null,
+  "pages": [
+    {
+      "name": "Home",
+      "route": "/",
+      "filePath": "app/page.tsx",
+      "status": "pending",
+      "startedAt": null,
+      "completedAt": null,
+      "extractedComponents": [],
+      "extractedFunctions": [],
+      "scenarioCount": 0
+    }
+  ],
+  "currentPageIndex": 0,
+  "sharedComponents": []
+}
+```
+
+Then run: `codeyam editor migrate 1`
+
 ## The Cycle
 
 Every feature follows 13 gated steps:
@@ -41,34 +112,133 @@ codeyam editor 13   → Present summary, get final approval
 
 ## Handling User Feedback / Changes
 
-When the user asks for changes — whether through the menu, a direct request, or even a question that implies a change (e.g., "Can the cards have images?") — you MUST run `codeyam editor change` **before** writing any code. This command gives you the post-change checklist (re-register scenarios, re-run tests, update journal, etc.). Never make changes without running the change workflow first.
+When the user asks for changes — whether through the menu, a direct request, or even a question that implies a change (e.g., "Can the cards have images?") — you MUST run `codeyam editor change` **before** making any modifications. This includes:
+
+- Code changes (components, routes, lib functions, styles)
+- Scenario data updates (seed data, localStorage data, mock data)
+- Style adjustments (CSS, Tailwind classes, layout tweaks)
+- Even small fixes (typos, color tweaks, spacing)
+
+This command gives you the post-change checklist (re-register scenarios, re-run tests, update journal, etc.). Never make changes without running the change workflow first.
+
+**CRITICAL:** The change workflow MUST end with `codeyam editor 13`, which shows Working Session Results to the user. Skipping this step is a broken experience — the user will not see what changed and cannot approve or request further changes. Every change, no matter how small, must conclude with results being shown.
 
 ## 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
 - **Start the dev server via the CodeYam API** — it handles proxy setup automatically
-- **Verify the preview after changes** — check the dev server URL, not the proxy
+- **Keep the preview moving** — the user watches the preview panel as you work. Refresh it frequently so they see progress, not a static screen. See below.
+
+## Keep the Preview Moving
+
+The user is watching the live preview panel while you work. A static preview makes it feel like nothing is happening. **Refresh the preview after every meaningful change** — not just at the end of a step.
+
+**During prototyping (step 2):**
+
+- Refresh after creating the first visible page, even if it's bare
+- Refresh after adding each major UI section (header, list, form, etc.)
+- Refresh after seeding data so the user sees real content appear
+- Refresh after styling changes so the user sees the visual progress
+
+**During extraction (step 5):**
+
+- Refresh after extracting each batch of components to confirm nothing broke
+
+**During changes:**
+
+- Refresh after each individual change, not after all changes are done
+
+**How to refresh:**
+
+```
+codeyam editor preview '{"dimension":"<name from screenSizes>"}'
+```
+
+Navigate to a specific path or switch scenario:
+
+```
+codeyam editor preview '{"path":"/drinks/1","dimension":"<name from screenSizes>"}'
+codeyam editor preview '{"scenarioId":"abc-123"}'
+```
+
+The goal: the user should see the preview update 4-8+ times during a typical building session, not just once at the end.
+
+## Collaboration
+
+Isolation routes are committed to git (not gitignored). They are protected by a layout guard at `app/isolated-components/layout.tsx` that returns `notFound()` in production, so they are safe to commit. Scenarios, screenshots, journal entries, and the glossary are also committed. Only the local database and secrets are gitignored.
+
+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
-# Register scenario (auto-captures screenshot)
-curl -s -X POST http://localhost:${CODEYAM_PORT:-3111}/api/editor-register-scenario \
-  -H 'Content-Type: application/json' \
-  -d '{"name":"...","description":"...","mockData":{"routes":{"/api/...":{"body":[...]}}}}'
+# Register component scenario (auto-captures screenshot)
+# ALWAYS include "dimensions" — use the project's default screen size name from setup
+codeyam editor register '{"name":"DrinkCard - Default","componentName":"DrinkCard","componentPath":"app/components/DrinkCard.tsx","url":"/isolated-components/DrinkCard?s=Default","dimensions":["<name from screenSizes>"],"mockData":{"routes":{"/api/...":{"body":[...]}}}}'
+
+# Register app scenario with seed data (ALWAYS include "url" and "dimensions")
+codeyam editor register '{"name":"Full Catalog","type":"application","url":"/","dimensions":["<name from screenSizes>"],"seed":{"drinks":[...]}}'
+
+# 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":[...]}}'
+
+# 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)
-curl -s -X POST http://localhost:${CODEYAM_PORT:-3111}/api/editor-journal-entry \
-  -H 'Content-Type: application/json' \
-  -d '{"title":"...","type":"feature","description":"...","scenarios":["..."]}'
+codeyam editor journal '{"title":"...","type":"feature","description":"..."}'
 
-# Refresh preview
-curl -s -X POST http://localhost:${CODEYAM_PORT:-3111}/api/dev-mode-preview
+# Update journal with commit info
+codeyam editor journal-update '{"time":"...","commitSha":"...","commitMessage":"..."}'
+
+# Refresh preview / navigate / switch scenario (ALWAYS include "dimension")
+codeyam editor preview '{"dimension":"<name from screenSizes>"}'
+codeyam editor preview '{"path":"/drinks/1","dimension":"<name from screenSizes>"}'
+codeyam editor preview '{"scenarioId":"abc-123"}'
+
+# Show/hide results panel
+codeyam editor show-results
+codeyam editor hide-results
+
+# Commit feature
+codeyam editor commit '{"message":"feat: Add drinks page"}'
 
 # Restart dev server (only for config/dependency changes)
-curl -s -X POST http://localhost:${CODEYAM_PORT:-3111}/api/editor-dev-server \
-  -H 'Content-Type: application/json' -d '{"action":"restart"}'
+codeyam editor dev-server '{"action":"restart"}'
+
+# Check for client-side errors
+codeyam editor client-errors
+
+# Verify all images load (extracts URLs from pages, HTTP-checks each one)
+codeyam editor verify-images '{"paths":["/","/drinks/1"]}'
+
+# Sync scenarios from manifest (after pulling collaborator changes)
+codeyam editor sync
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codeyam/codeyam-cli",
-  "version": "0.1.0-staging.b8f4f94",
+  "version": "0.1.0-staging.ba3f279",
   "description": "Local development CLI for CodeYam analysis",
   "type": "module",
   "bin": {
@@ -46,6 +46,7 @@
     "p-queue": "^9.1.0",
     "p-retry": "^7.1.1",
     "pg": "^8.19.0",
+    "posthog-node": "^4.0.0",
     "piscina": "^5.1.4",
     "pixelmatch": "^5.3.0",
     "playwright": "1.58.0",
@@ -61,6 +62,11 @@
     "node-pty": "^1.0.0",
     "sharp": "^0.34.5",
     "ws": "^8.18.3",
+    "@xterm/xterm": "^6.0.0",
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/addon-web-links": "^0.11.0",
+    "@xterm/addon-webgl": "^0.18.0",
+    "@xterm/addon-canvas": "^0.7.0",
     "simple-git": "^3.32.2",
     "typescript": "^5.9.3",
     "uuid": "^11.1.0",