preflight-mcp 0.2.4 → 0.2.6

package/README.md

@@ -3,47 +3,81 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org/)
 [![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io/)
+[![npm version](https://img.shields.io/npm/v/preflight-mcp)](https://www.npmjs.com/package/preflight-mcp)
 
 > **English** | [中文](./README.zh-CN.md)
 
-An MCP (Model Context Protocol) **stdio** server that creates evidence-based preflight bundles for GitHub repositories and library documentation.
-
-Each bundle contains:
-- A local copy of repo docs + code (normalized text)
-- A lightweight **full-text search index** (SQLite FTS5)
-- Agent-facing entry files: `START_HERE.md`, `AGENTS.md`, and `OVERVIEW.md` (factual-only, with evidence pointers)
-
-## Features
-
-- **13 MCP tools** to create/update/repair/search/read bundles, generate evidence graphs, and manage trace links
-- **5 MCP prompts** for interactive guidance: menu, analyze guide, search guide, manage guide, trace guide
-- **LLM-friendly outputs**: After bundle creation, prompts user to generate dependency graph for deeper analysis
-- **Proactive trace links**: LLM automatically discovers and records code↔test, code↔doc relationships
-- **Auto-export trace.json**: Trace links are automatically exported to JSON for direct LLM reading (no API needed)
-- **Progress tracking**: Real-time progress reporting for long-running operations (create/update bundles)
-- **Bundle integrity check**: Prevents operations on incomplete bundles with helpful error messages
-- **De-duplication with in-progress lock**: Prevent duplicate bundle creation even during MCP timeouts
-- **Global dependency graph**: Generate project-wide import relationship graphs
-- **Batch file reading**: Read all key bundle files in a single call
-- **Resilient GitHub fetching**: configurable git clone timeout + GitHub archive (zipball) fallback
-- **Offline repair**: rebuild missing/empty derived artifacts (index/guides/overview) without re-fetching
-- **Static facts extraction** via `analysis/FACTS.json` (non-LLM)
-- **Resources** to read bundle files via `preflight://...` URIs
-- **Multi-path mirror backup** for cloud storage redundancy
-- **Resilient storage** with automatic failover when mounts are unavailable
-- **Atomic bundle creation** with crash-safety and zero orphans
-- **Fast background deletion** with 100-300x performance improvement
-- **Auto-cleanup** on startup for historical orphan bundles
+**Give your AI assistant deep knowledge of any codebase — in seconds.**
+
+Preflight-MCP creates searchable, indexed knowledge bundles from GitHub repos, so Claude/GPT/Cursor can understand your project structure, find relevant code, and trace dependencies — without copy-pasting or token limits.
+
+## Why Preflight?
+
+| Problem | Preflight Solution |
+|---------|--------------------|
+| 🤯 AI forgets your codebase context | Persistent, searchable bundles |
+| 📋 Copy-pasting code into chat | One command: `"index this repo"` |
+| 🔍 AI can't find related files | Full-text search + dependency graph |
+| 🧩 Lost in large projects | Auto-generated `START_HERE.md` & `OVERVIEW.md` |
+| 🔗 No idea what tests cover what | Trace links: code↔test↔doc |
+
+## Demo
+
+```
+You: "Create a bundle for the repository facebook/react"
+
+Preflight: ✅ Cloned, indexed 2,847 files, generated overview
+
+You: "Search for 'useState' implementation"
+
+Preflight: 📍 Found 23 matches:
+  → packages/react/src/ReactHooks.js:24
+  → packages/react-reconciler/src/ReactFiberHooks.js:1042
+  ...
+
+You: "Show me what tests cover useState"
+
+Preflight: 🔗 Trace links:
+  → ReactHooks.js tested_by ReactHooksTest.js
+  ...
+```
+
+## Core Features
+
+- 🚀 **One-command indexing** — `"index owner/repo"` creates a complete knowledge bundle
+- 🔍 **Full-text search** — SQLite FTS5 search across all code and docs
+- 🗺️ **Dependency graph** — Visualize imports and file relationships
+- 🔗 **Trace links** — Track code↔test↔doc relationships
+- 📖 **Auto-generated guides** — `START_HERE.md`, `AGENTS.md`, `OVERVIEW.md`
+- ☁️ **Cloud sync** — Multi-path mirror backup for redundancy
+- ⚡ **15 MCP tools + 5 prompts** — Complete toolkit for code exploration
+
+<details>
+<summary><b>All Features (click to expand)</b></summary>
+
+- **Progress tracking**: Real-time progress for long-running operations
+- **Bundle integrity check**: Prevents operations on incomplete bundles
+- **De-duplication**: Prevent duplicate bundle creation even during timeouts
+- **Resilient GitHub fetching**: Git clone timeout + archive fallback
+- **Offline repair**: Rebuild derived artifacts without re-fetching
+- **Static facts extraction**: `analysis/FACTS.json` (non-LLM)
+- **Resources**: Read bundle files via `preflight://...` URIs
+- **Atomic operations**: Crash-safety with zero orphans
+- **Fast deletion**: 100-300x performance improvement
+- **Auto-cleanup**: Removes orphan bundles on startup
+
+</details>
 
 ## Table of Contents
 
-- [Requirements](#requirements)
-- [Installation](#installation)
+- [Why Preflight?](#why-preflight)
+- [Demo](#demo)
+- [Core Features](#core-features)
 - [Quick Start](#quick-start)
-- [Tools](#tools-12-total)
+- [Tools](#tools-15-total)
+- [Prompts](#prompts-5-total)
 - [Environment Variables](#environment-variables)
 - [Contributing](#contributing)
-- [License](#license)
 
 ## Requirements
 
@@ -125,7 +159,7 @@ Run end-to-end smoke test:
 npm run smoke
 ```
 
-## Tools (13 total)
+## Tools (15 total)
 
 ### `preflight_list_bundles`
 List bundle IDs in storage.
@@ -156,10 +190,15 @@ Input (example):
 ### `preflight_read_file`
 Read file(s) from bundle. Two modes:
 - **Batch mode** (omit `file`): Returns ALL key files (OVERVIEW.md, START_HERE.md, AGENTS.md, manifest.json, deps/dependency-graph.json, repo READMEs) in one call
-- **Single file mode** (provide `file`): Returns that specific file (e.g., `deps/dependency-graph.json` for dependency graph)
+- **Single file mode** (provide `file`): Returns that specific file
+- **Evidence citation**: Use `withLineNumbers: true` to get `N|line` format; use `ranges: ["20-80"]` to read specific lines
 - Triggers: "查看bundle", "bundle概览", "项目信息", "show bundle", "读取依赖图"
-- Use `file: "manifest.json"` to get bundle metadata (repos, timestamps, tags, etc.)
-- Use `file: "deps/dependency-graph.json"` to read the dependency graph (generated by `preflight_evidence_dependency_graph`)
+
+### `preflight_repo_tree`
+Get repository structure overview without wasting tokens on search.
+- Returns: ASCII directory tree, file count by extension/directory, entry point candidates
+- Use BEFORE deep analysis to understand project layout
+- Triggers: "show project structure", "what files are in this repo", "项目结构", "文件分布"
 
 ### `preflight_delete_bundle`
 Delete/remove a bundle permanently.
@@ -216,9 +255,14 @@ Create or update traceability links (code↔test, code↔doc, file↔requirement
 ### `preflight_trace_query`
 Query traceability links (code↔test, code↔doc, commit↔ticket).
 - **Proactive use**: LLM automatically queries trace links when analyzing specific files
-- Helps answer: "Does this code have tests?", "What requirements does this implement?"
+- Returns `reason` and `nextSteps` when no edges found (helps LLM decide next action)
 - Fast when `bundleId` is provided; can scan across bundles when omitted.
 
+### `preflight_trace_export`
+Export trace links to `trace/trace.json` for direct LLM reading.
+- Note: Auto-exported after each `trace_upsert`, so only needed to manually refresh
+- Triggers: "export trace", "refresh trace.json", "导出trace"
+
 ### `preflight_cleanup_orphans`
 Remove incomplete or corrupted bundles (bundles without valid manifest.json).
 - Triggers: "clean up broken bundles", "remove orphans", "清理孤儿bundle"

package/README.zh-CN.md

@@ -3,41 +3,81 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org/)
 [![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io/)
+[![npm version](https://img.shields.io/npm/v/preflight-mcp)](https://www.npmjs.com/package/preflight-mcp)
 
 > [English](./README.md) | **中文**
 
-一个 MCP (Model Context Protocol) **stdio** 服务器，用于为 GitHub 仓库与库文档生成"基于证据"的 preflight bundles。
-
-每个 bundle 包含：
-- 仓库文档 + 代码的本地副本（规范化文本）
-- 轻量级 **全文搜索索引**（SQLite FTS5）
-- 面向 Agent 的入口文件：`START_HERE.md`、`AGENTS.md`、`OVERVIEW.md`（仅事实，带证据指针）
-
-## Features
-
-- **13 个 MCP 工具**：create/update/repair/search/evidence/trace/read/cleanup（外加 resources）
-- **5 个 MCP prompts**：交互式引导（菜单、分析指南、搜索指南、管理指南、追溯指南）
-- **去重**：避免对相同的规范化输入重复索引
-- **可靠的 GitHub 获取**：可配置 git clone 超时 + GitHub archive（zipball）兜底
-- **离线修复**：无需重新抓取，重建缺失/为空的派生物（index/guides/overview）
-- **静态事实提取**：生成 `analysis/FACTS.json`（非 LLM）
-- **Resources**：通过 `preflight://...` URI 读取 bundle 文件
-- **多路径镜像备份**：云存储冗余
-- **弹性存储**：挂载点不可用时自动故障转移
-- **原子创建 + 零孤儿**：临时目录 + 原子重命名，崩溃安全
-- **后台快速删除**：<100ms 响应，实际删除在后台进行
-- **启动自动清理**：历史孤儿目录自动清理（非阻塞）
-
-## Table of Contents
-
-- [Requirements](#requirements)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Architecture](#architecture)
-- [Tools](#tools-12-total)
-- [Environment Variables](#environment-variables)
-- [Contributing](#contributing)
-- [License](#license)
+**让你的 AI 助手秒懂任何代码仓库。**
+
+Preflight-MCP 为 GitHub 仓库创建可搜索的知识库，让 Claude/GPT/Cursor 理解你的项目结构、快速定位代码、追踪依赖关系 —— 无需复制粘贴，不受 token 限制。
+
+## 为什么需要 Preflight？
+
+| 痛点 | Preflight 解决方案 |
+|------|--------------------|
+| 🤯 AI 记不住你的代码库 | 持久化、可搜索的知识包 |
+| 📋 反复复制粘贴代码 | 一句话：「索引这个仓库」 |
+| 🔍 AI 找不到相关文件 | 全文搜索 + 依赖图 |
+| 🧩 大项目里迷失方向 | 自动生成 `START_HERE.md` 和 `OVERVIEW.md` |
+| 🔗 不知道哪些测试覆盖哪些代码 | 追溯链接：代码↔测试↔文档 |
+
+## 效果演示
+
+```
+你：「为 facebook/react 创建 bundle」
+
+Preflight：✅ 已克隆，索引了 2,847 个文件，生成概览完成
+
+你：「搜索 useState 的实现」
+
+Preflight：📍 找到 23 处匹配：
+  → packages/react/src/ReactHooks.js:24
+  → packages/react-reconciler/src/ReactFiberHooks.js:1042
+  ...
+
+你：「哪些测试覆盖了 useState」
+
+Preflight：🔗 追溯链接：
+  → ReactHooks.js tested_by ReactHooksTest.js
+  ...
+```
+
+## 核心功能
+
+- 🚀 **一句话索引** — 「索引 owner/repo」即可创建完整知识包
+- 🔍 **全文搜索** — SQLite FTS5 搜索全部代码和文档
+- 🗺️ **依赖图** — 可视化 import 关系和文件依赖
+- 🔗 **追溯链接** — 追踪代码↔测试↔文档关系
+- 📖 **自动生成指南** — `START_HERE.md`、`AGENTS.md`、`OVERVIEW.md`
+- ☁️ **云端同步** — 多路径镜像备份
+- ⚡ **15 个 MCP 工具 + 5 个 prompts** — 完整的代码探索工具集
+
+<details>
+<summary><b>全部功能（点击展开）</b></summary>
+
+- **进度追踪**：长时间操作的实时进度显示
+- **Bundle 完整性检查**：防止对不完整 bundle 进行操作
+- **去重机制**：即使超时也能防止重复创建
+- **可靠的 GitHub 抓取**：git clone 超时 + archive 兜底
+- **离线修复**：无需重新抓取即可重建派生文件
+- **静态事实提取**：`analysis/FACTS.json`（非 LLM）
+- **Resources**：通过 `preflight://...` URI 读取文件
+- **原子操作**：崩溃安全，零孤儿目录
+- **快速删除**：100-300 倍性能提升
+- **自动清理**：启动时自动清理孤儿 bundle
+
+</details>
+
+## 目录
+
+- [为什么需要 Preflight](#为什么需要-preflight)
+- [效果演示](#效果演示)
+- [核心功能](#核心功能)
+- [快速开始](#quick-start)
+- [工具](#tools-15-total)
+- [Prompts](#prompts-5-total)
+- [环境变量](#environment-variables)
+- [贡献指南](#contributing)
 
 ## Requirements
 
@@ -140,7 +180,7 @@ npm run smoke
 - 列表与清理逻辑只接受 UUID v4 作为 bundleId
 - 会自动过滤 `#recycle`、`tmp`、`.deleting` 等非 bundle 目录
 
-## Tools (12 total)
+## Tools (15 total)
 
 ### `preflight_list_bundles`
 列出所有 bundle。
@@ -170,11 +210,16 @@ npm run smoke
 
 ### `preflight_read_file`
 从 bundle 读取文件。两种模式：
-- **批量模式**（省略 `file`）：返回所有关键文件（OVERVIEW.md、START_HERE.md、AGENTS.md、manifest.json、deps/dependency-graph.json、repo READMEs）
-- **单文件模式**（提供 `file`）：返回指定文件（如 `deps/dependency-graph.json` 获取依赖图）
+- **批量模式**（省略 `file`）：返回所有关键文件
+- **单文件模式**（提供 `file`）：返回指定文件
+- **证据引用**：使用 `withLineNumbers: true` 获取 `N|行` 格式；使用 `ranges: ["20-80"]` 读取指定行
 - 触发词：「查看概览」「项目概览」「bundle详情」「读取依赖图」
-- 使用 `file: "manifest.json"` 获取 bundle 元数据
-- 使用 `file: "deps/dependency-graph.json"` 读取依赖图（由 `preflight_evidence_dependency_graph` 生成）
+
+### `preflight_repo_tree`
+获取仓库结构概览，避免浪费 token 搜索。
+- 返回：ASCII 目录树、按扩展名/目录统计文件数、入口点候选
+- 在深入分析前使用，了解项目布局
+- 触发词：「项目结构」「文件分布」「show tree」
 
 ### `preflight_delete_bundle`
 永久删除/移除一个 bundle。
@@ -225,7 +270,14 @@ npm run smoke
 写入/更新 bundle 级 traceability links（commit↔ticket、symbol↔test、code↔doc 等）。
 
 ### `preflight_trace_query`
-查询 traceability links（提供 `bundleId` 时更快；省略时可跨 bundle 扫描，带上限）。
+查询 traceability links。
+- 无匹配边时返回 `reason` 和 `nextSteps`（帮助 LLM 决定下一步）
+- 提供 `bundleId` 时更快；省略时可跨 bundle 扫描
+
+### `preflight_trace_export`
+导出 trace links 到 `trace/trace.json`。
+- 注意：每次 `trace_upsert` 后会自动导出，此工具仅用于手动刷新
+- 触发词：「导出trace」「刷新trace.json」
 
 ### `preflight_cleanup_orphans`
 删除不完整或损坏的 bundle（缺少有效 manifest.json）。

package/dist/bundle/tree.js

@@ -0,0 +1,224 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+const ENTRY_POINT_PATTERNS = [
+    { pattern: /^readme\.md$/i, type: 'readme', priority: 100 },
+    { pattern: /^readme$/i, type: 'readme', priority: 95 },
+    { pattern: /^index\.(ts|js|tsx|jsx|py|go|rs)$/i, type: 'index', priority: 90 },
+    { pattern: /^main\.(ts|js|tsx|jsx|py|go|rs)$/i, type: 'main', priority: 85 },
+    { pattern: /^app\.(ts|js|tsx|jsx|py)$/i, type: 'app', priority: 80 },
+    { pattern: /^server\.(ts|js|tsx|jsx|py|go)$/i, type: 'server', priority: 75 },
+    { pattern: /^cli\.(ts|js|py)$/i, type: 'cli', priority: 70 },
+    { pattern: /^__init__\.py$/i, type: 'index', priority: 60 },
+    { pattern: /^mod\.rs$/i, type: 'index', priority: 60 },
+    { pattern: /^lib\.rs$/i, type: 'main', priority: 85 },
+    { pattern: /^package\.json$/i, type: 'config', priority: 50 },
+    { pattern: /^pyproject\.toml$/i, type: 'config', priority: 50 },
+    { pattern: /^cargo\.toml$/i, type: 'config', priority: 50 },
+    { pattern: /^go\.mod$/i, type: 'config', priority: 50 },
+    { pattern: /\.test\.(ts|js|tsx|jsx)$/i, type: 'test', priority: 30 },
+    { pattern: /_test\.(py|go)$/i, type: 'test', priority: 30 },
+    { pattern: /^test_.*\.py$/i, type: 'test', priority: 30 },
+];
+function matchesGlob(filename, patterns) {
+    if (patterns.length === 0)
+        return true;
+    for (const pattern of patterns) {
+        // Simple glob matching: * matches any sequence, ** matches any path
+        const regexPattern = pattern
+            .replace(/\./g, '\\.')
+            .replace(/\*\*/g, '.*')
+            .replace(/\*/g, '[^/]*');
+        const regex = new RegExp(`^${regexPattern}$`, 'i');
+        if (regex.test(filename))
+            return true;
+    }
+    return false;
+}
+function shouldExclude(relativePath, excludePatterns) {
+    if (excludePatterns.length === 0)
+        return false;
+    for (const pattern of excludePatterns) {
+        // Simple exclusion matching
+        if (relativePath.includes(pattern))
+            return true;
+        if (pattern.startsWith('*') && relativePath.endsWith(pattern.slice(1)))
+            return true;
+    }
+    return false;
+}
+export async function generateRepoTree(bundleRootDir, bundleId, options = {}) {
+    const depth = options.depth ?? 4;
+    const includePatterns = options.include ?? [];
+    const excludePatterns = options.exclude ?? ['node_modules', '.git', '__pycache__', '.venv', 'venv', 'dist', 'build', '*.pyc'];
+    const reposDir = path.join(bundleRootDir, 'repos');
+    const stats = {
+        totalFiles: 0,
+        totalDirs: 0,
+        byExtension: {},
+        byTopDir: {},
+    };
+    const entryPointCandidates = [];
+    // Build tree recursively
+    async function buildTree(dir, currentDepth, relativePath) {
+        if (currentDepth > depth)
+            return null;
+        try {
+            const stat = await fs.stat(dir);
+            const name = path.basename(dir);
+            if (stat.isFile()) {
+                // Check include/exclude patterns
+                if (includePatterns.length > 0 && !matchesGlob(name, includePatterns)) {
+                    return null;
+                }
+                if (shouldExclude(relativePath, excludePatterns)) {
+                    return null;
+                }
+                stats.totalFiles++;
+                // Track extension stats
+                const ext = path.extname(name).toLowerCase() || '(no ext)';
+                stats.byExtension[ext] = (stats.byExtension[ext] ?? 0) + 1;
+                // Track top directory stats
+                const topDir = relativePath.split('/')[0] ?? '(root)';
+                stats.byTopDir[topDir] = (stats.byTopDir[topDir] ?? 0) + 1;
+                // Check for entry point candidates
+                for (const ep of ENTRY_POINT_PATTERNS) {
+                    if (ep.pattern.test(name)) {
+                        entryPointCandidates.push({
+                            path: relativePath,
+                            type: ep.type,
+                            priority: ep.priority,
+                        });
+                        break;
+                    }
+                }
+                return { name, type: 'file', size: stat.size };
+            }
+            if (stat.isDirectory()) {
+                // Check exclude patterns for directories
+                if (shouldExclude(name, excludePatterns) || shouldExclude(relativePath, excludePatterns)) {
+                    return null;
+                }
+                stats.totalDirs++;
+                const entries = await fs.readdir(dir, { withFileTypes: true });
+                const children = [];
+                // Sort: directories first, then files, alphabetically
+                const sortedEntries = entries.sort((a, b) => {
+                    if (a.isDirectory() && !b.isDirectory())
+                        return -1;
+                    if (!a.isDirectory() && b.isDirectory())
+                        return 1;
+                    return a.name.localeCompare(b.name);
+                });
+                for (const entry of sortedEntries) {
+                    const childPath = path.join(dir, entry.name);
+                    const childRelPath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+                    const childNode = await buildTree(childPath, currentDepth + 1, childRelPath);
+                    if (childNode) {
+                        children.push(childNode);
+                    }
+                }
+                return { name, type: 'dir', children: children.length > 0 ? children : undefined };
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    // Build tree starting from repos directory
+    let rootNode = null;
+    try {
+        await fs.access(reposDir);
+        rootNode = await buildTree(reposDir, 0, '');
+    }
+    catch {
+        // repos directory doesn't exist, try bundle root
+        rootNode = await buildTree(bundleRootDir, 0, '');
+    }
+    // Generate ASCII tree
+    function renderTree(node, prefix = '', isLast = true) {
+        const lines = [];
+        const connector = isLast ? '└── ' : '├── ';
+        const extension = isLast ? '    ' : '│   ';
+        lines.push(`${prefix}${connector}${node.name}${node.type === 'dir' ? '/' : ''}`);
+        if (node.children) {
+            const childCount = node.children.length;
+            node.children.forEach((child, index) => {
+                const childLines = renderTree(child, prefix + extension, index === childCount - 1);
+                lines.push(...childLines);
+            });
+        }
+        return lines;
+    }
+    let treeText = '';
+    if (rootNode) {
+        if (rootNode.children && rootNode.children.length > 0) {
+            treeText = `${rootNode.name}/\n`;
+            rootNode.children.forEach((child, index) => {
+                const childLines = renderTree(child, '', index === rootNode.children.length - 1);
+                treeText += childLines.join('\n') + '\n';
+            });
+        }
+        else {
+            treeText = `${rootNode.name}/ (empty or filtered out)`;
+        }
+    }
+    else {
+        treeText = '(no files found)';
+    }
+    // Sort entry point candidates by priority
+    entryPointCandidates.sort((a, b) => b.priority - a.priority);
+    return {
+        bundleId,
+        tree: treeText.trim(),
+        stats,
+        entryPointCandidates: entryPointCandidates.slice(0, 20), // Limit to top 20
+    };
+}
+/**
+ * Format tree result as human-readable text
+ */
+export function formatTreeResult(result) {
+    const lines = [];
+    lines.push(`📂 Repository Structure for bundle: ${result.bundleId}`);
+    lines.push('');
+    lines.push('## Directory Tree');
+    lines.push('```');
+    lines.push(result.tree);
+    lines.push('```');
+    lines.push('');
+    lines.push('## Statistics');
+    lines.push(`- Total files: ${result.stats.totalFiles}`);
+    lines.push(`- Total directories: ${result.stats.totalDirs}`);
+    lines.push('');
+    // By extension (top 10)
+    const extEntries = Object.entries(result.stats.byExtension)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 10);
+    if (extEntries.length > 0) {
+        lines.push('### Files by Extension');
+        for (const [ext, count] of extEntries) {
+            lines.push(`- ${ext}: ${count}`);
+        }
+        lines.push('');
+    }
+    // By top directory (top 10)
+    const dirEntries = Object.entries(result.stats.byTopDir)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 10);
+    if (dirEntries.length > 0) {
+        lines.push('### Files by Top Directory');
+        for (const [dir, count] of dirEntries) {
+            lines.push(`- ${dir}: ${count}`);
+        }
+        lines.push('');
+    }
+    // Entry point candidates
+    if (result.entryPointCandidates.length > 0) {
+        lines.push('## Entry Point Candidates');
+        for (const ep of result.entryPointCandidates.slice(0, 10)) {
+            lines.push(`- \`${ep.path}\` (${ep.type})`);
+        }
+    }
+    return lines.join('\n');
+}