@yottagraph-app/aether-instructions 1.1.18 → 1.1.20

package/rules/mcp-servers.mdc

@@ -102,7 +102,7 @@ Once deployed, agents can connect to your MCP server. Add the Cloud Run URL to y
 
 - One server per data domain or external service
 - Keep tools focused and well-documented
-- Return structured data (dicts/lists), not raw strings
+- Return structured data (dicts/lists), not raw strings — MCP handles serialization via the protocol. (This differs from ADK agent tools, which should return formatted strings because the LLM reads tool output directly — see the `agents` rule.)
 - Handle errors by returning descriptive error messages in the response
 - Use environment variables for API keys and configuration (never hardcode secrets)
 - For secrets, use GCP Secret Manager and access at runtime

package/rules/pref.mdc

@@ -46,13 +46,25 @@ The backing store auto-initializes on first use — no need to call
 
 ## Local Development
 
-KV credentials are only available in deployed builds (Vercel auto-injects
-them at runtime). In local dev, `getRedis()` returns `null` and KV routes
-return `undefined` for reads and silently skip writes. `Pref<T>` still
-works with its default value but won't persist across page refreshes.
+KV credentials (`KV_REST_API_URL`, `KV_REST_API_TOKEN`) are only available
+in deployed builds (Vercel auto-injects them at runtime). In local dev,
+`getRedis()` returns `null` and KV routes return `undefined` for reads and
+silently skip writes. `Pref<T>` still works with its default value but
+won't persist across page refreshes.
 
 This is expected — push to `main` and test persistence on the deployed build.
 
+For local-only persistence, use `localStorage` as a lightweight alternative:
+
+```typescript
+const saved = localStorage.getItem('watchlist');
+const watchlist = ref<string[]>(saved ? JSON.parse(saved) : []);
+watch(watchlist, (val) => localStorage.setItem('watchlist', JSON.stringify(val)), { deep: true });
+```
+
+Use `Pref<T>` for production persistence and `localStorage` for local-only
+development when KV isn't available.
+
 **Auth dependency:** All `/api/kv/*` routes call `unsealCookie(event)` to
 identify the user. In dev mode (no `NUXT_PUBLIC_AUTH0_CLIENT_SECRET` set),
 this is bypassed automatically using `NUXT_PUBLIC_USER_NAME`. If you set an
@@ -107,22 +119,6 @@ function useMyFeaturePrefs() {
 - **Key format**: `prefs:users:{userId}:apps:{appId}:settings:general`
   (doc-style paths converted to colon-separated Redis keys)
 
-## Local Development Without KV
-
-When KV credentials (`KV_REST_API_URL`, `KV_REST_API_TOKEN`) aren't configured,
-`Pref<T>` still works with its default value but won't persist across page
-refreshes. For local dev, use `localStorage` directly as a lightweight
-alternative:
-
-```typescript
-const saved = localStorage.getItem('watchlist');
-const watchlist = ref<string[]>(saved ? JSON.parse(saved) : []);
-watch(watchlist, (val) => localStorage.setItem('watchlist', JSON.stringify(val)), { deep: true });
-```
-
-Use `Pref<T>` for production persistence and `localStorage` for local-only
-development when KV isn't available.
-
 ## Scope Guidance
 
 | App-specific | Global |

package/rules/server.mdc

@@ -158,6 +158,110 @@ export function getDb(): NeonQueryFunction | null {
 }
 ```
 
+## Calling the Elemental API from Server Routes
+
+Server routes can call the Elemental API through the Portal Gateway proxy,
+just like client-side code does. The gateway URL, tenant org ID, and API key
+are available via `useRuntimeConfig()`.
+
+**NEVER use `readFileSync('broadchurch.yaml')` in server routes.** The YAML
+file is read at build time by `nuxt.config.ts` and its values flow into
+`runtimeConfig`. Nitro serverless functions (Vercel) don't bundle arbitrary
+project files — `readFileSync` will crash with ENOENT in production even
+though it works locally.
+
+```typescript
+export default defineEventHandler(async (event) => {
+  const { public: config } = useRuntimeConfig();
+
+  const gatewayUrl = config.gatewayUrl;   // Portal Gateway base URL
+  const orgId = config.tenantOrgId;       // Tenant org ID (path segment)
+  const apiKey = config.qsApiKey;         // API key for X-Api-Key header
+
+  if (!gatewayUrl || !orgId) {
+    throw createError({ statusCode: 503, statusMessage: 'Gateway not configured' });
+  }
+
+  const res = await $fetch(`${gatewayUrl}/api/qs/${orgId}/entities/search`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      ...(apiKey && { 'X-Api-Key': apiKey }),
+    },
+    body: { queries: [{ queryId: 1, query: 'Microsoft' }], maxResults: 5 },
+  });
+
+  return res;
+});
+```
+
+Available runtime config keys (all under `runtimeConfig.public`):
+
+| Key | Source | Purpose |
+|---|---|---|
+| `gatewayUrl` | `broadchurch.yaml` → `gateway.url` | Portal Gateway base URL |
+| `tenantOrgId` | `broadchurch.yaml` → `tenant.org_id` | Tenant ID for API path |
+| `qsApiKey` | `broadchurch.yaml` → `gateway.qs_api_key` | API key sent as `X-Api-Key` |
+| `queryServerAddress` | `broadchurch.yaml` → `query_server.url` | Direct QS URL (prefer gateway) |
+
+Build the request URL as `{gatewayUrl}/api/qs/{tenantOrgId}/{endpoint}`.
+See the `api` rule for endpoint reference and response shapes.
+
+## Neon Postgres: Handle Missing Tables in GET Routes
+
+Tables created by POST/setup routes won't exist on a fresh deployment.
+**Every GET route that queries a table must handle the case where the table
+doesn't exist yet.** Without this, fresh deploys will 500 on every page load
+until the setup route runs.
+
+```typescript
+export default defineEventHandler(async () => {
+  const sql = getDb();
+  if (!sql) throw createError({ statusCode: 503, statusMessage: 'Database not configured' });
+
+  try {
+    const rows = await sql`SELECT * FROM companies ORDER BY updated_at DESC`;
+    return rows;
+  } catch (err: any) {
+    if (err.message?.includes('does not exist')) {
+      return [];
+    }
+    throw err;
+  }
+});
+```
+
+Alternatively, ensure tables exist before querying by calling
+`CREATE TABLE IF NOT EXISTS` at the top of each GET route, or by calling a
+shared setup function:
+
+```typescript
+// server/utils/ensure-tables.ts
+import { getDb } from '~/server/utils/neon';
+
+let _initialized = false;
+
+export async function ensureTables() {
+  if (_initialized) return;
+  const sql = getDb();
+  if (!sql) return;
+
+  await sql`CREATE TABLE IF NOT EXISTS companies (
+    id SERIAL PRIMARY KEY,
+    neid TEXT UNIQUE NOT NULL,
+    name TEXT NOT NULL,
+    data JSONB DEFAULT '{}',
+    updated_at TIMESTAMPTZ DEFAULT NOW()
+  )`;
+
+  _initialized = true;
+}
+```
+
+Then call `await ensureTables()` at the start of any route that reads the
+table. The `_initialized` flag makes it a no-op after the first call within
+the same serverless invocation.
+
 ## Key Differences from Client-Side Code
 
 - Server routes run on the server (Node.js), not in the browser

package/skills/data-model/newsdata/schema.yaml

@@ -62,12 +62,14 @@ flavors:
     description: "A news article or press release being processed"
     display_name: "Article"
     mergeability: not_mergeable
+    strong_id_properties: ["newsdata_id"]
     passive: true
 
   - name: "publication"
     description: "A news publication or media outlet identified by its home URL"
     display_name: "Publication"
     mergeability: not_mergeable
+    strong_id_properties: ["homeUrl"]
     passive: true
 
 # =============================================================================
@@ -389,6 +391,14 @@ properties:
     domain_flavors: ["article"]
     passive: true
 
+  - name: "newsdata_id"
+    type: string
+    description: "Unique article identifier from the NewsData API"
+    display_name: "NewsData ID"
+    mergeability: not_mergeable
+    domain_flavors: ["article"]
+    passive: true
+
   - name: "title"
     type: string
     description: "Title of the entity"

package/skills/elemental-api/SKILL.md

@@ -11,17 +11,15 @@ This skill provides documentation for the Lovelace Elemental API, the primary in
 
 Use this skill when you need to:
 - Look up entities (companies, people, organizations) by name or ID
-- Get sentiment analysis for entities over time
-- Find news mentions and articles about entities
-- Explore relationships and connections between entities
-- Retrieve events involving specific entities
+- Search for entities by type, property values, or relationships using the expression language
+- Get entity metadata (types/flavors, properties)
 - Build knowledge graphs of entity networks
 
 ## Quick Start
 
 1. **Find an entity**: Use `entities.md` to look up a company or person by name and get their NEID (Named Entity ID)
-2. **Get information**: Use the NEID to query sentiment, mentions, relationships, or events
-3. **Dive deeper**: Retrieve full article details or explore connected entities
+2. **Get information**: Use the NEID to query entity properties or explore the graph
+3. **Search**: Use `find.md` for expression-based entity searches
 
 ## Files in This Skill
 
@@ -29,9 +27,5 @@ See [overview.md](overview.md) for descriptions of each endpoint category:
 - `entities.md` - Entity search, details, and properties
 - `find.md` - Expression language for searching entities by type, property values, and relationships
 - `schema.md` - Data model: entity types (flavors), properties, and schema endpoints
-- `sentiment.md` - Sentiment analysis
-- `articles.md` - Articles mentioning entities and full article content
-- `events.md` - Events involving entities
-- `relationships.md` - Entity connections
 - `graph.md` - Visual graph generation
 - `server.md` - Server status and health

package/skills/elemental-api/entities.md

@@ -2,6 +2,10 @@
 
 Entities are the core objects in the Knowledge Graph: companies, people, organizations, products, and other named things that appear in the news. Each entity has a unique **Named Entity ID (NEID)**.
 
+NEIDs are stable and can be persisted long-term, but may occasionally change if the database is rebuilt or the application switches databases. When an NEID becomes invalid (e.g., resolution returns no results), re-resolve the entity using its canonical name from the previous query result, then redo any downstream operations that depended on it. NEIDs should NEVER be hardcoded in source code.
+
+**Looking for property-based search?** To search for entities by type, property values, or relationships using the expression language, see [find.md](find.md).
+
 ## When to Use
 
 - You have an entity name and need to find its NEID
@@ -16,28 +20,24 @@ Entities are the core objects in the Knowledge Graph: companies, people, organiz
   - Example: `00416400910670863867`
   - Always pad with leading zeros to exactly 20 characters when normalizing
 - **EID**: The term EID is sometimes used interchangeably with NEID.
+- **nindex**: The term nindex is sometimes used interchangeably with NEID.
 - **Entity Resolution**: The same real-world entity may have multiple names (e.g., "Apple", "Apple Inc.", "AAPL"). The API resolves these to a single NEID.
-- **Entity Types (Flavors)**: Each entity has a type identified by a Flavor ID (FID) (ex. type "ship" is FID 1).
+- **Flavors (Entity Types)**: Each entity has a type identified by a Flavor ID (FID).
 
 ## Tips
 
 - Always start by searching for the entity to get the correct NEID
-- After resolving an entity to an NEID, it's best to display the canonical entity name to the user to help them identify if something went wrong with the resolution.
+- After resolving an entity to an NEID, save and use the the canonical entity name going forward.
 - It's typically safe to resolve an entity to the top matching NEID. However, sometimes a useful pattern is to let the user give input that the resolution was incorrect, show them a longer list of matches, and let them choose a different resolution.
 - Entity names are case-insensitive
 
 ## Key Endpoints
 
-| What you need | Endpoint | Client method | Returns |
-|---------------|----------|---------------|---------|
-| Find entities by expression | `POST /elemental/find` | `findEntities()` | Entity IDs matching expression |
-| Find entity by name (simple lookup) | `GET /entities/lookup` | `getNEID()` | NEIDs matching a single name query |
-| Basic info (name, aliases, type) | `GET /entities/{neid}` | — | Quick summary for display |
-| Full property values | `POST /elemental/entities/properties` | `getPropertyValues()` | All properties with PIDs, values, timestamps |
-
-**`findEntities()` vs `getNEID()` for entity search**:
-- **`findEntities()`** → `POST /elemental/find` — expression-based search. Supports filtering by type, property value, relationship, and complex nested queries. See `find.md` for the expression language. **Use this for filtered or batch searches.**
-- **`getNEID()`** → `GET /entities/lookup` — simple single-entity name lookup via query parameters (`entityName`, `maxResults`). Best for resolving one company/person name quickly.
+| What you need | Endpoint | Returns |
+|---------------|----------|---------|
+| Find entity by name (batch, scored) | `POST /entities/search` | Ranked matches with NEIDs and scores |
+| Basic info (name, aliases, type) | `GET /entities/{neid}` | Quick summary for display |
+| Full property values | `POST /elemental/entities/properties` | All properties with PIDs, values, timestamps |
 
 **Important**: When a user asks for "entity properties," clarify which they mean:
 - Basic info/metadata → use `/entities/{neid}`
@@ -160,57 +160,42 @@ The same pattern applies to the `expression` parameter on `POST /elemental/find`
 
 For understanding entity types (flavors), properties, and the data model, see **schema.md**. You'll need the schema because many API responses return only FIDs and PIDs — use it to translate these to human-readable names.
 
+## Properties Return Multiple Timestamped Values
 
-<!-- BEGIN GENERATED CONTENT -->
-
-## Endpoints
-
-### Get entity details
-
-`GET /entities/{neid}`
-
-Get details about a named entity including name, aliases, and type. This is an alias for /reports/{neid}. Response is cached for 5 minutes.
-
-#### Guidance
-
-Response is wrapped in a 'report' container object. Access entity data via response.report.
-
-#### Parameters
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| neid | string | yes | Named Entity ID |
+`getPropertyValues` returns **all** recorded values for a property, not just the latest. A single entity and property (e.g. Apple's `company_cik`) may return dozens of rows with different `recorded_at` timestamps — one per filing or data ingestion event. For display, take the first (or latest) value and deduplicate by PID:
 
-#### Responses
+```typescript
+const byPid = new Map<number, string>();
+for (const v of values) {
+    if (!byPid.has(v.pid)) byPid.set(v.pid, v.value);
+}
+```
 
-| Status | Description |
-|--------|-------------|
-| 200 | Entity details (`GetNamedEntityReportResponse`) |
-| 400 | Invalid NEID (`Error`) |
-| 404 | Entity not found (`Error`) |
-| 500 | Internal server error (`Error`) |
+## `include_attributes` Parameter
 
-#### Example
+`getPropertyValues` accepts an `include_attributes` parameter (set to `'true'` as a string) that returns additional metadata on each value. This is essential for relationship properties like `appears_in`, where attributes carry entity-level sentiment scores and article URLs.
 
-**Request:**
+**Note:** The generated TypeScript client types don't include `include_attributes` in the parameter type. Pass it as an extra property — the API accepts it:
 
-```
-GET /entities/00416400910670863867
+```typescript
+const res = await client.getPropertyValues({
+    eids: JSON.stringify([neid]),
+    pids: JSON.stringify([appearsInPid]),
+    include_attributes: 'true',  // Not in TS types, but API accepts it
+} as any);
 ```
 
-**Response:**
+Attribute values are keyed by **numeric PID**, not by name. Resolve attribute names to PIDs via the schema before accessing them.
 
-```json
-{"report": {"neid": "00416400910670863867", "name": "Apple", "aliases": ["AAPL", "APPLE", "APPLE INC", "Apple Inc"], "type": "organization"}}
-```
+<!-- BEGIN GENERATED CONTENT -->
 
----
+## Endpoints
 
-### Get entity report
+### Get entity details
 
-`GET /reports/{neid}`
+`GET /entities/{neid}`
 
-Get a report about a named entity including name, aliases, and type. Response is cached for 5 minutes.
+Get details about a named entity including name, aliases, and type. This is an alias for /reports/{neid}. Response is cached for 5 minutes.
 
 #### Guidance
 
@@ -226,7 +211,7 @@ Response is wrapped in a 'report' container object. Access entity data via respo
 
 | Status | Description |
 |--------|-------------|
-| 200 | Entity report (`GetNamedEntityReportResponse`) |
+| 200 | Entity details (`GetNamedEntityReportResponse`) |
 | 400 | Invalid NEID (`Error`) |
 | 404 | Entity not found (`Error`) |
 | 500 | Internal server error (`Error`) |
@@ -236,7 +221,7 @@ Response is wrapped in a 'report' container object. Access entity data via respo
 **Request:**
 
 ```
-GET /reports/00416400910670863867
+GET /entities/00416400910670863867
 ```
 
 **Response:**
@@ -247,54 +232,6 @@ GET /reports/00416400910670863867
 
 ---
 
-### Find entities by expression
-
-`POST /elemental/find`
-
-Search for entities using a powerful expression language. The expression parameter supports complex nested queries with logical operators, geographic constraints, property comparisons, and more.
-
-#### Guidance
-
-CRITICAL: This endpoint REQUIRES Content-Type: application/x-www-form-urlencoded. Sending a JSON body will fail with 400 error. The expression parameter must be URL-encoded form data, not a JSON request body. For the full expression language reference including all expression types, comparison operators, and examples, see find.md.
-
-#### Request Body
-
-**Content-Type:** `application/x-www-form-urlencoded`
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| expression | string | yes | JSON-encoded expression object defining the search criteria |
-| deadline | any | no | Response deadline in milliseconds or duration format |
-| limit | integer | no | Maximum number of entity IDs to return in first response |
-
-#### Responses
-
-| Status | Description |
-|--------|-------------|
-| 200 | Find operation successful (`FindResponse`) |
-| 400 | Bad request - invalid parameters or malformed expression (`Error`) |
-| 500 | Internal server error (`Error`) |
-| 501 | Elemental API capability not enabled (`Error`) |
-
-#### Example
-
-**Request:**
-
-```
-POST /elemental/find
-Content-Type: application/x-www-form-urlencoded
-
-expression={"type":"is_type","is_type":{"fid":10}}&limit=5
-```
-
-**Response:**
-
-```json
-{"op_id": "98cc54e9-0108-4361-9c96-18ea97cda7a2", "follow_up": true, "eids": ["01601807036815568643", "08115040994665529432", "02045070050429461063"]}
-```
-
----
-
 ### Get property values for entities
 
 `POST /elemental/entities/properties`
@@ -361,18 +298,6 @@ The named entity report
 | neid | string | Named Entity ID |
 | type | string | Entity type (flavor) |
 
-### FindResponse
-
-| Field | Type | Description |
-|-------|------|-------------|
-| find | `FindData` |  |
-
-### FindData
-
-| Field | Type | Description |
-|-------|------|-------------|
-| **eids** | string[] | Array of 20-character entity IDs matching the search expression |
-
 ### GetPropertyValuesResponse
 
 | Field | Type | Description |

package/skills/elemental-api/find.md

@@ -5,8 +5,8 @@ The `/elemental/find` endpoint searches for entities using a JSON expression lan
 ## When to Use
 
 - You need to search for entities matching specific criteria (type, property values, relationships)
-- You need to combine multiple filters (e.g., "ships with name containing PACIFIC")
-- You need to find entities connected to a given entity via the knowledge graph
+- You need to combine multiple filters
+- You need to find entities connected to a given entity via the relationship links
 
 ## Expression Structure
 
@@ -124,13 +124,13 @@ Content-Type: application/x-www-form-urlencoded
 expression={"type":"comparison","comparison":{"operator":"string_like","pid":8,"value":"Apple"}}
 ```
 
-### Find ships with "PACIFIC" in the name (combined AND)
+### Find organizations with "Global" in the name (combined AND)
 
 ```
 POST /elemental/find
 Content-Type: application/x-www-form-urlencoded
 
-expression={"type":"and","and":[{"type":"is_type","is_type":{"fid":1}},{"type":"comparison","comparison":{"operator":"string_like","pid":8,"value":"PACIFIC"}}]}&limit=50
+expression={"type":"and","and":[{"type":"is_type","is_type":{"fid":10}},{"type":"comparison","comparison":{"operator":"string_like","pid":8,"value":"Global"}}]}&limit=50
 ```
 
 ### Find entities linked to a specific entity
@@ -261,6 +261,12 @@ expression={"type":"is_type","is_type":{"fid":10}}&limit=5
 |-------|------|-------------|
 | **is_type** | `IsType` |  |
 
+### LinkedExpression
+
+| Field | Type | Description |
+|-------|------|-------------|
+| **linked** | `Linked` |  |
+
 ### Comparison
 
 | Field | Type | Description |
@@ -276,4 +282,13 @@ expression={"type":"is_type","is_type":{"fid":10}}&limit=5
 |-------|------|-------------|
 | **fid** | integer | Flavor identifier (FID) representing entity type |
 
+### Linked
+
+| Field | Type | Description |
+|-------|------|-------------|
+| **distance** | integer | Maximum relationship distance to traverse |
+| pids | integer[] | Property identifiers defining the relationship types to follow |
+| to_entity | string | Target entity ID for relationship traversal |
+| direction | string | Direction of relationship traversal. 'outgoing' (default) follows subject->value edges, 'incoming' follows value->subject (reverse) edges, 'both' unions outgoing and incoming results. |
+
 <!-- END GENERATED CONTENT -->

package/skills/elemental-api/graph.md

@@ -1,6 +1,6 @@
 # Graph
 
-The graph endpoints are focused on "graph analysis", providing insights into relationships between different entities. This includes, but is not limited to, visual rendering of a graph.
+The graph endpoints are focused on "graph analysis". This includes, but is not limited to, visual rendering of a graph.
 
 ## When to Use
 
@@ -32,7 +32,7 @@ Get nodes and edges layout data for visualizing a relationship graph. Response i
 
 #### Guidance
 
-Only use this endpoint if you care about graph-specific properties. Otherwise it is faster to use /entities/{source_neid}/links/{target_neid}. This should always be called with a non-empty list of neids. A typical pattern is to call /graph/{center_neid}/neighborhood and then use the returned NEIDs to call this endpoint.
+This should always be called with a non-empty list of neids. A typical pattern is to call /graph/{center_neid}/neighborhood and then use the returned NEIDs to call this endpoint.
 
 #### Parameters
 
@@ -77,7 +77,7 @@ Get list of neighboring entities in the relationship graph, optionally filtered
 
 #### Guidance
 
-Only use this endpoint if you care about graph-specific properties. Otherwise it is faster to use /entities/{source_neid}/linked. Response includes the center entity itself in the results with a weight of 1.0. The 'neighbors' and 'weights' arrays are parallel (same indices correspond).
+Response includes the center entity itself in the results with a weight of 1.0. The 'neighbors' and 'weights' arrays are parallel (same indices correspond).
 
 #### Parameters
 

package/skills/elemental-api/overview.md

@@ -4,26 +4,55 @@ The Elemental API provides access to the Lovelace Knowledge Graph through the Qu
 
 ## Core Concepts
 
-### Named Entity ID (NEID)
+### Entities
+
+Every entity has:
+- **NEID** — a unique Named Entity ID (stable identifier)
+- **Name** — human-readable label (may have aliases)
+- **Flavor** — the entity type (e.g. "organization", "person", "country", "vessel", "event")
+
+#### Named Entity ID (NEID)
+
 Every entity in the system has a unique identifier called a NEID. Most API calls require a NEID, so your first step is usually looking up an entity by name to get its NEID.
 
 **Format**: 20-character numeric string with zero-padding. Example: `00416400910670863867`
 
 When normalizing NEIDs, always pad with leading zeros to exactly 20 characters.
 
+NEIDs are stable and can be persisted long-term, but may occasionally change if the database is rebuilt or the application switches databases. When an NEID becomes invalid (e.g., resolution returns no results), re-resolve the entity using its canonical name from the previous query result, then redo any downstream operations that depended on it. NEIDs should NEVER be hardcoded in source code.
+
 **Note**: The terms "eid" and "neid" are interchangeable throughout the API. Some endpoints use `neid` and others use `eid`, but they refer to the same entity identifier.
 
-### Mention Code (MCODE)
-A mention is a specific reference to an entity in an article. Each mention has a unique MCODE that links the entity, article, and context together.
+### Properties
+
+Key-value facts attached to entities, scoped by flavor.
+
+Examples: nationality, birth_date, industry, total_revenue, employee_count.
+
+Use the schema to discover which properties are available for
+a given entity type.
 
-**Format**: `{neid}:{artid}` with colon separator. Example: `00416400910670863867:05433395856363393596`
+## Relationships
 
-### Time Ranges
-Most endpoints accept `start` and `end` parameters for filtering by date.
+Directed, typed edges between two entities:
+- **Type** — e.g. "owns", "board_member_of", "subsidiary_of", "appears_in"
+- **Direction** — relationships go from source (subject) to target (object)
 
-**Required format**: Full ISO 8601 with timezone.
-- Correct: `2026-01-28T00:00:00Z`
-- Incorrect: `2026-01-28` (missing time and timezone)
+## Attributes
+
+Metadata attached to relationships. For example, the "participant" relationship
+connecting an entity to an event carries:
+- **role** — the entity's role in the event (e.g. "acquirer", "target", "plaintiff")
+- **sentiment** — an impact score for the entity's involvement
+
+## Events
+
+Structured occurrences extracted from source data, each with:
+- **Category** — e.g. "Bankruptcy", "IPO", "Layoffs", "Acquisition"
+- **Date** — when the event occurred (YYYY-MM-DD, or YYYY-MM / YYYY for partial dates)
+- **Description** — detailed, objective description of the event
+- **Likelihood** — temporal status: confirmed, ongoing, likely, or speculative
+- **Participants** — entities involved, each with a role and sentiment score
 
 ## Endpoint Categories
 
@@ -31,21 +60,16 @@ Most endpoints accept `start` and `end` parameters for filtering by date.
 |------|------------------------|
 | [entities.md](entities.md) | Look up entities by name, get details and properties |
 | [find.md](find.md) | Search for entities by type, property values, or relationships using the expression language |
-| [sentiment.md](sentiment.md) | Get sentiment scores and trends for an entity |
-| [articles.md](articles.md) | Get articles that mention an entity, article content, titles, summaries |
-| [events.md](events.md) | Find events involving an entity (mergers, lawsuits, etc.) |
-| [relationships.md](relationships.md) | Find connections between entities |
+| [schema.md](schema.md) | Understand the data model: entity types (flavors), properties, and their metadata |
 | [graph.md](graph.md) | Generate visual network graphs |
-| [server.md](server.md) | Check server status and capabilities, as well as schema info including flavors and properties. |
-| [llm.md](llm.md) | (Not currently available) AI-assisted queries |
+| [server.md](server.md) | Check server status and capabilities |
 
 ## Common Workflows
 
-### "What's the sentiment for Apple?"
-1. `entities.md` → Look up "Apple" to get NEID
-2. `sentiment.md` → Query sentiment with the NEID
-
+### "Find all organizations in a specific sector"
+1. `schema.md` → Check available properties and flavors
+2. `find.md` → Use the expression language to search by property values
 
-### "How are Microsoft and OpenAI connected?"
-1. `entities.md` → Look up both companies to get NEIDs
-2. `relationships.md` → Query links between the two NEIDs
+### "What companies are related to Apple?"
+1. `entities.md` → Look up "Apple" to get NEID
+2. `find.md` → Query linked entities to find related entities