@yottagraph-app/aether-instructions 1.1.10 → 1.1.11

package/commands/build_my_app.md

@@ -82,7 +82,7 @@ Key capabilities:
 
 - **Query Server / Elemental API** -- the primary data source. Use `useElementalClient()` from `@yottagraph-app/elemental-api/client`. See the `api` rule.
 - **KV storage** -- always available for preferences and lightweight data (see `pref` rule)
-- **Supabase** -- check if `NUXT_PUBLIC_SUPABASE_URL` is in `.env` for database access
+- **Neon Postgres** -- check if `DATABASE_URL` is in `.env` for database access (see `server` rule)
 - **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
@@ -104,7 +104,7 @@ Plan what you'll build:
 1. What pages to create in `pages/`
 2. What reusable components to extract into `components/`
 3. What shared logic belongs in `composables/`
-4. What data needs to be persisted (and whether KV or Supabase is appropriate)
+4. What data needs to be persisted (and whether KV or Neon Postgres is appropriate)
 5. Whether the app needs AI agents or MCP servers
 6. Whether the app needs an agent chat page (use the `useAgentChat` composable)
 7. Whether `app.vue` needs a sidebar, tabs, or other navigation (and what it should look like)

package/package.json

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

package/rules/aether.mdc

@@ -10,7 +10,7 @@ alwaysApply: true
 
 **Data:** The Query Server (Elemental API) is the primary data source -- entities, news, filings, sentiment, relationships, events. Use `useElementalClient()` from `@yottagraph-app/elemental-api/client`. Do NOT call external APIs for data the platform provides. Discovery-first: use `getSchema()` to discover entity types and properties at runtime. Skill docs: `skills/elemental-api/` (API endpoints) and `skills/data-model/` (Lovelace entity types, properties, relationships, YAML schemas per fetch source; `SKILL.md` first). Run `npm install` if those directories are empty. Lovelace MCP servers may also be configured (see `api` rule) but are optional — check your tool list before assuming they're available.
 
-**Storage:** KV (Upstash Redis) for preferences and lightweight state via `Pref<T>` from `usePrefsStore()`. Supabase for relational data if connected (check `.env`).
+**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.
 
@@ -18,4 +18,4 @@ alwaysApply: true
 
 **First action for a new project:** Run `/build_my_app`.
 
-**Task-specific rules:** `architecture` (project structure, navigation, server routes, agents, MCP), `api` (Elemental API client, schema discovery, gotchas, optional MCP servers), `design` (DESIGN.md workflow, feature docs), `ui` (page templates, layout patterns), `cookbook` (copy-paste UI patterns), `pref` (KV preferences), `branding` (colors, fonts), `server` (Nitro routes, Supabase), `something-broke` (error recovery, build failures).
+**Task-specific rules:** `architecture` (project structure, navigation, server routes, agents, MCP), `api` (Elemental API client, schema discovery, gotchas, optional MCP servers), `design` (DESIGN.md workflow, feature docs), `ui` (page templates, layout patterns), `cookbook` (copy-paste UI patterns), `pref` (KV preferences), `branding` (colors, fonts), `server` (Nitro routes, Neon Postgres), `something-broke` (error recovery, build failures).

package/rules/architecture.mdc

@@ -30,11 +30,11 @@ mcp-servers/        # MCP servers (Python, deploy to Cloud Run)
 |---|---|---|
 | Query Server (Elemental API) | Lovelace Knowledge Graph | Entities, news, relationships, events, sentiment, filings |
 | KV (Upstash Redis) | User preferences, lightweight state | Settings, watchlists, UI state that should persist |
-| Supabase (PostgreSQL) | App-specific relational data | Custom tables, complex queries (if connected) |
+| Neon Postgres | App-specific relational data | Custom tables, complex queries (if connected — check `DATABASE_URL` in `.env`) |
 
 Use `useElementalClient()` for Query Server data (see `api` rule).
 Use `Pref<T>` or `usePrefsStore()` for KV (see `pref` rule).
-Check `.env` for `NUXT_PUBLIC_SUPABASE_URL` before using Supabase.
+Check `.env` for `DATABASE_URL` before using Neon Postgres (see `server` rule).
 
 ## Adding Pages
 

package/rules/server.mdc

@@ -67,33 +67,55 @@ if (redis) {
 
 Returns `null` if KV is not configured (env vars missing). Always check.
 
-## Supabase (PostgreSQL)
+## Neon Postgres
 
-If Supabase is connected to the project, Vercel auto-injects these env vars:
+If a Neon database is connected to the project, Vercel auto-injects
+`DATABASE_URL` (pooled) and `DATABASE_URL_UNPOOLED` (direct). For local
+development, copy the connection string from Vercel project settings into
+`.env`.
 
-- `NUXT_PUBLIC_SUPABASE_URL` — Supabase project URL
-- `NUXT_PUBLIC_SUPABASE_ANON_KEY` — Public anon key (safe for client-side)
-- `SUPABASE_SERVICE_ROLE_KEY` — Server-only service role key (never expose to client)
-- `SUPABASE_DB_URL` — Direct Postgres connection string
+### Utility pattern
 
-Use `@supabase/supabase-js` for the Supabase client:
+Create `server/utils/neon.ts` following the same lazy-init pattern as
+`redis.ts` — export a getter that returns `null` when the env var is missing:
 
 ```typescript
-import { createClient } from '@supabase/supabase-js';
+import { neon, type NeonQueryFunction } from '@neondatabase/serverless';
 
-const supabase = createClient(
-  process.env.NUXT_PUBLIC_SUPABASE_URL!,
-  process.env.SUPABASE_SERVICE_ROLE_KEY!,  // server routes only
-);
+let _sql: NeonQueryFunction | null = null;
 
-const { data } = await supabase.from('my_table').select('*');
+export function getDb(): NeonQueryFunction | null {
+  if (_sql) return _sql;
+  const url = process.env.DATABASE_URL;
+  if (!url) return null;
+  _sql = neon(url);
+  return _sql;
+}
+```
+
+Install the driver: `npm install @neondatabase/serverless`
+
+### Usage 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' });
+
+  const rows = await sql`SELECT * FROM notes ORDER BY created_at DESC`;
+  return rows;
+});
 ```
 
-For client-side access, use the anon key instead of the service role key.
+The driver uses tagged template literals for automatic SQL injection
+protection — `await sql\`SELECT * FROM notes WHERE id = ${id}\`` is safe.
+No ORM, no query builder, no connection pool setup needed.
 
 ## Key Differences from Client-Side Code
 
 - Server routes run on the server (Node.js), not in the browser
-- They have access to Redis, Supabase, secrets, and server-only APIs
+- They have access to Redis, Neon Postgres, secrets, and server-only APIs
 - They do NOT have access to Vue composables, Vuetify, or any client-side code
 - Use `defineEventHandler`, not Vue component patterns