From 49d2a68ad107a3129b0214e66fb1e5009abd9337 Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Fri, 21 Aug 2026 13:23:28 +0000
Subject: [PATCH 1/3] feat(spec)!: lower the derive's flatten into a flagset
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`#[usage(flatten)]` splices a struct's declarations into the command that holds
it, and the emitted spec repeated them under every command that flattened the
struct. mise gives one `Args` type to ten commands; the spec said it ten times.

Now the struct becomes one `flagset`, named after it, and each command that
flattens it gets a `use`. A struct that flattens another becomes a set that uses
a set. Positionals stay on each command, since a set holds flags only.

`CommandMeta` gains `flatten_groups`: the seam the expansion leaves behind, so
`to_kdl` knows which run of a command's flags came from which struct. Nothing
about parsing changes — the flags are in the flag table either way, and the hot
path never reads metadata.

Two decisions worth recording:

- **One set per flattened struct**, not only for the ones with several users or
  the ones that save lines. A threshold would make how one command is written
  depend on what another command does, so adding a `flatten` elsewhere would
  restructure a command nobody touched.
- **Two structs whose names end in the same word get no set.** One name cannot
  stand for both, so both are written inline — what every flatten did before,
  never wrong and only longer. Detected by comparing flag keys, which the derive
  hashes from the declaring type.

usage-cli is the first case: its four shell commands flatten `Shell`, and its
checked-in spec now says so. Its generated markdown, JSON reference and manpage
are byte-identical across the change, because the reference parser resolves a
`use` while it reads the file.

Breaking only in that `CommandMeta` grows a field. It is constructed by generated
code, which moves with this crate, so an adopter recompiles rather than edits.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 PLAN.md                        |  19 ++-
 argv/src/spec.rs               | 252 ++++++++++++++++++++++++------
 cli/src/cli/mod.rs             |   5 +
 cli/usage.usage.kdl            |  16 +-
 conformance/src/tables.rs      |   3 +
 conformance/tests/flatten.rs   |  24 ++-
 derive/src/codegen.rs          |  55 ++++++-
 docs/rust/subcommands.md       |  34 +++-
 docs/spec/reference/flagset.md |  12 ++
 usage-rs/tests/facade.rs       | 275 +++++++++++++++++++++++++++++++++
 10 files changed, 623 insertions(+), 72 deletions(-)

diff --git a/PLAN.md b/PLAN.md
index f54c8602a..93c1b1aa6 100644
--- a/PLAN.md
+++ b/PLAN.md
@@ -321,10 +321,21 @@ tasks --usage"`, so task names are meant to come from running that. usage-argv d
       different arguments would mean two different things. Sets travel through `include`, and
       each file resolves its own `use` nodes — a file cannot use a set declared only by a file
       that includes _it_, which would make a spec's meaning depend on who read it.
-      What this does **not** do yet is give the derive's `flatten` a lossless lowering: it still
-      emits the expanded copy, so the flags mise's spec repeats stay repeated in the generated
-      file. Emitting one flagset per flattened struct is the follow-up, and it is what would
-      turn this from an authoring convenience into a smaller generated spec.
+      The derive lowers `flatten` into it rather than emitting the expanded copy: one flagset
+      per flattened struct, named after it, and a `use` on every command that flattens it. A
+      struct that flattens another becomes a set that uses a set. One set per struct rather
+      than only for the ones with several users — a threshold would make how one command is
+      written depend on what another does, so adding a `flatten` elsewhere would restructure a
+      command nobody touched. Two flattened structs whose names end in the same word get no set:
+      one name cannot stand for both, so both are written inline, which is what every flatten
+      did before. usage-cli's own checked-in spec is the first case of it, and its generated
+      markdown, JSON and manpage are byte-identical across the change — the reference parser
+      resolves the set while it reads the file, so what a command accepts never moved.
+      Still owed: a way to name a set other than after the Rust type, which is what a collision
+      needs to be fixable rather than merely safe. And usage-cli declares
+      `min_usage_version "4.0"` while now emitting a node no 4.0 can read — the floor moves to
+      whatever release carries this, which is release-plz's to stamp rather than a number to
+      guess here.
 
 ### Then: what a CLI framework has to have
 
diff --git a/argv/src/spec.rs b/argv/src/spec.rs
index a71fbb7ff..f020c3e2b 100644
--- a/argv/src/spec.rs
+++ b/argv/src/spec.rs
@@ -851,6 +851,13 @@ pub struct CommandMeta<'a> {
     /// Cold like everything else here: a group is checked once the last token has been
     /// read, by code the derive generates, and a successful parse never reads this.
     pub groups: &'a [GroupMeta<'a>],
+    /// Which runs of [`Self::flags`] came from a flattened `Args` type.
+    ///
+    /// Only [`Spec::to_kdl`] reads this, and only to write a `flagset` once instead of the
+    /// same flags under every command that flattens the struct. It changes nothing about
+    /// parsing: the flags are in `flags` either way, which is why this is a description of
+    /// where they came from rather than a table anything binds against.
+    pub flatten_groups: &'a [FlattenGroup<'a>],
 }
 
 impl CommandMeta<'_> {
@@ -886,9 +893,29 @@ impl CommandMeta<'_> {
         flags: &[],
         args: &[],
         subcommands: &[],
+        flatten_groups: &[],
     };
 }
 
+/// A run of one command's flags that arrived from a flattened `Args` type.
+///
+/// `#[usage(flatten)]` splices a struct's declarations into the command that holds it, so a
+/// set of flags shared by thirty commands is thirty identical copies in the emitted spec.
+/// This records the seam the expansion leaves behind, so [`Spec::to_kdl`] can write the set
+/// once as a `flagset` and a `use` in each command that has it.
+#[derive(Debug, Clone, Copy)]
+pub struct FlattenGroup<'a> {
+    /// The name the emitted `flagset` is given: the flattened type's, in kebab-case.
+    pub name: &'a str,
+    /// Where this group's flags begin in the flattening command's flag list.
+    pub start: usize,
+    /// The flattened type's own metadata.
+    ///
+    /// The flagset's body comes from here rather than from the parent's slice, so a struct
+    /// that flattens another can be written as a set that `use`s a set.
+    pub meta: &'a CommandMeta<'a>,
+}
+
 /// What a flag knows about itself beyond how it parses.
 #[derive(Debug, Clone, Copy)]
 pub struct FlagMeta<'a> {
@@ -1454,18 +1481,173 @@ impl Spec<'_> {
         for example in self.root.examples {
             write_example(out, example, 0)?;
         }
+        // Before the flags, since that is where the first `use` of one appears. Which sets
+        // there are is a property of the whole tree, so it is settled before anything is
+        // written rather than discovered command by command.
+        let w = Writing {
+            bin: self.bin.unwrap_or(self.name),
+            overlays,
+            sets: Flagsets::collect(self.root),
+        };
+        for entry in w.sets.written() {
+            writeln!(out, "flagset {} {{", quoted(entry.name))?;
+            write_flag_layout(out, entry.meta, 1, &w.sets)?;
+            out.push_str("}\n");
+        }
         // Nothing above the root, so what it does not state is the default.
         let mut path = Vec::new();
-        write_body(
-            out,
-            self.root,
-            0,
-            UnknownFlags::Value,
-            self.bin.unwrap_or(self.name),
-            overlays,
-            &mut path,
-        )
+        write_body(out, self.root, 0, UnknownFlags::Value, &w, &mut path)
+    }
+}
+
+/// Whether two flattened groups are the same declarations.
+///
+/// Keys are hashed from the type a declaration came from, so a matching key sequence means
+/// a matching struct. Pointer equality is tried first because it is the usual case: the same
+/// associated const, reached from every command that flattens the type.
+fn same_group(a: &CommandMeta<'_>, b: &CommandMeta<'_>) -> bool {
+    core::ptr::eq(a, b)
+        || (a.flags.len() == b.flags.len()
+            && a.flags
+                .iter()
+                .zip(b.flags)
+                .all(|(x, y)| x.flag.key == y.flag.key))
+}
+
+/// The flagsets a spec is going to write, worked out before anything is written.
+///
+/// One per flattened struct, whether it is flattened once or thirty times. A threshold —
+/// only sets with several users, or only ones that save lines — would make how a command is
+/// written depend on what some other command does, so adding a second `#[usage(flatten)]`
+/// elsewhere would restructure a command nobody touched. A `flatten` is a shared declaration
+/// wherever it appears, and this writes it as one.
+struct Flagsets<'a> {
+    entries: Vec<FlagsetEntry<'a>>,
+}
+
+struct FlagsetEntry<'a> {
+    name: &'a str,
+    meta: &'a CommandMeta<'a>,
+    /// Another type claimed this name, so it cannot stand for either of them.
+    ambiguous: bool,
+}
+
+impl<'a> Flagsets<'a> {
+    fn collect(root: &'a CommandMeta<'a>) -> Self {
+        let mut sets = Self {
+            entries: Vec::new(),
+        };
+        sets.walk(root);
+        sets
+    }
+
+    fn walk(&mut self, meta: &'a CommandMeta<'a>) {
+        for group in meta.flatten_groups {
+            self.record(group);
+        }
+        for sub in meta.subcommands {
+            self.walk(sub);
+        }
+    }
+
+    fn record(&mut self, group: &'a FlattenGroup<'a>) {
+        if let Some(entry) = self.entries.iter_mut().find(|e| e.name == group.name) {
+            if !same_group(entry.meta, group.meta) {
+                // Two flattened types whose names end in the same word. Neither can have
+                // the name, because a `use` of it would put one struct's flags on the
+                // command that asked for the other's. Both are written inline instead, which
+                // is what every flatten did before sets existed.
+                entry.ambiguous = true;
+            }
+            return;
+        }
+        self.entries.push(FlagsetEntry {
+            name: group.name,
+            meta: group.meta,
+            ambiguous: false,
+        });
+        // The sets this one composes. Recorded once, when the set is first met, because
+        // they are written inside its body rather than by everything that uses it.
+        for nested in group.meta.flatten_groups {
+            self.record(nested);
+        }
+    }
+
+    /// The sets that get written, in the order they were met.
+    fn written(&self) -> impl Iterator<Item = &FlagsetEntry<'a>> {
+        self.entries.iter().filter(|e| Self::worth_writing(e))
+    }
+
+    /// Whether a `use` may stand for this group, or its flags have to be written out.
+    fn covers(&self, group: &FlattenGroup<'_>) -> bool {
+        self.entries.iter().any(|e| {
+            e.name == group.name && Self::worth_writing(e) && same_group(e.meta, group.meta)
+        })
+    }
+
+    /// A set with no flags in it has nothing to declare and nothing to stand for: a
+    /// flattened struct may hold only positionals, which stay where they are.
+    fn worth_writing(entry: &FlagsetEntry<'_>) -> bool {
+        !entry.ambiguous && !entry.meta.flags.is_empty()
+    }
+}
+
+/// What every command in one document is written against.
+///
+/// Bundled because it is the same for all of them: the binary a completer would name, the
+/// per-command overlays a view applies, and which flagsets exist. Passing them one by one had
+/// `write_command` and `write_body` at eight parameters each, most of them pass-through.
+struct Writing<'a, 'o> {
+    bin: &'a str,
+    overlays: &'o [CommandOverlay<'o>],
+    sets: Flagsets<'a>,
+}
+
+/// Write one command's flags, as `use` for every set that stands for a run of them.
+///
+/// Shared with the body of a `flagset`, which is the same question asked of a flattened
+/// struct's own metadata — so a struct that flattens another is written as a set that uses a
+/// set, and a group written inline still uses the sets it composes.
+fn write_flag_layout(
+    out: &mut String,
+    meta: &CommandMeta<'_>,
+    depth: usize,
+    sets: &Flagsets<'_>,
+) -> core::fmt::Result {
+    let mut i = 0;
+    while i < meta.flags.len() {
+        // A group that contributed no flags has no run to stand for, and matching it would
+        // advance nothing.
+        let group = meta
+            .flatten_groups
+            .iter()
+            .find(|g| g.start == i && !g.meta.flags.is_empty());
+        match group {
+            Some(group) if sets.covers(group) => {
+                indent(out, depth)?;
+                writeln!(out, "use {}", quoted(group.name))?;
+                i += group.meta.flags.len();
+            }
+            Some(group) => {
+                write_flag_layout(out, group.meta, depth, sets)?;
+                i += group.meta.flags.len();
+            }
+            None => {
+                // The two tables are written in the same order by construction, so a
+                // mismatch means a table was edited without its metadata.
+                debug_assert!(
+                    meta.cmd
+                        .flags
+                        .get(i)
+                        .is_some_and(|f| core::ptr::eq(*f, meta.flags[i].flag)),
+                    "flag metadata is out of step with the parse table"
+                );
+                write_flag(out, &meta.flags[i], depth)?;
+                i += 1;
+            }
+        }
     }
+    Ok(())
 }
 
 /// Write a command's contents: its flags, arguments, and subcommands.
@@ -1477,8 +1659,7 @@ fn write_body<'a>(
     meta: &CommandMeta<'a>,
     depth: usize,
     inherited_unknown_flags: UnknownFlags,
-    bin: &str,
-    overlays: &[CommandOverlay<'_>],
+    w: &Writing<'_, '_>,
     path: &mut Vec<&'a str>,
 ) -> core::fmt::Result {
     // The effective setting for everything inside, which is this command's if it stated one
@@ -1501,18 +1682,7 @@ fn write_body<'a>(
         meta.subcommands.len(),
         "every subcommand in the parse table needs metadata"
     );
-    for (i, flag) in meta.flags.iter().enumerate() {
-        // The two tables are written in the same order by construction, so a
-        // mismatch means a table was edited without its metadata.
-        debug_assert!(
-            meta.cmd
-                .flags
-                .get(i)
-                .is_some_and(|f| core::ptr::eq(*f, flag.flag)),
-            "flag metadata is out of step with the parse table"
-        );
-        write_flag(out, flag, depth)?;
-    }
+    write_flag_layout(out, meta, depth, &w.sets)?;
     for (i, arg) in meta.args.iter().enumerate() {
         debug_assert!(
             meta.cmd
@@ -1530,17 +1700,9 @@ fn write_body<'a>(
         write_group(out, group, depth)?;
     }
     #[cfg(feature = "complete")]
-    write_completers(out, meta, bin, depth)?;
+    write_completers(out, meta, w.bin, depth)?;
     for sub in meta.subcommands {
-        write_command(
-            out,
-            sub,
-            depth,
-            enclosing_unknown_flags,
-            bin,
-            overlays,
-            path,
-        )?;
+        write_command(out, sub, depth, enclosing_unknown_flags, w, path)?;
     }
     Ok(())
 }
@@ -1599,8 +1761,7 @@ fn write_command<'a>(
     meta: &CommandMeta<'a>,
     depth: usize,
     inherited_unknown_flags: UnknownFlags,
-    bin: &str,
-    overlays: &[CommandOverlay<'_>],
+    w: &Writing<'_, '_>,
     path: &mut Vec<&'a str>,
 ) -> core::fmt::Result {
     path.push(meta.cmd.name);
@@ -1624,7 +1785,8 @@ fn write_command<'a>(
     if let Some(heading) = meta.help_heading {
         write!(out, " help_heading={}", quoted(heading))?;
     }
-    let effect = overlays
+    let effect = w
+        .overlays
         .iter()
         .rev()
         .find(|overlay| overlay.command.matches(meta, path))
@@ -1745,15 +1907,7 @@ fn write_command<'a>(
     for example in meta.examples {
         write_example(out, example, inner)?;
     }
-    write_body(
-        out,
-        meta,
-        inner,
-        effective_unknown_flags,
-        bin,
-        overlays,
-        path,
-    )?;
+    write_body(out, meta, inner, effective_unknown_flags, w, path)?;
 
     indent(out, depth)?;
     out.push_str("}\n");
@@ -3603,13 +3757,17 @@ mod tests {
         };
 
         let mut out = String::new();
+        let w = Writing {
+            bin: "ex",
+            overlays: &[],
+            sets: Flagsets::collect(&ROOT_META),
+        };
         write_body(
             &mut out,
             &ROOT_META,
             0,
             UnknownFlags::Value,
-            "ex",
-            &[],
+            &w,
             &mut Vec::new(),
         )
         .unwrap();
diff --git a/cli/src/cli/mod.rs b/cli/src/cli/mod.rs
index 272b0e1f9..9344e8375 100644
--- a/cli/src/cli/mod.rs
+++ b/cli/src/cli/mod.rs
@@ -20,6 +20,11 @@ mod sponsors;
 // 3.6 added `effect=` and 4.0 added it on flags and args; older `usage` CLIs reject the spec
 // outright with "unsupported cmd prop effect", so this moves in lockstep with the fields the
 // spec actually carries.
+//
+// Owed a bump: the four shell commands flatten `Shell`, which now emits a `flagset`, and no
+// 4.0 can read that node. The floor is whichever release carries flagsets, so the number waits
+// for that release rather than being guessed at here — and this crate warning about its own
+// spec until then is worse than the stale claim.
 #[derive(DeriveCli)]
 #[usage(
     bin = "usage",
diff --git a/cli/usage.usage.kdl b/cli/usage.usage.kdl
index 8522bcbb0..4f5513f71 100644
--- a/cli/usage.usage.kdl
+++ b/cli/usage.usage.kdl
@@ -9,14 +9,17 @@ about "CLI for working with usage-based CLIs"
 usage "Usage: usage <COMMAND>\n       usage --completions <COMPLETIONS>\n       usage --usage-spec"
 unknown_flags error
 subcommand_required #true
+flagset shell {
+    flag -h help="Show help"
+    flag --help help="Show help"
+}
 flag --completions help="Outputs completions for the specified shell for completing the `usage` CLI itself" {
     arg <COMPLETIONS>
 }
 flag --usage-spec help="Outputs a `usage.kdl` spec for this CLI itself"
 cmd bash help="Execute a shell script using bash" unknown_flags=value {
     long_help "Execute a shell script with the specified shell\n\nTypically, this will be called by a script's shebang.\n\nIf using `var=#true` on args/flags, they will be joined with spaces using `shell_words::join()`\nto properly escape and quote values with spaces in them."
-    flag -h help="Show help"
-    flag --help help="Show help"
+    use shell
     arg <SCRIPT>
     arg "[ARGS]..." help="Arguments to pass to script" {
         long_help "Arguments to pass to script\n\nAnything `usage` does not recognise is a value rather than a mistake, which is what\nlets a shebang script take flags of its own."
@@ -51,8 +54,7 @@ cmd exec help="Execute a script, parsing args and exposing them as environment v
 }
 cmd fish help="Execute a shell script using fish" unknown_flags=value {
     long_help "Execute a shell script with the specified shell\n\nTypically, this will be called by a script's shebang.\n\nIf using `var=#true` on args/flags, they will be joined with spaces using `shell_words::join()`\nto properly escape and quote values with spaces in them."
-    flag -h help="Show help"
-    flag --help help="Show help"
+    use shell
     arg <SCRIPT>
     arg "[ARGS]..." help="Arguments to pass to script" {
         long_help "Arguments to pass to script\n\nAnything `usage` does not recognise is a value rather than a mistake, which is what\nlets a shebang script take flags of its own."
@@ -244,8 +246,7 @@ cmd mcp help="Serve a usage spec over the Model Context Protocol" effect=read {
 }
 cmd powershell help="Execute a shell script using PowerShell" unknown_flags=value {
     long_help "Execute a shell script with the specified shell\n\nTypically, this will be called by a script's shebang.\n\nIf using `var=#true` on args/flags, they will be joined with spaces using `shell_words::join()`\nto properly escape and quote values with spaces in them."
-    flag -h help="Show help"
-    flag --help help="Show help"
+    use shell
     arg <SCRIPT>
     arg "[ARGS]..." help="Arguments to pass to script" {
         long_help "Arguments to pass to script\n\nAnything `usage` does not recognise is a value rather than a mistake, which is what\nlets a shebang script take flags of its own."
@@ -255,8 +256,7 @@ cmd sponsors help="Show the companies sponsoring usage and the jdx.dev open sour
 }
 cmd zsh help="Execute a shell script using zsh" unknown_flags=value {
     long_help "Execute a shell script with the specified shell\n\nTypically, this will be called by a script's shebang.\n\nIf using `var=#true` on args/flags, they will be joined with spaces using `shell_words::join()`\nto properly escape and quote values with spaces in them."
-    flag -h help="Show help"
-    flag --help help="Show help"
+    use shell
     arg <SCRIPT>
     arg "[ARGS]..." help="Arguments to pass to script" {
         long_help "Arguments to pass to script\n\nAnything `usage` does not recognise is a value rather than a mistake, which is what\nlets a shebang script take flags of its own."
diff --git a/conformance/src/tables.rs b/conformance/src/tables.rs
index c9c8197a8..09b9c3912 100644
--- a/conformance/src/tables.rs
+++ b/conformance/src/tables.rs
@@ -172,6 +172,9 @@ pub fn build(
         groups: groups(&cmd.groups),
         flags: Box::leak(flag_metas.into_boxed_slice()),
         args: Box::leak(arg_metas.into_boxed_slice()),
+        // A spec read from KDL has already had its `use` nodes resolved, so there is no seam
+        // left to record: these tables come from flags, not from the struct that declared them.
+        flatten_groups: &[],
         subcommands: Box::leak(
             subs.iter()
                 .map(|s| s.meta)
diff --git a/conformance/tests/flatten.rs b/conformance/tests/flatten.rs
index b0d5245d6..f93f80225 100644
--- a/conformance/tests/flatten.rs
+++ b/conformance/tests/flatten.rs
@@ -2,9 +2,13 @@
 //!
 //! mise writes `ConfigLs` once and gives it to both `config` and `config ls`, so that
 //! `mise config --no-header` and `mise config ls --no-header` accept the same flags. Ten
-//! commands do this. It is a Rust-side device with no counterpart in the spec: the emitted
-//! KDL lists the flags inline, exactly as a hand-written command would, because a spec
-//! describes what a CLI accepts and not how the declarations were organised.
+//! commands do this. The spec has a counterpart for it — a `flagset`, and a `use` on each
+//! command that has the flags — so the emitted KDL says it once too, rather than repeating
+//! the declarations under every command.
+//!
+//! What a command *accepts* is the same either way, which is the property these tests hold:
+//! the reference parser resolves a `use` while it reads the file, so a spec with sets and
+//! the same spec written out flat describe one CLI.
 //!
 //! The tables are joined at compile time, so the parser walks one flat slice and flatten
 //! costs nothing at run time.
@@ -131,9 +135,9 @@ fn a_flattened_declaration_is_still_checked() {
 }
 
 #[test]
-fn the_spec_shows_the_flags_inline() {
-    // A spec has no idea of flattening, and does not need one: what reaches the KDL is the
-    // command with every flag it accepts, indistinguishable from one written out by hand.
+fn the_spec_says_the_flags_are_shared() {
+    // The shared declarations reach the KDL as a set the two commands use, and every flag
+    // is still on every command that accepts it once the reference parser has read it.
     let kdl = Ex::to_kdl();
     let spec: LibSpec = kdl.parse().expect("valid spec");
     let config = spec.cmd.subcommands.get("config").expect("config");
@@ -166,9 +170,13 @@ fn the_spec_shows_the_flags_inline() {
         Some("Do not print a header")
     );
 
-    // Nothing about the Rust-side arrangement leaks in.
+    // Said once, and used by both commands rather than copied into each.
+    assert!(kdl.contains("flagset listing {"), "{kdl}");
+    assert_eq!(kdl.matches("use listing").count(), 2, "{kdl}");
+    assert_eq!(kdl.matches("flag --no-header").count(), 1, "{kdl}");
+    // The set is a spec node. How the Rust side arranged it — the attribute, the field name
+    // holding the struct — still does not appear.
     assert!(!kdl.contains("flatten"), "{kdl}");
-    assert!(!kdl.contains("listing"), "{kdl}");
 }
 
 /// A parent with a required flag of its own, to pit against a flattened rule.
diff --git a/derive/src/codegen.rs b/derive/src/codegen.rs
index bc1cbf902..b742d7987 100644
--- a/derive/src/codegen.rs
+++ b/derive/src/codegen.rs
@@ -17,8 +17,8 @@ use quote::{format_ident, quote};
 
 use crate::crate_name::{crate_name, FoundCrate};
 use crate::model::{
-    rendered_path, to_kebab, Cli, ConditionalDefault, Dispatch, DoubleDash, ExampleDecl, Field,
-    Kind, Shape, Subcommands, ValueEnum, ViewDecl,
+    rendered_path, to_kebab, type_name, Cli, ConditionalDefault, Dispatch, DoubleDash,
+    ExampleDecl, Field, Kind, Shape, Subcommands, ValueEnum, ViewDecl,
 };
 
 /// Construct the user's command type after its generated partial has been checked.
@@ -207,6 +207,7 @@ pub fn emit(cli: &Cli) -> TokenStream {
     let arg_table_ref = &tables.args;
     let flag_meta_table_ref = &tables.flag_metas;
     let arg_meta_table_ref = &tables.arg_metas;
+    let flatten_group_table_ref = &tables.flatten_groups;
 
     let name = &cli.name;
     let bin = option_str(cli.bin.as_deref());
@@ -627,6 +628,7 @@ pub fn emit(cli: &Cli) -> TokenStream {
                 flags: #flag_meta_table_ref,
                 args: #arg_meta_table_ref,
                 groups: #group_meta_table_ref,
+                flatten_groups: #flatten_group_table_ref,
                 #sub_metas
                 ..usage_argv::spec::CommandMeta::EMPTY
             };
@@ -2402,6 +2404,9 @@ struct Tables {
     args: TokenStream,
     flag_metas: TokenStream,
     arg_metas: TokenStream,
+    /// Where each flattened struct's flags landed, for the emitted spec to write one
+    /// `flagset` instead of the same flags under every command that flattens it.
+    flatten_groups: TokenStream,
 }
 
 /// Build the four expressions, splicing any flattened groups into place.
@@ -2420,6 +2425,13 @@ fn tables(cli: &Cli) -> Tables {
     let mut own_args: Vec<usize> = Vec::new();
     let (mut flag_at, mut arg_at) = (0usize, 0usize);
     let mut flattened = false;
+    // One entry per flattened field, naming the struct and where its flags begin. The
+    // offset is written as a sum rather than a number because the lengths that make it up
+    // belong to other structs' tables: `.len()` on a const slice is a const expression, so
+    // the arithmetic happens where the rest of the table does.
+    let mut flatten_groups: Vec<TokenStream> = Vec::new();
+    let mut flag_offset: Vec<TokenStream> = Vec::new();
+    let mut own_since_flatten = 0usize;
 
     // Flush the runs collected so far, so that what follows lands after them.
     fn flush_flags(
@@ -2462,6 +2474,7 @@ fn tables(cli: &Cli) -> Tables {
             Kind::Flag { .. } => {
                 own_flags.push(flag_at);
                 flag_at += 1;
+                own_since_flatten += 1;
             }
             Kind::Arg { .. } => {
                 own_args.push(arg_at);
@@ -2469,6 +2482,21 @@ fn tables(cli: &Cli) -> Tables {
             }
             Kind::Flatten { ty } => {
                 flattened = true;
+                if own_since_flatten > 0 {
+                    flag_offset.push(quote!(#own_since_flatten));
+                    own_since_flatten = 0;
+                }
+                let name = flagset_name(ty);
+                let terms = flag_offset.iter();
+                flatten_groups.push(quote! {
+                    usage_argv::spec::FlattenGroup {
+                        name: #name,
+                        start: 0 #(+ #terms)*,
+                        meta: <#ty as usage_argv::spec::CommandArgs>::META,
+                    }
+                });
+                flag_offset
+                    .push(quote!(<#ty as usage_argv::spec::CommandArgs>::COMMAND.flags.len()));
                 flush_flags(&mut own_flags, &mut flag_groups, &mut flag_meta_groups);
                 flush_args(&mut own_args, &mut arg_groups, &mut arg_meta_groups);
                 flag_groups.push(quote!(<#ty as usage_argv::spec::CommandArgs>::COMMAND.flags));
@@ -2501,6 +2529,7 @@ fn tables(cli: &Cli) -> Tables {
             args: quote!(&[#(#arg_refs),*]),
             flag_metas: quote!(&[#(#flag_meta_refs),*]),
             arg_metas: quote!(&[#(#arg_meta_refs),*]),
+            flatten_groups: quote!(&[]),
         };
     }
 
@@ -2525,14 +2554,34 @@ fn tables(cli: &Cli) -> Tables {
             static ARG_METAS: [usage_argv::spec::ArgMeta<'static>;
                 usage_argv::table_len(ARG_META_GROUPS)] =
                 usage_argv::spec::concat_arg_metas(ARG_META_GROUPS);
+            const FLATTEN_GROUPS: &[usage_argv::spec::FlattenGroup<'static>] =
+                &[#(#flatten_groups),*];
         },
         flags: quote!(&FLAGS),
         args: quote!(&ARGS),
         flag_metas: quote!(&FLAG_METAS),
         arg_metas: quote!(&ARG_METAS),
+        flatten_groups: quote!(FLATTEN_GROUPS),
     }
 }
 
+/// The name a flattened struct's flagset is given: its own, in kebab-case.
+///
+/// The last path segment only, so `cli::CommonArgs` and `super::CommonArgs` name the same
+/// set — which they must, since they are the same struct. Two different structs whose names
+/// end in the same word collide, and [`usage_argv::spec::Spec::to_kdl`] resolves that by
+/// writing neither as a set rather than by guessing which one meant it.
+fn flagset_name(ty: &syn::Type) -> String {
+    let rendered = type_name(ty);
+    let last = rendered
+        .rsplit("::")
+        .next()
+        .unwrap_or(&rendered)
+        .trim()
+        .to_string();
+    to_kebab(&last)
+}
+
 fn flag_arm(cli: &Cli, i: usize, field: &Field) -> TokenStream {
     let key = key_ident("FLAG", Some(i));
     let ident = &field.ident;
@@ -4811,6 +4860,7 @@ pub fn emit_args(cli: &Cli) -> TokenStream {
     let arg_table_ref = &tables.args;
     let flag_meta_table_ref = &tables.flag_metas;
     let arg_meta_table_ref = &tables.arg_metas;
+    let flatten_group_table_ref = &tables.flatten_groups;
 
     let name = &cli.name;
     let aliases = cli.aliases.iter().chain(&cli.hidden_aliases);
@@ -5053,6 +5103,7 @@ pub fn emit_args(cli: &Cli) -> TokenStream {
                 flags: #flag_meta_table_ref,
                 args: #arg_meta_table_ref,
                 groups: #group_meta_table_ref,
+                flatten_groups: #flatten_group_table_ref,
                 #sub_metas
                 ..usage_argv::spec::CommandMeta::EMPTY
             };
diff --git a/docs/rust/subcommands.md b/docs/rust/subcommands.md
index fd4b6f5a7..db88aab0e 100644
--- a/docs/rust/subcommands.md
+++ b/docs/rust/subcommands.md
@@ -163,9 +163,37 @@ struct Config {
 }
 ```
 
-The tables are joined at compile time and the emitted KDL lists the flags inline — a consumer of
-the spec can't tell a flattened flag from a declared one. Groups and `exclusive` flags declared
-on the flattened struct are enforced (and emitted) on the command that flattens them.
+The tables are joined at compile time, so the parser walks one flat slice and `flatten` costs
+nothing at run time. Groups and `exclusive` flags declared on the flattened struct are enforced
+(and emitted) on the command that flattens them.
+
+The emitted KDL says the declarations are shared, rather than repeating them under each command:
+the struct becomes a [`flagset`](/spec/reference/flagset) named after it, and every command that
+flattens it gets a `use`.
+
+```kdl
+flagset listing {
+    flag --no-header help="Do not print a header"
+    flag --format help="Output format" {
+        arg <FORMAT> {
+            choices json table
+        }
+    }
+}
+cmd config {
+    flag "-f --file" {
+        arg <FILE>
+    }
+    use listing
+}
+```
+
+A `use` is resolved while the spec is read, so what a command accepts is exactly what it was
+when the flags were written out: anything reading the spec — docs, manpages, completions, another
+implementation — sees `config` with all three flags. A struct that flattens another becomes a set
+that uses a set. Positionals stay on each command, since a set holds flags only, and two flattened
+structs whose names end in the same word get no set at all — one name cannot stand for both, so
+both are written inline.
 
 A flattened struct may not declare subcommands; that's a compile-time error with an explanation.
 
diff --git a/docs/spec/reference/flagset.md b/docs/spec/reference/flagset.md
index ccf1b4abe..9d5c30624 100644
--- a/docs/spec/reference/flagset.md
+++ b/docs/spec/reference/flagset.md
@@ -194,6 +194,18 @@ declaration means the same thing under any command. A positional is identified b
 position, so the same set spliced into two commands with different arguments would mean
 two different things. Declaring `arg` inside a `flagset` is an error rather than a guess.
 
+## What the derive emits
+
+The typed Rust side has its own way to share declarations —
+[`#[usage(flatten)]`](/rust/subcommands#sharing-declarations-with-flatten) — and it lowers into
+this node: a flattened struct becomes one `flagset` named after it, and every command that
+flattens the struct gets a `use`. So a CLI written in Rust and a CLI written as a spec say the
+same thing the same way, which is the point of the node existing on both sides.
+
+Two flattened structs whose names end in the same word cannot both have the name, so neither gets
+it and both are written inline. That is never wrong, only longer — but it is worth knowing if a
+set you expected did not appear.
+
 ## One-way
 
 Expansion is part of reading the file. A spec that is parsed and re-emitted — by
diff --git a/usage-rs/tests/facade.rs b/usage-rs/tests/facade.rs
index f96da0a77..3ccdd2ba1 100644
--- a/usage-rs/tests/facade.rs
+++ b/usage-rs/tests/facade.rs
@@ -2852,3 +2852,278 @@ fn the_endpoint_wins_over_default_subcommand_routing() {
     // that wants the word back declares it, or sets `spec_endpoint = false`.
     assert!(DefaultSubcommandEx::spec_request(&[OsStr::new(usage::SPEC_REQUEST)]).is_some());
 }
+
+// A struct flattened into more than one command: the shape mise has 200-odd times over, and
+// the reason the emitted spec used to repeat itself.
+#[derive(Args)]
+#[allow(dead_code)]
+struct SharedFlags {
+    /// Print more.
+    #[arg(long, short)]
+    verbose: bool,
+    /// How many at once.
+    #[arg(long)]
+    jobs: Option<usize>,
+}
+
+#[derive(Args)]
+#[allow(dead_code)]
+struct BuildCmd {
+    #[arg(long)]
+    release: bool,
+    #[usage(flatten)]
+    shared: SharedFlags,
+    #[arg(long)]
+    target: Option<String>,
+}
+
+#[derive(Args)]
+#[allow(dead_code)]
+struct TestCmd {
+    #[usage(flatten)]
+    shared: SharedFlags,
+}
+
+#[derive(Subcommands)]
+#[allow(dead_code)]
+enum FlagsetCommand {
+    Build(BuildCmd),
+    Test(TestCmd),
+}
+
+#[derive(Cli)]
+#[usage(bin = "flagset-ex")]
+#[allow(dead_code)]
+struct FlagsetEx {
+    #[usage(subcommand)]
+    command: FlagsetCommand,
+}
+
+#[test]
+fn a_struct_flattened_twice_is_written_once_as_a_flagset() {
+    let kdl = FlagsetEx::to_kdl();
+    assert!(kdl.contains("flagset shared-flags {"), "{kdl}");
+    // Two commands, one set, and the flags written once rather than under each.
+    assert_eq!(kdl.matches("use shared-flags").count(), 2, "{kdl}");
+    assert_eq!(kdl.matches("flag \"-v --verbose\"").count(), 1, "{kdl}");
+
+    // The set stands where the struct did, so help order is still declaration order.
+    let spec: usage_parser::Spec = kdl.parse().expect("the emitted set should parse back");
+    let build = spec.cmd.subcommands.get("build").expect("build");
+    let flags: Vec<&str> = build.flags.iter().map(|f| f.name.as_str()).collect();
+    assert_eq!(flags, ["release", "verbose", "jobs", "target"], "{kdl}");
+    let test = spec.cmd.subcommands.get("test").expect("test");
+    let flags: Vec<&str> = test.flags.iter().map(|f| f.name.as_str()).collect();
+    assert_eq!(flags, ["verbose", "jobs"], "{kdl}");
+
+    // Help text and values survive the trip, not just the names: a set that lost them
+    // would still pass the assertions above.
+    let verbose = build
+        .flags
+        .iter()
+        .find(|f| f.name == "verbose")
+        .expect("verbose");
+    assert_eq!(verbose.help.as_deref(), Some("Print more."));
+    assert_eq!(verbose.short, vec!['v']);
+    let jobs = build.flags.iter().find(|f| f.name == "jobs").expect("jobs");
+    assert!(jobs.arg.is_some(), "{kdl}");
+}
+
+#[test]
+fn what_the_flagset_expands_to_is_what_the_typed_parse_binds() {
+    // The emitted spec is what docs, completions and other implementations read, so the
+    // question is not only whether it parses but whether it means the same thing.
+    let spec: usage_parser::Spec = FlagsetEx::to_kdl().parse().expect("parses");
+    let words = ["flagset-ex", "build", "--verbose", "--jobs", "4"].map(String::from);
+    let parsed = usage_parser::parse(&spec, &words).expect("the reference parser binds it");
+    assert_eq!(
+        parsed.as_env().get("usage_jobs").map(String::as_str),
+        Some("4")
+    );
+
+    let typed = FlagsetEx::parse_from(&[
+        OsStr::new("build"),
+        OsStr::new("--verbose"),
+        OsStr::new("--jobs"),
+        OsStr::new("4"),
+    ])
+    .expect("the typed parse binds it too");
+    let FlagsetCommand::Build(build) = typed.command else {
+        panic!("build should have been selected");
+    };
+    assert!(build.shared.verbose);
+    assert_eq!(build.shared.jobs, Some(4));
+}
+
+// A set assembled from a smaller one, which is the composition the spec node allows.
+#[derive(Args)]
+#[allow(dead_code)]
+struct InnerFlags {
+    #[arg(long)]
+    inner: bool,
+}
+
+#[derive(Args)]
+#[allow(dead_code)]
+struct OuterFlags {
+    #[usage(flatten)]
+    inner: InnerFlags,
+    #[arg(long)]
+    outer: bool,
+}
+
+#[derive(Args)]
+#[allow(dead_code)]
+struct NestedOne {
+    #[usage(flatten)]
+    outer: OuterFlags,
+}
+
+#[derive(Args)]
+#[allow(dead_code)]
+struct NestedTwo {
+    #[usage(flatten)]
+    outer: OuterFlags,
+}
+
+#[derive(Subcommands)]
+#[allow(dead_code)]
+enum NestedFlagsetCommand {
+    One(NestedOne),
+    Two(NestedTwo),
+}
+
+#[derive(Cli)]
+#[usage(bin = "nested-flagset-ex")]
+#[allow(dead_code)]
+struct NestedFlagsetEx {
+    #[usage(subcommand)]
+    command: NestedFlagsetCommand,
+}
+
+#[test]
+fn a_struct_that_flattens_another_is_a_set_that_uses_a_set() {
+    let kdl = NestedFlagsetEx::to_kdl();
+    assert!(kdl.contains("flagset inner-flags {"), "{kdl}");
+    assert!(kdl.contains("flagset outer-flags {"), "{kdl}");
+    // `--inner` is declared once, inside its own set, and the outer set uses it rather
+    // than holding a copy.
+    assert_eq!(kdl.matches("flag --inner").count(), 1, "{kdl}");
+    assert_eq!(kdl.matches("use inner-flags").count(), 1, "{kdl}");
+    assert_eq!(kdl.matches("use outer-flags").count(), 2, "{kdl}");
+
+    let spec: usage_parser::Spec = kdl.parse().expect("composed sets should parse back");
+    for name in ["one", "two"] {
+        let cmd = spec.cmd.subcommands.get(name).expect(name);
+        let flags: Vec<&str> = cmd.flags.iter().map(|f| f.name.as_str()).collect();
+        assert_eq!(flags, ["inner", "outer"], "{name}: {kdl}");
+    }
+}
+
+// A flattened struct holding only positionals. There is no set of flags to name, and the
+// arguments stay on each command that flattens it.
+#[derive(Args)]
+#[allow(dead_code)]
+struct PositionalsOnly {
+    script: String,
+}
+
+#[derive(Args)]
+#[allow(dead_code)]
+struct RunsAScript {
+    #[usage(flatten)]
+    script: PositionalsOnly,
+}
+
+#[derive(Cli)]
+#[usage(bin = "args-only-ex")]
+#[allow(dead_code)]
+struct ArgsOnlyEx {
+    #[usage(flatten)]
+    script: PositionalsOnly,
+}
+
+#[test]
+fn a_flattened_struct_with_no_flags_declares_no_set() {
+    let kdl = ArgsOnlyEx::to_kdl();
+    assert!(!kdl.contains("flagset"), "{kdl}");
+    assert!(!kdl.contains("use "), "{kdl}");
+    assert!(kdl.contains("arg <SCRIPT>"), "{kdl}");
+}
+
+mod first {
+    #[derive(usage_rs::Args)]
+    #[allow(dead_code)]
+    pub struct Collides {
+        #[arg(long)]
+        pub left: bool,
+    }
+}
+
+mod second {
+    #[derive(usage_rs::Args)]
+    #[allow(dead_code)]
+    pub struct Collides {
+        #[arg(long)]
+        pub right: bool,
+    }
+}
+
+#[derive(Args)]
+#[allow(dead_code)]
+struct UsesFirst {
+    #[usage(flatten)]
+    inner: first::Collides,
+}
+
+#[derive(Args)]
+#[allow(dead_code)]
+struct UsesSecond {
+    #[usage(flatten)]
+    inner: second::Collides,
+}
+
+#[derive(Subcommands)]
+#[allow(dead_code)]
+enum CollidingCommand {
+    One(UsesFirst),
+    Two(UsesSecond),
+}
+
+#[derive(Cli)]
+#[usage(bin = "colliding-ex")]
+#[allow(dead_code)]
+struct CollidingEx {
+    #[usage(subcommand)]
+    command: CollidingCommand,
+}
+
+#[test]
+fn two_structs_whose_names_end_the_same_way_get_no_set_at_all() {
+    // A set named for one of them would put its flags on the command that asked for the
+    // other's, so neither gets the name and both are written inline — which is what every
+    // flatten did before sets existed, and is never wrong, only longer.
+    let kdl = CollidingEx::to_kdl();
+    assert!(!kdl.contains("flagset collides"), "{kdl}");
+    assert!(!kdl.contains("use collides"), "{kdl}");
+
+    let spec: usage_parser::Spec = kdl.parse().expect("parses");
+    let one = spec.cmd.subcommands.get("one").expect("one");
+    assert_eq!(
+        one.flags
+            .iter()
+            .map(|f| f.name.as_str())
+            .collect::<Vec<_>>(),
+        ["left"],
+        "{kdl}"
+    );
+    let two = spec.cmd.subcommands.get("two").expect("two");
+    assert_eq!(
+        two.flags
+            .iter()
+            .map(|f| f.name.as_str())
+            .collect::<Vec<_>>(),
+        ["right"],
+        "{kdl}"
+    );
+}

From 458aab5a2ba0978a753bd7bfab2b5cc5349c74e4 Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Fri, 21 Aug 2026 13:50:04 +0000
Subject: [PATCH 2/3] fix(spec): a flagset collision does not hide the one
 inside it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When two flattened structs' names end in the same word, neither gets the name and
both are written inline. Marking that returned early, before walking what the
second struct itself flattens — so if the structs *those* held also collided, the
inner pair was never compared. The first one walked kept the name, and which
command got a `use` for it came down to traversal order rather than to anything
either command said.

The output was never wrong, because a `use` is only written for a group whose
flags match the set's, so the command holding the other struct still had its flags
inline. What was wrong is that one of two colliding structs got a set while the
rule says neither does, and that adding a `flatten` elsewhere in the tree could
move it.

Found by Cursor Bugbot on #1172.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 argv/src/spec.rs         | 21 ++++++++---
 derive/src/codegen.rs    |  4 +-
 usage-rs/tests/facade.rs | 80 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 97 insertions(+), 8 deletions(-)

diff --git a/argv/src/spec.rs b/argv/src/spec.rs
index f020c3e2b..c90482f52 100644
--- a/argv/src/spec.rs
+++ b/argv/src/spec.rs
@@ -1552,12 +1552,21 @@ impl<'a> Flagsets<'a> {
 
     fn record(&mut self, group: &'a FlattenGroup<'a>) {
         if let Some(entry) = self.entries.iter_mut().find(|e| e.name == group.name) {
-            if !same_group(entry.meta, group.meta) {
-                // Two flattened types whose names end in the same word. Neither can have
-                // the name, because a `use` of it would put one struct's flags on the
-                // command that asked for the other's. Both are written inline instead, which
-                // is what every flatten did before sets existed.
-                entry.ambiguous = true;
+            if same_group(entry.meta, group.meta) {
+                // The same struct again, whose own sets were recorded the first time.
+                return;
+            }
+            // Two flattened types whose names end in the same word. Neither can have the
+            // name, because a `use` of it would put one struct's flags on the command that
+            // asked for the other's. Both are written inline instead, which is what every
+            // flatten did before sets existed.
+            entry.ambiguous = true;
+            // Its nested sets are still sets, and still have to face the same-name rule:
+            // returning here left whatever this one composes uncompared, so which of two
+            // colliding nested structs got the name came down to which parent was walked
+            // first.
+            for nested in group.meta.flatten_groups {
+                self.record(nested);
             }
             return;
         }
diff --git a/derive/src/codegen.rs b/derive/src/codegen.rs
index b742d7987..96c6cc30f 100644
--- a/derive/src/codegen.rs
+++ b/derive/src/codegen.rs
@@ -17,8 +17,8 @@ use quote::{format_ident, quote};
 
 use crate::crate_name::{crate_name, FoundCrate};
 use crate::model::{
-    rendered_path, to_kebab, type_name, Cli, ConditionalDefault, Dispatch, DoubleDash,
-    ExampleDecl, Field, Kind, Shape, Subcommands, ValueEnum, ViewDecl,
+    rendered_path, to_kebab, type_name, Cli, ConditionalDefault, Dispatch, DoubleDash, ExampleDecl,
+    Field, Kind, Shape, Subcommands, ValueEnum, ViewDecl,
 };
 
 /// Construct the user's command type after its generated partial has been checked.
diff --git a/usage-rs/tests/facade.rs b/usage-rs/tests/facade.rs
index 3ccdd2ba1..f121a890e 100644
--- a/usage-rs/tests/facade.rs
+++ b/usage-rs/tests/facade.rs
@@ -3058,6 +3058,16 @@ mod first {
         #[arg(long)]
         pub left: bool,
     }
+
+    /// Holds a colliding struct, and collides itself.
+    #[derive(usage_rs::Args)]
+    #[allow(dead_code)]
+    pub struct Nested {
+        #[usage(flatten)]
+        pub inner: Collides,
+        #[arg(long)]
+        pub one: bool,
+    }
 }
 
 mod second {
@@ -3067,6 +3077,15 @@ mod second {
         #[arg(long)]
         pub right: bool,
     }
+
+    #[derive(usage_rs::Args)]
+    #[allow(dead_code)]
+    pub struct Nested {
+        #[usage(flatten)]
+        pub inner: Collides,
+        #[arg(long)]
+        pub two: bool,
+    }
 }
 
 #[derive(Args)]
@@ -3127,3 +3146,64 @@ fn two_structs_whose_names_end_the_same_way_get_no_set_at_all() {
         "{kdl}"
     );
 }
+
+#[derive(Args)]
+#[allow(dead_code)]
+struct NestsFirst {
+    #[usage(flatten)]
+    nested: first::Nested,
+}
+
+#[derive(Args)]
+#[allow(dead_code)]
+struct NestsSecond {
+    #[usage(flatten)]
+    nested: second::Nested,
+}
+
+#[derive(Subcommands)]
+#[allow(dead_code)]
+enum NestedCollidingCommand {
+    One(NestsFirst),
+    Two(NestsSecond),
+}
+
+#[derive(Cli)]
+#[usage(bin = "nested-colliding-ex")]
+#[allow(dead_code)]
+struct NestedCollidingEx {
+    #[usage(subcommand)]
+    command: NestedCollidingCommand,
+}
+
+#[test]
+fn a_collision_does_not_hide_the_one_inside_it() {
+    // Both `Nested` types collide, and so do the `Collides` types they hold. Stopping at the
+    // outer collision left the inner pair uncompared, so whichever parent was walked first
+    // gave its `Collides` the name — and which command got a `use` came down to traversal
+    // order rather than to anything either command said.
+    let kdl = NestedCollidingEx::to_kdl();
+    assert!(!kdl.contains("flagset nested"), "{kdl}");
+    assert!(!kdl.contains("flagset collides"), "{kdl}");
+    assert!(!kdl.contains("use collides"), "{kdl}");
+
+    let spec: usage_parser::Spec = kdl.parse().expect("parses");
+    let one = spec.cmd.subcommands.get("one").expect("one");
+    assert_eq!(
+        one.flags
+            .iter()
+            .map(|f| f.name.as_str())
+            .collect::<Vec<_>>(),
+        ["left", "one"],
+        "{kdl}"
+    );
+    let two = spec.cmd.subcommands.get("two").expect("two");
+    assert_eq!(
+        two.flags
+            .iter()
+            .map(|f| f.name.as_str())
+            .collect::<Vec<_>>(),
+        ["right", "two"],
+        "{kdl}"
+    );
+}

From 3bb01c217cb05319773257c0c00ae3e016d1dbd9 Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Fri, 21 Aug 2026 21:23:15 +0000
Subject: [PATCH 3/3] feat(config): ask for provenance by key, like a value
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`Resolved` answered values by dotted key and provenance only by `PropId`,
so the two halves of one resolution were reached for differently. A
settings listing walks keys, and the shortest way to ask where a value
came from was `origin(registry.lookup(key)?.id)` — a mouthful that the
crate's own headline doc example and fifteen of its tests all wrote out.

pitchfork's port of `settings list` hit the same wall and went around it:
it renders the value and the default and compares the strings, which
calls an explicit override that happens to equal the default unset. That
is the exact confusion an origin-tracked merge exists to end, reached by
a first adopter, because the accessor that answers it was not there.

So `origin_key` and `contributors_key`, folding renames the way `get_key`
does — provenance that named a different setting than the value did
would be the split between two answers this crate is written to prevent.
The call sites that spelled the lookup out now don't.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 config/src/cli.rs                            |  14 +--
 config/src/env.rs                            |  28 ++---
 config/src/files.rs                          |  11 +-
 config/src/lib.rs                            |   2 +-
 config/src/resolve.rs                        | 121 +++++++++++++++++++
 conformance/tests/derive_settings.rs         |  12 +-
 conformance/tests/derive_settings_env.rs     |   8 +-
 conformance/tests/derive_settings_flatten.rs |   4 +-
 8 files changed, 145 insertions(+), 55 deletions(-)

diff --git a/config/src/cli.rs b/config/src/cli.rs
index adf6e8594..e0dd7b772 100644
--- a/config/src/cli.rs
+++ b/config/src/cli.rs
@@ -28,7 +28,7 @@
 //! assert_eq!(resolved.get_key("jobs"), Some(&Value::Int(8)));
 //! // Named as the flag rather than as "the command line", so an explanation is actionable.
 //! assert_eq!(
-//!     resolved.origin(REGISTRY.lookup("jobs").unwrap().id).unwrap().describe(),
+//!     resolved.origin_key("jobs").unwrap().describe(),
 //!     "--jobs",
 //! );
 //! # Ok::<(), usage_config::LayerError>(())
@@ -216,9 +216,7 @@ mod tests {
         // Named as the flag, not as "the command line": a user who does not like the answer needs to
         // know what to stop passing.
         assert_eq!(
-            resolved
-                .origin(REGISTRY.lookup("jobs").expect("declared").id)
-                .map(|o| o.describe()),
+            resolved.origin_key("jobs").map(|o| o.describe()),
             Some("--jobs")
         );
     }
@@ -286,9 +284,7 @@ mod tests {
         let resolved = resolve(REGISTRY, Layers::new().then(&cli)).expect("resolves");
         assert_eq!(resolved.get_key("stash"), Some(&Value::from("none")));
         assert_eq!(
-            resolved
-                .origin(REGISTRY.lookup("stash").expect("declared").id)
-                .map(|o| o.describe()),
+            resolved.origin_key("stash").map(|o| o.describe()),
             Some("stash")
         );
     }
@@ -307,9 +303,7 @@ mod tests {
             "still folds"
         );
         assert_eq!(
-            resolved
-                .origin(REGISTRY.lookup("jobs").expect("declared").id)
-                .map(|o| o.describe()),
+            resolved.origin_key("jobs").map(|o| o.describe()),
             Some("--concurrency")
         );
     }
diff --git a/config/src/env.rs b/config/src/env.rs
index 35d27692f..998c827f8 100644
--- a/config/src/env.rs
+++ b/config/src/env.rs
@@ -281,9 +281,7 @@ mod tests {
         assert!(resolved.warnings.is_empty(), "{:?}", resolved.warnings);
         // The name the user set is what an explanation names.
         assert_eq!(
-            resolved
-                .origin(REGISTRY.lookup("jobs").expect("declared").id)
-                .map(|o| o.describe()),
+            resolved.origin_key("jobs").map(|o| o.describe()),
             Some("HK_JOBS")
         );
     }
@@ -296,12 +294,11 @@ mod tests {
         let layer = env(&[("HK_JOB", "2"), ("HK_JOBS", "8")]);
         let resolved = resolve(REGISTRY, Layers::new().then(&layer)).expect("resolves");
         assert_eq!(resolved.get_key("jobs"), Some(&Value::Int(8)));
-        let id = REGISTRY.lookup("jobs").expect("declared").id;
         assert_eq!(
-            resolved.contributors(id).len(),
+            resolved.contributors_key("jobs").len(),
             2,
             "the default and one variable, not both variables: {:?}",
-            resolved.contributors(id)
+            resolved.contributors_key("jobs")
         );
 
         // And with only the older one set, it is read.
@@ -309,7 +306,7 @@ mod tests {
         let resolved = resolve(REGISTRY, Layers::new().then(&layer)).expect("resolves");
         assert_eq!(resolved.get_key("jobs"), Some(&Value::Int(2)));
         assert_eq!(
-            resolved.origin(id).map(|o| o.describe()),
+            resolved.origin_key("jobs").map(|o| o.describe()),
             Some("HK_JOB"),
             "named as the user set it"
         );
@@ -317,10 +314,9 @@ mod tests {
 
     #[test]
     fn a_deprecated_environment_alias_is_read_last_and_warned_about() {
-        let id = REGISTRY.lookup("jobs").expect("declared").id;
         let resolved =
             resolve(REGISTRY, Layers::new().then(&env(&[("HK_JOBS_OLD", "3")]))).expect("resolves");
-        assert_eq!(resolved.get(id), Some(&Value::Int(3)));
+        assert_eq!(resolved.get_key("jobs"), Some(&Value::Int(3)));
         let warnings = crate::explain::warnings(&resolved);
         assert_eq!(warnings.len(), 1, "{warnings:?}");
         assert!(
@@ -334,7 +330,7 @@ mod tests {
             Layers::new().then(&env(&[("HK_JOBS", "8"), ("HK_JOBS_OLD", "3")])),
         )
         .expect("resolves");
-        assert_eq!(resolved.get(id), Some(&Value::Int(8)));
+        assert_eq!(resolved.get_key("jobs"), Some(&Value::Int(8)));
         assert!(resolved.warnings.is_empty(), "{:?}", resolved.warnings);
     }
 
@@ -362,15 +358,14 @@ mod tests {
 
     #[test]
     fn a_current_renamed_variable_beats_a_deprecated_target_alias() {
-        let id = REGISTRY.lookup("jobs").expect("declared").id;
         let resolved = resolve(
             REGISTRY,
             Layers::new().then(&env(&[("HK_JOBS_OLD", "3"), ("HK_CONCURRENCY", "6")])),
         )
         .expect("resolves");
-        assert_eq!(resolved.get(id), Some(&Value::Int(6)));
+        assert_eq!(resolved.get_key("jobs"), Some(&Value::Int(6)));
         assert_eq!(
-            resolved.origin(id).map(|origin| origin.describe()),
+            resolved.origin_key("jobs").map(|origin| origin.describe()),
             Some("HK_CONCURRENCY")
         );
         let warnings = crate::explain::warnings(&resolved);
@@ -461,9 +456,8 @@ mod tests {
         let layer = env(&[("HK_CONCURRENCY", "6"), ("HK_JOBS", "8")]);
         let resolved = resolve(REGISTRY, Layers::new().then(&layer)).expect("resolves");
         assert_eq!(resolved.get_key("jobs"), Some(&Value::Int(8)));
-        let id = REGISTRY.lookup("jobs").expect("declared").id;
         assert_eq!(
-            resolved.origin(id).map(|o| o.describe()),
+            resolved.origin_key("jobs").map(|o| o.describe()),
             Some("HK_JOBS"),
             "the name that is not deprecated"
         );
@@ -614,9 +608,7 @@ mod tests {
         // And reported as the user spelled it, not as the spec declares it: this is the only
         // platform where those can differ, so it is the only place the difference can be asserted.
         assert_eq!(
-            resolved
-                .origin(REGISTRY.lookup("jobs").expect("declared").id)
-                .map(|o| o.describe()),
+            resolved.origin_key("jobs").map(|o| o.describe()),
             Some("Hk_Jobs")
         );
     }
diff --git a/config/src/files.rs b/config/src/files.rs
index e960f94b5..ba9f40ea5 100644
--- a/config/src/files.rs
+++ b/config/src/files.rs
@@ -877,9 +877,7 @@ mod tests {
         );
         // The origin names the file *and* the key inside it, which is what makes `explain`
         // worth reading.
-        let origin = resolved
-            .origin(REGISTRY.lookup("jobs").unwrap().id)
-            .unwrap();
+        let origin = resolved.origin_key("jobs").unwrap();
         assert!(origin.describe().ends_with("hk.toml#jobs"), "{origin:?}");
     }
 
@@ -1271,9 +1269,8 @@ mod tests {
         );
 
         // Every file that contributed is recorded, farthest first — the order they were read.
-        let jobs = REGISTRY.lookup("jobs").unwrap().id;
         let contributors: Vec<String> = resolved
-            .contributors(jobs)
+            .contributors_key("jobs")
             .iter()
             .map(|o| o.describe().to_string())
             .collect();
@@ -1545,9 +1542,7 @@ mod tests {
             resolved.get_key("exclude"),
             Some(&Value::List(vec![Value::from("a,b"), Value::from("c")]))
         );
-        let origin = resolved
-            .origin(REGISTRY.lookup("jobs").unwrap().id)
-            .unwrap();
+        let origin = resolved.origin_key("jobs").unwrap();
         assert!(origin.describe().ends_with("hk.yaml#jobs"), "{origin:?}");
 
         // `.yml` is the same format, and a settings table within the file works the same way.
diff --git a/config/src/lib.rs b/config/src/lib.rs
index add4271c4..bd00b12af 100644
--- a/config/src/lib.rs
+++ b/config/src/lib.rs
@@ -49,7 +49,7 @@
 //! assert_eq!(resolved.get_key("jobs"), Some(&Value::Int(8)));
 //! // And where it came from is the variable the user set, not "the environment".
 //! assert_eq!(
-//!     resolved.origin(REGISTRY.lookup("jobs").unwrap().id).unwrap().describe(),
+//!     resolved.origin_key("jobs").unwrap().describe(),
 //!     "MYCLI_JOBS",
 //! );
 //! # Ok::<(), usage_config::LayerError>(())
diff --git a/config/src/resolve.rs b/config/src/resolve.rs
index d067d0614..a298895a3 100644
--- a/config/src/resolve.rs
+++ b/config/src/resolve.rs
@@ -47,6 +47,18 @@ impl Resolved {
         self.provenance.get(id.index()).and_then(Option::as_ref)
     }
 
+    /// Where the winning value for a dotted key came from, following renames.
+    ///
+    /// The counterpart to [`Resolved::get_key`], and the reason this exists: a settings
+    /// listing walks keys, and without it the only way to ask about provenance was
+    /// `origin(registry.lookup(key)?.id)`. pitchfork's first port of `settings list` reached
+    /// that wall and fell back to comparing the rendered value against the rendered default,
+    /// which reports an explicit override that happens to equal the default as unset — the
+    /// exact confusion an origin-tracked merge exists to end.
+    pub fn origin_key(&self, key: &str) -> Option<&Origin> {
+        self.origin(self.registry.lookup(key)?.id)
+    }
+
     /// Every place that contributed to this setting, in merge order.
     ///
     /// One entry for a `replace` setting, several for a `union` or `deep` one — which is
@@ -58,6 +70,18 @@ impl Resolved {
             .unwrap_or_default()
     }
 
+    /// Every place that contributed to a dotted key, in merge order, following renames.
+    ///
+    /// Empty for a key the registry does not have, which is the same answer as a key nothing
+    /// contributed to. A caller that needs to tell the two apart is asking whether the
+    /// setting exists, and [`Registry::lookup`] is that question.
+    pub fn contributors_key(&self, key: &str) -> &[Origin] {
+        match self.registry.lookup(key) {
+            Some(found) => self.contributors(found.id),
+            None => &[],
+        }
+    }
+
     pub fn registry(&self) -> Registry {
         self.registry
     }
@@ -1213,4 +1237,101 @@ mod tests {
             "could not read hk.toml: expected a value at line 3"
         );
     }
+
+    #[test]
+    fn provenance_answers_to_a_key_the_way_a_value_does() {
+        // The accessor a settings listing needs. Without it the shortest way to ask "did anyone
+        // set this, or is it just the default" was to render the value and the default and
+        // compare the strings — which calls an explicit override that happens to equal the
+        // default unset, and is exactly what an origin-tracked merge exists to avoid.
+        let file = layer(
+            SourceKind::FILE,
+            vec![(
+                "jobs",
+                // The declared default, set again on purpose.
+                Value::Int(4),
+                Origin::file("hk.toml", FileScope::Project),
+            )],
+        );
+        let resolved = resolve(REGISTRY, Layers::new().then(&file)).expect("resolves");
+
+        assert_eq!(resolved.get_key("jobs"), Some(&Value::Int(4)));
+        let origin = resolved.origin_key("jobs").expect("set by the file");
+        assert_eq!(origin.kind, SourceKind::FILE);
+        assert!(origin.describe().contains("hk.toml"));
+        // The value alone cannot tell these apart; the origin can.
+        assert_ne!(origin.kind, SourceKind::DEFAULTS);
+
+        // And a setting nothing touched still has an origin, which is the default itself.
+        let untouched = resolve(REGISTRY, Layers::new()).expect("resolves");
+        assert_eq!(
+            untouched.origin_key("jobs").map(|o| o.kind),
+            Some(SourceKind::DEFAULTS)
+        );
+        // Except where there is no default either: unset is unset, and says nothing.
+        assert!(untouched.origin_key("undeclared_default").is_none());
+    }
+
+    #[test]
+    fn provenance_by_key_follows_a_rename_like_a_value_does() {
+        // `get_key` folds a rename, so provenance that did not would answer about a different
+        // setting than the value did — the split the one-merge design is written to prevent.
+        let env = layer(
+            SourceKind::ENV,
+            vec![(
+                "jobs",
+                Value::Int(8),
+                Origin::new(SourceKind::ENV, "HK_JOBS"),
+            )],
+        );
+        let resolved = resolve(REGISTRY, Layers::new().then(&env)).expect("resolves");
+
+        assert_eq!(resolved.get_key("renamed_jobs"), Some(&Value::Int(8)));
+        assert_eq!(
+            resolved.origin_key("renamed_jobs").map(|o| o.describe()),
+            Some("HK_JOBS")
+        );
+        assert_eq!(
+            resolved.contributors_key("renamed_jobs"),
+            resolved.contributors_key("jobs")
+        );
+
+        // A key the registry does not have is not a setting with no contributors, but a caller
+        // rendering a list has already looked it up; both answer emptily and neither panics.
+        assert!(resolved.origin_key("nonesuch").is_none());
+        assert!(resolved.contributors_key("nonesuch").is_empty());
+    }
+
+    #[test]
+    fn contributors_by_key_lists_a_merged_setting_in_merge_order() {
+        let user = layer(
+            SourceKind::FILE,
+            vec![(
+                "excluded",
+                Value::List(vec![Value::from("vendor")]),
+                Origin::file("~/.config/hk.toml", FileScope::Global),
+            )],
+        );
+        let project = layer(
+            SourceKind::FILE,
+            vec![(
+                "excluded",
+                Value::List(vec![Value::from("dist")]),
+                Origin::file("hk.toml", FileScope::Project),
+            )],
+        );
+        let resolved =
+            resolve(REGISTRY, Layers::new().then(&project).then(&user)).expect("resolves");
+
+        let described: Vec<&str> = resolved
+            .contributors_key("excluded")
+            .iter()
+            .map(|o| o.describe())
+            .collect();
+        // Lowest precedence first: the declared default, then the user's file, then the project's.
+        assert_eq!(described.len(), 3, "{described:?}");
+        assert_eq!(described[0], "the default", "{described:?}");
+        assert!(described[1].contains(".config"), "{described:?}");
+        assert!(described[2].contains("hk.toml"), "{described:?}");
+    }
 }
diff --git a/conformance/tests/derive_settings.rs b/conformance/tests/derive_settings.rs
index 96f9f6c40..b668570ac 100644
--- a/conformance/tests/derive_settings.rs
+++ b/conformance/tests/derive_settings.rs
@@ -99,9 +99,7 @@ fn a_flag_that_was_given_sets_its_setting() {
     );
     // Named as the flag, which is what makes an explanation actionable.
     assert_eq!(
-        resolved
-            .origin(REGISTRY.lookup("jobs").expect("declared").id)
-            .map(|o| o.describe()),
+        resolved.origin_key("jobs").map(|o| o.describe()),
         Some("--jobs")
     );
 }
@@ -117,9 +115,7 @@ fn a_flag_that_was_not_given_leaves_the_lower_layers_alone() {
     assert_eq!(resolved.get_key("jobs"), Some(&Value::Int(4)));
     assert_eq!(resolved.get_key("colour"), Some(&Value::Bool(true)));
     assert_eq!(
-        resolved
-            .origin(REGISTRY.lookup("colour").expect("declared").id)
-            .map(|o| o.describe()),
+        resolved.origin_key("colour").map(|o| o.describe()),
         Some("the default")
     );
 }
@@ -135,9 +131,7 @@ fn a_negated_flag_is_a_value_and_not_an_absence() {
     let resolved = resolve(REGISTRY, Layers::new().then(&layer)).expect("resolves");
     assert_eq!(resolved.get_key("colour"), Some(&Value::Bool(false)));
     assert_eq!(
-        resolved
-            .origin(REGISTRY.lookup("colour").expect("declared").id)
-            .map(|o| o.describe()),
+        resolved.origin_key("colour").map(|o| o.describe()),
         Some("--colour"),
         "reported as the flag the setting declares first"
     );
diff --git a/conformance/tests/derive_settings_env.rs b/conformance/tests/derive_settings_env.rs
index 19d694aaa..d0e6d1e50 100644
--- a/conformance/tests/derive_settings_env.rs
+++ b/conformance/tests/derive_settings_env.rs
@@ -46,9 +46,7 @@ fn a_value_the_environment_filled_in_is_not_a_command_line_value() {
     let resolved = resolve(REGISTRY, Layers::new().then(&layer).then(&env)).expect("resolves");
     assert_eq!(resolved.get_key("jobs"), Some(&Value::Int(6)));
     assert_eq!(
-        resolved
-            .origin(REGISTRY.lookup("jobs").expect("declared").id)
-            .map(|o| o.describe()),
+        resolved.origin_key("jobs").map(|o| o.describe()),
         Some("EX_SETTINGS_JOBS"),
         "and it is named as one"
     );
@@ -60,9 +58,7 @@ fn a_value_the_environment_filled_in_is_not_a_command_line_value() {
     let resolved = resolve(REGISTRY, Layers::new().then(&layer).then(&env)).expect("resolves");
     assert_eq!(resolved.get_key("jobs"), Some(&Value::Int(8)));
     assert_eq!(
-        resolved
-            .origin(REGISTRY.lookup("jobs").expect("declared").id)
-            .map(|o| o.describe()),
+        resolved.origin_key("jobs").map(|o| o.describe()),
         Some("--jobs")
     );
 }
diff --git a/conformance/tests/derive_settings_flatten.rs b/conformance/tests/derive_settings_flatten.rs
index ce5f06602..4023b470c 100644
--- a/conformance/tests/derive_settings_flatten.rs
+++ b/conformance/tests/derive_settings_flatten.rs
@@ -113,9 +113,7 @@ fn a_group_contributes_what_it_was_given() {
     assert_eq!(resolved.get_key("colour"), Some(&Value::Bool(false)));
     // Named by the flag the group declares, not by the root.
     assert_eq!(
-        resolved
-            .origin(REGISTRY.lookup("jobs").expect("declared").id)
-            .map(|o| o.describe()),
+        resolved.origin_key("jobs").map(|o| o.describe()),
         Some("--jobs")
     );
 }