nat-engine 1__py3-none-any.whl

mannf/product/cli.py

@@ -0,0 +1,3900 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+# Commercial licensing available — see COMMERCIAL_LICENSE.md.
+
+"""CLI entry point for the NeuroAgentTest (NAT) framework.
+
+Usage::
+
+    nat scan --spec path/to/openapi.yaml --base-url http://localhost:8080
+    python -m mannf scan --spec path/to/openapi.yaml --base-url http://localhost:8080
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import importlib
+import json
+import logging
+import os
+import sys
+import xml.etree.ElementTree as ET
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Optional
+
+from mannf._version import __version__
+
+if TYPE_CHECKING:
+    from mannf.core.testing.models import TestSuite
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Exit code constants
+# ---------------------------------------------------------------------------
+EXIT_OK = 0          # all tests passed
+EXIT_FAILURES = 1    # one or more test failures detected
+EXIT_SCAN_ERROR = 2  # scan error (connection failure, spec parse error, runtime exception)
+EXIT_CONFIG_ERROR = 3  # configuration error (invalid flags, missing required args, bad config file)
+
+
+# ---------------------------------------------------------------------------
+# Config file support (.natrc)
+# ---------------------------------------------------------------------------
+
+# Severity icons used in security scan output
+_SEVERITY_ICONS: dict[str, str] = {
+    "critical": "🔴",
+    "high": "🟠",
+    "medium": "🟡",
+    "low": "🔵",
+    "info": "ℹ️",
+}
+
+def _load_natrc(config_path: Optional[str] = None) -> dict:
+    """Load a YAML ``.natrc`` config file and return its contents as a dict.
+
+    Search order (unless *config_path* is explicitly given):
+    1. ``--config PATH`` value
+    2. ``.natrc`` in the current working directory
+    3. ``~/.natrc`` in the user's home directory
+
+    Returns an empty dict if no file is found.
+    Raises :class:`ValueError` if the file exists but cannot be parsed.
+    """
+    import yaml  # pyyaml is a listed dependency
+
+    candidates: list[str] = []
+    if config_path:
+        candidates = [config_path]
+    else:
+        candidates = [
+            str(Path.cwd() / ".natrc"),
+            str(Path.home() / ".natrc"),
+        ]
+
+    for path in candidates:
+        if os.path.isfile(path):
+            try:
+                with open(path, encoding="utf-8") as fh:
+                    data = yaml.safe_load(fh)
+                if data is None:
+                    return {}
+                if not isinstance(data, dict):
+                    raise ValueError(f"Config file {path!r} must be a YAML mapping, got {type(data).__name__}")
+                logger.debug("Loaded config from %s", path)
+                return data
+            except Exception as exc:
+                raise ValueError(f"Failed to parse config file {path!r}: {exc}") from exc
+
+    if config_path:
+        raise OSError(f"Config file not found: {config_path!r}")
+
+    return {}
+
+
+def _apply_config_defaults(parser: argparse.ArgumentParser, config: dict) -> None:
+    """Set *config* values as defaults on every sub-command parser.
+
+    CLI flags override these defaults because argparse processes command-line
+    arguments after defaults are set.
+    """
+    defaults = {k.replace("-", "_"): v for k, v in config.items()}
+    if not defaults:
+        return
+    for action in parser._subparsers._group_actions:  # type: ignore[attr-defined]
+        for subparser in action.choices.values():
+            subparser.set_defaults(**defaults)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="nat",
+        description=(
+            "NeuroAgentTest (NAT) — Adaptive API Testing Framework\n\n"
+            "Exit codes:\n"
+            "  0  All tests passed\n"
+            "  1  One or more test failures detected\n"
+            "  2  Scan error (connection failure, spec parse error, runtime exception)\n"
+            "  3  Configuration error (invalid flags, missing required args, bad config file)"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--config",
+        metavar="PATH",
+        default=None,
+        help="Path to a YAML config file (default: .natrc in cwd or ~/.natrc).",
+    )
+    parser.add_argument(
+        "--version", "-V",
+        action="version",
+        version=f"nat {__version__}",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    scan = subparsers.add_parser(
+        "scan",
+        help="Parse an OpenAPI spec and run adaptive tests against a live API.",
+    )
+    scan.add_argument(
+        "--spec",
+        required=False,
+        default=None,
+        metavar="PATH",
+        help="Path to an OpenAPI 3.x or Swagger 2.x spec file (JSON or YAML), or a Postman Collection v2.1 JSON file.",
+    )
+    scan.add_argument(
+        "--format",
+        choices=["openapi", "postman"],
+        default="openapi",
+        help="Spec format: openapi (default) or postman (Postman Collection v2.1).",
+    )
+    scan.add_argument(
+        "--base-url",
+        required=False,
+        default=None,
+        metavar="URL",
+        help="Base URL of the API under test (e.g. http://localhost:8080).",
+    )
+    scan.add_argument(
+        "--type",
+        choices=["rest", "graphql", "grpc", "websocket"],
+        default="rest",
+        help="API type: rest (default), graphql, grpc, or websocket.",
+    )
+    scan.add_argument(
+        "--graphql-introspection",
+        action="store_true",
+        help="Auto-discover GraphQL schema via introspection (only used with --type graphql).",
+    )
+    scan.add_argument(
+        "--proto",
+        metavar="PATH",
+        default=None,
+        help="Path to a .proto file (used with --type grpc).",
+    )
+    scan.add_argument(
+        "--grpc-endpoint",
+        metavar="HOST:PORT",
+        default=None,
+        dest="grpc_endpoint",
+        help="gRPC server address in host:port format (used with --type grpc).",
+    )
+    scan.add_argument(
+        "--grpc-use-tls",
+        action="store_true",
+        default=False,
+        dest="grpc_use_tls",
+        help="Use TLS for gRPC connections (used with --type grpc).",
+    )
+    scan.add_argument(
+        "--asyncapi",
+        metavar="PATH",
+        default=None,
+        help="Path to an AsyncAPI spec file (used with --type websocket).",
+    )
+    scan.add_argument(
+        "--ws-endpoint",
+        metavar="URL",
+        default=None,
+        dest="ws_endpoint",
+        help="WebSocket base URL (e.g. ws://localhost:8765) (used with --type websocket).",
+    )
+    scan.add_argument(
+        "--auth-token",
+        metavar="TOKEN",
+        default=None,
+        help="Bearer token for Authorization header.",
+    )
+    scan.add_argument(
+        "--api-key",
+        metavar="KEY",
+        default=None,
+        help="API key value sent in X-API-Key header.",
+    )
+    scan.add_argument(
+        "--api-key-header",
+        metavar="HEADER",
+        default="X-API-Key",
+        help="Header name for the API key (default: X-API-Key).",
+    )
+    # OAuth2 args
+    scan.add_argument("--oauth2-token-url", metavar="URL", default=None, help="OAuth2 token endpoint URL.")
+    scan.add_argument("--oauth2-client-id", metavar="ID", default=None, help="OAuth2 client ID.")
+    scan.add_argument("--oauth2-client-secret", metavar="SECRET", default=None, help="OAuth2 client secret.")
+    scan.add_argument("--oauth2-scopes", metavar="SCOPES", default=None, help="Comma-separated OAuth2 scopes.")
+    scan.add_argument(
+        "--oauth2-grant-type",
+        metavar="TYPE",
+        default="client_credentials",
+        help="OAuth2 grant type (default: client_credentials).",
+    )
+    scan.add_argument(
+        "--max-tests",
+        type=int,
+        default=None,
+        metavar="N",
+        help="Maximum number of test cases to run.",
+    )
+    scan.add_argument(
+        "--executors",
+        type=int,
+        default=3,
+        metavar="N",
+        help="Number of executor agents (default: 3).",
+    )
+    scan.add_argument(
+        "--timeout",
+        type=float,
+        default=10.0,
+        metavar="SECONDS",
+        help="HTTP request timeout in seconds (default: 10).",
+    )
+    scan.add_argument(
+        "--latency-sla",
+        type=float,
+        default=None,
+        metavar="MS",
+        help="Latency SLA in milliseconds — responses slower than this fail.",
+    )
+    scan.add_argument(
+        "--output",
+        "-o",
+        choices=["text", "json", "html", "junit", "allure", "ctrf", "pdf"],
+        default="text",
+        help="Output format: text (default), json, html, junit, allure, ctrf, pdf.",
+    )
+    scan.add_argument(
+        "--output-file",
+        metavar="PATH",
+        default=None,
+        help="Write output to this file instead of stdout (default: stdout for text/json; "
+             "auto-named file for html/junit/ctrf; output directory for allure).",
+    )
+    scan.add_argument(
+        "--trace-dir",
+        metavar="DIR",
+        default=None,
+        help="Directory to write Playwright trace .zip files when running browser-based "
+             "autonomous scenarios.  Traces can be replayed in Playwright Trace Viewer.",
+    )
+    scan.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Enable verbose logging.",
+    )
+    # Regression flags
+    scan.add_argument(
+        "--record-regression",
+        metavar="OUTPUT_FILE",
+        default=None,
+        help="Record a regression baseline to the specified JSON file.",
+    )
+    scan.add_argument(
+        "--replay",
+        metavar="BASELINE_FILE",
+        default=None,
+        help="Replay a prior regression baseline and compare results.",
+    )
+    scan.add_argument(
+        "--regression-diff-only",
+        action="store_true",
+        help="Only show differences when replaying (suppress unchanged endpoints).",
+    )
+    scan.add_argument(
+        "--mask-sensitive",
+        action="store_true",
+        help="Mask sensitive data (auth headers, tokens) in regression recordings.",
+    )
+    # Weight persistence flags
+    scan.add_argument(
+        "--save-weights",
+        metavar="PATH",
+        default=None,
+        help="After scan completes, save all agent weights to this JSON file.",
+    )
+    scan.add_argument(
+        "--load-weights",
+        metavar="PATH",
+        default=None,
+        help="Before scan starts, load pretrained weights from this JSON file.",
+    )
+    scan.add_argument(
+        "--weights-dir",
+        metavar="DIR",
+        default=None,
+        help="Directory for auto-save/auto-load of weights (saves after each scan, "
+             "loads the latest on the next scan for the same API).",
+    )
+    # Healing flags
+    scan.add_argument(
+        "--previous-spec",
+        metavar="PATH",
+        default=None,
+        help="Path to the previous spec. When provided, NAT diffs it against --spec "
+             "and runs self-healing before executing the scan.",
+    )
+    scan.add_argument(
+        "--healing-report",
+        metavar="PATH",
+        default=None,
+        help="Save the healing report to this JSON file (used with --previous-spec).",
+    )
+    # LLM augmentation flags
+    scan.add_argument(
+        "--use-llm",
+        action="store_true",
+        default=False,
+        help="Enable LLM-augmented test case generation (default: off).",
+    )
+    scan.add_argument(
+        "--llm-provider",
+        choices=["openai", "anthropic"],
+        default="openai",
+        metavar="PROVIDER",
+        help="LLM provider to use: openai (default) or anthropic.",
+    )
+    scan.add_argument(
+        "--llm-model",
+        default=None,
+        metavar="MODEL",
+        help="LLM model name override (e.g. gpt-4o, claude-3-5-sonnet-20241022).",
+    )
+    scan.add_argument(
+        "--llm-api-key",
+        default=None,
+        metavar="KEY",
+        help="LLM API key (alternative to OPENAI_API_KEY / ANTHROPIC_API_KEY env vars).",
+    )
+
+    security = subparsers.add_parser(
+        "security-scan",
+        help="Run OWASP API Security Top 10 checks against an API.",
+    )
+    security.add_argument("--spec", required=False, default=None, metavar="PATH", help="Path to OpenAPI spec file or Postman Collection v2.1 JSON file.")
+    security.add_argument(
+        "--format",
+        choices=["openapi", "postman"],
+        default="openapi",
+        help="Spec format: openapi (default) or postman (Postman Collection v2.1).",
+    )
+    security.add_argument("--base-url", required=False, default=None, metavar="URL", help="Base URL of the API to test.")
+    security.add_argument(
+        "--type",
+        choices=["rest", "graphql"],
+        default="rest",
+        help="API type: rest (default) or graphql.",
+    )
+    security.add_argument("--checks", metavar="CHECKS", default=None,
+                          help="Comma-separated OWASP check IDs (e.g. API1,API2,API8). Default: all.")
+    security.add_argument("--severity-threshold", metavar="LEVEL", default="low",
+                          choices=["critical", "high", "medium", "low", "info"],
+                          help="Minimum severity to report (default: low).")
+    security.add_argument("--output", "-o", choices=["text", "json", "markdown"], default="text",
+                          help="Output format: text (default), json, markdown.")
+    security.add_argument(
+        "--output-file",
+        metavar="PATH",
+        default=None,
+        help="Write output to this file instead of stdout.",
+    )
+    security.add_argument("--belief-guided", action="store_true", default=True,
+                          help="Use neural network risk scores to prioritize (default: true).")
+    security.add_argument(
+        "--prioritization",
+        choices=["adaptive", "static", "off"],
+        default="adaptive",
+        help=(
+            "Prioritization mode: 'adaptive' (default) uses live BDI belief states, "
+            "'static' uses keyword/verb heuristics only, 'off' scans in spec order."
+        ),
+    )
+    security.add_argument("--verbose", action="store_true", help="Enable verbose logging.")
+    # OAuth2 args for security-scan
+    security.add_argument("--oauth2-token-url", metavar="URL", default=None, help="OAuth2 token endpoint URL.")
+    security.add_argument("--oauth2-client-id", metavar="ID", default=None, help="OAuth2 client ID.")
+    security.add_argument("--oauth2-client-secret", metavar="SECRET", default=None, help="OAuth2 client secret.")
+    security.add_argument("--oauth2-scopes", metavar="SCOPES", default=None, help="Comma-separated OAuth2 scopes.")
+    security.add_argument(
+        "--oauth2-grant-type",
+        metavar="TYPE",
+        default="client_credentials",
+        help="OAuth2 grant type (default: client_credentials).",
+    )
+    # LLM augmentation flags
+    security.add_argument("--use-llm", action="store_true", default=False,
+                          help="Enable LLM-augmented test generation (default: off).")
+    security.add_argument("--llm-provider", choices=["openai", "anthropic"], default="openai",
+                          metavar="PROVIDER", help="LLM provider: openai (default) or anthropic.")
+    security.add_argument("--llm-model", default=None, metavar="MODEL", help="LLM model name override.")
+    security.add_argument("--llm-api-key", default=None, metavar="KEY", help="LLM API key.")
+    # Plugin flags
+    security.add_argument(
+        "--plugins-dir",
+        metavar="PATH",
+        default=None,
+        help="Path to a directory containing custom check plugin .py files.",
+    )
+    security.add_argument(
+        "--plugin",
+        metavar="MODULE.ClassName",
+        action="append",
+        dest="plugins",
+        default=None,
+        help=(
+            "Fully-qualified Python class name to load as a plugin "
+            "(e.g. mypackage.checks.MyCheck). Can be specified multiple times."
+        ),
+    )
+    # Exporter flags
+    security.add_argument(
+        "--export",
+        metavar="NAME",
+        default=None,
+        help="Name of the exporter plugin to use (e.g. jira, linear, github-issues, console).",
+    )
+    security.add_argument(
+        "--exporters-dir",
+        metavar="PATH",
+        default=None,
+        help="Path to a directory containing custom exporter plugin .py files.",
+    )
+    security.add_argument(
+        "--export-config",
+        metavar="KEY=VALUE",
+        action="append",
+        dest="export_config",
+        default=None,
+        help=(
+            "Exporter-specific config as key=value pairs "
+            "(e.g. --export-config jira_url=https://myco.atlassian.net). "
+            "Can be specified multiple times."
+        ),
+    )
+    security.add_argument(
+        "--export-min-severity",
+        metavar="LEVEL",
+        choices=["critical", "high", "medium", "low", "info"],
+        default="low",
+        help="Minimum severity level to export (default: low).",
+    )
+
+    # ----------------------------------------------------------------
+    # weights sub-command group
+    # ----------------------------------------------------------------
+    weights = subparsers.add_parser(
+        "weights",
+        help="Manage saved weight snapshots.",
+    )
+    weights_sub = weights.add_subparsers(dest="weights_command", required=True)
+
+    # nat weights list
+    weights_sub.add_parser(
+        "list",
+        help="List all registered weight snapshots.",
+    )
+
+    # nat weights save
+    weights_save = weights_sub.add_parser(
+        "save",
+        help="Save weights from a completed scan to a file and register the snapshot.",
+    )
+    weights_save.add_argument(
+        "--scan-id",
+        metavar="ID",
+        required=True,
+        help="ID of the completed scan whose agent weights to save.",
+    )
+    weights_save.add_argument(
+        "--output",
+        metavar="PATH",
+        required=True,
+        help="Output file path for the weight JSON file.",
+    )
+    weights_save.add_argument(
+        "--name",
+        metavar="NAME",
+        default=None,
+        help="Human-readable name to register the snapshot under (defaults to the scan ID).",
+    )
+
+    # nat weights info
+    weights_info = weights_sub.add_parser(
+        "info",
+        help="Show metadata about a weight file.",
+    )
+    weights_info.add_argument(
+        "path",
+        metavar="PATH",
+        help="Path to the weight JSON file (or a registered snapshot name).",
+    )
+
+    # ----------------------------------------------------------------
+    # export sub-command group
+    # ----------------------------------------------------------------
+    export = subparsers.add_parser(
+        "export",
+        help="Manage and inspect exporter plugins.",
+    )
+    export_sub = export.add_subparsers(dest="export_command", required=True)
+
+    # nat export list
+    export_list = export_sub.add_parser(
+        "list",
+        help="List all available exporter plugins (built-in + discovered).",
+    )
+    export_list.add_argument(
+        "--json",
+        action="store_true",
+        default=False,
+        dest="json_output",
+        help="Output as JSON (for CI/automation).",
+    )
+
+    # ----------------------------------------------------------------
+    # heal sub-command
+    # ----------------------------------------------------------------
+    heal = subparsers.add_parser(
+        "heal",
+        help="Detect API schema drift and show what would be healed (dry-run).",
+    )
+    heal.add_argument(
+        "--old-spec",
+        metavar="PATH",
+        required=True,
+        help="Path to the previous OpenAPI spec file.",
+    )
+    heal.add_argument(
+        "--new-spec",
+        metavar="PATH",
+        required=True,
+        help="Path to the current (updated) OpenAPI spec file.",
+    )
+    heal.add_argument(
+        "--output",
+        choices=["text", "json", "markdown"],
+        default="text",
+        help="Output format for the healing report (default: text).",
+    )
+    heal.add_argument(
+        "--healing-report",
+        metavar="PATH",
+        default=None,
+        help="Save healing report to this file path.",
+    )
+
+    # ----------------------------------------------------------------
+    # test-gen sub-command
+    # ----------------------------------------------------------------
+    test_gen = subparsers.add_parser(
+        "test-gen",
+        help="Generate test cases from a spec and print them (without running a scan).",
+    )
+    test_gen.add_argument(
+        "--spec",
+        required=True,
+        metavar="PATH",
+        help="Path to an OpenAPI 3.x or Swagger 2.x spec file.",
+    )
+    test_gen.add_argument(
+        "--base-url",
+        default="http://localhost:8080",
+        metavar="URL",
+        help="Base URL used for test case targets (default: http://localhost:8080).",
+    )
+    test_gen.add_argument(
+        "--output",
+        choices=["text", "json"],
+        default="text",
+        help="Output format (default: text).",
+    )
+    test_gen.add_argument(
+        "--use-llm",
+        action="store_true",
+        default=False,
+        help="Augment generated cases with LLM-generated edge cases.",
+    )
+    test_gen.add_argument(
+        "--llm-provider",
+        choices=["openai", "anthropic"],
+        default="openai",
+        metavar="PROVIDER",
+        help="LLM provider: openai (default) or anthropic.",
+    )
+    test_gen.add_argument(
+        "--llm-model",
+        default=None,
+        metavar="MODEL",
+        help="LLM model name override.",
+    )
+    test_gen.add_argument(
+        "--llm-api-key",
+        default=None,
+        metavar="KEY",
+        help="LLM API key.",
+    )
+    test_gen.add_argument(
+        "--max-tests",
+        type=int,
+        default=None,
+        metavar="N",
+        help="Maximum number of test cases to output.",
+    )
+
+    # ----------------------------------------------------------------
+    # completions sub-command
+    # ----------------------------------------------------------------
+    completions = subparsers.add_parser(
+        "completions",
+        help="Output shell completion script for bash, zsh, or fish.",
+    )
+    completions.add_argument(
+        "shell",
+        choices=["bash", "zsh", "fish"],
+        help="Shell to generate completions for: bash, zsh, or fish.",
+    )
+
+    # ----------------------------------------------------------------
+    # demo sub-command
+    # ----------------------------------------------------------------
+    demo = subparsers.add_parser(
+        "demo",
+        help=(
+            "Start the NAT server, open the dashboard, and run a curated "
+            "demo with live agent telemetry, risk heatmap, anomaly "
+            "detection, and pre-seeded security findings. Press Ctrl+C to stop."
+        ),
+    )
+    demo.add_argument(
+        "--port",
+        type=int,
+        default=8080,
+        metavar="PORT",
+        help="Port to serve the demo on (default: 8080).",
+    )
+    demo.add_argument(
+        "--no-browser",
+        action="store_true",
+        default=False,
+        help="Skip auto-launching the browser (useful for headless environments).",
+    )
+    demo.add_argument(
+        "--target",
+        default=None,
+        metavar="TARGET",
+        help=(
+            "Demo target to run against. Choices: 'orangehrm' (OrangeHRM live demo), "
+            "'vulnapi' (VulnAPI testbed), or a custom URL (e.g. https://example.com). "
+            "When omitted, the NAT server + dashboard starts with synthetic data (default behavior)."
+        ),
+    )
+    demo.add_argument(
+        "--headed",
+        action="store_true",
+        default=False,
+        help="Run the browser in visible/headed mode (for screen recordings and live demos). Default is headless.",
+    )
+    demo.add_argument(
+        "--output-dir",
+        default="demo_output",
+        metavar="DIR",
+        dest="output_dir",
+        help="Directory to write HTML + JSON reports into (default: demo_output/).",
+    )
+    demo.add_argument(
+        "--json-summary",
+        default="",
+        metavar="PATH",
+        dest="json_summary",
+        help="Optional path to write a JSON summary file.",
+    )
+
+    # ----------------------------------------------------------------
+    # setup sub-command
+    # ----------------------------------------------------------------
+    setup = subparsers.add_parser(
+        "setup",
+        help="Run the interactive NAT setup wizard.",
+    )
+    setup.add_argument(
+        "--non-interactive",
+        action="store_true",
+        default=False,
+        dest="non_interactive",
+        help="Skip all prompts and read configuration from environment variables.",
+    )
+    setup.add_argument(
+        "--demo",
+        action="store_true",
+        default=False,
+        help="Launch `nat demo` after setup completes.",
+    )
+
+    # ----------------------------------------------------------------
+    # upgrade sub-command
+    # ----------------------------------------------------------------
+    upgrade = subparsers.add_parser(
+        "upgrade",
+        help="Check for updates and upgrade nat-engine.",
+    )
+    upgrade.add_argument(
+        "--check",
+        action="store_true",
+        default=False,
+        help="Only check if an update is available; do not install.",
+    )
+    upgrade.add_argument(
+        "--migrate",
+        action="store_true",
+        default=False,
+        help="Run `alembic upgrade head` after upgrading (for self-hosted deployments).",
+    )
+    upgrade.add_argument(
+        "--pre",
+        action="store_true",
+        default=False,
+        help="Allow pre-release versions when checking or installing.",
+    )
+
+    # ----------------------------------------------------------------
+    # uninstall sub-command
+    # ----------------------------------------------------------------
+    uninstall = subparsers.add_parser(
+        "uninstall",
+        help="Remove NAT configuration, data directory, and shell completions.",
+    )
+    uninstall.add_argument(
+        "--keep-config",
+        action="store_true",
+        default=False,
+        dest="keep_config",
+        help="Preserve .natrc files during uninstall.",
+    )
+    uninstall.add_argument(
+        "--yes",
+        "-y",
+        action="store_true",
+        default=False,
+        help="Skip the confirmation prompt.",
+    )
+    uninstall.add_argument(
+        "--purge",
+        action="store_true",
+        default=False,
+        help="Also remove database tables via `alembic downgrade base` and Docker volumes.",
+    )
+
+    # ----------------------------------------------------------------
+    # doctor sub-command
+    # ----------------------------------------------------------------
+    doctor = subparsers.add_parser(
+        "doctor",
+        help="Run pre-flight checks to validate your NAT environment.",
+    )
+    doctor.add_argument(
+        "--json",
+        action="store_true",
+        default=False,
+        dest="json_output",
+        help="Output results as JSON (for CI/automation).",
+    )
+    doctor.add_argument(
+        "--verbose",
+        action="store_true",
+        default=False,
+        help="Show detailed diagnostics for each check.",
+    )
+
+    # ----------------------------------------------------------------
+    # point-and-fire sub-command
+    # ----------------------------------------------------------------
+    paf = subparsers.add_parser(
+        "point-and-fire",
+        help="Autonomous end-to-end test loop: crawl → generate → execute → feedback → repeat.",
+    )
+    paf.add_argument(
+        "url",
+        help="Root URL of the web application to test.",
+    )
+    paf.add_argument(
+        "--strategy",
+        default="all",
+        choices=["all", "high_risk", "new_changed", "belief_targeted"],
+        help="Scenario selection strategy (default: all).",
+    )
+    paf.add_argument(
+        "--max-iterations",
+        type=int,
+        default=5,
+        dest="max_iterations",
+        help="Maximum number of loop iterations (default: 5).",
+    )
+    paf.add_argument(
+        "--max-duration",
+        type=float,
+        default=600.0,
+        dest="max_duration_s",
+        help="Maximum total run time in seconds (default: 600).",
+    )
+    paf.add_argument(
+        "--stability-threshold",
+        type=int,
+        default=2,
+        dest="stability_threshold",
+        help="Stop after N consecutive iterations with no new failures (default: 2).",
+    )
+    paf.add_argument(
+        "--risk-threshold",
+        type=float,
+        default=0.6,
+        dest="risk_threshold",
+        help="Minimum risk_score for high_risk strategy (default: 0.6).",
+    )
+    paf.add_argument(
+        "--max-pages",
+        type=int,
+        default=50,
+        dest="max_pages",
+        help="Maximum pages to crawl per iteration (default: 50).",
+    )
+    paf.add_argument(
+        "--max-depth",
+        type=int,
+        default=5,
+        dest="max_depth",
+        help="Maximum BFS crawl depth (default: 5).",
+    )
+    paf.add_argument(
+        "--no-headless",
+        action="store_true",
+        default=False,
+        dest="no_headless",
+        help="Show browser windows (default: headless).",
+    )
+    paf.add_argument(
+        "--recrawl-every",
+        type=int,
+        default=3,
+        dest="recrawl_every",
+        help="Re-crawl every N iterations (default: 3).",
+    )
+    paf.add_argument(
+        "--use-llm",
+        action="store_true",
+        default=False,
+        dest="use_llm",
+        help="Enable LLM-augmented scenario generation.",
+    )
+    paf.add_argument("--llm-provider", default=None, dest="llm_provider", help="LLM provider name.")
+    paf.add_argument("--llm-model", default=None, dest="llm_model", help="LLM model name.")
+    paf.add_argument("--llm-api-key", default=None, dest="llm_api_key", help="LLM API key.")
+    paf.add_argument(
+        "--output",
+        "-o",
+        default="text",
+        choices=["text", "json"],
+        help="Output format (default: text).",
+    )
+    paf.add_argument(
+        "--schedule",
+        default=None,
+        dest="schedule",
+        metavar="CRON",
+        help=(
+            "Register the run as a recurring scheduled sweep using this cron expression "
+            "(e.g. '0 2 * * *').  Requires the NAT server to be running with a database "
+            "configured.  When supplied, the command registers the schedule and returns "
+            "without executing the run immediately."
+        ),
+    )
+    paf.add_argument(
+        "--schedule-name",
+        default=None,
+        dest="schedule_name",
+        help="Human-readable name for the scheduled sweep (default: auto-generated).",
+    )
+    paf.add_argument(
+        "--tenant-id",
+        default=None,
+        dest="tenant_id",
+        help="Tenant UUID to associate with the scheduled sweep.",
+    )
+
+    # ----------------------------------------------------------------
+    # import sub-command
+    # ----------------------------------------------------------------
+    imp = subparsers.add_parser(
+        "import",
+        help=(
+            "Batch import test artifacts (HAR, Playwright, Cypress, mitmproxy) "
+            "and convert them into scenario seeds."
+        ),
+    )
+    imp.add_argument(
+        "--source",
+        required=True,
+        dest="source",
+        metavar="PATH",
+        help=(
+            "File or directory to import.  When a directory is given, all "
+            "matching files are discovered recursively."
+        ),
+    )
+    imp.add_argument(
+        "--format",
+        default="auto",
+        dest="import_format",
+        metavar="FORMAT",
+        help=(
+            "Artifact format: auto, har, playwright, cypress, traffic, postman, "
+            "openapi, graphql, gherkin, curl (default: auto)."
+        ),
+    )
+    imp.add_argument(
+        "--base-url",
+        default="",
+        dest="base_url",
+        metavar="URL",
+        help="Base URL used to resolve relative paths in imported artifacts.",
+    )
+    imp.add_argument(
+        "--output",
+        "-o",
+        default="text",
+        choices=["text", "json"],
+        help="Output format (default: text).",
+    )
+    imp.add_argument(
+        "--replay-mode",
+        action="store_true",
+        default=False,
+        dest="replay_mode",
+        help="Enable HAR replay mode — preserve request ordering and timing.",
+    )
+    imp.add_argument(
+        "--out-file",
+        default=None,
+        dest="out_file",
+        metavar="FILE",
+        help="Write scenario seeds to this JSON file instead of stdout.",
+    )
+
+    # ----------------------------------------------------------------
+    # worker sub-command group
+    # ----------------------------------------------------------------
+    worker = subparsers.add_parser(
+        "worker",
+        help="Manage NAT worker pools for distributed test execution.",
+    )
+    worker_sub = worker.add_subparsers(dest="worker_command", required=True)
+
+    # nat worker launch
+    worker_launch = worker_sub.add_parser(
+        "launch",
+        help="Launch a local worker pool that consumes jobs from the queue.",
+    )
+    worker_launch.add_argument(
+        "--count",
+        type=int,
+        default=4,
+        metavar="N",
+        help="Number of concurrent workers to launch (default: 4).",
+    )
+    worker_launch.add_argument(
+        "--queue",
+        default="memory",
+        metavar="BACKEND",
+        help=(
+            "Queue backend: 'memory' (default), 'sqlite://<path>', "
+            "or 'redis://<host>:<port>[/<db>]'."
+        ),
+    )
+    worker_launch.add_argument(
+        "--poll-interval",
+        type=float,
+        default=1.0,
+        metavar="SECONDS",
+        help="Seconds to wait between polling for new jobs (default: 1.0).",
+    )
+    worker_launch.add_argument(
+        "--max-attempts",
+        type=int,
+        default=3,
+        metavar="N",
+        help="Maximum retry attempts per job before marking it failed (default: 3).",
+    )
+
+    # nat worker status
+    worker_status = worker_sub.add_parser(
+        "status",
+        help="Show current worker pool and queue status.",
+    )
+    worker_status.add_argument(
+        "--queue",
+        default="memory",
+        metavar="BACKEND",
+        help="Queue backend to query (default: memory).",
+    )
+    worker_status.add_argument(
+        "--output",
+        choices=["text", "json"],
+        default="text",
+        help="Output format (default: text).",
+    )
+
+    # ----------------------------------------------------------------
+    # plan sub-command
+    # ----------------------------------------------------------------
+    plan = subparsers.add_parser(
+        "plan",
+        help=(
+            "Generate an AI-powered test plan from an API spec.  "
+            "Uses the LLM to produce a priority-ranked, risk-assessed plan "
+            "of endpoint groups, attack vectors, and edge cases."
+        ),
+    )
+    plan.add_argument(
+        "--spec",
+        required=True,
+        metavar="PATH",
+        help="Path to an OpenAPI 3.x or Swagger 2.x spec file.",
+    )
+    plan.add_argument(
+        "--base-url",
+        default="http://localhost:8080",
+        metavar="URL",
+        help="Base URL of the target API (for context; default: http://localhost:8080).",
+    )
+    plan.add_argument(
+        "--output",
+        choices=["text", "json"],
+        default="text",
+        help="Output format (default: text).",
+    )
+    plan.add_argument(
+        "--execute",
+        action="store_true",
+        default=False,
+        help="Auto-approve and execute the plan immediately after generation.",
+    )
+    plan.add_argument(
+        "--llm-provider",
+        choices=["openai", "anthropic"],
+        default="openai",
+        metavar="PROVIDER",
+        help="LLM provider: openai (default) or anthropic.",
+    )
+    plan.add_argument(
+        "--llm-model",
+        default=None,
+        metavar="MODEL",
+        help="LLM model name override.",
+    )
+    plan.add_argument(
+        "--llm-api-key",
+        default=None,
+        metavar="KEY",
+        help="LLM API key.",
+    )
+
+    nat_test = subparsers.add_parser(
+        "test",
+        help=(
+            "Generate executable test scenarios from a plain-English description.  "
+            "Uses the LLM to translate natural language into API and browser test scenarios "
+            "that can be reviewed and optionally executed immediately."
+        ),
+    )
+    nat_test.add_argument(
+        "description",
+        metavar="DESCRIPTION",
+        help='Natural-language description of what to test (e.g. "Verify admin cannot access other tenants data").',
+    )
+    nat_test.add_argument(
+        "--base-url",
+        default="",
+        metavar="URL",
+        help="Base URL of the target API or application.",
+    )
+    nat_test.add_argument(
+        "--auth-type",
+        default="none",
+        metavar="AUTH",
+        help="Auth type context hint (e.g. bearer, api-key, cookie; default: none).",
+    )
+    nat_test.add_argument(
+        "--known-endpoints",
+        default="",
+        metavar="ENDPOINTS",
+        help="Comma-separated list of known endpoints in METHOD /path format.",
+    )
+    nat_test.add_argument(
+        "--execute",
+        action="store_true",
+        default=False,
+        help="Generate and immediately execute the scenarios.",
+    )
+    nat_test.add_argument(
+        "--headed",
+        action="store_true",
+        default=False,
+        help="Run browser scenarios in headed mode (not headless).",
+    )
+    nat_test.add_argument(
+        "--output",
+        choices=["text", "json"],
+        default="text",
+        help="Output format (default: text).",
+    )
+    nat_test.add_argument(
+        "--llm-provider",
+        choices=["openai", "anthropic"],
+        default="openai",
+        metavar="PROVIDER",
+        help="LLM provider: openai (default) or anthropic.",
+    )
+    nat_test.add_argument(
+        "--llm-model",
+        default=None,
+        metavar="MODEL",
+        help="LLM model name override.",
+    )
+    nat_test.add_argument(
+        "--llm-api-key",
+        default=None,
+        metavar="KEY",
+        help="LLM API key.",
+    )
+
+    return parser
+
+
+def _build_llm_provider(args: argparse.Namespace) -> Optional[Any]:
+    """Build an :class:`~mannf.product.llm.base.LLMProvider` from *args*, or ``None`` if disabled."""
+    if not getattr(args, "use_llm", False):
+        return None
+    try:
+        from mannf.product.llm.config import LLMConfig
+        from mannf.product.llm.factory import get_provider
+        config = LLMConfig(
+            provider=getattr(args, "llm_provider", "openai") or "openai",
+            model=getattr(args, "llm_model", None) or "",
+            api_key=getattr(args, "llm_api_key", None),
+        )
+        provider = get_provider(config)
+        if not provider.is_available():
+            logger.warning(
+                "LLM provider %r is not available (no API key). "
+                "Proceeding without LLM augmentation.",
+                config.provider,
+            )
+            return None
+        return provider
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("Could not initialise LLM provider: %s", exc)
+        return None
+
+
+def _build_auth(args: argparse.Namespace):
+    """Return the appropriate :class:`~mannf.product.integrations.auth.AuthStrategy` from *args*."""
+    from mannf.product.integrations.auth import ApiKeyAuth, BearerTokenAuth, NoAuth, OAuth2Auth
+
+    if getattr(args, "oauth2_token_url", None) and getattr(args, "oauth2_client_id", None):
+        scopes = None
+        if getattr(args, "oauth2_scopes", None):
+            scopes = [s.strip() for s in args.oauth2_scopes.split(",") if s.strip()]
+        return OAuth2Auth(
+            token_url=args.oauth2_token_url,
+            client_id=args.oauth2_client_id,
+            client_secret=args.oauth2_client_secret or "",
+            scopes=scopes,
+            grant_type=getattr(args, "oauth2_grant_type", "client_credentials"),
+        )
+    if getattr(args, "auth_token", None):
+        return BearerTokenAuth(args.auth_token)
+    if getattr(args, "api_key", None):
+        return ApiKeyAuth(args.api_key, getattr(args, "api_key_header", "X-API-Key"))
+    return NoAuth()
+
+
+def _resolve_weights_dir_arg(args: argparse.Namespace) -> None:
+    """If ``--weights-dir`` is set, auto-populate ``--load-weights`` and ``--save-weights``.
+
+    The latest weight file for the given API (keyed by base URL) is loaded
+    automatically, and a new file is saved after the scan completes.
+    """
+    weights_dir = getattr(args, "weights_dir", None)
+    if not weights_dir:
+        return
+
+    import re
+    safe_filename_prefix = re.sub(r"[^a-zA-Z0-9_-]", "_", getattr(args, "base_url", "api"))
+    latest = _find_latest_weights_file(weights_dir, safe_filename_prefix)
+
+    if latest and not getattr(args, "load_weights", None):
+        args.load_weights = latest
+        logger.info("Auto-loading weights from %s", latest)
+
+    if not getattr(args, "save_weights", None):
+        ts = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+        args.save_weights = os.path.join(weights_dir, f"{safe_filename_prefix}_{ts}.json")
+
+
+def _find_latest_weights_file(directory: str, prefix: str) -> Optional[str]:
+    """Return the most recently modified weight file matching *prefix* in *directory*."""
+    if not os.path.isdir(directory):
+        return None
+    candidates = [
+        os.path.join(directory, f)
+        for f in os.listdir(directory)
+        if f.startswith(prefix) and f.endswith(".json")
+    ]
+    if not candidates:
+        return None
+    return max(candidates, key=os.path.getmtime)
+
+
+def _handle_post_scan_weights(args: argparse.Namespace) -> None:
+    """Save agent weights after a scan if ``--save-weights`` is set.
+
+    Because the CLI scan runs through ``HttpApiSUT`` directly (without
+    instantiating BDI agents), this function saves an empty-agents weight file
+    as a valid placeholder so downstream tools can detect that a scan ran.
+    When the full BDI orchestrator is used the agents dict will be populated.
+    """
+    save_path = getattr(args, "save_weights", None)
+    if not save_path:
+        return
+
+    from mannf.product.weights.store import WeightStore
+
+    try:
+        WeightStore.save(save_path, {})
+        logger.info("Agent weights saved to %s", save_path)
+        print(f"  Agent weights saved to: {save_path}")
+    except OSError as exc:
+        logger.warning("Could not save weights to %s: %s", save_path, exc)
+
+
+# ---------------------------------------------------------------------------
+# Output formatters
+# ---------------------------------------------------------------------------
+
+def _format_html_report(report: dict, suite: "TestSuite", args: argparse.Namespace) -> str:
+    """Render a standalone HTML report for a scan result."""
+    s = report.get("suite", {})
+    spec = report.get("spec") or report.get("endpoint", "")
+    base_url = report.get("base_url", getattr(args, "base_url", ""))
+    total = s.get("total", 0)
+    passed = s.get("passed", 0)
+    failed = s.get("failed", 0)
+    errored = s.get("errored", 0)
+    pass_rate = s.get("pass_rate", 0.0) * 100
+    avg_latency = s.get("avg_execution_time_ms", 0.0)
+    ts = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC")
+
+    # Build rows for individual results
+    rows_html = ""
+    for result in getattr(suite, "results", []):
+        status = "PASS" if result.passed else ("ERROR" if result.error else "FAIL")
+        css_class = "pass" if result.passed else ("error" if result.error else "fail")
+        tc_id = result.test_case_id or ""
+        latency = f"{result.execution_time_ms:.1f}" if result.execution_time_ms is not None else "—"
+        error_msg = str(result.error) if result.error else ""
+        rows_html += (
+            f"<tr class='{css_class}'>"
+            f"<td>{tc_id}</td>"
+            f"<td class='status'>{status}</td>"
+            f"<td>{latency} ms</td>"
+            f"<td>{error_msg}</td>"
+            f"</tr>\n"
+        )
+
+    return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>NAT Scan Report</title>
+<style>
+  body {{ font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; margin: 0; background: #f5f7fa; color: #333; }}
+  .header {{ background: #1a1a2e; color: white; padding: 24px 32px; }}
+  .header h1 {{ margin: 0 0 4px; font-size: 1.6rem; }}
+  .header p {{ margin: 0; opacity: 0.7; font-size: 0.9rem; }}
+  .container {{ max-width: 1100px; margin: 32px auto; padding: 0 24px; }}
+  .summary {{ display: grid; grid-template-columns: repeat(auto-fit, minmax(150px, 1fr)); gap: 16px; margin-bottom: 32px; }}
+  .card {{ background: white; border-radius: 8px; padding: 20px; box-shadow: 0 1px 4px rgba(0,0,0,.08); text-align: center; }}
+  .card .value {{ font-size: 2rem; font-weight: bold; }}
+  .card .label {{ font-size: 0.8rem; color: #888; margin-top: 4px; text-transform: uppercase; }}
+  .pass .value {{ color: #22c55e; }}
+  .fail .value {{ color: #ef4444; }}
+  .error .value {{ color: #f97316; }}
+  .rate .value {{ color: #3b82f6; }}
+  table {{ width: 100%; border-collapse: collapse; background: white; border-radius: 8px; overflow: hidden; box-shadow: 0 1px 4px rgba(0,0,0,.08); }}
+  th {{ background: #f1f5f9; padding: 12px 16px; text-align: left; font-size: 0.85rem; color: #555; border-bottom: 1px solid #e2e8f0; }}
+  td {{ padding: 10px 16px; border-bottom: 1px solid #f1f5f9; font-size: 0.9rem; }}
+  tr:last-child td {{ border-bottom: none; }}
+  tr.pass td.status {{ color: #22c55e; font-weight: bold; }}
+  tr.fail td.status {{ color: #ef4444; font-weight: bold; }}
+  tr.error td.status {{ color: #f97316; font-weight: bold; }}
+  .meta {{ font-size: 0.8rem; color: #888; margin-bottom: 16px; }}
+  h2 {{ font-size: 1.1rem; margin-bottom: 12px; color: #444; }}
+</style>
+</head>
+<body>
+<div class="header">
+  <h1>NAT Scan Report</h1>
+  <p>Generated: {ts}</p>
+</div>
+<div class="container">
+  <div class="meta">
+    <strong>Spec:</strong> {spec} &nbsp;|&nbsp;
+    <strong>Base URL:</strong> {base_url}
+  </div>
+  <div class="summary">
+    <div class="card"><div class="value">{total}</div><div class="label">Total</div></div>
+    <div class="card pass"><div class="value">{passed}</div><div class="label">Passed</div></div>
+    <div class="card fail"><div class="value">{failed}</div><div class="label">Failed</div></div>
+    <div class="card error"><div class="value">{errored}</div><div class="label">Errored</div></div>
+    <div class="card rate"><div class="value">{pass_rate:.1f}%</div><div class="label">Pass Rate</div></div>
+    <div class="card"><div class="value">{avg_latency:.0f}</div><div class="label">Avg Latency (ms)</div></div>
+  </div>
+  <h2>Test Results</h2>
+  <table>
+    <thead><tr><th>Test Case</th><th>Status</th><th>Latency</th><th>Details</th></tr></thead>
+    <tbody>
+{rows_html}    </tbody>
+  </table>
+</div>
+</body>
+</html>"""
+
+
+def _format_junit_report(report: dict, suite: "TestSuite", args: argparse.Namespace) -> str:
+    """Render a JUnit XML report for a scan result.
+
+    Compatible with Jenkins, GitLab CI, and Azure DevOps test result import.
+    """
+    s = report.get("suite", {})
+    suite_name = getattr(suite, "name", report.get("spec", "NAT Scan"))
+    total = s.get("total", 0)
+    failures = s.get("failed", 0)
+    errors = s.get("errored", 0)
+    elapsed = s.get("total_execution_time_ms", 0.0) / 1000.0
+    ts = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S")
+
+    testsuites = ET.Element("testsuites", {
+        "name": "NAT",
+        "tests": str(total),
+        "failures": str(failures),
+        "errors": str(errors),
+        "time": f"{elapsed:.3f}",
+    })
+    testsuite = ET.SubElement(testsuites, "testsuite", {
+        "name": suite_name,
+        "tests": str(total),
+        "failures": str(failures),
+        "errors": str(errors),
+        "time": f"{elapsed:.3f}",
+        "timestamp": ts,
+    })
+
+    for result in getattr(suite, "results", []):
+        tc_id = result.test_case_id or "unknown"
+        tc_time = f"{(result.execution_time_ms or 0.0) / 1000.0:.3f}"
+        tc_elem = ET.SubElement(testsuite, "testcase", {
+            "name": tc_id,
+            "classname": "NAT",
+            "time": tc_time,
+        })
+        if result.error:
+            err_elem = ET.SubElement(tc_elem, "error", {"message": str(result.error)})
+            err_elem.text = str(result.error)
+        elif not result.passed:
+            reason = str(result.error) if result.error else "Test case failed"
+            fail_elem = ET.SubElement(tc_elem, "failure", {"message": reason})
+            fail_elem.text = reason
+
+    ET.indent(testsuites, space="  ")
+    return '<?xml version="1.0" encoding="UTF-8"?>\n' + ET.tostring(testsuites, encoding="unicode")
+
+
+def _format_allure_report(
+    report: dict, suite: "TestSuite", output_dir: str
+) -> list[str]:
+    """Write Allure result JSON files to *output_dir* and return paths written.
+
+    One ``*-result.json`` file is written per test case.  The directory is
+    created if it does not already exist.
+    """
+    from mannf.product.formatters.allure_formatter import write_allure_results
+    return write_allure_results(report, suite, output_dir)
+
+
+def _format_ctrf_report(report: dict, suite: "TestSuite") -> str:
+    """Return a CTRF-schema JSON string for the scan result."""
+    from mannf.product.formatters.ctrf_formatter import build_ctrf_report
+    return build_ctrf_report(report, suite)
+
+
+def _write_output(content: str, output_file: Optional[str]) -> None:
+    """Write *content* to *output_file* or stdout."""
+    if output_file:
+        Path(output_file).parent.mkdir(parents=True, exist_ok=True)
+        with open(output_file, "w", encoding="utf-8") as fh:
+            fh.write(content)
+        print(f"  Output written to: {output_file}", file=sys.stderr)
+    else:
+        print(content)
+
+
+def _auto_output_filename(fmt: str, base: str = "nat-report") -> str:
+    """Return an auto-generated output filename for *fmt*."""
+    ts = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    ext = {"html": "html", "junit": "xml", "ctrf": "json", "allure": "", "pdf": "pdf"}.get(fmt, "txt")
+    if fmt == "allure":
+        # allure writes a directory, not a single file
+        return f"{base}-allure-results-{ts}"
+    return f"{base}-{ts}.{ext}"
+
+
+async def _generate_pdf_from_html(html: str, output_file: str) -> None:
+    """Convert *html* to a PDF file written to *output_file*.
+
+    Uses :class:`~mannf.product.reports.pdf.PDFReportGenerator` which
+    requires Playwright and an installed Chromium browser binary.
+
+    Raises:
+        RuntimeError: If Playwright or its browser binaries are not installed.
+    """
+    from mannf.product.reports.pdf import PDFReportGenerator  # noqa: PLC0415
+
+    generator = PDFReportGenerator()
+    pdf_bytes = await generator.generate(html)
+    Path(output_file).parent.mkdir(parents=True, exist_ok=True)
+    with open(output_file, "wb") as fh:
+        fh.write(pdf_bytes)
+    print(f"  PDF report written to: {output_file}", file=sys.stderr)
+
+
+async def _run_scan(args: argparse.Namespace) -> int:
+    """Execute the *scan* sub-command.  Returns exit code."""
+    from mannf.product.integrations.auth import ApiKeyAuth, BearerTokenAuth, NoAuth
+    from mannf.product.integrations.http_sut import HttpApiSUT
+    from mannf.product.integrations.openapi_parser import OpenApiParser
+    from mannf.core.testing.models import TestSuite
+
+    api_type = getattr(args, "type", "rest")
+
+    if api_type == "graphql":
+        return await _run_graphql_scan(args)
+
+    if api_type == "grpc":
+        return await _run_grpc_scan(args)
+
+    if api_type == "websocket":
+        return await _run_websocket_scan(args)
+
+    # --- Regression replay mode ------------------------------------------
+    replay_file = getattr(args, "replay", None)
+    if replay_file:
+        return await _run_regression_replay(args)
+
+    # --- Weight pre-scan: resolve auto-load path -------------------------
+    _resolve_weights_dir_arg(args)
+
+    # --- Auth -----------------------------------------------------------
+    auth = _build_auth(args)
+
+    # --- Regression recorder --------------------------------------------
+    record_file = getattr(args, "record_regression", None)
+    recorder = None
+    if record_file:
+        from mannf.product.regression.recorder import RegressionRecorder
+        recorder = RegressionRecorder(
+            spec=args.spec,
+            base_url=args.base_url,
+            mask_sensitive_data=getattr(args, "mask_sensitive", False),
+        )
+
+    # --- SUT ------------------------------------------------------------
+    sut = HttpApiSUT(
+        base_url=args.base_url,
+        timeout=args.timeout,
+        auth=auth,
+        latency_sla_ms=args.latency_sla,
+        recorder=recorder,
+    )
+
+    if not args.spec:
+        print("--spec is required for REST scans.", file=sys.stderr)
+        return EXIT_CONFIG_ERROR
+
+    # --- Parse spec ------------------------------------------------------
+    llm_provider = _build_llm_provider(args)
+    spec_format = getattr(args, "format", "openapi")
+    try:
+        if spec_format == "postman":
+            from mannf.product.integrations.postman_parser import PostmanParser
+            parser = PostmanParser(
+                collection_path=args.spec,
+                base_url=args.base_url,
+                registry=sut.registry,
+                max_tests=args.max_tests,
+            )
+            test_cases = parser.parse()
+        else:
+            parser = OpenApiParser(
+                spec_path=args.spec,
+                base_url=args.base_url,
+                registry=sut.registry,
+                max_tests=args.max_tests,
+                llm_provider=llm_provider,
+            )
+            if llm_provider is not None:
+                test_cases = await parser.parse_with_llm()
+            else:
+                test_cases = parser.parse()
+    except (FileNotFoundError, ValueError, OSError) as exc:
+        print(f"Spec parse error: {exc}", file=sys.stderr)
+        return EXIT_SCAN_ERROR
+
+    if not test_cases:
+        print("No test cases generated from spec.", file=sys.stderr)
+        return EXIT_SCAN_ERROR
+
+    # --- Execute test cases directly through the SUT --------------------
+    # The pre-generated TestCase objects from the OpenAPI parser carry
+    # precise HTTP method, headers, body, and expected_status_codes that
+    # must be preserved.  Running them through HttpApiSUT directly (rather
+    # than the adaptive NATOrchestrator BDI pipeline, which generates its own
+    # generic test cases) ensures spec-accurate coverage.
+    suite = TestSuite(name=f"NAT scan: {args.spec}")
+    try:
+        for tc in test_cases:
+            suite.add_case(tc)
+            result = await sut.execute(tc)
+            suite.record_result(result)
+            logger.debug(
+                "  %s %s → %s",
+                tc.inputs.get("method", "GET"),
+                tc.target,
+                "PASS" if result.passed else "FAIL",
+            )
+    except Exception as exc:
+        print(f"Scan error during test execution: {exc}", file=sys.stderr)
+        return EXIT_SCAN_ERROR
+
+    # --- Save regression baseline ----------------------------------------
+    if record_file and recorder is not None:
+        recorder.save(record_file)
+        logger.info("Regression baseline saved to: %s", record_file)
+        if args.output not in ("json", "junit", "html", "allure", "ctrf"):
+            print(f"  Regression baseline saved to: {record_file}")
+
+    # --- Weight persistence (post-scan) ----------------------------------
+    _handle_post_scan_weights(args)
+
+    # --- Build report dict -----------------------------------------------
+    s = suite.summary()
+    llm_cases = [tc for tc in test_cases if tc.metadata.get("generator") == "llm"]
+    report = {
+        "suite": s,
+        "spec": args.spec,
+        "base_url": args.base_url,
+        "llm_cases_generated": len(llm_cases),
+    }
+
+    # --- Output ----------------------------------------------------------
+    output_fmt = getattr(args, "output", "text")
+    output_file = getattr(args, "output_file", None)
+
+    if output_fmt == "json":
+        _write_output(json.dumps(report, indent=2), output_file)
+    elif output_fmt == "html":
+        html_path = output_file or _auto_output_filename("html", "nat-scan-report")
+        _write_output(_format_html_report(report, suite, args), html_path)
+    elif output_fmt == "pdf":
+        pdf_path = output_file or _auto_output_filename("pdf", "nat-scan-report")
+        await _generate_pdf_from_html(_format_html_report(report, suite, args), pdf_path)
+    elif output_fmt == "junit":
+        junit_path = output_file or _auto_output_filename("junit", "nat-scan-results")
+        _write_output(_format_junit_report(report, suite, args), junit_path)
+    elif output_fmt == "allure":
+        allure_dir = output_file or _auto_output_filename("allure", "nat-scan")
+        paths = _format_allure_report(report, suite, allure_dir)
+        print(f"  Allure results written to: {allure_dir} ({len(paths)} file(s))", file=sys.stderr)
+    elif output_fmt == "ctrf":
+        ctrf_path = output_file or _auto_output_filename("ctrf", "nat-scan-report")
+        _write_output(_format_ctrf_report(report, suite), ctrf_path)
+    else:
+        text = (
+            f"\n{'=' * 60}\n"
+            f"  NAT Scan Results: {args.spec}\n"
+            f"  Base URL: {args.base_url}\n"
+            f"{'=' * 60}\n"
+            f"  Total:   {s['total']}\n"
+            f"  Passed:  {s['passed']}\n"
+            f"  Failed:  {s['failed']}\n"
+            f"  Errored: {s['errored']}\n"
+            f"  Pass rate: {s['pass_rate'] * 100:.1f}%\n"
+            f"  Avg latency: {s['avg_execution_time_ms']:.1f} ms\n"
+            f"{'=' * 60}\n"
+        )
+        _write_output(text, output_file)
+
+    return EXIT_OK if suite.failed == 0 and suite.errored == 0 else EXIT_FAILURES
+
+
+async def _run_graphql_scan(args: argparse.Namespace) -> int:
+    """Execute the *scan* sub-command for a GraphQL API."""
+    from mannf.product.integrations.graphql_sut import GraphQLSUT
+    from mannf.core.testing.models import TestSuite
+
+    auth = _build_auth(args)
+
+    # --- Regression recorder --------------------------------------------
+    record_file = getattr(args, "record_regression", None)
+    recorder = None
+    if record_file:
+        from mannf.product.regression.recorder import RegressionRecorder
+        recorder = RegressionRecorder(
+            spec=getattr(args, "spec", None),
+            base_url=args.base_url,
+            mask_sensitive_data=getattr(args, "mask_sensitive", False),
+        )
+
+    sut = GraphQLSUT(
+        endpoint_url=args.base_url,
+        auth=auth,
+        timeout=getattr(args, "timeout", 10.0),
+        recorder=recorder,
+    )
+
+    use_introspection = getattr(args, "graphql_introspection", False)
+    spec = getattr(args, "spec", None)
+
+    if use_introspection or not spec:
+        test_cases = await sut.generate_test_cases()
+    else:
+        # Spec-based test case generation (falls back to introspection for GraphQL)
+        test_cases = await sut.generate_test_cases()
+
+    if not test_cases:
+        print("No test cases generated from GraphQL schema.", file=sys.stderr)
+        return EXIT_SCAN_ERROR
+
+    max_tests = getattr(args, "max_tests", None)
+    if max_tests:
+        test_cases = test_cases[:max_tests]
+
+    suite = TestSuite(name=f"NAT GraphQL scan: {args.base_url}")
+    for tc in test_cases:
+        suite.add_case(tc)
+        result = await sut.run_test(tc)
+        suite.record_result(result)
+        logger.debug(
+            "  GraphQL %s → %s",
+            tc.metadata.get("case_type", "?"),
+            "PASS" if result.passed else "FAIL",
+        )
+
+    # --- Save regression baseline ----------------------------------------
+    if record_file and recorder is not None:
+        recorder.save(record_file)
+        logger.info("Regression baseline saved to: %s", record_file)
+        if args.output not in ("json", "junit", "html", "allure", "ctrf"):
+            print(f"  Regression baseline saved to: {record_file}")
+
+    s = suite.summary()
+    report = {
+        "suite": s,
+        "endpoint": args.base_url,
+        "type": "graphql",
+    }
+
+    output_fmt = getattr(args, "output", "text")
+    output_file = getattr(args, "output_file", None)
+
+    if output_fmt == "json":
+        _write_output(json.dumps(report, indent=2), output_file)
+    elif output_fmt == "html":
+        html_path = output_file or _auto_output_filename("html", "nat-graphql-report")
+        _write_output(_format_html_report(report, suite, args), html_path)
+    elif output_fmt == "pdf":
+        pdf_path = output_file or _auto_output_filename("pdf", "nat-graphql-report")
+        await _generate_pdf_from_html(_format_html_report(report, suite, args), pdf_path)
+    elif output_fmt == "junit":
+        junit_path = output_file or _auto_output_filename("junit", "nat-graphql-results")
+        _write_output(_format_junit_report(report, suite, args), junit_path)
+    elif output_fmt == "allure":
+        allure_dir = output_file or _auto_output_filename("allure", "nat-graphql")
+        paths = _format_allure_report(report, suite, allure_dir)
+        print(f"  Allure results written to: {allure_dir} ({len(paths)} file(s))", file=sys.stderr)
+    elif output_fmt == "ctrf":
+        ctrf_path = output_file or _auto_output_filename("ctrf", "nat-graphql-report")
+        _write_output(_format_ctrf_report(report, suite), ctrf_path)
+    else:
+        text = (
+            f"\n{'=' * 60}\n"
+            f"  NAT GraphQL Scan Results\n"
+            f"  Endpoint: {args.base_url}\n"
+            f"{'=' * 60}\n"
+            f"  Total:   {s['total']}\n"
+            f"  Passed:  {s['passed']}\n"
+            f"  Failed:  {s['failed']}\n"
+            f"  Errored: {s['errored']}\n"
+            f"  Pass rate: {s['pass_rate'] * 100:.1f}%\n"
+            f"  Avg latency: {s['avg_execution_time_ms']:.1f} ms\n"
+            f"{'=' * 60}\n"
+        )
+        _write_output(text, output_file)
+
+    return EXIT_OK if suite.failed == 0 and suite.errored == 0 else EXIT_FAILURES
+
+
+async def _run_grpc_scan(args: argparse.Namespace) -> int:
+    """Execute the *scan* sub-command for a gRPC service."""
+    from mannf.product.integrations.grpc_sut import GrpcSUT
+    from mannf.core.testing.models import TestSuite
+
+    grpc_endpoint = getattr(args, "grpc_endpoint", None) or getattr(args, "base_url", None)
+    proto_path = getattr(args, "proto", None)
+    use_tls = getattr(args, "grpc_use_tls", False)
+
+    if not grpc_endpoint:
+        print(
+            "--grpc-endpoint (or --base-url) is required for gRPC scans.",
+            file=sys.stderr,
+        )
+        return EXIT_CONFIG_ERROR
+
+    sut = GrpcSUT(
+        endpoint=grpc_endpoint,
+        timeout=getattr(args, "timeout", 10.0),
+        use_tls=use_tls,
+    )
+
+    # Parse .proto file with GrpcIngestor if provided
+    test_cases = []
+    if proto_path:
+        from mannf.product.ingestors.grpc_ingestor import GrpcIngestor
+        from mannf.product.ingestors.models import IngestorSource
+
+        ingestor = GrpcIngestor()
+        source = IngestorSource(format="grpc", path=proto_path)
+        result = await ingestor.ingest(source, config={"grpc_endpoint": grpc_endpoint})
+
+        if not result.success:
+            print(f"Proto parse error: {'; '.join(result.errors)}", file=sys.stderr)
+            return EXIT_SCAN_ERROR
+
+        # Convert IngestedEndpoints to TestCase objects
+        from mannf.core.testing.models import TestCase
+
+        for ep in result.endpoints:
+            meta = ep.metadata
+            req_body = ep.request_body or {}
+            rpc_name = meta.get("rpc_name", meta.get("full_method", ep.path))
+            tc = TestCase(
+                target=meta.get("full_method", ep.path),
+                inputs={
+                    "rpc_type": meta.get("rpc_type", "unary"),
+                    "request": req_body.get("example", {}),
+                },
+                expected_behavior=f"gRPC {meta.get('rpc_type', 'unary')} call to {rpc_name}",
+                metadata={
+                    **meta,
+                    "case_type": "happy_path",
+                    "generator": "grpc_ingestor",
+                },
+            )
+            test_cases.append(tc)
+
+        max_tests = getattr(args, "max_tests", None)
+        if max_tests:
+            test_cases = test_cases[:max_tests]
+
+    if not test_cases:
+        print(
+            "No test cases generated. Provide --proto to parse a .proto file.",
+            file=sys.stderr,
+        )
+        return EXIT_SCAN_ERROR
+
+    suite = TestSuite(name=f"NAT gRPC scan: {grpc_endpoint}")
+    for tc in test_cases:
+        suite.add_case(tc)
+        result = await sut.execute(tc)
+        suite.record_result(result)
+        logger.debug(
+            "  gRPC %s → %s",
+            tc.target,
+            "PASS" if result.passed else "FAIL",
+        )
+
+    s = suite.summary()
+    report = {
+        "suite": s,
+        "endpoint": grpc_endpoint,
+        "type": "grpc",
+        "proto": proto_path,
+    }
+
+    output_fmt = getattr(args, "output", "text")
+    output_file = getattr(args, "output_file", None)
+
+    if output_fmt == "json":
+        _write_output(json.dumps(report, indent=2), output_file)
+    elif output_fmt == "html":
+        html_path = output_file or _auto_output_filename("html", "nat-grpc-report")
+        _write_output(_format_html_report(report, suite, args), html_path)
+    elif output_fmt == "pdf":
+        pdf_path = output_file or _auto_output_filename("pdf", "nat-grpc-report")
+        await _generate_pdf_from_html(_format_html_report(report, suite, args), pdf_path)
+    elif output_fmt == "junit":
+        junit_path = output_file or _auto_output_filename("junit", "nat-grpc-results")
+        _write_output(_format_junit_report(report, suite, args), junit_path)
+    elif output_fmt == "allure":
+        allure_dir = output_file or _auto_output_filename("allure", "nat-grpc")
+        paths = _format_allure_report(report, suite, allure_dir)
+        print(f"  Allure results written to: {allure_dir} ({len(paths)} file(s))", file=sys.stderr)
+    elif output_fmt == "ctrf":
+        ctrf_path = output_file or _auto_output_filename("ctrf", "nat-grpc-report")
+        _write_output(_format_ctrf_report(report, suite), ctrf_path)
+    else:
+        text = (
+            f"\n{'=' * 60}\n"
+            f"  NAT gRPC Scan Results\n"
+            f"  Endpoint: {grpc_endpoint}\n"
+            f"  Proto: {proto_path or '(none)'}\n"
+            f"{'=' * 60}\n"
+            f"  Total:   {s['total']}\n"
+            f"  Passed:  {s['passed']}\n"
+            f"  Failed:  {s['failed']}\n"
+            f"  Errored: {s['errored']}\n"
+            f"  Pass rate: {s['pass_rate'] * 100:.1f}%\n"
+            f"  Avg latency: {s['avg_execution_time_ms']:.1f} ms\n"
+            f"{'=' * 60}\n"
+        )
+        _write_output(text, output_file)
+
+    return EXIT_OK if suite.failed == 0 and suite.errored == 0 else EXIT_FAILURES
+
+
+async def _run_websocket_scan(args: argparse.Namespace) -> int:
+    """Execute the *scan* sub-command for a WebSocket API."""
+    from mannf.product.integrations.websocket_sut import WebSocketSUT
+    from mannf.core.testing.models import TestSuite
+
+    ws_endpoint = getattr(args, "ws_endpoint", None) or getattr(args, "base_url", None)
+    asyncapi_path = getattr(args, "asyncapi", None) or getattr(args, "spec", None)
+
+    if not ws_endpoint:
+        print(
+            "--ws-endpoint (or --base-url) is required for WebSocket scans.",
+            file=sys.stderr,
+        )
+        return EXIT_CONFIG_ERROR
+
+    sut = WebSocketSUT(
+        ws_url=ws_endpoint,
+        timeout=getattr(args, "timeout", 10.0),
+    )
+
+    # Parse AsyncAPI spec with WebSocketIngestor if provided
+    test_cases = []
+    if asyncapi_path:
+        from mannf.product.ingestors.websocket_ingestor import WebSocketIngestor
+        from mannf.product.ingestors.models import IngestorSource
+
+        ingestor = WebSocketIngestor()
+        source = IngestorSource(format="websocket", path=asyncapi_path)
+        ingest_result = await ingestor.ingest(
+            source, config={"ws_endpoint": ws_endpoint}
+        )
+
+        if not ingest_result.success:
+            print(
+                f"AsyncAPI parse error: {'; '.join(ingest_result.errors)}",
+                file=sys.stderr,
+            )
+            return EXIT_SCAN_ERROR
+
+        from mannf.core.testing.models import TestCase
+
+        for ep in ingest_result.endpoints:
+            meta = ep.metadata
+            req_body = ep.request_body or {}
+            tc = TestCase(
+                target=meta.get("channel", ep.path),
+                inputs={
+                    "action": "send_receive" if meta.get("operation") == "publish" else "receive_only",
+                    "payload": req_body.get("example", {}),
+                },
+                metadata={
+                    **meta,
+                    "case_type": "happy_path",
+                    "generator": "websocket_ingestor",
+                },
+            )
+            test_cases.append(tc)
+
+        max_tests = getattr(args, "max_tests", None)
+        if max_tests:
+            test_cases = test_cases[:max_tests]
+
+    if not test_cases:
+        print(
+            "No test cases generated. Provide --asyncapi to parse an AsyncAPI spec.",
+            file=sys.stderr,
+        )
+        return EXIT_SCAN_ERROR
+
+    suite = TestSuite(name=f"NAT WebSocket scan: {ws_endpoint}")
+    for tc in test_cases:
+        suite.add_case(tc)
+        result = await sut.execute(tc)
+        suite.record_result(result)
+        logger.debug(
+            "  WS %s → %s",
+            tc.target,
+            "PASS" if result.passed else "FAIL",
+        )
+
+    s = suite.summary()
+    report = {
+        "suite": s,
+        "endpoint": ws_endpoint,
+        "type": "websocket",
+        "asyncapi": asyncapi_path,
+    }
+
+    output_fmt = getattr(args, "output", "text")
+    output_file = getattr(args, "output_file", None)
+
+    if output_fmt == "json":
+        _write_output(json.dumps(report, indent=2), output_file)
+    elif output_fmt == "html":
+        html_path = output_file or _auto_output_filename("html", "nat-ws-report")
+        _write_output(_format_html_report(report, suite, args), html_path)
+    elif output_fmt == "pdf":
+        pdf_path = output_file or _auto_output_filename("pdf", "nat-ws-report")
+        await _generate_pdf_from_html(_format_html_report(report, suite, args), pdf_path)
+    elif output_fmt == "junit":
+        junit_path = output_file or _auto_output_filename("junit", "nat-ws-results")
+        _write_output(_format_junit_report(report, suite, args), junit_path)
+    elif output_fmt == "allure":
+        allure_dir = output_file or _auto_output_filename("allure", "nat-ws")
+        paths = _format_allure_report(report, suite, allure_dir)
+        print(f"  Allure results written to: {allure_dir} ({len(paths)} file(s))", file=sys.stderr)
+    elif output_fmt == "ctrf":
+        ctrf_path = output_file or _auto_output_filename("ctrf", "nat-ws-report")
+        _write_output(_format_ctrf_report(report, suite), ctrf_path)
+    else:
+        text = (
+            f"\n{'=' * 60}\n"
+            f"  NAT WebSocket Scan Results\n"
+            f"  Endpoint: {ws_endpoint}\n"
+            f"  AsyncAPI: {asyncapi_path or '(none)'}\n"
+            f"{'=' * 60}\n"
+            f"  Total:   {s['total']}\n"
+            f"  Passed:  {s['passed']}\n"
+            f"  Failed:  {s['failed']}\n"
+            f"  Errored: {s['errored']}\n"
+            f"  Pass rate: {s['pass_rate'] * 100:.1f}%\n"
+            f"  Avg latency: {s['avg_execution_time_ms']:.1f} ms\n"
+            f"{'=' * 60}\n"
+        )
+        _write_output(text, output_file)
+
+    return EXIT_OK if suite.failed == 0 and suite.errored == 0 else EXIT_FAILURES
+
+
+async def _run_regression_replay(args: argparse.Namespace) -> int:
+    """Execute a regression replay against a previously recorded baseline."""
+    from mannf.product.regression.models import RegressionBaseline
+    from mannf.product.regression.replayer import RegressionReplayer
+    from mannf.product.regression.differ import RegressionDiffer
+
+    baseline_file = args.replay
+    try:
+        baseline = RegressionBaseline.load(baseline_file)
+    except (OSError, ValueError, KeyError) as exc:
+        print(f"Failed to load baseline file {baseline_file!r}: {exc}", file=sys.stderr)
+        return EXIT_SCAN_ERROR
+
+    if not baseline.records:
+        print("Baseline file contains no records.", file=sys.stderr)
+        return EXIT_SCAN_ERROR
+
+    auth = _build_auth(args)
+    mask = getattr(args, "mask_sensitive", False)
+
+    replayer = RegressionReplayer(
+        baseline=baseline,
+        auth=auth,
+        timeout=getattr(args, "timeout", 10.0),
+        mask_sensitive_data=mask,
+    )
+
+    replay_baseline = await replayer.replay()
+
+    differ = RegressionDiffer()
+    diff = differ.diff(baseline, replay_baseline)
+
+    diff_only = getattr(args, "regression_diff_only", False)
+
+    if args.output == "json":
+        diff_dict = diff.to_dict()
+        if diff_only:
+            # Only include entries with actual changes
+            diff_dict["changes"] = [c for c in diff_dict["changes"] if c["changes"]]
+        print(json.dumps(diff_dict, indent=2))
+    else:
+        print(diff.human_readable())
+        if diff_only and not diff.changes:
+            print("  (no differences found)")
+
+    # Exit 1 if there are any regressions
+    return EXIT_FAILURES if diff.changes else EXIT_OK
+
+
+async def _run_security_scan(args: argparse.Namespace) -> int:
+    """Execute the security-scan sub-command."""
+    from mannf.product.integrations.http_sut import HttpApiSUT
+    from mannf.product.integrations.openapi_parser import OpenApiParser
+    from mannf.product.security.scanner import SecurityScanner
+    from mannf.product.security.checks.base import EndpointInfo
+    from mannf.product.security.reporter import SecurityReporter
+
+    api_type = getattr(args, "type", "rest")
+
+    if api_type == "graphql":
+        # For GraphQL, the "endpoint" is the base URL itself
+        endpoints = [
+            EndpointInfo(
+                method="POST",
+                path="",
+                base_url=args.base_url,
+            )
+        ]
+    else:
+        if not getattr(args, "spec", None):
+            print("--spec is required for REST security scans.", file=sys.stderr)
+            return EXIT_CONFIG_ERROR
+
+        sut = HttpApiSUT(base_url=args.base_url)
+        spec_format = getattr(args, "format", "openapi")
+        if spec_format == "postman":
+            from mannf.product.integrations.postman_parser import PostmanParser
+            parser = PostmanParser(
+                collection_path=args.spec,
+                base_url=args.base_url,
+                registry=sut.registry,
+            )
+        else:
+            parser = OpenApiParser(spec_path=args.spec, base_url=args.base_url, registry=sut.registry)
+        test_cases = parser.parse()
+
+        endpoints = []
+        seen: set = set()
+        for tc in test_cases:
+            method = tc.inputs.get("method", "GET").upper()
+            path = tc.target
+            key = f"{method} {path}"
+            if key not in seen:
+                seen.add(key)
+                endpoints.append(EndpointInfo(
+                    method=method,
+                    path=path,
+                    base_url=args.base_url,
+                    parameters=tc.inputs.get("parameters", []),
+                    request_body=tc.inputs.get("body"),
+                ))
+
+        if not endpoints:
+            print("No endpoints discovered from spec.", file=sys.stderr)
+            return EXIT_SCAN_ERROR
+
+    checks = [c.strip() for c in args.checks.split(",")] if args.checks else None
+
+    # Resolve prioritization mode: --prioritization takes precedence over legacy --belief-guided
+    prioritization_mode = getattr(args, "prioritization", "adaptive")
+    belief_guided = prioritization_mode != "off"
+
+    # Collect extra check plugins from --plugins-dir and --plugin flags
+    extra_checks: list = []
+    plugins_dir = getattr(args, "plugins_dir", None)
+    if plugins_dir:
+        from mannf.product.security.plugin_loader import load_plugins_from_directory
+        extra_checks.extend(load_plugins_from_directory(plugins_dir))
+
+    plugin_classes = getattr(args, "plugins", None) or []
+    for fqn in plugin_classes:
+        try:
+            module_name, class_name = fqn.rsplit(".", 1)
+        except ValueError:
+            print(f"Invalid --plugin value '{fqn}': expected 'module.ClassName'.", file=sys.stderr)
+            continue
+        try:
+            mod = importlib.import_module(module_name)
+            cls = getattr(mod, class_name)
+            instance = cls()
+            extra_checks.append(instance)
+        except Exception as exc:  # noqa: BLE001
+            print(
+                f"Failed to load plugin '{fqn}': {exc} "
+                "— ensure the module is installed and the class name is correct.",
+                file=sys.stderr,
+            )
+
+    scanner = SecurityScanner(
+        base_url=args.base_url,
+        enabled_checks=checks,
+        severity_threshold=args.severity_threshold,
+        belief_guided=belief_guided,
+        adaptive_checks=(prioritization_mode == "adaptive"),
+        extra_checks=extra_checks or None,
+    )
+
+    # For 'adaptive' mode, attempt to load belief states from a prior scan if available
+    belief_states = None
+    risk_scorer = None
+    if prioritization_mode == "adaptive":
+        try:
+            from mannf.core.prioritization.risk_scorer import RiskScorer
+            risk_scorer = RiskScorer()
+        except Exception:
+            pass
+
+    report = await scanner.scan(endpoints, belief_states=belief_states, risk_scorer=risk_scorer)
+
+    reporter = SecurityReporter()
+    output_fmt = getattr(args, "output", "text")
+    output_file = getattr(args, "output_file", None)
+
+    if output_fmt == "json":
+        _write_output(reporter.to_json(report), output_file)
+    elif output_fmt == "markdown":
+        _write_output(reporter.to_markdown(report), output_file)
+    else:
+        lines = [
+            f"\n{'=' * 60}",
+            f"  NAT Security Scan Results",
+            f"  Target: {args.base_url}",
+            f"{'=' * 60}",
+        ]
+        total = report.total_endpoints_scanned
+        lines.append(f"  Endpoints scanned: {total}")
+        lines.append(f"  Findings:          {len(report.findings)}")
+        sev_counts = report.summary
+        for sev in ["critical", "high", "medium", "low", "info"]:
+            count = sev_counts.get(sev, 0)
+            if count > 0:
+                lines.append(f"  {_SEVERITY_ICONS.get(sev, ' ')} {sev.capitalize()}: {count}")
+        lines.append(f"{'=' * 60}\n")
+        for finding in report.findings:
+            icon = _SEVERITY_ICONS.get(finding.severity, "•")
+            lines.append(f"{icon} [{finding.check_id}] {finding.title}")
+            lines.append(f"   Endpoint: {finding.endpoint}")
+            lines.append(f"   {finding.description}")
+            lines.append(f"   Fix: {finding.remediation}")
+            lines.append("")
+        _write_output("\n".join(lines), output_file)
+
+    high_severity = [f for f in report.findings if f.severity in ("critical", "high")]
+
+    # ------------------------------------------------------------------
+    # Exporter integration
+    # ------------------------------------------------------------------
+    export_name = getattr(args, "export", None)
+    if export_name:
+        from mannf.product.exporters.loader import (
+            get_exporter_by_name,
+            load_all_exporters,
+        )
+
+        exporters_dir = getattr(args, "exporters_dir", None)
+        exporters = load_all_exporters(exporters_dir=exporters_dir)
+        exporter = get_exporter_by_name(export_name, exporters)
+
+        if exporter is None:
+            print(
+                f"Exporter '{export_name}' not found. "
+                f"Available: {[e.name for e in exporters] or 'none'}",
+                file=sys.stderr,
+            )
+            return EXIT_CONFIG_ERROR
+
+        # Parse --export-config key=value pairs
+        export_config: dict[str, str] = {}
+        for pair in (getattr(args, "export_config", None) or []):
+            if "=" not in pair:
+                print(
+                    f"Invalid --export-config value '{pair}': expected KEY=VALUE.",
+                    file=sys.stderr,
+                )
+                return EXIT_CONFIG_ERROR
+            key, _, value = pair.partition("=")
+            export_config[key.strip()] = value.strip()
+
+        config_errors = exporter.validate_config(export_config)
+        if config_errors:
+            print("Exporter config errors:", file=sys.stderr)
+            for err in config_errors:
+                print(f"  - {err}", file=sys.stderr)
+            return EXIT_CONFIG_ERROR
+
+        min_severity = getattr(args, "export_min_severity", "low")
+        summary = await exporter.export_findings(
+            report.findings, report, export_config, min_severity
+        )
+
+        print(
+            f"\nExport summary ({exporter.display_name}): "
+            f"{summary.succeeded} exported, "
+            f"{summary.failed} failed, "
+            f"{summary.skipped} skipped."
+        )
+        if summary.failed:
+            for result in summary.results:
+                if not result.success:
+                    print(
+                        f"  ✗ [{result.finding.check_id}] {result.finding.title}: {result.error}",
+                        file=sys.stderr,
+                    )
+
+    return EXIT_FAILURES if high_severity else EXIT_OK
+
+
+def _run_weights(args: argparse.Namespace) -> int:
+    """Execute the *weights* sub-command group."""
+    from mannf.product.weights.registry import WeightRegistry
+    from mannf.product.weights.store import WeightStore
+
+    registry = WeightRegistry()
+    sub = args.weights_command
+
+    if sub == "list":
+        snapshots = registry.list()
+        if not snapshots:
+            print("No weight snapshots registered.")
+            return 0
+        print(f"{'NAME':<30} {'SAVED AT':<28} PATH")
+        print("-" * 90)
+        for snap in snapshots:
+            print(f"{snap['name']:<30} {snap['registered_at']:<28} {snap['path']}")
+        return 0
+
+    if sub == "save":
+        output_path = args.output
+        name = args.name if args.name is not None else args.scan_id
+        # weights save is a placeholder for CLI-driven save; the actual agent
+        # weight extraction happens through the server or --save-weights flag.
+        # Here we just register the path if the file already exists.
+        if not os.path.isfile(output_path):
+            print(
+                f"Weight file {output_path!r} not found. "
+                "Use --save-weights during a scan to produce it.",
+                file=sys.stderr,
+            )
+            return 1
+        registry.register(name, output_path, metadata={"scan_id": args.scan_id})
+        print(f"Registered weight snapshot {name!r} → {output_path}")
+        return 0
+
+    if sub == "info":
+        path = args.path
+        # Allow a registered name as well as a raw path
+        if not os.path.isfile(path):
+            try:
+                path = registry.get(path)
+            except KeyError:
+                print(f"No weight file or registered snapshot found for {args.path!r}", file=sys.stderr)
+                return 1
+        try:
+            data = WeightStore.load(path)
+        except (FileNotFoundError, ValueError) as exc:
+            print(f"Failed to read weight file: {exc}", file=sys.stderr)
+            return 1
+
+        print(f"Weight file: {path}")
+        print(f"  Version:  {data['version']}")
+        print(f"  Saved at: {data['saved_at']}")
+        print(f"  Agents:   {len(data['agents'])}")
+        for agent_id, info in data["agents"].items():
+            layers = info["layers"]
+            print(f"    [{agent_id}] role={info['role']}  layers={len(layers)}", end="")
+            if layers:
+                shapes = " → ".join(
+                    f"{l['W'].shape[0]}×{l['W'].shape[1]}" for l in layers
+                )
+                print(f"  shapes={shapes}", end="")
+            print()
+        return 0
+
+    print(f"Unknown weights sub-command: {sub!r}", file=sys.stderr)
+    return 1
+
+
+def _run_export(args: argparse.Namespace) -> int:
+    """Execute the *export* sub-command group."""
+    import json as _json  # noqa: PLC0415
+
+    from mannf.product.exporters import BUILTIN_EXPORTERS, load_all_exporters  # noqa: PLC0415
+
+    sub = args.export_command
+
+    if sub == "list":
+        exporters = load_all_exporters()
+        # Merge built-ins with any discovered extras, deduplicating by name.
+        all_names = {e.name for e in exporters}
+        merged = list(exporters)
+        for builtin in BUILTIN_EXPORTERS:
+            if builtin.name not in all_names:
+                merged.append(builtin)
+                all_names.add(builtin.name)
+        merged.sort(key=lambda e: e.name)
+
+        if not merged:
+            if getattr(args, "json_output", False):
+                print(_json.dumps([]))
+            else:
+                print("No exporter plugins found.")
+            return 0
+
+        if getattr(args, "json_output", False):
+            data = [
+                {"name": e.name, "display_name": e.display_name, "description": e.description}
+                for e in merged
+            ]
+            print(_json.dumps(data, indent=2))
+        else:
+            print(f"Available exporters ({len(merged)} total):")
+            print(f"  {'NAME':<20} {'DISPLAY NAME':<24} DESCRIPTION")
+            print("  " + "-" * 80)
+            for exp in merged:
+                print(f"  {exp.name:<20} {exp.display_name:<24} {exp.description}")
+        return 0
+
+    print(f"Unknown export sub-command: {sub!r}", file=sys.stderr)
+    return 1
+
+
+def _parse_queue_backend(queue_arg: str) -> "Any":
+    """Parse the ``--queue`` CLI argument and return a configured :class:`JobQueue`."""
+    from mannf.product.scheduling.queue import create_job_queue  # noqa: PLC0415
+
+    q = queue_arg.strip()
+    if q == "memory" or not q:
+        return create_job_queue("memory")
+    if q.startswith("sqlite://"):
+        db_path = q[len("sqlite://"):]
+        return create_job_queue("sqlite", db_path=db_path)
+    if q.startswith("redis://"):
+        return create_job_queue("redis", redis_url=q)
+    # Plain path — treat as SQLite
+    return create_job_queue("sqlite", db_path=q)
+
+
+def _run_worker(args: argparse.Namespace) -> int:
+    """Execute the *worker* sub-command group."""
+    sub = args.worker_command
+
+    if sub == "launch":
+        return asyncio.run(_run_worker_launch(args))
+
+    if sub == "status":
+        return asyncio.run(_run_worker_status(args))
+
+    print(f"Unknown worker sub-command: {sub!r}", file=sys.stderr)
+    return 1
+
+
+async def _run_worker_launch(args: argparse.Namespace) -> int:
+    """Launch a local worker pool and block until interrupted."""
+    from mannf.core.agents.worker_pool import WorkerPool  # noqa: PLC0415
+
+    queue = _parse_queue_backend(args.queue)
+    pool = WorkerPool(
+        queue=queue,
+        worker_count=args.count,
+        poll_interval=args.poll_interval,
+        max_attempts=args.max_attempts,
+    )
+    await pool.start()
+
+    print(
+        f"NAT worker pool started — {args.count} worker(s), queue={args.queue!r}"
+    )
+    print("Press Ctrl+C to stop.")
+
+    try:
+        while True:
+            await asyncio.sleep(5)
+            info = await pool.full_status()
+            active = sum(1 for w in info["workers"] if w["status"] == "running")
+            idle = sum(1 for w in info["workers"] if w["status"] == "idle")
+            q = info["queue"]
+            print(
+                f"  workers: {active} active / {idle} idle  |  "
+                f"queue: {q['pending']} pending / {q['running']} running / "
+                f"{q['completed']} completed / {q['failed']} failed"
+            )
+    except (KeyboardInterrupt, asyncio.CancelledError):
+        print("\nShutting down worker pool…")
+        await pool.stop()
+        print("Worker pool stopped.")
+        return 0
+
+
+async def _run_worker_status(args: argparse.Namespace) -> int:
+    """Show worker pool and queue status."""
+    queue = _parse_queue_backend(args.queue)
+    stats = await queue.status()
+
+    if args.output == "json":
+        print(json.dumps(stats.to_dict(), indent=2))
+    else:
+        print("Queue Status")
+        print("------------")
+        print(f"  Pending:   {stats.pending}")
+        print(f"  Running:   {stats.running}")
+        print(f"  Completed: {stats.completed}")
+        print(f"  Failed:    {stats.failed}")
+        print(f"  Retrying:  {stats.retrying}")
+        print(f"  Total:     {stats.total}")
+    return 0
+
+
+def _run_heal(args: argparse.Namespace) -> int:
+    """Execute the *heal* sub-command (schema drift detection + dry-run report)."""
+    from mannf.product.healing.healer import TestHealer
+
+    healer = TestHealer()
+    try:
+        result = healer.heal(args.old_spec, args.new_spec, [])
+    except (FileNotFoundError, ValueError, OSError) as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return EXIT_SCAN_ERROR
+
+    report = result.healing_report
+
+    if args.output == "json":
+        print(json.dumps(report.to_dict(), indent=2))
+    elif args.output == "markdown":
+        print(report.markdown())
+    else:
+        print(report.human_readable())
+
+    if getattr(args, "healing_report", None):
+        report.save(args.healing_report)
+        print(f"\n  Healing report saved to: {args.healing_report}", file=sys.stderr)
+
+    return 1 if report.schema_diff and report.schema_diff.has_changes else 0
+
+
+# ---------------------------------------------------------------------------
+# Shell completions
+# ---------------------------------------------------------------------------
+
+_BASH_COMPLETION = """\
+# bash completion for nat
+# Install: source <(nat completions bash)
+
+_nat_completions() {
+    local cur prev words cword
+    _init_completion || return
+
+    local commands="scan security-scan weights heal test-gen completions demo setup upgrade uninstall doctor"
+    local global_opts="--config --help"
+
+    if [[ ${cword} -eq 1 ]]; then
+        COMPREPLY=( $(compgen -W "${commands} ${global_opts}" -- "${cur}") )
+        return
+    fi
+
+    local cmd="${words[1]}"
+    case "${cmd}" in
+        scan)
+            local opts="--spec --base-url --type --graphql-introspection --auth-token --api-key
+                        --api-key-header --max-tests --executors --timeout --latency-sla
+                        --output -o --output-file --verbose --record-regression --replay
+                        --regression-diff-only --mask-sensitive --save-weights --load-weights
+                        --weights-dir --previous-spec --healing-report --use-llm --llm-provider
+                        --llm-model --llm-api-key --oauth2-token-url --oauth2-client-id
+                        --oauth2-client-secret --oauth2-scopes --oauth2-grant-type"
+            case "${prev}" in
+                --output|-o)
+                    COMPREPLY=( $(compgen -W "text json html junit" -- "${cur}") ) ;;
+                --type)
+                    COMPREPLY=( $(compgen -W "rest graphql" -- "${cur}") ) ;;
+                --spec|--save-weights|--load-weights|--healing-report|--previous-spec|--record-regression|--output-file)
+                    COMPREPLY=( $(compgen -f -- "${cur}") ) ;;
+                --base-url|--oauth2-token-url)
+                    COMPREPLY=() ;;
+                *)
+                    COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") ) ;;
+            esac ;;
+        security-scan)
+            local opts="--spec --base-url --type --checks --severity-threshold --output -o
+                        --output-file --belief-guided --prioritization --verbose --use-llm
+                        --llm-provider --llm-model --llm-api-key --oauth2-token-url
+                        --oauth2-client-id --oauth2-client-secret --oauth2-scopes --oauth2-grant-type"
+            case "${prev}" in
+                --output|-o)
+                    COMPREPLY=( $(compgen -W "text json markdown" -- "${cur}") ) ;;
+                --type)
+                    COMPREPLY=( $(compgen -W "rest graphql" -- "${cur}") ) ;;
+                --severity-threshold)
+                    COMPREPLY=( $(compgen -W "critical high medium low info" -- "${cur}") ) ;;
+                --prioritization)
+                    COMPREPLY=( $(compgen -W "adaptive static off" -- "${cur}") ) ;;
+                --spec|--output-file)
+                    COMPREPLY=( $(compgen -f -- "${cur}") ) ;;
+                *)
+                    COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") ) ;;
+            esac ;;
+        completions)
+            COMPREPLY=( $(compgen -W "bash zsh fish" -- "${cur}") ) ;;
+        setup)
+            COMPREPLY=( $(compgen -W "--non-interactive --demo" -- "${cur}") ) ;;
+        upgrade)
+            COMPREPLY=( $(compgen -W "--check --migrate --pre" -- "${cur}") ) ;;
+        uninstall)
+            COMPREPLY=( $(compgen -W "--keep-config --yes -y --purge" -- "${cur}") ) ;;
+        doctor)
+            COMPREPLY=( $(compgen -W "--json --verbose" -- "${cur}") ) ;;
+        *)
+            COMPREPLY=( $(compgen -W "${commands}" -- "${cur}") ) ;;
+    esac
+}
+
+complete -F _nat_completions nat
+"""
+
+_ZSH_COMPLETION = """\
+#compdef nat
+# zsh completion for nat
+# Install: nat completions zsh > "${fpath[1]}/_nat"
+#   or: source <(nat completions zsh)
+
+_nat() {
+    local -a commands
+    commands=(
+        'scan:Parse an OpenAPI spec and run adaptive tests'
+        'security-scan:Run OWASP API Security Top 10 checks'
+        'weights:Manage saved weight snapshots'
+        'heal:Detect API schema drift'
+        'test-gen:Generate test cases from a spec'
+        'completions:Output shell completion script'
+        'demo:Run a curated interactive demo'
+        'setup:Interactive setup wizard'
+        'upgrade:Check for updates and upgrade NAT'
+        'uninstall:Remove NAT config, data, and completions'
+        'doctor:Run pre-flight environment checks'
+    )
+
+    _arguments -C \\
+        '--config[Path to YAML config file]:config file:_files' \\
+        '(-h --help)'{-h,--help}'[Show help]' \\
+        '1:command:->command' \\
+        '*::args:->args'
+
+    case "${state}" in
+        command)
+            _describe 'nat command' commands ;;
+        args)
+            case "${words[1]}" in
+                scan)
+                    _arguments \\
+                        '--spec[OpenAPI spec file]:spec:_files' \\
+                        '--base-url[Base URL]:url:' \\
+                        '--type[API type]:type:(rest graphql)' \\
+                        '--graphql-introspection[Enable introspection]' \\
+                        '--auth-token[Bearer token]:token:' \\
+                        '--api-key[API key]:key:' \\
+                        '--api-key-header[API key header]:header:' \\
+                        '--max-tests[Max test cases]:N:' \\
+                        '--executors[Executor count]:N:' \\
+                        '--timeout[HTTP timeout seconds]:seconds:' \\
+                        '--latency-sla[Latency SLA ms]:ms:' \\
+                        '(-o --output)'{-o,--output}'[Output format]:format:(text json html junit)' \\
+                        '--output-file[Output file path]:file:_files' \\
+                        '--verbose[Verbose logging]' ;;
+                security-scan)
+                    _arguments \\
+                        '--spec[OpenAPI spec file]:spec:_files' \\
+                        '--base-url[Base URL]:url:' \\
+                        '--type[API type]:type:(rest graphql)' \\
+                        '--checks[Check IDs]:checks:' \\
+                        '--severity-threshold[Min severity]:level:(critical high medium low info)' \\
+                        '(-o --output)'{-o,--output}'[Output format]:format:(text json markdown)' \\
+                        '--output-file[Output file path]:file:_files' \\
+                        '--prioritization[Mode]:mode:(adaptive static off)' \\
+                        '--verbose[Verbose logging]' ;;
+                completions)
+                    _arguments '1:shell:(bash zsh fish)' ;;
+                setup)
+                    _arguments \
+                        '--non-interactive[Skip prompts]' \
+                        '--demo[Launch demo after setup]' ;;
+                upgrade)
+                    _arguments \
+                        '--check[Only check for updates]' \
+                        '--migrate[Run DB migrations after upgrade]' \
+                        '--pre[Allow pre-release versions]' ;;
+                uninstall)
+                    _arguments \
+                        '--keep-config[Preserve .natrc files]' \
+                        '(-y --yes)'{-y,--yes}'[Skip confirmation]' \
+                        '--purge[Remove DB tables and Docker volumes]' ;;
+                doctor)
+                    _arguments \
+                        '--json[Output as JSON]' \
+                        '--verbose[Show detailed diagnostics]' ;;
+            esac ;;
+    esac
+}
+
+_nat "$@"
+"""
+
+_FISH_COMPLETION = """\
+# fish completion for nat
+# Install: nat completions fish > ~/.config/fish/completions/nat.fish
+
+set -l commands scan security-scan weights heal test-gen completions demo setup upgrade uninstall doctor
+
+complete -c nat -f -n "not __fish_seen_subcommand_from $commands" -a scan -d 'Run functional test scan'
+complete -c nat -f -n "not __fish_seen_subcommand_from $commands" -a security-scan -d 'Run OWASP security checks'
+complete -c nat -f -n "not __fish_seen_subcommand_from $commands" -a weights -d 'Manage weight snapshots'
+complete -c nat -f -n "not __fish_seen_subcommand_from $commands" -a heal -d 'Detect schema drift'
+complete -c nat -f -n "not __fish_seen_subcommand_from $commands" -a test-gen -d 'Generate test cases'
+complete -c nat -f -n "not __fish_seen_subcommand_from $commands" -a completions -d 'Shell completion script'
+complete -c nat -f -n "not __fish_seen_subcommand_from $commands" -a demo -d 'Run curated demo'
+complete -c nat -f -n "not __fish_seen_subcommand_from $commands" -a setup -d 'Interactive setup wizard'
+complete -c nat -f -n "not __fish_seen_subcommand_from $commands" -a upgrade -d 'Check for updates and upgrade'
+complete -c nat -f -n "not __fish_seen_subcommand_from $commands" -a uninstall -d 'Remove NAT config and data'
+complete -c nat -f -n "not __fish_seen_subcommand_from $commands" -a doctor -d 'Pre-flight environment checks'
+
+# Global
+complete -c nat -l config -d 'YAML config file path' -r
+
+# scan
+complete -c nat -n "__fish_seen_subcommand_from scan" -l spec -d 'OpenAPI spec file' -r -F
+complete -c nat -n "__fish_seen_subcommand_from scan" -l base-url -d 'Base URL' -r
+complete -c nat -n "__fish_seen_subcommand_from scan" -l type -d 'API type' -r -a 'rest graphql'
+complete -c nat -n "__fish_seen_subcommand_from scan" -l graphql-introspection -d 'Enable introspection'
+complete -c nat -n "__fish_seen_subcommand_from scan" -l auth-token -d 'Bearer token' -r
+complete -c nat -n "__fish_seen_subcommand_from scan" -l api-key -d 'API key' -r
+complete -c nat -n "__fish_seen_subcommand_from scan" -l max-tests -d 'Max test cases' -r
+complete -c nat -n "__fish_seen_subcommand_from scan" -l output -s o -d 'Output format' -r -a 'text json html junit'
+complete -c nat -n "__fish_seen_subcommand_from scan" -l output-file -d 'Output file path' -r -F
+complete -c nat -n "__fish_seen_subcommand_from scan" -l verbose -d 'Verbose logging'
+
+# security-scan
+complete -c nat -n "__fish_seen_subcommand_from security-scan" -l spec -d 'OpenAPI spec file' -r -F
+complete -c nat -n "__fish_seen_subcommand_from security-scan" -l base-url -d 'Base URL' -r
+complete -c nat -n "__fish_seen_subcommand_from security-scan" -l type -d 'API type' -r -a 'rest graphql'
+complete -c nat -n "__fish_seen_subcommand_from security-scan" -l checks -d 'Check IDs' -r
+complete -c nat -n "__fish_seen_subcommand_from security-scan" -l severity-threshold -d 'Min severity' -r -a 'critical high medium low info'
+complete -c nat -n "__fish_seen_subcommand_from security-scan" -l output -s o -d 'Output format' -r -a 'text json markdown'
+complete -c nat -n "__fish_seen_subcommand_from security-scan" -l output-file -d 'Output file path' -r -F
+complete -c nat -n "__fish_seen_subcommand_from security-scan" -l prioritization -d 'Prioritization mode' -r -a 'adaptive static off'
+complete -c nat -n "__fish_seen_subcommand_from security-scan" -l verbose -d 'Verbose logging'
+
+# completions
+complete -c nat -n "__fish_seen_subcommand_from completions" -a 'bash zsh fish' -d 'Shell type'
+
+# setup
+complete -c nat -n "__fish_seen_subcommand_from setup" -l non-interactive -d 'Skip prompts'
+complete -c nat -n "__fish_seen_subcommand_from setup" -l demo -d 'Launch demo after setup'
+
+# upgrade
+complete -c nat -n "__fish_seen_subcommand_from upgrade" -l check -d 'Only check for updates'
+complete -c nat -n "__fish_seen_subcommand_from upgrade" -l migrate -d 'Run DB migrations'
+complete -c nat -n "__fish_seen_subcommand_from upgrade" -l pre -d 'Allow pre-release'
+
+# uninstall
+complete -c nat -n "__fish_seen_subcommand_from uninstall" -l keep-config -d 'Preserve .natrc'
+complete -c nat -n "__fish_seen_subcommand_from uninstall" -l yes -s y -d 'Skip confirmation'
+complete -c nat -n "__fish_seen_subcommand_from uninstall" -l purge -d 'Remove DB and Docker volumes'
+
+# doctor
+complete -c nat -n "__fish_seen_subcommand_from doctor" -l json -d 'Output as JSON'
+complete -c nat -n "__fish_seen_subcommand_from doctor" -l verbose -d 'Show detailed diagnostics'
+"""
+
+
+def _run_completions(args: argparse.Namespace) -> int:
+    """Output a shell completion script for the requested shell."""
+    shell = args.shell
+    scripts = {
+        "bash": _BASH_COMPLETION,
+        "zsh": _ZSH_COMPLETION,
+        "fish": _FISH_COMPLETION,
+    }
+    print(scripts[shell], end="")
+    return EXIT_OK
+
+
+async def _run_test_gen(args: argparse.Namespace) -> int:
+    """Execute the *test-gen* sub-command.  Generates and prints test cases."""
+    from mannf.product.integrations.openapi_parser import OpenApiParser
+
+    llm_provider = _build_llm_provider(args)
+
+    parser = OpenApiParser(
+        spec_path=args.spec,
+        base_url=args.base_url,
+        max_tests=getattr(args, "max_tests", None),
+        llm_provider=llm_provider,
+    )
+
+    if llm_provider is not None:
+        test_cases = await parser.parse_with_llm()
+    else:
+        test_cases = parser.parse()
+
+    if not test_cases:
+        print("No test cases generated.", file=sys.stderr)
+        return 1
+
+    llm_count = sum(1 for tc in test_cases if tc.metadata.get("generator") == "llm")
+
+    if args.output == "json":
+        output = [
+            {
+                "id": tc.id,
+                "target": tc.target,
+                "inputs": tc.inputs,
+                "expected_behavior": tc.expected_behavior,
+                "priority": tc.priority,
+                "metadata": tc.metadata,
+            }
+            for tc in test_cases
+        ]
+        print(json.dumps(output, indent=2))
+    else:
+        print(f"\n{'=' * 60}")
+        print(f"  NAT Test Generation: {args.spec}")
+        print(f"{'=' * 60}")
+        print(f"  Total cases: {len(test_cases)}")
+        if llm_count:
+            print(f"  LLM-generated: {llm_count} 🤖")
+        print(f"{'=' * 60}")
+        for tc in test_cases:
+            llm_tag = " 🤖" if tc.metadata.get("generator") == "llm" else ""
+            print(f"  [{tc.metadata.get('method', '?')}] {tc.target}{llm_tag}")
+            print(f"    {tc.expected_behavior}")
+        print()
+
+    return 0
+
+
+async def _run_plan(args: argparse.Namespace) -> int:
+    """Execute the *plan* sub-command.  Generates and prints an LLM test plan."""
+    import yaml  # noqa: PLC0415
+
+    from mannf.product.llm.config import LLMConfig  # noqa: PLC0415
+    from mannf.product.llm.factory import get_provider  # noqa: PLC0415
+
+    spec_path = args.spec
+    if not os.path.isfile(spec_path):
+        print(f"error: spec file not found: {spec_path!r}", file=sys.stderr)
+        return EXIT_SCAN_ERROR
+
+    # Parse spec → compact summary
+    try:
+        with open(spec_path, encoding="utf-8") as fh:
+            raw = fh.read()
+        if spec_path.endswith(".json"):
+            spec = json.loads(raw)
+        else:
+            spec = yaml.safe_load(raw) or {}
+    except Exception as exc:  # noqa: BLE001
+        print(f"error: could not parse spec: {exc}", file=sys.stderr)
+        return EXIT_SCAN_ERROR
+
+    if not isinstance(spec, dict):
+        print("error: spec must be a YAML/JSON object", file=sys.stderr)
+        return EXIT_SCAN_ERROR
+
+    endpoints = []
+    for path, path_item in spec.get("paths", {}).items():
+        if not isinstance(path_item, dict):
+            continue
+        for method, operation in path_item.items():
+            if method.lower() not in ("get", "post", "put", "patch", "delete", "head", "options"):
+                continue
+            if not isinstance(operation, dict):
+                continue
+            endpoints.append({
+                "method": method.upper(),
+                "path": path,
+                "summary": operation.get("summary") or operation.get("operationId") or "",
+                "description": operation.get("description", ""),
+                "tags": operation.get("tags", []),
+                "requires_auth": bool(operation.get("security")),
+            })
+
+    info = spec.get("info", {})
+    auth_schemes = list(spec.get("components", {}).get("securitySchemes", {}).keys())
+    api_summary = {
+        "spec_source": os.path.basename(spec_path),
+        "base_url": args.base_url,
+        "title": info.get("title", "Unknown API"),
+        "version": info.get("version", ""),
+        "auth_schemes": auth_schemes,
+        "total_endpoints": len(endpoints),
+        "endpoints": endpoints,
+    }
+
+    # Build LLM provider
+    try:
+        config = LLMConfig(
+            provider=getattr(args, "llm_provider", "openai") or "openai",
+            model=getattr(args, "llm_model", None) or "",
+            api_key=getattr(args, "llm_api_key", None),
+        )
+        provider = get_provider(config)
+    except Exception as exc:  # noqa: BLE001
+        print(f"error: could not initialise LLM provider: {exc}", file=sys.stderr)
+        return EXIT_CONFIG_ERROR
+
+    if not provider.is_available():
+        print(
+            "error: LLM provider is not available — set OPENAI_API_KEY or ANTHROPIC_API_KEY, "
+            "or pass --llm-api-key.",
+            file=sys.stderr,
+        )
+        return EXIT_CONFIG_ERROR
+
+    print(f"\n  🧠  Generating test plan for {api_summary['title']} …\n")
+
+    test_plan = await provider.generate_test_plan(api_summary)
+
+    if test_plan is None:
+        print("error: LLM did not return a valid test plan.", file=sys.stderr)
+        return EXIT_SCAN_ERROR
+
+    output_format = getattr(args, "output", "text")
+
+    if output_format == "json":
+        print(json.dumps(test_plan.model_dump(), indent=2))
+        return EXIT_OK
+
+    # Text output
+    _PRIORITY_ICONS = {"critical": "🔴", "high": "🟠", "medium": "🟡", "low": "🔵"}
+    print(f"{'=' * 64}")
+    print(f"  NAT Test Plan — {api_summary['title']} {api_summary.get('version', '')}")
+    print(f"  Spec: {os.path.basename(spec_path)}  |  Endpoints: {len(endpoints)}")
+    if test_plan.estimated_coverage is not None:
+        print(f"  Estimated coverage: {test_plan.estimated_coverage * 100:.0f}%")
+    print(f"{'=' * 64}")
+    for group in test_plan.endpoint_groups:
+        icon = _PRIORITY_ICONS.get(group.priority.value if hasattr(group.priority, 'value') else group.priority, "⚪")
+        print(f"\n  {icon}  {group.name}  [{group.priority if isinstance(group.priority, str) else group.priority.value}]")
+        if group.risk_assessment:
+            print(f"     Risk: {group.risk_assessment}")
+        for ep in group.endpoints:
+            print(f"       • {ep}")
+        if group.suggested_strategies:
+            strats = ", ".join(group.suggested_strategies)
+            print(f"     Strategies: {strats}")
+        if group.edge_cases:
+            for ec in group.edge_cases:
+                print(f"     ⚠ {ec}")
+    print(f"\n{'=' * 64}\n")
+
+    if getattr(args, "execute", False):
+        print("  ▶  Auto-execute requested — plan approved and executed locally.")
+        print(f"     Groups scheduled: {len(test_plan.endpoint_groups)}")
+        print()
+
+    return EXIT_OK
+
+
+async def _run_nl_test(args: argparse.Namespace) -> int:
+    """Execute the *test* sub-command.
+
+    Generates executable test scenarios from a plain-English description using
+    the LLM, prints them for review, and optionally executes them immediately.
+    """
+    from mannf.product.llm.config import LLMConfig  # noqa: PLC0415
+    from mannf.product.llm.factory import get_provider  # noqa: PLC0415
+
+    description = args.description
+    base_url = getattr(args, "base_url", "")
+    auth_type = getattr(args, "auth_type", "none")
+    known_endpoints_raw = getattr(args, "known_endpoints", "")
+    known_endpoints = [e.strip() for e in known_endpoints_raw.split(",") if e.strip()]
+
+    context = {
+        "base_url": base_url,
+        "auth_type": auth_type,
+        "known_endpoints": known_endpoints,
+    }
+
+    # Build LLM provider
+    try:
+        config = LLMConfig(
+            provider=getattr(args, "llm_provider", "openai") or "openai",
+            model=getattr(args, "llm_model", None) or "",
+            api_key=getattr(args, "llm_api_key", None),
+        )
+        provider = get_provider(config)
+    except Exception as exc:  # noqa: BLE001
+        print(f"error: could not initialise LLM provider: {exc}", file=sys.stderr)
+        return EXIT_CONFIG_ERROR
+
+    if not provider.is_available():
+        print(
+            "error: LLM provider is not available — set OPENAI_API_KEY or ANTHROPIC_API_KEY, "
+            "or pass --llm-api-key.",
+            file=sys.stderr,
+        )
+        return EXIT_CONFIG_ERROR
+
+    print(f"\n  🧪  Generating test scenarios for: {description!r} …\n")
+
+    scenarios = await provider.generate_from_natural_language(description, context)
+
+    if not scenarios:
+        print("error: LLM did not return any test scenarios.", file=sys.stderr)
+        return EXIT_SCAN_ERROR
+
+    output_format = getattr(args, "output", "text")
+
+    if output_format == "json":
+        print(json.dumps(scenarios, indent=2))
+        return EXIT_OK
+
+    # Text output
+    _TYPE_ICONS = {"api": "🌐", "browser": "🖥️"}
+    _PRIORITY_ICONS = {"critical": "🔴", "high": "🟠", "medium": "🟡", "low": "🔵"}
+    print(f"{'=' * 64}")
+    print(f"  NAT Generated Test Scenarios")
+    print(f"  Description: {description}")
+    if base_url:
+        print(f"  Base URL: {base_url}")
+    print(f"  Scenarios: {len(scenarios)}")
+    print(f"{'=' * 64}")
+    for i, scenario in enumerate(scenarios, 1):
+        s_type = scenario.get("type", "api")
+        priority = scenario.get("priority", "medium")
+        type_icon = _TYPE_ICONS.get(s_type, "🔷")
+        priority_icon = _PRIORITY_ICONS.get(priority, "⚪")
+        print(f"\n  {type_icon}  [{i}] {scenario.get('name', 'Unnamed')}  {priority_icon} [{priority}]")
+        if scenario.get("description"):
+            print(f"     {scenario['description']}")
+        if s_type == "api":
+            method = scenario.get("method", "GET")
+            path = scenario.get("path", "/")
+            print(f"     Endpoint: {method} {path}")
+            if scenario.get("body"):
+                print(f"     Body: {json.dumps(scenario['body'])}")
+        elif s_type == "browser":
+            steps = scenario.get("steps", [])
+            for step in steps:
+                action = step.get("action", "")
+                selector = step.get("selector", "")
+                value = step.get("value", "")
+                if value:
+                    print(f"     • {action}({selector!r}, {value!r})")
+                else:
+                    print(f"     • {action}({selector!r})")
+        if scenario.get("assertions"):
+            for assertion in scenario["assertions"]:
+                print(f"     ✓ {assertion}")
+    print(f"\n{'=' * 64}\n")
+
+    if getattr(args, "execute", False):
+        print("  ▶  --execute flag detected — running scenarios now …\n")
+        _execute_nl_scenarios(scenarios, base_url, getattr(args, "headed", False))
+
+    return EXIT_OK
+
+
+def _execute_nl_scenarios(
+    scenarios: list,
+    base_url: str,
+    headed: bool,
+) -> None:
+    """Execute generated NL test scenarios locally.
+
+    API scenarios are sent as HTTP requests; browser scenarios are logged
+    for execution by the functional orchestrator (full browser runner not
+    invoked inline to avoid heavyweight dependencies from the CLI path).
+    """
+    import urllib.request  # noqa: PLC0415
+
+    api_scenarios = [s for s in scenarios if s.get("type") == "api"]
+    browser_scenarios = [s for s in scenarios if s.get("type") == "browser"]
+
+    for scenario in api_scenarios:
+        method = scenario.get("method", "GET").upper()
+        path = scenario.get("path", "/")
+        url = f"{base_url.rstrip('/')}{path}"
+        body_data = scenario.get("body")
+        print(f"  🌐  {method} {url}", end=" … ")
+        try:
+            body_bytes = json.dumps(body_data).encode() if body_data else None
+            headers = {"Content-Type": "application/json"} if body_bytes else {}
+            headers.update(scenario.get("headers") or {})
+            req = urllib.request.Request(url, data=body_bytes, headers=headers, method=method)
+            with urllib.request.urlopen(req, timeout=10) as resp:  # noqa: S310
+                status = resp.getcode()
+            print(f"HTTP {status}")
+        except Exception as exc:  # noqa: BLE001
+            print(f"error: {exc}")
+
+    if browser_scenarios:
+        mode = "headed" if headed else "headless"
+        print(f"\n  🖥️   {len(browser_scenarios)} browser scenario(s) queued for {mode} execution.")
+        print("     Use `nat scan --base-url <url>` or the dashboard to run browser scenarios.")
+
+
+def _run_demo(args: argparse.Namespace) -> int:
+    """Execute the ``demo`` sub-command.
+
+    When ``--target`` is provided, delegates to the appropriate demo runner:
+
+    * ``orangehrm`` — runs the OrangeHRM live demo via
+      :func:`scripts.demo_orangehrm.run_orangehrm_demo`.
+    * ``vulnapi`` — starts the VulnAPI testbed (if not already running) and
+      runs a security scan against it.
+    * Any URL (starts with ``http://`` or ``https://``) — runs the autonomous
+      browser pipeline via :class:`~mannf.core.functional_orchestrator.FunctionalTestOrchestrator`.
+
+    When ``--target`` is **not** provided, the original behavior is preserved:
+    starts the NAT FastAPI server in-process, waits for it to be healthy,
+    opens the browser, runs the curated demo scan, then blocks until the user
+    presses Ctrl+C.
+    """
+    import threading
+    import time
+    import webbrowser
+
+    import httpx
+    import uvicorn
+
+    from mannf.product.server import app
+
+    port: int = getattr(args, "port", 8080)
+    no_browser: bool = getattr(args, "no_browser", False)
+    target: str | None = getattr(args, "target", None)
+    headed: bool = getattr(args, "headed", False)
+    output_dir: str = getattr(args, "output_dir", "demo_output")
+    json_summary: str = getattr(args, "json_summary", "")
+
+    # ------------------------------------------------------------------
+    # Route to the appropriate demo runner based on --target
+    # ------------------------------------------------------------------
+
+    if target is not None:
+        return _run_demo_target(
+            target=target,
+            headed=headed,
+            output_dir=output_dir,
+            json_summary=json_summary,
+        )
+
+    dashboard_url = f"http://localhost:{port}/dashboard"
+
+    print(f"\n  🚀  NAT Demo Mode — starting server on port {port} …\n")
+
+    # ------------------------------------------------------------------
+    # Run the server as a co-task inside the demo event loop so that
+    # WebSocket telemetry broadcasts are delivered to browser clients.
+    # ------------------------------------------------------------------
+
+    async def _demo_main() -> None:
+        from mannf.product.demo import run_demo_scan
+
+        config = uvicorn.Config(
+            app,
+            host="0.0.0.0",
+            port=port,
+            log_level="warning",
+        )
+        server = uvicorn.Server(config)
+
+        # Start the uvicorn server as a background task
+        server_task = asyncio.create_task(server.serve())
+
+        # Wait until the server is accepting requests
+        _healthy = False
+        for _ in range(30):
+            await asyncio.sleep(0.5)
+            try:
+                async with httpx.AsyncClient() as client:
+                    resp = await client.get(
+                        f"http://localhost:{port}/api/v1/health",
+                        timeout=2.0,
+                    )
+                if resp.status_code == 200:
+                    _healthy = True
+                    break
+            except Exception:  # noqa: BLE001
+                pass
+
+        if not _healthy:
+            print(
+                f"  ⚠️  Server did not become healthy in time. "
+                f"Check that port {port} is not already in use.",
+                file=sys.stderr,
+            )
+            server.should_exit = True
+            await server_task
+            return
+
+        print(f"  ✅  Server ready at http://localhost:{port}")
+        print(f"  📊  Dashboard: {dashboard_url}")
+        print("\n  Running demo scan … (press Ctrl+C to stop)\n")
+
+        if not no_browser:
+            # Open browser in a thread to avoid blocking the event loop
+            threading.Thread(
+                target=lambda: (time.sleep(0.5), webbrowser.open(dashboard_url)),
+                daemon=True,
+            ).start()
+
+        # Run the demo scan (populates dashboard with live data)
+        try:
+            await run_demo_scan(port=port)
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("Demo scan error: %s", exc)
+
+        print("\n  ✅  Demo data loaded — dashboard is ready!")
+        print(f"  🌐  Open: {dashboard_url}")
+        print("\n  Press Ctrl+C to stop the server.\n")
+
+        # Block until Ctrl+C
+        try:
+            await asyncio.Event().wait()
+        except asyncio.CancelledError:
+            pass
+        finally:
+            server.should_exit = True
+            await server_task
+
+    try:
+        asyncio.run(_demo_main())
+    except KeyboardInterrupt:
+        print("\n\n  👋  Demo stopped. Goodbye!\n")
+
+    return EXIT_OK
+
+
+def _run_demo_target(
+    target: str,
+    headed: bool,
+    output_dir: str,
+    json_summary: str,
+) -> int:
+    """Route ``nat demo --target <target>`` to the correct demo runner.
+
+    Parameters
+    ----------
+    target:
+        ``"orangehrm"`` — OrangeHRM live demo.
+        ``"vulnapi"`` — VulnAPI testbed demo.
+        A URL string (starts with ``http://`` or ``https://``) — autonomous
+        browser pipeline against that URL.
+    headed:
+        When ``True``, open a visible browser window.
+    output_dir:
+        Directory for HTML + JSON reports.
+    json_summary:
+        Optional path for a JSON summary file.
+    """
+    headless = not headed
+
+    if target == "orangehrm":
+        return _run_demo_orangehrm(
+            headless=headless,
+            output_dir=output_dir,
+            json_summary=json_summary,
+        )
+
+    if target == "vulnapi":
+        return _run_demo_vulnapi(
+            headless=headless,
+            output_dir=output_dir,
+            json_summary=json_summary,
+        )
+
+    if target.startswith("http://") or target.startswith("https://"):
+        return _run_demo_url(
+            url=target,
+            headless=headless,
+            output_dir=output_dir,
+            json_summary=json_summary,
+        )
+
+    print(
+        f"  ❌  Unknown --target value: {target!r}\n"
+        "      Valid choices: 'orangehrm', 'vulnapi', or a URL starting with http:// or https://",
+        file=sys.stderr,
+    )
+    return EXIT_FAILURES
+
+
+def _run_demo_orangehrm(
+    headless: bool,
+    output_dir: str,
+    json_summary: str,
+) -> int:
+    """Run the OrangeHRM live demo via :func:`scripts.demo_orangehrm.run_orangehrm_demo`."""
+    import json as _json
+
+    try:
+        import pathlib as _pathlib
+        import sys as _sys
+
+        # Make the scripts/ directory importable so that demo_orangehrm can be
+        # imported as a module regardless of the current working directory.
+        _scripts_dir = str(_pathlib.Path(__file__).parents[3] / "scripts")
+        if _scripts_dir not in _sys.path:
+            _sys.path.insert(0, _scripts_dir)
+
+        from demo_orangehrm import run_orangehrm_demo  # type: ignore[import]
+    except ImportError as exc:
+        print(
+            f"  ❌  Could not import the OrangeHRM demo runner: {exc}\n"
+            "      Make sure 'mannf[browser]' is installed and you are running from "
+            "the repository root.",
+            file=sys.stderr,
+        )
+        return EXIT_FAILURES
+
+    try:
+        report = asyncio.run(
+            run_orangehrm_demo(
+                headless=headless,
+                output_dir=output_dir,
+            )
+        )
+    except KeyboardInterrupt:
+        print("\nDemo interrupted.", file=sys.stderr)
+        return 130
+    except Exception as exc:  # noqa: BLE001
+        logger.error("OrangeHRM demo failed: %s", exc)
+        return EXIT_FAILURES
+
+    if json_summary:
+        try:
+            import pathlib
+
+            pathlib.Path(json_summary).parent.mkdir(parents=True, exist_ok=True)
+            pathlib.Path(json_summary).write_text(_json.dumps(report, indent=2), encoding="utf-8")
+            print(f"  📄  JSON summary written to: {json_summary}")
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("Could not write JSON summary to %s: %s", json_summary, exc)
+
+    failed = report.get("failed", 0)
+    return EXIT_OK if failed == 0 else EXIT_FAILURES
+
+
+def _run_demo_vulnapi(
+    headless: bool,
+    output_dir: str,
+    json_summary: str,
+) -> int:
+    """Start the VulnAPI testbed (if needed) and run a security scan against it."""
+    import json as _json
+    import socket
+    import subprocess
+    import time
+
+    vulnapi_port = 9181
+    vulnapi_url = f"http://localhost:{vulnapi_port}"
+
+    # Check if the testbed is already running
+    _already_running = False
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as _sock:
+        _already_running = _sock.connect_ex(("localhost", vulnapi_port)) == 0
+
+    _server_proc = None
+    if not _already_running:
+        print(f"  🚀  Starting VulnAPI testbed on port {vulnapi_port} …")
+        try:
+            _server_proc = subprocess.Popen(  # noqa: S603
+                [sys.executable, "-m", "uvicorn", "testbed.app:app", f"--port={vulnapi_port}", "--log-level=warning"],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+            # Wait for the testbed to become healthy
+            for _ in range(20):
+                time.sleep(0.5)
+                with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as _s:
+                    if _s.connect_ex(("localhost", vulnapi_port)) == 0:
+                        break
+            else:
+                print("  ⚠️  VulnAPI testbed did not start in time.", file=sys.stderr)
+                if _server_proc:
+                    _server_proc.terminate()
+                return EXIT_FAILURES
+            print(f"  ✅  VulnAPI testbed ready at {vulnapi_url}")
+        except Exception as exc:  # noqa: BLE001
+            logger.error("Failed to start VulnAPI testbed: %s", exc)
+            return EXIT_FAILURES
+    else:
+        print(f"  ✅  VulnAPI testbed already running at {vulnapi_url}")
+
+    try:
+        return _run_demo_url(
+            url=vulnapi_url,
+            headless=headless,
+            output_dir=output_dir,
+            json_summary=json_summary,
+        )
+    finally:
+        if _server_proc is not None:
+            _server_proc.terminate()
+            print("  🛑  VulnAPI testbed stopped.")
+
+
+def _run_demo_url(
+    url: str,
+    headless: bool,
+    output_dir: str,
+    json_summary: str,
+) -> int:
+    """Run the autonomous browser pipeline against *url*."""
+    import json as _json
+
+    from mannf.core.functional_orchestrator import FunctionalTestOrchestrator
+
+    print(f"\n  🚀  NAT Demo Mode — autonomous browser pipeline")
+    print(f"  🎯  Target: {url}")
+    print(f"  🖥️   Browser: {'headed' if not headless else 'headless'}\n")
+
+    tasks = [
+        {
+            "url": url,
+            "steps": [
+                {"action": "navigate", "url": url},
+            ],
+        }
+    ]
+
+    orch = FunctionalTestOrchestrator(
+        num_browser_agents=1,
+        browser_type="chromium",
+        headless=headless,
+        max_tasks=len(tasks),
+    )
+
+    try:
+        report = asyncio.run(orch.run(tasks))
+    except KeyboardInterrupt:
+        print("\nDemo interrupted.", file=sys.stderr)
+        return 130
+    except Exception as exc:  # noqa: BLE001
+        logger.error("Browser pipeline failed: %s", exc)
+        return EXIT_FAILURES
+
+    report_paths = orch.generate_report(output_dir=output_dir)
+    report["report_paths"] = report_paths
+
+    passed = report.get("passed", 0)
+    failed = report.get("failed", 0)
+    total = report.get("total", 0)
+
+    print(f"\n  ✅  Demo complete — {passed}/{total} tasks passed, {failed} failed")
+    if report_paths:
+        print("  Reports written to:")
+        for p in report_paths:
+            print(f"    📄  {p}")
+
+    if json_summary:
+        try:
+            import pathlib
+
+            pathlib.Path(json_summary).parent.mkdir(parents=True, exist_ok=True)
+            pathlib.Path(json_summary).write_text(_json.dumps(report, indent=2), encoding="utf-8")
+            print(f"  📄  JSON summary written to: {json_summary}")
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("Could not write JSON summary to %s: %s", json_summary, exc)
+
+    return EXIT_OK if failed == 0 else EXIT_FAILURES
+
+
+def _register_autonomous_schedule(args: argparse.Namespace, cron_expression: str) -> int:
+    """Register an autonomous sweep schedule in the ScheduleStore and exit.
+
+    This uses the in-process store singleton when available (i.e. when the
+    server is embedded in the same process) or prints a summary for manual
+    registration.
+    """
+    import uuid as _uuid  # noqa: PLC0415
+
+    from mannf.product.scheduling.cron_utils import validate_cron  # noqa: PLC0415
+
+    try:
+        validate_cron(cron_expression)
+    except Exception as exc:  # noqa: BLE001
+        print(f"\n  ❌  Invalid cron expression '{cron_expression}': {exc}", file=sys.stderr)
+        return EXIT_CONFIG_ERROR
+
+    schedule_id = str(_uuid.uuid4())
+    tenant_id = getattr(args, "tenant_id", None) or "00000000-0000-0000-0000-000000000000"
+    name = (
+        getattr(args, "schedule_name", None)
+        or f"Autonomous sweep — {args.url}"
+    )
+
+    schedule_dict = {
+        "schedule_id": schedule_id,
+        "name": name,
+        "schedule_type": "autonomous",
+        "cron_expression": cron_expression,
+        "timezone": "UTC",
+        "tenant_id": tenant_id,
+        "spec_path": "",
+        "spec_format": "openapi",
+        "base_url": args.url,
+        "enabled": True,
+        "scan_config": {
+            "strategy": args.strategy,
+            "max_iterations": args.max_iterations,
+            "max_duration_s": args.max_duration_s,
+            "max_pages": args.max_pages,
+            "max_depth": args.max_depth,
+            "recrawl_every": args.recrawl_every,
+        },
+    }
+
+    # Attempt to register with the live store
+    registered = False
+    try:
+        from mannf.product.scheduling.store import get_store  # noqa: PLC0415
+        from mannf.product.scheduling.models import ScanSchedule  # noqa: PLC0415
+        from datetime import datetime as _dt, timezone as _tz  # noqa: PLC0415
+
+        store = get_store()
+        schedule = ScanSchedule(
+            schedule_id=schedule_id,
+            tenant_id=tenant_id,
+            name=name,
+            schedule_type="autonomous",
+            cron_expression=cron_expression,
+            timezone="UTC",
+            spec_path="",
+            spec_format="openapi",
+            base_url=args.url,
+            enabled=True,
+            scan_config=schedule_dict["scan_config"],
+            created_at=_dt.now(_tz.utc).isoformat(),
+            updated_at=_dt.now(_tz.utc).isoformat(),
+        )
+        store.create(schedule, plan_tier="enterprise")
+        registered = True
+    except Exception:  # noqa: BLE001
+        pass
+
+    output_fmt: str = getattr(args, "output", "text")
+    if output_fmt == "json":
+        print(json.dumps({"registered": registered, "schedule": schedule_dict}, indent=2))
+    else:
+        print(f"\n  📅  Autonomous sweep scheduled")
+        print(f"  Schedule ID: {schedule_id}")
+        print(f"  Name:        {name}")
+        print(f"  Target:      {args.url}")
+        print(f"  Cron:        {cron_expression}")
+        print(f"  Strategy:    {args.strategy}")
+        if registered:
+            print(f"  ✅  Registered with in-process scheduler")
+        else:
+            print(f"  ℹ️   Use the NAT API to register this schedule on a running server")
+        print()
+
+    return EXIT_OK
+
+
+async def _run_point_and_fire(args: argparse.Namespace) -> int:
+    """Execute the *point-and-fire* sub-command (autonomous test loop)."""
+    schedule_cron: Optional[str] = getattr(args, "schedule", None)
+
+    # --schedule mode: register a recurring sweep and exit
+    if schedule_cron:
+        return _register_autonomous_schedule(args, schedule_cron)
+
+    from mannf.core.agents.autonomous_loop_agent import AutonomousTestLoopAgent  # noqa: PLC0415
+
+    llm_provider = _build_llm_provider(args)
+
+    agent = AutonomousTestLoopAgent(
+        target_url=args.url,
+        max_iterations=args.max_iterations,
+        max_duration_s=args.max_duration_s,
+        stability_threshold=args.stability_threshold,
+        strategy=args.strategy,
+        risk_threshold=args.risk_threshold,
+        max_pages=args.max_pages,
+        max_depth=args.max_depth,
+        headless=not args.no_headless,
+        llm_provider=llm_provider,
+        recrawl_every=args.recrawl_every,
+    )
+
+    output_fmt: str = getattr(args, "output", "text")
+
+    print(f"\n  🤖  NAT Autonomous Test Loop")
+    print(f"  Target:    {args.url}")
+    print(f"  Strategy:  {args.strategy}")
+    print(f"  Max iters: {args.max_iterations}")
+    print(f"  Budget:    {args.max_duration_s:.0f}s")
+    print()
+
+    try:
+        report = await agent.run_loop()
+    except KeyboardInterrupt:
+        print("\n\n  👋  Autonomous run interrupted.\n")
+        return EXIT_SCAN_ERROR
+    except Exception as exc:  # noqa: BLE001
+        print(f"\n  ❌  Autonomous run failed: {exc}", file=sys.stderr)
+        return EXIT_SCAN_ERROR
+
+    if output_fmt == "json":
+        print(json.dumps(report.model_dump(), indent=2))
+        return EXIT_OK
+
+    # Human-readable summary
+    print(f"  ✅  Run complete — stop reason: {report.stop_reason}")
+    print(f"  Iterations:  {report.total_iterations}")
+    print(f"  Scenarios:   {report.total_scenarios_executed} executed")
+    print(f"  Passed:      {report.total_passed}")
+    print(f"  Failed:      {report.total_failed}")
+    print(f"  Flaky:       {report.total_flaky}")
+    print(f"  Duration:    {report.duration_s:.1f}s")
+    print()
+
+    if report.iterations:
+        print("  Iteration summary:")
+        for it in report.iterations:
+            status = "✅" if it.failed == 0 else "❌"
+            print(
+                f"    {status}  [{it.iteration:2d}] "
+                f"exec={it.scenarios_executed:3d}  "
+                f"pass={it.passed:3d}  "
+                f"fail={it.failed:3d}  "
+                f"new={it.new_failures:2d}  "
+                f"({it.duration_s:.1f}s)"
+            )
+        print()
+
+    if report.unique_failures:
+        print(f"  Unique failures ({len(report.unique_failures)}):")
+        for f in report.unique_failures[:10]:
+            print(f"    • {f.get('page', f.get('url', '?'))}: {f.get('error', '')[:80]}")
+        if len(report.unique_failures) > 10:
+            print(f"    … and {len(report.unique_failures) - 10} more")
+        print()
+
+    return EXIT_FAILURES if report.total_failed > 0 else EXIT_OK
+
+
+async def _run_import(args: argparse.Namespace) -> int:
+    """Execute the *import* sub-command (batch artifact ingestion)."""
+    import pathlib  # noqa: PLC0415
+    from mannf.product.ingestors.loader import (  # noqa: PLC0415
+        get_ingestor_by_name,
+        get_ingestor_for_source,
+        load_all_ingestors,
+    )
+    from mannf.product.ingestors.models import IngestorSource  # noqa: PLC0415
+    from mannf.core.browser.ingestor_bridge import IngestorBridge  # noqa: PLC0415
+    from mannf.product.orchestrator import _guess_format  # noqa: PLC0415
+
+    source_path = pathlib.Path(args.source)
+    import_format: str = args.import_format
+    base_url: str = getattr(args, "base_url", "") or ""
+    output_fmt: str = getattr(args, "output", "text")
+    replay_mode: bool = getattr(args, "replay_mode", False)
+    out_file: Optional[str] = getattr(args, "out_file", None)
+
+    # --- Collect files to ingest ---
+    files_to_ingest: list[pathlib.Path] = []
+    if source_path.is_dir():
+        # Recursively discover all files; filter later by format
+        for f in sorted(source_path.rglob("*")):
+            if f.is_file():
+                files_to_ingest.append(f)
+    elif source_path.is_file():
+        files_to_ingest.append(source_path)
+    else:
+        print(
+            f"\n  ❌  Source path not found: {source_path}\n",
+            file=sys.stderr,
+        )
+        return EXIT_CONFIG_ERROR
+
+    if not files_to_ingest:
+        print(f"\n  ❌  No files found in {source_path}\n", file=sys.stderr)
+        return EXIT_CONFIG_ERROR
+
+    all_ingestors = load_all_ingestors()
+
+    results_summary: list[dict] = []
+    all_scenarios: list[dict] = []
+    total_files = 0
+    total_scenarios = 0
+    skipped_files = 0
+
+    if output_fmt == "text":
+        print(f"\n  📥  NAT Batch Import")
+        print(f"  Source:  {source_path}")
+        print(f"  Format:  {import_format}")
+        if base_url:
+            print(f"  Base URL: {base_url}")
+        print()
+
+    for file_path in files_to_ingest:
+        # Determine format
+        if import_format == "auto":
+            guessed = _guess_format(str(file_path))
+            if guessed is None:
+                # Try by filename pattern for playwright/cypress
+                fn = file_path.name.lower()
+                if ".spec." in fn or ".test." in fn:
+                    if fn.endswith(".ts") or fn.endswith(".js"):
+                        guessed = "playwright"
+                elif fn.endswith(".cy.js") or fn.endswith(".cy.ts"):
+                    guessed = "cypress"
+            if guessed is None:
+                skipped_files += 1
+                if output_fmt == "text":
+                    print(f"  ⚠️   Skipped (unknown format): {file_path.name}")
+                continue
+            fmt = guessed
+        else:
+            fmt = import_format
+
+        # Build source
+        source = IngestorSource(
+            format=fmt,
+            path=str(file_path),
+            metadata={"filename": file_path.name},
+        )
+
+        # Find ingestor
+        ingestor = get_ingestor_for_source(source, all_ingestors)
+        if ingestor is None:
+            skipped_files += 1
+            if output_fmt == "text":
+                print(f"  ⚠️   Skipped (no ingestor for format={fmt!r}): {file_path.name}")
+            continue
+
+        # Run ingestor
+        ingest_config: dict = {}
+        if replay_mode and ingestor.name == "har":
+            ingest_config["replay_mode"] = True
+
+        try:
+            ingest_result = await ingestor.ingest(source, ingest_config)
+        except Exception as exc:  # noqa: BLE001
+            skipped_files += 1
+            if output_fmt == "text":
+                print(f"  ❌  Failed ({ingestor.name}): {file_path.name} — {exc}")
+            continue
+
+        if not ingest_result.success and not ingest_result.test_cases and not ingest_result.endpoints:
+            skipped_files += 1
+            if output_fmt == "text":
+                errors_str = "; ".join(ingest_result.errors) if ingest_result.errors else "no results"
+                print(f"  ⚠️   Empty result: {file_path.name} — {errors_str}")
+            continue
+
+        # Convert to scenario dicts via IngestorBridge
+        bridge = IngestorBridge(base_url=base_url or "https://example.com", source_tag=ingestor.name)
+        scenarios = bridge.convert(ingest_result)
+
+        all_scenarios.extend(scenarios)
+        total_files += 1
+        total_scenarios += len(scenarios)
+
+        file_summary = {
+            "file": str(file_path),
+            "format": fmt,
+            "ingestor": ingestor.name,
+            "endpoints": len(ingest_result.endpoints),
+            "test_cases": len(ingest_result.test_cases),
+            "scenarios": len(scenarios),
+        }
+        results_summary.append(file_summary)
+
+        if output_fmt == "text":
+            print(
+                f"  ✅  {file_path.name}  [{ingestor.name}]  "
+                f"→ {len(scenarios)} scenario(s)"
+            )
+
+    if output_fmt == "text":
+        print()
+        print(f"  Summary: {total_files} file(s) imported, {total_scenarios} scenario(s) generated")
+        if skipped_files:
+            print(f"           {skipped_files} file(s) skipped (unrecognized or empty)")
+        print()
+
+    # Write results
+    output_data = {
+        "total_files": total_files,
+        "total_scenarios": total_scenarios,
+        "skipped_files": skipped_files,
+        "files": results_summary,
+        "scenarios": all_scenarios,
+    }
+
+    if out_file:
+        out_path = pathlib.Path(out_file)
+        out_path.write_text(json.dumps(output_data, indent=2), encoding="utf-8")
+        if output_fmt == "text":
+            print(f"  💾  Scenarios written to: {out_path}\n")
+    elif output_fmt == "json":
+        print(json.dumps(output_data, indent=2))
+
+    return EXIT_OK if total_files > 0 else EXIT_CONFIG_ERROR
+
+
+def main(argv: Optional[list] = None) -> None:
+    """Entry point for ``nat`` CLI and ``python -m mannf``."""
+    # ------------------------------------------------------------------
+    # Step 1: Pre-parse to find --config before the full parser runs.
+    # This allows the config file to set defaults that CLI flags override.
+    # ------------------------------------------------------------------
+    if argv is None:
+        argv = sys.argv[1:]
+
+    pre_parser = argparse.ArgumentParser(add_help=False)
+    pre_parser.add_argument("--config", default=None)
+    pre_parser.add_argument("--version", "-V", action="version", version=f"nat {__version__}")
+    pre_args, _ = pre_parser.parse_known_args(argv)
+
+    # ------------------------------------------------------------------
+    # Step 2: Load config file and apply as defaults.
+    # ------------------------------------------------------------------
+    try:
+        config = _load_natrc(pre_args.config)
+    except (OSError, ValueError) as exc:
+        print(f"Configuration error: {exc}", file=sys.stderr)
+        sys.exit(EXIT_CONFIG_ERROR)
+
+    parser = _build_parser()
+
+    if config:
+        _apply_config_defaults(parser, config)
+
+    # ------------------------------------------------------------------
+    # Step 3: Parse argv.  Map argparse's exit-2 (bad usage) → exit 3.
+    # ------------------------------------------------------------------
+    # Strip --config from argv since it's a top-level flag handled above;
+    # individual subcommand parsers don't know about it.
+    clean_argv = []
+    skip_next = False
+    for arg in argv:
+        if skip_next:
+            skip_next = False
+            continue
+        if arg == "--config":
+            skip_next = True
+            continue
+        if arg.startswith("--config="):
+            continue
+        clean_argv.append(arg)
+
+    try:
+        args = parser.parse_args(clean_argv)
+    except SystemExit as exc:
+        sys.exit(EXIT_CONFIG_ERROR if exc.code == 2 else (exc.code or 0))
+
+    # Propagate config path for downstream use
+    args.config = pre_args.config
+
+    # ------------------------------------------------------------------
+    # Step 4: Validate required fields that may be satisfied by config.
+    # ------------------------------------------------------------------
+    if args.command in ("scan", "security-scan"):
+        if not getattr(args, "base_url", None):
+            print(
+                "error: --base-url is required (or set base_url in .natrc)",
+                file=sys.stderr,
+            )
+            sys.exit(EXIT_CONFIG_ERROR)
+
+    # ------------------------------------------------------------------
+    # Step 5: Dispatch.
+    # ------------------------------------------------------------------
+    log_level = logging.INFO if getattr(args, "verbose", False) else logging.WARNING
+    logging.basicConfig(level=log_level, format="%(levelname)s %(name)s: %(message)s")
+
+    if args.command == "scan":
+        exit_code = asyncio.run(_run_scan(args))
+        sys.exit(exit_code)
+    elif args.command == "security-scan":
+        exit_code = asyncio.run(_run_security_scan(args))
+        sys.exit(exit_code)
+    elif args.command == "weights":
+        exit_code = _run_weights(args)
+        sys.exit(exit_code)
+    elif args.command == "export":
+        exit_code = _run_export(args)
+        sys.exit(exit_code)
+    elif args.command == "heal":
+        exit_code = _run_heal(args)
+        sys.exit(exit_code)
+    elif args.command == "test-gen":
+        exit_code = asyncio.run(_run_test_gen(args))
+        sys.exit(exit_code)
+    elif args.command == "completions":
+        exit_code = _run_completions(args)
+        sys.exit(exit_code)
+    elif args.command == "demo":
+        exit_code = _run_demo(args)
+        sys.exit(exit_code)
+    elif args.command == "setup":
+        from mannf.product.setup_wizard import run_setup_wizard  # noqa: PLC0415
+        exit_code = asyncio.run(run_setup_wizard(args))
+        sys.exit(exit_code)
+    elif args.command == "upgrade":
+        from mannf.product.upgrade import run_upgrade  # noqa: PLC0415
+        exit_code = run_upgrade(args)
+        sys.exit(exit_code)
+    elif args.command == "uninstall":
+        from mannf.product.uninstall import run_uninstall  # noqa: PLC0415
+        exit_code = run_uninstall(args)
+        sys.exit(exit_code)
+    elif args.command == "doctor":
+        from mannf.product.doctor import run_doctor  # noqa: PLC0415
+        exit_code = asyncio.run(run_doctor(args))
+        sys.exit(exit_code)
+    elif args.command == "point-and-fire":
+        exit_code = asyncio.run(_run_point_and_fire(args))
+        sys.exit(exit_code)
+    elif args.command == "import":
+        exit_code = asyncio.run(_run_import(args))
+        sys.exit(exit_code)
+    elif args.command == "worker":
+        exit_code = _run_worker(args)
+        sys.exit(exit_code)
+    elif args.command == "plan":
+        exit_code = asyncio.run(_run_plan(args))
+        sys.exit(exit_code)
+    elif args.command == "test":
+        exit_code = asyncio.run(_run_nl_test(args))
+        sys.exit(exit_code)
+    else:
+        parser.print_help()
+        sys.exit(EXIT_CONFIG_ERROR)
+
+
+if __name__ == "__main__":
+    main()