@codeyam/codeyam-cli 0.1.0-staging.036391e → 0.1.0-staging.039fa00

package/codeyam-cli/templates/rule-reflection-hook.py

@@ -120,6 +120,51 @@ def read_rule_content(rule_name):
     return text
 
 
+def get_project_slug():
+    """
+    Derive project slug from .codeyam/config.json (matching getProjectSlug() on the TS side).
+    Falls back to os.path.basename(project_dir) if config is absent or malformed.
+    """
+    project_dir = os.environ.get('CLAUDE_PROJECT_DIR', os.getcwd())
+    try:
+        config_path = os.path.join(project_dir, '.codeyam', 'config.json')
+        with open(config_path, 'r') as f:
+            config = json.load(f)
+        slug = config.get('projectSlug', '')
+        if slug:
+            return slug
+    except (IOError, json.JSONDecodeError, KeyError):
+        pass
+    return os.path.basename(project_dir)
+
+
+def load_memory_settings():
+    """
+    Load memory settings from .codeyam/config.json.
+    Returns dict with safe defaults when absent or malformed.
+    """
+    defaults = {
+        'conversationReflection': True,
+        'ruleMaintenance': True,
+        'promptModel': 'haiku',
+    }
+    try:
+        project_dir = os.environ.get('CLAUDE_PROJECT_DIR', os.getcwd())
+        config_path = os.path.join(project_dir, '.codeyam', 'config.json')
+        with open(config_path, 'r') as f:
+            config = json.load(f)
+        memory = config.get('memory', {})
+        if not isinstance(memory, dict):
+            return defaults
+        return {
+            'conversationReflection': memory.get('conversationReflection', True),
+            'ruleMaintenance': memory.get('ruleMaintenance', True),
+            'promptModel': memory.get('promptModel', 'haiku'),
+        }
+    except (IOError, json.JSONDecodeError, KeyError):
+        return defaults
+
+
 def get_stale_rules():
     """
     Run `codeyam memory status` and parse the output to find stale rules.
@@ -157,8 +202,8 @@ def get_stale_rules():
                 # Look for the next few lines for details
                 for j in range(i + 1, min(i + 4, len(lines))):
                     detail = lines[j].strip()
-                    if detail.startswith('Rule timestamp:'):
-                        rule_info['rule_timestamp'] = detail.replace('Rule timestamp:', '').strip()
+                    if detail.startswith('Last audited:'):
+                        rule_info['last_audited'] = detail.replace('Last audited:', '').strip()
                     elif detail.startswith('Newest file:'):
                         rule_info['newest_file'] = detail.replace('Newest file:', '').strip()
                     elif detail.startswith('File modified:'):
@@ -286,7 +331,7 @@ def build_stale_rules_context(stale_rules):
     parts.append("For each rule, review the rule content and the diff of changes, then:")
     parts.append("1. Determine if the rule content needs updating based on the code changes")
     parts.append("2. Update the rule if needed")
-    parts.append("3. ALWAYS update the timestamp (run `codeyam memory touch`)\n")
+    parts.append("3. Run `codeyam memory touch <rule-path1> <rule-path2> ...` with the SPECIFIC rule paths you reviewed to mark them as audited\n")
 
     for rule in stale_rules:
         parts.append(f"### {rule['name']}")
@@ -298,8 +343,8 @@ def build_stale_rules_context(stale_rules):
             parts.append(f"  Changed file: {rule['newest_file']}")
         if rule.get('file_modified'):
             parts.append(f"  File modified: {rule['file_modified']}")
-        if rule.get('rule_timestamp'):
-            parts.append(f"  Rule timestamp: {rule['rule_timestamp']}")
+        if rule.get('last_audited'):
+            parts.append(f"  Last audited: {rule['last_audited']}")
         if rule.get('diff'):
             parts.append(f"  Changes:")
             for line in rule['diff'].split('\n'):
@@ -373,7 +418,7 @@ def build_interruption_context(conversation_snippets, follow_up_prompt, modified
     return '\n'.join(parts)
 
 
-def spawn_claude_agent(prompt, log_file, project_dir):
+def spawn_claude_agent(prompt, log_file, project_dir, model='haiku'):
     """Spawn a detached claude -p agent as a background process."""
     try:
         log_fh = open(log_file, 'w')
@@ -381,7 +426,8 @@ def spawn_claude_agent(prompt, log_file, project_dir):
         env['CODEYAM_RULE_AGENT'] = '1'
         subprocess.Popen(
             ['claude', '-p', prompt,
-             '--model', 'haiku',
+             '--model', model,
+             '--no-session-persistence',
              '--output-format', 'stream-json', '--verbose',
              '--allowedTools', 'Read,Edit,Write,Bash,Glob,Grep'],
             cwd=project_dir,
@@ -427,14 +473,17 @@ def handle_stop(hook_input):
     agent spawn) runs first. The slow `get_stale_rules()` call (~10s) runs last
     so the hook timeout doesn't kill us before the critical work is done.
     """
+    settings = load_memory_settings()
+
     session_id = hook_input.get('session_id', '')
     transcript_path = hook_input.get('transcript_path', '')
 
     if not session_id or not transcript_path:
         return
 
-    marker_dir = Path('/tmp/claude-rule-markers')
-    marker_dir.mkdir(exist_ok=True)
+    slug = get_project_slug()
+    marker_dir = Path('/tmp/claude-rule-markers') / slug
+    marker_dir.mkdir(parents=True, exist_ok=True)
     marker_file = marker_dir / f'{session_id}.marker'
 
     last_line, _ = read_marker(marker_file)
@@ -452,8 +501,8 @@ def handle_stop(hook_input):
     invocation_ts = datetime.now().strftime('%Y%m%d-%H%M%S')
     invocation_id = f'{session_id}-{invocation_ts}'
 
-    # Fast: spawn conversation review agent first
-    if len(conversation_snippets) > 0:
+    # Fast: spawn conversation review agent first (if enabled)
+    if settings['conversationReflection'] and len(conversation_snippets) > 0:
         conv_context = build_conversation_context(conversation_snippets, modified_files)
         conv_context_file = marker_dir / f'{invocation_id}-conversation.context'
         conv_context_file.write_text(conv_context)
@@ -466,26 +515,27 @@ def handle_stop(hook_input):
             NOTIFICATION_FILE=str(conv_notification_file),
             PROJECT_DIR=project_dir,
         )
-        spawn_claude_agent(conv_prompt, conv_log_file, project_dir)
+        spawn_claude_agent(conv_prompt, conv_log_file, project_dir, model=settings['promptModel'])
 
     # Slow (~10s): check for stale rules last — if the hook timeout kills us
     # here, the conversation agent and marker are already handled
-    stale_rules = get_stale_rules()
-
-    if len(stale_rules) > 0:
-        stale_context = build_stale_rules_context(stale_rules)
-        stale_context_file = marker_dir / f'{invocation_id}-stale.context'
-        stale_context_file.write_text(stale_context)
-
-        stale_log_file = marker_dir / f'{invocation_id}-stale.log'
-        stale_notification_file = marker_dir / 'rule-notification-stale.md'
-        stale_prompt = load_prompt_template(
-            'stale-rules-prompt.txt',
-            CONTEXT_FILE=str(stale_context_file),
-            NOTIFICATION_FILE=str(stale_notification_file),
-            PROJECT_DIR=project_dir,
-        )
-        spawn_claude_agent(stale_prompt, stale_log_file, project_dir)
+    if settings['ruleMaintenance']:
+        stale_rules = get_stale_rules()
+
+        if len(stale_rules) > 0:
+            stale_context = build_stale_rules_context(stale_rules)
+            stale_context_file = marker_dir / f'{invocation_id}-stale.context'
+            stale_context_file.write_text(stale_context)
+
+            stale_log_file = marker_dir / f'{invocation_id}-stale.log'
+            stale_notification_file = marker_dir / 'rule-notification-stale.md'
+            stale_prompt = load_prompt_template(
+                'stale-rules-prompt.txt',
+                CONTEXT_FILE=str(stale_context_file),
+                NOTIFICATION_FILE=str(stale_notification_file),
+                PROJECT_DIR=project_dir,
+            )
+            spawn_claude_agent(stale_prompt, stale_log_file, project_dir, model=settings['promptModel'])
 
 
 def handle_user_prompt_submit(hook_input):
@@ -495,6 +545,12 @@ def handle_user_prompt_submit(hook_input):
     marker file is stale (transcript has lines beyond the marker). If so, spawns a
     rule-reflection agent focused on the interruption.
     """
+    settings = load_memory_settings()
+
+    # Interruption detection is part of conversation reflection
+    if not settings['conversationReflection']:
+        return
+
     session_id = hook_input.get('session_id', '')
     transcript_path = hook_input.get('transcript_path', '')
     follow_up_prompt = hook_input.get('prompt', '')
@@ -502,8 +558,9 @@ def handle_user_prompt_submit(hook_input):
     if not session_id or not transcript_path:
         return
 
-    marker_dir = Path('/tmp/claude-rule-markers')
-    marker_dir.mkdir(exist_ok=True)
+    slug = get_project_slug()
+    marker_dir = Path('/tmp/claude-rule-markers') / slug
+    marker_dir.mkdir(parents=True, exist_ok=True)
     marker_file = marker_dir / f'{session_id}.marker'
 
     last_line, was_stop = read_marker(marker_file)
@@ -561,7 +618,7 @@ def handle_user_prompt_submit(hook_input):
         NOTIFICATION_FILE=str(notification_file),
         PROJECT_DIR=project_dir,
     )
-    spawn_claude_agent(prompt, log_file, project_dir)
+    spawn_claude_agent(prompt, log_file, project_dir, model=settings['promptModel'])
 
 
 def main():

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

@@ -4,120 +4,75 @@ Rules provide context-specific guidance when working in files matching their `pa
 
 ## Core Principles
 
-1. **One concept per rule** - Each rule should cover a single topic. If you're documenting two unrelated things, create two rules.
-2. **Paths must match content scope** - A rule about one specific file should have that file in `paths`, not a broad `**/*.ts` pattern.
-3. **Be concise** - Every word costs context. Use bullets and tables.
+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.
 
-## When to Create a New Rule
+**Example** — a typical rule:
 
-Create a new rule when:
-
-- You learn something non-obvious about the codebase
-- You make a mistake and want to prevent it in the future
-- The user explains something that isn't clear from the code
-- An existing rule is covering multiple unrelated topics (split it)
-
-## Before Creating: The Confusion Test
-
-Only create rules that document genuinely confusing aspects—not things Claude can figure out by reading code and will likely come up again in future sessions.
-
-**Ask yourself:**
-
-1. **Could Claude figure this out by reading the code?**
-   - If YES → don't create the rule
-   - If NO → proceed
-
-2. **Does this explain "why" not just "what"?**
-   - Good: Historical context, gotchas, non-obvious behavior, non-obvious architectural decisions
-   - Bad: Bug fixes, Limitations (unless the user requests the limitation be noted), What functions do (unless providing a high-level architectural overview)
-
-3. **Would this have prevented a past mistake?**
-   - If you can point to a bug or confusion this would have prevented → create it
-   - If it's just "nice to know" → skip it
-
-### Examples
-
-**✅ Worth documenting:**
-
-- Where to add new functionality
-- An overview of all files, classes, functions, etc used in a particular part of the repo
-- Debugging strategies for a particular area of the repo
-- "Use `pnpm test` to run tests" (if there is more than one way to run tests and this way is preferred)
-
-**❌ Not worth documenting:**
-
-- "The auth module handles authentication" (obvious from reading code)
-- "This function takes X and returns Y" (Claude can read the signature)
+```markdown
+---
+paths:
+  - 'packages/ai/src/lib/generateMockData.ts'
+---
 
-## Path Specificity
+# Mock Data Generation
 
-The `paths` field controls when the rule is shown. Match the scope of your content:
+- 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
+```
 
-| 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 with paths to test configs and test files |
+## When to Create a Rule
 
-**Anti-pattern**: Don't use `'**/*.ts'` for a rule about one specific feature.
+Create a rule when you learn something that **reading the code alone wouldn't reveal**:
 
-## File Structure
+- 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
 
-Rules mirror the source code structure:
+**Skip** rules that restate what the code says — function signatures, type definitions, "this module handles X." Claude can read the code.
 
-| Source Location      | Rule Location                           |
-| -------------------- | --------------------------------------- |
-| `src/api/auth.ts`    | `.claude/rules/src/api/auth.md`         |
-| `src/utils/queue/**` | `.claude/rules/src/utils/queue.md`      |
-| Test configuration   | `.claude/rules/testing/jest-configs.md` |
+## Frontmatter & Paths
 
-## Required Frontmatter
+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'
-timestamp: 2026-01-30T00:00:00Z
 ---
 ```
 
-| Field       | Purpose                                                          |
-| ----------- | ---------------------------------------------------------------- |
-| `paths`     | Glob patterns - be specific to avoid loading rules unnecessarily |
-| `timestamp` | ISO 8601 - update when rule is reviewed                          |
-
-## Content Guidelines
-
-### Be Actionable
-
-- Good: "Run `pnpm test:api` for API tests"
-- Bad: "Make sure to run the appropriate tests"
+| 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   |
 
-### Focus on What, Not What Not
+Audit dates live in `.claude/codeyam-rule-state.json` (managed by `codeyam memory touch`). Keep frontmatter limited to `paths`.
 
-- Good: "Auth tokens are stored in httpOnly cookies via `src/auth/cookies.ts`"
-- Bad: "WARNING: Don't store tokens in localStorage!"
+## File Placement
 
-### Keep Rules Short
+Rules must be written to `.claude/rules/`, NOT `.codeyam/rules/`. The instructions file lives in `.codeyam/` but actual rule files go in `.claude/rules/`.
 
-- Target 30-50 lines
-- If a rule exceeds 60 lines, consider splitting it
+Use `codeyam memory rule-path` to compute the correct directory from your frontmatter paths:
 
-## Categories
-
-**architecture** - Design decisions, file relationships, data flow
-
-- "These three files must change together because..."
-- "Data flows from X → Y → Z"
-
-**testing** - Test commands, mock patterns, fixtures
+```
+$ codeyam memory rule-path packages/ai/src/lib/foo.ts packages/ai/src/utils/bar.ts
+{"result":".claude/rules/packages/ai/src/"}
+```
 
-- "Run tests with: `pnpm test path/to/test.ts`"
-- "Must run `pnpm pretest` first because..."
+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.
 
-**faq** - Gotchas, workarounds, common questions
+## Content Guidelines
 
-- "If you see error X, it means Y"
-- "This looks wrong but is intentional because..."
+- **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/{codeyam:debug.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.

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?". 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.
+- Keep edits small and incremental so the user can see changes in the preview as you go
+- **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