agentrules 3.4.1__tar.gz

agentrules-3.4.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Trevor Nichols
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentrules-3.4.1/PKG-INFO

@@ -0,0 +1,385 @@
+Metadata-Version: 2.4
+Name: agentrules
+Version: 3.4.1
+Summary: AGENTS.md/CLAUDE.md generator and ExecPlan harness for coding agents
+Author: trevor-nichols
+License-Expression: MIT
+Keywords: cursor,ai,analysis,cli,agents
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anthropic>=0.78.0
+Requires-Dist: rich
+Requires-Dist: openai
+Requires-Dist: google-genai>=1.51.0
+Requires-Dist: protobuf>=4.25
+Requires-Dist: python-dotenv
+Requires-Dist: tavily-python>=0.7.14
+Requires-Dist: typer>=0.12
+Requires-Dist: questionary>=2.0
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: pathspec>=0.12
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: tomli; python_version < "3.11"
+Requires-Dist: tomli-w
+Requires-Dist: tiktoken>=0.7.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+Requires-Dist: flask; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: pyright>=1.1.380; extra == "dev"
+Dynamic: license-file
+
+# 🤖 AgentRules Architect v3
+
+<div align="center">
+
+[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://choosealicense.com/licenses/mit/)
+[![OpenAI](https://img.shields.io/badge/OpenAI-supported-blue.svg)](https://openai.com/)
+[![Codex Runtime](https://img.shields.io/badge/Codex%20app--server-supported-orange.svg)](https://github.com/openai/codex)
+[![Anthropic](https://img.shields.io/badge/Anthropic-supported-purple.svg)](https://www.anthropic.com/)
+[![DeepSeek](https://img.shields.io/badge/DeepSeek-supported-red.svg)](https://deepseek.com/)
+[![Google](https://img.shields.io/badge/Google-supported-green.svg)](https://ai.google.dev/)
+[![xAI](https://img.shields.io/badge/xAI-supported-black.svg)](https://x.ai/)
+[![Built By](https://img.shields.io/badge/Built%20By-trevor-nichols-orange.svg)](https://github.com/trevor-nichols)
+
+**Your multi-provider AI code analysis and AGENTS.md generator 🚀**
+
+[Demo](#-cli-demo) • [Highlights](#-v3-highlights) • [Features](#-feature-overview) • [Requirements](#-requirements) • [Installation](#-installation) • [Codex Runtime](#-configure-codex-runtime-optional) • [CLI](#-cli-at-a-glance) • [Configuration](#-configuration--preferences) • [Architecture](#-project-architecture) • [Outputs](#-output-artifacts) • [Development](#-development-workflow)
+
+</div>
+
+## 🎥 CLI Demo
+
+![AgentRules CLI demo](docs/assets/media/demo.gif)
+
+## Why AgentRules Architect?
+
+Version 3 rebrands the project from **CursorRules Architect** to **AgentRules Architect** to match the standardized `AGENTS.md` contract used across modern AI coding agents. The rename comes with a fresh Typer-powered CLI, a persistent configuration service, broader provider support across Anthropic, OpenAI, Google, DeepSeek, xAI, and the local Codex app-server runtime, and a tooling layer that keeps the six-phase analysis reliably consistent yet flexibly extensible to your project's unique needs.
+
+## 🔥 v3 Highlights
+
+- ✨ **Rebrand & packaging** – ships with console-script and `python -m agentrules` entry points when installed from source.
+- 🧭 **Typer CLI overhaul** – `agentrules` launches an interactive main menu with subcommands for `analyze`, `configure`, and `keys`.
+- 🗂️ **Persistent settings** – API keys, model presets, logging, and output preferences live in `~/.config/agentrules/config.toml` (override with `AGENTRULES_CONFIG_DIR`).
+- 🧠 **Expanded provider matrix** – the preset catalog spans Anthropic, OpenAI, Google, DeepSeek, xAI, and Codex runtime presets, with phase-by-phase model selection from the CLI or config file.
+- 🧰 **Codex runtime support** – route phases through local `codex app-server` with ChatGPT auth via `CODEX_HOME` (no AgentRules-stored OpenAI API key required).
+- 🔌 **Unified tool management** – the new `ToolManager` adapts JSON tool schemas for each provider; Tavily web search is available to researcher agents with one toggle.
+- ✅ **Test & quality backbone** – 200+ unit/integration tests, Pyright, Ruff, and offline stubs provide confidence without hitting live APIs.
+
+## ✨ Feature Overview
+
+- 🌐 Multi-provider orchestration with consistent streaming telemetry.
+- 🔍 Six-phase pipeline: discovery → planning → deep dives → synthesis → consolidation → final AGENTS.md generation.
+- 🧩 Researcher tooling via Tavily search with provider-aware tool translation.
+- 📊 Rich terminal UI (Rich) showing per-agent progress, duration, and failures in real time.
+- 🪵 Configurable outputs: `AGENTS.md`, `SNAPSHOT.md` (enabled by default), `.cursorignore`, optional `.agent/` scaffold templates, and per-phase markdown/json snapshots.
+- 🔧 Declarative model presets plus runtime overrides via CLI or TOML.
+
+## 🧮 Analysis Pipeline
+
+All CLI entry points ultimately execute the `AnalysisPipeline` orchestrator (`src/agentrules/core/pipeline`) that wires the six analysis phases together and streams progress events to the Rich console.
+
+1. **Phase 1 – Initial Discovery** (`core/analysis/phase_1.py`) inventories the repo tree, surfaces tech stack signals, and collects dependency metadata that later phases reuse.
+2. **Phase 2 – Methodical Planning** (`core/analysis/phase_2.py`) asks the configured model to draft an XML-ish agent plan, then parses it into structured agent definitions (with a safe fallback extractor).
+3. **Phase 3 – Deep Analysis** (`core/analysis/phase_3.py`) spins up specialized architects per agent definition, hydrates them with file excerpts, and runs them in parallel; if no plan exists it falls back to three default agents.
+4. **Phase 4 – Synthesis** (`core/analysis/phase_4.py`) stitches together Phase 3 findings, elevates cross-cutting insights, and flags follow-up prompts for the final steps.
+5. **Phase 5 – Consolidation** (`core/analysis/phase_5.py`) produces a canonical report object that downstream tooling (rules generator, metrics, exporters) consumes.
+6. **Final Analysis** (`core/analysis/final_analysis.py`) produces the narrative summary that drives `AGENTS.md`, output toggles, and console highlights.
+
+The pipeline captures metrics (elapsed time, agent counts) and hands them to the output writer so offline runs and full analyses share the same persistence path.
+
+## 🛠 Requirements
+
+- Python **3.11.9+** (matches Pyright target and packaged metadata).
+- API key(s) for at least one provider:
+  - Anthropic
+  - OpenAI
+  - DeepSeek
+  - Google
+  - xAI
+  - Tavily (optional, enables live web search tooling)
+- Optional local runtime provider:
+  - Codex CLI (`codex`) for `codex app-server` integration
+- Current preset IDs live in `src/agentrules/config/agents.py`.
+- Core dependencies: `anthropic`, `openai`, `google-genai>=1.51.0`, `tavily-python`, `tiktoken`, `rich`, `typer`, `questionary`, `platformdirs`, `pathspec`, `python-dotenv`, `protobuf`.
+- Dev tooling: `pytest`, `pytest-asyncio`, `pytest-mock`, `flask`, `ruff`, `pyright`.
+
+## 📦 Installation
+
+### Install from PyPI
+
+```bash
+pip install agentrules
+```
+
+### Install from source
+
+```bash
+git clone https://github.com/trevor-nichols/agentrules-architect.git
+cd agentrules-architect
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Need a one-liner? Use the helper script:
+
+```bash
+./scripts/bootstrap_env.sh           # set PYTHON_BIN=/abs/path/to/python to override interpreter
+```
+
+### Quick smoke test
+
+```bash
+agentrules --version
+agentrules analyze /path/to/project
+```
+
+Prefer module execution during development? Invoke the CLI with Python’s module flag—the package ships a `__main__` entry point:
+
+```bash
+python -m agentrules analyze /path/to/project
+```
+
+Need to install directly from GitHub instead of PyPI?
+
+```bash
+pip install "git+https://github.com/trevor-nichols/agentrules-architect.git#egg=agentrules"
+```
+
+## 🔐 Configure API Keys
+
+Run the interactive configurator to store credentials securely:
+
+```bash
+agentrules configure
+```
+
+- Keys are saved to `~/.config/agentrules/config.toml` (override with `AGENTRULES_CONFIG_DIR`).
+- Values are mirrored into environment variables on the next launch.
+- Use `agentrules configure --provider openai` for quick single-key updates.
+- Show current status with:
+
+```bash
+agentrules keys
+```
+
+## 🧰 Configure Codex Runtime (Optional)
+
+AgentRules supports Codex as a local runtime provider via `codex app-server`, separate from API-key providers.
+
+- Open `agentrules` -> `Settings` -> `Codex runtime`
+- Configure:
+  - executable path (`codex` by default)
+  - `CODEX_HOME` strategy (`managed` or `inherit`)
+  - optional managed home override
+- Use `Sign in with ChatGPT` to authenticate runtime-backed model access.
+
+After runtime setup, choose Codex presets under `Settings -> Model presets per phase`.
+
+See [docs/codex-runtime.md](docs/codex-runtime.md) for complete setup, auth flow, model catalog behavior, and live smoke instructions.
+
+## 🧭 CLI At A Glance
+
+- `agentrules` – interactive main menu (analyze, configure models/outputs, check keys).
+- `agentrules analyze /path/to/project` – full six-phase analysis.
+- `agentrules analyze /path/to/project --rules-filename CLAUDE.md` – one-run override for output rules filename.
+- `agentrules snapshot generate [path]` – create (or refresh) `SNAPSHOT.md` in the current directory by default.
+- `agentrules snapshot sync [path]` – sync an existing snapshot as project files evolve (also creates if missing).
+- `agentrules execplan new \"Title\"` – create a new ExecPlan markdown file under `.agent/exec_plans/active/<slug>/`.
+- `agentrules execplan archive EP-YYYYMMDD-NNN [--date YYYYMMDD]` – archive a full ExecPlan directory under `.agent/exec_plans/archive/YYYY/MM/DD/EP-YYYYMMDD-NNN_<slug>/`.
+- `agentrules execplan list [--path]` – list active ExecPlans with compact milestone progress (`completed/total`).
+- `agentrules execplan milestone new EP-YYYYMMDD-NNN \"Title\" [--ms N]` – create a milestone under a specific ExecPlan (auto sequence by default, or explicit `MS###` when provided).
+- `agentrules execplan milestone list EP-YYYYMMDD-NNN [--active-only]` – list milestones for one ExecPlan.
+- `agentrules execplan milestone archive EP-YYYYMMDD-NNN --ms <N>` – archive an active milestone sequence.
+- `agentrules execplan milestone remaining EP-YYYYMMDD-NNN [--path]` – show active milestones left for one ExecPlan.
+- `agentrules execplan-registry [build|check|update]` – manage `.agent/exec_plans/registry.json` from ExecPlan front matter.
+- `agentrules scaffold sync [--check|--force]` – sync `.agent/PLANS.md` and `.agent/templates/MILESTONE_TEMPLATE.md` with packaged defaults.
+- `agentrules configure --models` – assign presets per phase with guided prompts; the Phase 1 → Researcher entry lets you toggle the agent On/Off once a Tavily key is configured.
+- `agentrules configure --outputs` – toggle `.cursorignore`, `.agent/` scaffold generation, `phases_output/`, and custom rules filename.
+- `agentrules configure --logging` – set verbosity (`quiet`, `standard`, `verbose`) or export via `AGENTRULES_LOG_LEVEL`.
+
+## 🧭 ExecPlan & Milestones
+
+ExecPlans are long-horizon execution artifacts for work that is too large for a single prompt/session and too risky to run as ad hoc edits.
+They give humans and agents a durable plan, explicit scope, and audit trail that can survive context switching across days or weeks.
+
+This follows the same general planning pattern OpenAI now recommends for larger Codex work: start with an implementation plan, then execute it iteratively in smaller scoped chunks (see [OpenAI Codex docs](https://developers.openai.com/codex) and [How OpenAI uses Codex](https://openai.com/index/how-openai-uses-codex/)).
+
+Think of the model in three layers:
+
+- **ExecPlan (strategic layer)** – one high-level objective, constraints, success criteria, and overall rollout strategy.
+- **Milestones (delivery layer)** – concrete sub-deliverables within that plan, sequenced (`MS001`, `MS002`, ...) and independently completable.
+- **Task checklists (execution layer)** – fine-grained implementation/validation steps inside each plan or milestone document.
+
+Why this exists:
+
+- Keep long-running work coherent across multiple agent runs.
+- Make progress and remaining scope visible at a glance.
+- Reduce regressions by forcing explicit sequencing, verification, and rollback thinking.
+- Preserve design decisions and rationale in one canonical place.
+
+ExecPlans and milestones use canonical IDs and deterministic file locations:
+
+- ExecPlan ID: `EP-YYYYMMDD-NNN`
+- Milestone ID: `EP-YYYYMMDD-NNN/MS###`
+- Active ExecPlan path: `.agent/exec_plans/active/<plan-slug>/EP-YYYYMMDD-NNN_<plan-slug>.md`
+- Archived ExecPlan path: `.agent/exec_plans/archive/YYYY/MM/DD/EP-YYYYMMDD-NNN_<plan-slug>/EP-YYYYMMDD-NNN_<plan-slug>.md`
+- Active milestone path: `.agent/exec_plans/active/<plan-slug>/milestones/active/MS###_<milestone-slug>.md`
+- Archive milestone path: `.agent/exec_plans/active/<plan-slug>/milestones/archive/MS###_<milestone-slug>.md`
+
+Milestone creation is parent-first and sequence-safe:
+
+- Users provide parent ExecPlan ID + milestone title.
+- CLI/API assign `MS###` automatically, or accept `--ms N` to request a specific sequence.
+- Sequence is monotonic per plan across active and archived milestones (`MS001`, `MS002`, ...).
+- `.agent/templates/MILESTONE_TEMPLATE.md` is a guidance scaffold for authors.
+  Generated milestone files come from an internal file template used by `execplan milestone new`.
+
+Examples:
+
+```bash
+# 1) Create an ExecPlan
+agentrules execplan new "Auth Refresh" --date 20260207
+
+# 2) Create milestones for that plan (auto-assigns MS001, then MS002, ...)
+agentrules execplan milestone new EP-20260207-001 "Design callback flow"
+agentrules execplan milestone new EP-20260207-001 "Implement callback flow"
+
+# Optional: request an explicit sequence (must be unused)
+agentrules execplan milestone new EP-20260207-001 "Backfill docs" --ms 5
+
+# 3) List milestones (all or active-only)
+agentrules execplan milestone list EP-20260207-001
+agentrules execplan milestone list EP-20260207-001 --active-only
+
+# Optional: compact "what's left" view for active milestones only
+agentrules execplan milestone remaining EP-20260207-001
+
+# 4) Archive a completed milestone
+agentrules execplan milestone archive EP-20260207-001 --ms 1
+
+# 5) Archive the completed ExecPlan directory
+agentrules execplan archive EP-20260207-001 --date 20260212
+
+# Optional: list all active plans with compact milestone progress
+agentrules execplan list
+```
+
+## ⚙️ Configuration & Preferences
+
+- **Config file**: `~/.config/agentrules/config.toml`
+  - `providers` – API keys per provider.
+  - `codex` – local runtime settings (`cli_path`, `home_strategy`, `managed_home`).
+  - `models` – preset IDs applied to each phase (`phase1`, `phase2`, `final`, `researcher`, …).
+  - `outputs` – `generate_cursorignore`, `generate_agent_scaffold`, `generate_phase_outputs`, `generate_snapshot`, `rules_filename`, `snapshot_filename`.
+    - `generate_snapshot` defaults to `true` and writes `SNAPSHOT.md` at project root after each analysis run (toggle anytime in `agentrules configure --outputs`).
+  - `features` – `researcher_mode` (`on`/`off`) to control Phase 1 web research (managed from the Researcher row in the models wizard).
+  - `exclusions` – add/remove directories, files, or extensions; choose to respect `.gitignore`.
+- **Runtime helpers** (via `agentrules/core/configuration/manager.py`):
+  - `ConfigManager.get_effective_exclusions()` resolves overrides with defaults from `config/exclusions.py`.
+  - `ConfigManager.should_generate_phase_outputs()` and related methods toggle output writers in `core/utils/file_creation`.
+- **Environment variables**:
+  - `AGENTRULES_CONFIG_DIR` – alternate config root.
+  - `AGENTRULES_LOG_LEVEL` – overrides persisted verbosity.
+  - `AGENTRULES_RULES_FILENAME` – runtime override for generated rules filename (for example `CLAUDE.md`).
+  - `CODEX_HOME` – used when Codex `home_strategy = "inherit"`.
+- **Rules filename precedence**:
+  1. `agentrules analyze --rules-filename <name>`
+  2. `AGENTRULES_RULES_FILENAME`
+  3. `outputs.rules_filename` in `config.toml` (set via `agentrules configure --outputs`)
+  4. `AGENTS.md` default
+
+## 🧠 Model Presets & Providers
+
+Presets live in `config/agents.py` via the `MODEL_PRESETS` dictionary. Each preset bundles:
+
+- Provider (`ModelProvider`)
+- Model name plus reasoning/temperature configuration
+- Human-readable label and description for the CLI wizard
+
+The app currently exposes presets across these providers:
+
+- Anthropic
+- OpenAI
+- Codex App Server (local runtime)
+- Google
+- DeepSeek
+- xAI
+
+Choose any available preset per phase through the CLI (`agentrules configure --models`) or by editing `config.toml` / `config/agents.py`. At runtime the values populate `MODEL_CONFIG`, which the pipeline consumes while resolving phase architects (`src/agentrules/core/agents/factory/factory.py`).
+
+> **Preset tip:** Legacy-friendly presets stay under the `gpt5-*` keys (backed by the `gpt-5` model name) so existing `config.toml` files continue to work, while the newer GPT‑5.1 presets live under the `gpt51-*` keys and GPT‑5.2 presets under `gpt52-*`. Mixing them per phase or per-agent is fully supported.
+
+## 🧠 Reasoning & Advanced Configuration
+
+- **Reasoning modes:** Anthropic presets use fixed-budget or adaptive thinking depending on the Claude family, Gemini presets use provider-native thinking controls, OpenAI presets map to reasoning effort or temperature based on model family, and DeepSeek/xAI presets keep their provider-native reasoning behavior (`src/agentrules/core/types/models.py`).
+- **Codex runtime modes:** Codex presets route the same model families through `codex app-server`, with runtime-discovered model/effort variants available from the live model catalog.
+- **Agent planning:** Phase 2 generates agent manifests that Phase 3 converts into live architects; when parsing fails the fallback extractor and default agents keep the pipeline running (`core/analysis/phase_2.py`, `core/analysis/phase_3.py`).
+- **Provider-specific tools:** `create_researcher_config` enables Tavily-backed tool use for whichever preset you promote to the Researcher role, and the CLI’s Researcher row simply flips that on/off (`core/types/models.py`, `config/tools.py`).
+- **Prompt customization:** Fine-tune behaviour by editing the phase prompts under `src/agentrules/config/prompts/`—heavy modifications should stay aligned with the YAML/XML formats expected by the parser utilities.
+- **Token-aware runs:** Architects now emit token preflight logs using configured context limits/estimators, and Phase 3 uses limit-aware batching plus summarization when a model’s max input tokens are provided.
+- **Direct overrides:** Advanced users can swap presets or tweak reasoning levels by modifying `MODEL_PRESETS`/`MODEL_PRESET_DEFAULTS` in `config/agents.py`; the configuration manager merges those with TOML overrides at runtime.
+
+## 🔍 Tooling & Research Agents
+
+- `core/agent_tools/tool_manager.py` normalizes JSON tool schemas for each provider.
+- `config/tools.py` exposes `TOOL_SETS` and a `with_tools_enabled` helper for models that accept function/tool calls.
+- Tavily search (`tavily_web_search`) ships as the default researcher tool. Add `TAVILY_API_KEY` in the provider settings to automatically enable the Researcher agent, then pick the model (or flip it back `Off`) from the models wizard’s Researcher entry. When disabled—or when no key is present—documentation research is skipped; our contributor smoke tests use deterministic stubs to keep CI free of external calls. The dependency agent automatically downgrades from “knowledge gaps” mode to its legacy full catalog so downstream agents still receive usable dependency data when research is unavailable.
+
+## 🧱 Project Architecture
+
+- `agentrules/` – Typer CLI, interactive Questionary flows, Rich UI, configuration services, and pipeline runner (`agentrules/SNAPSHOT.md`).
+- `core/` – provider-specific architects (`core/agents`), analysis phases (`core/analysis`), tool adapters (`core/agent_tools`), streaming primitives, and filesystem utilities (`core/SNAPSHOT.md`).
+- `config/` – preset definitions, exclusions, prompts, and tool bindings (`config/SNAPSHOT.md`).
+- `tests/` – live smoke tests, deterministic offline stubs for CI, provider fixtures, and unit coverage for helpers and phases.
+- `pyproject.toml` – package metadata, scripts, Ruff/Pyright config, and dependency declarations.
+
+## 🧾 Output Artifacts
+
+By default the pipeline produces:
+
+- `AGENTS.md` (or your custom rules filename) – cleaned, standardized agent instructions.
+- `SNAPSHOT.md` – full project tree snapshot (no depth limit by default) generated at the project root after the pipeline finishes.
+- `.cursorignore` – generated when enabled to keep editor agents focused on relevant files.
+- `.agent/` scaffold – generated when enabled (`.agent/PLANS.md` and `.agent/templates/MILESTONE_TEMPLATE.md`).
+- `phases_output/` – per-phase markdown/JSON snapshots for auditing and downstream automation.
+- Want a concrete sample? See `docs/examples/phases_output/` for a full run’s phase artifacts.
+- Rich console logs summarizing model usage, timing, and file counts.
+
+Toggle outputs with `agentrules configure --outputs` or via the config TOML.
+
+## 🛠 Development Workflow
+
+- Install dev extras: `pip install -e .[dev]`
+- Format & lint: `ruff format . && ruff check .`
+- Static typing: `pyright`
+- Run targeted tests: `python tests/phase_3_test/run_test.py`
+- Deterministic smoke runs (CI/local without API calls): `agentrules analyze --offline tests/tests_input`
+- Full suite: `python -m unittest discover tests -v`
+- Releases are tag-driven: bump `[project].version` in `pyproject.toml`, commit, create matching `vX.Y.Z` tag, and push it.
+- GitHub Actions now publishes package artifacts with Trusted Publishing (OIDC) via `.github/workflows/publish-pypi.yml` (no long-lived PyPI API token).
+- Run a safe preflight publish first from Actions with `workflow_dispatch` and `repository = testpypi`; publish to production PyPI on tag push or manual `repository = pypi`.
+- Keep docs and presets in sync when adding providers (`config/agents.py`, `config/tools.py`, `core/agents/*`).
+
+### Release Process (PyPI)
+
+1. Update `[project].version` in `pyproject.toml`, then commit and push.
+2. Run `.github/workflows/publish-pypi.yml` manually with `repository = testpypi` to validate package upload first.
+3. Create and push matching tag `vX.Y.Z` to trigger Trusted Publishing to PyPI.
+4. The same tag also triggers `.github/workflows/release.yml` for GitHub Release artifact/notes.
+
+## 🤝 Contributing
+
+See `CONTRIBUTING.md` for detailed guidelines on workflows, testing, and pull request expectations. Issues and PRs are welcome—just ensure Ruff/Pyright/tests pass before submitting.
+
+## 📄 License
+
+Released under the MIT License. See `LICENSE` for details.