@yottagraph-app/aether-instructions 1.1.40 → 1.1.42

package/AGENTS.md

@@ -0,0 +1,85 @@
+# Aether
+
+**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.
+
+**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).
+
+**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.
+
+**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.
+
+**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
+
+## Environment
+
+Detect your runtime once at startup, then read the matching 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 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.
+
+This check is cheap and only needs to run once per session.
+
+### Cursor instructions (`.cursor/`)
+
+Cursor rules, commands, and skills are installed from the
+`@yottagraph-app/aether-instructions` npm package during project init.
+`.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.
+
+## Configuration
+
+`broadchurch.yaml` contains tenant-specific settings (GCP project, org ID,
+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.
+
+## Verification Commands
+
+```bash
+npm run dev          # dev server -- check browser at localhost:3000
+npm run build        # production build -- catches compile errors
+npm run format       # Prettier formatting (run before committing)
+```
+
+## Known Issues
+
+### Port 3000 conflict
+
+The dev server binds to port 3000 by default. If another service is already
+using that port, start with `PORT=3001 npm run dev`.
+
+### Formatting
+
+Pre-commit hook runs `lint-staged` with Prettier. Run `npm run format` before
+committing to avoid failures.

package/commands/update_instructions.md

@@ -71,13 +71,22 @@ 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.
+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.
 
 ```bash
 if [ -f .cursor/.aether-instructions-manifest ]; then
   while IFS= read -r rel || [ -n "$rel" ]; do
     [ -z "$rel" ] && continue
-    rm -rf ".cursor/$rel"
+    case "$rel" in
+      root/*)
+        target="${rel#root/}"
+        case "$target" in ""|*..*) continue ;; esac
+        [ -f "$target" ] && rm -f "$target"
+        ;;
+      *)
+        rm -rf ".cursor/$rel"
+        ;;
+    esac
   done < .cursor/.aether-instructions-manifest
 fi
 ```
@@ -100,6 +109,12 @@ 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:
+
+```bash
+[ -f "$TEMP_DIR/package/AGENTS.md" ] && cp "$TEMP_DIR/package/AGENTS.md" ./AGENTS.md
+```
+
 ### Data-mode variant overlay
 
 If this project uses **mcp-only** (or another non-default mode), re-apply the same overlay `init-project.js` uses. Read the saved mode:
@@ -134,6 +149,7 @@ Build a manifest of all installed files (one relative path per line). **Do not**
   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
 ```
 
@@ -185,6 +201,7 @@ Commit the updated instruction files. A root `.gitignore` rule like `skills/` ca
 ```bash
 git add .cursor/rules/ .cursor/commands/ .cursor/.aether-instructions-version .cursor/.aether-instructions-manifest
 git add -f .cursor/skills/
+[ -f AGENTS.md ] && git add AGENTS.md
 git commit -m "Update instructions to vX.Y.Z"
 ```
 
@@ -208,13 +225,13 @@ If you get permission errors:
 
 > Try running with appropriate permissions, or check that `.cursor/` is writable.
 
-### Want to customize a rule or command?
+### Want to customize a rule, command, or AGENTS.md?
 
-If you need to modify a package-provided file:
+If you need to modify a package-provided file (including the root `AGENTS.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
-3. Remove the original's entry from `.cursor/.aether-instructions-manifest` so it won't be deleted on 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)
 
 ### Blank line in manifest deleted `.cursor/`
 

package/package.json

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

package/rules/agents.mdc

@@ -8,6 +8,13 @@ alwaysApply: false
 
 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.
 
+## Starter agent
+
+`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 follow the patterns described below.
+
 ## Directory Structure
 
 Each agent is a self-contained Python package. **Directory names must use underscores, not hyphens** (ADK uses the directory name as a Python identifier).

package/rules/architecture.mdc

@@ -30,10 +30,9 @@ mcp-servers/        # MCP servers (Python, deploy to Cloud Run)
 |---|---|---|
 | Platform data (Query Server / Postgres per your architecture) | Lovelace knowledge graph or synced local data | See the `data` rule |
 | KV (Upstash Redis) | User preferences, lightweight state | Settings, watchlists, UI state that should persist |
-| Neon Postgres | App-specific relational data | Custom tables, complex queries (if connected — check `DATABASE_URL` in `.env`) |
+| Neon Postgres | App-specific relational data | Custom tables, complex queries (if provisioned — see the `storage` rule for how to check) |
 
-Use `Pref<T>` or `usePrefsStore()` for KV (see `pref` rule).
-Check `.env` for `DATABASE_URL` before using Neon Postgres (see `server` rule).
+See the `storage` rule to check which stores are available, then `pref` (client-side KV) and `server` (Neon usage) for detailed patterns.
 
 ## Adding Pages
 

package/rules/cursor-cloud.mdc

@@ -0,0 +1,62 @@
+---
+description: Cursor Cloud environment quirks (Node managed by env, dev server auto-started, skip browser testing during initial setup). Apply when the environment check in AGENTS.md indicates Cursor Cloud ($HOME under /root or /home/ubuntu, or a dev-server terminal was auto-started), or when the user mentions Cursor Cloud.
+alwaysApply: false
+---
+
+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.
+
+**Verify before starting:** check that `.env` exists and `node_modules/` is
+present. If either is missing, run: `node init-project.js && npm install`
+
+**Do NOT** manually run `nvm install` or `nvm use` — Node version is managed
+by the environment.
+
+### Initial environment setup only
+
+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.
+
+**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.
+
+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.
+
+### MCP tools
+
+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.
+
+### Technical details
+
+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.
+
+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.

package/rules/deployment.mdc

@@ -0,0 +1,19 @@
+---
+description: App, agent, and MCP server deployment targets (Vercel, Vertex AI Agent Engine, Cloud Run). Apply when pushing to main, running /deploy_agent or /deploy_mcp, or explaining how code reaches production.
+alwaysApply: false
+---
+
+### 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/env.mdc

@@ -0,0 +1,15 @@
+---
+description: .env variable reference (APP_ID, USER_NAME, QUERY_SERVER_ADDRESS, etc.). Apply when adding env vars, configuring Auth0 bypass, or inspecting runtime config.
+alwaysApply: false
+---
+
+| 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/instructions_warning.mdc

@@ -10,32 +10,43 @@ 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).
+
 ## Do Not
 
 - Modify files listed in the manifest directly (changes will be lost on update)
 
 ## To Customize
 
-If you need to modify a package-provided rule or command:
+If you need to modify a package-provided rule, command, or the root `AGENTS.md`:
 
 1. **Copy** the file to a new name
 2. Make your changes to the copy
 3. Remove the original's entry from `.cursor/.aether-instructions-manifest`
    so it won't be replaced on update
 
-Example:
+Examples:
 
 ```bash
-# Copy the rule you want to customize
+# Customize a rule
 cp .cursor/rules/data.mdc .cursor/rules/data_custom.mdc
 
+# Customize AGENTS.md
+cp AGENTS.md AGENTS.local.md
+# then remove the `root/AGENTS.md` line from
+# .cursor/.aether-instructions-manifest
+
 # Edit your copy — it won't be affected by instruction updates
 ```
 
 ## How It Works
 
 - `.cursor/.aether-instructions-manifest` lists every file installed by the
-  package (one relative path per line, e.g. `rules/data.mdc`)
+  package (one relative path per line, e.g. `rules/data.mdc`). 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
   the latest package, and writes a new manifest
 - Files not in the manifest are never touched

package/rules/local-setup.mdc

@@ -0,0 +1,20 @@
+---
+description: Manual local dev setup (npm run init --local, npm run dev). Apply when the environment check in AGENTS.md indicates local (non-Cursor-Cloud) and .env or node_modules are missing, or when the user asks how to run the app locally.
+alwaysApply: false
+---
+
+## Manual / Local Setup
+
+Node 20 is the baseline (pinned in `.nvmrc`). Newer versions generally work.
+
+```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/storage.mdc

@@ -0,0 +1,54 @@
+---
+description: Storage backends available to the app (KV/Upstash Redis always on; Neon Postgres if provisioned). Apply when choosing persistence, deciding if Postgres is available, or wiring up getRedis()/getDb().
+alwaysApply: false
+---
+
+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.
+
+For the `getDb()` lazy-init pattern, `@neondatabase/serverless` install, and
+full code examples (creating tables, handling missing tables in GET routes,
+etc.), see the `server` rule.
+
+### 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.

package/rules/aether.mdc

@@ -1,21 +0,0 @@
----
-alwaysApply: true
----
-
-# Aether
-
-**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.
-
-**Storage:** KV (Upstash Redis) for preferences and lightweight state via `Pref<T>` from `usePrefsStore()`. Neon Postgres for relational data if connected (check `.env` for `DATABASE_URL`).
-
-**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.
-
-**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.
-
-**First action for a new project:** Run `/build_my_app`.
-
-**Task-specific rules:** `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), `server-data` (server-side Elemental API from routes), `agents` (ADK agents), `agents-data` (agents calling Elemental API), `something-broke` (error recovery, build failures).