docs: align wrapper logging documentation (#2065)

docs/base-cli.md

@@ -235,13 +235,12 @@ Every run gets two streams:
 
 | Stream | Destination | Level | Format |
 |---|---|---|---|
-| user | stderr | INFO by default, DEBUG with `--debug` | Local timestamp (or UTC with `--utc-wrapper`), level, source, message |
-| persistent | `ctx.log_file` when enabled | DEBUG | Local timestamp (or UTC with `--utc-wrapper`), level, source, message |
+| user | stderr | INFO by default, DEBUG with `--debug` | Local timestamp, level, source, message |
+| persistent | `ctx.log_file` when enabled | DEBUG | Local timestamp, level, source, message |
 
-Python user-facing logs default to the host's local timezone so a local run has
-one clock throughout the Bash and Python layers. The local offset is included
-in each timestamp; `--utc-wrapper` sets `LOG_UTC=1` and switches both layers to
-UTC for CI, support, or cross-machine diagnostics:
+Python user-facing logs default to the host's local timezone. The local offset
+is included in each timestamp. `--utc-wrapper` switches Bash wrapper and library
+logs to UTC, but does not change Python CLI log timestamps:
 
 When `basectl --color` is used on a terminal, Python user-facing logs use the
 same level colors as Bash logs. Persistent log files remain plain text, and

docs/cache-ownership-and-layout.md

@@ -173,8 +173,9 @@ Run IDs use UTC-based timestamps so bundle names remain sortable across hosts.
 Python CLI log streams (stderr and the per-run log file) use the host's local
 timezone by default, matching the Bash logger during local runs. The local
 offset is included in Python log lines. Pass `basectl --utc-wrapper ...` to set
-`LOG_UTC=1` and render both Bash and Python log streams in UTC for CI, support,
-or cross-machine diagnostics. `basectl history` keeps its existing UTC default
+`BASE_BASH_LIBS_LOG_UTC=1` and render the Bash wrapper and library log streams in
+UTC for CI, support, or cross-machine diagnostics. Python CLI logs retain their
+normal Python logging timezone. `basectl history` keeps its existing UTC default
 and can render human-readable views in local time with `--local-time`.
 
 History and run artifacts are user-private by default. History and metadata

docs/observability.md

@@ -237,9 +237,10 @@ errors.
 `basectl history` should point to logs, not replace them.
 
 Raw Python CLI logs use the host's local timezone by default, with the local
-numeric offset included in each timestamp. This matches the Bash logger for a
-local run. `basectl --utc-wrapper ...` sets `LOG_UTC=1` and switches both log
-layers to UTC for CI, support, or cross-machine diagnostics.
+numeric offset included in each timestamp. `basectl --utc-wrapper ...` sets
+`BASE_BASH_LIBS_LOG_UTC=1` and switches Bash wrapper and library logs to UTC for
+CI, support, or cross-machine diagnostics; it does not change Python CLI log
+timestamps.
 
 The primary run log uses ISO-8601 UTC timestamps, run IDs use UTC-based
 timestamps, and history JSON retains canonical UTC timestamps. Only

docs/runtime-environment.md

@@ -182,8 +182,8 @@ These variables are involved in normal shell startup rather than the full
 | `BASE_ENABLE_BASH_DEFAULTS` | Base | Generated preference controlling optional Base Bash defaults. | Change with `basectl update-profile --defaults` or `--no-defaults`, not by editing files directly. |
 | `BASE_ENABLE_ZSH_DEFAULTS` | Base | Generated preference controlling optional Base Zsh defaults. | Change with `basectl update-profile --defaults` or `--no-defaults`, not by editing files directly. |
 | `BASE_DEBUG` | User | Enables debug traces in Base-managed shell startup snippets and the runtime Bash rcfile. | Safe to set in `~/.baserc` or as a one-off environment variable. |
-| `LOG_DEBUG` | Base wrapper compatibility | Internal debug signal exported by wrapper/debug paths before the full runtime exists. The Python config layer treats `1` or `true` as a fallback for `BASE_CLI_LOG_LEVEL=debug` when `BASE_CLI_LOG_LEVEL` is unset. | Do not set directly; use `--debug-wrapper` or `BASE_CLI_LOG_LEVEL=debug` for Python CLI logs. |
-| `LOG_UTC` | Base wrapper compatibility | When set to `1`, switches Bash and Python CLI log presentation to UTC. It is set by `basectl --utc-wrapper`; persisted metadata is UTC regardless. | Prefer `basectl --utc-wrapper` for one-off CI or diagnostic runs. |
+| `BASE_BASH_LIBS_LOG_DEBUG` | Base wrapper compatibility | Internal debug signal exported by `--debug-wrapper` before the full runtime exists. It controls Bash wrapper and library logging. | Do not set directly; use `--debug-wrapper` for early Bash-side diagnostics. |
+| `BASE_BASH_LIBS_LOG_UTC` | Base wrapper compatibility | When set to `1`, switches Bash wrapper and library log presentation to UTC. It is set by `basectl --utc-wrapper`; persisted metadata is UTC regardless. | Prefer `basectl --utc-wrapper` for one-off CI or diagnostic runs. |
 | `BASE_CLI_COLOR` | Base wrapper compatibility | Internal signal exported by `basectl --color` so Python-backed child commands use the same terminal log colors as Bash. | Do not set directly; use `basectl --color`. `NO_COLOR` still disables colors. |
 
 The ordinary Bash/Zsh dotfile snippets derive `BASE_HOME` and add

docs/shell-startup.md

@@ -178,9 +178,11 @@ runtime is loaded and the selected command is dispatched. For earlier startup
 debugging, use wrapper options that are consumed by `bin/basectl` before
 `base_init.sh` is sourced:
 
-- `--debug-wrapper` enables `LOG_DEBUG=1` before runtime initialization,
-  including DEBUG diagnostics from reusable Bash libraries.
-- `--utc-wrapper` enables UTC log timestamps before runtime initialization.
+- `--debug-wrapper` enables `BASE_BASH_LIBS_LOG_DEBUG=1` before runtime
+  initialization, including DEBUG diagnostics from reusable Bash libraries.
+- `--utc-wrapper` enables `BASE_BASH_LIBS_LOG_UTC=1` before runtime
+  initialization for Bash wrapper and library log timestamps. It does not
+  change Python CLI log timestamps.
 - `--color` preserves color-aware wrapper argument handling while keeping the flag
   out of command arguments.