@yottagraph-app/aether-instructions 1.0.1

package/rules/aether_mcp-servers.mdc

@@ -0,0 +1,108 @@
+---
+description: Rules for developing MCP servers in the mcp-servers/ directory
+globs: mcp-servers/**
+alwaysApply: false
+---
+
+# MCP Server Development (FastMCP)
+
+This project supports developing and deploying custom MCP (Model Context Protocol) servers alongside the UI. Servers live in the `mcp-servers/` directory and deploy to Google Cloud Run via the `/deploy_mcp` command.
+
+MCP servers expose tools that agents can call. They act as bridges between AI agents and external data sources or APIs.
+
+## Directory Structure
+
+Each MCP server is a self-contained Python package:
+
+```
+mcp-servers/<server-name>/
+├── server.py           # Required: FastMCP server definition, must define `mcp = FastMCP("...")`
+├── requirements.txt    # Required: must include fastmcp
+└── Dockerfile          # Optional: auto-generated if missing
+```
+
+## Writing an MCP Server
+
+Use [FastMCP](https://github.com/jlowin/fastmcp) (v2.x) to define servers:
+
+```python
+import os
+from fastmcp import FastMCP
+
+mcp = FastMCP("my-data-server")
+
+@mcp.tool()
+def search_records(query: str, limit: int = 10) -> list[dict]:
+    """Search records matching the query.
+
+    Args:
+        query: Search text to match against record names and descriptions.
+        limit: Maximum number of results to return.
+
+    Returns:
+        List of matching records with id, name, and description fields.
+    """
+    # Your implementation here
+    return [{"id": "1", "name": "Example", "description": "..."}]
+
+@mcp.tool()
+def get_record(record_id: str) -> dict:
+    """Get a specific record by ID.
+
+    Args:
+        record_id: The unique identifier of the record.
+
+    Returns:
+        The full record with all fields.
+    """
+    return {"id": record_id, "name": "Example", "data": {}}
+
+if __name__ == "__main__":
+    port = int(os.environ.get("PORT", 8080))
+    mcp.run(transport="sse", host="0.0.0.0", port=port)
+```
+
+Key rules:
+- The FastMCP instance MUST be named `mcp` — the Dockerfile runs `fastmcp run server:mcp` to find it
+- FastMCP 2.x takes a single positional name argument: `FastMCP("name")`. Do NOT pass `name=` or `description=` as keyword arguments
+- Use `@mcp.tool()` decorators to define tools
+- Tool docstrings are essential: agents read them to understand the tool's purpose, parameters, and return values
+- Use type hints on all tool parameters and return values
+
+## Local Testing
+
+Test MCP servers locally:
+
+```bash
+cd mcp-servers/<server-name>
+pip install -r requirements.txt
+python server.py
+```
+
+This starts the server on port 8080 (or `$PORT`). You can also use the FastMCP CLI, which matches the production Dockerfile entry point:
+
+```bash
+python -m fastmcp run server:mcp --transport streamable-http --host 0.0.0.0 --port 8080
+```
+
+## Deployment
+
+Deploy with the `/deploy_mcp` Cursor command. This will:
+1. Build a container image via Cloud Build
+2. Deploy to Cloud Run with IAM authentication
+3. Grant invoker permissions to tenant and Portal service accounts
+4. Register the server in Firestore (via the Portal API)
+5. Add the server to `.cursor/mcp.json` for Cursor IDE access
+
+## Connecting MCP Servers to Agents
+
+Once deployed, agents can connect to your MCP server. Add the Cloud Run URL to your agent's MCP configuration. The agent's service account (from `broadchurch.yaml`) is already authorized to invoke the server.
+
+## MCP Server Design Guidelines
+
+- One server per data domain or external service
+- Keep tools focused and well-documented
+- Return structured data (dicts/lists), not raw strings
+- Handle errors by returning descriptive error messages in the response
+- Use environment variables for API keys and configuration (never hardcode secrets)
+- For secrets, use GCP Secret Manager and access at runtime

package/rules/aether_pref.mdc

@@ -0,0 +1,123 @@
+---
+description: Apply when working with user preferences, settings persistence, usePrefsStore, the Pref class, KV storage, or app namespacing (NUXT_PUBLIC_APP_ID).
+alwaysApply: false
+---
+
+# User Preferences
+
+Preferences are persisted to Upstash Redis (KV) via `usePrefsStore()` from
+`~/composables/usePrefsStore.ts`, backed by `KVPrefsStore` which calls
+`/api/kv/*` endpoints. The KV store is provisioned automatically during
+project creation and connected via Vercel env vars (`KV_REST_API_URL`,
+`KV_REST_API_TOKEN`).
+
+## Two-Tier Namespacing
+
+Preferences are scoped by the app ID set in `NUXT_PUBLIC_APP_ID`:
+
+- **App-specific**: `/users/{userId}/apps/{appId}/settings/general`
+- **Global (cross-app)**: `/users/{userId}/global/settings/general`
+
+## The Pref Class
+
+`Pref<T>` is a reactive wrapper that auto-syncs to KV. Defined in
+`usePrefsStore.ts`.
+
+```typescript
+const myPref = new Pref<string>(docPath, 'fieldName', 'defaultValue');
+await myPref.initialize();
+
+myPref.r.value; // reactive ref (use in templates)
+myPref.v;       // getter shorthand
+myPref.set('new value'); // persists to KV
+```
+
+Values are JSON-serialized. The `Pref` sets up a watcher after
+`initialize()` so any change to `.r` auto-persists.
+
+## usePrefsStore()
+
+```typescript
+const { readDoc, listDocuments, deleteCollection } = usePrefsStore();
+```
+
+The backing store auto-initializes on first use — no need to call
+`initializePrefsStore()` manually.
+
+## Local Development
+
+When KV credentials (`KV_REST_API_URL`, `KV_REST_API_TOKEN`) are not set
+(e.g. local dev without Vercel env vars), the KV server routes return
+`undefined` for reads and silently skip writes. Prefs will work with
+their default values but won't persist across page refreshes.
+
+For full local persistence, copy the KV credentials from your Vercel
+project settings into your local `.env` file (or use the Portal's
+"Get .env file" feature).
+
+## Direct API Alternative
+
+If you prefer not to use the `Pref<T>` class, you can call the KV
+routes directly:
+
+```typescript
+// Read
+const value = await $fetch('/api/kv/read', {
+  params: { docPath: '/users/abc/settings', fieldName: 'theme' }
+});
+
+// Write
+await $fetch('/api/kv/write', {
+  method: 'POST',
+  body: { docPath: '/users/abc/settings', fieldName: 'theme', value: '"dark"' }
+});
+```
+
+## Feature-Scoped Preferences
+
+Features should namespace preferences under the app's prefix:
+
+```typescript
+function useMyFeaturePrefs() {
+    const { appId } = useRuntimeConfig().public;
+    const { userId } = useUserState();
+    const path = `/users/${userId.value}/apps/${appId}/features/my-feature`;
+
+    const myPref = new Pref<boolean>(path, 'enabled', true);
+    return { myPref };
+}
+```
+
+## KV Architecture
+
+- **Server**: `server/utils/redis.ts` initializes the Upstash Redis client
+  from `KV_REST_API_URL` and `KV_REST_API_TOKEN` env vars
+- **API routes**: `server/api/kv/` (read, write, delete, documents)
+- **Client store**: `utils/kvPrefsStore.ts` implements `PrefsStore` by
+  calling the KV API routes
+- **Key format**: `prefs:users:{userId}:apps:{appId}:settings:general`
+  (doc-style paths converted to colon-separated Redis keys)
+
+## Local Development Without KV
+
+When KV credentials (`KV_REST_API_URL`, `KV_REST_API_TOKEN`) aren't configured,
+`Pref<T>` still works with its default value but won't persist across page
+refreshes. For local dev, use `localStorage` directly as a lightweight
+alternative:
+
+```typescript
+const saved = localStorage.getItem('watchlist');
+const watchlist = ref<string[]>(saved ? JSON.parse(saved) : []);
+watch(watchlist, (val) => localStorage.setItem('watchlist', JSON.stringify(val)), { deep: true });
+```
+
+Use `Pref<T>` for production persistence and `localStorage` for local-only
+development when KV isn't available.
+
+## Scope Guidance
+
+| App-specific | Global |
+|---|---|
+| Layout prefs, favorites | Language |
+| Watchlists, feature settings | Accessibility |
+| Feature-specific settings | Timezone, notifications |

package/rules/aether_server.mdc

@@ -0,0 +1,99 @@
+---
+description: Nitro server-side API routes and utilities in server/
+globs: server/**
+alwaysApply: false
+---
+
+# Nitro Server Routes
+
+The `server/` directory contains Nuxt's Nitro server layer. These routes deploy
+with the app to Vercel -- they are NOT a separate service. They handle
+server-side concerns like KV storage, database access, and image proxying
+that can't run in the browser.
+
+## Directory Layout
+
+```
+server/
+├── api/
+│   ├── kv/                  # KV (Upstash Redis) CRUD — read, write, delete, documents, status
+│   └── avatar/[url].ts      # Avatar image proxy
+└── utils/
+    ├── redis.ts              # Upstash Redis client init (from Vercel KV env vars)
+    └── cookies.ts            # Cookie handling (@hapi/iron)
+```
+
+## Adding Routes
+
+Follow Nitro file-based routing. The filename determines the HTTP method and
+path:
+
+```
+server/api/my-resource.get.ts      → GET  /api/my-resource
+server/api/my-resource.post.ts     → POST /api/my-resource
+server/api/my-resource/[id].get.ts → GET  /api/my-resource/:id
+```
+
+Route handler pattern:
+
+```typescript
+export default defineEventHandler(async (event) => {
+  const params = getQuery(event);        // query string
+  const body = await readBody(event);    // POST body
+  const id = getRouterParam(event, 'id'); // path params
+
+  // ... implementation ...
+  return { result: 'data' };
+});
+```
+
+## KV Storage (Upstash Redis)
+
+`server/utils/redis.ts` initializes the Upstash Redis client from env vars
+that Vercel auto-injects when a KV store is connected:
+
+- `KV_REST_API_URL` — Redis REST API endpoint
+- `KV_REST_API_TOKEN` — Auth token
+
+```typescript
+import { getRedis, toRedisKey } from '~/server/utils/redis';
+
+const redis = getRedis();
+if (redis) {
+  await redis.hset(toRedisKey('/users/abc/settings'), { theme: 'dark' });
+  const theme = await redis.hget(toRedisKey('/users/abc/settings'), 'theme');
+}
+```
+
+Returns `null` if KV is not configured (env vars missing). Always check.
+
+## Supabase (PostgreSQL)
+
+If Supabase is connected to the project, Vercel auto-injects these env vars:
+
+- `NUXT_PUBLIC_SUPABASE_URL` — Supabase project URL
+- `NUXT_PUBLIC_SUPABASE_ANON_KEY` — Public anon key (safe for client-side)
+- `SUPABASE_SERVICE_ROLE_KEY` — Server-only service role key (never expose to client)
+- `SUPABASE_DB_URL` — Direct Postgres connection string
+
+Use `@supabase/supabase-js` for the Supabase client:
+
+```typescript
+import { createClient } from '@supabase/supabase-js';
+
+const supabase = createClient(
+  process.env.NUXT_PUBLIC_SUPABASE_URL!,
+  process.env.SUPABASE_SERVICE_ROLE_KEY!,  // server routes only
+);
+
+const { data } = await supabase.from('my_table').select('*');
+```
+
+For client-side access, use the anon key instead of the service role key.
+
+## Key Differences from Client-Side Code
+
+- Server routes run on the server (Node.js), not in the browser
+- They have access to Redis, Supabase, secrets, and server-only APIs
+- They do NOT have access to Vue composables, Vuetify, or any client-side code
+- Use `defineEventHandler`, not Vue component patterns

package/rules/aether_something-broke.mdc

@@ -0,0 +1,73 @@
+---
+description: "Error recovery and build failure troubleshooting. Apply when something broke, build failed, npm run build errors, or user wants to restore previous behavior."
+alwaysApply: false
+---
+
+# Restoring Broken Functionality from Git History
+
+**Trigger phrases:** "this used to work", "this broke", "it was working before", "I want it back the way it was", "it looked right before", or similar.
+
+**Important:** If the user says it "just" worked or worked "a moment ago", the working version may not be in any commit yet — it may be an uncommitted change you made earlier in the conversation. In that case, review your own chat history to find what changed and revert it directly. This workflow is for restoring functionality that existed in a **previous commit**.
+
+## 1. Gather Context
+
+Ask the user:
+- What specifically broke or changed?
+- When do they remember it last working? (A rough timeframe, a branch, a specific action, etc.)
+
+## 2. Find the Working Commit
+
+Use `git log` (with relevant flags like `--oneline`, `--since`, `-- <path>`) to locate a commit where the feature was working. Show candidates to the user so they can help narrow it down.
+
+## 3. Confirm the Working State
+
+Check out the candidate commit so the user can verify it's the version they want. Save any uncommitted work first and resolve any conflicts or discrepancies that arise when switching between commits.
+
+If it's not right, try other commits. Collaborate with the user until the correct commit is identified. Once confirmed, return to the working branch.
+
+## 4. Extract Only What's Needed
+
+From the confirmed commit, extract **only** the parts that fix the regression — this could be entire files or as little as a single line. Do NOT blindly take the whole commit if only part of it is relevant.
+
+Show the user the combined result (current code + restored pieces) and have them confirm it works as desired **before** creating a commit.
+
+## 5. Commit the Restoration
+
+Only after the user confirms the restored version is correct, follow the standard git workflow (see `git-support.mdc`) to commit the changes.
+
+# Common Build Errors
+
+When `npm run build` fails, check these common causes:
+
+### `Cannot find module '~/composables/...'` or `'~/utils/...'`
+
+Wrong import path or the file doesn't exist. Nuxt auto-imports everything in `composables/` but NOT `utils/` -- use explicit imports for utils:
+
+```typescript
+import { myHelper } from '~/utils/myHelper';
+```
+
+### `Type 'X' is not assignable to type 'Y'`
+
+Usually an API response shape mismatch. Common case: `getSchema()` nests data under `response.schema` but TypeScript types suggest top-level access. See the `api` rule's API Gotchas section.
+
+### `SyntaxError` or blank page with "missing export"
+
+Nuxt's auto-import scanner misdetected a function parameter as an export. Verify the `imports:dirs` hook in `nuxt.config.ts` excludes `utils/` from scanning:
+
+```typescript
+hooks: {
+    'imports:dirs': (dirs: string[]) => {
+        const idx = dirs.findIndex((d) => d.endsWith('/utils'));
+        if (idx !== -1) dirs.splice(idx, 1);
+    },
+},
+```
+
+### Prettier pre-commit failure
+
+Run `npm run format` then `git add -A` and retry the commit. Do not run Prettier directly -- always use `npm run format`.
+
+### `sh: nuxt: command not found`
+
+Dependencies aren't installed. Run `npm install` first.

package/rules/aether_ui.mdc

@@ -0,0 +1,76 @@
+---
+description: Apply when creating or editing page templates, layouts, scrollable content, data tables, or loading states in Vue/Vuetify components.
+alwaysApply: false
+---
+
+# UI Patterns
+
+## Vuetify Layout System
+
+- Use `fill-height` class on containers that need full height
+- Use Vuetify components (`v-card`, `v-btn`, `v-data-table`) over custom implementations
+- Use Vuetify spacing utilities (`pa-4`, `ma-2`) and grid system (`v-row`, `v-col`)
+
+## Page Layout Template
+
+For pages with a header and scrollable content, use flexbox:
+- `d-flex flex-column` on the column container
+- `flex-shrink-0` on fixed elements (header, toolbar)
+- `flex-grow-1 overflow-y-auto` on scrollable content
+- Never use `calc(100vh - Xpx)` -- let flexbox handle sizing
+- Never nest multiple scroll containers
+
+Full page template covering all four data states (loading, error, empty, content):
+
+```vue
+<template>
+    <div class="d-flex flex-column fill-height">
+        <div class="flex-shrink-0 pa-4">
+            <PageHeader title="Page Title" icon="mdi-view-dashboard" />
+        </div>
+        <div class="flex-grow-1 overflow-y-auto pa-4">
+            <v-progress-circular v-if="loading" indeterminate class="ma-auto d-block" />
+            <v-alert v-else-if="error" type="error" variant="tonal" closable>
+                {{ error }}
+            </v-alert>
+            <v-empty-state
+                v-else-if="!items.length"
+                headline="No data yet"
+                icon="mdi-database-off"
+            />
+            <div v-else>
+                <!-- Content here -->
+            </div>
+        </div>
+    </div>
+</template>
+```
+
+## Dialogs
+
+- Cards inside `v-dialog` automatically get `variant="flat"` (solid background) via the nested Vuetify default in `nuxt.config.ts`. No manual override needed.
+- Use `v-card` directly inside `v-dialog` — it will have a solid surface background despite the global `outlined` default.
+- See the **cookbook** rule for a full dialog pattern.
+
+## Loading States
+
+Use `v-progress-circular` for inline loading and `v-skeleton-loader` for layout-preserving placeholders:
+
+```vue
+<v-progress-circular v-if="loading" indeterminate />
+<div v-else>
+    <!-- Content -->
+</div>
+```
+
+## Data Tables
+
+```vue
+<v-data-table :headers="headers" :items="items" :loading="loading" density="comfortable" hover>
+    <template v-slot:item.actions="{ item }">
+        <v-btn icon size="small" @click="selectItem(item)">
+            <v-icon>mdi-eye</v-icon>
+        </v-btn>
+    </template>
+</v-data-table>
+```

package/skills/aether_test-api-queries/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: test-api-queries
+description: Test Elemental API queries before integrating into app code. Use when writing code that calls the query server.
+---
+
+# Test API Queries
+
+**When writing code that calls the Query Server, test queries with this CLI tool before integrating them into app code.**
+
+This prevents wasted iteration cycles from incorrect assumptions about API responses.
+
+## Workflow
+
+1. **Test the query** using the CLI tool below
+2. **Verify the response** matches what you expect
+3. **Then write the app code** with confidence
+
+## CLI Tool
+
+Location: `~/.cursor/skills/test-api-queries/query-api.js`
+
+### Requirements
+
+The CLI reads these from the project's `.env` file or shell environment:
+
+- `AUTH0_M2M_DEV_TOKEN` - Auth0 M2M dev token for API access
+- `NUXT_PUBLIC_QUERY_SERVER_ADDRESS` - Query server URL
+
+**Before using this tool**, check that both variables are set in the project's `.env` file. If either is missing or empty, add them to `.env` (see `.env.example` for the format). Tell the user to ask the engineering team for the token value if they don't have it.
+
+### Usage
+
+```bash
+node ~/.cursor/skills/test-api-queries/query-api.js <METHOD> <ENDPOINT> [JSON_PARAMS]
+```
+
+### Examples
+
+```bash
+# Search for entities by name
+node ~/.cursor/skills/test-api-queries/query-api.js POST /entities/search \
+  '{"queries":[{"queryId":1,"query":"Apple"}],"maxResults":3}'
+
+# Get entity details by ID
+node ~/.cursor/skills/test-api-queries/query-api.js GET /entities/00416400910670863867
+
+# Find entities by type
+node ~/.cursor/skills/test-api-queries/query-api.js POST /elemental/find \
+  '{"expression":{"type":"is_type","is_type":{"fid":10}},"limit":5}'
+
+# Find entities with a specific property
+node ~/.cursor/skills/test-api-queries/query-api.js POST /elemental/find \
+  '{"expression":{"type":"comparison","comparison":{"operator":"has_value","pid":313}},"limit":10}'
+
+# Get entity properties
+node ~/.cursor/skills/test-api-queries/query-api.js POST /elemental/entities/properties \
+  '{"eids":["00416400910670863867"],"pids":[8,313]}'
+```
+
+### Notes
+
+- Run from the project directory so the `.env` file is found
+- `/elemental/find` and `/elemental/entities/properties` require form-encoded bodies—the tool handles this automatically