Introduce a canonical config API with backward-compatible normalization

[KayleeWilliams]

Problem

DocsConfig has grown from a local MDX-generation config into the project model for identity, source acquisition, navigation, feeds, redirects, agent surfaces, and multi-repo orchestration. The capabilities are valuable, but the authoring API now exposes historical naming and overlapping concepts:

• defineDocsConfig is used for both source-owned docs.config.ts and site/orchestration leadtype.config.ts;
• top-level frontmatterSchema becomes collection-level schema;
• collection prefix is specifically a public route prefix;
• sourceConfig means “inherit selected config from the source repository”;
• groups remains a legacy navigation fallback beside canonical navigation;
• the type permits combinations that are rejected only when the config is loaded.

This makes advanced configs harder to read and gives agents more semantically similar options to choose between. We should establish one canonical vocabulary without breaking existing users.

Proposal

Introduce a new canonical authoring shape and normalize both the existing and new shapes into one internal ResolvedDocsConfig.

Possible vocabulary to validate during design:

• defineLeadtypeConfig for project/site orchestration while retaining defineDocsConfig for source-owned docs config;
• routePrefix instead of collection prefix;
• frontmatterSchema at both top level and collection level;
• inheritConfig instead of sourceConfig;
• navigation as the canonical IA field, with groups retained only as legacy taxonomy/fallback.

The exact names should be settled with representative configs before implementation. The important architectural constraint is that generation, linting, scoring, syncing, framework adapters, and diagnostics all consume the same resolved shape.

Compatibility strategy

This should be a gradual migration:

1. Add the new syntax without removing the old syntax.
2. Normalize both at config load into one canonical internal representation.
3. Add TypeScript @deprecated annotations only to fields that have a true replacement.
4. Emit one actionable deprecation warning per config load in CLI flows.
5. Make leadtype init, documentation, and examples emit only the new syntax.
6. Reject old and new equivalents supplied together instead of silently choosing precedence.
7. Keep legacy syntax working through the next major release; do not remove it before 1.0.

Convenience shorthands are not deprecations. For example, agents.mcp: true can coexist with the advanced object form { enabled: true, ... }.

Resolved config requirements

The normalizer should:

• produce a serializable resolved representation where possible;
• preserve source ownership and inheritance provenance for diagnostics;
• validate single-source versus multi-source combinations centrally;
• make conflict errors name both fields and show the canonical replacement;
• be shared by every command and runtime helper rather than reimplemented per subsystem.

Acceptance criteria

• A short design note compares the existing API and proposed canonical API against local, remote, and multi-repo examples.
• Existing configs remain type-valid and operational.
• Replaced fields have IDE-visible @deprecated guidance and CLI migration warnings.
• Ambiguous old-plus-new combinations fail with actionable errors.
• One normalizer produces the config consumed by generate, sync, lint, score, and runtime adapters.
• New docs, examples, and leadtype init use only the canonical syntax.
• Tests prove equivalent legacy and canonical configs resolve identically.
• A removal policy is documented, with no removal before the next major version.

[pullfrog]

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

[coderabbitai]

🔗 Related PRs

#56 - Add config-driven docs navigation [merged]
#59 - Restructure docs for agent-ready site workflow [merged]
#76 - Agent surface: MCP, llms.txt/robots/JSON-LD, agent-skills, GEO + score, and a restructured config [merged]
#79 - Add source config inheritance for remote docs [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!