@yottagraph-app/aether-instructions 1.1.25 → 1.1.26

package/commands/build_my_app.md

@@ -10,7 +10,7 @@ This command reads `DESIGN.md` (which contains the project creator's vision) and
 
 ---
 
-## Step 1: Read the Brief
+## Step 1: Read the Brief and Design References
 
 Read `DESIGN.md` from the project root.
 
@@ -26,6 +26,33 @@ Look for a `## Vision` section -- this contains the project creator's descriptio
 
 Stop here and wait for the user to describe what they want.
 
+### Long-form briefs
+
+If the Vision section is long (roughly 500+ words -- a full PRD, spec, or design doc), don't try to hold it all in your head at once. Instead:
+
+1. Read the full Vision section carefully.
+2. Extract the **core purpose** (one sentence: what is this app for?).
+3. Identify the **MVP feature set** -- the minimum set of features that delivers the core value. Look for explicit priority indicators (P0/P1, "must have" vs "nice to have", numbered phases). If none exist, use your judgment: what's the smallest thing that works end-to-end?
+4. Create `design/requirements.md` with your extracted requirements, grouped by priority. This becomes your working checklist.
+5. Build the MVP first, then iterate. Don't try to implement every detail from a long brief in one pass.
+
+### Design references
+
+Check for a `## Design References` section in DESIGN.md and for files in `design/references/`:
+
+```bash
+ls design/references/ 2>/dev/null
+```
+
+If design reference images exist (screenshots from Figma or other design tools):
+
+1. **Examine each image** -- these are design mockups from the project creator showing what the app should look like.
+2. Describe what you see in each image: layout structure, navigation patterns, component types, color usage, typography.
+3. Map visual elements to **Vuetify components** (cards = `v-card`, data tables = `v-data-table`, navigation drawers = `v-navigation-drawer`, app bars = `v-app-bar`, etc.). If a `vuetify-figma` skill is available in `.cursor/skills/`, read it for detailed component mapping guidance.
+4. Use the design references alongside the Vision text to plan the UX. The images show *what it should look like*; the Vision text explains *what it should do*.
+
+If a Figma URL is referenced in DESIGN.md, note it for the user but don't attempt to fetch it -- work from the uploaded screenshots and the text brief.
+
 ---
 
 ## Step 2: Check MCP Servers

package/commands/manage_secrets.md

@@ -0,0 +1,158 @@
+# Manage Secrets
+
+Add, update, or remove environment variables (secrets) for your deployed app. Secrets are stored encrypted on Vercel and are available to your app at runtime and build time.
+
+## Overview
+
+This command manages environment variables on your project's Vercel deployment through the Broadchurch Portal API. After any change, it automatically syncs the updated values to your local `.env` file so your dev server stays in sync with production.
+
+**Prerequisite:** The project must have a valid `broadchurch.yaml` (created during provisioning).
+
+---
+
+## Step 1: Read Configuration
+
+Read `broadchurch.yaml` from the project root.
+
+```bash
+cat broadchurch.yaml
+```
+
+**If the file does not exist:**
+
+> This project hasn't been provisioned yet. Create it in the Broadchurch Portal first.
+
+Stop here.
+
+Extract these values:
+
+- `tenant.org_id` (tenant org ID)
+- `gateway.url` (Portal Gateway URL)
+
+---
+
+## Step 2: List Current Environment Variables
+
+Fetch the current user-managed environment variables:
+
+```bash
+curl -sf "<GATEWAY_URL>/api/projects/<ORG_ID>/env-vars"
+```
+
+Parse the JSON response. The `vars` array contains `{ key, value }` objects.
+
+Present the current state to the user:
+
+> **Environment Variables for this project:**
+>
+> | Key | Value |
+> |-----|-------|
+> | `MY_API_KEY` | `sk-abc...xyz` |
+> | `THIRD_PARTY_SECRET` | `secret_1234` |
+>
+> _(or "No environment variables set yet." if empty)_
+>
+> What would you like to do?
+>
+> 1. **Add** a new variable
+> 2. **Update** an existing variable
+> 3. **Remove** a variable
+> 4. **Done** — nothing to change
+
+Wait for the user to choose.
+
+---
+
+## Step 3: Execute the Change
+
+### If adding or updating:
+
+Ask the user for the key name and value. Key names must match `[A-Za-z_][A-Za-z0-9_]*`.
+
+```bash
+curl -sf -X PUT "<GATEWAY_URL>/api/projects/<ORG_ID>/env-vars" \
+  -H "Content-Type: application/json" \
+  -d '{"vars": {"<KEY>": "<VALUE>"}}'
+```
+
+**If the API returns 403:** The key is a platform-managed variable and cannot be modified by users.
+
+### If removing:
+
+Confirm which key to delete, then:
+
+```bash
+curl -sf -X DELETE "<GATEWAY_URL>/api/projects/<ORG_ID>/env-vars/<KEY>"
+```
+
+**If the API returns 404:** The variable doesn't exist.
+
+---
+
+## Step 4: Sync Local .env
+
+After the API call succeeds, update the local `.env` file to match.
+
+1. Read the current `.env` file
+2. Look for a `# User secrets (managed via Broadchurch Portal)` section delimiter
+3. **If the section exists:** Replace everything from that delimiter to the next blank line (or end of file) with the updated variables
+4. **If the section doesn't exist:** Append it at the end of `.env`
+
+Fetch the current full list to ensure local is in sync:
+
+```bash
+curl -sf "<GATEWAY_URL>/api/projects/<ORG_ID>/env-vars"
+```
+
+Then write the section to `.env`:
+
+```
+# User secrets (managed via Broadchurch Portal)
+KEY_ONE=value_one
+KEY_TWO=value_two
+```
+
+**Important:** Do not modify any other lines in `.env`. Only touch lines within the user secrets section.
+
+---
+
+## Step 5: Confirm and Offer Next Steps
+
+> Updated `<KEY>`:
+>
+> - Vercel (production + preview) — updated
+> - Local `.env` — synced
+>
+> **Restart your dev server** (`npm run dev`) if it's running, to pick up the change locally.
+
+If the variable name starts with `NUXT_PUBLIC_`:
+
+> **Note:** `NUXT_PUBLIC_*` variables are baked into the app at build time. The Vercel deployment will need a rebuild for the change to take effect in production. Push a commit or trigger a redeployment from the Portal.
+
+If the variable name does NOT start with `NUXT_PUBLIC_`:
+
+> This server-side variable will be available on the next request in production — no redeployment needed.
+
+Then ask:
+
+> Would you like to add, update, or remove another variable? (or type "done")
+
+If yes, go back to Step 3. If done, finish.
+
+---
+
+## Troubleshooting
+
+### "Project has no Vercel project configured"
+
+The project's Vercel integration wasn't set up during provisioning. Check the Broadchurch Portal for the project status.
+
+### API returns 403 for a key
+
+The key is platform-managed (Auth0, gateway, query server, etc.) and cannot be modified through this command. Use the Portal's Platform Services section instead.
+
+### Variable not appearing in the deployed app
+
+- **`NUXT_PUBLIC_*` vars** need a redeployment (push a commit or trigger from Portal)
+- **Server-side vars** should be available immediately — check that the key name is correct
+- Make sure you're reading the variable correctly in code: use `useRuntimeConfig()` in Nuxt, not `process.env` directly

package/package.json

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

package/rules/design.mdc

@@ -31,10 +31,23 @@ asks to keep specific parts.
 
 # Project Brief
 
-If `DESIGN.md` has a `## Vision` section, it contains the project creator's original description of what they want to build — written during project setup in the Broadchurch Portal.
+If `DESIGN.md` has a `## Vision` section, it contains the project creator's original description of what they want to build — written during project setup in the Broadchurch Portal. This can range from a single sentence to a full PRD with user stories, wireframes, and technical constraints.
 
 When a user opens the project for the first time and hasn't started building yet (the `## Status` section says "Run `/build_my_app`"), suggest running that command. If they ask "what should I build?" or similar, read the Vision section of DESIGN.md first.
 
+## Long-form briefs
+
+Users may paste full PRD or spec documents as their project brief. When the Vision section is long (500+ words), focus on extracting the MVP scope before building. Look for priority indicators, phased rollout plans, or "must-have" vs "nice-to-have" distinctions. If none exist, identify the smallest coherent feature set that demonstrates the core value. Create `design/requirements.md` to capture your extracted requirements as a working checklist.
+
+## Design references
+
+`DESIGN.md` may include a `## Design References` section with Figma URLs and/or image references. Design mockup images live in `design/references/`. When these exist:
+
+- Examine the images to understand intended layout, navigation patterns, and visual style
+- Map visual elements to Vuetify components (if a `vuetify-figma` skill exists, use it)
+- Treat design references as the "what it should look like" complement to the Vision's "what it should do"
+- Figma URLs are informational — work from the uploaded screenshots, not the live Figma file
+
 # Feature docs
 
 Feature docs are used as working documents to help a user and agent collaborate on feature implementation. A feature can be whatever size you need -- an entire page, a shared composable, or a single component.