Prism Docs Surface

How local and synced docs are published at /docs and kept tied to repo source files.

Source: docs/architecture/prism-docs-surface.md

Prism Docs Surface

Prism exposes documentation under /docs. This restores the useful v1 pattern where the public app had discoverable docs, while keeping the source of truth in Git.

File Layout

Local Prism docs live in:

docs/architecture/

Synced Substrate docs live in:

docs/substrate/

Synced scidex-agents docs live in:

docs/agents/

The route registry is generated into:

src/lib/scidex/docs.ts

Local Prism entries are declared in scripts/sync-substrate-docs.mjs under LOCAL_PRISM_DOCS. Substrate entries are copied from ../scidex-substrate/docs/integrations/prism-docs-manifest.json. Agent entries are discovered from Markdown files in ../scidex-agents and prefixed with agents- slugs.

Each entry maps a URL slug to a source file and source repository:

{
  slug: "myst-living-artifacts",
  title: "MyST Living Artifacts",
  summary: "Architecture and conventions for repo-backed scientific artifacts.",
  category: "Architecture",
  sourcePath: "docs/architecture/myst-living-artifacts.md",
  sourceRepo: "prism"
}

Route Behavior

/docs renders the docs index. /docs/[slug] reads the registered Markdown or MyST file from the repository, renders it with the shared MyST renderer, and serves it as a normal Prism page.

The docs surface intentionally supports the same document primitives as scientific artifacts:

  • admonitions

  • figures

  • cross references

  • math

  • task lists

  • Mermaid diagrams

  • tables

Maintenance Rules

  • Add or update local Prism files under docs/architecture/.

  • Add a matching local entry in LOCAL_PRISM_DOCS inside scripts/sync-substrate-docs.mjs.

  • For Substrate docs, update the substrate Prism manifest.

  • For agent docs, add or update Markdown under scidex-agents/docs/ or scidex-agents/skills/.

  • Run pnpm sync:docs after changing the synced catalog, local docs registry, or agent docs.

  • Link important docs from AGENTS.md.

  • Keep docs concise enough to render well in Prism.

  • Prefer local docs for SciDEX-specific architecture and conventions.

  • Prefer external links for upstream references such as MyST, Forgejo, SvelteKit, and Substrate specs.

Testing

At minimum:

pnpm test --run src/lib/scidex/myst-render.test.ts
pnpm build

When docs route behavior changes, add focused route tests for src/routes/docs/[slug]/+page.server.ts.

Related Prism architecture docs

The 3 sister architecture docs that the /docs surface publishes:

  • artifact-authoring-conventions.md — authoring contract for agent-written artifacts; cross-links to SPEC-199 + substrate authoring-skill catalog (iter-144 #1596).

  • citations-and-references.md — [PMID:N] / [@key] / {cite} citation standard; cross-links to substrate methodology cluster exemplars (iter-145 #1597).

  • myst-living-artifacts.md — MyST rendering path + repo-backed artifact architecture (iter-156 #1599 added its sister cross-refs).

These 3 plus this doc are the canonical 4-doc Prism architecture set. Together they describe: WHAT to author (authoring-conventions), HOW citations render (citations), WHERE MyST content lives (myst-living), and HOW operators discover it (this doc — the publishing surface).