Merge pull request #1970 from PR0M3TH3AN/codex/update-dev-mode-flag-defaults-and-documentation

Harden dev-mode defaults with runtime overrides

README.md

@@ -431,8 +431,11 @@ artifacts now that the deploy pipeline owns the build step.
     preparing a new deployment.
   - See [`docs/instance-config.md`](docs/instance-config.md) for a full
     reference of every setting and how to tune it.
-  - Flip `IS_DEV_MODE` to `false` before shipping production builds. The flag
-    flows into `js/config.js` as `isDevMode`, seeds the
+  - `IS_DEV_MODE` and `IS_VERBOSE_DEV_MODE` default to `false` for production.
+    If you need dev logging in a staging or QA build without editing source,
+    inject `window.__BITVID_DEV_MODE_OVERRIDE__` and/or
+    `window.__BITVID_VERBOSE_DEV_MODE_OVERRIDE__` before `js/config.js` loads.
+    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.

config/instance-config.js

@@ -17,11 +17,13 @@
  * Whether the current deployment should enable developer-centric behavior.
  *
  * When `true`, bitvid surfaces extra logging, debug helpers, and experimental
- * UI affordances intended for development environments. Set the value to
- * `false` before deploying to production so that end users receive the stable
- * experience. Downstream modules read this flag via `js/config.js`.
+ * UI affordances intended for development environments. Leave the value
+ * `false` for production so end users receive the stable experience; use the
+ * runtime overrides documented in `js/config.js` when you need to toggle dev
+ * mode without editing this file. Downstream modules read this flag via
+ * `js/config.js`.
  */
-export const IS_DEV_MODE = true;
+export const IS_DEV_MODE = false;
 
 /**
  * Whether development builds should surface extra verbose diagnostics.
@@ -29,8 +31,10 @@ export const IS_DEV_MODE = true;
  * Set this to `true` to keep high-volume development warnings (like COUNT
  * request failures) visible in the console. Flip it to `false` when you want
  * a quieter dev mode without disabling other development helpers entirely.
+ * Use the runtime override documented in `js/config.js` if you need to toggle
+ * verbosity without editing this file.
  */
-export const IS_VERBOSE_DEV_MODE = true;
+export const IS_VERBOSE_DEV_MODE = false;
 
 /**
  * Whether the current deployment should operate in lockdown mode.

docs/instance-config.md

@@ -28,14 +28,30 @@ an operator might change it.
     debug affordances. The value is re-exported as `isDevMode` in
     `js/config.js` and controls `window.__BITVID_DEV_MODE__` as well as
     logger routing.
-  - **Why change it:** Set to `false` for production builds so only the stable
-    UX and user-facing logging remain.
+  - **Why change it:** Defaults to `false` for production builds. Set to `true`
+    for local development, or use the runtime override described below to
+    toggle dev mode without editing this file.
 
 - **`IS_VERBOSE_DEV_MODE`**
   - **What it does:** Enables high-volume diagnostics inside dev mode (for
     example, repeated COUNT failures).
   - **Why change it:** Keep `true` while debugging noisy workflows and set to
     `false` when you want a quieter dev console without disabling dev mode.
+    Defaults to `false` for production.
+
+To override the dev flags at runtime (for example in a staging build) without
+changing `config/instance-config.js`, inject one or both of the following
+globals **before** `js/config.js` loads:
+
+```html
+<script>
+  window.__BITVID_DEV_MODE_OVERRIDE__ = true;
+  window.__BITVID_VERBOSE_DEV_MODE_OVERRIDE__ = true;
+</script>
+```
+
+The overrides accept boolean values or the strings `"true"` / `"false"` so they
+can be injected at build time.
 
 - **`IS_LOCKDOWN_MODE`**
   - **What it does:** Toggles a lockdown posture that limits access and switches

docs/logging.md

@@ -59,10 +59,23 @@ 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.
+- Keep `IS_DEV_MODE = false` for production builds. This value 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.
+
+If you need to enable dev logging without editing `config/instance-config.js`,
+inject a runtime override before `js/config.js` loads:
+
+```html
+<script>
+  window.__BITVID_DEV_MODE_OVERRIDE__ = true;
+  window.__BITVID_VERBOSE_DEV_MODE_OVERRIDE__ = true;
+</script>
+```
+
+Overrides accept boolean values or the strings `"true"` / `"false"` so they can
+be injected by a build pipeline.

js/config.js

@@ -47,10 +47,39 @@ import {
 
 export const WATCH_HISTORY_VERSION_TAG_VALUE = "2";
 
-export const isDevMode = Boolean(IS_DEV_MODE);
+const runtimeScope = typeof globalThis === "undefined" ? null : globalThis;
+
+const parseBooleanOverride = (value) => {
+  if (typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "string") {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "true") {
+      return true;
+    }
+    if (normalized === "false") {
+      return false;
+    }
+  }
+  return null;
+};
+
+const devModeOverride = parseBooleanOverride(
+  runtimeScope?.__BITVID_DEV_MODE_OVERRIDE__
+);
+const verboseDevModeOverride = parseBooleanOverride(
+  runtimeScope?.__BITVID_VERBOSE_DEV_MODE_OVERRIDE__
+);
+
+export const isDevMode =
+  devModeOverride === null ? Boolean(IS_DEV_MODE) : devModeOverride;
 export { IS_DEV_MODE };
 
-export const isVerboseDevMode = Boolean(IS_VERBOSE_DEV_MODE);
+export const isVerboseDevMode =
+  verboseDevModeOverride === null
+    ? Boolean(IS_VERBOSE_DEV_MODE)
+    : verboseDevModeOverride;
 export { IS_VERBOSE_DEV_MODE };
 
 export const isLockdownMode = Boolean(IS_LOCKDOWN_MODE);