@yottagraph-app/aether-instructions 1.1.41 → 1.1.43

package/{rules/agents.mdc → skills/aether/agents.md}

@@ -1,13 +1,14 @@
----
-description: Rules for developing ADK agents in the agents/ directory
-globs: agents/**
-alwaysApply: false
----
-
 # Agent Development (Google ADK)
 
 This project supports developing and deploying AI agents alongside the UI. Agents live in the `agents/` directory and deploy to Vertex AI Agent Engine via the `/deploy_agent` command.
 
+## Starter agent
+
+`agents/example_agent/` is a working starter agent that queries the Elemental
+Knowledge Graph. It includes schema discovery, entity search, property lookup,
+and optional MCP server integration. Use it as a starting point — customize the
+instruction, add tools, and follow the patterns described below.
+
 ## Directory Structure
 
 Each agent is a self-contained Python package. **Directory names must use underscores, not hyphens** (ADK uses the directory name as a Python identifier).
@@ -42,14 +43,15 @@ root_agent = Agent(
 ```
 
 Key rules:
+
 - The `agent.py` file MUST export a variable named `root_agent`
 - Tool functions should have detailed docstrings -- the LLM reads these to understand when and how to use each tool
 - Use `google-adk` for the agent framework, `httpx` for HTTP calls
 - Pin dependency versions in `requirements.txt` for reproducible deployments
 
 For agents that call the **Elemental API** (`broadchurch_auth`, endpoints,
-local `ELEMENTAL_*` env vars), see the `agents-data` rule. For agents
-using **Elemental MCP tools**, the `agents-data` rule also covers
+local `ELEMENTAL_*` env vars), see [agents-data.md](agents-data.md) in this skill. For agents
+using **Elemental MCP tools**, [agents-data.md](agents-data.md) also covers
 `McpToolset` wiring — use `StreamableHTTPConnectionParams` (not
 `SseConnectionParams`) and read the `elemental-mcp-patterns` skill for
 response handling patterns.
@@ -153,17 +155,18 @@ The response includes an `agents` array:
 
 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 |
+| 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 `/api/agent/{agentId}/stream` (the local Nitro route) and
 the portal's `/authorize` endpoint.
 
 **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
@@ -219,9 +222,26 @@ A typical stream for an agent that uses a tool:
 
 ```json
 [
-  { "content": { "parts": [{ "functionCall": { "name": "search", "args": {"q": "AAPL 8-K"} } }], "role": "model" } },
-  { "content": { "parts": [{ "functionResponse": { "name": "search", "response": {"results": ["..."]} } }], "role": "tool" } },
-  { "content": { "parts": [{ "text": "Here is the summary of the 8-K filing..." }], "role": "model" } }
+    {
+        "content": {
+            "parts": [{ "functionCall": { "name": "search", "args": { "q": "AAPL 8-K" } } }],
+            "role": "model"
+        }
+    },
+    {
+        "content": {
+            "parts": [
+                { "functionResponse": { "name": "search", "response": { "results": ["..."] } } }
+            ],
+            "role": "tool"
+        }
+    },
+    {
+        "content": {
+            "parts": [{ "text": "Here is the summary of the 8-K filing..." }],
+            "role": "model"
+        }
+    }
 ]
 ```
 
@@ -252,13 +272,13 @@ automatically.
 
 SSE event types:
 
-| Event | Data Shape | Description |
-|---|---|---|
-| `text` | `{ "text": "..." }` | Agent text output (replaces previous text) |
-| `function_call` | `{ "name": "...", "args": {...} }` | Agent is calling a tool |
-| `function_response` | `{ "name": "...", "response": {...} }` | Tool returned a result |
-| `error` | `{ "message": "...", "code": "..." }` | Error during processing (`code` is `PERMISSION_DENIED` for IAM failures) |
-| `done` | `{ "session_id": "...", "text": "..." }` | Stream complete with final text |
+| Event               | Data Shape                               | Description                                                              |
+| ------------------- | ---------------------------------------- | ------------------------------------------------------------------------ |
+| `text`              | `{ "text": "..." }`                      | Agent text output (replaces previous text)                               |
+| `function_call`     | `{ "name": "...", "args": {...} }`       | Agent is calling a tool                                                  |
+| `function_response` | `{ "name": "...", "response": {...} }`   | Tool returned a result                                                   |
+| `error`             | `{ "message": "...", "code": "..." }`    | Error during processing (`code` is `PERMISSION_DENIED` for IAM failures) |
+| `done`              | `{ "session_id": "...", "text": "..." }` | Stream complete with final text                                          |
 
 For custom agent UIs that need streaming, import `readSSE`:
 
@@ -292,14 +312,14 @@ to the original plain object are invisible to the template.
 // 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
+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
+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
@@ -342,7 +362,7 @@ agents (MCP or REST-backed):
 
 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.
+[mcp-servers.md](mcp-servers.md).
 
 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
@@ -465,6 +485,7 @@ Passing a raw `McpToolset` as the agent's only tool source and writing a
 long system prompt does **not** satisfy the spec.
 
 `McpToolset` passthrough means:
+
 - The LLM receives raw JSON responses — no Markdown formatting, no
   human-readable reports
 - No session-state caching — repeated queries for the same entity make

package/{rules/architecture.mdc → skills/aether/architecture.md}

@@ -1,15 +1,10 @@
----
-description: "Project structure, navigation patterns, data architecture, server routes, agents, MCP servers. Read when adding pages, navigation, or server-side functionality."
-alwaysApply: false
----
-
 # Aether Architecture
 
 Aether is an app framework built on Nuxt 3 + Vue 3 + Vuetify 3 + TypeScript. It follows standard Nuxt conventions -- pages in `pages/`, components in `components/`, composables in `composables/`, server routes in `server/api/`.
 
 **Tech stack**: Nuxt 3 (SPA), Vue 3 Composition API (`<script setup>`), Vuetify 3, TypeScript (required), Auth0 (automatic).
 
-**Data source**: This app runs on the Lovelace platform (entities, news, filings, sentiment, relationships, events). See the `data` rule for how your app accesses that data. Do not call external APIs for data the platform provides.
+**Data source**: This app runs on the Lovelace platform (entities, news, filings, sentiment, relationships, events). See [data.md](data.md) in this skill for how your app accesses that data. Do not call external APIs for data the platform provides.
 
 ## Project Structure
 
@@ -26,14 +21,13 @@ mcp-servers/        # MCP servers (Python, deploy to Cloud Run)
 
 ## Data Architecture
 
-| Store | Purpose | When to use |
-|---|---|---|
-| Platform data (Query Server / Postgres per your architecture) | Lovelace knowledge graph or synced local data | See the `data` rule |
-| KV (Upstash Redis) | User preferences, lightweight state | Settings, watchlists, UI state that should persist |
-| Neon Postgres | App-specific relational data | Custom tables, complex queries (if connected — check `DATABASE_URL` in `.env`) |
+| Store                                                         | Purpose                                       | When to use                                                                                     |
+| ------------------------------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| Platform data (Query Server / Postgres per your architecture) | Lovelace knowledge graph or synced local data | See [data.md](data.md)                                                                          |
+| KV (Upstash Redis)                                            | User preferences, lightweight state           | Settings, watchlists, UI state that should persist                                              |
+| Neon Postgres                                                 | App-specific relational data                  | Custom tables, complex queries (if provisioned — see [storage.md](storage.md) for how to check) |
 
-Use `Pref<T>` or `usePrefsStore()` for KV (see `pref` rule).
-Check `.env` for `DATABASE_URL` before using Neon Postgres (see `server` rule).
+See [storage.md](storage.md) for backend selection and server-side usage (both KV and Neon Postgres), plus [pref.md](pref.md) for the client-side `Pref<T>` pattern.
 
 ## Adding Pages
 
@@ -116,8 +110,8 @@ Use server routes when you need to proxy external APIs (avoid CORS), access
 data server-side, or keep secrets off the client. Call them from client code
 with `$fetch('/api/my-data/fetch')`.
 
-See the `server` rule for file-routing conventions and Neon Postgres patterns.
-See `server-data` when calling the platform Query Server from server routes.
+See [server.md](server.md) for file-routing conventions and [storage.md](storage.md) for Neon Postgres patterns.
+See [server-data.md](server-data.md) when calling the platform Query Server from server routes.
 
 ## Beyond the UI: Agents, MCP Servers, and Server Routes
 
@@ -125,7 +119,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`. Use the `useAgentChat` composable to build a chat UI that talks to them.
+Each subdirectory is a self-contained Python agent that deploys to Vertex AI Agent Engine. See [agents.md](agents.md) for development patterns. Agents are deployed via the Broadchurch Portal UI or the `/deploy_agent` Cursor command, both of which trigger `deploy-agent.yml`. Use the `useAgentChat` composable to build a chat UI that talks to them.
 
 **Agent query path:** The app talks to Agent Engine directly — the portal is
 only in the auth path. The flow is:
@@ -143,7 +137,7 @@ project detail page for IAM health status.
 
 ### `mcp-servers/` -- MCP Servers (Python)
 
-Each subdirectory is a FastMCP server that deploys to Cloud Run. See the `mcp-servers` cursor rule. Deployed via Portal UI or `/deploy_mcp`, triggering `deploy-mcp.yml`. Agents can connect to MCP servers as tool providers.
+Each subdirectory is a FastMCP server that deploys to Cloud Run. See [mcp-servers.md](mcp-servers.md). Deployed via Portal UI or `/deploy_mcp`, triggering `deploy-mcp.yml`. Agents can connect to MCP servers as tool providers.
 
 ### `broadchurch.yaml`
 
@@ -158,11 +152,10 @@ Use these to build whatever UI fits the app:
   local Nitro streaming route (`/api/agent/:agentId/stream`) which calls
   Agent Engine directly with a tenant SA token. Handles streaming, session
   management, and response parsing. Shows clear error messages when IAM
-  permissions are missing. See the `agents` cursor rule for details.
+  permissions are missing. See [agents.md](agents.md) for details.
 - **`useTenantConfig()`** -- Fetch the tenant's runtime config (deployed
   agents, feature flags, MCP servers) from the Portal Gateway.
 - **`useElementalClient()`** -- When using the Elemental API from the client,
-  see the `data` rule.
+  see [data.md](data.md).
 - **`usePrefsStore()` / `Pref<T>`** -- KV-backed user preferences. See
-  the `pref` rule.
-
+  [pref.md](pref.md).

package/{rules/branding.mdc → skills/aether/branding.md}

@@ -1,8 +1,3 @@
----
-description: Apply when working on visual styling, colors, typography, theming, branding, or UI appearance.
-alwaysApply: false
----
-
 # Lovelace Branding
 
 The `lovelace-branding` skill (`skills/lovelace-branding/`) is the single source of truth for all brand specifics -- colors, typography, patterns, assets, and usage guidelines. Read the skill before making branding decisions. Start with `SKILL.md` for the file index.
@@ -15,13 +10,13 @@ Single dark theme. No light mode, no theme switching.
 
 These files are project-owned. Consult the branding skill for the values and patterns they should implement.
 
-| File | Role |
-|------|------|
-| `assets/brand-globals.css` | `:root` CSS variables and global typography/layout |
-| `assets/fonts.css` | `@font-face` declarations |
-| `assets/theme-styles.css` | Theme-aware CSS utility classes |
-| `composables/useLovelaceTheme.ts` | Theme color palette and Vuetify theme activation |
-| `composables/useThemeClasses.ts` | Theme-aware class combination utilities |
+| File                              | Role                                               |
+| --------------------------------- | -------------------------------------------------- |
+| `assets/brand-globals.css`        | `:root` CSS variables and global typography/layout |
+| `assets/fonts.css`                | `@font-face` declarations                          |
+| `assets/theme-styles.css`         | Theme-aware CSS utility classes                    |
+| `composables/useLovelaceTheme.ts` | Theme color palette and Vuetify theme activation   |
+| `composables/useThemeClasses.ts`  | Theme-aware class combination utilities            |
 
 ## Integration
 

package/{rules/cookbook-data.mdc → skills/aether/cookbook-data.md}

@@ -1,17 +1,12 @@
----
-description: "Data-fetching UI recipes: entity search, news feed, filings, gateway helpers. Read with the `data` rule when building pages that use the Query Server or platform data."
-alwaysApply: false
----
-
 # Data-fetching cookbook
 
-Copy-paste patterns that call the Elemental API, gateway, or helpers. For platform API details see the `data` rule. Pure UI patterns (tables, forms, charts) are in the `cookbook` rule.
+Copy-paste patterns that call the Elemental API, gateway, or helpers. For platform API details see [data.md](data.md) in this skill. Pure UI patterns (tables, forms, charts) are in [cookbook.md](cookbook.md).
 
 ## 1. Entity Search Page
 
 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 `data` rule.
+is not wrapped by the generated `useElementalClient()` — see [data.md](data.md).
 
 ```vue
 <template>
@@ -182,8 +177,8 @@ for runtime flavor/PID discovery and `buildGatewayUrl()` for gateway access.
                 const vals = valueMap.get(neid) ?? {};
                 return {
                     neid,
-                    name: namePid ? (vals[namePid] as string) ?? neid : neid,
-                    sentiment: sentimentPid ? (vals[sentimentPid] as number) ?? null : null,
+                    name: namePid ? ((vals[namePid] as string) ?? neid) : neid,
+                    sentiment: sentimentPid ? ((vals[sentimentPid] as number) ?? null) : null,
                 };
             });
         } catch (e: any) {
@@ -215,12 +210,7 @@ Simpler version of recipe #1 using the pre-built `searchEntities()` helper.
             {{ error }}
         </v-alert>
         <v-list v-if="results.length" class="mt-4">
-            <v-list-item
-                v-for="r in results"
-                :key="r.neid"
-                :title="r.name"
-                :subtitle="r.neid"
-            />
+            <v-list-item v-for="r in results" :key="r.neid" :title="r.name" :subtitle="r.neid" />
         </v-list>
         <v-empty-state
             v-else-if="searched && !loading"
@@ -266,7 +256,7 @@ properties are then fetched via `useElementalClient()`.
 **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 `data` rule for the two-layer architecture.
+relationship PID. See [data.md](data.md) for the two-layer architecture.
 
 ```vue
 <template>
@@ -366,7 +356,7 @@ relationship PID. See the `data` rule for the two-layer architecture.
             });
 
             const docNeids = (propRes.values ?? []).map((v: any) =>
-                String(v.value).padStart(20, '0'),
+                String(v.value).padStart(20, '0')
             );
 
             function getEntityNameUrl(neid: string) {
@@ -379,15 +369,14 @@ relationship PID. See the `data` rule for the two-layer architecture.
             const names = await Promise.all(
                 docNeids.map(async (neid: string) => {
                     try {
-                        const res = await $fetch<{ name: string }>(
-                            getEntityNameUrl(neid),
-                            { headers: { 'X-Api-Key': getApiKey() } },
-                        );
+                        const res = await $fetch<{ name: string }>(getEntityNameUrl(neid), {
+                            headers: { 'X-Api-Key': getApiKey() },
+                        });
                         return res.name || neid;
                     } catch {
                         return neid;
                     }
-                }),
+                })
             );
 
             filings.value = docNeids.map((neid: string, i: number) => ({
@@ -430,11 +419,7 @@ Type-ahead search that shows results in a dropdown as the user types. Uses
             @click:clear="onClear"
         />
 
-        <v-card
-            v-if="showMenu && suggestions.length > 0"
-            class="search-dropdown"
-            elevation="8"
-        >
+        <v-card v-if="showMenu && suggestions.length > 0" class="search-dropdown" elevation="8">
             <v-list density="compact">
                 <v-list-item
                     v-for="item in suggestions"
@@ -457,7 +442,7 @@ Type-ahead search that shows results in a dropdown as the user types. Uses
             icon?: string;
             flavors?: string[];
         }>(),
-        { label: 'Search', icon: 'mdi-magnify', flavors: undefined },
+        { label: 'Search', icon: 'mdi-magnify', flavors: undefined }
     );
 
     const emit = defineEmits<{

package/{rules/cookbook.mdc → skills/aether/cookbook.md}

@@ -1,13 +1,8 @@
----
-description: "Copy-paste UI patterns for common pages: data table, form, chart, dialog, master-detail. For Query Server / data-fetching recipes see `cookbook-data`."
-alwaysApply: false
----
-
 # UI Pattern Cookbook
 
 Copy-paste patterns using the project's actual composables and Vuetify components. Adapt to your needs.
 
-**Data-fetching recipes** (entity search, news feed, filings, gateway helpers) live in the `cookbook-data` rule.
+**Data-fetching recipes** (entity search, news feed, filings, gateway helpers) live in [cookbook-data.md](cookbook-data.md).
 
 ## 2. Data Table Page
 
@@ -98,9 +93,7 @@ Form with field validation, submit handler, and user feedback.
                 variant="outlined"
                 class="mb-3"
             />
-            <v-btn type="submit" color="primary" :loading="saving" :disabled="!valid">
-                Save
-            </v-btn>
+            <v-btn type="submit" color="primary" :loading="saving" :disabled="!valid"> Save </v-btn>
         </v-form>
     </v-container>
 </template>

package/skills/aether/cursor-cloud.md

@@ -0,0 +1,57 @@
+If you are in Cursor Cloud, the `environment.json` install step runs
+`init-project.js` and `npm install` automatically, and starts a dev server
+on port 3000.
+
+**Verify before starting:** check that `.env` exists and `node_modules/` is
+present. If either is missing, run: `node init-project.js && npm install`
+
+**Do NOT** manually run `nvm install` or `nvm use` — Node version is managed
+by the environment.
+
+### Initial environment setup only
+
+This subsection applies ONLY when first asked to "set up the development
+environment" or "demonstrate that the environment is working." It does
+**NOT** apply to ongoing development — once the app is built, use the
+browser normally to test and verify UI changes.
+
+**During initial setup**, skip browser/UI testing. The starter UI is a
+placeholder template that will be replaced by `/build_my_app`. Do not
+launch a browser, record videos, or take screenshots at this stage.
+Verifying `npm run build` passes is sufficient.
+
+1. Check the "Dev Server" terminal output for a line containing
+   `Listening on` or `Local: http://localhost:3000`. If present, the
+   environment is working.
+2. If the dev server is NOT running, start it with `npm run dev` and wait
+   for the "Listening on" line.
+3. Run `npm run build` to verify the project compiles.
+4. Once confirmed, tell the user the environment is ready, then
+   immediately run the `/build_my_app` command.
+
+### MCP tools
+
+Lovelace MCP servers (`lovelace-elemental`, `lovelace-stocks`, etc.)
+should be available if configured at the org level. Check your tool list
+for `elemental_*` tools. If they're not available, use the Elemental API
+client (`useElementalClient()`) and the skill docs in
+`.cursor/skills/elemental-api/` and `.cursor/skills/data-model/` for platform data access instead.
+
+### Technical details
+
+Node 20 is the baseline (`.nvmrc`). The `environment.json` install step
+handles this via `nvm install 20 && nvm alias default 20`. Newer Node
+versions (22, 25) generally work but may produce `EBADENGINE` warnings
+during install — safe to ignore.
+
+The install step runs `node init-project.js --local` (creates `.env` if
+absent) then `npm install` (triggers `postinstall` → `nuxt prepare`).
+Auth0 is bypassed via `NUXT_PUBLIC_USER_NAME=dev-user`
+in the generated `.env`.
+
+**No automated test suite.** Verification is `npm run build` (compile
+check) and `npm run format:check` (Prettier). See Verification Commands.
+
+**Before committing:** always run `npm run format` — the husky pre-commit
+hook runs `lint-staged` with `prettier --check` and will reject
+unformatted files.