# examples.yaml — canonical MCP scenarios (single source of truth)
# Rendered on the landing page (section 1.0 Ask) and mirrored by agents.md +
# MCP prompts/list templates (landing v4 P4, #81).
# Validator (scripts/validate.sh) checks ids, ask strings, and citations
# appear verbatim in index.html — keep line shapes stable.
#
# ⚠️ THE `steps:` LINES ARE NARRATIVE, NOT CALLABLE TOOL SIGNATURES.
# They are product-story shorthand and several name capabilities the MCP server
# does not expose. Do not copy them into an agent integration. The authoritative
# contract is `tools/list` — documented in agents.md §MCP Tools and mirrored in
# openapi.yaml `x-mcp-tools`; scripts/validate.sh keeps those three in sync.
#
# Reality check as of 2026-09-05, against mcp_server.rs `tool_list()`:
#   search(…)    -> not a tool. Use `unified_search` (federated semantic+lexical)
#                   or `vector_search` (embeddings only).
#   query(…)     -> not a tool. Use `run_sql`.
#   entities(…)  -> not a tool. There is no single-entity lookup; `entity_path`
#                   finds paths BETWEEN two entities (from, to).
#   events(…)    -> not a tool. Event rows are reached via `run_sql` over the
#                   allowlisted tables `events` / `pg_events` / `ch_events`.
#   calendar(…), email(…), watch(…) -> NO SUCH TOOL EXISTS. These are the
#                   "enterprise systems and personal context" aspiration in the
#                   site tagline, not shipped surface. `watch` in particular
#                   implies standing subscriptions/notification, which the
#                   read-only server does not provide.
# SQL in `steps:` that includes `FROM <table>` must use the run_sql allowlist
# (`events`, `pg_events`, `ch_events`, `audit_log` — policy.rs `ALLOWED_TABLES`);
# anything else is rejected 403. FEC and other connectors store rows in
# `ch_events`/`events` with `event_type` + JSON `payload` (read fields with
# `jsonExtractString(payload, 'key')`).
#
# The scenario IDs do correspond to real `prompts/list` entries
# (follow-the-money, scan-the-courts, meeting-brief, thesis-watch); the prompt
# templates, not these steps, are the machine-readable form.

version: 1

scenarios:
  - id: follow-the-money
    n: "01"
    title: Follow the money
    ask: "Which companies named in new federal rules donated to the committees overseeing them?"
    steps:
      - search(q="final rule" · Federal Register · last 90 days) -> 14 notices
      - entities(name="Acme Robotics") -> officers · donors · graph edges
      - query(SELECT jsonExtractString(payload, 'committee_id') AS committee, jsonExtractString(payload, 'contribution_receipt_amount') AS amount FROM ch_events WHERE event_type = 'fec.contribution' LIMIT 6) -> $48,200 · 6 gifts
    answer: "Acme appears in three new rules this quarter. Its officers gave $48,200 to members of the oversight committee."
    cite:
      - "1 · Federal Register · 91 FR 23114"
      - "2 · FEC itemized contributions · Q2"

  - id: scan-the-courts
    n: "02"
    title: Scan the courts
    ask: "Is anyone challenging the new broadband rule?"
    steps:
      - search(q="petition for review" · Court opinions · related 91 FR 44102) -> 2 cases
      - query(SELECT docket, status, next_hearing) -> lead 24-1188 · argued
    answer: "Two challenges filed. Lead case 24-1188 was argued June 12; a ruling could stay the rule nationwide."
    cite:
      - "1 · Dkt. 24-1188 · docket"
      - "2 · Order list · May 28"

  - id: meeting-brief
    n: "03"
    title: The 2pm brief
    ask: "What should I know before my 2pm?"
    steps:
      - calendar(event=next) -> Northwind renewal · 14:00
      - email(counterparty=Northwind · last 30 days) -> 11 messages · $240k ask
      - search(q="Northwind" · all sources) -> 1 regulatory hit
    answer: "Renewal at $240k; they pushed for net-60 terms. A procurement rule published Tuesday names the parent company — lock multi-year terms before it applies."
    cite:
      - "1 · Northwind thread · May 9"
      - "2 · Federal Register · published Tuesday"

  - id: thesis-watch
    n: "04"
    title: Thesis watch
    ask: "Flag anything that changes my thesis on Acme."
    steps:
      - watch(entity="Acme" · sources=all · notify=material) -> standing
      - events(filter.entity_id=acme · since last review) -> 1 material diff
    answer: "Thesis factor at risk: government revenue. Contract-freeze notice published today."
    cite:
      - "1 · Federal Register · 90 FR 44102 · 06:00 ET"

  - id: vendor-risk
    n: "05"
    title: Vendor risk
    ask: "Which vendors on my list have SEC, NVD/KEV, or Federal Register risk flags?"
    steps:
      - vendor_risk_screen(csv=<vendor list>) -> GLEIF LEI + SEC CIK match per row
      - flags(SEC · NVD/KEV · Federal Register · public corpus) -> cited hits per vendor
      - audit(vendor_risk.screen) -> run_id + vendor count (FEC donor data excluded)
    answer: "Three vendors on your list have material public-record flags; each hit cites its source event."
    cite:
      - "1 · SEC EDGAR · 8-K filing"
      - "2 · CISA KEV · CVE-2024-1234"