@codeyam/codeyam-cli 0.1.0-staging.8778565 → 0.1.0-staging.87dd4be

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

@@ -27,6 +27,9 @@ STEP_LABELS = {
     11: "Journal",
     12: "Review",
     13: "Present",
+    14: "Commit",
+    15: "Finalize",
+    16: "Push",
 }
 
 STEP_RESTRICTIONS = {
@@ -43,6 +46,35 @@ STEP_RESTRICTIONS = {
     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`.",
 }
 
 
@@ -81,6 +113,13 @@ def detect_event():
 
 
 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")
@@ -88,11 +127,12 @@ def main():
     # Detect event early so we can capture the user prompt even before state exists
     event_type, event_data = detect_event()
 
-    # Capture the very first user prompt (before state file may exist).
+    # 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:
+        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:
@@ -112,24 +152,40 @@ def main():
     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)
 
-    restriction = STEP_RESTRICTIONS.get(step, "")
-    next_cmd = f"codeyam editor {step + 1}" if step < 13 else "codeyam editor 1"
+    # 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'Editor Mode — Step {step} ({label}): "{feature}"',
+            f'{mode_label} — Step {step} ({label}): "{feature}"{page_info}',
         ]
 
         # Include the active scenario so Claude knows what the user is looking at
@@ -149,15 +205,26 @@ def main():
         except (IOError, json.JSONDecodeError):
             pass
 
-        if step == 13:
+        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 steps` after committing "
-                "to start the next feature."
+                "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(
@@ -170,8 +237,9 @@ def main():
         print("\n".join(lines))
         return
 
+    mode_label = "Migration Mode" if migration else "Editor Mode"
     lines = [
-        f'Editor Mode \u2014 Step {step} ({label}): "{feature}"',
+        f'{mode_label} \u2014 Step {step} ({label}): "{feature}"',
     ]
     if restriction:
         lines.append(restriction)
@@ -182,18 +250,40 @@ def main():
         BOLD_CYAN = "\033[1;36m"
         DIM = "\033[2m"
         RESET = "\033[0m"
-        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, 14):
-            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}")
+
+        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(
@@ -201,7 +291,7 @@ def main():
             "\u2713 (done) or \u2717 (skipped + reason)."
         )
 
-    if event_type == "stop" and step == 13:
+    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(
@@ -218,8 +308,8 @@ def main():
                 "\n\033[1;31m⚠️  You have uncommitted changes but haven't shown Working Session Results.\033[0m"
             )
             lines.append(
-                "\033[31mRun `codeyam editor change` if you haven't already, then complete the "
-                "checklist and run `codeyam editor 13` to show results to the user.\033[0m"
+                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}")

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     |

package/codeyam-cli/templates/expo-react-native/package.json

@@ -4,6 +4,7 @@
   "private": true,
   "main": "expo-router/entry",
   "scripts": {
+    "setup": "npm install",
     "dev": "expo start --web",
     "start": "expo start",
     "android": "expo start --android",

package/codeyam-cli/templates/nextjs-prisma-sqlite/DATABASE.md

@@ -23,6 +23,20 @@ npm run db:reset
 npx prisma studio
 ```
 
+## Adding Columns to Existing Tables
+
+When adding a new **required** column to a table that already has data, `db push` will fail because existing rows have no value for the new column. To avoid this:
+
+- **Add a `@default(...)` value** so Prisma can fill existing rows automatically:
+  ```prisma
+  model Rating {
+    userId String @default("anonymous")  // existing rows get "anonymous"
+  }
+  ```
+- Once all rows have real values, you can remove the default if desired.
+- **Never use `--force-reset`** — it drops ALL tables and deletes all data.
+- Optional columns (`String?`) don't need a default — existing rows get `null`.
+
 ## Using the Database
 
 ```typescript

package/codeyam-cli/templates/nextjs-prisma-sqlite/README.md

@@ -0,0 +1,53 @@
+# Project Name
+
+Brief description of what this app does.
+
+## Setup
+
+Run the setup script to install dependencies, initialize the database, and seed it with demo data:
+
+```bash
+npm run setup
+```
+
+## Development
+
+Start the dev server:
+
+```bash
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) in your browser.
+
+## Using CodeYam Editor
+
+This project was built with [CodeYam](https://codeyam.com). To launch the editor:
+
+```bash
+codeyam editor
+```
+
+The editor provides a live preview alongside a Claude Code terminal for iterating on the app.
+
+## Database
+
+This project uses SQLite via Prisma. Common commands:
+
+```bash
+npm run db:push    # Apply schema changes and generate Prisma client
+npm run db:seed    # Seed the database with demo data
+npm run db:reset   # Reset database: drop, recreate, and re-seed
+```
+
+## Scripts
+
+| Script             | Description                                  |
+| ------------------ | -------------------------------------------- |
+| `npm run setup`    | One-line project setup (install + db + seed) |
+| `npm run dev`      | Start the development server                 |
+| `npm run build`    | Build for production                         |
+| `npm run test`     | Run tests                                    |
+| `npm run db:push`  | Apply Prisma schema changes                  |
+| `npm run db:seed`  | Seed the database                            |
+| `npm run db:reset` | Reset and re-seed the database               |

package/codeyam-cli/templates/nextjs-prisma-sqlite/package.json

@@ -3,6 +3,7 @@
   "version": "0.1.0",
   "private": true,
   "scripts": {
+    "setup": "npm install && npm run db:push && npm run db:seed",
     "dev": "next dev --turbopack",
     "build": "next build",
     "start": "next start",
@@ -17,7 +18,7 @@
     "@prisma/adapter-better-sqlite3": "^7.4.1",
     "@prisma/client": "^7.4.1",
     "better-sqlite3": "^12.6.2",
-    "next": "^15.3.3",
+    "next": "^16.1.7",
     "prisma": "^7.4.1",
     "react": "^19.1.0",
     "react-dom": "^19.1.0"

package/codeyam-cli/templates/nextjs-prisma-sqlite/seed-adapter.ts

@@ -17,7 +17,7 @@
  */
 
 import 'dotenv/config';
-import { PrismaClient } from '@prisma/client';
+import { PrismaClient, Prisma } from '@prisma/client';
 import { PrismaBetterSqlite3 } from '@prisma/adapter-better-sqlite3';
 import * as fs from 'fs';
 
@@ -84,9 +84,44 @@ async function main() {
   console.log('Seed complete');
 }
 
-main()
-  .then(() => prisma.$disconnect())
-  .catch((e) => {
-    console.error('Seed adapter error:', e);
-    process.exit(1);
-  });
+/**
+ * Export mode: dump current database state to a JSON file.
+ * Used by CodeYam to save interactive changes back to scenario seed data.
+ *
+ * Usage: npx tsx .codeyam/seed-adapter.ts --export <output-path.json>
+ */
+async function exportData(outputPath: string) {
+  const modelNames = Prisma.dmmf.datamodel.models.map((m) => m.name);
+
+  const seed: Record<string, unknown[]> = {};
+  for (const model of modelNames) {
+    const camelCase = model.charAt(0).toLowerCase() + model.slice(1);
+    try {
+      const rows = await (prisma as any)[camelCase].findMany();
+      if (rows.length > 0) {
+        seed[camelCase] = rows;
+      }
+    } catch {
+      // Skip tables that can't be queried
+    }
+  }
+
+  fs.writeFileSync(outputPath, JSON.stringify(seed, null, 2));
+  console.log(`Exported ${Object.keys(seed).length} tables`);
+}
+
+if (process.argv[2] === '--export') {
+  exportData(process.argv[3])
+    .then(() => prisma.$disconnect())
+    .catch((e) => {
+      console.error('Seed adapter export error:', e);
+      process.exit(1);
+    });
+} else {
+  main()
+    .then(() => prisma.$disconnect())
+    .catch((e) => {
+      console.error('Seed adapter error:', e);
+      process.exit(1);
+    });
+}