From 67e4d74a8aa963379f0e95feeb464288648a2dcf Mon Sep 17 00:00:00 2001
From: l0ng-ai <24760907+l0ng-ai@users.noreply.github.com>
Date: Sun, 16 Aug 2026 10:28:17 +0800
Subject: [PATCH] test: keep the command reference's flags from falling behind
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Checked the reference against the CLI it describes, in both directions.
It holds today: every flag it names is real — `--h` and `--v` are the
visible aliases of `--horizontal` and `--vertical`, `--all` and
`--orphans` belong to the `pane` subcommands — and every flag of every
verb it covers is on the page. So are the JSON keys: workspaces, agents,
build, control_version, protocol_version, socket, uptime_secs, ports,
procs.

Adding a flag is one line in this file. The page is somewhere else, and
an agent that cannot see a flag will not use it, so the drift is silent
and lands on the readers the page exists for.

The test asks clap for the flags rather than keeping a list beside it —
a list would be a third thing to drift — and skips the `ws`, `tab`,
`pane`, `machine` and `server` groups the page now says it leaves to
`--help`.

It also counts what it looked at. A cross-file test whose filter matches
nothing passes just as quietly as one that finds nothing wrong, and this
one would have: ten verbs and five flags are the floor.
---
 crates/tty7-cli/src/cli.rs | 47 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/crates/tty7-cli/src/cli.rs b/crates/tty7-cli/src/cli.rs
index 518ac9dd..9885119a 100644
--- a/crates/tty7-cli/src/cli.rs
+++ b/crates/tty7-cli/src/cli.rs
@@ -614,6 +614,53 @@ mod tests {
     use super::*;
     use clap::error::ErrorKind;
 
+    /// Every flag of every verb the reference documents is on the page.
+    ///
+    /// The page promises "the verbs an agent drives, their flags, and the JSON
+    /// they emit", and an agent that cannot see a flag will not use it. Adding
+    /// one is a line in this file; the page is somewhere else entirely, so
+    /// nothing but this notices. Read from clap rather than a hand-kept list,
+    /// so the two cannot disagree about what the flags even are.
+    ///
+    /// Only the verbs the page covers: it says plainly that the `ws`, `tab`,
+    /// `pane`, `machine` and `server` groups live behind `--help` instead.
+    #[test]
+    fn the_reference_documents_every_flag_of_the_verbs_it_covers() {
+        use clap::CommandFactory as _;
+
+        const DOC: &str = include_str!("../../../docs/cli/reference.mdx");
+        // Global flags have their own table, and `--help` is clap's.
+        const EVERYWHERE: [&str; 4] = ["json", "quiet", "machine", "help"];
+
+        let cli = Cli::command();
+        let mut missing: Vec<String> = Vec::new();
+        let (mut covered, mut checked) = (0usize, 0usize);
+        for verb in cli.get_subcommands() {
+            let name = verb.get_name();
+            if !DOC.contains(&format!("`tty7 {name}")) {
+                continue;
+            }
+            covered += 1;
+            for arg in verb.get_arguments() {
+                let Some(long) = arg.get_long() else { continue };
+                if EVERYWHERE.contains(&long) {
+                    continue;
+                }
+                checked += 1;
+                if !DOC.contains(&format!("`--{long}")) {
+                    missing.push(format!("{name} --{long}"));
+                }
+            }
+        }
+        // Or the loop could pass by matching nothing at all.
+        assert!(covered >= 10, "only {covered} documented verbs were found");
+        assert!(checked >= 5, "only {checked} verb flags were checked");
+        assert!(
+            missing.is_empty(),
+            "the command reference does not mention these flags: {missing:?}"
+        );
+    }
+
     fn parse(args: &[&str]) -> Cli {
         Cli::try_parse_from(args).expect("this invocation is part of the documented grammar")
     }