From 191db719f5b28a6ec72a5bcf1d65d9917de16482 Mon Sep 17 00:00:00 2001
From: Damian Reeves <957246+DamianReeves@users.noreply.github.com>
Date: Wed, 28 Oct 2026 05:56:47 -0500
Subject: [PATCH] docs(openspec): archive the published site change

---
 .../.openspec.yaml                            |  0
 .../design.html                               | 25 ++++----
 .../proposal.md                               |  0
 .../specs/docs/cli-integration/spec.md        |  0
 .../specs/docs/examples/spec.md               |  0
 .../specs/docs/site/spec.md                   |  0
 .../tasks.md                                  |  2 +-
 openspec/specs/docs/cli-integration/spec.md   | 50 +++++++++++++++
 openspec/specs/docs/examples/spec.md          | 58 ++++++++++++++++++
 openspec/specs/docs/site/spec.md              | 61 +++++++++++++++++++
 10 files changed, 183 insertions(+), 13 deletions(-)
 rename openspec/changes/{add-documentation-site => archive/2026-10-28-add-documentation-site}/.openspec.yaml (100%)
 rename openspec/changes/{add-documentation-site => archive/2026-10-28-add-documentation-site}/design.html (87%)
 rename openspec/changes/{add-documentation-site => archive/2026-10-28-add-documentation-site}/proposal.md (100%)
 rename openspec/changes/{add-documentation-site => archive/2026-10-28-add-documentation-site}/specs/docs/cli-integration/spec.md (100%)
 rename openspec/changes/{add-documentation-site => archive/2026-10-28-add-documentation-site}/specs/docs/examples/spec.md (100%)
 rename openspec/changes/{add-documentation-site => archive/2026-10-28-add-documentation-site}/specs/docs/site/spec.md (100%)
 rename openspec/changes/{add-documentation-site => archive/2026-10-28-add-documentation-site}/tasks.md (99%)
 create mode 100644 openspec/specs/docs/cli-integration/spec.md
 create mode 100644 openspec/specs/docs/examples/spec.md
 create mode 100644 openspec/specs/docs/site/spec.md

diff --git a/openspec/changes/add-documentation-site/.openspec.yaml b/openspec/changes/archive/2026-10-28-add-documentation-site/.openspec.yaml
similarity index 100%
rename from openspec/changes/add-documentation-site/.openspec.yaml
rename to openspec/changes/archive/2026-10-28-add-documentation-site/.openspec.yaml
diff --git a/openspec/changes/add-documentation-site/design.html b/openspec/changes/archive/2026-10-28-add-documentation-site/design.html
similarity index 87%
rename from openspec/changes/add-documentation-site/design.html
rename to openspec/changes/archive/2026-10-28-add-documentation-site/design.html
index 52df927b..c0afa75c 100644
--- a/openspec/changes/add-documentation-site/design.html
+++ b/openspec/changes/archive/2026-10-28-add-documentation-site/design.html
@@ -13,16 +13,16 @@
   Code goes in <pre><code class="language-python"> (or json, toml, bash, diff). Give sections an id and
   list them in nav.toc.
 -->
-<link rel="stylesheet" href="../../../docs/templates/assets/agent-document.css">
-<link rel="stylesheet" href="../../../docs/templates/assets/highlight/styles/github.min.css" media="(prefers-color-scheme: light)">
-<link rel="stylesheet" href="../../../docs/templates/assets/highlight/styles/github-dark.min.css" media="(prefers-color-scheme: dark)">
-<script defer src="../../../docs/templates/assets/highlight/highlight.min.js"></script>
-<script defer src="../../../docs/templates/assets/agent-document.js"></script>
+<link rel="stylesheet" href="../../../../docs/templates/assets/agent-document.css">
+<link rel="stylesheet" href="../../../../docs/templates/assets/highlight/styles/github.min.css" media="(prefers-color-scheme: light)">
+<link rel="stylesheet" href="../../../../docs/templates/assets/highlight/styles/github-dark.min.css" media="(prefers-color-scheme: dark)">
+<script defer src="../../../../docs/templates/assets/highlight/highlight.min.js"></script>
+<script defer src="../../../../docs/templates/assets/agent-document.js"></script>
 </head>
 <body>
 <main>
 <h1>add-documentation-site</h1>
-<p class="meta">OpenSpec change · Bead <code>morphir-ukvn.9</code> · 2026-10-28 · Published foundation; MoonBit visual alignment in progress</p>
+<p class="meta">OpenSpec change · Bead <code>morphir-ukvn.9</code> · 2026-10-28 · Published and verified; MoonBit visual alignment complete</p>
 
 <nav class="toc" aria-label="Contents">
 <ul>
@@ -41,12 +41,12 @@ <h2 id="context">Context and evidence</h2>
 <table>
 <thead><tr><th>Observed source</th><th>Consequence</th></tr></thead>
 <tbody>
-<tr><td><a href="../../../docs/python-compiler.md">Python compiler guide</a> and <a href="../../../tests/tools/test_python_docs.py">its tests</a></td><td>Reuse the typed API example and fresh-interpreter/type-checking coverage. The current test assumes one page and fixed stdout; expand it for named examples and assertions.</td></tr>
-<tr><td><a href="../../../docs/python-extension.md">Extension guide</a> and <a href="../../../rust/extension.toml">bundle pins</a></td><td>The Python artifact is an Extism guest. Existing host qualification and bundle metadata are the starting evidence for finos/morphir.</td></tr>
+<tr><td><a href="../../../../docs/python-compiler.md">Python compiler guide</a> and <a href="../../../../tests/tools/test_python_docs.py">its tests</a></td><td>Reuse the typed API example and fresh-interpreter/type-checking coverage. The current test assumes one page and fixed stdout; expand it for named examples and assertions.</td></tr>
+<tr><td><a href="../../../../docs/python-extension.md">Extension guide</a> and <a href="../../../../rust/extension.toml">bundle pins</a></td><td>The Python artifact is an Extism guest. Existing host qualification and bundle metadata are the starting evidence for finos/morphir.</td></tr>
 <tr><td><a href="https://github.com/finos/morphir-moonbit/blob/bd3adc52e6b8f6368fdaee50f76535799732f8d6/docs/WRITING_FOR_THE_SITE.md">MoonBit site authoring guide</a></td><td>Follow its user journeys, tested examples and checked links. Use Telescope rather than copy its custom MoonBit renderer.</td></tr>
 <tr><td><a href="https://github.com/finos/morphir-moonbit/blob/bd3adc52e6b8f6368fdaee50f76535799732f8d6/apps/morphir/docs/extension.md">MoonBit extension adapters</a></td><td>Core-WASM process and native-process support do not qualify an Extism guest. The portable path uses an IR v4 model envelope and has explicit codec/provenance constraints.</td></tr>
 <tr><td><a href="https://github.com/moonrockz/telescope/blob/615d75c/docs/cli.md">Telescope CLI</a> and <a href="https://github.com/moonrockz/telescope/blob/615d75c/docs/release/0.2.1.md">0.2.1 release evidence</a></td><td>A stock native CLI builds Markdown/HTML, checks links, and embeds CSS and browser controls. Its API adapter consumes MoonBit metadata, not Python signatures.</td></tr>
-<tr><td><a href="../../../scripts/ci_changes.py">CI selector</a> and <a href="../../../.github/workflows/ci.yml">CI workflow</a></td><td>Most docs currently select no work. Unknown paths, workflow changes and full runs select all categories. Add explicit docs ownership without weakening aggregate failure handling.</td></tr>
+<tr><td><a href="../../../../scripts/ci_changes.py">CI selector</a> and <a href="../../../../.github/workflows/ci.yml">CI workflow</a></td><td>Most docs currently select no work. Unknown paths, workflow changes and full runs select all categories. Add explicit docs ownership without weakening aggregate failure handling.</td></tr>
 </tbody>
 </table>
 </section>
@@ -134,19 +134,20 @@ <h3 id="ci-1">CI-1. Select docs work and promote one checked artifact</h3>
 <summary>Build-master reassessment and validation evidence</summary>
 <p>Implementation <code>af9c725</code> passed every check in <a href="https://github.com/finos/morphir-python/actions/runs/40637061027">CI run 40637061027</a>, against base <code>f9c9af6</code>. The retained site binds the integrated candidate <code>302892bc85fdbac838c9b0b850f03a7e3ed48023</code>, Telescope 0.2.1, all three installed-example groups, Linux host qualification and hashes of 20 published files. A local download independently passed artifact verification and Telescope checking. <a href="https://github.com/finos/morphir-python/pull/51">PR 51</a> has no automated review findings.</p>
 <p>After rebasing onto the corrected companion release <code>1f547d1</code>, local full checks passed 2,518 tests, 34 BDD scenarios and 98.35% coverage. The current qualified set is core/CLI 0.1.0, native 0.1.1 and extension 0.4.2. Clean published-wheel, candidate-wheel and library-only examples passed after publication; the strict multi-document check remains enforced. The first refreshed CI attempt reached PyPI before its CLI index entry was visible, so fresh-index acquisition and final CI repeat that qualification before merging. Twelve browser cases passed at both deployment bases. Linux CI measured installed examples at 43 seconds, host qualification at 76 seconds, and site/browser validation at 45 seconds. These are one-run job durations, not queue time, billing or a measured before/after speedup. The compatible native wheel was produced once and reused by tests, bundle qualification, installed examples and packaging.</p>
-<p>The implementation preserves required failure/cancellation/skip handling, binds evidence and artifact bytes, and refuses PR/fork/failed/unrelated producers. No required coverage was deferred to a schedule. GitHub Pages now reports Actions deployment enabled. A first authorized production promotion and a real production rollback remain workflow follow-up after review and merge.</p>
+<p>The implementation preserves required failure/cancellation/skip handling, binds evidence and artifact bytes, and refuses PR/fork/failed/unrelated producers. No required coverage was deferred to a schedule. GitHub Pages now reports Actions deployment enabled. Production promotion passed; a real production rollback remains untested, while the retained-artifact recovery contract has regression coverage.</p>
 <table>
 <thead><tr><th>Criterion</th><th>Weight</th><th>Implemented rating</th><th>Evidence and confidence</th></tr></thead>
 <tbody>
 <tr><td>Risk and coverage fit</td><td>25</td><td>4</td><td>Selector/aggregate regressions, broken-build preservation, stale receipt and artifact/producer refusal tests; full CI passed. High confidence for tested contracts.</td></tr>
 <tr><td>Feedback and placement</td><td>20</td><td>3</td><td>Measured category jobs run independently after their real producer. No prior site baseline; one Linux run gives medium confidence.</td></tr>
-<tr><td>Evidence and trust</td><td>20</td><td>U</td><td>Candidate binding and producer refusals pass; first production workflow invocation awaits authorized main publication.</td></tr>
+<tr><td>Evidence and trust</td><td>20</td><td>4</td><td>Candidate binding and producer refusals pass. Published final bytes match their source-bound manifest after authorized promotion. High confidence.</td></tr>
 <tr><td>Execution efficiency</td><td>15</td><td>3</td><td>Native artifact reuse verified. Small pure wheels are built for early docs feedback before the broader package gate; no compute-saving estimate is claimed.</td></tr>
 <tr><td>Ownership and structure</td><td>10</td><td>4</td><td>One reusable documentation workflow with explicit example/host inputs, stable aggregate and separate privileged publisher. High confidence from source and CI.</td></tr>
 <tr><td>Operability and recovery</td><td>10</td><td>2</td><td>Failure diagnostics, 30-day retention and run-ID rollback are documented and their refusal checks pass. A real Pages rollback is untested.</td></tr>
 </tbody>
 </table>
-<p>The total remains withheld because the 20-weight production trust criterion is unknown. Retain the scoped design provisionally: the all-checks-on-every-prose-edit alternative adds unrelated compiler work, while this selector preserves conservative unknown/full-run behavior and qualifies relevant examples and host changes. The maintainer owns the first production promotion and rollback evidence; a green proposal or PR does not grant merge or deployment approval.</p>
+<p>The implemented design scores 86/100 after production verification, denominator 100. Retain the scoped design: the all-checks-on-every-prose-edit alternative adds unrelated compiler work, while this selector preserves conservative unknown/full-run behavior and qualifies relevant examples and host changes. The maintainer owns recovery and any future publication decisions; the score does not grant publication approval.</p>
+<p>Final visual alignment landed in PR 53 as <code>d02f260c8040d24941aafa38938ab0e01e59a1be</code>. Main CI <a href="https://github.com/finos/morphir-python/actions/runs/40657687946">40657687946</a> and Pages deployment <a href="https://github.com/finos/morphir-python/actions/runs/40658741564">40658741564</a> passed. Independent public verification retrieved all 21 files, checked their SHA-256 digests against the source-bound eligible manifest, and verified the home design, search, release quickstart, clipboard, dark mobile layout and keyboard menu with no browser errors. Local checks passed 2,526 tests and 34 BDD scenarios, 12 explicit site/example checks and 20 browser cases. Telescope customization is tracked in <a href="https://github.com/moonrockz/telescope/issues/13">issue 13</a>.</p>
 </details>
 </section>
 
diff --git a/openspec/changes/add-documentation-site/proposal.md b/openspec/changes/archive/2026-10-28-add-documentation-site/proposal.md
similarity index 100%
rename from openspec/changes/add-documentation-site/proposal.md
rename to openspec/changes/archive/2026-10-28-add-documentation-site/proposal.md
diff --git a/openspec/changes/add-documentation-site/specs/docs/cli-integration/spec.md b/openspec/changes/archive/2026-10-28-add-documentation-site/specs/docs/cli-integration/spec.md
similarity index 100%
rename from openspec/changes/add-documentation-site/specs/docs/cli-integration/spec.md
rename to openspec/changes/archive/2026-10-28-add-documentation-site/specs/docs/cli-integration/spec.md
diff --git a/openspec/changes/add-documentation-site/specs/docs/examples/spec.md b/openspec/changes/archive/2026-10-28-add-documentation-site/specs/docs/examples/spec.md
similarity index 100%
rename from openspec/changes/add-documentation-site/specs/docs/examples/spec.md
rename to openspec/changes/archive/2026-10-28-add-documentation-site/specs/docs/examples/spec.md
diff --git a/openspec/changes/add-documentation-site/specs/docs/site/spec.md b/openspec/changes/archive/2026-10-28-add-documentation-site/specs/docs/site/spec.md
similarity index 100%
rename from openspec/changes/add-documentation-site/specs/docs/site/spec.md
rename to openspec/changes/archive/2026-10-28-add-documentation-site/specs/docs/site/spec.md
diff --git a/openspec/changes/add-documentation-site/tasks.md b/openspec/changes/archive/2026-10-28-add-documentation-site/tasks.md
similarity index 99%
rename from openspec/changes/add-documentation-site/tasks.md
rename to openspec/changes/archive/2026-10-28-add-documentation-site/tasks.md
index 301fb988..e27f30fc 100644
--- a/openspec/changes/add-documentation-site/tasks.md
+++ b/openspec/changes/archive/2026-10-28-add-documentation-site/tasks.md
@@ -10,7 +10,7 @@ Implement the contracts in `specs/docs/` using the decisions in `design.html`. S
 - [x] 1.4 Add browser smoke coverage for desktop and 360px, light/dark themes, keyboard focus, navigation, search and code copying; verify no page-level overflow and retain screenshots/results for the candidate.
 - [x] 1.5 Record the foundation/version/limitations in `docs/site-foundation.md`; link Telescope's existing tutorial intent when durable, and report any confirmed reusable blocker upstream with reproduction and acceptance criteria. Verify each remaining gap has a linked report or an explicit non-blocking consumer workaround.
 
-- [ ] 1.6 Match morphir-moonbit revision bd3adc52 colors and landing design using an attributed theme and Python example; verify both themes, desktop/mobile layouts, canonical source, base paths and atomic failure preservation, report the Telescope customization gap upstream and verify the published site after merge.
+- [x] 1.6 Match morphir-moonbit revision bd3adc52 colors and landing design using an attributed theme and Python example; verify both themes, desktop/mobile layouts, canonical source, base paths and atomic failure preservation, report the Telescope customization gap upstream and verify the published site after merge.
 
 ## 2. Publish verified Python API and CLI examples (morphir-ukvn.9.2)
 
diff --git a/openspec/specs/docs/cli-integration/spec.md b/openspec/specs/docs/cli-integration/spec.md
new file mode 100644
index 00000000..3464283d
--- /dev/null
+++ b/openspec/specs/docs/cli-integration/spec.md
@@ -0,0 +1,50 @@
+# docs/cli-integration Specification
+
+## Purpose
+
+Give users accurate, reproducible instructions for using the Python extension and exchanging IR across the independently implemented Morphir CLIs.
+
+## Requirements
+
+### Requirement: Compatibility guidance identifies the host
+The documentation SHALL distinguish morphir-python, finos/morphir and the MoonBit-based Morphir CLI by provider and version. Its compatibility matrix MUST identify extension transport, protocol, IR formats, artifact shape, supported operations and qualification evidence for each host. (bead: morphir-ukvn.9.3)
+
+#### Scenario: Two CLIs use the same executable name
+- **WHEN** a user selects an extension setup recipe
+- **THEN** the guide identifies which Morphir implementation must be installed and how to verify it before invoking commands
+
+### Requirement: Qualified extension setup is reproducible
+The finos/morphir guide SHALL document a qualified Python bundle/host pair, checksum verification, repository publication or selection, installation, discovery and compile/generate invocation. It MUST distinguish installing a bundle from selecting it for execution. (bead: morphir-ukvn.9.3)
+
+#### Scenario: Use a clean extension repository
+- **WHEN** a user follows the guide with the pinned bundle and host in a fresh workspace
+- **THEN** the host verifies and installs the expected extension, compiles the supplied Python model and generates Python with the documented artifacts
+
+### Requirement: Unsupported adapters are explicit
+The documentation MUST state that the current Python Extism guest is not interchangeable with the MoonBit core-WASM process adapter. Until an Extism adapter is independently qualified, the MoonBit guide SHALL label direct invocation unsupported and link its separate upstream proposal. (bead: morphir-ukvn.9.3)
+
+#### Scenario: Attempt direct MoonBit invocation
+- **WHEN** a user reads how to connect the current Python WASM bundle to the MoonBit CLI
+- **THEN** the guide explains the adapter and protocol gap and does not present an unqualified direct-invocation command as working
+
+### Requirement: IR interchange claims are qualified
+Each documented interchange direction SHALL identify the exact producer/consumer pair, model subset, version, encoding and artifact shape. Successful recipes MUST verify the consumer's result; refusal cases MUST identify the incompatibility. The guide MUST distinguish file exchange from invoking the Python extension through that host. (bead: morphir-ukvn.9.3)
+
+#### Scenario: Exchange a model using a supported route
+- **WHEN** a user follows a recipe classified as supported for the qualified versions
+- **THEN** the supplied fixture reaches the documented consumer operation through the stated conversion steps with checked semantic results
+
+#### Scenario: Formats or envelopes differ
+- **WHEN** the current host pair cannot exchange the supplied model without unsupported conversion or provenance loss
+- **THEN** the guide records a tested refusal and the missing capability rather than suggesting that renaming a plain IR file supplies the required envelope
+
+### Requirement: Qualification failures cannot silently become support claims
+Host integration checks SHALL record pinned host and bundle identities, commands, expected artifacts and diagnostics. Changes to a supported recipe MUST rerun its required qualification before publication. External-host availability problems MUST remain visible and cannot count as a passing compatibility check. (bead: morphir-ukvn.9.3)
+
+#### Scenario: A supported recipe changes
+- **WHEN** an edit changes a host pin, bundle pin or executable setup command
+- **THEN** publication requires evidence for that exact combination and changed recipe
+
+#### Scenario: The host cannot be obtained
+- **WHEN** qualification cannot obtain a required host or bundle
+- **THEN** the result reports the unavailable prerequisite and blocks a new or revised supported claim
diff --git a/openspec/specs/docs/examples/spec.md b/openspec/specs/docs/examples/spec.md
new file mode 100644
index 00000000..db44d75f
--- /dev/null
+++ b/openspec/specs/docs/examples/spec.md
@@ -0,0 +1,58 @@
+# docs/examples Specification
+
+## Purpose
+
+Help Python users learn the library and tools through reproducible examples whose displayed source and documented results stay consistent with the qualified packages.
+
+## Requirements
+
+### Requirement: Installation guidance identifies package responsibilities
+The guides SHALL distinguish the library, CLI distribution and automatically installed native compiler package. Each workflow MUST identify required interpreter/platform support and qualified package versions, separating released capabilities from source-only or draft capabilities. (bead: morphir-ukvn.9.2)
+
+#### Scenario: Start with an installed package
+- **WHEN** a user follows the compiler quickstart on a qualified wheel platform
+- **THEN** the guide installs the CLI distribution and its compatible compiler without requiring the user to install Rust
+
+#### Scenario: Use only the library
+- **WHEN** a user follows an IR or SDK example
+- **THEN** the guide identifies the library-only installation and does not require the compiler package for that example
+
+### Requirement: API examples cover both compiler directions
+The guides SHALL provide complete examples for in-memory Python compilation, generation from typed IR, and structured diagnostics. Examples MUST explain supported syntax, package/module identity, exposure and IR version selection. (bead: morphir-ukvn.9.2)
+
+#### Scenario: Compile and generate through Python
+- **WHEN** a user runs the API example with the documented prerequisites
+- **THEN** the example compiles a multi-module model, inspects its typed result and generates source artifacts with the documented relative paths
+
+#### Scenario: Understand unsupported source
+- **WHEN** a user runs the diagnostic example
+- **THEN** the example returns the documented error code and available source location and explains the relevant language limit
+
+### Requirement: Library examples explain IR and SDK usage
+The guides SHALL provide executable examples for reading and writing versioned IR, explicit supported migration and representative SDK operations. They MUST explain format support and refusal or loss diagnostics without implying that every distribution or construct can be compiled or generated. (bead: morphir-ukvn.9.2)
+
+#### Scenario: Inspect and migrate a model
+- **WHEN** a user follows the library example using the supplied fixture
+- **THEN** the example reads its version, decodes and writes it, and demonstrates an explicit supported conversion with its documented diagnostics
+
+### Requirement: CLI examples cover a complete workflow
+The guides SHALL include runnable compile, generate, inspect and convert examples, with input fixtures, expected files and exit behavior. They MUST explain output-directory constraints and distinguish semantic round trips from source-text preservation. (bead: morphir-ukvn.9.2)
+
+#### Scenario: Follow the CLI quickstart
+- **WHEN** a user runs the documented compile, inspect, generate and recompile sequence in a fresh directory
+- **THEN** the commands produce the documented artifacts and preserve the supported model's normalized semantics
+
+#### Scenario: Diagnose a command failure
+- **WHEN** a documented failing command uses unsupported source or a nonempty generation directory
+- **THEN** the observed exit status and diagnostic match the guide and existing user files remain intact
+
+### Requirement: Displayed examples match checked sources
+Every example presented as runnable SHALL have a canonical source and automated verification of its claimed result. Displayed code MUST match that source. API examples SHALL pass the project's type checks; CLI examples SHALL verify commands and outputs in isolated temporary directories. Unsupported platform or external-host cases MUST be labeled with their qualification limits. (bead: morphir-ukvn.9.2)
+
+#### Scenario: A snippet drifts
+- **WHEN** an edit changes a displayed runnable snippet without updating its checked source
+- **THEN** documentation verification fails before publication
+
+#### Scenario: An API or CLI option changes
+- **WHEN** a public signature or command option used in an example changes incompatibly
+- **THEN** verification detects the obsolete example or reference rather than publishing a successful quickstart claim
diff --git a/openspec/specs/docs/site/spec.md b/openspec/specs/docs/site/spec.md
new file mode 100644
index 00000000..953e9941
--- /dev/null
+++ b/openspec/specs/docs/site/spec.md
@@ -0,0 +1,61 @@
+# docs/site Specification
+
+## Purpose
+
+Provide a public, repository-owned documentation site that users can navigate and contributors can preview and validate before publication.
+
+## Requirements
+
+### Requirement: Documentation is discoverable
+The site SHALL expose installation, Python API, CLI, extension integration and contributor guides through navigation and search. Repository and package READMEs SHALL link to the site while retaining useful installation summaries. (bead: morphir-ukvn.9.1)
+
+#### Scenario: Find a workflow
+- **WHEN** a user opens the home page or searches for Python compilation
+- **THEN** the user can reach the corresponding runnable API and CLI guides and their prerequisites
+
+### Requirement: Documentation remains readable across devices
+The site SHALL support keyboard navigation, visible focus, light and dark themes, and narrow screens. Code examples SHALL preserve whitespace, identify their language and allow copying without decorative prompt characters. (bead: morphir-ukvn.9.1)
+
+#### Scenario: Read a guide on a narrow screen
+- **WHEN** a reader opens a guide at a 360-pixel viewport in either theme
+- **THEN** navigation and content remain usable without page-level horizontal overflow, with long code scrollable within its block
+
+#### Scenario: Navigate using a keyboard
+- **WHEN** a reader uses keyboard controls to open navigation, search and copy an example
+- **THEN** each control is reachable and exposes visible focus and an accessible name
+
+### Requirement: Contributors can reproduce a checked preview
+The repository SHALL document a pinned site-tool installation and commands to build, check and serve a local preview. Builds SHALL exclude planning artifacts and validate local pages, resources, fragments and deployment-base paths before publication. (bead: morphir-ukvn.9.1)
+
+#### Scenario: Preview a project-path deployment
+- **WHEN** a contributor follows the guide in a clean checkout and builds for the repository's Pages path
+- **THEN** the site passes checks and local preview resolves navigation, search and assets beneath that path
+
+#### Scenario: Broken content blocks publication
+- **WHEN** a page links to a nonexistent local fragment or resource
+- **THEN** validation fails with an actionable location and the invalid output is not published
+
+### Requirement: Publication uses verified output
+Site publication SHALL consume the exact output that passed required site and example checks for the selected source revision. Pull requests SHALL receive validation without production publication. Failed, missing or cancelled required checks MUST block publication. (bead: morphir-ukvn.9.4)
+
+#### Scenario: Publish a checked revision
+- **WHEN** an authorized main-branch publication passes its required checks
+- **THEN** deployment publishes their verified artifact with recorded source and tool versions
+
+#### Scenario: Example verification fails
+- **WHEN** required example verification fails or is unexpectedly skipped
+- **THEN** no production site deployment occurs for that revision
+
+### Requirement: Reusable site limitations are reported upstream
+When a site-foundation limitation obstructs a required experience, contributors MUST record a reproducible report in Telescope's tracker or link existing upstream work, documenting the affected version, consumer need and any temporary workaround. (bead: morphir-ukvn.9.1)
+
+#### Scenario: A required presentation feature is unavailable
+- **WHEN** a contributor confirms the pinned foundation cannot render a required example interaction
+- **THEN** the change records an upstream report or existing proposal and labels any workaround and remaining acceptance gap
+
+### Requirement: The site follows the Morphir MoonBit visual design
+The documentation SHALL use morphir-moonbit's blue/orange palette in light and dark themes, and its landing-page structure with a split hero, code window, workflow pipeline and feature cards. Content and calls to action SHALL describe qualified Python workflows and remain usable at 360 pixels. The displayed model MUST match a canonical checked Python example. (bead: morphir-ukvn.9.1)
+
+#### Scenario: Open the Python landing page
+- **WHEN** a reader opens the site at either supported deployment base in either theme
+- **THEN** the Morphir palette and responsive landing design are visible, the model matches the checked source, and the main actions reach the API and CLI guides without overflow