Skip to content

Docs: config-precedence and environment-variable reference docs disagree with each other #1945

Description

@codeforester

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

  • Config precedence order is stated once, correctly, and the other doc
    cross-references it instead of restating a (possibly different) count.
  • docs/local-config.md's recognized environment variables list matches
    docs/base-cli.md/docs/runtime-environment.md exactly, or explains
    why it's a deliberate subset.
  • BASE_PROJECT_PYTHON_BIN is documented in
    docs/runtime-environment.md (or the doc explains why it's out of
    scope there).
  • The duplicated python_runtime field description is consolidated into
    one canonical location with a cross-reference from the other.

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)

Metadata

Metadata

Assignees

Labels

documentationDocumentation improvements

Type

No type

Projects

Status
Backlog

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions