docs: add docs/, README example table + agent prompt; skill mirror fallback

- Move the skill's reference files into a human-facing docs/ folder (single
  source): package-types.md, cn-mirror.md, repository-and-schema.md (+ index
  docs/README.md). SKILL.md now links to ../../../docs/*; the skill dir keeps
  just SKILL.md (the agent SOP).
- README: add a "参考示例" table linking typical descriptors by shape
  (Form-A module / C-source compat / header-only / module wrapper), a
  copy-paste agent prompt that drives the skill end-to-end, and links to docs/.
- skill + docs: document the no-`mcpp-res`-permission fallback — use a
  plain-string upstream `url` (lint forbids a {GLOBAL,CN} table whose CN isn't
  gitcode/mcpp-res; plain strings are unconstrained). Real precedent:
  pkgs/t/tensorvia-cpu.lua.
- skill step 1 now distinguishes the two sources: a third-party upstream lib
  vs. the user's own mcpp-based library (Form A, lighter research).

Author: Sunrisepeak

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

@@ -14,26 +14,33 @@ 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)。
 
-> 配套参考文件(按需读):
-> - [package-types.md](package-types.md) —— 四种库形态的描述符模板 + 真实样例路径
-> - [cn-mirror.md](cn-mirror.md) —— gtc / gitcode CN 镜像闭环
-> - [references.md](references.md) —— 仓库结构、schema、CI、关键文件、踩坑清单
+> 配套参考文件(在仓库 `docs/` 下,人/agent 共用,按需读):
+> - [docs/package-types.md](../../../docs/package-types.md) —— 四种库形态的描述符模板 + 真实样例路径
+> - [docs/cn-mirror.md](../../../docs/cn-mirror.md) —— gtc / gitcode CN 镜像闭环(含无 mcpp-res 权限的回退)
+> - [docs/repository-and-schema.md](../../../docs/repository-and-schema.md) —— 仓库结构、schema、CI、关键文件、踩坑清单
 
 ## 何时用 / 不用
-- **用**:把一个新的第三方库(或新版本)加进 mcpp-index。
+- **用**:把一个新库(或新版本)加进 mcpp-index。两种来源都适用:
+  - **(a) 第三方上游库** —— 自己没有 mcpp 支持(如 cJSON / Eigen / nlohmann),由本仓以 `compat` 形态适配。
+  - **(b) 用户基于 mcpp 开发的库** —— 上游已经是 mcpp 工程(自带 `mcpp.toml`、`mcpp emit xpkg` 产出描述符、自有 release),
+    要登记进索引(如 `mcpplibs.*`、`tensorvia-cpu`)。这类多是 **Form A**:描述符只声明元数据 + 下载地址,无需内联构建。
 - **不用**:改 mcpp 本体、改 xlings 引擎、纯文档。那些不在本仓。
 
 ## 总流程(12 步)
 
 按顺序做;每步的细节进对应参考文件。建议用 todo 跟踪。
 
-1. **调研上游**(最关键,决定形态)
+1. **调研来源与形态**(最关键,决定模板)
+   - **先分清来源**:是 (a) 第三方上游库,还是 (b) 用户自己的 mcpp 库?
+     - (b) 自有 mcpp 库:形态已定(Form A,模块库),版本/release 上游已有 → 本步很轻,直接拿上游 `mcpp emit xpkg` 的描述符
+       或照 `pkgs/t/tensorvia-cpu.lua` 写;重点落在镜像 + 登记 + 验证。
+     - (a) 第三方库:需判形态(下面)。
    - 上游仓库、**最新 tag/版本**(`git ls-remote --tags <repo>` → `sort -V | tail`;注意大版本跳跃,如 Eigen 3.4 → 5.x)。
    - License、源码布局:下 tarball,`tar -tzf` 看顶层 wrap 目录 + 子目录;判断是
      **纯头 / C 源码 / 自带 `.cppm` 模块 / 有可选组件(可做 feature)**。
    - 算 `sha256sum`,并**复算两次确认稳定**(GitLab/部分归档会重新打包导致 sha 漂移 → CI 用 GLOBAL 拉取会校验失败)。
-2. **定形态 → 选模板**:见 [package-types.md](package-types.md)。四类:C-source compat / header-only / C++23 module(generated wrapper)/ 外部 Form-A 模块仓。
-3. **建 CN 镜像**:`gtc` 在 gitcode `mcpp-res` org 下建仓 + 发 release,上传**与 GLOBAL 同一个 tarball**(保证 byte-identical → 同 sha)。见 [cn-mirror.md](cn-mirror.md)。
+2. **定形态 → 选模板**:见 [docs/package-types.md](../../../docs/package-types.md)。四类:C-source compat / header-only / C++23 module(generated wrapper)/ 外部 Form-A 模块仓。
+3. **建 CN 镜像**:`gtc` 在 gitcode `mcpp-res` org 下建仓 + 发 release,上传**与 GLOBAL 同一个 tarball**(保证 byte-identical → 同 sha)。**没有 `mcpp-res` 写权限时**:不要写镜像表,直接用 plain-string `url = "<GLOBAL 上游 release>"`(lint 允许;CN 用户回落上游),留给维护者后补镜像 —— 详见 [docs/cn-mirror.md](../../../docs/cn-mirror.md)。
 4. **写描述符** `pkgs/<x>/<name>.lua`
    - ⚠️ **目录 `<x>` = 完整包名首字母**(`compat.eigen` → `pkgs/c/`,`nlohmann.json` → `pkgs/n/`),**不是短名**。放错本地 path index 会 `not found in local index`。
    - 三平台 `xpm`(linux/macosx/windows),每个版本 `url = { GLOBAL=…, CN=… }` + `sha256`。
@@ -45,7 +52,7 @@ description: Use when adding a new third-party library/package to the mcpp-index
 7. **本地实测**(用与 CI 同版本的 mcpp):见下"本地验证"。必须真跑过 `mcpp build && mcpp run` 绿。
 8. **README** 在对应表(mcpplibs 模块库 / 独立模块库 / 第三方 C/C++ 库)加一行。
 9. **设计文档** `.agents/docs/<YYYY-MM-DD>-add-<lib>-plan.md`,记录形态判断、镜像、feature 评估、实测结论、踩坑。
-10. **本地 lint**:模拟 `validate.yml` 的 lint(语法 / 必填字段 / 无前导 v / mirror 检查)。见 [references.md](references.md)。
+10. **本地 lint**:模拟 `validate.yml` 的 lint(语法 / 必填字段 / 无前导 v / mirror 检查)。见 [docs/repository-and-schema.md](../../../docs/repository-and-schema.md)。
 11. **分支 → commit → push → PR**(从 `main` 切新分支;别直接推 main)。PR 描述写清形态、镜像、feature、实测。
 12. **盯 CI 绿**:`detect` 应只选中本库的 example(`smoke-full-linux`/`portable` 显示 `skipping`),`smoke-examples (<short>)` 绿;`mirror-cn-reachable` 覆盖新 CN url。合并交维护者。
 

README.md

@@ -22,14 +22,38 @@ mcpp self config --mirror CN   # 切到国内镜像(默认走 GLOBAL 上游源)
 
 收录两类包:
 
-- **原生 mcpp 模块库** — 以 C++23 模块发布、`import` 即用(如 `mcpplibs.*`、`nlohmann.json`、`imgui`)。
-  上游多自带 `mcpp.toml`,描述文件只声明元数据与下载地址。
-- **第三方 C/C++ 库(`compat`)** — 上游无 mcpp 支持,在描述文件里内联构建信息:header-only、纯 C 源码、
+- **原生 mcpp 模块库** — C++23 模块、`import` 即用(`mcpplibs.*`、`nlohmann.json`、`imgui`,以及用户自己基于
+  mcpp 开发、要登记进索引的库如 `tensorvia-cpu`)。上游多自带 `mcpp.toml`,描述文件(Form A)只声明元数据 + 下载地址。
+- **第三方 C/C++ 库(`compat`)** — 上游无 mcpp 支持,描述文件(Form B)内联构建信息:header-only / 纯 C 源码 /
   C++23 module wrapper 等不同形态,可选组件经 `features` 门控,并配 GitCode CN 镜像。
 
-**新增一个包** → 参考 agent skill [`add-mcpp-index-package`](.agents/skills/add-mcpp-index-package/SKILL.md):
-完整 SOP —— 四种库形态模板、`gtc` CN 镜像闭环、`features` 门控、本地 + CI 验证。字段规范见
-[mcpp 扩展字段文档](https://github.com/mcpp-community/mcpp/blob/main/docs/04-schema-xpkg-extension.md)。
+### 参考示例(`.lua` 描述符)
+
+| 形态 | 示例 |
+|------|------|
+| 原生模块库(Form A) | [`mcpplibs.tinyhttps`](pkgs/t/tinyhttps.lua) · [`tensorvia-cpu`](pkgs/t/tensorvia-cpu.lua) |
+| C 源码 compat(+ `features`) | [`compat.cjson`](pkgs/c/compat.cjson.lua) · [`compat.zlib`](pkgs/c/compat.zlib.lua) |
+| header-only(+ `features`) | [`compat.eigen`](pkgs/c/compat.eigen.lua) |
+| C++23 module wrapper | [`nlohmann.json`](pkgs/n/nlohmann.json.lua) |
+
+### 新增一个包
+
+照 agent skill [`add-mcpp-index-package`](.agents/skills/add-mcpp-index-package/SKILL.md) 走完整 SOP。
+最快的方式 —— 把下面这段丢给 agent(Claude Code 等),让它**用该 skill** 完成描述文件与全流程:
+
+```text
+参考本仓 skill `.agents/skills/add-mcpp-index-package`,把 <库名 / 仓库URL> @<版本> 收录进 mcpp-index:
+判形态 → 配 CN 镜像(无 mcpp-res 权限则用 plain-string 上游 url) → 写 pkgs/<首字母>/<包名>.lua
+→ 加 tests/examples/<库>/ 最小工程 → 用与 CI 同版本的 mcpp 本地 `mcpp build && run` 实测
+→ 更新 README/在线索引 → 开 PR 等 CI 绿。
+```
+
+详细文档(人 / agent 共用,在 [`docs/`](docs/) 下):
+
+- [库形态与描述符模板](docs/package-types.md) — C 源 / header-only / 模块 / 外部 Form-A 四类模板 + 样例
+- [CN 镜像闭环](docs/cn-mirror.md) — `gtc` / gitcode 操作 + **无 `mcpp-res` 权限的回退**
+- [仓库结构 / schema / CI](docs/repository-and-schema.md) — 字段速查、选跑机制、本地 lint
+- 字段规范:[mcpp 扩展字段文档](https://github.com/mcpp-community/mcpp/blob/main/docs/04-schema-xpkg-extension.md)
 
 > 开 PR 后 `validate` 自动 lint + 按改动库选跑示例;合入后 `deploy-site` 发布到浏览站。
 

docs/README.md

@@ -0,0 +1,13 @@
+# mcpp-index 文档
+
+给本仓贡献者(人 / agent 共用)的参考文档。新增一个包的**端到端 SOP** 在 agent skill
+[`add-mcpp-index-package`](../.agents/skills/add-mcpp-index-package/SKILL.md);下面是各环节的细节参考。
+
+| 文档 | 内容 |
+|------|------|
+| [package-types.md](package-types.md) | 四种库形态(C 源 compat / header-only / C++23 module wrapper / 外部 Form-A 模块仓)的描述符模板 + 真实样例 |
+| [cn-mirror.md](cn-mirror.md) | GitCode `mcpp-res` CN 镜像闭环(`gtc` 工具、闭环校验、踩坑),含**无 `mcpp-res` 写权限时的回退**(plain-string 上游 url) |
+| [repository-and-schema.md](repository-and-schema.md) | 仓库布局、描述符 schema 速查、`validate.yml` CI 行为、一把梭本地 lint、真实案例表 |
+
+> 包的**字段规范**(`mcpp = { … }` 扩展)以上游为准:
+> [mcpp docs/04-schema-xpkg-extension.md](https://github.com/mcpp-community/mcpp/blob/main/docs/04-schema-xpkg-extension.md)。

…ills/add-mcpp-index-package/cn-mirror.md docs/cn-mirror.md.agents/skills/add-mcpp-index-package/cn-mirror.md renamed to docs/cn-mirror.md .agents/skills/add-mcpp-index-package/cn-mirror.md renamed to docs/cn-mirror.md

@@ -9,6 +9,26 @@
 - CN 资产公网 URL 约定:
   `https://gitcode.com/mcpp-res/<slug>/releases/download/<ver>/<slug>-<ver>.<ext>`
 
+## 没有 `mcpp-res` 写权限时的回退
+
+建镜像需要 gitcode `mcpp-res` org 的写权限(token)。**拿不到时不要硬凑镜像表** —— lint
+(`check_mirror_urls.lua`)强制:`url` 一旦写成表,`CN` **必须**是 `https://gitcode.com/mcpp-res/…`,
+所以 `{ GLOBAL=上游, CN=上游 }` 会直接挂 lint。正确回退是**用 plain-string 单串 url**(只填上游 release),
+lint 对纯字符串 url 不做镜像约束:
+
+```lua
+-- 回退:无 CN 镜像,GLOBAL/CN 都等价于上游 release(单串即可)
+["0.1.1"] = { url = "https://github.com/<owner>/<repo>/releases/download/v0.1.1/<repo>-0.1.1.tar.gz",
+              sha256 = "…" },
+```
+
+- CN 用户会回落到上游源(慢一点但可用),功能不受影响。
+- 真实先例:`pkgs/t/tensorvia-cpu.lua`(用户自有 mcpp 库,无 CN 镜像,三平台都是上游单串 url)。
+- 后续拿到权限、或由维护者补上镜像后,再把该版本的 `url` 改成 `{ GLOBAL=…, CN=… }` 表即可(sha256 不变)。
+
+> 想表达「GLOBAL 和 CN 都走上游」就用上面的单串写法,**不要**写成 `{GLOBAL=x, CN=x}` 表(过不了 CN 必须指向
+> gitcode 的 lint)。
+
 ## gtc 工具
 
 `gtc`(`tools/gtc`,亦在 `~/.local/bin/gtc`,python,gitcode API v5)。Token 在