Problem
basectl --help shows a real, wired-up wrapper-level flag that isn't documented anywhere:
-x Enable Bash xtrace before running the command
Confirmed wired in cli/bash/commands/basectl/basectl.sh:848,851 (getopts ":hvx" ... x) set -x ;;). It is not mentioned in docs/command-reference.md, docs/execution-model.md, or docs/stability-tiers.md's public/internal wrapper-option lists -- those docs document -v and --keep-temp but not -x.
Why this matters
-x is exactly the kind of flag a contributor debugging a Bash-layer issue would want to know about (it's the wrapper-level xtrace switch, distinct from -v's DEBUG logging and --debug-wrapper's pre-runtime diagnostics) -- but it's currently only discoverable via --help itself, not the docs that specifically catalog wrapper options.
Related: #1606 (open) proposes a canonical command-metadata source to prevent flag documentation from silently diverging from --help output; this issue is the concrete current gap.
Proposed change
Add -x to the wrapper-option documentation in docs/command-reference.md, docs/execution-model.md, and docs/stability-tiers.md's public option lists, alongside the existing -v/--keep-temp entries.
Acceptance criteria
Problem
basectl --helpshows a real, wired-up wrapper-level flag that isn't documented anywhere:Confirmed wired in
cli/bash/commands/basectl/basectl.sh:848,851(getopts ":hvx"...x) set -x ;;). It is not mentioned in docs/command-reference.md, docs/execution-model.md, or docs/stability-tiers.md's public/internal wrapper-option lists -- those docs document-vand--keep-tempbut not-x.Why this matters
-xis exactly the kind of flag a contributor debugging a Bash-layer issue would want to know about (it's the wrapper-level xtrace switch, distinct from-v's DEBUG logging and--debug-wrapper's pre-runtime diagnostics) -- but it's currently only discoverable via--helpitself, not the docs that specifically catalog wrapper options.Related: #1606 (open) proposes a canonical command-metadata source to prevent flag documentation from silently diverging from
--helpoutput; this issue is the concrete current gap.Proposed change
Add
-xto the wrapper-option documentation in docs/command-reference.md, docs/execution-model.md, and docs/stability-tiers.md's public option lists, alongside the existing-v/--keep-tempentries.Acceptance criteria
-xis documented in the wrapper-option reference alongside the other public wrapper flags.