zio Companion Examples
A page's runnable examples come in two forms. Inline mdoc blocks compile as part of the page and
need nothing here. Embedded files — pulled in with mdoc:embed:<path> or SourceFile.print from a
tutorial's "Putting It Together" or a reference page's "Running the Examples" — are real .scala files
that must exist on disk before mdoc runs, in their own sbt build.
Delegate the build to the docs-examples-builder agent with the Task tool — it must NOT share
your conversation, so its only knowledge of the page is what you tell it. The agent already knows the
decoupled sbt build topology, file templates, and the compile/lint/self-check procedure; give it only
the page-specific parameters:
Task(
description: "Build companion examples for <page-id>",
subagent_type: "documentation:docs-examples-builder",
prompt: "Page: <path to the page being documented>
Embeds this page declares: <every mdoc:embed:<path> or SourceFile.print path it names,
each of which must end up at exactly that path>
Requirement: every example must print meaningful output when run, not just compile."
)
Ordering
Commission the examples before mdoc verification. An mdoc:embed:<path> block fails outright when
the file it names is absent, so a page that embeds examples cannot pass mdoc until they exist.
For a module reference, prefer ONE module-level example set that exercises several types together over one set per type — the cross-type workflow is what a module page is for.
Verifying what came back
The delegation is done when every embedded path exists and the examples leaf compiles and runs. Check:
- each
mdoc:embed:<path>orSourceFile.printcall in the page resolves to a real file, - the example code traces to the page's own blocks — nothing invented beyond glue,
- the leaf built and each example ran, rather than only compiling.
If mdoc later reports an unresolved embed, the file is missing or at the wrong path — fix the path or re-commission it rather than deleting the embed to make the page compile.