@yottagraph-app/aether-instructions 1.1.15 → 1.1.17

package/package.json

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

package/rules/pref.mdc

@@ -46,19 +46,23 @@ The backing store auto-initializes on first use — no need to call
 
 ## Local Development
 
-When KV credentials (`KV_REST_API_URL`, `KV_REST_API_TOKEN`) are not set
-(e.g. local dev without Vercel env vars), the KV server routes return
-`undefined` for reads and silently skip writes. Prefs will work with
-their default values but won't persist across page refreshes.
+KV credentials are only available in deployed builds (Vercel auto-injects
+them at runtime). In local dev, `getRedis()` returns `null` and KV routes
+return `undefined` for reads and silently skip writes. `Pref<T>` still
+works with its default value but won't persist across page refreshes.
 
-For full local persistence, copy the KV credentials from your Vercel
-project settings into your local `.env` file (or use the Portal's
-"Get .env file" feature).
+This is expected — push to `main` and test persistence on the deployed build.
+
+**Auth dependency:** All `/api/kv/*` routes call `unsealCookie(event)` to
+identify the user. In dev mode (no `NUXT_PUBLIC_AUTH0_CLIENT_SECRET` set),
+this is bypassed automatically using `NUXT_PUBLIC_USER_NAME`. If you set an
+Auth0 client secret without proper cookie setup, KV writes will silently
+no-op.
 
 ## Direct API Alternative
 
 If you prefer not to use the `Pref<T>` class, you can call the KV
-routes directly:
+routes directly from client-side code:
 
 ```typescript
 // Read
@@ -73,6 +77,11 @@ await $fetch('/api/kv/write', {
 });
 ```
 
+These routes require the browser's auth cookie — they work from client-side
+`$fetch` calls but not from server routes or external scripts. For
+server-to-server KV access, use `getRedis()` from `server/utils/redis.ts`
+directly.
+
 ## Feature-Scoped Preferences
 
 Features should namespace preferences under the app's prefix:

package/rules/server.mdc

@@ -19,7 +19,8 @@ server/
 │   ├── kv/                  # KV (Upstash Redis) CRUD — read, write, delete, documents, status
 │   └── avatar/[url].ts      # Avatar image proxy
 └── utils/
-    ├── redis.ts              # Upstash Redis client init (from Vercel KV env vars)
+    ├── redis.ts              # Upstash Redis client (lazy-init from KV_REST_API_URL)
+    ├── neon.ts               # Neon Postgres client (lazy-init from DATABASE_URL) — present if Neon provisioned
     └── cookies.ts            # Cookie handling (@hapi/iron)
 ```
 
@@ -67,35 +68,33 @@ if (redis) {
 
 Returns `null` if KV is not configured (env vars missing). Always check.
 
+For client-side preferences, use `usePrefsStore()` and `Pref<T>` instead of
+calling KV routes directly — see the `pref` rule.
+
 ## Neon Postgres
 
-If a Neon database is connected to the project, `DATABASE_URL` (pooled) and
-`DATABASE_URL_UNPOOLED` (direct) are available. Vercel auto-injects them for
-deployed builds; for local dev they are populated in `.env` during project
-init. Check `.env` for `DATABASE_URL` — if present, Postgres is ready to use.
+If `DATABASE_URL` is in `.env`, Postgres is ready to use. The project init
+scaffolds `server/utils/neon.ts` and installs `@neondatabase/serverless`
+automatically when a Neon database is detected.
 
-### Utility pattern
+### How to check
 
-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:
+- `DATABASE_URL` present in `.env` → Postgres is connected
+- `server/utils/neon.ts` exists → utility is scaffolded
+- If either is missing, the project wasn't provisioned with Neon (add it
+  from the Broadchurch Portal, then re-run `node init-project.js`)
 
-```typescript
-import { neon, type NeonQueryFunction } from '@neondatabase/serverless';
+**Local dev:** `DATABASE_URL` is not yet available for local development.
+`getDb()` returns `null` when the credential is missing or invalid. Write
+your server routes to handle this gracefully (return a "database not
+configured" error or empty state). Push to `main` to test with a real
+database on the deployed build, where credentials are auto-injected.
 
-let _sql: NeonQueryFunction | null = null;
+### Usage
 
-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
+`server/utils/neon.ts` exports `getDb()` (same lazy-init pattern as
+`getRedis()` in `redis.ts`): returns a query function or `null` if
+`DATABASE_URL` is not set.
 
 ```typescript
 import { getDb } from '~/server/utils/neon';
@@ -109,13 +108,62 @@ export default defineEventHandler(async () => {
 });
 ```
 
-The driver uses tagged template literals for automatic SQL injection
+The Neon 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.
 
+### Creating tables
+
+There is no migrations framework. Use `CREATE TABLE IF NOT EXISTS` directly
+in a setup route or at the top of a route that needs the table:
+
+```typescript
+const sql = getDb()!;
+await sql`CREATE TABLE IF NOT EXISTS notes (
+  id SERIAL PRIMARY KEY,
+  content TEXT NOT NULL,
+  created_at TIMESTAMPTZ DEFAULT NOW()
+)`;
+```
+
+For simple apps, putting the `CREATE TABLE IF NOT EXISTS` in each route that
+uses the table is fine — it's a no-op after the first call. For more complex
+schemas, create a `server/api/db/setup.post.ts` route that initializes all
+tables.
+
+### If `server/utils/neon.ts` doesn't exist
+
+Create it manually (or re-run init):
+
+```bash
+npm install @neondatabase/serverless
+```
+
+```typescript
+// server/utils/neon.ts
+import { neon, type NeonQueryFunction } from '@neondatabase/serverless';
+
+let _sql: NeonQueryFunction | null = null;
+
+export function isDbConfigured(): boolean {
+  return Boolean(process.env.DATABASE_URL);
+}
+
+export function getDb(): NeonQueryFunction | null {
+  if (_sql) return _sql;
+  const url = process.env.DATABASE_URL;
+  if (!url) return null;
+  _sql = neon(url);
+  return _sql;
+}
+```
+
 ## Key Differences from Client-Side Code
 
 - Server routes run on the server (Node.js), not in the browser
 - 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
+
+See `architecture` rule for the full data architecture overview, `pref` rule
+for client-side KV preferences.