@yottagraph-app/aether-instructions 1.0.1

package/README.md

@@ -0,0 +1,52 @@
+# @yottagraph-app/aether-instructions
+
+Cursor rules, commands, and skills for Aether development.
+
+## Usage
+
+This package is automatically downloaded and extracted during Aether project
+initialization (`init-project.js`). You don't need to install it directly.
+
+### Updating Instructions
+
+To update to the latest version:
+
+```
+/aether_update_instructions
+```
+
+This Cursor command will:
+1. Download the latest version of this package
+2. Delete existing `aether_*` files in `.cursor/`
+3. Extract fresh files from the package
+4. Commit the changes
+
+### File Naming Convention
+
+All files from this package are prefixed with `aether_`:
+- Rules: `.cursor/rules/aether_*.mdc`
+- Commands: `.cursor/commands/aether_*.md`
+- Skills: `.cursor/skills/aether_*/`
+
+This separates package-provided files from your own custom files. Files with
+the `aether_` prefix will be overwritten on update; your non-prefixed files
+are untouched.
+
+### Customizing Rules/Commands
+
+To customize a package file:
+1. Copy it to a new name without the `aether_` prefix
+2. Make your changes to the copy
+3. Your copy won't be affected by instruction updates
+
+## For Maintainers
+
+This package is built from `aether-dev` sources. To publish:
+
+1. Make changes to `rules/`, `commands/`, or `skills/` in aether-dev
+2. Run `/publish_instructions --bump patch --publish`
+
+The publish command:
+- Copies source files with `aether_` prefix to `packages/aether-instructions/`
+- Bumps the version
+- Publishes to npmjs

package/commands/aether_broadchurch_setup.md

@@ -0,0 +1,163 @@
+# Broadchurch Setup
+
+Set up this Aether project for deploying agents and MCP servers to GCP via Broadchurch.
+
+## Overview
+
+This command walks through connecting an Aether project to the Broadchurch tenant infrastructure. It creates a `broadchurch.yaml` config file that stores the tenant's GCP project, service account, and deployment state. All subsequent `/deploy_agent` and `/deploy_mcp` commands read from this file.
+
+**Prerequisite:** The user must have `gcloud` installed and authenticated, and their tenant must already exist in the Broadchurch Tenant Registry (created via the Portal or provisioning scripts).
+
+---
+
+## Step 1: Check for Existing Configuration
+
+Check if `broadchurch.yaml` already exists in the project root.
+
+```bash
+cat broadchurch.yaml 2>/dev/null
+```
+
+**If the file exists:** Show the current config and ask:
+
+> Broadchurch is already configured for this project. Would you like to reconfigure it?
+
+If no, stop here. If yes, continue.
+
+**If the file does not exist:** Continue with setup.
+
+---
+
+## Step 2: Verify gcloud Authentication
+
+```bash
+gcloud auth list --filter=status:ACTIVE --format="value(account)" 2>&1
+```
+
+**If no active account:** Tell the user:
+
+> You need to authenticate with Google Cloud first. Run: `gcloud auth login`
+
+Wait for confirmation before continuing.
+
+**Also check application default credentials:**
+
+```bash
+gcloud auth application-default print-access-token > /dev/null 2>&1
+echo $?
+```
+
+**If this fails:** Tell the user:
+
+> Application Default Credentials are not set up. Run: `gcloud auth application-default login`
+
+---
+
+## Step 3: Gather Tenant Information
+
+Ask the user for their Auth0 Organization ID. This is the identifier from the Broadchurch Portal (format: `org_XXXXXXXXXXXXXX`).
+
+> What is your Auth0 Organization ID? (e.g., org_U7tGKXTsbfM30te6)
+
+If the user doesn't know, suggest:
+
+> You can find this in the Broadchurch Portal under your tenant settings, or ask your Lovelace admin.
+
+---
+
+## Step 4: Look Up Tenant Configuration
+
+Once you have the org_id, check if the tenant exists. The user needs to provide or you need to look up:
+
+- **GCP Project:** The GCP project ID for this tenant (e.g., `broadchurch`)
+- **GCP Region:** The deployment region (default: `us-central1`)
+- **Service Account:** The tenant's service account email
+
+Ask the user to confirm these values, or provide them if they have a different setup:
+
+> Here's the configuration I'll use:
+>
+> - **GCP Project:** broadchurch
+> - **Region:** us-central1
+> - **Tenant Name:** (from user input)
+>
+> Does this look right?
+
+---
+
+## Step 5: Create Staging Bucket
+
+The agent deployment pipeline needs a GCS bucket for staging artifacts.
+
+```bash
+BUCKET_NAME="gs://broadchurch-staging-$(echo $ORG_ID | tr '[:upper:]' '[:lower:]' | sed 's/org_//')"
+gsutil ls $BUCKET_NAME 2>/dev/null || gsutil mb -p $PROJECT_ID -l $REGION $BUCKET_NAME
+```
+
+---
+
+## Step 6: Verify ADK Installation
+
+Check that the Google ADK CLI is available:
+
+```bash
+adk --version 2>&1
+```
+
+**If not installed:** Tell the user:
+
+> The Google ADK CLI is required for deploying agents. Install it with:
+>
+> ```
+> pip install google-adk
+> ```
+
+---
+
+## Step 7: Write broadchurch.yaml
+
+Create the configuration file:
+
+```yaml
+# Broadchurch Tenant Configuration
+# Generated by /broadchurch_setup
+# Do not commit secrets to this file.
+
+tenant:
+    org_id: <ORG_ID>
+    name: '<TENANT_NAME>'
+
+gcp:
+    project: <PROJECT_ID>
+    region: <REGION>
+    service_account: <SERVICE_ACCOUNT_EMAIL>
+    staging_bucket: <BUCKET_NAME>
+
+# Auto-populated by /deploy_agent and /deploy_mcp
+agents: {}
+mcp_servers: {}
+```
+
+Also add `broadchurch.yaml` to `.gitignore` if it's not already there (it may contain sensitive config).
+
+---
+
+## Step 8: Verify Connectivity
+
+Run a quick check to verify everything works:
+
+```bash
+gcloud projects describe $PROJECT_ID --format="value(projectId)" 2>&1
+```
+
+**If successful:**
+
+> Broadchurch setup complete! Your project is configured for agent and MCP server deployment.
+>
+> Next steps:
+>
+> - Create an agent in `agents/` and deploy with `/deploy_agent`
+> - Create an MCP server in `mcp-servers/` and deploy with `/deploy_mcp`
+> - Deploy your UI to Vercel with `/vercel_deploy`
+
+**If it fails:** Help the user troubleshoot the GCP authentication.

package/commands/aether_build_my_app.md

@@ -0,0 +1,148 @@
+# Build My App
+
+Read the project brief and build the described application.
+
+## Overview
+
+This command reads `DESIGN.md` (which contains the project creator's vision) and implements the described application using standard Nuxt patterns, Vuetify components, and the Lovelace platform's data APIs.
+
+**This is meant to be the first thing a user runs after opening their project in Cursor.**
+
+---
+
+## Step 1: Read the Brief
+
+Read `DESIGN.md` from the project root.
+
+```bash
+cat DESIGN.md
+```
+
+Look for a `## Vision` section -- this contains the project creator's description of what they want to build.
+
+**If the file doesn't exist or has no Vision section:**
+
+> No project brief found. That's fine -- tell me what you'd like to build and I'll help you get started!
+
+Stop here and wait for the user to describe what they want.
+
+---
+
+## Step 2: Enable MCP Servers
+
+Check if `.cursor/mcp.json` exists and contains Lovelace MCP servers:
+
+```bash
+cat .cursor/mcp.json 2>/dev/null
+```
+
+**If the file contains `mcpServers`:** These MCP servers give you access to Lovelace platform tools (entity search, market data, news, etc.) that you'll need during development. Cursor disables new MCP servers by default, so ask the user:
+
+> Before we start building, let's make sure your MCP tools are enabled.
+>
+> Open **Cursor Settings** (Cmd+Shift+J) → **Tools & MCP** and enable the `lovelace-*` servers listed there. They should show green toggles when active.
+>
+> Let me know when they're enabled (or if you'd like to skip this for now).
+
+Wait for confirmation before proceeding. If the user skips this step, note that MCP tools won't be available during the build but can be enabled later.
+
+**If the file doesn't exist or has no servers:** Skip this step silently.
+
+---
+
+## Step 3: Understand the Environment
+
+First, ensure dependencies are installed (skill docs and types aren't available without this):
+
+```bash
+test -d node_modules || npm install
+```
+
+Then read these files to understand what's available:
+
+1. `DESIGN.md` -- project vision and current status
+2. `broadchurch.yaml` -- project config (name, gateway URL, etc.)
+3. **The `api` cursor rule** -- this is critical. It describes the Query Server, the platform's primary data source. Build against platform APIs, not external sources.
+4. The **elemental-api skill docs** in `skills/elemental-api/` -- start with `SKILL.md` for API overview, then `entities.md`, `schema.md`, etc.
+5. `.cursor/rules/` -- scan rule names to know what other patterns are available
+
+**Important: Use the platform's data.** This app runs on the Lovelace platform, which provides a Query Server with entities, news, filings, sentiment, relationships, events, and more. Read the `api` rule and the skill docs to understand what data is available. Use `getSchema()` to discover entity types and properties at runtime.
+
+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
+- **AI agent chat** -- `pages/chat.vue` exists for agent interactions
+- **MCP Explorer** -- `pages/mcp.vue` for testing MCP tools
+- **Components** -- Vuetify 3 component library is available
+
+---
+
+## Step 4: Design the UX
+
+Based on the brief, think about the right UX for this specific problem. Do NOT default to a sidebar-with-tabs layout. Consider:
+
+- **Single-page app** -- if the core experience is one focused view (e.g. a dashboard, a watchlist, a chat interface)
+- **Multi-page with navigation** -- if the app has distinct sections. Choose the right nav pattern: sidebar, top tabs, bottom nav, breadcrumbs, etc.
+- **Hybrid** -- a primary view with secondary pages accessible from a menu or header
+
+Design the UX around the user's workflow, not around a fixed navigation pattern.
+
+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)
+5. Whether the app needs AI agents or MCP servers
+6. Whether to keep, modify, or remove the built-in pages (`chat.vue`, `mcp.vue`, `entity-lookup.vue`)
+7. Whether `app.vue` needs a sidebar, tabs, or other navigation (and what it should look like)
+
+Present the plan to the user and ask for approval before proceeding.
+
+---
+
+## Step 5: Build
+
+Implement the plan:
+
+1. Create pages in `pages/` (standard Nuxt file-based routing)
+2. Extract reusable components into `components/`
+3. Put shared logic in `composables/`
+4. If the app needs navigation, add it to `app.vue` or to individual pages
+5. Use `Pref<T>` for any persisted settings (see `pref.mdc`)
+6. Use Vuetify components and the project's dark theme
+7. Update `DESIGN.md` with what you built
+
+**Follow the project's coding conventions:**
+
+- `<script setup lang="ts">` for all Vue components
+- TypeScript required
+- Composables return `readonly()` refs with explicit setters
+
+---
+
+## Step 6: Verify
+
+After building, check dependencies are installed and run a build:
+
+```bash
+test -d node_modules || npm install
+npm run build
+```
+
+Fix any build errors.
+
+Then suggest the user run `npm run dev` to preview their app locally.
+
+---
+
+## Step 7: Next Steps
+
+> Your app is taking shape! Here's what you can do next:
+>
+> - **Preview locally** with `npm run dev`
+> - **Push to deploy** -- Vercel auto-deploys on push to main
+> - **Deploy an AI agent** -- run `/deploy_agent` when you have an agent ready
+> - **Deploy an MCP server** -- run `/deploy_mcp` for tool servers

package/commands/aether_configure_query_server.md

@@ -0,0 +1,90 @@
+# Configure Query Server
+
+Change the Query Server address used by this project for data access (Elemental API).
+
+## Overview
+
+This command updates the Query Server URL in both `broadchurch.yaml` and `.env` so your local dev server uses the new address. No portal access is needed.
+
+**Prerequisite:** The project must have a `broadchurch.yaml` file (created during provisioning or `/broadchurch_setup`).
+
+---
+
+## Step 1: Read Current Configuration
+
+Read `broadchurch.yaml` from the project root.
+
+```bash
+cat broadchurch.yaml
+```
+
+**If the file does not exist:**
+
+> This project doesn't have a `broadchurch.yaml` yet. Run `/broadchurch_setup` first, or create one manually.
+
+Stop here.
+
+Extract the current `query_server.url` value.
+
+Also read `.env` to check the current `NUXT_PUBLIC_QUERY_SERVER_ADDRESS`:
+
+```bash
+grep NUXT_PUBLIC_QUERY_SERVER_ADDRESS .env
+```
+
+Show the user the current value from both files.
+
+---
+
+## Step 2: Ask for the New Address
+
+Present the user with common options:
+
+> **Current Query Server:** `<current_url>`
+>
+> Which Query Server would you like to use?
+>
+> 1. **Production** — `https://query.news.prod.g.lovelace.ai`
+> 2. **Sandbox** — `https://query.news.sbox.g.lovelace.ai`
+> 3. **Local** — `http://localhost:8080`
+> 4. **Custom** — Enter a custom URL
+
+Wait for the user to choose.
+
+---
+
+## Step 3: Update broadchurch.yaml
+
+Replace the `query_server.url` value in `broadchurch.yaml` with the new URL. The line to update looks like:
+
+```yaml
+query_server:
+  url: "<NEW_URL>"
+```
+
+Preserve all other content in the file.
+
+---
+
+## Step 4: Update .env
+
+Update the `NUXT_PUBLIC_QUERY_SERVER_ADDRESS` line in `.env`:
+
+```
+NUXT_PUBLIC_QUERY_SERVER_ADDRESS=<NEW_URL>
+```
+
+**If the line doesn't exist in `.env`:** Add it.
+
+---
+
+## Step 5: Confirm
+
+> Query Server updated to `<NEW_URL>`.
+>
+> - `broadchurch.yaml` — updated
+> - `.env` — updated
+>
+> **Restart your dev server** (`npm run dev`) for the change to take effect.
+>
+> Note: This only affects your local environment. To update the deployed app, change the Query Server address in the Broadchurch Portal (it will propagate to your repo and Vercel automatically).

package/commands/aether_deploy_agent.md

@@ -0,0 +1,153 @@
+# Deploy Agent
+
+Deploy an ADK agent from the `agents/` directory to Vertex AI Agent Engine via the Broadchurch Portal.
+
+## Overview
+
+This command deploys a Python ADK agent by triggering a GitHub Actions workflow through the Portal API. No local GCP credentials are needed -- the workflow authenticates via Workload Identity Federation.
+
+The agent must live in `agents/<name>/` with the standard ADK structure (`agent.py`, `__init__.py`, `requirements.txt`).
+
+**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: Discover Agents
+
+List the directories under `agents/`:
+
+```bash
+ls -d agents/*/
+```
+
+**If no directories exist:**
+
+> No agents found. Create one by making a directory under `agents/` with the following structure:
+>
+> ```
+> agents/my_agent/
+> ├── __init__.py
+> ├── agent.py       # Your ADK agent definition (must export root_agent)
+> └── requirements.txt
+> ```
+>
+> See the `agents.mdc` rule for guidance on writing ADK agents.
+
+Stop here.
+
+**If multiple agents exist:** Ask the user which one to deploy.
+
+**If only one agent exists:** Confirm with the user.
+
+**Important:** Agent directory names must use underscores, not hyphens (e.g., `my_agent` not `my-agent`).
+
+---
+
+## Step 3: Validate Agent Structure
+
+For the selected agent directory, verify the required files exist:
+
+```bash
+ls agents/<name>/__init__.py agents/<name>/agent.py agents/<name>/requirements.txt
+```
+
+**If any are missing:** Tell the user what's needed.
+
+Also verify that `agent.py` exports a `root_agent`:
+
+```bash
+grep -l "root_agent" agents/<name>/agent.py
+```
+
+---
+
+## Step 4: Ensure Code is Pushed
+
+The deployment workflow runs on the code in the GitHub repo, not the local working directory. Make sure the agent code is committed and pushed:
+
+```bash
+git status
+```
+
+**If there are uncommitted changes in `agents/<name>/`:**
+
+> Your agent code has local changes that aren't pushed yet. The deployment will use the version on GitHub. Would you like me to commit and push first?
+
+If yes, commit and push. If no, warn them and continue.
+
+---
+
+## Step 5: Trigger Deployment
+
+Call the Portal API to trigger the deploy workflow:
+
+```bash
+curl -sf -X POST "<GATEWAY_URL>/api/projects/<ORG_ID>/deploy" \
+  -H "Content-Type: application/json" \
+  -d '{"type": "agent", "name": "<AGENT_NAME>"}'
+```
+
+**If this fails with 404:** The agent directory may not exist on GitHub yet. Push your code first.
+
+**If this succeeds:** The Portal has triggered the `deploy-agent.yml` GitHub Actions workflow.
+
+---
+
+## Step 6: Monitor Progress
+
+> Deployment triggered! The agent is being deployed via GitHub Actions.
+>
+> - **Agent:** <name>
+> - **Workflow:** deploy-agent.yml
+>
+> This typically takes 2-5 minutes. You can monitor progress:
+>
+> - In the Broadchurch Portal under your project's Deployment Status section
+> - On GitHub: `https://github.com/<REPO>/actions`
+>
+> Once complete, the agent will automatically appear in your app's `/chat` page.
+
+---
+
+## Troubleshooting
+
+### Deployment workflow fails
+
+Check the GitHub Actions logs for the `Deploy Agent` workflow. Common issues:
+
+- **"agent.py does not export root_agent"**: Ensure your agent module defines `root_agent`.
+- **"Module not found"**: All dependencies must be in the agent's `requirements.txt`.
+- **WIF auth failure**: The Broadchurch admin needs to run the WIF setup script (`portal/scripts/setup-wif.sh`).
+
+### Agent directory naming
+
+ADK requires directory names to use underscores (Python package convention). If your directory uses hyphens, rename it:
+
+```bash
+mv agents/my-agent agents/my_agent
+```
+
+### "No agents found" after successful deploy
+
+The workflow registers the agent with the Portal automatically. If it doesn't appear, check the workflow logs for the "Register with Portal" step.