Polish README and docs

Author: Euan MacIntyre

README.md

@@ -1,50 +1,63 @@
-# econ_crime_monitoring_lab
+# Economic Crime Monitoring Lab
 
-Synthetic-only economic crime monitoring lab for local demo and interview use.
-The project simulates a fraud + AML monitoring stack end-to-end: synthetic transaction generation, controls, rules + ML scoring, alerting, case simulation, MI reporting, and investigator dashboarding.
+[![CI](https://github.com/<OWNER>/economic-crime-monitoring-lab/actions/workflows/ci.yml/badge.svg)](https://github.com/<OWNER>/economic-crime-monitoring-lab/actions/workflows/ci.yml)
 
-## Quick Start (macOS, ~2 minutes)
+Synthetic transaction monitoring pipeline with alerting, management information (MI), and a dashboard. All data in this repository is synthetic, and the project is for defensive analytics only.
+
+## What it does
+
+The pipeline generates synthetic customer, account, and transaction data; runs data quality checks; engineers monitoring features; applies rules and a baseline model; creates an alert queue and case records; produces weekly MI outputs; and serves a Streamlit dashboard for review.
+
+## Quickstart (macOS)
 
 ```bash
 make install
 make run
 make dashboard
 ```
 
-What happens:
-- `make run` creates outputs in local folders only:
-  - `data/econ_crime_lab.db`
-  - `reports/YYYY-MM-DD/mi_report.md`
-  - `reports/YYYY-MM-DD/mi_report.html`
-- `make dashboard` starts Streamlit and loads data from SQLite.
+`make dashboard` starts the app at `http://localhost:8501`. Generated outputs are written locally and are not committed to the repository.
 
-## Synthetic Data & Repo Hygiene
+## Outputs
 
-- All data is synthetic. No real customer data is used.
-- Generated outputs are intentionally ignored by git (`.db`, CSV outputs, reports, caches).
-- To reset local outputs and caches:
+- Default SQLite database: `data/econ_crime_lab.db`
+- Reports directory: `reports/YYYY-MM-DD/`
+- Key tables:
+  - `customers`
+  - `accounts`
+  - `transactions`
+  - `alerts`
+  - `cases`
+  - `mi_weekly`
+  - `model_metrics` (if present)
 
-```bash
-make clean
-```
-
-## What This Demonstrates (Economic Crime Data)
+## How this maps to Economic Crime (Data)
 
-- Monitoring controls: schema validation, data quality checks, and run metadata.
-- Management information (MI): weekly alert volumes, outcomes, and handling metrics.
-- Alert explainability: rule hit context, model feature contributions, and investigator notes.
+- Controls and monitoring: rule-based controls, alert volume/rate monitoring, and false-positive review.
+- MI: weekly reporting outputs and trend tracking for alerts and case outcomes.
+- Governance: reproducible runs, logged assumptions and run metadata, and data quality checks.
+- Threat awareness: simulated typologies (for example structuring-style behavior and unusual movement patterns) support pattern spotting and triage practice.
 
-## Common Commands
+## Repository layout
 
-```bash
-make install
-make run
-make dashboard
-make test
-make lint
-make clean
+```text
+scripts/    # pipeline and utility entry points
+src/        # econ_crime_monitoring_lab package
+tests/      # automated tests
+data/       # local synthetic data outputs
+reports/    # dated MI outputs
 ```
 
-## Architecture
+## Notes and limitations
+
+- Synthetic data only.
+- This is not a fraud playbook.
+- The baseline model is illustrative.
+- This is a learning project and not production monitoring.
+
+## Screenshots
+
+![Dashboard screenshot](docs/dashboard.png)
+![Alert detail screenshot](docs/alert_detail.png)
 
-See `docs/architecture.md` for a mermaid system overview.
+Add screenshots by saving images into `docs/` with those names.