uopdate doc

README.md

@@ -46,6 +46,33 @@ Or use the helper script, which creates/uses `.venv` automatically and runs `pip
 - Continuous monitor writing `state/fgai-status.json`
 - Local dashboard at `http://127.0.0.1:8088`
 
+## Dashboard How To
+
+The dashboard is the normal way to run SignalScope once the service is started.
+It is organized around the operational workflow:
+
+1. Open `Settings`.
+2. Select `Graylog MCP`.
+3. Enter the Graylog MCP URL and token, then save.
+4. Click `Load streams`.
+5. Enable the streams you want SignalScope to monitor, then save again.
+6. Apply missing recommended profiles, or click `Edit profile` on a stream to
+   choose its entity, time, baseline, detector, and weight fields manually.
+7. Let the baseline learn for the configured `Baseline training days` before
+   treating every deviation as actionable.
+8. Use `Overview` for incidents, trends, stream health, AI assessment, and the
+   correlation map.
+9. Use `Findings` for the triage queue, field baseline deviations, related
+   activity across sources, threat intelligence, and policy findings.
+10. Use `Diagnostics` to confirm stream coverage, MCP fetch health, profile
+    readiness, data quality, and normalized top fields.
+11. Mark findings as `Expected`, `False positive`, or `Confirmed` so repeated
+    known behavior is labeled and lower priority in later refreshes.
+
+The UI also includes a `How To` tab with the same operational checklist. Use it
+when adding new streams or when the dashboard has data but it is unclear what
+needs attention next.
+
 ## Primary Workflow: Graylog MCP
 
 Graylog 7.1 MCP is the primary log-source integration. In the dashboard, open
@@ -99,6 +126,16 @@ see which streams are enabled, which have profiles, how many profile fields are
 baseline-ready, how many events were fetched, and whether a stream is `ready`,
 `learning`, `missing_profile`, `no_events`, or `not_enabled`.
 
+Recommended stream profiles are an onboarding helper, not a fixed FortiGate
+parser. SignalScope inspects the fields observed from each Graylog stream and
+looks for common denominator fields such as entities, timestamps, actions,
+severities, categories, ports, DNS names, URLs, process fields, Windows event
+IDs, and numeric counters. Fields that appear across multiple enabled streams
+are preferred when they are useful for correlation or baselining. The local
+Ollama profile advisor can refine those recommendations, but the deterministic
+profile discovery remains the fallback when Ollama is disabled, missing, slow, or
+returns invalid JSON.
+
 Enabled streams are normalized through the same event model. Stream profiles
 define the entity, timestamp, categorical, and numeric fields used for baselines.
 The dashboard and Ollama then correlate behavior across sources, for example a
@@ -141,6 +178,13 @@ Use the dashboard incident actions to acknowledge, resolve, or reopen an inciden
 and attach a note. The state is keyed to a stable incident fingerprint so it can
 survive monitor refreshes even when the current detection window changes.
 
+Field deviation review state is stored locally as feedback. Mark a deviation as
+`Expected`, `False positive`, or `Confirmed` from the Findings page. The decision
+is scoped to the stream, entity, field or detector pattern, optional value, note,
+and expiry time. Expected and false-positive feedback does not erase the finding;
+it keeps the row reviewable while reducing repeat noise for the same scoped
+pattern and giving Ollama context that the behavior is already known.
+
 Export the current investigation view when you need to share or archive an
 incident outside the dashboard:
 

tests/test_dashboard.py

@@ -2,7 +2,7 @@ import json
 import unittest
 from unittest.mock import patch
 
-from fgai.dashboard import _ollama_models
+from fgai.dashboard import HTML, _ollama_models
 
 
 class DashboardTests(unittest.TestCase):
@@ -23,6 +23,11 @@ class DashboardTests(unittest.TestCase):
         self.assertEqual(result["status"], "ok")
         self.assertEqual([item["name"] for item in result["models"]], ["llama3.1", "qwen3:8b"])
 
+    def test_dashboard_includes_how_to_view(self):
+        self.assertIn('data-tab="howto"', HTML)
+        self.assertIn('data-view="howto"', HTML)
+        self.assertIn("How To Use SignalScope", HTML)
+
 
 if __name__ == "__main__":
     unittest.main()