@yottagraph-app/aether-instructions 1.1.20 → 1.1.21

package/package.json

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

package/rules/api.mdc

@@ -85,19 +85,12 @@ import { useElementalClient } from '@yottagraph-app/elemental-api/client';
 const client = useElementalClient();
 
 const schema = await client.getSchema();
-const report = await client.getNamedEntityReport('00508379502570440213');
 const entities = await client.findEntities({
     expression: JSON.stringify({ type: 'comparison', comparison: { operator: 'string_like', pid: 8, value: 'Apple' } }),
     limit: 5,
 });
 ```
 
-Types are also imported from the client:
-
-```typescript
-import type { NamedEntityReport } from '@yottagraph-app/elemental-api/client';
-```
-
 ### Client Method Quick Reference
 
 All methods return data directly and throw on non-2xx responses.
@@ -107,14 +100,17 @@ All methods return data directly and throw on non-2xx responses.
 | Method | Signature | Purpose |
 |---|---|---|
 | `findEntities` | `(body: FindEntitiesBody)` | Expression-based search (see `find.md`) |
-| `getNamedEntityReport` | `(neid: string)` | Entity details (name, aliases, type) |
-| `getEntityDetails` | `(neid: string)` | Alias for entity reports |
 
 > **Entity search**: Use `findEntities()` with `string_like` on the name PID
 > for name-based searches, or call `POST /entities/search` directly via
 > `$fetch` for batch name resolution with scored ranking (this endpoint is
 > not wrapped by the generated client).
 
+> **Entity name lookup**: To get an entity's display name from its NEID,
+> call `GET /entities/{neid}/name` directly via `$fetch` (not on the
+> generated client). Returns `{"name": "..."}`. For all other entity
+> data, use `getPropertyValues()`.
+
 **Properties and schema:**
 
 | Method | Signature | Purpose |
@@ -188,35 +184,13 @@ 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.
 
-### `getNamedEntityReport()` response is nested under `.report`
-
-Same problem as `getSchema()`. The TypeScript types suggest entity fields
-(`name`, `aliases`, `type`) exist at the top level. **They don't.** The
-API wraps them in a `.report` container. The generated client does NOT
-unwrap this automatically.
-
-```typescript
-// WRONG — name will be undefined:
-const res = await client.getNamedEntityReport(neid);
-const name = res.name; // undefined!
-
-// CORRECT — always access through .report:
-const res = await client.getNamedEntityReport(neid);
-const name = res.report?.name ?? (res as any).name ?? neid;
-const aliases = res.report?.aliases ?? (res as any).aliases ?? [];
-const type = res.report?.type ?? (res as any).type;
-```
-
-The `(res as any).name` fallback handles the case where the client is
-eventually fixed to unwrap the response.
-
 ### Relationship property values need zero-padding to form valid NEIDs
 
 Relationship properties (`data_nindex`) return linked entity IDs as raw
 numbers (e.g. `4926132345040704022`). These must be **zero-padded to 20
 characters** to form valid NEIDs. This is easy to miss and causes silent
-failures — `getNamedEntityReport` returns a 404, `getPropertyValues`
-returns empty results.
+failures — `getPropertyValues` returns empty results and
+`/entities/{neid}/name` returns a 404.
 
 ```typescript
 // WRONG — raw value is NOT a valid NEID:

package/rules/cookbook.mdc

@@ -501,11 +501,21 @@ relationship PID. See the `api` rule for the two-layer architecture.
                 String(v.value).padStart(20, '0'),
             );
 
+            function getEntityNameUrl(neid: string) {
+                const config = useRuntimeConfig();
+                const gw = (config.public as any).gatewayUrl as string;
+                const org = (config.public as any).tenantOrgId as string;
+                return `${gw}/api/qs/${org}/entities/${neid}/name`;
+            }
+
             const names = await Promise.all(
                 docNeids.map(async (neid: string) => {
                     try {
-                        const r = await client.getNamedEntityReport(neid);
-                        return r.report?.name ?? (r as any).name ?? neid;
+                        const res = await $fetch<{ name: string }>(
+                            getEntityNameUrl(neid),
+                            { headers: { 'X-Api-Key': getApiKey() } },
+                        );
+                        return res.name || neid;
                     } catch {
                         return neid;
                     }