@yottagraph-app/aether-instructions 1.1.21 → 1.1.22

package/package.json

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

package/rules/api.mdc

@@ -28,13 +28,32 @@ For Lovelace **entity types, properties, relationships, and per-source schemas**
 
 ## Test Before You Build
 
-**ALWAYS test API calls via curl before writing code that depends on them.**
-This is not optional — the Elemental API has response shapes that differ from
-what the TypeScript types suggest, and assumptions about nesting, property
-formats, and field names will be wrong without testing. This applies doubly
-to server-side code, where you can't inspect responses in the browser console.
+**ALWAYS test data access before writing application code.** The Elemental
+API has response shapes that differ from what the TypeScript types suggest,
+and assumptions about nesting, property formats, and field names will be
+wrong without testing.
 
-### How to test
+### Step 1: MCP tools (interactive exploration)
+
+**If MCP tools appear in your tool list, start here.** MCP handles entity
+resolution, PID lookups, and NEID formatting automatically — use it to
+verify what data exists and how it's structured.
+
+```
+elemental_get_schema()                          → list all entity types
+elemental_get_schema(flavor="article")          → properties for a type
+elemental_get_entity(entity="Apple")            → resolve + fetch entity
+elemental_get_related(entity="Apple",
+    related_flavor="person")                    → follow relationships
+```
+
+MCP tells you the correct flavor IDs, property IDs, and data shapes. Use
+these to inform your REST implementation.
+
+### Step 2: curl (verify exact request/response shapes)
+
+MCP doesn't cover every REST endpoint (e.g. `/elemental/find` expressions).
+Test those with curl before implementing them in code.
 
 The gateway proxy authenticates on your behalf — no Auth0 tokens needed.
 Read `broadchurch.yaml` for the three values you need:
@@ -48,8 +67,6 @@ Read `broadchurch.yaml` for the three values you need:
 Build the request URL as `{gateway.url}/api/qs/{tenant.org_id}/{endpoint}`
 and include the header `X-Api-Key: {gateway.qs_api_key}`.
 
-### Example calls
-
 ```bash
 # Variables — read these from broadchurch.yaml
 GW="https://broadchurch-portal-194773164895.us-central1.run.app"
@@ -62,6 +79,13 @@ curl -s "$GW/api/qs/$ORG/entities/search" \
   -H "X-Api-Key: $KEY" \
   -d '{"queries":[{"queryId":1,"query":"Microsoft"}],"maxResults":3}'
 
+# Test a find expression
+curl -s -X POST "$GW/api/qs/$ORG/elemental/find" \
+  -H "X-Api-Key: $KEY" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  --data-urlencode 'expression={"type":"is_type","is_type":{"fid":12}}' \
+  --data-urlencode 'limit=5'
+
 # Get entity properties (form-encoded)
 curl -s -X POST "$GW/api/qs/$ORG/elemental/entities/properties" \
   -H "X-Api-Key: $KEY" \
@@ -74,6 +98,14 @@ curl -s -X POST "$GW/api/qs/$ORG/elemental/entities/properties" \
 `application/x-www-form-urlencoded` with JSON-stringified parameter values.
 All other endpoints accept `application/json`.
 
+**Interpreting errors:** 400 = expression syntax is wrong. 500 = expression
+is valid but the query failed (wrong PID, unsupported operator for that
+property type). 200 + empty `eids` = query worked but no results match.
+
+### Step 3: Implement with confidence
+
+Now write your composable or server route, knowing the exact API shapes.
+
 ## Client Usage
 
 All API calls go through `useElementalClient()` from `@yottagraph-app/elemental-api/client`.
@@ -163,26 +195,46 @@ knowledge of what's in the graph.
 
 ## API Gotchas
 
-### `getSchema()` response is nested — WILL crash if you don't handle it
+### `getSchema()` response structure differs by endpoint
 
-The generated TypeScript types suggest `response.properties` and
-`response.flavors` exist at the top level. **They don't.** The API nests
-them under `response.schema`. This mismatch between types and reality
-causes `Cannot read properties of undefined` every time.
+There are two schema endpoints with **different response shapes**:
+
+| Endpoint | Flavors at | Flavor ID field | Detail level |
+|----------|-----------|-----------------|--------------|
+| `GET /schema` | top-level (`res.flavors`) | `findex` | Rich (display names, units, domains) |
+| `GET /elemental/metadata/schema` | nested (`res.schema.flavors`) | `fid` | Basic (name + type only) |
+
+The TypeScript client's `getSchema()` calls `/elemental/metadata/schema`,
+so the response nests data under `.schema`. The generated types may suggest
+top-level access, but it won't work at runtime.
 
 ```typescript
-// WRONG — will crash at runtime despite TypeScript compiling fine:
+// WRONG — will crash (data is nested under .schema):
 const res = await client.getSchema();
 const props = res.properties; // undefined!
 
-// CORRECT — always access through .schema:
+// CORRECT — always use fallback to handle both shapes:
 const res = await client.getSchema();
 const properties = res.schema?.properties ?? (res as any).properties ?? [];
 const flavors = res.schema?.flavors ?? (res as any).flavors ?? [];
 ```
 
-The `(res as any).properties` fallback is there in case the API is ever
-fixed to match the types. Use this pattern every time.
+### Flavor ID field: `fid` vs `findex`
+
+The flavor identifier has **different field names** depending on the endpoint:
+`GET /schema` returns `findex`, `/elemental/metadata/schema` returns `fid`.
+Same value, different key. Always use a fallback:
+
+```typescript
+const articleFlavor = flavors.find(f => f.name === 'article');
+const articleFid = articleFlavor?.fid ?? articleFlavor?.findex ?? null;
+
+// When building a FID lookup map:
+const fidMap = new Map(flavors.map(f => [f.fid ?? f.findex, f.name]));
+```
+
+The `is_type` expression in `/elemental/find` always uses the `fid` key
+regardless of which schema endpoint provided the value.
 
 ### Relationship property values need zero-padding to form valid NEIDs
 
@@ -273,6 +325,23 @@ const docNeids = (res.values ?? []).map((v) => String(v.value).padStart(20, '0')
 
 See the **cookbook** rule for a full "Get filings for a company" recipe.
 
+### Expression language pitfalls
+
+These mistakes come up repeatedly when building `/elemental/find` queries:
+
+- **Entity type filtering**: Use `is_type` (not `comparison` with pid=0).
+  `comparison` requires `pid != 0`.
+- **`string_like` is name-only**: Only works on the name property (PID 8).
+  Use `eq` for exact matches on other string properties.
+- **Boolean combinators**: Use `{"type": "and", "and": [...]}` — not
+  `conjunction` or any other name.
+- **`lt`/`gt` are numeric-only**: Only work on `data_int` and `data_float`
+  properties.
+- **`regex` is not implemented**: Will return an error.
+
+Read the "Common Mistakes" section in the **elemental-api skill** (`find.md`)
+for examples of each.
+
 ### Entity Search
 
 Use `client.findEntities()` (`POST /elemental/find`) for entity search.
@@ -327,17 +396,13 @@ const response = await getArticle(artid);
 if (response.status === 404) { /* handle not found */ }
 ```
 
-## Lovelace MCP Servers (Optional)
-
-Four MCP servers **may** be configured in `.cursor/mcp.json` for interactive
-data exploration. They are NOT required — the REST client
-(`useElementalClient()`) and skill docs cover the same data and are the
-primary path for building features.
+## Lovelace MCP Servers
 
-**Before referencing MCP tools, check your available tool list.** If tools
-like `elemental_get_schema` don't appear in your MCP server list, the
-servers aren't connected — just use the REST client and skill docs instead.
-Do not report this as a problem; it's a normal configuration state.
+Four MCP servers may be configured in `.cursor/mcp.json` for interactive
+data exploration. **Check your tool list** — if tools like
+`elemental_get_schema` appear, use them as your primary testing and
+exploration interface before writing code. If they don't appear, the
+servers aren't connected; use curl and the skill docs instead.
 
 | Server | What it provides |
 |---|---|
@@ -346,6 +411,23 @@ Do not report this as a problem; it's a normal configuration state.
 | `lovelace-wiki` | Wikipedia entity enrichment |
 | `lovelace-polymarket` | Prediction market data |
 
+### MCP Tool Quick Reference
+
+| Tool | Purpose | Use to verify... |
+|---|---|---|
+| `elemental_get_schema` | Discover entity types (flavors), properties, and relationships | Flavor IDs, property IDs, data types |
+| `elemental_get_entity` | Look up entity by name or NEID; returns properties | Entity resolution, property shapes |
+| `elemental_get_related` | Related entities with type/relationship filters | Relationship types and traversal |
+| `elemental_get_relationships` | Relationship types and counts between two entities | Edge types between specific entities |
+| `elemental_graph_neighborhood` | Most influential neighbors of an entity | Graph connectivity |
+| `elemental_graph_sentiment` | Sentiment analysis from news articles | Sentiment data availability |
+| `elemental_get_events` | Events for an entity or by search query | Event categories and shapes |
+| `elemental_health` | Health check | Server connectivity |
+
+MCP tools handle entity resolution, PID lookups, and NEID formatting
+automatically. Use them to discover IDs and verify data exists before
+building REST-based features with `useElementalClient()`.
+
 ### Setup
 
 `.cursor/mcp.json` is auto-generated by `init-project.js`. If it's missing,
@@ -353,25 +435,3 @@ run `node init-project.js --local` to regenerate it. For provisioned projects,
 the servers route through the Portal Gateway proxy (no credentials needed).
 For local development without a gateway, the servers require an
 `AUTH0_M2M_DEV_TOKEN` environment variable.
-
-These servers are also accessible from the browser through the Portal
-Gateway, so you can build MCP tool exploration UIs if needed.
-
-### When MCP Servers Are Available
-
-If the MCP tools appear in your tool list, you can use them for interactive
-exploration alongside the REST client:
-
-| Tool | Purpose |
-|---|---|
-| `elemental_get_schema` | Discover entity types (flavors), properties, and relationships |
-| `elemental_get_entity` | Look up entity by name or NEID; returns properties |
-| `elemental_get_related` | Related entities with type/relationship filters |
-| `elemental_get_relationships` | Relationship types and counts between two entities |
-| `elemental_graph_neighborhood` | Most influential neighbors of an entity |
-| `elemental_graph_sentiment` | Sentiment analysis from news articles |
-| `elemental_get_events` | Events for an entity or by search query |
-| `elemental_health` | Health check |
-
-MCP is convenient for schema discovery and entity resolution during planning.
-For building UI features, always use the REST client (`useElementalClient()`).