docs: add curated AI context and maintenance guidance

.ai-context/ARCHITECTURE.md

@@ -0,0 +1,26 @@
+# Architecture
+
+The package lives under `lib/python/base_cli/`. `App` declares or attaches a
+consumer command tree; `run_app` enters the framework lifecycle. A Context makes
+run state, logging, paths, configuration, and cleanup available to handlers.
+Profiles define consumer policy without embedding Base's project conventions in
+the generic runtime.
+
+The public facade in `__init__.py` is the supported import boundary. Internal
+`_lifecycle`, `_run`, `_runtime`, `_attach`, and cleanup modules coordinate
+execution. Public modules and facade exports cover configuration, output
+rendering, logging, attachment adapters/contracts, runtime/history, inspection,
+testing, and selected JSON-redaction helpers. The implementation-heavy
+`redaction` module is not itself part of the stable facade. Optional Typer and
+other integrations do not become unconditional core dependencies.
+
+Human-oriented output remains the default. Opt-in versioned JSON contracts
+support automation; consumer payload formats remain distinct from a framework
+lifecycle envelope. Logging goes to stderr and runtime log files, keeping command
+stdout usable as data. Cleanup, error status, and sensitive-value redaction are
+cross-cutting contracts, not application business logic.
+
+Sources: [package facade](../lib/python/base_cli/__init__.py),
+[profiles](../lib/python/base_cli/profile.py), [JSON contracts](../docs/json-contracts.md),
+[testing guide](../docs/testing.md), and
+[security model](../docs/security-threat-model.md).

.ai-context/INDEX.md

@@ -0,0 +1,11 @@
+# base-cli AI context index
+
+Read in this order:
+
+1. [Project](PROJECT.md): purpose, audience, scope, and boundaries.
+2. [Architecture](ARCHITECTURE.md): components, contracts, and source map.
+3. [Workflows](WORKFLOWS.md): setup, validation, and contribution practices.
+4. [Maintenance](README.md): sources, update rules, and export behavior.
+
+The pack is curated orientation. Canonical repository sources linked from each
+page take precedence when exact implementation or policy details matter.

.ai-context/PROJECT.md

@@ -0,0 +1,20 @@
+# Base-CLI
+
+`base-cli` is a Python invocation-lifecycle framework for Click and optional
+Typer applications. Consumers import `base_cli`; the distribution name is
+`base-cli`. It standardizes context, configuration boundaries, logging, cleanup,
+runtime paths, structured errors, and automation-facing output.
+
+Click/Typer retain parsing and command definitions. Consumer applications retain
+domain services, configuration policy, and project discovery decisions. Base is
+one consumer; its manifests, project model, and workspace conventions are not
+requirements for generic consumers. The separately released Northstar demo shows
+that boundary in an operational CLI.
+
+Use the public facade and documented compatibility promises rather than importing
+private implementation modules. Optional integrations remain opt-in. Consult
+package metadata, release notes, and the compatibility dashboard for the exact
+supported version/dependency matrix; this pack describes the source architecture.
+
+Sources: [README](../README.md), [public API](../docs/api-reference.md),
+[API stability](../docs/api-stability.md), and [metadata](../pyproject.toml).

.ai-context/README.md

@@ -0,0 +1,27 @@
+# AI context for base-cli
+
+This directory is the repository's curated orientation for AI-assisted work and
+portable export. It summarizes verified repository behavior; it is not generated
+runtime evidence or an authoritative release/status registry. Start with
+[INDEX.md](INDEX.md).
+
+Keep purpose, architecture, commands, and workflows aligned with code and
+canonical documentation. Update the affected pages in the same meaningful PR;
+for typo-only or internal changes with no contract impact, record no context
+impact in the PR. Resolve disagreements by correcting this pack from its sources.
+Do not copy credentials, local databases, private machine paths, personal records,
+or transient logs into it. Link to evidence rather than copying runtime data.
+
+From this checkout, with Base available:
+
+```bash
+basectl export-context --list-files
+basectl export-context --print
+```
+
+Markdown exports combine Markdown files in INDEX order, then append unlisted
+files deterministically. Links outside this directory are source references;
+the exporter does not inline their targets. Keep core explanations self-contained.
+Use real regular files, not symlinks. Store generated bundles outside the project
+and keep generation timestamps out of source pages so unchanged exports remain
+byte-identical. This pack is picked up automatically by workspace export jobs.

.ai-context/WORKFLOWS.md

@@ -0,0 +1,23 @@
+# Workflows
+
+Create a development environment with the repository's `uv` metadata and extras.
+The Base manifest declares the dev, typer, quality, and benchmark extras for its
+test path; `basectl setup base-cli` and `basectl test base-cli` use that contract
+in a Base workspace. Generic consumers need only their declared package extras.
+
+The authoritative development aggregate is `./tests/full_validate.sh`. Its
+`--gate` options allow baseline, runtime, coverage, typing, style, contracts,
+benchmark, and security checks to run independently. Documentation/API changes
+should exercise the documentation and contract validators, not just syntax.
+Use the testing guide for dependencies and the full validation matrix.
+
+Work from an issue-backed dedicated worktree, preserve the primary checkout,
+and link each PR to its issue. Record the actual checks run and distinguish
+focused validation from the complete aggregate. Update CHANGELOG only for
+release-worthy changes; documentation orientation does not change package
+versions. Follow the release process for artifact publication rather than
+publishing from a documentation PR.
+
+Sources: [contribution guide](../CONTRIBUTING.md),
+[validation driver](../tests/full_validate.sh), [testing](../docs/testing.md),
+[Base manifest](../base_manifest.yaml), and [releasing](../docs/releasing.md).

CONTRIBUTING.md

@@ -71,3 +71,19 @@ basectl check base-cli
 basectl doctor base-cli
 basectl test base-cli
 ```
+
+## AI Context Maintenance
+
+Start AI-assisted orientation with [.ai-context/INDEX.md](.ai-context/INDEX.md).
+Maintain these curated summaries alongside meaningful changes to product scope,
+architecture, commands, or contributor workflows. Canonical docs and code remain
+the source of truth; update the pack when they disagree. State context impact in
+the PR, including a reason when no update is needed. Typo-only and internal changes
+without behavioral or architectural impact usually need no context update.
+
+Validate changes with `basectl export-context --list-files`,
+`basectl export-context --print`, and `python scripts/validate_docs.py` from the
+checkout, plus `git diff --check`. The documentation validator includes
+`.ai-context/*.md` so links from the curated pack fail in CI when they drift.
+Keep the pack self-contained enough for offline reading, free of secrets and
+private runtime data, and independent of generated timestamps or export bundles.

scripts/validate_docs.py

@@ -82,6 +82,7 @@ def validate_links(root: Path) -> None:
         *sorted((root / "docs").rglob("*.md")),
         *sorted((root / "examples").rglob("*.md")),
         *sorted((root / "compatibility").rglob("*.md")),
+        *sorted((root / ".ai-context").rglob("*.md")),
     ]
     for document in markdown_files:
         text = document.read_text(encoding="utf-8")