aether-code 0.42.0 → 0.43.0

package/src/project-context.js

@@ -1,707 +1,712 @@
-// Project context scanner. Reads the cwd on startup to give the model
-// immediate understanding of what project it's working in — tech stack,
-// file structure, available scripts, dependencies, and any project-specific
-// instructions. This is the single biggest quality-of-life improvement for
-// a weaker model: instead of guessing, it KNOWS.
-
-import fs from "node:fs";
-import path from "node:path";
-
-const SKIP_DIRS = new Set([
-  "node_modules", ".git", ".next", "dist", "build", "__pycache__",
-  ".venv", "venv", "env", ".env", ".idea", ".vscode", "coverage",
-  ".cache", ".turbo", "target", "out", ".output", ".nuxt", ".svelte-kit",
-  "vendor", "bower_components", ".parcel-cache", ".webpack",
-]);
-
-const FRAMEWORK_SIGNATURES = {
-  "next.config.js": "Next.js",
-  "next.config.mjs": "Next.js",
-  "next.config.ts": "Next.js",
-  "nuxt.config.ts": "Nuxt",
-  "svelte.config.js": "SvelteKit",
-  "astro.config.mjs": "Astro",
-  "remix.config.js": "Remix",
-  "angular.json": "Angular",
-  "vue.config.js": "Vue CLI",
-  "vite.config.ts": "Vite",
-  "vite.config.js": "Vite",
-  "webpack.config.js": "Webpack",
-  "tsconfig.json": "TypeScript",
-  "Cargo.toml": "Rust (Cargo)",
-  "go.mod": "Go",
-  "pyproject.toml": "Python",
-  "setup.py": "Python (setuptools)",
-  "requirements.txt": "Python",
-  "Gemfile": "Ruby (Bundler)",
-  "pom.xml": "Java (Maven)",
-  "build.gradle": "Java/Kotlin (Gradle)",
-  "CMakeLists.txt": "C/C++ (CMake)",
-  "Makefile": "Make",
-  "Dockerfile": "Docker",
-  "docker-compose.yml": "Docker Compose",
-  "docker-compose.yaml": "Docker Compose",
-  ".env": "dotenv config",
-  "prisma/schema.prisma": "Prisma ORM",
-  "drizzle.config.ts": "Drizzle ORM",
-};
-
-const DEP_FRAMEWORKS = {
-  next: "Next.js",
-  react: "React",
-  vue: "Vue",
-  svelte: "Svelte",
-  angular: "Angular",
-  express: "Express",
-  fastify: "Fastify",
-  koa: "Koa",
-  hono: "Hono",
-  "socket.io": "Socket.IO",
-  prisma: "Prisma",
-  drizzle: "Drizzle",
-  mongoose: "Mongoose",
-  sequelize: "Sequelize",
-  tailwindcss: "Tailwind CSS",
-  "styled-components": "styled-components",
-  electron: "Electron",
-  jest: "Jest",
-  vitest: "Vitest",
-  mocha: "Mocha",
-  playwright: "Playwright",
-  cypress: "Cypress",
-};
-
-function readJsonSafe(filePath) {
-  try {
-    return JSON.parse(fs.readFileSync(filePath, "utf8"));
-  } catch {
-    return null;
-  }
-}
-
-function readTextSafe(filePath, maxBytes = 2000) {
-  try {
-    const stat = fs.statSync(filePath);
-    if (!stat.isFile() || stat.size > 500_000) return null;
-    const buf = Buffer.alloc(Math.min(stat.size, maxBytes));
-    const fd = fs.openSync(filePath, "r");
-    const bytesRead = fs.readSync(fd, buf, 0, buf.length, 0);
-    fs.closeSync(fd);
-    return buf.toString("utf8", 0, bytesRead);
-  } catch {
-    return null;
-  }
-}
-
-function listTopLevel(cwd) {
-  let entries;
-  try {
-    entries = fs.readdirSync(cwd, { withFileTypes: true });
-  } catch {
-    return { dirs: [], files: [] };
-  }
-  const dirs = [];
-  const files = [];
-  for (const e of entries) {
-    if (e.name.startsWith(".") && e.name !== ".env" && e.name !== ".gitignore") continue;
-    if (SKIP_DIRS.has(e.name)) continue;
-    if (e.isDirectory()) {
-      dirs.push(e.name + "/");
-    } else if (e.isFile()) {
-      files.push(e.name);
-    }
-  }
-  dirs.sort();
-  files.sort();
-  return { dirs, files };
-}
-
-function listSecondLevel(cwd, dirName) {
-  const full = path.join(cwd, dirName);
-  let entries;
-  try {
-    entries = fs.readdirSync(full, { withFileTypes: true });
-  } catch {
-    return [];
-  }
-  const items = [];
-  for (const e of entries) {
-    if (e.name.startsWith(".")) continue;
-    if (SKIP_DIRS.has(e.name)) continue;
-    items.push(e.isDirectory() ? e.name + "/" : e.name);
-  }
-  items.sort();
-  return items.slice(0, 30);
-}
-
-function detectFrameworks(cwd, topFiles) {
-  const found = new Set();
-  for (const file of topFiles) {
-    if (FRAMEWORK_SIGNATURES[file]) found.add(FRAMEWORK_SIGNATURES[file]);
-  }
-  if (fs.existsSync(path.join(cwd, "prisma", "schema.prisma"))) {
-    found.add("Prisma ORM");
-  }
-  return [...found];
-}
-
-function extractPackageInfo(cwd) {
-  const pkg = readJsonSafe(path.join(cwd, "package.json"));
-  if (!pkg) return null;
-  const info = { name: pkg.name, version: pkg.version };
-  if (pkg.scripts && Object.keys(pkg.scripts).length > 0) {
-    info.scripts = Object.keys(pkg.scripts);
-  }
-  const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
-  const detectedLibs = [];
-  for (const [dep, label] of Object.entries(DEP_FRAMEWORKS)) {
-    if (allDeps[dep]) detectedLibs.push(label);
-  }
-  if (detectedLibs.length > 0) info.frameworks = detectedLibs;
-  const depCount = Object.keys(pkg.dependencies || {}).length;
-  const devCount = Object.keys(pkg.devDependencies || {}).length;
-  if (depCount || devCount) {
-    info.depCounts = `${depCount} deps, ${devCount} devDeps`;
-  }
-  return info;
-}
-
-function extractCargoInfo(cwd) {
-  const raw = readTextSafe(path.join(cwd, "Cargo.toml"), 1500);
-  if (!raw) return null;
-  const name = raw.match(/^name\s*=\s*"(.+?)"/m)?.[1];
-  const version = raw.match(/^version\s*=\s*"(.+?)"/m)?.[1];
-  return { name, version, type: "Rust" };
-}
-
-function extractGoInfo(cwd) {
-  const raw = readTextSafe(path.join(cwd, "go.mod"), 500);
-  if (!raw) return null;
-  const mod = raw.match(/^module\s+(\S+)/m)?.[1];
-  const goVer = raw.match(/^go\s+(\S+)/m)?.[1];
-  return { module: mod, goVersion: goVer, type: "Go" };
-}
-
-function extractPythonInfo(cwd) {
-  const pyproject = readTextSafe(path.join(cwd, "pyproject.toml"), 1500);
-  if (pyproject) {
-    const name = pyproject.match(/^name\s*=\s*"(.+?)"/m)?.[1];
-    return { name, type: "Python" };
-  }
-  if (fs.existsSync(path.join(cwd, "requirements.txt"))) {
-    return { type: "Python (requirements.txt)" };
-  }
-  return null;
-}
-
-export function scanProject(cwd) {
-  const { dirs, files } = listTopLevel(cwd);
-  if (dirs.length === 0 && files.length === 0) {
-    return "[project]\nEmpty directory — no files detected.\n[/project]\n";
-  }
-
-  const lines = ["[project]"];
-
-  const frameworks = detectFrameworks(cwd, files);
-  if (frameworks.length > 0) {
-    lines.push(`stack: ${frameworks.join(", ")}`);
-  }
-
-  const pkg = extractPackageInfo(cwd);
-  const cargo = extractCargoInfo(cwd);
-  const goInfo = extractGoInfo(cwd);
-  const pyInfo = extractPythonInfo(cwd);
-
-  if (pkg) {
-    if (pkg.name) lines.push(`package: ${pkg.name}${pkg.version ? `@${pkg.version}` : ""}`);
-    if (pkg.frameworks) lines.push(`libraries: ${pkg.frameworks.join(", ")}`);
-    if (pkg.depCounts) lines.push(`dependencies: ${pkg.depCounts}`);
-    if (pkg.scripts) lines.push(`scripts: ${pkg.scripts.join(", ")}`);
-  }
-  if (cargo) {
-    lines.push(`crate: ${cargo.name || "unknown"}${cargo.version ? `@${cargo.version}` : ""}`);
-  }
-  if (goInfo) {
-    lines.push(`module: ${goInfo.module || "unknown"}${goInfo.goVersion ? ` (go ${goInfo.goVersion})` : ""}`);
-  }
-  if (pyInfo) {
-    lines.push(`python project: ${pyInfo.name || pyInfo.type}`);
-  }
-
-  lines.push("");
-  lines.push("structure:");
-  for (const d of dirs) {
-    lines.push(`  ${d}`);
-    const children = listSecondLevel(cwd, d.replace(/\/$/, ""));
-    for (const child of children.slice(0, 15)) {
-      lines.push(`    ${child}`);
-    }
-    if (children.length > 15) {
-      lines.push(`    ... (${children.length - 15} more)`);
-    }
-  }
-  for (const f of files) {
-    lines.push(`  ${f}`);
-  }
-
-  const contextFile = path.join(cwd, ".aether", "context.md");
-  const context = readTextSafe(contextFile, 3000);
-  if (context) {
-    lines.push("");
-    lines.push("project-instructions:");
-    lines.push(context.trim());
-  }
-
-  const readme = readTextSafe(path.join(cwd, "README.md"), 1500);
-  if (readme) {
-    lines.push("");
-    lines.push("readme-excerpt:");
-    lines.push(readme.trim());
-  }
-
-  lines.push("[/project]");
-  return lines.join("\n") + "\n";
-}
-
-// ─────────── /init — deep project indexing ───────────
-
-const KEY_FILES = [
-  "README.md", "CLAUDE.md", ".env.example", "Dockerfile",
-  "docker-compose.yml", "docker-compose.yaml",
-];
-
-const ENTRY_PATTERNS = [
-  /^(src\/)?index\.[jt]sx?$/,
-  /^(src\/)?main\.[jt]sx?$/,
-  /^(src\/)?app\.[jt]sx?$/,
-  /^(src\/)?server\.[jt]sx?$/,
-  /^(bin|cli|cmd)\/[^/]+\.[jt]sx?$/,
-  /^(pages|app)\/_app\.[jt]sx?$/,
-  /^(pages|app)\/layout\.[jt]sx?$/,
-];
-
-const CONFIG_FILES = [
-  "next.config.js", "next.config.mjs", "next.config.ts",
-  "vite.config.ts", "vite.config.js", "webpack.config.js",
-  "tsconfig.json", "tailwind.config.js", "tailwind.config.ts",
-  "eslint.config.js", ".eslintrc.js", ".eslintrc.json",
-  "jest.config.js", "jest.config.ts", "vitest.config.ts",
-  "prisma/schema.prisma", "drizzle.config.ts",
-];
-
-function collectSourceFiles(dir, base, maxFiles = 500) {
-  const results = [];
-  function walk(current, rel) {
-    if (results.length >= maxFiles) return;
-    let entries;
-    try { entries = fs.readdirSync(current, { withFileTypes: true }); } catch { return; }
-    for (const e of entries) {
-      if (results.length >= maxFiles) return;
-      if (e.name.startsWith(".") && e.name !== ".env.example") continue;
-      if (SKIP_DIRS.has(e.name)) continue;
-      const fullPath = path.join(current, e.name);
-      const relPath = rel ? `${rel}/${e.name}` : e.name;
-      if (e.isDirectory()) {
-        walk(fullPath, relPath);
-      } else if (e.isFile()) {
-        let size = 0;
-        try { size = fs.statSync(fullPath).size; } catch { /* skip */ }
-        results.push({ path: relPath, size });
-      }
-    }
-  }
-  walk(dir, "");
-  return results;
-}
-
-function identifyKeyFiles(allFiles, cwd) {
-  const key = [];
-  for (const f of allFiles) {
-    const name = f.path.split("/").pop();
-    if (KEY_FILES.includes(name)) { key.push(f.path); continue; }
-    if (CONFIG_FILES.includes(f.path)) { key.push(f.path); continue; }
-    for (const pat of ENTRY_PATTERNS) {
-      if (pat.test(f.path)) { key.push(f.path); break; }
-    }
-  }
-  return key;
-}
-
-function summarizeFile(filePath, maxLines = 30) {
-  try {
-    const stat = fs.statSync(filePath);
-    if (!stat.isFile() || stat.size > 200_000) return null;
-    const content = fs.readFileSync(filePath, "utf8");
-    const lines = content.split("\n");
-    const exports = [];
-    const imports = [];
-    for (const line of lines.slice(0, 100)) {
-      if (/^export\s+(default\s+)?(function|class|const|let|async)\s+(\w+)/m.test(line)) {
-        const match = line.match(/^export\s+(?:default\s+)?(?:function|class|const|let|async\s+function)\s+(\w+)/);
-        if (match) exports.push(match[1]);
-      }
-      if (/^import\s/.test(line)) {
-        const match = line.match(/from\s+["']([^"']+)["']/);
-        if (match && !match[1].startsWith(".")) imports.push(match[1]);
-      }
-    }
-    const summary = { lines: lines.length };
-    if (exports.length > 0) summary.exports = exports.slice(0, 15);
-    if (imports.length > 0) summary.externalImports = [...new Set(imports)].slice(0, 10);
-    const firstComment = content.match(/^\/\/\s*(.+)/m);
-    if (firstComment) summary.description = firstComment[1].trim().slice(0, 120);
-    return summary;
-  } catch {
-    return null;
-  }
-}
-
-function detectConventions(allFiles, cwd) {
-  const conventions = [];
-  const extensions = new Set();
-  for (const f of allFiles) {
-    const ext = path.extname(f.path);
-    if (ext) extensions.add(ext);
-  }
-  if (extensions.has(".ts") || extensions.has(".tsx")) conventions.push("TypeScript");
-  if (extensions.has(".jsx") || extensions.has(".tsx")) conventions.push("JSX/TSX (React-style)");
-  const hasTest = allFiles.some((f) =>
-    /\.(test|spec)\.[jt]sx?$/.test(f.path) || f.path.startsWith("test/") || f.path.startsWith("__tests__/"),
-  );
-  if (hasTest) {
-    const testDirs = [];
-    if (allFiles.some((f) => f.path.startsWith("test/"))) testDirs.push("test/");
-    if (allFiles.some((f) => f.path.startsWith("__tests__/"))) testDirs.push("__tests__/");
-    const colocated = allFiles.some((f) => /src\/.*\.(test|spec)\.[jt]sx?$/.test(f.path));
-    if (colocated) testDirs.push("colocated in src/");
-    conventions.push(`Tests: ${testDirs.join(", ") || "detected"}`);
-  }
-  if (fs.existsSync(path.join(cwd, ".prettierrc")) || fs.existsSync(path.join(cwd, ".prettierrc.json"))) {
-    conventions.push("Prettier formatting");
-  }
-  if (fs.existsSync(path.join(cwd, ".eslintrc.js")) || fs.existsSync(path.join(cwd, "eslint.config.js"))) {
-    conventions.push("ESLint");
-  }
-  return conventions;
-}
-
-function buildDirectoryTree(allFiles, maxDepth = 3) {
-  const tree = {};
-  for (const f of allFiles) {
-    const parts = f.path.split("/");
-    let node = tree;
-    for (let i = 0; i < Math.min(parts.length - 1, maxDepth); i++) {
-      if (!node[parts[i]]) node[parts[i]] = {};
-      node = node[parts[i]];
-    }
-  }
-  function render(node, indent = "") {
-    const lines = [];
-    const entries = Object.keys(node).sort();
-    for (const key of entries) {
-      const children = Object.keys(node[key]);
-      lines.push(`${indent}${key}/`);
-      if (children.length > 0 && indent.length < maxDepth * 2) {
-        lines.push(...render(node[key], indent + "  "));
-      }
-    }
-    return lines;
-  }
-  return render(tree);
-}
-
-export function generateProjectIndex(cwd) {
-  const lines = [];
-  lines.push("# Project Context");
-  lines.push(`# Auto-generated by \`aether /init\` — edit freely, this file is yours.`);
-  lines.push(`# Loaded on every agent turn to give the model deep project understanding.`);
-  lines.push("");
-
-  const { dirs, files: topFiles } = listTopLevel(cwd);
-  const frameworks = detectFrameworks(cwd, topFiles);
-  const pkg = extractPackageInfo(cwd);
-  const cargo = extractCargoInfo(cwd);
-  const goInfo = extractGoInfo(cwd);
-  const pyInfo = extractPythonInfo(cwd);
-
-  lines.push("## Overview");
-  if (pkg?.name) lines.push(`- **Package:** ${pkg.name}${pkg.version ? ` v${pkg.version}` : ""}`);
-  if (cargo?.name) lines.push(`- **Crate:** ${cargo.name}${cargo.version ? ` v${cargo.version}` : ""}`);
-  if (goInfo?.module) lines.push(`- **Module:** ${goInfo.module}${goInfo.goVersion ? ` (go ${goInfo.goVersion})` : ""}`);
-  if (pyInfo?.name) lines.push(`- **Python:** ${pyInfo.name || pyInfo.type}`);
-  if (frameworks.length > 0) lines.push(`- **Stack:** ${frameworks.join(", ")}`);
-  if (pkg?.frameworks?.length) lines.push(`- **Libraries:** ${pkg.frameworks.join(", ")}`);
-  if (pkg?.depCounts) lines.push(`- **Dependencies:** ${pkg.depCounts}`);
-  lines.push("");
-
-  const allFiles = collectSourceFiles(cwd);
-  const conventions = detectConventions(allFiles, cwd);
-  if (conventions.length > 0) {
-    lines.push("## Conventions");
-    for (const c of conventions) lines.push(`- ${c}`);
-    lines.push("");
-  }
-
-  if (pkg?.scripts?.length) {
-    lines.push("## Scripts");
-    const pkgFull = readJsonSafe(path.join(cwd, "package.json"));
-    if (pkgFull?.scripts) {
-      for (const [name, cmd] of Object.entries(pkgFull.scripts)) {
-        lines.push(`- \`npm run ${name}\` → \`${cmd}\``);
-      }
-    }
-    lines.push("");
-  }
-
-  lines.push("## Structure");
-  const tree = buildDirectoryTree(allFiles);
-  for (const t of tree.slice(0, 60)) lines.push(t);
-  if (tree.length > 60) lines.push(`... (${tree.length - 60} more directories)`);
-  lines.push("");
-
-  const keyFiles = identifyKeyFiles(allFiles, cwd);
-  if (keyFiles.length > 0) {
-    lines.push("## Key Files");
-    for (const kf of keyFiles.slice(0, 25)) {
-      const abs = path.join(cwd, kf.replace(/\//g, path.sep));
-      const summary = summarizeFile(abs);
-      if (summary) {
-        const desc = summary.description ? ` — ${summary.description}` : "";
-        const exports = summary.exports?.length ? ` (exports: ${summary.exports.join(", ")})` : "";
-        lines.push(`- \`${kf}\` [${summary.lines} lines]${desc}${exports}`);
-      } else {
-        lines.push(`- \`${kf}\``);
-      }
-    }
-    lines.push("");
-  }
-
-  const sourceByDir = {};
-  for (const f of allFiles) {
-    const dir = f.path.includes("/") ? f.path.split("/").slice(0, -1).join("/") : ".";
-    if (!sourceByDir[dir]) sourceByDir[dir] = [];
-    sourceByDir[dir].push(f);
-  }
-  const topDirs = Object.entries(sourceByDir)
-    .sort((a, b) => b[1].length - a[1].length)
-    .slice(0, 10);
-  if (topDirs.length > 0) {
-    lines.push("## Module Map");
-    for (const [dir, dirFiles] of topDirs) {
-      const exts = {};
-      for (const f of dirFiles) {
-        const ext = path.extname(f.path) || "(no ext)";
-        exts[ext] = (exts[ext] || 0) + 1;
-      }
-      const extStr = Object.entries(exts).map(([e, c]) => `${c}${e}`).join(", ");
-      lines.push(`- \`${dir}/\` — ${dirFiles.length} files (${extStr})`);
-    }
-    lines.push("");
-  }
-
-  lines.push("## Notes");
-  lines.push("<!-- Add project-specific instructions, patterns, or gotchas below. -->");
-  lines.push("<!-- The agent reads this file on every turn. -->");
-  lines.push("");
-
-  return lines.join("\n");
-}
-
-// ─────────── Auto-verify: detect project check commands ───────────
-
-export function detectVerifyCommand(cwd) {
-  const pkg = readJsonSafe(path.join(cwd, "package.json"));
-  if (pkg?.scripts) {
-    if (pkg.scripts.typecheck) return { cmd: "npm run typecheck", label: "typecheck" };
-    if (pkg.scripts["type-check"]) return { cmd: "npm run type-check", label: "typecheck" };
-  }
-  if (fs.existsSync(path.join(cwd, "tsconfig.json"))) {
-    const hasTsc = pkg?.devDependencies?.typescript || pkg?.dependencies?.typescript;
-    if (hasTsc) return { cmd: "npx tsc --noEmit", label: "typecheck" };
-  }
-  if (pkg?.scripts) {
-    if (pkg.scripts.lint) return { cmd: "npm run lint", label: "lint" };
-    if (pkg.scripts.check) return { cmd: "npm run check", label: "check" };
-  }
-  const cargo = readTextSafe(path.join(cwd, "Cargo.toml"), 500);
-  if (cargo) return { cmd: "cargo check", label: "cargo check" };
-  const goMod = readTextSafe(path.join(cwd, "go.mod"), 500);
-  if (goMod) return { cmd: "go vet ./...", label: "go vet" };
-  if (fs.existsSync(path.join(cwd, "pyproject.toml"))) {
-    if (pkg?.scripts?.mypy || fs.existsSync(path.join(cwd, "mypy.ini"))) {
-      return { cmd: "mypy .", label: "mypy" };
-    }
-  }
-  return null;
-}
-
-// ─────────── Auto-build: detect compilation / build commands ───────────
-
-export function detectBuildCommand(cwd, writtenFiles = []) {
-  const exts = new Set(writtenFiles.map((f) => path.extname(f).toLowerCase()));
-  const basenames = new Set(writtenFiles.map((f) => path.basename(f).toLowerCase()));
-  const win = process.platform === "win32";
-
-  // Assembly (NASM/FASM/MASM)
-  if (exts.has(".asm") || exts.has(".s")) {
-    const asmFiles = writtenFiles.filter((f) => /\.(asm|s)$/i.test(f));
-    if (asmFiles.length > 0) {
-      const outName = win ? "output.exe" : "output";
-      const objName = asmFiles[0].replace(/\.(asm|s)$/i, ".o");
-      return {
-        cmd: `nasm -f ${win ? "win64" : "elf64"} ${asmFiles[0]} -o ${objName} && ${win ? "link" : "ld"} ${objName} -o ${outName}`,
-        label: "nasm",
-        type: "compiled",
-        runCmd: win ? `.\\${outName}` : `./${outName}`,
-      };
-    }
-  }
-
-  // C/C++
-  if (exts.has(".c") || exts.has(".cpp") || exts.has(".cc") || exts.has(".cxx") || exts.has(".h") || exts.has(".hpp")) {
-    if (fs.existsSync(path.join(cwd, "CMakeLists.txt"))) {
-      return { cmd: "cmake -B build && cmake --build build", label: "cmake", type: "compiled" };
-    }
-    if (fs.existsSync(path.join(cwd, "Makefile")) || fs.existsSync(path.join(cwd, "makefile"))) {
-      return { cmd: "make", label: "make", type: "compiled" };
-    }
-    const cFiles = writtenFiles.filter((f) => /\.(c|cpp|cc|cxx)$/i.test(f));
-    if (cFiles.length > 0) {
-      const hasC = cFiles.some((f) => /\.c$/i.test(f) && !/\.(cpp|cc|cxx)$/i.test(f));
-      const hasCpp = cFiles.some((f) => /\.(cpp|cc|cxx)$/i.test(f));
-      const compiler = hasCpp ? "g++" : "gcc";
-      const outName = win ? "output.exe" : "output";
-      const flags = [];
-      if (hasCpp) flags.push("-std=c++17");
-      else if (hasC) flags.push("-std=c11");
-      flags.push("-Wall", "-O2");
-      // Check if they need threading, math, etc. from the source
-      const allSrc = cFiles.map((f) => {
-        try { return fs.readFileSync(path.join(cwd, f), "utf8"); } catch { return ""; }
-      }).join("\n");
-      if (allSrc.includes("pthread") || allSrc.includes("<thread>")) flags.push("-pthread");
-      if (allSrc.includes("<math.h>") || allSrc.includes("<cmath>")) flags.push("-lm");
-      if (win && (allSrc.includes("winsock") || allSrc.includes("WinSock") || allSrc.includes("ws2_32"))) flags.push("-lws2_32");
-      if (win && allSrc.includes("windows.h")) flags.push("-lkernel32", "-luser32");
-      return {
-        cmd: `${compiler} ${flags.join(" ")} ${cFiles.join(" ")} -o ${outName}`,
-        label: compiler,
-        type: "compiled",
-        runCmd: win ? `.\\${outName}` : `./${outName}`,
-      };
-    }
-  }
-
-  // Rust
-  if (exts.has(".rs") || fs.existsSync(path.join(cwd, "Cargo.toml"))) {
-    if (fs.existsSync(path.join(cwd, "Cargo.toml"))) {
-      return { cmd: "cargo build --release", label: "cargo", type: "compiled" };
-    }
-    const rsFiles = writtenFiles.filter((f) => /\.rs$/i.test(f));
-    if (rsFiles.length === 1) {
-      const outName = win ? "output.exe" : "output";
-      return { cmd: `rustc -o ${outName} ${rsFiles[0]}`, label: "rustc", type: "compiled", runCmd: win ? `.\\${outName}` : `./${outName}` };
-    }
-  }
-
-  // Go
-  if (exts.has(".go") || fs.existsSync(path.join(cwd, "go.mod"))) {
-    const outName = win ? "output.exe" : "output";
-    return { cmd: `go build -o ${outName} ./...`, label: "go build", type: "compiled", runCmd: win ? `.\\${outName}` : `./${outName}` };
-  }
-
-  // C# / .NET
-  if (exts.has(".cs")) {
-    const csproj = writtenFiles.find((f) => f.endsWith(".csproj"));
-    if (csproj || fs.existsSync(path.join(cwd, "*.csproj"))) {
-      return { cmd: "dotnet build", label: "dotnet", type: "compiled" };
-    }
-    const csFiles = writtenFiles.filter((f) => /\.cs$/i.test(f));
-    if (csFiles.length > 0) {
-      const outName = win ? "output.exe" : "output";
-      return { cmd: `dotnet-script ${csFiles[0]}`, label: "dotnet-script", type: "interpreted", runCmd: `dotnet-script ${csFiles[0]}` };
-    }
-  }
-
-  // Java
-  if (exts.has(".java")) {
-    const javaFiles = writtenFiles.filter((f) => /\.java$/i.test(f));
-    if (javaFiles.length > 0) {
-      // Find the file with main()
-      let mainClass = null;
-      for (const jf of javaFiles) {
-        try {
-          const src = fs.readFileSync(path.join(cwd, jf), "utf8");
-          if (src.includes("public static void main")) {
-            mainClass = path.basename(jf, ".java");
-            break;
-          }
-        } catch { /* skip */ }
-      }
-      return {
-        cmd: `javac ${javaFiles.join(" ")}`,
-        label: "javac",
-        type: "compiled",
-        runCmd: mainClass ? `java ${mainClass}` : null,
-      };
-    }
-  }
-
-  // Node/TypeScript — npm build script
-  if (fs.existsSync(path.join(cwd, "package.json"))) {
-    const pkg = readJsonSafe(path.join(cwd, "package.json"));
-    if (pkg?.scripts?.build) {
-      const startCmd = pkg.scripts.start ? "npm start" : null;
-      return { cmd: "npm install && npm run build", label: "npm build", type: "compiled", runCmd: startCmd };
-    }
-    if (pkg?.scripts?.start) {
-      return { cmd: "npm install", label: "npm install", type: "interpreted", runCmd: "npm start" };
-    }
-  }
-
-  // Python
-  if (exts.has(".py")) {
-    // Check for requirements.txt first
-    const hasReqs = fs.existsSync(path.join(cwd, "requirements.txt"));
-    const installCmd = hasReqs ? "pip install -r requirements.txt && " : "";
-    // Priority: main.py > __main__.py > app.py > single file
-    const pyFiles = writtenFiles.filter((f) => /\.py$/i.test(f));
-    const mainCandidates = ["main.py", "__main__.py", "app.py", "run.py"];
-    let entrypoint = null;
-    for (const mc of mainCandidates) {
-      const match = pyFiles.find((f) => path.basename(f).toLowerCase() === mc);
-      if (match) { entrypoint = match; break; }
-    }
-    if (!entrypoint && pyFiles.length === 1) entrypoint = pyFiles[0];
-    if (entrypoint) {
-      return {
-        cmd: installCmd ? installCmd.slice(0, -4) : `python ${entrypoint}`,
-        label: hasReqs ? "pip install" : "python",
-        type: "interpreted",
-        runCmd: `python ${entrypoint}`,
-      };
-    }
-  }
-
-  // Makefile fallback (no source files matched above but a Makefile exists)
-  if (fs.existsSync(path.join(cwd, "Makefile")) || fs.existsSync(path.join(cwd, "makefile"))) {
-    return { cmd: "make", label: "make", type: "compiled" };
-  }
-
-  return null;
-}
-
-export function scanProjectQuick(cwd) {
-  const { dirs, files } = listTopLevel(cwd);
-  const total = dirs.length + files.length;
-  if (total === 0) return "empty directory";
-  const frameworks = detectFrameworks(cwd, files);
-  const pkg = extractPackageInfo(cwd);
-  const parts = [];
-  if (pkg?.name) parts.push(pkg.name);
-  if (frameworks.length > 0) parts.push(frameworks.join(", "));
-  else if (pkg?.frameworks?.length) parts.push(pkg.frameworks[0]);
-  parts.push(`${total} items`);
-  if (pkg?.scripts) parts.push(`${pkg.scripts.length} scripts`);
-  return parts.join(" · ");
-}
+// Project context scanner. Reads the cwd on startup to give the model
+// immediate understanding of what project it's working in — tech stack,
+// file structure, available scripts, dependencies, and any project-specific
+// instructions. This is the single biggest quality-of-life improvement for
+// a weaker model: instead of guessing, it KNOWS.
+
+import fs from "node:fs";
+import path from "node:path";
+
+const SKIP_DIRS = new Set([
+  "node_modules", ".git", ".next", "dist", "build", "__pycache__",
+  ".venv", "venv", "env", ".env", ".idea", ".vscode", "coverage",
+  ".cache", ".turbo", "target", "out", ".output", ".nuxt", ".svelte-kit",
+  "vendor", "bower_components", ".parcel-cache", ".webpack",
+]);
+
+const FRAMEWORK_SIGNATURES = {
+  "next.config.js": "Next.js",
+  "next.config.mjs": "Next.js",
+  "next.config.ts": "Next.js",
+  "nuxt.config.ts": "Nuxt",
+  "svelte.config.js": "SvelteKit",
+  "astro.config.mjs": "Astro",
+  "remix.config.js": "Remix",
+  "angular.json": "Angular",
+  "vue.config.js": "Vue CLI",
+  "vite.config.ts": "Vite",
+  "vite.config.js": "Vite",
+  "webpack.config.js": "Webpack",
+  "tsconfig.json": "TypeScript",
+  "Cargo.toml": "Rust (Cargo)",
+  "go.mod": "Go",
+  "pyproject.toml": "Python",
+  "setup.py": "Python (setuptools)",
+  "requirements.txt": "Python",
+  "Gemfile": "Ruby (Bundler)",
+  "pom.xml": "Java (Maven)",
+  "build.gradle": "Java/Kotlin (Gradle)",
+  "CMakeLists.txt": "C/C++ (CMake)",
+  "Makefile": "Make",
+  "Dockerfile": "Docker",
+  "docker-compose.yml": "Docker Compose",
+  "docker-compose.yaml": "Docker Compose",
+  ".env": "dotenv config",
+  "prisma/schema.prisma": "Prisma ORM",
+  "drizzle.config.ts": "Drizzle ORM",
+};
+
+const DEP_FRAMEWORKS = {
+  next: "Next.js",
+  react: "React",
+  vue: "Vue",
+  svelte: "Svelte",
+  angular: "Angular",
+  express: "Express",
+  fastify: "Fastify",
+  koa: "Koa",
+  hono: "Hono",
+  "socket.io": "Socket.IO",
+  prisma: "Prisma",
+  drizzle: "Drizzle",
+  mongoose: "Mongoose",
+  sequelize: "Sequelize",
+  tailwindcss: "Tailwind CSS",
+  "styled-components": "styled-components",
+  electron: "Electron",
+  jest: "Jest",
+  vitest: "Vitest",
+  mocha: "Mocha",
+  playwright: "Playwright",
+  cypress: "Cypress",
+};
+
+function readJsonSafe(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function readTextSafe(filePath, maxBytes = 2000) {
+  try {
+    const stat = fs.statSync(filePath);
+    if (!stat.isFile() || stat.size > 500_000) return null;
+    const buf = Buffer.alloc(Math.min(stat.size, maxBytes));
+    const fd = fs.openSync(filePath, "r");
+    const bytesRead = fs.readSync(fd, buf, 0, buf.length, 0);
+    fs.closeSync(fd);
+    return buf.toString("utf8", 0, bytesRead);
+  } catch {
+    return null;
+  }
+}
+
+function listTopLevel(cwd) {
+  let entries;
+  try {
+    entries = fs.readdirSync(cwd, { withFileTypes: true });
+  } catch {
+    return { dirs: [], files: [] };
+  }
+  const dirs = [];
+  const files = [];
+  for (const e of entries) {
+    if (e.name.startsWith(".") && e.name !== ".env" && e.name !== ".gitignore") continue;
+    if (SKIP_DIRS.has(e.name)) continue;
+    if (e.isDirectory()) {
+      dirs.push(e.name + "/");
+    } else if (e.isFile()) {
+      files.push(e.name);
+    }
+  }
+  dirs.sort();
+  files.sort();
+  return { dirs, files };
+}
+
+function listSecondLevel(cwd, dirName) {
+  const full = path.join(cwd, dirName);
+  let entries;
+  try {
+    entries = fs.readdirSync(full, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const items = [];
+  for (const e of entries) {
+    if (e.name.startsWith(".")) continue;
+    if (SKIP_DIRS.has(e.name)) continue;
+    items.push(e.isDirectory() ? e.name + "/" : e.name);
+  }
+  items.sort();
+  return items.slice(0, 30);
+}
+
+function detectFrameworks(cwd, topFiles) {
+  const found = new Set();
+  for (const file of topFiles) {
+    if (FRAMEWORK_SIGNATURES[file]) found.add(FRAMEWORK_SIGNATURES[file]);
+  }
+  if (fs.existsSync(path.join(cwd, "prisma", "schema.prisma"))) {
+    found.add("Prisma ORM");
+  }
+  return [...found];
+}
+
+function extractPackageInfo(cwd) {
+  const pkg = readJsonSafe(path.join(cwd, "package.json"));
+  if (!pkg) return null;
+  const info = { name: pkg.name, version: pkg.version };
+  if (pkg.scripts && Object.keys(pkg.scripts).length > 0) {
+    info.scripts = Object.keys(pkg.scripts);
+  }
+  const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+  const detectedLibs = [];
+  for (const [dep, label] of Object.entries(DEP_FRAMEWORKS)) {
+    if (allDeps[dep]) detectedLibs.push(label);
+  }
+  if (detectedLibs.length > 0) info.frameworks = detectedLibs;
+  const depCount = Object.keys(pkg.dependencies || {}).length;
+  const devCount = Object.keys(pkg.devDependencies || {}).length;
+  if (depCount || devCount) {
+    info.depCounts = `${depCount} deps, ${devCount} devDeps`;
+  }
+  return info;
+}
+
+function extractCargoInfo(cwd) {
+  const raw = readTextSafe(path.join(cwd, "Cargo.toml"), 1500);
+  if (!raw) return null;
+  const name = raw.match(/^name\s*=\s*"(.+?)"/m)?.[1];
+  const version = raw.match(/^version\s*=\s*"(.+?)"/m)?.[1];
+  return { name, version, type: "Rust" };
+}
+
+function extractGoInfo(cwd) {
+  const raw = readTextSafe(path.join(cwd, "go.mod"), 500);
+  if (!raw) return null;
+  const mod = raw.match(/^module\s+(\S+)/m)?.[1];
+  const goVer = raw.match(/^go\s+(\S+)/m)?.[1];
+  return { module: mod, goVersion: goVer, type: "Go" };
+}
+
+function extractPythonInfo(cwd) {
+  const pyproject = readTextSafe(path.join(cwd, "pyproject.toml"), 1500);
+  if (pyproject) {
+    const name = pyproject.match(/^name\s*=\s*"(.+?)"/m)?.[1];
+    return { name, type: "Python" };
+  }
+  if (fs.existsSync(path.join(cwd, "requirements.txt"))) {
+    return { type: "Python (requirements.txt)" };
+  }
+  return null;
+}
+
+export function scanProject(cwd) {
+  const { dirs, files } = listTopLevel(cwd);
+  if (dirs.length === 0 && files.length === 0) {
+    return "[project]\nEmpty directory — no files detected.\n[/project]\n";
+  }
+
+  const lines = ["[project]"];
+
+  const frameworks = detectFrameworks(cwd, files);
+  if (frameworks.length > 0) {
+    lines.push(`stack: ${frameworks.join(", ")}`);
+  }
+
+  const pkg = extractPackageInfo(cwd);
+  const cargo = extractCargoInfo(cwd);
+  const goInfo = extractGoInfo(cwd);
+  const pyInfo = extractPythonInfo(cwd);
+
+  if (pkg) {
+    if (pkg.name) lines.push(`package: ${pkg.name}${pkg.version ? `@${pkg.version}` : ""}`);
+    if (pkg.frameworks) lines.push(`libraries: ${pkg.frameworks.join(", ")}`);
+    if (pkg.depCounts) lines.push(`dependencies: ${pkg.depCounts}`);
+    if (pkg.scripts) lines.push(`scripts: ${pkg.scripts.join(", ")}`);
+  }
+  if (cargo) {
+    lines.push(`crate: ${cargo.name || "unknown"}${cargo.version ? `@${cargo.version}` : ""}`);
+  }
+  if (goInfo) {
+    lines.push(`module: ${goInfo.module || "unknown"}${goInfo.goVersion ? ` (go ${goInfo.goVersion})` : ""}`);
+  }
+  if (pyInfo) {
+    lines.push(`python project: ${pyInfo.name || pyInfo.type}`);
+  }
+
+  lines.push("");
+  lines.push("structure:");
+  for (const d of dirs) {
+    lines.push(`  ${d}`);
+    const children = listSecondLevel(cwd, d.replace(/\/$/, ""));
+    for (const child of children.slice(0, 15)) {
+      lines.push(`    ${child}`);
+    }
+    if (children.length > 15) {
+      lines.push(`    ... (${children.length - 15} more)`);
+    }
+  }
+  for (const f of files) {
+    lines.push(`  ${f}`);
+  }
+
+  const contextFile = path.join(cwd, ".aether", "context.md");
+  const context = readTextSafe(contextFile, 3000);
+  if (context) {
+    lines.push("");
+    lines.push("project-instructions:");
+    lines.push(context.trim());
+  }
+
+  const readme = readTextSafe(path.join(cwd, "README.md"), 1500);
+  if (readme) {
+    lines.push("");
+    lines.push("readme-excerpt:");
+    lines.push(readme.trim());
+  }
+
+  lines.push("[/project]");
+  return lines.join("\n") + "\n";
+}
+
+// ─────────── /init — deep project indexing ───────────
+
+const KEY_FILES = [
+  "README.md", "CLAUDE.md", ".env.example", "Dockerfile",
+  "docker-compose.yml", "docker-compose.yaml",
+];
+
+const ENTRY_PATTERNS = [
+  /^(src\/)?index\.[jt]sx?$/,
+  /^(src\/)?main\.[jt]sx?$/,
+  /^(src\/)?app\.[jt]sx?$/,
+  /^(src\/)?server\.[jt]sx?$/,
+  /^(bin|cli|cmd)\/[^/]+\.[jt]sx?$/,
+  /^(pages|app)\/_app\.[jt]sx?$/,
+  /^(pages|app)\/layout\.[jt]sx?$/,
+];
+
+const CONFIG_FILES = [
+  "next.config.js", "next.config.mjs", "next.config.ts",
+  "vite.config.ts", "vite.config.js", "webpack.config.js",
+  "tsconfig.json", "tailwind.config.js", "tailwind.config.ts",
+  "eslint.config.js", ".eslintrc.js", ".eslintrc.json",
+  "jest.config.js", "jest.config.ts", "vitest.config.ts",
+  "prisma/schema.prisma", "drizzle.config.ts",
+];
+
+function collectSourceFiles(dir, base, maxFiles = 500) {
+  const results = [];
+  function walk(current, rel) {
+    if (results.length >= maxFiles) return;
+    let entries;
+    try { entries = fs.readdirSync(current, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (results.length >= maxFiles) return;
+      if (e.name.startsWith(".") && e.name !== ".env.example") continue;
+      if (SKIP_DIRS.has(e.name)) continue;
+      const fullPath = path.join(current, e.name);
+      const relPath = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) {
+        walk(fullPath, relPath);
+      } else if (e.isFile()) {
+        let size = 0;
+        try { size = fs.statSync(fullPath).size; } catch { /* skip */ }
+        results.push({ path: relPath, size });
+      }
+    }
+  }
+  walk(dir, "");
+  return results;
+}
+
+function identifyKeyFiles(allFiles, cwd) {
+  const key = [];
+  for (const f of allFiles) {
+    const name = f.path.split("/").pop();
+    if (KEY_FILES.includes(name)) { key.push(f.path); continue; }
+    if (CONFIG_FILES.includes(f.path)) { key.push(f.path); continue; }
+    for (const pat of ENTRY_PATTERNS) {
+      if (pat.test(f.path)) { key.push(f.path); break; }
+    }
+  }
+  return key;
+}
+
+function summarizeFile(filePath, maxLines = 30) {
+  try {
+    const stat = fs.statSync(filePath);
+    if (!stat.isFile() || stat.size > 200_000) return null;
+    const content = fs.readFileSync(filePath, "utf8");
+    const lines = content.split("\n");
+    const exports = [];
+    const imports = [];
+    for (const line of lines.slice(0, 100)) {
+      if (/^export\s+(default\s+)?(function|class|const|let|async)\s+(\w+)/m.test(line)) {
+        const match = line.match(/^export\s+(?:default\s+)?(?:function|class|const|let|async\s+function)\s+(\w+)/);
+        if (match) exports.push(match[1]);
+      }
+      if (/^import\s/.test(line)) {
+        const match = line.match(/from\s+["']([^"']+)["']/);
+        if (match && !match[1].startsWith(".")) imports.push(match[1]);
+      }
+    }
+    const summary = { lines: lines.length };
+    if (exports.length > 0) summary.exports = exports.slice(0, 15);
+    if (imports.length > 0) summary.externalImports = [...new Set(imports)].slice(0, 10);
+    const firstComment = content.match(/^\/\/\s*(.+)/m);
+    if (firstComment) summary.description = firstComment[1].trim().slice(0, 120);
+    return summary;
+  } catch {
+    return null;
+  }
+}
+
+function detectConventions(allFiles, cwd) {
+  const conventions = [];
+  const extensions = new Set();
+  for (const f of allFiles) {
+    const ext = path.extname(f.path);
+    if (ext) extensions.add(ext);
+  }
+  if (extensions.has(".ts") || extensions.has(".tsx")) conventions.push("TypeScript");
+  if (extensions.has(".jsx") || extensions.has(".tsx")) conventions.push("JSX/TSX (React-style)");
+  const hasTest = allFiles.some((f) =>
+    /\.(test|spec)\.[jt]sx?$/.test(f.path) || f.path.startsWith("test/") || f.path.startsWith("__tests__/"),
+  );
+  if (hasTest) {
+    const testDirs = [];
+    if (allFiles.some((f) => f.path.startsWith("test/"))) testDirs.push("test/");
+    if (allFiles.some((f) => f.path.startsWith("__tests__/"))) testDirs.push("__tests__/");
+    const colocated = allFiles.some((f) => /src\/.*\.(test|spec)\.[jt]sx?$/.test(f.path));
+    if (colocated) testDirs.push("colocated in src/");
+    conventions.push(`Tests: ${testDirs.join(", ") || "detected"}`);
+  }
+  if (fs.existsSync(path.join(cwd, ".prettierrc")) || fs.existsSync(path.join(cwd, ".prettierrc.json"))) {
+    conventions.push("Prettier formatting");
+  }
+  if (fs.existsSync(path.join(cwd, ".eslintrc.js")) || fs.existsSync(path.join(cwd, "eslint.config.js"))) {
+    conventions.push("ESLint");
+  }
+  return conventions;
+}
+
+function buildDirectoryTree(allFiles, maxDepth = 3) {
+  const tree = {};
+  for (const f of allFiles) {
+    const parts = f.path.split("/");
+    let node = tree;
+    for (let i = 0; i < Math.min(parts.length - 1, maxDepth); i++) {
+      if (!node[parts[i]]) node[parts[i]] = {};
+      node = node[parts[i]];
+    }
+  }
+  function render(node, indent = "") {
+    const lines = [];
+    const entries = Object.keys(node).sort();
+    for (const key of entries) {
+      const children = Object.keys(node[key]);
+      lines.push(`${indent}${key}/`);
+      if (children.length > 0 && indent.length < maxDepth * 2) {
+        lines.push(...render(node[key], indent + "  "));
+      }
+    }
+    return lines;
+  }
+  return render(tree);
+}
+
+export function generateProjectIndex(cwd) {
+  const lines = [];
+  lines.push("# Project Context");
+  lines.push(`# Auto-generated by \`aether /init\` — edit freely, this file is yours.`);
+  lines.push(`# Loaded on every agent turn to give the model deep project understanding.`);
+  lines.push("");
+
+  const { dirs, files: topFiles } = listTopLevel(cwd);
+  const frameworks = detectFrameworks(cwd, topFiles);
+  const pkg = extractPackageInfo(cwd);
+  const cargo = extractCargoInfo(cwd);
+  const goInfo = extractGoInfo(cwd);
+  const pyInfo = extractPythonInfo(cwd);
+
+  lines.push("## Overview");
+  if (pkg?.name) lines.push(`- **Package:** ${pkg.name}${pkg.version ? ` v${pkg.version}` : ""}`);
+  if (cargo?.name) lines.push(`- **Crate:** ${cargo.name}${cargo.version ? ` v${cargo.version}` : ""}`);
+  if (goInfo?.module) lines.push(`- **Module:** ${goInfo.module}${goInfo.goVersion ? ` (go ${goInfo.goVersion})` : ""}`);
+  if (pyInfo?.name) lines.push(`- **Python:** ${pyInfo.name || pyInfo.type}`);
+  if (frameworks.length > 0) lines.push(`- **Stack:** ${frameworks.join(", ")}`);
+  if (pkg?.frameworks?.length) lines.push(`- **Libraries:** ${pkg.frameworks.join(", ")}`);
+  if (pkg?.depCounts) lines.push(`- **Dependencies:** ${pkg.depCounts}`);
+  lines.push("");
+
+  const allFiles = collectSourceFiles(cwd);
+  const conventions = detectConventions(allFiles, cwd);
+  if (conventions.length > 0) {
+    lines.push("## Conventions");
+    for (const c of conventions) lines.push(`- ${c}`);
+    lines.push("");
+  }
+
+  if (pkg?.scripts?.length) {
+    lines.push("## Scripts");
+    const pkgFull = readJsonSafe(path.join(cwd, "package.json"));
+    if (pkgFull?.scripts) {
+      for (const [name, cmd] of Object.entries(pkgFull.scripts)) {
+        lines.push(`- \`npm run ${name}\` → \`${cmd}\``);
+      }
+    }
+    lines.push("");
+  }
+
+  lines.push("## Structure");
+  const tree = buildDirectoryTree(allFiles);
+  for (const t of tree.slice(0, 60)) lines.push(t);
+  if (tree.length > 60) lines.push(`... (${tree.length - 60} more directories)`);
+  lines.push("");
+
+  const keyFiles = identifyKeyFiles(allFiles, cwd);
+  if (keyFiles.length > 0) {
+    lines.push("## Key Files");
+    for (const kf of keyFiles.slice(0, 25)) {
+      const abs = path.join(cwd, kf.replace(/\//g, path.sep));
+      const summary = summarizeFile(abs);
+      if (summary) {
+        const desc = summary.description ? ` — ${summary.description}` : "";
+        const exports = summary.exports?.length ? ` (exports: ${summary.exports.join(", ")})` : "";
+        lines.push(`- \`${kf}\` [${summary.lines} lines]${desc}${exports}`);
+      } else {
+        lines.push(`- \`${kf}\``);
+      }
+    }
+    lines.push("");
+  }
+
+  const sourceByDir = {};
+  for (const f of allFiles) {
+    const dir = f.path.includes("/") ? f.path.split("/").slice(0, -1).join("/") : ".";
+    if (!sourceByDir[dir]) sourceByDir[dir] = [];
+    sourceByDir[dir].push(f);
+  }
+  const topDirs = Object.entries(sourceByDir)
+    .sort((a, b) => b[1].length - a[1].length)
+    .slice(0, 10);
+  if (topDirs.length > 0) {
+    lines.push("## Module Map");
+    for (const [dir, dirFiles] of topDirs) {
+      const exts = {};
+      for (const f of dirFiles) {
+        const ext = path.extname(f.path) || "(no ext)";
+        exts[ext] = (exts[ext] || 0) + 1;
+      }
+      const extStr = Object.entries(exts).map(([e, c]) => `${c}${e}`).join(", ");
+      lines.push(`- \`${dir}/\` — ${dirFiles.length} files (${extStr})`);
+    }
+    lines.push("");
+  }
+
+  lines.push("## Notes");
+  lines.push("<!-- Add project-specific instructions, patterns, or gotchas below. -->");
+  lines.push("<!-- The agent reads this file on every turn. -->");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+// ─────────── Auto-verify: detect project check commands ───────────
+
+export function detectVerifyCommand(cwd) {
+  const pkg = readJsonSafe(path.join(cwd, "package.json"));
+  if (pkg?.scripts) {
+    if (pkg.scripts.typecheck) return { cmd: "npm run typecheck", label: "typecheck" };
+    if (pkg.scripts["type-check"]) return { cmd: "npm run type-check", label: "typecheck" };
+  }
+  if (fs.existsSync(path.join(cwd, "tsconfig.json"))) {
+    const hasTsc = pkg?.devDependencies?.typescript || pkg?.dependencies?.typescript;
+    if (hasTsc) return { cmd: "npx tsc --noEmit", label: "typecheck" };
+  }
+  if (pkg?.scripts) {
+    if (pkg.scripts.lint) return { cmd: "npm run lint", label: "lint" };
+    if (pkg.scripts.check) return { cmd: "npm run check", label: "check" };
+  }
+  const cargo = readTextSafe(path.join(cwd, "Cargo.toml"), 500);
+  if (cargo) return { cmd: "cargo check", label: "cargo check" };
+  const goMod = readTextSafe(path.join(cwd, "go.mod"), 500);
+  if (goMod) return { cmd: "go vet ./...", label: "go vet" };
+  if (fs.existsSync(path.join(cwd, "pyproject.toml"))) {
+    if (pkg?.scripts?.mypy || fs.existsSync(path.join(cwd, "mypy.ini"))) {
+      return { cmd: "mypy .", label: "mypy" };
+    }
+  }
+  return null;
+}
+
+// ─────────── Auto-build: detect compilation / build commands ───────────
+
+export function detectBuildCommand(cwd, writtenFiles = []) {
+  const exts = new Set(writtenFiles.map((f) => path.extname(f).toLowerCase()));
+  const basenames = new Set(writtenFiles.map((f) => path.basename(f).toLowerCase()));
+  const win = process.platform === "win32";
+  // Quote a path for a shell:true command so filenames/dirs with spaces don't
+  // split into multiple args (a bare `src/my game/main.cpp` made g++ fail with a
+  // "no such file" that looked like a build error). Double quotes work in both
+  // cmd.exe and POSIX sh.
+  const q = (p) => `"${p}"`;
+
+  // Assembly (NASM/FASM/MASM)
+  if (exts.has(".asm") || exts.has(".s")) {
+    const asmFiles = writtenFiles.filter((f) => /\.(asm|s)$/i.test(f));
+    if (asmFiles.length > 0) {
+      const outName = win ? "output.exe" : "output";
+      const objName = asmFiles[0].replace(/\.(asm|s)$/i, ".o");
+      return {
+        cmd: `nasm -f ${win ? "win64" : "elf64"} ${q(asmFiles[0])} -o ${q(objName)} && ${win ? "link" : "ld"} ${q(objName)} -o ${outName}`,
+        label: "nasm",
+        type: "compiled",
+        runCmd: win ? `.\\${outName}` : `./${outName}`,
+      };
+    }
+  }
+
+  // C/C++
+  if (exts.has(".c") || exts.has(".cpp") || exts.has(".cc") || exts.has(".cxx") || exts.has(".h") || exts.has(".hpp")) {
+    if (fs.existsSync(path.join(cwd, "CMakeLists.txt"))) {
+      return { cmd: "cmake -B build && cmake --build build", label: "cmake", type: "compiled" };
+    }
+    if (fs.existsSync(path.join(cwd, "Makefile")) || fs.existsSync(path.join(cwd, "makefile"))) {
+      return { cmd: "make", label: "make", type: "compiled" };
+    }
+    const cFiles = writtenFiles.filter((f) => /\.(c|cpp|cc|cxx)$/i.test(f));
+    if (cFiles.length > 0) {
+      const hasC = cFiles.some((f) => /\.c$/i.test(f) && !/\.(cpp|cc|cxx)$/i.test(f));
+      const hasCpp = cFiles.some((f) => /\.(cpp|cc|cxx)$/i.test(f));
+      const compiler = hasCpp ? "g++" : "gcc";
+      const outName = win ? "output.exe" : "output";
+      const flags = [];
+      if (hasCpp) flags.push("-std=c++17");
+      else if (hasC) flags.push("-std=c11");
+      flags.push("-Wall", "-O2");
+      // Check if they need threading, math, etc. from the source
+      const allSrc = cFiles.map((f) => {
+        try { return fs.readFileSync(path.join(cwd, f), "utf8"); } catch { return ""; }
+      }).join("\n");
+      if (allSrc.includes("pthread") || allSrc.includes("<thread>")) flags.push("-pthread");
+      if (allSrc.includes("<math.h>") || allSrc.includes("<cmath>")) flags.push("-lm");
+      if (win && (allSrc.includes("winsock") || allSrc.includes("WinSock") || allSrc.includes("ws2_32"))) flags.push("-lws2_32");
+      if (win && allSrc.includes("windows.h")) flags.push("-lkernel32", "-luser32");
+      return {
+        cmd: `${compiler} ${flags.join(" ")} ${cFiles.map(q).join(" ")} -o ${outName}`,
+        label: compiler,
+        type: "compiled",
+        runCmd: win ? `.\\${outName}` : `./${outName}`,
+      };
+    }
+  }
+
+  // Rust
+  if (exts.has(".rs") || fs.existsSync(path.join(cwd, "Cargo.toml"))) {
+    if (fs.existsSync(path.join(cwd, "Cargo.toml"))) {
+      return { cmd: "cargo build --release", label: "cargo", type: "compiled" };
+    }
+    const rsFiles = writtenFiles.filter((f) => /\.rs$/i.test(f));
+    if (rsFiles.length === 1) {
+      const outName = win ? "output.exe" : "output";
+      return { cmd: `rustc -o ${outName} ${q(rsFiles[0])}`, label: "rustc", type: "compiled", runCmd: win ? `.\\${outName}` : `./${outName}` };
+    }
+  }
+
+  // Go
+  if (exts.has(".go") || fs.existsSync(path.join(cwd, "go.mod"))) {
+    const outName = win ? "output.exe" : "output";
+    return { cmd: `go build -o ${outName} ./...`, label: "go build", type: "compiled", runCmd: win ? `.\\${outName}` : `./${outName}` };
+  }
+
+  // C# / .NET
+  if (exts.has(".cs")) {
+    const csproj = writtenFiles.find((f) => f.endsWith(".csproj"));
+    if (csproj || fs.existsSync(path.join(cwd, "*.csproj"))) {
+      return { cmd: "dotnet build", label: "dotnet", type: "compiled" };
+    }
+    const csFiles = writtenFiles.filter((f) => /\.cs$/i.test(f));
+    if (csFiles.length > 0) {
+      const outName = win ? "output.exe" : "output";
+      return { cmd: `dotnet-script ${csFiles[0]}`, label: "dotnet-script", type: "interpreted", runCmd: `dotnet-script ${csFiles[0]}` };
+    }
+  }
+
+  // Java
+  if (exts.has(".java")) {
+    const javaFiles = writtenFiles.filter((f) => /\.java$/i.test(f));
+    if (javaFiles.length > 0) {
+      // Find the file with main()
+      let mainClass = null;
+      for (const jf of javaFiles) {
+        try {
+          const src = fs.readFileSync(path.join(cwd, jf), "utf8");
+          if (src.includes("public static void main")) {
+            mainClass = path.basename(jf, ".java");
+            break;
+          }
+        } catch { /* skip */ }
+      }
+      return {
+        cmd: `javac ${javaFiles.map(q).join(" ")}`,
+        label: "javac",
+        type: "compiled",
+        runCmd: mainClass ? `java ${mainClass}` : null,
+      };
+    }
+  }
+
+  // Node/TypeScript — npm build script
+  if (fs.existsSync(path.join(cwd, "package.json"))) {
+    const pkg = readJsonSafe(path.join(cwd, "package.json"));
+    if (pkg?.scripts?.build) {
+      const startCmd = pkg.scripts.start ? "npm start" : null;
+      return { cmd: "npm install && npm run build", label: "npm build", type: "compiled", runCmd: startCmd };
+    }
+    if (pkg?.scripts?.start) {
+      return { cmd: "npm install", label: "npm install", type: "interpreted", runCmd: "npm start" };
+    }
+  }
+
+  // Python
+  if (exts.has(".py")) {
+    // Check for requirements.txt first
+    const hasReqs = fs.existsSync(path.join(cwd, "requirements.txt"));
+    const installCmd = hasReqs ? "pip install -r requirements.txt && " : "";
+    // Priority: main.py > __main__.py > app.py > single file
+    const pyFiles = writtenFiles.filter((f) => /\.py$/i.test(f));
+    const mainCandidates = ["main.py", "__main__.py", "app.py", "run.py"];
+    let entrypoint = null;
+    for (const mc of mainCandidates) {
+      const match = pyFiles.find((f) => path.basename(f).toLowerCase() === mc);
+      if (match) { entrypoint = match; break; }
+    }
+    if (!entrypoint && pyFiles.length === 1) entrypoint = pyFiles[0];
+    if (entrypoint) {
+      return {
+        cmd: installCmd ? installCmd.slice(0, -4) : `python ${entrypoint}`,
+        label: hasReqs ? "pip install" : "python",
+        type: "interpreted",
+        runCmd: `python ${entrypoint}`,
+      };
+    }
+  }
+
+  // Makefile fallback (no source files matched above but a Makefile exists)
+  if (fs.existsSync(path.join(cwd, "Makefile")) || fs.existsSync(path.join(cwd, "makefile"))) {
+    return { cmd: "make", label: "make", type: "compiled" };
+  }
+
+  return null;
+}
+
+export function scanProjectQuick(cwd) {
+  const { dirs, files } = listTopLevel(cwd);
+  const total = dirs.length + files.length;
+  if (total === 0) return "empty directory";
+  const frameworks = detectFrameworks(cwd, files);
+  const pkg = extractPackageInfo(cwd);
+  const parts = [];
+  if (pkg?.name) parts.push(pkg.name);
+  if (frameworks.length > 0) parts.push(frameworks.join(", "));
+  else if (pkg?.frameworks?.length) parts.push(pkg.frameworks[0]);
+  parts.push(`${total} items`);
+  if (pkg?.scripts) parts.push(`${pkg.scripts.length} scripts`);
+  return parts.join(" · ");
+}