@yottagraph-app/aether-instructions 1.1.27 → 1.1.28

package/variants/mcp-only/commands/build_my_app.md

@@ -0,0 +1,146 @@
+# Build My App (MCP-only data mode)
+
+Read the project brief and build the described application.
+
+**MCP-only** means the SPA does **not** use `useElementalClient()` for primary platform data — **ADK agents** use **Elemental MCP** to reach the graph.
+
+**Valid product shapes include:**
+
+- **Materialized data** — Agents sync or aggregate graph data into **Postgres** (or similar); the Nuxt app reads via your own APIs and composables.
+- **Research / investigation / aggregation** — Agents use MCP tools inside multi-step workflows; outputs may be answers, reports, or partial writes — with or without a large local mirror of the graph.
+- **Channeling** — Agents invoke MCP tools and return **natural-language** answers to the user (often chat-first; minimal or no Postgres for graph data).
+- **Mixes** — e.g. a sync job for dashboards plus a research agent plus a channel agent for Q&A.
+
+Read the **`data`** and **`agents-data`** cursor rules for detail.
+
+**This is meant to be the first thing a user runs after opening their project in Cursor.**
+
+---
+
+## Step 1: Read the Brief and Design References
+
+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.
+
+### 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: MCP for development
+
+Check if Lovelace MCP tools are available (e.g. `elemental_get_schema`, `elemental_get_entity`). Use them while **authoring agents** and validating graph behavior.
+
+**If MCP tools are NOT available**, check `.cursor/mcp.json`:
+
+```bash
+cat .cursor/mcp.json 2>/dev/null
+```
+
+If the file exists but tools aren't active yet:
+
+> Your project has Lovelace MCP servers configured (`.cursor/mcp.json`), but they don't appear to be active yet. Cursor disables new MCP servers by default.
+>
+> Open **Cursor Settings** (Cmd+Shift+J on macOS) → **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).
+
+Wait for confirmation before proceeding if you asked the user to enable servers. If the user skips or the panel isn't available (e.g. Cursor Cloud), proceed — you can still follow the **`data`** rule and ship agents that use MCP at **runtime**.
+
+The **Nuxt** layer may combine **your APIs** (often Postgres-backed), **chat** via **`useAgentChat`**, or both — not Elemental REST from Vue for graph data.
+
+---
+
+## Step 3: Understand the Environment
+
+Run `npm install` / `node init-project.js` as needed so `.cursor/skills/` includes **`data-model`** (no `elemental-api` skill in this mode).
+
+Read:
+
+1. `DESIGN.md` — which of the valid shapes above (or a mix) the brief implies
+2. `broadchurch.yaml`
+3. **`data` rule** — MCP-only patterns
+4. **`agents-data` rule** — wiring MCP into ADK
+5. **`cookbook-data` / `server` / `server-data`** — when the UI lists data from **your** APIs / Postgres
+
+---
+
+## Step 4: Verify assumptions
+
+- **Postgres-backed UIs:** confirm **`DATABASE_URL`** where needed; plan tables and **`data-model`** semantics for agents that materialize data.
+- **Chat-first:** confirm **`useAgentChat`** + gateway; agents registered; MCP available in the agent runtime.
+- Explore schema with MCP tools in Cursor as needed for any shape.
+
+---
+
+## Step 5: Design the UX
+
+Match the brief: dashboards from `/api/...`, **chat** as primary, or both. No Elemental client calls in components for graph data.
+
+---
+
+## Step 6: Build
+
+1. **`agents/`** — one or more agents per `agents-data` (sync, research, channeling, or mixed).
+2. **`server/api/` + composables + `pages/`** — when the brief needs materialized lists or detail.
+3. **`pages/chat` or custom** — when the brief is agent-forward.
+4. **`DESIGN.md`** — document what you shipped.
+
+---
+
+## Step 7: Verify
+
+After building, ensure dependencies are installed and run a production 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 locally.
+
+Deploy agents as needed; if the brief relies on **materialized** data, run or schedule the relevant agents before expecting full UI data.
+
+---
+
+## Step 8: Next steps
+
+> Your app is taking shape. Suggested follow-ups:
+>
+> - **Preview locally** with `npm run dev`
+> - **Push to deploy** — Vercel auto-deploys on push to main
+> - **Agents** — run `/deploy_agent` when an agent is ready; ensure MCP is configured for the agent runtime per `agents-data`
+> - **MCP servers** — run `/deploy_mcp` if you add custom tool servers

package/variants/mcp-only/rules/agents-data.mdc

@@ -0,0 +1,45 @@
+---
+description: "MCP-only: ADK agents use Elemental MCP for sync, research, investigation, aggregation, or channeling — Postgres optional."
+alwaysApply: false
+globs: agents/**
+---
+
+# Agents: Elemental MCP (MCP-only)
+
+In **mcp-only** mode, **Elemental MCP** is the primary way agents reach the knowledge graph. **`broadchurch_auth` HTTP** to the Query Server is the **api-mcp** path; here you wire **MCP tools** into ADK (e.g. **McpToolset** + `SseConnectionParams` to your Elemental MCP URL — from env or `broadchurch.yaml` / gateway).
+
+## Primary agent patterns (all first-class)
+
+**A. Sync / materialization** — Agent runs on a schedule or event, calls MCP tools (`elemental_get_schema`, `elemental_get_entity`, …), maps results into **Neon** (or another store) with **`psycopg2-binary`** (or your driver). Idempotent **UPSERT**s. Use **`data-model`** skill when designing columns.
+
+**B. Investigation / research / aggregation** — Agent uses MCP tools **during multi-step reasoning**: compare entities, trace relationships, pull events or filings, summarize. Typical outputs: a **final answer**, a **report artifact**, or **partial writes** to a store; a full graph replica is optional. Postgres is optional.
+
+**C. Channel / concierge** — Agent is the **user’s interface** to the graph: user message → agent selects and invokes MCP tools → **natural-language reply** (with optional structured blocks). Often pairs with **`useAgentChat`** in Nuxt; **no local DB** required for the graph if answers are computed on the fly.
+
+You can deploy **multiple agents** with different mixes of A–C.
+
+## Python stack (typical)
+
+- `google-adk` — agent framework
+- MCP client or ADK **McpToolset** — `ELEMENTAL_MCP_URL` or gateway-proxied MCP URL
+- **`psycopg2-binary`** — only when an agent **persists** to `DATABASE_URL`
+
+```bash
+export ELEMENTAL_MCP_URL="https://.../elemental/mcp"   # or gateway URL from provisioning
+# Optional, for sync agents:
+export DATABASE_URL="postgresql://..."
+```
+
+## Tool surface
+
+MCP tools handle schema, entity resolution, related entities, events, sentiment, etc. Use them for **discovery** in research agents and for **batch extraction** in sync agents. Match tool choice to the pattern (A/B/C) in each agent’s `instruction`.
+
+## When HTTP `elemental_client` still appears
+
+**api-mcp** agents often use **`broadchurch_auth`** + REST. In **mcp-only**, prefer **MCP** for graph access unless you have a concrete reason to call REST from Python (e.g. legacy batch job). Do not route **Vue** through REST for the primary architecture — that contradicts mcp-only.
+
+## Instructions template
+
+- **Sync agent:** Instruct: which MCP calls, how rows map to tables, UPSERT behavior, logging, failure handling.
+- **Research agent:** Instruct: hypothesis → tool calls → synthesis; cite NEIDs or entity names; when to stop.
+- **Channel agent:** Instruct: clarify user intent → call tools → answer directly; optional follow-up questions.

package/variants/mcp-only/rules/cookbook-data.mdc

@@ -0,0 +1,50 @@
+---
+description: "MCP-only: UI recipes when data is exposed via your own APIs (often Postgres). Chat-first or agent-only flows may skip these."
+alwaysApply: false
+---
+
+# Data-fetching cookbook (MCP-only)
+
+**Valid UIs for mcp-only include:** (a) **Chat-first** surfaces where the user talks to an agent that calls MCP tools (`useAgentChat`, agent design — see `data` / `agents-data`). (b) **List/detail/table** screens fed by **your** Nitro APIs, often backed by **Postgres** rows populated by agents that used Elemental MCP upstream.
+
+**These recipes** cover (b): tabular or list data through Nitro APIs.
+
+When you build Postgres-backed screens:
+
+Assume composables like `useEntities()` wrap `$fetch('/api/entities')` — adjust paths to match your project.
+
+## 1. Entity list page
+
+```vue
+<template>
+    <div class="d-flex flex-column fill-height pa-4">
+        <h1 class="text-h5 mb-4">Entities</h1>
+        <v-alert v-if="error" type="error" variant="tonal" class="mb-4" closable>{{ error }}</v-alert>
+        <v-data-table :items="items" :loading="loading" />
+    </div>
+</template>
+
+<script setup lang="ts">
+    const { items, loading, error, refresh } = useEntities();
+
+    onMounted(() => refresh());
+</script>
+```
+
+Implement `useEntities()` to call `GET /api/entities` (or paginated variant). The server route runs SQL against **your** tables (populated by agents via MCP), not Elemental REST from this handler.
+
+## 2. Search / filter
+
+Use query params on the same API: `GET /api/entities?q=apple`. Server uses `ILIKE` or a `tsvector` if you add search indexes.
+
+## 3. News or events feed
+
+`GET /api/events?limit=20` returning rows your pipeline populated (agent + MCP → storage). Display from columns — no `useElementalSchema()` in Vue.
+
+## 4. Master-detail with relationships
+
+Foreign keys in Postgres that mirror relationships your agents synced or derived. Detail via `GET /api/entities/:id` and related rows.
+
+## 5. Filings or documents
+
+Metadata in a table keyed by org or symbol; ingestion happened in an agent using MCP — the UI reads your API only.

package/variants/mcp-only/rules/data.mdc

@@ -0,0 +1,55 @@
+---
+description: "MCP-only data mode: no Elemental REST client in Nuxt; Elemental MCP is used by ADK agents — sync, research, or direct channeling."
+alwaysApply: false
+---
+
+# Data — MCP-only (agents + Elemental MCP, not the Elemental API in the SPA)
+
+In **mcp-only** mode the Nuxt app does **not** call the Elemental API via `useElementalClient()` or gateway REST from the browser. **Elemental MCP** is how custom **ADK agents** reach the Lovelace knowledge graph.
+
+**Valid applications include:**
+
+1. **Sync / local store** — Agents call Elemental MCP tools, normalize results, and **persist** into **Neon Postgres** (or another store you own). The **web app reads that store** via Nitro routes and composables. Suited to dashboards, feeds, and CRUD UIs backed by materialized graph data.
+
+2. **Investigation / research / aggregation** — Agents use Elemental MCP tools **inside their reasoning loop** (schema discovery, entity resolution, related entities, events, sentiment) to **investigate**, **research**, or **aggregate** answers. Summaries or structured outputs may go to Postgres, KV, or nowhere persistent — emphasis is on the **agent workflow** and the delivered answer.
+
+3. **Direct channeling** — An agent **channels** Elemental MCP to the user: the user talks to the agent (e.g. via `useAgentChat`), and the agent invokes MCP tools and **responds in natural language** with citations or structured excerpts. **Chat-first** SPAs; Postgres may be absent or limited to prefs/KV.
+
+**Combining patterns:** One project can run a sync job for hot data, a research agent for deep dives, and a channel agent for Q&A.
+
+## What does not exist in this mode (SPA / Nitro conventions)
+
+- Do **not** use `useElementalClient()` from `@yottagraph-app/elemental-api/client` for the **standard data path** of the UI described in api-mcp docs.
+- Do **not** assume `~/utils/elementalHelpers` for **primary** user-facing data fetch in Vue — graph access for agents is via **MCP in Python**, not from Vue calling REST.
+- The **`skills/elemental-api/`** skill directory is not installed for mcp-only projects. Use **`skills/data-model/`** for entity/property/relationship semantics when designing agent instructions, tables, or prompts.
+
+## When the product surfaces data via Postgres
+
+If you **do** use the sync pattern, treat Neon as the **read model** for those pages:
+
+1. **`DATABASE_URL`** — Use `getDb()` from `~/server/utils/neon.ts` in server routes.
+2. **Schema** — `CREATE TABLE IF NOT EXISTS` / `ensureTables()` (see `server` rule). Align columns with the **data-model** skill where relevant.
+3. **Composables** — Thin wrappers around `$fetch('/api/...')` to your own APIs (`useEntities`, etc.).
+4. **Agents that populate tables** — Call Elemental MCP tools, map to rows, **UPSERT** idempotently. Document env (`DATABASE_URL`, MCP URL) in `DESIGN.md` or the agent README.
+
+```text
+Elemental MCP → ADK agent → Postgres ← Nitro ← Vue   (sync / dashboard pattern)
+```
+
+## When the product is agent-first (no Postgres read path)
+
+Chat UI + deployed agents that call MCP tools and return answers **without** mirroring the full graph locally. The **gateway** and **`useAgentChat`** are the integration surface; Postgres may be unused for graph data.
+
+```text
+User → Nuxt chat → Portal Gateway → ADK agent → Elemental MCP tools → answer to user   (channeling / research)
+```
+
+## Local development
+
+- **Postgres-backed UIs:** Without `DATABASE_URL`, `getDb()` returns `null` — empty states or 503; do not fall back to Elemental REST from the client.
+- **Cursor:** Elemental MCP in your **tool list** helps you author and test agent behavior; tenant users still rely on **deployed agents** and MCP configured for the agent runtime, not the Vue bundle.
+
+## Error handling
+
+- Empty tables after deploy are normal until a **sync** agent runs — only applies if you use the Postgres pattern.
+- If Vue code imports Elemental client packages for primary data, you are mixing modes — move graph access to **agents + MCP** or switch data architecture in `DESIGN.md` / provisioning.

package/variants/mcp-only/rules/server-data.mdc

@@ -0,0 +1,41 @@
+---
+description: "MCP-only: Nitro routes that read your own store (often Neon). Not used for proxying Elemental REST to the SPA."
+alwaysApply: false
+globs: server/**
+---
+
+# Server routes: your data store (MCP-only)
+
+In mcp-only mode, **server routes do not** implement the **Elemental REST** proxy pattern from api-mcp for the **primary** SPA data path. Graph access lives in **agents + Elemental MCP**.
+
+This rule applies when your architecture includes a **local read model** (usually **Neon Postgres**) filled by agents that called MCP upstream. **Chat-only** or **agent-only** products may have **few or no** such routes — that is fine.
+
+## Pattern (Postgres-backed lists / detail)
+
+```typescript
+import { getDb } from '~/server/utils/neon';
+
+export default defineEventHandler(async (event) => {
+  const sql = getDb();
+  if (!sql) throw createError({ statusCode: 503, statusMessage: 'Database not configured' });
+
+  const q = getQuery(event).q as string | undefined;
+  if (q) {
+    return await sql`
+      SELECT neid, name, updated_at FROM entities
+      WHERE name ILIKE ${'%' + q + '%'}
+      ORDER BY updated_at DESC LIMIT 50
+    `;
+  }
+  return await sql`SELECT neid, name, updated_at FROM entities ORDER BY updated_at DESC LIMIT 50`;
+});
+```
+
+## `ensureTables`
+
+Call a shared `ensureTables()` before reads if tables might be missing on cold start (see `server` rule).
+
+## Secrets
+
+- **`DATABASE_URL`** — for your app’s relational store when you use one.
+- Do not treat **Nitro** as the place to **call Elemental MCP** for end-user traffic — MCP runs in **agent** runtimes. (Cursor MCP in dev is for authoring.)