Add bundled AGENTS.md generator + drift test

The wheel now ships a generated AGENTS.md at the installed package
root (openarmature/AGENTS.md) for AI agents working in code that
uses openarmature. Sections, in order: version-stamped self-
reference header, TL;DR, capability summaries (spec §1+§2 of
graph-engine / pipeline-utilities / llm-provider / observability /
prompt-management), patterns from docs/patterns/*.md, hand-written
non-obvious-shapes recipes, example index (one-liners + paths
inside the source tree), discovery footer.

Generator at scripts/build_agents_md.py reads from the pinned spec
submodule via `git show <sha>:spec/...` (not the working tree) and
refuses to regenerate unless the submodule HEAD is reachable from a
v* tag — closes the "release ships a bundle pinned to draft spec
text" failure mode. Spec text and patterns are pulled verbatim; the
non-obvious-shapes file (docs/agent/non-obvious-shapes.md) and the
TL;DR (docs/agent/tldr.md) are hand-curated by python.

tests/test_agents_md_drift.py regenerates in-memory and diffs
against the committed src/openarmature/AGENTS.md, failing the suite
when the bundle is stale relative to its sources. Run on every PR
via the standard pytest invocation.

Bundle is 908 lines / 46KB at v0.22.1 — dense enough to be
authoritative without ballooning past useful agent context budgets.

Author: chris-colinsky

docs/agent/non-obvious-shapes.md

@@ -0,0 +1,45 @@
+## Non-obvious shapes
+
+Recipes that aren't deducible from the API surface alone. The primitives docs tell you what's possible; this section tells you what's smart.
+
+### Use the bundled `FilesystemCheckpointer` or `SQLiteCheckpointer`, not a hand-rolled serializer
+
+The temptation when persisting graph state is to `json.dumps(state.model_dump())` and write to a file. Don't. The shipped Checkpointer backends handle every contract `openarmature.checkpoint.Checkpointer` defines — round-trip integrity, `parent_states` for inner-save resume, fan-out progress tracking, schema-version migration, listing by `correlation_id`, `CheckpointRecordInvalid` on shape drift. A hand-rolled serializer that "works" on the happy path silently fails the moment a fan-out crash leaves an in-flight save record, and you'll be debugging it for hours before realizing the bundled backend exists.
+
+If your storage requirement isn't local disk (`FilesystemCheckpointer`) or local SQLite (`SQLiteCheckpointer` — also supports `:memory:` and arbitrary file paths), implement the `Checkpointer` Protocol against your backend rather than wrapping state serialization yourself. Custom backends inherit the spec's correctness contract for free.
+
+### Subgraphs > conditional-edge spaghetti when branches don't share state
+
+A common shape is "after this LLM call, route to either a JSON-extraction node or a tool-dispatch node depending on `finish_reason`." The naive solution is two conditional edges from the LLM node, one to each downstream. That works for two branches; it scales poorly past three.
+
+When the branches operate on different sub-shapes of state — e.g., one path is "extract JSON, then validate" while another is "dispatch tools, loop until done, then summarize" — encapsulate each as a `SubgraphNode` and route from the LLM node to the right subgraph. Each subgraph has its own state schema (projected from the parent), its own entry node, and its own internal topology. The parent graph becomes a switchboard with a few edges; the complexity lives one layer down where it composes cleanly.
+
+### Be explicit with `tool_choice`; don't trust the provider's default
+
+`Provider.complete(messages, tools, tool_choice=...)` accepts `"auto"`, `"required"`, `"none"`, or a `ForceTool(name=...)` record. When you omit `tool_choice`, the OpenAI provider's own default applies — usually `"auto"` when `tools` is non-empty, but documented per-provider. A pipeline that wants deterministic tool-calling (a routing node that MUST produce a tool call, a guarded LLM call that MUST NOT call tools) should pin `tool_choice` explicitly rather than relying on the provider default.
+
+Pre-send validation catches the three §5 failure modes (`required` with empty tools, `ForceTool` with empty tools, `ForceTool.name` not in tools) and raises `ProviderInvalidRequest` before the HTTP call. Not all providers honor `tool_choice` — confirm with your provider's docs — but the OpenAI-compatible mapping is in `OpenAIProvider`.
+
+### Always `await graph.drain()` in short-lived processes; supply a `timeout` if observers might hang
+
+`CompiledGraph.invoke()` returns when the graph reaches END or raises; observer events are dispatched onto a per-invocation queue and delivered by a background worker. The graph's execution loop never awaits observer processing. In a long-running service this is invisible — the worker drains naturally. In a CLI, script, or serverless function, the process exits before the worker finishes, and any late observer events (typically the last node's `completed` event plus any `checkpoint_saved` events) get dropped.
+
+Always call `await graph.drain()` before the short-lived process exits. If your observer set includes anything that might hang (a metrics observer with a flaky network endpoint, an OTel exporter behind a slow OTLP collector), supply a `timeout`:
+
+```python
+summary = await graph.drain(timeout=5.0)
+if summary.timeout_reached:
+    log.warning("drain truncated: %d events undelivered", summary.undelivered_count)
+```
+
+The compiled graph stays usable for subsequent invocations after a timed-out drain — workers are cancelled cleanly, no partial state leaks.
+
+### Three exception hierarchies; know which one your code catches
+
+`openarmature` exceptions split across three sibling hierarchies:
+
+- `RuntimeGraphError` (in `openarmature.graph`) — node execution failures: `NodeException`, `RoutingError`, `EdgeException`, `ReducerError`, `StateValidationError`. Each has a `category` string matching the spec's canonical error categories.
+- `CheckpointError` (in `openarmature.checkpoint`) — persistence failures: `CheckpointNotFound`, `CheckpointSaveFailed`, `CheckpointRecordInvalid`, `CheckpointStateMigrationMissing`, `CheckpointStateMigrationFailed`, `CheckpointStateMigrationChainAmbiguous`.
+- `LlmProviderError` (in `openarmature.llm`) — provider call failures: `ProviderAuthentication`, `ProviderInvalidRequest`, `ProviderInvalidResponse`, `ProviderInvalidModel`, `ProviderModelNotLoaded`, `ProviderRateLimit`, `ProviderUnavailable`, `ProviderUnsupportedContentBlock`, `StructuredOutputInvalid`.
+
+Catching `Exception` works but is too broad; catching one hierarchy misses the other two. If you want to branch on category strings (e.g., for retry logic), catch the relevant base — `RuntimeGraphError` covers all five spec runtime categories, `LlmProviderError` covers all nine provider categories, `CheckpointError` covers all six checkpoint categories. The `TRANSIENT_CATEGORIES` frozenset in `openarmature.llm` enumerates which provider categories are retriable.

docs/agent/tldr.md

@@ -0,0 +1,3 @@
+OpenArmature is a workflow framework for LLM pipelines and tool-calling agents — typed state, compile-time topology checks, observability, and crash-safe checkpoints baked into a graph engine. The graph layer has no concept of LLMs or tools; the same primitives drive deterministic ETL pipelines and tool-calling agents alike. Nodes return partial updates; the engine merges into a frozen state snapshot. Behavior is defined by [openarmature-spec](https://openarmature.ai/capabilities/) and verified by conformance fixtures; this package is the reference Python implementation.
+
+**What OpenArmature is NOT:** not a chat framework (no built-in messages channel), not an LLM SDK (Provider is the abstraction layer; OpenAIProvider is the canonical impl), not a state-management library (state is per-invocation, not application-wide), not an evaluation framework (deferred to `openarmature-eval`).

scripts/build_agents_md.py

@@ -0,0 +1,269 @@
+"""Generator for the bundled ``src/openarmature/AGENTS.md`` agent docs.
+
+Pulls from canonical sources (pinned spec submodule, patterns docs,
+hand-curated agent docs, example program docstrings) and concatenates
+into a single agent-discoverable file shipped in the wheel.
+
+Sources, in order of bundle layout:
+
+1. Self-reference header — version-stamped, pointers out to the docs
+   site and the spec capabilities page.
+2. ``docs/agent/tldr.md`` — hand-written 3-5 sentence orientation.
+3. Capability summaries — §1 (Purpose) + §2 (Concepts) of each
+   capability spec, read from the pinned ``openarmature-spec``
+   submodule via ``git show <sha>:spec/...`` rather than the
+   working tree.
+4. ``docs/patterns/*.md`` — verbatim concatenation of the patterns
+   docs (excluding ``index.md``).
+5. ``docs/agent/non-obvious-shapes.md`` — hand-written opinionated
+   recipes.
+6. Example index — one-line description + path for each
+   ``examples/*/main.py`` program.
+7. Discovery footer — pointer back out to docs / spec / host
+   project conventions.
+
+Build-time invariants (matches proposal-0028 follow-on review's
+submodule-pin discipline):
+
+- Submodule HEAD MUST be reachable from a ``v*`` tag. The build
+  refuses to read draft (untagged) spec text into a release bundle.
+- Spec text is read from the pinned commit via ``git show``, NOT
+  from the submodule working tree. Closes the "submodule HEAD
+  moved but bundle still reads stale tree" failure mode.
+
+Drift between the committed bundle and the regenerated output is
+caught by ``tests/test_agents_md_drift.py``.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+# Make ``openarmature`` importable without requiring an editable install
+# pass through ``uv`` — the build script runs locally and on CI.
+REPO_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(REPO_ROOT / "src"))
+
+import openarmature  # noqa: E402
+
+SPEC_ROOT = REPO_ROOT / "openarmature-spec"
+DOCS = REPO_ROOT / "docs"
+EXAMPLES = REPO_ROOT / "examples"
+OUTPUT = REPO_ROOT / "src" / "openarmature" / "AGENTS.md"
+
+# Spec capability directory names under ``openarmature-spec/spec/``,
+# in the order they appear in the bundle's "Capability contracts"
+# section. The order matches the order capabilities were introduced
+# (graph-engine first, prompt-management most recent) so an agent
+# reading top-down sees the foundational layer before the layers
+# built on top.
+CAPABILITIES = (
+    "graph-engine",
+    "pipeline-utilities",
+    "llm-provider",
+    "observability",
+    "prompt-management",
+)
+
+
+def _git_in_spec(*args: str) -> str:
+    """Run ``git -C openarmature-spec <args>`` and return stdout stripped."""
+    return subprocess.run(
+        ["git", "-C", str(SPEC_ROOT), *args],
+        capture_output=True,
+        text=True,
+        check=True,
+    ).stdout.strip()
+
+
+def _assert_pin_at_tag() -> str:
+    """Confirm the submodule HEAD is at a ``v*`` tag.
+
+    Returns the tag name (e.g., ``v0.22.1``). Raises ``RuntimeError``
+    on a non-tag pin so a release can't accidentally ship a bundle
+    pinned to a draft spec commit.
+    """
+    sha = _git_in_spec("rev-parse", "HEAD")
+    tags_out = _git_in_spec("tag", "--points-at", sha, "--list", "v*")
+    if not tags_out:
+        raise RuntimeError(
+            f"submodule HEAD {sha[:8]} is not at a v* tag; "
+            f"bundle build refuses to read draft (untagged) spec text. "
+            f"Pin the submodule to a published tag before regenerating."
+        )
+    # Prefer the highest version tag if multiple point at the same SHA
+    # (e.g., during a re-tag) — sort by version-string descending.
+    tags = sorted(tags_out.splitlines(), reverse=True)
+    return tags[0]
+
+
+def _read_pinned_spec(path_in_spec: str) -> str:
+    """Read a file from the pinned spec commit via ``git show``.
+
+    Distinct from reading the working tree: a stale checkout would
+    silently produce stale bundle content. ``git show HEAD:<path>``
+    always reads from the recorded commit.
+    """
+    return subprocess.run(
+        ["git", "-C", str(SPEC_ROOT), "show", f"HEAD:{path_in_spec}"],
+        capture_output=True,
+        text=True,
+        check=True,
+    ).stdout
+
+
+def _header(version: str, spec_tag: str) -> str:
+    return (
+        f"# OpenArmature — Agent documentation\n"
+        f"\n"
+        f"*This is the agent guide bundled with the openarmature Python package, "
+        f"version {version} (spec {spec_tag}). For the full docs site see "
+        f"[openarmature.ai](https://openarmature.ai). For the canonical spec text see "
+        f"[openarmature.ai/capabilities](https://openarmature.ai/capabilities/). "
+        f"For project-specific conventions for the code you're editing, see the host "
+        f"project's `AGENTS.md` or `CLAUDE.md`.*"
+    )
+
+
+def _tldr() -> str:
+    body = (DOCS / "agent" / "tldr.md").read_text().strip()
+    return f"## TL;DR\n\n{body}"
+
+
+def _extract_sections_1_2(spec_text: str) -> str:
+    """Extract content between ``## 1.`` and ``## 3.`` (inclusive of §1+§2)."""
+    out: list[str] = []
+    in_target = False
+    for line in spec_text.splitlines():
+        if line.startswith("## 1."):
+            in_target = True
+        elif line.startswith("## 3."):
+            break
+        if in_target:
+            out.append(line)
+    if not out:
+        raise RuntimeError(
+            "spec heading-extraction failed: no `## 1.` heading found. "
+            "Spec capability may have renumbered; revisit the build script."
+        )
+    return "\n".join(out).rstrip()
+
+
+def _capability_summaries(spec_tag: str) -> str:
+    sections = [
+        "## Capability contracts",
+        "",
+        f"_Sourced from openarmature-spec {spec_tag}. Each entry below "
+        f"reproduces §1 (Purpose) and §2 (Concepts) of the capability's "
+        f"`spec.md`. For the full spec text (execution model, error semantics, "
+        f"determinism, observer hooks, etc.) see the linked docs site._",
+    ]
+    for cap in CAPABILITIES:
+        text = _read_pinned_spec(f"spec/{cap}/spec.md")
+        sections.append("")
+        sections.append(f"### Capability: `{cap}`")
+        sections.append("")
+        sections.append(_extract_sections_1_2(text))
+    return "\n".join(sections)
+
+
+def _patterns() -> str:
+    sections = [
+        "## Patterns",
+        "",
+        "_Recipes that compose the primitives. Not framework contracts — "
+        "these are how to do common things idiomatically._",
+    ]
+    pattern_files = sorted(p for p in (DOCS / "patterns").glob("*.md") if p.name != "index.md")
+    for pf in pattern_files:
+        sections.append("")
+        sections.append(pf.read_text().rstrip())
+    return "\n".join(sections)
+
+
+def _non_obvious_shapes() -> str:
+    # The file's own top-level heading is `## Non-obvious shapes`;
+    # inlined verbatim with the heading intact.
+    return (DOCS / "agent" / "non-obvious-shapes.md").read_text().rstrip()
+
+
+def _extract_first_docstring_paragraph(source: str) -> str:
+    """Extract the first paragraph of a Python module docstring.
+
+    Module docstrings open with a triple-quoted string at line 0.
+    The first "paragraph" is the text from the opening quotes to
+    the first blank line within the docstring (or to the closing
+    quotes if the docstring is one paragraph).
+    """
+    lines = source.splitlines()
+    if not lines or not lines[0].startswith('"""'):
+        return ""
+    # First line after the opening triple-quote
+    first_text = lines[0][3:].rstrip()
+    if first_text.endswith('"""'):
+        return first_text[:-3].rstrip()
+    para = [first_text] if first_text else []
+    for line in lines[1:]:
+        stripped = line.strip()
+        if stripped == "" or stripped.startswith('"""') or stripped.endswith('"""'):
+            break
+        para.append(stripped)
+    return " ".join(p for p in para if p)
+
+
+def _example_index() -> str:
+    sections = [
+        "## Example index",
+        "",
+        "_Runnable example programs shipped in the source tree at `examples/`. "
+        "The full code is not bundled here (each example is 300+ lines); read "
+        "the file at the listed path to see the canonical shape for that use case._",
+        "",
+    ]
+    for ex in sorted(EXAMPLES.glob("*/main.py")):
+        first_paragraph = _extract_first_docstring_paragraph(ex.read_text())
+        rel = ex.relative_to(REPO_ROOT)
+        sections.append(f"- **`{rel}`** — {first_paragraph}")
+    return "\n".join(sections)
+
+
+def _discovery_footer() -> str:
+    return (
+        "## Discovery cross-references\n"
+        "\n"
+        "If your question isn't covered above, look here:\n"
+        "\n"
+        "- **Full docs site:** [openarmature.ai](https://openarmature.ai)\n"
+        "- **Spec text:** [openarmature.ai/capabilities](https://openarmature.ai/capabilities/)\n"
+        "- **API reference:** [openarmature.ai/reference](https://openarmature.ai/reference/)\n"
+        "- **Host project conventions:** the project's own `AGENTS.md` / `CLAUDE.md`\n"
+    )
+
+
+def build() -> str:
+    spec_tag = _assert_pin_at_tag()
+    version = openarmature.__version__
+    sections = [
+        _header(version, spec_tag),
+        _tldr(),
+        _capability_summaries(spec_tag),
+        _patterns(),
+        _non_obvious_shapes(),
+        _example_index(),
+        _discovery_footer(),
+    ]
+    return "\n\n".join(sections) + "\n"
+
+
+def main() -> None:
+    content = build()
+    OUTPUT.write_text(content)
+    line_count = content.count("\n")
+    byte_count = len(content.encode("utf-8"))
+    print(f"wrote {OUTPUT.relative_to(REPO_ROOT)}: {line_count} lines, {byte_count:,} bytes")
+
+
+if __name__ == "__main__":
+    main()