[codeforester]

Summary

base-workspace is discovered as a Base-managed project but cannot be exported without .ai-context/. Add five curated Markdown pages covering workspace manifest ownership, repository composition, and bootstrap/update/validation workflow, with a deliberate INDEX order and links to canonical sources. Contribution guidance defines when the pack must be updated.

Issue

Fixes #17

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/validate.sh: 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.

[codeforester]

Instruction conflates --manifest with workspace root. This paragraph says to "specify the intended workspace root when it differs from Base's configured workspace," but every example below only passes --manifest workspace.yaml — never --workspace <path>. These are two distinct flags (confirmed via basectl workspace status --help): --manifest selects which YAML inventory file to read; --workspace <path> selects which directory on disk gets scanned for the repo checkouts (defaults to workspace.root/BASE_HOME's parent). I verified empirically: running basectl workspace status --manifest workspace.yaml from a worktree in a completely different directory still reported "workspace": "/Users/rameshhp/work" (Base's configured default), not the directory it was run from. So a contributor whose checkout root actually differs from Base's configured workspace, following this guidance literally, will get status/check/doctor/clone output scoped to the wrong directory while believing --manifest fixed that — they'd need --workspace <path> as well (or instead).\n\nSuggest either dropping the "workspace root" sentence, or adding --workspace <path> to the examples and explaining the two flags separately.

[codeforester]

New .ai-context maintenance obligation has no CI enforcement. CONTRIBUTING.md now asks contributors to "maintain these curated summaries alongside meaningful changes" and "state context impact in the PR," but tests/validate.sh's required_files array (which .github/workflows/tests.yml runs on every push/PR) was not extended to include anything under .ai-context/. I confirmed this directly: deleting the entire .ai-context/ directory from the PR worktree and re-running ./tests/validate.sh still printed Repository baseline is present. and exited 0.\n\nSo a future PR can delete, rename, or let the pack go stale with CI staying green — nothing catches it. Consider adding the 5 .ai-context/*.md files to required_files (or a dedicated check) so the pack gets the same CI protection as README.md, CHANGELOG.md, etc.

[codeforester]

PR template checklist wasn't updated to match this new rule. This line asks contributors to "state context impact in the PR," the same way the repo already requires for docs and CHANGELOG — but .github/pull_request_template.md's Checklist has - [ ] Documentation is updated when behavior or user-facing commands change. and - [ ] CHANGELOG is updated for notable user-visible or release-worthy changes. with no analogous .ai-context item. Since the template is what a contributor actually fills in when opening a PR, this new convention has no prompt anywhere in the authoring flow (and this PR itself doesn't visibly state a context-impact line in its own description, which is a live example of the gap). Suggest adding a checklist item, e.g. "AI context pack (.ai-context/) is updated or its non-update is explained."

[codeforester]

INDEX.md doesn't self-reference, so it exports LAST despite being the stated entry point. .ai-context/README.md (line 5-6) says "Start with INDEX.md," and the exporter (base_export_context/engine.py: ordered_context_files/index_references) builds Markdown-export order by parsing the markdown links/code-spans found inside INDEX.md, in order of appearance, then appends any unreferenced files alphabetically. Since this INDEX.md never links to itself, it isn't in that reference list, so it gets appended at the end.\n\nI confirmed this by actually running basectl export-context --list-files against this PR's worktree:\n\n.ai-context/PROJECT.md\n.ai-context/ARCHITECTURE.md\n.ai-context/WORKFLOWS.md\n.ai-context/README.md\n.ai-context/INDEX.md\n\nINDEX.md — the page meant to be read first — is last in the actual exported/printed bundle a reader or AI tool consumes via basectl export-context --print. (Note: this same pattern already exists in base-bash-libs/.ai-context/INDEX.md, so it's not unique to this PR, but it's being newly copied here too.)

[codeforester]

Unverified claim: no "workspace export job" exists anywhere in this org. I searched this repo's CI (.github/workflows/issue-branch-policy.yml, project-intake.yml, and tests.yml, which only runs ./tests/validate.sh) and the sibling base, base-cli, and base-bash-libs repos for any automated job that reads/exports .ai-context/ and found none — the only way this pack gets exported is a human (or agent) manually running basectl export-context. (The identical sentence already appears in base-bash-libs/.ai-context/README.md, so this looks like copied boilerplate rather than something verified for this repo.) If there's no such job, this line overstates what happens automatically and could lead a reader to assume the pack is kept fresh/consumed without anyone acting on it. Worth confirming the intended meaning and either pointing to the actual mechanism or dropping the sentence.