add-documentation-site
+ + + + +Context and evidence
+See the proposal for motivation. The compiler and extension already exist. This design adds a public guide around their present contracts, with executable evidence for the instructions readers follow.
+| Observed source | Consequence |
|---|---|
| Python compiler guide and its tests | 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. |
| Extension guide and bundle pins | The Python artifact is an Extism guest. Existing host qualification and bundle metadata are the starting evidence for finos/morphir. |
| MoonBit site authoring guide | Follow its user journeys, tested examples and checked links. Use Telescope rather than copy its custom MoonBit renderer. |
| MoonBit extension adapters | 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. |
| Telescope CLI and 0.2.1 release evidence | A stock native CLI builds Markdown/HTML, checks links, and embeds CSS and browser controls. Its API adapter consumes MoonBit metadata, not Python signatures. |
| CI selector and CI workflow | 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. |
Goals and boundaries
+Readers should install the right package, complete a small model round trip, use the IR/SDK library directly, and understand which host can run the extension. A contributor should preview the same site that CI checks and publishes. The contracts are in docs/site, docs/examples and docs/cli-integration.
+The initial site uses one documentation tree with explicit release and development labels. It does not introduce an evaluator, a browser Python runtime, a benchmark claim about Rust performance, or a new extension adapter. Full historical version trees can follow when releases need them. The user selected current-support documentation; the MoonBit Extism proposal is separate and does not gate this site.
+Decisions
+SITE-1. Consume the published Telescope CLI
+Start with Telescope 0.2.1. Pin the release archive and expected SHA-256 in repository-owned setup metadata for Linux x64 CI and macOS arm64 local use. Verify the binary version after installation. These targets have published qualification; document other platforms as unqualified. Telescope is build tooling, outside the Python runtime dependency graph. A stock binary requires no MoonBit compiler or neighboring checkout.
Use site/site.json, site/pages/ for the landing page, existing docs/ for guides and site/assets/ for repository assets. Explicit discovery/exclusions must keep templates, planning documents, OpenSpec changes and generated output out of navigation and search. Proposed mise tasks are site:setup, site:build, site:check, site:serve and docs:test. Setup should install only the tools each command needs.
{
+ "schema_version": 1,
+ "title": "Morphir Python",
+ "description": "Python models, Morphir IR and language tooling",
+ "base_path": "/morphir-python/",
+ "site_url": "https://finos.github.io/morphir-python/",
+ "repo_url": "https://github.com/finos/morphir-python",
+ "repo_ref": "main",
+ "packages": [],
+ "source_roots": ["docs", "site/pages"]
+}
+This is a configuration starting point, not the final navigation manifest. Configure exclusions, navigation and static resources using the pinned version's supported contract. Build to _site/; test both / and /morphir-python/. Keep existing guide URLs in the repository useful and add site links to READMEs. Copying MoonBit's renderer would duplicate work now owned by Telescope; a separate Python documentation framework would split that shared foundation.
DOCS-1. Organize around complete user journeys
+| Navigation | Initial content |
|---|---|
| Start | Package responsibilities, supported Python/wheel platforms, installation, first CLI round trip and first in-memory API example. |
| Python API | Compiler inputs, typed success/failure results, diagnostics, exposure and generated artifacts; IR codecs, version reading/migration and representative SDK functions. |
| CLI | compile, generate, ir inspect, ir convert, options, exit behavior, output safety and supported Python subset. |
| Connect to Morphir | Host identification, compatibility table, finos/morphir extension setup, MoonBit limitations and qualified IR exchange or refusal examples. |
| Contribute | Build/preview/check commands, example authoring, pin updates, host qualification, publication and Telescope upstream reporting. |
Use one checked multi-module domain example for API, CLI and extension guides, plus small independent IR/SDK examples. Explain the result before reference details. Keep a concise public symbol/command reference checked against exports, signatures and help output. Telescope's MoonBit API importer is unsuitable for Python; explicit Python reference pages avoid adding an unrelated generator to the first delivery.
+ +DOCS-2. Treat runnable snippets as maintained examples
+Store canonical Python sources, CLI argument arrays, fixtures and expected results under examples/. Give runnable snippets stable example identifiers and source-region references. A small Python docs utility synchronizes marked fenced regions in committed Markdown and offers a check-only mode that fails on drift. This works with the stock Telescope CLI. Retain source-file links and downloadable examples. Do not copy a tutorial into multiple untracked code blocks.
Extend the existing docs test coverage to execute named API examples in isolated interpreters and run mypy/pyright, checking typed results, artifacts and diagnostics. Run CLI recipes in temporary directories against installed distributions, assert semantic round trips, and cover invalid source and nonempty output directories. Test snippets without executing submitted compiler input as part of compilation. Generated model behavior can be checked in a separate verification process, as existing compiler tests do.
+Record example prerequisites in a small machine-readable manifest. Released quickstarts use an exact qualified package set installed outside the checkout; development examples use the candidate wheels already produced by CI and visibly say they require a source build. The site's main-branch freshness must not imply that an unreleased compact-v4 writer or migration is available in a released wheel. A single tree can carry both labels without a version-assembly pipeline.
+ +HOST-1. Qualify each CLI independently
+| Consumer | Current evidence | Guide treatment |
|---|---|---|
morphir-python | Typed Python API and installed CLI call the native compiler in process. Default compiler output is IR v3; draft v4 is explicit. | Release-qualified install and API/CLI round trips, independent of another Morphir executable. |
finos/morphir | Existing Extism bundle host qualification; descriptor/CLI versions are pinned in rust/extension.toml. | Pin an actual released host/bundle pair, download and verify, create/select repository, install, discover capabilities and compile/generate. State IR selection explicitly. |
| MoonBit-based Morphir CLI | Core-WASM callback adapter and native-process adapter; its current guide requires a separately qualified Extism adapter. | Label direct Python-bundle invocation unsupported. Probe narrow file exchange with the pinned CLI and show either a verified route or an actionable refusal. |
Give each recipe an executable path and version/provider check so two programs called morphir cannot silently substitute for one another. Record exact host revisions/releases, bundle digest, MEP version, IR version/encoding, model distribution and envelope shape. A plain IR JSON document and a MoonBit model-envelope.json are distinct artifacts. Ion support or a shared IR version alone does not prove a working file exchange. Do not add ad hoc envelope or provenance conversions to make a documentation test pass.
Reuse scripts/extension_bundle.py qualification and its existing host rather than invent another bundle packager. Add a bounded host recipe runner for the documented setup. Host-integration evidence contains input/command hashes, dependencies, outputs, diagnostic expectations and the qualification runner identity. Successful support claims require matching evidence. If no MoonBit exchange direction works today, publish the checked incompatibility and follow-up instead of expanding runtime scope.
A Codex workspace was dispatched at /Users/damian/orca/workspaces/morphir-moonbit/propose-extism-python, branch DamianReeves/propose-extism-python, to propose Extism support separately. Replace this dispatch reference with its durable proposal/bead link when available. Existing MoonBit installed-selection follow-up morphir-ukvn.5.64.30 is another reason to distinguish installation from invocation.
UP-1. Report generic foundation gaps to Telescope
+Use stock rendering and browser controls first. Python compilation, CLI execution and result assertions belong to this consumer. Telescope's current API adapter accepts MoonBit metadata, so use authored, checked Python reference pages. If a reusable Python metadata adapter becomes necessary, report it upstream with a minimal fixture and acceptance criteria before building a private parallel system.
+The local Telescope checkout already contains an unmerged standardize-tutorial-components intent covering source-region examples and verification metadata. Record that relationship without treating it as a released dependency or modifying its draft. If its proposal later has a durable upstream link, use it rather than file a duplicate. For any blocking limitation, record version, minimal reproduction, expected behavior, consumer impact, workaround and upstream issue/proposal in docs/site-foundation.md. Adopt a fix only through a published, pinned release after checks. No confirmed rendering blocker currently requires a new Telescope issue.
Checks and publication
+CI-1. Select docs work and promote one checked artifact
+Add docs ownership to the existing CI selector. Keep specific site/example/workflow rules ahead of broad docs, scripts and workflow rules. Published prose/configuration selects static build/check/browser coverage. Example or referenced API/CLI changes also select the relevant installed-package tests, using compatible existing wheel artifacts. Host recipe/pin changes select host qualification. Unknown paths and full runs remain conservative, and selected jobs that fail, cancel, disappear or skip unexpectedly must fail the aggregate.
| Check and owner | Risk, trigger and deadline | Evidence and failure action |
|---|---|---|
| Static site, docs maintainers | Broken links, excluded content leaks, deployment paths and unreadable UI. All published prose/config/assets; before merge and deployment. | Build/check at both bases; browser smoke at desktop and 360px, both themes, search/menu/copy/focus. Failure blocks the aggregate and publication. |
| Examples, Python maintainers | Incorrect API/CLI advice. Example sources, snippets, dependencies and referenced APIs/commands; before merge and deployment. | Snippet drift, type checks, isolated execution and output assertions for the declared package set. Reuse wheel producers when candidate checks are selected. |
| Host recipes, extension maintainers | False compatibility claims. Recipe/pin/host-contract changes; before new or revised claims merge or publish. | Exact recipe and artifact evidence. Missing evidence blocks the changed claim. Unchanged recipes may reuse evidence only with matching relevant-input hashes and qualified dependencies. |
| Pages, docs maintainers | Publishing unverified bytes. Authorized main push or manual main run; after all required evidence succeeds. | Deploy the checked build artifact, with source SHA, Telescope version, package pins and evidence manifest. No rebuild during deployment. |
Factor reusable site build/check work so the main CI and deployment caller use one definition. Keep deployment in the trusted main workflow, with pages: write and id-token: write only on the deploy job and the github-pages environment. PR validation has no deployment credentials. Avoid workflow_run promotion of untrusted PR artifacts. Re-run required examples for the main candidate or verify the documented relevant-input equivalence contract; a cache hit alone is insufficient.
Initial checks run on Linux x64; validate local installation on macOS arm64. Broader package-platform coverage stays with existing package qualification. No new nightly schedule is needed. Measure representative run duration and artifact reuse during implementation; this proposal promises no unmeasured speedup.
+Build-master assessment and alternatives
+The decision is provisional until selector, artifact and failure-path tests exist. Incorrect examples have moderate impact; untrusted deployment has high impact. The deadline is before the relevant merge or publication. Hard requirements for gate preservation, artifact identity and privilege isolation are currently unknown for the proposed implementation. No required coverage is deferred to an unenforced schedule.
+| Criterion | Weight | All checks on every docs edit | Scoped category and artifact reuse |
|---|---|---|---|
| Risk and coverage fit | 25 | U, new site checks absent | U, selector regressions required |
| Feedback and placement | 20 | U, no baseline timings | U, measure selected runs |
| Evidence and trust | 20 | U, deployment not built | U, promotion tests required |
| Execution efficiency | 15 | U, no measured comparison | U, verify compatible reuse |
| Ownership and structure | 10 | 2, broad existing categories | U, proposed docs ownership |
| Operability and recovery | 10 | U, new deployment absent | U, rollback/failure tests required |
Totals are withheld because the evidence is incomplete. Confidence in the inspected category contracts is high; runtime and proposed promotion behavior remain unmeasured. Prefer scoped checks because the existing selector already owns change planning, then validate that choice in task group 4.
+Risks and trade-offs
+| Risk | Mitigation |
|---|---|
| MoonBit interoperability cannot be made successful with documentation alone. | Checked refusals satisfy accurate current-support guidance. Extism implementation remains a separate upstream proposal. |
| Telescope 0.2.1 lacks a required reusable feature. | Report or link upstream, keep a bounded documented consumer workaround and expose any unmet acceptance criterion. |
| Main-branch API docs get ahead of released packages. | Exact prerequisite manifests, visible release/development labels and installed-artifact checks. |
| Generated snippets add maintenance cost. | One small sync/check utility with explicit markers; consumer tests own domain behavior. Replace with an upstream facility only after a published compatible release. |
| Host downloads are unavailable or pins change. | Retain matching evidence for immutable qualified inputs. Changes to those inputs require fresh qualification; download failure never counts as success. |
| Pages settings are not enabled. | Prepare and verify the complete site artifact and workflow first, then request the specific maintainer setting if necessary. |
Migration and rollback
+Deliver the implementation in one PR if practical, with task groups carrying their own tests and docs. Preserve existing guide paths and enhance their content rather than delete the only instructions before the site is live. Add the site skeleton, checked examples and host guidance, then integrate the selector and publication job. Run the pinned consumer installation, project-base checks and browser smoke on the complete candidate.
+After review and authorized merge, deploy the verified main artifact. If repository settings block it, provide the checked artifact and exact setting request. Roll back a bad publication by redeploying a retained previously verified site artifact or reverting the content change and validating that revision. Keep package/extension releases independent of a site rollback. Archive this OpenSpec change and close task beads only after the agreed implementation evidence exists.
+