docs: clarify safe local verification commands

AGENTS.md

@@ -18,22 +18,32 @@ The current machine-readable truth surface is `output/portfolio-truth-latest.jso
 
 ## How To Run
 
-Refresh and verify the local portfolio truth snapshot:
+For repository verification, start with the credential-free fixture commands in
+[CONTRIBUTING.md](CONTRIBUTING.md). That guide is authoritative for environment
+extras, focused/broader tests and conditional browser checks. The full semantic
+lane and operator workflows are separate from the lightweight fixture baseline.
+
+The following commands are deliberate operator work: they scan the configured
+local projects workspace and regenerate canonical/compatibility outputs. Do not
+use them as a smoke test or run them to verify documentation changes.
+
+Refresh and verify the local portfolio truth snapshot only when requested:
 
 ```sh
 uv run python -m github_repo_auditor.cli report saagpatel --portfolio-truth
 jq '{generated_at,total:(.projects|length),counts:.source_summary.attention_state_counts}' output/portfolio-truth-latest.json
 uv run operator-os-seam-linter --truth output/portfolio-truth-latest.json --json
 ```
 
-Useful checks for repo changes:
+For a focused repository check, use the locked fixture baseline:
 
 ```sh
-uv run ruff check .
-uv run pytest -q
+uv run --locked --extra dev ruff check src/ tests/
+uv run --locked --extra dev --extra serve --extra config pytest tests/test_scorer.py -q -p no:cacheprovider
 ```
 
-Use narrower tests when the change is scoped and the full suite would be disproportionate.
+Select the focused test file for the changed module; use CONTRIBUTING.md for
+broader checks and the optional semantic environment that full CI requires.
 
 The seam-linter checks truth freshness, schema pinning, and generated Markdown
 provenance markers. Its identity-resolution check is opt-in:

CHANGELOG.md

@@ -13,6 +13,8 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ## [Unreleased]
 
+- Clarify locked contributor setup, optional test dependencies, and credential-free fixture verification without workstation discovery.
+
 ### Added
 - Added the local-only `audit pr-evidence <snapshot.json>` operator path with
   strict `PRHeadEvidenceV1` input validation and deterministic

CONTRIBUTING.md

@@ -2,74 +2,90 @@
 
 Thank you for your interest in contributing. This guide covers how to set up a local development environment, run tests, follow coding conventions, add a new analyzer, and submit a pull request.
 
-## Prerequisites
+## Prerequisites and local setup
 
-- **Python 3.11 or later** — the codebase uses `match` statements, `X | Y` union syntax, and other 3.11+ features.
-- **A GitHub Personal Access Token** — optional for public-only audits, but useful for private repos, organization metadata, and higher rate limits. Create one at <https://github.com/settings/tokens> with the narrowest scopes needed for the audit you plan to run.
-- **Git** — standard installation, used for shallow cloning during audits.
-
-## Local Setup
+Use Git, `uv`, and Python 3.11 or later. The checked-in `.python-version` selects
+3.11.15 for the locked local/Cloud environment. Run commands from the repository
+root; `uv` creates a project virtual environment and can download the selected
+interpreter and dependencies during setup. No GitHub, Anthropic, or Notion token
+is needed for the fixture checks below. Do not copy credential-bearing `.env`
+files into a verification checkout.
 
 ```bash
-# Clone the repo
 git clone https://github.com/<your-fork>/GithubRepoAuditor.git
 cd GithubRepoAuditor
-
-# Install all runtime + dev dependencies
-make install-dev
-
-# Copy the environment template if you need authenticated audit runs
-cp .env.example .env
-# Edit .env and set GITHUB_TOKEN=<your token>
+uv sync --locked --extra dev --extra serve --extra config
 ```
 
-If you do not use `make`, the equivalent pip command is:
-
-```bash
-python3 -m pip install -e ".[dev,config]"
-```
+The `serve` extra is needed by web-route tests. `semantic` adds heavyweight ML
+and SQLite vector dependencies and remains opt-in for routine local checks.
+The older `make install-dev` / pip equivalent installs only `dev,config`, so it
+does not provision the full CI test environment.
 
-## Running Tests
+## Safe smoke and focused tests
 
 ```bash
-make test
+uv run --locked python -m github_repo_auditor.cli --help
+uv run --locked --extra dev --extra serve --extra config pytest tests/test_scorer.py -q -p no:cacheprovider
 ```
 
-This runs the full test suite under `tests/` with verbose output. The suite covers all 12 analyzers, the scorer, the report generator, the GitHub API client, and the CLI integration.
+The scorer tests use synthetic metadata and block live scorecard lookup. Replace
+the test path with the focused fixture tests for your changed module after
+checking their prerequisites. CLI help is not a live audit.
 
-To run a single test file:
+For report/export changes, generate the committed demo in a disposable checkout:
 
 ```bash
-python3 -m pytest tests/test_scorer.py -v
+uv run --locked --extra config python scripts/build_demo_artifacts.py
 ```
 
-To run tests matching a pattern:
+This uses `fixtures/demo/sample-report.json` and regenerates only `output/demo/`,
+including replacement of older demo artifacts. It does not audit the workstation
+or contact provider accounts. Live `audit run`, portfolio-truth regeneration,
+seam identity-resolution, writeback, and deployment commands belong to explicit
+operator tasks, not a fixture verification pass.
 
-```bash
-python3 -m pytest tests/ -k "readme" -v
-```
+## Broader checks and optional lanes
 
-## Linting and Formatting
+The lightweight local/Cloud suite excludes the optional semantic-index module:
 
 ```bash
-# Check for lint errors (does not modify files)
-make lint
-
-# Auto-format source and test files
-make format
+uv run --locked --extra dev --extra serve --extra config pytest tests/ -q -p no:cacheprovider -k 'not semantic_index'
+uv run --locked --extra dev ruff check src/ tests/
+uv run --locked --extra dev ruff format --check src/ tests/
 ```
 
-Both commands target `src/` and `tests/`. The project uses [Ruff](https://docs.astral.sh/ruff/) configured in `pyproject.toml` with `target-version = "py311"` and `line-length = 100`. Rules `E`, `F`, and `I` (errors, pyflakes, isort) are enabled.
-
-CI will reject PRs that fail `ruff check`. Run `make lint` before opening a PR.
+`ruff format --check` is read-only; omit `--check` only when deliberately
+formatting source. Ruff's actual settings are in `pyproject.toml`.
 
-## Type Checking
+[GitHub CI](.github/workflows/ci.yml) runs the full suite with `dev,serve,semantic`
+on Python 3.11 and 3.12. To reproduce that lane locally, include the semantic
+extra explicitly:
 
 ```bash
-make type-check
+uv run --locked --extra dev --extra serve --extra semantic --extra config pytest tests/ -q -p no:cacheprovider
 ```
 
-This runs `mypy src/ --ignore-missing-imports`. All new functions must have complete type annotations — no `Any` usage, no untyped parameters.
+CI type-checks the operator-trend modules listed in that workflow. The broader
+`make type-check` target runs `mypy src/ --ignore-missing-imports`; it is a
+separate whole-source diagnostic, not a claim that CI checks every module.
+For wheel/sdist packaging, install the `build` extra and run
+`uv run --locked --extra build python -m build`; this writes local `dist/`
+artifacts and does not publish them. Mutation testing, workbook checks and
+release-specific prerequisites remain in
+[docs/release-gates.md](docs/release-gates.md), including the mutation lane's
+Python 3.13 requirement.
+
+## Conditional UI and report verification
+
+When HTML/report presentation changes, open the generated
+`output/demo/dashboard-*.html` and inspect the changed views with synthetic data.
+For serve changes, run the fixture route tests in `tests/test_serve.py` with the
+`serve` extra and follow [the web UI guide](docs/audit-serve.md) using
+`output/demo/`. Do not start a live audit or submit provider/writeback actions to
+check a UI change. Browser checks are conditional on changed presentation or
+interaction; a documentation-only PR does not require them. Synthetic output
+and route tests do not establish production or human acceptance.
 
 ## Coding Conventions
 

README.md

@@ -324,31 +324,16 @@ For a full description of all flags grouped by workflow, see
 
 ### Run tests
 
-```bash
-pytest
-```
+Use the [contributor verification lanes](CONTRIBUTING.md#safe-smoke-and-focused-tests)
+for the focused fixture check and broader suites with their required extras.
 
 ## Development
 
-For local development, clone the repo and install with the dev + config extras:
-
-```bash
-git clone https://github.com/saagpatel/GithubRepoAuditor.git
-cd GithubRepoAuditor
-pip install -e ".[dev,serve,semantic,config]"
-```
-
-Common dev commands:
-
-```bash
-python3 -m pytest -q -p no:cacheprovider   # full test suite
-python3 -m ruff check src/ tests/          # lint
-python3 -m ruff format src/ tests/         # format
-make workbook-gate                         # workbook invariant check
-make release-gate                          # mutation testing gate
-```
-
-See [docs/release-gates.md](docs/release-gates.md) for the full gate checklist.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the locked local environment, safe
+fixture smoke, focused and broader test lanes, lint/format/typecheck/build
+commands, optional semantic prerequisites, and conditional UI/report checks.
+Live audits and portfolio-truth regeneration are operator workflows, not test
+smokes. [docs/release-gates.md](docs/release-gates.md) retains the release gates.
 
 ## Tech Stack