update docs and skills

Author: bebechien

docs/contributing/components.md

@@ -326,6 +326,7 @@ The quiet band under every H1. You never write this markup; it is rendered from
 models: [gemma-4]        # what the page is about
 frameworks: [ollama]     # primary tools the page teaches, linked to their home pages
 requires: audio          # narrows the selector to models that accept audio
+colab: https://colab.research.google.com/github/google-gemma/docs/blob/main/docs/notebooks/tutorial-gemma-4-e2b-it.ipynb # opens in Colab
 ```
 
 Two kinds of item sit on the line, and keeping them apart is the design:
@@ -335,6 +336,7 @@ Two kinds of item sit on the line, and keeping them apart is the design:
 | `Models` | `models` frontmatter | What the page is **about**. Links to the local model page. |
 | `Uses` | `frameworks` frontmatter | Primary tools the page teaches. Links out to each project. |
 | `Examples` | the page's own code | What **you** want the commands to target. A preference. |
+| `Colab` | `colab` frontmatter | Direct link to Colab notebook; dynamically updates to target the selected model. |
 
 Pairs are separated by a 1px rule, values all share one weight, and labels are muted — 16px of
 space alone was not enough to stop `Frameworks Sentence Transformers` reading as a single run
@@ -367,6 +369,8 @@ every tag while the `pull` command above it follows the selector.
 
 A model is only offered if it has a published id for **every** engine appearing in the page's
 marked blocks, so switching can never rewrite some snippets and silently leave others behind.
+If a page specifies a `requires:` modality in frontmatter (such as `requires: audio`), the picker
+and exported notebooks are additionally filtered to models supporting that modality.
 If an intentionally separate example lacks one size—such as a QAT checkpoint—mark it
 `{ .model-fixed }` and explain the limitation beside it instead of unnecessarily narrowing the
 page's primary examples.
@@ -389,23 +393,32 @@ should become executable cells in the generated notebook:
 
 ````markdown
 ```python { .notebook-cell .model-swap }
-print("This becomes a code cell; the authored model is retained.")
+model_id = "google/gemma-4-E2B-it"
 ```
 ````
 
 Unmarked fences remain part of a Markdown cell, and `{ .output }` blocks are omitted because a
-notebook recreates them when it runs. Add the generated notebook's Colab URL to frontmatter to
-show a quiet, accessible Colab icon in the page context strip:
+notebook recreates them when it runs.
+
+When a tutorial uses `{ .model-swap }`, `scripts/notebooks.py` exports separate model-specific
+notebooks named `<page>-gemma-4-<size>-it.ipynb` (e.g., `thinking-gemma-4-e2b-it.ipynb`,
+`thinking-gemma-4-12b-it.ipynb`) for every candidate model supported by the page's engines and
+`requires:` modality constraint. Tutorials without `.model-swap` export a single `<page>.ipynb`.
+
+Add the default model notebook's Colab URL to frontmatter to show a quiet, accessible Colab icon
+in the page context strip:
 
 ```yaml
-colab: https://colab.research.google.com/github/google-gemma/docs/blob/main/docs/notebooks/tutorial.ipynb
+colab: https://colab.research.google.com/github/google-gemma/docs/blob/main/docs/notebooks/tutorial-gemma-4-e2b-it.ipynb
 ```
 
+When readers select another model in the page context dropdown, the model switcher dynamically
+updates the Colab button's destination to match the selected model notebook.
+
 Wrap any other site-only controls in `<!-- notebook:skip-start -->` and
-`<!-- notebook:skip-end -->`. Register the source and output in `scripts/notebooks.py`, then
+`<!-- notebook:skip-end -->`. Register the source page in `SOURCES` in `scripts/notebooks.py`, then
 generate every registered notebook with `uv run python scripts/notebooks.py`; use `--check`
-during verification. Do not edit the generated `.ipynb`
-directly.
+during verification. Do not edit the generated `.ipynb` directly.
 
 ## Engine grid
 

docs/contributing/conventions.md

@@ -45,7 +45,7 @@ Nothing in this list should ever be edited by hand. Each has a generator, and
 | `docs/javascripts/model-data.js` | `generate_model_names.py` | `models.yml`, `frameworks.yml` |
 | `snippets/links.md`, `snippets/glossary.md` | `generate_snippets.py` | `links.yml`, `glossary.yml` |
 | `docs/llms.txt` and the raw `.md` routes | `agent_docs.py` | Page frontmatter and the nav |
-| `docs/notebooks/*.ipynb` | `notebooks.py` | The ten registered tutorial pages |
+| `docs/notebooks/*.ipynb` | `notebooks.py` | Registered tutorial pages (model-adapted variants for swappable pages) |
 | `overrides/.icons/**.svg` | `vendor_icons.py` | The icons pages actually reference |
 
 Icons are the one entry checked by `--check icons` rather than `--check generated`, because
@@ -75,7 +75,7 @@ upstream source is still findable.
 distinction it draws matters:
 
 - **Authored** keys are facts only a person knows — `title`, `description`, `models`,
-  `frameworks`, `prerequisites`.
+  `frameworks`, `prerequisites`, `requires` (modality constraints), `colab` (direct notebook link).
 - **Computed** keys are derivable from the file. Writing one by hand is an *error*, because a
   hand-written token count is wrong the moment the page is edited.
 
@@ -110,13 +110,22 @@ one, and marking it up buries the links that do need revisiting.
 
 ## Markdown is the source, notebooks are output
 
-Ten pages are exported to Jupyter. Markdown owns every subsequent edit; the `.ipynb` is a build
-artifact.
+Ten tutorial pages in `SOURCES` are exported to Jupyter. Markdown owns every subsequent edit; the
+`.ipynb` files are build artifacts.
 
-Only fences marked `.notebook-cell` become executable cells. Everything else in the page is
-site chrome, and `notebooks.py` strips what Jupyter cannot render — `attr_list` annotations,
-card grids, snippet includes and abbreviation definitions. **Anything added to the authoring
-vocabulary needs a matching strip**, or it lands in the notebook as literal text.
+Only fences marked `.notebook-cell` become executable cells. When a tutorial contains
+`{ .model-swap }` code blocks, `notebooks.py` exports separate model-specific notebooks named
+`<stem>-gemma-4-<size>-it.ipynb` (e.g., `thinking-gemma-4-e2b-it.ipynb`) for all candidate models
+matching the tutorial's engines and `requires:` modality constraint. Non-swappable tutorials
+export a single `<stem>.ipynb`.
+
+For swappable tutorials, frontmatter specifies the default model notebook in `colab:`, and the
+page context switcher dynamically updates the link when readers select a different model.
+
+Everything else in the page is site chrome, and `notebooks.py` strips what Jupyter cannot render —
+`attr_list` annotations, card grids, `{ .output }` blocks, snippet includes, abbreviation definitions,
+and skip blocks (`<!-- notebook:skip-start -->` ... `<!-- notebook:skip-end -->`). **Anything added
+to the authoring vocabulary needs a matching strip**, or it lands in the notebook as literal text.
 
 ## Verification
 

skills/gemma-docs/SKILL.md

@@ -57,7 +57,7 @@ This skill guides coding agents and contributors in maintaining and authoring do
 
 | Data File | Governs | Generator / Consumer |
 |---|---|---|
-| `data/models.yml` | Model families, parameter sizes, context lengths, memory requirements, framework-specific checkpoint IDs | `scripts/generate_model_names.py` -> `docs/javascripts/model-data.js` and `overrides/partials/model-names.html` |
+| `data/models.yml` | Model families, parameter sizes, context lengths, memory requirements, framework-specific checkpoint IDs | `scripts/generate_model_names.py` -> `docs/javascripts/model-data.js` and `overrides/partials/model-names.html`; `scripts/notebooks.py` -> `docs/notebooks/*.ipynb` |
 | `data/frameworks.yml` | Engine metadata, blurbs, icons, URLs, `tuning_paths` | Rendered by Jinja macros (`{{ engines(...) }}`, `{{ paths(...) }}`) in pages |
 | `data/links.yml` | URLs used on more than one page, model version tags | `scripts/generate_snippets.py` -> `snippets/links.md` (auto-appended to all pages) |
 | `data/glossary.yml` | Acronyms and term definitions | `scripts/generate_snippets.py` -> `snippets/glossary.md` (opt-in via `--8<-- "glossary.md"`) |
@@ -68,6 +68,7 @@ Whenever editing files in `data/`, run:
 uv run --frozen python scripts/generate_model_names.py
 uv run --frozen python scripts/generate_snippets.py
 uv run --frozen python scripts/agent_docs.py
+uv run --frozen python scripts/notebooks.py
 ```
 `scripts/lint_docs.py --check generated` will fail if generated files are out of sync with `data/`.
 
@@ -83,14 +84,18 @@ Every page must have valid YAML frontmatter matching `scripts/frontmatter_schema
 title: Page Title
 description: Concise 1-2 sentence description for search and previews.
 models: [gemma-4]          # Optional: list of relevant model family IDs
-frameworks: [ollama, vllm] # Optional: list of relevant framework IDs
+frameworks: [transformers] # Optional: list of relevant framework IDs
+requires: audio            # Optional: required input modality (e.g. audio, vision)
+colab: https://colab.research.google.com/github/google-gemma/docs/blob/main/docs/notebooks/tutorial-gemma-4-e2b-it.ipynb # Optional: Colab link
 prerequisites:             # Optional: list of prerequisite topics
   - get-started/index.md
 source_url: "https://..."  # Mandatory on imported pages; omitted on original pages
 ---
 ```
 - **Authored keys only**: Do NOT add computed keys (e.g. token counts).
 - **Vocabularies**: Model and framework identifiers must exist in `data/models.yml` and `data/frameworks.yml`.
+- **Modality gating**: Use `requires:` to restrict model selection and notebook export to models supporting that modality (e.g., `audio` excludes 26B/31B).
+- **Colab link**: For swappable tutorials, link to the default model notebook (`-gemma-4-e2b-it.ipynb`). The model switcher updates the link dynamically when readers select other models.
 
 ### Headings and Anchor Links
 - Use standard markdown headings (`# H1`, `## 1. Step`, `### Substep`).
@@ -101,7 +106,7 @@ source_url: "https://..."  # Mandatory on imported pages; omitted on original pa
 To enable interactive model switching in code examples:
 ```python { .model-swap }
 # Use default model name in authoring; the JS switcher replaces it dynamically:
-model_id = "google/gemma-4-it"
+model_id = "google/gemma-4-E2B-it"
 ```
 
 ### Shared Links & Citations
@@ -124,16 +129,24 @@ To create or edit a tutorial that exports to a Jupyter notebook:
    from transformers import AutoModelForCausalLM
    ```
    ````
-2. **Display-Only Code**: Normal fences (without `.notebook-cell`) stay in Markdown and become text cells in notebooks.
-3. **Outputs**: Fences marked `{ .output }` are omitted during notebook export.
-4. **Site-Only Blocks**: Wrap web-only elements (such as interactive widgets or card grids) in skip comments:
+2. **Model-Swappable Cells**: Combine with `{ .model-swap }` to export multi-model notebooks:
+   ````markdown
+   ```python { .notebook-cell .model-swap }
+   model_id = "google/gemma-4-E2B-it"
+   ```
+   ````
+   During export, `scripts/notebooks.py` detects swappable engines in marked blocks and candidate models matching any `requires:` frontmatter. For swappable tutorials, it generates model-specific notebooks named `<stem>-gemma-4-<size>-it.ipynb` (e.g., `thinking-gemma-4-e2b-it.ipynb`, `thinking-gemma-4-12b-it.ipynb`). Non-swappable tutorials generate a single `<stem>.ipynb`.
+3. **Display-Only Code**: Normal fences (without `.notebook-cell`) stay in Markdown and become text cells in notebooks.
+4. **Outputs**: Fences marked `{ .output }` are omitted during notebook export.
+5. **Site-Only Blocks**: Wrap web-only elements (such as interactive widgets or card grids) in skip comments:
    ```markdown
    <!-- notebook:skip-start -->
    {{ engines(["ollama", "vllm"]) }}
    <!-- notebook:skip-end -->
    ```
-5. **Registration**: Register new notebook tutorials in `NOTEBOOKS` in `scripts/notebooks.py`.
-6. **Export**: Run `uv run --frozen python scripts/notebooks.py` to regenerate `docs/notebooks/*.ipynb`.
+6. **Registration**: Register new notebook source tutorials in `SOURCES` in `scripts/notebooks.py`.
+7. **Colab Link**: For swappable tutorials, add the default model notebook's Colab URL to frontmatter (`colab: .../<stem>-gemma-4-e2b-it.ipynb`). The page context switcher dynamically updates the link when readers select a different model.
+8. **Export & Verify**: Run `uv run --frozen python scripts/notebooks.py` to regenerate `docs/notebooks/*.ipynb`, and verify with `uv run --frozen python scripts/notebooks.py --check`.
 
 ---