@yottagraph-app/aether-instructions 1.1.30 → 1.1.32

package/commands/build_my_app.md

@@ -210,7 +210,7 @@ Implement the plan:
 
 ---
 
-## Step 7: Verify
+## Step 7: Verify and Commit
 
 After building, check dependencies are installed and run a build:
 
@@ -221,27 +221,51 @@ npm run build
 
 Fix any build errors.
 
-Then suggest the user run `npm run dev` to preview their app locally.
+Then format and commit:
+
+```bash
+npm run format
+git add -A
+git commit -m "[Agent commit] Initial app build from project brief"
+```
+
+**Push directly to main.** Vercel auto-deploys on push to main, so this
+gets the app live immediately. Do NOT try to create a pull request via
+`gh pr create` — 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.
 
 ---
 
 ## 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.
+
+**Skip `example_agent`** — this is a template placeholder, not a real
+agent. Only deploy agents you actually built for this project.
 
-> 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.
+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 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.
+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.30",
+    "version": "1.1.32",
     "description": "Cursor rules, commands, and skills for Aether development",
     "files": [
         "rules",

package/rules/agents-data.mdc

@@ -70,3 +70,19 @@ 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.
+
+## Reliability invariants (REST-backed agents)
+
+These constraints reduce failure modes when building graph-aware agents on
+the Query Server API:
+
+- **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 instead of inferring semantics from property/PID names.
+- **Keep IDs internal to tool calls.** Use NEIDs/EIDs internally for precise
+  requests, and render human-readable names in user-facing output.
+- **Dereference linked values before display.** Reference-like property
+  values should be resolved into entity names when shown to users.
+- **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/variants/mcp-only/commands/build_my_app.md

@@ -121,7 +121,7 @@ Match the brief: dashboards from `/api/...`, **chat** as primary, or both. No El
 
 ---
 
-## Step 7: Verify
+## Step 7: Verify and Commit
 
 After building, ensure dependencies are installed and run a production build:
 
@@ -130,7 +130,26 @@ test -d node_modules || npm install
 npm run build
 ```
 
-Fix any build errors. Then suggest the user run `npm run dev` to preview locally.
+Fix any build errors. Then format and commit:
+
+```bash
+npm run format
+git add -A
+git commit -m "[Agent commit] Initial app build from project brief"
+```
+
+**Push directly to main.** Vercel auto-deploys on push to main, so this
+gets the app live immediately. Do NOT try to create a pull request via
+`gh pr create` — 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.
 
 Deploy agents as needed; if the brief relies on **materialized** data, run or schedule the relevant agents before expecting full UI data.
 
@@ -138,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.
+
+**Skip `example_agent`** — this is a template placeholder, not a real
+agent. Only deploy agents you actually built for this project.
 
-> 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.
+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 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`.
+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

@@ -34,6 +34,22 @@ export DATABASE_URL="postgresql://..."
 
 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`.
 
+## 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
 
 **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.