metergraph-cli 0.2.1 → 0.2.2

package/README.md

@@ -21,7 +21,8 @@ Published on npm as `latest`. See the [changelog](https://github.com/metergraph/
 ## Quickstart
 
 **1. Set up the project.** Run this in your project directory. It opens your browser to
-sign in and choose a workspace, asks a workspace member to approve an ingest-only key,
+sign in and choose a workspace, asks a workspace member to approve an ingest-only key
+(on the same page as sign in, where the service supports it),
 writes `METERGRAPH_APP_TOKEN` and `METERGRAPH_INGEST_URL` to a private `.env`, and
 installs the skill for your coding agent.
 
@@ -47,11 +48,12 @@ Then read what Metergraph has recorded:
 
 ```sh
 npx --yes metergraph-cli@latest usage --days 7      # calls, errors, cost and tokens per route per day
+npx --yes metergraph-cli@latest usage --group-by route --today   # most expensive route today (UTC)
 npx --yes metergraph-cli@latest traces --limit 20   # one page of trace metadata
 ```
 
 To install it globally instead, run `npm install -g metergraph-cli@latest`. The command is
-`metergraph`. Pin an exact version, such as `metergraph-cli@0.2.1`, when a
+`metergraph`. Pin an exact version, such as `metergraph-cli@0.2.2`, when a
 script must not change with the `latest` tag. Previews use the `next` tag.
 
 ## Requirements
@@ -67,8 +69,11 @@ Sign in needs a service that offers Metadata-only CLI grants and grant revocatio
 service without them is reported as unsupported, and the CLI never falls back to
 broader access. `setup` also needs the deployment's ingest bootstrap API and approval by
 a workspace member. Sign in needs a browser on the same machine. From SSH sessions,
-cloud development environments and CI, `login` and `setup` hand off to a local machine
-instead (exit 6).
+cloud development environments and CI, `login` and `setup` exit 6 with a structured
+`next_action`: a person creates a coding-agent key with Metadata access on the Keys
+page and saves it as the secret `METERGRAPH_AGENT_TOKEN`, and the read commands use it
+after verifying the origin, workspace, scope and capabilities. Ingest setup still runs
+on a local machine.
 
 ## Using it with a coding agent
 
@@ -132,8 +137,8 @@ Suggested `AGENTS.md` or `CLAUDE.md` lines for a project that uses Metergraph:
 | --- | --- | --- |
 | `setup` | Sign in, choose a workspace, write the ingest key to `.env`, record the repository, install the skill | Yes |
 | `verify` | Confirm that one exact trace, by trace ID or request ID, reached the workspace | Yes |
-| `usage` | Daily calls, errors, cost, tokens and latency per route | Yes |
-| `traces` | One page of trace metadata, with a cursor for the next page | Yes |
+| `usage` | Daily calls, errors, cost, tokens and latency per route, or cost grouped by provider, model, route or UTC day with exact filters, rankings and a prior-period comparison; filtered by exact metadata or grouped by one metadata key | Yes |
+| `traces` | One page of trace metadata, filtered by route, status or exact metadata, with a cursor for the next page | Yes |
 | `routes` | Routes with call counts and evaluation contract status | Yes |
 | `status` | Whether the project is signed in, and to which workspace | Yes |
 | `context` | Workspace details and retention | Yes |
@@ -170,7 +175,7 @@ Exit codes are stable. Changing one is a breaking change. Codes 10 to 18 are not
 | 13 | `revocation_unconfirmed` | Local credentials were removed, but the service did not confirm that the grant was revoked. |
 | 14 | `capability_unavailable` | The service does not make this read available to the project's Metadata grant. No data was read. |
 | 15 | `permission_denied` | The service refused this read for the signed in grant, for example for a missing scope or permission. |
-| 16 | `rate_limited` | The service asked the CLI to slow down. Nothing was retried. Try again later. |
+| 16 | `rate_limited` | The service asked the CLI to slow down. Try again later. Only setup retries, after a short Retry-After, to keep its approval. |
 | 17 | `cancelled` | A read command was interrupted before it finished. Read commands never change workspace configuration or telemetry. |
 | 18 | `action_required` | A person must act before the command can finish; `data.next_action` says what to do. `login` and `setup` with `--json --no-browser` exit with this as soon as an approval URL exists (`next_action.kind: "open_url"`), while a background process waits for the approval until `--timeout-ms`. After approval, run the same command again to continue. |
 

package/assets/skill/SKILL.md

@@ -57,6 +57,53 @@ pass the same `--workspace` UUID each time, and give each repository its own
 identity. The SDK warning that repository identity is not configured does not
 stop capture.
 
+## Pick the CLI path for where the agent runs
+
+Check `metergraph --help` first. If the read commands' help lists
+`--agent-token-file`, the CLI also accepts a coding-agent key with Metadata
+access from the `METERGRAPH_AGENT_TOKEN` environment variable. Use one sequence:
+
+| Where the agent runs | Sequence |
+|---|---|
+| Local shell, hosted, new workspace | `metergraph setup --runtime local --client <client> --json --no-browser`, rerun after each approval, then `metergraph status --json`. Add `--signup` for a person with no hosted account. |
+| Local shell, hosted, existing workspace | `metergraph login --runtime local --workspace <uuid> --json --no-browser`, then `metergraph status --json`. |
+| Local shell, customer-local or customer-owned AWS | `metergraph setup --runtime local --client <client> --deployment customer-local` (or `byoc`) `--url <origin> --workspace <uuid> --json --no-browser`. Follow its `next_action` for each prerequisite, and add `--confirm-prerequisites` only after the person confirms them. Then `metergraph status --json`. Without `--deployment`, setup and login go to the hosted service. |
+| Local container (Docker, local dev container) | As a local shell. If the browser cannot reach the container's sign in callback, use the key sequence below. |
+| SSH, Codespaces, Gitpod, Cloud Shell, remote dev container, CI: hosted, customer-local or customer-owned AWS | The person signs in (or signs up, on the hosted service only) on their own device, opens the Keys page of the deployment and workspace the agent should read, creates a coding-agent key with Metadata access, and saves it in this environment's secret settings, or as a CI secret, named `METERGRAPH_AGENT_TOKEN`. Then run `metergraph status --json` and `metergraph usage --json`. Add `--workspace <uuid>` to make a key for another workspace fail. For a non-hosted deployment, pass `--url <origin>` (or set `METERGRAPH_URL`) with its address. |
+| Any runtime: open-source self-hosted server | The CLI read commands do not support the open-source server; use its MCP route (below). There are no accounts and no Keys page: the operator gives the person one of the server's `MG_AGENT_TOKENS` values for the client's private MCP settings. |
+| Has a Metadata key but no saved sign in | The same key sequence. If the project has a `.metergraph/project.json`, it pins the origin and workspace the key must match. |
+
+`.metergraph/project.json` names the deployment origin and workspace ID. In a
+public repository, keep it untracked (for example in `.gitignore`) and do not
+commit it: that would publish the workspace ID. In CI for a public repository,
+the read commands' JSON includes workspace IDs and per-route usage: write it to a file or
+a masked step instead of the public job log, and print only what the person
+needs.
+
+Before answering a cost question from the CLI, confirm the workspace and what
+it offers: `metergraph status --json` (the verified workspace must be the one
+the person means) and `metergraph capabilities --json`. Then run the smallest
+bounded `usage` read that answers it. Grouped usage needs a CLI that has it:
+run `metergraph help usage` first, and use `--group-by` only when that help
+lists it (for example `metergraph usage --group-by route --today --json` for
+the most expensive route today). An older CLI has only
+`metergraph usage --days N --json` (cost per route and day); say that grouping
+by provider, model or metadata needs a newer CLI or the
+`metergraph_get_usage_aggregates` tool, and do not invent flags. Grouped
+usage windows are UTC days; plain `usage --days N` is the last N x 24 hours,
+rolling. `metergraph-investigate` covers the rest. A deployment without grouped
+usage exits 14 with a `next_action` that names the read it supports.
+
+When `login`, `setup` or a read cannot finish where it runs, it prints
+`data.next_action`. Follow it: `use_agent_key` lists the person's steps and the
+commands to run afterwards; `replace_agent_key`, `use_metadata_only_key` and
+`use_workspace_key` mean the key was refused, was broader than Metadata, or
+belongs to another workspace. Never ask the person to paste the key into chat or
+a command, and never put it in a project file. Ingest setup cannot run over SSH,
+in a cloud workspace or in CI; it runs on the person's machine. The Metadata key
+is separate from the application's ingest key and never replaces it. Debug and
+Replay keys are refused by the CLI, not reduced.
+
 ## Route honestly
 
 | Client and runtime | Hosted | Customer-local bundle | Customer AWS | Open source self-hosted |
@@ -103,10 +150,12 @@ rather than improvising the analysis steps.
 
 ## When already connected: bounded investigation
 
-1. Call `metergraph_get_workspace_context` and `metergraph_get_capabilities` first. Verify the intended workspace, deployment profile, available tools, required scopes and privacy classes. Stop on wrong workspace, unavailable capabilities or failed authorization.
-2. Confirm the question, route and explicit time window. Choose the smallest available tool: bounded usage/route metadata for aggregate questions, incidents for known anomalies, or `metergraph_query_traces` with a small limit (start with 1) for a failed/anomalous trace. Follow cursors only within the agreed bound. Never request generic SQL or unbounded data.
+Read through the `metergraph` CLI first when it is installed and can read the workspace: it returns the same Metadata evidence as the MCP tools in far fewer tokens. Use the MCP tools for what the CLI does not cover (incidents, ingestion health, reports, retained content and replay) and in clients with no shell. Being connected means either one; stop for setup only when neither can read the workspace.
+
+1. Confirm the workspace and what it offers. With the CLI: `metergraph status --json` (continue when `data.authenticated` is true and `data.workspace.match` is true. When `match` is null because no workspace was pinned, name `data.workspace.actual` and continue only after the person confirms it is the one they mean. Otherwise follow `data.next_action`) and `metergraph capabilities --json`. With MCP: `metergraph_get_workspace_context`, then `metergraph_get_capabilities`. Verify the intended workspace, deployment profile, available reads, required scopes and privacy classes. A wrong workspace or failed authorization on one path is a reason to use the other path when it can read the intended workspace; stop when neither can, or when the capability the question needs is unavailable.
+2. Confirm the question, route and explicit UTC time window. Choose the smallest available read, and always pass `--json` to the CLI: grouped usage (`metergraph usage --group-by ... --json`, or `metergraph_get_usage_aggregates`) or `metergraph usage --days N --json` / route metadata for aggregate questions, `metergraph traces --days N --limit 1 --json` with `--route` when known and `--status error` only for a failed trace (or `metergraph_query_traces` with a small limit, which also takes an exact trace or request ID) for a failed or anomalous trace, and the incidents tool for known anomalies. Check that `metergraph help <command>` lists an option before using it, and use the matching MCP tool when it does not. Follow cursors only within the agreed bound. Never request generic SQL or unbounded data.
 3. Start with metadata. Retained-content debugging and report evidence are separate content-bearing tools; confirm the user's content intent and capability before calling them. Replay is a separate scope and can send data to a provider and spend money. Obtain explicit bounded execution/data-egress authority before any replay. Read access grants no eval-write, analysis-run or production-mutation authority.
-4. Explain the failure or anomaly using only returned evidence. Cite workspace, time window, provenance, trace/report IDs, completeness/coverage, warnings and working app links when returned. Do not fabricate links. Distinguish no data, incomplete evidence, unavailable capability, classification pending, stale/mismatched identity, failed analysis and missing report. An empty result alone does not prove absence of traffic.
+4. Explain the failure or anomaly using only returned evidence. Cite workspace, time window, provenance, trace/report IDs, completeness/coverage, warnings and working app links when returned. Do not fabricate links. Distinguish no data, incomplete evidence, unavailable capability, classification pending, stale/mismatched identity, failed analysis and missing report. An empty result alone does not prove absence of traffic. Never conclude that a commit, deploy or config change did or did not change cost from source code or a git diff alone; a diff is a hypothesis until bounded usage reads for the same route before and after the change reached production agree, with completeness and warnings cited.
 5. An optional approved replay must be eligible, bounded and non-persistent. Do not claim that it changed production telemetry or fixed the application. Refuse autonomous dashboard mutations or production configuration changes.
 
 For an empty workspace, use https://www.metergraph.dev/docs/agents/instrument-a-repo/. If `metergraph setup` already ran in this project, it delivered the ingest credential: the project's `.env` holds `METERGRAPH_APP_TOKEN` and `METERGRAPH_INGEST_URL`. Use them; do not ask for or create another key, and never print their values. The SDK reads the process environment, not `.env`, so load it when you run the application (for example `set -a; . ./.env; set +a`, python-dotenv or `node --env-file=.env`). Otherwise confirm the ingestion destination and obtain a separate ingest credential securely. Ask before running anything that calls a paid model provider, and do not initiate provider calls or paid work merely to validate setup. Confirm the exact trace with `metergraph verify`; if the CLI is not installed, or `metergraph --version` lacks `verify`, use `npx --yes metergraph-cli@latest verify`. Ingestion accepted, processed, retained content, classification readiness and analysis readiness are distinct states. Label synthetic/demo fixtures; they do not prove a first real application trace.

package/assets/skill/manifest.json

@@ -3,7 +3,7 @@
   "name": "metergraph",
   "file": "SKILL.md",
   "source_url": "https://www.metergraph.dev/SKILL.md",
-  "sha256": "d527a67efc42a55245b9c2c8fd2687c1f31f553e154a6242d0f31466993e314e",
-  "size": 13666,
-  "revision": "sha256-d527a67efc42"
+  "sha256": "ebf784673eff0280d85974504f93c683a1dabfb54156c9d27e091131462e9d5f",
+  "size": 19764,
+  "revision": "sha256-ebf784673eff"
 }

package/assets/skills/manifest.json

@@ -1,13 +1,13 @@
 {
   "manifest_version": 1,
   "repository": "metergraph/skills",
-  "commit": "839da0fc82c331598db78022610620390a81703a",
+  "commit": "39411ce1eceed6929ab3e5c4c20649f02e8eabb4",
   "skills": [
     {
       "name": "metergraph-analyze",
-      "sha256": "e8bf1debf62aa7d33d3dd363e5d95d8f781e8ca23cde4619b5bb4133dd47a7a5",
-      "size": 9360,
-      "revision": "sha256-e8bf1debf62a"
+      "sha256": "c45756ad1d33a360c7c845ca299d8c1ab1e2b8162865f635bc25c78358c2a1e6",
+      "size": 12148,
+      "revision": "sha256-c45756ad1d33"
     },
     {
       "name": "metergraph-candidates",
@@ -23,9 +23,9 @@
     },
     {
       "name": "metergraph-investigate",
-      "sha256": "775dbe7ca1100b17638d0905302ef1324694a60b90372c6c3df7b598a8f70438",
-      "size": 6091,
-      "revision": "sha256-775dbe7ca110"
+      "sha256": "470579faf9e8b5f1a562060d51ec5a71d1b9c47213403a2447dd40af56a74869",
+      "size": 19331,
+      "revision": "sha256-470579faf9e8"
     },
     {
       "name": "metergraph-iterate",
@@ -47,15 +47,15 @@
     },
     {
       "name": "metergraph-onboarding",
-      "sha256": "6e6f418933f37b34437035ab3171344d43f37dee3770815b19f97efb62e5f1d1",
-      "size": 10267,
-      "revision": "sha256-6e6f418933f3"
+      "sha256": "409d105f3b042514fd347a1fffc5489a94c01d1bc8aac55800e8c9f13a66a2c1",
+      "size": 10751,
+      "revision": "sha256-409d105f3b04"
     },
     {
       "name": "metergraph-report",
-      "sha256": "58add8f6a32191e6fc01ca533a700e190a8e6da412e619bca38c65a481ea9fb5",
-      "size": 4521,
-      "revision": "sha256-58add8f6a321"
+      "sha256": "0cdbeb684c4f7f87932784db832f376cff984fe0220a1167f1a73edd550450b7",
+      "size": 5471,
+      "revision": "sha256-0cdbeb684c4f"
     },
     {
       "name": "metergraph-workloads",

package/assets/skills/metergraph-analyze/SKILL.md

@@ -116,14 +116,72 @@ restate what you are starting and proceed. Otherwise ask and wait.
    the returned run instead of starting another. On `precondition_failed`,
    report the `reason` and stop.
 4. Poll `metergraph_get_analysis_run` with the `run_id` at a modest interval
-   (about every 30 to 60 seconds) and tell the user the status as it changes.
-   Do not restart a run because it is slow. Stop polling when the status is
-   final, and say if it failed, with its `error_code`.
+   (about every 30 to 60 seconds). Do not restart a run because it is slow.
+   Stop polling when the status is final, and say if it failed, with its
+   `error_code`.
+5. After the start and after every poll, write a progress report in the
+   shape shown under "Show run progress" before you wait, set a timer or
+   schedule the next check. The start response already carries
+   `run.stages`, so the reply that starts the run has one too. A one-line
+   status such as "The run is exporting; I'll check again in a minute" is
+   not a progress report. The graphic is required every time.
+
+## Show run progress
+
+Draw the stages from `run.stages.items`, in the order returned. Use each
+item's `state` exactly as given. Never decide a stage's state from `status`,
+trace names or the report.
+
+Render one line with a marker per state: `✓` completed, `●` current, `✗`
+failed, `–` skipped, `○` not started. For example:
+
+```
+✓ queued → ✓ exporting → ✓ analyzing → ● classified → ○ importing → ○ completed
+```
+
+If the client can draw a richer inline graphic, you may use one. Keep the
+same order and states, and make the states distinct without relying on
+colour alone.
+
+Under the graphic, always write a plain-text line that says the same thing:
+the stages that are done, the current stage, and the stages still to come.
+
+Every check-in, including the reply that starts the run, has this shape:
+
+````
+Run 3f2a… at 19:34 UTC:
+
+```
+✓ queued → ✓ exporting → ✓ analyzing → ● classified → ○ importing → ○ completed
+```
+Done: queued, exporting, analyzing. Now: classified, since 19:23 UTC
+(11 minutes, unchanged since the last check). Still to come: importing,
+completed. No error, no report yet. Next check in about a minute.
+````
+
+- **Time in the current stage.** Take it from the current item's
+  `entered_at` and the response's `provenance.generated_at`, which is the
+  check time. Say when you last checked, and say plainly when the stage has
+  not changed since the last check. Never give a percentage, an ETA or a
+  time remaining. The run data supports neither.
+- **Finished.** On `completed`, draw the items as returned, like any other
+  check: the stages the run passed through are `✓`, and a stage it never
+  entered stays `–` skipped. When `report.available` is true, read the
+  report (step 6) and give any link it returns exactly as given. When it is
+  false, say plainly that no report exists yet.
+- **Failed.** On `failed`, mark the stage it stopped in with `✗`, give the
+  `error_code`, and leave the later stages `○`.
+- **No stage data.** When `run.stages.available` is false, or `stages` is
+  missing, show no graphic. Say the stage breakdown is unavailable for this
+  run (`unavailable_reason`, when present). Report the `status`, the
+  timestamps, the `error_code` if the run failed, and whether a report
+  exists. Never mark stages complete by inference.
 
 ## 6. Read the report and recommend
 
 When `report.available` is true, call `metergraph_get_report` with
-`report.analysis_id`. Use the summary format and report link in
+`report.analysis_id`. While it is false, do not look for a report under
+another or guessed ID. Use the summary format and report link in
 `metergraph-report` when it is installed. Present:
 
 - the report `outcome`: `opportunities`, `no_opportunities`,

package/assets/skills/metergraph-investigate/SKILL.md

@@ -1,50 +1,183 @@
 ---
 name: metergraph-investigate
-description: Investigate a failed or anomalous LLM trace, usage spike or incident through an already connected Metergraph Agent Access server, answering only from bounded, cited evidence. Use after setup is verified; use the metergraph skill first when not connected.
+description: Investigate a failed or anomalous LLM trace, usage spike, cost question (which route, provider or model costs most, a daily trend, a change from the prior period), incident or whether a code change moved cost, reading through the metergraph CLI first (fewer tokens) or a connected Metergraph Agent Access MCP server, answering only from bounded, cited evidence. Use after setup is verified; use the metergraph skill first when neither the CLI nor MCP can read the workspace.
 ---
 
 # Investigate with Metergraph evidence
 
 This skill expands the bounded investigation section of the public `metergraph`
-skill. It adds no tools, scopes or authority. When no Metergraph MCP server is
-connected, or the user has not chosen a client, runtime and deployment, stop and
-use the `metergraph` skill for setup routing. Never ask for, echo or store a
+skill. It adds no tools, scopes or authority. Never ask for, echo or store a
 key.
 
+Read through the `metergraph` CLI first when it is installed and can read the
+workspace: it returns the same Metadata evidence as the MCP tools in far fewer
+tokens. Use the MCP tools for what the CLI does not cover (incidents, ingestion
+health, reports, retained content and replay) and in clients that have no
+shell. Stop and use the `metergraph` skill for setup routing only when neither
+the CLI nor a Metergraph MCP server can read the workspace, or the user has not
+chosen a client, runtime and deployment.
+
 ## 1. Discover before reading data
 
+**With the CLI** (preferred when `metergraph --help` lists `status`,
+`capabilities` and `usage`; an older CLI can run but lack them):
+
+1. Run `metergraph status --json`. Continue when it exits 0 with
+   `data.authenticated: true` and `data.workspace.match: true`. When `match`
+   is null because no workspace was pinned (a coding-agent key without
+   `--workspace`), name `data.workspace.actual` and continue only after the
+   person confirms it is the workspace they mean. When it prints
+   `data.next_action` (for example sign in again, or the coding-agent Metadata
+   key path for a remote session), follow it; never ask for the key in chat.
+2. Run `metergraph capabilities --json` and build the plan from
+   `data.result.agent` (each capability's `available`, `privacy_class` and
+   `required_scope`) and `data.result.bounds` (`max_days`, `max_rows`).
+3. Before using any option, check that `metergraph help <command>` lists it.
+   An option an older CLI lacks is a reason to use the matching MCP tool, not
+   to guess a flag. Always pass `--json`: the evidence is under `data.result`,
+   with `data.notices` and `data.next_action` beside it, and the exit code is
+   the outcome (for example 14 when the deployment does not offer the read).
+
+**With MCP** (no CLI, no shell, or a read the CLI does not offer):
+
 1. Call `metergraph_get_workspace_context`, then `metergraph_get_capabilities`.
    Do not call any other Metergraph tool first.
-2. Confirm with the user that `provenance.workspace_id`, the workspace name and
-   `provenance.deployment_profile` match the installation they intend. A staging
-   or demo workspace is not their production workspace. Stop on a mismatch,
-   an authorization error, or revoked or expired access, and tell the human to
-   reconnect through their client's secure flow.
-3. Build the tool plan only from what the server returns: the workspace
+2. Build the tool plan only from what the server returns: the workspace
    context's `access.scopes`, and each capability under the capabilities
    response's `agent` object with its `available`, `privacy_class` (metadata,
    content or replay), `required_scope`, `mutates` and `external_calls`, plus
    `bounds` (`max_days`, `max_rows`). Treat the tools your client lists as the
-   only callable tools. A tool or capability that is absent, or has
-   `available: false`, is a blocker to report, not something to
-   guess, retry under another name or replace with a dashboard API, generic SQL
-   or a shell command. Some deployments are content-blind or have no replay,
-   incidents, ingestion health or reports.
+   only callable tools.
+
+Either way, confirm with the user that the workspace ID, the workspace name
+and the deployment profile match the installation they intend. A staging or
+demo workspace is not their production workspace. A mismatch, an
+authorization error, or revoked or expired access belongs to that one path:
+when the CLI cannot read the intended workspace but a connected MCP server
+can (or the other way round), use the path that can. Stop and tell the human
+to reconnect through their client's secure flow only when neither the CLI nor
+MCP can verify the intended workspace. A capability that is absent, or
+has `available: false`, is a blocker to report, not something to guess, retry
+under another name or replace with a dashboard API, generic SQL or an ad hoc
+shell command. Some deployments are content-blind or have no replay,
+incidents, ingestion health or reports.
 
 ## 2. Fix the question and the bound
 
-Restate the question, the route or workload if known, and an explicit window in
-whole days (tools accept `days` from 1 to 90; default to the shortest window
-that answers the question). Then choose the smallest tool that can answer:
+Restate the question, the route or workload if known, and an explicit UTC
+window. For grouped usage, windows are UTC: `days: N` means the current UTC
+day so far plus the `N - 1` whole UTC days before it, so today is always
+partial; `since` (inclusive) and `until` (exclusive) give an exact window.
+Plain `metergraph usage --days N` (no grouping) is instead the last N x 24
+hours, rolling and not aligned to UTC days; say so when you report it. Keep
+every window within 90 days and within the capabilities' `bounds.max_days`.
+Default to the shortest window that answers the question. Then choose the
+smallest tool that can answer:
+
+| Question | CLI (check its help first) | MCP tool | Bound |
+| --- | --- | --- | --- |
+| Which route, provider or model costs most; spend with one provider or model; a daily trend | `metergraph usage --group-by ... --json` with `--route`, `--provider`, `--model` or `--environment` | `metergraph_get_usage_aggregates` with `group_by` and the same exact filters | `--days`/`days` or `--since`/`--until`, small limit |
+| Daily cost per route, when grouped usage is unavailable | `metergraph usage --days N --json` | `metergraph_get_usage` | days, small limit |
+| Which routes exist or are replay eligible | `metergraph routes --json` | `metergraph_list_routes` | none needed |
+| Is data arriving | none; use MCP | `metergraph_get_ingestion_health` | `days` |
+| Known alert or anomaly | none; use MCP | `metergraph_list_incidents` | small `limit` |
+| Cost or calls for one prompt, workflow or other tag value | `metergraph usage --group-by metadata.KEY --json`, or `--metadata KEY=VALUE` | `metergraph_get_usage_aggregates` with `group_by` including `metadata.<key>`, or `metadata` (exact pairs) | days, small limit |
+| One failed call | `metergraph traces --status error --limit 1 --json` (also `--route`, `--metadata`) | `metergraph_query_traces` with `status` set to the failure status, and `route`, `trace_id`, `request_id` or `metadata` | limit 1 to 5 |
+| One costly call (it may have succeeded) | `metergraph traces --route NAME --limit 5 --json` with no `--status`, then compare cost on that page | `metergraph_query_traces` with `route`, `trace_id`, `request_id` or `metadata`, no `status` | limit 1 to 5 |
+| Which routes are slow (route level, not one call) | `metergraph usage --group-by route --sort p95-latency --json`; CLI `traces` returns no latency | `metergraph_get_usage_aggregates` grouped by route | days, small limit |
+| One slow call | none; CLI `traces` has no latency, so ask for its trace or request ID and use MCP, or send the person to the trace in the app | `metergraph_query_traces` with that `trace_id` or `request_id` | limit 1 |
+| A finished analysis | none; use MCP | `metergraph_list_reports`, then `metergraph_get_report` | small `limit` |
 
-| Question | First tool | Bound |
+Use grouped usage (`metergraph usage --group-by`, or
+`metergraph_get_usage_aggregates`) only when capabilities list
+`usage_aggregates` as available. On an older deployment it is absent: say so,
+answer what `metergraph_get_usage` can (cost per route and day), and do not
+rebuild provider or model totals by paging traces.
+
+### Cost questions
+
+`metergraph_get_usage_aggregates` groups calls by any ordered subset of
+`provider`, `model`, `route` and `day` (the call's UTC calendar day), plus at
+most one `metadata.<key>`. Cost is
+attributed per call, so a trace that used two providers adds each call's cost
+to that call's provider. Groups come back highest cost first, at most `limit`
+of them; `totals` cover every matching call whatever the limit. From a shell,
+the `metergraph` CLI sends the same read and prints the same evidence. Check
+`metergraph help usage` first: use these commands only when it lists
+`--group-by`. An older CLI has only `metergraph usage --days N` (cost per route
+and day); use the tool instead, or say a newer CLI is needed.
+
+| Question | Tool arguments | CLI |
 | --- | --- | --- |
-| How much, how many, which route costs most | `metergraph_get_usage` | `days`, small `limit` |
-| Which routes exist or are replay eligible | `metergraph_list_routes` | none needed |
-| Is data arriving | `metergraph_get_ingestion_health` | `days` |
-| Known alert or anomaly | `metergraph_list_incidents` | small `limit` |
-| One failed, slow or costly call | `metergraph_query_traces` with `status`, `route`, `trace_id` or `request_id` | `limit` 1 to 5 |
-| A finished analysis | `metergraph_list_reports`, then `metergraph_get_report` | small `limit` |
+| Most expensive route today | `{"group_by": ["route"], "days": 1}` | `metergraph usage --group-by route --today --json` |
+| Spend with one provider | `{"group_by": ["provider"], "provider": ["<name>"], "days": 7}` | `metergraph usage --group-by provider --provider <name> --days 7 --json` |
+| Spend by model | `{"group_by": ["model"], "days": 7}` | `metergraph usage --group-by model --days 7 --json` |
+| One route's daily trend | `{"group_by": ["day"], "route": ["<route>"], "days": 14}` | `metergraph usage --route <route> --group-by day --days 14 --json` |
+| Cost by prompt ID | `{"group_by": ["metadata.prompt_id"], "days": 7}` | `metergraph usage --group-by metadata.prompt_id --days 7 --json` |
+| Today against yesterday | two reads: `days: 1`, then `since`/`until` for the prior UTC day | `metergraph usage --group-by route --today --compare previous --json` |
+
+Rank only what was returned. When `coverage.rows.truncated` is true (more
+groups matched than `limit`), a ranking by calls, errors or latency covers
+only the listed groups. Before naming a "top" group, raise `limit` to
+`coverage.rows.matched` when that is at most 200 and at most the
+capabilities' `bounds.max_rows`; otherwise narrow the read. Name the latency
+you report:
+`latency.avg_ms` is the mean over `latency.samples` calls that reported one,
+and `latency.p95_ms` is an estimate from a fixed histogram
+(`p95_method: histogram_estimate`), not an exact percentile.
+
+A "costs most" answer needs exact pricing. When `pricing.cost` is
+`lower_bound` (the overall `pricing`, or a group's own), some calls are not
+fully priced, so a group with more unpriced calls can look cheaper than it is.
+Name the group with the highest recorded cost as a lower bound and say the
+ranking is not definitive until pricing is exact; never call it the most
+expensive outright.
+
+A prior-period comparison needs two reads with stated windows. Comparing
+today so far with all of yesterday is not like for like: say so, or compare
+with yesterday up to the same UTC time (`--compare previous-same-time` in the
+CLI). A group missing from a truncated window is unknown, not zero.
+
+A route is not a prompt. One route (for example `support-reply`) can carry
+several prompt IDs in its metadata (SDK tags), and one prompt ID can run on
+several routes. To answer "which prompt costs most", group by the metadata key
+alone, so each prompt is one row across every route. Add `route` to `group_by`
+only to show how a route splits by prompt. Keep the same `days` on every
+follow-up read, so the examples come from the window you just summarised:
+
+```json
+{"name": "metergraph_get_usage_aggregates", "arguments": {"days": 7, "group_by": ["metadata.prompt_id"]}}
+{"name": "metergraph_query_traces", "arguments": {"days": 7, "metadata": {"prompt_id": "reply-v3"}, "limit": 3}}
+```
+
+Metadata values are exact, case-sensitive opaque strings: `reply-v3` does not
+match `reply-v30`, a call without the key never matches a filter, and several
+filter keys must all match. In a read grouped by a metadata key, calls in the
+window that have no value for the grouped key form the group whose value is
+`null`, and `coverage.reasons` names `metadata_key_missing` (or
+`metadata_value_ineligible` for a non-string or oversize value). Report that
+group rather than dropping it. If you also filtered on that same key, no such
+calls remain, so there is no `null` group. A `metadata_key_mostly_missing`
+warning means most calls or cost have no value for the key; say so, and
+suggest checking the key's spelling. `metadata_groups.unlisted` accounts for
+every call not listed with a value: `other_values` (values past the limit, with
+a group count), `missing_key` and `ineligible_value`. Report the spend in
+`missing_key` plus `ineligible_value` as not attributed to any value of the
+key, so a prompt ranking never reads as the whole spend. When
+`coverage.rows.truncated` is true, the listed groups are not the whole window:
+quote `totals` for the window and `coverage.rows.matched` as the number of
+matched groups. That counts groups, not distinct values of the key: with
+`group_by: ["route", "metadata.prompt_id"]` one prompt used on three routes is
+three groups. For a count of distinct values, read with the metadata key as
+the only dimension.
+
+The CLI can run the same reads (`metergraph usage --group-by
+metadata.prompt_id --days 7 --json`, where `--group-by-metadata prompt_id` is
+the same dimension and the way to give a key that contains a comma, and
+`metergraph traces --days 7 --metadata prompt_id=reply-v3 --json`) only in versions that
+have these options. Check that `metergraph usage --help` lists `--group-by`
+(and `metergraph traces --help` lists `--metadata`) before you suggest them,
+and otherwise use the tools above.
 
 Follow `next_cursor` only while you are still inside the agreed bound, and say
 how many pages you read. Never request every trace, every report or unbounded
@@ -69,14 +202,23 @@ point to the human action in the Metergraph app instead.
 
 ## 4. Answer only from returned evidence
 
-Every answer cites, from the tool responses you actually received:
+Every answer cites, from the CLI results or tool responses you actually
+received (a CLI result carries the same fields under `data.result`, plus
+`data.notices`):
 
 - **Workspace**: workspace name and `provenance.workspace_id`, plus
   `deployment_profile`.
-- **Window**: `window.since` to `window.until` (or `days`) for each read.
+- **Window**: `window.since` to `window.until` in UTC (or `days`) for each
+  read, and whether the last day is partial.
 - **Provenance**: the tool name, `provenance.source` and `generated_at`.
 - **Evidence and completeness**: `evidence.rows`, `evidence.complete`,
-  `page.truncated` and whether a `next_cursor` was left unread.
+  `page.truncated` and whether a `next_cursor` was left unread; for usage,
+  `coverage.completeness` with its `reasons`, `coverage.rows.matched` against
+  the rows returned, and whether a total is the whole population
+  (`totals.scope`) or only the returned rows.
+- **Pricing and attribution**: `pricing.cost` (`exact` or a `lower_bound`) and
+  `attribution.level`. A trace cost is a whole-trace total and is never split
+  by provider.
 - **Warnings**: every returned `warnings[].code` with its message. Say "no
   warnings returned" when the list is empty.
 - **Identifiers and links**: trace, request, incident or analysis IDs, and
@@ -87,16 +229,61 @@ window, incomplete or truncated evidence, capability unavailable in this
 deployment, classification pending, ambiguous request match
 (`request_match.ambiguous`), failed analysis, and missing report. An empty page
 does not prove there was no traffic; check ingestion health or a longer bounded
-window before saying so. Do not round, extrapolate or invent totals.
+window before saying so. Do not round, extrapolate or invent totals. Never
+attribute a cost change, or the absence of one, to a code change from source
+code or a git diff; see section 5.
+
+## 5. Code changes and cost: never decide from the diff
+
+When the question is whether a commit, pull request, deploy or config change
+raised, lowered or did not change cost, a git diff is never the evidence. Read
+it to form a hypothesis (a different model, a longer prompt, a new retry loop, a
+changed `max_tokens`, an added tool call), then say it is a hypothesis. Do not
+answer "this commit increased cost", "this commit saved money" or "this commit
+has no cost impact" from code alone, including a diff that touches no model or
+prompt code: wrappers, retries, caching, routing, traffic and provider prices
+change spend without appearing in the diff.
+
+A cost conclusion needs returned Metergraph usage evidence:
+
+1. Establish when the change reached the traffic Metergraph observes, from
+   recorded commit or deployment identity (a deploy record, or the commit the
+   telemetry itself carries). Merge time is not deploy time. Without that
+   record, any before-and-after reading is only a time correlation: call it
+   that, give the windows, and do not attribute the difference to the commit.
+   If no one knows when it shipped, say the comparison cannot be anchored.
+2. Read usage for the same route or workload over comparable, bounded UTC
+   windows before and after that point (`metergraph_get_usage_aggregates`
+   with explicit `since` and `until` and the same filters, or
+   `metergraph_get_usage` where grouped usage is unavailable), and cite both
+   reads as in section 4. Windows of equal length avoid comparing a partial
+   day with a whole one. Filter both reads to the environment the deployment
+   record names (`environment`), so traffic in another environment that
+   shares the route is not credited to the change. If that environment
+   cannot be isolated (for example the grant or deployment has no
+   environment filter), say the cost impact is unknown.
+3. Compare per-call cost and token counts as well as totals, so a traffic
+   change is not mistaken for a code change. Name what else changed in the
+   window when you know it (traffic, provider prices, other deploys).
+4. If either window is incomplete, truncated or warned, if the windows are not
+   comparable, or if the returned data cannot separate traffic by the change,
+   state that the cost impact is unknown and name the next bounded check. Do
+   not fill the gap from the diff.
+
+Present the diff and the usage evidence separately: what the code suggests,
+and what Metergraph measured.
 
-## 5. Worked workflow: one failed trace
+## 6. Worked workflow: one failed trace
 
-1. Discover: context, then capabilities. Confirm the workspace with the user.
-2. Find: `metergraph_query_traces` with `status` set to the failure status, the
-   agreed `days` and `limit` 1. If the user gave a request ID and the match is
+1. Discover: `metergraph status --json` and `metergraph capabilities --json`
+   (or the context and capabilities tools). Confirm the workspace with the user.
+2. Find: `metergraph traces --status error --days N --limit 1 --json` (or
+   `metergraph_query_traces` with `status` set to the failure status, the
+   agreed `days` and `limit` 1). If the user gave a request ID and the match is
    ambiguous, list the candidates and ask which one.
-3. Explain from metadata: route, model, provider, tokens, cost, latency, status
-   and span count, with the citations above. If metadata is enough, stop here.
+3. Explain from metadata: route, model, provider, tokens, cost, status and
+   span count, plus latency only when the read returns it (CLI `traces` does
+   not; never infer it from timestamps), with the citations above. If metadata is enough, stop here.
 4. Optional content: with consent, `metergraph_get_trace` for that one trace to
    read the error, tool calls and root-cause classification.
 5. Optional replay: only with explicit approval and when the trace is replay

package/assets/skills/metergraph-onboarding/SKILL.md

@@ -117,6 +117,13 @@ connection, paid eval rule or provider invocation just to manufacture proof.
    still needed and the next eval selection action. A synthetic demonstration
    does not meet real application or hosted pilot acceptance.
 
+A person's first cost question after setup ("which route costs most today")
+is a bounded usage read, not a trace scan: `metergraph usage --group-by route
+--today --json` from a CLI whose `metergraph help usage` lists `--group-by`, or
+`metergraph_get_usage_aggregates` when capabilities list `usage_aggregates`. Use `metergraph-investigate` for it. A
+remote or CI agent reads with the coding-agent Metadata key path in the
+`metergraph` skill, never with the application's ingest key.
+
 Verify the named trace through the connected client's advertised MCP tools,
 with an explicit source label and the same workspace/deployment before and
 after any permitted content read. The older trace-debug contract has no