tn-financial-data 0.4.0 → 0.4.1

package/README.md

@@ -57,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:
 
@@ -90,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 |

package/dist/cli.js

@@ -929,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",
@@ -1637,7 +1637,7 @@ function buildOpenCliDocument() {
           },
           {
             name: "us-economic-indicators",
-            description: "Fetch US CPI, GDP, and unemployment series with historical observations.",
+            description: "Fetch US CPI, GDP, and unemployment series with historical observations. Returns raw series levels for client-side MoM or YoY transforms when needed.",
             options: [
               {
                 name: "series",
@@ -2180,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."
@@ -2521,7 +2524,10 @@ var QUERY_SUBCOMMAND_HELP = {
   ),
   "us-economic-indicators": renderHelp(
     "us-economic-indicators",
-    ["Fetch stored US CPI, GDP, and unemployment history from the hosted API."],
+    [
+      "Fetch stored US CPI, GDP, and unemployment history from the hosted API.",
+      "Returns raw series levels; derive MoM or YoY percentage changes from adjacent observations when needed."
+    ],
     [
       "--series <csv>      Optional comma-separated US economic indicator keys.",
       "--start-date <date> Optional start date (YYYY-MM-DD).",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tn-financial-data",
-  "version": "0.4.0",
+  "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

@@ -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
@@ -106,6 +109,8 @@ Practical defaults:
 - Use `investor-portfolio` for prompts like “What does Vanguard hold?” or “Show Berkshire’s latest 13F portfolio.”
 - Use `global-rates` for central-bank and cross-country rate-comparison prompts
 - Use `us-rates` and `us-economic-indicators` for FRED-backed US macro history such as Treasury yields, Fed funds, CPI, GDP, and unemployment
+- `available-tickers` is the equity-only support snapshot; do not use it as a macro coverage check
+- For MoM or YoY CPI prompts, fetch `us-economic-indicators` and compute the percentage change from adjacent `us_cpi` observations
 
 ## References
 

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

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

@@ -50,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
 
@@ -371,6 +372,7 @@ Meaning:
 - preferred first read for US CPI, GDP, and unemployment prompts
 - reads stored macro history from the hosted API
 - raw series only: `us_cpi` is the CPI index level, not a computed YoY inflation transform
+- for MoM or YoY CPI prompts, compute the percentage change from adjacent observations and say that the transform is derived from the raw series
 - natural-language aliases include `cpi`, `gdp`, and `unemployment`
 
 Shared query options: