DX roadmap: simpler common path without losing Leadtype's supply-chain model

[KayleeWilliams]

Context

A DX comparison with Blume highlights a useful split:

• Blume has the stronger docs-site common path: filesystem-first navigation, very small configuration, an integrated CLI lifecycle, doctor, and skill descriptions that explicitly trigger for Markdown/MDX authoring.
• Leadtype has the stronger docs supply-chain and agent-consumption model: framework-independent content primitives, package-bundled version-matched docs, multi-repo acquisition and source ownership, rich generated agent surfaces, config-aware linting, scoring, and structured CLI output.

The goal is to take the best DX lessons from Blume without turning Leadtype into a rendered theme/framework or hiding the controls needed by c15t-scale multi-repo documentation.

Principles

1. The common path should be small and progressive; advanced controls remain available.
2. Existing configs keep working while one canonical format becomes the documented path.
3. Human docs and agent artifacts must consume one resolved content/navigation graph.
4. Every important operation should be explainable to both humans and agents.
5. Leadtype continues to own the content pipeline and integration primitives, not rendered UI.

Workstreams

Immediate agent-authoring DX

• Make the Leadtype skill activate for docs authoring and review #150 — Make the Leadtype skill activate for docs authoring and review

Configuration and defaults

• Introduce a canonical config API with backward-compatible normalization #151 — Introduce a canonical config API with backward-compatible normalization
• Make the common single-repo config minimal with derived defaults #152 — Make the common single-repo config minimal with derived defaults
• Add first-class git source groups for multi-repo docs configs #153 — Add first-class git source groups for multi-repo docs configs

Runtime parity and explainability

• Make project config the source of truth for runtime docs loading #154 — Make project config the source of truth for runtime docs loading
• Add leadtype doctor to explain resolved config and project health #155 — Add leadtype doctor to explain resolved config and project health

Large-site authoring

• Reduce navigation config churn for large and repeated docs trees #156 — Reduce navigation config churn for large and repeated docs trees

Suggested sequencing

1. Ship Make the Leadtype skill activate for docs authoring and review #150 first; it is small and directly improves docs work today.
2. Define the resolved-config boundary in Introduce a canonical config API with backward-compatible normalization #151, with Make the common single-repo config minimal with derived defaults #152 and Add leadtype doctor to explain resolved config and project health #155 informing what inference/provenance it must expose.
3. Build Add first-class git source groups for multi-repo docs configs #153 and Make project config the source of truth for runtime docs loading #154 on the resolved project/source graph.
4. Use c15t and Leadtype public docs as dogfood throughout.
5. Land Reduce navigation config churn for large and repeated docs trees #156 once the canonical navigation representation and diagnostics are stable.

Success criteria

• A new local project reaches useful generated output with minimal configuration.
• Existing advanced and multi-repo projects migrate incrementally, without a flag-day rewrite.
• The Leadtype skill activates on ordinary docs-authoring prompts in Leadtype repositories.
• Public docs apps no longer duplicate project/source/navigation state between build-time and runtime code.
• A human or coding agent can inspect the resolved project and understand exactly where each value came from.

[pullfrog]

  ^{｜ Build this ➔ ｜ Make a plan ➔}

[coderabbitai]

🔗 Related PRs

#59 - Restructure docs for agent-ready site workflow [merged]
#65 - Docs DX + agent-readability: init command, Search & AI/Concepts sections, example modernization [merged]
#76 - Agent surface: MCP, llms.txt/robots/JSON-LD, agent-skills, GEO + score, and a restructured config [merged]
#99 - Bring-your-own-pages agent artifacts, capability-led docs IA, and an audit script [merged]
#137 - Position lint as a headline and pass our own snippet typechecking [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!