diff --git a/docs/base-cli.md b/docs/base-cli.md index 7b0a3726..9e3a9557 100644 --- a/docs/base-cli.md +++ b/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 diff --git a/docs/cache-ownership-and-layout.md b/docs/cache-ownership-and-layout.md index 7a599a4b..3aec730a 100644 --- a/docs/cache-ownership-and-layout.md +++ b/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 diff --git a/docs/observability.md b/docs/observability.md index e6ff7a22..3d0ded84 100644 --- a/docs/observability.md +++ b/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 diff --git a/docs/runtime-environment.md b/docs/runtime-environment.md index 506f5b00..8eb1c635 100644 --- a/docs/runtime-environment.md +++ b/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 diff --git a/docs/shell-startup.md b/docs/shell-startup.md index 596c6afb..d6a26194 100644 --- a/docs/shell-startup.md +++ b/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.