@dx-do/cli 5.2.49 → 5.2.50

package/dist-node/query-vs-analysis-separation-sag1ezcq.md

@@ -0,0 +1,97 @@
+---
+id: query-vs-analysis-separation
+title: Query vs analysis separation — produce data-fetching queries by default
+applies_to: all
+tags: [investigator, reference, default-behavior]
+related: [investigator-flow, nassql-quickstart]
+---
+
+# Query vs analysis separation
+
+## The default
+
+When a user asks an investigative question that involves a metric (CPU, memory, latency, error count, request rate, …), the investigator's default is:
+
+> **Produce a query that returns the raw data the user cares about. Don't apply thresholds / aggregations / anomaly detection in the query itself unless the user explicitly named one. Hand the data to the ui (for human exploration) or to an analyzer (for automated thresholding).**
+
+The same data shape supports many analyses; the same threshold collapses many shapes into a single boolean.
+
+## Why this matters — the load-bearing example
+
+User asks: *"Are there any hosts with high CPU right now?"*
+
+What "high" means is unspecified, and the right answer depends on the user's actual operational concern. Three common interpretations of *the same dataset*:
+
+| Interpretation | What you'd ask the data | Maps to |
+|---|---|---|
+| **Momentary spike** | `1-of-30 datapoints over 90%` in last hour | Usually noise; investigator alerts only the curious |
+| **Sustained pressure** | `all-of-30 datapoints over 70%` in last hour | Usually a real story; the load is constant |
+| **SLO-shaped** | `peak over 95% in last 6 hours` | An SLO question; involves time aggregation |
+
+A query that returns the raw CPU datapoints (one row per host per timestamp) supports all three. A query with `FILTER cpu > 90` baked in supports only the first, and **silently** — the user doesn't see "no hosts with sustained pressure", they see "no high-CPU hosts" and may walk away with the wrong conclusion.
+
+## When to threshold in the query anyway
+
+Three legitimate reasons:
+
+1. **The user explicitly named a threshold.** *"Hosts with sustained CPU over 80%"* → bake `FILTER cpu > 80` into the NASSQL pipeline (and confirm "sustained" = window aggregation).
+2. **Result-set size would be unmanageable.** A naive query against a million-host tenant might return millions of datapoints. First, add a sane `limit` (or sample). Only add a value-filter if `limit` isn't enough.
+3. **The threshold is part of the entity definition.** *"Hosts that are unhealthy"* might map to `state IN ['CRITICAL', 'WARNING']` — that's an entity-level filter, not a metric threshold; bake it in.
+
+## Pattern catalog
+
+### Pattern: "are there any X with high Y"
+
+Default shape: TAS query for X (entities), then NASSQL pipeline for Y values.
+
+```
+TAS:    type=HOST in <scope>     ← saved as queries/host-list-<scope>
+NASSQL: FROM_TOPOLOGY (host-list)
+        → JOIN_METADATA on cpu metrics
+        → FROM (datapoints, last 1h)
+        → KEEP host.name, ts, cpu
+```
+
+Hand off: *"Saved as `15-cpu-by-host`. Open the query in ui to see the raw values; threshold there or hand to the analyzer."*
+
+### Pattern: "top N noisy metric sources"
+
+NASSQL `FROM_METADATA` (definitions), GROUP, COUNT, TOP. Threshold-free; the "noisy" is just an ordering. Fine to apply `TOP n=10` because that's pagination, not analysis.
+
+### Pattern: "show me the trend"
+
+NASSQL `FROM` (datapoints) with WINDOW + MEAN (or PERCENTILE). The aggregation IS the user's intent — they want a trend, not raw datapoints. Bake it in. Include the time window. Don't threshold.
+
+### Pattern: "X right now"
+
+"Right now" → time window of last ~1h (the most-recent-N-minutes default). The user almost never wants a single point-in-time; they want recent data.
+
+### Pattern: "is there a problem with X"
+
+This is a *yes/no* question that wants analysis, not data. Two options:
+
+1. **Surface as data + ask** — *"Here's the recent data for X. Define what 'problem' means and I'll threshold."* Works when the user is exploring.
+2. **Hand to analyzer** — *"I'll save the data query and have the analyzer apply standard thresholds (sustained over 80%, sudden change > 30%, etc.) and give you a yes/no."* Works when the user wants a quick verdict.
+
+## Handoff phrasing templates
+
+After saving with `create_query`:
+
+> *"Saved as `<id>`. Open `http://localhost:<port>/queries/<id>` in ui to refine the time window or thresholds."*
+
+When passing to analyzer (forthcoming):
+
+> *"Saved as `<id>`. Handed to the analyzer with default thresholds for [CPU / memory / latency / etc.]. It'll come back with anomaly flags + a written summary."*
+
+## Anti-patterns
+
+- **Silent thresholding.** Hard-coding `cpu > 90` because "that's what high probably means" — the user doesn't see what fell out, may make wrong calls.
+- **Threshold as a default for `limit`.** Don't threshold to control result size; use `limit` (or `TOP`/`BOTTOM`).
+- **One-shot analysis when the user is exploring.** If the user might iterate on the query (refine the universe, change the time window), give them a query they can edit, not a paragraph of analysis.
+- **Skipping the data query and going straight to analysis.** Especially when the user asked an investigative-shaped question — the saved query is the artifact they can re-run, share, attach to dashboards. The analysis is ephemeral.
+
+## See also
+
+- `cookbooks/investigator-flow` — step 5 of the loop is this default.
+- `cookbooks/nassql-quickstart` — source-op selection (`FROM_TOPOLOGY` vs `FROM_METADATA` vs `FROM`).
+- `entities/universe`, `entities/service` — for the scoping side of the same investigative question.

package/dist-node/run-query-vs-run-partial-6138pc94.md

@@ -0,0 +1,80 @@
+---
+id: run-query-vs-run-partial
+title: run_query vs run_partial_query — when to use which
+applies_to: all
+tags: [reference, execution]
+related: [tas-quickstart, nassql-quickstart, gotchas]
+---
+
+# `run_query` vs `run_partial_query`
+
+Both execute against the bound tenant; both return the same `ExecuteResult` shape. The choice is about *what* you want to run — the full payload as authored, or a sub-portion for verification.
+
+## Short version
+
+| You want to… | Use |
+|---|---|
+| Execute the user-facing query as a whole | `run_query` |
+| Verify a sub-tree of TAS while debugging an authoring step | `run_partial_query(at: …)` |
+| Verify a NASSQL pipeline truncated at step N | `run_partial_query(upToStep: N)` |
+| Run an MM specifier alone | `run_query` (MM has no partial form) |
+
+`run_partial_query` is **always** an authoring/debug tool — never the final execution. When you save a query (`create_query`), the saved payload is what `run_query` would execute, not a partial.
+
+## `run_query` — full execution
+
+```
+run_query({type: "tas" | "nassql" | "metadata", payload: <full payload>})
+```
+
+- Executes the payload as-is against the bound tenant.
+- Returns the `ExecuteResult` envelope — `result` (the data), `error`, `validation`, `executionTimeMs`.
+- Validates with the canonical Zod schema (`@dx-do/client/datastore/<type>`) before sending. Validation errors come back as `validation`, not `error`.
+- **Don't pass an empty payload.** `{}` parses as valid but executes against the entire topology / metric catalog (often megabytes of result). See `gotchas.md` "run_query — empty payload silently dumps the whole topology" — the server-side preflight refuses three unbounded shapes, but don't lean on it.
+
+## `run_partial_query` — sub-tree / step-up-to execution
+
+Two surfaces, one endpoint, two argument shapes:
+
+### TAS: `at` (path array)
+
+```
+run_partial_query({type: "tas", payload: <full payload>, at: ["filter", "input", 1]})
+```
+
+- `at` is a JSONPath array (NOT a string). Walks into the payload starting from the root; the addressed sub-filter is extracted and wrapped in an envelope.
+- The wrapped envelope **inherits** `limit`, `projection`, `time`, `universe`, `order`, `offset` from the parent payload — so "run just this branch" sees the same projection/limit the user has at the top.
+- Use when you want to verify a single op deep in a recursive TAS filter tree without authoring a separate test query.
+
+### NASSQL: `upToStep` (integer, 0-based)
+
+```
+run_partial_query({type: "nassql", payload: <full payload>, upToStep: 2})
+```
+
+- `upToStep` truncates `payload.query` to the first N+1 steps.
+- Top-level `limit` and `authorizationView` are preserved.
+- Use to inspect the intermediate tabular shape after each pipeline stage — invaluable when chaining FROM_X + JOIN_Y + GROUP + AGG + KEEP.
+
+### Metadata: not supported
+
+There's no partial form for MM — a single specifier has no obvious slice point. Don't pass `at` or `upToStep` for `type: "metadata"`; the server returns a structured error.
+
+## When the user asks "show me the data" — full or partial?
+
+If the user is iterating on authoring (mid-conversation, just discussed an op), `run_partial_query` is often the cheaper move — verify the sub-tree, then commit to a full run when you've sharpened it.
+
+If the user is asking for the actual answer (saved query, end-of-conversation handoff), `run_query` against the full payload is what they want.
+
+## Common mistakes
+
+- **Passing `at` as a string** — must be an array of `string | number` segments. `"$.filter.input[1]"` is the human-readable rendering; the wire format is `["filter", "input", 1]`.
+- **Passing both `at` and `upToStep`** — exactly one. The other must be omitted (not null). Server rejects.
+- **Passing `at` with a path that doesn't address a TAS filter** — e.g. pointing at a number or array element that isn't itself a filter. Server returns a structured error.
+- **Using `run_partial_query` as the final execution** — it's a debug op. Save with `create_query` and `run_query` for the canonical run.
+
+## See also
+
+- `gotchas.md` — empty-payload trap on `run_query`.
+- `cookbooks/tas-quickstart` — TAS payload shape; sub-tree iteration with `run_partial_query`.
+- `cookbooks/nassql-quickstart` — NASSQL pipeline shape + step-up-to truncation.

package/dist-node/service-5pz5nhzf.md

@@ -0,0 +1,133 @@
+---
+id: service
+title: Service — the secondary scoping axis (often hierarchical)
+synonyms: [saService, business service]
+related_entities: [universe, dxi_service, host]
+related_cookbooks: [service-hierarchies, universes-and-scopes, investigator-flow]
+tags: [scoping, core, organizational-axis, hierarchy]
+---
+
+# Service
+
+## What it is
+
+A **Service** in DXO2 is a named grouping of related entities (hosts, agents, business transactions, k8s resources, …) that represents a unit of business or operational meaning — usually a customer-facing application, a back-end system, or an internal capability. Services are the secondary scoping axis after universes; on tenants where universes don't segregate the data finely enough, services are how users carve the topology.
+
+Services are **vertex `type: 'saService'`** in the topology graph. The full attributes:
+
+| Attribute | What it carries |
+|---|---|
+| `name` | Human-readable service name (what `discovery_services` returns and what users say). |
+| `state` | `ACTIVE` (vs deprecated/inactive variants). |
+| `root_service` | Array of root service names — represents the **service's path back to root services**, i.e. the hierarchy. |
+| `situationsIncludeChildServices` | Per-service flag — whether situations bubble through the hierarchy. |
+| `tags`, `location`, `source` | Free-form taxonomy + provenance (e.g. `source: 'OI'` for services from Operational Intelligence). |
+| `metrics[]` | Built-in service metrics: `service_risk`, `service_health`, `service_availability`. |
+| `externalId` | Shape: `SA:<cohort-uuid>:<service-uuid>`. |
+
+## Hierarchies — the load-bearing nuance
+
+Services are **frequently hierarchical**: a *Mobile Service* might have *EMEA Mobile* / *NA Mobile* / *APJ Mobile* as subservices, each of which might further decompose. The `root_service` attribute is a service's path back to its roots; subservice relationships are encoded as graph edges in the topology.
+
+The hierarchy is a **DAG, not a tree** — a single child service can have multiple parents. The DXO2 model has no notion of edge-typed relationships (no "depends-on" vs "rolls-up-to" distinction); every parent-child link is the same kind. Be aware: descending into a parent that has shared children pulls **all** of those children, including subtrees of the *other* parents that share them.
+
+When a user names a service in an investigative question — *"hosts for Mobile Service"* — the answer is materially different depending on whether they mean:
+
+- **JUST the directly-named service** (`Mobile Service` only) — typically far fewer entities.
+- **The named service AND all subservices** (`Mobile Service` + `EMEA Mobile` + `NA Mobile` + `APJ Mobile` + …) — typically much larger.
+
+Both interpretations are common. Don't guess; ask.
+
+### How to enumerate
+
+From an MCP-driven agent, call `discovery_service_hierarchy` (front-door, always loaded). It returns a DAG view in one call: `{totalServices, rootCount, edgeCount, multiParentChildren[], roots[], byName: {<lowercase-name>: {displayName, parents[], children[], tags[], leaf}}}`.
+
+- Keys in `byName` are case-folded — lowercase any service name the user mentions before looking it up.
+- Walk `children` to know what subscoping pulls in.
+- Walk `parents` to know what broader scope a service sits inside.
+- Check `multiParentChildren` for the warning case above.
+
+For the bare flat list (just service names, no hierarchy), `discovery_services` is cheaper. Both share an upstream call but project differently.
+
+## The shortcut: the `serviceNames` attribute on entities
+
+Every entity that the platform has assigned to one or more services carries a **`serviceNames`** attribute — an array of the service names it belongs to (e.g. `["NA_Billing", "NA_Provisioning", "APPService_NA_Provisioning"]`). It's a denormalized index that the platform keeps current automatically: typically populated **within ~1 minute** of an entity being created, and **within ~2 minutes** of a new service being created.
+
+For "what services does X belong to" questions, this is the cheapest possible move — far cheaper than running `discovery_service_hierarchy` and joining membership client-side.
+
+**Important: the attribute is not in the default projection.** Pass `includeServices: true` on the TAS query envelope and the `serviceNames` field will appear in `vertex.attributes`. With `BRIEF`/`DETAILED` projection alone (no `includeServices`), the field is silently absent — agents who skip the flag will conclude "this tenant doesn't track service membership", which is wrong.
+
+```json
+{
+  "filter": { "op": "ATTRIBUTE", "expressions": [{ "name": "name", "values": ["host-001"], "operator": "EQ" }] },
+  "limit": 5,
+  "projection": "DETAILED",
+  "includeServices": true
+}
+```
+
+Some entity types reliably carry it (DXI_SERVICE, AGENT, BUSINESSTRANSACTION, k8s workloads, HOSTs that participate in services). A few legitimately have `serviceNames: null` (CONNECTOR, PRODUCT, ACN_CONFIG — these are platform-internal records that aren't service members). Both `null` and a non-empty array are normal; missing-from-the-payload-entirely usually means `includeServices` was not set.
+
+The companion knob is `includeStatus: true` — same idea but for the `state`/`status` attribute, which is similarly omitted by default. Worth setting alongside `includeServices` when you want a one-shot "what is this entity, what services does it belong to, and is it healthy" snapshot.
+
+## The SERVICE filter (the load-bearing schema)
+
+TAS has a dedicated `SERVICE` op for service-scoped queries:
+
+```json
+{
+  "op": "SERVICE",
+  "values": ["Mobile Service"],
+  "includeServiceHierarchy": false,
+  "excludeSubServices": false
+}
+```
+
+| Knob | Default | Meaning |
+|---|---|---|
+| `values: string[]` | (required) | Service names to scope to. Multiple names = OR. |
+| `includeServiceHierarchy: boolean` | `false` | Returns the service's hierarchy info alongside the matched entities. |
+| `excludeSubServices: boolean` | `false` | When `true`, restricts to entities directly attached to the named service(s) only. When `false` or omitted, includes entities of all subservices too. |
+
+The user's mental model and the schema knob have inverted polarity on subservices — a user saying *"include subservices"* maps to `excludeSubServices: false` (the default, not an opt-in). Be explicit about what you set, especially when the user said *"just the Mobile Service"* — that's `excludeSubServices: true`.
+
+`includeServiceHierarchy` is independent and orthogonal — it controls whether the response carries hierarchy metadata, not what's matched.
+
+## Investigator pattern
+
+For any investigative question naming a service:
+
+1. **Confirm the service exists**: it's in `discovery_services` (returns flat names).
+2. **Confirm the user's intent**: just the named service, or the service + its subservices? *"Did you want JUST the named service, or also its subservices? On this tenant `Mobile Service` has [N] subservices."* (You'll need a TAS query to count subservices — `discovery_services` is flat.)
+3. **Author with explicit knobs**: set `excludeSubServices` to whatever the user confirmed. Don't rely on default behavior — different consumers of the schema have different defaults.
+
+For the **inverse direction** ("what services does this entity belong to") — read the entity's `serviceNames` attribute (with `includeServices: true`). Don't traverse, don't query the service hierarchy, don't enumerate. The attribute is the canonical answer.
+
+## Relationship to universes
+
+Services and universes are both scoping axes, frequently overlapping in tenant naming conventions. On many tenants:
+
+- A service of name X and a universe with label X coexist (one created from the other, or vice versa).
+- `O2UniverseService.getServiceNameToUniverseLabelMap()` is the lookup — when a user names "X" check this map to detect which axis they probably mean. If both exist, ask.
+
+See `entities/universe`.
+
+## Common synonyms / mistakes
+
+- **"saService"** — internal vertex type name; the user-facing word is "service" or "business service."
+- **"Service Hierarchy"** — refers to the parent-child structure, not the `includeServiceHierarchy` boolean.
+- **`DXI_SERVICE`** — *different concept*. APM-internal service abstraction (lives in APM_INFRASTRUCTURE layer); see `entities/dxi_service`. A user saying "service" almost never means DXI_SERVICE.
+- **Services with parent-of-multiple-roots** — a service can have multiple root_service entries; queries that assume a single-rooted tree will miss content.
+- **Defaulting on `excludeSubServices`** — schema-level default behavior may differ from what a user expects. Be explicit.
+
+## Useful CLI commands
+
+- `dx-do o2-universe services universeViewId=<id>` — services associated with an O2 universe.
+- (No flat `dx-do service list` today; enumerate via `discovery_services` or a TAS query for `type: 'saService'`.)
+
+## See also
+
+- `entities/universe` — primary scoping axis; often interacts with services.
+- `entities/dxi_service` — APM-internal service abstraction (commonly confused with `service`).
+- `cookbooks/service-hierarchies` — query patterns for navigating parent-child + subservice traversal.
+- `cookbooks/investigator-flow` — the broader scope-clarification checklist.

package/dist-node/service-hierarchies-87a4ynpj.md

@@ -0,0 +1,178 @@
+---
+id: service-hierarchies
+title: Service hierarchies — navigating parent-child + the subservice-traversal decision
+applies_to: all
+tags: [investigator, scoping, reference]
+related: [investigator-flow, universes-and-scopes]
+---
+
+# Service hierarchies
+
+## Why this matters
+
+When a user names a service in an investigative question (*"hosts for Mobile Service"*), they could mean two materially different things:
+
+- **Just the named service** — entities directly attached to `Mobile Service` only.
+- **The named service + all subservices** — entities attached to `Mobile Service` + `EMEA Mobile` + `NA Mobile` + `APJ Mobile` + every level beneath.
+
+Both are common and the result sets differ by an order of magnitude. The schema has explicit knobs for this — DON'T let it default silently. See `entities/service` for the SERVICE filter schema.
+
+## Gotcha — use the `SERVICE` op, not `type=saService` ATTRIBUTE
+
+A `saService` vertex *exists* in the topology, but on most tenants filtering by
+
+```json
+{ "op": "ATTRIBUTE",
+  "expressions": [
+    { "name": "type", "operator": "IN", "values": ["saService"] },
+    { "name": "name", "operator": "IN", "values": ["Mobile Service"] }
+  ] }
+```
+
+returns **zero matches**. Service-membership semantics — "the vertices that ARE this service" — are reachable only through the dedicated `SERVICE` op:
+
+```json
+{ "op": "SERVICE",
+  "values": ["Mobile Service"],
+  "excludeSubServices": false }
+```
+
+Use that as the input to your `TRAVERSE` (or AND it with a `type` ATTRIBUTE expression to narrow). This is the single most common first-attempt failure when a new author tries to scope a topology query to a named service — burns one wasted iteration before pivoting. Reach for `SERVICE` first.
+
+## The SERVICE filter (recap)
+
+```json
+{
+  "op": "SERVICE",
+  "values": ["Mobile Service"],
+  "includeServiceHierarchy": false,
+  "excludeSubServices": false
+}
+```
+
+| Knob | Default | When `true` | When `false`/omitted |
+|---|---|---|---|
+| `includeServiceHierarchy` | `false` | Include hierarchy metadata in the response | Don't include hierarchy metadata |
+| `excludeSubServices` | `false` | Restrict to entities directly attached to the named service(s) | **Include subservices' entities too** |
+
+**Polarity gotcha**: the user saying *"include subservices"* maps to `excludeSubServices: false` — i.e. the *default*. The user saying *"just this service"* maps to the explicit `excludeSubServices: true`. Always set the knob explicitly so future readers (and your future self) don't have to remember the polarity.
+
+## Asking the user the right way
+
+Single targeted question:
+
+> *"Did you want JUST `Mobile Service`, or `Mobile Service` and its subservices? On this tenant `Mobile Service` has [N] subservices."*
+
+To get the [N], run a TAS query and count — no flat "list subservices of X" tool today (`discovery_services` returns flat names, no parents). Two common shapes:
+
+```json
+// shape A: rely on saService.root_service to find descendants
+{ "op": "ATTRIBUTE",
+  "expressions": [
+    { "name": "type", "operator": "IN", "values": ["saService"] },
+    { "name": "root_service", "operator": "MATCHES", "values": ["Mobile Service"] }
+  ]
+}
+```
+
+```json
+// shape B: TRAVERSE from the service vertex through its hierarchy edges
+{ "op": "TRAVERSE",
+  "input": {
+    "op": "ATTRIBUTE",
+    "expressions": [
+      { "name": "type", "operator": "IN", "values": ["saService"] },
+      { "name": "name", "operator": "IN", "values": ["Mobile Service"] }
+    ]
+  },
+  "traverse": [
+    { "vertex": { "op": "ATTRIBUTE", "expressions": [{"name": "type", "operator": "IN", "values": ["saService"]}] },
+      "edge": { "op": "ALL" },
+      "direction": "FORWARD"
+    }
+  ]
+}
+```
+
+The `root_service` shape is cheaper (no traverse); the TRAVERSE shape gives you the actual graph and works across multi-rooted services.
+
+## Authoring the user's query
+
+Once the user has confirmed scope, weave the SERVICE filter into the user's actual intent:
+
+### "Hosts for Mobile Service (just it)"
+
+```json
+{
+  "filter": {
+    "op": "AND",
+    "input": [
+      { "op": "ATTRIBUTE",
+        "expressions": [
+          { "name": "type", "operator": "IN", "values": ["HOST"] }
+        ]
+      },
+      { "op": "SERVICE",
+        "values": ["Mobile Service"],
+        "excludeSubServices": true
+      }
+    ]
+  },
+  "limit": 100,
+  "projection": "DETAILED"
+}
+```
+
+### "Hosts for Mobile Service and all subservices"
+
+```json
+{
+  "filter": {
+    "op": "AND",
+    "input": [
+      { "op": "ATTRIBUTE",
+        "expressions": [
+          { "name": "type", "operator": "IN", "values": ["HOST"] }
+        ]
+      },
+      { "op": "SERVICE",
+        "values": ["Mobile Service"],
+        "excludeSubServices": false
+      }
+    ]
+  },
+  "limit": 100,
+  "projection": "DETAILED"
+}
+```
+
+Same shape; the only thing the user's choice changed is `excludeSubServices`.
+
+## Multiple services
+
+`SERVICE.values` is an array — multiple services = OR. Useful when the user names siblings:
+
+```json
+{ "op": "SERVICE",
+  "values": ["EMEA Mobile", "NA Mobile", "APJ Mobile"],
+  "excludeSubServices": false
+}
+```
+
+If the user names a parent + asks to exclude one subservice, that's an `AND(SERVICE(parent, includeSubs), NOT(SERVICE(excluded, includeSubs)))` shape.
+
+## Service vs universe
+
+If the named "service" is also the name of a universe (common — see `cookbooks/universes-and-scopes`), the universe-scoped query is usually preferable: it carries a richer, curated filter than the bare SERVICE op. Cross-check the universe list (e.g. `dx-do o2-universe list`) for a label that matches the service name.
+
+## Anti-patterns
+
+- **Defaulting to `excludeSubServices: undefined`** — relies on schema-level default (which is `false` = include subs) but reads as "I didn't think about it." Set the knob explicitly.
+- **Confusing `includeServiceHierarchy` with subservice-inclusion** — the names are similar; `includeServiceHierarchy` is about response metadata, not what's matched.
+- **Using TAS `TRAVERSE` when `SERVICE` will do** — the SERVICE op is purpose-built for this; reach for TRAVERSE only when you need the actual graph relationships in the result.
+
+## See also
+
+- `entities/service` — full SERVICE filter schema + the `saService` vertex shape.
+- `cookbooks/universes-and-scopes` — universe-side of scope clarification (often interacts).
+- `cookbooks/investigator-flow` — the broader investigator decision tree.

package/dist-node/service-k4f5mkbq.md

@@ -0,0 +1,51 @@
+---
+id: service
+title: service — five things at once
+aliases: [services, svc]
+category: scoping
+related: [application, dxi_service, host]
+tags: [overloaded, disambiguation, core]
+---
+
+# service
+
+"Service" is one of the most overloaded terms in the DXO2 domain. When a user says "service X", they could mean any of these:
+
+| Candidate | Description | Vertex type |
+|---|---|---|
+| **DXO2 service** | Organizational construct on the platform — a hierarchical group of entities, often created to model business or operational ownership. The default meaning. | (no specific vertex type — services are not vertices, they're an organizational axis) |
+| **DXI_SERVICE** | APM-internal service abstraction. Aggregates an agent's traffic. Rarely the user's first interest. | `DXI_SERVICE` |
+| **k8s_SERVICE** | Kubernetes Service — a network-routing object that exposes a set of pods. Common in cloud-native shops. | `k8s_SERVICE` |
+| **AWS_ECS_FARGATE_SERVICE** | ECS Fargate service definition. AWS-specific. | `AWS_ECS_FARGATE_SERVICE` |
+| **OS / system service** | Operating-system service (systemd, Windows Service). Rarely modeled as a vertex unless the customer has a specific integration. | (varies) |
+| **business service** | A user-narrative service ("the checkout service") that may correspond to a DXO2 service, an APM application, a k8s deployment, or none of those. | (none — a label) |
+
+## Disambiguation rule
+
+**Default to DXO2 service** unless the user's phrasing or context suggests otherwise. Specifically:
+
+1. If the name they used **matches a DXO2 service**, use that. (Use `discovery_search_by_name` or `discovery_services`.)
+2. If it doesn't match a DXO2 service but **matches an entity name with a more specific type** (`k8s_SERVICE` named `payments-svc`, an OS service, etc.), use that.
+3. If it matches multiple kinds, **show the user both** and ask, or run the query both ways.
+
+## How users phrase it
+
+- "the X service" → almost always DXO2 service first; Kubernetes-shop second.
+- "this k8s service" / "the cluster IP service" → `k8s_SERVICE`.
+- "the application service" / "the APM service" → `DXI_SERVICE` (rare).
+- "the systemd service" / "the windows service" → OS service.
+- "the business service" → business label, may not have a vertex.
+
+## Quick path for "what DXO2 services does X belong to"
+
+Every entity carries a `serviceNames` array attribute that the platform keeps current automatically (populated within ~1 min of entity creation, ~2 min of service creation). It's the cheapest way to answer "what services does X belong to" — no traversal, no hierarchy lookup.
+
+The attribute is hidden behind a TAS envelope flag: pass `includeServices: true` and `serviceNames` shows up in `vertex.attributes`. Without it, the field is silently absent — leading the agent to think the tenant has no service membership. See `entities/service` for the canonical pattern.
+
+## See also
+
+- `entities/service` — the DXO2 service.
+- `entities/dxi_service` — APM-internal service.
+- `entities/k8s_pod_and_container` (k8s_SERVICE catalog row) — k8s service.
+- `lexicon/application` — closely-related overload.
+- `cookbooks/service-hierarchies` — DXO2 service mechanics.

package/dist-node/servlet_or_frontend-1kjcb7ar.md

@@ -0,0 +1,76 @@
+---
+id: servlet_or_frontend
+title: Servlet / Frontend / Spring service — the APM "entry point" cluster
+related_entities: [business_transaction, agent, database]
+related_cookbooks: [investigator-flow]
+tags: [apm, runtime-specific]
+---
+
+# Servlet / Frontend / Spring service — entry-point cluster
+
+This doc covers three closely-related vertex types that all describe **where a request enters an APM-instrumented app**:
+
+- `SERVLET` — Java Servlet endpoint (Java APM agent).
+- `GENERICFRONTEND` — generic frontend record (HTTP / gRPC / message handler) emitted when the agent recognizes traffic but the framework is not specifically known.
+- `SPRINGSERVICE` — Spring-framework service endpoint (Java APM agent, Spring instrumentation).
+
+`EXPRESSJS` (Node.js) and `BROWSER_APPLICATION` (RUM) are siblings of this cluster; they have their own catalog rows.
+
+## When to reach for which
+
+| If the user asks about… | Filter type to… |
+|---|---|
+| "the API endpoints for X" | `GENERICFRONTEND` (most-general label) |
+| "the servlets in the Java app" | `SERVLET` |
+| "the Spring controllers" | `SPRINGSERVICE` |
+| "this route in our Node app" | `EXPRESSJS` (sibling) |
+| "the browser-side performance" | `BROWSER_APPLICATION` (sibling) |
+
+When unclear, query all three with `ATTRIBUTE` `type IN [SERVLET, GENERICFRONTEND, SPRINGSERVICE]` and let the user disambiguate from the result.
+
+## What lives where
+
+All three live in the **ATC** layer and share most of these attributes:
+
+- `name` — endpoint label (path / class / method).
+- `applicationName` — APM app the endpoint belongs to.
+- `agent`, `agentDomain` — the producing agent.
+- `processedBy`, `product` — provenance.
+- `hostname` — the machine the agent runs on.
+
+Type-specific detail attributes:
+
+- `SERVLET`: `servletClassname`, `servletMethod`, sometimes `Build Date` / `Build Number`.
+- `SPRINGSERVICE`: `ServiceName`, `Technology`.
+- `GENERICFRONTEND`: `Experience`, `IsExperience`, `serviceId` (when wired into a DXO2 service), `deployment.environment.name`.
+
+## How metrics are reported
+
+Per-endpoint response time, throughput, errors. Path shape under the agent:
+
+- `Servlets|<servlet>:<metric>`
+- `Frontends|<frontend>:<metric>`
+- `<spring-namespace>|<service>:<metric>`
+
+The path roots vary slightly by agent version and language SDK — when uncertain, use MM `discovery_metrics` filtered to the relevant `metric.source` and inspect the actual paths.
+
+## Relationship to BUSINESSTRANSACTION
+
+A BT often passes through one or more of these endpoints. The BT is the logical end-to-end name; servlets/frontends are *touchpoints*. Common patterns:
+
+- A BT named `Login` has `agent-monitors` edges to a `SERVLET` named `LoginServlet.doPost` and a `SPRINGSERVICE` named `AuthController.login` — the same logical work, two technology views.
+- The same BT name can show up under multiple agents if the JVM is replicated; the BT vertex is one identity, the touchpoint vertices are per-agent.
+
+When a user asks about "performance of the login flow", the right starting point is the BT (logical identity); when they ask about "the endpoint that's slow", start at the SERVLET / SPRINGSERVICE / GENERICFRONTEND level.
+
+## Common synonyms / mistakes
+
+- "Endpoint" / "API" / "route" — usually `GENERICFRONTEND` but ambiguous with k8s_SERVICE, especially in cloud-native shops.
+- "The login servlet" → `SERVLET`. "The login transaction" → `BUSINESSTRANSACTION`. They're related but distinct vertex types.
+- Spring users sometimes say "service" when they mean `SPRINGSERVICE` — this is yet another collision with DXO2 `service`. See `lexicon/service`.
+
+## See also
+
+- `entities/business_transaction` — the logical end-to-end view.
+- `entities/agent` — the producing collector.
+- `cookbooks/investigator-flow` — the BT vs touchpoint disambiguation.

package/dist-node/src-apm-mfnsq6vw.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="#fff" stroke="none">
+  <path d="M12 3 L21 21 L3 21 Z" fill-opacity="0.25" stroke="#fff" stroke-width="1.6" stroke-linejoin="round"/>
+  <text x="12" y="17" text-anchor="middle" font-family="Helvetica,Arial" font-size="8" font-weight="700" fill="#fff">A</text>
+</svg>

package/dist-node/src-axa-nn28yqmj.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="#fff" stroke="none">
+  <circle cx="12" cy="12" r="9" fill-opacity="0.25" stroke="#fff" stroke-width="1.6"/>
+  <text x="12" y="16" text-anchor="middle" font-family="Helvetica,Arial" font-size="8" font-weight="700" fill="#fff">X</text>
+</svg>

package/dist-node/src-dxim-fv7ne4qa.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="#fff" stroke="none">
+  <rect x="3" y="3" width="18" height="18" rx="3" fill-opacity="0.25" stroke="#fff" stroke-width="1.6"/>
+  <text x="12" y="16" text-anchor="middle" font-family="Helvetica,Arial" font-size="8" font-weight="700" fill="#fff">D</text>
+</svg>