[codeforester]

Summary

base-cli is discovered as a Base-managed project but cannot be exported without .ai-context/. Add five curated Markdown pages covering Python CLI framework boundaries, public consumption patterns, runtime controls, and test strategy, with a deliberate INDEX order and links to canonical sources. Contribution guidance defines when the pack must be updated.

Issue

Fixes #459

Validation

• Checked all relative source links in the five context files and reviewed the summaries against repository docs and implementation.
• Real basectl export-context --list-files, Markdown, and Zip exports passed from this issue worktree.
• Two consecutive Markdown exports are byte-identical; Zip entries match all five source files byte-for-byte.
• git diff --cached --check before commit and git diff --check passed.
• bash tests/full_validate.sh --gate baseline: passed.
• bash tests/full_validate.sh --gate contracts: passed.

Docs Impact

Adds .ai-context/README.md, INDEX.md, PROJECT.md, ARCHITECTURE.md, and WORKFLOWS.md; adds maintenance guidance in CONTRIBUTING.md. The pack supplies offline orientation while canonical documentation/code remain authoritative. It does not claim that source links are inlined by the exporter.

Notes

No release version or CHANGELOG update: this is repository orientation, with no runtime behavior change. The optional Base scaffold enhancement is tracked separately in basefoundry/base#2627 and is not required to use this pack. After merge and checkout update, existing workspace export/sync jobs discover the directory automatically. This PR does not publish exports or change cloud synchronization.

Hosted validation status

The Windows benchmark passed on a targeted rerun of the unchanged PR commit: persistence_enabled_ms p95 57.66 ms, median 46.26 ms, below the unchanged 250 ms p95 limit (job).

The previous run measured 427.25 ms p95. Two runs of the unchanged base commit also measured 338.68 ms (failure) and 89.01 ms (success), confirming variable results independent of this documentation diff. No runtime, benchmark code, or threshold was changed. The still-queued workflow was canceled and its failed/unfinished jobs rerun; completed successful jobs were retained. All 104 hosted checks now completed successfully (or were intentionally skipped) on unchanged commit e1f9447; the macOS/Python 3.10 runtime job also passed.

[codeforester]

correctness / factual-accuracy: This line lists attachment among the Internal modules ("Internal _lifecycle, _run, _runtime, attachment, and cleanup modules coordinate execution"), but lib/python/base_cli/attachment.py is actually part of the public facade: __init__.py imports AttachmentAdapter, AttachmentContextFactory, AttachmentContract, and AttachmentServiceFactory from it, all four appear in __all__, and docs/api-reference.md documents them as part of "the complete stable facade" generated from __all__. The genuinely private module is _attach.py (underscore-prefixed), not attachment.py.\n\nFailure scenario: an AI assistant or contributor reading this curated context concludes the Attachment extension point is internal/unsupported and either avoids the documented AttachmentAdapter/AttachmentContract API, or reaches into the private _attach.py internals instead — directly contradicting this same file's guidance two lines later to "Use the public facade... rather than importing private implementation modules" (PROJECT.md) and the public-modules list on line 11-12, which omits attachment even though it is demonstrably public.

[codeforester]

altitude / validation gap: The suggested validation (basectl export-context --list-files, --print, plus git diff --check) does not actually check that the Markdown links inside .ai-context/*.md resolve — the exporter only lists/bundles files, it never validates cross-references. The repo's real link checker, scripts/validate_docs.py (run by tests/full_validate.sh --gate contracts, which the PR description says it ran), hard-codes its markdown_files scan to README.md, CONTRIBUTING.md, SECURITY.md, docs/**/*.md, examples/**/*.md, and compatibility/**/*.md — .ai-context/ is absent from that list, and nothing in scripts/ or .github/workflows/ references .ai-context at all.\n\nFailure scenario: a later PR renames/moves lib/python/base_cli/profile.py or docs/security-threat-model.md (both linked from .ai-context/ARCHITECTURE.md) without updating the context pack. --gate contracts still passes (it never looked at .ai-context), CI is green, and the AI context pack silently rots — exactly the drift this PR's own "AI Context Maintenance" contract is meant to prevent. The deeper fix is to add .ai-context/**/*.md to validate_docs.py's markdown_files list (or give export-context its own link-check mode) rather than relying on a human running the exporter and eyeballing links, as the PR's "Validation" section describes doing manually this time.

[codeforester]

plausible factual imprecision: "Public modules cover configuration, output rendering, logging, redaction, runtime/history, inspection, and testing" lists redaction as one of the public modules, but base_cli.redaction (the module defining REDACTED, redact_argv, etc.) is never imported into __init__.py and has no symbols in __all__ — docs/api-reference.md states it documents only "the complete stable facade" generated from __all__, which excludes this module. Only redact_json_value (from json_contracts.py) is actually in the public facade.\n\nThis may be intentional shorthand (the module is non-underscore-prefixed, tested, and tracked in docs/coverage-policy.md), but as written it implies base_cli.redaction carries the same compatibility promise as the generated api-reference facade, which the facade's own generation rule contradicts. Worth confirming against docs/api-stability.md's compatibility scope before treating this sentence as accurate.