docs(openspec): archive the published site change

openspec/changes/add-documentation-site/design.html → 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>
 

openspec/changes/add-documentation-site/tasks.md → 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)
 

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

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