From 8cfb97435819d343b5f536029018f38e76053eff Mon Sep 17 00:00:00 2001
From: speak-agent <248744407+speak-agent@users.noreply.github.com>
Date: Sat, 24 Oct 2026 03:49:51 +0900
Subject: [PATCH 1/3] docs: checkpoint mwrap usage and package template
 guidance

---
 .agents/skills/mcpp-usage/SKILL.md | 26 +++++++++++++++++++++++++-
 docs/01-getting-started.md         |  9 +++++++++
 2 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/.agents/skills/mcpp-usage/SKILL.md b/.agents/skills/mcpp-usage/SKILL.md
index 4ca8f052a..fb01db918 100644
--- a/.agents/skills/mcpp-usage/SKILL.md
+++ b/.agents/skills/mcpp-usage/SKILL.md
@@ -72,6 +72,30 @@ license = "Apache-2.0"
 
 ## mcpp.toml 配置
 
+### 传统头文件库的模块化封装
+
+`mcpplibs.mwrap.<库名>` 为传统 C/C++ 库提供模块入口；API namespace 保留上游，例如
+`import mcpplibs.mwrap.opencv.core;` 后仍使用 `cv::Mat`。包版本对齐上游，封装修订最多追加一个数字尾号。
+具体已发布的版本/feature 先查索引，不把文档中的候选库当已发布包。
+
+每个新建或重构的 -m 库提供包自带快捷模板：
+
+```bash
+mcpp new vision --template mcpplibs.mwrap.opencv@5.0.0.1
+mcpp new --list-templates mcpplibs.mwrap.opencv@5.0.0.1
+```
+
+模板语法为 `[namespace.]name[@version][:template]`，只有一个默认模板时可以省略模板名。
+包模板中的 `{{self.name}}` 是完整包选择器，应用 `"{{self.name}}"` 作为单个依赖 key，
+不要放到另一层 namespace 表下。模板必须实际创建、构建、运行，而不只做字符串检查。
+
+feature 是加法并集；消费者当前不能关闭依赖包的默认 features。`--features` 增加能力，不代表排除其他能力。
+因此可选大依赖应由包作者显式门控。模块可导入不等于实际后端已启用，窗口/推理/设备能力需分别验证。
+宏不能经 import 传递；`.macros` 只提供可保持语义的常量/函数映射，原始宏仍需兼容头。
+
+维护规范与包装流程见 [mcpp-index mwrap 规范](https://github.com/mcpplibs/mcpp-index/blob/main/docs/mwrap.md)。
+修改普通消费者项目时按现有包契约使用，不自动替用户迁移其他依赖。
+
 ```toml
 [package]
 name = "myapp"
@@ -88,7 +112,7 @@ gtest = "1.15.2"            # 仅测试使用；SemVer: ^, ~, 范围, 精确
 default = "gcc@16.1.0"
 ```
 
-更多配置：https://github.com/mcpp-community/mcpp/blob/main/docs/05-mcpp-toml.md
+更多配置：https://github.com/mcpp-community/mcpp/blob/main/docs/04-mcpp-toml.md
 
 ## 工具链
 
diff --git a/docs/01-getting-started.md b/docs/01-getting-started.md
index 1459d5511..a26c9968c 100644
--- a/docs/01-getting-started.md
+++ b/docs/01-getting-started.md
@@ -118,6 +118,15 @@ automatically uses the package's only template when none is explicitly marked.
 Multiple templates without one default are an error that points to
 `--list-templates`. There is no separate `--variant` vocabulary.
 
+Module wrappers for traditional C/C++ header libraries use the
+`mcpplibs.mwrap.<library>` package/module namespace, while preserving the
+upstream API namespace: importing an OpenCV wrapper still gives `cv::Mat`.
+Each newly published or refactored `-m` wrapper ships a runnable package template.
+Look up the package's published version before using its exact template selector;
+a candidate documented in a library PR may not be in the released index yet.
+See the [wrapper specification](https://github.com/mcpplibs/mcpp-index/blob/main/docs/mwrap.md)
+for the naming, version, feature and macro contract.
+
 The package identity, version, and template are fully resolved before the
 destination is committed. A failed download, render, hook, or validation leaves
 no half-created project directory.

From 968089769f9c1e1f1a454f8831c9dd450653a63a Mon Sep 17 00:00:00 2001
From: speak-agent <248744407+speak-agent@users.noreply.github.com>
Date: Sat, 24 Oct 2026 03:51:15 +0900
Subject: [PATCH 2/3] docs: align bilingual wrapper template guidance

---
 docs/01-getting-started.md    | 14 ++++++--------
 docs/zh/01-getting-started.md |  5 +++++
 2 files changed, 11 insertions(+), 8 deletions(-)

diff --git a/docs/01-getting-started.md b/docs/01-getting-started.md
index a26c9968c..6b549dd90 100644
--- a/docs/01-getting-started.md
+++ b/docs/01-getting-started.md
@@ -118,14 +118,12 @@ automatically uses the package's only template when none is explicitly marked.
 Multiple templates without one default are an error that points to
 `--list-templates`. There is no separate `--variant` vocabulary.
 
-Module wrappers for traditional C/C++ header libraries use the
-`mcpplibs.mwrap.<library>` package/module namespace, while preserving the
-upstream API namespace: importing an OpenCV wrapper still gives `cv::Mat`.
-Each newly published or refactored `-m` wrapper ships a runnable package template.
-Look up the package's published version before using its exact template selector;
-a candidate documented in a library PR may not be in the released index yet.
-See the [wrapper specification](https://github.com/mcpplibs/mcpp-index/blob/main/docs/mwrap.md)
-for the naming, version, feature and macro contract.
+A package template can use a module wrapper for a traditional header library.
+The module name and the C++ API namespace are independent: importing a wrapper
+does not rename the upstream types or functions. Use the package's published
+identity and version when selecting its template. The
+[wrapper specification](https://github.com/mcpplibs/mcpp-index/blob/main/docs/mwrap.md)
+documents the `mcpplibs.mwrap` naming and interface contract.
 
 The package identity, version, and template are fully resolved before the
 destination is committed. A failed download, render, hook, or validation leaves
diff --git a/docs/zh/01-getting-started.md b/docs/zh/01-getting-started.md
index 4749fe8fa..36fcf1a2d 100644
--- a/docs/zh/01-getting-started.md
+++ b/docs/zh/01-getting-started.md
@@ -115,6 +115,11 @@ mcpp new --list-templates ocornut.imgui@1.92.8
 那个唯一的模板。存在多个模板却没有默认值是一个错误，会指向
 `--list-templates`。没有另一套 `--variant` 词汇。
 
+包模板可以使用传统头文件库的模块化封装。模块名与 C++ API namespace 相互独立：
+import 封装模块不会重命名上游类型和函数。选择模板时使用该包已发布的身份与版本。
+[封装规范](https://github.com/mcpplibs/mcpp-index/blob/main/docs/mwrap.md)
+记录了 `mcpplibs.mwrap` 的命名和接口约定。
+
 包身份、版本与模板会在提交目标目录之前全部解析完成。下载、渲染、hook 或
 校验失败时，不会留下一个半成品的工程目录。
 

From 7d424b41ac76c7c6fb47f57c3b12f9b6aab29bb4 Mon Sep 17 00:00:00 2001
From: speak-agent <248744407+speak-agent@users.noreply.github.com>
Date: Sat, 24 Oct 2026 03:54:48 +0900
Subject: [PATCH 3/3] docs: distinguish dependency default opt-out from root
 CLI features

---
 .agents/skills/mcpp-usage/SKILL.md      |  5 +++--
 docs/06-features-and-capabilities.md    | 17 +++++++++++++----
 docs/zh/06-features-and-capabilities.md | 16 ++++++++++++----
 3 files changed, 28 insertions(+), 10 deletions(-)

diff --git a/.agents/skills/mcpp-usage/SKILL.md b/.agents/skills/mcpp-usage/SKILL.md
index fb01db918..e9f599b2d 100644
--- a/.agents/skills/mcpp-usage/SKILL.md
+++ b/.agents/skills/mcpp-usage/SKILL.md
@@ -89,8 +89,9 @@ mcpp new --list-templates mcpplibs.mwrap.opencv@5.0.0.1
 包模板中的 `{{self.name}}` 是完整包选择器，应用 `"{{self.name}}"` 作为单个依赖 key，
 不要放到另一层 namespace 表下。模板必须实际创建、构建、运行，而不只做字符串检查。
 
-feature 是加法并集；消费者当前不能关闭依赖包的默认 features。`--features` 增加能力，不代表排除其他能力。
-因此可选大依赖应由包作者显式门控。模块可导入不等于实际后端已启用，窗口/推理/设备能力需分别验证。
+feature 是加法并集；消费者可在依赖声明中使用 `default-features = false` 关闭该边的默认集合，
+显式 features 仍会启用，其他依赖边的请求不会被取消。根项目没有 `--no-default-features` 命令行选项。
+可选大依赖由包作者显式门控。模块可导入不等于实际后端已启用，窗口/推理/设备能力需分别验证。
 宏不能经 import 传递；`.macros` 只提供可保持语义的常量/函数映射，原始宏仍需兼容头。
 
 维护规范与包装流程见 [mcpp-index mwrap 规范](https://github.com/mcpplibs/mcpp-index/blob/main/docs/mwrap.md)。
diff --git a/docs/06-features-and-capabilities.md b/docs/06-features-and-capabilities.md
index 8a86f2e83..dcf94d840 100644
--- a/docs/06-features-and-capabilities.md
+++ b/docs/06-features-and-capabilities.md
@@ -556,10 +556,19 @@ statement: private keeps the headers off a consumer's search path, and
 
 ## Current limitations
 
-**A default feature is turned off in the manifest, not on the command line.**
-There is no `--no-default-features`. `mcpp build --features metrics` activates
-`default ∪ {metrics}`; building without a member of `default` means editing
-`[features] default`. Measured on 2026.9.8.1.
+**The root's default features are changed in its manifest.** There is no
+`--no-default-features` command-line option. `mcpp build --features metrics`
+activates the root's `default ∪ {metrics}`.
+
+A consumer can suppress a dependency's own default set:
+
+```toml
+[dependencies]
+widget = { version = "1.2.3", default-features = false, features = ["metrics"] }
+```
+
+Explicit features still activate. Requests unify across dependency edges: an
+edge opting out does not cancel defaults or features another edge requests.
 
 **A dependency cannot be conditioned on the accelerator.** `accelerator` is
 resolved from the dependency graph, so a dependency chosen by it would decide
diff --git a/docs/zh/06-features-and-capabilities.md b/docs/zh/06-features-and-capabilities.md
index 57bf6f25a..f1acb1d54 100644
--- a/docs/zh/06-features-and-capabilities.md
+++ b/docs/zh/06-features-and-capabilities.md
@@ -503,10 +503,18 @@ provides = ["platform-sdk"]
 
 ## 当前边界
 
-**默认 feature 在 manifest 里关掉，不在命令行上关掉。** 没有
-`--no-default-features`。`mcpp build --features metrics` 激活的是
-`default ∪ {metrics}`；要在不带 `default` 中某个成员的情况下构建，得改
-`[features] default`。实测于 2026.9.8.1。
+**根项目的默认 feature 在 manifest 中修改。** 没有 `--no-default-features`
+命令行选项。`mcpp build --features metrics` 激活根项目的 `default ∪ {metrics}`。
+
+消费者可以关闭依赖包自身的默认集合：
+
+```toml
+[dependencies]
+widget = { version = "1.2.3", default-features = false, features = ["metrics"] }
+```
+
+显式指定的 feature 仍会激活。不同依赖边的请求取并集：某条边关闭默认项，不会取消
+另一条边要求的默认项或 feature。
 
 **依赖不能以加速器为条件。** `accelerator` 是从依赖图中解析出来的，因此由它
 选择的依赖会决定它自己所问的那个答案。mcpp 会报告该谓词并忽略它。包要么无