@dx-do/cli 5.2.48 → 5.2.50

package/dist-node/SKILL-1xn7r9nt.md

@@ -0,0 +1,104 @@
+---
+description: Use when the user asks investigative questions about a DXO2 tenant — hosts, services, agents, alarms, metrics, traces, topology shape, "what's slow / noisy / broken / down". Teaches the investigator decision tree (scope-clarify → discovery → corpus grounding → query author → UI handoff) for the dx-do-query MCP. Always reach for this skill before authoring TAS / NASSQL / Metrics-Metadata queries against the bound tenant.
+---
+
+# investigator (dx-do investigate)
+
+You're acting as a DXO2 (DX Operational Observability) investigator. The user wants an answer about their tenant's data — hosts, services, alarms, metrics, traces, topology shape — and the dx-do-query MCP is your tool.
+
+The full grounding lives in the corpus (`corpus_sections` to enumerate, `corpus_get` to fetch). This skill is the **decision tree** that tells you *which* corpus content to load and *when*. Don't restate corpus content here; reference it.
+
+## The investigator loop
+
+Always in this order:
+
+1. **Scope clarification** — universes? services? subservice traversal? time window? threshold semantics? Identify the load-bearing ambiguities for the question shape.
+2. **Empirical grounding** — call `discovery_capabilities`, then enumerate universes / services / layers as the question demands. Surface counts in a single sentence to the user.
+3. **Targeted question** — ask one or two clarifying questions on the load-bearing ambiguities. Don't guess; don't ask five.
+4. **Pick query type** — TAS for graph (entities, neighbors, paths) / NASSQL for tabular (group, count, trend, aggregate) / metric-metadata is a *source* in NASSQL not a separate language.
+5. **Author + verify** — start from a corpus example via `corpus_get('queries', '<id>')` if one matches. Verify with `run_partial_query` for sub-trees, `run_query` for the whole.
+6. **Save + hand off** — `create_query` to save, then surface the saved id and the ui URL ("open in ui as `<id>`") OR offer the analyzer subagent.
+
+The full version of step 1–6 lives in `corpus_get('cookbooks', 'investigator-flow')`. **Read it on the first investigative turn of any session**, then reference inline.
+
+## Three load-bearing distinctions
+
+These collapse silently into wrong answers. Internalize them:
+
+- **Universe ≠ Service ≠ DXI_SERVICE.** Two kinds of universes (APM + O2). Services are the secondary scoping axis (often hierarchical). DXI_SERVICE is APM-internal and rarely what the user means by "service." See `corpus_get('entities', 'universe')`, `'service'`, `'dxi_service'`.
+- **`FROM_METADATA` vs `FROM`.** Metadata = metric *definitions*; FROM = metric *datapoints* over time. Same metric, totally different rows. See `corpus_get('cookbooks', 'nassql-quickstart')` source-op decision table at the top.
+- **Query vs analysis.** Default to producing a query that returns *raw data*, not analysis. Let the user / ui / analyzer threshold. *"1-of-30 datapoints over 90 vs all-of-30 over 70"* — same dataset, different shapes; a thresholded query silently picks one. See `corpus_get('cookbooks', 'query-vs-analysis-separation')`.
+
+## Schema landmines (memorize)
+
+The five gotchas that bite first-time TAS authors:
+
+- **No `EQ` op** — use `ATTRIBUTE` with `operator: IN` or `LUCENE`.
+- **`AND` / `OR` cannot be empty** — always at least one child; HTTP 400 otherwise.
+- **`NOT` takes a single `input`, not an array** — `input: <filter>`, NOT `input: [<filter>]`.
+- **Empty `run_query` payload** is server-refused — pair `op:"ALL"` with `limit ≤ 100`. The server-side guard's error message points at `corpus_get('queries', '01-discover-vertices')`.
+- **`LUCENE` is tenant-config-dependent** — call `discovery_capabilities` once per session to know.
+
+NASSQL parallels:
+
+- **`KEEP` must be the last op.**
+- **`TOP` / `BOTTOM` use `n`, not `count`.**
+- **`vertex.attr.<name>` is the FROM_TOPOLOGY column convention.**
+
+Full list in `corpus_get('cookbooks', 'tas-quickstart')` and `'nassql-quickstart'` (top of each).
+
+## Tool defaults
+
+When the user asks an investigative question, your default first calls:
+
+```
+corpus_get('cookbooks', 'investigator-flow')   ← only on first turn of a session
+discovery_capabilities                            ← only on first turn of a session
+```
+
+Then for any specific question:
+
+```
+corpus_list('entities', {})                      ← if conceptual ambiguity
+corpus_get('entities', '<name>')                 ← when an entity is named
+discovery_layers / discovery_services /           ← live tenant grounding
+  discovery_attributes / discovery_attribute_values
+corpus_list('queries', {type: '<type>'})         ← worked-example patterns
+corpus_get('queries', '<id>')                    ← study an example before authoring
+run_partial_query                                  ← verify sub-trees while authoring
+run_query                                          ← final execution (against narrowed scope)
+create_query                                      ← save, then hand off
+```
+
+**Don't** guess attribute names, layer names, service names, or vertex types. Always discover. The cost is one tool call; the reward is correctness.
+
+## Handoff phrasing
+
+When the query is built and saved:
+
+> *"Saved as `<id>`. Open in the ui to refine the time window or thresholds: `http://localhost:<port>/queries/<id>` (the ui port is in the agentic-mcp launch logs / `dx-do ui start` log). If you'd like a thresholded analysis right now, I can hand it to the analyzer subagent."*
+
+When more clarification is needed before authoring:
+
+> *"Quick scope check first — [empirical observation: N universes, M services]. Did you want [option A] or [option B]? [Optionally one more clarifying question on threshold / time window if load-bearing.]"*
+
+## Anti-patterns
+
+- Skipping scope clarification → wrong-scope query → wrong answer that looks right.
+- Five clarifying questions instead of one or two → the user gives up.
+- Hard-coding tenant-specific names → query rots when the tenant evolves.
+- Defaulting to thresholded queries → silently lossy.
+- Treating "service" as `DXI_SERVICE` by default → wrong scoping axis.
+- Long-form analysis paragraph instead of a saved query → ephemeral; user can't iterate or share.
+- `run_partial_query` as the FINAL execution → it's a debug op; save with `create_query` and `run_query` for the canonical answer.
+
+## See also
+
+- `corpus_get('cookbooks', 'investigator-flow')` — the full 7-step loop.
+- `corpus_get('cookbooks', 'universes-and-scopes')` — universe disambiguation.
+- `corpus_get('cookbooks', 'service-hierarchies')` — service `excludeSubServices` polarity + traversal.
+- `corpus_get('cookbooks', 'query-vs-analysis-separation')` — the data-vs-analysis default.
+- `corpus_get('cookbooks', 'discovery-flow')` — discovery hierarchy (capabilities → entities → live → metadata).
+- `corpus_get('cookbooks', 'gotchas')` — empirical surprises across all of the above.
+- `corpus_get('cookbooks', 'run-query-vs-run-partial')` — full vs partial execution choice.
+- `corpus_get('cookbooks', 'tas-quickstart')` / `'nassql-quickstart'` / `'mm-quickstart'` — schema-level details when authoring.

package/dist-node/agent-25q752kd.md

@@ -0,0 +1,55 @@
+---
+id: agent
+title: AGENT — a telemetry collector
+layer: APM_INFRASTRUCTURE
+synonyms: [collector, monitor]
+related_entities: [host, agent_connection, dxi_service]
+related_cookbooks: [tas-quickstart]
+tags: [apm, telemetry]
+---
+
+# AGENT
+
+## What it is
+
+An AGENT vertex represents a software collector that reports telemetry — APM agents, infrastructure agents, Kubernetes agents, MySQL agents, etc. AGENTs are usually associated with a HOST and a PRODUCT.
+
+## Where it lives
+
+`type=AGENT` vertices live in the **APM_INFRASTRUCTURE** layer. This is the layer to query when you want to know "what's collecting telemetry from where".
+
+**If your goal is "find HOSTs that have APM agents"** — start from `INFRASTRUCTURE.HOST` with `SourceProduct=APM`, *not* from APM_INFRASTRUCTURE. See `entities/host`.
+
+## Common uses
+
+- **Agent inventory** — list all agents per host, per product, per cluster.
+- **Coverage analysis** — which hosts have which agent types?
+- **Health filtering** — combine with `agentIsConnected`, `agentMode`, `agentConnectedTime` attributes.
+
+## Useful attributes
+
+- `agentName` / `name` — display name (often `<cluster>|<host>|<product>` shape).
+- `agentType` — kind of agent (e.g. `Kubernetes Agent`, `Infrastructure Agent`).
+- `agentIsConnected` — boolean, current connectivity state.
+- `agentConnectedTime` — last connection epoch ms.
+- `SystemFQHostName` / `SystemSimpleHostName` — host this agent runs on.
+- `SourceProduct` — usually `APM`, but agents can be associated with other products.
+
+## Common synonyms / mistakes
+
+- "monitor", "collector" — colloquially synonymous with AGENT.
+- **"the agent for host X"** — multiple agents can run on one host (Kubernetes + Infrastructure + product-specific). The relationship is many-to-one, not one-to-one.
+- "is this host monitored?" — usually means "does this host have at least one connected AGENT?". Use the `agent` attribute on HOST as a shortcut, or TRAVERSE from HOST to AGENT.
+
+## Related entities
+
+- **HOST** (in INFRASTRUCTURE) — typically the machine this agent runs on. TRAVERSE in either direction.
+- **AGENT_CONNECTION** (same layer) — represents an agent's connection lifecycle.
+- **DXI_SERVICE** (same layer) — APM service abstraction the agent feeds metrics into.
+
+## See also
+
+- `entities/host` — for the host-side companion.
+- `cookbooks/tas-quickstart` — the layer + ATTRIBUTE pattern.
+- `queries/12-filter-or-not` — example query that filters AGENTs by name pattern.
+- `queries/19-filter-order-statefilter` — agents sorted with status included.

package/dist-node/agent_connection_and_status-0dq7zkpc.md

@@ -0,0 +1,62 @@
+---
+id: agent_connection_and_status
+title: AGENT_CONNECTION / AGENT_STATUS — agent lifecycle records
+layer: APM_INFRASTRUCTURE
+related_entities: [agent, host, dxi_service]
+related_cookbooks: []
+tags: [apm, telemetry, platform-internal]
+---
+
+# AGENT_CONNECTION and AGENT_STATUS
+
+## What they are
+
+These two platform-internal vertex types describe the **state and history** of an agent's relationship to the platform:
+
+- `AGENT_CONNECTION` — a connection lifecycle record. Holds the connection's identity, the agent it represents, and the backend node the agent connects through. Useful for "when did this agent last connect" / "is this agent connected right now".
+- `AGENT_STATUS` — current health/state of a deployed agent. Holds attributes like `agentHostname`, `agentProcess`, and the platform's view of the agent's running state.
+
+Most tenants have one `AGENT_CONNECTION` per `AGENT` (sometimes more — multiple connection histories) and similar fan-out for `AGENT_STATUS`. In demo-prod: 92 AGENTs, 59 AGENT_CONNECTIONs, 60 AGENT_STATUSes.
+
+## Where they live
+
+Both live in the **APM_INFRASTRUCTURE** layer next to AGENT.
+
+## Useful attributes
+
+AGENT_CONNECTION:
+- `name`, `ACNId`, `SourceProduct`, `agent`, `backendNode`, `category`, `resourceType`.
+
+AGENT_STATUS:
+- `name`, `Hostname`, `agentHostname`, `agentAgent`, `agentProcess`.
+- `RootResourceFolder`, `agentDomain`, `createdBy`, `Source cluster`.
+
+## When you'd actually query these
+
+Most user-facing questions ("is X being monitored?", "did the agent miss data?") are answered by:
+
+1. Attributes on `AGENT` itself (`agentIsConnected`, `agentConnectedTime`).
+2. Time-series under the agent's own metric source (e.g. `*Status*` paths).
+
+Reach for `AGENT_CONNECTION` / `AGENT_STATUS` only when:
+
+- You're auditing connection lifecycle history (multiple records over time).
+- You need to correlate a status flap with a specific deploy.
+- You're writing a tenant-side report on agent fleet health.
+
+For the common case "is host X being monitored?", traverse from HOST → AGENT and check `agentIsConnected` on the AGENT vertex.
+
+## No first-class metrics
+
+Neither type is itself a metric source. State changes show up in alarms / event streams; for time-series of agent up/down, look at the agent's own metric source (the AGENT, not these records).
+
+## Related entities
+
+- **AGENT** — the parent. Almost everything you'd want to know lives there or one TRAVERSE away.
+- **HOST** — the machine the agent runs on; matched by hostname attribute.
+- **DXI_SERVICE** — the platform-internal service that aggregates an agent's traffic.
+
+## See also
+
+- `entities/agent` — the primary record.
+- `cookbooks/metrics-grounding` — agent ↔ metric mapping.

package/dist-node/agent_source_collector-6s06n3rs.md

@@ -0,0 +1,40 @@
+---
+id: agent_source_collector
+title: agent / source / collector / monitor
+aliases: [collector, monitors, source]
+category: agent
+related: [attribute_resource_metric_name, host]
+tags: [overloaded, core]
+---
+
+# agent / source / collector / monitor
+
+These four words refer to **closely related but not identical** things:
+
+- **AGENT vertex** — a topology vertex of `type=AGENT` representing a deployed software collector. Has attributes like `agentName`, `agentType`, `agentIsConnected`. Lives in `APM_INFRASTRUCTURE`.
+- **`source` field on a metric** — a string identifier on every metric in MM, naming the producer. Usually a pipe-delimited path: `<domain>|<host-or-agent-id>|<bus>|<role>`. Most metrics have *some* `source` even when no AGENT vertex exists.
+- **"collector" / "monitor" / "agent"** (colloquial) — synonyms users employ for the AGENT vertex.
+
+## When the distinction matters
+
+- Querying *what's monitored*: filter `AGENT` vertices, optionally TRAVERSE to monitored entities.
+- Querying *where a metric came from*: filter MM by `metric.source`. **Not every metric.source has a corresponding AGENT vertex** (some come from platform-side processing, virtual sources, sub-agent components).
+- Going from source string to AGENT: the `agent` segment of the source name often matches the AGENT vertex's `agentName`, but not always — some agents emit metrics under a separate sub-agent identity.
+
+## Common mistakes
+
+- Assuming "the agent for host X" is unique. A host can have many agents (Infrastructure + Kubernetes + product-specific). The relationship is many-to-one.
+- Filtering metrics by `source LIKE %X%` and expecting the result to match a single AGENT vertex. Sources can be more granular than AGENTs (sub-paths under one collector).
+- Using `agent` ambiguously between the *attribute* (a string on many vertex types) and the *AGENT vertex* (one specific type). The string attribute often gives you the agent name without a TRAVERSE.
+
+## How users phrase it
+
+- "the agent" / "the collector" / "the monitor" → AGENT vertex.
+- "the source" → `metric.source` field on a metric.
+- "is X being monitored" → check for AGENT vertex(es) whose monitored-entities include X.
+
+## See also
+
+- `entities/agent` — AGENT vertex detail.
+- `cookbooks/metric-source-names` — pipe-delimited source naming.
+- `cookbooks/metrics-grounding` — agent ↔ metric mapping, including orphaned metrics.

package/dist-node/agentic-mcp-rycd2gh8.md

@@ -0,0 +1,140 @@
+# `dx-do agentic mcp` — stdio MCP server
+
+Run `dx-do` as a [Model Context Protocol](https://modelcontextprotocol.io/) server bound to a single tenant config. The server speaks JSON-RPC over **stdio**, so it is launched as a subprocess by your AI agent (Claude Code, Cursor, mcp-inspector, …).
+
+> **Experimental.** `agentic mcp` is currently gated. To run it from the shell, either:
+>   - pass `--enable-experimental-commands` on the dx-do invocation
+>   - export `DXDO_ENABLE_EXPERIMENTAL_COMMANDS=true` in your environment
+>
+> When MCP clients spawn dx-do as a subprocess, set the env var in their MCP server config (Claude Code: `env: {"DXDO_ENABLE_EXPERIMENTAL_COMMANDS": "true"}`; Cursor: same). Examples below show this.
+
+## Usage
+
+```
+DXDO_ENABLE_EXPERIMENTAL_COMMANDS=true dx-do agentic mcp config=<alias> [module.<id>=off|read|write ...]
+```
+
+Required:
+
+* `config=<alias>` — bind to `~/.dxdo/<alias>.dxo2.config.json`. There is no default — stdio MCP servers must be explicitly bound.
+
+Optional, repeatable:
+
+* `module.<id>=off|read|write` — override the permission level for one module. See **Modules** below.
+
+## Modules
+
+The MCP exposes the dx-do client surface as a small set of named **modules**. Each module is gated by a permission level you can set independently:
+
+* `off`   — module is not exposed at all (no tools registered)
+* `read`  — only read-only tools in the module are exposed
+* `write` — full surface (reads + mutating tools, where they exist)
+
+| Module | What it is | `read` | `write` |
+|---|---|---|---|
+| `discovery` | Explore the tenant's topology graph — what layers / services / metrics / attributes / attribute-values exist. Cached per session. | All discovery tools (read-only by nature). | Same as `read` — no mutating discovery operations. |
+| `corpus`  | Browse the corpus shipped with `@dx-do/corpus` — sections today: `queries` (worked-example payloads), `cookbooks` (quickstart + gotchas + discovery-flow), `entities` (vertex-type reference docs). Future: `metrics`, `lexicon`. | All three generic corpus tools (`corpus_sections` / `corpus_list` / `corpus_get`). | Same as `read` — no mutating corpus operations. |
+| `datastore` | Execute queries against the live tenant's DXO2 DataStore APIs (TAS / NASSQL / Metrics-Metadata). | Run full and partial queries (read against tenant data). | Reserved for future mutating datastore operations (alarms, etc.) — currently same as `read`. |
+| `ui` | Manage user-authored queries on disk under `~/.dxdo/queries/<alias>/`. Same surface the visual ui exposes. | List folders / list queries / get query. | Adds create / update / move query + create folder. |
+
+**Defaults:** `ui=write`, everything else `read`. Override per module — modules you don't mention keep their default.
+
+### Examples
+
+```sh
+# Default surface (ui=write, others=read).
+dx-do agentic mcp config=demo-prod
+
+# Lock the agent to read-only on user queries (no create/update/move).
+dx-do agentic mcp config=demo-prod module.ui=read
+
+# Hide the user-queries surface entirely. Agent can only browse the
+# corpus + run queries against the tenant.
+dx-do agentic mcp config=demo-prod module.ui=off
+
+# Browse-only — no live tenant calls. Useful when teaching an agent
+# what's available without letting it touch the tenant.
+dx-do agentic mcp config=demo-prod module.datastore=off module.ui=read
+```
+
+**Single-tenant guarantee.** No `select_segment` / `bind_session` tool exists in any module. The agent cannot programmatically switch tenants — re-binding requires restarting the process with a different `config=<alias>`.
+
+## Wiring into Claude Code
+
+The simplest path is the bundled plugin (`dx-do agentic extract-claude-marketplace base-directory=~/`) — its `plugin.json` already carries the experimental-gate env var. If you wire MCP manually, set the env var explicitly:
+
+```sh
+claude mcp add dx-do-query \
+  --env DXDO_ENABLE_EXPERIMENTAL_COMMANDS=true \
+  -- /path/to/dx-do agentic mcp config=demo-prod
+```
+
+For npm-installed dx-do:
+
+```sh
+claude mcp add dx-do-query \
+  --env DXDO_ENABLE_EXPERIMENTAL_COMMANDS=true \
+  -- npx @dx-do/cli agentic mcp config=demo-prod
+```
+
+After adding, the tools appear in Claude Code's tool palette. Verify by asking Claude to call `corpus_sections` — it should return the registered corpus sections.
+
+## Wiring into Cursor
+
+Cursor reads MCP servers from `~/.cursor/mcp.json` (or per-project `./.cursor/mcp.json`). Add an entry — note the `env` field that opens the experimental gate inside the spawned subprocess:
+
+```json
+{
+  "mcpServers": {
+    "dx-do-query": {
+      "command": "/path/to/dx-do",
+      "args": ["agentic", "mcp", "config=demo-prod"],
+      "env": {
+        "DXDO_ENABLE_EXPERIMENTAL_COMMANDS": "true"
+      }
+    }
+  }
+}
+```
+
+Restart Cursor to pick up the change. To pass module overrides, append them to the `args` array: `["agentic", "mcp", "config=demo-prod", "module.ui=read"]`.
+
+## Wiring into `mcp-inspector` (for debugging)
+
+```sh
+DXDO_ENABLE_EXPERIMENTAL_COMMANDS=true npx @modelcontextprotocol/inspector \
+  /path/to/dx-do agentic mcp config=demo-prod
+```
+
+Inspector opens a browser UI where you can list tools, invoke them with arbitrary inputs, and watch the raw JSON-RPC traffic.
+
+## Smoke test from the shell
+
+```sh
+cat <<'EOF' | DXDO_ENABLE_EXPERIMENTAL_COMMANDS=true dx-do agentic mcp config=demo-prod
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}
+{"jsonrpc":"2.0","method":"notifications/initialized"}
+{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
+EOF
+```
+
+Expected: two JSON-RPC response lines on **stdout**. The first is the `initialize` reply (`serverInfo: { name: "dx-do-query", version: "1.0.0" }`); the second lists the tools enabled by your module flags. All other dx-do output (configuration loading, etc.) goes to **stderr** and is safe to ignore (or pipe to a log file).
+
+## stdout / stderr discipline
+
+The MCP protocol uses stdout for JSON-RPC messages. Anything else on stdout corrupts the stream and the parent agent will disconnect.
+
+* **stdout**: JSON-RPC only. Owned by the MCP transport.
+* **stderr**: All `dx-do` diagnostic output (`signale`-routed by default). Treat as informational.
+
+If you wrap `dx-do agentic mcp` in your own subprocess invocation, do **not** add anything that writes to stdout (no `tee`, no progress bars, no shell wrappers that prepend output). You can freely pipe stderr (`2>somewhere`).
+
+## Lifecycle
+
+* The server runs until the parent process closes its stdin pipe (or the dx-do process receives SIGINT). Killing the parent agent terminates the MCP server cleanly.
+* Each `agentic mcp` invocation spawns its own dx-do process, loads its own session, and maintains its own discovery cache. Two parents = two processes = two caches. There is no shared state across invocations.
+* Authentication happens once at startup (during session bootstrap); failed auth aborts before any MCP requests are handled.
+
+## Related
+
+* `dx-do help configuration` — how `~/.dxdo/<alias>.dxo2.config.json` files are loaded.

package/dist-node/application-dfva8tz0.md

@@ -0,0 +1,48 @@
+---
+id: application
+title: application — also overloaded
+aliases: [app, apps, applications]
+category: scoping
+related: [service, host]
+tags: [overloaded, disambiguation, core]
+---
+
+# application
+
+"Application" overlaps with "service" but adds its own ambiguity. Candidates when a user says "the X application":
+
+| Candidate                         | Description                                                                                             |
+|-----------------------------------|---------------------------------------------------------------------------------------------------------|
+| **DXO2 application**              | A service with `type=application`. Recently introduced; Lives in the same hierarchy as other services.  |
+| **DXO2 service**                  | A service with `type=service`. For now, more common than DXO2 applications.                             |
+| **APM agent's `applicationName`** | A label attribute the APM agent sets on BUSINESSTRANSACTIONs and SERVLETs. Pre-dates DXO2 applications. |
+| **k8s_DEPLOYMENT**                | In Kubernetes-native shops, "application" usually maps to a Deployment.                                 |
+| **APM-flavored "application"**    | Older docs sometimes call the APM-monitored unit an "application".                                      |
+| **Universe**                      | At portfolio level, customers occasionally use a Universe to scope an application.                      |
+| **Business application**          | A user-narrative concept that may correspond to any of the above (or to nothing in DXO2).               |
+
+## Disambiguation rule
+
+When the user says "application X":
+
+1. **Name-search across multiple kinds**: services-with-type=application, plain DXO2 services, k8s_DEPLOYMENTs, universes, vertex names with `applicationName=X`. The MCP tool `discovery_search_by_name` does this in one call.
+2. **Pick the strongest match**:
+   - If a DXO2 service with `type=application` matches, use it.
+   - Else if a `k8s_DEPLOYMENT` with that name exists in a k8s-monitored tenant, use it.
+   - Else if a 'universe' with that name matches it
+   - Else if `applicationName` matches on BTs / SERVLETs, that's the APM-flavored anchor.
+   - Else fall back to plain DXO2 service.
+3. **If multiple candidates plausibly match**, surface them and ask the user.
+
+## How users phrase it
+
+- "How is the X application doing?" → start with the name-search.
+- "All the apps in our portfolio" → DXO2 services with `type=application`.
+- "The Java app" → APM agent's `applicationName`, often paired with the agent.
+- "The deployment for X" → `k8s_DEPLOYMENT` directly.
+
+## See also
+
+- `entities/application` — the DXO2 application detail doc.
+- `lexicon/service` — closely-related overload.
+- `cookbooks/investigation-planning` — name-disambiguation as the very first step.

package/dist-node/application-m0q2vaxj.md

@@ -0,0 +1,74 @@
+---
+id: application
+title: Application — the recently-added DXO2 service-with-type=application
+related_entities: [service, dxi_service, k8s_deployment, business_transaction]
+related_cookbooks: [investigation-planning, service-hierarchies]
+tags: [scoping, apm, organizational-axis]
+---
+
+# Application
+
+## What it is
+
+DXO2 introduced a first-class **application** concept on top of services. Mechanically, an application is a `service` with `type=application` — it lives in the same hierarchy as other services but has elevated semantic weight: applications are the headline names that tend to show up in dashboards, alert summaries, and conversation.
+
+Applications are layered on top of services for **focus and visibility** rather than to introduce a new container type. A typical pattern:
+
+```
+Service: corp-platform                             (root)
+   └── Service: payments-application               (type=application)
+         ├── Service: payments-api                  (member services)
+         └── Service: payments-worker
+```
+
+The application's children are a mix of services and the entities that ultimately populate them.
+
+## Where it lives
+
+Same place as `service` (no separate layer). The catalog row in `entities/service.md` covers the underlying service shape; this doc adds what's special when `type=application`.
+
+## Useful attributes
+
+(via the parent service shape)
+
+- `name` — display label, e.g. `payments-application`.
+- `type` — `application` (the marker).
+- Plus everything a regular service carries: `root_service`, parent/child relationships, member entities.
+
+## Mapping to "application" in user phrasing
+
+"Application X" is one of the most overloaded terms a user can use. Candidates:
+
+| Candidate | When to suspect |
+|---|---|
+| **DXO2 application** (this entity) | The customer has explicitly modeled their portfolio with `type=application` services. Modern DXO2 deployments increasingly use this. |
+| **APM agent's `applicationName`** attribute | Older APM-flavored phrasing; the application is a label on BTs and SERVLETs, not a vertex. |
+| **k8s_DEPLOYMENT** | Kubernetes-native shops usually equate one Deployment with one app. |
+| **DXO2 service** (without `type=application`) | Services predate applications; many tenants still organize purely by service. |
+| **Universe** | Some customers use universes as application-level groupings (especially at the portfolio level). |
+
+The `cookbooks/investigation-planning` decision tree starts with a name-search across all five candidates and picks based on what matches.
+
+## Common starting moves
+
+- "How is the X application doing?" → `discovery_search_by_name` across services-with-type=application, plain services, k8s_DEPLOYMENTs, universes. If a `type=application` service matches, that's the strong candidate.
+- "Inventory of the X application" → from the matched service, walk the service membership (`query-service-inventory` CLI / `service overview` MCP) to enumerate constituent entities.
+- "Dependency graph for X" → from the matched service, the `service-dependency-graph` API returns the TAS subgraph.
+
+## Common synonyms / mistakes
+
+- "App" / "application" / "system" / "product" — heavily overloaded. Always disambiguate via name-search before committing.
+- Don't assume every customer has applications modeled — some tenants have services without `type=application` for their entire portfolio.
+
+## Related entities
+
+- **service** — the underlying entity shape.
+- **dxi_service** — APM-internal service abstraction (NOT the same).
+- **k8s_DEPLOYMENT** — the most common k8s-shop equivalent of "application".
+- **BUSINESSTRANSACTION** — BTs frequently carry `applicationName` matching the app's name.
+
+## See also
+
+- `lexicon/application` — full term-overload disambiguation.
+- `cookbooks/service-hierarchies` — the service hierarchy mechanics.
+- `cookbooks/investigation-planning` — name-disambiguation as step #1.

package/dist-node/attribute_resource_metric_name-pxrceab5.md

@@ -0,0 +1,56 @@
+---
+id: attribute_resource_metric_name
+title: attribute / resource / metric name / metric path
+aliases: [metric attribute, metric name, resource name]
+category: metric
+related: [agent_source_collector]
+tags: [overloaded, core]
+---
+
+# attribute / resource / metric name / metric path
+
+The **same metric** has several names depending on which API surface or user phrasing you encounter it through. They all refer to the same underlying thing, but the field labels differ:
+
+| Term | Where you see it | Example |
+|---|---|---|
+| `metric.path` (full) | NASSQL `FROM_METADATA` columns | `Frontends\|CheckoutBT:Average Response Time (ms)` |
+| `metric.attribute` | older API field | (alias for the leaf segment) |
+| User shorthand: `<resource>:<metric>` | Conversational phrasing | `CheckoutBT:Average Response Time` |
+| MM "specifier" | Metrics-Metadata query input | `AttributeNameSpecifier { values: [...] }` |
+
+## Anatomy
+
+A metric is identified by **(source, path)** together:
+
+- `metric.source` — pipe-delimited path naming the producer. Example: `SuperDomain|host-001|Custom Metric Process|Custom Metric Agent`.
+- `metric.path` — pipe-delimited folder breadcrumb ending with `:<metric-name>`. Example: `Beans|Nass Reactive Client|Store|Flush|Unregistered Queue:Concurrent Invocations`.
+
+Together they uniquely identify the time-series.
+
+## The user's `<resource>:<metric>` framing
+
+When a user says "the `CheckoutBT:Average Response Time` metric", they're using conventional shorthand: the *resource* is the path-without-the-name, and the *metric name* is the segment after the final `:`. To map to a query:
+
+1. The resource maps to the path's pipe-delimited prefix.
+2. The metric name maps to the segment after `:`.
+3. The source is whatever agent or producer is reporting it (often inferable from the path's first segment, but not always).
+
+`cookbooks/metric-source-names` and `cookbooks/metrics-grounding` cover this in detail.
+
+## Pitfalls
+
+- Don't author NASSQL queries with `metric.attribute` — the working column name in modern NASSQL is `metric.path`. Older docs may still say `attribute`.
+- The path's `:` separator is **not** in the source. Sources don't have `:` segments; paths do.
+- Some metrics have empty resource paths and a bare metric name; those are usually agent-level rollups.
+
+## How users phrase it
+
+- "the response-time metric" → metric name (the leaf).
+- "the resource" → folder breadcrumb (the path prefix).
+- "the attribute" → ambiguous: vertex attribute? metric attribute? Always confirm.
+
+## See also
+
+- `cookbooks/metric-source-names` — pipe-delimited source name anatomy.
+- `cookbooks/metrics-grounding` — semantic layer for metrics.
+- `cookbooks/mm-cookbook` — full MM specifier reference.

package/dist-node/browseragent-snippet.template-9megjp8a.html

@@ -0,0 +1,12 @@
+<script
+        type="text/javascript"
+        id="ca_eum_ba"
+        src="${app.collectorURL}/api/1/urn:ca:tenantId:${app.tenantId}/urn:ca:appId:${app.appId}/bajs?agent=browser"
+        data-profileUrl="${app.collectorURL}/api/1/urn:ca:tenantId:${app.tenantId}/urn:ca:appId:${app.appId}/profile?agent=browser"
+        data-tenantID="${app.tenantId}"
+        data-appID="${app.appId}"
+        data-appVersion="1.0"
+        data-use-axa-appname="true"
+        data-appKey="${app.appKey}"
+        async
+></script>