Decide markdown report schema naming for boards versus faces

Problem

Settle the frontmatter and embed naming for markdown report objects before M3 ships, so report syntax, reusable grouped layouts, and docs use stable terms instead of mixing face and board concepts. The decision also needs an explicit documentation outcome so user-facing authoring guidance, examples, and reference material all use the same vocabulary.

Context

Dataface currently uses Face as the top-level internal type in dataface/core/compile/types.py, and render/serve entry points still talk about face files (render_face_svg(), _render_face_file(), compile_file()). At the same time, a lot of user-facing docs already lean on board language, especially in docs/docs/boards/implementation.md, which describes authored layouts and nested boards as the main mental model.

The markdown report feature adds a new place where naming matters because the user-facing surface will need explicit terms for:

• the whole rendered page/report
• reusable grouped embeds inside that page
• the inline embed syntax for charts versus grouped layouts

If that vocabulary is not decided up front, the markdown feature will hard-code confusing mixed terms into frontmatter, docs, error messages, starter files, and future integrations.

Relevant anchors:

• dataface/core/compile/types.py - internal Face type and nested face behavior
• dataface/core/render/faces.py - render path still uses face terminology
• docs/docs/boards/implementation.md - user-facing board terminology and mental model
• ai_notes/features/MARKDOWN_FRONTMATTER_REPORTS.md - current exploration of .md + frontmatter + embeds

Constraints:

• Prefer a user-facing term that reads naturally in authoring and docs.
• Avoid a repo-wide rename of internal classes unless it pays for itself.
• Keep the markdown contract explicit and minimal for M3.
• The outcome must be stable enough for docs, examples, validation errors, and future integrations.

Possible Solutions

Option A - Use face everywhere

Keep user-facing markdown/frontmatter terms aligned with current internals, e.g. grouped embeds and docs continue to talk about faces.

• Pros: least conceptual drift from current code.
• Cons: reads awkwardly in authoring, fights existing board-oriented docs, and makes report syntax feel internal rather than product-facing.

Option B - Recommended: keep Face internal, use board for authored grouped layouts

Treat Face as the implementation type, but standardize user-facing authoring/docs around boards. In markdown/report mode that likely means:

• charts: for single visual units
• boards: for named grouped layouts
• {{ chart id }} and {{ board id }} for embeds

The top-level .md file can still compile into the internal Face model without exposing that implementation term in authoring.

• Pros: aligns with current docs, reads naturally, and avoids a large internal rename.
• Cons: introduces a deliberate user-facing/internal terminology split that docs and errors need to explain cleanly.

Option C - Rename internals from Face to Board

Push the terminology change all the way through Python types, render functions, docs, and CLI references.

• Pros: one term everywhere.
• Cons: broad churn, rename risk, and little user value relative to the amount of code/doc movement.

Plan

1. Inventory where face versus board already appears across core types, docs, examples, and future markdown/report proposals.
2. Decide the canonical user-facing authoring terms for markdown reports, grouped embeds, docs, and validation errors.
3. Write down explicit rules for what stays internal versus what becomes external product vocabulary.
4. Update the markdown-report task and related starter/init/docs tasks so they inherit the same vocabulary.
5. Identify the minimum docs/reference updates required once the naming decision is made, including authoring guides and starter examples.

Implementation Progress

QA Exploration

N/A - terminology/design decision task, not a browser flow.

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

Review Feedback

• [ ] Review cleared