@yottagraph-app/aether-instructions 1.1.38 → 1.1.40

package/package.json

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

package/rules/agents-data.mdc

@@ -71,6 +71,45 @@ In production, all Elemental API calls go through the Portal Gateway at
 `broadchurch.yaml`) and the portal injects its own Auth0 M2M token
 upstream.
 
+## Agent secrets (DATABASE_URL etc.)
+
+For runtime values that aren't shipped in `broadchurch.yaml` and can't be
+sourced from Vercel — most commonly `DATABASE_URL` for tenants whose
+Postgres is provisioned via the Vercel Neon integration — use
+`get_agent_secret()` from `broadchurch_auth`. It fetches from the portal
+at `GET /api/agent-secrets/{org_id}` using the same `X-Api-Key` the agent
+already carries, and caches per-process.
+
+```python
+try:
+    from broadchurch_auth import get_agent_secret
+except ImportError:
+    from .broadchurch_auth import get_agent_secret
+
+def my_db_tool() -> str:
+    db_url = get_agent_secret("DATABASE_URL")
+    if not db_url:
+        return "DATABASE_URL is not configured for this tenant."
+    # ... use db_url ...
+```
+
+Resolution order is `os.environ[name]` → portal-stored secret → default.
+The env var path means local dev "just works" with `export DATABASE_URL=...`
+without touching the portal.
+
+Set values via the portal admin endpoint:
+
+```bash
+curl -X PUT $GATEWAY_URL/api/projects/$ORG_ID/agent-secrets \
+  -H 'Content-Type: application/json' \
+  -d '{"vars": {"DATABASE_URL": "postgresql://..."}}'
+```
+
+Secrets are stored encrypted-at-rest in Firestore on the tenant doc.
+There is no per-tenant Vercel/Neon integration — when credentials rotate,
+push the new value via the same endpoint and let the agent cold-start
+pick it up (or call `get_agent_secrets(refresh=True)`).
+
 ## MCP-based agents
 
 When the project uses **MCP-only data architecture**, agents access the

package/rules/server.mdc

@@ -20,7 +20,7 @@ server/
 │   └── avatar/[url].ts      # Avatar image proxy
 └── utils/
     ├── 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
+    ├── neon.ts               # Neon Postgres client (lazy-init from DATABASE_URL) — create if missing when Neon is provisioned
     └── cookies.ts            # Cookie handling (@hapi/iron)
 ```
 
@@ -73,16 +73,27 @@ calling KV routes directly — see the `pref` rule.
 
 ## Neon Postgres
 
-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.
+Neon provisioning is decided by the portal, not by what is in `.env`.
+`DATABASE_URL` and `DATABASE_URL_UNPOOLED` are intentionally left commented
+out locally — Neon does not work in local dev. On deploy, Vercel
+auto-injects `DATABASE_URL` at runtime.
 
 ### How to check
 
-- `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`)
+Pull `gateway.url` and `tenant.org_id` out of `broadchurch.yaml` and ask the
+portal:
+
+```bash
+curl <gateway.url>/api/tenants/<tenant.org_id>
+```
+
+- Provisioned: `vercel.postgres_store_id` is set in the response. The
+  `DATABASE_URL` is also findable under `agent_secrets`, but you usually
+  don't need to read it.
+- `server/utils/neon.ts` present → ready to use. If missing, create it
+  (mirror the `getDb()` lazy-init pattern in `server/utils/redis.ts`).
+- `@neondatabase/serverless` in `package.json` → ready. If missing, run
+  `npm install @neondatabase/serverless`.
 
 **Local dev:** `DATABASE_URL` is not yet available for local development.
 `getDb()` returns `null` when the credential is missing or invalid. Write