fix: clarify prompt analytics defaults

DOCUMENTATION.md

@@ -276,6 +276,9 @@ Default shipped posture:
 - persist raw prompt text: disabled
 - redact-before-persist: enabled
 
+Important operational note:
+- if both `security_scan` and `context_lens` remain disabled, AISBF will not record any prompt-analysis rows, and the prompt analytics dashboard will remain empty even though the page itself loads correctly
+
 ### Request-time behavior
 
 When enabled, AISBF performs local prompt analysis before proxying the request upstream:

README.md

@@ -106,6 +106,7 @@ The dashboard provides:
 - Enable Context Lens analytics to capture prompt composition metadata, risk summaries, and redacted evidence
 - Enable NSFW and privacy classification so AISBF can route or restrict traffic based on content sensitivity
 - Optionally block high-risk prompts and keep persisted prompt text disabled by default while redaction remains enabled
+- Prompt analytics stay empty until Prompt Security or Context Lens Analytics is explicitly enabled in settings or resource overrides
 
 ## API Usage
 

templates/dashboard/prompt_analytics.html

@@ -313,7 +313,14 @@ document.getElementById('timeRangeSelect').addEventListener('change', function()
     {% endif %}
 </div>
 {% else %}
-<p style="color: var(--color-muted);">No prompt analysis data available yet.</p>
+<div style="background: var(--bg-page); padding: 20px; border-radius: 8px; border: 1px solid rgba(148,163,184,0.15); margin-bottom: 20px;">
+    <p style="color: var(--color-muted); margin: 0 0 12px;">No prompt analysis data available yet.</p>
+    <div style="color: var(--color-muted); line-height: 1.7;">
+        <div>Prompt analytics are only recorded when <strong>Prompt Security</strong> or <strong>Context Lens Analytics</strong> is enabled for the active request path.</div>
+        <div style="margin-top: 8px;">The shipped defaults keep both features disabled. Enable them from <strong>Dashboard → Settings</strong> or via provider/model overrides, then send new requests through AISBF.</div>
+        <div style="margin-top: 8px;">Optional related controls include <strong>Block High-Risk Prompts</strong>, <strong>NSFW Classification</strong>, and <strong>Privacy Classification</strong>.</div>
+    </div>
+</div>
 {% endif %}
 
 <div style="margin-top: 30px; display: flex; gap: 10px; flex-wrap: wrap;">

templates/dashboard/settings.html

@@ -42,6 +42,17 @@ along with this program.  If not, see <https://www.gnu.org/licenses/>.
 </div>
 {% endmacro %}
 
+{% macro bool_mode_select(field_name, selected_value, label, help_text='') %}
+<div class="form-group">
+    <label for="{{ field_name }}">{{ label }}</label>
+    <select id="{{ field_name }}" name="{{ field_name }}">
+        <option value="enabled" {% if selected_value == 'enabled' %}selected{% endif %}>Enabled</option>
+        <option value="disabled" {% if selected_value == 'disabled' %}selected{% endif %}>Disabled</option>
+    </select>
+    {% if help_text %}<small style="color: var(--color-subtle); display: block; margin-top: 5px;">{{ help_text }}</small>{% endif %}
+</div>
+{% endmacro %}
+
 <div style="display:flex; justify-content:space-between; align-items:center; margin-bottom:24px;">
     <h2 style="margin:0;">Server Settings</h2>
 </div>
@@ -537,25 +548,25 @@ along with this program.  If not, see <https://www.gnu.org/licenses/>.
     </div>
 
     <div class="section-title" style="margin-top:28px;"><i class="fas fa-sliders-h"></i> Global Feature Defaults</div>
-    <p style="color:var(--color-muted);margin-bottom:16px;font-size:.9em;">These tri-state defaults drive inheritance for provider, model, rotation, and autoselect overrides.</p>
+    <p style="color:var(--color-muted);margin-bottom:16px;font-size:.9em;">These are the global defaults used by provider, model, rotation, and autoselect overrides when they inherit behavior.</p>
     {% set feature_controls = config.feature_controls if config.feature_controls else none %}
     {% set prompt_security = feature_controls.prompt_security if feature_controls and feature_controls.prompt_security else none %}
     <div class="tri-grid">
-        {{ tri_state_select('feature_nsfw_classification_mode', feature_controls.nsfw_classification.mode if feature_controls and feature_controls.nsfw_classification else 'inherit', 'NSFW Classification', 'Default NSFW classification behavior.') }}
-        {{ tri_state_select('feature_privacy_classification_mode', feature_controls.privacy_classification.mode if feature_controls and feature_controls.privacy_classification else 'inherit', 'Privacy Classification', 'Default privacy classification behavior.') }}
-        {{ tri_state_select('feature_context_condensation_mode', feature_controls.context_condensation.mode if feature_controls and feature_controls.context_condensation else 'inherit', 'Context Condensation', 'Default context condensation behavior.') }}
-        {{ tri_state_select('feature_response_cache_mode', feature_controls.response_cache.mode if feature_controls and feature_controls.response_cache else 'inherit', 'Response Cache', 'Default response-cache behavior.') }}
-        {{ tri_state_select('feature_prompt_batching_mode', feature_controls.prompt_batching.mode if feature_controls and feature_controls.prompt_batching else 'inherit', 'Prompt Batching', 'Default batching behavior.') }}
-        {{ tri_state_select('feature_prompt_security_mode', prompt_security.security_scan.mode if prompt_security and prompt_security.security_scan else 'inherit', 'Prompt Security', 'Default local prompt scanning behavior.') }}
-        {{ tri_state_select('feature_context_lens_mode', prompt_security.context_lens.mode if prompt_security and prompt_security.context_lens else 'inherit', 'Context Lens Analytics', 'Default prompt composition analytics behavior.') }}
-        {{ tri_state_select('feature_block_high_risk_prompts_mode', prompt_security.block_high_risk_prompts.mode if prompt_security and prompt_security.block_high_risk_prompts else 'inherit', 'Block High-Risk Prompts', 'Default local high-risk blocking behavior.') }}
+        {{ bool_mode_select('feature_nsfw_classification_mode', feature_controls.nsfw_classification.mode if feature_controls and feature_controls.nsfw_classification else 'disabled', 'NSFW Classification', 'Default NSFW classification behavior.') }}
+        {{ bool_mode_select('feature_privacy_classification_mode', feature_controls.privacy_classification.mode if feature_controls and feature_controls.privacy_classification else 'disabled', 'Privacy Classification', 'Default privacy classification behavior.') }}
+        {{ bool_mode_select('feature_context_condensation_mode', feature_controls.context_condensation.mode if feature_controls and feature_controls.context_condensation else 'disabled', 'Context Condensation', 'Default context condensation behavior.') }}
+        {{ bool_mode_select('feature_response_cache_mode', feature_controls.response_cache.mode if feature_controls and feature_controls.response_cache else 'disabled', 'Response Cache', 'Default response-cache behavior.') }}
+        {{ bool_mode_select('feature_prompt_batching_mode', feature_controls.prompt_batching.mode if feature_controls and feature_controls.prompt_batching else 'disabled', 'Prompt Batching', 'Default batching behavior.') }}
+        {{ bool_mode_select('feature_prompt_security_mode', prompt_security.security_scan.mode if prompt_security and prompt_security.security_scan else 'disabled', 'Prompt Security', 'Default local prompt scanning behavior.') }}
+        {{ bool_mode_select('feature_context_lens_mode', prompt_security.context_lens.mode if prompt_security and prompt_security.context_lens else 'disabled', 'Context Lens Analytics', 'Default prompt composition analytics behavior.') }}
+        {{ bool_mode_select('feature_block_high_risk_prompts_mode', prompt_security.block_high_risk_prompts.mode if prompt_security and prompt_security.block_high_risk_prompts else 'disabled', 'Block High-Risk Prompts', 'Default local high-risk blocking behavior.') }}
     </div>
 
     <div class="section-title" style="margin-top:28px;"><i class="fas fa-shield-alt"></i> Prompt Security Persistence</div>
     <p style="color:var(--color-muted);margin-bottom:16px;font-size:.9em;">Controls how prompt analysis findings are stored when prompt-security features are active.</p>
     <div class="tri-grid">
-        {{ tri_state_select('feature_persist_prompt_text_mode', prompt_security.persist_prompt_text.mode if prompt_security and prompt_security.persist_prompt_text else 'inherit', 'Persist Prompt Text', 'Store prompt text with prompt-analysis records when allowed.') }}
-        {{ tri_state_select('feature_redact_before_persist_mode', prompt_security.redact_before_persist.mode if prompt_security and prompt_security.redact_before_persist else 'inherit', 'Redact Before Persist', 'Redact sensitive fragments before storing prompt-analysis records.') }}
+        {{ bool_mode_select('feature_persist_prompt_text_mode', prompt_security.persist_prompt_text.mode if prompt_security and prompt_security.persist_prompt_text else 'disabled', 'Persist Prompt Text', 'Store prompt text with prompt-analysis records when allowed.') }}
+        {{ bool_mode_select('feature_redact_before_persist_mode', prompt_security.redact_before_persist.mode if prompt_security and prompt_security.redact_before_persist else 'enabled', 'Redact Before Persist', 'Redact sensitive fragments before storing prompt-analysis records.') }}
     </div>
 
     <div class="form-group" style="margin-top: 18px; max-width: 340px;">