diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 68904c5..2378d91 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -2,31 +2,46 @@ name: CI
 
 on:
   push:
+    branches: [main]
   pull_request:
+    branches: [main]
 
 jobs:
   tests:
-    runs-on: ubuntu-latest
+    name: ${{ matrix.os }} / py${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
     strategy:
+      fail-fast: false
       matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
         python-version: ["3.11", "3.12"]
 
     steps:
-      - name: Checkout repository
+      - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Set up Python
+      - name: Setup Python
         uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
+          cache: pip
 
-      - name: Install dependencies
+      - name: Install
         run: |
-          python -m pip install --upgrade pip
-          pip install -e ".[dev]"
+          python -m pip install -U pip
+          python -m pip install -e ".[dev]"
 
-      - name: Run Ruff
-        run: ruff check .
+      - name: Format
+        run: python -m ruff format --check .
 
-      - name: Run pytest
-        run: pytest
+      - name: Lint
+        run: python -m ruff check .
+
+      - name: Smoke
+        run: |
+          python -m sysforge --version
+          python -m sysforge doctor
+          python -m sysforge collect --pretty
+
+      - name: Tests
+        run: python -m pytest -q
diff --git a/.gitignore b/.gitignore
index 9ac09ef..3fdb221 100644
--- a/.gitignore
+++ b/.gitignore
@@ -18,3 +18,6 @@ dist/
 # Editors
 .DS_Store
 .vscode/
+
+# sysforge output artifacts
+sysforge-report.json
\ No newline at end of file
diff --git a/README.md b/README.md
index c850994..55992be 100644
--- a/README.md
+++ b/README.md
@@ -11,7 +11,8 @@ Modular system diagnostics and analysis CLI. Collects environment data, runs hea
 ```bash
 python3 -m venv .venv
 source .venv/bin/activate  # Windows: .venv\Scripts\activate
-pip install -e ".[dev]"
+python -m pip install -U pip
+python -m pip install -e ".[dev]"
 ```
 
 ## Usage
@@ -56,10 +57,17 @@ Exit codes (for `sysforge doctor` and `sysforge report`):
 ```bash
 python3 -m venv .venv
 source .venv/bin/activate  # Windows: .venv\Scripts\activate
-pip install -e ".[dev]"
-pip install pre-commit
+python -m pip install -U pip
+python -m pip install -e ".[dev]"
+python -m pip install -U pre-commit
 pre-commit install
 pre-commit run --all-files  # optional: run on demand
-ruff check .
-pytest
+```
+
+Run the same checks locally that CI performs:
+```bash
+python -m ruff format --check .
+python -m ruff check .
+python -m pytest -q
+sysforge --version
 ```
diff --git a/src/sysforge/__init__.py b/src/sysforge/__init__.py
index 8ed61fa..e306618 100644
--- a/src/sysforge/__init__.py
+++ b/src/sysforge/__init__.py
@@ -3,4 +3,4 @@
 """
 
 __all__ = ["__version__"]
-__version__ = "0.1.0"
\ No newline at end of file
+__version__ = "0.1.0"
diff --git a/src/sysforge/cli.py b/src/sysforge/cli.py
index 326ca90..cdd334c 100644
--- a/src/sysforge/cli.py
+++ b/src/sysforge/cli.py
@@ -16,6 +16,7 @@
     help="sysforge — collect environment data, run health checks, and write reports.",
 )
 
+
 def _exit_code_from_summary(summary: object) -> int:
     """Map doctor `summary` to CLI exit codes.
 
diff --git a/src/sysforge/reporting.py b/src/sysforge/reporting.py
index d70758d..cbe83b0 100644
--- a/src/sysforge/reporting.py
+++ b/src/sysforge/reporting.py
@@ -29,13 +29,13 @@ def write_report_file(data: dict[str, Any], path: Path, *, pretty: bool = False)
 
 
 def _format_bytes(value: Any) -> str:
-    if isinstance(value, (int, float)):
+    if isinstance(value, int | float):
         return f"{int(value):,} bytes"
     return "unknown"
 
 
 def _format_percent(value: Any) -> str:
-    if isinstance(value, (int, float)):
+    if isinstance(value, int | float):
         return f"{value * 100:.1f}%"
     return "unknown"