From b7e450bb9cf9bd6a4398ed96d274da3ef5d3f7b3 Mon Sep 17 00:00:00 2001
From: Guillaume Tauzin <4648633+gtauzin@users.noreply.github.com>
Date: Sun, 29 Mar 2026 11:58:53 +0200
Subject: [PATCH] feat(template): group example gallery by Diataxis category

- Add category field to gallery metadata and group by tutorial/how-to
- Extract _build_gallery_cards helper and reuse in API examples
- Update examples page intro to describe grouped notebooks
- Update contribute.md notebook structure guidelines
- Create diataxis-notebook-writer skill with tutorial/how-to patterns
- Add companion notebook sections to tutorial and howto writer skills
- Add notebook classification to docs planner skill

Backported from stateful-y/sklearn-optuna#21 (91268db)
---
 .github/skills/diataxis-docs-planner/SKILL.md |   2 +
 .github/skills/diataxis-howto-writer/SKILL.md |  12 ++
 .../skills/diataxis-notebook-writer/SKILL.md  |  68 +++++++++
 .../references/howto-notebook.md              | 121 ++++++++++++++++
 .../references/tutorial-notebook.md           | 129 ++++++++++++++++++
 .../skills/diataxis-tutorial-writer/SKILL.md  |  12 ++
 .../skills/diataxis-docs-planner/SKILL.md     |   2 +
 .../skills/diataxis-howto-writer/SKILL.md     |  12 ++
 .../skills/diataxis-notebook-writer/SKILL.md  |  68 +++++++++
 .../references/howto-notebook.md              | 121 ++++++++++++++++
 .../references/tutorial-notebook.md           | 129 ++++++++++++++++++
 .../skills/diataxis-tutorial-writer/SKILL.md  |  12 ++
 template/docs/hooks.py.jinja                  |  54 +++++---
 .../docs/pages/how-to/contribute.md.jinja     |  54 +++++---
 ...de_examples %}examples.md{% endif %}.jinja |   2 +-
 .../hello.py.jinja                            |   1 +
 tests/test_docs_content.py                    |  11 ++
 tests/test_propagated_features.py             |  11 ++
 18 files changed, 780 insertions(+), 41 deletions(-)
 create mode 100644 .github/skills/diataxis-notebook-writer/SKILL.md
 create mode 100644 .github/skills/diataxis-notebook-writer/references/howto-notebook.md
 create mode 100644 .github/skills/diataxis-notebook-writer/references/tutorial-notebook.md
 create mode 100644 template/.github/skills/diataxis-notebook-writer/SKILL.md
 create mode 100644 template/.github/skills/diataxis-notebook-writer/references/howto-notebook.md
 create mode 100644 template/.github/skills/diataxis-notebook-writer/references/tutorial-notebook.md

diff --git a/.github/skills/diataxis-docs-planner/SKILL.md b/.github/skills/diataxis-docs-planner/SKILL.md
index 87f5828..729f8cc 100644
--- a/.github/skills/diataxis-docs-planner/SKILL.md
+++ b/.github/skills/diataxis-docs-planner/SKILL.md
@@ -49,6 +49,7 @@ Read all files in `docs/` and classify each page by quadrant using the compass:
 - For each page, note: file path, current title, actual quadrant, intended quadrant
 - Flag pages that mix quadrants (e.g., a "getting started" that is half tutorial, half reference)
 - Flag pages that are misclassified (e.g., an "explanation" page that is really a how-to)
+- Check `examples/` for marimo notebooks: classify each by quadrant using its `__gallery__` metadata `category` field and verify it matches the notebook content
 
 ### Step 3: Identify Gaps
 
@@ -89,6 +90,7 @@ Output a structured documentation plan:
    - How-to pages → `diataxis-howto-writer`
    - Reference pages → `diataxis-reference-writer`
    - Explanation pages → `diataxis-explanation-writer`
+   - Companion notebooks → `diataxis-notebook-writer`
 
 ## MkDocs Nav Patterns
 
diff --git a/.github/skills/diataxis-howto-writer/SKILL.md b/.github/skills/diataxis-howto-writer/SKILL.md
index 99d3c51..3daed51 100644
--- a/.github/skills/diataxis-howto-writer/SKILL.md
+++ b/.github/skills/diataxis-howto-writer/SKILL.md
@@ -184,3 +184,15 @@ A tutorial teaches general skills through a specific exercise. A how-to guide he
 - **Tool-centric framing** — "How to use the X class" is not addressed to a human need
 - **Missing conditionals** — Real-world tasks branch; acknowledge this with if/then guidance
 - **Burying the action** — Lead with what to do, not why
+
+## Companion Notebooks
+
+How-to doc pages can have an interactive companion notebook (marimo). When one exists, add a callout after the title:
+
+```markdown
+!!! tip "Interactive notebook"
+    See the companion notebook for a runnable example.
+    [View](/examples/slug/) · [Open in marimo](/examples/slug/edit/)
+```
+
+Use the `diataxis-notebook-writer` skill when creating or editing the companion notebook itself.
diff --git a/.github/skills/diataxis-notebook-writer/SKILL.md b/.github/skills/diataxis-notebook-writer/SKILL.md
new file mode 100644
index 0000000..66ab803
--- /dev/null
+++ b/.github/skills/diataxis-notebook-writer/SKILL.md
@@ -0,0 +1,68 @@
+---
+name: diataxis-notebook-writer
+description: Write or rework marimo example notebooks following Diataxis principles. Use when asked to create, edit, or rework interactive notebook examples that serve as tutorial or how-to companions to documentation pages. Triggers on "write a notebook example", "rework notebook", "example notebook", "interactive example", "marimo example", "tutorial notebook", "how-to notebook".
+---
+
+# Diataxis Notebook Writer
+
+Write marimo notebook examples that follow Diataxis quadrant conventions for voice, structure, and content boundaries.
+
+Notebooks serve only **tutorials** and **how-to guides** - never explanation or reference. Explanation belongs in markdown pages read away from the keyboard. Reference mirrors code structure, not user tasks.
+
+## Quadrant Decision
+
+Ask two questions to classify the notebook:
+
+1. Does it teach a beginner by guiding them through a learning experience? -> **Tutorial**
+2. Does it help a competent user accomplish a specific real-world task? -> **How-to**
+
+If it does neither (conceptual discussion, API description), it should not be a notebook.
+
+## File Placement and Metadata
+
+Place notebooks in `examples/`. Every notebook must define `__gallery__` metadata:
+
+```python
+__gallery__ = {
+    "title": "How to Stop Optimization Early with Callbacks",  # goal-oriented for how-to
+    "description": "Stop unneeded work early by adding Optuna callbacks to your search.",
+    "category": "how-to",  # "tutorial" or "how-to"
+    "companion": "pages/how-to/use-callbacks.md",  # optional: path to companion doc page
+}
+```
+
+**Title conventions:**
+- Tutorial: descriptive noun phrase - "OptunaSearchCV Quickstart"
+- How-to: "How to [verb]..." - "How to Stop Optimization Early with Callbacks"
+
+## Notebook Cell Structure
+
+Both quadrants use **hidden setup cells** (`hide_code=True`) for imports and markdown narrative, with visible code cells for the actions the reader should focus on.
+
+**For quadrant-specific cell patterns, voice, and templates:**
+- **Tutorial notebooks**: Read [references/tutorial-notebook.md](references/tutorial-notebook.md)
+- **How-to notebooks**: Read [references/howto-notebook.md](references/howto-notebook.md)
+
+## Companion Doc Page Pattern
+
+When a notebook has a companion markdown page, add this admonition near the top of the doc page (after any prerequisites):
+
+```markdown
+!!! tip "Interactive version available"
+    Try this guide as an interactive notebook:
+    [View](/examples/callbacks/) · [Open in marimo](/examples/callbacks/edit/)
+```
+
+## Common Anti-Patterns
+
+- **One-size-fits-all structure**: Using "What You'll Learn" + "Key Takeaways" in every notebook regardless of quadrant
+- **Embedded explanation in how-to**: "Class imbalance is common because..." belongs in an explanation page, not a how-to notebook
+- **Design reasoning in how-to**: "We set refit=False because the outer search doesn't need..." - just say "Set `refit=False`"
+- **Tool-centric titles**: "Callbacks" instead of "How to Stop Optimization Early with Callbacks"
+- **Tutorial language in how-to**: "What You'll Learn" presumes a learning orientation; how-to readers already know what they want
+
+## Related Skills
+
+- `diataxis-tutorial-writer` - for companion markdown tutorial pages
+- `diataxis-howto-writer` - for companion markdown how-to pages
+- `marimo-notebook` - for marimo format mechanics (cell syntax, reactivity, script mode)
diff --git a/.github/skills/diataxis-notebook-writer/references/howto-notebook.md b/.github/skills/diataxis-notebook-writer/references/howto-notebook.md
new file mode 100644
index 0000000..1eca0ea
--- /dev/null
+++ b/.github/skills/diataxis-notebook-writer/references/howto-notebook.md
@@ -0,0 +1,121 @@
+# How-to Notebook Patterns
+
+Cell patterns for marimo notebooks classified as `"category": "how-to"` in `__gallery__`.
+
+A how-to notebook is a **recipe**. The reader already knows what they want to accomplish and needs practical directions to get there. The notebook lets them adapt the recipe to their real-world case.
+
+## Voice
+
+Use imperative and conditional language. Address the reader directly when needed, but focus on actions.
+
+- "This notebook shows how to stop optimization early using Optuna callbacks."
+- "Wrap Optuna's `MaxTrialsCallback` using the `Callback` wrapper."
+- "If you need multiple stopping criteria, pass a dictionary of callbacks."
+
+Never use "What You'll Learn" - the reader already knows what they want to achieve.
+
+## Cell Structure
+
+### Title cell (hidden, first narrative cell)
+
+```python
+@app.cell(hide_code=True)
+def _(mo):
+    mo.md(
+        """
+        # How to Stop Optimization Early with Callbacks
+
+        This notebook shows how to stop optimization early by
+        adding Optuna callbacks to `OptunaSearchCV`.
+
+        **Prerequisites:** Familiarity with the
+        OptunaSearchCV quickstart
+        ([View](/examples/quickstart/) · [Open in marimo](/examples/quickstart/edit/)).
+        """
+    )
+```
+
+Key points:
+- Title starts with "How to [verb]..."
+- One-sentence description of the goal
+- Prerequisites as a single line linking to prior knowledge
+
+### Step cells (hidden, between code cells)
+
+```python
+@app.cell(hide_code=True)
+def _(mo):
+    mo.md(
+        """
+        ## 1. Wrap the Callback
+
+        Wrap Optuna's `MaxTrialsCallback` with the `Callback`
+        wrapper for sklearn compatibility.
+        """
+    )
+```
+
+Key points:
+- Numbered steps with action verbs
+- One to two sentences max - what to do, not why
+- No conceptual explanation; link to explanation page if context is needed
+
+### Verification cells (hidden, after result)
+
+```python
+@app.cell(hide_code=True)
+def _(mo, n_trials_run):
+    mo.md(
+        f"""
+        Requested trials: 20
+        Actual trials run: {n_trials_run}
+        """
+    )
+```
+
+Key points:
+- Show the result that proves the task succeeded
+- No interpretation beyond the facts
+
+### Conditional guidance (when variations exist)
+
+```python
+@app.cell(hide_code=True)
+def _(mo):
+    mo.md(
+        """
+        ## 3. Multiple Callbacks
+
+        If you need multiple stopping criteria, pass a dictionary
+        of callbacks. Each callback is invoked at the end of every trial.
+        """
+    )
+```
+
+Key points:
+- "If you need X, do Y" - conditional imperatives
+- Present variations as branches the user can follow or skip
+- Don't explain why they might need it
+
+### No closing summary
+
+How-to notebooks end after the final verification step. Do not add:
+- "Key Takeaways" sections
+- "What We Learned" summaries
+- "Next Steps" sections (these are optional; include only if directly relevant)
+
+The task is done. The reader moves on.
+
+## Principles Checklist
+
+- [ ] Title is "How to [verb]..." - goal-oriented
+- [ ] `__gallery__` title matches the goal format
+- [ ] No "What You'll Learn" section
+- [ ] No "Key Takeaways" or summary section
+- [ ] Markdown cells contain only directional action prose
+- [ ] No embedded explanation - link out for "why" content
+- [ ] No design reasoning - just show what to do
+- [ ] Conditional imperatives for variations ("If you need X, do Y")
+- [ ] Verification step shows the task succeeded
+- [ ] Numbered steps for clear progression
+- [ ] Assumes competence from prerequisites
diff --git a/.github/skills/diataxis-notebook-writer/references/tutorial-notebook.md b/.github/skills/diataxis-notebook-writer/references/tutorial-notebook.md
new file mode 100644
index 0000000..38c48fd
--- /dev/null
+++ b/.github/skills/diataxis-notebook-writer/references/tutorial-notebook.md
@@ -0,0 +1,129 @@
+# Tutorial Notebook Patterns
+
+Cell patterns for marimo notebooks classified as `"category": "tutorial"` in `__gallery__`.
+
+A tutorial notebook is a **lesson**. The reader acquires skills through guided hands-on practice. The notebook is the classroom - every cell produces visible output the learner can verify.
+
+## Voice
+
+Use first-person plural throughout: **"we"**, **"our"**, **"let's"**.
+
+- "We create a classification dataset"
+- "Now we define the search space"
+- "Let's run the search and inspect the results"
+
+Never use "you will learn" - that is presumptuous. Use "we will [do concrete thing]" instead.
+
+## Cell Structure
+
+### Title cell (hidden, first narrative cell)
+
+```python
+@app.cell(hide_code=True)
+def _(mo):
+    mo.md(
+        """
+        # OptunaSearchCV Quickstart
+
+        In this notebook, we will run a hyperparameter search using
+        `OptunaSearchCV` and inspect the best parameters and score.
+        Along the way, we will define search spaces with Optuna
+        distributions and see how the results API works.
+
+        **Prerequisites:** Basic familiarity with scikit-learn's
+        fit/predict API.
+        """
+    )
+```
+
+Key points:
+- State what **we will do**, not what "you will learn"
+- Mention concrete outcomes, not abstract learning objectives
+- Prerequisites in a single line, not a bulleted list
+
+### Section cells (hidden, between code cells)
+
+```python
+@app.cell(hide_code=True)
+def _(mo):
+    mo.md(
+        """
+        ## 1. Prepare Data and Estimator
+
+        We start by creating a classification dataset and
+        initializing a LogisticRegression estimator.
+        """
+    )
+```
+
+Key points:
+- Number the sections for clear progression
+- One sentence of context - what we do, not why
+- No explanation of concepts - link to explanation page if needed
+
+### Observation cells (hidden, after code output)
+
+```python
+@app.cell(hide_code=True)
+def _(mo, search):
+    mo.md(
+        f"""
+        **Best params:** {search.best_params_}
+        **Best score:** {search.best_score_:.3f}
+
+        Notice that `best_params_` returns the same format as
+        scikit-learn's `GridSearchCV`. The score is the mean
+        cross-validated score from the best trial.
+        """
+    )
+```
+
+Key points:
+- Show exact expected output
+- "Notice that..." closes the learning loop
+- One sentence of observation, not a paragraph of explanation
+
+### Closing cell (hidden, final cell)
+
+```python
+@app.cell(hide_code=True)
+def _(mo):
+    mo.md(
+        """
+        ## What We Built
+
+        We ran a hyperparameter search with `OptunaSearchCV` and found
+        the best regularization parameter for a LogisticRegression. Along
+        the way, we:
+
+        - Defined a search space with `FloatDistribution`
+        - Ran the search with `OptunaSearchCV.fit()`
+        - Inspected `best_params_` and `best_score_`
+
+        **Next steps:**
+
+        - How to resume optimization from prior trials:
+          [View](/examples/study_management/) · [Open in marimo](/examples/study_management/edit/)
+        - How to stop optimization early with callbacks:
+          [View](/examples/callbacks/) · [Open in marimo](/examples/callbacks/edit/)
+        """
+    )
+```
+
+Key points:
+- "What We Built" - celebrate accomplishment, don't summarize theory
+- Brief bullet list of concrete things done, not concepts learned
+- Link to how-to notebooks, not more tutorials
+
+## Principles Checklist
+
+- [ ] Every code cell produces visible output (no silent cells)
+- [ ] "We" language throughout, never "you will learn"
+- [ ] Title says what we will do, not what you will learn
+- [ ] "Notice that..." observations after key outputs
+- [ ] One-sentence max explanation per concept; link out for depth
+- [ ] Single path - no branching, no CategoricalDistribution choices unless essential
+- [ ] All code cells are re-runnable with deterministic results
+- [ ] Ends with "What We Built", not "Key Takeaways"
+- [ ] Numbered sections guide sequential progression
+- [ ] No options or alternatives - just one clear path
diff --git a/.github/skills/diataxis-tutorial-writer/SKILL.md b/.github/skills/diataxis-tutorial-writer/SKILL.md
index fca6780..fc96d80 100644
--- a/.github/skills/diataxis-tutorial-writer/SKILL.md
+++ b/.github/skills/diataxis-tutorial-writer/SKILL.md
@@ -206,3 +206,15 @@ You have [accomplished concrete thing]. Along the way, you:
 - Not a reference (describes machinery, doesn't guide action)
 - Not an explanation (discusses topics, doesn't guide action)
 - Not "the basics" — tutorials can be advanced; the distinction is study vs. work
+
+## Companion Notebooks
+
+Tutorial doc pages can have an interactive companion notebook (marimo). When one exists, add a callout after the title:
+
+```markdown
+!!! tip "Interactive notebook"
+    Follow along in the Quickstart notebook for a hands-on version of this tutorial.
+    [View](/examples/slug/) · [Open in marimo](/examples/slug/edit/)
+```
+
+Use the `diataxis-notebook-writer` skill when creating or editing the companion notebook itself.
diff --git a/template/.github/skills/diataxis-docs-planner/SKILL.md b/template/.github/skills/diataxis-docs-planner/SKILL.md
index 87f5828..729f8cc 100644
--- a/template/.github/skills/diataxis-docs-planner/SKILL.md
+++ b/template/.github/skills/diataxis-docs-planner/SKILL.md
@@ -49,6 +49,7 @@ Read all files in `docs/` and classify each page by quadrant using the compass:
 - For each page, note: file path, current title, actual quadrant, intended quadrant
 - Flag pages that mix quadrants (e.g., a "getting started" that is half tutorial, half reference)
 - Flag pages that are misclassified (e.g., an "explanation" page that is really a how-to)
+- Check `examples/` for marimo notebooks: classify each by quadrant using its `__gallery__` metadata `category` field and verify it matches the notebook content
 
 ### Step 3: Identify Gaps
 
@@ -89,6 +90,7 @@ Output a structured documentation plan:
    - How-to pages → `diataxis-howto-writer`
    - Reference pages → `diataxis-reference-writer`
    - Explanation pages → `diataxis-explanation-writer`
+   - Companion notebooks → `diataxis-notebook-writer`
 
 ## MkDocs Nav Patterns
 
diff --git a/template/.github/skills/diataxis-howto-writer/SKILL.md b/template/.github/skills/diataxis-howto-writer/SKILL.md
index 99d3c51..3daed51 100644
--- a/template/.github/skills/diataxis-howto-writer/SKILL.md
+++ b/template/.github/skills/diataxis-howto-writer/SKILL.md
@@ -184,3 +184,15 @@ A tutorial teaches general skills through a specific exercise. A how-to guide he
 - **Tool-centric framing** — "How to use the X class" is not addressed to a human need
 - **Missing conditionals** — Real-world tasks branch; acknowledge this with if/then guidance
 - **Burying the action** — Lead with what to do, not why
+
+## Companion Notebooks
+
+How-to doc pages can have an interactive companion notebook (marimo). When one exists, add a callout after the title:
+
+```markdown
+!!! tip "Interactive notebook"
+    See the companion notebook for a runnable example.
+    [View](/examples/slug/) · [Open in marimo](/examples/slug/edit/)
+```
+
+Use the `diataxis-notebook-writer` skill when creating or editing the companion notebook itself.
diff --git a/template/.github/skills/diataxis-notebook-writer/SKILL.md b/template/.github/skills/diataxis-notebook-writer/SKILL.md
new file mode 100644
index 0000000..66ab803
--- /dev/null
+++ b/template/.github/skills/diataxis-notebook-writer/SKILL.md
@@ -0,0 +1,68 @@
+---
+name: diataxis-notebook-writer
+description: Write or rework marimo example notebooks following Diataxis principles. Use when asked to create, edit, or rework interactive notebook examples that serve as tutorial or how-to companions to documentation pages. Triggers on "write a notebook example", "rework notebook", "example notebook", "interactive example", "marimo example", "tutorial notebook", "how-to notebook".
+---
+
+# Diataxis Notebook Writer
+
+Write marimo notebook examples that follow Diataxis quadrant conventions for voice, structure, and content boundaries.
+
+Notebooks serve only **tutorials** and **how-to guides** - never explanation or reference. Explanation belongs in markdown pages read away from the keyboard. Reference mirrors code structure, not user tasks.
+
+## Quadrant Decision
+
+Ask two questions to classify the notebook:
+
+1. Does it teach a beginner by guiding them through a learning experience? -> **Tutorial**
+2. Does it help a competent user accomplish a specific real-world task? -> **How-to**
+
+If it does neither (conceptual discussion, API description), it should not be a notebook.
+
+## File Placement and Metadata
+
+Place notebooks in `examples/`. Every notebook must define `__gallery__` metadata:
+
+```python
+__gallery__ = {
+    "title": "How to Stop Optimization Early with Callbacks",  # goal-oriented for how-to
+    "description": "Stop unneeded work early by adding Optuna callbacks to your search.",
+    "category": "how-to",  # "tutorial" or "how-to"
+    "companion": "pages/how-to/use-callbacks.md",  # optional: path to companion doc page
+}
+```
+
+**Title conventions:**
+- Tutorial: descriptive noun phrase - "OptunaSearchCV Quickstart"
+- How-to: "How to [verb]..." - "How to Stop Optimization Early with Callbacks"
+
+## Notebook Cell Structure
+
+Both quadrants use **hidden setup cells** (`hide_code=True`) for imports and markdown narrative, with visible code cells for the actions the reader should focus on.
+
+**For quadrant-specific cell patterns, voice, and templates:**
+- **Tutorial notebooks**: Read [references/tutorial-notebook.md](references/tutorial-notebook.md)
+- **How-to notebooks**: Read [references/howto-notebook.md](references/howto-notebook.md)
+
+## Companion Doc Page Pattern
+
+When a notebook has a companion markdown page, add this admonition near the top of the doc page (after any prerequisites):
+
+```markdown
+!!! tip "Interactive version available"
+    Try this guide as an interactive notebook:
+    [View](/examples/callbacks/) · [Open in marimo](/examples/callbacks/edit/)
+```
+
+## Common Anti-Patterns
+
+- **One-size-fits-all structure**: Using "What You'll Learn" + "Key Takeaways" in every notebook regardless of quadrant
+- **Embedded explanation in how-to**: "Class imbalance is common because..." belongs in an explanation page, not a how-to notebook
+- **Design reasoning in how-to**: "We set refit=False because the outer search doesn't need..." - just say "Set `refit=False`"
+- **Tool-centric titles**: "Callbacks" instead of "How to Stop Optimization Early with Callbacks"
+- **Tutorial language in how-to**: "What You'll Learn" presumes a learning orientation; how-to readers already know what they want
+
+## Related Skills
+
+- `diataxis-tutorial-writer` - for companion markdown tutorial pages
+- `diataxis-howto-writer` - for companion markdown how-to pages
+- `marimo-notebook` - for marimo format mechanics (cell syntax, reactivity, script mode)
diff --git a/template/.github/skills/diataxis-notebook-writer/references/howto-notebook.md b/template/.github/skills/diataxis-notebook-writer/references/howto-notebook.md
new file mode 100644
index 0000000..1eca0ea
--- /dev/null
+++ b/template/.github/skills/diataxis-notebook-writer/references/howto-notebook.md
@@ -0,0 +1,121 @@
+# How-to Notebook Patterns
+
+Cell patterns for marimo notebooks classified as `"category": "how-to"` in `__gallery__`.
+
+A how-to notebook is a **recipe**. The reader already knows what they want to accomplish and needs practical directions to get there. The notebook lets them adapt the recipe to their real-world case.
+
+## Voice
+
+Use imperative and conditional language. Address the reader directly when needed, but focus on actions.
+
+- "This notebook shows how to stop optimization early using Optuna callbacks."
+- "Wrap Optuna's `MaxTrialsCallback` using the `Callback` wrapper."
+- "If you need multiple stopping criteria, pass a dictionary of callbacks."
+
+Never use "What You'll Learn" - the reader already knows what they want to achieve.
+
+## Cell Structure
+
+### Title cell (hidden, first narrative cell)
+
+```python
+@app.cell(hide_code=True)
+def _(mo):
+    mo.md(
+        """
+        # How to Stop Optimization Early with Callbacks
+
+        This notebook shows how to stop optimization early by
+        adding Optuna callbacks to `OptunaSearchCV`.
+
+        **Prerequisites:** Familiarity with the
+        OptunaSearchCV quickstart
+        ([View](/examples/quickstart/) · [Open in marimo](/examples/quickstart/edit/)).
+        """
+    )
+```
+
+Key points:
+- Title starts with "How to [verb]..."
+- One-sentence description of the goal
+- Prerequisites as a single line linking to prior knowledge
+
+### Step cells (hidden, between code cells)
+
+```python
+@app.cell(hide_code=True)
+def _(mo):
+    mo.md(
+        """
+        ## 1. Wrap the Callback
+
+        Wrap Optuna's `MaxTrialsCallback` with the `Callback`
+        wrapper for sklearn compatibility.
+        """
+    )
+```
+
+Key points:
+- Numbered steps with action verbs
+- One to two sentences max - what to do, not why
+- No conceptual explanation; link to explanation page if context is needed
+
+### Verification cells (hidden, after result)
+
+```python
+@app.cell(hide_code=True)
+def _(mo, n_trials_run):
+    mo.md(
+        f"""
+        Requested trials: 20
+        Actual trials run: {n_trials_run}
+        """
+    )
+```
+
+Key points:
+- Show the result that proves the task succeeded
+- No interpretation beyond the facts
+
+### Conditional guidance (when variations exist)
+
+```python
+@app.cell(hide_code=True)
+def _(mo):
+    mo.md(
+        """
+        ## 3. Multiple Callbacks
+
+        If you need multiple stopping criteria, pass a dictionary
+        of callbacks. Each callback is invoked at the end of every trial.
+        """
+    )
+```
+
+Key points:
+- "If you need X, do Y" - conditional imperatives
+- Present variations as branches the user can follow or skip
+- Don't explain why they might need it
+
+### No closing summary
+
+How-to notebooks end after the final verification step. Do not add:
+- "Key Takeaways" sections
+- "What We Learned" summaries
+- "Next Steps" sections (these are optional; include only if directly relevant)
+
+The task is done. The reader moves on.
+
+## Principles Checklist
+
+- [ ] Title is "How to [verb]..." - goal-oriented
+- [ ] `__gallery__` title matches the goal format
+- [ ] No "What You'll Learn" section
+- [ ] No "Key Takeaways" or summary section
+- [ ] Markdown cells contain only directional action prose
+- [ ] No embedded explanation - link out for "why" content
+- [ ] No design reasoning - just show what to do
+- [ ] Conditional imperatives for variations ("If you need X, do Y")
+- [ ] Verification step shows the task succeeded
+- [ ] Numbered steps for clear progression
+- [ ] Assumes competence from prerequisites
diff --git a/template/.github/skills/diataxis-notebook-writer/references/tutorial-notebook.md b/template/.github/skills/diataxis-notebook-writer/references/tutorial-notebook.md
new file mode 100644
index 0000000..38c48fd
--- /dev/null
+++ b/template/.github/skills/diataxis-notebook-writer/references/tutorial-notebook.md
@@ -0,0 +1,129 @@
+# Tutorial Notebook Patterns
+
+Cell patterns for marimo notebooks classified as `"category": "tutorial"` in `__gallery__`.
+
+A tutorial notebook is a **lesson**. The reader acquires skills through guided hands-on practice. The notebook is the classroom - every cell produces visible output the learner can verify.
+
+## Voice
+
+Use first-person plural throughout: **"we"**, **"our"**, **"let's"**.
+
+- "We create a classification dataset"
+- "Now we define the search space"
+- "Let's run the search and inspect the results"
+
+Never use "you will learn" - that is presumptuous. Use "we will [do concrete thing]" instead.
+
+## Cell Structure
+
+### Title cell (hidden, first narrative cell)
+
+```python
+@app.cell(hide_code=True)
+def _(mo):
+    mo.md(
+        """
+        # OptunaSearchCV Quickstart
+
+        In this notebook, we will run a hyperparameter search using
+        `OptunaSearchCV` and inspect the best parameters and score.
+        Along the way, we will define search spaces with Optuna
+        distributions and see how the results API works.
+
+        **Prerequisites:** Basic familiarity with scikit-learn's
+        fit/predict API.
+        """
+    )
+```
+
+Key points:
+- State what **we will do**, not what "you will learn"
+- Mention concrete outcomes, not abstract learning objectives
+- Prerequisites in a single line, not a bulleted list
+
+### Section cells (hidden, between code cells)
+
+```python
+@app.cell(hide_code=True)
+def _(mo):
+    mo.md(
+        """
+        ## 1. Prepare Data and Estimator
+
+        We start by creating a classification dataset and
+        initializing a LogisticRegression estimator.
+        """
+    )
+```
+
+Key points:
+- Number the sections for clear progression
+- One sentence of context - what we do, not why
+- No explanation of concepts - link to explanation page if needed
+
+### Observation cells (hidden, after code output)
+
+```python
+@app.cell(hide_code=True)
+def _(mo, search):
+    mo.md(
+        f"""
+        **Best params:** {search.best_params_}
+        **Best score:** {search.best_score_:.3f}
+
+        Notice that `best_params_` returns the same format as
+        scikit-learn's `GridSearchCV`. The score is the mean
+        cross-validated score from the best trial.
+        """
+    )
+```
+
+Key points:
+- Show exact expected output
+- "Notice that..." closes the learning loop
+- One sentence of observation, not a paragraph of explanation
+
+### Closing cell (hidden, final cell)
+
+```python
+@app.cell(hide_code=True)
+def _(mo):
+    mo.md(
+        """
+        ## What We Built
+
+        We ran a hyperparameter search with `OptunaSearchCV` and found
+        the best regularization parameter for a LogisticRegression. Along
+        the way, we:
+
+        - Defined a search space with `FloatDistribution`
+        - Ran the search with `OptunaSearchCV.fit()`
+        - Inspected `best_params_` and `best_score_`
+
+        **Next steps:**
+
+        - How to resume optimization from prior trials:
+          [View](/examples/study_management/) · [Open in marimo](/examples/study_management/edit/)
+        - How to stop optimization early with callbacks:
+          [View](/examples/callbacks/) · [Open in marimo](/examples/callbacks/edit/)
+        """
+    )
+```
+
+Key points:
+- "What We Built" - celebrate accomplishment, don't summarize theory
+- Brief bullet list of concrete things done, not concepts learned
+- Link to how-to notebooks, not more tutorials
+
+## Principles Checklist
+
+- [ ] Every code cell produces visible output (no silent cells)
+- [ ] "We" language throughout, never "you will learn"
+- [ ] Title says what we will do, not what you will learn
+- [ ] "Notice that..." observations after key outputs
+- [ ] One-sentence max explanation per concept; link out for depth
+- [ ] Single path - no branching, no CategoricalDistribution choices unless essential
+- [ ] All code cells are re-runnable with deterministic results
+- [ ] Ends with "What We Built", not "Key Takeaways"
+- [ ] Numbered sections guide sequential progression
+- [ ] No options or alternatives - just one clear path
diff --git a/template/.github/skills/diataxis-tutorial-writer/SKILL.md b/template/.github/skills/diataxis-tutorial-writer/SKILL.md
index fca6780..fc96d80 100644
--- a/template/.github/skills/diataxis-tutorial-writer/SKILL.md
+++ b/template/.github/skills/diataxis-tutorial-writer/SKILL.md
@@ -206,3 +206,15 @@ You have [accomplished concrete thing]. Along the way, you:
 - Not a reference (describes machinery, doesn't guide action)
 - Not an explanation (discusses topics, doesn't guide action)
 - Not "the basics" — tutorials can be advanced; the distinction is study vs. work
+
+## Companion Notebooks
+
+Tutorial doc pages can have an interactive companion notebook (marimo). When one exists, add a callout after the title:
+
+```markdown
+!!! tip "Interactive notebook"
+    Follow along in the Quickstart notebook for a hands-on version of this tutorial.
+    [View](/examples/slug/) · [Open in marimo](/examples/slug/edit/)
+```
+
+Use the `diataxis-notebook-writer` skill when creating or editing the companion notebook itself.
diff --git a/template/docs/hooks.py.jinja b/template/docs/hooks.py.jinja
index 0f66cd2..1fb03bf 100644
--- a/template/docs/hooks.py.jinja
+++ b/template/docs/hooks.py.jinja
@@ -359,6 +359,7 @@ def _get_gallery_items(project_root):
         items.append({
             "title": gallery.get("title", stem.replace("_", " ").title()),
             "description": gallery.get("description", ""),
+            "category": gallery.get("category", ""),
             "view_path": view_path,
             "open_path": open_path,
             "stem": stem,
@@ -369,12 +370,43 @@ def _get_gallery_items(project_root):
 
 
 def _build_gallery_html(project_root):
-    """Build gallery card grid as Material 'grid cards' markdown."""
+    """Build gallery card grid as Material 'grid cards' markdown, grouped by category."""
     items = _get_gallery_items(project_root)
 
     if not items:
         return "<!-- no gallery items found -->\n"
 
+    # Group items by category, preserving order within each group
+    _CATEGORY_ORDER = ["tutorial", "how-to"]
+    _CATEGORY_HEADINGS = {
+        "tutorial": "Tutorials",
+        "how-to": "How-to Guides",
+    }
+
+    grouped: dict[str, list[dict]] = {}
+    for item in items:
+        cat = item.get("category") or "other"
+        grouped.setdefault(cat, []).append(item)
+
+    sections = []
+    for cat in _CATEGORY_ORDER:
+        group = grouped.pop(cat, [])
+        if not group:
+            continue
+        heading = _CATEGORY_HEADINGS.get(cat, cat.title())
+        cards = _build_gallery_cards(group)
+        sections.append(f"## {heading}\n\n{cards}")
+
+    # Remaining uncategorized items
+    for _cat, group in grouped.items():
+        cards = _build_gallery_cards(group)
+        sections.append(cards)
+
+    return "\n\n".join(sections) + "\n"
+
+
+def _build_gallery_cards(items):
+    """Build a Material 'grid cards' block from a list of gallery items."""
     cards = []
     for item in items:
         desc = item["description"] or "No description."
@@ -481,25 +513,7 @@ def _build_api_examples_html(project_root, qualified_name):
             seen.add(item["stem"])
             unique_items.append(item)
 
-    cards = []
-    for item in unique_items:
-        desc = item["description"] or "No description."
-        cards.append(
-            f"-   **{item['title']}**\n"
-            f"\n"
-            f"    ---\n"
-            f"\n"
-            f"    {desc}\n"
-            f"\n"
-            f"    [View]({item['view_path']}) · "
-            f"[Open in marimo]({item['open_path']})"
-        )
-
-    return (
-        "## Examples\n\n"
-        "The following example notebooks use this component:\n\n"
-        '<div class="grid cards" markdown>\n\n' + "\n\n".join(cards) + "\n\n</div>\n"
-    )
+    return "## Examples\n\nThe following example notebooks use this component:\n\n" + _build_gallery_cards(unique_items)
 {%- endif %}
 
 
diff --git a/template/docs/pages/how-to/contribute.md.jinja b/template/docs/pages/how-to/contribute.md.jinja
index 1b9c8d4..dc6a8c3 100644
--- a/template/docs/pages/how-to/contribute.md.jinja
+++ b/template/docs/pages/how-to/contribute.md.jinja
@@ -445,29 +445,44 @@ Create a new marimo notebook in `examples/<name>.py`:
 
 #### Required Structure
 
-Every example notebook **must** follow this structure in order:
+Notebooks serve **tutorials** or **how-to guides** only - never explanation or reference. The structure depends on the quadrant:
 
-1. **Title**: A top-level `# Title` heading describing the notebook topic
-2. **What You'll Learn**: A `## What You'll Learn` section with a bulleted list of concrete learning goals
-3. **Prerequisites**: A `## Prerequisites` section stating required prior knowledge (one-liner or short bullet list). For standalone dataset explorations, use "None: this is a standalone dataset exploration."
-4. **Numbered sections**: Main content as `## 1. Section Name`, `## 2. Section Name`, etc.
-5. **Key Takeaways**: A `## Key Takeaways` section with bullet points summarizing important lessons learned
-6. **Next Steps**: A `## Next Steps` section with bullet points linking to related notebooks or documentation
+**Tutorial notebooks** (category: `tutorial`):
 
-**Example intro cell**:
+1. **Title**: `# In this notebook, we will [goal]`
+2. **Prerequisites**: One-liner stating required prior knowledge
+3. **Numbered sections**: `## 1. Section Name`, `## 2. Section Name`, etc. with visible output every cell
+4. **What We Built**: Closing section summarizing what was accomplished and linking to next steps
+
+**How-to notebooks** (category: `how-to`):
+
+1. **Title**: `# How to [Verb] [Object]`
+2. **Prerequisites**: One-liner stating required prior knowledge
+3. **Numbered sections**: `## 1. Section Name`, `## 2. Section Name`, etc. with action-only prose
+4. No closing summary - the notebook ends after the last step
+
+**Example intro cell (tutorial)**:
 
 ```markdown
-# Reduction Forecasting with sklearn
+# Your First Hyperparameter Search
 
-## What You'll Learn
+In this notebook, we will run a hyperparameter search using OptunaSearchCV
+and inspect the results.
 
-- How `PointReductionForecaster` tabularizes time series data using lag features
-- The difference between `target_transformer` and `feature_transformer` parameters
-- Tuning hyperparameters with `GridSearchCV`
+**Prerequisites:** Python 3.11+ and familiarity with sklearn's fit/predict API.
+```
+
+**Example intro cell (how-to)**:
+
+```markdown
+# How to Stop Optimization Early with Callbacks
 
-## Prerequisites
+This notebook shows how to attach Optuna callbacks to OptunaSearchCV
+to stop a search after a fixed number of trials.
 
-Basic familiarity with sklearn's fit/predict API and time series concepts (trend, seasonality).
+**Prerequisites:** Familiarity with the
+OptunaSearchCV quickstart
+([View](/examples/quickstart/) · [Open in marimo](/examples/quickstart/edit/)).
 ```
 
 #### Marimo Cell Conventions
@@ -494,12 +509,11 @@ Basic familiarity with sklearn's fit/predict API and time series concepts (trend
 
 #### Content Guidelines
 
-- **Gallery metadata**: Every example notebook should include a `__gallery__` variable in the first `@app.cell` defining `title`, `description`, and `category` for the example gallery.
-- **Markdown density**: Each numbered section should open with a descriptive markdown cell explaining the concept before any code cells. Consecutive code cells within the same section are acceptable when logically grouped.
+- **Gallery metadata**: Every example notebook should include a `__gallery__` variable defining `title`, `description`, and `category` (`"tutorial"` or `"how-to"`) for the example gallery. Add a `companion` key pointing to the matching doc page path when one exists.
+- **Markdown density**: Each numbered section should open with a short markdown cell (one to two sentences) before any code cells. Tutorial sections may be slightly longer; how-to sections should be action-only.
 - **No emojis**: Do not use emojis anywhere in notebooks whether it is in headings, content bullets, or concluding remarks.
-- **API cross-links**: When mentioning {{ package_name }} classes or functions in markdown cells, wrap them in backtick-link syntax pointing to the API page (e.g., `` [`SeasonalNaive`](/pages/api/generated/{{ package_name }}.point.naive.SeasonalNaive/) ``).
-- **Key Takeaways format**: Use bold for key terms with plain descriptions (e.g., `- **Reduction forecasting** converts time series into tabular regression via lag features`)
-- **Next Steps format**: Use bold labels with linked notebook references (e.g., `- **Naive baselines**: See [`naive_forecasters.py`](/examples/point/naive_forecasters/) to compare`). Always link to the rendered example page, not the raw file.
+- **API cross-links**: When mentioning {{ package_name }} classes or functions in markdown cells, wrap them in backtick-link syntax pointing to the API page.
+- **Voice**: Tutorials use "we" (first-person plural). How-to guides use imperative or conditional imperatives ("If you need X, pass Y").
 
 #### Testing and Documentation
 
diff --git a/template/docs/pages/tutorials/{% if include_examples %}examples.md{% endif %}.jinja b/template/docs/pages/tutorials/{% if include_examples %}examples.md{% endif %}.jinja
index 7286628..049602e 100644
--- a/template/docs/pages/tutorials/{% if include_examples %}examples.md{% endif %}.jinja	
+++ b/template/docs/pages/tutorials/{% if include_examples %}examples.md{% endif %}.jinja	
@@ -1,6 +1,6 @@
 {% if include_examples %}# Examples
 
-Explore {{ project_name }} through interactive example notebooks.
+Interactive notebooks grouped by purpose: **Tutorials** walk through a topic step-by-step, while **How-to Guides** solve a specific task.
 
 <!-- GALLERY -->
 
diff --git a/template/{% if include_examples %}examples{% endif %}/hello.py.jinja b/template/{% if include_examples %}examples{% endif %}/hello.py.jinja
index bd8a3ae..92a4123 100644
--- a/template/{% if include_examples %}examples{% endif %}/hello.py.jinja	
+++ b/template/{% if include_examples %}examples{% endif %}/hello.py.jinja	
@@ -12,6 +12,7 @@ __generated_with = "0.9.0"
 __gallery__ = {
     "title": "Hello {{ project_name }}",
     "description": "Interactive scatter plot demonstrating {{ project_name }} with marimo notebooks.",
+    "category": "tutorial",
 }
 app = marimo.App(width="medium")
 
diff --git a/tests/test_docs_content.py b/tests/test_docs_content.py
index e17dd3b..85aa7a1 100644
--- a/tests/test_docs_content.py
+++ b/tests/test_docs_content.py
@@ -363,6 +363,17 @@ def test_examples_page_uses_gallery_placeholder(self, copie):
         assert "## Running Examples Locally" in content
         assert "just example" in content
 
+    def test_examples_page_describes_diataxis_grouping(self, copie):
+        """Test that examples page intro describes tutorial/how-to grouping."""
+        result = copie.copy(extra_answers={"include_examples": True})
+        assert result.exit_code == 0
+
+        examples_page = result.project_dir / "docs" / "pages" / "tutorials" / "examples.md"
+        content = examples_page.read_text(encoding="utf-8")
+
+        assert "Tutorials" in content
+        assert "How-to Guides" in content
+
 
 class TestMkdocsConfiguration:
     """Test mkdocs.yml configuration."""
diff --git a/tests/test_propagated_features.py b/tests/test_propagated_features.py
index 04d8b57..479f734 100644
--- a/tests/test_propagated_features.py
+++ b/tests/test_propagated_features.py
@@ -215,6 +215,7 @@ def test_hello_notebook_has_gallery_metadata(self, copie):
         assert "__gallery__" in content
         assert '"title"' in content
         assert '"description"' in content
+        assert '"category"' in content
 
     def test_hooks_has_gallery_functions_when_examples(self, copie):
         """Test that hooks.py includes gallery functions when examples enabled."""
@@ -222,6 +223,16 @@ def test_hooks_has_gallery_functions_when_examples(self, copie):
         content = (result.project_dir / "docs" / "hooks.py").read_text()
         assert "_get_gallery_items" in content
         assert "_build_gallery_html" in content
+        assert "_build_gallery_cards" in content
+
+    def test_hooks_gallery_groups_by_category(self, copie):
+        """Test that hooks.py gallery groups items by tutorial/how-to category."""
+        result = copie.copy(extra_answers={"include_examples": True})
+        content = (result.project_dir / "docs" / "hooks.py").read_text()
+        assert '"tutorial"' in content
+        assert '"how-to"' in content
+        assert "Tutorials" in content
+        assert "How-to Guides" in content
 
     def test_hooks_no_gallery_when_no_examples(self, copie):
         """Test that hooks.py omits gallery functions when examples disabled."""