docs: document basectl xtrace wrapper flag (#2063)

docs/command-reference.md

@@ -21,8 +21,9 @@ command-specific exceptions.
 `basectl` exposes `-v` as the public command-level debug switch. Direct
 `base_cli` package standard options such as `--debug`, `--quiet`, `--log-file`,
 `--config` and `--environment` are private to Python package execution and are
-rejected by `basectl`. Use `basectl --keep-temp <command>` when temporary run
-files must be preserved for diagnosis; they are removed by default.
+rejected by `basectl`. Use `basectl -x <command>` to enable Bash xtrace before
+the command runs. Use `basectl --keep-temp <command>` when temporary run files
+must be preserved for diagnosis; they are removed by default.
 
 ## Stability Tiers
 

docs/execution-model.md

@@ -15,6 +15,11 @@ public executable directory: `$BASE_HOME/bin`.
 `basectl` is responsible for deciding what kind of invocation the user asked
 for. It then delegates runtime setup to `base_init.sh`.
 
+Wrapper diagnostics are consumed before command dispatch. Use `-v` for
+command-level DEBUG logging, `-x` for Bash xtrace, `--debug-wrapper` for early
+wrapper DEBUG logging, `--utc-wrapper` for wrapper/runtime timestamps in UTC,
+and `--keep-temp` to preserve temporary run files.
+
 At a high level, `basectl` can:
 
 - start a Base-enabled interactive Bash shell

docs/stability-tiers.md

@@ -95,6 +95,6 @@ When a user-facing workflow starts depending on an internal surface, promote
 that surface deliberately by documenting its tier and adding a focused test or
 contract row.
 
-The wrapper-level `basectl --keep-temp <command>` flag is public and stable; it
-is intentionally separate from the rejected direct `base_cli` package options
-listed above.
+The wrapper-level `basectl -x <command>` and `basectl --keep-temp <command>`
+flags are public and stable; they are intentionally separate from the rejected
+direct `base_cli` package options listed above.