@yottagraph-app/aether-instructions 1.1.4 → 1.1.6

package/commands/build_my_app.md

@@ -73,8 +73,8 @@ Key capabilities:
 - **Query Server / Elemental API** -- the primary data source. Use `useElementalClient()` from `@yottagraph-app/elemental-api/client`. See the `api` rule.
 - **KV storage** -- always available for preferences and lightweight data (see `pref` rule)
 - **Supabase** -- check if `NUXT_PUBLIC_SUPABASE_URL` is in `.env` for database access
-- **AI agent chat** -- `pages/chat.vue` exists for agent interactions
-- **MCP Explorer** -- `pages/mcp.vue` for testing MCP tools
+- **AI agent chat** -- use the `useAgentChat` composable to build a chat UI for deployed agents
+- **MCP servers** -- Lovelace MCP servers may be available (check `.cursor/mcp.json`)
 - **Components** -- Vuetify 3 component library is available
 
 ---
@@ -96,7 +96,7 @@ Plan what you'll build:
 3. What shared logic belongs in `composables/`
 4. What data needs to be persisted (and whether KV or Supabase is appropriate)
 5. Whether the app needs AI agents or MCP servers
-6. Whether to keep, modify, or remove the built-in pages (`chat.vue`, `mcp.vue`, `entity-lookup.vue`)
+6. Whether the app needs an agent chat page (use the `useAgentChat` composable)
 7. Whether `app.vue` needs a sidebar, tabs, or other navigation (and what it should look like)
 
 Present the plan to the user and ask for approval before proceeding.

package/package.json

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

package/rules/agents.mdc

@@ -161,22 +161,76 @@ adk deploy agent_engine \
   agents/<agent-name>/
 ```
 
-## How Agents Reach the Chat UI
+## How Agents Reach the App
 
 Once deployed, the agent is reachable through the Portal Gateway:
 
 ```
-Chat UI (pages/chat.vue)
+App (useAgentChat composable)
   → POST NUXT_PUBLIC_GATEWAY_URL/api/agents/{tenantId}/{agentId}/query
   → Portal Gateway proxies to Vertex AI Agent Engine (streamQuery)
   → Agent runs (may invoke tools, make multiple LLM calls)
   → Gateway collects the ADK event stream, extracts final text
-  → Chat UI displays it
+  → App displays it
 ```
 
 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 app 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;
+    }),
 );
 ```
 
@@ -291,8 +329,8 @@ the servers route through the Portal Gateway proxy (no credentials needed).
 For local development without a gateway, the servers require an
 `AUTH0_M2M_DEV_TOKEN` environment variable.
 
-The MCP Explorer page (`pages/mcp.vue`) also connects to these servers
-through the Portal Gateway for interactive exploration in the browser.
+These servers are also accessible from the browser through the Portal
+Gateway, so you can build MCP tool exploration UIs if needed.
 
 ### When MCP Servers Are Available
 

package/rules/architecture.mdc

@@ -121,7 +121,7 @@ Aether apps are more than just a Nuxt SPA. The project contains three additional
 
 ### `agents/` -- ADK Agents (Python)
 
-Each subdirectory is a self-contained Python agent that deploys to Vertex AI Agent Engine. See the `agents` cursor rule for development patterns. Agents are deployed via the Broadchurch Portal UI or the `/deploy_agent` Cursor command, both of which trigger `deploy-agent.yml`. Once deployed, the chat UI at `pages/chat.vue` talks to agents through the Portal Gateway (`NUXT_PUBLIC_GATEWAY_URL`).
+Each subdirectory is a self-contained Python agent that deploys to Vertex AI Agent Engine. See the `agents` cursor rule for development patterns. Agents are deployed via the Broadchurch Portal UI or the `/deploy_agent` Cursor command, both of which trigger `deploy-agent.yml`. Once deployed, agents are reachable through the Portal Gateway (`NUXT_PUBLIC_GATEWAY_URL`). Use the `useAgentChat` composable to build a chat UI that talks to them.
 
 ### `mcp-servers/` -- MCP Servers (Python)
 
@@ -131,19 +131,19 @@ Each subdirectory is a FastMCP server that deploys to Cloud Run. See the `mcp-se
 
 Tenant-specific configuration generated during provisioning. Contains GCP project, org ID, service account, gateway URL, and query server URL. Read by deploy commands and GitHub Actions workflows. Don't edit manually.
 
-## Built-in Pages
-
-These pages ship with the template and 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/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.
+## Available Composables for Platform Features
+
+The template ships composables for interacting with the Lovelace platform.
+Use these to build whatever UI fits the app:
+
+- **`useAgentChat()`** -- Send messages to deployed ADK agents through the
+  Portal Gateway. Handles streaming, session management, and response
+  parsing. See the `agents` cursor rule for gateway endpoints and response
+  formats.
+- **`useTenantConfig()`** -- Fetch the tenant's runtime config (deployed
+  agents, feature flags, MCP servers) from the Portal Gateway.
+- **`useElementalClient()`** -- Query Server client for entities, news,
+  filings, etc. See the `api` rule.
+- **`usePrefsStore()` / `Pref<T>`** -- KV-backed user preferences. See
+  the `pref` rule.
 

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;
                     }

package/rules/design.mdc

@@ -15,16 +15,13 @@ The sections of the design doc are flexible and you should add or remove section
 
 # Starter App is a Placeholder
 
-The default UI that ships with this template (home page, chat page, entity
-lookup) is **placeholder content** meant to demonstrate capabilities. When
-building from a project brief or user request, feel free to:
+The default UI that ships with this template is **placeholder content**.
+When building from a project brief or user request, feel free to:
 
 - **Replace** `pages/index.vue` with the app's real home page
-- **Remove** example pages (`entity-lookup.vue`, `chat.vue`, `mcp.vue`)
-  if the app doesn't need them
+- **Remove** any pages that don't fit the app
 - **Restructure** the navigation, layout, and branding entirely
-- **Keep** only the infrastructure: `composables/`, `server/api/kv/`,
-  `agents/`, and `pages/chat.vue` (if the app uses agent chat)
+- **Keep** the infrastructure: `composables/`, `server/api/kv/`, `agents/`
 
 Do NOT treat the existing UI as something to preserve. Build what the
 user described, using the template's infrastructure and patterns but not