tn-financial-data 0.3.0 → 0.3.1

package/README.md

@@ -28,6 +28,7 @@ This package is the hosted agent-facing surface only. The repo's website, local
 - Company facts, financials, prices, news, insider trades, ownership, global rates, and raw SEC filings through one hosted API
 - Multi-ticker resolve and snapshot reads for lower-latency agent workflows
 - Earnings calendar, dividends, and stock splits through the same hosted read contract
+- Cross-ticker news search over article title, summary, and body text with ticker, provider, publisher, and date filters
 - Agent-friendly CLI with clean error output, scoped subcommand help, and self-description via `tn-financial-data describe opencli`
 - Packaged skill bundle for Claude and OpenCode installs
 - Typed TypeScript client from the root package export
@@ -73,6 +74,7 @@ tn-financial-data query financial-metrics-snapshot --tickers AAPL,MSFT,NVDA --pe
 tn-financial-data query earnings-calendar --tickers AAPL,MSFT --start-date 2026-04-02 --end-date 2026-04-16
 tn-financial-data query dividends --ticker AAPL --limit 10
 tn-financial-data query company --ticker AAPL
+tn-financial-data query news-search --query "tariff semiconductor" --ticker NVDA --limit 10
 tn-financial-data query filings --ticker AAPL --filing-type 8-K --limit 5
 tn-financial-data query general-overview --ticker AAPL --period quarterly --financial-limit 4 --news-limit 5
 tn-financial-data skill install --tool claude
@@ -108,6 +110,8 @@ tn-financial-data query splits --ticker AAPL --limit 10
 tn-financial-data query filings --ticker AAPL --filing-type 10-K,10-Q,8-K --limit 10
 tn-financial-data query filing-items --ticker AAPL --accession-number 0000320193-26-000005 --item 2.02 --include-exhibits
 tn-financial-data query prices --ticker AAPL --interval day --start-date 2025-01-01 --end-date 2025-01-31
+tn-financial-data query news --ticker AAPL --limit 10
+tn-financial-data query news-search --query "AI data center" --provider alpaca --limit 10
 tn-financial-data query institutional-ownership --ticker AAPL --limit 20
 tn-financial-data query investor-portfolio --investor vanguard --limit 20
 tn-financial-data query global-rates --series ecb_refi,boe_sonia --limit 10
@@ -205,6 +209,14 @@ const filings = await client.getFilings("AAPL", {
 
 console.log(filings.filings[0]?.accession_number);
 
+const news = await client.searchNews("AI data center", {
+  ticker: "NVDA",
+  provider: "alpaca",
+  limit: 5,
+});
+
+console.log(news.news[0]?.title, news.count);
+
 const filingItems = await client.getFilingItems("AAPL", {
   accessionNumber: "0000320193-26-000005",
   filingType: "8-K",

package/dist/cli.js

@@ -202,6 +202,13 @@ var TnFinancialData = class {
     if (opts?.endDate) params.set("end_date", opts.endDate);
     return params.toString();
   }
+  buildNewsParams(params, opts) {
+    if (opts?.limit !== void 0) params.set("limit", String(opts.limit));
+    if (opts?.startDate) params.set("start_date", opts.startDate);
+    if (opts?.endDate) params.set("end_date", opts.endDate);
+    if (opts?.publisher) params.set("publisher", opts.publisher);
+    return params.toString();
+  }
   buildFilingsParams(ticker, opts) {
     const params = new URLSearchParams({ ticker });
     this.appendLimitParam(params, opts?.limit);
@@ -317,11 +324,14 @@ var TnFinancialData = class {
   }
   async getNews(ticker, opts) {
     const params = new URLSearchParams({ ticker });
-    if (opts?.limit !== void 0) params.set("limit", String(opts.limit));
-    if (opts?.startDate) params.set("start_date", opts.startDate);
-    if (opts?.endDate) params.set("end_date", opts.endDate);
-    if (opts?.publisher) params.set("publisher", opts.publisher);
-    return this.request(`/news?${params}`);
+    return this.request(`/news?${this.buildNewsParams(params, opts)}`);
+  }
+  async searchNews(query, opts) {
+    const params = new URLSearchParams({ q: query });
+    if (opts?.ticker) params.set("ticker", opts.ticker);
+    if (opts?.offset !== void 0) params.set("offset", String(opts.offset));
+    if (opts?.provider) params.set("provider", opts.provider);
+    return this.request(`/news/search?${this.buildNewsParams(params, opts)}`);
   }
   async getDividends(ticker, opts) {
     return this.request(
@@ -551,6 +561,13 @@ function parsePositiveInt(value, optionName) {
   }
   return parsed;
 }
+function parseNonNegativeInt(value, optionName) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    throw new CliUsageError(`--${optionName} must be a non-negative integer.`);
+  }
+  return parsed;
+}
 function parseCsvValues(value, optionName) {
   const parts = value.split(",").map((part) => part.trim()).filter((part) => part.length > 0);
   if (parts.length === 0) {
@@ -649,7 +666,7 @@ function rootHelp() {
     "tn-financial-data",
     "",
     "Usage:",
-    "  tn-financial-data query <available-tickers|resolve-ticker|company|filings|filing-items|general-overview|financials|financial-metrics|financial-metrics-snapshot|earnings|earnings-calendar|quarterly-highlights|analyst-estimates|prices|snapshot|dividends|splits|news|insider-trades|institutional-ownership|investor-portfolio|global-rates|segmented-revenues|screen|screen-fields> [options]",
+    "  tn-financial-data query <available-tickers|resolve-ticker|company|filings|filing-items|general-overview|financials|financial-metrics|financial-metrics-snapshot|earnings|earnings-calendar|quarterly-highlights|analyst-estimates|prices|snapshot|dividends|splits|news|news-search|insider-trades|institutional-ownership|investor-portfolio|global-rates|segmented-revenues|screen|screen-fields> [options]",
     "  tn-financial-data skill <install|print|targets> [--tool claude|opencode]",
     "  tn-financial-data describe opencli",
     "  tn-financial-data --version",
@@ -673,6 +690,7 @@ function rootHelp() {
     "  tn-financial-data query prices --ticker AAPL --interval day --start-date 2025-01-01 --end-date 2025-01-31",
     "  tn-financial-data query dividends --ticker AAPL --limit 20",
     "  tn-financial-data query splits --ticker AAPL --limit 20",
+    '  tn-financial-data query news-search --query "tariff semiconductor" --ticker NVDA --limit 10',
     "  tn-financial-data query insider-trades --ticker AAPL --transaction-code P,S --limit 25",
     "  tn-financial-data query institutional-ownership --ticker AAPL --limit 20",
     "  tn-financial-data query investor-portfolio --investor vanguard --limit 20",
@@ -713,6 +731,7 @@ function queryHelp() {
     "  tn-financial-data query dividends --ticker <symbol> [--start-date <date>] [--end-date <date>] [--limit <n>] [--api-key <key>] [--base-url <url>]",
     "  tn-financial-data query splits --ticker <symbol> [--start-date <date>] [--end-date <date>] [--limit <n>] [--api-key <key>] [--base-url <url>]",
     "  tn-financial-data query news --ticker <symbol> [--start-date <date>] [--end-date <date>] [--publisher <name>] [--limit <n>] [--api-key <key>] [--base-url <url>]",
+    "  tn-financial-data query news-search --query <text> [--ticker <symbol>] [--start-date <date>] [--end-date <date>] [--publisher <name>] [--provider <id>] [--limit <n>] [--offset <n>] [--api-key <key>] [--base-url <url>]",
     "  tn-financial-data query insider-trades --ticker <symbol> [--start-date <date>] [--end-date <date>] [--reporting-owner-cik <cik>] [--transaction-code <csv>] [--security-type <all|non_derivative|derivative>] [--limit <n>] [--api-key <key>] [--base-url <url>]",
     "  tn-financial-data query institutional-ownership --ticker <symbol> [--limit <n>] [--api-key <key>] [--base-url <url>]",
     "  tn-financial-data query investor-portfolio (--cik <cik> | --investor <alias>) [--limit <n>] [--api-key <key>] [--base-url <url>]",
@@ -837,6 +856,7 @@ function buildOpenCliDocument() {
       "tn-financial-data query prices --ticker AAPL --interval day --start-date 2025-01-01 --end-date 2025-01-31",
       "tn-financial-data query dividends --ticker AAPL --limit 20",
       "tn-financial-data query splits --ticker AAPL --limit 20",
+      'tn-financial-data query news-search --query "tariff semiconductor" --ticker NVDA --limit 10',
       "tn-financial-data query insider-trades --ticker AAPL --transaction-code P,S --limit 25",
       "tn-financial-data query institutional-ownership --ticker AAPL --limit 20",
       "tn-financial-data query investor-portfolio --investor vanguard --limit 20",
@@ -1640,6 +1660,61 @@ function buildOpenCliDocument() {
               }
             ]
           },
+          {
+            name: "news-search",
+            description: "Search canonical news articles across the covered ticker universe.",
+            options: [
+              {
+                name: "query",
+                required: true,
+                arguments: [{ name: "text", required: true, description: "Search query." }],
+                description: "Plain-text search query."
+              },
+              {
+                name: "ticker",
+                arguments: [{ name: "ticker", required: true, description: "Ticker symbol." }],
+                description: "Optional ticker filter."
+              },
+              {
+                name: "start-date",
+                arguments: [{ name: "date", required: true, description: "Filter start date." }],
+                description: "Inclusive start date for search results."
+              },
+              {
+                name: "end-date",
+                arguments: [{ name: "date", required: true, description: "Filter end date." }],
+                description: "Inclusive end date for search results."
+              },
+              {
+                name: "publisher",
+                arguments: [
+                  { name: "publisher", required: true, description: "Publisher name filter." }
+                ],
+                description: "Filter by publisher name."
+              },
+              {
+                name: "provider",
+                arguments: [
+                  { name: "provider", required: true, description: "Provider id filter." }
+                ],
+                description: "Filter by provider id, for example alpaca."
+              },
+              {
+                name: "limit",
+                arguments: [
+                  { name: "limit", required: true, description: "Positive integer, max 100." }
+                ],
+                description: "Maximum number of search results to return."
+              },
+              {
+                name: "offset",
+                arguments: [
+                  { name: "offset", required: true, description: "Non-negative integer." }
+                ],
+                description: "Zero-based pagination offset."
+              }
+            ]
+          },
           {
             name: "insider-trades",
             description: "Fetch stored SEC Form 4 insider-trade line items for one ticker, including derivative and non-derivative transactions.",
@@ -2151,6 +2226,23 @@ var QUERY_SUBCOMMAND_HELP = {
     ],
     "tn-financial-data query news --ticker AAPL --limit 10"
   ),
+  "news-search": renderHelp(
+    "news-search",
+    ["Search canonical news articles across the covered ticker universe."],
+    [
+      "--query <text>      Required. Plain-text search query.",
+      "--ticker <symbol>   Optional covered ticker filter.",
+      "--start-date <date> Optional start date (YYYY-MM-DD).",
+      "--end-date <date>   Optional end date (YYYY-MM-DD).",
+      "--publisher <name>  Optional publisher filter.",
+      "--provider <id>     Optional provider filter, for example alpaca.",
+      "--limit <n>         Number of articles to return. Max 100.",
+      "--offset <n>        Optional zero-based pagination offset.",
+      "--api-key <key>     API key. Overrides TN_FINANCIAL_DATA_API_KEY.",
+      "--base-url <url>    API base URL override."
+    ],
+    'tn-financial-data query news-search --query "tariff semiconductor" --ticker NVDA --limit 10'
+  ),
   "insider-trades": renderHelp(
     "insider-trades",
     ["Fetch SEC Form 4 insider-trade rows for a single issuer."],
@@ -2677,6 +2769,26 @@ async function handleQuery(parsed, runtime, deps) {
       );
       return 0;
     }
+    case "news-search": {
+      const query = requireOption(parsed, "query");
+      const limit = getOption(parsed, "limit");
+      const offset = getOption(parsed, "offset");
+      const options = {
+        ticker: getOption(parsed, "ticker"),
+        startDate: getOption(parsed, "start-date"),
+        endDate: getOption(parsed, "end-date"),
+        publisher: getOption(parsed, "publisher"),
+        provider: getOption(parsed, "provider")
+      };
+      if (limit) {
+        options.limit = parsePositiveInt(limit, "limit");
+      }
+      if (offset) {
+        options.offset = parseNonNegativeInt(offset, "offset");
+      }
+      printJson(runtime, await client.searchNews(query, options));
+      return 0;
+    }
     case "insider-trades": {
       const ticker = requireOption(parsed, "ticker");
       const limit = getOption(parsed, "limit");

package/dist/client/index.d.ts

@@ -384,6 +384,10 @@ interface NewsArticle {
     summary: string | null;
     refreshed_at: string;
 }
+interface NewsSearchArticle extends NewsArticle {
+    provider: string | null;
+    relevance: number | null;
+}
 interface ReadMetadata {
     ticker: string;
     availability: DataAvailability;
@@ -423,6 +427,15 @@ interface NewsOpts {
     endDate?: string;
     publisher?: string;
 }
+interface NewsSearchOpts {
+    ticker?: string;
+    limit?: number;
+    offset?: number;
+    startDate?: string;
+    endDate?: string;
+    publisher?: string;
+    provider?: string;
+}
 interface CorporateActionsOpts {
     limit?: number;
     startDate?: string;
@@ -615,6 +628,14 @@ interface PriceHistoryResponse extends ReadMetadata {
 interface NewsResponse extends ReadMetadata {
     news: NewsArticle[];
 }
+interface NewsSearchResponse {
+    query: string;
+    count: number;
+    limit: number;
+    offset: number;
+    has_more: boolean;
+    news: NewsSearchArticle[];
+}
 interface DividendsResponse extends ReadMetadata {
     count: number;
     limit: number;
@@ -924,6 +945,7 @@ declare class TnFinancialData {
     private buildEarningsCalendarParams;
     private buildInsiderTradeParams;
     private buildCorporateActionsParams;
+    private buildNewsParams;
     private buildFilingsParams;
     private buildFilingItemsParams;
     getIncomeStatements(ticker: string, opts: FinancialOpts): Promise<ApiResponse<IncomeStatementsResponse>>;
@@ -944,6 +966,7 @@ declare class TnFinancialData {
     getPriceSnapshot(ticker: string): Promise<ApiResponse<PriceSnapshotResponse>>;
     getBatchPriceSnapshots(tickers: readonly string[]): Promise<ApiResponse<BatchPriceSnapshotsResponse>>;
     getNews(ticker: string, opts?: NewsOpts): Promise<ApiResponse<NewsResponse>>;
+    searchNews(query: string, opts?: NewsSearchOpts): Promise<ApiResponse<NewsSearchResponse>>;
     getDividends(ticker: string, opts?: CorporateActionsOpts): Promise<ApiResponse<DividendsResponse>>;
     getSplits(ticker: string, opts?: CorporateActionsOpts): Promise<ApiResponse<SplitsResponse>>;
     getInsiderTrades(ticker: string, opts?: InsiderTradesOpts): Promise<ApiResponse<InsiderTradesResponse>>;
@@ -962,4 +985,4 @@ declare class TnFinancialData {
     screen(request: ScreenerRequest): Promise<ApiResponse<ScreenerResponse>>;
 }
 
-export { type AnalystEstimate, type AnalystEstimatesResponse, type AnalystPriceTarget, ApiError, type ApiResponse, type AvailableTicker, type AvailableTickersResponse, type BalanceSheet, type BalanceSheetsResponse, type BatchFinancialMetricsSnapshotEntry, type BatchFinancialMetricsSnapshotsResponse, type BatchNotFoundEntry, type BatchPriceSnapshotEntry, type BatchPriceSnapshotsResponse, type BatchTickerResolutionResponse, type CashFlowStatement, type CashFlowStatementsResponse, type ClientOptions, type CompanyFacts, type ConsensusSurprise, type CorporateActionsOpts, DEFAULT_API_BASE_URL, type DataAvailability, type DividendEvent, type DividendsResponse, type EarningsCalendarEvent, type EarningsCalendarOpts, type EarningsCalendarResponse, type EarningsOpts, type EarningsResponse, type EarningsRow, type FilingExhibit, type FilingItemSection, type FilingItemsOpts, type FilingItemsResponse, type FilingMetadata, type FilingsOpts, type FilingsResponse, type FinancialMetric, type FinancialMetricsOpts, type FinancialMetricsResponse, type FinancialMetricsSnapshotResponse, type FinancialOpts, type FinancialsResponse, type GeneralOverviewFinancials, type GeneralOverviewNews, type GeneralOverviewOpts, type GeneralOverviewPriceSnapshot, type GeneralOverviewResponse, type GlobalInterestRateObservation, type GlobalInterestRateSeries, type GlobalInterestRatesOpts, type GlobalInterestRatesResponse, type IncomeStatement, type IncomeStatementsResponse, type InsiderTrade, type InsiderTradesOpts, type InsiderTradesResponse, type InstitutionalOwnershipEntry, type InstitutionalOwnershipOpts, type InstitutionalOwnershipResponse, type InvestorPortfolioHolding, type InvestorPortfolioInvestor, type InvestorPortfolioOpts, type InvestorPortfolioResponse, type InvestorPortfolioSummary, type KeyStatistics, type KeyStatisticsResponse, type NewsArticle, type NewsOpts, type NewsResponse, type OptionalFinancialQueryOpts, type PriceBar, type PriceHistoryResponse, type PriceOpts, type PriceSnapshot, type PriceSnapshotResponse, type QuarterlyHighlightsMetric, type QuarterlyHighlightsOpts, type QuarterlyHighlightsPayload, type QuarterlyHighlightsResponse, type RateLimitAnnotatedResponse, type RateLimitInfo, type ReadMetadata, type ReportPeriodFilterOpts, type ScreenerFieldMetadata, type ScreenerFieldsResponse, type ScreenerRequest, type ScreenerResponse, type ScreenerResultRow, type SegmentedRevenueItem, type SegmentedRevenuePeriod, type SegmentedRevenuesOpts, type SegmentedRevenuesResponse, type SnakeCase, type SplitEvent, type SplitsResponse, type TickerResolutionCandidate, type TickerResolutionConfidence, type TickerResolutionIntent, type TickerResolutionMatchKind, type TickerResolutionRelationship, type TickerResolutionResponse, type TickerResolutionStatus, TnFinancialData };
+export { type AnalystEstimate, type AnalystEstimatesResponse, type AnalystPriceTarget, ApiError, type ApiResponse, type AvailableTicker, type AvailableTickersResponse, type BalanceSheet, type BalanceSheetsResponse, type BatchFinancialMetricsSnapshotEntry, type BatchFinancialMetricsSnapshotsResponse, type BatchNotFoundEntry, type BatchPriceSnapshotEntry, type BatchPriceSnapshotsResponse, type BatchTickerResolutionResponse, type CashFlowStatement, type CashFlowStatementsResponse, type ClientOptions, type CompanyFacts, type ConsensusSurprise, type CorporateActionsOpts, DEFAULT_API_BASE_URL, type DataAvailability, type DividendEvent, type DividendsResponse, type EarningsCalendarEvent, type EarningsCalendarOpts, type EarningsCalendarResponse, type EarningsOpts, type EarningsResponse, type EarningsRow, type FilingExhibit, type FilingItemSection, type FilingItemsOpts, type FilingItemsResponse, type FilingMetadata, type FilingsOpts, type FilingsResponse, type FinancialMetric, type FinancialMetricsOpts, type FinancialMetricsResponse, type FinancialMetricsSnapshotResponse, type FinancialOpts, type FinancialsResponse, type GeneralOverviewFinancials, type GeneralOverviewNews, type GeneralOverviewOpts, type GeneralOverviewPriceSnapshot, type GeneralOverviewResponse, type GlobalInterestRateObservation, type GlobalInterestRateSeries, type GlobalInterestRatesOpts, type GlobalInterestRatesResponse, type IncomeStatement, type IncomeStatementsResponse, type InsiderTrade, type InsiderTradesOpts, type InsiderTradesResponse, type InstitutionalOwnershipEntry, type InstitutionalOwnershipOpts, type InstitutionalOwnershipResponse, type InvestorPortfolioHolding, type InvestorPortfolioInvestor, type InvestorPortfolioOpts, type InvestorPortfolioResponse, type InvestorPortfolioSummary, type KeyStatistics, type KeyStatisticsResponse, type NewsArticle, type NewsOpts, type NewsResponse, type NewsSearchArticle, type NewsSearchOpts, type NewsSearchResponse, type OptionalFinancialQueryOpts, type PriceBar, type PriceHistoryResponse, type PriceOpts, type PriceSnapshot, type PriceSnapshotResponse, type QuarterlyHighlightsMetric, type QuarterlyHighlightsOpts, type QuarterlyHighlightsPayload, type QuarterlyHighlightsResponse, type RateLimitAnnotatedResponse, type RateLimitInfo, type ReadMetadata, type ReportPeriodFilterOpts, type ScreenerFieldMetadata, type ScreenerFieldsResponse, type ScreenerRequest, type ScreenerResponse, type ScreenerResultRow, type SegmentedRevenueItem, type SegmentedRevenuePeriod, type SegmentedRevenuesOpts, type SegmentedRevenuesResponse, type SnakeCase, type SplitEvent, type SplitsResponse, type TickerResolutionCandidate, type TickerResolutionConfidence, type TickerResolutionIntent, type TickerResolutionMatchKind, type TickerResolutionRelationship, type TickerResolutionResponse, type TickerResolutionStatus, TnFinancialData };

package/dist/client/index.js

@@ -200,6 +200,13 @@ var TnFinancialData = class {
     if (opts?.endDate) params.set("end_date", opts.endDate);
     return params.toString();
   }
+  buildNewsParams(params, opts) {
+    if (opts?.limit !== void 0) params.set("limit", String(opts.limit));
+    if (opts?.startDate) params.set("start_date", opts.startDate);
+    if (opts?.endDate) params.set("end_date", opts.endDate);
+    if (opts?.publisher) params.set("publisher", opts.publisher);
+    return params.toString();
+  }
   buildFilingsParams(ticker, opts) {
     const params = new URLSearchParams({ ticker });
     this.appendLimitParam(params, opts?.limit);
@@ -315,11 +322,14 @@ var TnFinancialData = class {
   }
   async getNews(ticker, opts) {
     const params = new URLSearchParams({ ticker });
-    if (opts?.limit !== void 0) params.set("limit", String(opts.limit));
-    if (opts?.startDate) params.set("start_date", opts.startDate);
-    if (opts?.endDate) params.set("end_date", opts.endDate);
-    if (opts?.publisher) params.set("publisher", opts.publisher);
-    return this.request(`/news?${params}`);
+    return this.request(`/news?${this.buildNewsParams(params, opts)}`);
+  }
+  async searchNews(query, opts) {
+    const params = new URLSearchParams({ q: query });
+    if (opts?.ticker) params.set("ticker", opts.ticker);
+    if (opts?.offset !== void 0) params.set("offset", String(opts.offset));
+    if (opts?.provider) params.set("provider", opts.provider);
+    return this.request(`/news/search?${this.buildNewsParams(params, opts)}`);
   }
   async getDividends(ticker, opts) {
     return this.request(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tn-financial-data",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Hosted US equity financial data and SEC filings CLI and client for agents",
   "keywords": [
     "agent",

package/skills/tn-financial-data/references/cli.md

@@ -13,6 +13,7 @@ Auth rule:
 - for ambiguous company, brand, or free-form one-company prompts, start with `resolve-ticker`
 - for broad ticker prompts like "what's up with NVDA?", start with `general-overview`
 - for covered recent-news prompts like "show me recent Nvidia news", start with `news`
+- for cross-ticker headline/theme prompts like "search semiconductor tariff news", start with `news-search`
 - for latest-quarter product mix, supplemental KPIs, AWS segment profitability, or Tesla free-cash-flow prompts, start with `quarterly-highlights`
 - for Apple product mix specifically, do not start with `segmented-revenues`; that surface only exposes broad `Product` and `Service` rollups, while `quarterly-highlights` carries `iPhone`, `Mac`, `iPad`, `Wearables, Home and Accessories`, and `Services`
 - for compare prompts, try to use matching command families and comparable periods across the names
@@ -246,6 +247,19 @@ Meaning:
 - use it before web search when the stored dataset can answer
 - optionally pair with `snapshot` or `general-overview` if the user needs price or broader company context
 
+News search:
+
+```bash
+tn-financial-data query news-search --query "tariff semiconductor" --ticker NVDA --limit 20
+tn-financial-data query news-search --query "AI data center" --provider alpaca --offset 20
+```
+
+Meaning:
+- article-centric search across the stored covered-news corpus
+- use it for cross-ticker topic scans, theme tracking, or when the user gives keywords instead of one issuer
+- supports optional `--ticker`, `--publisher`, `--provider`, `--start-date`, `--end-date`, `--limit`, and `--offset`
+- search results include provider and relevance metadata; do not assume the first result is the only relevant one when `has_more` is true
+
 Insider trades:
 
 ```bash