@yottagraph-app/aether-instructions 1.1.16 → 1.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@yottagraph-app/aether-instructions",
-    "version": "1.1.16",
+    "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

@@ -68,6 +68,9 @@ 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 `DATABASE_URL` is in `.env`, Postgres is ready to use. The project init
@@ -81,6 +84,12 @@ automatically when a Neon database is detected.
 - If either is missing, the project wasn't provisioned with Neon (add it
   from the Broadchurch Portal, then re-run `node init-project.js`)
 
+**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.
+
 ### Usage
 
 `server/utils/neon.ts` exports `getDb()` (same lazy-init pattern as
@@ -103,6 +112,25 @@ 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):
@@ -136,3 +164,6 @@ export function getDb(): NeonQueryFunction | null {
 - 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.