tn-financial-data 0.1.4 → 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.",
@@ -1675,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."],
@@ -2064,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.4",
+  "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

@@ -40,7 +40,10 @@ Covered reads include:
 - 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
@@ -58,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
@@ -84,6 +88,7 @@ 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

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 `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, 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."
+  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, 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.
+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

@@ -10,6 +10,7 @@ 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`
@@ -20,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
@@ -28,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