Phase 6 of S06's rollout plan is listed as "own spec". This issue is for writing that spec, not for the implementation. Use the /spec-extension skill; mise run new-doc-number spec gives the next free number.
What the phase is
Documentation for the second audience S06's introduction names — the integrator, "the operator is the entire gap; the integrator is second" — covering the extension points a wrapper distribution builds against.
The shape: curated, deliberately not complete
R14 is explicit that this must not be a full autodoc pass. Its reasoning: a reference over 194 modules is high noise and low value, because nobody imports mdd except wrapper authors, and they need roughly five things:
MirrorBackend- the converter registry (S15)
- the config schema
- typed frontmatter (S40)
- the IR entry points (S28)
Generate over that symbol list and nothing else. In R14's words: completeness here is a cost, not a benefit. This is the same demotion logic S06 applies to the design record — publishing everything makes the useful part harder to find.
Tooling
Extraction layer is Griffe, which walks the AST and produces a structured model of the package including annotations. Renderer is griffe2md (Markdown from the same data via Jinja templates) or Griffonner (template-first generator over Griffe, for arbitrary output). Explicitly not mkdocstrings-python, which renders HTML for MkDocs — the wrong stack here. And explicitly not pydoc.
Questions the spec will need to answer
- The exact symbol list, and where it lives — a hand-maintained allow-list is the obvious approach, and its staleness mode (a symbol gets renamed and drops silently out of the reference) needs a gate.
- Whether output goes to
docs/reference/ alongside Phase 3's CLI pages or to a sibling directory, and whether it shares Phase 3's drift gate. The same committed-plus-drift-gate reasoning applies, so it probably reuses that machinery rather than inventing a second mechanism.
- What stability promise, if any, the published surface carries. This is the substantive question: documenting a symbol as an extension point is close to promising not to break it, and
mdd installs from git main with no released version, so there is no deprecation window to point at. S06's requirement list mentions "stability expectations" as something the integrator wants.
- Whether S23's
register_skill_root belongs in the list — it is an extension point a wrapper uses, and S06's open question 4 already leans on it.
- Sequencing against Phase 3, which builds the committed-generated-reference pattern this phase would reuse.
Note on priority
Worth weighing against the other phases: this one is small, but it only pays off once there is a wrapper author to serve. That audience exists (the private distribution composes this CLI, per CLAUDE.md's note about --repo-root/--dispatcher), so it is not hypothetical — but it is one known consumer, and R14's own argument against generalising for zero-to-few consumers is the reason S06 resolved its open question 4 the way it did.
Phase 6 of S06's rollout plan is listed as "own spec". This issue is for writing that spec, not for the implementation. Use the
/spec-extensionskill;mise run new-doc-number specgives the next free number.What the phase is
Documentation for the second audience S06's introduction names — the integrator, "the operator is the entire gap; the integrator is second" — covering the extension points a wrapper distribution builds against.
The shape: curated, deliberately not complete
R14 is explicit that this must not be a full autodoc pass. Its reasoning: a reference over 194 modules is high noise and low value, because nobody imports
mddexcept wrapper authors, and they need roughly five things:MirrorBackendGenerate over that symbol list and nothing else. In R14's words: completeness here is a cost, not a benefit. This is the same demotion logic S06 applies to the design record — publishing everything makes the useful part harder to find.
Tooling
Extraction layer is Griffe, which walks the AST and produces a structured model of the package including annotations. Renderer is
griffe2md(Markdown from the same data via Jinja templates) or Griffonner (template-first generator over Griffe, for arbitrary output). Explicitly notmkdocstrings-python, which renders HTML for MkDocs — the wrong stack here. And explicitly notpydoc.Questions the spec will need to answer
docs/reference/alongside Phase 3's CLI pages or to a sibling directory, and whether it shares Phase 3's drift gate. The same committed-plus-drift-gate reasoning applies, so it probably reuses that machinery rather than inventing a second mechanism.mddinstalls from gitmainwith no released version, so there is no deprecation window to point at. S06's requirement list mentions "stability expectations" as something the integrator wants.register_skill_rootbelongs in the list — it is an extension point a wrapper uses, and S06's open question 4 already leans on it.Note on priority
Worth weighing against the other phases: this one is small, but it only pays off once there is a wrapper author to serve. That audience exists (the private distribution composes this CLI, per
CLAUDE.md's note about--repo-root/--dispatcher), so it is not hypothetical — but it is one known consumer, and R14's own argument against generalising for zero-to-few consumers is the reason S06 resolved its open question 4 the way it did.