From c505723e7d0d569737500e67d24294a8560ebf07 Mon Sep 17 00:00:00 2001 From: Ramesh Padmanabhaiah <22363102+codeforester@users.noreply.github.com> Date: Wed, 21 Oct 2026 21:04:58 +0530 Subject: [PATCH] docs: add curated AI context and maintenance guidance --- .ai-context/ARCHITECTURE.md | 22 ++++++++++++++++++++++ .ai-context/INDEX.md | 11 +++++++++++ .ai-context/PROJECT.md | 21 +++++++++++++++++++++ .ai-context/README.md | 27 +++++++++++++++++++++++++++ .ai-context/WORKFLOWS.md | 27 +++++++++++++++++++++++++++ CONTRIBUTING.md | 14 ++++++++++++++ 6 files changed, 122 insertions(+) create mode 100644 .ai-context/ARCHITECTURE.md create mode 100644 .ai-context/INDEX.md create mode 100644 .ai-context/PROJECT.md create mode 100644 .ai-context/README.md create mode 100644 .ai-context/WORKFLOWS.md diff --git a/.ai-context/ARCHITECTURE.md b/.ai-context/ARCHITECTURE.md new file mode 100644 index 0000000..4132ff9 --- /dev/null +++ b/.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). diff --git a/.ai-context/INDEX.md b/.ai-context/INDEX.md new file mode 100644 index 0000000..bd5db8e --- /dev/null +++ b/.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. diff --git a/.ai-context/PROJECT.md b/.ai-context/PROJECT.md new file mode 100644 index 0000000..f2e6089 --- /dev/null +++ b/.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). diff --git a/.ai-context/README.md b/.ai-context/README.md new file mode 100644 index 0000000..2b4ad02 --- /dev/null +++ b/.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. diff --git a/.ai-context/WORKFLOWS.md b/.ai-context/WORKFLOWS.md new file mode 100644 index 0000000..db54298 --- /dev/null +++ b/.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). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 62fe5a8..c4e43c6 100644 --- a/CONTRIBUTING.md +++ b/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.