@mycodemap/mycodemap 1.9.0 → 2.7.0

package/docs/API.md

@@ -0,0 +1,170 @@
+<!-- generated-by: gsd-doc-writer -->
+
+# API Reference
+
+CodeMap exposes two runtime surfaces:
+
+- a REST API mounted under `/api/v1`
+- an experimental MCP server for stdio-based agent integrations
+
+## Server Configuration
+
+`CodeMapServer` defaults to:
+
+- `host: 0.0.0.0`
+- `port: 3000`
+
+Optional server config includes:
+
+- `cors.origin`
+- `cors.credentials`
+- `auth.type` with `none`, `bearer`, or `api-key`
+
+## Authentication
+
+The server configuration accepts an optional `auth` field, but authentication is **not enforced by middleware** in the current implementation. All endpoints are publicly accessible when the server is started with default settings.
+
+When `auth.type` is set to `bearer` or `api-key`, consumers should include the credential in the `Authorization` header. <!-- VERIFY: actual header format and secret rotation are not implemented in route middleware -->
+
+## Endpoints Overview
+
+All endpoints are mounted under `/api/v1`.
+
+| Method | Path | Description | Auth Required |
+|---|---|---|---|
+| GET | `/health` | Basic health check | No |
+| GET | `/search/symbols` | Search symbols by query string | No |
+| GET | `/search/modules` | Search modules by query string | No |
+| GET | `/modules/:id` | Module detail | No |
+| GET | `/symbols/:id` | Symbol detail | No |
+| GET | `/symbols/:id/callers` | Incoming callers for a symbol | No |
+| GET | `/symbols/:id/callees` | Outgoing callees for a symbol | No |
+| POST | `/analysis` | Run analysis for a project path | No |
+| POST | `/analysis/refresh` | Refresh an existing project | No |
+| POST | `/analysis/impact` | Analyze the impact of a module change | No |
+| GET | `/analysis/cycles` | Detect circular dependencies | No |
+| GET | `/analysis/validate` | Validate the current code graph | No |
+| GET | `/stats` | Project statistics | No |
+| GET | `/graph` | Dependency graph data for visualization | No |
+| GET | `/export/:format` | Export graph data | No |
+
+### Query Parameters
+
+Search endpoints accept:
+
+- `q` — string, default empty
+- `limit` — number, default `50`
+
+The graph endpoint accepts:
+
+- `page` — number, default `1`
+- `limit` — number, default `100`
+
+### Export Formats
+
+`export/:format` accepts `json`, `graphml`, and `dot`. The response is returned as a file download with the appropriate `Content-Type` and `Content-Disposition` headers.
+
+## Request/Response Formats
+
+### Response Envelope
+
+Every JSON endpoint returns an `ApiResponse<T>` envelope:
+
+```json
+{
+  "success": true,
+  "data": { ... },
+  "meta": {
+    "timestamp": "2026-05-11T08:49:11.768Z",
+    "requestId": "req_1746989351768_abc1234"
+  }
+}
+```
+
+On failure:
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "NOT_FOUND",
+    "message": "Module xyz not found"
+  },
+  "meta": {
+    "timestamp": "2026-05-11T08:49:11.768Z",
+    "requestId": "req_1746989351768_abc1234"
+  }
+}
+```
+
+### Request Bodies
+
+**POST `/analysis`**
+
+```json
+{
+  "projectPath": "/path/to/project",
+  "options": {
+    "mode": "tree-sitter"
+  }
+}
+```
+
+**POST `/analysis/refresh`**
+
+```json
+{
+  "projectPath": "/path/to/project"
+}
+```
+
+**POST `/analysis/impact`**
+
+```json
+{
+  "moduleId": "module-uuid",
+  "depth": 3
+}
+```
+
+For deprecated parser modes, the API returns the same actionable error shape used by the CLI, including `nextCommand` when available.
+
+## Error Codes
+
+Standard HTTP status codes and their meanings in this API:
+
+| Status | Code | Meaning |
+|---|---|---|
+| 200 | — | Success |
+| 400 | `INVALID_FORMAT` | Unsupported export format or bad request parameter |
+| 400 | `DEPRECATED_PARSER_MODE` | Requested parser mode is no longer supported |
+| 404 | `NOT_FOUND` | Requested module or symbol does not exist |
+| 500 | `INTERNAL_ERROR` | Unhandled server exception |
+| 500 | `SEARCH_ERROR` | Search operation failed |
+| 500 | `QUERY_ERROR` | Query operation failed |
+| 500 | `ANALYSIS_ERROR` | Analysis operation failed |
+| 500 | `EXPORT_ERROR` | Export operation failed |
+| 500 | `VALIDATION_ERROR` | Validation operation failed |
+| 501 | `ANALYSIS_NOT_SUPPORTED` | Analysis operation is not supported by the server layer |
+| 501 | `INCREMENTAL_UPDATE_NOT_SUPPORTED` | Incremental update is not supported |
+| 501 | `REFRESH_NOT_SUPPORTED` | Refresh operation is not supported by the server layer |
+
+The 404 handler also returns a standard error envelope for unmatched routes:
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "NOT_FOUND",
+    "message": "Route /api/v1/unknown not found"
+  }
+}
+```
+
+## Rate Limits
+
+No rate limiting is currently configured for the API.
+
+## MCP
+
+The MCP server lives under `src/server/mcp/` and is started via the `mcp start` CLI path. It is intentionally experimental and uses the process' stdio transport rather than the REST API transport.

package/docs/CONFIGURATION.md

@@ -0,0 +1,141 @@
+<!-- generated-by: gsd-doc-writer -->
+
+# Configuration
+
+## Config File Resolution
+
+CodeMap reads config files in this order:
+
+1. `.mycodemap/config.json`
+2. `mycodemap.config.json`
+3. `codemap.config.json`
+
+`mycodemap init` writes the canonical config under `.mycodemap/config.json` unless you are explicitly using a legacy path.
+
+## Config File Format
+
+The configuration file is JSON-based. The canonical location is `.mycodemap/config.json`, with fallback to `mycodemap.config.json` or `codemap.config.json` in the project root.
+
+Top-level keys:
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `$schema` | string | `https://mycodemap.dev/schema/config.json` | JSON Schema reference for editor tooling |
+| `mode` | string | `"tree-sitter"` | Parser mode. Only `"tree-sitter"` is valid; legacy values (`fast`, `smart`, `hybrid`) are rejected. |
+| `include` | string[] | `["src/**/*.ts"]` | Glob patterns to include in analysis |
+| `exclude` | string[] | See defaults below | Glob patterns to exclude from analysis |
+| `output` | string | `".mycodemap"` | Output directory for generated files |
+| `watch` | boolean | `false` | Enable watch mode for file changes |
+| `storage` | object | See below | Storage backend configuration |
+| `plugins` | object | See below | Plugin loading options |
+
+Example:
+
+```json
+{
+  "$schema": "https://mycodemap.dev/schema/config.json",
+  "mode": "tree-sitter",
+  "include": ["src/**/*.ts"],
+  "exclude": [
+    "node_modules/**",
+    "dist/**",
+    "build/**",
+    "coverage/**",
+    ".venv/**",
+    "**/__pycache__/**",
+    "vendor/**",
+    "**/*.test.ts",
+    "**/*.spec.ts",
+    "**/*.d.ts"
+  ],
+  "output": ".mycodemap",
+  "watch": false,
+  "storage": {
+    "type": "sqlite",
+    "databasePath": ".mycodemap/governance.sqlite"
+  },
+  "plugins": {
+    "builtInPlugins": true,
+    "plugins": [],
+    "debug": false
+  }
+}
+```
+
+## Defaults
+
+The following defaults are applied when a key is omitted from the config file or no config file exists:
+
+| Key | Default | Source |
+|---|---|---|
+| `mode` | `"tree-sitter"` | `src/cli/config-loader.ts:42` |
+| `include` | `["src/**/*.ts"]` | `src/cli/config-loader.ts:43` |
+| `exclude` | `["node_modules/**", "dist/**", "build/**", "coverage/**", ".venv/**", "**/__pycache__/**", "vendor/**", "**/*.test.ts", "**/*.spec.ts", "**/*.d.ts"]` | `src/core/file-discovery.ts:8` |
+| `output` | `".mycodemap"` | `src/cli/config-loader.ts:44` |
+| `watch` | `false` | `src/cli/config-loader.ts:254` |
+| `storage.type` | `"sqlite"` | `src/cli/config-loader.ts:243` |
+| `storage.databasePath` | `".mycodemap/governance.sqlite"` | `src/cli/config-loader.ts:244` |
+| `plugins.builtInPlugins` | `true` | `src/cli/config-loader.ts:235` |
+| `plugins.plugins` | `[]` | `src/cli/config-loader.ts:236` |
+| `plugins.debug` | `false` | `src/cli/config-loader.ts:237` |
+
+## Storage
+
+Supported storage types:
+
+- `sqlite` default persistent backend
+- `memory` for tests and ephemeral runs
+- `auto` as a SQLite-family alias
+
+Unsupported legacy backends are rejected:
+
+- `filesystem`
+- `kuzudb`
+- `neo4j`
+
+The storage factory now routes persistent storage through the SQLite family only.
+
+## Parser Mode
+
+The active parser mode is `tree-sitter`. Deprecated inputs `fast`, `smart`, and `hybrid` are rejected by the CLI and server entry points.
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `MYCODEMAP_RUNTIME_LOG_ENABLED` | Optional | `true` | Enable or disable runtime logs |
+| `MYCODEMAP_RUNTIME_LOG_DIR` | Optional | `.mycodemap/logs` | Set the runtime log directory |
+| `MYCODEMAP_RUNTIME_LOG_RETENTION_DAYS` | Optional | `14` | Retain logs for this many days |
+| `MYCODEMAP_RUNTIME_LOG_MAX_FILES` | Optional | `30` | Cap the number of runtime log files |
+| `MYCODEMAP_RUNTIME_LOG_MAX_SIZE_MB` | Optional | `10` | Cap the size of a single runtime log file |
+| `CODEMAP_USE_WASM_TREE_SITTER` | Optional | — | Force the tree-sitter loader to use WASM when set to `1` |
+| `CODEMAP_USE_WASM_BETTER_SQLITE3` | Optional | — | Force SQLite fallback behavior when set to `1` |
+| `GITHUB_TOKEN` | Optional | — | Preferred token for release monitoring and GitHub API access |
+| `GH_TOKEN` | Optional | — | Fallback token for release monitoring |
+| `SHIP_IN_CI` | Optional | — | Skip local release checks inside CI when set to `1` |
+
+The runtime logger accepts the `CODEMAP_*` legacy variables as fallbacks for the newer `MYCODEMAP_*` names:
+
+- `CODEMAP_RUNTIME_LOG_ENABLED` → fallback for `MYCODEMAP_RUNTIME_LOG_ENABLED`
+- `CODEMAP_RUNTIME_LOG_DIR` → fallback for `MYCODEMAP_RUNTIME_LOG_DIR`
+- `CODEMAP_RUNTIME_LOG_RETENTION_DAYS` → fallback for `MYCODEMAP_RUNTIME_LOG_RETENTION_DAYS`
+- `CODEMAP_RUNTIME_LOG_MAX_FILES` → fallback for `MYCODEMAP_RUNTIME_LOG_MAX_FILES`
+- `CODEMAP_RUNTIME_LOG_MAX_SIZE_MB` → fallback for `MYCODEMAP_RUNTIME_LOG_MAX_SIZE_MB`
+
+## Required vs Optional Settings
+
+All configuration settings are optional. CodeMap starts successfully with no configuration file and no environment variables set. If a config file is present, any omitted keys use the built-in defaults listed above. Invalid values (such as deprecated parser modes or unsupported storage types) cause the CLI to exit with an error rather than falling back silently.
+
+## Per-Environment Overrides
+
+No per-environment config files (`.env.development`, `.env.production`, `.env.test`) are built into CodeMap. Environment-specific behavior is controlled through:
+
+- **Environment variables** — set `MYCODEMAP_RUNTIME_LOG_ENABLED=false` in CI to disable log noise, or `SHIP_IN_CI=1` to skip local release checks.
+- **WASM toggles** — `CODEMAP_USE_WASM_TREE_SITTER` and `CODEMAP_USE_WASM_BETTER_SQLITE3` can be set per environment to force fallback behavior.
+- **Separate config files** — you can maintain distinct config files and point to them by placing the appropriate file in the project root, since CodeMap resolves `.mycodemap/config.json` → `mycodemap.config.json` → `codemap.config.json` in that order.
+
+## Operational Notes
+
+- `mycodemap generate` writes to `.mycodemap/` unless the config overrides `output`.
+- `mycodemap benchmark` toggles the WASM environment variables internally for each measurement.
+- `mycodemap ship` and release monitoring use GitHub token settings from the environment.

package/docs/DEVELOPMENT.md

@@ -0,0 +1,96 @@
+<!-- generated-by: gsd-doc-writer -->
+
+# Development Guide
+
+## Local setup
+
+Fork and clone the repository, then install dependencies and build:
+
+```bash
+git clone https://github.com/yuanyuanyuan/mycodemap.git
+cd mycodemap
+npm install
+npm run build
+```
+
+- **Node.js:** `>= 20.0.0` (required by `package.json` `engines`)
+- No `.env` file is required for local development.
+
+The build emits compiled output into `dist/`, and the package ships the CLI from `dist/cli/index.js`.
+
+## Build commands
+
+| Command | Description |
+|---|---|
+| `npm run dev` | Watch TypeScript compilation |
+| `npm run build` | Compile the project |
+| `npm run postbuild` | Copy static build assets after compilation |
+| `npm run typecheck` | Type-check without emitting files |
+| `npm run lint` | Run ESLint on `src/` |
+| `npm run fix:all` | Auto-fix lint issues |
+| `npm test` | Run the Vitest suite |
+| `npm run test:all` | Run tests and benchmarks together |
+| `npm run test:e2e` | Run workflow and integration-style tests |
+| `npm run benchmark` | Run benchmark checks |
+| `npm run docs:check` | Validate human and AI documentation |
+| `npm run docs:check:human` | Validate human-facing docs only |
+| `npm run docs:check:ai` | Validate AI-facing docs only |
+| `npm run docs:check:pre-release` | Pre-release docs validation |
+| `npm run check:all` | Full local gate (typecheck + lint + test + docs) |
+| `npm run check:security` | Run `npm audit` for security issues |
+| `npm run validate-pack` | Validate the package before publish |
+| `npm run release` | Run the release script |
+| `npm run ai:pre-task` | Pre-task validation gate (same as `check:all`) |
+| `npm run ai:post-task` | Auto-fix and re-run full validation gate |
+
+## Code style
+
+The project uses **ESLint** with the TypeScript plugin for linting. Configuration lives in `eslint.config.js`.
+
+- **Lint target:** `src/**/*.ts` (test files use relaxed rules)
+- **Run lint:** `npm run lint`
+- **Auto-fix:** `npm run fix:all`
+- **Key rules:** duplicate enum values are errors; unused vars, `any`, and non-null assertions are warnings
+
+There is no Prettier, Biome, or `.editorconfig` configured.
+
+## Branch conventions
+
+No explicit branch naming convention is documented. The CI pipeline runs against `main` and `develop`:
+
+- `main` — stable branch
+- `develop` — integration branch
+
+## PR process
+
+Follow these guidelines when opening a pull request:
+
+- Keep each PR focused on a single concern.
+- Include tests for any behavior changes.
+- Run `npm run check:all` before opening the PR.
+- Use the commit format `[TAG] scope: message`. Valid tags: `BUGFIX`, `FEATURE`, `REFACTOR`, `CONFIG`, `DOCS`, `DELETE`.
+- For `FEATURE` or `BUGFIX` commits, include a `[证据]` trail (path references or command output) in the commit message or PR description when you have real-world validation evidence.
+- Mention any remaining risks or skipped verification explicitly in the PR description.
+
+## Working Rules
+
+- Keep TypeScript files in ESM style with explicit exports.
+- Preserve the file headers that carry `[META]` and `[WHY]` annotations in source files.
+- Prefer small, surgical changes that match the surrounding code.
+- If a change touches CLI behavior, configuration, or public APIs, update the corresponding docs in the same change.
+
+## Local Feedback Loop
+
+Recommended loop for most changes:
+
+```bash
+npm run typecheck
+npm test
+npm run docs:check
+```
+
+For agent-driven work, `npm run ai:pre-task` and `npm run ai:post-task` wrap the same validation gates used in CI.
+
+## Release Notes
+
+`npm run release` invokes the release script, and `prepublishOnly` runs the pre-release docs check, build, and tests before publish. Treat those flows as gated operations, not casual dev commands.

package/docs/GETTING-STARTED.md

@@ -0,0 +1,114 @@
+<!-- generated-by: gsd-doc-writer -->
+
+# Getting Started
+
+## Prerequisites
+
+- Node.js `>= 20.0.0`
+- npm, pnpm, or yarn
+- A repository with source files to analyze
+
+The tool can run without native build toolchains. When native dependencies are unavailable, the runtime falls back to WASM paths.
+
+## Installation
+
+### Install from npm (recommended for users)
+
+```bash
+npm install -g @mycodemap/mycodemap
+```
+
+`mycodemap` is the primary binary. `codemap` is kept as an alias.
+
+### Build from source (for contributors)
+
+```bash
+git clone https://github.com/yuanyuanyuan/mycodemap.git
+cd mycodemap
+npm install
+npm run build
+```
+
+After building, run the CLI locally via `node dist/cli/index.js` or link it:
+
+```bash
+npm link
+mycodemap --help
+```
+
+## First Run
+
+```bash
+mycodemap init
+```
+
+By default, `init` prints a reconciliation preview. Use `--yes` to apply the plan immediately.
+
+If the repository has a recognizable project marker, `init` can auto-detect a profile. Use `--profile <name>` to override that detection.
+
+Next:
+
+```bash
+mycodemap generate
+mycodemap doctor
+```
+
+`generate` writes analysis artifacts to `.mycodemap/`. `doctor` checks the runtime, workspace, and agent integrations.
+
+## What Gets Written
+
+- `.mycodemap/config.json` as the canonical config file
+- `.mycodemap/codemap.json` as the persisted graph data
+- `.mycodemap/logs/` for runtime logs when enabled
+- additional generated reports depending on the command you run
+
+## Minimal Workflow
+
+1. Install the package.
+2. Run `mycodemap init` or `mycodemap init --yes`.
+3. Run `mycodemap generate`.
+4. Inspect the output in `.mycodemap/`.
+5. Run `mycodemap doctor` if something looks off.
+
+## Common Setup Issues
+
+### Command not found after global install
+
+If `mycodemap` is not recognized after `npm install -g`, refresh the shell hash or use `npx`:
+
+```bash
+hash -r
+npx mycodemap --help
+```
+
+### Native dependency build failures
+
+Packages like `tree-sitter` and `better-sqlite3` may require a C++ compiler on your system. If the install fails:
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install build-essential
+
+# macOS
+xcode-select --install
+```
+
+When native modules are unavailable, CodeMap falls back to WASM equivalents automatically.
+
+### Node.js version mismatch
+
+CodeMap requires Node.js `>= 20.0.0`. If you see an engine-unsupported error, upgrade Node.js or use a version manager such as `nvm`.
+
+## Common Follow-Up Commands
+
+- `mycodemap query` to search symbols and modules
+- `mycodemap deps` to inspect dependencies
+- `mycodemap impact -f <file>` to estimate change impact
+- `mycodemap benchmark` to compare native and WASM startup paths
+- `mycodemap --schema` to inspect the CLI contract
+
+## Next Steps
+
+- See [DEVELOPMENT.md](DEVELOPMENT.md) for local development setup, build commands, and contribution workflow.
+- See [TESTING.md](TESTING.md) for how to run the test suite and write new tests.
+- See [CONFIGURATION.md](CONFIGURATION.md) for the full config file format, environment variables, and per-environment overrides.

package/docs/README.md

@@ -1,6 +1,8 @@
 # docs/ - 文档信息架构
 
-本目录采用“入口文档短、细节文档分层”的结构。
+> **v2.0 里程碑上下文**：当前文档体系对应 CodeMap v2.0（”agent-native-foundation”）。v2.0 引入了 CLI-as-MCP 自动网关、接口契约 Schema、WASM-first 构建基础等核心能力。详见下方 [v2.0 文档索引](#v20-文档索引)。
+
+本目录采用”入口文档短、细节文档分层”的结构。
 
 ## 目录职责
 
@@ -11,6 +13,8 @@
 - `docs/product-specs/`：当前仍有效的产品规格与验收边界。
 - `docs/references/`：外部参考、设计系统、工具链资料。
 - `docs/archive/`：历史方案、迁移遗留、过期文档索引。
+- `docs/ai-guide/`：AI / Agent 集成指南（v2.0 新增）。
+- `src/cli/interface-contract/`：接口契约 Schema 定义（单一 Schema 生成 parser、MCP tool 定义、`--help-json`、shell 补全）。
 
 ## 当前状态
 
@@ -19,6 +23,20 @@
 - `docs/design-docs/` 与 `docs/product-specs/` 当前不再保留旧稿；历史内容请从 `docs/archive/README.md` 进入。
 - 新增内容优先写入分层目录，不再把新设计或新计划继续堆到根层。
 
+### v2.0 功能状态
+
+v2.0（"agent-native-foundation"）已引入以下核心能力，相关文档已就位：
+
+| 功能 | 状态 | 文档位置 |
+|------|------|----------|
+| **CLI-as-MCP 自动网关** | 已交付 | `docs/ai-guide/INTEGRATION.md` |
+| `codemap doctor` 持续健康诊断 | 已交付 | `AI_GUIDE.md` + `src/cli/doctor/` |
+| `codemap benchmark` WASM/Native 性能对比 | 已交付 | `AI_GUIDE.md` |
+| `--schema` 接口契约输出 | 已交付 | `AI_GUIDE.md` + `src/cli/interface-contract/` |
+| WASM-first 构建基础 | 已交付 | `AI_GUIDE.md` + `src/cli/loaders/` |
+| AI-First 默认输出（JSON/NDJSON） | 已交付 | `AI_GUIDE.md` |
+| Failure-to-Action 协议 | 已交付 | `docs/rules/harness.md` |
+
 ## 建议阅读顺序
 
 1. `../AGENTS.md`
@@ -28,6 +46,27 @@
 5. 与任务最相关的现行文档；如需历史背景，再看 `docs/archive/README.md`
 6. 如需过程信息，再看 `docs/exec-plans/*`
 
+## v2.0 文档索引
+
+以下文档涵盖 v2.0 核心功能，按主题分类：
+
+### AI / Agent 集成
+- `docs/ai-guide/INTEGRATION.md` — CLI-as-MCP 自动网关配置指南（动态 tool 注册、20+ 命令自动暴露）
+- `docs/ai-guide/AI_ASSISTANT_SETUP.md` — AI 助手（Kimi、Claude、Codex、Cursor、Copilot）集成配置
+- `AI_GUIDE.md` — CodeMap CLI / MCP / AI 使用总览（含 `doctor`、`benchmark`、`--schema` 用法）
+
+### 接口契约与 Schema
+- `src/cli/interface-contract/` — 单一 Schema 源文件（生成 parser、MCP tool 定义、`--help-json`、shell 补全）
+- 运行 `codemap --schema` 可输出完整契约 JSON，供 Agent 自省
+
+### Harness 与 Agent 控制
+- `docs/rules/harness.md` — Harness 设计、Agent 控制、上下文分层、权限升级策略
+- `docs/rules/harness.md` — Failure-to-Action 协议（每个错误返回 `rootCause` + `remediationPlan` + `confidence` + `nextCommand`）
+
+### 架构与构建
+- `ARCHITECTURE.md` — 架构分层、依赖方向、模块边界
+- `src/cli/loaders/` — WASM-first 构建基础（`tree-sitter` → `web-tree-sitter`；`better-sqlite3` → `node:sqlite` / `sql.js`）
+
 ## 维护规则
 
 - 入口文档只做导航，不复述大段细节。

package/docs/SETUP_GUIDE.md

@@ -96,6 +96,55 @@ mycodemap init -y
 
 `init` 会同步 `.mycodemap/hooks/` 与 `.mycodemap/rules/`，但不会自动改写 `CLAUDE.md` / `AGENTS.md`；相关引用片段会通过 receipt 提示你手动加入。
 
+#### 理解 Init 收据
+
+`mycodemap init` 完成后会输出一份收据，分为两个部分：
+
+**Main Agent（主 Agent 上下文）**
+- 报告已生成的上下文文件路径（如 `claude-context.md`、`agents-context.md`）
+- 指导你将相关内容手动合并到项目根目录的 `CLAUDE.md` / `AGENTS.md`
+- 检测已同步状态：如果 `CLAUDE.md` 已包含 `.mycodemap/` 引用，标记为 `already-synced`
+
+**Subagent（子 Agent 配置）**
+- 报告平台配置示例文件（如 `claude-hook-example.json`、`codex-agent-example.toml`）
+- 指导你将配置复制到对应平台设置目录
+
+收据还会显示**个性化下一步**，基于实际安装的资产生成，而非固定的三步欢迎信息。
+
+> 注意：`init` 不会自动改写 `CLAUDE.md`、`AGENTS.md` 等团队共管文件。所有需要手动操作的步骤都会在收据中明确标注。
+
+#### 环境契约（Environment Contract）
+
+`mycodemap init` 还会生成 `.mycodemap/env-contract.json`，这是一个结构化的项目规则索引，包含：
+
+- **执行规则**：shell 命令包装（rtk）、测试入口命令（vitest run）
+- **提交规则**：commit message 格式（`[TAG] scope: message`）、有效标签列表
+- **验证规则**：真实场景验证要求、代码质量标准
+- **来源追踪**：每条规则的源文件和 hash，用于漂移检测
+
+子代理（Claude Code / Codex CLI 的委托代理）通过以下方式检索契约：
+
+```bash
+# CLI 检索（按代理类型过滤）
+mycodemap env-contract --for worker --json
+mycodemap env-contract --for explore --json
+
+# MCP 检索
+codemap_env_contract(agentType="worker")
+```
+
+检查契约一致性和源文件漂移：
+
+```bash
+# 检查契约是否过期或缺失关键项
+mycodemap env-contract --check
+
+# 全面健康诊断（包含 env-contract 状态）
+mycodemap doctor
+```
+
+> 冲突（如 hook 要求大写标签但文档示例写小写）会被报告为警告，不会阻断。源文件漂移会导致 `--check` 返回非零退出码，需要运行 `mycodemap env-contract --update` 重新生成。
+
 生成的 canonical 配置文件 `.mycodemap/config.json`：
 
 ```json
@@ -210,24 +259,21 @@ mycodemap impact -f src/cli/index.ts --transitive
 ### 统一分析（analyze）
 
 ```bash
-# 影响分析
-mycodemap analyze -i impact -t src/cli/index.ts
-mycodemap analyze -i impact -t src/cli/index.ts --scope transitive --include-tests
+# 搜索符号或文件
+mycodemap analyze -i find -k "UnifiedResult" --topK 10
 
-# 依赖分析
-mycodemap analyze -i dependency -t src/orchestrator
+# 读取代码范围
+mycodemap analyze -i read -t src/cli/index.ts
+mycodemap analyze -i read -t src/cli/index.ts --scope transitive --include-tests
 
-# 复杂度分析
-mycodemap analyze -i complexity -t src/domain
+# 查看模块依赖关系
+mycodemap analyze -i link -t src/orchestrator
 
-# 搜索分析
-mycodemap analyze -i search -k "UnifiedResult" --topK 10
+# 展示项目概览或复杂度
+mycodemap analyze -i show -t src/
 
-# 项目概览
-mycodemap analyze -i overview -t src/
-
-# JSON 输出
-mycodemap analyze -i impact -t src/index.ts --json
+# JSON 结构化输出
+mycodemap analyze -i find -k "UnifiedResult" --json --structured
 ```
 
 ### 工作流编排（workflow）