fix(ci): key the registry cache off the git index; add English README/docs as the default (#137)

* fix(ci): compute the registry cache key from the git index, not hashFiles

The windows leg of run 30433315359 went red after every one of its 42
workspace members passed:

  The template is not valid. .github/workflows/validate.yml (Line: 272,
  Col: 16): hashFiles('pkgs/**/*.lua, tests/**,
  .github/workflows/validate.yml') couldn't finish within 120 seconds

hashFiles() globs the WORKING TREE, and actions/cache re-evaluates its
`key` in the post (save) step — i.e. AFTER the build. By then `tests/**`
no longer matches the 82 tracked sources but the build output under
tests/examples/*/target and .mcpp: 42k files / 2.1 GB in a local run,
since .gitignore does not apply to hashFiles. Hashing that blew past the
runner's 120s template-evaluation cap on the slowest filesystem, which is
why only windows failed while linux and macos squeaked under it.

Compute the key once, before anything builds, from `git ls-files -s`: it
reads the INDEX, so it sees exactly the tracked inputs and never build
output, and it reports blob SHAs git already holds rather than reading
file content (~50ms). Freezing it in the job env also guarantees the save
step keys on the same string the restore step used.

Also add README.zh-CN.md to the PR trigger paths, alongside README.md.

* docs: add English README/docs and make English the default

README.md and docs/ were Chinese-only. Adopt the layout mcpp upstream
already uses — English at the canonical path, Chinese one level down:

  README.md            (English, default)   README.zh-CN.md
  docs/*.md            (English, default)   docs/zh/*.md

The Chinese files move with `git mv`, so history follows them, and every
page carries a language switcher at the top.

Follow-through so nothing dangles:
- .agents/skills/add-mcpp-index-package/SKILL.md is Chinese, so its
  reference links now point at docs/zh/, and its "update the README" step
  names both files.
- publish_mcpp_index.sh ships README.zh-CN.md next to README.md, or the
  unpacked artifact's language switch would point at nothing.
- Both language versions of docs/repository-and-schema.md document the
  new cache-key step and the corrected CI trigger list.

Author: Sunrisepeak

.agents/skills/add-mcpp-index-package/SKILL.md

@@ -16,11 +16,12 @@ description: Use when adding a new third-party library/package to the mcpp-index
 - `.agents/docs/2026-06-28-add-eigen-plan.md`(header-only 库及 source-gated `blas` feature)。
 - 既有 PR:#48(cjson 与 nlohmann.json)、#50(eigen)。
 
-配套参考文档位于仓库 `docs/` 目录,供人工与 agent 共同使用,可按需查阅:
+配套参考文档位于仓库 `docs/` 目录(英文为默认版本,中文版在 `docs/zh/`,内容对等),供人工与 agent 共同使用,
+可按需查阅(下列链接指向中文版):
 
-- [docs/package-types.md](../../../docs/package-types.md) —— 四种库形态的描述符模板与样例路径。
-- [docs/cn-mirror.md](../../../docs/cn-mirror.md) —— CN 镜像闭环,含无 `mcpp-res` 权限时的回退方案。
-- [docs/repository-and-schema.md](../../../docs/repository-and-schema.md) —— 仓库结构、schema、CI 行为、关键文件与注意事项。
+- [docs/zh/package-types.md](../../../docs/zh/package-types.md) —— 四种库形态的描述符模板与样例路径。
+- [docs/zh/cn-mirror.md](../../../docs/zh/cn-mirror.md) —— CN 镜像闭环,含无 `mcpp-res` 权限时的回退方案。
+- [docs/zh/repository-and-schema.md](../../../docs/zh/repository-and-schema.md) —— 仓库结构、schema、CI 行为、关键文件与注意事项。
 
 ## 适用范围
 
@@ -48,12 +49,12 @@ description: Use when adding a new third-party library/package to the mcpp-index
      **纯头文件 / C 源码 / 自带 `.cppm` 模块 / 含可选组件(可实现 feature)** 中的何种形态。
    - 计算 `sha256sum`,并**重复计算两次以确认稳定**。GitLab 等部分归档源会重新打包,导致 sha 漂移,进而使 CI
      经 GLOBAL 拉取时校验失败。
-2. **确定形态并选择模板**:详见 [docs/package-types.md](../../../docs/package-types.md)。四类形态为:C 源码 compat、
+2. **确定形态并选择模板**:详见 [docs/zh/package-types.md](../../../docs/zh/package-types.md)。四类形态为:C 源码 compat、
    header-only、C++23 module(generated wrapper)、外部 Form-A 模块仓。
 3. **建立 CN 镜像**:使用 `gtc` 在 gitcode `mcpp-res` 组织下建仓并发布 release,上传**与 GLOBAL 相同的 tarball**,
    以保证字节一致(sha 相同)。**在不具备 `mcpp-res` 写权限时**,不应构造镜像表,而应使用纯字符串形式
    `url = "<GLOBAL 上游 release>"`(lint 允许此形式,CN 用户将回退至上游源),镜像由维护者后续补充。详见
-   [docs/cn-mirror.md](../../../docs/cn-mirror.md)。
+   [docs/zh/cn-mirror.md](../../../docs/zh/cn-mirror.md)。
 4. **编写描述符** `pkgs/<x>/<name>.lua`。
    - 目录 `<x>` **取完整包名首字母**(`compat.eigen` 对应 `pkgs/c/`,`nlohmann.json` 对应 `pkgs/n/`),
      而非短名。放置错误将导致本地 path index 报 `not found in local index`。
@@ -70,11 +71,11 @@ description: Use when adding a new third-party library/package to the mcpp-index
      编译为 no-op `main`(`#ifdef __linux__ … #else int main(){return 0;} #endif` 模式)。
    - 如需测试 feature,依赖采用长式声明 `name = { version = "…", features = ["…"] }`。
 7. **本地验证**(使用与 CI 相同版本的 mcpp,详见下文“本地验证”)。必须实际执行 `mcpp test -p <member>` 并通过。
-8. **更新 README**:在对应分类表中新增一条记录。
+8. **更新 README**:在对应分类表中新增一条记录 —— `README.md`(英文,默认)与 `README.zh-CN.md`(中文)两份都要更新。
 9. **撰写设计文档** `.agents/docs/<YYYY-MM-DD>-add-<lib>-plan.md`,记录形态判定、镜像、feature 评估、验证结论
    与注意事项。
 10. **本地 lint**:在本地复现 `validate.yml` 的 lint 检查(语法、必填字段、无前导 v、镜像表校验)。详见
-    [docs/repository-and-schema.md](../../../docs/repository-and-schema.md)。
+    [docs/zh/repository-and-schema.md](../../../docs/zh/repository-and-schema.md)。
 11. **提交变更**:由 `main` 切出新分支,依次 commit、push、开 PR(不应直接推送 `main`)。PR 描述应载明形态、镜像、
     feature 与验证结论。
 12. **确认 CI 通过**:`workspace (linux|macos|windows)` 的选择性成员测试应仅选中本库对应成员并通过

.github/workflows/validate.yml

@@ -5,7 +5,7 @@ on:
     # mcpp.toml and index.toml carry the workspace member list, the inherited
     # [indices] redirect and the client version floor — a change to any of them
     # can break every member, so they gate the run like the descriptors do.
-    paths: ["pkgs/**/*.lua", "tests/**", "README.md", "mcpp.toml", "index.toml", ".github/workflows/validate.yml"]
+    paths: ["pkgs/**/*.lua", "tests/**", "README.md", "README.zh-CN.md", "mcpp.toml", "index.toml", ".github/workflows/validate.yml"]
   push:
     branches: [main]
   schedule:
@@ -263,13 +263,37 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
+      # The cache key is computed ONCE, here, instead of inline in the cache
+      # step. `hashFiles()` globs the WORKING TREE, and actions/cache
+      # re-evaluates its `key` in the post (save) step — i.e. AFTER the build,
+      # when `tests/**` no longer matches 80-odd tracked sources but tens of
+      # thousands of build-output files under tests/examples/*/target and
+      # .mcpp (multi-GB; .gitignore does not apply to hashFiles). Hashing that
+      # tree blew past the runner's 120s template-evaluation cap on windows
+      # and failed an otherwise all-green job:
+      #   "hashFiles('pkgs/**/*.lua, tests/**, .github/workflows/validate.yml')
+      #    couldn't finish within 120 seconds"
+      # `git ls-files -s` reads the INDEX, so it sees exactly the tracked
+      # inputs, never build output, and reports blob SHAs git already has —
+      # no file content is read at all. Freezing the result in the job env
+      # also guarantees the save step keys on the same string the restore
+      # step used, no matter what the build left behind.
+      - name: Compute registry cache key
+        shell: bash
+        run: |
+          # git hash-object rather than sha256sum/cut: git is already a hard
+          # requirement here (checkout ran), coreutils on the windows leg is
+          # only a Git-Bash convenience.
+          h=$(git ls-files -s -- 'pkgs/**/*.lua' 'tests/**' '.github/workflows/validate.yml' \
+              | git hash-object --stdin)
+          echo "REGISTRY_CACHE_KEY=mcpp-registry-${{ runner.os }}-${{ env.MCPP_EFFECTIVE }}-$h" >> "$GITHUB_ENV"
       - name: Restore mcpp registry cache
         uses: actions/cache@v4
         with:
           # Holds toolchains AND the built compat packages (data/xpkgs), so a
           # repeat `mcpp test` rebuilds little.
           path: ~/.mcpp/registry
-          key: mcpp-registry-${{ runner.os }}-${{ env.MCPP_EFFECTIVE }}-${{ hashFiles('pkgs/**/*.lua', 'tests/**', '.github/workflows/validate.yml') }}
+          key: ${{ env.REGISTRY_CACHE_KEY }}
           restore-keys: |
             mcpp-registry-${{ runner.os }}-${{ env.MCPP_EFFECTIVE }}-
       - name: Download mcpp