contextdevkit 1.8.0

package/templates/contextkit/tools/scripts/agent-tuning.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+/**
+ * Agent-tuning signals — the deterministic half of /tune-agents.
+ *
+ * Aggregates the signals available for refining agent briefings: the roster +
+ * tier-2 briefing coverage, and how often each agent is referenced across the
+ * session history (a usage proxy). `/tune-agents` reads this, adds judgment, and
+ * PROPOSES briefing edits — it never auto-applies (mirrors /distill-sessions).
+ *
+ *   agent-tuning.mjs            # human summary
+ *   agent-tuning.mjs --json     # { agents: [...], sessionsAnalyzed, withoutBriefing }
+ *
+ * Zero-dependency, defensive: degrades to empty signals, never throws.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { squadOf } from './squad-meta.mjs';
+import { pathsFor } from '../../runtime/config/paths.mjs';
+
+const ROOT = process.cwd();
+const P = pathsFor(ROOT);
+const AGENTS = resolve(ROOT, '.claude/agents');
+const SQUADS = P.squads;
+const SESSIONS = P.sessions;
+
+function read(p) {
+  try {
+    return readFileSync(p, 'utf-8');
+  } catch {
+    return '';
+  }
+}
+
+function listMd(dir) {
+  try {
+    return readdirSync(dir).filter((f) => f.endsWith('.md'));
+  } catch {
+    return [];
+  }
+}
+
+function collect() {
+  const agentFiles = listMd(AGENTS).filter((f) => f !== '_TEMPLATE.md');
+  const sessions = listMd(SESSIONS).map((f) => read(resolve(SESSIONS, f)));
+  const agents = agentFiles.map((f) => {
+    const name = f.slice(0, -3);
+    const squad = squadOf(AGENTS, name);
+    return {
+      name,
+      squad,
+      hasBriefing: existsSync(resolve(SQUADS, squad, `${name}.md`)),
+      mentions: sessions.filter((s) => s.includes(name)).length,
+    };
+  });
+  agents.sort((a, b) => b.mentions - a.mentions);
+  return { agents, sessionsAnalyzed: sessions.length, withoutBriefing: agents.filter((a) => !a.hasBriefing).map((a) => a.name) };
+}
+
+function main() {
+  const s = collect();
+  if (process.argv.includes('--json')) {
+    process.stdout.write(JSON.stringify(s, null, 2) + '\n');
+    return;
+  }
+  if (!s.agents.length) {
+    console.log('🎯 agent-tuning: no agents found (Level < 4?).');
+    return;
+  }
+  console.log(`🎯 agent-tuning signals — ${s.agents.length} agents, ${s.sessionsAnalyzed} sessions analyzed\n`);
+  for (const a of s.agents) console.log(`   ${a.hasBriefing ? '📄' : '  '} ${a.name}  (${a.squad})  ${a.mentions} mention(s)`);
+  console.log(`\n   ${s.withoutBriefing.length} agent(s) without a tier-2 briefing. Run /tune-agents to propose refinements.`);
+}
+
+main();

package/templates/contextkit/tools/scripts/aiso-audit.mjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+/**
+ * AISO audit — static analyser for AI Search Optimization smells (ADR-0025).
+ *
+ * AISO is the discoverability surface for LLM answer engines
+ * (ChatGPT search, Perplexity, Claude search, Gemini). A site can rank
+ * well on Google and never appear in LLM answers — this audit catches
+ * the missing patterns: `llms.txt`, FAQ schema, semantic HTML5,
+ * author + date stamps, and a `robots.txt` that does not block AI
+ * crawlers by accident.
+ *
+ * Same shape as seo-audit.mjs: walks page files, emits findings,
+ * supports `--json`. Zero deps. Defensive.
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, relative } from 'node:path';
+import { lineOf, renderFindings, exitCodeFor, walkProject } from './audit-shared.mjs';
+
+const PAGE_EXTS = ['.html', '.astro', '.jsx', '.tsx', '.vue', '.svelte', '.mdx'];
+
+const SEVERITY = {
+  MISSING_LLMS_TXT:       'high',
+  MISSING_FAQ_SCHEMA:     'high',
+  MISSING_ORG_SCHEMA:     'medium',
+  DIV_SOUP:               'medium',
+  JS_RENDERED_CONTENT:    'high',
+  MISSING_AUTHOR_SCHEMA:  'low',
+  MISSING_DATE_STAMP:     'low',
+  BLOCKS_AI_CRAWLERS:     'high',
+};
+
+const finding = (rel) => (code, line, message) =>
+  ({ file: rel, code, line, severity: SEVERITY[code] || 'medium', message });
+
+const AI_CRAWLERS = ['GPTBot', 'ClaudeBot', 'PerplexityBot', 'Google-Extended', 'OAI-SearchBot'];
+
+/** robots.txt smells: missing file (handled by seo-audit) and AI-crawler disallow without explicit override. */
+function checkRobots(root) {
+  const out = [];
+  const robotsPaths = ['robots.txt', 'public/robots.txt', 'static/robots.txt'];
+  const robotsPath = robotsPaths.map((p) => resolve(root, p)).find((p) => existsSync(p));
+  if (!robotsPath) return out;
+  let txt = '';
+  try { txt = readFileSync(robotsPath, 'utf8'); } catch { return out; }
+  for (const ua of AI_CRAWLERS) {
+    const block = new RegExp(`User-agent:\\s*${ua}[\\s\\S]*?Disallow:\\s*/`, 'i');
+    if (block.test(txt)) {
+      out.push({
+        file: relative(root, robotsPath).replaceAll('\\', '/'),
+        code: 'BLOCKS_AI_CRAWLERS',
+        line: 0,
+        severity: SEVERITY.BLOCKS_AI_CRAWLERS,
+        message: `robots.txt blocks ${ua}; the site will not appear in that LLM's answers. Add a project ADR if this is intentional.`,
+      });
+    }
+  }
+  return out;
+}
+
+/** llms.txt presence — the 2024-vintage AISO convention. */
+function checkLlmsTxt(root) {
+  const paths = ['llms.txt', 'public/llms.txt', 'static/llms.txt'];
+  if (paths.some((p) => existsSync(resolve(root, p)))) return [];
+  return [{
+    file: 'public/llms.txt',
+    code: 'MISSING_LLMS_TXT',
+    line: 0,
+    severity: SEVERITY.MISSING_LLMS_TXT,
+    message: 'no llms.txt at root — LLM answer engines have no curated routing map. See llmstxt.org for the format.',
+  }];
+}
+
+/** Per-file AISO checks: FAQ + Org schema, div-soup, JS-rendered content, author + date stamps. */
+function checkFile(file, text, rel) {
+  const f = finding(rel);
+  const out = [];
+  const isHtmlLike = /\.(html|astro)$/i.test(file);
+
+  if (!isHtmlLike) return out;
+
+  // FAQ schema — the load-bearing AISO move
+  if (!/"@type":\s*"FAQPage"/.test(text)) {
+    out.push(f('MISSING_FAQ_SCHEMA', 1, 'no FAQPage JSON-LD — LLMs cite FAQ entries near-verbatim; without it the page does not appear in answers'));
+  }
+
+  // Organization schema
+  if (!/"@type":\s*"Organization"/.test(text)) {
+    out.push(f('MISSING_ORG_SCHEMA', 1, 'no Organization JSON-LD — brand entity unknown to LLM rankers'));
+  }
+
+  // Author / person schema (low — only flags if completely absent)
+  if (!/"@type":\s*"(Person|Article|NewsArticle)"/.test(text) && /<article/i.test(text)) {
+    out.push(f('MISSING_AUTHOR_SCHEMA', 1, 'page has <article> but no Person/Article schema — LLMs weight authored content over anonymous'));
+  }
+
+  // Date stamps
+  if (!/(datePublished|dateModified|article:modified_time)/i.test(text)) {
+    out.push(f('MISSING_DATE_STAMP', 1, 'no published/modified timestamp — LLMs care about recency'));
+  }
+
+  // Div soup: ratio of <div> to semantic HTML5 tags
+  const divs = (text.match(/<div[\s>]/gi) || []).length;
+  const semantic = (text.match(/<(article|section|nav|main|aside|header|footer)[\s>]/gi) || []).length;
+  if (divs > 5 && semantic > 0 && divs / Math.max(semantic, 1) > 5) {
+    out.push(f('DIV_SOUP', 1, `${divs} <div> to ${semantic} semantic tags (ratio ${(divs / semantic).toFixed(1)}:1) — LLM extractors weight semantic HTML5`));
+  } else if (divs > 10 && semantic === 0) {
+    out.push(f('DIV_SOUP', 1, `${divs} <div> with no semantic HTML5 tags at all — use <article>, <section>, <nav>, <main>`));
+  }
+
+  // JS-rendered content heuristic: large <script> with template-like content but tiny <body>
+  const bodyMatch = /<body[^>]*>([\s\S]*?)<\/body>/i.exec(text);
+  if (bodyMatch) {
+    const bodyText = bodyMatch[1].replace(/<[^>]+>/g, '').trim();
+    const scripts = [...text.matchAll(/<script[^>]*>([\s\S]*?)<\/script>/gi)];
+    const heavyScript = scripts.some((m) => m[1].length > 2000);
+    if (bodyText.length < 200 && heavyScript) {
+      out.push(f('JS_RENDERED_CONTENT', lineOf(text, bodyMatch.index), 'body text < 200 chars but script body > 2 kB — content appears JS-rendered; LLM crawlers may miss it'));
+    }
+  }
+  return out;
+}
+
+/**
+ * Run the AISO audit against a project root.
+ *
+ * @param {string} root
+ * @returns {{ findings: object[] }}
+ */
+export function runAisoAudit(root) {
+  const findings = [...checkLlmsTxt(root), ...checkRobots(root)];
+  for (const file of walkProject(root, PAGE_EXTS)) {
+    let text = '';
+    try { text = readFileSync(file, 'utf8'); } catch { continue; }
+    findings.push(...checkFile(file, text, relative(root, file).replaceAll('\\', '/')));
+  }
+  return { findings };
+}
+
+const argv = process.argv.slice(2);
+const wantJson = argv.includes('--json');
+const wantHelp = argv.includes('--help') || argv.includes('-h');
+
+const isMain = (() => {
+  try {
+    const here = new URL(import.meta.url).pathname.toLowerCase();
+    const entry = process.argv[1]
+      ? new URL('file://' + process.argv[1].replace(/\\/g, '/')).pathname.toLowerCase()
+      : '';
+    return here === entry;
+  } catch { return false; }
+})();
+
+if (isMain) {
+  if (wantHelp) {
+    process.stdout.write(`Usage: aiso-audit.mjs [--json]
+
+Scans the project for AI Search Optimization smells per ADR-0025.
+AISO is about LLM answer-engine discoverability (ChatGPT, Perplexity,
+Claude, Gemini) — orthogonal to classical SEO.
+
+  --json   emit findings as JSON to stdout
+  --help   this message
+`);
+    process.exit(0);
+  }
+  const root = process.cwd();
+  const result = runAisoAudit(root);
+  if (wantJson) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  } else {
+    process.stdout.write(renderFindings(result.findings, { title: 'AISO audit' }));
+  }
+  process.exit(exitCodeFor(result.findings));
+}

package/templates/contextkit/tools/scripts/audit-shared.mjs

@@ -0,0 +1,129 @@
+/**
+ * Shared helpers for the SEO + AISO audit scripts (ADR-0025).
+ *
+ * - `walkProject(root, exts)` — recursive file walk that skips the usual
+ *   noise (`node_modules`, `.git`, `dist`, `build`, framework caches).
+ * - `detectFramework(root)` — reads package.json and reports the
+ *   rendering posture (`astro`, `next`, `nuxt`, `remix`, `sveltekit`,
+ *   `vite-react`, or `null`).
+ * - `lineOf(text, idx)` — 1-based line number for a regex match index.
+ * - `renderFindings(findings)` — pretty terminal output, grouped by
+ *   severity. JSON output handled by the calling script.
+ *
+ * Zero deps. Defensive: any failure returns a safe default (empty
+ * array, `null` framework) — rule 2.
+ */
+import { readFileSync, readdirSync } from 'node:fs';
+import { join, extname } from 'node:path';
+
+const SKIP_DIRS = /(^|[\\/])(node_modules|\.git|dist|build|out|\.next|\.astro|\.nuxt|\.svelte-kit|\.cache|coverage|\.vercel|\.netlify|\.turbo)([\\/]|$)/;
+
+/**
+ * Walk a directory recursively yielding files with one of the given
+ * extensions. Skips noise dirs. Defensive — unreadable subdirs are
+ * silently skipped.
+ *
+ * @param {string}   root
+ * @param {string[]} exts  e.g. ['.html', '.astro', '.jsx']
+ */
+export function* walkProject(root, exts) {
+  const stack = [root];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); }
+    catch { continue; }
+    for (const e of entries) {
+      const full = join(dir, e.name);
+      if (SKIP_DIRS.test(full)) continue;
+      if (e.isDirectory()) stack.push(full);
+      else if (exts.includes(extname(e.name))) yield full;
+    }
+  }
+}
+
+/**
+ * Best-effort framework detection from package.json. The result drives
+ * the SPA_ENTRYPOINT refusal in seo-audit.
+ *
+ * @param {string} root
+ * @returns {'astro' | 'next' | 'nuxt' | 'remix' | 'sveltekit' | 'vite-react' | 'gatsby' | 'eleventy' | null}
+ */
+export function detectFramework(root) {
+  let pkg;
+  try {
+    pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8').replace(/^/, ''));
+  } catch { return null; }
+  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  if (deps.astro) return 'astro';
+  if (deps.next) return 'next';
+  if (deps.nuxt) return 'nuxt';
+  if (deps['@remix-run/react'] || deps['@remix-run/node']) return 'remix';
+  if (deps['@sveltejs/kit']) return 'sveltekit';
+  if (deps.gatsby) return 'gatsby';
+  if (deps['@11ty/eleventy']) return 'eleventy';
+  if (deps.vite && (deps.react || deps['react-dom'])) return 'vite-react';
+  return null;
+}
+
+/** True when the detected framework leaves the user responsible for SSR/SSG wiring. */
+export const isSpaFramework = (fw) => fw === 'vite-react' || fw === null;
+
+/** True when the detected framework ships SSG / SSR by default. */
+export const isIndexableFramework = (fw) =>
+  fw === 'astro' || fw === 'next' || fw === 'nuxt' || fw === 'remix' ||
+  fw === 'sveltekit' || fw === 'gatsby' || fw === 'eleventy';
+
+/**
+ * 1-based line number for the character at `idx` in `text`.
+ *
+ * @param {string} text
+ * @param {number} idx
+ * @returns {number}
+ */
+export function lineOf(text, idx) {
+  if (idx <= 0) return 1;
+  let n = 1;
+  for (let i = 0; i < idx; i++) if (text.charCodeAt(i) === 10) n++;
+  return n;
+}
+
+const SEV_ORDER = ['critical', 'high', 'medium', 'low'];
+const SEV_LABEL = {
+  critical: '\x1b[31mCRITICAL\x1b[0m',
+  high:     '\x1b[33mHIGH    \x1b[0m',
+  medium:   '\x1b[36mMEDIUM  \x1b[0m',
+  low:      '\x1b[90mLOW     \x1b[0m',
+};
+
+/**
+ * Render findings as a coloured terminal table grouped by severity.
+ *
+ * @param {Array<{ code:string, file:string, line:number, severity:string, message:string }>} findings
+ * @param {object} opts
+ * @param {string} opts.title
+ * @returns {string}
+ */
+export function renderFindings(findings, { title }) {
+  if (!findings.length) {
+    return `\n🔍 ${title}\n   ✅ no findings — all checks passed.\n`;
+  }
+  const bySev = Object.fromEntries(SEV_ORDER.map((s) => [s, []]));
+  for (const f of findings) (bySev[f.severity] || bySev.medium).push(f);
+  const lines = [`\n🔍 ${title}`, `   ${findings.length} finding${findings.length === 1 ? '' : 's'}\n`];
+  for (const sev of SEV_ORDER) {
+    if (!bySev[sev].length) continue;
+    lines.push(`   ${SEV_LABEL[sev]} (${bySev[sev].length})`);
+    for (const f of bySev[sev]) {
+      const loc = f.line ? `:${f.line}` : '';
+      lines.push(`     ${f.code.padEnd(22, ' ')} ${f.file}${loc}`);
+      if (f.message) lines.push(`       ↳ ${f.message}`);
+    }
+    lines.push('');
+  }
+  return lines.join('\n') + '\n';
+}
+
+/** Convenience: exit code from findings (1 if any critical, 0 otherwise). */
+export const exitCodeFor = (findings) =>
+  findings.some((f) => f.severity === 'critical') ? 1 : 0;

package/templates/contextkit/tools/scripts/claim.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * Reserves resources for the current session (Level >= 3) — paths and, since
+ * [ADR-0015 §B](../../memory/decisions/0015-pipeline-dsl-working-stage-and-multi-session-work-claims.md),
+ * DevPipeline task ids. Writes/updates `.claude/.workspace/<sid>.json`, then
+ * regenerates `contextkit/memory/WORKSPACE.md`. The current session id is read
+ * from the `.last-touched` pointer the hooks maintain.
+ *
+ * Usage:  node contextkit/tools/scripts/claim.mjs <path> [path2 ...]
+ * API:    attachTask(taskId) / detachTask(taskId) — used by pipeline.mjs
+ *         start|stop so task ownership flows through the same single source
+ *         of truth as path ownership.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { sanitizeSid } from '../../runtime/hooks/ledger.mjs';
+import { writeFileAtomic } from '../../runtime/hooks/safe-io.mjs';
+
+const ROOT = process.cwd();
+const WS_DIR = resolve(ROOT, '.claude/.workspace');
+const LAST_TOUCHED = resolve(ROOT, '.claude/.sessions/.last-touched');
+
+// execFileSync (argv array, no shell) — consistent with the other git callers.
+function gitOut(args, fallback) {
+  try {
+    return execFileSync('git', args, { cwd: ROOT, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+async function sessionId() {
+  try {
+    return JSON.parse(await readFile(LAST_TOUCHED, 'utf-8')).sessionId;
+  } catch {
+    return `local_${process.pid}`;
+  }
+}
+
+/**
+ * Loads (or creates) the current session's workspace record. Backward-compat:
+ * records without `tasks[]` get an empty default so old sessions parse fine.
+ *
+ * @param {string} sid — already sanitized
+ * @returns {Promise<{ sessionId, branch, user, startedAt, lastHeartbeat, claims, tasks, file }>}
+ */
+async function loadRecord(sid) {
+  await mkdir(WS_DIR, { recursive: true });
+  const file = resolve(WS_DIR, `${sid}.json`);
+  const fresh = { sessionId: sid, branch: gitOut(['symbolic-ref', '--short', 'HEAD'], 'detached'), user: gitOut(['config', 'user.name'], 'unknown'), startedAt: Date.now(), lastHeartbeat: Date.now(), claims: [], tasks: [] };
+  if (!existsSync(file)) return { ...fresh, file };
+  try {
+    const existing = JSON.parse(await readFile(file, 'utf-8'));
+    return { ...fresh, ...existing, tasks: Array.isArray(existing.tasks) ? existing.tasks : [], file };
+  } catch {
+    return { ...fresh, file };
+  }
+}
+
+async function persistRecord(record) {
+  record.lastHeartbeat = Date.now();
+  const { file, ...body } = record;
+  await writeFileAtomic(file, JSON.stringify(body, null, 2));
+  try {
+    execFileSync('node', ['contextkit/tools/scripts/workspace-sync.mjs'], { cwd: ROOT, stdio: 'ignore' });
+  } catch {
+    /* best effort */
+  }
+}
+
+/**
+ * Attaches a DevPipeline task id to the current session's record (ADR-0015 §B).
+ * Called by `pipeline.mjs start <id>`. Idempotent: re-attaching a task id is a
+ * no-op (heartbeat refresh only).
+ *
+ * @param {string} taskId
+ */
+export async function attachTask(taskId) {
+  const sid = sanitizeSid(await sessionId());
+  const record = await loadRecord(sid);
+  const id = String(taskId).padStart(3, '0');
+  const existing = record.tasks.find((t) => t.id === id);
+  if (existing) {
+    existing.lastHeartbeat = Date.now();
+  } else {
+    record.tasks.push({ id, startedAt: Date.now(), lastHeartbeat: Date.now() });
+  }
+  await persistRecord(record);
+}
+
+/**
+ * Detaches a DevPipeline task id from the current session's record. Called by
+ * `pipeline.mjs stop <id>` and by the stale-eviction sweep in workspace-sync.
+ * No-op if the task wasn't on this session's list.
+ *
+ * @param {string} taskId
+ */
+export async function detachTask(taskId) {
+  const sid = sanitizeSid(await sessionId());
+  const record = await loadRecord(sid);
+  const id = String(taskId).padStart(3, '0');
+  const before = record.tasks.length;
+  record.tasks = record.tasks.filter((t) => t.id !== id);
+  if (record.tasks.length === before) return;
+  await persistRecord(record);
+}
+
+async function main() {
+  const paths = process.argv.slice(2).map((p) => p.replaceAll('\\', '/'));
+  if (paths.length === 0) {
+    console.error('Usage: claim.mjs <path> [path2 ...]');
+    process.exit(1);
+  }
+  const sid = sanitizeSid(await sessionId());
+  const record = await loadRecord(sid);
+  const existing = new Set((record.claims || []).map((c) => c.path));
+  for (const p of paths) {
+    if (!existing.has(p)) record.claims.push({ path: p, claimedAt: Date.now() });
+  }
+  await persistRecord(record);
+  console.log(`✅ Claimed ${paths.length} path(s) for session ${sid.slice(0, 8)}: ${paths.join(', ')}`);
+}
+
+// Only run the CLI when invoked directly; library imports stay side-effect-free.
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
+  main().catch((err) => {
+    console.error('❌ claim failed:', err);
+    process.exit(1);
+  });
+}

package/templates/contextkit/tools/scripts/claude-md.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+/**
+ * Modular CLAUDE.md scaffolder.
+ *
+ * Like the source platform (root CLAUDE.md + apps/api/CLAUDE.md +
+ * apps/mobile/CLAUDE.md), each app / independent module should carry its OWN
+ * scoped CLAUDE.md so Claude Code loads the closest, most relevant rules. This
+ * detects module roots and ensures each has one.
+ *
+ * A "module root" is a directory that looks independently buildable: under a
+ * monorepo group (apps/ packages/ modules/ services/ libs/ apps-*), OR a
+ * conventional split dir (backend/ frontend/ client/ server/ api/ web/ mobile/
+ * desktop/ functions/ worker/), AND it contains a manifest or a src/.
+ *
+ * Usage:
+ *   node contextkit/tools/scripts/claude-md.mjs find [--json]
+ *   node contextkit/tools/scripts/claude-md.mjs scaffold   # create missing (stub) CLAUDE.md
+ */
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = process.cwd();
+// Installed at <project>/contextkit/tools/scripts/ → the seeded template is at <project>/contextkit/.
+const TPL = resolve(dirname(fileURLToPath(import.meta.url)), '../../CLAUDE.child.md.tpl');
+
+const GROUPS = ['apps', 'packages', 'modules', 'services', 'libs', 'plugins'];
+const SPLITS = ['backend', 'frontend', 'client', 'server', 'api', 'web', 'mobile', 'desktop', 'functions', 'worker', 'workers', 'app'];
+const MANIFESTS = ['package.json', 'pyproject.toml', 'go.mod', 'Cargo.toml', 'tsconfig.json', 'composer.json', 'Gemfile', 'pom.xml'];
+
+function looksBuildable(absDir) {
+  if (MANIFESTS.some((m) => existsSync(join(absDir, m)))) return true;
+  return existsSync(join(absDir, 'src'));
+}
+
+function dirsIn(absDir) {
+  try {
+    return readdirSync(absDir, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith('.')).map((e) => e.name);
+  } catch {
+    return [];
+  }
+}
+
+/** Detect module roots (depth 1 splits + depth 2 monorepo group children). */
+function detectModuleRoots() {
+  const roots = new Set();
+  for (const name of SPLITS) {
+    const abs = resolve(ROOT, name);
+    if (existsSync(abs) && looksBuildable(abs)) roots.add(name);
+  }
+  for (const group of GROUPS) {
+    const groupAbs = resolve(ROOT, group);
+    if (!existsSync(groupAbs)) continue;
+    for (const child of dirsIn(groupAbs)) {
+      const abs = join(groupAbs, child);
+      if (looksBuildable(abs)) roots.add(`${group}/${child}`);
+    }
+  }
+  return [...roots].sort();
+}
+
+function moduleStack(absDir) {
+  if (existsSync(join(absDir, 'package.json'))) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(absDir, 'package.json'), 'utf-8').replace(/^/, ''));
+      const deps = Object.keys({ ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) });
+      const known = ['react', 'next', 'expo', 'react-native', 'vue', 'svelte', 'hono', 'express', 'fastify', '@nestjs/core', 'drizzle-orm', 'prisma', 'vite'];
+      const found = known.filter((k) => deps.includes(k));
+      return `Node/TypeScript. ${found.length ? 'Detected: ' + found.join(', ') + '.' : '_TODO: fill in._'}`;
+    } catch {
+      /* ignore */
+    }
+  }
+  for (const [f, label] of [['pyproject.toml', 'Python'], ['go.mod', 'Go'], ['Cargo.toml', 'Rust']]) {
+    if (existsSync(join(absDir, f))) return `${label} (${f}).`;
+  }
+  return '_TODO: fill in this module\'s stack._';
+}
+
+function render(tpl, vars) {
+  return tpl.replace(/\{\{(\w+)\}\}/g, (_, k) => (k in vars ? vars[k] : `{{${k}}}`));
+}
+
+const cmd = process.argv[2];
+const roots = detectModuleRoots();
+const status = roots.map((r) => ({ module: r, hasClaudeMd: existsSync(resolve(ROOT, r, 'CLAUDE.md')) }));
+
+if (cmd === 'find') {
+  if (process.argv.includes('--json')) {
+    console.log(JSON.stringify({ moduleRoots: status }, null, 2));
+  } else if (status.length === 0) {
+    console.log('No app/module roots detected (single-package project — root CLAUDE.md is enough).');
+  } else {
+    console.log('Module roots:');
+    for (const s of status) console.log(`  ${s.hasClaudeMd ? '✓' : '✗'} ${s.module}/CLAUDE.md`);
+    const missing = status.filter((s) => !s.hasClaudeMd).length;
+    if (missing) console.log(`\n${missing} module(s) missing CLAUDE.md — run \`claude-md.mjs scaffold\` (or /claude-md).`);
+  }
+} else if (cmd === 'scaffold') {
+  if (!existsSync(TPL)) {
+    console.error(`Child template not found at ${TPL}.`);
+    process.exit(1);
+  }
+  const tpl = readFileSync(TPL, 'utf-8');
+  let created = 0;
+  for (const s of status) {
+    if (s.hasClaudeMd) continue;
+    const abs = resolve(ROOT, s.module);
+    const content = render(tpl, {
+      MODULE_NAME: s.module,
+      MODULE_PATH: s.module,
+      DATE: new Date().toISOString().slice(0, 10),
+      MODULE_STACK: moduleStack(abs),
+    });
+    writeFileSync(resolve(abs, 'CLAUDE.md'), content, 'utf-8');
+    created++;
+    console.log(`✓ created ${s.module}/CLAUDE.md`);
+  }
+  console.log(created === 0 ? 'All module roots already have a CLAUDE.md.' : `\n✅ Scaffolded ${created} scoped CLAUDE.md. Fill in the TODOs (or let /claude-md do it).`);
+} else {
+  console.error('Usage: claude-md.mjs <find|scaffold> [--json]');
+  process.exit(1);
+}