docs/NAV.md

mindXtrain Documentation Index

Every doc lives in docs/. The only Markdown at the repo root is README.md (entry point) plus CLAUDE.md / AGENTS.md (agent-tooling entrypoints, required at root).

This is the detailed table of contents for the whole docs/ tree: every doc gets a one-line hook and a nested list of its sections, each deep-linked to the heading. Skim the reading paths first, then jump straight to the section you need.

Reading paths

• New here? → Quickstart → Architecture → CLI reference.
• Running the demo / operating a real run? → HANDOFF.md → CLI → YAML schema.
• Contributing code? → Development workflow → Architecture → Actualization status.
• Driving the UI? → Coach UI → dcoach → Governance.
• Researching the space? → Decentralized training deep-dive → LLM training-stack landscape → Autoresearch strategy.

---

Getting started

Quickstart

Install (with optional-dep groups), init, dry-run autotune, and a 30-second CPU-only tour.

• Prerequisites
• Install — base
• Install — with extras
• 30-second tour (CPU-only)
• What you have on a CPU (base install)
• On the MI300X (operator path)
• Useful one-liners
• Next steps

HANDOFF.md

The 11-step operator checklist: local setup → MI300X provision → train/eval/quantize → publish → contracts → deploy.

• 1. Local setup (no GPU; 10 minutes)
• 2. Provision the MI300X droplet (sign-up + 30 min)
• 3. Install heavyweight deps inside the container
• 4. Run the autotune probe (real, ~60 s)
• 5. Train + eval + quantize
• 6. Build the manifest + verify
• 7. Publish (HF Hub + Lighthouse + mindX register)
• 8. Deploy contracts (optional)
• 9. Serve the model + wire the production URL
• 10. Publish & demo
• 11. Quality gates (run before every push)
• What's still TODO · Quick reference

---

Architecture & invariants

Architecture

The 5-layer single-package layout, the MI300X invariants, and the end-to-end data flow.

• The five conceptual layers
• Autotune is the spine
• MI300X-specific invariants (non-negotiable)
• End-to-end data flow
• Model strategy
• Actualization status
• What lives outside the Python tree

Development workflow

Toolchain, optional-deps, the lazy-import pattern, training lanes, and how to add recipes/backends/methods.

• Toolchain
• Optional dependency groups
• Lazy-import pattern
• The standard local cycle
• Repository layout
• Reuse boundaries
• Invariants
• Training lanes (CPU / local-GPU / MI300X)
• Adding a new recipe
• Adding a new training backend
• Adding a new model backend (operator)
• Adding a new training method
• Adding a new optional-dep group
• Adding a new doc
• Live training UI — Routes · Invariants · Frontend · Why not Selenium / WebSocket / Streamlit
• Common debugging
• What not to commit

Actualization status

Per-module map of what's real vs. needs --extra vs. CPU-active / GPU-pending / stub.

• v1.0.0 production-readiness audit
• Headline numbers
• What uv sync (no extras) gives you
• What the optional-dep groups unlock
• Per-subpackage status — cli · config · data · models · train · eval · autotune · operator · storage · provenance · deploy · budget
• What stays as NotImplementedError
• Test coverage · See also

Autotune deep-dive

The 60-second AOT probe — the differentiator. Probe taxonomy, the AutotunePlan, and how training consumes it.

• The AOT-only discipline
• The probe taxonomy — attention_probe (CK vs Triton) · gemm_probe (hipBLASLt) · rccl_probe (collective bw)
• The AutotunePlan schema
• How the training layer consumes the plan
• Dry-run / CI path
• Implementation budget
• Where the demo wow-moment lives

---

Coach UI & training workflow

Coach UI

The interactive /coach/ operator UI: create-script, live-training diagnostics, verifiable receipt, streaming chat, Modelfile builder.

• Why it exists · Boot · Layout · Routes
• Live training diagnostics
• Verifiable receipt card
• Create script + imprint (actor / persona / script)
• Create script — personas + skills
• Build an Ollama Modelfile (separate window)
• The core storyboard · Demo storyboard
• Dependencies · Tests · Customizing for the demo
• Streaming chat + ollama controls (Try the model)

dcoach

/coach/dcoach: prove a CPU-trained model recalls its training (imprint → classroom → boardroom → autotune feedback), clean-room eval tools, and how mindXtrain fits decentralized training.

• The proof loop
• Clean-room eval tools
• Prompt tools — test cheap, promote if it wins
• How mindXtrain fits decentralized training
• Why this matters

Governance

classroom (graduation) / boardroom (any-N consensus) / dojo (prime-N dispute settlement), model-backed deliberation.

• The model · Flow · Why prime
• Model-backed deliberation
• Coach surface · Tests

---

Reference

CLI reference

Every mindxtrain verb with synopsis, options, and exit codes.

• Global options
• init — scaffold a YAML
• bench — 60-second AOT autotune probe
• train — dispatch a training run
• dataset prep — run the dataset pipeline
• eval — run lm-evaluation-harness
• quantize — Quark FP8 / MXFP4
• serve — print the vLLM-ROCm launch command
• publish — push to HF + Lighthouse + register
• receipt — verify a provenance manifest
• Exit-code summary · Where the verbs live

YAML schema

Every field of the 10-section XTrainConfig.

• meta · hardware · autotune · model · data
• train — train.method (discriminated union)
• eval · quantize · serve · publish · receipt
• How the schema is enforced

Benchmarks

Target metrics + framework comparison.

• Hero workload
• H100 cost baseline
• Framework comparison
• Capturing the numbers
• Regression detection
• What's not measured (yet)

CHANGELOG

Version history (current: v1.0.4).

• [Unreleased]
• [1.0.4] — 2026-09-16
• [1.0.3] — 2026-09-15
• [1.0.2] — 2026-09-15
• [1.0.1] — 2026-09-15
• [1.0.0] — 2026-06-11
• [0.1.0] — 2026-05-06

LICENSE-NOTICE

Apache-2.0 + MIT-compatibility statement.

---

Decentralized-training landscape (2026)

Decentralized training deep-dive

Prime Intellect / Nous Psyche / Gensyn / Templar / Pluralis, the DiLoCo/SparseLoCo algorithms, verification (TOPLOC / Verde / Gauntlet), and where mindXtrain fits.

• TL;DR
• 1. The Algorithms — DiLoCo family · Momentum-decoupling · Model-parallel over WAN · Other lineages
• 2. The Networks — Prime Intellect · Nous / Psyche · Gensyn · Templar · Pluralis · Others
• 3. Verification: The Trust Layer
• 4. Why RL Is the Decentralization Sweet Spot
• 5. Economics & Crypto Integration
• 6. Hardware & Network Realities
• 7. Critical Assessment & Open Problems
• 8. Practical Integration for mindXtrain / PYTHAI
• Network Comparison Table · Key Papers Index · Caveats

LLM training-stack landscape

The open-source training/eval/quantize stack survey anchored on mindXtrain.

• TL;DR
• 1. The mindXtrain Point of Departure
• 2. Open-Source Training Frameworks
• 3. Automated / Autonomous Training Pipelines
• 4. Training-as-a-Service — 4a. Verification software
• 5. Data Curation
• 6. LoRA/Adapter Ecosystem, Weights, Formats, Quantization
• 7. AOT Compilation, Reproducibility, Licensing
• The End-to-End Pipeline · Recommendations · Caveats

Autoresearch strategy

The research-harness-as-a-wrapper design: attempt contract, git guard, search loop, on-chain champion provenance, parallel researchers.

• 0. Thesis
• 1. The four disciplines being imported
• 2. Architecture: the research harness as a wrapper — attempt contract · git guard · attempt runner · search loop
• 3. Provenance: every champion is verifiable — off-chain · on-chain · settlement
• 4. Foundry + mainnet — test · deploy
• 5. Operator + CLI + parallel researchers — CLI verb · operator route · parallel researchers
• 6. Phased rollout · 7. What this buys you

Vercel AI SDK 6 deep-dive

The streaming/agent toolkit the Coach chat patterns after (clean-room, vanilla JS).

• TL;DR · Key Findings
• Architecture & Philosophy
• Detailed Capability List
• Clean-Room Setup
• Code Examples (v6 API)
• Ecosystem & Context · Recommendations · Caveats

---

Source briefs (blueprints/)

The frozen design briefs the project was built against — historical specification; for current state read the docs above. Do not edit.

• blueprints/mindXtrain.md — operating brief; three-track pitch, module design, day-by-day execution.
• blueprints/mindXtrain2.md — technical master reference; GLM-5.1 depth, aGLM lineage, canonical Part 4 repository layout, training configs.
• blueprints/mindXtrain_ Production Blueprint for the AMD and lablab.ai Hackathon.md — pinned reference stack, Qwen3 targeting, repo skeleton, critical code snippets.
• PDFs (read-only design source): blueprints/mindXtrain Framework_ GLM-5.1, aGLM Lineage, and Qwen3.5 Primary Base Strategy.pdf, blueprints/mindXtrain_ Production Blueprint ….pdf, blueprints/Winning the AMD x lablab.ai Developer Hackathon ….pdf.

Build-in-public posts (posts/)

Dated launch-narrative posts and their rendered HTML — historical, not product docs.

• posts/README.md — index + cross-platform posting notes.
• posts/day1_scaffold.md · posts/day2_autotune.md · posts/day5_demo.md
• Rendered: posts/rendered/{about,day1,day2,day5}.html.

On-chain

• contracts/README.md — Foundry workspace for the immutable run-receipt registry + x402 receiver.