@yottagraph-app/aether-instructions 1.1.42 → 1.1.43

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

@@ -1,8 +1,3 @@
----
-description: Warns users not to modify package-managed instruction files in .cursor/
-alwaysApply: false
----
-
 # Aether Instructions Warning
 
 **You are editing a file managed by the `@yottagraph-app/aether-instructions` package.**
@@ -10,9 +5,8 @@ alwaysApply: false
 Package-managed files are tracked by `.cursor/.aether-instructions-manifest`.
 They will be **overwritten** when you run `/update_instructions`.
 
-This includes files under `.cursor/rules/`, `.cursor/commands/`,
-`.cursor/skills/`, **and the root `AGENTS.md`** (tracked as `root/AGENTS.md`
-in the manifest).
+This includes files under `.cursor/commands/`, `.cursor/skills/`, **and the
+root `AGENTS.md`** (tracked as `root/AGENTS.md` in the manifest).
 
 ## Do Not
 
@@ -20,7 +14,7 @@ in the manifest).
 
 ## To Customize
 
-If you need to modify a package-provided rule, command, or the root `AGENTS.md`:
+If you need to modify a package-provided command, skill topic, or the root `AGENTS.md`:
 
 1. **Copy** the file to a new name
 2. Make your changes to the copy
@@ -30,8 +24,8 @@ If you need to modify a package-provided rule, command, or the root `AGENTS.md`:
 Examples:
 
 ```bash
-# Customize a rule
-cp .cursor/rules/data.mdc .cursor/rules/data_custom.mdc
+# Customize a skill topic
+cp .cursor/skills/aether/data.md .cursor/skills/aether/data_custom.md
 
 # Customize AGENTS.md
 cp AGENTS.md AGENTS.local.md
@@ -44,7 +38,7 @@ cp AGENTS.md AGENTS.local.md
 ## How It Works
 
 - `.cursor/.aether-instructions-manifest` lists every file installed by the
-  package (one relative path per line, e.g. `rules/data.mdc`). Entries
+  package (one relative path per line, e.g. `skills/aether/data.md`). Entries
   prefixed with `root/` refer to files at the tenant repo root
   (currently only `root/AGENTS.md`).
 - `/update_instructions` deletes manifest entries, extracts fresh files from

package/{rules/local-setup.mdc → skills/aether/local-setup.md}

@@ -1,8 +1,3 @@
----
-description: Manual local dev setup (npm run init --local, npm run dev). Apply when the environment check in AGENTS.md indicates local (non-Cursor-Cloud) and .env or node_modules are missing, or when the user asks how to run the app locally.
-alwaysApply: false
----
-
 ## Manual / Local Setup
 
 Node 20 is the baseline (pinned in `.nvmrc`). Newer versions generally work.
@@ -17,4 +12,4 @@ For the full interactive wizard (project name, Auth0, query server, etc.):
 
 ```bash
 npm run init              # interactive, or --non-interactive for CI (see --help)
-```
+```

package/{rules/mcp-servers.mdc → skills/aether/mcp-servers.md}

@@ -1,9 +1,3 @@
----
-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.
@@ -63,6 +57,7 @@ if __name__ == "__main__":
 ```
 
 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
@@ -88,6 +83,7 @@ python -m fastmcp run server:mcp --transport streamable-http --host 0.0.0.0 --po
 ## 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
@@ -102,7 +98,7 @@ Once deployed, agents can connect to your MCP server. Add the Cloud Run URL to y
 
 - One server per data domain or external service
 - Keep tools focused and well-documented
-- Return structured data (dicts/lists), not raw strings — MCP handles serialization via the protocol. (This differs from ADK agent tools, which should return formatted strings because the LLM reads tool output directly — see the `agents` rule.)
+- Return structured data (dicts/lists), not raw strings — MCP handles serialization via the protocol. (This differs from ADK agent tools, which should return formatted strings because the LLM reads tool output directly — see [agents.md](agents.md) in this skill.)
 - 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/pref.mdc → skills/aether/pref.md}

@@ -1,8 +1,3 @@
----
-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
@@ -28,7 +23,7 @@ const myPref = new Pref<string>(docPath, 'fieldName', 'defaultValue');
 await myPref.initialize();
 
 myPref.r.value; // reactive ref (use in templates)
-myPref.v;       // getter shorthand
+myPref.v; // getter shorthand
 myPref.set('new value'); // persists to KV
 ```
 
@@ -79,13 +74,13 @@ routes directly from client-side code:
 ```typescript
 // Read
 const value = await $fetch('/api/kv/read', {
-  params: { docPath: '/users/abc/settings', fieldName: 'theme' }
+    params: { docPath: '/users/abc/settings', fieldName: 'theme' },
 });
 
 // Write
 await $fetch('/api/kv/write', {
-  method: 'POST',
-  body: { docPath: '/users/abc/settings', fieldName: 'theme', value: '"dark"' }
+    method: 'POST',
+    body: { docPath: '/users/abc/settings', fieldName: 'theme', value: '"dark"' },
 });
 ```
 
@@ -121,8 +116,8 @@ function useMyFeaturePrefs() {
 
 ## Scope Guidance
 
-| App-specific | Global |
-|---|---|
-| Layout prefs, favorites | Language |
-| Watchlists, feature settings | Accessibility |
-| Feature-specific settings | Timezone, notifications |
+| App-specific                 | Global                  |
+| ---------------------------- | ----------------------- |
+| Layout prefs, favorites      | Language                |
+| Watchlists, feature settings | Accessibility           |
+| Feature-specific settings    | Timezone, notifications |

package/skills/aether/server-data.md

@@ -0,0 +1,48 @@
+# Server routes: Elemental API (Query Server)
+
+Server routes can call the Elemental API through the Portal Gateway proxy,
+just like client-side code does. The gateway URL, tenant org ID, and API key
+are available via `useRuntimeConfig()`.
+
+**NEVER use `readFileSync('broadchurch.yaml')` in server routes.** The YAML
+file is read at build time by `nuxt.config.ts` and its values flow into
+`runtimeConfig`. Nitro serverless functions (Vercel) don't bundle arbitrary
+project files — `readFileSync` will crash with ENOENT in production even
+though it works locally.
+
+```typescript
+export default defineEventHandler(async (event) => {
+    const { public: config } = useRuntimeConfig();
+
+    const gatewayUrl = config.gatewayUrl; // Portal Gateway base URL
+    const orgId = config.tenantOrgId; // Tenant org ID (path segment)
+    const apiKey = config.qsApiKey; // API key for X-Api-Key header
+
+    if (!gatewayUrl || !orgId) {
+        throw createError({ statusCode: 503, statusMessage: 'Gateway not configured' });
+    }
+
+    const res = await $fetch(`${gatewayUrl}/api/qs/${orgId}/entities/search`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            ...(apiKey && { 'X-Api-Key': apiKey }),
+        },
+        body: { queries: [{ queryId: 1, query: 'Microsoft' }], maxResults: 5 },
+    });
+
+    return res;
+});
+```
+
+Available runtime config keys (all under `runtimeConfig.public`):
+
+| Key                  | Source                                    | Purpose                        |
+| -------------------- | ----------------------------------------- | ------------------------------ |
+| `gatewayUrl`         | `broadchurch.yaml` → `gateway.url`        | Portal Gateway base URL        |
+| `tenantOrgId`        | `broadchurch.yaml` → `tenant.org_id`      | Tenant ID for API path         |
+| `qsApiKey`           | `broadchurch.yaml` → `gateway.qs_api_key` | API key sent as `X-Api-Key`    |
+| `queryServerAddress` | `broadchurch.yaml` → `query_server.url`   | Direct QS URL (prefer gateway) |
+
+Build the request URL as `{gatewayUrl}/api/qs/{tenantOrgId}/{endpoint}`.
+See [data.md](data.md) in this skill for endpoint reference and response shapes.

package/skills/aether/server.md

@@ -0,0 +1,60 @@
+# 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 (lazy-init from KV_REST_API_URL)
+    ├── neon.ts               # Neon Postgres client (lazy-init from DATABASE_URL) — create if missing when Neon is provisioned
+    └── cookies.ts            # Cookie handling (@hapi/iron)
+```
+
+For KV and Neon Postgres access (client usage, provisioning checks, creating
+tables, handling missing credentials gracefully), see
+[storage.md](storage.md) in this skill. For calling the platform Query
+Server from Nitro routes, see [server-data.md](server-data.md) in this
+skill.
+
+## 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' };
+});
+```
+
+## Key Differences from Client-Side Code
+
+- Server routes run on the server (Node.js), not in the browser
+- They have access to Redis, Neon Postgres, 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
+
+See [architecture.md](architecture.md) in this skill for the full data
+architecture overview, [storage.md](storage.md) for KV/Postgres patterns,
+and [pref.md](pref.md) for client-side KV preferences.

package/{rules/something-broke.mdc → skills/aether/something-broke.md}

@@ -1,8 +1,3 @@
----
-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.
@@ -12,6 +7,7 @@ alwaysApply: false
 ## 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.)
 
@@ -33,7 +29,7 @@ Show the user the combined result (current code + restored pieces) and have them
 
 ## 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.
+Only after the user confirms the restored version is correct, follow the standard git workflow (see [git-support.md](git-support.md) in this skill) to commit the changes.
 
 # Common Build Errors
 
@@ -49,7 +45,7 @@ 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 `data` rule's API Gotchas section.
+Usually an API response shape mismatch. Common case: `getSchema()` nests data under `response.schema` but TypeScript types suggest top-level access. See [data.md](data.md)'s API Gotchas section in this skill.
 
 ### `SyntaxError` or blank page with "missing export"
 

package/{rules/server.mdc → skills/aether/storage.md}

@@ -1,54 +1,36 @@
----
-description: Nitro server-side API routes and utilities in server/
-globs: server/**
-alwaysApply: false
----
+# Storage
 
-# Nitro Server Routes
+Two storage services are available. KV is always connected; Neon Postgres
+is only present if the tenant was provisioned with it. Each store has its
+own way of checking availability — see the **How to check** column below:
 
-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.
+| Store                  | How to check                                                                      | Env var                                 | Utility file                                              | Always available?                   |
+| ---------------------- | --------------------------------------------------------------------------------- | --------------------------------------- | --------------------------------------------------------- | ----------------------------------- |
+| **KV** (Upstash Redis) | `KV_REST_API_URL` in `.env`                                                       | `KV_REST_API_URL`, `KV_REST_API_TOKEN`  | `server/utils/redis.ts` (pre-scaffolded)                  | Yes                                 |
+| **Neon Postgres**      | `curl <gateway.url>/api/tenants/<tenant.org_id>` → `vercel.postgres_store_id` set | `DATABASE_URL`, `DATABASE_URL_UNPOOLED` | `server/utils/neon.ts` (create it if missing — see below) | Only if enabled at project creation |
 
-## Directory Layout
+Both utilities live in `server/utils/` and are consumed from Nitro server
+routes (`server/api/**`). For how to add a server route, see
+[server.md](server.md) in this skill. For client-side user preferences that
+sit on top of KV, see [pref.md](pref.md) in this skill.
 
-```
-server/
-├── api/
-│   ├── kv/                  # KV (Upstash Redis) CRUD — read, write, delete, documents, status
-│   └── avatar/[url].ts      # Avatar image proxy
-└── utils/
-    ├── redis.ts              # Upstash Redis client (lazy-init from KV_REST_API_URL)
-    ├── neon.ts               # Neon Postgres client (lazy-init from DATABASE_URL) — create if missing when Neon is provisioned
-    └── 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
-```
+## Where credentials come from
 
-Route handler pattern:
+**Deployed builds** (push to `main` → Vercel): storage env vars are
+auto-injected and decrypted at runtime. Storage works with zero
+configuration. **This is the primary development path** — push your code
+and test on the deployed preview/production URL.
 
-```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
+**Local dev / Cursor Cloud:** storage credentials are not yet available for
+local use. `getRedis()` and `getDb()` will return `null`, and the app should
+handle this gracefully (show a "not configured" state, use defaults, etc.).
+KV preferences fall back to their default values. Postgres features should
+check `getDb()` and show appropriate UI when it returns `null`.
 
-  // ... implementation ...
-  return { result: 'data' };
-});
-```
+This is a known platform limitation — the Broadchurch team is working on
+making storage credentials available for local development.
 
-## KV Storage (Upstash Redis)
+## KV (Upstash Redis)
 
 `server/utils/redis.ts` initializes the Upstash Redis client from env vars
 that Vercel auto-injects when a KV store is connected:
@@ -61,15 +43,16 @@ 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');
+    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.
+Returns `null` if KV is not configured (env vars missing). Always check
+before using.
 
 For client-side preferences, use `usePrefsStore()` and `Pref<T>` instead of
-calling KV routes directly — see the `pref` rule.
+calling KV routes directly — see [pref.md](pref.md) in this skill.
 
 ## Neon Postgres
 
@@ -91,7 +74,7 @@ curl <gateway.url>/api/tenants/<tenant.org_id>
   `DATABASE_URL` is also findable under `agent_secrets`, but you usually
   don't need to read it.
 - `server/utils/neon.ts` present → ready to use. If missing, create it
-  (mirror the `getDb()` lazy-init pattern in `server/utils/redis.ts`).
+  (see "If `server/utils/neon.ts` doesn't exist" below).
 - `@neondatabase/serverless` in `package.json` → ready. If missing, run
   `npm install @neondatabase/serverless`.
 
@@ -111,16 +94,16 @@ database on the deployed build, where credentials are auto-injected.
 import { getDb } from '~/server/utils/neon';
 
 export default defineEventHandler(async () => {
-  const sql = getDb();
-  if (!sql) throw createError({ statusCode: 503, statusMessage: 'Database not configured' });
+    const sql = getDb();
+    if (!sql) throw createError({ statusCode: 503, statusMessage: 'Database not configured' });
 
-  const rows = await sql`SELECT * FROM notes ORDER BY created_at DESC`;
-  return rows;
+    const rows = await sql`SELECT * FROM notes ORDER BY created_at DESC`;
+    return rows;
 });
 ```
 
 The Neon driver uses tagged template literals for automatic SQL injection
-protection — `await sql\`SELECT * FROM notes WHERE id = ${id}\`` is safe.
+protection — `await sql\`SELECT \* FROM notes WHERE id = ${id}\`` is safe.
 No ORM, no query builder, no connection pool setup needed.
 
 ### Creating tables
@@ -137,42 +120,12 @@ await sql`CREATE TABLE IF NOT EXISTS notes (
 )`;
 ```
 
-For simple apps, putting the `CREATE TABLE IF NOT EXISTS` in each route that
+For simple apps, putting `CREATE TABLE IF NOT EXISTS` in each route that
 uses the table is fine — it's a no-op after the first call. For more complex
 schemas, create a `server/api/db/setup.post.ts` route that initializes all
 tables.
 
-### If `server/utils/neon.ts` doesn't exist
-
-Create it manually (or re-run init):
-
-```bash
-npm install @neondatabase/serverless
-```
-
-```typescript
-// server/utils/neon.ts
-import { neon, type NeonQueryFunction } from '@neondatabase/serverless';
-
-let _sql: NeonQueryFunction | null = null;
-
-export function isDbConfigured(): boolean {
-  return Boolean(process.env.DATABASE_URL);
-}
-
-export function getDb(): NeonQueryFunction | null {
-  if (_sql) return _sql;
-  const url = process.env.DATABASE_URL;
-  if (!url) return null;
-  _sql = neon(url);
-  return _sql;
-}
-```
-
-For **Query Server / Elemental API** calls from server routes (gateway URL,
-`X-Api-Key`, request shapes), see the `server-data` rule.
-
-## Neon Postgres: Handle Missing Tables in GET Routes
+### Handle missing tables in GET routes
 
 Tables created by POST/setup routes won't exist on a fresh deployment.
 **Every GET route that queries a table must handle the case where the table
@@ -181,18 +134,18 @@ until the setup route runs.
 
 ```typescript
 export default defineEventHandler(async () => {
-  const sql = getDb();
-  if (!sql) throw createError({ statusCode: 503, statusMessage: 'Database not configured' });
-
-  try {
-    const rows = await sql`SELECT * FROM companies ORDER BY updated_at DESC`;
-    return rows;
-  } catch (err: any) {
-    if (err.message?.includes('does not exist')) {
-      return [];
+    const sql = getDb();
+    if (!sql) throw createError({ statusCode: 503, statusMessage: 'Database not configured' });
+
+    try {
+        const rows = await sql`SELECT * FROM companies ORDER BY updated_at DESC`;
+        return rows;
+    } catch (err: any) {
+        if (err.message?.includes('does not exist')) {
+            return [];
+        }
+        throw err;
     }
-    throw err;
-  }
 });
 ```
 
@@ -207,11 +160,11 @@ import { getDb } from '~/server/utils/neon';
 let _initialized = false;
 
 export async function ensureTables() {
-  if (_initialized) return;
-  const sql = getDb();
-  if (!sql) return;
+    if (_initialized) return;
+    const sql = getDb();
+    if (!sql) return;
 
-  await sql`CREATE TABLE IF NOT EXISTS companies (
+    await sql`CREATE TABLE IF NOT EXISTS companies (
     id SERIAL PRIMARY KEY,
     neid TEXT UNIQUE NOT NULL,
     name TEXT NOT NULL,
@@ -219,7 +172,7 @@ export async function ensureTables() {
     updated_at TIMESTAMPTZ DEFAULT NOW()
   )`;
 
-  _initialized = true;
+    _initialized = true;
 }
 ```
 
@@ -227,12 +180,29 @@ Then call `await ensureTables()` at the start of any route that reads the
 table. The `_initialized` flag makes it a no-op after the first call within
 the same serverless invocation.
 
-## Key Differences from Client-Side Code
+### If `server/utils/neon.ts` doesn't exist
+
+Create it manually (or re-run init):
+
+```bash
+npm install @neondatabase/serverless
+```
+
+```typescript
+// server/utils/neon.ts
+import { neon, type NeonQueryFunction } from '@neondatabase/serverless';
 
-- Server routes run on the server (Node.js), not in the browser
-- They have access to Redis, Neon Postgres, 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
+let _sql: NeonQueryFunction | null = null;
 
-See `architecture` rule for the full data architecture overview, `pref` rule
-for client-side KV preferences.
+export function isDbConfigured(): boolean {
+    return Boolean(process.env.DATABASE_URL);
+}
+
+export function getDb(): NeonQueryFunction | null {
+    if (_sql) return _sql;
+    const url = process.env.DATABASE_URL;
+    if (!url) return null;
+    _sql = neon(url);
+    return _sql;
+}
+```

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

@@ -1,8 +1,3 @@
----
-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
@@ -14,6 +9,7 @@ alwaysApply: false
 ## 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
@@ -50,7 +46,7 @@ Full page template covering all four data states (loading, error, empty, content
 
 - 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.
+- See [cookbook.md](cookbook.md) in this skill for a full dialog pattern.
 
 ## Loading States