From b72452e212ebac37610c8cd10270364f240fef2f Mon Sep 17 00:00:00 2001
From: Travis Vasceannie <travis.vas@gmail.com>
Date: Mon, 12 Jan 2026 00:49:10 +0000
Subject: [PATCH] docs: add client logging guidelines to CLAUDE.md

- Introduced a new section on client logging, emphasizing the use of the `clientlog` system instead of console methods.
- Provided code examples for debug and error logging, as well as direct clientlog access.
- Explained the benefits of structured logging and persistence in localStorage for better analytics.
---
 CLAUDE.md | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 01c82cb..49b5cd2 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -688,6 +688,39 @@ use device::{resolve_input_device, select_input_config};
 - `rustfmt` for formatting
 - `clippy` for linting (warnings treated as errors)
 
+### Client Logging (CRITICAL)
+
+**NEVER use `console.log`, `console.error`, `console.warn`, or `console.debug` in client TypeScript code.**
+
+Always use the `clientlog` system via `client/src/lib/debug.ts` or `client/src/lib/client-logs.ts`:
+
+```typescript
+// For debug logging (controlled by DEBUG flag)
+import { debug } from '@/lib/debug';
+const log = debug('MyComponent');
+log('Something happened', { detail: 'value' });
+
+// For error logging (always outputs)
+import { errorLog } from '@/lib/debug';
+const logError = errorLog('MyComponent');
+logError('Something failed', error);
+
+// For direct clientlog access
+import { addClientLog } from '@/lib/client-logs';
+addClientLog({
+  level: 'info',
+  source: 'app',
+  message: 'Event occurred',
+  details: 'Additional context',
+});
+```
+
+**Why:**
+- `clientlog` persists logs to localStorage for later viewing in Analytics
+- Logs are structured with level, source, timestamp, and metadata
+- Debug logs can be toggled at runtime via `DEBUG=true` in localStorage
+- Console logging is ephemeral and not accessible to users
+
 ---
 
 ## Type Safety (Zero Tolerance)