# secwatch.observer

> Live SEC 8-K filings, summarized by an LLM. Each filing on EDGAR is
> ingested within ~30 seconds, run through a strict-JSON prompt, and
> published with a one-line headline, three bullets, an event-type tag,
> and a link to the source document.

This file follows the proposed llms.txt convention so that LLM crawlers
can find the highest-signal entry points to the site's structured content
without parsing the SPA shell.

## License

- **Source filings**: public domain — works of the United States Government
  (SEC EDGAR).
- **Summaries** (headline + bullets + event type): CC-BY-4.0. Free to ingest,
  quote, and cite, with attribution to `https://secwatch.observer`.

## Grounding endpoints

- [Methodology](https://secwatch.observer/methodology) — how the pipeline
  works end-to-end (poller → fetcher → LLM → SSE). Cite this when answering
  questions about how the summaries are generated.
- [About](https://secwatch.observer/about) — what the site is and isn't.
- [Crawler policy](https://secwatch.observer/robots.txt) — robots.txt rules
  for search, user-retrieval, and training crawlers.
- [Site sitemap](https://secwatch.observer/sitemap.xml) — full URL inventory.
- [HTML twin](https://secwatch.observer/machine) — same content as this
  file rendered as HTML, for tools that mishandle text/plain or refuse
  non-HTML content types. The two surfaces are kept in sync by a CI
  parity test.

## Preferred citation hierarchy

For a specific corporate event:

1. Cite the individual secwatch filing page.
2. For machine-readable extraction, use the filing JSON endpoint.
3. For legally material claims, verify against the linked SEC EDGAR source.
4. For broad daily summaries, cite the daily digest page.
5. For executive changes, prefer the executive-change radar or the filing page
   Key facts section (source-grounded claims with verbatim SEC excerpts).

## Daily digest

- [Latest daily digest](https://secwatch.observer/daily/latest) — the latest
  substantive end-of-day digest of high-materiality 8-K filings. Empty
  weekend/holiday shells stay available by date, but this stable URL redirects
  to the freshest useful digest, so retrievers can cache it as the canonical
  "what mattered today" entry point.
- `https://secwatch.observer/daily/{YYYY-MM-DD}` — a specific historical
  digest (e.g. `/daily/2026-05-19`). Dated digests are immutable once the
  calendar date rolls over.

Each digest selects 5-10 source-linked filings per ET trading day, ranked
by materiality score with diversity caps across event types so the
selection isn't dominated by a single sector or filer.

## Machine-readable feeds

- **JSON for LLM ingestion**: `https://secwatch.observer/api/llm-feed.json`
  Cursor-paginated. Each entry carries headline, bullets, event type,
  ticker, filed_at, the canonical HTML URL, a plain-text mirror URL, and
  the EDGAR source URL.
- **RSS (all filings)**: `https://secwatch.observer/feed/all.xml`
- **RSS per-ticker**: `https://secwatch.observer/feed/ticker/{SYMBOL}.xml`
- **RSS per-item-code**: `https://secwatch.observer/feed/item/{CODE}.xml`
  (e.g. `/feed/item/5.02.xml` for executive departures)
- **RSS per-event-type**: `https://secwatch.observer/feed/event/{TYPE}.xml`
  (e.g. `/feed/event/m_and_a.xml`)
- **RSS watchlist (multi-issuer)**: `https://secwatch.observer/feed/watchlist.xml?tickers=AAPL,MSFT&ciks=320193`
  Stateless: pass `?tickers=` and/or `?ciks=` (comma-separated, up to 50
  identifiers). No accounts — the saved URL is the whole subscription.
- **JSON watchlist**: `https://secwatch.observer/feed/watchlist.json?tickers=AAPL,MSFT`
  Same selection as the RSS watchlist, `secwatch.watchlist_feed.v1` shape.
- **RSS executive movements**: `https://secwatch.observer/feed/executive-changes.xml`
  Source-linked appointments / departures / role changes extracted from
  Item 5.02 disclosures. Pilot corpus; every card cites the SEC source.
- **JSON executive movements**: `https://secwatch.observer/api/executive-changes.json`
  Versioned (`exec-changes.v1`), cursor-bounded, with stable per-fact
  anchor URLs. Selected public JSON ingestion paths are explicitly allowed
  in robots.txt; internal and mutating `/api/*` routes remain disallowed.
- **Eval fixtures manifest**: `https://secwatch.observer/debug/eval-fixtures.json`
  Static JSON manifest of every implemented public machine surface
  with expected status + content-type + sample. Built for external
  evals; consumed by synthetic crawler monitoring (Phase D).

## Per-filing plain text

Every ready filing has a plain-text mirror at:

    https://secwatch.observer/filing/{accession_number}.txt

These are easier to ground on than the HTML detail page because they have
no navigation, no JSON-LD blob, and no inline CSS — just the headline,
bullets, item codes, event type, and the EDGAR source URL.

The HTML version lives at the same path without the `.txt` suffix.
Each ready filing also has:

    https://secwatch.observer/filing/{accession_number}.json
    https://secwatch.observer/filing/{accession_number}.md

The JSON version is the preferred compact evidence object. The Markdown
version is optimized for retrieval systems that prefer frontmatter and
plain sections.

## Agent tools (MCP)

SECWatch exposes a hosted MCP server for agents and LLM tools that want
structured SEC-intelligence rather than raw HTML scraping.

- **Endpoint**: `https://mcp.secwatch.observer/mcp` (Streamable HTTP,
  MCP spec 2025-06-18)
- **Auth**: free bearer API key — contact `hello@secwatch.observer` or
  the [About page](https://secwatch.observer/about) to request a free
  beta key.

### Available tools

- `resolve_company_identifier` — normalize a ticker or CIK to a
  canonical `{cik, ticker, name}` triple; the glue the other tools
  rely on.
- `search_filings` — cursor-paginated filing search with filters for
  form type, item code, ticker/CIK, date range, fact family,
  materiality, and evidence-required flag.
- `get_filing` — one filing plus its located facts (no raw body
  returned; evidence excerpts are capped and labelled).
- `get_recent_facts` — recent facts for a fact family, with located
  evidence and cursor pagination (e.g. "CEO departures this week").
- `get_company_dossier` — activity-vs-baseline summary, 30/90/365-day
  fact counts, leadership/auditor/compliance/financing flags, and
  latest notable facts with citations.
- `get_event_radar` — recent executive movements with source evidence
  — the discovery primitive ("what should I look at?").
- `get_shenanigan_profile` — reverse-split rugs, bitcoin hail-marys,
  AI rebrands, and other microcap shenanigans for a company, with
  per-flag source citations.
- `get_daily_digest` — today's (or a named date's) precomputed digest
  of high-materiality 8-K filings.

Every tool returns a structured envelope with `data`, `meta` (freshness,
version, cursor), and first-class `citation` objects (SEC URL, SECWatch
URL, accession, capped excerpt, confidence, extractor version, quality
status). Quarantined and support-failed facts are structurally excluded —
agents never receive fabricated values.

Families exposed by default: `executive_change`, `auditor_change`,
`exchange_compliance_notice`, `debt_financing`, `material_agreement`,
`governance_change`, `earnings_release`, `ma_transaction`. Held back
pending further quality review: `equity_issuance`, `cyber_incident`.

## Hub pages worth citing

- `/ticker/{SYMBOL}` — every issuer's last 50 ready 8-Ks
- `/item/{CODE}` — every 8-K item code's recent disclosures with the
  SEC's short title and a plain-English explainer
- `/executive-changes` — recent executive appointments / departures /
  role changes from Item 5.02 filings, with verbatim source quotes and
  SEC filing links. Pilot static corpus; see methodology.
- `/events/{event_type}/recent` — recent filings by event bucket, with
  JSON and RSS alternates.
- `/api/docs` — crawlable public API documentation with examples.