From e1f94475fe23829d58aab6e84977874da5c281a1 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 1/2] docs: add curated AI context and maintenance guidance --- .ai-context/ARCHITECTURE.md | 24 ++++++++++++++++++++++++ .ai-context/INDEX.md | 11 +++++++++++ .ai-context/PROJECT.md | 20 ++++++++++++++++++++ .ai-context/README.md | 27 +++++++++++++++++++++++++++ .ai-context/WORKFLOWS.md | 23 +++++++++++++++++++++++ CONTRIBUTING.md | 14 ++++++++++++++ 6 files changed, 119 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..8919bdb --- /dev/null +++ b/.ai-context/ARCHITECTURE.md @@ -0,0 +1,24 @@ +# 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`, attachment, and cleanup modules coordinate +execution. Public modules cover configuration, output rendering, logging, +redaction, runtime/history, inspection, and testing. 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). diff --git a/.ai-context/INDEX.md b/.ai-context/INDEX.md new file mode 100644 index 0000000..f386ec6 --- /dev/null +++ b/.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. diff --git a/.ai-context/PROJECT.md b/.ai-context/PROJECT.md new file mode 100644 index 0000000..c895366 --- /dev/null +++ b/.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). diff --git a/.ai-context/README.md b/.ai-context/README.md new file mode 100644 index 0000000..8192ce3 --- /dev/null +++ b/.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. diff --git a/.ai-context/WORKFLOWS.md b/.ai-context/WORKFLOWS.md new file mode 100644 index 0000000..f57a17e --- /dev/null +++ b/.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). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 385b90d..bba7ef5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -69,3 +69,17 @@ 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` 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. From 634ab2744bfb33b87bd1a5c9631872d133b7881b Mon Sep 17 00:00:00 2001 From: Ramesh Padmanabhaiah <22363102+codeforester@users.noreply.github.com> Date: Tue, 27 Oct 2026 23:43:31 +0530 Subject: [PATCH 2/2] docs: keep AI context references accurate --- .ai-context/ARCHITECTURE.md | 10 ++++++---- CONTRIBUTING.md | 6 ++++-- scripts/validate_docs.py | 1 + 3 files changed, 11 insertions(+), 6 deletions(-) diff --git a/.ai-context/ARCHITECTURE.md b/.ai-context/ARCHITECTURE.md index 8919bdb..ad12b10 100644 --- a/.ai-context/ARCHITECTURE.md +++ b/.ai-context/ARCHITECTURE.md @@ -7,10 +7,12 @@ 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`, attachment, and cleanup modules coordinate -execution. Public modules cover configuration, output rendering, logging, -redaction, runtime/history, inspection, and testing. Optional Typer and other -integrations do not become unconditional core dependencies. +`_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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bba7ef5..ebbb66b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -79,7 +79,9 @@ 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`. +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. diff --git a/scripts/validate_docs.py b/scripts/validate_docs.py index 708b8a1..47c642e 100644 --- a/scripts/validate_docs.py +++ b/scripts/validate_docs.py @@ -81,6 +81,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")