@cofoundr/init 1.5.0

package/src/adapters/index.mjs

@@ -0,0 +1,14 @@
+import { adapter as claudeCode } from './claude-code.mjs';
+import { adapter as cursor } from './cursor.mjs';
+import { adapter as windsurf } from './windsurf.mjs';
+import { adapter as cline } from './cline.mjs';
+import { adapter as codex } from './codex.mjs';
+import { adapter as aider } from './aider.mjs';
+import { adapter as copilot } from './copilot.mjs';
+import { adapter as gemini } from './gemini.mjs';
+
+export const adapters = [claudeCode, cursor, windsurf, cline, codex, aider, copilot, gemini];
+
+export function getAdapter(id) {
+  return adapters.find((a) => a.id === id);
+}

package/src/adapters/windsurf.mjs

@@ -0,0 +1,69 @@
+// Windsurf adapter.
+// Windsurf supports two formats: legacy `.windsurfrules` (single text file at the repo root)
+// and the newer `.windsurf/rules/*.md`. We write both for maximum compatibility.
+
+import { join } from 'node:path';
+import { writeIfChanged } from '../core/fs.mjs';
+
+export const adapter = {
+  id: 'windsurf',
+  name: 'Windsurf',
+
+  async apply({ repoPath, manifest, opts }) {
+    const written = [];
+    const skipped = [];
+
+    const body = renderRule(manifest);
+
+    bump(await writeIfChanged(join(repoPath, '.windsurf', 'rules', 'cofoundr.md'), body, opts), written, skipped);
+    bump(await writeIfChanged(join(repoPath, '.windsurfrules'), legacyBody(manifest), opts), written, skipped);
+
+    return { written, skipped };
+  },
+};
+
+function renderRule(manifest) {
+  const cmds = manifest.commands.map((c) => `- \`/cofoundr:${c.id}\` — ${c.summary}`).join('\n');
+  return `# CoFoundr workspace
+
+This project uses **CoFoundr** — a spec-driven workspace at \`.cofoundr/\`.
+
+When the user says \`/cofoundr:<name>\`, \`cofoundr <name>\`, or \`run cofoundr <name>\`:
+
+1. Read \`.cofoundr/commands/<name>.md\`.
+2. Follow it step-by-step. Do not paraphrase, do not skip steps.
+3. Honor \`.cofoundr/constitution.md\` (the \`Never\` section is binding).
+
+## Reading order
+
+1. \`AGENTS.md\`
+2. \`.cofoundr/constitution.md\`
+3. \`.cofoundr/memory/project.md\`
+4. \`.cofoundr/memory/decisions.md\`
+
+## Commands
+
+${cmds}
+
+Refresh with \`npx @cofoundr/init sync\`.
+`;
+}
+
+function legacyBody(manifest) {
+  return `# CoFoundr (Windsurf rules)
+
+This project uses CoFoundr. Read AGENTS.md and .cofoundr/constitution.md before any change.
+
+When the user says /cofoundr:<name> or cofoundr <name>:
+  1. Read .cofoundr/commands/<name>.md.
+  2. Follow it step-by-step.
+  3. Honor .cofoundr/constitution.md.
+
+Available commands: ${manifest.commands.map((c) => c.id).join(', ')}.
+`;
+}
+
+function bump(r, written, skipped) {
+  if (r.wrote) written.push(r.path);
+  else skipped.push({ path: r.path, reason: r.reason });
+}

package/src/cli.mjs

@@ -0,0 +1,124 @@
+// Tiny zero-dep argv router. Subcommands live in src/commands/.
+
+import { parseArgs } from 'node:util';
+import { c } from './core/log.mjs';
+import { init } from './commands/init.mjs';
+import { sync } from './commands/sync.mjs';
+import { onboard } from './commands/onboard.mjs';
+import { doctor } from './commands/doctor.mjs';
+import { listTools } from './commands/list.mjs';
+import { remove } from './commands/remove.mjs';
+import { version } from './core/version.mjs';
+
+const HELP = `
+${c.bold('cofoundr')} ${c.dim('— universal installer for the CoFoundr starter kit')}
+
+Usage:
+  ${c.cyan('npx @cofoundr/init')} <command> [options]
+
+Commands:
+  ${c.green('init')}         Scaffold .cofoundr/, AGENTS.md, and per-tool shims into the current repo.
+  ${c.green('sync')}         Refresh commands/agents/templates without touching project content.
+  ${c.green('onboard')}      Brownfield: scan an existing codebase and write .cofoundr/memory/codebase.md.
+  ${c.green('doctor')}       Inspect this project's CoFoundr install. Detect drift, missing shims, version mismatches.
+  ${c.green('tools')}        List supported tools and which ones are detected here.
+  ${c.green('remove')}       Remove CoFoundr from this project. Leaves .cofoundr/specs/ and .cofoundr/memory/ alone unless --hard.
+
+Common flags:
+  ${c.dim('--here')}              Operate on the current directory (default).
+  ${c.dim('--cwd <path>')}        Operate on a different directory.
+  ${c.dim('--tools <a,b,c>')}     Comma-separated tool ids. Default: detect + prompt.
+  ${c.dim('--all-tools')}         Install shims for every supported tool.
+  ${c.dim('--license <key>')}     CoFoundr Starter Kit license key. Cached after first use.
+  ${c.dim('--yes')}, ${c.dim('-y')}            Non-interactive. Accept defaults.
+  ${c.dim('--force')}             Overwrite existing .cofoundr files (still preserves memory/, specs/).
+  ${c.dim('--dry-run')}           Print what would change; write nothing.
+  ${c.dim('--debug')}             Verbose logging.
+  ${c.dim('--version')}           Print version.
+  ${c.dim('--help')}              Print this help.
+
+Examples:
+  ${c.cyan('npx @cofoundr/init init')}                       ${c.dim('# detect tools, prompt to confirm')}
+  ${c.cyan('npx @cofoundr/init init --tools claude-code,cursor --yes')}
+  ${c.cyan('npx @cofoundr/init onboard')}                    ${c.dim('# map existing codebase')}
+  ${c.cyan('npx @cofoundr/init sync --all-tools')}           ${c.dim('# refresh every shim')}
+
+More: https://cofoundr.ai
+`;
+
+export async function run(argv) {
+  const top = argv[0];
+
+  if (!top || top === '--help' || top === '-h' || top === 'help') {
+    process.stdout.write(HELP);
+    return;
+  }
+
+  if (top === '--version' || top === '-v') {
+    process.stdout.write(`${await version()}\n`);
+    return;
+  }
+
+  const sub = top;
+  const rest = argv.slice(1);
+
+  const opts = parseSharedFlags(rest);
+
+  switch (sub) {
+    case 'init':
+      return init(opts);
+    case 'sync':
+      return sync(opts);
+    case 'onboard':
+      return onboard(opts);
+    case 'doctor':
+      return doctor(opts);
+    case 'tools':
+    case 'list':
+      return listTools(opts);
+    case 'remove':
+    case 'uninstall':
+      return remove(opts);
+    default:
+      process.stderr.write(`cofoundr: unknown command "${sub}"\n\n`);
+      process.stdout.write(HELP);
+      process.exitCode = 1;
+  }
+}
+
+function parseSharedFlags(rest) {
+  const { values, positionals } = parseArgs({
+    args: rest,
+    allowPositionals: true,
+    strict: false,
+    options: {
+      here: { type: 'boolean' },
+      cwd: { type: 'string' },
+      tools: { type: 'string' },
+      'all-tools': { type: 'boolean' },
+      license: { type: 'string' },
+      yes: { type: 'boolean', short: 'y' },
+      force: { type: 'boolean' },
+      'dry-run': { type: 'boolean' },
+      debug: { type: 'boolean' },
+      refresh: { type: 'boolean' },
+      hard: { type: 'boolean' },
+    },
+  });
+
+  if (values.debug) process.env.COFOUNDR_DEBUG = '1';
+
+  return {
+    cwd: values.cwd || process.cwd(),
+    tools: values.tools ? values.tools.split(',').map((s) => s.trim()).filter(Boolean) : null,
+    allTools: !!values['all-tools'],
+    license: values.license || null,
+    yes: !!values.yes,
+    force: !!values.force,
+    dryRun: !!values['dry-run'],
+    debug: !!values.debug,
+    refresh: !!values.refresh,
+    hard: !!values.hard,
+    positionals,
+  };
+}

package/src/commands/doctor.mjs

@@ -0,0 +1,90 @@
+import { resolve, join } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { c, log } from '../core/log.mjs';
+import { locateSource, loadManifest } from '../core/source.mjs';
+import { detectTools } from '../core/detect.mjs';
+import { getCachedLicense, verifyLicense, reasonMessage } from '../core/license.mjs';
+
+export async function doctor(opts) {
+  const repoPath = resolve(opts.cwd);
+  log.info(`${c.bold('CoFoundr doctor')} ${c.dim(`→ ${repoPath}`)}`);
+
+  const projManPath = join(repoPath, '.cofoundr', 'manifest.json');
+  if (!existsSync(projManPath)) {
+    log.err('No CoFoundr install detected here. Run `npx @cofoundr/init init`.');
+    process.exitCode = 1;
+    return;
+  }
+
+  const projMan = JSON.parse(readFileSync(projManPath, 'utf8'));
+  const source = await locateSource();
+  const manifest = await loadManifest(source);
+
+  log.blank();
+  log.info(`${c.bold('Versions')}`);
+  log.list(`Project:  v${projMan.cofoundrVersion}`);
+  log.list(`Latest:   v${manifest.version}`);
+  if (projMan.cofoundrVersion !== manifest.version) {
+    log.warn(`Out of date — run ${c.cyan('npx @cofoundr/init sync')} to refresh.`);
+  } else {
+    log.ok('Up to date.');
+  }
+
+  log.blank();
+  log.info(`${c.bold('Workspace')}`);
+  for (const f of [
+    '.cofoundr/constitution.md',
+    '.cofoundr/memory/project.md',
+    '.cofoundr/memory/decisions.md',
+    '.cofoundr/specs/README.md',
+    'AGENTS.md',
+  ]) {
+    const present = existsSync(join(repoPath, f));
+    log.list(`${present ? c.green('✓') : c.red('✗')} ${f}`);
+  }
+
+  log.blank();
+  log.info(`${c.bold('Per-tool shims')}`);
+  const tools = projMan.tools || [];
+  for (const id of tools) {
+    const target = manifest.targets.find((t) => t.id === id);
+    if (!target) {
+      log.warn(`Unknown tool id "${id}" recorded in manifest.`);
+      continue;
+    }
+    const allPresent = target.config.every((p) => existsSync(join(repoPath, p)) || existsSync(join(repoPath, p.replace(/\/$/, ''))));
+    log.list(`${allPresent ? c.green('✓') : c.yellow('!')} ${target.name} ${c.dim(`(${target.config.join(', ')})`)}`);
+  }
+
+  log.blank();
+  const detected = detectTools(repoPath);
+  const detectedIds = Object.entries(detected).filter(([, v]) => v.found).map(([id]) => id);
+  const missing = detectedIds.filter((id) => !tools.includes(id));
+  if (missing.length) {
+    log.info(`${c.bold('Tools detected in repo but not yet shimmed:')}`);
+    for (const id of missing) {
+      const target = manifest.targets.find((t) => t.id === id);
+      log.list(`${target?.name ?? id} — add with ${c.cyan(`npx @cofoundr/init sync --tools ${id}`)}`);
+    }
+  }
+
+  log.blank();
+  log.info(`${c.bold('License')}`);
+  const cached = getCachedLicense();
+  if (!cached?.key) {
+    log.list(c.dim('No cached license. Run `npx @cofoundr/init init --license <key>` to activate.'));
+  } else {
+    const last4 = cached.key.slice(-4);
+    log.list(c.dim(`csk_live_…${last4}  plan: ${cached.plan ?? 'starter_kit'}  email: ${cached.email ?? '—'}`));
+    try {
+      const result = await verifyLicense(cached.key, { skipCache: true });
+      if (result.valid) {
+        log.list(`${c.green('✓')} Server confirms key is active.`);
+      } else {
+        log.list(`${c.red('✗')} ${reasonMessage(result.reason)}`);
+      }
+    } catch {
+      log.list(c.yellow('Could not reach license server (cached key still trusted within TTL).'));
+    }
+  }
+}

package/src/commands/init.mjs

@@ -0,0 +1,190 @@
+import { resolve, basename } from 'node:path';
+import { existsSync } from 'node:fs';
+import { c, log } from '../core/log.mjs';
+import { locateSource, loadManifest } from '../core/source.mjs';
+import { detectTools, detectRuntime } from '../core/detect.mjs';
+import { confirm, multiSelect, text } from '../core/prompts.mjs';
+import { writeScaffold, writeProjectManifest } from '../core/scaffold.mjs';
+import { adapters, getAdapter } from '../adapters/index.mjs';
+import {
+  verifyLicense,
+  getCachedLicense,
+  isValidLicenseFormat,
+  reasonMessage,
+  PURCHASE_URL,
+  RECOVERY_URL,
+} from '../core/license.mjs';
+
+export async function init(opts) {
+  const repoPath = resolve(opts.cwd);
+  log.info(`${c.bold('CoFoundr init')} ${c.dim(`→ ${repoPath}`)}`);
+
+  if (!existsSync(repoPath)) throw new Error(`Target directory does not exist: ${repoPath}`);
+
+  // License gate — refuses scaffold without a valid Starter Kit key.
+  const licenseOk = await ensureLicense(opts);
+  if (!licenseOk) {
+    process.exitCode = 1;
+    return;
+  }
+
+  const source = await locateSource();
+  const manifest = await loadManifest(source);
+  log.debug(`Using source: ${source.root} (${source.mode})`);
+
+  const detected = detectTools(repoPath);
+  const runtime = detectRuntime(repoPath);
+
+  const detectedIds = Object.entries(detected)
+    .filter(([, v]) => v.found)
+    .map(([id]) => id);
+
+  log.blank();
+  log.info(`${c.bold('Detected:')} ${runtime.languages.join(', ') || c.dim('no language signal')}`);
+  if (runtime.frameworks.length) log.list(`Framework: ${runtime.frameworks.join(', ')}`);
+  if (runtime.isMonorepo) log.list('Layout: monorepo');
+  log.list(
+    `AI tools already in repo: ${
+      detectedIds.length
+        ? detectedIds.map((id) => manifest.targets.find((t) => t.id === id)?.name ?? id).join(', ')
+        : c.dim('none')
+    }`
+  );
+  log.blank();
+
+  // Pick which tools to install shims for.
+  let selected;
+  if (opts.allTools) {
+    selected = adapters.map((a) => a.id);
+  } else if (opts.tools) {
+    const valid = new Set(adapters.map((a) => a.id));
+    const invalid = opts.tools.filter((t) => !valid.has(t));
+    if (invalid.length) throw new Error(`Unknown tool(s): ${invalid.join(', ')}`);
+    selected = opts.tools;
+  } else if (opts.yes) {
+    selected = detectedIds.length ? detectedIds : ['claude-code'];
+  } else {
+    selected = await multiSelect(
+      'Which AI tools should CoFoundr install shims for?',
+      adapters.map((a) => ({
+        id: a.id,
+        label: c.bold(manifest.targets.find((t) => t.id === a.id)?.name ?? a.id),
+        note: detected[a.id]?.found ? c.green('detected in repo') : '',
+      })),
+      { defaults: detectedIds.length ? detectedIds : ['claude-code'] }
+    );
+  }
+
+  if (selected.length === 0) {
+    log.warn('No tools selected. AGENTS.md will still be written — every modern coding agent reads it.');
+  }
+
+  // Project name: from package.json if present, else basename, else prompt.
+  const projectName = await resolveProjectName(repoPath, opts);
+
+  // Write the scaffold.
+  log.blank();
+  log.step(`Writing ${c.bold('.cofoundr/')} workspace and ${c.bold('AGENTS.md')}`);
+  const scaffold = await writeScaffold({
+    repoPath,
+    source,
+    manifest,
+    projectName,
+    selectedTools: selected,
+    dryRun: opts.dryRun,
+    force: opts.force,
+  });
+  reportFileResult(scaffold);
+
+  // Write per-tool shims.
+  for (const id of selected) {
+    const adapter = getAdapter(id);
+    if (!adapter) {
+      log.warn(`No adapter for "${id}" — skipping.`);
+      continue;
+    }
+    log.step(`Installing ${c.bold(adapter.name)} shim`);
+    const result = await adapter.apply({ repoPath, source, manifest, opts: { dryRun: opts.dryRun, force: opts.force } });
+    reportFileResult(result);
+  }
+
+  // Project manifest stamp.
+  await writeProjectManifest({ repoPath, manifest, selectedTools: selected, dryRun: opts.dryRun });
+
+  log.blank();
+  log.ok(`CoFoundr v${manifest.version} initialized in ${c.bold(repoPath)}`);
+  log.blank();
+  log.info(`${c.bold('Next steps:')}`);
+  log.list(`Open the repo in any of: ${selected.map((id) => manifest.targets.find((t) => t.id === id)?.name ?? id).join(', ')}`);
+  log.list(`Run ${c.cyan('/cofoundr:constitution')} to lock the rules.`);
+  log.list(`Run ${c.cyan('/cofoundr:onboard')} if this is an existing codebase, or ${c.cyan('/cofoundr:new-project')} for a greenfield spec.`);
+  log.list(`Re-sync after a CoFoundr upgrade with ${c.cyan('npx @cofoundr/init sync')}.`);
+}
+
+async function resolveProjectName(repoPath, opts) {
+  // Prefer package.json#name.
+  const pkgPath = resolve(repoPath, 'package.json');
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(await (await import('node:fs/promises')).readFile(pkgPath, 'utf8'));
+      if (pkg.name) return pkg.name;
+    } catch {}
+  }
+  if (opts.yes) return basename(repoPath);
+  return text('Project name?', { defaultValue: basename(repoPath) });
+}
+
+async function ensureLicense(opts) {
+  // 1. --license flag, 2. COFOUNDR_LICENSE_KEY env, 3. cached key, 4. prompt.
+  let key = opts.license || process.env.COFOUNDR_LICENSE_KEY || null;
+  let cachedHit = false;
+
+  if (!key) {
+    const cached = getCachedLicense();
+    if (cached?.key && isValidLicenseFormat(cached.key)) {
+      key = cached.key;
+      cachedHit = true;
+    }
+  }
+
+  if (!key) {
+    log.blank();
+    log.info(`${c.bold('License required.')} Activate the CoFoundr Starter Kit CLI.`);
+    log.list(`Buy at ${c.cyan(PURCHASE_URL)} — keys arrive in your purchase email.`);
+    log.list(`Lost your key? Recover at ${c.cyan(RECOVERY_URL)}.`);
+    log.blank();
+    key = (await text('Paste your license key', { defaultValue: '' })).trim();
+  }
+
+  if (!key) {
+    log.err('No license key provided. Run with --license <key> or set COFOUNDR_LICENSE_KEY.');
+    return false;
+  }
+
+  if (!isValidLicenseFormat(key)) {
+    log.err('License key format is invalid. Expected: csk_live_<32 chars>.');
+    return false;
+  }
+
+  const result = await verifyLicense(key);
+  if (!result.valid) {
+    log.err(reasonMessage(result.reason));
+    return false;
+  }
+
+  const tag = result.source === 'cache' ? c.dim('(verified from cache)') : c.dim('(verified)');
+  log.ok(`License active for ${c.bold(result.email || 'your account')} ${tag}`);
+  if (cachedHit && opts.debug) log.list(c.dim('using cached key'));
+  return true;
+}
+
+function reportFileResult({ written, skipped }) {
+  for (const p of written) log.ok(c.dim(p));
+  for (const s of skipped) {
+    if (s.reason === 'unchanged') {
+      log.list(c.dim(`${s.path} ${c.dim('(unchanged)')}`));
+    } else {
+      log.list(`${c.yellow('skip')} ${s.path} ${c.dim(`(${s.reason}; pass --force to overwrite)`)}`);
+    }
+  }
+}

package/src/commands/list.mjs

@@ -0,0 +1,28 @@
+import { resolve } from 'node:path';
+import { c, log } from '../core/log.mjs';
+import { locateSource, loadManifest } from '../core/source.mjs';
+import { detectTools } from '../core/detect.mjs';
+import { adapters } from '../adapters/index.mjs';
+
+export async function listTools(opts) {
+  const source = await locateSource();
+  const manifest = await loadManifest(source);
+  const repoPath = resolve(opts.cwd);
+  const detected = detectTools(repoPath);
+
+  log.info(`${c.bold('Supported AI tools')}`);
+  log.blank();
+
+  const order = adapters.map((a) => a.id);
+  for (const id of order) {
+    const target = manifest.targets.find((t) => t.id === id);
+    if (!target) continue;
+    const found = detected[id]?.found;
+    const tag = found ? c.green('detected') : c.dim('available');
+    const cfg = c.dim(`writes: ${target.config.join(', ')}`);
+    process.stdout.write(`  ${c.bold(target.name.padEnd(22))} ${tag.padEnd(20)} ${cfg}\n`);
+  }
+
+  log.blank();
+  log.info(c.dim('Pass --tools <id1,id2> to init or sync to install only specific shims.'));
+}

package/src/commands/onboard.mjs

@@ -0,0 +1,130 @@
+// Onboard — static-analysis pass that writes a starter `.cofoundr/memory/codebase.md`.
+// The richer pass (route extraction, schema parsing, doc backfill) lives in the in-tool
+// /cofoundr:onboard slash command. This CLI step gives the AI a head start so its first
+// run isn't from scratch.
+
+import { resolve, join, basename } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { c, log } from '../core/log.mjs';
+import { detectTools, detectRuntime, listTopLevel } from '../core/detect.mjs';
+import { writeIfChanged } from '../core/fs.mjs';
+
+export async function onboard(opts) {
+  const repoPath = resolve(opts.cwd);
+  if (!existsSync(repoPath)) throw new Error(`Target directory does not exist: ${repoPath}`);
+
+  log.info(`${c.bold('CoFoundr onboard (static pass)')} ${c.dim(`→ ${repoPath}`)}`);
+
+  const runtime = detectRuntime(repoPath);
+  const tools = detectTools(repoPath);
+  const topLevel = listTopLevel(repoPath, 2);
+
+  const pkg = readJSON(join(repoPath, 'package.json'));
+  const projectName = pkg?.name ?? basename(repoPath);
+  const projectDescription = pkg?.description ?? '<!-- no package.json description; fill via /cofoundr:onboard in-tool -->';
+
+  const summary = renderCodebaseMap({
+    projectName,
+    projectDescription,
+    runtime,
+    tools,
+    topLevel,
+    pkg,
+  });
+
+  const dest = join(repoPath, '.cofoundr', 'memory', 'codebase.md');
+  const r = await writeIfChanged(dest, summary, { dryRun: opts.dryRun, force: opts.refresh || opts.force });
+  if (r.wrote) {
+    log.ok(`Wrote ${dest}`);
+  } else {
+    log.warn(`${dest} ${c.dim(`(${r.reason}; pass --refresh to overwrite)`)}`);
+  }
+
+  log.blank();
+  log.info(c.bold('Next:'));
+  log.list(`Open the project in your AI tool and run ${c.cyan('/cofoundr:onboard')} for the deep pass (routes, schema, doc backfill).`);
+  log.list(`Then ${c.cyan('/cofoundr:constitution')} to confirm the rules.`);
+  log.list(`Then ${c.cyan('/cofoundr:audit')} to find drift.`);
+}
+
+function readJSON(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function renderCodebaseMap({ projectName, projectDescription, runtime, tools, topLevel, pkg }) {
+  const today = new Date().toISOString().slice(0, 10);
+  const langs = runtime.languages.length ? runtime.languages.join(', ') : '<unknown>';
+  const fws = runtime.frameworks.length ? runtime.frameworks.join(', ') : '<unknown>';
+  const pms = runtime.packageManagers.length ? runtime.packageManagers.join(', ') : '<unknown>';
+  const layout = runtime.isMonorepo ? 'monorepo' : 'single project';
+
+  const aiTools = Object.entries(tools)
+    .filter(([, v]) => v.found)
+    .map(([id, v]) => `- **${id}** — evidence: ${v.evidence.join(', ')}`)
+    .join('\n') || '- _none detected_';
+
+  const tree = topLevel
+    .filter((e) => !e.path.includes('/'))
+    .slice(0, 50)
+    .map((e) => `- ${e.dir ? `${e.path}/` : e.path}`)
+    .join('\n');
+
+  const deps = pkg
+    ? Object.entries({ ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) })
+        .slice(0, 30)
+        .map(([k, v]) => `- ${k} \`${v}\``)
+        .join('\n')
+    : '_no package.json_';
+
+  return `# Codebase Map — ${projectName}
+
+> Generated by \`cofoundr onboard\` (static pass) on ${today}.
+> This is a starting point — run \`/cofoundr:onboard\` inside your AI tool for the deep pass.
+
+## TL;DR
+
+${projectDescription}
+
+## Layout
+
+- ${layout}
+- Languages: ${langs}
+- Frameworks (config files seen): ${fws}
+- Package manager(s): ${pms}
+
+## Top-level
+
+${tree || '_empty repo_'}
+
+## Stack signals
+
+| Source | Value |
+|--------|-------|
+| package.json#name | ${pkg?.name ?? '—'} |
+| package.json#version | ${pkg?.version ?? '—'} |
+| Node engines | ${pkg?.engines?.node ?? '—'} |
+| Scripts | ${pkg?.scripts ? Object.keys(pkg.scripts).join(', ') : '—'} |
+
+## Top dependencies
+
+${deps}
+
+## AI tools already configured
+
+${aiTools}
+
+## Gaps and Open Questions
+
+<!-- GAP: routes — run /cofoundr:onboard inside Claude Code / Cursor / etc. for route enumeration. -->
+<!-- GAP: data model — same. -->
+<!-- GAP: external integrations — same. -->
+<!-- GAP: tests + CI — same. -->
+
+---
+<sub>Refresh with \`cofoundr onboard --refresh\`. The deep pass lives in \`/cofoundr:onboard\`.</sub>
+`;
+}