@yottagraph-app/aether-instructions 1.1.41 → 1.1.42

package/AGENTS.md

@@ -1,107 +1,52 @@
-# AGENTS.md
+# Aether
 
-Broadchurch tenant application built on Aether (Nuxt 3 + Vuetify).
+**Stack:** Nuxt 3 (SPA), Vue 3 Composition API (`<script setup>`), Vuetify 3, TypeScript (required), Auth0.
 
-## Cursor Cloud specific instructions
+**Structure:** `pages/` (file-based routing), `components/`, `composables/`, `server/api/`, `agents/` (Python ADK), `mcp-servers/` (Python FastMCP).
 
-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.
+**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.
 
-**Verify before starting:** check that `.env` exists and `node_modules/` is
-present. If either is missing, run: `node init-project.js && npm install`
+**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).
 
-**Do NOT** manually run `nvm install` or `nvm use` — Node version is managed
-by the environment.
+**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.
 
-### Initial environment setup only
+**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.
 
-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.
+**First action for a new project:** Run `/build_my_app`.
 
-**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.
+## Task-specific rules
 
-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.
+Conditional rules, loaded based on what you're doing:
 
-### MCP tools
+- `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
 
-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 rule:
 
-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 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.
 
-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/`)
 
@@ -112,13 +57,6 @@ 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 +64,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 +74,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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@yottagraph-app/aether-instructions",
-    "version": "1.1.41",
+    "version": "1.1.42",
     "description": "Cursor rules, commands, and skills for Aether development",
     "files": [
         "rules",

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/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).