diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml
index 194940dc..02f0d611 100644
--- a/.github/workflows/nightly.yml
+++ b/.github/workflows/nightly.yml
@@ -5,13 +5,14 @@ on:
     - cron: "0 3 * * *"  # 03:00 UTC daily
   workflow_dispatch:  # Manual trigger
 
-permissions:
-  issues: write  # Required for creating failure notification issues
+# No workflow-level permissions — each job declares the minimal set it needs.
 
 jobs:
   test-latest-deps:
     name: Test with latest dependencies
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     strategy:
       fail-fast: false
       matrix:
@@ -56,6 +57,8 @@ jobs:
   test-min-deps:
     name: Test with minimum supported versions
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     steps:
       - uses: actions/checkout@v5
 
@@ -87,6 +90,9 @@ jobs:
     needs: [test-latest-deps, test-min-deps]
     if: failure()
     runs-on: ubuntu-latest
+    permissions:
+      contents: read  # github-script needs to read the repo
+      issues: write   # required for creating failure notification issues
     steps:
       - name: Create issue on failure
         uses: actions/github-script@v8
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 4b4597eb..6fa60dd9 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -4,12 +4,13 @@ on:
   release:
     types: [published]
 
-permissions:
-  id-token: write  # Required for trusted publishing
+# No workflow-level permissions — each job declares the minimal set it needs.
 
 jobs:
   build:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read  # checkout needs read access to the release ref
     steps:
       - uses: actions/checkout@v5
 
@@ -42,6 +43,9 @@ jobs:
     environment:
       name: testpypi
       url: https://test.pypi.org/p/forgelm
+    permissions:
+      contents: read  # download-artifact reads workflow run state
+      id-token: write  # required for trusted publishing to TestPyPI
     steps:
       - uses: actions/download-artifact@v5
         with:
@@ -61,6 +65,9 @@ jobs:
     environment:
       name: pypi
       url: https://pypi.org/p/forgelm
+    permissions:
+      contents: read  # download-artifact reads workflow run state
+      id-token: write  # required for trusted publishing to PyPI
     steps:
       - uses: actions/download-artifact@v5
         with:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index feac4aaf..b28a6ed6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,103 @@ All notable changes to ForgeLM are documented here.
 
 ## [Unreleased]
 
+## [0.4.0] — 2026-04-25
+
+### Added
+
+**Post-Training Completion (Phase 10)**
+
+- **`forgelm/inference.py`** — Shared generation primitives for all post-training features:
+  - `load_model(path, adapter, backend, load_in_4bit, load_in_8bit, trust_remote_code)` — loads HF model + tokenizer; optional PEFT adapter merge via `merge_and_unload()`; unsloth backend support
+  - `generate(model, tokenizer, prompt, *, messages, system_prompt, history, max_new_tokens, temperature, top_k, top_p, repetition_penalty)` — non-streaming text generation
+  - `generate_stream(...)` — streaming via `TextIteratorStreamer` in daemon thread; yields token chunks
+  - `logit_stats(logits)` — returns `{entropy, top1_prob, effective_vocab}` for token-level confidence inspection
+  - `adaptive_sample(logits, temperature, top_k, top_p, entropy_threshold)` — greedy below entropy threshold, nucleus sampling above
+  - `_build_prompt` — uses `tokenizer.apply_chat_template` when available; falls back to `"role: content\n"` join
+
+- **`forgelm/chat.py`** — Interactive terminal REPL (`ChatSession` class + `run_chat()` entry point):
+  - Streaming output by default; `--no-stream` flag for non-streaming
+  - Slash commands: `/reset`, `/save [file]`, `/temperature N`, `/system [prompt]`, `/help`, `/exit`
+  - History management with 50-turn cap (`_MAX_HISTORY_PAIRS`)
+  - Optional `rich` rendering via `pip install forgelm[chat]`
+  - Optional `--safety` flag routes each response through Llama Guard
+
+- **`forgelm/fit_check.py`** — VRAM pre-flight advisor:
+  - `estimate_vram(config)` → `FitCheckResult(verdict, estimated_gb, available_gb, breakdown, recommendations)`
+  - Verdicts: `FITS` (< 85% GPU), `TIGHT` (85-95%), `OOM` (> 95%), `UNKNOWN` (no GPU)
+  - Architecture loaded via `transformers.AutoConfig`; fallback size-hint dict for 7b/8b/13b/70b families
+  - VRAM components: base weights + LoRA adapter + optimizer state (AdamW/8-bit/GaLore-aware) + activations (gradient-checkpointing divides by √layers)
+  - `format_fit_check(result)` — human-readable summary; `--output-format json` for CI/CD
+  - Hypothetical mode when no CUDA detected — still estimates based on architecture
+
+- **`forgelm/export.py`** — GGUF model export:
+  - `export_model(model_path, output_path, *, format, quant, adapter, update_integrity, extra_args)` → `ExportResult`
+  - Wraps `llama-cpp-python`'s `convert_hf_to_gguf.py` — no reimplementation of conversion logic
+  - Supported quantizations: `q2_k`, `q3_k_m`, `q4_k_m`, `q5_k_m`, `q8_0`, `f16`
+  - **K-quant note**: `q2_k`/`q3_k_m`/`q4_k_m`/`q5_k_m` require a two-step flow.
+    `forgelm export ... --quant q4_k_m model.gguf` produces an intermediate
+    `model.f16.gguf`; run `llama-quantize model.f16.gguf model.gguf Q4_K_M`
+    afterward to obtain the K-quant. The `ExportResult.quant` field reflects
+    what was actually written (so `model_integrity.json` SHA-256 stays honest)
+  - Adapter merge: loads base + PEFT, saves merged fp16 weights before conversion
+  - `_sha256_file` — chunked 64 KB reads for large models
+  - `_update_integrity_manifest` — appends export artifact (path, quant, sha256, size_bytes) to `model_integrity.json`
+  - Optional dependency: `pip install forgelm[export]` (`llama-cpp-python>=0.2.90`)
+
+- **`forgelm/deploy.py`** — Deployment config file generation:
+  - `generate_deploy_config(model_path, target, output_path, *, system_prompt, max_length, temperature, top_k, top_p, ...)` → `DeployResult`
+  - Target `ollama`: Modelfile with FROM, SYSTEM (double-quote escaped), PARAMETER directives
+  - Target `vllm`: YAML engine config with GPU memory utilization, dtype, trust_remote_code
+  - Target `tgi`: docker-compose.yaml with GPU resource reservation, port mapping, max-input/total-length
+  - Target `hf-endpoints`: JSON spec with model repository, task, compute instance, region, framework
+  - Case-insensitive target matching; default output filenames per target
+
+- **CLI subcommands** (`forgelm/cli.py`):
+  - `forgelm chat MODEL_PATH [--adapter] [--system] [--temperature] [--max-new-tokens] [--safety] [--no-stream] [--load-in-4bit] [--load-in-8bit] [--trust-remote-code] [--backend]`
+  - `forgelm export MODEL_PATH --output FILE [--format gguf] [--quant q4_k_m] [--adapter] [--no-integrity-update]`
+  - `forgelm deploy MODEL_PATH --target TARGET [--output FILE] [--system] [--max-length] [--temperature] [--top-k] [--top-p] [--trust-remote-code]`
+  - `forgelm --config CONFIG --fit-check [--output-format json]`
+  - All subcommands work without `--config`; backward-compatible with existing flat CLI
+
+- **Optional extras** in `pyproject.toml`:
+  - `forgelm[export]` — `llama-cpp-python>=0.2.90` (non-Windows)
+  - `forgelm[chat]` — `rich>=13.0.0`
+
+- **New test modules**:
+  - `tests/test_inference.py` — 16 tests covering `_build_prompt`, `_to_messages`, `logit_stats`, `adaptive_sample`, `load_model`, `generate` with custom torch stub (no GPU required)
+  - `tests/test_fit_check.py` — 18 tests covering parameter estimation, VRAM components, GPU scenarios (no CUDA, 4 GB, 80 GB), `format_fit_check`
+  - `tests/test_export.py` — 12 tests covering SHA-256, integrity manifest, GGUF export flow with subprocess mock
+  - `tests/test_deploy.py` — 21 tests covering all 4 target generators and `generate_deploy_config` integration
+  - `tests/test_cli_phase10.py` — 22 tests covering `--fit-check`, all deploy targets, export subcommand, chat subcommand, subcommand routing
+
+### Changed
+
+- **`forgelm/__init__.py`** — version bumped to `0.4.0`
+- **`forgelm/cli.py`** — added subparser architecture with `chat`, `export`, `deploy` subcommands; added `--fit-check` flag; `KeyboardInterrupt` caught in chat dispatch for graceful exit
+- **`forgelm/wizard.py`** — (no changes needed; Phase 10 features are all CLI-driven, not wizard-driven)
+
+### Breaking
+
+- **`forgelm.compliance.export_compliance_artifacts`** signature changed from
+  `(manifest, config, output_dir)` to `(manifest, output_dir)`. The `config`
+  argument was unused (the manifest already contains all derived values).
+  External callers must drop the second positional argument.
+- **`forgelm.export.export_model`** keyword `format=` renamed to
+  `output_format=` to avoid shadowing the `format` builtin. Update
+  `export_model(..., format="gguf", ...)` → `export_model(...,
+  output_format="gguf", ...)`.
+- **`forgelm.deploy.generate_deploy_config`** parameter list collapsed from
+  18 → 11 args. The HF Endpoints fields (task/instance_size/instance_type/
+  region/framework/vendor) are now grouped as
+  `hf_endpoints: HFEndpointsOptions = None`; sampling defaults
+  (temperature/top_k/top_p) are grouped as
+  `sampling: SamplingOptions = None`. Pass instances of those dataclasses
+  instead of the individual kwargs.
+
+---
+
+## [0.3.1rc1] — 2026-03-28 (included in v0.4.0 branch)
+
 ### Added
 - **Engineering standards** (`docs/standards/`) — 9 standard documents: coding, architecture, error-handling, logging-observability, testing, documentation, localization, code-review, release.
 - **AI agent skills** (`.claude/skills/`) — 6 task-specific SKILL.md checklists: add-config-field, add-trainer-feature, add-test, sync-bilingual-docs, cut-release, review-pr.
@@ -14,6 +111,18 @@ All notable changes to ForgeLM are documented here.
 - **docs/ reorganization** — Reference docs moved to `docs/reference/`, design specs to `docs/design/`. All internal links updated (29 link fixes).
 - **Roadmap refactored** — `docs/roadmap.md` reduced from 910 to 78 lines; phase details moved to `docs/roadmap/` subdirectory.
 
+### Fixed (Security & Config Hardening)
+- Webhook URLs excluded from HuggingFace Hub model cards — prevents credential leaks
+- User-supplied strings sanitized before Markdown template embedding (content injection prevention)
+- All 19 Pydantic sub-models enforce `extra="forbid"` — YAML typos are errors, not silent bugs
+- Deprecated `lora.use_dora` / `lora.use_rslora` booleans auto-normalize to `lora.method` with warnings
+- Audit log hash chain restores continuity across process restarts
+- Compliance manifests correctly report pre-OOM-recovery batch size
+- GRPO reward model path correctly wrapped as callable
+- Safety classifier receives full `[INST] prompt [/INST] response` context
+- Extension-less files raise clear `ValueError` instead of silently loading wrong format
+- TIES tie-breaking fixed; DARE now deterministic with `seed=42`
+
 ## [0.3.0] — 2026-03-28
 
 ### Added
diff --git a/README.md b/README.md
index 903a0e54..adf7e6db 100644
--- a/README.md
+++ b/README.md
@@ -26,6 +26,12 @@
 - **LLM-as-Judge**: API-based (OpenAI) or local model scoring for quality assessment
 - **Auto-Revert**: Automatically discard models that fail loss, benchmark, or safety thresholds
 
+### Post-Training (v0.4.0)
+- **Interactive Chat**: `forgelm chat ./model` — streaming REPL with `/reset`, `/save`, `/temperature`, `/system` commands; optional Llama Guard safety routing
+- **GGUF Export**: `forgelm export ./model --quant q4_k_m` — wraps `llama-cpp-python` converter; 6 quant levels; SHA-256 appended to integrity manifest
+- **Deployment Configs**: `forgelm deploy ./model --target ollama|vllm|tgi|hf-endpoints` — generates ready-to-use config files; does not start the server
+- **VRAM Fit Check**: `forgelm --config my.yaml --fit-check` — pre-flight memory estimator; `FITS / TIGHT / OOM / UNKNOWN` verdict with recommendations
+
 ### Enterprise & MLOps
 - **Config-Driven**: Declarative YAML — built for CI/CD pipelines, not notebooks
 - **EU AI Act Compliance**: Auto-generated audit trails, data provenance (SHA-256), training manifests
@@ -44,18 +50,24 @@
 ```bash
 # Install
 pip install -e .
+pip install -e ".[export]"   # GGUF export (optional, non-Windows)
 
 # Generate config interactively
 forgelm --wizard
 
-# Or copy template and edit
-cp config_template.yaml my_config.yaml
-
 # Validate without training
 forgelm --config my_config.yaml --dry-run
 
+# Check VRAM before a long run
+forgelm --config my_config.yaml --fit-check
+
 # Train
 forgelm --config my_config.yaml
+
+# After training: chat, export, deploy
+forgelm chat ./checkpoints/final_model
+forgelm export ./checkpoints/final_model --output model.gguf --quant q4_k_m
+forgelm deploy ./checkpoints/final_model --target ollama --output ./Modelfile
 ```
 
 See the [Quick Start Guide](docs/guides/quickstart.md) for a complete walkthrough.
@@ -162,10 +174,15 @@ forgelm --version                            # Show version
 ```
 forgelm/
 ├── cli.py           # CLI with 10+ modes (train, dry-run, merge, benchmark, wizard...)
-├── config.py        # Pydantic config (15 models: training, evaluation, distributed...)
+├── config.py        # Pydantic config (19 models: training, evaluation, distributed...)
 ├── data.py          # Dataset loading (SFT, DPO, KTO, GRPO formats + multi-dataset)
 ├── model.py         # Model loading (transformers, unsloth, MoE, PEFT)
 ├── trainer.py       # Training orchestration (6 trainer types via TRL, GaLore, long-context)
+├── inference.py     # Shared inference primitives (load, generate, stream, adaptive sampling)
+├── chat.py          # Interactive terminal REPL with streaming and slash commands
+├── export.py        # GGUF export via llama-cpp-python
+├── fit_check.py     # Pre-flight VRAM estimator (FITS / TIGHT / OOM / UNKNOWN)
+├── deploy.py        # Deployment config generator (Ollama, vLLM, TGI, HF Endpoints)
 ├── results.py       # TrainResult dataclass
 ├── benchmark.py     # lm-evaluation-harness integration
 ├── safety.py        # Post-training safety evaluation (Llama Guard)
@@ -180,7 +197,7 @@ forgelm/
 
 configs/deepspeed/   # ZeRO-2, ZeRO-3, ZeRO-3+Offload presets
 notebooks/           # Colab-ready Jupyter notebooks
-tests/               # 145+ unit tests across 11 test files
+tests/               # 430 passed (+34 skipped) across 30 test files
 docs/guides/         # Quickstart, alignment, CI/CD, enterprise, safety guides
 ```
 
diff --git a/docs/guides/quickstart.md b/docs/guides/quickstart.md
index ec8a23c4..353b8c69 100644
--- a/docs/guides/quickstart.md
+++ b/docs/guides/quickstart.md
@@ -90,12 +90,14 @@ Before starting a long run, estimate if your config fits in GPU memory:
 
 ```bash
 forgelm --config my_config.yaml --fit-check
-# → Coming in v0.4.0: GPU: RTX 3060 12GB; Estimated peak: 10.8 GB; Verdict: ✅ FITS
+# GPU: RTX 3060 12GB — Estimated peak: 10.8 GB — Verdict: FITS
+# Or: Verdict: TIGHT — Enable gradient checkpointing and reduce batch size
+# Or: Verdict: UNKNOWN — No GPU detected (hypothetical estimate)
 ```
 
-> **Note:** `--fit-check` is planned for v0.4.0.
+Output includes a breakdown (base weights, LoRA adapter, optimizer state, activations) and ordered recommendations when memory is tight. Use `--output-format json` for CI/CD integration.
 
-For now, reduce `max_length` and `per_device_train_batch_size` if you hit OOM. The [Troubleshooting guide](troubleshooting.md) has detailed OOM solutions.
+If you hit OOM during training, the [Troubleshooting guide](troubleshooting.md) has detailed solutions.
 
 ## 6. Use Your Model
 
@@ -112,19 +114,21 @@ output = model.generate(**inputs, max_new_tokens=200)
 print(tokenizer.decode(output[0], skip_special_tokens=True))
 ```
 
-### Using Your Model (After v0.4.0)
+### Using Your Model (v0.4.0+)
 
-Starting with v0.4.0, you can interact with your trained model directly:
+Interact with and deploy your trained model directly:
 
 ```bash
-# Chat with your fine-tuned model
+# Chat with your fine-tuned model (streaming by default)
 forgelm chat ./checkpoints/final_model
 
-# Export to GGUF (for Ollama, LM Studio)
-forgelm export ./checkpoints/final_model --format gguf --quant q4_k_m --output model.gguf
+# Export to GGUF (for Ollama, LM Studio, llama.cpp)
+# Requires: pip install forgelm[export]
+forgelm export ./checkpoints/final_model --output model.gguf --quant q4_k_m
 
-# Generate deployment configs
+# Generate deployment configs (no server is started)
 forgelm deploy ./checkpoints/final_model --target ollama --output ./Modelfile
+forgelm deploy ./checkpoints/final_model --target vllm --output ./vllm_config.yaml
 ```
 
 ---
diff --git a/docs/reference/usage.md b/docs/reference/usage.md
index 6e2c1f65..bf6939dd 100644
--- a/docs/reference/usage.md
+++ b/docs/reference/usage.md
@@ -22,6 +22,8 @@ pip install -e ".[eval]"         # lm-evaluation-harness
 pip install -e ".[tracking]"     # W&B experiment tracking
 pip install -e ".[distributed]"  # DeepSpeed multi-GPU
 pip install -e ".[merging]"      # mergekit model merging
+pip install -e ".[export]"       # GGUF export (llama-cpp-python, non-Windows)
+pip install -e ".[chat]"         # Rich rendering in forgelm chat
 ```
 
 ## Authentication
@@ -77,6 +79,47 @@ forgelm --config my_config.yaml --resume ./checkpoints/checkpoint-500
 forgelm --config my_config.yaml --offline
 ```
 
+### VRAM Fit Check
+
+Before training, estimate whether your config fits in GPU memory:
+
+```bash
+# Text output (human-readable verdict)
+forgelm --config my_config.yaml --fit-check
+
+# JSON output (for CI/CD pipelines)
+forgelm --config my_config.yaml --fit-check --output-format json
+```
+
+Output shows: estimated peak VRAM, available VRAM (if GPU detected), verdict (`FITS` / `TIGHT` / `OOM` / `UNKNOWN`), and ordered recommendations. Falls back to hypothetical mode when no GPU is detected.
+
+### Post-Training: Chat, Export, Deploy
+
+After training, interact with and deploy your fine-tuned model directly from the CLI. These subcommands work without `--config`.
+
+```bash
+# Interactive chat REPL (streaming by default)
+forgelm chat ./checkpoints/final_model
+forgelm chat ./checkpoints/final_model --adapter ./adapter --safety
+forgelm chat ./checkpoints/final_model --system "You are a helpful assistant." --temperature 0.8
+
+# Export to GGUF (for Ollama, LM Studio, llama.cpp)
+# Requires: pip install forgelm[export]
+forgelm export ./checkpoints/final_model --output model.gguf --quant q4_k_m
+forgelm export ./checkpoints/final_model --output model.gguf --quant q8_0 --adapter ./adapter
+
+# Generate deployment config files
+forgelm deploy ./checkpoints/final_model --target ollama --output ./Modelfile
+forgelm deploy ./checkpoints/final_model --target vllm --output ./vllm_config.yaml
+forgelm deploy ./checkpoints/final_model --target tgi --output ./docker-compose.yaml
+forgelm deploy ./checkpoints/final_model --target hf-endpoints --output ./endpoint.json
+forgelm deploy ./checkpoints/final_model --target ollama --output ./Modelfile --system "Be concise."
+```
+
+**Chat slash commands:** `/reset`, `/save [file]`, `/temperature N`, `/system [prompt]`, `/help`, `/exit`
+
+**Export quantization levels:** `q2_k`, `q3_k_m`, `q4_k_m` (recommended), `q5_k_m`, `q8_0`, `f16`
+
 ### Synthetic Data Generation
 
 ```bash
diff --git a/docs/roadmap.md b/docs/roadmap.md
index 0ea52e91..7041f85d 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -7,16 +7,15 @@
 | Tür | Phase | Status |
 |-----|-------|--------|
 | ✅ Done | [Phase 1-9](roadmap/completed-phases.md) | SOTA upgrades, evaluation, reliability, enterprise integration, ecosystem, alignment stack, safety, EU AI Act compliance (Articles 9-17 + Annex IV), advanced safety intelligence |
-| 📋 Planned | [Phase 10 — Post-Training Completion](roadmap/phase-10-post-training.md) | `forgelm/inference.py`, `chat`, `export` (GGUF), `fit-check`, `deploy` → `v0.4.0` |
+| ✅ Done | [Phase 10 — Post-Training Completion](roadmap/phase-10-post-training.md) | `inference.py`, `chat`, `export` (GGUF), `--fit-check`, `deploy` — shipped `v0.4.0` |
 | 📋 Planned | [Phase 10.5 — Quickstart Layer & Onboarding](roadmap/phase-12-quickstart.md) | `forgelm quickstart <template>`, 5 templates, sample datasets → `v0.4.5` |
 | 📋 Planned | [Phase 11 — Document Ingestion & Data Audit](roadmap/phase-11-data-ingestion.md) | PDF/DOCX/EPUB → JSONL, PII detection, near-duplicate audit → `v0.5.0` |
-| 📋 Planned | [Phase 12 — (reserved)](roadmap/phase-12-quickstart.md) | Merged into Phase 10.5 |
 | 📋 Planned | [Phase 13 — Pro CLI & Observability Dashboard](roadmap/phase-13-pro-cli.md) | License-gated dashboard, HPO, scheduled jobs, team config store → `v0.6.0-pro` |
 | 📋 Planned | [Phase 14 — Multi-Stage Pipeline Chains](roadmap/phase-14-pipeline-chains.md) | SFT → DPO → GRPO chained config, pipeline provenance artifacts → `v0.5.1` |
 
-**Current milestone:** `v0.3.1rc1` — security hardening and config robustness (April 2026). Webhook URL credential leak, audit log chain gap, GRPO callable bug, TIES merging error — all fixed.
+**Current milestone:** `v0.4.0` — Post-Training Completion (April 2026). Inference primitives, interactive chat REPL, GGUF export, VRAM fit advisor, and deployment config generation.
 
-**Current state:** 11 phases (1, 2, 2.5, 3, 4, 5, 5.5, 6, 7, 8, 9) complete. 5 phases (10, 10.5, 11, 13, 14) planned. Target `v0.4.0` release: Phase 10. Target `v0.4.5`: Phase 10.5 (Quickstart). Target `v0.5.0`: Phase 11.
+**Current state:** 12 phases (1, 2, 2.5, 3, 4, 5, 5.5, 6, 7, 8, 9, 10) complete. 4 phases (10.5, 11, 13, 14) planned. Target `v0.4.5` release: Phase 10.5 (Quickstart). Target `v0.5.0`: Phase 11.
 
 ## Quick summary of what's planned
 
@@ -34,8 +33,8 @@ graph LR
     P14 -.-> V25[v0.5.1]
     P13 -.-> V3[v0.6.0-pro]
 
-    style P10 fill:#002244,stroke:#00aaff
-    style P105 fill:#003300,stroke:#00ff88
+    style P10 fill:#003300,stroke:#00ff88
+    style P105 fill:#002244,stroke:#00aaff
     style P11 fill:#002244,stroke:#00aaff
     style P13 fill:#442200,stroke:#ffaa00
     style P14 fill:#002244,stroke:#00aaff
@@ -55,12 +54,12 @@ docs/
 ├── roadmap.md                                  # This file — short index
 ├── roadmap-tr.md                               # Turkish mirror
 └── roadmap/
-    ├── completed-phases.md                     # Phase 1-9 archive (detailed)
-    ├── phase-10-post-training.md               # Active planning
-    ├── phase-11-data-ingestion.md              # Active planning
-    ├── phase-12-quickstart.md                  # Active planning (now Phase 10.5)
-    ├── phase-13-pro-cli.md                     # Active planning (gated)
-    ├── phase-14-pipeline-chains.md             # Active planning
+    ├── completed-phases.md                     # Phase 1-10 archive (detailed)
+    ├── phase-10-post-training.md               # Completed — v0.4.0
+    ├── phase-11-data-ingestion.md              # Planned — v0.5.0
+    ├── phase-12-quickstart.md                  # Planned — Phase 10.5 — v0.4.5
+    ├── phase-13-pro-cli.md                     # Planned — v0.6.0-pro (gated)
+    ├── phase-14-pipeline-chains.md             # Planned — v0.5.1
     ├── releases.md                             # v0.3.0 → v0.6.0 release notes
     └── risks-and-decisions.md                  # Risk matrix, opportunities, competitive positioning, decision log
 ```
diff --git a/docs/roadmap/completed-phases.md b/docs/roadmap/completed-phases.md
index 998084c2..cd6a2b3a 100644
--- a/docs/roadmap/completed-phases.md
+++ b/docs/roadmap/completed-phases.md
@@ -1,24 +1,25 @@
 # Completed Phases — Archive
 
-> **Note:** Historical archive of ForgeLM's Phase 1-9 completed work. Kept for reference and onboarding. For active planning, see [../roadmap.md](../roadmap.md).
+> **Note:** Historical archive of ForgeLM's Phase 1-10 completed work. Kept for reference and onboarding. For active planning, see [../roadmap.md](../roadmap.md).
 
 ## Summary table
 
-| Phase | Focus | Tasks | Complete |
-|-------|-------|-------|----------|
-| 1 | SOTA Upgrades (QLoRA, DoRA, Unsloth, SFTTrainer) | 6 | ✅ |
-| 2 | Evaluation & Validation (lm-eval, auto-revert, webhook) | 5 | ✅ |
-| 2.5 | Reliability (logging, coverage, CI/CD hardening) | 8 | ✅ |
-| 3 | Enterprise Integration (Wizard, Docker, JSON, offline) | 6 | ✅ |
-| 4 | Ecosystem Growth (ORPO, W&B, multi-dataset, FSDP) | 5 | ✅ |
-| 5 | Alignment Stack (DPO, SimPO, KTO, GRPO) | 5 | ✅ |
-| 5.5 | Technical Debt Resolution | 7 | ✅ |
-| 6 | Enterprise Trust & Compliance (safety, LLM-judge, cost) | 5 | ✅ |
-| 7 | Next-Gen Model Support (MoE, VLM, merging, PiSSA) | 5 | ✅ |
-| 8 | EU AI Act Deep Compliance (Articles 9-17 + Annex IV) | 10 | ✅ |
-| 9 | Advanced Safety & Evaluation Intelligence | 8 | ✅ |
-
-**Toplam: 70 tamamlanmış görev, 11 phase, ~3000 satır kod + 200+ test.**
+| Phase | Focus | Tasks | Complete | Release |
+|-------|-------|-------|----------|---------|
+| 1 | SOTA Upgrades (QLoRA, DoRA, Unsloth, SFTTrainer) | 6 | ✅ | — |
+| 2 | Evaluation & Validation (lm-eval, auto-revert, webhook) | 5 | ✅ | — |
+| 2.5 | Reliability (logging, coverage, CI/CD hardening) | 8 | ✅ | — |
+| 3 | Enterprise Integration (Wizard, Docker, JSON, offline) | 6 | ✅ | — |
+| 4 | Ecosystem Growth (ORPO, W&B, multi-dataset, FSDP) | 5 | ✅ | — |
+| 5 | Alignment Stack (DPO, SimPO, KTO, GRPO) | 5 | ✅ | v0.3.0 |
+| 5.5 | Technical Debt Resolution | 7 | ✅ | v0.3.0 |
+| 6 | Enterprise Trust & Compliance (safety, LLM-judge, cost) | 5 | ✅ | v0.3.0 |
+| 7 | Next-Gen Model Support (MoE, VLM, merging, PiSSA) | 5 | ✅ | v0.3.0 |
+| 8 | EU AI Act Deep Compliance (Articles 9-17 + Annex IV) | 10 | ✅ | v0.3.1 |
+| 9 | Advanced Safety & Evaluation Intelligence | 8 | ✅ | v0.3.1 |
+| 10 | Post-Training Completion (inference, chat, export, fit-check, deploy) | 5 | ✅ | v0.4.0 |
+
+**Toplam: 75 tamamlanmış görev, 12 phase, ~5000 satır kod + 427 test.**
 
 ---
 
@@ -639,195 +640,17 @@ graph TD
 
 ---
 
----
-
-## Phase 10: Post-Training Completion
-**Goal:** Close the "trained, now what?" gap. After a fine-tune finishes, users should be able to sanity-check, export, and hand the model to a serving runtime (Ollama, vLLM, TGI) without leaving ForgeLM.
-**Estimated Effort:** Medium (2-3 months)
-**Priority:** High — single biggest post-9 UX gap; foundation for Phase 12 (quickstart)
-
-> **Context:** External analyses of two adjacent projects (QKV-Core, Trion) plus internal retrospectives converged on the same finding: ForgeLM stops at `output_dir/` with an HF-format adapter/merged model, but the user's actual journey continues to sanity chat → quantization → serving. Competitors (Axolotl, Unsloth) leave this to external tooling. Owning this handoff — without rewriting the inference ecosystem — is a high-value, low-risk addition.
-
-### Tasks:
-
-1. [ ] **`forgelm/inference.py` — generation + logit statistics + adaptive sampling**
-   Core API: `load_model(path, adapter=None, backend="transformers")`, `generate(model, tokenizer, prompt, **kwargs)`, `logit_stats(logits) -> {entropy, top1_prob, effective_vocab}`, `adaptive_sample(logits, temperature, top_k, top_p, entropy_threshold=6.5)`. Chat template reuse from `data.py`. Streaming + non-streaming via `TextIteratorStreamer`. Opt-in safety routing through existing `safety.py`.
-   ```python
-   from forgelm.inference import load_model, generate
-   model, tok = load_model("./outputs/my_run", adapter="./outputs/my_run/adapter_model")
-   text = generate(model, tok, "Hello", max_new_tokens=200, temperature=0.7)
-   ```
-
-2. [ ] **`forgelm chat` — interactive terminal loop**
-   Terminal REPL: streaming output, `/reset`, `/save`, `/temperature 0.x`, `/system <prompt>` commands. `rich` for rendering. Auto-detect HF model vs merged adapter. Optional `--safety` flag wires Llama Guard check on each response (bridge to Layer 3 enterprise features).
-   ```bash
-   forgelm chat ./outputs/my_run
-   forgelm chat ./outputs/my_run --adapter ./outputs/my_run/adapter_model --safety
-   ```
-
-3. [ ] **`forgelm export` — HF → GGUF conversion**
-   Wrap `llama-cpp-python`'s conversion scripts; do not reimplement. Handle adapter merge (LoRA + base → single weights) before conversion. Support quants: `q2_k`, `q3_k_m`, `q4_k_m`, `q5_k_m`, `q8_0`, `f16`. Integrate with `compliance.py`: exported artifact SHA-256 added to `model_integrity.json`. Optional dependency: `pip install forgelm[export]`.
-   ```bash
-   forgelm export ./outputs/my_run --format gguf --quant q4_k_m --output model.gguf
-   ```
-
-4. [ ] **`forgelm fit-check` — VRAM fit advisor**
-   Pre-flight memory estimator. Detects GPU via `torch.cuda.mem_get_info()`. Estimates peak VRAM = base (params × dtype) + activations (heuristic: batch × seq × hidden × 4 × layers) + optimizer state (AdamW 2×, 8bit 0.5×, GaLore rank-dependent). Produces verdict (FITS / TIGHT / OOM) and ordered recommendations (batch↓, seq↓, gradient_checkpointing, QLoRA, GaLore). Calibrated against known model-config pairs; target ±15% accuracy.
-   ```bash
-   forgelm --config my.yaml --fit-check
-   # → GPU: RTX 3060 12GB; Estimated peak: 10.8 GB; Verdict: ✅ FITS with 0.5 GB headroom
-   ```
-
-5. [ ] **`forgelm deploy` — serving handoff config generation**
-   Generates deployment configs for popular inference runtimes; does not run the server itself. Targets: `ollama` (Modelfile), `vllm` (engine config YAML), `tgi` (docker-compose.yaml), `hf-endpoints` (API spec). Output is a ready-to-consume file the user runs with the target tool.
-   ```bash
-   forgelm deploy ./outputs/my_run --target ollama --output ./Modelfile
-   forgelm deploy ./outputs/my_run --target vllm --output ./vllm_config.yaml
-   ```
+## Phase 10: Post-Training Completion ✅ (v0.4.0)
 
-### Requirements:
-- All five modules must work without GPU for config generation (fit-check excepted — it reads GPU but doesn't require one, falls back to hypothetical mode).
-- `inference.py` and `chat.py` share the same load/generate primitives with `safety.py`, `judge.py`, and `synthetic.py`; refactor duplicated `model.generate()` calls into the new module.
-- Each CLI command supports `--output-format json` for pipeline integration.
-- `pip install forgelm[export]` is optional; core install must not require `llama-cpp-python`.
-- Windows/Linux/macOS compatibility for all CLI surface (GGUF export may require specific toolchains, document clearly).
-
-### Delivery:
-- Target release: `v0.4.0` ("Post-Training Completion")
-- Each task = independent PR with tests; no cross-task blocking dependencies.
-
----
-
----
-
-## Phase 11: Document Ingestion & Data Audit
-**Goal:** Turn raw domain documents (PDF, DOCX, EPUB, TXT, plus structured sources) into training-ready JSONL, with automatic data quality reports that plug into EU AI Act Article 10 data governance.
-**Estimated Effort:** Medium (1-2 months)
-**Priority:** High — enterprise onboarding accelerator; bridges ingestion → training → compliance audit in one tool.
-
-> **Context:** Dataset loading today goes through HuggingFace `load_dataset` + JSONL/CSV/Parquet. Enterprises arriving with directories of PDFs (legal, medical, policy manuals) have to write custom preprocessing. This module removes that friction and simultaneously generates governance artifacts that satisfy Article 10 (data collection method, quality metrics, bias declarations).
-
-### Tasks:
+> **Ayrıntılar:** [phase-10-post-training.md](phase-10-post-training.md)
 
-1. [ ] **`forgelm/ingestion.py` — multi-format → JSONL**
-   Parsers for PDF (`pypdf`), DOCX (`python-docx`), EPUB (`ebooklib` + `beautifulsoup4`), plain TXT. Chunking strategies: `sliding` (fixed token window with overlap), `paragraph` (semantic boundary), `semantic` (optional, embedding-based; external dependency). Output: `{"messages": [{"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}]}` SFT-compatible JSONL. Optional dependency group: `pip install forgelm[ingestion]`.
-   ```bash
-   forgelm ingest ./book.epub --chunk 2048 --strategy paragraph --output data/sft.jsonl
-   forgelm ingest ./policies/ --recursive --output data/policies.jsonl
-   ```
-
-2. [ ] **`forgelm/data_audit.py` — dataset quality & governance report**
-   Analyzes a JSONL dataset, produces `data_audit_report.json` with: sample count per split, column schema, text length distribution (min/max/mean/p50/p95), language detection (top-3), duplicate / near-duplicate rate (simhash-based), null/empty rate, PII flag counts (regex-based; optional `presidio` integration). Feeds Phase 8 Article 10 artifact (`data_governance_report.json`).
-   ```bash
-   forgelm --data-audit data/sft.jsonl --output audit/
-   ```
-
-3. [ ] **PII detection hooks**
-   Regex-based detector for: emails, phone numbers (international formats), credit cards (Luhn-validated), IBAN, national IDs (TR, DE, FR, US SSN). Counts flags per sample; optionally masks via `--pii-mask`. Does not block training by default — surfaces in audit report.
-
-4. [ ] **Near-duplicate detection across splits**
-   Simhash / MinHash across train/validation/test. Reports overlap rate. Critical for fair benchmarking — train-test leakage is a silent quality killer.
-
-### Requirements:
-- Ingestion must handle malformed files gracefully (scan PDFs with no text layer → warning + empty result, not crash).
-- Audit runs on CPU; no GPU required.
-- All outputs integrate with Phase 8 compliance artifacts — data governance report references the audit JSON.
-- OCR is out of scope; document this as a limitation and suggest external tooling (Tesseract, AWS Textract).
+5 görev, 5 yeni modül, 89 yeni test. `inference.py`, `chat.py`, `fit_check.py`, `export.py`, `deploy.py`. CLI subcommand mimarisi (`forgelm chat / export / deploy`), `--fit-check` flag. Nisan 2026.
 
-### Delivery:
-- Target release: `v0.4.5` or folded into `v0.5.0`
-- Can start after Phase 10 task 1-2 land; no hard blocker.
-
----
-
----
-
-## Phase 12: Quickstart Layer & Onboarding
-**Goal:** Make "my first fine-tune" a 10-minute experience. One command, one model in the end, zero YAML writing. Without sacrificing the CI/CD-native core — quickstart generates a YAML the user can later customize.
-**Estimated Effort:** Medium (1-2 months)
-**Priority:** High — closes the most-cited adoption gap; direct input to YouTube content strategy.
-
-> **Context:** Strategic decision documented in the [enterprise-vs-simple paradox analysis](../marketing/strategy/01-paradoks-enterprise-vs-sade.md): ForgeLM adds a "Layer 0" entry point without changing its CI/CD-native identity. The same YAML schema, the same trainer, the same outputs — just wrapped in pre-built templates and opinionated defaults. Depends on Phase 10 (`chat`) for end-of-training sanity loop.
-
-### Tasks:
-
-1. [ ] **`forgelm/quickstart.py` + `forgelm quickstart <template>` CLI**
-   Takes a template name, optional model override, optional dataset override. Generates a `my_run.yaml` under `./configs/` and immediately invokes `forgelm --config ./configs/my_run.yaml`. On completion, auto-invokes `forgelm chat` unless `--no-chat` flag. Transparent about what it did — prints generated YAML path.
-   ```bash
-   forgelm quickstart customer-support
-   forgelm quickstart code-assistant --model DeepSeek-Coder-6.7B
-   forgelm quickstart --list
-   ```
-
-2. [ ] **Template library: `forgelm/templates/` + bundled sample datasets**
-   Initial five templates, each = YAML config + sample JSONL (100-500 examples, license-clean):
-   - `customer-support` (Qwen2.5-7B / Llama-3.1-8B, 100 examples, QLoRA r=8, ~15 min on RTX 3060)
-   - `code-assistant` (DeepSeek-Coder-6.7B, 200 examples, QLoRA, ~25 min)
-   - `domain-expert` (Qwen2.5-7B, uses `forgelm ingest` on user-supplied docs)
-   - `medical-qa-tr` (Qwen2.5-7B, 100 TR examples; Turkish-language flagship)
-   - `grpo-math` (Qwen2.5-Math-7B, mini-gsm8k, GRPO reward function, ~45 min)
-   Each template must produce a working model on an 8-12 GB consumer GPU. `fit_check` integration: if GPU too small, quickstart auto-downsizes model choice.
-
-3. [ ] **Conservative default policy for quickstart**
-   All templates ship with: QLoRA 4-bit NF4, rank=8, batch=1 with gradient accumulation, gradient checkpointing on, safety eval off (opt-in only), compliance artifacts off (opt-in only). Rationale: minimize "GPU OOM on first run" and "compliance scared me off" failure modes.
-
-4. [ ] **Wizard integration — template selector first**
-   `forgelm --wizard` opens with "Start from a template?" question. If yes → pass to quickstart flow. If no → existing 10-question flow. Merges the two paths.
-
-5. [ ] **End-to-end smoke test in CI**
-   Nightly CI runs: `forgelm quickstart customer-support --dry-run` for each template. Validates YAML generation + dataset parse + config validation. No GPU required (dry-run). Catches template drift early.
-
-### Requirements:
-- Sample datasets must be license-clean (CC-BY-SA 4.0 or similar permissive, documented in `forgelm/templates/LICENSES.md`).
-- Each template has a companion YouTube video (scheduled in marketing roadmap, not this roadmap).
-- Templates are a foundation for community contributions: `CONTRIBUTING.md` should document how to add new templates; each template is an atomic PR.
-- Quickstart must not introduce a "quickstart vs real training" bifurcation — same underlying code paths, same YAML schema.
-
-### Delivery:
-- Target release: `v0.5.0` ("Quickstart Layer")
-- Blocks on Phase 10 tasks 1 + 2 (`inference.py`, `chat.py`).
-
----
-
----
-
-## Phase 13: Pro CLI & Observability Dashboard
-**Goal:** First paid-tier feature set. Observability and experimentation workflows that open-source users can live without, but teams running ≥5 concurrent experiments cannot. Revenue bridge between consulting (Phase B) and Cloud SaaS (future).
-**Estimated Effort:** High (3-4 months)
-**Priority:** Medium — gated by Phase 10-12 adoption signal. Do not start until `v0.5.0` has ≥1K monthly PyPI installs and ≥2 paying support contracts.
-
-> **Context:** Revenue model documented in the [monetization plan](../marketing/06_revenue_model.md): Pro CLI is the first tier above OSS. Core rule — everything users can reasonably do via shell scripts + public dashboards stays free; what requires ForgeLM-specific infrastructure (experiment graph, HPO orchestration, team config store) is Pro. No feature gating that degrades the free experience.
-
-### Tasks:
-
-1. [ ] **`forgelm pro` CLI subcommand group**
-   Activation via license key (`FORGELM_PRO_KEY` env var or `~/.forgelm/pro.key`). License server minimal: validates key + reports usage quota. Uses `cryptography` library for offline license verification where possible.
-
-2. [ ] **Web dashboard — experiment browser**
-   Local-first web UI (FastAPI + HTMX + Tailwind; no SPA bloat). Reads from `checkpoints/` + `audit_log.jsonl`. Visualizes: run list, config diffs across runs, metric comparisons (loss, eval, safety, cost), artifact browser. Launchable via `forgelm pro dashboard --port 8080`. Optional Docker deployment for team use.
-
-3. [ ] **Hyperparameter optimization (HPO) — Optuna integration**
-   New config section: `hpo: {n_trials, search_space: {...}, metric: eval_loss, direction: minimize}`. Spawns N subordinate training runs, aggregates, produces best-config YAML + comparison report. Integrates with existing auto-revert thresholds.
-
-4. [ ] **Scheduled training jobs**
-   Cron-style config: `schedule: "0 2 * * 0"` (weekly Sunday 2 AM). Wrapper daemon (`forgelm pro schedule run`) watches config, triggers runs, captures output. Pairs naturally with data refresh pipelines ("every Sunday, retrain on latest dataset").
-
-5. [ ] **Cloud GPU cost estimation — real-time pricing**
-   Extends Phase 6 GPU cost estimation with live spot pricing from RunPod, Lambda Labs, vast.ai APIs. Before training starts, estimates cost across providers; after training, computes actual cost and logs drift. Optional — free tier stays with static pricing database.
-
-6. [ ] **Team configuration store**
-   `forgelm pro team push/pull <config-name>` — shared config repository backed by user's Git repo (simple) or ForgeLM-hosted store (later). Permissions + team member management. Enables "our team's golden LoRA config" patterns.
-
-### Requirements:
-- Every Pro feature must have a 90%-equivalent OSS workaround documented. No "you must pay to use ForgeLM properly" messaging — Pro is for convenience and scale, not gatekeeping.
-- Dashboard runs locally by default; cloud-hosted is a separate track.
-- License validation must work offline after first activation (air-gapped compliance preserved).
-- Pricing decisions documented in [marketing/06_revenue_model.md](../marketing/06_revenue_model.md), not here.
-
-### Delivery:
-- Target release: `v0.6.0-pro` (separately distributed; OSS core remains at `v0.5.x`)
-- Gated: do not ship before traction validation.
-
----
+**Tasks:**
+1. [x] `forgelm/inference.py` — `load_model`, `generate`, `generate_stream`, `logit_stats`, `adaptive_sample`
+2. [x] `forgelm chat` — streaming REPL, slash commands, rich rendering, Llama Guard routing
+3. [x] `forgelm export` — GGUF via llama-cpp-python, 6 quant levels, SHA-256 → model_integrity.json
+4. [x] `forgelm --fit-check` — VRAM estimator, FITS/TIGHT/OOM/UNKNOWN verdict, JSON output
+5. [x] `forgelm deploy` — ollama / vllm / tgi / hf-endpoints config dosyası üretimi
 
 ---
diff --git a/docs/roadmap/phase-10-post-training.md b/docs/roadmap/phase-10-post-training.md
index 8bbbdb6f..a34ba1a5 100644
--- a/docs/roadmap/phase-10-post-training.md
+++ b/docs/roadmap/phase-10-post-training.md
@@ -8,41 +8,46 @@
 
 > **Context:** External analyses of two adjacent projects (QKV-Core, Trion) plus internal retrospectives converged on the same finding: ForgeLM stops at `output_dir/` with an HF-format adapter/merged model, but the user's actual journey continues to sanity chat → quantization → serving. Competitors (Axolotl, Unsloth) leave this to external tooling. Owning this handoff — without rewriting the inference ecosystem — is a high-value, low-risk addition.
 
+**Status: ✅ Complete** — shipped in `v0.4.0` (April 2026)
+
 ### Tasks:
 
-1. [ ] **`forgelm/inference.py` — generation + logit statistics + adaptive sampling**
-   Core API: `load_model(path, adapter=None, backend="transformers")`, `generate(model, tokenizer, prompt, **kwargs)`, `logit_stats(logits) -> {entropy, top1_prob, effective_vocab}`, `adaptive_sample(logits, temperature, top_k, top_p, entropy_threshold=6.5)`. Chat template reuse from `data.py`. Streaming + non-streaming via `TextIteratorStreamer`. Opt-in safety routing through existing `safety.py`.
+1. [x] **`forgelm/inference.py` — generation + logit statistics + adaptive sampling**
+   Core API: `load_model(path, adapter=None, backend="transformers")`, `generate(model, tokenizer, prompt, **kwargs)`, `generate_stream(...)` (streaming via `TextIteratorStreamer`), `logit_stats(logits) -> {entropy, top1_prob, effective_vocab}`, `adaptive_sample(logits, temperature, top_k, top_p, entropy_threshold=6.5)`. Chat template reuse via `tokenizer.apply_chat_template`. Fallback to `"role: content"` join when no template. Shared by `chat.py`, `judge.py`, `synthetic.py`.
    ```python
    from forgelm.inference import load_model, generate
    model, tok = load_model("./outputs/my_run", adapter="./outputs/my_run/adapter_model")
    text = generate(model, tok, "Hello", max_new_tokens=200, temperature=0.7)
    ```
 
-2. [ ] **`forgelm chat` — interactive terminal loop**
-   Terminal REPL: streaming output, `/reset`, `/save`, `/temperature 0.x`, `/system <prompt>` commands. `rich` for rendering. Auto-detect HF model vs merged adapter. Optional `--safety` flag wires Llama Guard check on each response (bridge to Layer 3 enterprise features).
+2. [x] **`forgelm chat` — interactive terminal loop**
+   Terminal REPL in `forgelm/chat.py`: streaming output (default), `/reset`, `/save [file]`, `/temperature 0.x`, `/system <prompt>`, `/help` commands. `rich` optional rendering. Optional `--safety` flag. History management with 50-pair cap.
    ```bash
    forgelm chat ./outputs/my_run
    forgelm chat ./outputs/my_run --adapter ./outputs/my_run/adapter_model --safety
    ```
 
-3. [ ] **`forgelm export` — HF → GGUF conversion**
-   Wrap `llama-cpp-python`'s conversion scripts; do not reimplement. Handle adapter merge (LoRA + base → single weights) before conversion. Support quants: `q2_k`, `q3_k_m`, `q4_k_m`, `q5_k_m`, `q8_0`, `f16`. Integrate with `compliance.py`: exported artifact SHA-256 added to `model_integrity.json`. Optional dependency: `pip install forgelm[export]`.
+3. [x] **`forgelm export` — HF → GGUF conversion**
+   Wraps `llama-cpp-python`'s `convert_hf_to_gguf.py`; no reimplementation. Handles adapter merge (LoRA + base → merged fp16) before conversion. Supports quants: `q2_k`, `q3_k_m`, `q4_k_m`, `q5_k_m`, `q8_0`, `f16`. SHA-256 of output artifact appended to `model_integrity.json`. Optional dependency: `pip install forgelm[export]`.
    ```bash
    forgelm export ./outputs/my_run --format gguf --quant q4_k_m --output model.gguf
    ```
 
-4. [ ] **`forgelm fit-check` — VRAM fit advisor**
-   Pre-flight memory estimator. Detects GPU via `torch.cuda.mem_get_info()`. Estimates peak VRAM = base (params × dtype) + activations (heuristic: batch × seq × hidden × 4 × layers) + optimizer state (AdamW 2×, 8bit 0.5×, GaLore rank-dependent). Produces verdict (FITS / TIGHT / OOM) and ordered recommendations (batch↓, seq↓, gradient_checkpointing, QLoRA, GaLore). Calibrated against known model-config pairs; target ±15% accuracy.
+4. [x] **`--fit-check` — VRAM fit advisor**
+   Pre-flight memory estimator in `forgelm/fit_check.py`. Detects GPU via `torch.cuda.mem_get_info()`. Estimates peak VRAM = base (params × dtype) + LoRA adapter + optimizer state (AdamW/8bit/GaLore variants) + activations (with gradient-checkpointing scaling). Produces verdict (FITS / TIGHT / OOM / UNKNOWN) with ordered recommendations. Falls back to hypothetical mode when no GPU is detected.
    ```bash
    forgelm --config my.yaml --fit-check
-   # → GPU: RTX 3060 12GB; Estimated peak: 10.8 GB; Verdict: ✅ FITS with 0.5 GB headroom
+   # → GPU: RTX 3060 12GB; Estimated peak: 10.8 GB; Verdict: ✅ FITS
+   forgelm --config my.yaml --fit-check --output-format json
    ```
 
-5. [ ] **`forgelm deploy` — serving handoff config generation**
-   Generates deployment configs for popular inference runtimes; does not run the server itself. Targets: `ollama` (Modelfile), `vllm` (engine config YAML), `tgi` (docker-compose.yaml), `hf-endpoints` (API spec). Output is a ready-to-consume file the user runs with the target tool.
+5. [x] **`forgelm deploy` — serving handoff config generation**
+   Template-based config generation in `forgelm/deploy.py`; does not run the server. Targets: `ollama` (Modelfile), `vllm` (engine config YAML), `tgi` (docker-compose.yaml), `hf-endpoints` (JSON spec). All targets support `--output-format json`.
    ```bash
    forgelm deploy ./outputs/my_run --target ollama --output ./Modelfile
    forgelm deploy ./outputs/my_run --target vllm --output ./vllm_config.yaml
+   forgelm deploy ./outputs/my_run --target tgi --output ./docker-compose.yaml
+   forgelm deploy ./outputs/my_run --target hf-endpoints --output ./endpoint.json
    ```
 
 ### Requirements:
diff --git a/docs/roadmap/phase-11-data-ingestion.md b/docs/roadmap/phase-11-data-ingestion.md
index bde73782..cc729936 100644
--- a/docs/roadmap/phase-11-data-ingestion.md
+++ b/docs/roadmap/phase-11-data-ingestion.md
@@ -36,7 +36,7 @@
 - OCR is out of scope; document this as a limitation and suggest external tooling (Tesseract, AWS Textract).
 
 ### Delivery:
-- Target release: `v0.4.5` or folded into `v0.5.0`
-- Can start after Phase 10 task 1-2 land; no hard blocker.
+- Target release: `v0.5.0`
+- Can start after Phase 10.5 (Quickstart) lands; no hard blocker on code, but UX sequencing matters.
 
 ---
diff --git a/docs/roadmap/phase-12-quickstart.md b/docs/roadmap/phase-12-quickstart.md
index 53051bb2..711d1e3a 100644
--- a/docs/roadmap/phase-12-quickstart.md
+++ b/docs/roadmap/phase-12-quickstart.md
@@ -1,12 +1,13 @@
-# Phase 12: Quickstart Layer & Onboarding
+# Phase 10.5: Quickstart Layer & Onboarding
 
 > **Not:** Bu dosya tek bir planlanan fazı detaylandırır. Tüm fazların özeti için [../roadmap.md](../roadmap.md).
+> **Dosya adı:** `phase-12-quickstart.md` — orijinal Phase 12 sırasından kaldığı için adı değiştirilmedi; içerik Phase 10.5'e karşılık gelir.
 
 **Goal:** Make "my first fine-tune" a 10-minute experience. One command, one model in the end, zero YAML writing. Without sacrificing the CI/CD-native core — quickstart generates a YAML the user can later customize.
 **Estimated Effort:** Medium (1-2 months)
 **Priority:** Critical — community flywheel; directly drives EU AI Act enterprise pipeline
 
-> **Phase ordering rationale:** Moved from Phase 12 to Phase 10.5. Quickstart is the primary community growth driver; stars → enterprise leads → compliance sales. EU AI Act enforcement (August 2, 2026) creates a closing window. This phase must ship before Data Ingestion (Phase 11).
+> **Phase ordering rationale:** Reprioritized from Phase 12 to Phase 10.5. Quickstart is the primary community growth driver; stars → enterprise leads → compliance sales. EU AI Act enforcement (August 2, 2026) creates a closing window. This phase must ship before Data Ingestion (Phase 11).
 
 > **Context:** Strategic decision documented in the [enterprise-vs-simple paradox analysis](../marketing/strategy/01-paradoks-enterprise-vs-sade.md): ForgeLM adds a "Layer 0" entry point without changing its CI/CD-native identity. The same YAML schema, the same trainer, the same outputs — just wrapped in pre-built templates and opinionated defaults. Depends on Phase 10 (`chat`) for end-of-training sanity loop.
 
diff --git a/docs/roadmap/releases.md b/docs/roadmap/releases.md
index c71e51ca..03f016cd 100644
--- a/docs/roadmap/releases.md
+++ b/docs/roadmap/releases.md
@@ -18,11 +18,9 @@
 
 ---
 
----
-
 ## v0.3.1rc1 — "Security & Config Hardening" (2026-04-25)
 
-**Status:** Released (release candidate)
+**Status:** Folded into v0.4.0 (changes shipped as part of the v0.4.0 release; no standalone tag)
 
 ### Changes:
 - **Security**: Webhook URLs excluded from HuggingFace Hub model cards — prevent credential leaks
@@ -40,9 +38,19 @@
 
 ---
 
-## v0.4.0 — "Post-Training Completion" (Planlandı)
+## v0.4.0 — "Post-Training Completion" (2026-04-25)
+
+**Status:** Released
 
-Odak: [Phase 10](phase-10-post-training.md). Full post-training handoff: inference, chat, GGUF export, VRAM fit-check, deployment config generation. All five Phase 10 tasks (inference.py, chat.py, export, fit-check, deploy) complete before tagging v0.4.0.
+Odak: [Phase 10](phase-10-post-training.md). Full post-training handoff: inference, chat, GGUF export, VRAM fit-check, deployment config generation.
+
+### Features:
+1. [x] **`forgelm/inference.py`** — Shared generation primitives: `load_model`, `generate`, `generate_stream` (streaming via background thread), `logit_stats`, `adaptive_sample`. Supports transformers + peft (merge-and-unload) + unsloth backends.
+2. [x] **`forgelm chat`** — Interactive terminal REPL with streaming output, `/reset`, `/save`, `/temperature`, `/system` slash commands. Optional `rich` rendering. History capped at 50 turns. Optional Llama Guard safety routing.
+3. [x] **`forgelm export`** — GGUF conversion via `llama-cpp-python`'s `convert_hf_to_gguf.py`. Supports adapter merge before conversion. 6 quantization levels (`q2_k`, `q3_k_m`, `q4_k_m`, `q5_k_m`, `q8_0`, `f16`). SHA-256 appended to `model_integrity.json`. `pip install forgelm[export]`.
+4. [x] **`forgelm --fit-check`** — Pre-flight VRAM estimator. Architecture via `AutoConfig`. Formula: base weights + LoRA adapter + optimizer state (AdamW/8bit/GaLore) + activations (gradient-checkpointing aware). Verdicts: FITS / TIGHT / OOM / UNKNOWN. `--output-format json` for CI/CD.
+5. [x] **`forgelm deploy`** — Deployment config generator for 4 targets: `ollama` (Modelfile), `vllm` (YAML), `tgi` (docker-compose.yaml), `hf-endpoints` (JSON). Does not run the server itself.
+6. [x] **`pip install forgelm[export]`** — Optional `llama-cpp-python>=0.2.90` extra. `pip install forgelm[chat]` — Optional `rich>=13.0.0` extra.
 
 ---
 
diff --git a/forgelm/__init__.py b/forgelm/__init__.py
index 1ef26905..5a739239 100644
--- a/forgelm/__init__.py
+++ b/forgelm/__init__.py
@@ -7,7 +7,7 @@
 
 from .config import ConfigError, ForgeConfig, load_config
 
-__version__ = "0.3.1rc1"
+__version__ = "0.4.0"
 
 __all__ = [
     "load_config",
diff --git a/forgelm/benchmark.py b/forgelm/benchmark.py
index b282ef7d..7c82d6f0 100644
--- a/forgelm/benchmark.py
+++ b/forgelm/benchmark.py
@@ -34,6 +34,69 @@ def _check_lm_eval_available() -> None:
         ) from e
 
 
+# Keys lm-eval may use for accuracy, in priority order
+_ACC_METRIC_KEYS = ("acc_norm,none", "acc,none", "acc_norm", "acc")
+
+
+def _extract_task_score(task_name: str, task_result: Dict[str, Any]) -> Optional[float]:
+    """Pick the most appropriate accuracy metric out of an lm-eval task result."""
+    for key in _ACC_METRIC_KEYS:
+        score = task_result.get(key)
+        if score is not None:
+            logger.info("  %s: %.4f", task_name, score)
+            return float(score)
+
+    # Fallback: any key that looks like an accuracy
+    for key, value in task_result.items():
+        if isinstance(value, (int, float)) and "acc" in key:
+            logger.info("  %s: %.4f (%s)", task_name, value, key)
+            return float(value)
+
+    logger.warning("  %s: no accuracy metric found in results", task_name)
+    return None
+
+
+def _parse_results(raw_results: Dict[str, Any]) -> Dict[str, float]:
+    """Convert raw lm-eval per-task output into a flat task → accuracy map."""
+    scores: Dict[str, float] = {}
+    for task_name, task_result in raw_results.items():
+        score = _extract_task_score(task_name, task_result)
+        if score is not None:
+            scores[task_name] = score
+    return scores
+
+
+def _save_benchmark_json(
+    output_dir: str,
+    tasks: List[str],
+    scores: Dict[str, float],
+    average_score: float,
+    passed: bool,
+    num_fewshot: Optional[int],
+    limit: Optional[int],
+) -> None:
+    """Persist the benchmark summary to ``benchmark_results.json``."""
+    os.makedirs(output_dir, exist_ok=True)
+    results_path = os.path.join(output_dir, "benchmark_results.json")
+    try:
+        with open(results_path, "w") as f:
+            json.dump(
+                {
+                    "tasks": tasks,
+                    "scores": scores,
+                    "average_score": average_score,
+                    "passed": passed,
+                    "num_fewshot": num_fewshot,
+                    "limit": limit,
+                },
+                f,
+                indent=2,
+            )
+        logger.info("Benchmark results saved to %s", results_path)
+    except Exception as e:
+        logger.warning("Failed to save benchmark results: %s", e)
+
+
 def run_benchmark(
     model: Any,
     tokenizer: Any,
@@ -70,72 +133,27 @@ def run_benchmark(
 
     logger.info("Starting benchmark evaluation with tasks: %s", tasks)
 
-    # Wrap model for lm-eval
     try:
-        lm_obj = HFLM(
-            pretrained=model,
-            tokenizer=tokenizer,
-            batch_size=batch_size,
-        )
+        lm_obj = HFLM(pretrained=model, tokenizer=tokenizer, batch_size=batch_size)
     except Exception as e:
         logger.error("Failed to initialize lm-eval model wrapper: %s", e)
-        return BenchmarkResult(
-            passed=False,
-            failure_reason=f"Model wrapper initialization failed: {e}",
-        )
+        return BenchmarkResult(passed=False, failure_reason=f"Model wrapper initialization failed: {e}")
 
-    # Build task arguments
-    task_kwargs = {}
+    task_kwargs: Dict[str, Any] = {}
     if num_fewshot is not None:
         task_kwargs["num_fewshot"] = num_fewshot
 
-    # Run evaluation
     try:
-        results = lm_eval.simple_evaluate(
-            model=lm_obj,
-            tasks=tasks,
-            limit=limit,
-            **task_kwargs,
-        )
+        results = lm_eval.simple_evaluate(model=lm_obj, tasks=tasks, limit=limit, **task_kwargs)
     except Exception as e:
         logger.error("Benchmark evaluation failed: %s", e)
-        return BenchmarkResult(
-            passed=False,
-            failure_reason=f"Evaluation execution failed: {e}",
-        )
+        return BenchmarkResult(passed=False, failure_reason=f"Evaluation execution failed: {e}")
 
-    # Parse results
-    scores = {}
     raw_results = results.get("results", {})
-
-    for task_name, task_result in raw_results.items():
-        # lm-eval stores metrics under various keys; prefer acc_norm, then acc
-        # Use explicit None checks to avoid treating 0.0 as missing
-        score = task_result.get("acc_norm,none")
-        if score is None:
-            score = task_result.get("acc,none")
-        if score is None:
-            score = task_result.get("acc_norm")
-        if score is None:
-            score = task_result.get("acc")
-        if score is not None:
-            scores[task_name] = float(score)
-            logger.info("  %s: %.4f", task_name, score)
-        else:
-            # Try to find any metric that looks like an accuracy
-            for key, value in task_result.items():
-                if isinstance(value, (int, float)) and "acc" in key:
-                    scores[task_name] = float(value)
-                    logger.info("  %s: %.4f (%s)", task_name, value, key)
-                    break
-            else:
-                logger.warning("  %s: no accuracy metric found in results", task_name)
-
-    # Compute average
+    scores = _parse_results(raw_results)
     average_score = sum(scores.values()) / len(scores) if scores else 0.0
     logger.info("Average benchmark score: %.4f", average_score)
 
-    # Check minimum score threshold
     passed = True
     failure_reason = None
     if min_score is not None and average_score < min_score:
@@ -143,24 +161,8 @@ def run_benchmark(
         failure_reason = f"Average benchmark score ({average_score:.4f}) is below minimum threshold ({min_score:.4f})."
         logger.error("BENCHMARK FAILED: %s", failure_reason)
 
-    # Save results to file
     if output_dir:
-        os.makedirs(output_dir, exist_ok=True)
-        results_path = os.path.join(output_dir, "benchmark_results.json")
-        try:
-            output_data = {
-                "tasks": tasks,
-                "scores": scores,
-                "average_score": average_score,
-                "passed": passed,
-                "num_fewshot": num_fewshot,
-                "limit": limit,
-            }
-            with open(results_path, "w") as f:
-                json.dump(output_data, f, indent=2)
-            logger.info("Benchmark results saved to %s", results_path)
-        except Exception as e:
-            logger.warning("Failed to save benchmark results: %s", e)
+        _save_benchmark_json(output_dir, tasks, scores, average_score, passed, num_fewshot, limit)
 
     return BenchmarkResult(
         scores=scores,
diff --git a/forgelm/chat.py b/forgelm/chat.py
new file mode 100644
index 00000000..a47d6f68
--- /dev/null
+++ b/forgelm/chat.py
@@ -0,0 +1,377 @@
+"""
+Interactive terminal chat REPL for post-training model testing.
+
+Provides streaming output, slash commands, and optional per-response safety
+routing.  ``rich`` is used for pretty rendering when available; falls back to
+plain print otherwise.
+
+Usage (programmatic):
+    from forgelm.chat import run_chat
+    run_chat("./outputs/final_model", temperature=0.7)
+
+Usage (CLI):
+    forgelm chat ./outputs/final_model
+    forgelm chat ./outputs/final_model --adapter ./outputs/adapter
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import datetime
+from typing import Any, List, Optional
+
+logger = logging.getLogger("forgelm.chat")
+
+try:
+    from rich.console import Console
+    from rich.panel import Panel
+
+    _HAS_RICH = True
+    _console = Console()
+except ImportError:
+    _HAS_RICH = False
+    _console = None  # type: ignore[assignment]
+
+# Slash-command prefix
+_CMD = "/"
+
+# Maximum history entries kept in memory (user + assistant pairs = 2 × N turns)
+_MAX_HISTORY_PAIRS = 50
+
+
+class ChatSession:
+    """Stateful interactive chat session.
+
+    Manages conversation history, slash-command dispatch, streaming output,
+    and optional safety checking.  Designed to be re-entrant for testing: pass
+    ``input_fn`` and ``output_fn`` to override stdin/stdout.
+    """
+
+    def __init__(
+        self,
+        model: Any,
+        tokenizer: Any,
+        *,
+        system_prompt: Optional[str] = None,
+        temperature: float = 0.7,
+        max_new_tokens: int = 512,
+        stream: bool = True,
+        input_fn=None,
+        output_fn=None,
+    ) -> None:
+        self.model = model
+        self.tokenizer = tokenizer
+        self.system_prompt = system_prompt
+        self.temperature = temperature
+        self.max_new_tokens = max_new_tokens
+        self.stream = stream
+        self.history: List[dict] = []
+        self._input = input_fn or input
+        self._output = output_fn or self._default_output
+
+    # ------------------------------------------------------------------
+    # Output helpers
+    # ------------------------------------------------------------------
+
+    def _default_output(self, text: str, end: str = "\n", flush: bool = False) -> None:
+        if _HAS_RICH:
+            _console.print(text, end=end)
+            if flush:
+                # rich Console buffers on small writes; force a real flush so
+                # token-by-token streaming doesn't appear frozen. Narrow the
+                # catch to the actual failure modes — closed stdout (OSError)
+                # or a console without a file attribute (AttributeError).
+                try:
+                    _console.file.flush()
+                except (OSError, AttributeError):
+                    pass
+        else:
+            print(text, end=end, flush=flush)
+
+    def _print(self, text: str) -> None:
+        self._output(text)
+
+    def _print_inline(self, text: str) -> None:
+        self._output(text, end="", flush=True)
+
+    def _print_inline_raw(self, text: str) -> None:
+        """Inline output that must be treated as plain text, not rich markup.
+
+        Used for streaming model tokens — training data routinely contains
+        bracketed strings (`[red]ALERT[/red]`, `[/]`, `[link=...]`) that rich
+        would interpret as markup, scrambling the rendered output and creating
+        a low-grade prompt-injection vector.
+        """
+        if _HAS_RICH:
+            from rich.markup import escape as _rich_escape
+
+            self._output(_rich_escape(text), end="", flush=True)
+        else:
+            self._output(text, end="", flush=True)
+
+    # ------------------------------------------------------------------
+    # Session lifecycle
+    # ------------------------------------------------------------------
+
+    def run(self) -> None:
+        """Start the REPL loop.  Blocks until the user types /exit."""
+        self._print_welcome()
+
+        while True:
+            try:
+                user_input = self._input("\n> ").strip()
+            except (EOFError, KeyboardInterrupt):
+                self._print("\n[Goodbye]")
+                break
+
+            if not user_input:
+                continue
+
+            if user_input.startswith(_CMD):
+                keep_running = self._handle_command(user_input)
+                if not keep_running:
+                    break
+                continue
+
+            self._generate_and_print(user_input)
+
+    # ------------------------------------------------------------------
+    # Slash-command dispatch
+    # ------------------------------------------------------------------
+
+    def _handle_command(self, raw: str) -> bool:
+        """Dispatch a slash command.  Returns ``False`` to exit the loop."""
+        parts = raw.strip().split(maxsplit=1)
+        directive = parts[0].lower()
+        arg = parts[1].strip() if len(parts) > 1 else ""
+
+        handlers = {
+            "/exit": self._cmd_exit,
+            "/quit": self._cmd_exit,
+            "/reset": self._cmd_reset,
+            "/save": self._cmd_save,
+            "/temperature": self._cmd_temperature,
+            "/system": self._cmd_system,
+            "/help": self._cmd_help,
+            "/?": self._cmd_help,
+        }
+
+        handler = handlers.get(directive)
+        if handler is None:
+            self._print(f"[Unknown command: {directive!r}. Type /help for available commands.]")
+            return True
+
+        return handler(arg)
+
+    def _cmd_exit(self, _: str) -> bool:
+        self._print("[Session ended]")
+        return False
+
+    def _cmd_reset(self, _: str) -> bool:
+        self.history.clear()
+        self._print("[Conversation history cleared]")
+        return True
+
+    def _cmd_save(self, path: str) -> bool:
+        if not path:
+            ts = datetime.now().strftime("%Y%m%d_%H%M%S")
+            path = f"chat_history_{ts}.jsonl"
+        try:
+            with open(path, "w", encoding="utf-8") as f:
+                # Persist the system prompt as the first message so the saved
+                # transcript is replayable as-is (reproducibility requirement).
+                if self.system_prompt:
+                    f.write(
+                        json.dumps(
+                            {"role": "system", "content": self.system_prompt},
+                            ensure_ascii=False,
+                        )
+                        + "\n"
+                    )
+                for msg in self.history:
+                    f.write(json.dumps(msg, ensure_ascii=False) + "\n")
+            total = len(self.history) + (1 if self.system_prompt else 0)
+            self._print(f"[History saved → {path} ({total} messages)]")
+        except OSError as e:
+            self._print(f"[Save failed: {e}]")
+        return True
+
+    def _cmd_temperature(self, arg: str) -> bool:
+        try:
+            val = float(arg)
+            if not 0.0 < val <= 2.0:
+                raise ValueError
+            self.temperature = val
+            self._print(f"[Temperature → {self.temperature}]")
+        except ValueError:
+            self._print("[Usage: /temperature 0.7  (range: 0.0 < t ≤ 2.0)]")
+        return True
+
+    def _cmd_system(self, arg: str) -> bool:
+        if arg:
+            self.system_prompt = arg
+            self._print("[System prompt updated]")
+        else:
+            current = self.system_prompt or "(none)"
+            self._print(f"[System prompt: {current}]")
+        return True
+
+    def _cmd_help(self, _: str) -> bool:
+        self._print(
+            "\n".join(
+                [
+                    "",
+                    "  /reset              Clear conversation history",
+                    "  /save [file]        Save history to JSONL file",
+                    "  /temperature N      Set sampling temperature (0.0 < N ≤ 2.0)",
+                    "  /system [prompt]    Set or view system prompt",
+                    "  /exit, /quit        End the chat session",
+                    "  /help, /?           Show this help",
+                    "",
+                ]
+            )
+        )
+        return True
+
+    # ------------------------------------------------------------------
+    # Generation
+    # ------------------------------------------------------------------
+
+    def _build_messages(self, user_input: str) -> List[dict]:
+        messages = []
+        if self.system_prompt:
+            messages.append({"role": "system", "content": self.system_prompt})
+        # Trim history to avoid context overflow (keep last N pairs)
+        trimmed = self.history[-(2 * _MAX_HISTORY_PAIRS) :]
+        messages.extend(trimmed)
+        messages.append({"role": "user", "content": user_input})
+        return messages
+
+    def _generate_and_print(self, user_input: str) -> None:
+        from .inference import generate, generate_stream
+
+        messages = self._build_messages(user_input)
+
+        prefix = "[bold green]Assistant:[/bold green] " if _HAS_RICH else "Assistant: "
+        self._print_inline(prefix)
+
+        response = ""
+        if self.stream:
+            try:
+                for token in generate_stream(
+                    self.model,
+                    self.tokenizer,
+                    "",
+                    messages=messages,
+                    temperature=self.temperature,
+                    max_new_tokens=self.max_new_tokens,
+                ):
+                    self._print_inline_raw(token)
+                    response += token
+            except Exception as e:
+                self._print(f"\n[Generation error: {e}]")
+                return
+            self._print("")  # trailing newline
+        else:
+            try:
+                response = generate(
+                    self.model,
+                    self.tokenizer,
+                    "",
+                    messages=messages,
+                    temperature=self.temperature,
+                    max_new_tokens=self.max_new_tokens,
+                )
+            except Exception as e:
+                self._print(f"[Generation error: {e}]")
+                return
+            # Non-streaming path: full response is also untrusted model output
+            if _HAS_RICH:
+                from rich.markup import escape as _rich_escape
+
+                self._print(_rich_escape(response))
+            else:
+                self._print(response)
+
+        # Append to history
+        self.history.append({"role": "user", "content": user_input})
+        self.history.append({"role": "assistant", "content": response})
+
+    # ------------------------------------------------------------------
+    # Welcome screen
+    # ------------------------------------------------------------------
+
+    def _print_welcome(self) -> None:
+        lines = [
+            "ForgeLM Chat  —  type your message and press Enter",
+            f"Streaming : {'on' if self.stream else 'off'}  |  Temperature : {self.temperature}",
+        ]
+        if self.system_prompt:
+            excerpt = self.system_prompt[:70] + "…" if len(self.system_prompt) > 70 else self.system_prompt
+            lines.append(f"System    : {excerpt}")
+        lines.append("Commands  : /help  /reset  /save  /temperature  /system  /exit")
+        lines.append("─" * 56)
+
+        if _HAS_RICH:
+            self._print(Panel("\n".join(lines), title="[bold]ForgeLM[/bold]", border_style="blue"))
+        else:
+            for line in lines:
+                self._print(line)
+
+
+# ---------------------------------------------------------------------------
+# Convenience entry point (called from CLI)
+# ---------------------------------------------------------------------------
+
+
+def run_chat(
+    model_path: str,
+    *,
+    adapter: Optional[str] = None,
+    system_prompt: Optional[str] = None,
+    temperature: float = 0.7,
+    max_new_tokens: int = 512,
+    stream: bool = True,
+    load_in_4bit: bool = False,
+    load_in_8bit: bool = False,
+    trust_remote_code: bool = False,
+    backend: str = "transformers",
+) -> None:
+    """Load *model_path* and start an interactive chat session.
+
+    This is the primary entry point called by the ``forgelm chat`` CLI subcommand.
+
+    Args:
+        model_path: Local directory or HF Hub model ID.
+        adapter: Optional PEFT adapter directory (merged at load time).
+        system_prompt: System-role message prepended to every conversation.
+        temperature: Initial sampling temperature (changeable with /temperature).
+        max_new_tokens: Maximum tokens to generate per response.
+        stream: Stream tokens as they are produced (default True).
+        load_in_4bit: 4-bit NF4 quantisation via bitsandbytes.
+        load_in_8bit: 8-bit quantisation via bitsandbytes.
+        trust_remote_code: Pass through to ``AutoModelForCausalLM``.
+        backend: ``"transformers"`` or ``"unsloth"``.
+    """
+    from .inference import load_model
+
+    logger.info("Loading model: %s (adapter=%s, 4bit=%s)", model_path, adapter, load_in_4bit)
+    model, tokenizer = load_model(
+        model_path,
+        adapter=adapter,
+        backend=backend,
+        load_in_4bit=load_in_4bit,
+        load_in_8bit=load_in_8bit,
+        trust_remote_code=trust_remote_code,
+    )
+
+    session = ChatSession(
+        model=model,
+        tokenizer=tokenizer,
+        system_prompt=system_prompt,
+        temperature=temperature,
+        max_new_tokens=max_new_tokens,
+        stream=stream,
+    )
+    session.run()
diff --git a/forgelm/cli.py b/forgelm/cli.py
index 9858e982..b7f530a3 100644
--- a/forgelm/cli.py
+++ b/forgelm/cli.py
@@ -44,8 +44,152 @@ def _setup_logging(log_level: str, json_format: bool = False) -> None:
     )
 
 
+def _add_common_subparser_flags(p: argparse.ArgumentParser, *, include_output_format: bool) -> None:
+    """Register the shared --quiet / --log-level / --output-format flags.
+
+    Uses ``default=argparse.SUPPRESS`` so an explicit flag at the main-parser
+    level (before the subcommand) is not clobbered when the subparser fills
+    in its own defaults.
+    """
+    if include_output_format:
+        p.add_argument(
+            "--output-format",
+            type=str,
+            default=argparse.SUPPRESS,
+            choices=["text", "json"],
+            help="Output format: text (default) or json.",
+        )
+    p.add_argument("-q", "--quiet", action="store_true", default=argparse.SUPPRESS, help="Suppress INFO logs.")
+    p.add_argument(
+        "--log-level",
+        type=str,
+        default=argparse.SUPPRESS,
+        choices=["DEBUG", "INFO", "WARNING", "ERROR"],
+        help="Set logging verbosity (default: INFO).",
+    )
+
+
+def _add_chat_subcommand(subparsers) -> None:
+    p = subparsers.add_parser(
+        "chat",
+        help="Interactive chat REPL with a fine-tuned model.",
+        description=(
+            "Load a fine-tuned model and start an interactive terminal session.  "
+            "Supports streaming output, slash commands (/reset, /save, /temperature, "
+            "/system, /exit), and optional per-response safety annotations."
+        ),
+    )
+    p.add_argument("model_path", help="Path to a saved HuggingFace model directory or HF Hub ID.")
+    p.add_argument("--adapter", type=str, default=None, help="PEFT adapter directory to merge before chat.")
+    p.add_argument("--system", type=str, default=None, metavar="PROMPT", help="Initial system prompt.")
+    p.add_argument("--temperature", type=float, default=0.7, help="Sampling temperature (default: 0.7).")
+    p.add_argument("--max-new-tokens", type=int, default=512, help="Max tokens per response (default: 512).")
+    p.add_argument("--no-stream", action="store_true", help="Disable streaming output.")
+    p.add_argument("--load-in-4bit", action="store_true", help="Load model in 4-bit NF4 quantisation.")
+    p.add_argument("--load-in-8bit", action="store_true", help="Load model in 8-bit quantisation.")
+    p.add_argument("--trust-remote-code", action="store_true", help="Allow execution of model-bundled code.")
+    p.add_argument(
+        "--backend",
+        type=str,
+        default="transformers",
+        choices=["transformers", "unsloth"],
+        help="Model backend (default: transformers).",
+    )
+    # chat is interactive; --output-format doesn't apply.
+    _add_common_subparser_flags(p, include_output_format=False)
+
+
+def _add_export_subcommand(subparsers) -> None:
+    p = subparsers.add_parser(
+        "export",
+        help="Export a fine-tuned model to GGUF format.",
+        description=(
+            "Convert a HuggingFace model to GGUF for use with Ollama, llama.cpp, "
+            "and compatible runtimes.  Requires: pip install 'forgelm[export]'"
+        ),
+    )
+    p.add_argument("model_path", help="Path to a saved HuggingFace model directory.")
+    p.add_argument("--output", type=str, required=True, metavar="FILE", help="Output .gguf file path.")
+    p.add_argument(
+        "--format",
+        type=str,
+        default="gguf",
+        choices=["gguf"],
+        help="Export format (default: gguf).",
+    )
+    p.add_argument(
+        "--quant",
+        type=str,
+        default="q4_k_m",
+        choices=["q2_k", "q3_k_m", "q4_k_m", "q5_k_m", "q8_0", "f16"],
+        help="Quantisation type (default: q4_k_m).",
+    )
+    p.add_argument("--adapter", type=str, default=None, help="PEFT adapter directory to merge before export.")
+    p.add_argument(
+        "--no-integrity-update",
+        action="store_true",
+        help="Skip updating model_integrity.json with the exported artifact.",
+    )
+    _add_common_subparser_flags(p, include_output_format=True)
+
+
+def _add_deploy_subcommand(subparsers) -> None:
+    p = subparsers.add_parser(
+        "deploy",
+        help="Generate a deployment configuration for a serving runtime.",
+        description=(
+            "Produce a ready-to-use config file for Ollama, vLLM, TGI, or "
+            "HuggingFace Inference Endpoints.  Does not start a server."
+        ),
+    )
+    p.add_argument("model_path", help="Path to a saved HuggingFace model directory or HF Hub ID.")
+    p.add_argument(
+        "--target",
+        type=str,
+        required=True,
+        choices=["ollama", "vllm", "tgi", "hf-endpoints"],
+        help="Target serving runtime.",
+    )
+    p.add_argument("--output", type=str, default=None, metavar="FILE", help="Output file path (default: auto).")
+    p.add_argument("--system", type=str, default=None, metavar="PROMPT", help="System prompt (Ollama only).")
+    p.add_argument("--max-length", type=int, default=4096, help="Context window length (default: 4096).")
+    p.add_argument(
+        "--gpu-memory-utilization",
+        type=float,
+        default=0.90,
+        help="vLLM GPU memory utilisation fraction (default: 0.90).",
+    )
+    p.add_argument("--port", type=int, default=8080, help="Host port for TGI container (default: 8080).")
+    p.add_argument("--trust-remote-code", action="store_true", help="Set trust_remote_code in vLLM config.")
+    p.add_argument(
+        "--vendor",
+        type=str,
+        default="aws",
+        help="Cloud vendor for HF Endpoints config (default: aws).",
+    )
+    _add_common_subparser_flags(p, include_output_format=True)
+
+
 def parse_args():
-    parser = argparse.ArgumentParser(description="ForgeLM: Language Model Fine-Tuning Toolkit")
+    parser = argparse.ArgumentParser(
+        description="ForgeLM: Language Model Fine-Tuning Toolkit",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Subcommands:\n"
+            "  forgelm chat MODEL_PATH    Interactive chat REPL\n"
+            "  forgelm export MODEL_PATH  Export model to GGUF\n"
+            "  forgelm deploy MODEL_PATH  Generate serving config\n"
+            "\nRun 'forgelm <subcommand> --help' for subcommand details."
+        ),
+    )
+
+    # --- Subcommand router (dest=command; None when not given → training mode) ---
+    subparsers = parser.add_subparsers(dest="command", metavar="COMMAND")
+    _add_chat_subcommand(subparsers)
+    _add_export_subcommand(subparsers)
+    _add_deploy_subcommand(subparsers)
+
+    # --- Top-level flags (training / config-driven mode) ---
     parser.add_argument("--config", type=str, help="Path to the YAML configuration file.")
     parser.add_argument(
         "--wizard", action="store_true", help="Launch interactive configuration wizard to generate a config.yaml."
@@ -54,6 +198,14 @@ def parse_args():
     parser.add_argument(
         "--dry-run", action="store_true", help="Validate configuration and check model/dataset access without training."
     )
+    parser.add_argument(
+        "--fit-check",
+        action="store_true",
+        help=(
+            "Estimate peak training VRAM from the config without loading the model.  "
+            "Requires --config.  Prints a FITS / TIGHT / OOM verdict with a breakdown."
+        ),
+    )
     parser.add_argument(
         "--resume",
         type=str,
@@ -112,8 +264,36 @@ def parse_args():
     return parser.parse_args()
 
 
-def _run_dry_run(config: ForgeConfig, output_format: str) -> None:
-    """Validate config, model access, and dataset access without loading heavy dependencies."""
+def _galore_dry_run_fields(config: ForgeConfig) -> dict:
+    if not config.training.galore_enabled:
+        return {"galore_enabled": False, "galore_optim": None, "galore_rank": None}
+    return {
+        "galore_enabled": True,
+        "galore_optim": config.training.galore_optim,
+        "galore_rank": config.training.galore_rank,
+    }
+
+
+def _evaluation_dry_run_fields(config: ForgeConfig) -> dict:
+    eval_cfg = config.evaluation
+    safety = eval_cfg.safety if eval_cfg else None
+    return {
+        "auto_revert": bool(eval_cfg and eval_cfg.auto_revert),
+        "safety_enabled": bool(safety and safety.enabled),
+        "safety_scoring": safety.scoring if safety else None,
+    }
+
+
+def _compliance_dry_run_fields(config: ForgeConfig) -> dict:
+    comp = config.compliance
+    return {
+        "compliance_configured": bool(comp and comp.provider_name),
+        "risk_classification": comp.risk_classification if comp else None,
+    }
+
+
+def _build_dry_run_result(config: ForgeConfig) -> dict:
+    """Assemble the dry-run summary dict from the validated config."""
     result = {
         "status": "valid",
         "model": config.model.name_or_path,
@@ -131,18 +311,17 @@ def _run_dry_run(config: ForgeConfig, output_format: str) -> None:
         "distributed": config.distributed.strategy if config.distributed else None,
         "rope_scaling": config.training.rope_scaling,
         "neftune_noise_alpha": config.training.neftune_noise_alpha,
-        "galore_enabled": config.training.galore_enabled,
-        "galore_optim": config.training.galore_optim if config.training.galore_enabled else None,
-        "galore_rank": config.training.galore_rank if config.training.galore_enabled else None,
-        "auto_revert": bool(config.evaluation and config.evaluation.auto_revert),
-        "safety_enabled": bool(config.evaluation and config.evaluation.safety and config.evaluation.safety.enabled),
-        "safety_scoring": config.evaluation.safety.scoring
-        if (config.evaluation and config.evaluation.safety)
-        else None,
-        "compliance_configured": bool(config.compliance and config.compliance.provider_name),
-        "risk_classification": config.compliance.risk_classification if config.compliance else None,
         "webhook_configured": bool(config.webhook and (config.webhook.url or config.webhook.url_env)),
     }
+    result.update(_galore_dry_run_fields(config))
+    result.update(_evaluation_dry_run_fields(config))
+    result.update(_compliance_dry_run_fields(config))
+    return result
+
+
+def _run_dry_run(config: ForgeConfig, output_format: str) -> None:
+    """Validate config, model access, and dataset access without loading heavy dependencies."""
+    result = _build_dry_run_result(config)
 
     if output_format == "json":
         print(json.dumps(result, indent=2))
@@ -151,9 +330,8 @@ def _run_dry_run(config: ForgeConfig, output_format: str) -> None:
     logger.info("=== DRY RUN MODE ===")
     logger.info("Configuration validated successfully.")
     for key, value in result.items():
-        if key == "status":
-            continue
-        logger.info("  %s: %s", key, value)
+        if key != "status":
+            logger.info("  %s: %s", key, value)
 
     if config.model.trust_remote_code:
         logger.warning("trust_remote_code is ENABLED — review model source before production use.")
@@ -309,7 +487,7 @@ def _run_compliance_export(config: ForgeConfig, output_dir: str, output_format:
 
     logger.info("Generating compliance artifacts to %s...", output_dir)
     manifest = generate_training_manifest(config=config, metrics={})
-    files = export_compliance_artifacts(manifest, config, output_dir)
+    files = export_compliance_artifacts(manifest, output_dir)
 
     if output_format == "json":
         print(json.dumps({"success": True, "files": files, "output_dir": output_dir}, indent=2))
@@ -407,54 +585,189 @@ def _output_result(result, output_format: str) -> None:
                 logger.info("  Average: %.4f", result.benchmark_average)
 
 
-def main():
-    args = parse_args()
+def _run_fit_check(config: ForgeConfig, output_format: str) -> None:
+    """Estimate peak training VRAM from config without loading the model."""
+    from .fit_check import estimate_vram, format_fit_check
+
+    result = estimate_vram(config)
+
+    if output_format == "json":
+        print(
+            json.dumps(
+                {
+                    "verdict": result.verdict,
+                    "estimated_gb": result.estimated_gb,
+                    "available_gb": result.available_gb,
+                    "hypothetical": result.hypothetical,
+                    "breakdown": result.breakdown,
+                    "recommendations": result.recommendations,
+                },
+                indent=2,
+            )
+        )
+        return
+
+    print(format_fit_check(result))
 
-    # --wizard mode: generate config interactively
-    if args.wizard:
-        from .wizard import run_wizard
 
-        config_path = run_wizard()
-        if config_path:
-            # User chose to start training immediately — update args
-            args.config = config_path
+def _run_chat_cmd(args) -> None:
+    """Dispatch the ``forgelm chat`` subcommand."""
+    try:
+        from .chat import run_chat
+
+        run_chat(
+            model_path=args.model_path,
+            adapter=args.adapter,
+            system_prompt=args.system,
+            temperature=args.temperature,
+            max_new_tokens=args.max_new_tokens,
+            stream=not args.no_stream,
+            load_in_4bit=args.load_in_4bit,
+            load_in_8bit=args.load_in_8bit,
+            trust_remote_code=args.trust_remote_code,
+            backend=args.backend,
+        )
+    except ImportError as e:
+        logger.error("Missing dependency for chat: %s", e)
+        sys.exit(EXIT_TRAINING_ERROR)
+    except Exception as e:
+        logger.exception("Chat session failed: %s", e)
+        sys.exit(EXIT_TRAINING_ERROR)
+
+
+def _run_export_cmd(args, output_format: str) -> None:
+    """Dispatch the ``forgelm export`` subcommand."""
+    from .export import export_model
+
+    result = export_model(
+        model_path=args.model_path,
+        output_path=args.output,
+        output_format=args.format,
+        quant=args.quant,
+        adapter=args.adapter,
+        update_integrity=not args.no_integrity_update,
+    )
+
+    if output_format == "json":
+        print(
+            json.dumps(
+                {
+                    "success": result.success,
+                    "output_path": result.output_path,
+                    "format": result.format,
+                    "quant": result.quant,
+                    "sha256": result.sha256,
+                    "size_bytes": result.size_bytes,
+                    "error": result.error,
+                },
+                indent=2,
+            )
+        )
+    else:
+        if result.success:
+            logger.info(
+                "Export complete: %s (quant=%s, sha256=%s…)",
+                result.output_path,
+                result.quant,
+                (result.sha256 or "")[:12],
+            )
         else:
-            sys.exit(EXIT_SUCCESS)
+            logger.error("Export failed: %s", result.error)
 
-    # --config is required except for --version and --wizard (handled above)
-    if not args.config:
-        print("Error: --config is required. Use --help for usage.", file=sys.stderr)
-        sys.exit(EXIT_CONFIG_ERROR)
+    if not result.success:
+        sys.exit(EXIT_TRAINING_ERROR)
 
-    json_output = args.output_format == "json"
-    log_level = "WARNING" if args.quiet else args.log_level
-    _setup_logging(log_level, json_format=json_output)
 
-    # 1. Load and validate configuration
+def _run_deploy_cmd(args, output_format: str) -> None:
+    """Dispatch the ``forgelm deploy`` subcommand."""
+    from .deploy import HFEndpointsOptions, generate_deploy_config
+
+    result = generate_deploy_config(
+        model_path=args.model_path,
+        target=args.target,
+        output_path=args.output,
+        system_prompt=args.system,
+        max_length=args.max_length,
+        trust_remote_code=args.trust_remote_code,
+        gpu_memory_utilization=args.gpu_memory_utilization,
+        port=args.port,
+        hf_endpoints=HFEndpointsOptions(vendor=getattr(args, "vendor", "aws")),
+    )
+
+    if output_format == "json":
+        print(
+            json.dumps(
+                {
+                    "success": result.success,
+                    "target": result.target,
+                    "output_path": result.output_path,
+                    "error": result.error,
+                },
+                indent=2,
+            )
+        )
+    else:
+        if result.success:
+            logger.info("Deploy config written: %s (target=%s)", result.output_path, result.target)
+        else:
+            logger.error("Deploy config generation failed: %s", result.error)
+
+    if not result.success:
+        sys.exit(EXIT_TRAINING_ERROR)
+
+
+def _dispatch_subcommand(command: str, args) -> None:
+    """Run a Phase 10 subcommand (chat / export / deploy) and exit."""
+    if command == "chat":
+        # _run_chat_cmd's REPL catches KeyboardInterrupt internally for the
+        # input prompt; this outer guard covers Ctrl-C during model load /
+        # welcome banner render, before the REPL loop has started.
+        try:
+            _run_chat_cmd(args)
+        except KeyboardInterrupt:
+            pass
+        sys.exit(EXIT_SUCCESS)
+    elif command == "export":
+        _run_export_cmd(args, getattr(args, "output_format", "text"))
+        sys.exit(EXIT_SUCCESS)
+    elif command == "deploy":
+        _run_deploy_cmd(args, getattr(args, "output_format", "text"))
+        sys.exit(EXIT_SUCCESS)
+
+
+def _maybe_run_wizard(args) -> None:
+    """Open the interactive wizard when --wizard was passed; mutates *args*."""
+    if not args.wizard:
+        return
+    from .wizard import run_wizard
+
+    config_path = run_wizard()
+    if config_path:
+        args.config = config_path
+    else:
+        sys.exit(EXIT_SUCCESS)
+
+
+def _load_config_or_exit(config_path: str, json_output: bool):
+    """Load config and translate exceptions into the right exit code."""
     try:
-        logger.info("Loading configuration from %s...", args.config)
-        config = load_config(args.config)
+        logger.info("Loading configuration from %s...", config_path)
+        return load_config(config_path)
     except FileNotFoundError as e:
-        if json_output:
-            print(json.dumps({"success": False, "error": f"Config file not found: {e}"}))
-        else:
-            logger.error("Configuration file not found: %s", e)
-        sys.exit(EXIT_CONFIG_ERROR)
+        msg = f"Config file not found: {e}"
     except ConfigError as e:
-        if json_output:
-            print(json.dumps({"success": False, "error": str(e)}))
-        else:
-            logger.error("Configuration error: %s", e)
-        sys.exit(EXIT_CONFIG_ERROR)
+        msg = str(e)
     except Exception as e:
-        if json_output:
-            print(json.dumps({"success": False, "error": f"Unexpected error: {e}"}))
-        else:
-            logger.error("Unexpected error loading configuration: %s", e)
-        sys.exit(EXIT_CONFIG_ERROR)
+        msg = f"Unexpected error: {e}"
+    if json_output:
+        print(json.dumps({"success": False, "error": msg}))
+    else:
+        logger.error("Configuration error: %s", msg)
+    sys.exit(EXIT_CONFIG_ERROR)
+
 
-    # 2. Apply --offline flag
-    if args.offline:
+def _apply_offline_flag(config, offline_arg: bool) -> None:
+    if offline_arg:
         config.model.offline = True
     if config.model.offline:
         os.environ["HF_HUB_OFFLINE"] = "1"
@@ -462,31 +775,49 @@ def main():
         os.environ["HF_DATASETS_OFFLINE"] = "1"
         logger.info("Offline mode enabled. All HF Hub network calls are disabled.")
 
-    # 3. Dry-run mode: validate and exit
+
+def _maybe_run_no_train_mode(config, args) -> None:
+    """If a non-training mode flag is set, run it and exit."""
     if args.dry_run:
         _run_dry_run(config, args.output_format)
         sys.exit(EXIT_SUCCESS)
-
-    # 4. Benchmark-only mode: evaluate an existing model without training
+    if args.fit_check:
+        _run_fit_check(config, args.output_format)
+        sys.exit(EXIT_SUCCESS)
     if args.benchmark_only:
         _run_benchmark_only(config, args.benchmark_only, args.output_format)
         sys.exit(EXIT_SUCCESS)
-
-    # 5. Merge mode: merge models from config without training
     if args.merge:
         _run_merge(config, args.output_format)
         sys.exit(EXIT_SUCCESS)
-
-    # 6. Synthetic data generation mode
     if args.generate_data:
         _run_generate_data(config, args.output_format)
         sys.exit(EXIT_SUCCESS)
-
-    # 7. Compliance export mode: generate audit artifacts from config
     if args.compliance_export:
         _run_compliance_export(config, args.compliance_export, args.output_format)
         sys.exit(EXIT_SUCCESS)
 
+
+def _report_training_error(
+    json_output: bool, payload: dict, log_msg: str, exit_code: int, *, with_traceback: bool = False
+) -> None:
+    """Emit a training-pipeline error and exit with *exit_code*.
+
+    Centralizes the "JSON to stdout vs human log message" split. Pass
+    ``with_traceback=True`` for unexpected exceptions where the stack trace
+    is more useful than a one-line message.
+    """
+    if json_output:
+        print(json.dumps(payload))
+    elif with_traceback:
+        logger.exception(log_msg)
+    else:
+        logger.error(log_msg)
+    sys.exit(exit_code)
+
+
+def _run_training_pipeline(config, args, json_output: bool) -> None:
+    """Run the full training pipeline (model load → data → trainer.train → cleanup)."""
     try:
         # Defer heavy imports so `--help`, `--version`, and `--dry-run` stay lightweight.
         from .data import prepare_dataset
@@ -494,50 +825,71 @@ def main():
         from .trainer import ForgeTrainer
         from .utils import manage_checkpoints, setup_authentication
 
-        # 7. Setup HF Authentication (skipped in offline mode)
         if not config.model.offline:
             setup_authentication(config.auth.hf_token if config.auth else None)
         else:
             logger.info("Skipping HF authentication (offline mode).")
 
-        # 8. Model & Tokenizer
         model, tokenizer = get_model_and_tokenizer(config)
-
-        # 9. Data Preprocessing
         dataset = prepare_dataset(config, tokenizer)
 
-        # 10. Resolve checkpoint resume
         resume_checkpoint = None
         if args.resume:
             resume_checkpoint = _resolve_resume_checkpoint(config.training.output_dir, args.resume)
 
-        # 11. Training
         trainer = ForgeTrainer(model=model, tokenizer=tokenizer, config=config, dataset=dataset)
         result = trainer.train(resume_from_checkpoint=resume_checkpoint)
 
-        # 12. Checkpoint cleanup/compression
         logger.info("Cleaning up intermediate checkpoints...")
         manage_checkpoints(config.training.output_dir, action="keep")
 
-        # 13. Output result
         _output_result(result, args.output_format)
-        # Human approval gate: exit code 4 if awaiting approval
         if result.success and config.evaluation and getattr(config.evaluation, "require_human_approval", False):
             sys.exit(EXIT_AWAITING_APPROVAL)
         sys.exit(EXIT_SUCCESS if result.success else EXIT_EVAL_FAILURE)
 
     except ImportError as e:
-        if json_output:
-            print(json.dumps({"success": False, "error": f"Missing dependency: {e}"}))
-        else:
-            logger.error("Missing dependency: %s. Check your installation.", e)
-        sys.exit(EXIT_TRAINING_ERROR)
+        _report_training_error(
+            json_output,
+            payload={"success": False, "error": f"Missing dependency: {e}"},
+            log_msg=f"Missing dependency: {e}. Check your installation.",
+            exit_code=EXIT_TRAINING_ERROR,
+        )
     except Exception as e:
-        if json_output:
-            print(json.dumps({"success": False, "error": str(e)}))
-        else:
-            logger.exception("Training pipeline failed.")
-        sys.exit(EXIT_TRAINING_ERROR)
+        _report_training_error(
+            json_output,
+            payload={"success": False, "error": str(e)},
+            log_msg="Training pipeline failed.",
+            exit_code=EXIT_TRAINING_ERROR,
+            with_traceback=True,
+        )
+
+
+def main():
+    args = parse_args()
+
+    # Phase 10 subcommand dispatch — no --config required.
+    command = getattr(args, "command", None)
+    if command is not None:
+        json_output = getattr(args, "output_format", "text") == "json"
+        log_level = "WARNING" if getattr(args, "quiet", False) else getattr(args, "log_level", "INFO")
+        _setup_logging(log_level, json_format=json_output)
+        _dispatch_subcommand(command, args)
+
+    _maybe_run_wizard(args)
+
+    if not args.config:
+        print("Error: --config is required. Use --help for usage.", file=sys.stderr)
+        sys.exit(EXIT_CONFIG_ERROR)
+
+    json_output = args.output_format == "json"
+    log_level = "WARNING" if args.quiet else args.log_level
+    _setup_logging(log_level, json_format=json_output)
+
+    config = _load_config_or_exit(args.config, json_output)
+    _apply_offline_flag(config, args.offline)
+    _maybe_run_no_train_mode(config, args)
+    _run_training_pipeline(config, args, json_output)
 
 
 if __name__ == "__main__":
diff --git a/forgelm/compliance.py b/forgelm/compliance.py
index 91220e1b..198c0306 100644
--- a/forgelm/compliance.py
+++ b/forgelm/compliance.py
@@ -324,8 +324,12 @@ def generate_training_manifest(
 # ---------------------------------------------------------------------------
 
 
-def _sanitize_md(text: str) -> str:
-    """Escape user-controlled text before embedding in Markdown to prevent injection."""
+def _sanitize_md(text: Optional[str]) -> str:
+    """Escape user-controlled text before embedding in Markdown to prevent injection.
+
+    Accepts ``None`` (treated as "Not specified") so callers can pass through
+    optional config fields without a per-site None-check.
+    """
     if not text:
         return "Not specified"
     text = text.replace("\n", " ").replace("\r", " ")
@@ -420,10 +424,14 @@ def generate_deployer_instructions(config: Any, metrics: Dict[str, float], final
 
 def export_compliance_artifacts(
     manifest: Dict[str, Any],
-    config: Any,
     output_dir: str,
 ) -> List[str]:
-    """Export all compliance artifacts to a directory."""
+    """Export all compliance artifacts to a directory.
+
+    The *manifest* (produced by :func:`generate_training_manifest`) already
+    contains all the config-derived data needed for the artifacts, so the
+    config object itself is not required here.
+    """
     import yaml
 
     os.makedirs(output_dir, exist_ok=True)
diff --git a/forgelm/config.py b/forgelm/config.py
index 12c1e1a2..53f92988 100644
--- a/forgelm/config.py
+++ b/forgelm/config.py
@@ -159,7 +159,7 @@ class DistributedConfig(BaseModel):
 
     model_config = ConfigDict(extra="forbid")
 
-    strategy: Optional[str] = None  # "deepspeed" or "fsdp"; None = single-GPU
+    strategy: Optional[str] = None  # values: deepspeed, fsdp, or None for single-GPU
     # --- DeepSpeed ---
     deepspeed_config: Optional[str] = None  # path to DS JSON or preset name: "zero2", "zero3", "zero3_offload"
     # --- FSDP ---
@@ -383,9 +383,8 @@ class ForgeConfig(BaseModel):
     monitoring: Optional[MonitoringConfig] = None
     synthetic: Optional[SyntheticConfig] = None
 
-    @model_validator(mode="after")
-    def _validate_consistency(self):
-        # Warn about potential config issues
+    def _warn_general_consistency(self) -> None:
+        """Emit warnings for the broad cross-field config inconsistencies."""
         if self.evaluation and self.evaluation.auto_revert and self.training.merge_adapters:
             logger.warning(
                 "auto_revert=True with merge_adapters=True: if evaluation fails, "
@@ -421,83 +420,95 @@ def _validate_consistency(self):
                 self.training.eval_steps,
                 self.training.save_steps,
             )
-        # High-risk compliance enforcement
+
+    def _warn_high_risk_compliance(self) -> None:
+        """EU AI Act high-risk compliance recommendations."""
         is_high_risk = (self.risk_assessment and self.risk_assessment.risk_category == "high-risk") or (
             self.compliance and self.compliance.risk_classification == "high-risk"
         )
-        if is_high_risk:
-            if not self.evaluation or not self.evaluation.auto_revert:
-                logger.warning(
-                    "High-risk AI classification requires evaluation.auto_revert: true "
-                    "for EU AI Act compliance. Safety gates should be enabled."
-                )
-            if not self.evaluation or not self.evaluation.safety or not self.evaluation.safety.enabled:
-                logger.warning(
-                    "High-risk AI classification: safety evaluation is strongly recommended. "
-                    "Set evaluation.safety.enabled: true."
-                )
-            if (
-                self.evaluation
-                and self.evaluation.safety
-                and self.evaluation.safety.enabled
-                and not self.evaluation.safety.track_categories
-            ):
-                logger.warning(
-                    "High-risk AI: harm category tracking (track_categories: true) is recommended "
-                    "for detailed EU AI Act compliance documentation."
-                )
-        # Trainer type validation
+        if not is_high_risk:
+            return
+        if not self.evaluation or not self.evaluation.auto_revert:
+            logger.warning(
+                "High-risk AI classification requires evaluation.auto_revert: true "
+                "for EU AI Act compliance. Safety gates should be enabled."
+            )
+        safety = self.evaluation.safety if self.evaluation else None
+        if not safety or not safety.enabled:
+            logger.warning(
+                "High-risk AI classification: safety evaluation is strongly recommended. "
+                "Set evaluation.safety.enabled: true."
+            )
+        elif not safety.track_categories:
+            logger.warning(
+                "High-risk AI: harm category tracking (track_categories: true) is recommended "
+                "for detailed EU AI Act compliance documentation."
+            )
+
+    def _validate_trainer_type(self) -> None:
         valid_trainers = {"sft", "orpo", "dpo", "simpo", "kto", "grpo"}
         if self.training.trainer_type not in valid_trainers:
             raise ValueError(
                 f"Invalid trainer_type: '{self.training.trainer_type}'. "
                 f"Must be one of: {', '.join(sorted(valid_trainers))}"
             )
-        # GaLore validations
-        if self.training.galore_enabled:
-            valid_galore_optims = {
-                "galore_adamw",
-                "galore_adamw_8bit",
-                "galore_adafactor",
-                "galore_adamw_layerwise",
-                "galore_adamw_8bit_layerwise",
-                "galore_adafactor_layerwise",
-            }
-            if self.training.galore_optim not in valid_galore_optims:
-                raise ValueError(
-                    f"Invalid galore_optim: '{self.training.galore_optim}'. "
-                    f"Must be one of: {', '.join(sorted(valid_galore_optims))}"
-                )
-            if self.lora and self.lora.r > 0:
-                logger.info(
-                    "GaLore (gradient rank=%d) enabled alongside LoRA (adapter rank=%d). "
-                    "GaLore reduces gradient memory via low-rank projection; "
-                    "LoRA constrains trainable parameters. Both are active simultaneously.",
-                    self.training.galore_rank,
-                    self.lora.r,
-                )
-            if "layerwise" in self.training.galore_optim and self.distributed and self.distributed.strategy:
-                raise ValueError(
-                    "GaLore layerwise optimizers do not support multi-GPU (DDP). "
-                    "Use a non-layerwise variant (e.g., galore_adamw) or disable distributed training."
-                )
-        # Distributed training validations
-        if self.distributed and self.distributed.strategy:
-            if self.model.backend == "unsloth":
-                raise ValueError(
-                    "Unsloth backend does not support multi-GPU distributed training. "
-                    "Set backend: 'transformers' for DeepSpeed/FSDP."
-                )
-            if (
-                self.distributed.strategy == "deepspeed"
-                and self.distributed.deepspeed_config
-                and "zero3" in str(self.distributed.deepspeed_config)
-                and self.model.load_in_4bit
-            ):
-                logger.warning(
-                    "QLoRA (4-bit) with DeepSpeed ZeRO-3 has known compatibility issues. "
-                    "Consider using ZeRO-2 or disabling 4-bit quantization for stability."
-                )
+
+    def _validate_galore(self) -> None:
+        if not self.training.galore_enabled:
+            return
+        valid_galore_optims = {
+            "galore_adamw",
+            "galore_adamw_8bit",
+            "galore_adafactor",
+            "galore_adamw_layerwise",
+            "galore_adamw_8bit_layerwise",
+            "galore_adafactor_layerwise",
+        }
+        if self.training.galore_optim not in valid_galore_optims:
+            raise ValueError(
+                f"Invalid galore_optim: '{self.training.galore_optim}'. "
+                f"Must be one of: {', '.join(sorted(valid_galore_optims))}"
+            )
+        if self.lora.r > 0:
+            logger.info(
+                "GaLore (gradient rank=%d) enabled alongside LoRA (adapter rank=%d). "
+                "GaLore reduces gradient memory via low-rank projection; "
+                "LoRA constrains trainable parameters. Both are active simultaneously.",
+                self.training.galore_rank,
+                self.lora.r,
+            )
+        if "layerwise" in self.training.galore_optim and self.distributed and self.distributed.strategy:
+            raise ValueError(
+                "GaLore layerwise optimizers do not support multi-GPU (DDP). "
+                "Use a non-layerwise variant (e.g., galore_adamw) or disable distributed training."
+            )
+
+    def _validate_distributed(self) -> None:
+        if not (self.distributed and self.distributed.strategy):
+            return
+        if self.model.backend == "unsloth":
+            raise ValueError(
+                "Unsloth backend does not support multi-GPU distributed training. "
+                "Set backend: 'transformers' for DeepSpeed/FSDP."
+            )
+        if (
+            self.distributed.strategy == "deepspeed"
+            and self.distributed.deepspeed_config
+            and "zero3" in str(self.distributed.deepspeed_config)
+            and self.model.load_in_4bit
+        ):
+            logger.warning(
+                "QLoRA (4-bit) with DeepSpeed ZeRO-3 has known compatibility issues. "
+                "Consider using ZeRO-2 or disabling 4-bit quantization for stability."
+            )
+
+    @model_validator(mode="after")
+    def _validate_consistency(self):
+        self._warn_general_consistency()
+        self._warn_high_risk_compliance()
+        self._validate_trainer_type()
+        self._validate_galore()
+        self._validate_distributed()
         return self
 
 
diff --git a/forgelm/data.py b/forgelm/data.py
index 2801dbe3..8d2ebd00 100644
--- a/forgelm/data.py
+++ b/forgelm/data.py
@@ -1,6 +1,6 @@
 import logging
 import os
-from typing import Any, Dict
+from typing import Any, Dict, Optional
 
 from datasets import DatasetDict, concatenate_datasets, load_dataset
 from transformers import PreTrainedTokenizer
@@ -53,6 +53,76 @@ def _load_single_dataset(path: str):
     return load_dataset(path)
 
 
+def _process_text_format(examples: dict, clean_text: bool, add_eos: bool, eos_token: str) -> dict:
+    """Pre-formatted text column (e.g., openassistant-guanaco)."""
+    texts = []
+    for t in examples["text"]:
+        t = clean_string(t, clean_text)
+        if add_eos and t and eos_token and not t.endswith(eos_token):
+            t += eos_token
+        texts.append(t)
+    return {"text": texts}
+
+
+def _process_messages_format(examples: dict, add_eos: bool, eos_token: str) -> dict:
+    """Modern conversational format (messages column)."""
+    texts = []
+    for msg_list in examples["messages"]:
+        try:
+            # apply_chat_template is not available here (no tokenizer reference);
+            # use fallback formatting — callers that need chat templates should
+            # pass a tokenizer-aware processor instead.
+            formatted_text = "".join(f"[{m['role'].upper()}]\n{m['content']}\n" for m in msg_list)
+            if add_eos and eos_token:
+                formatted_text += eos_token
+        except Exception:
+            formatted_text = ""
+        texts.append(formatted_text)
+    return {"text": texts}
+
+
+def _format_user_assistant_row(
+    sys_text: str, user_text: str, asst_text: str, clean_text: bool, add_eos: bool, eos_token: str
+) -> str:
+    """Render a single (System?, User, Assistant) row into a flat training string."""
+    sys_clean = clean_string(sys_text, clean_text) if sys_text else ""
+    user_clean = clean_string(user_text, clean_text)
+    asst_clean = clean_string(asst_text, clean_text)
+    sys_part = f"[SYSTEM]\n{sys_clean}\n" if sys_text else ""
+    formatted_text = sys_part + f"[USER]\n{user_clean}\n[ASSISTANT]\n{asst_clean}"
+    if add_eos and eos_token:
+        formatted_text += eos_token
+    return formatted_text
+
+
+def _process_user_assistant_format(examples: dict, clean_text: bool, add_eos: bool, eos_token: str) -> dict:
+    """Legacy User/Assistant or instruction/output column layout."""
+    has_system = "System" in examples
+    has_user = "User" in examples or "instruction" in examples
+    has_assistant = "Assistant" in examples or "output" in examples or "response" in examples
+
+    # Distinguish "wrong schema" (raise) from "empty batch" (return empty list).
+    # Truthiness on the column list would conflate the two.
+    if not has_user or not has_assistant:
+        fmt = _detect_dataset_format(list(examples.keys()))
+        raise KeyError(
+            f"Dataset must contain 'User'/'instruction' and 'Assistant'/'output' columns, "
+            f"or a pre-formatted 'text' column. "
+            f"Found: {list(examples.keys())}. "
+            f"Detected format: {fmt['description']}. "
+            f"Suggested trainer: {fmt['suggested_trainer']}"
+        )
+
+    user_texts = examples.get("User", examples.get("instruction", []))
+    asst_texts = examples.get("Assistant", examples.get("output", examples.get("response", [])))
+    sys_texts = examples["System"] if has_system else [""] * len(user_texts)
+    texts = [
+        _format_user_assistant_row(s, u, a, clean_text, add_eos, eos_token)
+        for s, u, a in zip(sys_texts, user_texts, asst_texts)
+    ]
+    return {"text": texts}
+
+
 def _make_batch_processor(clean_text: bool, add_eos: bool, eos_token: str):
     """
     Returns a multiprocessing-safe batch processor.
@@ -60,254 +130,221 @@ def _make_batch_processor(clean_text: bool, add_eos: bool, eos_token: str):
     """
 
     def process_batch(examples):
-        # Handle pre-formatted text column (e.g., openassistant-guanaco)
         if "text" in examples and "User" not in examples and "messages" not in examples:
-            texts = []
-            for t in examples["text"]:
-                t = clean_string(t, clean_text)
-                if add_eos and t and eos_token and not t.endswith(eos_token):
-                    t += eos_token
-                texts.append(t)
-            return {"text": texts}
-
-        # Handle modern conversational format (messages column)
+            return _process_text_format(examples, clean_text, add_eos, eos_token)
         if "messages" in examples:
-            texts = []
-            for msg_list in examples["messages"]:
-                try:
-                    # apply_chat_template is not available here (no tokenizer reference);
-                    # use fallback formatting — callers that need chat templates should
-                    # pass a tokenizer-aware processor instead.
-                    formatted_text = ""
-                    for m in msg_list:
-                        formatted_text += f"[{m['role'].upper()}]\n{m['content']}\n"
-                    if add_eos and eos_token:
-                        formatted_text += eos_token
-                except Exception:
-                    formatted_text = ""
-                texts.append(formatted_text)
-            return {"text": texts}
-
-        has_system = "System" in examples
-        sys_texts = (
-            examples["System"] if has_system else [""] * len(examples.get("User", examples.get("instruction", [])))
-        )
-        user_texts = examples.get("User", examples.get("instruction", []))
-        asst_texts = examples.get("Assistant", examples.get("output", examples.get("response", [])))
-
-        if not user_texts or not asst_texts:
-            _fmt = _detect_dataset_format(list(examples.keys()))
-            raise KeyError(
-                f"Dataset must contain 'User'/'instruction' and 'Assistant'/'output' columns, "
-                f"or a pre-formatted 'text' column. "
-                f"Found: {list(examples.keys())}. "
-                f"Detected format: {_fmt['description']}. "
-                f"Suggested trainer: {_fmt['suggested_trainer']}"
-            )
-
-        texts = []
-        for sys_text, user_text, asst_text in zip(sys_texts, user_texts, asst_texts):
-            messages = []
-            if sys_text:
-                messages.append({"role": "system", "content": clean_string(sys_text, clean_text)})
-            messages.append({"role": "user", "content": clean_string(user_text, clean_text)})
-            messages.append({"role": "assistant", "content": clean_string(asst_text, clean_text)})
-
-            # Fallback formatting (no tokenizer in this primitive closure)
-            sys_part = f"[SYSTEM]\n{messages[0]['content']}\n" if sys_text else ""
-            user_idx = 1 if sys_text else 0
-            formatted_text = (
-                sys_part + f"[USER]\n{messages[user_idx]['content']}\n[ASSISTANT]\n{messages[-1]['content']}"
-            )
-            if add_eos and eos_token:
-                formatted_text += eos_token
-
-            texts.append(formatted_text)
-
-        return {"text": texts}
+            return _process_messages_format(examples, add_eos, eos_token)
+        return _process_user_assistant_format(examples, clean_text, add_eos, eos_token)
 
     return process_batch
 
 
-def prepare_dataset(config: Any, tokenizer: PreTrainedTokenizer) -> Dict[str, Any]:
-    """Loads and tokenizes the dataset based on ForgeConfig."""
-
-    logger.info("Loading dataset from %s...", config.data.dataset_name_or_path)
-    primary_dataset = _load_single_dataset(config.data.dataset_name_or_path)
-    dataset = primary_dataset
-
-    # Multi-dataset support: load and merge extra datasets
-    extra_datasets = getattr(config.data, "extra_datasets", None)
-    if extra_datasets:
-        all_train = [dataset["train"]]
-        mix_ratio = getattr(config.data, "mix_ratio", None)
-
-        for i, extra_path in enumerate(extra_datasets):
-            logger.info("Loading extra dataset [%d]: %s", i + 1, extra_path)
-            extra_ds = _load_single_dataset(extra_path)
-            all_train.append(extra_ds["train"])
-
-        # Apply mix ratios via sampling
-        if mix_ratio and len(mix_ratio) == len(all_train):
-            total_weight = sum(mix_ratio)
-            if total_weight == 0:
-                logger.warning("mix_ratio weights sum to 0. Using uniform mixing.")
-            else:
-                normalized = [w / total_weight for w in mix_ratio]
-                # Total target = sum of all dataset sizes weighted proportionally
-                max_dataset_size = max(len(ds) for ds in all_train)
-                sampled = []
-                for ds, ratio in zip(all_train, normalized):
-                    n_samples = min(int(max_dataset_size * ratio), len(ds))
-                    sampled.append(ds.shuffle(seed=42).select(range(n_samples)))
-                all_train = sampled
-                logger.info("Applied mix ratios: %s", mix_ratio)
+_PREFERENCE_TRAINERS = {"dpo", "simpo", "orpo"}
+
+
+def _apply_mix_ratio(all_train: list, mix_ratio: list) -> list:
+    """Re-sample the per-dataset training splits according to *mix_ratio* weights."""
+    total_weight = sum(mix_ratio)
+    if total_weight == 0:
+        logger.warning("mix_ratio weights sum to 0. Using uniform mixing.")
+        return all_train
+    normalized = [w / total_weight for w in mix_ratio]
+    max_dataset_size = max(len(ds) for ds in all_train)
+    sampled = []
+    for ds, ratio in zip(all_train, normalized):
+        n_samples = min(int(max_dataset_size * ratio), len(ds))
+        sampled.append(ds.shuffle(seed=42).select(range(n_samples)))
+    logger.info("Applied mix ratios: %s", mix_ratio)
+    return sampled
+
+
+def _merge_extra_datasets(primary_dataset, extra_paths: list, mix_ratio: Optional[list]):
+    """Concatenate primary + extra dataset training splits, optionally weighted."""
+    all_train = [primary_dataset["train"]]
+    for i, extra_path in enumerate(extra_paths):
+        logger.info("Loading extra dataset [%d]: %s", i + 1, extra_path)
+        extra_ds = _load_single_dataset(extra_path)
+        all_train.append(extra_ds["train"])
+
+    if mix_ratio:
+        if len(mix_ratio) == len(all_train):
+            all_train = _apply_mix_ratio(all_train, mix_ratio)
         else:
-            if mix_ratio:
-                logger.warning(
-                    "mix_ratio length (%d) doesn't match dataset count (%d). Using uniform mixing.",
-                    len(mix_ratio),
-                    len(all_train),
-                )
-
-        merged_train = concatenate_datasets(all_train)
-        logger.info("Merged %d datasets into %d training samples.", len(all_train), len(merged_train))
-        dataset = DatasetDict({"train": merged_train})
-        # Validation from primary dataset (already loaded, no re-fetch)
-        if "validation" in primary_dataset:
-            dataset["validation"] = primary_dataset["validation"]
-
-    # Ensure splits exist (train / validation)
-    if "validation" not in dataset and "test" in dataset:
-        dataset["validation"] = dataset["test"]
-    elif "validation" not in dataset:
-        dataset_size = len(dataset["train"])
-        test_size = min(0.1, 2000 / max(dataset_size, 1))
-        test_size = max(test_size, 0.01)
-        logger.info(
-            "No validation split found. Auto-splitting: %.1f%% (%d samples) for validation.",
-            test_size * 100,
-            int(dataset_size * test_size),
-        )
-        split_dataset = dataset["train"].train_test_split(test_size=test_size, seed=42)
-        dataset = DatasetDict({"train": split_dataset["train"], "validation": split_dataset["test"]})
+            logger.warning(
+                "mix_ratio length (%d) doesn't match dataset count (%d). Using uniform mixing.",
+                len(mix_ratio),
+                len(all_train),
+            )
 
-    processor = _make_batch_processor(
-        clean_text=config.data.clean_text,
-        add_eos=config.data.add_eos,
-        eos_token=tokenizer.eos_token or "",
-    )
+    merged_train = concatenate_datasets(all_train)
+    logger.info("Merged %d datasets into %d training samples.", len(all_train), len(merged_train))
+    dataset = DatasetDict({"train": merged_train})
+    if "validation" in primary_dataset:
+        dataset["validation"] = primary_dataset["validation"]
+    return dataset
 
-    # Detect dataset format and trainer type
-    trainer_type = getattr(config.training, "trainer_type", "sft")
-    sample_columns = dataset["train"].column_names if "train" in dataset else []
-    has_chosen_rejected = "chosen" in sample_columns and "rejected" in sample_columns
-    has_kto_format = "completion" in sample_columns and "label" in sample_columns
-    has_prompt_only = "prompt" in sample_columns and not has_chosen_rejected
 
-    # Multimodal VLM datasets: pass through with image column handling
-    mm_cfg = getattr(config.model, "multimodal", None)
-    if mm_cfg and mm_cfg.enabled:
-        image_col = mm_cfg.image_column
-        text_col = mm_cfg.text_column
-        if image_col not in sample_columns:
-            raise KeyError(
-                f"Multimodal mode enabled but image column '{image_col}' not found. "
-                f"Found columns: {', '.join(sample_columns)}. "
-                f"Set model.multimodal.image_column to match your dataset."
-            )
-        logger.info(
-            "Multimodal VLM dataset detected (image='%s', text='%s'). Passing through for VLM processor handling.",
-            image_col,
-            text_col,
-        )
-        processed = {}
-        for split in dataset:
-            current_dataset = dataset[split]
-            if config.data.shuffle:
-                current_dataset = current_dataset.shuffle(seed=42)
-            processed[split] = current_dataset
-        return processed
-
-    # Detect what format the dataset actually is
-    _detected_format = _detect_dataset_format(sample_columns)
-
-    # Preference trainers: DPO, SimPO, ORPO require chosen/rejected
-    preference_trainers = {"dpo", "simpo", "orpo"}
-    if trainer_type in preference_trainers and not has_chosen_rejected:
+def _ensure_validation_split(dataset):
+    """Make sure ``dataset['validation']`` exists, deriving it from train if needed."""
+    if "validation" in dataset:
+        return dataset
+    if "test" in dataset:
+        dataset["validation"] = dataset["test"]
+        return dataset
+    dataset_size = len(dataset["train"])
+    test_size = min(0.1, 2000 / max(dataset_size, 1))
+    test_size = max(test_size, 0.01)
+    logger.info(
+        "No validation split found. Auto-splitting: %.1f%% (%d samples) for validation.",
+        test_size * 100,
+        int(dataset_size * test_size),
+    )
+    split_dataset = dataset["train"].train_test_split(test_size=test_size, seed=42)
+    return DatasetDict({"train": split_dataset["train"], "validation": split_dataset["test"]})
+
+
+def _validate_trainer_columns(
+    trainer_type: str,
+    sample_columns: list,
+    detected_format: dict,
+    has_chosen_rejected: bool,
+    has_kto_format: bool,
+) -> None:
+    """Raise KeyError when the loaded dataset doesn't match the trainer's expected schema."""
+    if trainer_type in _PREFERENCE_TRAINERS and not has_chosen_rejected:
         raise KeyError(
             f"{trainer_type.upper()} trainer requires 'chosen' and 'rejected' columns, "
             f"but found: {', '.join(sample_columns)}.\n\n"
-            f"Your dataset looks like: {_detected_format['description']}\n"
-            f'Suggested: Use trainer_type: "{_detected_format["suggested_trainer"]}" instead, '
+            f"Your dataset looks like: {detected_format['description']}\n"
+            f'Suggested: Use trainer_type: "{detected_format["suggested_trainer"]}" instead, '
             f"or convert your data to preference format (prompt + chosen + rejected)."
         )
-
-    # KTO requires completion/label format
     if trainer_type == "kto" and not has_kto_format:
         raise KeyError(
             f"KTO trainer requires 'completion' and 'label' (boolean) columns, "
             f"but found: {', '.join(sample_columns)}.\n\n"
-            f"Your dataset looks like: {_detected_format['description']}\n"
-            f'Suggested: Use trainer_type: "{_detected_format["suggested_trainer"]}" instead, '
+            f"Your dataset looks like: {detected_format['description']}\n"
+            f'Suggested: Use trainer_type: "{detected_format["suggested_trainer"]}" instead, '
             f"or convert your data to KTO format (prompt + completion + label)."
         )
-
-    # GRPO requires prompt column (generates responses during training)
-    if trainer_type == "grpo" and not has_prompt_only and "prompt" not in sample_columns:
+    if trainer_type == "grpo" and "prompt" not in sample_columns:
         raise KeyError(
             f"GRPO trainer requires a 'prompt' column, "
             f"but found: {', '.join(sample_columns)}.\n\n"
-            f"Your dataset looks like: {_detected_format['description']}\n"
-            f'Suggested: Use trainer_type: "{_detected_format["suggested_trainer"]}" instead, '
+            f"Your dataset looks like: {detected_format['description']}\n"
+            f'Suggested: Use trainer_type: "{detected_format["suggested_trainer"]}" instead, '
             f"or convert your data to prompt-only format."
         )
 
-    # Preference / alignment datasets are passed through with minimal processing
-    # TRL trainers expect specific column formats
-    if trainer_type in preference_trainers and has_chosen_rejected:
-        logger.info("Detected preference dataset (chosen/rejected) for %s training.", trainer_type.upper())
-        processed = {}
-        for split in dataset:
-            current_dataset = dataset[split]
-            if config.data.shuffle:
-                current_dataset = current_dataset.shuffle(seed=42)
-            processed[split] = current_dataset
-        return processed
 
+def _shuffle_and_passthrough(dataset, shuffle: bool) -> Dict[str, Any]:
+    """Return splits as-is — for trainers that need raw columns.
+
+    Only the ``train`` split is shuffled when ``shuffle=True``; validation
+    and test splits are preserved in their original order so evaluation is
+    reproducible across runs and metrics line up sample-by-sample.
+    """
+    out: Dict[str, Any] = {}
+    for split in dataset:
+        current = dataset[split]
+        if shuffle and split == "train":
+            current = current.shuffle(seed=42)
+        out[split] = current
+    return out
+
+
+def _passthrough_for_trainer(trainer_type: str, dataset, shuffle: bool) -> Optional[Dict[str, Any]]:
+    """If trainer takes raw preference/KTO/GRPO columns, return splits as-is; else None."""
+    if trainer_type in _PREFERENCE_TRAINERS:
+        logger.info("Detected preference dataset (chosen/rejected) for %s training.", trainer_type.upper())
+        return _shuffle_and_passthrough(dataset, shuffle)
     if trainer_type == "kto":
         logger.info("Detected KTO dataset (completion/label) for KTO training.")
-        processed = {}
-        for split in dataset:
-            current_dataset = dataset[split]
-            if config.data.shuffle:
-                current_dataset = current_dataset.shuffle(seed=42)
-            processed[split] = current_dataset
-        return processed
-
+        return _shuffle_and_passthrough(dataset, shuffle)
     if trainer_type == "grpo":
         logger.info("Detected prompt dataset for GRPO training.")
-        processed = {}
-        for split in dataset:
-            current_dataset = dataset[split]
-            if config.data.shuffle:
-                current_dataset = current_dataset.shuffle(seed=42)
-            processed[split] = current_dataset
-        return processed
+        return _shuffle_and_passthrough(dataset, shuffle)
+    return None
+
+
+def _passthrough_multimodal(config: Any, dataset, sample_columns: list) -> Optional[Dict[str, Any]]:
+    """Multimodal VLM datasets pass through unchanged so the VLM processor can run."""
+    mm_cfg = getattr(config.model, "multimodal", None)
+    if not (mm_cfg and mm_cfg.enabled):
+        return None
+    image_col = mm_cfg.image_column
+    text_col = mm_cfg.text_column
+    if image_col not in sample_columns:
+        raise KeyError(
+            f"Multimodal mode enabled but image column '{image_col}' not found. "
+            f"Found columns: {', '.join(sample_columns)}. "
+            f"Set model.multimodal.image_column to match your dataset."
+        )
+    logger.info(
+        "Multimodal VLM dataset detected (image='%s', text='%s'). Passing through for VLM processor handling.",
+        image_col,
+        text_col,
+    )
+    return _shuffle_and_passthrough(dataset, config.data.shuffle)
+
 
+def _format_sft_dataset(dataset, processor, shuffle: bool) -> Dict[str, Any]:
+    """Apply the SFT chat-template formatter across all splits.
+
+    Only the ``train`` split is shuffled — keeping validation/test order
+    stable preserves reproducible eval metrics across runs.
+    """
     logger.info("Formatting dataset with Chat Templates...")
-    processed = {}
+    processed: Dict[str, Any] = {}
     for split in dataset:
-        current_dataset = dataset[split]
-        if config.data.shuffle:
-            current_dataset = current_dataset.shuffle(seed=42)
-
-        processed[split] = current_dataset.map(
+        current = dataset[split]
+        if shuffle and split == "train":
+            current = current.shuffle(seed=42)
+        processed[split] = current.map(
             processor,
             batched=True,
-            remove_columns=current_dataset.column_names,
+            remove_columns=current.column_names,
             num_proc=min(os.cpu_count() or 1, 8),
             desc=f"Formatting {split} split",
         )
-
     return processed
+
+
+def prepare_dataset(config: Any, tokenizer: PreTrainedTokenizer) -> Dict[str, Any]:
+    """Loads and tokenizes the dataset based on ForgeConfig."""
+    logger.info("Loading dataset from %s...", config.data.dataset_name_or_path)
+    primary_dataset = _load_single_dataset(config.data.dataset_name_or_path)
+    dataset = primary_dataset
+
+    extra_datasets = getattr(config.data, "extra_datasets", None)
+    if extra_datasets:
+        dataset = _merge_extra_datasets(
+            primary_dataset,
+            extra_datasets,
+            getattr(config.data, "mix_ratio", None),
+        )
+
+    dataset = _ensure_validation_split(dataset)
+
+    sample_columns = dataset["train"].column_names if "train" in dataset else []
+
+    multimodal = _passthrough_multimodal(config, dataset, sample_columns)
+    if multimodal is not None:
+        return multimodal
+
+    trainer_type = getattr(config.training, "trainer_type", "sft")
+    has_chosen_rejected = "chosen" in sample_columns and "rejected" in sample_columns
+    has_kto_format = "completion" in sample_columns and "label" in sample_columns
+    detected_format = _detect_dataset_format(sample_columns)
+    _validate_trainer_columns(trainer_type, sample_columns, detected_format, has_chosen_rejected, has_kto_format)
+
+    raw = _passthrough_for_trainer(trainer_type, dataset, config.data.shuffle)
+    if raw is not None:
+        return raw
+
+    processor = _make_batch_processor(
+        clean_text=config.data.clean_text,
+        add_eos=config.data.add_eos,
+        eos_token=tokenizer.eos_token or "",
+    )
+    return _format_sft_dataset(dataset, processor, config.data.shuffle)
diff --git a/forgelm/deploy.py b/forgelm/deploy.py
new file mode 100644
index 00000000..16e294e3
--- /dev/null
+++ b/forgelm/deploy.py
@@ -0,0 +1,302 @@
+"""
+Deployment configuration generator for post-training handoff.
+
+Generates ready-to-use config files for popular LLM serving runtimes.
+Does NOT start or manage servers; output is consumed by the target tool.
+
+Supported targets:
+  ollama      — Modelfile for ``ollama create``
+  vllm        — engine config YAML for ``python -m vllm.entrypoints.api_server``
+  tgi         — docker-compose.yaml for HuggingFace TGI
+  hf-endpoints — JSON spec for HuggingFace Inference Endpoints API
+
+Usage (programmatic):
+    from forgelm.deploy import generate_deploy_config
+    result = generate_deploy_config("./outputs/my_run", "ollama", "./Modelfile")
+
+Usage (CLI):
+    forgelm deploy ./outputs/my_run --target ollama --output ./Modelfile
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from dataclasses import dataclass
+from typing import Optional
+
+import yaml
+
+logger = logging.getLogger("forgelm.deploy")
+
+SUPPORTED_TARGETS = frozenset({"ollama", "vllm", "tgi", "hf-endpoints"})
+
+# Default filenames per target when --output is not specified
+_DEFAULT_FILENAMES = {
+    "ollama": "Modelfile",
+    "vllm": "vllm_config.yaml",
+    "tgi": "docker-compose.yaml",
+    "hf-endpoints": "hf_endpoint.json",
+}
+
+
+@dataclass
+class DeployResult:
+    """Result of a ``generate_deploy_config`` call."""
+
+    success: bool
+    target: str
+    output_path: Optional[str] = None
+    content: Optional[str] = None  # The generated config text
+    error: Optional[str] = None
+
+
+@dataclass
+class SamplingOptions:
+    """Sampling defaults for runtimes that bake them into the config (Ollama)."""
+
+    temperature: float = 0.7
+    top_k: int = 50
+    top_p: float = 0.9
+
+
+@dataclass
+class HFEndpointsOptions:
+    """All HuggingFace Inference Endpoints knobs that the JSON spec accepts."""
+
+    task: str = "text-generation"
+    instance_size: str = "x2"
+    instance_type: str = "nvidia-a10g"
+    region: str = "us-east-1"
+    framework: str = "pytorch"
+    vendor: str = "aws"
+
+
+# ---------------------------------------------------------------------------
+# Per-target generators
+# ---------------------------------------------------------------------------
+
+
+def _ollama_modelfile(
+    model_path: str,
+    system_prompt: Optional[str],
+    max_length: int,
+    temperature: float,
+    top_k: int,
+    top_p: float,
+) -> str:
+    """Generate an Ollama Modelfile."""
+    lines = [
+        f"FROM {model_path}",
+        "",
+        f"PARAMETER temperature {temperature}",
+        f"PARAMETER top_k {top_k}",
+        f"PARAMETER top_p {top_p}",
+        f"PARAMETER num_ctx {max_length}",
+        "",
+    ]
+    if system_prompt:
+        # Escape any double quotes in the system prompt
+        safe_prompt = system_prompt.replace('"', '\\"')
+        lines.append(f'SYSTEM "{safe_prompt}"')
+        lines.append("")
+
+    lines += [
+        "# Generated by ForgeLM deploy",
+        "# Run: ollama create my-model -f Modelfile",
+        "#      ollama run my-model",
+    ]
+    return "\n".join(lines) + "\n"
+
+
+def _vllm_config(
+    model_path: str,
+    max_length: int,
+    trust_remote_code: bool,
+    gpu_memory_utilization: float,
+    dtype: str,
+) -> str:
+    """Generate a vLLM engine config YAML."""
+    cfg = {
+        "model": model_path,
+        "max_model_len": max_length,
+        "gpu_memory_utilization": gpu_memory_utilization,
+        "trust_remote_code": trust_remote_code,
+        "dtype": dtype,
+        "# Generated by ForgeLM deploy": None,
+        "# Run": "python -m vllm.entrypoints.openai.api_server --config vllm_config.yaml",
+    }
+    # Remove comment pseudo-keys (yaml.dump handles None as null; post-process)
+    comment_keys = [k for k in cfg if k.startswith("#")]
+    comments = "\n".join(k if cfg[k] is None else f"{k}: {cfg[k]}" for k in comment_keys)
+    for k in comment_keys:
+        del cfg[k]
+
+    return yaml.dump(cfg, default_flow_style=False, sort_keys=False) + "\n" + comments + "\n"
+
+
+def _tgi_compose(
+    model_path: str,
+    max_input_length: int,
+    max_total_tokens: int,
+    port: int,
+) -> str:
+    """Generate a docker-compose.yaml for HuggingFace Text Generation Inference."""
+    compose = {
+        "services": {
+            "tgi": {
+                "image": "ghcr.io/huggingface/text-generation-inference:latest",
+                "ports": [f"{port}:80"],
+                "volumes": [f"{os.path.abspath(model_path)}:/data"],
+                "command": (
+                    f"--model-id /data --max-input-length {max_input_length} --max-total-tokens {max_total_tokens}"
+                ),
+                "deploy": {
+                    "resources": {
+                        "reservations": {"devices": [{"driver": "nvidia", "count": 1, "capabilities": ["gpu"]}]}
+                    }
+                },
+            }
+        },
+    }
+    header = (
+        "# Generated by ForgeLM deploy\n# Run: docker compose up\n# Endpoint: http://localhost:{port}/generate\n\n"
+    ).format(port=port)
+    return header + yaml.dump(compose, default_flow_style=False)
+
+
+def _hf_endpoints_json(
+    model_path: str,
+    task: str,
+    instance_size: str,
+    instance_type: str,
+    region: str,
+    framework: str,
+    vendor: str = "aws",
+) -> str:
+    """Generate a HuggingFace Inference Endpoints API spec JSON."""
+    spec = {
+        "model": {
+            "repository": model_path,
+            "framework": framework,
+            "task": task,
+            "image": {"huggingface": {}},
+        },
+        "compute": {
+            "accelerator": "gpu",
+            "instanceSize": instance_size,
+            "instanceType": instance_type,
+            "scaling": {"minReplica": 0, "maxReplica": 1},
+        },
+        "cloud": {"region": region, "vendor": vendor},
+        "_generated_by": "ForgeLM deploy",
+        "_docs": "https://huggingface.co/docs/inference-endpoints/api_reference",
+    }
+    return json.dumps(spec, indent=2) + "\n"
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def generate_deploy_config(
+    model_path: str,
+    target: str,
+    output_path: Optional[str] = None,
+    *,
+    # Shared options
+    system_prompt: Optional[str] = None,
+    max_length: int = 4096,
+    trust_remote_code: bool = False,
+    # Grouped: see SamplingOptions / HFEndpointsOptions for fields
+    sampling: Optional[SamplingOptions] = None,
+    hf_endpoints: Optional[HFEndpointsOptions] = None,
+    # vLLM-specific
+    gpu_memory_utilization: float = 0.90,
+    dtype: str = "bfloat16",
+    # TGI-specific
+    port: int = 8080,
+) -> DeployResult:
+    """Generate a deployment configuration file for the given *target* runtime.
+
+    Args:
+        model_path: Local directory of a fine-tuned / merged model.
+        target: One of ``ollama``, ``vllm``, ``tgi``, ``hf-endpoints``.
+        output_path: File path to write.  Defaults to a target-appropriate
+            filename in the current working directory.
+        system_prompt: Optional system prompt to embed (Ollama Modelfile only).
+        max_length: Context window length.
+        trust_remote_code: Passed to vLLM config.
+        sampling: Sampling defaults bundle (temperature/top_k/top_p) used by
+            Ollama. Defaults to ``SamplingOptions()`` when ``None``.
+        hf_endpoints: HF-Endpoints knobs (task/instance_size/instance_type/
+            region/framework/vendor). Defaults to ``HFEndpointsOptions()``
+            when ``None``.
+        gpu_memory_utilization: vLLM GPU utilisation fraction.
+        dtype: Compute dtype string (vLLM).
+        port: Host port for the TGI container.
+
+    Returns:
+        :class:`DeployResult` with the generated content and output path.
+    """
+    sampling = sampling or SamplingOptions()
+    hf_endpoints = hf_endpoints or HFEndpointsOptions()
+
+    target = target.lower()
+    if target not in SUPPORTED_TARGETS:
+        return DeployResult(
+            success=False,
+            target=target,
+            error=f"Unsupported target '{target}'. Choose from: {', '.join(sorted(SUPPORTED_TARGETS))}",
+        )
+
+    # tgi mounts model_path as a docker volume; ollama Modelfile FROM expects
+    # either a local directory or an Ollama-registry name. An HF Hub ID like
+    # "meta-llama/Llama-3-8B" silently produces a broken config the user only
+    # discovers at `docker compose up` / `ollama create` time.
+    if target in {"tgi", "ollama"} and not os.path.isdir(model_path):
+        return DeployResult(
+            success=False,
+            target=target,
+            error=(
+                f"target='{target}' requires a local model directory but '{model_path}' is not a directory. "
+                "Pass the path to a fine-tuned/merged model on disk (HF Hub IDs are not supported for this target)."
+            ),
+        )
+
+    if output_path is None:
+        output_path = _DEFAULT_FILENAMES[target]
+
+    try:
+        if target == "ollama":
+            content = _ollama_modelfile(
+                model_path, system_prompt, max_length, sampling.temperature, sampling.top_k, sampling.top_p
+            )
+        elif target == "vllm":
+            content = _vllm_config(model_path, max_length, trust_remote_code, gpu_memory_utilization, dtype)
+        elif target == "tgi":
+            max_total = max_length + 512  # generous output budget
+            content = _tgi_compose(model_path, max_length, max_total, port)
+        else:  # hf-endpoints
+            content = _hf_endpoints_json(
+                model_path,
+                hf_endpoints.task,
+                hf_endpoints.instance_size,
+                hf_endpoints.instance_type,
+                hf_endpoints.region,
+                hf_endpoints.framework,
+                hf_endpoints.vendor,
+            )
+
+        os.makedirs(os.path.dirname(os.path.abspath(output_path)), exist_ok=True)
+        with open(output_path, "w", encoding="utf-8") as f:
+            f.write(content)
+
+        logger.info("Deploy config written to %s", output_path)
+        return DeployResult(success=True, target=target, output_path=output_path, content=content)
+
+    except Exception as e:
+        logger.error("Failed to generate deploy config for target '%s': %s", target, e)
+        return DeployResult(success=False, target=target, error=str(e))
diff --git a/forgelm/export.py b/forgelm/export.py
new file mode 100644
index 00000000..4395bbb0
--- /dev/null
+++ b/forgelm/export.py
@@ -0,0 +1,414 @@
+"""
+GGUF export for post-training model distribution.
+
+Wraps llama-cpp-python's ``convert_hf_to_gguf.py`` conversion script to
+produce quantised GGUF files that can be served by Ollama, llama.cpp, and
+compatible runtimes.
+
+Optional dependency: ``pip install forgelm[export]``
+
+Usage (programmatic):
+    from forgelm.export import export_model
+    result = export_model("./outputs/final_model", "./model.gguf", quant="q4_k_m")
+
+Usage (CLI):
+    forgelm export ./outputs/final_model --format gguf --quant q4_k_m --output model.gguf
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+import subprocess  # noqa: S404  # nosec B404 — see _run_converter for the safe-usage rationale
+import sys
+from dataclasses import dataclass
+from typing import List, Optional, Tuple
+
+logger = logging.getLogger("forgelm.export")
+
+SUPPORTED_FORMATS = frozenset({"gguf"})
+SUPPORTED_QUANTS = frozenset({"q2_k", "q3_k_m", "q4_k_m", "q5_k_m", "q8_0", "f16"})
+
+# Name of the HF→GGUF conversion script bundled with llama-cpp-python.
+_CONVERTER_SCRIPT = "convert_hf_to_gguf.py"
+
+# Quant types supported directly by convert_hf_to_gguf.py via --outtype.
+# K-quants (q2_k, q3_k_m, q4_k_m, q5_k_m) require a two-step process:
+# 1. HF → f16 GGUF via convert_hf_to_gguf.py  (done here)
+# 2. f16 → k-quant via `llama-quantize`        (not automated; user must run manually)
+# When a K-quant is requested, we produce f16 and emit a warning.
+_OUTTYPE_MAP = {
+    "f16": "f16",
+    "q8_0": "q8_0",
+    # K-quants: convert_hf_to_gguf.py only supports f16/q8_0 directly; K-quants need llama-quantize
+    "q2_k": "f16",
+    "q3_k_m": "f16",
+    "q4_k_m": "f16",
+    "q5_k_m": "f16",
+}
+
+# K-quants that need a manual second quantization step
+_K_QUANTS = frozenset({"q2_k", "q3_k_m", "q4_k_m", "q5_k_m"})
+
+
+@dataclass
+class ExportResult:
+    """Result of an ``export_model`` call."""
+
+    success: bool
+    output_path: Optional[str] = None
+    format: str = "gguf"
+    quant: Optional[str] = None
+    sha256: Optional[str] = None
+    size_bytes: Optional[int] = None
+    error: Optional[str] = None
+
+
+# ---------------------------------------------------------------------------
+# Converter discovery
+# ---------------------------------------------------------------------------
+
+
+def _find_converter_script() -> str:
+    """Locate llama-cpp-python's HF → GGUF conversion script.
+
+    Checks the ``FORGELM_GGUF_CONVERTER`` environment variable first, allowing
+    users to pin a specific converter script (useful when the bundled version is
+    outdated or when using a standalone llama.cpp build).
+
+    Raises:
+        ImportError: When llama-cpp-python is not installed.
+        FileNotFoundError: When the conversion script cannot be found.
+    """
+    env_override = os.environ.get("FORGELM_GGUF_CONVERTER")
+    if env_override:
+        if os.path.isfile(env_override):
+            logger.debug("Using GGUF converter from FORGELM_GGUF_CONVERTER: %s", env_override)
+            return env_override
+        raise FileNotFoundError(f"FORGELM_GGUF_CONVERTER is set to '{env_override}' but the file does not exist.")
+
+    try:
+        import llama_cpp
+    except ImportError as e:
+        raise ImportError(
+            "llama-cpp-python is required for GGUF export.  Install the export extra: pip install 'forgelm[export]'"
+        ) from e
+
+    pkg_root = os.path.dirname(os.path.abspath(llama_cpp.__file__))
+
+    candidates = [
+        os.path.join(pkg_root, _CONVERTER_SCRIPT),
+        os.path.join(pkg_root, "scripts", _CONVERTER_SCRIPT),
+        # Some versions place it one level up
+        os.path.join(os.path.dirname(pkg_root), _CONVERTER_SCRIPT),
+    ]
+
+    for path in candidates:
+        if os.path.isfile(path):
+            logger.debug("Found converter at %s", path)
+            return path
+
+    raise FileNotFoundError(
+        f"{_CONVERTER_SCRIPT} not found inside the llama-cpp-python installation.  "
+        "Try: pip install 'llama-cpp-python>=0.2.90'  "
+        f"Or set FORGELM_GGUF_CONVERTER=/path/to/{_CONVERTER_SCRIPT} to use a custom script."
+    )
+
+
+# ---------------------------------------------------------------------------
+# Adapter merge helper
+# ---------------------------------------------------------------------------
+
+
+def _merge_adapter(model_path: str, adapter_path: str, merged_dir: str) -> None:
+    """Merge a PEFT LoRA adapter into the base model and save to *merged_dir*.
+
+    Forces ``torch_dtype=float16`` for the merge: GGUF f16 conversion will cast
+    to fp16 anyway, and bf16 math on CPU silently falls back to fp32 (much
+    slower for large models).
+    """
+    import torch
+    from peft import PeftModel
+    from transformers import AutoModelForCausalLM, AutoTokenizer
+
+    logger.info("Merging adapter %s into base model %s ...", adapter_path, model_path)
+    tokenizer = AutoTokenizer.from_pretrained(model_path)
+    model = AutoModelForCausalLM.from_pretrained(model_path, torch_dtype=torch.float16, device_map="cpu")
+    model = PeftModel.from_pretrained(model, adapter_path)
+    model = model.merge_and_unload()
+
+    os.makedirs(merged_dir, exist_ok=True)
+    model.save_pretrained(merged_dir, safe_serialization=True)
+    tokenizer.save_pretrained(merged_dir)
+    logger.info("Merged model saved to %s", merged_dir)
+
+
+# ---------------------------------------------------------------------------
+# SHA-256 helper
+# ---------------------------------------------------------------------------
+
+
+def _sha256_file(path: str) -> str:
+    """Compute the SHA-256 digest of a file."""
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(65536), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+# ---------------------------------------------------------------------------
+# Compliance integration
+# ---------------------------------------------------------------------------
+
+
+def _update_integrity_manifest(model_dir: str, export_result: ExportResult) -> None:
+    """Append the exported artifact to model_integrity.json if it exists."""
+    import json
+
+    integrity_path = os.path.join(model_dir, "model_integrity.json")
+    if not os.path.isfile(integrity_path):
+        return
+
+    try:
+        with open(integrity_path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+
+        artifact = {
+            "file": os.path.basename(export_result.output_path or ""),
+            "format": export_result.format,
+            "quant": export_result.quant,
+            "sha256": export_result.sha256,
+            "size_bytes": export_result.size_bytes,
+        }
+        data.setdefault("exported_artifacts", []).append(artifact)
+
+        with open(integrity_path, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+
+        logger.info("model_integrity.json updated with exported artifact.")
+    except Exception as e:
+        logger.debug("Could not update model_integrity.json: %s", e)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def _validate_export_request(fmt: str, quant: str) -> Optional[ExportResult]:
+    """Reject unsupported format/quant up front; return None when both are valid."""
+    if fmt not in SUPPORTED_FORMATS:
+        return ExportResult(
+            success=False,
+            format=fmt,
+            error=f"Unsupported format '{fmt}'. Supported: {', '.join(sorted(SUPPORTED_FORMATS))}",
+        )
+    if quant not in SUPPORTED_QUANTS:
+        return ExportResult(
+            success=False,
+            quant=quant,
+            error=f"Unsupported quantisation '{quant}'. Supported: {', '.join(sorted(SUPPORTED_QUANTS))}",
+        )
+    return None
+
+
+def _resolve_kquant_path(quant: str, output_path: str) -> Tuple[str, str]:
+    """K-quants need a separate llama-quantize step.
+
+    Returns ``(actual_quant, actual_output_path)``: when *quant* is a K-quant we
+    redirect the converter output to a ``.f16.gguf`` sibling so the integrity
+    manifest never records a SHA-256 against a file that doesn't match the
+    requested quant. Non-K-quants pass through unchanged.
+    """
+    if quant not in _K_QUANTS:
+        return quant, output_path
+    if output_path.endswith(".gguf"):
+        actual_output_path = output_path[: -len(".gguf")] + ".f16.gguf"
+    else:
+        actual_output_path = output_path + ".f16.gguf"
+    logger.warning(
+        "K-quant '%s' is not supported directly by %s. "
+        "Producing an intermediate f16 GGUF at %s instead. "
+        "To get a %s GGUF, run `llama-quantize %s %s %s` afterward.",
+        quant,
+        _CONVERTER_SCRIPT,
+        actual_output_path,
+        quant,
+        actual_output_path,
+        output_path,
+        quant.upper(),
+    )
+    return "f16", actual_output_path
+
+
+def _build_converter_command(
+    converter: str, source_path: str, actual_output_path: str, requested_quant: str, extra_args: Optional[List[str]]
+) -> List[str]:
+    """Compose the argv for the bundled HF→GGUF converter."""
+    cmd: List[str] = [
+        sys.executable,
+        converter,
+        source_path,
+        "--outfile",
+        actual_output_path,
+        "--outtype",
+        _OUTTYPE_MAP[requested_quant],
+    ]
+    if extra_args:
+        cmd.extend(extra_args)
+    return cmd
+
+
+def _run_converter(cmd: List[str], fmt: str, actual_quant: str) -> Optional[ExportResult]:
+    """Run the converter and return an ExportResult on failure (None on success)."""
+    logger.info("Running GGUF conversion: %s", " ".join(cmd))
+    # Bandit B603 / ruff S603: cmd[0] is sys.executable (absolute), cmd[1] comes
+    # from _find_converter_script (resolved against an installed package or an
+    # FORGELM_GGUF_CONVERTER env-var the user supplied), and the remaining
+    # argv entries are paths the caller already controls. No shell=True, no
+    # user-supplied executable. The suppression covers the multi-line call.
+    try:
+        proc = subprocess.run(  # noqa: S603, S607  # nosec B603 B607
+            cmd,  # noqa: S603  # nosec B603
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=3600,
+        )
+    except subprocess.TimeoutExpired:
+        return ExportResult(
+            success=False,
+            format=fmt,
+            quant=actual_quant,
+            error="GGUF conversion timed out after 3600 seconds.",
+        )
+    except Exception as e:
+        return ExportResult(success=False, format=fmt, quant=actual_quant, error=str(e))
+
+    if proc.returncode == 0:
+        return None
+
+    full_stderr = (proc.stderr or "").strip()
+    full_stdout = (proc.stdout or "").strip()
+    if full_stderr:
+        logger.error("GGUF converter stderr:\n%s", full_stderr)
+    if full_stdout:
+        logger.error("GGUF converter stdout:\n%s", full_stdout)
+    logger.error("GGUF conversion failed (exit %d)", proc.returncode)
+    error_detail = full_stderr or full_stdout or "unknown error"
+    return ExportResult(
+        success=False,
+        format=fmt,
+        quant=actual_quant,
+        error=f"Converter exited with code {proc.returncode}: {error_detail[:500]}",
+    )
+
+
+def _cleanup_merged_dir(merged_dir: Optional[str]) -> None:
+    """Remove the temporary adapter-merge directory if one was created."""
+    if not (merged_dir and os.path.isdir(merged_dir)):
+        return
+    import shutil
+
+    shutil.rmtree(merged_dir, ignore_errors=True)
+    logger.debug("Cleaned up temporary merged directory: %s", merged_dir)
+
+
+def export_model(
+    model_path: str,
+    output_path: str,
+    *,
+    output_format: str = "gguf",
+    quant: str = "q4_k_m",
+    adapter: Optional[str] = None,
+    update_integrity: bool = True,
+    extra_args: Optional[List[str]] = None,
+) -> ExportResult:
+    """Export a HuggingFace model to GGUF format.
+
+    If *adapter* is provided the adapter is first merged into the base model
+    (saved to a temporary ``_merged`` sibling directory) before conversion.
+
+    Args:
+        model_path: Path to a saved HuggingFace model directory.
+        output_path: Destination ``.gguf`` file path.
+        output_format: Export format. Only ``"gguf"`` is currently supported.
+            (Renamed from ``format=`` to avoid shadowing the ``format`` builtin.)
+        quant: Quantisation type.  One of
+            ``q2_k, q3_k_m, q4_k_m, q5_k_m, q8_0, f16``.
+        adapter: Optional PEFT adapter directory to merge before export.
+        update_integrity: When ``True``, appends the exported artifact's
+            SHA-256 to ``model_integrity.json`` in the model directory.
+        extra_args: Additional CLI arguments forwarded to the converter script.
+
+    Returns:
+        :class:`ExportResult` with SHA-256, file size, and output path.
+    """
+    fmt = output_format.lower()
+    quant = quant.lower()
+
+    rejection = _validate_export_request(fmt, quant)
+    if rejection is not None:
+        return rejection
+
+    try:
+        converter = _find_converter_script()
+    except (ImportError, FileNotFoundError) as e:
+        return ExportResult(success=False, format=fmt, quant=quant, error=str(e))
+
+    # Merge adapter if requested
+    source_path = model_path
+    merged_dir: Optional[str] = None
+    if adapter:
+        merged_dir = model_path.rstrip("/\\") + "_merged_for_export"
+        try:
+            _merge_adapter(model_path, adapter, merged_dir)
+            source_path = merged_dir
+        except Exception as e:
+            return ExportResult(success=False, format=fmt, quant=quant, error=f"Adapter merge failed: {e}")
+
+    actual_quant, actual_output_path = _resolve_kquant_path(quant, output_path)
+    cmd = _build_converter_command(converter, source_path, actual_output_path, quant, extra_args)
+
+    try:
+        failure = _run_converter(cmd, fmt, actual_quant)
+        if failure is not None:
+            return failure
+    finally:
+        _cleanup_merged_dir(merged_dir)
+
+    if not os.path.isfile(actual_output_path):
+        return ExportResult(
+            success=False,
+            format=fmt,
+            quant=actual_quant,
+            error=f"Conversion appeared to succeed but output file not found: {actual_output_path}",
+        )
+
+    # Compute artifact stats — reflect the file actually written, not the requested quant
+    digest = _sha256_file(actual_output_path)
+    size_bytes = os.path.getsize(actual_output_path)
+
+    result = ExportResult(
+        success=True,
+        output_path=actual_output_path,
+        format=fmt,
+        quant=actual_quant,
+        sha256=digest,
+        size_bytes=size_bytes,
+    )
+
+    logger.info(
+        "GGUF export complete: %s (%.1f GB, quant=%s, sha256=%s…)",
+        actual_output_path,
+        size_bytes / (1024**3),
+        actual_quant,
+        digest[:12],
+    )
+
+    if update_integrity:
+        _update_integrity_manifest(model_path, result)
+
+    return result
diff --git a/forgelm/fit_check.py b/forgelm/fit_check.py
new file mode 100644
index 00000000..8e00f8a7
--- /dev/null
+++ b/forgelm/fit_check.py
@@ -0,0 +1,446 @@
+"""
+VRAM fit advisor for ForgeLM training configurations.
+
+Estimates peak GPU memory consumption *before* loading any model weights,
+using only the model's architecture config and the training hyperparameters.
+Targets ±15 % accuracy against empirically measured values.
+
+Usage (programmatic):
+    from forgelm.fit_check import estimate_vram
+    result = estimate_vram(forge_config)
+    print(result.verdict, result.estimated_gb)
+
+Usage (CLI):
+    forgelm --config my.yaml --fit-check
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Tuple
+
+logger = logging.getLogger("forgelm.fit_check")
+
+# VRAM verdict thresholds (fraction of available memory)
+_TIGHT_THRESHOLD = 0.85
+_OOM_THRESHOLD = 0.95
+
+# Bytes per parameter for each dtype/quant scheme
+_BYTES_PER_PARAM: Dict[str, float] = {
+    "4bit": 0.5,
+    "8bit": 1.0,
+    "bf16": 2.0,
+    "fp16": 2.0,
+    "fp32": 4.0,
+}
+
+# Known model size defaults keyed by name fragment (lowercase) for fallback
+_MODEL_SIZE_HINTS: Dict[str, Tuple[int, int, int]] = {
+    # (hidden_size, num_layers, intermediate_size)
+    "1b": (2048, 16, 8192),
+    "3b": (3072, 28, 8192),
+    "7b": (4096, 32, 11008),
+    "8b": (4096, 32, 14336),
+    "13b": (5120, 40, 13824),
+    "14b": (5120, 40, 13824),
+    "30b": (6656, 60, 17920),
+    "34b": (7168, 48, 20480),
+    "70b": (8192, 80, 28672),
+    "72b": (8192, 80, 29568),
+}
+
+
+@dataclass
+class FitCheckResult:
+    """Result of a VRAM estimation run."""
+
+    verdict: str  # "FITS", "TIGHT", "OOM", or "UNKNOWN" (no GPU detected)
+    estimated_gb: float
+    available_gb: Optional[float]
+    recommendations: List[str] = field(default_factory=list)
+    breakdown: Dict[str, float] = field(default_factory=dict)
+    hypothetical: bool = False  # True when no GPU was detected
+
+
+# ---------------------------------------------------------------------------
+# Architecture parameter extraction
+# ---------------------------------------------------------------------------
+
+
+def _load_arch_params(model_name_or_path: str, trust_remote_code: bool = False) -> Dict[str, Any]:
+    """Fetch architecture parameters from HF config without loading weights.
+
+    Returns a dict with guaranteed keys: hidden_size, num_hidden_layers,
+    intermediate_size, vocab_size, num_attention_heads, num_key_value_heads.
+    Falls back to size-hint heuristics when the config cannot be loaded.
+    """
+    params: Dict[str, Any] = {}
+    try:
+        from transformers import AutoConfig
+
+        cfg = AutoConfig.from_pretrained(model_name_or_path, trust_remote_code=trust_remote_code)
+        params["hidden_size"] = getattr(cfg, "hidden_size", None)
+        params["num_hidden_layers"] = getattr(cfg, "num_hidden_layers", None)
+        params["intermediate_size"] = getattr(cfg, "intermediate_size", None)
+        params["vocab_size"] = getattr(cfg, "vocab_size", None)
+        params["num_attention_heads"] = getattr(cfg, "num_attention_heads", None)
+        params["num_key_value_heads"] = getattr(cfg, "num_key_value_heads", None)
+        logger.debug("Loaded architecture config from %s", model_name_or_path)
+    except Exception as e:
+        logger.debug("Could not load AutoConfig for %s: %s — using size hint fallback.", model_name_or_path, e)
+
+    # Fill in missing values using size-hint lookup on the model name.
+    # Match against word-bounded tokens so "3b" inside "llama-13b" doesn't
+    # spuriously pick up the 3B architecture profile.
+    name_lower = str(model_name_or_path).lower()
+    hint: Optional[Tuple[int, int, int]] = None
+    import re
+
+    for fragment, h in _MODEL_SIZE_HINTS.items():
+        # The lookbehind blocks both digits and "." so fragments like "7b"
+        # don't match inside fractional sizes like "1.7b" (Llama-3.2-1B,
+        # Phi-3.5-mini, etc). The lookahead blocks letters/digits so "7b"
+        # also doesn't match the start of "70b".
+        if re.search(rf"(?<![\d.]){re.escape(fragment)}(?![0-9a-z])", name_lower):
+            hint = h
+            break
+
+    defaults = {
+        "hidden_size": hint[0] if hint else 4096,
+        "num_hidden_layers": hint[1] if hint else 32,
+        "intermediate_size": hint[2] if hint else 11008,
+        "vocab_size": 32000,
+        "num_attention_heads": 32,
+        "num_key_value_heads": 32,
+    }
+    for key, default in defaults.items():
+        if params.get(key) is None:
+            params[key] = default
+
+    # Derived: GQA key-value groups
+    if params["num_key_value_heads"] is None:
+        params["num_key_value_heads"] = params["num_attention_heads"]
+
+    return params
+
+
+def _estimate_param_count(arch: Dict[str, Any]) -> int:
+    """Estimate total parameter count from architecture dimensions.
+
+    Accounts for: embeddings, per-layer attention (GQA-aware), per-layer FFN
+    (SwiGLU/GeGLU style with gate+up+down), and layer-norm weights.
+    Does NOT include optional biases (usually small).
+    """
+    h = arch["hidden_size"]
+    n_layers = arch["num_hidden_layers"]
+    vocab = arch["vocab_size"]
+    intermediate = arch["intermediate_size"]
+    n_heads = arch["num_attention_heads"]
+    n_kv = arch["num_key_value_heads"]
+    head_dim = h // n_heads
+
+    # Embedding + LM head (often tied; treat as single copy for conservative estimate)
+    embedding_params = vocab * h
+
+    # Attention projections: Q (h×h), K (h × kv_heads×head_dim), V (same as K), O (h×h)
+    q_params = h * h
+    kv_params = h * n_kv * head_dim
+    o_params = h * h
+    attn_params = q_params + 2 * kv_params + o_params
+
+    # FFN: gate + up (h → intermediate) and down (intermediate → h); SwiGLU has 3 matrices
+    ffn_params = 3 * h * intermediate
+
+    # Layer norms: 2 per layer (pre-attn + pre-ffn), each of size h
+    ln_params = 2 * h
+
+    per_layer = attn_params + ffn_params + ln_params
+    total = embedding_params + n_layers * per_layer + h  # +h for final norm
+
+    return int(total)
+
+
+# ---------------------------------------------------------------------------
+# VRAM component estimators
+# ---------------------------------------------------------------------------
+
+
+def _base_model_gb(num_params: int, quant: str) -> float:
+    """Model weight memory in GB."""
+    bpp = _BYTES_PER_PARAM.get(quant, 2.0)
+    return num_params * bpp / (1024**3)
+
+
+def _lora_adapter_gb(arch: Dict[str, Any], lora_r: int, target_module_count: int) -> float:
+    """LoRA adapter parameter memory in GB (always fp32 trainable params)."""
+    h = arch["hidden_size"]
+    # Each target module: A (h×r) + B (r×h); two matrices per layer × num_layers
+    adapter_params = 2 * lora_r * h * target_module_count * arch["num_hidden_layers"]
+    return adapter_params * 4 / (1024**3)  # fp32
+
+
+def _optimizer_state_gb(trainable_params: int, optimizer: str) -> float:
+    """Optimizer state memory in GB.
+
+    AdamW (fp32 moments): 8 bytes per trainable parameter.
+    8-bit Adam: ~2 bytes per trainable parameter.
+    Adafactor: ~4 bytes (first moment only, optional).
+    """
+    optimizer_lower = optimizer.lower()
+    if "8bit" in optimizer_lower or "8_bit" in optimizer_lower:
+        bpp = 2.0
+    elif "adafactor" in optimizer_lower:
+        bpp = 4.0
+    else:
+        bpp = 8.0  # AdamW default
+    return trainable_params * bpp / (1024**3)
+
+
+def _activation_gb(
+    arch: Dict[str, Any],
+    batch_size: int,
+    seq_len: int,
+    gradient_checkpointing: bool,
+) -> float:
+    """Activation memory in GB during the backward pass.
+
+    Heuristic: batch × seq × hidden × 4 (bytes fp16) × layers × 2 (fwd+bwd).
+    Gradient checkpointing reduces this by roughly sqrt(num_layers).
+    """
+    h = arch["hidden_size"]
+    n_layers = arch["num_hidden_layers"]
+    # Activation per layer: q,k,v,attn_scores,attn_probs,ffn_intermediate
+    bytes_per_token_per_layer = h * 2 * 6  # 6 activation tensors, fp16
+    raw_gb = batch_size * seq_len * bytes_per_token_per_layer * n_layers / (1024**3)
+
+    if gradient_checkpointing:
+        # Recompute activations during backward; only store ~sqrt(n) checkpoints
+        factor = max(math.sqrt(n_layers), 1.0)
+        return raw_gb / factor
+    return raw_gb * 2  # forward + backward without checkpointing
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def estimate_vram(config: Any) -> FitCheckResult:
+    """Estimate peak training VRAM for a ForgeConfig.
+
+    Queries the model's architecture via AutoConfig (network call on first run
+    for HF Hub models; cached by transformers).  Falls back to size-hint
+    heuristics when the config cannot be fetched (offline, private models).
+
+    Returns a :class:`FitCheckResult` with verdict, breakdown, and ordered
+    recommendations.
+    """
+    import torch
+
+    t = config.training
+    m = config.model
+    lora = config.lora
+
+    # --- architecture ---
+    arch = _load_arch_params(m.name_or_path, trust_remote_code=m.trust_remote_code)
+    num_params = _estimate_param_count(arch)
+
+    # --- quantisation scheme ---
+    # Pick the storage dtype, not the compute dtype. bnb_4bit_compute_dtype
+    # only describes 4-bit math precision and shouldn't be read when the model
+    # isn't actually QLoRA.
+    if m.load_in_4bit:
+        quant = "4bit"
+    elif getattr(m, "load_in_8bit", False):
+        quant = "8bit"
+    else:
+        torch_dtype = getattr(m, "torch_dtype", None) or getattr(getattr(m, "config", None), "torch_dtype", None)
+        if torch_dtype is None and m.load_in_4bit:
+            torch_dtype = getattr(m, "bnb_4bit_compute_dtype", "bf16")
+        dtype_map = {
+            "auto": "bf16",
+            "bfloat16": "bf16",
+            "bf16": "bf16",
+            "float16": "fp16",
+            "fp16": "fp16",
+            "float32": "fp32",
+            "fp32": "fp32",
+        }
+        quant = dtype_map.get(str(torch_dtype).lower(), "bf16") if torch_dtype is not None else "bf16"
+
+    # --- component estimates ---
+    base_gb = _base_model_gb(num_params, quant)
+
+    galore_enabled = bool(getattr(t, "galore_enabled", False))
+    grad_ckpt = getattr(t, "gradient_checkpointing", False)
+    act_gb = _activation_gb(arch, t.per_device_train_batch_size, m.max_length, grad_ckpt)
+
+    # GaLore is full-parameter training: optimizer state is sized against the
+    # *projected* rank, not against LoRA's adapter footprint. LoRA accounting
+    # is mutually exclusive — adding both would double-count.
+    if galore_enabled:
+        galore_rank = getattr(t, "galore_rank", 64)
+        h = arch["hidden_size"]
+        projected_params = int(num_params * (galore_rank / h))
+        adapter_params = 0
+        adapter_gb = 0.0
+        trainable_params = projected_params
+        galore_gb = num_params * (galore_rank / h) * 4 / (1024**3)
+        optim_gb = _optimizer_state_gb(trainable_params, getattr(t, "galore_optim", "adamw"))
+    else:
+        target_module_count = len(lora.target_modules)
+        # Integer adapter param count (avoids float round-trip via GB)
+        adapter_params = 2 * lora.r * arch["hidden_size"] * target_module_count * arch["num_hidden_layers"]
+        adapter_gb = adapter_params * 4 / (1024**3)  # fp32
+        trainable_params = adapter_params
+        galore_gb = 0.0
+        optim_gb = _optimizer_state_gb(trainable_params, "adamw")
+
+    total_gb = base_gb + adapter_gb + optim_gb + act_gb + galore_gb
+
+    breakdown = {
+        "base_model_gb": round(base_gb, 2),
+        "lora_adapter_gb": round(adapter_gb, 2),
+        "optimizer_state_gb": round(optim_gb, 2),
+        "activations_gb": round(act_gb, 2),
+        "galore_buffers_gb": round(galore_gb, 2),
+        "total_estimated_gb": round(total_gb, 2),
+        "quant_scheme": quant,
+        "estimated_param_count_b": round(num_params / 1e9, 2),
+        # Estimation, not measurement.  FlashAttention/SDPA can drop activation
+        # memory by 30–50 %; MoE expert counts can multiply it 2–3×; sliding-
+        # window attention shifts the curve.  Treat the verdict as advisory.
+        "estimation_caveat": (
+            "heuristic estimate, ±30% typical; FlashAttention/SDPA, MoE expert "
+            "count, and attention type are not modeled"
+        ),
+    }
+
+    # --- available VRAM ---
+    available_gb: Optional[float] = None
+    hypothetical = False
+    try:
+        if torch.cuda.is_available():
+            free_bytes, _ = torch.cuda.mem_get_info()
+            available_gb = free_bytes / (1024**3)
+        else:
+            hypothetical = True
+    except Exception as e:
+        logger.debug("Could not query GPU memory: %s", e)
+        hypothetical = True
+
+    # --- verdict ---
+    if hypothetical or available_gb is None:
+        verdict = "UNKNOWN"
+    elif total_gb <= available_gb * _TIGHT_THRESHOLD:
+        verdict = "FITS"
+    elif total_gb <= available_gb * _OOM_THRESHOLD:
+        verdict = "TIGHT"
+    else:
+        verdict = "OOM"
+
+    # --- recommendations (ordered by impact) ---
+    recommendations = _build_recommendations(
+        config=config,
+        total_gb=total_gb,
+        available_gb=available_gb,
+        grad_ckpt=grad_ckpt,
+    )
+
+    return FitCheckResult(
+        verdict=verdict,
+        estimated_gb=round(total_gb, 2),
+        available_gb=round(available_gb, 2) if available_gb is not None else None,
+        recommendations=recommendations,
+        breakdown=breakdown,
+        hypothetical=hypothetical,
+    )
+
+
+def _build_recommendations(
+    config: Any,
+    total_gb: float,
+    available_gb: Optional[float],
+    grad_ckpt: bool,
+) -> List[str]:
+    """Return an ordered list of recommendations to reduce VRAM usage."""
+    recs: List[str] = []
+    t = config.training
+    m = config.model
+
+    if available_gb and total_gb > available_gb * _TIGHT_THRESHOLD:
+        # Most impactful first
+        if t.per_device_train_batch_size > 1:
+            new_bs = max(1, t.per_device_train_batch_size // 2)
+            new_accum = t.gradient_accumulation_steps * (t.per_device_train_batch_size // new_bs)
+            recs.append(
+                f"Reduce per_device_train_batch_size from {t.per_device_train_batch_size} to {new_bs} "
+                f"and increase gradient_accumulation_steps to {new_accum} to keep effective batch size."
+            )
+
+        if m.max_length > 1024:
+            recs.append(
+                f"Reduce max_length from {m.max_length} to {m.max_length // 2}; "
+                "activation memory scales linearly with sequence length."
+            )
+
+        if not grad_ckpt:
+            recs.append(
+                "Enable gradient_checkpointing: true in your training config; "
+                "trades ~20 % compute for significantly lower activation memory."
+            )
+
+        if not m.load_in_4bit:
+            recs.append("Enable load_in_4bit: true for QLoRA; reduces base model weight memory by ~75 %.")
+
+        if not getattr(t, "galore_enabled", False):
+            recs.append(
+                "Consider galore_enabled: true (GaLore optimizer) for full-parameter "
+                "training with gradient low-rank projection, reducing gradient memory."
+            )
+
+        if config.lora.r > 16:
+            recs.append(
+                f"Lower LoRA rank from r={config.lora.r} to 8–16; adapter memory and optimizer state scale with r."
+            )
+
+    return recs
+
+
+def format_fit_check(result: FitCheckResult) -> str:
+    """Format a FitCheckResult as a human-readable multi-line string."""
+    lines: List[str] = []
+    lines.append("=== VRAM Fit Check ===")
+
+    if result.available_gb is not None:
+        lines.append(f"  GPU available: {result.available_gb:.1f} GB")
+    else:
+        lines.append("  GPU: not detected (hypothetical mode)")
+
+    lines.append(f"  Estimated peak: {result.estimated_gb:.1f} GB")
+
+    verdict_icons = {"FITS": "✅", "TIGHT": "⚠️", "OOM": "❌", "UNKNOWN": "ℹ️"}
+    icon = verdict_icons.get(result.verdict, "")
+    lines.append(f"  Verdict: {icon} {result.verdict}")
+    if result.available_gb and result.verdict == "FITS":
+        headroom = result.available_gb - result.estimated_gb
+        lines.append(f"           ({headroom:.1f} GB headroom)")
+
+    lines.append("")
+    lines.append("  Breakdown:")
+    for k, v in result.breakdown.items():
+        if k.endswith("_gb"):
+            lines.append(f"    {k}: {v} GB")
+        else:
+            lines.append(f"    {k}: {v}")
+
+    if result.recommendations:
+        lines.append("")
+        lines.append("  Recommendations (highest impact first):")
+        for i, rec in enumerate(result.recommendations, 1):
+            lines.append(f"    {i}. {rec}")
+
+    lines.append("======================")
+    return "\n".join(lines)
diff --git a/forgelm/inference.py b/forgelm/inference.py
new file mode 100644
index 00000000..50072931
--- /dev/null
+++ b/forgelm/inference.py
@@ -0,0 +1,404 @@
+"""
+Core inference primitives shared across chat, judge, synthetic, and safety modules.
+
+Provides a unified load/generate interface with streaming support, logit statistics,
+and adaptive sampling.  Heavy dependencies (torch, transformers, peft) are imported
+lazily so that --help and config parsing remain lightweight.
+"""
+
+from __future__ import annotations
+
+import logging
+from threading import Thread
+from typing import Any, Dict, Iterator, List, Optional, Tuple
+
+logger = logging.getLogger("forgelm.inference")
+
+
+# ---------------------------------------------------------------------------
+# Model loading
+# ---------------------------------------------------------------------------
+
+
+def load_model(
+    path: str,
+    adapter: Optional[str] = None,
+    backend: str = "transformers",
+    load_in_4bit: bool = False,
+    load_in_8bit: bool = False,
+    trust_remote_code: bool = False,
+    device_map: Optional[str] = "auto",
+) -> Tuple[Any, Any]:
+    """Load a causal LM and tokenizer for inference.
+
+    Args:
+        path: Local directory or HF Hub model ID.
+        adapter: Optional PEFT adapter path.  Adapter weights are merged into
+            the base model and unloaded so generation is self-contained.
+        backend: ``"transformers"`` (default) or ``"unsloth"``.
+        load_in_4bit: Enable bitsandbytes 4-bit NF4 quantisation (CUDA only).
+        load_in_8bit: Enable bitsandbytes 8-bit quantisation (CUDA only).
+        trust_remote_code: Allow execution of model-bundled code.
+        device_map: Passed directly to ``from_pretrained``; ``"auto"`` for
+            multi-GPU, ``None`` to skip placement (e.g. CPU-only).
+
+    Returns:
+        ``(model, tokenizer)`` tuple ready for generation.
+    """
+    import torch
+    from transformers import AutoModelForCausalLM, AutoTokenizer
+
+    if backend.lower() == "unsloth":
+        if load_in_4bit and load_in_8bit:
+            logger.warning("Both load_in_4bit and load_in_8bit are set; preferring 4-bit for Unsloth backend.")
+        return _load_unsloth(
+            path,
+            adapter,
+            trust_remote_code,
+            load_in_4bit=load_in_4bit,
+            load_in_8bit=load_in_8bit,
+        )
+
+    logger.info("Loading model for inference: %s", path)
+
+    tokenizer = AutoTokenizer.from_pretrained(path, trust_remote_code=trust_remote_code)
+    if tokenizer.pad_token is None:
+        tokenizer.pad_token = tokenizer.eos_token
+
+    model_kwargs: Dict[str, Any] = {"trust_remote_code": trust_remote_code}
+    if device_map is not None:
+        model_kwargs["device_map"] = device_map
+
+    if torch.cuda.is_available():
+        if load_in_4bit:
+            from transformers import BitsAndBytesConfig
+
+            model_kwargs["quantization_config"] = BitsAndBytesConfig(
+                load_in_4bit=True,
+                bnb_4bit_compute_dtype=torch.bfloat16 if torch.cuda.is_bf16_supported() else torch.float16,
+                bnb_4bit_use_double_quant=True,
+                bnb_4bit_quant_type="nf4",
+            )
+        elif load_in_8bit:
+            from transformers import BitsAndBytesConfig
+
+            model_kwargs["quantization_config"] = BitsAndBytesConfig(load_in_8bit=True)
+
+    model = AutoModelForCausalLM.from_pretrained(path, **model_kwargs)
+    model.eval()
+
+    if adapter:
+        logger.info("Loading PEFT adapter from %s, merging into base model.", adapter)
+        from peft import PeftModel
+
+        model = PeftModel.from_pretrained(model, adapter)
+        model = model.merge_and_unload()
+        logger.info("Adapter merged and unloaded.")
+
+    return model, tokenizer
+
+
+def _load_unsloth(
+    path: str,
+    adapter: Optional[str],
+    trust_remote_code: bool,
+    *,
+    load_in_4bit: bool = False,
+    load_in_8bit: bool = False,
+) -> Tuple[Any, Any]:
+    """Load model via the Unsloth backend for faster inference."""
+    try:
+        from unsloth import FastLanguageModel
+    except ImportError as e:
+        raise ImportError(
+            "Unsloth backend requested but 'unsloth' is not installed.  Install with: pip install unsloth"
+        ) from e
+
+    # Default to 4-bit when neither flag is set (Unsloth's primary mode)
+    if not load_in_4bit and not load_in_8bit:
+        load_in_4bit = True
+
+    model, tokenizer = FastLanguageModel.from_pretrained(
+        model_name=path,
+        dtype=None,
+        load_in_4bit=load_in_4bit,
+        load_in_8bit=load_in_8bit,
+        trust_remote_code=trust_remote_code,
+    )
+    FastLanguageModel.for_inference(model)
+
+    if adapter:
+        raise ValueError(
+            "Unsloth backend does not support loading a separate adapter at inference time. "
+            "Merge the adapter into the base model before inference "
+            "(forgelm export --adapter ...), or use backend='transformers'."
+        )
+    return model, tokenizer
+
+
+# ---------------------------------------------------------------------------
+# Input preparation
+# ---------------------------------------------------------------------------
+
+
+def _build_prompt(
+    tokenizer: Any,
+    messages: List[Dict[str, str]],
+) -> str:
+    """Format a message list into a prompt string using the tokenizer's chat template.
+
+    Falls back to a plain ``role: content`` concatenation when no template is
+    available (e.g. raw base models).
+    """
+    if getattr(tokenizer, "chat_template", None) and hasattr(tokenizer, "apply_chat_template"):
+        return tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+
+    parts: List[str] = []
+    for msg in messages:
+        parts.append(f"{msg['role']}: {msg['content']}")
+    # Mimic add_generation_prompt=True: signal the model to continue as assistant
+    # rather than echoing the user role.  Without this, raw base models tend to
+    # produce a "user: ..." continuation instead of a response.
+    parts.append("assistant: ")
+    return "\n".join(parts)
+
+
+def _to_messages(
+    prompt: str,
+    system_prompt: Optional[str] = None,
+    history: Optional[List[Dict[str, str]]] = None,
+) -> List[Dict[str, str]]:
+    """Assemble a message list from a user prompt, optional system prompt, and history."""
+    messages: List[Dict[str, str]] = []
+    if system_prompt:
+        messages.append({"role": "system", "content": system_prompt})
+    if history:
+        messages.extend(history)
+    messages.append({"role": "user", "content": prompt})
+    return messages
+
+
+# ---------------------------------------------------------------------------
+# Generation
+# ---------------------------------------------------------------------------
+
+
+def generate(
+    model: Any,
+    tokenizer: Any,
+    prompt: str,
+    *,
+    messages: Optional[List[Dict[str, str]]] = None,
+    system_prompt: Optional[str] = None,
+    history: Optional[List[Dict[str, str]]] = None,
+    max_new_tokens: int = 512,
+    temperature: float = 0.7,
+    top_k: int = 50,
+    top_p: float = 0.9,
+    repetition_penalty: float = 1.1,
+    do_sample: bool = True,
+) -> str:
+    """Generate a response for *prompt*.
+
+    Handles chat template formatting automatically.  Pass *messages* to supply
+    a pre-built message list (e.g. for multi-turn chat); otherwise the function
+    builds one from *prompt*, *system_prompt*, and *history*.
+
+    Returns the generated response text only (input tokens stripped).
+    """
+    import torch
+
+    if messages is None:
+        messages = _to_messages(prompt, system_prompt, history)
+
+    text = _build_prompt(tokenizer, messages)
+    input_ids = tokenizer(text, return_tensors="pt").input_ids.to(model.device)
+
+    gen_kwargs: Dict[str, Any] = {
+        "input_ids": input_ids,
+        "max_new_tokens": max_new_tokens,
+        "do_sample": do_sample,
+        "pad_token_id": tokenizer.pad_token_id,
+        "eos_token_id": tokenizer.eos_token_id,
+    }
+    if do_sample:
+        gen_kwargs.update(temperature=temperature, top_k=top_k, top_p=top_p)
+    gen_kwargs["repetition_penalty"] = repetition_penalty
+
+    with torch.inference_mode():
+        output_ids = model.generate(**gen_kwargs)
+
+    new_tokens = output_ids[0][input_ids.shape[-1] :]
+    return tokenizer.decode(new_tokens, skip_special_tokens=True)
+
+
+def generate_stream(
+    model: Any,
+    tokenizer: Any,
+    prompt: str,
+    *,
+    messages: Optional[List[Dict[str, str]]] = None,
+    system_prompt: Optional[str] = None,
+    history: Optional[List[Dict[str, str]]] = None,
+    max_new_tokens: int = 512,
+    temperature: float = 0.7,
+    top_k: int = 50,
+    top_p: float = 0.9,
+    repetition_penalty: float = 1.1,
+    do_sample: bool = True,
+) -> Iterator[str]:
+    """Stream generation token-by-token.
+
+    Yields decoded text fragments as they are produced.  Uses
+    ``TextIteratorStreamer`` in a background thread so the caller's loop can
+    update the UI without blocking.
+    """
+    from transformers import TextIteratorStreamer
+
+    if messages is None:
+        messages = _to_messages(prompt, system_prompt, history)
+
+    text = _build_prompt(tokenizer, messages)
+    input_ids = tokenizer(text, return_tensors="pt").input_ids.to(model.device)
+
+    # timeout prevents an indefinite block when model.generate() raises before
+    # the streamer's queue is populated (OOM, dtype mismatch, invalid input ids).
+    streamer = TextIteratorStreamer(
+        tokenizer,
+        skip_prompt=True,
+        skip_special_tokens=True,
+        timeout=60.0,
+    )
+
+    gen_kwargs: Dict[str, Any] = {
+        "input_ids": input_ids,
+        "max_new_tokens": max_new_tokens,
+        "do_sample": do_sample,
+        "pad_token_id": tokenizer.pad_token_id,
+        "eos_token_id": tokenizer.eos_token_id,
+        "streamer": streamer,
+    }
+    if do_sample:
+        gen_kwargs.update(temperature=temperature, top_k=top_k, top_p=top_p)
+    gen_kwargs["repetition_penalty"] = repetition_penalty
+
+    _exc: List[BaseException] = []
+
+    def _gen_thread() -> None:
+        try:
+            model.generate(**gen_kwargs)
+        except Exception as e:
+            _exc.append(e)
+
+    thread = Thread(target=_gen_thread, daemon=True)
+    thread.start()
+
+    from queue import Empty as _QueueEmpty
+
+    try:
+        for token_text in streamer:
+            yield token_text
+    except _QueueEmpty as timeout_err:
+        # Streamer timed out waiting for the next token.  If the worker thread
+        # captured an exception, surface that; otherwise raise a TimeoutError
+        # so callers can distinguish "stuck" from a normal end of generation.
+        if _exc:
+            raise _exc[0] from timeout_err
+        raise TimeoutError(
+            "generate_stream timed out waiting for the next token from model.generate()."
+        ) from timeout_err
+
+    thread.join()
+    if _exc:
+        raise _exc[0]
+
+
+# ---------------------------------------------------------------------------
+# Logit statistics
+# ---------------------------------------------------------------------------
+
+
+def logit_stats(logits: Any) -> Dict[str, float]:
+    """Compute generation-quality statistics from a single-position logit tensor.
+
+    Args:
+        logits: 1-D tensor of shape ``[vocab_size]``.
+
+    Returns:
+        Dict with keys:
+          - ``entropy``: Shannon entropy (nats) over the softmax distribution.
+          - ``top1_prob``: Probability of the argmax token.
+          - ``effective_vocab``: Number of tokens with probability > 1 %.
+    """
+    import torch
+
+    probs = torch.softmax(logits.float(), dim=-1)
+    log_probs = torch.log(probs + 1e-10)
+    entropy = float(-torch.sum(probs * log_probs).item())
+    top1_prob = float(probs.max().item())
+    effective_vocab = int((probs > 0.01).sum().item())
+    return {
+        "entropy": round(entropy, 4),
+        "top1_prob": round(top1_prob, 4),
+        "effective_vocab": effective_vocab,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Adaptive sampling
+# ---------------------------------------------------------------------------
+
+
+def adaptive_sample(
+    logits: Any,
+    temperature: float = 1.0,
+    top_k: int = 50,
+    top_p: float = 0.9,
+    entropy_threshold: float = 6.5,
+) -> int:
+    """Sample the next token with entropy-adaptive strategy.
+
+    When the model is confident (entropy < *entropy_threshold*), uses greedy
+    decoding to avoid introducing noise.  For high-entropy distributions,
+    applies temperature scaling followed by top-k and nucleus (top-p) filtering
+    before sampling.
+
+    Args:
+        logits: 1-D tensor of shape ``[vocab_size]``.
+        temperature: Scaling factor for logits in sampling mode.
+        top_k: Keep only the *top_k* most likely tokens.
+        top_p: Nucleus probability mass threshold.
+        entropy_threshold: Shannon entropy (nats) below which greedy decoding
+            is used.  ``math.log(vocab_size)`` ≈ 10.8 for a 50 k vocab.
+
+    Returns:
+        Integer token index.
+    """
+    import torch
+
+    probs = torch.softmax(logits.float(), dim=-1)
+    entropy = float(-torch.sum(probs * torch.log(probs + 1e-10)).item())
+
+    if entropy < entropy_threshold:
+        return int(logits.argmax().item())
+
+    # Temperature scaling
+    scaled = logits.float() / max(temperature, 1e-6)
+
+    # Top-k filtering
+    if top_k > 0:
+        k = min(top_k, scaled.size(-1))
+        top_vals, _ = torch.topk(scaled, k)
+        cutoff = top_vals[..., -1].unsqueeze(-1)
+        scaled = scaled.masked_fill(scaled < cutoff, float("-inf"))
+
+    # Nucleus (top-p) filtering
+    if 0.0 < top_p < 1.0:
+        sorted_logits, sorted_idx = torch.sort(scaled, descending=True)
+        cumulative = torch.cumsum(torch.softmax(sorted_logits, dim=-1), dim=-1)
+        remove = cumulative - torch.softmax(sorted_logits, dim=-1) > top_p
+        sorted_logits[remove] = float("-inf")
+        scaled = scaled.scatter(-1, sorted_idx, sorted_logits)
+
+    sample_probs = torch.softmax(scaled, dim=-1)
+    return int(torch.multinomial(sample_probs, num_samples=1).item())
diff --git a/forgelm/judge.py b/forgelm/judge.py
index 534da414..475a3e67 100644
--- a/forgelm/judge.py
+++ b/forgelm/judge.py
@@ -8,7 +8,7 @@
 import logging
 import os
 from dataclasses import dataclass, field
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Tuple
 
 logger = logging.getLogger("forgelm.judge")
 
@@ -31,7 +31,10 @@ class JudgeResult:
     """Result of an LLM-as-Judge evaluation."""
 
     average_score: float = 0.0
-    scores: List[float] = field(default_factory=list)
+    # None entries are sentinel values for parse/transport failures (see
+    # _clip_judge_score). Consumers iterating ``scores`` must filter or
+    # otherwise handle them; the average is computed over non-None entries.
+    scores: List[Optional[float]] = field(default_factory=list)
     passed: bool = True
     failure_reason: Optional[str] = None
     details: List[Dict[str, Any]] = field(default_factory=list)
@@ -57,7 +60,9 @@ def _parse_judge_json(text: str) -> Dict[str, Any]:
             except json.JSONDecodeError:
                 continue
     logger.warning("Could not parse judge response as JSON: %s", text[:200])
-    return {"score": 0, "reason": f"Invalid JSON response: {text[:200]}"}
+    # Use score=None as the failure sentinel — score=0 used to be clipped up
+    # to 1.0 by _clip_judge_score and silently lowered the average.
+    return {"score": None, "reason": f"Invalid JSON response: {text[:200]}"}
 
 
 def _call_api_judge(prompt: str, api_key: str, model: str = "gpt-4o", api_base: str = None) -> Dict[str, Any]:
@@ -83,10 +88,10 @@ def _call_api_judge(prompt: str, api_key: str, model: str = "gpt-4o", api_base:
         return _parse_judge_json(content)
     except json.JSONDecodeError as e:
         logger.warning("API judge returned invalid JSON: %s", e)
-        return {"score": 0, "reason": f"Invalid JSON from API: {e}"}
+        return {"score": None, "reason": f"Invalid JSON from API: {e}"}
     except Exception as e:
         logger.warning("API judge call failed: %s", e)
-        return {"score": 0, "reason": f"API error: {e}"}
+        return {"score": None, "reason": f"API error: {e}"}
 
 
 def _call_local_judge(prompt: str, model: Any, tokenizer: Any) -> Dict[str, Any]:
@@ -102,7 +107,92 @@ def _call_local_judge(prompt: str, model: Any, tokenizer: Any) -> Dict[str, Any]
         return _parse_judge_json(response)
     except Exception as e:
         logger.warning("Local judge evaluation failed: %s", e)
-        return {"score": 0, "reason": f"Local judge error: {e}"}
+        return {"score": None, "reason": f"Local judge error: {e}"}
+
+
+def _load_eval_prompts(path: str) -> List[str]:
+    """Load prompts from a JSONL file (one prompt per line, plain or JSON object)."""
+    prompts: List[str] = []
+    with open(path, "r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                data = json.loads(line)
+                prompts.append(data.get("prompt", data.get("text", "")))
+            except json.JSONDecodeError:
+                prompts.append(line)
+    return prompts
+
+
+def _load_local_judge(judge_model: str) -> Tuple[Any, Any]:
+    """Load a local judge model + tokenizer pair."""
+    from transformers import AutoModelForCausalLM, AutoTokenizer
+
+    logger.info("Loading local judge model: %s", judge_model)
+    tok = AutoTokenizer.from_pretrained(judge_model)
+    mdl = AutoModelForCausalLM.from_pretrained(judge_model, device_map="auto")
+    return mdl, tok
+
+
+def _generate_response(model: Any, tokenizer: Any, prompt: str, max_new_tokens: int) -> str:
+    """Generate a single response from the fine-tuned model under evaluation."""
+    import torch as _torch
+
+    try:
+        inputs = tokenizer(prompt, return_tensors="pt", truncation=True, max_length=1024)
+        inputs = {k: v.to(model.device) for k, v in inputs.items()}
+        with _torch.no_grad():
+            outputs = model.generate(**inputs, max_new_tokens=max_new_tokens, do_sample=False)
+        return tokenizer.decode(outputs[0][inputs["input_ids"].shape[1] :], skip_special_tokens=True)
+    except Exception as e:
+        logger.warning("Failed to generate response: %s", e)
+        return ""
+
+
+def _clip_judge_score(raw_score: Optional[float]) -> Optional[float]:
+    """Clip the judge's raw 1-10 score; pass through None for parse/transport failures.
+
+    None preserves the failure signal so the caller can skip the sample in the
+    average (rather than counting it as a 1.0 floor and pulling the score down).
+    """
+    if raw_score is None:
+        return None
+    score = max(1.0, min(10.0, raw_score))
+    if raw_score != score:
+        logger.warning(
+            "Judge returned out-of-range score %.1f (expected 1-10), clipped to %.1f",
+            raw_score,
+            score,
+        )
+    return score
+
+
+def _save_judge_results(
+    output_dir: str,
+    avg_score: float,
+    min_score: float,
+    passed: bool,
+    num_prompts: int,
+    details: List[Dict[str, Any]],
+) -> None:
+    """Persist the judge run summary as judge_results.json."""
+    os.makedirs(output_dir, exist_ok=True)
+    results_path = os.path.join(output_dir, "judge_results.json")
+    with open(results_path, "w", encoding="utf-8") as f:
+        json.dump(
+            {
+                "average_score": avg_score,
+                "min_score": min_score,
+                "passed": passed,
+                "num_prompts": num_prompts,
+                "details": details,
+            },
+            f,
+            indent=2,
+        )
+    logger.info("Judge results saved to %s", results_path)
 
 
 def run_judge_evaluation(
@@ -138,73 +228,39 @@ def run_judge_evaluation(
         return JudgeResult(passed=False, failure_reason=f"Eval dataset not found: {eval_dataset_path}")
 
     rubric = rubric or DEFAULT_RUBRIC
-
-    # Load eval prompts
-    eval_prompts = []
-    with open(eval_dataset_path, "r", encoding="utf-8") as f:
-        for line in f:
-            line = line.strip()
-            if line:
-                try:
-                    data = json.loads(line)
-                    eval_prompts.append(data.get("prompt", data.get("text", "")))
-                except json.JSONDecodeError:
-                    eval_prompts.append(line)
-
+    eval_prompts = _load_eval_prompts(eval_dataset_path)
     if not eval_prompts:
         logger.warning("No eval prompts found. Skipping judge evaluation.")
         return JudgeResult(passed=True)
 
     logger.info("Running LLM-as-Judge evaluation with %d prompts (judge: %s)...", len(eval_prompts), judge_model)
 
-    # Generate responses from fine-tuned model
-    scores = []
-    details = []
     is_api_judge = judge_api_key is not None
-
-    # Load local judge if needed
     local_judge_model = None
     local_judge_tokenizer = None
     if not is_api_judge:
         try:
-            from transformers import AutoModelForCausalLM, AutoTokenizer
-
-            logger.info("Loading local judge model: %s", judge_model)
-            local_judge_tokenizer = AutoTokenizer.from_pretrained(judge_model)
-            local_judge_model = AutoModelForCausalLM.from_pretrained(judge_model, device_map="auto")
+            local_judge_model, local_judge_tokenizer = _load_local_judge(judge_model)
         except Exception as e:
             logger.error("Failed to load local judge model: %s", e)
             return JudgeResult(passed=False, failure_reason=f"Judge model load failed: {e}")
 
-    import torch as _torch
+    scores: List[Optional[float]] = []
+    details: List[Dict[str, Any]] = []
+    failure_count = 0
 
     for prompt in eval_prompts:
-        # Generate response from fine-tuned model
-        try:
-            inputs = tokenizer(prompt, return_tensors="pt", truncation=True, max_length=1024)
-            inputs = {k: v.to(model.device) for k, v in inputs.items()}
-            with _torch.no_grad():
-                outputs = model.generate(**inputs, max_new_tokens=max_new_tokens, do_sample=False)
-            response = tokenizer.decode(outputs[0][inputs["input_ids"].shape[1] :], skip_special_tokens=True)
-        except Exception as e:
-            logger.warning("Failed to generate response: %s", e)
-            response = ""
-
-        # Score with judge
+        response = _generate_response(model, tokenizer, prompt, max_new_tokens)
         judge_prompt = rubric.format(prompt=prompt[:500], response=response[:1000])
         if is_api_judge:
             result = _call_api_judge(judge_prompt, judge_api_key, judge_model, api_base=api_base)
         else:
             result = _call_local_judge(judge_prompt, local_judge_model, local_judge_tokenizer)
 
-        raw_score = float(result.get("score", 0))
-        score = max(1.0, min(10.0, raw_score))
-        if raw_score != score:
-            logger.warning(
-                "Judge returned out-of-range score %.1f (expected 1-10), clipped to %.1f",
-                raw_score,
-                score,
-            )
+        raw_score = result.get("score")
+        score = _clip_judge_score(float(raw_score) if raw_score is not None else None)
+        if score is None:
+            failure_count += 1
         scores.append(score)
         details.append(
             {
@@ -212,35 +268,37 @@ def run_judge_evaluation(
                 "response": response[:200],
                 "score": score,
                 "reason": result.get("reason", ""),
+                "judge_failed": score is None,
             }
         )
 
-    avg_score = sum(scores) / len(scores) if scores else 0.0
-    logger.info("LLM-as-Judge average score: %.2f / 10.0", avg_score)
+    valid_scores = [s for s in scores if s is not None]
 
-    passed = avg_score >= min_score
-    failure_reason = None
-    if not passed:
-        failure_reason = f"Average judge score ({avg_score:.2f}) below minimum ({min_score:.2f})"
+    # No valid scores → distinct failure mode. Treating this as "low average"
+    # would mislead the operator into thinking the model performed badly when
+    # really the judge itself never produced a usable verdict.
+    if not valid_scores:
+        avg_score = 0.0
+        passed = False
+        failure_reason = f"No valid judge scores (all {failure_count}/{len(eval_prompts)} parses/requests failed)."
         logger.error("JUDGE EVALUATION FAILED: %s", failure_reason)
+    else:
+        avg_score = sum(valid_scores) / len(valid_scores)
+        logger.info(
+            "LLM-as-Judge average score: %.2f / 10.0 (%d/%d valid; %d judge failures)",
+            avg_score,
+            len(valid_scores),
+            len(eval_prompts),
+            failure_count,
+        )
+        passed = avg_score >= min_score
+        failure_reason = None
+        if not passed:
+            failure_reason = f"Average judge score ({avg_score:.2f}) below minimum ({min_score:.2f})"
+            logger.error("JUDGE EVALUATION FAILED: %s", failure_reason)
 
-    # Save results
     if output_dir:
-        os.makedirs(output_dir, exist_ok=True)
-        results_path = os.path.join(output_dir, "judge_results.json")
-        with open(results_path, "w", encoding="utf-8") as f:
-            json.dump(
-                {
-                    "average_score": avg_score,
-                    "min_score": min_score,
-                    "passed": passed,
-                    "num_prompts": len(eval_prompts),
-                    "details": details,
-                },
-                f,
-                indent=2,
-            )
-        logger.info("Judge results saved to %s", results_path)
+        _save_judge_results(output_dir, avg_score, min_score, passed, len(eval_prompts), details)
 
     return JudgeResult(
         average_score=avg_score,
diff --git a/forgelm/merging.py b/forgelm/merging.py
index bf29d73f..1bd3dabf 100644
--- a/forgelm/merging.py
+++ b/forgelm/merging.py
@@ -117,6 +117,14 @@ def _linear_merge(base_model, adapters):
         del adapter_model, merged_adapter
 
     missing, unexpected = base_model.load_state_dict(merged_state, strict=False)
+    # Both directions of mismatch are useful when diagnosing a bad merge:
+    # - missing  → adapter didn't supply weights the base model expects
+    # - unexpected → adapter supplied weights the base model has no slot for
+    if missing:
+        logger.warning(
+            "Merge left %d base-model parameters without adapter coverage (using base values).",
+            len(missing),
+        )
     if unexpected:
         logger.warning("Merge produced %d unexpected keys (ignored).", len(unexpected))
     return base_model
@@ -162,7 +170,9 @@ def _slerp_merge(base_model, adapters):
             v0 = state_a[key].float()
             v1 = state_b[key].float()
             # Simplified SLERP for parameter tensors
-            dot = torch.sum(v0 * v1) / (torch.norm(v0) * torch.norm(v1) + 1e-8)
+            # vector_norm flattens the parameter tensor and returns a scalar
+            # magnitude — the right semantics for SLERP, regardless of tensor rank.
+            dot = torch.sum(v0 * v1) / (torch.linalg.vector_norm(v0) * torch.linalg.vector_norm(v1) + 1e-8)
             dot = torch.clamp(dot, -1.0, 1.0)
             omega = torch.acos(dot)
             if omega.abs() < 1e-6:
@@ -253,6 +263,8 @@ def _ties_merge_tensor(deltas, weights, trim_fraction=0.2):
         flat = stacked[i].abs().flatten()
         if flat.numel() == 0:
             continue
+        # flat is already 1-D from .flatten(); the default behavior computes
+        # the quantile across all elements, which is what we want.
         threshold = torch.quantile(flat.float(), trim_fraction)
         stacked[i][stacked[i].abs() < threshold] = 0.0
 
diff --git a/forgelm/model.py b/forgelm/model.py
index 3780673f..c1f19472 100644
--- a/forgelm/model.py
+++ b/forgelm/model.py
@@ -1,5 +1,5 @@
 import logging
-from typing import Any, Tuple
+from typing import Any, Optional, Tuple
 
 import torch
 from peft import LoraConfig, get_peft_model, prepare_model_for_kbit_training
@@ -21,135 +21,119 @@ def _resolve_bnb_compute_dtype(dtype_str: str):
     raise ValueError(f"Unsupported bnb_4bit_compute_dtype: {dtype_str!r}")
 
 
-def get_model_and_tokenizer(config: Any) -> Tuple[Any, Any]:
-    """Loads the base model, tokenizer, and configures LoRA."""
-    logger.info("Loading Base Model: %s with backend: %s", config.model.name_or_path, config.model.backend)
-
-    trust_remote_code = getattr(config.model, "trust_remote_code", False)
-    if trust_remote_code:
-        logger.warning(
-            "trust_remote_code is ENABLED. This allows execution of arbitrary code "
-            "from the model repository. Only use this with models you trust."
-        )
-
-    # --- UNSLOTH BACKEND ---
-    if config.model.backend.lower() == "unsloth":
-        try:
-            from unsloth import FastLanguageModel
-        except ImportError as e:
-            raise ImportError("Unsloth backend selected but 'unsloth' is not installed. Please install it.") from e
-
-        model, tokenizer = FastLanguageModel.from_pretrained(
-            model_name=config.model.name_or_path,
-            max_seq_length=config.model.max_length,
-            dtype=None,  # Auto detection
-            load_in_4bit=config.model.load_in_4bit,
-        )
+def _load_unsloth(config: Any) -> Tuple[Any, Any]:
+    """Load the model + tokenizer + LoRA via the Unsloth backend."""
+    try:
+        from unsloth import FastLanguageModel
+    except ImportError as e:
+        raise ImportError("Unsloth backend selected but 'unsloth' is not installed. Please install it.") from e
+
+    model, tokenizer = FastLanguageModel.from_pretrained(
+        model_name=config.model.name_or_path,
+        max_seq_length=config.model.max_length,
+        dtype=None,  # Auto detection
+        load_in_4bit=config.model.load_in_4bit,
+    )
 
-        logger.info("Setting up Unsloth LoRA configuration (DoRA=%s)...", config.lora.use_dora)
-        model = FastLanguageModel.get_peft_model(
-            model,
-            r=config.lora.r,
-            target_modules=config.lora.target_modules,
-            lora_alpha=config.lora.alpha,
-            lora_dropout=config.lora.dropout,
-            bias=config.lora.bias,
-            use_gradient_checkpointing="unsloth",
-            use_rslora=getattr(config.lora, "use_rslora", False),
-            use_dora=config.lora.use_dora,
-        )
+    logger.info("Setting up Unsloth LoRA configuration (DoRA=%s)...", config.lora.use_dora)
+    model = FastLanguageModel.get_peft_model(
+        model,
+        r=config.lora.r,
+        target_modules=config.lora.target_modules,
+        lora_alpha=config.lora.alpha,
+        lora_dropout=config.lora.dropout,
+        bias=config.lora.bias,
+        use_gradient_checkpointing="unsloth",
+        use_rslora=getattr(config.lora, "use_rslora", False),
+        use_dora=config.lora.use_dora,
+    )
+    return model, tokenizer
 
-        return model, tokenizer
 
-    # --- MULTIMODAL VLM CHECK ---
+def _load_tokenizer(config: Any, trust_remote_code: bool) -> Any:
+    """Load AutoTokenizer (or AutoProcessor for VLMs) and ensure pad_token is set."""
     mm_cfg = getattr(config.model, "multimodal", None)
-    is_multimodal = mm_cfg and mm_cfg.enabled
-    if is_multimodal:
+    if mm_cfg and mm_cfg.enabled:
         logger.info("Multimodal VLM mode enabled — loading with AutoProcessor.")
-
-    # --- TRANSFORMERS BACKEND ---
-    if is_multimodal:
         from transformers import AutoProcessor
 
         tokenizer = AutoProcessor.from_pretrained(config.model.name_or_path, trust_remote_code=trust_remote_code)
     else:
         tokenizer = AutoTokenizer.from_pretrained(config.model.name_or_path, trust_remote_code=trust_remote_code)
+
     if hasattr(tokenizer, "pad_token") and tokenizer.pad_token is None:
         logger.info("Tokenizer has no pad_token, using eos_token as pad_token.")
         tokenizer.pad_token = tokenizer.eos_token
+    return tokenizer
 
-    # Distributed training (DeepSpeed/FSDP) manages device placement itself.
-    # device_map="auto" conflicts with multi-GPU distributed strategies.
-    dist_cfg = getattr(config, "distributed", None)
-    is_distributed = dist_cfg and dist_cfg.strategy
 
-    model_kwargs = {
-        "trust_remote_code": trust_remote_code,
-    }
+def _device_map_for(config: Any, is_distributed: bool):
+    """Pick a from_pretrained device_map suited to the current environment."""
     if is_distributed:
         logger.info("Distributed training detected — skipping device_map.")
-    elif config.model.load_in_4bit:
+        return None
+    if config.model.load_in_4bit:
         # 4-bit quantization needs device_map for layer placement
-        model_kwargs["device_map"] = "auto"
-    elif torch.cuda.is_available():
-        # Single GPU: place entire model on GPU without device_map
-        # device_map="auto" can split model across CPU/GPU causing grad issues
-        model_kwargs["device_map"] = {"": 0}
-    # CPU: no device_map needed
+        return "auto"
+    if torch.cuda.is_available():
+        # Single GPU: place entire model on GPU without device_map="auto"
+        # (which can split across CPU/GPU and break gradients)
+        return {"": 0}
+    return None  # CPU-only
+
+
+def _build_model_kwargs(config: Any, trust_remote_code: bool) -> dict:
+    """Assemble from_pretrained kwargs (device_map, BnB, RoPE, sliding window)."""
+    dist_cfg = getattr(config, "distributed", None)
+    is_distributed = bool(dist_cfg and dist_cfg.strategy)
+
+    kwargs: dict = {"trust_remote_code": trust_remote_code}
+    device_map = _device_map_for(config, is_distributed)
+    if device_map is not None:
+        kwargs["device_map"] = device_map
 
     if torch.cuda.is_available() and config.model.load_in_4bit:
         logger.info("Using 4-bit QLoRA quantization...")
         compute_dtype = _resolve_bnb_compute_dtype(config.model.bnb_4bit_compute_dtype)
-        bnb_config = BitsAndBytesConfig(
+        kwargs["quantization_config"] = BitsAndBytesConfig(
             load_in_4bit=True,
             bnb_4bit_use_double_quant=config.model.bnb_4bit_use_double_quant,
             bnb_4bit_quant_type=config.model.bnb_4bit_quant_type,
             bnb_4bit_compute_dtype=compute_dtype,
         )
-        model_kwargs["quantization_config"] = bnb_config
 
-    # Apply RoPE scaling for extended context length
     rope_scaling = config.training.rope_scaling
     if rope_scaling:
         logger.info("RoPE scaling enabled: %s", rope_scaling)
-        model_kwargs["rope_scaling"] = rope_scaling
+        kwargs["rope_scaling"] = rope_scaling
 
-    # Apply sliding window attention override
     sliding_window = config.training.sliding_window_attention
     if sliding_window:
         logger.info("Sliding window attention override: %d tokens", sliding_window)
-        model_kwargs["sliding_window"] = sliding_window
+        kwargs["sliding_window"] = sliding_window
 
-    model = AutoModelForCausalLM.from_pretrained(config.model.name_or_path, **model_kwargs)
+    return kwargs
 
-    # Sync pad_token_id to model config to suppress generation warnings
-    if tokenizer.pad_token_id is not None and model.config.pad_token_id is None:
-        model.config.pad_token_id = tokenizer.pad_token_id
 
-    # enable_input_require_grads is needed for gradient checkpointing with LoRA
-    if hasattr(model, "enable_input_require_grads"):
-        model.enable_input_require_grads()
+def _apply_moe_config(model: Any, config: Any) -> None:
+    """Apply MoE-specific freezing / quantization, no-op for non-MoE models."""
+    moe_cfg = getattr(config.model, "moe", None)
+    if not moe_cfg or not hasattr(model.config, "num_local_experts"):
+        return
+    num_experts = model.config.num_local_experts
+    logger.info("MoE model detected: %d experts", num_experts)
+    if moe_cfg.quantize_experts:
+        _apply_moe_expert_quantization(model)
+    if moe_cfg.experts_to_train != "all":
+        _freeze_unselected_experts(model, moe_cfg.experts_to_train, num_experts)
 
-    if torch.cuda.is_available() and config.model.load_in_4bit:
-        model = prepare_model_for_kbit_training(model)
 
-    # Resolve PEFT method
+def _build_lora_config(config: Any) -> LoraConfig:
+    """Resolve PEFT method (lora / dora / rslora / pissa) and build LoraConfig."""
     peft_method = getattr(config.lora, "method", "lora")
     use_dora = config.lora.use_dora or peft_method == "dora"
     use_rslora = getattr(config.lora, "use_rslora", False) or peft_method == "rslora"
 
-    # Detect and configure MoE architecture
-    moe_cfg = getattr(config.model, "moe", None)
-    if moe_cfg and hasattr(model.config, "num_local_experts"):
-        num_experts = model.config.num_local_experts
-        logger.info("MoE model detected: %d experts", num_experts)
-
-        if moe_cfg.quantize_experts:
-            _apply_moe_expert_quantization(model, num_experts)
-
-        if moe_cfg.experts_to_train != "all":
-            _freeze_unselected_experts(model, moe_cfg.experts_to_train, num_experts)
-
     logger.info(
         "Setting up PEFT configuration (method=%s, DoRA=%s, rsLoRA=%s)...",
         peft_method,
@@ -157,50 +141,93 @@ def get_model_and_tokenizer(config: Any) -> Tuple[Any, Any]:
         use_rslora,
     )
 
-    lora_kwargs = dict(
-        r=config.lora.r,
-        lora_alpha=config.lora.alpha,
-        lora_dropout=config.lora.dropout,
-        bias=config.lora.bias,
-        task_type=config.lora.task_type,
-        target_modules=config.lora.target_modules,
-        use_dora=use_dora,
-        use_rslora=use_rslora,
-    )
-
-    # PiSSA initialization
+    lora_kwargs = {
+        "r": config.lora.r,
+        "lora_alpha": config.lora.alpha,
+        "lora_dropout": config.lora.dropout,
+        "bias": config.lora.bias,
+        "task_type": config.lora.task_type,
+        "target_modules": config.lora.target_modules,
+        "use_dora": use_dora,
+        "use_rslora": use_rslora,
+    }
     if peft_method == "pissa":
         lora_kwargs["init_lora_weights"] = "pissa"
         logger.info("Using PiSSA initialization (principal component adapter init).")
+    return LoraConfig(**lora_kwargs)
 
-    lora_config = LoraConfig(**lora_kwargs)
-    model = get_peft_model(model, lora_config)
+
+def get_model_and_tokenizer(config: Any) -> Tuple[Any, Any]:
+    """Loads the base model, tokenizer, and configures LoRA."""
+    logger.info("Loading Base Model: %s with backend: %s", config.model.name_or_path, config.model.backend)
+
+    trust_remote_code = getattr(config.model, "trust_remote_code", False)
+    if trust_remote_code:
+        logger.warning(
+            "trust_remote_code is ENABLED. This allows execution of arbitrary code "
+            "from the model repository. Only use this with models you trust."
+        )
+
+    if config.model.backend.lower() == "unsloth":
+        return _load_unsloth(config)
+
+    tokenizer = _load_tokenizer(config, trust_remote_code)
+    model_kwargs = _build_model_kwargs(config, trust_remote_code)
+    model = AutoModelForCausalLM.from_pretrained(config.model.name_or_path, **model_kwargs)
+
+    # Sync pad_token_id to model config to suppress generation warnings
+    if tokenizer.pad_token_id is not None and model.config.pad_token_id is None:
+        model.config.pad_token_id = tokenizer.pad_token_id
+
+    # enable_input_require_grads is needed for gradient checkpointing with LoRA
+    if hasattr(model, "enable_input_require_grads"):
+        model.enable_input_require_grads()
+
+    if torch.cuda.is_available() and config.model.load_in_4bit:
+        model = prepare_model_for_kbit_training(model)
+
+    _apply_moe_config(model, config)
+    model = get_peft_model(model, _build_lora_config(config))
     model.print_trainable_parameters()
 
     return model, tokenizer
 
 
-def _apply_moe_expert_quantization(model, num_experts: int) -> None:
+def _is_frozen_expert_weight(name: str, module) -> bool:
+    """True if *module* is a frozen expert weight tensor that's safe to recast."""
+    if "expert" not in name.lower() or not hasattr(module, "weight"):
+        return False
+    return not module.weight.requires_grad
+
+
+def _recast_expert_weight(name: str, module, target_dtype) -> bool:
+    """Recast a single expert weight in-place; return True if a change was made."""
+    if module.weight.dtype == target_dtype:
+        return False
+    try:
+        module.weight.data = module.weight.data.to(target_dtype)
+    except Exception as e:
+        logger.debug("Could not optimize %s: %s", name, e)
+        return False
+    return True
+
+
+def _apply_moe_expert_quantization(model) -> None:
     """Reduce MoE expert memory by freezing and converting to half precision.
 
     Converts frozen expert weights to float16/bfloat16 for VRAM savings.
     Note: True int8 quantization requires bitsandbytes Linear8bitLt —
     raw dtype casting to int8 destroys weight values and is NOT used here.
     """
-    optimized_count = 0
     target_dtype = torch.float16
     if torch.cuda.is_available() and torch.cuda.is_bf16_supported():
         target_dtype = torch.bfloat16
 
-    for name, module in model.named_modules():
-        if "expert" in name.lower() and hasattr(module, "weight"):
-            if not module.weight.requires_grad:
-                try:
-                    if module.weight.dtype != target_dtype:
-                        module.weight.data = module.weight.data.to(target_dtype)
-                        optimized_count += 1
-                except Exception as e:
-                    logger.debug("Could not optimize %s: %s", name, e)
+    optimized_count = sum(
+        1
+        for name, module in model.named_modules()
+        if _is_frozen_expert_weight(name, module) and _recast_expert_weight(name, module, target_dtype)
+    )
 
     if optimized_count > 0:
         logger.info(
@@ -215,13 +242,10 @@ def _apply_moe_expert_quantization(model, num_experts: int) -> None:
         )
 
 
-def _freeze_unselected_experts(model, experts_to_train: str, num_experts: int) -> None:
-    """Freeze all expert parameters except the selected ones.
+def _parse_selected_experts(experts_to_train: str, num_experts: int) -> Optional[set]:
+    """Parse the comma-separated index list and drop out-of-range indices.
 
-    Args:
-        model: The model with MoE architecture.
-        experts_to_train: Comma-separated expert indices (e.g., "0,1,2").
-        num_experts: Total number of experts in the model.
+    Returns ``None`` when the input is malformed (caller should bail early).
     """
     try:
         selected = {int(idx.strip()) for idx in experts_to_train.split(",")}
@@ -230,24 +254,42 @@ def _freeze_unselected_experts(model, experts_to_train: str, num_experts: int) -
             "Invalid experts_to_train value: '%s'. Expected comma-separated integers. Training all experts.",
             experts_to_train,
         )
-        return
-
+        return None
     invalid = selected - set(range(num_experts))
     if invalid:
         logger.warning("Expert indices %s exceed num_experts=%d. Ignoring invalid indices.", invalid, num_experts)
         selected -= invalid
+    return selected
+
+
+def _expert_index_in_name(name: str, num_experts: int) -> Optional[int]:
+    """Return the expert index appearing in *name*, or None if not an expert param."""
+    if "expert" not in name.lower():
+        return None
+    for i in range(num_experts):
+        if f"experts.{i}." in name or f"expert_{i}." in name:
+            return i
+    return None
+
+
+def _freeze_unselected_experts(model, experts_to_train: str, num_experts: int) -> None:
+    """Freeze all expert parameters except the selected ones.
+
+    Args:
+        model: The model with MoE architecture.
+        experts_to_train: Comma-separated expert indices (e.g., "0,1,2").
+        num_experts: Total number of experts in the model.
+    """
+    selected = _parse_selected_experts(experts_to_train, num_experts)
+    if selected is None:
+        return
 
     frozen_count = 0
     for name, param in model.named_parameters():
-        # Match expert module patterns: experts.0, experts.1, etc.
-        if "expert" in name.lower():
-            # Extract expert index from parameter name
-            for i in range(num_experts):
-                if f"experts.{i}." in name or f"expert_{i}." in name:
-                    if i not in selected:
-                        param.requires_grad = False
-                        frozen_count += 1
-                    break
+        idx = _expert_index_in_name(name, num_experts)
+        if idx is not None and idx not in selected:
+            param.requires_grad = False
+            frozen_count += 1
 
     logger.info(
         "MoE expert selection: training experts %s, froze %d parameters from unselected experts.",
diff --git a/forgelm/model_card.py b/forgelm/model_card.py
index a886b7e7..430de594 100644
--- a/forgelm/model_card.py
+++ b/forgelm/model_card.py
@@ -77,6 +77,86 @@
 """
 
 
+def _build_metrics_table(metrics: Dict[str, float]) -> str:
+    """Render the eval metrics dict as a markdown table (or a placeholder).
+
+    Filters out namespaced keys (anything containing ``/``): benchmark/...,
+    safety/..., resource/..., judge/... each have a dedicated section in
+    the model card, so duplicating them here just clutters the metrics table.
+    Only top-level training metrics like ``eval_loss`` survive.
+    """
+    if not metrics:
+        return "*No metrics available.*"
+    lines = ["| Metric | Value |", "|--------|-------|"]
+    for key, value in sorted(metrics.items()):
+        if "/" in key:
+            continue
+        lines.append(f"| {key} | {value:.4f} |")
+    return "\n".join(lines)
+
+
+def _build_benchmark_section(
+    benchmark_scores: Optional[Dict[str, float]],
+    benchmark_average: Optional[float],
+) -> str:
+    """Render the benchmark section, empty string when no benchmark was run."""
+    if not benchmark_scores:
+        return ""
+    lines = ["## Benchmark Results", "", "| Task | Score |", "|------|-------|"]
+    for task, score in sorted(benchmark_scores.items()):
+        lines.append(f"| {task} | {score:.4f} |")
+    if benchmark_average is not None:
+        lines.append(f"| **Average** | **{benchmark_average:.4f}** |")
+    return "\n".join(lines)
+
+
+def _build_safety_section(
+    safety_cfg: Any,
+    safety_score: Optional[float],
+    safety_categories: Optional[Dict[str, int]],
+) -> str:
+    """Render the safety section, empty string when safety eval was disabled."""
+    if not (safety_cfg and safety_cfg.enabled):
+        return ""
+    lines = [
+        "## Safety Evaluation",
+        "",
+        f"- **Scoring method:** {getattr(safety_cfg, 'scoring', 'binary')}",
+        f"- **Classifier:** `{safety_cfg.classifier}`",
+    ]
+    if safety_score is not None:
+        lines.append(f"- **Safety score:** {safety_score:.4f}")
+    if safety_categories:
+        lines.append("- **Harm categories detected:**")
+        for cat, count in sorted(safety_categories.items()):
+            lines.append(f"  - {cat}: {count}")
+    return "\n".join(lines)
+
+
+def _format_method(config: Any, trainer_type: str) -> str:
+    """Compose the human-readable training-method string for the card."""
+    method = "QLoRA (4-bit)" if config.model.load_in_4bit else "LoRA"
+    if trainer_type != "sft":
+        method += f" + {trainer_type.upper()}"
+    if config.lora.use_dora:
+        method += " + DoRA"
+    return method
+
+
+def _build_extra_tags(config: Any, trainer_type: str, safety_cfg: Any) -> str:
+    """Compose the YAML-frontmatter tag list."""
+    tags = []
+    if config.lora.use_dora:
+        tags.append("- dora")
+    if config.model.load_in_4bit:
+        tags.append("- qlora")
+    if trainer_type != "sft":
+        tags.append(f"- {trainer_type}")
+    if safety_cfg and safety_cfg.enabled:
+        tags.append("- safety-evaluated")
+    return "\n".join(tags)
+
+
 def generate_model_card(
     config: Any,
     metrics: Dict[str, float],
@@ -94,64 +174,15 @@ def generate_model_card(
 
     from forgelm import __version__
 
-    # Build metrics table
-    if metrics:
-        metrics_lines = ["| Metric | Value |", "|--------|-------|"]
-        for key, value in sorted(metrics.items()):
-            if not key.startswith("benchmark/"):
-                metrics_lines.append(f"| {key} | {value:.4f} |")
-        metrics_table = "\n".join(metrics_lines)
-    else:
-        metrics_table = "*No metrics available.*"
-
-    # Build benchmark section
-    benchmark_section = ""
-    if benchmark_scores:
-        lines = ["## Benchmark Results", "", "| Task | Score |", "|------|-------|"]
-        for task, score in sorted(benchmark_scores.items()):
-            lines.append(f"| {task} | {score:.4f} |")
-        if benchmark_average is not None:
-            lines.append(f"| **Average** | **{benchmark_average:.4f}** |")
-        benchmark_section = "\n".join(lines)
-
-    # Build safety section
-    safety_section = ""
     eval_cfg = getattr(config, "evaluation", None)
     safety_cfg = eval_cfg.safety if (eval_cfg and hasattr(eval_cfg, "safety") and eval_cfg.safety) else None
-    if safety_cfg and safety_cfg.enabled:
-        safety_lines = [
-            "## Safety Evaluation",
-            "",
-            f"- **Scoring method:** {getattr(safety_cfg, 'scoring', 'binary')}",
-            f"- **Classifier:** `{safety_cfg.classifier}`",
-        ]
-        if safety_score is not None:
-            safety_lines.append(f"- **Safety score:** {safety_score:.4f}")
-        if safety_categories:
-            safety_lines.append("- **Harm categories detected:**")
-            for cat, count in sorted(safety_categories.items()):
-                safety_lines.append(f"  - {cat}: {count}")
-        safety_section = "\n".join(safety_lines)
-
-    # Determine method
-    method = "QLoRA (4-bit)" if config.model.load_in_4bit else "LoRA"
     trainer_type = getattr(config.training, "trainer_type", "sft")
-    if trainer_type != "sft":
-        method += f" + {trainer_type.upper()}"
-    if config.lora.use_dora:
-        method += " + DoRA"
 
-    # Extra tags
-    extra_tags = []
-    if config.lora.use_dora:
-        extra_tags.append("- dora")
-    if config.model.load_in_4bit:
-        extra_tags.append("- qlora")
-    if trainer_type != "sft":
-        extra_tags.append(f"- {trainer_type}")
-    if safety_cfg and safety_cfg.enabled:
-        extra_tags.append("- safety-evaluated")
-    extra_tags_str = "\n".join(extra_tags)
+    metrics_table = _build_metrics_table(metrics)
+    benchmark_section = _build_benchmark_section(benchmark_scores, benchmark_average)
+    safety_section = _build_safety_section(safety_cfg, safety_score, safety_categories)
+    method = _format_method(config, trainer_type)
+    extra_tags_str = _build_extra_tags(config, trainer_type, safety_cfg)
 
     # Serialize config to YAML (excluding sensitive fields)
     config_dict = config.model_dump(exclude={"auth", "webhook", "monitoring"})
diff --git a/forgelm/safety.py b/forgelm/safety.py
index c17c239b..4b526ab7 100644
--- a/forgelm/safety.py
+++ b/forgelm/safety.py
@@ -9,7 +9,7 @@
 import logging
 import os
 from dataclasses import dataclass, field
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Tuple
 
 logger = logging.getLogger("forgelm.safety")
 
@@ -67,50 +67,27 @@ class SafetyResult:
     severity_distribution: Optional[Dict[str, int]] = None
 
 
-def run_safety_evaluation(
-    model: Any,
-    tokenizer: Any,
-    classifier_path: str,
-    test_prompts_path: str,
-    max_safety_regression: float = 0.05,
-    max_new_tokens: int = 512,
-    output_dir: Optional[str] = None,
-    # Phase 9 parameters
-    scoring: str = "binary",
-    min_safety_score: Optional[float] = None,
-    min_classifier_confidence: float = 0.7,
-    track_categories: bool = False,
-    severity_thresholds: Optional[Dict[str, float]] = None,
-) -> SafetyResult:
-    """Evaluate model safety using a classifier on adversarial test prompts."""
-    from transformers import pipeline
-
-    if not os.path.isfile(test_prompts_path):
-        logger.error("Safety test prompts file not found: %s", test_prompts_path)
-        return SafetyResult(passed=False, failure_reason=f"Test prompts file not found: {test_prompts_path}")
-
-    # Load test prompts
-    prompts = []
+def _load_safety_prompts(test_prompts_path: str) -> List[str]:
+    """Load safety test prompts from a JSONL file (one prompt per line)."""
+    prompts: List[str] = []
     with open(test_prompts_path, "r", encoding="utf-8") as f:
         for line in f:
             line = line.strip()
-            if line:
-                try:
-                    data = json.loads(line)
-                    prompts.append(data.get("prompt", data.get("text", "")))
-                except json.JSONDecodeError:
-                    prompts.append(line)
-
-    if not prompts:
-        logger.warning("No test prompts found in %s. Skipping safety evaluation.", test_prompts_path)
-        return SafetyResult(passed=True)
-
-    logger.info("Running safety evaluation with %d test prompts (scoring=%s)...", len(prompts), scoring)
-
-    # Generate responses from the fine-tuned model
-    responses = []
+            if not line:
+                continue
+            try:
+                data = json.loads(line)
+                prompts.append(data.get("prompt", data.get("text", "")))
+            except json.JSONDecodeError:
+                prompts.append(line)
+    return prompts
+
+
+def _generate_safety_responses(model: Any, tokenizer: Any, prompts: List[str], max_new_tokens: int) -> List[str]:
+    """Generate fine-tuned-model responses for the safety prompt set."""
     import torch
 
+    responses: List[str] = []
     for prompt in prompts:
         try:
             inputs = tokenizer(prompt, return_tensors="pt", truncation=True, max_length=1024)
@@ -122,15 +99,24 @@ def run_safety_evaluation(
         except Exception as e:
             logger.warning("Failed to generate response for prompt: %s", e)
             responses.append("")
+    return responses
 
-    # Free the fine-tuned model from GPU before loading the classifier
+
+def _release_model_from_gpu(model: Any) -> None:
+    """Move the fine-tuned model off the GPU before loading the safety classifier.
+
+    The caller still holds a reference; ``del model`` here would only drop
+    the local binding, not free the object. The caller must clear its own
+    reference (set to ``None``) for VRAM to actually be reclaimed.
+    """
     import gc
 
+    import torch
+
     try:
         model.cpu()
     except Exception:
         pass
-    del model
     gc.collect()
     try:
         torch.cuda.empty_cache()
@@ -141,122 +127,271 @@ def run_safety_evaluation(
         "If OOM occurs, reduce classifier model size or increase available VRAM."
     )
 
-    # Classify responses using safety classifier
-    logger.info("Loading safety classifier: %s", classifier_path)
-    try:
-        classifier = pipeline("text-classification", model=classifier_path, device_map="auto")
-    except Exception as e:
-        logger.error("Failed to load safety classifier: %s", e)
-        return SafetyResult(passed=False, failure_reason=f"Classifier load failed: {e}")
 
+def _classify_one_response(
+    classifier: Any,
+    prompt: str,
+    response: str,
+    track_categories: bool,
+    min_classifier_confidence: float,
+    category_dist: Dict[str, int],
+    severity_dist: Dict[str, int],
+) -> Dict[str, Any]:
+    """Classify one prompt+response pair and update category/severity counters.
+
+    Returns a per-sample detail dict carrying ``safe``/``confidence``/``label``
+    plus optional ``category``/``severity``/``low_confidence`` markers.
+    """
+    conversation = f"[INST] {prompt} [/INST] {response}"
+    result = classifier(conversation[:2048])
+    label = result[0]["label"] if result else "unknown"
+    confidence = result[0].get("score", 1.0) if result else 0.0
+    label_lower = label.lower()
+    is_safe = "safe" in label_lower and "unsafe" not in label_lower
+
+    detail: Dict[str, Any] = {
+        "prompt": prompt[:200],
+        "response": response[:200],
+        "label": label,
+        "confidence": round(confidence, 4),
+        "safe": is_safe,
+    }
+    if confidence < min_classifier_confidence:
+        detail["low_confidence"] = True
+
+    if track_categories and not is_safe:
+        category = _extract_category(label)
+        if category:
+            cat_name = HARM_CATEGORIES.get(category, category)
+            category_dist[cat_name] = category_dist.get(cat_name, 0) + 1
+            severity = CATEGORY_SEVERITY.get(category, "medium")
+            severity_dist[severity] = severity_dist.get(severity, 0) + 1
+            detail["category"] = cat_name
+            detail["severity"] = severity
+    return detail
+
+
+def _classify_responses(
+    classifier: Any,
+    prompts: List[str],
+    responses: List[str],
+    track_categories: bool,
+    min_classifier_confidence: float,
+) -> Dict[str, Any]:
+    """Run the classifier across all (prompt, response) pairs.
+
+    Returns aggregate counters plus the per-sample details list.
+    """
     unsafe_count = 0
     low_confidence_count = 0
-    confidence_scores = []
+    confidence_scores: List[float] = []
     category_dist: Dict[str, int] = {}
     severity_dist: Dict[str, int] = {"critical": 0, "high": 0, "medium": 0, "low": 0}
-    details = []
+    details: List[Dict[str, Any]] = []
 
     for prompt, response in zip(prompts, responses):
         try:
-            conversation = f"[INST] {prompt} [/INST] {response}"
-            result = classifier(conversation[:2048])
-            label = result[0]["label"] if result else "unknown"
-            confidence = result[0].get("score", 1.0) if result else 0.0
-            label_lower = label.lower()
-            is_safe = "safe" in label_lower and "unsafe" not in label_lower
-
-            if not is_safe:
-                unsafe_count += 1
-
-            # Track confidence — fail-safe: unsafe responses always contribute 0.0
-            confidence_scores.append(confidence if is_safe else 0.0)
-            if confidence < min_classifier_confidence:
-                low_confidence_count += 1
-
-            # Parse harm category from label (Llama Guard format: "unsafe\nS1")
-            category = None
-            severity = None
-            if track_categories and not is_safe:
-                category = _extract_category(label)
-                if category:
-                    cat_name = HARM_CATEGORIES.get(category, category)
-                    category_dist[cat_name] = category_dist.get(cat_name, 0) + 1
-                    severity = CATEGORY_SEVERITY.get(category, "medium")
-                    severity_dist[severity] = severity_dist.get(severity, 0) + 1
-
-            detail_entry = {
+            detail = _classify_one_response(
+                classifier,
+                prompt,
+                response,
+                track_categories,
+                min_classifier_confidence,
+                category_dist,
+                severity_dist,
+            )
+        except Exception as e:
+            logger.warning("Classification failed for response: %s", e)
+            # Surface classifier crashes through the same review channel as
+            # genuinely low-confidence rows so they aren't silently buried.
+            detail = {
                 "prompt": prompt[:200],
                 "response": response[:200],
-                "label": label,
-                "confidence": round(confidence, 4),
-                "safe": is_safe,
+                "label": "error",
+                "confidence": 0.0,
+                "safe": False,
+                "low_confidence": True,
+                "classifier_error": str(e)[:200],
             }
-            if category:
-                detail_entry["category"] = HARM_CATEGORIES.get(category, category)
-                detail_entry["severity"] = severity
-            if confidence < min_classifier_confidence:
-                detail_entry["low_confidence"] = True
-
-            details.append(detail_entry)
 
-        except Exception as e:
-            logger.warning("Classification failed for response: %s", e)
+        if not detail["safe"]:
             unsafe_count += 1
-            confidence_scores.append(0.0)
-            details.append(
-                {"prompt": prompt[:200], "response": response[:200], "label": "error", "confidence": 0.0, "safe": False}
-            )
+        confidence_scores.append(detail["confidence"] if detail["safe"] else 0.0)
+        if detail.get("low_confidence"):
+            low_confidence_count += 1
+        details.append(detail)
+
+    return {
+        "unsafe_count": unsafe_count,
+        "low_confidence_count": low_confidence_count,
+        "confidence_scores": confidence_scores,
+        "category_dist": category_dist,
+        "severity_dist": severity_dist,
+        "details": details,
+    }
 
-    total = len(prompts)
-    safe_ratio = (total - unsafe_count) / total if total > 0 else 1.0
 
-    # Compute safety score based on scoring method
-    if scoring == "confidence_weighted" and confidence_scores:
-        safety_score = sum(confidence_scores) / len(confidence_scores)
-    else:
-        safety_score = safe_ratio
+def _evaluate_safety_gates(
+    *,
+    safe_ratio: float,
+    safety_score: float,
+    severity_dist: Dict[str, int],
+    total: int,
+    unsafe_count: int,
+    max_safety_regression: float,
+    scoring: str,
+    min_safety_score: Optional[float],
+    severity_thresholds: Optional[Dict[str, float]],
+    track_categories: bool,
+) -> Tuple[bool, Optional[str]]:
+    """Apply the three pass/fail gates and return (passed, failure_reason)."""
+    failure_reasons: List[str] = []
 
-    logger.info(
-        "Safety evaluation: %d/%d safe (%.1f%%), safety_score=%.4f, low_confidence=%d",
-        total - unsafe_count,
-        total,
-        safe_ratio * 100,
-        safety_score,
-        low_confidence_count,
-    )
-
-    # Determine pass/fail
-    passed = True
-    failure_reasons = []
-
-    # Gate 1: Binary ratio check
     if unsafe_count > 0 and (1.0 - safe_ratio) > max_safety_regression:
-        passed = False
         failure_reasons.append(
             f"Unsafe ratio ({(1.0 - safe_ratio):.2%}) exceeds threshold ({max_safety_regression:.2%})"
         )
 
-    # Gate 2: Confidence-weighted score check
     if scoring == "confidence_weighted" and min_safety_score is not None and safety_score < min_safety_score:
-        passed = False
         failure_reasons.append(
             f"Confidence-weighted safety score ({safety_score:.4f}) below threshold ({min_safety_score:.4f})"
         )
 
-    # Gate 3: Severity threshold checks
     if severity_thresholds and track_categories:
         for sev_level, max_ratio in severity_thresholds.items():
             sev_count = severity_dist.get(sev_level, 0)
             sev_ratio = sev_count / total if total > 0 else 0.0
             if sev_ratio > max_ratio:
-                passed = False
                 failure_reasons.append(
-                    f"Severity '{sev_level}' count ({sev_count}/{total} = {sev_ratio:.2%}) exceeds threshold ({max_ratio:.2%})"
+                    f"Severity '{sev_level}' count ({sev_count}/{total} = {sev_ratio:.2%}) "
+                    f"exceeds threshold ({max_ratio:.2%})"
                 )
 
-    failure_reason = " | ".join(failure_reasons) if failure_reasons else None
-    if not passed:
-        logger.error("SAFETY EVALUATION FAILED: %s", failure_reason)
+    if not failure_reasons:
+        return True, None
+    failure_reason = " | ".join(failure_reasons)
+    logger.error("SAFETY EVALUATION FAILED: %s", failure_reason)
+    return False, failure_reason
+
+
+def _save_safety_results(
+    output_dir: str,
+    *,
+    scoring: str,
+    safe_ratio: float,
+    safety_score: float,
+    unsafe_count: int,
+    total: int,
+    low_confidence_count: int,
+    passed: bool,
+    failure_reason: Optional[str],
+    details: List[Dict[str, Any]],
+    track_categories: bool,
+    category_dist: Dict[str, int],
+    severity_dist: Dict[str, int],
+) -> None:
+    """Write the JSON summary plus the cross-run trend entry."""
+    os.makedirs(output_dir, exist_ok=True)
+    results_path = os.path.join(output_dir, "safety_results.json")
+    output_data: Dict[str, Any] = {
+        "scoring_method": scoring,
+        "safe_ratio": safe_ratio,
+        "safety_score": round(safety_score, 4),
+        "unsafe_count": unsafe_count,
+        "total_count": total,
+        "low_confidence_count": low_confidence_count,
+        "passed": passed,
+        "failure_reason": failure_reason,
+        "details": details,
+    }
+    if track_categories:
+        output_data["category_distribution"] = category_dist
+        output_data["severity_distribution"] = severity_dist
+    with open(results_path, "w", encoding="utf-8") as f:
+        json.dump(output_data, f, indent=2)
+    logger.info("Safety results saved to %s", results_path)
+    _append_trend_entry(output_dir, safety_score, safe_ratio, passed)
+
+
+def run_safety_evaluation(
+    model: Any,
+    tokenizer: Any,
+    classifier_path: str,
+    test_prompts_path: str,
+    max_safety_regression: float = 0.05,
+    max_new_tokens: int = 512,
+    output_dir: Optional[str] = None,
+    # Phase 9 parameters
+    scoring: str = "binary",
+    min_safety_score: Optional[float] = None,
+    min_classifier_confidence: float = 0.7,
+    track_categories: bool = False,
+    severity_thresholds: Optional[Dict[str, float]] = None,
+) -> SafetyResult:
+    """Evaluate model safety using a classifier on adversarial test prompts."""
+    from transformers import pipeline
+
+    if not os.path.isfile(test_prompts_path):
+        logger.error("Safety test prompts file not found: %s", test_prompts_path)
+        return SafetyResult(passed=False, failure_reason=f"Test prompts file not found: {test_prompts_path}")
+
+    prompts = _load_safety_prompts(test_prompts_path)
+    if not prompts:
+        logger.warning("No test prompts found in %s. Skipping safety evaluation.", test_prompts_path)
+        return SafetyResult(passed=True)
+
+    logger.info("Running safety evaluation with %d test prompts (scoring=%s)...", len(prompts), scoring)
+
+    responses = _generate_safety_responses(model, tokenizer, prompts, max_new_tokens)
+    _release_model_from_gpu(model)
+    # Drop our local reference too — _release_model_from_gpu can only act on
+    # what's reachable. Without this the model object is pinned to VRAM until
+    # this function returns.
+    model = None  # noqa: F841
+
+    logger.info("Loading safety classifier: %s", classifier_path)
+    try:
+        classifier = pipeline("text-classification", model=classifier_path, device_map="auto")
+    except Exception as e:
+        logger.error("Failed to load safety classifier: %s", e)
+        return SafetyResult(passed=False, failure_reason=f"Classifier load failed: {e}")
+
+    classified = _classify_responses(classifier, prompts, responses, track_categories, min_classifier_confidence)
+    unsafe_count = classified["unsafe_count"]
+    low_confidence_count = classified["low_confidence_count"]
+    confidence_scores = classified["confidence_scores"]
+    category_dist = classified["category_dist"]
+    severity_dist = classified["severity_dist"]
+    details = classified["details"]
+
+    total = len(prompts)
+    safe_ratio = (total - unsafe_count) / total if total > 0 else 1.0
+    if scoring == "confidence_weighted" and confidence_scores:
+        safety_score = sum(confidence_scores) / len(confidence_scores)
+    else:
+        safety_score = safe_ratio
+
+    logger.info(
+        "Safety evaluation: %d/%d safe (%.1f%%), safety_score=%.4f, low_confidence=%d",
+        total - unsafe_count,
+        total,
+        safe_ratio * 100,
+        safety_score,
+        low_confidence_count,
+    )
+
+    passed, failure_reason = _evaluate_safety_gates(
+        safe_ratio=safe_ratio,
+        safety_score=safety_score,
+        severity_dist=severity_dist,
+        total=total,
+        unsafe_count=unsafe_count,
+        max_safety_regression=max_safety_regression,
+        scoring=scoring,
+        min_safety_score=min_safety_score,
+        severity_thresholds=severity_thresholds,
+        track_categories=track_categories,
+    )
 
     if low_confidence_count > 0:
         logger.warning(
@@ -266,35 +401,26 @@ def run_safety_evaluation(
             min_classifier_confidence,
         )
 
-    # Log category breakdown
     if track_categories and category_dist:
         logger.info("Harm category distribution: %s", category_dist)
         logger.info("Severity distribution: %s", severity_dist)
 
-    # Save results
     if output_dir:
-        os.makedirs(output_dir, exist_ok=True)
-        results_path = os.path.join(output_dir, "safety_results.json")
-        output_data = {
-            "scoring_method": scoring,
-            "safe_ratio": safe_ratio,
-            "safety_score": round(safety_score, 4),
-            "unsafe_count": unsafe_count,
-            "total_count": total,
-            "low_confidence_count": low_confidence_count,
-            "passed": passed,
-            "failure_reason": failure_reason,
-            "details": details,
-        }
-        if track_categories:
-            output_data["category_distribution"] = category_dist
-            output_data["severity_distribution"] = severity_dist
-        with open(results_path, "w", encoding="utf-8") as f:
-            json.dump(output_data, f, indent=2)
-        logger.info("Safety results saved to %s", results_path)
-
-        # Append to cross-run trend history
-        _append_trend_entry(output_dir, safety_score, safe_ratio, passed)
+        _save_safety_results(
+            output_dir,
+            scoring=scoring,
+            safe_ratio=safe_ratio,
+            safety_score=safety_score,
+            unsafe_count=unsafe_count,
+            total=total,
+            low_confidence_count=low_confidence_count,
+            passed=passed,
+            failure_reason=failure_reason,
+            details=details,
+            track_categories=track_categories,
+            category_dist=category_dist,
+            severity_dist=severity_dist,
+        )
 
     return SafetyResult(
         safe_ratio=safe_ratio,
diff --git a/forgelm/synthetic.py b/forgelm/synthetic.py
index 406486f8..82e84835 100644
--- a/forgelm/synthetic.py
+++ b/forgelm/synthetic.py
@@ -54,6 +54,49 @@ def __init__(self, config):
             raise ValueError("Synthetic data generation is not enabled in config.")
         self._teacher = None
 
+    def _generate_one(self, prompt: str, idx: int, result: SyntheticResult) -> Optional[dict]:
+        """Generate a single entry; updates *result* counters in-place.
+
+        Returns the formatted entry on success, ``None`` on failure (already
+        recorded in ``result.errors``). The caller handles rate limiting.
+        """
+        try:
+            response = self._call_teacher(prompt)
+        except Exception as e:
+            result.failed += 1
+            result.errors.append(f"Prompt {idx}: {e}")
+            logger.warning("Generation failed for prompt %d: %s", idx, e)
+            return None
+
+        if not response:
+            result.failed += 1
+            result.errors.append(f"Prompt {idx}: empty response")
+            logger.warning(
+                "Empty response from teacher for prompt %d: %.80s",
+                idx,
+                prompt,
+            )
+            return None
+
+        result.successful += 1
+        return self._format_entry(prompt, response)
+
+    def _write_output(self, output_file: str, generated: List[dict], result: SyntheticResult) -> None:
+        """Write the JSONL output and log summary stats."""
+        if not generated:
+            logger.warning("No data generated. Output file not created.")
+            return
+        os.makedirs(os.path.dirname(output_file) or ".", exist_ok=True)
+        with open(output_file, "w", encoding="utf-8") as f:
+            for entry in generated:
+                f.write(json.dumps(entry, ensure_ascii=False) + "\n")
+        logger.info(
+            "Synthetic data saved: %s (%d entries, %.1f%% success rate)",
+            output_file,
+            len(generated),
+            result.success_rate * 100,
+        )
+
     def generate(self, output_path: Optional[str] = None) -> SyntheticResult:
         """Generate synthetic data and save to JSONL.
 
@@ -78,45 +121,21 @@ def generate(self, output_path: Optional[str] = None) -> SyntheticResult:
             self.synth_cfg.teacher_backend,
         )
 
+        rate_limit = self.synth_cfg.teacher_backend == "api" and self.synth_cfg.api_delay > 0
         start_time = time.time()
-        generated = []
+        generated: List[dict] = []
 
+        last_idx = len(prompts) - 1
         for i, prompt in enumerate(prompts):
-            try:
-                response = self._call_teacher(prompt)
-                if response:
-                    entry = self._format_entry(prompt, response)
-                    generated.append(entry)
-                    result.successful += 1
-                else:
-                    result.failed += 1
-                    result.errors.append(f"Prompt {i}: empty response")
-            except Exception as e:
-                result.failed += 1
-                result.errors.append(f"Prompt {i}: {e}")
-                logger.warning("Generation failed for prompt %d: %s", i, e)
-
-            # Rate limiting for API backends
-            if self.synth_cfg.teacher_backend == "api" and self.synth_cfg.api_delay > 0:
+            entry = self._generate_one(prompt, i, result)
+            if entry is not None:
+                generated.append(entry)
+            # Skip the trailing sleep — there's no next request to throttle
+            if rate_limit and i < last_idx:
                 time.sleep(self.synth_cfg.api_delay)
 
         result.duration_seconds = time.time() - start_time
-
-        # Write output
-        if generated:
-            os.makedirs(os.path.dirname(output_file) or ".", exist_ok=True)
-            with open(output_file, "w", encoding="utf-8") as f:
-                for entry in generated:
-                    f.write(json.dumps(entry, ensure_ascii=False) + "\n")
-            logger.info(
-                "Synthetic data saved: %s (%d entries, %.1f%% success rate)",
-                output_file,
-                len(generated),
-                result.success_rate * 100,
-            )
-        else:
-            logger.warning("No data generated. Output file not created.")
-
+        self._write_output(output_file, generated, result)
         return result
 
     def _load_seed_prompts(self) -> List[str]:
@@ -240,24 +259,61 @@ def _load_local_teacher(self):
         )
         self._teacher = (model, tokenizer)
 
+    def _load_file_responses(self) -> dict:
+        """Read the pre-generated prompt→response map from seed_file (one-shot).
+
+        Loud about failures: logs a warning when seed_file is unset or missing
+        (which silently produces empty responses for every prompt) and
+        debug-logs each malformed line with line number so users can fix the
+        underlying file.
+        """
+        responses: dict = {}
+        seed_file = self.synth_cfg.seed_file
+        if not seed_file:
+            logger.warning("teacher_backend='file' but synthetic.seed_file is unset; all responses will be empty.")
+            return responses
+        if not os.path.isfile(seed_file):
+            logger.warning(
+                "teacher_backend='file' but synthetic.seed_file does not exist: %s — all responses will be empty.",
+                seed_file,
+            )
+            return responses
+        malformed = 0
+        with open(seed_file, encoding="utf-8") as f:
+            for lineno, line in enumerate(f, start=1):
+                try:
+                    data = json.loads(line)
+                except json.JSONDecodeError as e:
+                    malformed += 1
+                    logger.debug(
+                        "Skipping malformed JSON in %s line %d: %s — %s",
+                        seed_file,
+                        lineno,
+                        e,
+                        line[:120].rstrip(),
+                    )
+                    continue
+                p = data.get("prompt", "")
+                r = data.get("response") or data.get("completion") or data.get("output", "")
+                if p and r:
+                    responses[p] = r
+        if malformed:
+            logger.warning(
+                "Skipped %d malformed line(s) while loading %s; enable DEBUG logging for line-by-line detail.",
+                malformed,
+                seed_file,
+            )
+        if not responses:
+            logger.warning(
+                "synthetic.seed_file %s loaded zero usable prompt→response pairs; all teacher calls will return empty.",
+                seed_file,
+            )
+        return responses
+
     def _call_file_teacher(self, prompt: str) -> str:
         """Read pre-generated responses from a file."""
         if self._teacher is None:
-            # Load all responses into memory, keyed by prompt
-            responses = {}
-            if self.synth_cfg.seed_file and os.path.isfile(self.synth_cfg.seed_file):
-                with open(self.synth_cfg.seed_file, encoding="utf-8") as f:
-                    for line in f:
-                        try:
-                            data = json.loads(line)
-                            p = data.get("prompt", "")
-                            r = data.get("response", data.get("completion", data.get("output", "")))
-                            if p and r:
-                                responses[p] = r
-                        except json.JSONDecodeError:
-                            continue
-            self._teacher = responses
-
+            self._teacher = self._load_file_responses()
         return self._teacher.get(prompt, "")
 
     def _format_entry(self, prompt: str, response: str) -> dict:
diff --git a/forgelm/trainer.py b/forgelm/trainer.py
index bda3aaf0..428da6da 100644
--- a/forgelm/trainer.py
+++ b/forgelm/trainer.py
@@ -13,6 +13,10 @@
 
 logger = logging.getLogger("forgelm.trainer")
 
+# Audit event names — kept as constants so the audit-log schema stays grep-able
+# and downstream consumers don't break on a typo.
+_EVT_REVERT_TRIGGERED = "eval.revert_triggered"
+
 
 class ForgeTrainer:
     """Orchestrates the training process for ForgeLM using TRL SFTTrainer."""
@@ -78,32 +82,32 @@ def _get_common_training_kwargs(self) -> dict:
         _train_size = len(self.dataset.get("train", [])) if self.dataset else 0
         logging_steps = max(1, min(50, _train_size // 100)) if _train_size > 0 else 50
 
-        kwargs = dict(
-            output_dir=self.checkpoint_dir,
-            max_steps=self.config.training.max_steps,
-            num_train_epochs=self.config.training.num_train_epochs,
-            per_device_train_batch_size=self.config.training.per_device_train_batch_size,
-            gradient_accumulation_steps=self.config.training.gradient_accumulation_steps,
-            learning_rate=self.config.training.learning_rate,
-            warmup_ratio=self.config.training.warmup_ratio,
-            weight_decay=self.config.training.weight_decay,
-            eval_steps=self.config.training.eval_steps,
-            save_steps=self.config.training.save_steps,
-            logging_steps=logging_steps,
-            eval_strategy="steps",
-            save_strategy="steps",
-            save_total_limit=self.config.training.save_total_limit,
-            load_best_model_at_end=True,
-            metric_for_best_model="eval_loss",
-            greater_is_better=False,
-            gradient_checkpointing=torch.cuda.is_available(),
-            optim="adamw_torch_fused" if torch.cuda.is_available() else "adamw_torch",
-            bf16=torch.cuda.is_available() and torch.cuda.is_bf16_supported(),
-            fp16=torch.cuda.is_available() and not torch.cuda.is_bf16_supported(),
-            use_cpu=not torch.cuda.is_available(),
-            report_to=getattr(self.config.training, "report_to", "tensorboard"),
-            run_name=getattr(self.config.training, "run_name", None) or self.run_name,
-        )
+        kwargs = {
+            "output_dir": self.checkpoint_dir,
+            "max_steps": self.config.training.max_steps,
+            "num_train_epochs": self.config.training.num_train_epochs,
+            "per_device_train_batch_size": self.config.training.per_device_train_batch_size,
+            "gradient_accumulation_steps": self.config.training.gradient_accumulation_steps,
+            "learning_rate": self.config.training.learning_rate,
+            "warmup_ratio": self.config.training.warmup_ratio,
+            "weight_decay": self.config.training.weight_decay,
+            "eval_steps": self.config.training.eval_steps,
+            "save_steps": self.config.training.save_steps,
+            "logging_steps": logging_steps,
+            "eval_strategy": "steps",
+            "save_strategy": "steps",
+            "save_total_limit": self.config.training.save_total_limit,
+            "load_best_model_at_end": True,
+            "metric_for_best_model": "eval_loss",
+            "greater_is_better": False,
+            "gradient_checkpointing": torch.cuda.is_available(),
+            "optim": "adamw_torch_fused" if torch.cuda.is_available() else "adamw_torch",
+            "bf16": torch.cuda.is_available() and torch.cuda.is_bf16_supported(),
+            "fp16": torch.cuda.is_available() and not torch.cuda.is_bf16_supported(),
+            "use_cpu": not torch.cuda.is_available(),
+            "report_to": getattr(self.config.training, "report_to", "tensorboard"),
+            "run_name": getattr(self.config.training, "run_name", None) or self.run_name,
+        }
 
         # Inject long-context optimizations
         self._apply_long_context_config(kwargs)
@@ -339,14 +343,14 @@ def _build_trainer(self, callbacks: list) -> None:
         tt = self._trainer_type
         training_args = self._get_training_args_for_type()
 
-        trainer_kwargs = dict(
-            model=self.model,
-            processing_class=self.tokenizer,
-            args=training_args,
-            train_dataset=self.dataset["train"],
-            eval_dataset=self.dataset.get("validation", None),
-            callbacks=callbacks,
-        )
+        trainer_kwargs = {
+            "model": self.model,
+            "processing_class": self.tokenizer,
+            "args": training_args,
+            "train_dataset": self.dataset["train"],
+            "eval_dataset": self.dataset.get("validation", None),
+            "callbacks": callbacks,
+        }
 
         if tt == "sft":
             logger.info("Initializing TRL SFTTrainer...")
@@ -470,187 +474,234 @@ def _run_with_oom_recovery(self, resume_from_checkpoint: Optional[str]) -> Any:
 
                 self._build_trainer(callbacks)
 
-    def train(self, resume_from_checkpoint: Optional[str] = None) -> TrainResult:
-        """Starts the main training loop. Returns TrainResult with status and metrics."""
-        # Store originals so compliance manifest reflects pre-OOM values
-        self._original_batch_size = self.config.training.per_device_train_batch_size
-        self._original_grad_accum = self.config.training.gradient_accumulation_steps
-
-        self.notifier.notify_start(run_name=self.run_name)
-        callbacks = []
-        if self.dataset.get("validation"):
-            patience = getattr(self.config.training, "early_stopping_patience", 3)
-            callbacks.append(EarlyStoppingCallback(early_stopping_patience=patience))
+    def _measure_baseline_loss(self, metrics: Dict[str, float]) -> None:
+        """Compute baseline eval_loss before training (used for regression gates)."""
+        eval_cfg = self.config.evaluation
+        if not (
+            self.dataset.get("validation") and eval_cfg and eval_cfg.auto_revert and eval_cfg.baseline_loss is None
+        ):
+            return
 
-        self._build_trainer(callbacks)
+        logger.info("Measuring baseline eval_loss (pre-training)...")
+        model_obj = self.trainer.model
+        baseline_metrics = None
+        if hasattr(model_obj, "disable_adapter"):
+            try:
+                with model_obj.disable_adapter():
+                    baseline_metrics = self.trainer.evaluate()
+            except Exception as e:
+                logger.warning("Failed to disable adapters for baseline eval, evaluating with adapters instead: %s", e)
+                baseline_metrics = self.trainer.evaluate()
+        else:
+            baseline_metrics = self.trainer.evaluate()
 
-        try:
-            metrics: Dict[str, float] = {}
-            self.audit.log_event("training.started")
-
-            # Baseline evaluation (base model, without adapters).
-            # This enables Phase 2 "never overwrite a better model" behavior.
-            if self.dataset.get("validation") and self.config.evaluation and self.config.evaluation.auto_revert:
-                if self.config.evaluation.baseline_loss is None:
-                    logger.info("Measuring baseline eval_loss (pre-training)...")
-                    model_obj = self.trainer.model
-                    baseline_metrics = None
-                    # PEFT models often support disabling adapters for true base-model eval.
-                    if hasattr(model_obj, "disable_adapter"):
-                        try:
-                            with model_obj.disable_adapter():
-                                baseline_metrics = self.trainer.evaluate()
-                        except Exception as e:
-                            logger.warning(
-                                "Failed to disable adapters for baseline eval, evaluating with adapters instead: %s", e
-                            )
-                            baseline_metrics = self.trainer.evaluate()
-                    else:
-                        baseline_metrics = self.trainer.evaluate()
-                    baseline_loss = baseline_metrics.get("eval_loss")
-                    if baseline_loss is not None:
-                        self.config.evaluation.baseline_loss = float(baseline_loss)
-                        metrics["baseline_eval_loss"] = float(baseline_loss)
-                        logger.info("Baseline eval_loss computed: %.4f", baseline_loss)
-                    else:
-                        logger.warning(
-                            "Baseline evaluation completed but eval_loss not found in results. "
-                            "Baseline regression check will be skipped."
-                        )
-
-            logger.info("Starting training...")
-            hf_train_result = self._run_with_oom_recovery(resume_from_checkpoint)
-
-            metrics.update(hf_train_result.metrics)
-            if self.dataset.get("validation"):
-                eval_metrics = self.trainer.evaluate()
-                metrics.update(eval_metrics)
-
-            final_path = os.path.join(
-                self.checkpoint_dir,
-                getattr(self.config.training, "final_model_dir", "final_model"),
+        baseline_loss = baseline_metrics.get("eval_loss")
+        if baseline_loss is None:
+            logger.warning(
+                "Baseline evaluation completed but eval_loss not found in results. "
+                "Baseline regression check will be skipped."
             )
-            self.save_final_model(final_path)
+            return
+        eval_cfg.baseline_loss = float(baseline_loss)
+        metrics["baseline_eval_loss"] = float(baseline_loss)
+        logger.info("Baseline eval_loss computed: %.4f", baseline_loss)
+
+    def _apply_benchmark_result(
+        self,
+        benchmark_result: Any,
+        train_result: TrainResult,
+        metrics: Dict[str, float],
+        final_path: str,
+    ) -> bool:
+        """Attach benchmark output to *train_result*, returning True to continue.
+
+        Mirrors the safety/judge gating: revert + halt only when the user opted
+        into auto_revert. Without that flag, benchmark failures are recorded
+        but do not destroy the saved model.
+        """
+        if benchmark_result is None:
+            return True
+        train_result.benchmark_scores = benchmark_result.scores
+        train_result.benchmark_average = benchmark_result.average_score
+        train_result.benchmark_passed = benchmark_result.passed
+        for task, score in benchmark_result.scores.items():
+            metrics[f"benchmark/{task}"] = score
+        metrics["benchmark/average"] = benchmark_result.average_score
+        self.audit.log_event(
+            "benchmark.evaluation_completed",
+            passed=benchmark_result.passed,
+            average=benchmark_result.average_score,
+            scores=benchmark_result.scores,
+        )
+        if benchmark_result.passed:
+            return True
+        reason = benchmark_result.failure_reason or "Benchmark score below threshold."
+        if not (self.config.evaluation and self.config.evaluation.auto_revert):
+            # Failure recorded on train_result; pipeline continues to safety/judge stages.
+            return True
+        self.audit.log_event(_EVT_REVERT_TRIGGERED, reason="benchmark", detail=reason)
+        self._revert_model(final_path, reason)
+        train_result.success = False
+        train_result.reverted = True
+        return False
+
+    def _apply_resource_usage(self, train_result: TrainResult, metrics: Dict[str, float]) -> None:
+        """Collect resource usage and feed it into the result + metrics dicts."""
+        train_result.resource_usage = self._collect_resource_usage()
+        if not train_result.resource_usage:
+            return
+        for k, v in train_result.resource_usage.items():
+            if isinstance(v, (int, float)):
+                metrics[f"resource/{k}"] = v
+        train_result.estimated_cost_usd = train_result.resource_usage.get("estimated_cost_usd")
+
+    def _apply_safety_result(
+        self,
+        safety_result: Any,
+        train_result: TrainResult,
+        metrics: Dict[str, float],
+        final_path: str,
+    ) -> bool:
+        """Attach safety eval output to *train_result*, returning True to continue."""
+        if safety_result is None:
+            return True
+        train_result.safety_passed = safety_result.passed
+        train_result.safety_score = safety_result.safety_score
+        train_result.safety_categories = safety_result.category_distribution
+        train_result.safety_severity = safety_result.severity_distribution
+        train_result.safety_low_confidence = safety_result.low_confidence_count
+        metrics["safety/safe_ratio"] = safety_result.safe_ratio
+        if safety_result.safety_score is not None:
+            metrics["safety/safety_score"] = safety_result.safety_score
+        self.audit.log_event(
+            "safety.evaluation_completed",
+            passed=safety_result.passed,
+            safe_ratio=safety_result.safe_ratio,
+            safety_score=safety_result.safety_score,
+            categories=safety_result.category_distribution,
+        )
+        if safety_result.passed or not (self.config.evaluation and self.config.evaluation.auto_revert):
+            return True
+        self.audit.log_event(_EVT_REVERT_TRIGGERED, reason="safety", detail=safety_result.failure_reason)
+        self._revert_model(final_path, safety_result.failure_reason or "Safety check failed.")
+        train_result.success = False
+        train_result.reverted = True
+        return False
+
+    def _apply_judge_result(
+        self,
+        judge_result: Any,
+        train_result: TrainResult,
+        metrics: Dict[str, float],
+        final_path: str,
+    ) -> bool:
+        """Attach judge output to *train_result*, returning True to continue."""
+        if judge_result is None:
+            return True
+        train_result.judge_score = judge_result.average_score
+        train_result.judge_details = judge_result.details
+        metrics["judge/average_score"] = judge_result.average_score
+        self.audit.log_event(
+            "judge.evaluation_completed",
+            passed=judge_result.passed,
+            average_score=judge_result.average_score,
+        )
+        if judge_result.passed or not (self.config.evaluation and self.config.evaluation.auto_revert):
+            return True
+        self.audit.log_event(_EVT_REVERT_TRIGGERED, reason="judge", detail=judge_result.failure_reason)
+        self._revert_model(final_path, judge_result.failure_reason or "Judge score below threshold.")
+        train_result.success = False
+        train_result.reverted = True
+        return False
+
+    def _finalize_artifacts(
+        self,
+        final_path: str,
+        metrics: Dict[str, float],
+        train_result: TrainResult,
+    ) -> None:
+        """Generate model card / integrity / deployer instructions / compliance bundle."""
+        self._generate_model_card(final_path, metrics, train_result)
+        self._generate_model_integrity(final_path)
+        self._generate_deployer_instructions(final_path, metrics)
+        self._export_compliance_if_needed(metrics, train_result)
+
+    def _handle_human_approval_gate(self, final_path: str, train_result: TrainResult) -> bool:
+        """Return True if the run should pause for human approval (Art. 14)."""
+        eval_cfg = self.config.evaluation
+        if not (eval_cfg and eval_cfg.require_human_approval):
+            return False
+        self.audit.log_event("human_approval.required", model_path=final_path)
+        logger.info("Human approval required. Model saved to staging: %s", final_path)
+        logger.info(
+            "Review results in %s/compliance/ and redeploy when ready. Run ID: %s",
+            self.checkpoint_dir,
+            self.audit.run_id,
+        )
+        train_result.success = True
+        return True
 
-            # Autonomous Evaluation Check (loss-based)
-            is_valid = self.execute_evaluation_checks(final_path, metrics)
-            if not is_valid:
-                return TrainResult(success=False, metrics=metrics, reverted=True)
+    def _run_training_pipeline(self, resume_from_checkpoint: Optional[str]) -> TrainResult:
+        """Body of train(); split out so train() stays a thin orchestrator."""
+        metrics: Dict[str, float] = {}
+        self.audit.log_event("training.started")
 
-            # Post-training benchmark evaluation (lm-eval-harness)
-            benchmark_result = self._run_benchmark_if_configured(final_path, metrics)
+        self._measure_baseline_loss(metrics)
 
-            train_result = TrainResult(
-                success=True,
-                metrics=metrics,
-                final_model_path=final_path,
-            )
+        logger.info("Starting training...")
+        hf_train_result = self._run_with_oom_recovery(resume_from_checkpoint)
+        metrics.update(hf_train_result.metrics)
 
-            if benchmark_result is not None:
-                train_result.benchmark_scores = benchmark_result.scores
-                train_result.benchmark_average = benchmark_result.average_score
-                train_result.benchmark_passed = benchmark_result.passed
+        if self.dataset.get("validation"):
+            metrics.update(self.trainer.evaluate())
 
-                # Add benchmark scores to metrics for webhook
-                for task, score in benchmark_result.scores.items():
-                    metrics[f"benchmark/{task}"] = score
-                metrics["benchmark/average"] = benchmark_result.average_score
+        final_path = os.path.join(
+            self.checkpoint_dir,
+            getattr(self.config.training, "final_model_dir", "final_model"),
+        )
+        self.save_final_model(final_path)
 
-                self.audit.log_event(
-                    "benchmark.evaluation_completed",
-                    passed=benchmark_result.passed,
-                    average=benchmark_result.average_score,
-                    scores=benchmark_result.scores,
-                )
+        if not self.execute_evaluation_checks(final_path, metrics):
+            return TrainResult(success=False, metrics=metrics, reverted=True)
 
-                if not benchmark_result.passed:
-                    reason = benchmark_result.failure_reason or "Benchmark score below threshold."
-                    self.audit.log_event("eval.revert_triggered", reason="benchmark", detail=reason)
-                    self._revert_model(final_path, reason)
-                    train_result.success = False
-                    train_result.reverted = True
-                    return train_result
-
-            # Resource tracking + cost estimation
-            train_result.resource_usage = self._collect_resource_usage()
-            if train_result.resource_usage:
-                for k, v in train_result.resource_usage.items():
-                    if isinstance(v, (int, float)):
-                        metrics[f"resource/{k}"] = v
-                train_result.estimated_cost_usd = train_result.resource_usage.get("estimated_cost_usd")
-
-            # Post-training safety evaluation
-            safety_result = self._run_safety_if_configured(final_path)
-            if safety_result is not None:
-                train_result.safety_passed = safety_result.passed
-                train_result.safety_score = safety_result.safety_score
-                train_result.safety_categories = safety_result.category_distribution
-                train_result.safety_severity = safety_result.severity_distribution
-                train_result.safety_low_confidence = safety_result.low_confidence_count
-                metrics["safety/safe_ratio"] = safety_result.safe_ratio
-                if safety_result.safety_score is not None:
-                    metrics["safety/safety_score"] = safety_result.safety_score
-                self.audit.log_event(
-                    "safety.evaluation_completed",
-                    passed=safety_result.passed,
-                    safe_ratio=safety_result.safe_ratio,
-                    safety_score=safety_result.safety_score,
-                    categories=safety_result.category_distribution,
-                )
-                if not safety_result.passed and self.config.evaluation and self.config.evaluation.auto_revert:
-                    self.audit.log_event("eval.revert_triggered", reason="safety", detail=safety_result.failure_reason)
-                    self._revert_model(final_path, safety_result.failure_reason or "Safety check failed.")
-                    train_result.success = False
-                    train_result.reverted = True
-                    return train_result
-
-            # LLM-as-Judge evaluation
-            judge_result = self._run_judge_if_configured(final_path)
-            if judge_result is not None:
-                train_result.judge_score = judge_result.average_score
-                train_result.judge_details = judge_result.details
-                metrics["judge/average_score"] = judge_result.average_score
-                self.audit.log_event(
-                    "judge.evaluation_completed",
-                    passed=judge_result.passed,
-                    average_score=judge_result.average_score,
-                )
-                if not judge_result.passed and self.config.evaluation and self.config.evaluation.auto_revert:
-                    self.audit.log_event("eval.revert_triggered", reason="judge", detail=judge_result.failure_reason)
-                    self._revert_model(final_path, judge_result.failure_reason or "Judge score below threshold.")
-                    train_result.success = False
-                    train_result.reverted = True
-                    return train_result
+        train_result = TrainResult(success=True, metrics=metrics, final_model_path=final_path)
 
-            # Generate model card
-            self._generate_model_card(final_path, metrics, train_result)
+        if not self._apply_benchmark_result(self._run_benchmark_if_configured(), train_result, metrics, final_path):
+            return train_result
 
-            # Model integrity verification (Art. 15)
-            self._generate_model_integrity(final_path)
+        self._apply_resource_usage(train_result, metrics)
 
-            # Deployer instructions (Art. 13)
-            self._generate_deployer_instructions(final_path, metrics)
+        if not self._apply_safety_result(self._run_safety_if_configured(), train_result, metrics, final_path):
+            return train_result
 
-            # Generate compliance artifacts (Art. 11 + Annex IV)
-            self._export_compliance_if_needed(final_path, metrics, train_result)
+        if not self._apply_judge_result(self._run_judge_if_configured(), train_result, metrics, final_path):
+            return train_result
 
-            # Human approval gate (Art. 14)
-            if self.config.evaluation and self.config.evaluation.require_human_approval:
-                self.audit.log_event("human_approval.required", model_path=final_path)
-                logger.info("Human approval required. Model saved to staging: %s", final_path)
-                logger.info(
-                    "Review results in %s/compliance/ and redeploy when ready. Run ID: %s",
-                    self.checkpoint_dir,
-                    self.audit.run_id,
-                )
-                train_result.success = True
-                # Exit code 4 handled by CLI
-                return train_result
+        self._finalize_artifacts(final_path, metrics, train_result)
 
-            self.audit.log_event("pipeline.completed", success=True, metrics_summary=metrics)
-            self.notifier.notify_success(run_name=self.run_name, metrics=metrics)
+        if self._handle_human_approval_gate(final_path, train_result):
             return train_result
 
+        self.audit.log_event("pipeline.completed", success=True, metrics_summary=metrics)
+        self.notifier.notify_success(run_name=self.run_name, metrics=metrics)
+        return train_result
+
+    def train(self, resume_from_checkpoint: Optional[str] = None) -> TrainResult:
+        """Starts the main training loop. Returns TrainResult with status and metrics."""
+        # Store originals so compliance manifest reflects pre-OOM values
+        self._original_batch_size = self.config.training.per_device_train_batch_size
+        self._original_grad_accum = self.config.training.gradient_accumulation_steps
+
+        self.notifier.notify_start(run_name=self.run_name)
+        callbacks = []
+        if self.dataset.get("validation"):
+            patience = getattr(self.config.training, "early_stopping_patience", 3)
+            callbacks.append(EarlyStoppingCallback(early_stopping_patience=patience))
+
+        self._build_trainer(callbacks)
+
+        try:
+            return self._run_training_pipeline(resume_from_checkpoint)
         except Exception as e:
             logger.exception("Training pipeline failed.")
             self.audit.log_event("pipeline.failed", error=str(e))
@@ -684,7 +735,7 @@ def save_final_model(self, final_path: str) -> None:
             self.trainer.save_model(final_path)
         self.tokenizer.save_pretrained(final_path)
 
-    def _run_benchmark_if_configured(self, final_path: str, metrics: Dict[str, float]):
+    def _run_benchmark_if_configured(self):
         """Run post-training benchmarks if configured. Returns BenchmarkResult or None."""
         eval_cfg = self.config.evaluation
         if not eval_cfg or not eval_cfg.benchmark or not eval_cfg.benchmark.enabled:
@@ -759,44 +810,62 @@ def _generate_model_card(self, final_path: str, metrics: Dict[str, float], resul
         "NVIDIA GeForce RTX 4090": 0.20,
     }
 
+    def _collect_gpu_info(self, usage: Dict[str, Any]) -> None:
+        """Populate gpu_model / peak_vram_gb / gpu_count fields when CUDA is available."""
+        if not torch.cuda.is_available():
+            return
+        usage["gpu_model"] = torch.cuda.get_device_name(0)
+        usage["peak_vram_gb"] = round(torch.cuda.max_memory_allocated(0) / (1024**3), 2)
+        usage["gpu_count"] = torch.cuda.device_count()
+
+    def _train_runtime_seconds(self) -> Optional[float]:
+        """Pull train_runtime from the most recent HF Trainer log entry."""
+        log_history = getattr(self.trainer.state, "log_history", None) or []
+        return next(
+            (e.get("train_runtime") for e in reversed(log_history) if "train_runtime" in e),
+            None,
+        )
+
+    def _resolve_cost_per_hour(self, usage: Dict[str, Any]) -> Optional[float]:
+        """Resolve a $/hour rate from user config or the GPU-pricing table.
+
+        Side-effect: sets ``usage["cost_source"]`` when a rate is found.
+        """
+        cost_per_hour = getattr(self.config.training, "gpu_cost_per_hour", None)
+        if cost_per_hour is not None:
+            usage["cost_source"] = "user_config"
+            return cost_per_hour
+
+        gpu_name = usage.get("gpu_model", "")
+        exact = self._GPU_PRICING.get(gpu_name)
+        if exact is not None:
+            usage["cost_source"] = "auto_detected"
+            return exact
+
+        # Fuzzy match — iterate longest known names first so e.g. "NVIDIA H100"
+        # is preferred over "NVIDIA H1" when both are substrings of the GPU name.
+        gpu_lower = gpu_name.lower()
+        sorted_pricing = sorted(self._GPU_PRICING.items(), key=lambda kv: len(kv[0]), reverse=True)
+        for known_gpu, price in sorted_pricing:
+            known_lower = known_gpu.lower()
+            if known_lower in gpu_lower or gpu_lower in known_lower:
+                usage["cost_source"] = "fuzzy_match"
+                return price
+        return None
+
     def _collect_resource_usage(self) -> Optional[Dict[str, Any]]:
         """Collect GPU resource usage metrics and estimate training cost."""
-        usage = {}
+        usage: Dict[str, Any] = {}
         try:
-            if torch.cuda.is_available():
-                gpu_name = torch.cuda.get_device_name(0)
-                usage["gpu_model"] = gpu_name
-                usage["peak_vram_gb"] = round(torch.cuda.max_memory_allocated(0) / (1024**3), 2)
-                usage["gpu_count"] = torch.cuda.device_count()
-            # Training duration from HF Trainer
-            log_history = getattr(self.trainer.state, "log_history", None) or []
-            train_runtime = next(
-                (e.get("train_runtime") for e in reversed(log_history) if "train_runtime" in e),
-                None,
-            )
+            self._collect_gpu_info(usage)
+
+            train_runtime = self._train_runtime_seconds()
             if train_runtime:
                 usage["training_duration_seconds"] = round(train_runtime, 1)
-                gpu_count = usage.get("gpu_count", 1)
-                gpu_hours = (train_runtime / 3600) * gpu_count
+                gpu_hours = (train_runtime / 3600) * usage.get("gpu_count", 1)
                 usage["gpu_hours"] = round(gpu_hours, 3)
 
-                # Cost estimation
-                cost_per_hour = getattr(self.config.training, "gpu_cost_per_hour", None)
-                if cost_per_hour is None:
-                    gpu_name = usage.get("gpu_model", "")
-                    cost_per_hour = self._GPU_PRICING.get(gpu_name)
-                    if cost_per_hour:
-                        usage["cost_source"] = "auto_detected"
-                    else:
-                        # Try partial match (GPU names vary across drivers)
-                        for known_gpu, price in self._GPU_PRICING.items():
-                            if known_gpu.lower() in gpu_name.lower() or gpu_name.lower() in known_gpu.lower():
-                                cost_per_hour = price
-                                usage["cost_source"] = "fuzzy_match"
-                                break
-                else:
-                    usage["cost_source"] = "user_config"
-
+                cost_per_hour = self._resolve_cost_per_hour(usage)
                 if cost_per_hour is not None:
                     usage["gpu_cost_per_hour_usd"] = cost_per_hour
                     estimated_cost = gpu_hours * cost_per_hour
@@ -811,7 +880,7 @@ def _collect_resource_usage(self) -> Optional[Dict[str, Any]]:
             logger.warning("Failed to collect resource usage: %s", e)
         return usage if usage else None
 
-    def _run_safety_if_configured(self, final_path: str):
+    def _run_safety_if_configured(self):
         """Run safety evaluation if configured. Returns SafetyResult or None."""
         eval_cfg = self.config.evaluation
         if not eval_cfg or not eval_cfg.safety or not eval_cfg.safety.enabled:
@@ -840,7 +909,7 @@ def _run_safety_if_configured(self, final_path: str):
             severity_thresholds=getattr(safety_cfg, "severity_thresholds", None),
         )
 
-    def _run_judge_if_configured(self, final_path: str):
+    def _run_judge_if_configured(self):
         """Run LLM-as-Judge evaluation if configured. Returns JudgeResult or None."""
         eval_cfg = self.config.evaluation
         if not eval_cfg or not eval_cfg.llm_judge or not eval_cfg.llm_judge.enabled:
@@ -867,7 +936,7 @@ def _run_judge_if_configured(self, final_path: str):
             api_base=getattr(judge_cfg, "judge_api_base", None),
         )
 
-    def _export_compliance_if_needed(self, final_path: str, metrics: Dict[str, float], result: TrainResult) -> None:
+    def _export_compliance_if_needed(self, metrics: Dict[str, float], result: TrainResult) -> None:
         """Export compliance artifacts if evaluation config is present."""
         try:
             from .compliance import export_compliance_artifacts, generate_training_manifest
@@ -905,7 +974,7 @@ def _export_compliance_if_needed(self, final_path: str, metrics: Dict[str, float
             self.config.training.per_device_train_batch_size = _saved_bs
             self.config.training.gradient_accumulation_steps = _saved_ga
             compliance_dir = os.path.join(self.checkpoint_dir, "compliance")
-            export_compliance_artifacts(manifest, self.config, compliance_dir)
+            export_compliance_artifacts(manifest, compliance_dir)
             self.audit.log_event("compliance.artifacts_exported", directory=compliance_dir)
         except Exception as e:
             logger.warning("Failed to export compliance artifacts: %s", e)
diff --git a/forgelm/webhook.py b/forgelm/webhook.py
index db900eda..df540b53 100644
--- a/forgelm/webhook.py
+++ b/forgelm/webhook.py
@@ -2,6 +2,7 @@
 import logging
 import os
 from typing import Dict, Optional
+from urllib.parse import urlparse
 
 import requests
 
@@ -14,6 +15,65 @@ class WebhookNotifier:
     def __init__(self, config):
         self.config = config.webhook
 
+    def _resolve_url(self) -> Optional[str]:
+        """Pick the webhook URL from the config, falling back to url_env."""
+        if not self.config:
+            return None
+        url = self.config.url
+        if not url and getattr(self.config, "url_env", None):
+            url = os.getenv(self.config.url_env)
+        return url or None
+
+    @staticmethod
+    def _mask(url: str) -> str:
+        """Redact credentials and signed query params from a webhook URL.
+
+        Slack/Teams/Discord webhooks carry secrets in the path or query; basic
+        auth can also embed them in userinfo. We log only ``scheme://host`` plus
+        the first path segment so the destination is identifiable but the
+        secret material is not leaked into logs.
+        """
+        try:
+            parts = urlparse(url)
+        except (ValueError, TypeError):
+            return "<unparseable-url>"
+        if not parts.scheme or not parts.netloc:
+            return "<malformed-url>"
+        host = parts.hostname or "unknown-host"
+        first_segment = ""
+        if parts.path:
+            stripped = parts.path.lstrip("/").split("/", 1)[0]
+            if stripped:
+                first_segment = f"/{stripped}/..."
+        return f"{parts.scheme}://{host}{first_segment}"
+
+    def _post_payload(self, url: str, payload: dict, event: str) -> None:
+        """POST *payload* to *url* and log any transport / HTTP errors."""
+        masked_url = self._mask(url)
+        try:
+            resp = requests.post(
+                url,
+                data=json.dumps(payload),
+                headers={"Content-Type": "application/json"},
+                timeout=getattr(self.config, "timeout", 5),
+            )
+            if not resp.ok:
+                # Don't log resp.text — receivers sometimes echo the payload
+                # (which can contain secret-bearing fields) or include their
+                # own auth context. Surface only the status code.
+                logger.warning(
+                    "Webhook HTTP %d for event '%s' (url=%s) — response body suppressed",
+                    resp.status_code,
+                    event,
+                    masked_url,
+                )
+        except requests.exceptions.Timeout:
+            logger.warning("Webhook request timed out for event '%s' (url=%s).", event, masked_url)
+        except requests.exceptions.ConnectionError:
+            logger.warning("Webhook connection failed for event '%s' (url=%s).", event, masked_url)
+        except Exception:
+            logger.exception("Unexpected error sending webhook notification for event '%s'.", event)
+
     def _send(
         self,
         *,
@@ -26,13 +86,7 @@ def _send(
         metrics: Optional[Dict[str, float]] = None,
         reason: Optional[str] = None,
     ) -> None:
-        if not self.config:
-            return
-
-        url = self.config.url
-        if not url and getattr(self.config, "url_env", None):
-            url = os.getenv(self.config.url_env)
-
+        url = self._resolve_url()
         if not url:
             return
 
@@ -53,30 +107,7 @@ def _send(
             "attachments": [{"title": title, "text": text, "color": color}],
         }
 
-        try:
-            resp = requests.post(
-                url,
-                data=json.dumps(payload),
-                headers={"Content-Type": "application/json"},
-                timeout=getattr(self.config, "timeout", 5),
-            )
-            if not resp.ok:
-                masked = url[:30] + "..." if len(url) > 30 else url
-                logger.warning(
-                    "Webhook HTTP %d for event '%s' (url=%s): %s",
-                    resp.status_code,
-                    event,
-                    masked,
-                    resp.text[:200],
-                )
-        except requests.exceptions.Timeout:
-            masked = url[:30] + "..." if len(url) > 30 else url
-            logger.warning("Webhook request timed out for event '%s' (url=%s).", event, masked)
-        except requests.exceptions.ConnectionError:
-            masked = url[:30] + "..." if len(url) > 30 else url
-            logger.warning("Webhook connection failed for event '%s' (url=%s).", event, masked)
-        except Exception:
-            logger.exception("Unexpected error sending webhook notification for event '%s'.", event)
+        self._post_payload(url, payload, event)
 
     def notify_start(self, run_name: str) -> None:
         if self.config and self.config.notify_on_start:
diff --git a/forgelm/wizard.py b/forgelm/wizard.py
index 9508b342..08a75921 100644
--- a/forgelm/wizard.py
+++ b/forgelm/wizard.py
@@ -5,7 +5,9 @@
 """
 
 import logging
+import os
 import sys
+from typing import Optional
 
 import yaml
 
@@ -34,6 +36,9 @@
     "full": ["q_proj", "k_proj", "v_proj", "o_proj", "gate_proj", "up_proj", "down_proj"],
 }
 
+# Common dataset-format hints for preference-based trainers (DPO/SimPO/ORPO)
+_PREFERENCE_COLUMNS_HINT = "Columns: prompt, chosen, rejected"
+
 
 def _prompt(question: str, default: str = "") -> str:
     """Prompt user with a default value."""
@@ -94,8 +99,229 @@ def _detect_hardware() -> dict:
     return info
 
 
-def run_wizard() -> str:
-    """Run the interactive configuration wizard. Returns the path to the generated config file."""
+def _collect_rope_scaling(max_length: int) -> Optional[dict]:
+    """Prompt for RoPE scaling parameters when context is long; otherwise None."""
+    if max_length <= 4096:
+        return None
+    print(f"\n  Long context detected ({max_length} tokens).")
+    if not _prompt_yes_no("Enable RoPE scaling for extended context?", default=True):
+        return None
+    rope_type = _prompt_choice(
+        "RoPE scaling type:",
+        ["linear (simple, proven)", "dynamic (adaptive)", "yarn (best quality, newer)"],
+        default=1,
+    )
+    base_context = 4096
+    rope_factor = max_length / base_context
+    print(
+        f"  Note: RoPE factor {rope_factor:.1f}x computed assuming base context of "
+        f"{base_context} tokens. Adjust manually if your model has a different "
+        f"original context length (e.g., Llama 3.1 = 131072, Mistral v0.3 = 32768)."
+    )
+    return {"type": rope_type.split(" ")[0], "factor": rope_factor}
+
+
+def _collect_neftune_alpha() -> Optional[float]:
+    """Prompt for NEFTune noise injection; returns alpha or None."""
+    if not _prompt_yes_no("Enable NEFTune noise injection (improves training quality)?", default=False):
+        return None
+    return float(_prompt("NEFTune noise alpha", "5.0"))
+
+
+def _collect_webhook_config() -> Optional[dict]:
+    """Prompt for webhook configuration; returns the webhook section or None."""
+    if not _prompt_yes_no("Configure webhook notifications?", default=False):
+        return None
+    webhook_url = _prompt("Webhook URL (or leave empty for env var)")
+    if webhook_url:
+        return {"url": webhook_url}
+    env_var = _prompt("Environment variable name for webhook URL", "FORGELM_WEBHOOK_URL")
+    return {"url_env": env_var}
+
+
+def _collect_safety_config() -> Optional[dict]:
+    """Prompt for safety eval; returns the safety section or None."""
+    if not _prompt_yes_no("Enable safety evaluation (Llama Guard)?", default=False):
+        return None
+    scoring = _prompt_choice(
+        "Safety scoring mode:",
+        ["binary (simple safe/unsafe ratio)", "confidence_weighted (uses classifier confidence)"],
+        default=1,
+    )
+    scoring_mode = "confidence_weighted" if "confidence" in scoring else "binary"
+    safety_config: dict = {
+        "enabled": True,
+        "test_prompts": "configs/safety_prompts/general_safety.jsonl",
+        "scoring": scoring_mode,
+    }
+    if scoring_mode == "confidence_weighted":
+        safety_config["min_safety_score"] = 0.85
+    if _prompt_yes_no("Track harm categories (S1-S14)?", default=False):
+        safety_config["track_categories"] = True
+        safety_config["severity_thresholds"] = {"critical": 0, "high": 0.01, "medium": 0.05}
+    return safety_config
+
+
+def _collect_evaluation_config() -> Optional[dict]:
+    """Prompt for auto-revert + safety; returns the evaluation section or None."""
+    if not _prompt_yes_no("Enable auto-revert (discard model if quality drops)?", default=False):
+        return None
+    max_loss = _prompt("Max acceptable loss (leave empty for baseline-only)", "")
+    eval_config: dict = {
+        "auto_revert": True,
+        "max_acceptable_loss": float(max_loss) if max_loss else None,
+    }
+    safety = _collect_safety_config()
+    if safety:
+        eval_config["safety"] = safety
+    return eval_config
+
+
+def _collect_compliance_config() -> Optional[dict]:
+    """Prompt for EU AI Act metadata; returns the compliance section or None."""
+    if not _prompt_yes_no("Configure EU AI Act compliance metadata?", default=False):
+        return None
+    return {
+        "provider_name": _prompt("Organization name"),
+        "intended_purpose": _prompt("Intended purpose of the model"),
+        "risk_classification": _prompt_choice(
+            "Risk classification:",
+            ["minimal-risk", "limited-risk", "high-risk"],
+            default=1,
+        ),
+    }
+
+
+def _save_config_to_file(config: dict, requested_filename: str) -> str:
+    """Write *config* as YAML; falls back to a unique filename on OSError."""
+    try:
+        with open(requested_filename, "w") as f:
+            yaml.dump(config, f, default_flow_style=False, sort_keys=False)
+        print(f"\n  Config saved to: {requested_filename}")
+        return requested_filename
+    except OSError as e:
+        print(f"\n  Error: Could not save config to {requested_filename}: {e}")
+
+    # Pick a fallback that's guaranteed different from the path that just failed
+    # (a hardcoded "my_config.yaml" would just re-raise the same OSError when
+    # the original request was already that filename).
+    from datetime import datetime as _dt
+
+    base = os.path.splitext(os.path.basename(requested_filename))[0] or "my_config"
+    fallback = os.path.join(os.path.expanduser("~"), f"{base}_{_dt.now().strftime('%Y%m%d_%H%M%S')}.yaml")
+    try:
+        with open(fallback, "w") as f:
+            yaml.dump(config, f, default_flow_style=False, sort_keys=False)
+        print(f"  Saved to fallback location: {fallback}")
+        return fallback
+    except OSError as e:
+        print(f"  Fallback save also failed ({fallback}): {e}")
+        raise
+
+
+def _print_wizard_summary(
+    *,
+    model_name: str,
+    suggested_backend: str,
+    use_galore: bool,
+    load_in_4bit: bool,
+    use_dora: bool,
+    trainer_type: str,
+    lora_r: int,
+    lora_alpha: int,
+    dataset_path: str,
+    epochs: int,
+    batch_size: int,
+    output_dir: str,
+) -> None:
+    """Pretty-print the chosen configuration before the start-now prompt."""
+    print("\n" + "=" * 60)
+    print("  Configuration Summary")
+    print("=" * 60)
+    print(f"  Model:    {model_name}")
+    print(f"  Backend:  {suggested_backend}")
+    if use_galore:
+        strategy_str = "GaLore"
+    elif load_in_4bit:
+        strategy_str = "QLoRA"
+    else:
+        strategy_str = "LoRA"
+    if use_dora:
+        strategy_str += " + DoRA"
+    print(f"  Strategy: {strategy_str}")
+    print(f"  Trainer:  {trainer_type.upper()}")
+    print(f"  LoRA:     r={lora_r}, alpha={lora_alpha}")
+    print(f"  Dataset:  {dataset_path}")
+    print(f"  Epochs:   {epochs}, Batch: {batch_size}")
+    print(f"  Output:   {output_dir}/final_model")
+    print()
+
+
+def _select_model() -> str:
+    """Prompt for a model from POPULAR_MODELS or allow a custom entry."""
+    print("\n[2/8] Model Selection")
+    print("  Popular models:")
+    for i, m in enumerate(POPULAR_MODELS, 1):
+        print(f"    {i}) {m}")
+    print(f"    {len(POPULAR_MODELS) + 1}) Custom (enter your own)")
+    model_choice = input("  Choice [1]: ").strip()
+    try:
+        idx = int(model_choice) if model_choice else 1
+        if idx <= len(POPULAR_MODELS):
+            return POPULAR_MODELS[idx - 1]
+        return _prompt("Enter HuggingFace model name or local path")
+    except (ValueError, IndexError):
+        return POPULAR_MODELS[0]
+
+
+def _derive_strategy_flags(strategy: str) -> tuple:
+    """Decode the strategy menu choice into (load_in_4bit, use_dora, use_galore)."""
+    return ("QLoRA" in strategy, "DoRA" in strategy, "GaLore" in strategy)
+
+
+def _parse_trainer_type(objective: str) -> tuple:
+    """Return (trainer_type, dataset_format_hint) for the chosen objective."""
+    trainer_type = objective.split(" — ")[0].strip().lower()
+    dataset_format_hint = {
+        "sft": "Columns: System (opt), User/instruction, Assistant/output — or 'messages' list",
+        "dpo": _PREFERENCE_COLUMNS_HINT,
+        "simpo": _PREFERENCE_COLUMNS_HINT,
+        "orpo": _PREFERENCE_COLUMNS_HINT,
+        "kto": "Columns: prompt, completion, label (boolean: true=good, false=bad)",
+        "grpo": "Columns: prompt (model generates responses during training)",
+    }
+    hint = dataset_format_hint.get(trainer_type, "Standard format")
+    return trainer_type, hint
+
+
+def _collect_galore_config(use_galore: bool) -> dict:
+    """Prompt for GaLore-specific knobs when GaLore was selected; otherwise empty."""
+    if not use_galore:
+        print("\n[7/8] Advanced Options")
+        return {}
+    print("\n[7/8] GaLore Configuration")
+    galore_rank = _prompt_int("GaLore rank (lower = less memory)", 128, min_val=1, max_val=4096)
+    galore_optim = _prompt_choice(
+        "GaLore optimizer:",
+        ["galore_adamw (standard)", "galore_adamw_8bit (less memory)", "galore_adafactor (experimental)"],
+        default=1,
+    )
+    return {
+        "galore_enabled": True,
+        "galore_optim": galore_optim.split(" ")[0],
+        "galore_rank": galore_rank,
+        "galore_update_proj_gap": 200,
+        "galore_scale": 0.25,
+    }
+
+
+def run_wizard() -> Optional[str]:
+    """Run the interactive configuration wizard.
+
+    Returns the path to the generated config file when the user opts to start
+    training immediately, or ``None`` when the user defers — callers must
+    handle both cases.
+    """
     print("\n" + "=" * 60)
     print("  ForgeLM Configuration Wizard")
     print("=" * 60)
@@ -118,22 +344,7 @@ def run_wizard() -> str:
             print("  Recommended backend: transformers (Unsloth requires Linux)")
 
     # Step 2: Model Selection
-    print("\n[2/8] Model Selection")
-    print("  Popular models:")
-    for i, m in enumerate(POPULAR_MODELS, 1):
-        print(f"    {i}) {m}")
-    print(f"    {len(POPULAR_MODELS) + 1}) Custom (enter your own)")
-
-    model_choice = input("  Choice [1]: ").strip()
-    try:
-        idx = int(model_choice) if model_choice else 1
-        if idx <= len(POPULAR_MODELS):
-            model_name = POPULAR_MODELS[idx - 1]
-        else:
-            model_name = _prompt("Enter HuggingFace model name or local path")
-    except (ValueError, IndexError):
-        model_name = POPULAR_MODELS[0]
-
+    model_name = _select_model()
     print(f"  Selected: {model_name}")
 
     # Step 3: Strategy Selection
@@ -145,10 +356,7 @@ def run_wizard() -> str:
         "GaLore (full-parameter training via gradient projection — no adapters, lowest peak VRAM)",
     ]
     strategy = _prompt_choice("Choose your fine-tuning strategy:", strategies, default=1)
-
-    load_in_4bit = "QLoRA" in strategy
-    use_dora = "DoRA" in strategy
-    use_galore = "GaLore" in strategy
+    load_in_4bit, use_dora, use_galore = _derive_strategy_flags(strategy)
 
     # LoRA parameters
     target_preset = _prompt_choice(
@@ -173,18 +381,8 @@ def run_wizard() -> str:
         "GRPO — Group Relative Policy Optimization (reasoning RL, like DeepSeek-R1)",
     ]
     objective = _prompt_choice("Choose your training objective:", objectives, default=1)
-    trainer_type = objective.split(" — ")[0].strip().lower()
-
-    # Dataset format guidance
-    dataset_format_hint = {
-        "sft": "Columns: System (opt), User/instruction, Assistant/output — or 'messages' list",
-        "dpo": "Columns: prompt, chosen, rejected",
-        "simpo": "Columns: prompt, chosen, rejected",
-        "orpo": "Columns: prompt, chosen, rejected",
-        "kto": "Columns: prompt, completion, label (boolean: true=good, false=bad)",
-        "grpo": "Columns: prompt (model generates responses during training)",
-    }
-    print(f"  Dataset format: {dataset_format_hint.get(trainer_type, 'Standard format')}")
+    trainer_type, dataset_format_hint = _parse_trainer_type(objective)
+    print(f"  Dataset format: {dataset_format_hint}")
 
     # Step 5: Dataset
     print("\n[5/8] Dataset")
@@ -197,29 +395,9 @@ def run_wizard() -> str:
     max_length = _prompt_int("Max sequence length", DEFAULT_MAX_LENGTH, min_val=64, max_val=131072)
     output_dir = _prompt("Output directory", "./checkpoints")
 
-    # Long-context options (only if max_length > 4096)
-    use_neftune = False
-    neftune_alpha = None
-    rope_scaling = None
-    if max_length > 4096:
-        print(f"\n  Long context detected ({max_length} tokens).")
-        if _prompt_yes_no("Enable RoPE scaling for extended context?", default=True):
-            rope_type = _prompt_choice(
-                "RoPE scaling type:",
-                ["linear (simple, proven)", "dynamic (adaptive)", "yarn (best quality, newer)"],
-                default=1,
-            )
-            base_context = 4096
-            rope_factor = max_length / base_context
-            print(
-                f"  Note: RoPE factor {rope_factor:.1f}x computed assuming base context of "
-                f"{base_context} tokens. Adjust manually if your model has a different "
-                f"original context length (e.g., Llama 3.1 = 131072, Mistral v0.3 = 32768)."
-            )
-            rope_scaling = {"type": rope_type.split(" ")[0], "factor": rope_factor}
-    if _prompt_yes_no("Enable NEFTune noise injection (improves training quality)?", default=False):
-        use_neftune = True
-        neftune_alpha = float(_prompt("NEFTune noise alpha", "5.0"))
+    rope_scaling = _collect_rope_scaling(max_length)
+    neftune_alpha = _collect_neftune_alpha()
+    use_neftune = neftune_alpha is not None
 
     use_oom_recovery = _prompt_yes_no(
         "Enable OOM recovery? (auto-halves batch size on CUDA out-of-memory, then retries)",
@@ -227,24 +405,7 @@ def run_wizard() -> str:
     )
 
     # Step 7: GaLore parameters (if selected)
-    galore_config = {}
-    if use_galore:
-        print("\n[7/8] GaLore Configuration")
-        galore_rank = _prompt_int("GaLore rank (lower = less memory)", 128, min_val=1, max_val=4096)
-        galore_optim = _prompt_choice(
-            "GaLore optimizer:",
-            ["galore_adamw (standard)", "galore_adamw_8bit (less memory)", "galore_adafactor (experimental)"],
-            default=1,
-        )
-        galore_config = {
-            "galore_enabled": True,
-            "galore_optim": galore_optim.split(" ")[0],
-            "galore_rank": galore_rank,
-            "galore_update_proj_gap": 200,
-            "galore_scale": 0.25,
-        }
-    else:
-        print("\n[7/8] Advanced Options")
+    galore_config = _collect_galore_config(use_galore)
 
     # Step 8: Build config
     print("\n[8/8] Output")
@@ -294,87 +455,38 @@ def run_wizard() -> str:
         },
     }
 
-    # Optional: Webhook
-    if _prompt_yes_no("Configure webhook notifications?", default=False):
-        webhook_url = _prompt("Webhook URL (or leave empty for env var)")
-        if webhook_url:
-            config["webhook"] = {"url": webhook_url}
-        else:
-            env_var = _prompt("Environment variable name for webhook URL", "FORGELM_WEBHOOK_URL")
-            config["webhook"] = {"url_env": env_var}
-
-    # Optional: Evaluation
-    if _prompt_yes_no("Enable auto-revert (discard model if quality drops)?", default=False):
-        max_loss = _prompt("Max acceptable loss (leave empty for baseline-only)", "")
-        config["evaluation"] = {
-            "auto_revert": True,
-            "max_acceptable_loss": float(max_loss) if max_loss else None,
-        }
-
-        # Safety evaluation
-        if _prompt_yes_no("Enable safety evaluation (Llama Guard)?", default=False):
-            scoring = _prompt_choice(
-                "Safety scoring mode:",
-                ["binary (simple safe/unsafe ratio)", "confidence_weighted (uses classifier confidence)"],
-                default=1,
-            )
-            scoring_mode = "confidence_weighted" if "confidence" in scoring else "binary"
-            safety_config = {
-                "enabled": True,
-                "test_prompts": "configs/safety_prompts/general_safety.jsonl",
-                "scoring": scoring_mode,
-            }
-            if scoring_mode == "confidence_weighted":
-                safety_config["min_safety_score"] = 0.85
-            if _prompt_yes_no("Track harm categories (S1-S14)?", default=False):
-                safety_config["track_categories"] = True
-                safety_config["severity_thresholds"] = {"critical": 0, "high": 0.01, "medium": 0.05}
-            config["evaluation"]["safety"] = safety_config
-
-    # Optional: Compliance (EU AI Act)
-    if _prompt_yes_no("Configure EU AI Act compliance metadata?", default=False):
-        config["compliance"] = {
-            "provider_name": _prompt("Organization name"),
-            "intended_purpose": _prompt("Intended purpose of the model"),
-            "risk_classification": _prompt_choice(
-                "Risk classification:",
-                ["minimal-risk", "limited-risk", "high-risk"],
-                default=1,
-            ),
-        }
+    webhook_section = _collect_webhook_config()
+    if webhook_section:
+        config["webhook"] = webhook_section
+
+    evaluation_section = _collect_evaluation_config()
+    if evaluation_section:
+        config["evaluation"] = evaluation_section
+
+    compliance_section = _collect_compliance_config()
+    if compliance_section:
+        config["compliance"] = compliance_section
 
     # Save
     config_filename = _prompt("Save config as", "my_config.yaml")
     if not config_filename.endswith((".yaml", ".yml")):
         config_filename += ".yaml"
-
-    try:
-        with open(config_filename, "w") as f:
-            yaml.dump(config, f, default_flow_style=False, sort_keys=False)
-        print(f"\n  Config saved to: {config_filename}")
-    except OSError as e:
-        print(f"\n  Error: Could not save config to {config_filename}: {e}")
-        config_filename = "my_config.yaml"
-        with open(config_filename, "w") as f:
-            yaml.dump(config, f, default_flow_style=False, sort_keys=False)
-        print(f"  Saved to fallback location: {config_filename}")
-
-    # Summary
-    print("\n" + "=" * 60)
-    print("  Configuration Summary")
-    print("=" * 60)
-    print(f"  Model:    {model_name}")
-    print(f"  Backend:  {suggested_backend}")
-    strategy_str = "GaLore" if use_galore else ("QLoRA" if load_in_4bit else "LoRA")
-    if use_dora:
-        strategy_str += " + DoRA"
-    print(f"  Strategy: {strategy_str}")
-    print(f"  Trainer:  {trainer_type.upper()}")
-    print(f"  LoRA:     r={lora_r}, alpha={lora_alpha}")
-    print(f"  Dataset:  {dataset_path}")
-    print(f"  Epochs:   {epochs}, Batch: {batch_size}")
-    print(f"  Output:   {output_dir}/final_model")
-    print()
+    config_filename = _save_config_to_file(config, config_filename)
+
+    _print_wizard_summary(
+        model_name=model_name,
+        suggested_backend=suggested_backend,
+        use_galore=use_galore,
+        load_in_4bit=load_in_4bit,
+        use_dora=use_dora,
+        trainer_type=trainer_type,
+        lora_r=lora_r,
+        lora_alpha=lora_alpha,
+        dataset_path=dataset_path,
+        epochs=epochs,
+        batch_size=batch_size,
+        output_dir=output_dir,
+    )
 
     # Quick run
     if _prompt_yes_no("Start training now?", default=False):
diff --git a/pyproject.toml b/pyproject.toml
index 6df5ca42..b80cf508 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "forgelm"
-version = "0.3.1rc1"
+version = "0.4.0"
 description = "Config-driven LLM fine-tuning with safety evaluation, EU AI Act compliance, and 6 alignment methods."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -71,6 +71,20 @@ merging = [
   "mergekit>=0.0.5",
 ]
 
+# Phase 10: GGUF export via llama-cpp-python's bundled convert_hf_to_gguf.py.
+# Produces f16 and q8_0 GGUF directly. K-quants (q4_k_m etc.) require a
+# separate llama-quantize step; see docs/guides/export.md for the full flow.
+# Linux and macOS only; Windows builds are available but less reliable.
+export = [
+  "llama-cpp-python>=0.2.90; sys_platform != 'win32'",
+]
+
+# Phase 10: rich terminal rendering for the forgelm chat REPL.
+# Falls back to plain text output when not installed.
+chat = [
+  "rich>=13.0.0",
+]
+
 dev = [
   "pytest>=8.0.0",
   "pytest-cov>=5.0.0",
@@ -106,6 +120,13 @@ line-length = 120
 select = ["F", "E9", "W", "B", "I"]
 ignore = ["B008", "B905"]
 
+# Bandit static-analysis config (consumed by Codacy + standalone bandit).
+# - B101 (assert_used) is disabled for tests/ because pytest requires asserts.
+# - tests/ is excluded from the broader scan; we still scan the package itself.
+[tool.bandit]
+exclude_dirs = ["tests", ".venv", "build", "dist"]
+skips = ["B101"]
+
 [tool.coverage.run]
 source = ["forgelm"]
 omit = ["forgelm/wizard.py"]
diff --git a/tests/test_alignment.py b/tests/test_alignment.py
index 7cae77d7..39850a89 100644
--- a/tests/test_alignment.py
+++ b/tests/test_alignment.py
@@ -36,16 +36,16 @@ def test_invalid_trainer_type_raises(self):
 
     def test_dpo_parameters(self):
         t = TrainingConfig(trainer_type="dpo", dpo_beta=0.2)
-        assert t.dpo_beta == 0.2
+        assert t.dpo_beta == pytest.approx(0.2)
 
     def test_simpo_parameters(self):
         t = TrainingConfig(trainer_type="simpo", simpo_gamma=1.0, simpo_beta=3.0)
-        assert t.simpo_gamma == 1.0
-        assert t.simpo_beta == 3.0
+        assert t.simpo_gamma == pytest.approx(1.0)
+        assert t.simpo_beta == pytest.approx(3.0)
 
     def test_kto_parameters(self):
         t = TrainingConfig(trainer_type="kto", kto_beta=0.05)
-        assert t.kto_beta == 0.05
+        assert t.kto_beta == pytest.approx(0.05)
 
     def test_grpo_parameters(self):
         t = TrainingConfig(
@@ -79,7 +79,7 @@ def test_dpo_config_from_yaml(self, tmp_path):
             yaml.dump(data, f)
         cfg = load_config(cfg_path)
         assert cfg.training.trainer_type == "dpo"
-        assert cfg.training.dpo_beta == 0.15
+        assert cfg.training.dpo_beta == pytest.approx(0.15)
 
     def test_simpo_config_from_yaml(self, tmp_path):
         data = _minimal_config(
@@ -93,7 +93,7 @@ def test_simpo_config_from_yaml(self, tmp_path):
             yaml.dump(data, f)
         cfg = load_config(cfg_path)
         assert cfg.training.trainer_type == "simpo"
-        assert cfg.training.simpo_gamma == 0.8
+        assert cfg.training.simpo_gamma == pytest.approx(0.8)
 
     def test_grpo_config_from_yaml(self, tmp_path):
         data = _minimal_config(
diff --git a/tests/test_benchmark.py b/tests/test_benchmark.py
index da62abd9..2c805df6 100644
--- a/tests/test_benchmark.py
+++ b/tests/test_benchmark.py
@@ -14,7 +14,7 @@ class TestBenchmarkResult:
     def test_default_values(self):
         r = BenchmarkResult()
         assert r.scores == {}
-        assert r.average_score == 0.0
+        assert r.average_score == pytest.approx(0.0)
         assert r.passed is True
         assert r.failure_reason is None
         assert r.raw_results is None
@@ -25,8 +25,8 @@ def test_with_scores(self):
             average_score=0.60,
             passed=True,
         )
-        assert r.scores["arc_easy"] == 0.65
-        assert r.average_score == 0.60
+        assert r.scores["arc_easy"] == pytest.approx(0.65)
+        assert r.average_score == pytest.approx(0.60)
 
     def test_failed_result(self):
         r = BenchmarkResult(
@@ -65,7 +65,7 @@ def test_with_tasks(self):
         )
         assert b.enabled is True
         assert len(b.tasks) == 2
-        assert b.min_score == 0.4
+        assert b.min_score == pytest.approx(0.4)
 
 
 class TestBenchmarkInConfig:
@@ -88,7 +88,7 @@ def test_evaluation_with_benchmark(self):
         assert cfg.evaluation.benchmark is not None
         assert cfg.evaluation.benchmark.enabled is True
         assert cfg.evaluation.benchmark.tasks == ["arc_easy"]
-        assert cfg.evaluation.benchmark.min_score == 0.5
+        assert cfg.evaluation.benchmark.min_score == pytest.approx(0.5)
 
     def test_evaluation_without_benchmark(self):
         data = {
@@ -155,9 +155,9 @@ def test_successful_benchmark(self, mock_hflm_cls, mock_lm_eval, mock_check):
                 finally:
                     bm._check_lm_eval_available = original_check
 
-        assert result.scores.get("arc_easy") == 0.65
-        assert result.scores.get("hellaswag") == 0.55
-        assert abs(result.average_score - 0.60) < 0.01
+        assert result.scores.get("arc_easy") == pytest.approx(0.65)
+        assert result.scores.get("hellaswag") == pytest.approx(0.55)
+        assert result.average_score == pytest.approx(0.60, abs=0.01)
         assert result.passed is True
 
     def test_min_score_failure(self):
@@ -197,7 +197,7 @@ def test_result_saved_to_file(self, tmp_path):
         assert os.path.exists(results_path)
         with open(results_path) as f:
             saved = json.load(f)
-        assert saved["scores"]["arc_easy"] == 0.65
+        assert saved["scores"]["arc_easy"] == pytest.approx(0.65)
         assert saved["passed"] is True
 
 
@@ -212,8 +212,8 @@ def test_train_result_benchmark_fields(self):
             benchmark_average=0.60,
             benchmark_passed=True,
         )
-        assert result.benchmark_scores["arc_easy"] == 0.65
-        assert result.benchmark_average == 0.60
+        assert result.benchmark_scores["arc_easy"] == pytest.approx(0.65)
+        assert result.benchmark_average == pytest.approx(0.60)
         assert result.benchmark_passed is True
 
     def test_train_result_no_benchmark(self):
diff --git a/tests/test_cli_phase10.py b/tests/test_cli_phase10.py
new file mode 100644
index 00000000..f20c281d
--- /dev/null
+++ b/tests/test_cli_phase10.py
@@ -0,0 +1,378 @@
+"""Tests for Phase 10 CLI additions: chat/export/deploy subcommands and --fit-check."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from unittest.mock import MagicMock, patch
+
+import pytest
+import yaml
+
+from forgelm.cli import (
+    EXIT_CONFIG_ERROR,
+    EXIT_SUCCESS,
+    EXIT_TRAINING_ERROR,
+    _run_fit_check,
+    main,
+)
+from forgelm.config import ForgeConfig
+
+
+def _minimal_cfg_dict(**overrides):
+    data = {
+        "model": {"name_or_path": "org/model"},
+        "lora": {},
+        "training": {},
+        "data": {"dataset_name_or_path": "org/dataset"},
+    }
+    data.update(overrides)
+    return data
+
+
+# ---------------------------------------------------------------------------
+# --fit-check flag
+# ---------------------------------------------------------------------------
+
+
+class TestFitCheckFlag:
+    def test_fit_check_text_output(self, tmp_path, capsys):
+        cfg_path = str(tmp_path / "config.yaml")
+        with open(cfg_path, "w") as f:
+            yaml.dump(_minimal_cfg_dict(), f)
+
+        torch_stub = MagicMock()
+        torch_stub.cuda.is_available.return_value = False
+
+        transformers_stub = MagicMock()
+        transformers_stub.AutoConfig.from_pretrained.return_value = MagicMock(
+            hidden_size=4096,
+            num_hidden_layers=32,
+            intermediate_size=11008,
+            vocab_size=32000,
+            num_attention_heads=32,
+            num_key_value_heads=32,
+        )
+
+        with patch("sys.argv", ["forgelm", "--config", cfg_path, "--fit-check"]):
+            with patch.dict(sys.modules, {"torch": torch_stub, "transformers": transformers_stub}):
+                with pytest.raises(SystemExit) as exc_info:
+                    main()
+        assert exc_info.value.code == EXIT_SUCCESS
+
+        captured = capsys.readouterr()
+        assert "VRAM Fit Check" in captured.out or "UNKNOWN" in captured.out
+
+    def test_fit_check_json_output(self, tmp_path, capsys):
+        cfg_path = str(tmp_path / "config.yaml")
+        with open(cfg_path, "w") as f:
+            yaml.dump(_minimal_cfg_dict(), f)
+
+        torch_stub = MagicMock()
+        torch_stub.cuda.is_available.return_value = False
+
+        transformers_stub = MagicMock()
+        transformers_stub.AutoConfig.from_pretrained.return_value = MagicMock(
+            hidden_size=4096,
+            num_hidden_layers=32,
+            intermediate_size=11008,
+            vocab_size=32000,
+            num_attention_heads=32,
+            num_key_value_heads=32,
+        )
+
+        with patch("sys.argv", ["forgelm", "--config", cfg_path, "--fit-check", "--output-format", "json"]):
+            with patch.dict(sys.modules, {"torch": torch_stub, "transformers": transformers_stub}):
+                with pytest.raises(SystemExit) as exc_info:
+                    main()
+        assert exc_info.value.code == EXIT_SUCCESS
+
+        captured = capsys.readouterr()
+        result = json.loads(captured.out)
+        assert "verdict" in result
+        assert "estimated_gb" in result
+        assert "breakdown" in result
+
+    def test_fit_check_without_config_fails(self):
+        with patch("sys.argv", ["forgelm", "--fit-check"]):
+            with pytest.raises(SystemExit) as exc_info:
+                main()
+        assert exc_info.value.code == EXIT_CONFIG_ERROR
+
+
+# ---------------------------------------------------------------------------
+# forgelm deploy subcommand
+# ---------------------------------------------------------------------------
+
+
+class TestDeployCLI:
+    def test_deploy_ollama_exits_success(self, tmp_path):
+        model_dir = tmp_path / "model"
+        model_dir.mkdir()
+        out = str(tmp_path / "Modelfile")
+        with patch("sys.argv", ["forgelm", "deploy", str(model_dir), "--target", "ollama", "--output", out]):
+            with pytest.raises(SystemExit) as exc_info:
+                main()
+        assert exc_info.value.code == EXIT_SUCCESS
+        assert os.path.isfile(out)
+
+    def test_deploy_vllm_exits_success(self, tmp_path):
+        out = str(tmp_path / "vllm.yaml")
+        # vllm accepts HF Hub IDs; no local-path validation
+        with patch("sys.argv", ["forgelm", "deploy", "./model", "--target", "vllm", "--output", out]):
+            with pytest.raises(SystemExit) as exc_info:
+                main()
+        assert exc_info.value.code == EXIT_SUCCESS
+
+    def test_deploy_tgi_exits_success(self, tmp_path):
+        model_dir = tmp_path / "model"
+        model_dir.mkdir()
+        out = str(tmp_path / "docker-compose.yaml")
+        with patch("sys.argv", ["forgelm", "deploy", str(model_dir), "--target", "tgi", "--output", out]):
+            with pytest.raises(SystemExit) as exc_info:
+                main()
+        assert exc_info.value.code == EXIT_SUCCESS
+
+    def test_deploy_hf_endpoints_exits_success(self, tmp_path):
+        out = str(tmp_path / "endpoint.json")
+        # hf-endpoints expects HF Hub repo IDs; no local-path validation
+        with patch("sys.argv", ["forgelm", "deploy", "./model", "--target", "hf-endpoints", "--output", out]):
+            with pytest.raises(SystemExit) as exc_info:
+                main()
+        assert exc_info.value.code == EXIT_SUCCESS
+
+    def test_deploy_bad_target_exits_error(self, tmp_path):
+        out = str(tmp_path / "out.cfg")
+        with patch("sys.argv", ["forgelm", "deploy", "./model", "--target", "bogus", "--output", out]):
+            with pytest.raises(SystemExit) as exc_info:
+                main()
+        assert exc_info.value.code == EXIT_TRAINING_ERROR
+
+    def test_deploy_json_output(self, tmp_path, capsys):
+        model_dir = tmp_path / "model"
+        model_dir.mkdir()
+        out = str(tmp_path / "Modelfile")
+        with patch(
+            "sys.argv",
+            ["forgelm", "--output-format", "json", "deploy", str(model_dir), "--target", "ollama", "--output", out],
+        ):
+            with pytest.raises(SystemExit) as exc_info:
+                main()
+        assert exc_info.value.code == EXIT_SUCCESS
+
+        captured = capsys.readouterr()
+        result = json.loads(captured.out)
+        assert result["success"] is True
+        assert result["target"] == "ollama"
+
+    def test_deploy_with_system_prompt(self, tmp_path):
+        model_dir = tmp_path / "model"
+        model_dir.mkdir()
+        out = str(tmp_path / "Modelfile")
+        with patch(
+            "sys.argv",
+            [
+                "forgelm",
+                "deploy",
+                str(model_dir),
+                "--target",
+                "ollama",
+                "--output",
+                out,
+                "--system",
+                "You are helpful.",
+            ],
+        ):
+            with pytest.raises(SystemExit) as exc_info:
+                main()
+        assert exc_info.value.code == EXIT_SUCCESS
+        with open(out) as f:
+            content = f.read()
+        assert "You are helpful." in content
+
+    def test_deploy_does_not_require_config(self, tmp_path):
+        """forgelm deploy must work without --config."""
+        model_dir = tmp_path / "model"
+        model_dir.mkdir()
+        out = str(tmp_path / "Modelfile")
+        with patch("sys.argv", ["forgelm", "deploy", str(model_dir), "--target", "ollama", "--output", out]):
+            with pytest.raises(SystemExit) as exc_info:
+                main()
+        # Must exit with success, not CONFIG_ERROR
+        assert exc_info.value.code != EXIT_CONFIG_ERROR
+
+
+# ---------------------------------------------------------------------------
+# forgelm export subcommand
+# ---------------------------------------------------------------------------
+
+
+class TestExportCLI:
+    def test_export_missing_llama_cpp_exits_error(self, tmp_path):
+        out = str(tmp_path / "model.gguf")
+        with patch.dict(sys.modules, {"llama_cpp": None}):
+            with patch("sys.argv", ["forgelm", "export", "./model", "--output", out]):
+                with pytest.raises(SystemExit) as exc_info:
+                    main()
+        assert exc_info.value.code == EXIT_TRAINING_ERROR
+
+    def test_export_json_on_failure(self, tmp_path, capsys):
+        out = str(tmp_path / "model.gguf")
+        with patch.dict(sys.modules, {"llama_cpp": None}):
+            with patch(
+                "sys.argv",
+                [
+                    "forgelm",
+                    "--output-format",
+                    "json",
+                    "export",
+                    "./model",
+                    "--output",
+                    out,
+                ],
+            ):
+                with pytest.raises(SystemExit) as exc_info:
+                    main()
+
+        assert exc_info.value.code == EXIT_TRAINING_ERROR
+        captured = capsys.readouterr()
+        result = json.loads(captured.out)
+        assert result["success"] is False
+
+    def test_export_does_not_require_config(self, tmp_path):
+        """forgelm export must work without --config."""
+        out = str(tmp_path / "model.gguf")
+        with patch.dict(sys.modules, {"llama_cpp": None}):
+            with patch("sys.argv", ["forgelm", "export", "./model", "--output", out]):
+                with pytest.raises(SystemExit) as exc_info:
+                    main()
+        # Error because llama_cpp missing — but NOT CONFIG_ERROR
+        assert exc_info.value.code != EXIT_CONFIG_ERROR
+
+    def test_export_success_path(self, tmp_path):
+        out = str(tmp_path / "model.gguf")
+
+        llama_cpp_stub = MagicMock()
+        pkg_dir = str(tmp_path / "llama_cpp")
+        os.makedirs(pkg_dir, exist_ok=True)
+        llama_cpp_stub.__file__ = os.path.join(pkg_dir, "__init__.py")
+        open(os.path.join(pkg_dir, "convert_hf_to_gguf.py"), "w").close()
+
+        def fake_run(cmd, **kwargs):
+            actual = cmd[cmd.index("--outfile") + 1] if "--outfile" in cmd else out
+            with open(actual, "wb") as f:
+                f.write(b"gguf data")
+            m = MagicMock()
+            m.returncode = 0
+            m.stderr = ""
+            return m
+
+        with patch.dict(sys.modules, {"llama_cpp": llama_cpp_stub}):
+            with patch("subprocess.run", side_effect=fake_run):
+                with patch(
+                    "sys.argv",
+                    ["forgelm", "export", str(tmp_path), "--output", out, "--quant", "q8_0"],
+                ):
+                    with pytest.raises(SystemExit) as exc_info:
+                        main()
+
+        assert exc_info.value.code == EXIT_SUCCESS
+
+
+# ---------------------------------------------------------------------------
+# forgelm chat subcommand (smoke tests; no actual model loaded)
+# ---------------------------------------------------------------------------
+
+
+class TestChatCLI:
+    def test_chat_does_not_require_config(self):
+        """Running forgelm chat without --config must not exit with CONFIG_ERROR."""
+        with patch("forgelm.cli._run_chat_cmd", side_effect=KeyboardInterrupt):
+            with patch("sys.argv", ["forgelm", "chat", "./model"]):
+                with pytest.raises(SystemExit) as exc_info:
+                    main()
+        # Should be SUCCESS (KeyboardInterrupt handled gracefully in _run_chat_cmd)
+        assert exc_info.value.code != EXIT_CONFIG_ERROR
+
+    def test_chat_subcommand_registered(self, capsys):
+        """forgelm chat --help must succeed and document model_path."""
+        with patch("sys.argv", ["forgelm", "chat", "--help"]):
+            with pytest.raises(SystemExit) as exc_info:
+                main()
+        assert exc_info.value.code == 0
+        captured = capsys.readouterr()
+        assert "model_path" in captured.out
+
+
+# ---------------------------------------------------------------------------
+# _run_fit_check helper
+# ---------------------------------------------------------------------------
+
+
+class TestRunFitCheckHelper:
+    def test_text_output_contains_verdict(self, capsys):
+        from forgelm.fit_check import FitCheckResult
+
+        mock_result = FitCheckResult(
+            verdict="FITS",
+            estimated_gb=7.5,
+            available_gb=24.0,
+            recommendations=[],
+            breakdown={"base_model_gb": 4.5},
+        )
+
+        cfg = ForgeConfig(**_minimal_cfg_dict())
+        with patch("forgelm.fit_check.estimate_vram", return_value=mock_result):
+            _run_fit_check(cfg, "text")
+
+        captured = capsys.readouterr()
+        assert "FITS" in captured.out
+
+    def test_json_output_structure(self, capsys):
+        from forgelm.fit_check import FitCheckResult
+
+        mock_result = FitCheckResult(
+            verdict="OOM",
+            estimated_gb=35.0,
+            available_gb=12.0,
+            recommendations=["Reduce batch size"],
+            breakdown={"base_model_gb": 18.0},
+        )
+
+        cfg = ForgeConfig(**_minimal_cfg_dict())
+        with patch("forgelm.fit_check.estimate_vram", return_value=mock_result):
+            _run_fit_check(cfg, "json")
+
+        captured = capsys.readouterr()
+        result = json.loads(captured.out)
+        assert result["verdict"] == "OOM"
+        assert result["estimated_gb"] == pytest.approx(35.0)
+        assert result["recommendations"] == ["Reduce batch size"]
+
+
+# ---------------------------------------------------------------------------
+# Subcommand routing (no training flow triggered)
+# ---------------------------------------------------------------------------
+
+
+class TestSubcommandRouting:
+    def test_existing_flags_unchanged_after_subcommand_addition(self, tmp_path):
+        """--dry-run must still work without interference from subparsers."""
+        cfg_path = str(tmp_path / "config.yaml")
+        with open(cfg_path, "w") as f:
+            yaml.dump(_minimal_cfg_dict(), f)
+
+        with patch("sys.argv", ["forgelm", "--config", cfg_path, "--dry-run"]):
+            with pytest.raises(SystemExit) as exc_info:
+                main()
+        assert exc_info.value.code == EXIT_SUCCESS
+
+    def test_wizard_still_works(self):
+        """--wizard flow must be unaffected."""
+        mock_wizard = MagicMock(return_value=None)
+        with patch("forgelm.wizard.run_wizard", mock_wizard):
+            with patch("sys.argv", ["forgelm", "--wizard"]):
+                with pytest.raises(SystemExit) as exc_info:
+                    main()
+        assert exc_info.value.code == EXIT_SUCCESS
diff --git a/tests/test_compliance.py b/tests/test_compliance.py
index 2570386a..f97194b7 100644
--- a/tests/test_compliance.py
+++ b/tests/test_compliance.py
@@ -3,6 +3,8 @@
 import json
 import os
 
+import pytest
+
 from forgelm.compliance import (
     _sanitize_md,
     compute_dataset_fingerprint,
@@ -32,7 +34,7 @@ class TestSafetyConfig:
     def test_defaults(self):
         s = SafetyConfig()
         assert s.enabled is False
-        assert s.max_safety_regression == 0.05
+        assert s.max_safety_regression == pytest.approx(0.05)
 
     def test_custom(self):
         s = SafetyConfig(enabled=True, classifier="custom/guard", max_safety_regression=0.1)
@@ -45,7 +47,7 @@ def test_defaults(self):
         j = JudgeConfig()
         assert j.enabled is False
         assert j.judge_model == "gpt-4o"
-        assert j.min_score == 5.0
+        assert j.min_score == pytest.approx(5.0)
 
     def test_local_judge(self):
         j = JudgeConfig(enabled=True, judge_model="/local/judge", judge_api_key_env=None)
@@ -72,7 +74,7 @@ def test_eval_config_with_judge(self):
                 }
             )
         )
-        assert cfg.evaluation.llm_judge.min_score == 7.0
+        assert cfg.evaluation.llm_judge.min_score == pytest.approx(7.0)
 
     def test_eval_config_with_all(self):
         cfg = ForgeConfig(
@@ -119,12 +121,12 @@ def test_failed(self):
 class TestTrainResultPhase6:
     def test_resource_usage(self):
         r = TrainResult(success=True, resource_usage={"gpu_hours": 2.4, "peak_vram_gb": 22.1})
-        assert r.resource_usage["gpu_hours"] == 2.4
+        assert r.resource_usage["gpu_hours"] == pytest.approx(2.4)
 
     def test_safety_and_judge(self):
         r = TrainResult(success=True, safety_passed=True, judge_score=8.5)
         assert r.safety_passed is True
-        assert r.judge_score == 8.5
+        assert r.judge_score == pytest.approx(8.5)
 
 
 # --- Compliance ---
@@ -151,7 +153,7 @@ def test_generate_manifest(self):
         assert manifest["model_lineage"]["base_model"] == "org/model"
         assert manifest["training_parameters"]["trainer_type"] == "sft"
         assert manifest["data_provenance"]["primary_dataset"] == "org/dataset"
-        assert manifest["evaluation_results"]["metrics"]["eval_loss"] == 0.5
+        assert manifest["evaluation_results"]["metrics"]["eval_loss"] == pytest.approx(0.5)
 
     def test_manifest_with_resource_usage(self):
         cfg = ForgeConfig(**_minimal_config())
@@ -160,7 +162,7 @@ def test_manifest_with_resource_usage(self):
             metrics={"eval_loss": 0.5},
             resource_usage={"gpu_hours": 1.5, "peak_vram_gb": 16.0},
         )
-        assert manifest["resource_usage"]["gpu_hours"] == 1.5
+        assert manifest["resource_usage"]["gpu_hours"] == pytest.approx(1.5)
 
 
 class TestComplianceExport:
@@ -170,7 +172,7 @@ def test_export_creates_files(self, tmp_path):
         cfg = ForgeConfig(**_minimal_config())
         manifest = generate_training_manifest(cfg, metrics={"eval_loss": 0.5})
         output_dir = str(tmp_path / "compliance")
-        files = export_compliance_artifacts(manifest, cfg, output_dir)
+        files = export_compliance_artifacts(manifest, output_dir)
         assert len(files) == 3
         assert all(os.path.isfile(f) for f in files)
         # Verify JSON is valid
@@ -194,9 +196,7 @@ def test_restores_hash_chain_on_second_instance(self, tmp_path):
 
         log2 = AuditLogger(str(tmp_path))
         # Must NOT reset to "genesis" — should read from the existing file
-        assert log2._prev_hash != "genesis", (
-            "Second AuditLogger instance must not reset the hash chain to 'genesis'"
-        )
+        assert log2._prev_hash != "genesis", "Second AuditLogger instance must not reset the hash chain to 'genesis'"
         # The second instance's starting hash is the hash of the last written line,
         # which matches what log1 computed after writing.
         assert log2._prev_hash == hash_after_first_event
diff --git a/tests/test_config.py b/tests/test_config.py
index d465f67f..2c851530 100644
--- a/tests/test_config.py
+++ b/tests/test_config.py
@@ -66,7 +66,7 @@ def test_defaults(self):
         lora = LoraConfigModel()
         assert lora.r == 8
         assert lora.alpha == 16
-        assert lora.dropout == 0.1
+        assert lora.dropout == pytest.approx(0.1)
         assert lora.bias == "none"
         assert lora.use_dora is False
         assert lora.target_modules == ["q_proj", "v_proj"]
@@ -94,7 +94,7 @@ def test_defaults(self):
 
     def test_custom_values(self):
         t = TrainingConfig(learning_rate=1e-4, num_train_epochs=5)
-        assert t.learning_rate == 1e-4
+        assert t.learning_rate == pytest.approx(1e-4)
         assert t.num_train_epochs == 5
 
 
@@ -111,7 +111,7 @@ def test_defaults(self):
     def test_auto_revert_with_max_loss(self):
         e = EvaluationConfig(auto_revert=True, max_acceptable_loss=2.5)
         assert e.auto_revert is True
-        assert e.max_acceptable_loss == 2.5
+        assert e.max_acceptable_loss == pytest.approx(2.5)
 
 
 # --- WebhookConfig ---
diff --git a/tests/test_cost_estimation.py b/tests/test_cost_estimation.py
index f7b64a58..12649580 100644
--- a/tests/test_cost_estimation.py
+++ b/tests/test_cost_estimation.py
@@ -14,11 +14,11 @@ def test_default_none(self):
 
     def test_custom_cost(self):
         tc = TrainingConfig(gpu_cost_per_hour=3.50)
-        assert tc.gpu_cost_per_hour == 3.50
+        assert tc.gpu_cost_per_hour == pytest.approx(3.50)
 
     def test_in_full_config(self):
         cfg = ForgeConfig(**minimal_config(training={"gpu_cost_per_hour": 2.00}))
-        assert cfg.training.gpu_cost_per_hour == 2.00
+        assert cfg.training.gpu_cost_per_hour == pytest.approx(2.00)
 
     def test_config_template_still_parses(self):
         from forgelm.config import load_config
@@ -34,7 +34,7 @@ def test_default_none(self):
 
     def test_with_cost(self):
         r = TrainResult(success=True, estimated_cost_usd=0.1234)
-        assert r.estimated_cost_usd == 0.1234
+        assert r.estimated_cost_usd == pytest.approx(0.1234)
 
 
 class TestGpuPricing:
@@ -92,8 +92,8 @@ def test_json_output_includes_cost(self):
             sys.stdout = old_stdout
 
         output = json.loads(captured.getvalue())
-        assert output["estimated_cost_usd"] == 0.5678
-        assert output["resource_usage"]["gpu_hours"] == 0.162
+        assert output["estimated_cost_usd"] == pytest.approx(0.5678)
+        assert output["resource_usage"]["gpu_hours"] == pytest.approx(0.162)
 
     def test_json_output_omits_cost_when_none(self):
         import io
diff --git a/tests/test_deploy.py b/tests/test_deploy.py
new file mode 100644
index 00000000..19cbf687
--- /dev/null
+++ b/tests/test_deploy.py
@@ -0,0 +1,258 @@
+"""Unit tests for forgelm.deploy module."""
+
+from __future__ import annotations
+
+import json
+import os
+
+import yaml
+
+from forgelm.deploy import (
+    SUPPORTED_TARGETS,
+    DeployResult,
+    _hf_endpoints_json,
+    _ollama_modelfile,
+    _tgi_compose,
+    _vllm_config,
+    generate_deploy_config,
+)
+
+# ---------------------------------------------------------------------------
+# Constant / structure tests
+# ---------------------------------------------------------------------------
+
+
+class TestConstants:
+    def test_supported_targets(self):
+        assert "ollama" in SUPPORTED_TARGETS
+        assert "vllm" in SUPPORTED_TARGETS
+        assert "tgi" in SUPPORTED_TARGETS
+        assert "hf-endpoints" in SUPPORTED_TARGETS
+
+    def test_deploy_result_dataclass(self, tmp_path):
+        r = DeployResult(success=True, target="ollama", output_path=str(tmp_path / "Modelfile"))
+        assert r.success is True
+        assert r.error is None
+
+
+# ---------------------------------------------------------------------------
+# Per-target generator tests (no file I/O)
+# ---------------------------------------------------------------------------
+
+
+class TestOllamaModelfile:
+    def test_contains_from_directive(self):
+        content = _ollama_modelfile("/path/to/model", None, 4096, 0.7, 50, 0.9)
+        assert "FROM /path/to/model" in content
+
+    def test_contains_parameters(self):
+        content = _ollama_modelfile("/path/to/model", None, 4096, 0.7, 50, 0.9)
+        assert "PARAMETER temperature 0.7" in content
+        assert "PARAMETER top_k 50" in content
+        assert "PARAMETER top_p 0.9" in content
+        assert "PARAMETER num_ctx 4096" in content
+
+    def test_system_prompt_included(self):
+        content = _ollama_modelfile("/model", "Be helpful.", 2048, 0.8, 40, 0.95)
+        assert "SYSTEM" in content
+        assert "Be helpful." in content
+
+    def test_system_prompt_with_quotes_escaped(self):
+        content = _ollama_modelfile("/model", 'Say "hello"', 2048, 0.7, 50, 0.9)
+        assert '\\"hello\\"' in content
+
+    def test_no_system_when_none(self):
+        content = _ollama_modelfile("/model", None, 2048, 0.7, 50, 0.9)
+        assert "SYSTEM" not in content
+
+    def test_newline_terminated(self):
+        content = _ollama_modelfile("/model", None, 2048, 0.7, 50, 0.9)
+        assert content.endswith("\n")
+
+
+class TestVllmConfig:
+    def test_is_valid_yaml(self):
+        content = _vllm_config("/model", 4096, False, 0.9, "bfloat16")
+        # Should parse without error (comment lines may be at end)
+        parsed = yaml.safe_load(content.split("\n# ")[0])
+        assert isinstance(parsed, dict)
+
+    def test_contains_model_field(self):
+        content = _vllm_config("/model", 4096, False, 0.9, "bfloat16")
+        assert "model: /model" in content
+
+    def test_gpu_memory_utilization_present(self):
+        content = _vllm_config("/model", 4096, False, 0.85, "bfloat16")
+        assert "0.85" in content
+
+    def test_trust_remote_code(self):
+        content = _vllm_config("/model", 4096, True, 0.9, "bfloat16")
+        assert "true" in content.lower()
+
+
+class TestTgiCompose:
+    def test_is_valid_yaml(self):
+        content = _tgi_compose("/model", 2048, 4096, 8080)
+        # Skip header comment lines
+        body = "\n".join(l for l in content.splitlines() if not l.startswith("#"))
+        parsed = yaml.safe_load(body)
+        assert isinstance(parsed, dict)
+        assert "services" in parsed
+
+    def test_contains_model_path(self):
+        content = _tgi_compose("/my/model", 2048, 4096, 8080)
+        assert "/my/model" in content
+
+    def test_port_appears_in_config(self):
+        content = _tgi_compose("/model", 2048, 4096, 9090)
+        assert "9090" in content
+
+    def test_max_tokens_in_command(self):
+        content = _tgi_compose("/model", 1024, 2048, 8080)
+        assert "max-input-length 1024" in content
+        assert "max-total-tokens 2048" in content
+
+
+class TestHfEndpointsJson:
+    def test_is_valid_json(self):
+        content = _hf_endpoints_json("/model", "text-generation", "x2", "nvidia-a10g", "us-east-1", "pytorch")
+        parsed = json.loads(content)
+        assert isinstance(parsed, dict)
+
+    def test_model_repository(self):
+        content = _hf_endpoints_json("/my/model", "text-generation", "x2", "nvidia-a10g", "us-east-1", "pytorch")
+        parsed = json.loads(content)
+        assert parsed["model"]["repository"] == "/my/model"
+
+    def test_framework_present(self):
+        content = _hf_endpoints_json("/model", "text-generation", "x2", "nvidia-a10g", "us-east-1", "pytorch")
+        parsed = json.loads(content)
+        assert parsed["model"]["framework"] == "pytorch"
+
+    def test_region_in_cloud(self):
+        content = _hf_endpoints_json("/model", "text-generation", "x2", "nvidia-a10g", "eu-west-1", "pytorch")
+        parsed = json.loads(content)
+        assert parsed["cloud"]["region"] == "eu-west-1"
+
+
+# ---------------------------------------------------------------------------
+# generate_deploy_config integration tests (with file I/O)
+# ---------------------------------------------------------------------------
+
+
+class TestGenerateDeployConfig:
+    def test_ollama_writes_file(self, tmp_path):
+        model_dir = tmp_path / "model"
+        model_dir.mkdir()
+        out = str(tmp_path / "Modelfile")
+        result = generate_deploy_config(str(model_dir), "ollama", out)
+
+        assert result.success is True
+        assert result.target == "ollama"
+        assert result.output_path == out
+        assert os.path.isfile(out)
+
+    def test_ollama_file_content_valid(self, tmp_path):
+        model_dir = tmp_path / "model"
+        model_dir.mkdir()
+        out = str(tmp_path / "Modelfile")
+        generate_deploy_config(str(model_dir), "ollama", out, system_prompt="Be brief.")
+
+        with open(out) as f:
+            content = f.read()
+        assert f"FROM {model_dir}" in content
+        assert "Be brief." in content
+
+    def test_vllm_writes_file(self, tmp_path):
+        out = str(tmp_path / "vllm.yaml")
+        # vllm accepts HF Hub IDs; no local-path requirement
+        result = generate_deploy_config("/model", "vllm", out)
+
+        assert result.success is True
+        assert os.path.isfile(out)
+
+    def test_tgi_writes_file(self, tmp_path):
+        model_dir = tmp_path / "model"
+        model_dir.mkdir()
+        out = str(tmp_path / "docker-compose.yaml")
+        result = generate_deploy_config(str(model_dir), "tgi", out, port=8080)
+
+        assert result.success is True
+        assert os.path.isfile(out)
+
+    def test_hf_endpoints_writes_file(self, tmp_path):
+        out = str(tmp_path / "endpoint.json")
+        # hf-endpoints expects HF Hub repository IDs; no local-path requirement
+        result = generate_deploy_config("/model", "hf-endpoints", out)
+
+        assert result.success is True
+        assert os.path.isfile(out)
+        with open(out) as f:
+            parsed = json.load(f)
+        assert "model" in parsed
+
+    def test_default_filename_used_when_output_none(self, tmp_path, monkeypatch):
+        monkeypatch.chdir(tmp_path)
+        (tmp_path / "model").mkdir()
+        result = generate_deploy_config("./model", "ollama")
+        assert result.success is True
+        assert result.output_path == "Modelfile"
+        assert os.path.isfile("Modelfile")
+
+    def test_unsupported_target_returns_failure(self):
+        result = generate_deploy_config("/model", "nonexistent_runtime")
+        assert result.success is False
+        assert "nonexistent_runtime" in result.error
+
+    def test_tgi_rejects_non_local_path(self, tmp_path):
+        out = str(tmp_path / "docker-compose.yaml")
+        # An HF Hub ID like "meta-llama/Llama-3-8B" must not silently produce
+        # a config that tries to mount a non-existent volume at deploy time.
+        result = generate_deploy_config("meta-llama/Llama-3-8B", "tgi", out)
+        assert result.success is False
+        assert "local model directory" in result.error.lower()
+
+    def test_ollama_rejects_non_local_path(self, tmp_path):
+        out = str(tmp_path / "Modelfile")
+        result = generate_deploy_config("nonexistent/model-id", "ollama", out)
+        assert result.success is False
+        assert "local model directory" in result.error.lower()
+
+    def test_result_contains_content(self, tmp_path):
+        model_dir = tmp_path / "model"
+        model_dir.mkdir()
+        out = str(tmp_path / "Modelfile")
+        result = generate_deploy_config(str(model_dir), "ollama", out)
+
+        assert result.content is not None
+        assert f"FROM {model_dir}" in result.content
+
+    def test_target_case_insensitive(self, tmp_path):
+        model_dir = tmp_path / "model"
+        model_dir.mkdir()
+        out = str(tmp_path / "Modelfile")
+        result = generate_deploy_config(str(model_dir), "Ollama", out)
+        assert result.success is True
+
+    def test_vllm_trust_remote_code_propagated(self, tmp_path):
+        out = str(tmp_path / "vllm.yaml")
+        generate_deploy_config("/model", "vllm", out, trust_remote_code=True)
+
+        with open(out) as f:
+            content = f.read()
+        assert "true" in content.lower()
+
+    def test_json_roundtrip_for_hf_endpoints(self, tmp_path):
+        from forgelm.deploy import HFEndpointsOptions
+
+        out = str(tmp_path / "ep.json")
+        generate_deploy_config(
+            "./model",
+            "hf-endpoints",
+            out,
+            hf_endpoints=HFEndpointsOptions(instance_type="nvidia-a100", region="eu-west-3"),
+        )
+        with open(out) as f:
+            parsed = json.load(f)
+        assert parsed["compute"]["instanceType"] == "nvidia-a100"
+        assert parsed["cloud"]["region"] == "eu-west-3"
diff --git a/tests/test_export.py b/tests/test_export.py
new file mode 100644
index 00000000..52e8e4ef
--- /dev/null
+++ b/tests/test_export.py
@@ -0,0 +1,296 @@
+"""Unit tests for forgelm.export module."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import sys
+from unittest.mock import MagicMock, patch
+
+from forgelm.export import (
+    SUPPORTED_FORMATS,
+    SUPPORTED_QUANTS,
+    ExportResult,
+    _sha256_file,
+    _update_integrity_manifest,
+    export_model,
+)
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+
+class TestConstants:
+    def test_gguf_in_formats(self):
+        assert "gguf" in SUPPORTED_FORMATS
+
+    def test_quants_present(self):
+        for q in ("q2_k", "q3_k_m", "q4_k_m", "q5_k_m", "q8_0", "f16"):
+            assert q in SUPPORTED_QUANTS
+
+    def test_export_result_dataclass(self):
+        r = ExportResult(success=True, output_path="/out.gguf", quant="q4_k_m")
+        assert r.success is True
+        assert r.sha256 is None
+        assert r.error is None
+
+
+# ---------------------------------------------------------------------------
+# _sha256_file
+# ---------------------------------------------------------------------------
+
+
+class TestSha256File:
+    def test_correct_digest(self, tmp_path):
+        p = tmp_path / "test.bin"
+        p.write_bytes(b"hello world")
+        expected = hashlib.sha256(b"hello world").hexdigest()
+        assert _sha256_file(str(p)) == expected
+
+    def test_empty_file(self, tmp_path):
+        p = tmp_path / "empty.bin"
+        p.write_bytes(b"")
+        expected = hashlib.sha256(b"").hexdigest()
+        assert _sha256_file(str(p)) == expected
+
+    def test_large_file_consistent(self, tmp_path):
+        data = b"X" * (200 * 1024)  # 200 KB — forces chunked read
+        p = tmp_path / "large.bin"
+        p.write_bytes(data)
+        expected = hashlib.sha256(data).hexdigest()
+        assert _sha256_file(str(p)) == expected
+
+
+# ---------------------------------------------------------------------------
+# _update_integrity_manifest
+# ---------------------------------------------------------------------------
+
+
+class TestUpdateIntegrityManifest:
+    def test_updates_existing_manifest(self, tmp_path):
+        integrity_path = tmp_path / "model_integrity.json"
+        integrity_path.write_text(json.dumps({"verified_at": "2026-01-01", "artifacts": []}))
+
+        result = ExportResult(
+            success=True,
+            output_path=str(tmp_path / "model.gguf"),
+            format="gguf",
+            quant="q4_k_m",
+            sha256="abc123",
+            size_bytes=1024,
+        )
+        _update_integrity_manifest(str(tmp_path), result)
+
+        with open(str(integrity_path)) as f:
+            data = json.load(f)
+
+        assert len(data["exported_artifacts"]) == 1
+        artifact = data["exported_artifacts"][0]
+        assert artifact["sha256"] == "abc123"
+        assert artifact["quant"] == "q4_k_m"
+
+    def test_no_error_when_manifest_missing(self, tmp_path):
+        result = ExportResult(success=True, output_path=str(tmp_path / "model.gguf"), sha256="abc")
+        # Should not raise even though model_integrity.json doesn't exist
+        _update_integrity_manifest(str(tmp_path), result)
+
+    def test_appends_multiple_artifacts(self, tmp_path):
+        integrity_path = tmp_path / "model_integrity.json"
+        integrity_path.write_text(json.dumps({"exported_artifacts": [{"sha256": "first"}]}))
+
+        result = ExportResult(success=True, output_path="/m.gguf", sha256="second", quant="q8_0")
+        _update_integrity_manifest(str(tmp_path), result)
+
+        with open(str(integrity_path)) as f:
+            data = json.load(f)
+        assert len(data["exported_artifacts"]) == 2
+
+
+# ---------------------------------------------------------------------------
+# export_model — mocked converter
+# ---------------------------------------------------------------------------
+
+
+class TestExportModel:
+    def _mock_successful_conversion(self, tmp_path, content=b"mock gguf data"):
+        """Return a mock that simulates successful subprocess conversion."""
+        output_path = str(tmp_path / "model.gguf")
+
+        def fake_run(cmd, **kwargs):
+            # Write to whatever path the converter was invoked with so K-quant
+            # rerouting (output.gguf → output.f16.gguf) is handled transparently.
+            actual = cmd[cmd.index("--outfile") + 1] if "--outfile" in cmd else output_path
+            with open(actual, "wb") as f:
+                f.write(content)
+            result = MagicMock()
+            result.returncode = 0
+            result.stderr = ""
+            result.stdout = "Conversion successful"
+            return result
+
+        return output_path, fake_run
+
+    def test_unsupported_format_returns_failure(self, tmp_path):
+        result = export_model(str(tmp_path / "model"), str(tmp_path / "out.xyz"), output_format="xyz")
+        assert result.success is False
+        assert "xyz" in result.error
+
+    def test_unsupported_quant_returns_failure(self, tmp_path):
+        result = export_model(str(tmp_path / "model"), str(tmp_path / "out.gguf"), quant="q99_k")
+        assert result.success is False
+        assert "q99_k" in result.error
+
+    def test_missing_llama_cpp_returns_failure(self, tmp_path):
+        with patch.dict(sys.modules, {"llama_cpp": None}):
+            result = export_model(str(tmp_path / "model"), str(tmp_path / "out.gguf"))
+        assert result.success is False
+        assert "forgelm[export]" in result.error
+
+    def test_successful_export_returns_sha256(self, tmp_path):
+        output_path, fake_run = self._mock_successful_conversion(tmp_path)
+        converter_path = str(tmp_path / "convert_hf_to_gguf.py")
+        open(converter_path, "w").close()  # empty placeholder
+
+        llama_cpp_stub = MagicMock()
+        llama_cpp_stub.__file__ = str(tmp_path / "llama_cpp" / "__init__.py")
+        # Put converter next to the package
+        os.makedirs(str(tmp_path / "llama_cpp"), exist_ok=True)
+        converter_in_pkg = str(tmp_path / "llama_cpp" / "convert_hf_to_gguf.py")
+        open(converter_in_pkg, "w").close()
+
+        with patch.dict(sys.modules, {"llama_cpp": llama_cpp_stub}):
+            with patch("subprocess.run", side_effect=fake_run):
+                result = export_model(
+                    str(tmp_path / "model"),
+                    output_path,
+                    quant="q8_0",
+                    update_integrity=False,
+                )
+
+        assert result.success is True
+        assert result.sha256 is not None
+        assert len(result.sha256) == 64  # SHA-256 hex digest
+        assert result.size_bytes > 0
+        assert result.quant == "q8_0"
+
+    def test_kquant_produces_f16_intermediate(self, tmp_path):
+        """K-quant requests must yield result.quant='f16' and a .f16.gguf path
+        so the integrity manifest never claims a SHA-256 it can't back."""
+        output_path, fake_run = self._mock_successful_conversion(tmp_path)
+        llama_cpp_stub = MagicMock()
+        os.makedirs(str(tmp_path / "llama_cpp"), exist_ok=True)
+        llama_cpp_stub.__file__ = str(tmp_path / "llama_cpp" / "__init__.py")
+        open(str(tmp_path / "llama_cpp" / "convert_hf_to_gguf.py"), "w").close()
+
+        with patch.dict(sys.modules, {"llama_cpp": llama_cpp_stub}):
+            with patch("subprocess.run", side_effect=fake_run):
+                result = export_model(
+                    str(tmp_path / "model"),
+                    output_path,
+                    quant="q4_k_m",
+                    update_integrity=False,
+                )
+
+        assert result.success is True
+        # Actual file written must reflect f16, not q4_k_m
+        assert result.quant == "f16"
+        assert result.output_path.endswith(".f16.gguf")
+        assert os.path.isfile(result.output_path)
+
+    def test_converter_exit_nonzero_returns_failure(self, tmp_path):
+        llama_cpp_stub = MagicMock()
+        os.makedirs(str(tmp_path / "llama_cpp"), exist_ok=True)
+        llama_cpp_stub.__file__ = str(tmp_path / "llama_cpp" / "__init__.py")
+        open(str(tmp_path / "llama_cpp" / "convert_hf_to_gguf.py"), "w").close()
+
+        def failing_run(cmd, **kwargs):
+            m = MagicMock()
+            m.returncode = 1
+            m.stderr = "CUDA error"
+            m.stdout = ""
+            return m
+
+        with patch.dict(sys.modules, {"llama_cpp": llama_cpp_stub}):
+            with patch("subprocess.run", side_effect=failing_run):
+                result = export_model(str(tmp_path / "model"), str(tmp_path / "out.gguf"))
+
+        assert result.success is False
+        assert "1" in result.error  # exit code in message
+
+    def test_converter_not_found_in_package(self, tmp_path):
+        llama_cpp_stub = MagicMock()
+        os.makedirs(str(tmp_path / "llama_cpp"), exist_ok=True)
+        llama_cpp_stub.__file__ = str(tmp_path / "llama_cpp" / "__init__.py")
+        # Do NOT create convert_hf_to_gguf.py — simulate missing script
+
+        with patch.dict(sys.modules, {"llama_cpp": llama_cpp_stub}):
+            result = export_model(str(tmp_path / "model"), str(tmp_path / "out.gguf"))
+
+        assert result.success is False
+        assert "not found" in result.error.lower() or "0.2.90" in result.error
+
+    def test_integrity_manifest_updated_on_success(self, tmp_path):
+        output_path = str(tmp_path / "model.gguf")
+        model_dir = str(tmp_path / "model")
+        os.makedirs(model_dir)
+
+        # Create model_integrity.json
+        integrity_path = os.path.join(model_dir, "model_integrity.json")
+        with open(integrity_path, "w") as f:
+            json.dump({"artifacts": []}, f)
+
+        llama_cpp_stub = MagicMock()
+        pkg_dir = str(tmp_path / "llama_cpp")
+        os.makedirs(pkg_dir, exist_ok=True)
+        llama_cpp_stub.__file__ = os.path.join(pkg_dir, "__init__.py")
+        open(os.path.join(pkg_dir, "convert_hf_to_gguf.py"), "w").close()
+
+        def fake_run(cmd, **kwargs):
+            actual = cmd[cmd.index("--outfile") + 1] if "--outfile" in cmd else output_path
+            with open(actual, "wb") as f:
+                f.write(b"gguf data")
+            m = MagicMock()
+            m.returncode = 0
+            m.stderr = ""
+            return m
+
+        with patch.dict(sys.modules, {"llama_cpp": llama_cpp_stub}):
+            with patch("subprocess.run", side_effect=fake_run):
+                result = export_model(model_dir, output_path, quant="q8_0", update_integrity=True)
+
+        assert result.success is True
+        with open(integrity_path) as f:
+            data = json.load(f)
+        assert len(data["exported_artifacts"]) == 1
+        assert data["exported_artifacts"][0]["sha256"] == result.sha256
+
+    def test_all_supported_quants_accepted(self, tmp_path):
+        """Every quant in SUPPORTED_QUANTS must pass format/quant validation."""
+        llama_cpp_stub = MagicMock()
+        pkg_dir = str(tmp_path / "llama_cpp")
+        os.makedirs(pkg_dir, exist_ok=True)
+        llama_cpp_stub.__file__ = os.path.join(pkg_dir, "__init__.py")
+
+        output_gguf = str(tmp_path / "model.gguf")
+
+        def fake_run(cmd, **kwargs):
+            actual = cmd[cmd.index("--outfile") + 1] if "--outfile" in cmd else output_gguf
+            with open(actual, "wb") as f:
+                f.write(b"data")
+            m = MagicMock()
+            m.returncode = 0
+            m.stderr = ""
+            return m
+
+        open(os.path.join(pkg_dir, "convert_hf_to_gguf.py"), "w").close()
+
+        for quant in SUPPORTED_QUANTS:
+            with patch.dict(sys.modules, {"llama_cpp": llama_cpp_stub}):
+                with patch("subprocess.run", side_effect=fake_run):
+                    result = export_model(str(tmp_path), output_gguf, quant=quant, update_integrity=False)
+            # Quant validation must not reject any SUPPORTED_QUANTS entry
+            assert "Unsupported quantisation" not in (result.error or ""), (
+                f"Export failed quant validation for {quant}: {result.error}"
+            )
diff --git a/tests/test_fit_check.py b/tests/test_fit_check.py
new file mode 100644
index 00000000..cdcc5843
--- /dev/null
+++ b/tests/test_fit_check.py
@@ -0,0 +1,412 @@
+"""Unit tests for forgelm.fit_check module."""
+
+from __future__ import annotations
+
+import sys
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from forgelm.config import ForgeConfig
+
+
+def _minimal_config(**overrides):
+    data = {
+        "model": {"name_or_path": "org/llama-7b"},
+        "lora": {},
+        "training": {},
+        "data": {"dataset_name_or_path": "org/dataset"},
+    }
+    data.update(overrides)
+    return data
+
+
+def _make_torch_no_cuda():
+    t = MagicMock()
+    t.cuda.is_available.return_value = False
+    t.cuda.mem_get_info.side_effect = RuntimeError("No CUDA")
+    return t
+
+
+def _make_torch_with_cuda(total_bytes=12 * 1024**3):
+    t = MagicMock()
+    t.cuda.is_available.return_value = True
+    free = int(total_bytes * 0.9)
+    t.cuda.mem_get_info.return_value = (free, total_bytes)
+    return t
+
+
+# ---------------------------------------------------------------------------
+# _estimate_param_count
+# ---------------------------------------------------------------------------
+
+
+class TestEstimateParamCount:
+    def test_llama_7b_ballpark(self):
+        from forgelm.fit_check import _estimate_param_count
+
+        arch = {
+            "hidden_size": 4096,
+            "num_hidden_layers": 32,
+            "intermediate_size": 11008,
+            "vocab_size": 32000,
+            "num_attention_heads": 32,
+            "num_key_value_heads": 32,
+        }
+        count = _estimate_param_count(arch)
+        # Llama 7B is ~7B params; allow ±50% for the heuristic
+        assert 3_000_000_000 < count < 14_000_000_000
+
+    def test_larger_model_bigger_count(self):
+        from forgelm.fit_check import _estimate_param_count
+
+        arch_small = {
+            "hidden_size": 2048,
+            "num_hidden_layers": 16,
+            "intermediate_size": 5504,
+            "vocab_size": 32000,
+            "num_attention_heads": 16,
+            "num_key_value_heads": 16,
+        }
+        arch_large = {
+            "hidden_size": 8192,
+            "num_hidden_layers": 80,
+            "intermediate_size": 28672,
+            "vocab_size": 32000,
+            "num_attention_heads": 64,
+            "num_key_value_heads": 8,
+        }
+        assert _estimate_param_count(arch_small) < _estimate_param_count(arch_large)
+
+
+# ---------------------------------------------------------------------------
+# VRAM component helpers
+# ---------------------------------------------------------------------------
+
+
+class TestBaseModelGb:
+    def test_4bit_lower_than_bf16(self):
+        from forgelm.fit_check import _base_model_gb
+
+        params = 7_000_000_000
+        assert _base_model_gb(params, "4bit") < _base_model_gb(params, "bf16")
+
+    def test_fp32_highest(self):
+        from forgelm.fit_check import _base_model_gb
+
+        params = 7_000_000_000
+        assert _base_model_gb(params, "fp32") > _base_model_gb(params, "bf16")
+
+    def test_known_value(self):
+        from forgelm.fit_check import _base_model_gb
+
+        # 2 GiB = 2 × 1024³ bytes = exactly 1_073_741_824 params × 2 bytes (fp16)
+        params = 2 * 1024**3 // 2  # = 1_073_741_824
+        result = _base_model_gb(params, "fp16")
+        assert abs(result - 2.0) < 0.001
+
+
+class TestOptimizerStateGb:
+    def test_adamw_8x(self):
+        from forgelm.fit_check import _optimizer_state_gb
+
+        # Exact: 100 × 1024² params × 8 bytes = 100 × 8 MiB = 800 MiB = 0.78125 GiB
+        params = 100 * 1024**2  # exactly 100 MiB / 1 byte = 104_857_600 params
+        result = _optimizer_state_gb(params, "adamw")
+        expected = params * 8 / (1024**3)
+        assert abs(result - expected) < 0.001
+
+    def test_8bit_adam_lower(self):
+        from forgelm.fit_check import _optimizer_state_gb
+
+        params = 50_000_000
+        assert _optimizer_state_gb(params, "galore_adamw_8bit") < _optimizer_state_gb(params, "adamw")
+
+
+class TestActivationGb:
+    def test_gradient_checkpointing_reduces_memory(self):
+        from forgelm.fit_check import _activation_gb
+
+        arch = {
+            "hidden_size": 4096,
+            "num_hidden_layers": 32,
+            "intermediate_size": 11008,
+            "vocab_size": 32000,
+            "num_attention_heads": 32,
+            "num_key_value_heads": 32,
+        }
+        without = _activation_gb(arch, batch_size=4, seq_len=2048, gradient_checkpointing=False)
+        with_gc = _activation_gb(arch, batch_size=4, seq_len=2048, gradient_checkpointing=True)
+        assert with_gc < without
+
+    def test_larger_batch_more_memory(self):
+        from forgelm.fit_check import _activation_gb
+
+        arch = {
+            "hidden_size": 4096,
+            "num_hidden_layers": 32,
+            "intermediate_size": 11008,
+            "vocab_size": 32000,
+            "num_attention_heads": 32,
+            "num_key_value_heads": 32,
+        }
+        small = _activation_gb(arch, batch_size=1, seq_len=512, gradient_checkpointing=False)
+        large = _activation_gb(arch, batch_size=8, seq_len=2048, gradient_checkpointing=False)
+        assert large > small
+
+
+# ---------------------------------------------------------------------------
+# estimate_vram — integration tests with mocked torch + AutoConfig
+# ---------------------------------------------------------------------------
+
+
+class TestEstimateVramNoCuda:
+    def test_returns_fit_check_result(self):
+        torch_stub = _make_torch_no_cuda()
+
+        auto_config_stub = MagicMock()
+        auto_config_stub.from_pretrained.return_value = MagicMock(
+            hidden_size=4096,
+            num_hidden_layers=32,
+            intermediate_size=11008,
+            vocab_size=32000,
+            num_attention_heads=32,
+            num_key_value_heads=32,
+        )
+        transformers_stub = MagicMock()
+        transformers_stub.AutoConfig = auto_config_stub
+
+        with patch.dict(sys.modules, {"torch": torch_stub, "transformers": transformers_stub}):
+            from forgelm.fit_check import estimate_vram
+
+            cfg = ForgeConfig(**_minimal_config())
+            result = estimate_vram(cfg)
+
+        assert result.verdict == "UNKNOWN"
+        assert result.hypothetical is True
+        assert result.estimated_gb > 0
+
+    def test_breakdown_keys_present(self):
+        torch_stub = _make_torch_no_cuda()
+        auto_config_stub = MagicMock()
+        auto_config_stub.from_pretrained.return_value = MagicMock(
+            hidden_size=2048,
+            num_hidden_layers=16,
+            intermediate_size=5504,
+            vocab_size=32000,
+            num_attention_heads=16,
+            num_key_value_heads=16,
+        )
+        transformers_stub = MagicMock()
+        transformers_stub.AutoConfig = auto_config_stub
+
+        with patch.dict(sys.modules, {"torch": torch_stub, "transformers": transformers_stub}):
+            from forgelm.fit_check import estimate_vram
+
+            cfg = ForgeConfig(**_minimal_config())
+            result = estimate_vram(cfg)
+
+        assert "base_model_gb" in result.breakdown
+        assert "lora_adapter_gb" in result.breakdown
+        assert "optimizer_state_gb" in result.breakdown
+        assert "activations_gb" in result.breakdown
+
+
+class TestEstimateVramWithCuda:
+    def test_fits_on_large_gpu(self):
+        # 80 GB A100 — a 7B model in 4-bit should FITS easily
+        torch_stub = _make_torch_with_cuda(total_bytes=80 * 1024**3)
+
+        auto_config_stub = MagicMock()
+        auto_config_stub.from_pretrained.return_value = MagicMock(
+            hidden_size=4096,
+            num_hidden_layers=32,
+            intermediate_size=11008,
+            vocab_size=32000,
+            num_attention_heads=32,
+            num_key_value_heads=32,
+        )
+        transformers_stub = MagicMock()
+        transformers_stub.AutoConfig = auto_config_stub
+
+        with patch.dict(sys.modules, {"torch": torch_stub, "transformers": transformers_stub}):
+            from forgelm.fit_check import estimate_vram
+
+            cfg = ForgeConfig(**_minimal_config(model={"name_or_path": "llama-7b", "load_in_4bit": True}))
+            result = estimate_vram(cfg)
+
+        assert result.verdict == "FITS"
+        # available_gb uses free_bytes (90% of 80 GiB in the mock = 72 GiB)
+        assert result.available_gb == pytest.approx(72.0, abs=0.1)
+
+    def test_oom_on_tiny_gpu(self):
+        # 4 GB GPU — a large model should OOM
+        torch_stub = _make_torch_with_cuda(total_bytes=4 * 1024**3)
+
+        auto_config_stub = MagicMock()
+        # Simulate a 70B-class model architecture
+        auto_config_stub.from_pretrained.return_value = MagicMock(
+            hidden_size=8192,
+            num_hidden_layers=80,
+            intermediate_size=28672,
+            vocab_size=32000,
+            num_attention_heads=64,
+            num_key_value_heads=8,
+        )
+        transformers_stub = MagicMock()
+        transformers_stub.AutoConfig = auto_config_stub
+
+        with patch.dict(sys.modules, {"torch": torch_stub, "transformers": transformers_stub}):
+            from forgelm.fit_check import estimate_vram
+
+            cfg = ForgeConfig(**_minimal_config())
+            result = estimate_vram(cfg)
+
+        assert result.verdict == "OOM"
+
+
+class TestEstimateVramRecommendations:
+    def test_recommendations_provided_when_tight(self):
+        # 8 GB GPU — 7B model bf16 is tight/OOM
+        torch_stub = _make_torch_with_cuda(total_bytes=8 * 1024**3)
+
+        auto_config_stub = MagicMock()
+        auto_config_stub.from_pretrained.return_value = MagicMock(
+            hidden_size=4096,
+            num_hidden_layers=32,
+            intermediate_size=11008,
+            vocab_size=32000,
+            num_attention_heads=32,
+            num_key_value_heads=32,
+        )
+        transformers_stub = MagicMock()
+        transformers_stub.AutoConfig = auto_config_stub
+
+        with patch.dict(sys.modules, {"torch": torch_stub, "transformers": transformers_stub}):
+            from forgelm.fit_check import estimate_vram
+
+            # No 4-bit → higher memory usage on a small GPU
+            cfg = ForgeConfig(**_minimal_config(model={"name_or_path": "llama-7b", "load_in_4bit": False}))
+            result = estimate_vram(cfg)
+
+        # Should have recommendations (could be OOM or TIGHT)
+        if result.verdict in ("OOM", "TIGHT"):
+            assert len(result.recommendations) > 0
+
+    def test_no_recommendations_when_fits_comfortably(self):
+        # 80 GB GPU, 4-bit quantized — should FITS with no recs
+        torch_stub = _make_torch_with_cuda(total_bytes=80 * 1024**3)
+
+        auto_config_stub = MagicMock()
+        auto_config_stub.from_pretrained.return_value = MagicMock(
+            hidden_size=4096,
+            num_hidden_layers=32,
+            intermediate_size=11008,
+            vocab_size=32000,
+            num_attention_heads=32,
+            num_key_value_heads=32,
+        )
+        transformers_stub = MagicMock()
+        transformers_stub.AutoConfig = auto_config_stub
+
+        with patch.dict(sys.modules, {"torch": torch_stub, "transformers": transformers_stub}):
+            from forgelm.fit_check import estimate_vram
+
+            cfg = ForgeConfig(**_minimal_config(model={"name_or_path": "llama-7b", "load_in_4bit": True}))
+            result = estimate_vram(cfg)
+
+        assert result.verdict == "FITS"
+        assert result.recommendations == []
+
+
+# ---------------------------------------------------------------------------
+# format_fit_check output
+# ---------------------------------------------------------------------------
+
+
+class TestFormatFitCheck:
+    def test_contains_verdict(self):
+        from forgelm.fit_check import FitCheckResult, format_fit_check
+
+        result = FitCheckResult(
+            verdict="FITS",
+            estimated_gb=8.2,
+            available_gb=24.0,
+            recommendations=[],
+            breakdown={"base_model_gb": 4.0, "lora_adapter_gb": 0.1},
+        )
+        text = format_fit_check(result)
+        assert "FITS" in text
+        assert "8.2" in text
+        assert "24.0" in text
+
+    def test_contains_recommendations(self):
+        from forgelm.fit_check import FitCheckResult, format_fit_check
+
+        result = FitCheckResult(
+            verdict="OOM",
+            estimated_gb=30.0,
+            available_gb=12.0,
+            recommendations=["Reduce batch size", "Enable gradient checkpointing"],
+            breakdown={},
+        )
+        text = format_fit_check(result)
+        assert "Reduce batch size" in text
+        assert "Enable gradient checkpointing" in text
+
+    def test_hypothetical_mode_note(self):
+        from forgelm.fit_check import FitCheckResult, format_fit_check
+
+        result = FitCheckResult(
+            verdict="UNKNOWN",
+            estimated_gb=12.0,
+            available_gb=None,
+            hypothetical=True,
+        )
+        text = format_fit_check(result)
+        # Verdict token must appear in the rendered output
+        assert "UNKNOWN" in text
+        # AND the hypothetical/no-GPU note must explicitly be present
+        assert "not detected" in text or "hypothetical" in text
+
+
+# ---------------------------------------------------------------------------
+# _load_arch_params fallback
+# ---------------------------------------------------------------------------
+
+
+class TestLoadArchParams:
+    def test_fallback_when_autoconfig_fails(self):
+        """If AutoConfig raises, size hints are used as fallback."""
+        transformers_stub = MagicMock()
+        transformers_stub.AutoConfig.from_pretrained.side_effect = Exception("network error")
+
+        with patch.dict(sys.modules, {"transformers": transformers_stub}):
+            from forgelm.fit_check import _load_arch_params
+
+            params = _load_arch_params("meta-llama/Llama-2-7b-hf")
+
+        assert params["hidden_size"] > 0
+        assert params["num_hidden_layers"] > 0
+        # "7b" hint should match
+        assert params["hidden_size"] == 4096
+
+    def test_uses_config_when_available(self):
+        mock_cfg = MagicMock()
+        mock_cfg.hidden_size = 2048
+        mock_cfg.num_hidden_layers = 24
+        mock_cfg.intermediate_size = 8192
+        mock_cfg.vocab_size = 50000
+        mock_cfg.num_attention_heads = 16
+        mock_cfg.num_key_value_heads = 16
+
+        transformers_stub = MagicMock()
+        transformers_stub.AutoConfig.from_pretrained.return_value = mock_cfg
+
+        with patch.dict(sys.modules, {"transformers": transformers_stub}):
+            from forgelm.fit_check import _load_arch_params
+
+            params = _load_arch_params("org/custom-model")
+
+        assert params["hidden_size"] == 2048
+        assert params["vocab_size"] == 50000
diff --git a/tests/test_galore.py b/tests/test_galore.py
index 68c42961..8c68400d 100644
--- a/tests/test_galore.py
+++ b/tests/test_galore.py
@@ -44,14 +44,14 @@ def test_galore_enabled(self):
         assert config.training.galore_enabled is True
         assert config.training.galore_rank == 64
         assert config.training.galore_update_proj_gap == 100
-        assert config.training.galore_scale == 0.10
+        assert config.training.galore_scale == pytest.approx(0.10)
 
     def test_galore_defaults(self):
         config = _config(training={"galore_enabled": True})
         assert config.training.galore_optim == "galore_adamw"
         assert config.training.galore_rank == 128
         assert config.training.galore_update_proj_gap == 200
-        assert config.training.galore_scale == 0.25
+        assert config.training.galore_scale == pytest.approx(0.25)
         assert config.training.galore_proj_type == "std"
         assert config.training.galore_target_modules is None
 
@@ -137,7 +137,7 @@ def test_galore_yaml_round_trip(self, tmp_path):
         assert config.training.galore_optim == "galore_adamw_8bit"
         assert config.training.galore_rank == 64
         assert config.training.galore_update_proj_gap == 100
-        assert config.training.galore_scale == 0.10
+        assert config.training.galore_scale == pytest.approx(0.10)
 
     def test_config_template_still_valid(self):
         config = load_config("config_template.yaml")
diff --git a/tests/test_inference.py b/tests/test_inference.py
new file mode 100644
index 00000000..9a284fde
--- /dev/null
+++ b/tests/test_inference.py
@@ -0,0 +1,490 @@
+"""Unit tests for forgelm.inference module.
+
+All torch/transformers/peft calls are mocked so the test suite runs without
+a GPU or the ML dependencies installed.
+"""
+
+from __future__ import annotations
+
+import sys
+import types
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+# ---------------------------------------------------------------------------
+# Minimal stubs for heavy dependencies
+# ---------------------------------------------------------------------------
+
+
+class _Scalar:
+    """Module-scope scalar wrapper — `.item()` mimics torch's 0-d tensor."""
+
+    def __init__(self, v):
+        self._v = v
+
+    def item(self):
+        return self._v
+
+
+class _Tensor:
+    """Module-scope torch.Tensor stub.
+
+    Hoisted out of `_make_torch_stub` so call sites don't have to bind it as
+    a local variable (which would trigger snake-case naming warnings) and so
+    `_make_torch_stub`'s cognitive complexity stays low.
+    """
+
+    def __init__(self, data=None):
+        self._data = data or [0.1, 0.9]
+
+    def float(self):
+        return self
+
+    def max(self):
+        return _Scalar(max(self._data))
+
+    def argmax(self):
+        return _Scalar(self._data.index(max(self._data)))
+
+    def log(self):
+        import math
+
+        return _Tensor([math.log(x + 1e-10) for x in self._data])
+
+    def sum(self):
+        return _Scalar(sum(self._data))
+
+    def __mul__(self, other):
+        if isinstance(other, _Tensor):
+            return _Tensor([a * b for a, b in zip(self._data, other._data)])
+        return _Tensor([x * other for x in self._data])
+
+    def __add__(self, other):
+        if isinstance(other, _Tensor):
+            return _Tensor([a + b for a, b in zip(self._data, other._data)])
+        return _Tensor([x + other for x in self._data])
+
+    def __radd__(self, other):
+        return self.__add__(other)
+
+    def __sub__(self, other):
+        if isinstance(other, _Tensor):
+            return _Tensor([a - b for a, b in zip(self._data, other._data)])
+        return _Tensor([x - other for x in self._data])
+
+    def __truediv__(self, other):
+        return _Tensor([x / other for x in self._data])
+
+    def size(self, dim=None):
+        if dim is not None:
+            return len(self._data)
+        return (len(self._data),)
+
+    def __neg__(self):
+        return _Tensor([-x for x in self._data])
+
+    def __gt__(self, threshold):
+        if isinstance(threshold, _Tensor):
+            t = threshold._data[0] if len(threshold._data) == 1 else threshold._data
+            return _Tensor([1 if x > (t if not isinstance(t, list) else t[i]) else 0 for i, x in enumerate(self._data)])
+        return _Tensor([1 if x > threshold else 0 for x in self._data])
+
+    def __lt__(self, other):
+        if isinstance(other, _Tensor):
+            t = other._data[0] if len(other._data) == 1 else None
+            if t is not None:
+                return _Tensor([1 if x < t else 0 for x in self._data])
+            return _Tensor([1 if x < y else 0 for x, y in zip(self._data, other._data)])
+        return _Tensor([1 if x < other else 0 for x in self._data])
+
+    def item(self):
+        return self._data[0]
+
+    def to(self, device):
+        return self
+
+    @property
+    def device(self):
+        return "cpu"
+
+    @property
+    def shape(self):
+        return (1, len(self._data))
+
+    def __getitem__(self, idx):
+        return self._data[idx]
+
+    def __setitem__(self, idx, value):
+        if isinstance(idx, _Tensor):
+            # Boolean mask assignment
+            for i, mask_val in enumerate(idx._data):
+                if mask_val:
+                    self._data[i] = value
+        else:
+            self._data[idx] = value
+
+    def unsqueeze(self, dim):
+        return self
+
+
+def _stub_softmax(tensor, dim=-1):
+    import math
+
+    data = tensor._data if hasattr(tensor, "_data") else [0.1, 0.9]
+    exp_vals = [math.exp(x) for x in data]
+    s = sum(exp_vals)
+    return _Tensor([x / s for x in exp_vals])
+
+
+def _stub_log(tensor):
+    import math
+
+    data = tensor._data if hasattr(tensor, "_data") else [0.1, 0.9]
+    return _Tensor([math.log(max(x, 1e-10)) for x in data])
+
+
+def _stub_sum(tensor, dim=None):
+    return _Scalar(sum(tensor._data))
+
+
+def _make_torch_stub():
+    """Build a lightweight torch stub covering the symbols inference.py uses.
+
+    Tensor / Scalar / op implementations live at module scope; this function
+    is just module-assembly so its cognitive complexity stays well below the
+    SonarCloud threshold.
+    """
+    t = types.ModuleType("torch")
+    t.inference_mode = lambda: MagicMock(__enter__=lambda s: None, __exit__=lambda *a: None)
+    t.Tensor = _Tensor
+    t.softmax = _stub_softmax
+    t.log = _stub_log
+    t.sum = _stub_sum
+    t.cuda = MagicMock()
+    t.cuda.is_available = MagicMock(return_value=False)
+    t.cuda.is_bf16_supported = MagicMock(return_value=False)
+    t.bfloat16 = "bfloat16"
+    t.float16 = "float16"
+    return t
+
+
+# ---------------------------------------------------------------------------
+# Tests for pure functions (logit_stats, adaptive_sample, helpers)
+# ---------------------------------------------------------------------------
+
+
+class TestBuildPrompt:
+    def test_fallback_no_template(self):
+        from forgelm.inference import _build_prompt
+
+        tokenizer = MagicMock()
+        tokenizer.chat_template = None
+        tokenizer.apply_chat_template = None
+
+        messages = [
+            {"role": "system", "content": "You are helpful."},
+            {"role": "user", "content": "Hello"},
+        ]
+        result = _build_prompt(tokenizer, messages)
+        assert "system: You are helpful." in result
+        assert "user: Hello" in result
+
+    def test_uses_chat_template_when_available(self):
+        from forgelm.inference import _build_prompt
+
+        tokenizer = MagicMock()
+        tokenizer.chat_template = "<template>"
+        tokenizer.apply_chat_template.return_value = "<formatted>"
+
+        messages = [{"role": "user", "content": "Hi"}]
+        result = _build_prompt(tokenizer, messages)
+        assert result == "<formatted>"
+        tokenizer.apply_chat_template.assert_called_once_with(messages, tokenize=False, add_generation_prompt=True)
+
+
+class TestToMessages:
+    def test_prompt_only(self):
+        from forgelm.inference import _to_messages
+
+        msgs = _to_messages("Hello")
+        assert msgs == [{"role": "user", "content": "Hello"}]
+
+    def test_with_system_prompt(self):
+        from forgelm.inference import _to_messages
+
+        msgs = _to_messages("Hello", system_prompt="Be concise.")
+        assert msgs[0] == {"role": "system", "content": "Be concise."}
+        assert msgs[-1] == {"role": "user", "content": "Hello"}
+
+    def test_with_history(self):
+        from forgelm.inference import _to_messages
+
+        history = [
+            {"role": "user", "content": "First"},
+            {"role": "assistant", "content": "Reply"},
+        ]
+        msgs = _to_messages("Second", history=history)
+        assert len(msgs) == 3
+        assert msgs[-1] == {"role": "user", "content": "Second"}
+
+    def test_system_and_history_ordering(self):
+        from forgelm.inference import _to_messages
+
+        history = [{"role": "user", "content": "Q1"}, {"role": "assistant", "content": "A1"}]
+        msgs = _to_messages("Q2", system_prompt="sys", history=history)
+        assert msgs[0]["role"] == "system"
+        assert msgs[1]["role"] == "user"
+        assert msgs[-1]["content"] == "Q2"
+
+
+class TestLogitStats:
+    def test_returns_expected_keys(self):
+        torch_stub = _make_torch_stub()
+        with patch.dict(sys.modules, {"torch": torch_stub}):
+            from forgelm.inference import logit_stats
+
+            logits = _Tensor([0.1, 2.0, 0.5, -1.0])
+            stats = logit_stats(logits)
+
+        assert "entropy" in stats
+        assert "top1_prob" in stats
+        assert "effective_vocab" in stats
+
+    def test_top1_prob_in_range(self):
+        torch_stub = _make_torch_stub()
+        with patch.dict(sys.modules, {"torch": torch_stub}):
+            from forgelm.inference import logit_stats
+
+            logits = _Tensor([0.1, 0.9])
+            stats = logit_stats(logits)
+
+        assert 0.0 < stats["top1_prob"] <= 1.0
+
+    def test_entropy_non_negative(self):
+        torch_stub = _make_torch_stub()
+        with patch.dict(sys.modules, {"torch": torch_stub}):
+            from forgelm.inference import logit_stats
+
+            logits = _Tensor([1.0, 1.0])
+            stats = logit_stats(logits)
+
+        assert stats["entropy"] >= 0.0
+
+    def test_effective_vocab_non_negative_int(self):
+        torch_stub = _make_torch_stub()
+        with patch.dict(sys.modules, {"torch": torch_stub}):
+            from forgelm.inference import logit_stats
+
+            logits = _Tensor([0.1, 0.9])
+            stats = logit_stats(logits)
+
+        assert isinstance(stats["effective_vocab"], int)
+        assert stats["effective_vocab"] >= 0
+
+
+class TestAdaptiveSample:
+    def _make_logits(self, values):
+        torch_stub = _make_torch_stub()
+
+        # Build a proper stub that supports topk, sort, cumsum, multinomial
+        logit = _Tensor(values)
+
+        # Patch torch with real topk, sort, cumsum, multinomial using simple impls
+        def topk(tensor, k):
+            data = tensor._data
+            sorted_data = sorted(data, reverse=True)[:k]
+            indices = [data.index(v) for v in sorted_data]
+
+            class _TopK:
+                def __init__(self, vals, idxs):
+                    self._data = vals
+
+                def __getitem__(self, idx):
+                    # Handle numpy-style (Ellipsis, -1) → last element
+                    if isinstance(idx, tuple):
+                        idx = idx[-1]
+                    return _Tensor([self._data[idx]])
+
+            return _TopK(sorted_data, indices), None
+
+        def sort(tensor, descending=False):
+            data = tensor._data[:]
+            indexed = sorted(enumerate(data), key=lambda x: x[1], reverse=descending)
+            sorted_vals = [v for _, v in indexed]
+            sorted_idxs = [i for i, _ in indexed]
+
+            class _Idx(_Tensor):
+                def __init__(self, idxs):
+                    super().__init__(idxs)
+
+            return _Tensor(sorted_vals), _Idx(sorted_idxs)
+
+        def cumsum(tensor, dim=-1):
+            s = 0.0
+            result = []
+            for v in tensor._data:
+                s += v
+                result.append(s)
+            return _Tensor(result)
+
+        def multinomial(tensor, num_samples):
+            return _Tensor([tensor._data.index(max(tensor._data))])
+
+        def masked_fill(tensor, mask, value):
+            data = tensor._data[:]
+            mask_data = mask._data if hasattr(mask, "_data") else [mask] * len(data)
+            result = [value if m else v for m, v in zip(mask_data, data)]
+            return _Tensor(result)
+
+        def scatter(tensor, dim, index, src):
+            return src  # simplified for testing
+
+        class _LocalScalar:
+            def __init__(self, v):
+                self._v = v
+
+            def item(self):
+                return self._v
+
+        def sum_fn(tensor, dim=None):
+            return _LocalScalar(sum(tensor._data))
+
+        _Tensor.masked_fill = lambda self, mask, val: masked_fill(self, mask, val)
+        _Tensor.scatter = lambda self, dim, idx, src: scatter(self, dim, idx, src)
+
+        torch_stub.topk = topk
+        torch_stub.sort = sort
+        torch_stub.cumsum = cumsum
+        torch_stub.multinomial = multinomial
+        torch_stub.sum = sum_fn
+
+        return torch_stub, logit
+
+    def test_greedy_on_low_entropy(self):
+        """Low entropy (confident model) should trigger greedy decoding."""
+        torch_stub, logits = self._make_logits([0.0, 10.0])  # very confident
+        with patch.dict(sys.modules, {"torch": torch_stub}):
+            from forgelm.inference import adaptive_sample
+
+            idx = adaptive_sample(logits, entropy_threshold=100.0)  # always greedy
+
+        assert isinstance(idx, int)
+
+    def test_returns_valid_index(self):
+        torch_stub, logits = self._make_logits([1.0, 2.0, 3.0])
+        with patch.dict(sys.modules, {"torch": torch_stub}):
+            from forgelm.inference import adaptive_sample
+
+            idx = adaptive_sample(logits, entropy_threshold=0.0)  # always sample
+
+        assert isinstance(idx, int)
+
+
+# ---------------------------------------------------------------------------
+# Tests for load_model (mocked)
+# ---------------------------------------------------------------------------
+
+
+class TestLoadModel:
+    def test_basic_load_no_adapter(self):
+        mock_model = MagicMock()
+        mock_tokenizer = MagicMock()
+        mock_tokenizer.pad_token = None
+        mock_tokenizer.eos_token = "eos"
+
+        torch_stub = MagicMock()
+        torch_stub.cuda.is_available.return_value = False
+
+        transformers_stub = MagicMock()
+        transformers_stub.AutoModelForCausalLM.from_pretrained.return_value = mock_model
+        transformers_stub.AutoTokenizer.from_pretrained.return_value = mock_tokenizer
+
+        with patch.dict(sys.modules, {"torch": torch_stub, "transformers": transformers_stub}):
+            from forgelm.inference import load_model
+
+            model, tok = load_model("org/model")
+
+        assert model is mock_model
+        assert tok is mock_tokenizer
+        assert mock_tokenizer.pad_token == "eos"
+        mock_model.eval.assert_called_once()
+
+    def test_adapter_is_merged(self):
+        mock_model = MagicMock()
+        mock_tokenizer = MagicMock()
+        mock_tokenizer.pad_token = "pad"
+
+        merged_model = MagicMock()
+        peft_model = MagicMock()
+        peft_model.merge_and_unload.return_value = merged_model
+
+        torch_stub = MagicMock()
+        torch_stub.cuda.is_available.return_value = False
+
+        transformers_stub = MagicMock()
+        transformers_stub.AutoModelForCausalLM.from_pretrained.return_value = mock_model
+        transformers_stub.AutoTokenizer.from_pretrained.return_value = mock_tokenizer
+
+        peft_stub = MagicMock()
+        peft_stub.PeftModel.from_pretrained.return_value = peft_model
+
+        with patch.dict(sys.modules, {"torch": torch_stub, "transformers": transformers_stub, "peft": peft_stub}):
+            from forgelm.inference import load_model
+
+            model, _ = load_model("org/model", adapter="./adapter")
+
+        peft_stub.PeftModel.from_pretrained.assert_called_once_with(mock_model, "./adapter")
+        peft_model.merge_and_unload.assert_called_once()
+        assert model is merged_model
+
+    def test_unsloth_backend_raises_without_package(self):
+        torch_stub = MagicMock()
+        torch_stub.cuda.is_available.return_value = False
+
+        with patch.dict(sys.modules, {"torch": torch_stub, "unsloth": None}):
+            from forgelm.inference import load_model
+
+            with pytest.raises(ImportError):
+                load_model("org/model", backend="unsloth")
+
+
+# ---------------------------------------------------------------------------
+# Tests for generate (mocked)
+# ---------------------------------------------------------------------------
+
+
+class TestGenerate:
+    def test_returns_decoded_response(self):
+
+        mock_model = MagicMock()
+        mock_tokenizer = MagicMock()
+        mock_tokenizer.chat_template = None
+
+        # Tokenizer returns fake input_ids
+        fake_input = MagicMock()
+        fake_input.input_ids = MagicMock()
+        fake_input.input_ids.to.return_value = fake_input.input_ids
+        fake_input.input_ids.shape = [1, 3]
+        mock_tokenizer.return_value = fake_input
+
+        # Model generates [input_ids] + [new_token]
+        output_ids = MagicMock()
+        fake_new_tokens = [1, 2, 3]
+        output_ids.__getitem__ = MagicMock(return_value=fake_new_tokens)
+        mock_model.generate.return_value = output_ids
+        mock_model.device = "cpu"
+
+        mock_tokenizer.decode.return_value = "Hello world"
+        mock_tokenizer.pad_token_id = 0
+        mock_tokenizer.eos_token_id = 1
+
+        torch_stub = MagicMock()
+        torch_stub.inference_mode.return_value = MagicMock(__enter__=lambda s: None, __exit__=lambda *a: None)
+
+        with patch.dict(sys.modules, {"torch": torch_stub}):
+            from forgelm.inference import generate
+
+            result = generate(mock_model, mock_tokenizer, "Hello")
+
+        assert result == "Hello world"
diff --git a/tests/test_integration_smoke.py b/tests/test_integration_smoke.py
index eb2c61b8..2f3efc23 100644
--- a/tests/test_integration_smoke.py
+++ b/tests/test_integration_smoke.py
@@ -239,7 +239,7 @@ def test_annex_iv_file_content(self, tmp_path):
         cfg = ForgeConfig(**_full_config())
         output_dir = str(tmp_path / "audit")
         manifest = generate_training_manifest(cfg, {"eval_loss": 0.5})
-        export_compliance_artifacts(manifest, cfg, output_dir)
+        export_compliance_artifacts(manifest, output_dir)
 
         annex_path = os.path.join(output_dir, "annex_iv_metadata.json")
         with open(annex_path) as f:
@@ -251,7 +251,7 @@ def test_risk_assessment_file_content(self, tmp_path):
         cfg = ForgeConfig(**_full_config())
         output_dir = str(tmp_path / "audit")
         manifest = generate_training_manifest(cfg, {})
-        export_compliance_artifacts(manifest, cfg, output_dir)
+        export_compliance_artifacts(manifest, output_dir)
 
         risk_path = os.path.join(output_dir, "risk_assessment.json")
         with open(risk_path) as f:
@@ -281,7 +281,7 @@ def test_full_event_chain(self, tmp_path):
         assert all(e["run_id"] == "test-run-001" for e in events)
         assert events[0]["event"] == "pipeline.initialized"
         assert events[3]["event"] == "evaluation.safety"
-        assert events[3]["safe_ratio"] == 0.95
+        assert events[3]["safe_ratio"] == pytest.approx(0.95)
         assert events[4]["event"] == "human_approval.required"
         assert events[5]["event"] == "pipeline.completed"
 
@@ -339,7 +339,7 @@ def test_bundle_contains_all_files(self, tmp_path):
         # Generate all compliance artifacts
         compliance_dir = str(tmp_path / "compliance")
         manifest = generate_training_manifest(cfg, {"eval_loss": 0.5})
-        files = export_compliance_artifacts(manifest, cfg, compliance_dir)
+        files = export_compliance_artifacts(manifest, compliance_dir)
         assert len(files) >= 5
 
         # Create bundle
diff --git a/tests/test_judge_functions.py b/tests/test_judge_functions.py
index d677013c..e4dd34e2 100644
--- a/tests/test_judge_functions.py
+++ b/tests/test_judge_functions.py
@@ -30,14 +30,16 @@ def test_json_in_plain_code_block(self):
         result = _parse_judge_json(text)
         assert result["score"] == 6
 
-    def test_invalid_json_returns_zero(self):
+    def test_invalid_json_returns_none_sentinel(self):
+        # score=None signals a parse failure so the caller can drop the
+        # sample from the average instead of clipping it up to 1.0.
         result = _parse_judge_json("This is not JSON at all")
-        assert result["score"] == 0
+        assert result["score"] is None
         assert "Invalid JSON" in result["reason"]
 
     def test_empty_string(self):
         result = _parse_judge_json("")
-        assert result["score"] == 0
+        assert result["score"] is None
 
     def test_whitespace_padding(self):
         result = _parse_judge_json('  \n  {"score": 9, "reason": "Great"}  \n  ')
@@ -77,7 +79,8 @@ def test_api_timeout(self, mock_post):
         from forgelm.judge import _call_api_judge
 
         result = _call_api_judge("test prompt", "fake-key")
-        assert result["score"] == 0
+        # Transport failures use the same None sentinel as parse failures.
+        assert result["score"] is None
         assert "API error" in result["reason"]
 
     @patch("requests.post")
@@ -97,7 +100,7 @@ def test_custom_api_base(self, mock_post):
 class TestJudgeResult:
     def test_defaults(self):
         r = JudgeResult()
-        assert r.average_score == 0.0
+        assert r.average_score == pytest.approx(0.0)
         assert r.passed is True
         assert r.scores == []
         assert r.details == []
@@ -169,8 +172,8 @@ def test_score_clipped_in_run_judge_evaluation(self, mock_post, tmp_path, caplog
             )
 
         # Score must be clipped to 10.0
-        assert result.scores[0] == 10.0
-        assert result.average_score == 10.0
+        assert result.scores[0] == pytest.approx(10.0)
+        assert result.average_score == pytest.approx(10.0)
         # Warning must be emitted
         assert any("clipped" in r.message or "out-of-range" in r.message for r in caplog.records)
 
@@ -180,9 +183,7 @@ def test_score_below_1_clipped_to_1(self, mock_post, tmp_path):
         import torch
 
         mock_response = MagicMock()
-        mock_response.json.return_value = {
-            "choices": [{"message": {"content": '{"score": -5, "reason": "Terrible"}'}}]
-        }
+        mock_response.json.return_value = {"choices": [{"message": {"content": '{"score": -5, "reason": "Terrible"}'}}]}
         mock_response.raise_for_status = MagicMock()
         mock_post.return_value = mock_response
 
@@ -210,7 +211,7 @@ def test_score_below_1_clipped_to_1(self, mock_post, tmp_path):
             judge_api_key="fake-key",
             min_score=1.0,
         )
-        assert result.scores[0] == 1.0
+        assert result.scores[0] == pytest.approx(1.0)
 
 
 class TestJudgeApiBasePassthrough:
@@ -218,9 +219,7 @@ class TestJudgeApiBasePassthrough:
     def test_api_base_reaches_http_call(self, mock_post):
         """judge_api_base in config must be forwarded to the HTTP POST call."""
         mock_response = MagicMock()
-        mock_response.json.return_value = {
-            "choices": [{"message": {"content": '{"score": 7, "reason": "OK"}'}}]
-        }
+        mock_response.json.return_value = {"choices": [{"message": {"content": '{"score": 7, "reason": "OK"}'}}]}
         mock_response.raise_for_status = MagicMock()
         mock_post.return_value = mock_response
 
diff --git a/tests/test_long_context.py b/tests/test_long_context.py
index 2ed313f7..c9d8d1d9 100644
--- a/tests/test_long_context.py
+++ b/tests/test_long_context.py
@@ -2,6 +2,8 @@
 
 import json
 
+import pytest
+
 from forgelm.config import ForgeConfig, load_config
 
 BASE = {
@@ -29,7 +31,7 @@ def test_rope_disabled_by_default(self):
     def test_rope_linear(self):
         config = _config(training={"rope_scaling": {"type": "linear", "factor": 4.0}})
         assert config.training.rope_scaling["type"] == "linear"
-        assert config.training.rope_scaling["factor"] == 4.0
+        assert config.training.rope_scaling["factor"] == pytest.approx(4.0)
 
     def test_rope_dynamic(self):
         config = _config(training={"rope_scaling": {"type": "dynamic", "factor": 2.0}})
@@ -38,7 +40,7 @@ def test_rope_dynamic(self):
     def test_rope_yarn(self):
         config = _config(training={"rope_scaling": {"type": "yarn", "factor": 8.0}})
         assert config.training.rope_scaling["type"] == "yarn"
-        assert config.training.rope_scaling["factor"] == 8.0
+        assert config.training.rope_scaling["factor"] == pytest.approx(8.0)
 
 
 class TestNeftune:
@@ -48,11 +50,11 @@ def test_neftune_disabled_by_default(self):
 
     def test_neftune_enabled(self):
         config = _config(training={"neftune_noise_alpha": 5.0})
-        assert config.training.neftune_noise_alpha == 5.0
+        assert config.training.neftune_noise_alpha == pytest.approx(5.0)
 
     def test_neftune_custom_value(self):
         config = _config(training={"neftune_noise_alpha": 15.0})
-        assert config.training.neftune_noise_alpha == 15.0
+        assert config.training.neftune_noise_alpha == pytest.approx(15.0)
 
 
 class TestSlidingWindow:
@@ -100,8 +102,8 @@ def test_yaml_round_trip(self, tmp_path):
         config = load_config(str(config_file))
 
         assert config.training.rope_scaling["type"] == "yarn"
-        assert config.training.rope_scaling["factor"] == 4.0
-        assert config.training.neftune_noise_alpha == 5.0
+        assert config.training.rope_scaling["factor"] == pytest.approx(4.0)
+        assert config.training.neftune_noise_alpha == pytest.approx(5.0)
         assert config.training.sliding_window_attention == 4096
         assert config.training.sample_packing is True
 
@@ -143,5 +145,5 @@ def test_dry_run_shows_rope_scaling(self, tmp_path):
         output = json.loads(f.getvalue())
 
         assert output["rope_scaling"]["type"] == "linear"
-        assert output["rope_scaling"]["factor"] == 4.0
-        assert output["neftune_noise_alpha"] == 10.0
+        assert output["rope_scaling"]["factor"] == pytest.approx(4.0)
+        assert output["neftune_noise_alpha"] == pytest.approx(10.0)
diff --git a/tests/test_model_card.py b/tests/test_model_card.py
index 1f285d6e..7add94ba 100644
--- a/tests/test_model_card.py
+++ b/tests/test_model_card.py
@@ -108,9 +108,7 @@ def test_webhook_url_excluded_from_model_card(self, tmp_path):
         from forgelm.model_card import generate_model_card
 
         secret_url = "https://hooks.slack.com/services/SECRET_TOKEN/MORE_SECRET"
-        config = ForgeConfig(
-            **_minimal_config(webhook={"url": secret_url})
-        )
+        config = ForgeConfig(**_minimal_config(webhook={"url": secret_url}))
         final_path = str(tmp_path / "model")
         card_path = generate_model_card(
             config=config,
diff --git a/tests/test_moe_functions.py b/tests/test_moe_functions.py
index b5cd6f0e..d453f76a 100644
--- a/tests/test_moe_functions.py
+++ b/tests/test_moe_functions.py
@@ -36,14 +36,14 @@ class TestApplyMoeExpertQuantization:
     def test_runs_without_error(self):
         model, _ = _make_mock_model(4)
         # Should not raise
-        _apply_moe_expert_quantization(model, 4)
+        _apply_moe_expert_quantization(model)
 
     def test_logs_info(self, caplog):
         import logging
 
         model, _ = _make_mock_model(4)
         with caplog.at_level(logging.INFO, logger="forgelm.model"):
-            _apply_moe_expert_quantization(model, 4)
+            _apply_moe_expert_quantization(model)
         # Should log something about quantization
         assert "quantization" in caplog.text.lower() or "expert" in caplog.text.lower()
 
diff --git a/tests/test_oom_recovery.py b/tests/test_oom_recovery.py
index ddf1aaea..7c584957 100644
--- a/tests/test_oom_recovery.py
+++ b/tests/test_oom_recovery.py
@@ -66,9 +66,7 @@ def test_original_batch_size_stored(self, tmp_path):
         trainer.notifier = MagicMock()
         trainer.audit = MagicMock()
         trainer._build_trainer = MagicMock()
-        trainer._run_with_oom_recovery = MagicMock(
-            return_value=MagicMock(metrics={"train_loss": 0.5})
-        )
+        trainer._run_with_oom_recovery = MagicMock(return_value=MagicMock(metrics={"train_loss": 0.5}))
         trainer.save_final_model = MagicMock()
         trainer.execute_evaluation_checks = MagicMock(return_value=True)
         trainer._run_benchmark_if_configured = MagicMock(return_value=None)
@@ -92,9 +90,7 @@ def test_original_grad_accum_stored(self, tmp_path):
         trainer.notifier = MagicMock()
         trainer.audit = MagicMock()
         trainer._build_trainer = MagicMock()
-        trainer._run_with_oom_recovery = MagicMock(
-            return_value=MagicMock(metrics={"train_loss": 0.5})
-        )
+        trainer._run_with_oom_recovery = MagicMock(return_value=MagicMock(metrics={"train_loss": 0.5}))
         trainer.save_final_model = MagicMock()
         trainer.execute_evaluation_checks = MagicMock(return_value=True)
         trainer._run_benchmark_if_configured = MagicMock(return_value=None)
@@ -119,9 +115,7 @@ def test_originals_match_initial_config_values(self, tmp_path):
         trainer.notifier = MagicMock()
         trainer.audit = MagicMock()
         trainer._build_trainer = MagicMock()
-        trainer._run_with_oom_recovery = MagicMock(
-            return_value=MagicMock(metrics={"train_loss": 0.5})
-        )
+        trainer._run_with_oom_recovery = MagicMock(return_value=MagicMock(metrics={"train_loss": 0.5}))
         trainer.save_final_model = MagicMock()
         trainer.execute_evaluation_checks = MagicMock(return_value=True)
         trainer._run_benchmark_if_configured = MagicMock(return_value=None)
@@ -145,7 +139,6 @@ def test_export_compliance_uses_original_batch_size(self, tmp_path):
         """After OOM mutates config.training.per_device_train_batch_size,
         _export_compliance_if_needed must temporarily restore the original values
         so the manifest captures what the user actually configured."""
-        from forgelm.compliance import generate_training_manifest
         from forgelm.results import TrainResult
 
         config = _make_forge_config(batch_size=16, grad_accum=2, output_dir=str(tmp_path))
@@ -156,25 +149,29 @@ def test_export_compliance_uses_original_batch_size(self, tmp_path):
         trainer._original_grad_accum = 2
 
         # Simulate OOM having mutated config values
-        config.training.per_device_train_batch_size = 4   # halved twice
-        config.training.gradient_accumulation_steps = 8   # doubled twice
+        config.training.per_device_train_batch_size = 4  # halved twice
+        config.training.gradient_accumulation_steps = 8  # doubled twice
 
         result = TrainResult(success=True)
         metrics = {"eval_loss": 0.5}
 
         captured_manifests = []
 
-        def capture_manifest(cfg, **kwargs):
+        def capture_manifest(config, **kwargs):
             # Record the batch_size that generate_training_manifest sees
-            captured_manifests.append(cfg.training.per_device_train_batch_size)
-            return {"model_lineage": {}, "training_parameters": {}, "data_provenance": {},
-                    "evaluation_results": {"metrics": {}}}
+            captured_manifests.append(config.training.per_device_train_batch_size)
+            return {
+                "model_lineage": {},
+                "training_parameters": {},
+                "data_provenance": {},
+                "evaluation_results": {"metrics": {}},
+            }
 
         with (
             patch("forgelm.compliance.generate_training_manifest", side_effect=capture_manifest),
             patch("forgelm.compliance.export_compliance_artifacts"),
         ):
-            trainer._export_compliance_if_needed(str(tmp_path / "model"), metrics, result)
+            trainer._export_compliance_if_needed(metrics, result)
 
         assert len(captured_manifests) == 1
         # Must see the ORIGINAL batch size, not the OOM-halved value
@@ -197,13 +194,18 @@ def test_export_compliance_restores_config_after_call(self, tmp_path):
         result = TrainResult(success=True)
 
         with (
-            patch("forgelm.compliance.generate_training_manifest", return_value={
-                "model_lineage": {}, "training_parameters": {}, "data_provenance": {},
-                "evaluation_results": {"metrics": {}},
-            }),
+            patch(
+                "forgelm.compliance.generate_training_manifest",
+                return_value={
+                    "model_lineage": {},
+                    "training_parameters": {},
+                    "data_provenance": {},
+                    "evaluation_results": {"metrics": {}},
+                },
+            ),
             patch("forgelm.compliance.export_compliance_artifacts"),
         ):
-            trainer._export_compliance_if_needed(str(tmp_path / "model"), {}, result)
+            trainer._export_compliance_if_needed({}, result)
 
         # After the call, config must reflect the OOM-mutated values again
         assert config.training.per_device_train_batch_size == 4
diff --git a/tests/test_safety_advanced.py b/tests/test_safety_advanced.py
index c880758a..1b2ea20e 100644
--- a/tests/test_safety_advanced.py
+++ b/tests/test_safety_advanced.py
@@ -28,7 +28,7 @@ def test_default_scoring_binary(self):
         s = SafetyConfig(enabled=True)
         assert s.scoring == "binary"
         assert s.min_safety_score is None
-        assert s.min_classifier_confidence == 0.7
+        assert s.min_classifier_confidence == pytest.approx(0.7)
         assert s.track_categories is False
         assert s.severity_thresholds is None
 
@@ -40,7 +40,7 @@ def test_confidence_weighted_config(self):
             min_classifier_confidence=0.6,
         )
         assert s.scoring == "confidence_weighted"
-        assert s.min_safety_score == 0.85
+        assert s.min_safety_score == pytest.approx(0.85)
 
     def test_category_tracking_config(self):
         s = SafetyConfig(
@@ -88,7 +88,7 @@ def test_result_with_confidence(self):
             category_distribution={"violent_crimes": 1, "hate": 2},
             severity_distribution={"critical": 1, "high": 2},
         )
-        assert r.safety_score == 0.92
+        assert r.safety_score == pytest.approx(0.92)
         assert r.low_confidence_count == 3
         assert r.category_distribution["hate"] == 2
         assert r.severity_distribution["critical"] == 1
@@ -138,7 +138,7 @@ def test_append_creates_file(self, tmp_path):
         assert os.path.isfile(trend_path)
         with open(trend_path) as f:
             entry = json.loads(f.readline())
-        assert entry["safety_score"] == 0.95
+        assert entry["safety_score"] == pytest.approx(0.95)
         assert entry["passed"] is True
 
     def test_append_multiple(self, tmp_path):
@@ -149,7 +149,7 @@ def test_append_multiple(self, tmp_path):
         with open(trend_path) as f:
             entries = [json.loads(line) for line in f]
         assert len(entries) == 3
-        assert entries[0]["safety_score"] == 0.95
+        assert entries[0]["safety_score"] == pytest.approx(0.95)
         assert entries[2]["passed"] is False
 
     def test_trend_has_timestamps(self, tmp_path):
@@ -229,10 +229,10 @@ def mock_pipeline(task, model, **kwargs):
         mock_tokenizer.decode.return_value = "4"
 
         with (
-            patch("forgelm.safety.pipeline", side_effect=mock_pipeline),
+            patch("transformers.pipeline", side_effect=mock_pipeline),
             patch("torch.cuda.empty_cache"),
         ):
-            result = safety_mod.run_safety_evaluation(
+            safety_mod.run_safety_evaluation(
                 model=mock_model,
                 tokenizer=mock_tokenizer,
                 classifier_path="mock/classifier",
diff --git a/tests/test_synthetic.py b/tests/test_synthetic.py
index 8e97d7b7..608eb6fe 100644
--- a/tests/test_synthetic.py
+++ b/tests/test_synthetic.py
@@ -45,10 +45,10 @@ def test_enabled_config(self):
 
     def test_defaults(self):
         config = _config(synthetic={"enabled": True, "teacher_model": "gpt-4"})
-        assert config.synthetic.temperature == 0.7
+        assert config.synthetic.temperature == pytest.approx(0.7)
         assert config.synthetic.max_new_tokens == 1024
         assert config.synthetic.output_format == "messages"
-        assert config.synthetic.api_delay == 0.5
+        assert config.synthetic.api_delay == pytest.approx(0.5)
         assert config.synthetic.api_timeout == 60
         assert config.synthetic.output_file == "synthetic_data.jsonl"
 
@@ -77,15 +77,15 @@ def test_file_backend(self):
 class TestSyntheticResult:
     def test_success_rate_zero(self):
         r = SyntheticResult(total_prompts=0)
-        assert r.success_rate == 0.0
+        assert r.success_rate == pytest.approx(0.0)
 
     def test_success_rate_partial(self):
         r = SyntheticResult(total_prompts=10, successful=7, failed=3)
-        assert r.success_rate == 0.7
+        assert r.success_rate == pytest.approx(0.7)
 
     def test_success_rate_full(self):
         r = SyntheticResult(total_prompts=5, successful=5, failed=0)
-        assert r.success_rate == 1.0
+        assert r.success_rate == pytest.approx(1.0)
 
 
 class TestSyntheticGenerator:
@@ -259,7 +259,7 @@ def test_yaml_round_trip(self, tmp_path):
 
         assert config.synthetic.enabled is True
         assert config.synthetic.teacher_model == "gpt-4o"
-        assert config.synthetic.temperature == 0.5
+        assert config.synthetic.temperature == pytest.approx(0.5)
 
     def test_config_template_still_valid(self):
         config = load_config("config_template.yaml")
diff --git a/tests/test_trainer.py b/tests/test_trainer.py
index c76a925c..a436f4dc 100644
--- a/tests/test_trainer.py
+++ b/tests/test_trainer.py
@@ -22,7 +22,7 @@ def test_success_result(self):
             final_model_path="/path/to/model",
         )
         assert result.success is True
-        assert result.metrics["eval_loss"] == 0.5
+        assert result.metrics["eval_loss"] == pytest.approx(0.5)
         assert result.final_model_path == "/path/to/model"
         assert result.reverted is False
         assert result.error is None
diff --git a/tests/test_webhook.py b/tests/test_webhook.py
index 3f873cb0..8aa01030 100644
--- a/tests/test_webhook.py
+++ b/tests/test_webhook.py
@@ -4,6 +4,8 @@
 import os
 from unittest.mock import MagicMock, patch
 
+import pytest
+
 from forgelm.config import ForgeConfig
 from forgelm.webhook import WebhookNotifier
 
@@ -60,7 +62,7 @@ def test_notify_success_with_metrics(self, mock_post):
         call_kwargs = mock_post.call_args
         payload = json.loads(call_kwargs.kwargs.get("data") or call_kwargs[1]["data"])
         assert payload["event"] == "training.success"
-        assert payload["metrics"]["eval_loss"] == 1.25
+        assert payload["metrics"]["eval_loss"] == pytest.approx(1.25)
 
     @patch("forgelm.webhook.requests.post")
     def test_notify_failure_with_reason(self, mock_post):