@yottagraph-app/aether-instructions 1.1.27 → 1.1.28

package/rules/cookbook.mdc

@@ -1,5 +1,5 @@
 ---
-description: "Copy-paste UI patterns for common pages: entity search, data table, form, chart, master-detail. Read when building new pages or features."
+description: "Copy-paste UI patterns for common pages: data table, form, chart, dialog, master-detail. For Query Server / data-fetching recipes see `cookbook-data`."
 alwaysApply: false
 ---
 
@@ -7,92 +7,7 @@ alwaysApply: false
 
 Copy-paste patterns using the project's actual composables and Vuetify components. Adapt to your needs.
 
-## 1. Entity Search Page
-
-Search for entities by name and display results. Uses `$fetch` directly
-because `POST /entities/search` (batch name resolution with scored ranking)
-is not wrapped by the generated `useElementalClient()` — see the `api` rule.
-
-```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="(neid, i) in results"
-                :key="neid"
-                :title="names[i] || neid"
-                :subtitle="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 { useElementalClient } from '@yottagraph-app/elemental-api/client';
-
-    const client = useElementalClient();
-    const query = ref('');
-    const results = ref<string[]>([]);
-    const names = ref<string[]>([]);
-    const loading = ref(false);
-    const error = ref<string | null>(null);
-    const searched = ref(false);
-
-    function getSearchUrl() {
-        const config = useRuntimeConfig();
-        const gw = (config.public as any).gatewayUrl as string;
-        const org = (config.public as any).tenantOrgId as string;
-        return `${gw}/api/qs/${org}/entities/search`;
-    }
-
-    function getApiKey() {
-        return (useRuntimeConfig().public as any).qsApiKey as string;
-    }
-
-    async function search() {
-        if (!query.value.trim()) return;
-        loading.value = true;
-        error.value = null;
-        searched.value = true;
-        try {
-            const res = await $fetch<any>(getSearchUrl(), {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json', 'X-Api-Key': getApiKey() },
-                body: {
-                    queries: [{ queryId: 1, query: query.value.trim() }],
-                    maxResults: 10,
-                    includeNames: true,
-                },
-            });
-            const matches = res?.results?.[0]?.matches ?? [];
-            results.value = matches.map((m: any) => m.neid);
-            names.value = matches.map((m: any) => m.name || m.neid);
-        } catch (e: any) {
-            error.value = e.message || 'Search failed';
-            results.value = [];
-        } finally {
-            loading.value = false;
-        }
-    }
-</script>
-```
+**Data-fetching recipes** (entity search, news feed, filings, gateway helpers) live in the `cookbook-data` rule.
 
 ## 2. Data Table Page
 
@@ -387,313 +302,3 @@ Two-column layout with selectable list and detail panel.
     });
 </script>
 ```
-
-## 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`
-is not wrapped by the generated client (same as recipe #1). Filing
-properties are then fetched via `useElementalClient()`.
-
-**Important:** For graph-layer entities (person, organization, location),
-use `findEntities` with a `linked` expression. For property-layer entities
-(documents, filings, articles), use `getPropertyValues` with the
-relationship PID. See the `api` rule for the two-layer architecture.
-
-```vue
-<template>
-    <div class="d-flex flex-column fill-height pa-4">
-        <h1 class="text-h5 mb-4">Company Filings</h1>
-        <v-text-field
-            v-model="query"
-            label="Company name"
-            prepend-inner-icon="mdi-magnify"
-            @keyup.enter="search"
-            :loading="loading"
-        />
-        <v-alert v-if="error" type="error" variant="tonal" class="mt-2" closable>
-            {{ error }}
-        </v-alert>
-        <v-data-table
-            v-if="filings.length"
-            :headers="headers"
-            :items="filings"
-            :loading="loading"
-            density="comfortable"
-            hover
-            class="mt-4"
-        />
-        <v-empty-state
-            v-else-if="searched && !loading"
-            headline="No filings found"
-            icon="mdi-file-document-off"
-        />
-    </div>
-</template>
-
-<script setup lang="ts">
-    import { useElementalClient } from '@yottagraph-app/elemental-api/client';
-
-    const client = useElementalClient();
-    const query = ref('');
-    const filings = ref<{ neid: string; name: string }[]>([]);
-    const loading = ref(false);
-    const error = ref<string | null>(null);
-    const searched = ref(false);
-
-    const headers = [
-        { title: 'NEID', key: 'neid', sortable: true },
-        { title: 'Name', key: 'name', sortable: true },
-    ];
-
-    async function getPropertyPidMap(client: ReturnType<typeof useElementalClient>) {
-        const schemaRes = await client.getSchema();
-        const properties = schemaRes.schema?.properties ?? (schemaRes as any).properties ?? [];
-        return new Map(properties.map((p: any) => [p.name, p.pid]));
-    }
-
-    function getSearchUrl() {
-        const config = useRuntimeConfig();
-        const gw = (config.public as any).gatewayUrl as string;
-        const org = (config.public as any).tenantOrgId as string;
-        return `${gw}/api/qs/${org}/entities/search`;
-    }
-
-    function getApiKey() {
-        return (useRuntimeConfig().public as any).qsApiKey as string;
-    }
-
-    async function search() {
-        if (!query.value.trim()) return;
-        loading.value = true;
-        error.value = null;
-        searched.value = true;
-        try {
-            const res = await $fetch<any>(getSearchUrl(), {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json', 'X-Api-Key': getApiKey() },
-                body: {
-                    queries: [{ queryId: 1, query: query.value.trim(), flavors: ['organization'] }],
-                    maxResults: 1,
-                    includeNames: true,
-                },
-            });
-            const matches = res?.results?.[0]?.matches ?? [];
-            if (!matches.length) {
-                filings.value = [];
-                return;
-            }
-            const orgNeid = matches[0].neid;
-
-            const pidMap = await getPropertyPidMap(client);
-            const filedPid = pidMap.get('filed');
-            if (!filedPid) {
-                error.value = '"filed" relationship not found in schema';
-                return;
-            }
-
-            const propRes = await client.getPropertyValues({
-                eids: JSON.stringify([orgNeid]),
-                pids: JSON.stringify([filedPid]),
-            });
-
-            const docNeids = (propRes.values ?? []).map((v: any) =>
-                String(v.value).padStart(20, '0'),
-            );
-
-            function getEntityNameUrl(neid: string) {
-                const config = useRuntimeConfig();
-                const gw = (config.public as any).gatewayUrl as string;
-                const org = (config.public as any).tenantOrgId as string;
-                return `${gw}/api/qs/${org}/entities/${neid}/name`;
-            }
-
-            const names = await Promise.all(
-                docNeids.map(async (neid: string) => {
-                    try {
-                        const res = await $fetch<{ name: string }>(
-                            getEntityNameUrl(neid),
-                            { headers: { 'X-Api-Key': getApiKey() } },
-                        );
-                        return res.name || neid;
-                    } catch {
-                        return neid;
-                    }
-                }),
-            );
-
-            filings.value = docNeids.map((neid: string, i: number) => ({
-                neid,
-                name: names[i],
-            }));
-        } catch (e: any) {
-            error.value = e.message || 'Failed to load filings';
-            filings.value = [];
-        } finally {
-            loading.value = false;
-        }
-    }
-</script>
-```

package/rules/{api.mdc → data.mdc}

@@ -1,8 +1,8 @@
 ---
-description: "Elemental API client usage, schema discovery, entity search, API gotchas, MCP servers. Read when building features that fetch or display data from the Query Server."
+description: "Data access via Elemental API: client usage, schema discovery, entity search, API gotchas, MCP servers. Read when building features that fetch or display data from the Query Server."
 alwaysApply: false
 ---
-# Elemental API — The Platform Data Source
+# Data — Elemental API (platform data source)
 
 **This app is built on the Lovelace platform.** The Query Server is the
 primary data source — use it first for any data needs (entities, news,
@@ -379,7 +379,7 @@ const res = await client.getPropertyValues({
 const docNeids = (res.values ?? []).map((v) => String(v.value).padStart(20, '0'));
 ```
 
-See the **cookbook** rule for a full "Get filings for a company" recipe.
+See the **cookbook-data** rule for a full "Get filings for a company" recipe.
 
 ### Expression language pitfalls
 
@@ -425,7 +425,7 @@ source-specific schemas.
   `getPropertyValues()` with the relationship PID. Values are entity IDs
   that must be zero-padded to 20 characters.
 
-See the **cookbook** rule (recipe #7) for a full example.
+See the **cookbook-data** rule (news feed recipe) for a full example.
 
 ## Error Handling
 

package/rules/instructions_warning.mdc

@@ -27,7 +27,7 @@ Example:
 
 ```bash
 # Copy the rule you want to customize
-cp .cursor/rules/api.mdc .cursor/rules/api_custom.mdc
+cp .cursor/rules/data.mdc .cursor/rules/data_custom.mdc
 
 # Edit your copy — it won't be affected by instruction updates
 ```
@@ -35,7 +35,7 @@ cp .cursor/rules/api.mdc .cursor/rules/api_custom.mdc
 ## How It Works
 
 - `.cursor/.aether-instructions-manifest` lists every file installed by the
-  package (one relative path per line, e.g. `rules/api.mdc`)
+  package (one relative path per line, e.g. `rules/data.mdc`)
 - `/update_instructions` deletes manifest entries, extracts fresh files from
   the latest package, and writes a new manifest
 - Files not in the manifest are never touched

package/rules/server-data.mdc

@@ -0,0 +1,54 @@
+---
+description: "Calling the Elemental API from Nitro server routes via the Portal Gateway. Read when proxying Query Server calls server-side."
+alwaysApply: false
+globs: server/**
+---
+
+# Server routes: Elemental API (Query Server)
+
+Server routes can call the Elemental API through the Portal Gateway proxy,
+just like client-side code does. The gateway URL, tenant org ID, and API key
+are available via `useRuntimeConfig()`.
+
+**NEVER use `readFileSync('broadchurch.yaml')` in server routes.** The YAML
+file is read at build time by `nuxt.config.ts` and its values flow into
+`runtimeConfig`. Nitro serverless functions (Vercel) don't bundle arbitrary
+project files — `readFileSync` will crash with ENOENT in production even
+though it works locally.
+
+```typescript
+export default defineEventHandler(async (event) => {
+  const { public: config } = useRuntimeConfig();
+
+  const gatewayUrl = config.gatewayUrl;   // Portal Gateway base URL
+  const orgId = config.tenantOrgId;       // Tenant org ID (path segment)
+  const apiKey = config.qsApiKey;         // API key for X-Api-Key header
+
+  if (!gatewayUrl || !orgId) {
+    throw createError({ statusCode: 503, statusMessage: 'Gateway not configured' });
+  }
+
+  const res = await $fetch(`${gatewayUrl}/api/qs/${orgId}/entities/search`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      ...(apiKey && { 'X-Api-Key': apiKey }),
+    },
+    body: { queries: [{ queryId: 1, query: 'Microsoft' }], maxResults: 5 },
+  });
+
+  return res;
+});
+```
+
+Available runtime config keys (all under `runtimeConfig.public`):
+
+| Key | Source | Purpose |
+|---|---|---|
+| `gatewayUrl` | `broadchurch.yaml` → `gateway.url` | Portal Gateway base URL |
+| `tenantOrgId` | `broadchurch.yaml` → `tenant.org_id` | Tenant ID for API path |
+| `qsApiKey` | `broadchurch.yaml` → `gateway.qs_api_key` | API key sent as `X-Api-Key` |
+| `queryServerAddress` | `broadchurch.yaml` → `query_server.url` | Direct QS URL (prefer gateway) |
+
+Build the request URL as `{gatewayUrl}/api/qs/{tenantOrgId}/{endpoint}`.
+See the `data` rule for endpoint reference and response shapes.

package/rules/server.mdc

@@ -158,54 +158,8 @@ export function getDb(): NeonQueryFunction | null {
 }
 ```
 
-## Calling the Elemental API from Server Routes
-
-Server routes can call the Elemental API through the Portal Gateway proxy,
-just like client-side code does. The gateway URL, tenant org ID, and API key
-are available via `useRuntimeConfig()`.
-
-**NEVER use `readFileSync('broadchurch.yaml')` in server routes.** The YAML
-file is read at build time by `nuxt.config.ts` and its values flow into
-`runtimeConfig`. Nitro serverless functions (Vercel) don't bundle arbitrary
-project files — `readFileSync` will crash with ENOENT in production even
-though it works locally.
-
-```typescript
-export default defineEventHandler(async (event) => {
-  const { public: config } = useRuntimeConfig();
-
-  const gatewayUrl = config.gatewayUrl;   // Portal Gateway base URL
-  const orgId = config.tenantOrgId;       // Tenant org ID (path segment)
-  const apiKey = config.qsApiKey;         // API key for X-Api-Key header
-
-  if (!gatewayUrl || !orgId) {
-    throw createError({ statusCode: 503, statusMessage: 'Gateway not configured' });
-  }
-
-  const res = await $fetch(`${gatewayUrl}/api/qs/${orgId}/entities/search`, {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      ...(apiKey && { 'X-Api-Key': apiKey }),
-    },
-    body: { queries: [{ queryId: 1, query: 'Microsoft' }], maxResults: 5 },
-  });
-
-  return res;
-});
-```
-
-Available runtime config keys (all under `runtimeConfig.public`):
-
-| Key | Source | Purpose |
-|---|---|---|
-| `gatewayUrl` | `broadchurch.yaml` → `gateway.url` | Portal Gateway base URL |
-| `tenantOrgId` | `broadchurch.yaml` → `tenant.org_id` | Tenant ID for API path |
-| `qsApiKey` | `broadchurch.yaml` → `gateway.qs_api_key` | API key sent as `X-Api-Key` |
-| `queryServerAddress` | `broadchurch.yaml` → `query_server.url` | Direct QS URL (prefer gateway) |
-
-Build the request URL as `{gatewayUrl}/api/qs/{tenantOrgId}/{endpoint}`.
-See the `api` rule for endpoint reference and response shapes.
+For **Query Server / Elemental API** calls from server routes (gateway URL,
+`X-Api-Key`, request shapes), see the `server-data` rule.
 
 ## Neon Postgres: Handle Missing Tables in GET Routes
 

package/rules/something-broke.mdc

@@ -49,7 +49,7 @@ import { myHelper } from '~/utils/myHelper';
 
 ### `Type 'X' is not assignable to type 'Y'`
 
-Usually an API response shape mismatch. Common case: `getSchema()` nests data under `response.schema` but TypeScript types suggest top-level access. See the `api` rule's API Gotchas section.
+Usually an API response shape mismatch. Common case: `getSchema()` nests data under `response.schema` but TypeScript types suggest top-level access. See the `data` rule's API Gotchas section.
 
 ### `SyntaxError` or blank page with "missing export"