# NFL Picks Local Development

This repo is safe to run in fixture mode without live API secrets.

## Modes

- `fixture`: default local mode. Uses checked-in mock data and does not require secrets.
- `sample`: reserved for sanitized provider samples and does not require secrets.
- `live_no_call`: online-prep mode. Validates live wiring/readiness while provider calls remain disabled.
- `live`: future mode for approved providers only. Do not enable until provider/API decisions are approved and quota is available.

Use `.env.example` as the reference shape for local environment variables. Never commit real keys.
Use `docs/PROVIDER_DECISIONS.md` to record provider approvals before adding live adapters.
When Odds API quota is exhausted, keep `NFL_PICKS_MODE=live_no_call` or `fixture`.

## Core Commands

Run tests:

```powershell
python -m pytest -q
```

Build all fixture artifacts:

```powershell
python run_build_all.py --output-dir docs\mock --results-csv docs\mock\sample_results.csv
```

Run the sanitized sample-baseline slate without live provider calls:

```powershell
python run_mock.py --mode sample --output-dir docs\mock\sample_baseline
```

Validate generated artifacts:

```powershell
python run_validate_artifacts.py --base-dir docs\mock
```

Run the full local quality gate:

```powershell
python run_quality_gate.py
```

Run the secret scan directly:

```powershell
python run_secret_scan.py
```

## Expected Generated Outputs

- `docs/mock/index.html`
- `docs/mock/report_summary.json`
- `docs/mock/mock_slate_results.json`
- `docs/mock/tracker.csv`
- `docs/mock/audit.json`
- `docs/mock/sample_baseline/`
- `docs/mock/settled_tracker.csv`
- `docs/mock/backtest_summary.json`
- `docs/mock/market_health.json`
- `docs/mock/market_health.html`
- `docs/mock/run_manifest.json`
- `docs/mock/build_summary.md`
- `docs/mock/release_notes.md`
- `docs/mock/artifact_index.json`
- `docs/mock/release_bundle.json`
- `docs/mock/live_readiness.json`
- `docs/mock/live_readiness.html`
- `docs/mock/live_enablement_checklist.json`
- `docs/mock/live_enablement_checklist.html`
- `docs/mock/provider_dry_run.json`
- `docs/mock/provider_dry_run.html`
- `docs/mock/provider_sample_request.json`
- `docs/mock/provider_sample_request.html`
- `docs/mock/provider_sample_intake.json`
- `docs/mock/provider_sample_intake.html`
- `docs/mock/provider_sample_validation.json`
- `docs/mock/provider_sample_validation.html`
- `docs/mock/provider_sample_redaction_audit.json`
- `docs/mock/provider_sample_redaction_audit.html`
- `docs/mock/provider_sample_review_summary.json`
- `docs/mock/provider_sample_review_summary.html`
- `docs/mock/provider_sample_collection_packet.md`
- `docs/mock/network_guard_audit.json`
- `docs/mock/network_guard_audit.html`
- `docs/mock/runtime_mode_matrix.json`
- `docs/mock/runtime_mode_matrix.html`
- `docs/site_map.json`

## Release Safety

Before handoff or publish, run the full quality gate and confirm:

- tests pass
- artifacts validate
- release bundle reports ready
- live readiness keeps provider calls disabled unless `live` is explicitly valid
- live enablement checklist keeps online prep ready while live calls remain blocked
- provider sample request remains credential-free and live-disabled
- provider sample intake lists only approved-sample collection actions
- provider sample validation reports missing or invalid sanitized sample files without requiring credentials
- provider sample redaction audit has zero findings
- provider sample review summary points to the next safe provider-sample action
- provider sample collection packet remains copy-ready and live-disabled
- network guard audit has zero direct provider-call findings
- runtime mode matrix shows `live_no_call` as the default safe mode
- no live provider secrets are committed
- product copy avoids guarantee and lock language