diff --git a/Cargo.lock b/Cargo.lock
index aa18632..935f217 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -303,7 +303,7 @@ checksum = "c8d4a3bb8b1e0c1050499d1815f5ab16d04f0959b233085fb31653fbfc9d98f9"
 
 [[package]]
 name = "codegraph-bench"
-version = "0.12.0"
+version = "0.12.1"
 dependencies = [
  "anyhow",
  "clap",
@@ -318,7 +318,7 @@ dependencies = [
 
 [[package]]
 name = "codegraph-core"
-version = "0.12.0"
+version = "0.12.1"
 dependencies = [
  "anyhow",
  "serde",
@@ -334,7 +334,7 @@ dependencies = [
 
 [[package]]
 name = "codegraph-daemon"
-version = "0.12.0"
+version = "0.12.1"
 dependencies = [
  "anyhow",
  "codegraph-core",
@@ -352,7 +352,7 @@ dependencies = [
 
 [[package]]
 name = "codegraph-extract"
-version = "0.12.0"
+version = "0.12.1"
 dependencies = [
  "anyhow",
  "codegraph-core",
@@ -394,7 +394,7 @@ dependencies = [
 
 [[package]]
 name = "codegraph-graph"
-version = "0.12.0"
+version = "0.12.1"
 dependencies = [
  "anyhow",
  "codegraph-core",
@@ -406,7 +406,7 @@ dependencies = [
 
 [[package]]
 name = "codegraph-mcp"
-version = "0.12.0"
+version = "0.12.1"
 dependencies = [
  "anyhow",
  "codegraph-core",
@@ -422,7 +422,7 @@ dependencies = [
 
 [[package]]
 name = "codegraph-resolve"
-version = "0.12.0"
+version = "0.12.1"
 dependencies = [
  "anyhow",
  "codegraph-core",
@@ -436,7 +436,7 @@ dependencies = [
 
 [[package]]
 name = "codegraph-rs"
-version = "0.12.0"
+version = "0.12.1"
 dependencies = [
  "anyhow",
  "assert_cmd",
@@ -470,7 +470,7 @@ dependencies = [
 
 [[package]]
 name = "codegraph-store"
-version = "0.12.0"
+version = "0.12.1"
 dependencies = [
  "anyhow",
  "codegraph-core",
@@ -482,7 +482,7 @@ dependencies = [
 
 [[package]]
 name = "codegraph-watch"
-version = "0.12.0"
+version = "0.12.1"
 dependencies = [
  "anyhow",
  "codegraph-core",
diff --git a/README.md b/README.md
index 35c1515..404bcb9 100644
--- a/README.md
+++ b/README.md
@@ -334,9 +334,9 @@ accept the project path as a positional argument or `-p/--path`; `query`/`files`
 
 ## What CodeGraph Does (and Doesn't)
 
-**Does:** deterministic code-structure extraction across ~29 languages (TypeScript,
+**Does:** deterministic code-structure extraction across 32 languages (TypeScript,
 Python, Go, Rust, Java, C/C++, C#, Vue, Svelte, GDScript, and more — see
-[`docs/grammar-manifest.md`](docs/grammar-manifest.md)), cross-file resolution,
+[`docs/languages.md`](docs/languages.md)), cross-file resolution,
 graph traversal, FTS5 search, whole-graph export with deterministic PageRank
 centrality, MCP/CLI surfaces, and golden byte-stable output.
 
@@ -346,6 +346,25 @@ beyond the fixed `LANGUAGES` set.
 
 ---
 
+## Supported Languages
+
+CodeGraph supports **32 languages** grouped by extraction depth:
+
+**Tier 1 — Full symbol extraction (23):** TypeScript, TSX, JavaScript, JSX,
+Python, Go, Rust, Java, C, C++, C#, PHP, Ruby, Swift, Kotlin, Dart, Scala, Lua,
+Luau, Objective-C, R, GDScript, Pascal.
+
+**Tier 2 — Embedded / template extraction (6):** Vue (delegates `<script>` to
+TS/JS), Svelte (delegates script blocks), Astro, Razor/`.cshtml`, Liquid
+(Shopify templates + sections), XML/MyBatis mapper.
+
+**Tier 3 — File-level only (3):** YAML, Twig, Properties — indexed as file
+nodes; no symbol extraction.
+
+Full list with extensions and per-language notes: [`docs/languages.md`](docs/languages.md).
+
+---
+
 ## Documentation
 
 - [`docs/architecture.md`](docs/architecture.md) — crate dependency graph,
@@ -353,9 +372,11 @@ beyond the fixed `LANGUAGES` set.
 - [`docs/data-model.md`](docs/data-model.md) — SQLite/FTS5 storage contract.
 - [`docs/equivalence.md`](docs/equivalence.md) — the 3-tier equivalence oracle,
   golden regeneration, `KNOWN_DIFFS.md` format.
+- [`docs/languages.md`](docs/languages.md) — full supported-language list grouped
+  by extraction depth.
 - [`docs/grammar-manifest.md`](docs/grammar-manifest.md) /
   [`docs/embedded-extraction.md`](docs/embedded-extraction.md) — language support
-  and extraction tiers.
+  and extraction tiers (engineering ABI detail).
 - [`docs/cli.md`](docs/cli.md) — full CLI subcommand reference (22 subcommands,
   all flags).
 - [`docs/mcp.md`](docs/mcp.md) — MCP server protocol, all 10 tools, JSON-RPC
diff --git a/docs/languages.md b/docs/languages.md
new file mode 100644
index 0000000..c2d012b
--- /dev/null
+++ b/docs/languages.md
@@ -0,0 +1,105 @@
+# Supported Languages
+
+CodeGraph extracts code structure deterministically using tree-sitter grammars and custom
+embedded extractors. No AI, vectors, or embeddings are involved. The output is byte-stable
+across runs.
+
+**32 concrete languages** are supported, grouped into three extraction tiers based on what
+the extractor produces.
+
+> **Note on TypeScript/JavaScript variants:** `typescript` and `tsx`, and `javascript` and
+> `jsx`, are distinct grammar variants internally (separate `Language` enum entries). They
+> share grammars but handle different file-extension sets. The table lists each variant
+> separately so the extension mapping is unambiguous.
+
+---
+
+## Tier 1 — Full symbol extraction (23 languages)
+
+Tree-sitter parses the file and extracts all symbols (functions, classes, structs, methods,
+variables, imports, etc.) plus call and dependency edges. This is the richest extraction
+level.
+
+| Language    | Extensions                                  | Extraction                | Notes                                                                                     |
+| ----------- | ------------------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------- |
+| TypeScript  | `.ts` `.mts` `.cts`                         | Full tree-sitter          |                                                                                           |
+| TSX         | `.tsx`                                      | Full tree-sitter          | TypeScript grammar, JSX syntax                                                            |
+| JavaScript  | `.js` `.mjs` `.cjs` `.xsjs` `.xsjslib`      | Full tree-sitter          |                                                                                           |
+| JSX         | `.jsx`                                      | Full tree-sitter          | JavaScript grammar, JSX syntax                                                            |
+| Python      | `.py` `.pyw`                                | Full tree-sitter          |                                                                                           |
+| Go          | `.go`                                       | Full tree-sitter          |                                                                                           |
+| Rust        | `.rs`                                       | Full tree-sitter          |                                                                                           |
+| Java        | `.java`                                     | Full tree-sitter          |                                                                                           |
+| C           | `.c` `.h`                                   | Full tree-sitter          | `.h` may be promoted to C++ or Objective-C by heuristics                                  |
+| C++         | `.cpp` `.cc` `.cxx` `.hpp` `.hxx`           | Full tree-sitter          |                                                                                           |
+| C#          | `.cs`                                       | Full tree-sitter          |                                                                                           |
+| PHP         | `.php` `.module` `.install` `.theme` `.inc` | Full tree-sitter          |                                                                                           |
+| Ruby        | `.rb` `.rake`                               | Full tree-sitter          |                                                                                           |
+| Swift       | `.swift`                                    | Full tree-sitter          |                                                                                           |
+| Kotlin      | `.kt` `.kts`                                | Full tree-sitter          |                                                                                           |
+| Dart        | `.dart`                                     | Full tree-sitter          |                                                                                           |
+| Scala       | `.scala` `.sc`                              | Full tree-sitter          |                                                                                           |
+| Lua         | `.lua`                                      | Full tree-sitter          |                                                                                           |
+| Luau        | `.luau`                                     | Full tree-sitter          | Roblox Luau dialect                                                                       |
+| Objective-C | `.m` `.mm`                                  | Full tree-sitter          |                                                                                           |
+| R           | `.r`                                        | Full tree-sitter          |                                                                                           |
+| GDScript    | `.gd`                                       | Full tree-sitter          | Godot scripting; extracts functions, classes, enums, variables, signals, extends, preload |
+| Pascal      | `.pas` `.dpr` `.dpk` `.lpr` `.dfm` `.fmx`   | Full tree-sitter / custom | `.dfm`/`.fmx` form files use a custom path                                                |
+
+---
+
+## Tier 2 — Embedded / template extraction (6 languages)
+
+These languages wrap or embed code in another language (or use a custom extractor). The
+host file gets its own node; inner code is delegated to the appropriate Tier-1 grammar
+and merged back into the parent result.
+
+| Language      | Extensions                                       | Extraction                    | Notes                                                                                    |
+| ------------- | ------------------------------------------------ | ----------------------------- | ---------------------------------------------------------------------------------------- |
+| Vue           | `.vue`                                           | Embedded (delegates to TS/JS) | `<script>` and `<script setup>` blocks delegated; `lang="ts"` selects TypeScript grammar |
+| Svelte        | `.svelte`                                        | Embedded (delegates to TS/JS) | Script blocks extracted and delegated; component node created for the file               |
+| Astro         | `.astro`                                         | Embedded                      | Detected via embedded pre-pass only (not in the built-in extension map)                  |
+| Razor         | `.razor` `.cshtml`                               | Embedded (custom)             | Detected via embedded pre-pass only; C# snippets extracted from `.cshtml`/`.razor` files |
+| Liquid        | `.liquid`, `templates/*.json`, `sections/*.json` | Custom regex extractor        | Shopify template support; path-based `.json` detection for templates and sections        |
+| XML (MyBatis) | `.xml`                                           | Custom (MyBatis mapper)       | Extracts SQL-mapper nodes from MyBatis XML files; generic XML gets a file node only      |
+
+---
+
+## Tier 3 — File-level only (3 languages)
+
+These files are indexed as file nodes so they appear in the graph and are searchable, but
+no symbol extraction is performed. They contribute to traversal and impact analysis at the
+file level.
+
+| Language   | Extensions     | Extraction     | Notes                |
+| ---------- | -------------- | -------------- | -------------------- |
+| YAML       | `.yml` `.yaml` | File node only | No symbol extraction |
+| Twig       | `.twig`        | File node only | No symbol extraction |
+| Properties | `.properties`  | File node only | No symbol extraction |
+
+---
+
+## Adding custom extension mappings
+
+Non-standard extensions can be mapped to any supported language via `.codegraph/codegraph.json`:
+
+```jsonc
+{
+  "extensions": {
+    ".x": "lua",
+    ".blade": "php",
+  },
+}
+```
+
+Keys are dot-stripped and lowercased before matching. Unknown language names are silently
+skipped. The nearest config up the directory tree wins.
+
+---
+
+## See also
+
+- [`docs/grammar-manifest.md`](grammar-manifest.md) — engineering ABI manifest: per-language
+  grammar crate, tier policy, and ABI smoke status (for contributors and grammar maintainers).
+- [`docs/embedded-extraction.md`](embedded-extraction.md) — detailed description of the
+  embedded extraction pipeline: region detection, line-number remapping, and node merging.
diff --git a/docs/readme/README.zh-CN.md b/docs/readme/README.zh-CN.md
index ede5b11..69d5004 100644
--- a/docs/readme/README.zh-CN.md
+++ b/docs/readme/README.zh-CN.md
@@ -352,9 +352,9 @@ Set-PSReadLineKeyHandler -Key Tab -Function MenuComplete
 
 ## CodeGraph 的能力范围
 
-**做什么：** 确定性代码结构提取，支持约 29 种语言（TypeScript、Python、Go、Rust、
+**做什么：** 确定性代码结构提取，支持 32 种语言（TypeScript、Python、Go、Rust、
 Java、C/C++、C#、Vue、Svelte、GDScript 等——详见
-[`../grammar-manifest.md`](../grammar-manifest.md)），跨文件解析，图遍历，FTS5 检索，
+[`../languages.md`](../languages.md)），跨文件解析，图遍历，FTS5 检索，
 全图导出（含确定性 PageRank 中心性），MCP/CLI 表面，golden 字节稳定输出。
 
 **不做什么：** 二进制内部无任何 AI/向量/嵌入/LLM（硬约束，`scripts/guardrail.sh`
@@ -362,12 +362,32 @@ Java、C/C++、C#、Vue、Svelte、GDScript 等——详见
 
 ---
 
+## 支持的语言
+
+CodeGraph 支持 **32 种语言**，按提取深度分为三个层级：
+
+**Tier 1 — 完整符号提取（23 种）：** TypeScript、TSX、JavaScript、JSX、
+Python、Go、Rust、Java、C、C++、C#、PHP、Ruby、Swift、Kotlin、Dart、Scala、Lua、
+Luau、Objective-C、R、GDScript、Pascal。
+
+**Tier 2 — 嵌入式 / 模板提取（6 种）：** Vue（`<script>` 委托给 TS/JS）、
+Svelte（脚本块委托）、Astro、Razor/`.cshtml`、Liquid（Shopify 模板与 sections）、
+XML/MyBatis mapper。
+
+**Tier 3 — 仅文件级索引（3 种）：** YAML、Twig、Properties——作为文件节点
+索引，不提取符号。
+
+完整列表（含各语言扩展名和说明）：[`../languages.md`](../languages.md)。
+
+---
+
 ## 文档
 
 - [`../architecture.md`](../architecture.md) — crate 依赖图、提取/解析/遍历/检索流水线、daemon/watch 生命周期。
 - [`../data-model.md`](../data-model.md) — SQLite/FTS5 存储契约。
 - [`../equivalence.md`](../equivalence.md) — 3 层等价预言机、golden 再生流程、KNOWN_DIFFS 规则格式。
-- [`../grammar-manifest.md`](../grammar-manifest.md) / [`../embedded-extraction.md`](../embedded-extraction.md) — 语言支持与提取层级。
+- [`../languages.md`](../languages.md) — 支持语言完整列表，按提取深度分层。
+- [`../grammar-manifest.md`](../grammar-manifest.md) / [`../embedded-extraction.md`](../embedded-extraction.md) — 语言支持与提取层级（工程 ABI 细节）。
 - [`../cli.md`](../cli.md) — 完整 CLI 子命令参考（22 个子命令，所有标志）。
 - [`../mcp.md`](../mcp.md) — MCP 服务器协议、全部 10 个工具、JSON-RPC 详情。
 - [`../../examples/`](../../examples/) — codegraph + LLM 编排示例。