docs(site): UX, nav, and reference cleanup

docs/index.md

@@ -1,6 +1,5 @@
 ---
 hide:
-  - navigation
   - toc
 ---
 
@@ -65,7 +64,11 @@ buy-in from every node.
 
 ---
 
-Built around an open, language-agnostic
-[specification](https://github.com/LunarCommand/openarmature-spec){target="_blank" rel="noopener"}.
-A TypeScript implementation is on the roadmap; behaviour stays
-identical across implementations via spec conformance fixtures.
+## Open specification
+
+OpenArmature is defined by a public, language-agnostic specification,
+not a Python-shaped opinion exported to other languages. Reference
+implementations share conformance fixtures, so behavior stays identical
+across languages, runtimes, and tooling stacks.
+
+[Read the spec →](https://openarmature.org){target="_blank" rel="noopener"}

docs/overrides/partials/header.html

@@ -0,0 +1,103 @@
+{#-
+  Local override of material/partials/header.html.
+
+  Local modifications vs. the upstream partial:
+
+  1. The site-name topic in ``.md-header__title`` is rendered as an
+     ``<a>`` (carrying the ``md-header__topic`` class) so the visible
+     "OpenArmature" wordmark navigates home. Upstream's default leaves
+     that topic as a plain ``<div>``; the only header-area link is the
+     icon-style ``md-logo`` button, which our extra.css hides because
+     we want the wordmark on its own.
+  2. On the homepage (``page.is_homepage``), the ``.md-header__title``
+     element gets an extra ``md-header__title--pinned`` class and the
+     second ``.md-header__topic`` (the page-title topic) is not
+     rendered. A paired rule in extra.css pins the wordmark in place
+     regardless of ``data-md-state="topic"`` so the scroll animation
+     doesn't fire; we omit the page-title topic because on the
+     homepage it would just be an un-bold copy of "OpenArmature".
+
+  Re-sync this file when bumping mkdocs-material; preserve both
+  modifications. Everything below is otherwise verbatim from the
+  upstream partial.
+-#}
+{% set class = "md-header" %}
+{% if "navigation.tabs.sticky" in features %}
+  {% set class = class ~ " md-header--shadow md-header--lifted" %}
+{% elif "navigation.tabs" not in features %}
+  {% set class = class ~ " md-header--shadow" %}
+{% endif %}
+<header class="{{ class }}" data-md-component="header">
+  <nav class="md-header__inner md-grid" aria-label="{{ lang.t('header') }}">
+    <a href="{{ config.extra.homepage | d(nav.homepage.url, true) | url }}" title="{{ config.site_name | e }}" class="md-header__button md-logo" aria-label="{{ config.site_name }}" data-md-component="logo">
+      {% include "partials/logo.html" %}
+    </a>
+    <label class="md-header__button md-icon" for="__drawer">
+      {% set icon = config.theme.icon.menu or "material/menu" %}
+      {% include ".icons/" ~ icon ~ ".svg" %}
+    </label>
+    {#- LOCAL OVERRIDE: pin the wordmark on the homepage. The page title
+        there is also "OpenArmature", so Material's default scroll
+        animation flips between the bold wordmark and the un-bold page
+        title of the same text, which reads as a glitch. On the
+        homepage we tag the title element so extra.css can suppress the
+        swap, and we skip rendering the page-title topic entirely. -#}
+    <div class="md-header__title{% if page.is_homepage %} md-header__title--pinned{% endif %}" data-md-component="header-title">
+      <div class="md-header__ellipsis">
+        {# LOCAL OVERRIDE: render the site-name topic as an <a> so the
+           wordmark is clickable. Material's default markup is a plain
+           <div class="md-header__topic">; we substitute an anchor that
+           carries the same .md-header__topic class so the theme's
+           positioning rules (which target direct children of
+           .md-header__ellipsis) still apply. #}
+        <a href="{{ config.extra.homepage | d(nav.homepage.url, true) | url }}" class="md-header__topic md-header__topic-link" aria-label="{{ config.site_name }}">
+          <span class="md-ellipsis">
+            {{ config.site_name }}
+          </span>
+        </a>
+        {% if not page.is_homepage %}
+        <div class="md-header__topic" data-md-component="header-topic">
+          <span class="md-ellipsis">
+            {% if page.meta and page.meta.title %}
+              {{ page.meta.title }}
+            {% else %}
+              {{ page.title }}
+            {% endif %}
+          </span>
+        </div>
+        {% endif %}
+      </div>
+    </div>
+    {% if config.theme.palette %}
+      {% if not config.theme.palette is mapping %}
+        {% include "partials/palette.html" %}
+      {% endif %}
+    {% endif %}
+    {% if not config.theme.palette is mapping %}
+      {% include "partials/javascripts/palette.html" %}
+    {% endif %}
+    {% if config.extra.alternate %}
+      {% include "partials/alternate.html" %}
+    {% endif %}
+    {% if "material/search" in config.plugins %}
+      {% set search = config.plugins["material/search"] | attr("config") %}
+      {% if search.enabled %}
+        <label class="md-header__button md-icon" for="__search">
+          {% set icon = config.theme.icon.search or "material/magnify" %}
+          {% include ".icons/" ~ icon ~ ".svg" %}
+        </label>
+        {% include "partials/search.html" %}
+      {% endif %}
+    {% endif %}
+    {% if config.repo_url %}
+      <div class="md-header__source">
+        {% include "partials/source.html" %}
+      </div>
+    {% endif %}
+  </nav>
+  {% if "navigation.tabs.sticky" in features %}
+    {% if "navigation.tabs" in features %}
+      {% include "partials/tabs.html" %}
+    {% endif %}
+  {% endif %}
+</header>

docs/reference/index.md

@@ -3,13 +3,16 @@
 Auto-generated from docstrings. Pick a subpackage:
 
 - [`openarmature.graph`](graph.md): state, builder, edges, nodes,
-  projections, fan-out, middleware, observer, reducers, errors.
+  projections, fan-out, parallel branches, middleware, observer,
+  reducers, errors.
 - [`openarmature.llm`](llm.md): Provider Protocol, message + tool
-  types, the OpenAIProvider, shared error helpers.
+  types, multimodal content blocks, structured output, the
+  OpenAIProvider, shared error helpers.
+- [`openarmature.prompts`](prompts.md): PromptManager, PromptBackend
+  Protocol, FilesystemPromptBackend, PromptGroup, prompt
+  observability propagation.
 - [`openarmature.checkpoint`](checkpoint.md): Checkpointer Protocol,
-  CheckpointRecord, in-memory + SQLite backends.
+  CheckpointRecord, in-memory + SQLite backends, state-migration
+  registry.
 - [`openarmature.observability`](observability.md): correlation
   primitives and the optional OTel mapping (`[otel]` extra).
-
-Public surface is what each subpackage's `__init__.py` re-exports. Symbols
-prefixed with `_` are package-private and not shown here.

docs/stylesheets/extra.css

@@ -157,13 +157,39 @@
   color: #cd8bf4;
 }
 
-/* Hide the default Material book-icon logo next to the site name; the
- * "OpenArmature" wordmark stands on its own and already links to the
- * site root. */
+/* Hide the default Material book-icon logo next to the site name. The
+ * "OpenArmature" wordmark itself is made clickable by the local
+ * ``docs/overrides/partials/header.html`` override, which wraps the
+ * site-name topic in an ``<a>`` pointing at the site root. */
 .md-header__button.md-logo {
   display: none;
 }
 
+/* Inherit header text colors on the wordmark anchor introduced by the
+ * partial override, so it reads as the wordmark rather than a styled
+ * link. */
+.md-header__topic-link,
+.md-header__topic-link:hover,
+.md-header__topic-link:focus,
+.md-header__topic-link:visited {
+  color: inherit;
+  text-decoration: none;
+}
+
+/* Suppress the wordmark/page-title scroll animation on the homepage.
+ * The homepage's page title is also "OpenArmature", so Material's
+ * default swap flips between the bold wordmark and the un-bold
+ * page-title of the same text — reads as a render glitch. The
+ * ``--pinned`` modifier is added by the partial override when
+ * ``page.is_homepage`` is true, and we don't render the second topic
+ * at all in that case; this rule keeps the wordmark visible regardless
+ * of the ``data-md-state="topic"`` toggle Material adds on scroll. */
+.md-header__title--pinned .md-header__topic {
+  opacity: 1;
+  pointer-events: auto;
+  transform: none;
+}
+
 /* Hide Material's auto-generated site-name header at the top of the
  * primary sidebar — we have an explicit ``OpenArmature: index.md``
  * entry in the nav config which serves as the home link. */

mkdocs.yml

@@ -9,6 +9,11 @@ dev_addr: "127.0.0.1:8765"
 
 theme:
   name: material
+  # Override directory for theme partials. ``docs/overrides/`` carries
+  # the customized ``partials/header.html`` that makes the
+  # "OpenArmature" wordmark clickable (Material's default leaves it
+  # as a plain ``<div>``).
+  custom_dir: docs/overrides
   palette:
     - media: "(prefers-color-scheme: light)"
       scheme: default
@@ -94,6 +99,7 @@ nav:
     - Graphs: concepts/graphs.md
     - Composition: concepts/composition.md
     - Fan-out: concepts/fan-out.md
+    - Parallel branches: concepts/parallel-branches.md
     - LLMs: concepts/llms.md
     - Prompts: concepts/prompts.md
     - Observability: concepts/observability.md