@yottagraph-app/aether-instructions 1.1.17 → 1.1.19

package/package.json

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

package/rules/agents.mdc

@@ -88,9 +88,9 @@ dev (`agents/` on sys.path → absolute import) and Agent Engine runtime
 
 Key endpoints:
 - `GET /elemental/metadata/schema` — entity types and properties
-- `POST /elemental/find` — search for entities
+- `POST /elemental/find` — search for entities by expression
+- `POST /entities/search` — search for entities by name (batch, scored)
 - `POST /elemental/entities/properties` — get entity property values
-- `GET /entities/lookup?q=<name>` — look up entity by name
 
 Requirements for agents using the Elemental API (add to `requirements.txt`):
 ```
@@ -352,6 +352,31 @@ for await (const { event, data } of readSSE(res)) {
 The `done` event always includes the final extracted text, so you don't
 need to track text deltas yourself.
 
+## useAgentChat Gotcha — Vue Reactivity
+
+When building a chat UI with `useAgentChat`, do NOT hold a local reference
+to a message object after pushing it into the `messages` array. Vue's
+reactivity only tracks mutations made through the reactive Proxy — writes
+to the original plain object are invisible to the template.
+
+```typescript
+// WRONG — local ref bypasses Vue's reactivity, UI won't update:
+const msg: ChatMessage = { id: '...', role: 'agent', text: '', streaming: true };
+messages.value.push(msg);
+msg.text = 'hello';        // data changes, but Vue doesn't know
+msg.streaming = false;     // template still shows typing indicator
+
+// CORRECT — access through the reactive array:
+messages.value.push({ id: '...', role: 'agent', text: '', streaming: true });
+const idx = messages.value.length - 1;
+messages.value[idx].text = 'hello';        // Vue detects this
+messages.value[idx].streaming = false;     // template re-renders
+```
+
+The `useAgentChat` composable uses the correct pattern internally (via an
+`updateAgent()` helper that writes through the array index). If you build a
+custom chat composable or modify `sendMessage`, follow the same approach.
+
 ## Agent Design Guidelines
 
 - Keep agents focused: one agent per domain or task type

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`.
@@ -36,15 +82,18 @@ import { useElementalClient } from '@yottagraph-app/elemental-api/client';
 
 const client = useElementalClient();
 
-const results = await client.getNEID({ entityName: 'Apple', maxResults: 5 });
-const report = await client.getNamedEntityReport(results.neids[0]);
 const schema = await client.getSchema();
+const report = await client.getNamedEntityReport('00508379502570440213');
+const entities = await client.findEntities({
+    expression: JSON.stringify({ type: 'comparison', comparison: { operator: 'string_like', pid: 8, value: 'Apple' } }),
+    limit: 5,
+});
 ```
 
 Types are also imported from the client:
 
 ```typescript
-import type { NamedEntityReport, GetNEIDResponse } from '@yottagraph-app/elemental-api/client';
+import type { NamedEntityReport } from '@yottagraph-app/elemental-api/client';
 ```
 
 ### Client Method Quick Reference
@@ -55,11 +104,15 @@ All methods return data directly and throw on non-2xx responses.
 
 | Method | Signature | Purpose |
 |---|---|---|
-| `getNEID` | `(params: { entityName, maxResults?, includeNames? })` | Lookup entity by name |
 | `findEntities` | `(body: FindEntitiesBody)` | Expression-based search (see `find.md`) |
 | `getNamedEntityReport` | `(neid: string)` | Entity details (name, aliases, type) |
 | `getEntityDetails` | `(neid: string)` | Alias for entity reports |
 
+> **Entity search**: Use `findEntities()` with `string_like` on the name PID
+> for name-based searches, or call `POST /entities/search` directly via
+> `$fetch` for batch name resolution with scored ranking (this endpoint is
+> not wrapped by the generated client).
+
 **Properties and schema:**
 
 | Method | Signature | Purpose |
@@ -72,23 +125,7 @@ All methods return data directly and throw on non-2xx responses.
 
 | Method | Signature | Purpose |
 |---|---|---|
-| `getLinkedEntities` | `(neid, params?: { entity_type?, link_type? })` | Linked entities (person/org/location only) |
-| `getLinks` | `(sourceNeid, targetNeid, params?)` | Links between two specific entities |
-| `getLinkCounts` | `(sourceNeid, targetNeid)` | Link counts between entities |
-| `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 |
+| `findEntities` | `(body: { expression, limit? })` | Find linked entities via `linked` expression (see `find.md`) |
 
 **Other:**
 
@@ -171,6 +208,22 @@ const type = res.report?.type ?? (res as any).type;
 The `(res as any).name` fallback handles the case where the client is
 eventually fixed to unwrap the response.
 
+### Relationship property values need zero-padding to form valid NEIDs
+
+Relationship properties (`data_nindex`) return linked entity IDs as raw
+numbers (e.g. `4926132345040704022`). These must be **zero-padded to 20
+characters** to form valid NEIDs. This is easy to miss and causes silent
+failures — `getNamedEntityReport` returns a 404, `getPropertyValues`
+returns empty results.
+
+```typescript
+// WRONG — raw value is NOT a valid NEID:
+const filingId = res.values[0].value; // "4926132345040704022" (19 chars)
+
+// CORRECT — always pad to 20 characters:
+const filingNeid = String(res.values[0].value).padStart(20, '0'); // "04926132345040704022"
+```
+
 > **WARNING -- `getPropertyValues()` takes JSON-stringified arrays**: The `eids`
 > and `pids` parameters must be JSON-encoded strings, NOT native arrays. The
 > TypeScript type is `string`, not `string[]`. Passing a raw array will silently
@@ -183,31 +236,41 @@ const values = await client.getPropertyValues({
 });
 ```
 
-### `getLinkedEntities` only supports graph node types
-
-`getLinkedEntities(neid, { entity_type: ['document'] })` will fail at
-runtime with _"entity_type document not a valid graph node type"_. The
-`/entities/{neid}/linked` endpoint only supports three entity types:
-**person**, **organization**, **location**. Documents, filings, articles,
-financial instruments, events, and all other types are excluded — even
-though the schema shows relationships like `filed` connecting organizations
-to documents.
-
-**Why?** The knowledge graph has two layers. The **graph layer** models
-first-class entities (people, organizations, locations) as nodes with
-edges between them — this is what `getLinkedEntities` traverses. The
-**property layer** attaches everything else (documents, filings, financial
-instruments, events) as property values on graph nodes. Documents aren't
-"lesser" entities — they're stored differently because they're associated
-with specific graph nodes rather than standing independently in the graph.
-Understanding this distinction helps you generalize: if a target entity
-type doesn't appear in the `getLinkedEntities` response, it's a property-
-layer entity and you need `getPropertyValues` with the relationship PID.
-
-To traverse relationships to non-graph-node types, use `getPropertyValues`
-with the relationship PID instead. Relationship properties (`data_nindex`)
-return linked entity IDs as values. Zero-pad the returned IDs to 20
-characters to form valid NEIDs.
+### Traversing relationships: graph-layer vs property-layer entities
+
+The knowledge graph has two layers:
+
+- **Graph layer** — people, organizations, and locations are first-class
+  nodes with edges between them. Use `findEntities()` with a `linked`
+  expression to traverse these (see `find.md`).
+- **Property layer** — documents, filings, articles, financial instruments,
+  events, and all other types are attached as property values on graph
+  nodes. Use `getPropertyValues()` with the relationship PID to traverse
+  these.
+
+If you need to find people linked to an organization, use `findEntities`
+with a `linked` expression:
+
+```typescript
+const res = await client.findEntities({
+    expression: JSON.stringify({
+        type: 'linked',
+        linked: {
+            to_entity: orgNeid,
+            distance: 1,
+            pids: [isOfficerPid, isDirectorPid, worksAtPid],
+            direction: 'incoming',
+        },
+    }),
+    limit: 50,
+});
+const personNeids = (res as any).eids ?? [];
+```
+
+For non-graph-node types (filings, documents, etc.), use `getPropertyValues`
+with the relationship PID. Relationship properties (`data_nindex`) return
+linked entity IDs as values. Zero-pad the returned IDs to 20 characters
+to form valid NEIDs.
 
 ```typescript
 const pidMap = await getPropertyPidMap(client);
@@ -216,69 +279,48 @@ 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.
 
-### `getNEID()` vs `findEntities()` for entity search
-
-- **`client.getNEID()`** -- simple single-entity lookup by name
-  (`GET /entities/lookup`). Best for resolving one company/person name.
-- **`client.findEntities()`** -- expression-based search
-  (`POST /elemental/find`). Best for filtered searches (by type, property,
-  relationship). See `find.md` for the expression language.
+### Entity Search
 
-## Common Entity Relationships
+Use `client.findEntities()` (`POST /elemental/find`) for entity search.
+It supports filtering by type, property value, and relationship via the
+expression language (see `find.md`). For name-based lookups, use
+`string_like` on the name property (PID 8).
 
-The knowledge graph connects entities through relationship properties
-(`data_nindex` PIDs). These are the most common patterns:
+For batch name resolution with scored ranking, call `POST /entities/search`
+directly via `$fetch` (not on the generated client). See the
+**elemental-api skill** (`entities.md`) for request/response shapes.
 
-| From | PID | To | How to traverse |
-|---|---|---|---|
-| Organization | `filed` | Document (filings) | `getPropertyValues` with the `filed` PID on the org's NEID |
-| Organization | `employs` | Person | `getLinkedEntities` (person is a graph node type) |
-| Person | `employed_by` | Organization | `getLinkedEntities` (organization is a graph node type) |
-| Organization | `headquartered_in` | Location | `getLinkedEntities` (location is a graph node type) |
-| Any entity | `related_to` | Any entity | `getLinkedEntities` for person/org/location; `getPropertyValues` for others |
+## Traversing Relationships
 
-**Key constraint:** `getLinkedEntities` only works for three target types:
-**person**, **organization**, **location**. For documents, filings,
-articles, financial instruments, and events, use `getPropertyValues` with
-the relationship PID. See the cookbook rule (recipe #7) for a full filings
-example.
+Relationships between entities are discoverable via the schema — use
+`getSchema()` to find relationship properties (`data_nindex` type) and
+their PIDs. Do NOT hardcode relationship names or PIDs; they can change
+as the knowledge graph evolves. See the **data-model skill** for
+source-specific schemas.
 
-**Traversal pattern for non-graph-node types:**
+**Two traversal methods:**
 
-```typescript
-// 1. Get the PID for the relationship
-const schema = await client.getSchema();
-const pids = schema.schema?.properties ?? [];
-const filedPid = pids.find((p: any) => p.name === 'filed')?.pid;
-
-// 2. Get linked entity IDs via getPropertyValues
-const res = await client.getPropertyValues({
-    eids: JSON.stringify([orgNeid]),
-    pids: JSON.stringify([filedPid]),
-});
-
-// 3. Pad IDs to 20 chars to form valid NEIDs
-const docNeids = res.values.map((v: any) => String(v.value).padStart(20, '0'));
+- **Graph-layer entities** (person, organization, location): Use
+  `findEntities()` with a `linked` expression. See `find.md`.
+- **Property-layer entities** (documents, filings, articles, etc.): Use
+  `getPropertyValues()` with the relationship PID. Values are entity IDs
+  that must be zero-padded to 20 characters.
 
-// 4. Get details for each linked entity (response is nested under .report)
-const reports = await Promise.all(
-    docNeids.map(async (neid: string) => {
-        const r = await client.getNamedEntityReport(neid);
-        return r.report ?? r;
-    }),
-);
-```
+See the **cookbook** rule (recipe #7) for a full example.
 
 ## Error Handling
 
 ```typescript
 try {
-    const data = await client.getNEID({ entityName: '...' });
+    const data = await client.findEntities({
+        expression: JSON.stringify({ type: 'comparison', comparison: { operator: 'string_like', pid: 8, value: 'Apple' } }),
+        limit: 5,
+    });
 } catch (error) {
     console.error('API Error:', error);
     showError('Failed to load data. Please try again.');

package/rules/cookbook.mdc

@@ -53,19 +53,35 @@ Search for entities by name and display results.
     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 client.getNEID({
-                entityName: query.value.trim(),
-                maxResults: 10,
-                includeNames: true,
+            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,
+                },
             });
-            results.value = res.neids || [];
-            names.value = res.names || [];
+            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 = [];
@@ -374,9 +390,10 @@ Two-column layout with selectable list and detail panel.
 
 Fetch Edgar filings (or any relationship-linked documents) for an organization.
 
-**Important:** `getLinkedEntities` only supports graph node types (person,
-organization, location). Documents, filings, articles, and other types are
-NOT supported — use `getPropertyValues` with the relationship PID instead.
+**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>
@@ -430,22 +447,38 @@ NOT supported — use `getPropertyValues` with the relationship PID instead.
         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 lookup = await client.getNEID({
-                entityName: query.value.trim(),
-                maxResults: 1,
-                includeNames: true,
+            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,
+                },
             });
-            if (!lookup.neids?.length) {
+            const matches = res?.results?.[0]?.matches ?? [];
+            if (!matches.length) {
                 filings.value = [];
                 return;
             }
-            const orgNeid = lookup.neids[0];
+            const orgNeid = matches[0].neid;
 
             const pidMap = await getPropertyPidMap(client);
             const filedPid = pidMap.get('filed');
@@ -459,7 +492,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/skills/data-model/newsdata/schema.yaml

@@ -62,12 +62,14 @@ flavors:
     description: "A news article or press release being processed"
     display_name: "Article"
     mergeability: not_mergeable
+    strong_id_properties: ["newsdata_id"]
     passive: true
 
   - name: "publication"
     description: "A news publication or media outlet identified by its home URL"
     display_name: "Publication"
     mergeability: not_mergeable
+    strong_id_properties: ["homeUrl"]
     passive: true
 
 # =============================================================================
@@ -389,6 +391,14 @@ properties:
     domain_flavors: ["article"]
     passive: true
 
+  - name: "newsdata_id"
+    type: string
+    description: "Unique article identifier from the NewsData API"
+    display_name: "NewsData ID"
+    mergeability: not_mergeable
+    domain_flavors: ["article"]
+    passive: true
+
   - name: "title"
     type: string
     description: "Title of the entity"

package/skills/elemental-api/SKILL.md

@@ -11,17 +11,15 @@ This skill provides documentation for the Lovelace Elemental API, the primary in
 
 Use this skill when you need to:
 - Look up entities (companies, people, organizations) by name or ID
-- Get sentiment analysis for entities over time
-- Find news mentions and articles about entities
-- Explore relationships and connections between entities
-- Retrieve events involving specific entities
+- Search for entities by type, property values, or relationships using the expression language
+- Get entity metadata (types/flavors, properties)
 - Build knowledge graphs of entity networks
 
 ## Quick Start
 
 1. **Find an entity**: Use `entities.md` to look up a company or person by name and get their NEID (Named Entity ID)
-2. **Get information**: Use the NEID to query sentiment, mentions, relationships, or events
-3. **Dive deeper**: Retrieve full article details or explore connected entities
+2. **Get information**: Use the NEID to query entity properties or explore the graph
+3. **Search**: Use `find.md` for expression-based entity searches
 
 ## Files in This Skill
 
@@ -29,9 +27,5 @@ See [overview.md](overview.md) for descriptions of each endpoint category:
 - `entities.md` - Entity search, details, and properties
 - `find.md` - Expression language for searching entities by type, property values, and relationships
 - `schema.md` - Data model: entity types (flavors), properties, and schema endpoints
-- `sentiment.md` - Sentiment analysis
-- `articles.md` - Articles mentioning entities and full article content
-- `events.md` - Events involving entities
-- `relationships.md` - Entity connections
 - `graph.md` - Visual graph generation
 - `server.md` - Server status and health