fix(diag): the freestanding import std message pointed at a package that does not exist

It ended with a copy-pasteable

    [dependencies]
    mcpplibs.std.freestanding = "0.1"

and no such package is published. Following the advice fails at the very next
command with "package not found", which sends the reader off to debug their
index instead of their code.

Now it points at what a bare-metal project actually has — the module its board
package exports, named concretely — and describes a freestanding subset package
as a shape rather than a line to paste, saying plainly that none is published
yet. The concrete line comes back when one ships.

Every suggestion in a diagnostic is a promise; this one had not been checked
against reality before being written.

Author: speak-agent

.agents/docs/2026-08-19-baremetal-phase3-usable-plan.md

@@ -413,3 +413,27 @@ deps = { "xim:picolibc-riscv@1.8.12", "xim:qemu-riscv@9.2.4-1" },
 #### 兼容性:类型化 API 没有语言内的特性探测(见 §3.2 的补记)
 
 包侧无解 ⇒ 补在引擎侧的编译失败诊断上,对**以后每一次**类型化 API 新增都生效。
+
+### 11.3 ⚠️ 我在第二阶段留下了一条**指向不存在的包**的诊断
+
+W6 的 `import std` 诊断里写着可以直接粘贴的:
+
+```toml
+[dependencies]
+mcpplibs.std.freestanding = "0.1"
+```
+
+**这个包没有发布,而且本阶段也不该顺手发**(E-STD-1/E-STD-2 各自是 M 规模:
+`-nostdinc++` 之下 libc++ 的头一个都用不了,子集要自己实现;而且往 `namespace std`
+里加声明本身就是另一个问题)。
+
+⇒ 用户照着诊断粘完,下一条命令报「package not found」。**一条修不好问题的诊断,
+比一条只解释不给命令的诊断更糟** —— 它让读者接下来几分钟在怀疑自己的索引坏了。
+
+已改成指向**今天确实存在**的东西(板级包导出的模块,点名 `mcpplibs.riscv_virt_rt`),
+并把子集包描述成一个**形态**而不是一行可粘贴的依赖,末尾明说「还没有这样的包」。
+**E-STD 仍然开着;它发布时要把这条诊断改回具体的一行。**
+
+⚠️ 一般化:**诊断里的每一条建议都是一个承诺**,而承诺是要被兑现的。写「加这一行」
+之前必须先确认那一行今天能跑通 —— 这条和 [[issue427-absence-treated-as-contradiction]]
+里那条错误建议是同一形状。

docs/05-mcpp-toml.md

@@ -931,7 +931,7 @@ that has none.
 |---|---|
 | Link line | `-nostdlib -nostartfiles -static`, and nothing hosted — no crt files, no dynamic linker, no C++ runtime. The linker is addressed by **absolute path** (`-fuse-ld=<payload>/bin/ld.lld`), because `-fuse-ld=lld` resolves through `PATH` and finds GNU ld on any machine with binutils earlier on it. |
 | ISA flags | `-march` / `-mabi` / `-mcmodel` come from the target table, so `--target <triple>` alone is enough to produce a correct object file. |
-| `import std` | **Unavailable.** `std` is one module over the entire library — threads, filesystem and iostreams included — so there is no subset of it to build without an OS. The freestanding subset package replaces it, and mcpp's diagnostic names it. |
+| `import std` | **Unavailable.** `std` is one module over the entire library — threads, filesystem and iostreams included — so there is no subset of it to build without an OS. What a firmware imports instead is the module its **board package** exports, which is where the target's C library is already wrapped. |
 | Entry point | `int main()` works **as long as something supplies a `crt0`** — a board package normally does, and then a firmware's entry point is an ordinary `main` whose return value reaches the host through semihosting. Only a zero-libc board needs an explicit target whose `main` points at the file carrying `_start`. |
 
 **A minimal firmware**

docs/zh/05-mcpp-toml.md

@@ -827,7 +827,7 @@ cd blinky && mcpp run
 |---|---|
 | 链接线 | `-nostdlib -nostartfiles -static`,且不带任何 hosted 的东西 —— 没有 crt 文件、没有动态链接器、没有 C++ 运行时。链接器用**绝对路径**寻址(`-fuse-ld=<载荷>/bin/ld.lld`),因为 `-fuse-ld=lld` 走 `PATH` 解析,在任何 binutils 排前面的机器上都会找到 GNU ld。 |
 | ISA flag | `-march` / `-mabi` / `-mcmodel` 来自 target 表,所以只写 `--target <triple>` 就足以产出正确的目标文件。 |
-| `import std` | **不可用。** `std` 是覆盖整个库的一个模块 —— 线程、文件系统、iostreams 全在内 —— 没有 OS 就没有它的子集可编。freestanding 子集包取代它,mcpp 的诊断会点名。 |
+| `import std` | **不可用。** `std` 是覆盖整个库的一个模块 —— 线程、文件系统、iostreams 全在内 —— 没有 OS 就没有它的子集可编。固件真正 import 的是**板级包导出的模块**,目标的 C 库已经在那里包好了。 |
 | 入口点 | **只要有人提供 `crt0`,`int main()` 就能用** —— 板级支持包通常就提供它,于是固件的入口就是普通的 `main`,它的返回值经 semihosting 传回宿主。**只有零 libc 的板子**才需要显式声明 target 并把 `main` 指向携带 `_start` 的那个文件。 |
 
 **一个最小固件**

src/build/prepare.cppm

@@ -5273,9 +5273,18 @@ prepare_build(bool print_fingerprint,
         // no subset of it to build without an OS. Saying "provides no std
         // module source" sends the reader to look for a broken payload.
         //
-        // Naming the replacement is the whole value of the diagnostic: the
-        // freestanding subset is an ordinary package, so the fix is one line in
-        // the manifest rather than a toolchain investigation.
+        // ⚠️ It used to end with a copy-pasteable
+        //
+        //     [dependencies]
+        //     mcpplibs.std.freestanding = "0.1"
+        //
+        // and that package is NOT published. A diagnostic whose suggested fix
+        // fails at the next command is worse than one that explains and stops:
+        // the reader spends the next minutes deciding whether their index is
+        // broken. Point at what a bare-metal project actually has today — the
+        // board package it already depends on exports a module — and describe
+        // the subset package as a shape rather than as a line to paste.
+        // Restore the concrete line when such a package ships.
         if (auto ft = mcpp::toolchain::triple::parse(tc->targetTriple);
             ft && ft->is_freestanding())
         {
@@ -5286,13 +5295,19 @@ prepare_build(bool print_fingerprint,
                 "filesystem, iostreams\n"
                 "       included), so there is no subset of it to build without "
                 "an OS underneath.\n"
-                "       Use the freestanding subset instead:\n"
                 "\n"
-                "           [dependencies]\n"
-                "           mcpplibs.std.freestanding = \"0.1\"\n"
+                "       What a bare-metal project uses instead:\n"
+                "         * the module its BOARD package exports — that is where "
+                "the target's\n"
+                "           C library is already wrapped (riscv-virt-rt exports "
+                "`mcpplibs.riscv_virt_rt`);\n"
+                "         * or a freestanding subset package, which is an "
+                "ordinary dependency\n"
+                "           providing the header-only parts of the library that "
+                "need no OS.\n"
                 "\n"
-                "       then `import mcpplibs.std.freestanding;` in place of "
-                "`import std;`.",
+                "       No such subset package is published yet, so there is no "
+                "line to paste here.",
                 tc->targetTriple));
         }
         return std::unexpected(std::format(