docs: sync with 2026.8.3.4 — ZH windows→linux section, artifact naming, correct the pin-checker claim

Review of #348 against the current tree (2026.8.3.4, three releases newer than
when the sync was written). Four things needed adjusting.

1. The ZH toolchain doc was missing THREE sections the EN one has, including
   the whole `x86_64-linux-musl`-from-Windows feature (2026.8.3.2). A Chinese
   reader had no way to learn that Windows can produce Linux ELF at all. Added,
   mirroring EN: "Windows 上产出 Linux ELF", "MSVC(系统工具链,Windows)", and
   the Clang 20+ operator-template hazard. EN/ZH are now at 16 sections each,
   and every other doc pair already matched.

   The EN section's claims were re-derived from `toolchain::host_can_serve`
   before translating: Windows serves linux targets only when musl AND same
   arch, which is exactly "no x86_64-linux-gnu, no cross-arch". Both languages
   now also state the fact that function makes explicit and the docs omitted —
   **a macOS host has no Linux-targeting payload at all** — and point at
   `mcpp toolchain list` as the authority so nobody has to memorize the matrix.

2. Artifact naming, undocumented since 2026.8.3.3 changed it. `kind = "lib"`
   for `x86_64-windows-gnu` produces `libfoo.a`, not `foo.lib`: the static-lib
   convention splits on the triple's *env* segment, not its OS. That release
   fixed a name that was wrong (a GNU archive wearing an MSVC name, which MSVC
   cannot consume), so anyone globbing `*.lib` out of a mingw build needs to
   know. Added as a table to both languages.

3. `docs/spec/package-identity.md` carried "当前实现为 2026.8.3.2" — already
   stale two releases later. A spec should not restate a value that expires on
   every release; the minimum-implementation version (0.0.106) is the load
   bearing one and it is still there. Dropped the parenthetical rather than
   bumping it, so it cannot go stale again.

4. **`check_version_pins.sh` does not have a Bash syntax error.** It parses
   (`bash -n`), runs, and exits 0 — verified on this tree. The failure is
   `sh check_version_pins.sh`: the script uses process substitution
   (`done < <(...)`), which dash cannot parse, so it reports
   "line 95: Syntax error: redirection unexpected". That is the invoking shell,
   not the script — its shebang is `#!/usr/bin/env bash` and CI invokes it as
   bash.

   This mattered enough to chase down because the claim appeared in six places
   across three files, each instructing the releaser to skip the guard and
   check pins by hand. That guard is the only machine check for pin drift, and
   pin drift has broken releases here before. All six now show the correct
   invocation and explain the sh-vs-bash trap instead.

Also noted the cache-entry layout change from 2026.8.3.4 in the `[build] cache`
section (both languages): entry layout is versioned, an upgrade that changes it
retires older entries and the next build repopulates — nothing to clean by hand.

The PR's other two findings were re-verified against the source and are correct:
`kind = "shared"` really is refused off Linux/ELF (plan.cppm:513), and
`[build].cxx_runtime` really is parsed but missing from `kKnownBuildKeys` — the
allowlist's own comment says it "MUST stay in sync with the doc->get_* reads",
and it is not. Left as-is; this PR touches no source.

Author: speak-agent

.agents/skills/mcpp-release/SKILL.md

@@ -47,10 +47,19 @@ mcpp 有 **三个持久化版本位置**，以及 `ci-fresh-install` 的一个
 Release 推导一次，所有安装 job 消费同一个输出。绝不能手工编辑或恢复字面量
 `MCPP_PIN`，否则 index guard 和实际安装版本会再次漂移。
 
-`.github/tools/check_version_pins.sh` 的目标是校验版本关系和 xlings pin；但当前版本在
-第 95 行有 Bash 语法错误，不能把它的执行当成有效验证。修复该实现前，手工核对
-`mcpp.toml` 与 `MCPP_VERSION` 相等、`.xlings.json` 不领先于正在构建的版本；也不要
-通过修改文档或 workflow 绕开动态 `MCPP_PIN` 设计。`src/xlings.cppm` 的
+`.github/tools/check_version_pins.sh` 校验版本关系和 xlings pin：
+
+```bash
+bash .github/tools/check_version_pins.sh
+```
+
+**必须用 `bash` 跑，不能用 `sh`。** 脚本用了进程替换（`done < <(...)`），POSIX
+`sh`/dash 解析不了，用 `sh` 调用会在第 95 行附近报 `Syntax error: redirection
+unexpected`。那是调用它的 shell 的问题，不是脚本的缺陷 —— 它的 shebang 是
+`#!/usr/bin/env bash`，CI 也是用 `bash` 调的。别据此把这条 guard 当成坏的而跳过：
+它是唯一能机器化捕捉 pin 漂移的东西。
+
+也不要通过修改文档或 workflow 绕开动态 `MCPP_PIN` 设计。`src/xlings.cppm` 的
 `pinned::kXlingsVersion` 仍是 xlings 版本的唯一真源。
 
 ## 发布步骤
@@ -82,8 +91,8 @@ git checkout -b "chore/bump-$NEW_VERSION"
 sed -i "s/^version.*=.*/version     = \"$NEW_VERSION\"/" mcpp.toml
 sed -i "s/MCPP_VERSION = \".*\"/MCPP_VERSION = \"$NEW_VERSION\"/" src/toolchain/fingerprint.cppm
 
-# 当前 check_version_pins.sh 有 Bash 语法错误；在它修复前手工确认：
-# mcpp.toml 与 MCPP_VERSION 相等，.xlings.json 仍是已发布的 bootstrap 版本。
+# 校验：mcpp.toml 与 MCPP_VERSION 相等，.xlings.json 不领先于正在构建的版本。
+bash .github/tools/check_version_pins.sh
 
 # 自查：构建产物真的报新版本。注意 target/ 目录名带指纹哈希，
 # 版本一变就是新目录 —— 用 `ls -dt` 取最新的那个，`head -1` 会拿到旧二进制。
@@ -212,7 +221,7 @@ xlings update && xlings install mcpp@$NEW_VERSION -y
 # 3) bootstrap pin 收尾 —— 仅 .xlings.json；新版此时已发布、已镜像、已进索引
 sed -i "s/\"mcpp\": \"[^\"]*\"/\"mcpp\": \"$NEW_VERSION\"/" .xlings.json
 # 不编辑 ci-fresh-install.yml 的 MCPP_PIN：它由 wait-index 运行时推导。
-# 当前 check_version_pins.sh 有 Bash 语法错误；手工确认 pin 关系。
+bash .github/tools/check_version_pins.sh   # 复核 pin 关系
 git commit -am "ci: workspace mcpp bootstrap pin -> $NEW_VERSION (released, mirrored, indexed)"
 ```
 
@@ -304,7 +313,7 @@ gh workflow run release.yml --ref "v$NEW_VERSION"
 | `.xlings.json` | `workspace.mcpp` — CI bootstrap 装哪个 mcpp（发布**后**才 bump） |
 | `.github/workflows/ci-fresh-install.yml` | `MCPP_PIN` — 由 `wait-index` 从最新 release 推导，**从不手工 bump** |
 | `src/xlings.cppm` | `kXlingsVersion` — xlings pin 的**唯一真源** |
-| `.github/tools/check_version_pins.sh` | 版本/pin 校验的预期 guard；当前有 Bash 语法错误，修复前须手工核对 |
+| `.github/tools/check_version_pins.sh` | 版本/pin 校验 guard（**用 `bash` 跑，不能用 `sh`**） |
 | `.github/tools/slim_linux_payload.sh` | linux 载荷 strip + 断言 |
 | `.github/tools/mirror_res.sh` | 双端镜像（并发上传 + leg deadline + 完整性 gate） |
 | `.github/tools/gtc` | GitCode CLI（release create/upload、PR） |
@@ -315,5 +324,4 @@ gh workflow run release.yml --ref "v$NEW_VERSION"
 > **注意版本 bump 的两个阶段**：`mcpp.toml` + `fingerprint.cppm` 在发版**前**改
 > （它们定义要发什么）；`.xlings.json` 只在发版成功、镜像并进索引后才可更新
 > （它指定 bootstrap 使用的已发布版本）。`MCPP_PIN` 是被测版本的运行时推导值，
-> 不属于任何手工 bump 阶段。当前 `check_version_pins.sh` 的 Bash 语法错误修复前，
-> 这些关系须手工核对。
+> 不属于任何手工 bump 阶段。这些关系由 `bash .github/tools/check_version_pins.sh` 校验。

docs/03-toolchains.md

@@ -162,6 +162,18 @@ windows = "gcc@16"            # gcc family on Windows = MinGW-w64
 # legacy value "mingw@16.1.0" keeps working
 ```
 
+Artifact names follow the **target**, and for static libraries the convention
+splits on the *env* segment, not on the OS:
+
+| Target | `kind = "lib"` produces |
+|---|---|
+| `x86_64-windows-gnu` | `libfoo.a` (GNU convention) |
+| `x86_64-windows-msvc` | `foo.lib` (MSVC convention) |
+
+Before 2026.8.3.3 a mingw build on a Windows host emitted `foo.lib` — a GNU
+archive wearing an MSVC name, which MSVC cannot consume. If you have a script
+that globs `*.lib` out of a `windows-gnu` build, it needs to glob `*.a` now.
+
 ## Linux ELF from Windows (`x86_64-linux-musl`, no WSL required)
 
 The mirror of the section above: a Windows machine producing a **fully static
@@ -193,9 +205,13 @@ mcpp: ELF 64-bit LSB executable, x86-64, statically linked, stripped
 Linux hosts only. The musl target is self-contained and needs neither.
 
 Cross-arch from Windows (e.g. `aarch64-linux-musl`) is not available either —
-the canadian-cross payload is built per host arch. `mcpp toolchain list` shows
-only what the current host can actually install, so if a target is missing from
-the Targets block, that host genuinely cannot serve it.
+the canadian-cross payload is built per host arch. **A macOS host has no
+Linux-targeting payload at all**, so no Linux target is reachable from there.
+
+You do not have to memorize any of this: `mcpp toolchain list` shows only what
+the current host can actually install, so if a target is missing from the
+Targets block, that host genuinely cannot serve it (implemented by
+`toolchain::host_can_serve`).
 
 ## MSVC (System Toolchain, Windows)
 

docs/05-mcpp-toml.md

@@ -895,6 +895,14 @@ mcpp cache gc --older-than 30d      # ...or by how long since they were last use
 mcpp cache clean [--deps|--std|--all|--legacy]
 ```
 
+The on-disk entry layout is versioned. An mcpp release that changes it retires
+every older entry at once, so the first build after such an upgrade rebuilds
+its dependencies and repopulates — nothing to clean by hand. 2026.8.3.4 did
+exactly that: an entry's object paths are now addressed relative to the
+*package*, never to the build directory of whichever project happened to
+populate the entry first. `mcpp cache verify` additionally reports any entry
+whose recorded addresses escape it, so a recurrence is auditable offline.
+
 ### 2.11 `[runtime]` — Host Runtime Capabilities
 
 ```toml

docs/09-release.md

@@ -15,11 +15,19 @@ of those commit messages contains a misdiagnosis that is corrected in §5.
 | `.xlings.json` `[workspace].mcpp` | **bootstrapped from** | separately, *after* a release is installable |
 | `ci-fresh-install.yml` `MCPP_PIN` | **version under test** | **nothing — it is derived at run time** (§5) |
 
-The intended `.github/tools/check_version_pins.sh` guard covers the persistent
-relationships: the two "being built" sites must be equal, and the bootstrap
-pin must never be **newer** than the version being built. At this revision the
-script has a Bash syntax error, so it cannot currently provide that verification;
-check these relationships manually until its implementation is repaired.
+`.github/tools/check_version_pins.sh` machine-checks the persistent
+relationships: the two "being built" sites must be equal, and the bootstrap pin
+must never be **newer** than the version being built.
+
+```bash
+bash .github/tools/check_version_pins.sh
+```
+
+Run it with **bash**, not `sh`. It uses process substitution (`done < <(...)`),
+which POSIX `sh`/dash cannot parse — `sh check_version_pins.sh` fails with
+`Syntax error: redirection unexpected` around line 95. That is the invoking
+shell, not a defect in the script: its shebang is `#!/usr/bin/env bash` and CI
+invokes it as `bash`.
 
 The two groups are deliberately allowed to differ. Bumping them together is what
 an earlier revision of the pin checker required, and it sent every CI job to
@@ -123,8 +131,7 @@ hardcoded literal only bought the first:
    The guard was already deriving the right answer and throwing it away. Feeding
    both from one value makes that disagreement structurally impossible.
 
-The intended `check_version_pins.sh` guard rejects a literal `MCPP_PIN:`. Do
-not reintroduce one while its current syntax error is being repaired: a literal
+`check_version_pins.sh` rejects a literal `MCPP_PIN:`. Do not reintroduce one: a literal
 would again let the index guard and the installed version drift apart.
 
 > **Correction.** Commit `3b1cb6b` ("bootstrap pin -> 2026.7.29.2") states *"the
@@ -139,7 +146,7 @@ would again let the index guard and the installed version drift apart.
 ```
 [ ] version bumped in mcpp.toml + fingerprint.cppm (one commit)
 [ ] CHANGELOG entry
-[ ] manually verify `mcpp.toml` = `MCPP_VERSION` and `.xlings.json` is not newer (the current `check_version_pins.sh` has a Bash syntax error)
+[ ] `bash .github/tools/check_version_pins.sh` passes (verifies `mcpp.toml` = `MCPP_VERSION`, and `.xlings.json` is not newer)
 [ ] merge to main, CI green
 [ ] gh workflow run release.yml --ref main
 [ ] release.yml green (4 builds + publish-ecosystem)

docs/spec/package-identity.md

@@ -7,7 +7,7 @@
 | **状态** | **评审中(Review)** —— 已实现 |
 | **版本** | 1.1 |
 | **最后修改** | 2026-08-03 |
-| **最低实现版本** | mcpp **0.0.106**(xlings >= 0.4.69；当前实现为 2026.8.3.2) |
+| **最低实现版本** | mcpp **0.0.106**(xlings >= 0.4.69) |
 | **作者/维护** | mcpp-community |
 | **相关设计文档** | `.agents/docs/2026-06-20-package-resolution-architecture.md` §4<br>`.agents/docs/2026-06-26-identity-first-resolution-no-filename.md`<br>`.agents/docs/2026-07-25-issue278-descriptor-name-form-canonicalization-design.md`<br>`.agents/docs/2026-07-25-name-namespace-bidirectional-verification-report.md`<br>`.agents/docs/2026-07-25-name-namespace-canonical-implementation-spec.md` |
 | **相关 issue** | [mcpp#278](https://github.com/mcpp-community/mcpp/issues/278)<br>[xlings#381](https://github.com/openxlings/xlings/issues/381) —— 索引键缺命名空间维度(§3.3) |

docs/zh/03-toolchains.md

@@ -156,6 +156,98 @@ windows = "gcc@16"            # Windows 上的 gcc family = MinGW-w64
 # 旧值 "mingw@16.1.0" 原样可用
 ```
 
+产物名跟随 **target**;静态库的命名约定分岔点是 triple 的 *env* 段,而不是 OS:
+
+| Target | `kind = "lib"` 产出 |
+|---|---|
+| `x86_64-windows-gnu` | `libfoo.a`(GNU 约定) |
+| `x86_64-windows-msvc` | `foo.lib`(MSVC 约定) |
+
+2026.8.3.3 之前,Windows 宿主上的 mingw 构建产出的是 `foo.lib` —— 一个 GNU
+archive 顶着 MSVC 的名字,MSVC 拿不去用。如果你有脚本按 `*.lib` 去捞
+`windows-gnu` 的产物,现在要改成 `*.a`。
+
+## Windows 上产出 Linux ELF(`x86_64-linux-musl`,无需 WSL)
+
+上一节的镜像:一台 Windows 机器直接产出**完全静态的 Linux 二进制**,
+不需要 WSL、不需要容器,也不往系统里装任何东西。
+
+```bash
+mcpp build --target x86_64-linux-musl        # Windows 或 Linux 上皆可
+```
+
+两种宿主上这条命令**逐字相同**,因为 "交叉" 在 mcpp 里不是一个名字,
+它只是 `host ≠ target` 这个关系。由哪个 payload 承接目标是自动分流的:
+Linux x86_64 宿主装原生 `musl-gcc`;Windows 宿主装一条 **canadian-cross**
+GCC(以 `x86_64-linux-gnu` 构建 → 运行于 `x86_64-w64-mingw32` → 产出
+`x86_64-linux-musl`)。两者都是 GCC 16.1.0,也都带 `bits/std.cc`,
+所以 `import std` 在两边行为一致。
+
+产物是没有 `PT_INTERP` 的全静态 ELF —— 不挑发行版、不挑 libc,
+这正是 musl 成为第一个被打通的 Linux target 的原因:
+
+```console
+$ file mcpp
+mcpp: ELF 64-bit LSB executable, x86-64, statically linked, stripped
+```
+
+Windows 上**不支持** `x86_64-linux-gnu`:glibc target 还需要 `xim:glibc`
+与 `xim:linux-headers` 两个 sysroot payload,而它们只为 Linux 宿主发布。
+musl target 自包含,两者都不需要。
+
+Windows 上也**不支持跨 arch**(如 `aarch64-linux-musl`)—— canadian-cross
+payload 是按宿主 arch 构建的。**macOS 宿主则完全没有面向 Linux 的 payload**,
+任何 Linux target 都不可用。
+
+判据不必靠记:`mcpp toolchain list` 只列出当前宿主真正装得上的 target,
+Targets 一栏里没有的,就是这台机器确实服务不了(实现见
+`toolchain::host_can_serve`)。
+
+## MSVC(系统工具链,Windows)
+
+MSVC 与 mcpp 管理的其它工具链都不同:它是一条**系统工具链**。mcpp 只负责
+定位并识别已安装的 Visual Studio / Build Tools —— **从不**安装、升级或卸载
+MSVC 本身。
+
+```bash
+mcpp toolchain default msvc
+```
+
+在装有 MSVC 的机器上,mcpp 会自动定位(依次尝试 `vswhere.exe`、
+`VSINSTALLDIR`/`VS*COMNTOOLS`、标准安装路径),识别涉及的各个版本,
+并持久化为稳定 spec `msvc@system`:
+
+```
+Detected   msvc 19.44.35211 (VS 2022 BuildTools) (VC tools 14.44.35207)
+           cl: C:\Program Files\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.44.35207\bin\Hostx64\x64\cl.exe
+           import std: available (std.ixx)
+Default    set to msvc@system (was: llvm@20.1.7)
+```
+
+若机器上**没有** MSVC,mcpp 打印安装指引(Visual Studio Installer 勾选
+*Desktop development with C++* 负载,或 `winget install
+Microsoft.VisualStudio.2022.BuildTools`)并以非零码退出 —— 需要你自己装好,
+再重跑该命令。
+
+`mcpp toolchain list` 会把检测到的 MSVC 列在单独的 `System:` 分区,
+`mcpp self doctor` 在 Windows 上会报告它的状态。manifest 里可按平台 pin:
+
+```toml
+[toolchain]
+windows = "msvc@system"
+```
+
+`msvc@<前缀>`(如 `msvc@19.44`)是一个 **pin-verify**:mcpp 仍然使用已安装
+的最新 VC tools,但检测到的版本与前缀不符时报错。
+
+自 0.0.90 起,**原生 cl.exe 构建可用**:mcpp 从检测到的 VC tools + Windows
+SDK 合成 INCLUDE/LIB 环境(不经 `vcvarsall`),把 `std.ixx`/`std.compat.ixx`
+staging 成 `.ifc` BMI,用 `/interface /TP /ifcOutput` 编译 `.cppm` 模块单元,
+用 `/scanDependencies` 扫描,并通过 response file 调 `link.exe`/`lib.exe`
+链接。选择 `/MT` CRT 用 `[target.x86_64-windows-msvc] linkage = "static"`
+(或 `mcpp build --static`)—— 不是 `[build] linkage`,那个键不存在。
+缺 Windows SDK 会让构建失败并给出安装指引(`mcpp self doctor` 会报告 SDK 状态)。
+
 ## 项目级版本锁定
 
 若项目需固定特定版本而不依赖全局默认,可在项目的 `mcpp.toml` 中声明:
@@ -239,3 +331,51 @@ mcpp 的运行行为可通过以下环境变量调整:
 工具链 ABI 不满足任一依赖的 abi 要求时,构建会**尽早失败**并给出修复建议
 (例如 musl-static 工具链遇到 abi:glibc 依赖),取代深层的链接/头文件报错。
 查看:`mcpp why toolchain`。
+
+## 已知工具链风险:模块接口中的运算符模板(Clang 20+)
+
+一个导出**替换性运算符模板**的模块,在 Clang 20 或 22 下会毒化所有导入者
+中该运算符的名字查找:任何 `import` 了这个模块、并用到该运算符的 TU
+——**无论作用在什么类型上**——都会让前端崩溃(SIGSEGV)。GCC 16 与
+Clang 18 不受影响,所以这是 Clang 18 到 20 之间的一处回归。
+
+它正好打在 module-package 这个模式上。包装一个运算符是 `static inline`
+模板的上游头文件,再用一个恒真约束镜像它们的签名(跨 TU 包含关系的标准配方),
+恰恰就是踩中它的写法。
+
+**经验判据:**每个模板形参都应由**第一个**函数实参定死。破坏这一点的形状就是有毒的:
+
+```cpp
+// 有毒 —— `n` 与 `l` 不由第 1 个实参决定
+template<typename T, int m, int n, int l>
+Matx<T, m, n> operator*(const Matx<T, m, l>& a, const Matx<T, l, n>& b);
+
+// 有毒 —— 第二个 typename 只出现在第 2 个实参里
+template<typename T1, typename T2, int n>
+Vec<T1, n>& operator+=(Vec<T1, n>& a, const Vec<T2, n>& b);
+
+// 没问题 —— 每个形参都由第 1 个实参定死
+template<typename T, int m, int n>
+Matx<T, m, n> operator+(const Matx<T, m, n>& a, const Matx<T, m, n>& b);
+```
+
+崩溃是**按名字**触发的:一处被毒化的 `operator*` 声明,会让每个导入者里的
+每一个 `x * y` 都崩,哪怕类型完全无关。函数体本身无关紧要。
+
+**绕法**是整体推导操作数类型再加约束,而不是在形参列表里把它们拆开。
+这样保持调用兼容,跨 TU 语义也仍然成立 —— 上游那个精确匹配的
+`static inline` 更特化,在那边照样胜出:
+
+```cpp
+template<typename MA, typename MB>
+    requires pick<typename MA::value_type>
+          && __is_same(MA, typename MA::mat_type)
+          && __is_same(MB, Matx<typename MB::value_type,
+                               (int)MA::rows, (int)MA::cols>)
+inline MA& operator+=(MA& a, const MB& b);
+```
+
+跟踪于 [mcpp#256](https://github.com/mcpp-community/mcpp/issues/256)。
+`tests/e2e/150_clang_module_operator_template.sh` 是一只跑在内置 LLVM
+工具链上的金丝雀 —— 未来某次 Clang 升级修好(或再次弄坏)这一点时,
+它会显式暴露出来,而不是悄悄改变包能表达的东西。

docs/zh/05-mcpp-toml.md

@@ -663,6 +663,13 @@ mcpp cache gc --older-than 30d      # 或按"多久没用过"回收
 mcpp cache clean [--deps|--std|--all|--legacy]
 ```
 
+条目的磁盘布局是带版本的。改动布局的 mcpp 版本会**一次性作废全部旧条目**,
+所以升级后的第一次构建会重编依赖并重新填充 —— 不需要手工清理。
+2026.8.3.4 就是这样一次:条目里对象的地址现在相对**包**自身,
+而不再相对"最先填充这个条目的那个工程"的构建目录。
+`mcpp cache verify` 另外会报告任何逃出条目的记录地址,
+使这条不变量可以离线审计。
+
 ### 2.11 `[runtime]` — 主机运行时能力
 
 ```toml