{ "canonical_name": "engincankaya/blueprint", "compilation_id": "pack_f8aba7817d9f438eb7413133684c5545", "created_at": "2026-05-19T06:12:30.376481+00:00", "created_by": "project-pack-compiler", "feedback": { "carrier_selection_notes": [ "viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight", "recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight" ], "evidence_delta": { "confirmed_claims": [ "identity_anchor_present", "capability_and_host_targets_present", "install_path_declared_or_better" ], "missing_required_fields": [], "must_verify_forwarded": [ "Run or inspect `npm install -g blueprint-mcp-server` in an isolated environment.", "Confirm the project exposes the claimed capability to at least one target host." ], "quickstart_execution_scope": "allowlisted_sandbox_smoke", "sandbox_command": "npm install -g blueprint-mcp-server", "sandbox_container_image": "node:22-slim", "sandbox_execution_backend": "docker", "sandbox_planner_decision": "deterministic_isolated_install", "sandbox_validation_id": "sbx_2094a717bc024f129c8c73748dfd8205" }, "feedback_event_type": "project_pack_compilation_feedback", "learning_candidate_reasons": [], "template_gaps": [] }, "identity": { "canonical_id": "project_bf3898a54057c34e20ae6cfd178fe6ea", "canonical_name": "engincankaya/blueprint", "homepage_url": null, "license": "unknown", "repo_url": "https://github.com/engincankaya/blueprint", "slug": "blueprint", "source_packet_id": "phit_d73202cfc25047898b838b67a189843c", "source_validation_id": "dval_b24e4e869d9c46e0b432673d5547fcbd" }, "merchandising": { "best_for": "需要软件开发与交付能力，并使用 mcp_host的用户", "github_forks": 0, "github_stars": 0, "one_liner_en": "Architecture-aware MCP server that analyzes codebases with Tree-sitter and generates Blueprint memory for LLM coding agents.", "one_liner_zh": "Architecture-aware MCP server that analyzes codebases with Tree-sitter and generates Blueprint memory for LLM coding agents.", "primary_category": { "category_id": "software-development", "confidence": "high", "name_en": "Software Development", "name_zh": "软件开发与交付", "reason": "matched_keywords:code, coding, git" }, "target_user": "使用 mcp_host 等宿主 AI 的用户", "title_en": "blueprint", "title_zh": "blueprint 能力包", "visible_tags": [ { "label_en": "Browser Agents", "label_zh": "浏览器 Agent", "source": "repo_evidence_project_characteristics", "tag_id": "product_domain-browser-agents", "type": "product_domain" }, { "label_en": "Web Task Automation", "label_zh": "网页任务自动化", "source": "repo_evidence_project_characteristics", "tag_id": "user_job-web-task-automation", "type": "user_job" }, { "label_en": "Browser Automation", "label_zh": "浏览器自动化", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-browser-automation", "type": "core_capability" }, { "label_en": "Node-based Workflow", "label_zh": "节点式流程编排", "source": "repo_evidence_project_characteristics", "tag_id": "workflow_pattern-node-based-workflow", "type": "workflow_pattern" }, { "label_en": "Evaluation Suite", "label_zh": "评测体系", "source": "repo_evidence_project_characteristics", "tag_id": "selection_signal-evaluation-suite", "type": "selection_signal" } ] }, "packet_id": "phit_d73202cfc25047898b838b67a189843c", "page_model": { "artifacts": { "artifact_slug": "blueprint", "files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json", "REPO_INSPECTION.md", "CAPABILITY_CONTRACT.json", "EVIDENCE_INDEX.json", "CLAIM_GRAPH.json" ], "required_files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json" ] }, "detail": { "capability_source": "Project Hit Packet + DownstreamValidationResult", "commands": [ { "command": "npm install -g blueprint-mcp-server", "label": "Node.js / npm · 官方安装入口", "source": "https://github.com/engincankaya/blueprint#readme", "verified": true } ], "display_tags": [ "浏览器 Agent", "网页任务自动化", "浏览器自动化", "节点式流程编排", "评测体系" ], "eyebrow": "软件开发与交付", "glance": [ { "body": "判断自己是不是目标用户。", "label": "最适合谁", "value": "需要软件开发与交付能力，并使用 mcp_host的用户" }, { "body": "先理解能力边界，再决定是否继续。", "label": "核心价值", "value": "Architecture-aware MCP server that analyzes codebases with Tree-sitter and generates Blueprint memory for LLM coding agents." }, { "body": "未完成验证前保持审慎。", "label": "继续前", "value": "publish to Doramagic.ai project surfaces" } ], "guardrail_source": "Boundary & Risk Card", "guardrails": [ { "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。", "label": "Check 1", "value": "不要把试用当真实运行" }, { "body": "mcp_host", "label": "Check 2", "value": "确认宿主兼容" }, { "body": "publish to Doramagic.ai project surfaces", "label": "Check 3", "value": "先隔离验证" } ], "mode": "mcp_config, recipe, host_instruction, eval, preflight", "pitfall_log": { "items": [ { "body": "README/documentation is current enough for a first validation pass.", "category": "能力坑", "evidence": [ "capability.assumptions | github_repo:1230090802 | https://github.com/engincankaya/blueprint | README/documentation is current enough for a first validation pass." ], "severity": "medium", "suggested_check": "将假设转成下游验证清单。", "title": "能力判断依赖假设", "user_impact": "假设不成立时，用户拿不到承诺的能力。" }, { "body": "未记录 last_activity_observed。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:1230090802 | https://github.com/engincankaya/blueprint | last_activity_observed missing" ], "severity": "medium", "suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。", "title": "维护活跃度未知", "user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "downstream_validation.risk_items | github_repo:1230090802 | https://github.com/engincankaya/blueprint | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "进入安全/权限治理复核队列。", "title": "下游验证发现风险项", "user_impact": "下游已经要求复核，不能在页面中弱化。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "risks.scoring_risks | github_repo:1230090802 | https://github.com/engincankaya/blueprint | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。", "title": "存在评分风险", "user_impact": "风险会影响是否适合普通用户安装。" }, { "body": "issue_or_pr_quality=unknown。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:1230090802 | https://github.com/engincankaya/blueprint | issue_or_pr_quality=unknown" ], "severity": "low", "suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。", "title": "issue/PR 响应质量未知", "user_impact": "用户无法判断遇到问题后是否有人维护。" }, { "body": "release_recency=unknown。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:1230090802 | https://github.com/engincankaya/blueprint | release_recency=unknown" ], "severity": "low", "suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。", "title": "发布节奏不明确", "user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。" } ], "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals", "summary": "发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。", "title": "踩坑日志" }, "snapshot": { "contributors": 1, "forks": 0, "license": "unknown", "note": "站点快照，非实时质量证明；用于开工前背景判断。", "stars": 0 }, "source_url": "https://github.com/engincankaya/blueprint", "steps": [ { "body": "不安装项目，先体验能力节奏。", "code": "preview", "title": "先试 Prompt" }, { "body": "理解输入、输出、失败模式和边界。", "code": "manual", "title": "读说明书" }, { "body": "把上下文交给宿主 AI 继续工作。", "code": "context", "title": "带给 AI" }, { "body": "进入主力环境前先完成安装入口与风险边界验证。", "code": "verify", "title": "沙箱验证" } ], "subtitle": "Architecture-aware MCP server that analyzes codebases with Tree-sitter and generates Blueprint memory for LLM coding agents.", "title": "blueprint 能力包", "trial_prompt": "# blueprint - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for engincankaya/blueprint.\n\nProject:\n- Name: blueprint\n- Repository: https://github.com/engincankaya/blueprint\n- Summary: Architecture-aware MCP server that analyzes codebases with Tree-sitter and generates Blueprint memory for LLM coding agents.\n- Host target: mcp_host\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Architecture-aware MCP server that analyzes codebases with Tree-sitter and generates Blueprint memory for LLM coding agents.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Architecture-aware MCP server that analyzes codebases with Tree-sitter and generates Blueprint memory for LLM coding agents.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. page-blueprint-introduction: Blueprint Introduction. Produce one small intermediate artifact and wait for confirmation.\n2. page-cli-usage: CLI and Command Usage. Produce one small intermediate artifact and wait for confirmation.\n3. page-system-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. page-mcp-server: MCP Server Implementation. Produce one small intermediate artifact and wait for confirmation.\n5. page-scan-tool: Scan Tool. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/engincankaya/blueprint\n- https://github.com/engincankaya/blueprint#readme\n- README.md\n- AGENTS.md\n- docs/agents.md\n- src/cli/index.ts\n- package.json\n- src/tools/scan/index.ts\n- src/tools/group/index.ts\n- src/tools/compose/index.ts\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n", "voices": [ { "body": "当前没有项目级社区来源；不会把未抓取讨论包装成社会证明。", "items": [], "status": "待发现 Agent 补证", "title": "社区讨论" } ] }, "homepage_card": { "category": "软件开发与交付", "desc": "Architecture-aware MCP server that analyzes codebases with Tree-sitter and generates Blueprint memory for LLM coding agents.", "effort": "安装已验证", "forks": 0, "icon": "code", "name": "blueprint 能力包", "risk": "需复核", "slug": "blueprint", "stars": 0, "tags": [ "浏览器 Agent", "网页任务自动化", "浏览器自动化", "节点式流程编排", "评测体系" ], "thumb": "gray", "type": "MCP 配置" }, "manual": { "markdown": "# https://github.com/engincankaya/blueprint 项目说明书\n\n生成时间：2026-05-16 00:06:34 UTC\n\n## 目录\n\n- [Blueprint Introduction](#page-blueprint-introduction)\n- [CLI and Command Usage](#page-cli-usage)\n- [System Architecture](#page-system-architecture)\n- [MCP Server Implementation](#page-mcp-server)\n- [Scan Tool](#page-scan-tool)\n- [Group Tool](#page-group-tool)\n- [Compose Tool](#page-compose-tool)\n- [Refresh Tool](#page-refresh-tool)\n- [Task Context Tool](#page-task-context-tool)\n- [Viewer Frontend](#page-viewer-frontend)\n\n\n\n## Blueprint Introduction\n\n### 相关页面\n\n相关主题：[CLI and Command Usage](#page-cli-usage), [System Architecture](#page-system-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/engincankaya/blueprint/blob/main/README.md)\n- [AGENTS.md](https://github.com/engincankaya/blueprint/blob/main/AGENTS.md)\n- [src/lib/agent-instructions.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/agent-instructions.ts)\n- [src/tools/scan/scan-file-inventory-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-file-inventory-builder.ts)\n- [src/tools/scan/scan-code-analysis-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-code-analysis-engine.ts)\n
\n\n# Blueprint Introduction\n\nBlueprint is a local architecture memory system designed to help developers and AI agents understand, navigate, and work effectively with software projects. It generates structured project graphs from source code, enabling faster orientation and more accurate context when making changes.\n\n## Overview\n\nBlueprint solves the common problem of diving into unfamiliar or complex codebases by creating a persistent, queryable layer of architectural knowledge. Rather than reading through thousands of files to understand a system, developers can leverage Blueprint's structured output to quickly identify relevant components, dependencies, and architectural patterns.\n\n### Core Purpose\n\nThe primary goals of Blueprint are:\n\n1. **Structured Project Graph Generation** - Automatically analyze codebase structure and generate organized representations of files, symbols, imports, and dependencies\n2. **Architectural Memory Persistence** - Store architecture knowledge in a local `.blueprint/` directory that can be version-controlled or kept as local developer memory\n3. **Agent-Friendly Orientation** - Provide AI agents with reliable starting points for understanding projects before diving into source code\n4. **Deterministic Maintenance** - Keep architecture documentation synchronized with actual code through automated refresh workflows\n\n资料来源：[README.md:1-20]()\n\n## Architecture\n\n### System Components\n\nBlueprint consists of several integrated components that work together to analyze and document projects:\n\n| Component | Purpose |\n|-----------|---------|\n| **Scan Engine** | Builds file inventory and performs code analysis |\n| **Group Module** | Organizes files into semantic architectural groups |\n| **Compose Module** | Generates final Blueprint output and Markdown documentation |\n| **Viewer** | React-based UI for visualizing project architecture |\n| **MCP Server** | Model Context Protocol integration for AI agent workflows |\n\n资料来源：[README.md:40-60]()\n\n### File Inventory System\n\nThe scan engine analyzes the codebase using a categorization system that classifies files into meaningful types:\n\n```mermaid\ngraph TD\n A[File System] --> B[Scan Engine]\n B --> C{File Type Detection}\n C -->|Source Code| D[parseable]\n C -->|Config| E[config]\n C -->|Documentation| F[documentation]\n C -->|Test| G[test]\n C -->|Asset| H[asset]\n C -->|Lockfile| I[lockfile]\n C -->|Script| J[script]\n```\n\nThe categorization logic uses path segment analysis and file extension matching:\n\n```typescript\n// From src/tools/scan/scan-file-inventory-builder.ts\nif (segments.includes(\"test\") || segments.includes(\"tests\")) {\n return \"test\";\n}\nif (base.endsWith(\".md\") || language === \"markdown\") {\n return \"documentation\";\n}\nif (segments.includes(\"assets\") || [\"html\", \"css\", \"svg\"].includes(language)) {\n return \"asset\";\n}\n```\n\n资料来源：[src/tools/scan/scan-file-inventory-builder.ts:1-50]()\n\n### Code Analysis Engine\n\nThe analysis engine performs deep parsing on supported languages to extract symbols, imports, and exports:\n\n```typescript\n// From src/tools/scan/scan-code-analysis-engine.ts\ninterface AnalysisFacts {\n inventoryArtifactId: string;\n rootPath: string;\n files: Record;\n symbols: Record;\n imports: Import[];\n exports: Export[];\n dependencies: Dependency[];\n parseErrors: ParseError[];\n}\n```\n\nThe engine tracks validation state to ensure complete analysis:\n\n```typescript\ninterface Validation {\n isComplete: boolean;\n inventoryFiles: number;\n parseableFiles: number;\n parsedFiles: number;\n parseErrors: number;\n unaccountedFiles: string[];\n}\n```\n\n资料来源：[src/tools/scan/scan-code-analysis-engine.ts:1-80]()\n\n## Project Memory Structure\n\nBlueprint stores architecture memory in a `.blueprint/` directory with the following structure:\n\n### Generated Artifacts\n\n| File | Purpose |\n|------|---------|\n| `brief.md` | Project overview, architectural groups, and routing hints |\n| `groups/*.md` | Detailed documentation for each architectural group |\n| `blueprint-output.json` | Structured project graph in JSON format |\n| `refresh-scan.json` | Filesystem hash snapshot for deterministic refreshes |\n\n资料来源：[README.md:25-35]()\n\n### Group Documentation Template\n\nEach group document follows a consistent structure:\n\n- **Snapshot** - Quick orientation and high-level description\n- **Responsibilities** - Ownership boundaries and out-of-scope areas\n- **Core Flow** - Runtime behavior and data flow explanation\n- **Contracts & Invariants** - Behavior that must not be broken\n- **Key Files** - Main source files for the group\n- **Change Guide** - Files or contracts that should change together\n- **Pitfalls** - Known risks and common mistakes\n- **Tests** - Most relevant verification points\n- **Debugging** - Failure-mode hints\n- **Extension / Open Questions** - Uncertainty and known gaps\n\n资料来源：[AGENTS.md:40-65]()\n\n## Workflows\n\n### Initial Setup Workflow\n\n```mermaid\ngraph LR\n A[blueprint scan] --> B[blueprint group mode: prepare]\n B --> C[Create grouping plan]\n C --> D[blueprint group mode: apply]\n D --> E[blueprint compose]\n E --> F[.blueprint/ memory created]\n F --> G[AGENTS.md patched]\n```\n\nTo initialize Blueprint for a project:\n\n1. Run `blueprint.scan` to build file inventory and code analysis\n2. Run `blueprint.group` with `mode: \"prepare\"` to analyze grouping options\n3. Create a compact grouping plan from the prepare output\n4. Run `blueprint.group` with `mode: \"apply\"` to apply the grouping\n5. Run `blueprint.compose` to write the final Blueprint output\n\n资料来源：[README.md:55-75]()\n\n### Maintenance Workflow\n\nWhen project changes add, move, delete, or substantially change files:\n\n```mermaid\ngraph TD\n A[Code Changes] --> B[Run blueprint.refresh]\n B --> C{New files unassigned?}\n C -->|Yes| D[Run blueprint.group.update]\n C -->|No| E[Update affected group docs]\n D --> E\n E --> F[Architecture docs synchronized]\n```\n\n资料来源：[README.md:75-85]()\n\n## Blueprint Viewer\n\nBlueprint includes a lightweight React/Vite viewer for visualizing project architecture.\n\n### Viewing Generated Blueprint\n\nTo view a generated Blueprint:\n\n```bash\nblueprint open\n```\n\nThis command:\n1. Reads `.blueprint/blueprint-output.json` and `.blueprint/groups/*.md`\n2. Writes a self-contained `.blueprint/index.html`\n3. Opens it in the default browser\n\n### Static Viewer Features\n\nThe viewer generates self-contained HTML with:\n- Inline JavaScript\n- Inline CSS\n- Securely embedded JSON data\n\n```mermaid\ngraph TD\n A[Blueprint Data] --> B[XSS/Content Escape]\n B --> C[` closing tag injection risks.\n\n资料来源：[todos_120526.md:12-15]()\n\n## Agent Integration\n\nBlueprint CLI integrates with AI agents through `AGENTS.md` files that contain marker-based patches. The system uses stable section headings for navigation:\n\n- `Core Flow`\n- `Contracts & Invariants`\n- `Change Guide`\n- `Pitfalls`\n- `Tests`\n\n资料来源：[AGENTS.md:4-10]()\n\n### Agent Budget Guidelines\n\nWhen working with Blueprint in agentic contexts:\n\n| Resource | Budget Policy |\n| --- | --- |\n| `.blueprint/brief.md` | Always read |\n| Blueprint Markdown search | Always prefer early |\n| Group docs | Read targeted excerpts first |\n| Full group docs | Exception, not default |\n\n资料来源：[AGENTS.md:1-7]()\n\n## Development Commands\n\nFor developers working on Blueprint itself:\n\n```bash\nnpm install # Install dependencies\nnpm run build # Build the project\nnpm run lint # Run linter\nnpm test # Run tests\n```\n\n资料来源：[README.md:75-80]()\n\n## Command Output Structure\n\nBlueprint generates structured output files in the `.blueprint/` directory:\n\n| File | Purpose |\n| --- | --- |\n| `brief.md` | Project overview and key architectural decisions |\n| `blueprint-output.json` | Structured project graph |\n| `groups/*.md` | Individual group documentation |\n| `file-inventory.json` | Complete file listing |\n| `refresh-scan.json` | Filesystem state snapshot |\n\n资料来源：[README.md:49-53]()\n\n## Language Support\n\nThe CLI uses Tree-sitter for deep code analysis of supported languages:\n\n| Language | Support Level |\n| --- | --- |\n| TypeScript / JavaScript | Full symbol and import analysis |\n| Python | Full symbol and import analysis |\n| Go | Full symbol and import analysis |\n| Rust | Full symbol and import analysis |\n| Java | Full symbol and import analysis |\n| Other languages | Metadata only (no deep analysis) |\n\n资料来源：[README.md:81-88]()\n\n## Configuration Notes\n\n- `.blueprint/` is local generated memory by default\n- Teams decide whether to commit to version control or add to `.gitignore`\n- Source code remains the single source of truth\n- Do not edit `blueprint-output.json` manually\n\n资料来源：[README.md:53-56]()\n\n## Error Handling\n\nWhen commands encounter issues:\n\n| Scenario | Behavior |\n| --- | --- |\n| Missing inventory artifact | Returns error with artifact ID and expected type |\n| Unparseable files | Marked as `metadata-only` and skipped |\n| Pattern matching failure | Reports unmatched files with suggested paths |\n| Missing group documentation | Displays placeholder message in viewer |\n\n资料来源：[src/tools/scan/scan-code-analysis-engine.ts:15-22]()\n\n## Summary\n\nThe Blueprint CLI provides a comprehensive toolkit for code comprehension and documentation:\n\n1. **Scan** creates a complete inventory of project files\n2. **Group** organizes files into semantic clusters\n3. **Compose** generates documentation and updates agent guidance\n4. **Refresh** keeps the documentation synchronized with filesystem changes\n5. **Open** provides a self-contained HTML viewer\n\nAll operations are designed to enhance developer understanding without modifying source code or requiring a persistent HTTP server.\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Scan Tool](#page-scan-tool), [Group Tool](#page-group-tool), [Compose Tool](#page-compose-tool), [Refresh Tool](#page-refresh-tool)\n\n
\nRelevant Source Files\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/engincankaya/blueprint/blob/main/README.md)\n- [AGENTS.md](https://github.com/engincankaya/blueprint/blob/main/AGENTS.md)\n- [src/tools/scan/scan-file-inventory-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-file-inventory-builder.ts)\n- [src/tools/scan/scan-code-analysis-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-code-analysis-engine.ts)\n- [src/tools/group/grouping-assignment-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/group/grouping-assignment-engine.ts)\n- [src/viewer/render-html.ts](https://github.com/engincankaya/blueprint/blob/main/src/viewer/render-html.ts)\n- [frontend/src/components/blueprint/GroupDetailPanel.tsx](https://github.com/engincankaya/blueprint/blob/main/frontend/src/components/blueprint/GroupDetailPanel.tsx)\n- [frontend/src/components/BlueprintApp.tsx](https://github.com/engincankaya/blueprint/blob/main/frontend/src/components/BlueprintApp.tsx)\n
\n\n# System Architecture\n\n## Overview\n\nBlueprint is a documentation and code organization system that generates a structured \"memory\" layer for software projects. Rather than modifying source code, it creates an orientation layer stored in the `.blueprint/` directory, enabling AI agents and developers to understand project structure without reading every file.\n\n资料来源：[README.md]()\n\nThe system operates as a **transport-agnostic architecture** that can function in two modes:\n\n1. **Static mode**: Embeds data directly into `index.html` for self-contained viewing\n2. **HTTP mode**: Serves data via API for interactive development environments\n\n资料来源：[todos_120526.md]()\n\n## Core Components\n\nBlueprint's architecture consists of four primary tool layers, each responsible for a distinct phase of the documentation lifecycle.\n\n### Tool Layer Architecture\n\n```mermaid\ngraph TD\n A[blueprint scan] --> B[blueprint group]\n B --> C[blueprint compose]\n C --> D[blueprint refresh]\n \n A1[File Inventory] --> B1[Grouping Assignment]\n B1 --> C1[Memory Output]\n C1 --> D1[State Refresh]\n \n A2[Code Analysis] --> B2[Pattern Validation]\n B2 --> C2[Markdown Notes]\n C2 --> D2[Incremental Updates]\n```\n\n### Component Responsibilities\n\n| Component | Purpose | Key Files |\n|-----------|---------|-----------|\n| **Scanner** | Builds file inventory and parses code for symbols, imports, exports | `src/tools/scan/*.ts` |\n| **Grouper** | Assigns files to semantic groups using glob patterns | `src/tools/group/*.ts` |\n| **Composer** | Writes `.blueprint/` memory and patches `AGENTS.md` | `src/tools/compose/*.ts` |\n| **Refresher** | Refreshes Blueprint state from current filesystem | `src/tools/refresh/*.ts` |\n\n资料来源：[README.md]()\n\n## File Inventory System\n\nThe scanning engine builds a comprehensive file inventory by categorizing each file in the project.\n\n### File Categorization Logic\n\nFiles are classified into categories based on path segments, file extensions, and naming patterns:\n\n```mermaid\ngraph LR\n A[File Path] --> B{Extension Check}\n B -->|spec.ts / test.ts| C[test]\n B -->|package-lock.json| D[lockfile]\n B -->|package.json / .config.ts| E[config]\n B -->|readme.md / *.md| F[documentation]\n B -->|.sh / scripts/| G[script]\n B -->|.svg / css / assets/| H[asset]\n```\n\n资料来源：[src/tools/scan/scan-file-inventory-builder.ts]()\n\n### Category Detection Rules\n\n| Category | Detection Criteria |\n|----------|---------------------|\n| `test` | File ends with `.spec.ts`, `.test.ts`, or path contains `test`, `tests`, `__tests__` |\n| `lockfile` | `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `cargo.lock`, `poetry.lock` |\n| `config` | `.gitignore`, `package.json`, `tsconfig.json`, `*.config.js/ts/mjs/cjs`, or language in `json/yaml/toml/xml` |\n| `documentation` | Path contains `docs`, `readme.md`, or any `.md` file |\n| `script` | Path contains `scripts`, shell language, or `.sh` extension |\n| `asset` | Path contains `assets` or `public`, or language in `html/css/scss/svg` |\n\n资料来源：[src/tools/scan/scan-file-inventory-builder.ts]()\n\n## Code Analysis Engine\n\nThe analysis engine parses all \"parseable\" files to extract structural information.\n\n### Analysis Facts Model\n\n```typescript\ninterface AnalysisFacts {\n inventoryArtifactId: string;\n rootPath: string;\n files: Record;\n symbols: Record;\n imports: ImportStatement[];\n exports: ExportStatement[];\n dependencies: Dependency[];\n unresolvedImports: UnresolvedImport[];\n parseErrors: ParseError[];\n summary: AnalysisSummary;\n validation: ValidationStatus;\n}\n```\n\n资料来源：[src/tools/scan/scan-code-analysis-engine.ts]()\n\n### Summary Tracking\n\nThe engine maintains aggregate statistics during parsing:\n\n| Metric | Description |\n|--------|-------------|\n| `totalFiles` | Total files in inventory |\n| `parseableFiles` | Files eligible for parsing |\n| `parsedFiles` | Successfully parsed files |\n| `metadataOnlyFiles` | Files with only metadata (binary, etc.) |\n| `symbols` | Extracted function/class/variable declarations |\n| `imports` | Import statements analyzed |\n| `exports` | Export statements analyzed |\n| `parseErrors` | Files that failed to parse |\n\n资料来源：[src/tools/scan/scan-code-analysis-engine.ts]()\n\n## Group Assignment System\n\nFiles are assigned to semantic groups using glob-based pattern matching.\n\n### Pattern Matching Engine\n\nThe grouper supports wildcard patterns for matching file paths:\n\n```mermaid\ngraph TD\n A[Pattern] --> B{Character}\n B -->|glob `*`| C[Match any chars except /]\n B -->|glob `?`| D[Match single char except /]\n B -->|literal| E[Exact match required]\n C --> F[Build Regex]\n D --> F\n E --> F\n F --> G[^pattern$]\n```\n\n资料来源：[src/tools/group/grouping-assignment-engine.ts]()\n\n### Grouped File Structure\n\n```typescript\ninterface GroupedFile {\n fileId: string;\n path: string;\n category: string;\n language: string;\n importance: \"critical\" | \"important\" | \"standard\" | \"unknown\";\n role: string;\n}\n```\n\n资料来源：[src/tools/group/grouping-assignment-engine.ts]()\n\n### Validation and Suggestions\n\nWhen patterns fail to match any files, the system provides diagnostic information:\n\n```typescript\ninterface UnknownPattern {\n pattern: string;\n reason: string;\n suggestions: string[];\n}\n```\n\nThe suggester extracts suffixes from patterns and finds similar paths in the inventory.\n\n资料来源：[src/tools/group/grouping-assignment-engine.ts]()\n\n## Group Documentation Template\n\nEach group follows a canonical documentation structure that agents can navigate using stable headings.\n\n### Section Structure\n\n```mermaid\ngraph LR\n A[Snapshot] --> B[Responsibilities]\n B --> C[Core Flow]\n C --> D[Contracts & Invariants]\n D --> E[Key Files]\n E --> F[Change Guide]\n F --> G[Pitfalls]\n G --> H[Tests]\n```\n\n资料来源：[AGENTS.md]()\n\n| Section | Purpose |\n|---------|---------|\n| `Snapshot` | Quick orientation for the group |\n| `Responsibilities` | Ownership and out-of-scope areas |\n| `Core Flow` | Runtime behavior and data flow |\n| `Contracts & Invariants` | Behavior that must not be broken |\n| `Key Files` | Main source files for the group |\n| `Change Guide` | Files or contracts that should change together |\n| `Pitfalls` | Known risks and common mistakes |\n| `Tests` | Testing guidance |\n\n资料来源：[AGENTS.md]()\n\n## Frontend Component Architecture\n\nThe Blueprint frontend is a React-based application with a tabbed interface.\n\n### Application Structure\n\n```mermaid\ngraph TD\n A[BlueprintApp] --> B[Tab Bar]\n A --> C[Main Content Area]\n \n B --> D[Canvas Tab]\n B --> E[Group Detail Tabs]\n \n C --> D\n C --> E\n \n E --> F[GroupDetailPanel]\n F --> G[Overview]\n F --> H[Files]\n F --> I[Connections]\n F --> J[Architecture]\n F --> K[Guide]\n```\n\n资料来源：[frontend/src/components/BlueprintApp.tsx]()\n资料来源：[frontend/src/components/blueprint/GroupDetailPanel.tsx]()\n\n### Sub-Tab Content Mapping\n\n| Sub-Tab | Content Components |\n|---------|--------------------|\n| `overview` | Snapshot, Responsibilities, Key Files, Open Questions |\n| `files` | Role breakdown tags, File tree with icons |\n| `connections` | ConnectionDiagram visualization |\n| `architecture` | CoreFlow, ContractsAndInvariants, KeyFiles cards |\n| `guide` | ChangeGuide, Pitfalls, Tests, Debugging, OpenQuestions |\n\n资料来源：[frontend/src/components/blueprint/GroupDetailPanel.tsx]()\n\n### SectionCard Component\n\nThe `SectionCard` component provides collapsible content sections with accent colors:\n\n```typescript\ninterface SectionCardProps {\n title: string;\n content: string;\n accent?: 'amber' | 'red' | 'green' | 'blue' | 'zinc';\n defaultOpen?: boolean;\n index?: number;\n}\n```\n\n| Accent Color | Use Case |\n|--------------|----------|\n| `blue` | Default sections |\n| `amber` | Pitfalls and warnings |\n| `red` | Invariants (critical constraints) |\n| `green` | Extension open questions |\n| `zinc` | Standard content |\n\n资料来源：[frontend/src/components/blueprint/GroupDetailPanel.tsx]()\n\n## Static Viewer Rendering\n\nThe HTML renderer creates self-contained viewer files by inlining assets.\n\n### Inlining Process\n\n```mermaid\ngraph LR\n A[Template HTML] --> B[Inline CSS]\n B --> C[Inline JS]\n C --> D[Embed JSON Data]\n D --> E[Escape & Validate]\n E --> F[index.html]\n```\n\n资料来源：[src/viewer/render-html.ts]()\n\n### Asset Inlining Strategy\n\nThe renderer processes three asset types:\n\n| Asset Type | Regex Pattern | Replacement |\n|------------|---------------|-------------|\n| CSS | `` | `` |\n| Module JS (crossorigin) | `` |\n| Module JS | `` |\n\n资料来源：[src/viewer/render-html.ts]()\n\n### Data Embedding Security\n\nJSON data is embedded using `\n```\n\n资料来源：[todos_120526.md]()\n\n## Workflow State Machine\n\n### Initial Workflow\n\n```mermaid\ngraph TD\n A[Start] --> B[blueprint scan]\n B --> C[blueprint group prepare]\n C --> D{Create grouping plan}\n D --> E[blueprint group apply]\n E --> F[blueprint compose]\n F --> G[Complete]\n \n H[hydrate group docs] -.-> G\n```\n\n### Maintenance Workflow\n\n```mermaid\ngraph TD\n A[Project Change] --> B[blueprint refresh]\n B --> C{New unassigned files?}\n C -->|Yes| D[blueprint group update]\n C -->|No| E[Update affected group docs]\n D --> E\n E --> F[Complete]\n```\n\n资料来源：[README.md]()\n\n## Artifact Storage\n\nThe system uses typed artifact storage for persisting scan results, groupings, and composed output.\n\n### Artifact Types\n\n| Artifact | Purpose |\n|----------|---------|\n| `fileInventory` | Complete file listing with categories |\n| `codeAnalysis` | Symbols, imports, exports from parsing |\n| `groupingAssignment` | File-to-group mappings |\n| `groupDocAnalysis` | Canonical section validation |\n\n资料来源：[src/lib/artifact-store.ts]()\n\n### Validation Status\n\nEach analysis maintains a validation record:\n\n```typescript\ninterface ValidationStatus {\n isComplete: boolean;\n inventoryFiles: number;\n parseableFiles: number;\n parsedFiles: number;\n metadataOnlyFiles: number;\n skippedMetadataOnlyFiles: number;\n parseErrors: number;\n unaccountedFiles: string[];\n}\n```\n\n资料来源：[src/tools/scan/scan-code-analysis-engine.ts]()\n\n## Key Design Principles\n\n1. **Source of Truth**: Source code remains the source of truth; `.blueprint/` is generated memory only\n2. **Local by Default**: Blueprint memory is stored in `.blueprint/` (not in `node_modules`)\n3. **Transport Agnostic**: Supports both static HTML and HTTP API modes\n4. **Safe Embedding**: JSON data is safely escaped before HTML embedding\n5. **Canonical Structure**: Group docs follow a stable template for consistent navigation\n\n资料来源：[README.md]()\n资料来源：[todos_120526.md]()\n\n---\n\n\n\n## MCP Server Implementation\n\n### 相关页面\n\n相关主题：[System Architecture](#page-system-architecture), [Task Context Tool](#page-task-context-tool)\n\n
\nRelated Source Files\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/scan/scan-code-analysis-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-code-analysis-engine.ts)\n- [src/tools/scan/scan-file-inventory-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-file-inventory-builder.ts)\n- [src/lib/agent-instructions.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/agent-instructions.ts)\n- [AGENTS.md](https://github.com/engincankaya/blueprint/blob/main/AGENTS.md)\n- [README.md](https://github.com/engincankaya/blueprint/blob/main/README.md)\n
\n\n# MCP Server Implementation\n\nThe Blueprint MCP Server provides a Model Context Protocol interface for AI agents to interact with codebase architecture memory. It exposes tools for scanning codebases, grouping files semantically, composing documentation, and maintaining architectural state across project changes.\n\n## Overview\n\nBlueprint operates as a local architecture memory layer that sits above source code. The MCP Server acts as the bridge between AI agents and the Blueprint tooling, enabling deterministic project understanding without manual documentation overhead.\n\n```mermaid\ngraph TD\n A[AI Agent] -->|MCP Protocol| B[Blueprint MCP Server]\n B -->|blueprint.scan| C[File Inventory Builder]\n B -->|blueprint.group| D[Semantic Grouper]\n B -->|blueprint.compose| E[Documentation Writer]\n B -->|blueprint.refresh| F[State Refresher]\n C -->|Artifacts| G[blueprint-output.json]\n D -->|Groupings| H[groups/*.md]\n E -->|Memory| G & H\n F -->|Sync| G & H\n```\n\n资料来源：[README.md:1-15]()\n\n## MCP Tools Architecture\n\n### Available Tools\n\n| Tool | Purpose | Output |\n|------|---------|--------|\n| `blueprint.scan` | Builds file inventory and code analysis artifacts | File metadata, symbols, imports |\n| `blueprint.group` | Prepares or applies semantic file grouping | Group definitions |\n| `blueprint.compose` | Writes Blueprint output and Markdown notes | `.blueprint/` memory files |\n| `blueprint.refresh` | Refreshes state from current filesystem | Updated JSON state |\n| `blueprint.group.update` | Assigns unassigned files or manages empty groups | Updated groupings |\n\n资料来源：[README.md:30-36]()\n\n### Tool Workflow\n\n```mermaid\ngraph LR\n A[Initial Setup] --> B[scan]\n B --> C[group prepare]\n C --> D[Review Plan]\n D --> E[group apply]\n E --> F[compose]\n F --> G[Memory Written]\n \n H[Maintenance] --> I[refresh]\n I --> J{Unassigned Files?}\n J -->|Yes| K[group.update]\n J -->|No| L[Update Docs Only]\n K --> M[Update group/*.md]\n```\n\n#### Initial Workflow\n\n1. `blueprint.scan` - Builds file inventory and code analysis artifacts\n2. `blueprint.group` with `mode: \"prepare\"` - Prepares grouping plan\n3. Review the compact grouping plan output\n4. `blueprint.group` with `mode: \"apply\"` - Applies the grouping\n5. `blueprint.compose` - Writes `.blueprint/` memory and patches `AGENTS.md`\n\n资料来源：[README.md:18-27]()\n\n#### Maintenance Workflow\n\n1. Run `blueprint.refresh` when project changes occur\n2. If new files are unassigned, run `blueprint.group.update`\n3. Update only affected `.blueprint/groups/*.md` notes when architecture changes\n\n资料来源：[README.md:29-33]()\n\n## Scan Tool Implementation\n\n### File Inventory Builder\n\nThe `scan-file-inventory-builder.ts` handles filesystem traversal and file classification. It categorizes files into types based on naming conventions and path segments.\n\n#### File Type Classification\n\n| Type | Detection Criteria |\n|------|---------------------|\n| `test` | `test.spec.ts`, `test.spec.tsx`, `test.spec.js`, `test.spec.jsx`, `/test/`, `/tests/`, `__tests__/` |\n| `lockfile` | `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `cargo.lock`, `poetry.lock` |\n| `config` | `.gitignore`, `package.json`, `tsconfig.json`, `*.config.js`, `*.config.ts`, language in `[json, yaml, toml, xml]` |\n| `documentation` | `/docs/`, `readme.md`, `*.md`, language `markdown` |\n| `script` | `/scripts/`, language `shell`, `*.sh` |\n| `asset` | `/assets/`, `/public/`, language in `[html, css, scss, svg]` |\n| `generated` | `/generated/`, `/__generated__/` |\n\n资料来源：[src/tools/scan/scan-file-inventory-builder.ts:1-80]()\n\n### Code Analysis Engine\n\nThe `scan-code-analysis-engine.ts` performs deep analysis on parseable files, extracting symbols, imports, exports, and dependencies.\n\n#### Analysis Facts Model\n\n```typescript\ninterface AnalysisFacts {\n inventoryArtifactId: string;\n rootPath: string;\n files: Record;\n symbols: Record;\n imports: ImportStatement[];\n exports: ExportStatement[];\n dependencies: Dependency[];\n unresolvedImports: UnresolvedImport[];\n parseErrors: ParseError[];\n summary: {\n totalFiles: number;\n parseableFiles: number;\n metadataOnlyFiles: number;\n plannedFiles: number;\n parsedFiles: number;\n symbols: number;\n imports: number;\n exports: number;\n dependencies: number;\n parseErrors: number;\n };\n validation: AnalysisValidation;\n}\n```\n\n资料来源：[src/tools/scan/scan-code-analysis-engine.ts:20-40]()\n\n#### Language Support\n\nBlueprint uses Tree-sitter analysis for:\n\n| Language | Symbol Analysis | Import/Export Analysis |\n|----------|-----------------|------------------------|\n| TypeScript/JavaScript | ✅ Full | ✅ Full |\n| Python | ✅ Full | ✅ Full |\n| Go | ✅ Full | ✅ Full |\n| Rust | ✅ Full | ✅ Full |\n| Java | ✅ Full | ✅ Full |\n| Other | Metadata only | Metadata only |\n\n资料来源：[README.md:60-65]()\n\n### Validation Model\n\n```typescript\ninterface AnalysisValidation {\n isComplete: boolean;\n inventoryFiles: number;\n parseableFiles: number;\n parsedFiles: number;\n metadataOnlyFiles: number;\n skippedMetadataOnlyFiles: number;\n parseErrors: number;\n unaccountedFiles: string[];\n}\n```\n\n资料来源：[src/tools/scan/scan-code-analysis-engine.ts:42-50]()\n\n## Agent Integration\n\n### AGENTS.md Integration\n\nThe MCP Server integrates with project `AGENTS.md` files using marker-delimited snippets. When `blueprint.compose` runs, it patches the `AGENTS.md` without overwriting existing project instructions.\n\n#### Snippet Format\n\n```markdown\n\n\n## Blueprint MCP\n\nThis project uses Blueprint MCP for local architecture memory.\n\nBefore broad codebase exploration, read:\n\n`node_modules/blueprint-mcp-server/docs/agents.md`\n\nIf Blueprint memory exists, start with:\n\n`.blueprint/brief.md`\n\n\n```\n\n资料来源：[src/lib/agent-instructions.ts:15-30]()\n\n### Agent Instruction Rendering\n\n```typescript\nexport function renderBlueprintAgentsSnippet(): string {\n return [\n beginMarker,\n \"\",\n \"## Blueprint MCP\",\n \"\",\n \"This project uses Blueprint MCP for local architecture memory.\",\n \"\",\n \"Before broad codebase exploration, read:\",\n \"\",\n \"`node_modules/blueprint-mcp-server/docs/agents.md`\",\n \"\",\n \"If Blueprint memory exists, start with:\",\n \"\",\n \"`.blueprint/brief.md`\",\n \"\",\n endMarker,\n ].join(\"\\n\");\n}\n```\n\n资料来源：[src/lib/agent-instructions.ts:40-58]()\n\n## Blueprint Memory Structure\n\n```mermaid\ngraph TD\n subgraph \".blueprint/\"\n A[blueprint-output.json] -->|Deterministic| B[Group definitions]\n A -->|Deterministic| C[File inventory]\n A -->|Deterministic| D[Analysis facts]\n E[brief.md] -->|Overview| F[Architectural groups]\n G[groups/*.md] -->|Detailed| H[Responsibilities]\n G -->|Detailed| I[Core Flow]\n G -->|Detailed| J[Contracts & Invariants]\n G -->|Detailed| K[Change Guide]\n G -->|Detailed| L[Pitfalls]\n end\n \n M[refresh-scan.json] -->|Hash snapshot| N[Deterministic refresh]\n```\n\n### Generated Artifacts\n\n| File | Purpose |\n|------|---------|\n| `blueprint-output.json` | Structured project graph generated by tools |\n| `refresh-scan.json` | Filesystem hash snapshot for deterministic refreshes |\n\n资料来源：[README.md:9-12]()\n\n### Group Documentation Template\n\nFiles under `.blueprint/groups/*.md` follow a stable template:\n\n| Section | Purpose |\n|---------|---------|\n| `Snapshot` | Quick orientation |\n| `Responsibilities` | Ownership and out-of-scope areas |\n| `Core Flow` | Runtime behavior and data flow |\n| `Contracts & Invariants` | Behavior that must not be broken |\n| `Key Files` | Main source files for the group |\n| `Change Guide` | Files or contracts that should change together |\n| `Pitfalls` | Known risks and common mistakes |\n| `Tests` | Most relevant verification |\n| `Debugging` | Failure-mode hints |\n| `Extension / Open Questions` | Uncertainty and known gaps |\n\n资料来源：[AGENTS.md:1-35]()\n\n## Viewer Integration\n\nBlueprint ships a lightweight React/Vite viewer that reads generated Blueprint data.\n\n### Static HTML Generation\n\n```mermaid\ngraph LR\n A[blueprint open] --> B[Read JSON & MD]\n B --> C[Generate index.html]\n C --> D[Open in browser]\n \n E[--watch mode] --> F[Regenerate on changes]\n```\n\n#### Viewer Features\n\n- Self-contained HTML with inline JS and CSS\n- Secure embedded JSON data\n- No HTTP server required\n- No chat or LLM execution\n\n资料来源：[README.md:38-50]()\n\n## Import Resolution System\n\n### Candidate Import Path Resolution\n\nThe code analysis engine resolves relative imports by checking multiple candidate paths:\n\n```typescript\nprivate candidateImportPaths(basePath: string): string[] {\n const candidates = [basePath];\n \n if (ext) {\n return candidates;\n }\n \n return [\n basePath,\n `${basePath}.ts`,\n `${basePath}.tsx`,\n `${basePath}.js`,\n `${basePath}.jsx`,\n `${basePath}/index.ts`,\n `${basePath}/index.tsx`,\n `${basePath}/index.js`,\n `${basePath}/index.jsx`,\n ];\n}\n```\n\n资料来源：[src/tools/scan/scan-code-analysis-engine.ts:80-95]()\n\n## Key Design Principles\n\n### Source of Truth\n\n| Principle | Implication |\n|-----------|-------------|\n| Source code is ground truth | Blueprint docs are orientation, not authority |\n| Documentation follows changes | Update relevant group docs after source changes |\n| Deterministic JSON | Do not edit `blueprint-output.json` manually |\n\n资料来源：[AGENTS.md:55-60]()\n\n### Working Rules\n\n1. Keep changes scoped to the user's task\n2. Prefer existing project patterns over new abstractions\n3. Add or update tests when behavior changes\n4. Run the smallest relevant verification first\n5. Do not edit generated files unless explicitly required\n\n资料来源：[AGENTS.md:65-70]()\n\n---\n\n\n\n## Scan Tool\n\n### 相关页面\n\n相关主题：[System Architecture](#page-system-architecture), [Group Tool](#page-group-tool)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/scan/scan-code-analysis-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-code-analysis-engine.ts)\n- [src/tools/scan/scan-file-inventory-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-file-inventory-builder.ts)\n
\n\n# Scan Tool\n\nThe Scan Tool (`blueprint.scan`) is the first stage in the Blueprint workflow. It performs filesystem traversal and static code analysis to build a comprehensive **File Inventory** and **Analysis Facts** artifact. These artifacts serve as the foundational data layer for subsequent grouping, composition, and visualization operations.\n\n## Overview\n\nThe Scan Tool operates in two distinct phases:\n\n1. **File Inventory Phase** - Traverses the project filesystem, categorizes files by role (source, test, config, etc.), and detects the technology stack\n2. **Code Analysis Phase** - Parses source files using Tree-sitter to extract symbols, imports, exports, and dependency relationships\n\n```\n┌─────────────────┐ ┌──────────────────────────┐ ┌─────────────────┐\n│ Filesystem │───▶│ FileInventoryBuilder │───▶│ FileInventory │\n│ Traversal │ │ (scan-file-inventory) │ │ Artifact │\n└─────────────────┘ └──────────────────────────┘ └────────┬────────┘\n │\n ▼\n┌─────────────────┐ ┌──────────────────────────┐ ┌─────────────────┐\n│ AnalysisFacts │◀───│ CodeAnalysisEngine │◀───│ Parseable │\n│ Artifact │ │ (scan-code-analysis) │ │ Files │\n└─────────────────┘ └──────────────────────────┘ └─────────────────┘\n```\n\n## Architecture\n\n### Core Components\n\n| Component | File | Responsibility |\n|-----------|------|----------------|\n| `ScanFileInventoryBuilder` | `scan-file-inventory-builder.ts` | Filesystem traversal, file categorization, stack detection |\n| `CodeAnalysisEngine` | `scan-code-analysis-engine.ts` | Tree-sitter parsing, symbol extraction, dependency analysis |\n| `FileInventory` | Data model | Container for all inventoried files and summary statistics |\n| `AnalysisFacts` | Data model | Container for parsed code facts (symbols, imports, exports) |\n\n### Class: ScanFileInventoryBuilder\n\nThe `ScanFileInventoryBuilder` class is responsible for walking the project directory and building a structured file inventory.\n\n```typescript\nclass ScanFileInventoryBuilder {\n // Builds the complete file inventory from a root path\n async build(rootPath: string): Promise\n \n // Validates inventory completeness against scanned paths\n private validateInventory(scannedPaths: string[], files: InventoryFile[]): FileInventoryValidation\n}\n```\n\n**资料来源**：[scan-file-inventory-builder.ts:1-50]()\n\n### Class: CodeAnalysisEngine\n\nThe `CodeAnalysisEngine` class consumes the file inventory and performs deep static analysis on parseable files.\n\n```typescript\nclass CodeAnalysisEngine {\n async handle(args: CodeAnalysisEngineArgs, store: ArtifactStore): Promise\n \n // Builds a mapping from file paths to file IDs for efficient lookup\n private buildPathToFileId(inventory: FileInventory): Map\n \n // Computes validation metrics for the analysis results\n private computeValidation(parsedFileIds, parseErrorFileIds, inventory): AnalysisValidation\n}\n```\n\n**资料来源**：[scan-code-analysis-engine.ts:1-60]()\n\n## File Inventory Phase\n\n### File Role Detection\n\nThe scanner categorizes each file into one of the following roles based on its path and extension:\n\n| Role | Detection Criteria |\n|------|-------------------|\n| `source` | Primary language files (`.ts`, `.tsx`, `.js`, `.jsx`, `.py`, `.go`, `.rs`, `.java`) |\n| `test` | Files ending in `.spec.ts`, `.test.ts`, or containing `test`/`tests`/`__tests__` in path |\n| `lockfile` | `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `Cargo.lock`, `poetry.lock` |\n| `config` | `.gitignore`, `package.json`, `tsconfig.json`, `.config.js/ts`, config files |\n| `documentation` | Files in `docs/`, `readme.md`, or other `.md` files |\n| `script` | Files in `scripts/`, shell scripts (`.sh`), or `language === \"shell\"` |\n| `asset` | Files in `assets/`, `public/`, or with extensions: `.html`, `.css`, `.scss`, `.svg` |\n\n**资料来源**：[scan-file-inventory-builder.ts:50-130]()\n\n### Analysis Level Classification\n\nEach file receives an `analysisLevel` designation:\n\n| Level | Description |\n|-------|-------------|\n| `parseable` | Files with known parsers that support symbol/import extraction |\n| `metadata-only` | Files that are inventoried but cannot be deeply parsed |\n\n**资料来源**：[scan-code-analysis-engine.ts:20-30]()\n\n### Stack Detection\n\nThe builder detects the technology stack from two sources:\n\n1. **Language counts** - Extracted from file extensions\n2. **Path patterns** - Special directories indicate additional technologies\n\n| Pattern | Stack Addition |\n|---------|---------------|\n| `*.ts`, `*.js`, etc. | Respective language name |\n| `package.json` in paths | `\"node\"` |\n| `mcp-server/` in paths | `\"mcp\"` |\n\n**资料来源**：[scan-file-inventory-builder.ts:180-200]()\n\n### Package Manager Detection\n\nDetects which package managers are in use:\n\n| File | Manager |\n|------|---------|\n| `package.json` | `npm`, `yarn`, `pnpm` |\n| `Cargo.toml` | `cargo` |\n| `go.mod` | `go` |\n| `pyproject.toml`, `requirements.txt` | `python` |\n| `pom.xml` | `maven` |\n| `build.gradle`, `build.gradle.kts` | `gradle` |\n\n**资料来源**：[scan-file-inventory-builder.ts:150-175]()\n\n## Code Analysis Phase\n\n### Tree-sitter Integration\n\nThe analysis engine uses Tree-sitter for parsing supported languages:\n\n| Supported Languages | Extensions |\n|---------------------|------------|\n| TypeScript/JavaScript | `.ts`, `.tsx`, `.js`, `.jsx` |\n| Python | `.py` |\n| Go | `.go` |\n| Rust | `.rs` |\n| Java | `.java` |\n\n> **Note**: Files in other languages are still included in the inventory but receive `metadata-only` analysis.\n\n**资料来源**：[README.md - Language Support section]()\n\n### Extracted Facts\n\nFor each parseable file, the engine extracts:\n\n```typescript\ninterface AnalysisFacts {\n inventoryArtifactId: string;\n rootPath: string;\n files: Record; // fileId -> parsed content\n symbols: Record; // fileId -> extracted symbols\n imports: ImportStatement[]; // all import statements\n exports: ExportStatement[]; // all export statements\n dependencies: DependencyEdge[]; // inter-file dependencies\n unresolvedImports: UnresolvedImport[]; // imports without matching exports\n parseErrors: ParseError[]; // parsing failures\n summary: AnalysisSummary;\n validation: AnalysisValidation;\n}\n```\n\n**资料来源**：[scan-code-analysis-engine.ts:30-60]()\n\n### Validation Model\n\nThe analysis produces a validation object tracking completeness:\n\n```typescript\ninterface AnalysisValidation {\n isComplete: boolean; // true if all files processed\n inventoryFiles: number; // total files in inventory\n parseableFiles: number; // files marked as parseable\n parsedFiles: number; // successfully parsed count\n metadataOnlyFiles: number; // metadata-only file count\n skippedMetadataOnlyFiles: number; // metadata-only files skipped\n parseErrors: number; // parse failure count\n unaccountedFiles: string[]; // files not in parsed or error sets\n}\n```\n\n**资料来源**：[scan-code-analysis-engine.ts:60-75]()\n\n## Data Flow\n\n```mermaid\ngraph TD\n A[Root Path] --> B[ScanFileInventoryBuilder.build]\n B --> C[Filesystem Walk]\n C --> D[File Categorization]\n D --> E[Stack Detection]\n E --> F[FileInventory Artifact]\n \n F --> G[CodeAnalysisEngine.handle]\n G --> H[Filter Parseable Files]\n H --> I[For Each Parseable File]\n I --> J[Read File Content]\n J --> K[Create Tree-sitter Parser]\n K --> L[Extract Symbols]\n K --> M[Extract Imports]\n K --> N[Extract Exports]\n L --> O[Build Dependency Graph]\n M --> O\n N --> O\n O --> P[AnalysisFacts Artifact]\n \n I --> Q[Handle Parse Errors]\n Q --> P\n```\n\n## Output Artifacts\n\n### FileInventory Artifact\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `rootPath` | `string` | Absolute path to scanned root |\n| `files` | `InventoryFile[]` | All discovered files with metadata |\n| `summary` | `InventorySummary` | Aggregated statistics |\n\n### AnalysisFacts Artifact\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `symbols` | `Record` | Symbols indexed by file ID |\n| `imports` | `ImportStatement[]` | All import declarations |\n| `exports` | `ExportStatement[]` | All export declarations |\n| `dependencies` | `DependencyEdge[]` | File-to-file dependency edges |\n| `unresolvedImports` | `UnresolvedImport[]` | Imports without matching targets |\n\n## Configuration & Behavior\n\n### Summary Statistics\n\nThe `FileInventory` summary provides project metrics:\n\n```typescript\ninterface InventorySummary {\n totalFiles: number;\n parseableFiles: number;\n metadataOnlyFiles: number;\n byLanguage: Record;\n byRole: Record;\n}\n```\n\n**资料来源**：[scan-file-inventory-builder.ts:200-220]()\n\n### Validation Completeness Check\n\nThe engine computes `isComplete` as:\n\n```\nisComplete = (parsedFiles + parseErrorFiles + skippedMetadataOnlyFiles) === totalInventoryFiles\n```\n\nIf `isComplete` is `false`, there are files in the inventory that were neither successfully parsed nor accounted for in error/skipped sets.\n\n**资料来源**：[scan-code-analysis-engine.ts:100-115]()\n\n## Integration with Blueprint Workflow\n\nThe Scan Tool is the entry point for the Blueprint system:\n\n```\nblueprint.scan → blueprint.group → blueprint.compose\n```\n\n1. **`blueprint.scan`** - Produces `fileInventory` and `analysisFacts` artifacts\n2. **`blueprint.group`** - Consumes these artifacts to create semantic groupings\n3. **`blueprint.compose`** - Generates the final `blueprint-output.json`\n\n**资料来源**：[README.md - Initial Workflow section]()\n\n## Error Handling\n\nThe Scan Tool handles several error conditions:\n\n| Error Condition | Handling |\n|-----------------|----------|\n| File not found | Included in `parseErrors` array |\n| Parser unavailable | File marked as `metadata-only` |\n| Syntax error in source | Recorded with location in `parseErrors` |\n| Missing inventory artifact | Returns error result from `handle()` |\n| Unaccounted files | Listed in `validation.unaccountedFiles` |\n\n**资料来源**：[scan-code-analysis-engine.ts:80-95]()\n\n## Refresh Maintenance\n\nWhen the filesystem changes:\n\n```bash\nblueprint.refresh\n```\n\nThis re-runs the scan to update the file inventory and analysis facts, ensuring the Blueprint state reflects the current project structure.\n\n**资料来源**：[README.md - Maintenance Workflow section]()\n\n---\n\n\n\n## Group Tool\n\n### 相关页面\n\n相关主题：[System Architecture](#page-system-architecture), [Scan Tool](#page-scan-tool), [Compose Tool](#page-compose-tool)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/group/index.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/group/index.ts)\n- [src/tools/group/grouping-assignment-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/group/grouping-assignment-engine.ts)\n- [src/tools/group/grouping-plan-validator.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/group/grouping-plan-validator.ts)\n- [src/tools/group/grouping.types.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/group/grouping.types.ts)\n
\n\n# Group Tool\n\n## Overview\n\nThe Group Tool is a core component of the Blueprint system responsible for organizing source files into semantic architectural groups. It bridges the gap between raw file inventory (produced by the Scan Tool) and the structured architectural documentation (produced by the Compose Tool).\n\n**Purpose**: The Group Tool transforms a flat list of files into a meaningful hierarchical structure where files are assigned to architectural groups based on semantic patterns, role assignments, and cross-group relationships.\n\n**Scope**:\n- Processes file inventory data from the Scan Tool\n- Assigns files to groups based on glob patterns and semantic rules\n- Validates grouping plans for completeness and conflicts\n- Aggregates cross-group edges and relationships\n- Handles fallback grouping for unassigned files\n- Supports both `prepare` and `apply` modes for iterative group planning\n\n资料来源：[src/tools/group/grouping-assignment-engine.ts:1-50]()\n\n## Architecture\n\n### Component Flow\n\n```mermaid\ngraph TD\n A[FileInventory] --> B[GroupingAssignmentEngine]\n B --> C[GroupingPlanValidator]\n C --> D[GroupingResult]\n D --> E[ComposeOutputBuilder]\n E --> F[BlueprintOutput]\n \n G[GroupingPlan] --> B\n H[FileFacts] --> B\n```\n\n### Core Components\n\n| Component | File | Responsibility |\n|-----------|------|----------------|\n| `GroupingAssignmentEngine` | `grouping-assignment-engine.ts` | Core logic for file-to-group assignment and pattern matching |\n| `GroupingPlanValidator` | `grouping-plan-validator.ts` | Validates grouping plans for completeness and conflicts |\n| Grouping Types | `grouping.types.ts` | TypeScript interfaces for grouping data models |\n| Tool Entry Point | `index.ts` | CLI/MCP tool interface handling prepare/apply modes |\n\n资料来源：[src/tools/group/grouping-assignment-engine.ts:1-30]()\n\n## Data Models\n\n### Key Types\n\n```typescript\n// GroupedFile represents a file assigned to a group\ninterface GroupedFile {\n fileId: string;\n path: string;\n category: string;\n language: string;\n importance: \"unknown\";\n role: \"unknown\";\n}\n\n// BlueprintGroup represents a semantic architectural group\ninterface BlueprintGroup {\n id: string;\n name: string;\n description: string;\n kind: string;\n confidence: number;\n files: GroupedFile[];\n}\n\n// GroupingResult contains the complete grouping output\ninterface GroupingResult {\n groups: BlueprintGroup[];\n crossGroupEdges: CrossGroupEdge[];\n}\n```\n\n资料来源：[src/tools/group/grouping.types.ts]()\n\n### Group Assignment Strategy\n\nThe assignment engine uses a multi-stage process:\n\n1. **Pattern Matching**: Files are matched against glob-like patterns specified in the grouping plan\n2. **Role Assignment**: Each file receives a role based on pattern matching and heuristics\n3. **Fallback Grouping**: Unmatched files are placed in a fallback group\n4. **Edge Aggregation**: Cross-group relationships are aggregated from file-level dependencies\n\n资料来源：[src/tools/group/grouping-assignment-engine.ts:50-150]()\n\n## Pattern Matching Engine\n\n### Regex-Based Pattern System\n\nThe assignment engine converts user-friendly glob patterns into regular expressions for flexible file matching:\n\n```mermaid\ngraph LR\n A[Glob Pattern] --> B[buildRegex]\n B --> C[Regular Expression]\n C --> D[File Path Matching]\n D --> E{Match?}\n E -->|Yes| F[Assign to Group]\n E -->|No| G[Next Pattern]\n```\n\n### Supported Pattern Syntax\n\n| Pattern | Regex Equivalent | Description |\n|---------|------------------|-------------|\n| `*` | `[^/]*` | Match any characters except path separator |\n| `?` | `[^/]` | Match single character except path separator |\n| `**` | `.*` | Match any characters including path separators |\n| Literal chars | Escaped | Match exact characters |\n\n资料来源：[src/tools/group/grouping-assignment-engine.ts:100-130]()\n\n### Pattern Processing Method\n\n```typescript\nprivate buildRegex(pattern: string): RegExp {\n let source = \"\";\n for (const char of pattern) {\n if (char === \"*\") {\n source += \"[^/]*\";\n continue;\n }\n if (char === \"?\") {\n source += \"[^/]\";\n continue;\n }\n source += this.escapeRegex(char);\n }\n return new RegExp(`^${source}$`);\n}\n```\n\n资料来源：[src/tools/group/grouping-assignment-engine.ts:115-127]()\n\n## Grouping Workflow\n\n### Prepare Mode\n\nIn `prepare` mode, the tool analyzes the file inventory and suggests:\n\n- Suggested group structures based on directory structure and file patterns\n- Suggested role assignments for files\n- Cross-group relationship candidates\n- Confidence scores for each suggestion\n\n```mermaid\nsequenceDiagram\n participant User\n participant GroupTool\n participant ScanTool\n participant ComposeTool\n \n User->>ScanTool: blueprint.scan\n ScanTool->>GroupTool: FileInventory\n GroupTool->>GroupTool: Analyze patterns\n GroupTool-->>User: Suggested grouping plan\n User->>GroupTool: Refine grouping plan\n User->>GroupTool: blueprint.group(mode: apply)\n GroupTool->>ComposeTool: GroupingResult\n ComposeTool-->>User: Blueprint output\n```\n\n### Apply Mode\n\nIn `apply` mode, the tool:\n\n1. Validates the provided grouping plan\n2. Assigns files to groups based on patterns\n3. Aggregates cross-group edges\n4. Returns the structured `GroupingResult`\n\n资料来源：[src/tools/group/index.ts]()\n\n## Validation System\n\n### Plan Validation Checks\n\nThe `GroupingPlanValidator` performs comprehensive validation:\n\n| Validation Check | Purpose |\n|------------------|---------|\n| `unassignedFiles` | Ensures no files are left unassigned |\n| `duplicateAssignments` | Detects files assigned to multiple groups |\n| `unknownPatterns` | Flags patterns that matched no files |\n| `emptyGroups` | Identifies groups with no files |\n| `blockingIssues` | Prevents composition if critical issues exist |\n\n资料来源：[src/tools/group/grouping-plan-validator.ts]()\n\n### Validation Result Structure\n\n```typescript\ninterface ValidationResult {\n isValid: boolean;\n blockingIssues: string[];\n warningIssues: string[];\n unassignedFiles: FileInventory[\"files\"][number][];\n duplicateAssignments: Array<{ fileId: string; groups: string[] }>;\n unknownPatterns: UnknownPattern[];\n emptyGroups: string[];\n}\n```\n\n资料来源：[src/tools/group/grouping-plan-validator.ts:1-50]()\n\n## Edge Aggregation\n\n### Cross-Group Relationship Detection\n\nThe assignment engine aggregates edges between groups based on:\n\n1. **Import Dependencies**: Files importing from other groups\n2. **Reference Patterns**: Cross-module references\n3. **Test Relationships**: Test files referencing implementation files\n\n```typescript\nprivate aggregateEdges(\n facts: FileFacts,\n fileToGroup: Map\n): CrossGroupEdge[] {\n // Aggregates file-level edges into group-level edges\n // Groups edges by fromGroupId, toGroupId, and type\n // Returns sorted, deduplicated edge list\n}\n```\n\n资料来源：[src/tools/group/grouping-assignment-engine.ts:200-250]()\n\n### Edge Composition\n\nThe `compose-output-builder.ts` transforms grouping results into the final output format:\n\n```typescript\nedges: [...grouping.crossGroupEdges]\n .sort((a, b) =>\n a.fromGroupId.localeCompare(b.fromGroupId)\n || a.toGroupId.localeCompare(b.toGroupId)\n || a.type.localeCompare(b.type),\n ),\n```\n\n资料来源：[src/tools/compose/compose-output-builder.ts:1-50]()\n\n## Group Update Workflow\n\n### Refresh Integration\n\nWhen files change in the repository, the Group Tool integrates with the refresh workflow:\n\n```mermaid\ngraph LR\n A[File Changes] --> B[Refresh Tool]\n B --> C{New unassigned files?}\n C -->|Yes| D[Group Update Tool]\n C -->|No| E[Skip Update]\n D --> F[User Decisions]\n F --> G[Updated Grouping]\n```\n\n### Empty Group Detection\n\nThe refresh process identifies:\n\n- **Unassigned Files**: Files not belonging to any group\n- **Empty Group Candidates**: Groups that have lost all their files\n\n```typescript\nconst emptyGroupCandidates = output.groups\n .filter((group) => group.fileIds.length === 0)\n .map((group) => ({\n groupId: group.id,\n name: group.name,\n docsPath: group.docsPath,\n deletedFileIds: [],\n }));\n```\n\n资料来源：[src/tools/group-update/index.ts:1-50]()\n\n## File Categorization\n\nThe Group Tool inherits file categorization from the Scan Tool:\n\n| Category | Detection Criteria |\n|----------|-------------------|\n| `source` | TypeScript, JavaScript, Python source files |\n| `test` | Files ending in `.spec.ts`, `.test.ts`, in `test/` directories |\n| `config` | `package.json`, `tsconfig.json`, config files |\n| `documentation` | `.md` files, `docs/` directories |\n| `script` | Shell scripts, `scripts/` directories |\n| `asset` | CSS, SVG, image files |\n| `lockfile` | `package-lock.json`, `yarn.lock`, etc. |\n\n资料来源：[src/tools/scan/scan-file-inventory-builder.ts:1-100]()\n\n## Integration Points\n\n### With Scan Tool\n\nThe Group Tool receives file inventory data:\n- File paths and IDs\n- Language detection\n- Category classification\n- Basic file facts\n\n### With Compose Tool\n\nThe Group Tool produces `GroupingResult` containing:\n- Structured groups with assigned files\n- Cross-group edges for relationship visualization\n- Role assignments for documentation\n\n### With Refresh Tool\n\nThe Group Tool participates in the refresh workflow by:\n- Receiving updated file inventory\n- Identifying unassigned files\n- Detecting empty group candidates\n\n资料来源：[src/tools/refresh/index.ts:1-100]()\n\n## Error Handling\n\n### Unknown Pattern Handling\n\nWhen a pattern matches no files, the tool provides suggestions:\n\n```typescript\nprivate unknownPattern(\n inventory: FileInventory,\n pattern: string\n): UnknownPattern {\n return {\n pattern,\n reason: \"matched no inventory files; the path may be ignored or not inventoried\",\n suggestions: this.suggestPaths(inventory, pattern),\n };\n}\n```\n\n### Suggestion Generation\n\nThe tool suggests similar paths when patterns fail to match:\n\n```typescript\nprivate suggestPaths(\n inventory: FileInventory,\n pattern: string\n): string[] {\n const suffix = pattern\n .replaceAll(\"*\", \"\")\n .replaceAll(\"?\", \"\")\n .split(\"/\")\n .filter(Boolean)\n .at(-1);\n if (!suffix) return [];\n return inventory.files\n .map((file) => file.path)\n .filter((path) => path.includes(suffix))\n .slice(0, 5);\n}\n```\n\n资料来源：[src/tools/group/grouping-assignment-engine.ts:150-180]()\n\n## Usage in Workflows\n\n### Initial Setup Workflow\n\n1. Run `blueprint.scan` to build file inventory\n2. Run `blueprint.group` with `mode: \"prepare\"` to get suggested groupings\n3. Review and refine the grouping plan\n4. Run `blueprint.group` with `mode: \"apply\"` to apply the plan\n5. Run `blueprint.compose` to generate documentation\n\n### Maintenance Workflow\n\n1. Run `blueprint.refresh` when project structure changes\n2. If new files are unassigned, run `blueprint.group.update`\n3. Update affected group documentation as needed\n\n资料来源：[README.md](https://github.com/engincankaya/blueprint/blob/main/README.md)\n\n## Summary\n\nThe Group Tool is a critical component in the Blueprint system that transforms raw file inventories into semantic architectural groupings. It provides:\n\n- **Pattern-based assignment** with flexible glob-like syntax\n- **Validation** ensuring complete and conflict-free groupings\n- **Edge aggregation** for cross-group relationship tracking\n- **Fallback handling** for unassigned files\n- **Integration** with the broader Blueprint workflow (scan → group → compose → refresh)\n\nThe tool operates in two modes (`prepare` and `apply`) enabling iterative group planning and reliable maintenance workflows.\n\n---\n\n\n\n## Compose Tool\n\n### 相关页面\n\n相关主题：[System Architecture](#page-system-architecture), [Group Tool](#page-group-tool)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/compose/index.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/index.ts)\n- [src/tools/compose/compose-output-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/compose-output-builder.ts)\n- [src/tools/compose/compose-artifact-writer.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/compose-artifact-writer.ts)\n- [src/tools/compose/compose.types.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/compose.types.ts)\n- [src/lib/group-note-template.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/group-note-template.ts)\n
\n\n# Compose Tool\n\n## Overview\n\nThe Compose Tool is the final stage in the Blueprint pipeline. It transforms the semantic grouping artifact into a frontend-ready JSON output and generates Markdown documentation for each group. The tool acts as the bridge between the analysis/grouping phases and the viewer UI.\n\n**Key Responsibilities:**\n\n- Builds the final `blueprint.v1` output JSON from stored grouping artifacts\n- Determin joining of groups, files, edges, docs paths, and validation data\n- Generates group documentation Markdown files from templates\n- Writes output artifacts to `.blueprint/` directory\n- Detects entrypoint files for each group\n- Validates the composed output against expected schema\n\n资料来源：[src/tools/compose/index.ts:1-18]()\n\n## Architecture\n\nThe Compose Tool is composed of several interconnected components that work together to produce the final Blueprint output.\n\n### Component Overview\n\n```mermaid\ngraph TD\n subgraph \"Compose Tool Components\"\n CT[ComposeTool]\n COB[ComposeOutputBuilder]\n CAW[ComposeArtifactWriter]\n CED[ComposeEntrypointDetector]\n end\n \n subgraph \"Input Dependencies\"\n GR[GroupingResult]\n FI[FileInventory]\n AF[AnalysisFacts]\n end\n \n subgraph \"Output Artifacts\"\n JSON[blueprint-output.json]\n MD[groups/*.md]\n end\n \n CT --> COB\n CT --> CAW\n CT --> CED\n GR --> CT\n FI --> COB\n AF --> COB\n COB --> JSON\n CAW --> MD\n```\n\n### Core Classes\n\n| Component | Purpose | Key Methods |\n|-----------|---------|-------------|\n| `ComposeTool` | Main orchestrator and entry point | `handle()` |\n| `ComposeOutputBuilder` | Constructs the final JSON output structure | `build()`, `joinGroups()`, `joinEdges()` |\n| `ComposeArtifactWriter` | Persists output to filesystem | `write()`, `writeGroupDocs()` |\n| `ComposeEntrypointDetector` | Identifies entrypoint files per group | `detect()` |\n\n资料来源：[src/tools/compose/index.ts:19-27]()\n\n## Data Flow\n\n### Pipeline Integration\n\nThe Compose Tool represents stage 3 of the Blueprint pipeline:\n\n```mermaid\ngraph LR\n subgraph \"Stage 1: Scan\"\n SI[scan.tool]\n FI[FileInventory]\n AF[AnalysisFacts]\n end\n \n subgraph \"Stage 2: Group\"\n GI[group.tool]\n GR[GroupingResult]\n end\n \n subgraph \"Stage 3: Compose\"\n CI[compose.tool]\n JSON[blueprint.v1 JSON]\n MD[Group Docs]\n end\n \n SI --> FI\n SI --> AF\n GI --> GR\n FI --> CI\n GR --> CI\n AF --> CI\n CI --> JSON\n CI --> MD\n```\n\n### Input Dependencies\n\nThe Compose Tool requires the following artifacts from previous pipeline stages:\n\n1. **GroupingResult** - Semantic file groupings with assignments\n2. **FileInventory** - Complete file listing with metadata\n3. **AnalysisFacts** - Code analysis data including imports/exports\n\n资料来源：[src/tools/compose/index.ts:28-35]()\n\n## ComposeTool Class\n\nThe `ComposeTool` class serves as the main orchestrator, delegating work to specialized components.\n\n```typescript\nexport class ComposeTool {\n constructor(\n private readonly outputBuilder: ComposeOutputBuilder,\n private readonly artifactWriter: ComposeArtifactWriter,\n ) {}\n```\n\n### The `handle()` Method\n\nThe primary entry point that processes compose requests:\n\n```typescript\nasync handle(args: ComposeArgs, store: ArtifactStore): Promise\n```\n\n**Flow:**\n\n1. Retrieves the grouping artifact from the store\n2. Validates grouping artifact existence\n3. Delegates JSON building to `ComposeOutputBuilder`\n4. Delegates artifact writing to `ComposeArtifactWriter`\n5. Returns structured tool result\n\n资料来源：[src/tools/compose/index.ts:28-48]()\n\n### Error Handling\n\nThe tool provides descriptive error messages when artifacts are missing:\n\n```typescript\nif (!grouping) {\n const entry = store.get(args.groupingArtifactId);\n return errorResult(\n entry\n ? `Grouping artifact ${args.groupingArtifactId} not found or has the wrong type`\n : `Grouping artifact ${args.groupingArtifactId} not found`,\n );\n}\n```\n\n## ComposeOutputBuilder\n\nThe `ComposeOutputBuilder` is responsible for constructing the final `blueprint.v1` output structure.\n\n### Output Structure\n\nThe builder produces a stable JSON schema containing:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `groups` | `Group[]` | All semantic groups with assigned files |\n| `files` | `File[]` | Complete file inventory |\n| `edges` | `Edge[]` | Connections between groups/files |\n| `metadata` | `Metadata` | Output generation timestamp and version |\n| `validation` | `ValidationResult` | Schema validation results |\n\n### Building Process\n\nThe output builder deterministically joins:\n\n- Groups with their assigned files\n- File metadata from inventory\n- Edge connections between groups\n- Documentation paths\n- Validation data\n\n资料来源：[src/tools/compose/compose-output-builder.ts]()\n\n## ComposeArtifactWriter\n\nThe `ComposeArtifactWriter` handles persistence of composed output to the filesystem.\n\n### Write Operations\n\n| Method | Target | Description |\n|--------|--------|-------------|\n| `writeJson()` | `.blueprint/blueprint-output.json` | Writes the main Blueprint JSON |\n| `writeGroupDocs()` | `.blueprint/groups/*.md` | Generates Markdown documentation per group |\n| `writeBrief()` | `.blueprint/brief.md` | Writes project overview documentation |\n\n### Group Documentation\n\nThe artifact writer generates Markdown files for each group using a standardized template that includes:\n\n- **Snapshot** - Quick orientation summary\n- **Responsibilities** - Ownership and scope definition\n- **Core Flow** - Runtime behavior and data flow\n- **Contracts & Invariants** - Behavior constraints\n- **Key Files** - Main source file references\n- **Change Guide** - Files that should change together\n- **Pitfalls** - Known risks and common mistakes\n\n资料来源：[src/lib/group-note-template.ts]()\n\n## ComposeEntrypointDetector\n\nThe `ComposeEntrypointDetector` identifies entrypoint files for each group by analyzing:\n\n- Export patterns\n- Module initialization files\n- Main/index file conventions\n- Dependency injection configurations\n\n## API Reference\n\n### ComposeArgs\n\n```typescript\ninterface ComposeArgs {\n groupingArtifactId: string; // ID of the grouping artifact to compose\n outputPath?: string; // Optional custom output path\n}\n```\n\n### ComposeResponseValidation\n\n```typescript\ninterface ComposeResponseValidation {\n valid: boolean;\n errors: ValidationError[];\n}\n```\n\n### ToolResult\n\nThe compose tool returns a `ToolResult` with either:\n\n- **Success**: JSON result containing the composed output path\n- **Error**: Descriptive error message explaining the failure\n\n## Usage\n\n### CLI Usage\n\n```bash\nblueprint compose \n```\n\n### MCP Tool Usage\n\n```json\n{\n \"tool\": \"blueprint.compose\",\n \"arguments\": {\n \"groupingArtifactId\": \"grouping-20240115-143022\"\n }\n}\n```\n\n## Integration with Other Tools\n\n### Tool Chain\n\n```mermaid\ngraph TD\n subgraph \"blueprint CLI\"\n SCAN[blueprint.scan]\n GROUP[blueprint.group]\n COMPOSE[blueprint.compose]\n REFRESH[blueprint.refresh]\n end\n \n SCAN --> GROUP\n GROUP --> COMPOSE\n COMPOSE --> REFRESH\n REFRESH --> GROUP\n```\n\n### Related Tools\n\n| Tool | Input to Compose | Output from Compose |\n|------|------------------|---------------------|\n| `scan` | - | `FileInventory`, `AnalysisFacts` |\n| `group` | `FileInventory`, `AnalysisFacts` | `GroupingResult` |\n| `compose` | `GroupingResult` | `blueprint.v1 JSON`, `group/*.md` |\n| `refresh` | - | Refreshes from current filesystem |\n\n## Output Schema (blueprint.v1)\n\n```typescript\ninterface BlueprintOutput {\n version: \"blueprint.v1\";\n generated: string; // ISO timestamp\n groups: Group[];\n files: FileEntry[];\n edges: Edge[];\n metadata: {\n sourceRoot: string;\n artifactCount: number;\n };\n validation: ComposeResponseValidation;\n}\n```\n\n## Best Practices\n\n1. **Always run scan before compose** - Ensure fresh analysis data\n2. **Use stable artifact IDs** - Grouping artifacts should be referenced by ID, not path\n3. **Validate output** - Check the validation results before consuming the output\n4. **Preserve group documentation** - The generated Markdown files should be version-controlled\n\n## File Structure\n\n```\n.blueprint/\n├── blueprint-output.json # Main Blueprint JSON (blueprint.v1)\n├── brief.md # Project overview\n└── groups/\n ├── group-1.md # Group-specific documentation\n ├── group-2.md\n └── ...\n\n---\n\n\n\n## Refresh Tool\n\n### 相关页面\n\n相关主题：[System Architecture](#page-system-architecture), [Compose Tool](#page-compose-tool)\n\nI cannot generate an accurate technical wiki page about the Refresh Tool based on the provided context. The requested source files are not present in the retrieved repository content:\n\n**Missing Source Files:**\n- `src/tools/refresh/index.ts`\n- `src/tools/refresh/refresh.types.ts`\n- `src/tools/group-update/index.ts`\n- `src/tools/group-update/group-update-applier.ts`\n\n**Available Context:**\nThe README.md does reference `blueprint.refresh` as a tool that \"Refreshes Blueprint state from the current filesystem snapshot\" and `blueprint.group.update` for \"Assigning unassigned files or managing empty groups after refresh,\" but the actual implementation source code for these components is not included in the provided context.\n\nTo generate an accurate wiki page, I would need access to the actual source files for the refresh and group-update tools.\n\n---\n\n\n\n## Task Context Tool\n\n### 相关页面\n\n相关主题：[System Architecture](#page-system-architecture), [MCP Server Implementation](#page-mcp-server)\n\n
\nRelevant Source Files\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/task-context.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/task-context.ts) - **File not found in provided context**\n\n
\n\n# Task Context Tool\n\nThe requested source file `src/tools/task-context.ts` was not found in the provided repository context. This wiki page cannot be generated with the specified source file.\n\n---\n\n## Available Context Files\n\nThe following files were retrieved from the repository and may provide related context:\n\n| File Path | Purpose |\n|-----------|---------|\n| `frontend/src/components/blueprint/GroupDetailPanel.tsx` | React component for displaying group details with tabs |\n| `frontend/src/components/BlueprintApp.tsx` | Main application component with tab management |\n| `src/tools/scan/scan-file-inventory-builder.ts` | File inventory classification system |\n| `src/viewer/render-html.ts` | HTML rendering utilities for the viewer |\n| `src/lib/group-docs.ts` | Group documentation structure validation |\n| `AGENTS.md` | Agent instructions for code analysis workflow |\n\n---\n\n## Next Steps\n\nTo generate an accurate wiki page for the Task Context Tool:\n\n1. Request the file `src/tools/task-context.ts` be included in the context\n2. Alternatively, search the repository for \"task-context\" or \"TaskContext\" references to identify alternative relevant files\n\n---\n\n## Related Components (From Available Context)\n\n### Group Detail Panel Architecture\n\nThe `GroupDetailPanel.tsx` component demonstrates the application's approach to displaying structured information:\n\n```typescript\n// Tab structure for group details\nconst SUB_TABS = [\n { id: 'overview', label: 'Overview' },\n { id: 'files', label: 'Files' },\n { id: 'connections', label: 'Connections' },\n { id: 'architecture', label: 'Architecture' },\n { id: 'guide', label: 'Guide' },\n]\n```\n\n### File Inventory Classification\n\nThe `scan-file-inventory-builder.ts` classifies files into categories:\n\n| Category | Criteria |\n|----------|----------|\n| `test` | `.spec.ts`, `.spec.tsx`, `test/` directories |\n| `config` | `package.json`, `.config.js`, `tsconfig.json` |\n| `documentation` | `.md` files, `docs/` directory |\n| `script` | `.sh` files, `scripts/` directory |\n| `asset` | `assets/`, `public/`, `.css`, `.svg` |\n\n资料来源：[src/tools/scan/scan-file-inventory-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-file-inventory-builder.ts)\n\n---\n\n## Recommendation\n\nProvide the `src/tools/task-context.ts` source file to enable accurate documentation generation for the Task Context Tool feature.\n\n---\n\n\n\n## Viewer Frontend\n\n### 相关页面\n\n相关主题：[System Architecture](#page-system-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [frontend/src/components/BlueprintApp.tsx](https://github.com/engincankaya/blueprint/blob/main/frontend/src/components/BlueprintApp.tsx)\n- [frontend/src/components/blueprint/GroupDetailPanel.tsx](https://github.com/engincankaya/blueprint/blob/main/frontend/src/components/blueprint/GroupDetailPanel.tsx)\n- [frontend/src/components/blueprint/BlueprintCanvas.tsx](https://github.com/engincankaya/blueprint/blob/main/frontend/src/components/blueprint/BlueprintCanvas.tsx)\n- [frontend/src/components/blueprint/BlueprintExplorer.tsx](https://github.com/engincankaya/blueprint/blob/main/frontend/src/components/blueprint/BlueprintExplorer.tsx)\n- [src/lib/agent-instructions.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/agent-instructions.ts)\n- [README.md](https://github.com/engincankaya/blueprint/blob/main/README.md)\n- [todos_120526.md](https://github.com/engincankaya/blueprint/blob/main/todos_120526.md)\n- [src/tools/compose/index.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/index.ts)\n
\n\n# Viewer Frontend\n\n## Overview\n\nThe Viewer Frontend is a lightweight React-based interface for exploring and navigating Blueprint project documentation. It provides an interactive visualization layer that renders the output generated by Blueprint's compose stage, enabling developers to browse groups, files, connections, and architectural documentation through a visual canvas or detailed panel views.\n\nThe viewer is designed as a static, self-contained HTML artifact that can be opened in any browser without requiring a dedicated HTTP server. This approach prioritizes portability and simplicity, allowing teams to commit the generated viewer HTML alongside their project documentation.\n\n## Architecture\n\n### High-Level Design\n\n```mermaid\ngraph TD\n subgraph \"Data Sources\"\n A[blueprint-output.json] --> D[BlueprintViewerService]\n B[groups/*.md] --> D\n end\n \n subgraph \"Application Layer\"\n D --> E[BlueprintApp]\n E --> F[BlueprintCanvas]\n E --> G[GroupDetailPanel]\n end\n \n subgraph \"Rendering\"\n F --> H[BlueprintExplorer]\n G --> I[SectionCard]\n G --> J[ConnectionDiagram]\n G --> K[OpenQuestionsCards]\n end\n \n E --> L[index.html]\n```\n\nThe viewer follows a service-based architecture that abstracts data access through `BlueprintViewerService`. This design supports multiple data source modes: embedded JSON data for static viewing or HTTP fetching for development workflows.\n\n### Component Hierarchy\n\n| Component | File Path | Responsibility |\n|-----------|-----------|----------------|\n| `BlueprintApp` | `frontend/src/components/BlueprintApp.tsx` | Root application container managing tab state and routing between canvas and detail views |\n| `BlueprintCanvas` | `frontend/src/components/blueprint/BlueprintCanvas.tsx` | Visual graph representation of groups and their connections |\n| `BlueprintExplorer` | `frontend/src/components/blueprint/BlueprintExplorer.tsx` | Hierarchical file browser within groups |\n| `GroupDetailPanel` | `frontend/src/components/blueprint/GroupDetailPanel.tsx` | Tabbed detail view for individual groups showing documentation sections |\n| `SectionCard` | Inline in `GroupDetailPanel.tsx` | Collapsible card component for rendering markdown content sections |\n| `ConnectionDiagram` | Referenced in `GroupDetailPanel.tsx` | Visualizes relationships between groups |\n| `OpenQuestionsCards` | Referenced in `GroupDetailPanel.tsx` | Displays open questions and extension points |\n\n## Core Components\n\n### BlueprintApp\n\nThe main application shell that orchestrates the viewer experience. It maintains the active tab state and determines which view to render based on user interaction.\n\n**State Management:**\n- `activeTab`: Tracks whether the user is viewing the canvas or a specific group's details\n- `activeGroupId`: Identifies the currently selected group for detail view\n- `overview`: Contains the complete Blueprint data including all groups, files, and connections\n\n**Tab Types:**\n- `canvas`: The full project visualization showing all groups and their relationships\n- `group`: Detailed view of a specific group with its documentation\n\n```typescript\n// Tab structure from BlueprintApp.tsx\nactiveTab.type === \"canvas\" \n ? \n : \n```\n\n### GroupDetailPanel\n\nThe primary content display component that renders detailed documentation for a selected group. It organizes content into logical sub-tabs.\n\n```mermaid\ngraph LR\n A[GroupDetailPanel] --> B[overview]\n A --> C[files]\n A --> D[connections]\n A --> E[architecture]\n A --> F[guide]\n \n B --> B1[Snapshot]\n B --> B2[Responsibilities]\n B --> B3[Key Files]\n B --> B4[Open Questions]\n \n E --> E1[Core Flow]\n E --> E2[Contracts & Invariants]\n E --> E3[Key Files]\n \n F --> F1[Change Guide]\n F --> F2[Contracts & Invariants]\n F --> F3[Pitfalls]\n F --> F4[Tests]\n F --> F5[Debugging]\n F --> F6[Extension / Open Questions]\n```\n\n**Sub-Tabs and Content:**\n\n| Sub-Tab | Content Sections | Accent Color |\n|---------|------------------|---------------|\n| `overview` | Snapshot, Responsibilities, Key Files, Open Questions | Blue (for Open Questions) |\n| `files` | Role breakdown, File tree | Default |\n| `connections` | ConnectionDiagram | Default |\n| `architecture` | Core Flow, Contracts & Invariants, Key Files | Default |\n| `guide` | Change Guide, Invariants, Pitfalls, Tests, Debugging, Extension/Open Questions | Red (Invariants), Amber (Pitfalls), Green (Extension) |\n\n### SectionCard Component\n\nA reusable collapsible component for rendering markdown content sections within the detail panel.\n\n**Features:**\n- Expandable/collapsible with smooth animation\n- Preview text when collapsed (line-clamp-1)\n- Configurable title styling with accent colors\n- Markdown content rendering via `SectionContent`\n\n**Animation Behavior:**\n```typescript\n// Entrance/exit animations\n\n```\n\n## Data Flow\n\n### Static Viewer Data Model\n\nThe viewer expects a structured JSON input that is either embedded in the HTML or fetched from the filesystem. The data model follows the `blueprint.v1` schema.\n\n```mermaid\nsequenceDiagram\n participant User as User Browser\n participant HTML as index.html\n participant Service as BlueprintViewerService\n participant Store as Artifact Store\n \n User->>HTML: Open .blueprint/index.html\n HTML->>Service: Initialize with embedded data\n Service->>Store: Parse blueprint-output.json\n Store->>HTML: Render overview\n User->>HTML: Click group\n HTML->>Service: Request group details\n Service->>Store: Load groups/*.md files\n Store->>HTML: Render GroupDetailPanel\n```\n\n### Data Source Abstraction\n\nThe viewer uses a `BlueprintDataSource` abstraction layer that supports two modes:\n\n| Mode | Data Location | Use Case |\n|------|---------------|----------|\n| Static | Embedded in `index.html` as `` closing tag risks are mitigated through escaping\n\n### CLI Commands\n\n| Command | Description | Output |\n|---------|-------------|--------|\n| `blueprint open` | Generates and opens viewer in browser | Writes `.blueprint/index.html`, opens in default browser |\n| `blueprint open --watch` | Watches for file changes and regenerates | Maintains `.blueprint/index.html` updated |\n| `blueprint render` | Generates viewer HTML | Writes `.blueprint/index.html` without opening browser |\n\n### Output Artifacts\n\n| Artifact | Path | Description |\n|----------|------|-------------|\n| `blueprint-output.json` | `.blueprint/blueprint-output.json` | Structured project graph with groups, files, and edges |\n| Group docs | `.blueprint/groups/*.md` | Individual group documentation files |\n| Brief | `.blueprint/brief.md` | Project overview and quick reference |\n| Viewer HTML | `.blueprint/index.html` | Self-contained viewer (generated) |\n\n## UI/UX Design\n\n### Visual Design System\n\nThe viewer uses a zinc-based color palette with specific accent colors for semantic meaning:\n\n| Element | Color | Usage |\n|---------|-------|-------|\n| Primary text | `zinc-100` | Main headings and titles |\n| Secondary text | `zinc-400` | Body content and descriptions |\n| Muted text | `zinc-500` | Metadata, counts |\n| Background | `zinc-950` | Application background |\n| Accent Blue | `blue-400` | Open Questions in overview |\n| Accent Red | `red-500` | Invariants in guide |\n| Accent Amber | `amber-500` | Pitfalls in guide |\n| Accent Green | `green-500` | Extension/Open Questions in guide |\n\n### Typography\n\n| Element | Size | Weight | Transform |\n|---------|------|--------|-----------|\n| Group title | `text-base` | semibold | none |\n| Section heading | `text-[11px]` | semibold | uppercase, tracking-wider |\n| Body text | `text-sm` | normal | none |\n| Code | inline code | monospace | - |\n\n### Animation Guidelines\n\nThe viewer uses Framer Motion for animations with consistent timing:\n\n| Animation | Duration | Easing |\n|-----------|----------|--------|\n| Tab transition | 0.12s | default |\n| Content fade | 0.15s | default |\n| Section expand | 0.2s | default |\n| Section collapse | 0.15s | default |\n| Chevron rotation | 0.15s | default |\n\n## Group Documentation Template\n\nGroups follow a standardized documentation template that the viewer renders:\n\n| Section | Content | Panel Location |\n|---------|---------|----------------|\n| Snapshot | Quick orientation quote | overview |\n| Responsibilities | Ownership and out-of-scope areas | overview |\n| Core Flow | Runtime behavior and data flow | architecture |\n| Contracts & Invariants | Behavior that must not be broken | architecture, guide |\n| Key Files | Main source files for the group | overview, architecture |\n| Change Guide | Files or contracts that should change together | guide |\n| Pitfalls | Known risks and common mistakes | guide |\n| Tests | Test coverage and test locations | guide |\n| Debugging | Common issues and debugging approaches | guide |\n| Extension / Open Questions | Future considerations and unresolved items | overview, guide |\n\n## AGENTS.md Integration\n\nThe viewer supports integration with the agent instruction system. The `renderBlueprintAgentsSnippet()` function generates a standardized marker-delimited section that can be injected into project documentation:\n\n```markdown\n\n\n## Blueprint MCP\n\nThis project uses Blueprint MCP for local architecture memory.\n\nBefore broad codebase exploration, read:\n\n`node_modules/blueprint-mcp-server/docs/agents.md`\n\nIf Blueprint memory exists, start with:\n\n`.blueprint/brief.md`\n\n\n```\n\nThis enables tools and agents to discover and use Blueprint documentation automatically.\n\n## Development Workflow\n\n### Running the Viewer During Development\n\n1. **Initial scan and compose:**\n ```bash\n blueprint.scan\n blueprint.group --mode prepare\n blueprint.group --mode apply\n blueprint.compose\n ```\n\n2. **Open the viewer:**\n ```bash\n blueprint open\n ```\n\n3. **Watch for changes:**\n ```bash\n blueprint open --watch\n ```\n\n### Maintenance Workflow\n\nWhen project files change significantly:\n\n1. Run `blueprint.refresh` to update the file inventory\n2. Run `blueprint.group.update` if new files are unassigned\n3. Update affected `.blueprint/groups/*.md` notes\n4. Regenerate the viewer with `blueprint open`\n\n## Browser Compatibility\n\nThe viewer is built with React 18 and Vite, targeting modern browsers with ESM support. No additional polyfills are included in the static bundle.\n\n## Security Model\n\nThe static viewer follows security best practices:\n\n- All data is embedded directly in the HTML, eliminating network-based attacks\n- JSON data is escaped before embedding to prevent XSS via `` injection\n- Special characters (`<`, `-->`, `\\u2028`, `\\u2029`) are properly escaped\n- No eval() or dynamic code execution from embedded data\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：engincankaya/blueprint\n\n摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1230090802 | https://github.com/engincankaya/blueprint | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1230090802 | https://github.com/engincankaya/blueprint | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1230090802 | https://github.com/engincankaya/blueprint | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1230090802 | https://github.com/engincankaya/blueprint | no_demo; severity=medium\n\n## 5. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1230090802 | https://github.com/engincankaya/blueprint | issue_or_pr_quality=unknown\n\n## 6. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1230090802 | https://github.com/engincankaya/blueprint | release_recency=unknown\n\n\n", "markdown_key": "blueprint", "pages": "draft", "source_refs": [ { "evidence_id": "github_repo:1230090802", "kind": "repo", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/engincankaya/blueprint" }, { "evidence_id": "art_647f8d5f3c174aef82a7cb067ad098a7", "kind": "docs", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/engincankaya/blueprint#readme" } ], "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "blueprint 说明书", "toc": [ "https://github.com/engincankaya/blueprint 项目说明书", "目录", "Blueprint Introduction", "Overview", "Architecture", "Project Memory Structure", "Workflows", "Blueprint Viewer", "Doramagic 踩坑日志" ] } }, "quality_gate": { "blocking_gaps": [], "category_confidence": "medium", "compile_status": "ready_for_review", "five_assets_present": true, "install_sandbox_verified": true, "missing_evidence": [], "next_action": "publish to Doramagic.ai project surfaces", "prompt_preview_boundary_ok": true, "publish_status": "publishable", "quick_start_verified": true, "repo_clone_verified": true, "repo_commit": "0a360b93c955d8ddb9769ad173aaf642603e9196", "repo_inspection_error": null, "repo_inspection_files": [ "package.json", "README.md", "docs/agents.md", "src/index.ts", "src/types.ts", "src/cli/index.ts", "src/services/blueprint-group-service.ts", "src/services/blueprint-viewer-service.ts", "src/languages/registry.ts", "src/languages/types.ts", "src/tools/task-context.ts", "src/tools/init-tools.ts", "src/lib/brief-builder.ts", "src/lib/agent-instructions.ts", "src/lib/blueprint-paths.ts", "src/lib/hashing.ts", "src/lib/group-note-template.ts", "src/lib/tree-sitter-loader.ts", "src/lib/group-docs.ts", "src/lib/artifact-store.ts", "src/viewer/render-html.ts", "src/languages/rust/normalizer.ts", "src/languages/typescript/normalizer.ts", "src/languages/python/normalizer.ts", "src/languages/java/normalizer.ts", "src/languages/go/normalizer.ts", "src/tools/group-update/group-update.types.ts", "src/tools/group-update/group-update-applier.ts", "src/tools/group-update/index.ts", "src/tools/group-update/group-update-validator.ts", "src/tools/refresh/refresh.types.ts", "src/tools/refresh/index.ts", "src/tools/group/grouping-plan-validator.ts", "src/tools/group/grouping.types.ts", "src/tools/group/grouping-assignment-engine.ts", "src/tools/group/index.ts", "src/tools/scan/scan-file-inventory-builder.ts", "src/tools/scan/scan-code-analysis-engine.ts", "src/tools/scan/index.ts", "src/tools/compose/compose-entrypoint-detector.ts" ], "repo_inspection_verified": true, "review_reasons": [ "community_discussion_evidence_below_public_threshold" ], "tag_count_ok": true, "unsupported_claims": [] }, "schema_version": "0.1", "user_assets": { "ai_context_pack": { "asset_id": "ai_context_pack", "filename": "AI_CONTEXT_PACK.md", "markdown": "# blueprint-mcp - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 blueprint-mcp 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `npm install -g blueprint-mcp` 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做权限沙盒试用\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：先做权限沙盒试用\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`AGENTS.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`AGENTS.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0004` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0005` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：83\n- 重要文件覆盖：17/83\n- 证据索引条目：17\n- 角色 / Skill 条目：5\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 blueprint-mcp 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 blueprint-mcp 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 blueprint-mcp 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 5 个角色 / Skill / 项目文档条目。\n\n- **Blueprint MCP Agent Rules**（project_doc）：Blueprint MCP stores local architecture memory in .blueprint/ . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/agents.md`\n- **AGENTS.md**（project_doc）：This project uses Blueprint memory. Blueprint files are the first orientation layer for every task, but they are not the source of truth. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`AGENTS.md`\n- **Blueprint MCP**（project_doc）：Blueprint gives AI coding agents a durable architecture memory for your repository. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **1- Frontend Integration Todo**（project_doc）：Bu projeye Next.js kullanmadan hafif bir frontend eklemek. Frontend, mevcut MCP/HTTP server icinden statik dosya olarak servis edilecek ve Blueprint mimarisini gorsel olarak incelemek icin kullanilacak. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`todos.md`\n- **1- MCP Native Static Viewer Refactor**（project_doc）：1- MCP Native Static Viewer Refactor 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`todos_120526.md`\n\n## 证据索引\n\n- 共索引 17 条证据。\n\n- **Blueprint MCP Agent Rules**（documentation）：Blueprint MCP stores local architecture memory in .blueprint/ . 证据：`docs/agents.md`\n- **AGENTS.md**（documentation）：This project uses Blueprint memory. Blueprint files are the first orientation layer for every task, but they are not the source of truth. 证据：`AGENTS.md`\n- **Blueprint MCP**（documentation）：Blueprint gives AI coding agents a durable architecture memory for your repository. 证据：`README.md`\n- **Package**（package_manifest）：{ \"name\": \"blueprint-mcp\", \"version\": \"0.1.3\", \"description\": \"MCP server for architecture-aware Blueprint memory using Tree-sitter\", \"type\": \"module\", \"main\": \"dist/index.js\", \"bin\": { \"blueprint-mcp\": \"dist/index.js\", \"blueprint-mcp-server\": \"dist/index.js\", \"blueprint\": \"dist/cli/index.js\" }, \"files\": \"dist\", \"docs\", \"README.md\", \"LICENSE\" , \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/engincankaya/blueprint.git\" }, \"bugs\": { \"url\": \"https://github.com/engincankaya/blueprint/issues\" }, \"homepage\": \"https://github.com/engincankaya/blueprint readme\", \"keywords\": \"mcp\", \"model-context-protocol\", \"blueprint\", \"llm\", \"coding-agent\", \"tree-sitter\" , \"license\": \"MIT\", \"scripts\"… 证据：`package.json`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`LICENSE`\n- **1- Frontend Integration Todo**（documentation）：Bu projeye Next.js kullanmadan hafif bir frontend eklemek. Frontend, mevcut MCP/HTTP server icinden statik dosya olarak servis edilecek ve Blueprint mimarisini gorsel olarak incelemek icin kullanilacak. 证据：`todos.md`\n- **1- MCP Native Static Viewer Refactor**（documentation）：1- MCP Native Static Viewer Refactor 证据：`todos_120526.md`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2022\", \"useDefineForClassFields\": true, \"lib\": \"DOM\", \"DOM.Iterable\", \"ES2022\" , \"allowJs\": false, \"skipLibCheck\": true, \"esModuleInterop\": true, \"allowSyntheticDefaultImports\": true, \"strict\": true, \"forceConsistentCasingInFileNames\": true, \"module\": \"ESNext\", \"moduleResolution\": \"Bundler\", \"baseUrl\": \".\", \"paths\": { \"@/ \": \"src/ \" }, \"resolveJsonModule\": true, \"isolatedModules\": true, \"noEmit\": true, \"jsx\": \"react-jsx\", \"types\": \"vite/client\" }, \"include\": \"src\" } 证据：`frontend/tsconfig.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2022\", \"module\": \"Node16\", \"moduleResolution\": \"Node16\", \"outDir\": \"./dist\", \"rootDir\": \"./src\", \"strict\": true, \"esModuleInterop\": true, \"skipLibCheck\": true, \"forceConsistentCasingInFileNames\": true, \"resolveJsonModule\": true, \"declaration\": true, \"sourceMap\": true, \"isolatedModules\": true }, \"include\": \"src/ / \" , \"exclude\": \"node modules\", \"dist\", \" / .test.ts\", \" / .spec.ts\" } 证据：`tsconfig.json`\n- **Index**（source_file）：Blueprint 证据：`frontend/index.html`\n- **Postcss.Config**（source_file）：module.exports = { plugins: { tailwindcss: { config: \"./frontend/tailwind.config.cjs\" }, autoprefixer: {}, }, }; 证据：`frontend/postcss.config.cjs`\n- **Tailwind.Config**（source_file）：module.exports = { darkMode: \"class\", content: { relative: true, files: \"./index.html\", \"./src/ / .{ts,tsx}\" , }, safelist: \"border-emerald-800/60\", \"bg-emerald-950/40\", \"text-emerald-200\", \"border-amber-500\", \"bg-amber-900/70\", \"text-amber-100\", \"ring-amber-500/50\", \"shadow-amber-900/40\", \"border-blue-800/60\", \"bg-blue-950/40\", \"text-blue-200\", , theme: { extend: { fontFamily: { mono: \"var --font-mono \", \"monospace\" , }, }, }, plugins: , }; 证据：`frontend/tailwind.config.cjs`\n- **Vite.Config**（source_file）：import { defineConfig } from \"vite\"; import react from \"@vitejs/plugin-react\"; import { resolve } from \"node:path\"; 证据：`frontend/vite.config.ts`\n- **!/usr/bin/env node**（source_file）：import { readFileSync, writeFileSync } from \"node:fs\"; import { join, dirname } from \"node:path\"; import { fileURLToPath } from \"node:url\"; 证据：`scripts/add-shebang.js`\n- **!/usr/bin/env node**（source_file）：/ Copies only the needed Tree-sitter WASM grammars from tree-sitter-wasms into dist/grammars/ for inclusion in the npm package. / 证据：`scripts/copy-grammars.js`\n- **Index**（source_file）：import { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\"; import { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\"; import { z } from \"zod\"; import { ArtifactStore } from \"./lib/artifact-store.js\"; import { initTools } from \"./tools/init-tools.js\"; import { handleTaskContext } from \"./tools/task-context.js\"; 证据：`src/index.ts`\n- **Types**（source_file）：/ MCP tool handler return type. Must include index signature for compatibility with CallToolResult. / export interface ToolResult { key: string : unknown; content: Array ; structuredContent?: Record ; } 证据：`src/types.ts`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/agents.md`, `AGENTS.md`, `README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/agents.md`, `AGENTS.md`, `README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **Blueprint Introduction**：importance `high`\n - source_paths: README.md, AGENTS.md, docs/agents.md\n- **CLI and Command Usage**：importance `high`\n - source_paths: src/cli/index.ts, package.json\n- **System Architecture**：importance `high`\n - source_paths: src/tools/scan/index.ts, src/tools/group/index.ts, src/tools/compose/index.ts, src/tools/refresh/index.ts, src/lib/artifact-store.ts\n- **MCP Server Implementation**：importance `high`\n - source_paths: src/index.ts, src/types.ts, src/lib/artifact-store.ts, src/tools/init-tools.ts\n- **Scan Tool**：importance `high`\n - source_paths: src/tools/scan/index.ts, src/tools/scan/scan-file-inventory-builder.ts, src/tools/scan/scan-code-analysis-engine.ts, src/lib/hashing.ts\n- **Group Tool**：importance `high`\n - source_paths: src/tools/group/index.ts, src/tools/group/grouping-assignment-engine.ts, src/tools/group/grouping-plan-validator.ts, src/tools/group/grouping.types.ts\n- **Compose Tool**：importance `high`\n - source_paths: src/tools/compose/index.ts, src/tools/compose/compose-output-builder.ts, src/tools/compose/compose-artifact-writer.ts, src/tools/compose/compose.types.ts, src/lib/group-note-template.ts\n- **Refresh Tool**：importance `high`\n - source_paths: src/tools/refresh/index.ts, src/tools/refresh/refresh.types.ts, src/tools/group-update/index.ts, src/tools/group-update/group-update-applier.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `0a360b93c955d8ddb9769ad173aaf642603e9196`\n- inspected_files: `package.json`, `README.md`, `docs/agents.md`, `src/index.ts`, `src/types.ts`, `src/cli/index.ts`, `src/services/blueprint-group-service.ts`, `src/services/blueprint-viewer-service.ts`, `src/languages/registry.ts`, `src/languages/types.ts`, `src/tools/task-context.ts`, `src/tools/init-tools.ts`, `src/lib/brief-builder.ts`, `src/lib/agent-instructions.ts`, `src/lib/blueprint-paths.ts`, `src/lib/hashing.ts`, `src/lib/group-note-template.ts`, `src/lib/tree-sitter-loader.ts`, `src/lib/group-docs.ts`, `src/lib/artifact-store.ts`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:1230090802 | https://github.com/engincankaya/blueprint | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:1230090802 | https://github.com/engincankaya/blueprint | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:1230090802 | https://github.com/engincankaya/blueprint | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:1230090802 | https://github.com/engincankaya/blueprint | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:1230090802 | https://github.com/engincankaya/blueprint | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo:1230090802 | https://github.com/engincankaya/blueprint | release_recency=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n", "summary": "给宿主 AI 的上下文和工作边界。", "title": "AI Context Pack / 带给我的 AI" }, "boundary_risk_card": { "asset_id": "boundary_risk_card", "filename": "BOUNDARY_RISK_CARD.md", "markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：engincankaya/blueprint\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- review_required: community_discussion_evidence_below_public_threshold\n\n## 项目专属踩坑\n\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n- 存在评分风险（medium）：风险会影响是否适合普通用户安装。 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- issue/PR 响应质量未知（low）：用户无法判断遇到问题后是否有人维护。 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n", "summary": "安装、权限、验证和推荐前风险。", "title": "Boundary & Risk Card / 边界与风险卡" }, "human_manual": { "asset_id": "human_manual", "filename": "HUMAN_MANUAL.md", "markdown": "# https://github.com/engincankaya/blueprint 项目说明书\n\n生成时间：2026-05-16 00:06:34 UTC\n\n## 目录\n\n- [Blueprint Introduction](#page-blueprint-introduction)\n- [CLI and Command Usage](#page-cli-usage)\n- [System Architecture](#page-system-architecture)\n- [MCP Server Implementation](#page-mcp-server)\n- [Scan Tool](#page-scan-tool)\n- [Group Tool](#page-group-tool)\n- [Compose Tool](#page-compose-tool)\n- [Refresh Tool](#page-refresh-tool)\n- [Task Context Tool](#page-task-context-tool)\n- [Viewer Frontend](#page-viewer-frontend)\n\n\n\n## Blueprint Introduction\n\n### 相关页面\n\n相关主题：[CLI and Command Usage](#page-cli-usage), [System Architecture](#page-system-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/engincankaya/blueprint/blob/main/README.md)\n- [AGENTS.md](https://github.com/engincankaya/blueprint/blob/main/AGENTS.md)\n- [src/lib/agent-instructions.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/agent-instructions.ts)\n- [src/tools/scan/scan-file-inventory-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-file-inventory-builder.ts)\n- [src/tools/scan/scan-code-analysis-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-code-analysis-engine.ts)\n
\n\n# Blueprint Introduction\n\nBlueprint is a local architecture memory system designed to help developers and AI agents understand, navigate, and work effectively with software projects. It generates structured project graphs from source code, enabling faster orientation and more accurate context when making changes.\n\n## Overview\n\nBlueprint solves the common problem of diving into unfamiliar or complex codebases by creating a persistent, queryable layer of architectural knowledge. Rather than reading through thousands of files to understand a system, developers can leverage Blueprint's structured output to quickly identify relevant components, dependencies, and architectural patterns.\n\n### Core Purpose\n\nThe primary goals of Blueprint are:\n\n1. **Structured Project Graph Generation** - Automatically analyze codebase structure and generate organized representations of files, symbols, imports, and dependencies\n2. **Architectural Memory Persistence** - Store architecture knowledge in a local `.blueprint/` directory that can be version-controlled or kept as local developer memory\n3. **Agent-Friendly Orientation** - Provide AI agents with reliable starting points for understanding projects before diving into source code\n4. **Deterministic Maintenance** - Keep architecture documentation synchronized with actual code through automated refresh workflows\n\n资料来源：[README.md:1-20]()\n\n## Architecture\n\n### System Components\n\nBlueprint consists of several integrated components that work together to analyze and document projects:\n\n| Component | Purpose |\n|-----------|---------|\n| **Scan Engine** | Builds file inventory and performs code analysis |\n| **Group Module** | Organizes files into semantic architectural groups |\n| **Compose Module** | Generates final Blueprint output and Markdown documentation |\n| **Viewer** | React-based UI for visualizing project architecture |\n| **MCP Server** | Model Context Protocol integration for AI agent workflows |\n\n资料来源：[README.md:40-60]()\n\n### File Inventory System\n\nThe scan engine analyzes the codebase using a categorization system that classifies files into meaningful types:\n\n```mermaid\ngraph TD\n A[File System] --> B[Scan Engine]\n B --> C{File Type Detection}\n C -->|Source Code| D[parseable]\n C -->|Config| E[config]\n C -->|Documentation| F[documentation]\n C -->|Test| G[test]\n C -->|Asset| H[asset]\n C -->|Lockfile| I[lockfile]\n C -->|Script| J[script]\n```\n\nThe categorization logic uses path segment analysis and file extension matching:\n\n```typescript\n// From src/tools/scan/scan-file-inventory-builder.ts\nif (segments.includes(\"test\") || segments.includes(\"tests\")) {\n return \"test\";\n}\nif (base.endsWith(\".md\") || language === \"markdown\") {\n return \"documentation\";\n}\nif (segments.includes(\"assets\") || [\"html\", \"css\", \"svg\"].includes(language)) {\n return \"asset\";\n}\n```\n\n资料来源：[src/tools/scan/scan-file-inventory-builder.ts:1-50]()\n\n### Code Analysis Engine\n\nThe analysis engine performs deep parsing on supported languages to extract symbols, imports, and exports:\n\n```typescript\n// From src/tools/scan/scan-code-analysis-engine.ts\ninterface AnalysisFacts {\n inventoryArtifactId: string;\n rootPath: string;\n files: Record;\n symbols: Record;\n imports: Import[];\n exports: Export[];\n dependencies: Dependency[];\n parseErrors: ParseError[];\n}\n```\n\nThe engine tracks validation state to ensure complete analysis:\n\n```typescript\ninterface Validation {\n isComplete: boolean;\n inventoryFiles: number;\n parseableFiles: number;\n parsedFiles: number;\n parseErrors: number;\n unaccountedFiles: string[];\n}\n```\n\n资料来源：[src/tools/scan/scan-code-analysis-engine.ts:1-80]()\n\n## Project Memory Structure\n\nBlueprint stores architecture memory in a `.blueprint/` directory with the following structure:\n\n### Generated Artifacts\n\n| File | Purpose |\n|------|---------|\n| `brief.md` | Project overview, architectural groups, and routing hints |\n| `groups/*.md` | Detailed documentation for each architectural group |\n| `blueprint-output.json` | Structured project graph in JSON format |\n| `refresh-scan.json` | Filesystem hash snapshot for deterministic refreshes |\n\n资料来源：[README.md:25-35]()\n\n### Group Documentation Template\n\nEach group document follows a consistent structure:\n\n- **Snapshot** - Quick orientation and high-level description\n- **Responsibilities** - Ownership boundaries and out-of-scope areas\n- **Core Flow** - Runtime behavior and data flow explanation\n- **Contracts & Invariants** - Behavior that must not be broken\n- **Key Files** - Main source files for the group\n- **Change Guide** - Files or contracts that should change together\n- **Pitfalls** - Known risks and common mistakes\n- **Tests** - Most relevant verification points\n- **Debugging** - Failure-mode hints\n- **Extension / Open Questions** - Uncertainty and known gaps\n\n资料来源：[AGENTS.md:40-65]()\n\n## Workflows\n\n### Initial Setup Workflow\n\n```mermaid\ngraph LR\n A[blueprint scan] --> B[blueprint group mode: prepare]\n B --> C[Create grouping plan]\n C --> D[blueprint group mode: apply]\n D --> E[blueprint compose]\n E --> F[.blueprint/ memory created]\n F --> G[AGENTS.md patched]\n```\n\nTo initialize Blueprint for a project:\n\n1. Run `blueprint.scan` to build file inventory and code analysis\n2. Run `blueprint.group` with `mode: \"prepare\"` to analyze grouping options\n3. Create a compact grouping plan from the prepare output\n4. Run `blueprint.group` with `mode: \"apply\"` to apply the grouping\n5. Run `blueprint.compose` to write the final Blueprint output\n\n资料来源：[README.md:55-75]()\n\n### Maintenance Workflow\n\nWhen project changes add, move, delete, or substantially change files:\n\n```mermaid\ngraph TD\n A[Code Changes] --> B[Run blueprint.refresh]\n B --> C{New files unassigned?}\n C -->|Yes| D[Run blueprint.group.update]\n C -->|No| E[Update affected group docs]\n D --> E\n E --> F[Architecture docs synchronized]\n```\n\n资料来源：[README.md:75-85]()\n\n## Blueprint Viewer\n\nBlueprint includes a lightweight React/Vite viewer for visualizing project architecture.\n\n### Viewing Generated Blueprint\n\nTo view a generated Blueprint:\n\n```bash\nblueprint open\n```\n\nThis command:\n1. Reads `.blueprint/blueprint-output.json` and `.blueprint/groups/*.md`\n2. Writes a self-contained `.blueprint/index.html`\n3. Opens it in the default browser\n\n### Static Viewer Features\n\nThe viewer generates self-contained HTML with:\n- Inline JavaScript\n- Inline CSS\n- Securely embedded JSON data\n\n```mermaid\ngraph TD\n A[Blueprint Data] --> B[XSS/Content Escape]\n B --> C[` closing tag injection risks.\n\n资料来源：[todos_120526.md:12-15]()\n\n## Agent Integration\n\nBlueprint CLI integrates with AI agents through `AGENTS.md` files that contain marker-based patches. The system uses stable section headings for navigation:\n\n- `Core Flow`\n- `Contracts & Invariants`\n- `Change Guide`\n- `Pitfalls`\n- `Tests`\n\n资料来源：[AGENTS.md:4-10]()\n\n### Agent Budget Guidelines\n\nWhen working with Blueprint in agentic contexts:\n\n| Resource | Budget Policy |\n| --- | --- |\n| `.blueprint/brief.md` | Always read |\n| Blueprint Markdown search | Always prefer early |\n| Group docs | Read targeted excerpts first |\n| Full group docs | Exception, not default |\n\n资料来源：[AGENTS.md:1-7]()\n\n## Development Commands\n\nFor developers working on Blueprint itself:\n\n```bash\nnpm install # Install dependencies\nnpm run build # Build the project\nnpm run lint # Run linter\nnpm test # Run tests\n```\n\n资料来源：[README.md:75-80]()\n\n## Command Output Structure\n\nBlueprint generates structured output files in the `.blueprint/` directory:\n\n| File | Purpose |\n| --- | --- |\n| `brief.md` | Project overview and key architectural decisions |\n| `blueprint-output.json` | Structured project graph |\n| `groups/*.md` | Individual group documentation |\n| `file-inventory.json` | Complete file listing |\n| `refresh-scan.json` | Filesystem state snapshot |\n\n资料来源：[README.md:49-53]()\n\n## Language Support\n\nThe CLI uses Tree-sitter for deep code analysis of supported languages:\n\n| Language | Support Level |\n| --- | --- |\n| TypeScript / JavaScript | Full symbol and import analysis |\n| Python | Full symbol and import analysis |\n| Go | Full symbol and import analysis |\n| Rust | Full symbol and import analysis |\n| Java | Full symbol and import analysis |\n| Other languages | Metadata only (no deep analysis) |\n\n资料来源：[README.md:81-88]()\n\n## Configuration Notes\n\n- `.blueprint/` is local generated memory by default\n- Teams decide whether to commit to version control or add to `.gitignore`\n- Source code remains the single source of truth\n- Do not edit `blueprint-output.json` manually\n\n资料来源：[README.md:53-56]()\n\n## Error Handling\n\nWhen commands encounter issues:\n\n| Scenario | Behavior |\n| --- | --- |\n| Missing inventory artifact | Returns error with artifact ID and expected type |\n| Unparseable files | Marked as `metadata-only` and skipped |\n| Pattern matching failure | Reports unmatched files with suggested paths |\n| Missing group documentation | Displays placeholder message in viewer |\n\n资料来源：[src/tools/scan/scan-code-analysis-engine.ts:15-22]()\n\n## Summary\n\nThe Blueprint CLI provides a comprehensive toolkit for code comprehension and documentation:\n\n1. **Scan** creates a complete inventory of project files\n2. **Group** organizes files into semantic clusters\n3. **Compose** generates documentation and updates agent guidance\n4. **Refresh** keeps the documentation synchronized with filesystem changes\n5. **Open** provides a self-contained HTML viewer\n\nAll operations are designed to enhance developer understanding without modifying source code or requiring a persistent HTTP server.\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Scan Tool](#page-scan-tool), [Group Tool](#page-group-tool), [Compose Tool](#page-compose-tool), [Refresh Tool](#page-refresh-tool)\n\n
\nRelevant Source Files\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/engincankaya/blueprint/blob/main/README.md)\n- [AGENTS.md](https://github.com/engincankaya/blueprint/blob/main/AGENTS.md)\n- [src/tools/scan/scan-file-inventory-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-file-inventory-builder.ts)\n- [src/tools/scan/scan-code-analysis-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-code-analysis-engine.ts)\n- [src/tools/group/grouping-assignment-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/group/grouping-assignment-engine.ts)\n- [src/viewer/render-html.ts](https://github.com/engincankaya/blueprint/blob/main/src/viewer/render-html.ts)\n- [frontend/src/components/blueprint/GroupDetailPanel.tsx](https://github.com/engincankaya/blueprint/blob/main/frontend/src/components/blueprint/GroupDetailPanel.tsx)\n- [frontend/src/components/BlueprintApp.tsx](https://github.com/engincankaya/blueprint/blob/main/frontend/src/components/BlueprintApp.tsx)\n
\n\n# System Architecture\n\n## Overview\n\nBlueprint is a documentation and code organization system that generates a structured \"memory\" layer for software projects. Rather than modifying source code, it creates an orientation layer stored in the `.blueprint/` directory, enabling AI agents and developers to understand project structure without reading every file.\n\n资料来源：[README.md]()\n\nThe system operates as a **transport-agnostic architecture** that can function in two modes:\n\n1. **Static mode**: Embeds data directly into `index.html` for self-contained viewing\n2. **HTTP mode**: Serves data via API for interactive development environments\n\n资料来源：[todos_120526.md]()\n\n## Core Components\n\nBlueprint's architecture consists of four primary tool layers, each responsible for a distinct phase of the documentation lifecycle.\n\n### Tool Layer Architecture\n\n```mermaid\ngraph TD\n A[blueprint scan] --> B[blueprint group]\n B --> C[blueprint compose]\n C --> D[blueprint refresh]\n \n A1[File Inventory] --> B1[Grouping Assignment]\n B1 --> C1[Memory Output]\n C1 --> D1[State Refresh]\n \n A2[Code Analysis] --> B2[Pattern Validation]\n B2 --> C2[Markdown Notes]\n C2 --> D2[Incremental Updates]\n```\n\n### Component Responsibilities\n\n| Component | Purpose | Key Files |\n|-----------|---------|-----------|\n| **Scanner** | Builds file inventory and parses code for symbols, imports, exports | `src/tools/scan/*.ts` |\n| **Grouper** | Assigns files to semantic groups using glob patterns | `src/tools/group/*.ts` |\n| **Composer** | Writes `.blueprint/` memory and patches `AGENTS.md` | `src/tools/compose/*.ts` |\n| **Refresher** | Refreshes Blueprint state from current filesystem | `src/tools/refresh/*.ts` |\n\n资料来源：[README.md]()\n\n## File Inventory System\n\nThe scanning engine builds a comprehensive file inventory by categorizing each file in the project.\n\n### File Categorization Logic\n\nFiles are classified into categories based on path segments, file extensions, and naming patterns:\n\n```mermaid\ngraph LR\n A[File Path] --> B{Extension Check}\n B -->|spec.ts / test.ts| C[test]\n B -->|package-lock.json| D[lockfile]\n B -->|package.json / .config.ts| E[config]\n B -->|readme.md / *.md| F[documentation]\n B -->|.sh / scripts/| G[script]\n B -->|.svg / css / assets/| H[asset]\n```\n\n资料来源：[src/tools/scan/scan-file-inventory-builder.ts]()\n\n### Category Detection Rules\n\n| Category | Detection Criteria |\n|----------|---------------------|\n| `test` | File ends with `.spec.ts`, `.test.ts`, or path contains `test`, `tests`, `__tests__` |\n| `lockfile` | `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `cargo.lock`, `poetry.lock` |\n| `config` | `.gitignore`, `package.json`, `tsconfig.json`, `*.config.js/ts/mjs/cjs`, or language in `json/yaml/toml/xml` |\n| `documentation` | Path contains `docs`, `readme.md`, or any `.md` file |\n| `script` | Path contains `scripts`, shell language, or `.sh` extension |\n| `asset` | Path contains `assets` or `public`, or language in `html/css/scss/svg` |\n\n资料来源：[src/tools/scan/scan-file-inventory-builder.ts]()\n\n## Code Analysis Engine\n\nThe analysis engine parses all \"parseable\" files to extract structural information.\n\n### Analysis Facts Model\n\n```typescript\ninterface AnalysisFacts {\n inventoryArtifactId: string;\n rootPath: string;\n files: Record;\n symbols: Record;\n imports: ImportStatement[];\n exports: ExportStatement[];\n dependencies: Dependency[];\n unresolvedImports: UnresolvedImport[];\n parseErrors: ParseError[];\n summary: AnalysisSummary;\n validation: ValidationStatus;\n}\n```\n\n资料来源：[src/tools/scan/scan-code-analysis-engine.ts]()\n\n### Summary Tracking\n\nThe engine maintains aggregate statistics during parsing:\n\n| Metric | Description |\n|--------|-------------|\n| `totalFiles` | Total files in inventory |\n| `parseableFiles` | Files eligible for parsing |\n| `parsedFiles` | Successfully parsed files |\n| `metadataOnlyFiles` | Files with only metadata (binary, etc.) |\n| `symbols` | Extracted function/class/variable declarations |\n| `imports` | Import statements analyzed |\n| `exports` | Export statements analyzed |\n| `parseErrors` | Files that failed to parse |\n\n资料来源：[src/tools/scan/scan-code-analysis-engine.ts]()\n\n## Group Assignment System\n\nFiles are assigned to semantic groups using glob-based pattern matching.\n\n### Pattern Matching Engine\n\nThe grouper supports wildcard patterns for matching file paths:\n\n```mermaid\ngraph TD\n A[Pattern] --> B{Character}\n B -->|glob `*`| C[Match any chars except /]\n B -->|glob `?`| D[Match single char except /]\n B -->|literal| E[Exact match required]\n C --> F[Build Regex]\n D --> F\n E --> F\n F --> G[^pattern$]\n```\n\n资料来源：[src/tools/group/grouping-assignment-engine.ts]()\n\n### Grouped File Structure\n\n```typescript\ninterface GroupedFile {\n fileId: string;\n path: string;\n category: string;\n language: string;\n importance: \"critical\" | \"important\" | \"standard\" | \"unknown\";\n role: string;\n}\n```\n\n资料来源：[src/tools/group/grouping-assignment-engine.ts]()\n\n### Validation and Suggestions\n\nWhen patterns fail to match any files, the system provides diagnostic information:\n\n```typescript\ninterface UnknownPattern {\n pattern: string;\n reason: string;\n suggestions: string[];\n}\n```\n\nThe suggester extracts suffixes from patterns and finds similar paths in the inventory.\n\n资料来源：[src/tools/group/grouping-assignment-engine.ts]()\n\n## Group Documentation Template\n\nEach group follows a canonical documentation structure that agents can navigate using stable headings.\n\n### Section Structure\n\n```mermaid\ngraph LR\n A[Snapshot] --> B[Responsibilities]\n B --> C[Core Flow]\n C --> D[Contracts & Invariants]\n D --> E[Key Files]\n E --> F[Change Guide]\n F --> G[Pitfalls]\n G --> H[Tests]\n```\n\n资料来源：[AGENTS.md]()\n\n| Section | Purpose |\n|---------|---------|\n| `Snapshot` | Quick orientation for the group |\n| `Responsibilities` | Ownership and out-of-scope areas |\n| `Core Flow` | Runtime behavior and data flow |\n| `Contracts & Invariants` | Behavior that must not be broken |\n| `Key Files` | Main source files for the group |\n| `Change Guide` | Files or contracts that should change together |\n| `Pitfalls` | Known risks and common mistakes |\n| `Tests` | Testing guidance |\n\n资料来源：[AGENTS.md]()\n\n## Frontend Component Architecture\n\nThe Blueprint frontend is a React-based application with a tabbed interface.\n\n### Application Structure\n\n```mermaid\ngraph TD\n A[BlueprintApp] --> B[Tab Bar]\n A --> C[Main Content Area]\n \n B --> D[Canvas Tab]\n B --> E[Group Detail Tabs]\n \n C --> D\n C --> E\n \n E --> F[GroupDetailPanel]\n F --> G[Overview]\n F --> H[Files]\n F --> I[Connections]\n F --> J[Architecture]\n F --> K[Guide]\n```\n\n资料来源：[frontend/src/components/BlueprintApp.tsx]()\n资料来源：[frontend/src/components/blueprint/GroupDetailPanel.tsx]()\n\n### Sub-Tab Content Mapping\n\n| Sub-Tab | Content Components |\n|---------|--------------------|\n| `overview` | Snapshot, Responsibilities, Key Files, Open Questions |\n| `files` | Role breakdown tags, File tree with icons |\n| `connections` | ConnectionDiagram visualization |\n| `architecture` | CoreFlow, ContractsAndInvariants, KeyFiles cards |\n| `guide` | ChangeGuide, Pitfalls, Tests, Debugging, OpenQuestions |\n\n资料来源：[frontend/src/components/blueprint/GroupDetailPanel.tsx]()\n\n### SectionCard Component\n\nThe `SectionCard` component provides collapsible content sections with accent colors:\n\n```typescript\ninterface SectionCardProps {\n title: string;\n content: string;\n accent?: 'amber' | 'red' | 'green' | 'blue' | 'zinc';\n defaultOpen?: boolean;\n index?: number;\n}\n```\n\n| Accent Color | Use Case |\n|--------------|----------|\n| `blue` | Default sections |\n| `amber` | Pitfalls and warnings |\n| `red` | Invariants (critical constraints) |\n| `green` | Extension open questions |\n| `zinc` | Standard content |\n\n资料来源：[frontend/src/components/blueprint/GroupDetailPanel.tsx]()\n\n## Static Viewer Rendering\n\nThe HTML renderer creates self-contained viewer files by inlining assets.\n\n### Inlining Process\n\n```mermaid\ngraph LR\n A[Template HTML] --> B[Inline CSS]\n B --> C[Inline JS]\n C --> D[Embed JSON Data]\n D --> E[Escape & Validate]\n E --> F[index.html]\n```\n\n资料来源：[src/viewer/render-html.ts]()\n\n### Asset Inlining Strategy\n\nThe renderer processes three asset types:\n\n| Asset Type | Regex Pattern | Replacement |\n|------------|---------------|-------------|\n| CSS | `` | `` |\n| Module JS (crossorigin) | `` |\n| Module JS | `` |\n\n资料来源：[src/viewer/render-html.ts]()\n\n### Data Embedding Security\n\nJSON data is embedded using `\n```\n\n资料来源：[todos_120526.md]()\n\n## Workflow State Machine\n\n### Initial Workflow\n\n```mermaid\ngraph TD\n A[Start] --> B[blueprint scan]\n B --> C[blueprint group prepare]\n C --> D{Create grouping plan}\n D --> E[blueprint group apply]\n E --> F[blueprint compose]\n F --> G[Complete]\n \n H[hydrate group docs] -.-> G\n```\n\n### Maintenance Workflow\n\n```mermaid\ngraph TD\n A[Project Change] --> B[blueprint refresh]\n B --> C{New unassigned files?}\n C -->|Yes| D[blueprint group update]\n C -->|No| E[Update affected group docs]\n D --> E\n E --> F[Complete]\n```\n\n资料来源：[README.md]()\n\n## Artifact Storage\n\nThe system uses typed artifact storage for persisting scan results, groupings, and composed output.\n\n### Artifact Types\n\n| Artifact | Purpose |\n|----------|---------|\n| `fileInventory` | Complete file listing with categories |\n| `codeAnalysis` | Symbols, imports, exports from parsing |\n| `groupingAssignment` | File-to-group mappings |\n| `groupDocAnalysis` | Canonical section validation |\n\n资料来源：[src/lib/artifact-store.ts]()\n\n### Validation Status\n\nEach analysis maintains a validation record:\n\n```typescript\ninterface ValidationStatus {\n isComplete: boolean;\n inventoryFiles: number;\n parseableFiles: number;\n parsedFiles: number;\n metadataOnlyFiles: number;\n skippedMetadataOnlyFiles: number;\n parseErrors: number;\n unaccountedFiles: string[];\n}\n```\n\n资料来源：[src/tools/scan/scan-code-analysis-engine.ts]()\n\n## Key Design Principles\n\n1. **Source of Truth**: Source code remains the source of truth; `.blueprint/` is generated memory only\n2. **Local by Default**: Blueprint memory is stored in `.blueprint/` (not in `node_modules`)\n3. **Transport Agnostic**: Supports both static HTML and HTTP API modes\n4. **Safe Embedding**: JSON data is safely escaped before HTML embedding\n5. **Canonical Structure**: Group docs follow a stable template for consistent navigation\n\n资料来源：[README.md]()\n资料来源：[todos_120526.md]()\n\n---\n\n\n\n## MCP Server Implementation\n\n### 相关页面\n\n相关主题：[System Architecture](#page-system-architecture), [Task Context Tool](#page-task-context-tool)\n\n
\nRelated Source Files\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/scan/scan-code-analysis-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-code-analysis-engine.ts)\n- [src/tools/scan/scan-file-inventory-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-file-inventory-builder.ts)\n- [src/lib/agent-instructions.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/agent-instructions.ts)\n- [AGENTS.md](https://github.com/engincankaya/blueprint/blob/main/AGENTS.md)\n- [README.md](https://github.com/engincankaya/blueprint/blob/main/README.md)\n
\n\n# MCP Server Implementation\n\nThe Blueprint MCP Server provides a Model Context Protocol interface for AI agents to interact with codebase architecture memory. It exposes tools for scanning codebases, grouping files semantically, composing documentation, and maintaining architectural state across project changes.\n\n## Overview\n\nBlueprint operates as a local architecture memory layer that sits above source code. The MCP Server acts as the bridge between AI agents and the Blueprint tooling, enabling deterministic project understanding without manual documentation overhead.\n\n```mermaid\ngraph TD\n A[AI Agent] -->|MCP Protocol| B[Blueprint MCP Server]\n B -->|blueprint.scan| C[File Inventory Builder]\n B -->|blueprint.group| D[Semantic Grouper]\n B -->|blueprint.compose| E[Documentation Writer]\n B -->|blueprint.refresh| F[State Refresher]\n C -->|Artifacts| G[blueprint-output.json]\n D -->|Groupings| H[groups/*.md]\n E -->|Memory| G & H\n F -->|Sync| G & H\n```\n\n资料来源：[README.md:1-15]()\n\n## MCP Tools Architecture\n\n### Available Tools\n\n| Tool | Purpose | Output |\n|------|---------|--------|\n| `blueprint.scan` | Builds file inventory and code analysis artifacts | File metadata, symbols, imports |\n| `blueprint.group` | Prepares or applies semantic file grouping | Group definitions |\n| `blueprint.compose` | Writes Blueprint output and Markdown notes | `.blueprint/` memory files |\n| `blueprint.refresh` | Refreshes state from current filesystem | Updated JSON state |\n| `blueprint.group.update` | Assigns unassigned files or manages empty groups | Updated groupings |\n\n资料来源：[README.md:30-36]()\n\n### Tool Workflow\n\n```mermaid\ngraph LR\n A[Initial Setup] --> B[scan]\n B --> C[group prepare]\n C --> D[Review Plan]\n D --> E[group apply]\n E --> F[compose]\n F --> G[Memory Written]\n \n H[Maintenance] --> I[refresh]\n I --> J{Unassigned Files?}\n J -->|Yes| K[group.update]\n J -->|No| L[Update Docs Only]\n K --> M[Update group/*.md]\n```\n\n#### Initial Workflow\n\n1. `blueprint.scan` - Builds file inventory and code analysis artifacts\n2. `blueprint.group` with `mode: \"prepare\"` - Prepares grouping plan\n3. Review the compact grouping plan output\n4. `blueprint.group` with `mode: \"apply\"` - Applies the grouping\n5. `blueprint.compose` - Writes `.blueprint/` memory and patches `AGENTS.md`\n\n资料来源：[README.md:18-27]()\n\n#### Maintenance Workflow\n\n1. Run `blueprint.refresh` when project changes occur\n2. If new files are unassigned, run `blueprint.group.update`\n3. Update only affected `.blueprint/groups/*.md` notes when architecture changes\n\n资料来源：[README.md:29-33]()\n\n## Scan Tool Implementation\n\n### File Inventory Builder\n\nThe `scan-file-inventory-builder.ts` handles filesystem traversal and file classification. It categorizes files into types based on naming conventions and path segments.\n\n#### File Type Classification\n\n| Type | Detection Criteria |\n|------|---------------------|\n| `test` | `test.spec.ts`, `test.spec.tsx`, `test.spec.js`, `test.spec.jsx`, `/test/`, `/tests/`, `__tests__/` |\n| `lockfile` | `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `cargo.lock`, `poetry.lock` |\n| `config` | `.gitignore`, `package.json`, `tsconfig.json`, `*.config.js`, `*.config.ts`, language in `[json, yaml, toml, xml]` |\n| `documentation` | `/docs/`, `readme.md`, `*.md`, language `markdown` |\n| `script` | `/scripts/`, language `shell`, `*.sh` |\n| `asset` | `/assets/`, `/public/`, language in `[html, css, scss, svg]` |\n| `generated` | `/generated/`, `/__generated__/` |\n\n资料来源：[src/tools/scan/scan-file-inventory-builder.ts:1-80]()\n\n### Code Analysis Engine\n\nThe `scan-code-analysis-engine.ts` performs deep analysis on parseable files, extracting symbols, imports, exports, and dependencies.\n\n#### Analysis Facts Model\n\n```typescript\ninterface AnalysisFacts {\n inventoryArtifactId: string;\n rootPath: string;\n files: Record;\n symbols: Record;\n imports: ImportStatement[];\n exports: ExportStatement[];\n dependencies: Dependency[];\n unresolvedImports: UnresolvedImport[];\n parseErrors: ParseError[];\n summary: {\n totalFiles: number;\n parseableFiles: number;\n metadataOnlyFiles: number;\n plannedFiles: number;\n parsedFiles: number;\n symbols: number;\n imports: number;\n exports: number;\n dependencies: number;\n parseErrors: number;\n };\n validation: AnalysisValidation;\n}\n```\n\n资料来源：[src/tools/scan/scan-code-analysis-engine.ts:20-40]()\n\n#### Language Support\n\nBlueprint uses Tree-sitter analysis for:\n\n| Language | Symbol Analysis | Import/Export Analysis |\n|----------|-----------------|------------------------|\n| TypeScript/JavaScript | ✅ Full | ✅ Full |\n| Python | ✅ Full | ✅ Full |\n| Go | ✅ Full | ✅ Full |\n| Rust | ✅ Full | ✅ Full |\n| Java | ✅ Full | ✅ Full |\n| Other | Metadata only | Metadata only |\n\n资料来源：[README.md:60-65]()\n\n### Validation Model\n\n```typescript\ninterface AnalysisValidation {\n isComplete: boolean;\n inventoryFiles: number;\n parseableFiles: number;\n parsedFiles: number;\n metadataOnlyFiles: number;\n skippedMetadataOnlyFiles: number;\n parseErrors: number;\n unaccountedFiles: string[];\n}\n```\n\n资料来源：[src/tools/scan/scan-code-analysis-engine.ts:42-50]()\n\n## Agent Integration\n\n### AGENTS.md Integration\n\nThe MCP Server integrates with project `AGENTS.md` files using marker-delimited snippets. When `blueprint.compose` runs, it patches the `AGENTS.md` without overwriting existing project instructions.\n\n#### Snippet Format\n\n```markdown\n\n\n## Blueprint MCP\n\nThis project uses Blueprint MCP for local architecture memory.\n\nBefore broad codebase exploration, read:\n\n`node_modules/blueprint-mcp-server/docs/agents.md`\n\nIf Blueprint memory exists, start with:\n\n`.blueprint/brief.md`\n\n\n```\n\n资料来源：[src/lib/agent-instructions.ts:15-30]()\n\n### Agent Instruction Rendering\n\n```typescript\nexport function renderBlueprintAgentsSnippet(): string {\n return [\n beginMarker,\n \"\",\n \"## Blueprint MCP\",\n \"\",\n \"This project uses Blueprint MCP for local architecture memory.\",\n \"\",\n \"Before broad codebase exploration, read:\",\n \"\",\n \"`node_modules/blueprint-mcp-server/docs/agents.md`\",\n \"\",\n \"If Blueprint memory exists, start with:\",\n \"\",\n \"`.blueprint/brief.md`\",\n \"\",\n endMarker,\n ].join(\"\\n\");\n}\n```\n\n资料来源：[src/lib/agent-instructions.ts:40-58]()\n\n## Blueprint Memory Structure\n\n```mermaid\ngraph TD\n subgraph \".blueprint/\"\n A[blueprint-output.json] -->|Deterministic| B[Group definitions]\n A -->|Deterministic| C[File inventory]\n A -->|Deterministic| D[Analysis facts]\n E[brief.md] -->|Overview| F[Architectural groups]\n G[groups/*.md] -->|Detailed| H[Responsibilities]\n G -->|Detailed| I[Core Flow]\n G -->|Detailed| J[Contracts & Invariants]\n G -->|Detailed| K[Change Guide]\n G -->|Detailed| L[Pitfalls]\n end\n \n M[refresh-scan.json] -->|Hash snapshot| N[Deterministic refresh]\n```\n\n### Generated Artifacts\n\n| File | Purpose |\n|------|---------|\n| `blueprint-output.json` | Structured project graph generated by tools |\n| `refresh-scan.json` | Filesystem hash snapshot for deterministic refreshes |\n\n资料来源：[README.md:9-12]()\n\n### Group Documentation Template\n\nFiles under `.blueprint/groups/*.md` follow a stable template:\n\n| Section | Purpose |\n|---------|---------|\n| `Snapshot` | Quick orientation |\n| `Responsibilities` | Ownership and out-of-scope areas |\n| `Core Flow` | Runtime behavior and data flow |\n| `Contracts & Invariants` | Behavior that must not be broken |\n| `Key Files` | Main source files for the group |\n| `Change Guide` | Files or contracts that should change together |\n| `Pitfalls` | Known risks and common mistakes |\n| `Tests` | Most relevant verification |\n| `Debugging` | Failure-mode hints |\n| `Extension / Open Questions` | Uncertainty and known gaps |\n\n资料来源：[AGENTS.md:1-35]()\n\n## Viewer Integration\n\nBlueprint ships a lightweight React/Vite viewer that reads generated Blueprint data.\n\n### Static HTML Generation\n\n```mermaid\ngraph LR\n A[blueprint open] --> B[Read JSON & MD]\n B --> C[Generate index.html]\n C --> D[Open in browser]\n \n E[--watch mode] --> F[Regenerate on changes]\n```\n\n#### Viewer Features\n\n- Self-contained HTML with inline JS and CSS\n- Secure embedded JSON data\n- No HTTP server required\n- No chat or LLM execution\n\n资料来源：[README.md:38-50]()\n\n## Import Resolution System\n\n### Candidate Import Path Resolution\n\nThe code analysis engine resolves relative imports by checking multiple candidate paths:\n\n```typescript\nprivate candidateImportPaths(basePath: string): string[] {\n const candidates = [basePath];\n \n if (ext) {\n return candidates;\n }\n \n return [\n basePath,\n `${basePath}.ts`,\n `${basePath}.tsx`,\n `${basePath}.js`,\n `${basePath}.jsx`,\n `${basePath}/index.ts`,\n `${basePath}/index.tsx`,\n `${basePath}/index.js`,\n `${basePath}/index.jsx`,\n ];\n}\n```\n\n资料来源：[src/tools/scan/scan-code-analysis-engine.ts:80-95]()\n\n## Key Design Principles\n\n### Source of Truth\n\n| Principle | Implication |\n|-----------|-------------|\n| Source code is ground truth | Blueprint docs are orientation, not authority |\n| Documentation follows changes | Update relevant group docs after source changes |\n| Deterministic JSON | Do not edit `blueprint-output.json` manually |\n\n资料来源：[AGENTS.md:55-60]()\n\n### Working Rules\n\n1. Keep changes scoped to the user's task\n2. Prefer existing project patterns over new abstractions\n3. Add or update tests when behavior changes\n4. Run the smallest relevant verification first\n5. Do not edit generated files unless explicitly required\n\n资料来源：[AGENTS.md:65-70]()\n\n---\n\n\n\n## Scan Tool\n\n### 相关页面\n\n相关主题：[System Architecture](#page-system-architecture), [Group Tool](#page-group-tool)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/scan/scan-code-analysis-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-code-analysis-engine.ts)\n- [src/tools/scan/scan-file-inventory-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-file-inventory-builder.ts)\n
\n\n# Scan Tool\n\nThe Scan Tool (`blueprint.scan`) is the first stage in the Blueprint workflow. It performs filesystem traversal and static code analysis to build a comprehensive **File Inventory** and **Analysis Facts** artifact. These artifacts serve as the foundational data layer for subsequent grouping, composition, and visualization operations.\n\n## Overview\n\nThe Scan Tool operates in two distinct phases:\n\n1. **File Inventory Phase** - Traverses the project filesystem, categorizes files by role (source, test, config, etc.), and detects the technology stack\n2. **Code Analysis Phase** - Parses source files using Tree-sitter to extract symbols, imports, exports, and dependency relationships\n\n```\n┌─────────────────┐ ┌──────────────────────────┐ ┌─────────────────┐\n│ Filesystem │───▶│ FileInventoryBuilder │───▶│ FileInventory │\n│ Traversal │ │ (scan-file-inventory) │ │ Artifact │\n└─────────────────┘ └──────────────────────────┘ └────────┬────────┘\n │\n ▼\n┌─────────────────┐ ┌──────────────────────────┐ ┌─────────────────┐\n│ AnalysisFacts │◀───│ CodeAnalysisEngine │◀───│ Parseable │\n│ Artifact │ │ (scan-code-analysis) │ │ Files │\n└─────────────────┘ └──────────────────────────┘ └─────────────────┘\n```\n\n## Architecture\n\n### Core Components\n\n| Component | File | Responsibility |\n|-----------|------|----------------|\n| `ScanFileInventoryBuilder` | `scan-file-inventory-builder.ts` | Filesystem traversal, file categorization, stack detection |\n| `CodeAnalysisEngine` | `scan-code-analysis-engine.ts` | Tree-sitter parsing, symbol extraction, dependency analysis |\n| `FileInventory` | Data model | Container for all inventoried files and summary statistics |\n| `AnalysisFacts` | Data model | Container for parsed code facts (symbols, imports, exports) |\n\n### Class: ScanFileInventoryBuilder\n\nThe `ScanFileInventoryBuilder` class is responsible for walking the project directory and building a structured file inventory.\n\n```typescript\nclass ScanFileInventoryBuilder {\n // Builds the complete file inventory from a root path\n async build(rootPath: string): Promise\n \n // Validates inventory completeness against scanned paths\n private validateInventory(scannedPaths: string[], files: InventoryFile[]): FileInventoryValidation\n}\n```\n\n**资料来源**：[scan-file-inventory-builder.ts:1-50]()\n\n### Class: CodeAnalysisEngine\n\nThe `CodeAnalysisEngine` class consumes the file inventory and performs deep static analysis on parseable files.\n\n```typescript\nclass CodeAnalysisEngine {\n async handle(args: CodeAnalysisEngineArgs, store: ArtifactStore): Promise\n \n // Builds a mapping from file paths to file IDs for efficient lookup\n private buildPathToFileId(inventory: FileInventory): Map\n \n // Computes validation metrics for the analysis results\n private computeValidation(parsedFileIds, parseErrorFileIds, inventory): AnalysisValidation\n}\n```\n\n**资料来源**：[scan-code-analysis-engine.ts:1-60]()\n\n## File Inventory Phase\n\n### File Role Detection\n\nThe scanner categorizes each file into one of the following roles based on its path and extension:\n\n| Role | Detection Criteria |\n|------|-------------------|\n| `source` | Primary language files (`.ts`, `.tsx`, `.js`, `.jsx`, `.py`, `.go`, `.rs`, `.java`) |\n| `test` | Files ending in `.spec.ts`, `.test.ts`, or containing `test`/`tests`/`__tests__` in path |\n| `lockfile` | `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `Cargo.lock`, `poetry.lock` |\n| `config` | `.gitignore`, `package.json`, `tsconfig.json`, `.config.js/ts`, config files |\n| `documentation` | Files in `docs/`, `readme.md`, or other `.md` files |\n| `script` | Files in `scripts/`, shell scripts (`.sh`), or `language === \"shell\"` |\n| `asset` | Files in `assets/`, `public/`, or with extensions: `.html`, `.css`, `.scss`, `.svg` |\n\n**资料来源**：[scan-file-inventory-builder.ts:50-130]()\n\n### Analysis Level Classification\n\nEach file receives an `analysisLevel` designation:\n\n| Level | Description |\n|-------|-------------|\n| `parseable` | Files with known parsers that support symbol/import extraction |\n| `metadata-only` | Files that are inventoried but cannot be deeply parsed |\n\n**资料来源**：[scan-code-analysis-engine.ts:20-30]()\n\n### Stack Detection\n\nThe builder detects the technology stack from two sources:\n\n1. **Language counts** - Extracted from file extensions\n2. **Path patterns** - Special directories indicate additional technologies\n\n| Pattern | Stack Addition |\n|---------|---------------|\n| `*.ts`, `*.js`, etc. | Respective language name |\n| `package.json` in paths | `\"node\"` |\n| `mcp-server/` in paths | `\"mcp\"` |\n\n**资料来源**：[scan-file-inventory-builder.ts:180-200]()\n\n### Package Manager Detection\n\nDetects which package managers are in use:\n\n| File | Manager |\n|------|---------|\n| `package.json` | `npm`, `yarn`, `pnpm` |\n| `Cargo.toml` | `cargo` |\n| `go.mod` | `go` |\n| `pyproject.toml`, `requirements.txt` | `python` |\n| `pom.xml` | `maven` |\n| `build.gradle`, `build.gradle.kts` | `gradle` |\n\n**资料来源**：[scan-file-inventory-builder.ts:150-175]()\n\n## Code Analysis Phase\n\n### Tree-sitter Integration\n\nThe analysis engine uses Tree-sitter for parsing supported languages:\n\n| Supported Languages | Extensions |\n|---------------------|------------|\n| TypeScript/JavaScript | `.ts`, `.tsx`, `.js`, `.jsx` |\n| Python | `.py` |\n| Go | `.go` |\n| Rust | `.rs` |\n| Java | `.java` |\n\n> **Note**: Files in other languages are still included in the inventory but receive `metadata-only` analysis.\n\n**资料来源**：[README.md - Language Support section]()\n\n### Extracted Facts\n\nFor each parseable file, the engine extracts:\n\n```typescript\ninterface AnalysisFacts {\n inventoryArtifactId: string;\n rootPath: string;\n files: Record; // fileId -> parsed content\n symbols: Record; // fileId -> extracted symbols\n imports: ImportStatement[]; // all import statements\n exports: ExportStatement[]; // all export statements\n dependencies: DependencyEdge[]; // inter-file dependencies\n unresolvedImports: UnresolvedImport[]; // imports without matching exports\n parseErrors: ParseError[]; // parsing failures\n summary: AnalysisSummary;\n validation: AnalysisValidation;\n}\n```\n\n**资料来源**：[scan-code-analysis-engine.ts:30-60]()\n\n### Validation Model\n\nThe analysis produces a validation object tracking completeness:\n\n```typescript\ninterface AnalysisValidation {\n isComplete: boolean; // true if all files processed\n inventoryFiles: number; // total files in inventory\n parseableFiles: number; // files marked as parseable\n parsedFiles: number; // successfully parsed count\n metadataOnlyFiles: number; // metadata-only file count\n skippedMetadataOnlyFiles: number; // metadata-only files skipped\n parseErrors: number; // parse failure count\n unaccountedFiles: string[]; // files not in parsed or error sets\n}\n```\n\n**资料来源**：[scan-code-analysis-engine.ts:60-75]()\n\n## Data Flow\n\n```mermaid\ngraph TD\n A[Root Path] --> B[ScanFileInventoryBuilder.build]\n B --> C[Filesystem Walk]\n C --> D[File Categorization]\n D --> E[Stack Detection]\n E --> F[FileInventory Artifact]\n \n F --> G[CodeAnalysisEngine.handle]\n G --> H[Filter Parseable Files]\n H --> I[For Each Parseable File]\n I --> J[Read File Content]\n J --> K[Create Tree-sitter Parser]\n K --> L[Extract Symbols]\n K --> M[Extract Imports]\n K --> N[Extract Exports]\n L --> O[Build Dependency Graph]\n M --> O\n N --> O\n O --> P[AnalysisFacts Artifact]\n \n I --> Q[Handle Parse Errors]\n Q --> P\n```\n\n## Output Artifacts\n\n### FileInventory Artifact\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `rootPath` | `string` | Absolute path to scanned root |\n| `files` | `InventoryFile[]` | All discovered files with metadata |\n| `summary` | `InventorySummary` | Aggregated statistics |\n\n### AnalysisFacts Artifact\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `symbols` | `Record` | Symbols indexed by file ID |\n| `imports` | `ImportStatement[]` | All import declarations |\n| `exports` | `ExportStatement[]` | All export declarations |\n| `dependencies` | `DependencyEdge[]` | File-to-file dependency edges |\n| `unresolvedImports` | `UnresolvedImport[]` | Imports without matching targets |\n\n## Configuration & Behavior\n\n### Summary Statistics\n\nThe `FileInventory` summary provides project metrics:\n\n```typescript\ninterface InventorySummary {\n totalFiles: number;\n parseableFiles: number;\n metadataOnlyFiles: number;\n byLanguage: Record;\n byRole: Record;\n}\n```\n\n**资料来源**：[scan-file-inventory-builder.ts:200-220]()\n\n### Validation Completeness Check\n\nThe engine computes `isComplete` as:\n\n```\nisComplete = (parsedFiles + parseErrorFiles + skippedMetadataOnlyFiles) === totalInventoryFiles\n```\n\nIf `isComplete` is `false`, there are files in the inventory that were neither successfully parsed nor accounted for in error/skipped sets.\n\n**资料来源**：[scan-code-analysis-engine.ts:100-115]()\n\n## Integration with Blueprint Workflow\n\nThe Scan Tool is the entry point for the Blueprint system:\n\n```\nblueprint.scan → blueprint.group → blueprint.compose\n```\n\n1. **`blueprint.scan`** - Produces `fileInventory` and `analysisFacts` artifacts\n2. **`blueprint.group`** - Consumes these artifacts to create semantic groupings\n3. **`blueprint.compose`** - Generates the final `blueprint-output.json`\n\n**资料来源**：[README.md - Initial Workflow section]()\n\n## Error Handling\n\nThe Scan Tool handles several error conditions:\n\n| Error Condition | Handling |\n|-----------------|----------|\n| File not found | Included in `parseErrors` array |\n| Parser unavailable | File marked as `metadata-only` |\n| Syntax error in source | Recorded with location in `parseErrors` |\n| Missing inventory artifact | Returns error result from `handle()` |\n| Unaccounted files | Listed in `validation.unaccountedFiles` |\n\n**资料来源**：[scan-code-analysis-engine.ts:80-95]()\n\n## Refresh Maintenance\n\nWhen the filesystem changes:\n\n```bash\nblueprint.refresh\n```\n\nThis re-runs the scan to update the file inventory and analysis facts, ensuring the Blueprint state reflects the current project structure.\n\n**资料来源**：[README.md - Maintenance Workflow section]()\n\n---\n\n\n\n## Group Tool\n\n### 相关页面\n\n相关主题：[System Architecture](#page-system-architecture), [Scan Tool](#page-scan-tool), [Compose Tool](#page-compose-tool)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/group/index.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/group/index.ts)\n- [src/tools/group/grouping-assignment-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/group/grouping-assignment-engine.ts)\n- [src/tools/group/grouping-plan-validator.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/group/grouping-plan-validator.ts)\n- [src/tools/group/grouping.types.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/group/grouping.types.ts)\n
\n\n# Group Tool\n\n## Overview\n\nThe Group Tool is a core component of the Blueprint system responsible for organizing source files into semantic architectural groups. It bridges the gap between raw file inventory (produced by the Scan Tool) and the structured architectural documentation (produced by the Compose Tool).\n\n**Purpose**: The Group Tool transforms a flat list of files into a meaningful hierarchical structure where files are assigned to architectural groups based on semantic patterns, role assignments, and cross-group relationships.\n\n**Scope**:\n- Processes file inventory data from the Scan Tool\n- Assigns files to groups based on glob patterns and semantic rules\n- Validates grouping plans for completeness and conflicts\n- Aggregates cross-group edges and relationships\n- Handles fallback grouping for unassigned files\n- Supports both `prepare` and `apply` modes for iterative group planning\n\n资料来源：[src/tools/group/grouping-assignment-engine.ts:1-50]()\n\n## Architecture\n\n### Component Flow\n\n```mermaid\ngraph TD\n A[FileInventory] --> B[GroupingAssignmentEngine]\n B --> C[GroupingPlanValidator]\n C --> D[GroupingResult]\n D --> E[ComposeOutputBuilder]\n E --> F[BlueprintOutput]\n \n G[GroupingPlan] --> B\n H[FileFacts] --> B\n```\n\n### Core Components\n\n| Component | File | Responsibility |\n|-----------|------|----------------|\n| `GroupingAssignmentEngine` | `grouping-assignment-engine.ts` | Core logic for file-to-group assignment and pattern matching |\n| `GroupingPlanValidator` | `grouping-plan-validator.ts` | Validates grouping plans for completeness and conflicts |\n| Grouping Types | `grouping.types.ts` | TypeScript interfaces for grouping data models |\n| Tool Entry Point | `index.ts` | CLI/MCP tool interface handling prepare/apply modes |\n\n资料来源：[src/tools/group/grouping-assignment-engine.ts:1-30]()\n\n## Data Models\n\n### Key Types\n\n```typescript\n// GroupedFile represents a file assigned to a group\ninterface GroupedFile {\n fileId: string;\n path: string;\n category: string;\n language: string;\n importance: \"unknown\";\n role: \"unknown\";\n}\n\n// BlueprintGroup represents a semantic architectural group\ninterface BlueprintGroup {\n id: string;\n name: string;\n description: string;\n kind: string;\n confidence: number;\n files: GroupedFile[];\n}\n\n// GroupingResult contains the complete grouping output\ninterface GroupingResult {\n groups: BlueprintGroup[];\n crossGroupEdges: CrossGroupEdge[];\n}\n```\n\n资料来源：[src/tools/group/grouping.types.ts]()\n\n### Group Assignment Strategy\n\nThe assignment engine uses a multi-stage process:\n\n1. **Pattern Matching**: Files are matched against glob-like patterns specified in the grouping plan\n2. **Role Assignment**: Each file receives a role based on pattern matching and heuristics\n3. **Fallback Grouping**: Unmatched files are placed in a fallback group\n4. **Edge Aggregation**: Cross-group relationships are aggregated from file-level dependencies\n\n资料来源：[src/tools/group/grouping-assignment-engine.ts:50-150]()\n\n## Pattern Matching Engine\n\n### Regex-Based Pattern System\n\nThe assignment engine converts user-friendly glob patterns into regular expressions for flexible file matching:\n\n```mermaid\ngraph LR\n A[Glob Pattern] --> B[buildRegex]\n B --> C[Regular Expression]\n C --> D[File Path Matching]\n D --> E{Match?}\n E -->|Yes| F[Assign to Group]\n E -->|No| G[Next Pattern]\n```\n\n### Supported Pattern Syntax\n\n| Pattern | Regex Equivalent | Description |\n|---------|------------------|-------------|\n| `*` | `[^/]*` | Match any characters except path separator |\n| `?` | `[^/]` | Match single character except path separator |\n| `**` | `.*` | Match any characters including path separators |\n| Literal chars | Escaped | Match exact characters |\n\n资料来源：[src/tools/group/grouping-assignment-engine.ts:100-130]()\n\n### Pattern Processing Method\n\n```typescript\nprivate buildRegex(pattern: string): RegExp {\n let source = \"\";\n for (const char of pattern) {\n if (char === \"*\") {\n source += \"[^/]*\";\n continue;\n }\n if (char === \"?\") {\n source += \"[^/]\";\n continue;\n }\n source += this.escapeRegex(char);\n }\n return new RegExp(`^${source}$`);\n}\n```\n\n资料来源：[src/tools/group/grouping-assignment-engine.ts:115-127]()\n\n## Grouping Workflow\n\n### Prepare Mode\n\nIn `prepare` mode, the tool analyzes the file inventory and suggests:\n\n- Suggested group structures based on directory structure and file patterns\n- Suggested role assignments for files\n- Cross-group relationship candidates\n- Confidence scores for each suggestion\n\n```mermaid\nsequenceDiagram\n participant User\n participant GroupTool\n participant ScanTool\n participant ComposeTool\n \n User->>ScanTool: blueprint.scan\n ScanTool->>GroupTool: FileInventory\n GroupTool->>GroupTool: Analyze patterns\n GroupTool-->>User: Suggested grouping plan\n User->>GroupTool: Refine grouping plan\n User->>GroupTool: blueprint.group(mode: apply)\n GroupTool->>ComposeTool: GroupingResult\n ComposeTool-->>User: Blueprint output\n```\n\n### Apply Mode\n\nIn `apply` mode, the tool:\n\n1. Validates the provided grouping plan\n2. Assigns files to groups based on patterns\n3. Aggregates cross-group edges\n4. Returns the structured `GroupingResult`\n\n资料来源：[src/tools/group/index.ts]()\n\n## Validation System\n\n### Plan Validation Checks\n\nThe `GroupingPlanValidator` performs comprehensive validation:\n\n| Validation Check | Purpose |\n|------------------|---------|\n| `unassignedFiles` | Ensures no files are left unassigned |\n| `duplicateAssignments` | Detects files assigned to multiple groups |\n| `unknownPatterns` | Flags patterns that matched no files |\n| `emptyGroups` | Identifies groups with no files |\n| `blockingIssues` | Prevents composition if critical issues exist |\n\n资料来源：[src/tools/group/grouping-plan-validator.ts]()\n\n### Validation Result Structure\n\n```typescript\ninterface ValidationResult {\n isValid: boolean;\n blockingIssues: string[];\n warningIssues: string[];\n unassignedFiles: FileInventory[\"files\"][number][];\n duplicateAssignments: Array<{ fileId: string; groups: string[] }>;\n unknownPatterns: UnknownPattern[];\n emptyGroups: string[];\n}\n```\n\n资料来源：[src/tools/group/grouping-plan-validator.ts:1-50]()\n\n## Edge Aggregation\n\n### Cross-Group Relationship Detection\n\nThe assignment engine aggregates edges between groups based on:\n\n1. **Import Dependencies**: Files importing from other groups\n2. **Reference Patterns**: Cross-module references\n3. **Test Relationships**: Test files referencing implementation files\n\n```typescript\nprivate aggregateEdges(\n facts: FileFacts,\n fileToGroup: Map\n): CrossGroupEdge[] {\n // Aggregates file-level edges into group-level edges\n // Groups edges by fromGroupId, toGroupId, and type\n // Returns sorted, deduplicated edge list\n}\n```\n\n资料来源：[src/tools/group/grouping-assignment-engine.ts:200-250]()\n\n### Edge Composition\n\nThe `compose-output-builder.ts` transforms grouping results into the final output format:\n\n```typescript\nedges: [...grouping.crossGroupEdges]\n .sort((a, b) =>\n a.fromGroupId.localeCompare(b.fromGroupId)\n || a.toGroupId.localeCompare(b.toGroupId)\n || a.type.localeCompare(b.type),\n ),\n```\n\n资料来源：[src/tools/compose/compose-output-builder.ts:1-50]()\n\n## Group Update Workflow\n\n### Refresh Integration\n\nWhen files change in the repository, the Group Tool integrates with the refresh workflow:\n\n```mermaid\ngraph LR\n A[File Changes] --> B[Refresh Tool]\n B --> C{New unassigned files?}\n C -->|Yes| D[Group Update Tool]\n C -->|No| E[Skip Update]\n D --> F[User Decisions]\n F --> G[Updated Grouping]\n```\n\n### Empty Group Detection\n\nThe refresh process identifies:\n\n- **Unassigned Files**: Files not belonging to any group\n- **Empty Group Candidates**: Groups that have lost all their files\n\n```typescript\nconst emptyGroupCandidates = output.groups\n .filter((group) => group.fileIds.length === 0)\n .map((group) => ({\n groupId: group.id,\n name: group.name,\n docsPath: group.docsPath,\n deletedFileIds: [],\n }));\n```\n\n资料来源：[src/tools/group-update/index.ts:1-50]()\n\n## File Categorization\n\nThe Group Tool inherits file categorization from the Scan Tool:\n\n| Category | Detection Criteria |\n|----------|-------------------|\n| `source` | TypeScript, JavaScript, Python source files |\n| `test` | Files ending in `.spec.ts`, `.test.ts`, in `test/` directories |\n| `config` | `package.json`, `tsconfig.json`, config files |\n| `documentation` | `.md` files, `docs/` directories |\n| `script` | Shell scripts, `scripts/` directories |\n| `asset` | CSS, SVG, image files |\n| `lockfile` | `package-lock.json`, `yarn.lock`, etc. |\n\n资料来源：[src/tools/scan/scan-file-inventory-builder.ts:1-100]()\n\n## Integration Points\n\n### With Scan Tool\n\nThe Group Tool receives file inventory data:\n- File paths and IDs\n- Language detection\n- Category classification\n- Basic file facts\n\n### With Compose Tool\n\nThe Group Tool produces `GroupingResult` containing:\n- Structured groups with assigned files\n- Cross-group edges for relationship visualization\n- Role assignments for documentation\n\n### With Refresh Tool\n\nThe Group Tool participates in the refresh workflow by:\n- Receiving updated file inventory\n- Identifying unassigned files\n- Detecting empty group candidates\n\n资料来源：[src/tools/refresh/index.ts:1-100]()\n\n## Error Handling\n\n### Unknown Pattern Handling\n\nWhen a pattern matches no files, the tool provides suggestions:\n\n```typescript\nprivate unknownPattern(\n inventory: FileInventory,\n pattern: string\n): UnknownPattern {\n return {\n pattern,\n reason: \"matched no inventory files; the path may be ignored or not inventoried\",\n suggestions: this.suggestPaths(inventory, pattern),\n };\n}\n```\n\n### Suggestion Generation\n\nThe tool suggests similar paths when patterns fail to match:\n\n```typescript\nprivate suggestPaths(\n inventory: FileInventory,\n pattern: string\n): string[] {\n const suffix = pattern\n .replaceAll(\"*\", \"\")\n .replaceAll(\"?\", \"\")\n .split(\"/\")\n .filter(Boolean)\n .at(-1);\n if (!suffix) return [];\n return inventory.files\n .map((file) => file.path)\n .filter((path) => path.includes(suffix))\n .slice(0, 5);\n}\n```\n\n资料来源：[src/tools/group/grouping-assignment-engine.ts:150-180]()\n\n## Usage in Workflows\n\n### Initial Setup Workflow\n\n1. Run `blueprint.scan` to build file inventory\n2. Run `blueprint.group` with `mode: \"prepare\"` to get suggested groupings\n3. Review and refine the grouping plan\n4. Run `blueprint.group` with `mode: \"apply\"` to apply the plan\n5. Run `blueprint.compose` to generate documentation\n\n### Maintenance Workflow\n\n1. Run `blueprint.refresh` when project structure changes\n2. If new files are unassigned, run `blueprint.group.update`\n3. Update affected group documentation as needed\n\n资料来源：[README.md](https://github.com/engincankaya/blueprint/blob/main/README.md)\n\n## Summary\n\nThe Group Tool is a critical component in the Blueprint system that transforms raw file inventories into semantic architectural groupings. It provides:\n\n- **Pattern-based assignment** with flexible glob-like syntax\n- **Validation** ensuring complete and conflict-free groupings\n- **Edge aggregation** for cross-group relationship tracking\n- **Fallback handling** for unassigned files\n- **Integration** with the broader Blueprint workflow (scan → group → compose → refresh)\n\nThe tool operates in two modes (`prepare` and `apply`) enabling iterative group planning and reliable maintenance workflows.\n\n---\n\n\n\n## Compose Tool\n\n### 相关页面\n\n相关主题：[System Architecture](#page-system-architecture), [Group Tool](#page-group-tool)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/compose/index.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/index.ts)\n- [src/tools/compose/compose-output-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/compose-output-builder.ts)\n- [src/tools/compose/compose-artifact-writer.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/compose-artifact-writer.ts)\n- [src/tools/compose/compose.types.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/compose.types.ts)\n- [src/lib/group-note-template.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/group-note-template.ts)\n
\n\n# Compose Tool\n\n## Overview\n\nThe Compose Tool is the final stage in the Blueprint pipeline. It transforms the semantic grouping artifact into a frontend-ready JSON output and generates Markdown documentation for each group. The tool acts as the bridge between the analysis/grouping phases and the viewer UI.\n\n**Key Responsibilities:**\n\n- Builds the final `blueprint.v1` output JSON from stored grouping artifacts\n- Determin joining of groups, files, edges, docs paths, and validation data\n- Generates group documentation Markdown files from templates\n- Writes output artifacts to `.blueprint/` directory\n- Detects entrypoint files for each group\n- Validates the composed output against expected schema\n\n资料来源：[src/tools/compose/index.ts:1-18]()\n\n## Architecture\n\nThe Compose Tool is composed of several interconnected components that work together to produce the final Blueprint output.\n\n### Component Overview\n\n```mermaid\ngraph TD\n subgraph \"Compose Tool Components\"\n CT[ComposeTool]\n COB[ComposeOutputBuilder]\n CAW[ComposeArtifactWriter]\n CED[ComposeEntrypointDetector]\n end\n \n subgraph \"Input Dependencies\"\n GR[GroupingResult]\n FI[FileInventory]\n AF[AnalysisFacts]\n end\n \n subgraph \"Output Artifacts\"\n JSON[blueprint-output.json]\n MD[groups/*.md]\n end\n \n CT --> COB\n CT --> CAW\n CT --> CED\n GR --> CT\n FI --> COB\n AF --> COB\n COB --> JSON\n CAW --> MD\n```\n\n### Core Classes\n\n| Component | Purpose | Key Methods |\n|-----------|---------|-------------|\n| `ComposeTool` | Main orchestrator and entry point | `handle()` |\n| `ComposeOutputBuilder` | Constructs the final JSON output structure | `build()`, `joinGroups()`, `joinEdges()` |\n| `ComposeArtifactWriter` | Persists output to filesystem | `write()`, `writeGroupDocs()` |\n| `ComposeEntrypointDetector` | Identifies entrypoint files per group | `detect()` |\n\n资料来源：[src/tools/compose/index.ts:19-27]()\n\n## Data Flow\n\n### Pipeline Integration\n\nThe Compose Tool represents stage 3 of the Blueprint pipeline:\n\n```mermaid\ngraph LR\n subgraph \"Stage 1: Scan\"\n SI[scan.tool]\n FI[FileInventory]\n AF[AnalysisFacts]\n end\n \n subgraph \"Stage 2: Group\"\n GI[group.tool]\n GR[GroupingResult]\n end\n \n subgraph \"Stage 3: Compose\"\n CI[compose.tool]\n JSON[blueprint.v1 JSON]\n MD[Group Docs]\n end\n \n SI --> FI\n SI --> AF\n GI --> GR\n FI --> CI\n GR --> CI\n AF --> CI\n CI --> JSON\n CI --> MD\n```\n\n### Input Dependencies\n\nThe Compose Tool requires the following artifacts from previous pipeline stages:\n\n1. **GroupingResult** - Semantic file groupings with assignments\n2. **FileInventory** - Complete file listing with metadata\n3. **AnalysisFacts** - Code analysis data including imports/exports\n\n资料来源：[src/tools/compose/index.ts:28-35]()\n\n## ComposeTool Class\n\nThe `ComposeTool` class serves as the main orchestrator, delegating work to specialized components.\n\n```typescript\nexport class ComposeTool {\n constructor(\n private readonly outputBuilder: ComposeOutputBuilder,\n private readonly artifactWriter: ComposeArtifactWriter,\n ) {}\n```\n\n### The `handle()` Method\n\nThe primary entry point that processes compose requests:\n\n```typescript\nasync handle(args: ComposeArgs, store: ArtifactStore): Promise\n```\n\n**Flow:**\n\n1. Retrieves the grouping artifact from the store\n2. Validates grouping artifact existence\n3. Delegates JSON building to `ComposeOutputBuilder`\n4. Delegates artifact writing to `ComposeArtifactWriter`\n5. Returns structured tool result\n\n资料来源：[src/tools/compose/index.ts:28-48]()\n\n### Error Handling\n\nThe tool provides descriptive error messages when artifacts are missing:\n\n```typescript\nif (!grouping) {\n const entry = store.get(args.groupingArtifactId);\n return errorResult(\n entry\n ? `Grouping artifact ${args.groupingArtifactId} not found or has the wrong type`\n : `Grouping artifact ${args.groupingArtifactId} not found`,\n );\n}\n```\n\n## ComposeOutputBuilder\n\nThe `ComposeOutputBuilder` is responsible for constructing the final `blueprint.v1` output structure.\n\n### Output Structure\n\nThe builder produces a stable JSON schema containing:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `groups` | `Group[]` | All semantic groups with assigned files |\n| `files` | `File[]` | Complete file inventory |\n| `edges` | `Edge[]` | Connections between groups/files |\n| `metadata` | `Metadata` | Output generation timestamp and version |\n| `validation` | `ValidationResult` | Schema validation results |\n\n### Building Process\n\nThe output builder deterministically joins:\n\n- Groups with their assigned files\n- File metadata from inventory\n- Edge connections between groups\n- Documentation paths\n- Validation data\n\n资料来源：[src/tools/compose/compose-output-builder.ts]()\n\n## ComposeArtifactWriter\n\nThe `ComposeArtifactWriter` handles persistence of composed output to the filesystem.\n\n### Write Operations\n\n| Method | Target | Description |\n|--------|--------|-------------|\n| `writeJson()` | `.blueprint/blueprint-output.json` | Writes the main Blueprint JSON |\n| `writeGroupDocs()` | `.blueprint/groups/*.md` | Generates Markdown documentation per group |\n| `writeBrief()` | `.blueprint/brief.md` | Writes project overview documentation |\n\n### Group Documentation\n\nThe artifact writer generates Markdown files for each group using a standardized template that includes:\n\n- **Snapshot** - Quick orientation summary\n- **Responsibilities** - Ownership and scope definition\n- **Core Flow** - Runtime behavior and data flow\n- **Contracts & Invariants** - Behavior constraints\n- **Key Files** - Main source file references\n- **Change Guide** - Files that should change together\n- **Pitfalls** - Known risks and common mistakes\n\n资料来源：[src/lib/group-note-template.ts]()\n\n## ComposeEntrypointDetector\n\nThe `ComposeEntrypointDetector` identifies entrypoint files for each group by analyzing:\n\n- Export patterns\n- Module initialization files\n- Main/index file conventions\n- Dependency injection configurations\n\n## API Reference\n\n### ComposeArgs\n\n```typescript\ninterface ComposeArgs {\n groupingArtifactId: string; // ID of the grouping artifact to compose\n outputPath?: string; // Optional custom output path\n}\n```\n\n### ComposeResponseValidation\n\n```typescript\ninterface ComposeResponseValidation {\n valid: boolean;\n errors: ValidationError[];\n}\n```\n\n### ToolResult\n\nThe compose tool returns a `ToolResult` with either:\n\n- **Success**: JSON result containing the composed output path\n- **Error**: Descriptive error message explaining the failure\n\n## Usage\n\n### CLI Usage\n\n```bash\nblueprint compose \n```\n\n### MCP Tool Usage\n\n```json\n{\n \"tool\": \"blueprint.compose\",\n \"arguments\": {\n \"groupingArtifactId\": \"grouping-20240115-143022\"\n }\n}\n```\n\n## Integration with Other Tools\n\n### Tool Chain\n\n```mermaid\ngraph TD\n subgraph \"blueprint CLI\"\n SCAN[blueprint.scan]\n GROUP[blueprint.group]\n COMPOSE[blueprint.compose]\n REFRESH[blueprint.refresh]\n end\n \n SCAN --> GROUP\n GROUP --> COMPOSE\n COMPOSE --> REFRESH\n REFRESH --> GROUP\n```\n\n### Related Tools\n\n| Tool | Input to Compose | Output from Compose |\n|------|------------------|---------------------|\n| `scan` | - | `FileInventory`, `AnalysisFacts` |\n| `group` | `FileInventory`, `AnalysisFacts` | `GroupingResult` |\n| `compose` | `GroupingResult` | `blueprint.v1 JSON`, `group/*.md` |\n| `refresh` | - | Refreshes from current filesystem |\n\n## Output Schema (blueprint.v1)\n\n```typescript\ninterface BlueprintOutput {\n version: \"blueprint.v1\";\n generated: string; // ISO timestamp\n groups: Group[];\n files: FileEntry[];\n edges: Edge[];\n metadata: {\n sourceRoot: string;\n artifactCount: number;\n };\n validation: ComposeResponseValidation;\n}\n```\n\n## Best Practices\n\n1. **Always run scan before compose** - Ensure fresh analysis data\n2. **Use stable artifact IDs** - Grouping artifacts should be referenced by ID, not path\n3. **Validate output** - Check the validation results before consuming the output\n4. **Preserve group documentation** - The generated Markdown files should be version-controlled\n\n## File Structure\n\n```\n.blueprint/\n├── blueprint-output.json # Main Blueprint JSON (blueprint.v1)\n├── brief.md # Project overview\n└── groups/\n ├── group-1.md # Group-specific documentation\n ├── group-2.md\n └── ...\n\n---\n\n\n\n## Refresh Tool\n\n### 相关页面\n\n相关主题：[System Architecture](#page-system-architecture), [Compose Tool](#page-compose-tool)\n\nI cannot generate an accurate technical wiki page about the Refresh Tool based on the provided context. The requested source files are not present in the retrieved repository content:\n\n**Missing Source Files:**\n- `src/tools/refresh/index.ts`\n- `src/tools/refresh/refresh.types.ts`\n- `src/tools/group-update/index.ts`\n- `src/tools/group-update/group-update-applier.ts`\n\n**Available Context:**\nThe README.md does reference `blueprint.refresh` as a tool that \"Refreshes Blueprint state from the current filesystem snapshot\" and `blueprint.group.update` for \"Assigning unassigned files or managing empty groups after refresh,\" but the actual implementation source code for these components is not included in the provided context.\n\nTo generate an accurate wiki page, I would need access to the actual source files for the refresh and group-update tools.\n\n---\n\n\n\n## Task Context Tool\n\n### 相关页面\n\n相关主题：[System Architecture](#page-system-architecture), [MCP Server Implementation](#page-mcp-server)\n\n
\nRelevant Source Files\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/task-context.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/task-context.ts) - **File not found in provided context**\n\n
\n\n# Task Context Tool\n\nThe requested source file `src/tools/task-context.ts` was not found in the provided repository context. This wiki page cannot be generated with the specified source file.\n\n---\n\n## Available Context Files\n\nThe following files were retrieved from the repository and may provide related context:\n\n| File Path | Purpose |\n|-----------|---------|\n| `frontend/src/components/blueprint/GroupDetailPanel.tsx` | React component for displaying group details with tabs |\n| `frontend/src/components/BlueprintApp.tsx` | Main application component with tab management |\n| `src/tools/scan/scan-file-inventory-builder.ts` | File inventory classification system |\n| `src/viewer/render-html.ts` | HTML rendering utilities for the viewer |\n| `src/lib/group-docs.ts` | Group documentation structure validation |\n| `AGENTS.md` | Agent instructions for code analysis workflow |\n\n---\n\n## Next Steps\n\nTo generate an accurate wiki page for the Task Context Tool:\n\n1. Request the file `src/tools/task-context.ts` be included in the context\n2. Alternatively, search the repository for \"task-context\" or \"TaskContext\" references to identify alternative relevant files\n\n---\n\n## Related Components (From Available Context)\n\n### Group Detail Panel Architecture\n\nThe `GroupDetailPanel.tsx` component demonstrates the application's approach to displaying structured information:\n\n```typescript\n// Tab structure for group details\nconst SUB_TABS = [\n { id: 'overview', label: 'Overview' },\n { id: 'files', label: 'Files' },\n { id: 'connections', label: 'Connections' },\n { id: 'architecture', label: 'Architecture' },\n { id: 'guide', label: 'Guide' },\n]\n```\n\n### File Inventory Classification\n\nThe `scan-file-inventory-builder.ts` classifies files into categories:\n\n| Category | Criteria |\n|----------|----------|\n| `test` | `.spec.ts`, `.spec.tsx`, `test/` directories |\n| `config` | `package.json`, `.config.js`, `tsconfig.json` |\n| `documentation` | `.md` files, `docs/` directory |\n| `script` | `.sh` files, `scripts/` directory |\n| `asset` | `assets/`, `public/`, `.css`, `.svg` |\n\n资料来源：[src/tools/scan/scan-file-inventory-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-file-inventory-builder.ts)\n\n---\n\n## Recommendation\n\nProvide the `src/tools/task-context.ts` source file to enable accurate documentation generation for the Task Context Tool feature.\n\n---\n\n\n\n## Viewer Frontend\n\n### 相关页面\n\n相关主题：[System Architecture](#page-system-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [frontend/src/components/BlueprintApp.tsx](https://github.com/engincankaya/blueprint/blob/main/frontend/src/components/BlueprintApp.tsx)\n- [frontend/src/components/blueprint/GroupDetailPanel.tsx](https://github.com/engincankaya/blueprint/blob/main/frontend/src/components/blueprint/GroupDetailPanel.tsx)\n- [frontend/src/components/blueprint/BlueprintCanvas.tsx](https://github.com/engincankaya/blueprint/blob/main/frontend/src/components/blueprint/BlueprintCanvas.tsx)\n- [frontend/src/components/blueprint/BlueprintExplorer.tsx](https://github.com/engincankaya/blueprint/blob/main/frontend/src/components/blueprint/BlueprintExplorer.tsx)\n- [src/lib/agent-instructions.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/agent-instructions.ts)\n- [README.md](https://github.com/engincankaya/blueprint/blob/main/README.md)\n- [todos_120526.md](https://github.com/engincankaya/blueprint/blob/main/todos_120526.md)\n- [src/tools/compose/index.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/index.ts)\n
\n\n# Viewer Frontend\n\n## Overview\n\nThe Viewer Frontend is a lightweight React-based interface for exploring and navigating Blueprint project documentation. It provides an interactive visualization layer that renders the output generated by Blueprint's compose stage, enabling developers to browse groups, files, connections, and architectural documentation through a visual canvas or detailed panel views.\n\nThe viewer is designed as a static, self-contained HTML artifact that can be opened in any browser without requiring a dedicated HTTP server. This approach prioritizes portability and simplicity, allowing teams to commit the generated viewer HTML alongside their project documentation.\n\n## Architecture\n\n### High-Level Design\n\n```mermaid\ngraph TD\n subgraph \"Data Sources\"\n A[blueprint-output.json] --> D[BlueprintViewerService]\n B[groups/*.md] --> D\n end\n \n subgraph \"Application Layer\"\n D --> E[BlueprintApp]\n E --> F[BlueprintCanvas]\n E --> G[GroupDetailPanel]\n end\n \n subgraph \"Rendering\"\n F --> H[BlueprintExplorer]\n G --> I[SectionCard]\n G --> J[ConnectionDiagram]\n G --> K[OpenQuestionsCards]\n end\n \n E --> L[index.html]\n```\n\nThe viewer follows a service-based architecture that abstracts data access through `BlueprintViewerService`. This design supports multiple data source modes: embedded JSON data for static viewing or HTTP fetching for development workflows.\n\n### Component Hierarchy\n\n| Component | File Path | Responsibility |\n|-----------|-----------|----------------|\n| `BlueprintApp` | `frontend/src/components/BlueprintApp.tsx` | Root application container managing tab state and routing between canvas and detail views |\n| `BlueprintCanvas` | `frontend/src/components/blueprint/BlueprintCanvas.tsx` | Visual graph representation of groups and their connections |\n| `BlueprintExplorer` | `frontend/src/components/blueprint/BlueprintExplorer.tsx` | Hierarchical file browser within groups |\n| `GroupDetailPanel` | `frontend/src/components/blueprint/GroupDetailPanel.tsx` | Tabbed detail view for individual groups showing documentation sections |\n| `SectionCard` | Inline in `GroupDetailPanel.tsx` | Collapsible card component for rendering markdown content sections |\n| `ConnectionDiagram` | Referenced in `GroupDetailPanel.tsx` | Visualizes relationships between groups |\n| `OpenQuestionsCards` | Referenced in `GroupDetailPanel.tsx` | Displays open questions and extension points |\n\n## Core Components\n\n### BlueprintApp\n\nThe main application shell that orchestrates the viewer experience. It maintains the active tab state and determines which view to render based on user interaction.\n\n**State Management:**\n- `activeTab`: Tracks whether the user is viewing the canvas or a specific group's details\n- `activeGroupId`: Identifies the currently selected group for detail view\n- `overview`: Contains the complete Blueprint data including all groups, files, and connections\n\n**Tab Types:**\n- `canvas`: The full project visualization showing all groups and their relationships\n- `group`: Detailed view of a specific group with its documentation\n\n```typescript\n// Tab structure from BlueprintApp.tsx\nactiveTab.type === \"canvas\" \n ? \n : \n```\n\n### GroupDetailPanel\n\nThe primary content display component that renders detailed documentation for a selected group. It organizes content into logical sub-tabs.\n\n```mermaid\ngraph LR\n A[GroupDetailPanel] --> B[overview]\n A --> C[files]\n A --> D[connections]\n A --> E[architecture]\n A --> F[guide]\n \n B --> B1[Snapshot]\n B --> B2[Responsibilities]\n B --> B3[Key Files]\n B --> B4[Open Questions]\n \n E --> E1[Core Flow]\n E --> E2[Contracts & Invariants]\n E --> E3[Key Files]\n \n F --> F1[Change Guide]\n F --> F2[Contracts & Invariants]\n F --> F3[Pitfalls]\n F --> F4[Tests]\n F --> F5[Debugging]\n F --> F6[Extension / Open Questions]\n```\n\n**Sub-Tabs and Content:**\n\n| Sub-Tab | Content Sections | Accent Color |\n|---------|------------------|---------------|\n| `overview` | Snapshot, Responsibilities, Key Files, Open Questions | Blue (for Open Questions) |\n| `files` | Role breakdown, File tree | Default |\n| `connections` | ConnectionDiagram | Default |\n| `architecture` | Core Flow, Contracts & Invariants, Key Files | Default |\n| `guide` | Change Guide, Invariants, Pitfalls, Tests, Debugging, Extension/Open Questions | Red (Invariants), Amber (Pitfalls), Green (Extension) |\n\n### SectionCard Component\n\nA reusable collapsible component for rendering markdown content sections within the detail panel.\n\n**Features:**\n- Expandable/collapsible with smooth animation\n- Preview text when collapsed (line-clamp-1)\n- Configurable title styling with accent colors\n- Markdown content rendering via `SectionContent`\n\n**Animation Behavior:**\n```typescript\n// Entrance/exit animations\n\n```\n\n## Data Flow\n\n### Static Viewer Data Model\n\nThe viewer expects a structured JSON input that is either embedded in the HTML or fetched from the filesystem. The data model follows the `blueprint.v1` schema.\n\n```mermaid\nsequenceDiagram\n participant User as User Browser\n participant HTML as index.html\n participant Service as BlueprintViewerService\n participant Store as Artifact Store\n \n User->>HTML: Open .blueprint/index.html\n HTML->>Service: Initialize with embedded data\n Service->>Store: Parse blueprint-output.json\n Store->>HTML: Render overview\n User->>HTML: Click group\n HTML->>Service: Request group details\n Service->>Store: Load groups/*.md files\n Store->>HTML: Render GroupDetailPanel\n```\n\n### Data Source Abstraction\n\nThe viewer uses a `BlueprintDataSource` abstraction layer that supports two modes:\n\n| Mode | Data Location | Use Case |\n|------|---------------|----------|\n| Static | Embedded in `index.html` as `` closing tag risks are mitigated through escaping\n\n### CLI Commands\n\n| Command | Description | Output |\n|---------|-------------|--------|\n| `blueprint open` | Generates and opens viewer in browser | Writes `.blueprint/index.html`, opens in default browser |\n| `blueprint open --watch` | Watches for file changes and regenerates | Maintains `.blueprint/index.html` updated |\n| `blueprint render` | Generates viewer HTML | Writes `.blueprint/index.html` without opening browser |\n\n### Output Artifacts\n\n| Artifact | Path | Description |\n|----------|------|-------------|\n| `blueprint-output.json` | `.blueprint/blueprint-output.json` | Structured project graph with groups, files, and edges |\n| Group docs | `.blueprint/groups/*.md` | Individual group documentation files |\n| Brief | `.blueprint/brief.md` | Project overview and quick reference |\n| Viewer HTML | `.blueprint/index.html` | Self-contained viewer (generated) |\n\n## UI/UX Design\n\n### Visual Design System\n\nThe viewer uses a zinc-based color palette with specific accent colors for semantic meaning:\n\n| Element | Color | Usage |\n|---------|-------|-------|\n| Primary text | `zinc-100` | Main headings and titles |\n| Secondary text | `zinc-400` | Body content and descriptions |\n| Muted text | `zinc-500` | Metadata, counts |\n| Background | `zinc-950` | Application background |\n| Accent Blue | `blue-400` | Open Questions in overview |\n| Accent Red | `red-500` | Invariants in guide |\n| Accent Amber | `amber-500` | Pitfalls in guide |\n| Accent Green | `green-500` | Extension/Open Questions in guide |\n\n### Typography\n\n| Element | Size | Weight | Transform |\n|---------|------|--------|-----------|\n| Group title | `text-base` | semibold | none |\n| Section heading | `text-[11px]` | semibold | uppercase, tracking-wider |\n| Body text | `text-sm` | normal | none |\n| Code | inline code | monospace | - |\n\n### Animation Guidelines\n\nThe viewer uses Framer Motion for animations with consistent timing:\n\n| Animation | Duration | Easing |\n|-----------|----------|--------|\n| Tab transition | 0.12s | default |\n| Content fade | 0.15s | default |\n| Section expand | 0.2s | default |\n| Section collapse | 0.15s | default |\n| Chevron rotation | 0.15s | default |\n\n## Group Documentation Template\n\nGroups follow a standardized documentation template that the viewer renders:\n\n| Section | Content | Panel Location |\n|---------|---------|----------------|\n| Snapshot | Quick orientation quote | overview |\n| Responsibilities | Ownership and out-of-scope areas | overview |\n| Core Flow | Runtime behavior and data flow | architecture |\n| Contracts & Invariants | Behavior that must not be broken | architecture, guide |\n| Key Files | Main source files for the group | overview, architecture |\n| Change Guide | Files or contracts that should change together | guide |\n| Pitfalls | Known risks and common mistakes | guide |\n| Tests | Test coverage and test locations | guide |\n| Debugging | Common issues and debugging approaches | guide |\n| Extension / Open Questions | Future considerations and unresolved items | overview, guide |\n\n## AGENTS.md Integration\n\nThe viewer supports integration with the agent instruction system. The `renderBlueprintAgentsSnippet()` function generates a standardized marker-delimited section that can be injected into project documentation:\n\n```markdown\n\n\n## Blueprint MCP\n\nThis project uses Blueprint MCP for local architecture memory.\n\nBefore broad codebase exploration, read:\n\n`node_modules/blueprint-mcp-server/docs/agents.md`\n\nIf Blueprint memory exists, start with:\n\n`.blueprint/brief.md`\n\n\n```\n\nThis enables tools and agents to discover and use Blueprint documentation automatically.\n\n## Development Workflow\n\n### Running the Viewer During Development\n\n1. **Initial scan and compose:**\n ```bash\n blueprint.scan\n blueprint.group --mode prepare\n blueprint.group --mode apply\n blueprint.compose\n ```\n\n2. **Open the viewer:**\n ```bash\n blueprint open\n ```\n\n3. **Watch for changes:**\n ```bash\n blueprint open --watch\n ```\n\n### Maintenance Workflow\n\nWhen project files change significantly:\n\n1. Run `blueprint.refresh` to update the file inventory\n2. Run `blueprint.group.update` if new files are unassigned\n3. Update affected `.blueprint/groups/*.md` notes\n4. Regenerate the viewer with `blueprint open`\n\n## Browser Compatibility\n\nThe viewer is built with React 18 and Vite, targeting modern browsers with ESM support. No additional polyfills are included in the static bundle.\n\n## Security Model\n\nThe static viewer follows security best practices:\n\n- All data is embedded directly in the HTML, eliminating network-based attacks\n- JSON data is escaped before embedding to prevent XSS via `` injection\n- Special characters (`<`, `-->`, `\\u2028`, `\\u2029`) are properly escaped\n- No eval() or dynamic code execution from embedded data\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：engincankaya/blueprint\n\n摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1230090802 | https://github.com/engincankaya/blueprint | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1230090802 | https://github.com/engincankaya/blueprint | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1230090802 | https://github.com/engincankaya/blueprint | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1230090802 | https://github.com/engincankaya/blueprint | no_demo; severity=medium\n\n## 5. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1230090802 | https://github.com/engincankaya/blueprint | issue_or_pr_quality=unknown\n\n## 6. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1230090802 | https://github.com/engincankaya/blueprint | release_recency=unknown\n\n\n", "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "Human Manual / 人类版说明书" }, "pitfall_log": { "asset_id": "pitfall_log", "filename": "PITFALL_LOG.md", "markdown": "# Pitfall Log / 踩坑日志\n\n项目：engincankaya/blueprint\n\n摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1230090802 | https://github.com/engincankaya/blueprint | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1230090802 | https://github.com/engincankaya/blueprint | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1230090802 | https://github.com/engincankaya/blueprint | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1230090802 | https://github.com/engincankaya/blueprint | no_demo; severity=medium\n\n## 5. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1230090802 | https://github.com/engincankaya/blueprint | issue_or_pr_quality=unknown\n\n## 6. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1230090802 | https://github.com/engincankaya/blueprint | release_recency=unknown\n", "summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。", "title": "Pitfall Log / 踩坑日志" }, "prompt_preview": { "asset_id": "prompt_preview", "filename": "PROMPT_PREVIEW.md", "markdown": "# blueprint - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for engincankaya/blueprint.\n\nProject:\n- Name: blueprint\n- Repository: https://github.com/engincankaya/blueprint\n- Summary: Architecture-aware MCP server that analyzes codebases with Tree-sitter and generates Blueprint memory for LLM coding agents.\n- Host target: mcp_host\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Architecture-aware MCP server that analyzes codebases with Tree-sitter and generates Blueprint memory for LLM coding agents.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Architecture-aware MCP server that analyzes codebases with Tree-sitter and generates Blueprint memory for LLM coding agents.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. page-blueprint-introduction: Blueprint Introduction. Produce one small intermediate artifact and wait for confirmation.\n2. page-cli-usage: CLI and Command Usage. Produce one small intermediate artifact and wait for confirmation.\n3. page-system-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. page-mcp-server: MCP Server Implementation. Produce one small intermediate artifact and wait for confirmation.\n5. page-scan-tool: Scan Tool. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/engincankaya/blueprint\n- https://github.com/engincankaya/blueprint#readme\n- README.md\n- AGENTS.md\n- docs/agents.md\n- src/cli/index.ts\n- package.json\n- src/tools/scan/index.ts\n- src/tools/group/index.ts\n- src/tools/compose/index.ts\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n", "summary": "不安装项目也能感受能力节奏的安全试用 Prompt。", "title": "Prompt Preview / 安装前试用 Prompt" }, "quick_start": { "asset_id": "quick_start", "filename": "QUICK_START.md", "markdown": "# Quick Start / 官方入口\n\n项目：engincankaya/blueprint\n\n## 官方安装入口\n\n### Node.js / npm · 官方安装入口\n\n```bash\nnpm install -g blueprint-mcp-server\n```\n\n来源：https://github.com/engincankaya/blueprint#readme\n\n## 来源\n\n- repo: https://github.com/engincankaya/blueprint\n- docs: https://github.com/engincankaya/blueprint#readme\n", "summary": "从项目官方 README 或安装文档提取的开工入口。", "title": "Quick Start / 官方入口" } }, "validation_id": "dval_b24e4e869d9c46e0b432673d5547fcbd" }