@yottagraph-app/aether-instructions 1.1.35 → 1.1.37

package/package.json

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

package/rules/agents.mdc

@@ -455,3 +455,29 @@ exploration but requires more tool calls and is more error-prone.
 returns formatted strings. Fewer tools, more reliable, better for production
 use cases. **Prefer this pattern** unless the agent genuinely needs to
 explore arbitrary entity types.
+
+### McpToolset passthrough is not a substitute for custom tools
+
+When DESIGN.md specifies named agent tools (e.g. `entity_search`,
+`corporate_structure`, `event_monitor`), each must be implemented as a
+**Python function** that calls MCP, formats results, and handles errors.
+Passing a raw `McpToolset` as the agent's only tool source and writing a
+long system prompt does **not** satisfy the spec.
+
+`McpToolset` passthrough means:
+- The LLM receives raw JSON responses — no Markdown formatting, no
+  human-readable reports
+- No session-state caching — repeated queries for the same entity make
+  redundant MCP calls every turn
+- No property type handling — `data_nindex` values (entity references)
+  render as meaningless 19-digit numbers
+- No error boundaries — MCP failures surface as opaque tool errors
+- No compound cache keys or report generation — the patterns that make
+  multi-turn research conversations reliable
+
+`McpToolset` passthrough is fine for **simple exploration agents** or
+quick prototypes. It is **not acceptable** when the project spec
+describes a production agent with a defined tool suite. If DESIGN.md
+lists N custom tools, build N custom Python functions — each calling MCP
+tools internally, formatting output as Markdown, catching exceptions,
+and saving reports to session state where appropriate.

package/rules/cookbook-data.mdc

@@ -403,3 +403,148 @@ relationship PID. See the `data` rule for the two-layer architecture.
     }
 </script>
 ```
+
+## 5. Async Entity Search with Live Suggestions
+
+Type-ahead search that shows results in a dropdown as the user types. Uses
+`searchEntities()` from the gateway helpers with a debounced watcher.
+
+> **Do not use `v-autocomplete` for async search.** Vuetify's `v-autocomplete`
+> with `hide-no-data` + `no-filter` + async item loading has a timing bug:
+> the menu hides while items are empty (during the fetch) and does not reopen
+> when results arrive. Use `v-text-field` with a manual dropdown instead.
+
+```vue
+<template>
+    <div class="entity-search" style="position: relative">
+        <v-text-field
+            v-model="searchQuery"
+            :label="label"
+            :prepend-inner-icon="icon"
+            variant="solo-filled"
+            rounded="lg"
+            clearable
+            density="comfortable"
+            :loading="searching"
+            @focus="showMenu = suggestions.length > 0"
+            @click:clear="onClear"
+        />
+
+        <v-card
+            v-if="showMenu && suggestions.length > 0"
+            class="search-dropdown"
+            elevation="8"
+        >
+            <v-list density="compact">
+                <v-list-item
+                    v-for="item in suggestions"
+                    :key="item.neid"
+                    :title="item.name"
+                    :subtitle="item.neid"
+                    @click="onSelect(item)"
+                />
+            </v-list>
+        </v-card>
+    </div>
+</template>
+
+<script setup lang="ts">
+    import { searchEntities } from '~/utils/elementalHelpers';
+
+    const props = withDefaults(
+        defineProps<{
+            label?: string;
+            icon?: string;
+            flavors?: string[];
+        }>(),
+        { label: 'Search', icon: 'mdi-magnify', flavors: undefined },
+    );
+
+    const emit = defineEmits<{
+        selected: [entity: { neid: string; name: string }];
+    }>();
+
+    const searchQuery = ref('');
+    const suggestions = ref<{ neid: string; name: string }[]>([]);
+    const searching = ref(false);
+    const showMenu = ref(false);
+    let selectedName = '';
+    let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+
+    watch(searchQuery, (val) => {
+        if (debounceTimer) clearTimeout(debounceTimer);
+        if (val === selectedName) return;
+        if (!val || val.length < 2) {
+            suggestions.value = [];
+            showMenu.value = false;
+            return;
+        }
+        debounceTimer = setTimeout(() => doSearch(val), 300);
+    });
+
+    async function doSearch(query: string) {
+        searching.value = true;
+        try {
+            suggestions.value = await searchEntities(query, {
+                maxResults: 8,
+                flavors: props.flavors,
+            });
+            showMenu.value = suggestions.value.length > 0;
+        } catch {
+            suggestions.value = [];
+            showMenu.value = false;
+        } finally {
+            searching.value = false;
+        }
+    }
+
+    function onSelect(item: { neid: string; name: string }) {
+        selectedName = item.name;
+        searchQuery.value = item.name;
+        suggestions.value = [];
+        showMenu.value = false;
+        emit('selected', item);
+    }
+
+    function onClear() {
+        selectedName = '';
+        suggestions.value = [];
+        showMenu.value = false;
+    }
+
+    onMounted(() => {
+        document.addEventListener('click', (e) => {
+            const el = (e.target as HTMLElement)?.closest('.entity-search');
+            if (!el) showMenu.value = false;
+        });
+    });
+</script>
+
+<style scoped>
+    .entity-search {
+        max-width: 600px;
+    }
+
+    .search-dropdown {
+        position: absolute;
+        top: 100%;
+        left: 0;
+        right: 0;
+        z-index: 100;
+        max-height: 300px;
+        overflow-y: auto;
+        margin-top: -8px;
+    }
+</style>
+```
+
+Usage:
+
+```vue
+<EntitySearch
+    label="Search for a company"
+    icon="mdi-domain"
+    :flavors="['organization']"
+    @selected="onCompanySelected"
+/>
+```

package/skills/elemental-mcp-patterns/SKILL.md

@@ -604,6 +604,17 @@ These are mistakes previous agents have made. Do not repeat them.
    when the `ref` field is actually present in the tool response data.
    The client renders these as numbered citations with source links.
 
+6. **Do not pass raw `McpToolset` when the spec calls for custom tools.**
+   If DESIGN.md describes named tools (e.g. `entity_search`,
+   `corporate_structure`, `event_monitor`), each must be a Python
+   function that calls MCP internally. Passing `McpToolset` as the
+   agent's only tool source means: no Markdown report formatting, no
+   session-state caching, no property type resolution (`data_nindex`
+   values render as raw NEIDs), no compound cache keys, and no error
+   boundaries. The LLM gets raw JSON and hallucinates when responses
+   are large. `McpToolset` passthrough is acceptable for quick
+   prototypes but not for production agents with a defined tool suite.
+
 ---
 
 ## Citation Handling

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

@@ -114,6 +114,18 @@ Match the brief: dashboards from `/api/...`, **chat** as primary, or both. No El
 
 ## Step 6: Build
 
+**If the brief is agent-heavy** (the agent IS the product — chatbot,
+research assistant, investigation tool, etc.), build the agent FIRST:
+
+1. **`agents/`** — Build the full agent with all tools specified in DESIGN.md.
+   Each named tool must be a Python function — do NOT just pass `McpToolset`
+   through and write a system prompt. Read the `agents` rule ("McpToolset
+   passthrough" section) for why this matters.
+2. Test the agent locally with `adk web` before building the UI.
+3. Then build the UI around the working agent.
+
+**For all projects:**
+
 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.
@@ -121,6 +133,26 @@ Match the brief: dashboards from `/api/...`, **chat** as primary, or both. No El
 
 ---
 
+## Step 6b: Audit Against the Spec
+
+Before committing, re-read DESIGN.md and compare what you built against
+what it specifies. This is a mechanical check — no judgment needed.
+
+1. **List every agent tool** DESIGN.md describes (by name, with purpose).
+2. For each, confirm it exists in your code with the described behavior.
+3. If the spec describes N custom tools and you built fewer, **go back
+   and build the missing ones** before proceeding.
+4. If you used `McpToolset` passthrough where the spec calls for custom
+   Python tool functions, **replace it** — passthrough does not satisfy a
+   spec that describes named tools with specific behaviors.
+5. Check that tools format output as Markdown, handle errors, and cache
+   results in session state where the spec requires it.
+
+Do not skip this step. The most common failure mode is building a polished
+UI connected to a stub agent that passes raw MCP tools through to the LLM.
+
+---
+
 ## Step 7: Verify and Commit
 
 After building, ensure dependencies are installed and run a production build: