docs: add curated AI context and maintenance guidance #59

Goal

Add a curated, exportable .ai-context/ pack for base-cli-demo, so an assistant can understand the repository from a portable Markdown bundle.

Background

This Base-managed project is discovered by basectl projects list but has no .ai-context/ directory. basectl export-context therefore cannot produce a pack and scheduled context synchronization skips it. Existing repository sources can supply the necessary orientation. The shared optional scaffold enhancement is tracked separately in basefoundry/base#2627; this documentation work does not depend on it.

Scope

• Inspect and summarize the reference consumer, framework integration, reconciliation behavior, and validation workflow from current repository evidence.
• Add README, INDEX, PROJECT, ARCHITECTURE, and WORKFLOWS Markdown under .ai-context/; add a commands/decisions page only if it improves clarity.
• Include self-contained explanations and canonical source links. Export does not inline linked files outside the context directory.
• Add repository contribution/agent guidance for keeping the pack current on meaningful behavior, architecture, or workflow changes.
• Preserve project-specific policies and distinguish implemented behavior from roadmap ideas.

Acceptance Criteria

• The pack accurately describes this repository and contains no placeholder-only sections.
• INDEX provides a deliberate reading/export order; source paths and commands are checked.
• Export works as Markdown and Zip, and repeated unchanged Markdown exports are identical.
• Contribution guidance explains ownership, update triggers, and source-of-truth precedence.
• Context excludes credentials, personal runtime data, private machine paths, and transient generated artifacts.
• Existing code, runtime behavior, release versions, and user changes remain untouched.

Validation

Run repository-required relevant checks, git diff --check, local source-link validation, and actual basectl export-context list/Markdown/Zip smoke checks from the issue worktree. Compare two Markdown exports byte-for-byte. Record exact local results and hosted check state in the PR.

Non-Goals

Implementing the shared scaffolding enhancement, generating context using an external AI service, publishing to cloud storage, changing exports or runtime behavior, rewriting canonical documentation, or changing release versions.

Project Fields

Status: In Progress
Priority: P2
Size: S
Area: Docs
Initiative: Adoption Polish

Agent Assignment

Assigned to @codeforester; implementation by the current authorized documentation rollout in a dedicated canonical issue worktree. Open a reviewable issue-linked PR and leave merging for explicit authorization.