Tracks ADR-0048: Semantic-reference metadata embeds in package documentation (Status: Proposed).
ADR PR: #1794
Builds on: ADR-0046 (package docs as metadata, §3.4 reserved semantic links, §3.5 derived-content-is-rendered), ADR-0025 (trust boundary), ADR-0033 (AI as author).
Problem
A package's prose wants to point at the thing it documents — "here is the routing flow," "this is the pipeline dashboard," "these are the lead's fields." ADR-0046 bans MDX (code in the platform origin = ADR-0025 violation) but §3.4 reserved semantic links and §3.5 ruled that a diagram of an existing flow is derived metadata, rendered live, never committed. That describes a feature without specifying it. This is the specification.
Design (the inversion)
The author supplies only a NAME (data); the platform supplies the COMPONENT (code).
The opposite of embedding author-written MDX/SDUI (SDUI is worse — its nodes bind actions/data/server-calls). A name is inert data a sanitizer already trusts; the component is first-party code the platform already trusts. The trust boundary never moves.
- Syntax — extend §3.4's protocol-link family:
flow://<name>, view://<name>, dashboard://<name>, object://<name>. Markdown-native link → graceful GitHub/editor degradation, parse-only lint. Resolves renderer-side to a read-only SchemaRenderer scoped to that one metadata item, accepting no author props.
- Guardrail (a) — read-only + permission-scoped: non-interactive projection (no "run this flow" in a doc), resolved against the current viewer's permissions + the same
sys_package_grant that delivered the package. No access bypass; previews show the viewer's own RLS rows.
- Guardrail (b) — cross-package references degrade to a render-time "not found" notice; never couple into install-time dependency resolution.
- Boundary, one line — in-metadata → live embed (this ADR); not-in-metadata conceptual → Mermaid (deferred); author-written component code → never.
Phasing (P3+ on ADR-0046)
Rejected alternatives
Inline SDUI component JSON, MDX/author React, author-supplied <iframe>, custom fenced blocks, publish-time baking, lint-time metadata resolution.
Tracks ADR-0048: Semantic-reference metadata embeds in package documentation (Status: Proposed).
ADR PR: #1794
Builds on: ADR-0046 (package docs as metadata, §3.4 reserved semantic links, §3.5 derived-content-is-rendered), ADR-0025 (trust boundary), ADR-0033 (AI as author).
Problem
A package's prose wants to point at the thing it documents — "here is the routing flow," "this is the pipeline dashboard," "these are the lead's fields." ADR-0046 bans MDX (code in the platform origin = ADR-0025 violation) but §3.4 reserved semantic links and §3.5 ruled that a diagram of an existing flow is derived metadata, rendered live, never committed. That describes a feature without specifying it. This is the specification.
Design (the inversion)
The opposite of embedding author-written MDX/SDUI (SDUI is worse — its nodes bind actions/data/server-calls). A name is inert data a sanitizer already trusts; the component is first-party code the platform already trusts. The trust boundary never moves.
flow://<name>,view://<name>,dashboard://<name>,object://<name>. Markdown-native link → graceful GitHub/editor degradation, parse-only lint. Resolves renderer-side to a read-onlySchemaRendererscoped to that one metadata item, accepting no author props.sys_package_grantthat delivered the package. No access bypass; previews show the viewer's own RLS rows.Phasing (P3+ on ADR-0046)
plugin-markdown, not just full-page — not built.plugin-markdownintercepts protocol-scheme links → read-onlySchemaRendererprojection with both guardrails.Rejected alternatives
Inline SDUI component JSON, MDX/author React, author-supplied
<iframe>, custom fenced blocks, publish-time baking, lint-time metadata resolution.