@yottagraph-app/aether-instructions 1.1.40 → 1.1.41

package/AGENTS.md

@@ -0,0 +1,240 @@
+# AGENTS.md
+
+Broadchurch tenant application built on Aether (Nuxt 3 + Vuetify).
+
+## Cursor Cloud specific instructions
+
+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.
+
+## 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              |
+
+### 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.
+
+### 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,
+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
+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
+
+### 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
+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.41",
     "description": "Cursor rules, commands, and skills for Aether development",
     "files": [
         "rules",
         "commands",
         "skills",
-        "variants"
+        "variants",
+        "AGENTS.md"
     ],
     "repository": {
         "type": "git",

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