feat(site): consolidate UX review into shared design-system foundations

.github/workflows/tests.yml

@@ -94,6 +94,8 @@ jobs:
 
       - run: npm run build
 
+      - run: node --experimental-strip-types --test src/data/navigation.test.mjs
+
       - run: npm run check:presentations
 
       - run: node --experimental-strip-types --test src/data/mind-nervous-system-body-slides.test.mjs

CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/). This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.19.0] - 2026-07-26
+
+### Added
+
+- Reusable Astro design-system foundations: named layout and typography roles plus shared section-intro, destination-card, structured-card, closing-band, and terminal patterns.
+- A guided three-session Devague capture story with accessible transcript evidence, human-gate previews, and a reshaped pipeline reference.
+- Focused regression coverage for navigation and presentations, with Devague story anchors validated when the site builds.
+
+### Changed
+
+- Unified the site header, primary navigation, grouped footer, agent directory, and library destinations, including a sticky header and clearer internal and external link treatments.
+- Migrated the four agent profiles and current library, article, and presentation surfaces onto reusable patterns while preserving their bespoke compositions.
+- Consolidated the UX review into current spec, plan, and delivery records; removed generated review snapshots and superseded decision material; automatic future-page adoption remains deferred.
+
+### Fixed
+
+- Improved diagram spacing, agent-page code and terminal treatments, destination clarity, and presentation contract coverage across responsive layouts.
+
 ## [0.18.2] - 2026-07-22
 
 ### Changed

README.md

@@ -56,6 +56,13 @@ provisioned Cloudflare state and the DNS cutover procedure are recorded in
 [`docs/deploy-runbook.md`](docs/deploy-runbook.md). DNS for AgentCulture.org
 is operator-owned, so cutover is coordinated, not self-serve.
 
+The adopted navigation, design-system, agent-page, and Devague decisions are
+summarized in the
+[`site-ux-review` delivery record](docs/deliveries/2026-07-21-site-ux-review.md).
+Use that record and the implementation as the current source of truth; the
+Astro build plus focused navigation and presentation tests provide regression
+coverage.
+
 Two things worth knowing if you're extending it: the sibling repos'
 `publish.yml` are all **PyPI** workflows, not deploy templates — this repo's
 deploy workflow was written fresh, in the filename slot the removed

docs/deliveries/2026-07-21-site-ux-review.md

@@ -0,0 +1,69 @@
+# Delivery Summary — site-ux-review
+
+plan: `site-ux-review` · run: `complete` · date: `2026-07-26` · draft PR:
+[#30](https://github.com/agentculture/org/pull/30)
+
+## Intent
+
+Turn a measured review of the original site into reusable foundations
+for the current twelve-route Astro build. Preserve the site's visual identity
+and bespoke page compositions while making navigation, wayfinding, destination
+cues, long-form openings, information cards, terminal treatments, and Devague
+evidence easier to understand and maintain.
+
+## Actual Delivery
+
+| Plan task | Status | What landed |
+|---|---|---|
+| `t1` shared system | delivered | Named type, leading, tracking, rail, measure, diagram-spacing, and sticky-header roles with explicit container ownership. |
+| `t2` navigation and destinations | delivered | Typed grouped header, grouped sitemap footer, stable agent groups, capped Library features, external Learn product, whole-card destinations, and safe external cues. |
+| `t3` agent-page patterns | delivered | Shared `SectionIntro`, `StructuredCard`, `DestinationCard`, `ClosingBand`, and inline-code treatments; aligned terminal and diagram rules; bespoke compositions retained. |
+| `t4` Devague | delivered | Three guided sessions, fourteen source-anchored excerpts, accessible full transcripts, read-only gate previews, repaired flow sequence, and a ruled seven-stage pipeline reference. |
+| `t5` reconciliation | delivered | Breadcrumbs/local navigation experiments removed, focused navigation and presentation coverage retained, version advanced to `0.19.0`, and review artifacts consolidated into this record set. |
+
+## Final Decisions
+
+| Direction | Final status | Reason |
+|---|---|---|
+| Typed grouped navigation and sitemap footer | adopted | Keeps route ownership, current states, featured coverage, and Learn's external ownership explicit. |
+| Whole-card destination links with visible kind | adopted | Resolves the directory's target-size and destination-ambiguity findings together. |
+| Shared semantic components | adopted | Reduces repeated presentation decisions without forcing unrelated content into one visual primitive. |
+| Guided Devague sessions and transcript modal | adopted | Teaches the evidence while preserving complete, verbatim captures. |
+| Ruled pipeline reference list | adopted | Keeps the animated flow primary and makes the stage detail quieter lookup material. |
+| Directory filter and sticky jump list | superseded | Stable group fragments and grouped navigation provide the accepted wayfinding without another control surface. |
+| Generic `AgentPage` and `Terminal` components | deferred | The four pages share design rules but still have meaningfully different structures and terminal contracts. |
+| Breadcrumbs and local contents navigation | deferred | They were removed from this PR pending a separate information-architecture decision. |
+| Automatic adoption by future pages | deferred | New pages must choose semantic components deliberately. |
+| Generated review pages and static snapshots | retired | Source and these records now contain the accepted decisions. |
+
+## Evidence
+
+- Astro production build: twelve static routes
+- navigation: six focused behavior tests
+- delivered inventory: 28 authored section-introduction calls render 35
+  openings; 12 structured-card calls render 70 cards
+- Devague build input: three sessions and fourteen source-anchored excerpts
+- presentations: 23 built-page checks and 20 slide-data tests
+- Python test, coverage, formatting, lint, security, Markdown, local-link, and
+  strict repository-doctor lanes pass on the final branch
+
+## Source of Truth
+
+The implementation is authoritative for current behavior. The Astro build,
+focused navigation tests, and retained presentation tests cover durable
+regressions; this delivery records the final PR state. The matching
+[spec](../specs/2026-07-21-site-ux-review.md) preserves accepted requirements,
+and the [plan](../plans/2026-07-21-site-ux-review.md) preserves the delivery
+sequence.
+
+Focused records cover the shared
+[section introduction](2026-07-23-global-section-opener.md) and
+[structured card](2026-07-23-global-structured-card.md) patterns.
+
+## Remaining Work
+
+- complete manual visual and keyboard review on the draft deploy preview
+- decide breadcrumbs/local contents navigation separately
+- consider broader agent-page or terminal abstraction only when another page
+  provides enough evidence for a stable interface
+- keep Learn source and deployment in its owning project

docs/deliveries/2026-07-23-global-section-opener.md

@@ -0,0 +1,45 @@
+# Delivery Summary — global-section-opener
+
+plan: `global-section-opener` · run: `complete` · date: `2026-07-26` · draft
+PR: [#30](https://github.com/agentculture/org/pull/30)
+
+## Intent
+
+Give long-form sections one accessible, readable opening grammar while
+preserving the article's definitions and every page's bespoke downstream
+composition.
+
+## Actual Delivery
+
+| Plan task | Status | What landed |
+|---|---|---|
+| `t1` shared component | delivered | `SectionIntro.astro` owns eyebrow, stable heading, optional post-title content, readable measures, title spacing, and reveal behavior. |
+| `t2` agent profiles | delivered | Devague 6, Colleague 9, Lobes 5, and Reachy Mini CLI 7 authored calls; parent sections use matching `aria-labelledby` IDs. |
+| `t3` article | delivered | One loop-authored call renders eight beat openings while definitions, lede styling, paragraph reveals, and evidence notes remain local. |
+| `t4` validation | delivered | The production build and focused semantic/visual review covered ordering, measures, accessible labels, reveal behavior, and the presentation exclusion. |
+
+## Final Decisions
+
+- Agent sections use grouped introductory reveals; the article retains
+  paragraph-level reveals.
+- The article's definitions use the named `after-title` slot rather than moving
+  into the shared component's data model.
+- Agent headings use standard title spacing; the article keeps its relaxed
+  variant.
+- Explicit template branches prevent absent reveal flags from becoming literal
+  false-valued data attributes.
+- The presentation remains a separate slide pattern.
+
+## Evidence
+
+- delivery snapshot: 28 authored component calls render 35 section openings
+- all five migrated routes retain stable heading IDs and labelled parent regions
+- article heading → definitions → prose order is preserved in built output
+- the seven-slide presentation renders no shared section-introduction markers
+- the Astro production build passes
+
+## Boundaries
+
+- no copy, section order, route, breadcrumb, local-navigation, Learn, or
+  deployment change belongs to this component
+- future pages must opt into the component deliberately

docs/deliveries/2026-07-23-global-structured-card.md

@@ -0,0 +1,48 @@
+# Delivery Summary — global-structured-card
+
+plan: `global-structured-card` · run: `complete` · date: `2026-07-26` · draft
+PR: [#30](https://github.com/agentculture/org/pull/30)
+
+## Intent
+
+Give matching agent-profile information cards one hierarchy and responsive grid
+without turning every rectangular surface into the same component.
+
+## Actual Delivery
+
+| Plan task | Status | What landed |
+|---|---|---|
+| `t1` shared component | delivered | `StructuredCard.astro` owns optional metadata/footer, serif title, 16px body, featured span, reveal delay, and the responsive grid. |
+| `t2` Devague | delivered | Method moves and operator skills use 2 authored calls for 14 cards; command titles retain code semantics. |
+| `t3` Colleague | delivered | Five families use 5 authored calls for 25 cards; metadata and compact command footers retain their meaning. |
+| `t4` Reachy and Lobes | delivered | Four Reachy families and one Lobes family use 5 authored calls for 31 cards. |
+| `t5` validation | delivered | The production build and focused semantic/responsive review covered ordering, command treatment, absent copy controls, and explicit exclusions. |
+
+## Final Decisions
+
+- Shared treatment is based on the metadata/title/body/footer information model,
+  not visual similarity alone.
+- Command titles remain selectable semantic code and do not become buttons.
+- The Devague pipeline initially matched the card family, then moved to a ruled
+  reference list so the animated flow remained the section's visual
+  protagonist. Its seven rows are therefore excluded from the delivery
+  snapshot.
+- Directory/library links, article evidence, terminals, tables, measured
+  statistics, gate previews, closing bands, and presentation cards stay local.
+
+## Evidence
+
+- delivery snapshot: 12 authored component calls render 70 cards across four
+  agent profiles
+- route counts are Devague 14, Colleague 25, Reachy Mini CLI 25, and Lobes 6
+- built cards preserve metadata → title → body → footer order
+- shared grids contain three-column desktop, two-column intermediate, and
+  one-column narrow rules
+- excluded routes render no structured-card markers
+- the Astro production build passes
+
+## Boundaries
+
+- no card adds clipboard behavior or a copy control
+- future card families must match the semantic contract before adopting the
+  component

docs/plans/2026-07-21-site-ux-review.md

@@ -0,0 +1,75 @@
+# Build Plan — site-ux-review
+
+slug: `site-ux-review` · status: `delivered in draft PR #30`
+
+> Convert the accepted UX-review findings into named shared patterns, migrate
+> the current site, and leave a concise record of final decisions.
+
+## Tasks
+
+### t1 — Establish the shared system and containment rules
+
+- add named typography, leading, tracking, rail, measure, diagram-spacing, and
+  sticky-header roles to the global stylesheet
+- assign every authored container an explicit rail without changing the
+  presentation deck's independent content width
+- review token use, rail ownership, terminal legibility, diagram spacing, gate
+  previews, and the sticky header across representative pages
+- acceptance: the production build succeeds for twelve routes and manual review
+  confirms the shared roles without flattening page-specific layouts
+
+### t2 — Unify navigation, wayfinding, and destinations
+
+- centralize header and footer navigation data, including grouped Agents and
+  Library menus and the external Learn product
+- make agent-directory groups stable destinations and use whole-card links with
+  explicit destination labels
+- apply the shared destination-card and external-link behaviors to matching
+  surfaces
+- acceptance: focused navigation tests cover route ownership, grouped
+  destinations, footer derivation, and safe new-tab behavior; all links pass the
+  built-site link check
+
+### t3 — Extract proven agent-page patterns
+
+- add shared section-introduction, structured-card, closing-band, and inline-code
+  components
+- migrate only the page families that match each semantic pattern
+- align terminal legibility and diagram spacing while retaining the four
+  agent-specific terminal and diagram implementations
+- acceptance: source review confirms repeated markup moved into shared
+  components while other card families and the presentation deck remain local
+
+### t4 — Complete the Devague story and pipeline
+
+- model three guided capture sessions and resolve every excerpt from the
+  immutable capture source
+- add session, story-beat, transcript-modal, and read-only human-gate preview
+  treatments
+- repair the flow sequence and replace the competing stage-card grid with a
+  ruled seven-row reference list
+- acceptance: the Astro build resolves every story anchor, transcripts remain
+  complete and keyboard accessible, and the pipeline reference remains separate
+  from structured cards
+
+### t5 — Reconcile the final branch
+
+- remove experiments that did not survive review, including breadcrumbs and
+  local contents navigation
+- record adopted, superseded, and deferred directions without retaining
+  generated review artifacts
+- run Python, Markdown, Astro, focused navigation, presentation, link, and
+  repository-doctor validation
+- acceptance: the final PR diff contains source, tests, and formal
+  spec/plan/delivery records only; no generated review bundle remains
+
+## Risks
+
+- navigation and footer data can drift if a surface stops deriving from the
+  typed model; focused tests pin the durable ownership rules
+- component extraction can erase page meaning if it is based on appearance
+  alone; every shared component keeps explicit exclusions
+- Astro scoped styles can disappear from built output; inspect representative
+  built pages where styling is behaviorally significant
+- dated review measurements can be mistaken for current state; the delivery
+  record is the final reconciliation point

docs/plans/2026-07-23-global-section-opener.md

@@ -0,0 +1,48 @@
+# Build Plan — global-section-opener
+
+slug: `global-section-opener` · status: `delivered in draft PR #30`
+
+> Extract the repeated long-form opening grammar without changing page-owned
+> content or composition.
+
+## Tasks
+
+### t1 — Add the shared component
+
+- create `SectionIntro.astro` with eyebrow, stable `h2`, optional post-title
+  content, introduction paragraphs, title-spacing choice, and reveal choice
+- use the shared heading and prose measures
+- acceptance: source and built output contain the component's semantic markers,
+  measures, and reduced-motion-safe reveal behavior
+
+### t2 — Migrate the agent profiles
+
+- replace repeated opening markup in Devague, Colleague, Lobes, and Reachy Mini
+  CLI
+- label each migrated parent section with its component heading
+- acceptance: existing copy, section IDs, reveal timing, accessible labels, and
+  downstream content remain
+
+### t3 — Migrate the article beats
+
+- use one component call inside the existing eight-beat loop
+- preserve optional definitions, the first-paragraph lede, paragraph-level
+  reveals, evidence notes, and beat layout
+- acceptance: all eight rendered headings keep their stable IDs and definitions
+  remain between title and prose
+
+### t4 — Document and validate the migration
+
+- record the adopted surfaces, semantic requirements, article ordering, and
+  presentation exclusion
+- build the site and review representative agent and article output
+- acceptance: the production build passes; semantic order, readable measures,
+  reduced-motion behavior, and the presentation exclusion survive review
+
+## Risks
+
+- boolean false attributes can render as literal HTML attributes; use explicit
+  template branches for optional reveal markers
+- Astro scoped styles can miss component-generated markup; inspect built output,
+  not source alone
+- article definitions can move during extraction; verify their rendered order

docs/plans/2026-07-23-global-structured-card.md

@@ -0,0 +1,50 @@
+# Build Plan — global-structured-card
+
+slug: `global-structured-card` · status: `delivered in draft PR #30`
+
+> Migrate metadata-led agent-profile information cards to one semantic
+> component while preserving different card families.
+
+## Tasks
+
+### t1 — Add the shared card and grid
+
+- create `StructuredCard.astro` with optional metadata/footer, code-title
+  semantics, featured span, reveal timing, and namespaced grid styles
+- acceptance: metadata → title → body → footer order, 16px body copy, 52rem
+  three-to-two-to-one grid, and no client-side copy behavior
+
+### t2 — Migrate Devague
+
+- migrate method moves and operator skills
+- keep the lead method card featured and command titles semantic
+- acceptance: method and operator-skill cards preserve their content and
+  semantics; the pipeline remains a separate ruled reference list
+
+### t3 — Migrate Colleague
+
+- migrate paradigm, tiers, work loop, minds, and surfaces
+- keep tier/mind context as metadata and command strings as compact footers
+- acceptance: every migrated field retains its meaning and reading order
+
+### t4 — Migrate Reachy Mini CLI and Lobes
+
+- migrate four Reachy families and the Lobes role family
+- preserve source copy, repository/model strings, and page order
+- acceptance: source copy, repository/model strings, and page order remain
+
+### t5 — Document and validate inclusion and exclusion
+
+- record the adopted families, semantic order, responsive behavior, command
+  treatment, absent copy controls, and intentional exclusions
+- build the site and review representative card families at narrow and wide
+  viewports
+- acceptance: the production build passes and excluded families remain local
+
+## Risks
+
+- long command titles can overflow narrow columns; allow semantic code to wrap
+- equal-height desktop rows can create dead space on mobile; use natural rows at
+  the one-column layout
+- later pipeline changes can invalidate recorded counts; treat counts as a
+  delivery snapshot and review current source for present inventory