@dx-do/cli 5.2.49 → 5.2.50

package/dist-node/50-discover-custom-layers.tas-2hvvpkzw.md

@@ -0,0 +1,66 @@
+# 50-discover-custom-layers (TAS)
+
+## Purpose
+
+Find all vertices whose layer is **not** one of the built-in DataStore layers. This surfaces custom integration layers that third-party or internal connectors may use when writing their entities to the topology graph.
+
+## Query Construction
+
+Wraps a `LAYER` filter (using the multi-value `values` array) in a `NOT` filter:
+
+```
+NOT(
+  LAYER(values: ["ATC", "UIM", "APM_INFRASTRUCTURE", "INFRASTRUCTURE",
+                 "SA", "ACN", "CONNECTOR_METADATA", "ACN_CONFIGURATION"])
+)
+```
+
+The `LAYER` filter with `values` performs an OR match across all listed layer names. `NOT` inverts this, selecting every vertex whose layer is absent from the list. The result set therefore contains only vertices on unknown/custom layers.
+
+The exclusion list is the union of:
+- **Java API constants** (`TasConstants`): `ATC`, `APM_INFRASTRUCTURE`, `SA`, `ACN`
+- **`Layer` class static instances**: `ATC`, `UIM`, `APM_INFRASTRUCTURE`, `INFRASTRUCTURE`
+- **Conditional but server-recognized** (appear when the tenant uses connectors that publish to them): `CONNECTOR_METADATA`, `ACN_CONFIGURATION`
+
+## API Surface Exercised
+
+- **Filter**: `NOT` — inverts any inner filter result
+- **Filter**: `LAYER` with `values` (array) — multi-layer OR match
+- Together these form the idiomatic "exclude known layers" pattern; there is no native `NOT_LAYER` op
+
+## Expected Output
+
+Up to 200 vertices with `DETAILED` projection. For each vertex inspect:
+- `externalId` — the first colon-delimited segment is the custom layer name
+- `attributes.type` — the vertex type registered by the integration
+
+If the tenant has no custom integrations, the result will be empty (0 vertices).
+
+A typical result on a tenant with one or two integrations might look like:
+
+| Layer | Vertex count | Sample externalId prefix |
+|---|---|---|
+| `CUSTOM` | tens | `CUSTOM:LOGANALYTICS\|…` |
+| `INFRASTRUCTURE_UIM` | tens | `INFRASTRUCTURE_UIM:OpenAccess_…` |
+| `NETWORK_SPECTRUM` | tens | `NETWORK_SPECTRUM:<entity-id>` |
+
+To enumerate distinct custom layer names from any result file:
+
+```bash
+python3 -c "
+import json
+with open('packages/.tmp/output/datastore-driver/<dir>/<TENANT>_50-discover-custom-layers.tas.data-store.result.json') as f:
+    data = json.load(f)
+layers = sorted({v.get('externalId','').split(':')[0] for v in data['vertices']})
+print('Custom layers found:', layers)
+"
+```
+
+## What the Results Tell You
+
+Any layer name that appears here was written by an integration that is not part of the core DataStore product. Common examples include:
+- Cloud-provider collectors (e.g., `AWS`, `AZURE`, `GCP` specific namespaces)
+- Custom on-premise connectors
+- Partner integrations that declare their own namespace
+
+Once you know the custom layer names, you can query them directly with a targeted `LAYER` filter (see query 13 for the pattern).

package/dist-node/50-discover-custom-layers.tas.data-store-h85zgna9.json5

@@ -0,0 +1,36 @@
+/*
+ * Find vertices in CUSTOM (non-standard) topology layers — i.e.
+ * anything written by integrations that aren't part of the core
+ * DataStore product. Pattern: NOT(LAYER(values: <known layers>))
+ * — invert the filter against the known-standard set.
+ *
+ * The exclusion list combines:
+ *   - Java API constants (TasConstants): ATC, APM_INFRASTRUCTURE,
+ *     SA, ACN
+ *   - `Layer` class static instances: ATC, UIM, APM_INFRASTRUCTURE,
+ *     INFRASTRUCTURE
+ *   - Conditional but server-recognized (appear when the tenant
+ *     uses connectors that publish to them): CONNECTOR_METADATA,
+ *     ACN_CONFIGURATION
+ *
+ * Result-set on a tenant with integrations: typically tens of
+ * vertices across a handful of partner-defined layers
+ * (NETWORK_SPECTRUM, INFRASTRUCTURE_UIM, CUSTOM, etc.). Empty on
+ * tenants without integrations.
+ */
+{
+  /*
+   * NOT-wrapping a LAYER-with-values is the idiomatic "anything
+   * NOT in this layer set" pattern. There is no native `NOT_LAYER`
+   * op; this is the canonical replacement.
+   */
+  "filter": {
+    "op": "NOT",
+    "input": {
+      "op": "LAYER",
+      "values": ["ATC", "UIM", "APM_INFRASTRUCTURE", "INFRASTRUCTURE", "SA", "ACN", "CONNECTOR_METADATA", "ACN_CONFIGURATION"]
+    }
+  },
+  "limit": 200,
+  "projection": "DETAILED"
+}

package/dist-node/50-discover-custom-layers.tas.data-store-tmd-hagn9eak.json

@@ -0,0 +1,4 @@
+{
+  "description": "Find vertices on non-standard layers — any layer not in the known built-in set. Useful for discovering custom integration layers.",
+  "tags": ["tas", "filter", "layer", "discovery"]
+}

package/dist-node/51-collect-counts-everything.tas-nz0ksgdc.md

@@ -0,0 +1,46 @@
+# 51-collect-counts-everything (TAS)
+
+## Purpose
+
+Answer "how many vertices does this tenant have?" in a single round trip without paying the wire cost of the actual vertex set. The right thing to run before deciding whether to dump a tenant's full topology to a UI / agent / file — small tenants might be 1k vertices, big ones can hit 500k.
+
+> **MCP shortcut:** the same answer is one call away via `discovery_entity_count`. Use the shortcut when you just need the number; come back here when you want to see the underlying TAS pattern (so you can adapt it — same shape with `ALL` swapped for any vertex-shaped filter gives a count for that subset).
+
+## Query Construction
+
+The query composes three ops, outside-in:
+
+1. `EMPTY` — pass-through wrapper that forces the final result vertex set to be empty.
+2. `COLLECT_COUNTS` — analytic op that records its input's vertex count under a named `id` and emits it on `result.analytics[]`. Otherwise pass-through.
+3. `ALL` — every vertex in the tenant.
+
+The inner pipeline counts everything; the outer `EMPTY` drops the vertex set so only the analytic crosses the wire. Response is under 200 bytes regardless of tenant size.
+
+## API Surface Exercised
+
+- **EMPTY**: drop the final vertex set; keep analytics. Useful any time you only want aggregate metadata, not the vertices themselves.
+- **COLLECT_COUNTS**: cheap pass-through analytic. Records `{ id, vertexCount }` on `result.analytics[]`. The `id` is your read-key — use a stable string you can match against when multiple analytics are emitted.
+- **ALL**: matches every vertex in the tenant.
+
+## Expected Output
+
+```json
+{
+  "vertices": [],
+  "edges": [],
+  "analytics": [
+    { "t": "COLLECT_COUNTS", "id": "EVERYTHING", "vertexCount": 1718 }
+  ],
+  "totalVertices": 0,
+  "totalEdges": 0,
+  "nextOffset": -1
+}
+```
+
+`vertices` and `edges` are empty by design (the EMPTY wrapper). The analytic carries the count.
+
+## What the Results Tell You
+
+`vertexCount` is the total live vertex count in the tenant at query time. Tenants under ~5k vertices can usually be loaded whole into a graph visualizer; bigger tenants need scoping (by service, by type, by neighborhood traversal) before a full-topology load is worth attempting.
+
+This pattern generalizes — replace `ALL` with any vertex-shaped filter and you get a count for that subset. See `52-collect-counts-bulk` for the bulk-fan-in extension that gets multiple counts in a single query.

package/dist-node/51-collect-counts-everything.tas.data-store-eypcjah8.json5

@@ -0,0 +1,48 @@
+/*
+ * Pre-flight tenant-size probe — answer "how many vertices does
+ * this tenant have?" in one cheap analytic-only round trip. No
+ * vertices on the wire, just a single number.
+ *
+ * Pattern: EMPTY > COLLECT_COUNTS > ALL.
+ *   - ALL produces every vertex.
+ *   - COLLECT_COUNTS records the count as an analytic (it's a
+ *     pass-through op, so vertices flow through unchanged).
+ *   - EMPTY drops the vertex set on the way out so the response
+ *     is just `{ analytics: [{ t: "COLLECT_COUNTS", id, vertexCount }] }`.
+ *
+ * Response is < 200 bytes regardless of tenant size — 100 vertices
+ * or 500,000. Use this BEFORE deciding whether to dump the whole
+ * topology to a UI / agent / file.
+ */
+{
+  "filter": {
+    /*
+     * EMPTY — pass-through "force-empty-output" wrapper. The inner
+     * filter still runs (and any analytics inside still emit), but
+     * the final vertex set returned to the client is empty.
+     */
+    "op": "EMPTY",
+    "input": {
+      /*
+       * COLLECT_COUNTS — analytic pass-through. Records
+       * `vertexCount` for whatever its `input` produces, keyed by
+       * the unique `id`. Read it back from `result.analytics[]`.
+       */
+      "op": "COLLECT_COUNTS",
+      "id": "EVERYTHING",
+      "input": {
+        /*
+         * ALL — every vertex in the tenant. Pair with
+         * COLLECT_COUNTS to get the total tenant size.
+         */
+        "op": "ALL"
+      }
+    }
+  },
+  /*
+   * `limit: 1` is symbolic here — EMPTY drops the vertex set
+   * regardless. Some servers reject `limit: 0`, so 1 is the
+   * conventional placeholder for "I don't want any vertices".
+   */
+  "limit": 1
+}

package/dist-node/51-collect-counts-everything.tas.data-store-tmd-4pcj94s9.json

@@ -0,0 +1,4 @@
+{
+  "description": "Pre-flight tenant-size probe — total vertex count via EMPTY > COLLECT_COUNTS > ALL, single small round trip",
+  "tags": ["tas", "analytics", "collect-counts", "discovery"]
+}

package/dist-node/52-collect-counts-bulk.tas-eerw4z8s.md

@@ -0,0 +1,54 @@
+# 52-collect-counts-bulk (TAS)
+
+## Purpose
+
+Get N vertex counts (per type, per service, per layer — whatever the axis) in a single round trip instead of N parallel queries. The pattern that makes "count per service" UIs feasible on tenants with hundreds of services without a request storm.
+
+> **MCP shortcut for the per-service case:** `discovery_service_counts` returns `{services: [{id, name, count, childServiceNames}]}` in one call — it composes this exact `OR(COLLECT_COUNTS(SERVICE([name])))` query over the OI service catalog (and batches by 200 names so it scales past the multi-thousand-service tenants). Reach for the shortcut for the per-service axis; reach for the underlying pattern (this query) when you want counts on a different axis (per-type, per-layer, per-traversal-result, …).
+
+## Query Construction
+
+Three ops, nested:
+
+1. `EMPTY` — drop the final vertex set; keep the analytics.
+2. `OR` — compose multiple branches under one filter tree. Each branch produces a vertex set; OR returns their union. (The union is discarded by EMPTY — we don't actually want it.)
+3. Each branch is a `COLLECT_COUNTS` analytic with a unique `id`, wrapping whatever vertex-shaped filter defines its slice.
+
+The example uses three branches:
+- `count:host` — vertices with `type = HOST`
+- `count:agent` — vertices with `type = AGENT`
+- `count:all` — every vertex (`ALL`)
+
+The inner filter for each branch can be anything — `SERVICE`, `LAYER`, `LUCENE`, `ATTRIBUTE`, `TRAVERSE`, even another nested composition. Each branch's analytic is independent.
+
+## API Surface Exercised
+
+- **EMPTY**: as in `51-collect-counts-everything` — discard the vertex set, keep analytics.
+- **OR**: composes multiple sub-filters under one tree. Each branch runs in parallel inside the server, sharing the same query-plan context.
+- **COLLECT_COUNTS** with unique `id` per branch: each one emits an independent analytic entry.
+
+## Expected Output
+
+```json
+{
+  "vertices": [],
+  "edges": [],
+  "analytics": [
+    { "t": "COLLECT_COUNTS", "id": "count:host",  "vertexCount": 32 },
+    { "t": "COLLECT_COUNTS", "id": "count:agent", "vertexCount": 96 },
+    { "t": "COLLECT_COUNTS", "id": "count:all",   "vertexCount": 1718 }
+  ]
+}
+```
+
+Read the per-branch counts back by matching on `id`. Order isn't guaranteed — always look up by id, don't rely on positional indexing.
+
+## What the Results Tell You
+
+How big each slice is, before you commit to fetching its vertices. Concretely:
+
+- A "service picker" UI can render `Service Foo · 175 entities` rows for hundreds of services on the strength of one query — no need to issue one query per service.
+- A "topology summary" tool can answer "how is this tenant composed?" with one query: count by type, count by layer, count by source-product.
+- A scoping decision (e.g. "should I load this neighborhood or just sample it?") can call this once with the proposed filter to know the size before committing.
+
+The fan-in trick is the load-bearing pattern — without it, count-per-X UIs default to N parallel queries, which scales poorly with N. The unique-id-per-branch contract is non-negotiable; reusing an id silently collapses the analytics.

package/dist-node/52-collect-counts-bulk.tas.data-store-scedtw1m.json5

@@ -0,0 +1,65 @@
+/*
+ * Bulk count probe — multiple `COLLECT_COUNTS` analytics in a
+ * SINGLE round trip via `OR` composition. Each branch contributes
+ * its own analytic to `result.analytics[]`, keyed by a unique `id`.
+ *
+ * Use this any time you'd otherwise loop over N filters running
+ * one COLLECT_COUNTS each. Counts per type, per layer, per service,
+ * per attribute value — all collapse into one query. The inner
+ * `OR` produces a UNION of vertex sets but the outer `EMPTY`
+ * discards that — only the analytics matter.
+ *
+ * The example below counts HOSTs, AGENTs, and the total tenant
+ * vertices in one query. Swap the inner ATTRIBUTE filters for
+ * SERVICE / LAYER / LUCENE / TRAVERSE / etc. to count along any
+ * axis you care about.
+ */
+{
+  "filter": {
+    /*
+     * EMPTY drops the unioned vertex set. The analytics survive.
+     */
+    "op": "EMPTY",
+    "input": {
+      /*
+       * OR composes multiple branches — each branch runs its own
+       * COLLECT_COUNTS over a distinct vertex slice and emits its
+       * own analytic. The OR's vertex output is the union of
+       * branch outputs, but EMPTY makes that irrelevant.
+       *
+       * Important: each COLLECT_COUNTS needs a UNIQUE `id`. Use
+       * something stable you can match against when reading the
+       * analytics back (e.g. `count:host`, `svc:42`, `layer:apm`).
+       */
+      "op": "OR",
+      "input": [
+        {
+          "op": "COLLECT_COUNTS",
+          "id": "count:host",
+          "input": {
+            "op": "ATTRIBUTE",
+            "expressions": [
+              { "name": "type", "operator": "IN", "values": ["HOST"] }
+            ]
+          }
+        },
+        {
+          "op": "COLLECT_COUNTS",
+          "id": "count:agent",
+          "input": {
+            "op": "ATTRIBUTE",
+            "expressions": [
+              { "name": "type", "operator": "IN", "values": ["AGENT"] }
+            ]
+          }
+        },
+        {
+          "op": "COLLECT_COUNTS",
+          "id": "count:all",
+          "input": { "op": "ALL" }
+        }
+      ]
+    }
+  },
+  "limit": 1
+}

package/dist-node/52-collect-counts-bulk.tas.data-store-tmd-csyzj189.json

@@ -0,0 +1,4 @@
+{
+  "description": "Bulk count probe — multiple COLLECT_COUNTS via OR composition, one round trip per N counts",
+  "tags": ["tas", "analytics", "collect-counts", "or-composition", "discovery"]
+}

package/dist-node/53-collect-attributes-by-type.tas-cw0285hx.md

@@ -0,0 +1,71 @@
+# 53-collect-attributes-by-type (TAS)
+
+## Purpose
+
+Bucket every vertex in the tenant by its `type` attribute and get the per-value count in one query — a complete "what kinds of entities are here, and how many of each?" histogram. Companion to `COLLECT_COUNTS`:
+
+- `COLLECT_COUNTS` — "how many?"
+- `COLLECT_ATTRIBUTES` — "how many of each value?"
+
+Run this on a new tenant to get the type breakdown without iterating per-type queries.
+
+## Query Construction
+
+Two ops:
+
+1. `EMPTY` — drop the actual vertex set; keep the analytic.
+2. `COLLECT_ATTRIBUTES` — for each vertex in `input`, record its value of `attributeName` and tally how many vertices share each distinct value.
+
+`attributeName: "type"` makes this a type histogram. Swap for any attribute key — `"agent"` for an agent-name histogram, `"layer"` for a layer histogram, `"hostname"` for a hostname histogram, etc.
+
+`input: { op: "ALL" }` runs the histogram over every vertex. Replace with a more specific filter (`SERVICE`, `LAYER`, `ATTRIBUTE`, `TRAVERSE`) to scope the histogram to a population.
+
+## API Surface Exercised
+
+- **EMPTY**: drop the vertex set; keep analytics. As in `51` and `52`.
+- **COLLECT_ATTRIBUTES**: analytic op. Required: `id`, `attributeName`. Optional knobs:
+  - `layer` — restrict collection to one layer
+  - `includeIds: true` — also return `vertexIds[]` per bucket (handy when you want to drill into one without re-querying)
+  - `caseInsensitive: true` — dedupe value strings case-insensitively
+  - `skipBackends: true` — exclude backend-type vertices
+
+## Expected Output
+
+```json
+{
+  "vertices": [],
+  "edges": [],
+  "analytics": [
+    {
+      "t": "COLLECT_ATTRIBUTES",
+      "id": "type-histogram",
+      "values": [
+        {
+          "attribValue": "k8s_CONTAINER",
+          "occurances": 257,
+          "alerts": 0,
+          "cautionAlerts": 0,
+          "dangerAlerts": 0,
+          "vertexIds": null
+        },
+        { "attribValue": "k8s_POD",        "occurances": 192, "alerts": 0, "cautionAlerts": 0, "dangerAlerts": 0, "vertexIds": null },
+        { "attribValue": "GENERICFRONTEND","occurances": 144, "alerts": 0, "cautionAlerts": 0, "dangerAlerts": 0, "vertexIds": null }
+      ]
+    }
+  ]
+}
+```
+
+Note the canonical wire fields are `attribValue` (not `attributeValue`) and `occurances` (not `occurrences`) — both typos are baked into the Java model. Match the wire form exactly.
+
+Each value entry also carries `alerts` / `cautionAlerts` / `dangerAlerts` (per-bucket alert counts inherited from `TasGroupingAlertStatistics`) and a `vertexIds` field that's `null` unless `includeIds: true` is set on the COLLECT_ATTRIBUTES op. The alert counts are usually `0` on tenants without a configured alarm pipeline.
+
+## What the Results Tell You
+
+A complete profile of what's in the tenant, by entity kind. Concretely:
+
+- A "what's deployed?" inspection picks out the dominant types (k8s heavy? agent heavy? business-transaction heavy?) without needing to know the type vocabulary up front.
+- An adapter that styles a graph by type can pre-allocate per-type style rules from this histogram, sized to actual cardinality.
+- Anomaly detection: comparing the histogram across time reveals onboarded / offboarded entity classes — a tenant that grew a `MYSQL_DB` bucket overnight just connected a database collector.
+
+The pattern generalizes. Same shape with `attributeName: "agent"` gives you a load distribution across agents. With `attributeName: "SourceProduct"` (and a population that has it), you get a per-product entity census.

package/dist-node/53-collect-attributes-by-type.tas.data-store-fvjge4yr.json5

@@ -0,0 +1,65 @@
+/*
+ * Histogram-by-attribute — `COLLECT_ATTRIBUTES` over a population
+ * groups vertices by a chosen attribute and returns the per-value
+ * occurrence count. Companion to COLLECT_COUNTS:
+ *
+ *   COLLECT_COUNTS         — "how many?"
+ *   COLLECT_ATTRIBUTES     — "how many of each value?"
+ *
+ * Output entry shape (under `result.analytics[]`):
+ *
+ *   {
+ *     t: "COLLECT_ATTRIBUTES",
+ *     id, layer?,
+ *     values: [
+ *       { attribValue, occurances, vertexIds? },
+ *       ...
+ *     ]
+ *   }
+ *
+ * Note the canonical wire field is `attribValue` (not
+ * `attributeValue`) and `occurances` (not `occurrences`) — both
+ * are typos baked into the Java model. Match exactly.
+ *
+ * The example below buckets every vertex in the tenant by its
+ * `type` attribute, returning a complete type histogram in a
+ * single query — useful as a "what's in this tenant?" probe.
+ */
+{
+  "filter": {
+    /*
+     * EMPTY drops the actual vertex set so the response is just
+     * the histogram. Drop EMPTY if you want both the vertices
+     * AND the histogram in one shot — analytics flow through
+     * regardless of whether vertices reach the client.
+     */
+    "op": "EMPTY",
+    "input": {
+      /*
+       * COLLECT_ATTRIBUTES — analytic pass-through. For each
+       * vertex in `input`, record its value of `attributeName`
+       * and tally how many vertices share it.
+       */
+      "op": "COLLECT_ATTRIBUTES",
+      "id": "type-histogram",
+      /*
+       * `attributeName` selects which attribute's values to
+       * collect. "type" gives a type histogram; "agent" gives an
+       * agent-name histogram; any attribute key works.
+       */
+      "attributeName": "type",
+      /*
+       * Optional knobs (omitted here):
+       * - `layer`: restrict collection to one layer
+       * - `includeIds: true`: also return `vertexIds[]` per value
+       *   (use when you want to drill into a specific bucket
+       *   without re-querying)
+       * - `caseInsensitive: true`: dedupe values case-insensitively
+       */
+      "input": {
+        "op": "ALL"
+      }
+    }
+  },
+  "limit": 1
+}

package/dist-node/53-collect-attributes-by-type.tas.data-store-tmd-274qrd8f.json

@@ -0,0 +1,4 @@
+{
+  "description": "Type histogram via COLLECT_ATTRIBUTES — group every tenant vertex by its `type` attribute, get per-value counts in one query",
+  "tags": ["tas", "analytics", "collect-attributes", "discovery", "histogram"]
+}

package/dist-node/README-ghxecaz0.md

@@ -0,0 +1,84 @@
+# investigate (Claude Code plugin)
+
+The `investigate@dx-do` plugin — for asking a DXO2 tenant investigative questions in natural language ("are there any hosts with high CPU right now?", "which services depend on host X?", "where's the noise coming from?") and having Claude carry the conversation through scope-clarification → discovery → query authoring → UI / analyzer handoff.
+
+Lives under [`@dx-do/claude`](../README.md) — the umbrella package that hosts all dx-do Claude Code plugins.
+
+## What you get
+
+- **`dx-do-query` MCP server** — auto-wired at plugin enable time. 21 tools across 4 modules (discovery, corpus, datastore, ui — see `dx-do help agentic-mcp`). Corpus tools surface 5 entities, 14 cookbooks, and 29 worked-example queries shipped via `@dx-do/corpus`.
+- **`investigator` skill** — auto-loaded summary that reaches into the corpus for the right cookbook / entity / example before authoring a query. Teaches the decision tree, schema landmines, handoff phrasing.
+
+(Sibling skills planned in this same plugin: `analyzer` for thresholding/anomaly work on a saved query's data, `organizer` for curating the user's saved-query catalog.)
+
+## Prerequisites
+
+1. **A `dx-do` binary the plugin can find.** The plugin's MCP server entry resolves `${DXDO_BIN:-dx-do}` — so either:
+   - Set `DXDO_BIN=/path/to/your/dx-do` in your shell environment (point it at `packages/cli/dist-bun/dx-do` from a source checkout if you don't want a global install), OR
+   - Put `dx-do` on `$PATH` the conventional way: `sudo cp packages/cli/dist-bun/dx-do /usr/local/bin/dx-do && sudo chown $USER /usr/local/bin/dx-do` (the chown is required on macOS Sequoia or AMFI SIGKILLs the binary), OR
+   - npm-installed: `npx @dx-do/cli` works once `@dx-do/cli` is published.
+
+   `DXDO_BIN` is the lowest-friction option for source-checkout devs — no `sudo`, no `/usr/local/bin/` mutation, and the binary always points at whatever you most recently rebuilt under `packages/cli/dist-bun/`.
+2. **A tenant config** at `~/.dxdo/<alias>.dxo2.config.json`. Default plugin invocation uses `default`; override with `DXDO_CONFIG_ALIAS=<your-alias>` in your shell environment before launching Claude Code.
+
+> **About the experimental gate.** `dx-do agentic mcp` (and `dx-do ui start`) are currently marked experimental. The plugin's `plugin.json` already sets `DXDO_ENABLE_EXPERIMENTAL_COMMANDS=true` in the MCP-server spawn env, so users do **not** need to do anything special — Claude Code spawns the subprocess with the gate open. The same env var is needed if you ever invoke `dx-do agentic extract-claude-marketplace` from the shell yourself; see the install section below.
+
+## Install — for users with the `dx-do` binary
+
+The marketplace + this plugin are embedded in every `dx-do` binary. Extract once (the env var opens the experimental gate so the command runs):
+
+```sh
+DXDO_ENABLE_EXPERIMENTAL_COMMANDS=true \
+  dx-do agentic extract-claude-marketplace base-directory=~/
+```
+
+Then in a Claude Code session:
+
+```
+/plugin marketplace add ~/dx-do-claude-marketplace
+/plugin install investigate@dx-do
+/reload-plugins
+```
+
+The extract command prints the exact slash-command sequence so you can copy-paste it into Claude Code. Plugin management is interactive-only — there is no shell `claude plugin install`.
+
+## Install — source-checkout dev
+
+```
+/plugin marketplace add /Users/$USER/github/dx-do-mono/packages/claude
+/plugin install investigate@dx-do
+/reload-plugins
+```
+
+(`packages/claude/` already has `.claude-plugin/marketplace.json` + per-plugin subdirs — same layout extract produces.)
+
+## Verify
+
+After install, in a fresh Claude Code session:
+
+```
+"What entities can you ground me in for the bound tenant?"
+```
+
+Expected: Claude invokes the `investigator` skill (visible in the skill list), calls `corpus_sections` + `corpus_list('entities')`, and surfaces the universe / service / dxi_service / host / agent entries.
+
+If Claude doesn't reach for the skill automatically, the description trigger isn't strong enough — file a follow-up.
+
+## What's in here
+
+```
+.claude-plugin/
+  plugin.json                     ← plugin manifest (mcpServers + metadata)
+skills/
+  investigator/
+    SKILL.md                      ← the auto-loaded investigator skill
+```
+
+The skill points at content in `@dx-do/corpus` for the rich grounding (cookbooks, entities, queries). The MCP server `dx-do-query` (from `@dx-do/ui`) is the agent's tool surface.
+
+## Related
+
+- [`@dx-do/claude` README](../README.md) — why one package, many plugins.
+- `dx-do help agentic-mcp` — full tool surface + module flags.
+- `@dx-do/corpus` — `cookbooks/`, `entities/`, `queries/` content the skill references.
+- `~/.claude/plans/` (this Mac) — milestone plan.