diff --git a/Cargo.lock b/Cargo.lock
index 0a972c7bb..dd482bc7a 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -814,7 +814,7 @@ checksum = "d0881ea181b1df73ff77ffaaf9c7544ecc11e82fba9b5f27b262a3c73a332555"
[[package]]
name = "ecp-analyzer"
-version = "0.3.0"
+version = "0.4.0"
dependencies = [
"aho-corasick",
"anyhow",
@@ -871,7 +871,7 @@ dependencies = [
[[package]]
name = "ecp-core"
-version = "0.3.0"
+version = "0.4.0"
dependencies = [
"anyhow",
"cc",
@@ -904,7 +904,7 @@ dependencies = [
[[package]]
name = "ecp-mcp"
-version = "0.3.0"
+version = "0.4.0"
dependencies = [
"anyhow",
"clap",
@@ -916,7 +916,7 @@ dependencies = [
[[package]]
name = "egent-code-plexus"
-version = "0.3.0"
+version = "0.4.0"
dependencies = [
"chrono",
"clap",
diff --git a/Cargo.toml b/Cargo.toml
index 48f3d6c22..97a1c5cfe 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -21,7 +21,7 @@ exclude = [
resolver = "2"
[workspace.package]
-version = "0.3.0"
+version = "0.4.0"
edition = "2021"
authors = ["E-NoR"]
license = "MIT OR Apache-2.0"
diff --git a/README.md b/README.md
index 24337faa9..6ff899c22 100644
--- a/README.md
+++ b/README.md
@@ -1,49 +1,51 @@
# EgentCodePlexus
-[](https://scorecard.dev/viewer/?uri=github.com/coseto6125/egent-code-plexus)
-[](https://star-history.com/#coseto6125/egent-code-plexus&Date)
+Structural code knowledge for AI agents. One-shot CLI, zero-copy mmap, ~140 ms per query.
-A code intelligence graph for **LLMs and AI code agents** — one-shot CLI, zero-copy mmap, sub-second per query.
+`cold index 2.60 s · query p50 142 ms · 31 languages · BlindSpot edges (no hallucinated dispatch) · 60× upstream gitnexus`
-[繁體中文 (Traditional Chinese)](./docs/readme_i18n/README_zh-TW.md)
-
----
-
-## 🎯 Mission
+[](https://scorecard.dev/viewer/?uri=github.com/coseto6125/egent-code-plexus)
+[](https://github.com/coseto6125/egent-code-plexus/releases)
+[](https://github.com/coseto6125/egent-code-plexus/releases)
+[](https://github.com/coseto6125/egent-code-plexus/releases)
+[](https://github.com/coseto6125/egent-code-plexus/blob/main/skill_sample/claude/SKILL.md)
+[](https://github.com/coseto6125/egent-code-plexus/blob/main/skill_sample/codex/ecp/SKILL.md)
+[](https://github.com/coseto6125/egent-code-plexus/blob/main/docs/skills/ecp-onboard/guides/04-mcp.md)
-`ecp` exists to be the structural-knowledge layer that an autonomous AI coding agent calls 20–50 times per task. Every design decision falls out of that one premise:
+**English** · [繁體中文](./docs/readme_i18n/README_zh-TW.md) · [简体中文](./docs/readme_i18n/README_zh-CN.md) · [Español](./docs/readme_i18n/README_es.md) · [Русский](./docs/readme_i18n/README_ru.md) · [हिन्दी](./docs/readme_i18n/README_hi.md) · [日本語](./docs/readme_i18n/README_ja.md) · [한국어](./docs/readme_i18n/README_ko.md) · [Português (BR)](./docs/readme_i18n/README_pt-BR.md)
-- **Built for agents, not IDEs.** Output is token-cheap (TOON / compact JSON), every flag surfaces via `--help`, every command is non-interactive and stdout-parseable. No UI, no human-skim layout cruft eating the agent's context window.
-- **No warm-up, no daemon.** Each invocation `mmap`s a zero-copy `rkyv` graph file and exits. Read queries return in **~140–170 ms** *including process startup*; a 22k-file repo cold-indexes in under 3 s. An agent can fire dozens of queries per task without amortising a server boot, and there is no "daemon died, please restart" failure mode.
-- **Honest answers over readable graphs.** When a call site can't be statically resolved (dynamic dispatch, unresolved import, reflection), `ecp` emits a `BlindSpot` record — not a guessed edge. An agent that acts on a hallucinated dependency is much more expensive than one that gets an "I don't know" it can route around.
-- **Polyglot reach.** 31 languages parsed at the structural level so modern multi-stack repos (service code + Dockerfiles + GitHub Actions + Terraform + SQL + smart contracts) stop being black holes the moment you leave the main language.
+---
-🎙️ **[Agent Interviews](./interviews/README.md)** — See how real AI agents (Gemini CLI, Codex) use and evaluate `ecp` in autonomous workflows.
+## The case
-Built on top of [GitNexus](https://github.com/abhigyanpatwari/GitNexus) by [Abhigyan Patwari](https://github.com/abhigyanpatwari) — same conceptual model (a structural knowledge graph of a repo), rewritten in Rust for a different audience. Licensed under [PolyForm Noncommercial 1.0.0](./LICENSE.md); see [NOTICES.md](./LICENSES/NOTICES.md) for required attribution.
+Code agents fan out 20–50 lookups per task. Grep returns strings; an autonomous agent needs symbols, callers, edges, and an honest signal when the static graph runs out.
----
+`ecp` is the structural-knowledge layer that is:
-## ⚡ Performance
+- **stateless.** Every invocation `mmap`s a zero-copy `rkyv` graph and exits. No daemon to keep warm, no "server died, restart" failure mode.
+- **honest.** Unresolvable call sites (dynamic dispatch, unresolved import, reflection) become `BlindSpot` records. An agent that acts on a hallucinated dependency costs more than one that gets an "I don't know" and routes around.
+- **token-cheap.** Default output is TOON (compact key:value). Every flag surfaces via `--help`. Every command is non-interactive and stdout-parseable.
+- **polyglot.** 31 languages parsed at the structural level — service code, Dockerfiles, GitHub Actions, Terraform, SQL, and smart contracts stay legible the moment you leave the main language.
-The Mission section above is *why* `ecp` is built the way it is. This section is the receipts.
+Built on top of [GitNexus](https://github.com/abhigyanpatwari/GitNexus) by [Abhigyan Patwari](https://github.com/abhigyanpatwari) — same conceptual model, rewritten in Rust for a different audience. 🎙️ [Agent interviews](./interviews/README.md) — Gemini CLI and Codex evaluate `ecp` in autonomous workflows.
-### Head-to-head vs. upstream GitNexus
+## Receipts
-Measured on the [gitnexus](https://github.com/abhigyanpatwari/GitNexus) codebase (TypeScript) using `scripts/parity/benchmark_vs_gitnexus.py`:
+Head-to-head vs. upstream GitNexus, measured on the [gitnexus](https://github.com/abhigyanpatwari/GitNexus) codebase (TypeScript) using `scripts/parity/benchmark_vs_gitnexus.py`:
| Phase | ecp (Rust) | gitnexus (Node) | Speedup |
|---|---|---|---|
-| **Cold Index** | **~970 ms** | ~58 s | **60×** |
-| **Symbol Context** | **~70 ms** | ~430 ms | **6×** |
-| **Blast Radius** | **~70 ms** | ~460 ms | **6×** |
-| **Cypher Query** | **~70 ms** | ~400 ms | **5×** |
+| Cold Index | **~970 ms** | ~58 s | **60×** |
+| Symbol Context | **~70 ms** | ~430 ms | **6×** |
+| Blast Radius | **~70 ms** | ~460 ms | **6×** |
+| Cypher Query | **~70 ms** | ~400 ms | **5×** |
-*Note: `ecp` query latency includes full process startup (no daemon). GitNexus (v1.6.5) query latency is against a warm, indexed repo via its CLI.*
+`ecp` numbers include full process startup (no daemon). GitNexus (v1.6.5) numbers are against a warm, indexed repo via its CLI.
-### Scalability — single run on `.sample_repo` (a 2.1 GB polyglot collection of ~40 real-world open source projects across 25+ languages, used for cross-language stress testing)
+
+Scalability — single run on .sample_repo (2.1 GB polyglot, ~40 OSS projects, 25+ languages)
-**Ingest performance:**
+**Ingest performance**
| Phase | Value |
|---|---|
@@ -52,7 +54,7 @@ Measured on the [gitnexus](https://github.com/abhigyanpatwari/GitNexus) codebase
| Wall-clock (Incremental) | **4.9 ms** (xxh3_64 hash walk, zero dirty files) |
| Hardware | AMD Ryzen 9 9950X (16 logical), 39.2 GiB RAM, Linux 6.6.87 |
-**Per-query latency (including process startup):**
+**Per-query latency** (including process startup)
| Query | Median | Notes |
|---|---|---|
@@ -60,37 +62,58 @@ Measured on the [gitnexus](https://github.com/abhigyanpatwari/GitNexus) codebase
| `routes` (HTTP route map across repo) | **142.3 ms** | enumerates declarative + imperative |
| `summary --detailed` (frameworks + blind-spots) | **143.4 ms** | full registry + per-framework scoring |
| `impact --direction down` | **145.0 ms** | BFS over Calls / Extends edges |
-| `inspect ` (signature + callers + callees) | **145.6 ms** | symbol resolution + 1-hop traversal |
-| `find --mode bm25` (lexical search) | **154.5 ms** | Tantivy query + 5-bucket partition |
-| `cypher 'MATCH (a:Class)-[:HasMethod]->(b:Method) ...'` | **161.5 ms** | one pattern, one row returned |
+| `inspect ` | **145.6 ms** | symbol resolution + 1-hop traversal |
+| `find --mode bm25` | **154.5 ms** | Tantivy query + 5-bucket partition |
+| `cypher 'MATCH (a:Class)-[:HasMethod]->(b:Method) ...'` | **161.5 ms** | one pattern, one row |
| `cypher 'MATCH (a:Method)-[:Calls]->(b:Method) ...'` | **174.2 ms** | broader pattern, more matches |
| `impact --baseline HEAD~1` (change-set blast radius) | **359.0 ms** | git diff + parallel per-file parse + BFS |
Reproduce: `python scripts/benchmark/benchmark_ecp.py`.
----
+
-## vs. upstream GitNexus
+## vs. upstream gitnexus
-Same conceptual model, different audience. `ecp` is **not** a drop-in replacement — choose based on who reads the graph and what they do with it.
+Same conceptual model, different audience. `ecp` is **not** a drop-in replacement — choose based on who reads the graph.
| Dimension | EgentCodePlexus | GitNexus |
|---|---|---|
| Primary consumer | Autonomous AI code agents | Human devs + IDE integration |
| Runtime | Stateless one-shot CLI (zero warm-up) | Long-running MCP server |
-| Performance | **< 2.5s cold index / < 150ms query** | ~60s cold index / ~400ms query |
+| Performance | **< 2.5 s cold index / < 150 ms query** | ~60 s cold index / ~400 ms query |
| Unresolved edge | `BlindSpot` record (honest unknown) | Heuristic guess |
| Default output | TOON / compact JSON (token-cheap) | Wiki / UI rendering |
| Languages | 31 (14 deep + 17 structural) | 14 (deep, 9-dimension) |
| Storage | Rust + `rkyv` zero-copy mmap | Node.js + LadybugDB |
-**Full breakdown of all 8 dimensions, philosophy, and decision matrix → [docs/vs-gitnexus.md](./docs/vs-gitnexus.md)**
+Full 8-dimension breakdown + decision matrix → [docs/vs-gitnexus.md](./docs/vs-gitnexus.md).
----
+## 30-second demo
+
+```bash
+$ ecp impact parse_with_budget --direction upstream --format toon
+```
+
+```text
+target parse_with_budget
+ kind Function
+ file crates/ecp-analyzer/src/parse_budget.rs:28
+risk_level HIGH
+direct_callers 22 across 22 files
+ crates/ecp-analyzer/src/python/parser.rs:48 Method parse_file
+ crates/ecp-analyzer/src/rust/parser.rs:142 Method parse_file
+ crates/ecp-analyzer/src/typescript/parser.rs:73 Method parse_file
+ crates/ecp-analyzer/src/go/parser.rs:69 Method parse_file
+ ... (18 more language parsers)
+transitive 231 symbols across language detection + pipeline
+blind_spots 0
+```
-## 📦 Install
+One process, one mmap, ~140 ms. Real symbol from this repo — every per-language `parser.rs` fans in via the budget primitive. Read-side commands accept `--format text|json|toon`; the default per command is whichever encoding is cheapest in tokens.
-Prebuilt binaries are published with each GitHub Release. The installer scripts fall back to a cargo source build only when a matching release asset is unavailable.
+## Install
+
+Prebuilt binaries ship with every GitHub Release. The installer scripts fall back to a cargo source build only when a matching release asset is unavailable.
```bash
# Linux / macOS
@@ -103,24 +126,25 @@ iwr https://github.com/coseto6125/egent-code-plexus/releases/latest/download/ins
cargo install --git https://github.com/coseto6125/egent-code-plexus egent-code-plexus --bin ecp --locked
```
-Optional CPU-tuned source build:
+
+CPU-tuned source build
```bash
repo=https://github.com/coseto6125/egent-code-plexus
RUSTFLAGS="-C target-cpu=native" cargo install --git "$repo" egent-code-plexus --bin ecp --locked --profile release-dist
```
----
+
-## 🚀 Quick start
+## Quick start
```bash
-# 1. Index the current repo (incremental; first query also auto-indexes)
+# 1. Index the current repo (incremental; first query auto-indexes too)
ecp admin index --repo .
# 2. Locate a symbol — exact name by default
ecp find loginUser
-ecp find login --mode bm25 # ranked BM25, top-K partitioned by source/tests/ref/doc/config
+ecp find login --mode bm25 # ranked BM25, top-K bucketed by source/tests/ref/doc/config
# 3. Blast radius — who breaks if I change this?
ecp impact validateUser --direction upstream
@@ -136,21 +160,19 @@ ecp routes /api/users --method POST # route → handler → caller chain
ecp impact --literal session_meta.json # 14 langs; sink:read / sink:write / sink:join / sink:free
```
-Read-side commands accept `--format text|json|toon`. Default per command is the token-cheapest representation (mostly `toon`; `find` defaults to `text`; `cypher`/`summary` default to `json`).
-
----
+Read-side commands accept `--format text|json|toon`. Default per command is the token-cheapest representation (mostly `toon`; `find` defaults to `text`; `cypher` defaults to `json`).
## CLI surface
-Two tiers — **agent commands** at top level (query/refactor/verify) and **admin commands** under `ecp admin` (registry/hooks/destructive). Run `ecp --help` and `ecp admin --help` for full flag matrices.
+Two tiers — **agent commands** at top level (query / refactor / verify) and **admin commands** under `ecp admin` (registry / hooks / destructive). Run `ecp --help` and `ecp admin --help` for full flag matrices.
| Command | Purpose |
|---|---|
| `inspect ` | One symbol → metadata, decorators, signature, callers, callees, 1-hop impact, contained methods / properties / enum variants |
| `find ` | Locate symbols — exact (default) · `--mode fuzzy` substring · `--mode bm25` lexical ranking; bm25 partitions output into source / tests / reference / document / config buckets |
-| `find-schema-bindings ` | Surface MirrorsField heuristic edges + blind-spot candidates (schema field mirrors across classes / services). Format: toon (default) or json. |
-| `find-transaction-patterns [--class ]` | Detect Saga compensate/undo/rollback name-pairs on same class. Confidence ≥0.75 tier:POSSIBLY_RELATED, <0.75 tier:BLIND_SPOT. Outbox half deferred (T5-33). |
-| `impact --direction ` | Blast-radius traversal with confidence filtering. `--since [` for change-set impact. |
+| `find-schema-bindings ` | Surface MirrorsField heuristic edges + blind-spot candidates (schema field mirrors across classes / services). |
+| `find-transaction-patterns [--class ]` | Detect Saga compensate/undo/rollback name-pairs on same class. Confidence ≥0.75 tier:POSSIBLY_RELATED, <0.75 tier:BLIND_SPOT. |
+| `impact --direction ` | Blast-radius traversal with confidence filtering. `--baseline ][` for change-set impact (also `--literal ` for PathLiteral split-brain). |
| `rename --symbol --new-name ` | AST-aware multi-file rename across 14 languages. Always `--dry-run` first. |
| `cypher ''` | openCypher escape hatch; `m.content` returns source body. |
| `summary` | Registry overview, framework coverage, LLM-actionable blind-spot catalog, graph freshness. (Was `coverage`; the old verb still works as an alias.) |
@@ -159,10 +181,11 @@ Two tiers — **agent commands** at top level (query/refactor/verify) and **admi
| `diff` | Resolver-delta — edge-level binding tier-degradation + route / contract changes. |
| `tool-map` | Calls to external HTTP / DB / Redis / queue clients via per-file import-binding analysis. |
| `shape-check` | Drift between HTTP consumer access patterns and Route response shapes. |
-| `peers` | Multi-session peer collaboration: `status` / `diff` / `say` / `inbox` / `log` / `thread` / `watch` / `gc`. See [Multi-session peer sync](#multi-session-peer-sync). |
-| `review` | Aggregated LLM-workflow audit: runs impact + coverage + tool-map + shape-check + diff in one shot, filtered to high-confidence signals. |
+| `peers` | Multi-session peer collaboration: `status` / `diff` / `say` / `inbox` / `log` / `thread` / `watch` / `gc`. |
+| `review` | LLM-workflow audit aggregator — impact + summary + tool-map + shape-check + diff, filtered to high-confidence signals. |
-Admin namespace (`ecp admin ` — hidden from top-level help):
+]
+Admin namespace — ecp admin <cmd> (registry / hooks / destructive)
| Command | Purpose |
|---|---|
@@ -171,9 +194,12 @@ Admin namespace (`ecp admin ` — hidden from top-level help):
| `install-hook` | Install the git reference-transaction hook (auto-track branch switches). |
| `config` | Interactive TOML wizard for `.ecp/config.toml`. |
| `mcp serve` / `mcp tools` | MCP server (stdio) for LLM hosts; `tools` lists the exposed tool surface. |
+| `claude install / codex install / gemini install` | Scriptable host integration (skills, hooks, MCP entries). |
+| `verify-resolver` | Diff resolver dump against a language oracle (ecp-dev QA). |
+
+
-All commands resolve `.ecp/graph.bin` from CWD unless `--graph ` is given. Agent-facing commands are non-interactive by design — every flag surfaces via `--help`, every output stream is parseable.
-Run `ecp admin` with no subcommand to open the interactive admin TUI for index maintenance, host integrations, config, groups, and diagnostics.
+All commands resolve `.ecp/graph.bin` from CWD unless `--graph ` is given. Agent-facing commands are non-interactive by design. Run `ecp admin` with no subcommand to open the interactive admin TUI.
### Multi-session peer sync
@@ -236,99 +262,79 @@ ecp review --since main --verdicts --format json
Every verdict cites the exact diff section and graph fact that triggered it; see [Provable Verdicts Design Spec](./docs/specs/2026-05-22-review-verdicts.md) for semantics, provability invariants, and deferred features.
----
-
-## MCP server (for LLM hosts)
+## MCP server
-`ecp` ships an MCP server exposing core commands as MCP tools. Hosts that speak MCP (Claude Code, Cursor, Windsurf, Cline, Codex CLI, Gemini CLI) can register `ecp` and call the tools autonomously.
+`ecp` ships an MCP server exposing core commands as MCP tools. Hosts that speak MCP (Claude Code, Cursor, Windsurf, Cline, Codex CLI, Gemini CLI) register `ecp` and call the tools autonomously.
```bash
ecp admin mcp tools # inspect what tools will be exposed
-ecp admin mcp serve # run the server (default: spawn mode, fresh subprocess per call)
+ecp admin mcp serve # run the server
```
-Manual host config example for Claude Code (`~/.config/claude-code/mcp-servers.json`):
+Scripted host install:
+
+```bash
+ecp admin claude install mcp-server
+ecp admin gemini install skills
+```
+
+Progressive path (TUI): `ecp admin → Agent Integrations → MCP → → install`.
+
+
+Manual mcp.json snippet — Cursor / Windsurf / Cline (no scripted installer yet)
+
+These hosts read an `mcp.json` (or equivalent) but the file location varies per IDE. Paste this server entry into the host's MCP config; the binary just needs to be on `$PATH`:
```json
{
"mcpServers": {
- "ecp": { "command": "ecp", "args": ["admin", "mcp", "serve"] }
+ "ecp": {
+ "command": "ecp",
+ "args": ["admin", "mcp", "serve"]
+ }
}
}
```
-Progressive path for human operators:
+Per-host file:
-```text
-ecp admin
-→ Agent Integrations
-→ MCP
-→
-→ install
-```
+- **Cursor** → `~/.cursor/mcp.json` (global) or `/.cursor/mcp.json` (per-project)
+- **Windsurf** → `~/.codeium/windsurf/mcp_config.json`
+- **Cline** → VS Code settings → `cline.mcpServers` (object keyed the same way)
-## Codex CLI native integration
+After saving, restart the IDE; verify with `ecp admin mcp tools` matches what the host now lists.
-The Codex native path is separate from MCP. It prepares a patch for an `openai/codex` fork instead of editing the running Codex installation directly:
+
-Progressive path for human operators:
+
+Codex CLI native integration (separate from MCP — prepares a patch for an openai/codex fork)
-```text
-ecp admin
-→ Agent Integrations
-→ Codex CLI
-→ install
-→ native-tools
-```
-
-Bundled skills use the same progressive path:
+The Codex native path doesn't edit the running Codex installation; it writes a patch you apply to an `openai/codex` fork.
-```text
-ecp admin
-→ Agent Integrations
-→ Codex CLI
-→ install
-→ skills
-→ all | ecp | simplify
-```
+Progressive path: `ecp admin → Agent Integrations → Codex CLI → install → native-tools`.
-Scripted path for AI agents and automation:
+Scripted:
```bash
ecp admin codex install native-tools
-ecp admin codex install skills all
-ecp admin codex install skills ecp
-ecp admin codex install skills simplify
+ecp admin codex install skills all # or: ecp | simplify
```
-The bundled skills teach workflow selection that command help cannot infer by itself:
+Bundled skills teach workflow selection that command help can't infer:
| Skill | Use when |
|---|---|
-| `ecp` | The agent needs to decide whether graph-aware symbol, impact, route, contract, or rename workflows are better than grep / file reads. |
-| `simplify` | The agent is reviewing changed code and should start from ecp impact, blind spots, egress, shape drift, and resolver deltas before reading raw diffs. |
-
-The `native-tools` component writes:
+| `ecp` | Agent needs to decide whether graph-aware symbol / impact / route / contract / rename workflows beat grep / file reads. |
+| `simplify` | Agent is reviewing changed code and should start from `ecp impact`, blind spots, egress, shape drift, and resolver deltas before reading raw diffs. |
-```text
-~/.config/ecp/host-integration/codex-cli.patch
-```
-
-Apply the patch in your Codex CLI fork, then wire the generated module into Codex's tool registry:
+The `native-tools` component writes `~/.config/ecp/host-integration/codex-cli.patch`. Apply in your fork:
```bash
cd /path/to/openai-codex-fork
git apply ~/.config/ecp/host-integration/codex-cli.patch
```
-To verify a fork that already has the native marker, set `ECP_CODEX_CLI_CHECKOUT` before checking status in the TUI:
-
-```bash
-ECP_CODEX_CLI_CHECKOUT=/path/to/openai-codex-fork ecp admin
-# Agent Integrations → Codex CLI → status
-```
-
-The equivalent scripted checks are:
+Verify a fork that already has the native marker:
```bash
ECP_CODEX_CLI_CHECKOUT=/path/to/openai-codex-fork ecp admin codex status
@@ -336,56 +342,60 @@ ecp admin codex uninstall native-tools
ecp admin codex uninstall skills all
```
----
+
## Architecture
```
crates/
-├── ecp-core # Zero-copy graph (rkyv + mmap), incremental cache, graph queries
-├── ecp-analyzer # Tree-sitter parsers, HTTP route detector, framework confidence
-├── ecp-mcp # MCP server (stdio) — exposes core commands as tools
-└── ecp-cli # `ecp` binary, Tantivy BM25 engine, token-optimized output
+├── ecp-core Zero-copy graph (rkyv + mmap), incremental cache, graph queries
+├── ecp-analyzer Tree-sitter parsers, HTTP route detector, framework confidence
+├── ecp-mcp MCP server (stdio) — exposes core commands as tools
+└── ecp-cli `ecp` binary, Tantivy BM25 engine, token-optimized output
```
-Parse → resolve → serialize runs through an MPSC channel into a single builder thread that assembles the graph and writes a zero-copy `.ecp/graph.bin`. Read paths (`inspect`, `cypher`, `impact`, …) mmap this file directly. The xxh3_64 content cache keeps incremental rebuilds at sub-second on a 22k-file repo.
-
----
+Parse → resolve → serialize runs through an MPSC channel into a single builder thread that assembles the graph and writes a zero-copy `.ecp/graph.bin`. Read paths (`inspect`, `cypher`, `impact`, …) mmap this file directly. The xxh3_64 content cache keeps incremental rebuilds sub-second on a 22k-file repo.
## Language coverage
31 languages parsed at the structural level (functions / classes / methods / imports / calls). 14 of them — the original GitNexus set — get full-depth coverage across imports, named bindings, exports, heritage, types, constructors, config, frameworks, entry points, calls, and rename. The remaining 17 are structural-only (Bash, Crystal, Cairo, Dockerfile, Docker Compose, GitHub Actions, HCL, Lua, Markdown, Move, Nim, Solidity, SQL, Verilog, Vyper, YAML, Zig).
-📊 **[Full Language Capability Matrix](./docs/language-matrix.md)** — Detailed per-language status and rationale.
-
----
+📊 [Full Language Capability Matrix](./docs/language-matrix.md) — per-language status and rationale.
-## ⚙️ Tuning
+## Tuning
| Env var | Default | Effect |
|---|---|---|
| `ECP_MAX_FILE_BYTES` | `16777216` (16 MiB) | Skip source files larger than this during ingest. Caps worst-case worker RAM at `num_threads × MAX`. |
| `ECP_CSPROJ_MAX_DEPTH` | `4` | Directory recursion depth for `*.csproj` discovery. Raise for deeply-nested .NET monorepos. |
----
+## License
-## License & acknowledgments
+Licensed under [PolyForm Noncommercial 1.0.0](./LICENSE.md). Personal use, research, hobby projects, and noncommercial organizations are permitted. **Commercial use is not granted by this license** — contact upstream GitNexus author [Abhigyan Patwari](https://github.com/abhigyanpatwari) for commercial rights. See [NOTICES.md](./LICENSES/NOTICES.md) for required attribution.
-Licensed under [PolyForm Noncommercial 1.0.0](./LICENSE.md). Personal use, research, hobby projects, and noncommercial organizations are explicitly permitted. **Commercial use is not granted by this license** — contact the upstream GitNexus author Abhigyan Patwari for commercial rights.
+
+Built on (acknowledgments)
-Built on:
-- [GitNexus](https://github.com/abhigyanpatwari/GitNexus) — original design, CLI surface, and conceptual model
-- [tree-sitter](https://tree-sitter.github.io/) — robust incremental AST parsing
+- [GitNexus](https://github.com/abhigyanpatwari/GitNexus) — original design, CLI surface, conceptual model
+- [tree-sitter](https://tree-sitter.github.io/) — incremental AST parsing
- [rkyv](https://rkyv.org/) — zero-copy deserialization framework
-- [Tantivy](https://github.com/quickwit-oss/tantivy) — blazing fast Rust full-text search engine
+- [Tantivy](https://github.com/quickwit-oss/tantivy) — Rust BM25 search engine
- [Rayon](https://github.com/rayon-rs/rayon) — data parallelism for multi-core concurrent AST parsing
-- [xxhash (xxh3_64)](https://xxhash.com/) — extremely fast non-cryptographic hashing for content-based incremental indexing
-- [DashMap](https://github.com/xacrimon/dashmap) — high-performance concurrent hash maps for graph assembly
+- [xxhash (xxh3_64)](https://xxhash.com/) — content-based incremental indexing
+- [DashMap](https://github.com/xacrimon/dashmap) — concurrent hash maps for graph assembly
- [memmap2](https://github.com/RazrFalcon/memmap2-rs) — zero-copy memory mapping for sub-millisecond graph access
-- [msgspec](https://github.com/jcrist/msgspec) — high-performance JSON serialization for inter-process communication
+- [msgspec](https://github.com/jcrist/msgspec) — fast JSON serialization for IPC
+
+Onboarding for AI agents lives at `docs/skills/ecp-onboard/`. Concurrency invariants and how to re-verify them: `./scripts/audit/audit-concurrency.sh`.
-Onboarding for AI agents (URL bootstrap, Claude Code skill, plugin install) lives at `docs/skills/ecp-onboard/`. Concurrency invariants and how to re-verify them: `./scripts/audit/audit-concurrency.sh`.
+
## Release status
-The current verified install path is `cargo install --git ...`, which builds `ecp` from source. Release installers already contain the checksum and provenance-verification flow, but they require a published tag and release assets before the binary download path can be end-to-end verified. The agent-facing onboarding skill is documented in [docs/skills/ecp-onboard/ONBOARDING.md](./docs/skills/ecp-onboard/ONBOARDING.md); it is intended to guide users through install, first index, optional groups, MCP wiring, and next steps. The assisted configuration/setup flow is still being refined.
+The current verified install path is `cargo install --git ...`, which builds `ecp` from source. Release installers already contain the checksum and provenance-verification flow, but they require a published tag and release assets before the binary download path can be end-to-end verified. The agent-facing onboarding skill at [docs/skills/ecp-onboard/ONBOARDING.md](./docs/skills/ecp-onboard/ONBOARDING.md) guides users through install, first index, optional groups, MCP wiring, and next steps — the assisted setup flow is still being refined.
+
+---
+
+## Star History
+
+[](https://star-history.com/#coseto6125/egent-code-plexus&Date)
diff --git a/crates/ecp-analyzer/Cargo.toml b/crates/ecp-analyzer/Cargo.toml
index c2e5d359a..74d04c409 100644
--- a/crates/ecp-analyzer/Cargo.toml
+++ b/crates/ecp-analyzer/Cargo.toml
@@ -1,7 +1,7 @@
[package]
name = "ecp-analyzer"
description = "EgentCodePlexus — multi-language tree-sitter parser and route detector (Rust, TypeScript, Python, Go, Java, Swift, etc.)"
-version = "0.3.0"
+version = "0.4.0"
edition.workspace = true
license.workspace = true
repository.workspace = true
@@ -11,7 +11,7 @@ build = "build.rs"
sha2 = "0.11.0"
[dependencies]
-ecp-core = { path = "../ecp-core", version = "0.3.0" }
+ecp-core = { path = "../ecp-core", version = "0.4.0" }
phf = { version = "0.13", features = ["macros"] }
tree-sitter = "0.26"
tree-sitter-typescript = "*"
diff --git a/crates/ecp-cli/Cargo.toml b/crates/ecp-cli/Cargo.toml
index acf802423..292cad352 100644
--- a/crates/ecp-cli/Cargo.toml
+++ b/crates/ecp-cli/Cargo.toml
@@ -1,7 +1,7 @@
[package]
name = "egent-code-plexus"
description = "EgentCodePlexus — code intelligence graph for AI agents and LLMs (multi-language AST analysis)"
-version = "0.3.0"
+version = "0.4.0"
edition.workspace = true
default-run = "ecp"
license.workspace = true
@@ -25,9 +25,9 @@ name = "ecp_cli"
path = "src/lib.rs"
[dependencies]
-ecp-core = { path = "../ecp-core", version = "0.3.0" }
-ecp-analyzer = { path = "../ecp-analyzer", version = "0.3.0" }
-ecp-mcp = { path = "../ecp-mcp", version = "0.3.0" }
+ecp-core = { path = "../ecp-core", version = "0.4.0" }
+ecp-analyzer = { path = "../ecp-analyzer", version = "0.4.0" }
+ecp-mcp = { path = "../ecp-mcp", version = "0.4.0" }
tokio = { version = "1", features = ["rt"] }
clap = { version = "4.5.4", features = ["derive"] }
serde = { version = "1.0", features = ["derive"] }
diff --git a/crates/ecp-core/Cargo.toml b/crates/ecp-core/Cargo.toml
index 31eac100b..6e7bdd0db 100644
--- a/crates/ecp-core/Cargo.toml
+++ b/crates/ecp-core/Cargo.toml
@@ -1,7 +1,7 @@
[package]
name = "ecp-core"
description = "EgentCodePlexus — core graph storage and algorithms (zero-copy on-disk graph, registry, community detection)"
-version = "0.3.0"
+version = "0.4.0"
edition.workspace = true
license.workspace = true
repository.workspace = true
diff --git a/docs/readme_i18n/CONTRIBUTING.md b/docs/readme_i18n/CONTRIBUTING.md
new file mode 100644
index 000000000..8b15cc2b8
--- /dev/null
+++ b/docs/readme_i18n/CONTRIBUTING.md
@@ -0,0 +1,36 @@
+# Translating the README
+
+This directory holds non-English variants of the project README. The English one at the repo root is the source of truth; every other locale follows its structure 1-for-1.
+
+## Adding or improving a translation
+
+1. **Pick a locale code.** Use the [BCP-47](https://www.rfc-editor.org/info/bcp47) short form — `es`, `ru`, `ja`, `ko`, `hi`, `pt-BR`, etc. For Chinese variants we already split `zh-TW` and `zh-CN`.
+2. **Copy the structure.** Mirror the section order from `README.md` exactly. The brutalist hero box, badges, metrics block, code blocks, tables, and `` wrappers stay in English — only prose and table-cell descriptions get translated.
+3. **Keep technical terms in English** when the native rendering would be awkward (e.g., `mmap`, `BlindSpot`, `BFS`, `TOON`, `MCP`, all flag names like `--mode bm25`). The README is a developer doc; precision beats native-vocabulary purity.
+4. **Update the language picker** in every other locale file when you add a new one. The line right under the metrics block lists every available locale, with the current locale shown as `**bold**` (no link).
+5. **Internal links must resolve.** Translation files live at `docs/readme_i18n/.md`, so `../../LICENSE.md`, `../language-matrix.md`, and `./README_xx.md` are the right relative paths.
+
+## Quality bar
+
+We accept best-effort translations; we don't require certified-translator quality. What we do require:
+
+- The 4 numbers in the metrics block stay accurate (cold index 2.60 s, query p50 142 ms, 31 languages, edge policy).
+- The head-to-head + scalability tables stay numerically identical to the English version.
+- The CLI command names, flag names, and JSON snippets stay byte-for-byte identical.
+- The `[badges]` block stays identical across all locales.
+
+If you spot a translation that says something different from the English source — open an issue or PR with the diff. Translations drift; they need contributors to keep them honest.
+
+## Adding a brand-new locale
+
+1. Create `docs/readme_i18n/README_.md` mirroring the English structure.
+2. Insert the locale into the picker line in **every other README file** (root + each `docs/readme_i18n/README_*.md`).
+3. (Optional) update [`README.md`](../../README.md)'s social card / GitHub repo description if you want the locale advertised at the project level.
+
+## Removing a locale
+
+If a translation goes stale and no one is maintaining it, prefer **removing it** over leaving a misleading out-of-date version online. Open a PR that:
+
+1. Deletes `README_.md`.
+2. Removes the locale from every picker line.
+3. Notes in the PR body which sections diverged from English at time of removal, so a future contributor can resurrect the translation if they want.
diff --git a/docs/readme_i18n/README_es.md b/docs/readme_i18n/README_es.md
new file mode 100644
index 000000000..d01003ac5
--- /dev/null
+++ b/docs/readme_i18n/README_es.md
@@ -0,0 +1,340 @@
+# EgentCodePlexus
+
+[](https://scorecard.dev/viewer/?uri=github.com/coseto6125/egent-code-plexus)
+
+[](https://github.com/coseto6125/egent-code-plexus/releases)
+[](https://github.com/coseto6125/egent-code-plexus/releases)
+[](https://github.com/coseto6125/egent-code-plexus/releases)
+[](https://github.com/coseto6125/egent-code-plexus/blob/main/skill_sample/claude/SKILL.md)
+[](https://github.com/coseto6125/egent-code-plexus/blob/main/skill_sample/codex/ecp/SKILL.md)
+[](https://github.com/coseto6125/egent-code-plexus/blob/main/docs/skills/ecp-onboard/guides/04-mcp.md)
+
+`cold index 2.60 s · query p50 142 ms · 31 languages · BlindSpot edges (no hallucinated dispatch) · 60× upstream gitnexus`
+
+[English](../../README.md) · [繁體中文](./README_zh-TW.md) · [简体中文](./README_zh-CN.md) · **Español** · [Русский](./README_ru.md) · [हिन्दी](./README_hi.md) · [日本語](./README_ja.md) · [한국어](./README_ko.md) · [Português (BR)](./README_pt-BR.md)
+
+---
+
+## el caso
+
+Los agentes de código realizan entre 20 y 50 búsquedas por tarea. `grep` devuelve cadenas; un agente autónomo necesita símbolos, llamadores, aristas y una señal honesta cuando el grafo estático se agota.
+
+`ecp` es la capa de conocimiento estructural que es:
+
+- **sin estado.** Cada invocación hace `mmap` de un grafo `rkyv` zero-copy y termina. Sin daemon que mantener caliente, sin modo de fallo «el servidor murió, reinícialo».
+- **honesta.** Cuando un sitio de llamada no se puede resolver estáticamente (despacho dinámico, import sin resolver, reflexión), `ecp` emite un registro `BlindSpot`. Un agente que actúa sobre una dependencia alucinada cuesta más que uno que recibe un «no sé» y rodea el problema.
+- **barata en tokens.** Salida por defecto en TOON (clave:valor compacto). Cada flag aparece en `--help`. Cada comando es no-interactivo y su `stdout` es parseable. Sin ruido de UI consumiendo la ventana de contexto.
+- **políglota.** 31 lenguajes parseados a nivel estructural — código de servicio, Dockerfiles, GitHub Actions, Terraform, SQL y smart contracts dejan de ser agujeros negros en cuanto sales del lenguaje principal.
+
+Construido sobre [GitNexus](https://github.com/abhigyanpatwari/GitNexus) de [Abhigyan Patwari](https://github.com/abhigyanpatwari) — mismo modelo conceptual, reescrito en Rust para un público distinto.
+
+🎙️ **[Entrevistas con agentes](../../interviews/README.md)** — Gemini CLI y Codex evalúan `ecp` en flujos autónomos.
+
+## recibos
+
+Cabeza a cabeza contra el upstream GitNexus, medido sobre la codebase de [gitnexus](https://github.com/abhigyanpatwari/GitNexus) (TypeScript) con `scripts/parity/benchmark_vs_gitnexus.py`:
+
+| Fase | ecp (Rust) | gitnexus (Node) | Aceleración |
+|---|---|---|---|
+| **Cold Index** | **~970 ms** | ~58 s | **60×** |
+| **Symbol Context** | **~70 ms** | ~430 ms | **6×** |
+| **Blast Radius** | **~70 ms** | ~460 ms | **6×** |
+| **Cypher Query** | **~70 ms** | ~400 ms | **5×** |
+
+Los números de `ecp` incluyen el arranque completo del proceso (sin daemon). Los de GitNexus (v1.6.5) son contra un repo ya indexado y caliente vía su CLI.
+
+
+Escalabilidad — corrida única sobre .sample_repo (2,1 GB, ~40 proyectos OSS, 25+ lenguajes)
+
+**Rendimiento de ingesta**
+
+| Fase | Valor |
+|---|---|
+| Archivos indexados | **22 645** en 25 lenguajes detectados |
+| Reloj de pared (frío) | **2,60 s** (parse + resolve + serialize) |
+| Reloj de pared (incremental) | **4,9 ms** (recorrido xxh3_64, cero archivos sucios) |
+| Hardware | AMD Ryzen 9 9950X (16 lógicos), 39,2 GiB RAM, Linux 6.6.87 |
+
+**Latencia por consulta** (incluye arranque de proceso)
+
+| Consulta | Mediana | Notas |
+|---|---|---|
+| `coverage` (overview del registry) | **1,4 ms** | lectura más pequeña — solo mmap del registry |
+| `routes` (mapa HTTP de todo el repo) | **142,3 ms** | enumera declarativas + imperativas |
+| `coverage --detailed` (frameworks + blind-spots) | **143,4 ms** | registry completo + scoring por framework |
+| `impact --direction down` | **145,0 ms** | BFS sobre Calls / Extends |
+| `inspect ` (firma + callers + callees) | **145,6 ms** | resolución de símbolo + 1-hop |
+| `find --mode bm25` (búsqueda léxica) | **154,5 ms** | consulta Tantivy + partición en 5 cubos |
+| `cypher 'MATCH (a:Class)-[:HasMethod]->(b:Method) ...'` | **161,5 ms** | un patrón, una fila |
+| `cypher 'MATCH (a:Method)-[:Calls]->(b:Method) ...'` | **174,2 ms** | patrón más amplio, más coincidencias |
+| `impact --baseline HEAD~1` (blast radius del changeset) | **359,0 ms** | git diff + parse paralelo por archivo + BFS |
+
+Reproducir: `python scripts/benchmark/benchmark_ecp.py`.
+
+
+
+## vs. upstream gitnexus
+
+Mismo modelo conceptual, audiencia distinta. `ecp` **no** es un reemplazo drop-in — elige según quién lee el grafo.
+
+| Dimensión | EgentCodePlexus | GitNexus |
+|---|---|---|
+| Consumidor primario | Agentes de código autónomos | Devs humanos + integración IDE |
+| Runtime | CLI one-shot sin estado (cero calentamiento) | MCP server de larga duración |
+| Rendimiento | **< 2,5 s cold index / < 150 ms query** | ~60 s cold index / ~400 ms query |
+| Arista sin resolver | Registro `BlindSpot` (desconocimiento honesto) | Conjetura heurística |
+| Salida por defecto | TOON / JSON compacto (token-barato) | Renderizado wiki / UI |
+| Lenguajes | 31 (14 profundos + 17 estructurales) | 14 (profundos, 9 dimensiones) |
+| Almacenamiento | Rust + `rkyv` zero-copy mmap | Node.js + LadybugDB |
+
+Desglose completo de las 8 dimensiones + matriz de decisión → [docs/vs-gitnexus.md](../vs-gitnexus.md).
+
+## demo de 30 segundos
+
+```bash
+$ ecp impact parse_with_budget --direction upstream --format toon
+```
+
+```text
+target parse_with_budget
+ kind Function
+ file crates/ecp-analyzer/src/parse_budget.rs:28
+risk_level HIGH
+direct_callers 22 across 22 files
+ crates/ecp-analyzer/src/python/parser.rs:48 Method parse_file
+ crates/ecp-analyzer/src/rust/parser.rs:142 Method parse_file
+ crates/ecp-analyzer/src/typescript/parser.rs:73 Method parse_file
+ crates/ecp-analyzer/src/go/parser.rs:69 Method parse_file
+ ... (18 more language parsers)
+transitive 231 symbols across language detection + pipeline
+blind_spots 0
+```
+
+Eso es todo el round-trip — un proceso, un mmap, ~140 ms. Los comandos de lectura aceptan `--format text|json|toon`; el default por comando es la codificación más barata en tokens.
+
+## instalación
+
+Los binarios precompilados se publican con cada GitHub Release. Los scripts del instalador caen a una compilación cargo desde fuente solo si no hay un asset de release disponible.
+
+```bash
+# Linux / macOS
+curl -sSfL https://github.com/coseto6125/egent-code-plexus/releases/latest/download/install.sh | sh
+
+# Windows PowerShell
+iwr https://github.com/coseto6125/egent-code-plexus/releases/latest/download/install.ps1 -UseBasicParsing | iex
+
+# Vía cargo directo (mismo source build, sin wrapper del instalador)
+cargo install --git https://github.com/coseto6125/egent-code-plexus egent-code-plexus --bin ecp --locked
+```
+
+
+Source build con CPU tuneado
+
+```bash
+repo=https://github.com/coseto6125/egent-code-plexus
+RUSTFLAGS="-C target-cpu=native" cargo install --git "$repo" egent-code-plexus --bin ecp --locked --profile release-dist
+```
+
+
+
+## inicio rápido
+
+```bash
+# 1. Indexa el repo actual (incremental; la primera query también auto-indexa)
+ecp admin index --repo .
+
+# 2. Localiza un símbolo — nombre exacto por defecto
+ecp find loginUser
+ecp find login --mode bm25 # ranking BM25, top-K en cubos source/tests/ref/doc/config
+
+# 3. Blast radius — ¿quién se rompe si cambio esto?
+ecp impact validateUser --direction upstream
+
+# 4. Contexto completo del símbolo (firma, body, callers, callees, 1-hop impact)
+ecp inspect validateUser
+
+# 5. Todas las rutas HTTP del repo (declarativas @Get + imperativas app.get())
+ecp routes
+ecp routes /api/users --method POST # ruta → handler → cadena de callers
+```
+
+## cli surface
+
+Dos niveles — **comandos de agente** en el top level (query / refactor / verify) y **comandos admin** bajo `ecp admin` (registry / hooks / destructivos). Corre `ecp --help` y `ecp admin --help` para las matrices completas de flags.
+
+| Comando | Propósito |
+|---|---|
+| `inspect ` | Un símbolo → metadata, decoradores, firma, callers, callees, 1-hop impact |
+| `find ` | Localiza símbolos — exact (default) · `--mode fuzzy` substring · `--mode bm25` ranking léxico; bm25 particiona la salida en cubos source / tests / reference / document / config |
+| `impact --direction ` | Traversal de blast-radius con filtrado por confianza. `--baseline [` para impact del changeset. |
+| `rename --symbol --new-name ` | Rename AST-aware multi-archivo en 14 lenguajes. Siempre `--dry-run` primero. |
+| `cypher ''` | Escape hatch openCypher; `m.content` devuelve el cuerpo del fuente. |
+| `coverage` | Overview del registry, cobertura por framework, catálogo de blind-spots, frescura del grafo. |
+| `routes []` | Enumera rutas HTTP (declarativas + imperativas); con `` muestra handler + callers. |
+| `contracts` | Inventario cross-repo de contratos API (routes / queue / RPC). |
+| `diff` | Delta del resolver — binding tier-degradation + cambios de routes / contracts a nivel de arista. |
+| `tool-map` | Llamadas a clients externos HTTP / DB / Redis / queue vía análisis de import-binding por archivo. |
+| `shape-check` | Drift entre patrones de acceso del consumer HTTP y la forma de respuesta de la Route. |
+| `peers` | Colaboración multi-sesión entre pares (status / diff / log / gc). |
+| `review` | Agregador de auditoría LLM-workflow — impact + coverage + tool-map + shape-check + diff, filtrado a señales de alta confianza. |
+
+]
+Namespace admin — ecp admin <cmd> (registry / hooks / destructivos)
+
+| Comando | Propósito |
+|---|---|
+| `index --repo ` | Construye / refresca el grafo; incremental vía caché de contenido xxh3_64. `--force` para rebuild completo. |
+| `drop / prune / rename-branch` | Ciclo de vida del índice: eliminar, podar dirs de branch obsoletas, renombrar branch on-disk. |
+| `install-hook` | Instala el git reference-transaction hook (auto-tracking de cambios de branch). |
+| `config` | Wizard TOML interactivo para `.ecp/config.toml`. |
+| `mcp serve` / `mcp tools` | MCP server (stdio) para LLM hosts; `tools` lista la superficie de tools expuesta. |
+| `claude install / codex install / gemini install` | Integración scripteable de host (skills, hooks, entradas MCP). |
+| `verify-resolver` | Diff del dump del resolver contra un oracle de lenguaje (QA para ecp-dev). |
+
+
+
+Todos los comandos resuelven `.ecp/graph.bin` desde el CWD a menos que se pase `--graph `. Los comandos agent-facing son no-interactivos por diseño — cada flag sale en `--help`, cada stream de salida es parseable. Ejecuta `ecp admin` sin subcomando para abrir el TUI admin interactivo.
+
+## MCP server
+
+`ecp` incluye un MCP server que expone los comandos core como tools MCP. Los hosts que hablan MCP (Claude Code, Cursor, Windsurf, Cline, Codex CLI, Gemini CLI) pueden registrar `ecp` y llamar los tools de forma autónoma.
+
+```bash
+ecp admin mcp tools # inspecciona qué tools se van a exponer
+ecp admin mcp serve # corre el server (modo spawn por defecto)
+```
+
+Ejemplo de configuración manual del host para Claude Code (`~/.config/claude-code/mcp-servers.json`):
+
+```json
+{
+ "mcpServers": {
+ "ecp": { "command": "ecp", "args": ["admin", "mcp", "serve"] }
+ }
+}
+```
+
+Ruta progresiva para operadores humanos:
+
+```text
+ecp admin → Agent Integrations → MCP → → install
+```
+
+Ruta scripteada para agentes IA:
+
+```bash
+ecp admin claude install mcp-server
+ecp admin gemini install skills
+```
+
+
+Integración nativa de Codex CLI (separada de MCP — prepara un patch para un fork de openai/codex)
+
+La ruta nativa de Codex no edita la instalación de Codex en uso; escribe un patch que aplicas a un fork de `openai/codex`.
+
+Ruta progresiva:
+
+```text
+ecp admin → Agent Integrations → Codex CLI → install → native-tools
+```
+
+Skills incluidos (misma ruta progresiva):
+
+```text
+ecp admin → Agent Integrations → Codex CLI → install → skills → all | ecp | simplify
+```
+
+Ruta scripteada para agentes:
+
+```bash
+ecp admin codex install native-tools
+ecp admin codex install skills all
+ecp admin codex install skills ecp
+ecp admin codex install skills simplify
+```
+
+Los skills incluidos enseñan selección de flujo de trabajo que el command help no puede inferir:
+
+| Skill | Cuándo usar |
+|---|---|
+| `ecp` | El agente necesita decidir si flujos graph-aware de symbol / impact / route / contract / rename son mejores que grep / lectura de archivos. |
+| `simplify` | El agente está revisando código cambiado y debe empezar por `ecp impact`, blind spots, egress, shape drift y resolver deltas antes de leer diffs crudos. |
+
+El componente `native-tools` escribe:
+
+```text
+~/.config/ecp/host-integration/codex-cli.patch
+```
+
+Aplícalo en tu fork de Codex CLI:
+
+```bash
+cd /path/to/openai-codex-fork
+git apply ~/.config/ecp/host-integration/codex-cli.patch
+```
+
+Para verificar un fork que ya tiene el marcador nativo — fija `ECP_CODEX_CLI_CHECKOUT` antes de consultar status:
+
+```bash
+ECP_CODEX_CLI_CHECKOUT=/path/to/openai-codex-fork ecp admin codex status
+ecp admin codex uninstall native-tools
+ecp admin codex uninstall skills all
+```
+
+
+
+## arquitectura
+
+```
+crates/
+├── ecp-core Grafo zero-copy (rkyv + mmap), caché incremental, queries de grafo
+├── ecp-analyzer Parsers tree-sitter, detector de rutas HTTP, confianza por framework
+├── ecp-mcp MCP server (stdio) — expone comandos core como tools
+└── ecp-cli Binario `ecp`, motor BM25 de Tantivy, output optimizado para tokens
+```
+
+Parse → resolve → serialize corre a través de un canal MPSC hacia un único builder thread que ensambla el grafo y escribe un `.ecp/graph.bin` zero-copy. Las rutas de lectura (`inspect`, `cypher`, `impact`, …) hacen mmap directo de este archivo. La caché de contenido xxh3_64 mantiene los rebuilds incrementales en sub-segundo sobre un repo de 22k archivos.
+
+## cobertura de lenguajes
+
+31 lenguajes parseados a nivel estructural (funciones / clases / métodos / imports / calls). 14 de ellos — el conjunto original de GitNexus — obtienen cobertura full-depth en imports, named bindings, exports, herencia, types, constructores, config, frameworks, entry points, calls y rename. Los 17 restantes son structural-only (Bash, Crystal, Cairo, Dockerfile, Docker Compose, GitHub Actions, HCL, Lua, Markdown, Move, Nim, Solidity, SQL, Verilog, Vyper, YAML, Zig).
+
+📊 [Matriz completa de capacidades por lenguaje](../language-matrix.md) — status y rationale por lenguaje.
+
+## tuning
+
+| Variable de entorno | Default | Efecto |
+|---|---|---|
+| `ECP_MAX_FILE_BYTES` | `16777216` (16 MiB) | Salta archivos source mayores a esto durante la ingesta. Limita el peor caso de RAM por worker a `num_threads × MAX`. |
+| `ECP_CSPROJ_MAX_DEPTH` | `4` | Profundidad de recursión de directorios para descubrir `*.csproj`. Súbelo para monorepos .NET muy anidados. |
+
+## licencia
+
+Licenciado bajo [PolyForm Noncommercial 1.0.0](../../LICENSE.md). Uso personal, investigación, proyectos hobby y organizaciones sin fines de lucro están explícitamente permitidos. **El uso comercial no está concedido por esta licencia** — contacta al autor upstream de GitNexus [Abhigyan Patwari](https://github.com/abhigyanpatwari) para derechos comerciales. Atribución requerida: [NOTICES.md](../../LICENSES/NOTICES.md).
+
+
+Construido sobre (agradecimientos)
+
+- [GitNexus](https://github.com/abhigyanpatwari/GitNexus) — diseño original, superficie CLI, modelo conceptual
+- [tree-sitter](https://tree-sitter.github.io/) — parsing AST incremental
+- [rkyv](https://rkyv.org/) — framework de deserialización zero-copy
+- [Tantivy](https://github.com/quickwit-oss/tantivy) — motor de búsqueda BM25 en Rust
+- [Rayon](https://github.com/rayon-rs/rayon) — paralelismo de datos para parsing AST multinúcleo
+- [xxhash (xxh3_64)](https://xxhash.com/) — hashing para indexación incremental basada en contenido
+- [DashMap](https://github.com/xacrimon/dashmap) — hash maps concurrentes para ensamblaje del grafo
+- [memmap2](https://github.com/RazrFalcon/memmap2-rs) — memory mapping zero-copy
+- [msgspec](https://github.com/jcrist/msgspec) — serialización JSON rápida para IPC
+
+El onboarding para agentes IA (bootstrap por URL, skill de Claude Code, instalación de plugin) vive en `docs/skills/ecp-onboard/`. Invariantes de concurrencia y cómo re-verificarlos: `./scripts/audit/audit-concurrency.sh`.
+
+
+
+## estado de release
+
+La ruta de instalación verificada actualmente es `cargo install --git ...`, que compila `ecp` desde fuente. Los release installers ya contienen el flujo de verificación de checksum y procedencia, pero requieren un tag publicado y release assets antes de que la ruta de descarga del binario pueda ser end-to-end verificada. El skill de onboarding orientado a agentes en [docs/skills/ecp-onboard/ONBOARDING.md](../skills/ecp-onboard/ONBOARDING.md) guía a los usuarios por install, first-index, groups opcionales, wiring de MCP y siguientes pasos — el flujo de setup asistido sigue refinándose.
+
+---
+
+## Star History
+
+[](https://star-history.com/#coseto6125/egent-code-plexus&Date)
diff --git a/docs/readme_i18n/README_hi.md b/docs/readme_i18n/README_hi.md
new file mode 100644
index 000000000..8fe7ae9ac
--- /dev/null
+++ b/docs/readme_i18n/README_hi.md
@@ -0,0 +1,340 @@
+# EgentCodePlexus
+
+[](https://scorecard.dev/viewer/?uri=github.com/coseto6125/egent-code-plexus)
+
+[](https://github.com/coseto6125/egent-code-plexus/releases)
+[](https://github.com/coseto6125/egent-code-plexus/releases)
+[](https://github.com/coseto6125/egent-code-plexus/releases)
+[](https://github.com/coseto6125/egent-code-plexus/blob/main/skill_sample/claude/SKILL.md)
+[](https://github.com/coseto6125/egent-code-plexus/blob/main/skill_sample/codex/ecp/SKILL.md)
+[](https://github.com/coseto6125/egent-code-plexus/blob/main/docs/skills/ecp-onboard/guides/04-mcp.md)
+
+`cold index 2.60 s · query p50 142 ms · 31 languages · BlindSpot edges (no hallucinated dispatch) · 60× upstream gitnexus`
+
+[English](../../README.md) · [繁體中文](./README_zh-TW.md) · [简体中文](./README_zh-CN.md) · [Español](./README_es.md) · [Русский](./README_ru.md) · **हिन्दी** · [日本語](./README_ja.md) · [한국어](./README_ko.md) · [Português (BR)](./README_pt-BR.md)
+
+---
+
+## कारण
+
+Code agents एक task में 20–50 बार lookup करते हैं। `grep` केवल strings लौटाता है; एक autonomous agent को चाहिए symbols, callers, edges, और एक ईमानदार signal जब static graph जवाब नहीं दे सकता।
+
+`ecp` वह structural knowledge layer है जो:
+
+- **stateless है।** हर invocation एक zero-copy `rkyv` graph को `mmap` करता है और exit हो जाता है। कोई daemon गर्म नहीं रखना है, कोई "server died, please restart" failure mode नहीं है।
+- **ईमानदार है।** जब call site statically resolve नहीं हो सकता (dynamic dispatch, unresolved import, reflection), `ecp` एक `BlindSpot` record emit करता है। एक agent जो hallucinated dependency पर action लेता है, उससे महंगा पड़ता है जो "मुझे नहीं पता" पाकर रास्ता बदल लेता है।
+- **token-cheap है।** Default output TOON है (compact key:value)। हर flag `--help` के ज़रिए मिलता है। हर command non-interactive है और इसका `stdout` parseable है। कोई UI clutter context window को नहीं खाता।
+- **polyglot है।** 31 languages को structural level पर parse करता है — service code, Dockerfile, GitHub Actions, Terraform, SQL और smart contracts जैसे ही main language से बाहर जाते हैं, वे black hole बनना बंद कर देते हैं।
+
+[Abhigyan Patwari](https://github.com/abhigyanpatwari) के [GitNexus](https://github.com/abhigyanpatwari/GitNexus) पर बनाया गया — वही conceptual model, अलग audience के लिए Rust में फिर से लिखा गया।
+
+🎙️ **[Agent interviews](../../interviews/README.md)** — Gemini CLI और Codex autonomous workflows में `ecp` का evaluation करते हैं।
+
+## आँकड़े
+
+upstream GitNexus के विरुद्ध head-to-head, [gitnexus](https://github.com/abhigyanpatwari/GitNexus) codebase (TypeScript) पर `scripts/parity/benchmark_vs_gitnexus.py` से मापा गया:
+
+| Phase | ecp (Rust) | gitnexus (Node) | Speedup |
+|---|---|---|---|
+| **Cold Index** | **~970 ms** | ~58 s | **60×** |
+| **Symbol Context** | **~70 ms** | ~430 ms | **6×** |
+| **Blast Radius** | **~70 ms** | ~460 ms | **6×** |
+| **Cypher Query** | **~70 ms** | ~400 ms | **5×** |
+
+`ecp` के numbers में पूरा process startup शामिल है (no daemon)। GitNexus (v1.6.5) के numbers warm + indexed repo पर CLI के ज़रिए मापे गए हैं।
+
+
+Scalability — .sample_repo पर एकल run (2.1 GB polyglot, ~40 OSS projects, 25+ languages)
+
+**Ingest performance**
+
+| Phase | Value |
+|---|---|
+| Files indexed | **22,645** across 25 detected languages |
+| Wall-clock (Cold) | **2.60 s** (parse + resolve + serialize) |
+| Wall-clock (Incremental) | **4.9 ms** (xxh3_64 hash walk, zero dirty files) |
+| Hardware | AMD Ryzen 9 9950X (16 logical), 39.2 GiB RAM, Linux 6.6.87 |
+
+**Per-query latency** (process startup सहित)
+
+| Query | Median | Notes |
+|---|---|---|
+| `coverage` (registry overview) | **1.4 ms** | सबसे छोटा read — सिर्फ़ registry mmap |
+| `routes` (पूरे repo पर HTTP route map) | **142.3 ms** | declarative + imperative दोनों enumerate करता है |
+| `coverage --detailed` (frameworks + blind-spots) | **143.4 ms** | पूरा registry + per-framework scoring |
+| `impact --direction down` | **145.0 ms** | Calls / Extends edges पर BFS |
+| `inspect ` (signature + callers + callees) | **145.6 ms** | symbol resolution + 1-hop traversal |
+| `find --mode bm25` (lexical search) | **154.5 ms** | Tantivy query + 5-bucket partition |
+| `cypher 'MATCH (a:Class)-[:HasMethod]->(b:Method) ...'` | **161.5 ms** | एक pattern, एक row |
+| `cypher 'MATCH (a:Method)-[:Calls]->(b:Method) ...'` | **174.2 ms** | broader pattern, अधिक matches |
+| `impact --baseline HEAD~1` (changeset blast radius) | **359.0 ms** | git diff + parallel per-file parse + BFS |
+
+Reproduce: `python scripts/benchmark/benchmark_ecp.py`.
+
+
+
+## vs. upstream gitnexus
+
+वही conceptual model, अलग audience। `ecp` एक drop-in replacement **नहीं है** — चुनाव इस आधार पर करें कि graph को कौन पढ़ रहा है।
+
+| Dimension | EgentCodePlexus | GitNexus |
+|---|---|---|
+| Primary consumer | Autonomous AI code agents | Human devs + IDE integration |
+| Runtime | Stateless one-shot CLI (zero warm-up) | Long-running MCP server |
+| Performance | **< 2.5 s cold index / < 150 ms query** | ~60 s cold index / ~400 ms query |
+| Unresolved edge | `BlindSpot` record (ईमानदार unknown) | Heuristic guess |
+| Default output | TOON / compact JSON (token-cheap) | Wiki / UI rendering |
+| Languages | 31 (14 deep + 17 structural) | 14 (deep, 9-dimension) |
+| Storage | Rust + `rkyv` zero-copy mmap | Node.js + LadybugDB |
+
+8 dimensions का पूरा breakdown + decision matrix → [docs/vs-gitnexus.md](../vs-gitnexus.md)।
+
+## 30-second demo
+
+```bash
+$ ecp impact parse_with_budget --direction upstream --format toon
+```
+
+```text
+target parse_with_budget
+ kind Function
+ file crates/ecp-analyzer/src/parse_budget.rs:28
+risk_level HIGH
+direct_callers 22 across 22 files
+ crates/ecp-analyzer/src/python/parser.rs:48 Method parse_file
+ crates/ecp-analyzer/src/rust/parser.rs:142 Method parse_file
+ crates/ecp-analyzer/src/typescript/parser.rs:73 Method parse_file
+ crates/ecp-analyzer/src/go/parser.rs:69 Method parse_file
+ ... (18 more language parsers)
+transitive 231 symbols across language detection + pipeline
+blind_spots 0
+```
+
+यही पूरा round-trip है — एक process, एक mmap, ~140 ms। Read-side commands `--format text|json|toon` स्वीकार करते हैं; per-command default वह encoding है जो tokens में सबसे सस्ती हो।
+
+## Install
+
+हर GitHub Release के साथ prebuilt binaries publish होते हैं। Installer scripts cargo source build पर तभी fall back करते हैं जब matching release asset उपलब्ध नहीं है।
+
+```bash
+# Linux / macOS
+curl -sSfL https://github.com/coseto6125/egent-code-plexus/releases/latest/download/install.sh | sh
+
+# Windows PowerShell
+iwr https://github.com/coseto6125/egent-code-plexus/releases/latest/download/install.ps1 -UseBasicParsing | iex
+
+# Explicit cargo path (वही source build, बिना installer wrapper)
+cargo install --git https://github.com/coseto6125/egent-code-plexus egent-code-plexus --bin ecp --locked
+```
+
+
+CPU-tuned source build
+
+```bash
+repo=https://github.com/coseto6125/egent-code-plexus
+RUSTFLAGS="-C target-cpu=native" cargo install --git "$repo" egent-code-plexus --bin ecp --locked --profile release-dist
+```
+
+
+
+## Quick start
+
+```bash
+# 1. वर्तमान repo को index करें (incremental; पहली query auto-index भी करती है)
+ecp admin index --repo .
+
+# 2. एक symbol locate करें — default में exact name
+ecp find loginUser
+ecp find login --mode bm25 # BM25 ranking, top-K source/tests/ref/doc/config buckets में
+
+# 3. Blast radius — इसे बदलूँ तो कौन टूटेगा?
+ecp impact validateUser --direction upstream
+
+# 4. Symbol का पूरा context (signature, body, callers, callees, 1-hop impact)
+ecp inspect validateUser
+
+# 5. Repo के सारे HTTP routes (declarative @Get + imperative app.get())
+ecp routes
+ecp routes /api/users --method POST # route → handler → caller chain
+```
+
+## CLI surface
+
+दो tiers — **agent commands** top level पर (query / refactor / verify) और **admin commands** `ecp admin` के अंतर्गत (registry / hooks / destructive)। पूरी flag matrix के लिए `ecp --help` और `ecp admin --help` चलाएँ।
+
+| Command | Purpose |
+|---|---|
+| `inspect ` | एक symbol → metadata, decorators, signature, callers, callees, 1-hop impact |
+| `find ` | Symbols locate करें — exact (default) · `--mode fuzzy` substring · `--mode bm25` lexical ranking; bm25 output को source / tests / reference / document / config buckets में partition करता है |
+| `impact --direction ` | Confidence filtering के साथ blast-radius traversal। `--baseline [` changeset impact के लिए। |
+| `rename --symbol --new-name ` | 14 languages पर AST-aware multi-file rename। हमेशा `--dry-run` पहले। |
+| `cypher ''` | openCypher escape hatch; `m.content` source body लौटाता है। |
+| `coverage` | Registry overview, framework coverage, blind-spot catalog, graph freshness। |
+| `routes []` | HTTP routes enumerate करें (declarative + imperative); `` दें तो handler + callers दिखाता है। |
+| `contracts` | Cross-repo API contract inventory (routes / queue / RPC)। |
+| `diff` | Resolver-delta — edge-level binding tier-degradation + route / contract changes। |
+| `tool-map` | External HTTP / DB / Redis / queue clients पर calls — per-file import-binding analysis से। |
+| `shape-check` | HTTP consumer access patterns और Route response shapes के बीच drift। |
+| `peers` | Multi-session peer collaboration (status / diff / log / gc)। |
+| `review` | LLM-workflow audit aggregator — impact + coverage + tool-map + shape-check + diff, high-confidence signals तक filter। |
+
+]
+Admin namespace — ecp admin <cmd> (registry / hooks / destructive)
+
+| Command | Purpose |
+|---|---|
+| `index --repo ` | Graph build / refresh करें; xxh3_64 content cache के ज़रिए incremental। पूरे rebuild के लिए `--force`। |
+| `drop / prune / rename-branch` | Index lifecycle: delete, stale branch dirs prune, on-disk branch rename। |
+| `install-hook` | git reference-transaction hook install (branch switches auto-track)। |
+| `config` | `.ecp/config.toml` के लिए interactive TOML wizard। |
+| `mcp serve` / `mcp tools` | LLM hosts के लिए MCP server (stdio); `tools` exposed tool surface list करता है। |
+| `claude install / codex install / gemini install` | Scriptable host integration (skills, hooks, MCP entries)। |
+| `verify-resolver` | Resolver dump को language oracle से diff (ecp-dev QA)। |
+
+
+
+जब तक `--graph ` न दिया जाए, सभी commands CWD से `.ecp/graph.bin` resolve करते हैं। Agent-facing commands design से non-interactive हैं — हर flag `--help` से, हर output stream parseable। `ecp admin` बिना subcommand चलाने पर interactive admin TUI खुलता है।
+
+## MCP server
+
+`ecp` एक MCP server ship करता है जो core commands को MCP tools के रूप में expose करता है। MCP बोलने वाले hosts (Claude Code, Cursor, Windsurf, Cline, Codex CLI, Gemini CLI) `ecp` को register करके autonomously tools call कर सकते हैं।
+
+```bash
+ecp admin mcp tools # देखें कौन-से tools expose होंगे
+ecp admin mcp serve # server चलाएँ (default में spawn mode)
+```
+
+Claude Code के लिए manual host config example (`~/.config/claude-code/mcp-servers.json`):
+
+```json
+{
+ "mcpServers": {
+ "ecp": { "command": "ecp", "args": ["admin", "mcp", "serve"] }
+ }
+}
+```
+
+Human operators के लिए progressive path:
+
+```text
+ecp admin → Agent Integrations → MCP → → install
+```
+
+AI agents के लिए scripted path:
+
+```bash
+ecp admin claude install mcp-server
+ecp admin gemini install skills
+```
+
+
+Codex CLI native integration (MCP से अलग — openai/codex fork के लिए patch तैयार करता है)
+
+Codex native path आपके चल रहे Codex installation को edit नहीं करता; यह एक patch लिखता है जिसे आप `openai/codex` fork पर apply करते हैं।
+
+Progressive path:
+
+```text
+ecp admin → Agent Integrations → Codex CLI → install → native-tools
+```
+
+Bundled skills (वही progressive path):
+
+```text
+ecp admin → Agent Integrations → Codex CLI → install → skills → all | ecp | simplify
+```
+
+Agents के लिए scripted path:
+
+```bash
+ecp admin codex install native-tools
+ecp admin codex install skills all
+ecp admin codex install skills ecp
+ecp admin codex install skills simplify
+```
+
+Bundled skills वह workflow selection सिखाते हैं जो command help अकेले infer नहीं कर सकता:
+
+| Skill | कब उपयोग करें |
+|---|---|
+| `ecp` | Agent को decide करना है कि symbol / impact / route / contract / rename के graph-aware workflows grep / file reads से बेहतर हैं या नहीं। |
+| `simplify` | Agent बदले हुए code की review कर रहा है और raw diff पढ़ने से पहले `ecp impact`, blind spots, egress, shape drift, और resolver deltas से शुरू करना चाहिए। |
+
+`native-tools` component लिखता है:
+
+```text
+~/.config/ecp/host-integration/codex-cli.patch
+```
+
+अपने Codex CLI fork पर apply करें:
+
+```bash
+cd /path/to/openai-codex-fork
+git apply ~/.config/ecp/host-integration/codex-cli.patch
+```
+
+जिस fork पर पहले से native marker है, उसकी verify करने के लिए — status check से पहले `ECP_CODEX_CLI_CHECKOUT` set करें:
+
+```bash
+ECP_CODEX_CLI_CHECKOUT=/path/to/openai-codex-fork ecp admin codex status
+ecp admin codex uninstall native-tools
+ecp admin codex uninstall skills all
+```
+
+
+
+## Architecture
+
+```
+crates/
+├── ecp-core Zero-copy graph (rkyv + mmap), incremental cache, graph queries
+├── ecp-analyzer Tree-sitter parsers, HTTP route detector, framework confidence
+├── ecp-mcp MCP server (stdio) — core commands को tools के रूप में expose करता है
+└── ecp-cli `ecp` binary, Tantivy BM25 engine, token-optimized output
+```
+
+Parse → resolve → serialize एक MPSC channel से होकर एक single builder thread तक जाता है जो graph assemble करता है और एक zero-copy `.ecp/graph.bin` लिखता है। Read paths (`inspect`, `cypher`, `impact`, …) इस file को सीधे mmap करते हैं। xxh3_64 content cache 22k-file repo पर भी incremental rebuilds को sub-second में रखता है।
+
+## Language coverage
+
+31 languages structural level पर parse होती हैं (functions / classes / methods / imports / calls)। उनमें से 14 — original GitNexus set — को imports, named bindings, exports, heritage, types, constructors, config, frameworks, entry points, calls और rename के पार full-depth coverage मिलती है। बाकी 17 structural-only हैं (Bash, Crystal, Cairo, Dockerfile, Docker Compose, GitHub Actions, HCL, Lua, Markdown, Move, Nim, Solidity, SQL, Verilog, Vyper, YAML, Zig)।
+
+📊 [Full Language Capability Matrix](../language-matrix.md) — per-language status और rationale।
+
+## Tuning
+
+| Env var | Default | Effect |
+|---|---|---|
+| `ECP_MAX_FILE_BYTES` | `16777216` (16 MiB) | Ingest के दौरान इससे बड़ी source files skip करता है। Worst-case worker RAM को `num_threads × MAX` पर रोकता है। |
+| `ECP_CSPROJ_MAX_DEPTH` | `4` | `*.csproj` discovery के लिए directory recursion depth। गहरे-nested .NET monorepos के लिए बढ़ाएँ। |
+
+## License
+
+[PolyForm Noncommercial 1.0.0](../../LICENSE.md) के तहत licensed। Personal use, research, hobby projects, और noncommercial organizations को स्पष्ट रूप से अनुमति है। **Commercial use इस license से नहीं मिलता** — commercial rights के लिए upstream GitNexus लेखक [Abhigyan Patwari](https://github.com/abhigyanpatwari) से contact करें। आवश्यक attribution: [NOTICES.md](../../LICENSES/NOTICES.md)।
+
+
+Built on (acknowledgments)
+
+- [GitNexus](https://github.com/abhigyanpatwari/GitNexus) — original design, CLI surface, conceptual model
+- [tree-sitter](https://tree-sitter.github.io/) — incremental AST parsing
+- [rkyv](https://rkyv.org/) — zero-copy deserialization framework
+- [Tantivy](https://github.com/quickwit-oss/tantivy) — Rust BM25 search engine
+- [Rayon](https://github.com/rayon-rs/rayon) — multi-core AST parsing के लिए data parallelism
+- [xxhash (xxh3_64)](https://xxhash.com/) — content-based incremental indexing के लिए hashing
+- [DashMap](https://github.com/xacrimon/dashmap) — graph assembly के लिए concurrent hash maps
+- [memmap2](https://github.com/RazrFalcon/memmap2-rs) — zero-copy memory mapping
+- [msgspec](https://github.com/jcrist/msgspec) — IPC के लिए fast JSON serialization
+
+AI agents के लिए onboarding (URL bootstrap, Claude Code skill, plugin install) `docs/skills/ecp-onboard/` में है। Concurrency invariants और उन्हें re-verify करने का तरीका: `./scripts/audit/audit-concurrency.sh`।
+
+
+
+## Release status
+
+वर्तमान verified install path `cargo install --git ...` है, जो `ecp` को source से build करता है। Release installers में checksum और provenance-verification flow पहले से है, लेकिन binary download path को end-to-end verify करने के लिए published tag और release assets ज़रूरी हैं। Agent-facing onboarding skill [docs/skills/ecp-onboard/ONBOARDING.md](../skills/ecp-onboard/ONBOARDING.md) पर documented है; यह users को install, first index, optional groups, MCP wiring और next steps के through ले जाता है — assisted setup flow अभी refine हो रहा है।
+
+---
+
+## Star History
+
+[](https://star-history.com/#coseto6125/egent-code-plexus&Date)
diff --git a/docs/readme_i18n/README_ja.md b/docs/readme_i18n/README_ja.md
new file mode 100644
index 000000000..0907a25c0
--- /dev/null
+++ b/docs/readme_i18n/README_ja.md
@@ -0,0 +1,340 @@
+# EgentCodePlexus
+
+[](https://scorecard.dev/viewer/?uri=github.com/coseto6125/egent-code-plexus)
+
+[](https://github.com/coseto6125/egent-code-plexus/releases)
+[](https://github.com/coseto6125/egent-code-plexus/releases)
+[](https://github.com/coseto6125/egent-code-plexus/releases)
+[](https://github.com/coseto6125/egent-code-plexus/blob/main/skill_sample/claude/SKILL.md)
+[](https://github.com/coseto6125/egent-code-plexus/blob/main/skill_sample/codex/ecp/SKILL.md)
+[](https://github.com/coseto6125/egent-code-plexus/blob/main/docs/skills/ecp-onboard/guides/04-mcp.md)
+
+`cold index 2.60 s · query p50 142 ms · 31 languages · BlindSpot edges (no hallucinated dispatch) · 60× upstream gitnexus`
+
+[English](../../README.md) · [繁體中文](./README_zh-TW.md) · [简体中文](./README_zh-CN.md) · [Español](./README_es.md) · [Русский](./README_ru.md) · [हिन्दी](./README_hi.md) · **日本語** · [한국어](./README_ko.md) · [Português (BR)](./README_pt-BR.md)
+
+---
+
+## 動機
+
+コードエージェントは 1 タスクあたり 20〜50 回のルックアップを行います。`grep` は文字列しか返しませんが、自律エージェントが本当に必要としているのは、シンボル・呼び出し元・エッジ、そして静的グラフでは答えられないときに「分からない」と正直に告げるシグナルです。
+
+`ecp` は次の特徴を持つ構造的知識レイヤーです。
+
+- **ステートレス。** 呼び出すたびに `rkyv` のゼロコピーグラフを `mmap` して終了します。ウォームアップしておくデーモンもなく、「サーバが落ちたので再起動を」という失敗モードもありません。
+- **正直。** 呼び出しポイントを静的に解決できない場合（動的ディスパッチ、未解決 import、リフレクション）、`ecp` は `BlindSpot` レコードを出します。幻覚した依存関係に基づいて行動するエージェントは、「分からない」を受け取って迂回するエージェントよりもコストが高いのです。
+- **トークン節約。** デフォルト出力は TOON（コンパクトな key:value）。すべてのフラグは `--help` で表示され、すべてのコマンドは非対話型・`stdout` がパース可能。コンテキストウィンドウを食う UI ノイズはありません。
+- **多言語対応。** 31 言語を構造レベルで解析 — サービスコード、Dockerfile、GitHub Actions、Terraform、SQL、スマートコントラクトは、メインの言語を離れた瞬間にブラックホールになる、ということがなくなります。
+
+[Abhigyan Patwari](https://github.com/abhigyanpatwari) 氏の [GitNexus](https://github.com/abhigyanpatwari/GitNexus) を土台にしています — 概念モデルは同じで、別の読み手に向けて Rust で書き直したものです。
+
+🎙️ **[エージェントインタビュー](../../interviews/README.md)** — Gemini CLI と Codex が自律ワークフローで `ecp` を評価しています。
+
+## 計測結果
+
+upstream GitNexus との一対一比較。[gitnexus](https://github.com/abhigyanpatwari/GitNexus) のコードベース（TypeScript）上で `scripts/parity/benchmark_vs_gitnexus.py` を使用：
+
+| フェーズ | ecp (Rust) | gitnexus (Node) | 高速化 |
+|---|---|---|---|
+| **Cold Index** | **~970 ms** | ~58 s | **60×** |
+| **Symbol Context** | **~70 ms** | ~430 ms | **6×** |
+| **Blast Radius** | **~70 ms** | ~460 ms | **6×** |
+| **Cypher Query** | **~70 ms** | ~400 ms | **5×** |
+
+`ecp` の数字はプロセス起動を含む（デーモンなし）。GitNexus（v1.6.5）の数字は、すでにウォーム & インデックス済みのリポジトリに対して CLI 経由で計測したものです。
+
+
+スケーラビリティ — .sample_repo 単独実行（2.1 GB、~40 OSS プロジェクト、25+ 言語）
+
+**インジェスト性能**
+
+| フェーズ | 値 |
+|---|---|
+| インデックスされたファイル数 | **22,645**（検出 25 言語） |
+| Wall-clock（Cold） | **2.60 s**（parse + resolve + serialize） |
+| Wall-clock（Incremental） | **4.9 ms**（xxh3_64 ハッシュ walk、ダーティファイル 0） |
+| ハードウェア | AMD Ryzen 9 9950X（16 論理）、39.2 GiB RAM、Linux 6.6.87 |
+
+**クエリあたりのレイテンシ**（プロセス起動を含む）
+
+| クエリ | 中央値 | 備考 |
+|---|---|---|
+| `coverage`（registry overview） | **1.4 ms** | 最小読み取り — registry mmap のみ |
+| `routes`（リポジトリ全体の HTTP route マップ） | **142.3 ms** | 宣言型 + 命令型を列挙 |
+| `coverage --detailed`（フレームワーク + blind-spot） | **143.4 ms** | フル registry + フレームワークごとのスコア |
+| `impact --direction down` | **145.0 ms** | Calls / Extends エッジ上の BFS |
+| `inspect `（シグネチャ + callers + callees） | **145.6 ms** | シンボル解決 + 1-hop traversal |
+| `find --mode bm25`（語彙検索） | **154.5 ms** | Tantivy クエリ + 5 バケットへの分割 |
+| `cypher 'MATCH (a:Class)-[:HasMethod]->(b:Method) ...'` | **161.5 ms** | 1 パターン、1 行 |
+| `cypher 'MATCH (a:Method)-[:Calls]->(b:Method) ...'` | **174.2 ms** | より広いパターン、より多くのマッチ |
+| `impact --baseline HEAD~1`（changeset blast radius） | **359.0 ms** | git diff + ファイルごと並列 parse + BFS |
+
+再現：`python scripts/benchmark/benchmark_ecp.py`。
+
+
+
+## vs. upstream gitnexus
+
+概念モデルは同じ、ターゲットが違います。`ecp` は drop-in **な置き換えではありません** — 誰がそのグラフを読むかで選んでください。
+
+| 観点 | EgentCodePlexus | GitNexus |
+|---|---|---|
+| 主たる消費者 | 自律 AI コードエージェント | 人間の開発者 + IDE 統合 |
+| Runtime | ステートレスな one-shot CLI（ウォームアップ不要） | 長期稼働の MCP サーバ |
+| 性能 | **< 2.5 s cold index / < 150 ms query** | ~60 s cold index / ~400 ms query |
+| 未解決エッジ | `BlindSpot` レコード（正直な「分からない」） | ヒューリスティックな推測 |
+| デフォルト出力 | TOON / コンパクト JSON（トークン安価） | Wiki / UI レンダリング |
+| 言語数 | 31（14 深い + 17 構造のみ） | 14（深い、9 次元） |
+| ストレージ | Rust + `rkyv` ゼロコピー mmap | Node.js + LadybugDB |
+
+8 次元の完全な内訳 + 意思決定マトリクス → [docs/vs-gitnexus.md](../vs-gitnexus.md)。
+
+## 30 秒デモ
+
+```bash
+$ ecp impact parse_with_budget --direction upstream --format toon
+```
+
+```text
+target parse_with_budget
+ kind Function
+ file crates/ecp-analyzer/src/parse_budget.rs:28
+risk_level HIGH
+direct_callers 22 across 22 files
+ crates/ecp-analyzer/src/python/parser.rs:48 Method parse_file
+ crates/ecp-analyzer/src/rust/parser.rs:142 Method parse_file
+ crates/ecp-analyzer/src/typescript/parser.rs:73 Method parse_file
+ crates/ecp-analyzer/src/go/parser.rs:69 Method parse_file
+ ... (18 more language parsers)
+transitive 231 symbols across language detection + pipeline
+blind_spots 0
+```
+
+これがラウンドトリップの全てです — 1 プロセス、1 回の mmap、~140 ms。読み取り系コマンドは `--format text|json|toon` を受け付けます。デフォルトはコマンドごとに最もトークンの安いエンコーディングです。
+
+## インストール
+
+事前ビルド済みバイナリは各 GitHub Release で配布されます。インストーラスクリプトは、対応する release アセットが利用できない場合のみ cargo の source build にフォールバックします。
+
+```bash
+# Linux / macOS
+curl -sSfL https://github.com/coseto6125/egent-code-plexus/releases/latest/download/install.sh | sh
+
+# Windows PowerShell
+iwr https://github.com/coseto6125/egent-code-plexus/releases/latest/download/install.ps1 -UseBasicParsing | iex
+
+# cargo 直接（インストーララッパーなしで同じ source build）
+cargo install --git https://github.com/coseto6125/egent-code-plexus egent-code-plexus --bin ecp --locked
+```
+
+
+CPU 最適化された source build
+
+```bash
+repo=https://github.com/coseto6125/egent-code-plexus
+RUSTFLAGS="-C target-cpu=native" cargo install --git "$repo" egent-code-plexus --bin ecp --locked --profile release-dist
+```
+
+
+
+## クイックスタート
+
+```bash
+# 1. 現在のリポジトリをインデックス（インクリメンタル；初回クエリも自動インデックス）
+ecp admin index --repo .
+
+# 2. シンボルを探す — デフォルトは厳密名
+ecp find loginUser
+ecp find login --mode bm25 # BM25 ランキング、top-K を source/tests/ref/doc/config バケットに分割
+
+# 3. Blast radius — これを変えると誰が壊れる？
+ecp impact validateUser --direction upstream
+
+# 4. シンボルのフルコンテキスト（シグネチャ、本体、callers、callees、1-hop impact）
+ecp inspect validateUser
+
+# 5. リポジトリ内のすべての HTTP route（宣言型 @Get + 命令型 app.get()）
+ecp routes
+ecp routes /api/users --method POST # route → handler → caller チェーン
+```
+
+## cli surface
+
+2 階層 — トップレベルの **agent commands**（query / refactor / verify）と、`ecp admin` 配下の **admin commands**（registry / hooks / 破壊的操作）。完全なフラグマトリクスは `ecp --help` と `ecp admin --help` を実行してください。
+
+| コマンド | 用途 |
+|---|---|
+| `inspect ` | シンボル 1 つ → メタデータ、デコレータ、シグネチャ、callers、callees、1-hop impact |
+| `find ` | シンボル検索 — exact（デフォルト）· `--mode fuzzy` 部分文字列 · `--mode bm25` 語彙ランキング。bm25 は出力を source / tests / reference / document / config バケットに分割 |
+| `impact --direction ` | confidence フィルタ付き blast-radius traversal。`--baseline [` で changeset impact。 |
+| `rename --symbol --new-name ` | 14 言語にわたる AST-aware なマルチファイル rename。必ず `--dry-run` から。 |
+| `cypher ''` | openCypher のエスケープハッチ。`m.content` でソース本体を返す。 |
+| `coverage` | Registry overview、フレームワーク coverage、blind-spot カタログ、グラフの鮮度。 |
+| `routes []` | HTTP routes（宣言型 + 命令型）を列挙。`` 指定で handler + callers を表示。 |
+| `contracts` | リポジトリ横断 API contract インベントリ（routes / queue / RPC）。 |
+| `diff` | Resolver delta — binding tier-degradation + routes / contracts のエッジレベル変更。 |
+| `tool-map` | 外部 HTTP / DB / Redis / queue クライアントへの呼び出しを、ファイル単位 import-binding 分析で抽出。 |
+| `shape-check` | HTTP consumer のアクセスパターンと Route のレスポンス形状とのドリフト。 |
+| `peers` | マルチセッション ピア協調（status / diff / log / gc）。 |
+| `review` | LLM-workflow 監査アグリゲータ — impact + coverage + tool-map + shape-check + diff を一括実行し、高信頼シグナルのみにフィルタ。 |
+
+]
+Admin namespace — ecp admin <cmd>（registry / hooks / 破壊的）
+
+| コマンド | 用途 |
+|---|---|
+| `index --repo ` | グラフのビルド / 更新。xxh3_64 コンテンツキャッシュでインクリメンタル。`--force` で完全リビルド。 |
+| `drop / prune / rename-branch` | インデックスのライフサイクル：削除、古い branch dir のプルーン、ブランチ on-disk リネーム。 |
+| `install-hook` | git reference-transaction フックをインストール（ブランチ切り替えを自動追跡）。 |
+| `config` | `.ecp/config.toml` 対話型 TOML ウィザード。 |
+| `mcp serve` / `mcp tools` | LLM ホスト向け MCP server（stdio）。`tools` は公開される tool サーフェスを表示。 |
+| `claude install / codex install / gemini install` | スクリプタブルなホスト統合（skills、hooks、MCP エントリ）。 |
+| `verify-resolver` | resolver ダンプを language oracle と diff（ecp-dev の QA 用）。 |
+
+
+
+すべてのコマンドは、`--graph ` が渡されない限り CWD から `.ecp/graph.bin` を解決します。エージェント向けコマンドは設計上ノンインタラクティブ — フラグはすべて `--help` から、出力ストリームはすべてパース可能。`ecp admin` をサブコマンドなしで実行すると、対話型 admin TUI が開きます。
+
+## MCP server
+
+`ecp` はコアコマンドを MCP tool として公開する MCP server を同梱しています。MCP を話せるホスト（Claude Code、Cursor、Windsurf、Cline、Codex CLI、Gemini CLI）は `ecp` を登録して、自律的に tool を呼び出せます。
+
+```bash
+ecp admin mcp tools # 公開される tool を確認
+ecp admin mcp serve # サーバを起動（デフォルトは spawn モード）
+```
+
+Claude Code 用の手動ホスト設定例（`~/.config/claude-code/mcp-servers.json`）:
+
+```json
+{
+ "mcpServers": {
+ "ecp": { "command": "ecp", "args": ["admin", "mcp", "serve"] }
+ }
+}
+```
+
+人間オペレータ向けのプログレッシブパス：
+
+```text
+ecp admin → Agent Integrations → MCP → → install
+```
+
+AI エージェント向けのスクリプテッドパス：
+
+```bash
+ecp admin claude install mcp-server
+ecp admin gemini install skills
+```
+
+
+Codex CLI ネイティブ統合（MCP とは別 — openai/codex フォーク向けのパッチを準備）
+
+Codex ネイティブパスは、稼働中の Codex インストールを編集しません。`openai/codex` フォークに適用するパッチを書き出します。
+
+プログレッシブパス：
+
+```text
+ecp admin → Agent Integrations → Codex CLI → install → native-tools
+```
+
+同梱の skills（同じプログレッシブパス）：
+
+```text
+ecp admin → Agent Integrations → Codex CLI → install → skills → all | ecp | simplify
+```
+
+エージェント向けスクリプテッドパス：
+
+```bash
+ecp admin codex install native-tools
+ecp admin codex install skills all
+ecp admin codex install skills ecp
+ecp admin codex install skills simplify
+```
+
+同梱の skills は、command help だけでは推測できないワークフロー選択を教えます：
+
+| Skill | こんなとき |
+|---|---|
+| `ecp` | エージェントが、symbol / impact / route / contract / rename のグラフ感知ワークフローと grep / ファイル読みのどちらが良いかを判断する必要があるとき。 |
+| `simplify` | エージェントが変更コードをレビューしていて、生の diff を読む前に `ecp impact`、blind spot、egress、shape drift、resolver delta から始めるべきとき。 |
+
+`native-tools` コンポーネントが書き出すのは：
+
+```text
+~/.config/ecp/host-integration/codex-cli.patch
+```
+
+Codex CLI フォークでこのパッチを当てます：
+
+```bash
+cd /path/to/openai-codex-fork
+git apply ~/.config/ecp/host-integration/codex-cli.patch
+```
+
+すでに native マーカーがあるフォークを検証するには、status 確認前に `ECP_CODEX_CLI_CHECKOUT` を設定：
+
+```bash
+ECP_CODEX_CLI_CHECKOUT=/path/to/openai-codex-fork ecp admin codex status
+ecp admin codex uninstall native-tools
+ecp admin codex uninstall skills all
+```
+
+
+
+## アーキテクチャ
+
+```
+crates/
+├── ecp-core ゼロコピーグラフ（rkyv + mmap）、インクリメンタルキャッシュ、グラフクエリ
+├── ecp-analyzer Tree-sitter パーサ、HTTP route ディテクタ、フレームワーク信頼度
+├── ecp-mcp MCP server（stdio） — コアコマンドを tool として公開
+└── ecp-cli `ecp` バイナリ、Tantivy BM25 エンジン、トークン最適化された出力
+```
+
+Parse → resolve → serialize は MPSC チャネルを経由して単一の builder スレッドに流れ込み、そこでグラフが組み立てられて、ゼロコピーの `.ecp/graph.bin` が書き出されます。読み取りパス（`inspect`、`cypher`、`impact`、…）はこのファイルを直接 mmap します。xxh3_64 コンテンツキャッシュにより、22k ファイルのリポジトリでもインクリメンタルリビルドはサブ秒で完了します。
+
+## 言語カバレッジ
+
+31 言語を構造レベル（関数 / クラス / メソッド / import / call）で解析します。そのうち 14 言語 — オリジナルの GitNexus セット — は、import、named binding、export、heritage、type、コンストラクタ、config、フレームワーク、entry point、call、rename にわたるフルデプスのカバレッジを得ています。残り 17 言語は構造のみ（Bash、Crystal、Cairo、Dockerfile、Docker Compose、GitHub Actions、HCL、Lua、Markdown、Move、Nim、Solidity、SQL、Verilog、Vyper、YAML、Zig）。
+
+📊 [言語別ケイパビリティの完全マトリクス](../language-matrix.md) — 言語ごとの状態と根拠。
+
+## チューニング
+
+| 環境変数 | デフォルト | 効果 |
+|---|---|---|
+| `ECP_MAX_FILE_BYTES` | `16777216`（16 MiB） | インジェスト中、このサイズより大きいソースファイルをスキップ。最悪ケースの worker RAM を `num_threads × MAX` に抑える。 |
+| `ECP_CSPROJ_MAX_DEPTH` | `4` | `*.csproj` 発見のためのディレクトリ再帰深度。深くネストした .NET モノレポでは引き上げ。 |
+
+## ライセンス
+
+[PolyForm Noncommercial 1.0.0](../../LICENSE.md) でライセンスされています。個人利用、研究、ホビープロジェクト、非営利組織は明示的に許可されています。**本ライセンスは商用利用を許諾しません** — 商用ライセンスについては upstream の GitNexus 著者 [Abhigyan Patwari](https://github.com/abhigyanpatwari) にお問い合わせください。必要な帰属表示：[NOTICES.md](../../LICENSES/NOTICES.md)。
+
+
+基盤としているもの（謝辞）
+
+- [GitNexus](https://github.com/abhigyanpatwari/GitNexus) — オリジナルの設計、CLI サーフェス、概念モデル
+- [tree-sitter](https://tree-sitter.github.io/) — インクリメンタル AST パージング
+- [rkyv](https://rkyv.org/) — ゼロコピーデシリアライズフレームワーク
+- [Tantivy](https://github.com/quickwit-oss/tantivy) — Rust 製 BM25 サーチエンジン
+- [Rayon](https://github.com/rayon-rs/rayon) — 多コア並列 AST パージング向けデータパラレリズム
+- [xxhash (xxh3_64)](https://xxhash.com/) — コンテンツベースのインクリメンタルインデキシング向けハッシュ
+- [DashMap](https://github.com/xacrimon/dashmap) — グラフアセンブリ用の並行ハッシュマップ
+- [memmap2](https://github.com/RazrFalcon/memmap2-rs) — ゼロコピーメモリマッピング
+- [msgspec](https://github.com/jcrist/msgspec) — IPC 向け高速 JSON シリアライズ
+
+AI エージェント向けのオンボーディング（URL ブートストラップ、Claude Code skill、プラグインインストール）は `docs/skills/ecp-onboard/` にあります。並行性インバリアントとその再検証方法：`./scripts/audit/audit-concurrency.sh`。
+
+
+
+## リリースステータス
+
+現在検証済みのインストールパスは `cargo install --git ...` で、`ecp` をソースからビルドします。リリースインストーラには既に checksum と provenance 検証フローが含まれていますが、バイナリダウンロードパスをエンドツーエンドで検証可能にするには、公開されたタグとリリースアセットが必要です。エージェント向けのオンボーディング skill は [docs/skills/ecp-onboard/ONBOARDING.md](../skills/ecp-onboard/ONBOARDING.md) に文書化されており、インストール、初回インデックス、任意のグループ、MCP wiring、次のステップへとユーザーをガイドします — アシスト型のセットアップフローは現在もリファイン中です。
+
+---
+
+## Star History
+
+[](https://star-history.com/#coseto6125/egent-code-plexus&Date)
diff --git a/docs/readme_i18n/README_ko.md b/docs/readme_i18n/README_ko.md
new file mode 100644
index 000000000..fb6daae4a
--- /dev/null
+++ b/docs/readme_i18n/README_ko.md
@@ -0,0 +1,340 @@
+# EgentCodePlexus
+
+[](https://scorecard.dev/viewer/?uri=github.com/coseto6125/egent-code-plexus)
+
+[](https://github.com/coseto6125/egent-code-plexus/releases)
+[](https://github.com/coseto6125/egent-code-plexus/releases)
+[](https://github.com/coseto6125/egent-code-plexus/releases)
+[](https://github.com/coseto6125/egent-code-plexus/blob/main/skill_sample/claude/SKILL.md)
+[](https://github.com/coseto6125/egent-code-plexus/blob/main/skill_sample/codex/ecp/SKILL.md)
+[](https://github.com/coseto6125/egent-code-plexus/blob/main/docs/skills/ecp-onboard/guides/04-mcp.md)
+
+`cold index 2.60 s · query p50 142 ms · 31 languages · BlindSpot edges (no hallucinated dispatch) · 60× upstream gitnexus`
+
+[English](../../README.md) · [繁體中文](./README_zh-TW.md) · [简体中文](./README_zh-CN.md) · [Español](./README_es.md) · [Русский](./README_ru.md) · [हिन्दी](./README_hi.md) · [日本語](./README_ja.md) · **한국어** · [Português (BR)](./README_pt-BR.md)
+
+---
+
+## 동기
+
+코드 에이전트는 하나의 태스크당 20–50회의 조회를 수행합니다. `grep`은 문자열만 돌려주지만, 자율 에이전트가 정말 필요한 것은 심볼·호출자·간선, 그리고 정적 그래프가 답할 수 없을 때 솔직하게 "모른다"고 말하는 신호입니다.
+
+`ecp`는 다음 특성을 갖는 구조적 지식 레이어입니다.
+
+- **상태 없음.** 호출할 때마다 `rkyv` 제로카피 그래프를 `mmap`한 뒤 종료합니다. 따뜻하게 유지해야 할 데몬도, "서버가 죽었으니 재시작" 같은 실패 모드도 없습니다.
+- **정직함.** 호출 지점을 정적으로 해석할 수 없을 때(동적 디스패치, 미해결 import, 리플렉션) `ecp`는 `BlindSpot` 레코드를 발행합니다. 환각한 의존성에 기반해 행동하는 에이전트는, "모른다"는 답을 받고 우회하는 에이전트보다 훨씬 비쌉니다.
+- **토큰 절약.** 기본 출력은 TOON(컴팩트 key:value). 모든 플래그는 `--help`로 노출되고, 모든 명령은 비대화형·`stdout`은 파싱 가능합니다. 컨텍스트 윈도우를 잡아먹는 UI 잡음이 없습니다.
+- **다중 언어.** 31개 언어를 구조 수준에서 파싱합니다 — 서비스 코드, Dockerfile, GitHub Actions, Terraform, SQL, 스마트 컨트랙트가 주 언어를 벗어나는 순간 블랙홀이 되는 일을 없앱니다.
+
+[Abhigyan Patwari](https://github.com/abhigyanpatwari)의 [GitNexus](https://github.com/abhigyanpatwari/GitNexus) 위에 만들어졌습니다 — 개념 모델은 동일하지만, 다른 독자를 위해 Rust로 재작성된 버전입니다.
+
+🎙️ **[에이전트 인터뷰](../../interviews/README.md)** — Gemini CLI와 Codex가 자율 워크플로에서 `ecp`를 평가합니다.
+
+## 측정 결과
+
+upstream GitNexus와의 정면 비교. [gitnexus](https://github.com/abhigyanpatwari/GitNexus) 코드베이스(TypeScript) 위에서 `scripts/parity/benchmark_vs_gitnexus.py`를 사용해 측정:
+
+| 단계 | ecp (Rust) | gitnexus (Node) | 가속비 |
+|---|---|---|---|
+| **Cold Index** | **~970 ms** | ~58 s | **60×** |
+| **Symbol Context** | **~70 ms** | ~430 ms | **6×** |
+| **Blast Radius** | **~70 ms** | ~460 ms | **6×** |
+| **Cypher Query** | **~70 ms** | ~400 ms | **5×** |
+
+`ecp`의 수치는 프로세스 기동 시간을 포함합니다(데몬 없음). GitNexus(v1.6.5)의 수치는 이미 워밍업 & 인덱싱된 저장소에 대해 CLI로 측정한 값입니다.
+
+
+확장성 — .sample_repo 단일 실행(2.1 GB 다국어, OSS 프로젝트 ~40개, 25+ 언어)
+
+**인제스트 성능**
+
+| 단계 | 값 |
+|---|---|
+| 인덱싱된 파일 수 | **22,645**(감지된 25개 언어) |
+| Wall-clock(cold) | **2.60 s**(parse + resolve + serialize) |
+| Wall-clock(incremental) | **4.9 ms**(xxh3_64 해시 walk, 더티 파일 0) |
+| 하드웨어 | AMD Ryzen 9 9950X(논리 16), 39.2 GiB RAM, Linux 6.6.87 |
+
+**쿼리별 레이턴시**(프로세스 기동 포함)
+
+| 쿼리 | 중앙값 | 비고 |
+|---|---|---|
+| `coverage`(registry 개요) | **1.4 ms** | 가장 작은 읽기 — registry mmap만 |
+| `routes`(저장소 전체 HTTP route 맵) | **142.3 ms** | 선언형 + 명령형 모두 열거 |
+| `coverage --detailed`(프레임워크 + blind-spot) | **143.4 ms** | 전체 registry + 프레임워크별 스코어 |
+| `impact --direction down` | **145.0 ms** | Calls / Extends 간선 위의 BFS |
+| `inspect `(시그니처 + callers + callees) | **145.6 ms** | 심볼 해석 + 1-hop traversal |
+| `find --mode bm25`(어휘 검색) | **154.5 ms** | Tantivy 쿼리 + 5-버킷 분할 |
+| `cypher 'MATCH (a:Class)-[:HasMethod]->(b:Method) ...'` | **161.5 ms** | 단일 패턴, 단일 행 |
+| `cypher 'MATCH (a:Method)-[:Calls]->(b:Method) ...'` | **174.2 ms** | 더 넓은 패턴, 더 많은 매치 |
+| `impact --baseline HEAD~1`(changeset blast radius) | **359.0 ms** | git diff + 파일별 병렬 parse + BFS |
+
+재현: `python scripts/benchmark/benchmark_ecp.py`.
+
+
+
+## vs. upstream gitnexus
+
+개념 모델은 같지만 대상이 다릅니다. `ecp`는 drop-in 대체재가 **아닙니다** — 누가 그래프를 읽는지에 따라 고르세요.
+
+| 차원 | EgentCodePlexus | GitNexus |
+|---|---|---|
+| 주 소비자 | 자율 AI 코드 에이전트 | 인간 개발자 + IDE 통합 |
+| Runtime | 무상태 one-shot CLI(워밍업 0) | 장기 구동 MCP 서버 |
+| 성능 | **< 2.5 s cold index / < 150 ms query** | ~60 s cold index / ~400 ms query |
+| 미해결 간선 | `BlindSpot` 레코드(정직한 미상) | 휴리스틱 추측 |
+| 기본 출력 | TOON / 컴팩트 JSON(토큰 저렴) | Wiki / UI 렌더링 |
+| 언어 | 31(14 깊이 + 17 구조) | 14(깊이, 9 차원) |
+| 저장 | Rust + `rkyv` 제로카피 mmap | Node.js + LadybugDB |
+
+8개 차원 전체 분석 + 의사결정 매트릭스 → [docs/vs-gitnexus.md](../vs-gitnexus.md).
+
+## 30초 데모
+
+```bash
+$ ecp impact parse_with_budget --direction upstream --format toon
+```
+
+```text
+target parse_with_budget
+ kind Function
+ file crates/ecp-analyzer/src/parse_budget.rs:28
+risk_level HIGH
+direct_callers 22 across 22 files
+ crates/ecp-analyzer/src/python/parser.rs:48 Method parse_file
+ crates/ecp-analyzer/src/rust/parser.rs:142 Method parse_file
+ crates/ecp-analyzer/src/typescript/parser.rs:73 Method parse_file
+ crates/ecp-analyzer/src/go/parser.rs:69 Method parse_file
+ ... (18 more language parsers)
+transitive 231 symbols across language detection + pipeline
+blind_spots 0
+```
+
+이게 라운드트립 전부입니다 — 프로세스 한 번, mmap 한 번, ~140 ms. 읽기 계열 명령은 `--format text|json|toon`을 받습니다. 기본값은 명령마다 토큰이 가장 저렴한 인코딩입니다.
+
+## 설치
+
+사전 빌드된 바이너리는 매 GitHub Release마다 배포됩니다. 설치 스크립트는 매칭되는 release 자산이 없을 때만 cargo source build로 폴백합니다.
+
+```bash
+# Linux / macOS
+curl -sSfL https://github.com/coseto6125/egent-code-plexus/releases/latest/download/install.sh | sh
+
+# Windows PowerShell
+iwr https://github.com/coseto6125/egent-code-plexus/releases/latest/download/install.ps1 -UseBasicParsing | iex
+
+# 명시적인 cargo 경로(설치 래퍼 없는 동일 source build)
+cargo install --git https://github.com/coseto6125/egent-code-plexus egent-code-plexus --bin ecp --locked
+```
+
+
+CPU 튜닝된 source build
+
+```bash
+repo=https://github.com/coseto6125/egent-code-plexus
+RUSTFLAGS="-C target-cpu=native" cargo install --git "$repo" egent-code-plexus --bin ecp --locked --profile release-dist
+```
+
+
+
+## 빠른 시작
+
+```bash
+# 1. 현재 저장소 인덱싱(점진적; 첫 쿼리도 자동 인덱싱)
+ecp admin index --repo .
+
+# 2. 심볼 찾기 — 기본은 정확한 이름
+ecp find loginUser
+ecp find login --mode bm25 # BM25 랭킹, top-K를 source/tests/ref/doc/config 버킷으로 분할
+
+# 3. Blast radius — 이걸 바꾸면 누가 깨질까?
+ecp impact validateUser --direction upstream
+
+# 4. 심볼의 전체 컨텍스트(시그니처, 본체, callers, callees, 1-hop impact)
+ecp inspect validateUser
+
+# 5. 저장소의 모든 HTTP route(선언형 @Get + 명령형 app.get())
+ecp routes
+ecp routes /api/users --method POST # route → handler → caller 체인
+```
+
+## cli surface
+
+두 계층 — 최상위 레벨의 **agent commands**(query / refactor / verify)와 `ecp admin` 아래의 **admin commands**(registry / hooks / 파괴적). 전체 플래그 매트릭스는 `ecp --help`와 `ecp admin --help`로 확인하세요.
+
+| 명령 | 용도 |
+|---|---|
+| `inspect ` | 심볼 1개 → 메타데이터, 데코레이터, 시그니처, callers, callees, 1-hop impact |
+| `find ` | 심볼 위치 찾기 — exact(기본) · `--mode fuzzy` 부분 문자열 · `--mode bm25` 어휘 랭킹. bm25는 출력을 source / tests / reference / document / config 버킷으로 분할 |
+| `impact --direction ` | confidence 필터링 포함 blast-radius traversal. `--baseline [`로 changeset impact. |
+| `rename --symbol --new-name ` | 14개 언어에 걸친 AST-aware 다중 파일 rename. 항상 `--dry-run` 먼저. |
+| `cypher ''` | openCypher escape hatch. `m.content`는 소스 본문을 반환. |
+| `coverage` | Registry 개요, 프레임워크 커버리지, blind-spot 카탈로그, 그래프 신선도. |
+| `routes []` | HTTP route(선언형 + 명령형) 열거. `` 지정 시 handler + callers 표시. |
+| `contracts` | 저장소 간 API contract 인벤토리(routes / queue / RPC). |
+| `diff` | Resolver delta — binding tier-degradation + routes / contracts 간선 수준 변경. |
+| `tool-map` | 외부 HTTP / DB / Redis / queue 클라이언트 호출을 파일별 import-binding 분석으로 추출. |
+| `shape-check` | HTTP consumer 접근 패턴과 Route 응답 형태 간 드리프트. |
+| `peers` | 다중 세션 피어 협업(status / diff / log / gc). |
+| `review` | LLM-workflow 감사 집계기 — impact + coverage + tool-map + shape-check + diff를 한 번에 실행해 고신뢰 신호만 필터링. |
+
+]
+Admin namespace — ecp admin <cmd>(registry / hooks / 파괴적)
+
+| 명령 | 용도 |
+|---|---|
+| `index --repo ` | 그래프 빌드 / 갱신. xxh3_64 콘텐츠 캐시로 점진적. `--force`로 전체 리빌드. |
+| `drop / prune / rename-branch` | 인덱스 라이프사이클: 삭제, 오래된 branch dir 정리, on-disk 브랜치 리네임. |
+| `install-hook` | git reference-transaction 훅 설치(브랜치 전환 자동 추적). |
+| `config` | `.ecp/config.toml`용 대화형 TOML 위저드. |
+| `mcp serve` / `mcp tools` | LLM 호스트용 MCP server(stdio). `tools`는 노출되는 tool 표면을 나열. |
+| `claude install / codex install / gemini install` | 스크립트 가능한 호스트 통합(skills, hooks, MCP 항목). |
+| `verify-resolver` | resolver 덤프를 language oracle과 diff(ecp-dev QA). |
+
+
+
+모든 명령은 `--graph `가 주어지지 않으면 CWD에서 `.ecp/graph.bin`을 해석합니다. 에이전트용 명령은 설계상 비대화형 — 모든 플래그가 `--help`에서 노출되고, 모든 출력 스트림이 파싱 가능합니다. `ecp admin`을 서브커맨드 없이 실행하면 대화형 admin TUI가 열립니다.
+
+## MCP server
+
+`ecp`는 코어 명령을 MCP tool로 노출하는 MCP server를 함께 제공합니다. MCP를 말할 줄 아는 호스트(Claude Code, Cursor, Windsurf, Cline, Codex CLI, Gemini CLI)는 `ecp`를 등록하고 자율적으로 tool을 호출할 수 있습니다.
+
+```bash
+ecp admin mcp tools # 노출될 tool 미리 보기
+ecp admin mcp serve # 서버 실행(기본은 spawn 모드)
+```
+
+Claude Code용 수동 호스트 설정 예시(`~/.config/claude-code/mcp-servers.json`):
+
+```json
+{
+ "mcpServers": {
+ "ecp": { "command": "ecp", "args": ["admin", "mcp", "serve"] }
+ }
+}
+```
+
+사람 운영자용 점진적 경로:
+
+```text
+ecp admin → Agent Integrations → MCP → → install
+```
+
+AI 에이전트용 스크립트 경로:
+
+```bash
+ecp admin claude install mcp-server
+ecp admin gemini install skills
+```
+
+
+Codex CLI 네이티브 통합(MCP와 분리 — openai/codex 포크용 패치 준비)
+
+Codex 네이티브 경로는 작동 중인 Codex 설치를 편집하지 않습니다. `openai/codex` 포크에 적용할 패치를 작성합니다.
+
+점진적 경로:
+
+```text
+ecp admin → Agent Integrations → Codex CLI → install → native-tools
+```
+
+번들된 skills(동일한 점진 경로):
+
+```text
+ecp admin → Agent Integrations → Codex CLI → install → skills → all | ecp | simplify
+```
+
+에이전트용 스크립트 경로:
+
+```bash
+ecp admin codex install native-tools
+ecp admin codex install skills all
+ecp admin codex install skills ecp
+ecp admin codex install skills simplify
+```
+
+번들된 skills는 command help만으로는 추론할 수 없는 워크플로 선택을 가르칩니다:
+
+| Skill | 언제 |
+|---|---|
+| `ecp` | 에이전트가 graph-aware한 symbol / impact / route / contract / rename 워크플로가 grep / 파일 읽기보다 더 나은지 판단해야 할 때. |
+| `simplify` | 에이전트가 변경된 코드를 리뷰 중이고, 원시 diff를 읽기 전에 `ecp impact`, blind spot, egress, shape drift, resolver delta에서 시작해야 할 때. |
+
+`native-tools` 컴포넌트가 쓰는 파일:
+
+```text
+~/.config/ecp/host-integration/codex-cli.patch
+```
+
+Codex CLI 포크에서 적용:
+
+```bash
+cd /path/to/openai-codex-fork
+git apply ~/.config/ecp/host-integration/codex-cli.patch
+```
+
+이미 네이티브 마커가 있는 포크를 검증 — status 확인 전에 `ECP_CODEX_CLI_CHECKOUT` 설정:
+
+```bash
+ECP_CODEX_CLI_CHECKOUT=/path/to/openai-codex-fork ecp admin codex status
+ecp admin codex uninstall native-tools
+ecp admin codex uninstall skills all
+```
+
+
+
+## 아키텍처
+
+```
+crates/
+├── ecp-core 제로카피 그래프(rkyv + mmap), 점진적 캐시, 그래프 쿼리
+├── ecp-analyzer Tree-sitter 파서, HTTP route 디텍터, 프레임워크 신뢰도
+├── ecp-mcp MCP server(stdio) — 코어 명령을 tool로 노출
+└── ecp-cli `ecp` 바이너리, Tantivy BM25 엔진, 토큰 최적화된 출력
+```
+
+Parse → resolve → serialize는 MPSC 채널을 통해 단일 builder 스레드로 흘러 들어가, 그래프를 조립하고 제로카피 `.ecp/graph.bin`을 씁니다. 읽기 경로(`inspect`, `cypher`, `impact`, …)는 이 파일을 직접 mmap합니다. xxh3_64 콘텐츠 캐시 덕분에 22k 파일 저장소도 점진적 리빌드가 서브초 단위로 유지됩니다.
+
+## 언어 커버리지
+
+31개 언어를 구조 수준(함수 / 클래스 / 메서드 / import / call)으로 파싱합니다. 그중 14개 — 원본 GitNexus 세트 — 는 import, named binding, export, heritage, type, 생성자, config, 프레임워크, entry point, call, rename에 걸쳐 풀-뎁스 커버리지를 가집니다. 나머지 17개는 구조 전용입니다(Bash, Crystal, Cairo, Dockerfile, Docker Compose, GitHub Actions, HCL, Lua, Markdown, Move, Nim, Solidity, SQL, Verilog, Vyper, YAML, Zig).
+
+📊 [언어별 케이퍼빌리티 전체 매트릭스](../language-matrix.md) — 언어별 상태와 근거.
+
+## 튜닝
+
+| 환경 변수 | 기본값 | 효과 |
+|---|---|---|
+| `ECP_MAX_FILE_BYTES` | `16777216`(16 MiB) | 인제스트 중 이보다 큰 소스 파일을 건너뜀. 워커당 워스트케이스 RAM을 `num_threads × MAX`로 제한. |
+| `ECP_CSPROJ_MAX_DEPTH` | `4` | `*.csproj` 탐색용 디렉터리 재귀 깊이. 깊게 중첩된 .NET 모노레포에서 상향 조정. |
+
+## 라이선스
+
+[PolyForm Noncommercial 1.0.0](../../LICENSE.md)으로 라이선스됩니다. 개인 사용, 연구, 취미 프로젝트, 비영리 조직은 명시적으로 허용됩니다. **본 라이선스는 상업적 사용을 부여하지 않습니다** — 상업 라이선스는 upstream GitNexus 저자 [Abhigyan Patwari](https://github.com/abhigyanpatwari)에게 문의하세요. 필요한 귀속 고지: [NOTICES.md](../../LICENSES/NOTICES.md).
+
+
+기반(감사 인사)
+
+- [GitNexus](https://github.com/abhigyanpatwari/GitNexus) — 원본 설계, CLI 표면, 개념 모델
+- [tree-sitter](https://tree-sitter.github.io/) — 점진적 AST 파싱
+- [rkyv](https://rkyv.org/) — 제로카피 역직렬화 프레임워크
+- [Tantivy](https://github.com/quickwit-oss/tantivy) — Rust BM25 전문 검색 엔진
+- [Rayon](https://github.com/rayon-rs/rayon) — 다중 코어 동시 AST 파싱용 데이터 병렬화
+- [xxhash (xxh3_64)](https://xxhash.com/) — 콘텐츠 기반 점진 인덱싱용 해싱
+- [DashMap](https://github.com/xacrimon/dashmap) — 그래프 어셈블리용 동시성 해시 맵
+- [memmap2](https://github.com/RazrFalcon/memmap2-rs) — 제로카피 메모리 매핑
+- [msgspec](https://github.com/jcrist/msgspec) — IPC용 빠른 JSON 직렬화
+
+AI 에이전트용 온보딩(URL 부트스트랩, Claude Code skill, plugin install)은 `docs/skills/ecp-onboard/`에 있습니다. 동시성 불변식과 재검증 방법: `./scripts/audit/audit-concurrency.sh`.
+
+
+
+## 릴리스 상태
+
+현재 검증된 설치 경로는 `cargo install --git ...`로, `ecp`를 소스에서 빌드합니다. 릴리스 인스톨러에는 이미 checksum과 provenance 검증 흐름이 포함되어 있지만, 바이너리 다운로드 경로를 엔드투엔드로 검증하려면 게시된 태그와 릴리스 자산이 필요합니다. 에이전트용 온보딩 skill은 [docs/skills/ecp-onboard/ONBOARDING.md](../skills/ecp-onboard/ONBOARDING.md)에 문서화되어 있으며, 설치·첫 인덱스·선택적 그룹·MCP wiring·다음 단계를 안내합니다 — 보조 셋업 흐름은 계속 다듬어지고 있습니다.
+
+---
+
+## Star History
+
+[](https://star-history.com/#coseto6125/egent-code-plexus&Date)
diff --git a/docs/readme_i18n/README_pt-BR.md b/docs/readme_i18n/README_pt-BR.md
new file mode 100644
index 000000000..cc57f890c
--- /dev/null
+++ b/docs/readme_i18n/README_pt-BR.md
@@ -0,0 +1,340 @@
+# EgentCodePlexus
+
+[](https://scorecard.dev/viewer/?uri=github.com/coseto6125/egent-code-plexus)
+
+[](https://github.com/coseto6125/egent-code-plexus/releases)
+[](https://github.com/coseto6125/egent-code-plexus/releases)
+[](https://github.com/coseto6125/egent-code-plexus/releases)
+[](https://github.com/coseto6125/egent-code-plexus/blob/main/skill_sample/claude/SKILL.md)
+[](https://github.com/coseto6125/egent-code-plexus/blob/main/skill_sample/codex/ecp/SKILL.md)
+[](https://github.com/coseto6125/egent-code-plexus/blob/main/docs/skills/ecp-onboard/guides/04-mcp.md)
+
+`cold index 2.60 s · query p50 142 ms · 31 languages · BlindSpot edges (no hallucinated dispatch) · 60× upstream gitnexus`
+
+[English](../../README.md) · [繁體中文](./README_zh-TW.md) · [简体中文](./README_zh-CN.md) · [Español](./README_es.md) · [Русский](./README_ru.md) · [हिन्दी](./README_hi.md) · [日本語](./README_ja.md) · [한국어](./README_ko.md) · **Português (BR)**
+
+---
+
+## o caso
+
+Agentes de código fazem entre 20 e 50 buscas por tarefa. O `grep` devolve strings; um agente autônomo precisa de símbolos, chamadores, arestas e um sinal honesto quando o grafo estático acaba.
+
+`ecp` é a camada de conhecimento estrutural que é:
+
+- **sem estado.** Cada chamada faz `mmap` de um grafo `rkyv` zero-copy e termina. Sem daemon para manter aquecido, sem o modo de falha «servidor caiu, reinicie».
+- **honesto.** Quando um ponto de chamada não pode ser resolvido estaticamente (dispatch dinâmico, import não resolvido, reflection), o `ecp` emite um registro `BlindSpot`. Um agente que age sobre uma dependência alucinada custa mais do que um que recebe um «não sei» e contorna o problema.
+- **barato em tokens.** Saída padrão é TOON (key:value compacto). Cada flag aparece em `--help`. Cada comando é não-interativo e seu `stdout` é parseável. Sem ruído de UI consumindo a janela de contexto.
+- **poliglota.** 31 linguagens parseadas no nível estrutural — código de serviço, Dockerfiles, GitHub Actions, Terraform, SQL e smart contracts deixam de ser buracos negros assim que você sai da linguagem principal.
+
+Construído sobre o [GitNexus](https://github.com/abhigyanpatwari/GitNexus) do [Abhigyan Patwari](https://github.com/abhigyanpatwari) — mesmo modelo conceitual, reescrito em Rust para um público diferente.
+
+🎙️ **[Entrevistas com agentes](../../interviews/README.md)** — Gemini CLI e Codex avaliam o `ecp` em fluxos autônomos.
+
+## recibos
+
+Cabeça a cabeça contra o upstream GitNexus, medido sobre a codebase do [gitnexus](https://github.com/abhigyanpatwari/GitNexus) (TypeScript) usando `scripts/parity/benchmark_vs_gitnexus.py`:
+
+| Fase | ecp (Rust) | gitnexus (Node) | Aceleração |
+|---|---|---|---|
+| **Cold Index** | **~970 ms** | ~58 s | **60×** |
+| **Symbol Context** | **~70 ms** | ~430 ms | **6×** |
+| **Blast Radius** | **~70 ms** | ~460 ms | **6×** |
+| **Cypher Query** | **~70 ms** | ~400 ms | **5×** |
+
+Os números do `ecp` incluem o startup completo do processo (sem daemon). Os do GitNexus (v1.6.5) são contra um repo já indexado e aquecido via seu CLI.
+
+
+Escalabilidade — execução única sobre .sample_repo (2,1 GB poliglota, ~40 projetos OSS, 25+ linguagens)
+
+**Desempenho de ingestão**
+
+| Fase | Valor |
+|---|---|
+| Arquivos indexados | **22.645** em 25 linguagens detectadas |
+| Wall-clock (frio) | **2,60 s** (parse + resolve + serialize) |
+| Wall-clock (incremental) | **4,9 ms** (caminhada de hash xxh3_64, zero arquivos sujos) |
+| Hardware | AMD Ryzen 9 9950X (16 lógicos), 39,2 GiB RAM, Linux 6.6.87 |
+
+**Latência por consulta** (inclui startup do processo)
+
+| Consulta | Mediana | Notas |
+|---|---|---|
+| `coverage` (overview do registry) | **1,4 ms** | menor leitura — apenas mmap do registry |
+| `routes` (mapa HTTP do repo inteiro) | **142,3 ms** | enumera declarativas + imperativas |
+| `coverage --detailed` (frameworks + blind-spots) | **143,4 ms** | registry completo + scoring por framework |
+| `impact --direction down` | **145,0 ms** | BFS sobre Calls / Extends |
+| `inspect ` (assinatura + callers + callees) | **145,6 ms** | resolução de símbolo + traversal 1-hop |
+| `find --mode bm25` (busca lexical) | **154,5 ms** | consulta Tantivy + partição em 5 baldes |
+| `cypher 'MATCH (a:Class)-[:HasMethod]->(b:Method) ...'` | **161,5 ms** | um padrão, uma linha |
+| `cypher 'MATCH (a:Method)-[:Calls]->(b:Method) ...'` | **174,2 ms** | padrão mais amplo, mais matches |
+| `impact --baseline HEAD~1` (blast radius do changeset) | **359,0 ms** | git diff + parse paralelo por arquivo + BFS |
+
+Reproduzir: `python scripts/benchmark/benchmark_ecp.py`.
+
+
+
+## vs. upstream gitnexus
+
+Mesmo modelo conceitual, audiência diferente. O `ecp` **não** é um substituto drop-in — escolha pelo público que vai ler o grafo.
+
+| Dimensão | EgentCodePlexus | GitNexus |
+|---|---|---|
+| Consumidor primário | Agentes de código autônomos | Devs humanos + integração IDE |
+| Runtime | CLI one-shot sem estado (zero warm-up) | MCP server de longa duração |
+| Desempenho | **< 2,5 s cold index / < 150 ms query** | ~60 s cold index / ~400 ms query |
+| Aresta não resolvida | Registro `BlindSpot` (desconhecido honesto) | Chute heurístico |
+| Saída padrão | TOON / JSON compacto (token-barato) | Renderização wiki / UI |
+| Linguagens | 31 (14 profundas + 17 estruturais) | 14 (profundas, 9 dimensões) |
+| Armazenamento | Rust + `rkyv` zero-copy mmap | Node.js + LadybugDB |
+
+Detalhamento completo das 8 dimensões + matriz de decisão → [docs/vs-gitnexus.md](../vs-gitnexus.md).
+
+## demo de 30 segundos
+
+```bash
+$ ecp impact parse_with_budget --direction upstream --format toon
+```
+
+```text
+target parse_with_budget
+ kind Function
+ file crates/ecp-analyzer/src/parse_budget.rs:28
+risk_level HIGH
+direct_callers 22 across 22 files
+ crates/ecp-analyzer/src/python/parser.rs:48 Method parse_file
+ crates/ecp-analyzer/src/rust/parser.rs:142 Method parse_file
+ crates/ecp-analyzer/src/typescript/parser.rs:73 Method parse_file
+ crates/ecp-analyzer/src/go/parser.rs:69 Method parse_file
+ ... (18 more language parsers)
+transitive 231 symbols across language detection + pipeline
+blind_spots 0
+```
+
+Esse é o round-trip inteiro — um processo, um mmap, ~140 ms. Comandos de leitura aceitam `--format text|json|toon`; o default por comando é a codificação mais barata em tokens.
+
+## instalação
+
+Binários pré-compilados são publicados a cada GitHub Release. Os scripts do instalador caem para um cargo source build apenas quando não há um asset de release correspondente.
+
+```bash
+# Linux / macOS
+curl -sSfL https://github.com/coseto6125/egent-code-plexus/releases/latest/download/install.sh | sh
+
+# Windows PowerShell
+iwr https://github.com/coseto6125/egent-code-plexus/releases/latest/download/install.ps1 -UseBasicParsing | iex
+
+# Via cargo direto (mesmo source build, sem wrapper do instalador)
+cargo install --git https://github.com/coseto6125/egent-code-plexus egent-code-plexus --bin ecp --locked
+```
+
+
+Source build tuned para CPU
+
+```bash
+repo=https://github.com/coseto6125/egent-code-plexus
+RUSTFLAGS="-C target-cpu=native" cargo install --git "$repo" egent-code-plexus --bin ecp --locked --profile release-dist
+```
+
+
+
+## início rápido
+
+```bash
+# 1. Indexa o repo atual (incremental; a primeira query também faz auto-index)
+ecp admin index --repo .
+
+# 2. Localiza um símbolo — nome exato por padrão
+ecp find loginUser
+ecp find login --mode bm25 # ranking BM25, top-K em baldes source/tests/ref/doc/config
+
+# 3. Blast radius — quem quebra se eu mudar isso?
+ecp impact validateUser --direction upstream
+
+# 4. Contexto completo do símbolo (assinatura, body, callers, callees, 1-hop impact)
+ecp inspect validateUser
+
+# 5. Todas as rotas HTTP do repo (declarativas @Get + imperativas app.get())
+ecp routes
+ecp routes /api/users --method POST # rota → handler → cadeia de callers
+```
+
+## cli surface
+
+Dois níveis — **comandos de agente** no top level (query / refactor / verify) e **comandos admin** sob `ecp admin` (registry / hooks / destrutivos). Rode `ecp --help` e `ecp admin --help` para as matrizes completas de flags.
+
+| Comando | Propósito |
+|---|---|
+| `inspect ` | Um símbolo → metadata, decoradores, assinatura, callers, callees, 1-hop impact |
+| `find ` | Localiza símbolos — exact (padrão) · `--mode fuzzy` substring · `--mode bm25` ranking léxico; bm25 particiona a saída em baldes source / tests / reference / document / config |
+| `impact --direction ` | Traversal de blast-radius com filtragem por confiança. `--baseline [` para impact por changeset. |
+| `rename --symbol --new-name ` | Rename AST-aware multi-arquivo em 14 linguagens. Sempre `--dry-run` primeiro. |
+| `cypher ''` | Escape hatch openCypher; `m.content` devolve o corpo do fonte. |
+| `coverage` | Overview do registry, cobertura por framework, catálogo de blind-spots, frescor do grafo. |
+| `routes []` | Enumera rotas HTTP (declarativas + imperativas); com `` mostra handler + callers. |
+| `contracts` | Inventário cross-repo de contratos API (routes / queue / RPC). |
+| `diff` | Delta do resolver — binding tier-degradation + mudanças de routes / contracts em nível de aresta. |
+| `tool-map` | Chamadas a clients externos HTTP / DB / Redis / queue via análise de import-binding por arquivo. |
+| `shape-check` | Drift entre padrões de acesso do consumer HTTP e a forma de resposta da Route. |
+| `peers` | Colaboração multi-sessão entre pares (status / diff / log / gc). |
+| `review` | Agregador de auditoria LLM-workflow — impact + coverage + tool-map + shape-check + diff, filtrado para sinais de alta confiança. |
+
+]
+Namespace admin — ecp admin <cmd> (registry / hooks / destrutivos)
+
+| Comando | Propósito |
+|---|---|
+| `index --repo ` | Constrói / atualiza o grafo; incremental via cache de conteúdo xxh3_64. `--force` para rebuild completo. |
+| `drop / prune / rename-branch` | Ciclo de vida do índice: deletar, podar dirs de branch obsoletos, renomear branch on-disk. |
+| `install-hook` | Instala o hook git reference-transaction (auto-tracking de mudanças de branch). |
+| `config` | Wizard TOML interativo para `.ecp/config.toml`. |
+| `mcp serve` / `mcp tools` | MCP server (stdio) para hosts LLM; `tools` lista a superfície de tools exposta. |
+| `claude install / codex install / gemini install` | Integração scriptável de host (skills, hooks, entradas MCP). |
+| `verify-resolver` | Diff do dump do resolver contra um oracle de linguagem (QA para ecp-dev). |
+
+
+
+Todos os comandos resolvem `.ecp/graph.bin` a partir do CWD a menos que `--graph ` seja passado. Comandos voltados a agente são não-interativos por design — toda flag sai em `--help`, todo stream de saída é parseável. Execute `ecp admin` sem subcomando para abrir o TUI admin interativo.
+
+## MCP server
+
+O `ecp` traz um MCP server que expõe os comandos core como tools MCP. Hosts que falam MCP (Claude Code, Cursor, Windsurf, Cline, Codex CLI, Gemini CLI) podem registrar `ecp` e chamar as tools autonomamente.
+
+```bash
+ecp admin mcp tools # inspeciona quais tools serão expostas
+ecp admin mcp serve # roda o server (modo spawn por padrão)
+```
+
+Exemplo de configuração manual do host para Claude Code (`~/.config/claude-code/mcp-servers.json`):
+
+```json
+{
+ "mcpServers": {
+ "ecp": { "command": "ecp", "args": ["admin", "mcp", "serve"] }
+ }
+}
+```
+
+Caminho progressivo para operadores humanos:
+
+```text
+ecp admin → Agent Integrations → MCP → → install
+```
+
+Caminho scriptado para agentes IA:
+
+```bash
+ecp admin claude install mcp-server
+ecp admin gemini install skills
+```
+
+
+Integração nativa do Codex CLI (separada de MCP — prepara um patch para um fork do openai/codex)
+
+O caminho nativo do Codex não edita a instalação do Codex em uso; escreve um patch que você aplica a um fork do `openai/codex`.
+
+Caminho progressivo:
+
+```text
+ecp admin → Agent Integrations → Codex CLI → install → native-tools
+```
+
+Skills incluídos (mesmo caminho progressivo):
+
+```text
+ecp admin → Agent Integrations → Codex CLI → install → skills → all | ecp | simplify
+```
+
+Caminho scriptado para agentes:
+
+```bash
+ecp admin codex install native-tools
+ecp admin codex install skills all
+ecp admin codex install skills ecp
+ecp admin codex install skills simplify
+```
+
+Os skills incluídos ensinam seleção de workflow que o command help não consegue inferir:
+
+| Skill | Quando usar |
+|---|---|
+| `ecp` | O agente precisa decidir se workflows graph-aware de symbol / impact / route / contract / rename batem grep / leitura de arquivos. |
+| `simplify` | O agente está revisando código alterado e deve começar por `ecp impact`, blind spots, egress, shape drift e resolver deltas antes de ler diffs crus. |
+
+O componente `native-tools` escreve:
+
+```text
+~/.config/ecp/host-integration/codex-cli.patch
+```
+
+Aplique no seu fork do Codex CLI:
+
+```bash
+cd /path/to/openai-codex-fork
+git apply ~/.config/ecp/host-integration/codex-cli.patch
+```
+
+Para verificar um fork que já tem o marcador nativo — defina `ECP_CODEX_CLI_CHECKOUT` antes de consultar status:
+
+```bash
+ECP_CODEX_CLI_CHECKOUT=/path/to/openai-codex-fork ecp admin codex status
+ecp admin codex uninstall native-tools
+ecp admin codex uninstall skills all
+```
+
+
+
+## arquitetura
+
+```
+crates/
+├── ecp-core Grafo zero-copy (rkyv + mmap), cache incremental, queries de grafo
+├── ecp-analyzer Parsers tree-sitter, detector de rotas HTTP, confiança por framework
+├── ecp-mcp MCP server (stdio) — expõe comandos core como tools
+└── ecp-cli Binário `ecp`, engine BM25 do Tantivy, saída otimizada para tokens
+```
+
+Parse → resolve → serialize roda através de um canal MPSC para uma única thread builder que monta o grafo e escreve um `.ecp/graph.bin` zero-copy. As rotas de leitura (`inspect`, `cypher`, `impact`, …) fazem mmap direto desse arquivo. O cache de conteúdo xxh3_64 mantém os rebuilds incrementais em sub-segundo num repo de 22k arquivos.
+
+## cobertura de linguagens
+
+31 linguagens parseadas no nível estrutural (funções / classes / métodos / imports / calls). 14 delas — o conjunto original do GitNexus — recebem cobertura full-depth em imports, named bindings, exports, herança, types, construtores, config, frameworks, entry points, calls e rename. As outras 17 são structural-only (Bash, Crystal, Cairo, Dockerfile, Docker Compose, GitHub Actions, HCL, Lua, Markdown, Move, Nim, Solidity, SQL, Verilog, Vyper, YAML, Zig).
+
+📊 [Matriz completa de capacidades por linguagem](../language-matrix.md) — status e racional por linguagem.
+
+## tuning
+
+| Variável de ambiente | Padrão | Efeito |
+|---|---|---|
+| `ECP_MAX_FILE_BYTES` | `16777216` (16 MiB) | Pula arquivos source maiores que isso durante a ingestão. Limita o pior caso de RAM por worker a `num_threads × MAX`. |
+| `ECP_CSPROJ_MAX_DEPTH` | `4` | Profundidade de recursão de diretórios para descoberta de `*.csproj`. Aumente para monorepos .NET muito aninhados. |
+
+## licença
+
+Licenciado sob [PolyForm Noncommercial 1.0.0](../../LICENSE.md). Uso pessoal, pesquisa, projetos hobby e organizações sem fins lucrativos são explicitamente permitidos. **Uso comercial não é concedido por esta licença** — entre em contato com o autor upstream do GitNexus [Abhigyan Patwari](https://github.com/abhigyanpatwari) para direitos comerciais. Atribuição obrigatória: [NOTICES.md](../../LICENSES/NOTICES.md).
+
+
+Construído sobre (agradecimentos)
+
+- [GitNexus](https://github.com/abhigyanpatwari/GitNexus) — design original, superfície CLI, modelo conceitual
+- [tree-sitter](https://tree-sitter.github.io/) — parsing AST incremental
+- [rkyv](https://rkyv.org/) — framework de desserialização zero-copy
+- [Tantivy](https://github.com/quickwit-oss/tantivy) — engine de busca BM25 em Rust
+- [Rayon](https://github.com/rayon-rs/rayon) — paralelismo de dados para parsing AST multinúcleo
+- [xxhash (xxh3_64)](https://xxhash.com/) — hashing para indexação incremental baseada em conteúdo
+- [DashMap](https://github.com/xacrimon/dashmap) — hash maps concorrentes para montagem do grafo
+- [memmap2](https://github.com/RazrFalcon/memmap2-rs) — memory mapping zero-copy
+- [msgspec](https://github.com/jcrist/msgspec) — serialização JSON rápida para IPC
+
+O onboarding para agentes IA (bootstrap por URL, skill do Claude Code, instalação de plugin) vive em `docs/skills/ecp-onboard/`. Invariantes de concorrência e como re-verificá-los: `./scripts/audit/audit-concurrency.sh`.
+
+
+
+## status de release
+
+O caminho de instalação verificado atual é `cargo install --git ...`, que compila `ecp` a partir do source. Os release installers já contêm o fluxo de verificação de checksum e procedência, mas requerem uma tag publicada e release assets antes que o caminho de download do binário possa ser verificado end-to-end. O skill de onboarding voltado a agentes em [docs/skills/ecp-onboard/ONBOARDING.md](../skills/ecp-onboard/ONBOARDING.md) guia os usuários por install, first-index, groups opcionais, wiring de MCP e próximos passos — o fluxo de setup assistido segue sendo refinado.
+
+---
+
+## Star History
+
+[](https://star-history.com/#coseto6125/egent-code-plexus&Date)
diff --git a/docs/readme_i18n/README_ru.md b/docs/readme_i18n/README_ru.md
new file mode 100644
index 000000000..862c19591
--- /dev/null
+++ b/docs/readme_i18n/README_ru.md
@@ -0,0 +1,340 @@
+# EgentCodePlexus
+
+[](https://scorecard.dev/viewer/?uri=github.com/coseto6125/egent-code-plexus)
+
+[](https://github.com/coseto6125/egent-code-plexus/releases)
+[](https://github.com/coseto6125/egent-code-plexus/releases)
+[](https://github.com/coseto6125/egent-code-plexus/releases)
+[](https://github.com/coseto6125/egent-code-plexus/blob/main/skill_sample/claude/SKILL.md)
+[](https://github.com/coseto6125/egent-code-plexus/blob/main/skill_sample/codex/ecp/SKILL.md)
+[](https://github.com/coseto6125/egent-code-plexus/blob/main/docs/skills/ecp-onboard/guides/04-mcp.md)
+
+`cold index 2.60 s · query p50 142 ms · 31 languages · BlindSpot edges (no hallucinated dispatch) · 60× upstream gitnexus`
+
+[English](../../README.md) · [繁體中文](./README_zh-TW.md) · [简体中文](./README_zh-CN.md) · [Español](./README_es.md) · **Русский** · [हिन्दी](./README_hi.md) · [日本語](./README_ja.md) · [한국어](./README_ko.md) · [Português (BR)](./README_pt-BR.md)
+
+---
+
+## суть
+
+Кодовые агенты выполняют 20–50 запросов на задачу. `grep` возвращает строки; автономному агенту нужны символы, вызывающие, рёбра графа и честный сигнал, когда статический граф не может ответить.
+
+`ecp` — это слой структурного знания, который:
+
+- **без состояния.** Каждый вызов делает `mmap` zero-copy графа `rkyv` и завершается. Никакого демона, который надо поддерживать тёплым, никакого «сервер упал, перезапусти».
+- **честный.** Когда место вызова не разрешается статически (динамический диспатч, неразрешённый import, рефлексия), `ecp` выдаёт запись `BlindSpot`. Агент, действующий на основе галлюцинированной зависимости, обходится дороже, чем тот, кто получает «не знаю» и обходит проблему.
+- **дешёвый по токенам.** Вывод по умолчанию — TOON (компактный key:value). Каждый флаг доступен через `--help`. Каждая команда не интерактивна, а её `stdout` поддаётся парсингу. Никакого UI-мусора, съедающего контекстное окно.
+- **полиглотный.** 31 язык разбирается на структурном уровне — сервисный код, Dockerfile, GitHub Actions, Terraform, SQL и смарт-контракты перестают быть чёрными ящиками, как только вы покидаете основной язык.
+
+Построен поверх [GitNexus](https://github.com/abhigyanpatwari/GitNexus) от [Abhigyan Patwari](https://github.com/abhigyanpatwari) — та же концептуальная модель, переписанная на Rust для другой аудитории.
+
+🎙️ **[Интервью с агентами](../../interviews/README.md)** — Gemini CLI и Codex оценивают `ecp` в автономных рабочих процессах.
+
+## чеки
+
+Лоб в лоб против upstream GitNexus, измерено на кодовой базе [gitnexus](https://github.com/abhigyanpatwari/GitNexus) (TypeScript) с помощью `scripts/parity/benchmark_vs_gitnexus.py`:
+
+| Фаза | ecp (Rust) | gitnexus (Node) | Ускорение |
+|---|---|---|---|
+| **Cold Index** | **~970 мс** | ~58 с | **60×** |
+| **Symbol Context** | **~70 мс** | ~430 мс | **6×** |
+| **Blast Radius** | **~70 мс** | ~460 мс | **6×** |
+| **Cypher Query** | **~70 мс** | ~400 мс | **5×** |
+
+Числа `ecp` включают полный старт процесса (без демона). Числа GitNexus (v1.6.5) — против уже разогретого, индексированного репозитория через его CLI.
+
+
+Масштабируемость — один прогон по .sample_repo (2,1 ГБ полиглот, ~40 OSS-проектов, 25+ языков)
+
+**Производительность загрузки**
+
+| Фаза | Значение |
+|---|---|
+| Проиндексировано файлов | **22 645** на 25 обнаруженных языках |
+| Wall-clock (cold) | **2,60 с** (parse + resolve + serialize) |
+| Wall-clock (инкрементально) | **4,9 мс** (обход xxh3_64, ноль грязных файлов) |
+| Железо | AMD Ryzen 9 9950X (16 логических), 39,2 ГиБ RAM, Linux 6.6.87 |
+
+**Латентность на запрос** (включая старт процесса)
+
+| Запрос | Медиана | Заметки |
+|---|---|---|
+| `coverage` (обзор registry) | **1,4 мс** | минимальное чтение — только mmap registry |
+| `routes` (HTTP route-карта репозитория) | **142,3 мс** | перечисляет декларативные + императивные |
+| `coverage --detailed` (фреймворки + blind-spots) | **143,4 мс** | полный registry + per-framework scoring |
+| `impact --direction down` | **145,0 мс** | BFS по Calls / Extends |
+| `inspect ` (сигнатура + callers + callees) | **145,6 мс** | разрешение символа + 1-hop |
+| `find --mode bm25` (лексический поиск) | **154,5 мс** | запрос Tantivy + 5-ведерное партиционирование |
+| `cypher 'MATCH (a:Class)-[:HasMethod]->(b:Method) ...'` | **161,5 мс** | один паттерн, одна строка |
+| `cypher 'MATCH (a:Method)-[:Calls]->(b:Method) ...'` | **174,2 мс** | более широкий паттерн, больше совпадений |
+| `impact --baseline HEAD~1` (blast radius changeset) | **359,0 мс** | git diff + параллельный per-file parse + BFS |
+
+Воспроизвести: `python scripts/benchmark/benchmark_ecp.py`.
+
+
+
+## vs. upstream gitnexus
+
+Та же концептуальная модель, другая аудитория. `ecp` — **не** drop-in замена; выбирайте по тому, кто читает граф.
+
+| Измерение | EgentCodePlexus | GitNexus |
+|---|---|---|
+| Основной потребитель | Автономные AI-агенты кода | Разработчики-люди + интеграция с IDE |
+| Runtime | One-shot CLI без состояния (нулевой прогрев) | Долгоживущий MCP server |
+| Производительность | **< 2,5 с cold index / < 150 мс query** | ~60 с cold index / ~400 мс query |
+| Неразрешённое ребро | Запись `BlindSpot` (честное «не знаю») | Эвристическая догадка |
+| Вывод по умолчанию | TOON / компактный JSON (дешёвый по токенам) | Wiki / UI рендеринг |
+| Языков | 31 (14 глубоких + 17 структурных) | 14 (глубоких, 9 измерений) |
+| Хранение | Rust + `rkyv` zero-copy mmap | Node.js + LadybugDB |
+
+Полная разбивка по 8 измерениям + матрица решений → [docs/vs-gitnexus.md](../vs-gitnexus.md).
+
+## 30-секундное демо
+
+```bash
+$ ecp impact parse_with_budget --direction upstream --format toon
+```
+
+```text
+target parse_with_budget
+ kind Function
+ file crates/ecp-analyzer/src/parse_budget.rs:28
+risk_level HIGH
+direct_callers 22 across 22 files
+ crates/ecp-analyzer/src/python/parser.rs:48 Method parse_file
+ crates/ecp-analyzer/src/rust/parser.rs:142 Method parse_file
+ crates/ecp-analyzer/src/typescript/parser.rs:73 Method parse_file
+ crates/ecp-analyzer/src/go/parser.rs:69 Method parse_file
+ ... (18 more language parsers)
+transitive 231 symbols across language detection + pipeline
+blind_spots 0
+```
+
+Это весь round-trip — один процесс, один mmap, ~140 мс. Команды чтения принимают `--format text|json|toon`; default на команду — кодировка, наиболее дешёвая по токенам.
+
+## установка
+
+Предсобранные бинарники публикуются с каждым GitHub Release. Скрипты установщика откатываются на cargo source build только когда нет соответствующего release-актива.
+
+```bash
+# Linux / macOS
+curl -sSfL https://github.com/coseto6125/egent-code-plexus/releases/latest/download/install.sh | sh
+
+# Windows PowerShell
+iwr https://github.com/coseto6125/egent-code-plexus/releases/latest/download/install.ps1 -UseBasicParsing | iex
+
+# Прямой путь через cargo (тот же source build, без обёртки установщика)
+cargo install --git https://github.com/coseto6125/egent-code-plexus egent-code-plexus --bin ecp --locked
+```
+
+
+Source build с подстройкой под CPU
+
+```bash
+repo=https://github.com/coseto6125/egent-code-plexus
+RUSTFLAGS="-C target-cpu=native" cargo install --git "$repo" egent-code-plexus --bin ecp --locked --profile release-dist
+```
+
+
+
+## быстрый старт
+
+```bash
+# 1. Индексировать текущий репозиторий (инкрементально; первый запрос тоже авто-индексирует)
+ecp admin index --repo .
+
+# 2. Найти символ — по точному имени по умолчанию
+ecp find loginUser
+ecp find login --mode bm25 # BM25-ранжирование, top-K по корзинам source/tests/ref/doc/config
+
+# 3. Blast radius — кто сломается, если я изменю это?
+ecp impact validateUser --direction upstream
+
+# 4. Полный контекст символа (сигнатура, body, callers, callees, 1-hop impact)
+ecp inspect validateUser
+
+# 5. Все HTTP-маршруты репозитория (декларативные @Get + императивные app.get())
+ecp routes
+ecp routes /api/users --method POST # маршрут → handler → цепочка callers
+```
+
+## cli surface
+
+Два уровня — **команды агента** в верхнем уровне (query / refactor / verify) и **админ-команды** под `ecp admin` (registry / hooks / разрушающие). Запустите `ecp --help` и `ecp admin --help` для полных матриц флагов.
+
+| Команда | Назначение |
+|---|---|
+| `inspect ` | Один символ → метаданные, декораторы, сигнатура, callers, callees, 1-hop impact |
+| `find ` | Локализация символов — exact (default) · `--mode fuzzy` подстрока · `--mode bm25` лексическое ранжирование; bm25 партиционирует вывод в корзины source / tests / reference / document / config |
+| `impact --direction ` | Обход blast-radius с фильтрацией по confidence. `--baseline [` для impact по changeset. |
+| `rename --symbol --new-name ` | AST-aware многофайловый rename по 14 языкам. Всегда сперва `--dry-run`. |
+| `cypher ''` | openCypher escape hatch; `m.content` возвращает тело исходника. |
+| `coverage` | Обзор registry, покрытие фреймворков, каталог blind-spot, свежесть графа. |
+| `routes []` | Перечисляет HTTP-маршруты (декларативные + императивные); с `` показывает handler + callers. |
+| `contracts` | Инвентарь API-контрактов между репозиториями (routes / queue / RPC). |
+| `diff` | Дельта resolver — binding tier-degradation + изменения routes / contracts на уровне рёбер. |
+| `tool-map` | Вызовы внешних HTTP / DB / Redis / queue клиентов через per-file анализ import-binding. |
+| `shape-check` | Дрейф между паттернами доступа HTTP-консюмера и формой ответа Route. |
+| `peers` | Мультисессионная коллаборация пиров (status / diff / log / gc). |
+| `review` | Агрегатор аудита LLM-workflow — impact + coverage + tool-map + shape-check + diff, отфильтрованный до сигналов высокой уверенности. |
+
+]
+Admin namespace — ecp admin <cmd> (registry / hooks / разрушающие)
+
+| Команда | Назначение |
+|---|---|
+| `index --repo ` | Построить / обновить граф; инкрементально через content-кэш xxh3_64. `--force` для полного rebuild. |
+| `drop / prune / rename-branch` | Жизненный цикл индекса: удалить, очистить устаревшие dir веток, переименовать ветку on-disk. |
+| `install-hook` | Установить git reference-transaction hook (автоотслеживание переключения веток). |
+| `config` | Интерактивный TOML-визард для `.ecp/config.toml`. |
+| `mcp serve` / `mcp tools` | MCP server (stdio) для LLM-хостов; `tools` перечисляет экспонированную поверхность tools. |
+| `claude install / codex install / gemini install` | Скриптуемая интеграция хоста (skills, hooks, MCP-записи). |
+| `verify-resolver` | Дифф resolver-дампа против language oracle (QA для ecp-dev). |
+
+
+
+Все команды резолвят `.ecp/graph.bin` от CWD, если не передан `--graph `. Команды для агентов спроектированы неинтерактивными — каждый флаг доступен через `--help`, каждый поток вывода парсится. Запустите `ecp admin` без подкоманды, чтобы открыть интерактивный admin TUI.
+
+## MCP server
+
+`ecp` поставляется с MCP server, экспонирующим core-команды как MCP tools. Хосты, говорящие на MCP (Claude Code, Cursor, Windsurf, Cline, Codex CLI, Gemini CLI), могут зарегистрировать `ecp` и автономно вызывать tools.
+
+```bash
+ecp admin mcp tools # посмотреть, какие tools будут экспонированы
+ecp admin mcp serve # запустить server (режим spawn по умолчанию)
+```
+
+Пример ручной конфигурации хоста для Claude Code (`~/.config/claude-code/mcp-servers.json`):
+
+```json
+{
+ "mcpServers": {
+ "ecp": { "command": "ecp", "args": ["admin", "mcp", "serve"] }
+ }
+}
+```
+
+Прогрессивный путь для операторов-людей:
+
+```text
+ecp admin → Agent Integrations → MCP → → install
+```
+
+Скриптуемый путь для AI-агентов:
+
+```bash
+ecp admin claude install mcp-server
+ecp admin gemini install skills
+```
+
+
+Нативная интеграция Codex CLI (отдельно от MCP — готовит патч для форка openai/codex)
+
+Нативный путь Codex не редактирует работающую установку Codex; он пишет патч, который вы применяете к форку `openai/codex`.
+
+Прогрессивный путь:
+
+```text
+ecp admin → Agent Integrations → Codex CLI → install → native-tools
+```
+
+Бандленные skills (тот же прогрессивный путь):
+
+```text
+ecp admin → Agent Integrations → Codex CLI → install → skills → all | ecp | simplify
+```
+
+Скриптуемый путь для агентов:
+
+```bash
+ecp admin codex install native-tools
+ecp admin codex install skills all
+ecp admin codex install skills ecp
+ecp admin codex install skills simplify
+```
+
+Бандленные skills учат выбору workflow, который command help сам по себе не выводит:
+
+| Skill | Когда использовать |
+|---|---|
+| `ecp` | Агенту нужно решить, лучше ли graph-aware workflows для symbol / impact / route / contract / rename, чем grep / чтение файлов. |
+| `simplify` | Агент ревьюит изменённый код и должен начать с `ecp impact`, blind-spot, egress, shape drift, resolver delta перед чтением сырого diff. |
+
+Компонент `native-tools` пишет:
+
+```text
+~/.config/ecp/host-integration/codex-cli.patch
+```
+
+Применить в вашем форке Codex CLI:
+
+```bash
+cd /path/to/openai-codex-fork
+git apply ~/.config/ecp/host-integration/codex-cli.patch
+```
+
+Проверить форк, в котором уже стоит native-маркер — задайте `ECP_CODEX_CLI_CHECKOUT` перед проверкой статуса:
+
+```bash
+ECP_CODEX_CLI_CHECKOUT=/path/to/openai-codex-fork ecp admin codex status
+ecp admin codex uninstall native-tools
+ecp admin codex uninstall skills all
+```
+
+
+
+## архитектура
+
+```
+crates/
+├── ecp-core Zero-copy граф (rkyv + mmap), инкрементальный кэш, query графа
+├── ecp-analyzer Tree-sitter парсеры, детектор HTTP-маршрутов, confidence по фреймворкам
+├── ecp-mcp MCP server (stdio) — экспонирует core-команды как tools
+└── ecp-cli Бинарник `ecp`, движок BM25 Tantivy, токено-оптимизированный вывод
+```
+
+Parse → resolve → serialize проходит через MPSC-канал в один builder thread, который собирает граф и пишет zero-copy `.ecp/graph.bin`. Пути чтения (`inspect`, `cypher`, `impact`, …) mmap'ят этот файл напрямую. Content-кэш xxh3_64 держит инкрементальные rebuild на уровне сабсекунды на репо в 22k файлов.
+
+## покрытие языков
+
+31 язык разбирается на структурном уровне (функции / классы / методы / imports / calls). 14 из них — оригинальный набор GitNexus — получают full-depth покрытие по imports, named bindings, exports, heritage, types, constructors, config, frameworks, entry points, calls, rename. Оставшиеся 17 — structural-only (Bash, Crystal, Cairo, Dockerfile, Docker Compose, GitHub Actions, HCL, Lua, Markdown, Move, Nim, Solidity, SQL, Verilog, Vyper, YAML, Zig).
+
+📊 [Полная матрица возможностей по языкам](../language-matrix.md) — статус и обоснование по каждому языку.
+
+## тюнинг
+
+| Переменная окружения | Default | Эффект |
+|---|---|---|
+| `ECP_MAX_FILE_BYTES` | `16777216` (16 МиБ) | Пропускать source-файлы больше этого размера при загрузке. Ограничивает worst-case worker-RAM до `num_threads × MAX`. |
+| `ECP_CSPROJ_MAX_DEPTH` | `4` | Глубина рекурсии каталогов при поиске `*.csproj`. Повысьте для глубоко вложенных .NET-монорепозиториев. |
+
+## лицензия
+
+Лицензировано под [PolyForm Noncommercial 1.0.0](../../LICENSE.md). Личное использование, исследования, хобби-проекты и некоммерческие организации явно разрешены. **Коммерческое использование этой лицензией не предоставляется** — для коммерческих прав обращайтесь к upstream-автору GitNexus [Abhigyan Patwari](https://github.com/abhigyanpatwari). Необходимая атрибуция: [NOTICES.md](../../LICENSES/NOTICES.md).
+
+
+Стоит на плечах (благодарности)
+
+- [GitNexus](https://github.com/abhigyanpatwari/GitNexus) — оригинальный дизайн, CLI-поверхность, концептуальная модель
+- [tree-sitter](https://tree-sitter.github.io/) — инкрементальный AST-парсинг
+- [rkyv](https://rkyv.org/) — zero-copy фреймворк десериализации
+- [Tantivy](https://github.com/quickwit-oss/tantivy) — поисковый движок BM25 на Rust
+- [Rayon](https://github.com/rayon-rs/rayon) — параллелизм данных для многоядерного AST-парсинга
+- [xxhash (xxh3_64)](https://xxhash.com/) — хеширование для контентно-зависимого инкрементального индексирования
+- [DashMap](https://github.com/xacrimon/dashmap) — конкурентные хеш-таблицы для сборки графа
+- [memmap2](https://github.com/RazrFalcon/memmap2-rs) — zero-copy memory mapping
+- [msgspec](https://github.com/jcrist/msgspec) — быстрая JSON-сериализация для IPC
+
+Онбординг для AI-агентов (URL-bootstrap, Claude Code skill, plugin install) живёт в `docs/skills/ecp-onboard/`. Инварианты конкурентности и как их перепроверить: `./scripts/audit/audit-concurrency.sh`.
+
+
+
+## статус релиза
+
+Текущий проверенный путь установки — `cargo install --git ...`, который собирает `ecp` из исходников. Release-установщики уже содержат поток проверки checksum и provenance, но требуют опубликованного тега и release-активов, прежде чем путь скачивания бинарника может быть верифицирован end-to-end. Onboarding-skill для агентов в [docs/skills/ecp-onboard/ONBOARDING.md](../skills/ecp-onboard/ONBOARDING.md) проводит пользователей через установку, первую индексацию, опциональные группы, MCP wiring и следующие шаги — assisted-setup-флоу всё ещё дорабатывается.
+
+---
+
+## Star History
+
+[](https://star-history.com/#coseto6125/egent-code-plexus&Date)
diff --git a/docs/readme_i18n/README_zh-CN.md b/docs/readme_i18n/README_zh-CN.md
new file mode 100644
index 000000000..77cd77ecf
--- /dev/null
+++ b/docs/readme_i18n/README_zh-CN.md
@@ -0,0 +1,340 @@
+# EgentCodePlexus
+
+[](https://scorecard.dev/viewer/?uri=github.com/coseto6125/egent-code-plexus)
+
+[](https://github.com/coseto6125/egent-code-plexus/releases)
+[](https://github.com/coseto6125/egent-code-plexus/releases)
+[](https://github.com/coseto6125/egent-code-plexus/releases)
+[](https://github.com/coseto6125/egent-code-plexus/blob/main/skill_sample/claude/SKILL.md)
+[](https://github.com/coseto6125/egent-code-plexus/blob/main/skill_sample/codex/ecp/SKILL.md)
+[](https://github.com/coseto6125/egent-code-plexus/blob/main/docs/skills/ecp-onboard/guides/04-mcp.md)
+
+`cold index 2.60 s · query p50 142 ms · 31 languages · BlindSpot edges (no hallucinated dispatch) · 60× upstream gitnexus`
+
+[English](../../README.md) · [繁體中文](./README_zh-TW.md) · **简体中文** · [Español](./README_es.md) · [Русский](./README_ru.md) · [हिन्दी](./README_hi.md) · [日本語](./README_ja.md) · [한국어](./README_ko.md) · [Português (BR)](./README_pt-BR.md)
+
+---
+
+## 为什么
+
+Code agent 一次任务里会做 20–50 次代码查找。Grep 给你字符串；自主代理需要的是符号、调用者、边（edge），与「graph 推不出来时诚实说不知道」的信号。
+
+`ecp` 是这层结构知识，特性是：
+
+- **无状态。** 每次调用 `mmap` 一个 `rkyv` 零拷贝 graph，跑完直接 exit。没有 daemon 要保温、没有「server 死了请重启」这种失败模式。
+- **诚实。** 当调用点静态解析不出来（动态派发、未解析 import、reflection），`ecp` 发出 `BlindSpot` 纪录。代理对着幻觉出来的依赖下手，比代理收到一个「我不知道」然后绕道的成本高得多。
+- **Token 便宜。** 缺省输出 TOON（紧凑 key:value）。每个 flag 都从 `--help` 出来、每个指令都 non-interactive 且 stdout 可解析。没有耗 context window 的 UI 杂讯。
+- **多语言。** 31 个语言做结构级解析 —— service code、Dockerfile、GitHub Actions、Terraform、SQL、智能合约一旦离开主语言也不会变黑洞。
+
+底层概念模型来自 [GitNexus](https://github.com/abhigyanpatwari/GitNexus)（作者 [Abhigyan Patwari](https://github.com/abhigyanpatwari)），`ecp` 用 Rust 重写成另一种读者导向版本。
+
+🎙️ **[Agent 访谈](../../interviews/README.md)** — Gemini CLI 与 Codex 在自主流程里实测 `ecp` 的纪录。
+
+## 收据
+
+跟上游 GitNexus 对打，在 [gitnexus](https://github.com/abhigyanpatwari/GitNexus) 自家 codebase（TypeScript）上用 `scripts/parity/benchmark_vs_gitnexus.py` 量测：
+
+| 阶段 | ecp (Rust) | gitnexus (Node) | 加速 |
+|---|---|---|---|
+| **Cold Index** | **~970 ms** | ~58 s | **60×** |
+| **Symbol Context** | **~70 ms** | ~430 ms | **6×** |
+| **Blast Radius** | **~70 ms** | ~460 ms | **6×** |
+| **Cypher Query** | **~70 ms** | ~400 ms | **5×** |
+
+`ecp` 的数字包含完整 process 启动时间（无 daemon）。GitNexus（v1.6.5）的数字是已 warm-up + indexed 后跑 CLI。
+
+
+Scalability — .sample_repo 单次完整跑（2.1 GB 多语言、~40 个 OSS 项目、25+ 语言）
+
+**索引性能**
+
+| 阶段 | 值 |
+|---|---|
+| 索引文件数 | **22,645**（25 种侦测到的语言） |
+| Cold 墙钟 | **2.60 s**（parse + resolve + serialize） |
+| Incremental 墙钟 | **4.9 ms**（xxh3_64 hash walk、零 dirty file） |
+| 硬件 | AMD Ryzen 9 9950X（16 逻辑核）、39.2 GiB RAM、Linux 6.6.87 |
+
+**单次查找延迟**（包含 process 启动）
+
+| 查找 | 中位数 | 备注 |
+|---|---|---|
+| `coverage`（registry 总览） | **1.4 ms** | 最小读 — 只 mmap registry |
+| `routes`（HTTP route map 全 repo） | **142.3 ms** | 枚举 declarative + imperative |
+| `coverage --detailed`（框架 + blind-spot） | **143.4 ms** | 完整 registry + per-framework 打分 |
+| `impact --direction down` | **145.0 ms** | BFS 走 Calls / Extends |
+| `inspect `（signature + callers + callees） | **145.6 ms** | 符号解析 + 1-hop traversal |
+| `find --mode bm25`（lexical 搜索） | **154.5 ms** | Tantivy 查找 + 5 桶分区 |
+| `cypher 'MATCH (a:Class)-[:HasMethod]->(b:Method) ...'` | **161.5 ms** | 单 pattern、单 row |
+| `cypher 'MATCH (a:Method)-[:Calls]->(b:Method) ...'` | **174.2 ms** | 更广 pattern、更多 match |
+| `impact --baseline HEAD~1`（变更集 blast radius） | **359.0 ms** | git diff + 并行 per-file parse + BFS |
+
+复现：`python scripts/benchmark/benchmark_ecp.py`。
+
+
+
+## vs. upstream gitnexus
+
+概念模型一样、受众不同。`ecp` **不是** drop-in 替代品 —— 依「谁要读这张 graph」决定用哪个。
+
+| 维度 | EgentCodePlexus | GitNexus |
+|---|---|---|
+| 主要消费者 | 自主 AI code agent | 真人开发者 + IDE 集成 |
+| Runtime | 无状态一次性 CLI（零暖机） | 长驻 MCP server |
+| 性能 | **< 2.5 s cold index / < 150 ms query** | ~60 s cold index / ~400 ms query |
+| 无法解析的 edge | `BlindSpot` 纪录（诚实未知） | 启发式猜测 |
+| 缺省输出 | TOON / compact JSON（token 便宜） | Wiki / UI rendering |
+| 语言 | 31（14 deep + 17 structural） | 14（deep, 9-dimension） |
+| 保存 | Rust + `rkyv` 零拷贝 mmap | Node.js + LadybugDB |
+
+完整 8 维度分析 + 决策矩阵 → [docs/vs-gitnexus.md](../vs-gitnexus.md)。
+
+## 30 秒 demo
+
+```bash
+$ ecp impact parse_with_budget --direction upstream --format toon
+```
+
+```text
+target parse_with_budget
+ kind Function
+ file crates/ecp-analyzer/src/parse_budget.rs:28
+risk_level HIGH
+direct_callers 22 across 22 files
+ crates/ecp-analyzer/src/python/parser.rs:48 Method parse_file
+ crates/ecp-analyzer/src/rust/parser.rs:142 Method parse_file
+ crates/ecp-analyzer/src/typescript/parser.rs:73 Method parse_file
+ crates/ecp-analyzer/src/go/parser.rs:69 Method parse_file
+ ... (18 more language parsers)
+transitive 231 symbols across language detection + pipeline
+blind_spots 0
+```
+
+整个 round-trip 一个 process、一次 mmap、~140 ms。读类指令支持 `--format text|json|toon`；每个指令的缺省都选 token 最便宜的编码。
+
+## 安装
+
+每次 GitHub Release 都发 prebuilt binary。Installer 脚本只有在找不到对应 release asset 时才会 fallback 到 cargo source build。
+
+```bash
+# Linux / macOS
+curl -sSfL https://github.com/coseto6125/egent-code-plexus/releases/latest/download/install.sh | sh
+
+# Windows PowerShell
+iwr https://github.com/coseto6125/egent-code-plexus/releases/latest/download/install.ps1 -UseBasicParsing | iex
+
+# 直接走 cargo（跟 installer 同一个 source build）
+cargo install --git https://github.com/coseto6125/egent-code-plexus egent-code-plexus --bin ecp --locked
+```
+
+
+CPU-tuned source build
+
+```bash
+repo=https://github.com/coseto6125/egent-code-plexus
+RUSTFLAGS="-C target-cpu=native" cargo install --git "$repo" egent-code-plexus --bin ecp --locked --profile release-dist
+```
+
+
+
+## 快速上手
+
+```bash
+# 1. Index 当前 repo（增量；首次查找也会自动 index）
+ecp admin index --repo .
+
+# 2. 找符号 —— 缺省 exact name
+ecp find loginUser
+ecp find login --mode bm25 # BM25 排序、top-K 分 source/tests/ref/doc/config 桶
+
+# 3. 冲击半径 —— 动它会炸到谁？
+ecp impact validateUser --direction upstream
+
+# 4. 完整符号脉络（签名、body、callers、callees、1-hop impact）
+ecp inspect validateUser
+
+# 5. 全 repo HTTP route（declarative @Get + imperative app.get()）
+ecp routes
+ecp routes /api/users --method POST # route → handler → caller chain
+```
+
+## cli surface
+
+两层 —— **agent commands** 在顶层（query / refactor / verify），**admin commands** 在 `ecp admin` 下（registry / hooks / 破坏性操作）。完整 flag 矩阵请跑 `ecp --help` 与 `ecp admin --help`。
+
+| 指令 | 用途 |
+|---|---|
+| `inspect ` | 单一符号 → metadata、decorator、signature、callers、callees、1-hop impact |
+| `find ` | 符号定位 —— exact（缺省）· `--mode fuzzy` 子字符串 · `--mode bm25` 词汇排序；bm25 把输出分到 source / tests / reference / document / config 5 个桶 |
+| `impact --direction ` | 冲击半径遍历 + confidence 过滤。`--baseline [` 做变更集 impact。 |
+| `rename --symbol --new-name ` | 14 语言 AST 感知多档重命名。永远先 `--dry-run`。 |
+| `cypher ''` | openCypher 后门；`m.content` 拿原代码 body。 |
+| `coverage` | Registry 总览、框架覆盖、blind-spot 名单、graph 新鲜度。 |
+| `routes []` | 列出 HTTP route（declarative + imperative）；给 `` 就秀 handler + callers。 |
+| `contracts` | 跨 repo API contract 库存（routes / queue / RPC）。 |
+| `diff` | Resolver delta —— edge 级别 binding tier-degradation + route / contract 变动。 |
+| `tool-map` | 对外部 HTTP / DB / Redis / queue client 的调用（per-file import-binding 分析）。 |
+| `shape-check` | HTTP consumer 访问模式 vs. Route response shape 的漂移。 |
+| `peers` | 多 session 对端协作（status / diff / log / gc）。 |
+| `review` | LLM-workflow 稽核聚合器 —— impact + coverage + tool-map + shape-check + diff，过滤到高信心信号。 |
+
+]
+Admin namespace —— ecp admin <cmd>（registry / hooks / 破坏性）
+
+| 指令 | 用途 |
+|---|---|
+| `index --repo ` | 建 / 刷新 graph；xxh3_64 内容缓存做增量。`--force` 全量重建。 |
+| `drop / prune / rename-branch` | Index 生命周期：删除、清理过时 branch dir、改名 on-disk branch。 |
+| `install-hook` | 装 git reference-transaction hook（自动追踪 branch 切换）。 |
+| `config` | `.ecp/config.toml` 交互式 TOML 精灵。 |
+| `mcp serve` / `mcp tools` | MCP server（stdio）给 LLM host；`tools` 列出曝露的 tool 表面。 |
+| `claude install / codex install / gemini install` | 可脚本化的 host 集成（skills、hooks、MCP entry）。 |
+| `verify-resolver` | 解析器 dump 对 language oracle diff（ecp-dev QA 用）。 |
+
+
+
+所有指令缺省从 CWD 解析 `.ecp/graph.bin`，可用 `--graph ` 改写。Agent 端的指令设计上 non-interactive —— 每个 flag 走 `--help`、每个输出可解析。`ecp admin` 不带 subcommand 开交互 admin TUI。
+
+## MCP server
+
+`ecp` 内置 MCP server，把内核指令以 MCP tool 形式曝露。会说 MCP 的 host（Claude Code、Cursor、Windsurf、Cline、Codex CLI、Gemini CLI）都能注册 `ecp` 然后自主调用。
+
+```bash
+ecp admin mcp tools # 预览要曝露的 tools
+ecp admin mcp serve # 跑 server（缺省 spawn mode）
+```
+
+Claude Code 手动 host 设置范例（`~/.config/claude-code/mcp-servers.json`）：
+
+```json
+{
+ "mcpServers": {
+ "ecp": { "command": "ecp", "args": ["admin", "mcp", "serve"] }
+ }
+}
+```
+
+真人渐进路径：
+
+```text
+ecp admin → Agent Integrations → MCP → → install
+```
+
+AI agent 脚本路径：
+
+```bash
+ecp admin claude install mcp-server
+ecp admin gemini install skills
+```
+
+
+Codex CLI 原生集成（跟 MCP 不一样 —— 对 openai/codex fork 出 patch）
+
+Codex 原生路径不会改你正在跑的 Codex 安装；它写出一份 patch，你拿去套用在 `openai/codex` fork。
+
+渐进路径：
+
+```text
+ecp admin → Agent Integrations → Codex CLI → install → native-tools
+```
+
+内置 skills（同一条路径）：
+
+```text
+ecp admin → Agent Integrations → Codex CLI → install → skills → all | ecp | simplify
+```
+
+Agent 脚本路径：
+
+```bash
+ecp admin codex install native-tools
+ecp admin codex install skills all
+ecp admin codex install skills ecp
+ecp admin codex install skills simplify
+```
+
+内置 skills 教 agent 怎么选工作流，这是 command help 推不出来的：
+
+| Skill | 何时用 |
+|---|---|
+| `ecp` | Agent 要判断 graph 感知的 symbol / impact / route / contract / rename 工作流是否优于 grep / 读档。 |
+| `simplify` | Agent 要 review 变更，应该从 `ecp impact`、blind-spot、egress、shape drift、resolver delta 出发，再读原始 diff。 |
+
+`native-tools` 组件会写：
+
+```text
+~/.config/ecp/host-integration/codex-cli.patch
+```
+
+在你的 Codex CLI fork 套用：
+
+```bash
+cd /path/to/openai-codex-fork
+git apply ~/.config/ecp/host-integration/codex-cli.patch
+```
+
+验证已有 native 标记的 fork —— 设 `ECP_CODEX_CLI_CHECKOUT` 后查状态：
+
+```bash
+ECP_CODEX_CLI_CHECKOUT=/path/to/openai-codex-fork ecp admin codex status
+ecp admin codex uninstall native-tools
+ecp admin codex uninstall skills all
+```
+
+
+
+## 架构
+
+```
+crates/
+├── ecp-core 零拷贝 graph（rkyv + mmap）、增量缓存、graph 查找
+├── ecp-analyzer Tree-sitter parsers、HTTP route 侦测、framework 信心评分
+├── ecp-mcp MCP server（stdio）—— 把内核指令当 tool 曝露
+└── ecp-cli `ecp` binary、Tantivy BM25 引擎、token 优化的输出
+```
+
+Parse → resolve → serialize 过 MPSC channel 进单一 builder thread，组装 graph 后写出零拷贝 `.ecp/graph.bin`。读路径（`inspect`、`cypher`、`impact` …）直接 mmap 这个档。xxh3_64 内容缓存让 22k 档的 repo 增量重建维持亚秒级。
+
+## 语言覆盖
+
+31 个语言做结构级解析（functions / classes / methods / imports / calls）。其中 14 个 —— 原 GitNexus 那组 —— 拿到全深度覆盖，涵盖 imports、named bindings、exports、heritage、types、constructors、config、frameworks、entry points、calls、rename。其余 17 个是 structural-only（Bash、Crystal、Cairo、Dockerfile、Docker Compose、GitHub Actions、HCL、Lua、Markdown、Move、Nim、Solidity、SQL、Verilog、Vyper、YAML、Zig）。
+
+📊 [完整语言能力矩阵](../language-matrix.md) —— 各语言状态与理由。
+
+## 调校
+
+| 环境变量 | 缺省 | 效果 |
+|---|---|---|
+| `ECP_MAX_FILE_BYTES` | `16777216`（16 MiB） | Ingest 时略过超过此值的源文件。把 worst-case worker RAM 锁在 `num_threads × MAX`。 |
+| `ECP_CSPROJ_MAX_DEPTH` | `4` | 找 `*.csproj` 的目录递归深度。.NET 深层 monorepo 可调高。 |
+
+## 授权
+
+采用 [PolyForm Noncommercial 1.0.0](../../LICENSE.md)。个人使用、研究、业余项目、非商业组织明确允许。**本授权不授予商业使用权** —— 商业授权请联系上游 GitNexus 作者 [Abhigyan Patwari](https://github.com/abhigyanpatwari)。必要的归属声明见 [NOTICES.md](../../LICENSES/NOTICES.md)。
+
+
+站在这些巨人肩上（致谢）
+
+- [GitNexus](https://github.com/abhigyanpatwari/GitNexus) — 原始设计、CLI 接口、概念模型
+- [tree-sitter](https://tree-sitter.github.io/) — 增量 AST 解析
+- [rkyv](https://rkyv.org/) — 零拷贝串行化框架
+- [Tantivy](https://github.com/quickwit-oss/tantivy) — Rust BM25 全文搜索引擎
+- [Rayon](https://github.com/rayon-rs/rayon) — 多内核并行 AST 解析的数据并行库
+- [xxhash (xxh3_64)](https://xxhash.com/) — 内容哈希驱动的增量索引
+- [DashMap](https://github.com/xacrimon/dashmap) — 并行哈希表（graph 组装用）
+- [memmap2](https://github.com/RazrFalcon/memmap2-rs) — 零拷贝 mmap，亚毫秒级 graph 读取
+- [msgspec](https://github.com/jcrist/msgspec) — IPC 用高性能 JSON 串行化
+
+AI agent 安装引导（URL bootstrap、Claude Code skill、plugin install）位于 `docs/skills/ecp-onboard/`。并行不变式与如何重新验证：`./scripts/audit/audit-concurrency.sh`。
+
+
+
+## 发布状态
+
+目前已验证的安装路径是 `cargo install --git ...`，从原代码建置 `ecp`。Release installer 已包含 checksum 与 provenance verification 流程，但必须等 tag 与 release assets 发布后，binary 下载路径才能做端到端验证。Agent 安装引导文档在 [docs/skills/ecp-onboard/ONBOARDING.md](../skills/ecp-onboard/ONBOARDING.md) —— 引导用户完成安装、首次索引、可选 group、MCP wiring、后续建议。辅助式设置流程仍在完善中。
+
+---
+
+## Star History
+
+[](https://star-history.com/#coseto6125/egent-code-plexus&Date)
diff --git a/docs/readme_i18n/README_zh-TW.md b/docs/readme_i18n/README_zh-TW.md
index 1e8aa945c..517371ac1 100644
--- a/docs/readme_i18n/README_zh-TW.md
+++ b/docs/readme_i18n/README_zh-TW.md
@@ -1,221 +1,280 @@
# EgentCodePlexus
[](https://scorecard.dev/viewer/?uri=github.com/coseto6125/egent-code-plexus)
-[](https://star-history.com/#coseto6125/egent-code-plexus&Date)
-給 **LLM 與 AI 程式碼代理（AI code agents）** 用的代碼智能圖譜 — 單次 CLI 調用、mmap 零拷貝、每次查詢亞秒級。
+[](https://github.com/coseto6125/egent-code-plexus/releases)
+[](https://github.com/coseto6125/egent-code-plexus/releases)
+[](https://github.com/coseto6125/egent-code-plexus/releases)
+[](https://github.com/coseto6125/egent-code-plexus/blob/main/skill_sample/claude/SKILL.md)
+[](https://github.com/coseto6125/egent-code-plexus/blob/main/skill_sample/codex/ecp/SKILL.md)
+[](https://github.com/coseto6125/egent-code-plexus/blob/main/docs/skills/ecp-onboard/guides/04-mcp.md)
-[English README](../../README.md)
+`cold index 2.60 s · query p50 142 ms · 31 languages · BlindSpot edges (no hallucinated dispatch) · 60× upstream gitnexus`
----
+[English](../../README.md) · **繁體中文** · [简体中文](./README_zh-CN.md) · [Español](./README_es.md) · [Русский](./README_ru.md) · [हिन्दी](./README_hi.md) · [日本語](./README_ja.md) · [한국어](./README_ko.md) · [Português (BR)](./README_pt-BR.md)
-## 🎯 核心使命
+---
-`ecp` 的存在是為了成為自主 AI 代理在每個任務中調用 20-50 次的結構化知識層。所有的設計決策都源於這個前提：
+## 為什麼
-- **為代理而建，非為 IDE。** 輸出格式節省 Token（TOON / 精簡 JSON），每個旗標都透過 `--help` 顯露，每個命令都是非互動式且可解析的。沒有 UI，沒有消耗代理上下文視窗的人類閱讀排版。
-- **無預熱，無守護進程。** 每次調用都會 `mmap` 一個零拷貝的 `rkyv` 圖譜檔案並退出。讀取查詢在 **~140–170 ms** 內返回（*包含進程啟動*）；2.2 萬個檔案的專案冷啟動索引低於 3 秒。代理可以在不考慮伺服器啟動成本的情況下，每個任務發起數十次查詢，且沒有「伺服器當機，請重啟」的故障模式。
-- **老實的回答勝於可讀的圖表。** 當呼叫點無法靜態解析（動態派發、未解析的導入、反射）時，`ecp` 會記錄 `BlindSpot`，而不是隨便連一條邊。一個基於幻覺依賴行動的代理，其成本遠高於一個獲得「我不知道」並能繞道而行的代理。
-- **廣泛的語言覆蓋。** 在結構層級解析 31 種語言，讓現代多語言專案（服務代碼 + Dockerfile + GitHub Actions + Terraform + SQL + 智能合約）在離開主語言後不再是黑洞。
+Code agent 一次任務裡會做 20–50 次代碼查詢。Grep 給你字串；自主代理需要的是符號、呼叫者、邊（edge），與「graph 推不出來時誠實說不知道」的訊號。
-🎙️ **[Agent 訪談紀錄](../../interviews/README_zh-TW.md)** — 查看真實 AI Agent (Gemini CLI, Codex) 在自主工作流中如何使用與評價 `ecp`。
+`ecp` 是這層結構知識，特性是：
-致敬 [GitNexus](https://github.com/abhigyanpatwari/GitNexus)（原作：[Abhigyan Patwari](https://github.com/abhigyanpatwari)）— 同樣的核心想法（repo 的結構化知識圖譜），用 Rust 重寫成面向**另一群受眾**的版本。基於 [PolyForm Noncommercial 1.0.0](../../LICENSE) 授權；完整第三方歸屬清單請見 [NOTICES.md](../../LICENSES/NOTICES.md)。
+- **無狀態。** 每次調用 `mmap` 一個 `rkyv` 零拷貝 graph，跑完直接 exit。沒有 daemon 要保溫、沒有「server 死了請重啟」這種失敗模式。
+- **誠實。** 當呼叫點靜態解析不出來（動態派發、未解析 import、reflection），`ecp` 發出 `BlindSpot` 紀錄。代理對著幻覺出來的依賴下手，比代理收到一個「我不知道」然後繞道的成本高得多。
+- **Token 便宜。** 預設輸出 TOON（緊湊 key:value）。每個 flag 都從 `--help` 出來、每個指令都 non-interactive 且 stdout 可解析。沒有耗 context window 的 UI 雜訊。
+- **多語言。** 31 個語言做結構級解析 —— service code、Dockerfile、GitHub Actions、Terraform、SQL、智能合約一旦離開主語言也不會變黑洞。
----
+底層概念模型來自 [GitNexus](https://github.com/abhigyanpatwari/GitNexus)（作者 [Abhigyan Patwari](https://github.com/abhigyanpatwari)），`ecp` 用 Rust 重寫成另一種讀者導向版本。
-## ⚡ 效能表現
+🎙️ **[Agent 訪談](../../interviews/README.md)** — Gemini CLI 與 Codex 在自主流程裡實測 `ecp` 的紀錄。
-上述的使命說明了 `ecp` 為何如此構建。本節則是實測數據。
+## 收據
-### 與上游 GitNexus 的正面對決
+跟上游 GitNexus 對打，在 [gitnexus](https://github.com/abhigyanpatwari/GitNexus) 自家 codebase（TypeScript）上用 `scripts/parity/benchmark_vs_gitnexus.py` 量測：
-在 [gitnexus](https://github.com/abhigyanpatwari/GitNexus) 代碼庫（TypeScript）上使用 `scripts/parity/benchmark_vs_gitnexus.py` 測量：
-
-| 階段 | ecp (Rust) | gitnexus (Node) | 加速倍率 |
+| 階段 | ecp (Rust) | gitnexus (Node) | 加速 |
|---|---|---|---|
-| **冷啟動索引** | **~970 ms** | ~58 s | **60×** |
-| **符號上下文** | **~70 ms** | ~430 ms | **6×** |
-| **影響範圍** | **~70 ms** | ~460 ms | **6×** |
-| **Cypher 查詢** | **~70 ms** | ~400 ms | **5×** |
+| **Cold Index** | **~970 ms** | ~58 s | **60×** |
+| **Symbol Context** | **~70 ms** | ~430 ms | **6×** |
+| **Blast Radius** | **~70 ms** | ~460 ms | **6×** |
+| **Cypher Query** | **~70 ms** | ~400 ms | **5×** |
-*註：`ecp` 查詢延遲包含了完整的進程啟動時間（無背景常駐程式）。GitNexus (v1.6.5) 的延遲是在已索引且預熱的情況下透過 CLI 測量。*
+`ecp` 的數字包含完整 process 啟動時間（無 daemon）。GitNexus（v1.6.5）的數字是已 warm-up + indexed 後跑 CLI。
-### 可擴展性 — `.sample_repo` 單次運行（包含 25+ 種語言、約 40 個真實開源專案、總計 2.1 GB 的多語言測試集，用於跨語言壓力測試）
+
+Scalability — .sample_repo 單次完整跑（2.1 GB 多語言、~40 個 OSS 專案、25+ 語言）
-**攝入效能：**
+**索引效能**
-| 階段 | 數值 |
+| 階段 | 值 |
|---|---|
-| 已索引檔案數 | **22,645** 個，跨 25 種偵測到的語言 |
-| 冷啟動耗時 | **2.60 s** (解析 + 解析 + 序列化) |
-| 增量索引耗時 | **4.9 ms** (xxh3_64 雜湊掃描，零變動檔案) |
-| 測試硬體 | AMD Ryzen 9 9950X (16 邏輯核心), 39.2 GiB RAM, Linux 6.6.87 |
+| 索引檔案數 | **22,645**（25 種偵測到的語言） |
+| Cold 牆鐘 | **2.60 s**（parse + resolve + serialize） |
+| Incremental 牆鐘 | **4.9 ms**（xxh3_64 hash walk、零 dirty file） |
+| 硬體 | AMD Ryzen 9 9950X（16 邏輯核）、39.2 GiB RAM、Linux 6.6.87 |
-**單次查詢延遲（包含進程啟動）：**
+**單次查詢延遲**（包含 process 啟動）
| 查詢 | 中位數 | 備註 |
|---|---|---|
-| `summary` (註冊表總覽) | **1.4 ms** | 最小讀取 — 僅 mmap 註冊表 |
-| `routes` (全專案 HTTP 路由圖譜) | **142.3 ms** | 列舉聲明式 + 指令式定義 |
-| `summary --detailed` (框架 + 盲區) | **143.4 ms** | 完整註冊表 + 各框架評分 |
-| `impact --direction down` | **145.0 ms** | 遍歷 Calls / Extends 邊 (BFS) |
-| `inspect ` (簽名 + 呼叫鏈) | **145.6 ms** | 符號解析 + 1-hop 遍歷 |
-| `find --mode bm25` (詞法搜尋) | **154.5 ms** | Tantivy 查詢 + 5 個儲存桶分區 |
-| `cypher 'MATCH (a:Class)-[:HasMethod]->(b:Method) ...'` | **161.5 ms** | 單一模式，回傳單列 |
-| `cypher 'MATCH (a:Method)-[:Calls]->(b:Method) ...'` | **174.2 ms** | 較廣泛模式，匹配較多結果 |
-| `impact --baseline HEAD~1` (變更爆炸半徑) | **359.0 ms** | git diff + 平行單檔解析 + BFS |
-
-重現方式：`python scripts/benchmark/benchmark_ecp.py`。
+| `summary`（registry 總覽） | **1.4 ms** | 最小讀取 — 僅 mmap registry |
+| `routes`（全 repo HTTP route map） | **142.3 ms** | 列舉 declarative + imperative |
+| `summary --detailed`（框架 + blind-spot） | **143.4 ms** | 完整 registry + per-framework 打分 |
+| `impact --direction down` | **145.0 ms** | BFS 走 Calls / Extends |
+| `inspect `（signature + callers + callees） | **145.6 ms** | 符號解析 + 1-hop traversal |
+| `find --mode bm25`（lexical 搜尋） | **154.5 ms** | Tantivy 查詢 + 5 桶分區 |
+| `cypher 'MATCH (a:Class)-[:HasMethod]->(b:Method) ...'` | **161.5 ms** | 單 pattern、單 row |
+| `cypher 'MATCH (a:Method)-[:Calls]->(b:Method) ...'` | **174.2 ms** | 更廣 pattern、更多 match |
+| `impact --baseline HEAD~1`（變更集 blast radius） | **359.0 ms** | git diff + 並行 per-file parse + BFS |
----
+復現：`python scripts/benchmark/benchmark_ecp.py`。
+
+
-## 跟上游 GitNexus 的差別
+## vs. upstream gitnexus
-> **不是 drop-in 替代品。** 上游是為人類設計的 Agent 平台；egent-code-plexus 是為 **Coding AI Agent** 量身打造的結構化知識層 — 不同的受眾、不同的權衡。
+概念模型一樣、受眾不同。`ecp` **不是** drop-in 替代品 —— 依「誰要讀這張 graph」決定用哪個。
-| 維度 | egent-code-plexus | GitNexus |
+| 維度 | EgentCodePlexus | GitNexus |
|---|---|---|
-| **核心受眾** | **Coding AI Agent** | 人類開發者 + IDE 整合 |
-| **運行模式** | 無狀態 One-shot CLI (零預熱) | 長駐 MCP server |
-| **效能表現** | **< 2.5s 冷啟動 / < 150ms 查詢** | ~60s 冷啟動 / ~400ms 查詢 |
-| **未解析的邊** | `BlindSpot` 記錄 (老實的未知) | 啟發式猜測 |
-| **預設輸出** | TOON / 精簡 JSON (省 Token) | Wiki / UI 渲染 |
-| **支援語言** | 31 (14 種深度 + 17 種結構層級) | 14 (深度 9 維度覆蓋) |
-| **儲存層** | Rust + `rkyv` 零拷貝 mmap | Node.js + LadybugDB |
+| 主要消費者 | 自主 AI code agent | 真人開發者 + IDE 整合 |
+| Runtime | 無狀態一次性 CLI（零暖機） | 長駐 MCP server |
+| 性能 | **< 2.5 s cold index / < 150 ms query** | ~60 s cold index / ~400 ms query |
+| 無法解析的 edge | `BlindSpot` 紀錄（誠實未知） | 啟發式猜測 |
+| 預設輸出 | TOON / compact JSON（token 便宜） | Wiki / UI rendering |
+| 語言 | 31（14 deep + 17 structural） | 14（deep, 9-dimension） |
+| 儲存 | Rust + `rkyv` 零拷貝 mmap | Node.js + LadybugDB |
-**8 個維度的完整細節、哲學與決策矩陣 → [docs/vs-gitnexus.md](../vs-gitnexus.md)**
+完整 8 維度分析 + 決策矩陣 → [docs/vs-gitnexus.md](../vs-gitnexus.md)。
----
+## 30 秒 demo
+
+```bash
+$ ecp impact parse_with_budget --direction upstream --format toon
+```
+
+```text
+target parse_with_budget
+ kind Function
+ file crates/ecp-analyzer/src/parse_budget.rs:28
+risk_level HIGH
+direct_callers 22 across 22 files
+ crates/ecp-analyzer/src/python/parser.rs:48 Method parse_file
+ crates/ecp-analyzer/src/rust/parser.rs:142 Method parse_file
+ crates/ecp-analyzer/src/typescript/parser.rs:73 Method parse_file
+ crates/ecp-analyzer/src/go/parser.rs:69 Method parse_file
+ ... (18 more language parsers)
+transitive 231 symbols across language detection + pipeline
+blind_spots 0
+```
+
+整個 round-trip 一個 process、一次 mmap、~140 ms。讀類指令支援 `--format text|json|toon`；每個指令的預設都選 token 最便宜的編碼。
-## 📦 安裝
+## 安裝
-在第一個帶 tag 的 Release 發佈前，安裝腳本會 fallback 到 cargo source build。等 release assets 存在後，預編譯 binary 會成為最快路徑。
+每次 GitHub Release 都發 prebuilt binary。Installer 腳本只有在找不到對應 release asset 時才會 fallback 到 cargo source build。
```bash
-# Linux / macOS (最短路徑；尚無 Release assets 時需要 cargo/rustup)
-curl -sSfL https://raw.githubusercontent.com/coseto6125/egent-code-plexus/main/install.sh | sh
+# Linux / macOS
+curl -sSfL https://github.com/coseto6125/egent-code-plexus/releases/latest/download/install.sh | sh
# Windows PowerShell
-iwr https://raw.githubusercontent.com/coseto6125/egent-code-plexus/main/install.ps1 -UseBasicParsing | iex
+iwr https://github.com/coseto6125/egent-code-plexus/releases/latest/download/install.ps1 -UseBasicParsing | iex
-# 明確使用 cargo (同樣是 source build，不經 installer wrapper)
+# 直接走 cargo（跟 installer 同一個 source build）
cargo install --git https://github.com/coseto6125/egent-code-plexus egent-code-plexus --bin ecp --locked
```
-可選的 CPU 最佳化 source build：
+
+CPU-tuned source build
```bash
repo=https://github.com/coseto6125/egent-code-plexus
RUSTFLAGS="-C target-cpu=native" cargo install --git "$repo" egent-code-plexus --bin ecp --locked --profile release-dist
```
----
+
-## 🚀 快速上手
+## 快速上手
```bash
-# 1. 為當前目錄建立索引 (增量式；第一次查詢也會自動觸發)
+# 1. Index 當前 repo（增量；首次查詢也會自動 index）
ecp admin index --repo .
-# 2. 定位符號 — 預設為精準名稱比對
+# 2. 找符號 —— 預設 exact name
ecp find loginUser
-ecp find login --mode bm25 # BM25 排序，分為 source/tests/ref/doc/config 等 bucket
+ecp find login --mode bm25 # BM25 排序、top-K 分 source/tests/ref/doc/config 桶
-# 3. 爆炸半徑 — 我改這裡會壞掉什麼？
+# 3. 衝擊半徑 —— 動它會炸到誰？
ecp impact validateUser --direction upstream
-# 4. 完整的符號上下文 (簽名、body、呼叫者、被呼叫者、1-hop 影響)
+# 4. 完整符號脈絡（簽名、body、callers、callees、1-hop impact）
ecp inspect validateUser
-# 5. 專案中所有的 HTTP 路由 (聲明式 @Get + 指令式 app.get())
+# 5. 全 repo HTTP route（declarative @Get + imperative app.get()）
ecp routes
-ecp routes /api/users --method POST # 路由 → 處理器 → 呼叫鏈
+ecp routes /api/users --method POST # route → handler → caller chain
```
-讀取端命令接受 `--format text|json|toon`。預設為該命令最省 Token 的格式（多數為 `toon`；`find` 預設為 `text`；`cypher`/`summary` 預設為 `json`）。
+讀取端命令接受 `--format text|json|toon`。預設為該命令最省 Token 的格式（多數為 `toon`；`find` 預設為 `text`；`cypher` 預設為 `json`）。
----
+## cli surface
-## CLI 命令概覽
+兩層 —— **agent commands** 在頂層（query / refactor / verify），**admin commands** 在 `ecp admin` 下（registry / hooks / 破壞性操作）。完整 flag 矩陣請跑 `ecp --help` 與 `ecp admin --help`。
-雙層結構 — 頂層為 **agent 命令** (query/refactor/verify)，以及 `ecp admin` 下的 **admin 命令** (registry/hooks/破壞性操作)。詳見 `ecp --help` 與 `ecp admin --help`。
-
-| 命令 | 用途 |
+| 指令 | 用途 |
|---|---|
-| `inspect ` | 單一符號 → metadata、裝飾器、簽名、呼叫者、被呼叫者、1-hop 影響 |
-| `find ` | 定位符號 — 精準 (預設) · `--mode fuzzy` 子字串 · `--mode bm25` 詞法排序 |
-| `impact --direction ` | 帶信心度過濾的爆炸半徑 traversal。`--since [` 用於變更集影響分析。 |
-| `rename --symbol --new-name ` | AST 感知的跨檔重命名 (14 種語言)。務必先執行 `--dry-run`。 |
-| `cypher ''` | openCypher 逃生艙；`m.content` 返回原始碼。 |
-| `summary` | Registry 總覽、框架覆蓋率、LLM 可行動的盲區目錄、圖譜新鮮度。（原 `coverage`；舊名稱保留為別名一個版本。）|
-| `routes []` | 列出 HTTP 路由；帶 `` 時顯示處理器 + 呼叫者。 |
-| `contracts` | 跨 repo 的 API 合約清單 (routes / queue / RPC)。 |
-| `diff` | 解析器 Delta — 邊界綁定層級降級 + 路由 / 合約變更。 |
-| `tool-map` | 透過分析導入綁定，列出對外部 HTTP / DB / Redis / queue client 的呼叫。 |
-| `shape-check` | HTTP 消費者訪問模式與路由響應形狀之間的偏移。 |
-| `peers` | 多會話協作 (status / diff / log / gc)。 |
-| `review` | 聚合式稽核：一次執行 impact + coverage + tool-map + shape-check + diff。 |
-
-Admin 命名空間 (`ecp admin ` — 隱藏於頂層說明)：
-
-| 命令 | 用途 |
+| `inspect ` | 單一符號 → metadata、decorator、signature、callers、callees、1-hop impact、enum variants |
+| `find ` | 符號定位 —— exact（預設）· `--mode fuzzy` 子字串 · `--mode bm25` 詞彙排序；bm25 把輸出分到 source / tests / reference / document / config 5 個桶 |
+| `find-schema-bindings ` | Schema field mirror 偵測（跨 service / 跨 model 的欄位對齊 + blind-spot 候選） |
+| `find-transaction-patterns [--class ]` | Saga compensate/undo/rollback 名稱對偵測（≥0.75 POSSIBLY_RELATED、<0.75 BLIND_SPOT） |
+| `impact --direction ` | 衝擊半徑遍歷 + confidence 過濾。`--baseline ][` 做變更集 impact；`--literal ` 找 PathLiteral split-brain。 |
+| `rename --symbol --new-name ` | 14 語言 AST 感知多檔重命名。永遠先 `--dry-run`。 |
+| `cypher ''` | openCypher 後門；`m.content` 拿原始碼 body。 |
+| `summary` | Registry 總覽、框架覆蓋、blind-spot 名單、graph 新鮮度。（原 `coverage`；舊名留作別名一個版本） |
+| `routes []` | 列出 HTTP route（declarative + imperative）；給 `` 就秀 handler + callers。 |
+| `contracts` | 跨 repo API contract 庫存（routes / queue / RPC）。 |
+| `diff` | Resolver delta —— edge 級別 binding tier-degradation + route / contract 變動。 |
+| `tool-map` | 對外部 HTTP / DB / Redis / queue client 的呼叫（per-file import-binding 分析）。 |
+| `shape-check` | HTTP consumer 存取模式 vs. Route response shape 的漂移。 |
+| `peers` | 多 session 對端協作：`status` / `diff` / `say` / `inbox` / `log` / `thread` / `watch` / `gc`。 |
+| `review` | LLM-workflow 稽核聚合器 —— impact + summary + tool-map + shape-check + diff，過濾到高信心訊號。 |
+
+]
+Admin namespace —— ecp admin <cmd>（registry / hooks / 破壞性）
+
+| 指令 | 用途 |
|---|---|
-| `index --repo ` | 建立 / 刷新圖譜；透過 xxh3_64 內容快取達成增量。`--force` 為全量。 |
-| `drop / prune / rename-branch` | 索引生命週期：刪除、清理過時分支目錄、重命名分支。 |
-| `install-hook` | 安裝 git reference-transaction hook (自動追蹤分支切換)。 |
-| `config` | `.ecp/config.toml` 互動式精靈。 |
-| `mcp serve` / `mcp tools` | 給 LLM host 用的 MCP server (stdio)。 |
+| `index --repo ` | 建 / 刷新 graph；xxh3_64 內容快取做增量。`--force` 全量重建。 |
+| `drop / prune / rename-branch` | Index 生命週期：刪除、清理過時 branch dir、改名 on-disk branch。 |
+| `install-hook` | 裝 git reference-transaction hook（自動追蹤 branch 切換）。 |
+| `config` | `.ecp/config.toml` 互動式 TOML 精靈。 |
+| `mcp serve` / `mcp tools` | MCP server（stdio）給 LLM host；`tools` 列出曝露的 tool 表面。 |
+| `claude install / codex install / gemini install` | 可腳本化的 host 整合（skills、hooks、MCP entry）。 |
+| `verify-resolver` | 解析器 dump 對 language oracle diff（ecp-dev QA 用）。 |
-不帶子命令執行 `ecp admin` 會開啟互動式 admin TUI，用於索引維護、host 整合、設定、群組與診斷。
+
----
+所有指令預設從 CWD 解析 `.ecp/graph.bin`，可用 `--graph ` 改寫。Agent 端的指令設計上 non-interactive —— 每個 flag 走 `--help`、每個輸出可解析。`ecp admin` 不帶 subcommand 開互動 admin TUI。
-## MCP 伺服器
+## MCP server
-`ecp` 內建 MCP 伺服器，將核心命令暴露為 MCP 工具。支援 MCP 的主機 (Claude Code, Cursor, Windsurf, Cline, Codex CLI, Gemini CLI) 可以註冊 `ecp` 並自主調用。
+`ecp` 內建 MCP server，把核心指令以 MCP tool 形式曝露。會說 MCP 的 host（Claude Code、Cursor、Windsurf、Cline、Codex CLI、Gemini CLI）都能註冊 `ecp` 然後自主呼叫。
```bash
-ecp admin mcp tools # 檢視暴露的工具表面
-ecp admin mcp serve # 啟動伺服器 (預設：spawn 模式，每次調用啟動新進程)
+ecp admin mcp tools # 預覽要曝露的 tools
+ecp admin mcp serve # 跑 server（預設 spawn mode）
```
-給人操作的漸進式路徑：
+Claude Code 手動 host 設定範例（`~/.config/claude-code/mcp-servers.json`）：
+
+```json
+{
+ "mcpServers": {
+ "ecp": { "command": "ecp", "args": ["admin", "mcp", "serve"] }
+ }
+}
+```
+
+真人漸進路徑：
```text
-ecp admin
-→ Agent Integrations
-→ MCP
-→
-→ install
+ecp admin → Agent Integrations → MCP → → install
```
-## Codex CLI native 整合
+AI agent 腳本路徑：
+
+```bash
+ecp admin claude install mcp-server
+ecp admin gemini install skills
+```
-Codex native 路徑與 MCP 分離。它會為 `openai/codex` fork 準備 patch，不會直接修改正在執行的 Codex 安裝：
+
+手動 mcp.json snippet —— Cursor / Windsurf / Cline（尚無 scripted installer）
-給人操作的漸進式路徑：
+這幾個 host 讀 `mcp.json`（或同類設定），但檔案位置依 IDE 各異。把下面這段 server entry 貼進對應設定即可，binary 只要在 `$PATH` 上：
+
+```json
+{
+ "mcpServers": {
+ "ecp": {
+ "command": "ecp",
+ "args": ["admin", "mcp", "serve"]
+ }
+ }
+}
+```
+
+各 host 設定檔位置：
+
+- **Cursor** → `~/.cursor/mcp.json`（global）或 `/.cursor/mcp.json`（per-project）
+- **Windsurf** → `~/.codeium/windsurf/mcp_config.json`
+- **Cline** → VS Code settings → `cline.mcpServers`（key 結構一樣）
+
+存檔後重啟 IDE，跑 `ecp admin mcp tools` 對照 host 那邊列出的工具集對得上即可。
+
+
+
+
+Codex CLI 原生整合（跟 MCP 不一樣 —— 對 openai/codex fork 出 patch）
+
+Codex 原生路徑不會改你正在跑的 Codex 安裝；它寫出一份 patch，你拿去套用在 `openai/codex` fork。
+
+漸進路徑：
```text
-ecp admin
-→ Agent Integrations
-→ Codex CLI
-→ install
-→ native-tools
+ecp admin → Agent Integrations → Codex CLI → install → native-tools
```
-內建 skills 使用相同的漸進式路徑：
+內建 skills（同一條路徑）：
```text
-ecp admin
-→ Agent Integrations
-→ Codex CLI
-→ install
-→ skills
-→ all | ecp | simplify
+ecp admin → Agent Integrations → Codex CLI → install → skills → all | ecp | simplify
```
-給 AI agent 與自動化流程使用的指令化路徑：
+Agent 腳本路徑：
```bash
ecp admin codex install native-tools
@@ -224,34 +283,27 @@ ecp admin codex install skills ecp
ecp admin codex install skills simplify
```
-內建 skills 用來教 agent 判斷 help 本身無法推導的使用場景：
+內建 skills 教 agent 怎麼選工作流，這是 command help 推不出來的：
-| Skill | 適用場景 |
+| Skill | 何時用 |
|---|---|
-| `ecp` | agent 需要判斷何時用圖譜感知的 symbol、impact、route、contract、rename 流程，而不是 grep / 讀檔。 |
-| `simplify` | agent 在 review changed code 時，應先看 ecp impact、盲區、egress、shape drift、resolver delta，再讀 raw diff。 |
+| `ecp` | Agent 要判斷 graph 感知的 symbol / impact / route / contract / rename 工作流是否優於 grep / 讀檔。 |
+| `simplify` | Agent 要 review 變更，應該從 `ecp impact`、blind-spot、egress、shape drift、resolver delta 出發，再讀原始 diff。 |
-`native-tools` 元件會寫出：
+`native-tools` 元件會寫：
```text
~/.config/ecp/host-integration/codex-cli.patch
```
-在 Codex CLI fork 內套用 patch，接著把產生的 module 接進 Codex 的 tool registry：
+在你的 Codex CLI fork 套用：
```bash
cd /path/to/openai-codex-fork
git apply ~/.config/ecp/host-integration/codex-cli.patch
```
-若要檢查已套用 native marker 的 fork，先設定 `ECP_CODEX_CLI_CHECKOUT`，再於 TUI 內查看狀態：
-
-```bash
-ECP_CODEX_CLI_CHECKOUT=/path/to/openai-codex-fork ecp admin
-# Agent Integrations → Codex CLI → status
-```
-
-等價的指令化檢查：
+驗證已有 native 標記的 fork —— 設 `ECP_CODEX_CLI_CHECKOUT` 後查狀態：
```bash
ECP_CODEX_CLI_CHECKOUT=/path/to/openai-codex-fork ecp admin codex status
@@ -259,43 +311,60 @@ ecp admin codex uninstall native-tools
ecp admin codex uninstall skills all
```
----
+
-## 系統架構
+## 架構
```
crates/
-├── ecp-core # 零拷貝圖譜 (rkyv + mmap)、增量快取、圖譜查詢
-├── ecp-analyzer # Tree-sitter 解析器、HTTP 路由偵測、框架信心度
-├── ecp-mcp # MCP 伺服器 (stdio) — 將核心命令暴露為工具
-└── ecp-cli # `ecp` 執行檔、Tantivy BM25 引擎、Token 最佳化輸出
+├── ecp-core 零拷貝 graph（rkyv + mmap）、增量快取、graph 查詢
+├── ecp-analyzer Tree-sitter parsers、HTTP route 偵測、framework 信心評分
+├── ecp-mcp MCP server（stdio）—— 把核心指令當 tool 曝露
+└── ecp-cli `ecp` binary、Tantivy BM25 引擎、token 優化的輸出
```
----
+Parse → resolve → serialize 過 MPSC channel 進單一 builder thread，組裝 graph 後寫出零拷貝 `.ecp/graph.bin`。讀路徑（`inspect`、`cypher`、`impact` …）直接 mmap 這個檔。xxh3_64 內容快取讓 22k 檔的 repo 增量重建維持亞秒級。
-## 語言覆蓋範圍
+## 語言覆蓋
-在結構層級解析 31 種語言。其中 14 種（原 GitNexus 集合）獲得完整的 9 維度覆蓋。其餘 17 種為結構層級解析。
+31 個語言做結構級解析（functions / classes / methods / imports / calls）。其中 14 個 —— 原 GitNexus 那組 —— 拿到全深度覆蓋，涵蓋 imports、named bindings、exports、heritage、types、constructors、config、frameworks、entry points、calls、rename。其餘 17 個是 structural-only（Bash、Crystal、Cairo、Dockerfile、Docker Compose、GitHub Actions、HCL、Lua、Markdown、Move、Nim、Solidity、SQL、Verilog、Vyper、YAML、Zig）。
-📊 **[完整語言能力矩陣](../language-matrix.md)** — 各語言實作狀態與設計考量的詳細說明。
+📊 [完整語言能力矩陣](../language-matrix.md) —— 各語言狀態與理由。
----
+## 調校
+
+| 環境變數 | 預設 | 效果 |
+|---|---|---|
+| `ECP_MAX_FILE_BYTES` | `16777216`（16 MiB） | Ingest 時略過超過此值的原始檔。把 worst-case worker RAM 鎖在 `num_threads × MAX`。 |
+| `ECP_CSPROJ_MAX_DEPTH` | `4` | 找 `*.csproj` 的目錄遞迴深度。.NET 深層 monorepo 可調高。 |
+
+## 授權
+
+採用 [PolyForm Noncommercial 1.0.0](../../LICENSE.md)。個人使用、研究、業餘專案、非商業組織明確允許。**本授權不授予商業使用權** —— 商業授權請聯絡上游 GitNexus 作者 [Abhigyan Patwari](https://github.com/abhigyanpatwari)。必要的歸屬聲明見 [NOTICES.md](../../LICENSES/NOTICES.md)。
-## 📄 授權與致謝
+
+站在這些巨人肩上（致謝）
-基於 [PolyForm Noncommercial 1.0.0](../../LICENSE) 授權。
+- [GitNexus](https://github.com/abhigyanpatwari/GitNexus) — 原始設計、CLI 介面、概念模型
+- [tree-sitter](https://tree-sitter.github.io/) — 增量 AST 解析
+- [rkyv](https://rkyv.org/) — 零拷貝序列化框架
+- [Tantivy](https://github.com/quickwit-oss/tantivy) — Rust BM25 全文搜尋引擎
+- [Rayon](https://github.com/rayon-rs/rayon) — 多核心並行 AST 解析的資料並行庫
+- [xxhash (xxh3_64)](https://xxhash.com/) — 內容雜湊驅動的增量索引
+- [DashMap](https://github.com/xacrimon/dashmap) — 並行雜湊表（graph 組裝用）
+- [memmap2](https://github.com/RazrFalcon/memmap2-rs) — 零拷貝 mmap，亞毫秒級 graph 讀取
+- [msgspec](https://github.com/jcrist/msgspec) — IPC 用高效能 JSON 序列化
-技術底層：
-- [GitNexus](https://github.com/abhigyanpatwari/GitNexus) — 原始設計、CLI 介面與概念模型
-- [tree-sitter](https://tree-sitter.github.io/) — 強大的增量 AST 解析
-- [rkyv](https://rkyv.org/) — 零拷貝序列化框架 (Zero-copy deserialization)
-- [Tantivy](https://github.com/quickwit-oss/tantivy) — 高效 Rust 全文搜尋引擎 (BM25)
-- [Rayon](https://github.com/rayon-rs/rayon) — 用於多核心並行 AST 解析的數據並行庫
-- [xxhash (xxh3_64)](https://xxhash.com/) — 極速非加密雜湊，用於增量索引的內容校驗
-- [DashMap](https://github.com/xacrimon/dashmap) — 高效能並行雜湊表，用於圖譜組裝
-- [memmap2](https://github.com/RazrFalcon/memmap2-rs) — 零拷貝記憶體映射，實現亞毫秒級圖譜讀取
-- [msgspec](https://github.com/jcrist/msgspec) — 高效能 JSON 序列化，用於進程間通訊 (IPC)
+AI agent 安裝引導（URL bootstrap、Claude Code skill、plugin install）位於 `docs/skills/ecp-onboard/`。並行不變式與如何重新驗證：`./scripts/audit/audit-concurrency.sh`。
+
+
## 發佈狀態
-目前已驗證的安裝路徑是 `cargo install --git ...`，也就是從原始碼建置 `ecp`。release installer 已包含 checksum 與 provenance verification 流程，但必須等 tag 與 release assets 發佈後，binary 下載路徑才能做端到端驗證。Agent 安裝引導文件位於 [docs/skills/ecp-onboard/ONBOARDING.md](../skills/ecp-onboard/ONBOARDING.md)；它用來引導使用者完成安裝、首次索引、可選群組、MCP wiring 與後續建議。輔助式配置與設定流程仍在完善中。
+目前已驗證的安裝路徑是 `cargo install --git ...`，從原始碼建置 `ecp`。Release installer 已包含 checksum 與 provenance verification 流程，但必須等 tag 與 release assets 發佈後，binary 下載路徑才能做端到端驗證。Agent 安裝引導文件在 [docs/skills/ecp-onboard/ONBOARDING.md](../skills/ecp-onboard/ONBOARDING.md) —— 引導使用者完成安裝、首次索引、可選 group、MCP wiring、後續建議。輔助式設定流程仍在完善中。
+
+---
+
+## Star History
+
+[](https://star-history.com/#coseto6125/egent-code-plexus&Date)
diff --git a/docs/skills/ecp-onboard/ONBOARDING.md b/docs/skills/ecp-onboard/ONBOARDING.md
index 11a6f89c1..b2d57f6a8 100644
--- a/docs/skills/ecp-onboard/ONBOARDING.md
+++ b/docs/skills/ecp-onboard/ONBOARDING.md
@@ -5,42 +5,43 @@ You are the ecp onboarding wizard. Your job is to walk a recipient from
"never used egent-code-plexus" to "ecp installed, indexed, grouped (if applicable),
MCP-wired, and with a tailored 'what to try next' list".
-## Start now (no permission required)
+## Start now
-When this SKILL loads, your VERY NEXT actions — **no preamble, no
-permission-seeking, no "shall I begin?", no summarizing the SKILL back
-to the user**:
+When this SKILL loads, your VERY NEXT actions — start the workflow immediately,
+no preamble, no permission-seeking, no summarizing the SKILL back to the user:
1. Check whether `~/.ecp/onboarding-summary.md` exists (Directive 6 — resume).
2. If not resuming: read `_shared/refs/env-detect.md` and run its **single
bundled probe script** as ONE Bash tool call. Stash the JSON result
- in `config_inventory.system_probe`. Do NOT call `command -v` / `test
- -d` one tool at a time — that's the old anti-pattern.
+ in `config_inventory.system_probe`. Bundle every check into the single
+ script — one tool call per probe is the old anti-pattern.
3. Derive the persona per `_shared/refs/persona-inference.md` rules.
4. Read `guides/01-install.md` and emit its 3-choice menu.
-The user invoked you to install / set up ecp. Start installing. Do NOT
-ask "which file should I fetch next?" — the jump table below tells you;
-follow it.
+The user invoked you to install / set up ecp. Start installing. The jump
+table below routes you between phases — follow it.
## Directives (non-negotiable)
1. **Recommend → user picks accept / change / skip.** Every choice point
- uses this format. Never auto-decide on the user's behalf.
-2. **Only use already-loaded prompts + system probes.** Do not fish for
- user files beyond what is already in your context. Probes are limited
- to those listed in `_shared/refs/env-detect.md`.
-3. **Never silently retry, never silently switch methods.** On failure,
- show stderr verbatim → consult the common-cause table → offer
- retry / change-method / skip.
-4. **Never block on the install download.** When Phase 01 starts a
- background download, advance immediately to Phase 02 to collect
- later phases' choices in parallel. Apply choices in a batch at the
- T6 gate, after the binary is verified.
-5. **Background = `ecp` CLI only.** Every applied action goes through
- the `ecp` command. Never write to user files outside of
- `~/.ecp/onboarding-summary.md` (and IDE MCP configs the user has
- explicitly approved in Phase 04).
+ uses this format. Before any apply step, restate the exact files /
+ paths the action will touch and wait for explicit confirmation —
+ the user owns every decision.
+2. **Only use already-loaded prompts + system probes** listed in
+ `_shared/refs/env-detect.md`. Stay inside that allowlist.
+3. **Surface every failure.** On failure, show stderr verbatim → consult
+ the common-cause table → offer retry / change-method / skip. Every
+ retry or method switch is user-driven.
+4. **Keep the install download in the background.** When Phase 01 starts
+ a download, advance immediately to Phase 02 to collect later phases'
+ choices in parallel. Apply choices in a batch at the T6 gate, after
+ the binary is verified.
+5. **Every applied action goes through the `ecp admin` CLI** —
+ `index / group / claude install / codex install / gemini install`
+ perform the writes for you. The only path the wizard itself writes
+ to is `~/.ecp/onboarding-summary.md`. For IDEs without a scriptable
+ installer (Cursor / Zed / VS Code), emit the config snippet for the
+ user to paste; never edit IDE config files directly.
6. **On new session start:** if `~/.ecp/onboarding-summary.md` exists,
read it first and offer resume / redo-phase / start-over.
@@ -60,10 +61,9 @@ that dimension is needed by a phase.
## Jump table
-Walk the phases in order. **Load each guide ONLY when entering that
-phase** — selective loading is the whole point of the layered
-structure. Do NOT pre-fetch later phases' guides. Touching
-`guides/0X` before `guides/0X-1` is finalized wastes tokens and time.
+Walk the phases in order. Load each guide when entering its phase —
+selective loading is the whole point of the layered structure, and
+pre-fetching later phases wastes tokens.
| Intent / state | Next guide |
|---|---|
@@ -77,34 +77,25 @@ structure. Do NOT pre-fetch later phases' guides. Touching
## Ordering rules
- **Phases 01–04 are choice-collection only.** Each guide records the
- user's decision into an in-memory `config_inventory`. Do not invoke
- `ecp` apply commands inside Phases 02/03/04.
+ user's decision into an in-memory `config_inventory`; run no `ecp`
+ apply commands inside Phases 02/03/04.
- **Phase 05 is the apply-and-summarize gate.** Wait for the Phase 01
background download to complete + verify `ecp --version`, then drain
`config_inventory` into a single batch of `ecp admin` calls in order:
- index → group → mcp. Verify each command succeeds before moving to
- the next.
-- **If Phase 01 install failed**, do not proceed to Phase 05's apply
- step. Re-enter Phase 01 with the failure context surfaced from the
- common-cause table.
+ index → group → per-agent ` install ` for each
+ approved scriptable IDE (claude / codex / gemini). For unscripted
+ IDEs, emit the paste snippets in the final summary. Verify each
+ command succeeds before moving to the next.
+- **If Phase 01 install failed**, re-enter Phase 01 with the failure
+ context surfaced from the common-cause table before attempting
+ Phase 05's apply step.
## CLI flag lookups
-When you need exact `ecp ` flag syntax, read
-`_shared/cli/manifest.json`, find the version closest to the user's
-local `ecp --version`, and open the corresponding
-`_shared/cli//.md` card. If the user's version is not
-in the manifest, fall back to running `ecp --help` live and use
-its output as ground truth — never invent flags.
-
-## Hard "don't" list
-
-- Do not silently retry a failed command.
-- Do not switch install methods without user consent.
-- Do not modify `~/.zshrc`, `~/.gitconfig`, or any user file not
- explicitly listed under Phase 04 (IDE MCP configs).
-- Do not assume future ecp versions have a flag — always verify against
- the CLI reference cards or live `--help`.
+When you need exact `ecp ` flag syntax, read the corresponding
+`_shared/cli/.md` reference card. If the reference is missing or
+outdated, fall back to running `ecp --help` live and treat its
+output as ground truth.
@@ -389,35 +380,66 @@ Wait for user choice.
## Step 4: Record choice
+Tag each chosen IDE as `scripted` (driven by `ecp admin
+install`) or `paste-snippet` (no scripted installer; user pastes the
+snippet). Phase 05 runs the scripted ones and prints snippets for the
+rest.
+
```yaml
mcp_targets:
- ide: claude-code
- config_path: ~/.claude/.mcp.json # or the per-project equivalent
+ mode: scripted
+ command: ecp admin claude install mcp-server
+ status: queued
+ - ide: codex
+ mode: scripted
+ command: ecp admin codex install skills
+ status: queued
+ - ide: gemini
+ mode: scripted
+ command: ecp admin gemini install skills
status: queued
- ide: cursor
- config_path: ~/.cursor/mcp.json
+ mode: paste-snippet
+ snippet_target: ~/.cursor/mcp.json
+ status: queued
+ - ide: zed
+ mode: paste-snippet
+ snippet_target: ~/.config/zed/settings.json
status: queued
# ... one entry per chosen IDE
```
-## Step 5: Confirm explicit write consent
+Resolve the exact `command` via `ecp admin install --help` at
+apply time — components evolve between versions.
+
+## Step 5: Confirm before apply
-Per Directive 5 in SKILL.md, the wizard MUST NOT write to user files
-outside `~/.ecp/onboarding-summary.md` without consent. Show the user
-the exact paths the wizard will write to in Phase 05, and ask:
+Per Directive 5 in SKILL.md, the wizard never edits IDE config files
+directly. Restate the Phase 05 plan and wait for confirmation:
```
-I'll write these files in Phase 05:
- - ~/.claude/.mcp.json (Claude Code)
- - ~/.cursor/mcp.json (Cursor)
+Phase 05 will run:
+ - ecp admin claude install mcp-server (Claude Code)
+ - ecp admin codex install skills (Codex)
+ - ecp admin gemini install skills (Gemini)
-Reply: yes / no / show-content
+Then print paste snippets for:
+ - ~/.cursor/mcp.json (Cursor)
+ - ~/.config/zed/settings.json (Zed)
+
+The only file the wizard writes itself is
+~/.ecp/onboarding-summary.md.
+
+Reply: yes / no / show-snippet
```
-If `show-content`, display the JSON the wizard would write (template
+If `show-snippet`, display the snippet for the requested IDE (template
below), then re-ask.
-### MCP config template
+### Paste snippet for unscripted IDEs
+
+Standard MCP-servers schema (Cursor, most generic clients):
```json
{
@@ -430,9 +452,10 @@ below), then re-ask.
}
```
-For IDEs that use a different schema (e.g., Continue.dev uses
-`~/.continue/config.json` with a `models` + `mcpServers` mix), look up
-the exact format in the IDE's docs at apply time — do not guess.
+For IDEs that use a different schema (e.g., Continue.dev's
+`~/.continue/config.json` mixes `models` + `mcpServers`, Zed has its
+own `context_servers` block), look up the exact format in the IDE's
+docs at apply time rather than guessing.
## Step 6: Advance to Phase 05
@@ -474,8 +497,9 @@ For each repo in `config_inventory.first_index.repos`:
ecp admin index --repo
```
-Use `_shared/cli//admin-index.md` for exact flag syntax. If
-the version is missing, fall back to `ecp admin index --help`.
+Use `_shared/cli/admin-index.md` for exact flag syntax. If the
+reference card is missing or outdated, fall back to `ecp admin index
+--help` and treat its output as ground truth.
On success, mark `status: done` in the inventory. On failure, follow
the common-cause table → retry / change-method / skip.
@@ -491,31 +515,48 @@ ecp admin group add --repo
(See `_shared/cli/admin-group.md` for the exact subcommand
shape — `add` vs `create` etc.)
-## Step 4: Write MCP configs
+## Step 4: Apply IDE integrations
For each target in `config_inventory.mcp_targets` (user already
consented in Phase 04 Step 5):
-- **Idempotency:** if the config file already exists, **merge** the
- `ecp` entry into the existing `mcpServers` object rather than
- overwriting the file. Use `jq` for JSON files.
-- **Backup:** before any write, copy the existing file to
- `.bak.`.
-
-```bash
-# Example: Claude Code
-target=~/.claude/.mcp.json
-if [[ -f "$target" ]]; then
- cp "$target" "$target.bak.$(date +%s)"
- jq '.mcpServers.ecp = {"command":"ecp","args":["admin","mcp","serve"]}' \
- "$target" > "$target.tmp" && mv "$target.tmp" "$target"
-else
- mkdir -p "$(dirname "$target")"
- cat > "$target" <<'JSON'
-{ "mcpServers": { "ecp": { "command": "ecp", "args": ["admin", "mcp", "serve"] } } }
-JSON
-fi
-```
+- **Scripted IDEs (`mode: scripted`):** run the recorded `command`.
+ `ecp admin install` handles idempotency, backup, and
+ config-merging for you — the wizard does not touch the IDE config
+ file directly.
+
+ ```bash
+ # claude / codex / gemini
+ $target.command
+ # e.g., ecp admin claude install mcp-server
+ ```
+
+ On success, mark `status: done` in the inventory. On failure,
+ surface stderr → consult the common-cause table → offer
+ retry / skip.
+
+- **Paste-snippet IDEs (`mode: paste-snippet`):** emit the snippet to
+ the user with its target path; the user pastes manually. Standard
+ `mcpServers` schema (Cursor, generic clients):
+
+ ```text
+ Paste into ~/.cursor/mcp.json (merge into the existing "mcpServers"
+ object if the file is non-empty):
+
+ {
+ "mcpServers": {
+ "ecp": {
+ "command": "ecp",
+ "args": ["admin", "mcp", "serve"]
+ }
+ }
+ }
+ ```
+
+ Mark `status: snippet-emitted` in the inventory once the snippet has
+ been shown. IDEs with a different schema (Zed `context_servers`,
+ Continue.dev mixed config) — look up the exact shape in the IDE's
+ docs at apply time rather than guessing.
## Step 5: Persist summary
@@ -547,8 +588,9 @@ generated_at: {ISO 8601 timestamp}
- [ ] skipped — single-repo workflow
## Phase 04 mcp
-- [x] wrote ~/.claude/.mcp.json (Claude Code)
-- [x] wrote ~/.cursor/mcp.json (Cursor)
+- [x] ran `ecp admin claude install mcp-server`
+- [x] ran `ecp admin gemini install skills`
+- [x] emitted paste snippet for ~/.cursor/mcp.json (Cursor)
## Phase 05 summary
- [x] this file
@@ -594,5 +636,3 @@ Last session got to Phase {N}. What would you like to do?
- Redo a specific phase (which?)
- Start over (this will overwrite the summary)
```
-rwrite the summary)
-```
diff --git a/docs/skills/ecp-onboard/SKILL.md b/docs/skills/ecp-onboard/SKILL.md
index 26aeffce2..877ee87a5 100644
--- a/docs/skills/ecp-onboard/SKILL.md
+++ b/docs/skills/ecp-onboard/SKILL.md
@@ -13,42 +13,43 @@ You are the ecp onboarding wizard. Your job is to walk a recipient from
"never used egent-code-plexus" to "ecp installed, indexed, grouped (if applicable),
MCP-wired, and with a tailored 'what to try next' list".
-## Start now (no permission required)
+## Start now
-When this SKILL loads, your VERY NEXT actions — **no preamble, no
-permission-seeking, no "shall I begin?", no summarizing the SKILL back
-to the user**:
+When this SKILL loads, your VERY NEXT actions — start the workflow immediately,
+no preamble, no permission-seeking, no summarizing the SKILL back to the user:
1. Check whether `~/.ecp/onboarding-summary.md` exists (Directive 6 — resume).
2. If not resuming: read `_shared/refs/env-detect.md` and run its **single
bundled probe script** as ONE Bash tool call. Stash the JSON result
- in `config_inventory.system_probe`. Do NOT call `command -v` / `test
- -d` one tool at a time — that's the old anti-pattern.
+ in `config_inventory.system_probe`. Bundle every check into the single
+ script — one tool call per probe is the old anti-pattern.
3. Derive the persona per `_shared/refs/persona-inference.md` rules.
4. Read `guides/01-install.md` and emit its 3-choice menu.
-The user invoked you to install / set up ecp. Start installing. Do NOT
-ask "which file should I fetch next?" — the jump table below tells you;
-follow it.
+The user invoked you to install / set up ecp. Start installing. The jump
+table below routes you between phases — follow it.
## Directives (non-negotiable)
1. **Recommend → user picks accept / change / skip.** Every choice point
- uses this format. Never auto-decide on the user's behalf.
-2. **Only use already-loaded prompts + system probes.** Do not fish for
- user files beyond what is already in your context. Probes are limited
- to those listed in `_shared/refs/env-detect.md`.
-3. **Never silently retry, never silently switch methods.** On failure,
- show stderr verbatim → consult the common-cause table → offer
- retry / change-method / skip.
-4. **Never block on the install download.** When Phase 01 starts a
- background download, advance immediately to Phase 02 to collect
- later phases' choices in parallel. Apply choices in a batch at the
- T6 gate, after the binary is verified.
-5. **Background = `ecp` CLI only.** Every applied action goes through
- the `ecp` command. Never write to user files outside of
- `~/.ecp/onboarding-summary.md` (and IDE MCP configs the user has
- explicitly approved in Phase 04).
+ uses this format. Before any apply step, restate the exact files /
+ paths the action will touch and wait for explicit confirmation —
+ the user owns every decision.
+2. **Only use already-loaded prompts + system probes** listed in
+ `_shared/refs/env-detect.md`. Stay inside that allowlist.
+3. **Surface every failure.** On failure, show stderr verbatim → consult
+ the common-cause table → offer retry / change-method / skip. Every
+ retry or method switch is user-driven.
+4. **Keep the install download in the background.** When Phase 01 starts
+ a download, advance immediately to Phase 02 to collect later phases'
+ choices in parallel. Apply choices in a batch at the T6 gate, after
+ the binary is verified.
+5. **Every applied action goes through the `ecp admin` CLI** —
+ `index / group / claude install / codex install / gemini install`
+ perform the writes for you. The only path the wizard itself writes
+ to is `~/.ecp/onboarding-summary.md`. For IDEs without a scriptable
+ installer (Cursor / Zed / VS Code), emit the config snippet for the
+ user to paste; never edit IDE config files directly.
6. **On new session start:** if `~/.ecp/onboarding-summary.md` exists,
read it first and offer resume / redo-phase / start-over.
@@ -68,10 +69,9 @@ that dimension is needed by a phase.
## Jump table
-Walk the phases in order. **Load each guide ONLY when entering that
-phase** — selective loading is the whole point of the layered
-structure. Do NOT pre-fetch later phases' guides. Touching
-`guides/0X` before `guides/0X-1` is finalized wastes tokens and time.
+Walk the phases in order. Load each guide when entering its phase —
+selective loading is the whole point of the layered structure, and
+pre-fetching later phases wastes tokens.
| Intent / state | Next guide |
|---|---|
@@ -85,29 +85,22 @@ structure. Do NOT pre-fetch later phases' guides. Touching
## Ordering rules
- **Phases 01–04 are choice-collection only.** Each guide records the
- user's decision into an in-memory `config_inventory`. Do not invoke
- `ecp` apply commands inside Phases 02/03/04.
+ user's decision into an in-memory `config_inventory`; run no `ecp`
+ apply commands inside Phases 02/03/04.
- **Phase 05 is the apply-and-summarize gate.** Wait for the Phase 01
background download to complete + verify `ecp --version`, then drain
`config_inventory` into a single batch of `ecp admin` calls in order:
- index → group → mcp. Verify each command succeeds before moving to
- the next.
-- **If Phase 01 install failed**, do not proceed to Phase 05's apply
- step. Re-enter Phase 01 with the failure context surfaced from the
- common-cause table.
+ index → group → per-agent ` install ` for each
+ approved scriptable IDE (claude / codex / gemini). For unscripted
+ IDEs, emit the paste snippets in the final summary. Verify each
+ command succeeds before moving to the next.
+- **If Phase 01 install failed**, re-enter Phase 01 with the failure
+ context surfaced from the common-cause table before attempting
+ Phase 05's apply step.
## CLI flag lookups
When you need exact `ecp ` flag syntax, read the corresponding
`_shared/cli/.md` reference card. If the reference is missing or
-outdated, fall back to running `ecp --help` live and use its output
-as ground truth — never invent flags.
-
-## Hard "don't" list
-
-- Do not silently retry a failed command.
-- Do not switch install methods without user consent.
-- Do not modify `~/.zshrc`, `~/.gitconfig`, or any user file not
- explicitly listed under Phase 04 (IDE MCP configs).
-- Do not assume future ecp versions have a flag — always verify against
- the CLI reference cards or live `--help`.
+outdated, fall back to running `ecp --help` live and treat its
+output as ground truth.
diff --git a/docs/skills/ecp-onboard/guides/04-mcp.md b/docs/skills/ecp-onboard/guides/04-mcp.md
index 9b8988028..fdc275e42 100644
--- a/docs/skills/ecp-onboard/guides/04-mcp.md
+++ b/docs/skills/ecp-onboard/guides/04-mcp.md
@@ -54,35 +54,66 @@ Wait for user choice.
## Step 4: Record choice
+Tag each chosen IDE as `scripted` (driven by `ecp admin
+install`) or `paste-snippet` (no scripted installer; user pastes the
+snippet). Phase 05 runs the scripted ones and prints snippets for the
+rest.
+
```yaml
mcp_targets:
- ide: claude-code
- config_path: ~/.claude/.mcp.json # or the per-project equivalent
+ mode: scripted
+ command: ecp admin claude install mcp-server
+ status: queued
+ - ide: codex
+ mode: scripted
+ command: ecp admin codex install skills
+ status: queued
+ - ide: gemini
+ mode: scripted
+ command: ecp admin gemini install skills
status: queued
- ide: cursor
- config_path: ~/.cursor/mcp.json
+ mode: paste-snippet
+ snippet_target: ~/.cursor/mcp.json
+ status: queued
+ - ide: zed
+ mode: paste-snippet
+ snippet_target: ~/.config/zed/settings.json
status: queued
# ... one entry per chosen IDE
```
-## Step 5: Confirm explicit write consent
+Resolve the exact `command` via `ecp admin install --help` at
+apply time — components evolve between versions.
-Per Directive 5 in SKILL.md, the wizard MUST NOT write to user files
-outside `~/.ecp/onboarding-summary.md` without consent. Show the user
-the exact paths the wizard will write to in Phase 05, and ask:
+## Step 5: Confirm before apply
+
+Per Directive 5 in SKILL.md, the wizard never edits IDE config files
+directly. Restate the Phase 05 plan and wait for confirmation:
```
-I'll write these files in Phase 05:
- - ~/.claude/.mcp.json (Claude Code)
- - ~/.cursor/mcp.json (Cursor)
+Phase 05 will run:
+ - ecp admin claude install mcp-server (Claude Code)
+ - ecp admin codex install skills (Codex)
+ - ecp admin gemini install skills (Gemini)
+
+Then print paste snippets for:
+ - ~/.cursor/mcp.json (Cursor)
+ - ~/.config/zed/settings.json (Zed)
-Reply: yes / no / show-content
+The only file the wizard writes itself is
+~/.ecp/onboarding-summary.md.
+
+Reply: yes / no / show-snippet
```
-If `show-content`, display the JSON the wizard would write (template
+If `show-snippet`, display the snippet for the requested IDE (template
below), then re-ask.
-### MCP config template
+### Paste snippet for unscripted IDEs
+
+Standard MCP-servers schema (Cursor, most generic clients):
```json
{
@@ -95,9 +126,10 @@ below), then re-ask.
}
```
-For IDEs that use a different schema (e.g., Continue.dev uses
-`~/.continue/config.json` with a `models` + `mcpServers` mix), look up
-the exact format in the IDE's docs at apply time — do not guess.
+For IDEs that use a different schema (e.g., Continue.dev's
+`~/.continue/config.json` mixes `models` + `mcpServers`, Zed has its
+own `context_servers` block), look up the exact format in the IDE's
+docs at apply time rather than guessing.
## Step 6: Advance to Phase 05
diff --git a/docs/skills/ecp-onboard/guides/05-summary.md b/docs/skills/ecp-onboard/guides/05-summary.md
index ed181ca9b..89a8e6770 100644
--- a/docs/skills/ecp-onboard/guides/05-summary.md
+++ b/docs/skills/ecp-onboard/guides/05-summary.md
@@ -31,8 +31,9 @@ For each repo in `config_inventory.first_index.repos`:
ecp admin index --repo
```
-Use `_shared/cli//admin-index.md` for exact flag syntax. If
-the version is missing, fall back to `ecp admin index --help`.
+Use `_shared/cli/admin-index.md` for exact flag syntax. If the
+reference card is missing or outdated, fall back to `ecp admin index
+--help` and treat its output as ground truth.
On success, mark `status: done` in the inventory. On failure, follow
the common-cause table → retry / change-method / skip.
@@ -48,31 +49,48 @@ ecp admin group add --repo
(See `_shared/cli/admin-group.md` for the exact subcommand
shape — `add` vs `create` etc.)
-## Step 4: Write MCP configs
+## Step 4: Apply IDE integrations
For each target in `config_inventory.mcp_targets` (user already
consented in Phase 04 Step 5):
-- **Idempotency:** if the config file already exists, **merge** the
- `ecp` entry into the existing `mcpServers` object rather than
- overwriting the file. Use `jq` for JSON files.
-- **Backup:** before any write, copy the existing file to
- `.bak.`.
-
-```bash
-# Example: Claude Code
-target=~/.claude/.mcp.json
-if [[ -f "$target" ]]; then
- cp "$target" "$target.bak.$(date +%s)"
- jq '.mcpServers.ecp = {"command":"ecp","args":["admin","mcp","serve"]}' \
- "$target" > "$target.tmp" && mv "$target.tmp" "$target"
-else
- mkdir -p "$(dirname "$target")"
- cat > "$target" <<'JSON'
-{ "mcpServers": { "ecp": { "command": "ecp", "args": ["admin", "mcp", "serve"] } } }
-JSON
-fi
-```
+- **Scripted IDEs (`mode: scripted`):** run the recorded `command`.
+ `ecp admin install` handles idempotency, backup, and
+ config-merging for you — the wizard does not touch the IDE config
+ file directly.
+
+ ```bash
+ # claude / codex / gemini
+ $target.command
+ # e.g., ecp admin claude install mcp-server
+ ```
+
+ On success, mark `status: done` in the inventory. On failure,
+ surface stderr → consult the common-cause table → offer
+ retry / skip.
+
+- **Paste-snippet IDEs (`mode: paste-snippet`):** emit the snippet to
+ the user with its target path; the user pastes manually. Standard
+ `mcpServers` schema (Cursor, generic clients):
+
+ ```text
+ Paste into ~/.cursor/mcp.json (merge into the existing "mcpServers"
+ object if the file is non-empty):
+
+ {
+ "mcpServers": {
+ "ecp": {
+ "command": "ecp",
+ "args": ["admin", "mcp", "serve"]
+ }
+ }
+ }
+ ```
+
+ Mark `status: snippet-emitted` in the inventory once the snippet has
+ been shown. IDEs with a different schema (Zed `context_servers`,
+ Continue.dev mixed config) — look up the exact shape in the IDE's
+ docs at apply time rather than guessing.
## Step 5: Persist summary
@@ -104,8 +122,9 @@ generated_at: {ISO 8601 timestamp}
- [ ] skipped — single-repo workflow
## Phase 04 mcp
-- [x] wrote ~/.claude/.mcp.json (Claude Code)
-- [x] wrote ~/.cursor/mcp.json (Cursor)
+- [x] ran `ecp admin claude install mcp-server`
+- [x] ran `ecp admin gemini install skills`
+- [x] emitted paste snippet for ~/.cursor/mcp.json (Cursor)
## Phase 05 summary
- [x] this file
@@ -151,5 +170,3 @@ Last session got to Phase {N}. What would you like to do?
- Redo a specific phase (which?)
- Start over (this will overwrite the summary)
```
-rwrite the summary)
-```
diff --git a/skill_sample/claude/SKILL.md b/skill_sample/claude/SKILL.md
index e78295ba8..4133aced6 100644
--- a/skill_sample/claude/SKILL.md
+++ b/skill_sample/claude/SKILL.md
@@ -3,10 +3,25 @@ name: ecp
description: Use for symbol-level code analysis, blast-radius impact, cross-repo API contracts, AST-aware rename, route map. Defer to grep for string literals, config keys, vendored / generated code, and fs layout.
---
-# ecp — egent-code-plexus-rs CLI
+# ecp — egent-code-plexus CLI
`ecp [--repo ]`. `--repo` is **not** auto-injected; most commands fall back to cwd, a few require it explicitly. Run `ecp --help` if unsure.
+## Decisions (when X, Y is better)
+
+| When | Preferred path |
+|---|---|
+| Looking up a symbol by name | `ecp find` / `ecp inspect` is better than grep + Read (single call → kind + location + signature + body) |
+| Want callers + callees + body in one shot | `ecp inspect --name X` is better than chaining `find` → `cypher` |
+| `find` / `inspect` returns empty but grep matches | Re-running is better than escalating (auto-ensure walks tree). Still empty → `ecp admin index --force --repo .`; else symbol genuinely absent |
+| Impact shows d=1 caller outside the diff | Stop + surface to user is better than silent edit (breakage risk) |
+| Impact returns >15 symbols OR auth / payments / migrations path | Surface risk + suggest test plan is better than blind apply |
+| Refactor crosses repo boundary | `ecp contracts --repo @all --unmatched-only` is better than per-repo scan (orphan consumers visible in one view) |
+| Reference is a string / config key / dynamic dispatch | grep is better than ecp (AST doesn't see strings) |
+| Just edited a file, re-querying same turn | Waiting ~500ms (watcher debounce) or `ecp admin index --force` is better than reading possibly-stale graph |
+| Renaming a symbol called via string assembly | Two-pass — `ecp rename --dry-run` for static + `ecp find "old"` for string sweep — is better than single rename |
+| Renaming touches `.md / .rst / .txt` | `ecp rename --markdown` is better than default (code-only) |
+
## Tool selection
| Goal | Command |
@@ -14,16 +29,19 @@ description: Use for symbol-level code analysis, blast-radius impact, cross-repo
| ONE symbol → signature + body + 1-hop edges + callers + 1-hop impact | `ecp inspect --name X --repo .` |
| ONE symbol → blast radius | `ecp impact X --direction upstream --repo .` (positional; `--target X` alias works too. `--direction` accepts `up`/`down`/`both` or `upstream`/`downstream`. Filters: `--kind --file_path --relation_types --depth --min-confidence --include-tests`) |
| PR blast radius — symbol view (who breaks) | `ecp impact --baseline origin/main --repo .` |
-| Find symbol by name / concept | `ecp find "term" --repo .` (auto-picks bm25 / hybrid / vector; force via `--mode`) |
+| Find symbol by name / fragment / concept | `ecp find "term" --repo .` (default `--mode exact`; `--mode fuzzy` for substring, `--mode bm25` for ranked top-K bucketed across source / tests / docs / refs / config) |
| Schema mirrors (cross-service / multi-model field alignment) | `ecp find-schema-bindings User.email --repo .` or `ecp find-schema-bindings email --repo .` (bare = all classes). Toon format; `--format json` for parsing. |
-| Saga compensate/undo/rollback pairs (transaction pattern audit) | `ecp find-transaction-patterns --repo .` or `ecp find-transaction-patterns --class OrderService --repo .` (bare = all classes). JSON format; `POSSIBLY_RELATED` (≥0.75 confidence) or `BLIND_SPOT` (<0.75). Outbox half deferred (depends on T5-33). |
+| Saga compensate/undo/rollback pairs (transaction pattern audit) | `ecp find-transaction-patterns --repo .` or `ecp find-transaction-patterns --class OrderService --repo .` (bare = all classes). JSON format; `POSSIBLY_RELATED` (≥0.75 confidence) or `BLIND_SPOT` (<0.75). |
+| Path-literal split-brain (same filename, different writers/readers) | `ecp impact --literal session_meta.json --repo .` — find all `PathLiteral` nodes matching value, group by sink kind (read / write / config) |
| Arbitrary graph query / source body via Cypher | `ecp cypher "MATCH (m:Method) WHERE m.name='X' RETURN m,m" --repo .` (positional; `--query "..."` alias works. Single-repo only. Minimal grammar — see Cypher subset below) |
-| AST-aware multi-file rename | `ecp rename --symbol old --new-name new --dry-run --repo .` then drop `--dry-run`. **Never find-replace.** |
+| AST-aware multi-file rename | `ecp rename --symbol old --new-name new --dry-run --repo .` — start with `--dry-run`, drop the flag once the preview is correct. |
| HTTP route → handler → upstream callers | `ecp routes --repo .` (no path = list all) |
| Cross-repo API contracts (routes / queue / RPC) | `ecp contracts --repo @all` (needs ≥2 repos in group) |
| HTTP consumer → Route shape drift detection | `ecp shape-check --route ? --repo .` (no `--route` = scan all routes; drift = consumer reads key not in Route's response/error keys) |
| Binding tier / route / contract delta — edge view | `ecp diff --section --baseline [ --repo .` (`--baseline` required; accepts branch / tag / SHA / `HEAD~N` / `PR/`. Multi-select via `,`. Formats: text / json / toon. Use `--verbose` for full lists.) |
+| LLM-workflow audit (impact + summary blind-spot + tool-map egress + shape-check + resolver-diff in one shot) | `ecp review --repo .` (working tree) / `--since ][` / `--files a.rs,b.rs` |
| Registry health / freshness / frameworks / blind spots | `ecp summary` (registry-wide) or `ecp summary --repo @all --detailed`. (Was `ecp coverage`; the old verb is kept as an alias for one release.) |
+| External-client (HTTP / DB / Redis / queue) usage map | `ecp tool-map --repo .` |
| String literals / config keys / vendored / generated / fs layout | grep / glob |
| MCP host integration / install hooks / config TUI / **MCP server (`mcp serve\|tools`)** / **resolver vs LSP oracle benchmark (`verify-resolver`)** | `ecp admin` (hidden namespace) |
@@ -31,7 +49,7 @@ description: Use for symbol-level code analysis, blast-radius impact, cross-repo
Two access paths; pick one per command:
-- **`--repo `** → registry lookup → reads `~/.ecp/egent-code-plexus-//graph.bin`. Branch slug = current HEAD with `/` → `__`. **Preferred** day-to-day.
+- **`--repo `** → registry lookup → reads `~/.ecp/__//graph.bin`. Branch slug = current HEAD with `/` → `__`. **Preferred** day-to-day.
- **`--graph `** → bypass registry. Use when registry slug mismatch or testing a snapshot.
- **`--repo @ / @all / csv` (`name1,name2`)** → multi-repo. Works for `find / impact / contracts / coverage`. `cypher / inspect` are single-repo (will error on multi).
@@ -48,9 +66,9 @@ for human-driven workflows (full re-index, `--embeddings`, `--force`).
### "Not found" but `grep` shows the symbol
Almost always stale — auto-ensure should have rebuilt. If it didn't, the
-symbol genuinely isn't in the graph: check for typos, try `ecp find`
-for fuzzy matches, or re-run the same command (auto-ensure walks the
-tree on each call and re-indexes if mtime moved).
+symbol genuinely isn't in the graph: check for typos, try `ecp find
+--mode fuzzy` for substring matches, or re-run the same command
+(auto-ensure walks the tree on each call and re-indexes if mtime moved).
## Output formats
@@ -58,9 +76,9 @@ tree on each call and re-indexes if mtime moved).
| Command | Default | Other |
|---|---|---|
-| `inspect / coverage / contracts / routes` | toon | json |
+| `inspect / coverage / contracts / routes / review` | toon | json |
| `cypher` | json | toon, text |
-| `find / rename / impact` | text | json, toon |
+| `find / rename / impact / diff / shape-check / tool-map` | text | json, toon |
Rule of thumb: **toon** for agent → agent piping (compact key:value), **json** for parsing in scripts, **text** for human inspection.
@@ -72,22 +90,21 @@ MATCH (a:Kind)-[r:Rel]->(b:Kind) [WHERE ...] RETURN ...
Supports the openCypher read subset commonly used for graph queries: boolean WHERE (`AND / OR / NOT`), comparisons (`= != < <= > >=`), string ops (`STARTS WITH / ENDS WITH / CONTAINS / =~ / IN [...]`), aggregations (`COUNT(*)`, etc.), `DISTINCT`, `ORDER BY / SKIP / LIMIT`, `WITH`, `UNION`, variable-length paths (`[:Rel*1..2]`), and reverse arrows (`<-[r:Rel]-`). Convention: **keep queries minimal** — for richer needs use `ecp find` / `ecp inspect` / post-process JSON.
-**NodeKind** (case-sensitive labels): `Function / Method / Class / Property / Constructor / Interface / Const / Variable / Import / Route / Process / Document / Section / EntryPoint / File`.
+**NodeKind** (case-sensitive labels). Symbol-level: `Function / Method / Class / Interface / Constructor / Property / Variable / Const / Struct / Enum / EnumVariant / Typedef / Trait / Impl / Annotation / Macro`. Container / scope: `File / Namespace / Module / Process`. Routing / runtime: `Route / EntryPoint / TransactionScope`. Data / IO: `SchemaField / EventTopic / PathLiteral`. Imports / docs: `Import / Document / Section`.
-**RelType** (CamelCase only — `HAS_METHOD` fails with `unknown RelType` semantic error, use `HasMethod`): `Calls / Extends / Imports / Implements / HasMethod / HasProperty / Accesses / HandlesRoute / StepInProcess / References / Defines / Fetches`.
+**RelType** (CamelCase only — `HAS_METHOD` fails with `unknown RelType` semantic error, use `HasMethod`). Structural: `Defines / HasMethod / HasProperty / Extends / Implements / Overrides`. Code flow: `Calls / Accesses / References / Imports`. Routing / IO: `HandlesRoute / Fetches / StepInProcess / UsesPathLiteral`. Schema / events / tx: `MirrorsField / Publishes / Subscribes / EventTopicMirror / OpensTxScope`. Metadata: `Decorates`.
**Node properties** (in `WHERE` / `RETURN`): `a.name / a.uid / a.kind / a.filePath / a.content`. **Edge properties**: `r.rel_type / r.confidence / r.reason`.
-**`HasMethod` target kind is parser-determined**: Python `def` and Rust associated fn surface as `Function`, true methods as `Method`. Use `MATCH (c:Class)-[:HasMethod]->(m) RETURN m` — **don't add `:Method` filter** or you'll miss those languages. `ecp inspect .contained_methods` keeps each entry's `kind` field if callers need to distinguish.
+**`HasMethod` target kind is parser-determined**: Python `def` and Rust associated fn surface as `Function`, true methods as `Method`. Use `MATCH (c:Class)-[:HasMethod]->(m) RETURN m` — leave the target label unfiltered so all languages match (or `RETURN m, m.kind` to distinguish at the caller side).
## Common pitfalls
1. **`--repo` is required for cross-repo modes**. `@group / @all / csv` only work when explicit.
2. **`cypher --repo @group` errors** — single-repo only.
-3. **Default `--graph .ecp-rs/graph.bin`** is a cwd-relative legacy path. If you don't have a checked-in graph file, pass `--repo` (preferred) or absolute `--graph`.
+3. **Default `--graph .ecp/graph.bin`** is a cwd-relative path. If you don't have a checked-in graph file, pass `--repo` (preferred) or absolute `--graph`.
4. **Auto-ensure on every agent command** — first query after a source change pays a brief re-index cost. The stderr `✓ Index refreshed` line is informational, not an error.
-5. **`scan --strict`** flags identifiers that match language keywords / builtins. Off by default; turn on for high-noise files.
-6. **`rename --markdown`** is OFF by default — code-only rename. Add the flag to sweep `.md / .rst / .txt`.
+5. **`rename --markdown`** is OFF by default — code-only rename. Add the flag to sweep `.md / .rst / .txt`.
## PR-touching workflow
@@ -95,21 +112,24 @@ Supports the openCypher read subset commonly used for graph queries: boolean WHE
# Before editing a function: see blast radius
ecp impact Foo --direction upstream --repo .
-# After staging a diff: see what changed + downstream/upstream callers
+# After staging a diff: who breaks across the changed symbols?
ecp impact --baseline origin/main --repo .
-# After edits: catch binding tier / route / contract delta
+# Aggregated LLM-workflow audit (impact + blind spots + egress + shape drift + resolver delta)
+ecp review --since origin/main --repo .
+
+# Targeted edge-view delta (binding tier / route / contract only)
ecp diff --section bindings --baseline origin/main --repo .
# Touched HTTP routing / handlers?
ecp routes /api/foo --repo .
```
-HIGH / CRITICAL risk_level in impact output → **stop + confirm with user** before pushing. Cross-repo contract changes → check `ecp contracts --repo @all --unmatched-only` for orphaned consumers.
+HIGH / CRITICAL risk_level in impact / review output → **stop + confirm with user** before pushing. Cross-repo contract changes → check `ecp contracts --repo @all --unmatched-only` for orphaned consumers.
## Group / multi-repo
- Membership: `ecp admin group add --repo ` / `ecp admin group list`.
- Query across group: `--repo @` on supported commands.
- `--repo @all` = all registered repos.
-- ecp-rs has no standalone `group_status / group_query / group_impact` commands — use `--repo @group` on the relevant agent command.
+- ecp has no standalone `group_status / group_query / group_impact` commands — use `--repo @group` on the relevant agent command.
diff --git a/skill_sample/claude/ecp/SKILL.md b/skill_sample/claude/ecp/SKILL.md
new file mode 100644
index 000000000..4bebe86f9
--- /dev/null
+++ b/skill_sample/claude/ecp/SKILL.md
@@ -0,0 +1,100 @@
+---
+name: ecp
+description: Symbol-level code analysis, blast-radius impact, cross-repo API contracts, AST-aware rename, route map for egent-code-plexus. When the question is structural (callers, definitions, impact), ecp is better than grep; for literal strings, config keys, vendored / generated code, or fs layout, grep is better.
+---
+
+# ecp — egent-code-plexus CLI
+
+`ecp [--repo ]`. `--repo` 預設 cwd；多 repo 模式必填。`ecp --help` 查細節。
+
+## Layer 1: Directives
+
+### Directive 1: Use the actual help output
+`ecp --help` is the top-level command map.
+`ecp admin --help` is the admin subcommand map.
+
+### Directive 2: Prefer the smallest command that fits
+If a task can be answered by the top-level help or a single subcommand help page, use that before reading broader reference.
+
+### Directive 3: Keep task-specific workflows separate
+Command syntax, review workflows, and broader repository guidance should live in separate guides instead of one large doc.
+
+## Layer 2: Tool Selection
+
+| When the task is | Command |
+|---|---|
+| ONE symbol → signature + body + 1-hop edges + callers + 1-hop impact | `ecp inspect --repo .` |
+| ONE symbol → blast radius | `ecp impact --direction up --repo .` |
+| PR-staged blast radius (diff vs base) | `ecp impact --baseline origin/main --repo .` |
+| Find symbol by name or concept | `ecp find "term" --repo .` (auto bm25/hybrid/vector; force via `--mode`) |
+| Arbitrary graph query / source body | `ecp cypher "MATCH ..." --repo .` (single-repo) |
+| AST-aware multi-file rename | `ecp rename --dry-run --repo .` |
+| HTTP route → handler → upstream callers | `ecp routes [] --repo .` |
+| Cross-repo API contracts (routes / queue / RPC) | `ecp contracts --repo @all` (≥2 repos in group) |
+| HTTP consumer → Route shape drift | `ecp shape-check [--route ] --repo .` |
+| Binding / route / contract delta — edge view | `ecp diff --section --baseline ][ --repo .` |
+| Registry health / freshness / blind spots | `ecp coverage [--repo @all --detailed]` |
+| MCP server / install hooks / resolver bench | `ecp admin ` (hidden namespace) |
+| Literal strings, config keys, vendored, generated, fs layout | grep / glob is better than ecp |
+
+`--direction` accepts up/down/both. Impact filters: `--kind --file_path --relation_types --depth --min-confidence --include-tests`. `ecp diff --baseline` accepts branch / tag / SHA / `HEAD~N` / `PR/`; sections combine via `,`.
+
+## Layer 3: Decision Rules (when X, Y is better)
+
+| When | Preferred path |
+|---|---|
+| Looking up a symbol by name | `ecp find` / `ecp inspect` is better than grep + Read (single call → kind + location + signature + body) |
+| Want callers + callees + body in one shot | `ecp inspect ` is better than chaining `find` → `cypher` |
+| `find` / `inspect` returns empty but grep matches | Re-running is better than escalating (auto-ensure walks tree). Still empty → `ecp admin index --force --repo .`; else symbol genuinely absent |
+| Impact shows d=1 caller outside the diff | Stop + surface to user is better than silent edit (breakage risk) |
+| Impact returns >15 symbols OR auth / payments / migrations path | Surface risk + suggest test plan is better than blind apply |
+| Refactor crosses repo boundary | `ecp contracts --repo @all --unmatched-only` is better than per-repo scan (orphan consumers visible in one view) |
+| Reference is a string / config key / dynamic dispatch | grep is better than ecp (AST doesn't see strings) |
+| Just edited a file, re-querying same turn | Waiting ~500ms (watcher debounce) or `ecp admin index --force` is better than reading possibly-stale graph |
+| Renaming a symbol called via string assembly | Two-pass — `ecp rename --dry-run` for static + `ecp find "old"` for string sweep — is better than single rename |
+| Renaming touches `.md / .rst / .txt` | `ecp rename --markdown` is better than default (code-only) |
+| High-noise file (many keyword-named idents) | `ecp impact --high-trust-only=true` is better than default impact (filters noise-prone edges) |
+
+## Repo / graph resolution
+
+- `--repo ` → registry lookup → `~/.ecp/egent-code-plexus-//graph.bin`. Branch slug = HEAD with `/` → `__`. Day-to-day.
+- `--graph ` → bypass registry (snapshot testing / registry slug mismatch).
+- `--repo @ / @all / csv` → cross-repo. Supported on `find / impact / contracts / coverage`. `cypher / inspect` are single-repo (multi-repo 報錯).
+- Group membership: `ecp admin group add --repo ` / `ecp admin group list`.
+- Auto-ensure runs on every agent command; first query post-edit pays a ~30s-2min reindex; stderr `✓ Index refreshed (... in Xs)` is informational, not an error.
+- No checked-in graph in cwd → `--repo` is better than default `--graph .ecp/graph.bin` (cwd-relative legacy).
+
+## Output formats
+
+| Command | Default | Other |
+|---|---|---|
+| `inspect / coverage / contracts / routes` | toon | json |
+| `cypher` | json | toon, text |
+| `find / rename / impact` | text | json, toon |
+| `diff / shape-check` | text | json, toon |
+
+For agent → agent piping `toon` is better than json (compact key:value); for script parsing `json` is better; for human inspection `text` is better.
+
+## Cypher subset
+
+`MATCH (a:Kind)-[r:Rel]->(b:Kind) [WHERE ...] RETURN ...`
+
+WHERE: `AND / OR / NOT`, `= != < <= > >=`, `STARTS WITH / ENDS WITH / CONTAINS / =~ / IN [...]`. 支援 `COUNT(*)` / `DISTINCT` / `ORDER BY` / `SKIP` / `LIMIT` / `WITH` / `UNION` / 變長 `[:Rel*1..2]` / 反向 `<-[r:Rel]-`.
+
+**NodeKind** (case-sensitive). Symbol: `Function Method Class Interface Constructor Property Variable Const Struct Enum EnumVariant Typedef Trait Impl Annotation Macro`. Scope: `File Namespace Module Process`. Runtime: `Route EntryPoint TransactionScope`. Data/IO: `SchemaField EventTopic PathLiteral`. Import/doc: `Import Document Section`.
+**RelType** (CamelCase only — `HAS_METHOD` 報 `unknown RelType`). Structure: `Defines HasMethod HasProperty Extends Implements Overrides`. Flow: `Calls Accesses References Imports`. Routing/IO: `HandlesRoute Fetches StepInProcess UsesPathLiteral`. Schema/event/tx: `MirrorsField Publishes Subscribes EventTopicMirror OpensTxScope`. Metadata: `Decorates`.
+**Node props**: `name uid kind filePath content` · **Edge props**: `rel_type confidence reason`
+
+`HasMethod` target kind 依語言：Python `def` 和 Rust 關聯 fn 是 `Function`；真 method 是 `Method`。`MATCH (c:Class)-[:HasMethod]->(m) RETURN m` 比 `:Method` filter 通用（涵蓋所有語言）。
+
+## Cypher recipes
+
+```cypher
+-- 未被呼叫的 export
+MATCH (f:Function) WHERE NOT (()-[:Calls]->(f)) AND f.name STARTS WITH 'export_'
+RETURN f.name, f.filePath
+
+-- Route 的 1-3 hop call chain
+MATCH path = (r:Route {name:'/api/x'})-[:HandlesRoute]->()-[:Calls*1..3]->(leaf)
+RETURN [n IN nodes(path) | n.name]
+```
diff --git a/skill_sample/claude/simplify/SKILL.md b/skill_sample/claude/simplify/SKILL.md
index 78f234940..9e28947c8 100644
--- a/skill_sample/claude/simplify/SKILL.md
+++ b/skill_sample/claude/simplify/SKILL.md
@@ -1,29 +1,35 @@
---
name: simplify
-description: Review changed code for reuse, quality, and efficiency, then fix any issues found. Each review agent leverages gnx first (when the repo is indexed) so it has graph-aware context — affected symbols, blast radius — before reading raw diffs.
+description: Review changed code for reuse, quality, and efficiency, then fix any issues found. Each review agent leverages `ecp` first (when the repo is indexed) so it has graph-aware context — changed files, impact, blind spots, egress, shape drift, and resolver deltas — before reading raw diffs.
---
-# Simplify: Code Review and Cleanup (gnx-aware)
+# Simplify: Code Review and Cleanup (`ecp`-aware)
Review all changed files for reuse, quality, and efficiency. Fix any issues found.
-The flow is the original three-agent split. The difference is **each agent runs a gnx pre-pass** so it walks into the review with affected symbols, callers, and blast radius already mapped — instead of inferring everything from the raw diff.
+The flow is the original three-agent split. The difference is **the orchestrator runs a `ecp` pre-pass** so each agent walks into the review with changed-file impact, blind spots, egress, shape drift, and resolver deltas already mapped — instead of inferring everything from the raw diff.
## Phase 1: Identify Changes
Run `git diff` (or `git diff HEAD` if there are staged changes) to list what changed. If there are no git changes, fall back to the most recently modified files the user mentioned or that you edited earlier in this conversation.
-## Phase 2: Run a single gnx pre-pass (orchestrator)
+## Phase 2: Run a single `ecp` pre-pass (orchestrator)
Once, before launching agents:
-1. **Probe whether the repo is gnx-indexed.** Try `gnx impact --baseline HEAD~1 --repo . --format json` (use the merge-base ref for PR reviews, e.g. `--baseline origin/main`). If gnx isn't installed or the repo isn't indexed (`gnx admin index --repo .` to fix), skip silently — the rest of this skill still works without graph context.
-2. **Capture two artefacts** to hand to every agent:
- - `changed_symbols`: which symbols the diff hunks resolve to (function / class / module) — from `impact --baseline`
- - `impact_by_symbol`: upstream callers per changed symbol — same call
-3. If d=1 upstream callers count is high (>10) or hits auth / payment / external-API paths, surface that as **HIGH risk** to the user before the agents launch — don't bury it in the agent reports.
+1. **Probe whether the repo is indexed.** Run `ecp review --repo . --format toon`. If it fails because `.ecp/graph.bin` is missing or stale, run `ecp admin index --repo .` once, then retry `ecp review --repo . --format toon`. If `ecp` is unavailable or indexing fails, continue with raw diff review and note the missing graph context.
+2. **Choose the review scope.**
+ - Working-tree changes: `ecp review --repo . --format toon`
+ - Changes since a baseline: `ecp review --repo . --since ][ --format toon`
+ - Explicit file list: `ecp review --repo . --files path/a.rs,path/b.rs --format toon`
+3. **Capture four artefacts** to hand to every agent:
+ - `ecp_review`: output from `ecp review` (impact, blind spots, egress/tool-map, shape-check, resolver diff)
+ - `changed_files`: file list from `git diff --name-only` or the PR diff
+ - `resolver_delta`: if needed, `ecp diff --repo . --section all --baseline ][`
+ - `risk`: LOW / MEDIUM / HIGH / CRITICAL summary inferred from the review output
+4. If `ecp review` or `ecp diff` flags HIGH or CRITICAL risk, surface that to the user before the agents launch — don't bury it in the agent reports.
-Hand the artefacts to each agent verbatim in their prompt so they can scope correctly. Tell them to call `gnx inspect --name X --repo .` or `gnx impact --target X --direction upstream --repo .` themselves on any symbol they want to dig into; the orchestrator only does the broad-strokes mapping.
+Hand the artefacts to each agent verbatim in their prompt so they can scope correctly. Tell them to use `ecp inspect --repo . --name ""`, `ecp impact --repo . "" --direction up`, `ecp find --repo . "" --mode bm25`, or `ecp diff --repo . --section all --baseline ][` themselves on any symbol or flow they want to dig into; the orchestrator only does the broad-strokes mapping.
## Phase 3: Launch three review agents in parallel
@@ -31,18 +37,19 @@ Send a single message with three Agent tool uses so they run concurrently. Each
**Common preamble for every agent prompt:**
-> The repo is at ``. The diff to review is in ``. The gnx pre-pass found:
-> - changed_symbols: `]`
-> - impact_by_symbol: `