@yottagraph-app/aether-instructions 1.1.16 → 1.1.18

package/package.json

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

package/rules/api.mdc

@@ -26,6 +26,52 @@ the directory is missing, run `/update_instructions` to install it.
 
 For Lovelace **entity types, properties, relationships, and per-source schemas** (EDGAR, FRED, FDIC, etc.), read the **data-model skill** in `.cursor/skills/data-model/`. Start with `SKILL.md`, then `overview.md` and the source-specific folders. Both skills are distributed via `@yottagraph-app/aether-instructions` and installed during project init.
 
+## 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.
+
+### How to test
+
+The gateway proxy authenticates on your behalf — no Auth0 tokens needed.
+Read `broadchurch.yaml` for the three values you need:
+
+| YAML path | Purpose |
+|---|---|
+| `gateway.url` | Portal Gateway base URL |
+| `tenant.org_id` | Your tenant ID (path segment) |
+| `gateway.qs_api_key` | API key (sent as `X-Api-Key` header) |
+
+Build the request URL as `{gateway.url}/api/qs/{tenant.org_id}/{endpoint}`
+and include the header `X-Api-Key: {gateway.qs_api_key}`.
+
+### Example calls
+
+```bash
+# Variables — read these from broadchurch.yaml
+GW="https://broadchurch-portal-194773164895.us-central1.run.app"
+ORG="org_abc123"
+KEY="qs_..."
+
+# Search for an entity by name
+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}'
+
+# Get entity properties (form-encoded)
+curl -s -X POST "$GW/api/qs/$ORG/elemental/entities/properties" \
+  -H "X-Api-Key: $KEY" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  --data-urlencode 'eids=["00416400910670863867"]' \
+  --data-urlencode 'pids=[8,313]' | jq .
+```
+
+`/elemental/find` and `/elemental/entities/properties` require
+`application/x-www-form-urlencoded` with JSON-stringified parameter values.
+All other endpoints accept `application/json`.
+
 ## Client Usage
 
 All API calls go through `useElementalClient()` from `@yottagraph-app/elemental-api/client`.
@@ -78,18 +124,6 @@ All methods return data directly and throw on non-2xx responses.
 | `getNeighborhood` | `(centerNeid, params?)` | Neighboring entities |
 | `getGraphLayout` | `(centerNeid, params?)` | Graph layout for visualization |
 
-**News, events, and sentiment:**
-
-| Method | Signature | Purpose |
-|---|---|---|
-| `getArticle` | `(artid: string)` | Article by ID |
-| `getArticleText` | `(artid: string)` | Article full text |
-| `getEvent` | `(eveid: string)` | Event by ID |
-| `getEventsForEntity` | `(params: { neid, startTime?, endTime? })` | Events involving an entity |
-| `getMentions` | `(params: { neid, startTime?, endTime? })` | Mention codes for entities |
-| `getMentionCounts` | `(params: { neid, ... })` | Bucketed mention counts |
-| `getNamedEntitySentiment` | `(neid: string)` | Sentiment for an entity |
-
 **Other:**
 
 | Method | Signature | Purpose |
@@ -216,7 +250,7 @@ const res = await client.getPropertyValues({
     eids: JSON.stringify([orgNeid]),
     pids: JSON.stringify([filedPid]),
 });
-const docNeids = res.values.map((v) => String(v.value).padStart(20, '0'));
+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.
@@ -263,7 +297,7 @@ const res = await client.getPropertyValues({
 });
 
 // 3. Pad IDs to 20 chars to form valid NEIDs
-const docNeids = res.values.map((v: any) => String(v.value).padStart(20, '0'));
+const docNeids = (res.values ?? []).map((v: any) => String(v.value).padStart(20, '0'));
 
 // 4. Get details for each linked entity (response is nested under .report)
 const reports = await Promise.all(

package/rules/cookbook.mdc

@@ -459,7 +459,7 @@ NOT supported — use `getPropertyValues` with the relationship PID instead.
                 pids: JSON.stringify([filedPid]),
             });
 
-            const docNeids = res.values.map((v: any) =>
+            const docNeids = (res.values ?? []).map((v: any) =>
                 String(v.value).padStart(20, '0'),
             );
 

package/rules/pref.mdc

@@ -46,19 +46,23 @@ The backing store auto-initializes on first use — no need to call
 
 ## Local Development
 
-When KV credentials (`KV_REST_API_URL`, `KV_REST_API_TOKEN`) are not set
-(e.g. local dev without Vercel env vars), the KV server routes return
-`undefined` for reads and silently skip writes. Prefs will work with
-their default values but won't persist across page refreshes.
+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.
 
-For full local persistence, copy the KV credentials from your Vercel
-project settings into your local `.env` file (or use the Portal's
-"Get .env file" feature).
+This is expected — push to `main` and test persistence on the deployed build.
+
+**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
+Auth0 client secret without proper cookie setup, KV writes will silently
+no-op.
 
 ## Direct API Alternative
 
 If you prefer not to use the `Pref<T>` class, you can call the KV
-routes directly:
+routes directly from client-side code:
 
 ```typescript
 // Read
@@ -73,6 +77,11 @@ await $fetch('/api/kv/write', {
 });
 ```
 
+These routes require the browser's auth cookie — they work from client-side
+`$fetch` calls but not from server routes or external scripts. For
+server-to-server KV access, use `getRedis()` from `server/utils/redis.ts`
+directly.
+
 ## Feature-Scoped Preferences
 
 Features should namespace preferences under the app's prefix:

package/rules/server.mdc

@@ -68,6 +68,9 @@ if (redis) {
 
 Returns `null` if KV is not configured (env vars missing). Always check.
 
+For client-side preferences, use `usePrefsStore()` and `Pref<T>` instead of
+calling KV routes directly — see the `pref` rule.
+
 ## Neon Postgres
 
 If `DATABASE_URL` is in `.env`, Postgres is ready to use. The project init
@@ -81,6 +84,12 @@ automatically when a Neon database is detected.
 - If either is missing, the project wasn't provisioned with Neon (add it
   from the Broadchurch Portal, then re-run `node init-project.js`)
 
+**Local dev:** `DATABASE_URL` is not yet available for local development.
+`getDb()` returns `null` when the credential is missing or invalid. Write
+your server routes to handle this gracefully (return a "database not
+configured" error or empty state). Push to `main` to test with a real
+database on the deployed build, where credentials are auto-injected.
+
 ### Usage
 
 `server/utils/neon.ts` exports `getDb()` (same lazy-init pattern as
@@ -103,6 +112,25 @@ The Neon driver uses tagged template literals for automatic SQL injection
 protection — `await sql\`SELECT * FROM notes WHERE id = ${id}\`` is safe.
 No ORM, no query builder, no connection pool setup needed.
 
+### Creating tables
+
+There is no migrations framework. Use `CREATE TABLE IF NOT EXISTS` directly
+in a setup route or at the top of a route that needs the table:
+
+```typescript
+const sql = getDb()!;
+await sql`CREATE TABLE IF NOT EXISTS notes (
+  id SERIAL PRIMARY KEY,
+  content TEXT NOT NULL,
+  created_at TIMESTAMPTZ DEFAULT NOW()
+)`;
+```
+
+For simple apps, putting the `CREATE TABLE IF NOT EXISTS` in each route that
+uses the table is fine — it's a no-op after the first call. For more complex
+schemas, create a `server/api/db/setup.post.ts` route that initializes all
+tables.
+
 ### If `server/utils/neon.ts` doesn't exist
 
 Create it manually (or re-run init):
@@ -136,3 +164,6 @@ export function getDb(): NeonQueryFunction | null {
 - They have access to Redis, Neon Postgres, secrets, and server-only APIs
 - They do NOT have access to Vue composables, Vuetify, or any client-side code
 - Use `defineEventHandler`, not Vue component patterns
+
+See `architecture` rule for the full data architecture overview, `pref` rule
+for client-side KV preferences.

package/skills/test-api-queries/SKILL.md

@@ -1,63 +0,0 @@
----
-name: test-api-queries
-description: Test Elemental API queries before integrating into app code. Use when writing code that calls the query server.
----
-
-# Test API Queries
-
-**When writing code that calls the Query Server, test queries with this CLI tool before integrating them into app code.**
-
-This prevents wasted iteration cycles from incorrect assumptions about API responses.
-
-## Workflow
-
-1. **Test the query** using the CLI tool below
-2. **Verify the response** matches what you expect
-3. **Then write the app code** with confidence
-
-## CLI Tool
-
-Location: `~/.cursor/skills/test-api-queries/query-api.js`
-
-### Requirements
-
-The CLI reads these from the project's `.env` file or shell environment:
-
-- `AUTH0_M2M_DEV_TOKEN` - Auth0 M2M dev token for API access
-- `NUXT_PUBLIC_QUERY_SERVER_ADDRESS` - Query server URL
-
-**Before using this tool**, check that both variables are set in the project's `.env` file. If either is missing or empty, add them to `.env` (see `.env.example` for the format). Tell the user to ask the engineering team for the token value if they don't have it.
-
-### Usage
-
-```bash
-node ~/.cursor/skills/test-api-queries/query-api.js <METHOD> <ENDPOINT> [JSON_PARAMS]
-```
-
-### Examples
-
-```bash
-# Search for entities by name
-node ~/.cursor/skills/test-api-queries/query-api.js POST /entities/search \
-  '{"queries":[{"queryId":1,"query":"Apple"}],"maxResults":3}'
-
-# Get entity details by ID
-node ~/.cursor/skills/test-api-queries/query-api.js GET /entities/00416400910670863867
-
-# Find entities by type
-node ~/.cursor/skills/test-api-queries/query-api.js POST /elemental/find \
-  '{"expression":{"type":"is_type","is_type":{"fid":10}},"limit":5}'
-
-# Find entities with a specific property
-node ~/.cursor/skills/test-api-queries/query-api.js POST /elemental/find \
-  '{"expression":{"type":"comparison","comparison":{"operator":"has_value","pid":313}},"limit":10}'
-
-# Get entity properties
-node ~/.cursor/skills/test-api-queries/query-api.js POST /elemental/entities/properties \
-  '{"eids":["00416400910670863867"],"pids":[8,313]}'
-```
-
-### Notes
-
-- Run from the project directory so the `.env` file is found
-- `/elemental/find` and `/elemental/entities/properties` require form-encoded bodies—the tool handles this automatically

package/skills/test-api-queries/query-api.js

@@ -1,172 +0,0 @@
-#!/usr/bin/env node
-/**
- * Simple CLI tool to query the Elemental API.
- *
- * Auth: set AUTH0_M2M_DEV_TOKEN as an env var or in your .env file.
- * Server: set NUXT_PUBLIC_QUERY_SERVER_ADDRESS in your .env file.
- */
-
-const fs = require('fs');
-const path = require('path');
-
-const FORM_ENCODED_ENDPOINTS = ['/elemental/find', '/elemental/entities/properties'];
-
-function loadEnvFile() {
-    // Try current working directory first (project .env), then script directory
-    const envPaths = [path.join(process.cwd(), '.env'), path.join(__dirname, '.env')];
-
-    for (const envPath of envPaths) {
-        try {
-            const contents = fs.readFileSync(envPath, 'utf8');
-            for (const line of contents.split('\n')) {
-                const trimmed = line.trim();
-                if (!trimmed || trimmed.startsWith('#')) continue;
-                const eqIndex = trimmed.indexOf('=');
-                if (eqIndex === -1) continue;
-                const key = trimmed.slice(0, eqIndex).trim();
-                const value = trimmed.slice(eqIndex + 1).trim();
-                if (!process.env[key]) {
-                    process.env[key] = value;
-                }
-            }
-            return; // Stop after first successful load
-        } catch {
-            // Try next path
-        }
-    }
-}
-
-function requiresFormEncoding(endpoint) {
-    return FORM_ENCODED_ENDPOINTS.some((e) => endpoint.startsWith(e));
-}
-
-function buildFormBody(endpoint, params) {
-    const formParams = new URLSearchParams();
-    for (const [key, value] of Object.entries(params)) {
-        if (typeof value === 'object') {
-            formParams.append(key, JSON.stringify(value));
-        } else {
-            formParams.append(key, String(value));
-        }
-    }
-    return formParams.toString();
-}
-
-async function main() {
-    loadEnvFile();
-
-    const args = process.argv.slice(2);
-
-    if (args.length < 2 || args[0] === '--help' || args[0] === '-h') {
-        console.log(`
-Elemental API Query Tool
-
-Usage:
-  node query-api.js <METHOD> <ENDPOINT> [JSON_PARAMS]
-
-Examples:
-  # Search for entities (JSON body)
-  node query-api.js POST /entities/search '{"queries":[{"queryId":1,"query":"Apple"}],"maxResults":3}'
-
-  # Get entity details
-  node query-api.js GET /entities/00416400910670863867
-
-  # Find entities by expression (auto form-encoded)
-  node query-api.js POST /elemental/find '{"expression":{"type":"is_type","is_type":{"fid":10}},"limit":5}'
-
-  # Find entities with a property value
-  node query-api.js POST /elemental/find '{"expression":{"type":"comparison","comparison":{"operator":"has_value","pid":313}},"limit":10}'
-
-  # Get entity properties (auto form-encoded)
-  node query-api.js POST /elemental/entities/properties '{"eids":["00416400910670863867"],"pids":[8,313]}'
-
-Environment variables (required):
-  AUTH0_M2M_DEV_TOKEN                Bearer token for API auth
-  NUXT_PUBLIC_QUERY_SERVER_ADDRESS     Query server URL (e.g. https://query.news.prod.g.lovelace.ai)
-
-Setup:
-  1. Get a dev token from your team
-  2. Add AUTH0_M2M_DEV_TOKEN to your .env file or export in your shell
-     (NUXT_PUBLIC_QUERY_SERVER_ADDRESS should already be in your .env from project init)
-
-Note: /elemental/find and /elemental/entities/properties require form-encoded bodies.
-      This tool automatically handles the encoding for these endpoints.
-`);
-        process.exit(0);
-    }
-
-    const [method, endpoint, jsonParams] = args;
-
-    const token = process.env.AUTH0_M2M_DEV_TOKEN;
-    if (!token) {
-        console.error('Error: AUTH0_M2M_DEV_TOKEN is not set.');
-        console.error('Add it to your .env file or export it in your shell.');
-        console.error('Run: node query-api.js --help');
-        process.exit(1);
-    }
-
-    let params = {};
-    if (jsonParams) {
-        try {
-            params = JSON.parse(jsonParams);
-        } catch (err) {
-            console.error('Error: Invalid JSON parameters');
-            console.error(err.message);
-            process.exit(1);
-        }
-    }
-
-    const server = process.env.NUXT_PUBLIC_QUERY_SERVER_ADDRESS;
-    if (!server) {
-        console.error('Error: NUXT_PUBLIC_QUERY_SERVER_ADDRESS is not set.');
-        console.error('Add it to your .env file or export it in your shell.');
-        console.error('Run: node query-api.js --help');
-        process.exit(1);
-    }
-
-    const normalizedEndpoint = endpoint.startsWith('/') ? endpoint : '/' + endpoint;
-    let url = `${server}${normalizedEndpoint}`;
-
-    const useFormEncoding = requiresFormEncoding(normalizedEndpoint);
-    const fetchOptions = {
-        method: method.toUpperCase(),
-        headers: {
-            Authorization: `Bearer ${token}`,
-            'Content-Type': useFormEncoding
-                ? 'application/x-www-form-urlencoded'
-                : 'application/json',
-            Accept: 'application/json',
-        },
-    };
-
-    if (method.toUpperCase() === 'GET' && Object.keys(params).length > 0) {
-        const queryString = new URLSearchParams(params).toString();
-        url = `${url}?${queryString}`;
-    } else if (method.toUpperCase() !== 'GET' && Object.keys(params).length > 0) {
-        if (useFormEncoding) {
-            fetchOptions.body = buildFormBody(normalizedEndpoint, params);
-        } else {
-            fetchOptions.body = JSON.stringify(params);
-        }
-    }
-
-    console.error(`\n📡 ${method.toUpperCase()} ${url}\n`);
-
-    try {
-        const response = await fetch(url, fetchOptions);
-        const data = await response.json();
-
-        if (!response.ok) {
-            console.error(`❌ Error ${response.status}: ${response.statusText}`);
-        } else {
-            console.error(`✅ Success (${response.status})\n`);
-        }
-
-        console.log(JSON.stringify(data, null, 2));
-    } catch (err) {
-        console.error('❌ Request failed:', err.message);
-        process.exit(1);
-    }
-}
-
-main();