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

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
+```

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

@@ -208,6 +208,215 @@ Prioritize areas with stronger confusion signals:
 
 Focus your documentation efforts on areas with the highest confusion scores.
 
+Holistic source analysis signals (from the Holistic Source Analysis phase below) also feed into this scoring. Session mining signals (from the Session Log Mining phase below) feed into this same table.
+
+---
+
+## Phase 3B: Analysis Sizing & Menu
+
+Before running the expensive LLM-powered analysis phases, run the fast extraction scripts to gather sizing metrics and let the user choose which phases to run.
+
+### Step 1: Run fast extraction scripts (concurrent)
+
+Clear stale data from any previous run, then run all three scripts in parallel:
+
+```bash
+rm -rf /tmp/codeyam-memory/ /tmp/cc-session-analysis/
+```
+
+```bash
+node .claude/skills/codeyam-memory/scripts/holistic-analysis/detect-deprecated-patterns.mjs
+```
+
+```bash
+node .claude/skills/codeyam-memory/scripts/holistic-analysis/find-exports.mjs
+```
+
+```bash
+node .claude/skills/codeyam-memory/scripts/session-mining/preprocess.mjs 2>/dev/null
+```
+
+Capture the stdout of `preprocess.mjs` — each line is a path to a filtered session file.
+
+### Step 2: Extract sizing metrics
+
+Use quick one-liners to extract counts — do NOT read the full JSON files into the main context:
+
+```bash
+node .claude/skills/codeyam-memory/scripts/lib/read-json-field.mjs /tmp/codeyam-memory/deprecated-scan.json '.dependencies | length'
+node .claude/skills/codeyam-memory/scripts/lib/read-json-field.mjs /tmp/codeyam-memory/deprecated-scan.json '.explicit_markers | length'
+node .claude/skills/codeyam-memory/scripts/lib/read-json-field.mjs /tmp/codeyam-memory/exports-scan.json '.stats.total_exports'
+node .claude/skills/codeyam-memory/scripts/lib/read-json-field.mjs /tmp/codeyam-memory/exports-scan.json '.stats.total_files'
+```
+
+The session count is the number of lines from `preprocess.mjs` stdout.
+
+**Time estimate formulas:**
+
+| Phase                    | Formula                                 | Example                 |
+| ------------------------ | --------------------------------------- | ----------------------- |
+| Holistic source analysis | `3 + (total_exports / 500)` min, cap 12 | 3,470 exports → ~10 min |
+| Session log mining       | `1 + (sessions × 0.25)` min, cap 12     | 25 sessions → ~7 min    |
+
+### Step 3: Present the menu
+
+Use `AskUserQuestion` with `multiSelect: true`. Include actual numbers from Step 2:
+
+> **Which additional analysis phases would you like to run?**
+>
+> 📦 **Holistic Source Analysis** — {exports} exports across {files} files, {deps} dependencies, {markers} deprecation markers. Estimated: ~{N} min
+>
+> 💬 **Session Log Mining** — {sessions} qualifying sessions found. Estimated: ~{N} min
+
+Options (as `multiSelect: true`):
+
+- **Holistic Source Analysis (~N min)** — "Deep-read exports to find misleading APIs and deprecated patterns"
+- **Session Log Mining (~N min)** — "Mine Claude session history for confusion signals"
+- **Skip both** — "Proceed with git archaeology results only"
+
+Omit any option where the data count is zero (e.g., if no sessions qualify, don't show the session mining option). If both counts are zero, skip the menu entirely and proceed to Phase 4.
+
+### Step 4: Execute selected phases
+
+Based on the user's selection:
+
+- **Holistic Source Analysis selected:** Jump to the "Holistic Source Analysis" section below, starting at **Step 2** (scripts already ran in Step 1 above).
+- **Session Log Mining selected:** Jump to the "Session Log Mining" section below, starting at **Step 2** (preprocessing already ran in Step 1 above). Use the session file paths captured in Step 1.
+- **Both selected:** Run both, starting each at Step 2.
+- **Skip both:** Proceed directly to Phase 4.
+
+### Step 5: Cleanup
+
+Regardless of what the user selected, clean up temporary files before proceeding to Phase 4:
+
+```bash
+rm -rf /tmp/codeyam-memory/ /tmp/cc-session-analysis/
+```
+
+---
+
+## Additional Analysis Phase: Holistic Source Analysis
+
+Holistic analysis reads the codebase cross-cuttingly to find **latent confusion** — problems
+that haven't caused bugs yet but will mislead a future agent reading code locally.
+
+### Prerequisites
+
+- Project must contain `.ts`, `.tsx`, `.js`, or `.jsx` source files
+- If no source files are found, skip this phase entirely
+
+### Step 1: Run extraction scripts
+
+Handled by Phase 3B. Proceed to Step 2.
+
+### Step 2: Launch analysis subagents (concurrent)
+
+Read the prompt templates and launch both as Task agents concurrently. **Do NOT read the
+scan data into the main context** — it can be hundreds of KB. Each subagent reads its own
+data file via the Read tool.
+
+1. **Deprecated Pattern agent** — Read `.claude/skills/codeyam-memory/scripts/holistic-analysis/deprecated-prompt.md` for the
+   prompt template. Launch as a foreground Task agent (model: sonnet) with the prompt template
+   content. The agent reads `/tmp/codeyam-memory/deprecated-scan.json` itself, uses Grep to
+   find remaining callsites, and returns its findings JSON in the response.
+
+2. **Misleading API agent** — Read `.claude/skills/codeyam-memory/scripts/holistic-analysis/misleading-api-prompt.md` for the
+   prompt template. Launch as a foreground Task agent (model: sonnet) with the prompt template
+   content. The agent reads `/tmp/codeyam-memory/exports-scan.json` itself, uses Read to
+   inspect suspicious functions, and returns its findings JSON in the response.
+
+Both agents return their findings JSON and a brief summary directly in their response.
+
+**Context budget note:** The exports index alone can be 400KB+. Never read it into the main
+context. Subagents run as foreground Task agents and have full filesystem access including
+`/tmp/`.
+
+### Step 3: Integrate findings
+
+Parse the findings JSON from each subagent's response. For each finding:
+
+- **Deprecated patterns** get confusion score **4** (comparable to "workaround/hack" signal).
+  If an explicit `@deprecated` marker exists, bump to **5**.
+- **Misleading APIs** get confusion score **4** for medium severity, **6** for high severity
+  (where "high" means the mismatch could cause data corruption or silent failures).
+
+Add findings to the evidence pool alongside git archaeology results. They flow into
+Phase 4 (evidence-based user questions) and Phase 5 (rule generation) normally.
+
+### Step 4: Cleanup
+
+Handled by Phase 3B Step 5.
+
+---
+
+## Additional Analysis Phase: Session Log Mining
+
+This phase mines Claude Code session transcripts for empirical confusion: user corrections, wrong assumptions, re-edits, tribal knowledge gaps. It complements the git archaeology in Phase 2 with direct evidence from actual Claude sessions.
+
+### Step 1: Preprocess Sessions
+
+Handled by Phase 3B. Use the session file paths captured there.
+
+### Step 2: Launch Haiku Subagents
+
+Read the prompt template from `.claude/skills/codeyam-memory/scripts/session-mining/analyze-prompt.md`.
+
+For each filtered session file from Step 1:
+
+- If the file is **<200KB**: launch one Haiku Task agent
+- If the file is **>200KB**: chunk into ~200KB segments, launch one agent per chunk
+
+**Do NOT read session files into the main context** — they can be 20-40KB each and will
+exhaust the context window. Each subagent reads its own file via the Read tool. Each agent
+receives:
+
+1. The prompt template content
+2. The `/tmp/` file path to read (the agent reads it itself)
+3. Instruction to return a JSON array
+
+Launch agents in batches of **10** using the Task tool with `model: "haiku"`. **Use unique descriptions** for each agent (e.g., "Session mining batch 1 - session 1", "Session mining batch 1 - session 2", etc.; increment the batch number for each batch of 10). Wait for each batch to complete before launching the next. This keeps machine load manageable — a poweruser may have 30+ sessions qualifying.
+
+### Step 3: Collect and Validate Findings
+
+Parse each agent's response as JSON. Validate:
+
+- Must be an array
+- Each element must have `signal` and `summary` fields
+- `signal` must be one of: `USER_CORRECTION`, `RE_EDIT`, `FAILED_PIVOT`, `WRONG_ASSUMPTION`, `TRIBAL_KNOWLEDGE`, `APPROACH_PIVOT`
+
+If >50% of agents return invalid output, warn the user before continuing. Otherwise, silently skip invalid results.
+
+**Filter out environment-specific findings.** Discard any finding that relates to the developer's local machine setup rather than the project's codebase — e.g., bare repo checkout layouts, local tool versions, IDE configuration, shell aliases, filesystem paths, or permission issues. The rules we generate must be useful to _any_ developer cloning the repo, not just the one whose sessions we mined.
+
+### Step 4: Deduplicate Across Sessions
+
+Three-pass merge:
+
+1. **Cluster by `topic`** — group all findings with the same topic label
+2. **Rank within each cluster** — priority order: `USER_CORRECTION` > `TRIBAL_KNOWLEDGE` > `WRONG_ASSUMPTION` > `FAILED_PIVOT` > `RE_EDIT` > `APPROACH_PIVOT`
+3. **Count session occurrences** — add `session_count` to each merged finding
+
+Output: one merged finding per topic, with `session_count`, strongest signal type, and collected file paths.
+
+### Step 5: Feed into Phase 3 Scoring
+
+Additional scoring weights for session-mining signals:
+
+| Signal                              | Weight   |
+| ----------------------------------- | -------- |
+| User correction (session)           | 7        |
+| Tribal knowledge provided (session) | 6        |
+| Wrong assumption caught (session)   | 5        |
+| Re-edit of same file (session)      | 4        |
+| Failed-then-pivoted (session)       | 3        |
+| Appearing in 3+ sessions            | +3 bonus |
+
+These merge into the Phase 3 scoring table above. Session-mined findings then flow into Phase 4 (evidence-based questions) and Phase 5 (rule generation) alongside git archaeology findings.
+
+### Step 6: Cleanup
+
+Handled by Phase 3B Step 5.
+
 ---
 
 ## Phase 4: Ask Evidence-Based Questions
@@ -282,6 +491,12 @@ Before generating each rule, verify it passes these tests:
 - If YES → definitely document it
 - If NO → reconsider its value
 
+**For holistic analysis findings**, the validation checks apply with these adjustments:
+
+- **Evidence check:** Satisfied by structural evidence from source analysis (e.g., "name implies pure computation but implementation writes to cache on line 47") rather than git commit history.
+- **Code-derivable check:** These findings ARE derived from code — but from a cross-cutting read that a local reader wouldn't perform. The rule is valuable if it captures insight that requires reading multiple files or tracing non-obvious call chains.
+- **Prevention check:** "Would this rule prevent a future agent from being misled?" rather than "would it have prevented a past commit?"
+
 ### Rule Quality Examples
 
 **✅ Good rule** (passes all tests):

package/codeyam-cli/templates/skills/codeyam-memory/scripts/holistic-analysis/deprecated-prompt.md

@@ -0,0 +1,100 @@
+# Deprecated Pattern Analysis
+
+You are analyzing a codebase for **deprecated patterns** — situations where two approaches to the same problem coexist, with one fading in favor of another. These create confusion because a coding agent reading locally may follow the old pattern.
+
+## Input
+
+Read the scan data from `/tmp/codeyam-memory/deprecated-scan.json`. It contains:
+
+- `dependencies`: All npm dependency names from the project
+- `explicit_markers`: Lines containing `@deprecated`, `// legacy`, etc., with file, line number, and text
+- `git_recency`: Per-dependency counts of `recent_imports` (last 3 months) vs `old_imports` (3–12 months ago)
+
+## Analysis Steps
+
+### 1. Dependency Overlap Analysis
+
+Review the full dependency list and identify pairs or groups that serve **overlapping purposes**. Use your domain knowledge of the npm ecosystem — don't rely on name similarity alone.
+
+Common overlap categories:
+
+- **ORMs / query builders**: knex, kysely, prisma, drizzle, typeorm, sequelize, supabase-js (when used for queries)
+- **Date libraries**: moment, dayjs, date-fns, luxon
+- **HTTP clients**: axios, got, node-fetch, ky, superagent, undici
+- **State management**: redux, zustand, jotai, recoil, mobx, valtio
+- **Schema validation**: zod, yup, joi, ajv, io-ts, superstruct, valibot
+- **CSS-in-JS / styling**: styled-components, emotion, tailwind, vanilla-extract, stitches
+- **Testing**: jest, vitest, mocha, ava
+- **Bundlers**: webpack, vite, esbuild, rollup, parcel, turbopack
+- **Logging**: winston, pino, bunyan, log4js
+
+Also look for:
+
+- Internal packages that wrap the same underlying library differently
+- Old utility files alongside newer replacements
+
+### 2. Cross-Reference with Git Recency
+
+For each overlapping pair you identified, check the `git_recency` data:
+
+- Is one dependency's import count **growing** (more recent than old) while the other is **fading** (fewer recent than old)?
+- A clear growth-vs-fade pattern confirms a migration in progress.
+- If both are stable or both are growing, it may be intentional coexistence rather than a migration.
+
+### 3. Cross-Reference with Explicit Markers
+
+Check if any `@deprecated` or `// legacy` markers corroborate your dependency findings:
+
+- A marker on code that imports the fading dependency strengthens the signal
+- A marker on a wrapper/utility that abstracts one of the approaches is strong evidence
+
+### 4. Find Remaining Callsites
+
+For each confirmed deprecated pattern, use Grep to find all files still importing or using the old dependency/pattern. Count the callsites to assess migration completeness.
+
+Search patterns:
+
+```
+from ['"]<old-dep>
+require(['"]<old-dep>
+import <old-dep>
+```
+
+### 5. Assess Severity
+
+- **high**: Active migration with significant remaining old callsites (>10 files), or explicit deprecation markers present
+- **medium**: Clear trend in git recency but no explicit markers and fewer remaining callsites
+- **low**: Slight trend, possibly intentional coexistence
+
+## Output
+
+Return your findings as a JSON code block in your response, using this format:
+
+```json
+{
+  "findings": [
+    {
+      "type": "deprecated-pattern",
+      "old_pattern": "descriptive name of the old approach",
+      "new_pattern": "descriptive name of the new approach",
+      "evidence": "concise summary of the evidence (git recency numbers, markers found)",
+      "files_still_using_old": ["path/to/file1.ts", "path/to/file2.ts"],
+      "severity": "high|medium|low",
+      "suggested_rule_paths": ["src/relevant/**/*.ts"]
+    }
+  ],
+  "stats": {
+    "deps_analyzed": 0,
+    "overlapping_pairs_found": 0,
+    "confirmed_deprecated": 0
+  }
+}
+```
+
+After the JSON block, return a **brief one-paragraph summary** of your findings. Include the number of confirmed deprecated patterns and the highest-severity finding.
+
+## Important Notes
+
+- Be conservative: only flag patterns where there is clear evidence of transition, not just the presence of two similar libraries
+- Some projects intentionally use multiple tools in the same category (e.g., jest for unit tests and playwright for e2e) — that's not deprecation
+- Focus on patterns that would **mislead a coding agent** — if both approaches are valid and documented, it may not need a rule

package/codeyam-cli/templates/skills/codeyam-memory/scripts/holistic-analysis/detect-deprecated-patterns.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+// Gathers deprecation signals from package.json, source markers, and git history.
+// Outputs structured JSON to /tmp/codeyam-memory/deprecated-scan.json
+
+import { readdir, readFile, mkdir, writeFile } from 'node:fs/promises';
+import { execFileSync } from 'node:child_process';
+import { join } from 'node:path';
+import { ripgrepSearch } from '../lib/ripgrep-fallback.mjs';
+
+const OUTPUT_DIR = '/tmp/codeyam-memory';
+const OUTPUT_FILE = join(OUTPUT_DIR, 'deprecated-scan.json');
+await mkdir(OUTPUT_DIR, { recursive: true });
+
+// --- Dependency scan ---
+// Collect all dependency names from package.json files
+const allDeps = new Set();
+const packageFiles = await findFiles('.', 'package.json', ['node_modules', 'dist', '.next']);
+
+for (const pkgPath of packageFiles) {
+  try {
+    const pkg = JSON.parse(await readFile(pkgPath, 'utf-8'));
+    for (const key of ['dependencies', 'devDependencies']) {
+      if (pkg[key] && typeof pkg[key] === 'object') {
+        for (const dep of Object.keys(pkg[key])) allDeps.add(dep);
+      }
+    }
+  } catch {
+    // Skip unparseable package.json
+  }
+}
+
+const dependencies = [...allDeps].sort();
+
+// --- Explicit marker scan ---
+let explicitMarkers = [];
+
+const markerOutput = await ripgrepSearch(
+  '@deprecated|// legacy|// deprecated|// old approach|TODO.*deprecat|FIXME.*deprecat',
+  {
+    types: ['ts', 'js'],
+    globs: ['!node_modules', '!dist', '!build', '!.next'],
+    context: 2,
+    lineNumbers: true,
+  },
+);
+
+if (markerOutput.trim()) {
+  // Parse ripgrep output into structured entries
+  for (const line of markerOutput.split('\n')) {
+    // Match "file:line:text" (colons in file path unlikely for these repos)
+    const match = line.match(/^([^:]+):(\d+):(.*)$/);
+    if (match) {
+      explicitMarkers.push({
+        file: match[1],
+        line: parseInt(match[2], 10),
+        text: match[3].trim(),
+      });
+    }
+  }
+}
+
+// --- Git recency comparison ---
+const gitRecency = {};
+
+if (dependencies.length > 0) {
+  const recentImports = gitImports('3 months ago', undefined);
+  const oldImports = gitImports('12 months ago', '3 months ago');
+
+  for (const dep of dependencies) {
+    if (dep.length < 3) continue; // Skip short names that match too broadly
+
+    const pattern = `from ['"]${dep}`;
+    const recent = countMatches(recentImports, pattern);
+    const old = countMatches(oldImports, pattern);
+
+    if (recent > 0 || old > 0) {
+      gitRecency[dep] = { recent_imports: recent, old_imports: old };
+    }
+  }
+}
+
+// --- Assemble final output ---
+const output = {
+  dependencies,
+  explicit_markers: explicitMarkers,
+  git_recency: gitRecency,
+};
+
+await writeFile(OUTPUT_FILE, JSON.stringify(output, null, 2));
+
+console.log(`Deprecated pattern scan complete: ${OUTPUT_FILE}`);
+console.log(`  Dependencies found: ${dependencies.length}`);
+console.log(`  Explicit markers found: ${explicitMarkers.length}`);
+console.log(`  Deps with git activity: ${Object.keys(gitRecency).length}`);
+
+// --- Helpers ---
+
+async function findFiles(dir, filename, ignoreDirs) {
+  const results = [];
+  const ignoreSet = new Set(ignoreDirs);
+
+  let entries;
+  try {
+    entries = await readdir(dir, { recursive: true, withFileTypes: true });
+  } catch {
+    return results;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isFile() || entry.name !== filename) continue;
+    const parentPath = entry.parentPath ?? entry.path; // parentPath in Node 22+
+    const parts = parentPath.split('/');
+    if (parts.some((p) => ignoreSet.has(p))) continue;
+    results.push(join(parentPath, entry.name));
+  }
+  return results;
+}
+
+function gitImports(since, until) {
+  const args = ['log', `--since=${since}`, '-p', '--', '*.ts', '*.tsx', '*.js', '*.jsx'];
+  if (until) args.splice(2, 0, `--until=${until}`);
+
+  try {
+    const output = execFileSync('git', args, {
+      maxBuffer: 100 * 1024 * 1024,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return output;
+  } catch {
+    return '';
+  }
+}
+
+function countMatches(text, pattern) {
+  const regex = new RegExp(pattern, 'g');
+  const matches = text.match(regex);
+  return matches ? matches.length : 0;
+}

package/codeyam-cli/templates/skills/codeyam-memory/scripts/holistic-analysis/find-exports.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// Indexes the project's public API surface by finding all exports.
+// Outputs structured JSON to /tmp/codeyam-memory/exports-scan.json
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { ripgrepSearch } from '../lib/ripgrep-fallback.mjs';
+
+const OUTPUT_DIR = '/tmp/codeyam-memory';
+const OUTPUT_FILE = join(OUTPUT_DIR, 'exports-scan.json');
+await mkdir(OUTPUT_DIR, { recursive: true });
+
+const exportOutput = await ripgrepSearch(
+  '^export (function|const|class|default|async function|type|interface|enum)',
+  {
+    types: ['ts', 'js'],
+    globs: ['!node_modules', '!dist', '!build', '!.next', '!*.d.ts', '!*.map'],
+    lineNumbers: true,
+  },
+);
+
+if (!exportOutput.trim()) {
+  const empty = { files: {}, stats: { total_files: 0, total_exports: 0 } };
+  await writeFile(OUTPUT_FILE, JSON.stringify(empty, null, 2));
+  console.log(`Export scan complete: ${OUTPUT_FILE} (no exports found)`);
+  process.exit(0);
+}
+
+// Parse ripgrep output and group by file
+const files = {};
+for (const line of exportOutput.split('\n')) {
+  const match = line.match(/^([^:]+):(\d+):(.*)$/);
+  if (!match) continue;
+
+  const [, file, lineNum, text] = match;
+  if (!files[file]) files[file] = [];
+  files[file].push({ line: parseInt(lineNum, 10), text: text.trim() });
+}
+
+const totalFiles = Object.keys(files).length;
+const totalExports = Object.values(files).reduce((sum, arr) => sum + arr.length, 0);
+
+const output = {
+  files,
+  stats: { total_files: totalFiles, total_exports: totalExports },
+};
+
+await writeFile(OUTPUT_FILE, JSON.stringify(output, null, 2));
+
+console.log(`Export scan complete: ${OUTPUT_FILE}`);
+console.log(`  Files with exports: ${totalFiles}`);
+console.log(`  Total exports: ${totalExports}`);