@dx-do/cli 5.2.48 → 5.2.50

package/dist-node/tas-quickstart-wgcvwffc.md

@@ -0,0 +1,138 @@
+---
+id: tas-quickstart
+title: TAS quickstart — author a topology query
+applies_to: tas
+tags: [getting-started, authoring]
+related: [gotchas, discovery-flow]
+---
+
+# TAS quickstart
+
+TAS = topology graph queries. Returns `{ vertices, edges }` shaped by a single
+recursive **filter tree**. Every node is `{ "op": "<NAME>", ... }` — a
+discriminated union on `op`. Most ops can wrap an `input` filter; leaf ops
+(`ALL`, `LAYER`, `LUCENE`, `VARIABLE`) cannot.
+
+## Schema landmines (READ FIRST)
+
+The five things that bite first-time TAS authors:
+
+1. **There is no `EQ` op.** Equality goes through `ATTRIBUTE` with `operator: IN` (one or more values), or through `LUCENE` with `field:value` syntax. Reaching for `{op:"EQ"}` is the most common day-1 mistake.
+2. **`AND` / `OR` cannot be empty.** `{op:"AND", input:[]}` returns HTTP 400. Always at least one child. Schema validation rejects empty arrays before the request reaches the server.
+3. **`NOT` takes a single `input`, not an array.** `{op:"NOT", input: <filter>}` — NOT `input: [<filter>]`. The latter parses but is rejected.
+4. **`{op:"ALL"}` without `limit` returns the entire topology.** Often megabytes; sometimes refused. Always pair `ALL` with a sensible `limit` (5–100 for sampling).
+5. **Field name is `input`, not `filters`/`children`.** The recursive child slot is always called `input` (singular for NOT, array for AND/OR/TRAVERSE-input).
+
+Two more, schema-shape:
+
+6. **`LUCENE` is tenant-config-dependent** — not enabled on every tenant. If you're authoring a query that should work everywhere, prefer `ATTRIBUTE` + `MATCHES` instead.
+7. **`LAYER` filter has both `value` (singular string) and `values` (array)** — pick the one that matches the count of layers you want to match. Both work; mixing them is invalid.
+
+## The envelope
+
+```jsonish
+{
+  "filter": { ... },           // root filter tree (required in practice)
+  "limit": 20,                 // cap returned vertices
+  "projection": "DETAILED",    // attribute breadth: DETAILED | BRIEF | NO_TYPE
+  "includeServices": true,     // surface the `serviceNames` attribute on each vertex
+  "includeStatus": true,       // adds a `states[]` array to the response (NOT an attribute on each vertex — see the Status section in tas-cookbook)
+  "time": 1700000000000,       // optional point-in-time epoch ms
+  "order": [...],              // optional sort
+  "universe": { ... },         // optional filter applied first
+  "postFilter": { ... }        // optional filter applied after
+}
+```
+
+Default `projection` is implementation-defined; explicitly set `DETAILED`
+when you want all attributes back.
+
+**`includeServices: true` is the cheapest way to learn what services an entity belongs to** — every entity carries a `serviceNames: string[]` attribute that the platform pre-populates (typically within ~1 min of entity creation, ~2 min of new-service creation). Without this flag, the field is silently absent and you'll wrongly conclude the entity has no service membership. Pair with `includeStatus: true` for an identity + membership + health snapshot in one query.
+
+**`includeStatus: true` adds a `states[]` array to the response, separate from `vertices[]` / `edges[]`.** It does NOT add a `status` attribute to each vertex — read severity by joining `states[].vertexId` against `vertices[].id`. Each state row is per-`(vertex, alert OR metric)`; a single vertex typically has multiple state rows. The rolled-up severity (what the platform UI shows) lives on the row whose `stateExternalId.alert === "sa://sa_status"`. Numeric `status` values: `0=UNKNOWN`, `1=OK`, `2=MINOR`, `3=MAJOR`, `4=CRITICAL`. Full response shape, common patterns, and the "show me everything currently CRITICAL" workaround in `cookbooks/tas-cookbook` ("Status — `includeStatus` and the `states[]` response array" section).
+
+## The 8 ops you'll use most
+
+| Op | Purpose | Has `input`? |
+|---|---|---|
+| `ALL` | Match every vertex. Use with `limit` for sampling. | No |
+| `ATTRIBUTE` | Match by attribute expressions. The workhorse. | Yes |
+| `LAYER` | Restrict to one or more layers. | No |
+| `LUCENE` | Free-text Lucene query. | No |
+| `AND` / `OR` | Compose. Each takes `input: TasFilter[]`. **Cannot be empty.** | Yes (children) |
+| `NOT` | Negate. Takes `input: TasFilter`. | Yes |
+| `TRAVERSE` | Walk edges. Takes a `traverse: [...]` array. | Yes |
+
+## Discovery first, then author
+
+Before authoring anything specific, call:
+
+- `discovery_layers` → list of available layers (e.g. `INFRASTRUCTURE`, `CONNECTOR`, `AGENT`)
+- `discovery_attributes(layer)` → attribute names known on that layer
+- `discovery_attribute_values(layer, attribute)` → distinct values for IN-style filters
+
+Without this, you'll guess attribute names that don't exist on this tenant.
+
+**Authoring an `ATTRIBUTE` filter (or any other op)?** Call `query_schema` with the op first to confirm the canonical field names — `{type: "tas", op: "ATTRIBUTE"}` returns a 4 KB summary listing the 5 properties (op, input, expressions, layer, mode) with descriptions. Cheaper than a guess + server-validation retry, and prevents the textbook `_type` vs `type` mistake. The summary is inline-readable; reach for `full: true` only when nested validation detail (enum values past 6 entries, recursive sub-shapes) actually matters.
+
+## Pattern: layer + attribute filter
+
+```json
+{
+  "filter": {
+    "op": "AND",
+    "input": [
+      { "op": "LAYER", "values": ["INFRASTRUCTURE"] },
+      { "op": "ATTRIBUTE", "expressions": [
+        { "name": "type", "operator": "IN", "values": ["HOST"] }
+      ]}
+    ]
+  },
+  "limit": 20,
+  "projection": "DETAILED"
+}
+```
+
+## Pattern: traverse from one set to its neighbours
+
+```json
+{
+  "filter": {
+    "op": "TRAVERSE",
+    "input": { "op": "ATTRIBUTE", "expressions": [...] },
+    "traverse": [
+      { "vertex": { "op": "ALL" }, "edge": { "op": "ALL" }, "direction": "FORWARD" }
+    ]
+  }
+}
+```
+
+## ATTRIBUTE expression details
+
+```json
+{
+  "name": "hostname",          // attribute name
+  "operator": "MATCHES",       // IN | NOT_IN | MATCHES | NOT_MATCHES | GE | GT | LE | LT
+  "values": ["api-*"],         // values array (IN/NOT_IN take arrays of values)
+  "comparator": "LEXICAL",     // LEXICAL | NUMBER | DATETIME (changes value typing)
+  "caseInsensitive": false
+}
+```
+
+For `comparator: "NUMBER"`, `values` are JSON numbers, not strings.
+
+## Iteration
+
+Once a draft is in place, use `run_partial_query` with `at: ["filter", "input", N]`
+to verify a sub-tree without authoring a separate test query. The wrapped
+envelope inherits `limit`, `projection`, `time`, `universe`, `order`, `offset`
+from the parent payload — so "run just this branch" sees what would be seen
+at the top.
+
+## See also
+
+- `tas-cookbook.md` — full op reference, recipe catalog, composition patterns
+- `gotchas.md` — FROM_TOPOLOGY's restricted querySpecifier, ATTRIBUTE.layer constraint
+- `discovery-flow.md` — full discovery pattern
+- `run-query-vs-run-partial.md` — when to use which execution mode
+- Live examples: `corpus_list("queries", {type: "tas"})` — fetch full payloads with `corpus_get("queries", "<id>")`. Good starting points: `01-discover-vertices`, `02-discover-services`, `10-filter-attribute-matches`, `11-filter-and-compose`.

package/dist-node/time-format-0595g01j.md

@@ -0,0 +1,41 @@
+## Let's just say it out loud: time formatting from the command line sucks. 
+
+But there are some easy consistent options for many time range commands including
+
+* metric data
+* agent get-trace-summaries
+
+The absolutely easiest way, IMO is `ISO Durations`. 
+
+The commands above take
+
+* endTime + relativeStartTime
+* startTime + relativeEndTime
+
+## Let's start with examples:
+
+### Time period ends 1day+3 hours ago, and begins 2 hours before that.
+```
+endTime=P1DT3H relativeStartDuration=PT2H
+```
+
+### Time period starts 1week+7hours ago and ends 30 minutes after that.
+```
+startTime=P1WT3H relativeEndDuration=PT30M
+```
+
+* If you specify a partial for endTime or startTime, that is relative to NOW.
+* relativeStartDuration/relativeEndDuration is relative to the endTime/startTime. 
+* There is no need to specify a negative
+
+* P = REQUIRED START INDICATOR FOR ISO8601 Partial
+* Y = years
+* M = months
+* W = weeks
+* D = days
+* T = delineator between dates and times, necessary to disambiguate between months and minutes
+* H = hours
+* M = minutes
+* S = seconds
+
+

package/dist-node/toggles.pbd-9wscbmng.template

@@ -0,0 +1,2 @@
+TurnOn: ${flagName}
+

package/dist-node/type-host-agbhmn6v.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="#fff" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+  <rect x="3" y="5" width="18" height="11" rx="1.5"/>
+  <line x1="3" y1="13" x2="21" y2="13"/>
+  <line x1="8" y1="20" x2="16" y2="20"/>
+  <line x1="12" y1="16" x2="12" y2="20"/>
+</svg>

package/dist-node/type-metric-p9b90bpx.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="#fff" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round">
+  <polyline points="3 17 9 11 13 14 21 6"/>
+  <polyline points="15 6 21 6 21 12"/>
+</svg>

package/dist-node/type-service-k7f1x71k.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="#fff" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+  <circle cx="12" cy="12" r="3.2"/>
+  <path d="M12 4v3M12 17v3M4 12h3M17 12h3M6.3 6.3l2.1 2.1M15.6 15.6l2.1 2.1M6.3 17.7l2.1-2.1M15.6 8.4l2.1-2.1"/>
+</svg>

package/dist-node/ui-0b5grqrg.md

@@ -0,0 +1,113 @@
+# `dx-do ui start` — visual query builder
+
+Start a local Fastify + Angular server that lets you author and run **TAS / NASSQL / Metrics-Metadata** queries against a bound DXO2 tenant in your browser. The same server hosts the MCP endpoint at `/mcp` (see `dx-do help agentic-mcp` for the MCP surface).
+
+> **Experimental.** `ui start` is currently gated. To run it, either:
+>   - pass `--enable-experimental-commands` on the dx-do invocation
+>   - export `DXDO_ENABLE_EXPERIMENTAL_COMMANDS=true` in your environment
+>
+> Both forms work the same way; the env var is the easiest if you'll be running ui repeatedly.
+
+## Usage
+
+```
+DXDO_ENABLE_EXPERIMENTAL_COMMANDS=true dx-do ui start [config=<alias>]
+              [port=<n>]
+              [open=true|false]
+              [mcp=true|false]
+              [module.<id>=off|read|write ...]
+              [dev=true|false]
+              [mcpOnly=true|false]
+```
+
+All flags are optional. With no flags the server picks a free port, opens your browser, prompts you to pick a tenant config, and starts the MCP at `/mcp`.
+
+## What you get
+
+* **Visual editors** for the three datastore query types — TAS topology queries, NASSQL metric pipelines, and Metrics-Metadata specifiers. Each editor renders the payload tree with op-specific controls and discovery-driven dropdowns.
+* **Tenant picker** (the *configuration alias* pill in the top bar). Switch tenants mid-session without restarting; everything re-binds.
+* **Save to disk** under `~/.dxdo/queries/<alias>/` as a *file triplet* (see below). Saved queries appear in the left rail and can be edited / re-run later.
+* **Discovery panel** — auto-loaded layer / service / metric / attribute lists for the bound tenant, cached per session. Refresh with the refresh button when the tenant changes underneath you.
+* **Catalog browser** — read-only access to the universal worked-example queries and cookbooks shipped with `@dx-do/corpus`. Useful when you want a starting point for authoring.
+* **MCP endpoint at `/mcp`** for AI agents — same 17-tool default surface as `dx-do agentic mcp`, gated by the same module flags. Use `mcp=false` to skip MCP entirely.
+
+## Basic workflow
+
+1. **Start**: `dx-do ui start config=demo-prod` (browser opens automatically).
+2. **Pick a query type** in the left rail or open an existing one.
+3. **Edit** in the visual tree, in the JSON5 tab, or both (they round-trip).
+4. **Run** with the ▶ button. Use the per-op ▶ buttons for partial runs (TAS sub-filters; NASSQL up-to-step).
+5. **Save** with **⌘S** / **Ctrl+S**. The file triplet is written to disk and the left-rail entry refreshes.
+
+## Query persistence — the file triplet
+
+Each saved query is **three sibling files** under `~/.dxdo/queries/<alias>/`:
+
+| File | Contents |
+|---|---|
+| `<id>.<type>.data-store.json5` | Payload + path-keyed inline descriptions persisted as JSON5 `/* */` block comments. |
+| `<id>.<type>.data-store-tmd.json` | Test metadata: short description, tags, `expectedFailure`, `skip`. |
+| `<id>.<type>.md` | Companion markdown — long-form intent, expected output, gotchas. |
+
+`<type>` is `tas`, `nassql`, or `metadata`. The id includes a numeric prefix (e.g. `01-discover-vertices`) which orders the left rail. Files round-trip: hand-edit the JSON5 in your editor and the SPA picks up the changes on focus.
+
+## Inline descriptions — three tiers
+
+Every op in your query can carry an inline note. The notes persist as JSON5 block comments and round-trip through the visual / JSON5 tabs without flapping.
+
+* **Top-level** — file-leading comment, describes the whole query. Above the visual tree.
+* **Per-op** — above each op's header (in the visual tree). Bound to a JSONPath like `$.filter` or `$.query[2]`.
+* **Per-record** — above each AttributeExpression / specifier inside an op (e.g. `$.filter.expressions[0]`).
+
+These descriptions are how you ground future agents reading your saved query via MCP — leave reasoning here and the next agent gets it for free via `get_query`.
+
+## Right pane — Source / Results / Debug
+
+The right pane is tabbed:
+
+* **Source** — pretty-printed JSON of the parsed payload. The default tab.
+* **Results** — full-run output. Auto-activates when ▶ produces a result.
+* **Debug** — partial-run output. Auto-activates when a per-op ▶ runs. Shows a scope breadcrumb (e.g. `$.filter.input[1]` for TAS, `steps 1–3` for NASSQL).
+
+Tabs report `<n>ms / stale / error`. Editing the payload flips Results and Debug to **stale** until you re-run.
+
+## Flags
+
+| Flag | Default | Effect |
+|---|---|---|
+| `config=<alias>` | (prompts in UI) | Pre-bind to `~/.dxdo/<alias>.dxo2.config.json`. |
+| `port=<n>` | free port (4321 in `dev=true`) | Bind to a specific port. |
+| `open=false` | `true` | Suppress the auto-open browser. |
+| `mcpOnly=true` | `false` | Don't open browser; surface the MCP URL in the startup log. |
+| `mcp=false` | `true` | Skip registering `/mcp` on the HTTP server entirely. |
+| `module.<id>=off\|read\|write` | `ui=write`, others `read` | Per-module MCP permissions. See `dx-do help agentic-mcp` for the module corpus. |
+| `dev=true` | `false` | Bind port 4321; enable CORS for `http://localhost:4200` (the Angular dev server). |
+
+## MCP module flags
+
+The same `module.<id>=...` flags accepted by `dx-do agentic mcp` work here — they control the HTTP `/mcp` endpoint instead of stdio. Examples:
+
+```sh
+# Lock external agents to read-only on user queries even though the SPA can still write.
+dx-do ui start config=demo-prod module.ui=read
+
+# Disable the MCP entirely (SPA only).
+dx-do ui start config=demo-prod mcp=false
+```
+
+The startup log line shows the resolved per-module levels so you can confirm at a glance.
+
+## Stopping
+
+**Ctrl+C** terminates the server. The Fastify shutdown hook closes open connections cleanly.
+
+## Where things live on disk
+
+* **Tenant configs** — `~/.dxdo/<alias>.dxo2.config.json`
+* **Saved queries** — `~/.dxdo/queries/<alias>/[<folder>/]<id>.<type>.<ext>`
+* **Catalog (read-only)** — bundled inside `@dx-do/corpus` (no user-side files)
+
+## Related
+
+* `dx-do help agentic-mcp` — same MCP surface, stdio transport, no SPA.
+* `dx-do help configuration` — how `~/.dxdo/<alias>.dxo2.config.json` files are loaded and validated.

package/dist-node/universe-b9nhf325.md

@@ -0,0 +1,47 @@
+---
+id: universe
+title: universe — APM Universe vs O2 Universe
+aliases: [universes, view, scope]
+category: scoping
+related: [service, application]
+tags: [overloaded, core]
+---
+
+# universe
+
+DXO2 has **two flavors of universe**, and the difference matters for which API to call and what data to expect:
+
+- **APM Universe** — ApmUniverseService territory. Tends to hold telemetry sources (the agents that produce metrics) and their associated entities. Created and managed by the APM side of the platform.
+- **O2 Universe** (a.k.a. Platform Universe) — O2UniverseService territory. A catch-all for organization, especially data integrated from non-APM sources (NetOps, log analytics, custom integrations). Created and managed on the O2/platform side.
+
+Both are **scoping mechanisms** — like a workspace for a slice of tenant data.
+
+## Why this matters
+
+- The two flavors have **different APIs and different vertex shapes**. If you query the wrong service, you'll get an empty list and not realize it.
+- Some system-default universes exist on every tenant and are usually NOT what the user wants when they say "in universe X" — e.g. `UNsaasProd`, `VIEWALL`. Exclude these from offered choices unless the user explicitly references them.
+
+## Disambiguation rule
+
+1. If the user names a universe by id or label, search **both** APM and O2 universes.
+2. The MCP tool `discovery_universes` returns the union (in two distinguishable lists).
+3. Default to the matching universe; if both have a universe of that name, prefer the user-created one and confirm.
+
+## When to scope by universe vs by service
+
+- **Universe** = primary scope for *what data exists* (a slice of the tenant).
+- **Service** = secondary scope for *organizational/business meaning* on top of a universe.
+
+When a user says "the production environment", that's usually a universe (or a service inside a universe). "The X application" usually maps to a service or DXO2 application within whatever universe makes sense.
+
+## How users phrase it
+
+- "in the APM universe" / "the metric universe" → APM Universe.
+- "the platform universe" / "everything we ingest" → O2 Universe.
+- "the production view" / "the prod scope" → either; needs disambiguation.
+
+## See also
+
+- `cookbooks/universes-and-scopes` — full mechanics.
+- `lexicon/service` — the next-axis-down.
+- `entities/universe` — entity-shape detail.

package/dist-node/universe-fzpwzvxr.md

@@ -0,0 +1,91 @@
+---
+id: universe
+title: Universe — the primary scoping mechanism for tenant data
+synonyms: [view, scope, segregation]
+related_entities: [service, dxi_service]
+related_cookbooks: [universes-and-scopes, investigator-flow]
+tags: [scoping, core, organizational-axis]
+---
+
+# Universe
+
+## What it is
+
+A **Universe** is the primary scoping mechanism in DXO2 — a named, access-controlled view over a slice of the tenant's topology and metrics. When a user asks an investigative question on a typical tenant, *the first ambiguity to resolve is which universe(s) they mean*. Universes are how customers segregate environments (prod vs staging), regions (NA vs EMEA vs APJ), product lines, lines of business, or any other organizational axis they care about.
+
+There are **two distinct kinds of universes** in DXO2 with materially different shapes — confusing them silently is one of the bigger ways an investigator can hand back a wrong answer:
+
+- **APM Universe** (legacy-shaped, APM-flavoured)
+- **O2 Universe** (modern, "Platform" / O2-flavoured)
+
+Both kinds can coexist on the same tenant. Many tenants have only one kind; some have both.
+
+## APM Universes
+
+The original universe concept, scoped to APM (Application Performance Management) data.
+
+**Shape**: each universe has a single `viewId` + `label`, and a fixed `views` object with three slots:
+
+- `views.tas` — a TAS filter (in legacy form: `{ vertices, items, joins }`) defining which entities are visible.
+- `views.nass` — a NASS filter built from EXACT-name and REGEX specifiers.
+- `views.mm` — a metric-metadata filter (just a `string[]`).
+
+Plus per-view permissions, attributes (counts like `TAS_AGENT_COUNT` / `TAS_ATC_COUNT` / `NASS_COUNT`), and an `access` block of users + groups with role-based permissions.
+
+**How to enumerate**: from an MCP-driven agent, call `discovery_universes` (returns both kinds in one call as `{apm, o2}`, in the user-facing `name`-first shape). From the CLI: `dx-do apm-universe list`. Programmatically: `ApmUniverseService.retrieveAllUniverses()`.
+
+**APM-flavoured signals**: legacy TAS filter shape (`legacy.vertices`, `legacy.items`, `legacy.joins`); presence of `attributes.TAS_AGENT_COUNT`; user/group permissions include `nass`/`tas`/`mm` keys.
+
+## O2 Universes
+
+The newer Platform / O2-style universe. Same conceptual role (named, access-controlled view) but a flexible multi-view shape:
+
+**Shape**: each universe has `viewId` + `label`/`description` (in `attributes`), and a `views: O2UniverseView[]` array — each entry is one of:
+
+- `{ type: 'tas', filter: { filter: TASFilter, includeMetricFilter?, projection?, projectionFilter? }, permissions }`
+- `{ type: 'nass', filter: { filter: TASFilter, serviceFilter? }, permissions }`
+- `{ type: 'es', filter: unknown, permissions }`
+
+A single O2 universe can carry zero, one, or many of each view type. The TAS filter inside is the *modern* TAS schema (op-discriminated tree), not the legacy form. Per-view permissions are independent.
+
+**How to enumerate**: same as above — `discovery_universes` returns both kinds in one call. CLI: `dx-do o2-universe list`. Programmatically: `O2UniverseService.retrieveAllUniverses()`.
+
+**O2-flavoured signals**: modern TAS filter shape (`op: 'AND'`, `op: 'ATTRIBUTE'`, etc.); `viewId` + `attributes.label`; multiple views in an array; the universe-to-service relationship surfaced via `getServiceNameToUniverseLabelMap()` (see "Universes and services" below).
+
+## Investigative checklist (the load-bearing pattern)
+
+When a user asks an entity- or metric-shaped investigative question (*"are there any hosts with high CPU right now?"*, *"show me the top services by error rate"*, *"what alarms fired overnight?"*), **before authoring any query**:
+
+1. **Enumerate**: how many APM universes? how many O2 universes? how many top-level services?
+2. **Surface**: tell the user what you see, in a single sentence. *"On this tenant I see 3 APM universes (Prod, Staging, NA-EMEA-Combined), 7 O2 universes (mostly per-region), and 142 services."*
+3. **Ask**: did they mean *all* of it, a specific universe, a specific service?
+4. **Default carefully**: if the user replies "all hosts", confirm whether they mean "literally all" (cross-universe) or "all in the universe I'm currently looking at" — the answer is materially different on a tenant with multiple universes.
+
+This is one or two extra round-trips. It's worth it; the alternative is producing a query against the wrong scope and burning the user's time on a result they have to re-do.
+
+## Universes and services
+
+On many O2 tenants, a universe maps to a *service* (or a service maps to a universe — the relationship is bidirectional). `O2UniverseService.getServiceNameToUniverseLabelMap()` and `getUniverseLabelToServiceNameMap()` exist for exactly this lookup. When a user names a service in their question (*"the Mobile Service"*), check whether there's a universe of the same name first — if so, the universe-scoped query is usually what they want.
+
+See `entities/service` for the service axis (which has its own hierarchy and subservice-traversal nuances).
+
+## Common synonyms / mistakes
+
+- **"View" / "scope"** — colloquial synonyms. Worth confirming which kind of universe.
+- **"Universe" without qualifier** — on a multi-universe-kind tenant, ALWAYS clarify APM vs O2. They have different filter shapes, different access models, and different downstream behavior.
+- **Confusing universe with service** — common, especially because they often share names. A *universe* is the view-defining filter; a *service* is one of the things that view typically scopes around. They're orthogonal axes that frequently collapse together in tenant naming.
+- **Treating `attributes.label` and `viewId` interchangeably** — the user reads the label; the API takes the viewId. Always look up the viewId via the universe list, don't hardcode it. The `discovery_universes` MCP tool surfaces these as `name` (label) and `id` (viewId) — speak to users in `name` always, reach for `id` only when assembling an outgoing API call.
+
+## Useful CLI commands
+
+- `dx-do apm-universe list` — APM universes on the bound tenant.
+- `dx-do o2-universe list` — O2 universes on the bound tenant.
+- `dx-do o2-universe services` — service↔universe mapping.
+- `dx-do apm-universe detail` / `o2-universe export` — full universe shape including filters.
+
+## See also
+
+- `entities/service` — the secondary scoping axis (often interacts with universes).
+- `entities/dxi_service` — APM-internal service abstraction (different from the service axis).
+- `cookbooks/universes-and-scopes` — the canonical investigator pattern for universe-aware querying.
+- `cookbooks/investigator-flow` — the broader scope-clarification checklist.

package/dist-node/universes-and-scopes-1cb9pfk7.md

@@ -0,0 +1,105 @@
+---
+id: universes-and-scopes
+title: Universes and scopes — APM vs O2 disambiguation
+applies_to: all
+tags: [investigator, scoping, reference]
+related: [investigator-flow, service-hierarchies]
+---
+
+# Universes and scopes
+
+## Why this matters
+
+On any tenant with more than one universe, "show me the hosts" is ambiguous. The user almost always has a specific universe in mind but doesn't realize they're asking against an undefined scope. Authoring a query against the wrong scope is silently wrong — the user gets answers that look real but represent the wrong slice.
+
+This cookbook covers the universe-disambiguation half of the scope-clarification step (`cookbooks/investigator-flow` step 1).
+
+## Two kinds of universes
+
+DXO2 has **APM Universes** and **O2 Universes** (Platform). Both can coexist on a tenant. They have different shapes, different APIs, and different downstream behavior. See `entities/universe` for the schema-level details.
+
+| | APM Universe | O2 Universe |
+|---|---|---|
+| Shape | Fixed `views: { tas, nass, mm }` | Flexible `views[]` (TAS / NASS / ES, multi-instance) |
+| TAS filter form | Legacy (`vertices`, `items`, `joins`) | Modern op-discriminated tree |
+| NASS filter form | EXACT/REGEX specifiers | TAS filter + optional ServiceFilter |
+| Enumerate (CLI) | `dx-do apm-universe list` | `dx-do o2-universe list` |
+| Service↔universe map | (per-universe; check the universe's `views` for service references) | Provided by the O2 universe metadata; surfaced via `discovery_universes` once available |
+
+There is no shared "universe list" MCP tool today — `discovery_universes` is forthcoming. Until then, shell out to the CLI commands above.
+
+## How to detect "which kind does the user mean"
+
+When the user mentions a universe name without qualifying it:
+
+1. **Check both lists.** A name might be unique to APM, unique to O2, or duplicated across both (rare but possible).
+2. **If unique to one** — proceed with that universe; mention which kind in your handoff sentence so the user can correct you if wrong.
+3. **If duplicated** — ask. *"There's an APM universe and an O2 universe both called 'Prod' — which one?"*
+4. **If neither matches** — ask if they're naming a service instead. Universes and services often have overlapping names (see "Universe-service collisions" below).
+
+When the user uses APM-flavoured language (*"agents in this universe"*, *"the APM Prod universe"*, *"agent counts"*) — bias toward APM Universe.
+
+When the user uses O2-flavoured language (*"the O2 view"*, *"the platform universe"*, *"NASS view permissions"*) — bias toward O2 Universe.
+
+## Universe-service collisions
+
+On many O2-style tenants, **a universe and a service share the same name** because the universe was created from the service's filter (or vice versa). When the user says *"the Mobile Service"*:
+
+- Is there a universe labelled "Mobile Service"? Cross-check the O2 universe list (`dx-do o2-universe list`) for a matching label.
+- If yes, the universe-scoped query is usually the right move — universes already encode the relevant filter.
+- If no, fall back to a service-scoped TAS query (see `cookbooks/service-hierarchies`).
+
+If the user has both a universe and a service of the same name, that's an artifact of how their tenant was set up; the universe usually has the more curated definition.
+
+## Authoring queries scoped to a universe
+
+A universe is a collection of *filter definitions* — to scope a TAS or NASSQL query to a universe, you replicate the universe's filter into your query.
+
+### From an O2 Universe
+
+For an O2 Universe with a TAS view, retrieve the universe (e.g. via `dx-do o2-universe get <id>`), pull the TAS view's filter, and AND it with the user's intent filter:
+
+```jsonish
+{
+  "filter": {
+    "op": "AND",
+    "input": [
+      <universe's TAS filter>,
+      <the user's intent filter>
+    ]
+  },
+  "limit": 100,
+  "projection": "DETAILED"
+}
+```
+
+For a NASS view, the universe carries `{ filter: TASFilter, serviceFilter?: ServiceFilter }` — for NASSQL queries, use the TAS filter as the input to `FROM_TOPOLOGY`.
+
+### From an APM Universe
+
+The APM Universe carries a *legacy*-shaped TAS filter (`legacy.vertices`, `legacy.items`, `legacy.joins`). The DXO2 server typically accepts both forms; if the canonical TAS schema (op-discriminated) doesn't accept the legacy shape directly, you may need to translate it. A simpler practical approach: use the universe's `nass` filter (EXACT-name specifiers) as the input to `FROM_TOPOLOGY` in a NASSQL query when possible.
+
+## System-default universes — exclude when inferring org shape
+
+Two universe IDs are tenant-creation defaults (not user-modeled scopes). They appear on every tenant; their presence tells you nothing about how the customer organizes their data:
+
+- **`UNsaasProd`** — the APM default universe (often labelled "Your Applications").
+- **`VIEWALL`** — the O2 default universe (often labelled "All Access").
+
+When inferring the *organizational shape* of a tenant for an investigator's scope-clarification step, **filter these out** of the universe list. The user-created universes that remain are the ones that reflect the customer's intent (per-region, per-product, per-environment, etc.). If after filtering there are zero or one user-created universes, the tenant is universe-light — fall back on the service axis for org structure.
+
+(For *executing* a query against a universe, the system defaults are still valid scopes; they just don't help you understand "how is this tenant organized.")
+
+## Investigator-flow integration
+
+In step 1 of `cookbooks/investigator-flow`, surface the user-created universe count alongside the service count: *"On this tenant: 11 APM universes / 6 O2 universes (excluding the system defaults `UNsaasProd` and `VIEWALL`), 106 services across 24 root branches."* Then state the org-shape inference and ask one targeted question: *"Services look fully populated here, so I'd lean on the service axis — were you thinking of a specific service, or all of them?"*
+
+If the user answers with a name that maps to a universe: scope the query to that universe.
+
+If the user answers with a name that maps to a service: use `cookbooks/service-hierarchies` for the SERVICE filter pattern (preferred when both axes are populated — see `cookbooks/investigator-flow` § "Scope-axis precedence").
+
+## See also
+
+- `entities/universe` — the schema-level reference.
+- `cookbooks/service-hierarchies` — the service-axis half of scope clarification.
+- `cookbooks/investigator-flow` — the broader investigator decision tree.

package/dist-node/vertex_entity_node-mm3yp9d0.md

@@ -0,0 +1,31 @@
+---
+id: vertex_entity_node
+title: vertex / entity / node — same thing, three names
+aliases: [topology node, graph node]
+category: topology
+related: []
+tags: [overloaded]
+---
+
+# vertex / entity / node
+
+Three words for the same DXO2 concept: a record in the topology graph that represents a thing the platform tracks (a host, a transaction, a service, a database, …).
+
+- **vertex** — the most precise term. Used in TAS APIs (`vertices`, `vertex.attr.type`).
+- **entity** — used in cookbooks, docs, conversation. The corpus catalog section is `entities/`.
+- **node** — used in Kubernetes shops to mean the worker node, but in graph contexts can mean the same as vertex. Avoid in DXO2 docs; prefer "vertex" for TAS and "entity" for narrative.
+
+## Conventions
+
+- TAS query authoring → "vertex" (matches the API).
+- Entity catalog browsing / cookbook prose → "entity".
+- Talking to a Kubernetes user → "node" almost always means `k8s_NODE`. Don't conflate.
+
+## Edges
+
+The companion concept — relationships between vertices — is just **edge** (no overload). Edges have attributes including `semantic` (`contains`, `agent-monitors`, `runs_on`, etc.). Some edges have no `semantic` value at all; see `cookbooks/entity-relationships`.
+
+## See also
+
+- `entities/` — the catalog section.
+- `cookbooks/entity-relationships` — edge taxonomy.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dx-do/cli",
-  "version": "5.2.48",
+  "version": "5.2.50",
   "description": "CLI execution of DX Operational Observability operations and triage",
   "author": "Ki Alam",
   "logo": {