From a614ee838ef19f0ba88acef9005b50fa32a860af Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 7 Sep 2026 05:46:19 +0000
Subject: [PATCH] docs(plugin-markdown): compile the README's snippets against
 the shipped surface
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Burns down `packages/plugin-markdown/README.md`'s `UNGATED_DOCS` entry
(objectui#5174, batch 34): the page moves from the gate's ledgered tier into
its compiled tier, so its snippets are judged on every commit instead of being
recorded as debt.

- The "Schema API" block was a TYPE shape written as an object literal — the
  page's only parse failure and both ledgered diagnostics. It becomes a
  Markdown members table, so the page points at `MarkdownSchema` instead of
  carrying a second private copy of it.
- The Usage example's bare `const schema = { … }` is annotated
  `MarkdownSchema` with the type import; measured beforehand, the unannotated
  binding accepted a genuine type error with a byte-identical ledger row.
- The manual-registration loop now passes the `{ namespace: 'plugin-markdown' }`
  third argument the plugin's own registration makes; the two-argument form
  still compiles but `ComponentRegistry.register` warns that it is deprecated.

No `src/**` or type edit: `content`'s contract-versus-runtime reading
(`schema.content || ''`) and the two ADR-0049 tombstones are stated, not
changed.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FhBNJcLRZLe8M87VcUgpKr
---
 packages/plugin-markdown/README.md  | 35 +++++++++++++++++++++--------
 scripts/check-doc-snippet-types.mjs |  2 --
 2 files changed, 26 insertions(+), 11 deletions(-)

diff --git a/packages/plugin-markdown/README.md b/packages/plugin-markdown/README.md
index be10e1069b..4faeb86ae4 100644
--- a/packages/plugin-markdown/README.md
+++ b/packages/plugin-markdown/README.md
@@ -24,9 +24,10 @@ pnpm add @object-ui/plugin-markdown
 ```typescript
 // In your app entry point (e.g., App.tsx or main.tsx)
 import '@object-ui/plugin-markdown';
+import type { MarkdownSchema } from '@object-ui/plugin-markdown';
 
 // Now you can use markdown type in your schemas
-const schema = {
+const schema: MarkdownSchema = {
   type: 'markdown',
   content: '# Hello World\n\nThis is **markdown** text.'
 };
@@ -40,7 +41,7 @@ import { ComponentRegistry } from '@object-ui/core';
 
 // Manually register if needed
 Object.entries(markdownComponents).forEach(([type, component]) => {
-  ComponentRegistry.register(type, component);
+  ComponentRegistry.register(type, component, { namespace: 'plugin-markdown' });
 });
 ```
 
@@ -59,13 +60,29 @@ const schema: MarkdownSchema = {
 
 ## Schema API
 
-```typescript
-{
-  type: 'markdown',
-  content: string,     // Markdown content (supports GitHub Flavored Markdown)
-  className?: string   // Tailwind classes
-}
-```
+`MarkdownSchema` has one authority — it is declared in `@object-ui/types` and
+re-exported by this package — so the members are listed here rather than
+re-declared as a second copy in a code block.
+
+| Member | Type | Required | Default | Read by |
+| --- | --- | --- | --- | --- |
+| `type` | `'markdown'` | yes | none | the registry, to resolve this renderer (registered under the `plugin-markdown` namespace) |
+| `content` | `string` | yes | none — see the note below | `MarkdownRenderer`, which forwards it to the lazy implementation; supports GitHub Flavored Markdown |
+| `className` | `string` | no | none | `MarkdownRenderer`, which puts it on the markdown container as Tailwind classes |
+
+Every other member is inherited from `BaseSchema`; this renderer reads none of
+them.
+
+> ⚠️ **`content`: what the contract says and what the runtime does.** The type
+> declares `content` REQUIRED and the component's `inputs` manifest declares it
+> `required: true` — but the renderer reads `schema.content || ''`, so a node
+> that omits it renders empty instead of failing. Both statements are true, and
+> neither is widened or narrowed here.
+
+`sanitize` and `components` appear on the interface only as ADR-0049 retirement
+tombstones (`?: never`, objectui#6972) — they are not authorable members and
+nothing reads them. Sanitization is unconditional: there is no authored spelling
+that turns it off.
 
 ## Supported Markdown Features
 
diff --git a/scripts/check-doc-snippet-types.mjs b/scripts/check-doc-snippet-types.mjs
index 8d41e80e81..ab19b74bf6 100644
--- a/scripts/check-doc-snippet-types.mjs
+++ b/scripts/check-doc-snippet-types.mjs
@@ -779,8 +779,6 @@ const UNGATED_DOCS = {
     '2 undefined-name diagnostic(s) — blocks continue an earlier block, or use ambient names the page never defines; 1 unresolved-module diagnostic(s)',
   'packages/plugin-map/README.md':
     '1 parse diagnostic(s) — blocks fenced `ts` that are bare object literals or elided bodies; 1 undefined-name diagnostic(s) — blocks continue an earlier block, or use ambient names the page never defines; plus TS2322x1 — candidate real defects, un-triaged',
-  'packages/plugin-markdown/README.md':
-    '2 parse diagnostic(s) — blocks fenced `ts` that are bare object literals or elided bodies',
 };
 
 // ── Fence scanning ───────────────────────────────────────────────────────────