added more clarity on the thresholds field

Author: G-Wang12

MESSAGING.md

@@ -23,7 +23,7 @@ update. The agent extracts four things from your message:
 | --- | --- | --- |
 | `trackedKeywords` | Macro/news triggers to match headlines against | "alert me on CPI, FOMC, and Powell" |
 | `watchlist` | Explicit **stock tickers** you care about | "watch TSLA and NVDA for me" |
-| `sentimentThreshold` | Sensitivity, 0–1 (lower = more alerts) | "only the big stuff, threshold 0.8" |
+| `severityThreshold` | Minimum **market impact** to alert, 0–1 (lower = more alerts) | "only the big stuff, threshold 0.8" |
 | `sourceTrustThreshold` | Minimum publisher trustworthiness, 0–1 (higher = stricter) | "only alert me from reputable sources" |
 
 You can combine them in one message, or send them across several — you don't
@@ -40,10 +40,28 @@ The agent replies with a confirmation echoing your **current** settings, e.g.:
 Got it — saved your macro preferences for this chat.
 Tracked keywords: CPI, FOMC
 Watchlist: TSLA, NVDA
-Sentiment threshold: 0.5
+Severity threshold: 0.5
+Alerts when a matching headline's Severity score is ≥ 0.5 (same "Severity" on each alert; not bullish/bearish Direction). Lower = more alerts.
 Source trust: any source
 ```
 
+### What “threshold” means (severity, not direction)
+
+When you text `threshold 0.5`, you are setting your **severity threshold** — how
+**market-moving** a headline must be before you get pinged. After a headline matches your keywords or
+watchlist, Grok scores it on three separate 0–1 scales:
+
+| Score on each alert | What it measures | Used to filter alerts? |
+| --- | --- | --- |
+| **Severity** | How market-moving the headline is (CPI surprise, FOMC shock, etc.) | **Yes** — compared to your **severity threshold** |
+| **Direction** | Bearish vs bullish tone | **No** — shown for context only |
+| **Source trust** | Publisher credibility (Reuters high, PR wire low) | **Yes** — if you set a source-trust minimum |
+
+So **`threshold 0.5` sets your severity threshold** — “only alert me when severity ≥
+0.5.” It does **not** mean “only bearish news” or “only bullish news.” Lower the
+number for more alerts; raise it (e.g. `threshold 0.8`) for fewer, bigger
+headlines only.
+
 **Updates are incremental.** Each message changes only what it mentions; the
 rest of your settings are kept. So this works as a conversation:
 
@@ -68,7 +86,7 @@ start over:
 | **Replace a list** | `only watch TSLA`, `just track CPI and FOMC` | sets that one list to exactly what you named |
 | **Clear one list** | `clear my watchlist` | empties that list, keeps the rest |
 | **Reset everything** | `reset my settings`, `clear everything` | back to defaults (no keywords/tickers, threshold 0.6, any source) |
-| **Set threshold** | `threshold 0.5`, `only big alerts` | changes only the sensitivity |
+| **Set impact threshold** | `threshold 0.5`, `only big alerts` | changes how market-moving news must be |
 | **Filter by source** | `only reputable sources`, `any source is fine` | sets/clears the minimum source-trust level |
 
 Add/remove are case-insensitive, so `untrack cpi` removes `CPI`. Replacing or
@@ -78,7 +96,7 @@ untouched.
 ### What triggers a watchlist alert
 
 A watched ticker behaves like an extra keyword: a headline alerts you if it
-mentions the ticker **and** the headline's severity is at or above your
+mentions the ticker **and** the headline's **market impact** is at or above your
 threshold. Tickers and tracked keywords are matched as a combined set, so you
 don't need to also list a ticker under keywords.
 
@@ -99,7 +117,7 @@ each alert is labelled `low` / `medium` / `high`:
 Macro alert
 Fed raises rates by 25bps, signals higher-for-longer stance
 Source: Reuters · trust high (0.95)
-Severity: 0.90 | Sentiment: bearish (0.20)
+Severity: 0.90 | Direction: bearish (0.20)
 ...
 ```
 
@@ -114,13 +132,13 @@ only want credible publishers, set a minimum:
 | `any source is fine` | turns the filter off (back to 0) |
 
 The trust threshold is per chat and incremental like your other settings, and it
-stacks with your keyword/watchlist match and sentiment threshold — a headline
+stacks with your keyword/watchlist match and impact threshold — a headline
 must clear **all** of them to alert.
 
 ### Defaults
 
 A brand-new chat starts at `trackedKeywords = []`, `watchlist = []`,
-`sentimentThreshold = 0.6`, `sourceTrustThreshold = 0` (any source). An empty
+`severityThreshold = 0.6`, `sourceTrustThreshold = 0` (any source). An empty
 keyword **and** watchlist set means "match every headline" (subject to the
 thresholds).
 

ONBOARDING.md

@@ -119,7 +119,8 @@ The agent replies with something like:
 Got it — saved your macro preferences for this chat.
 Tracked keywords: CPI, FOMC
 Watchlist: (none)
-Sentiment threshold: 0.5
+Severity threshold: 0.5
+Alerts when a matching headline's Severity score is ≥ 0.5 (same "Severity" on each alert; not bullish/bearish Direction). Lower = more alerts.
 Source trust: any source
 ```
 

README.md

@@ -187,7 +187,7 @@ Checklist:
 
 Troubleshooting (preferences):
 
-- If you get `Got it — saved...` but `Tracked keywords: (none)` and `Sentiment threshold: 0.6`, the agent fell back to defaults (most commonly because `XAI_API_KEY` is missing/blank, or the LLM output wasn't parseable).
+- If you get `Got it — saved...` but `Tracked keywords: (none)` and `Severity threshold: 0.6`, the agent fell back to defaults (most commonly because `XAI_API_KEY` is missing/blank, or the LLM output wasn't parseable).
 - If you get `Sorry — I couldn't update your preferences right now.`, the LLM call failed (network/API/model error). Check the agent console logs for the error.
 - If an alert arrives before your “Got it — saved…” reply, restart the agent after `npm run build` — the agent holds alerts while your settings message is being processed so confirmations should arrive first.
 - If you get multiple identical replies for a single text, you likely have multiple `npm start` processes running at once. Stop extras (Ctrl+C) so only one agent instance is connected.
@@ -198,8 +198,8 @@ Troubleshooting (preferences):
 After saving preferences (above), leave `npm start` running with `cpp_engine` publishing:
 
 1. Watch the agent console for `[ZMQ] headline: ... [source: ...]` when a headline is received.
-2. If the headline matches your keywords **or watchlist tickers**, Grok’s **severity** is at or above your **sentiment threshold**, and the **source trust** Grok assigns the publisher is at or above your **source-trust threshold** (default 0 = any source), you should get a proactive iMessage (no new inbound message required). The alert names the source and its trust level, e.g. `Source: Reuters · trust high (0.95)`.
-3. Lower threshold → more alerts; higher threshold → fewer. Raise the source-trust threshold (e.g. "only reputable sources") to suppress low-credibility publishers — see [`MESSAGING.md`](MESSAGING.md).
+2. If the headline matches your keywords **or watchlist tickers**, Grok’s **severity** score is at or above your **severity threshold** (what you set with `threshold 0.5`, etc.), and the **source trust** Grok assigns the publisher is at or above your **source-trust threshold** (default 0 = any source), you should get a proactive iMessage (no new inbound message required). The alert names the source and its trust level, e.g. `Source: Reuters · trust high (0.95)`.
+3. Lower severity threshold → more alerts; higher → fewer. This filters on **how market-moving** the headline is — not bullish/bearish direction (direction is shown on the alert but not filtered). Raise the source-trust threshold (e.g. "only reputable sources") to suppress low-credibility publishers — see [`MESSAGING.md`](MESSAGING.md).
 
 #### Testing the watchlist specifically
 

TECHNICAL.md

@@ -136,7 +136,7 @@ When a user sends a text message, `ts_agent` extracts macro trading preferences
 
 - `userPreferences: Map<string, UserPreferences>`
 - Key: `space.id` (conversation id)
-- Value: `{ trackedKeywords: string[], watchlist: string[], sentimentThreshold: number, sourceTrustThreshold: number }`
+- Value: `{ trackedKeywords: string[], watchlist: string[], severityThreshold: number, sourceTrustThreshold: number }`
 - `spacesById: Map<string, Space>` — caches the Spectrum `space` handle for proactive outbound sends (populated on each inbound message)
 - `lastAlertBySpace: Map<string, AlertContext>` — headline + Grok analysis for conversational follow-ups (~30 minute TTL)
 
@@ -212,7 +212,7 @@ User preferences (tracked keywords + watchlist tickers) live only in the agent,
 1. Parse JSON frame (including the `source` publisher); dedupe by `ts` + headline (or headline alone) for ~2 minutes.
 2. Call Grok (`analyzeHeadlineWithLlm`, passing the headline + source) → `{ sentiment, severity, summary, sourceTrust }`. `sourceTrust` (0–1) is Grok's credibility rating of the publisher; an absent/garbled rating defaults to ~0.3 (low).
 3. For each `userPreferences` entry, enqueue `spaceOutbound.run(spaceId, "alert", …)` (waits if that space has an active alert hold).
-4. Inside the alert task, re-check keywords, `severity >= sentimentThreshold`, **and** `sourceTrust >= sourceTrustThreshold` against current preferences, then `app.send(space, alertText)` and store `lastAlertBySpace`. The alert text and stored context include the source name and its `low`/`medium`/`high` trust label.
+4. Inside the alert task, re-check keywords, `severity >= severityThreshold`, **and** `sourceTrust >= sourceTrustThreshold` against current preferences, then `app.send(space, alertText)` and store `lastAlertBySpace`. The alert text and stored context include the source name and its `low`/`medium`/`high` trust label. (`severityThreshold` is the user-facing “threshold”; it gates on market impact, not bullish/bearish sentiment.)
 
 If no user has messaged since startup, preferences are empty and headlines are logged but not alerted. If preferences exist but `spacesById` lacks that `space.id`, the agent logs that the user must message first (Spectrum needs a cached conversation handle for outbound iMessage).