refactor(examples): group per-backend material under its backend dire…

.github/workflows/deploy-backend-gap-dashboard.yml

@@ -22,7 +22,7 @@ on:
     paths:
       - "tools/backend_gap_report/**"
       - "tools/pip_index/**"
-      - "examples/deepseek-v4/projection/site/**"
+      - "examples/megatron/models/deepseek-v4/projection/site/**"
       - ".github/workflows/deploy-backend-gap-dashboard.yml"
 
 permissions:

.gitignore

@@ -21,8 +21,8 @@ pp_simulation_result
 
 # Allow the projection site's breakdown JSON (consumed by the static site /
 # GitHub Pages) despite the generic `data` ignore above.
-!examples/deepseek-v4/projection/site/data/
-!examples/deepseek-v4/projection/site/data/*.json
+!examples/megatron/models/deepseek-v4/projection/site/data/
+!examples/megatron/models/deepseek-v4/projection/site/data/*.json
 
 *.log
 *.nohup

README.md

@@ -41,7 +41,7 @@ For the full and up-to-date model matrix, see [Supported Models](./docs/06-devel
 - **[2026/07/29]** ⚡ **MegaMoE** - FlyDSL-based fused MoE layer that folds expert all-to-all into the grouped GEMMs, plus FP4 grouped GEMM support ([MegaMoE guide](./docs/04-technical-guides/mega-moe.md))
 - **[2026/07/29]** Hybrid linear-attention models: Gated Delta Net (GDN) and Kimi Delta Attention (KDA) on Megatron-LM ([Hybrid models](./docs/04-technical-guides/hybrid-models/README.md))
 - **[2026/07/22]** Backend upgrades: TorchTitan v0.2.2 (PyTorch 2.12) with GPT-OSS, and MaxText v26.5
-- **[2026/07/17]** 🚀 **DeepSeek-V4 training support** - model definition, fused attention/MoE kernels, Muon optimizer, FP8/FP4 recipes, and a projection toolkit ([examples](./examples/deepseek-v4))
+- **[2026/07/17]** 🚀 **DeepSeek-V4 training support** - model definition, fused attention/MoE kernels, Muon optimizer, FP8/FP4 recipes, and a projection toolkit ([examples](./examples/megatron/models/deepseek-v4))
 - **[2026/07/16]** 🎨 **Diffusion backend** - Flux.1 image and Wan video training with FP8/MXFP4, FSDP2, and Energon data pipelines ([Diffusion docs](./docs/04-technical-guides/diffusion-models/README.md))
 - **[2026/07/14]** MLPerf Training 6.0 examples on MI355X: Llama2-70B LoRA, Llama3.1-8B, and GPT-OSS-20B ([examples](./examples/mlperf))
 - **[2026/06/15]** [Tuning agent](./docs/02-user-guide/tuning-agent.md) with memory-aware benchmarking for automatic config search

docs/02-user-guide/pretraining.md

@@ -326,7 +326,7 @@ Controlled with `PRIMUS_HIPBLASLT_TUNING_STAGE` (see `examples/README.md`):
 | Stage | Purpose |
 | --- | --- |
 | 1 | Dump GEMM shapes seen during training (reduce `train_iters` for faster collection). |
-| 2 | Tune kernels from dumped shapes (offline tooling under `examples/offline_tune`). |
+| 2 | Tune kernels from dumped shapes (offline tooling under `examples/megatron/guides/offline_tune`). |
 | 3 | Train using tuned kernel artifacts from `./output/tune_hipblaslt/...`. |
 
 Example (from in-repo docs):

docs/02-user-guide/tuning-agent.md

@@ -246,21 +246,21 @@ environment takes precedence over the YAML for `LLM_MODEL`.
 #    synthesised metrics — verifies the install on a CPU-only host.
 python -m primus.agents.tuning_agent \
     --workload examples/megatron/configs/MI355X/mixtral_8x22B_v0.1-BF16-pretrain.yaml \
-    --target-cluster examples/agents/tuning_agent/target_cluster_mi355x_4nodes.yaml \
+    --target-cluster examples/megatron/guides/tuning_agent/target_cluster_mi355x_4nodes.yaml \
     --out-dir tuning_runs/dry-run \
     --dry-run --seed-only
 
 # 2) Seed-only with the real projection tool (Origami needed for simulate):
 python -m primus.agents.tuning_agent \
     --workload examples/megatron/configs/MI355X/mixtral_8x22B_v0.1-BF16-pretrain.yaml \
-    --target-cluster examples/agents/tuning_agent/target_cluster_mi355x_4nodes.yaml \
+    --target-cluster examples/megatron/guides/tuning_agent/target_cluster_mi355x_4nodes.yaml \
     --out-dir tuning_runs/mixtral-22b-seed \
     --seed-only
 
 # 3) Full agent (planner + DSPy.RLM rounds):
 python -m primus.agents.tuning_agent \
     --workload examples/megatron/configs/MI355X/mixtral_8x22B_v0.1-BF16-pretrain.yaml \
-    --target-cluster examples/agents/tuning_agent/target_cluster_mi355x_4nodes.yaml \
+    --target-cluster examples/megatron/guides/tuning_agent/target_cluster_mi355x_4nodes.yaml \
     --out-dir tuning_runs/mixtral-22b-full
 ```
 
@@ -330,7 +330,7 @@ are consumed by the analytical communication model (see
 [`projection.md` → Assumptions (performance projection)](./projection.md#assumptions-performance-projection)).
 
 A complete example ships at
-[`examples/agents/tuning_agent/target_cluster_mi355x_4nodes.yaml`](https://github.com/AMD-AGI/Primus/blob/main/examples/agents/tuning_agent/target_cluster_mi355x_4nodes.yaml):
+[`examples/megatron/guides/tuning_agent/target_cluster_mi355x_4nodes.yaml`](https://github.com/AMD-AGI/Primus/blob/main/examples/megatron/guides/tuning_agent/target_cluster_mi355x_4nodes.yaml):
 
 ```yaml
 target_cluster:
@@ -519,7 +519,7 @@ single idle 8-GPU node available for benchmarking:
 
 python -m primus.agents.tuning_agent \
     --workload examples/megatron/configs/MI355X/mixtral_8x22B_v0.1-BF16-pretrain.yaml \
-    --target-cluster examples/agents/tuning_agent/target_cluster_mi355x_4nodes.yaml \
+    --target-cluster examples/megatron/guides/tuning_agent/target_cluster_mi355x_4nodes.yaml \
     --out-dir tuning_runs/mixtral-22b-mi355x \
     --mode full --profiling-mode benchmark
 ```

docs/04-technical-guides/moe-training.md

@@ -1,8 +1,8 @@
 # MoE training deep-dive
 
-This guide covers Mixture-of-Experts (MoE) training in Primus on AMD Instinct GPUs: the bottlenecks unique to sparse models, the Primus/Primus-Turbo optimizations that address them, and a model-by-model tuning walkthrough. It is adapted from the AMD blog [MoE Training Best Practices on AMD GPU](https://rocm.blogs.amd.com/software-tools-optimization/primus-moe-package/README.html) (`examples/moe_package/README.md`) and grounded in the actual Primus configs and run scripts.
+This guide covers Mixture-of-Experts (MoE) training in Primus on AMD Instinct GPUs: the bottlenecks unique to sparse models, the Primus/Primus-Turbo optimizations that address them, and a model-by-model tuning walkthrough. It is adapted from the AMD blog [MoE Training Best Practices on AMD GPU](https://rocm.blogs.amd.com/software-tools-optimization/primus-moe-package/README.html) (`examples/megatron/guides/moe_package/README.md`) and grounded in the actual Primus configs and run scripts.
 
-All flags shown here are the **real CLI/YAML keys** used by `examples/moe_package/run_*_pretrain_mi355x.sh` and the Megatron module configs (`primus/configs/modules/megatron/`). The Primus-Turbo MoE optimizations in this guide (DeepEP, sync-free MoE, Turbo grouped GEMM) are **Megatron-backend** features. TorchTitan also supports MoE via expert parallelism (`expert_parallel_degree`, `expert_tensor_parallel_degree`), but its tuning is out of scope here.
+All flags shown here are the **real CLI/YAML keys** used by `examples/megatron/guides/moe_package/run_*_pretrain_mi355x.sh` and the Megatron module configs (`primus/configs/modules/megatron/`). The Primus-Turbo MoE optimizations in this guide (DeepEP, sync-free MoE, Turbo grouped GEMM) are **Megatron-backend** features. TorchTitan also supports MoE via expert parallelism (`expert_parallel_degree`, `expert_tensor_parallel_degree`), but its tuning is out of scope here.
 
 ---
 
@@ -33,19 +33,19 @@ Primus ships Megatron model presets for DeepSeek-style MoE models plus two ultra
 | MoE-1T | 1T / 44B | `moe_1T.yaml` |
 | MoE-2T | 2T / 80B | `moe_2T.yaml` |
 
-Ready-to-run pretrain scripts live in `examples/moe_package/`, e.g.:
+Ready-to-run pretrain scripts live in `examples/megatron/guides/moe_package/`, e.g.:
 
-- `examples/moe_package/run_deepseek_v2_lite_pretrain_mi355x.sh`
-- `examples/moe_package/run_deepseek_v2_pretrain_mi355x.sh`
-- `examples/moe_package/run_deepseek_v3_pretrain_mi355x.sh`
+- `examples/megatron/guides/moe_package/run_deepseek_v2_lite_pretrain_mi355x.sh`
+- `examples/megatron/guides/moe_package/run_deepseek_v2_pretrain_mi355x.sh`
+- `examples/megatron/guides/moe_package/run_deepseek_v3_pretrain_mi355x.sh`
 
-Each example script is a convenience wrapper: it sets environment + parallelism and selects an experiment YAML under `examples/moe_package/configs/`, then launches training. You can run the same training directly with the unified CLI, passing the experiment YAML with `--config` and the MoE feature toggles (Section 4) as overrides:
+Each example script is a convenience wrapper: it sets environment + parallelism and selects an experiment YAML under `examples/megatron/guides/moe_package/configs/`, then launches training. You can run the same training directly with the unified CLI, passing the experiment YAML with `--config` and the MoE feature toggles (Section 4) as overrides:
 
 ```bash
 # DeepSeek-V2-Lite baseline + DeepEP + sync-free + loss fusion + manual GC, via primus-cli
 export ENABLE_NUMA_BINDING=1 HSA_KERNARG_POOL_SIZE=12582912   # feature 6 (env, not CLI flags)
 ./runner/primus-cli direct -- train pretrain \
-  --config examples/moe_package/configs/MI355X/deepseek_v2_lite-pretrain-baseline.yaml \
+  --config examples/megatron/guides/moe_package/configs/MI355X/deepseek_v2_lite-pretrain-baseline.yaml \
   --enable_primus_turbo True \
   --use_turbo_deepep True --turbo_deepep_num_cu 64 --moe_router_dtype fp32 \
   --turbo_sync_free_moe_stage 1 \
@@ -70,7 +70,7 @@ Diagnose before optimizing. The recommended order:
 
 ## 4. Primus MoE optimizations
 
-The `examples/moe_package/run_*` scripts expose these as composable "MoE features." The table maps each feature to the **actual `--flags` (or environment variables)** you pass to `train pretrain`—the same toggles the example scripts set.
+The `examples/megatron/guides/moe_package/run_*` scripts expose these as composable "MoE features." The table maps each feature to the **actual `--flags` (or environment variables)** you pass to `train pretrain`—the same toggles the example scripts set.
 
 | Feature | Flags (real keys) | What it does |
 |---------|-------------------|--------------|
@@ -190,4 +190,4 @@ For PP=16, GA=16: VPP=1 gives ~48% bubble; VPP=6 gives ~14%—a large efficiency
 - [Parallelism strategies](./parallelism-strategies.md) and [Parallelism configuration](./parallelism-configuration.md)—EP, PP, CP, VPP.
 - [Collective operations](./collective-operations.md)—A2A and DeepEP context.
 - [Profiling & observability](./profiling-and-observability.md) and [Projection](../02-user-guide/projection.md).
-- Source blog: `examples/moe_package/README.md`.
+- Source blog: `examples/megatron/guides/moe_package/README.md`.

docs/04-technical-guides/multi-node-networking.md

@@ -74,7 +74,7 @@ GID selection (`NCCL_IB_GID_INDEX`) and traffic classes (`NCCL_IB_TC`, `NCCL_IB_
 ### Enable AINIC
 
 - Set **`USING_AINIC=1`**. The hook `runner/helpers/hooks/03_enable_ainic.sh` runs when this is set and exports AINIC-related variables back to the caller (`env.VAR=VALUE` lines).
-- Use container images built for AINIC when required by your site. Examples in this repository use tags such as `docker.io/tasimage/primus:<version>-ainic` (see `examples/customer_package/` and `.github/workflows/ci.yaml`). Match the image to your ROCm and ANP bundle.
+- Use container images built for AINIC when required by your site. Examples in this repository use tags such as `docker.io/tasimage/primus:<version>-ainic` (see `examples/megatron/guides/customer_package/` and `.github/workflows/ci.yaml`). Match the image to your ROCm and ANP bundle.
 - If the AINIC bundle in a published image does not match your host driver, see [AINIC bundle versions](./ainic-bundle-versions.md) for how to rebuild the image against a different bundle. Note that the bundle named in an image's build arguments is **not** always the one installed; verify with `dpkg-query -W libionic1`.
 
 ### `runner/use_ainic.yaml`

docs/04-technical-guides/performance-tuning.md

@@ -72,7 +72,7 @@ export HIPBLASLT_TUNING_OVERRIDE_FILE=/path/to/tune_hipblas_gemm_results.txt
 
 ### Standalone offline tool
 
-For manual HipBLASLt bench workflows, see `examples/offline_tune/offline_tune_gemm.py` and `examples/offline_tune/README.md` (hipblaslt-bench integration and `HIPBLASLT_TUNING_OVERRIDE_FILE` usage).
+For manual HipBLASLt bench workflows, see `examples/megatron/guides/offline_tune/offline_tune_gemm.py` and `examples/megatron/guides/offline_tune/README.md` (hipblaslt-bench integration and `HIPBLASLT_TUNING_OVERRIDE_FILE` usage).
 
 ---
 

docs/07-technical-blogs/README.md

@@ -9,7 +9,7 @@ the most recent handful.
 
 | Date | Title | What it covers | In this repo |
 |------|-------|----------------|--------------|
-| 2026/09/03 | [Enabling DeepSeek-V4-Flash Training on AMD Instinct MI355X GPUs with Primus](https://rocm.blogs.amd.com/software-tools-optimization/primus-deepseek-v4/README.html) | DeepSeek-V4-Flash architecture, performance projection, kernel optimizations, and how to reproduce the runs | [`examples/deepseek-v4`](https://github.com/AMD-AGI/Primus/tree/main/examples/deepseek-v4) |
+| 2026/09/03 | [Enabling DeepSeek-V4-Flash Training on AMD Instinct MI355X GPUs with Primus](https://rocm.blogs.amd.com/software-tools-optimization/primus-deepseek-v4/README.html) | DeepSeek-V4-Flash architecture, performance projection, kernel optimizations, and how to reproduce the runs | [`examples/megatron/models/deepseek-v4`](https://github.com/AMD-AGI/Primus/tree/main/examples/megatron/models/deepseek-v4) |
 | 2026/08/12 | [Using ODC to Accelerate AMD SFT Training](https://rocm.blogs.amd.com/software-tools-optimization/odc-accelerate-training/README.html) | On-demand point-to-point communication replacing the FSDP all-gather / reduce-scatter, over rocSHMEM and MORI | [ODC FSDP2 patches](https://github.com/AMD-AGI/Primus/blob/main/primus/backends/megatron/patches/odc_torch_fsdp2_patches.py) |
 | 2026/07/06 | [Primus Tuning Agent: Closing the Configuration-Search Loop](https://rocm.blogs.amd.com/software-tools-optimization/primus-tuning-agent/README.html) | LLM-driven search over parallelism, pipeline layout, and recompute sets, scored by projection instead of cluster time | [Tuning agent](../02-user-guide/tuning-agent.md) |
 | 2026/06/10 | [Dropless MoE Training in JAX with Primus-Turbo](https://rocm.blogs.amd.com/software-tools-optimization/maxtext-dropless-moe/README.html) | Grouped GEMM brought into MaxText through JAX FFI and `custom_vjp`, with the fan-out / fan-in correctness details | [MaxText parameters](../03-configuration-reference/maxtext-parameters.md) |

examples/README.md

@@ -10,6 +10,7 @@ It supports both **single-node** and **multi-node** training, and includes optio
 - [🧠 Pretraining with Primus](#-pretraining-with-primus)
   - [📚 Table of Contents](#-table-of-contents)
   - [⚙️ Supported Backends](#️-supported-backends)
+  - [📂 Directory Layout](#-directory-layout)
   - [🖥️ Single Node Training](#️-single-node-training)
     - [Setup Docker](#setup-docker)
     - [Setup Primus](#setup-primus)
@@ -42,6 +43,41 @@ Primus supports multiple backends.
 | TorchTitan     | PyTorch-compatible framework developed for training at scale |
 | NeMo AutoModel | NVIDIA-NeMo AutoModel (diffusion: Wan 2.2 T2V); `third_party/Automodel` submodule, installed editable on first run |
 
+## 📂 Directory Layout
+
+Every backend owns a top-level directory whose name matches the `framework` field in
+the experiment YAML. Anything specific to one backend lives underneath it, so a config
+and the material explaining it stay together:
+
+```text
+examples/
+├── megatron/              # framework: megatron
+│   ├── configs/           #   experiment YAMLs, grouped by GPU (MI300X, MI355X, …)
+│   ├── models/            #   model-specific launchers and studies
+│   │   ├── deepseek-v4/
+│   │   └── kimi-k3/
+│   └── guides/            #   walkthroughs and packaged workflows
+│       ├── customer_package/
+│       ├── moe_package/
+│       ├── odc/
+│       ├── offline_tune/
+│       └── tuning_agent/
+├── torchtitan/            # framework: torchtitan
+├── maxtext/               # framework: maxtext
+├── megatron_bridge/       # framework: megatron_bridge
+├── diffusion/             # framework: diffusion
+├── maxdiffusion/          # framework: maxdiffusion
+├── nemo_automodel/        # framework: nemo_automodel
+├── hummingbirdxt/         # framework: hummingbirdxt
+├── mlperf/                # MLPerf submissions; spans several backends
+└── hardware_configs/      # per-GPU bandwidth/latency inputs for primus projection
+```
+
+`mlperf/` and `hardware_configs/` sit at the top level because they are not tied to a
+single backend: MLPerf submissions cover Megatron, Megatron-Bridge and diffusion, and
+the hardware configs are consumed by `primus projection`. Launchers and helper scripts
+shared by every backend also live at the top level.
+
 
 ## 🖥️ Single Node Training
 
@@ -205,7 +241,7 @@ export EXP=examples/megatron/configs/MI300X/llama2_7B-BF16-pretrain.yaml
 
 ### Stage 2: Tune GEMM Kernel
 
-This stage performs kernel tuning based on the dumped GEMM shapes using the [offline_tune tool](https://github.com/AMD-AGI/Primus/tree/main/examples/offline_tune).
+This stage performs kernel tuning based on the dumped GEMM shapes using the [offline_tune tool](https://github.com/AMD-AGI/Primus/tree/main/examples/megatron/guides/offline_tune).
 It typically takes 10–30 minutes depending on model size and shape complexity.
 
 

examples/megatron/configs/MI355X/kimi_k3-BF16-8L-official.yaml

@@ -12,7 +12,7 @@ workspace: ${PRIMUS_WORKSPACE:./output}
 # optimizer, bf16 grads/moments, recompute full/block/8) is folded in so the file
 # runs at 4-node scale as written. Synthetic data (mock_data: true).
 #
-# Launched by examples/models/kimi-k3/run_kimi_k3_8L_official_pretrain_mi355x.sh.
+# Launched by examples/megatron/models/kimi-k3/run_kimi_k3_8L_official_pretrain_mi355x.sh.
 
 modules:
   pre_trainer:

examples/megatron/configs/MI355X/qwen3_30B_A3B-BF16-sft-packed.yaml

@@ -12,7 +12,7 @@ workspace: ${PRIMUS_WORKSPACE:./output}
 #   2) qwen3_30B_A3B-BF16-pretrain.yaml       -- Qwen3-specific fusion /
 #      recompute / precision-aware optimizer settings that have been
 #      empirically validated for this 30 B param + 128 expert architecture.
-#   3) examples/moe_package/start_training_qwen_30B_a3B.sh
+#   3) examples/megatron/guides/moe_package/start_training_qwen_30B_a3B.sh
 #      -- the actual override values used to reach the published
 #      ~555 TFLOPS pretrain steady state (mbs=8, gbs=512, recompute=5,
 #      manual_gc, mtp_num_layers=0).

examples/moe_package/README.md → examples/megatron/guides/moe_package/README.md

@@ -293,7 +293,7 @@ This section provides practical guidance for optimizing different DeepSeek model
 
 **Configuration files:**
 - Model Config: [primus/configs/models/megatron/deepseek_v2_lite.yaml](https://github.com/AMD-AGI/Primus/blob/main/primus/configs/models/megatron/deepseek_v2_lite.yaml)
-- Pretrain Script: [examples/moe_package/run_deepseek_v2_lite_pretrain_mi355x.sh](https://github.com/AMD-AGI/Primus/blob/main/examples/moe_package/run_deepseek_v2_lite_pretrain_mi355x.sh)
+- Pretrain Script: [examples/megatron/guides/moe_package/run_deepseek_v2_lite_pretrain_mi355x.sh](https://github.com/AMD-AGI/Primus/blob/main/examples/megatron/guides/moe_package/run_deepseek_v2_lite_pretrain_mi355x.sh)
 
 ---
 
@@ -367,7 +367,7 @@ Figure 6 below presents the cumulative impact of each optimization feature on De
 
 **Configuration files:**
 - Model Config: [primus/configs/models/megatron/deepseek_v2.yaml](https://github.com/AMD-AGI/Primus/blob/main/primus/configs/models/megatron/deepseek_v2.yaml)
-- Pretrain Script: [examples/moe_package/run_deepseek_v2_pretrain_mi355x.sh](https://github.com/AMD-AGI/Primus/blob/main/examples/moe_package/run_deepseek_v2_pretrain_mi355x.sh)
+- Pretrain Script: [examples/megatron/guides/moe_package/run_deepseek_v2_pretrain_mi355x.sh](https://github.com/AMD-AGI/Primus/blob/main/examples/megatron/guides/moe_package/run_deepseek_v2_pretrain_mi355x.sh)
 
 ---
 

examples/moe_package/run_deepseek_v2_lite_pretrain_mi355x.sh → examples/megatron/guides/moe_package/run_deepseek_v2_lite_pretrain_mi355x.sh

@@ -200,7 +200,7 @@ mkdir -p "$LOG_DIR"
 rm -rf "$LOG_FILE"
 
 ######################### Training Job #########################
-export EXP="examples/moe_package/configs/MI355X/deepseek_v2_lite-pretrain-baseline.yaml"
+export EXP="examples/megatron/guides/moe_package/configs/MI355X/deepseek_v2_lite-pretrain-baseline.yaml"
 
 echo "--------------------------------" | tee -a "$LOG_FILE"
 echo "Begin Training... $(date +%Y%m%d_%H%M%S)" | tee -a "$LOG_FILE"