diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
index eddca42..75f12b7 100644
--- a/.claude/CLAUDE.md
+++ b/.claude/CLAUDE.md
@@ -74,6 +74,24 @@ DUCKDB_PATH=local.duckdb SERVING_DUCKDB_PATH=analytics.duckdb \
 
 ```
 
+## Production queries
+
+Use `scripts/prod_query.py` to query the production DuckDB over SSH. **Always prefer this over raw SSH commands** — it handles escaping, enforces read-only, and blocks mutation keywords.
+
+```bash
+# Query analytics.duckdb (serving tables — default)
+uv run python scripts/prod_query.py "SELECT COUNT(*) FROM serving.location_profiles"
+
+# Query lakehouse.duckdb (foundation/staging tables)
+uv run python scripts/prod_query.py --db lakehouse "SELECT * FROM foundation.dim_countries LIMIT 5"
+
+# JSON output
+uv run python scripts/prod_query.py --json "SELECT COUNT(*) FROM serving.location_profiles"
+
+# Limit rows (default 500)
+uv run python scripts/prod_query.py --max-rows 1000 "SELECT ..."
+```
+
 ## Architecture documentation
 
 | Topic | File |