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

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

@@ -0,0 +1,78 @@
+# Claude Rules Guide
+
+Rules provide context-specific guidance when working in files matching their `paths` patterns.
+
+## Core Principles
+
+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.
+
+**Example** — a typical rule:
+
+```markdown
+---
+paths:
+  - 'packages/ai/src/lib/generateMockData.ts'
+---
+
+# Mock Data Generation
+
+- Entry point: `generateMockData()` in `generateMockData.ts`
+- Uses `convertDotNotation` to transform flat schema into nested objects
+- Schema entry ORDER matters — `key[]` must come before `key[].property` or arrays get overwritten
+- Test with exact ordering from database, not just same entries
+```
+
+## When to Create a Rule
+
+Create a rule when you learn something that **reading the code alone wouldn't reveal**:
+
+- 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
+
+**Skip** rules that restate what the code says — function signatures, type definitions, "this module handles X." Claude can read the code.
+
+## Frontmatter & Paths
+
+Every rule needs a `paths` frontmatter field. Be specific to avoid loading rules unnecessarily:
+
+```yaml
+---
+paths:
+  - 'specific/path/to/file.ts'
+  - 'another/specific/path/*.ts'
+---
+```
+
+| 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   |
+
+Audit dates live in `.claude/codeyam-rule-state.json` (managed by `codeyam memory touch`). Keep frontmatter limited to `paths`.
+
+## File Placement
+
+Rules must be written to `.claude/rules/`, NOT `.codeyam/rules/`. The instructions file lives in `.codeyam/` but actual rule files go in `.claude/rules/`.
+
+Use `codeyam memory rule-path` to compute the correct directory from your frontmatter paths:
+
+```
+$ codeyam memory rule-path packages/ai/src/lib/foo.ts packages/ai/src/utils/bar.ts
+{"result":".claude/rules/packages/ai/src/"}
+```
+
+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.
+
+## Content Guidelines
+
+- **Be actionable** — "Run `pnpm test:api` for API tests" not "Make sure to run the appropriate tests"
+- **Focus on why, not what** — Gotchas, non-obvious behavior, architectural decisions. The code already shows "what."
+- **Point to specifics** — "Auth tokens are stored in httpOnly cookies via `src/auth/cookies.ts`" beats a vague description.
+- **Be short!** - Context window space is precious! Do not ramble, use bullets, focus on providing clear actionable information.

package/codeyam-cli/templates/{codeyam-debug-skill.md → skills/codeyam-debug/SKILL.md}

@@ -1,5 +1,5 @@
 ---
-name: CodeYam Debug
+name: codeyam-debug
 autoApprove: true
 description: |
   Use this skill when entity analysis or capture fails with errors.
@@ -37,6 +37,49 @@ The `codeyam init` command has already auto-approved:
 
 You can freely work with logs and update configuration without asking for permission.
 
+## Important: File Locations
+
+Understanding where files live is critical for debugging:
+
+| What                | Location                                               | Notes                                                                                                         |
+| ------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
+| **Database**        | `.codeyam/db.sqlite3`                                  | In the **original project directory** (where you ran `codeyam init`). Contains entities, analyses, scenarios. |
+| **Config**          | `.codeyam/config.json`                                 | In the **original project directory**. Universal mocks go here.                                               |
+| **LLM Calls**       | `.codeyam/llm-calls/`                                  | In the **original project directory**. JSON files recording LLM inputs/outputs for each analysis.             |
+| **Logs**            | `/tmp/codeyam/local-dev/{projectSlug}/codeyam/log.txt` | In the temp folder. Analysis and capture logs.                                                                |
+| **Generated files** | `/tmp/codeyam/local-dev/{projectSlug}/project/`        | A **copy** of your project with mock injections.                                                              |
+| **Analyzer**        | `/tmp/codeyam/local-dev/{projectSlug}/codeyam/`        | The analysis engine runtime.                                                                                  |
+
+**Common mistake:** Looking for the database in `/tmp/codeyam/local-dev/{projectSlug}/project/.codeyam/db.sqlite3` - this is a **copy** and may be empty or stale. Always query the database in the **original project directory**.
+
+### Debugging with LLM Calls
+
+The `.codeyam/llm-calls/` directory contains JSON files recording every LLM interaction during analysis. Examining these is often key to understanding why analysis produced unexpected results:
+
+```bash
+# List recent LLM calls
+ls -lt .codeyam/llm-calls/ | head -10
+
+# View a specific call (shows both the prompt sent and response received)
+cat .codeyam/llm-calls/{filename}.json | jq .
+```
+
+**What to look for:**
+
+- **Input context**: Was the right code/context sent to the LLM?
+- **Response parsing**: Did the LLM return valid JSON? Were fields missing or malformed?
+- **Scenario generation**: For scenario issues, check if the LLM generated the expected data structures
+
+**Example database query:**
+
+```bash
+# CORRECT - query the original project database
+sqlite3 /path/to/your/project/.codeyam/db.sqlite3 "SELECT id, entityName FROM analyses LIMIT 5"
+
+# WRONG - the temp copy doesn't have the real data
+sqlite3 /tmp/codeyam/local-dev/{projectSlug}/project/.codeyam/db.sqlite3 "..."
+```
+
 ## Debugging Workflow
 
 ### Step 1: Read the Error Log
@@ -44,8 +87,8 @@ You can freely work with logs and update configuration without asking for permis
 The simulation log contains all error details:
 
 ```bash
-# For local development
-tail -n 100 /tmp/codeyam/local-dev/{projectSlug}/log.txt
+# For local development (note the /codeyam/ folder in the path)
+tail -n 100 /tmp/codeyam/local-dev/{projectSlug}/codeyam/log.txt
 ```
 
 Look for:
@@ -92,7 +135,8 @@ Cannot destructure property 'entities' of 'useLoaderData()' as it is null
 This is a **SCENARIO MOCK ISSUE**, not a universal mock issue. Follow these steps:
 
 1. **Check the analysis metadata** for `scenariosDataStructure`:
-   - Query the database or check analysis records
+   - Query the database **in the original project directory** (`.codeyam/db.sqlite3`)
+   - Example: `sqlite3 .codeyam/db.sqlite3 "SELECT json_extract(analysis, '$.scenariosDataStructure') FROM analyses WHERE entityName='MyEntity'"`
    - Look for the `dataForMocks` property
    - This shows what data the analysis engine expected to mock
 

package/codeyam-cli/templates/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

package/codeyam-cli/templates/skills/codeyam-editor/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: codeyam-editor
+autoApprove: true
+description: CodeYam Editor Mode — scaffold a project and build code + data scenarios together
+---
+
+# CodeYam Editor Mode
+
+You are in **Editor Mode**. The user sees a split-screen: this terminal on the left, live preview on the right.
+
+## CRITICAL: How This Works
+
+You MUST follow a step-by-step workflow driven by `codeyam editor` commands. Each command tells you exactly what to do next. **You do NOT have all the instructions upfront** — the commands provide them incrementally.
+
+**Your first action:** Run `codeyam editor steps`.
+
+**The rule:** After completing what a command tells you to do, run the NEXT command it specifies. The commands are your instructions — follow them one at a time.
+
+## The Cycle
+
+Every feature follows 13 gated steps:
+
+```
+codeyam editor steps → Setup (if new) or cycle overview
+codeyam editor 1    → Plan the feature (confirm with user)
+codeyam editor 2    → Build a working prototype fast
+codeyam editor 3    → Confirm prototype with user
+codeyam editor 4    → Plan extraction (read code, list everything to extract)
+codeyam editor 5    → Execute extraction (TDD for functions, extract components)
+codeyam editor 6    → Record functions in glossary
+codeyam editor 7    → Analyze and verify components
+codeyam editor 8    → Create app-level scenarios
+codeyam editor 9    → Create user-persona scenarios
+codeyam editor 10   → Verify screenshots and check for errors
+codeyam editor 11   → Create/update journal entry
+codeyam editor 12   → Verify screenshots and audit
+codeyam editor 13   → Present summary, get final approval
+```
+
+**You MUST run each command and follow its checklist before moving to the next.** Steps 1, 3, and 13 require user confirmation. After step 13, loop back to step 1.
+
+## Handling User Feedback / Changes
+
+When the user asks for changes — whether through the menu, a direct request, or even a question that implies a change (e.g., "Can the cards have images?") — you MUST run `codeyam editor change` **before** writing any code. This command gives you the post-change checklist (re-register scenarios, re-run tests, update journal, etc.). Never make changes without running the change workflow first.
+
+## Key Rules
+
+- **Run the commands** — they ARE your instructions, not suggestions
+- **Every feature gets scenarios** — this is the core value of CodeYam
+- **Always scaffold with a database** (Prisma + SQLite)
+- **Build real API routes** — the proxy handles scenario data transparently
+- **Start the dev server via the CodeYam API** — it handles proxy setup automatically
+- **Keep the preview moving** — the user watches the preview panel as you work. Refresh it frequently so they see progress, not a static screen. See below.
+
+## Keep the Preview Moving
+
+The user is watching the live preview panel while you work. A static preview makes it feel like nothing is happening. **Refresh the preview after every meaningful change** — not just at the end of a step.
+
+**During prototyping (step 2):**
+
+- Refresh after creating the first visible page, even if it's bare
+- Refresh after adding each major UI section (header, list, form, etc.)
+- Refresh after seeding data so the user sees real content appear
+- Refresh after styling changes so the user sees the visual progress
+
+**During extraction (step 5):**
+
+- Refresh after extracting each batch of components to confirm nothing broke
+
+**During changes:**
+
+- Refresh after each individual change, not after all changes are done
+
+**How to refresh:**
+
+```
+codeyam editor preview
+```
+
+Navigate to a specific path or switch scenario:
+
+```
+codeyam editor preview '{"path":"/drinks/1"}'
+codeyam editor preview '{"scenarioId":"abc-123"}'
+```
+
+The goal: the user should see the preview update 4-8+ times during a typical building session, not just once at the end.
+
+## Collaboration
+
+Isolation routes are committed to git (not gitignored). They are protected by a layout guard at `app/codeyam-isolate/layout.tsx` that returns `notFound()` in production, so they are safe to commit. Scenarios, screenshots, journal entries, and the glossary are also committed. Only the local database and secrets are gitignored.
+
+When a collaborator clones the repo and runs `codeyam editor`, scenarios are auto-imported from `scenarios-manifest.json`. Run `codeyam editor sync` to manually re-sync after pulling new changes.
+
+## Quick Reference
+
+```bash
+# Register component scenario (auto-captures screenshot)
+codeyam editor register '{"name":"DrinkCard - Default","componentName":"DrinkCard","componentPath":"app/components/DrinkCard.tsx","url":"/codeyam-isolate/DrinkCard?s=Default","mockData":{"routes":{"/api/...":{"body":[...]}}}}'
+
+# Register app scenario with seed data (ALWAYS include "url" — the page to screenshot)
+codeyam editor register '{"name":"Full Catalog","type":"application","url":"/","seed":{"drinks":[...]}}'
+
+# For large seed data, write JSON to a temp file and use @ prefix:
+codeyam editor register @/tmp/scenario-data.json
+
+# Journal entry (one per feature, references scenario names)
+codeyam editor journal '{"title":"...","type":"feature","description":"..."}'
+
+# Update journal with commit info
+codeyam editor journal-update '{"time":"...","commitSha":"...","commitMessage":"..."}'
+
+# Refresh preview / navigate / switch scenario
+codeyam editor preview
+codeyam editor preview '{"path":"/drinks/1"}'
+codeyam editor preview '{"scenarioId":"abc-123"}'
+
+# Show/hide results panel
+codeyam editor show-results
+codeyam editor hide-results
+
+# Commit feature
+codeyam editor commit '{"message":"feat: Add drinks page"}'
+
+# Restart dev server (only for config/dependency changes)
+codeyam editor dev-server '{"action":"restart"}'
+
+# Check for client-side errors
+codeyam editor client-errors
+
+# Verify all images load (extracts URLs from pages, HTTP-checks each one)
+codeyam editor verify-images '{"paths":["/","/drinks/1"]}'
+
+# Sync scenarios from manifest (after pulling collaborator changes)
+codeyam editor sync
+```