Document logging channels and dev mode flow

AGENTS.md

@@ -10,6 +10,13 @@ This guide tells AI agents how to keep bitvid aligned with the current product d
 * **Unstable** is our experimentation lane. Gate risky behavior behind feature flags defined in `js/constants.js` and document the toggle/rollback plan in PR descriptions.
 * **Emergency response:** If a change regresses URL-first playback or breaks magnet parsing, revert immediately, call this out in the PR, and annotate the AGENTS.md changelog with remediation tips. **Note:** These regressions usually surface in dev logs and tests around playback/magnet helpers—reference them when triaging so future agents don’t repeat the mistake.
 
+### Browser logging policy
+
+* Route every browser log through `js/utils/logger.js`. Do **not** call `console.*` directly.
+* Use `logger.dev.*` for diagnostics that should disappear in production (flagged by `IS_DEV_MODE`/`isDevMode`). Use `logger.user.*` for operator-facing warnings and errors that must reach production consoles.
+* Before promoting a build, flip `IS_DEV_MODE` in `config/instance-config.js` to match the target environment so `window.__BITVID_DEV_MODE__` and the logger channels behave correctly.
+* Review and follow [`docs/logging.md`](docs/logging.md) whenever you add new logging or touch inline scripts.
+
 ## 2. Mission: URL‑First Playback with WebTorrent Fallback
 
 * **Goal:** Always deliver smooth playback while keeping hosting costs low.

README.md

@@ -170,6 +170,11 @@ artifacts.
   - Central place for instance-specific values like the Super Admin npub and the
     default whitelist-only mode setting. Update the documented exports here when
     preparing a new deployment.
+  - Flip `IS_DEV_MODE` to `false` before shipping production builds. The flag
+    flows into `js/config.js` as `isDevMode`, seeds the
+    `window.__BITVID_DEV_MODE__` global for inline scripts, and gates whether the
+    dev logging channel emits to the console. See
+    [`docs/logging.md`](docs/logging.md) for rollout guidance.
   - Tune `PLATFORM_FEE_PERCENT` (0–100) to keep a percentage of Lightning tips.
     When the fee is positive, bitvid routes the platform’s split to
     `PLATFORM_LUD16_OVERRIDE`, so set it to the Lightning address that should
@@ -177,8 +182,15 @@ artifacts.
     the fee at `0` to pass through every satoshi.
   - Populate `DEFAULT_RELAY_URLS_OVERRIDE` with WSS URLs to replace the bundled
     relay bootstrap list. Keep it empty to stick with the upstream defaults.
-- **`config.js`**:
-  - Toggle `isDevMode` for development (`true`) or production (`false`).
+- **`js/config.js`**:
+  - Re-exports `isDevMode` (derived from `IS_DEV_MODE`) for modules, publishes
+    `window.__BITVID_DEV_MODE__`, and centralizes the global configuration
+    surface.
+- **`js/utils/logger.js`**:
+  - Provides the shared `logger` utility. Route user-facing errors through
+    `logger.user` and keep experimental diagnostics on `logger.dev` so operators
+    can quiet development noise in production. Details live in
+    [`docs/logging.md`](docs/logging.md).
 - **`js/constants.js`**:
   - Source for browser-safe tracker lists and feature flags that govern WebTorrent behavior.
 - **Magnet helpers**:

docs/logging.md

@@ -0,0 +1,66 @@
+# Logging and Dev-Mode Guidance
+
+This document explains how bitvid routes browser logs, how inline scripts can
+re-use the shared logger, and what operators must do with the dev-mode flag when
+promoting builds.
+
+## Picking the right channel
+
+bitvid ships a frozen logger at `js/utils/logger.js` with two channels:
+
+- `logger.dev`: Emits only when `IS_DEV_MODE` is truthy. Use this channel for
+  verbose traces, performance probes, and feature flag experimentation that
+  should disappear from production consoles.
+- `logger.user`: Always available and automatically prefixes output with
+  `[bitvid]`. Use this channel for operator-facing warnings and errors that help
+  diagnose issues in production.
+
+When adding new messages, classify them by the audience:
+
+| Scenario | Recommended channel | Notes |
+| --- | --- | --- |
+| Debugging a new feature locally | `logger.dev.info`/`logger.dev.log` | Remove or downgrade before launching if they no longer serve a purpose. |
+| Non-fatal recoverable issues users should investigate | `logger.user.warn` | Provide actionable context so operators know what failed. |
+| Fatal errors that block playback or payments | `logger.user.error` | Escalate with a clear message and include relevant IDs or URLs. |
+| Metrics or noisy traces that only help during QA | `logger.dev.*` | Wrap expensive logging in conditional checks when possible. |
+
+Avoid direct `console.*` calls—routing everything through the logger keeps the
+production console clean and guarantees dev-mode gates behave consistently.
+
+## Using the logger from inline scripts
+
+The logger is exposed as a frozen global so inline scripts can share the same
+API without additional bundling:
+
+```js
+const { dev, user } = window.bitvidLogger;
+
+dev.log("rendering upload modal preview");
+user.warn("Playback manifest missing expected resolution tag");
+```
+
+If you need to guard logic by environment, rely on the companion global set in
+`js/config.js`:
+
+```js
+if (window.__BITVID_DEV_MODE__) {
+  window.bitvidLogger.dev.info("Hydrating admin widgets in dev mode");
+}
+```
+
+The globals are populated as soon as `js/config.js` loads. Check for their
+existence before using them in third-party contexts that may execute earlier.
+
+## Adjusting the dev-mode flag for deployments
+
+The source of truth lives in `config/instance-config.js`:
+
+- Set `IS_DEV_MODE = true` while developing locally so the dev logger and other
+  diagnostics are available.
+- Flip `IS_DEV_MODE = false` before shipping a production build. This change
+  propagates to `isDevMode` (the module export), `window.__BITVID_DEV_MODE__`,
+  and `logger.dev`, silencing development-only messages.
+
+Always commit the flag change alongside deployment-ready configuration tweaks.
+Forgetting to update the flag leaves verbose traces in user consoles and can
+expose experimental behavior intended only for QA environments.