ADR-0048: Semantic-reference metadata embeds in package docs (flow:// / view:// / dashboard:// / object://) #1795

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)

• Prereq A (spec/cli): §3.4 semantic-link resolution layer (scheme→type, name lookup under viewer perms + grant) — not built.
• Prereq B (objectui): read-only embeddable metadata-view components — flow viewer, view preview, dashboard preview, object summary — usable inline in plugin-markdown, not just full-page — not built.
• P3a (lint): publish lint recognizes the protocol-link family, requires it parses (no metadata resolution).
• P3b (renderer): plugin-markdown intercepts protocol-scheme links → read-only SchemaRenderer projection with both guardrails.
• P3c (authoring + AI): Studio "insert reference" affordance; AI authors embeds when documenting an existing item.
• Deferred (separate ADR): Mermaid / conceptual text-diagrams.

Rejected alternatives

Inline SDUI component JSON, MDX/author React, author-supplied <iframe>, custom fenced blocks, publish-time baking, lint-time metadata resolution.