@yottagraph-app/aether-instructions 1.1.41 → 1.1.43

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
 

package/skills/elemental-mcp-patterns/SKILL.md

@@ -27,7 +27,7 @@ from google.adk.tools.mcp_tool import McpToolset
 from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
 ```
 
-> **Do NOT use `SseConnectionParams`.**  `SseConnectionParams` is for
+> **Do NOT use `SseConnectionParams`.** `SseConnectionParams` is for
 > legacy SSE-based MCP servers. Using it against the Elemental MCP server
 > will silently fail — the agent starts with zero tools and no error is
 > raised. The LLM then hallucinates tool calls.
@@ -95,12 +95,14 @@ McpToolset(
 
 If `McpToolset` cannot connect, **no error is raised at agent startup**.
 The agent simply has zero MCP tools. Symptoms:
+
 - The agent never calls any `elemental_*` tools
 - The LLM fabricates code or data instead of using tools
 - No connection error in logs
 
 **Always validate** the MCP URL and check for tool availability during
 development. If MCP tools aren't working, verify:
+
 1. The URL is correct (check `broadchurch.yaml` `mcp.elemental` or env var)
 2. You're using `StreamableHTTPConnectionParams` (not `SseConnectionParams`)
 3. The MCP server is reachable (try `curl -X POST <url> -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'`)
@@ -120,42 +122,42 @@ adk web
 
 ## Tool Quick Reference
 
-| Tool | Use when you need to... |
-|---|---|
-| `elemental_get_entity` | Resolve an entity by name or ID, fetch its properties (supports `history` for time-series) |
-| `elemental_get_related` | Find related entities (requires `related_flavor`); use `direction` and `relationship_types` to filter |
-| `elemental_get_events` | Get typed events with categories, dates, participants |
-| `elemental_get_citations` | Look up provenance for `ref` hashes returned by other tools |
-| `elemental_get_schema` | Discover flavors (entity types), property names, and property types |
-| `elemental_get_relationships` | Get relationship types and counts between two entities |
-| `elemental_graph_neighborhood` | Get the most influential neighbors of an entity |
-| `elemental_graph_sentiment` | Sentiment time series, trend analysis, and statistics from news articles |
-| `elemental_introspect` | Discover what data **actually exists**: entity counts, populated properties with fill rates, sample values. Use before building features to verify data availability. |
-| `elemental_traverse` | Stateful graph navigation — build a working set of entities across multiple calls (start → expand → filter → inspect) |
-| `elemental_health` | Health check — verify MCP server connectivity |
+| Tool                           | Use when you need to...                                                                                                                                               |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `elemental_get_entity`         | Resolve an entity by name or ID, fetch its properties (supports `history` for time-series)                                                                            |
+| `elemental_get_related`        | Find related entities (requires `related_flavor`); use `direction` and `relationship_types` to filter                                                                 |
+| `elemental_get_events`         | Get typed events with categories, dates, participants                                                                                                                 |
+| `elemental_get_citations`      | Look up provenance for `ref` hashes returned by other tools                                                                                                           |
+| `elemental_get_schema`         | Discover flavors (entity types), property names, and property types                                                                                                   |
+| `elemental_get_relationships`  | Get relationship types and counts between two entities                                                                                                                |
+| `elemental_graph_neighborhood` | Get the most influential neighbors of an entity                                                                                                                       |
+| `elemental_graph_sentiment`    | Sentiment time series, trend analysis, and statistics from news articles                                                                                              |
+| `elemental_introspect`         | Discover what data **actually exists**: entity counts, populated properties with fill rates, sample values. Use before building features to verify data availability. |
+| `elemental_traverse`           | Stateful graph navigation — build a working set of entities across multiple calls (start → expand → filter → inspect)                                                 |
+| `elemental_health`             | Health check — verify MCP server connectivity                                                                                                                         |
 
 ### MCP Prompts
 
 The server also exposes built-in prompts that provide pre-composed
 workflows:
 
-| Prompt | Purpose |
-|---|---|
-| `company-deep-dive` | Comprehensive company research workflow |
-| `blast-radius` | Analyze impact/connections radiating from an entity |
-| `event-monitor` | Track events and developments for entities |
+| Prompt              | Purpose                                             |
+| ------------------- | --------------------------------------------------- |
+| `company-deep-dive` | Comprehensive company research workflow             |
+| `blast-radius`      | Analyze impact/connections radiating from an entity |
+| `event-monitor`     | Track events and developments for entities          |
 
 ### MCP Resources
 
 Documentation resources are available directly from the server:
 
-| Resource | Description |
-|---|---|
-| `elemental_data_model` | Entity types, properties, and relationships |
-| `elemental_guide` | Usage guide for the MCP tools |
-| `elemental_schema` | Live schema data |
-| `elemental_workflows` | Common workflow patterns and examples |
-| `elemental_mcp_server_info` | Server capabilities and configuration |
+| Resource                    | Description                                 |
+| --------------------------- | ------------------------------------------- |
+| `elemental_data_model`      | Entity types, properties, and relationships |
+| `elemental_guide`           | Usage guide for the MCP tools               |
+| `elemental_schema`          | Live schema data                            |
+| `elemental_workflows`       | Common workflow patterns and examples       |
+| `elemental_mcp_server_info` | Server capabilities and configuration       |
 
 These prompts and resources can be useful shortcuts — check if your MCP
 client supports them before building equivalent logic from scratch.
@@ -204,6 +206,7 @@ result = await mcp_call("elemental_get_entity", {
 ```
 
 Key points:
+
 - `entity` is `null` if resolution failed
 - Each property value is `{"value": ..., "ref"?: "...", "attributes"?: {...}}`
 - **`value` can be a NEID** for reference-typed properties — see
@@ -247,6 +250,7 @@ result = await mcp_call("elemental_get_related", {
 ```
 
 Key points:
+
 - `related_flavor` is **required** — you must specify what type of entity
   to look for
 - `resolved` is the center entity (can be `null` if resolution failed)
@@ -298,6 +302,7 @@ result = await mcp_call("elemental_get_events", {
 ```
 
 Key points:
+
 - Events have typed fields: `category`, `date`, `description`, `likelihood`
 - Use `categories` to filter — do NOT try to find events by scanning
   property names for keywords
@@ -383,13 +388,13 @@ def _format_large_number(n: float) -> str:
 
 ### Property type values you'll encounter
 
-| Schema type | Value is | How to display |
-|---|---|---|
-| `string` | Plain text | Display directly |
-| `integer`, `float` | Number | Format with units (check `unit` in schema) |
-| `nindex` | Entity NEID | **Must resolve** via `elemental_get_entity` |
-| `boolean` | `true`/`false` | Display as Yes/No |
-| `datetime` | ISO 8601 string | Format as human-readable date |
+| Schema type        | Value is        | How to display                              |
+| ------------------ | --------------- | ------------------------------------------- |
+| `string`           | Plain text      | Display directly                            |
+| `integer`, `float` | Number          | Format with units (check `unit` in schema)  |
+| `nindex`           | Entity NEID     | **Must resolve** via `elemental_get_entity` |
+| `boolean`          | `true`/`false`  | Display as Yes/No                           |
+| `datetime`         | ISO 8601 string | Format as human-readable date               |
 
 ---
 
@@ -538,14 +543,14 @@ tables below are a starting-point cheat sheet — not exhaustive.
 
 ### Properties by flavor
 
-| Flavor | Common properties |
-|---|---|
-| `organization` | `country` (nindex), `ticker_symbol`, `total_revenue`, `net_income`, `total_assets`, `industry` (nindex), `lei`, `company_cik`, `ein`, `website` |
-| `person` | `nationality` (nindex), `title`, `birth_date`, `gender` |
-| `government_body` | `country` (nindex), `jurisdiction` |
-| `article` | `headline`, `published_date`, `source`, `url` |
-| `event` | `category`, `date`, `description`, `likelihood` |
-| `financial_instrument` | `ticker_symbol`, `exchange`, `currency` |
+| Flavor                 | Common properties                                                                                                                               |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `organization`         | `country` (nindex), `ticker_symbol`, `total_revenue`, `net_income`, `total_assets`, `industry` (nindex), `lei`, `company_cik`, `ein`, `website` |
+| `person`               | `nationality` (nindex), `title`, `birth_date`, `gender`                                                                                         |
+| `government_body`      | `country` (nindex), `jurisdiction`                                                                                                              |
+| `article`              | `headline`, `published_date`, `source`, `url`                                                                                                   |
+| `event`                | `category`, `date`, `description`, `likelihood`                                                                                                 |
+| `financial_instrument` | `ticker_symbol`, `exchange`, `currency`                                                                                                         |
 
 Properties marked `(nindex)` are entity references — their raw value is
 a NEID that must be resolved to a display name. See "The Property Type
@@ -556,16 +561,16 @@ Problem" above.
 The `direction` parameter on `elemental_get_related` controls traversal.
 Getting it wrong returns zero results with no error.
 
-| Relationship | Meaning | Direction from center |
-|---|---|---|
-| `board_member_of` | Person sits on org's board | `"incoming"` when center is org |
-| `is_officer` | Person is an officer of org | `"incoming"` when center is org |
-| `subsidiary_of` | Org is a subsidiary of parent | `"outgoing"` from subsidiary |
-| `owns` | Entity owns another entity | `"outgoing"` from owner |
-| `appears_in` | Entity mentioned in article | `"both"` is usually safest |
-| `participant` | Entity participates in event | `"both"` is usually safest |
-| `filed` | Org filed a document | `"outgoing"` from org |
-| `works_at` | Person works at org | `"outgoing"` from person |
+| Relationship      | Meaning                       | Direction from center           |
+| ----------------- | ----------------------------- | ------------------------------- |
+| `board_member_of` | Person sits on org's board    | `"incoming"` when center is org |
+| `is_officer`      | Person is an officer of org   | `"incoming"` when center is org |
+| `subsidiary_of`   | Org is a subsidiary of parent | `"outgoing"` from subsidiary    |
+| `owns`            | Entity owns another entity    | `"outgoing"` from owner         |
+| `appears_in`      | Entity mentioned in article   | `"both"` is usually safest      |
+| `participant`     | Entity participates in event  | `"both"` is usually safest      |
+| `filed`           | Org filed a document          | `"outgoing"` from org           |
+| `works_at`        | Person works at org           | `"outgoing"` from person        |
 
 > **Tip:** If you're unsure about direction, use `"both"` (the default)
 > first and check the results. Then narrow to `"incoming"` or
@@ -627,6 +632,7 @@ Revenue was $52.9B [ref_a3f2b1c8]
 ```
 
 The chat UI translates these into numbered source citations. Rules:
+
 - Only include refs that are present in the actual response data
 - Copy the ref string exactly — never construct or modify refs
 - Omit the bracket when no ref is present for a value

package/variants/mcp-only/commands/build_my_app.md

@@ -11,7 +11,7 @@ Read the project brief and build the described application.
 - **Channeling** — Agents invoke MCP tools and return **natural-language** answers to the user (often chat-first; minimal or no Postgres for graph data).
 - **Mixes** — e.g. a sync job for dashboards plus a research agent plus a channel agent for Q&A.
 
-Read the **`data`** and **`agents-data`** cursor rules for detail.
+Read [`data.md`](../skills/aether/data.md) and [`agents-data.md`](../skills/aether/agents-data.md) in the `aether` skill for detail.
 
 **This is meant to be the first thing a user runs after opening their project in Cursor.**
 
@@ -78,7 +78,7 @@ If the file exists but tools aren't active yet:
 >
 > Open **Cursor Settings** (Cmd+Shift+J on macOS) → **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).
 
-Wait for confirmation before proceeding if you asked the user to enable servers. If the user skips or the panel isn't available (e.g. Cursor Cloud), proceed — you can still follow the **`data`** rule and ship agents that use MCP at **runtime**.
+Wait for confirmation before proceeding if you asked the user to enable servers. If the user skips or the panel isn't available (e.g. Cursor Cloud), proceed — you can still follow [`data.md`](../skills/aether/data.md) in the `aether` skill and ship agents that use MCP at **runtime**.
 
 The **Nuxt** layer may combine **your APIs** (often Postgres-backed), **chat** via **`useAgentChat`**, or both — not Elemental REST from Vue for graph data.
 
@@ -92,9 +92,9 @@ Read:
 
 1. `DESIGN.md` — which of the valid shapes above (or a mix) the brief implies
 2. `broadchurch.yaml`
-3. **`data` rule** — MCP-only patterns
-4. **`agents-data` rule** — wiring MCP into ADK
-5. **`cookbook-data` / `server` / `server-data`** — when the UI lists data from **your** APIs / Postgres
+3. [`data.md`](../skills/aether/data.md) in the `aether` skill — MCP-only patterns
+4. [`agents-data.md`](../skills/aether/agents-data.md) in the `aether` skill — wiring MCP into ADK
+5. [`cookbook-data.md`](../skills/aether/cookbook-data.md), [`server.md`](../skills/aether/server.md) and [`storage.md`](../skills/aether/storage.md), [`server-data.md`](../skills/aether/server-data.md) in the `aether` skill — when the UI lists data from **your** APIs (server routes) or **Postgres** (storage)
 
 ---
 
@@ -119,7 +119,7 @@ research assistant, investigation tool, etc.), build the agent FIRST:
 
 1. **`agents/`** — Build the full agent with all tools specified in DESIGN.md.
    Each named tool must be a Python function — do NOT just pass `McpToolset`
-   through and write a system prompt. Read the `agents` rule ("McpToolset
+   through and write a system prompt. Read [`agents.md`](../skills/aether/agents.md) in the `aether` skill ("McpToolset
    passthrough" section) for why this matters.
 2. Test the agent locally with `adk web` before building the UI.
 3. Then build the UI around the working agent.

package/variants/mcp-only/{rules/agents-data.mdc → skills/aether/agents-data.md}

@@ -1,9 +1,3 @@
----
-description: "MCP-only: ADK agents use Elemental MCP for sync, research, investigation, aggregation, or channeling — Postgres optional."
-alwaysApply: false
-globs: agents/**
----
-
 # Agents: Elemental MCP (MCP-only)
 
 In **mcp-only** mode, **Elemental MCP** is the primary way agents reach the knowledge graph. **`broadchurch_auth` HTTP** to the Query Server is the **api-mcp** path; here you wire **MCP tools** into ADK via **McpToolset** + **`StreamableHTTPConnectionParams`** to your Elemental MCP URL — from env or `broadchurch.yaml` / gateway.

package/variants/mcp-only/{rules/cookbook-data.mdc → skills/aether/cookbook-data.md}

@@ -1,8 +1,3 @@
----
-description: "MCP-only: UI recipes when data is exposed via your own APIs (often Postgres). Chat-first or agent-only flows may skip these."
-alwaysApply: false
----
-
 # Data-fetching cookbook (MCP-only)
 
 **Valid UIs for mcp-only include:** (a) **Chat-first** surfaces where the user talks to an agent that calls MCP tools (`useAgentChat`, agent design — see `data` / `agents-data`). (b) **List/detail/table** screens fed by **your** Nitro APIs, often backed by **Postgres** rows populated by agents that used Elemental MCP upstream.
@@ -19,7 +14,9 @@ Assume composables like `useEntities()` wrap `$fetch('/api/entities')` — adjus
 <template>
     <div class="d-flex flex-column fill-height pa-4">
         <h1 class="text-h5 mb-4">Entities</h1>
-        <v-alert v-if="error" type="error" variant="tonal" class="mb-4" closable>{{ error }}</v-alert>
+        <v-alert v-if="error" type="error" variant="tonal" class="mb-4" closable>{{
+            error
+        }}</v-alert>
         <v-data-table :items="items" :loading="loading" />
     </div>
 </template>

package/variants/mcp-only/{rules/data.mdc → skills/aether/data.md}

@@ -1,8 +1,3 @@
----
-description: "MCP-only data mode: no Elemental REST client in Nuxt; Elemental MCP is used by ADK agents — sync, research, or direct channeling."
-alwaysApply: false
----
-
 # Data — MCP-only (agents + Elemental MCP, not the Elemental API in the SPA)
 
 In **mcp-only** mode the Nuxt app does **not** call the Elemental API via `useElementalClient()` or gateway REST from the browser. **Elemental MCP** is how custom **ADK agents** reach the Lovelace knowledge graph.
@@ -28,7 +23,7 @@ In **mcp-only** mode the Nuxt app does **not** call the Elemental API via `useEl
 If you **do** use the sync pattern, treat Neon as the **read model** for those pages:
 
 1. **`DATABASE_URL`** — Use `getDb()` from `~/server/utils/neon.ts` in server routes.
-2. **Schema** — `CREATE TABLE IF NOT EXISTS` / `ensureTables()` (see `server` rule). Align columns with the **data-model** skill where relevant.
+2. **Schema** — `CREATE TABLE IF NOT EXISTS` / `ensureTables()` (see [storage.md](storage.md) in this skill). Align columns with the **data-model** skill where relevant.
 3. **Composables** — Thin wrappers around `$fetch('/api/...')` to your own APIs (`useEntities`, etc.).
 4. **Agents that populate tables** — Call Elemental MCP tools, map to rows, **UPSERT** idempotently. Document env (`DATABASE_URL`, MCP URL) in `DESIGN.md` or the agent README.
 

package/variants/mcp-only/{rules/server-data.mdc → skills/aether/server-data.md}

@@ -1,14 +1,8 @@
----
-description: "MCP-only: Nitro routes that read your own store (often Neon). Not used for proxying Elemental REST to the SPA."
-alwaysApply: false
-globs: server/**
----
-
 # Server routes: your data store (MCP-only)
 
 In mcp-only mode, **server routes do not** implement the **Elemental REST** proxy pattern from api-mcp for the **primary** SPA data path. Graph access lives in **agents + Elemental MCP**.
 
-This rule applies when your architecture includes a **local read model** (usually **Neon Postgres**) filled by agents that called MCP upstream. **Chat-only** or **agent-only** products may have **few or no** such routes — that is fine.
+This guidance applies when your architecture includes a **local read model** (usually **Neon Postgres**) filled by agents that called MCP upstream. **Chat-only** or **agent-only** products may have **few or no** such routes — that is fine.
 
 ## Pattern (Postgres-backed lists / detail)
 
@@ -16,24 +10,24 @@ This rule applies when your architecture includes a **local read model** (usuall
 import { getDb } from '~/server/utils/neon';
 
 export default defineEventHandler(async (event) => {
-  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 q = getQuery(event).q as string | undefined;
-  if (q) {
-    return await sql`
+    const q = getQuery(event).q as string | undefined;
+    if (q) {
+        return await sql`
       SELECT neid, name, updated_at FROM entities
       WHERE name ILIKE ${'%' + q + '%'}
       ORDER BY updated_at DESC LIMIT 50
     `;
-  }
-  return await sql`SELECT neid, name, updated_at FROM entities ORDER BY updated_at DESC LIMIT 50`;
+    }
+    return await sql`SELECT neid, name, updated_at FROM entities ORDER BY updated_at DESC LIMIT 50`;
 });
 ```
 
 ## `ensureTables`
 
-Call a shared `ensureTables()` before reads if tables might be missing on cold start (see `server` rule).
+Call a shared `ensureTables()` before reads if tables might be missing on cold start (see [storage.md](storage.md) in this skill).
 
 ## Secrets