Rename examples and reorder catalog by topic

[chris-colinsky]

Summary

Drops the NN- numeric prefix from all 13 example directories and walk-through docs. Regroups the catalog at docs/examples/index.md and the mkdocs nav into seven topical sections (Foundations / Composition / Concurrency / Prompts / Tool use / Reliability / Observability). The numbers were never load-bearing; they implied a strict reading order the catalog never actually needed.

Cross-references between examples are rewritten by-name ("the observer-hooks example", "the fan-out-with-retry example"); no more "Example NN" references in docs, walk-throughs, example sources, READMEs, or CHANGELOG. Walk-through H1s drop the prefix; "Run with:" docstring blocks updated to the new paths.

examples/README.md brought up to date with the post-v0.11.0 catalog under the same topical grouping (entries for chat-with-multimodal, langfuse-observability, production-observability were missing). tests/test_examples_smoke.py's DEMOS list switches to flat names; pytest parametrize IDs follow automatically.

Folds in the em-dash sweep across example source files and examples/README.md to match the convention established in the v0.11.0-cycle docs sweep.

Includes nav CSS polish for the new nested sub-section groups: hides the redundant tab label inside the sidebar, adds a vertical guide line on sub-sections with children (via ::before pseudo-element on the level-2 nav, bottom-stopped 5px short of the nav's lower edge), and aligns sub-section labels horizontally across all three tabs (Documentation / Examples / Patterns) by overriding padding on label-form and direct-link-form .md-nav__link items to match Documentation's <div class="md-nav__container"> layered offset. Also adds a Python-version shield to the docs homepage mirroring the README's shield.

Test plan

• uv run pytest tests/test_examples_smoke.py green (13/13 demos)
• uv run mkdocs build --strict clean (no broken intra-docs links)
• uv run ruff check examples/ tests/ docs/ clean
• uv run pyright examples/ clean
• Zero em dashes in example sources and examples/README.md
• No stale examples/NN-name references in tracked files (only one historical CHANGELOG entry intentionally left as a record of what shipped under those names)
• Nav sidebar visually verified across Documentation / Examples / Patterns tabs via headless Chromium captures, with all sub-section / top-level page text aligned at the same X column

[Copilot]

Pull request overview

This PR removes numeric prefixes from all example directories and example docs, and reorganizes the Examples catalog + MkDocs navigation into topic-based groups, updating cross-references throughout the docs and source tree accordingly. It also applies a punctuation sweep in example sources/README to remove em dashes and includes CSS updates to improve sidebar alignment and subsection rendering.

Changes:

• Renamed example folders/docs from NN-name to name and updated all internal/external references.
• Reorganized docs/examples/index.md and mkdocs.yml Examples nav into seven topical sections.
• Updated examples README/tests and applied docs/CSS polish (sidebar alignment, subsection guide line, docs homepage Python badge).

Reviewed changes

Copilot reviewed 44 out of 48 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/test_examples_smoke.py	Updates demo directory names used by the smoke test.
src/openarmature/AGENTS.md	Updates example links/paths and example list to new names/order.
src/openarmature/_patterns/tool-dispatch-as-node.md	Updates example link to renamed tool-use example.
src/openarmature/_patterns/session-as-checkpoint-resume.md	Updates example link to renamed checkpointing example.
src/openarmature/_patterns/caller-supplied-trace-identifiers.md	Updates example link to renamed langfuse example.
RELEASING.md	Updates the “quickest example” path to renamed hello-world.
README.md	Updates example path reference to renamed hello-world.
mkdocs.yml	Reworks Examples nav into topical subsections and updates paths.
examples/tool-use/main.py	Updates run instructions and replaces em dashes with other punctuation.
examples/routing-and-subgraphs/main.py	Updates run instructions and replaces em dashes with other punctuation.
examples/README.md	Rewrites examples catalog by topic and updates paths/cross-references.
examples/production-observability/main.py	Updates example cross-references and run path.
examples/parallel-branches/main.py	Updates cross-references and run path; punctuation sweep.
examples/observer-hooks/main.py	Updates run path and punctuation sweep in doc/comments.
examples/nested-subgraphs/main.py	Updates run path; replaces em dash in output placeholder.
examples/multimodal-prompt/prompts/production/describe-surface.j2	Adds/updates production prompt template content.
examples/multimodal-prompt/prompts/production/describe-equipment.j2	Adds/updates production prompt template content.
examples/multimodal-prompt/prompts_fallback/production/describe-surface.j2	Adds fallback prompt template content.
examples/multimodal-prompt/prompts_fallback/production/describe-equipment.j2	Adds fallback prompt template content.
examples/multimodal-prompt/main.py	Updates run path and punctuation sweep.
examples/langfuse-observability/main.py	Updates run path and punctuation sweep.
examples/hello-world/main.py	Updates run path and punctuation sweep.
examples/fan-out-with-retry/main.py	Updates run path, cross-references, and punctuation sweep.
examples/explicit-subgraph-mapping/main.py	Updates run path and punctuation sweep.
examples/checkpointing-and-migration/main.py	Updates run path.
examples/chat-with-multimodal/main.py	Updates cross-references and run paths.
docs/stylesheets/extra.css	Adds sidebar/tab label hiding, subsection alignment tweaks, and guide line styling.
docs/patterns/tool-dispatch-as-node.md	Updates example doc link to renamed tool-use page.
docs/patterns/session-as-checkpoint-resume.md	Updates example doc link to renamed checkpointing page.
docs/patterns/caller-supplied-trace-identifiers.md	Updates example doc link to renamed langfuse page.
docs/index.md	Adds Python-version shield matching README.
docs/examples/tool-use.md	Removes numeric prefix from H1; updates run path.
docs/examples/routing-and-subgraphs.md	Removes numeric prefix from H1; updates run path.
docs/examples/production-observability.md	Removes numeric prefix from H1; updates run path and references.
docs/examples/parallel-branches.md	Removes numeric prefix from H1; updates run path and wording.
docs/examples/observer-hooks.md	Removes numeric prefix from H1; updates run path.
docs/examples/nested-subgraphs.md	Removes numeric prefix from H1; updates run path.
docs/examples/multimodal-prompt.md	Removes numeric prefix from H1; updates run path.
docs/examples/langfuse-observability.md	Removes numeric prefix from H1; updates run path.
docs/examples/index.md	Rewrites examples catalog into topic-based groups and updates paths.
docs/examples/hello-world.md	Removes numeric prefix from H1; updates run path.
docs/examples/fan-out-with-retry.md	Removes numeric prefix from H1; updates run paths.
docs/examples/explicit-subgraph-mapping.md	Removes numeric prefix from H1; updates run path and references.
docs/examples/checkpointing-and-migration.md	Removes numeric prefix from H1; updates run path.
docs/examples/chat-with-multimodal.md	Removes numeric prefix from H1; updates run paths and cross-references.
docs/concepts/observability.md	Updates langfuse example link to renamed page.
docs/concepts/llms.md	Updates example link targets; some link text still includes numeric prefixes.
CHANGELOG.md	Updates changelog entries to renamed examples and new catalog organization.

Comments suppressed due to low confidence (4)

examples/routing-and-subgraphs/main.py:373

• The QuestionProjection docstring formatting is broken: the second paragraph has inconsistent indentation and a stray standalone ; line, which will render poorly and is confusing to readers.
  examples/tool-use/main.py:10
• This sentence now uses a semicolon before “so”, which is grammatically incorrect and reads awkwardly in the module docstring.
  examples/parallel-branches/main.py:10
• The punctuation here produces an ungrammatical “either); which is …” construction. This should be a comma (or period) rather than a close-paren + semicolon.
  examples/observer-hooks/main.py:332
• The bullet list comment has an accidental standalone ; prefix, which reads like a formatting artifact and makes the instruction unclear.

---

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