Oleg Isonen
1b48716ff4
## Summary - Document how people create, connect, edit, validate, and publish MDX-backed Content Blocks. - Document the complete MCP workflow, including scoped expression sources, frontmatter updates, diagnostics, conflicts, and disconnect behavior. - Add two focused screenshots for the human workflow. - Fix issues found by a low-reasoning MCP agent while executing every documented workflow. Ref #6182 ## Implementation notes - Connection confirmation uses the public `confirmReplacement` field because `confirm` is reserved as a hidden transport field. - MCP edits frontmatter with `update-content-block-frontmatter`; materialized MDX elements are not persistent targets for generic instance mutation tools. - Reload now intentionally discards a conflicted local source and accepts the Asset's latest storage revision before an edit is reapplied. - Generated MCP documentation and runtime contracts are updated from their source files. ## Checklist - [x] Document the human MDX Content Block workflow. - [x] Document MCP discovery, connection, editing, diagnostics, frontmatter, dynamic sources, conflicts, and disconnection. - [x] Add only screenshots that clarify otherwise hard-to-describe UI steps. - [x] Test every documented MDX capability through the local MCP CLI with a low-reasoning agent. - [x] Reproduce and fix the replacement-confirmation schema mismatch. - [x] Reproduce and fix persistent-session conflict reload and reapply. - [x] Add regression tests that failed before each product fix and pass afterward. - [x] Regenerate runtime contracts and generated MCP documentation. - [x] Review authoritative `docs/` content and update affected pages. - [x] Run affected tests, typechecks, formatting, and diff checks. ## Verification - Project Build: 208 affected tests passed. - Content Engine Asset session: 8 tests passed. - CLI documentation tests: 14 tests passed. - MCP docs generator: 3 tests passed. - Content Engine, Project Build, CLI, and MCP docs typechecks passed. - `pnpm oxfmt --check` passed. - `git diff --check` passed. - Low-reasoning MCP evaluation passed all documented workflows, including a real two-client revision conflict, reload, reapply, and final saved inspection.
🧩 Core Components
Layout
{% content-ref url="element.md" %} element.md {% endcontent-ref %}
{% content-ref url="slot.md" %} slot.md {% endcontent-ref %}
{% content-ref url="separator.md" %} separator.md {% endcontent-ref %}
Typography
{% content-ref url="text.md" %} text.md {% endcontent-ref %}
{% content-ref url="heading.md" %} heading.md {% endcontent-ref %}
{% content-ref url="paragraph.md" %} paragraph.md {% endcontent-ref %}
{% content-ref url="inline-text.md" %} inline-text.md {% endcontent-ref %}
{% content-ref url="blockquote.md" %} blockquote.md {% endcontent-ref %}
{% content-ref url="code-text.md" %} code-text.md {% endcontent-ref %}
Navigation
{% content-ref url="link.md" %} link.md {% endcontent-ref %}
{% content-ref url="button.md" %} button.md {% endcontent-ref %}
Media
{% content-ref url="image.md" %} image.md {% endcontent-ref %}
{% content-ref url="video.md" %} video.md {% endcontent-ref %}
{% content-ref url="vimeo.md" %} vimeo.md {% endcontent-ref %}
{% content-ref url="vimeo-background-video.md" %} vimeo-background-video.md {% endcontent-ref %}
{% content-ref url="youtube.md" %} youtube.md {% endcontent-ref %}
Forms
{% content-ref url="form.md" %} form.md {% endcontent-ref %}
{% content-ref url="webhook-form.md" %} webhook-form.md {% endcontent-ref %}
{% content-ref url="input.md" %} input.md {% endcontent-ref %}
{% content-ref url="textarea.md" %} textarea.md {% endcontent-ref %}
{% content-ref url="label.md" %} label.md {% endcontent-ref %}
{% content-ref url="checkbox.md" %} checkbox.md {% endcontent-ref %}
{% content-ref url="radio-button.md" %} radio-button.md {% endcontent-ref %}
{% content-ref url="select.md" %} select.md {% endcontent-ref %}
Data
{% content-ref url="list.md" %} list.md {% endcontent-ref %}
{% content-ref url="collection.md" %} collection.md {% endcontent-ref %}
{% content-ref url="content-embed.md" %} content-embed.md {% endcontent-ref %}
{% content-ref url="content-block.md" %} content-block.md {% endcontent-ref %}
Embeds
{% content-ref url="html-embed.md" %} html-embed.md {% endcontent-ref %}
{% content-ref url="markdown-embed.md" %} markdown-embed.md {% endcontent-ref %}
Animation
{% content-ref url="animation-group.md" %} animation-group.md {% endcontent-ref %}
{% content-ref url="text-animation.md" %} text-animation.md {% endcontent-ref %}
{% content-ref url="video-animation.md" %} video-animation.md {% endcontent-ref %}
{% content-ref url="stagger-animation.md" %} stagger-animation.md {% endcontent-ref %}
Head / SEO
{% content-ref url="head-slot.md" %} head-slot.md {% endcontent-ref %}
{% content-ref url="json-ld.md" %} 🏷️ JSON-LD {% endcontent-ref %}
XML / Localization
{% content-ref url="xml-node.md" %} xml-node.md {% endcontent-ref %}
{% content-ref url="time.md" %} time.md {% endcontent-ref %}