@yottagraph-app/aether-instructions 1.1.32 → 1.1.33

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@yottagraph-app/aether-instructions",
-    "version": "1.1.32",
+    "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

@@ -71,18 +71,45 @@ In production, all Elemental API calls go through the Portal Gateway at
 `broadchurch.yaml`) and the portal injects its own Auth0 M2M token
 upstream.
 
-## Reliability invariants (REST-backed agents)
+## MCP-based agents
 
-These constraints reduce failure modes when building graph-aware agents on
-the Query Server API:
+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 instead of inferring semantics from property/PID names.
+  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.
-- **Dereference linked values before display.** Reference-like property
-  values should be resolved into entity names when shown to users.
+  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/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/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,9 @@ 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)