@yottagraph-app/aether-instructions 1.1.18 → 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.18",
+    "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

@@ -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
@@ -359,3 +384,127 @@ need to track text deltas yourself.
 - 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
 
@@ -82,15 +84,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
@@ -101,28 +106,28 @@ 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 |
 |---|---|---|
 | `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:**
 
 | 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 |
+| `findEntities` | `(body: { expression, limit? })` | Find linked entities via `linked` expression (see `find.md`) |
 
 **Other:**
 
@@ -205,43 +210,82 @@ 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
 > 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']),
+  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([8, 313]),  // 8=name, 313=country (from schema)
 });
 ```
 
-### `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);
@@ -255,64 +299,43 @@ 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.
-
-## Common Entity Relationships
-
-The knowledge graph connects entities through relationship properties
-(`data_nindex` PIDs). These are the most common patterns:
+### Entity Search
 
-| 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 |
+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).
 
-**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.
+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.
 
-**Traversal pattern for non-graph-node types:**
+## Traversing Relationships
 
-```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;
+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.
 
-// 2. Get linked entity IDs via getPropertyValues
-const res = await client.getPropertyValues({
-    eids: JSON.stringify([orgNeid]),
-    pids: JSON.stringify([filedPid]),
-});
+**Two traversal methods:**
 
-// 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/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>
@@ -53,19 +55,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 = [];
@@ -373,10 +391,14 @@ 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:** `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 +452,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');
@@ -454,12 +492,12 @@ NOT supported — use `getPropertyValues` with the relationship PID instead.
                 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.