tn-financial-data 0.1.3 → 0.1.4

package/dist/cli.js

@@ -827,12 +827,16 @@ function buildOpenCliDocument() {
               },
               {
                 name: "start-date",
-                arguments: [{ name: "date", required: true, description: "Inclusive lower bound." }],
+                arguments: [
+                  { name: "date", required: true, description: "Inclusive lower bound." }
+                ],
                 description: "Optional inclusive filing-date lower bound."
               },
               {
                 name: "end-date",
-                arguments: [{ name: "date", required: true, description: "Inclusive upper bound." }],
+                arguments: [
+                  { name: "date", required: true, description: "Inclusive upper bound." }
+                ],
                 description: "Optional inclusive filing-date upper bound."
               },
               {

package/package.json

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

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

@@ -1,10 +1,11 @@
 ---
 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, news, insider trades, institutional ownership, investor 13F portfolios, 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, news, insider trades, institutional ownership, investor 13F portfolios, raw SEC filings, and global interest rates through the tn-financial-data CLI.
 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`.
 
 ## Authentication
 
@@ -26,6 +27,7 @@ Covered reads include:
 - segment and geographic revenue mix
 - price history, latest price snapshot, and stored company news
 - 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
 
@@ -35,6 +37,7 @@ Covered reads include:
 - For a narrow ask, prefer the narrower read instead of widening the problem too early.
 - For Apple product mix or Greater China, Meta ad KPIs, Amazon `AWS` operating income or segment-profit prompts, and Tesla services-and-other or free-cash-flow prompts, start with `quarterly-highlights` before `segmented-revenues`, `financials`, or `general-overview`. For other covered issuers, `quarterly-highlights` now serves as a generic latest-quarter summary even when no issuer-specific release parser exists.
 - 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`.
 - Keep issuer-centric ownership (`institutional-ownership`) separate from investor-centric portfolio lookup (`investor-portfolio`).
 - If the company mapping is ambiguous, use `available-tickers` before guessing a ticker.
@@ -63,6 +66,8 @@ tn-financial-data query financial-metrics --ticker AAPL --period annual --limit
 tn-financial-data query financial-metrics-snapshot --ticker AAPL
 tn-financial-data query earnings --ticker AAPL --period quarterly --limit 8
 tn-financial-data query quarterly-highlights --ticker AAPL
+tn-financial-data query filings --ticker AAPL --filing-type 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 analyst-estimates --ticker AAPL
 tn-financial-data query segmented-revenues --ticker AAPL --period annual --limit 4
 tn-financial-data query prices --ticker AAPL --interval day --start-date 2025-01-01 --end-date 2025-01-31
@@ -80,6 +85,7 @@ Practical defaults:
 
 - Use `general-overview` for broad one-ticker prompts like “what’s up with NVDA?”
 - 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`, `news`, `prices`, or `snapshot` 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.”

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, and global-rate questions. 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 `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 `available-tickers` instead of guessing. Prefer synthesized, structured answers over raw dumps.
+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 `available-tickers` instead of guessing. 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, and global-rate questions. 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, resolve ambiguous names with `available-tickers`, 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, 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 `available-tickers`, and keep answers synthesized, structured, and user-facing."
 
 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, and global-rate questions. 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 `screen-fields` and `screen` for screens, `institutional-ownership` for issuer holders, and `investor-portfolio` for investor `13F` holdings. Resolve ambiguous company names with `available-tickers`, 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, 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 `available-tickers`, 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 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

@@ -2,6 +2,10 @@
 
 Use the CLI for agent access whenever possible.
 
+Published package:
+- install with `npm install -g tn-financial-data` when the CLI is not already present
+- the package ships the typed client, packaged skill bundle, and the same hosted `/v1` query surface used below
+
 Auth rule:
 - the published package reads credentials from flags and ambient process env, not from project-local `.env`
 - if there is any doubt, pass `--api-key` and `--base-url` explicitly
@@ -123,6 +127,34 @@ Meaning:
 - values are normalized into JSON with explicit units and `yoy_change` where the release provides a comparable prior-period baseline
 - when the prompt asks for a table plus one short bullet, keep the bullet descriptive and grounded in the returned fields; do not add speculative causes unless another fetched surface actually supports them
 
+Filings:
+
+```bash
+tn-financial-data query filings --ticker AAPL --filing-type 8-K --limit 10
+tn-financial-data query filings --ticker AAPL --filing-type 10-K,10-Q --start-date 2021-01-01 --end-date 2021-12-31 --limit 5
+```
+
+Meaning:
+- filing metadata index over stored SEC coverage
+- use this first when the user wants to find a specific filing, accession number, filing date, or form family
+- supports `10-K`, `10-Q`, `8-K`, `20-F`, `40-F`, and `6-K`
+- prefer this over guessing an accession number or hand-building SEC archive URLs
+
+Filing items:
+
+```bash
+tn-financial-data query filing-items --ticker AAPL --accession-number 0000320193-26-000005 --item 2.02 --include-exhibits
+tn-financial-data query filing-items --ticker AAPL --accession-number 0000320193-21-000105 --filing-type 10-K --item Item-1A,Item-7
+tn-financial-data query filing-items --ticker AAPL --accession-number 0000320193-26-000005 --full-text
+```
+
+Meaning:
+- bounded raw filing-text retrieval for one filing
+- use it when the user explicitly wants the filing text, a specific section, or the earnings-release exhibit tied to an `8-K`
+- `--full-text` returns the full primary filing body
+- `--include-exhibits` adds exhibit text such as `EX-99.1` when available
+- for `8-K` workflows, resolve the filing with `filings` first unless the accession number is already known
+
 Segmented revenues:
 
 ```bash
@@ -263,6 +295,7 @@ The published npm package is intentionally agent-facing:
 - `skill`
 - `describe opencli`
 - the typed TypeScript client
+- packaged access to raw SEC filing discovery and filing-item reads through the same hosted contract
 
 Self-hosting commands such as local API serving, migrations, and ingest flows live in the repository checkout and are intentionally outside the published npm contract.