📝 Update docs and add training information

Author: jemrobinson

docs/src/how-to/index.md

@@ -0,0 +1,7 @@
+# How-to guides
+
+Step-by-step guides for common tasks.
+
+- [Add a new model](add-a-model.md) - implement a custom architecture
+- [Train a model](train.md) - run single-stage end-to-end training
+- [Train in stages](train-multistage.md) - pretrain each component separately before finetuning

docs/src/how-to/train-multistage.md

@@ -1,30 +1,30 @@
-# Train in stages
+# Run multistage training
 
-Staged training is an alternative to end-to-end training for `EncodeProcessDecode` models.
+Multistage training is an alternative to [normal training](./train.md) for `EncodeProcessDecode` models.
 Instead of training the full model in one pass, each component is trained in isolation before the weights are loaded into the full model for a final finetuning step.
 This can be useful when the model is large, when encoder inputs have very different characteristics, or when you want finer control over the training of individual components.
 
 ## The four stages
 
-**Stage 1 — Train encoders**
+**Stage 1 - Train encoders**
 
 Each encoder is trained independently as a standalone autoencoder (encoder + disposable decoder). One training run per encoder.
 
 ![Stage 1 diagram](../assets/staged-training-stage1.png)
 
-**Stage 2 — Train decoder**
+**Stage 2 - Train decoder**
 
 The decoder is trained on the combined frozen encoder latents from stage 1.
 
 ![Stage 2 diagram](../assets/staged-training-stage2.png)
 
-**Stage 3 — Train processor**
+**Stage 3 - Train processor**
 
 The processor is trained with frozen encoders and decoder from stages 1–2.
 
 ![Stage 3 diagram](../assets/staged-training-stage3.png)
 
-**Stage 4 — Finetune**
+**Stage 4 - Finetune**
 
 Pretrained weights are loaded into the full `EncodeProcessDecode` model and the entire model is trained end-to-end.
 
@@ -36,7 +36,7 @@ Pretrained weights are loaded into the full `EncodeProcessDecode` model and the
 uv run imp train --multistage
 ```
 
-A checkpoint is saved at the end of each stage. To resume a partially completed run, pass `--checkpoint-dir` pointing at the checkpoint directory from the original run — any stage whose checkpoint already exists there will be skipped:
+A checkpoint is saved at the end of each stage. To resume a partially completed run, pass `--checkpoint-dir` pointing at the checkpoint directory from the original run - any stage whose checkpoint already exists there will be skipped:
 
 ```bash
 uv run imp train --multistage --checkpoint-dir ${BASE_DIR}/training/wandb/run-<date>-<id>/checkpoints

docs/src/how-to/train.md

@@ -0,0 +1,52 @@
+# Train a model
+
+Single-stage training trains the full model end-to-end in one pass.
+It is the default and works for all model architectures.
+
+```bash
+uv run imp train
+```
+
+## Prerequisites
+
+You will need a [Weights & Biases account](https://docs.wandb.ai/models/quickstart).
+Generate an API key, then authenticate before running any training command:
+
+```bash
+export WANDB_API_KEY=<your_api_key>
+wandb login
+```
+
+## Configuring training
+
+Training is controlled by the `train` section of your config.
+The most commonly adjusted settings are:
+
+```yaml
+train:
+  optimizer:
+    lr: 1e-3
+    weight_decay: 1e-4
+  scheduler:
+    T_max: 20
+    eta_min: 1e-5
+  trainer:
+    max_epochs: 20
+    accelerator: auto
+```
+
+## Checkpoints
+
+A checkpoint is saved after each epoch to:
+
+```
+${BASE_DIR}/training/wandb/run-<date>-<id>/checkpoints/
+```
+
+where `BASE_DIR` is the `base_path` defined in your local config.
+Pass this path to `evaluate` to assess the trained model.
+
+## Multistage training
+
+For `EncodeProcessDecode` models, components can be pretrained in isolation before a final finetuning step.
+See [Run multistage training](train-multistage.md) for details.

docs/src/index.md

@@ -5,8 +5,8 @@ It performs multi-modal data fusion across satellite, sensor and post-processed
 
 ## Getting started
 
-- [User Guide](user-guide/index.md) — installation, configuration, and the `imp` CLI
-- [API Reference](api/index.md) — every public module, class, and function
+- [User Guide](user-guide/index.md) - installation, configuration, and the `imp` CLI
+- [API Reference](api/index.md) - every public module, class, and function
 
 ## Quick install
 

docs/src/user-guide/index.md

@@ -1,3 +1,3 @@
 # User Guide
 
-This guide covers everything you need to get IceNet-MP running — from installing the package to training a model and visualising results.
+This guide covers everything you need to get IceNet-MP running - from installing the package to training a model and visualising results.

zensical.toml

@@ -15,8 +15,10 @@ nav = [
         { "Commands" = "user-guide/commands.md" },
     ] },
     { "How-to" = [
+        { "Overview" = "how-to/index.md" },
         { "Add a model" = "how-to/add-a-model.md" },
-        { "Train in stages" = "how-to/train-in-stages.md" },
+        { "Train a model" = "how-to/train.md" },
+        { "Run multistage training" = "how-to/train-multistage.md" },
     ] },
     { "API Reference" = [
         { "Overview" = "api/index.md" },