docs & tooling: new user onboarding + smart-test and pre-commit review fixes

.github/workflows/pr-orchestrator.yml

@@ -210,7 +210,7 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           pip install "hatch" "virtualenv<21" coverage "coverage[toml]" pytest pytest-cov pytest-mock pytest-asyncio pytest-xdist pytest-timeout
-          pip install -e .
+          pip install -e ".[dev]"
 
       - name: Cache hatch environments
         if: needs.changes.outputs.skip_tests_dev_to_main != 'true'
@@ -495,7 +495,7 @@ jobs:
       - name: Install type-check dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e . basedpyright
+          pip install -e ".[dev]"
       - name: Run type checking
         run: |
           echo "🔍 Running basedpyright type checking..."
@@ -533,7 +533,7 @@ jobs:
       - name: Install lint dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e . ruff basedpyright pylint
+          pip install -e ".[dev]"
 
       - name: Run linting
         run: |

.github/workflows/specfact.yml

@@ -62,8 +62,8 @@ jobs:
 
       - name: Install SpecFact CLI
         run: |
-          echo "📦 Installing SpecFact CLI..."
-          pip install -e .
+          echo "📦 Installing SpecFact CLI (contracts extra for repro / CrossHair)..."
+          pip install -e ".[contracts]"
 
       - name: Enforce Core-Module Isolation
         run: |

CHANGELOG.md

@@ -10,6 +10,31 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.45.1] - 2026-04-03
+
+### Changed
+
+- **Dependency install profiles**: the default wheel is slimmer—CrossHair, Hypothesis, Ruff, Radon,
+  and unused pins (`python-dotenv`, `cffi`) are no longer in core `dependencies`. Use
+  `pip install specfact-cli[contracts]` for CrossHair + Hypothesis, or `pip install specfact-cli[dev]`
+  for contributors. `packaging` is pinned explicitly for module installer / PEP 440 use.
+- **Smart-test baseline fallback**: incremental smart-test runs now establish a full-suite baseline when
+  no `last_full_run` cache exists (avoids a no-op incremental pass and misleading zero coverage).
+- **Pre-commit single-invocation overwrite handling**: staged Python files are passed to the code-review
+  helper in one batch so `.specfact/code-review.json` is not overwritten by multiple `xargs` processes.
+
+### Fixed
+
+- Missing bundle UX: when workflow bundles are not installed, the CLI now reports the
+  **marketplace module** (e.g. `nold-ai/specfact-codebase` for the `code` group) instead of
+  `Command 'code' is not installed`, which was easy to confuse with the VS Code `code` CLI.
+
+- Generated GitHub workflow (`resources/templates/github-action.yml.j2`): GitHub Actions `if`
+  conditions now use `${{ … }}` so annotations, PR comment, and fail steps evaluate correctly
+  on GitHub (avoids mixed `always() &&` / raw expression parsing issues).
+
+---
+
 ## [0.44.0] - 2026-03-31
 
 ### Added

README.md

@@ -71,26 +71,40 @@ With SpecFact, you get:
 
 ## How do I get started?
 
-### Start Here (5 minutes)
+### Start Here (about 2 minutes): scored code review — no `pip install`
 
-### Install
+**Point SpecFact at your code.** From a **git repository** (any branch), run two commands:
 
 ```bash
-# Zero-install (recommended)
-uvx specfact-cli@latest
-
-# Or install globally
-pip install -U specfact-cli
+uvx specfact-cli init --profile solo-developer
+uvx specfact-cli code review run --path . --scope full
 ```
 
-### Bootstrap
+You should see a **Verdict** (PASS/FAIL), a **Score**, and categorized **findings** — the fastest way to see SpecFact on real code before you dive into backlog, specs, or CI.
+
+- **Command 1** installs the `solo-developer` bundles (including `specfact-codebase` and `specfact-code-review`) into your user module store so `code review` and related commands are available on the next invocation.
+- **Command 2** runs the clean-code review on the repo at `.`. Use **`--scope full`** on the first run so review does not depend on having local git changes.
+
+**Already installed the CLI?** Use the same flow with `specfact` instead of `uvx specfact-cli`:
 
 ```bash
-# Recommended first run
 specfact init --profile solo-developer
+specfact code review run --path . --scope full
 ```
 
-### Get First Value
+**Read the canonical walkthrough:** **[Documentation — Quickstart](https://docs.specfact.io/getting-started/quickstart/)** · **[Installation](https://docs.specfact.io/getting-started/installation/)** (uvx-first, then persistent install).
+
+### Install (persistent CLI for daily use)
+
+```bash
+pip install -U specfact-cli
+```
+
+You can still use **`uvx specfact-cli@latest ...`** anytime without installing; it always fetches the latest published CLI.
+
+### After the wow path: deeper workflows
+
+When you want analysis, snapshots, or sidecar validation on top of the review layer:
 
 ```bash
 # Analyze a codebase you care about
@@ -104,10 +118,7 @@ specfact code validate sidecar init my-project /path/to/repo
 specfact code validate sidecar run my-project /path/to/repo
 ```
 
-That path gives you a concrete first win: SpecFact understands your project context and gives you a
-validated starting point instead of jumping straight into blind change work.
-
-### AI IDE Setup
+### AI IDE setup
 
 ```bash
 specfact init ide
@@ -125,7 +136,7 @@ your IDE. If module prompt payloads are not installed yet, the CLI uses packaged
 Use SpecFact as the validation layer around fast-moving implementation work.
 
 Start with:
-- `specfact init --profile solo-developer`
+- `uvx specfact-cli init --profile solo-developer` then `uvx specfact-cli code review run --path . --scope full` (see **Start Here** above)
 - `specfact code validate sidecar init <bundle> /path/to/repo`
 - `specfact code validate sidecar run <bundle> /path/to/repo`
 
@@ -303,10 +314,11 @@ Use `https://modules.specfact.io/` for the in-depth backlog, project, spec, gove
 
 ## How It Works (High Level)
 
-1. **Bootstrap**: install the CLI and initialize the official bundles you need.
-2. **Analyze or sync**: import code, connect backlog systems, or sync external artifacts into project bundles.
-3. **Validate**: run spec, governance, and sidecar validation flows before implementation or release.
-4. **Iterate safely**: use module-provided workflows while the core runtime keeps command mounting, trust, and lifecycle consistent.
+1. **Bootstrap**: use **uvx** or **pip**, then `init --profile` to install the bundles you need (for example `solo-developer` for a scored **code review** first).
+2. **Review or analyze**: run **`code review run`** on a repo, or import code and snapshot state for deeper workflows.
+3. **Sync**: connect backlog systems or sync external artifacts into project bundles when you are ready.
+4. **Validate**: run spec, governance, and sidecar validation flows before implementation or release.
+5. **Iterate safely**: use module-provided workflows while the core runtime keeps command mounting, trust, and lifecycle consistent.
 
 ## Where SpecFact Fits
 

docs/getting-started/installation.md

@@ -9,27 +9,25 @@ expertise_level: [beginner]
 
 # Getting Started with SpecFact CLI
 
-This guide will help you get started with SpecFact CLI in under 60 seconds.
+This guide will help you get started with SpecFact CLI in under 60 seconds — first with **no install** (uvx), then with a **persistent** install (pip) when you want IDE workflows and a stable `specfact` command.
 
-> **Primary Use Case**: SpecFact CLI is designed for **brownfield code modernization** - reverse-engineering existing codebases into documented specs with runtime contract enforcement. See [First Steps](quickstart.md) for brownfield workflows.
+> **Primary use case**: brownfield code modernization — reverse-engineering existing codebases into documented specs with runtime contract enforcement. See the [5-Minute Quickstart](quickstart.md) for a full walkthrough.
 
-## Installation
+## Try it now — no install required
 
-### Option 1: uvx (CLI-only Mode)
-
-No installation required - run directly:
+Run SpecFact from PyPI without installing into your environment:
 
 ```bash
-uvx specfact-cli@latest --help
+cd /path/to/your/git/repo
+uvx specfact-cli init --profile solo-developer
+uvx specfact-cli code review run --path . --scope full
 ```
 
-**Best for**: Quick testing, CI/CD, one-off commands
+You should see a **Verdict**, a **Score**, and a list of findings. That is the fastest way to validate SpecFact on real code. [Read the full quickstart →](quickstart.md)
 
-**Limitations**: CLI-only mode uses deterministic local analysis and may show limited results for very small test cases. If you want IDE slash-command workflows with your own AI copilot, use the installed CLI setup in Option 2.
+## Install for persistent use
 
-### Option 2: pip (Installed CLI + IDE Prompt Mode)
-
-**Required for**: local `specfact` command availability, IDE integration, and slash-command workflows
+Use pip when you want a local `specfact` command, IDE integration, and slash-command workflows.
 
 ```bash
 # System-wide
@@ -68,23 +66,21 @@ specfact init --install all
 Then set up IDE integration:
 
 ```bash
-# Initialize IDE integration (one-time per project)
 specfact init ide
-
-# Or specify IDE explicitly
 specfact init ide --ide cursor
 specfact init ide --ide vscode
-
-# Install required packages for contract enhancement
 specfact init ide --install-deps
-
-# Initialize for specific IDE and install dependencies
 specfact init ide --ide cursor --install-deps
 ```
 
 **Important**: SpecFact CLI does **not** ship with built-in AI. `specfact init ide` installs prompt templates for supported IDEs so your chosen AI copilot can call SpecFact commands in a guided workflow.
 
-### Option 3: Container
+[More options ↓](#more-options)
+
+## More options
+{: #more-options}
+
+### Container
 
 ```bash
 # Docker
@@ -94,7 +90,7 @@ docker run --rm -v $(pwd):/workspace ghcr.io/nold-ai/specfact-cli:latest --help
 podman run --rm -v $(pwd):/workspace ghcr.io/nold-ai/specfact-cli:latest --help
 ```
 
-### Option 4: GitHub Action
+### GitHub Action
 
 Create `.github/workflows/specfact.yml`:
 
@@ -212,7 +208,7 @@ Profile outcomes:
 
 | Profile | Installed bundles | Available groups |
 |---|---|---|
-| `solo-developer` | `specfact-codebase` | `code` |
+| `solo-developer` | `specfact-codebase`, `specfact-code-review` | `code` |
 | `backlog-team` | `specfact-project`, `specfact-backlog`, `specfact-codebase` | `project`, `backlog`, `code` |
 | `api-first-team` | `specfact-spec`, `specfact-codebase` (+`specfact-project` dependency) | `project`, `code`, `spec` |
 | `enterprise-full-stack` | all five bundles | `project`, `backlog`, `code`, `spec`, `govern` |

docs/getting-started/quickstart.md

@@ -4,71 +4,72 @@ title: 5-Minute Quickstart
 permalink: /getting-started/quickstart/
 redirect_from:
   - /getting-started/first-steps/
-description: Get SpecFact CLI running in under 5 minutes - install, bootstrap, and analyze your first codebase.
-keywords: [quickstart, first-run, bootstrap, analysis]
+description: Get SpecFact CLI running in under 5 minutes — uvx first, then optional pip install for IDE workflows and deeper analysis.
+keywords: [quickstart, first-run, bootstrap, analysis, uvx]
 audience: [solo, team]
 expertise_level: [beginner]
 doc_owner: specfact-cli
 tracks:
   - src/specfact_cli/**
   - openspec/**
-last_reviewed: 2026-03-29
+last_reviewed: 2026-04-02
 exempt: false
 exempt_reason: ""
 ---
 
 # 5-Minute Quickstart
 
-Get from zero to your first SpecFact analysis in under 5 minutes.
+Get from zero to a **scored code review** in a few commands. This path is aimed at developers who want one command and one clear result before reading about modules, profiles, or architecture.
 
 ## Prerequisites
 
 - Python 3.11+ (`python3 --version`)
 - A Git repository to analyze (or create a test project)
 
-## Step 1: Install
+## Step 1: Bootstrap with uvx (no pip install)
+
+From your repo root:
 
 ```bash
-pip install specfact-cli
+uvx specfact-cli init --profile solo-developer
 ```
 
-Or try without installing: `uvx specfact-cli@latest --help`
+This installs the workflow bundles for the solo-developer profile (including the code-review module). See [specfact init](/core-cli/init/) for other profiles.
 
-## Step 2: Bootstrap
+## Step 2: Run a scored code review
 
 ```bash
-# Navigate to your project
-cd /path/to/your/project
-
-# Initialize with a profile
-specfact init --profile solo-developer
+uvx specfact-cli code review run --path . --scope full
 ```
 
-This installs the default set of workflow bundles. See [specfact init](/core-cli/init/) for other profiles.
+You should see a **Verdict**, **Score**, and findings. That is the fastest “aha” path on a real codebase.
+
+## Step 3: Install SpecFact locally (optional)
 
-## Step 3: Set Up IDE (Optional)
+When you want a stable `specfact` command and IDE integration, install with pip:
 
 ```bash
-specfact init ide --ide cursor --install-deps
+pip install specfact-cli
+cd /path/to/your/project
+specfact init --profile solo-developer
 ```
 
-This creates `.specfact/` directory structure and IDE-specific prompt templates.
-
-## Step 4: Analyze Your Codebase
+## Step 4: Set Up IDE (Optional)
 
 ```bash
-specfact code import my-project --repo .
+specfact init ide --ide cursor --install-deps
 ```
 
-SpecFact analyzes your code and extracts features, user stories, and dependency graphs into a project bundle at `.specfact/projects/my-project/`.
+This creates `.specfact/` directory structure and IDE-specific prompt templates.
 
-## Step 5: Check Project Health
+## Step 5: Analyze Your Codebase and Check Health
 
 ```bash
+specfact code import my-project --repo .
 specfact project health-check
 ```
 
-Review what SpecFact discovered about your codebase.
+`code import` analyzes your code and extracts features, user stories, and dependency graphs into a project bundle at `.specfact/projects/my-project/`. `project health-check` summarizes what SpecFact discovered.
 
 ## Step 6: Validate