@yottagraph-app/aether-instructions 1.1.19 → 1.1.20

package/commands/build_my_app.md

@@ -62,12 +62,15 @@ MCP tools — the app can still be built using the Elemental API client
 
 ## Step 3: Understand the Environment
 
-First, ensure dependencies are installed (skill docs and types aren't available without this):
+First, ensure dependencies are installed (types aren't available without this):
 
 ```bash
 test -d node_modules || npm install
 ```
 
+Skills in `.cursor/skills/` are populated during project init (`node init-project.js`).
+If that directory is empty after `npm install`, run `node init-project.js` to install them.
+
 Then read these files to understand what's available:
 
 1. `DESIGN.md` -- project vision and current status

package/package.json

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

package/rules/aether.mdc

@@ -18,4 +18,4 @@ alwaysApply: true
 
 **First action for a new project:** Run `/build_my_app`.
 
-**Task-specific rules:** `architecture` (project structure, navigation, server routes, agents, MCP), `api` (Elemental API client, schema discovery, gotchas, optional MCP servers), `design` (DESIGN.md workflow, feature docs), `ui` (page templates, layout patterns), `cookbook` (copy-paste UI patterns), `pref` (KV preferences), `branding` (colors, fonts), `server` (Nitro routes, Neon Postgres), `something-broke` (error recovery, build failures).
+**Task-specific rules:** `architecture` (project structure, navigation, server routes, agents, MCP), `api` (Elemental API client, schema discovery, gotchas, optional MCP servers), `design` (DESIGN.md workflow, feature docs), `ui` (page templates, layout patterns), `cookbook` (copy-paste UI patterns), `pref` (KV preferences), `branding` (colors, fonts), `server` (Nitro routes, Neon Postgres, server-side Elemental API), `something-broke` (error recovery, build failures).

package/rules/agents.mdc

@@ -384,3 +384,127 @@ custom chat composable or modify `sendMessage`, follow the same approach.
 - Tool docstrings are critical: they're the LLM's API documentation
 - Handle errors gracefully in tools: return error messages, don't raise exceptions
 - Use `get_schema` as a discovery tool so the agent can learn about entity types at runtime
+
+## Agent Tool Design
+
+LLMs are better at parsing prose than nested JSON. The difference between
+a tool that works reliably and one that confuses the agent often comes down
+to how the tool formats its output. Follow these principles:
+
+### Return formatted strings, not raw JSON
+
+This applies to ADK agent tools, where the LLM reads tool output directly.
+MCP server tools follow different conventions (structured dicts/lists) — see
+the `mcp-servers` rule.
+
+The agent's LLM will try to interpret whatever the tool returns. Raw API
+responses with nested dicts, numeric IDs, and arrays of unlabeled values
+create unnecessary interpretation burden.
+
+```python
+# BAD — raw API response overwhelms the LLM:
+def lookup_entity(name: str) -> dict:
+    resp = elemental_client.get(f"/entities/lookup?entityName={name}&maxResults=5")
+    resp.raise_for_status()
+    return resp.json()  # {"results": [{"neid": "00416400910670863867", ...}]}
+
+# GOOD — formatted string the LLM can immediately use:
+def lookup_entity(name: str) -> str:
+    """Look up an entity by name. Returns entity name, ID, and type."""
+    try:
+        resp = elemental_client.get(f"/entities/lookup?entityName={name}&maxResults=5")
+        resp.raise_for_status()
+        data = resp.json()
+        results = data.get("results", [])
+        if not results:
+            return f"No entities found matching '{name}'."
+        lines = []
+        for r in results[:5]:
+            lines.append(f"- {r.get('name', 'Unknown')} (ID: {r.get('neid', '?')}, Type: {r.get('type', '?')})")
+        return f"Found {len(results)} result(s) for '{name}':\n" + "\n".join(lines)
+    except Exception as e:
+        return f"Error looking up '{name}': {e}"
+```
+
+### Catch all exceptions — never let errors propagate
+
+`raise_for_status()` without a try/catch will crash the tool and produce an
+opaque error in the agent's event stream. Always catch exceptions and return
+a descriptive error string.
+
+```python
+# BAD — unhandled exception kills the tool call:
+def get_data(neid: str) -> dict:
+    resp = elemental_client.post("/elemental/entities/properties", data={...})
+    resp.raise_for_status()
+    return resp.json()
+
+# GOOD — agent gets a useful error message it can relay to the user:
+def get_data(neid: str) -> str:
+    """Get properties for an entity by its NEID."""
+    try:
+        resp = elemental_client.post("/elemental/entities/properties", data={...})
+        resp.raise_for_status()
+        # ... format results ...
+        return formatted_output
+    except Exception as e:
+        return f"Error fetching data for {neid}: {e}"
+```
+
+### Pre-resolve known entities for focused agents
+
+If your agent tracks specific companies, people, or assets, hardcode their
+NEIDs instead of requiring a lookup step. This eliminates a fragile
+search-then-resolve flow.
+
+```python
+TRACKED_COMPANIES = {
+    "Apple": "00416400910670863867",
+    "Tesla": "00508379502570440213",
+    "Microsoft": "00112855504880632635",
+}
+
+def get_company_info(company_name: str) -> str:
+    """Get current information about a tracked company.
+    Available companies: Apple, Tesla, Microsoft."""
+    neid = TRACKED_COMPANIES.get(company_name)
+    if not neid:
+        return f"Unknown company '{company_name}'. Available: {', '.join(TRACKED_COMPANIES)}"
+    # ... fetch and format properties using the known NEID ...
+```
+
+### Combine multi-step API flows into single tools
+
+The fewer tools the agent needs to chain together, the more reliably it
+operates. If every query requires lookup → get properties → format, combine
+those steps into a single tool.
+
+```python
+# BAD — agent must chain 3 tools correctly:
+#   1. lookup_entity("Apple") → get NEID
+#   2. get_schema() → find property PIDs
+#   3. get_property_values(neid, pids) → parse values array
+
+# GOOD — one tool does the full flow:
+def get_company_summary(name: str) -> str:
+    """Get a summary of a company including name, country, and industry."""
+    try:
+        neid = resolve_entity(name)
+        if not neid:
+            return f"Could not find entity '{name}'."
+        props = fetch_properties(neid, [NAME_PID, COUNTRY_PID, INDUSTRY_PID])
+        return format_company_summary(neid, props)
+    except Exception as e:
+        return f"Error getting summary for '{name}': {e}"
+```
+
+### Two agent archetypes
+
+**General explorer** — uses `get_schema` + `find_entities` +
+`get_property_values` with runtime discovery. Good for open-ended
+exploration but requires more tool calls and is more error-prone.
+
+**Focused domain agent** — pre-resolves entity IDs, hardcodes relevant PIDs,
+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.

package/rules/api.mdc

@@ -28,9 +28,11 @@ For Lovelace **entity types, properties, relationships, and per-source schemas**
 
 ## Test Before You Build
 
-**Before writing app code that calls the Query Server, test the actual API
-call first and verify the response shape.** This avoids wasted iteration from incorrect
-assumptions about response shapes.
+**ALWAYS test API calls via curl before writing code that depends on them.**
+This is not optional — the Elemental API has response shapes that differ from
+what the TypeScript types suggest, and assumptions about nesting, property
+formats, and field names will be wrong without testing. This applies doubly
+to server-side code, where you can't inspect responses in the browser console.
 
 ### How to test
 
@@ -118,7 +120,7 @@ All methods return data directly and throw on non-2xx responses.
 | Method | Signature | Purpose |
 |---|---|---|
 | `getSchema` | `()` | All entity types (flavors) and properties (PIDs) |
-| `getPropertyValues` | `(body: { eids: string, pids: string })` | Property values (eids/pids are JSON-stringified arrays!) |
+| `getPropertyValues` | `(body: { eids: string, pids: string })` | Property values (eids: JSON array of NEID strings; pids: JSON array of numeric PIDs) |
 | `summarizeProperty` | `(pid: number)` | Summary stats for a property |
 
 **Relationships and graph:**
@@ -229,10 +231,23 @@ const filingNeid = String(res.values[0].value).padStart(20, '0'); // "0492613234
 > TypeScript type is `string`, not `string[]`. Passing a raw array will silently
 > return no data.
 
+> **WARNING -- PIDs are numeric IDs, not string names.** Property IDs (PIDs)
+> are integers, not human-readable names. `pids: JSON.stringify(['name'])`
+> will fail — use `pids: JSON.stringify([8])` (where 8 is the PID for "name"
+> from `getSchema()`). Always call `getSchema()` first to discover the
+> numeric PID for each property.
+
 ```typescript
+// WRONG — PIDs are numbers, not strings:
+const values = await client.getPropertyValues({
+  eids: JSON.stringify(['00416400910670863867']),
+  pids: JSON.stringify(['name', 'country', 'industry']),  // FAILS
+});
+
+// CORRECT — use numeric PIDs from getSchema():
 const values = await client.getPropertyValues({
   eids: JSON.stringify(['00416400910670863867']),
-  pids: JSON.stringify(['name', 'country', 'industry']),
+  pids: JSON.stringify([8, 313]),  // 8=name, 313=country (from schema)
 });
 ```
 

package/rules/architecture.mdc

@@ -99,21 +99,26 @@ Only add navigation if the app genuinely needs multiple views. Choose the patter
 
 ## New Page Checklist
 
-- [ ] Created a design doc in `design/` (copy `design/feature_template.md`)
 - [ ] Page in `pages/` with `<script setup lang="ts">`
 - [ ] Uses Vuetify components and the project's dark theme
 - [ ] Updated `DESIGN.md` with current status
+- [ ] (Optional) Created a design doc in `design/` for complex features
 
-## Server Routes
+Design docs in `design/` are most useful for incremental feature work where
+you need to plan, track decisions, and coordinate across multiple changes.
+For initial app builds via `/build_my_app`, skip the per-page design docs —
+they add friction without value when building the whole app at once. Start
+using them later when adding features to an established app.
 
-Nitro server routes live in `server/api/` and deploy with the app to Vercel. They're auto-registered by Nuxt:
+## Server Routes
 
-```
-server/api/my-data/fetch.get.ts   →   GET /api/my-data/fetch
-server/api/my-data/submit.post.ts →  POST /api/my-data/submit
-```
+Nitro server routes live in `server/api/` and deploy with the app to Vercel.
+Use server routes when you need to proxy external APIs (avoid CORS), call
+the Elemental API server-side, or keep secrets off the client. Call them
+from client code with `$fetch('/api/my-data/fetch')`.
 
-Call them from client code with `$fetch('/api/my-data/fetch')`. See the `server` cursor rule for patterns. Use server routes when you need to proxy external APIs (avoid CORS) or keep secrets off the client.
+See the `server` rule for file-routing conventions, Neon Postgres patterns,
+and server-side Elemental API access via `useRuntimeConfig()`.
 
 ## Beyond the UI: Agents, MCP Servers, and Server Routes
 

package/rules/cookbook.mdc

@@ -9,7 +9,9 @@ Copy-paste patterns using the project's actual composables and Vuetify component
 
 ## 1. Entity Search Page
 
-Search for entities by name and display results.
+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>
@@ -389,6 +391,9 @@ Two-column layout with selectable list and detail panel.
 ## 7. 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
@@ -487,12 +492,12 @@ relationship PID. See the `api` rule for the two-layer architecture.
                 return;
             }
 
-            const res = await client.getPropertyValues({
+            const propRes = await client.getPropertyValues({
                 eids: JSON.stringify([orgNeid]),
                 pids: JSON.stringify([filedPid]),
             });
 
-            const docNeids = (res.values ?? []).map((v: any) =>
+            const docNeids = (propRes.values ?? []).map((v: any) =>
                 String(v.value).padStart(20, '0'),
             );
 

package/rules/design.mdc

@@ -40,6 +40,8 @@ Feature docs are used as working documents to help a user and agent collaborate
 
 When a user starts working on implementing a change, if they are using a feature doc, read the relevant feature doc before starting work. Then update the feature doc with every change you make. Be sure to create checklists as you plan work, and check off the checklists as the work is completed. Document design choices and open questions.
 
-If the user is implementing a change that has no feature doc, encourage them to work with you to create one before starting work. A new feature doc should be created by copying `design/feature_template.md` to a new file in `design`, giving it an appropriate name, and editing it from there. 
+If the user is implementing a change that has no feature doc, encourage them to work with you to create one before starting work. A new feature doc should be created by copying `design/feature_template.md` to a new file in `design`, giving it an appropriate name, and editing it from there.
+
+**Exception for initial app builds:** When building a new app from scratch via `/build_my_app`, skip per-page feature docs. They add overhead during greenfield builds where the entire app is being created at once. Start using feature docs once the initial app is built and you're iterating on individual features.
 
 It is a good practice to close out one feature doc and start a new one as the focus of the work shifts. It is acceptable to be working with multiple feature docs at once, if the user is working on multiple unconnected or loosely connected features. The sections of the feature doc are flexible and you should add or remove sections to fit the needs of the project.

package/rules/mcp-servers.mdc

@@ -102,7 +102,7 @@ Once deployed, agents can connect to your MCP server. Add the Cloud Run URL to y
 
 - One server per data domain or external service
 - Keep tools focused and well-documented
-- Return structured data (dicts/lists), not raw strings
+- Return structured data (dicts/lists), not raw strings — MCP handles serialization via the protocol. (This differs from ADK agent tools, which should return formatted strings because the LLM reads tool output directly — see the `agents` rule.)
 - Handle errors by returning descriptive error messages in the response
 - Use environment variables for API keys and configuration (never hardcode secrets)
 - For secrets, use GCP Secret Manager and access at runtime

package/rules/pref.mdc

@@ -46,13 +46,25 @@ The backing store auto-initializes on first use — no need to call
 
 ## Local Development
 
-KV credentials are only available in deployed builds (Vercel auto-injects
-them at runtime). In local dev, `getRedis()` returns `null` and KV routes
-return `undefined` for reads and silently skip writes. `Pref<T>` still
-works with its default value but won't persist across page refreshes.
+KV credentials (`KV_REST_API_URL`, `KV_REST_API_TOKEN`) are only available
+in deployed builds (Vercel auto-injects them at runtime). In local dev,
+`getRedis()` returns `null` and KV routes return `undefined` for reads and
+silently skip writes. `Pref<T>` still works with its default value but
+won't persist across page refreshes.
 
 This is expected — push to `main` and test persistence on the deployed build.
 
+For local-only persistence, use `localStorage` as a lightweight alternative:
+
+```typescript
+const saved = localStorage.getItem('watchlist');
+const watchlist = ref<string[]>(saved ? JSON.parse(saved) : []);
+watch(watchlist, (val) => localStorage.setItem('watchlist', JSON.stringify(val)), { deep: true });
+```
+
+Use `Pref<T>` for production persistence and `localStorage` for local-only
+development when KV isn't available.
+
 **Auth dependency:** All `/api/kv/*` routes call `unsealCookie(event)` to
 identify the user. In dev mode (no `NUXT_PUBLIC_AUTH0_CLIENT_SECRET` set),
 this is bypassed automatically using `NUXT_PUBLIC_USER_NAME`. If you set an
@@ -107,22 +119,6 @@ function useMyFeaturePrefs() {
 - **Key format**: `prefs:users:{userId}:apps:{appId}:settings:general`
   (doc-style paths converted to colon-separated Redis keys)
 
-## Local Development Without KV
-
-When KV credentials (`KV_REST_API_URL`, `KV_REST_API_TOKEN`) aren't configured,
-`Pref<T>` still works with its default value but won't persist across page
-refreshes. For local dev, use `localStorage` directly as a lightweight
-alternative:
-
-```typescript
-const saved = localStorage.getItem('watchlist');
-const watchlist = ref<string[]>(saved ? JSON.parse(saved) : []);
-watch(watchlist, (val) => localStorage.setItem('watchlist', JSON.stringify(val)), { deep: true });
-```
-
-Use `Pref<T>` for production persistence and `localStorage` for local-only
-development when KV isn't available.
-
 ## Scope Guidance
 
 | App-specific | Global |

package/rules/server.mdc

@@ -158,6 +158,110 @@ 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.
+
+## Neon Postgres: Handle Missing Tables in GET Routes
+
+Tables created by POST/setup routes won't exist on a fresh deployment.
+**Every GET route that queries a table must handle the case where the table
+doesn't exist yet.** Without this, fresh deploys will 500 on every page load
+until the setup route runs.
+
+```typescript
+export default defineEventHandler(async () => {
+  const sql = getDb();
+  if (!sql) throw createError({ statusCode: 503, statusMessage: 'Database not configured' });
+
+  try {
+    const rows = await sql`SELECT * FROM companies ORDER BY updated_at DESC`;
+    return rows;
+  } catch (err: any) {
+    if (err.message?.includes('does not exist')) {
+      return [];
+    }
+    throw err;
+  }
+});
+```
+
+Alternatively, ensure tables exist before querying by calling
+`CREATE TABLE IF NOT EXISTS` at the top of each GET route, or by calling a
+shared setup function:
+
+```typescript
+// server/utils/ensure-tables.ts
+import { getDb } from '~/server/utils/neon';
+
+let _initialized = false;
+
+export async function ensureTables() {
+  if (_initialized) return;
+  const sql = getDb();
+  if (!sql) return;
+
+  await sql`CREATE TABLE IF NOT EXISTS companies (
+    id SERIAL PRIMARY KEY,
+    neid TEXT UNIQUE NOT NULL,
+    name TEXT NOT NULL,
+    data JSONB DEFAULT '{}',
+    updated_at TIMESTAMPTZ DEFAULT NOW()
+  )`;
+
+  _initialized = true;
+}
+```
+
+Then call `await ensureTables()` at the start of any route that reads the
+table. The `_initialized` flag makes it a no-op after the first call within
+the same serverless invocation.
+
 ## Key Differences from Client-Side Code
 
 - Server routes run on the server (Node.js), not in the browser