tn-financial-data 0.4.0 → 0.4.2

package/README.md

@@ -1,6 +1,6 @@
 # tn-financial-data
 
-Hosted US equity financial data and SEC filings for agents.
+Hosted US equity, macro, SEC filings, and earnings transcript coverage for agents.
 
 `tn-financial-data` is the published agent-facing surface for the hosted API:
 
@@ -25,10 +25,11 @@ This package is the hosted agent-facing surface only. The repo's website, local
 
 ## Features
 
-- Company facts, financials, prices, news, insider trades, ownership, earnings transcript structure, stored macro history, and raw SEC filings through one hosted API
+- Company facts, financials, prices, canonical issuer news, insider trades, ownership, earnings transcript structure and coverage, stored macro history, 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
+- Canonical issuer-scoped `news` plus cross-ticker `news-search` over article title, summary, and body text with ticker, publisher, and date filters
+- `news` and `news-search` responses include `body_text` when stored article content is available
 - 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
@@ -57,6 +58,7 @@ Optional base URL override:
 The published CLI reads those values from the current process environment only.
 Use `resolve-ticker` to map company or brand input to supported symbols.
 Treat `available-tickers` as the authoritative support list for exact symbols; do not silently swap an unsupported exact ticker to a different share class.
+`available-tickers` is the equity-symbol snapshot only; covered macro series are queried through `global-rates`, `us-rates`, and `us-economic-indicators`.
 
 Production default:
 
@@ -90,6 +92,11 @@ Ownership semantics:
 - `institutional-ownership` is issuer-centric: ticker to holders
 - `investor-portfolio` is investor-centric: filer to holdings via SEC 13F
 
+Macro note:
+
+- `us_cpi` is the raw CPI index level, not a precomputed inflation transform
+- For MoM or YoY CPI prompts, derive the percentage change from adjacent observations returned by `us-economic-indicators`
+
 ## Commands
 
 | Command | Description |
@@ -118,7 +125,7 @@ tn-financial-data query filings --ticker AAPL --filing-type 10-K,10-Q,8-K --limi
 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 news-search --query "AI data center" --publisher Reuters --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
@@ -209,12 +216,15 @@ const calendar = await client.getEarningsCalendar({
 
 console.log(calendar.events.map((row) => `${row.ticker}:${row.event_date_start}`));
 
-const transcripts = await client.getEarningsTranscripts({
-  ticker: "NVDA",
+const transcripts = await client.getEarningsTranscripts("NVDA", {
   limit: 1,
 });
 
-console.log(transcripts.transcripts[0]?.quarter_label, transcripts.transcripts[0]?.question_count);
+console.log(
+  transcripts.transcript_coverage.status,
+  transcripts.transcripts[0]?.quarter_label,
+  transcripts.transcripts[0]?.question_count,
+);
 
 const usRates = await client.getUsInterestRates({
   series: ["us_treasury_10y", "fed_funds_rate"],
@@ -234,7 +244,7 @@ console.log(filings.filings[0]?.accession_number);
 
 const news = await client.searchNews("AI data center", {
   ticker: "NVDA",
-  provider: "alpaca",
+  publisher: "Reuters",
   limit: 5,
 });
 

package/dist/cli.js

@@ -336,7 +336,6 @@ var TnFinancialData = class {
     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) {
@@ -753,7 +752,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 news-search --query <text> [--ticker <symbol>] [--start-date <date>] [--end-date <date>] [--publisher <name>] [--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>]",
@@ -929,7 +928,7 @@ function buildOpenCliDocument() {
         commands: [
           {
             name: "available-tickers",
-            description: "Fetch the current supported ticker snapshot with financial and news freshness timestamps."
+            description: "Fetch the current supported ticker snapshot for the equity universe with financial and news freshness timestamps."
           },
           {
             name: "resolve-ticker",
@@ -1385,7 +1384,7 @@ function buildOpenCliDocument() {
           },
           {
             name: "earnings-transcripts",
-            description: "Fetch normalized earnings call transcript metadata, participants, and speaker-turn structure for a single ticker.",
+            description: "Fetch normalized earnings call transcript metadata, participants, speaker-turn structure, and latest transcript coverage status for a single ticker.",
             options: [
               {
                 name: "ticker",
@@ -1637,7 +1636,7 @@ function buildOpenCliDocument() {
           },
           {
             name: "us-economic-indicators",
-            description: "Fetch US CPI, GDP, and unemployment series with historical observations.",
+            description: "Fetch US CPI, GDP, and unemployment series with historical observations. Returns raw series levels for client-side MoM or YoY transforms when needed.",
             options: [
               {
                 name: "series",
@@ -1754,7 +1753,7 @@ function buildOpenCliDocument() {
           },
           {
             name: "news",
-            description: "Fetch news articles for a single ticker.",
+            description: "Fetch canonical news articles for a single ticker, including body_text when available.",
             options: [
               {
                 name: "ticker",
@@ -1790,7 +1789,7 @@ function buildOpenCliDocument() {
           },
           {
             name: "news-search",
-            description: "Search canonical news articles across the covered ticker universe.",
+            description: "Search canonical news articles across the covered ticker universe, including body_text when available.",
             options: [
               {
                 name: "query",
@@ -1820,13 +1819,6 @@ function buildOpenCliDocument() {
                 ],
                 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: [
@@ -2180,7 +2172,10 @@ function renderHelp(command, description, options, example) {
 var QUERY_SUBCOMMAND_HELP = {
   "available-tickers": renderHelp(
     "available-tickers",
-    ["List tickers currently supported by the hosted read API."],
+    [
+      "List stock tickers currently supported by the hosted read API.",
+      "This is the equity support snapshot only; covered macro series live under global-rates, us-rates, and us-economic-indicators."
+    ],
     [
       "--api-key <key>    API key. Overrides TN_FINANCIAL_DATA_API_KEY.",
       "--base-url <url>   API base URL override."
@@ -2323,7 +2318,8 @@ var QUERY_SUBCOMMAND_HELP = {
   "earnings-transcripts": renderHelp(
     "earnings-transcripts",
     [
-      "Fetch normalized earnings call transcript metadata, participants, and speaker-turn structure for a single ticker."
+      "Fetch normalized earnings call transcript metadata, participants, speaker-turn structure, and latest transcript coverage status for a single ticker.",
+      "This surface does not return full transcript prose; use it for structure and coverage, not direct quotes or management-language analysis."
     ],
     [
       "--ticker <symbol>      Required. Stock ticker symbol.",
@@ -2425,7 +2421,9 @@ var QUERY_SUBCOMMAND_HELP = {
   ),
   news: renderHelp(
     "news",
-    ["Fetch curated issuer news for a single ticker."],
+    [
+      "Fetch canonical news articles for a single ticker. Returns `body_text` when article content is available."
+    ],
     [
       "--ticker <symbol>   Required. Stock ticker symbol.",
       "--start-date <date> Optional start date (YYYY-MM-DD).",
@@ -2439,14 +2437,15 @@ var QUERY_SUBCOMMAND_HELP = {
   ),
   "news-search": renderHelp(
     "news-search",
-    ["Search canonical news articles across the covered ticker universe."],
+    [
+      "Search canonical news articles across the covered ticker universe. Returns `body_text` when article content is available."
+    ],
     [
       "--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.",
@@ -2521,7 +2520,10 @@ var QUERY_SUBCOMMAND_HELP = {
   ),
   "us-economic-indicators": renderHelp(
     "us-economic-indicators",
-    ["Fetch stored US CPI, GDP, and unemployment history from the hosted API."],
+    [
+      "Fetch stored US CPI, GDP, and unemployment history from the hosted API.",
+      "Returns raw series levels; derive MoM or YoY percentage changes from adjacent observations when needed."
+    ],
     [
       "--series <csv>      Optional comma-separated US economic indicator keys.",
       "--start-date <date> Optional start date (YYYY-MM-DD).",
@@ -3039,8 +3041,7 @@ async function handleQuery(parsed, runtime, deps) {
         ticker: getOption(parsed, "ticker"),
         startDate: getOption(parsed, "start-date"),
         endDate: getOption(parsed, "end-date"),
-        publisher: getOption(parsed, "publisher"),
-        provider: getOption(parsed, "provider")
+        publisher: getOption(parsed, "publisher")
       };
       if (limit) {
         options.limit = parsePositiveInt(limit, "limit");

package/dist/client/index.d.ts

@@ -386,10 +386,10 @@ interface NewsArticle {
     type: string | null;
     link: string | null;
     summary: string | null;
+    body_text: string | null;
     refreshed_at: string;
 }
 interface NewsSearchArticle extends NewsArticle {
-    provider: string | null;
     relevance: number | null;
 }
 interface ReadMetadata {
@@ -438,7 +438,6 @@ interface NewsSearchOpts {
     startDate?: string;
     endDate?: string;
     publisher?: string;
-    provider?: string;
 }
 interface CorporateActionsOpts {
     limit?: number;
@@ -580,7 +579,18 @@ interface EarningsTranscript {
     participants: EarningsTranscriptParticipant[];
     speaker_turns: EarningsTranscriptSpeakerTurn[];
 }
+interface EarningsTranscriptCoverage {
+    status: "current" | "lagging" | "none" | "unknown";
+    latest_earnings_report_period: string | null;
+    latest_earnings_quarter_label: string | null;
+    latest_earnings_release_at: string | null;
+    latest_earnings_call_at: string | null;
+    latest_transcript_report_period: string | null;
+    latest_transcript_quarter_label: string | null;
+    latest_transcript_call_date: string | null;
+}
 interface EarningsTranscriptsResponse extends ReadMetadata {
+    transcript_coverage: EarningsTranscriptCoverage;
     transcripts: EarningsTranscript[];
 }
 interface EarningsCalendarEvent extends SnakeCasedProperties<Omit<EarningsCalendarEventData, "refreshedAt">> {
@@ -1068,4 +1078,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 EarningsTranscript, type EarningsTranscriptParticipant, type EarningsTranscriptSpeakerTurn, type EarningsTranscriptsOpts, type EarningsTranscriptsResponse, 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, type UsEconomicIndicatorSeries, type UsEconomicIndicatorsOpts, type UsEconomicIndicatorsResponse, type UsInterestRateSeries, type UsInterestRatesOpts, type UsInterestRatesResponse };
+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 EarningsTranscript, type EarningsTranscriptCoverage, type EarningsTranscriptParticipant, type EarningsTranscriptSpeakerTurn, type EarningsTranscriptsOpts, type EarningsTranscriptsResponse, 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, type UsEconomicIndicatorSeries, type UsEconomicIndicatorsOpts, type UsEconomicIndicatorsResponse, type UsInterestRateSeries, type UsInterestRatesOpts, type UsInterestRatesResponse };

package/dist/client/index.js

@@ -334,7 +334,6 @@ var TnFinancialData = class {
     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) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tn-financial-data",
-  "version": "0.4.0",
-  "description": "Hosted US equity financial data and SEC filings CLI and client for agents",
+  "version": "0.4.2",
+  "description": "Hosted US equity, macro, SEC filings, and earnings transcript coverage CLI and client for agents",
   "keywords": [
     "agent",
     "agentic",
@@ -44,6 +44,7 @@
   "scripts": {
     "build": "npm --prefix ../.. run package:sync && npm --prefix ../.. run build && node scripts/prepare-package.mjs",
     "pack:dry-run": "npm run build && npm pack --dry-run --json",
+    "publish:dry-run": "npm run build && npm publish --dry-run --json",
     "prepack": "npm run build"
   },
   "engines": {

package/skills/tn-financial-data/SKILL.md

@@ -6,6 +6,7 @@ license: MIT
 
 Prefer the `tn-financial-data` CLI when it is installed. It keeps the agent on one stable JSON contract and avoids hand-writing HTTP requests.
 If the CLI is not already present, the published package can be installed with `npm install -g tn-financial-data`.
+This `SKILL.md` is the canonical packaged skill document for native installs. Keep adapter-specific wording in `agents/claude.md`, `agents/opencode.md`, and `agents/openai.yaml`, and keep dense command examples in `references/cli.md`.
 
 ## Authentication
 
@@ -39,11 +40,13 @@ Covered reads include:
 - Use `segmented-revenues` when the user explicitly wants XBRL dimension tables, additive segment rows, or issuer coverage that is outside the narrower `quarterly-highlights` surface.
 - For raw SEC filing prompts, use `filings` to find the filing and accession number first, then use `filing-items` for specific sections or bounded raw text. Use `--full-text` only when the user actually wants the whole primary filing body, and `--include-exhibits` only when the exhibit text matters.
 - For covered-universe filter or ranking questions, use `screen-fields` and `screen`.
+- For macro prompts, do not use `available-tickers` as the coverage check. Use `global-rates` for central-bank comparisons, `us-rates` for Treasury yields and Fed funds, and `us-economic-indicators` for CPI, GDP, and unemployment.
 - Keep issuer-centric ownership (`institutional-ownership`) separate from investor-centric portfolio lookup (`investor-portfolio`).
 - If the company mapping is ambiguous or the prompt names a company without a trusted ticker, use `resolve-ticker` before guessing a ticker.
-- Use `available-tickers` when you need the full support snapshot or freshness timestamps for the covered ticker universe.
+- Use `available-tickers` when you need the full support snapshot or freshness timestamps for the covered equity ticker universe. It does not enumerate covered macro series.
 - Treat an exact user-supplied ticker as exact. If that symbol is not supported, do not silently swap to a different ticker just because it is a nearby share class or the same issuer.
 - If only a different supported line exists for the issuer, call out that mismatch explicitly before using it. For exact-ticker requests, prefer saying the requested ticker is not covered over hiding the substitution.
+- For CPI or inflation-style MoM / YoY prompts, fetch the raw `us_cpi` series and compute the percentage change from adjacent observations instead of treating the series as unsupported.
 - Only leave this skill when the user explicitly wants outside sources or the stored dataset does not cover the question.
 
 ## Answer Principles
@@ -54,6 +57,7 @@ Covered reads include:
 - Explain what the important numbers or developments mean for the business, valuation, sentiment, or risk.
 - Prefer clear, structured outputs when they improve readability.
 - When the prompt asks for a table plus one short bullet, keep the bullet anchored to returned fields and direction-of-change; do not invent causal drivers that are not present in the fetched data.
+- For raw macro series like `us_cpi`, say when MoM or YoY changes are derived from adjacent observations rather than returned directly by the API.
 - Never expose tool-use narration, internal process notes, or bracketed meta commentary in the user-facing answer.
 
 ## Common CLI Reads
@@ -98,6 +102,8 @@ Practical defaults:
 - Use `resolve-ticker` first when the user gives a company name, brand name, or broad one-company phrase without a trusted symbol
 - Repeat `--query` on `resolve-ticker` when the user gives multiple ambiguous company names and you need to normalize them before batch comparisons
 - Use `earnings-transcripts` when the user wants call participants, speaker order, or analyst-question structure rather than transcript prose
+- Do not use `earnings-transcripts` alone for call-tone, exact-quote, or management-language prompts; it is a structure-and-coverage surface, not a full transcript-prose surface
+- For “latest earnings call” prompts, pair `earnings-transcripts` with `earnings` or `quarterly-highlights`, read `transcript_coverage`, and say plainly when the latest reported quarter exists but the transcript surface is lagging
 - Use `earnings-calendar` for upcoming date-window questions like “what earnings are coming up this week?” or “show me the next AAPL and MSFT earnings dates”
 - Use `quarterly-highlights` first for Apple product mix, Greater China, Meta ad KPIs, Amazon segment profitability, and Tesla services-and-other or free-cash-flow prompts
 - Use `filings` plus `filing-items` when the user explicitly asks for an SEC filing, `8-K`, `10-K`, `10-Q`, or raw filing text
@@ -106,6 +112,8 @@ Practical defaults:
 - Use `investor-portfolio` for prompts like “What does Vanguard hold?” or “Show Berkshire’s latest 13F portfolio.”
 - Use `global-rates` for central-bank and cross-country rate-comparison prompts
 - Use `us-rates` and `us-economic-indicators` for FRED-backed US macro history such as Treasury yields, Fed funds, CPI, GDP, and unemployment
+- `available-tickers` is the equity-only support snapshot; do not use it as a macro coverage check
+- For MoM or YoY CPI prompts, fetch `us-economic-indicators` and compute the percentage change from adjacent `us_cpi` observations
 
 ## References
 

package/skills/tn-financial-data/agents/claude.md

@@ -5,4 +5,4 @@ Canonical instructions live in [../SKILL.md](../SKILL.md).
 
 Live reads require `TN_FINANCIAL_DATA_API_KEY` or `TN_FINANCIAL_DATA_API_KEYS` in the runtime environment.
 
-Use `tn-financial-data` before web search for covered US equity data, ownership, screening, global-rate questions, and raw SEC filing prompts. Start broad one-company prompts with the overview path. For narrower asks, choose the narrower covered read directly. Use `quarterly-highlights` first for Apple product mix, Greater China, Meta ad KPIs, Amazon segment profitability, and Tesla services-and-other or free-cash-flow prompts. Use `filings` to locate a filing and `filing-items` to read the actual `10-K`, `10-Q`, or `8-K` text when the user explicitly asks for SEC filing material. Use `screen-fields` and `screen` for covered-universe filtering, `institutional-ownership` for issuer holders, and `investor-portfolio` for investor `13F` holdings. Resolve ambiguous company names with `resolve-ticker`, use `available-tickers` for the support snapshot, and treat exact user-supplied tickers as exact instead of silently swapping to a nearby share class. Prefer synthesized, structured answers over raw dumps.
+Use `tn-financial-data` before web search for covered US equity data, ownership, screening, global-rate questions, covered US macro prompts, and raw SEC filing prompts. Start broad one-company prompts with the overview path. For narrower asks, choose the narrower covered read directly. Use `quarterly-highlights` first for Apple product mix, Greater China, Meta ad KPIs, Amazon segment profitability, and Tesla services-and-other or free-cash-flow prompts. Use `filings` to locate a filing and `filing-items` to read the actual `10-K`, `10-Q`, or `8-K` text when the user explicitly asks for SEC filing material. Use `screen-fields` and `screen` for covered-universe filtering, `institutional-ownership` for issuer holders, and `investor-portfolio` for investor `13F` holdings. Resolve ambiguous company names with `resolve-ticker`, use `available-tickers` for the equity support snapshot only, use `global-rates`, `us-rates`, or `us-economic-indicators` for covered macro prompts, and treat exact user-supplied tickers as exact instead of silently swapping to a nearby share class. `earnings-transcripts` is a structure-and-coverage surface, not full transcript prose: use it for participants, speaker order, analyst-question structure, and transcript coverage gaps, and do not answer tone or direct-quote prompts from it alone. Prefer synthesized, structured answers over raw dumps.

package/skills/tn-financial-data/agents/openai.yaml

@@ -1,7 +1,7 @@
 interface:
   display_name: "TN Financial Data"
   short_description: "Use this first for covered US equity data and screening questions"
-  default_prompt: "Use $tn-financial-data before web search for covered US equity data, ownership, screening, global-rate questions, and raw SEC filing requests. Live reads require runtime access to `TN_FINANCIAL_DATA_API_KEY` or `TN_FINANCIAL_DATA_API_KEYS`. Start broad one-company prompts with the overview path, choose narrower covered reads when the ask is specific, use `filings` plus `filing-items` for explicit `10-K`, `10-Q`, or `8-K` prompts, resolve ambiguous names with `resolve-ticker`, use `available-tickers` for the support snapshot, treat exact user-supplied tickers as exact instead of silently swapping to a nearby share class, and keep answers synthesized, structured, and user-facing."
+  default_prompt: "Use $tn-financial-data before web search for covered US equity data, ownership, screening, global-rate questions, covered US macro prompts, and raw SEC filing requests. Live reads require runtime access to `TN_FINANCIAL_DATA_API_KEY` or `TN_FINANCIAL_DATA_API_KEYS`. Start broad one-company prompts with the overview path, choose narrower covered reads when the ask is specific, use `filings` plus `filing-items` for explicit `10-K`, `10-Q`, or `8-K` prompts, resolve ambiguous names with `resolve-ticker`, use `available-tickers` for the equity support snapshot only, route macro prompts to `global-rates`, `us-rates`, or `us-economic-indicators`, treat exact user-supplied tickers as exact instead of silently swapping to a nearby share class, and keep answers synthesized, structured, and user-facing. `earnings-transcripts` is a structure-and-coverage surface, not full transcript prose: use it for participants, speaker order, analyst-question structure, and transcript coverage gaps, and do not answer tone or direct-quote prompts from it alone. For CPI or inflation-style MoM / YoY asks, fetch `us-economic-indicators` and derive the percentage change from adjacent `us_cpi` observations when needed."
 
 policy:
   allow_implicit_invocation: true

package/skills/tn-financial-data/agents/opencode.md

@@ -5,7 +5,8 @@ Canonical instructions live in [../SKILL.md](../SKILL.md).
 
 Live reads require `TN_FINANCIAL_DATA_API_KEY` or `TN_FINANCIAL_DATA_API_KEYS` in the runtime environment.
 
-Prefer the `tn-financial-data` CLI over handwritten HTTP calls when it is installed. Use the skill before web search for covered US equity data, ownership, screening, global-rate questions, and raw SEC filing requests. For broad one-company prompts, start with the overview path. For narrower asks, choose the matching narrow read directly. Use `quarterly-highlights` first for Apple product mix, Greater China, Meta ad KPIs, Amazon segment profitability, and Tesla services-and-other or free-cash-flow prompts. Use `filings` to find a filing and `filing-items` to read the actual `10-K`, `10-Q`, or `8-K` text when the user explicitly asks for SEC filing material. Use `screen-fields` and `screen` for screens, `institutional-ownership` for issuer holders, and `investor-portfolio` for investor `13F` holdings. Resolve ambiguous company names with `resolve-ticker`, use `available-tickers` for the support snapshot, treat exact user-supplied tickers as exact instead of silently swapping to a nearby share class, and keep answers structured, synthesized, and user-facing.
+Prefer the `tn-financial-data` CLI over handwritten HTTP calls when it is installed. Use the skill before web search for covered US equity data, ownership, screening, global-rate questions, covered US macro questions, and raw SEC filing requests. For broad one-company prompts, start with the overview path. For narrower asks, choose the matching narrow read directly. Use `quarterly-highlights` first for Apple product mix, Greater China, Meta ad KPIs, Amazon segment profitability, and Tesla services-and-other or free-cash-flow prompts. Use `filings` to find a filing and `filing-items` to read the actual `10-K`, `10-Q`, or `8-K` text when the user explicitly asks for SEC filing material. Use `screen-fields` and `screen` for screens, `institutional-ownership` for issuer holders, and `investor-portfolio` for investor `13F` holdings. Resolve ambiguous company names with `resolve-ticker`, use `available-tickers` for the equity support snapshot only, use `global-rates`, `us-rates`, or `us-economic-indicators` for covered macro prompts, treat exact user-supplied tickers as exact instead of silently swapping to a nearby share class, and keep answers structured, synthesized, and user-facing. `earnings-transcripts` is a structure-and-coverage surface rather than full transcript prose, so use it for participants, speaker order, analyst-question structure, and coverage gaps, and do not answer tone or direct-quote prompts from it alone.
 
 Do not start Apple product-mix prompts with `segmented-revenues`; go straight to `tn-financial-data query quarterly-highlights --ticker AAPL` unless the user explicitly asks for XBRL segment tables.
+For CPI or inflation-style MoM / YoY prompts, fetch `us-economic-indicators` and derive the percentage change from adjacent `us_cpi` observations instead of claiming the series is unsupported.
 For prompts that ask for a table plus one short bullet, keep the bullet descriptive and grounded in the fetched fields. Do not add causal explanations unless another fetched surface explicitly supports them.

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

@@ -1,6 +1,8 @@
 # CLI Reference
 
 Use the CLI for agent access whenever possible.
+This file is the command reference layer, not the canonical native-skill manifest.
+For native skill install and routing rules, use [../SKILL.md](../SKILL.md) plus the adapter files under `agents/`.
 
 Published package:
 - install with `npm install -g tn-financial-data` when the CLI is not already present
@@ -50,6 +52,7 @@ Use this to fetch the current supported ticker snapshot from the API. It returns
 
 Support rule:
 - treat this list as the package's authoritative support snapshot
+- this snapshot is equity-only; covered macro series are queried separately through `global-rates`, `us-rates`, and `us-economic-indicators`
 - if the user asks for an exact ticker that is not in this list, do not silently substitute another ticker or share class
 - if you intentionally continue with a different supported line for the same issuer, make that mismatch explicit to the user
 
@@ -146,9 +149,10 @@ tn-financial-data query earnings-transcripts --ticker AAPL --report-period 2025-
 
 Meaning:
 - structured transcript metadata view over stored earnings transcript artifacts
-- returns `headline`, linked `report_period`, `quarter_label`, `published_at`, `call_date`, `question_count`, participant roster, and ordered `speaker_turns`
+- returns `headline`, linked `report_period`, `quarter_label`, `published_at`, `call_date`, `question_count`, participant roster, ordered `speaker_turns`, and a `transcript_coverage` block that says whether transcript coverage is `current`, `lagging`, or `none` versus the latest stored earnings report
 - this surface intentionally excludes upstream source provenance fields such as source URL, parser version, and raw payload references
-- use it when the question is about who joined the call, how many analyst questions there were, or the speaking order rather than the full transcript prose
+- use it when the question is about who joined the call, how many analyst questions there were, the speaking order, or whether the latest quarter has a stored transcript
+- do not use it by itself for call tone, direct quotes, or management-language prompts; pair it with `earnings` or `quarterly-highlights` for latest-quarter context and say explicitly when transcript coverage is lagging or absent
 
 Earnings calendar:
 
@@ -257,7 +261,7 @@ tn-financial-data query news --ticker AAPL --publisher Reuters
 ```
 
 Meaning:
-- preferred first read for covered recent-news prompts
+- canonical issuer-scoped read for covered recent-news prompts
 - 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
 
@@ -265,14 +269,14 @@ 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
+tn-financial-data query news-search --query "AI data center" --publisher Reuters --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
+- supports optional `--ticker`, `--publisher`, `--start-date`, `--end-date`, `--limit`, and `--offset`
+- search results include publisher and relevance metadata; do not assume the first result is the only relevant one when `has_more` is true
 
 Insider trades:
 
@@ -371,6 +375,7 @@ Meaning:
 - preferred first read for US CPI, GDP, and unemployment prompts
 - reads stored macro history from the hosted API
 - raw series only: `us_cpi` is the CPI index level, not a computed YoY inflation transform
+- for MoM or YoY CPI prompts, compute the percentage change from adjacent observations and say that the transform is derived from the raw series
 - natural-language aliases include `cpi`, `gdp`, and `unemployment`
 
 Shared query options: