docs: add VLM training demo

CHANGELOG.md

@@ -30,6 +30,10 @@ will make up v0.1.0.
   per-modality support-status table
 - `tools/ci/check_doc_links.py`, a link checker for relative Markdown links, run
   as a required `doc_links` CI job
+- `docs/tutorials/`, an index of end-to-end tutorials grouped by application
+  area. The materials tutorial moved from `docs/materials_prism_tutorial.md` to
+  `docs/tutorials/material_science/materials_prism_tutorial.md`; notebooks stay
+  next to their scripts in `applications/<area>/`
 
 ### Changed
 

CONTRIBUTING.md

@@ -274,6 +274,7 @@ descriptions and return types where they are not obvious from the signature.
   | `modalities/` | Encoders, projectors, output decoders |
   | `models/` | Backbone integrations |
   | `evaluation/` | Universal evaluator, vLLM inference |
+  | `tutorials/` | End-to-end walkthroughs, one folder per application area; notebooks stay in the top-level `applications/<area>/`, not `docs/applications/` |
   | `applications/` | Scientific applications (BioReason, KEGG, materials) |
   | `api/` | API reference for the public `src.*` surface |
   | `development/` | CI and contributor tooling |

README.md

@@ -375,6 +375,7 @@ PRISM/
 [docs/index.md](docs/index.md) indexes every page. Most-used entry points:
 
 - [docs/getting-started.md](docs/getting-started.md) — clone → environment → first run
+- [docs/tutorials/README.md](docs/tutorials/README.md) — end-to-end tutorials by application area (BioReason, materials, …)
 - [docs/platforms/site_paths.md](docs/platforms/site_paths.md) — configuring the `PRISM_*` roots
 - [docs/platforms/aurora_operations.md](docs/platforms/aurora_operations.md) — Aurora ops, env, CCL tuning, troubleshooting
 - [docs/training/training.md](docs/training/training.md) — training stages

docs/index.md

@@ -98,6 +98,19 @@ loadable as Claude agent skills or read as docs. See the
 | [getting-started.md](getting-started.md) | Clone, pick a platform, build an environment, run a first job |
 | [training/cli.md](training/cli.md) | Unified CLI (`prism`) reference: installation, commands, options, examples |
 
+### Tutorials — `tutorials/`
+
+End-to-end walkthroughs, grouped by application area. Pages live in
+`tutorials/<area>/`; notebooks live next to their scripts in the top-level
+[`applications/<area>/`](../applications/) directory.
+
+| Document | Description |
+|----------|-------------|
+| [tutorials/README.md](tutorials/README.md) | Every tutorial by application area, and where a new one goes |
+| [../applications/bioreason/bioreason_demo.ipynb](../applications/bioreason/bioreason_demo.ipynb) | BioReason notebook: train a DNA + language model through projector alignment, SFT, GRPO, and KEGG evaluation on Aurora |
+| [tutorials/material_science/materials_prism_tutorial.md](tutorials/material_science/materials_prism_tutorial.md) | Materials: jointly train on crystal structures and text descriptions to predict a material property |
+| [tutorials/vision_language/vlm_training_demo.md](tutorials/vision_language/vlm_training_demo.md) | Vision language: train an image projector between frozen SigLIP2 and OLMo-1B on PixMo-Cap, as a 2-node DDP or HSDP job on Aurora |
+
 ### Platforms — `platforms/`
 
 Environment build and job submission, one page per machine, plus the

docs/tutorials/README.md

@@ -0,0 +1,30 @@
+# Tutorials
+
+Hands-on walkthroughs of PRISM on a scientific application, grouped by
+application area. Each one walks a single configuration from environment and
+data through training.
+
+Tutorial pages live here, in `docs/tutorials/<area>/`. Notebooks live in
+[`applications/<area>/`](../../applications/), next to the scripts they call.
+
+For reference material on the same applications, such as pipeline designs and
+evaluation invocations, see [`docs/applications/`](../applications/).
+
+| Area | Tutorial | Modalities | Platform |
+|---|---|---|---|
+| Biology | [BioReason: train a DNA + language model](../../applications/bioreason/bioreason_demo.ipynb) (notebook): projector alignment, SFT, GRPO, and KEGG evaluation, submitted as chained PBS jobs | DNA + text | Aurora |
+| Materials science | [Jointly train on material descriptions and crystal structures](material_science/materials_prism_tutorial.md): predict a material property from a CIF crystal graph and a text description | Crystal graph + text | CUDA, XPU, or CPU |
+| Vision language | [Train a vision-language projector](vision_language/vlm_training_demo.md): project frozen SigLIP2 features into a frozen OLMo-1B on PixMo-Cap, launched as a 2-node DDP or HSDP job and logged to W&B | Image + text | Aurora |
+
+## Adding a tutorial
+
+- Put Markdown pages in `docs/tutorials/<area>/`, where `<area>` is the
+  application's directory under `applications/`, or the name that directory
+  would take if the application has no scripts there yet.
+- Put a notebook in `applications/<area>/`, next to the scripts it runs, and
+  link to it from this page.
+- Add a row to the table above and to the Tutorials section of
+  [`docs/index.md`](../index.md).
+- Run `make docs` before pushing. It checks relative links in Markdown files
+  the same way CI does. Links inside notebooks are not checked, so test those
+  by hand after moving a notebook.

docs/materials_prism_tutorial.md → docs/tutorials/material_science/materials_prism_tutorial.md

@@ -89,7 +89,7 @@ python applications/material_science/stage_materials_text_model.py \
   --cache-dir /path/to/shared/huggingface/hub
 ```
 
-Then point Hugging Face at that cache when launching training, according to your cluster's setup. The tokenizer and model name passed to `--text-model` must match the staged model. On Polaris, see [the materials guide](applications/materials_multimodal.md) for the PBS launcher and cache environment settings.
+Then point Hugging Face at that cache when launching training, according to your cluster's setup. The tokenizer and model name passed to `--text-model` must match the staged model. On Polaris, see [the materials guide](../../applications/materials_multimodal.md) for the PBS launcher and cache environment settings.
 
 ## 5. What PRISM does with the two inputs