Merge pull request #138 from defog-ai/docs-ipo-prospectus

Describe IPO registration statements and prospectuses in the filings docs

Author: rishsriv

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "factiq",
   "description": "Answer economic and financial data questions with real data from FactIQ — official statistics, market data, earnings-call transcripts, executive media appearances, central-bank speeches and minutes, a curated business-news feed, and satellite-derived data (nighttime lights, shipping and port activity, reservoir levels, crop fires and wildfires with mappable footprints, NO2/SO2/CO activity, smoke and dust aerosol, monsoon rainfall) — return sourced answers, chart JSON, or report JSON.",
-  "version": "0.45.0",
+  "version": "0.46.0",
   "author": {
     "name": "FactIQ",
     "url": "https://www.factiq.com"

.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "factiq",
   "description": "Answer economic and financial data questions with real FactIQ data — official data, markets, earnings calls, executive media appearances, central-bank documents, and satellite-derived signals including crop fires and wildfires — then return sourced answers, chart JSON, or report JSON.",
-  "version": "0.45.0",
+  "version": "0.46.0",
   "author": {
     "name": "FactIQ",
     "url": "https://www.factiq.com"

references/data/schemas.md

@@ -28,7 +28,7 @@ States lists the tables to use.
 | `us_health` | Centers for Disease Control and Prevention | Measles cases by week (from 2022), by year (from 1962) and by state, measles hospitalizations, deaths and outbreaks, and kindergarten vaccination coverage and exemptions by state and school year. For other countries use `who_gho` |
 | `us_immigration` | Department of Labor (OFLC disclosure data) | H-1B labor condition applications and PERM labor certifications (the Labor Department step of an employment-based green card) per employer and federal fiscal year, from 2008: certified, denied and withdrawn, plus H-1B positions certified. One series per employer with at least 10 cases in some year, plus all-employer totals |
 | `sec` | SEC EDGAR | The company series behind `search_company_filings` as ordinary `series`/`data_points` tables, for about 2,500 US-listed companies and foreign filers: XBRL statements and segment detail (`sec_10k`, `sec_10q`, `sec_20f`, `sec_40f`, `sec_6k_interim`), forward guidance (`sec_guidance`), operating KPIs (`sec_kpi`), and SIC and NAICS classifications. Statements from 2008 |
-| `filings` | Company filings: US SEC filers (10-K, 10-Q, 8-K, 20-F, 40-F, 6-K) and companies listed in Germany, the UK, France, Switzerland, India, Japan, and South Korea (`issuers.source_schema` = `'german_filings'`, `'uk_filings'`, `'fr_filings'`, `'ch_filings'`, `'in_filings'`, `'jp_filings'`, `'kr_filings'`; Indian tickers end in `.NS`, e.g. `RELIANCE.NS`; Japanese and Korean tickers carry the exchange suffix, e.g. `7203.T` for Toyota Motor and `005930.KS` for Samsung Electronics) | The archive behind `search_company_filings`. Use the tool for one company; use `run_sql` on `filings` for joins and aggregations across companies. Start from `securities` (`ticker`, `issuer_id`, `is_primary`) and `issuers` (`id`, `canonical_name`). `source_filings` is one row per filing (`issuer_id`, `form_type`, `fiscal_year`, `fiscal_period`, `period_end`, `published_at`, `source_url`). `facts` is one row per extracted value (`filing_id`, `source_series_id`, `source_label`, `metric_class`, `period_start`, `period_end`, `period_basis`, `value`, `unit`, `segment_axis`, `segment_member`): always filter `is_serving AND is_active` (the other rows are superseded or never promoted) and by filing, series, or issuer, because the table holds more than 150 million rows. `source_series` (`source_series_id`, `issuer_id`, `dataset_code`, `title`, `measurement_units`, `frequency`, `is_serving`) and `serving_observations` (`source_series_id`, `time`, `value`, `unit`, `filing_id`) are the series and their points; `dataset_code` separates XBRL statements (`sec_10k`, `sec_10q`, `sec_20f`, `sec_40f`, `sec_6k_interim`), management's forward guidance (`sec_guidance`), and company-specific operating KPIs like ARR/RevPAR/subscribers (`sec_kpi`). `filing_claims` holds MD&A and earnings-release commentary and year-over-year risk-factor changes (`claim_kind`, `ticker`, `fiscal_year`, `fiscal_period`, `section`, `claim_family`, `topic`, `canonical_statement`, `verbatim_quote`, `source_url`; quote only `verbatim_quote`). `filing_risks` is one row per risk-factor heading in an annual report (`cik`, `fiscal_year`, `heading`, `summary`). The remaining tables are pipeline bookkeeping. `get_series(schema="filings", series_id=...)` and `describe_dataset("filings", "<dataset_code>")` also work: they return the same result as with `schema="sec"`, and the dataset codes are the `sec_*` codes listed above. Put a row's `source_url` beside any figure you use; `search_company_filings(format="json")` returns the same links as `source_link` on filing and fact nodes. |
+| `filings` | Company filings: US SEC filers (10-K, 10-Q, 8-K, 20-F, 40-F, 6-K, plus the IPO registration statements S-1 and F-1 and the final prospectus, 424B4 or 424B1) and companies listed in Germany, the UK, France, Switzerland, India, Japan, and South Korea (`issuers.source_schema` = `'german_filings'`, `'uk_filings'`, `'fr_filings'`, `'ch_filings'`, `'in_filings'`, `'jp_filings'`, `'kr_filings'`; Indian tickers end in `.NS`, e.g. `RELIANCE.NS`; Japanese and Korean tickers carry the exchange suffix, e.g. `7203.T` for Toyota Motor and `005930.KS` for Samsung Electronics) | The archive behind `search_company_filings`. Use the tool for one company; use `run_sql` on `filings` for joins and aggregations across companies. Start from `securities` (`ticker`, `issuer_id`, `is_primary`) and `issuers` (`id`, `canonical_name`). `source_filings` is one row per filing (`issuer_id`, `form_type`, `fiscal_year`, `fiscal_period`, `period_end`, `published_at`, `source_url`). `facts` is one row per extracted value (`filing_id`, `source_series_id`, `source_label`, `metric_class`, `period_start`, `period_end`, `period_basis`, `value`, `unit`, `segment_axis`, `segment_member`): always filter `is_serving AND is_active` (the other rows are superseded or never promoted) and by filing, series, or issuer, because the table holds more than 150 million rows. `source_series` (`source_series_id`, `issuer_id`, `dataset_code`, `title`, `measurement_units`, `frequency`, `is_serving`) and `serving_observations` (`source_series_id`, `time`, `value`, `unit`, `filing_id`) are the series and their points; `dataset_code` separates XBRL statements (`sec_10k`, `sec_10q`, `sec_20f`, `sec_40f`, `sec_6k_interim`), management's forward guidance (`sec_guidance`), and company-specific operating KPIs like ARR/RevPAR/subscribers (`sec_kpi`). Two codes come from IPO registration statements: `sec_registration` holds statement figures for the years before a company's first periodic report (a figure that a later report states for the same period replaces it), and `sec_offering` holds the offering terms (price range, shares offered, proceeds). `filing_claims` holds MD&A and earnings-release commentary (including the MD&A of a final IPO prospectus, `form_type` `424B4` or `424B1`) and year-over-year risk-factor changes (`claim_kind`, `ticker`, `fiscal_year`, `fiscal_period`, `section`, `claim_family`, `topic`, `canonical_statement`, `verbatim_quote`, `source_url`; quote only `verbatim_quote`). `filing_risks` is one row per risk-factor heading in an annual report or a final IPO prospectus (`cik`, `fiscal_year`, `heading`, `summary`). The remaining tables are pipeline bookkeeping. `get_series(schema="filings", series_id=...)` and `describe_dataset("filings", "<dataset_code>")` also work: they return the same result as with `schema="sec"`, and the dataset codes are the `sec_*` codes listed above, except `sec_registration` and `sec_offering`, which `describe_dataset` does not describe; read those through `search_company_filings` or `run_sql` on `source_series`. Put a row's `source_url` beside any figure you use; `search_company_filings(format="json")` returns the same links as `source_link` on filing and fact nodes. |
 | `screener` | FactIQ, from SEC filings and Nasdaq's public stock list | Finds companies that match conditions (sector, market value, valuation ratios, margins, growth). One view, `screener.companies`, with one row per US-listed company that files financial statements with the SEC (about 2,400 rows): price and `market_cap`, `price_to_sales`, `price_to_earnings`, `price_to_book`, `ev_to_sales`, latest-twelve-month revenue, income, cash flow and margins, and the latest balance sheet. No `series`/`data_points` tables: filter the view with one `run_sql` query. Prices are delayed about fifteen minutes; state `price_as_of` in the answer. **Read "Company screener" in `references/data/sql-guide.md` before writing SQL.** |
 | *(not a SQL schema)* | Earnings-call transcripts, decomposed into a claim graph | `search_earnings_transcripts` targets (selected with `search_target`): management statements (`claims`: `query`, `ticker` for tickers or `company_name` for company names (one or the other, both case-insensitive; `company_filter` is the old name of `ticker` and still works), `quarter_filter`, `claim_family`, claims-only `section`, `detail`, `limit`); Q&A pressure (`pressure_points`: query/company/quarter/linked `claim_family`/detail/limit; section ignored); company-level habits (`disclosure_profile`: direct lookup by the first ticker, not text or quarter search; other filters/detail/limit ignored); and corpus inventory (`coverage`: company/limit, not theme or quarter search; returns `calls_covered`, `earliest_period`, and `latest_period`). Text retrieval ranks strict matches above loose partial-term matches and uses trigram only when FTS is empty. For one-call notes, use coverage → exact quarter → bounded empty-query claims + pressure calls. Claim/pressure rows expose `transcript_id`, `source_block_index`, `qa_turn_id`, and `source_link`; `source_link.source_label` names the company or ticker, fiscal period, and earnings call transcript rather than the ingestion vendor. Quote only `verbatim_quote`, preserving any `[…]` omission marker (it stands for skipped transcript sentences between non-adjacent evidence spans); `canonical_statement` is normalized; neither `analyst_hypothesized` nor `mgmt_declined_to_confirm` is management speech. Put a provided source URL beside any used quote using the provided source label as link text; if it is null, report that the link is unavailable rather than searching for or inventing one. Never use `run_sql` on the gated `transcripts` schema or promise full-transcript/paginated access. See `references/report-patterns/earnings-intelligence.md` |
 | *(not a SQL schema)* | Executive podcasts, TV interviews, and conference appearances, plus documents published by central banks and monetary authorities (speeches, interviews, statements, press releases, minutes, press-conference transcripts, testimony, reports) | `search_media_appearances` performs deterministic strict lexical → loose any-term → trigram retrieval over precomputed claims and passage cards; no serving-time model. Use `search`, `claims`, `passages`, or `pressure_points` for timestamped paraphrase findings, `appearances` for video rows, and `coverage` for company-level structured-corpus inventory. `institution` (publisher-name substring) and `country` (ISO code, `EU` for the European Central Bank) restrict every target to official documents; `company` matches the subject of a claim, not its publisher. Dates are publication/upload dates; official documents also carry `event_date`. Never quote `canonical_paraphrase`, query `transcripts` with SQL, or infer absence before checking coverage and bounded synonym searches. See `references/report-patterns/media-intelligence.md` |