tn-financial-data 0.4.1 → 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
@@ -124,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
@@ -215,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"],
@@ -240,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>]",
@@ -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",
@@ -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: [
@@ -2326,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.",
@@ -2428,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).",
@@ -2442,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.",
@@ -3045,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.1",
-  "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
 
@@ -101,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

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, 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. 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, 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. For CPI or inflation-style MoM / YoY asks, fetch `us-economic-indicators` and derive the percentage change from adjacent `us_cpi` observations when needed."
+  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,7 @@ 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, 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.
+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.

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
@@ -147,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:
 
@@ -258,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
 
@@ -266,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: