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

docs/public-docs/docs.json

@@ -2422,7 +2422,12 @@
             "group": "Contribute",
             "pages": [
               "/op-stack/contribute/content-guide",
-              "/op-stack/contribute/link-policy"
+              "/op-stack/contribute/link-policy",
+              "/op-stack/contribute/choose-a-content-type",
+              "/op-stack/contribute/solution-guide",
+              "/op-stack/contribute/learning-unit",
+              "/op-stack/contribute/curriculum-hub",
+              "/op-stack/contribute/router-landing"
             ]
           }
         ]

docs/public-docs/op-stack/contribute/choose-a-content-type.mdx

@@ -0,0 +1,123 @@
+---
+title: Choose a content type
+description: A maintainer-facing decision table for picking the right content type, and how the composed types extend the diataxis frontmatter taxonomy.
+diataxis: reference
+---
+
+This page is for docs maintainers and contributors, not readers. It settles
+the two questions that come up in almost every content pull request — "which
+kind of page am I writing?" and "which frontmatter does it carry?" — by
+decision table, so the answer is cited rather than re-argued per PR. The
+pattern follows Cloudflare's maintainer-facing content-type selection page in
+its [documentation content strategy](https://developers.cloudflare.com/style-guide/documentation-content-strategy/).
+
+Before choosing a type, check the
+[content guide](/op-stack/contribute/content-guide) that the content belongs
+on docs.optimism.io at all.
+
+## The taxonomy: four quadrants, four compositions
+
+Every page on docs.optimism.io carries a `diataxis:` frontmatter key with one
+of the four [Diátaxis](https://diataxis.fr/) quadrant values — `tutorial`,
+`how-to`, `reference`, or `explanation`. That taxonomy is complete and does
+not grow: the composed types below are **compositions of the quadrants, not
+new quadrants**, and they never appear as `diataxis:` values.
+
+A composed type is declared with a second, optional frontmatter key,
+`content-type:`, carried *alongside* `diataxis:`. It takes exactly four
+values, one per published spec:
+
+| Composed type | `content-type:` | `diataxis:` | What the composition is |
+| --- | --- | --- | --- |
+| [Solution guide](/op-stack/contribute/solution-guide) | `solution-guide` | `how-to` | A goal-scoped how-to at journey altitude: it sequences existing pages across quadrants and adds only the connective decision logic |
+| [Learning unit](/op-stack/contribute/learning-unit) | `learning-unit` | The underlying page's quadrant (usually `explanation`; `tutorial` for hands-on stops) | A thin sequencing layer over one existing page inside an ordered track |
+| [Curriculum hub](/op-stack/contribute/curriculum-hub) | `curriculum-hub` | `explanation` | An oriented index that composes all four quadrants for one feature under one sidebar node |
+| [Router/landing](/op-stack/contribute/router-landing) | `router-landing` | Omitted — see below | Pure navigation: the page only routes readers to pages in the quadrants |
+
+Rules that keep this an extension rather than a fork:
+
+*   **`content-type:` never replaces `diataxis:`.** Every page that documents,
+    instructs, or explains anything keeps its quadrant tag. The one sanctioned
+    omission is `content-type: router-landing`: a pure router contains no
+    documentation mode of its own to classify, so it carries `content-type:`
+    and no `diataxis:` key. If a router grows explanatory or instructional
+    content, it is no longer a router — reclassify it.
+*   **Only these four `content-type:` values exist.** Proposing a fifth means
+    amending this page and publishing a spec for it, through normal docs
+    review.
+*   **Pages of the four base types don't carry `content-type:` at all.** An
+    ordinary how-to is just `diataxis: how-to`.
+*   **`keywords.config.yaml` is not extended.** The composed types are
+    declared only in page frontmatter, per the rows above.
+
+## How-to guide vs. tutorial vs. solution guide
+
+These three are confusable because all three are action-oriented. The
+distinctions are the starting state, the scope, and who owns the steps.
+
+| Question | How-to guide | Tutorial | Solution guide |
+| --- | --- | --- | --- |
+| What state does the reader start in? | A working environment, already set up | A clean machine (or close to it) — setup is part of the page | A working system, plus a goal that spans components |
+| How wide is the scope? | One discrete task on one component | One end-to-end build, environment setup included | One goal across multiple components, often multiple documentation properties |
+| Who owns the steps? | The page owns its steps | The page owns its steps | The page **derives**: each stop links an existing page and states what to extract; the page adds only decision logic |
+| What does it end with? | Verification of the task | Verification of the whole working state, then cleanup | Verification of the outcome, then curated exits |
+| Frontmatter | `diataxis: how-to` | `diataxis: tutorial` | `diataxis: how-to` + `content-type: solution-guide` |
+
+Quick tests:
+
+*   If the page must install or configure the environment before the real
+    work starts, it's a **tutorial**.
+*   If the page's steps are its own — copy-pasteable commands the reader
+    executes on one component — it's a **how-to guide**.
+*   If the page's main job is sequencing *other* pages toward a goal and
+    deciding between options along the way, it's a **solution guide**. A
+    solution guide that starts restating the steps of the pages it links is
+    violating the [dual-sourcing ban](/op-stack/contribute/content-guide#link-dont-restate-the-dual-sourcing-ban)
+    — cut the restatement and link.
+
+Exemplars: [Configure the batcher](/chain-operators/guides/configuration/batcher)
+(how-to at configuration-guide depth);
+[Bridging your ERC-20 token](/app-developers/tutorials/bridging/cross-dom-bridge-erc20)
+(tutorial); the first solution guide ships with the Use Cases section — until
+it lands, the [solution guide spec](/op-stack/contribute/solution-guide)
+carries the template.
+
+## Explanation vs. learning unit
+
+Both are understanding-oriented. The distinction is who the reader is and
+what the page may assume.
+
+| Question | Explanation | Learning unit |
+| --- | --- | --- |
+| Who arrives? | Anyone, in any order, usually from search or a cross-link | A learner progressing through an ordered track or curriculum hub |
+| What may it assume? | Only what it states in its own intro | Everything covered by the previous stops in its track |
+| Who owns the content? | The page owns its conceptual material | The unit **frames** existing material: it adds sequencing context (what you now know, what this stop adds, where to go next) and links, never forks |
+| Frontmatter | `diataxis: explanation` | The underlying page's quadrant + `content-type: learning-unit` |
+
+Quick tests:
+
+*   If removing the page from its nav group would leave it fully
+    comprehensible, it's an **explanation**.
+*   If the page opens with "in the previous stop…" or only makes sense at
+    position N of a sequence, it's a **learning unit**.
+*   If you're about to *copy* an explanation into a track so you can reorder
+    it — stop. Learning units link and frame; they never duplicate. Add a
+    framing header to the existing page instead (see the
+    [learning unit spec](/op-stack/contribute/learning-unit)).
+
+Exemplars: [The OP Stack](/op-stack/introduction/op-stack) and the
+[fault proofs explainer](/op-stack/fault-proofs/explainer) (explanations that
+would gain learning-unit framing inside a track without being rewritten).
+
+## Next steps
+
+*   Read the type spec before writing the page:
+    [solution guide](/op-stack/contribute/solution-guide),
+    [learning unit](/op-stack/contribute/learning-unit),
+    [curriculum hub](/op-stack/contribute/curriculum-hub),
+    [router/landing](/op-stack/contribute/router-landing).
+*   For the four base quadrants, the
+    [style guide's content types section](https://github.com/ethereum-optimism/optimism/blob/develop/docs/public-docs/STYLE_GUIDE.md#content-types)
+    remains the reference.
+*   For what belongs on the site at all, see the
+    [content guide](/op-stack/contribute/content-guide).

docs/public-docs/op-stack/contribute/curriculum-hub.mdx

@@ -0,0 +1,141 @@
+---
+title: "Content type: curriculum hub"
+description: The published contract for curriculum hubs — purpose, tone, required components, title grammar, and a copy-paste template.
+diataxis: reference
+---
+
+A **curriculum hub** gathers everything a reader needs to master one feature
+— fault proofs, interop — under a single sidebar node, ordered from gentle
+introduction to normative spec. It is the answer to "I want to actually
+understand X": one place, one reading order, all four documentation modes
+composed for one topic.
+
+This page is the contract for the type. A new curriculum hub is reviewed
+against it; cite the relevant section in review instead of re-arguing it.
+
+## Purpose
+
+*   Give each major feature **one front door** with a recommended reading
+    order, instead of pages scattered across nav groups.
+*   **Compose, don't rewrite**: the hub resequences existing pages and adds
+    at most a few short learning-unit pages where the sequence has a gap.
+*   Make the exits explicit: every hub ends at the **normative spec** (and
+    audits, where they exist) so depth-seekers are routed off-site on
+    purpose, never stranded.
+
+## Composition
+
+A curriculum hub composes all four quadrants for one feature: explanation
+(the gentle intro and deep dives), tutorial/how-to (the hands-on stops),
+reference (component and configuration pages), and the spec exit. The hub's
+index page carries `diataxis: explanation` (it orients the reader in the
+feature) plus `content-type: curriculum-hub`. Stops inside the hub keep
+their own quadrant values; new gap-filling stops follow the
+[learning unit contract](/op-stack/contribute/learning-unit).
+
+See [Choose a content type](/op-stack/contribute/choose-a-content-type) for
+how the composed types relate to the `diataxis:` taxonomy.
+
+## Tone
+
+*   The index page orients: what the feature is, why it matters, and how
+    the materials fit together — in a few short paragraphs, not an essay.
+*   Every listed stop gets a one-line reason ("read this to …"), written
+    for the learner deciding whether to click, not as a summary.
+*   Confidence about order, honesty about depth: say what is skippable and
+    what is normative.
+
+## Required components
+
+Every curriculum hub must have:
+
+1.  **One sidebar node**: the hub is a single nav group; a hub that spans
+    groups has failed its purpose.
+2.  **An index page** with frontmatter `title`, `description`,
+    `diataxis: explanation`, `content-type: curriculum-hub`, and
+    `last-reviewed: YYYY-MM-DD` (hubs are curated artifacts and enter the
+    review sweep on merge).
+3.  **An ordered path** on the index, in this shape (sections may be merged
+    or omitted only where the feature genuinely lacks the material):
+    *   `## Start here` — the gentle introduction.
+    *   `## Go deeper` — mechanism and architecture material.
+    *   `## Get hands-on` — the tutorials and how-tos, where they exist.
+    *   `## Economics and incentives` — where the feature has them.
+    *   `## The normative spec` — deep links into
+        [specs.optimism.io](https://specs.optimism.io/) on **current spec
+        paths** (never retired path generations), per the
+        [content guide](/op-stack/contribute/content-guide).
+    *   `## Audits and security` — where audits exist.
+4.  **One-line reasons** on every link.
+5.  **No duplicated content**: the hub links existing pages; a stop needing
+    rework gets an issue, not a fork. Gap-filling stops are new
+    [learning units](/op-stack/contribute/learning-unit), capped at a few
+    per hub.
+
+## Title grammar
+
+The hub's nav group and index title are the feature's plain name in sentence
+case: "Fault proofs", "Interoperability". No "hub", "curriculum", "guide to",
+or "learn" in the title — the shape is visible from the sidebar; the name
+should match what readers search for.
+
+## Template
+
+Copy this template for a new hub's index page:
+
+```mdx
+---
+title: <Feature name>
+description: <One sentence: what the feature is and what this hub covers.>
+diataxis: explanation
+content-type: curriculum-hub
+last-reviewed: <YYYY-MM-DD>
+---
+
+<Two or three short paragraphs: what <feature> is, why it matters to this
+audience, and how the materials below fit together.>
+
+## Start here
+
+*   [<Gentle introduction>](</path>) — read this first for the mental model.
+
+## Go deeper
+
+*   [<Mechanism page>](</path>) — <what it explains, one line>.
+*   [<Architecture page>](</path>) — <what it explains, one line>.
+
+## Get hands-on
+
+*   [<Tutorial or how-to>](</path>) — <what you'll build or do, one line>.
+
+## Economics and incentives
+
+*   [<Economics page>](</path>) — <what it covers, one line>.
+
+## The normative spec
+
+The definitive definition of <feature> behavior lives in the OP Stack
+specifications:
+
+*   [<Spec section title>](https://specs.optimism.io/<current-path>) —
+    <what it defines, one line>.
+
+## Audits and security
+
+*   [<Audit or security page>](</path>) — <what was audited or what the
+    security model is, one line>.
+```
+
+## Exemplars
+
+No hub is wired yet — fault proofs and interop are the first two planned.
+Calibrate against the raw material and the external pattern:
+
+*   The existing fault-proofs pages —
+    [explainer](/op-stack/fault-proofs/explainer),
+    [FP components](/op-stack/fault-proofs/fp-components),
+    [FP security](/op-stack/fault-proofs/fp-security) — the material a
+    fault-proofs hub resequences without rewriting.
+*   Arbitrum's [BoLD gentle introduction](https://docs.arbitrum.io/how-arbitrum-works/bold/gentle-introduction)
+    — the sidebar shape this type reproduces: gentle intro through deep
+    dive, economics, spec, and audits under one node.