@yottagraph-app/aether-instructions 1.1.22 → 1.1.24

package/commands/build_my_app.md

@@ -92,7 +92,47 @@ Key capabilities:
 
 ---
 
-## Step 4: Design the UX
+## Step 4: Verify Data Availability
+
+Before designing UX, verify that the data your app needs actually exists
+in the knowledge graph. This prevents building features around empty data.
+
+**If MCP tools are available:**
+
+```
+elemental_get_schema()                          → list entity types, confirm your target types exist
+elemental_get_entity(entity="Microsoft")        → verify entity lookup works with a known entity
+elemental_get_entity(entity="Apple Inc")        → try another known entity
+```
+
+If schema calls succeed but entity lookups return "not found," that means
+the entity type exists in the schema but has no data. That's a **data
+issue**, not a broken server. Try different, well-known entity names.
+
+**If MCP tools are NOT available, use curl:**
+
+```bash
+# Read credentials from broadchurch.yaml
+GW=$(grep 'url:' broadchurch.yaml | head -1 | sed 's/.*"\(.*\)".*/\1/')
+ORG=$(grep 'org_id:' broadchurch.yaml | sed 's/.*"\(.*\)".*/\1/')
+KEY=$(grep 'qs_api_key:' broadchurch.yaml | sed 's/.*"\(.*\)".*/\1/')
+
+# List entity types
+curl -s "$GW/api/qs/$ORG/elemental/metadata/schema" -H "X-Api-Key: $KEY"
+
+# Search for a known entity
+curl -s "$GW/api/qs/$ORG/entities/search" \
+  -X POST -H "Content-Type: application/json" -H "X-Api-Key: $KEY" \
+  -d '{"queries":[{"queryId":1,"query":"Microsoft"}],"maxResults":3,"includeNames":true}'
+```
+
+**Document what you find.** If certain entity types have sparse data, note
+it in your UX plan. Design features around data that actually exists, and
+mark aspirational features (that need more data) as future work.
+
+---
+
+## Step 5: Design the UX
 
 Based on the brief, think about the right UX for this specific problem. Do NOT default to a sidebar-with-tabs layout. Consider:
 
@@ -116,7 +156,7 @@ Present the plan to the user and ask for approval before proceeding.
 
 ---
 
-## Step 5: Build
+## Step 6: Build
 
 Implement the plan:
 
@@ -128,6 +168,13 @@ Implement the plan:
 6. Use Vuetify components and the project's dark theme
 7. Update `DESIGN.md` with what you built
 
+**Use the pre-built platform utilities:**
+
+- `useElementalSchema()` — schema discovery with caching, flavor/PID lookup helpers
+- `buildGatewayUrl()`, `getApiKey()`, `padNeid()` from `utils/elementalHelpers`
+- `searchEntities()`, `getEntityName()` from `utils/elementalHelpers`
+- `useElementalClient()` from `@yottagraph-app/elemental-api/client`
+
 **Follow the project's coding conventions:**
 
 - `<script setup lang="ts">` for all Vue components
@@ -136,7 +183,7 @@ Implement the plan:
 
 ---
 
-## Step 6: Verify
+## Step 7: Verify
 
 After building, check dependencies are installed and run a build:
 
@@ -151,7 +198,7 @@ Then suggest the user run `npm run dev` to preview their app locally.
 
 ---
 
-## Step 7: Next Steps
+## Step 8: Next Steps
 
 > Your app is taking shape! Here's what you can do next:
 >

package/package.json

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

package/rules/api.mdc

@@ -50,6 +50,29 @@ elemental_get_related(entity="Apple",
 MCP tells you the correct flavor IDs, property IDs, and data shapes. Use
 these to inform your REST implementation.
 
+**Verify MCP is working with known-good queries:**
+
+```
+elemental_get_schema()                          → should return flavors + properties
+elemental_get_entity(entity="Microsoft")        → should resolve to a company
+elemental_get_entity(entity="Apple Inc")        → another known entity
+elemental_health()                              → server health check
+```
+
+**Interpreting MCP errors — do NOT assume the server is broken:**
+
+- `entity not found` or 404 in entity lookup → the entity doesn't exist
+  in the knowledge graph, not a connectivity problem. Try a different entity.
+- `failed to get property values: 404` → the entity was resolved but has
+  no data for those properties. The MCP server is working correctly.
+- Schema calls succeed but entity calls fail → data is sparse for that
+  entity type. Try well-known entities (Microsoft, Apple Inc, JPMorgan).
+- If `elemental_health()` fails → actual connectivity problem.
+
+**Key insight:** A 404 from an MCP entity/property call means "not found,"
+not "server broken." Always test with known entities before concluding
+the server is down.
+
 ### Step 2: curl (verify exact request/response shapes)
 
 MCP doesn't cover every REST endpoint (e.g. `/elemental/find` expressions).
@@ -101,11 +124,44 @@ All other endpoints accept `application/json`.
 **Interpreting errors:** 400 = expression syntax is wrong. 500 = expression
 is valid but the query failed (wrong PID, unsupported operator for that
 property type). 200 + empty `eids` = query worked but no results match.
+404 from entity/property endpoints = entity or data doesn't exist (not a
+server error). Always test with known entities (e.g. search for "Microsoft")
+before assuming the API is broken.
 
 ### Step 3: Implement with confidence
 
 Now write your composable or server route, knowing the exact API shapes.
 
+## Pre-Built Helpers
+
+The template includes composables and utilities that handle common
+Elemental API patterns. **Use these instead of writing from scratch:**
+
+### `useElementalSchema()` — Schema Discovery with Caching
+
+```typescript
+const { flavors, properties, flavorByName, pidByName, refresh } = useElementalSchema();
+await refresh();                                // fetches once, then cached
+const articleFid = flavorByName('article');      // → number | null
+const namePid = pidByName('name');              // → typically 8
+```
+
+Handles the dual response shapes (`res.schema.flavors` vs `res.flavors`)
+and the `fid`/`findex` naming inconsistency automatically.
+
+### `utils/elementalHelpers` — Gateway URL Helpers
+
+```typescript
+import { buildGatewayUrl, getApiKey, padNeid, searchEntities, getEntityName } from '~/utils/elementalHelpers';
+
+const url = buildGatewayUrl('entities/search');   // full gateway URL
+const key = getApiKey();                          // from runtimeConfig
+const neid = padNeid('4926132345040704022');       // → "04926132345040704022"
+
+const results = await searchEntities('Microsoft'); // batch name search
+const name = await getEntityName(neid);            // display name lookup
+```
+
 ## Client Usage
 
 All API calls go through `useElementalClient()` from `@yottagraph-app/elemental-api/client`.

package/rules/cookbook.mdc

@@ -388,7 +388,169 @@ Two-column layout with selectable list and detail panel.
 </script>
 ```
 
-## 7. Get Filings for a Company
+## 7. News Feed — Recent Articles with Sentiment
+
+Fetch recent articles from the knowledge graph. Uses `useElementalSchema()`
+for runtime flavor/PID discovery and `buildGatewayUrl()` for gateway access.
+
+```vue
+<template>
+    <div class="d-flex flex-column fill-height pa-4">
+        <h1 class="text-h5 mb-4">Recent News</h1>
+        <v-alert v-if="error" type="error" variant="tonal" class="mb-4" closable>
+            {{ error }}
+        </v-alert>
+        <v-progress-linear v-if="loading" indeterminate class="mb-4" />
+        <v-list v-if="articles.length" lines="three">
+            <v-list-item v-for="a in articles" :key="a.neid">
+                <template #title>
+                    <span>{{ a.name || a.neid }}</span>
+                    <v-chip
+                        v-if="a.sentiment"
+                        size="x-small"
+                        class="ml-2"
+                        :color="a.sentiment > 0 ? 'success' : a.sentiment < 0 ? 'error' : 'grey'"
+                    >
+                        {{ a.sentiment > 0 ? 'Bullish' : a.sentiment < 0 ? 'Bearish' : 'Neutral' }}
+                    </v-chip>
+                </template>
+                <template #subtitle>{{ a.neid }}</template>
+            </v-list-item>
+        </v-list>
+        <v-empty-state
+            v-else-if="!loading"
+            headline="No articles found"
+            icon="mdi-newspaper-variant-outline"
+        />
+    </div>
+</template>
+
+<script setup lang="ts">
+    import { useElementalClient } from '@yottagraph-app/elemental-api/client';
+    import { padNeid } from '~/utils/elementalHelpers';
+
+    const client = useElementalClient();
+    const { flavorByName, pidByName, refresh: loadSchema } = useElementalSchema();
+
+    const articles = ref<{ neid: string; name: string; sentiment: number | null }[]>([]);
+    const loading = ref(false);
+    const error = ref<string | null>(null);
+
+    onMounted(async () => {
+        loading.value = true;
+        try {
+            await loadSchema();
+            const articleFid = flavorByName('article');
+            if (!articleFid) {
+                error.value = 'Article entity type not found in schema';
+                return;
+            }
+
+            const res = await client.findEntities({
+                expression: JSON.stringify({ type: 'is_type', is_type: { fid: articleFid } }),
+                limit: 20,
+            });
+            const neids: string[] = (res as any).eids ?? [];
+
+            if (!neids.length) {
+                return;
+            }
+
+            const namePid = pidByName('name');
+            const sentimentPid = pidByName('sentiment');
+            const pids = [namePid, sentimentPid].filter((p): p is number => p !== null);
+
+            const props = await client.getPropertyValues({
+                eids: JSON.stringify(neids),
+                pids: JSON.stringify(pids),
+            });
+
+            const valueMap = new Map<string, Record<number, any>>();
+            for (const v of (props as any).values ?? []) {
+                const eid = padNeid(v.eid ?? v.entity_id ?? '');
+                if (!valueMap.has(eid)) valueMap.set(eid, {});
+                valueMap.get(eid)![v.pid] = v.value;
+            }
+
+            articles.value = neids.map((neid) => {
+                const vals = valueMap.get(neid) ?? {};
+                return {
+                    neid,
+                    name: namePid ? (vals[namePid] as string) ?? neid : neid,
+                    sentiment: sentimentPid ? (vals[sentimentPid] as number) ?? null : null,
+                };
+            });
+        } catch (e: any) {
+            error.value = e.message || 'Failed to load articles';
+        } finally {
+            loading.value = false;
+        }
+    });
+</script>
+```
+
+## 8. Entity Search with Gateway Helpers
+
+Simpler version of recipe #1 using the pre-built `searchEntities()` helper.
+
+```vue
+<template>
+    <div class="d-flex flex-column fill-height pa-4">
+        <h1 class="text-h5 mb-4">Entity Search</h1>
+        <v-text-field
+            v-model="query"
+            label="Search entities"
+            prepend-inner-icon="mdi-magnify"
+            variant="outlined"
+            @keyup.enter="search"
+            :loading="loading"
+        />
+        <v-alert v-if="error" type="error" variant="tonal" class="mt-2" closable>
+            {{ error }}
+        </v-alert>
+        <v-list v-if="results.length" class="mt-4">
+            <v-list-item
+                v-for="r in results"
+                :key="r.neid"
+                :title="r.name"
+                :subtitle="r.neid"
+            />
+        </v-list>
+        <v-empty-state
+            v-else-if="searched && !loading"
+            headline="No results"
+            icon="mdi-magnify-remove-outline"
+        />
+    </div>
+</template>
+
+<script setup lang="ts">
+    import { searchEntities } from '~/utils/elementalHelpers';
+
+    const query = ref('');
+    const results = ref<{ neid: string; name: string }[]>([]);
+    const loading = ref(false);
+    const error = ref<string | null>(null);
+    const searched = ref(false);
+
+    async function search() {
+        if (!query.value.trim()) return;
+        loading.value = true;
+        error.value = null;
+        searched.value = true;
+        try {
+            results.value = await searchEntities(query.value.trim());
+        } catch (e: any) {
+            error.value = e.message || 'Search failed';
+            results.value = [];
+        } finally {
+            loading.value = false;
+        }
+    }
+</script>
+```
+
+## 9. Get Filings for a Company
 
 Fetch Edgar filings (or any relationship-linked documents) for an organization.
 Uses `$fetch` for the initial entity search because `POST /entities/search`

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

@@ -0,0 +1,184 @@
+# Data Dictionary — BNY Arbitrage Rebate Analysis
+
+## Source Description
+
+Interim Arbitrage Rebate Analysis reports prepared by BLX Group LLC for
+municipal bond issuers. Each report computes the arbitrage rebate liability
+under IRC Section 148 for a bond issue across a computation period. Reports
+include transmittal letters, legal opinions, notes/assumptions, summary
+schedules (rebate analysis, sources/uses of funds), and detailed per-fund
+cash flow and investment data.
+
+BNY (Bank of New York Mellon) serves as trustee. Orrick, Herrington &
+Sutcliffe LLP provides the accompanying legal opinion.
+
+## Entity Types
+
+### bond
+
+The municipal bond issue itself. One entity per unique bond across all reports.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `client_matter_number` | string | **Strong ID.** BLX Group client matter number (e.g. `42182-2748`). Invariant across all reports for the same bond. |
+| `bonds_name` | string | Full name of the bonds (e.g. "Multifamily Housing Revenue Refunding Bonds (Presidential Plaza at Newport Project-FHA Insured Mortgages) 1991 Series 1") |
+| `par_amount` | string | Total par amount of the bond issue (e.g. "$142,235,000") |
+| `dated_date` | string | Dated date of the bonds (e.g. "September 15, 1991") |
+| `issue_date` | string | Issue date of the bonds (e.g. "October 17, 1991") |
+| `bond_yield` | string | Arbitrage yield / allowable yield on investments (e.g. "7.420898%") |
+| `computation_period` | string | The computation period for this report (e.g. "October 17, 1991 through October 16, 2024") |
+| `rebate_computation_date` | string | End date of the computation period (e.g. "October 16, 2024") |
+| `cumulative_rebate_liability` | string | Total cumulative rebate liability (e.g. "$0.00") |
+| `rebate_payment_due` | string | Amount due to the US (e.g. "$0.00") |
+| `return_on_investments` | string | Weighted return on investments since prior computation date (e.g. "6.447251%") |
+| `shortfall_pct` | string | Shortfall percentage: return minus yield (e.g. "-0.973647%") |
+| `actual_gross_earnings` | string | Total actual gross earnings across all funds |
+| `allowable_gross_earnings` | string | Total allowable gross earnings at bond yield |
+| `excess_earnings` | string | Total excess (negative = under yield) |
+| `report_date` | string | Date the report was issued (e.g. "December 6, 2024") |
+
+### organization
+
+Companies, agencies, law firms, and financial institutions named in the reports.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `org_type` | string | Type: `government_agency`, `law_firm`, `financial_services`, `financial_institution`, `trust_company` |
+| `description` | string | Role in the deal (e.g. "Issuer", "Trustee", "Bond Counsel") |
+
+Expected entities:
+- New Jersey Housing and Mortgage Finance Agency (Issuer)
+- BLX Group LLC (Rebate Analyst)
+- Orrick, Herrington & Sutcliffe LLP (Bond Counsel)
+- BNY / Bank of New York Mellon (Trustee)
+- Willdan Financial Services (Prior Report preparer)
+- U.S. Department of the Treasury
+
+### fund_account
+
+Bond proceeds sub-accounts tracked for rebate computation purposes.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `fund_status` | string | Current status: `Active` or `Inactive` |
+| `computation_date_valuation` | string | Fair market value at computation date |
+| `gross_earnings` | string | Total gross earnings for the fund |
+| `internal_rate_of_return` | string | IRR on the fund's investments |
+| `excess_earnings` | string | Excess earnings (negative = below yield) |
+
+Expected entities:
+- Reserve I Account
+- Reserve II Account
+- Prior Rebate Liability
+- Liquidity I Account
+- Liquidity II Account
+
+Additional fund accounts mentioned in Notes and Assumptions:
+- Revenue Account (bona fide debt service fund, excluded from rebate)
+- Escrow Fund
+- Debt Service Reserve Account
+- Construction Account
+
+### financial_instrument
+
+Securities held within fund accounts (investments of bond proceeds).
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `par_amount` | string | Par amount of the security |
+| `coupon` | string | Coupon rate (e.g. "7.000%" or "Variable") |
+| `maturity_date` | string | Maturity date |
+| `settlement_date` | string | Settlement date |
+| `settlement_price` | string | Settlement price (e.g. "100.000") |
+| `yield` | string | Yield on the security |
+| `accreted_price` | string | Accreted price |
+| `accrued_interest` | string | Accrued interest amount |
+| `value` | string | Total value (par + accrued interest) |
+
+Expected entities (scoped per fund via `entity_context_from_title`):
+- Morgan IA (7% coupon, institutional investment)
+- Federated MM (variable rate money market fund)
+
+### legal_agreement
+
+Governing legal documents referenced in the reports.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `agreement_type` | string | Type: `arbitrage_certificate`, `trust_indenture`, `engagement_letter` |
+| `description` | string | Description of the agreement's role |
+
+Expected entities:
+- Certificate as to Arbitrage (Section 8, Section 21 referenced)
+- Prior Report (Willdan Financial Services, December 17, 2008)
+
+### location
+
+Addresses and jurisdictions.
+
+Expected entities:
+- Trenton, NJ (Issuer address)
+- Dallas, TX (BLX Group address)
+- New York, NY (Orrick address)
+- State of New Jersey
+
+### person
+
+Signatories, if extractable from signatures on transmittal letters and opinions.
+May be sparse — many PDFs have illegible or absent signature blocks.
+
+## Relationships
+
+| Relationship | Domain | Target | Description |
+|-------------|--------|--------|-------------|
+| `issuer_of` | organization | bond | Issuer issued the bonds |
+| `trustee_of` | organization | bond | Trustee of the bond issue |
+| `advisor_to` | organization | bond | BLX Group as rebate analyst; Orrick as bond counsel |
+| `fund_of` | fund_account | bond | Fund account belongs to the bond issue |
+| `holds_investment` | fund_account | financial_instrument | Fund holds a security as an investment |
+| `party_to` | organization | legal_agreement | Entity is party to an agreement |
+| `located_at` | organization | location | Organization's address |
+| `predecessor_of` | legal_agreement | legal_agreement | Prior Report preceded current Report |
+
+## Events
+
+| Event | Severity | Description |
+|-------|----------|-------------|
+| Rebate computation | medium | Periodic computation of arbitrage rebate liability |
+| Bond issuance | high | Original issuance of the bonds (October 17, 1991) |
+| Bond refunding | high | Refunding of prior 1985 Series F and G bonds |
+| Fund valuation | medium | Valuation of fund accounts at computation date |
+| Rebate payment determination | high | Determination that rebate payment is/isn't due |
+| Report issuance | low | Issuance of this rebate analysis report |
+
+## Table Extraction
+
+### Schedule A — Summary of Rebate Analysis
+
+Maps to `rebate_analysis` table config. Key column: Fund Description.
+Each row becomes a `fund_account` entity with properties for status,
+valuation, earnings, IRR, and excess earnings.
+
+### Schedule B — Sources & Uses of Funds
+
+Maps to `sources_of_funds` and `uses_of_funds` table configs. Uses
+`document_entity_from_title` mode to attach line items as properties
+on the bond entity.
+
+### Security Holdings (Schedules C1, D1, F1, G1)
+
+Maps to `security_tables` config. Key column: Security Type. Each
+security becomes a `financial_instrument` entity scoped by fund
+account title. Properties: par amount, coupon, maturity, yield, etc.
+
+### Cash Flow Tables (Schedules C2, D2, E1, F2, G2)
+
+New table config needed. These are the largest tables — hundreds of rows
+of deposit/withdrawal transactions for each fund account. Columns:
+Date, Description, Cash Flow, Muni-Days/Computation Date, FV Factor
+at bond yield, FV As Of at bond yield, FV Factor at IRR, FV As Of at IRR.
+
+## Citations
+
+All extracted data should cite the specific schedule and page number
+within the source PDF. The PDF filename serves as the document identifier.