@dx-do/cli 5.2.49 → 6.0.1

package/dist-node/marketplace-srdmzxkj.json

@@ -0,0 +1,15 @@
+{
+  "name": "dx-do",
+  "owner": {
+    "name": "Ki Alam",
+    "url": "https://github.com/zoobroker"
+  },
+  "description": "DXO2 plugins for Claude Code — one per activity (investigate, operate, admin, …). All share the dx-do-query MCP server and the @dx-do/catalog grounding content.",
+  "plugins": [
+    {
+      "name": "investigate",
+      "source": "./investigate",
+      "description": "Investigate a DXO2 tenant — guided discovery, query authoring, and UI/analyzer handoff."
+    }
+  ]
+}

package/dist-node/metric-source-names-6cbczyks.md

@@ -0,0 +1,75 @@
+---
+id: metric-source-names
+title: Metric source naming convention — the `<domain>|<host>|<bus>|<role>` shape
+applies_to: nassql
+tags: [reference, naming, gotcha]
+related: [nassql-quickstart, mm-quickstart, gotchas, discovery-flow]
+---
+
+# Metric source naming
+
+`metric.source` values are **pipe-delimited multi-segment strings** that identify the producer of a metric datapoint. Getting the regex shape wrong is the single most common reason an otherwise-correct NASSQL FROM pipeline returns zero rows. This cookbook covers the canonical shapes and the empirical-discovery move you should reach for when an unfamiliar tenant doesn't match what you expect.
+
+## The general shape
+
+```
+<domain>|<host-or-agent-id>|<bus>|<role>[|<extra-segments>...]
+```
+
+- **`<domain>`** — the source family. The most common value is `SuperDomain` (the default for Infrastructure-agent metrics). Other domains seen in the wild: `SystemEdge`, custom enterprise domains. **This is the segment most agents forget about** — they jump straight to the host name and write `.*<host>.*`, which doesn't match anything because every source starts with a domain prefix.
+- **`<host-or-agent-id>`** — usually the host name, sometimes a synthetic agent identifier. May be a bare hostname (`host-001`) or fully-qualified (`host-001.us-west1-b.c.example.internal`). The form depends on how the agent was registered.
+- **`<bus>`** — the metric bus / category (`Infrastructure`, `TopProcess`, `BusinessTransaction`, etc.).
+- **`<role>`** — the producer role within that bus (`Agent`, `TopNProcessByCPU`, etc.). For Infrastructure agents this is literally `Agent`.
+
+## Canonical examples
+
+| Source string | Shape |
+|---|---|
+| `SuperDomain\|host-001\|Infrastructure\|Agent` | 4-segment Infrastructure-agent (the most common shape). |
+| `SystemEdge\|host-001.us-west1-b.c.example.internal\|TopProcess\|TopNProcessByCPU\|3:Parent PID Number` | 5-segment SystemEdge probe with a sub-category. |
+
+## Regex authoring rules
+
+When you write a `metric.source` REGEX in a `sourceNameSpecifier`:
+
+1. **`|` is a regex meta-character.** Always escape it as `\|` in the pattern. A bare `|` will match anything (it's regex-OR).
+2. **Don't omit the leading segment.** A pattern like `.*host-001.*` is a common reflex — but it implicitly requires the host name to appear *somewhere*, which means it ALSO has to match the leading `<domain>|` prefix, which it does NOT (because there's no `.*` consuming the domain part). Either anchor with the domain (`^SuperDomain\|host-001\|...`) or use a wildcard explicitly between segments.
+3. **Anchor or don't — be deliberate.** Anchored (`^...$`) is faster and unambiguous. Unanchored (`.*...`) is forgiving but may pull in unintended sources from other buses.
+4. **Wildcards across segments use `.`, not `\|`.** `.*host-001.Infrastructure.Agent` (with bare `.` between segments) is a valid loose pattern — works because `.` matches the literal `|` along with anything else. Slightly wasteful but readable.
+
+## The empirical-discovery move
+
+When you don't know the source-name shape on a tenant — **do not guess from host names**. Run a FROM_METADATA probe and inspect actual source values:
+
+```json
+{
+  "query": [
+    {"op": "FROM_METADATA",
+     "querySpecifier": {"op": "SPEC",
+       "sourceNameSpecifier": {"op": "REGEX", "pattern": ".*<host-or-id-fragment>.*"},
+       "attributeNameSpecifier": {"op": "REGEX", "pattern": ".*"}}},
+    {"op": "KEEP", "columns": ["metric.source", "metric.path"]}
+  ],
+  "limit": 20
+}
+```
+
+Use `run_partial_query` with `upToStep: 0` for the cheapest possible probe (just the FROM_METADATA call, no transforms). Read the actual `metric.source` values back, then write your real query against the discovered shape.
+
+This is also the fastest way to figure out which **`<domain>`** values exist on a tenant — especially when an enterprise customer has provisioned non-`SuperDomain` agents.
+
+## Common mistakes (from the foray)
+
+| What the agent tried | Why it returned empty | The fix |
+|---|---|---|
+| `.*host-001.*` against `metric.source` | No `SuperDomain\|` prefix consumed; pattern doesn't span the literal `|` separators correctly. | `^SuperDomain\|host-001\|.*` or `.*host-001.Infrastructure.Agent` |
+| `.*<bare-host>.*` with `\|` in pattern as `|` (unescaped) | The `|` parses as regex-OR, blowing up the intended structure. | Escape as `\|` or use bare `.`. |
+| Probing source names with `run_query` (full execute) instead of a partial | Wastes a full pipeline run for what's actually a one-step inspection. | `run_partial_query` with `upToStep: 0`. |
+
+## See also
+
+- `nassql-quickstart` — the FROM / FROM_METADATA / FROM_DATA decision (this cookbook covers the source-pattern shape that those ops consume).
+- `mm-quickstart` — Metrics Metadata specifiers (the `sourceNameSpecifier` field is the same shape).
+- `gotchas` — promotes the empty-payload trap + auto-numbered shortName + this cookbook's source-pattern trap to the top.
+- `discovery-flow` — the broader discovery hierarchy.
+- `entities/agent` — the entity that *produces* these source names.

package/dist-node/metrics-grounding-2h4kkbe3.md

@@ -0,0 +1,130 @@
+---
+id: metrics-grounding
+title: Metrics grounding — the semantic layer beyond MM mechanics
+applies_to: metadata
+tags: [reference, authoring]
+related: [metric-source-names, mm-cookbook, mm-quickstart, entity-relationships, investigation-planning]
+---
+
+# Metrics grounding
+
+`mm-quickstart` and `mm-cookbook` cover the *mechanics* of authoring metric-metadata queries. This cookbook covers the **semantics** — what a metric *means* in DXO2's entity model, how to navigate from a metric back to the producing agent (or accept that no entity exists), and how to handle the most common surprise: metrics for resources that have no topology vertex.
+
+## Metric identity, four ways
+
+The same metric is referred to by different names depending on which surface you're on:
+
+| Name | Where you see it |
+|---|---|
+| `metric.source` + `metric.path` | NASSQL `FROM_METADATA` columns |
+| MM `SourceNameSpecifier` + `AttributeNameSpecifier` | Metrics-Metadata query input |
+| `<resource>:<metric>` | User shorthand — the `metric.path` ending after the last `:` is the metric name; the prefix is the "resource" |
+| `metric.attribute` (older) | Older API field — alias for the path's leaf segment |
+
+Concretely, a metric like `Beans|Nass Reactive Client|Store|Flush|Unregistered Queue:Concurrent Invocations` carries:
+
+- `metric.source` = `SuperDomain|host-001|Custom Metric Process|Custom Metric Agent` (the producer).
+- `metric.path` = the pipe-delimited folder breadcrumb ending with `:Concurrent Invocations`.
+- User shorthand: `Unregistered Queue:Concurrent Invocations` (resource = breadcrumb tail; metric name = post-`:`).
+
+For the field-level rules see `lexicon/attribute_resource_metric_name`.
+
+## The agent ↔ metric bridge
+
+Most metrics tie back to an **AGENT vertex** via a known path. The bridge:
+
+1. From a topology vertex (HOST, BUSINESSTRANSACTION, k8s_POD), TRAVERSE `agent-monitors` (incoming) → AGENT vertex.
+2. From the AGENT, the `agentName` attribute (or part of `metric.source`) connects to MM.
+3. Query MM by `metric.source` matching a regex of the agent's identity, or use `discovery_metrics_for_entity` (which builds the canonical metric query body for a vertex).
+
+The AGENT is the *producer*; metrics flow from it. If you only have a metric and you want to find its agent: split `metric.source` on `|`, look at the second-to-last segment (often the `agent` identity), and search AGENT vertices.
+
+## Orphaned-by-design metrics
+
+**Not every metric has a topology vertex.** This is the single biggest grounding gap a query agent runs into. The canonical example: **JMX metrics**.
+
+A JMX-instrumented JVM exposes hundreds of MBeans — connection pools, thread pools, cache regions, queue stats, GC details. The platform's JMX agent forwards these as metrics under the JVM's source. But:
+
+- There is usually **one** `JMX_SYSTEM` vertex per monitored JVM, not one vertex per pool.
+- There is **no `JDBC_CONNECTION_POOL` vertex type** by default.
+- The pool, queue, or cache identity exists *only in the metric path*.
+
+If a user asks "how are the database connection pools for application X doing", the wrong move is "search for `type=JDBC_CONNECTION_POOL`" — that returns nothing. The right move is:
+
+1. Find the application X (DXO2 service / k8s_DEPLOYMENT / `applicationName` — see `cookbooks/investigation-planning`).
+2. Find the agents producing metrics for X — typically a Java APM agent and a JMX agent.
+3. Query MM under those agents for paths matching pool-flavored regex: `.*JDBC.*Pool.*` or `.*Connection Pool.*` or similar.
+4. Group/aggregate by the pool segment of the path to get per-pool numbers.
+
+The metric *value* is sometimes the only place identity lives — e.g. a `queue_name` metric that's a string `queue://host-2/orders`. In that case, NASSQL `FROM_DATA` to extract values, then group/filter on the value.
+
+When this pattern repeats for the same customer / same kind of resource, **inventorize** materializes a vertex per resource so future queries can use vertex traversal. See `lexicon/inventorize`.
+
+## Metric `type` is opaque (for now)
+
+Every metric carries a numeric `type` field with values like `0`, `1`, `2`, `3`. The numeric ID indicates the metric's data shape (gauge, counter, rate, etc.) and informs how it should be aggregated and displayed.
+
+**The numeric → semantic mapping is not yet documented in the corpus.** Treat `metric.type` as opaque: when you need to aggregate or order, prefer empirical inspection of values via `run_partial_query` rather than assuming a particular type means a particular aggregation. A future grounding pass will close this gap.
+
+## Pattern recognition: deciding when to inventorize
+
+If you see all three of these for the same resource pattern, inventorizing is probably right:
+
+1. The user keeps asking about the resource by name — it's part of their vocabulary.
+2. The metrics for the resource are reliable and stable (same source, same path shape, same regular intervals).
+3. There's no existing vertex type that matches.
+
+In that case, an **inventorize rule** (`inventory create-inventorize-rule`) materializes a vertex per match. The vertex gets a `CUSTOM_INVENTORIZE_<N>` type by default; you can give it a more specific name. After the rule runs, future queries can use the new type as a first-class anchor.
+
+## Practical authoring patterns
+
+### Pattern 1 — find metrics for a known vertex
+
+```
+discovery_metrics_for_entity(vertexId="<id>")
+```
+
+Returns the canonical metric query body the platform's mapping configuration says applies. Use this when you have the vertex.
+
+### Pattern 2 — find metrics matching a name pattern
+
+```js
+// MM query
+{
+  "querySpecifier": {
+    "op": "AND",
+    "input": [
+      { "op": "ATTRIBUTE_NAME", "values": [".*Connection Pool.*"], "queryType": "REGEX" }
+    ]
+  },
+  "limit": 200
+}
+```
+
+Use this for orphaned metrics. Adjust the regex to taste.
+
+### Pattern 3 — find which agent produced a metric
+
+```js
+// NASSQL
+{ "query": [
+    { "op": "FROM_METADATA", "querySpecifier": { ... }, "alias": "m" },
+    { "op": "GROUP", "columns": ["metric.source"] },
+    { "op": "COUNT", "as": "n" }
+  ], "limit": 50 }
+```
+
+Group by source to see the producer distribution. Then look up each source as an AGENT.
+
+### Pattern 4 — compare multiple agents reporting the "same" metric
+
+A backend or BT may show up under multiple agents. To compare, NASSQL `FROM_DATA` joined to `FROM_TOPOLOGY` (or grouped by `metric.source`) gives per-agent slices. Sum/average for the unified view.
+
+## See also
+
+- `cookbooks/metric-source-names` — pipe-delimited source name anatomy.
+- `cookbooks/mm-cookbook` — full specifier vocabulary.
+- `cookbooks/investigation-planning` — when to reach for metric-first vs entity-first.
+- `lexicon/attribute_resource_metric_name` — the four-name terminology.
+- `lexicon/inventorize` — promoting metric patterns into vertices.
+- `entities/jmx_system` — the canonical orphaned-metrics case.

package/dist-node/mm-cookbook-23jpw721.md

@@ -0,0 +1,231 @@
+---
+id: mm-cookbook
+title: Metrics Metadata cookbook — specifier reference and recipe catalog
+applies_to: metadata
+tags: [reference, recipes, authoring]
+related: [mm-quickstart, nassql-cookbook, gotchas]
+---
+
+# Metrics Metadata cookbook
+
+Full specifier-vocabulary reference for Metrics Metadata
+(`/metadata/queryMetric`) authoring, plus a recipe catalog. The same
+`QuerySpecifier` vocabulary documented here is also embedded inside NASSQL
+`FROM_METADATA` and `JOIN_METADATA` ops — so this cookbook is required
+reading for NASSQL authors too.
+
+Use after `mm-quickstart.md` when you need the full sub-specifier
+breakdown or a concrete pattern to start from.
+
+## Specifier mental model
+
+A `QuerySpecifier` describes a **set of metric metadata records**. It is a
+discriminated union on `op`. The richest op is `SPEC`, which has three
+sub-specifier slots:
+
+```mermaid
+flowchart TB
+  spec["QuerySpecifier (op-discriminated)"] --> simple["leaves: ALL / NONE / ID / GROUP / SERVICE / ATTRIBUTE"]
+  spec --> compose["composers: AND / OR / NOT"]
+  spec --> structured["SPEC { sourceNameSpecifier, folderNameSpecifier, attributeNameSpecifier }"]
+  structured --> sourceSpec["SourceNameSpecifier (ALL / EXACT / REGEX / PART / AND / OR / NOT)"]
+  structured --> attrSpec["AttributeNameSpecifier (ALL / EXACT / REGEX / FOLDER / CHILDREN / TYPE / OPERATOR / NUMERIC / ATTRIBUTE / AND / OR / NOT)"]
+```
+
+Why three: a metric is keyed by `<source>` + `<folder/path>` + `<attribute>`,
+so each component has its own specifier sub-language with its own ops.
+
+## Top-level envelope
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| `specifier` | `QuerySpecifier` | What metrics to match; omit = `ALL` |
+| `clamp` | number | Cap on result count. **Default new queries to ≤ 500.** Large tenants return MB without this. |
+| `time` | number | Reference time (epoch ms); default = now |
+| `range` | number | Time range in ms around `time` to include recently-inactive metrics |
+| `includeLive` | boolean | Include currently-active live metrics not yet persisted |
+| `includeProfile` | boolean | Include profiling info per metric descriptor |
+| `profileLevel` | string | Granularity of profiling when `includeProfile=true` |
+| `authorizationView` | string | Auth-view restriction |
+| `queryHints` | `QueryHint[]` | `{ "hint": "ForceRange" }` forces time-range search even without an explicit `queryRange` |
+
+## Top-level `QuerySpecifier` ops
+
+| Op | Shape | Purpose |
+|----|-------|---------|
+| `ALL` | `{ op: "ALL", includeFolders?, includeMetrics? }` | Every metric |
+| `NONE` | `{ op: "NONE" }` | Empty set |
+| `AND` | `{ op: "AND", specifiers: [...] }` | Intersection |
+| `OR` | `{ op: "OR", specifiers: [...] }` | Union |
+| `NOT` | `{ op: "NOT", specifier: ... }` | Complement |
+| `SPEC` | `{ op: "SPEC", sourceNameSpecifier?, folderNameSpecifier?, attributeNameSpecifier? }` | Structured match (the workhorse) |
+| `ID` | `{ op: "ID", ids: ["m-id-1", ...] }` | By metric id |
+| `ATTRIBUTE` | `{ op: "ATTRIBUTE", expressions: [...] }` | By metric-attribute expression |
+| `GROUP` | `{ op: "GROUP", id?, managementModuleId? }` | By management module / group |
+| `SERVICE` | `{ op: "SERVICE", values: [...] }` | By named service |
+
+Note: `AND`/`OR` use `specifiers` (array), `NOT` uses `specifier` (single).
+**Do not** confuse with NASSQL `FILTER` predicates which use `spec`.
+
+## SourceNameSpecifier ops
+
+Used inside `SPEC.sourceNameSpecifier`.
+
+| Op | Shape | Purpose |
+|----|-------|---------|
+| `ALL` | `{ op: "ALL" }` | Any source |
+| `NONE` | `{ op: "NONE" }` | No source |
+| `EXACT` | `{ op: "EXACT", names: [...], ignoreCase? }` | Exact source-name match |
+| `REGEX` | `{ op: "REGEX", pattern, ignoreCase? }` | Regex match |
+| `PART` | `{ op: "PART", part, partValue?, operator? }` | Match a specific dot-separated segment (0-indexed) |
+| `AND` / `OR` | `{ op, specifiers: [...] }` | Boolean composition |
+| `NOT` | `{ op: "NOT", specifier: ... }` | Complement |
+
+`PART.operator`: `EQ | NE | GE | GT | LE | LT`.
+
+See `metric-source-names.md` for the canonical `<domain>|<host>|<bus>|<role>`
+shape that source strings follow, and the regex-authoring rules that
+prevent zero-row results.
+
+## AttributeNameSpecifier ops
+
+Used inside `SPEC.attributeNameSpecifier`. Richer than the source side
+because metric attribute names form a hierarchy:
+
+| Op | Shape | Purpose |
+|----|-------|---------|
+| `ALL` / `NONE` | `{ op }` | Any / no attribute |
+| `EXACT` | `{ op: "EXACT", names: [...], type?, ignoreCase? }` | Exact attribute name |
+| `REGEX` | `{ op: "REGEX", pattern, ignoreCase? }` | Regex match |
+| `FOLDER` | `{ op: "FOLDER", specifier: FolderNameSpecifier }` | Match by folder |
+| `CHILDREN` | `{ op: "CHILDREN", prefix?, recursive? }` | Match attribute children of prefix |
+| `TYPE` | `{ op: "TYPE", specifier?, bitMask?, bitMatch?, operator? }` | Match by type bits |
+| `OPERATOR` | `{ op: "OPERATOR", name?, fullPath?, operator? }` | Match by operator |
+| `NUMERIC` | `{ op: "NUMERIC" }` | Match any numeric attribute |
+| `ATTRIBUTE` | `{ op: "ATTRIBUTE", expressions: [...] }` | Match by metric-attribute expression |
+| `AND` / `OR` | `{ op, specifiers: [...] }` | Boolean composition |
+| `NOT` | `{ op: "NOT", specifier: ... }` | Complement |
+
+The simplest combinators are `EXACT` and `REGEX`, which cover the majority
+of real queries.
+
+## FolderNameSpecifier
+
+A sub-language for folder paths, used inside an
+`AttributeNameSpecifier` of op `FOLDER`.
+
+| Op | Shape | Purpose |
+|----|-------|---------|
+| `ALL` / `NONE` | `{ op }` | Any / no folder |
+| `EXACT` | `{ op: "EXACT", names: [...], ignoreCase? }` | Exact folder name |
+| `REGEX` | `{ op: "REGEX", pattern, ignoreCase? }` | Regex match |
+| `CHILDREN` | `{ op: "CHILDREN", prefix?, recursive? }` | Children of prefix path |
+| `AND` / `OR` | `{ op, specifiers: [...] }` | Boolean composition |
+| `NOT` | `{ op: "NOT", specifier: ... }` | Complement |
+
+Metric attribute names are organized in a virtual folder hierarchy using
+dots as separators. `prefix` is a dot-delimited parent path.
+
+## Recipe catalog
+
+### "All metrics on the tenant (smoke / count)"
+
+```json
+{
+  "specifier": { "op": "ALL" },
+  "clamp": 10,
+  "range": 480000,
+  "includeLive": true
+}
+```
+
+### "Metrics with source matching a regex"
+
+```json
+{
+  "specifier": {
+    "op": "SPEC",
+    "sourceNameSpecifier": { "op": "REGEX", "pattern": ".*Infrastructure.*" }
+  },
+  "clamp": 100
+}
+```
+
+### "Metrics with attribute matching a regex"
+
+```json
+{
+  "specifier": {
+    "op": "SPEC",
+    "attributeNameSpecifier": { "op": "REGEX", "pattern": ".*CPU.*Utilization.*" }
+  },
+  "clamp": 100
+}
+```
+
+### "Metrics for a specific source name (exact)"
+
+```json
+{
+  "specifier": {
+    "op": "SPEC",
+    "sourceNameSpecifier": { "op": "EXACT", "names": ["Infrastructure|host01|CPU"] }
+  },
+  "clamp": 50
+}
+```
+
+### "Cross-product: source regex AND attribute regex"
+
+```json
+{
+  "specifier": {
+    "op": "SPEC",
+    "sourceNameSpecifier": { "op": "REGEX", "pattern": ".*Infrastructure.*" },
+    "attributeNameSpecifier": { "op": "REGEX", "pattern": ".*CPU.*" }
+  },
+  "clamp": 200
+}
+```
+
+### "Either of two sources, but exclude a noisy attribute"
+
+```json
+{
+  "specifier": {
+    "op": "AND",
+    "specifiers": [
+      { "op": "SPEC",
+        "sourceNameSpecifier": { "op": "OR", "specifiers": [
+          { "op": "REGEX", "pattern": ".*Infrastructure.*" },
+          { "op": "REGEX", "pattern": ".*APM.*" } ] } },
+      { "op": "NOT",
+        "specifier": { "op": "SPEC",
+          "attributeNameSpecifier": { "op": "REGEX", "pattern": ".*Heap.*" } } }
+    ]
+  },
+  "clamp": 100
+}
+```
+
+### "Metrics by id"
+
+```json
+{ "specifier": { "op": "ID", "ids": ["m-id-1", "m-id-2"] } }
+```
+
+## Authoring tips
+
+- For NASSQL embedding, **always wrap REGEX in `SPEC`**. A bare
+  `{ op: "REGEX", ... }` is not a valid `QuerySpecifier`. See `gotchas.md`.
+- Use `AND` / `OR` / `NOT` at the **`QuerySpecifier`** level for
+  whole-spec composition, not inside the sub-specifiers.
+- The sub-specifiers (`SourceNameSpecifier`, `AttributeNameSpecifier`)
+  have their **own** `AND` / `OR` / `NOT` ops scoped to that
+  sub-language — useful for "source = (X regex OR Y regex)".
+- `clamp` caps the result count at the metadata service; use it in
+  addition to (or instead of) any pagination on the calling code.
+- When the metric-source vocabulary is unknown, run the `FROM_METADATA` +
+  `GROUP source` + `COUNT` discovery NASSQL query first
+  (`corpus_get("queries", "03-discover-sources")`) to learn real source
+  names. See `metric-source-names.md` for the source-string shape.

package/dist-node/mm-quickstart-x2adfc16.md

@@ -0,0 +1,106 @@
+---
+id: mm-quickstart
+title: Metrics Metadata quickstart — author a metric specifier
+applies_to: metadata
+tags: [getting-started, authoring]
+related: [nassql-quickstart, gotchas]
+---
+
+# Metrics Metadata quickstart
+
+MM = metric metadata queries. Returns `{ metrics, folders }` arrays of
+descriptors. The query body is a single recursive **specifier tree**.
+
+## The envelope
+
+```json
+{
+  "specifier": { "op": "ALL", "includeMetrics": true },
+  "clamp": 500,            // strongly recommended — see Gotcha below
+  "time": 1700000000000,
+  "range": 86400000,
+  "includeLive": false,
+  "includeProfile": false,
+  "profileLevel": null,
+  "authorizationView": null
+}
+```
+
+## Gotcha — set `clamp`
+
+Without a `clamp`, the server returns ALL matching metrics. On a real
+tenant that's tens of thousands of descriptors / multiple MB. **Default
+`clamp: 500`** for new MM queries, raise only when needed.
+
+## Top-level specifier ops (10)
+
+| Op | Purpose |
+|---|---|
+| `ALL` | Match everything. Use `includeFolders` / `includeMetrics`. |
+| `NONE` | Match nothing. |
+| `AND` / `OR` | Compose specifiers. **Cannot be empty.** |
+| `NOT` | Negate. |
+| `SPEC` | Compose three sub-specifiers (source-name + folder-name + attribute-name). |
+| `ID` | Match specific metric IDs. **`ids` cannot be empty.** |
+| `ATTRIBUTE` | Match by attribute expressions. |
+| `GROUP` | Match a metric group / module. |
+| `SERVICE` | Restrict by service name(s). |
+
+## SPEC — composing the three sub-specifier trees
+
+`SPEC` is the powerful pattern. It combines:
+
+- `sourceNameSpecifier` — match the source layer name
+- `folderNameSpecifier` — match the folder hierarchy
+- `attributeNameSpecifier` — match the attribute name
+
+Each is its own recursive tree with AND/OR/NOT/EXACT/REGEX. AttributeName
+also has CHILDREN, FOLDER, TYPE, OPERATOR, NUMERIC, ATTRIBUTE.
+
+Example — APM-sourced CPU metrics in a specific folder:
+
+```json
+{
+  "specifier": {
+    "op": "SPEC",
+    "sourceNameSpecifier": { "op": "EXACT", "names": ["APM"] },
+    "folderNameSpecifier": { "op": "CHILDREN", "prefix": "Hosts", "recursive": true },
+    "attributeNameSpecifier": { "op": "REGEX", "pattern": "^cpu\\..*" }
+  },
+  "clamp": 500
+}
+```
+
+## ID — pinpoint specific metrics
+
+```json
+{
+  "specifier": {
+    "op": "ID",
+    "ids": ["NOB-BE-qP-n5EevJ0B", "ABC-12-..."]
+  },
+  "clamp": 100
+}
+```
+
+`ids` is required-non-empty. Reading metric IDs from a previous MM query's
+result table (the leftmost column of the metric results) is the typical
+pattern.
+
+## Iteration
+
+MM has no partial-run primitive (single specifier — no obvious slice
+point). Run the full query, narrow the specifier, run again.
+
+## Discovery
+
+`discovery_metrics` returns up to 1000 metric attribute names known on
+the tenant. Useful to validate `ATTRIBUTE` expression names before
+running.
+
+## See also
+
+- `mm-cookbook.md` — full specifier reference, recipe catalog, sub-specifier composition
+- `gotchas.md` — `ID.ids` empty-array surprise (now caught by .min(1))
+- `nassql-quickstart.md` — for embedding MM specifiers in NASSQL FROM_METADATA / JOIN_METADATA
+- Live examples: `corpus_list("queries", {type: "metadata"})` — fetch full payloads with `corpus_get("queries", "<id>")`.