@yottagraph-app/aether-instructions 1.1.34 → 1.1.36

package/package.json

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

package/rules/agents.mdc

@@ -455,3 +455,29 @@ exploration but requires more tool calls and is more error-prone.
 returns formatted strings. Fewer tools, more reliable, better for production
 use cases. **Prefer this pattern** unless the agent genuinely needs to
 explore arbitrary entity types.
+
+### McpToolset passthrough is not a substitute for custom tools
+
+When DESIGN.md specifies named agent tools (e.g. `entity_search`,
+`corporate_structure`, `event_monitor`), each must be implemented as a
+**Python function** that calls MCP, formats results, and handles errors.
+Passing a raw `McpToolset` as the agent's only tool source and writing a
+long system prompt does **not** satisfy the spec.
+
+`McpToolset` passthrough means:
+- The LLM receives raw JSON responses — no Markdown formatting, no
+  human-readable reports
+- No session-state caching — repeated queries for the same entity make
+  redundant MCP calls every turn
+- No property type handling — `data_nindex` values (entity references)
+  render as meaningless 19-digit numbers
+- No error boundaries — MCP failures surface as opaque tool errors
+- No compound cache keys or report generation — the patterns that make
+  multi-turn research conversations reliable
+
+`McpToolset` passthrough is fine for **simple exploration agents** or
+quick prototypes. It is **not acceptable** when the project spec
+describes a production agent with a defined tool suite. If DESIGN.md
+lists N custom tools, build N custom Python functions — each calling MCP
+tools internally, formatting output as Markdown, catching exceptions,
+and saving reports to session state where appropriate.

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

@@ -604,6 +604,17 @@ These are mistakes previous agents have made. Do not repeat them.
    when the `ref` field is actually present in the tool response data.
    The client renders these as numbered citations with source links.
 
+6. **Do not pass raw `McpToolset` when the spec calls for custom tools.**
+   If DESIGN.md describes named tools (e.g. `entity_search`,
+   `corporate_structure`, `event_monitor`), each must be a Python
+   function that calls MCP internally. Passing `McpToolset` as the
+   agent's only tool source means: no Markdown report formatting, no
+   session-state caching, no property type resolution (`data_nindex`
+   values render as raw NEIDs), no compound cache keys, and no error
+   boundaries. The LLM gets raw JSON and hallucinates when responses
+   are large. `McpToolset` passthrough is acceptable for quick
+   prototypes but not for production agents with a defined tool suite.
+
 ---
 
 ## Citation Handling

package/variants/mcp-only/commands/build_my_app.md

@@ -114,6 +114,18 @@ Match the brief: dashboards from `/api/...`, **chat** as primary, or both. No El
 
 ## Step 6: Build
 
+**If the brief is agent-heavy** (the agent IS the product — chatbot,
+research assistant, investigation tool, etc.), build the agent FIRST:
+
+1. **`agents/`** — Build the full agent with all tools specified in DESIGN.md.
+   Each named tool must be a Python function — do NOT just pass `McpToolset`
+   through and write a system prompt. Read the `agents` rule ("McpToolset
+   passthrough" section) for why this matters.
+2. Test the agent locally with `adk web` before building the UI.
+3. Then build the UI around the working agent.
+
+**For all projects:**
+
 1. **`agents/`** — one or more agents per `agents-data` (sync, research, channeling, or mixed).
 2. **`server/api/` + composables + `pages/`** — when the brief needs materialized lists or detail.
 3. **`pages/chat` or custom** — when the brief is agent-forward.
@@ -121,6 +133,26 @@ Match the brief: dashboards from `/api/...`, **chat** as primary, or both. No El
 
 ---
 
+## Step 6b: Audit Against the Spec
+
+Before committing, re-read DESIGN.md and compare what you built against
+what it specifies. This is a mechanical check — no judgment needed.
+
+1. **List every agent tool** DESIGN.md describes (by name, with purpose).
+2. For each, confirm it exists in your code with the described behavior.
+3. If the spec describes N custom tools and you built fewer, **go back
+   and build the missing ones** before proceeding.
+4. If you used `McpToolset` passthrough where the spec calls for custom
+   Python tool functions, **replace it** — passthrough does not satisfy a
+   spec that describes named tools with specific behaviors.
+5. Check that tools format output as Markdown, handle errors, and cache
+   results in session state where the spec requires it.
+
+Do not skip this step. The most common failure mode is building a polished
+UI connected to a stub agent that passes raw MCP tools through to the LLM.
+
+---
+
 ## Step 7: Verify and Commit
 
 After building, ensure dependencies are installed and run a production build: