Add agent-docs discovery pointers + CHANGELOG entry

src/openarmature/__init__.py module docstring first line points at
the bundled AGENTS.md so the file shows in standard IDE hover
(Pylance / Pyright on `import openarmature`). README gets a "For AI
agents" section with the discovery one-liner adopters can point
their own AGENTS.md / CLAUDE.md at. Repo-root AGENTS.md gains a
disambiguating note distinguishing the two AGENTS.md files in the
project: this one orients agents working ON openarmature; the
bundled src/openarmature/AGENTS.md orients agents in user
codebases that USE openarmature.

CHANGELOG Unreleased section gains an Added entry covering the
bundle + discovery surface + drift check + the submodule-pin
discipline that prevents draft spec text from leaking into a
release bundle.

Author: chris-colinsky

AGENTS.md

@@ -1,8 +1,20 @@
 # AGENTS.md
 
-Orientation for coding agents working in this repo. `README.md` covers what
-the project is and how to use it; this file covers things that aren't
-obvious from reading the code.
+Orientation for coding agents working in **this repo** — i.e., agents
+contributing to openarmature itself. `README.md` covers what the project
+is and how to use it; this file covers things that aren't obvious from
+reading the code.
+
+> **Two AGENTS.md files in this project. Different audiences.**
+>
+> - This file (`./AGENTS.md`, at the repo root) — for agents working on
+>   the openarmature codebase. Package layout, test layout, tooling,
+>   spec-submodule discipline, commit conventions.
+> - `src/openarmature/AGENTS.md` (shipped in the wheel) — for agents
+>   working in user codebases that depend on openarmature. Capability
+>   contracts, common patterns, non-obvious shapes, example index.
+>   Generated by `scripts/build_agents_md.py` from canonical sources;
+>   committed and CI-drift-checked.
 
 ## Spec is the source of truth
 

CHANGELOG.md

@@ -8,6 +8,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). The
 
 ### Added
 
+- **Bundled agent documentation at `openarmature/AGENTS.md`.** The wheel now ships a generated `AGENTS.md` file at the installed package root, agent-discoverable via `python -c "import openarmature; print(openarmature.__path__[0] + '/AGENTS.md')"`. Sections include a TL;DR, capability summaries pulled from the pinned spec submodule's §1 (Purpose) + §2 (Concepts), the patterns docs, hand-written non-obvious-shapes recipes, and a one-line example index. Generator lives at `scripts/build_agents_md.py`; the committed file is CI-drift-checked by `tests/test_agents_md_drift.py`. The submodule pin discipline (build refuses unless the submodule HEAD is reachable from a `v*` tag) prevents draft spec text from leaking into a release bundle. Adopting projects can point their own `AGENTS.md` / `CLAUDE.md` at this path so agent sessions in their codebase find it automatically.
 - **`FanOutInstanceProgress.result_is_error` field** (proposal 0027, accepted in spec v0.21.0). Explicit boolean discriminator on each per-instance entry in `CheckpointRecord.fan_out_progress` — `True` for `collect`-mode error contributions (roll forward into `errors_field`), `False` for success contributions (roll forward into `target_field`). The engine reads the explicit field on resume rather than inferring routing from `result`'s shape; the previous structural heuristic (`_looks_like_error_record`) is removed. Backward-compat path on load: pre-0027 records that omit the key default to `False`.
 - **Strict `CheckpointRecordInvalid` on fan-out count drift** (proposal 0029, accepted in spec v0.22.0). When the resumed run's resolved instance count differs from the saved `fan_out_progress` entry's `instance_count`, the engine raises `CheckpointRecordInvalid` before any fan-out instance work runs on the resumed path. Replaces the pre-0029 pad/truncate behavior which silently dropped `completed` contributions on shrink (breaking §10.11.1's exactly-once guarantee) and dispatched unsaved work on grow.
 - **`tool_choice` parameter on `Provider.complete()`** (proposal 0025, accepted in spec v0.20.0). Optional discriminated-union value constraining the model's tool-calling behavior — one of `"auto"`, `"required"`, `"none"`, or a `ForceTool(name=...)` record. Validation runs pre-send: `"required"` and `ForceTool` both demand non-empty `tools`, and `ForceTool.name` must appear in the supplied list; violations raise `ProviderInvalidRequest` (§7's existing category — no new error category). When `tool_choice` is `None` (the default) the wire field is omitted and the provider's own default applies, preserving pre-0025 behavior exactly. The `OpenAIProvider` maps the spec shape onto OpenAI's wire shape per §8.1.1 (the `ForceTool.type="tool"` renames to wire `type="function"`).

README.md

@@ -195,3 +195,13 @@ A few things to notice:
 - **API reference**: auto-generated from docstrings. [openarmature.ai/reference](https://openarmature.ai/reference/)
 - **Examples**: ten runnable demos with walk-throughs. [openarmature.ai/examples](https://openarmature.ai/examples/) (source at [./examples/](./examples/))
 - **Spec**: behavioral contract this implementation conforms to. [LunarCommand/openarmature-spec](https://github.com/LunarCommand/openarmature-spec)
+
+## For AI agents
+
+If you're an AI agent working in code that uses openarmature, read the bundled agent docs before editing:
+
+```bash
+python -c "import openarmature; print(openarmature.__path__[0] + '/AGENTS.md')"
+```
+
+The file ships with the package and covers capability contracts, common patterns, non-obvious shapes, and an example index. Adopting projects can point their own `AGENTS.md` / `CLAUDE.md` at this path so agent sessions in their codebase find it automatically.

src/openarmature/__init__.py

@@ -1,4 +1,8 @@
-"""OpenArmature: workflow framework for LLM pipelines and tool-calling agents."""
+"""OpenArmature: workflow framework for LLM pipelines and tool-calling agents.
+
+AI agents: see ``AGENTS.md`` in this package for usage guidance
+(``python -c "import openarmature; print(openarmature.__path__[0] + '/AGENTS.md')"``).
+"""
 
 __version__ = "0.8.0"
 __spec_version__ = "0.22.1"