docs: publish content-type contracts for solution guide, learning unit, curriculum hub, and router/landing

[claude]

Requested by Matthew Cruz · Slack thread

What

Publishes the content-type contracts introduced by the Paved Paths plan (Option C, slice 2 — projects/docs-improver/plans/option-c-paved-paths.md in ethereum-optimism/solutions). Five new pages under docs/public-docs/op-stack/contribute/:

• choose-a-content-type — maintainer-facing decision tables for the confusable pairs (how-to vs. tutorial vs. solution guide; explanation vs. learning unit) plus the composition contract for how the new types extend the diataxis: frontmatter taxonomy.
• solution-guide, learning-unit, curriculum-hub, router-landing — one published spec per type, each with purpose, tone, required components, title grammar, a literal copy-paste template, and exemplar links.

Before / After

• Before: the page types the Paved Paths plan introduces (solution guides, the learn track's units, per-feature hubs, the persona router) exist only as plan prose — every future PR of these types would re-argue shape, tone, and frontmatter from scratch.
• After: each type is a published contract with a copy-paste template; reviews cite the spec instead of re-arguing it. The first solution guide (Option C slice 3) is written against, and reviewed against, solution-guide's template.

Taxonomy: extension, not fork

• The four diataxis: quadrant values from the landed 292-page sweep (docs: add diataxis tags across all sections #21830) are unchanged; the new types never appear as diataxis: values.
• Composed types are declared with an optional content-type: frontmatter key carried alongside diataxis: (Cloudflare's published-content-type pattern). One sanctioned exception is documented: a pure router carries content-type: router-landing and no diataxis: key (nothing on it to classify) — consistent with the sweep, which left the root router untagged.
• keywords.config.yaml delete-or-align decision (recorded here per the plan's risk item): the new types are not added to it — frontmatter is the only declaration surface. Recommend deleting keywords.config.yaml as a separate follow-up; it is a dead second taxonomy.

docs.json / merge order

• The docs.json hunk adds a Contribute group at the end of the OP Stack tab containing only these five pages. Synced with develop after docs: add canonical-home content guide and ThirdPartyContent component #21841 merged; the five pages now sit in the merged Contribute group (after content-guide).
• In-page links to /op-stack/contribute/content-guide now resolve in-tree (that page shipped in docs: add canonical-home content guide and ThirdPartyContent component #21841).

Checks run

• docs.json parses; all five nav entries map to existing files.
• Every internal link on the new pages resolves against develop (scripted check), including the content-guide links (shipped in docs: add canonical-home content guide and ThirdPartyContent component #21841).
• External exemplar URLs are restricted to ones already cited by the merged program plans and docs: add canonical-home content guide and ThirdPartyContent component #21841 (live fetch unavailable in this environment).

Follow-ups (out of scope here)

• Verifier-subagent checklist amendment ("check new page types against their published spec") — the verifier is defined in the not-yet-ratified agent-upgrades plan (ethereum-optimism/solutions PR Remove colons from filenames of artifacts #953); amend once ratified.
• keywords.config.yaml deletion (decision recorded above).

Reviewer checklist

• Each spec's required-components list is concrete enough to review a page against
• The decision tables settle the two confusable pairs without ambiguity
• The content-type: contract reads as an extension of the diataxis: sweep, not a fork
• Each ## Template block works as a copy-paste scaffold

Tracks ethereum-optimism/solutions#961
Part of the docs-improver program — see projects/docs-improver/README.md in ethereum-optimism/solutions. Skill-template mirror PR in ethereum-optimism/solutions accompanies this one.

🤖 Drafted by the docs-improver agent — review before merge.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EBBBR8m2V8LjzMvuG7Go2L

---

Generated by Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Optimism-Docs	🟢 Ready	View Preview	Jul 16, 2026, 7:42 AM

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Optimism-Docs	🟡 Building	–	Jul 16, 2026, 7:41 AM

[claude]

synced with develop after #21841 merged; docs.json hunks folded into the merged Contribute group.

[claude]

Merged origin/develop (post-#21846) — resolved the docs.json Contribute-group conflict to one group ordered content-guide, link-policy, then this branch's five pages; nav/redirect/link-policy linters all pass (no new link-policy findings). New head: ab4b413.