feat: update to mcpp 2026.8.1.1, ship templates/, i18n READMEs, split CI per platform

.agents/skills/README.md

@@ -1,27 +1,37 @@
-# mcpplibs template Agent Skills
+# mcpplibs template — Agent Skills
 
-用于指导 Agent 理解 mcpp/mcpplibs 模块库模板、查找外部资料，并在编写或审查 Modern/Module C++ 代码时遵循 mcpp-style-ref 规范。
+Skills that help an agent understand this mcpp/mcpplibs module-library template, look things up
+upstream, and follow the mcpp-style-ref rules when writing or reviewing Modern/Module C++.
 
-## 可用技能
+## Available Skills
 
-| 技能 | 说明 |
+| Skill | Contents |
 |------|------|
-| [more-details](more-details/SKILL.md) | mcpp、mcpplibs、包索引、依赖案例、xlings 等资料入口和任务指引 |
-| [mcpp-style-ref](mcpp-style-ref/SKILL.md) | 面向 mcpp 项目的 Modern/Module C++ (C++23) 命名、模块化与实践规则 |
+| [mcpp](mcpp/SKILL.md) | The mcpp build tool: commands, `mcpp.toml` fields, project conventions, shipping `templates/` |
+| [mcpp-index](mcpp-index/SKILL.md) | The package index: finding dependencies, namespace rules, publishing this library |
+| [mcpp-style-ref](mcpp-style-ref/SKILL.md) | Modern/Module C++23 naming, module organization and practice rules |
+| [more-details](more-details/SKILL.md) | Where to look things up — this repository, mcpp docs, the index, reference libraries, xlings |
 
-## 使用方式
+Start with `more-details` when you do not know where something lives; use `mcpp` and
+`mcpp-index` for tool and packaging questions; use `mcpp-style-ref` whenever you touch
+`.cppm` / `.cpp` files.
 
-要在 Cursor 中使用，请将技能软链接或复制到项目的 `.cursor/skills/`：
+## Usage
+
+To use them in Cursor, symlink or copy the skills into the project's `.cursor/skills/`:
 
 ```bash
 mkdir -p .cursor/skills
-ln -s ../../skills/more-details .cursor/skills/more-details
-ln -s ../../skills/mcpp-style-ref .cursor/skills/mcpp-style-ref
+for s in mcpp mcpp-index mcpp-style-ref more-details; do
+    ln -s "../../.agents/skills/$s" ".cursor/skills/$s"
+done
 ```
 
-或安装为个人技能：
+Or install them as personal skills:
 
 ```bash
-ln -s /path/to/mcpp-template/.agents/skills/more-details ~/.cursor/skills/more-details
-ln -s /path/to/mcpp-style-ref/skills/mcpp-style-ref ~/.cursor/skills/mcpp-style-ref
+ln -s /path/to/mcpp-template/.agents/skills/mcpp ~/.cursor/skills/mcpp
 ```
+
+Claude Code and other agents that read `.agents/skills/` pick them up from this directory
+directly.

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

@@ -0,0 +1,90 @@
+---
+name: mcpp-index
+description: Find, add and publish mcpp packages through mcpp-index (the default package index). Use when looking up a dependency, resolving a "package not found" error, choosing a namespace, or publishing this library to the index.
+---
+
+# mcpp-index
+
+[mcpp-index](https://github.com/mcpplibs/mcpp-index) is the default package index for mcpp:
+one `pkgs/<initial>/<name>.lua` descriptor per package. Browse it online at
+**https://mcpplibs.github.io/mcpp-index/**.
+
+Two kinds of packages live there:
+
+- **Native mcpp module libraries** (`mcpplibs.*`, `nlohmann.json`, `imgui`, `opencv`, …) — the
+  upstream repository carries its own `mcpp.toml`, so the descriptor (**Form A**) declares only
+  metadata and a download address. **A library built from this template is Form A.**
+- **Third-party C/C++ libraries** under the `compat` namespace — upstream has no mcpp support,
+  so the descriptor (**Form B**) inlines the build information.
+
+## Consuming: Finding and Adding a Dependency
+
+```bash
+mcpp search <keyword>          # search the index (also refreshes it)
+mcpp add <pkg>[@<version>]     # write the dependency into mcpp.toml
+mcpp build                     # fetch and build; dependencies propagate along the chain
+mcpp index list|add|remove|update   # manage registries
+```
+
+Package identity is a pair: **`namespace` is a dotted hierarchical path, `name` is a single
+atomic segment** (`compat` + `zlib`, `mcpplibs.capi` + `lua` — never `mcpplibs` + `capi.lua`).
+
+A **bare** dependency name resolves in exactly three places, in order:
+
+1. `mcpplibs` — the default namespace
+2. `compat` — third-party C/C++ wrappers
+3. packages that declare no namespace at all
+
+Anything else must be spelled out — there is no index-wide fuzzy search by short name:
+
+```toml
+[dependencies]
+"chriskohlhoff.asio" = "1.38.1"     # dotted selector
+
+[dependencies.chriskohlhoff]        # or a namespace sub-table
+asio = "1.38.1"
+```
+
+When resolution fails: read the error (it lists the namespaces searched), then check the
+spelling against the online index, and run `xlings update` — a release tarball bundles an
+index snapshot frozen at build time, which is the usual reason a fresh version "does not
+exist".
+
+Mirrors: `mcpp self config --mirror CN` switches to the GitCode mirror; `GLOBAL` (upstream) is
+the default.
+
+## Publishing This Library to the Index
+
+```bash
+mcpp publish --dry-run      # package a tarball, hash it, print the descriptor, upload nothing
+mcpp emit xpkg -o mylib.lua # descriptor only, no packaging
+```
+
+`--dry-run` prints the remaining steps with the project's real URLs filled in:
+
+1. Tag and push — `git tag -a v<version> -m "v<version>" && git push --tags`
+2. Attach `target/dist/<name>-<version>.tar.gz` to that GitHub Release
+3. Open a PR to mcpp-index adding `pkgs/<initial>/<name>.lua`
+
+Before opening the PR, confirm `[package]` in `mcpp.toml` carries an accurate `namespace`,
+`name`, `version`, `description`, `license` and `repo` — the descriptor is generated from
+those fields, and a `repo` still pointing at the template is the classic mistake.
+
+The index's CI (`validate.yml`) lints every descriptor, checks the GLOBAL/CN mirror tables,
+and builds a small test project per package on three platforms. Reproduce the lint locally
+with `mcpp xpkg parse pkgs/<initial>/<name>.lua`.
+
+## Writing a Descriptor by Hand
+
+For anything beyond a generated Form A descriptor — a `compat` wrapper, features, a CN mirror,
+multiple majors in one package — follow the index's own end-to-end procedure rather than
+improvising:
+
+- Skill: [`add-mcpp-index-package`](https://github.com/mcpplibs/mcpp-index/blob/main/.agents/skills/add-mcpp-index-package/SKILL.md)
+- [docs/package-types.md](https://github.com/mcpplibs/mcpp-index/blob/main/docs/package-types.md) — descriptor templates for the four library shapes
+- [docs/repository-and-schema.md](https://github.com/mcpplibs/mcpp-index/blob/main/docs/repository-and-schema.md) — layout, schema cheat-sheet, `[indices]` redirection, CI behavior
+- [docs/cn-mirror.md](https://github.com/mcpplibs/mcpp-index/blob/main/docs/cn-mirror.md) — the GitCode CN mirror loop and its fallback
+- Chinese versions of all three live under [`docs/zh/`](https://github.com/mcpplibs/mcpp-index/tree/main/docs/zh)
+
+Upstream mcpp is authoritative for the descriptor field specification; the index docs are
+authoritative for repository conventions and the contribution flow.

.agents/skills/mcpp/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: mcpp
+description: Use the mcpp build tool for C++23 module projects — commands (build/test/run/add/new/publish), mcpp.toml fields, project conventions, and shipping templates/. Use when building, testing, adding dependencies, editing mcpp.toml, or scaffolding with mcpp.
+---
+
+# mcpp
+
+The build and package tool this repository is built with. mcpp is module-first C++23:
+`import std` works out of the box, toolchains install into an isolated sandbox, and
+dependencies resolve through a package index.
+
+Verified against **mcpp 2026.8.1.1**. mcpp is pre-1.0 and moves fast — when this skill and
+the tool disagree, the tool wins. Check with `mcpp --help`, `mcpp <cmd> --help`, and the
+[upstream docs](https://github.com/mcpp-community/mcpp/tree/main/docs).
+
+## Environment
+
+The mcpp version is pinned per project in `.xlings.json` and installed into the **project**
+environment:
+
+```bash
+xlings install            # install the pinned mcpp for this project
+xlings install mcpp -g    # install mcpp globally instead
+mcpp --version            # confirm which one you got
+```
+
+Never assume the mcpp on `PATH` matches the pin — check first when a build behaves oddly.
+
+## Commands
+
+| Command | Use |
+|---|---|
+| `mcpp build [--release]` | Build. Default profile is `dev` (`-O0 -g`); `--release` is opt-in |
+| `mcpp test [pattern]` | Build + run `tests/**/*.cpp`, one binary per file (`--list`, `--timeout`) |
+| `mcpp run [target] [-- args]` | Build + run a binary target |
+| `mcpp new <name>` | New package skeleton; `--template <pkg>[@ver][:<tmpl>]`, `--list-templates <pkg>` |
+| `mcpp add <pkg>[@ver]` / `mcpp remove <pkg>` | Edit dependencies in `mcpp.toml` |
+| `mcpp update [pkg]` | Re-resolve and rewrite `mcpp.lock` |
+| `mcpp search <keyword>` | Search the package index |
+| `mcpp clean [--bmi-cache]` | Remove `target/` (and optionally the build cache) |
+| `mcpp publish [--dry-run]` / `mcpp emit xpkg` | Publish to / generate a descriptor for the index |
+| `mcpp self doctor` / `mcpp self env` | Diagnose the environment; print paths and toolchain |
+
+Useful flags: `--verbose`, `--quiet`, `--offline`, `--strict` (turns manifest warnings into
+errors), `--target <triple>`.
+
+## Conventions Before Configuration
+
+mcpp infers most of a project; write config only to override it.
+
+- Sources: `src/**/*.{cppm,cpp,cc,c,S,s,asm}`.
+- `src/main.cpp` present → a **bin** target named after the package.
+- Only `src/*.cppm`, no `main.cpp` → a **lib** target named after the package.
+- Lib-root module: `src/<last segment of the package name>.cppm`; override with `[lib] path`.
+- Tests: `tests/**/*.cpp`, discovered by `mcpp test`, one binary per file. Test files contain
+  `TEST(...)` cases only — **never their own `main()`** (gtest_main is linked in).
+- Standard: `c++23` by default, set via `[package] standard` — never through `cxxflags`.
+  The standard is module-graph-global and part of the cache key.
+
+## mcpp.toml
+
+```toml
+[package]
+namespace   = "mcpplibs"      # namespace + name form the package identity
+name        = "mylib"
+version     = "0.1.0"
+standard    = "c++23"         # c++20 | c++23 (default) | c++26
+description = "..."
+license     = "Apache-2.0"
+repo        = "https://github.com/mcpplibs/mylib"
+
+[targets.mylib]               # only when overriding inference
+kind = "lib"                  # bin | lib | shared
+
+[lib]
+path = "src/mylib.cppm"       # only when overriding the lib-root convention
+
+[build]
+include_dirs  = ["include"]
+defines       = ["FOO=1"]     # bare names; reach every TU including module scans
+default-profile = "release"   # project default when no --profile/--release is passed
+
+[dependencies]                # runtime deps
+cmdline = "0.0.2"             # bare name: searched in mcpplibs, then compat, then no-namespace
+
+[dependencies.mcpplibs]       # namespace sub-table (preferred for several from one org)
+tinyhttps = "0.2.3"
+
+[dev-dependencies]            # test-only; `mcpp build` ignores these
+gtest = "1.15.2"
+
+[toolchain]
+default = "gcc@16.1.0"        # pin only when the project genuinely needs it
+```
+
+Other sections, when you need them (see
+[docs/05-mcpp-toml.md](https://github.com/mcpp-community/mcpp/blob/main/docs/05-mcpp-toml.md)):
+`[features]` (additive, Cargo-style), `[feature-deps.<name>]`, `[profile.<name>]`,
+`[target.'cfg(...)']` for platform-conditional deps/flags, `[generated_files]`,
+`[build] flags` for per-glob compile flags.
+
+Dependency forms: `"1.2.3"` · `"^1.2"` · `"~1.2"` · `">=1.0, <2.0"` ·
+`{ path = "../mylib" }` · `{ git = "...", tag = "v1.0.0" }` ·
+`{ version = "0.0.3", features = ["docking"] }`.
+
+**Namespace rule:** a bare name resolves in exactly three places, in order — `mcpplibs`,
+`compat` (third-party C/C++ wrappers), then packages that declare no namespace. Any other
+namespace must be written out: `"chriskohlhoff.asio" = "1.38.1"` or a
+`[dependencies.chriskohlhoff]` sub-table.
+
+## Modules
+
+- `import std;` — do not `#include <print>` etc. in module code.
+- `.cppm` is the module interface; `.cpp` holds separated implementation.
+- Import a dependency where it is used. Do **not** `export import` a third-party module from
+  your root module unless the public API genuinely hands out that dependency's types.
+- Do not hand-write module dependency order — mcpp scans `export module` / `import`
+  declarations (P1689) and builds the graph itself.
+
+## Shipping templates/
+
+A package ships project scaffolds by adding `templates/<name>/`:
+
+```text
+templates/<name>/template.toml   # description, default = true (at most one), post_message
+templates/<name>/**.in           # rendered, then the .in suffix is stripped
+templates/<name>/**              # everything else copied verbatim
+```
+
+Placeholders — the whole vocabulary: `{{project.name}}`, `{{self.name}}`, `{{self.version}}`.
+File *names* are not rendered, only contents. Templates are pure data: no hooks, no scripts.
+Consumers use `mcpp new <proj> --template <pkg>[:<tmpl>]` and
+`mcpp new --list-templates <pkg>`.
+
+## Troubleshooting
+
+- Wrong mcpp version → check `.xlings.json` vs `mcpp --version`; re-run `xlings install`.
+- Dependency not found → `mcpp search <name>`; check the namespace rule above; `xlings update`
+  refreshes a stale index snapshot.
+- Stale build / BMI weirdness → `mcpp clean`, or `mcpp clean --bmi-cache` for the module cache.
+- Environment trouble → `mcpp self doctor`, `mcpp self env`.
+- An error code in the output → `mcpp self explain <CODE>`.
+
+## Further Reading
+
+- Docs index: https://github.com/mcpp-community/mcpp/tree/main/docs (`zh/` for Chinese)
+- Getting started: `docs/00-getting-started.md` · Examples: `docs/01-examples.md`
+- `mcpp.toml` guide: `docs/05-mcpp-toml.md` · Workspaces: `docs/06-workspace.md`
+- Toolchains: `docs/03-toolchains.md` · Packaging: `docs/02-pack-and-release.md`
+- Package index: see the [`mcpp-index`](../mcpp-index/SKILL.md) skill