Add DEBUG instrumentation and documentation

AGENTS.md

@@ -110,6 +110,14 @@ CREATE INDEX idx_artists_name_nocase ON artists(name COLLATE NOCASE);
 - `createPagination` – Standard pagination controls with page size selector.
 - `Keyboard` helper – Normalizes Enter/Esc handling for list rows and overlays.
 - `createAsyncListState` – Manages loading, error, and empty states for async lists.
+- `prepareForView` – Wraps `db.prepare` to attach view/label metadata for logging.
+- `normalizePaginationState` / `clampPaginationToTotal` – Normalizes and clamps pagination inputs while emitting DEBUG telemetry.
+
+## Debugging & Logging
+- Runtime diagnostics are gated behind a localStorage flag. Enable with `localStorage.setItem('mp3com.debug', 'true')` (or `'false'`/`removeItem` to disable) before reloading the app.
+- When DEBUG is on, every SQLite statement logs `Query begin`/`Query end` entries (with view, SQL, params, row count, and duration) and captures detailed error payloads before rethrowing.
+- Pagination helpers emit `[Pagination]` logs whenever raw inputs are normalized or clamped (including `clampedToTotal` flags when high page numbers are corrected after a count query).
+- Use `prepareForView(db, VIEW_NAMES.someView, sql, label)` so statement metadata matches the originating view; this keeps console traces actionable.
 
 ## View Status
 - [x] Navigation hub (`tpl-nav`, `createNavView`).