metergraph-cli 0.2.1 → 0.2.3

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.3`, 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
 
@@ -104,7 +109,11 @@ The CLI is built to be run by Codex, Claude Code and Cursor as well as by people
   `schema_version`, `command`, `ok`, `outcome`, `exit_code`, `data` and `error`.
   Failures carry a fixed `error.reason` and, where useful, a `data.next_action` that
   tells the agent what to do next.
-- **No hidden prompts.** No command reads stdin or asks a question. `--no-browser`
+- **No hidden prompts.** Only `setup` asks questions, and only a person at a terminal:
+  with stdin and stdout both terminals, no `--json` and no `CI`, it asks for what its
+  flags leave out and prints the full command before running it. Otherwise no command
+  reads stdin or asks a question, so an agent or script gets the same flag errors as
+  before. `--no-browser`
   prints the sign in URL for a person to open instead of launching a browser. With
   `--json`, a step that needs approval exits within seconds with 18
   `action_required` and `data.next_action` set to
@@ -130,14 +139,17 @@ Suggested `AGENTS.md` or `CLAUDE.md` lines for a project that uses Metergraph:
 
 | Command | What it does | Network |
 | --- | --- | --- |
+| `pricing models`, `pricing lookup`, `pricing calculate` (`cost` alias) | Discover models, look up rates and calculate costs through the public API without sign in | Yes |
+| `pricing market`, `pricing history` | Current public market board; historical terminal/HTML charts require the local reference adapter ([guide](docs/pricing.md)) | Yes |
 | `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 |
 | `capabilities` | What the workspace makes available to this project | Yes |
+| `experiments list`, `estimate`, `start`, `get` | Replay a workload's recent production calls on 1 to 3 other models or settings: price it, start it, poll it and read cost, latency and output statistics per treatment next to production | Yes |
 | `login`, `logout` | Sign a project in or out without the rest of `setup` | Yes |
 | `doctor` | Check that a service is reachable, healthy and supported, without credentials | Yes |
 | `skill install`, `skill update` | Install or update the Metergraph skill for one agent | No |
@@ -147,10 +159,37 @@ Suggested `AGENTS.md` or `CLAUDE.md` lines for a project that uses Metergraph:
 [CLI reference](https://github.com/metergraph/cli/blob/main/docs/reference.md) covers every option, what each command reads and
 writes, and full JSON examples.
 
+## Public pricing preview
+
+```sh
+metergraph pricing models --limit 10
+metergraph pricing lookup --model gpt-5 --provider openai --region global --json
+metergraph pricing calculate --model claude-sonnet-5 --provider anthropic \
+  --input-tokens 1000 --cache-read-tokens 800 --output-tokens 200
+metergraph pricing market --channel openai-api --limit 5
+```
+
+These commands use the public Pricing API without an account or workspace.
+`cost` is an alias for `calculate`. Inspect status and missing dimensions: an HTTP
+success may still be partial or unpriced. The current market board uses discovery
+plus bounded lookups; it does not invent historical prices or returns.
+
+The stock-style history visualization is preserved in explicit local reference mode:
+
+```sh
+metergraph pricing history --model openai/gpt-5.6-terra --channel openai-api \
+  --api reference --url http://127.0.0.1:8765 --format html > history.html
+```
+
+See [the pricing guide](docs/pricing.md) for the API contract, input semantics and
+local adapter. The public service does not document a history endpoint. This is
+an exploratory preview; supplier pricing coverage and storage claims are not
+independently verified by these command tests.
+
 ## Exit codes
 
 Exit codes are stable. Changing one is a breaking change. Codes 10 to 18 are not in
-`0.1.0`.
+`0.1.0`, and codes 19 and 20 are not in `0.2.2` or earlier.
 
 | Code | Outcome | Meaning |
 | --- | --- | --- |
@@ -170,9 +209,11 @@ 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. |
+| 19 | `refused` | The service refused an experiment for a stated reason, such as its budget, the daily cap, experiments already running or a model it cannot price; `data.refusal` says which. Nothing was started. |
+| 20 | `unconfirmed` | An `experiments start` request reached the service but its result was not confirmed (a timeout, a dropped connection, a server error or an answer that does not match the contract), so an experiment may exist and may run. List experiments before starting again; each start creates one. |
 
 ## Security and privacy
 
@@ -180,7 +221,11 @@ Exit codes are stable. Changing one is a breaking change. Codes 10 to 18 are not
   only to the Metergraph origin you point it at.
 - **Least access.** Sign in grants only the Metadata scope, `agent:metadata`. The CLI
   never requests Debug or Replay access, never falls back to broader access, and never
-  reads retained prompts, responses or other content. It calls no model provider.
+  reads retained prompts, responses or other content. It calls no model provider. The one
+  exception is `experiments start`: it uses a coding-agent key a workspace owner created
+  with exactly Debug access and Allow analysis starts, refuses a key with any other scope,
+  and sends it only with that one start request. The service then replays the sampled calls on the
+  chosen providers within its own budget. Every other command refuses such a key.
 - **Credentials.** The sign in grant is stored per user in `~/.config/metergraph`
   (`AppData\Roaming\Metergraph` on Windows), as owner-only files on Linux and macOS and
   encrypted with DPAPI on Windows. The ingest key goes only into the project's private
@@ -189,7 +234,11 @@ Exit codes are stable. Changing one is a breaking change. Codes 10 to 18 are not
 - **Files it writes in your project:** `.env` (from `setup`), the skill file, and
   secret-free state under `.metergraph/` that is safe to commit. The skill installer
   never replaces a file it did not write and has no force option.
-- **Network.** Only `GET` requests to fixed paths for reads, no redirects followed,
+- **Public pricing.** Pricing reads send no credentials and return public catalog data.
+  `--format html` emits a standalone document; it does not launch a browser.
+- **Network.** Workspace reads use `GET`; experiments estimate and start use `POST`.
+  Public pricing lookup/calculation use unauthenticated `POST` with metadata-only
+  inputs. Fixed paths, no redirects followed,
   bounded response sizes and fixed timeouts. Mistyped arguments are never echoed, since
   they may hold a secret. `--help`, `--version` and `skill` make no network requests.
 

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`,