Add SQLite quick-reference runbook for operations

README.md

@@ -435,6 +435,7 @@ Audio persistence and diagnostics:
 - To clear one session manually: `DELETE FROM session_config WHERE session_id='<channel:sender>' AND key='lastAudioAttachment'`.
 - When Flynn rewrites bad model-provided audio tool args, it emits audit event `tool.args_rewritten`.
 - Runbook: `docs/runbooks/VOICE_TRANSCRIPTION_DEBUG.md`.
+- SQLite quick reference: `docs/runbooks/SQLITE_QUICK_REFERENCE.md`.
 
 ### Text-to-Speech (TTS) Reply Audio
 

docs/plans/state.json

@@ -6052,6 +6052,18 @@
         "docs/runbooks/VOICE_TRANSCRIPTION_DEBUG.md"
       ],
       "test_status": "docs-only update; no runtime code changes"
+    },
+    "audit-followup-sqlite-quick-reference-runbook": {
+      "status": "completed",
+      "date": "2026-02-23",
+      "updated": "2026-02-23",
+      "summary": "Added a SQLite quick-reference runbook with high-utility operational queries for session history, session_config, tool execution diagnostics, pairing approvals, and safe backup/cleanup workflows.",
+      "files_modified": [
+        "docs/runbooks/SQLITE_QUICK_REFERENCE.md",
+        "docs/runbooks/VOICE_TRANSCRIPTION_DEBUG.md",
+        "README.md"
+      ],
+      "test_status": "docs-only update; no runtime code changes"
     }
   },
   "overall_progress": {

docs/runbooks/SQLITE_QUICK_REFERENCE.md

@@ -0,0 +1,102 @@
+# SQLite Quick Reference (Flynn)
+
+Operational SQLite queries for fast debugging and cache management.
+
+## Setup
+
+```bash
+DB=~/.local/share/flynn/sessions.db
+SID='telegram:8367012007'   # change per session
+```
+
+## 1) DB Health / Introspection
+
+```bash
+sqlite3 "$DB" ".tables"
+sqlite3 "$DB" ".schema"
+```
+
+## 2) Global Row Counts
+
+```bash
+sqlite3 "$DB" "SELECT 'messages',COUNT(*) FROM messages
+UNION ALL SELECT 'session_config',COUNT(*) FROM session_config
+UNION ALL SELECT 'tool_executions',COUNT(*) FROM tool_executions;"
+```
+
+## 3) Most Recent Active Sessions
+
+```bash
+sqlite3 "$DB" "SELECT session_id, datetime(MAX(created_at),'unixepoch','localtime') AS last_seen, COUNT(*) AS msg_count
+FROM messages GROUP BY session_id ORDER BY MAX(created_at) DESC LIMIT 20;"
+```
+
+## 4) Recent Messages for One Session
+
+```bash
+sqlite3 "$DB" "SELECT id, role, datetime(created_at,'unixepoch','localtime') AS ts, substr(content,1,200)
+FROM messages WHERE session_id='$SID' ORDER BY id DESC LIMIT 30;"
+```
+
+## 5) Search Message History by Text
+
+```bash
+sqlite3 "$DB" "SELECT session_id,id,role,datetime(created_at,'unixepoch','localtime')
+FROM messages WHERE content LIKE '%audio.transcribe%' ORDER BY id DESC LIMIT 50;"
+```
+
+## 6) List Session Config Keys
+
+```bash
+sqlite3 "$DB" "SELECT key, length(value) FROM session_config WHERE session_id='$SID' ORDER BY key;"
+```
+
+## 7) Inspect Cached Audio Across Sessions
+
+```bash
+sqlite3 "$DB" "SELECT session_id, key, length(value) FROM session_config WHERE key='lastAudioAttachment';"
+```
+
+## 8) Clear One Session's Cached Audio
+
+```bash
+sqlite3 "$DB" "DELETE FROM session_config WHERE session_id='$SID' AND key='lastAudioAttachment';"
+```
+
+Verify:
+
+```bash
+sqlite3 "$DB" "SELECT session_id, key, length(value) FROM session_config WHERE key='lastAudioAttachment';"
+```
+
+## 9) Tool Success/Failure Summary
+
+```bash
+sqlite3 "$DB" "SELECT tool_name, SUM(success=1) AS ok, SUM(success=0) AS fail, COUNT(*) AS total
+FROM tool_executions GROUP BY tool_name ORDER BY total DESC;"
+```
+
+## 10) Recent Tool Failures for One Session
+
+```bash
+sqlite3 "$DB" "SELECT id, tool_name, datetime(created_at,'unixepoch','localtime') AS ts
+FROM tool_executions WHERE session_id='$SID' AND success=0 ORDER BY id DESC LIMIT 50;"
+```
+
+## 11) Pairing Approvals
+
+```bash
+sqlite3 "$DB" "SELECT channel, sender_id, datetime(approved_at,'unixepoch','localtime')
+FROM pairing_approved ORDER BY approved_at DESC;"
+```
+
+## 12) Safety Backup Before Manual Edits
+
+```bash
+sqlite3 "$DB" ".backup '/tmp/flynn-sessions.backup.db'"
+```
+
+## Notes
+
+- `/reset` in a chat clears that session's messages/config/tool rows, including `lastAudioAttachment`.
+- Prefer deleting one key for one session over broad deletes.

docs/runbooks/VOICE_TRANSCRIPTION_DEBUG.md

@@ -105,3 +105,6 @@ If `/reset` is run in that chat, it also clears the session's `lastAudioAttachme
 
 - `session.clear()` (e.g. `/reset`) removes messages, tool executions, and session config for that session.
 - Session TTL pruning removes stale sessions and associated config from SQLite.
+
+For additional operational queries (sessions, tools, pairing, backups), see:
+- `docs/runbooks/SQLITE_QUICK_REFERENCE.md`