feat: add opt-in AI context scaffolding to repo init #2627

Goal

Make curated AI context an explicit, repeatable opt-in part of repository onboarding through basectl repo init --ai-context, with safe structural validation and clear authoring guidance.

Background

basectl export-context packages existing .ai-context/ files; it does not create their content. repo init --agent-ready seeds AGENTS.md and skills.md, but not an exportable context pack. In the current 13-project workspace, only Base, BankBuddy, and base-demo have packs; ten projects cannot be exported until maintainers author them. The documentation rollout can proceed independently, but new repositories would recreate this gap.

Scope

• Add explicit --ai-context to repo init, independent of --agent-ready; preserve existing defaults and the agent-ready contract.
• Seed a real .ai-context/ directory with README.md, INDEX.md, PROJECT.md, ARCHITECTURE.md, and WORKFLOWS.md. INDEX defines reading/export order. Small projects can curate/merge sections after initialization.
• Use only deterministic facts already available to initialization (project name, explicit description/languages, canonical source pointers). Clearly mark architecture, workflows, and decisions requiring human review as draft authoring prompts; never present guessed behavior or placeholder text as verified facts.
• Create missing files only, preserve all existing files byte-for-byte, and refuse symlink/special-file targets. Re-running must be idempotent, including partially populated packs. Follow existing baseline no-overwrite behavior without broad repository mutations.
• Keep --dry-run read-only and enumerate planned context files. Integrate the option into existing --pr issue-backed behavior.
• Add opt-in repo check --ai-context structural inspection with machine-readable results and a repair command. Distinguish a structurally exportable scaffold from curated content readiness; existing --agent-ready checks must not start requiring context.
• Document the source-of-truth boundary, keeping packs current during meaningful PRs, INDEX ordering, Markdown/Zip export, and the fact that links to files outside .ai-context are not inlined.
• Update applicable command help, command reference, baseline documentation, Base's own AI-facing command summary, and compatibility/schema documentation when affected.

Acceptance Criteria

• A newly initialized Base-managed repo can opt in and successfully export its seeded Markdown pack.
• Default initialization and existing agent-ready behavior are unchanged.
• Existing curated files survive repeated and partial initialization unchanged.
• Dry-run creates no files, branches, commits, or remote resources.
• Unsafe target types fail clearly without escaping the repository or overwriting existing content.
• Structural checks identify missing files and unresolved draft content separately; structural success does not claim factual accuracy.
• The documented init -> curate -> check -> export workflow works from paths containing spaces.

Validation

Focused baseline renderer/planner/check tests, CLI/help and inspection-schema tests, no-overwrite/idempotence/dry-run/symlink fixtures, and a real temporary-repo init/check/export smoke test. Run the relevant Base compatibility and repository validation gates for the final implementation.

Non-Goals

LLM-generated repository summaries, provider uploads, Google Drive integration, export destination changes, forcing AI context on all repositories, copying secrets/private runtime data, or updating unrelated baseline files. This issue does not block the ten repository-specific curated documentation PRs.

Project Fields

Status: Ready
Priority: P2
Area: CLI
Initiative: Agentic Coding Platform
Size: M

Agent Assignment

Maintainer: @codeforester. Implementation should use the canonical issue worktree after this interface and acceptance contract are reviewed. The current rollout files this tooling proposal and implements the independently useful repository documentation packs.