docs(cli): populate --help text for every command and flag across all CLI modules

aarambh-studio/src/cmd/convert.rs

@@ -11,37 +11,49 @@ use aarambh_studio_weights::{
 use clap::Args;
 
 #[derive(Debug, Args)]
+/// Convert checkpoints between HF SafeTensors and GGUF, or expand vocabularies.
 pub struct ConvertArgs {
+    /// Training/model TOML configuration (provides architecture + device).
     #[arg(long, default_value = "configs/tiny_shakespeare.toml")]
     pub config: PathBuf,
+    /// Source checkpoint path to convert.
     #[arg(long)]
     pub input: PathBuf,
+    /// Output converted checkpoint path.
     #[arg(long)]
     pub output: PathBuf,
+    /// HF architecture family: llama3 (used for HF -> SafeTensors migration).
     #[arg(long, default_value = "llama3")]
     pub arch: String,
+    /// Emit a GGUF checkpoint instead of native SafeTensors.
     #[arg(long)]
     pub gguf: bool,
+    /// GGUF quantisation format: q4_k_m, q5_k_m, or q8_0.
     #[arg(long, default_value = "q4_k_m")]
     pub format: String,
+    /// Expand the SafeTensors model with the Phase 35 video vocabulary.
     #[arg(long, requires = "tokenizer", requires = "output_tokenizer")]
     pub upgrade_video_vocab: bool,
+    /// Expand the SafeTensors model with the Phase 36 document vocabulary.
     #[arg(
         long,
         requires = "tokenizer",
         requires = "output_tokenizer",
         conflicts_with = "upgrade_video_vocab"
     )]
     pub upgrade_document_vocab: bool,
+    /// Expand the SafeTensors model with the Phase 42 audio vocabulary.
     #[arg(
         long,
         requires = "tokenizer",
         requires = "output_tokenizer",
         conflicts_with_all = ["upgrade_video_vocab", "upgrade_document_vocab"]
     )]
     pub upgrade_audio_vocab: bool,
+    /// Source tokenizer JSON path (required for vocabulary upgrades).
     #[arg(long)]
     pub tokenizer: Option<PathBuf>,
+    /// Output tokenizer JSON path for the upgraded vocabulary.
     #[arg(long)]
     pub output_tokenizer: Option<PathBuf>,
 }

aarambh-studio/src/cmd/distill.rs

@@ -10,6 +10,7 @@ use aarambh_studio_train::TrainingRunConfig;
 use clap::{Args, Subcommand};
 
 #[derive(Debug, Args)]
+/// Distil a smaller student model from a frozen local or dataset teacher.
 pub struct DistillArgs {
     #[command(subcommand)]
     pub command: DistillCommand,
@@ -28,171 +29,252 @@ pub enum DistillCommand {
 }
 
 #[derive(Debug, Args)]
+/// `distill train` — train a full student on fresh rollouts scored by a frozen teacher.
 pub struct TrainArgs {
+    /// Student distillation TOML configuration (architecture + train settings).
     #[arg(long, default_value = "configs/distill_smoke.toml")]
     pub config: PathBuf,
+    /// Student checkpoint path to fine-tune.
     #[arg(long)]
     pub student: PathBuf,
+    /// Optional tokenizer JSON path; falls back to the config.
     #[arg(long)]
     pub tokenizer: Option<PathBuf>,
+    /// Prompts JSONL path; defaults to the config dataset path.
     #[arg(long)]
     pub prompts: Option<PathBuf>,
+    /// Output adapter directory; defaults to the config checkpoint dir.
     #[arg(long)]
     pub output: Option<PathBuf>,
+    /// Teacher backend: local (frozen checkpoint) or dataset (logged completions).
     #[arg(long, default_value = "local")]
     pub teacher: String,
+    /// Frozen teacher checkpoint path (required for --teacher local).
     #[arg(long)]
     pub teacher_model: Option<PathBuf>,
+    /// Frozen teacher TOML config path (required for --teacher local).
     #[arg(long)]
     pub teacher_config: Option<PathBuf>,
+    /// Teacher completions JSONL path (required for --teacher dataset).
     #[arg(long)]
     pub teacher_data: Option<PathBuf>,
+    /// Override the teacher device (e.g. cpu, cuda:0, metal).
     #[arg(long)]
     pub teacher_device: Option<String>,
+    /// Override the teacher dtype (e.g. f16, bf16, f32).
     #[arg(long)]
     pub teacher_dtype: Option<String>,
+    /// Distillation objective: soft-kl (forward KL) or reward (GRPO-style).
     #[arg(long)]
     pub objective: Option<String>,
+    /// Number of student rollouts sampled per prompt.
     #[arg(long, default_value_t = 4)]
     pub rollouts_per_prompt: usize,
+    /// Maximum new tokens generated per student rollout.
     #[arg(long, default_value_t = 128)]
     pub max_new_tokens: usize,
+    /// Sampling temperature for student rollouts.
     #[arg(long, default_value_t = 0.8)]
     pub temperature: f32,
+    /// Nucleus sampling probability mass for student rollouts.
     #[arg(long, default_value_t = 0.95)]
     pub top_p: f32,
+    /// Top-k sampling width for student rollouts.
     #[arg(long, default_value_t = 50)]
     pub top_k: usize,
+    /// Sampling temperature applied to the teacher distribution.
     #[arg(long, default_value_t = 1.0)]
     pub teacher_temperature: f64,
+    /// Maximum absolute advantage used to clip reward-weighted rollouts.
     #[arg(long, default_value_t = 5.0)]
     pub advantage_clip: f64,
+    /// Thinking budget: none, low, medium, high, or max.
     #[arg(long, default_value = "none")]
     pub thinking: String,
+    /// Training batch size.
     #[arg(long)]
     pub batch_size: Option<usize>,
+    /// Maximum optimiser steps (overrides max-epochs when set).
     #[arg(long)]
     pub max_steps: Option<usize>,
+    /// Maximum training epochs.
     #[arg(long)]
     pub max_epochs: Option<usize>,
+    /// Learning rate.
     #[arg(long)]
     pub lr: Option<f64>,
+    /// Gradient accumulation steps before an optimiser update.
     #[arg(long)]
     pub grad_accum_steps: Option<usize>,
+    /// Linear warmup steps before the cosine schedule.
     #[arg(long)]
     pub warmup_steps: Option<usize>,
+    /// Save an adapter every N optimiser steps.
     #[arg(long)]
     pub save_every_n_steps: Option<usize>,
+    /// Log training metrics every N optimiser steps.
     #[arg(long)]
     pub log_every_n_steps: Option<usize>,
+    /// Resume training from the latest adapter in the output directory.
     #[arg(long)]
     pub resume: bool,
+    /// Disable dataset shuffling between epochs.
     #[arg(long)]
     pub no_shuffle: bool,
 }
 
 #[derive(Debug, Args)]
+/// `distill prepare-offline` — generate one static local-teacher completion per prompt.
 pub struct PrepareOfflineArgs {
+    /// Frozen teacher TOML config path.
     #[arg(long)]
     pub teacher_config: PathBuf,
+    /// Frozen teacher checkpoint path.
     #[arg(long)]
     pub teacher_model: PathBuf,
+    /// Optional tokenizer JSON path; falls back to the teacher config.
     #[arg(long)]
     pub tokenizer: Option<PathBuf>,
+    /// Input prompts JSONL path.
     #[arg(long)]
     pub prompts: PathBuf,
+    /// Output JSONL path with one static teacher completion per prompt.
     #[arg(long)]
     pub output: PathBuf,
+    /// Override the device used to generate completions.
     #[arg(long)]
     pub device: Option<String>,
+    /// Override the dtype used to generate completions.
     #[arg(long)]
     pub dtype: Option<String>,
+    /// Maximum new tokens generated per prompt.
     #[arg(long, default_value_t = 128)]
     pub max_new_tokens: usize,
+    /// Sampling temperature for completion generation.
     #[arg(long, default_value_t = 0.8)]
     pub temperature: f32,
+    /// Nucleus sampling probability mass for completion generation.
     #[arg(long, default_value_t = 0.95)]
     pub top_p: f32,
+    /// Top-k sampling width for completion generation.
     #[arg(long, default_value_t = 50)]
     pub top_k: usize,
+    /// RNG seed for deterministic completion sampling.
     #[arg(long, default_value_t = 42)]
     pub seed: u64,
 }
 
 #[derive(Debug, Args)]
+/// `distill train-offline` — train the matched static-completion offline control.
 pub struct TrainOfflineArgs {
+    /// Student distillation TOML configuration (architecture + train settings).
     #[arg(long, default_value = "configs/distill_smoke.toml")]
     pub config: PathBuf,
+    /// Student checkpoint path to fine-tune.
     #[arg(long)]
     pub student: PathBuf,
+    /// Optional tokenizer JSON path; falls back to the config.
     #[arg(long)]
     pub tokenizer: Option<PathBuf>,
+    /// Static-completion JSONL produced by `distill prepare-offline`.
     #[arg(long)]
     pub data: PathBuf,
+    /// Output adapter directory; defaults to the config checkpoint dir.
     #[arg(long)]
     pub output: Option<PathBuf>,
+    /// Training batch size.
     #[arg(long)]
     pub batch_size: Option<usize>,
+    /// Maximum optimiser steps (overrides max-epochs when set).
     #[arg(long)]
     pub max_steps: Option<usize>,
+    /// Maximum training epochs.
     #[arg(long)]
     pub max_epochs: Option<usize>,
+    /// Learning rate.
     #[arg(long)]
     pub lr: Option<f64>,
+    /// Gradient accumulation steps before an optimiser update.
     #[arg(long)]
     pub grad_accum_steps: Option<usize>,
+    /// Save an adapter every N optimiser steps.
     #[arg(long)]
     pub save_every_n_steps: Option<usize>,
+    /// Log training metrics every N optimiser steps.
     #[arg(long)]
     pub log_every_n_steps: Option<usize>,
+    /// Resume training from the latest adapter in the output directory.
     #[arg(long)]
     pub resume: bool,
+    /// Disable dataset shuffling between epochs.
     #[arg(long)]
     pub no_shuffle: bool,
 }
 
 #[derive(Debug, Args)]
+/// `distill evaluate` — score fresh student rollouts and write alignment reports.
 pub struct EvaluateArgs {
+    /// Student distillation TOML configuration (architecture + train settings).
     #[arg(long, default_value = "configs/distill_smoke.toml")]
     pub config: PathBuf,
+    /// Student checkpoint path to evaluate.
     #[arg(long)]
     pub student: PathBuf,
+    /// Optional tokenizer JSON path; falls back to the config.
     #[arg(long)]
     pub tokenizer: Option<PathBuf>,
+    /// Prompts JSONL path; defaults to the config dataset path.
     #[arg(long)]
     pub prompts: Option<PathBuf>,
+    /// Teacher backend: local (frozen checkpoint) or dataset (logged completions).
     #[arg(long, default_value = "local")]
     pub teacher: String,
+    /// Frozen teacher checkpoint path (required for --teacher local).
     #[arg(long)]
     pub teacher_model: Option<PathBuf>,
+    /// Frozen teacher TOML config path (required for --teacher local).
     #[arg(long)]
     pub teacher_config: Option<PathBuf>,
+    /// Teacher completions JSONL path (required for --teacher dataset).
     #[arg(long)]
     pub teacher_data: Option<PathBuf>,
+    /// Override the teacher device (e.g. cpu, cuda:0, metal).
     #[arg(long)]
     pub teacher_device: Option<String>,
+    /// Override the teacher dtype (e.g. f16, bf16, f32).
     #[arg(long)]
     pub teacher_dtype: Option<String>,
+    /// Distillation objective: soft-kl (forward KL) or reward (GRPO-style).
     #[arg(long)]
     pub objective: Option<String>,
+    /// Number of student rollouts sampled per prompt.
     #[arg(long, default_value_t = 2)]
     pub rollouts_per_prompt: usize,
+    /// Maximum new tokens generated per student rollout.
     #[arg(long, default_value_t = 128)]
     pub max_new_tokens: usize,
+    /// Sampling temperature for student rollouts.
     #[arg(long, default_value_t = 0.8)]
     pub temperature: f32,
+    /// Nucleus sampling probability mass for student rollouts.
     #[arg(long, default_value_t = 0.95)]
     pub top_p: f32,
+    /// Top-k sampling width for student rollouts.
     #[arg(long, default_value_t = 50)]
     pub top_k: usize,
+    /// Sampling temperature applied to the teacher distribution.
     #[arg(long, default_value_t = 1.0)]
     pub teacher_temperature: f64,
+    /// Optional cap on the number of prompts evaluated.
     #[arg(long)]
     pub max_prompts: Option<usize>,
+    /// Optional JSON output path for the alignment report.
     #[arg(long)]
     pub out: Option<PathBuf>,
+    /// Optional Markdown output path for the alignment report.
     #[arg(long)]
     pub markdown: Option<PathBuf>,
+    /// RNG seed for deterministic rollout sampling.
     #[arg(long, default_value_t = 42)]
     pub seed: u64,
 }

aarambh-studio/src/cmd/eval.rs

@@ -17,50 +17,72 @@ use serde::Deserialize;
 use std::str::FromStr;
 
 #[derive(Debug, Args)]
+/// Evaluate a checkpoint on capability, forgetting, or KV-cache probes.
 pub struct EvalArgs {
+    /// Optional training/model TOML config (required unless --compare is used).
     #[arg(long)]
     pub config: Option<PathBuf>,
+    /// Model checkpoint path; falls back to best.json/latest.json pointer.
     #[arg(long)]
     pub model: Option<PathBuf>,
+    /// Optional tokenizer JSON path; falls back to the configured tokenizer.
     #[arg(long)]
     pub tokenizer: Option<PathBuf>,
+    /// Comma-separated task list (e.g. ppl,gsm8k,humaneval).
     #[arg(long, default_value = "ppl")]
     pub tasks: String,
+    /// Directory containing per-task evaluation datasets.
     #[arg(long, default_value = "data/eval")]
     pub data_dir: PathBuf,
+    /// Optional cap on the number of examples evaluated per task.
     #[arg(long)]
     pub max_examples: Option<usize>,
+    /// Maximum new tokens generated per generative task.
     #[arg(long, default_value_t = 128)]
     pub max_new_tokens: usize,
     /// Thinking budget: none, low, medium, high, or max (Phase 39).
     #[arg(long, default_value = "none")]
     pub thinking: String,
+    /// Maximum tool-call steps for agent-style tasks.
     #[arg(long, default_value_t = 8)]
     pub agent_max_steps: usize,
+    /// Allow code execution in agent-style tasks (enables the code tool).
     #[arg(long)]
     pub allow_code_exec: bool,
+    /// Optional JSON output path for the scorecard.
     #[arg(long)]
     pub out: Option<PathBuf>,
+    /// Optional Markdown output path for the scorecard.
     #[arg(long)]
     pub markdown: Option<PathBuf>,
+    /// Compare two scorecards (takes exactly two JSON scorecard paths).
     #[arg(long, num_args = 2)]
     pub compare: Vec<PathBuf>,
+    /// Compare a QAT checkpoint against its unquantised baseline.
     #[arg(long)]
     pub qat_compare: bool,
+    /// Unquantised baseline checkpoint used as the --qat-compare reference.
     #[arg(long, requires = "qat_compare")]
     pub baseline_model: Option<PathBuf>,
+    /// Capability probe manifest path (enables forgetting analysis).
     #[arg(long)]
     pub forgetting_manifest: Option<PathBuf>,
+    /// Forgetting curves store path (read and updated).
     #[arg(long, default_value = "checkpoints/forgetting/curves.json")]
     pub forgetting_store: PathBuf,
+    /// Current checkpoint or session id recorded under the manifest.
     #[arg(long, requires = "forgetting_manifest")]
     pub checkpoint_id: Option<String>,
+    /// Baseline checkpoint or session id used to compute forgetting deltas.
     #[arg(long, requires = "forgetting_manifest")]
     pub baseline_id: Option<String>,
+    /// Absolute capability-score delta treated as significant forgetting.
     #[arg(long, default_value_t = DEFAULT_SIGNIFICANCE_THRESHOLD)]
     pub significance_threshold: f64,
+    /// Optional JSONL export path for forgetting deltas.
     #[arg(long, requires_all = ["forgetting_manifest", "baseline_id"])]
     pub forgetting_jsonl: Option<PathBuf>,
+    /// Require every manifest probe to run; otherwise missing probes are skipped.
     #[arg(long, requires = "forgetting_manifest")]
     pub require_all_probes: bool,
     /// Print per-layer KV-cache bytes/token by attention kind and exit (v4 Phase 41).