docs: add curated AI context and maintenance guidance

.ai-context/ARCHITECTURE.md

@@ -0,0 +1,22 @@
+# Architecture
+
+`src/base_cli_demo/cli.py` declares the Northstar Click tree and attaches a
+generic Base-CLI profile through the public `base_cli` facade. Service fixtures
+live under `src/base_cli_demo/fixtures/`; packaging declares the `northstar`
+console script in `pyproject.toml`.
+
+`status` renders fixture service state. `release plan` builds a release plan,
+and `release reconcile` demonstrates consumer-owned reconciliation with a dry-run
+boundary. `config show` reports normalized configuration and its provenance.
+An explicit JSON configuration can filter services by owner and select a default
+release target; no explicit configuration preserves generic defaults.
+
+Global lifecycle options such as `--environment`, `--quiet`, and `--dry-run`
+belong before the subcommand. Consumer `--format` chooses a payload renderer;
+framework `--json` adds the separate lifecycle envelope. Optional YAML, Typer,
+Rich, and OpenTelemetry scenarios have explicit dependency boundaries. Tests
+exercise public framework behavior rather than private imports.
+
+Sources: [consumer CLI](../src/base_cli_demo/cli.py),
+[configuration](../docs/configuration.md), [lifecycle](../docs/lifecycle-safety.md),
+[YAML](../docs/yaml-output.md), and [optional integrations](../docs/optional-integrations.md).

.ai-context/INDEX.md

@@ -0,0 +1,11 @@
+# base-cli-demo 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,21 @@
+# Northstar reference consumer
+
+Northstar is a small offline operational CLI that demonstrates embedding
+`base-cli` in a real consumer. It uses deterministic service fixtures and local
+release planning/reconciliation to explain lifecycle, machine output,
+configuration, dry-run, and error behavior.
+
+It requires its Python dependencies, not Base, Docker, cloud credentials, or
+network services at runtime. Its package/release version is independent of the
+framework version. `pyproject.toml` records the supported framework range;
+compatibility tests establish the installed-package behavior.
+
+Northstar owns its Click command tree, fixture schema, domain policy, and
+messages. Base-CLI owns reusable invocation context, logging, runtime paths,
+cleanup, and output contracts. Demonstrated reconciliation does not deploy
+software or mutate external services. Local reconciliation state has its own
+application contract and should not be mistaken for an external release.
+
+Sources: [README](../README.md), [metadata](../pyproject.toml),
+[framework value/boundary](../docs/why-base-cli.md), and
+[compatibility](../docs/compatibility.md).

.ai-context/README.md

@@ -0,0 +1,27 @@
+# AI context for base-cli-demo
+
+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,27 @@
+# Workflows
+
+Install the development extra in an isolated Python environment, then run the
+consumer's authoritative check:
+
+```bash
+python -m pip install '.[dev]'
+./tests/validate.sh
+northstar --help
+northstar --quiet --environment dev status --format json
+northstar --quiet --environment dev release plan --version 2.5.0
+northstar --quiet --environment dev --dry-run release reconcile --version 2.5.0 --format json
+```
+
+The validator verifies installed distributions before running the complete
+pytest suite, including documented-command tests. Follow the configuration guide
+for `--config` inputs and the learning path for expected output. Use temporary
+local state when experimenting with real reconciliation.
+
+Use a single issue, matching category branch, and a dedicated worktree. PRs
+record current validation and link their issue. Consumer release artifacts and
+compatibility evidence are separate from framework releases; a documentation PR
+does not update either version or publish packages.
+
+Sources: [contribution guide](../CONTRIBUTING.md), [agent guidance](../AGENTS.md),
+[learning path](../docs/learning-path.md), [validation](../tests/validate.sh), and
+[release process](../docs/release-process.md).

CONTRIBUTING.md

@@ -47,3 +47,17 @@ basectl check base-cli-demo
 basectl doctor base-cli-demo
 basectl test base-cli-demo
 ```
+
+## 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` and
+`basectl export-context --print` from the checkout, plus `git diff --check`.
+Keep the pack self-contained enough for offline reading, free of secrets and
+private runtime data, and independent of generated timestamps or export bundles.