chore(examples): scrub, standardize, reframe 04

[chris-colinsky]

Summary

First wave of the Examples Review phase. Cleans the existing example set so all surviving demos use the recommended provider API and read as use-case driven recipes rather than tech demos. Sets the stage for the new examples (fan-out, parallel-branches, multimodal-prompt, checkpointing-and-migration) that follow in subsequent PRs.

What's in the wave

Change	Files
Delete `01-linear-pipeline/`	Covered by `00-hello-world/` (LLM + structured output + reducers + routing + observer in one demo).
Renumber 02-05 down by one	`02-routing-and-subgraphs` → 01, `03-explicit-subgraph-mapping` → 02, `04-observer-hooks` → 03, `05-nested-subgraphs` → 04.
Standardize 01-03 on `OpenAIProvider`	Drop direct `AsyncOpenAI` + `client.chat.completions.create()`; route through `openarmature.llm.OpenAIProvider` with `SystemMessage` + `UserMessage`. Lift hardcoded `VLLM_BASE_URL` to `LLM_BASE_URL` / `LLM_MODEL` / `LLM_API_KEY` env vars, matching `00-hello-world`.
Reframe `03-observer-hooks` to include OTel	Register `OTelObserver` (`ConsoleSpanExporter`) alongside the existing plain `console_tracer`. Same hook, different backend: shows observability backends are pluggable behind one uniform protocol.
Reframe `04-nested-subgraphs` around a real use case	Was framed as "depth invariants tech demo with trivial integer updates so the output is short." Now: question answering against a tiny baked-in 3-document corpus. Outer coordinator delegates to a doc-QA subgraph that itself delegates to a section-extract subgraph. Two levels of nesting fall out of the use case naturally. Depth-aware observer still prints the descent and return, but as a side observation rather than the headline.
Strip spec/proposal references from `examples/`	No more "spec §X", "proposal NNNN", "graph-engine §" etc. in comments or docstrings. Internal `src/` scope unchanged. Pedagogical surface stays focused on what the code does and what the reader gets out of understanding it.
Refresh `examples/README.md`	Re-numbered table, new "Configuration" section covering the env vars, OTel note on demo 03.
Update `tests/test_examples_smoke.py`	Parametrize list trimmed to the five surviving demos.

Test plan

• `uv run pytest tests/` — 692 pass, 56 skipped, 0 fail.
• `uv run pyright` — clean.
• `uv run ruff check` + `uv run ruff format --check` — clean.
• Manual: all five demos run end-to-end against a real LLM endpoint with `LLM_API_KEY` set. (Validated by @chris-colinsky on the branch.)

What's next in the phase

This PR is the scrub. Subsequent PRs add the new examples one at a time:

1. `05-fan-out-with-retry` (Fan-out + RetryMiddleware + TimingMiddleware)
2. `06-parallel-branches` (M-way dispatch + branch middleware)
3. `07-multimodal-prompt` (PromptManager + FilesystemPromptBackend + ImageBlock)
4. `08-checkpointing-and-migration` (SQLite checkpointer + State.schema_version + MigrationRegistry)

After 08 merges, every major v0.6.0 surface has a home in `examples/`.

[Copilot]

Pull request overview

This PR performs the first “examples scrub” pass: removing redundant demos, renumbering the remaining set, standardizing examples on openarmature.llm.OpenAIProvider, and reframing demos as use-case recipes (including adding an OpenTelemetry observer demo).

Changes:

• Delete 01-linear-pipeline/ and renumber the remaining demos (02–05 → 01–04), updating the smoke test list accordingly.
• Standardize examples on OpenAIProvider + SystemMessage/UserMessage and shared env var configuration (LLM_BASE_URL, LLM_MODEL, LLM_API_KEY).
• Rework 03-observer-hooks to demonstrate pluggable observability backends via OTelObserver, and reframe nested subgraphs as a doc-QA use case.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/test_examples_smoke.py	Updates the demo list to the renamed/renumbered examples.
examples/README.md	Renumbers demos, adds unified configuration section, updates run instructions and OTel note.
examples/01-routing-and-subgraphs/main.py	Migrates to OpenAIProvider, updates docs/config, adds cleanup (drain() / provider close).
examples/02-explicit-subgraph-mapping/main.py	Migrates to OpenAIProvider, updates docs/config, adds cleanup (drain() / provider close).
examples/03-observer-hooks/main.py	Migrates to OpenAIProvider, adds OTelObserver example, updates docs/config, adds provider cleanup.
examples/04-nested-subgraphs/main.py	New doc-QA nested subgraphs demo using OpenAIProvider and a depth-aware observer.
examples/01-linear-pipeline/main.py	Deleted (superseded by 00-hello-world).
examples/05-nested-subgraphs/main.py	Deleted (replaced by reframed 04-nested-subgraphs).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.