fix(cli): rename run's positional to bin, which frees --target

The collision was real — `mcpp run q` became `mcpp run --target=q` — but
retreating to `--target-triple` on this one subcommand paid for it with a
lasting inconsistency.

The actual cause is narrower than "one word, two axes": ParsedArgs::value()
falls back from an unset option to a positional OF THE SAME NAME, and that
positional was named `target`. cmd_run never reads the name (it takes
positional(0) by index) — it only labels the slot in --help, where `bin` is
the more accurate word.

So `--target` works on `run` like everywhere else, `--target-triple` stays as
an alias because it shipped in 2026.8.19.1, and e2e/130 now pins both
spellings while e2e/73 pins the positional.

Author: speak-agent

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

@@ -352,5 +352,12 @@ error: test result: FAILED. 2 passed; 1 failed
   ```
 
   `e2e/73` 立刻红。而位置参数上**原本就有一条注释写着这个碰撞** —— 我为了对称把它
-  覆盖了。⇒ `run` 保持 `--target-triple`(`test` 没有这个位置参数,`--target` 正常)。
-  **一致性是判据之一,但它排在「不能坏」后面。**
+  覆盖了。
+
+  但**第一版修法(`run` 退回只认 `--target-triple`)也不对** —— 它把「不能坏」买回来了,
+  代价是留下一条真实的不一致。**真因不是这个词有两个轴,而是位置参数的名字选错了**:
+  `ParsedArgs::value()` 在选项未设置时会**按同名回落到位置参数**,而这个位置参数的名字
+  `cmd_run` 从来不读(它按下标取 `positional(0)`),只出现在 `--help` 里。
+  ⇒ **把位置参数改名 `bin`**(在 `--help` 里本来就更准),`--target` 就自由了。
+  `--target-triple` 作为 2026.8.19.1 已发布的拼写保留为别名。
+  **一致性是判据之一,它排在「不能坏」后面 —— 但排在后面不等于要放弃。**

docs/05-mcpp-toml.md

@@ -906,7 +906,7 @@ can produce them.
 
 ```bash
 mcpp build --target riscv64-none-elf
-mcpp run   --target-triple riscv64-none-elf     # via [target.<triple>].runner
+mcpp run   --target riscv64-none-elf     # via [target.<triple>].runner
 ```
 
 **What changes on a freestanding target**

docs/zh/05-mcpp-toml.md

@@ -804,7 +804,7 @@ cxxflags = ["-march=x86-64-v2"]
 
 ```bash
 mcpp build --target riscv64-none-elf
-mcpp run   --target-triple riscv64-none-elf     # 经 [target.<triple>].runner
+mcpp run   --target riscv64-none-elf     # 经 [target.<triple>].runner
 ```
 
 **freestanding target 上有什么不同**

src/cli.cppm

@@ -316,29 +316,29 @@ int run(int argc, char** argv) {
             .action(wrap_rc(cmd_build)))
         .subcommand(cl::App("run")
             .description("Build + run a binary target (after `--`, args are passed to it)")
-            // NB: this positional is a BINARY NAME from [[bin]]/src layout —
-            // unrelated to `--target <triple>` (the cross-target axis).
-            .arg(cl::Arg("target").help("Binary name (optional)"))
-            // ⚠️ Same word, two axes — and they were ALREADY named this way:
-            // the positional above is a binary name, this option is the cross
-            // target triple, exactly as in `mcpp build --target`. Spelling the
-            // option differently here would make the one command that needs
-            // both the one command where the flag is not called --target.
-            // ⚠️ NOT `--target`, and this is not a style choice.
+            // ⚠️ Named `bin`, NOT `target`, and the rename is load-bearing.
             //
-            // The POSITIONAL above is already called target — it is the binary
-            // NAME — and the parser keys both by that word, so declaring the
-            // option makes `mcpp run <binary>` set the cross-target instead:
+            // This positional is a BINARY NAME from [[bin]]/src layout. It was
+            // called `target` — the same word as the cross-target axis — and
+            // ParsedArgs::value() falls back from an unset option to a
+            // positional OF THE SAME NAME, so adding `--target` here made
+            // every ordinary invocation read the binary name as a triple:
             //
             //     $ mcpp run q
             //     error: unknown target 'q'
             //
-            // Measured, after trying exactly that for the sake of matching
-            // `mcpp build --target`. `run` is the one subcommand that cannot
-            // spell it that way, and the existing comment on the positional
-            // said so before this was attempted.
-            .option(cl::Option("target-triple").takes_value().value_name("TRIPLE")
+            // The name is never read back (cmd_run takes positional(0) by
+            // index); it only labels this slot and shows up in --help, where
+            // `bin` is the more accurate word anyway. So renaming it is what
+            // lets `run` spell the flag `--target` like every other
+            // subcommand, instead of being the one command that cannot.
+            .arg(cl::Arg("bin").help("Binary name (optional)"))
+            .option(cl::Option("target").takes_value().value_name("TRIPLE")
                 .help("Cross target triple (same axis as `mcpp build --target`)"))
+            // Kept as an alias: it shipped in 2026.8.19.1 as the only spelling
+            // `run` accepted, and scripts written against it must keep working.
+            .option(cl::Option("target-triple").takes_value().value_name("TRIPLE")
+                .help("Alias for --target"))
             .option(cl::Option("package").short_name('p').takes_value().value_name("NAME")
                 .help("Run only the named workspace member (single-member; no --workspace fan-out)"))
             .option(cl::Option("cache").takes_value().value_name("MODE")

src/cli/cmd_build.cppm

@@ -166,10 +166,10 @@ export int cmd_run(const mcpplibs::cmdline::ParsedArgs& parsed,
     bool no_cache = parsed.is_flag_set("no-cache");
     if (auto c = parsed.value("cache")) cache_mode = *c;
     else if (no_cache)                  cache_mode = "off";
-    // ⚠️ `--target-triple`, never `--target`: this subcommand's POSITIONAL is
-    // called target and means the binary NAME, and the parser keys both by
-    // that word. See the option's declaration in cli.cppm.
+    // Both spellings; see cli.cppm for why the positional had to be renamed
+    // before `--target` could exist here at all.
     std::string target_triple;
+    if (auto tt = parsed.value("target"))        target_triple = *tt;
     if (auto tt = parsed.value("target-triple")) target_triple = *tt;
     return mcpp::build::build_run_target(targetName, passthrough, package_filter,
                                          cache_mode, no_cache, target_triple);

tests/e2e/130_freestanding_riscv_build_and_run.sh

@@ -159,10 +159,26 @@ readelf -h "$img" | grep -q '0x80200000' || {
     readelf -h "$img" | grep -i entry; exit 1; }
 
 # ── run ─────────────────────────────────────────────────────────────────────
-"$MCPP" run --target-triple riscv64-none-elf > run.log 2>&1 || true
+# ⚠️ BOTH spellings, and the pairing is the test.
+#
+# `run` also takes a POSITIONAL binary name, and the arg parser falls back
+# from an unset option to a positional of the same name. While that positional
+# was itself called `target`, adding `--target` here silently turned
+# `mcpp run <binary>` into `mcpp run --target=<binary>`:
+#
+#     $ mcpp run q
+#     error: unknown target 'q'
+#
+# `--target-triple` shipped first and stays an alias, so both are pinned; the
+# positional case is pinned by 73_issue131_per_target_cxxflag.sh.
+"$MCPP" run --target riscv64-none-elf > run.log 2>&1 || true
 grep -q 'MCPP-FREESTANDING-OK' run.log || {
     cat run.log; echo "the firmware did not run (or produced no output)"; exit 1; }
 
+"$MCPP" run --target-triple riscv64-none-elf > alias.log 2>&1 || true
+grep -q 'MCPP-FREESTANDING-OK' alias.log || {
+    cat alias.log; echo "--target-triple (the 2026.8.19.1 spelling) stopped working"; exit 1; }
+
 # ── the runner is REQUIRED, and its absence must say so ─────────────────────
 # Two-sided: without this, "run worked" could equally mean mcpp exec'd the
 # image directly and something else printed the line.