docs: audit remaining design and command contract gaps #2650

Goal

Publish an evidence-backed crosswalk for the documentation gaps that remained outside the known-drift and upgrade PRs, then route confirmed corrections through focused issue/PR trains.

Background

The Claude audit identified candidates across architecture, manifest keys, environment variables, command documentation, AI context, release status, and uninstall guidance. Candidates need current-source verification and deduplication before being treated as drift. PRs #2629 and #2630 are under review for the known corrections; #2631/#2632 track the separate documentation-maintenance strategy. Existing related work includes #1613 for manifest JSON Schema/parser parity, #2427 for a prior command-reference pass, #2595 for the readiness scorecard, and #2649 for stale Base-local lib/python CI paths.

Scope

• Create a dated, point-in-time crosswalk that records the audited Base commit, candidate contract, implementation/source evidence, tests or other enforcement, affected design/user/operational/FAQ/release/AI-context docs, related issue or PR, and a disposition.
• Verify architecture candidates against the trust, gh, and repo implementations and their detailed references; include the execution-model and Base Bash library compatibility claims.
• Trace release manifest keys from parser and validator through tests and release docs; link or defer schema-parity work to Publish a tested JSON Schema for base_manifest.yaml #1613 rather than duplicating it.
• Inventory production environment-variable reads and declarations, compare them with maintained user and operational docs, and classify public, internal, test-only, sensitive, and CI-only values before recommending documentation.
• Compare the shipped command/help surface with the command reference and technical overview, including the reported grpcurl and uninstall front-door gaps; account for Document shipped public flags missing from the basectl command reference #2427's prior closure and any in-flight work in docs: reconcile audited design and implementation drift #2629/docs: publish the installation-route upgrade contract #2630.
• Check the AI status/version and base-bash-libs floor claims against current release and dependency evidence.
• For each confirmed material gap, link an existing issue or create a focused follow-up issue with its own acceptance criteria. Do not fold those corrections into this audit PR.

Acceptance Criteria

• The crosswalk distinguishes verified gaps, already-correct or adequately-covered claims, in-flight fixes, intentional boundaries, and unresolved questions.
• Every finding has concrete source and documentation evidence plus a priority and proposed next action.
• The audit records the exact source commit and method/coverage limits; it does not present the dated snapshot as a continuously current registry.
• Existing issues are linked rather than duplicated; each new correction issue is narrow enough for its own PR.
• No manual Last reviewed stamps or runtime changes are introduced.

Validation

• Verify source links and cited implementation/test locations against the recorded commit.
• Compare public command entries with current shipped help and docs contracts.
• Run the repository documentation-link check and git diff --check.

Non-Goals

• Implementing the documentation-maintenance policy from docs: propose documentation maintenance and drift prevention strategy #2631/docs: propose documentation maintenance and drift prevention #2632.
• Changing runtime behavior, manifest semantics, releases, or CI enforcement.
• Rewriting all documentation or treating historical docs/superpowers/ plans as current contracts.
• Adding manual review-date stamps.

Project Fields

• Status: Backlog
• Priority: P2
• Size: M
• Area: Docs
• Initiative: Contract Hardening

Agent Assignment

Assignee: codeforester. Keep the audit report evidence-based and separate from any correction issue/PR trains.