docs: SEO/GEO, zh-CN site coverage, and plain performance guides

CHANGELOG.md

@@ -8,6 +8,12 @@ Versions apply to the whole repository and are git tags (see [docs/release.md](d
 Kits are not released separately and carry no version of their own.
 
 ## [Unreleased]
+- **Docs guides (en + zh):** plain-docs pass on performance guides — drop How-to-read / Scope-and-method coaching lists where the lead already says measure-first; replace heuristic-dogfood scope wording with lint-hit vs wall-time framing; prefer `Lint: id (default …)` lines; soften coaching bold; sync zh-CN guide-src (and zperf hand `zh-CN/zig-performance-guide.md`) to the English structure and voice.
+
+- **Docs zh-CN:** site Markdown Chinese coverage for shared docs, kit guides (`guide-src/zh-CN` + build-guides stem pairing), package landings, corpus/evidence-policy/rule-ids, active evidence notes, and root pages published as `*.zh.md` via `zh-CN/` parents. Tombstone evidence under `evidence/_removed/` intentionally left English-only.
+
+- **Docs SEO / GEO (en + zh):** description, Open Graph (`og:locale` + `alternateLocale`), Twitter Card, canonical and hreflang; static export forces blocking metadata into HTML (`htmlLimitedBots`); `sitemap.xml` pairs en/zh with language alternates; `robots.txt` allows common AI crawlers; `llms.txt` + `llms.zh.txt`; locale-aware JSON-LD (`WebSite` / `WebPage` / `SoftwareApplication`); post-build sets `<html lang="zh-CN">` under `/zh/` for crawlers; 1200×630 `og.png`. README opens with an English-only value-prop hook.
+
 - **Docs site:** page links no longer keep a trailing `.md` (that 404s on GitHub Pages). Assemble rewrites them to trailing-slash directory URLs relative to the page directory, fails the build if any `.md` hrefs remain, emits static files as root-absolute paths so the `/zh/` locale works, and publishes `LICENSE` / `NOTICE` as directories so `trailingSlash` can open them.
 
 - **All kits:** default matching is **`--scope all`** where the kit CLI supports it (opt in to **`--scope loop`** for the former in-loop-only match). Finding messages no longer imply non-loop sites are out of scope. Rule slugs containing `in-loop` were **renamed** to `*-hot` (including leftover `rs-map-new-in-loop` → `rs-map-new-hot`; see per-kit Renamed tables); old slugs are tombstoned under each kit `evidence/_removed/*.REMOVED.md` and must never be reused. See each kit `docs/rule-ids.md` Renamed table. jsperf also keeps adopter FP cuts + new hints from earlier commits on this branch. No severity escalations.

README.md

@@ -1,6 +1,8 @@
 # XPerf
 
-XPerf is a set of performance guides and heuristic linters, one kit per language under `packages/`. A lint hit means “look here,” not “this will be faster.” A rule stays a hint until paired fixtures and a measured before/after promote it. Rule IDs are semantic slugs (~169 active).
+XPerf helps you find real performance smells across 19 languages — guides plus heuristic linters that stay honest: a hit means “look here,” not “this will be faster,” until paired fixtures and a measured before/after say otherwise.
+
+Docs site: [lbb00.github.io/xperf](https://lbb00.github.io/xperf/). Rule IDs are semantic slugs (~169 active).
 
 ## Languages
 

docs/zh-CN/README.md

@@ -0,0 +1,56 @@
+# XPerf 文档
+
+**XPerf** 伞形（多工具包系列）的共享文档。各语言的指南和 Lint 文档存放在各自的包下。
+
+GitHub Pages 会渲染此目录及每个工具包的指南。使用 `bash scripts/build-pages.sh serve` 进行预览。参见 [release.md](release.md)。
+
+## 共享文档（本目录）
+
+| 文档 | 目的 |
+|-----|---------|
+| [branding.md](branding.md) | 显示名称 **XPerf** 与路径 `xperf` |
+| [doc-style.md](doc-style.md) | 由 `scripts/doc-check.sh` 执行的 Markdown 规范 |
+| [release.md](release.md) | 我们在 `v*` 标签上发布的内容 |
+| [overview.md](overview.md) | XPerf 是什么：工具架构、共享循环、证据规则 |
+| [playbook.md](playbook.md) | 操作循环：库存 → 证据 → 语料库 → 反向优化 → 内部测试 → 文档 |
+| [kits.md](kits.md) | 检查入口点、默认值、语料库准备笔记（仅限短标签） |
+| [quickstart.md](quickstart.md) | 每种语言的构建/运行命令 |
+| [smell-catalog.md](smell-catalog.md) | 跨语言气味指数（ID为每套工具的标识符） |
+| [rule-regression.md](rule-regression.md) | 正/负夹具 + 证据覆盖；诚实的缺口 |
+| [rule-id-map.md](rule-id-map.md) | 历史数字 → 标识符映射（命令行接口不接受数字） |
+| [roadmap-next.md](roadmap-next.md) | 以相同方法进行下一项工作 |
+| [static-check-sources.md](static-check-sources.md) | 论坛、博客和 GitHub 上 linter 可以检测到的形状的来源 |
+
+## 各 package 入口
+
+| 工具包 | 指南 | 语料/证据政策 | Lint 文档 |
+|-----|-------|--------------------------|-----------|
+| **zperf** | [zig-performance-guide.md](../../packages/zperf/docs/zh-CN/zig-performance-guide.md) | [evidence-policy.md](../../packages/zperf/docs/zh-CN/evidence-policy.md) · `packages/zperf/evidence/` | [zperf-lint/README](../../packages/zperf/zperf-lint/README.md) |
+| **cperf** | [c-performance-guide.md](../../packages/cperf/docs/zh-CN/c-performance-guide.md) | [corpus.md](../../packages/cperf/docs/zh-CN/corpus.md) · [evidence-policy.md](../../packages/cperf/docs/zh-CN/evidence-policy.md) | `packages/cperf/cperf-lint/` |
+| **jsperf** | [js-performance-guide.md](../../packages/jsperf/docs/zh-CN/js-performance-guide.md) | [corpus.md](../../packages/jsperf/docs/zh-CN/corpus.md) · [evidence-policy.md](../../packages/jsperf/docs/zh-CN/evidence-policy.md) | `packages/jsperf/jsperf-lint/` |
+| **jvmperf** | [en/](../../packages/jvmperf/docs/en/) | [corpus.md](../../packages/jvmperf/docs/zh-CN/corpus.md) · [evidence-policy.md](../../packages/jvmperf/docs/zh-CN/evidence-policy.md) | `packages/jvmperf/jvmperf-lint/` |
+| **goperf** | [go-performance-guide.md](../../packages/goperf/docs/zh-CN/go-performance-guide.md) | [corpus.md](../../packages/goperf/docs/zh-CN/corpus.md) · [evidence-policy.md](../../packages/goperf/docs/zh-CN/evidence-policy.md) | `packages/goperf/goperf-lint/` |
+| **pyperf** | [python-performance-guide.md](../../packages/pyperf/docs/zh-CN/python-performance-guide.md) | [corpus.md](../../packages/pyperf/docs/zh-CN/corpus.md) · [evidence-policy.md](../../packages/pyperf/docs/zh-CN/evidence-policy.md) | `packages/pyperf/pyperf-lint/` |
+| **swiftperf** | [swift-performance-guide.md](../../packages/swiftperf/docs/zh-CN/swift-performance-guide.md) | [corpus.md](../../packages/swiftperf/docs/zh-CN/corpus.md) · [evidence-policy.md](../../packages/swiftperf/docs/zh-CN/evidence-policy.md) | `packages/swiftperf/swiftperf-lint/` |
+| **arktsperf** | [arkts-performance-guide.md](../../packages/arktsperf/docs/zh-CN/arkts-performance-guide.md) | [corpus.md](../../packages/arktsperf/docs/zh-CN/corpus.md) · [evidence-policy.md](../../packages/arktsperf/docs/zh-CN/evidence-policy.md) | `packages/arktsperf/arktsperf-lint/` |
+| **cppperf** | [cpp-performance-guide.md](../../packages/cppperf/docs/zh-CN/cpp-performance-guide.md) | [corpus.md](../../packages/cppperf/docs/zh-CN/corpus.md) · [evidence-policy.md](../../packages/cppperf/docs/zh-CN/evidence-policy.md) | `packages/cppperf/cppperf-lint/` |
+| **csharpperf** | [csharp-performance-guide.md](../../packages/csharpperf/docs/zh-CN/csharp-performance-guide.md) | [corpus.md](../../packages/csharpperf/docs/zh-CN/corpus.md) · [evidence-policy.md](../../packages/csharpperf/docs/zh-CN/evidence-policy.md) | `packages/csharpperf/csharpperf-lint/` |
+| **phpperf** | [php-performance-guide.md](../../packages/phpperf/docs/zh-CN/php-performance-guide.md) | [corpus.md](../../packages/phpperf/docs/zh-CN/corpus.md) · [evidence-policy.md](../../packages/phpperf/docs/zh-CN/evidence-policy.md) | `packages/phpperf/phpperf-lint/` |
+| **rubyperf** | [ruby-performance-guide.md](../../packages/rubyperf/docs/zh-CN/ruby-performance-guide.md) | [corpus.md](../../packages/rubyperf/docs/zh-CN/corpus.md) · [evidence-policy.md](../../packages/rubyperf/docs/zh-CN/evidence-policy.md) | `packages/rubyperf/rubyperf-lint/` |
+| **rustperf** | [rust-performance-guide.md](../../packages/rustperf/docs/zh-CN/rust-performance-guide.md) | [corpus.md](../../packages/rustperf/docs/zh-CN/corpus.md) · [evidence-policy.md](../../packages/rustperf/docs/zh-CN/evidence-policy.md) | `packages/rustperf/rustperf-lint/` |
+| **kotlinperf** | [kotlin-performance-guide.md](../../packages/kotlinperf/docs/zh-CN/kotlin-performance-guide.md) | [corpus.md](../../packages/kotlinperf/docs/zh-CN/corpus.md) · [evidence-policy.md](../../packages/kotlinperf/docs/zh-CN/evidence-policy.md) | `packages/kotlinperf/kotlinperf-lint/` |
+| **objcperf** | [objc-performance-guide.md](../../packages/objcperf/docs/zh-CN/objc-performance-guide.md) | [corpus.md](../../packages/objcperf/docs/zh-CN/corpus.md) · [evidence-policy.md](../../packages/objcperf/docs/zh-CN/evidence-policy.md) | `packages/objcperf/objcperf-lint/` |
+| **dartperf** | [dart-performance-guide.md](../../packages/dartperf/docs/zh-CN/dart-performance-guide.md) | [corpus.md](../../packages/dartperf/docs/zh-CN/corpus.md) · [evidence-policy.md](../../packages/dartperf/docs/zh-CN/evidence-policy.md) | `packages/dartperf/dartperf-lint/` |
+| **luaperf** | [lua-performance-guide.md](../../packages/luaperf/docs/zh-CN/lua-performance-guide.md) | [corpus.md](../../packages/luaperf/docs/zh-CN/corpus.md) · [evidence-policy.md](../../packages/luaperf/docs/zh-CN/evidence-policy.md) | `packages/luaperf/luaperf-lint/` |
+| **beamperf** | [beam-performance-guide.md](../../packages/beamperf/docs/zh-CN/beam-performance-guide.md) | [corpus.md](../../packages/beamperf/docs/zh-CN/corpus.md) · [evidence-policy.md](../../packages/beamperf/docs/zh-CN/evidence-policy.md) | `packages/beamperf/beamperf-lint/` |
+| **nimperf** | [nim-performance-guide.md](../../packages/nimperf/docs/zh-CN/nim-performance-guide.md) | [corpus.md](../../packages/nimperf/docs/zh-CN/corpus.md) · [evidence-policy.md](../../packages/nimperf/docs/zh-CN/evidence-policy.md) | `packages/nimperf/nimperf-lint/` |
+
+## 导航示意
+
+```mermaid
+flowchart TB
+  root[xperf]
+  root --> readme["README.md<br/>family entry"]
+  root --> docs["docs/<br/>overview · quickstart · kits<br/>playbook · smell catalog · rule regression<br/>roadmap · release · doc style"]
+  root --> kit["packages/kit/<br/>README · guide · corpus<br/>evidence/ · lint/"]
+```

docs/zh-CN/branding.md

@@ -0,0 +1,6 @@
+# 品牌写法
+
+| 形式 | 用法 |
+|------|------|
+| **XPerf** | 正文中的产品名：标题、句子、版权行（“XPerf contributors”）。 |
+| **xperf** | 仓库目录、克隆路径、归档名（`xperf-0.1.0-packages.tar.gz`）。 |

docs/zh-CN/doc-style.md

@@ -0,0 +1,34 @@
+# 文档风格
+
+由 `bash scripts/doc-check.sh` 与 `bash scripts/build-guides.sh --check` 强制执行（二者均在 CI 中运行）。在源头修正；不要放宽检查。
+
+## 全部 Markdown
+
+- 首行必须是一个 `# H1`；标题层级不可跳级；仅使用 ATX（`#`）标题。
+- 无行尾空白、无 CRLF、恰好一个末尾换行。
+- 相对链接必须可解析。不要链接到仓库外的文件。
+- 列表使用 `-`；代码围栏在适用时带上语言标签。
+- 除 `zh-CN/` 目录外一律使用英文。
+
+## 每个 package
+
+| 文件 | 要求 |
+|------|------|
+| `README.md` | 含 `## Run lint` 与 `## Layout`（建议顺序：Contents、Focus、Run lint、Layout） |
+| `docs/corpus.md` | 先写 `## Pins`；其后章节为带日期的笔记 |
+| `docs/evidence-policy.md` | 先 `## Gate`，再 `## Current map`（标题不含日期或版本；把“截至 <date>”写在该节首行） |
+| `docs/rule-ids.md` | 一个 H1；墓碑放在 `## Removed (tombstone; never reuse)` 下 |
+| `evidence/<slug>.md` | 含 `Claim`、`How measured`、`Runtime` 表与结果；或待定规则用 `Status` / `Reason` / `Unblock` |
+
+## 指南
+
+`docs/guide-src/*.md`（或 `guide-src/<lang>/*.md`）是唯一源。指南本身由生成得到：
+
+```sh
+bash scripts/build-guides.sh          # 从 guide-src 重写指南
+bash scripts/build-guides.sh --check  # 若指南被手改则失败
+```
+
+- 分片按字节拼接，因此仅当指南在该处需要空行时，分片才以空行结尾。
+- 分片内的链接相对**生成后的指南**书写，而不是相对 `guide-src/`。
+- 分片名为 `NN_topic.md`；`00_head.md` 打开指南。

docs/zh-CN/kits.md

@@ -0,0 +1,31 @@
+# 套件状态
+
+列出每个包的 Lint 入口点、默认严重性和语料库注释。规则 ID 仅为 **短标签**。计数与每个工具包的 `docs/rule-ids.md` 匹配（不包括墓碑）。启发式命中是审查提示，而非加速手段。
+
+在 AGENT.md G3 门下，所有 **19** 个工具包对于 2026-10-22（亚洲/上海）已分级的规则集都是 **语料库就绪** 的。2026-10-23 添加的提示规则 **不** 包含在该裁定中。现在有几个带有微基准测试并保持 **提示** 状态。公平重运行仍在 1× 附近的规则已被移除。新的标识没有进行语料库分级。
+
+| 软件包 | 代码检查 | 活跃 | 备注 |
+|---------|------|-------:|-------|
+| [zperf](../../packages/zperf/) | `zperf-lint` | 31 | Zig 0.17+。G3/r4 降级了 OK-idiom mass 规则；一些默认设置仍然启用（例如 `zp-page-allocator-small`, `zp-broad-runtime-safety`）。`zp-alloc-print-hot` 是未更改格式字符串的提示。 |
+| [cperf](../../packages/cperf/) | `cperf-lint` | 12 | C11 检查器 + 预设。`cp-alloc-hot` / `cp-realloc-grow-one` 错误；strlen, sprintf, fopen, clock, wide-bool-flag, `regcomp`, `alloca`-in-loop, 以及大值传递结构体提示；`cp-printf-hot` / `cp-strcat-hot` 在默认应用预设下关闭。2026-10-23 的提示有微基准测试，并不属于语料库裁决的一部分。 |
+| [jsperf](../../packages/jsperf/) | `jsperf-lint` | 11 | 纯节点 ≥18，无 npm 依赖。`jp-delete-array-hole` 错误；map-filter / regex-ctor / JSON / DOM-query / `Intl.DateTimeFormat` / `readFileSync` / 时钟提示；在应用预设下关闭 alloc / 控制台默认设置。`jp-string-plus-in-loop` 已移除（`push` + `join` 并非约 2×）。 |
+| [jvmperf](../../packages/jvmperf/) | `jvmperf-lint` | 29 | Java (Gradle)。在测试中固定使用 JDK **21**。在 G3/G4 之后混合出现错误/提示/关闭；请参阅工具包证据政策。|
+| [goperf](../../packages/goperf/) | `goperf-lint` | 10 | `gp-append-nil-slice` / `gp-defer-hot` 加上正则表达式 / JSON / 反射名称查找提示；`gp-make-hot`–`gp-fmt-hot` 关闭。`time.Parse` 已被移除。 |
+| [pyperf](../../packages/pyperf/) | `pyperf-lint` | 6 | `pp-list-plus-rebind` 加 JSON / deepcopy 提示；`pp-str-plus-hot` / `pp-print-hot` 关闭。`re.compile` 和 `datetime.strptime` 已被移除。 |
+| [swiftperf](../../packages/swiftperf/) | `swiftperf-lint` | 8 | `sp-array-no-reserve` 提示（小构建者约 5×；一个大填充约 1.6×）。循环打印保持关闭（约 10× 输出到 /dev/null）。强制解包，字符串 `+=`，以及 `map`/`joined` 已移除。日期格式化器 / JSON 解码 / `NSRegularExpression` 提示仍然存在。2026-10-23 的提示不属于语料库判定。若缺少 Swift SDK，则进行文本检查路径。 |
+| [arktsperf](../../packages/arktsperf/) | `arktsperf-lint` | 4 | 节点在 `.ets`/`.ts`/`.js` 上进行 lint 检查。`at-includes-hot` / `at-json-hot` 提示；分配 / 控制台默认关闭。 |
+| [cppperf](../../packages/cppperf/) | `cppperf-lint` | 6 | 专用 C++17（≠ cperf）。regex、endl、clock、ifstream、按值 const 和 vector-bool 提示。字符串追加、字符串流以及若干 jitter id **已删除**。短 `const` 字符串保持在约 1×，并仍有提示。 |
+| [csharpperf](../../packages/csharpperf/) | `csharpperf-lint` | 10 | 需要 `dotnet`。`cs-regex-hot`、LINQ 实例化、`string.Format` 和 JSON 提示；列表添加 / 字符串拼接 / 关闭控制台。 |
+| [phpperf](../../packages/phpperf/) | `phpperf-lint` | 3 | `ph-array-merge-rebind` 错误 (G4); `ph-string-dot-hot` 关闭; `ph-echo-hot` 提示. |
+| [rubyperf](../../packages/rubyperf/) | `rubyperf-lint` | 6 | 正则表达式 / JSON / 文件读取提示；字符串加 / 数组加 / 延迟输出。`Date.parse` 和 `Hash#merge` 已移除。 |
+| [rustperf](../../packages/rustperf/) | `rustperf-lint` | 7 | `rs-format-rebind-hot` 错误；println / collect / 正则提示；`rs-alloc-hot` 关闭。已去除摊销 `+=`、`Vec::new` 加上 push，以及循环中的 `HashMap::new`。 |
+| [kotlinperf](../../packages/kotlinperf/) | `kotlinperf-lint` | 3 | Kotlin-first (≠ jvmperf JMH)。所有三个规则默认关闭；一个抖动 ID **已移除**。 |
+| [objcperf](../../packages/objcperf/) | `objcperf-lint` | 8 | Objective-C（≠ swiftperf）。`oc-nsstring-append-hot` / `oc-nslog-hot` 关闭；日期格式化器、JSON 和正则表达式提示。两个抖动 ID **已移除**。|
+| [dartperf](../../packages/dartperf/) | `dartperf-lint` | 4 | `dt-growable-add-empty` 提示；list-add / string-plus / 打印 默认关闭。 |
+| [luaperf](../../packages/luaperf/) | `luaperf-lint` | 3 | `lu-string-concat-hot` 错误 (G4); `lu-table-insert-hot` 关闭; `lu-print-hot` 提示. |
+| [beamperf](../../packages/beamperf/) | `beamperf-lint` | 4 | Elixir + Erlang。list-concat / map-merge / enum-chain 提示；`be-io-puts-hot` 关闭。一个抖动ID **已移除**。 |
+| [nimperf](../../packages/nimperf/) | `nimperf-lint` | 4 | 需要 `nim`。`nm-seq-no-capacity` 提示；默认关闭 seq-add / string / echo。 |
+
+没有编造的发布网址。
+
+历史数字 → slug 映射（命令行界面**不**接受数字）：[rule-id-map.md](rule-id-map.md)。