                                                                                
 Usage: routertl [OPTIONS] COMMAND [ARGS]...                                    
                                                                                
 RouteRTL — one CLI for FPGA projects: describe the design in project.yml, then 
 simulate, lint, build and program it.                                          
                                                                                
                                                                                
  Getting started                                                               
    • no project here → routertl init (or routertl intro for the walkthrough)   
    • then → routertl doctor                                                    
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --verbose      -v  Enable verbose output and expanded plugin logging.        │
│ --agent-mode       Prefer compact structured output where commands support   │
│                    it.                                                       │
│ --json-errors      Alias for --agent-mode for agent-facing error capture.    │
│ --human            Force human-readable output even when RR_AGENT_MODE=1 is  │
│                    set (overrides agent-mode).                               │
│ --version      -V  Show the version and exit.                                │
│ --help         -h  Show this message and exit.                               │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ 🚀 Quickstart ──────────────────────────────────────────────────────────────╮
│ init            Initialize a new RouteRTL FPGA project.                      │
│ intro           Automated walkthrough — registry IPs → synthesizable design, │
│                 step by step.                                                │
│ eda             Native EDA Tool Management.                                  │
│ routewave       Launch the RouteWave waveform viewer.                        │
│ status          Display a project health dashboard.                          │
│ doctor          Environment health check — validate SDK toolchain, project   │
│                 config, and workspace hygiene.                               │
│ license         RouteRTL product license + EDA vendor license diagnostics.   │
│ version         Show the SDK version and exit.                               │
│ sdk-path        Print the resolved SDK root path and exit.                   │
│ help            Display deep, interactive manual-page documentation for a    │
│                 command.                                                     │
│ completion      Shell completion — emit scripts or install them in one shot. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ 🔨 Hardware Build ──────────────────────────────────────────────────────────╮
│ project         FPGA Project Management.                                     │
│ synth           Synthesis Validation Status Board.                           │
│ implementation  Run Project Mode Implementation (Place & Route).             │
│ bitstream       Generate the FPGA Bitstream (Synthesis + Implementation).    │
│ linting         Run the RouteRTL Smart Linter for a specific TOP module or   │
│                 all modules.                                                 │
│ hierarchy       View the design hierarchy for a given TOP module.            │
│ schematic       Generate an SVG schematic from RTL for a specific TOP        │
│                 module.                                                      │
│ fpga            FPGA toolchain queries — device families, parts, and         │
│                 licenses.                                                    │
│ program         FPGA Hardware Deployment (Bitstream + Software).             │
│ firmware        Scaffold and inspect soft-core firmware memory evidence.     │
│ ila             On-chip debug capture (ILA / SignalTap) → RouteWave.         │
│ hardware        Hardware connectivity and diagnostic tools.                  │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ 📥 Migration ───────────────────────────────────────────────────────────────╮
│ migrate         Migrate vendor FPGA projects to routertl.                    │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ 🧪 Verification ────────────────────────────────────────────────────────────╮
│ sim             Simulation commands — run tests, generate stubs, view        │
│                 history.                                                     │
│ testgen         Generate Cocotb test boilerplates for sources.               │
│ scan-tests      List available Cocotb tests.                                 │
│ waves           Open the waveform viewer on a file or the latest waveform.   │
│ viewlog         View a simulation log.                                       │
│ regression      Run RouteRTL regression suites (rr-native `make regression`  │
│                 replacement).                                                │
│ diff            Analyze git diff and suggest which tests to re-run.          │
│ watch           Auto-rerun simulation or linting whenever source files       │
│                 change.                                                      │
│ deps            Dependency inspection, graph export, and IP dependency       │
│                 fetch.                                                       │
│ info            Show detailed information about an RTL entity or module.     │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ 📊 Reporting & Rules ───────────────────────────────────────────────────────╮
│ report          Generate a unified project report.                           │
│ power           Power & thermal measurement (RTL-P3.1125 / P3.1310 /         │
│                 P3.1314).                                                    │
│ provenance      Report build-artifact provenance (is the dcp/bit/xsa         │
│                 current?).                                                   │
│ bom             Generate an FPGA Bill of Materials from ip.lock.             │
│ rules           FPGA design rules — check, add, and manage.                  │
│ telemetry       Manage local SDK telemetry data.                             │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ 📦 Workspace Management ────────────────────────────────────────────────────╮
│ target          Multi-project workspace management.                          │
│ workspace       Project Workspace and Configuration Management.              │
│ sources         List project source files grouped by category.               │
│ config          Read or write YAML configuration fields.                     │
│ ci              CI/CD pipeline management.                                   │
│ lock            Manage the project lockfile (routertl.lock).                 │
│ diff-lock       Show differences between current state and the lockfile.     │
│ release         Release helpers — verify a commit is tag-ready (RTL-P2.726). │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ 🧩 IP Package Manager ──────────────────────────────────────────────────────╮
│ pkg             IP package manager — add, install, and search FPGA IP cores. │
│ tool            Host-side Python tooling for IP packages (RTL-P2.480).       │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ 🧩 IP & Config Data ────────────────────────────────────────────────────────╮
│ ip              IP Manifest Management — init, list, hierarchy, update.      │
│ regbank         Register Bank — validate, generate, template, and export     │
│                 tools.                                                       │
│ rom             Generate ROM Data & Package.                                 │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ 🐧 Embedded Linux ──────────────────────────────────────────────────────────╮
│ linux           Embedded Linux generation and build tools.                   │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ 🐳 Docker Environments ─────────────────────────────────────────────────────╮
│ docker          Docker Container Development Environment.                    │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ 🪝 Hooks ───────────────────────────────────────────────────────────────────╮
│ hook            Manage TCL hooks for vendor tool integration.                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ 🧠 AI Assistant ────────────────────────────────────────────────────────────╮
│ ask             Ask the FPGA knowledge base a question.                      │
│ branch          Inspect Git branch state for agent handoff hygiene.          │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ 📌 Aliases ─────────────────────────────────────────────────────────────────╮
│ alias           Manage user-defined command aliases.                         │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ automation      Declarative scheduler for recurring rr workflows             │
│                 (RTL-P3.834).                                                │
│ bench           Authoritative bench topology, safe edits, and live state.    │
│ board           Board pinout registry — list, inspect, and preview           │
│                 subscriptions.                                               │
│ cache           Shared build-avoidance store — inspect, GC, purge            │
│                 (RTL-P3.1447).                                               │
│ contract        Present the project's behavioural contract + feature matrix. │
│ diagnose        Hazard-scoped post-mortem from a build/sim log (RTL-P3.180). │
│ env             Emit eval-able shell commands that activate vendor EDA       │
│                 tools.                                                       │
│ fdd             Living Firmware Design Document — scaffolded from            │
│                 declarative truth.                                           │
│ formal          Formally prove design properties (PSL / SVA) — RTL-P3.736.   │
│ hw              HW contract execution — run, promote, replay against         │
│                 silicon.                                                     │
│ incident        Community FPGA-build incident reporting (RTL-P3.181).        │
│ lease           Exclusive leases on bench hardware (board / console / JTAG / │
│                 TFTP).                                                       │
│ lint-profiles   Discover lint profiles and inspect their authoring           │
│                 conventions.                                                 │
│ loop            Convergence loop steward — budgeted sessions + anti-cheat    │
│                 close gate.                                                  │
│ mcp             MCP (Model Context Protocol) server integration for AI       │
│                 agents.                                                      │
│ metrics         Per-build resource metrics audit log.                        │
│ queue           Local resource-arbitrated EDA build queue (RTL-P2.749).      │
│ ref             Reference designs — discover, install, and share buildable   │
│                 FPGA projects.                                               │
│ schema          Show the project.yml / target-yml field reference.           │
│ skill           Agent skill discovery and verification.                      │
│ timing          Post-implementation CDC / timing analysis on the routed DCP. │
│ update          Update the RouteRTL SDK to the latest version.               │
│ vboard          Virtual FPGA board sessions (RouteBoard bridge, RTL-P2.969). │
│ verify          Report recorded verification evidence without executing      │
│                 checks.                                                      │
│ waivers         Audit every waiver/suppression in the project as one census. │
│ wisdom          Knowledge Loop: query the signature corpus, share what you   │
│                 learned.                                                     │
╰──────────────────────────────────────────────────────────────────────────────╯
