@yottagraph-app/aether-instructions 1.1.31 → 1.1.33

package/commands/build_my_app.md

@@ -246,21 +246,26 @@ workflow — ask before pushing directly to main in that case.
 
 ## Step 8: Deploy Agents and Next Steps
 
-If the app includes agents in `agents/`, offer to deploy them now:
+If the app includes agents in `agents/`, **deploy them automatically** —
+don't ask for confirmation. Run `/deploy_agent` for each agent immediately
+after pushing. The brief asked you to build an app with agents; deploying
+them is part of delivering a working app.
 
-> Your app is built! I see you have an agent in `agents/`. Want me to
-> deploy it now? I can run the deployment for you.
+**Skip `example_agent`** — this is a template placeholder, not a real
+agent. Only deploy agents you actually built for this project.
 
-If the user agrees (or if this is an automated build), run `/deploy_agent`
-to deploy each agent. Don't just tell the user to type the command — do it
-for them.
+After triggering deployment, monitor it yourself (see `/deploy_agent`
+Step 6 for how to poll). Only escalate to the user if deployment fails
+and you can't resolve it.
+
+If DESIGN.md explicitly says NOT to deploy, or says to wait for user
+confirmation, respect that. Otherwise, deploy without asking.
 
 Then present next steps:
 
 > Here's what you can do next:
 >
-> - **Preview locally** with `npm run dev`
-> - **Push to deploy** -- Vercel auto-deploys on push to main
-> - **Deploy agents** -- I can deploy them for you, or use the Deploy
->   button on the Broadchurch portal's project page
-> - **Deploy MCP servers** -- same as above, from the portal or ask me
+> - **Preview the app** — Vercel auto-deployed on push to main
+> - **Agents are deploying** — I triggered deployment; it typically
+>   takes 2-5 minutes. I'll let you know when they're registered.
+> - **MCP servers** — deploy from the Broadchurch portal or ask me

package/commands/deploy_agent.md

@@ -4,7 +4,7 @@ Deploy an ADK agent from the `agents/` directory to Vertex AI Agent Engine via t
 
 ## 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.
+This command deploys a Python ADK agent by triggering a Cloud Build job through the Portal API. No local GCP credentials are needed — Cloud Build authenticates via the project's service account.
 
 The agent must live in `agents/<name>/` with the standard ADK structure (`agent.py`, `__init__.py`, `requirements.txt`).
 
@@ -56,9 +56,13 @@ ls -d agents/*/
 
 Stop here.
 
-**If multiple agents exist:** Ask the user which one to deploy.
+**Skip `example_agent`** — this is a template placeholder and should
+never be deployed. Filter it out before proceeding.
 
-**If only one agent exists:** Confirm with the user.
+**If multiple agents remain:** Deploy all of them. If called interactively
+(not from `/build_my_app`), ask the user which one to deploy.
+
+**If only one agent remains:** Proceed with it — no confirmation needed.
 
 **Important:** Agent directory names must use underscores, not hyphens (e.g., `my_agent` not `my-agent`).
 
@@ -110,35 +114,88 @@ curl -sf -X POST "<GATEWAY_URL>/api/projects/<ORG_ID>/deploy" \
 
 **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.
+**If this succeeds:** The response will look like:
+
+```json
+{
+  "ok": true,
+  "method": "cloud-build",
+  "build_id": "...",
+  "log_url": "https://console.cloud.google.com/cloud-build/builds/...",
+  "target": "agents/<name>",
+  "repo": "<owner>/<repo>"
+}
+```
+
+Save the `build_id` — you'll need it for monitoring.
 
 ---
 
-## Step 6: Monitor Progress
+## Step 6: Monitor Progress and Confirm Registration
 
-> 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.
+Deployment uses Cloud Build and typically takes 2-5 minutes. Monitor it
+yourself rather than asking the user to check.
+
+### 6a. Poll build status
+
+Use the deploy-status endpoint to check whether the build has finished:
+
+```bash
+curl -sf "<GATEWAY_URL>/api/projects/<ORG_ID>/deploy-status" | jq '.cloud_builds[]'
+```
+
+Each build entry has a `status` field. Terminal statuses are: `SUCCESS`,
+`FAILURE`, `CANCELLED`, `TIMEOUT`, `INTERNAL_ERROR`, `EXPIRED`.
+
+Poll every 30 seconds until the build reaches a terminal status (up to
+5 minutes). If it's still running after 5 minutes, tell the user and
+share the `log_url` from the deploy response.
+
+### 6b. Confirm agent registration
+
+A successful build doesn't guarantee the agent is usable yet — it also
+needs to be registered with the tenant config. Poll the config endpoint
+until the agent appears:
+
+```bash
+curl -sf "<GATEWAY_URL>/api/config/<ORG_ID>" | jq '.agents'
+```
+
+Check that the `agents` array contains an entry whose name matches your
+agent. Poll every 30 seconds for up to 3 minutes after the build
+succeeds.
+
+### 6c. Report result
+
+**If the agent appears in config:**
+
+> Agent `<name>` is deployed and registered. It should now be available
+> in the app's chat interface.
+
+**If the build succeeded but the agent doesn't appear in config after
+3 minutes:**
+
+> The Cloud Build job succeeded, but the agent hasn't appeared in the
+> tenant config yet. This may indicate the registration step failed
+> silently. Check the build logs: <log_url>
+
+**If the build failed:**
+
+> Agent deployment failed with status `<status>`. Check the build logs
+> for details: <log_url>
 
 ---
 
 ## Troubleshooting
 
-### Deployment workflow fails
+### Cloud Build fails
 
-Check the GitHub Actions logs for the `Deploy Agent` workflow. Common issues:
+Check the build logs at the `log_url` returned by the deploy endpoint.
+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`).
+- **Service account permissions**: The Broadchurch admin may need to verify the project's service account has the required IAM roles.
 
 ### Agent directory naming
 

package/package.json

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

package/rules/aether.mdc

@@ -8,13 +8,13 @@ alwaysApply: true
 
 **Structure:** `pages/` (file-based routing), `components/`, `composables/`, `server/api/`, `agents/` (Python ADK), `mcp-servers/` (Python FastMCP).
 
-**Data:** This app runs on the Lovelace platform -- entities, news, filings, sentiment, relationships, events. See the `data` rule for access patterns and gotchas. Skill docs: `skills/data-model/` (entity types, properties, relationships; `SKILL.md` first). Do NOT call external APIs for data the platform provides.
+**Data:** This app runs on the Lovelace platform -- entities, news, filings, sentiment, relationships, events. See the `data` rule for access patterns and gotchas. Skill docs: `skills/data-model/` (entity types, properties, relationships; `SKILL.md` first), `skills/elemental-mcp-patterns/` (MCP response shapes, property type handling, Python patterns for agent tools). Do NOT call external APIs for data the platform provides.
 
 **Storage:** KV (Upstash Redis) for preferences and lightweight state via `Pref<T>` from `usePrefsStore()`. Neon Postgres for relational data if connected (check `.env` for `DATABASE_URL`).
 
 **Source of truth:** `DESIGN.md` -- read before starting work, update when changing features. The starter UI is placeholder -- replace freely. Feature docs in `design/` for implementation planning.
 
-**Git:** Commit meaningful units of work. Run `npm run format` before commit. Message format: `[Agent commit] {summary}`.
+**Git:** Commit meaningful units of work. Run `npm run format` before commit. Message format: `[Agent commit] {summary}`. Push directly to main — do NOT create PRs or feature branches.
 
 **First action for a new project:** Run `/build_my_app`.
 

package/rules/agents-data.mdc

@@ -70,3 +70,46 @@ In production, all Elemental API calls go through the Portal Gateway at
 `{gateway_url}/api/qs/{org_id}/...`. The agent sends `X-Api-Key` (from
 `broadchurch.yaml`) and the portal injects its own Auth0 M2M token
 upstream.
+
+## MCP-based agents
+
+When the project uses **MCP-only data architecture**, agents access the
+knowledge graph through Elemental MCP tools instead of REST. The MCP tools
+(`elemental_get_entity`, `elemental_get_related`, `elemental_get_events`,
+etc.) handle entity resolution, NEID formatting, and schema lookups
+automatically. Use the `data-model` skill docs for entity types,
+properties, and relationship schemas.
+
+Wire MCP into ADK agents by declaring an `McpToolset` that points to the
+Elemental MCP server. The MCP server URL and auth are configured in the
+agent's runtime environment (typically via `broadchurch.yaml` gateway
+proxy). See the Aether `agents` rule for ADK agent structure.
+
+**Read the `elemental-mcp-patterns` skill** (`skills/elemental-mcp-patterns/`)
+before writing tool code. It covers MCP response shapes, property type
+handling (the `data_nindex` problem), and copy-paste Python patterns for
+entity resolution, property formatting, events, and relationships.
+
+## Reliability invariants
+
+These constraints reduce failure modes when building graph-aware agents,
+whether using REST or MCP:
+
+- **Resolve entities first.** For named-entity questions, do explicit entity
+  resolution before deeper property/relationship/event retrieval.
+- **Prefer domain endpoints over heuristic matching.** Use dedicated event or
+  relationship APIs (`elemental_get_events`, event endpoints) instead of
+  inferring semantics from property/PID names. Substring-matching PID names
+  for words like "event" or "filing" returns wrong results — PIDs like
+  "filed" are document relationship IDs, not event timestamps.
+- **Keep IDs internal to tool calls.** Use NEIDs/EIDs internally for precise
+  requests, and render human-readable names in user-facing output. Never
+  show raw NEIDs to users.
+- **Handle reference-typed properties (`data_nindex`).** Some property
+  values are entity references (NEIDs), not display text. Use
+  `elemental_get_schema` or the data-model skill to check a property's
+  type. For `data_nindex` properties (e.g. "country" on an organization),
+  resolve the NEID to a display name before rendering. A helper like
+  `_pid_types()` that maps PIDs to their schema type is very useful.
+- **Treat 404 as not-found data by default.** Validate server health
+  separately before classifying these as connectivity failures.

package/rules/agents.mdc

@@ -316,6 +316,24 @@ LLMs are better at parsing prose than nested JSON. The difference between
 a tool that works reliably and one that confuses the agent often comes down
 to how the tool formats its output. Follow these principles:
 
+### Runtime invariants for data-heavy agents
+
+These are generic constraints that improve reliability across graph-backed
+agents (MCP or REST-backed):
+
+- **Resolve entities before domain fan-out.** For user prompts about named
+  entities, do explicit entity resolution first, then run domain-specific
+  retrieval (events, filings, relationships, sanctions, etc.).
+- **Use internal IDs only for precision.** Keep stable IDs (NEID/EID/etc.)
+  in tool calls and state, but do not expose raw internal IDs in
+  user-facing prose unless the user explicitly asks for them.
+- **Prefer canonical APIs over heuristic parsing.** For domain concepts
+  like events, use the dedicated API/tool and its typed fields; do not infer
+  semantics from property name substring matching.
+- **Separate gather from synthesize.** Retrieval tools should gather and
+  format reliable intermediate outputs; the final user answer should be
+  composed after all relevant tool outputs are available.
+
 ### Return formatted strings, not raw JSON
 
 This applies to ADK agent tools, where the LLM reads tool output directly.

package/rules/data.mdc

@@ -249,6 +249,20 @@ types or property names. Instead, discover them at runtime:
 This pattern lets agents work with any dataset without needing hardcoded
 knowledge of what's in the graph.
 
+## Semantics-First Data Handling
+
+For reliable agent behavior, prefer typed semantics over string heuristics:
+
+- **Use canonical endpoints/tools for each domain.** Example: fetch events
+  from event APIs (`elemental_get_events` / event endpoints), not by scanning
+  unrelated property names for words like "event" or "filing".
+- **Treat reference-typed properties as links, not display text.** For
+  relationship/reference values (`data_nindex` and similar), resolve linked
+  entities before presenting user-facing output.
+- **Interpret 404s as data absence first.** A 404 on entity/property lookups
+  usually means "not found in current data," not transport failure. Validate
+  connectivity separately (for example, with health endpoints).
+
 ## API Gotchas
 
 ### `getSchema()` response structure differs by endpoint

package/rules/git-support.mdc

@@ -43,6 +43,19 @@ Do **not** run Prettier directly — always use `npm run format`. After formatti
 
 If a user asks about this error, explain the `npm run format` requirement.
 
-## Post-Feature: Encourage Push
+## Pushing
 
-After a feature is fully implemented and committed, use `AskQuestion` to encourage the user to push their branch.
+**Push directly to main.** Vercel auto-deploys on push to main, so this
+gets the app live immediately.
+
+**Do NOT create pull requests** — do not run `gh pr create` or create
+feature branches. In Cursor Cloud environments, the GitHub integration
+token lacks PR permissions (known Cursor issue). Pushing to main is the
+correct workflow.
+
+```bash
+git push origin main
+```
+
+If running locally (not in Cursor Cloud), the user may prefer a PR-based
+workflow — ask before pushing directly to main in that case.

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

@@ -157,21 +157,26 @@ Deploy agents as needed; if the brief relies on **materialized** data, run or sc
 
 ## Step 8: Deploy Agents and Next Steps
 
-If the app includes agents in `agents/`, offer to deploy them now:
+If the app includes agents in `agents/`, **deploy them automatically** —
+don't ask for confirmation. Run `/deploy_agent` for each agent immediately
+after pushing. The brief asked you to build an app with agents; deploying
+them is part of delivering a working app.
 
-> Your app is built! I see you have an agent in `agents/`. Want me to
-> deploy it now? I can run the deployment for you.
+**Skip `example_agent`** — this is a template placeholder, not a real
+agent. Only deploy agents you actually built for this project.
 
-If the user agrees (or if this is an automated build), run `/deploy_agent`
-to deploy each agent. Don't just tell the user to type the command — do it
-for them. Ensure MCP is configured for the agent runtime per `agents-data`.
+After triggering deployment, monitor it yourself (see `/deploy_agent`
+Step 6 for how to poll). Only escalate to the user if deployment fails
+and you can't resolve it.
+
+If DESIGN.md explicitly says NOT to deploy, or says to wait for user
+confirmation, respect that. Otherwise, deploy without asking.
 
 Then present next steps:
 
 > Here's what you can do next:
 >
-> - **Preview locally** with `npm run dev`
-> - **Push to deploy** — Vercel auto-deploys on push to main
-> - **Deploy agents** — I can deploy them for you, or use the Deploy
->   button on the Broadchurch portal's project page
-> - **MCP servers** — same as above, from the portal or ask me
+> - **Preview the app** — Vercel auto-deployed on push to main
+> - **Agents are deploying** — I triggered deployment; it typically
+>   takes 2-5 minutes. I'll let you know when they're registered.
+> - **MCP servers** — deploy from the Broadchurch portal or ask me

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

@@ -14,7 +14,7 @@ In **mcp-only** mode, **Elemental MCP** is the primary way agents reach the know
 
 **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.
+**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.
 
@@ -32,7 +32,25 @@ 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`.
+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`.
+
+**Read the `elemental-mcp-patterns` skill** (`skills/elemental-mcp-patterns/SKILL.md`) before writing tool code. It covers MCP response shapes, property type handling (the `data_nindex` problem), and copy-paste Python patterns for entity resolution, property formatting, events, and relationships.
+
+## Reliability invariants (MCP agents)
+
+For MCP-first agents, enforce these runtime rules:
+
+- **Resolve first, then fan out.** Start with explicit entity resolution
+  before domain-specific calls (events, filings, relationships, sanctions).
+- **Use canonical MCP tools for domain data.** Prefer dedicated tools such as
+  `elemental_get_events` for events; avoid deriving domain semantics from
+  PID/property-name substring matching.
+- **Use IDs internally, names externally.** Pass NEIDs/entity IDs to tools
+  for precision, but present user-facing output using resolved names.
+- **Dereference linked values before display.** If a returned property value
+  points to another entity, resolve it to a display name in final output.
+- **Gather, then synthesize.** Let tools gather structured evidence first;
+  produce final narrative only after retrieval steps complete.
 
 ## When HTTP `elemental_client` still appears