@yottagraph-app/aether-instructions 1.1.41 → 1.1.43

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

@@ -1,7 +1,3 @@
----
-description: "Data access via Elemental API: client usage, schema discovery, entity search, API gotchas, MCP servers. Read when building features that fetch or display data from the Query Server."
-alwaysApply: false
----
 # Data — Elemental API (platform data source)
 
 **This app is built on the Lovelace platform.** The Query Server is the
@@ -81,10 +77,10 @@ Test those with curl before implementing them in code.
 The gateway proxy authenticates on your behalf — no Auth0 tokens needed.
 Read `broadchurch.yaml` for the three values you need:
 
-| YAML path | Purpose |
-|---|---|
-| `gateway.url` | Portal Gateway base URL |
-| `tenant.org_id` | Your tenant ID (path segment) |
+| YAML path            | Purpose                              |
+| -------------------- | ------------------------------------ |
+| `gateway.url`        | Portal Gateway base URL              |
+| `tenant.org_id`      | Your tenant ID (path segment)        |
 | `gateway.qs_api_key` | API key (sent as `X-Api-Key` header) |
 
 Build the request URL as `{gateway.url}/api/qs/{tenant.org_id}/{endpoint}`
@@ -141,9 +137,9 @@ Elemental API patterns. **Use these instead of writing from scratch:**
 
 ```typescript
 const { flavors, properties, flavorByName, pidByName, refresh } = useElementalSchema();
-await refresh();                                // fetches once, then cached
-const articleFid = flavorByName('article');      // → string | null
-const namePid = pidByName('name');              // → string | null
+await refresh(); // fetches once, then cached
+const articleFid = flavorByName('article'); // → string | null
+const namePid = pidByName('name'); // → string | null
 ```
 
 Handles the dual response shapes (`res.schema.flavors` vs `res.flavors`)
@@ -152,14 +148,20 @@ and the `fid`/`findex` naming inconsistency automatically.
 ### `utils/elementalHelpers` — Gateway URL Helpers
 
 ```typescript
-import { buildGatewayUrl, getApiKey, padNeid, searchEntities, getEntityName } from '~/utils/elementalHelpers';
-
-const url = buildGatewayUrl('entities/search');   // full gateway URL
-const key = getApiKey();                          // from runtimeConfig
-const neid = padNeid('4926132345040704022');       // → "04926132345040704022"
+import {
+    buildGatewayUrl,
+    getApiKey,
+    padNeid,
+    searchEntities,
+    getEntityName,
+} from '~/utils/elementalHelpers';
+
+const url = buildGatewayUrl('entities/search'); // full gateway URL
+const key = getApiKey(); // from runtimeConfig
+const neid = padNeid('4926132345040704022'); // → "04926132345040704022"
 
 const results = await searchEntities('Microsoft'); // batch name search
-const name = await getEntityName(neid);            // display name lookup
+const name = await getEntityName(neid); // display name lookup
 ```
 
 ## Client Usage
@@ -174,7 +176,10 @@ const client = useElementalClient();
 
 const schema = await client.getSchema();
 const entities = await client.findEntities({
-    expression: JSON.stringify({ type: 'comparison', comparison: { operator: 'string_like', pid: 8, value: 'Apple' } }),
+    expression: JSON.stringify({
+        type: 'comparison',
+        comparison: { operator: 'string_like', pid: 8, value: 'Apple' },
+    }),
     limit: 5,
 });
 ```
@@ -185,8 +190,8 @@ All methods return data directly and throw on non-2xx responses.
 
 **Entity search and lookup:**
 
-| Method | Signature | Purpose |
-|---|---|---|
+| Method         | Signature                  | Purpose                                 |
+| -------------- | -------------------------- | --------------------------------------- |
 | `findEntities` | `(body: FindEntitiesBody)` | Expression-based search (see `find.md`) |
 
 > **Entity search**: Use `findEntities()` with `string_like` on the name PID
@@ -201,25 +206,25 @@ All methods return data directly and throw on non-2xx responses.
 
 **Properties and schema:**
 
-| Method | Signature | Purpose |
-|---|---|---|
-| `getSchema` | `()` | All entity types (flavors) and properties (PIDs) |
+| Method              | Signature                                | Purpose                                                                              |
+| ------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------ |
+| `getSchema`         | `()`                                     | All entity types (flavors) and properties (PIDs)                                     |
 | `getPropertyValues` | `(body: { eids: string, pids: string })` | Property values (eids: JSON array of NEID strings; pids: JSON array of numeric PIDs) |
-| `summarizeProperty` | `(pid: number)` | Summary stats for a property |
+| `summarizeProperty` | `(pid: number)`                          | Summary stats for a property                                                         |
 
 **Relationships and graph:**
 
-| Method | Signature | Purpose |
-|---|---|---|
+| Method         | Signature                        | Purpose                                                      |
+| -------------- | -------------------------------- | ------------------------------------------------------------ |
 | `findEntities` | `(body: { expression, limit? })` | Find linked entities via `linked` expression (see `find.md`) |
 
 **Other:**
 
-| Method | Signature | Purpose |
-|---|---|---|
-| `getHealth` | `()` | Health check |
-| `getStatus` | `()` | Server status and capabilities |
-| `adaMessage` | `(body: AdaMessageBody)` | Ada AI chat |
+| Method       | Signature                | Purpose                        |
+| ------------ | ------------------------ | ------------------------------ |
+| `getHealth`  | `()`                     | Health check                   |
+| `getStatus`  | `()`                     | Server status and capabilities |
+| `adaMessage` | `(body: AdaMessageBody)` | Ada AI chat                    |
 
 ## Discovery-First Pattern
 
@@ -230,16 +235,16 @@ types or property names. Instead, discover them at runtime:
 1. **Get the schema** — `client.getSchema()` returns all entity types (flavors)
    and properties (PIDs) available in the system. See `schema.md`.
 
-   The schema response contains:
-   - **Flavors** (entity types): Company, Person, GovernmentOrg, etc.
-     Each flavor has a numeric ID and a human-readable name.
-   - **PIDs** (properties): name, country, industry, lei_code, etc.
-     Each PID has a type (`data_str`, `data_int`, `data_nindex`, etc.).
-   - Properties with type `data_nindex` are references to other entities —
-     resolve them with another `getPropertyValues` call.
+    The schema response contains:
+    - **Flavors** (entity types): Company, Person, GovernmentOrg, etc.
+      Each flavor has a numeric ID and a human-readable name.
+    - **PIDs** (properties): name, country, industry, lei_code, etc.
+      Each PID has a type (`data_str`, `data_int`, `data_nindex`, etc.).
+    - Properties with type `data_nindex` are references to other entities —
+      resolve them with another `getPropertyValues` call.
 
-   Use flavor names in `findEntities()` expressions and PID names in
-   `getPropertyValues()`.
+    Use flavor names in `findEntities()` expressions and PID names in
+    `getPropertyValues()`.
 
 2. **Search with expressions** — `client.findEntities()` uses a JSON expression
    language to search by type, property value, or relationship. See `find.md`.
@@ -269,10 +274,10 @@ For reliable agent behavior, prefer typed semantics over string heuristics:
 
 There are two schema endpoints with **different response shapes**:
 
-| Endpoint | Flavors at | Flavor ID field | Detail level |
-|----------|-----------|-----------------|--------------|
-| `GET /schema` | top-level (`res.flavors`) | `findex` | Rich (display names, units, domains) |
-| `GET /elemental/metadata/schema` | nested (`res.schema.flavors`) | `fid` | Basic (name + type only) |
+| Endpoint                         | Flavors at                    | Flavor ID field | Detail level                         |
+| -------------------------------- | ----------------------------- | --------------- | ------------------------------------ |
+| `GET /schema`                    | top-level (`res.flavors`)     | `findex`        | Rich (display names, units, domains) |
+| `GET /elemental/metadata/schema` | nested (`res.schema.flavors`) | `fid`           | Basic (name + type only)             |
 
 The TypeScript client's `getSchema()` calls `/elemental/metadata/schema`,
 so the response nests data under `.schema`. The generated types may suggest
@@ -296,12 +301,12 @@ The flavor identifier has **different field names** depending on the endpoint:
 Same value, different key. Always use a fallback:
 
 ```typescript
-const articleFlavor = flavors.find(f => f.name === 'article');
+const articleFlavor = flavors.find((f) => f.name === 'article');
 // Always use String() — safe for small IDs (12) and required for large ones
 const articleFid = String(articleFlavor?.fid ?? articleFlavor?.findex ?? '');
 
 // When building a FID lookup map:
-const fidMap = new Map(flavors.map(f => [String(f.fid ?? f.findex), f.name]));
+const fidMap = new Map(flavors.map((f) => [String(f.fid ?? f.findex), f.name]));
 ```
 
 The `is_type` expression in `/elemental/find` always uses the `fid` key
@@ -352,14 +357,14 @@ const filingNeid = String(res.values[0].value).padStart(20, '0'); // "0492613234
 ```typescript
 // WRONG — PIDs are numbers, not strings:
 const values = await client.getPropertyValues({
-  eids: JSON.stringify(['00416400910670863867']),
-  pids: JSON.stringify(['name', 'country', 'industry']),  // FAILS
+    eids: JSON.stringify(['00416400910670863867']),
+    pids: JSON.stringify(['name', 'country', 'industry']), // FAILS
 });
 
 // CORRECT — use numeric PIDs from getSchema():
 const values = await client.getPropertyValues({
-  eids: JSON.stringify(['00416400910670863867']),
-  pids: JSON.stringify([8, 313]),  // 8=name, 313=country (from schema)
+    eids: JSON.stringify(['00416400910670863867']),
+    pids: JSON.stringify([8, 313]), // 8=name, 313=country (from schema)
 });
 ```
 
@@ -409,7 +414,7 @@ const res = await client.getPropertyValues({
 const docNeids = (res.values ?? []).map((v) => String(v.value).padStart(20, '0'));
 ```
 
-See the **cookbook-data** rule for a full "Get filings for a company" recipe.
+See [cookbook-data.md](cookbook-data.md) in this skill for a full "Get filings for a company" recipe.
 
 ### Expression language pitfalls
 
@@ -455,14 +460,17 @@ source-specific schemas.
   `getPropertyValues()` with the relationship PID. Values are entity IDs
   that must be zero-padded to 20 characters.
 
-See the **cookbook-data** rule (news feed recipe) for a full example.
+See [cookbook-data.md](cookbook-data.md) (news feed recipe) for a full example.
 
 ## Error Handling
 
 ```typescript
 try {
     const data = await client.findEntities({
-        expression: JSON.stringify({ type: 'comparison', comparison: { operator: 'string_like', pid: 8, value: 'Apple' } }),
+        expression: JSON.stringify({
+            type: 'comparison',
+            comparison: { operator: 'string_like', pid: 8, value: 'Apple' },
+        }),
         limit: 5,
     });
 } catch (error) {
@@ -479,7 +487,9 @@ functions instead:
 import { getArticle } from '@yottagraph-app/elemental-api/client';
 
 const response = await getArticle(artid);
-if (response.status === 404) { /* handle not found */ }
+if (response.status === 404) {
+    /* handle not found */
+}
 ```
 
 ## Lovelace MCP Servers
@@ -490,25 +500,25 @@ data exploration. **Check your tool list** — if tools like
 exploration interface before writing code. If they don't appear, the
 servers aren't connected; use curl and the skill docs instead.
 
-| Server | What it provides |
-|---|---|
-| `lovelace-elemental` | Knowledge Graph: entities, relationships, events, sentiment, schema discovery |
-| `lovelace-stocks` | Stock/financial market data |
-| `lovelace-wiki` | Wikipedia entity enrichment |
-| `lovelace-polymarket` | Prediction market data |
+| Server                | What it provides                                                              |
+| --------------------- | ----------------------------------------------------------------------------- |
+| `lovelace-elemental`  | Knowledge Graph: entities, relationships, events, sentiment, schema discovery |
+| `lovelace-stocks`     | Stock/financial market data                                                   |
+| `lovelace-wiki`       | Wikipedia entity enrichment                                                   |
+| `lovelace-polymarket` | Prediction market data                                                        |
 
 ### MCP Tool Quick Reference
 
-| Tool | Purpose | Use to verify... |
-|---|---|---|
-| `elemental_get_schema` | Discover entity types (flavors), properties, and relationships | Flavor IDs, property IDs, data types |
-| `elemental_get_entity` | Look up entity by name or NEID; returns properties | Entity resolution, property shapes |
-| `elemental_get_related` | Related entities with type/relationship filters | Relationship types and traversal |
-| `elemental_get_relationships` | Relationship types and counts between two entities | Edge types between specific entities |
-| `elemental_graph_neighborhood` | Most influential neighbors of an entity | Graph connectivity |
-| `elemental_graph_sentiment` | Sentiment analysis from news articles | Sentiment data availability |
-| `elemental_get_events` | Events for an entity or by search query | Event categories and shapes |
-| `elemental_health` | Health check | Server connectivity |
+| Tool                           | Purpose                                                        | Use to verify...                     |
+| ------------------------------ | -------------------------------------------------------------- | ------------------------------------ |
+| `elemental_get_schema`         | Discover entity types (flavors), properties, and relationships | Flavor IDs, property IDs, data types |
+| `elemental_get_entity`         | Look up entity by name or NEID; returns properties             | Entity resolution, property shapes   |
+| `elemental_get_related`        | Related entities with type/relationship filters                | Relationship types and traversal     |
+| `elemental_get_relationships`  | Relationship types and counts between two entities             | Edge types between specific entities |
+| `elemental_graph_neighborhood` | Most influential neighbors of an entity                        | Graph connectivity                   |
+| `elemental_graph_sentiment`    | Sentiment analysis from news articles                          | Sentiment data availability          |
+| `elemental_get_events`         | Events for an entity or by search query                        | Event categories and shapes          |
+| `elemental_health`             | Health check                                                   | Server connectivity                  |
 
 MCP tools handle entity resolution, PID lookups, and NEID formatting
 automatically. Use them to discover IDs and verify data exists before

package/skills/aether/deployment.md

@@ -0,0 +1,14 @@
+### App (Nuxt UI + server routes)
+
+Vercel auto-deploys on every push to `main`. Preview deployments are created for
+other branches. The app is available at `{slug}.yottagraph.app`.
+
+### Agents (`agents/`)
+
+Each subdirectory in `agents/` is a self-contained Python ADK agent. Deploy via
+the Portal UI or `/deploy_agent` in Cursor.
+
+### MCP Servers (`mcp-servers/`)
+
+Each subdirectory in `mcp-servers/` is a Python FastMCP server. Deploy via
+the Portal UI or `/deploy_mcp` in Cursor.

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

@@ -1,8 +1,3 @@
----
-description: "DESIGN.md workflow, feature docs, starter app is placeholder. Read when starting work, planning features, or updating project design."
-alwaysApply: false
----
-
 # Design
 
 Read `DESIGN.md` before starting any work. It is the source of truth for project vision, architecture, and current implementation status.
@@ -58,4 +53,4 @@ If the user is implementing a change that has no feature doc, encourage them to
 
 **Exception for initial app builds:** When building a new app from scratch via `/build_my_app`, skip per-page feature docs. They add overhead during greenfield builds where the entire app is being created at once. Start using feature docs once the initial app is built and you're iterating on individual features.
 
-It is a good practice to close out one feature doc and start a new one as the focus of the work shifts. It is acceptable to be working with multiple feature docs at once, if the user is working on multiple unconnected or loosely connected features. The sections of the feature doc are flexible and you should add or remove sections to fit the needs of the project.
+It is a good practice to close out one feature doc and start a new one as the focus of the work shifts. It is acceptable to be working with multiple feature docs at once, if the user is working on multiple unconnected or loosely connected features. The sections of the feature doc are flexible and you should add or remove sections to fit the needs of the project.

package/skills/aether/env.md

@@ -0,0 +1,10 @@
+| Variable                           | Purpose                          | Default                                 |
+| ---------------------------------- | -------------------------------- | --------------------------------------- |
+| `NUXT_PUBLIC_APP_ID`               | Unique app identifier            | derived from directory name             |
+| `NUXT_PUBLIC_APP_NAME`             | Display name                     | derived from directory name             |
+| `NUXT_PUBLIC_USER_NAME`            | Set to any value to bypass Auth0 | `dev-user` in local mode                |
+| `NUXT_PUBLIC_QUERY_SERVER_ADDRESS` | Query Server URL                 | read from `broadchurch.yaml` if present |
+| `NUXT_PUBLIC_GATEWAY_URL`          | Portal Gateway for agent chat    | read from `broadchurch.yaml` if present |
+| `NUXT_PUBLIC_TENANT_ORG_ID`        | Auth0 org ID for this tenant     | read from `broadchurch.yaml` if present |
+
+See `.env.example` for the full list.

package/{rules/git-support.mdc → skills/aether/git-support.md}

@@ -1,11 +1,6 @@
----
-description: "Git commit workflow and conventions. Apply when finishing implementation work, making commits, or troubleshooting git/pre-commit failures."
-alwaysApply: false
----
-
 # Git Workflow
 
-This rule applies both when an agent is committing its own work and when helping a user commit theirs.
+This guidance applies both when an agent is committing its own work and when helping a user commit theirs.
 
 ## Committing
 
@@ -14,9 +9,9 @@ Commit when you finish a meaningful unit of work — a feature, a fix, a refacto
 ### Steps
 
 1. **Run formatting first** — this is required or the commit will fail:
-   ```bash
-   npm run format
-   ```
+    ```bash
+    npm run format
+    ```
 2. **Stage all files** — always use `git add -A`.
 3. **Commit** with the message format below.
 4. **Verify the commit succeeded** with `git status`. If it failed, see Pre-commit Failure Troubleshooting below. Do not proceed until the commit is confirmed.

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/skills/aether/local-setup.md

@@ -0,0 +1,15 @@
+## Manual / Local Setup
+
+Node 20 is the baseline (pinned in `.nvmrc`). Newer versions generally work.
+
+```bash
+npm run init -- --local   # creates .env with dev defaults (no Auth0)
+npm install               # all deps are public on npmjs.com -- no tokens needed
+npm run dev               # dev server on port 3000
+```
+
+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"