@yottagraph-app/aether-instructions 1.1.4 → 1.1.5

package/package.json

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

package/rules/agents.mdc

@@ -175,8 +175,62 @@ Chat UI (pages/chat.vue)
 ```
 
 The gateway URL and tenant ID come from `broadchurch.yaml` (injected as
-`NUXT_PUBLIC_GATEWAY_URL` and `NUXT_PUBLIC_TENANT_ORG_ID`). The chat page
-discovers available agents from the Portal config endpoint.
+`NUXT_PUBLIC_GATEWAY_URL` and `NUXT_PUBLIC_TENANT_ORG_ID`).
+
+### Agent Discovery
+
+The chat page discovers deployed agents by fetching the tenant config:
+
+```
+GET {NUXT_PUBLIC_GATEWAY_URL}/api/config/{NUXT_PUBLIC_TENANT_ORG_ID}
+```
+
+The response includes an `agents` array:
+
+```json
+{
+  "agents": [
+    { "name": "filing_analyst", "display_name": "Filing Analyst", "engine_id": "1234567890" },
+    { "name": "research_bot", "display_name": "Research Bot", "engine_id": "0987654321" }
+  ],
+  "features": { "chat": true, ... },
+  ...
+}
+```
+
+Each agent entry has:
+
+| Field | Type | Description |
+|---|---|---|
+| `name` | `string` | Agent directory name (e.g. `filing_analyst`) |
+| `display_name` | `string` | Human-readable name for the UI |
+| `engine_id` | `string` | Vertex AI Agent Engine resource ID — used as `{agentId}` in query/stream URLs |
+
+The `engine_id` is the key value — it becomes the `{agentId}` path
+parameter in `POST /api/agents/{tenantId}/{agentId}/query`.
+
+**How agents get populated:** The portal discovers agents from two sources:
+1. **Firestore** — agents registered by the deploy workflow (`deploy-agent.yml`
+   calls `POST /api/agents/{tenantId}` to register)
+2. **Agent Engine API** — the portal also queries Vertex AI for reasoning
+   engines whose display name starts with the project name (e.g.
+   `my-project--filing_analyst`), catching agents that were deployed but
+   not yet registered
+
+Both sources are merged and deduplicated by name. If the config endpoint
+returns an empty `agents` array, no agents have been deployed yet.
+
+Use `useTenantConfig()` to fetch this config from Vue code:
+
+```typescript
+import { useTenantConfig } from '~/composables/useTenantConfig';
+
+const { config, fetchConfig } = useTenantConfig();
+await fetchConfig();
+
+const agents = config.value?.agents ?? [];
+const agentId = agents[0]?.engine_id; // use as {agentId} in query URLs
+```
 
 ### Gateway Request
 

package/rules/api.mdc

@@ -20,7 +20,9 @@ For full endpoint documentation, read the **elemental-api skill** in
 `skills/elemental-api/`. Start with `SKILL.md`, then `overview.md`.
 These files are copied from `@yottagraph-app/elemental-api-skill` during
 `npm install` (postinstall step) — if the directory is empty, run
-`npm install` first.
+`npm install` first. The skill docs contain detailed response shapes and
+edge cases that go beyond this rule's quick reference — **run `npm install`
+early** to make them available during initial exploration.
 
 Key files:
 - `entities.md` — entity search, details, and properties
@@ -153,6 +155,28 @@ const flavors = res.schema?.flavors ?? (res as any).flavors ?? [];
 The `(res as any).properties` fallback is there in case the API is ever
 fixed to match the types. Use this pattern every time.
 
+### `getNamedEntityReport()` response is nested under `.report`
+
+Same problem as `getSchema()`. The TypeScript types suggest entity fields
+(`name`, `aliases`, `type`) exist at the top level. **They don't.** The
+API wraps them in a `.report` container. The generated client does NOT
+unwrap this automatically.
+
+```typescript
+// WRONG — name will be undefined:
+const res = await client.getNamedEntityReport(neid);
+const name = res.name; // undefined!
+
+// CORRECT — always access through .report:
+const res = await client.getNamedEntityReport(neid);
+const name = res.report?.name ?? (res as any).name ?? neid;
+const aliases = res.report?.aliases ?? (res as any).aliases ?? [];
+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.
+
 > **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
@@ -175,6 +199,17 @@ 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
@@ -236,9 +271,12 @@ 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'));
 
-// 4. Get details for each linked entity
+// 4. Get details for each linked entity (response is nested under .report)
 const reports = await Promise.all(
-    docNeids.map((neid: string) => client.getNamedEntityReport(neid)),
+    docNeids.map(async (neid: string) => {
+        const r = await client.getNamedEntityReport(neid);
+        return r.report ?? r;
+    }),
 );
 ```
 

package/rules/architecture.mdc

@@ -133,17 +133,21 @@ Tenant-specific configuration generated during provisioning. Contains GCP projec
 
 ## Built-in Pages
 
-These pages ship with the template and can be kept, modified, or removed
-based on the app's needs:
+Recent template versions include these pages. They can be kept, modified,
+or removed based on the app's needs:
 
-- `pages/chat.vue` -- Agent chat UI. Talks to deployed ADK agents through
-  the Portal Gateway with streaming support. Keep if the app uses AI agents.
+- `pages/chat.vue` -- Agent chat UI. Uses `useAgentChat()` and
+  `useTenantConfig()` to discover deployed agents and stream responses
+  through the Portal Gateway. Keep if the app uses AI agents.
 - `pages/mcp.vue` -- MCP Explorer. Browse and test MCP server tools. Keep
   if the app uses MCP servers.
 - `pages/entity-lookup.vue` -- Entity search tool. Useful for looking up
   NEIDs. Keep or remove based on the app.
 
-If any of these pages are missing from your project, your project may have
-been created from an older template version. Copy them from the latest
-aether-dev source or run `/update_instructions` to check for updates.
+**If these pages are missing** from your project, your project was created
+from an older template version. Create them from scratch — they're
+straightforward Vuetify pages. The key composables (`useAgentChat`,
+`useTenantConfig`) are included in all template versions and provide the
+connection logic. See the `agents` cursor rule for the gateway endpoints
+and response formats these pages use.
 

package/rules/cookbook.mdc

@@ -467,7 +467,7 @@ NOT supported — use `getPropertyValues` with the relationship PID instead.
                 docNeids.map(async (neid: string) => {
                     try {
                         const r = await client.getNamedEntityReport(neid);
-                        return r.name || neid;
+                        return r.report?.name ?? (r as any).name ?? neid;
                     } catch {
                         return neid;
                     }