tn-financial-data 0.1.3 → 0.2.0

package/README.md

@@ -37,7 +37,7 @@ This package is the hosted agent-facing surface only. The repo's website, local
 npm install -g tn-financial-data
 
 export TN_FINANCIAL_DATA_API_KEY=<your-api-key>
-tn-financial-data query available-tickers
+tn-financial-data query resolve-ticker --query google
 ```
 
 Live reads accept:
@@ -51,6 +51,8 @@ Optional base URL override:
 - `TN_FINANCIAL_DATA_API_BASE_URL`
 
 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.
 
 Production default:
 
@@ -61,6 +63,7 @@ https://api.truenorth-financial.ai/v1
 ## Quick Start
 
 ```bash
+tn-financial-data query resolve-ticker --query google
 tn-financial-data query available-tickers
 tn-financial-data query company --ticker AAPL
 tn-financial-data query filings --ticker AAPL --filing-type 8-K --limit 5
@@ -169,8 +172,11 @@ const client = new TnFinancialData({
   apiKey: process.env.TN_FINANCIAL_DATA_API_KEY!,
 });
 
+const resolution = await client.resolveTicker("google");
+console.log(resolution.status, resolution.resolved_ticker);
+
 const filings = await client.getFilings("AAPL", {
-  filingType: ["8-K"],
+  filingTypes: ["8-K"],
   limit: 3,
 });
 
@@ -179,7 +185,7 @@ console.log(filings.filings[0]?.accession_number);
 const filingItems = await client.getFilingItems("AAPL", {
   accessionNumber: "0000320193-26-000005",
   filingType: "8-K",
-  item: ["2.02"],
+  items: ["2.02"],
   includeExhibits: true,
 });
 

package/dist/cli.js

@@ -230,6 +230,11 @@ var TnFinancialData = class {
   async getAvailableTickers() {
     return this.request("/financials/income-statements/tickers");
   }
+  async resolveTicker(query) {
+    return this.request(
+      `/tickers/resolve?${new URLSearchParams({ q: query })}`
+    );
+  }
   async getPrices(ticker, opts) {
     const params = new URLSearchParams({
       ticker,
@@ -568,13 +573,14 @@ function rootHelp() {
     "tn-financial-data",
     "",
     "Usage:",
-    "  tn-financial-data query <available-tickers|company|filings|filing-items|general-overview|financials|financial-metrics|financial-metrics-snapshot|earnings|quarterly-highlights|analyst-estimates|prices|snapshot|news|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|quarterly-highlights|analyst-estimates|prices|snapshot|news|insider-trades|institutional-ownership|investor-portfolio|global-rates|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",
     "",
     "Examples:",
     "  tn-financial-data query available-tickers",
+    '  tn-financial-data query resolve-ticker --query "google"',
     "  tn-financial-data query financials --ticker AAPL --period annual --statement all",
     "  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 --full-text",
@@ -608,6 +614,7 @@ function queryHelp() {
   return [
     "Usage:",
     "  tn-financial-data query available-tickers [--api-key <key>] [--base-url <url>]",
+    "  tn-financial-data query resolve-ticker --query <text> [--api-key <key>] [--base-url <url>]",
     "  tn-financial-data query company --ticker <symbol> [--api-key <key>] [--base-url <url>]",
     "  tn-financial-data query filings --ticker <symbol> [--filing-type <csv>] [--start-date <date>] [--end-date <date>] [--limit <n>] [--api-key <key>] [--base-url <url>]",
     "  tn-financial-data query filing-items --ticker <symbol> --accession-number <accession> [--filing-type <10-K|10-Q|8-K>] [--item <csv>] [--full-text] [--include-exhibits] [--api-key <key>] [--base-url <url>]",
@@ -728,6 +735,7 @@ function buildOpenCliDocument() {
     ],
     examples: [
       "tn-financial-data query available-tickers",
+      'tn-financial-data query resolve-ticker --query "google"',
       "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 --full-text",
       "tn-financial-data query general-overview --ticker AAPL --period quarterly --financial-limit 4 --news-limit 5",
@@ -785,6 +793,24 @@ function buildOpenCliDocument() {
             name: "available-tickers",
             description: "Fetch the current supported ticker snapshot with financial and news freshness timestamps."
           },
+          {
+            name: "resolve-ticker",
+            description: "Resolve a company keyword or exact symbol against the supported ticker universe without silently swapping share classes.",
+            options: [
+              {
+                name: "query",
+                required: true,
+                arguments: [
+                  {
+                    name: "text",
+                    required: true,
+                    description: "Company name, brand, prompt fragment, or ticker text."
+                  }
+                ],
+                description: "Query text to resolve."
+              }
+            ]
+          },
           {
             name: "company",
             description: "Fetch company facts for a single ticker.",
@@ -827,12 +853,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."
               },
               {
@@ -1671,6 +1701,18 @@ var QUERY_SUBCOMMAND_HELP = {
     ],
     "tn-financial-data query available-tickers"
   ),
+  "resolve-ticker": renderHelp(
+    "resolve-ticker",
+    [
+      "Resolve a company keyword or exact symbol against the supported ticker universe without silently swapping share classes."
+    ],
+    [
+      "--query <text>    Required. Company name, brand, prompt fragment, or ticker text.",
+      "--api-key <key>   API key. Overrides TN_FINANCIAL_DATA_API_KEY.",
+      "--base-url <url>  API base URL override."
+    ],
+    'tn-financial-data query resolve-ticker --query "google"'
+  ),
   company: renderHelp(
     "company",
     ["Fetch the basic company identity record for a single ticker."],
@@ -2060,6 +2102,11 @@ async function handleQuery(parsed, runtime, deps) {
     case "available-tickers":
       printJson(runtime, await client.getAvailableTickers());
       return 0;
+    case "resolve-ticker": {
+      const query = requireOption(parsed, "query");
+      printJson(runtime, await client.resolveTicker(query));
+      return 0;
+    }
     case "company": {
       const ticker = requireOption(parsed, "ticker");
       printJson(runtime, await client.getCompanyFacts(ticker));

package/dist/client/index.d.ts

@@ -498,6 +498,33 @@ interface AvailableTickersResponse {
     as_of: string | null;
     tickers: AvailableTicker[];
 }
+type TickerResolutionStatus = "exact_supported" | "resolved" | "ambiguous" | "exact_unsupported" | "none";
+type TickerResolutionIntent = "ticker" | "keyword";
+type TickerResolutionMatchKind = "ticker_exact" | "ticker_format" | "alias_exact" | "company_name" | "company_prefix" | "company_tokens";
+type TickerResolutionRelationship = "supported" | "format_alias" | "brand_alias" | "deprecated_symbol" | "same_issuer_other_share_class";
+type TickerResolutionConfidence = "high" | "medium" | "low";
+interface TickerResolutionCandidate {
+    ticker: string;
+    name: string;
+    financials_updated_at: string | null;
+    news_updated_at: string | null;
+    updated_at: string;
+    match_kind: TickerResolutionMatchKind;
+    relationship: TickerResolutionRelationship;
+    confidence: TickerResolutionConfidence;
+    matched_alias: string | null;
+}
+interface TickerResolutionResponse {
+    query: string;
+    normalized_query: string;
+    intent: TickerResolutionIntent;
+    as_of: string | null;
+    extracted_query?: string;
+    status: TickerResolutionStatus;
+    resolved_ticker: string | null;
+    resolved_name: string | null;
+    candidates: TickerResolutionCandidate[];
+}
 interface PriceHistoryResponse extends ReadMetadata {
     interval: PriceInterval;
     prices: PriceBar[];
@@ -812,6 +839,7 @@ declare class TnFinancialData {
     getGeneralOverview(ticker: string, opts?: GeneralOverviewOpts): Promise<ApiResponse<GeneralOverviewResponse>>;
     getKeyStatistics(ticker: string): Promise<ApiResponse<KeyStatisticsResponse>>;
     getAvailableTickers(): Promise<ApiResponse<AvailableTickersResponse>>;
+    resolveTicker(query: string): Promise<ApiResponse<TickerResolutionResponse>>;
     getPrices(ticker: string, opts: PriceOpts): Promise<ApiResponse<PriceHistoryResponse>>;
     getPriceSnapshot(ticker: string): Promise<ApiResponse<PriceSnapshotResponse>>;
     getNews(ticker: string, opts?: NewsOpts): Promise<ApiResponse<NewsResponse>>;
@@ -831,4 +859,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 CashFlowStatement, type CashFlowStatementsResponse, type ClientOptions, type CompanyFacts, type ConsensusSurprise, DEFAULT_API_BASE_URL, type DataAvailability, 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 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, TnFinancialData };
+export { type AnalystEstimate, type AnalystEstimatesResponse, type AnalystPriceTarget, ApiError, type ApiResponse, type AvailableTicker, type AvailableTickersResponse, type BalanceSheet, type BalanceSheetsResponse, type CashFlowStatement, type CashFlowStatementsResponse, type ClientOptions, type CompanyFacts, type ConsensusSurprise, DEFAULT_API_BASE_URL, type DataAvailability, 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 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 TickerResolutionCandidate, type TickerResolutionConfidence, type TickerResolutionIntent, type TickerResolutionMatchKind, type TickerResolutionRelationship, type TickerResolutionResponse, type TickerResolutionStatus, TnFinancialData };

package/dist/client/index.js

@@ -228,6 +228,11 @@ var TnFinancialData = class {
   async getAvailableTickers() {
     return this.request("/financials/income-statements/tickers");
   }
+  async resolveTicker(query) {
+    return this.request(
+      `/tickers/resolve?${new URLSearchParams({ q: query })}`
+    );
+  }
   async getPrices(ticker, opts) {
     const params = new URLSearchParams({
       ticker,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tn-financial-data",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "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,9 +37,13 @@ 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.
+- 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.
+- 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.
 - Only leave this skill when the user explicitly wants outside sources or the stored dataset does not cover the question.
 
 ## Answer Principles
@@ -55,6 +61,7 @@ Covered reads include:
 These are the main commands an agent should reach for first. For full flags and examples, read [references/cli.md](references/cli.md).
 
 ```bash
+tn-financial-data query resolve-ticker --query google
 tn-financial-data query available-tickers
 tn-financial-data query company --ticker AAPL
 tn-financial-data query general-overview --ticker AAPL
@@ -63,6 +70,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
@@ -79,7 +88,9 @@ tn-financial-data query global-rates --series ecb_refi,boe_sonia --limit 10
 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
 - 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 `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.

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 `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."
 
 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 `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.
 
 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,10 +2,15 @@
 
 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
 - throttling surfaces as a clean CLI error; raw HTTP callers should read `X-RateLimit-*` and `Retry-After`
+- for ambiguous company, brand, or free-form one-company prompts, start with `resolve-ticker`
 - for broad ticker prompts like "what's up with NVDA?", start with `general-overview`
 - for covered recent-news prompts like "show me recent Nvidia news", start with `news`
 - for latest-quarter product mix, supplemental KPIs, AWS segment profitability, or Tesla free-cash-flow prompts, start with `quarterly-highlights`
@@ -16,6 +21,21 @@ Auth rule:
 
 ## Query Commands
 
+Resolve ticker:
+
+```bash
+tn-financial-data query resolve-ticker --query google
+tn-financial-data query resolve-ticker --query GOOGL
+```
+
+Use this to resolve a company keyword, brand name, prompt fragment, or exact symbol against the hosted supported universe.
+
+Resolution semantics:
+- returns one of `exact_supported`, `resolved`, `ambiguous`, `exact_unsupported`, or `none`
+- use this before guessing a ticker from a company or brand prompt
+- `exact_unsupported` can suggest a nearby supported line, but that suggestion is a hint, not an automatic substitution
+- exact share-class mismatches must stay explicit to the user
+
 Available tickers:
 
 ```bash
@@ -24,6 +44,11 @@ tn-financial-data query available-tickers
 
 Use this to fetch the current supported ticker snapshot from the API. It returns ticker symbols plus the latest financial-data and news-data timestamps tracked in the database.
 
+Support rule:
+- treat this list as the package's authoritative support snapshot
+- 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
+
 Company facts:
 
 ```bash
@@ -123,6 +148,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 +316,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.