@codeyam/codeyam-cli 0.1.0-staging.eb21b2f → 0.1.0-staging.f777668

package/codeyam-cli/templates/prompts/conversation-guidance.txt

@@ -0,0 +1,44 @@
+### What to look for
+
+Read the full transcript for these signals:
+
+**User corrections or redirections**
+- "no", "actually", "that's not right", "you need to also...", "you missed..."
+- User provides information Claude didn't know or couldn't infer from code
+- User reminds Claude of a step, pattern, or relationship
+- A correction about something other than current task requirements is ALWAYS rule-worthy
+
+**Investigation and debugging**
+- Claude tried multiple approaches, read logs, or tested hypotheses
+- Investigation revealed non-obvious behavior or root causes
+- Debugging strategies that worked (or didn't) for specific areas
+
+**Architecture not evident in code**
+- Files that must change together (templates + installation, routes + registration)
+- Complex files, data flows, pipelines, or system interactions that would benefit from an overview
+
+**Commands and workflows**
+- Specific commands or flags needed for this area
+- Order of operations that matters ("must run X before Y")
+
+**Ignore:**
+- Corrections to requirements for the current feature or bug
+- Confusion isolated to the current work session (won't recur)
+
+### Before creating a rule
+
+**Critical check:** Read the actual source files that were modified. If the code already contains comments, guard patterns, or tests that explain the insight, the code is the documentation — skip the rule unless the file is complex and you've made a mistake or the user had to interrupt and correct you.
+
+Show your thinking before proceeding with creating or updating rules.
+
+### How to write rules
+
+**Rules must be forward-looking, not historical.** You are reading a session transcript where bugs were found and fixed, but the rule should describe the *current* codebase, not tell the story of what went wrong, what was fixed, etc. The code has already been updated — past bugs are no longer relevant.
+
+- **DO**: State constraints and requirements ("this script MUST copy directories recursively, not just files")
+- **DO**: Explain *why* something matters ("errors in prompt copying are silently caught, so missing directories won't surface as errors")
+- **DON'T**: Describe what old code did ("the old version only copied files, causing X to be missing")
+- **DON'T**: Narrate the debugging journey ("we discovered that the catch block was swallowing errors")
+- **DON'T**: Note issues or known gaps if they are actively being worked on!
+
+Think of the reader as a developer about to modify these files. They need to know what constraints to preserve and what pitfalls to watch for — not what happened in the past if it is no longer relevant.

package/codeyam-cli/templates/prompts/conversation-prompt.txt

@@ -0,0 +1,28 @@
+FIRST: Read `.codeyam/rules/instructions.md` — it contains the required format, rule placement via the rule-path API, and an example rule. You MUST follow this format exactly when creating or editing rules.
+
+THEN: Read the file {{CONTEXT_FILE}} and follow the instructions inside.
+
+Analyze the conversation transcript for rule-worthy learnings:
+- User corrections, redirections, or information Claude didn't know
+- Investigation results and debugging knowledge
+- Architecture and relationships not obvious from code
+- Commands, workflows, and processes
+
+Access and read files in the repo or in the .claude folder as needed.
+
+Create new rules only when the learnings meet the guidelines in the context file.
+
+IMPORTANT: If you create ANY rule files, write a short summary to `{{NOTIFICATION_FILE}}`. The summary should list each rule change, e.g.:
+```
+The background rule-reflection agent created the following rules:
+- Created `.claude/rules/tooling/new-pattern.md` — documents X pattern
+```
+Only write the notification file when rules are created.
+
+The project root is {{PROJECT_DIR}}
+
+CRITICAL: All rule files MUST be written to {{PROJECT_DIR}}/.claude/rules/ (the project directory). Always use the full absolute path when writing rule files.
+
+CRITICAL: Before writing any rule file, you MUST run the rule-path command to determine the correct subdirectory:
+  codeyam memory rule-path path/one path/two
+Pass all paths from your frontmatter. The command returns the correct .claude/rules/ subdirectory as JSON. Do NOT guess the placement from the first path — rules with paths spanning multiple directories belong at their common ancestor.

package/codeyam-cli/templates/prompts/interruption-prompt.txt

@@ -0,0 +1,31 @@
+FIRST: Read `.codeyam/rules/instructions.md` — it contains the required format, rule placement via the rule-path API, and an example rule. You MUST follow this format exactly when creating or editing rules.
+
+THEN: Read the file {{CONTEXT_FILE}} and follow the instructions inside.
+
+The user interrupted Claude mid-response — a strong signal of confusion or misunderstanding.
+Analyze both Claude's interrupted output and the user's follow-up to determine what went wrong.
+
+Look for:
+- Claude heading in a wrong direction that the user had to correct
+- Misunderstanding of project conventions, architecture, or dependencies
+- Missing context that caused Claude to make incorrect assumptions
+- Patterns that would recur in future sessions without a rule
+
+Access and read files in the repo or in the .claude folder as needed.
+
+Create new rules only when the learnings meet the guidelines in the context file.
+
+IMPORTANT: If you create ANY rule files, write a short summary to `{{NOTIFICATION_FILE}}`. The summary should list each rule change, e.g.:
+```
+The background rule-reflection agent created the following rules:
+- Created `.claude/rules/tooling/new-pattern.md` — documents X pattern
+```
+Only write the notification file when rules are created.
+
+The project root is {{PROJECT_DIR}}
+
+CRITICAL: All rule files MUST be written to {{PROJECT_DIR}}/.claude/rules/ (the project directory). Always use the full absolute path when writing rule files.
+
+CRITICAL: Before writing any rule file, you MUST run the rule-path command to determine the correct subdirectory:
+  codeyam memory rule-path path/one path/two
+Pass all paths from your frontmatter. The command returns the correct .claude/rules/ subdirectory as JSON. Do NOT guess the placement from the first path — rules with paths spanning multiple directories belong at their common ancestor.

package/codeyam-cli/templates/prompts/stale-rules-prompt.txt

@@ -0,0 +1,24 @@
+FIRST: Read `.codeyam/rules/instructions.md` — it contains the required format, rule placement via the rule-path API, and an example rule. You MUST follow this format exactly when creating or editing rules.
+
+THEN: Read the file {{CONTEXT_FILE}} and follow the instructions inside.
+
+For each stale rule:
+1. Review the inline rule content and the diff to determine if the rule needs updating
+2. If it needs updating, edit the rule file in .claude/rules/ — also trim prose and unnecessary headers (most rules should be a few bullets)
+3. Run `codeyam memory touch <rule-path1> <rule-path2> ...` with the SPECIFIC rule paths you reviewed to mark them as audited in .claude/codeyam-rule-state.json
+   Example: `codeyam memory touch tooling/cli-build.md packages/ai/execution-flow-prioritization.md`
+
+Write a summary to `{{NOTIFICATION_FILE}}` listing each action taken, even if you only ran `codeyam memory touch` without content changes. Example:
+```
+The background rule-reflection agent updated the following rules:
+- Reviewed `.claude/rules/example.md` — no content changes, ran `codeyam memory touch`
+- Created `.claude/rules/tooling/new-pattern.md` — documents X pattern
+```
+
+The project root is {{PROJECT_DIR}}
+
+CRITICAL: All rule files MUST be written to {{PROJECT_DIR}}/.claude/rules/ (the project directory), NOT ~/.claude/rules/ (the user home directory). Always use the full absolute path when writing rule files.
+
+CRITICAL: Before writing any rule file, you MUST run the rule-path command to determine the correct subdirectory:
+  codeyam memory rule-path path/one path/two
+Pass all paths from your frontmatter. The command returns the correct .claude/rules/ subdirectory as JSON. Do NOT guess the placement from the first path — rules with paths spanning multiple directories belong at their common ancestor.

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

@@ -14,6 +14,7 @@ Supports four notification files (legacy combined + split agents):
 - rule-notification-interruption.md (interruption review agent)
 """
 
+import json
 import os
 import sys
 
@@ -26,27 +27,53 @@ NOTIFICATION_FILES = [
 ]
 
 
+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 main():
     collected = []
+    slug = get_project_slug()
+
+    # Check slug subdirectory first, then fall back to flat directory
+    dirs_to_check = [os.path.join(MARKER_DIR, slug), MARKER_DIR]
 
     for filename in NOTIFICATION_FILES:
-        filepath = os.path.join(MARKER_DIR, filename)
-        if not os.path.exists(filepath):
-            continue
-
-        try:
-            with open(filepath, 'r') as f:
-                content = f.read().strip()
-        except IOError:
-            continue
-
-        if content:
-            collected.append(content)
-
-        try:
-            os.remove(filepath)
-        except OSError:
-            pass
+        for check_dir in dirs_to_check:
+            filepath = os.path.join(check_dir, filename)
+            if not os.path.exists(filepath):
+                continue
+
+            try:
+                with open(filepath, 'r') as f:
+                    content = f.read().strip()
+            except IOError:
+                continue
+
+            if content:
+                collected.append(content)
+
+            try:
+                os.remove(filepath)
+            except OSError:
+                pass
+
+            # Found in this directory — don't check the fallback
+            break
 
     if collected:
         print('\n\n'.join(collected))

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

@@ -120,6 +120,24 @@ 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.
@@ -463,8 +481,9 @@ def handle_stop(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, _ = read_marker(marker_file)
@@ -539,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)

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

@@ -4,13 +4,11 @@ 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. **Keep rules SHORT** - Most rules should be **1-4 bullets**. Only complex multi-file architectural overviews should exceed ~10 lines. Every word costs context.
+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.
 
-### Good vs Bad Rule Length
-
-**Good** — a typical rule (4 bullets):
+**Example** — a typical rule:
 
 ```markdown
 ---
@@ -26,68 +24,21 @@ paths:
 - Test with exact ordering from database, not just same entries
 ```
 
-**Bad** — same info bloated to 40+ lines with unnecessary headers, restating what the code says, and paragraphs instead of bullets.
-
-## When to Create a New 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: What Makes a Rule Valuable?
-
-A rule earns its place when it meets these criteria:
-
-1. **Beyond the code** — It captures knowledge that reading the source alone wouldn't reveal (historical context, non-obvious interactions, gotchas).
-2. **Explains "why" over "what"** — Gotchas, non-obvious behavior, architectural decisions. (Function signatures, bug fixes, and limitations are already visible in code.)
-3. **Prevents real mistakes** — It would have saved someone from a past confusion or bug, not just a "nice to know."
+## When to Create a Rule
 
-### Examples
+Create a rule when you learn something that **reading the code alone wouldn't reveal**:
 
-**✅ Worth documenting:**
+- 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
 
-- 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)
-
-Skip things like "The auth module handles authentication" or "This function takes X and returns Y" unless creating an overview of a complex area of the app — For individual files Claude can read the code and infer these insights.
-
-## Path Specificity
-
-The `paths` field controls when the rule is shown. Match the scope of your content:
-
-| 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 |
-
-Match path specificity to content scope — use `'path/to/feature.ts'` for a single-feature rule, not `'**/*.ts'`.
-
-## File Placement
+**Skip** rules that restate what the code says — function signatures, type definitions, "this module handles X." Claude can read the code.
 
-Place each rule at the **deepest common directory** shared by all its `paths` entries:
+## Frontmatter & Paths
 
-1. Take all paths from the rule's frontmatter
-2. Strip filenames — keep only the directory portions
-3. Find the longest shared directory prefix
-4. Place the rule `.md` file in `.claude/rules/<that-prefix>/`
-
-| Paths in frontmatter                                       | Deepest common dir     | Rule location                                  |
-| ---------------------------------------------------------- | ---------------------- | ---------------------------------------------- |
-| `packages/ai/src/lib/foo.ts`, `packages/ai/src/lib/bar.ts` | `packages/ai/src/lib/` | `.claude/rules/packages/ai/src/lib/foo-bar.md` |
-| `packages/ai/src/lib/a.ts`, `packages/ai/src/utils/b.ts`   | `packages/ai/src/`     | `.claude/rules/packages/ai/src/a-and-b.md`     |
-| `packages/ai/**`, `packages/types/**`                      | `packages/`            | `.claude/rules/packages/ai-types.md`           |
-| `src/api/auth.ts` (single file)                            | `src/api/`             | `.claude/rules/src/api/auth.md`                |
-
-Reserve the top level of `.claude/rules/` for rules whose paths genuinely span the entire repo.
-
-## Required Frontmatter
+Every rule needs a `paths` frontmatter field. Be specific to avoid loading rules unnecessarily:
 
 ```yaml
 ---
@@ -97,36 +48,31 @@ paths:
 ---
 ```
 
-| Field   | Purpose                                                          |
-| ------- | ---------------------------------------------------------------- |
-| `paths` | Glob patterns - be specific to avoid loading rules unnecessarily |
-
-**Note:** Audit dates live in `.claude/codeyam-rule-state.json` (managed by `codeyam memory touch`). Keep rule frontmatter limited to `paths`.
-
-## Content Guidelines
-
-### Be Actionable
+| 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   |
 
-- Good: "Run `pnpm test:api` for API tests"
-- Bad: "Make sure to run the appropriate tests"
+Audit dates live in `.claude/codeyam-rule-state.json` (managed by `codeyam memory touch`). Keep frontmatter limited to `paths`.
 
-### Focus on What to Do
-
-- "Auth tokens are stored in httpOnly cookies via `src/auth/cookies.ts`" tells the reader exactly where to look and what pattern to follow.
-
-## Categories
+## File Placement
 
-**architecture** - Design decisions, file relationships, data flow
+Rules must be written to `.claude/rules/`, NOT `.codeyam/rules/`. The instructions file lives in `.codeyam/` but actual rule files go in `.claude/rules/`.
 
-- "These three files must change together because..."
-- "Data flows from X → Y → Z"
+Use `codeyam memory rule-path` to compute the correct directory from your frontmatter paths:
 
-**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/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.
+- **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