@dx-do/cli 5.2.49 → 6.0.1

package/dist-node/tas-cookbook-0y4826rp.md

@@ -0,0 +1,693 @@
+---
+id: tas-cookbook
+title: TAS cookbook — operations reference and recipe catalog
+applies_to: tas
+tags: [reference, recipes, authoring]
+related: [tas-quickstart, gotchas, discovery-flow, run-query-vs-run-partial]
+---
+
+# TAS cookbook
+
+Full operation reference for TAS (`/tas/graph/query`) authoring, plus a
+recipe catalog. Use after `tas-quickstart.md` when you need the breadth of
+ops or a concrete pattern to start from. The schema's `.describe()`
+metadata is the canonical wire spec — this cookbook organizes it by
+purpose.
+
+## TAS at a glance
+
+A TAS query returns a graph (`vertices` + `edges`) shaped by a single
+recursive **filter tree**. Every filter node is `{ "op": "<NAME>", ... }` —
+a discriminated union on `op`. Most ops can wrap an `input` filter
+(recursive composition); leaf ops (`ALL`, `LAYER`, `LUCENE`, `VARIABLE`)
+do not.
+
+```mermaid
+flowchart LR
+  envelope["TasQuery envelope { filter, projection, limit, variables, ... }"] --> root["root filter (composite)"]
+  root --> leaves["leaves: ALL / ATTRIBUTE / LAYER / VERTEX / LUCENE / VARIABLE"]
+  root --> composers["composers: AND / OR / NOT"]
+  root --> shapers["shapers / collectors: TRAVERSE / TAKE_VERTICES / TAKE_EDGES / FOLLOW_PATH / COLLECT_*"]
+  composers --> root
+  shapers --> root
+```
+
+## Top-level envelope
+
+Common fields:
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| `filter` | TasFilter | Root filter tree (required in practice) |
+| `limit` | number | Cap returned vertices |
+| `offset` | number | Pagination offset |
+| `projection` | `"DETAILED" \| "BRIEF" \| "NO_TYPE"` | Vertex/edge attribute breadth |
+| `projectionFilter` | `{ attributes: string[], attributeValueAsFields?: ... }` | Project specific attributes only |
+| `order` | `[{ name, comparator, caseInsensitive, desc }]` | Sort order |
+| `variables` | `[{ name, input: filter }]` | Named sub-filters reusable via `{op: "VARIABLE", name}` |
+| `universe` | TasFilter | Restrict the working set before `filter` |
+| `postFilter` | TasFilter | Filter applied after `filter` |
+| `stateFilter` | VertexStateFilter | Restrict by vertex state |
+| `includeStatus` | boolean | Adds a `states[]` array to the response (does NOT filter topology — see [Status section](#status--includestatus-and-the-states-response-array)). |
+| `includeServices` | boolean | Adds service-attribution metadata to each vertex |
+| `authorizationView` | string | Apply an auth view restriction |
+
+`projection` only changes attribute breadth (`DETAILED` is the default for
+"give me everything"). Use `projectionFilter.attributes[]` to project a
+specific subset.
+
+## Leaf filters
+
+### `ALL`
+Match every vertex. Use with a small `limit` for sampling.
+
+```json
+{ "op": "ALL" }
+```
+
+### `ATTRIBUTE`
+The workhorse — match by one or more attribute expressions. The list of
+expressions is AND-ed.
+
+```json
+{
+  "op": "ATTRIBUTE",
+  "expressions": [
+    { "name": "type", "values": ["HOST"], "operator": "IN" }
+  ]
+}
+```
+
+`AttributeExpression` fields:
+
+| Field | Notes |
+|-------|-------|
+| `name` | Attribute name (e.g. `type`, `name`, `hostname`, `k8s_namespace`) |
+| `pointer` | JSON pointer for nested attribute lookup |
+| `values` | Comparison values (regex pattern strings for `MATCHES`) |
+| `operator` | `IN \| NOT_IN \| MATCHES \| NOT_MATCHES \| GE \| GT \| LE \| LT` |
+| `comparator` | `LEXICAL \| NUMBER \| DATETIME` (default LEXICAL) |
+| `caseInsensitive` | for MATCHES |
+| `layer` | Optional: scope expression to a layer |
+
+There is no `TYPE` or `ID` filter op — type is just an attribute named `type`,
+and id selection is done via the `VERTEX` op (below).
+
+### `LAYER`
+Restrict to a layer (`externalId` first segment, by convention).
+
+```json
+{ "op": "LAYER", "value": "ATC" }
+```
+
+Or multiple layers:
+
+```json
+{ "op": "LAYER", "values": ["ATC", "INFRASTRUCTURE", "APM_INFRASTRUCTURE"] }
+```
+
+Discover real layer names via `corpus_get("queries", "50-discover-custom-layers")`,
+or by inspecting `externalId` prefixes on an `ALL` query.
+
+### `VERTEX`
+Select by id or external id.
+
+```json
+{ "op": "VERTEX", "vertexId": [12345, 67890] }
+```
+
+```json
+{ "op": "VERTEX", "externalId": ["ATC:tx:checkout"] }
+```
+
+### `LUCENE`
+Lucene-style query string (only on tenants with Lucene indexing — see
+gotchas).
+
+```json
+{ "op": "LUCENE", "query": "name:Kubernetes*" }
+```
+
+### `VARIABLE`
+Reference a named sub-filter declared in the top-level `variables[]` array.
+
+```json
+{ "op": "VARIABLE", "name": "k8s_hosts" }
+```
+
+### `SERVICE`
+Restrict to vertices participating in a named service (or services).
+
+```json
+{
+  "op": "SERVICE",
+  "values": ["payments-api"],
+  "includeServiceHierarchy": true
+}
+```
+
+## Composition
+
+### `AND` / `OR`
+
+```json
+{ "op": "AND", "input": [filterA, filterB, ...] }
+```
+
+```json
+{ "op": "OR",  "input": [filterA, filterB, ...] }
+```
+
+### `NOT`
+
+```json
+{ "op": "NOT", "input": filterA }
+```
+
+`AND`/`OR` take an **array** in `input`; `NOT` takes a **single** filter.
+Empty `AND`/`OR` arrays are rejected — see `gotchas.md`.
+
+### Variable reuse (`variables[]` + `VARIABLE`)
+
+Declare named sub-filters at the top level, then reference them in the main
+filter tree. Useful when the same vertex set is reused as a starting point.
+
+```json
+{
+  "variables": [
+    { "name": "k8s_hosts", "input": { "op": "ATTRIBUTE", "expressions": [ ... ] } }
+  ],
+  "filter": {
+    "op": "TRAVERSE",
+    "input": { "op": "VARIABLE", "name": "k8s_hosts" },
+    "traverse": [{ "direction": "ANY", "repeat": 1 }]
+  },
+  ...
+}
+```
+
+There is no `ASSIGN` / `USE` op — the top-level `variables[]` array is the
+mechanism.
+
+## Graph shaping
+
+These wrap a base filter (`input`) and reshape its result.
+
+### `TRAVERSE`
+Walk the graph from a starting set. Each `Traverse` step has `direction`,
+`repeat` (max hops), and optional `vertexFilter` / `edgeFilter` / `next`
+(nested traversal).
+
+```json
+{
+  "op": "TRAVERSE",
+  "input": { "op": "ATTRIBUTE", "expressions": [...] },
+  "traverse": [{ "direction": "ANY", "repeat": 2 }],
+  "includeInput": true
+}
+```
+
+`direction`: `FORWARD | BACKWARD | ANY`. `includeInput: true` keeps the
+starting vertices in the result; without it you only get the traversal
+targets.
+
+Multi-step (chained) traversal:
+
+```json
+{
+  "op": "TRAVERSE",
+  "input": { "op": "ATTRIBUTE", "expressions": [...] },
+  "traverse": [
+    { "direction": "FORWARD", "repeat": 1,
+      "next": [{ "direction": "BACKWARD", "repeat": 2 }] }
+  ]
+}
+```
+
+### `TAKE_VERTICES` / `TAKE_EDGES` / `TAKE_FLOWS`
+Restrict the result to only vertices, only edges, or only flow records:
+
+```json
+{ "op": "TAKE_EDGES", "input": { "op": "TRAVERSE", ... } }
+```
+
+Common pattern: traverse then `TAKE_EDGES` to get just the edges between two
+sets of vertices.
+
+### `FOLLOW_PATH`
+Directional path-following with hop limits and flow filtering. Useful for
+"upstream / downstream" queries.
+
+```json
+{
+  "op": "FOLLOW_PATH",
+  "input": filter,
+  "type": "DOWN",
+  "downHops": 3,
+  "followToLayers": ["INFRASTRUCTURE"]
+}
+```
+
+`type`: `UP | DOWN | BOTH | UP_THEN_DOWN | DOWN_THEN_UP | FULL | COVERAGE`.
+
+### `STATUS`
+Restrict the input set by current vertex state (alerts, metrics, etc.).
+
+```json
+{
+  "op": "STATUS",
+  "input": filter,
+  "statusFilter": { "op": "ALERT", ... }
+}
+```
+
+You can also use the top-level `stateFilter` field for the same effect.
+
+> ⚠️ The `statusFilter`'s `STATE` leaf op (filtering by numeric status code) is
+> currently a server-side no-op — `state[]` is silently ignored. Use the two-query
+> client-side filter pattern in `cookbooks/gotchas` instead. The other state-filter
+> ops (`ALERT`, `METRIC`, `VERTEX_ID`, `NAMESPACE`, `MANAGEMENT_MODULE`) work
+> as expected.
+
+### `ADD_FLOWS` / `ADD_WIRES` / `ADD_WIRE_CONTEXT` / `ADD_TRANSITIONING_EDGES`
+Augment the result with related flow/wire/transitioning-edge information
+without changing the base vertex set.
+
+- `ADD_FLOWS` — adds flow records (`direction: FORWARD | BACKWARD | ANY`).
+- `ADD_WIRES` — adds wire connection records.
+- `ADD_WIRE_CONTEXT` — adds wire context records with service context.
+- `ADD_TRANSITIONING_EDGES` — adds edges whose endpoints are currently
+  transitioning state.
+
+All four wrap an `input` filter and return the original vertex/edge result
+enriched with the additional domain records.
+
+### `COVERAGE`
+Compute coverage information over the input set. Use `COVERAGE` with TAS-level
+alert/health context filters.
+
+### `JOIN`
+Join two filter results. `type`: `INNER | LEFT | RIGHT | NOT`. Use sparingly —
+most TAS queries are tree-shaped, not join-shaped.
+
+```json
+{ "op": "JOIN", "input": filterA, "rightInput": filterB, "type": "INNER" }
+```
+
+### `LEGACY`
+Escape hatch for server-side legacy filter syntax. Use only when a modern
+equivalent does not exist — the string is executed as an internal legacy query.
+
+```json
+{ "op": "LEGACY", "query": "..." }
+```
+
+### `PROJECT`
+Return a pre-computed projection result by name. Rarely needed outside
+server-generated queries.
+
+```json
+{ "op": "PROJECT", "name": "some-projection" }
+```
+
+## Collectors
+
+Specialized filters that return aggregated information about the input set
+rather than the vertices/edges themselves. Each result is keyed by `id` in the
+`analytics[]` array of the `TasGraph` response.
+
+| Op | Key field(s) | What it returns |
+|----|--------------|----------------|
+| `COLLECT_ATTRIBUTES` | `attributeName` (single string) | Distinct values of one attribute across the matched vertex set, with per-value count and (optionally) the vertex IDs that carry each value. Stack multiple instances inside an `AND` to collect several attributes in one round-trip. |
+| `COLLECT_ATTRIBUTE_NAMES` | — | Distinct attribute names present on the matched vertex set. |
+| `COLLECT_VERTEX_ID` | — | List of vertex IDs in the result set. |
+| `COLLECT_COUNTS` | — | Vertex + edge counts (with optional per-type breakdown). |
+| `COLLECT_GROUPING_INFO` | `grouping: [{name, layer}, ...]` | Hierarchical grouping breakdown along one or more grouping dimensions, with per-group counts and alert stats. |
+| `COLLECT_CARD_INFO` | `tier`, `attributeName` | Card-shaped summary for one APM tier, grouped by a single attribute. |
+| `COLLECT_EXPERIENCE_ATTRIBUTES` | `attributeName`, `selector` | Same shape as `COLLECT_ATTRIBUTES`, restricted to APM experience or business-transaction vertices. |
+
+**Field-name landmine:** `COLLECT_ATTRIBUTES` is `attributeName` (singular). The `grouping[]` array shape lives on `COLLECT_GROUPING_INFO` — these are distinct ops with distinct payload shapes. Using `groupings`/`grouping` on `COLLECT_ATTRIBUTES` returns HTTP 500.
+
+Collectors wrap an `input` filter. The `id` field on each collector maps to a
+key in `TasGraph.analytics[]` — use multiple collectors inside an `AND` to
+collect several summaries in a single round-trip.
+
+```json
+{
+  "op": "AND",
+  "input": [
+    { "op": "ALL" },
+    { "op": "COLLECT_COUNTS", "id": "counts", "input": { "op": "ALL" } },
+    { "op": "COLLECT_ATTRIBUTE_NAMES", "id": "attrNames", "input": { "op": "ALL" } }
+  ]
+}
+```
+
+The schema's `.describe()` metadata documents the per-collector field details
+(see `tas/response.ts` schemas via the package's `.d.ts`).
+
+## Status — `includeStatus` and the `states[]` response array
+
+Setting `includeStatus: true` at the envelope level adds a `states[]`
+array to the response alongside `vertices[]` / `edges[]`. **This is
+purely additive** — the toggle does NOT filter the topology; it just
+attaches state information for the vertices already in the result.
+
+To filter topology BY state, use the `STATUS` op (or top-level
+`stateFilter`) — those narrow the vertex set; `includeStatus` controls
+whether the state rows are also serialized in the response. Most
+callers want both: filter via `STATUS`, then `includeStatus: true` to
+inspect the state alongside the matched topology.
+
+### `states[]` shape
+
+Each entry is a per-`(vertex, alert OR metric)` row, so a single
+vertex can have multiple state rows:
+
+```ts
+type VertexStateResponseItem = {
+  vertexId: number;
+  alertId?: number;     // populated for alert-driven state rows
+  metricId?: number;    // populated for metric-driven state rows
+  stateExternalId?: {
+    vertexId: number;
+    alert?: string;     // e.g. "sa://sa_status" — see rolled-up alert below
+    metric?: string;
+  };
+  status: number;       // numeric severity — see mapping below
+  data?: {
+    alarm?: { total, critical, major, minor, information };
+    services?: Record<string, unknown>;
+    stateUpdated?: boolean;
+  };
+  startTime: number;    // epoch ms when this state began
+  endTime: number;      // epoch ms when it ended; far-future ⇒ ongoing
+};
+```
+
+### Numeric `status` mapping
+
+Per-tenant DXO2 convention (verified empirically — used by both
+`states[].status` and `STATUS.statusFilter`'s `STATE` op `state[]`):
+
+| `status` | Label |
+|---|---|
+| 0 | UNKNOWN |
+| 1 | OK |
+| 2 | MINOR |
+| 3 | MAJOR |
+| 4 | CRITICAL |
+
+(See `cookbooks/gotchas` for the caveat that the canonical schema
+under-documents this — and that the `STATE` filter op itself is
+currently a server-side no-op until that's fixed.)
+
+### The rolled-up `sa://sa_status` alert
+
+Every vertex carries a synthetic aggregate alert with
+`stateExternalId.alert === "sa://sa_status"`. Its `status` is the
+**worst severity across all of that vertex's individual alerts and
+metrics** — i.e. the value the platform UI shows on the status badge.
+Per-individual-alert and per-individual-metric rows can disagree with
+this rollup (a vertex can have one CRITICAL alert and OK metrics; the
+rollup is CRITICAL).
+
+The rollup row's `data.alarm` block summarizes per-tier counts:
+`{ total, critical, major, minor, information }`. Useful for
+"how many alarms of each tier does this vertex carry" without
+reading every per-alert row.
+
+### Reading state for a specific vertex
+
+Match `states[].vertexId` against the vertex's `id`. Filter to the
+rolled-up severity by also checking
+`stateExternalId.alert === "sa://sa_status"`. Per-source severity is
+the inverse — exclude that alert id and look at the per-alert /
+per-metric rows.
+
+### Worked example: "what's the rolled-up status of these vertices?"
+
+```json
+{
+  "filter": { "op": "VERTEX", "externalId": ["<your-id-1>", "<your-id-2>"] },
+  "includeStatus": true,
+  "limit": 50,
+  "projection": "DETAILED"
+}
+```
+
+Response (sketch):
+
+```json
+{
+  "vertices": [{ "id": 5435, "externalId": "<your-id-1>", "attributes": { ... } }],
+  "states": [{
+    "vertexId": 5435,
+    "alertId": 774,
+    "stateExternalId": { "vertexId": 5435, "alert": "sa://sa_status" },
+    "status": 3,
+    "data": { "alarm": { "total": 1, "critical": 0, "major": 1, "minor": 0, "information": 0 } },
+    "startTime": 1768820848440,
+    "endTime": 1782097233000
+  }]
+}
+```
+
+`status: 3` ⇒ MAJOR; `data.alarm.major: 1` confirms the underlying
+alarm count.
+
+### Common patterns
+
+- **"Show me everything currently CRITICAL"** — the filter-server-side
+  path via `STATE` op is a no-op today. Use the two-query pattern
+  documented in `cookbooks/gotchas`: pull candidates with
+  `includeStatus: true`, client-filter to vertices whose rollup row
+  has `status === 4`, then issue a second query (e.g. TRAVERSE from
+  those externalIds) for downstream context.
+- **"What alarms does this vertex have right now?"** — issue a
+  `VERTEX(externalId=[...])` filter with `includeStatus: true` and
+  read every `states[]` row whose `vertexId` matches; skip the
+  `sa://sa_status` row to enumerate per-source alerts.
+- **"How long has this been bad?"** — `(endTime - startTime)` for the
+  most recent rollup row (or per-source row if you want the specific
+  alert's duration). A far-future `endTime` (e.g. `7505567987654`)
+  means the state is ongoing.
+
+## Recipe catalog
+
+Each recipe describes a goal in plain English and gives the minimum filter
+shape. Each links to a worked example shipped in the corpus —
+`corpus_get("queries", "<id>")` returns the full payload + per-op
+descriptions.
+
+### "Give me a sample of vertices to learn what's there"
+`corpus_get("queries", "01-discover-vertices")`
+
+```json
+{ "filter": { "op": "ALL" }, "limit": 20, "projection": "DETAILED" }
+```
+
+### "Find vertices of type X (or several types)"
+`corpus_get("queries", "02-discover-services")`
+
+```json
+{
+  "filter": {
+    "op": "ATTRIBUTE",
+    "expressions": [
+      { "name": "type", "values": ["HOST", "AGENT"], "operator": "IN" }
+    ]
+  },
+  "limit": 100, "projection": "DETAILED"
+}
+```
+
+### "Find vertices whose attribute matches a regex"
+`corpus_get("queries", "10-filter-attribute-matches")`
+
+```json
+{
+  "filter": {
+    "op": "ATTRIBUTE",
+    "expressions": [
+      { "name": "name", "values": [".*tixchange.*"],
+        "operator": "MATCHES", "caseInsensitive": true }
+    ]
+  },
+  "limit": 50, "projection": "DETAILED"
+}
+```
+
+### "Find vertices in a specific layer"
+`corpus_get("queries", "13-filter-layer")`
+
+```json
+{ "filter": { "op": "LAYER", "value": "ATC" }, "limit": 50, "projection": "DETAILED" }
+```
+
+### "Find vertices in any layer except a known set" (find unknown layers)
+`corpus_get("queries", "50-discover-custom-layers")`
+
+```json
+{
+  "filter": {
+    "op": "NOT",
+    "input": { "op": "LAYER",
+      "values": ["ATC", "INFRASTRUCTURE", "APM_INFRASTRUCTURE"] }
+  },
+  "limit": 200, "projection": "DETAILED"
+}
+```
+
+### "Multi-condition AND (type AND name pattern)"
+`corpus_get("queries", "11-filter-and-compose")`
+
+```json
+{
+  "filter": {
+    "op": "AND",
+    "input": [
+      { "op": "ATTRIBUTE", "expressions": [{ "name": "type",
+        "values": ["BUSINESSTRANSACTION"], "operator": "IN" }] },
+      { "op": "ATTRIBUTE", "expressions": [{ "name": "name",
+        "values": ["/checkout.shtml", "/signon.shtml"], "operator": "IN" }] }
+    ]
+  },
+  "limit": 20, "projection": "DETAILED"
+}
+```
+
+### "OR with a NOT (type X OR (type Y but not name matching ...))"
+`corpus_get("queries", "12-filter-or-not")`
+
+```json
+{
+  "filter": {
+    "op": "OR",
+    "input": [
+      { "op": "ATTRIBUTE", "expressions": [{ "name": "type",
+        "values": ["k8s_POD"], "operator": "IN" }] },
+      { "op": "AND", "input": [
+        { "op": "ATTRIBUTE", "expressions": [{ "name": "type",
+          "values": ["AGENT"], "operator": "IN" }] },
+        { "op": "NOT", "input": { "op": "ATTRIBUTE", "expressions": [
+          { "name": "name", "values": [".*Logstash.*"],
+            "operator": "MATCHES", "caseInsensitive": true } ] } }
+      ] }
+    ]
+  },
+  "limit": 50, "projection": "DETAILED"
+}
+```
+
+### "N-hop neighborhood from a starting set"
+`corpus_get("queries", "14-filter-traverse")`
+
+```json
+{
+  "filter": {
+    "op": "TRAVERSE",
+    "input": { "op": "ATTRIBUTE", "expressions": [{ "name": "type",
+      "values": ["k8s_CLUSTER"], "operator": "IN" }] },
+    "traverse": [{ "direction": "ANY", "repeat": 2 }],
+    "includeInput": true
+  },
+  "limit": 100, "projection": "DETAILED"
+}
+```
+
+### "Just the edges between a starting set and its neighborhood"
+`corpus_get("queries", "15-filter-take-vertices-edges")`
+
+```json
+{
+  "filter": {
+    "op": "TAKE_EDGES",
+    "input": {
+      "op": "TRAVERSE",
+      "input": { "op": "ATTRIBUTE", "expressions": [{ "name": "type",
+        "values": ["k8s_CLUSTER"], "operator": "IN" }] },
+      "traverse": [{ "direction": "ANY", "repeat": 2 }],
+      "includeInput": true
+    }
+  },
+  "limit": 100, "projection": "DETAILED"
+}
+```
+
+### "Project only the attributes I care about"
+`corpus_get("queries", "16-filter-projection")`
+
+```json
+{
+  "filter": { "op": "ATTRIBUTE", "expressions": [
+    { "name": "type", "values": ["k8s_POD"], "operator": "IN" } ] },
+  "limit": 30,
+  "projectionFilter": {
+    "attributes": ["name", "type", "hostname", "k8s_namespace", "k8s_status"]
+  }
+}
+```
+
+### "Reuse the same starting set in two places"
+`corpus_get("queries", "18-filter-variable-reuse")`
+
+```json
+{
+  "variables": [
+    { "name": "k8s_hosts", "input": { "op": "ATTRIBUTE", "expressions": [
+      { "name": "type", "values": ["HOST"], "operator": "IN" } ] } }
+  ],
+  "filter": {
+    "op": "TRAVERSE",
+    "input": { "op": "VARIABLE", "name": "k8s_hosts" },
+    "traverse": [{ "direction": "ANY", "repeat": 1 }],
+    "includeInput": true
+  },
+  "limit": 50, "projection": "DETAILED"
+}
+```
+
+### "Sort results and include status info"
+`corpus_get("queries", "19-filter-order-statefilter")`
+
+```json
+{
+  "filter": { "op": "ATTRIBUTE", "expressions": [
+    { "name": "type", "values": ["AGENT"], "operator": "IN" } ] },
+  "order": [{ "name": "name", "desc": false, "caseInsensitive": true }],
+  "includeStatus": true,
+  "limit": 20, "projection": "DETAILED"
+}
+```
+
+Response carries `states[]` alongside `vertices[]`. To read the
+rolled-up severity per vertex, find each vertex's `states[]` row
+where `stateExternalId.alert === "sa://sa_status"` and read
+`status` (0=UNKNOWN, 1=OK, 2=MINOR, 3=MAJOR, 4=CRITICAL). See the
+Status section above for the full shape and common patterns.
+
+### "Free-text Lucene query (where supported)"
+`corpus_get("queries", "17-filter-lucene")` — may return HTTP 400 on tenants
+without Lucene indexing.
+
+```json
+{ "filter": { "op": "LUCENE", "query": "name:Kubernetes*" },
+  "limit": 20, "projection": "DETAILED" }
+```
+
+## Authoring tips
+
+- Start broad (`ALL` with small `limit`) to discover vocabulary, then
+  progressively narrow with `ATTRIBUTE` and `LAYER`.
+- For "find X and its dependencies", build it as `TRAVERSE` over a base
+  `ATTRIBUTE` filter.
+- For "find edges between X and Y", build `TRAVERSE` then wrap in `TAKE_EDGES`.
+- When the same set is reused (e.g. base set and its neighborhood), declare
+  it in `variables[]` and reference via `{op: "VARIABLE", name}`.
+- Default `projection: "DETAILED"` if you do not yet know which attributes
+  you need; switch to `projectionFilter.attributes[]` once you do.
+- Verify sub-trees with `run_partial_query` (see `run-query-vs-run-partial.md`)
+  rather than authoring throwaway test queries.
+- See `gotchas.md` for the common `expressions` (array, not `expression`),
+  `input` (not `filters`), and layer-name pitfalls.