@yottagraph-app/aether-instructions 1.1.41 → 1.1.43

package/AGENTS.md

@@ -1,124 +1,44 @@
-# AGENTS.md
+# Aether
 
-Broadchurch tenant application built on Aether (Nuxt 3 + Vuetify).
+**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.
 
-## Cursor Cloud specific instructions
+**Stack:** Nuxt 3 (SPA), Vue 3 Composition API (`<script setup>`), Vuetify 3, TypeScript (required), Auth0.
 
-If you are in Cursor Cloud, the `environment.json` install step runs
-`init-project.js` and `npm install` automatically, and starts a dev server
-on port 3000.
+**Structure:** `pages/` (file-based routing), `components/`, `composables/`, `server/api/`, `agents/` (Python ADK), `mcp-servers/` (Python FastMCP).
 
-**Verify before starting:** check that `.env` exists and `node_modules/` is
-present. If either is missing, run: `node init-project.js && npm install`
+**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.
 
-**Do NOT** manually run `nvm install` or `nvm use` — Node version is managed
-by the environment.
+**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).
 
-### Initial environment setup only
+**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.
 
-This subsection applies ONLY when first asked to "set up the development
-environment" or "demonstrate that the environment is working." It does
-**NOT** apply to ongoing development — once the app is built, use the
-browser normally to test and verify UI changes.
+**Git:** Commit meaningful units of work. Run `npm run format` before commit. Message format: `[Agent commit] {summary}`. Push directly to main — do NOT create PRs or feature branches.
 
-**During initial setup**, skip browser/UI testing. The starter UI is a
-placeholder template that will be replaced by `/build_my_app`. Do not
-launch a browser, record videos, or take screenshots at this stage.
-Verifying `npm run build` passes is sufficient.
+**First action for a new project:** Run `/build_my_app`.
 
-1. Check the "Dev Server" terminal output for a line containing
-   `Listening on` or `Local: http://localhost:3000`. If present, the
-   environment is working.
-2. If the dev server is NOT running, start it with `npm run dev` and wait
-   for the "Listening on" line.
-3. Run `npm run build` to verify the project compiles.
-4. Once confirmed, tell the user the environment is ready, then
-   immediately run the `/build_my_app` command.
+## Task-specific topics
 
-### MCP tools
+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.
 
-Lovelace MCP servers (`lovelace-elemental`, `lovelace-stocks`, etc.)
-should be available if configured at the org level. Check your tool list
-for `elemental_*` tools. If they're not available, use the Elemental API
-client (`useElementalClient()`) and the skill docs in
-`.cursor/skills/elemental-api/` and `.cursor/skills/data-model/` for platform data access instead.
+## Environment
 
-### Technical details
+Detect your runtime once at startup, then read the matching topic in the `aether` skill:
 
-Node 20 is the baseline (`.nvmrc`). The `environment.json` install step
-handles this via `nvm install 20 && nvm alias default 20`. Newer Node
-versions (22, 25) generally work but may produce `EBADENGINE` warnings
-during install — safe to ignore.
+- **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).
 
-The install step runs `node init-project.js --local` (creates `.env` if
-absent) then `npm install` (triggers `postinstall` → `nuxt prepare`).
-Auth0 is bypassed via `NUXT_PUBLIC_USER_NAME=dev-user`
-in the generated `.env`.
-
-**No automated test suite.** Verification is `npm run build` (compile
-check) and `npm run format:check` (Prettier). See Verification Commands.
-
-**Before committing:** always run `npm run format` — the husky pre-commit
-hook runs `lint-staged` with `prettier --check` and will reject
-unformatted files.
-
-## 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)
-```
-
-## .env Essentials
-
-| 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.
-
-## Project Structure
-
-| Directory      | Contents                                             | Deployed to            |
-| -------------- | ---------------------------------------------------- | ---------------------- |
-| `pages/`       | Nuxt pages (file-based routing)                      | Vercel (with app)      |
-| `components/`  | Vue components                                       | Vercel (with app)      |
-| `composables/` | Vue composables (auto-imported by Nuxt)              | Vercel (with app)      |
-| `utils/`       | Utility functions (NOT auto-imported)                | Vercel (with app)      |
-| `server/`      | Nitro API routes (KV storage, avatar proxy)          | Vercel (with app)      |
-| `agents/`      | Python ADK agents (each subdirectory is deployable)  | Vertex AI Agent Engine |
-| `mcp-servers/` | Python MCP servers (each subdirectory is deployable) | Cloud Run              |
+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).
 If these directories are missing, run `/update_instructions` to reinstall.
 
-### Agents
-
-`agents/example_agent/` is a working starter agent that queries the Elemental
-Knowledge Graph. It includes schema discovery, entity search, property lookup,
-and optional MCP server integration. Use it as a starting point — customize the
-instruction, add tools, and see the `agents` cursor rule for the full guide.
-
 ## Configuration
 
 `broadchurch.yaml` contains tenant-specific settings (GCP project, org ID,
@@ -126,93 +46,6 @@ service account, gateway URL, query server URL). It's generated during
 provisioning and committed by the `tenant-init` workflow. Don't edit manually
 unless you know what you're doing.
 
-## Storage
-
-Two storage services are available. Check `.env` to see which are connected:
-
-| 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 |
-
-### Quick start
-
-**KV** is ready to use out of the box. Use `getRedis()` from
-`server/utils/redis.ts` in server routes, or `usePrefsStore()` on the client
-(see `pref` rule for the `Pref<T>` pattern).
-
-**Neon Postgres** — provisioning is determined by the portal, not by `.env`.
-To check whether Neon is enabled for this tenant, pull `gateway.url` and
-`tenant.org_id` out of `broadchurch.yaml` and query the portal:
-
-```bash
-curl <gateway.url>/api/tenants/<tenant.org_id>
-```
-
-If the response has `vercel.postgres_store_id` set, Neon is provisioned. The
-`DATABASE_URL` is also present under `agent_secrets` in that response, but
-you usually do not need to read it directly.
-
-`DATABASE_URL` and `DATABASE_URL_UNPOOLED` are intentionally left commented
-out in local `.env` — Neon does not work locally. On deploy, Vercel
-auto-injects `DATABASE_URL` at runtime, so pushed builds connect
-transparently.
-
-Before writing Postgres code, bootstrap the two things the project does NOT
-scaffold automatically:
-
-- If `server/utils/neon.ts` is not present, create it (same `getDb()`
-  lazy-init pattern as `server/utils/redis.ts`).
-- If `@neondatabase/serverless` is not in `package.json`, install it with
-  `npm install @neondatabase/serverless`.
-
-Then use `getDb()` in server routes:
-
-```typescript
-import { getDb } from '~/server/utils/neon';
-
-export default defineEventHandler(async () => {
-    const sql = getDb();
-    if (!sql) throw createError({ statusCode: 503, statusMessage: 'Database not configured' });
-    return await sql`SELECT * FROM my_table`;
-});
-```
-
-### Where credentials come from
-
-**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.
-
-**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`.
-
-This is a known platform limitation — the Broadchurch team is working on
-making storage credentials available for local development.
-
-See the `server` rule for detailed usage patterns for both KV and Postgres.
-
-## How Deployment Works
-
-### 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.
-
 ## Verification Commands
 
 ```bash
@@ -223,12 +56,6 @@ npm run format       # Prettier formatting (run before committing)
 
 ## Known Issues
 
-### Blank white page after `npm run dev`
-
-If the server returns HTTP 200 but the page is blank, check the browser console
-for `SyntaxError` about missing exports. This is caused by Nuxt's auto-import
-scanner. **Fix:** verify the `imports:dirs` hook in `nuxt.config.ts` is present.
-
 ### Port 3000 conflict
 
 The dev server binds to port 3000 by default. If another service is already

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.
 
@@ -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,13 +105,12 @@ 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
 ```
@@ -122,14 +128,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 +155,13 @@ 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"
 } > .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 +187,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 +195,6 @@ Report to user:
 
 > Updated to @yottagraph-app/aether-instructions@X.Y.Z
 >
-> - Rules: N files
 > - Commands: N files
 > - Skills: N directories
 
@@ -199,13 +205,15 @@ 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
+# 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,7 +233,7 @@ 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`):
 

package/package.json

@@ -1,9 +1,8 @@
 {
     "name": "@yottagraph-app/aether-instructions",
-    "version": "1.1.41",
-    "description": "Cursor rules, commands, and skills for Aether development",
+    "version": "1.1.43",
+    "description": "Cursor commands and skills for Aether development",
     "files": [
-        "rules",
         "commands",
         "skills",
         "variants",
@@ -17,7 +16,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"
 ```