Support markdown report pages in faces with frontmatter and chart board embeds

Problem

Add .md Dataface report pages under /faces with YAML frontmatter plus explicit chart and board embeds, translating markdown inputs into the same canonical face input/object shape the normal compiler already expects rather than introducing a separate markdown compiler or runtime. This also needs user-facing documentation so people understand when to use .md versus .yml, what embed syntax is supported, and how report pages fit into /faces.

Context

The current core pipeline assumes YAML face files:

• dataface/core/compile/compiler.py::compile_file() reads the file as text and treats it as YAML.
• dataface/cli/commands/render.py reads the target file directly and passes YAML content into the normal compiler.
• dataface/core/serve/server.py::_render_face_file() does the same for dft serve.
• dataface/core/compile/detect.py only recognizes .yml / .yaml Dataface files today.

At the same time, the repo already has most of the pieces needed for markdown report authoring:

• markdown content is already rendered inside content blocks
• tasks/frontmatter.py already has small frontmatter extraction helpers
• the VS Code extension has a temporary render-markdown-face.ts helper that turns markdown into a simple YAML face for preview
• ai_notes/features/MARKDOWN_FRONTMATTER_REPORTS.md already sketches the preferred architecture: parse .md, extract frontmatter/body, translate to canonical face shape, then reuse the existing compile/execute/render pipeline

The key decision for this task is architectural: markdown report files should be a thin source-format translation step into the normal face model, not a second markdown-specific compiler or runtime.

This task is blocked on the schema naming decision because the frontmatter contract and embed syntax should not hard-code unstable face versus board terminology.

Constraints:

• .md support must translate into the canonical face input/object shape.
• Avoid routing inline markdown embeds through mdsvg as a second composition engine.
• Start with explicit minimal embeds only.
• Detection changes also need to stay in sync with the VS Code extension if file classification rules change.
• Bug-risky parsing behavior requires focused tests and clear validation errors.

Possible Solutions

Option A - Treat markdown body as special content and let content rendering resolve embeds

Keep markdown as one big content block and teach the content path to understand embedded chart/board tokens.

• Pros: superficially small change.
• Cons: makes markdown rendering a second composition engine and tangles text layout with chart/board placement.

Option B - Recommended: translate .md into the canonical face model before normal compile/render

Parse frontmatter and markdown body, split the body into ordered text/embed blocks, and emit the equivalent face input structure (content chunks plus chart/board refs in rows, or the equivalent canonical layout shape). Then reuse the existing compile, execute, and render pipeline unchanged downstream.

• Pros: preserves one runtime model, keeps sizing/layout ownership in Dataface, and matches the current architectural direction.
• Cons: needs a small loader/translator layer and coordinated updates across compile/render/serve/detection.

Option C - Add a first-class markdown runtime/layout type

Create a new runtime path that renders markdown reports directly instead of translating them into the normal face model.

• Pros: could feel conceptually neat at first glance.
• Cons: duplicates runtime behavior, increases maintenance, and fights the repo's "normalize then trust the renderer" philosophy.

Plan

1. Finalize the user-facing contract after the schema naming task settles board/face vocabulary for grouped embeds.
2. Add a small markdown loader/translator in core that: - parses frontmatter - validates required Dataface sections - tokenizes markdown body into text blocks plus explicit embeds - emits the canonical face input/object shape for the existing compiler
3. Update compile/render/serve entry points so .md files under /faces resolve through that translation step rather than being treated as raw YAML.
4. Update file detection and any duplicated editor-side detection rules to recognize valid Dataface markdown report files.
5. Add focused tests first: - frontmatter parsing - embed parsing and unknown-id errors - .md compile/render integration through CLI and serve paths
6. Add docs/examples covering: - when to use .md versus .yml - supported embed syntax - the rule that markdown reports compile into the normal face model
7. Leave future fragment-render APIs and MkDocs/plugin adapters as follow-on work, not part of the M3 core implementation.

Implementation Progress

QA Exploration

QA should include at least one real dft serve smoke test against markdown report pages so route resolution, variable handling, and render output are exercised end-to-end. Browser exploration is likely useful once the feature exists because this changes a user-facing served surface.

• [ ] QA exploration completed (or N/A for non-UI tasks)

Review Feedback

• [ ] Review cleared