MyST Living Artifacts

Architecture and conventions for repo-backed scientific artifacts rendered by Prism.

Source: docs/architecture/myst-living-artifacts.md

MyST Living Artifacts

SciDEX treats scientific artifacts as living documents backed by two planes:

  • Substrate is the source of truth for identity, permissions, metadata, links, comments, signals, rankings, search, and lifecycle state.

  • Forgejo is the Git collaboration plane for repo history, branches, pull requests, issues, and human/agent review workflows.

MyST is the authoring format for rich scientific text because it keeps source files readable as Markdown while adding scientific document primitives: directives, roles, figures, cross-references, citations, equations, definition lists, task lists, and export-oriented metadata.

Rendering Path

Prism renders MyST through myst-parser and myst-to-html.

  1. The artifact stores content_md in Substrate, usually mirrored from artifact.myst.md in a Forgejo repo.

  2. Prism strips YAML frontmatter from the display body.

  3. Citation placeholders are resolved against Substrate citation metadata before MyST parsing.

  4. myst-parser converts the source into a MyST AST.

  5. myst-to-html converts the AST to safe HTML with raw HTML disabled.

  6. Prism applies shared .markdown styling and lazy-renders Mermaid diagrams.

The fallback path is the older markdown-it renderer. It exists only as a resilience guard if MyST parsing fails.

Supported Constructs

Construct Prism behavior
Admonitions Renders note, tip, important, warning, caution, and danger callouts.
Figures Renders figures with stable names and captions.
Cross references Resolves {numref} roles to numbered figure links.
Math Renders inline and display math containers.
Definition lists Renders definition terms and descriptions as <dl>.
Task lists Renders disabled checkboxes.
Mermaid Preserves diagram source for Prism’s lazy Mermaid renderer.

Canonical source examples:

:::{note} Review status
This artifact has an open Forgejo pull request.
:::

```{figure} figures/gbo-architecture.png
:name: fig-gbo-architecture

Repo-backed artifact flow for a SciDEX mission page.
```

See {numref}`fig-gbo-architecture`.

```{mermaid}
flowchart LR
  Repo --> Substrate
  Substrate --> Prism
```

Safety Rules

Prism does not execute source-repo MyST plugins. Agent-authored content is parsed with raw HTML disabled. Untrusted JavaScript, inline event handlers, and arbitrary HTML are not emitted by the renderer.

Allowed rich behavior must come through explicit SciDEX mechanisms:

  • MyST directives supported by the parser.

  • Substrate artifacts embedded by reference.

  • Prism components that intentionally render a known artifact/widget type.

  • Forgejo issues and pull requests linked by repo metadata.

Repository Contract

Repo-backed artifacts should use this layout:

scidex.yaml
README.md
artifact.myst.md
data/
figures/
notebooks/
reviews/open/
reviews/resolved/

scidex.yaml binds the Git repo to the Substrate artifact:

schema: scidex-artifact-repo@v1
artifact_ref: wiki_page:8b17d490-46d8-48df-8403-c51562a78342
artifact_type: wiki_page
repo_class: wiki
title: Global Brain Observatory
owner_actor_ref: actor:persona-jerome-lecoq
substrate_url: https://prism.scidex.ai
forge_provider: forgejo
forge_url: https://forge.scidex.ai/scidex-wiki/wiki-global-brain-observatory-8b17d490
clone_url_https: https://forge.scidex.ai/scidex-wiki/wiki-global-brain-observatory-8b17d490.git
license: CC-BY-4.0
renderers:
  - myst

Substrate Contract

The artifact record should include:

  • source_repo: Forgejo web URL.

  • frontmatter_json.forge_repository_url: Forgejo web URL.

  • frontmatter_json.forge_clone_url: clone URL.

  • frontmatter_json.artifact_authoring_format: myst.

  • frontmatter_json.artifact_repo_policy: repo-backed-living-artifact.

  • created_by: the owning actor or agent identity.

Substrate remains authoritative even when the repo contains the source file. Forgejo webhooks should eventually update content hashes, repo status, issue summaries, and PR state back into Substrate.

External References

Related Prism architecture docs

  • artifact-authoring-conventions.md — the upstream authoring contract that produces the MyST content this doc renders. Cross-links to SPEC-199 + substrate authoring-skill catalog (iter-144 #1596).

  • citations-and-references.md — the [PMID:N] / [@key] / {cite} citation rendering this MyST path supports. Cross-links to substrate methodology cluster exemplars (iter-145 #1597).

  • prism-docs-surface.md — how Prism’s /docs route publishes MyST content (local + synced substrate docs).