Chore/merge recipes into examples

README.md

@@ -60,8 +60,8 @@ and is heavily commented as a living tutorial — uncomment the optional blocks
 ## Example: train, then branch & resume
 
 ```bash
-lighttrain train -c recipes/pretrain_causal.yaml
-lighttrain fork  --from runs/<...>/checkpoints/step_500 -c recipes/finetune.yaml
+lighttrain train -c examples/references/recipes/pretrain_causal.yaml
+lighttrain fork  --from runs/<...>/checkpoints/step_500 -c examples/references/recipes/finetune.yaml
 lighttrain resume --run runs/<...>
 ```
 
@@ -78,7 +78,7 @@ judge:   { name: verifier, verify_pattern: "\\d+" }   # → reward_fn
 Multi-model (a frozen teacher + a trainable student) is a named model set; a
 custom trainer reads `self.models["teacher"]`. A runnable end-to-end template:
 [examples/online_distill.py](examples/online_distill.py)
-(`lighttrain train -c recipes/online_distill_demo.yaml`).
+(`lighttrain train -c examples/references/recipes/online_distill_demo.yaml`).
 → [Training paradigms](docs/concepts/training.md)
 
 ## What you get

README.zh-CN.md

@@ -54,8 +54,8 @@ lighttrain train   -c cfg.yaml ++trainer.max_steps=50   # 50 步冒烟
 ## 示例：训练，然后分叉与恢复
 
 ```bash
-lighttrain train -c recipes/pretrain_causal.yaml
-lighttrain fork  --from runs/<...>/checkpoints/step_500 -c recipes/finetune.yaml
+lighttrain train -c examples/references/recipes/pretrain_causal.yaml
+lighttrain fork  --from runs/<...>/checkpoints/step_500 -c examples/references/recipes/finetune.yaml
 lighttrain resume --run runs/<...>
 ```
 
@@ -72,7 +72,7 @@ judge:   { name: verifier, verify_pattern: "\\d+" }   # → reward_fn
 多模型（冻结 teacher + 可训练 student）是命名模型集；自定义 trainer 读
 `self.models["teacher"]`。可跑的端到端模板：
 [examples/online_distill.py](examples/online_distill.py)
-（`lighttrain train -c recipes/online_distill_demo.yaml`）。
+（`lighttrain train -c examples/references/recipes/online_distill_demo.yaml`）。
 → [训练范式](docs/concepts/training.zh-CN.md)
 
 ## 训练产出

docs/changelog/v0/v0.5/v0.5.3.md

@@ -0,0 +1,37 @@
+# v0.5.3
+
+> **`recipes/` 并入 `examples/`(PR1 / 2,纯重定位)**:把仓库根的 `recipes/` 与 `examples/` 合并到统一的 `examples/references/` 树下——YAML 配方移入 `examples/references/recipes/`,程序化 API 示例脚本移入 `examples/references/`。保留「recipe」概念词(CLI、registry、测试分组名不变),仅改文件路径。零运行时行为变化,纯文件搬家 + 引用路径更新;注册表 **33 category / 134 entries** 不变。知名仓库的本地化移植(nanoGPT / MiniMind 等)将作为 PR2 落在 `examples/` 顶层,本轮不含。
+
+## 动机
+
+旧布局把可运行入口拆成两处:`recipes/*.yaml`(CLI 配方)与 `examples/*.py`(程序化示例),二者双向耦合——示例 `load_config("recipes/X.yaml")`,而 5 个演示配方又经 `user_modules:` 反向 import `examples/*.py` 里的自定义组件。合并到一棵 `examples/references/` 树后,两个方向的引用都落在同一子树内,概念更清晰,也为顶层放「知名仓库忠实移植」腾出位置。
+
+## 新布局
+
+```
+examples/
+  references/
+    recipes/                 # 全部 YAML 配方(原 recipes/,29 个)
+      pretrain_causal.yaml  grpo.yaml  ddp.yaml  ...
+    pretrain_causal.py  grpo.py  ...   # 程序化示例(原 examples/,23 个)
+    lab_components.py  vision_components.py  online_distill.py   # 被配方 user_modules 加载的共享组件
+    README.md
+  README.md                  # 顶层导航(知名仓库移植 → PR2)
+```
+
+- **canonical CLI 路径**:`lighttrain train -c examples/references/recipes/pretrain_causal.yaml`。
+- 共享组件 `lab_components.py`(被 ff_demo / mezo_sft / jepa / diffusion_eps / pcn_demo **5 个**配方共享)平铺在 `references/` 根,5 个配方都能引用——这也是不采用「一例一子目录」的原因(共享件无法同时住进 5 个子目录)。
+
+## 改动范围(机械、可逐一断言)
+
+- **物理移动(`git mv` 保历史)**:`recipes/*.yaml` → `examples/references/recipes/`;`examples/*.py` → `examples/references/`;`examples/README.md` → `examples/references/README.md`;新建顶层 `examples/README.md`;删空目录 `recipes/`。
+- **路径引用更新**:`recipes/` → `examples/references/recipes/`(配方注释、示例脚本的 `load_config` / docstring、README ×2、docs 的 concepts/extending/operations 共 8 篇、生产 docstring 与 CLI `--help` epilog 7 处、`scripts/rt.sh`、测试中的字符串/路径段形式);配方 `user_modules:` 与点式 import 中 `examples/{lab_components,vision_components,online_distill}` → `examples/references/...`。
+- **不改**:`docs/changelog/**`(历史记录,point-in-time 保留旧路径);「recipe」概念词与 `tests/recipes/` 测试目录名。
+
+## 验证
+
+- `pytest`:**4491 passed / 7 skipped / 0 failed**(路径敏感面:`tests/recipes/`、`test_all_recipes_loadable`、CLI、regression demo-recipe e2e 全绿)。
+- `ruff check .`:全净。
+- `mypy lighttrain tests`:575 文件零 error。
+- CLI 冒烟:`lighttrain train -c examples/references/recipes/pretrain_causal.yaml --print-config` 通。
+- 残留扫描:跟踪文件中除 `docs/changelog/**` 与 OOM 报告测试的任意假路径外,无残留旧 `recipes/` 引用。

docs/concepts/training.md

@@ -83,7 +83,7 @@ A custom trainer reaches them as `self.models["teacher"]` /
 
 Runnable end-to-end example: a student rolling out on-policy against a frozen
 teacher — [examples/online_distill.py](../../examples/online_distill.py)
-(`lighttrain train -c recipes/online_distill_demo.yaml`).
+(`lighttrain train -c examples/references/recipes/online_distill_demo.yaml`).
 
 ## PEFT & memory efficiency
 

docs/concepts/training.zh-CN.md

@@ -76,7 +76,7 @@ optimizers:
 
 可跑的端到端示例：student 在线 rollout 对抗冻结 teacher——
 [examples/online_distill.py](../../examples/online_distill.py)
-（`lighttrain train -c recipes/online_distill_demo.yaml`）。
+（`lighttrain train -c examples/references/recipes/online_distill_demo.yaml`）。
 
 ## PEFT 与显存效率
 

docs/extending/architectures.md

@@ -6,12 +6,12 @@ Stateful (RWKV, Mamba) and non-Transformer objectives ship as plugins, selected
 like any other model/objective:
 
 ```bash
-lighttrain train -c recipes/pretrain_rwkv.yaml   # RWKV stateful pretraining
-lighttrain train -c recipes/diffusion_eps.yaml   # diffusion eps-prediction
-lighttrain train -c recipes/jepa.yaml            # JEPA masked-patch prediction
-lighttrain train -c recipes/pcn_demo.yaml        # Predictive Coding Networks
-lighttrain train -c recipes/ff_demo.yaml         # Forward-Forward
-lighttrain train -c recipes/mezo_sft.yaml        # MeZO zero-order SFT
+lighttrain train -c examples/references/recipes/pretrain_rwkv.yaml   # RWKV stateful pretraining
+lighttrain train -c examples/references/recipes/diffusion_eps.yaml   # diffusion eps-prediction
+lighttrain train -c examples/references/recipes/jepa.yaml            # JEPA masked-patch prediction
+lighttrain train -c examples/references/recipes/pcn_demo.yaml        # Predictive Coding Networks
+lighttrain train -c examples/references/recipes/ff_demo.yaml         # Forward-Forward
+lighttrain train -c examples/references/recipes/mezo_sft.yaml        # MeZO zero-order SFT
 ```
 
 Built-in objectives carry a `loss_family`: `next_token`, `masked_denoising`,

docs/extending/architectures.zh-CN.md

@@ -6,12 +6,12 @@
 一样选用：
 
 ```bash
-lighttrain train -c recipes/pretrain_rwkv.yaml   # RWKV 有状态预训练
-lighttrain train -c recipes/diffusion_eps.yaml   # diffusion eps 预测
-lighttrain train -c recipes/jepa.yaml            # JEPA 掩码 patch 预测
-lighttrain train -c recipes/pcn_demo.yaml        # 预测编码网络
-lighttrain train -c recipes/ff_demo.yaml         # Forward-Forward
-lighttrain train -c recipes/mezo_sft.yaml        # MeZO 零阶 SFT
+lighttrain train -c examples/references/recipes/pretrain_rwkv.yaml   # RWKV 有状态预训练
+lighttrain train -c examples/references/recipes/diffusion_eps.yaml   # diffusion eps 预测
+lighttrain train -c examples/references/recipes/jepa.yaml            # JEPA 掩码 patch 预测
+lighttrain train -c examples/references/recipes/pcn_demo.yaml        # 预测编码网络
+lighttrain train -c examples/references/recipes/ff_demo.yaml         # Forward-Forward
+lighttrain train -c examples/references/recipes/mezo_sft.yaml        # MeZO 零阶 SFT
 ```
 
 内置 objective 带 `loss_family`：`next_token`、`masked_denoising`、

docs/extending/recipes.md

@@ -3,8 +3,8 @@
 > [中文版](recipes.zh-CN.md) · [Docs index](../README.md)
 
 The fastest way to start: copy a bundled recipe from
-[`recipes/`](../../recipes/) and edit it. Most run with
-`lighttrain train -c recipes/<name>.yaml`; the distributed overlays (below) are
+[`examples/references/recipes/`](../../examples/references/recipes/) and edit it. Most run with
+`lighttrain train -c examples/references/recipes/<name>.yaml`; the distributed overlays (below) are
 the exception — they layer onto a full recipe and need a multi-process launcher.
 
 ## Pretraining & SFT

docs/extending/recipes.zh-CN.md

@@ -2,8 +2,8 @@
 
 > [English](recipes.md) · [文档索引](../README.md)
 
-最快的起步方式：从 [`recipes/`](../../recipes/) 拷一个内置 recipe 改。多数 recipe 用
-`lighttrain train -c recipes/<名字>.yaml` 运行；分布式 overlay（见下）是例外——
+最快的起步方式：从 [`examples/references/recipes/`](../../examples/references/recipes/) 拷一个内置 recipe 改。多数 recipe 用
+`lighttrain train -c examples/references/recipes/<名字>.yaml` 运行；分布式 overlay（见下）是例外——
 需叠加到完整 recipe 之上，并用多进程启动器。
 
 ## 预训练与 SFT

docs/operations/distributed.md

@@ -60,7 +60,7 @@ engine:   { mixed_precision: "no" }
 ```
 
 Full recipe examples live under
-[`recipes/`](../../recipes).
+[`examples/references/recipes/`](../../recipes).
 
 ## See also
 

docs/operations/distributed.zh-CN.md

@@ -57,7 +57,7 @@ engine:   { mixed_precision: "no" }
 ```
 
 完整 recipe 示例见
-[`recipes/`](../../recipes)。
+[`examples/references/recipes/`](../../recipes)。
 
 ## 相关
 

examples/README.md

@@ -1,25 +1,16 @@
 # Examples
 
-One minimal Python script per recipe demonstrating the programmatic API.
-Each script can also be run directly, but the CLI (`lighttrain train -c <recipe>`)
-is the recommended entry point for day-to-day use.
+Runnable, end-to-end entry points for lighttrain.
 
-| Script | Recipe | What it shows |
-|--------|--------|---------------|
-| [pretrain_causal.py](pretrain_causal.py) | `pretrain_causal.yaml` | Basic causal LM pretraining |
-| [sft_chat.py](sft_chat.py) | `sft_chat.yaml` | Supervised fine-tuning |
-| [dpo_offline.py](dpo_offline.py) | `dpo_offline.yaml` | Offline DPO preference training |
-| [ppo_online.py](ppo_online.py) | `ppo_online.yaml` | Online PPO RL training |
-| [grpo.py](grpo.py) | `grpo.yaml` | GRPO group-relative optimization |
-| [student_kd.py](student_kd.py) | `student_kd.yaml` | Knowledge distillation |
-| [produce_teacher.py](produce_teacher.py) | `produce_teacher.yaml` | Teacher logit artifact production |
-| [qlora.py](qlora.py) | `qlora.yaml` | QLoRA 4-bit fine-tuning |
-| [offload_fullparam.py](offload_fullparam.py) | `offload_fullparam.yaml` | LayerOffload full-parameter training |
-| [pretrain_rwkv.py](pretrain_rwkv.py) | `pretrain_rwkv.yaml` | Stateful RWKV pretraining |
-| [diffusion_eps.py](diffusion_eps.py) | `diffusion_eps.yaml` | Diffusion ε-prediction |
-| [jepa.py](jepa.py) | `jepa.yaml` | JEPA joint-embedding predictive arch |
-| [pcn_demo.py](pcn_demo.py) | `pcn_demo.yaml` | Predictive Coding Network |
-| [ff_demo.py](ff_demo.py) | `ff_demo.yaml` | Forward-Forward algorithm |
-| [mezo_sft.py](mezo_sft.py) | `mezo_sft.yaml` | MeZO memory-efficient zeroth-order |
-| [sweep_demo.py](sweep_demo.py) | `sweep_demo.yaml` + `sweep_r15.yaml` | Hyperparameter sweep |
-| [fork_resume.py](fork_resume.py) | `fork_resume.yaml` | Fork + resume with lineage |
+| Directory | What it holds |
+|-----------|---------------|
+| [`references/`](references) | One minimal script + recipe per built-in capability — the canonical "how do I use feature X" reference set (pretraining, SFT, DPO/PPO/GRPO, distillation, QLoRA, offload, RWKV/diffusion/JEPA, sweeps, fork-resume). The recipes (YAML) live under [`references/recipes/`](references/recipes). |
+
+Faithful local ports of well-known training repos (e.g. nanoGPT, MiniMind) land
+at the top level of this directory, one self-contained folder each.
+
+Run any recipe via the CLI:
+
+```bash
+lighttrain train -c examples/references/recipes/pretrain_causal.yaml
+```

examples/references/README.md

@@ -0,0 +1,30 @@
+# Reference examples
+
+One minimal Python script per recipe demonstrating the programmatic API. The
+matching recipes (YAML configs) live in [`recipes/`](recipes); each script can
+also be run directly, but the CLI is the recommended entry point for day-to-day
+use:
+
+```bash
+lighttrain train -c examples/references/recipes/pretrain_causal.yaml
+```
+
+| Script | Recipe | What it shows |
+|--------|--------|---------------|
+| [pretrain_causal.py](pretrain_causal.py) | `pretrain_causal.yaml` | Basic causal LM pretraining |
+| [sft_chat.py](sft_chat.py) | `sft_chat.yaml` | Supervised fine-tuning |
+| [dpo_offline.py](dpo_offline.py) | `dpo_offline.yaml` | Offline DPO preference training |
+| [ppo_online.py](ppo_online.py) | `ppo_online.yaml` | Online PPO RL training |
+| [grpo.py](grpo.py) | `grpo.yaml` | GRPO group-relative optimization |
+| [student_kd.py](student_kd.py) | `student_kd.yaml` | Knowledge distillation |
+| [produce_teacher.py](produce_teacher.py) | `produce_teacher.yaml` | Teacher logit artifact production |
+| [qlora.py](qlora.py) | `qlora.yaml` | QLoRA 4-bit fine-tuning |
+| [offload_fullparam.py](offload_fullparam.py) | `offload_fullparam.yaml` | LayerOffload full-parameter training |
+| [pretrain_rwkv.py](pretrain_rwkv.py) | `pretrain_rwkv.yaml` | Stateful RWKV pretraining |
+| [diffusion_eps.py](diffusion_eps.py) | `diffusion_eps.yaml` | Diffusion ε-prediction |
+| [jepa.py](jepa.py) | `jepa.yaml` | JEPA joint-embedding predictive arch |
+| [pcn_demo.py](pcn_demo.py) | `pcn_demo.yaml` | Predictive Coding Network |
+| [ff_demo.py](ff_demo.py) | `ff_demo.yaml` | Forward-Forward algorithm |
+| [mezo_sft.py](mezo_sft.py) | `mezo_sft.yaml` | MeZO memory-efficient zeroth-order |
+| [sweep_demo.py](sweep_demo.py) | `sweep_demo.yaml` + `sweep_r15.yaml` | Hyperparameter sweep |
+| [fork_resume.py](fork_resume.py) | `fork_resume.yaml` | Fork + resume with lineage |

examples/diffusion_eps.py → examples/references/diffusion_eps.py

@@ -1,13 +1,13 @@
 """Diffusion ε-prediction — programmatic API example.
 
 Equivalent CLI:
-    lighttrain train -c recipes/diffusion_eps.yaml
+    lighttrain train -c examples/references/recipes/diffusion_eps.yaml
 """
 
 import lighttrain.builtin_plugins.optim.architectures.diffusion_unet  # noqa: F401
 from lighttrain.cli._runtime import setup_run_from_config
 from lighttrain.config import load_config
 
-cfg = load_config("recipes/diffusion_eps.yaml")
+cfg = load_config("examples/references/recipes/diffusion_eps.yaml")
 bundle = setup_run_from_config(cfg)
 bundle["trainer"].fit()

examples/dpo_offline.py → examples/references/dpo_offline.py

@@ -1,12 +1,12 @@
 """Offline DPO — programmatic API example.
 
 Equivalent CLI:
-    lighttrain train -c recipes/dpo_offline.yaml
+    lighttrain train -c examples/references/recipes/dpo_offline.yaml
 """
 
 from lighttrain.cli._runtime import setup_run_from_config
 from lighttrain.config import load_config
 
-cfg = load_config("recipes/dpo_offline.yaml")
+cfg = load_config("examples/references/recipes/dpo_offline.yaml")
 bundle = setup_run_from_config(cfg)
 bundle["trainer"].fit()

examples/ff_demo.py → examples/references/ff_demo.py

@@ -1,13 +1,13 @@
 """Forward-Forward algorithm — programmatic API example.
 
 Equivalent CLI:
-    lighttrain train -c recipes/ff_demo.yaml
+    lighttrain train -c examples/references/recipes/ff_demo.yaml
 """
 
 import lighttrain.builtin_plugins.engine.update_rules.forward_forward  # noqa: F401 — registers the ForwardForward update rule
 from lighttrain.cli._runtime import setup_run_from_config
 from lighttrain.config import load_config
 
-cfg = load_config("recipes/ff_demo.yaml")
+cfg = load_config("examples/references/recipes/ff_demo.yaml")
 bundle = setup_run_from_config(cfg)
 bundle["trainer"].fit()

examples/fork_resume.py → examples/references/fork_resume.py

@@ -1,9 +1,9 @@
 """Fork + resume with 3-generation lineage — programmatic API example (R16).
 
 Equivalent CLI sequence:
-    lighttrain train -c recipes/fork_resume.yaml
+    lighttrain train -c examples/references/recipes/fork_resume.yaml
     lighttrain fork --from runs/fork_gen1/<run>/checkpoints/step_50 \
-                    -c recipes/fork_resume.yaml ++optim.lr=1.5e-4 ++exp=fork_gen2
+                    -c examples/references/recipes/fork_resume.yaml ++optim.lr=1.5e-4 ++exp=fork_gen2
     lighttrain resume --run runs/fork_gen2/<run>
 """
 
@@ -19,12 +19,12 @@
 checkpoints = list(gen1_ckpt.glob("*/checkpoints/step_*"))
 if not checkpoints:
     raise FileNotFoundError(
-        "No gen1 checkpoint found. Run `lighttrain train -c recipes/fork_resume.yaml` first."
+        "No gen1 checkpoint found. Run `lighttrain train -c examples/references/recipes/fork_resume.yaml` first."
     )
 ckpt = sorted(checkpoints)[-1]
 
 # Fork gen1 → gen2 with halved LR
-cfg2 = load_config("recipes/fork_resume.yaml", ["++optim.lr=1.5e-4", "++exp=fork_gen2"])
+cfg2 = load_config("examples/references/recipes/fork_resume.yaml", ["++optim.lr=1.5e-4", "++exp=fork_gen2"])
 r2 = fork(ckpt, cfg2)
 print(f"Gen2 run dir: {r2.new_run_dir}")
 print(f"Lineage recorded: {r2.lineage_edge_recorded}")

examples/grpo.py → examples/references/grpo.py

@@ -1,12 +1,12 @@
 """GRPO — programmatic API example.
 
 Equivalent CLI:
-    lighttrain train -c recipes/grpo.yaml
+    lighttrain train -c examples/references/recipes/grpo.yaml
 """
 
 from lighttrain.cli._runtime import setup_run_from_config
 from lighttrain.config import load_config
 
-cfg = load_config("recipes/grpo.yaml")
+cfg = load_config("examples/references/recipes/grpo.yaml")
 bundle = setup_run_from_config(cfg)
 bundle["trainer"].fit()

examples/image_cls.py → examples/references/image_cls.py

@@ -6,12 +6,12 @@
 imports them, so no explicit plugin import is needed here.
 
 Equivalent CLI:
-    lighttrain train -c recipes/image_cls.yaml
+    lighttrain train -c examples/references/recipes/image_cls.yaml
 """
 
 from lighttrain.cli._runtime import setup_run_from_config
 from lighttrain.config import load_config
 
-cfg = load_config("recipes/image_cls.yaml")
+cfg = load_config("examples/references/recipes/image_cls.yaml")
 bundle = setup_run_from_config(cfg)
 bundle["trainer"].fit()

examples/jepa.py → examples/references/jepa.py

@@ -1,12 +1,12 @@
 """JEPA joint-embedding predictive architecture — programmatic API example.
 
 Equivalent CLI:
-    lighttrain train -c recipes/jepa.yaml
+    lighttrain train -c examples/references/recipes/jepa.yaml
 """
 
 from lighttrain.cli._runtime import setup_run_from_config
 from lighttrain.config import load_config
 
-cfg = load_config("recipes/jepa.yaml")
+cfg = load_config("examples/references/recipes/jepa.yaml")
 bundle = setup_run_from_config(cfg)
 bundle["trainer"].fit()

examples/mezo_sft.py → examples/references/mezo_sft.py

@@ -1,12 +1,12 @@
 """MeZO memory-efficient zeroth-order SFT — programmatic API example.
 
 Equivalent CLI:
-    lighttrain train -c recipes/mezo_sft.yaml
+    lighttrain train -c examples/references/recipes/mezo_sft.yaml
 """
 
 from lighttrain.cli._runtime import setup_run_from_config
 from lighttrain.config import load_config
 
-cfg = load_config("recipes/mezo_sft.yaml")
+cfg = load_config("examples/references/recipes/mezo_sft.yaml")
 bundle = setup_run_from_config(cfg)
 bundle["trainer"].fit()

examples/offload_fullparam.py → examples/references/offload_fullparam.py

@@ -1,13 +1,13 @@
 """Full-parameter training with LayerOffload — programmatic API example.
 
 Equivalent CLI:
-    lighttrain train -c recipes/offload_fullparam.yaml
+    lighttrain train -c examples/references/recipes/offload_fullparam.yaml
 """
 
 import lighttrain.builtin_plugins.layer_offload  # registers LayerOffloadEngine  # noqa: F401
 from lighttrain.cli._runtime import setup_run_from_config
 from lighttrain.config import load_config
 
-cfg = load_config("recipes/offload_fullparam.yaml")
+cfg = load_config("examples/references/recipes/offload_fullparam.yaml")
 bundle = setup_run_from_config(cfg)
 bundle["trainer"].fit()