Provide a CI example for validating runnable Markdown snippets

[adrianbrowning]

Parent

#10

What to build

Provide a CI-ready example for extracting selected Markdown code blocks and validating them as runnable examples. Consumers should be able to adapt it to the language-specific test or lint command used by their project.

Acceptance criteria

• An example extracts only intentionally runnable blocks into an isolated workspace.
• The example invokes a configurable validation command against the extracted files.
• A validation failure produces a non-zero CI exit status and identifies the failing example.
• Temporary generated files are isolated from source files and cleaned up safely.
• Documentation explains the metadata convention for marking runnable snippets.

Blocked by

• Harden mdcode operations for untrusted Markdown and agent execution #7

[adrianbrowning]

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Provide a copyable CI recipe for extracting intentionally runnable snippets into an isolated workspace and validating them.

Current behavior:
The run command writes one temporary file per block and invokes a caller-provided shell command, but it does not supply a reusable extracted-workspace CI example. No public metadata convention identifies which Markdown snippets are intended to be runnable.

Desired behavior:
Consumers can mark intentionally runnable code fences with runnable=true, extract only those fences into a newly created isolated workspace, and invoke a trusted, configurable validation command against that workspace. Validation failures fail CI and identify the affected snippets or generated files. Temporary output is reliably cleaned up.

Key interfaces:

• Runnable metadata convention — runnable=true selects only code blocks intended for execution or validation.
• Isolated workspace — create a fresh temporary output directory outside source files, extract selected blocks there, and clean it up on success or failure.
• Validation command — accept a consumer-supplied command as trusted CI configuration; Markdown metadata must not provide a command to run.
• Diagnostics — report generated file paths and validation failures so a consumer can trace failures back to the source Markdown blocks.
• CI examples — provide local-shell and GitHub Actions recipes that can be adapted to language-specific lint or test commands.

Acceptance criteria:

• A documented example selects only runnable=true blocks.
• It extracts selected blocks into a newly created isolated workspace.
• It runs a configurable, trusted validation command against the extracted files.
• Validation failures return a non-zero status and identify the failing generated file or block.
• The temporary workspace is cleaned up safely after success and failure.
• Documentation explains the runnable=true convention and trust boundary.
• Tests cover selection, successful validation, validation failure, and cleanup.

Out of scope:

• Treating all code fences as independently runnable by default.
• Type-checking arbitrary snippets or providing editor diagnostics.
• Executing a command specified by Markdown metadata.
• Release gating, which is issue Gate package releases on mdcode documentation and example checks #13.

Verification status:
Confirmed: current run behavior is per-block and console-oriented; no extracted-workspace CI example or runnable metadata convention exists. This issue is blocked by #7.