initial code

README.md

@@ -1,3 +1,127 @@
 # SummerProject2026
 
-Kevin Bell's summer 2026 project
+Kevin Bell's summer 2026 data project using Utah county vehicle-registration
+and emissions-inspection data.
+
+See the [data inventory](docs/data_inventory.md) and the data-backed
+[project shortlist](docs/project_options.md).
+
+## Selected project
+
+The selected direction is **Utah Vehicle Health**, an explainable model and
+dashboard for the first-attempt outcome of a vehicle's next inspection episode.
+Start with the [project charter](docs/project_charter.md), then use the
+[modeling protocol](docs/modeling_protocol.md) and
+[dashboard specification](docs/dashboard_spec.md) as the project contracts.
+The latest private-sample pipeline findings are summarized in
+[development results](docs/development_results.md), with intended use and
+limitations consolidated in the [model card](docs/model_card.md).
+
+## Safe database access in VS Code
+
+The local `.env` file contains the standard PostgreSQL connection variables and
+is intentionally excluded from Git. Never put those values in source code,
+screenshots, browser JavaScript, or a Bolt project.
+
+1. Install the workspace-recommended **PostgreSQL** extension by Microsoft
+   (`ms-ossdata.vscode-pgsql`).
+2. In VS Code, run **Tasks: Run Task** and choose
+   **Countydata: test read-only connection**. It loads `.env`, requires TLS, and
+   forces the PostgreSQL session into read-only mode.
+3. To browse the server visually, open the PostgreSQL sidebar and add a
+   connection using the values in `.env`. Set SSL mode to **Require**, save the
+   profile at **User** scope, and store the password in macOS Keychain rather
+   than workspace settings.
+4. Connect to `countydata` and run [sql/00_read_only_connection_check.sql](sql/00_read_only_connection_check.sql).
+   Safe aggregate examples are in [sql/01_safe_data_overview.sql](sql/01_safe_data_overview.sql).
+
+The selected project's first aggregate cohort check is
+[sql/10_episode_cohort_feasibility.sql](sql/10_episode_cohort_feasibility.sql).
+Private bounded extraction is handled by
+[scripts/export_inspection_batch.py](scripts/export_inspection_batch.py); it
+requires the project-specific `VIN_HASH_KEY` described in `.env.example` and
+never writes a raw VIN.
+
+The current database login has write privileges even though this project only
+needs reads. Ask the database administrator for a dedicated read-only role
+before connecting any deployed service. Until then, always use explicit
+read-only transactions.
+
+## Reproducible development workflow
+
+Create the local environment once:
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -r requirements.txt
+.venv/bin/python scripts/create_vin_hash_key.py
+```
+
+The recommended way to run the pipeline is **Tasks: Run Task** in VS Code. The
+tasks preserve the intended order:
+
+1. Test the read-only TLS connection.
+2. Run the source outcome-mapping and aggregate feasibility audits.
+3. Export the private 10,000-vehicle development histories.
+4. Build the private DuckDB warehouse and Parquet feature mart.
+5. Run every test.
+6. Train the baselines while leaving the 2025 test partition locked.
+7. Train the nonlinear comparison while leaving the same partition locked.
+
+The development history sample is deliberately not population-representative.
+It exists to exercise feature engineering and modeling before a complete,
+contiguous bounded extraction is approved. Generated extracts, marts, database
+files, keys, and model artifacts remain under Git-ignored private paths.
+
+The 2025 metrics are not calculated by the normal training task. Unlocking them
+requires the conspicuous `--evaluate-locked` flag after the feature set,
+hyperparameters, calibration method, and reporting plan are frozen.
+That gate was opened once on the page-sampled development extract during live
+verification; the normal artifact paths were then regenerated closed. The
+audit trail is in [development results](docs/development_results.md), and no
+further 2025-informed tuning is permitted.
+
+## Sanitized dashboard preview
+
+After training both closed model bundles, run **Tasks: Run Task** and choose
+**Utah Vehicle Health: export sanitized dashboard preview**. The exporter
+publishes only suppression-reviewed JSON under `dashboard/public/data`; it
+refuses the sampled mart unless the explicit development-preview flag is used
+and refuses model artifacts containing holdout metrics.
+
+Preview the site without exposing the repository root:
+
+```bash
+node dashboard/server.mjs
+```
+
+Then open `http://localhost:4173`. Do not serve the repository root, because it
+contains the local connection profile and private ignored directories.
+
+The checked-in bundle is visibly labeled as a non-population development
+preview. Before a real public-data release, rerun the frozen pipeline on an
+approved complete extraction and pass the publication review documented in
+[the dashboard specification](docs/dashboard_spec.md).
+
+Local and Bolt handoff instructions are in
+[dashboard/README.md](dashboard/README.md). Bolt can import a GitHub repository,
+but the hosted site root must be the `dashboard` directory; never copy `.env`,
+private data, model artifacts, or database tooling into a web project.
+
+## Data safety and publishing
+
+The source contains direct identifiers and operational data, including VINs,
+plates, user records, sessions, and upload metadata. A public dashboard should
+contain only de-identified aggregates and model outputs with minimum group-size
+suppression.
+
+Recommended deployment flow:
+
+```text
+countydata (read-only) -> local ETL/modeling -> sanitized aggregate tables/files
+                                              -> Bolt-hosted dashboard
+```
+
+Do not connect a browser directly to `countydata`. If the dashboard must refresh
+automatically, use a scheduled backend job with a dedicated read-only database
+role and copy only approved aggregate results into the hosted application.