Document SQLite database usage in README.md and CLAUDE.md

CLAUDE.md

@@ -13,7 +13,8 @@ The full SRS (69 FRs, 23 NFRs, 29 SRs with Gherkin acceptance criteria) lives in
 - **Language:** Rust with `#![forbid(unsafe_code)]` (SR-023)
 - **Framework:** Axum (async HTTP/WebSocket)
 - **Runtime:** Tokio
-- **Database:** TimescaleDB (time-series attestation history/metrics)
+- **Database (production):** TimescaleDB (time-series attestation history/metrics)
+- **Database (dev/test):** SQLite via `DATABASE_URL` env var (`sqlite::memory:` or `sqlite://./file.db`); auto-creates schema on startup, optional mock seeding
 - **Cache:** Redis with tiered TTLs (agent list 10s, detail 30s, policies 60s, certs 300s)
 - **Keylime comms:** mTLS via rustls, private keys in HSM/Vault (never cleartext on disk)
 - **Auth:** OIDC/SAML + short-lived JWT (15 min) with refresh rotation
@@ -51,6 +52,20 @@ The mock fleet has 3 agents: healthy (GET_QUOTE), failed (FAILED), and push-mode
 
 Alternatively, open `test-data/verifier.json` and `test-data/registrar.json` in the Mockoon desktop app, start both environments, then run the tests from a terminal. The GUI shows live request logs for debugging.
 
+## SQLite Database
+
+For development and testing, the backend supports SQLite as a lightweight database alternative to TimescaleDB. It is controlled entirely by the `DATABASE_URL` environment variable:
+
+```bash
+DATABASE_URL=sqlite::memory: cargo run       # in-memory (ephemeral)
+DATABASE_URL=sqlite://./keylime-dev.db cargo run  # file-based (persistent)
+cargo run                                    # no database (in-memory repositories)
+```
+
+The schema (alerts, policies, policy_changes, audit_entries, attestation_results, correlated_incidents) is auto-created on startup. When `seed_mock_data = true` is set in the settings file, the alerts table is seeded with sample data on first run.
+
+See [docs/TESTING_WITH_SQLITE.md](docs/TESTING_WITH_SQLITE.md) for the full guide.
+
 ## Architecture
 
 ### System Layers

README.md

@@ -250,6 +250,24 @@ curl -X POST http://localhost:8080/api/auth/logout | jq
 
 The backend reads `KEYLIME_VERIFIER_URL` and `KEYLIME_REGISTRAR_URL` environment variables (defaulting to `http://localhost:3000` and `http://localhost:3001`).
 
+## SQLite Database
+
+The backend supports SQLite as a lightweight database for development and testing, controlled by the `DATABASE_URL` environment variable. When unset, in-memory repositories are used (no database).
+
+```bash
+# In-memory (ephemeral, data lost on restart)
+DATABASE_URL=sqlite::memory: cargo run
+
+# File-based (persists across restarts, auto-created)
+DATABASE_URL=sqlite://./keylime-dev.db cargo run
+```
+
+SQLite stores alerts, policies, policy changes, audit entries, attestation results, and correlated incidents. The schema is auto-created on startup (`CREATE TABLE IF NOT EXISTS`).
+
+When mock data seeding is enabled via the settings file (`seed_mock_data = true`), the alerts table is populated with sample data on first run.
+
+For a complete guide including schema details, type conventions, inspection commands, and limitations vs production Postgres, see [docs/TESTING_WITH_SQLITE.md](docs/TESTING_WITH_SQLITE.md).
+
 ### Mock fleet
 
 The mock data defines a fleet of 7 agents in different states: