@yottagraph-app/aether-instructions 1.1.27 → 1.1.28

package/commands/build_my_app.md

@@ -102,15 +102,15 @@ Then read these files to understand what's available:
 
 1. `DESIGN.md` -- project vision and current status
 2. `broadchurch.yaml` -- project config (name, gateway URL, etc.)
-3. **The `api` cursor rule** -- this is critical. It describes the Query Server, the platform's primary data source. Build against platform APIs, not external sources.
+3. **The `data` cursor rule** -- this is critical. It describes the Query Server, the platform's primary data source. Build against platform APIs, not external sources.
 4. **`.cursor/skills/`** — Each subdirectory is one skill. List them, open each skill’s entry (usually `SKILL.md`) and follow its structure to learn what is documented (APIs, schemas, helpers, etc.).
 5. `.cursor/rules/` -- scan rule names to know what other patterns are available
 
-**Important: Use the platform's data.** This app runs on the Lovelace platform, which provides a Query Server with entities, news, filings, sentiment, relationships, events, and more. Read the `api` rule and the skills under `.cursor/skills/` to understand what data is available. Use `getSchema()` to discover entity types and properties at runtime.
+**Important: Use the platform's data.** This app runs on the Lovelace platform, which provides a Query Server with entities, news, filings, sentiment, relationships, events, and more. Read the `data` rule and the skills under `.cursor/skills/` to understand what data is available. Use `getSchema()` to discover entity types and properties at runtime.
 
 Key capabilities:
 
-- **Query Server / Elemental API** -- the primary data source. Use `useElementalClient()` from `@yottagraph-app/elemental-api/client`. See the `api` rule.
+- **Query Server / Elemental API** -- the primary data source. Use `useElementalClient()` from `@yottagraph-app/elemental-api/client`. See the `data` rule.
 - **KV storage** -- always available for preferences and lightweight data (see `pref` rule)
 - **Neon Postgres** -- check if `DATABASE_URL` is in `.env` for database access (see `server` rule)
 - **AI agent chat** -- use the `useAgentChat` composable to build a chat UI for deployed agents

package/commands/update_instructions.md

@@ -100,6 +100,29 @@ cp "$TEMP_DIR/package/commands/"* .cursor/commands/ 2>/dev/null || true
 cp -r "$TEMP_DIR/package/skills/"* .cursor/skills/ 2>/dev/null || true
 ```
 
+### Data-mode variant overlay
+
+If this project uses **mcp-only** (or another non-default mode), re-apply the same overlay `init-project.js` uses. Read the saved mode:
+
+```bash
+MODE=$(tr -d '\n' < .cursor/.aether-data-mode 2>/dev/null || echo "api-mcp")
+PKG="$TEMP_DIR/package"
+if [ "$MODE" != "api-mcp" ] && [ -d "$PKG/variants/$MODE/rules" ]; then
+  cp "$PKG/variants/$MODE/rules/"* .cursor/rules/ 2>/dev/null || true
+fi
+if [ "$MODE" != "api-mcp" ] && [ -d "$PKG/variants/$MODE/commands" ]; then
+  cp "$PKG/variants/$MODE/commands/"* .cursor/commands/ 2>/dev/null || true
+fi
+if [ "$MODE" != "api-mcp" ] && [ -d "$PKG/variants/$MODE/skills" ]; then
+  cp -r "$PKG/variants/$MODE/skills/"* .cursor/skills/ 2>/dev/null || true
+fi
+if [ "$MODE" = "mcp-only" ]; then
+  rm -rf .cursor/skills/elemental-api
+fi
+```
+
+If `.cursor/.aether-data-mode` is missing, skip the overlay (defaults to **api-mcp**).
+
 ---
 
 ## Step 6: Write Manifest and Version Marker

package/package.json

@@ -1,11 +1,12 @@
 {
     "name": "@yottagraph-app/aether-instructions",
-    "version": "1.1.27",
+    "version": "1.1.28",
     "description": "Cursor rules, commands, and skills for Aether development",
     "files": [
         "rules",
         "commands",
-        "skills"
+        "skills",
+        "variants"
     ],
     "repository": {
         "type": "git",

package/rules/aether.mdc

@@ -8,7 +8,7 @@ alwaysApply: true
 
 **Structure:** `pages/` (file-based routing), `components/`, `composables/`, `server/api/`, `agents/` (Python ADK), `mcp-servers/` (Python FastMCP).
 
-**Data:** The Query Server (Elemental API) is the primary data source -- entities, news, filings, sentiment, relationships, events. Use `useElementalClient()` from `@yottagraph-app/elemental-api/client`. Do NOT call external APIs for data the platform provides. Discovery-first: use `getSchema()` to discover entity types and properties at runtime. Skill docs: `skills/elemental-api/` (API endpoints) and `skills/data-model/` (Lovelace entity types, properties, relationships, YAML schemas per fetch source; `SKILL.md` first). Run `npm install` if those directories are empty. Lovelace MCP servers may also be configured (see `api` rule) but are optional — check your tool list before assuming they're available.
+**Data:** This app runs on the Lovelace platform -- entities, news, filings, sentiment, relationships, events. See the `data` rule for access patterns and gotchas. Skill docs: `skills/data-model/` (entity types, properties, relationships; `SKILL.md` first). Do NOT call external APIs for data the platform provides.
 
 **Storage:** KV (Upstash Redis) for preferences and lightweight state via `Pref<T>` from `usePrefsStore()`. Neon Postgres for relational data if connected (check `.env` for `DATABASE_URL`).
 
@@ -18,4 +18,4 @@ alwaysApply: true
 
 **First action for a new project:** Run `/build_my_app`.
 
-**Task-specific rules:** `architecture` (project structure, navigation, server routes, agents, MCP), `api` (Elemental API client, schema discovery, gotchas, optional MCP servers), `design` (DESIGN.md workflow, feature docs), `ui` (page templates, layout patterns), `cookbook` (copy-paste UI patterns), `pref` (KV preferences), `branding` (colors, fonts), `server` (Nitro routes, Neon Postgres, server-side Elemental API), `something-broke` (error recovery, build failures).
+**Task-specific rules:** `architecture` (project structure, navigation, server routes, agents, MCP), `data` (Elemental API / data access patterns and gotchas), `cookbook` (copy-paste UI patterns), `cookbook-data` (data-fetching recipes), `design` (DESIGN.md workflow, feature docs), `ui` (page templates, layout patterns), `pref` (KV preferences), `branding` (colors, fonts), `server` (Nitro routes, Neon Postgres), `server-data` (server-side Elemental API from routes), `agents` (ADK agents), `agents-data` (agents calling Elemental API), `something-broke` (error recovery, build failures).

package/rules/agents-data.mdc

@@ -0,0 +1,72 @@
+---
+description: "ADK agents calling the Elemental API via broadchurch_auth and local testing env vars."
+alwaysApply: false
+globs: agents/**
+---
+
+# Agents: Elemental API (Query Server)
+
+## 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:
+
+- Routing through the Broadchurch Portal gateway proxy in production
+  (no direct QS credentials needed — the portal handles Auth0 M2M auth)
+- Authenticating to the proxy with a per-tenant API key from
+  `broadchurch.yaml` (`gateway.qs_api_key`)
+- Falling back to `ELEMENTAL_API_URL` + `ELEMENTAL_API_TOKEN` env vars
+  for local dev
+
+```python
+try:
+    from broadchurch_auth import elemental_client
+except ImportError:
+    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()
+```
+
+The try/except is required because the import path differs between local
+dev (`agents/` on sys.path → absolute import) and Agent Engine runtime
+(code packaged inside an ADK module → relative import).
+
+**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 by expression
+- `POST /entities/search` — search for entities by name (batch, scored)
+- `POST /elemental/entities/properties` — get entity property values
+
+Requirements for agents using the Elemental API (add to `requirements.txt`):
+```
+google-auth>=2.20.0
+pyyaml>=6.0
+```
+
+## Local testing: Elemental API env vars
+
+When testing agents locally with `adk web`, for agents that call the Elemental API:
+
+```bash
+export ELEMENTAL_API_URL=https://stable-query.lovelace.ai
+export ELEMENTAL_API_TOKEN=<your-token>
+```
+
+In production, all Elemental API calls go through the Portal Gateway at
+`{gateway_url}/api/qs/{org_id}/...`. The agent sends `X-Api-Key` (from
+`broadchurch.yaml`) and the portal injects its own Auth0 M2M token
+upstream.

package/rules/agents.mdc

@@ -47,56 +47,8 @@ Key rules:
 - 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:
-
-- Routing through the Broadchurch Portal gateway proxy in production
-  (no direct QS credentials needed — the portal handles Auth0 M2M auth)
-- Authenticating to the proxy with a per-tenant API key from
-  `broadchurch.yaml` (`gateway.qs_api_key`)
-- Falling back to `ELEMENTAL_API_URL` + `ELEMENTAL_API_TOKEN` env vars
-  for local dev
-
-```python
-try:
-    from broadchurch_auth import elemental_client
-except ImportError:
-    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()
-```
-
-The try/except is required because the import path differs between local
-dev (`agents/` on sys.path → absolute import) and Agent Engine runtime
-(code packaged inside an ADK module → relative import).
-
-**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 by expression
-- `POST /entities/search` — search for entities by name (batch, scored)
-- `POST /elemental/entities/properties` — get entity property values
-
-Requirements for agents using the Elemental API (add to `requirements.txt`):
-```
-google-auth>=2.20.0
-pyyaml>=6.0
-```
+For agents that call the **Elemental API** (`broadchurch_auth`, endpoints,
+local `ELEMENTAL_*` env vars), see the `agents-data` rule.
 
 ## Local Testing
 
@@ -113,10 +65,6 @@ 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/
 ```
 

package/rules/architecture.mdc

@@ -9,7 +9,7 @@ Aether is an app framework built on Nuxt 3 + Vue 3 + Vuetify 3 + TypeScript. It
 
 **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.
+**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.
 
 ## Project Structure
 
@@ -28,11 +28,10 @@ mcp-servers/        # MCP servers (Python, deploy to Cloud Run)
 
 | Store | Purpose | When to use |
 |---|---|---|
-| Query Server (Elemental API) | Lovelace Knowledge Graph | Entities, news, relationships, events, sentiment, filings |
+| 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`) |
 
-Use `useElementalClient()` for Query Server data (see `api` rule).
 Use `Pref<T>` or `usePrefsStore()` for KV (see `pref` rule).
 Check `.env` for `DATABASE_URL` before using Neon Postgres (see `server` rule).
 
@@ -113,12 +112,12 @@ using them later when adding features to an established app.
 ## Server Routes
 
 Nitro server routes live in `server/api/` and deploy with the app to Vercel.
-Use server routes when you need to proxy external APIs (avoid CORS), call
-the Elemental API server-side, or keep secrets off the client. Call them
-from client code with `$fetch('/api/my-data/fetch')`.
+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, Neon Postgres patterns,
-and server-side Elemental API access via `useRuntimeConfig()`.
+See the `server` rule for file-routing conventions and Neon Postgres patterns.
+See `server-data` when calling the platform Query Server from server routes.
 
 ## Beyond the UI: Agents, MCP Servers, and Server Routes
 
@@ -147,8 +146,8 @@ Use these to build whatever UI fits the app:
   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.
+- **`useElementalClient()`** -- When using the Elemental API from the client,
+  see the `data` rule.
 - **`usePrefsStore()` / `Pref<T>`** -- KV-backed user preferences. See
   the `pref` rule.