docs: reconcile config and runtime references

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: `<project-root>/.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

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: `<project>/.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.

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
 

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. |

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 <path>` includes normal project diagnostics
 for present Base-managed projects and renders check-oriented status, names, and