micforge 1.3.0__py3-none-any.whl

micforge/commands/wizard.py

@@ -0,0 +1,70 @@
+"""Interactive menu shown when `micforge` is run with no arguments."""
+from __future__ import annotations
+
+from rich.panel import Panel
+from rich.prompt import Prompt
+
+from .. import __version__
+from ..config import AppConfig
+from ..errors import MicforgeError
+from ..ui.theme import console
+from .calibrate import run_calibrate
+from .devices_cmd import run_setup, show_devices, show_presets
+from .doctor import run_doctor
+from .live import run_live
+from .test_mic import run_test
+
+MENU = [
+    ("1", "Start enhancer  (mic → virtual cable → Discord)"),
+    ("2", "Mic test       (record, compare, play back raw vs processed)"),
+    ("3", "Loopback       (hear yourself live, A/B raw vs processed)"),
+    ("4", "Calibrate room noise"),
+    ("5", "Setup devices"),
+    ("6", "Presets"),
+    ("7", "Settings & Hotkeys (global hotkeys, audio cues, autostart)"),
+    ("8", "Doctor         (diagnose problems)"),
+    ("q", "Quit"),
+]
+
+
+def run_wizard(app: AppConfig) -> None:
+    while True:
+        body = "\n".join(f"[bold cyan]{k}[/]  {v}" for k, v in MENU)
+        console.print(Panel(body, title=f"[bold]micforge[/] v{__version__}", subtitle=f"preset: {app.preset}",
+                            border_style="cyan", padding=(1, 3)))
+        choice = Prompt.ask("Choose", choices=[k for k, _ in MENU], default="1", console=console)
+        try:
+            if choice == "q":
+                return
+            if choice == "1":
+                run_live(app)
+            elif choice == "2":
+                run_test(app)
+            elif choice == "3":
+                run_live(app, loopback=True)
+            elif choice == "4":
+                run_calibrate(app)
+            elif choice == "5":
+                show_devices()
+                run_setup(app)
+            elif choice == "6":
+                show_presets(None)
+                name = Prompt.ask("Set default preset (Enter to skip)", default="", console=console).strip()
+                if name:
+                    from ..presets import get_preset
+                    get_preset(name)  # validates
+                    app.preset = name
+                    app.save()
+                    console.print(f"[green]Default preset: {name}[/]")
+            elif choice == "7":
+                from ..ui.settings_gui import launch_settings_gui
+                launch_settings_gui(app, standalone=True)
+            elif choice == "8":
+                run_doctor(app)
+        except MicforgeError as exc:
+            console.print(f"\n[bold red]✖ {exc}[/]")
+            if exc.hint:
+                console.print(f"[yellow]  → {exc.hint}[/]")
+        except KeyboardInterrupt:
+            console.print()
+        console.print()

micforge/config.py

@@ -0,0 +1,279 @@
+"""Typed configuration: DSP chain settings + application settings.
+
+Everything is a plain dataclass so it round-trips through JSON and stays easy
+to test. Unknown keys in files are ignored; missing keys fall back to defaults.
+"""
+from __future__ import annotations
+
+import dataclasses
+import json
+import os
+import sys
+import typing
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, TypeVar
+
+from .errors import ConfigError
+
+APP_NAME = "micforge"
+T = TypeVar("T")
+
+
+def config_dir() -> Path:
+    if os.name == "nt":
+        base = Path(os.environ.get("APPDATA", Path.home() / "AppData" / "Roaming"))
+    elif sys.platform == "darwin":
+        base = Path.home() / "Library" / "Application Support"
+    else:
+        base = Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config"))
+    return base / APP_NAME
+
+
+def _build(cls: type[T], data: dict[str, Any]) -> T:
+    """Recursively build a dataclass from a dict, ignoring unknown keys."""
+    hints = typing.get_type_hints(cls)
+    kwargs: dict[str, Any] = {}
+    for f in dataclasses.fields(cls):  # type: ignore[arg-type]
+        if f.name not in data:
+            continue
+        value, hint = data[f.name], hints[f.name]
+        if dataclasses.is_dataclass(hint) and isinstance(value, dict):
+            value = _build(hint, value)
+        elif typing.get_origin(hint) is list and isinstance(value, list):
+            (inner,) = typing.get_args(hint)
+            if dataclasses.is_dataclass(inner):
+                value = [_build(inner, v) for v in value if isinstance(v, dict)]
+        kwargs[f.name] = value
+    return cls(**kwargs)  # type: ignore[call-arg]
+
+
+# --------------------------------------------------------------------------- #
+# DSP chain configuration
+# --------------------------------------------------------------------------- #
+@dataclass
+class EQBand:
+    kind: str = "peak"  # peak | lowshelf | highshelf | highpass | lowpass | bandpass
+    freq: float = 1000.0
+    gain_db: float = 0.0
+    q: float = 0.707
+
+
+@dataclass
+class AECConfig:
+    enabled: bool = False  # Enabled when loopback reference is provided or active in preset
+    amount: float = 1.0  # 0..1 cancellation intensity
+    filter_length_ms: float = 60.0  # acoustic tail memory (20..200 ms)
+    delay_ms: float = 40.0  # speaker-to-mic loopback alignment (0..250 ms)
+    suppression_db: float = 24.0  # residual echo suppression floor (6..40 dB)
+
+
+@dataclass
+class DeverbConfig:
+    enabled: bool = True
+    amount: float = 0.5  # 0..1 late reverberation reduction aggression
+    room_decay: float = 0.4  # estimated RT60 decay time in seconds (0.15..1.5s)
+    early_retention: float = 0.8  # 0..1 preserves natural direct voice warmth
+
+
+@dataclass
+class ProximityConfig:
+    enabled: bool = True
+    amount: float = 0.5  # 0..1 chest resonance boost intensity
+    body_hz: float = 120.0  # center frequency of voice fundamental (70..250 Hz)
+    warmth: float = 0.35  # 0..1 even-order low harmonic saturation
+    mud_cleanup: float = 0.4  # 0..1 dynamic 300 Hz anti-boxiness cleanup
+
+
+@dataclass
+class DenoiseConfig:
+    enabled: bool = True
+    strength: float = 1.0  # 0..1, how aggressively noise is attenuated (1.0 = full neural suppression)
+    max_reduction_db: float = 24.0  # attenuation floor per bin
+    model_type: str = "cofilite"  # "cofilite" | "spectral"
+    model_path: str | None = None  # path to swappable model file (.onnx or .tar)
+
+
+@dataclass
+class GateConfig:
+    enabled: bool = True
+    threshold_db: float = -48.0  # soft expander threshold (eliminates ambient room tone/hiss in speech pauses)
+    range_db: float = 20.0  # how far the gate closes (soft expander, not a hard mute)
+    attack_ms: float = 3.0
+    hold_ms: float = 80.0
+    release_ms: float = 150.0
+    hysteresis_db: float = 4.0
+
+
+@dataclass
+class DeEsserConfig:
+    enabled: bool = True
+    freq_hz: float = 7000.0
+    threshold_db: float = -32.0
+    ratio: float = 3.0
+
+
+@dataclass
+class LevelerConfig:
+    enabled: bool = True
+    target_db: float = -20.0
+    max_gain_db: float = 9.0
+    max_cut_db: float = 6.0
+    gate_db: float = -48.0
+
+
+@dataclass
+class CompressorConfig:
+    enabled: bool = True
+    threshold_db: float = -22.0
+    ratio: float = 3.0
+    attack_ms: float = 6.0
+    release_ms: float = 90.0
+    knee_db: float = 6.0
+    makeup_db: float = 3.0
+
+
+@dataclass
+class LimiterConfig:
+    enabled: bool = True
+    ceiling_db: float = -1.5
+    release_ms: float = 60.0
+
+
+@dataclass
+class ChainConfig:
+    input_gain_db: float = 0.0
+    output_gain_db: float = 0.0
+    highpass_hz: float = 90.0  # 0 disables
+    aec: AECConfig = field(default_factory=AECConfig)
+    denoise: DenoiseConfig = field(default_factory=DenoiseConfig)
+    deverb: DeverbConfig = field(default_factory=DeverbConfig)
+    gate: GateConfig = field(default_factory=GateConfig)
+    proximity: ProximityConfig = field(default_factory=ProximityConfig)
+    eq_enabled: bool = True
+    eq: list[EQBand] = field(default_factory=list)
+    deesser: DeEsserConfig = field(default_factory=DeEsserConfig)
+    leveler: LevelerConfig = field(default_factory=LevelerConfig)
+    compressor: CompressorConfig = field(default_factory=CompressorConfig)
+    limiter: LimiterConfig = field(default_factory=LimiterConfig)
+
+    def to_dict(self) -> dict[str, Any]:
+        return dataclasses.asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "ChainConfig":
+        cfg = _build(cls, data)
+        cfg.validate()
+        return cfg
+
+    def validate(self) -> None:
+        def check(cond: bool, msg: str) -> None:
+            if not cond:
+                raise ConfigError(msg)
+
+        check(-40 <= self.input_gain_db <= 40, "input_gain_db must be within -40..40")
+        check(-40 <= self.output_gain_db <= 40, "output_gain_db must be within -40..40")
+        check(0 <= self.highpass_hz <= 400, "highpass_hz must be within 0..400")
+        check(0.0 <= self.aec.amount <= 1.0, "aec.amount must be within 0..1")
+        check(0.0 <= self.deverb.amount <= 1.0, "deverb.amount must be within 0..1")
+        check(0.0 <= self.proximity.amount <= 1.0, "proximity.amount must be within 0..1")
+        check(0.0 <= self.denoise.strength <= 1.0, "denoise.strength must be within 0..1")
+        check(0 <= self.denoise.max_reduction_db <= 60, "denoise.max_reduction_db must be within 0..60")
+        check(self.denoise.model_type in ("cofilite", "spectral"), "denoise.model_type must be 'cofilite' or 'spectral'")
+        check(self.gate.range_db >= 0, "gate.range_db must be >= 0")
+        check(self.compressor.ratio >= 1.0, "compressor.ratio must be >= 1")
+        check(self.deesser.ratio >= 1.0, "deesser.ratio must be >= 1")
+        check(self.limiter.ceiling_db <= 0, "limiter.ceiling_db must be <= 0")
+        valid = {"peak", "lowshelf", "highshelf", "highpass", "lowpass", "bandpass"}
+        for b in self.eq:
+            check(b.kind in valid, f"unknown EQ band kind {b.kind!r}")
+            check(b.freq > 0 and b.q > 0, "EQ band freq and q must be > 0")
+
+
+# --------------------------------------------------------------------------- #
+# Application configuration
+# --------------------------------------------------------------------------- #
+DeviceSpec = typing.Union[str, int, None]
+
+
+@dataclass
+class HotkeyConfig:
+    toggle_mute: str = "ctrl+shift+m"
+    push_to_mute: str = ""
+    push_to_talk: str = ""
+    toggle_bypass: str = "ctrl+shift+b"
+    play_cues: bool = True
+    cue_volume: float = 0.5
+    start_in_tray: bool = False
+
+
+@dataclass
+class AppConfig:
+    sample_rate: int = 48000
+    block_size: int = 480  # 10 ms @ 48 kHz
+    jitter_blocks: float = 3.0  # output prefill in blocks; 3.0 = 30 ms rock-solid cushion (glitch-proof for gaming)
+    input_device: DeviceSpec = None  # name substring or index; None = system default
+    output_device: DeviceSpec = None  # virtual cable (Discord reads its other end)
+    monitor_device: DeviceSpec = None  # your headphones, for self-monitoring
+    aec_reference_device: DeviceSpec = None  # speaker/loopback capture device for AEC (None = auto-detect loopback)
+    input_channel: int = 0
+    preset: str = "discord"
+    denoise_model: str | None = None  # custom swappable model path (.onnx or .tar)
+    hotkeys: HotkeyConfig = field(default_factory=HotkeyConfig)
+
+    @property
+    def mic(self) -> DeviceSpec:
+        return self.input_device
+
+    @mic.setter
+    def mic(self, val: DeviceSpec) -> None:
+        self.input_device = val
+
+    @property
+    def cable(self) -> DeviceSpec:
+        return self.output_device
+
+    @cable.setter
+    def cable(self, val: DeviceSpec) -> None:
+        self.output_device = val
+
+    @staticmethod
+    def path() -> Path:
+        return config_dir() / "config.json"
+
+    @classmethod
+    def load(cls) -> "AppConfig":
+        p = cls.path()
+        if not p.exists():
+            return cls()
+        try:
+            data = json.loads(p.read_text(encoding="utf-8"))
+            cfg = _build(cls, data)
+        except (OSError, ValueError, TypeError) as exc:
+            raise ConfigError(
+                f"Could not read {p}: {exc}",
+                hint=f"Delete {p} to reset to defaults.",
+            ) from exc
+        # Ensure balanced, glitch-resistant default of 3.0 blocks (30ms cushion)
+        jb = getattr(cfg, "jitter_blocks", 3.0)
+        if jb < 1.0 or jb > 8.0 or jb in (1.5, 2.5):
+            cfg.jitter_blocks = 3.0
+        cfg.validate()
+        return cfg
+
+    def save(self) -> None:
+        p = self.path()
+        p.parent.mkdir(parents=True, exist_ok=True)
+        tmp = p.with_suffix(".tmp")
+        tmp.write_text(json.dumps(dataclasses.asdict(self), indent=2), encoding="utf-8")
+        tmp.replace(p)
+
+    def validate(self) -> None:
+        if self.sample_rate not in (16000, 22050, 24000, 32000, 44100, 48000, 96000):
+            raise ConfigError(f"Unsupported sample_rate {self.sample_rate}", hint="Use 48000 or 44100.")
+        if not 64 <= self.block_size <= 4096:
+            raise ConfigError("block_size must be within 64..4096")
+        if not 1.0 <= float(self.jitter_blocks) <= 8.0:
+            raise ConfigError("jitter_blocks must be within 1.0..8.0")
+        if self.input_channel < 0:
+            raise ConfigError("input_channel must be >= 0")

micforge/diagnostics.py

@@ -0,0 +1,308 @@
+"""Export diagnostics with redaction, system inspection, and plain-English doctor summary."""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import platform
+import re
+import sys
+import tempfile
+import time
+import zipfile
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+from . import __version__
+from .audio.backend import get_sd
+from .audio.devices import detect_virtual_output, find_device, list_devices
+from .config import AppConfig, config_dir
+
+log = logging.getLogger("micforge.diagnostics")
+
+SECRET_KEY_PATTERNS = [
+    re.compile(r"(api[_-]?key|token|secret|password|auth|webhook[_-]?url|credential)", re.IGNORECASE),
+]
+
+URL_AUTH_PATTERN = re.compile(r"://([^:]+):([^@]+)@")
+
+
+def redact_secrets(obj: Any) -> Any:
+    """Recursively redact secrets and user home directories from data structures."""
+    user_home = str(Path.home())
+    user_home_forward = user_home.replace("\\", "/")
+
+    def _clean_str(s: str) -> str:
+        # Redact embedded credentials in URLs
+        s = URL_AUTH_PATTERN.sub("://***:***@", s)
+        # Redact home paths
+        if user_home in s:
+            s = s.replace(user_home, "<USER_HOME>")
+        if user_home_forward in s:
+            s = s.replace(user_home_forward, "<USER_HOME>")
+        return s
+
+    if isinstance(obj, dict):
+        cleaned: dict[str, Any] = {}
+        for k, v in obj.items():
+            k_str = str(k)
+            # Check if key implies secret
+            if any(p.search(k_str) for p in SECRET_KEY_PATTERNS):
+                cleaned[k_str] = "***REDACTED***"
+            else:
+                cleaned[k_str] = redact_secrets(v)
+        return cleaned
+    elif isinstance(obj, (list, tuple)):
+        return [redact_secrets(item) for item in obj]
+    elif isinstance(obj, str):
+        return _clean_str(obj)
+    return obj
+
+
+@dataclass
+class DiagnosticReport:
+    """Complete system diagnostic telemetry."""
+    micforge_version: str = __version__
+    timestamp: float = field(default_factory=time.time)
+    platform_info: dict[str, str] = field(default_factory=dict)
+    package_versions: dict[str, str] = field(default_factory=dict)
+    config_summary: dict[str, Any] = field(default_factory=dict)
+    devices: list[dict[str, Any]] = field(default_factory=list)
+    engine_stats: dict[str, Any] = field(default_factory=dict)
+    noise_profile: dict[str, Any] = field(default_factory=dict)
+    doctor_checks: list[dict[str, str]] = field(default_factory=list)
+    overall_status: str = "HEALTHY"  # HEALTHY | WARNING | CRITICAL
+    summary_text: str = ""
+    next_steps: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def collect_diagnostics(
+    app: AppConfig,
+    engine_snapshot: Any | None = None,
+    recent_logs: list[str] | None = None,
+) -> DiagnosticReport:
+    """Gather complete diagnostic data with all secrets redacted."""
+    report = DiagnosticReport()
+
+    # 1. Platform Info
+    report.platform_info = {
+        "os": platform.system(),
+        "release": platform.release(),
+        "version": platform.version(),
+        "machine": platform.machine(),
+        "processor": platform.processor(),
+        "python_version": platform.python_version(),
+        "python_executable": redact_secrets(sys.executable),
+    }
+
+    # 2. Package Versions
+    pkgs = {"micforge": __version__, "python": sys.version.split()[0]}
+    for mod_name in ("sounddevice", "numpy", "scipy", "onnxruntime", "psutil", "rich"):
+        try:
+            m = __import__(mod_name)
+            pkgs[mod_name] = getattr(m, "__version__", "installed")
+        except ImportError:
+            pkgs[mod_name] = "not installed"
+    report.package_versions = pkgs
+
+    # 3. Redacted Config
+    try:
+        report.config_summary = redact_secrets(app.to_dict())
+    except Exception as exc:
+        report.config_summary = {"error": str(exc)}
+
+    # 4. Audio Devices
+    try:
+        pool = list_devices(all_apis=True)
+        report.devices = [
+            {
+                "index": d.index,
+                "name": d.name,
+                "hostapi": d.hostapi,
+                "max_input": d.max_input,
+                "max_output": d.max_output,
+                "default_rate": d.default_rate,
+                "is_default_input": d.is_default_input,
+                "is_default_output": d.is_default_output,
+            }
+            for d in pool
+        ]
+    except Exception as exc:
+        report.devices = [{"error": str(exc)}]
+
+    # 5. Engine Runtime Stats
+    if engine_snapshot is not None:
+        report.engine_stats = {
+            "running": getattr(engine_snapshot, "running", False),
+            "cpu_load_pct": round(getattr(engine_snapshot, "cpu_load", 0.0) * 100, 1),
+            "latency_ms": round(getattr(engine_snapshot, "latency_ms", 0.0), 1),
+            "output_underruns": getattr(engine_snapshot, "output_underruns", 0),
+            "input_overflows": getattr(engine_snapshot, "input_overflows", 0),
+            "drift_corrections": getattr(engine_snapshot, "drift_corrections", 0),
+            "errors": getattr(engine_snapshot, "errors", 0),
+            "bypass": getattr(engine_snapshot, "bypass", False),
+            "muted": getattr(engine_snapshot, "muted", False),
+        }
+        if hasattr(engine_snapshot, "noise_profile") and engine_snapshot.noise_profile:
+            np = engine_snapshot.noise_profile
+            report.noise_profile = {
+                "name": getattr(np, "name", "unknown"),
+                "noise_floor_db": getattr(np, "noise_floor_db", -62.0),
+                "gate_threshold_db": getattr(np, "gate_threshold_db", -50.0),
+                "frozen": getattr(np, "frozen", False),
+            }
+
+    # 6. Run Doctor Checks
+    _run_doctor_assessment(report, app)
+    return report
+
+
+def _run_doctor_assessment(report: DiagnosticReport, app: AppConfig) -> None:
+    """Generate plain-English health assessment with next steps."""
+    checks = []
+    issues = 0
+    critical = 0
+
+    # Check 1: Python
+    if sys.version_info >= (3, 10):
+        checks.append({"name": "Python Runtime", "status": "OK", "detail": f"Python {platform.python_version()} (compatible)"})
+    else:
+        checks.append({"name": "Python Runtime", "status": "BAD", "detail": f"Python {platform.python_version()} is older than 3.10"})
+        critical += 1
+
+    # Check 2: Audio Backend
+    try:
+        sd = get_sd()
+        pa_ver = str(sd.get_portaudio_version()[1])
+        checks.append({"name": "PortAudio Engine", "status": "OK", "detail": pa_ver})
+    except Exception as exc:
+        checks.append({"name": "PortAudio Engine", "status": "CRITICAL", "detail": f"Could not load audio backend: {exc}"})
+        critical += 1
+
+    # Check 3: Input Microphone
+    pool = list_devices(all_apis=True)
+    try:
+        mic = find_device(app.input_device, "input", pool)
+        checks.append({"name": "Microphone", "status": "OK", "detail": f"{mic.name} [{mic.hostapi}]"})
+    except Exception as exc:
+        checks.append({"name": "Microphone", "status": "CRITICAL", "detail": f"Microphone device not found: {exc}"})
+        critical += 1
+
+    # Check 4: Virtual Cable (for Discord/OBS)
+    cable = None
+    if app.output_device is not None:
+        try:
+            cable = find_device(app.output_device, "output", pool)
+        except Exception:
+            pass
+    if cable is None:
+        cable = detect_virtual_output(pool)
+
+    if cable is not None:
+        checks.append({"name": "Virtual Cable", "status": "OK", "detail": f"{cable.name} (Discord/OBS ready)"})
+    else:
+        checks.append({
+            "name": "Virtual Cable",
+            "status": "WARN",
+            "detail": "No virtual cable (VB-CABLE / BlackHole) detected. Discord won't receive processed audio directly.",
+        })
+        issues += 1
+
+    # Check 5: Latency & Real-Time Performance
+    if report.engine_stats:
+        lat = report.engine_stats.get("latency_ms", 0.0)
+        underruns = report.engine_stats.get("output_underruns", 0)
+        drift = report.engine_stats.get("drift_corrections", 0)
+        if underruns == 0:
+            checks.append({"name": "Audio Buffer Sync", "status": "OK", "detail": "Zero dropped glitches, perfect stream sync"})
+        else:
+            checks.append({"name": "Audio Buffer Sync", "status": "WARN", "detail": f"{underruns} buffer glitches dropped"})
+            issues += 1
+
+    report.doctor_checks = checks
+
+    # Assign overall status
+    if critical > 0:
+        report.overall_status = "CRITICAL"
+        report.summary_text = "Micforge detected critical configuration or hardware issues preventing normal audio routing."
+        report.next_steps = [
+            "Check that your USB microphone is plugged in and authorized in OS privacy settings.",
+            "Review docs/TROUBLESHOOTING.md for device connection troubleshooting.",
+            "Run 'micforge setup' to re-select active microphone and playback endpoints.",
+        ]
+    elif issues > 0:
+        report.overall_status = "WARNING"
+        report.summary_text = "Micforge is operational, but one or more optimizations (like virtual cable routing) need attention."
+        report.next_steps = [
+            "Install a free virtual audio cable (e.g. VB-CABLE on Windows or BlackHole on macOS).",
+            "Set Discord's Input Device to 'CABLE Output (VB-Audio Virtual Cable)'.",
+            "See docs/TROUBLESHOOTING.md for step-by-step app setup guides.",
+        ]
+    else:
+        report.overall_status = "HEALTHY"
+        report.summary_text = "All systems healthy! Audio routing, noise profile, and DSP pipeline are streaming cleanly."
+        report.next_steps = [
+            "In Discord/Zoom/OBS, verify your input is set to your Virtual Cable.",
+            "Press [Tab] in the live terminal to switch between Studio Inspector and Gamer HUD.",
+        ]
+
+
+def export_diagnostics_zip(
+    report: DiagnosticReport,
+    output_path: Path | None = None,
+    recent_logs: list[str] | None = None,
+) -> Path:
+    """Create a single .zip diagnostic bundle containing redacted config, report, and logs."""
+    timestamp_str = time.strftime("%Y%m%d_%H%M%S", time.localtime(report.timestamp))
+    if output_path is None:
+        target_dir = config_dir() / "diagnostics"
+        target_dir.mkdir(parents=True, exist_ok=True)
+        zip_path = target_dir / f"micforge_diagnostics_{timestamp_str}.zip"
+    else:
+        zip_path = Path(output_path)
+        zip_path.parent.mkdir(parents=True, exist_ok=True)
+
+    with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zf:
+        # 1. Full JSON Report
+        zf.writestr("diagnostic_report.json", json.dumps(report.to_dict(), indent=2))
+
+        # 2. Plain-English Doctor Summary
+        doc_lines = [
+            f"Micforge Diagnostic Doctor Summary (v{report.micforge_version})",
+            f"Generated: {time.ctime(report.timestamp)}",
+            "=" * 60,
+            f"Overall Status: {report.overall_status}",
+            f"Summary: {report.summary_text}",
+            "",
+            "Health Checks:",
+        ]
+        for c in report.doctor_checks:
+            doc_lines.append(f"  [{c['status']:<4}] {c['name']:<24}: {c['detail']}")
+        doc_lines.append("")
+        doc_lines.append("Recommended Next Steps:")
+        for step in report.next_steps:
+            doc_lines.append(f"  • {step}")
+        doc_lines.append("")
+        doc_lines.append("See docs/TROUBLESHOOTING.md for comprehensive solutions.")
+        zf.writestr("doctor_summary.txt", "\n".join(doc_lines))
+
+        # 3. Audio Devices Inventory
+        dev_lines = ["Audio Devices Inventory:\n"]
+        for d in report.devices:
+            dev_lines.append(f"[{d.get('index', '?')}] {d.get('name', 'unknown')} (in={d.get('max_input', 0)}, out={d.get('max_output', 0)}) hostapi={d.get('hostapi', '?')}")
+        zf.writestr("devices.txt", "\n".join(dev_lines))
+
+        # 4. Redacted Config
+        zf.writestr("config_redacted.json", json.dumps(report.config_summary, indent=2))
+
+        # 5. Recent Logs
+        log_content = "\n".join(recent_logs) if recent_logs else "No active log buffer captured."
+        zf.writestr("recent_logs.txt", redact_secrets(log_content))
+
+    log.info("Exported diagnostics zip to %s", zip_path)
+    return zip_path
+