@yottagraph-app/aether-instructions 1.1.5 → 1.1.7

package/commands/build_my_app.md

@@ -28,25 +28,35 @@ Stop here and wait for the user to describe what they want.
 
 ---
 
-## Step 2: Enable MCP Servers
+## Step 2: Check MCP Servers
 
-Check if `.cursor/mcp.json` exists and contains Lovelace MCP servers:
+Check if Lovelace MCP tools are available by looking at your tool list for
+tools like `elemental_get_schema`, `elemental_get_entity`, etc.
+
+**If MCP tools are available:** Great — you have access to Lovelace platform
+tools (entity search, market data, news, etc.) that you can use during
+development.
+
+**If MCP tools are NOT available:** Check if `.cursor/mcp.json` exists:
 
 ```bash
 cat .cursor/mcp.json 2>/dev/null
 ```
 
-**If the file contains `mcpServers`:** These MCP servers give you access to Lovelace platform tools (entity search, market data, news, etc.) that you'll need during development. Cursor disables new MCP servers by default, so ask the user:
+If the file exists but tools aren't showing, they may need to be enabled:
 
-> Before we start building, let's make sure your MCP tools are enabled.
+> Your project has Lovelace MCP servers configured (`.cursor/mcp.json`),
+> but they don't appear to be active yet. Cursor disables new MCP servers
+> by default.
 >
-> Open **Cursor Settings** (Cmd+Shift+J) → **Tools & MCP** and enable the `lovelace-*` servers listed there. They should show green toggles when active.
->
-> Let me know when they're enabled (or if you'd like to skip this for now).
-
-Wait for confirmation before proceeding. If the user skips this step, note that MCP tools won't be available during the build but can be enabled later.
+> Open **Cursor Settings** (Cmd+Shift+J) → **Tools & MCP** and enable the
+> `lovelace-*` servers listed there. They should show green toggles when
+> active. Let me know when they're enabled (or if you'd like to skip this).
 
-**If the file doesn't exist or has no servers:** Skip this step silently.
+Wait for confirmation before proceeding. If the user skips this step or
+the settings panel isn't available (e.g. Cursor Cloud), proceed without
+MCP tools — the app can still be built using the Elemental API client
+(`useElementalClient()`) directly.
 
 ---
 
@@ -73,8 +83,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 +106,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.5",
+    "version": "1.1.7",
     "description": "Cursor rules, commands, and skills for Aether development",
     "files": [
         "rules",

package/rules/agents.mdc

@@ -161,17 +161,17 @@ 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
@@ -179,7 +179,7 @@ The gateway URL and tenant ID come from `broadchurch.yaml` (injected as
 
 ### Agent Discovery
 
-The chat page discovers deployed agents by fetching the tenant config:
+The app discovers deployed agents by fetching the tenant config:
 
 ```
 GET {NUXT_PUBLIC_GATEWAY_URL}/api/config/{NUXT_PUBLIC_TENANT_ORG_ID}

package/rules/api.mdc

@@ -329,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,23 +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
-
-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. 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 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.
+## 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/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