@yottagraph-app/aether-instructions 1.1.22 → 1.1.23

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.23",
     "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`