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

package/codeyam-cli/templates/rules-instructions.md

@@ -0,0 +1,78 @@
+# Claude Rules Guide
+
+Rules provide context-specific guidance when working in files matching their `paths` patterns.
+
+## Core Principles
+
+1. **One concept per rule** — If you're documenting two unrelated things, create two rules.
+2. **Paths must match content scope** — A rule about one file should have that file in `paths`, not a broad `**/*.ts` pattern.
+3. **Keep rules SHORT** — Most rules should be **1-4 bullets**. Only complex multi-file architectures should exceed ~10 lines.
+
+**Example** — a typical rule:
+
+```markdown
+---
+paths:
+  - 'packages/ai/src/lib/generateMockData.ts'
+---
+
+# Mock Data Generation
+
+- Entry point: `generateMockData()` in `generateMockData.ts`
+- Uses `convertDotNotation` to transform flat schema into nested objects
+- Schema entry ORDER matters — `key[]` must come before `key[].property` or arrays get overwritten
+- Test with exact ordering from database, not just same entries
+```
+
+## When to Create a Rule
+
+Create a rule when you learn something that **reading the code alone wouldn't reveal**:
+
+- Non-obvious gotchas or behavior that caused real confusion or bugs
+- Architecture, file relationships, or data flows that take time to piece together
+- Debugging strategies for a tricky area of the codebase
+- Preferred commands or workflows when multiple options exist (e.g. "Use `pnpm test` to run tests")
+- User corrections or explanations that aren't captured in the code itself
+
+**Skip** rules that restate what the code says — function signatures, type definitions, "this module handles X." Claude can read the code.
+
+## Frontmatter & Paths
+
+Every rule needs a `paths` frontmatter field. Be specific to avoid loading rules unnecessarily:
+
+```yaml
+---
+paths:
+  - 'specific/path/to/file.ts'
+  - 'another/specific/path/*.ts'
+---
+```
+
+| Content Scope | Path Pattern            | Example                                        |
+| ------------- | ----------------------- | ---------------------------------------------- |
+| Single file   | `'path/to/file.ts'`     | Rule about `processExpression.ts` specifically |
+| Related files | `'path/to/feature*.ts'` | Rule about `generateExecutionFlows*.ts` files  |
+| Directory     | `'path/to/dir/**/*.ts'` | Rule about the queue system in `utils/queue/`  |
+| Cross-cutting | Multiple specific paths | Testing rule spanning test configs and tests   |
+
+Audit dates live in `.claude/codeyam-rule-state.json` (managed by `codeyam memory touch`). Keep frontmatter limited to `paths`.
+
+## File Placement
+
+Rules must be written to `.claude/rules/`, NOT `.codeyam/rules/`. The instructions file lives in `.codeyam/` but actual rule files go in `.claude/rules/`.
+
+Use `codeyam memory rule-path` to compute the correct directory from your frontmatter paths:
+
+```
+$ codeyam memory rule-path packages/ai/src/lib/foo.ts packages/ai/src/utils/bar.ts
+{"result":".claude/rules/packages/ai/src/"}
+```
+
+The command computes the deepest common directory shared by all paths and returns the `.claude/rules/` subdirectory where the rule file should live. Reserve the top level of `.claude/rules/` for rules whose paths genuinely span the entire repo.
+
+## Content Guidelines
+
+- **Be actionable** — "Run `pnpm test:api` for API tests" not "Make sure to run the appropriate tests"
+- **Focus on why, not what** — Gotchas, non-obvious behavior, architectural decisions. The code already shows "what."
+- **Point to specifics** — "Auth tokens are stored in httpOnly cookies via `src/auth/cookies.ts`" beats a vague description.
+- **Be short!** - Context window space is precious! Do not ramble, use bullets, focus on providing clear actionable information.

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

@@ -0,0 +1,282 @@
+/**
+ * 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 * 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';
+  }
+}
+
+async function seedTables(seed: Record<string, unknown[]>) {
+  const tableNames = Object.keys(seed);
+  if (tableNames.length === 0) return;
+
+  console.log(`Seeding tables: ${tableNames.join(', ')}`);
+
+  // Wipe tables in reverse order (to respect foreign keys)
+  for (const table of [...tableNames].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
+  for (const [table, rows] of Object.entries(seed)) {
+    if (!Array.isArray(rows) || rows.length === 0) continue;
+    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}`);
+  }
+}
+
+/**
+ * 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})`);
+
+  // 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,
+          token_type: 'bearer',
+          expires_in: signInData.session.expires_in,
+          expires_at: signInData.session.expires_at,
+        }),
+        path: '/',
+        sameSite: 'Lax' as const,
+      },
+    ],
+  };
+
+  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}`);
+
+  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/{codeyam-debug-skill.md → skills/codeyam-debug/SKILL.md}

@@ -1,5 +1,5 @@
 ---
-name: CodeYam Debug
+name: codeyam-debug
 autoApprove: true
 description: |
   Use this skill when entity analysis or capture fails with errors.
@@ -37,6 +37,49 @@ The `codeyam init` command has already auto-approved:
 
 You can freely work with logs and update configuration without asking for permission.
 
+## Important: File Locations
+
+Understanding where files live is critical for debugging:
+
+| What                | Location                                               | Notes                                                                                                         |
+| ------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
+| **Database**        | `.codeyam/db.sqlite3`                                  | In the **original project directory** (where you ran `codeyam init`). Contains entities, analyses, scenarios. |
+| **Config**          | `.codeyam/config.json`                                 | In the **original project directory**. Universal mocks go here.                                               |
+| **LLM Calls**       | `.codeyam/llm-calls/`                                  | In the **original project directory**. JSON files recording LLM inputs/outputs for each analysis.             |
+| **Logs**            | `/tmp/codeyam/local-dev/{projectSlug}/codeyam/log.txt` | In the temp folder. Analysis and capture logs.                                                                |
+| **Generated files** | `/tmp/codeyam/local-dev/{projectSlug}/project/`        | A **copy** of your project with mock injections.                                                              |
+| **Analyzer**        | `/tmp/codeyam/local-dev/{projectSlug}/codeyam/`        | The analysis engine runtime.                                                                                  |
+
+**Common mistake:** Looking for the database in `/tmp/codeyam/local-dev/{projectSlug}/project/.codeyam/db.sqlite3` - this is a **copy** and may be empty or stale. Always query the database in the **original project directory**.
+
+### Debugging with LLM Calls
+
+The `.codeyam/llm-calls/` directory contains JSON files recording every LLM interaction during analysis. Examining these is often key to understanding why analysis produced unexpected results:
+
+```bash
+# List recent LLM calls
+ls -lt .codeyam/llm-calls/ | head -10
+
+# View a specific call (shows both the prompt sent and response received)
+cat .codeyam/llm-calls/{filename}.json | jq .
+```
+
+**What to look for:**
+
+- **Input context**: Was the right code/context sent to the LLM?
+- **Response parsing**: Did the LLM return valid JSON? Were fields missing or malformed?
+- **Scenario generation**: For scenario issues, check if the LLM generated the expected data structures
+
+**Example database query:**
+
+```bash
+# CORRECT - query the original project database
+sqlite3 /path/to/your/project/.codeyam/db.sqlite3 "SELECT id, entityName FROM analyses LIMIT 5"
+
+# WRONG - the temp copy doesn't have the real data
+sqlite3 /tmp/codeyam/local-dev/{projectSlug}/project/.codeyam/db.sqlite3 "..."
+```
+
 ## Debugging Workflow
 
 ### Step 1: Read the Error Log
@@ -44,8 +87,8 @@ You can freely work with logs and update configuration without asking for permis
 The simulation log contains all error details:
 
 ```bash
-# For local development
-tail -n 100 /tmp/codeyam/local-dev/{projectSlug}/log.txt
+# For local development (note the /codeyam/ folder in the path)
+tail -n 100 /tmp/codeyam/local-dev/{projectSlug}/codeyam/log.txt
 ```
 
 Look for:
@@ -92,7 +135,8 @@ Cannot destructure property 'entities' of 'useLoaderData()' as it is null
 This is a **SCENARIO MOCK ISSUE**, not a universal mock issue. Follow these steps:
 
 1. **Check the analysis metadata** for `scenariosDataStructure`:
-   - Query the database or check analysis records
+   - Query the database **in the original project directory** (`.codeyam/db.sqlite3`)
+   - Example: `sqlite3 .codeyam/db.sqlite3 "SELECT json_extract(analysis, '$.scenariosDataStructure') FROM analyses WHERE entityName='MyEntity'"`
    - Look for the `dataForMocks` property
    - This shows what data the analysis engine expected to mock
 

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

@@ -0,0 +1,237 @@
+---
+name: codeyam-dev-mode
+autoApprove: true
+description: |
+  Use this skill when working in CodeYam Dev Mode — an interactive environment for iterating on
+  components and scenarios with a live preview panel alongside a Claude Code terminal.
+  Use when: The embedded terminal in Dev Mode auto-invokes this skill to provide entity/scenario context.
+---
+
+# CodeYam Dev Mode
+
+You are working inside CodeYam Dev Mode — a split-screen environment with this Claude Code terminal on the left and a live preview on the right.
+
+## Step 1: Read Session Context
+
+Read the dev mode context file to understand the current entity and scenario:
+
+```
+cat .codeyam/dev-mode-context.md
+```
+
+The context file contains all the specific paths you need — source file, mock data, dev server project, and **server log**. All paths are fully resolved; no placeholders to fill in.
+
+## Step 2: Gather Context While Server Sets Up
+
+The dev server needs time to set up the sandboxed project (copying files, installing deps, starting Vite). The mock data files in the tmp project **do not exist yet** when you first start. Use this time productively.
+
+**Do these in parallel:**
+
+1. **Read the source file** from the real repo (exists immediately).
+
+2. **Query the database** for all scenarios belonging to this entity's analysis. Use the **Analysis ID** from the context file:
+
+   ```
+   sqlite3 .codeyam/db.sqlite3 "SELECT name, description FROM scenarios WHERE analysis_id = '<ANALYSIS_ID>'"
+   ```
+
+   Each scenario's `description` explains what data shape it tests — e.g. "empty list", "many items", "error state". This tells you what data attributes matter most for the component's visual states.
+
+3. **Monitor the server log** listed in the context file under **Server log**:
+
+   ```
+   tail -f <server log path from context file>
+   ```
+
+   Wait until you see a local URL like `http://localhost:...` indicating the Vite server has started. Do NOT try to read mock data or other files from the tmp project until the logs confirm setup is complete.
+
+## Step 3: Read Mock Data and Present Overview
+
+Once the dev server is ready, read the **mock data file** from the tmp project path listed in the context file.
+
+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?". 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.
+
+## How Dev Mode Works
+
+**Layout:**
+
+- **Left panel** — This Claude Code terminal (you)
+- **Right panel** — Live preview iframe showing the rendered component/scenario
+
+**Architecture:**
+
+- The preview runs from a sandboxed project at the tmp path listed in the context file
+- Source code edits in the real repo auto-sync to the preview via HMR (hot module replacement)
+- Mock data files live in the tmp project under `__codeyamMocks__/`
+
+**What you can edit:**
+
+- **Source code** (the entity's file in the real repo) — edits sync automatically to the preview
+- **Mock data** (the `MockData_*.tsx` file in the tmp project) — edits also sync via HMR
+- Both types of edits show up in the preview almost instantly
+
+**CRITICAL — What you must NEVER edit for functional changes:**
+
+- **Shimmed component files** (`*_Scenario.tsx` in the tmp project) — these are auto-generated files that wire up the component with mocked dependencies. **NEVER modify these to change what renders.** Any functional changes you make here:
+  - Will be lost when the scenario is recaptured or regenerated
+  - Cannot be saved as a scenario (only mock data is persisted to the database)
+  - Break the ability to reproduce the scenario in the future
+- To change what the component displays, **always edit the `MockData_*.tsx` file**. The shimmed component reads mock data via `scenarios().data()` — that's the mechanism for controlling component behavior and visual state.
+- The ONLY acceptable edit to a shimmed component file is adding temporary `console.log` statements for debugging (see Client-Side Logging below). Never change imports, state initialization, hooks, memos, or rendering logic.
+
+## Workflow
+
+1. Read the context file (`.codeyam/dev-mode-context.md`)
+2. While dev server sets up, do in parallel:
+   - Read the source file (from real repo — available immediately)
+   - Query database for scenario names/descriptions (available immediately)
+   - Monitor server log until dev server is ready
+3. Read the mock data file (from tmp project — only after setup completes)
+4. Present concise overview: component summary + suggested untested scenarios
+5. Ask the user what they want to change
+6. Make incremental edits to **source code or mock data only** — the preview updates live
+7. After making changes, refresh the preview (curl command from context file)
+8. Iterate based on user feedback
+
+## Client-Side Logging (Required)
+
+**Always add `console.log` statements to trace the execution flow when making changes.** This is critical — you cannot see the preview, so logging is your only way to verify the component renders as expected.
+
+Client-side `console.log` and `console.error` calls are automatically captured by the `/api/client-log` endpoint and written to the server log file. This means you can add logging in component code and read it from the server log.
+
+**When to add logging:**
+
+- Before and after every change you make to the shimmed component or mock data
+- At key data flow checkpoints: after state initialization, after useMemo computations, before the render return
+- In useEffect callbacks to confirm they fire
+- Around conditional branches you're targeting (e.g. "this condition should now be true")
+
+**How to log:**
+
+Add `console.log` with a `[CY-DEBUG]` prefix in the shimmed component file (the `*_Default_Scenario.tsx` file in the tmp project). **This is the ONLY acceptable edit to shimmed component files — temporary debug logging. Never change the component's logic, imports, state, or rendering in these files.**
+
+```typescript
+// After state declarations:
+console.log(
+  '[CY-DEBUG] render: myState:',
+  myState?.length,
+  'otherData:',
+  otherData,
+);
+
+// Inside useEffect:
+useEffect(() => {
+  console.log('[CY-DEBUG] useEffect fired, setting data');
+  // ...
+}, []);
+
+// Before return:
+console.log(
+  '[CY-DEBUG] PRE-RENDER: showThumbnails:',
+  items?.length > 0,
+  'showLoader:',
+  !items,
+);
+```
+
+**After refreshing, always check the log** for your `[CY-DEBUG]` lines:
+
+```
+tail -30 <server log path from context file>
+```
+
+If you don't see your debug logs but see `[CLIENT CONSOLE.ERROR]` or `Application Error`, the component is crashing before your code runs. Read the error stack trace to find the failing component.
+
+**Keep logging in place** as you iterate — it costs nothing and saves significant debugging time.
+
+## Refreshing the Preview
+
+After making changes, refresh the live preview so it picks up your edits. The exact curl command is in the context file under **Server > Refresh preview** — copy and run it:
+
+```
+curl -s -X POST http://localhost:<port>/api/dev-mode-preview
+```
+
+**Always refresh after making changes.** This triggers the preview iframe to reload, **clears the server log file**, waits for the page to re-render, and then fetches the preview URL to check for SSR errors.
+
+**The response includes preview health info.** Check the `preview` field in the JSON response:
+
+```json
+{
+  "success": true,
+  "sessionsNotified": 1,
+  "logCleared": true,
+  "preview": {
+    "status": 200,
+    "healthy": true
+  }
+}
+```
+
+If the preview is unhealthy (e.g., SSR error caught by an error boundary), the response will include the error:
+
+```json
+{
+  "preview": {
+    "status": 500,
+    "healthy": false,
+    "error": "ReferenceError: myVariable is not defined\n    at Component (/path/to/file.tsx:42:5)"
+  }
+}
+```
+
+**After every refresh:**
+
+1. **Check `preview.healthy`** in the JSON response. If `false`, the `error` field contains the SSR error — fix it before proceeding.
+2. **Check the log** for your `[CY-DEBUG]` lines to confirm the execution path:
+
+```
+tail -30 <server log path from context file>
+```
+
+If the preview was unhealthy, the log will also contain `[DEV-MODE-CHECK]` lines with the error details.
+
+Look for your `[CY-DEBUG]` lines to confirm the execution path. If you see errors instead, the component is crashing. If you see nothing, the page may still be loading — wait a moment and check again.
+
+## Debugging with Server Logs
+
+The **Server log** path in the context file captures all output from the dev server process — Vite compilation errors, SSR errors, HMR updates, and runtime warnings. **Client-side errors** (React rendering errors, unhandled exceptions, console.error calls) are also automatically reported to this log via the `/api/client-log` endpoint. This means both server and client errors appear in the same log file.
+
+Since the log is **cleared on every refresh**, you always see fresh output. No need to scroll past old errors.
+
+**When to check the server log:**
+
+- **After every refresh** — always verify your debug logs appear and no errors are present
+- The preview shows a blank page, error boundary, or 500 error
+- HMR updates aren't taking effect after edits
+- The preview is stuck loading or shows unexpected content
+
+**How to check:**
+
+```
+tail -50 <server log path from context file>
+```
+
+**What to look for:**
+
+- `[CY-DEBUG]` — your trace logs confirming the execution path and data values
+- `[CLIENT CONSOLE.ERROR]` — client-side React errors or unhandled exceptions
+- `[vite]` error messages — TypeScript compilation failures
+- `Application Error` — React error boundary activated (component crashed during render)
+- No output at all — the page hasn't loaded yet, or the component never rendered
+
+## 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.
+- **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
+- If the preview breaks, check the server log (path in context file) for compilation or runtime errors
+- You can also modify other files in the repo that the entity imports — those changes sync too