@yottagraph-app/aether-instructions 1.0.1

package/rules/aether_agents.mdc

@@ -0,0 +1,166 @@
+---
+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.
+
+## 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).
+
+```
+agents/my_agent/            # Underscores only! "my-agent" will NOT work.
+├── __init__.py             # Required (can be empty)
+├── agent.py                # Required: must export root_agent
+├── requirements.txt        # Required: must include google-adk
+└── .env                    # Optional: local env vars (git-ignored)
+```
+
+## Writing an Agent
+
+Agents use the [Google Agent Development Kit (ADK)](https://google.github.io/adk-docs/). The core pattern:
+
+```python
+from google.adk.agents import Agent
+
+def my_tool(query: str) -> dict:
+    """Tool docstrings become the LLM's understanding of what the tool does.
+    Be specific about parameters and return values."""
+    # Tool implementation
+    return {"result": "..."}
+
+root_agent = Agent(
+    model="gemini-2.0-flash",
+    name="my_agent",
+    instruction="Clear instructions about the agent's purpose and capabilities.",
+    tools=[my_tool],
+)
+```
+
+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
+
+## Connecting to the Elemental API
+
+Use `broadchurch_auth` for all Elemental API calls. It lives at
+`agents/broadchurch_auth.py` and is automatically bundled into each agent
+directory at deploy time. It handles:
+
+- Reading the API URL from `broadchurch.yaml` (or `ELEMENTAL_API_URL` env var)
+- Minting and caching GCP ID tokens in production
+- Falling back to `ELEMENTAL_API_TOKEN` for local dev
+
+```python
+from broadchurch_auth import elemental_client
+
+def get_schema() -> dict:
+    """Get the yottagraph schema."""
+    resp = elemental_client.get("/elemental/metadata/schema")
+    resp.raise_for_status()
+    return resp.json()
+
+def find_entities(expression: str, limit: int = 10) -> dict:
+    """Search for entities."""
+    resp = elemental_client.post("/elemental/find", data={"expression": expression, "limit": str(limit)})
+    resp.raise_for_status()
+    return resp.json()
+```
+
+**Do NOT** hardcode URLs or manually handle auth tokens. Do NOT read
+`broadchurch.yaml` directly — `broadchurch_auth` handles all of this.
+
+Key endpoints:
+- `GET /elemental/metadata/schema` — entity types and properties
+- `POST /elemental/find` — search for entities
+- `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`):
+```
+google-auth>=2.20.0
+pyyaml>=6.0
+```
+
+## Local Testing
+
+Test agents locally before deploying. Run `adk web` from the `agents/`
+directory (NOT from inside the agent folder — ADK discovers agents by
+scanning subdirectories):
+
+```bash
+cd agents/                  # The PARENT of your agent directories
+pip install -r my_agent/requirements.txt
+
+# Required: tell ADK to use Vertex AI for Gemini
+export GOOGLE_CLOUD_PROJECT=broadchurch
+export GOOGLE_CLOUD_LOCATION=us-central1
+export GOOGLE_GENAI_USE_VERTEXAI=1
+
+# For agents that call the Elemental API:
+export ELEMENTAL_API_URL=https://stable-query.lovelace.ai
+export ELEMENTAL_API_TOKEN=<your-token>
+
+adk web                     # Opens browser UI at http://127.0.0.1:8000/dev-ui/
+```
+
+Select your agent from the dropdown in the web UI. You can also run a single agent directly: `adk run my_agent/`
+
+`broadchurch_auth.py` lives at the `agents/` root, so it's importable
+during local dev (agents/ is the CWD → on sys.path). At deploy time, the
+workflow copies it into the agent directory alongside `broadchurch.yaml`.
+
+## Deployment
+
+Two ways to deploy:
+
+1. **Portal UI** -- Open the project in the Broadchurch Portal. It scans
+   `agents/` in your GitHub repo and shows undeployed agents with a Deploy
+   button. Make sure your code is pushed to `main` first.
+2. **Cursor command** -- Run `/deploy_agent`. It reads `broadchurch.yaml` and
+   triggers the same workflow.
+
+Both paths trigger `deploy-agent.yml` in GitHub Actions, which runs
+`adk deploy agent_engine` and then registers the agent with the Portal Gateway.
+
+Manual CLI deployment (advanced):
+
+```bash
+adk deploy agent_engine \
+  --project <from broadchurch.yaml> \
+  --region <from broadchurch.yaml> \
+  --staging_bucket <from broadchurch.yaml> \
+  --display_name "<agent-name>" \
+  --trace_to_cloud \
+  agents/<agent-name>/
+```
+
+## How Agents Reach the Chat UI
+
+Once deployed, the agent is reachable through the Portal Gateway:
+
+```
+Chat UI (pages/chat.vue)
+  → POST NUXT_PUBLIC_GATEWAY_URL/api/agents/{tenantId}/{agentId}/query
+  → Portal Gateway proxies to Vertex AI Agent Engine
+  → Agent runs, returns response
+  → Chat UI 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.
+
+## Agent Design Guidelines
+
+- Keep agents focused: one agent per domain or task type
+- Write clear, specific instructions -- the LLM follows them literally
+- 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

package/rules/aether_api.mdc

@@ -0,0 +1,211 @@
+---
+description: "Elemental API client usage, schema discovery, entity search, API gotchas, MCP servers. Read when building features that fetch or display data from the Query Server."
+alwaysApply: false
+---
+# Elemental API — The Platform Data Source
+
+**This app is built on the Lovelace platform.** The Query Server is the
+primary data source — use it first for any data needs (entities, news,
+filings, sentiment, relationships, events). Do NOT call external APIs
+(e.g. sec.gov, Wikipedia) for data that the platform already provides.
+
+The Elemental API provides access to the Lovelace Knowledge Graph through
+the Query Server. Use it to search for entities, retrieve properties,
+explore relationships, and analyze sentiment. New data sources are added
+regularly — use the discovery-first pattern to find what's available.
+
+## Skill Documentation
+
+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.
+
+Key files:
+- `entities.md` — entity search, details, and properties
+- `find.md` — expression language for searching by type, property, and relationships
+- `schema.md` — entity types (flavors), properties (PIDs), and schema endpoints
+- `relationships.md` — entity connections
+- `events.md` — events involving entities
+- `articles.md` — news mentions and article content
+
+## Client Usage
+
+All API calls go through `useElementalClient()` from `@yottagraph-app/elemental-api/client`.
+Auth tokens and base URL are configured automatically by the `elemental-client` plugin.
+
+```typescript
+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();
+```
+
+Types are also imported from the client:
+
+```typescript
+import type { NamedEntityReport, GetNEIDResponse } from '@yottagraph-app/elemental-api/client';
+```
+
+## Discovery-First Pattern
+
+The knowledge graph contains many entity types and properties, and new datasets
+are added regularly (e.g. Edgar filings, financial data). Do NOT hardcode entity
+types or property names. Instead, discover them at runtime:
+
+1. **Get the schema** — `client.getSchema()` returns all entity types (flavors)
+   and properties (PIDs) available in the system. See `schema.md`.
+
+   The schema response contains:
+   - **Flavors** (entity types): Company, Person, GovernmentOrg, etc.
+     Each flavor has a numeric ID and a human-readable name.
+   - **PIDs** (properties): name, country, industry, lei_code, etc.
+     Each PID has a type (`data_str`, `data_int`, `data_nindex`, etc.).
+   - Properties with type `data_nindex` are references to other entities —
+     resolve them with another `getPropertyValues` call.
+
+   Use flavor names in `findEntities()` expressions and PID names in
+   `getPropertyValues()`.
+
+2. **Search with expressions** — `client.findEntities()` uses a JSON expression
+   language to search by type, property value, or relationship. See `find.md`.
+3. **Get property values** — `client.getPropertyValues()` fetches property data
+   for specific entities.
+
+This pattern lets agents work with any dataset without needing hardcoded
+knowledge of what's in the graph.
+
+## API Gotchas
+
+> **WARNING -- `getSchema()` response nesting**: The generated TypeScript types
+> put `flavors` and `properties` at the top level, but the actual API response
+> nests them under a `schema` key. Using `response.properties` directly will
+> crash with `Cannot read properties of undefined`. Always use:
+
+```typescript
+const res = await client.getSchema();
+const properties = res.schema?.properties ?? (res as any).properties ?? [];
+const flavors = res.schema?.flavors ?? (res as any).flavors ?? [];
+```
+
+> **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.
+
+```typescript
+const values = await client.getPropertyValues({
+  eids: JSON.stringify(['00416400910670863867']),
+  pids: JSON.stringify(['name', 'country', 'industry']),
+});
+```
+
+### `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.
+
+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.
+
+```typescript
+const pidMap = await getPropertyPidMap(client);
+const filedPid = pidMap.get('filed')!;
+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'));
+```
+
+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 batch search
+  (`POST /entities/search`). Best for filtered searches (by type, property,
+  relationship). See `find.md` for the expression language.
+
+## Error Handling
+
+```typescript
+try {
+    const data = await client.getNEID({ entityName: '...' });
+} catch (error) {
+    console.error('API Error:', error);
+    showError('Failed to load data. Please try again.');
+}
+```
+
+Methods on `useElementalClient()` return data directly and throw on non-2xx
+responses. For full `{ data, status, headers }` access, import the raw
+functions instead:
+
+```typescript
+import { getArticle } from '@yottagraph-app/elemental-api/client';
+
+const response = await getArticle(artid);
+if (response.status === 404) { /* handle not found */ }
+```
+
+## Lovelace MCP Servers (Optional)
+
+Four MCP servers **may** be configured in `.cursor/mcp.json` for interactive
+data exploration. They are NOT required — the REST client
+(`useElementalClient()`) and skill docs cover the same data and are the
+primary path for building features.
+
+**Before referencing MCP tools, check your available tool list.** If tools
+like `elemental_get_schema` don't appear in your MCP server list, the
+servers aren't connected — just use the REST client and skill docs instead.
+Do not report this as a problem; it's a normal configuration state.
+
+| Server | What it provides |
+|---|---|
+| `lovelace-elemental` | Knowledge Graph: entities, relationships, events, sentiment, schema discovery |
+| `lovelace-stocks` | Stock/financial market data |
+| `lovelace-wiki` | Wikipedia entity enrichment |
+| `lovelace-polymarket` | Prediction market data |
+
+### Setup
+
+`.cursor/mcp.json` is auto-generated by `init-project.js`. If it's missing,
+run `node init-project.js --local` to regenerate it. For provisioned projects,
+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.
+
+### When MCP Servers Are Available
+
+If the MCP tools appear in your tool list, you can use them for interactive
+exploration alongside the REST client:
+
+| Tool | Purpose |
+|---|---|
+| `elemental_get_schema` | Discover entity types (flavors), properties, and relationships |
+| `elemental_get_entity` | Look up entity by name or NEID; returns properties |
+| `elemental_get_related` | Related entities with type/relationship filters |
+| `elemental_get_relationships` | Relationship types and counts between two entities |
+| `elemental_graph_neighborhood` | Most influential neighbors of an entity |
+| `elemental_graph_sentiment` | Sentiment analysis from news articles |
+| `elemental_get_events` | Events for an entity or by search query |
+| `elemental_health` | Health check |
+
+MCP is convenient for schema discovery and entity resolution during planning.
+For building UI features, always use the REST client (`useElementalClient()`).

package/rules/aether_architecture.mdc

@@ -0,0 +1,141 @@
+---
+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. The Query Server (Elemental API) is the primary data source -- use it for entities, news, filings, sentiment, relationships, and events. See the `api` rule. Do not call external APIs for data the platform provides.
+
+## Project Structure
+
+```
+pages/              # Routes (file-based routing)
+components/         # Reusable Vue components
+composables/        # Shared logic (useXxx.ts)
+server/api/         # Nitro server routes (deploy with app)
+assets/             # CSS, fonts, static assets
+utils/              # Pure utility functions
+agents/             # ADK agents (Python, deploy to Vertex AI)
+mcp-servers/        # MCP servers (Python, deploy to Cloud Run)
+```
+
+## Data Architecture
+
+| Store | Purpose | When to use |
+|---|---|---|
+| Query Server (Elemental API) | Lovelace Knowledge Graph | Entities, news, relationships, events, sentiment, filings |
+| KV (Upstash Redis) | User preferences, lightweight state | Settings, watchlists, UI state that should persist |
+| Supabase (PostgreSQL) | App-specific relational data | Custom tables, complex queries (if connected) |
+
+Use `useElementalClient()` for Query Server data (see `api` rule).
+Use `Pref<T>` or `usePrefsStore()` for KV (see `pref` rule).
+Check `.env` for `NUXT_PUBLIC_SUPABASE_URL` before using Supabase.
+
+## Adding Pages
+
+Create `.vue` files in `pages/`. Nuxt generates routes automatically:
+
+```
+pages/index.vue         → /
+pages/dashboard.vue     → /dashboard
+pages/settings.vue      → /settings
+pages/reports/index.vue → /reports
+```
+
+## App Shell
+
+`app.vue` provides `AppHeader` (branding, user menu, settings) and renders `<NuxtPage />`. There is no prescribed layout beyond the header -- design whatever UX fits the problem.
+
+## Adding Navigation
+
+Only add navigation if the app genuinely needs multiple views. Choose the pattern that fits the UX:
+
+**Sidebar** -- add to `app.vue` for persistent section navigation:
+
+```vue
+<v-navigation-drawer permanent app>
+  <v-list nav density="compact">
+    <v-list-item title="Dashboard" prepend-icon="mdi-view-dashboard" to="/" />
+    <v-list-item title="Reports" prepend-icon="mdi-chart-bar" to="/reports" />
+  </v-list>
+</v-navigation-drawer>
+```
+
+**Top tabs** -- add to `app.vue` or a layout component:
+
+```vue
+<v-tabs>
+  <v-tab to="/">Dashboard</v-tab>
+  <v-tab to="/reports">Reports</v-tab>
+</v-tabs>
+```
+
+**In-page tabs** -- for subsections within a single page:
+
+```vue
+<v-tabs v-model="tab">
+  <v-tab value="overview">Overview</v-tab>
+  <v-tab value="details">Details</v-tab>
+</v-tabs>
+<v-window v-model="tab">
+  <v-window-item value="overview">...</v-window-item>
+  <v-window-item value="details">...</v-window-item>
+</v-window>
+```
+
+**No nav** -- single-page apps can put everything on `pages/index.vue`.
+
+## Naming Conventions
+
+- **Pages**: `kebab-case.vue`
+- **Components**: `PascalCase.vue`
+- **Composables**: `useCamelCase.ts`
+- **Server routes**: `kebab-case.<method>.ts`
+
+## 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
+
+## Server Routes
+
+Nitro server routes live in `server/api/` and deploy with the app to Vercel. They're auto-registered by Nuxt:
+
+```
+server/api/my-data/fetch.get.ts   →   GET /api/my-data/fetch
+server/api/my-data/submit.post.ts →  POST /api/my-data/submit
+```
+
+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.
+
+## Beyond the UI: Agents, MCP Servers, and Server Routes
+
+Aether apps are more than just a Nuxt SPA. The project contains three additional directories that deploy independently:
+
+### `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`).
+
+### `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.
+
+### `broadchurch.yaml`
+
+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. 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.
+

package/rules/aether_branding.mdc

@@ -0,0 +1,43 @@
+---
+description: Apply when working on visual styling, colors, typography, theming, branding, or UI appearance.
+alwaysApply: false
+---
+
+# Lovelace Brand R2
+
+The app follows Lovelace Brand R2 guidelines. For the full specification (color ramps, accessibility, visual effects), read `branding/BRANDING.md`.
+
+## Quick Reference
+
+- **Theme**: Single dark theme. No light mode, no theme switching.
+- **Core colors**: Jet Black `#0A0A0A`, Pure White `#FFFFFF`, Cyber Green `#3FEA00`, Sonic Silver `#757575`
+- **Secondary colors**: Electric Blue `#003BFF`, Blaze Orange `#FF5C00`
+- **Semantic**: Amber `#FF9F0A` (warnings), Red `#EF4444` (errors)
+- **Fonts**: FK Grotesk (body), FK Grotesk Mono (headlines, buttons, code). Falls back to Inter / system-ui. See `public/fonts/README.md` for setup.
+- **Icons**: Material Design Icons (mdi) via Vuetify
+
+## Branding Files
+
+These files are copied wholesale from the canonical branding source (`moongoose/ui/news-ui`). Update them by running `/update_branding`. Do **not** edit them in place.
+
+| File | Purpose |
+|---|---|
+| `branding/BRANDING.md` | Full brand specification |
+| `composables/useNewsTheme.ts` | Theme colors and CSS variable application |
+| `composables/useThemeClasses.ts` | Theme-aware class utilities |
+| `assets/theme-styles.css` | Theme CSS classes |
+| `assets/fonts.css` | `@font-face` declarations |
+| `assets/brand-globals.css` | Global CSS variables, typography, utilities |
+| `public/fonts/README.md` | Font setup instructions |
+| `public/LL-logo-full-wht.svg` | Primary logo (white, for dark backgrounds) |
+
+## Vuetify Theme
+
+The `lovelaceDark` Vuetify theme is defined in `nuxt.config.ts` under `vuetify.vuetifyOptions.theme`. This is the same theme used by the Broadchurch Portal. It provides Brand R2 colors to all Vuetify components automatically (primary = Cyber Green, secondary = Electric Blue, etc.). Component defaults (rounded buttons, outlined cards, etc.) are also set in `nuxt.config.ts` under `vuetify.vuetifyOptions.defaults`.
+
+## Integration
+
+- `composables/useCustomTheme.ts` is a thin adapter around `useNewsTheme`. Use `useCustomTheme()` or `useThemeClasses()` in components.
+- CSS variables (`--lv-green`, `--lv-black`, etc.) and theme classes (`.theme-card`, `.theme-text-primary`, etc.) are available globally.
+- `useNewsTheme` calls `theme.change('lovelaceDark')` to activate the Vuetify theme. This must match the theme name in `nuxt.config.ts`.
+- If you need to change how the branding integrates with Aether, modify the adapter -- not the branding files.