@yottagraph-app/aether-instructions 1.1.42 → 1.1.44

package/AGENTS.md

@@ -1,12 +1,14 @@
 # Aether
 
+**Read first:** [`.cursor/skills/aether/SKILL.md`](.cursor/skills/aether/SKILL.md) — the Aether skill indexes every topic below and is the canonical entry point for any work in this repo.
+
 **Stack:** Nuxt 3 (SPA), Vue 3 Composition API (`<script setup>`), Vuetify 3, TypeScript (required), Auth0.
 
 **Structure:** `pages/` (file-based routing), `components/`, `composables/`, `server/api/`, `agents/` (Python ADK), `mcp-servers/` (Python FastMCP).
 
-**Data:** This app runs on the Lovelace platform -- entities, news, filings, sentiment, relationships, events. See the `data` rule for access patterns and gotchas. Skill docs: `skills/data-model/` (entity types, properties, relationships; `SKILL.md` first), `skills/elemental-mcp-patterns/` (MCP response shapes, property type handling, Python patterns for agent tools). Do NOT call external APIs for data the platform provides.
+**Data:** This app runs on the Lovelace platform -- entities, news, filings, sentiment, relationships, events. See [`data.md`](.cursor/skills/aether/data.md) in the `aether` skill for access patterns and gotchas. Additional skill docs: `skills/data-model/` (entity types, properties, relationships; `SKILL.md` first), `skills/elemental-mcp-patterns/` (MCP response shapes, property type handling, Python patterns for agent tools). Do NOT call external APIs for data the platform provides.
 
-**Storage:** KV (Upstash Redis) for preferences and lightweight state via `Pref<T>` from `usePrefsStore()`. Neon Postgres for relational data if connected (see the `storage` rule).
+**Storage:** KV (Upstash Redis) for preferences and lightweight state via `Pref<T>` from `usePrefsStore()`. Neon Postgres for relational data if connected (see [`storage.md`](.cursor/skills/aether/storage.md) in the `aether` skill).
 
 **Source of truth:** `DESIGN.md` -- read before starting work, update when changing features. The starter UI is placeholder -- replace freely. Feature docs in `design/` for implementation planning.
 
@@ -14,44 +16,24 @@
 
 **First action for a new project:** Run `/build_my_app`.
 
-## Task-specific rules
-
-Conditional rules, loaded based on what you're doing:
-
-- `architecture` — project structure, navigation, server routes, agents, MCP
-- `data` — Elemental API / data access patterns and gotchas
-- `cookbook` — copy-paste UI patterns
-- `cookbook-data` — data-fetching recipes
-- `design` — DESIGN.md workflow, feature docs
-- `ui` — page templates, layout patterns
-- `pref` — KV preferences
-- `branding` — colors, fonts
-- `server` — Nitro routes, Neon Postgres usage
-- `server-data` — server-side Elemental API from routes
-- `storage` — KV vs Neon availability and selection
-- `agents` — ADK agents
-- `agents-data` — agents calling Elemental API
-- `mcp-servers` — FastMCP server development
-- `deployment` — app, agent, and MCP server deployment
-- `env` — `.env` variable reference
-- `local-setup` — manual local dev setup
-- `cursor-cloud` — Cursor Cloud environment quirks
-- `git-support` — commit workflow and pre-commit troubleshooting
-- `something-broke` — error recovery, build failures
+## Task-specific topics
+
+The `aether` skill (`.cursor/skills/aether/SKILL.md`) covers architecture, data, UI cookbook, agents, MCP servers, deployment, env, storage, troubleshooting, and more. Read `SKILL.md` first; it's a short index that points you to the specific topic file you need.
 
 ## Environment
 
-Detect your runtime once at startup, then read the matching rule:
+Detect your runtime once at startup, then read the matching topic in the `aether` skill:
 
-- **Cursor Cloud** if `$HOME` starts with `/root` or `/home/ubuntu`, OR `uname -s` reports `Linux` in a container-shaped path, OR a "Dev Server" terminal was auto-started from `.cursor/environment.json`. → Read the `cursor-cloud` rule.
-- **Local dev** if `$HOME` is under `/Users/…` (macOS) or a normal Linux/Windows user home, and no "Dev Server" terminal is auto-running. → If `.env` and `node_modules/` are present, you're set up; otherwise read the `local-setup` rule.
+- **Cursor Cloud** if `$HOME` starts with `/root` or `/home/ubuntu`, OR `uname -s` reports `Linux` in a container-shaped path, OR a "Dev Server" terminal was auto-started from `.cursor/environment.json`. → Read [`cursor-cloud.md`](.cursor/skills/aether/cursor-cloud.md).
+- **Local dev** if `$HOME` is under `/Users/…` (macOS) or a normal Linux/Windows user home, and no "Dev Server" terminal is auto-running. → If `.env` and `node_modules/` are present, you're set up; otherwise read [`local-setup.md`](.cursor/skills/aether/local-setup.md).
 
 This check is cheap and only needs to run once per session.
 
 ### Cursor instructions (`.cursor/`)
 
-Cursor rules, commands, and skills are installed from the
+Cursor commands and skills are installed from the
 `@yottagraph-app/aether-instructions` npm package during project init.
+`.cursor/skills/aether/` is the main Aether skill.
 `.cursor/skills/elemental-api/` contains API skill documentation (endpoint
 reference, types, usage patterns). `.cursor/skills/data-model/` contains
 Lovelace data model documentation (entity types, schemas per fetch source).

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/README.md

@@ -1,6 +1,10 @@
 # @yottagraph-app/aether-instructions
 
-Cursor rules, commands, and skills for Aether development.
+Cursor commands and skills for Aether development.
+
+The core Aether guidance (architecture, data, UI, agents, MCP servers,
+deployment, etc.) ships as the **`aether` skill** under `skills/aether/`,
+with a `SKILL.md` entry point that indexes the topic files.
 
 ## Usage
 
@@ -19,18 +23,18 @@ This Cursor command will:
 
 1. Download the latest version of this package
 2. Replace files in `.cursor/` that are listed in `.cursor/.aether-instructions-manifest`
-3. Extract fresh files from the package
-4. Commit the changes
+3. Remove the deprecated `.cursor/rules/` directory if present (rules were replaced by the `aether` skill)
+4. Extract fresh files from the package
+5. Commit the changes
 
 ### File Naming Convention
 
-Package files keep their original names under `.cursor/rules/`,
-`.cursor/commands/`, and `.cursor/skills/`. Which paths are owned by the
-package is recorded in `.cursor/.aether-instructions-manifest`. Only those
-paths are overwritten on update; other files under `.cursor/` are not touched
-by the updater.
+Package files keep their original names under `.cursor/commands/` and
+`.cursor/skills/`. Which paths are owned by the package is recorded in
+`.cursor/.aether-instructions-manifest`. Only those paths are overwritten on
+update; other files under `.cursor/` are not touched by the updater.
 
-### Customizing Rules/Commands
+### Customizing Commands or Skill Topics
 
 To customize something that ships with the package:
 

package/commands/build_my_app.md

@@ -102,17 +102,16 @@ Then read these files to understand what's available:
 
 1. `DESIGN.md` -- project vision and current status
 2. `broadchurch.yaml` -- project config (name, gateway URL, etc.)
-3. **The `data` cursor rule** -- this is critical. It describes the Query Server, the platform's primary data source. Build against platform APIs, not external sources.
-4. **`.cursor/skills/`** — Each subdirectory is one skill. List them, open each skill’s entry (usually `SKILL.md`) and follow its structure to learn what is documented (APIs, schemas, helpers, etc.).
-5. `.cursor/rules/` -- scan rule names to know what other patterns are available
+3. **The `aether` skill's `data.md` topic** (`.cursor/skills/aether/data.md`) — this is critical. It describes the Query Server, the platform's primary data source. Build against platform APIs, not external sources.
+4. **`.cursor/skills/`** — Each subdirectory is one skill. Start with `.cursor/skills/aether/SKILL.md` — it's the index for every Aether topic (architecture, data, UI, agents, MCP, deployment, etc.). Then open each other skill's entry (usually `SKILL.md`) and follow its structure to learn what is documented (APIs, schemas, helpers, etc.).
 
-**Important: Use the platform's data.** This app runs on the Lovelace platform, which provides a Query Server with entities, news, filings, sentiment, relationships, events, and more. Read the `data` rule and the skills under `.cursor/skills/` to understand what data is available. Use `getSchema()` to discover entity types and properties at runtime.
+**Important: Use the platform's data.** This app runs on the Lovelace platform, which provides a Query Server with entities, news, filings, sentiment, relationships, events, and more. Read [`data.md`](../skills/aether/data.md) in the `aether` skill and the other skills under `.cursor/skills/` to understand what data is available. Use `getSchema()` to discover entity types and properties at runtime.
 
 Key capabilities:
 
-- **Query Server / Elemental API** -- the primary data source. Use `useElementalClient()` from `@yottagraph-app/elemental-api/client`. See the `data` rule.
-- **KV storage** -- always available for preferences and lightweight data (see `pref` rule)
-- **Neon Postgres** -- check if `DATABASE_URL` is in `.env` for database access (see `server` rule)
+- **Query Server / Elemental API** -- the primary data source. Use `useElementalClient()` from `@yottagraph-app/elemental-api/client`. See [`data.md`](../skills/aether/data.md) in the `aether` skill.
+- **KV storage** -- always available for preferences and lightweight data (see [`pref.md`](../skills/aether/pref.md) in the `aether` skill)
+- **Neon Postgres** -- may be available for relational data; see [`storage.md`](../skills/aether/storage.md) in the `aether` skill for how to check and how to use it
 - **AI agent chat** -- use the `useAgentChat` composable to build a chat UI for deployed agents
 - **MCP servers** -- Lovelace MCP servers may be available (check `.cursor/mcp.json`)
 - **Components** -- Vuetify 3 component library is available
@@ -191,7 +190,7 @@ Implement the plan:
 2. Extract reusable components into `components/`
 3. Put shared logic in `composables/`
 4. If the app needs navigation, add it to `app.vue` or to individual pages
-5. Use `Pref<T>` for any persisted settings (see `pref.mdc`)
+5. Use `Pref<T>` for any persisted settings (see [`pref.md`](../skills/aether/pref.md) in the `aether` skill)
 6. Use Vuetify components and the project's dark theme
 7. Update `DESIGN.md` with what you built
 

package/commands/deploy_agent.md

@@ -52,7 +52,7 @@ ls -d agents/*/
 > └── requirements.txt
 > ```
 >
-> See the `agents.mdc` rule for guidance on writing ADK agents.
+> See [`agents.md`](../skills/aether/agents.md) in the `aether` skill for guidance on writing ADK agents.
 
 Stop here.
 
@@ -118,12 +118,12 @@ curl -sf -X POST "<GATEWAY_URL>/api/projects/<ORG_ID>/deploy" \
 
 ```json
 {
-  "ok": true,
-  "method": "cloud-build",
-  "build_id": "...",
-  "log_url": "https://console.cloud.google.com/cloud-build/builds/...",
-  "target": "agents/<name>",
-  "repo": "<owner>/<repo>"
+    "ok": true,
+    "method": "cloud-build",
+    "build_id": "...",
+    "log_url": "https://console.cloud.google.com/cloud-build/builds/...",
+    "target": "agents/<name>",
+    "repo": "<owner>/<repo>"
 }
 ```
 

package/commands/update_branding.md

@@ -68,4 +68,4 @@ Compare logo and asset files in `public/` against the skill's `assets/` director
 
 ## Step 6: Commit
 
-Follow the `git-support.mdc` workflow to commit the changes.
+Follow the [`git-support.md`](../skills/aether/git-support.md) workflow in the `aether` skill to commit the changes.

package/commands/update_instructions.md

@@ -1,6 +1,6 @@
 # Update Instructions
 
-Update Cursor rules, commands, and skills from the `@yottagraph-app/aether-instructions` npm package.
+Update Cursor commands and skills from the `@yottagraph-app/aether-instructions` npm package.
 
 ## Overview
 
@@ -10,9 +10,10 @@ This command downloads the latest instructions package and extracts it to your `
 
 1. Downloads the latest `@yottagraph-app/aether-instructions` package
 2. Deletes files listed in the existing manifest
-3. Extracts fresh files from the package
-4. Writes a new manifest
-5. Commits the changes
+3. Removes the deprecated `.cursor/rules/` directory if present (rules were replaced by the `aether` skill)
+4. Extracts fresh files from the package
+5. Writes a new manifest
+6. Commits the changes
 
 **Your files are safe:** Only paths listed in the manifest are removed before reinstall. Other files under `.cursor/` are left alone.
 
@@ -71,7 +72,7 @@ The extracted content is in `$TEMP_DIR/package/`.
 
 ## Step 4: Delete Previously Installed Files
 
-Read the manifest and delete listed paths. **Skip blank lines** — an empty `rel` would run `rm -rf ".cursor/"` and wipe the whole directory. Entries prefixed with `root/` point at files at the repo root (currently just `AGENTS.md`); only remove **regular files** there, never directories.
+Read the manifest and delete listed paths. **Skip blank lines** — an empty `rel` would run `rm -rf ".cursor/"` and wipe the whole directory. Entries prefixed with `root/` point at files at the repo root (currently `AGENTS.md` and `CLAUDE.md`); only remove **regular files** there, never directories.
 
 ```bash
 if [ -f .cursor/.aether-instructions-manifest ]; then
@@ -91,6 +92,12 @@ if [ -f .cursor/.aether-instructions-manifest ]; then
 fi
 ```
 
+Also remove the deprecated `.cursor/rules/` directory (superseded by the `aether` skill in `.cursor/skills/aether/`):
+
+```bash
+rm -rf .cursor/rules
+```
+
 ---
 
 ## Step 5: Copy New Files
@@ -98,21 +105,21 @@ fi
 Create directories if needed:
 
 ```bash
-mkdir -p .cursor/rules .cursor/commands .cursor/skills
+mkdir -p .cursor/commands .cursor/skills
 ```
 
 Copy files from the extracted package:
 
 ```bash
-cp "$TEMP_DIR/package/rules/"* .cursor/rules/ 2>/dev/null || true
 cp "$TEMP_DIR/package/commands/"* .cursor/commands/ 2>/dev/null || true
 cp -r "$TEMP_DIR/package/skills/"* .cursor/skills/ 2>/dev/null || true
 ```
 
-Copy the root-level AGENTS.md from the package to the tenant repo root, if the package ships one:
+Copy the root-level AGENTS.md and CLAUDE.md from the package to the tenant repo root, if the package ships them. `CLAUDE.md` is a one-line `@AGENTS.md` pointer so Claude Code imports the same instructions Cursor reads from `AGENTS.md`:
 
 ```bash
 [ -f "$TEMP_DIR/package/AGENTS.md" ] && cp "$TEMP_DIR/package/AGENTS.md" ./AGENTS.md
+[ -f "$TEMP_DIR/package/CLAUDE.md" ] && cp "$TEMP_DIR/package/CLAUDE.md" ./CLAUDE.md
 ```
 
 ### Data-mode variant overlay
@@ -122,14 +129,17 @@ If this project uses **mcp-only** (or another non-default mode), re-apply the sa
 ```bash
 MODE=$(tr -d '\n' < .cursor/.aether-data-mode 2>/dev/null || echo "api-mcp")
 PKG="$TEMP_DIR/package"
-if [ "$MODE" != "api-mcp" ] && [ -d "$PKG/variants/$MODE/rules" ]; then
-  cp "$PKG/variants/$MODE/rules/"* .cursor/rules/ 2>/dev/null || true
-fi
 if [ "$MODE" != "api-mcp" ] && [ -d "$PKG/variants/$MODE/commands" ]; then
   cp "$PKG/variants/$MODE/commands/"* .cursor/commands/ 2>/dev/null || true
 fi
 if [ "$MODE" != "api-mcp" ] && [ -d "$PKG/variants/$MODE/skills" ]; then
-  cp -r "$PKG/variants/$MODE/skills/"* .cursor/skills/ 2>/dev/null || true
+  # Overlay per-file so default skill topics survive
+  for src_dir in "$PKG/variants/$MODE/skills/"*/; do
+    [ -d "$src_dir" ] || continue
+    dir_name=$(basename "$src_dir")
+    mkdir -p ".cursor/skills/$dir_name"
+    cp "$src_dir"* ".cursor/skills/$dir_name/" 2>/dev/null || true
+  done
 fi
 if [ "$MODE" = "mcp-only" ]; then
   rm -rf .cursor/skills/elemental-api
@@ -146,14 +156,14 @@ Build a manifest of all installed files (one relative path per line). **Do not**
 
 ```bash
 {
-  for f in .cursor/rules/*.mdc; do [ -f "$f" ] && echo "rules/$(basename "$f")"; done
   for f in .cursor/commands/*.md; do [ -f "$f" ] && echo "commands/$(basename "$f")"; done
   for d in .cursor/skills/*/; do [ -d "$d" ] && echo "skills/$(basename "$d")"; done
   [ -f "$TEMP_DIR/package/AGENTS.md" ] && [ -f ./AGENTS.md ] && echo "root/AGENTS.md"
+  [ -f "$TEMP_DIR/package/CLAUDE.md" ] && [ -f ./CLAUDE.md ] && echo "root/CLAUDE.md"
 } > .cursor/.aether-instructions-manifest
 ```
 
-If the repo uses **bash** for this loop and a glob might match nothing, run `shopt -s nullglob` first so the loops don’t treat `*.mdc` as a literal filename.
+If the repo uses **bash** for this loop and a glob might match nothing, run `shopt -s nullglob` first so the loops don't treat `*.md` as a literal filename.
 
 Write the version marker:
 
@@ -179,7 +189,6 @@ Count what was installed:
 
 ```bash
 wc -l < .cursor/.aether-instructions-manifest
-ls .cursor/rules/*.mdc 2>/dev/null | wc -l
 ls .cursor/commands/*.md 2>/dev/null | wc -l
 ls -d .cursor/skills/*/ 2>/dev/null | wc -l
 ```
@@ -188,7 +197,6 @@ Report to user:
 
 > Updated to @yottagraph-app/aether-instructions@X.Y.Z
 >
-> - Rules: N files
 > - Commands: N files
 > - Skills: N directories
 
@@ -199,13 +207,16 @@ Report to user:
 Commit the updated instruction files. A root `.gitignore` rule like `skills/` can **ignore** `.cursor/skills/`; if `git add .cursor/skills/` reports ignored paths, force-add:
 
 ```bash
-git add .cursor/rules/ .cursor/commands/ .cursor/.aether-instructions-version .cursor/.aether-instructions-manifest
+git add .cursor/commands/ .cursor/.aether-instructions-version .cursor/.aether-instructions-manifest
 git add -f .cursor/skills/
 [ -f AGENTS.md ] && git add AGENTS.md
+[ -f CLAUDE.md ] && git add CLAUDE.md
+# Remove the legacy rules dir from tracking if it was committed in an earlier install
+git rm -rf --cached --ignore-unmatch .cursor/rules 2>/dev/null || true
 git commit -m "Update instructions to vX.Y.Z"
 ```
 
-Use the repo’s commit convention if applicable (e.g. `[Agent commit] Update instructions to vX.Y.Z`).
+Use the repo's commit convention if applicable (e.g. `[Agent commit] Update instructions to vX.Y.Z`).
 
 > Changes committed. Your instructions are now up to date.
 
@@ -225,13 +236,15 @@ If you get permission errors:
 
 > Try running with appropriate permissions, or check that `.cursor/` is writable.
 
-### Want to customize a rule, command, or AGENTS.md?
+### Want to customize a command, skill topic, or AGENTS.md?
 
-If you need to modify a package-provided file (including the root `AGENTS.md`):
+If you need to modify a package-provided file (including the root `AGENTS.md` or `CLAUDE.md`):
 
 1. Edit it directly — your changes will persist until the next update
 2. To preserve changes across updates, copy it to a new name first (e.g. `cp AGENTS.md AGENTS.local.md`)
-3. Remove the original's entry from `.cursor/.aether-instructions-manifest` so it won't be deleted on update (for `AGENTS.md`, remove the `root/AGENTS.md` line)
+3. Remove the original's entry from `.cursor/.aether-instructions-manifest` so it won't be deleted on update (for `AGENTS.md`, remove the `root/AGENTS.md` line; for `CLAUDE.md`, remove `root/CLAUDE.md`)
+
+`CLAUDE.md` ships as a one-line `@AGENTS.md` pointer — Claude Code imports `AGENTS.md` via that syntax, so in most cases you only need to edit `AGENTS.md`.
 
 ### Blank line in manifest deleted `.cursor/`
 

package/package.json

@@ -1,13 +1,13 @@
 {
     "name": "@yottagraph-app/aether-instructions",
-    "version": "1.1.42",
-    "description": "Cursor rules, commands, and skills for Aether development",
+    "version": "1.1.44",
+    "description": "Cursor commands and skills for Aether development",
     "files": [
-        "rules",
         "commands",
         "skills",
         "variants",
-        "AGENTS.md"
+        "AGENTS.md",
+        "CLAUDE.md"
     ],
     "repository": {
         "type": "git",
@@ -17,7 +17,6 @@
     "keywords": [
         "cursor",
         "aether",
-        "rules",
         "commands",
         "skills"
     ],

package/skills/aether/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: aether
+description: Aether app conventions, architecture, data access, UI patterns, agents, MCP servers, deployment, env, storage. Read first for any work in an Aether repo.
+---
+
+# Aether Skill
+
+Aether is an app framework built on Nuxt 3 + Vue 3 + Vuetify 3 + TypeScript,
+running on the Lovelace platform (entities, news, filings, sentiment,
+relationships, events). It follows standard Nuxt conventions -- pages in
+`pages/`, components in `components/`, composables in `composables/`, server
+routes in `server/api/`. Auth0 is wired in automatically. Apps can also
+contain ADK **agents** (`agents/`, deployed to Vertex AI Agent Engine) and
+**MCP servers** (`mcp-servers/`, deployed to Cloud Run) that deploy
+independently from the web app.
+
+This skill is the single entry point for conventions, architecture, and
+copy-paste patterns. Read this file first, then follow the links below for
+the specific topic you need.
+
+## How to Use This Skill
+
+**Always read this `SKILL.md` file whenever you are working on any code in
+an Aether tenant project.** It is the index of what guidance is available to you.
+
+Do _not_ read every topic file up front. Instead, once you've read this
+index, use the "When to read" column in the table below to decide which
+specific topic files are relevant to the task in front of you, and read
+only those. Re-consult this index whenever the task shifts (e.g. from
+pages to agents, or from data access to deployment) to pick up any new
+topics that apply.
+
+## Files
+
+| File                                               | When to read                                                                                                                                                                                                                     |
+| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [architecture.md](architecture.md)                 | Project structure, navigation, server routes, agents, MCP. Read when adding pages, navigation, or server-side functionality.                                                                                                     |
+| [data.md](data.md)                                 | How this app reads platform data (clients, schema discovery, entity/news/filings access, common gotchas). Read when building any feature that fetches or displays platform data.                                                 |
+| [cookbook.md](cookbook.md)                         | Copy-paste UI patterns for common pages: data table, form, chart, dialog, master-detail. For data-fetching recipes see `cookbook-data.md`.                                                                                       |
+| [cookbook-data.md](cookbook-data.md)               | Data-fetching UI recipes: entity search, news feed, filings, and related helpers. Read with `data.md` when building pages that display platform data.                                                                            |
+| [design.md](design.md)                             | `DESIGN.md` workflow, feature docs, starter-app-is-placeholder guidance. Read when starting work, planning features, or updating project design.                                                                                 |
+| [ui.md](ui.md)                                     | Vue/Vuetify page templates, layouts, scrollable content, data tables, loading states. Applies when creating or editing page templates (`pages/**`, `components/**`).                                                             |
+| [pref.md](pref.md)                                 | User preferences and KV storage: `usePrefsStore`, `Pref<T>`, app namespacing (`NUXT_PUBLIC_APP_ID`). Read when working on settings persistence.                                                                                  |
+| [branding.md](branding.md)                         | Visual styling, colors, typography, theming, branding, UI appearance. Read when updating brand assets or theme code.                                                                                                             |
+| [server.md](server.md)                             | Nitro server-side API routes (`server/**`): file-based routing, event handlers, image proxy. Read when adding server routes. For storage backends see `storage.md`; for platform-data proxying see `server-data.md`.             |
+| [server-data.md](server-data.md)                   | Reading platform data from Nitro server routes (`server/**`). Read when a server route needs to fetch platform data on behalf of the app.                                                                                        |
+| [storage.md](storage.md)                           | Storage backends: KV (always on) vs Neon Postgres (if provisioned). Read when choosing persistence, wiring `getRedis()`/`getDb()`, creating tables, or handling missing credentials gracefully.                                  |
+| [agents.md](agents.md)                             | Conventions for developing ADK agents in `agents/**`. Read when writing or editing agent code.                                                                                                                                   |
+| [agents-data.md](agents-data.md)                   | How ADK agents access platform data (authentication, local testing env vars, mode-specific wiring). Read when an agent needs platform data (`agents/**`).                                                                        |
+| [mcp-servers.md](mcp-servers.md)                   | Conventions for developing MCP servers in `mcp-servers/**`. Read when writing or editing FastMCP servers.                                                                                                                        |
+| [deployment.md](deployment.md)                     | App, agent, and MCP server deployment targets (Vercel, Vertex AI Agent Engine, Cloud Run). Read when pushing to main, running `/deploy_agent` or `/deploy_mcp`, or explaining how code reaches production.                       |
+| [env.md](env.md)                                   | `.env` variable reference (`APP_ID`, `USER_NAME`, `QUERY_SERVER_ADDRESS`, etc.). Read when adding env vars, configuring Auth0 bypass, or inspecting runtime config.                                                              |
+| [local-setup.md](local-setup.md)                   | Manual local dev setup (`npm run init -- --local`, `npm run dev`). Read when running the app locally outside Cursor Cloud.                                                                                                       |
+| [cursor-cloud.md](cursor-cloud.md)                 | Cursor Cloud environment quirks (Node managed by env, dev server auto-started, skip browser testing during initial setup). Read when `$HOME` is under `/root` or `/home/ubuntu`, or when a dev-server terminal was auto-started. |
+| [git-support.md](git-support.md)                   | Git commit workflow and conventions. Read when finishing implementation work, making commits, or troubleshooting git/pre-commit failures.                                                                                        |
+| [something-broke.md](something-broke.md)           | Error recovery and build failure troubleshooting. Read when something broke, build failed, `npm run build` errors, or the user wants to restore previous behavior.                                                               |
+| [instructions_warning.md](instructions_warning.md) | Warning about editing `.cursor/` files managed by `@yottagraph-app/aether-instructions`. Read before modifying installed instruction files.                                                                                      |

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

@@ -1,9 +1,3 @@
----
-description: "ADK agents calling the Elemental API via broadchurch_auth and local testing env vars."
-alwaysApply: false
-globs: agents/**
----
-
 # Agents: Elemental API (Query Server)
 
 ## Connecting to the Elemental API
@@ -46,12 +40,14 @@ dev (`agents/` on sys.path → absolute import) and Agent Engine runtime
 `broadchurch.yaml` directly — `broadchurch_auth` handles all of this.
 
 Key endpoints:
+
 - `GET /elemental/metadata/schema` — entity types and properties
 - `POST /elemental/find` — search for entities by expression
 - `POST /entities/search` — search for entities by name (batch, scored)
 - `POST /elemental/entities/properties` — get entity property values
 
 Requirements for agents using the Elemental API (add to `requirements.txt`):
+
 ```
 google-auth>=2.20.0
 pyyaml>=6.0
@@ -160,6 +156,7 @@ def _get_mcp_url(server_name: str = "elemental") -> str:
 ```
 
 For **local dev**, set the env var:
+
 ```bash
 export ELEMENTAL_MCP_URL="https://mcp.news.prod.g.lovelace.ai/elemental/mcp"
 ```

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

@@ -1,9 +1,3 @@
----
-description: Rules for developing ADK agents in the agents/ directory
-globs: agents/**
-alwaysApply: false
----
-
 # Agent Development (Google ADK)
 
 This project supports developing and deploying AI agents alongside the UI. Agents live in the `agents/` directory and deploy to Vertex AI Agent Engine via the `/deploy_agent` command.
@@ -49,14 +43,15 @@ root_agent = Agent(
 ```
 
 Key rules:
+
 - The `agent.py` file MUST export a variable named `root_agent`
 - Tool functions should have detailed docstrings -- the LLM reads these to understand when and how to use each tool
 - Use `google-adk` for the agent framework, `httpx` for HTTP calls
 - Pin dependency versions in `requirements.txt` for reproducible deployments
 
 For agents that call the **Elemental API** (`broadchurch_auth`, endpoints,
-local `ELEMENTAL_*` env vars), see the `agents-data` rule. For agents
-using **Elemental MCP tools**, the `agents-data` rule also covers
+local `ELEMENTAL_*` env vars), see [agents-data.md](agents-data.md) in this skill. For agents
+using **Elemental MCP tools**, [agents-data.md](agents-data.md) also covers
 `McpToolset` wiring — use `StreamableHTTPConnectionParams` (not
 `SseConnectionParams`) and read the `elemental-mcp-patterns` skill for
 response handling patterns.
@@ -160,17 +155,18 @@ The response includes an `agents` array:
 
 Each agent entry has:
 
-| Field | Type | Description |
-|---|---|---|
-| `name` | `string` | Agent directory name (e.g. `filing_analyst`) |
-| `display_name` | `string` | Human-readable name for the UI |
-| `engine_id` | `string` | Vertex AI Agent Engine resource ID — used as `{agentId}` in query/stream URLs |
+| Field          | Type     | Description                                                                   |
+| -------------- | -------- | ----------------------------------------------------------------------------- |
+| `name`         | `string` | Agent directory name (e.g. `filing_analyst`)                                  |
+| `display_name` | `string` | Human-readable name for the UI                                                |
+| `engine_id`    | `string` | Vertex AI Agent Engine resource ID — used as `{agentId}` in query/stream URLs |
 
 The `engine_id` is the key value — it becomes the `{agentId}` path
 parameter in `/api/agent/{agentId}/stream` (the local Nitro route) and
 the portal's `/authorize` endpoint.
 
 **How agents get populated:** The portal discovers agents from two sources:
+
 1. **Firestore** — agents registered by the deploy workflow (`deploy-agent.yml`
    calls `POST /api/agents/{tenantId}` to register)
 2. **Agent Engine API** — the portal also queries Vertex AI for reasoning
@@ -226,9 +222,26 @@ A typical stream for an agent that uses a tool:
 
 ```json
 [
-  { "content": { "parts": [{ "functionCall": { "name": "search", "args": {"q": "AAPL 8-K"} } }], "role": "model" } },
-  { "content": { "parts": [{ "functionResponse": { "name": "search", "response": {"results": ["..."]} } }], "role": "tool" } },
-  { "content": { "parts": [{ "text": "Here is the summary of the 8-K filing..." }], "role": "model" } }
+    {
+        "content": {
+            "parts": [{ "functionCall": { "name": "search", "args": { "q": "AAPL 8-K" } } }],
+            "role": "model"
+        }
+    },
+    {
+        "content": {
+            "parts": [
+                { "functionResponse": { "name": "search", "response": { "results": ["..."] } } }
+            ],
+            "role": "tool"
+        }
+    },
+    {
+        "content": {
+            "parts": [{ "text": "Here is the summary of the 8-K filing..." }],
+            "role": "model"
+        }
+    }
 ]
 ```
 
@@ -259,13 +272,13 @@ automatically.
 
 SSE event types:
 
-| Event | Data Shape | Description |
-|---|---|---|
-| `text` | `{ "text": "..." }` | Agent text output (replaces previous text) |
-| `function_call` | `{ "name": "...", "args": {...} }` | Agent is calling a tool |
-| `function_response` | `{ "name": "...", "response": {...} }` | Tool returned a result |
-| `error` | `{ "message": "...", "code": "..." }` | Error during processing (`code` is `PERMISSION_DENIED` for IAM failures) |
-| `done` | `{ "session_id": "...", "text": "..." }` | Stream complete with final text |
+| Event               | Data Shape                               | Description                                                              |
+| ------------------- | ---------------------------------------- | ------------------------------------------------------------------------ |
+| `text`              | `{ "text": "..." }`                      | Agent text output (replaces previous text)                               |
+| `function_call`     | `{ "name": "...", "args": {...} }`       | Agent is calling a tool                                                  |
+| `function_response` | `{ "name": "...", "response": {...} }`   | Tool returned a result                                                   |
+| `error`             | `{ "message": "...", "code": "..." }`    | Error during processing (`code` is `PERMISSION_DENIED` for IAM failures) |
+| `done`              | `{ "session_id": "...", "text": "..." }` | Stream complete with final text                                          |
 
 For custom agent UIs that need streaming, import `readSSE`:
 
@@ -299,14 +312,14 @@ to the original plain object are invisible to the template.
 // WRONG — local ref bypasses Vue's reactivity, UI won't update:
 const msg: ChatMessage = { id: '...', role: 'agent', text: '', streaming: true };
 messages.value.push(msg);
-msg.text = 'hello';        // data changes, but Vue doesn't know
-msg.streaming = false;     // template still shows typing indicator
+msg.text = 'hello'; // data changes, but Vue doesn't know
+msg.streaming = false; // template still shows typing indicator
 
 // CORRECT — access through the reactive array:
 messages.value.push({ id: '...', role: 'agent', text: '', streaming: true });
 const idx = messages.value.length - 1;
-messages.value[idx].text = 'hello';        // Vue detects this
-messages.value[idx].streaming = false;     // template re-renders
+messages.value[idx].text = 'hello'; // Vue detects this
+messages.value[idx].streaming = false; // template re-renders
 ```
 
 The `useAgentChat` composable uses the correct pattern internally (via an
@@ -349,7 +362,7 @@ agents (MCP or REST-backed):
 
 This applies to ADK agent tools, where the LLM reads tool output directly.
 MCP server tools follow different conventions (structured dicts/lists) — see
-the `mcp-servers` rule.
+[mcp-servers.md](mcp-servers.md).
 
 The agent's LLM will try to interpret whatever the tool returns. Raw API
 responses with nested dicts, numeric IDs, and arrays of unlabeled values
@@ -472,6 +485,7 @@ Passing a raw `McpToolset` as the agent's only tool source and writing a
 long system prompt does **not** satisfy the spec.
 
 `McpToolset` passthrough means:
+
 - The LLM receives raw JSON responses — no Markdown formatting, no
   human-readable reports
 - No session-state caching — repeated queries for the same entity make