feat(xlings): tools gain a tier, and a dependency's declaration is installed

## Two halves of one defect

`[xlings.workspace]` had one list. A board-support package naming both an
emulator (to run) and a debug probe (to reach hardware) installed both for every
consumer, including one that only wanted the library to compile — while package
dependencies have had `[dependencies]` / `[build-dependencies]` /
`[dev-dependencies]` since the beginning.

    [xlings.workspace]
    "xim:qemu-arm" = "9.2.4-1"                            # unchanged behaviour
    "xim:probe-rs" = { version = "0.24.0", when = "run" }

    [feature-xlings.hardware]
    "xim:probe-rs" = "0.24.0"                             # never fetched otherwise

| when | installed by | reaches a consumer |
|---|---|---|
| (omitted) | every verb that builds | yes |
| build | every verb that builds | yes |
| run | `mcpp run`, `mcpp test` | yes |
| dev | only the package that declared it, as the root | no |

Omitting `when` is the pre-2026.9.4.2 behaviour exactly, so no manifest changes.
The tier rides the entry rather than a second table, the shape `[dependencies]`
already uses; `[feature-xlings.<f>]` is `[feature-deps.<f>]`'s spelling.

## ⚠️⚠️ And provisioning now spans the graph, because looking did already

The previous release extended the runner's bare-name LOOKUP to every package in
the graph and left provisioning at the root. That is a search of directories
nothing installed into — a lookup that can only fail. Both are one expression
now, so they cannot drift.

Provisioning happens in two passes for an ordering reason: the root's list is
needed before the graph exists (a toolchain may depend on it), and a
dependency's is not known until resolution. The second pass provisions only what
the first did not, under its own stamp, so an unchanged project still pays for
no xlings round trip.

## ⚠️ The hazard a tier introduces, and the gate for it

`mcpp build` installs less than `mcpp run` needs, and the run fast path exists
precisely to skip the pass that would install the difference. The build cache
records whether a build left a run-tier tool unprovisioned; `try_fast_run`
declines such an entry, exactly as it declines one that records a runner.

## The criterion tests what mcpp REQUESTS, not what got installed

Verifying a tier by installing needs a clean machine and a network. It is also
the wrong object: what the tier changes is the SET, and `MCPP_NO_AUTO_INSTALL=1`
refuses to provision while naming exactly that set. `tests/e2e/335` reads both
commands on one project, so the criterion carries its own denominator — an mcpp
that provisioned nothing, or a manifest that never parsed, fails the `run` half.

## Discoverability

`mcpp why runners` lists what this project supplies, beside everything else it
reports resolving; `mcpp run --list-runners` is the same read alone. No stamped
one-time hint: a cache hit does not re-run, so it would be silent on the build
that needed it most.

97/97 unit (5 new); e2e 88, 130-131, 327, 332-335 green.

Author: speak-agent

CHANGELOG.md

@@ -5,7 +5,7 @@
 
 ## [2026.9.4.2] — 2026-09-04
 
-runner 有了名字,`--locked` 成为断言,`mcpp emit sbom`。
+runner 有了名字,工具有了档位,`--locked` 成为断言,`mcpp emit sbom`。
 
 ### ⭐⭐ 一条命令,加具名的例外
 
@@ -49,6 +49,47 @@ CycloneDX 1.5,覆盖**已记录**的解析。⚠️ 读锁而不是重新解析
 者不同的图的文档比没有更糟。归在 `emit` 之下而不是新开一级命令:`emit` 已经是
 「生成描述本工程的文档」。
 
+### ⭐⭐ 工具有了档位,而且依赖声明的工具现在真的会被装
+
+包依赖从一开始就有 `[dependencies]` / `[build-dependencies]` / `[dev-dependencies]`
+这条轴,工具只有一张表。一个同时点名模拟器与调试探针的板级包,会把两个都装给每一位
+消费者,包括只想把库编出来的那一位。
+
+```toml
+[xlings.workspace]
+"xim:qemu-arm"  = "9.2.4-1"                             # 不写就是从前的行为
+"xim:probe-rs"  = { version = "0.24.0", when = "run"   }
+
+[feature-xlings.hardware]
+"xim:probe-rs"  = "0.24.0"                              # 不要这个 feature 就永不下载
+```
+
+| `when` | 由谁安装 | 传播到消费者 |
+|---|---|---|
+| *(不写)* | 每个构建命令 | 是 |
+| `build` | 每个构建命令 | 是 |
+| `run` | `mcpp run`、`mcpp test` | 是 |
+| `dev` | 只有声明它的那个包作为根时 | **否** |
+
+⭐ **不写 `when` 保持今天的行为,所以没有迁移。**
+
+⚠️⚠️ **同时:`[xlings.workspace]` 的供给扩到全图。** 在此之前只有根工程的声明会被
+安装,而查找(runner 按裸名找程序)已经跨全图 —— **在没有任何东西安装过的目录里
+查找,是只可能失败的查找**。两者现在由同一个表达式定义。
+
+⚠️ 档位带来的一个危险已被堵上:`mcpp build` 装得比 `mcpp run` 需要的少,而 run 的
+快路径正是为跳过那一步存在的。构建缓存记下「这次构建留下了未安装的 run 档工具」,
+`mcpp run` 的快路径据此拒绝该条目 —— 与它拒绝声明了 runner 的条目同理。
+
+判据不测「装成了没有」,而测**mcpp 要装什么**:`MCPP_NO_AUTO_INSTALL=1` 下拒绝供给
+并**点名它本来要装的集合**,于是 `build` 与 `run` 两条命令的差集就是被测的性质,
+一次下载都不需要(`tests/e2e/335`)。
+
+### 发现性
+
+`mcpp why runners` 列出本工程提供的 runner,与其余解析结果并列;
+`mcpp run --list-runners` 是同一份读取,单独报告。
+
 新增 `docs/18-devices.md`、`docs/19-supported-versions.md`(中英双份)。
 指令协议版本 6。
 

docs/05-mcpp-toml.md

@@ -1920,6 +1920,65 @@ triples say one, descriptors and xlings' project file say the other) and both
 are accepted wherever a platform is named. A table with no key for this host
 and no `default` declares nothing here.
 
+#### `when` — which verbs need this tool (mcpp 2026.9.4.2+)
+
+```toml
+[xlings.workspace]
+"xim:qemu-arm"  = "9.2.4-1"                             # every build, as before
+"xim:codegen"   = { version = "1.0",    when = "build" }
+"xim:probe-rs"  = { version = "0.24.0", when = "run"   }
+"xim:clang-tidy"= { version = "20",     when = "dev"   }
+```
+
+Package dependencies have had this axis since the beginning —
+`[dependencies]`, `[build-dependencies]`, `[dev-dependencies]`. Tools had one
+list, so a board-support package that named both an emulator and a debug probe
+installed both for every consumer, including one that only wanted the library
+to compile.
+
+| `when` | Installed by | Reaches a consumer |
+|---|---|---|
+| *(omitted)* | every verb that builds | yes |
+| `build` | every verb that builds | yes |
+| `run` | `mcpp run`, `mcpp test` | yes |
+| `dev` | only the package that declared it, as the root | **no** |
+
+**Omitting `when` is the pre-2026.9.4.2 behaviour exactly**, so no manifest has
+to change. Narrowing is optional; it is not a question an author has to answer.
+
+`dev` is the only tier that does not propagate. It means *"while the package
+that declared this is itself being developed"*, so a dependency's `dev` entry is
+never installed for a consumer. Every other tier does reach one, which is the
+point of a board package knowing its own machine: it declares the emulator once
+and every consumer gets it.
+
+The tier is written on the entry rather than as a second table, on the same
+reasoning that makes `[dependencies]` accept both `dep = "1.0"` and
+`dep = { version = "1.0", features = [...] }`. A scoped entry must name
+`version` even to leave it empty (`version = ""` means *present, any version*),
+because `{ when = "run" }` and a misspelt `version` key would otherwise be
+indistinguishable.
+
+#### `[feature-xlings.<feature>]` — a tool a feature needs
+
+```toml
+[features]
+default  = ["emulator"]
+emulator = {}
+hardware = {}
+
+[feature-xlings.hardware]
+"xim:probe-rs" = "0.24.0"
+```
+
+The same table, gated on a feature, spelled the way `[feature-deps.<feature>]`
+is. A consumer who never asks for `hardware` never downloads a probe driver.
+Entries here accept `when` exactly as the unconditional ones do.
+
+A feature name no `[features]` table declares is reported as a schema warning:
+it activates for nobody and installs nothing, and a tool whose absence is only
+visible as *"the device is never reachable"* is the hardest kind to diagnose.
+
 #### Which version a tool the project did not name resolves to
 
 | The project declares | The version comes from |

docs/17-the-project-environment.md

@@ -151,7 +151,12 @@ exists for one host platform only is therefore declared for that platform
 on Linux and nothing elsewhere. The keys and the resolution rule are in
 chapter 5, §2.13.
 
-**The runner.** A program under `[xlings] deps` is also where
+**Which verbs install it.** An entry may name a tier —
+`{ version = "0.24.0", when = "run" }` — and a `[feature-xlings.<feature>]`
+table gates one on a feature. A tool the project will not use is then not
+downloaded: chapter 5, §2.13. Omitting the tier is the historical behaviour.
+
+**The runner.** A program under `[xlings.workspace]` is also where
 `[target.<triple>].runner` looks first for its first element, before `PATH`
 (chapter 5, §2.7.3). The two keys together provision a user-mode emulator on a
 CI host and execute a cross-built artifact through it, without the manifest
@@ -164,7 +169,8 @@ naming the payload's path.
 | a library the program links | `[dependencies]` |
 | the compiler | `[toolchain]`, chapter 3 |
 | a host tool a dependency produces | `tools = [...]`, chapter 7 |
-| a tool present in the environment | `[xlings] deps` |
+| a tool present in the environment | `[xlings.workspace]` |
+| a tool only one verb or one feature needs | `when = "run"`, `[feature-xlings.<f>]` |
 | which environment | `[xlings] subos` |
 
 ## 7. Related chapters

docs/18-devices.md

@@ -20,6 +20,7 @@ performs, with the artifact appended or substituted for `{}`.
 mcpp run                        # the default runner
 mcpp run --runner flash         # a named one
 mcpp run --list-runners         # what this project supplies
+mcpp why runners                # the same list, beside everything else resolved
 ```
 
 `mcpp run` is the whole of the common case, including on real hardware. On a

docs/zh/05-mcpp-toml.md

@@ -1637,6 +1637,57 @@ mcpp 既供给它——机器上没有就装,有就映射——也把它物化
 文件说后者),**凡是点名平台的地方两者都接受**。表里既没有本机这一项也没有
 `default`,就表示在这里什么都不声明。
 
+#### `when` —— 哪些命令需要这个工具(mcpp 2026.9.4.2+)
+
+```toml
+[xlings.workspace]
+"xim:qemu-arm"   = "9.2.4-1"                             # 每次构建都装,与从前一样
+"xim:codegen"    = { version = "1.0",    when = "build" }
+"xim:probe-rs"   = { version = "0.24.0", when = "run"   }
+"xim:clang-tidy" = { version = "20",     when = "dev"   }
+```
+
+包依赖从一开始就有这条轴 —— `[dependencies]`、`[build-dependencies]`、
+`[dev-dependencies]`。工具只有一张表,于是一个同时点名模拟器与调试探针的板级支持包
+会把两个都装给每一位消费者,包括只想把库编出来的那一位。
+
+| `when` | 由谁安装 | 是否传播到消费者 |
+|---|---|---|
+| *(不写)* | 每个构建命令 | 是 |
+| `build` | 每个构建命令 | 是 |
+| `run` | `mcpp run`、`mcpp test` | 是 |
+| `dev` | 只有声明它的那个包作为根时 | **否** |
+
+**不写 `when` 就是 2026.9.4.2 之前的行为**,所以没有任何清单需要改。收窄是可选动作,
+不是作者必须回答的新问题。
+
+`dev` 是唯一不传播的一档。它的含义是「声明它的那个包自己在被开发时」,所以依赖的
+`dev` 条目永远不会为消费者安装。其余各档都会到达消费者 —— 这正是板级包知道自己机器
+的意义:它声明一次模拟器,每一位消费者都拿得到。
+
+档位写在**条目**上而不是另开一张表,理由与 `[dependencies]` 同时接受 `dep = "1.0"`
+和 `dep = { version = "1.0", features = [...] }` 是同一条。带档位的条目**必须**写出
+`version`,哪怕留空(`version = ""` 表示「存在即可,版本不限」)—— 否则
+`{ when = "run" }` 与写错的 `version` 键无法区分。
+
+#### `[feature-xlings.<feature>]` —— 某个 feature 才需要的工具
+
+```toml
+[features]
+default  = ["emulator"]
+emulator = {}
+hardware = {}
+
+[feature-xlings.hardware]
+"xim:probe-rs" = "0.24.0"
+```
+
+同一张表,按 feature 门控,拼法沿用 `[feature-deps.<feature>]`。**不要 `hardware`
+的消费者永远不会下载探针驱动。** 这里的条目同样接受 `when`。
+
+`[features]` 里没有声明过的 feature 名会作为 schema 警告报出:它对谁都不激活、什么
+都不装,而这种工具的缺席只表现为「设备就是连不上」,是最难诊断的一种。
+
 #### 工程没点名的工具,其版本的来源
 
 | 工程声明了 | 版本来自 |

docs/zh/17-the-project-environment.md

@@ -122,7 +122,11 @@ create/bootstrap that environment instead of falling back to active/default
 `deps = [{ linux = "qemu-user-aarch64" }]` 在 Linux 上声明这个模拟器,在别处什么都不声明。
 键与解析规则见第 5 章 §2.13。
 
-**runner。** `[xlings] deps` 下的程序也是 `[target.<triple>].runner` 查找其第一个元素
+**哪些命令会安装它。** 一条条目可以带档位 —— `{ version = "0.24.0", when = "run" }` ——
+`[feature-xlings.<feature>]` 则把工具挂在某个 feature 上。用不到的工具因此不会被下载:
+见第 5 章 §2.13。不写档位就是从前的行为。
+
+**runner。** `[xlings.workspace]` 下的程序也是 `[target.<triple>].runner` 查找其第一个元素
 的首选位置,在 `PATH` 之前(第 5 章 §2.7.3)。两个键合起来,在 CI 宿主上供给用户态模拟器,
 并通过它执行交叉构建的产物,而清单不必写出载荷的路径。
 
@@ -133,7 +137,8 @@ create/bootstrap that environment instead of falling back to active/default
 | 程序链接的库 | `[dependencies]` |
 | 编译器 | `[toolchain]`,第 3 章 |
 | 依赖产出的宿主工具 | `tools = [...]`,第 7 章 |
-| 环境里要有的工具 | `[xlings] deps` |
+| 环境里要有的工具 | `[xlings.workspace]` |
+| 只有某个命令或某个 feature 需要的工具 | `when = "run"`、`[feature-xlings.<f>]` |
 | 用哪个环境 | `[xlings] subos` |
 
 ## 7. 相关章节

docs/zh/18-devices.md

@@ -15,6 +15,7 @@
 mcpp run                        # 默认 runner
 mcpp run --runner flash         # 具名的
 mcpp run --list-runners         # 这个工程提供了哪些
+mcpp why runners                # 同一份清单,与其余解析结果并列
 ```
 
 **`mcpp run` 覆盖了常见情形的全部,真实硬件也一样。** 在设备上,「运行一个程序」

modules/manifest/src/toml.cppm

@@ -240,6 +240,69 @@ inline XlingsEntry parse_address(std::string_view address) {
     return XlingsEntry{ ns, target, std::string(version) };
 }
 
+// An entry's value, split into the part that names a version and the tier that
+// part belongs to.
+//
+// ⭐ `{ version = "…", when = "…" }` IS THE SAME SHAPE A DEPENDENCY ALREADY
+// HAS. mcpp writes `dep = "1.0"` or `dep = { version = "1.0", features = [] }`,
+// and a tool entry now writes `"xim:probe-rs" = "0.24.0"` or
+// `{ version = "0.24.0", when = "run" }`. One table, richer entries — rather
+// than a second table per tier, which `[xlings.workspace]` was made the one
+// table specifically to avoid.
+//
+// The two spellings cannot be confused. A platform table's keys are `linux`,
+// `macosx`, `macos`, `windows` and `default`; the scoped table's are `version`
+// and `when`, and neither set contains a member of the other. So the presence
+// of either key decides, and the `version` it carries may itself be a platform
+// table.
+struct WhenSplit {
+    const mcpp::libs::toml::Value* value = nullptr;   // string, or platform table
+    ToolWhen                       when  = ToolWhen::Always;
+};
+
+inline std::expected<ToolWhen, std::string> parse_when(std::string_view w) {
+    if (w == "build")  return ToolWhen::Build;
+    if (w == "run")    return ToolWhen::Run;
+    if (w == "dev")    return ToolWhen::Dev;
+    if (w == "always") return ToolWhen::Always;
+    return std::unexpected(std::format(
+        "when = '{}' is not a tier; expected 'build', 'run' or 'dev' "
+        "(omit it for the default, which is every build)", w));
+}
+
+inline std::expected<WhenSplit, std::string>
+split_when(const mcpp::libs::toml::Value& v) {
+    if (!v.is_table()) return WhenSplit{ &v, ToolWhen::Always };
+    const auto& t = v.as_table();
+    auto itVer  = t.find("version");
+    auto itWhen = t.find("when");
+    if (itVer == t.end() && itWhen == t.end())
+        return WhenSplit{ &v, ToolWhen::Always };   // a platform table
+    // ⚠️ A SCOPED ENTRY MUST NAME ITS VERSION KEY EVEN TO LEAVE IT EMPTY.
+    // `{ when = "run" }` alone reads as "present, unconstrained, run tier",
+    // which is a meaningful thing to say — but so is a typo of `version`, and
+    // the two would be indistinguishable. The key is required, `""` says
+    // unconstrained, and a table carrying anything else is refused by name.
+    for (auto const& [k, _] : t)
+        if (k != "version" && k != "when")
+            return std::unexpected(std::format(
+                "unknown key '{}' in a scoped entry; expected 'version' and "
+                "'when'", k));
+    if (itVer == t.end())
+        return std::unexpected(std::string(
+            "a scoped entry needs 'version' (write version = \"\" for "
+            "\"present, any version\")"));
+    WhenSplit out{ &itVer->second, ToolWhen::Always };
+    if (itWhen != t.end()) {
+        if (!itWhen->second.is_string())
+            return std::unexpected(std::string("'when' must be a string"));
+        auto w = parse_when(itWhen->second.as_string());
+        if (!w) return std::unexpected(w.error());
+        out.when = *w;
+    }
+    return out;
+}
+
 // Combine the two halves a namespace may be written on. Both may carry it;
 // disagreeing is an error rather than a precedence rule, because a precedence
 // rule would make one of the two spellings silently ineffective.
@@ -1518,7 +1581,10 @@ std::expected<Manifest, ManifestError> parse_string(std::string_view content,
         // both rather than pick one.
         std::map<std::string, std::string> writtenAs;
         for (auto& [k, val] : *wt) {
-            auto vals = platform_values(val);
+            auto scoped = split_when(val);
+            if (!scoped) return std::unexpected(error(origin,
+                std::format("[xlings.workspace] {}: {}", k, scoped.error())));
+            auto vals = platform_values(*scoped->value);
             if (!vals) return std::unexpected(error(origin,
                 std::format("[xlings.workspace] {}: {}", k, vals.error())));
             // Every platform, for the descriptor emitter. Resolved per
@@ -1544,6 +1610,65 @@ std::expected<Manifest, ManifestError> parse_string(std::string_view content,
             writtenAs.emplace(entry->target, k);
             m.xlings.workspace[entry->target] = entry->pin();
             m.xlings.deps.push_back(entry->address());
+            if (scoped->when != ToolWhen::Always)
+                m.xlings.depWhen[entry->address()] = scoped->when;
+        }
+    }
+    // `[feature-xlings.<feature>]` — the same table, gated on a feature of the
+    // package that declared it.
+    //
+    // ⭐ THE SPELLING IS `[feature-deps.<feature>]`'s, DELIBERATELY. A feature
+    // that pulls in a package and a feature that pulls in a tool are the same
+    // statement about the same feature, and inventing a second syntax for the
+    // second would make an author learn a rule that buys nothing. The keys
+    // differ because the things named differ: a package name there, an xim
+    // address here.
+    //
+    // ⚠️ A FEATURE NAME THAT NO `[features]` DECLARES IS REPORTED. A
+    // `[feature-xlings.hardwear]` activates for nobody and installs nothing,
+    // and the tool it names is the one whose absence is hardest to diagnose:
+    // the build succeeds and the device is simply never reachable.
+    //
+    // A warning rather than an error, on the same reasoning as the
+    // `[features]` schema check above — it is surfaced for the ROOT manifest
+    // before any dependency's is loaded, so a package may adopt a feature its
+    // consumers' engines do not yet know without breaking them.
+    if (auto* ft = doc->get_table("feature-xlings")) {
+        for (auto& [feature, tbl] : *ft) {
+            if (!m.featuresMap.contains(feature)) {
+                std::string known;
+                for (auto const& [f, _] : m.featuresMap) {
+                    if (!known.empty()) known += ", ";
+                    known += f;
+                }
+                m.schemaWarnings.push_back(std::format(
+                    "[feature-xlings.{}] names a feature no [features] table "
+                    "declares, so nothing it lists is ever installed. {}",
+                    feature, known.empty()
+                        ? std::string("This package declares no features.")
+                        : std::format("Declared features: {}.", known)));
+            }
+            if (!tbl.is_table())
+                return std::unexpected(error(origin, std::format(
+                    "[feature-xlings.{}] must be a table of package = version",
+                    feature)));
+            for (auto& [k, val] : tbl.as_table()) {
+                auto scoped = split_when(val);
+                if (!scoped) return std::unexpected(error(origin, std::format(
+                    "[feature-xlings.{}] {}: {}", feature, k, scoped.error())));
+                auto vals = platform_values(*scoped->value);
+                if (!vals) return std::unexpected(error(origin, std::format(
+                    "[feature-xlings.{}] {}: {}", feature, k, vals.error())));
+                auto hostValue = value_for_platform(*vals, host_platform_key());
+                if (!hostValue) continue;   // not declared on this host
+                auto entry = make_xlings_entry(k, *hostValue);
+                if (!entry) return std::unexpected(error(origin, std::format(
+                    "[feature-xlings.{}] {}: {}", feature, k, entry.error())));
+                m.xlings.featureDeps[feature].push_back(entry->address());
+                m.xlings.featurePins[entry->address()] = entry->pin();
+                if (scoped->when != ToolWhen::Always)
+                    m.xlings.depWhen[entry->address()] = scoped->when;
+            }
         }
     }
     if (doc->get("xlings.subos")) {