stock-scanner-mcp 1.17.0 → 1.18.0

package/README.md

@@ -6,7 +6,7 @@
 
 A modular MCP server for Claude Code and Claude Desktop that provides real-time access to stock and crypto market data. Scan markets, check technicals, monitor insider trades, track earnings, analyze options flow, and optionally save your own watchlists and thesis notes from one server.
 
-**65 tools** across **13 modules** — 9 modules work with zero API keys, including an optional stateful Market Workspace.
+**66 tools** across **14 modules** — 10 modules work with zero API keys, including an optional stateful Market Workspace.
 
 ## Quick Start
 
@@ -52,8 +52,19 @@ This gives you **46 tools** immediately with no API keys. API keys are optional
 
 Restart Claude Desktop after saving. Claude Code picks up the config automatically.
 
+> **Claude Code shortcut — install as a plugin instead of Steps 1 and 2.** If you use Claude Code, skip the manual config above and install everything with two commands:
+> ```
+> /plugin marketplace add yyordanov-tradu/stock-scanner-mcp
+> /plugin install stock-scanner@tradu-marketplace
+> ```
+> Run `/reload-plugins`, then `/mcp` — you should see the `stock-scanner` server listed as connected. The first launch runs `npx -y stock-scanner-mcp`, which downloads the package once (then it is cached). The plugin enables the workspace by default (data is stored in `~/.stock-scanner-mcp`) and passes the optional API keys (`FINNHUB_API_KEY`, `ALPHA_VANTAGE_API_KEY`, `FRED_API_KEY`) through from your environment; modules without a key are skipped automatically.
+>
+> **The plugin already bundles the skills — do NOT run Step 2.** All 19 skills ship with the plugin and load under the `stock-scanner:` namespace, e.g. `/stock-scanner:analyze-stock AAPL`, `/stock-scanner:morning-briefing`, `/stock-scanner:setup-market-workspace`. Running the Step 2 installer as well copies a second, unprefixed set into `~/.claude/skills/`, and the two collide — Step 2 is only for the manual (non-plugin) install. After installing, go straight to Step 3, using the namespaced command: `/stock-scanner:setup-market-workspace`.
+
 ### Step 2 — Install the trading skills
 
+> Skip this step if you installed via the plugin above — the plugin already bundles these skills (as `stock-scanner:<name>`). This step is only for the manual config in Step 1.
+
 Run this command in your terminal:
 
 ```bash
@@ -97,7 +108,7 @@ Once answered, it saves your profile and creates a `core` watchlist:
 
 You can also skip the skill and ask Claude directly: *"Set up my workspace — I'm a swing trader, create a core watchlist with MARA, HOOD, BTC, daily reviews."*
 
-**That's it.** You now have 65 tools, 19 skills, and a personalized workspace. Try `/workspace-morning-brief` for your first tailored market scan.
+**That's it.** You now have 66 tools, 19 skills, and a personalized workspace. Try `/workspace-morning-brief` for your first tailored market scan.
 
 ## What You Can Do
 
@@ -229,6 +240,7 @@ For the full list of workspace tools, see the [tool reference](#workspace--perso
 | sentiment | 2 | None | CNN Fear & Greed Index, Crypto Fear & Greed Index |
 | frankfurter | 5 | None | Forex exchange rates — 31 currencies from ECB (daily reference rates) |
 | reddit | 4 | None | Reddit trending tickers, mention tracking, sentiment, and batch watchlist scan from r/wallstreetbets, r/stocks, r/investing, r/options |
+| market-breadth | 1 | None | Market breadth metrics (advance/decline ratio, SMA 50/200, 52-week highs/lows) |
 | workspace | 7 | None | Optional stateful profile, watchlists, and thesis tracking for personalized workflows (`--enable-workspace`) |
 | finnhub | 9 | `FINNHUB_API_KEY` | Quotes, news, earnings, analyst ratings, short interest |
 | alpha-vantage | 5 | `ALPHA_VANTAGE_API_KEY` | Quotes, daily prices, fundamentals, earnings, dividends |
@@ -236,9 +248,9 @@ For the full list of workspace tools, see the [tool reference](#workspace--perso
 
 Modules auto-enable when their API key is set. No-key modules are always enabled, except `workspace`, which requires `--enable-workspace`.
 
-For a complete list of every tool with descriptions, see the [Full Tool Reference](#full-tool-reference-64-tools) below.
+For a complete list of every tool with descriptions, see the [Full Tool Reference](#full-tool-reference-66-tools) below.
 
-## Full Tool Reference (65 tools)
+## Full Tool Reference (66 tools)
 
 ### TradingView — Stock Scanning (no API key)
 
@@ -325,6 +337,12 @@ For a complete list of every tool with descriptions, see the [Full Tool Referenc
 | `reddit_sentiment` | Keyword-based sentiment analysis (bullish/bearish/neutral) for a ticker from Reddit discussions |
 | `reddit_watchlist_scan` | Batch Reddit scan for a list of tickers in one pass (combined OR query, ceil(N/20)×4 requests) — per-ticker mentions, sentiment, top post, and a hot flag (≥5 mentions) |
 
+### Market Breadth — Breadth Indicators (no API key)
+
+| Tool | Description |
+|------|-------------|
+| `market_breadth` | Get market breadth statistics for US equities: advance/decline ratio, SMA 50/200 percent above, and 52-week new highs/lows |
+
 ### Workspace — Personalized Context (optional, no API key)
 
 Enabled only when you start the server with `--enable-workspace`.
@@ -417,7 +435,7 @@ curl http://localhost:3200/openapi.json
 
 See [Sidecar HTTP API](https://github.com/yyordanov-tradu/stock-scanner-mcp/wiki/Sidecar-HTTP-API) for endpoint details.
 
-**65 tools** exposed as REST routes, including `/tradingview/quote`, `/options/chain`, `/workspace/profile`, and more.
+**66 tools** exposed as REST routes, including `/tradingview/quote`, `/options/chain`, `/workspace/profile`, and more.
 
 ## Rate Limits
 
@@ -439,8 +457,9 @@ All modules use in-memory TTL caching to minimize API calls.
 
 ```bash
 npm install && npm run build && npm test
-npm run lint          # TypeScript type checking
-npm run validate-tools # Tool description quality check
+npm run lint               # TypeScript type checking
+npm run validate-tools     # Tool description quality check
+npm run validate-doc-tools # Skill/command tool reference check
 ```
 
 ## Credibility Artifacts

package/dist/{chunk-WRGE3BZV.js → chunk-HUVDITHX.js}

@@ -4043,6 +4043,183 @@ function createWorkspaceModule(dataDir, defaultExchange = "NASDAQ") {
   };
 }
 
+// src/modules/market-breadth/index.ts
+import { z as z15 } from "zod";
+
+// src/modules/market-breadth/client.ts
+var CACHE_TTL9 = 15 * 60 * 1e3;
+var cache9 = new TtlCache(CACHE_TTL9);
+function aggregateMarketBreadth(rows, options) {
+  let advancers = 0;
+  let decliners = 0;
+  let unchanged = 0;
+  let adDenominator = 0;
+  let aboveSma50 = 0;
+  let sma50Denominator = 0;
+  let aboveSma200 = 0;
+  let sma200Denominator = 0;
+  let newHighs = 0;
+  let newLows = 0;
+  let hlDenominator = 0;
+  const threshold = options.newHighLowThresholdPct;
+  for (const row of rows) {
+    const d = row.data;
+    const close = d.close != null ? Number(d.close) : null;
+    const change = d.change != null ? Number(d.change) : null;
+    const high52 = d.price_52_week_high != null ? Number(d.price_52_week_high) : d["High.52Week"] != null ? Number(d["High.52Week"]) : d["High.52week"] != null ? Number(d["High.52week"]) : null;
+    const low52 = d.price_52_week_low != null ? Number(d.price_52_week_low) : d["Low.52Week"] != null ? Number(d["Low.52Week"]) : d["Low.52week"] != null ? Number(d["Low.52week"]) : null;
+    const sma50 = d.SMA50 != null ? Number(d.SMA50) : null;
+    const sma200 = d.SMA200 != null ? Number(d.SMA200) : null;
+    if (close !== null && change !== null && !isNaN(close) && !isNaN(change)) {
+      adDenominator++;
+      if (change > 0) {
+        advancers++;
+      } else if (change < 0) {
+        decliners++;
+      } else {
+        unchanged++;
+      }
+    }
+    if (close !== null && sma50 !== null && !isNaN(close) && !isNaN(sma50)) {
+      sma50Denominator++;
+      if (close > sma50) {
+        aboveSma50++;
+      }
+    }
+    if (close !== null && sma200 !== null && !isNaN(close) && !isNaN(sma200)) {
+      sma200Denominator++;
+      if (close > sma200) {
+        aboveSma200++;
+      }
+    }
+    if (close !== null && high52 !== null && low52 !== null && !isNaN(close) && !isNaN(high52) && !isNaN(low52)) {
+      hlDenominator++;
+      const highThreshold = high52 * (1 - threshold / 100);
+      const lowThreshold = low52 * (1 + threshold / 100);
+      if (close >= highThreshold) {
+        newHighs++;
+      }
+      if (close <= lowThreshold) {
+        newLows++;
+      }
+    }
+  }
+  const ratio = decliners > 0 ? Math.round(advancers / decliners * 100) / 100 : null;
+  const advancePercent = adDenominator > 0 ? Math.round(advancers / adDenominator * 1e4) / 100 : 0;
+  const declinePercent = adDenominator > 0 ? Math.round(decliners / adDenominator * 1e4) / 100 : 0;
+  const aboveSma50Percent = sma50Denominator > 0 ? Math.round(aboveSma50 / sma50Denominator * 1e4) / 100 : 0;
+  const aboveSma200Percent = sma200Denominator > 0 ? Math.round(aboveSma200 / sma200Denominator * 1e4) / 100 : 0;
+  return {
+    sampleSize: adDenominator,
+    advanceDecline: {
+      advancers,
+      decliners,
+      unchanged,
+      ratio,
+      advancePercent,
+      declinePercent
+    },
+    movingAverages: {
+      aboveSma50,
+      sma50Denominator,
+      aboveSma50Percent,
+      aboveSma200,
+      sma200Denominator,
+      aboveSma200Percent
+    },
+    newHighsLows: {
+      newHighs,
+      newLows,
+      thresholdPct: threshold,
+      denominator: hlDenominator
+    }
+  };
+}
+async function getMarketBreadth(options = {}) {
+  const universe = options.universe ?? "major_us";
+  const limit = options.limit ?? 3e3;
+  const threshold = options.newHighLowThresholdPct ?? 0.5;
+  const cacheKey = `breadth:${universe}:${limit}:${threshold}`;
+  const cached = cache9.get(cacheKey);
+  if (cached) return cached;
+  let exchanges = [];
+  if (universe === "major_us") {
+    exchanges = ["NYSE", "NASDAQ", "AMEX"];
+  } else {
+    exchanges = [universe];
+  }
+  const columns = ["close", "change", "SMA50", "SMA200", "price_52_week_high", "price_52_week_low", "type", "volume"];
+  let mergedRows = [];
+  for (const ex of exchanges) {
+    try {
+      const filters = [
+        { left: "type", operation: "equal", right: "stock" },
+        { left: "volume", operation: "greater", right: 1e4 },
+        { left: "exchange", operation: "equal", right: ex }
+      ];
+      const rows = await scanStocks({
+        exchange: ex,
+        columns,
+        filters,
+        limit
+      });
+      mergedRows = mergedRows.concat(rows);
+    } catch (e) {
+      console.error(`Failed to scan breadth for exchange ${ex}:`, e);
+    }
+  }
+  if (mergedRows.length === 0) {
+    throw new Error(`Failed to fetch breadth data for universe: ${universe}`);
+  }
+  const aggregates = aggregateMarketBreadth(mergedRows, {
+    universe,
+    limit,
+    newHighLowThresholdPct: threshold
+  });
+  const result = {
+    universe,
+    exchanges,
+    ...aggregates,
+    metadata: {
+      source: "tradingview",
+      dataDelay: "15min",
+      asOf: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
+  cache9.set(cacheKey, result);
+  return result;
+}
+
+// src/modules/market-breadth/index.ts
+function createMarketBreadthModule() {
+  const metadata3 = { source: "tradingview", dataDelay: "15min" };
+  return {
+    name: "market-breadth",
+    description: "Market breadth metrics aggregating advance/decline ratios, SMA alignment, and new 52-week highs/lows.",
+    requiredEnvVars: [],
+    tools: [
+      {
+        name: "market_breadth",
+        description: "Get market breadth statistics for US equities (NYSE, NASDAQ, AMEX). Recommends default 'major_us' representing NYSE+NASDAQ+AMEX. Filters out ETFs, funds, and illiquid symbols (volume < 10k) by default to measure standard stock performance.",
+        inputSchema: z15.object({
+          universe: z15.enum(["major_us", "NYSE", "NASDAQ", "AMEX"]).default("major_us").describe("Stock exchange universe. major_us includes NYSE, NASDAQ, and AMEX. NYSE, NASDAQ, or AMEX queries single exchange."),
+          limit: z15.number().int().min(100).max(1e4).default(3e3).describe("Max stocks to scan per exchange (default 3000)."),
+          newHighLowThresholdPct: z15.number().min(0).max(5).default(0.5).describe("Proximity threshold to count new 52-week high or low (e.g. 0.5 means within 0.5% of high/low, default 0.5).")
+        }),
+        readOnly: true,
+        handler: withMetadata(async (input) => {
+          const result = await getMarketBreadth({
+            universe: input.universe,
+            limit: input.limit,
+            newHighLowThresholdPct: input.newHighLowThresholdPct
+          });
+          return successResult(JSON.stringify(result, null, 2));
+        }, metadata3)
+      }
+    ]
+  };
+}
+
 // src/registry.ts
 import * as path2 from "path";
 import * as os from "os";
@@ -4059,6 +4236,7 @@ var MODULE_CATALOG = [
   { name: "sentiment", envVar: null, toolCount: 2, factory: () => createSentimentModule() },
   { name: "frankfurter", envVar: null, toolCount: 5, factory: () => createFrankfurterModule() },
   { name: "reddit", envVar: null, toolCount: 4, factory: () => createRedditModule() },
+  { name: "market-breadth", envVar: null, toolCount: 1, factory: () => createMarketBreadthModule() },
   { name: "workspace", envVar: null, toolCount: 7, factory: (config) => config.enableWorkspace ? createWorkspaceModule(config.dataDir || path2.join(os.homedir(), ".stock-scanner-mcp"), config.defaultExchange) : null }
 ];
 function resolveEnabledModules(allModules, env, filter) {

package/dist/index.js

@@ -5,7 +5,7 @@ import {
 import {
   MODULE_CATALOG,
   resolveEnabledModules
-} from "./chunk-WRGE3BZV.js";
+} from "./chunk-HUVDITHX.js";
 
 // src/index.ts
 import { readFileSync } from "fs";
@@ -79,7 +79,7 @@ OPTIONS
   --enable-workspace      Enable stateful workspace (watchlists, theses, profile)
   --data-dir <path>       Directory for workspace storage (default: ~/.stock-scanner-mcp)
 
-MODULES (65 tools total)
+MODULES (66 tools total)
   tradingview        10 tools Stock scanning, quotes, technicals       (no key)
   tradingview-crypto 4 tools  Crypto pair scanning and technicals      (no key)
   sec-edgar          6 tools  SEC filings, insider trades, holdings    (no key)
@@ -89,6 +89,7 @@ MODULES (65 tools total)
   sentiment          2 tools  Market & crypto Fear & Greed sentiment   (no key)
   frankfurter        5 tools  Forex exchange rates and conversion       (no key)
   reddit             4 tools  Reddit trending, sentiment, watchlist scan (no key)
+  market-breadth     1 tool   Advance/decline and SMA market breadth    (no key)
   workspace          7 tools  Stateful watchlists, theses, and profile  (no key)
   finnhub            9 tools  Quotes, profiles, peers, news, earnings  (FINNHUB_API_KEY)
   alpha-vantage      5 tools  Stock quotes, fundamentals, dividends    (ALPHA_VANTAGE_API_KEY)

package/dist/sidecar/index.js

@@ -2,7 +2,7 @@
 import {
   MODULE_CATALOG,
   resolveEnabledModules
-} from "../chunk-WRGE3BZV.js";
+} from "../chunk-HUVDITHX.js";
 
 // src/sidecar/server.ts
 import * as http from "http";
@@ -163,6 +163,8 @@ var SIDECAR_ROUTES = [
   { method: "POST", path: "/workspace/watchlists/update", tool: "workspace_update_watchlist" },
   { method: "GET", path: "/workspace/thesis", tool: "workspace_get_thesis" },
   { method: "POST", path: "/workspace/thesis", tool: "workspace_save_thesis" },
+  // Market Breadth
+  { method: "GET", path: "/market-breadth", tool: "market_breadth" },
   // CoinGecko
   { method: "GET", path: "/coingecko/coin", tool: "coingecko_coin" },
   { method: "GET", path: "/coingecko/trending", tool: "coingecko_trending" },

package/docs/sidecar-openapi.json

@@ -3,7 +3,7 @@
   "info": {
     "title": "Stock Scanner Sidecar API",
     "description": "REST API for stock and crypto market data, SEC filings, and technical analysis. This is the HTTP sidecar for the stock-scanner-mcp server.",
-    "version": "1.17.0",
+    "version": "1.18.0",
     "contact": {
       "name": "Yordan Yordanov",
       "url": "https://github.com/yyordanov-tradu/stock-scanner-mcp"
@@ -4520,6 +4520,87 @@
         }
       }
     },
+    "/market-breadth": {
+      "get": {
+        "summary": "Get market breadth statistics for US equities (NYSE, NASDAQ, AMEX)",
+        "description": "Get market breadth statistics for US equities (NYSE, NASDAQ, AMEX). Recommends default 'major_us' representing NYSE+NASDAQ+AMEX. Filters out ETFs, funds, and illiquid symbols (volume < 10k) by default to measure standard stock performance.",
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "description": "Varies by tool"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid parameters",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Tool not found or API key missing",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal server error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        },
+        "parameters": [
+          {
+            "name": "universe",
+            "in": "query",
+            "required": false,
+            "description": "Stock exchange universe. major_us includes NYSE, NASDAQ, and AMEX. NYSE, NASDAQ, or AMEX queries single exchange.",
+            "schema": {
+              "type": "string",
+              "description": "Stock exchange universe. major_us includes NYSE, NASDAQ, and AMEX. NYSE, NASDAQ, or AMEX queries single exchange."
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "required": false,
+            "description": "Max stocks to scan per exchange (default 3000).",
+            "schema": {
+              "type": "integer",
+              "description": "Max stocks to scan per exchange (default 3000)."
+            }
+          },
+          {
+            "name": "newHighLowThresholdPct",
+            "in": "query",
+            "required": false,
+            "description": "Proximity threshold to count new 52-week high or low (e.g. 0.5 means within 0.5% of high/low, default 0.5).",
+            "schema": {
+              "type": "number",
+              "description": "Proximity threshold to count new 52-week high or low (e.g. 0.5 means within 0.5% of high/low, default 0.5)."
+            }
+          }
+        ]
+      }
+    },
     "/coingecko/coin": {
       "get": {
         "summary": "Get detailed cryptocurrency info from CoinGecko",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "stock-scanner-mcp",
   "mcpName": "io.github.yyordanov-tradu/stock-scanner-mcp",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "description": "MCP server providing Claude Code with real-time stock and crypto market data, SEC filings, insider trades, and technical analysis",
   "type": "module",
   "bin": {
@@ -17,6 +17,7 @@
     "lint": "tsc --noEmit",
     "generate-openapi": "tsx src/scripts/generate-sidecar-openapi.ts",
     "validate-tools": "tsx src/scripts/validate-tools.ts",
+    "validate-doc-tools": "tsx src/scripts/validate-doc-tool-references.ts",
     "validate-structure": "tsx src/scripts/validate-structure.ts",
     "prepublishOnly": "npm run build && npm test"
   },
@@ -87,7 +88,7 @@
     "@emnapi/core": "^1.9.2",
     "@emnapi/runtime": "^1.9.2",
     "@emnapi/wasi-threads": "^2.0.0",
-    "@types/node": "^25.5.0",
+    "@types/node": "^26.0.1",
     "@types/proper-lockfile": "^4.1.4",
     "tsup": "^8.0.0",
     "tsx": "^4.21.0",

package/skills/README.md

@@ -4,6 +4,8 @@ Ready-made trading workflows that orchestrate [stock-scanner-mcp](https://www.np
 
 ## Quick Start
 
+> **Installed the Claude Code plugin?** You already have these skills — the plugin bundles them and loads them under the `stock-scanner:` namespace (e.g. `/stock-scanner:morning-briefing`). Skip the installer below; it is only for the manual MCP-server setup.
+
 **Prerequisites:** stock-scanner-mcp configured as an MCP server in Claude Code.
 
 ```bash

package/skills/TOOLS.md

@@ -1,6 +1,6 @@
 # stock-scanner-mcp Tool Reference
 
-Quick reference for all 54 MCP tools available to trading skills.
+Quick reference for all 66 MCP tools available to trading skills.
 
 ## TradingView (10 tools)
 
@@ -110,3 +110,32 @@ Quick reference for all 54 MCP tools available to trading skills.
 | `frankfurter_timeseries` | Daily rate history (max 90 days) | start_date, end_date, base, symbols |
 | `frankfurter_convert` | Convert amount between currencies | amount, from, to |
 | `frankfurter_currencies` | List all 31 supported currency codes | (none) |
+
+## Reddit (4 tools)
+
+| Tool | Purpose | Key Params |
+|------|---------|------------|
+| `reddit_trending` | Trending stock tickers from investing subreddits | subreddits, limit |
+| `reddit_mentions` | Mentions and top posts for a ticker | symbol, period |
+| `reddit_sentiment` | Keyword sentiment for a ticker | symbol, limit |
+| `reddit_watchlist_scan` | Batch scan watchlist tickers in one pass | symbols, period |
+
+## Market Breadth (1 tool)
+
+| Tool | Purpose | Key Params |
+|------|---------|------------|
+| `market_breadth` | Advance/decline ratio, % above SMA50/SMA200, 52-week highs/lows | universe, limit, newHighLowThresholdPct |
+
+## Workspace (7 tools)
+
+Requires the MCP server to run with `--enable-workspace`.
+
+| Tool | Purpose | Key Params |
+|------|---------|------------|
+| `workspace_get_profile` | Read saved trading profile and defaults | (none) |
+| `workspace_update_profile` | Save trading style, asset focus, cadence | tradingStyle, assetFocus, workflowCadence |
+| `workspace_list_watchlists` | List saved watchlists | (none) |
+| `workspace_create_watchlist` | Create a named watchlist | name |
+| `workspace_update_watchlist` | Replace watchlist symbols | name, symbols |
+| `workspace_get_thesis` | Read saved thesis for a symbol | symbol |
+| `workspace_save_thesis` | Save or update thesis for a symbol | symbol, summary, bullCase, bearCase, catalyst, timeframe |

package/skills/daily/market-close-recap/SKILL.md

@@ -7,9 +7,9 @@ description: Produce an end-of-day market recap covering index performance, sect
 
 ## Overview
 
-Desk analyst closing the book. Collect final index prints, sector scores, top movers, volume anomalies, and late-day headlines in one parallel wave, then synthesize into a concise session narrative.
+Desk analyst closing the book. Collect final index prints, market breadth, sector scores, top movers, volume anomalies, and late-day headlines in one parallel wave, then synthesize into a concise session narrative.
 
-Announce at start: "Running market close recap -- collecting final prints, sectors, movers, and headlines."
+Announce at start: "Running market close recap -- collecting final prints, breadth, sectors, movers, and headlines."
 
 ## Data Collection
 
@@ -18,6 +18,7 @@ Announce at start: "Running market close recap -- collecting final prints, secto
 | Tool | Parameters | Priority |
 |------|-----------|----------|
 | `tradingview_market_indices` | (defaults) | REQUIRED |
+| `market_breadth` | universe=major_us | REQUIRED |
 | `sentiment_fear_greed` | (defaults) | REQUIRED |
 | `tradingview_sector_performance` | (defaults) | REQUIRED |
 | `tradingview_top_gainers` | limit=10 | REQUIRED |
@@ -36,8 +37,9 @@ DO NOT reproduce raw tool output. Synthesize a session narrative by answering:
 1. **Session driver** -- What single theme or catalyst best explains today's price action? Name it explicitly.
 2. **Sector leaders and laggards** -- Identify the top 2 and bottom 2 sectors. Explain WHY they led or lagged using news, earnings, or macro context.
 3. **Index divergence** -- Did the major indices move in lockstep or diverge? If NASDAQ outperformed Dow (or vice versa), note the growth-vs-value implication.
-4. **Unusual volume** -- Flag names with abnormal volume that are NOT already in the gainers/losers lists. These are tomorrow's watchlist candidates.
-5. **Sentiment alignment** -- Does the Fear & Greed reading match the day's action, or is there a disconnect worth noting?
+4. **Breadth confirmation** -- Did advance/decline ratio, % above SMA50/SMA200, and new highs/lows confirm the index move or reveal narrow leadership?
+5. **Unusual volume** -- Flag names with abnormal volume that are NOT already in the gainers/losers lists. These are tomorrow's watchlist candidates.
+6. **Sentiment alignment** -- Does the Fear & Greed reading match the day's action and breadth, or is there a disconnect worth noting?
 
 ## Output Format
 
@@ -48,6 +50,10 @@ DO NOT reproduce raw tool output. Synthesize a session narrative by answering:
 
 Include S&P 500, NASDAQ Composite, Dow Jones, VIX. Add a one-sentence narrative below the table.
 
+### Market Breadth
+
+Report advance/decline ratio, % above SMA50, % above SMA200, new highs, and new lows. Add a one-sentence breadth verdict: CONFIRMED / NARROW / DETERIORATING.
+
 ### Sector Scorecard
 
 | Sector | Change % | Rank | Note |
@@ -85,4 +91,5 @@ Data from TradingView and Yahoo Finance is 15-minute delayed. CBOE and sentiment
 - Restating every gainer and loser without identifying the common thread that connects them.
 - Presenting sector data without explaining what drove the leaders and laggards.
 - Omitting the VIX context -- a rising VIX on a green day is a critical signal.
+- Calling a green index session risk-on when breadth is weak or new lows are expanding.
 - Listing headlines without connecting them to observed price action.

package/skills/daily/morning-briefing/SKILL.md

@@ -7,9 +7,9 @@ description: Run a pre-market scan across indices, sectors, sentiment, and upcom
 
 ## Overview
 
-Institutional pre-market desk analyst briefing. Collect broad market indices, sector performance, sentiment, top movers, and upcoming catalysts in a single parallel wave, then cross-reference to produce a directional bias.
+Institutional pre-market desk analyst briefing. Collect broad market indices, sector performance, market breadth, sentiment, top movers, and upcoming catalysts in a single parallel wave, then cross-reference to produce a directional bias.
 
-Announce at start: "Running pre-market briefing -- collecting indices, sectors, sentiment, movers, and catalysts."
+Announce at start: "Running pre-market briefing -- collecting indices, sectors, breadth, sentiment, movers, and catalysts."
 
 ## Data Collection
 
@@ -21,6 +21,7 @@ Announce at start: "Running pre-market briefing -- collecting indices, sectors,
 | `sentiment_fear_greed` | (defaults) | REQUIRED |
 | `finnhub_market_status` | (defaults) | REQUIRED |
 | `tradingview_sector_performance` | (defaults) | REQUIRED |
+| `market_breadth` | universe=major_us | REQUIRED |
 | `tradingview_top_gainers` | limit=10 | ENRICHMENT |
 | `tradingview_top_losers` | limit=10 | ENRICHMENT |
 | `tradingview_volume_breakout` | limit=10 | ENRICHMENT |
@@ -34,10 +35,11 @@ If any REQUIRED call fails, report the failure explicitly and proceed with avail
 
 DO NOT reproduce raw tool output. Cross-reference the collected data to answer:
 
-1. **Risk appetite agreement** -- Do index levels/futures direction and the Fear & Greed score point the same way? Flag any divergence as a caution signal.
-2. **Sector divergence** -- Which sectors diverge from the broad market direction? A defensive sector leading in a risk-on tape (or vice versa) is notable.
-3. **Volume clustering** -- Do volume breakout names cluster in one or two sectors? Flag as a potential rotation signal and name the sectors.
-4. **Catalyst check** -- Are any earnings or economic releases in the next 5 days likely to move the broad market or a specific sector? Highlight date, event, and expected impact.
+1. **Risk appetite agreement** -- Do index levels/futures direction, market breadth, and the Fear & Greed score point the same way? Flag any divergence as a caution signal.
+2. **Breadth confirmation** -- Are advancers/decliners, % above SMA50/SMA200, and new highs/lows confirming the index move or warning that leadership is narrow?
+3. **Sector divergence** -- Which sectors diverge from the broad market direction? A defensive sector leading in a risk-on tape (or vice versa) is notable.
+4. **Volume clustering** -- Do volume breakout names cluster in one or two sectors? Flag as a potential rotation signal and name the sectors.
+5. **Catalyst check** -- Are any earnings or economic releases in the next 5 days likely to move the broad market or a specific sector? Highlight date, event, and expected impact.
 
 ## Output Format
 
@@ -52,6 +54,10 @@ Include VIX, S&P 500, NASDAQ Composite, Dow Jones. Note market session status (p
 
 Single line: score, label (Extreme Fear / Fear / Neutral / Greed / Extreme Greed), and one-week trend direction.
 
+### Market Breadth
+
+Single line: advance/decline ratio, % above SMA50, % above SMA200, and whether new highs or new lows dominate.
+
 ### Sector Map
 
 | Sector | Change % | Signal |
@@ -83,5 +89,6 @@ Data from TradingView and Yahoo Finance is 15-minute delayed. CBOE and sentiment
 
 - Dumping raw JSON or full tool responses instead of synthesized tables.
 - Ignoring divergences between sentiment score and index direction -- these are the most valuable signals.
+- Ignoring weak breadth when indexes are green -- narrow leadership can invalidate a risk-on read.
 - Listing movers without connecting them to sector rotation or catalysts.
 - Stating a bias without citing the supporting data points that justify it.

package/skills/macro/macro-dashboard/SKILL.md

@@ -7,11 +7,11 @@ description: Build a comprehensive macroeconomic dashboard covering rates, infla
 
 ## Overview
 
-Act as a macro strategist. Collect key economic indicators, yield curve data, inflation metrics, labor market signals, and market sentiment to produce a unified macro picture. Cross-reference all data points to classify the current economic regime.
+Act as a macro strategist. Collect key economic indicators, yield curve data, inflation metrics, labor market signals, market breadth, and market sentiment to produce a unified macro picture. Cross-reference all data points to classify the current economic regime.
 
 **Prerequisite:** This skill requires FRED_API_KEY to be configured. Without it, only market indices and sentiment data are available.
 
-Announce at start: "Building macro dashboard -- collecting economic indicators, yield curve, inflation, labor, and sentiment data."
+Announce at start: "Building macro dashboard -- collecting economic indicators, yield curve, inflation, labor, breadth, and sentiment data."
 
 ## Data Collection
 
@@ -29,6 +29,7 @@ Announce at start: "Building macro dashboard -- collecting economic indicators,
 | `fred_indicator`           | series_id=initial_claims    | ENRICHMENT  |
 | `fred_economic_calendar`   | limit=15                    | REQUIRED    |
 | `tradingview_market_indices` | (default)                 | REQUIRED    |
+| `market_breadth`           | universe=major_us           | ENRICHMENT  |
 | `sentiment_fear_greed`     | (default)                   | ENRICHMENT  |
 
 DO NOT proceed to analysis until ALL REQUIRED calls return. ENRICHMENT failures are acceptable.
@@ -41,7 +42,7 @@ Cross-reference the collected data across five dimensions:
 2. **Inflation Trajectory** -- Compare CPI and Core PCE to the Fed's 2% target. Determine if inflation is accelerating, decelerating, or anchored.
 3. **Labor Market Health** -- Assess unemployment rate direction and initial claims trend. Rising claims with rising unemployment = deterioration.
 4. **Fed Policy Stance** -- Current Fed Funds rate vs inflation readings. Is policy restrictive (rate > inflation) or accommodative?
-5. **Market Pricing of Risk** -- Extract VIX from market indices. Combine with Fear & Greed score. Elevated VIX (>25) with extreme fear = stress.
+5. **Market Pricing of Risk** -- Extract VIX from market indices. Combine with Fear & Greed score and breadth. Elevated VIX (>25) with extreme fear and weak breadth = stress.
 
 Synthesize all five dimensions into a single macro regime classification.
 
@@ -75,6 +76,7 @@ DO NOT reproduce raw tool output. Synthesize and interpret.
 ### Market Risk Gauges
 - VIX level and interpretation
 - Fear & Greed score and classification
+- Market breadth: advance/decline ratio, % above SMA50/SMA200, and new highs/lows if available
 
 ### Upcoming Releases (Next 2 Weeks)
 List the most market-moving releases from the economic calendar with dates.
@@ -95,3 +97,4 @@ Data from TradingView and Yahoo Finance is 15-minute delayed. CBOE and sentiment
 - Forgetting to compute the yield curve spread (just listing 2Y and 10Y separately)
 - Classifying regime based on a single indicator instead of cross-referencing all five dimensions
 - Ignoring the direction/trend of indicators and only reporting the latest snapshot value
+- Ignoring market breadth when market indices and sentiment disagree

package/skills/macro/sector-rotation/SKILL.md

@@ -7,9 +7,9 @@ description: Analyze sector performance across timeframes, detect risk-on vs ris
 
 ## Overview
 
-Act as a sector strategist. Collect sector performance data across multiple timeframes, overlay technical signals on leaders and laggards, and determine whether capital is rotating toward risk-on or risk-off sectors. Produce actionable sector allocation guidance.
+Act as a sector strategist. Collect sector performance data across multiple timeframes, overlay market breadth and technical signals on leaders and laggards, and determine whether capital is rotating toward risk-on or risk-off sectors. Produce actionable sector allocation guidance.
 
-Announce at start: "Running sector rotation analysis -- collecting sector performance, market indices, and technical signals."
+Announce at start: "Running sector rotation analysis -- collecting sector performance, breadth, market indices, and technical signals."
 
 ## Data Collection
 
@@ -19,6 +19,7 @@ Announce at start: "Running sector rotation analysis -- collecting sector perfor
 |------------------------------|-----------------------|-------------|
 | `tradingview_sector_performance` | (default)         | REQUIRED    |
 | `tradingview_market_indices`     | (default)         | REQUIRED    |
+| `market_breadth`                 | universe=major_us | ENRICHMENT  |
 | `sentiment_fear_greed`           | (default)         | ENRICHMENT  |
 | `fred_indicator`                 | series_id=treasury_10y | ENRICHMENT |
 
@@ -39,7 +40,7 @@ DO NOT proceed to analysis until ALL REQUIRED calls return. ENRICHMENT failures
 Cross-reference the collected data across four dimensions:
 
 1. **Timeframe Divergence** -- Compare 1-day vs 1-week vs 1-month vs YTD performance for each sector. Short-term moves diverging from longer-term trends signal emerging rotation.
-2. **Risk Appetite** -- Defensive sectors (XLU, XLP, XLV) outperforming cyclicals (XLY, XLI, XLF) = RISK-OFF. Cyclicals outperforming defensives = RISK-ON. Mixed leadership = no clear signal.
+2. **Risk Appetite** -- Defensive sectors (XLU, XLP, XLV) outperforming cyclicals (XLY, XLI, XLF) = RISK-OFF. Cyclicals outperforming defensives = RISK-ON. Mixed leadership = no clear signal. Use breadth as confirmation: strong breadth confirms broad risk-on rotation; weak breadth implies narrow leadership.
 3. **Rate Sensitivity** -- Compare rate-sensitive sectors (XLU, XLRE) performance to 10Y yield direction. Rising yields should pressure these sectors. Outperformance despite rising yields is a strong signal.
 4. **Technical Confirmation** -- Use RSI and trend data from Wave 2 to confirm or contradict the rotation signal. Overbought leaders (RSI >70) may reverse. Oversold laggards (RSI <30) may bounce.
 
@@ -72,6 +73,9 @@ DO NOT reproduce raw tool output. Synthesize and interpret.
 ### Rate Sensitivity
 Note how rate-sensitive sectors (XLU, XLRE) are behaving relative to the current 10Y yield direction. Flag any divergence.
 
+### Breadth Confirmation
+State whether market breadth confirms or contradicts the sector rotation signal. Reference advance/decline ratio, % above SMA50/SMA200, and new highs/lows when available.
+
 ### Sector Picks
 
 **Overweight (top 2):**
@@ -90,3 +94,4 @@ Data from TradingView and Yahoo Finance is 15-minute delayed. CBOE and sentiment
 - Classifying rotation signal without comparing defensive vs cyclical sector groups explicitly
 - Skipping Wave 2 technicals and making sector picks without RSI or trend confirmation
 - Ignoring interest rate direction when assessing rate-sensitive sectors like Utilities and Real Estate
+- Treating leadership in one or two sectors as broad risk-on rotation without checking market breadth

package/skills/market-data/SKILL.md

@@ -8,29 +8,42 @@ description: Guidance on using stock and crypto market data tools effectively --
 ## Available Tool Categories
 
 ### Stock Technical Analysis (TradingView)
-- `tradingview_scan_indicators` -- full technical scan for a stock symbol
+- `tradingview_scan` -- custom stock scanner with filters and columns
+- `tradingview_quote` -- delayed quote for one or more tickers
+- `tradingview_technicals` -- RSI, MACD, moving averages, pivots, and ratings
+- `tradingview_market_indices` -- VIX, S&P 500, NASDAQ, Dow, and related index context
+- `tradingview_sector_performance` -- 11 sector ETFs across multiple timeframes
 - `tradingview_top_gainers` / `tradingview_top_losers` -- market movers
+- `tradingview_top_volume` -- highest volume stocks
 - `tradingview_volume_breakout` -- unusual volume detection
-- `tradingview_rating_filter` -- filter by buy/sell rating
+- Use `tradingview_scan` filters and columns for rating-based stock screens
+- `market_breadth` -- advance/decline ratio, % above SMA50/SMA200, and new highs/lows
 
 ### Crypto Technical Analysis (TradingView Crypto)
-- `crypto_scan_indicators` -- full technical scan for crypto pairs
-- `crypto_top_gainers` / `crypto_top_losers` -- crypto movers
-- `crypto_volume_breakout` -- unusual crypto volume
+- `crypto_scan` -- custom crypto scanner with filters and columns
+- `crypto_quote` -- quote and 24h change for crypto pairs
+- `crypto_technicals` -- RSI, MACD, moving averages, pivots, and ratings
+- `crypto_top_gainers` -- top gaining crypto pairs
 
 ### News & Events
 - `finnhub_company_news` -- recent company news (7-day lookback)
 - `finnhub_earnings_calendar` -- upcoming/recent earnings
-- `edgar_search_filings` -- search SEC 8-K filings
-- `edgar_recent_filings` -- recent material events
+- `edgar_search` -- search SEC filings by keyword, form, ticker, and date range
+- `edgar_company_filings` -- recent company filings
 
 ### Prices & Fundamentals
-- `alpha_vantage_quote` -- current price, volume, change
-- `alpha_vantage_daily_history` -- daily OHLCV (100 days)
-- `alpha_vantage_company_overview` -- PE, EPS, market cap, sector
+- `alphavantage_quote` -- current price, volume, change
+- `alphavantage_daily` -- daily OHLCV history
+- `alphavantage_overview` -- PE, EPS, market cap, sector
+
+### Social Sentiment
+- `reddit_trending` -- trending tickers from investing subreddits
+- `reddit_mentions` -- mentions and top posts for a ticker
+- `reddit_sentiment` -- keyword sentiment for a ticker
+- `reddit_watchlist_scan` -- batch scan watchlist tickers
 
 ### Crypto Market Data
-- `coingecko_coin_data` -- price, market cap, 24h volume
+- `coingecko_coin` -- price, market cap, 24h volume
 - `coingecko_trending` -- trending coins
 - `coingecko_global` -- total market cap, BTC dominance
 
@@ -38,11 +51,14 @@ description: Guidance on using stock and crypto market data tools effectively --
 
 | User Question | Tools to Use |
 |---|---|
-| "What do the charts say about AAPL?" | `tradingview_scan_indicators` |
+| "What do the charts say about AAPL?" | `tradingview_technicals`, `tradingview_quote` |
 | "What's moving today?" | `tradingview_top_gainers`, `tradingview_top_losers`, `tradingview_volume_breakout` |
-| "Any news on TSLA?" | `finnhub_company_news`, `edgar_recent_filings` |
-| "Is MSFT fairly valued?" | `alpha_vantage_company_overview`, `alpha_vantage_quote` |
-| "How's crypto doing?" | `coingecko_global`, `coingecko_trending`, `crypto_top_gainers` |
+| "How broad is this rally?" | `market_breadth`, `tradingview_market_indices` |
+| "What's the market regime?" | `tradingview_market_indices`, `market_breadth`, `sentiment_fear_greed`, `tradingview_sector_performance` |
+| "Any news on TSLA?" | `finnhub_company_news`, `edgar_company_filings` |
+| "Is MSFT fairly valued?" | `alphavantage_overview`, `alphavantage_quote` |
+| "How's crypto doing?" | `coingecko_global`, `coingecko_trending`, `crypto_top_gainers`, `crypto_quote` |
+| "What is Reddit focused on?" | `reddit_trending`, `reddit_mentions`, `reddit_sentiment` |
 | "Full analysis of AAPL" | All stock tools in parallel |
 
 ## Key Principles

package/skills/risk/risk-check/SKILL.md

@@ -34,6 +34,7 @@ Normalize ticker to uppercase. Set `ticker` variable.
 | `options_implied_move`        | symbol=ticker                               | REQUIRED    |
 | `finnhub_short_interest`      | symbol=ticker                               | REQUIRED    |
 | `finnhub_earnings_calendar`   | from=today, to=today+14, symbol=ticker      | REQUIRED    |
+| `market_breadth`              | universe=major_us                           | ENRICHMENT  |
 | `tradingview_sector_performance` |                                           | ENRICHMENT  |
 | `sentiment_fear_greed`        |                                             | ENRICHMENT  |
 | `options_max_pain`            | symbol=ticker                               | ENRICHMENT  |
@@ -71,6 +72,8 @@ After scoring, derive key levels:
 - Max pain: options max pain strike (if available)
 - Suggested stop: below nearest support level, or 2-3% below entry for a standard risk tolerance
 
+Use market breadth as qualitative context, not as a ninth flag. Weak breadth, low % above SMA50/SMA200, or expanding new lows should make sizing commentary more conservative when the flag score is already MODERATE or worse.
+
 ## Output Format
 
 ### [TICKER] -- Pre-Trade Risk Assessment
@@ -97,7 +100,7 @@ PASS = flag NOT triggered (favorable). FAIL = flag triggered (risk present).
 **Risk Score: X / 8 flags -- [LEVEL]**
 
 **Market Context**
-VIX level and trend, Fear & Greed index value and label, broad market direction.
+VIX level and trend, Fear & Greed index value and label, broad market direction, and breadth confirmation if available.
 
 **Sector Context**
 Stock's sector, sector rank today, top and bottom 3 sectors.
@@ -132,3 +135,5 @@ Data from TradingView and Yahoo Finance is 15-minute delayed. CBOE and sentiment
   see VIX=23.5 (PASS), not just PASS.
 - DO NOT give position sizing advice without referencing the flag count. Every
   sizing recommendation MUST tie back to the risk score.
+- DO NOT add market breadth as a ninth scored flag. Use it to qualify the
+  market context and sizing language only.

package/skills/workspace/workspace-morning-brief/SKILL.md

@@ -24,13 +24,14 @@ Based ONLY on the symbols found in the user's workspace, fetch relevant data usi
 - **Crypto Exposure Check:** If the watchlist contains crypto-exposed equities (e.g., MARA, CIFR, COIN) or Bitcoin, you MUST fetch the current price and 24h change of BTC (using `tradingview_quote` for `BINANCE:BTCUSDT`). Evaluate the correlation and note if the stocks are tracking or diverging from the BTC move.
 - **Event Risk Check:** For active equity names (e.g., HOOD, SOFI), check for upcoming earnings today using `finnhub_earnings_calendar` and recent news using `finnhub_company_news`.
 - **Risk Tone Check:** If the watchlist contains Gold or Silver (or proxies like GLD/SLV), fetch their current prices. Note any sharp moves that might change the overall market risk tone.
-- **Market Pulse:** Fetch a basic S&P 500 / VIX quote (`tradingview_quote` for `SPY` and `VIX`) to establish the baseline market direction.
+- **Market Pulse:** Fetch a basic S&P 500 / VIX quote (`tradingview_quote` for `SPY` and `VIX`) plus `market_breadth` with universe=major_us to establish whether the baseline market direction is broad or narrow.
 
 ### STEP 3: SYNTHESIZE THE BRIEF
 Do NOT give a generic, broad market recap. Structure your response to answer the following questions specifically about the user's watchlist:
 
 #### 1. What Matters Today
 Highlight the overarching theme for the user's specific portfolio (e.g., "Crypto proxies are leading the market today," or "A defensive risk-off tone driven by a drop in Gold").
+Include whether broad-market breadth supports or contradicts that theme when it affects the user's saved names.
 
 #### 2. Active Names & Event Risk
 List the tickers from the watchlist that are moving significantly (pre-market or early trading) or have an immediate catalyst (Earnings, News, Options Flow).