@yottagraph-app/aether-instructions 1.1.33 → 1.1.35

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@yottagraph-app/aether-instructions",
-    "version": "1.1.33",
+    "version": "1.1.35",
     "description": "Cursor rules, commands, and skills for Aether development",
     "files": [
         "rules",

package/rules/agents-data.mdc

@@ -80,10 +80,69 @@ etc.) handle entity resolution, NEID formatting, and schema lookups
 automatically. Use the `data-model` skill docs for entity types,
 properties, and relationship schemas.
 
-Wire MCP into ADK agents by declaring an `McpToolset` that points to the
-Elemental MCP server. The MCP server URL and auth are configured in the
-agent's runtime environment (typically via `broadchurch.yaml` gateway
-proxy). See the Aether `agents` rule for ADK agent structure.
+### Wiring McpToolset (transport class)
+
+The Elemental MCP server uses **Streamable HTTP** transport. Use
+`StreamableHTTPConnectionParams` — **NOT** `SseConnectionParams`. The
+`SseConnectionParams` class is for older SSE-based MCP servers and will
+silently fail against the Elemental server (the agent starts with zero
+tools and the LLM hallucinates code).
+
+```python
+from google.adk.tools.mcp_tool import McpToolset
+from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
+
+McpToolset(
+    connection_params=StreamableHTTPConnectionParams(url=mcp_url)
+)
+```
+
+Resolve the MCP URL from the environment or `broadchurch.yaml`:
+
+```python
+import os
+from pathlib import Path
+import yaml
+
+def _get_mcp_url(server_name: str = "elemental") -> str:
+    """Resolve MCP server URL from env or broadchurch.yaml."""
+    env_url = os.environ.get("ELEMENTAL_MCP_URL")
+    if env_url:
+        return env_url
+    for candidate in [Path("broadchurch.yaml"), Path(__file__).parent / "broadchurch.yaml"]:
+        if candidate.exists():
+            config = yaml.safe_load(candidate.read_text()) or {}
+            gw = config.get("gateway", {})
+            org_id = config.get("tenant", {}).get("org_id", "")
+            if gw.get("url") and org_id:
+                return f"{gw['url'].rstrip('/')}/api/mcp/{org_id}/{server_name}/mcp"
+            return config.get("mcp", {}).get(server_name, "")
+    return ""
+```
+
+For **local dev**, set the env var:
+```bash
+export ELEMENTAL_MCP_URL="https://mcp.news.prod.g.lovelace.ai/elemental/mcp"
+```
+
+In **production**, the agent reads the gateway URL and org_id from
+`broadchurch.yaml` and routes through the Portal MCP proxy, which handles
+authentication automatically.
+
+### Silent failure warning
+
+If `McpToolset` cannot connect (wrong transport class, bad URL, or server
+down), **the agent starts with zero MCP tools and no error is raised**.
+The LLM will then hallucinate tool calls instead of executing real ones.
+Always validate the MCP URL at agent startup:
+
+```python
+mcp_url = _get_mcp_url()
+if not mcp_url:
+    raise RuntimeError("No MCP URL — check broadchurch.yaml or ELEMENTAL_MCP_URL env var")
+```
+
+### MCP response patterns
 
 **Read the `elemental-mcp-patterns` skill** (`skills/elemental-mcp-patterns/`)
 before writing tool code. It covers MCP response shapes, property type

package/rules/agents.mdc

@@ -48,7 +48,11 @@ Key rules:
 - Pin dependency versions in `requirements.txt` for reproducible deployments
 
 For agents that call the **Elemental API** (`broadchurch_auth`, endpoints,
-local `ELEMENTAL_*` env vars), see the `agents-data` rule.
+local `ELEMENTAL_*` env vars), see the `agents-data` rule. For agents
+using **Elemental MCP tools**, the `agents-data` rule also covers
+`McpToolset` wiring — use `StreamableHTTPConnectionParams` (not
+`SseConnectionParams`) and read the `elemental-mcp-patterns` skill for
+response handling patterns.
 
 ## Local Testing
 

package/skills/data-model/edgar/DATA_DICTIONARY.md

@@ -52,7 +52,32 @@ Each SEC form type is a separate flavor, namespaced under `sec`. All share the s
 | `sec::13f_hr` | 13F-HR | Institutional investment manager holdings |
 | `sec::def_14a` | DEF 14A | Definitive proxy statement |
 
-Sub-records (8-K events, Form 4 transactions, Form 3 holdings) use their parent filing's flavor.
+### Sub-Records (8-K Events, Form 4 Transactions, Form 3 Holdings)
+
+Sub-records are **separate graph entities**, not nested properties on the parent filing. Each sub-record has its own NEID and can be queried independently. They use the same flavor as their parent filing (e.g., `sec::8_k` for 8-K events, `sec::form_4` for Form 4 transactions).
+
+**Entity naming pattern:**
+- 8-K events: `{accession_number}_evt_{n}` (e.g., `0000320193-24-000067_evt_1`)
+- Form 4 transactions: `{accession_number}_trx_{n}` (e.g., `0000320193-24-000067_trx_1`)
+- Form 3 holdings: `{accession_number}_holding_{n}`
+
+**Relationships on sub-records:**
+- `filed` — points to the parent filing's accession number
+- `issued_by` — points to the company
+
+**Critical querying note:** Properties like `form_8k_event`, `form_8k_item_code`, `transaction_type`, `shares_transacted`, and other sub-record-specific properties do NOT appear on the parent filing entity or the organization entity. You must traverse the graph to the sub-record entities to access them.
+
+**Traversal path:**
+```
+organization --[filed]--> 8-K filing --[linked, distance 1]--> event sub-records
+```
+
+**Example: Finding 8-K event sub-records for a company:**
+1. Get filing NEIDs from the organization's `filed` property
+2. Filter to 8-K filings by checking `form_type == "8-K"`
+3. For each 8-K filing, use a `linked` expression (distance 1, direction both) to find connected entities
+4. Exclude the organization and the filing itself from results — the remaining entities are the event sub-records
+5. Query those sub-record NEIDs for `form_8k_event` and `form_8k_item_code`
 
 ### `person`
 
@@ -161,12 +186,34 @@ The six core financial properties appear on both the **organization** and its **
 
 #### 8-K Corporate Events (source: `edgar_8k`)
 
-Data source: 8-K current report filings. Properties on document sub-records.
+Data source: 8-K current report filings.
+
+> **Important:** These properties are on **event sub-record entities**, not on the parent 8-K filing or the organization. See the [Sub-Records section](#sub-records-8-k-events-form-4-transactions-form-3-holdings) above for how to find them.
 
+**Core event properties:**
 * `form_8k_event` — Snake_case event identifier. Examples: `"material_agreement"`, `"officer_director_change"`
 * `form_8k_item_code` — Raw SEC item number. Examples: `"1.01"`, `"5.02"`
+* `event_severity` — Event importance classification. Values: `"critical"`, `"high"`, `"medium"`, `"low"`
 * `category` — Sub-classification of Item 8.01 Other Events. Examples: `"cybersecurity_incident"`
 
+**Sub-record identity and relationships:**
+* `accession_number` — Synthetic sub-record identifier. Example: `"0000320193-24-000067_evt_1"`
+* `filed` — Relationship: event sub-record → parent 8-K filing
+* `issued_by` — Relationship: event sub-record → company
+
+**Item 8.01 keyword flags** (set to `"true"` when matched):
+* `8k_cybersecurity_keyword` — Cybersecurity-related disclosure detected
+* `8k_litigation_keyword` — Litigation-related disclosure detected
+* `8k_regulatory_keyword` — Regulatory-related disclosure detected
+* `8k_operational_keyword` — Operational issue disclosure detected
+
+**ABS event flags** (Items 6.01–6.05, set to `"true"` when applicable):
+* `abs_servicing_event` — Item 6.01: ABS servicing event
+* `abs_servicer_change` — Item 6.02: ABS servicer change
+* `abs_credit_enhancement_change` — Item 6.03: ABS credit enhancement change
+* `abs_failure_event` — Item 6.04: ABS failure to make distribution
+* `abs_securities_act` — Item 6.05: ABS Securities Act updating disclosure
+
 #### Beneficial Ownership (source: `edgar_sc_13d`, `edgar_sc_13g`)
 
 Data source: SC 13D/G XML filings. Properties on the filer organization.
@@ -240,8 +287,14 @@ Data source: Form 3/4 XML.
 
 #### Form 4 Transactions (source: `edgar_4`)
 
-Properties on document sub-records, one per transaction.
+> **Important:** These properties are on **transaction sub-record entities**, not on the parent Form 4 filing. See the [Sub-Records section](#sub-records-8-k-events-form-4-transactions-form-3-holdings) above for how to find them.
+
+**Sub-record identity and relationships:**
+* `accession_number` — Synthetic sub-record identifier. Example: `"0000320193-24-000067_trx_1"`
+* `filed` — Relationship: transaction sub-record → parent Form 4 filing
+* `issued_by` — Relationship: transaction sub-record → issuer company
 
+**Transaction properties:**
 * `transaction_type` — Human-readable code description. Examples: `"Open market or private purchase"`, `"Grant, award, or other acquisition"`
 * `transaction_date` — Transaction date (YYYY-MM-DD)
 * `acquired_disposed_code` — `"A"` (acquired) or `"D"` (disposed)
@@ -284,6 +337,8 @@ Data source: 13F-HR XML information table.
 
 ## Entity Relationships
 
+> **Sub-record traversal:** Sub-records (8-K events, Form 4 transactions, Form 3 holdings) are separate document entities. To find them, traverse from the parent filing using a `linked` expression (distance 1). The sub-record's `filed` property points back to the parent filing, and `issued_by` points to the company.
+
 ```
 organization         ──[filed]────────────────────→ document
 organization         ──[filing_reference]─────────→ document
@@ -296,7 +351,8 @@ document             ──[refers_to]──────────────
 document             ──[filer]────────────────────→ organization    (SC 13D/G)
 document             ──[group_member]─────────────→ organization    (SC 13D)
 document             ──[compares_to]──────────────→ organization    (DEF 14A)
-document             ──[filed]────────────────────→ document        (sub-record → parent)
+document (sub-record)──[filed]────────────────────→ document        (8-K event → parent 8-K filing)
+document (sub-record)──[issued_by]────────────────→ organization    (8-K event / Form 4 txn → company)
 person               ──[is_officer]───────────────→ organization
 person               ──[is_director]──────────────→ organization
 person               ──[is_ten_percent_owner]─────→ organization

package/skills/data-model/edgar/schema.yaml

@@ -126,6 +126,14 @@ flavors:
     strong_id_properties: ["accession_number"]
     passive: true
 
+  - name: "filing"
+    namespace: "sec"
+    description: "SEC filing (generic, for form types without a specific modeled flavor)"
+    display_name: "SEC Filing"
+    mergeability: not_mergeable
+    strong_id_properties: ["accession_number"]
+    passive: true
+
   - name: "person"
     description: "A real person as opposed to a fictional character, such as a CEO, politician, or public figure"
     display_name: "Person"
@@ -140,6 +148,13 @@ flavors:
     strong_id_properties: ["cusip_number"]
     passive: true
 
+  - name: "industry"
+    description: "A Standard Industrial Classification (SIC) industry category assigned by the SEC"
+    display_name: "Industry"
+    mergeability: not_mergeable
+    strong_id_properties: ["sic_code"]
+    passive: true
+
 # =============================================================================
 # PROPERTIES — Organization
 # =============================================================================
@@ -176,7 +191,7 @@ properties:
     description: "Four-digit Standard Industrial Classification code"
     display_name: "SIC Code"
     mergeability: not_mergeable
-    domain_flavors: ["organization"]
+    domain_flavors: ["organization", "industry"]
     passive: true
 
   - name: "sic_description"
@@ -184,7 +199,7 @@ properties:
     description: "Human-readable SIC code description"
     display_name: "SIC Description"
     mergeability: not_mergeable
-    domain_flavors: ["organization"]
+    domain_flavors: ["organization", "industry"]
     passive: true
 
   - name: "state_of_incorporation"
@@ -574,7 +589,7 @@ properties:
     description: "SEC accession number uniquely identifying a filing"
     display_name: "Accession Number"
     mergeability: not_mergeable
-    domain_flavors: ["sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a"]
+    domain_flavors: ["sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a", "sec::filing"]
     passive: true
 
   - name: "form_type"
@@ -582,7 +597,7 @@ properties:
     description: "Normalized SEC form type (e.g. 10-K, SC 13D, 4)"
     display_name: "Form Type"
     mergeability: not_mergeable
-    domain_flavors: ["sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a"]
+    domain_flavors: ["sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a", "sec::filing"]
     passive: true
 
   - name: "filing_date"
@@ -590,7 +605,7 @@ properties:
     description: "Date the filing was submitted to the SEC (YYYY-MM-DD)"
     display_name: "Filing Date"
     mergeability: not_mergeable
-    domain_flavors: ["sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a"]
+    domain_flavors: ["sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a", "sec::filing"]
     passive: true
 
   - name: "report_date"
@@ -598,7 +613,7 @@ properties:
     description: "End date of the primary reporting period (YYYY-MM-DD)"
     display_name: "Report Date"
     mergeability: not_mergeable
-    domain_flavors: ["sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a"]
+    domain_flavors: ["sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a", "sec::filing"]
     passive: true
 
   # ── XBRL Financial Facts (key concepts) ──
@@ -1717,11 +1732,19 @@ relationships:
   # ── Organization → Filing ──
 
   - name: "filed"
-    description: "Link from a company to an SEC filing document it filed, or from a sub-record (event, transaction, holding) to its parent filing"
+    description: "Link from a company or person to an SEC filing document they filed, or from a sub-record (event, transaction, holding) to its parent filing"
     display_name: "Filed"
     mergeability: not_mergeable
-    domain_flavors: ["organization", "sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a"]
-    target_flavors: ["sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a"]
+    domain_flavors: ["organization", "person", "sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a", "sec::filing"]
+    target_flavors: ["sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a", "sec::filing"]
+    passive: true
+
+  - name: "is_issuer_of"
+    description: "Link from an issuer organization to an ownership filing (Forms 3/4, SC 13D/G) where the CIK is the issuer, not the filer"
+    display_name: "Is Issuer Of"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    target_flavors: ["sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::filing"]
     passive: true
 
   - name: "filing_reference"
@@ -1735,10 +1758,10 @@ relationships:
   # ── Filing → Organization ──
 
   - name: "issued_by"
-    description: "Link from a filing to the company it pertains to (the filer for most forms; the issuer for ownership forms)"
+    description: "Link from a filing or financial instrument to the company it pertains to (the filer for most forms; the issuer for ownership forms and 13F holdings)"
     display_name: "Issued By"
     mergeability: not_mergeable
-    domain_flavors: ["sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a"]
+    domain_flavors: ["sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a", "sec::filing", "financial_instrument"]
     target_flavors: ["organization"]
     passive: true
 
@@ -1751,10 +1774,10 @@ relationships:
     passive: true
 
   - name: "filer"
-    description: "Link from a filing to the beneficial owner or manager who filed it"
+    description: "Link from a filing to the entity (person or organization) who filed it"
     display_name: "Filer"
     mergeability: not_mergeable
-    domain_flavors: ["sec::sc_13d", "sec::sc_13g", "sec::13f_hr"]
+    domain_flavors: ["sec::10_k", "sec::10_q", "sec::20_f", "sec::8_k", "sec::6_k", "sec::40_f", "sec::form_3", "sec::form_4", "sec::sc_13d", "sec::sc_13g", "sec::13f_hr", "sec::def_14a", "sec::filing"]
     target_flavors: ["organization", "person"]
     passive: true
 
@@ -1803,10 +1826,10 @@ relationships:
   # ── Organization → Financial Instrument ──
 
   - name: "holds_position"
-    description: "Link from an investment manager to a security it holds (13F-HR)"
+    description: "Link from an investment manager or fund to a security it holds (13F-HR, N-PORT)"
     display_name: "Holds Position"
     mergeability: not_mergeable
-    domain_flavors: ["organization"]
+    domain_flavors: ["organization", "financial_instrument"]
     target_flavors: ["financial_instrument"]
     passive: true
 
@@ -1844,6 +1867,16 @@ relationships:
     target_flavors: ["organization"]
     passive: true
 
+  # ── Organization → Financial Instrument (issuer link) ──
+
+  - name: "issues_security"
+    description: "Link from an issuing company to a financial instrument it has issued, identified by CUSIP (SC 13D/G)"
+    display_name: "Issues Security"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    target_flavors: ["financial_instrument"]
+    passive: true
+
 # =============================================================================
 # ATTRIBUTES
 # =============================================================================
@@ -1891,3 +1924,61 @@ attributes:
     description: "Fiscal period: FY (annual), Q1, Q2, Q3 (quarterly)"
     display_name: "Filing Period"
     mergeability: not_mergeable
+
+  # ── holds_position relationship attributes (13F-HR) ──
+
+  - property: "holds_position"
+    name: "position_value"
+    type: string
+    description: "Market value of the position in thousands of USD"
+    display_name: "Position Value"
+    mergeability: not_mergeable
+
+  - property: "holds_position"
+    name: "shares_held"
+    type: string
+    description: "Number of shares or principal amount held"
+    display_name: "Shares Held"
+    mergeability: not_mergeable
+
+  - property: "holds_position"
+    name: "instrument_type"
+    type: string
+    description: "Type of instrument: SH (shares) or PRN (principal amount)"
+    display_name: "Instrument Type"
+    mergeability: not_mergeable
+
+  - property: "holds_position"
+    name: "put_call"
+    type: string
+    description: "Option type if applicable: PUT or CALL"
+    display_name: "Put/Call"
+    mergeability: not_mergeable
+
+  - property: "holds_position"
+    name: "investment_discretion"
+    type: string
+    description: "Investment discretion: SOLE, SHARED, or DEFINED"
+    display_name: "Investment Discretion"
+    mergeability: not_mergeable
+
+  - property: "holds_position"
+    name: "voting_authority_sole"
+    type: string
+    description: "Shares with sole voting authority"
+    display_name: "Voting Authority (Sole)"
+    mergeability: not_mergeable
+
+  - property: "holds_position"
+    name: "voting_authority_shared"
+    type: string
+    description: "Shares with shared voting authority"
+    display_name: "Voting Authority (Shared)"
+    mergeability: not_mergeable
+
+  - property: "holds_position"
+    name: "voting_authority_none"
+    type: string
+    description: "Shares with no voting authority"
+    display_name: "Voting Authority (None)"
+    mergeability: not_mergeable

package/skills/data-model/fred/DATA_DICTIONARY.md

@@ -48,7 +48,7 @@ A traded security, index, or reference rate for which FRED publishes price or yi
 - Primary key: entity name (e.g. "10-Year U.S. Treasury", "S&P 500"). No strong ID — resolved by name with MERGEABLE mergeability.
 - Entity resolver: named entity, MERGEABLE. Disambiguation snippet includes series title, frequency, and units.
 - Source: `fred-source`
-- Entities produced: U.S. Treasuries (1Y, 2Y, 10Y, 30Y, 3M bill), SOFR, SONIA, S&P 500, NASDAQ Composite, CBOE VIX, ICE BofA High Yield Index, FX pairs (JPY/USD, KRW/USD, USD/EUR, USD/GBP, CAD/USD, CNY/USD), U.S. Dollar Index, U.S. Dollar Advanced Economy Index
+- Entities produced: U.S. Treasuries (1Y, 2Y, 10Y, 30Y, 3M bill), SOFR, SONIA, NASDAQ Composite, CBOE VIX, FX pairs (JPY/USD, KRW/USD, USD/EUR, USD/GBP, CAD/USD, CNY/USD), U.S. Dollar Index, U.S. Dollar Advanced Economy Index
 
 ### `product`
 
@@ -77,7 +77,7 @@ These atoms appear once per series record, timestamped at the first observation
 * `fred_series_id`
   * Definition: FRED's unique alphanumeric identifier for the series.
   * Source flavor: location, organization, financial_instrument, product
-  * Examples: `"GDP"`, `"UNRATE"`, `"DGS10"`, `"SP500"`
+  * Examples: `"GDP"`, `"UNRATE"`, `"DGS10"`
   * Derivation: `id` field from the FRED `/series` API response.
 
 * `notes`
@@ -198,7 +198,6 @@ Each observation in a series becomes one atom timestamped at the observation dat
 * `bank_lending_standards` — Net % of banks tightening C&I loan standards for large firms (Percent, quarterly). Series: DRTSCILM.
 * `bank_lending_standards_small` — Net % of banks tightening C&I loan standards for small firms (Percent, quarterly). Series: DRTSCLNM. **Note: FRED reports this series as discontinued/nonexistent as of 2026-03.**
 * `bank_lending_standards_cre` — Net % of banks tightening CRE lending standards (Percent, quarterly). Series: DRTSRCL. **Note: FRED reports this series as discontinued/nonexistent as of 2026-03.**
-* `baa_10y_spread` — Moody's Baa corporate bond yield minus 10Y Treasury (Percent, daily). Series: BAA10Y.
 * `credit_card_delinquency_rate` — Delinquency rate on credit card loans, all commercial banks (Percent, quarterly). Series: DRCCLACBS.
 * `cre_delinquency_rate` — Delinquency rate on CRE loans excluding farmland (Percent, quarterly). Series: DRCRELEXFACBS.
 
@@ -215,8 +214,6 @@ Each observation in a series becomes one atom timestamped at the observation dat
 * `building_permits` — New privately-owned housing units authorized, SAAR (Thousands of Units, monthly). Series: PERMIT.
 * `housing_months_supply` — Monthly supply of new houses, seasonally adjusted (Months' Supply, monthly). Series: MSACSR.
 * `home_price_median` — Median sales price of houses sold (Dollars, quarterly). Series: MSPUS.
-* `home_price_index` — S&P CoreLogic Case-Shiller U.S. National Home Price Index (Index Jan 2000=100, monthly). Series: CSUSHPINSA.
-* `home_price_index_20city` — S&P CoreLogic Case-Shiller 20-City Composite Home Price Index (Index Jan 2000=100, monthly). Series: SPCS20RSA.
 * `home_price_index_fhfa` — FHFA all-transactions house price index (Index 1980:Q1=100, quarterly). Series: USSTHPI.
 * `mortgage_rate_30y` — 30-year fixed rate mortgage average (Percent, weekly). Series: MORTGAGE30US.
 * `rental_vacancy_rate` — Rental housing vacancy rate (Percent, quarterly). Series: RRVRUSQ156N.
@@ -286,8 +283,7 @@ Each observation in a series becomes one atom timestamped at the observation dat
 #### Financial Markets (financial_instrument)
 
 * `yield` — Market yield or interest rate for a fixed-income instrument (Percent). Series: DGS1, DGS2, DGS10, DGS30, DTB3, TB3MS, SOFR, IUDSOIA.
-* `price` — Market price, index level, or exchange rate (varies by instrument). Series: SP500, NASDAQCOM, VIXCLS, DTWEXBGS, TWEXAFEGSMTH, DEXUSEU, DEXUSUK, DEXJPUS, DEXKOUS, EXCAUS, DEXCHUS.
-* `option_adjusted_spread` — Option-adjusted spread for a bond index (Percent, daily). Series: BAMLH0A0HYM2.
+* `price` — Market price, index level, or exchange rate (varies by instrument). Series: NASDAQCOM, VIXCLS, DTWEXBGS, TWEXAFEGSMTH, DEXUSEU, DEXUSUK, DEXJPUS, DEXKOUS, EXCAUS, DEXCHUS.
 
 #### Commodity Prices (product)
 
@@ -308,6 +304,6 @@ The FRED source produces no `data_nindex` relationship properties. All atoms are
 ```
 location            ── [fed_funds_rate, gdp, unemployment_rate, cpi, ...] (scalar observation properties)
 organization        ── [fed_funds_rate, policy_rate, monetary_base, ...]
-financial_instrument ── [yield, price, option_adjusted_spread]
+financial_instrument ── [yield, price]
 product             ── [price]
 ```

package/skills/data-model/fred/schema.yaml

@@ -77,7 +77,7 @@ properties:
     display_name: "FRED Series ID"
     mergeability: not_mergeable
     domain_flavors: ["fred_series"]
-    examples: ["GDP", "UNRATE", "DGS10", "SP500"]
+    examples: ["GDP", "UNRATE", "DGS10"]
     passive: true
 
   - name: "name"
@@ -86,7 +86,7 @@ properties:
     display_name: "Name"
     mergeability: not_mergeable
     domain_flavors: ["fred_series"]
-    examples: ["Gross Domestic Product", "Federal Funds Effective Rate", "S&P 500"]
+    examples: ["Gross Domestic Product", "Federal Funds Effective Rate"]
     passive: true
 
   - name: "notes"

package/skills/data-model/industries/schema.yaml

@@ -0,0 +1,64 @@
+# Dataset schema for SIC industry classifications derived from SEC EDGAR filings.
+#
+# This schema introduces the `industry` flavor — a Standard Industrial
+# Classification (SIC) category identified by its 4-digit code. Organizations
+# are linked to their industry via the `works_in_industry` relationship.
+#
+# All elements are passive (deterministic extraction from filing headers).
+name: "industries"
+description: "SIC industry classifications linking SEC-registered organizations to their Standard Industrial Classification codes"
+
+extraction:
+  flavors: closed
+  properties: closed
+  relationships: closed
+  attributes: closed
+
+flavors:
+  - name: "industry"
+    description: "A Standard Industrial Classification (SIC) industry category assigned by the SEC"
+    display_name: "Industry"
+    mergeability: not_mergeable
+    strong_id_properties: ["sic_code"]
+    passive: true
+
+  - name: "organization"
+    description: "A particular business, institution, or organization such as a corporation, university, government agency, or non-profit"
+    display_name: "Organization"
+    mergeability: not_mergeable
+    strong_id_properties: ["company_cik"]
+    passive: true
+
+properties:
+  - name: "sic_code"
+    type: string
+    description: "Four-digit Standard Industrial Classification code"
+    display_name: "SIC Code"
+    mergeability: not_mergeable
+    domain_flavors: ["industry", "organization"]
+    passive: true
+
+  - name: "sic_description"
+    type: string
+    description: "Human-readable SIC code description"
+    display_name: "SIC Description"
+    mergeability: not_mergeable
+    domain_flavors: ["industry", "organization"]
+    passive: true
+
+  - name: "company_cik"
+    type: string
+    description: "SEC Central Index Key, 10-digit zero-padded"
+    display_name: "CIK"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    passive: true
+
+relationships:
+  - name: "works_in_industry"
+    description: "Link from an organization to its SIC industry classification"
+    display_name: "Works In Industry"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    target_flavors: ["industry"]
+    passive: true

package/skills/elemental-mcp-patterns/SKILL.md

@@ -0,0 +1,621 @@
+---
+name: elemental-mcp-patterns
+description: How to correctly call Elemental MCP tools and process their responses when writing Python ADK agent tool functions.
+---
+
+# Elemental MCP Patterns
+
+This skill is for **build agents writing Python tool code** that calls
+Elemental MCP tools. It covers MCP wiring, transport configuration,
+response shapes, property type handling, and copy-paste patterns for
+common operations.
+
+For domain knowledge (what entity types and properties exist), see the
+**data-model** skill.
+
+---
+
+## MCP Wiring: Connecting ADK Agents to Elemental MCP
+
+### Transport class
+
+The Elemental MCP server uses **Streamable HTTP** transport. You **must**
+use `StreamableHTTPConnectionParams`:
+
+```python
+from google.adk.tools.mcp_tool import McpToolset
+from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
+```
+
+> **Do NOT use `SseConnectionParams`.**  `SseConnectionParams` is for
+> legacy SSE-based MCP servers. Using it against the Elemental MCP server
+> will silently fail — the agent starts with zero tools and no error is
+> raised. The LLM then hallucinates tool calls.
+
+### Resolving the MCP URL
+
+The MCP URL comes from the environment (`ELEMENTAL_MCP_URL`) for local
+dev, or from `broadchurch.yaml` for deployed agents:
+
+```python
+import os
+from pathlib import Path
+import yaml
+
+def _get_mcp_url(server_name: str = "elemental") -> str:
+    """Resolve MCP server URL from env or broadchurch.yaml."""
+    env_url = os.environ.get("ELEMENTAL_MCP_URL")
+    if env_url:
+        return env_url
+    for candidate in [Path("broadchurch.yaml"), Path(__file__).parent / "broadchurch.yaml"]:
+        if candidate.exists():
+            config = yaml.safe_load(candidate.read_text()) or {}
+            gw = config.get("gateway", {})
+            org_id = config.get("tenant", {}).get("org_id", "")
+            if gw.get("url") and org_id:
+                return f"{gw['url'].rstrip('/')}/api/mcp/{org_id}/{server_name}/mcp"
+            return config.get("mcp", {}).get(server_name, "")
+    return ""
+```
+
+### Complete wiring example
+
+```python
+from google.adk.agents import Agent
+from google.adk.tools.mcp_tool import McpToolset
+from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
+
+mcp_url = _get_mcp_url()  # function from above
+if not mcp_url:
+    raise RuntimeError("No MCP URL — check broadchurch.yaml or ELEMENTAL_MCP_URL env var")
+
+root_agent = Agent(
+    model="gemini-2.0-flash",
+    name="my_mcp_agent",
+    instruction="You are a research assistant with access to the Lovelace knowledge graph.",
+    tools=[
+        my_custom_tool,  # your Python tool functions
+        McpToolset(connection_params=StreamableHTTPConnectionParams(url=mcp_url)),
+    ],
+)
+```
+
+The `McpToolset` automatically discovers all MCP tools at startup and
+exposes them to the agent. To restrict which tools are exposed, use
+`tool_filter`:
+
+```python
+McpToolset(
+    connection_params=StreamableHTTPConnectionParams(url=mcp_url),
+    tool_filter=["elemental_get_entity", "elemental_get_related", "elemental_get_events"],
+)
+```
+
+### Silent failure mode
+
+If `McpToolset` cannot connect, **no error is raised at agent startup**.
+The agent simply has zero MCP tools. Symptoms:
+- The agent never calls any `elemental_*` tools
+- The LLM fabricates code or data instead of using tools
+- No connection error in logs
+
+**Always validate** the MCP URL and check for tool availability during
+development. If MCP tools aren't working, verify:
+1. The URL is correct (check `broadchurch.yaml` `mcp.elemental` or env var)
+2. You're using `StreamableHTTPConnectionParams` (not `SseConnectionParams`)
+3. The MCP server is reachable (try `curl -X POST <url> -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'`)
+
+### Local dev setup
+
+```bash
+export ELEMENTAL_MCP_URL="https://mcp.news.prod.g.lovelace.ai/elemental/mcp"
+export GOOGLE_CLOUD_PROJECT=broadchurch
+export GOOGLE_CLOUD_LOCATION=us-central1
+export GOOGLE_GENAI_USE_VERTEXAI=1
+cd agents/
+adk web
+```
+
+---
+
+## Tool Quick Reference
+
+| Tool | Use when you need to... |
+|---|---|
+| `elemental_get_entity` | Resolve an entity by name or ID, fetch its properties (supports `history` for time-series) |
+| `elemental_get_related` | Find related entities (requires `related_flavor`); use `direction` and `relationship_types` to filter |
+| `elemental_get_events` | Get typed events with categories, dates, participants |
+| `elemental_get_citations` | Look up provenance for `ref` hashes returned by other tools |
+| `elemental_get_schema` | Discover flavors (entity types), property names, and property types |
+| `elemental_get_relationships` | Get relationship types and counts between two entities |
+| `elemental_graph_neighborhood` | Get the most influential neighbors of an entity |
+| `elemental_graph_sentiment` | Sentiment time series, trend analysis, and statistics from news articles |
+| `elemental_introspect` | Discover what data **actually exists**: entity counts, populated properties with fill rates, sample values. Use before building features to verify data availability. |
+| `elemental_traverse` | Stateful graph navigation — build a working set of entities across multiple calls (start → expand → filter → inspect) |
+| `elemental_health` | Health check — verify MCP server connectivity |
+
+### MCP Prompts
+
+The server also exposes built-in prompts that provide pre-composed
+workflows:
+
+| Prompt | Purpose |
+|---|---|
+| `company-deep-dive` | Comprehensive company research workflow |
+| `blast-radius` | Analyze impact/connections radiating from an entity |
+| `event-monitor` | Track events and developments for entities |
+
+### MCP Resources
+
+Documentation resources are available directly from the server:
+
+| Resource | Description |
+|---|---|
+| `elemental_data_model` | Entity types, properties, and relationships |
+| `elemental_guide` | Usage guide for the MCP tools |
+| `elemental_schema` | Live schema data |
+| `elemental_workflows` | Common workflow patterns and examples |
+| `elemental_mcp_server_info` | Server capabilities and configuration |
+
+These prompts and resources can be useful shortcuts — check if your MCP
+client supports them before building equivalent logic from scratch.
+
+---
+
+## Response Shapes
+
+Every MCP tool call returns a JSON dict. Below are annotated examples of
+the three tools you'll use most.
+
+### elemental_get_entity
+
+```python
+result = await mcp_call("elemental_get_entity", {
+    "entity": "Intel",
+    "properties": ["country", "total_revenue", "ticker_symbol", "net_income"]
+})
+
+# Response shape:
+{
+    "entity": {
+        "neid": "04926132345040704022",
+        "name": "Intel Corporation",
+        "flavor": "organization",
+        "properties": {
+            "country": {
+                "value": "5816460566439750832",  # <-- THIS IS A NEID, NOT A NAME
+                "ref": "ref_a3f2b1c8"
+            },
+            "total_revenue": {
+                "value": 52900000000,
+                "ref": "ref_d4e5f678",
+                "attributes": {"filing_period": "FY"}
+            },
+            "ticker_symbol": {
+                "value": "INTC"
+            },
+            "net_income": {
+                "value": -267000000,
+                "ref": "ref_b2c3d4e5"
+            }
+        }
+    }
+}
+```
+
+Key points:
+- `entity` is `null` if resolution failed
+- Each property value is `{"value": ..., "ref"?: "...", "attributes"?: {...}}`
+- **`value` can be a NEID** for reference-typed properties — see
+  "The Property Type Problem" below
+- `ref` is a citation hash — pass it through to the LLM exactly as-is
+- `low_confidence` means the entity match is fuzzy — confirm with the user
+
+### elemental_get_related
+
+```python
+result = await mcp_call("elemental_get_related", {
+    "entity": "Intel",
+    "related_flavor": "person",                    # REQUIRED
+    "relationship_types": ["board_member_of"],      # optional filter
+    "related_properties": ["nationality", "title"], # properties on each person
+    "limit": 20
+})
+
+# Response shape:
+{
+    "resolved": {
+        "neid": "04926132345040704022",
+        "name": "Intel Corporation",
+        "flavor": "organization"
+    },
+    "total": 12,
+    "relationships": [
+        {
+            "neid": "08371625409283746152",
+            "name": "Patrick Gelsinger",
+            "flavor": "person",
+            "relationship_types": ["board_member_of"],
+            "properties": {
+                "nationality": {"value": "United States"},
+                "title": {"value": "CEO"}
+            }
+        }
+        # ... more related entities
+    ]
+}
+```
+
+Key points:
+- `related_flavor` is **required** — you must specify what type of entity
+  to look for
+- `resolved` is the center entity (can be `null` if resolution failed)
+- Each item in `relationships` has the same property value shape as
+  `elemental_get_entity`
+- Use `direction` (`"outgoing"`, `"incoming"`, `"both"`) to control
+  traversal direction
+
+### elemental_get_events
+
+```python
+result = await mcp_call("elemental_get_events", {
+    "entity": "Intel",
+    "categories": ["Bankruptcy", "IPO", "Regulatory Action"],  # optional
+    "time_range": {"after": "2025-01-01"},                     # optional
+    "include_participants": True,                               # optional
+    "limit": 20
+})
+
+# Response shape:
+{
+    "resolved": {
+        "neid": "04926132345040704022",
+        "name": "Intel Corporation"
+    },
+    "total": 3,
+    "events": [
+        {
+            "neid": "09283746152837461528",
+            "name": "Intel CHIPS Act Award",
+            "flavor": "event",
+            "properties": {
+                "category": {"value": "Regulatory Action"},
+                "date": {"value": "2025-03-15"},
+                "description": {"value": "Intel awarded $8.5B in CHIPS Act funding"},
+                "likelihood": {"value": 0.95}
+            },
+            "participants": [
+                {
+                    "neid": "04926132345040704022",
+                    "name": "Intel Corporation",
+                    "flavor": "organization",
+                    "relationship_types": ["participant"]
+                }
+            ]
+        }
+    ]
+}
+```
+
+Key points:
+- Events have typed fields: `category`, `date`, `description`, `likelihood`
+- Use `categories` to filter — do NOT try to find events by scanning
+  property names for keywords
+- `participants` only included when `include_participants` is `True`
+
+---
+
+## The Property Type Problem
+
+This is the single biggest source of bugs in MCP-based agents.
+
+**The issue:** property values can be entity references (NEIDs), not
+display text. If you render them raw, the user sees `"5816460566439750832"`
+instead of `"United States"`.
+
+### Step 1: Get the schema to learn property types
+
+```python
+schema = await mcp_call("elemental_get_schema", {"flavor": "organization"})
+
+# Response includes a properties array:
+# [
+#   {"name": "country",       "type": "nindex", ...},  <-- entity reference!
+#   {"name": "total_revenue", "type": "float",  ...},
+#   {"name": "ticker_symbol", "type": "string", ...},
+#   {"name": "industry",      "type": "nindex", ...},  <-- entity reference!
+# ]
+```
+
+### Step 2: Build a type map (once per session)
+
+```python
+def build_property_type_map(schema_result: dict) -> dict[str, str]:
+    """Map property names to their types from schema."""
+    type_map = {}
+    for prop in schema_result.get("properties", []):
+        type_map[prop["name"]] = prop["type"]
+    return type_map
+
+# Cache this — don't re-fetch schema for every tool call
+property_types = build_property_type_map(schema)
+# {"country": "nindex", "total_revenue": "float", "ticker_symbol": "string", ...}
+```
+
+### Step 3: Resolve reference values before display
+
+```python
+async def format_properties(
+    properties: dict,
+    property_types: dict[str, str],
+    mcp_call,
+) -> dict[str, str]:
+    """Format property values for user-facing display."""
+    formatted = {}
+    for name, prop in properties.items():
+        value = prop["value"]
+        prop_type = property_types.get(name, "string")
+
+        if prop_type == "nindex" and isinstance(value, (str, int)):
+            # This is an entity reference — resolve to display name
+            resolved = await mcp_call("elemental_get_entity", {
+                "entity_id": {"id": str(value), "id_type": "neid"}
+            })
+            entity = resolved.get("entity")
+            formatted[name] = entity["name"] if entity else str(value)
+        elif isinstance(value, (int, float)) and abs(value) >= 1_000_000:
+            formatted[name] = _format_large_number(value)
+        else:
+            formatted[name] = str(value)
+    return formatted
+
+def _format_large_number(n: float) -> str:
+    """Format large numbers: 52900000000 -> '$52.9B'."""
+    abs_n = abs(n)
+    if abs_n >= 1e12:
+        return f"${n/1e12:.1f}T"
+    if abs_n >= 1e9:
+        return f"${n/1e9:.1f}B"
+    if abs_n >= 1e6:
+        return f"${n/1e6:.1f}M"
+    return f"${n:,.0f}"
+```
+
+### Property type values you'll encounter
+
+| Schema type | Value is | How to display |
+|---|---|---|
+| `string` | Plain text | Display directly |
+| `integer`, `float` | Number | Format with units (check `unit` in schema) |
+| `nindex` | Entity NEID | **Must resolve** via `elemental_get_entity` |
+| `boolean` | `true`/`false` | Display as Yes/No |
+| `datetime` | ISO 8601 string | Format as human-readable date |
+
+---
+
+## Common Patterns
+
+### Resolve and cache an entity
+
+```python
+async def resolve_entity(
+    name: str,
+    session_state: dict,
+    mcp_call,
+    neid: str | None = None,
+) -> dict | None:
+    """Resolve entity, using cache if available."""
+    cache = session_state.setdefault("entities", {})
+
+    # Check cache by NEID or name
+    cache_key = neid or name.lower()
+    if cache_key in cache:
+        return cache[cache_key]
+
+    params = {}
+    if neid:
+        params["entity_id"] = {"id": neid, "id_type": "neid"}
+    else:
+        params["entity"] = name
+
+    result = await mcp_call("elemental_get_entity", params)
+    entity = result.get("entity")
+    if not entity:
+        return None
+
+    # Cache by both NEID and lowercase name
+    cache[entity["neid"]] = entity
+    cache[entity["name"].lower()] = entity
+    return entity
+```
+
+### Build a rich entity briefing
+
+Don't return a one-paragraph summary. Chain multiple calls to build a
+comprehensive report:
+
+```python
+async def entity_briefing(name: str, mcp_call, session_state: dict) -> str:
+    """Build a comprehensive entity briefing."""
+    # 1. Resolve + properties
+    entity = await mcp_call("elemental_get_entity", {
+        "entity": name,
+        "properties": [
+            "country", "ticker_symbol", "total_revenue", "net_income",
+            "total_assets", "industry", "lei", "company_cik"
+        ]
+    })
+    if not entity.get("entity"):
+        return f"Could not resolve entity: {name}"
+
+    e = entity["entity"]
+    neid = e["neid"]
+    report_parts = [f"# {e['name']}", f"Type: {e.get('flavor', 'unknown')}"]
+
+    # 2. Format properties (handling nindex resolution)
+    if e.get("properties"):
+        schema = await mcp_call("elemental_get_schema", {"flavor": e.get("flavor", "")})
+        ptypes = build_property_type_map(schema)
+        props = await format_properties(e["properties"], ptypes, mcp_call)
+        for k, v in props.items():
+            report_parts.append(f"- {k}: {v}")
+
+    # 3. Key relationships
+    for related_flavor, label in [("person", "Key People"), ("organization", "Related Orgs")]:
+        related = await mcp_call("elemental_get_related", {
+            "entity_id": {"id": neid, "id_type": "neid"},
+            "related_flavor": related_flavor,
+            "limit": 10
+        })
+        if related.get("relationships"):
+            report_parts.append(f"\n## {label}")
+            for r in related["relationships"]:
+                types = ", ".join(r.get("relationship_types", []))
+                report_parts.append(f"- {r['name']} ({types})")
+
+    # 4. Recent events
+    events = await mcp_call("elemental_get_events", {
+        "entity_id": {"id": neid, "id_type": "neid"},
+        "limit": 10
+    })
+    if events.get("events"):
+        report_parts.append("\n## Recent Events")
+        for ev in events["events"]:
+            props = ev.get("properties", {})
+            date = props.get("date", {}).get("value", "")
+            cat = props.get("category", {}).get("value", "")
+            desc = props.get("description", {}).get("value", ev["name"])
+            report_parts.append(f"- [{date}] {cat}: {desc}")
+
+    return "\n".join(report_parts)
+```
+
+### Fetch events correctly
+
+Always use `elemental_get_events`. Never try to find events by scanning
+property names or PID names for keywords like "event" or "filing".
+
+```python
+# CORRECT — use the dedicated events tool
+events = await mcp_call("elemental_get_events", {
+    "entity": "Intel",
+    "categories": ["Regulatory Action", "Acquisition"],
+    "time_range": {"after": "2025-01-01"},
+    "include_participants": True
+})
+
+# WRONG — do NOT scan properties/PIDs for event-like names
+# This matches "filed" (a document relationship), not actual events
+schema = await mcp_call("elemental_get_schema", {"flavor": "organization"})
+event_pids = [p for p in schema["properties"] if "event" in p["name"]]  # BAD
+```
+
+### Fetch related entities with properties
+
+```python
+# Get board members with their titles and nationalities
+board = await mcp_call("elemental_get_related", {
+    "entity": "JPMorgan Chase",
+    "related_flavor": "person",
+    "relationship_types": ["board_member_of", "is_officer"],
+    "related_properties": ["title", "nationality"],
+    "limit": 30
+})
+
+for person in board.get("relationships", []):
+    name = person["name"]
+    title = person.get("properties", {}).get("title", {}).get("value", "")
+    print(f"{name} — {title}")
+```
+
+---
+
+## Common Properties & Relationships Quick Reference
+
+Use `elemental_introspect` to discover what's actually populated for a
+given flavor. Use `elemental_get_schema` for the full property list. The
+tables below are a starting-point cheat sheet — not exhaustive.
+
+### Properties by flavor
+
+| Flavor | Common properties |
+|---|---|
+| `organization` | `country` (nindex), `ticker_symbol`, `total_revenue`, `net_income`, `total_assets`, `industry` (nindex), `lei`, `company_cik`, `ein`, `website` |
+| `person` | `nationality` (nindex), `title`, `birth_date`, `gender` |
+| `government_body` | `country` (nindex), `jurisdiction` |
+| `article` | `headline`, `published_date`, `source`, `url` |
+| `event` | `category`, `date`, `description`, `likelihood` |
+| `financial_instrument` | `ticker_symbol`, `exchange`, `currency` |
+
+Properties marked `(nindex)` are entity references — their raw value is
+a NEID that must be resolved to a display name. See "The Property Type
+Problem" above.
+
+### Relationship types and direction
+
+The `direction` parameter on `elemental_get_related` controls traversal.
+Getting it wrong returns zero results with no error.
+
+| Relationship | Meaning | Direction from center |
+|---|---|---|
+| `board_member_of` | Person sits on org's board | `"incoming"` when center is org |
+| `is_officer` | Person is an officer of org | `"incoming"` when center is org |
+| `subsidiary_of` | Org is a subsidiary of parent | `"outgoing"` from subsidiary |
+| `owns` | Entity owns another entity | `"outgoing"` from owner |
+| `appears_in` | Entity mentioned in article | `"both"` is usually safest |
+| `participant` | Entity participates in event | `"both"` is usually safest |
+| `filed` | Org filed a document | `"outgoing"` from org |
+| `works_at` | Person works at org | `"outgoing"` from person |
+
+> **Tip:** If you're unsure about direction, use `"both"` (the default)
+> first and check the results. Then narrow to `"incoming"` or
+> `"outgoing"` once you know which way the edges point. You can also use
+> `elemental_get_relationships` to see all relationship types and counts
+> between two specific entities.
+
+> **Tip:** Use `elemental_introspect(flavor="organization")` to see which
+> properties and relationships are actually populated with data and their
+> fill rates. This prevents building features against empty data.
+
+---
+
+## Anti-Patterns
+
+These are mistakes previous agents have made. Do not repeat them.
+
+1. **Do not substring-match PID names to find events or filings.**
+   PIDs like `"filed"` are document relationship IDs, not event timestamps.
+   Use `elemental_get_events` for events.
+
+2. **Do not render raw NEID values in user-facing text.** If a property
+   value looks like a large number (`5816460566439750832`), it's probably
+   a `nindex` reference. Check the schema.
+
+3. **Do not skip schema lookup.** Property types are not guessable from
+   names alone. `"country"` looks like it should be a string, but it's
+   an `nindex` (entity reference). Always call `elemental_get_schema`
+   at least once per flavor.
+
+4. **Do not return thin briefings.** When a user asks "tell me about
+   Intel," they expect a comprehensive research report — not a single
+   paragraph. Chain entity + related + events into a thorough response.
+
+5. **Do not fabricate citation refs.** Only include `[ref_...]` markers
+   when the `ref` field is actually present in the tool response data.
+   The client renders these as numbered citations with source links.
+
+---
+
+## Citation Handling
+
+Property values may include a `ref` field (e.g. `"ref_a3f2b1c8"`). When
+building user-facing text, include the ref in brackets after the fact:
+
+```
+Revenue was $52.9B [ref_a3f2b1c8]
+```
+
+The chat UI translates these into numbered source citations. Rules:
+- Only include refs that are present in the actual response data
+- Copy the ref string exactly — never construct or modify refs
+- Omit the bracket when no ref is present for a value

package/variants/mcp-only/rules/agents-data.mdc

@@ -6,7 +6,13 @@ globs: agents/**
 
 # Agents: Elemental MCP (MCP-only)
 
-In **mcp-only** mode, **Elemental MCP** is the primary way agents reach the knowledge graph. **`broadchurch_auth` HTTP** to the Query Server is the **api-mcp** path; here you wire **MCP tools** into ADK (e.g. **McpToolset** + `SseConnectionParams` to your Elemental MCP URL — from env or `broadchurch.yaml` / gateway).
+In **mcp-only** mode, **Elemental MCP** is the primary way agents reach the knowledge graph. **`broadchurch_auth` HTTP** to the Query Server is the **api-mcp** path; here you wire **MCP tools** into ADK via **McpToolset** + **`StreamableHTTPConnectionParams`** to your Elemental MCP URL — from env or `broadchurch.yaml` / gateway.
+
+> **Transport class:** The Elemental MCP server uses **Streamable HTTP**
+> transport. Use `StreamableHTTPConnectionParams` — **NOT**
+> `SseConnectionParams`. Using `SseConnectionParams` will silently fail:
+> the agent starts with zero tools and the LLM hallucinates code. See the
+> "Wiring McpToolset" section below for a working snippet.
 
 ## Primary agent patterns (all first-class)
 
@@ -18,10 +24,52 @@ In **mcp-only** mode, **Elemental MCP** is the primary way agents reach the know
 
 You can deploy **multiple agents** with different mixes of A–C.
 
+## Wiring McpToolset
+
+Use `StreamableHTTPConnectionParams` to connect to the Elemental MCP
+server. Resolve the URL from `broadchurch.yaml` (gateway-proxied in
+production) or fall back to `ELEMENTAL_MCP_URL` for local dev.
+
+```python
+import os
+from pathlib import Path
+import yaml
+from google.adk.tools.mcp_tool import McpToolset
+from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
+
+def _get_mcp_url(server_name: str = "elemental") -> str:
+    """Resolve MCP server URL from env or broadchurch.yaml."""
+    env_url = os.environ.get("ELEMENTAL_MCP_URL")
+    if env_url:
+        return env_url
+    for candidate in [Path("broadchurch.yaml"), Path(__file__).parent / "broadchurch.yaml"]:
+        if candidate.exists():
+            config = yaml.safe_load(candidate.read_text()) or {}
+            gw = config.get("gateway", {})
+            org_id = config.get("tenant", {}).get("org_id", "")
+            if gw.get("url") and org_id:
+                return f"{gw['url'].rstrip('/')}/api/mcp/{org_id}/{server_name}/mcp"
+            return config.get("mcp", {}).get(server_name, "")
+    return ""
+
+mcp_url = _get_mcp_url()
+mcp_tools = [McpToolset(connection_params=StreamableHTTPConnectionParams(url=mcp_url))] if mcp_url else []
+```
+
+> **Silent failure warning:** If `McpToolset` cannot connect (wrong
+> transport, bad URL, server down), the agent starts with **zero MCP
+> tools** and the LLM will hallucinate code instead of calling tools.
+> Always verify tool count at startup:
+>
+> ```python
+> if not mcp_url:
+>     raise RuntimeError("No MCP URL configured — check broadchurch.yaml or ELEMENTAL_MCP_URL env var")
+> ```
+
 ## Python stack (typical)
 
 - `google-adk` — agent framework
-- MCP client or ADK **McpToolset** — `ELEMENTAL_MCP_URL` or gateway-proxied MCP URL
+- ADK **McpToolset** + **`StreamableHTTPConnectionParams`** — `ELEMENTAL_MCP_URL` or gateway-proxied MCP URL
 - **`psycopg2-binary`** — only when an agent **persists** to `DATABASE_URL`
 
 ```bash