From b192a57e6307e4eca978f22002380fa9a3fbb292 Mon Sep 17 00:00:00 2001 From: Ramesh Padmanabhaiah <22363102+codeforester@users.noreply.github.com> Date: Sun, 16 Aug 2026 11:43:55 +0530 Subject: [PATCH] docs: reconcile config and runtime references --- docs/base-cli.md | 17 +++++++++++------ docs/local-config.md | 15 +++++---------- docs/python-manifest.md | 13 +++++++------ docs/runtime-environment.md | 1 + docs/workspace-manifest.md | 6 ++---- 5 files changed, 26 insertions(+), 26 deletions(-) diff --git a/docs/base-cli.md b/docs/base-cli.md index d4a36fb6..7b0a3726 100644 --- a/docs/base-cli.md +++ b/docs/base-cli.md @@ -305,9 +305,14 @@ Configuration is resolved from lowest to highest precedence: 1. Code defaults 2. User config: `~/.base.d/config.yaml` 3. Project config: `/.base/config.yaml` -4. Environment variables -5. Command line options -6. Explicit runtime API overrides +4. Explicit config selected by `--config` +5. Recognized environment variables +6. Command-line standard options + +The `--config` option selects an additional config file that is merged after +project config and before environment variables. It is therefore a config +source layer, while options such as `--environment`, `--debug`, and +`--keep-temp` remain the final command-line layer. V1 intentionally does not read machine-wide or organization-wide config implicitly. In particular, Base must not silently load `/etc/base.d/config.yaml` @@ -316,9 +321,9 @@ checkout and a local developer shell deterministic unless the user or wrapper explicitly opts into an additional config source. V1 implements the shape and context fields, but only needs a minimal config -loader: YAML files are merged when present, environment is read from -`BASE_CLI_ENVIRONMENT`, and CLI options can override `--environment`, `--debug`, -`--keep-temp`, and `--log-file`. +loader: YAML files are merged when present, recognized environment values are +applied after the explicit config source, and CLI options can override +`--environment`, `--debug`, `--keep-temp`, and `--log-file`. `ctx.config` remains the merged raw configuration dictionary. `ctx.user_config` is the typed machine-local user config, so command authors can read diff --git a/docs/local-config.md b/docs/local-config.md index 5aa3f6ac..24526d39 100644 --- a/docs/local-config.md +++ b/docs/local-config.md @@ -88,22 +88,17 @@ and cloud sync. ## Config Precedence -For Python commands built on `base_cli.App`, configuration is loaded in this -order: - -1. user config: `~/.base.d/config.yaml` -2. project config: `/.base/config.yaml` -3. explicit config from `--config` -4. recognized environment variables -5. direct command-line standard options - -Later layers override earlier layers for the same key. +For Python commands built on `base_cli.App`, the canonical precedence contract +is documented in [Base CLI Configuration](base-cli.md#configuration). This page +describes the local config file and its supported settings; it does not define +a second precedence order. Recognized environment variables include: - `BASE_CLI_ENVIRONMENT` - `BASE_CLI_LOG_LEVEL` - `BASE_CLI_KEEP_TEMP` +- `BASE_CLI_TEMP_RETENTION_DAYS` `BASE_CACHE_DIR` separately controls the runtime cache/log/temp root; it is not stored in the user config. diff --git a/docs/python-manifest.md b/docs/python-manifest.md index 324dc8a3..61da3f25 100644 --- a/docs/python-manifest.md +++ b/docs/python-manifest.md @@ -301,12 +301,13 @@ version-mismatched packages in human-readable output and in the optional replace reviewing manifests from unfamiliar repositories before running their declared commands. -`basectl workspace status --format json` also includes a `python_runtime` -object for each ready, inspectable project environment. That summary reports -the environment manager, virtualenv path, interpreter path, and actual Python -minor version for both Base-managed and uv-managed projects. -Shell-only projects instead report `venv: "not_applicable"` and omit -`python_runtime`. +### Workspace status `python_runtime` + +`basectl workspace status --format json` includes a `python_runtime` object for +each ready, inspectable project environment. That summary reports the +environment manager, virtualenv path, interpreter path, and actual Python minor +version for both Base-managed and uv-managed projects. Shell-only projects +instead report `venv: "not_applicable"` and omit `python_runtime`. ## Non-Goals diff --git a/docs/runtime-environment.md b/docs/runtime-environment.md index 1dbb9eba..11507242 100644 --- a/docs/runtime-environment.md +++ b/docs/runtime-environment.md @@ -200,6 +200,7 @@ readonly by Base. | Variable | Scope | Meaning | | --- | --- | --- | | `BASE_CACHE_DIR` | Python CLI/runtime cache | Overrides the cache, log, and temp root. Defaults are platform-specific. | +| `BASE_PROJECT_PYTHON_BIN` | Project Python runtime selection | Overrides the interpreter candidate used when Base creates or checks a project virtual environment. The path must point to a supported Python interpreter. | | `BASE_CLI_ENVIRONMENT` | Python CLI config | Selects the CLI environment value used by `base_cli`. | | `BASE_CLI_LOG_LEVEL` | Python CLI config | Sets the Python CLI user-stream log level. | | `BASE_CLI_KEEP_TEMP` | Python CLI config | Keeps temp directories for inspection when true. | diff --git a/docs/workspace-manifest.md b/docs/workspace-manifest.md index 712f15ae..98db8d72 100644 --- a/docs/workspace-manifest.md +++ b/docs/workspace-manifest.md @@ -487,10 +487,8 @@ Missing required repositories are errors. Missing optional repositories are warnings. Present repositories without `base_manifest.yaml` are allowed and reported with project diagnostics skipped. -With `--format json`, workspace status includes `python_runtime` for each -ready, inspectable Base-managed project environment. The object reports the -environment manager, virtualenv path, interpreter path, and actual Python minor -version so users can quickly compare project runtimes across a workspace. +For the canonical `python_runtime` field definition and JSON shape, see +[Python Manifest](python-manifest.md#workspace-status-python_runtime). `basectl workspace check --manifest ` includes normal project diagnostics for present Base-managed projects and renders check-oriented status, names, and