feat(cli): add usage explain

AGENTS.md

@@ -116,6 +116,10 @@ The `parse()` function parses command-line arguments against a spec, returning:
 - Matched command path
 - Parsed args and flags with values
 - Env var and default fallbacks applied
+- Provenance: `tokens` says what each word of argv became, and
+  `flag_origins`/`arg_origins` say where a value came from when no token supplied
+  it. `Parser::explain` returns all of it with the errors kept rather than bailing
+  on the first, which is what `usage explain` renders.
 
 ### Documentation Generation (`lib/src/docs/`)
 

cli/assets/fig.ts

@@ -194,6 +194,63 @@ const completionSpec: Fig.Spec = {
         },
       ],
     },
+    {
+      name: "explain",
+      description: "Explain what a command line binds to",
+      options: [
+        {
+          name: ["-f", "--file"],
+          description:
+            'A usage spec file or script with a usage shebang, use "-" to read from stdin',
+          isRepeatable: false,
+          args: {
+            name: "file",
+            template: "filepaths",
+          },
+        },
+        {
+          name: ["-s", "--spec"],
+          description: "Raw string spec input",
+          isRepeatable: false,
+          args: {
+            name: "spec",
+          },
+        },
+        {
+          name: "--format",
+          description: "Output format",
+          isRepeatable: false,
+          args: {
+            name: "format",
+            suggestions: ["text", "json"],
+          },
+        },
+        {
+          name: "--view",
+          description: "A spec-declared executable view to explain",
+          isRepeatable: false,
+          args: {
+            name: "view",
+          },
+        },
+        {
+          name: ["-e", "--env"],
+          description:
+            "Environment to explain against, as KEY=VALUE, repeatable",
+          isRepeatable: true,
+          args: {
+            name: "env",
+          },
+        },
+      ],
+      args: {
+        name: "argv",
+        description:
+          "The command line to explain, starting with the program name",
+        isOptional: true,
+        isVariadic: true,
+      },
+    },
     {
       name: "fish",
       description: "Execute a shell script using fish",

cli/assets/usage.1

@@ -32,6 +32,9 @@ Execute a script, parsing args and exposing them as environment variables
 \fIAliases: \fRx
 .RE
 .TP
+\fBexplain\fR
+Explain what a command line binds to
+.TP
 \fBfish\fR
 Execute a shell script with the specified shell
 .TP
@@ -176,6 +179,49 @@ path to script to execute
 .TP
 \fB<ARGS>\fR
 arguments to pass to script
+.SH "USAGE EXPLAIN"
+Explain what a command line binds to
+
+Prints a row per argv token saying what it became, then the values that came from
+somewhere other than argv, then anything that went wrong. Exits 0 even when the explained
+command line does not parse: the report succeeded, and that is the case worth a report.
+.PP
+\fBUsage:\fR usage explain [OPTIONS] [<ARGV>] ...
+.PP
+\fBOptions:\fR
+.PP
+.TP
+\fB\-f, \-\-file\fR \fI<FILE>\fR
+A usage spec file or script with a usage shebang, use "\-" to read from stdin
+.TP
+\fB\-s, \-\-spec\fR \fI<SPEC>\fR
+Raw string spec input
+.TP
+\fB\-\-format\fR \fI<FORMAT>\fR
+Output format
+.RS
+\fIDefault: \fRtext
+.RE
+.TP
+\fB\-\-view\fR \fI<VIEW>\fR
+A spec\-declared executable view to explain
+.TP
+\fB\-e, \-\-env\fR \fI<ENV>\fR
+Environment to explain against, as KEY=VALUE, repeatable
+
+Given at all, these are the *whole* environment: an explanation pasted into a bug
+report has to mean the same thing on the machine that reads it. Omitted, the process
+environment is used, which is what an execution would see.
+\fBArguments:\fR
+.PP
+.TP
+\fB<ARGV>\fR
+The command line to explain, starting with the program name
+
+`usage`'s own flags come before it, and flag parsing ends at the program name, so
+both `explain \-f f.kdl mycli \-\-env=prod` and `explain \-f f.kdl \-\- mycli \-\-env=prod`
+work. Separate with `\-\-` when the explained line carries its own: the first `\-\-` is
+still `usage`'s separator, so `explain \-f f.kdl mycli a \-\- b` loses one.
 .SH "USAGE FISH"
 Execute a shell script with the specified shell