repo-docs-framework 0.1.0

package/README.md

@@ -0,0 +1,119 @@
+# Repo Docs Framework (Tree-sitter → Repo Map → Sys Design)
+
+This is a **repo-agnostic framework** that generates Copilot-friendly documentation for **any** codebase:
+
+```
+Codebase
+  ↓
+Tree-sitter AST (optional, for symbols)
+  ↓
+Symbol extraction
+  ↓
+Repo Map (repo-map.md)
+  ↓
+System Design (sys-design.md = repo-map + architecture + api-flow + detected stack/languages)
+```
+
+It’s intentionally dependency-light:
+- Uses **Node.js** only (no npm install required to run the generators)
+- Uses **Tree-sitter CLI globally** (not installed in the target repo)
+
+## What it generates
+
+Inside a chosen output folder (default: `docs/`):
+- `repo-map.md` (auto-generated)
+- `sys-design.md` (auto-generated)
+- `architecture.md` (optional template, if missing)
+- `api-flow.md` (optional template, if missing)
+
+## Quick start (any repo)
+
+From the repo root you want to document:
+
+```bash
+node /path/to/repo-docs-framework/bin/repo-docs.mjs --root . --out docs
+```
+
+Re-run any time things change.
+
+## Tree-sitter global install (recommended)
+
+The framework can generate a repo map without Tree-sitter, but **symbol extraction requires it**.
+
+### Install Tree-sitter CLI globally
+
+Pick one:
+
+```bash
+# npm global install
+npm i -g tree-sitter-cli
+
+# or cargo install
+cargo install tree-sitter-cli
+```
+
+Verify:
+
+```bash
+tree-sitter --version
+```
+
+### Install grammars (multi-language)
+
+Tree-sitter discovers grammars via a global config.
+
+1) Create config:
+
+```bash
+tree-sitter init-config
+```
+
+2) Add grammar directory in `~/.config/tree-sitter/config.json` (Linux):
+
+```json
+{
+  "parser-directories": [
+    "$HOME/.tree-sitter-parsers"
+  ]
+}
+```
+
+3) Clone grammars into that directory (names must start with `tree-sitter-`):
+
+```bash
+mkdir -p "$HOME/.tree-sitter-parsers"
+cd "$HOME/.tree-sitter-parsers"
+
+# Common starters
+git clone https://github.com/tree-sitter/tree-sitter-typescript
+git clone https://github.com/tree-sitter/tree-sitter-javascript
+git clone https://github.com/tree-sitter/tree-sitter-python
+git clone https://github.com/tree-sitter/tree-sitter-go
+git clone https://github.com/tree-sitter/tree-sitter-java
+git clone https://github.com/tree-sitter/tree-sitter-rust
+git clone https://github.com/tree-sitter/tree-sitter-json
+git clone https://github.com/tree-sitter/tree-sitter-yaml
+git clone https://github.com/tree-sitter/tree-sitter-bash
+```
+
+Confirm:
+
+```bash
+tree-sitter dump-languages
+```
+
+## How it decides “stack” and “languages”
+
+- **Languages**: file extension counts across the target `--root`, excluding configured ignore dirs.
+- **Stack**: heuristic detection from:
+  - package manifests (`package.json`, `pyproject.toml`, `go.mod`, etc.)
+  - well-known config files (`docker-compose.yml`, `k8s/`, `terraform`, etc.)
+  - common folder patterns (`src/`, `apps/`, `services/`, etc.)
+
+You can customize ignores and behavior via `--config` (see `config/default.json`).
+
+## Suggested automation (optional)
+
+- Pre-commit hook to regenerate docs
+- CI job to ensure generated docs are up to date (fail on diff)
+

package/bin/repo-docs.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadConfig, parseArgs, runRepoDocs } from "../src/index.mjs";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const cfg = await loadConfig({
+    frameworkRoot: path.resolve(__dirname, ".."),
+    configPath: args.config,
+    overrides: {
+      outDir: args.out,
+      // allow renaming output filenames if user wants later
+    }
+  });
+
+  await runRepoDocs({
+    rootDir: path.resolve(process.cwd(), args.root ?? "."),
+    outDir: path.resolve(process.cwd(), args.out ?? cfg.outDir),
+    cfg
+  });
+}
+
+main().catch((err) => {
+  process.stderr.write(String(err?.stack ?? err) + "\n");
+  process.exitCode = 1;
+});
+

package/config/default.json

@@ -0,0 +1,99 @@
+{
+  "outDir": "docs",
+  "repoMapFile": "repo-map.md",
+  "sysDesignFile": "sys-design.md",
+  "architectureFile": "architecture.md",
+  "apiFlowFile": "api-flow.md",
+
+  "maxTreeDepth": 6,
+  "maxFilesPerDir": 120,
+
+  "ignoreDirs": [
+    ".git",
+    ".hg",
+    ".svn",
+    ".idea",
+    ".vscode",
+    "node_modules",
+    "dist",
+    "build",
+    "out",
+    "coverage",
+    ".nyc_output",
+    ".next",
+    ".turbo",
+    ".cache",
+    ".venv",
+    "venv",
+    "__pycache__",
+    "target",
+    "vendor",
+    ".terraform",
+    ".gradle",
+    ".m2"
+  ],
+
+  "ignoreFiles": [
+    "pnpm-lock.yaml",
+    "package-lock.json",
+    "yarn.lock",
+    "poetry.lock",
+    "uv.lock",
+    "composer.lock",
+    "Cargo.lock",
+    "go.sum",
+    "*.tsbuildinfo",
+    "*.log"
+  ],
+
+  "treeIncludeExtensions": [
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".cjs",
+    ".py",
+    ".go",
+    ".rs",
+    ".java",
+    ".kt",
+    ".cs",
+    ".php",
+    ".rb",
+    ".swift",
+    ".scala",
+    ".tf",
+    ".yaml",
+    ".yml",
+    ".json",
+    ".toml",
+    ".ini",
+    ".md",
+    ".sh",
+    ".dockerfile"
+  ],
+
+  "symbolExtensions": [
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".cjs",
+    ".py",
+    ".go",
+    ".rs",
+    ".java",
+    ".kt",
+    ".cs",
+    ".php",
+    ".rb"
+  ],
+
+  "copilot": {
+    "recommendedContextFiles": ["architecture.md", "repo-map.md", "api-flow.md", "sys-design.md"],
+    "recommendedHint": "Use repo-map.md + sys-design.md as the repo map. Prefer source directories over generated outputs; avoid editing build artifacts. When adding a feature, update the entrypoints, the core module, and any API/schema definitions."
+  }
+}
+

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "repo-docs-framework",
+  "version": "0.1.0",
+  "description": "Repo-agnostic Tree-sitter powered repo-map + system-design generator (Copilot-friendly).",
+  "type": "module",
+  "license": "UNLICENSED",
+  "bin": {
+    "repo-docs": "./bin/repo-docs.mjs"
+  },
+  "files": [
+    "bin/",
+    "config/",
+    "src/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test:smoke": "node ./test/smoke.mjs",
+    "prepack": "npm run test:smoke"
+  },
+  "keywords": [
+    "tree-sitter",
+    "repo-map",
+    "architecture",
+    "system-design",
+    "copilot",
+    "documentation",
+    "cli"
+  ]
+}
+

package/src/index.mjs

@@ -0,0 +1,4 @@
+export { parseArgs } from "./lib/args.mjs";
+export { loadConfig } from "./lib/config.mjs";
+export { runRepoDocs } from "./lib/run.mjs";
+

package/src/lib/args.mjs

@@ -0,0 +1,51 @@
+function usage() {
+  return `
+Repo Docs Framework
+
+Generate:
+  - repo-map.md
+  - sys-design.md
+  - (optional templates) architecture.md, api-flow.md
+
+Usage:
+  repo-docs.mjs --root <path> --out <path> [--config <path>]
+
+Examples:
+  node tools/repo-docs-framework/bin/repo-docs.mjs --root . --out docs
+  node /abs/path/repo-docs.mjs --root /path/to/repo --out /path/to/repo/docs
+
+Flags:
+  --root     Target repository root to scan (default ".")
+  --out      Output docs folder (default "docs")
+  --config   Optional path to config JSON
+  --help     Show help
+`.trim();
+}
+
+export function parseArgs(argv) {
+  const out = { root: ".", out: "docs", config: undefined };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") {
+      process.stdout.write(usage() + "\n");
+      process.exit(0);
+    }
+    if (a === "--root") {
+      out.root = argv[++i];
+      continue;
+    }
+    if (a === "--out") {
+      out.out = argv[++i];
+      continue;
+    }
+    if (a === "--config") {
+      out.config = argv[++i];
+      continue;
+    }
+    if (a.startsWith("-")) {
+      throw new Error(`Unknown flag: ${a}\n\n${usage()}`);
+    }
+  }
+  return out;
+}
+

package/src/lib/config.mjs

@@ -0,0 +1,24 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+async function readJson(filePath) {
+  return JSON.parse(await fs.readFile(filePath, "utf8"));
+}
+
+function deepMerge(a, b) {
+  if (Array.isArray(a) || Array.isArray(b)) return b ?? a;
+  if (a && typeof a === "object" && b && typeof b === "object") {
+    const out = { ...a };
+    for (const [k, v] of Object.entries(b)) out[k] = deepMerge(a[k], v);
+    return out;
+  }
+  return b ?? a;
+}
+
+export async function loadConfig({ frameworkRoot, configPath, overrides }) {
+  const defaultPath = path.join(frameworkRoot, "config/default.json");
+  const base = await readJson(defaultPath);
+  const user = configPath ? await readJson(path.resolve(process.cwd(), configPath)) : {};
+  return deepMerge(deepMerge(base, user), overrides ?? {});
+}
+

package/src/lib/languages.mjs

@@ -0,0 +1,50 @@
+import path from "node:path";
+
+const extToLang = new Map([
+  [".ts", "TypeScript"],
+  [".tsx", "TypeScript (React)"],
+  [".js", "JavaScript"],
+  [".jsx", "JavaScript (React)"],
+  [".mjs", "JavaScript (ESM)"],
+  [".cjs", "JavaScript (CJS)"],
+  [".py", "Python"],
+  [".go", "Go"],
+  [".rs", "Rust"],
+  [".java", "Java"],
+  [".kt", "Kotlin"],
+  [".cs", "C#"],
+  [".php", "PHP"],
+  [".rb", "Ruby"],
+  [".swift", "Swift"],
+  [".scala", "Scala"],
+  [".sql", "SQL"],
+  [".tf", "Terraform"],
+  [".yaml", "YAML"],
+  [".yml", "YAML"],
+  [".toml", "TOML"],
+  [".ini", "INI"],
+  [".json", "JSON"],
+  [".md", "Markdown"],
+  [".sh", "Shell"]
+]);
+
+function ext(rel) {
+  return path.extname(rel).toLowerCase();
+}
+
+export function summarizeLanguages(filesRel) {
+  const langCounts = new Map();
+  const extCounts = new Map();
+
+  for (const f of filesRel) {
+    const e = ext(f);
+    if (e) extCounts.set(e, (extCounts.get(e) ?? 0) + 1);
+    const lang = extToLang.get(e) ?? "Other/Unknown";
+    langCounts.set(lang, (langCounts.get(lang) ?? 0) + 1);
+  }
+
+  const langs = [...langCounts.entries()].sort((a, b) => b[1] - a[1]);
+  const exts = [...extCounts.entries()].sort((a, b) => b[1] - a[1]);
+  return { langs, exts };
+}
+

package/src/lib/run.mjs

@@ -0,0 +1,214 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+import { walkFiles } from "./scan.mjs";
+import { treeLines } from "./tree.mjs";
+import { summarizeLanguages } from "./languages.mjs";
+import { detectStack } from "./stack.mjs";
+import { extractSymbols } from "./tree_sitter.mjs";
+import { architectureTemplate, apiFlowTemplate } from "./templates.mjs";
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+async function exists(p) {
+  try {
+    await fs.stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readUtf8(p) {
+  return await fs.readFile(p, "utf8");
+}
+
+async function writeUtf8(p, content) {
+  await fs.mkdir(path.dirname(p), { recursive: true });
+  await fs.writeFile(p, content, "utf8");
+}
+
+function mdEsc(s) {
+  return String(s).replaceAll("|", "\\|");
+}
+
+function formatSymbols(grouped, { maxPerFile = 60 } = {}) {
+  const lines = [];
+  for (const [file, syms] of grouped) {
+    lines.push(`- **\`${mdEsc(file)}\`**`);
+    const shown = syms.slice(0, maxPerFile);
+    for (const s of shown) {
+      const loc = s.line ? `:${s.line}` : "";
+      lines.push(`  - \`${mdEsc(s.kind)}\` \`${mdEsc(s.name)}\`${loc}`);
+    }
+    if (syms.length > maxPerFile) lines.push(`  - … (${syms.length - maxPerFile} more)`);
+  }
+  return lines;
+}
+
+function frontMatter(obj) {
+  const lines = ["---"];
+  for (const [k, v] of Object.entries(obj)) {
+    if (Array.isArray(v)) {
+      lines.push(`${k}:`);
+      for (const item of v) lines.push(`  - ${item}`);
+      continue;
+    }
+    lines.push(`${k}: ${v}`);
+  }
+  lines.push("---");
+  return lines.join("\n");
+}
+
+function rootNameFromPath(rootDir) {
+  const base = path.basename(rootDir);
+  return base || "repo";
+}
+
+async function readPackageJsonMaybe(rootDir) {
+  const pj = path.join(rootDir, "package.json");
+  if (!(await exists(pj))) return null;
+  try {
+    return JSON.parse(await readUtf8(pj));
+  } catch {
+    return null;
+  }
+}
+
+export async function runRepoDocs({ rootDir, outDir, cfg }) {
+  const filesRel = await walkFiles(rootDir, cfg);
+  const pkg = await readPackageJsonMaybe(rootDir);
+
+  const rootName = rootNameFromPath(rootDir);
+  const stack = detectStack({ filesRel, packageJson: pkg });
+  const { langs, exts } = summarizeLanguages(filesRel);
+
+  // Ensure base docs exist (templates) in output folder.
+  const architecturePath = path.join(outDir, cfg.architectureFile);
+  const apiFlowPath = path.join(outDir, cfg.apiFlowFile);
+  const repoMapPath = path.join(outDir, cfg.repoMapFile);
+  const sysDesignPath = path.join(outDir, cfg.sysDesignFile);
+
+  if (!(await exists(architecturePath))) {
+    await writeUtf8(architecturePath, architectureTemplate({ rootName, stackList: stack }));
+  }
+  if (!(await exists(apiFlowPath))) {
+    await writeUtf8(apiFlowPath, apiFlowTemplate({ rootName }));
+  }
+
+  // Repo map generation.
+  const tree = treeLines(filesRel, cfg);
+  const symbols = extractSymbols({ rootDir, filesRel, cfg });
+
+  const repoMapMd = [];
+  repoMapMd.push(
+    frontMatter({
+      generatedAt: nowIso(),
+      scope: rootName,
+      generator: "repo-docs-framework",
+      rootDir: path.resolve(rootDir)
+    })
+  );
+  repoMapMd.push("");
+  repoMapMd.push("## Repo map");
+  repoMapMd.push("");
+  repoMapMd.push("Regenerate:");
+  repoMapMd.push("");
+  repoMapMd.push("```bash");
+  repoMapMd.push(`node tools/repo-docs-framework/bin/repo-docs.mjs --root "${path.resolve(rootDir)}" --out "${path.resolve(outDir)}"`);
+  repoMapMd.push("```");
+  repoMapMd.push("");
+  repoMapMd.push("### Directory tree (filtered)");
+  repoMapMd.push("");
+  repoMapMd.push("```text");
+  repoMapMd.push(`${rootName}/`);
+  for (const l of tree) repoMapMd.push(`  ${l}`);
+  repoMapMd.push("```");
+  repoMapMd.push("");
+  repoMapMd.push("### Symbol index (Tree-sitter tags)");
+  repoMapMd.push("");
+  if (!symbols.available) {
+    repoMapMd.push("**Tree-sitter CLI not found.** Install it globally to enable symbol extraction.");
+  } else if (symbols.grouped.length === 0) {
+    repoMapMd.push("**No symbols extracted.** Install/configure the required grammars for your languages.");
+  } else {
+    if (symbols.failures) repoMapMd.push(`_Note: tags failed for ${symbols.failures} file(s); index is partial._\n`);
+    repoMapMd.push(...formatSymbols(symbols.grouped, { maxPerFile: 60 }));
+  }
+  repoMapMd.push("");
+  repoMapMd.push("### Copilot Chat suggested context");
+  repoMapMd.push("");
+  const ctx = (cfg.copilot?.recommendedContextFiles ?? []).map((f) => `- \`${f}\``);
+  repoMapMd.push(...ctx);
+  repoMapMd.push("");
+  if (cfg.copilot?.recommendedHint) {
+    repoMapMd.push("Suggested hint to paste into Copilot Chat:");
+    repoMapMd.push("");
+    repoMapMd.push("```text");
+    repoMapMd.push(cfg.copilot.recommendedHint);
+    repoMapMd.push("```");
+    repoMapMd.push("");
+  }
+  await writeUtf8(repoMapPath, repoMapMd.join("\n"));
+
+  // Sys design = merge + detected tables.
+  const [architectureMd, apiFlowMd, repoMapFinal] = await Promise.all([
+    readUtf8(architecturePath),
+    readUtf8(apiFlowPath),
+    readUtf8(repoMapPath)
+  ]);
+
+  const sys = [];
+  sys.push(
+    frontMatter({
+      generatedAt: nowIso(),
+      scope: rootName,
+      generator: "repo-docs-framework",
+      inputs: [path.relative(outDir, architecturePath), path.relative(outDir, apiFlowPath), path.relative(outDir, repoMapPath)].map((p) =>
+        p.split(path.sep).join("/")
+      )
+    })
+  );
+  sys.push("");
+  sys.push(`# System design (${rootName})`);
+  sys.push("");
+  sys.push("## Stack (detected)");
+  sys.push("");
+  for (const s of stack) sys.push(`- ${s}`);
+  if (!stack.length) sys.push("- (no stack signals detected)");
+  sys.push("");
+  sys.push("## Languages (detected)");
+  sys.push("");
+  sys.push("| Language | Files |");
+  sys.push("|---|---:|");
+  for (const [lang, count] of langs) sys.push(`| ${lang} | ${count} |`);
+  sys.push("");
+  sys.push("### Extensions (top)");
+  sys.push("");
+  sys.push("| Extension | Files |");
+  sys.push("|---|---:|");
+  for (const [e, count] of exts.slice(0, 20)) sys.push(`| \`${e}\` | ${count} |`);
+  sys.push("");
+  sys.push("## Merged docs");
+  sys.push("");
+  sys.push("### Architecture");
+  sys.push("");
+  sys.push(architectureMd.trim());
+  sys.push("");
+  sys.push("### API flow");
+  sys.push("");
+  sys.push(apiFlowMd.trim());
+  sys.push("");
+  sys.push("### Repo map");
+  sys.push("");
+  sys.push(repoMapFinal.trim());
+  sys.push("");
+
+  await writeUtf8(sysDesignPath, sys.join("\n"));
+
+  process.stdout.write(`Wrote ${path.relative(process.cwd(), repoMapPath)}\n`);
+  process.stdout.write(`Wrote ${path.relative(process.cwd(), sysDesignPath)}\n`);
+}
+

package/src/lib/scan.mjs

@@ -0,0 +1,40 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+function matchesGlobLike(name, patterns) {
+  // Very small glob subset: only supports "*.ext" patterns for ignoreFiles.
+  for (const p of patterns) {
+    if (p.includes("*")) {
+      const suffix = p.replaceAll("*", "");
+      if (suffix && name.endsWith(suffix)) return true;
+    } else {
+      if (name === p) return true;
+    }
+  }
+  return false;
+}
+
+export async function walkFiles(rootDir, cfg) {
+  const ignoreDirs = new Set(cfg.ignoreDirs ?? []);
+  const ignoreFiles = cfg.ignoreFiles ?? [];
+
+  async function rec(dirAbs) {
+    const out = [];
+    const entries = await fs.readdir(dirAbs, { withFileTypes: true });
+    for (const ent of entries) {
+      const abs = path.join(dirAbs, ent.name);
+      const rel = path.relative(rootDir, abs).split(path.sep).join("/");
+      if (ent.isDirectory()) {
+        if (ignoreDirs.has(ent.name)) continue;
+        out.push(...(await rec(abs)));
+      } else if (ent.isFile()) {
+        if (matchesGlobLike(ent.name, ignoreFiles)) continue;
+        out.push(rel);
+      }
+    }
+    return out;
+  }
+
+  return await rec(rootDir);
+}
+

package/src/lib/stack.mjs

@@ -0,0 +1,74 @@
+// Heuristic stack detection for arbitrary repos.
+// Strategy: look for well-known manifest/config files and dependency names.
+
+function hasFile(filesRel, p) {
+  return filesRel.includes(p);
+}
+
+function hasPrefix(filesRel, pref) {
+  return filesRel.some((f) => f.startsWith(pref));
+}
+
+function getJsonDeps(pkgJson) {
+  const deps = { ...(pkgJson?.dependencies ?? {}), ...(pkgJson?.devDependencies ?? {}) };
+  return new Set(Object.keys(deps));
+}
+
+function addIf(arr, cond, label) {
+  if (cond) arr.push(label);
+}
+
+export function detectStack({ filesRel, packageJson }) {
+  const out = [];
+  const deps = packageJson ? getJsonDeps(packageJson) : new Set();
+
+  // Containers & orchestration.
+  addIf(out, hasFile(filesRel, "docker-compose.yml") || hasFile(filesRel, "compose.yaml"), "Docker Compose");
+  addIf(out, hasPrefix(filesRel, "k8s/") || hasPrefix(filesRel, "helm/"), "Kubernetes");
+
+  // IaC.
+  addIf(out, hasPrefix(filesRel, "terraform/") || filesRel.some((f) => f.endsWith(".tf")), "Terraform");
+  addIf(out, hasFile(filesRel, "cdk.json") || deps.has("aws-cdk-lib"), "AWS CDK");
+  addIf(out, deps.has("serverless") || hasFile(filesRel, "serverless.yml"), "Serverless Framework");
+
+  // JS/TS ecosystem.
+  addIf(out, hasFile(filesRel, "package.json"), "Node.js");
+  addIf(out, hasFile(filesRel, "pnpm-lock.yaml"), "pnpm");
+  addIf(out, hasFile(filesRel, "yarn.lock"), "Yarn");
+  addIf(out, hasFile(filesRel, "package-lock.json"), "npm");
+  addIf(out, hasFile(filesRel, "tsconfig.json") || deps.has("typescript"), "TypeScript");
+  addIf(out, deps.has("next") || hasPrefix(filesRel, "apps/") && hasPrefix(filesRel, "apps/") && filesRel.some((f) => f.includes("next.config")), "Next.js");
+  addIf(out, deps.has("react") || filesRel.some((f) => f.endsWith(".tsx") || f.endsWith(".jsx")), "React");
+  addIf(out, deps.has("vite"), "Vite");
+  addIf(out, deps.has("express"), "Express");
+  addIf(out, deps.has("fastify"), "Fastify");
+  addIf(out, deps.has("nestjs/core") || deps.has("@nestjs/core"), "NestJS");
+
+  // Python.
+  addIf(out, hasFile(filesRel, "pyproject.toml") || hasFile(filesRel, "requirements.txt"), "Python");
+  addIf(out, filesRel.some((f) => f.includes("poetry.lock")), "Poetry");
+
+  // Go.
+  addIf(out, hasFile(filesRel, "go.mod"), "Go");
+
+  // Rust.
+  addIf(out, hasFile(filesRel, "Cargo.toml"), "Rust");
+
+  // Java/Kotlin.
+  addIf(out, hasFile(filesRel, "pom.xml"), "Maven (Java)");
+  addIf(out, hasFile(filesRel, "build.gradle") || hasFile(filesRel, "build.gradle.kts"), "Gradle (Java/Kotlin)");
+
+  // .NET.
+  addIf(out, filesRel.some((f) => f.endsWith(".csproj") || f.endsWith(".sln")), ".NET");
+
+  // Common clouds/services.
+  addIf(out, deps.has("@aws-sdk/client-s3") || deps.has("@aws-sdk/client-dynamodb") || deps.has("@aws-sdk/client-lambda"), "AWS SDK");
+  addIf(out, deps.has("@google-cloud/storage") || deps.has("@google-cloud/firestore"), "Google Cloud SDK");
+  addIf(out, deps.has("@azure/storage-blob"), "Azure SDK");
+
+  // API specs.
+  addIf(out, filesRel.some((f) => f.toLowerCase().includes("openapi") || f.endsWith("openapi.yaml") || f.endsWith("openapi.yml")), "OpenAPI");
+
+  return [...new Set(out)];
+}
+

package/src/lib/templates.mjs

@@ -0,0 +1,56 @@
+export function architectureTemplate({ rootName, stackList }) {
+  const stack = stackList.length ? stackList.map((s) => `- ${s}`).join("\n") : "- (detected at generation time)";
+  return `
+# Architecture (${rootName})
+
+This file is a **human-owned** summary of the system architecture.
+
+## Stack (detected hints)
+
+${stack}
+
+## Key entry points
+
+- **Entrypoints**: list runtime entrypoints (server startup, CLI, workers)
+- **Core modules**: list the modules that hold the domain/business logic
+- **Data stores**: list databases/queues/caches used
+
+## Conventions
+
+- Note which directories are **source of truth** vs generated output.
+- Note how to run locally and how to deploy.
+`.trimStart();
+}
+
+export function apiFlowTemplate({ rootName }) {
+  return `
+# API flow (${rootName})
+
+Describe request flow(s) relevant to this repo.
+
+## Local flow
+
+\`\`\`text
+Client
+  ↓
+Local server / emulator
+  ↓
+Handlers / controllers
+  ↓
+DB / queues / external services
+\`\`\`
+
+## Deployed flow
+
+\`\`\`text
+Client
+  ↓
+Edge / gateway
+  ↓
+App services
+  ↓
+Data stores + integrations
+\`\`\`
+`.trimStart();
+}
+

package/src/lib/tree.mjs

@@ -0,0 +1,69 @@
+import path from "node:path";
+
+function extOf(relPath) {
+  return path.extname(relPath).toLowerCase();
+}
+
+function includeInTree(relPath, cfg) {
+  const base = path.basename(relPath).toLowerCase();
+  if (base === "dockerfile") return true;
+  const ext = extOf(relPath);
+  return (cfg.treeIncludeExtensions ?? []).includes(ext);
+}
+
+export function treeLines(filesRel, cfg) {
+  const files = filesRel.filter((f) => includeInTree(f, cfg)).sort();
+  const root = { dirs: new Map(), files: [] };
+
+  for (const f of files) {
+    const parts = f.split("/").filter(Boolean);
+    let cur = root;
+    for (let i = 0; i < parts.length; i++) {
+      const part = parts[i];
+      const isLeaf = i === parts.length - 1;
+      if (isLeaf) cur.files.push(part);
+      else {
+        if (!cur.dirs.has(part)) cur.dirs.set(part, { dirs: new Map(), files: [] });
+        cur = cur.dirs.get(part);
+      }
+    }
+  }
+
+  const maxDepth = cfg.maxTreeDepth ?? 6;
+  const maxFilesPerDir = cfg.maxFilesPerDir ?? 120;
+  const lines = [];
+
+  function rec(node, prefix, depth) {
+    if (depth > maxDepth) return;
+    const dirNames = [...node.dirs.keys()].sort();
+    const fileNames = [...node.files].sort();
+
+    const total = dirNames.length + fileNames.length;
+    let shown = 0;
+
+    for (const d of dirNames) {
+      shown++;
+      const isLast = shown === Math.min(total, maxFilesPerDir);
+      lines.push(`${prefix}${isLast ? "└── " : "├── "}${d}/`);
+      rec(node.dirs.get(d), `${prefix}${isLast ? "    " : "│   "}`, depth + 1);
+      if (shown >= maxFilesPerDir) break;
+    }
+
+    if (shown < maxFilesPerDir) {
+      for (const f of fileNames) {
+        shown++;
+        const isLast = shown === Math.min(total, maxFilesPerDir);
+        lines.push(`${prefix}${isLast ? "└── " : "├── "}${f}`);
+        if (shown >= maxFilesPerDir) break;
+      }
+    }
+
+    if (total > maxFilesPerDir) {
+      lines.push(`${prefix}└── … (${total - maxFilesPerDir} more items)`);
+    }
+  }
+
+  rec(root, "", 1);
+  return lines;
+}
+

package/src/lib/tree_sitter.mjs

@@ -0,0 +1,81 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+
+function ext(rel) {
+  return path.extname(rel).toLowerCase();
+}
+
+export function hasTreeSitter() {
+  const r = spawnSync("tree-sitter", ["--version"], { encoding: "utf8" });
+  return r.status === 0;
+}
+
+function shouldSymbolScan(rel, cfg) {
+  return (cfg.symbolExtensions ?? []).includes(ext(rel));
+}
+
+function runTags(rootDir, fileRel) {
+  const r = spawnSync("tree-sitter", ["tags", fileRel], {
+    cwd: rootDir,
+    encoding: "utf8",
+    maxBuffer: 20 * 1024 * 1024
+  });
+  if (r.status !== 0) return { ok: false, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+  return { ok: true, stdout: r.stdout ?? "" };
+}
+
+function parseCtags(stdout) {
+  const symbols = [];
+  const lines = stdout.split(/\r?\n/).filter(Boolean);
+  for (const line of lines) {
+    const parts = line.split("\t");
+    if (parts.length < 4) continue;
+    const [name, file, exCmd, kind, ...rest] = parts;
+    let lineNo = null;
+    const lineField = rest.find((r) => r.startsWith("line:"));
+    if (lineField) {
+      const n = Number(lineField.slice("line:".length));
+      if (Number.isFinite(n)) lineNo = n;
+    } else {
+      const m = exCmd.match(/(\d+)/);
+      if (m) {
+        const n = Number(m[1]);
+        if (Number.isFinite(n)) lineNo = n;
+      }
+    }
+    symbols.push({ name, file, kind, line: lineNo });
+  }
+  return symbols;
+}
+
+function groupByFile(symbols) {
+  const byFile = new Map();
+  for (const s of symbols) {
+    if (!byFile.has(s.file)) byFile.set(s.file, []);
+    byFile.get(s.file).push(s);
+  }
+  for (const [file, list] of byFile) {
+    list.sort((a, b) => `${a.kind}:${a.name}`.localeCompare(`${b.kind}:${b.name}`));
+    byFile.set(file, list);
+  }
+  return [...byFile.entries()].sort((a, b) => a[0].localeCompare(b[0]));
+}
+
+export function extractSymbols({ rootDir, filesRel, cfg }) {
+  if (!hasTreeSitter()) return { available: false, failures: 0, grouped: [] };
+  const symbols = [];
+  let failures = 0;
+
+  for (const f of filesRel) {
+    if (!shouldSymbolScan(f, cfg)) continue;
+    const r = runTags(rootDir, f);
+    if (!r.ok) {
+      failures++;
+      continue;
+    }
+    symbols.push(...parseCtags(r.stdout));
+  }
+
+  return { available: true, failures, grouped: groupByFile(symbols) };
+}
+