rtl-buddy 2.1.4__tar.gz

rtl_buddy-2.1.4/.github/workflows/docs.yml

@@ -0,0 +1,64 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'scripts/gen_cli_reference.py'
+      - 'src/rtl_buddy/**'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'scripts/gen_cli_reference.py'
+      - 'src/rtl_buddy/**'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: Install dependencies
+        run: uv sync --group docs
+
+      - name: Check CLI reference is up to date
+        run: uv run python scripts/gen_cli_reference.py --check
+
+      - name: Build docs
+        run: uv run mkdocs build --strict
+
+      - name: Check site links
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: --offline site/**/*.html
+          fail: true
+
+      - name: Upload Pages artifact
+        if: github.event_name == 'push'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+
+  deploy:
+    if: github.event_name == 'push'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

rtl_buddy-2.1.4/.github/workflows/publish.yml

@@ -0,0 +1,45 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/rtl_buddy
+    permissions:
+      id-token: write
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

rtl_buddy-2.1.4/.github/workflows/release-on-merge.yml

@@ -0,0 +1,91 @@
+name: Release on PR Merge
+
+on:
+  pull_request:
+    types: [closed]
+    branches:
+      - main
+
+jobs:
+  release:
+    if: github.event.pull_request.merged == true
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout merged commit
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.pull_request.merge_commit_sha }}
+
+      - name: Compute next version
+        id: version
+        run: |
+          LATEST=$(git tag --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -1)
+          if [ -z "$LATEST" ]; then
+            LATEST="v0.0.0"
+          fi
+
+          VERSION=${LATEST#v}
+          MAJOR=$(echo "$VERSION" | cut -d. -f1)
+          MINOR=$(echo "$VERSION" | cut -d. -f2)
+          PATCH=$(echo "$VERSION" | cut -d. -f3)
+
+          LABELS='${{ toJson(github.event.pull_request.labels.*.name) }}'
+          if echo "$LABELS" | grep -qi '"version/major"'; then
+            NEW_TAG="v$((MAJOR + 1)).0.0"
+          elif echo "$LABELS" | grep -qi '"version/minor"'; then
+            NEW_TAG="v${MAJOR}.$((MINOR + 1)).0"
+          elif echo "$LABELS" | grep -qi '"version/patch"'; then
+            NEW_TAG="v${MAJOR}.${MINOR}.$((PATCH + 1))"
+          else
+            echo "No version label found, skipping release."
+            echo "new_tag=" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          echo "latest_tag=${LATEST}" >> "$GITHUB_OUTPUT"
+          echo "new_tag=${NEW_TAG}" >> "$GITHUB_OUTPUT"
+          echo "Bumping ${LATEST} -> ${NEW_TAG}"
+
+      - name: Create and push tag
+        if: steps.version.outputs.new_tag != ''
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -a "${{ steps.version.outputs.new_tag }}" \
+            -m "Release ${{ steps.version.outputs.new_tag }}"
+          git push origin "${{ steps.version.outputs.new_tag }}"
+
+      - name: Create GitHub release
+        if: steps.version.outputs.new_tag != ''
+        uses: actions/github-script@v8
+        env:
+          TAG: ${{ steps.version.outputs.new_tag }}
+          PREV_TAG: ${{ steps.version.outputs.latest_tag }}
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          PR_USER: ${{ github.event.pull_request.user.login }}
+          SERVER_URL: ${{ github.server_url }}
+          REPO: ${{ github.repository }}
+        with:
+          script: |
+            const tag = process.env.TAG;
+            const prevTag = process.env.PREV_TAG;
+            let body = `**PR #${process.env.PR_NUMBER}** by @${process.env.PR_USER}: ${process.env.PR_TITLE}`;
+
+            if (prevTag && prevTag !== 'v0.0.0') {
+              body += `\n\n**Full changelog:** ${process.env.SERVER_URL}/${process.env.REPO}/compare/${prevTag}...${tag}`;
+            }
+
+            await github.rest.repos.createRelease({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              tag_name: tag,
+              name: `Release ${tag}`,
+              body,
+              draft: false,
+              prerelease: false,
+            });

rtl_buddy-2.1.4/.gitignore

@@ -0,0 +1,13 @@
+**egg-info
+**__pycache__
+**.sw?
+tags
+.venv
+.worktrees/
+# Sphinx
+docs/_build/
+_build/
+
+.DS_Store
+# MkDocs build output
+site/

rtl_buddy-2.1.4/AGENTS.md

@@ -0,0 +1,94 @@
+# rtl_buddy — AI Agent Guide
+
+## Role
+
+This repo is the source-of-truth implementation of the `rtl_buddy` CLI.
+
+## Key Files
+
+```text
+src/rtl_buddy/
+├── __main__.py            # package entry point
+├── rtl_buddy.py           # Typer CLI and top-level command flow
+├── logging_utils.py       # log_event(), setup_logging(), console helpers
+├── errors.py              # FatalRtlBuddyError, FilelistError, SetupScriptError
+├── seed_mode.py           # seed handling enum
+├── config/                # YAML-backed config classes
+├── runner/test_runner.py  # PRE -> COMP -> SIM -> POST execution
+└── tools/                 # filelist, sim, postproc, verible wrappers
+```
+
+## Development Rules
+
+- Keep changes targeted. Avoid broad refactors unless the task requires them.
+- Preserve CLI behavior unless intentionally changing it.
+- Treat YAML config classes and runtime behavior as part of the public interface for downstream RTL projects.
+- When adding or changing behavior, update downstream docs and validation assets after validating the implementation.
+
+## Implementation Notes
+
+- `rtl_buddy.py` owns CLI wiring, global options, and command dispatch.
+- `RootConfig` selects platform, builder, verible, and regression config from `root_config.yaml`.
+- `TestRunner` drives PRE, COMPILE, SIM, and POST with early-stop support.
+- `VlogSim` handles compile/sim command construction, log paths, seeds, and timeout behavior.
+- `VlogFilelist` handles `.f` parsing and transformations.
+- Hook scripts (`sweep`, `preproc`, `postproc`) are executed dynamically and should be treated as compatibility-sensitive APIs.
+
+## Validation
+
+Typical checks:
+
+```bash
+# from a project root that has `rtl_buddy` installed
+./venv/bin/python -m rtl_buddy regression -c regression.yaml
+./venv/bin/python -m rtl_buddy filelist test_module -c design/example_block/src/models.yaml
+./venv/bin/python -m rtl_buddy verible syntax design/example_block/src/test_module.sv
+
+# from a suite directory
+cd design/example_block/verif
+../../../venv/bin/python -m rtl_buddy test basic
+```
+
+If validating the dev checkout directly, install this repo into the target venv and confirm with `./venv/bin/python -m rtl_buddy --version`.
+
+## Logging Practices
+
+All runtime logging goes through `log_event()` in `src/rtl_buddy/logging_utils.py`. Do not use `logger.info(f"...")` directly — use `log_event(logger, level, "event.name", key=value, ...)` so that both human and machine modes produce correct output.
+
+### How it works
+
+- **Human mode (default)**: `_human_message()` converts each event into a readable sentence for `rtl_buddy.log` and the console. Machine-oriented fields are not visible.
+- **Machine mode (`--machine`)**: `rtl_buddy.log` is written as JSON Lines with the event name, all fields, and the human message. Console output is plain text.
+
+### Adding new events
+
+1. Choose a dotted event name following the existing convention (e.g. `compile.start`, `sim.timeout`, `suite_config.load_failed`).
+2. Call `log_event(logger, logging.<LEVEL>, "your.event", field1=val1, ...)`.
+3. If the event is logged at **WARNING or above**, add a dedicated `case` entry in `_human_message()`. Users see these messages directly, so they must be clear and actionable.
+4. DEBUG and INFO events may rely on the wildcard fallback formatter, which converts `"foo.bar"` to `"foo bar"` and appends select fields.
+
+### Error handling
+
+- Fatal config/environment errors: log at `logging.ERROR`, then `raise FatalRtlBuddyError(...)`. The top-level `run()` catches these and exits with code 2.
+- Per-test filelist failures: log at `logging.ERROR`, then `raise FilelistError(...)`. `TestRunner` catches these and records a `FilelistFailResults`.
+- Sweep/preproc script failures: return an error string from `pre()` or `_expand_tests_with_sweep()`. The caller records a `SetupFailResults` and continues.
+- Do not use `logger.critical()` — the old `ExitHandler` abort pattern has been removed.
+
+### Console output
+
+- Use `emit_console_text()` for direct user-facing output (e.g. git status banner, regression directory).
+- Use `render_summary()` for result tables — it writes a Rich table to the console and plain text to the log file.
+- Use `task_status()` for spinners on long-running phases (compile, sim). Falls back to plain text on non-interactive terminals.
+
+## Required Follow-Through
+
+After meaningful `rtl_buddy` changes:
+
+1. **If any CLI command, flag, or help text changed**: run `python scripts/gen_cli_reference.py` and commit the updated `docs/reference/cli.md` in the same PR. The file is committed to the repo and must stay in sync — CI will catch drift via `python scripts/gen_cli_reference.py --check`.
+2. Update any downstream agent docs if command behavior, YAML schema, version expectations, or validation notes changed.
+3. Update downstream integrations to the intended commit as needed.
+
+## Release Workflow
+
+1. Merge to `main` in this repo and tag (e.g. `v2.0.0`).
+2. Update and tag any downstream integrations that track this repo.

rtl_buddy-2.1.4/CLAUDE.md

@@ -0,0 +1,3 @@
+# rtl_buddy — Claude Code Guide
+
+@AGENTS.md

rtl_buddy-2.1.4/CONTRIBUTORS

@@ -0,0 +1,7 @@
+Loh Zhi-Hern
+Xie Jiacheng
+Emil Goh
+Damien Lim
+Chai Wei Lynthia
+Zubin Jain
+Daniel Lim

rtl_buddy-2.1.4/LICENSE

@@ -0,0 +1,11 @@
+Copyright 2024 rtl_buddy contributors
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

rtl_buddy-2.1.4/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: rtl_buddy
+Version: 2.1.4
+Summary: RTL Buddy is a build-system with testplan, regression, workflow support for Verilog RTL codebases.
+Author: Zhi-Hern Loh, Xie Jiacheng
+License-Expression: BSD-3-Clause
+Project-URL: Source, https://github.com/rtl-buddy/rtl_buddy
+Project-URL: Documentation, https://rtl-buddy.github.io/rtl_buddy/
+Project-URL: Tracker, https://github.com/rtl-buddy/rtl_buddy/issues
+Keywords: SystemVerilog,Verilog,ASIC,FPGA
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ruamel.yaml>=0.18.15
+Requires-Dist: typer>=0.19.2
+Requires-Dist: click>=8.3.0
+Requires-Dist: pyserde[yaml]>=0.27.0
+Requires-Dist: rich>=14.0.0
+Dynamic: license-file
+
+# `rtl_buddy`
+
+`rtl_buddy` is a CLI for running RTL tests, regressions, filelist generation, and adjacent workflow automation in Verilog and SystemVerilog projects. It is designed to work well for both humans and AI agents.
+
+It is built to sit on top of the tools your project already uses, while giving you a cleaner, more repeatable interface for day-to-day verification work. The primary supported flows are Verilator and VCS-based compile, simulation, and regression workflows. Basic Verible command integration exists, while broader first-class Verible and PeakRDL workflows are on the roadmap.
+
+## Why `rtl_buddy`
+
+`rtl_buddy` gives RTL projects a lightweight control plane for common verification tasks:
+
+- Run a single test or a full regression from YAML config instead of ad hoc shell scripts
+- Keep simulator invocation, seeds, logs, and result handling consistent across runs
+- Manage filelists easily with project model definitions
+- Add sweep generation, preprocessing, and postprocessing hooks without rewriting the main flow
+- Export machine-readable logs that work well in CI and AI-agent-driven workflows
+
+## Features
+
+- **Test and regression commands**: run one test, many tests, or whole suites with a consistent CLI
+- **Randomized testing support**: create new seeds, repeat runs, and replay previous randomized iterations
+- **Structured config model**: describe suites, regressions, platforms, builders, and models in readable YAML
+- **Filelist generation**: build simulator-ready filelists from `models.yaml`
+- **Coverage workflows**: collect, merge, summarize, and export Verilator coverage
+- **Hookable execution flow**: plug in your own sweep generation, test preprocessing, and postprocessing scripts
+- **Verible integration**: invoke lint, syntax, formatting, and preprocessing commands through the same project config
+- **Rich outputs for humans**: displays pretty formatted for easy reading
+- **Structured logging for machines**: emits JSONL logs for interpretation by CI systems, automation, and coding agents
+- **Cross-project reuse**: keep one tool interface while adapting it to different RTL repo layouts and builder setups
+
+## Installation
+
+`rtl_buddy` is installed into your project environment with `uv` directly from the Git repository. PyPI publication is planned but not yet available.
+
+Prerequisites:
+
+- Python 3.11+
+- `uv`
+- A simulator on `PATH`
+  - Verilator is the recommended open-source starting point
+  - VCS is also supported as a first-class flow
+- Optional Verible binaries if you want to use `uv run rb verible ...`
+- Optional system-level coverage tools:
+  - `lcov` for LCOV and HTML coverage export
+  - [Coverview](https://github.com/antmicro/coverview) for Coverview package generation
+
+See [docs/install.md](docs/install.md) for the full install flow.
+
+## Documentation
+
+Full documentation lives in [`docs/`](docs/), is built with MkDocs, and is intended to be published on GitHub Pages.
+
+To preview the docs locally while developing:
+
+```bash
+uv sync --group docs
+uv run mkdocs serve
+```
+
+Useful entry points:
+
+- [Installation](docs/install.md)
+- [Quick Start](docs/quickstart.md)
+- [Coverage](docs/concepts/coverage.md)
+- [CLI Reference](docs/reference/cli.md)
+- [YAML Formats](docs/reference/yaml.md)
+
+## Quick Start
+
+Run a test:
+
+```bash
+uv run rb test basic
+```
+
+Run a regression:
+
+```bash
+uv run rb regression
+```
+
+For full usage, see [docs/quickstart.md](docs/quickstart.md).
+
+## Known Issues
+
+See [docs/known-issues.md](docs/known-issues.md).

rtl_buddy-2.1.4/README.md

@@ -0,0 +1,85 @@
+# `rtl_buddy`
+
+`rtl_buddy` is a CLI for running RTL tests, regressions, filelist generation, and adjacent workflow automation in Verilog and SystemVerilog projects. It is designed to work well for both humans and AI agents.
+
+It is built to sit on top of the tools your project already uses, while giving you a cleaner, more repeatable interface for day-to-day verification work. The primary supported flows are Verilator and VCS-based compile, simulation, and regression workflows. Basic Verible command integration exists, while broader first-class Verible and PeakRDL workflows are on the roadmap.
+
+## Why `rtl_buddy`
+
+`rtl_buddy` gives RTL projects a lightweight control plane for common verification tasks:
+
+- Run a single test or a full regression from YAML config instead of ad hoc shell scripts
+- Keep simulator invocation, seeds, logs, and result handling consistent across runs
+- Manage filelists easily with project model definitions
+- Add sweep generation, preprocessing, and postprocessing hooks without rewriting the main flow
+- Export machine-readable logs that work well in CI and AI-agent-driven workflows
+
+## Features
+
+- **Test and regression commands**: run one test, many tests, or whole suites with a consistent CLI
+- **Randomized testing support**: create new seeds, repeat runs, and replay previous randomized iterations
+- **Structured config model**: describe suites, regressions, platforms, builders, and models in readable YAML
+- **Filelist generation**: build simulator-ready filelists from `models.yaml`
+- **Coverage workflows**: collect, merge, summarize, and export Verilator coverage
+- **Hookable execution flow**: plug in your own sweep generation, test preprocessing, and postprocessing scripts
+- **Verible integration**: invoke lint, syntax, formatting, and preprocessing commands through the same project config
+- **Rich outputs for humans**: displays pretty formatted for easy reading
+- **Structured logging for machines**: emits JSONL logs for interpretation by CI systems, automation, and coding agents
+- **Cross-project reuse**: keep one tool interface while adapting it to different RTL repo layouts and builder setups
+
+## Installation
+
+`rtl_buddy` is installed into your project environment with `uv` directly from the Git repository. PyPI publication is planned but not yet available.
+
+Prerequisites:
+
+- Python 3.11+
+- `uv`
+- A simulator on `PATH`
+  - Verilator is the recommended open-source starting point
+  - VCS is also supported as a first-class flow
+- Optional Verible binaries if you want to use `uv run rb verible ...`
+- Optional system-level coverage tools:
+  - `lcov` for LCOV and HTML coverage export
+  - [Coverview](https://github.com/antmicro/coverview) for Coverview package generation
+
+See [docs/install.md](docs/install.md) for the full install flow.
+
+## Documentation
+
+Full documentation lives in [`docs/`](docs/), is built with MkDocs, and is intended to be published on GitHub Pages.
+
+To preview the docs locally while developing:
+
+```bash
+uv sync --group docs
+uv run mkdocs serve
+```
+
+Useful entry points:
+
+- [Installation](docs/install.md)
+- [Quick Start](docs/quickstart.md)
+- [Coverage](docs/concepts/coverage.md)
+- [CLI Reference](docs/reference/cli.md)
+- [YAML Formats](docs/reference/yaml.md)
+
+## Quick Start
+
+Run a test:
+
+```bash
+uv run rb test basic
+```
+
+Run a regression:
+
+```bash
+uv run rb regression
+```
+
+For full usage, see [docs/quickstart.md](docs/quickstart.md).
+
+## Known Issues
+
+See [docs/known-issues.md](docs/known-issues.md).

rtl_buddy-2.1.4/docs/agents.md

@@ -0,0 +1,88 @@
+# For Agents
+
+This page covers how AI agents should interact with `rtl_buddy`. It describes machine mode, log formats, and the recommended validation workflow.
+
+## Always use machine mode
+
+Run `rtl_buddy` with `--machine` in all agent-driven workflows:
+
+```bash
+rtl-buddy --machine test basic
+rtl-buddy --machine regression -c design/regression.yaml
+```
+
+In machine mode:
+
+- `rtl_buddy.log` is written as **JSON Lines** (one JSON object per line) instead of human-readable text.
+- Console output switches to plain, colorless text — no Rich formatting, no spinners.
+- All structured event fields (event name, status, durations, paths) are present in the log.
+
+This makes it reliable to parse outcomes from `rtl_buddy.log` without screen-scraping.
+
+## Log file locations
+
+| File | Description |
+|------|-------------|
+| `rtl_buddy.log` | Orchestration log; JSONL in machine mode, human-readable otherwise |
+| `logs/{test_name}.log` | Simulation stdout for each test |
+| `logs/{test_name}.err` | Simulation stderr for each test |
+| `logs/{test_name}.randseed` | Seed used for this test run |
+| `test.log` | Symlink to the most recent test's log |
+| `test.err` | Symlink to the most recent test's stderr |
+| `test.randseed` | Symlink to the most recent test's seed |
+
+All files are written relative to the directory where `rtl_buddy` is invoked.
+
+## Machine mode log format
+
+Each line in `rtl_buddy.log` (machine mode) is a JSON object:
+
+```json
+{"event": "test.pass", "name": "smoke", "duration": 4.2, "seed": 31310, "msg": "smoke passed"}
+{"event": "suite.summary", "passed": 3, "failed": 0, "total": 3, "msg": "3/3 passed"}
+```
+
+Key fields:
+
+- `event`: dotted event name identifying what happened (e.g. `test.pass`, `test.fail`, `compile.error`)
+- `msg`: the human-readable message corresponding to the event
+- Other fields are event-specific (name, duration, seed, exit code, etc.)
+
+## Recommended validation workflow
+
+```bash
+# 1. Check rtl_buddy version
+rtl-buddy --version
+
+# 2. Dry-run: verify pre-flight config without compiling or simulating
+rtl-buddy --machine test basic --early-stop pre
+
+# 3. Run a single test
+rtl-buddy --machine test basic
+
+# 4. Check the log for outcome
+grep '"event"' rtl_buddy.log | tail -5
+
+# 5. Run a full regression
+rtl-buddy --machine regression -c design/regression.yaml
+```
+
+Use `--early-stop pre` to validate that config files, model paths, and testbench paths all resolve correctly before committing to a compile step.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | All tests passed |
+| 1 | One or more tests failed |
+| 2 | Fatal configuration or environment error |
+
+## Version checking
+
+Always verify the installed version before running, especially in CI or after dependency updates:
+
+```bash
+rtl-buddy --version
+```
+
+The version follows semantic versioning. Breaking YAML schema or CLI changes are signaled by a major version bump.