@codeyam/codeyam-cli 0.1.0-staging.1669d45 → 0.1.0-staging.2a88920

package/codeyam-cli/src/webserver/build/server/index.js

@@ -1 +1 @@
-import{Y as F,M as G,N as H,W as I,O as J,R as K,T as L,V as Z,U as _,X as $,Q as rr}from"./assets/server-build-CFXnd7MG.js";import"react/jsx-runtime";import"node:stream";import"@react-router/node";import"react-router";import"isbot";import"react-dom/server";import"react";import"lucide-react";import"fetch-retry";import"better-sqlite3";import"pg";import"fs";import"path";import"kysely";import"kysely/helpers/sqlite";import"kysely/helpers/postgres";import"typescript";import"fs/promises";import"os";import"prompts";import"chalk";import"crypto";import"child_process";import"util";import"dotenv";import"events";import"uuid";import"url";import"openai";import"p-queue";import"p-retry";import"@aws-sdk/client-dynamodb";import"lru-cache";import"pluralize";import"piscina";import"json5";import"@aws-sdk/util-dynamodb";import"react-syntax-highlighter";import"react-syntax-highlighter/dist/cjs/styles/prism/index.js";import"node:crypto";import"v8";import"react-diff-viewer-continued";export{F as assets,G as assetsBuildDirectory,H as basename,I as entry,J as future,K as isSpaMode,L as prerender,Z as publicPath,_ as routeDiscovery,$ as routes,rr as ssr};
+import{Y as H,Z as I,M as J,N as K,W as L,O as _,R as $,T as rr,V as tr,U as or,X as ir,Q as pr}from"./assets/server-build-dYC34MHw.js";import"react/jsx-runtime";import"node:stream";import"@react-router/node";import"react-router";import"isbot";import"react-dom/server";import"react";import"lucide-react";import"fetch-retry";import"better-sqlite3";import"pg";import"fs";import"path";import"kysely";import"kysely/helpers/sqlite";import"kysely/helpers/postgres";import"typescript";import"fs/promises";import"os";import"prompts";import"chalk";import"crypto";import"child_process";import"url";import"util";import"dotenv";import"events";import"uuid";import"openai";import"p-queue";import"p-retry";import"@aws-sdk/client-dynamodb";import"lru-cache";import"pluralize";import"piscina";import"json5";import"@aws-sdk/util-dynamodb";import"v8";import"react-syntax-highlighter";import"react-syntax-highlighter/dist/cjs/styles/prism/index.js";import"node:crypto";import"minimatch";import"react-markdown";import"remark-gfm";import"react-diff-viewer-continued";export{H as allowedActionOrigins,I as assets,J as assetsBuildDirectory,K as basename,L as entry,_ as future,$ as isSpaMode,rr as prerender,tr as publicPath,or as routeDiscovery,ir as routes,pr as ssr};

package/codeyam-cli/src/webserver/build-info.json

@@ -1,7 +1,7 @@
 {
-  "buildTimestamp": "2026-01-21T15:31:57.854Z",
-  "buildTime": 1769009517854,
-  "buildNumber": 487,
-  "semanticVersion": "0.1.487",
-  "version": "0.1.487 (2026-01-21T15:31)"
+  "buildTimestamp": "2026-02-03T16:02:39.433Z",
+  "buildTime": 1770134559433,
+  "buildNumber": 579,
+  "semanticVersion": "0.1.579",
+  "version": "0.1.579 (2026-02-03T16:02)"
 }

package/codeyam-cli/templates/codeyam-memory-hook.sh

@@ -0,0 +1,200 @@
+#!/bin/bash
+# CodeYam Memory - Pre-commit Hook (BLOCKING)
+# Ensures rules are reviewed when associated code changes
+#
+# This hook checks that rules with matching `paths` patterns have been reviewed
+# (indicated by an updated `timestamp` field) when associated code files are modified.
+
+set -e
+
+RULES_DIR=".claude/rules"
+
+# Skip if no rules directory
+if [ ! -d "$RULES_DIR" ]; then
+  exit 0
+fi
+
+# Get staged code files (added, copied, modified, renamed)
+STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACMR 2>/dev/null | grep -E '\.(ts|tsx|js|jsx)$' || true)
+
+if [ -z "$STAGED_FILES" ]; then
+  exit 0
+fi
+
+# Function to convert ISO 8601 timestamp to epoch seconds
+# Handles both macOS and Linux date commands
+timestamp_to_epoch() {
+  local ts="$1"
+  # Remove trailing Z if present
+  ts="${ts%Z}"
+
+  if date --version >/dev/null 2>&1; then
+    # GNU date (Linux)
+    date -d "$ts" +%s 2>/dev/null || echo "0"
+  else
+    # BSD date (macOS)
+    # Handle ISO 8601 format: 2026-01-27T10:30:00
+    date -j -f "%Y-%m-%dT%H:%M:%S" "$ts" +%s 2>/dev/null || echo "0"
+  fi
+}
+
+# Function to get file modification time as epoch
+get_file_mtime() {
+  local file="$1"
+  if [ ! -f "$file" ]; then
+    echo "0"
+    return
+  fi
+
+  if stat --version >/dev/null 2>&1; then
+    # GNU stat (Linux)
+    stat -c %Y "$file" 2>/dev/null || echo "0"
+  else
+    # BSD stat (macOS)
+    stat -f %m "$file" 2>/dev/null || echo "0"
+  fi
+}
+
+# Function to check if a file matches a glob pattern
+# This is a simplified matcher - complex globs may not work perfectly
+matches_pattern() {
+  local file="$1"
+  local pattern="$2"
+
+  # Handle ** patterns by converting to simpler form
+  # This is a simplification - proper glob matching would need a more robust solution
+  local regex_pattern="$pattern"
+
+  # Escape regex special chars except * and ?
+  regex_pattern=$(echo "$regex_pattern" | sed 's/\./\\./g; s/\[/\\[/g; s/\]/\\]/g')
+
+  # Convert glob patterns to regex
+  # ** matches any path segment(s)
+  regex_pattern=$(echo "$regex_pattern" | sed 's/\*\*/DOUBLESTAR/g')
+  # * matches anything except /
+  regex_pattern=$(echo "$regex_pattern" | sed 's/\*/[^/]*/g')
+  # ** matches any path
+  regex_pattern=$(echo "$regex_pattern" | sed 's/DOUBLESTAR/.*/g')
+  # ? matches single char
+  regex_pattern=$(echo "$regex_pattern" | sed 's/?/./g')
+
+  # Anchor the pattern
+  regex_pattern="^${regex_pattern}$"
+
+  echo "$file" | grep -qE "$regex_pattern" 2>/dev/null
+}
+
+# Parse timestamp from YAML frontmatter
+get_rule_timestamp() {
+  local rule_file="$1"
+  # Extract content between first two --- lines, then find timestamp
+  sed -n '1,/^---$/!{/^---$/q;p}' "$rule_file" 2>/dev/null | \
+    grep -E '^timestamp:' | \
+    sed 's/timestamp:[[:space:]]*//' | \
+    tr -d "'" | tr -d '"' | \
+    head -1
+}
+
+# Parse paths from YAML frontmatter
+get_rule_paths() {
+  local rule_file="$1"
+  # Extract the paths array from YAML frontmatter
+  # This handles both inline array and multi-line array formats
+  sed -n '1,/^---$/!{/^---$/q;p}' "$rule_file" 2>/dev/null | \
+    sed -n '/^paths:/,/^[a-z]/p' | \
+    grep -E "^[[:space:]]*-" | \
+    sed "s/^[[:space:]]*-[[:space:]]*//" | \
+    tr -d "'" | tr -d '"'
+}
+
+OUTDATED_RULES=""
+CHECKED_RULES=""
+
+# Find all rule files and check them
+while IFS= read -r rule_file; do
+  # Skip if already checked this rule
+  if echo "$CHECKED_RULES" | grep -qF "$rule_file"; then
+    continue
+  fi
+  CHECKED_RULES="$CHECKED_RULES $rule_file"
+
+  rule_timestamp=$(get_rule_timestamp "$rule_file")
+
+  # Skip rules without timestamp
+  if [ -z "$rule_timestamp" ]; then
+    continue
+  fi
+
+  rule_epoch=$(timestamp_to_epoch "$rule_timestamp")
+
+  if [ "$rule_epoch" = "0" ]; then
+    continue
+  fi
+
+  # Get paths for this rule
+  rule_paths=$(get_rule_paths "$rule_file")
+
+  if [ -z "$rule_paths" ]; then
+    continue
+  fi
+
+  # Check each staged file against this rule's paths
+  rule_is_outdated=false
+  matched_file=""
+
+  while IFS= read -r staged_file; do
+    if [ -z "$staged_file" ]; then
+      continue
+    fi
+
+    while IFS= read -r pattern; do
+      if [ -z "$pattern" ]; then
+        continue
+      fi
+
+      if matches_pattern "$staged_file" "$pattern"; then
+        # Get file modification time
+        file_epoch=$(get_file_mtime "$staged_file")
+
+        # If file is newer than rule timestamp, flag it
+        if [ "$file_epoch" -gt "$rule_epoch" ]; then
+          rule_is_outdated=true
+          matched_file="$staged_file"
+          break 2
+        fi
+      fi
+    done <<< "$rule_paths"
+  done <<< "$STAGED_FILES"
+
+  if [ "$rule_is_outdated" = true ]; then
+    OUTDATED_RULES="$OUTDATED_RULES
+    - $rule_file
+      (matched: $matched_file)"
+  fi
+
+done < <(find "$RULES_DIR" -name "*.md" -type f 2>/dev/null)
+
+if [ -n "$OUTDATED_RULES" ]; then
+  echo ""
+  echo "================================================================"
+  echo "  Claude Rules (Codeyam Memory): Outdated Documentation Detected"
+  echo "================================================================"
+  echo ""
+  echo "  The following rules have timestamps older than the code"
+  echo "  files they cover:"
+  echo "$OUTDATED_RULES"
+  echo ""
+  echo "  To proceed:"
+  echo "    1. Review each rule to ensure it's still accurate"
+  echo "    2. Update the 'timestamp' field in the YAML frontmatter"
+  echo "    3. Stage the updated rule file(s)"
+  echo "    4. Commit again"
+  echo ""
+  echo "  Or ask Claude to \"run \`codeyam memory status\` and follow the instructions.\""
+  echo ""
+  echo "================================================================"
+  echo ""
+  exit 1  # BLOCK the commit
+fi
+
+exit 0

package/codeyam-cli/templates/codeyam:debug.md

@@ -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/codeyam:diagnose.md

@@ -4,7 +4,7 @@ When a user asks to debug a scenario or analysis (e.g., `/codeyam:diagnose [ID]`
 
 ## Goal
 
-Determine whether a capture failure can be fixed locally (via database changes) or requires a CodeYam engine fix. Either way, produce a detailed debug report.
+**Capture quality screenshots** by fixing all errors, then document what was wrong. Every issue can be fixed locally—the question is whether the fix is in the database (Categories 1-3) or in the tmp folder code (Category 4). Either way, you must capture screenshots before concluding.
 
 ## Definition of Done
 
@@ -14,6 +14,43 @@ Determine whether a capture failure can be fixed locally (via database changes)
 2. **SUCCESS (File Fix)**: Issue fixed via tmp folder edits, screenshots recaptured with `--capture-only`, ALL screenshot files verified AND visually inspected, changes documented for CodeYam team
 3. **UNFIXABLE**: Issue cannot be fixed locally (rare), documented in final report with full details
 
+**CRITICAL: NEVER stop debugging before capturing quality screenshots.** Even if you identify the root cause as a "Category 4 engine bug", you MUST:
+
+1. Fix the issue manually in the tmp folder (this is always possible)
+2. Run `codeyam recapture --capture-only` to capture screenshots with your fixes in place
+3. Verify the screenshots show the component rendering correctly
+4. ONLY THEN document the engine bug for the CodeYam team
+
+Stopping after identifying a bug category without capturing screenshots defeats the purpose of debugging.
+
+## Critical: Persistence and User Communication
+
+**DO NOT give up prematurely.** Every issue can be fixed by editing files in the tmp folder. If you find yourself thinking:
+
+- "This requires an engine-level fix"
+- "This is blocked by a code generation bug"
+- "The engine doesn't properly handle X"
+
+**STOP.** These statements are incorrect. You have full access to edit any file in `/tmp/codeyam/local-dev/{slug}/project/`. The "engine" just wrote those files—they're plain TypeScript/JavaScript that you can edit directly.
+
+### Before Stopping or Concluding
+
+1. **Try at least 3 different approaches** to fix the issue
+2. **Never unilaterally decide to stop.** If you've been debugging and aren't making progress, ASK THE USER:
+   > "I've tried X, Y, and Z but haven't resolved the issue yet. Would you like me to continue investigating other approaches, or should I document what I've found so far?"
+3. **Only stop when the user agrees** or when you've successfully captured quality screenshots
+
+### The "Engine Bug" Misconception
+
+When you identify a Category 4 issue (code generation bug), this does NOT mean you're blocked. It means:
+
+- The bug is in how CodeYam generates code (useful info for the CodeYam team)
+- You MUST still fix it manually by editing files in the tmp folder
+- You MUST still capture quality screenshots
+- You document what you fixed so the CodeYam team can improve the engine
+
+**"Engine bug" is a diagnosis category, not an excuse to stop.**
+
 ---
 
 ## Debug Flow Summary
@@ -25,11 +62,12 @@ Determine whether a capture failure can be fixed locally (via database changes)
 │          Retrieve the analysis id to use in the debug command       │
 │                    │                                                │
 │                    ▼                                                │
-│  Step 1: codeyam debug [ANALYSIS ID]  (generates files to inspect)  │
-│  Step 2: Identify error type from logs/output                       │
-│  Step 3: Diagnose root cause category (1-4)                         │
-│  Step 4: Attempt fix (database edit or universal mock)              │
-│  Step 5: Verify locally (curl returns 200)                          │
+│  Step 1: Copy the logs to a temporary location (see below).         |
+|  Step 2: codeyam debug [ANALYSIS ID]  (generates files to inspect)  │
+│  Step 3: Identify error type from logs/output                       │
+│  Step 4: Diagnose root cause category (1-4)                         │
+│  Step 5: Attempt fix (database edit or universal mock)              │
+│  Step 6: Verify locally (curl returns 200)                          │
 │                   │                                                 │
 │         ┌─────────┴─────────┐                                       │
 │         ▼                   ▼                                       │
@@ -43,12 +81,12 @@ Determine whether a capture failure can be fixed locally (via database changes)
 │         │         Verify without regenerating                       │
 │         │                   │                                       │
 │         ▼                   ▼                                       │
-│   Step 6: Recapture    Step 6: Recapture --capture-only             │
+│   Step 7: Recapture    Step 7: Recapture --capture-only             │
 │   (normal)             (preserves file fixes)                       │
 │         │                   │                                       │
 │         └─────────┬─────────┘                                       │
 │                   ▼                                                 │
-│   Step 7: Verify screenshots (check for client-side errors)         │
+│   Step 8: Verify screenshots (check for client-side errors)         │
 │                   │                                                 │
 │                   ▼                                                 │
 │   Verify ALL files exist on disk                                    │
@@ -59,16 +97,128 @@ Determine whether a capture failure can be fixed locally (via database changes)
 └─────────────────────────────────────────────────────────────────────┘
 ```
 
+**Logs:** Before debugging copy the original logs to a temorary location as the debugging will overwrite these logs and they are valuable for debugging issues.
+
+Original Logs Locaion: `/tmp/codeyam/local-dev/{slug}/codeyam/logs.txt`
+Temporary location: `/tmp/codeyam/local-dev/{slug}/debug/original-logs.txt`
+
+**Notice:** Both paths lead to "Recapture" and "Verify screenshots". There is no path that ends after just identifying a bug category. You must always capture quality screenshots before completing.
+
+---
+
+## MANDATORY: Session Context (Do This First!)
+
+Long debugging sessions cause context loss. To prevent forgetting critical information:
+
+### Step 1: Create Session Context File
+
+At the **very start** of debugging, create `.codeyam/debug-session.md` in the **original project directory**:
+
+```markdown
+# Debug Session Context
+
+**IMPORTANT**: Keep a todo item "📍 Re-read debug session context" that is NEVER marked complete.
+If the todo disappears, add it back immediately.
+
+## Key Locations
+
+- **Original project**: [FULL PATH - run all codeyam commands here]
+- **Tmp folder**: /tmp/codeyam/local-dev/[SLUG]/project (edit files here, do NOT run codeyam commands)
+- **Database**: [ORIGINAL PROJECT]/.codeyam/db.sqlite3
+- **Logs**: /tmp/codeyam/local-dev/[SLUG]/codeyam/log.txt
+
+## IDs
+
+- **Analysis ID**: [ID]
+- **Scenario ID**: [ID]
+- **Entity**: [NAME] at [FILE PATH]
+
+## URLs (fill in after running codeyam debug)
+
+- **Scenario URL**: http://localhost:[PORT]/static/codeyam-sample
+- **Dev server port**: [PORT from codeyam debug output]
+
+## Commands Reference
+
+All commands run from: [ORIGINAL PROJECT PATH]
+
+- `codeyam debug [ANALYSIS_ID]` - regenerate files (overwrites tmp folder!)
+- `codeyam recapture [ID]` - regenerate AND capture (overwrites tmp folder!)
+- `codeyam recapture [ID] --capture-only` - capture WITHOUT regenerating (preserves your edits)
+- `codeyam test-startup` - test startup (overwrites tmp folder!)
+```
+
+### Step 2: Create Persistent Todo
+
+Use TodoWrite to create this todo list with the first item being a persistent reminder:
+
+```
+📍 Re-read .codeyam/debug-session.md before any codeyam command (NEVER complete this)
+```
+
+**CRITICAL**: The first todo item must NEVER be marked as completed. It serves as a constant reminder to check your session context before running commands. If you accidentally complete it or it disappears, add it back immediately.
+
+### Step 3: Read Context Before Actions
+
+**Before running ANY of these commands**, re-read `.codeyam/debug-session.md`:
+
+- `codeyam debug`
+- `codeyam recapture`
+- `codeyam test-startup`
+- Any database queries
+
+This prevents running commands from the wrong directory or forgetting key IDs.
+
+---
+
+## Critical: Where to Run Commands
+
+**All `codeyam` commands MUST be run from the ORIGINAL PROJECT DIRECTORY**, not from the tmp folder.
+
+| Location                                                               | What's There                                                   | Run Commands Here?                                |
+| ---------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------- |
+| **Original project** (e.g., `/Users/.../clients-codeyam/boltwise/app`) | Database (`.codeyam/db.sqlite3`), config, universal mocks      | **YES - run all codeyam commands here**           |
+| **Tmp folder** (`/tmp/codeyam/local-dev/{slug}/project/`)              | Copy of project with mock injections, generated scenario files | **NO - only edit files here, don't run commands** |
+
+**Common mistake:** Running `codeyam recapture` from the tmp folder. This will fail with "Not in a CodeYam project" because the database doesn't exist there.
+
+```bash
+# WRONG - running from tmp folder
+cd /tmp/codeyam/local-dev/boltwise-app/project
+codeyam recapture abc123  # ❌ Fails: "Not in a CodeYam project"
+
+# CORRECT - running from original project directory
+cd /Users/jaredcosulich/workspace/codeyam/clients-codeyam/boltwise/app
+codeyam recapture abc123  # ✅ Works
+```
+
+**Workflow:**
+
+1. Edit files in `/tmp/codeyam/local-dev/{slug}/project/` to fix issues
+2. Test by curling the dev server running from the tmp folder
+3. **Switch back to the original project directory** to run `codeyam recapture`
+
 ---
 
 ## What You Can and Cannot Modify
 
 **NEVER modify the client's original source code in the workspace.** Only modify files in the tmp folder.
 
+### CRITICAL: Fix the Mocks, Never the Client Code
+
+When debugging errors, the fix is ALWAYS in the mock data or mock code—never in the client's components or application code.
+
+**If a component crashes due to unexpected data:**
+
+- Fix the mock data to provide what the component expects
+- Do NOT modify the component to handle the bad data
+
+**The client's code is sacred.** Our job is to make the simulation environment correct, not to "improve" or "harden" the client's code. Even if a component could be more defensive, that's not our fix to make.
+
 **You CAN modify:**
 
-- Data in the local SQLite database (`.codeyam/db.sqlite3`)
-- Universal mocks in `.codeyam/universal-mocks`
+- Data in the local SQLite database (`.codeyam/db.sqlite3`) - in the **original project directory**
+- Universal mocks in `.codeyam/universal-mocks` - in the **original project directory**
 - **Files in `/tmp/codeyam/local-dev/{slug}/project/`** - These are temporary copies used for simulation
   - Generated mock files in `__codeyamMocks__/` directories
   - Layout/route files that wrap scenarios
@@ -157,12 +307,12 @@ This is the most important step. Determine WHERE in the pipeline the bug origina
 
 ### The 4 Error Categories
 
-| Category | What's Wrong                                         | Where to Check            | Fixable Locally?       |
-| -------- | ---------------------------------------------------- | ------------------------- | ---------------------- |
-| **1**    | Missing attribute in `isolatedDataStructure`         | `entities.metadata`       | Sometimes (re-analyze) |
-| **2**    | Attribute not merged into `mergedDataStructure`      | `analyses.metadata`       | Sometimes (re-analyze) |
-| **3**    | Data structure complete, but scenario data wrong     | `scenarios.metadata`      | Yes (edit mockData)    |
-| **4**    | Data complete, but mock code/mock data written wrong | Generated files in `/tmp` | **No (engine bug)**    |
+| Category | What's Wrong                                         | Where to Check            | Fixable Locally?              |
+| -------- | ---------------------------------------------------- | ------------------------- | ----------------------------- |
+| **1**    | Missing attribute in `isolatedDataStructure`         | `entities.metadata`       | Sometimes (re-analyze)        |
+| **2**    | Attribute not merged into `mergedDataStructure`      | `analyses.metadata`       | Sometimes (re-analyze)        |
+| **3**    | Data structure complete, but scenario data wrong     | `scenarios.metadata`      | Yes (edit mockData)           |
+| **4**    | Data complete, but mock code/mock data written wrong | Generated files in `/tmp` | **Yes (edit files directly)** |
 
 ### Diagnostic Queries
 
@@ -201,7 +351,7 @@ sqlite3 .codeyam/db.sqlite3 \
 6. **Check generated mock code** - Is the mock code syntactically/semantically correct? If wrong → **Category 4 (engine bug)**
 7. **Check generated imports** - Are the imports correct? Are entities containing environment variables mocked out? If wrong → **Category 4 (engine bug)**
 
-### Category 4 Indicators (Engine Bug)
+### Category 4 Indicators (Code Generation Issue)
 
 The issue is Category 4 if:
 
@@ -210,6 +360,16 @@ The issue is Category 4 if:
 - BUT the generated mock code has syntax errors, wrong structure, or doesn't match the data
 - Database edits don't fix the generated code (it regenerates wrong)
 
+**Category 4 does NOT mean you are blocked.** You have full access to fix these issues:
+
+1. **Edit the files directly** in `/tmp/codeyam/local-dev/{slug}/project/`
+2. **Fix any syntax errors, wrong imports, missing mocks** - these are just TypeScript files
+3. **Restart the dev server** and verify the fix works
+4. **Capture quality screenshots** with `codeyam recapture --capture-only`
+5. **Document what you fixed** for the CodeYam team to improve the engine
+
+The term "engine bug" means the CodeYam code generation has a bug—it does NOT mean you cannot fix the issue locally. You always can.
+
 ---
 
 ## Step 4: Attempt Fix
@@ -261,9 +421,15 @@ EOF
 
 ### For Category 4 (Code Generation Issues)
 
-**CAN be fixed locally by editing files in the tmp folder!** See Step 5a below.
+**MUST be fixed locally by editing files in the tmp folder.** This is a REQUIRED step, not optional.
 
-After fixing, use `codeyam recapture --capture-only` to capture without regenerating the (now-fixed) files.
+1. Go to Step 5a and fix all code issues in the tmp folder
+2. Verify the scenario loads correctly (curl returns 200)
+3. Run `codeyam recapture --capture-only` to capture screenshots (this preserves your fixes)
+4. Verify the screenshots look correct
+5. THEN document the engine bug in your final report
+
+**DO NOT stop after identifying a Category 4 issue.** The goal is to capture quality screenshots, then document what you fixed.
 
 ### Universal Mocks (for infrastructure dependencies)
 
@@ -322,7 +488,9 @@ After making **database changes** (Categories 1-3):
 
 ## Step 5a: Fix Code Issues in Tmp Folder (Category 4)
 
-If the error is in bad imports, generated code or mock files, you can fix them directly in the tmp folder:
+If the error is in bad imports, generated code or mock files, you can fix them directly in the tmp folder.
+
+**REMINDER: Only fix GENERATED files (mocks, layouts, routes)—never the client's application code.** If a client component crashes, the fix is in the mock data or mock code, not in the component itself.
 
 ### Locate the Problematic File
 
@@ -361,11 +529,19 @@ cd /tmp/codeyam/local-dev/{slug}/project
 npm run dev  # or pnpm dev / yarn dev
 ```
 
-Then curl the scenario URL to verify the fix works:
+Then verify the fix works. You can either:
 
-```bash
-curl -s http://localhost:3112/static/codeyam-sample | head -50
-```
+1. **Curl the URL** to check for errors:
+
+   ```bash
+   curl -s http://localhost:3112/static/codeyam-sample | head -50
+   ```
+
+2. **Ask the user to verify visually**: If the fix involves visual output or you're unsure if it worked, ask the user to visit the URL and confirm:
+
+   > "I've fixed the mock data. Can you visit http://localhost:3112/static/codeyam-sample and let me know if the component renders correctly now?"
+
+   This is especially useful for client-side rendering issues that curl won't catch.
 
 ---
 
@@ -574,8 +750,10 @@ If this is an engine bug, include:
 
 ### Verification
 
+**All of these must be checked before the debug session is complete:**
+
 - [ ] Scenario loads without errors (curl returns 200)
-- [ ] Screenshots recaptured successfully
+- [ ] Screenshots recaptured successfully (this is REQUIRED, not optional)
 - [ ] Used `--capture-only` flag (if file changes were made)
 - [ ] Screenshot files verified to exist on disk
 - [ ] Screenshots visually inspected - no client-side errors visible