Goal
Reconcile the config-precedence and environment-variable reference docs,
which currently disagree with each other on layer count and which variables
exist.
Background
A documentation review of the reference/contract layer found:
- Config precedence order is documented twice with different layer counts
and different treatment of --config's position relative to env vars/CLI
options: docs/local-config.md:89-100 (5 layers) vs.
docs/base-cli.md:301-310 (6 layers), with no cross-reference between the
two "contract" pages.
docs/local-config.md:102-106's "Recognized environment variables" list
(3 vars) omits BASE_CLI_TEMP_RETENTION_DAYS, which docs/base-cli.md's
Standard Environment Variables table (:328-335) and
docs/runtime-environment.md:206 both include as part of the same config
layer.
docs/python-manifest.md:66 references BASE_PROJECT_PYTHON_BIN as an
interpreter-selection input, but it is completely absent from
docs/runtime-environment.md, which bills itself (line 6) as "the
canonical reference for Base-managed shell environment variables" and
documents closely related knobs like BASE_PROJECT_VENV_DIR.
docs/workspace-manifest.md:490-493 and docs/python-manifest.md:304-309
describe the same python_runtime JSON field for workspace status --format json almost verbatim, with no cross-link between the two.
Scope
docs/local-config.md
docs/base-cli.md
docs/runtime-environment.md
docs/python-manifest.md
docs/workspace-manifest.md
Acceptance Criteria
Validation
git diff --check; if feasible, verify actual config-resolution order
against the CLI's implementation to confirm which layer count (5 or 6) is
correct before documenting it.
Non-Goals
- Changing actual config-resolution behavior — this is a documentation
accuracy/consolidation issue.
Project Metadata
- Priority: P1
- Size: M
- Area: Docs
- Initiative: Contract Hardening
- Agent Assignment: Human first (need to verify actual precedence behavior
against the codebase before picking which doc is correct)
Goal
Reconcile the config-precedence and environment-variable reference docs,
which currently disagree with each other on layer count and which variables
exist.
Background
A documentation review of the reference/contract layer found:
and different treatment of
--config's position relative to env vars/CLIoptions:
docs/local-config.md:89-100(5 layers) vs.docs/base-cli.md:301-310(6 layers), with no cross-reference between thetwo "contract" pages.
docs/local-config.md:102-106's "Recognized environment variables" list(3 vars) omits
BASE_CLI_TEMP_RETENTION_DAYS, whichdocs/base-cli.md'sStandard Environment Variables table (
:328-335) anddocs/runtime-environment.md:206both include as part of the same configlayer.
docs/python-manifest.md:66referencesBASE_PROJECT_PYTHON_BINas aninterpreter-selection input, but it is completely absent from
docs/runtime-environment.md, which bills itself (line 6) as "thecanonical reference for Base-managed shell environment variables" and
documents closely related knobs like
BASE_PROJECT_VENV_DIR.docs/workspace-manifest.md:490-493anddocs/python-manifest.md:304-309describe the same
python_runtimeJSON field forworkspace status --format jsonalmost verbatim, with no cross-link between the two.Scope
docs/local-config.mddocs/base-cli.mddocs/runtime-environment.mddocs/python-manifest.mddocs/workspace-manifest.mdAcceptance Criteria
cross-references it instead of restating a (possibly different) count.
docs/local-config.md's recognized environment variables list matchesdocs/base-cli.md/docs/runtime-environment.mdexactly, or explainswhy it's a deliberate subset.
BASE_PROJECT_PYTHON_BINis documented indocs/runtime-environment.md(or the doc explains why it's out ofscope there).
python_runtimefield description is consolidated intoone canonical location with a cross-reference from the other.
Validation
git diff --check; if feasible, verify actual config-resolution orderagainst the CLI's implementation to confirm which layer count (5 or 6) is
correct before documenting it.
Non-Goals
accuracy/consolidation issue.
Project Metadata
against the codebase before picking which doc is correct)