@codeyam/codeyam-cli 0.1.0-staging.d3e886e → 0.1.0-staging.d4f25c3

package/codeyam-cli/templates/codeyam-editor-reference.md

@@ -0,0 +1,214 @@
+# .codeyam/ Directory Reference
+
+This file documents the `.codeyam/` internals and CLI commands. Consult this when you're stuck on scenario registration, audit failures, preview issues, or understanding what files do what.
+
+## Directory Structure
+
+### Committed Files (shared across clones)
+
+- `config.json` — Project configuration: slug, screen sizes, default viewport, feature metadata
+- `editor-scenarios/` — Scenario JSON files with seed data, localStorage, MSW handlers, and metadata
+- `scenarios-manifest.json` — Index of all scenarios for database sync on fresh clones
+- `design-system.md` — Design tokens and brand guidelines (if present)
+- `glossary.json` — Entity glossary built during extraction steps
+- `msw-handlers/` — MSW handler files for API mocking (one per scenario)
+- `seed-adapters/` — Seed adapter templates for database seeding
+
+### Gitignored Files (machine-local)
+
+- `db.sqlite3` / `db.sqlite3-wal` / `db.sqlite3-shm` — SQLite database (rebuilt on clone via `codeyam editor`)
+- `secrets.json` — API keys (Anthropic, etc.)
+- `server.json` / `server-state.json` — Background server process state
+- `queue.json` — Analysis job queue state
+- `active-scenario.json` — Currently active scenario for the preview
+- `editor-step.json` — Current editor workflow step number
+- `editor-user-prompt.txt` — The user's feature request text
+- `claude-session-id.txt` — Claude Code session ID for step tracking
+- `editor-mode-context.md` / `dev-mode-context.md` — Generated context for Claude
+- `logs/` — Server and analysis logs
+- `llm-calls/` — LLM call recordings
+- `captures/` — Playwright screenshot captures
+- `results/` — Analysis results
+- `tmp/` — Temporary files (use for large scenario JSON)
+- `rules/` — Auto-installed Claude rules
+- `bin/` — Helper scripts and hooks
+
+## CLI Command Reference
+
+All commands use the pattern `codeyam editor <subcommand>`.
+
+### Scenario Management
+
+| Command                                 | Description                                                |
+| --------------------------------------- | ---------------------------------------------------------- |
+| `codeyam editor register '<json>'`      | Register a scenario (inline JSON or `@path/to/file.json`)  |
+| `codeyam editor scenarios`              | List all registered scenarios                              |
+| `codeyam editor delete <scenarioId>`    | Delete a scenario by ID                                    |
+| `codeyam editor scenario-coverage`      | Verify all affected scenarios are fresh after code changes |
+| `codeyam editor validate-seed '<json>'` | Validate seed data structure                               |
+
+### Preview & Verification
+
+| Command                           | Description                                                                                       |
+| --------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `codeyam editor preview '<json>'` | Navigate preview — **must include `dimension`** (e.g., `{"path":"/route","dimension":"Desktop"}`) |
+| `codeyam editor client-errors`    | Show client-side errors from the preview iframe                                                   |
+| `codeyam editor audit`            | Check that glossary entries have registered scenarios and tests                                   |
+
+### Entity Analysis
+
+| Command                                          | Description                                         |
+| ------------------------------------------------ | --------------------------------------------------- |
+| `codeyam editor analyze-imports`                 | Build the import dependency graph from source files |
+| `codeyam editor dependents <EntityName>`         | Find all entities that import a given entity        |
+| `codeyam editor isolate "ComponentA ComponentB"` | Create isolation route directories for components   |
+
+### Server
+
+| Command                     | Description             |
+| --------------------------- | ----------------------- |
+| `codeyam editor dev-server` | Query dev server status |
+
+### Workflow
+
+| Command                                                 | Description                                                     |
+| ------------------------------------------------------- | --------------------------------------------------------------- |
+| `codeyam editor <1-16>`                                 | Jump to a specific editor workflow step                         |
+| `codeyam editor steps`                                  | Show setup overview or cycle progress                           |
+| `codeyam editor change <feature>`                       | Start the change workflow for modifying features                |
+| `codeyam editor sync`                                   | Import scenarios from manifest into database (used after clone) |
+| `codeyam editor migrate [step\|next\|complete\|status]` | Run migration workflow steps                                    |
+
+## Scenario Registration Patterns
+
+### Component-Level Scenario
+
+```json
+{
+  "name": "TaskCard - Overdue",
+  "componentName": "TaskCard",
+  "url": "/isolated-components/TaskCard?s=Overdue",
+  "dimensions": ["Desktop"]
+}
+```
+
+### App-Level Scenario
+
+```json
+{
+  "name": "Dashboard with Tasks",
+  "url": "/",
+  "dimensions": ["Desktop"],
+  "seedData": {
+    "tasks": [{ "id": 1, "title": "Ship feature", "status": "in_progress" }]
+  },
+  "localStorage": { "user": "{\"name\":\"Alice\"}" }
+}
+```
+
+### Large JSON — Use a Tmp File
+
+Write JSON to `.codeyam/tmp/scenario.json` using the **Write tool**, then:
+
+```bash
+codeyam editor register @.codeyam/tmp/scenario.json
+```
+
+### Re-registration
+
+Registering a scenario with the same name replaces the existing one. No need to delete first.
+
+### Dimensions
+
+Dimension names come from `screenSizes` in `.codeyam/config.json`. Common values: `"Desktop"`, `"Mobile"`, `"Tablet"`. Every scenario and preview command must specify a dimension.
+
+## Troubleshooting
+
+### Audit gate blocking step 8+
+
+The audit checks that every glossary entity has at least one scenario and passes tests. Fix by:
+
+1. Run `codeyam editor audit` to see which entities are missing coverage
+2. Register scenarios for uncovered entities
+3. Fix any failing tests
+4. Re-run audit — do NOT loop `audit` and `analyze-imports` repeatedly
+
+### Scenarios showing empty/blank pages or error pages
+
+The scenario renders a URL but the page has no visible content, or shows an error page. Common causes:
+
+- **URL references IDs that don't exist in the seed data**: The URL contains a dynamic segment (e.g., `/items/abc-123`) but the seed data creates records with different IDs. Check the register output for `API response error` lines — they show the exact API call that failed and the server's response.
+- **Seed data doesn't match the code**: The seeded data has fields the component doesn't read, or the component expects data the seed doesn't provide
+- **Missing API route**: The component fetches from an API that doesn't exist yet
+- **Component not exported or not mounted**: The isolation route doesn't render the component
+- **Only create scenarios for states the current code can render** — if the component isn't built yet, the screenshot will be blank
+
+### Client errors in preview
+
+Run `codeyam editor client-errors` to see errors from the preview. There are three types:
+
+- **Console errors** (`Page console.error:`): JavaScript runtime errors — missing env vars, import errors, schema mismatches
+- **HTTP errors** (`HTTP error: status=NNN`): The page URL itself returned a non-2xx status (e.g., 404 page not found)
+- **API response errors** (`API response error: GET /api/... → NNN`): An API call made during page load returned a non-2xx status, with the server's response body included
+
+API response errors are the most actionable — they show the exact endpoint that failed and what the server returned. When you see one, read the scenario's seed data and verify that the IDs in the URL match IDs created by the seed. For example, if the URL is `/page/items/abc-123` but the seed creates items with ID `item-1`, the API call to `/api/items/abc-123` will return 404.
+
+### Dependents returning nothing
+
+`codeyam editor dependents <Entity>` requires the import graph to be built first. Run:
+
+```bash
+codeyam editor analyze-imports
+```
+
+Then retry `dependents`. The import graph persists in the database.
+
+### Database missing after clone
+
+This is expected — `db.sqlite3` is gitignored. Running `codeyam editor` detects this state (config.json exists, DB doesn't) and automatically runs `init --force` to rebuild the database and sync scenarios from the manifest.
+
+### Dev server not starting
+
+Check if another process holds the port:
+
+1. Look at `.codeyam/server-state.json` for the PID and port
+2. Kill any stale process
+3. Restart with `codeyam editor` (the editor command starts the server)
+
+### Step validation errors
+
+Each step has prerequisites. If a step refuses to run:
+
+1. Run `codeyam editor steps` to see which steps are complete
+2. Complete the prerequisite steps first
+3. Don't skip steps — the workflow is sequential
+
+### Dimension mismatch
+
+If previews look wrong or captures fail:
+
+- Check `screenSizes` in `.codeyam/config.json` for valid dimension names
+- Scenario `dimensions` must reference names defined in `screenSizes`
+- Preview commands must also include `dimension` — don't omit it
+
+### Preview not updating
+
+If changes aren't reflected in the preview:
+
+- The dev server may need to rebuild — check terminal output for compilation errors
+- Hard-refresh the preview: `codeyam editor preview '{"path":"<current-path>","dimension":"<dimension>","forceRefresh":true}'`
+- Check `codeyam editor client-errors` for runtime errors blocking render
+
+## Anti-Patterns
+
+**Don't loop audit/analyze-imports.** If audit fails, fix the underlying issues (missing scenarios, failing tests). Running audit repeatedly without fixing anything wastes time.
+
+**Don't use `prisma db push --force-reset`.** This drops all data. Instead, add `@default()` values for new required columns, or make them optional (`Int?`). Use `npm run db:push`.
+
+**Don't hardcode viewport dimensions.** Always reference named dimensions from `screenSizes` in config.json (e.g., `"Desktop"`). Don't use raw pixel values like `1440x900`.
+
+**Don't use bash heredocs for JSON.** Braces and quotes in heredocs trigger Claude Code security warnings. Use the **Write tool** to create `.codeyam/tmp/scenario.json`, then `codeyam editor register @.codeyam/tmp/scenario.json`.
+
+**Don't blanket-ignore `.codeyam` in `.gitignore`.** Only machine-local files are ignored with granular patterns. Shared files (`config.json`, `editor-scenarios/`, etc.) must be committable.
+
+**Don't register scenarios for unbuilt features.** If the component or page doesn't exist yet, the scenario will capture a blank page. Build the component first, then create scenarios for what it actually renders.

package/codeyam-cli/templates/editor-step-hook.py

@@ -0,0 +1,321 @@
+#!/usr/bin/env python3
+"""
+PostToolUse + Stop + UserPromptSubmit hook for editor mode step tracking.
+
+Reads .codeyam/editor-step.json and prints a reminder about the current step.
+Logs each firing to .codeyam/logs/editor-log.jsonl.
+If no state file exists, outputs nothing (not in editor mode or between features).
+"""
+
+import json
+import os
+import sys
+from datetime import datetime, timezone
+
+
+STEP_LABELS = {
+    1: "Plan",
+    2: "Prototype",
+    3: "Confirm",
+    4: "Deconstruct",
+    5: "Extract",
+    6: "Glossary",
+    7: "Analyze",
+    8: "App Scenarios",
+    9: "User Scenarios",
+    10: "Verify",
+    11: "Journal",
+    12: "Review",
+    13: "Present",
+    14: "Commit",
+    15: "Finalize",
+    16: "Push",
+}
+
+STEP_RESTRICTIONS = {
+    1: "Do NOT write any code. Plan and describe only. Wait for user confirmation.",
+    2: "Do NOT create scenarios or run codeyam analyze. Build fast — working prototype with real data.",
+    3: "Present a selection menu (AskUserQuestion) for confirmation. Do NOT refactor or create scenarios until approved.",
+    4: "Do NOT write any code. Read every file, identify all extractable pieces, write a numbered plan. Planning only.",
+    5: "Execute the extraction plan from step 4. Components first (no tests), then library functions via TDD. Page files must contain ZERO direct JSX.",
+    6: "Do NOT write application code or scenarios. Update the glossary only.",
+    7: "Create isolation routes for visual components, run tests for library functions. Register component scenarios via codeyam editor register.",
+    8: "Do NOT modify application code. Create and register app-level scenarios only.",
+    9: "Do NOT modify application code. Create user-persona scenarios only (or skip if no users).",
+    10: "Verify component isolation screenshots AND editor scenarios. After ANY code fix, re-register affected components. Fix only — do NOT add features.",
+    11: "Create or update the journal entry for this feature. Do NOT create a duplicate — check if one exists first.",
+    12: "Verify ALL screenshots exist and NO client-side errors (/api/editor-client-errors). Run codeyam editor audit. Do not proceed until all checks pass.",
+    13: "Show the results panel, present summary, then selection menu (AskUserQuestion): Save or make changes.",
+    14: "Hide the results panel and commit all changes. Do NOT push — that happens in step 16.",
+    15: "Update the journal entry with the commit SHA and amend the commit to include the journal update.",
+    16: "Check for a git remote and offer to push. WAIT for the user's answer before starting the next feature.",
+}
+
+MIGRATION_STEP_LABELS = {
+    1: "Survey",
+    2: "App Scenarios",
+    3: "Component Scenarios",
+    4: "Preview",
+    5: "Discuss",
+    6: "Decompose",
+    7: "Extract",
+    8: "Recapture",
+    9: "Journal",
+    10: "Present",
+}
+
+MIGRATION_STEP_RESTRICTIONS = {
+    1: "Survey the page and start the dev server. Read all files and map data flow. Do NOT register scenarios yet.",
+    2: "Set up seed adapter if needed, then register application scenarios for the ACTUAL page route with seed data.",
+    3: "Create isolation routes and register component scenarios for individual visual components.",
+    4: "Verify screenshots and show results to the user. Do NOT modify application code.",
+    5: "Assess complexity and ask user about decomposition. Wait for user decision before proceeding.",
+    6: "Plan-only. Identify all extractions, mark existing components as REUSE. Do NOT write code.",
+    7: "Execute the extraction plan. Components first, then functions via TDD.",
+    8: "Update glossary, re-register scenarios after code changes, verify screenshots. Fix issues only.",
+    9: "Create the journal entry for this page's migration.",
+    10: "Show results, present summary, commit or make changes. After commit run `codeyam editor migrate complete` then `codeyam editor migrate next`.",
+}
+
+
+def log_event(project_dir, event, data=None):
+    """Append a JSONL entry to .codeyam/logs/editor-log.jsonl."""
+    try:
+        logs_dir = os.path.join(project_dir, ".codeyam", "logs")
+        os.makedirs(logs_dir, exist_ok=True)
+        log_path = os.path.join(logs_dir, "editor-log.jsonl")
+        entry = {"ts": datetime.now(timezone.utc).isoformat(), "event": event}
+        if data:
+            entry.update(data)
+        with open(log_path, "a") as f:
+            f.write(json.dumps(entry) + "\n")
+    except Exception:
+        pass  # Logging is best-effort
+
+
+def detect_event():
+    """Detect whether this is a PostToolUse, Stop, or UserPromptSubmit hook from stdin."""
+    try:
+        raw = sys.stdin.read()
+        if not raw.strip():
+            return "unknown", {}
+        data = json.loads(raw)
+        # PostToolUse has tool_name; Stop has stop_hook_active; UserPromptSubmit has prompt
+        if "tool_name" in data:
+            return "post_tool_use", data
+        elif "stop_hook_active" in data:
+            return "stop", data
+        elif "prompt" in data:
+            return "user_prompt", data
+        return "unknown", data
+    except Exception:
+        return "unknown", {}
+
+
+def main():
+    # Only run in editor Build sessions. The env var is set by the terminal
+    # server when launching Claude in editor mode. Without this guard, hooks
+    # fire in every Claude session in the project (scenario editing, bare
+    # claude, etc.) and inject unwanted step restrictions.
+    if not os.environ.get("CODEYAM_EDITOR_ACTIVE"):
+        return
+
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
+    state_path = os.path.join(project_dir, ".codeyam", "editor-step.json")
+    prompt_path = os.path.join(project_dir, ".codeyam", "editor-user-prompt.txt")
+
+    # Detect event early so we can capture the user prompt even before state exists
+    event_type, event_data = detect_event()
+
+    # Capture the very first real user prompt (before state file may exist).
+    # Save to a separate file so it persists across state transitions.
+    # Skip slash commands (e.g. /codeyam-editor) — they aren't user prompts.
+    if event_type == "user_prompt" and not os.path.exists(prompt_path):
+        prompt_text = event_data.get("prompt", "").strip()
+        if prompt_text and not prompt_text.startswith("/"):
+            try:
+                os.makedirs(os.path.dirname(prompt_path), exist_ok=True)
+                with open(prompt_path, "w") as f:
+                    f.write(prompt_text)
+            except Exception:
+                pass  # Best-effort
+
+    if not os.path.exists(state_path):
+        return
+
+    try:
+        with open(state_path, "r") as f:
+            state = json.load(f)
+    except (json.JSONDecodeError, IOError):
+        return
+
+    step = state.get("step")
+    label = state.get("label", "Unknown")
+    feature = state.get("feature", "")
+    migration = state.get("migration")  # Optional migration context
+
+    if not step:
+        return
+
+    # Log the hook firing
+    log_data = {"step": step, "label": label, "feature": feature, "hook": event_type}
+    if migration:
+        log_data["migration"] = True
+    if event_type == "post_tool_use":
+        log_data["tool"] = event_data.get("tool_name", "")
+    log_event(project_dir, "hook", log_data)
+
+    # Use migration-specific labels/restrictions when in migration mode
+    if migration:
+        restriction = MIGRATION_STEP_RESTRICTIONS.get(step, "")
+        next_cmd = f"codeyam editor migrate {step + 1}" if step < 10 else "codeyam editor migrate next"
+    else:
+        restriction = STEP_RESTRICTIONS.get(step, "")
+        next_cmd = f"codeyam editor {step + 1}" if step < 16 else "codeyam editor 1"
+
+    # UserPromptSubmit: concise workflow reminder injected before Claude processes the user's message
+    if event_type == "user_prompt":
+        mode_label = "Migration Mode" if migration else "Editor Mode"
+        page_info = ""
+        if migration:
+            page_name = migration.get("pageName", "")
+            page_idx = migration.get("pageIndex", 0)
+            total = migration.get("totalPages", 0)
+            page_info = f" — Page {page_idx + 1}/{total} ({page_name})"
+
+        lines = [
+            f'<user-prompt-submit-hook>',
+            f'{mode_label} — Step {step} ({label}): "{feature}"{page_info}',
+        ]
+
+        # Include the active scenario so Claude knows what the user is looking at
+        active_scenario_path = os.path.join(project_dir, ".codeyam", "active-scenario.json")
+        try:
+            with open(active_scenario_path, "r") as f:
+                active = json.load(f)
+            scenario_name = (
+                active.get("scenarioName")
+                or active.get("scenarioSlug", "").replace("_", " ")
+            )
+            if scenario_name:
+                lines.append(
+                    f'The user is currently viewing scenario: "{scenario_name}". '
+                    "Assume any feedback refers to this scenario unless they say otherwise."
+                )
+        except (IOError, json.JSONDecodeError):
+            pass
+
+        if migration and step == 8:
+            lines.append(
+                "If the user is requesting changes (even indirectly), "
+                "run `codeyam editor change` BEFORE making any modifications. "
+                "The change workflow ensures Working Session Results are shown to the user. "
+                "If the user chose to commit, run `codeyam editor migrate next` to advance to the next page."
+            )
+        elif step in (13, 14, 15, 16) and not migration:
+            lines.append(
+                "If the user is requesting changes (even indirectly), "
+                "run `codeyam editor change` BEFORE making any modifications "
+                "(code, scenarios, data, styles — everything). "
+                "The change command gives you the post-change checklist. "
+                "The change workflow ensures Working Session Results are shown to the user. "
+                "If the user chose to commit, run `codeyam editor 14` to advance to the commit step."
+            )
+        elif migration:
+            lines.append(
+                f"You are on migration step {step}. Follow the `codeyam editor migrate` workflow. "
+                f"Do NOT skip ahead or make changes outside the current step."
+            )
+        else:
+            lines.append(
+                f"You are on step {step}. Follow the `codeyam editor` workflow. "
+                f"Do NOT skip ahead or make changes outside the current step."
+            )
+        if restriction:
+            lines.append(restriction)
+        lines.append('</user-prompt-submit-hook>')
+        print("\n".join(lines))
+        return
+
+    mode_label = "Migration Mode" if migration else "Editor Mode"
+    lines = [
+        f'{mode_label} \u2014 Step {step} ({label}): "{feature}"',
+    ]
+    if restriction:
+        lines.append(restriction)
+
+    if event_type == "stop":
+        # Build colored progress tracker using ANSI escape codes
+        GREEN = "\033[32m"
+        BOLD_CYAN = "\033[1;36m"
+        DIM = "\033[2m"
+        RESET = "\033[0m"
+
+        if migration:
+            # Migration progress tracker (10 steps)
+            page_name = migration.get("pageName", "")
+            page_idx = migration.get("pageIndex", 0)
+            total = migration.get("totalPages", 0)
+            tracker = [f"{DIM}  Migration: Page {page_idx + 1}/{total} ({page_name}){RESET}"]
+            tracker.append(f"{DIM}  \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510{RESET}")
+            for i in range(1, 11):
+                lbl = MIGRATION_STEP_LABELS[i].ljust(28)
+                num = f" {i}" if i < 10 else f"{i}"
+                cntnt = f"{num}. {lbl}"
+                if i < step:
+                    tracker.append(f"{DIM}  \u2502{RESET}{GREEN}  \u2713  {cntnt}{RESET}{DIM}\u2502{RESET}")
+                elif i == step:
+                    tracker.append(f"{DIM}  \u2502{RESET}{BOLD_CYAN}  \u2192  {cntnt}{RESET}{DIM}\u2502{RESET}")
+                else:
+                    tracker.append(f"{DIM}  \u2502  \u25cb  {cntnt}\u2502{RESET}")
+            tracker.append(f"{DIM}  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518{RESET}")
+        else:
+            # Standard progress tracker (16 steps)
+            tracker = [f"{DIM}  \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510{RESET}"]
+            for i in range(1, 17):
+                lbl = STEP_LABELS[i].ljust(28)
+                num = f" {i}" if i < 10 else f"{i}"
+                content = f"{num}. {lbl}"
+                if i < step:
+                    tracker.append(f"{DIM}  \u2502{RESET}{GREEN}  \u2713  {content}{RESET}{DIM}\u2502{RESET}")
+                elif i == step:
+                    tracker.append(f"{DIM}  \u2502{RESET}{BOLD_CYAN}  \u2192  {content}{RESET}{DIM}\u2502{RESET}")
+                else:
+                    tracker.append(f"{DIM}  \u2502  \u25cb  {content}\u2502{RESET}")
+            tracker.append(f"{DIM}  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518{RESET}")
+
+        lines.append("Present this progress tracker to the user (copy verbatim):")
+        lines.extend(tracker)
+        lines.append(
+            "For the CURRENT step (\u2192), show each checklist item with "
+            "\u2713 (done) or \u2717 (skipped + reason)."
+        )
+
+    if event_type == "stop" and ((step in (13, 14) and not migration) or (step == 8 and migration)):
+        import subprocess as _sp
+        try:
+            _result = _sp.run(
+                ["git", "status", "--porcelain"],
+                cwd=project_dir,
+                capture_output=True, text=True, timeout=5
+            )
+            has_uncommitted = bool(_result.stdout.strip())
+        except Exception:
+            has_uncommitted = False
+
+        if has_uncommitted:
+            lines.append(
+                "\n\033[1;31m⚠️  You have uncommitted changes but haven't shown Working Session Results.\033[0m"
+            )
+            lines.append(
+                f"\033[31mRun `codeyam editor change` if you haven't already, then complete the "
+                f"checklist and run `{'codeyam editor migrate 8' if migration else 'codeyam editor 13'}` to show results to the user.\033[0m"
+            )
+
+    lines.append(f"When this step is complete, run: {next_cmd}")
+
+    print("\n".join(lines))
+
+
+if __name__ == "__main__":
+    main()

package/codeyam-cli/templates/expo-react-native/MOBILE_SETUP.md

@@ -0,0 +1,89 @@
+# Expo + React Native Setup
+
+## Development
+
+This project uses **Expo** with **Expo Router** for file-based navigation and **NativeWind** (Tailwind CSS) for styling.
+
+### Web Development (used by CodeYam)
+
+```bash
+npm run dev
+```
+
+This starts the Expo web dev server. CodeYam uses this to preview your app and take screenshots.
+
+### Mobile Development
+
+```bash
+# iOS Simulator
+npm run ios
+
+# Android Emulator
+npm run android
+
+# Start Expo dev server (pick platform from menu)
+npm start
+```
+
+## Project Structure
+
+```
+app/                    # Expo Router file-based routes
+  _layout.tsx           # Root layout (status bar, navigation)
+  (tabs)/               # Tab-based navigation group
+    _layout.tsx         # Tab bar configuration
+    index.tsx           # Home tab
+    settings.tsx        # Settings tab
+components/             # Reusable components
+lib/
+  storage.ts            # AsyncStorage wrapper for persistent data
+```
+
+## Key Patterns
+
+### Navigation (Expo Router)
+
+Add new screens by creating files in `app/`:
+
+- `app/profile.tsx` — accessible at `/profile`
+- `app/items/[id].tsx` — dynamic route at `/items/123`
+
+### Data Fetching
+
+Use standard `fetch()` for API calls. CodeYam intercepts these to provide mock data during simulations:
+
+```tsx
+const response = await fetch('/api/items');
+const data = await response.json();
+```
+
+### Storage
+
+Use the typed storage helper for persistent data:
+
+```tsx
+import { storage } from '@/lib/storage';
+
+const items = await storage.get('items', []);
+await storage.set('items', [...items, newItem]);
+```
+
+### Styling (NativeWind)
+
+Use Tailwind classes on React Native components:
+
+```tsx
+<View className="flex-1 items-center justify-center bg-white p-4">
+  <Text className="text-lg font-bold text-gray-900">Hello</Text>
+</View>
+```
+
+## Building for Production
+
+```bash
+# Web
+npm run build:web
+
+# iOS/Android (requires EAS CLI)
+npx eas build
+```

package/codeyam-cli/templates/expo-react-native/README.md

@@ -0,0 +1,41 @@
+# Project Name
+
+Brief description of what this app does.
+
+## Setup
+
+```bash
+npm run setup
+```
+
+## Development
+
+Start the Expo dev server (web):
+
+```bash
+npm run dev
+```
+
+For native platforms:
+
+```bash
+npm run ios      # iOS simulator
+npm run android  # Android emulator
+```
+
+## Using CodeYam Editor
+
+This project was built with [CodeYam](https://codeyam.com). To launch the editor:
+
+```bash
+codeyam editor
+```
+
+## Scripts
+
+| Script            | Description                 |
+| ----------------- | --------------------------- |
+| `npm run setup`   | Install dependencies        |
+| `npm run dev`     | Start Expo dev server (web) |
+| `npm run ios`     | Run on iOS simulator        |
+| `npm run android` | Run on Android emulator     |