tn-financial-data 0.3.1 → 0.4.1

package/README.md

@@ -25,7 +25,7 @@ This package is the hosted agent-facing surface only. The repo's website, local
 
 ## Features
 
-- Company facts, financials, prices, news, insider trades, ownership, global rates, and raw SEC filings through one hosted API
+- Company facts, financials, prices, news, insider trades, ownership, earnings transcript structure, 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
@@ -33,6 +33,7 @@ This package is the hosted agent-facing surface only. The repo's website, local
 - Packaged skill bundle for Claude and OpenCode installs
 - Typed TypeScript client from the root package export
 - Stable production default at `https://api.truenorth-financial.ai/v1`
+- Stored macro endpoints for FRED-backed US rates and economic indicators, plus global central-bank rate history through `global-rates`, `us-rates`, and `us-economic-indicators`
 
 ## Installation
 
@@ -56,6 +57,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:
 
@@ -71,8 +73,11 @@ tn-financial-data query resolve-ticker --query google --query meta --query nvda
 tn-financial-data query available-tickers
 tn-financial-data query snapshot --tickers AAPL,MSFT,NVDA
 tn-financial-data query financial-metrics-snapshot --tickers AAPL,MSFT,NVDA --period annual
+tn-financial-data query earnings-transcripts --ticker AAPL --limit 4
 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 us-rates --series us_treasury_2y,us_treasury_10y,fed_funds_rate --start-date 2021-01-01 --end-date 2026-04-01 --limit 2000
+tn-financial-data query us-economic-indicators --series us_cpi,us_unemployment,us_gdp --start-date 2021-01-01 --end-date 2026-04-01 --limit 120
 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
@@ -86,6 +91,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 |
@@ -103,10 +113,13 @@ tn-financial-data query financial-metrics-snapshot --tickers AAPL,MSFT,NVDA --pe
 tn-financial-data query financials --ticker AAPL --period annual --statement all
 tn-financial-data query financial-metrics --ticker AAPL --period annual --limit 4
 tn-financial-data query earnings --ticker AAPL --period quarterly --limit 8
+tn-financial-data query earnings-transcripts --ticker AAPL --limit 4
 tn-financial-data query earnings-calendar --tickers AAPL,MSFT --start-date 2026-04-02 --end-date 2026-04-16
 tn-financial-data query quarterly-highlights --ticker AAPL
 tn-financial-data query dividends --ticker AAPL --limit 10
 tn-financial-data query splits --ticker AAPL --limit 10
+tn-financial-data query us-rates --series us_treasury_2y,us_treasury_10y,fed_funds_rate --start-date 2021-01-01 --end-date 2026-04-01 --limit 2000
+tn-financial-data query us-economic-indicators --series us_cpi,us_unemployment,us_gdp --start-date 2021-01-01 --end-date 2026-04-01 --limit 120
 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
@@ -202,6 +215,22 @@ const calendar = await client.getEarningsCalendar({
 
 console.log(calendar.events.map((row) => `${row.ticker}:${row.event_date_start}`));
 
+const transcripts = await client.getEarningsTranscripts({
+  ticker: "NVDA",
+  limit: 1,
+});
+
+console.log(transcripts.transcripts[0]?.quarter_label, transcripts.transcripts[0]?.question_count);
+
+const usRates = await client.getUsInterestRates({
+  series: ["us_treasury_10y", "fed_funds_rate"],
+  startDate: "2021-01-01",
+  endDate: "2026-04-01",
+  limit: 2000,
+});
+
+console.log(usRates.rates.map((row) => `${row.key}:${row.latest?.value}`));
+
 const filings = await client.getFilings("AAPL", {
   filingTypes: ["8-K"],
   limit: 3,

package/dist/cli.js

@@ -274,6 +274,12 @@ var TnFinancialData = class {
       `/earnings?${this.buildOptionalFinancialParams(ticker, opts)}`
     );
   }
+  async getEarningsTranscripts(ticker, opts) {
+    const params = new URLSearchParams({ ticker });
+    if (opts?.limit !== void 0) params.set("limit", String(opts.limit));
+    if (opts?.reportPeriod) params.set("report_period", opts.reportPeriod);
+    return this.request(`/earnings/transcripts?${params.toString()}`);
+  }
   async getEarningsCalendar(opts) {
     const params = this.buildEarningsCalendarParams(opts);
     return this.request(
@@ -369,12 +375,24 @@ var TnFinancialData = class {
     return this.request(`/institutional-ownership/investor?${params}`);
   }
   async getGlobalInterestRates(opts) {
+    const params = this.buildMacroSeriesParams(opts);
+    return this.request(`/macro/interest-rates/global?${params}`);
+  }
+  async getUsInterestRates(opts) {
+    const params = this.buildMacroSeriesParams(opts);
+    return this.request(`/macro/interest-rates/us?${params}`);
+  }
+  async getUsEconomicIndicators(opts) {
+    const params = this.buildMacroSeriesParams(opts);
+    return this.request(`/macro/economic-indicators/us?${params}`);
+  }
+  buildMacroSeriesParams(opts) {
     const params = new URLSearchParams();
     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?.series && opts.series.length > 0) params.set("series", opts.series.join(","));
-    return this.request(`/macro/interest-rates/global?${params}`);
+    return params;
   }
   async getAnalystEstimates(ticker) {
     return this.request(
@@ -666,7 +684,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|news-search|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-transcripts|earnings-calendar|quarterly-highlights|analyst-estimates|prices|snapshot|dividends|splits|news|news-search|insider-trades|institutional-ownership|investor-portfolio|global-rates|us-rates|us-economic-indicators|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",
@@ -684,6 +702,7 @@ function rootHelp() {
     "  tn-financial-data query snapshot --tickers AAPL,MSFT,NVDA",
     "  tn-financial-data query financial-metrics-snapshot --tickers AAPL,MSFT,NVDA --period annual",
     "  tn-financial-data query earnings --ticker AAPL --period quarterly --limit 8",
+    "  tn-financial-data query earnings-transcripts --ticker AAPL --limit 4",
     "  tn-financial-data query earnings-calendar --tickers AAPL,MSFT --start-date 2026-04-02 --end-date 2026-04-16",
     "  tn-financial-data query quarterly-highlights --ticker AAPL",
     "  tn-financial-data query analyst-estimates --ticker AAPL",
@@ -695,6 +714,8 @@ function rootHelp() {
     "  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",
+    "  tn-financial-data query us-rates --series us_treasury_2y,us_treasury_10y,fed_funds_rate --start-date 2021-01-01 --end-date 2026-04-01 --limit 2000",
+    "  tn-financial-data query us-economic-indicators --series us_cpi,us_unemployment,us_gdp --start-date 2021-01-01 --end-date 2026-04-01 --limit 120",
     '  tn-financial-data query screen --filter "trailing_pe < 25" --filter "recommendation_key = buy" --limit 10',
     "  tn-financial-data skill install --tool opencode",
     "  tn-financial-data skill install --tool claude",
@@ -723,6 +744,7 @@ function queryHelp() {
     "  tn-financial-data query financial-metrics --ticker <symbol> [--period <annual|quarterly|ttm>] [--limit <n>] [--report-period <date>] [--report-period-gte <date>] [--report-period-lte <date>] [--report-period-gt <date>] [--report-period-lt <date>] [--api-key <key>] [--base-url <url>]",
     "  tn-financial-data query financial-metrics-snapshot (--ticker <symbol> | --tickers <csv>) [--period <annual|quarterly|ttm>] [--api-key <key>] [--base-url <url>]",
     "  tn-financial-data query earnings --ticker <symbol> [--period <annual|quarterly|ttm>] [--limit <n>] [--report-period <date>] [--report-period-gte <date>] [--report-period-lte <date>] [--report-period-gt <date>] [--report-period-lt <date>] [--api-key <key>] [--base-url <url>]",
+    "  tn-financial-data query earnings-transcripts --ticker <symbol> [--limit <n>] [--report-period <date>] [--api-key <key>] [--base-url <url>]",
     "  tn-financial-data query earnings-calendar [--ticker <symbol> | --tickers <csv>] [--start-date <date>] [--end-date <date>] [--limit <n>] [--api-key <key>] [--base-url <url>]",
     "  tn-financial-data query quarterly-highlights --ticker <symbol> [--report-period <date>] [--api-key <key>] [--base-url <url>]",
     "  tn-financial-data query analyst-estimates --ticker <symbol> [--api-key <key>] [--base-url <url>]",
@@ -736,6 +758,8 @@ function queryHelp() {
     "  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>]",
     "  tn-financial-data query global-rates [--series <csv>] [--start-date <date>] [--end-date <date>] [--limit <n>] [--api-key <key>] [--base-url <url>]",
+    "  tn-financial-data query us-rates [--series <csv>] [--start-date <date>] [--end-date <date>] [--limit <n>] [--api-key <key>] [--base-url <url>]",
+    "  tn-financial-data query us-economic-indicators [--series <csv>] [--start-date <date>] [--end-date <date>] [--limit <n>] [--api-key <key>] [--base-url <url>]",
     "  tn-financial-data query segmented-revenues --ticker <symbol> --period <annual|quarterly|ttm> [--limit <n>] [--segment-type <type>] [--report-period <date>] [--report-period-gte <date>] [--report-period-lte <date>] [--report-period-gt <date>] [--report-period-lt <date>] [--api-key <key>] [--base-url <url>]",
     '  tn-financial-data query screen --filter "field operator value" [--filter "field operator value"] [--limit <n>] [--api-key <key>] [--base-url <url>]',
     "  tn-financial-data query screen-fields [--api-key <key>] [--base-url <url>]",
@@ -799,7 +823,7 @@ function buildOpenCliDocument() {
     info: {
       title: "tn-financial-data",
       summary: "Server-backed US equity financial data CLI for agents and operators.",
-      description: "Query company facts, SEC financial statements, issuer-centric ownership data, investor-centric SEC 13F portfolios, global central-bank rate series, and daily or hourly prices from the tn-financial-data API.",
+      description: "Query company facts, SEC financial statements, issuer-centric ownership data, investor-centric SEC 13F portfolios, global and US macro series, and daily or hourly prices from the tn-financial-data API.",
       version,
       license: {
         identifier: "MIT",
@@ -849,6 +873,7 @@ function buildOpenCliDocument() {
       "tn-financial-data query financial-metrics-snapshot --ticker AAPL",
       "tn-financial-data query financial-metrics-snapshot --tickers AAPL,MSFT,NVDA --period annual",
       "tn-financial-data query earnings --ticker AAPL --period quarterly --limit 8",
+      "tn-financial-data query earnings-transcripts --ticker AAPL --limit 4",
       "tn-financial-data query earnings-calendar --tickers AAPL,MSFT --start-date 2026-04-02 --end-date 2026-04-16",
       "tn-financial-data query quarterly-highlights --ticker AAPL",
       "tn-financial-data query analyst-estimates --ticker AAPL",
@@ -861,6 +886,8 @@ function buildOpenCliDocument() {
       "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",
+      "tn-financial-data query us-rates --series us_treasury_2y,us_treasury_10y,fed_funds_rate --start-date 2021-01-01 --end-date 2026-04-01 --limit 2000",
+      "tn-financial-data query us-economic-indicators --series us_cpi,us_unemployment,us_gdp --start-date 2021-01-01 --end-date 2026-04-01 --limit 120",
       'tn-financial-data query screen --filter "trailing_pe < 25" --filter "recommendation_key = buy" --limit 10',
       "tn-financial-data skill install --tool opencode",
       "tn-financial-data skill install --tool claude",
@@ -902,7 +929,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",
@@ -1356,6 +1383,34 @@ function buildOpenCliDocument() {
               }
             ]
           },
+          {
+            name: "earnings-transcripts",
+            description: "Fetch normalized earnings call transcript metadata, participants, and speaker-turn structure for a single ticker.",
+            options: [
+              {
+                name: "ticker",
+                required: true,
+                arguments: [{ name: "ticker", required: true, description: "Ticker symbol." }],
+                description: "Ticker to fetch."
+              },
+              {
+                name: "limit",
+                arguments: [{ name: "limit", required: true, description: "Positive integer." }],
+                description: "Maximum number of transcript artifacts to return."
+              },
+              {
+                name: "report-period",
+                arguments: [
+                  {
+                    name: "date",
+                    required: true,
+                    description: "Exact linked reporting-period end date."
+                  }
+                ],
+                description: "Exact linked report-period filter."
+              }
+            ]
+          },
           {
             name: "quarterly-highlights",
             description: "Fetch issuer-reported supplemental quarterly highlights from the linked SEC Exhibit 99.1 release for supported companies.",
@@ -1540,6 +1595,79 @@ function buildOpenCliDocument() {
               }
             ]
           },
+          {
+            name: "us-rates",
+            description: "Fetch US Treasury and Fed funds series with historical observations.",
+            options: [
+              {
+                name: "series",
+                arguments: [
+                  {
+                    name: "series",
+                    required: true,
+                    acceptedValues: [
+                      "us_treasury_3m",
+                      "us_treasury_2y",
+                      "us_treasury_5y",
+                      "us_treasury_10y",
+                      "us_treasury_30y",
+                      "fed_funds_rate"
+                    ],
+                    description: "Comma-separated series key list."
+                  }
+                ],
+                description: "Comma-separated US rates series list. Defaults to all supported US rates."
+              },
+              {
+                name: "start-date",
+                arguments: [{ name: "date", required: true, description: "Window start date." }],
+                description: "Inclusive start date filter."
+              },
+              {
+                name: "end-date",
+                arguments: [{ name: "date", required: true, description: "Window end date." }],
+                description: "Inclusive end date filter."
+              },
+              {
+                name: "limit",
+                arguments: [{ name: "limit", required: true, description: "Positive integer." }],
+                description: "Maximum observations per series to return."
+              }
+            ]
+          },
+          {
+            name: "us-economic-indicators",
+            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",
+                arguments: [
+                  {
+                    name: "series",
+                    required: true,
+                    acceptedValues: ["us_cpi", "us_gdp", "us_unemployment"],
+                    description: "Comma-separated series key list."
+                  }
+                ],
+                description: "Comma-separated US economic indicator series list. Defaults to all supported indicators."
+              },
+              {
+                name: "start-date",
+                arguments: [{ name: "date", required: true, description: "Window start date." }],
+                description: "Inclusive start date filter."
+              },
+              {
+                name: "end-date",
+                arguments: [{ name: "date", required: true, description: "Window end date." }],
+                description: "Inclusive end date filter."
+              },
+              {
+                name: "limit",
+                arguments: [{ name: "limit", required: true, description: "Positive integer." }],
+                description: "Maximum observations per series to return."
+              }
+            ]
+          },
           {
             name: "snapshot",
             description: "Fetch the latest daily price snapshot for one ticker or a small ticker batch.",
@@ -1940,6 +2068,20 @@ var GLOBAL_INTEREST_RATE_SERIES_KEYS = [
   "rba_3m",
   "snb_call_money"
 ];
+var US_INTEREST_RATE_SERIES_KEYS = [
+  "us_treasury_3m",
+  "us_treasury_2y",
+  "us_treasury_5y",
+  "us_treasury_10y",
+  "us_treasury_30y",
+  "fed_funds_rate"
+];
+var US_ECONOMIC_INDICATOR_SERIES_KEYS = ["us_cpi", "us_gdp", "us_unemployment"];
+var MACRO_SERIES_KEYS = [
+  ...GLOBAL_INTEREST_RATE_SERIES_KEYS,
+  ...US_INTEREST_RATE_SERIES_KEYS,
+  ...US_ECONOMIC_INDICATOR_SERIES_KEYS
+];
 
 // src/reference-data/global-rates-series.ts
 var GLOBAL_INTEREST_RATE_SERIES_ALIASES = {
@@ -1966,6 +2108,61 @@ function normalizeGlobalInterestRateSeriesKey(value) {
   return GLOBAL_INTEREST_RATE_SERIES_ALIASES[normalized] ?? null;
 }
 
+// src/reference-data/us-macro-series.ts
+var US_INTEREST_RATE_SERIES_ALIASES = {
+  "3m": "us_treasury_3m",
+  "3mo": "us_treasury_3m",
+  "3_month": "us_treasury_3m",
+  treasury_3m: "us_treasury_3m",
+  us_3m: "us_treasury_3m",
+  us_tbill_3m: "us_treasury_3m",
+  "2y": "us_treasury_2y",
+  treasury_2y: "us_treasury_2y",
+  us_2y: "us_treasury_2y",
+  "5y": "us_treasury_5y",
+  treasury_5y: "us_treasury_5y",
+  us_5y: "us_treasury_5y",
+  "10y": "us_treasury_10y",
+  treasury_10y: "us_treasury_10y",
+  us_10y: "us_treasury_10y",
+  "30y": "us_treasury_30y",
+  treasury_30y: "us_treasury_30y",
+  us_30y: "us_treasury_30y",
+  fed_funds: "fed_funds_rate",
+  fedfunds: "fed_funds_rate",
+  fedfundsrate: "fed_funds_rate",
+  ffr: "fed_funds_rate"
+};
+var US_ECONOMIC_INDICATOR_SERIES_ALIASES = {
+  cpi: "us_cpi",
+  gdp: "us_gdp",
+  unemployment: "us_unemployment",
+  unemployment_rate: "us_unemployment"
+};
+function canonicalizeSeriesKeyInput2(value) {
+  return value.trim().toLowerCase().replace(/[\s-]+/g, "_");
+}
+function normalizeUsInterestRateSeriesKey(value) {
+  const normalized = canonicalizeSeriesKeyInput2(value);
+  if (!normalized) {
+    return null;
+  }
+  if (US_INTEREST_RATE_SERIES_KEYS.includes(normalized)) {
+    return normalized;
+  }
+  return US_INTEREST_RATE_SERIES_ALIASES[normalized] ?? null;
+}
+function normalizeUsEconomicIndicatorSeriesKey(value) {
+  const normalized = canonicalizeSeriesKeyInput2(value);
+  if (!normalized) {
+    return null;
+  }
+  if (US_ECONOMIC_INDICATOR_SERIES_KEYS.includes(normalized)) {
+    return normalized;
+  }
+  return US_ECONOMIC_INDICATOR_SERIES_ALIASES[normalized] ?? null;
+}
+
 // src/cli/query-subcommand-help.ts
 function renderHelp(command, description, options, example) {
   return [
@@ -1983,7 +2180,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."
@@ -2123,6 +2323,20 @@ var QUERY_SUBCOMMAND_HELP = {
     ],
     "tn-financial-data query earnings --ticker AAPL --period quarterly --limit 8"
   ),
+  "earnings-transcripts": renderHelp(
+    "earnings-transcripts",
+    [
+      "Fetch normalized earnings call transcript metadata, participants, and speaker-turn structure for a single ticker."
+    ],
+    [
+      "--ticker <symbol>      Required. Stock ticker symbol.",
+      "--limit <n>            Number of transcript artifacts to return.",
+      "--report-period <date> Exact linked report period (YYYY-MM-DD).",
+      "--api-key <key>        API key. Overrides TN_FINANCIAL_DATA_API_KEY.",
+      "--base-url <url>       API base URL override."
+    ],
+    "tn-financial-data query earnings-transcripts --ticker AAPL --limit 4"
+  ),
   "earnings-calendar": renderHelp(
     "earnings-calendar",
     [
@@ -2284,7 +2498,7 @@ var QUERY_SUBCOMMAND_HELP = {
   ),
   "global-rates": renderHelp(
     "global-rates",
-    ["Fetch curated global policy and money-market rate series."],
+    ["Fetch stored global policy and money-market rate history from the hosted API."],
     [
       "--series <csv>     Optional comma-separated series keys.",
       "--start-date <date> Optional start date (YYYY-MM-DD).",
@@ -2295,6 +2509,35 @@ var QUERY_SUBCOMMAND_HELP = {
     ],
     "tn-financial-data query global-rates --series ecb_refi,boe_sonia --limit 10"
   ),
+  "us-rates": renderHelp(
+    "us-rates",
+    ["Fetch stored US Treasury and Fed funds history from the hosted API."],
+    [
+      "--series <csv>      Optional comma-separated US rates series keys.",
+      "--start-date <date> Optional start date (YYYY-MM-DD).",
+      "--end-date <date>   Optional end date (YYYY-MM-DD).",
+      "--limit <n>         Number of observations to return per series.",
+      "--api-key <key>     API key. Overrides TN_FINANCIAL_DATA_API_KEY.",
+      "--base-url <url>    API base URL override."
+    ],
+    "tn-financial-data query us-rates --series us_treasury_2y,us_treasury_10y,fed_funds_rate --start-date 2021-01-01 --end-date 2026-04-01 --limit 2000"
+  ),
+  "us-economic-indicators": renderHelp(
+    "us-economic-indicators",
+    [
+      "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).",
+      "--end-date <date>   Optional end date (YYYY-MM-DD).",
+      "--limit <n>         Number of observations to return per series.",
+      "--api-key <key>     API key. Overrides TN_FINANCIAL_DATA_API_KEY.",
+      "--base-url <url>    API base URL override."
+    ],
+    "tn-financial-data query us-economic-indicators --series us_cpi,us_unemployment,us_gdp --start-date 2021-01-01 --end-date 2026-04-01 --limit 120"
+  ),
   "segmented-revenues": renderHelp(
     "segmented-revenues",
     ["Fetch reported segment revenue rows for a single issuer."],
@@ -2524,6 +2767,17 @@ function buildEarningsCalendarCliOptions(parsed) {
   }
   return options;
 }
+function parseMacroSeriesSelection(value, acceptedValues, normalize) {
+  return value?.split(",").map((item) => item.trim()).filter((item) => item.length > 0).map((item) => {
+    const normalized = normalize(item);
+    if (!normalized) {
+      throw new CliUsageError(
+        `series must be a comma-separated list of: ${acceptedValues.join(", ")}.`
+      );
+    }
+    return normalized;
+  });
+}
 async function handleQuery(parsed, runtime, deps) {
   const resource = parsed.positionals[1];
   if (!resource) {
@@ -2702,6 +2956,20 @@ async function handleQuery(parsed, runtime, deps) {
       printJson(runtime, await client.getEarningsCalendar(buildEarningsCalendarCliOptions(parsed)));
       return 0;
     }
+    case "earnings-transcripts": {
+      const ticker = requireOption(parsed, "ticker");
+      const options = {};
+      const limit = getOption(parsed, "limit");
+      const reportPeriod = getOption(parsed, "report-period");
+      if (limit) {
+        options.limit = parsePositiveInt(limit, "limit");
+      }
+      if (reportPeriod) {
+        options.reportPeriod = reportPeriod;
+      }
+      printJson(runtime, await client.getEarningsTranscripts(ticker, options));
+      return 0;
+    }
     case "quarterly-highlights": {
       const ticker = requireOption(parsed, "ticker");
       const options = {};
@@ -2848,15 +3116,11 @@ async function handleQuery(parsed, runtime, deps) {
     }
     case "global-rates": {
       const limit = getOption(parsed, "limit");
-      const series = getOption(parsed, "series")?.split(",").map((value) => value.trim()).filter((value) => value.length > 0).map((value) => {
-        const normalized = normalizeGlobalInterestRateSeriesKey(value);
-        if (!normalized) {
-          throw new CliUsageError(
-            `series must be a comma-separated list of: ${GLOBAL_INTEREST_RATE_SERIES_KEYS.join(", ")}.`
-          );
-        }
-        return normalized;
-      });
+      const series = parseMacroSeriesSelection(
+        getOption(parsed, "series"),
+        GLOBAL_INTEREST_RATE_SERIES_KEYS,
+        normalizeGlobalInterestRateSeriesKey
+      );
       printJson(
         runtime,
         await client.getGlobalInterestRates({
@@ -2868,6 +3132,46 @@ async function handleQuery(parsed, runtime, deps) {
       );
       return 0;
     }
+    case "us-rates": {
+      const limit = getOption(parsed, "limit");
+      const series = parseMacroSeriesSelection(
+        getOption(parsed, "series"),
+        US_INTEREST_RATE_SERIES_KEYS,
+        normalizeUsInterestRateSeriesKey
+      );
+      const options = {
+        startDate: getOption(parsed, "start-date"),
+        endDate: getOption(parsed, "end-date")
+      };
+      if (limit) {
+        options.limit = parsePositiveInt(limit, "limit");
+      }
+      if (series && series.length > 0) {
+        options.series = series;
+      }
+      printJson(runtime, await client.getUsInterestRates(options));
+      return 0;
+    }
+    case "us-economic-indicators": {
+      const limit = getOption(parsed, "limit");
+      const series = parseMacroSeriesSelection(
+        getOption(parsed, "series"),
+        US_ECONOMIC_INDICATOR_SERIES_KEYS,
+        normalizeUsEconomicIndicatorSeriesKey
+      );
+      const options = {
+        startDate: getOption(parsed, "start-date"),
+        endDate: getOption(parsed, "end-date")
+      };
+      if (limit) {
+        options.limit = parsePositiveInt(limit, "limit");
+      }
+      if (series && series.length > 0) {
+        options.series = series;
+      }
+      printJson(runtime, await client.getUsEconomicIndicators(options));
+      return 0;
+    }
     case "segmented-revenues": {
       const ticker = requireOption(parsed, "ticker");
       const period = assertAcceptedValue(

package/dist/client/index.d.ts

@@ -35,6 +35,10 @@ interface ScreenerStringInFilter {
 type ScreenerFilter = ScreenerNumericFilter | ScreenerStringEqFilter | ScreenerStringInFilter;
 declare const GLOBAL_INTEREST_RATE_SERIES_KEYS: readonly ["ecb_refi", "ecb_deposit", "boj_call_money", "boe_sonia", "boc_call_money", "rba_3m", "snb_call_money"];
 type GlobalInterestRateSeriesKey = (typeof GLOBAL_INTEREST_RATE_SERIES_KEYS)[number];
+declare const US_INTEREST_RATE_SERIES_KEYS: readonly ["us_treasury_3m", "us_treasury_2y", "us_treasury_5y", "us_treasury_10y", "us_treasury_30y", "fed_funds_rate"];
+type UsInterestRateSeriesKey = (typeof US_INTEREST_RATE_SERIES_KEYS)[number];
+declare const US_ECONOMIC_INDICATOR_SERIES_KEYS: readonly ["us_cpi", "us_gdp", "us_unemployment"];
+type UsEconomicIndicatorSeriesKey = (typeof US_ECONOMIC_INDICATOR_SERIES_KEYS)[number];
 
 interface IncomeStatementData {
     ticker: string;
@@ -470,6 +474,10 @@ interface FinancialMetricsOpts extends OptionalFinancialQueryOpts {
 }
 interface EarningsOpts extends OptionalFinancialQueryOpts {
 }
+interface EarningsTranscriptsOpts {
+    limit?: number;
+    reportPeriod?: string;
+}
 interface EarningsCalendarOpts {
     ticker?: string;
     tickers?: readonly string[];
@@ -499,6 +507,18 @@ interface GlobalInterestRatesOpts {
     endDate?: string;
     series?: readonly GlobalInterestRateSeriesKey[];
 }
+interface UsInterestRatesOpts {
+    limit?: number;
+    startDate?: string;
+    endDate?: string;
+    series?: readonly UsInterestRateSeriesKey[];
+}
+interface UsEconomicIndicatorsOpts {
+    limit?: number;
+    startDate?: string;
+    endDate?: string;
+    series?: readonly UsEconomicIndicatorSeriesKey[];
+}
 interface IncomeStatementsResponse extends ReadMetadata {
     period: FinancialPeriod;
     income_statements: IncomeStatement[];
@@ -536,6 +556,33 @@ interface EarningsResponse extends ReadMetadata {
     period: FinancialPeriod;
     earnings: EarningsRow[];
 }
+interface EarningsTranscriptParticipant {
+    participant_index: number;
+    name: string;
+    title: string | null;
+    firm: string | null;
+    role: string;
+}
+interface EarningsTranscriptSpeakerTurn {
+    turn_index: number;
+    speaker: string;
+    role: string;
+}
+interface EarningsTranscript {
+    headline: string;
+    report_period: string | null;
+    quarter_label: string | null;
+    published_at: string | null;
+    call_date: string | null;
+    question_count: number;
+    total_speaker_turns: number;
+    qa_turn_start_index: number | null;
+    participants: EarningsTranscriptParticipant[];
+    speaker_turns: EarningsTranscriptSpeakerTurn[];
+}
+interface EarningsTranscriptsResponse extends ReadMetadata {
+    transcripts: EarningsTranscript[];
+}
 interface EarningsCalendarEvent extends SnakeCasedProperties<Omit<EarningsCalendarEventData, "refreshedAt">> {
     name: string;
     refreshed_at: string;
@@ -813,7 +860,7 @@ interface GlobalInterestRateSeries {
     label: string;
     region: string;
     country_code: string;
-    frequency: "daily" | "monthly";
+    frequency: "daily" | "monthly" | "quarterly";
     latest: GlobalInterestRateObservation | null;
     observations: GlobalInterestRateObservation[];
 }
@@ -823,6 +870,38 @@ interface GlobalInterestRatesResponse {
     as_of: string | null;
     rates: GlobalInterestRateSeries[];
 }
+interface UsInterestRateSeries {
+    key: UsInterestRateSeriesKey;
+    series_id: string;
+    label: string;
+    region: string;
+    country_code: string;
+    frequency: "daily" | "monthly" | "quarterly";
+    latest: GlobalInterestRateObservation | null;
+    observations: GlobalInterestRateObservation[];
+}
+interface UsInterestRatesResponse {
+    source: "fred";
+    availability: DataAvailability;
+    as_of: string | null;
+    rates: UsInterestRateSeries[];
+}
+interface UsEconomicIndicatorSeries {
+    key: UsEconomicIndicatorSeriesKey;
+    series_id: string;
+    label: string;
+    region: string;
+    country_code: string;
+    frequency: "daily" | "monthly" | "quarterly";
+    latest: GlobalInterestRateObservation | null;
+    observations: GlobalInterestRateObservation[];
+}
+interface UsEconomicIndicatorsResponse {
+    source: "fred";
+    availability: DataAvailability;
+    as_of: string | null;
+    indicators: UsEconomicIndicatorSeries[];
+}
 type AnalystEstimate = SnakeCasedProperties<Omit<AnalystEstimateData, "ticker">>;
 type AnalystPriceTarget = SnakeCasedProperties<AnalystPriceTargetData>;
 interface AnalystEstimatesResponse {
@@ -956,6 +1035,7 @@ declare class TnFinancialData {
     getFinancialMetricsSnapshot(ticker: string, opts?: Pick<FinancialMetricsOpts, "period">): Promise<ApiResponse<FinancialMetricsSnapshotResponse>>;
     getBatchFinancialMetricsSnapshots(tickers: readonly string[], opts?: Pick<FinancialMetricsOpts, "period">): Promise<ApiResponse<BatchFinancialMetricsSnapshotsResponse>>;
     getEarnings(ticker: string, opts?: EarningsOpts): Promise<ApiResponse<EarningsResponse>>;
+    getEarningsTranscripts(ticker: string, opts?: EarningsTranscriptsOpts): Promise<ApiResponse<EarningsTranscriptsResponse>>;
     getEarningsCalendar(opts?: EarningsCalendarOpts): Promise<ApiResponse<EarningsCalendarResponse>>;
     getGeneralOverview(ticker: string, opts?: GeneralOverviewOpts): Promise<ApiResponse<GeneralOverviewResponse>>;
     getKeyStatistics(ticker: string): Promise<ApiResponse<KeyStatisticsResponse>>;
@@ -975,6 +1055,9 @@ declare class TnFinancialData {
     getInstitutionalOwnership(ticker: string, opts?: InstitutionalOwnershipOpts): Promise<ApiResponse<InstitutionalOwnershipResponse>>;
     getInvestorPortfolio(opts: InvestorPortfolioOpts): Promise<ApiResponse<InvestorPortfolioResponse>>;
     getGlobalInterestRates(opts?: GlobalInterestRatesOpts): Promise<ApiResponse<GlobalInterestRatesResponse>>;
+    getUsInterestRates(opts?: UsInterestRatesOpts): Promise<ApiResponse<UsInterestRatesResponse>>;
+    getUsEconomicIndicators(opts?: UsEconomicIndicatorsOpts): Promise<ApiResponse<UsEconomicIndicatorsResponse>>;
+    private buildMacroSeriesParams;
     getAnalystEstimates(ticker: string): Promise<ApiResponse<AnalystEstimatesResponse>>;
     getCompanyFacts(ticker: string): Promise<ApiResponse<{
         company_facts: CompanyFacts;
@@ -985,4 +1068,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 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 };
+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 };

package/dist/client/index.js

@@ -272,6 +272,12 @@ var TnFinancialData = class {
       `/earnings?${this.buildOptionalFinancialParams(ticker, opts)}`
     );
   }
+  async getEarningsTranscripts(ticker, opts) {
+    const params = new URLSearchParams({ ticker });
+    if (opts?.limit !== void 0) params.set("limit", String(opts.limit));
+    if (opts?.reportPeriod) params.set("report_period", opts.reportPeriod);
+    return this.request(`/earnings/transcripts?${params.toString()}`);
+  }
   async getEarningsCalendar(opts) {
     const params = this.buildEarningsCalendarParams(opts);
     return this.request(
@@ -367,12 +373,24 @@ var TnFinancialData = class {
     return this.request(`/institutional-ownership/investor?${params}`);
   }
   async getGlobalInterestRates(opts) {
+    const params = this.buildMacroSeriesParams(opts);
+    return this.request(`/macro/interest-rates/global?${params}`);
+  }
+  async getUsInterestRates(opts) {
+    const params = this.buildMacroSeriesParams(opts);
+    return this.request(`/macro/interest-rates/us?${params}`);
+  }
+  async getUsEconomicIndicators(opts) {
+    const params = this.buildMacroSeriesParams(opts);
+    return this.request(`/macro/economic-indicators/us?${params}`);
+  }
+  buildMacroSeriesParams(opts) {
     const params = new URLSearchParams();
     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?.series && opts.series.length > 0) params.set("series", opts.series.join(","));
-    return this.request(`/macro/interest-rates/global?${params}`);
+    return params;
   }
   async getAnalystEstimates(ticker) {
     return this.request(

package/package.json

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

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

@@ -1,6 +1,6 @@
 ---
 name: tn-financial-data
-description: Use this skill first for covered US equity data questions and covered-universe screens. Query server-backed company facts, general overviews, financials, analyst estimates, segmented revenues, prices, corporate actions, news, insider trades, institutional ownership, investor 13F portfolios, raw SEC filings, and global interest rates through the tn-financial-data CLI.
+description: Use this skill first for covered US equity data questions and covered-universe screens. Query server-backed company facts, general overviews, financials, analyst estimates, segmented revenues, prices, corporate actions, news, insider trades, institutional ownership, investor 13F portfolios, raw SEC filings, and global or US macro series through the tn-financial-data CLI.
 license: MIT
 ---
 
@@ -29,7 +29,7 @@ Covered reads include:
 - insider trades, issuer-level institutional ownership, and investor `13F` portfolios
 - SEC filing discovery plus bounded raw filing text for `10-K`, `10-Q`, and `8-K`
 - covered-universe screening and ranking
-- curated global central-bank and rate series
+- stored global central-bank history plus FRED-backed US macro history through the hosted `tn-financial-data` API
 
 ## Routing Principles
 
@@ -39,11 +39,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 +56,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
@@ -70,6 +73,7 @@ tn-financial-data query financials --ticker AAPL --period annual --statement all
 tn-financial-data query financial-metrics --ticker AAPL --period annual --limit 4
 tn-financial-data query financial-metrics-snapshot --ticker AAPL
 tn-financial-data query earnings --ticker AAPL --period quarterly --limit 8
+tn-financial-data query earnings-transcripts --ticker AAPL --limit 4
 tn-financial-data query earnings-calendar --tickers AAPL,MSFT --start-date 2026-04-02 --end-date 2026-04-16
 tn-financial-data query quarterly-highlights --ticker AAPL
 tn-financial-data query filings --ticker AAPL --filing-type 8-K --limit 10
@@ -87,6 +91,8 @@ tn-financial-data query investor-portfolio --investor vanguard --limit 20
 tn-financial-data query screen-fields
 tn-financial-data query screen --filter "trailing_pe < 25" --filter "recommendation_key = buy" --limit 10
 tn-financial-data query global-rates --series ecb_refi,boe_sonia --limit 10
+tn-financial-data query us-rates --series us_treasury_2y,us_treasury_10y,fed_funds_rate --start-date 2021-01-01 --end-date 2026-04-01 --limit 2000
+tn-financial-data query us-economic-indicators --series us_cpi,us_unemployment,us_gdp --start-date 2021-01-01 --end-date 2026-04-01 --limit 120
 ```
 
 Practical defaults:
@@ -94,13 +100,17 @@ Practical defaults:
 - Use `general-overview` for broad one-ticker prompts like “what’s up with NVDA?”
 - 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
 - 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
 - Do not start Apple product-mix prompts with `segmented-revenues`; that surface only exposes broad `Product` and `Service` rollups, while `quarterly-highlights` carries the product-line fields the prompt usually wants
 - Use `financials`, `financial-metrics`, `earnings`, `analyst-estimates`, `segmented-revenues`, `prices`, `snapshot`, `dividends`, `splits`, or `news` when the user asks for a specific slice
 - Use `investor-portfolio` for prompts like “What does Vanguard hold?” or “Show Berkshire’s latest 13F portfolio.”
-- Use `global-rates` for central-bank and rate-comparison prompts
+- 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. 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. 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.
 
 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

@@ -19,6 +19,7 @@ Auth rule:
 - for compare prompts, try to use matching command families and comparable periods across the names
 - for investor-filer prompts like "what does Vanguard hold?", start with `investor-portfolio`
 - for central-bank / global-rate comparisons, start with `global-rates`
+- for US Treasury, Fed, CPI, GDP, or unemployment prompts, start with `us-rates` or `us-economic-indicators`
 
 ## Query Commands
 
@@ -49,6 +50,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
 
@@ -136,6 +138,19 @@ Meaning:
 - if no matching quarterly statement exists for a reported quarter, the row still appears but statement-derived fields can be `null`
 - do not use Yahoo key-statistics growth fields as a substitute for statement-line YoY when the question is about revenue, operating income, net income, or EPS
 
+Earnings transcripts:
+
+```bash
+tn-financial-data query earnings-transcripts --ticker AAPL --limit 4
+tn-financial-data query earnings-transcripts --ticker AAPL --report-period 2025-12-27
+```
+
+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`
+- 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
+
 Earnings calendar:
 
 ```bash
@@ -332,8 +347,34 @@ tn-financial-data query global-rates --series ecb_refi,boe_sonia --limit 10
 
 Meaning:
 - preferred first read for central-bank and global-rate prompts
+- reads stored macro history from the hosted API, including FRED-backed US series
 - natural-language mappings include ECB refi, ECB deposit, BOE Sonia, SNB call money, BOJ call money, BOC call money, and RBA 3M
 
+US rates:
+
+```bash
+tn-financial-data query us-rates --series us_treasury_2y,us_treasury_10y,fed_funds_rate --start-date 2021-01-01 --end-date 2026-04-01 --limit 2000
+```
+
+Meaning:
+- preferred first read for US Treasury curve and Fed funds prompts
+- reads stored macro history from the hosted API, including FRED-backed US series
+- returns historical observations plus a `latest` point per series
+- natural-language aliases include `2y`, `5y`, `10y`, `30y`, and `fedfunds`
+
+US economic indicators:
+
+```bash
+tn-financial-data query us-economic-indicators --series us_cpi,us_unemployment,us_gdp --start-date 2021-01-01 --end-date 2026-04-01 --limit 120
+```
+
+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:
 - `--api-key`
 - `--base-url`