docs(training): align cookbook docs and skill references with main

skills/dev/SKILL.md

@@ -62,7 +62,7 @@ The requirement lives in the cookbook's `training/pyproject.toml` — look for t
 
 ```bash
 grep 'fireworks-ai\[training\]' cookbook/training/pyproject.toml
-# e.g. "fireworks-ai[training]>=1.0.0a62,<2"
+# e.g. "fireworks-ai[training]>=1.2.0a66,<2"
 
 pip show fireworks-ai | grep -i version
 ```
@@ -71,7 +71,7 @@ If the installed version doesn't satisfy the pin, upgrade first and retry. Only
 
 ## Non-negotiables
 
-1. **Shape first.** `cfg.infra.training_shape_id` is required. The deployment shape comes from the profile. Manual infra fields are a mistake; the backend will reject or ignore them. See [`references/shapes.md`](references/shapes.md).
+1. **Shape first.** Prefer leaving `cfg.infra.training_shape_id` unset so recipes auto-select the smallest validated shape that fits; set it only when you need an explicit override. The deployment shape comes from the profile. Manual infra fields are a mistake; the backend will reject or ignore them. See [`references/shapes.md`](references/shapes.md).
 2. **`WeightSyncScope.PER_TRAINER` is the default.** Set `DeployConfig(weight_sync_scope=WeightSyncScope.PER_TRAINER)` (the default). Do not combine it with `hot_load_deployment_id` — that field belongs to `PER_DEPLOYMENT`. Pick one bucket scope. See [`references/rl/hotload.md`](references/rl/hotload.md#weight-sync-scope-per_trainer-vs-per_deployment).
 3. **Fork, don't reinvent.** Training loop plumbing lives in `training/recipes/`. Fork the file that matches the task; do not rewire `FiretitanTrainingClient` / `DeploymentManager` / `WeightSyncer` from scratch.
 4. **Validate `output_model_id` before promote.** Server cap is 63 chars, charset `[a-z0-9-]`. A rejected promote orphans the sampler blob; the same `checkpoint_id` returns "not found in GCS" after GC. See [`references/checkpoints.md`](references/checkpoints.md#output_model_id-validation).

skills/dev/references/checkpoints.md

@@ -63,7 +63,7 @@ Priority inside `TrainingCheckpoints.resume` (highest first):
 - `warm_start_from_adapter` and `init_from_checkpoint` are mutually exclusive.
 - Requires `lora_rank > 0`. Full-parameter continue-training uses `base_model` instead.
 
-Supported in all recipe loops: `sft_loop`, `dpo_loop`, `orpo_loop`, `rl_loop`, `igpo_loop`.
+Supported in all recipe loops: `sft_loop`, `dpo_loop`, `orpo_loop`, `rl_loop`, `async_rl_loop`, `igpo_loop`.
 
 ## Cross-run resume
 

skills/dev/references/examples.md

@@ -1,31 +1,32 @@
 # Out-of-the-box examples
 
-When the user wants "something that just runs", point them at `training/examples/`. Each subdirectory imports from `training/recipes/` and ships a ready-to-run `Config`.
+When the user wants "something that just runs", point them at `training/examples/`. Most subdirectories import from `training/recipes/` and ship a ready-to-run `Config`; the agentic examples may own a custom loop plus rollout code.
 
 | Task | Path |
 |------|------|
-| Minimal SFT (single-file demo) | `training/examples/sft_getting_started/` |
-| SFT on real datasets | `training/examples/sft/` |
+| SFT | `training/examples/sft/` |
 | DPO | `training/examples/dpo/` |
-| ORPO | `training/examples/orpo/` |
-| GRPO on deepmath | `training/examples/deepmath_rl/` |
-| Tool-use RL (frozen lake) | `training/examples/frozen_lake/` |
-| Multi-hop QA RL | `training/examples/multihop_qa/` |
-| Generic RL wiring | `training/examples/rl/` |
+| ORPO (IFEval) | `training/examples/orpo/ifeval/` |
+| GRPO on DeepMath | `training/examples/rl/deepmath/` |
+| Tool-use RL (Frozen Lake) | `training/examples/rl/frozen_lake/` |
+| Async RL single-turn (token-in rollout) | `training/examples/rl/single_turn_token_in/` |
+| Async RL multi-turn (message-in rollout) | `training/examples/rl/multi_turn_message_in/` |
+| Multi-hop QA async RL (+ optional IGPO) | `training/examples/multihop_qa/` |
+| Manual hotload-scope tests (PER_TRAINER re-attach, PER_DEPLOYMENT) | `training/examples/manual/` |
 
 ## What to read
 
-In each example directory, read the top-level `train_*.py` (or `main.py`) — it builds the `Config` and calls `main(config)` from the corresponding recipe. That's the whole script.
+In each example directory, read the top-level `train_*.py`, `train.py`, or `rollout.py` — it builds the `Config` or rollout function and calls the corresponding recipe/helper.
 
 ## Running
 
 ```bash
 cd cookbook/training
-pip install -e .
-python examples/sft_getting_started/<script>.py
+pip install --pre -e .
+python examples/sft/train_sft.py --output-model-id <model-id>
 ```
 
-Every example pulls `FIREWORKS_API_KEY` from the env (or `.env`). If the example needs a dataset path, it is listed in its `README.md`.
+Every example pulls `FIREWORKS_API_KEY` from the env (or `.env`). If an example needs a dataset path or extra arguments, check that script's `argparse` block, `README.md`, or `run.sh`.
 
 ## When the example isn't quite right
 

skills/dev/references/recipes.md

@@ -7,7 +7,7 @@ Each recipe is a single Python file in `training/recipes/` that wires the Traini
 | SFT | `training/recipes/sft_loop.py` |
 | DPO | `training/recipes/dpo_loop.py` |
 | ORPO | `training/recipes/orpo_loop.py` |
-| Importance-weighted GRPO | `training/recipes/igpo_loop.py` |
+| Information Gain-based Policy Optimization (IGPO) | `training/recipes/igpo_loop.py` |
 | Generic RL loop (GRPO scaffold) | `training/recipes/rl_loop.py` |
 | Async RL loop (rollout/train overlap, PPO inner minibatches) | `training/recipes/async_rl_loop.py` — see [`rl/async-rl.md`](rl/async-rl.md) |
 
@@ -23,7 +23,7 @@ Always required on `Config` + `InfraConfig`:
 - `dataset` — path to JSONL
 - `tokenizer_model` — HF model name
 - `log_path` — directory for `dataloader.json` and logs
-- `infra.training_shape_id` — **required**; do not set manual `accelerator_type` / `node_count` (see [`shapes.md`](shapes.md))
+- `infra.training_shape_id` — optional override; leave unset for auto-selection. Do not set manual `accelerator_type` / `node_count` (see [`shapes.md`](shapes.md))
 
 RL-specific (in `rl_loop.py`'s `Config`): reward function, rollout batch sizes, deployment config (shape is auto-filled from the profile).
 

skills/dev/references/shapes.md

@@ -4,7 +4,14 @@ Shapes are the required entry point for both trainer and deployment. Never hand-
 
 ## Training shape
 
-Set `cfg.infra.training_shape_id`:
+By default, recipes auto-select the smallest validated training shape that can
+fit the configured model and context length:
+
+```python
+cfg.infra.training_shape_id = None
+```
+
+Set `cfg.infra.training_shape_id` only when you need an explicit override:
 
 ```python
 cfg.infra.training_shape_id = "accounts/fireworks/trainingShapes/ts-qwen3-8b-policy"
@@ -13,14 +20,14 @@ cfg.infra.training_shape_id = "accounts/fireworks/trainingShapes/ts-qwen3-8b-pol
 The recipe then does:
 
 ```python
-profile = rlor_mgr.resolve_training_profile(cfg.infra.training_shape_id)
+profile = rlor_mgr.resolve_training_profile(resolved_training_shape_id)
 # profile.training_shape_version
 # profile.deployment_shape_version
 # profile.max_supported_context_length
 # profile.accelerator_type, profile.node_count, ...  (read, do not copy to cfg)
 ```
 
-See `training/recipes/sft_loop.py` (search `resolve_training_profile`) and `training/recipes/rl_loop.py` (same — called once per policy, once per reference).
+See `training/recipes/sft_loop.py` (search `auto_select_training_shape`) and `training/utils/infra.py` for the shared RL / DPO infra path.
 
 ## Deployment shape
 
@@ -35,7 +42,7 @@ That is a **versioned** path (`accounts/fw/deploymentShapes/ds-x/versions/abc123
 
 ## Reference-model shape (RL / DPO)
 
-For **full-parameter** training with a frozen reference, set `cfg.infra.ref_training_shape_id` explicitly — there is no implicit fallback. It can share the same shape as the policy; the control plane appends `--forward-only` automatically.
+For **full-parameter** training with a frozen reference, leave `ref_training_shape_id` unset to auto-select a compatible validated shape. Set it explicitly only when you need an override; it can share the same shape as the policy, and the control plane appends `--forward-only` automatically.
 
 For **LoRA** (`lora_rank > 0`), two valid options:
 - **Shared session (recommended, saves GPUs)**: leave `ref_training_shape_id` unset. `setup_infra` uses `policy.create_base_reference()` on the policy trainer for reference logprobs — no separate trainer, no extra GPUs.

training/README.md

@@ -10,6 +10,8 @@ Each recipe is a single Python file you can fork and customize.
 | Recipe | File | Description |
 | --- | --- | --- |
 | GRPO / IS / DAPO / DRO / GSPO / CISPO | `recipes/rl_loop.py` | On-policy RL with streaming rollouts. Set `policy_loss="grpo"`, `"importance_sampling"`, `"dapo"`, `"dro"`, `"gspo"`, or `"cispo"`. |
+| Async RL (any of the above losses) | `recipes/async_rl_loop.py` | Gate-native async RL: rollout/train overlap with bounded off-policy staleness. Strict superset of `rl_loop.py`; recommended for new RL work. |
+| IGPO (multi-turn turn-level Information Gain) | `recipes/igpo_loop.py` | GRPO + per-turn IG rewards for agent trajectories (Wang et al., ICLR 2026). |
 | DPO | `recipes/dpo_loop.py` | Direct preference optimization with cached reference logprobs. |
 | ORPO | `recipes/orpo_loop.py` | Odds-ratio preference optimization -- no reference model needed. |
 | SFT | `recipes/sft_loop.py` | Supervised fine-tuning with response-only cross-entropy loss. |
@@ -145,15 +147,19 @@ For detailed guides, configuration reference, and examples, see the official doc
 ## Directory layout
 
 ```
-recipes/                 Training loop scripts (fork these)
-utils/                   Shared config, data loading, loss functions, metrics
-examples/rl/deepmath/    Worked example: math reasoning with GRPO
-examples/rl/frozen_lake/ Worked example: Frozen Lake with tool-use RL
-examples/orpo/ifeval/    Worked example: IFEval with ORPO
-examples/sft/            Worked example: SFT getting started
-examples/dpo/            Worked example: DPO
-examples/snippets/       Standalone utility scripts
-tests/                   Unit and end-to-end tests
+recipes/                                Training loop scripts (fork these)
+utils/                                  Shared config, data loading, loss functions, metrics
+examples/sft/                           Worked example: SFT getting started
+examples/dpo/                           Worked example: DPO
+examples/orpo/ifeval/                   Worked example: IFEval with ORPO
+examples/rl/deepmath/                   GRPO on DeepMath (rl_loop)
+examples/rl/frozen_lake/                Frozen Lake tool-use RL (custom loop)
+examples/rl/single_turn_token_in/       Async RL single-turn, token-in rollout
+examples/rl/multi_turn_message_in/      Async RL multi-turn, message-in rollout
+examples/multihop_qa/                   Multi-hop QA async RL (+ optional IGPO turn-level scoring)
+examples/manual/                        Manual hotload-scope tests (PER_TRAINER / PER_DEPLOYMENT)
+examples/tools/                         Standalone utility scripts
+tests/                                  Unit and end-to-end tests
 ```
 
 ## Tests

training/examples/tools/README.md

@@ -1,8 +1,10 @@
-# Snippets
+# Tools
 
 Standalone utility scripts that complement the main cookbook recipes.
 
 | Script | Description |
 |--------|-------------|
-| `promote_checkpoint.py` | Promote a sampler checkpoint from `checkpoints.jsonl` to a deployable Fireworks model. |
+| `promote_checkpoint.py` | Promote a sampler checkpoint from the control plane checkpoint list to a deployable Fireworks model. |
+| `list_checkpoints.py` | List checkpoint rows known to the control plane for a trainer job. |
 | `reconnect_and_adjust_lr.py` | Reconnect to an existing trainer job and adjust the learning rate mid-run. |
+| `verify_logprobs.py` | Compare inference-time and training-time logprobs for a checkpoint. |

training/pyproject.toml

@@ -7,7 +7,7 @@ name = "fireworks-training-cookbook"
 version = "0.1.0"
 requires-python = ">=3.11"
 dependencies = [
-    "fireworks-ai[training]>=1.2.0a65,<2",
+    "fireworks-ai[training]>=1.2.0a66,<2",
     "tqdm",
     "torch",
     "datasets",