@@ -0,0 +1,13 @@
+# Training Feature Examples
+
+This directory groups examples that focus on training-system features rather than model families or checkpoint conversion.
+
+## Contents
+
+| Directory | Focus |
+|-----------|-------|
+| `decentralized_pg/` | Explicit process-group construction and `use_decentralized_pg=True` training runs |
+| `long_context/` | Long-context training launch examples |
+| `resiliency/` | Fault tolerance and straggler detection examples |
+
+Run commands from the repository root so relative paths in the child READMEs and launch scripts resolve correctly.
@@ -25,10 +25,10 @@ Just use an existing recipe and enable decentralized process groups:
 
 ```bash
 # 8 GPUs: TP2 x PP2 x DP2
-uv run python -m torch.distributed.run --nproc_per_node=8 examples/decentralized_pg/pretrain_qwen3_simple.py
+uv run python -m torch.distributed.run --nproc_per_node=8 examples/training_features/decentralized_pg/pretrain_qwen3_simple.py
 
 # 4 GPUs: TP2 x PP2 x DP1
-uv run python -m torch.distributed.run --nproc_per_node=4 examples/decentralized_pg/pretrain_qwen3_simple.py
+uv run python -m torch.distributed.run --nproc_per_node=4 examples/training_features/decentralized_pg/pretrain_qwen3_simple.py
 ```
 
 The key is just two lines:
@@ -53,14 +53,14 @@ For full control over process groups:
 
 ```bash
 # 8 GPUs: TP2 x PP2 x DP2
-uv run python -m torch.distributed.run --nproc_per_node=8 examples/decentralized_pg/pretrain_qwen3_with_decentralized_pg.py
+uv run python -m torch.distributed.run --nproc_per_node=8 examples/training_features/decentralized_pg/pretrain_qwen3_with_decentralized_pg.py
 
 # 4 GPUs: TP2 x PP2 x DP1
-uv run python -m torch.distributed.run --nproc_per_node=4 examples/decentralized_pg/pretrain_qwen3_with_decentralized_pg.py \
+uv run python -m torch.distributed.run --nproc_per_node=4 examples/training_features/decentralized_pg/pretrain_qwen3_with_decentralized_pg.py \
     --tp-size 2 --pp-size 2
 
 # 2 GPUs: TP2 x PP1 x DP1
-uv run python -m torch.distributed.run --nproc_per_node=2 examples/decentralized_pg/pretrain_qwen3_with_decentralized_pg.py \
+uv run python -m torch.distributed.run --nproc_per_node=2 examples/training_features/decentralized_pg/pretrain_qwen3_with_decentralized_pg.py \
     --tp-size 2 --pp-size 1
 ```
 
 
@@ -54,21 +54,21 @@
 ----------
 # 8 GPUs: TP2 x PP2 x CP_train=1 x CP_eval=2 (default; shows bubble-shrink win)
 uv run python -m torch.distributed.run --nproc_per_node=8 \\
-    examples/decentralized_pg/pretrain_qwen3_eval_cp.py
+    examples/training_features/decentralized_pg/pretrain_qwen3_eval_cp.py
 
 # 8 GPUs, longer seq for the cleanest Step 7b speedup demo (~1.78x at PP=2):
 uv run python -m torch.distributed.run --nproc_per_node=8 \\
-    examples/decentralized_pg/pretrain_qwen3_eval_cp.py \\
+    examples/training_features/decentralized_pg/pretrain_qwen3_eval_cp.py \\
     --num-layers 8 --seq-length 16384
 
 # 8 GPUs at PP=4 (largest bubble win, ~1.88x):
 uv run python -m torch.distributed.run --nproc_per_node=8 \\
-    examples/decentralized_pg/pretrain_qwen3_eval_cp.py \\
+    examples/training_features/decentralized_pg/pretrain_qwen3_eval_cp.py \\
     --tp-size 1 --pp-size 4 --num-layers 8 --seq-length 16384
 
 # 4 GPUs: TP2 x PP1 x CP_train=1 x CP_eval=2 (no bubble; expect Step 7b regression)
 uv run python -m torch.distributed.run --nproc_per_node=4 \\
-    examples/decentralized_pg/pretrain_qwen3_eval_cp.py \\
+    examples/training_features/decentralized_pg/pretrain_qwen3_eval_cp.py \\
     --tp-size 2 --pp-size 1 --cp-train 1 --cp-eval 2
 
 Prerequisites
 
@@ -27,10 +27,10 @@
 How to Run
 ----------
 # 8 GPUs: TP2 x PP2 x DP2
-uv run python -m torch.distributed.run --nproc_per_node=8 examples/decentralized_pg/pretrain_qwen3_simple.py
+uv run python -m torch.distributed.run --nproc_per_node=8 examples/training_features/decentralized_pg/pretrain_qwen3_simple.py
 
 # 4 GPUs: TP2 x PP2 x DP1
-uv run python -m torch.distributed.run --nproc_per_node=4 examples/decentralized_pg/pretrain_qwen3_simple.py
+uv run python -m torch.distributed.run --nproc_per_node=4 examples/training_features/decentralized_pg/pretrain_qwen3_simple.py
 """
 
 import torch
 
@@ -27,7 +27,7 @@
 How to Run
 ----------
 # 8 GPUs: EP8
-uv run python -m torch.distributed.run --nproc_per_node=8 examples/decentralized_pg/pretrain_qwen3_vl_simple.py
+uv run python -m torch.distributed.run --nproc_per_node=8 examples/training_features/decentralized_pg/pretrain_qwen3_vl_simple.py
 """
 
 import torch
 
@@ -37,14 +37,14 @@
 How to Run
 ----------
 # 8 GPUs: TP2 x PP2 x DP2
-uv run python -m torch.distributed.run --nproc_per_node=8 examples/decentralized_pg/pretrain_qwen3_with_decentralized_pg.py
+uv run python -m torch.distributed.run --nproc_per_node=8 examples/training_features/decentralized_pg/pretrain_qwen3_with_decentralized_pg.py
 
 # 4 GPUs: TP2 x PP2 x DP1
-uv run python -m torch.distributed.run --nproc_per_node=4 examples/decentralized_pg/pretrain_qwen3_with_decentralized_pg.py \
+uv run python -m torch.distributed.run --nproc_per_node=4 examples/training_features/decentralized_pg/pretrain_qwen3_with_decentralized_pg.py \
     --tp-size 2 --pp-size 2
 
 # 2 GPUs: TP2 x PP1 x DP1
-uv run python -m torch.distributed.run --nproc_per_node=2 examples/decentralized_pg/pretrain_qwen3_with_decentralized_pg.py \
+uv run python -m torch.distributed.run --nproc_per_node=2 examples/training_features/decentralized_pg/pretrain_qwen3_with_decentralized_pg.py \
     --tp-size 2 --pp-size 1
 """
 
 
@@ -21,27 +21,27 @@ Examples demonstrating Megatron-Bridge resiliency features powered by [nvidia-re
 Detects slow-performing GPUs during training using NVRx straggler detection.
 
 ```bash
-uv run python -m torch.distributed.run --nproc_per_node=2 examples/resiliency/straggler_detection/straggler_detection_example.py
+uv run python -m torch.distributed.run --nproc_per_node=2 examples/training_features/resiliency/straggler_detection/straggler_detection_example.py
 ```
 
 Or use the launch script:
 
 ```bash
-./examples/resiliency/straggler_detection/run_straggler_detection.sh
+./examples/training_features/resiliency/straggler_detection/run_straggler_detection.sh
 ```
 
 ### Fault Tolerance
 
 Enables automatic hang detection and job restart using the `ft_launcher`.
 
 ```bash
-./examples/resiliency/fault_tolerance/run_fault_tolerance.sh
+./examples/training_features/resiliency/fault_tolerance/run_fault_tolerance.sh
 ```
 
 To test fault recovery with simulated failures:
 
 ```bash
-./examples/resiliency/fault_tolerance/run_fault_tolerance.sh --simulate-fault
+./examples/training_features/resiliency/fault_tolerance/run_fault_tolerance.sh --simulate-fault
 ```
 
 Note: Fault simulation requires careful timing - the fault must trigger after a checkpoint is saved but before training completes. See the `--simulate-fault` option in `fault_tolerance_example.py` for details.
@@ -46,15 +46,15 @@
         --nnodes=1 --nproc-per-node=2 \\
         --ft-rank_section_timeouts=setup:600,step:180,checkpointing:420 \\
         --ft-rank_out_of_section_timeout=300 \\
-        examples/resiliency/fault_tolerance/fault_tolerance_example.py
+        examples/training_features/resiliency/fault_tolerance/fault_tolerance_example.py
 
     # With fault simulation:
     uv run ft_launcher ... --max-restarts=3 \\
-        examples/resiliency/fault_tolerance/fault_tolerance_example.py --simulate-fault
+        examples/training_features/resiliency/fault_tolerance/fault_tolerance_example.py --simulate-fault
 
     # Or use the launch script:
-    ./examples/resiliency/fault_tolerance/run_fault_tolerance.sh
-    ./examples/resiliency/fault_tolerance/run_fault_tolerance.sh --simulate-fault
+    ./examples/training_features/resiliency/fault_tolerance/run_fault_tolerance.sh
+    ./examples/training_features/resiliency/fault_tolerance/run_fault_tolerance.sh --simulate-fault
 
 Documentation:
     - Megatron-Bridge: https://docs.nvidia.com/nemo/megatron-bridge/latest/training/resiliency.html