metergraph-cli 0.2.1 → 0.2.3

package/src/output.js

@@ -1,3 +1,4 @@
+import { PRICING_OPTIONS } from "./pricing-args.js";
 import {
   CONNECTION_GUIDE_URL,
   DEFAULT_ORIGIN,
@@ -27,6 +28,7 @@ import {
   SUPPORTED_PROFILES,
   VERSION,
 } from "./constants.js";
+import { PLAIN, fields, headline, paragraph, render, section, steps, toneFor } from "./style.js";
 
 // Every JSON result, success or failure, has the same top-level keys:
 //   schema_version, command, ok, outcome, exit_code, data, error
@@ -115,6 +117,20 @@ const AGENT_APPROVAL_HELP = [
   "and after they approve, run the same command again to continue.",
 ];
 
+// One recommended sequence per place an agent runs. login and setup detect
+// SSH, cloud workspaces and CI and answer with a structured next_action.
+const AGENT_PATH_HELP = [
+  "Where the agent runs:",
+  "  Local shell or local container   setup --runtime local --client C --json --no-browser,",
+  "                                   rerun after each approval, then status --json",
+  "  SSH, cloud workspace or CI       A person creates a coding-agent key with Metadata access",
+  "                                   on the Keys page and saves it as the secret",
+  "                                   METERGRAPH_AGENT_TOKEN; then status --json, usage --json",
+  "  Metadata key, no saved sign in   The same: reads use METERGRAPH_AGENT_TOKEN, or",
+  "                                   --agent-token-file PATH, after verifying the workspace",
+  "Never pass a key as an argument. Debug and Replay keys are refused, not reduced.",
+];
+
 const CONFIG_DIR_OPTION = {
   name: "--config-dir",
   value: "DIR",
@@ -127,7 +143,9 @@ const LOGIN_OPTIONS = [
   {
     name: "--runtime",
     value: "RUNTIME",
-    summary: "Required. local: the browser runs on this machine. cloud and cloud-no-shell get a handoff.",
+    summary:
+      "Required. Where this terminal runs, not which Metergraph service. local: your own machine, " +
+      "including for the hosted service. cloud, cloud-no-shell: a cloud sandbox; get the connection guide.",
   },
   { name: "--url", value: "ORIGIN", summary: `Origin to sign in to. Default ${DEFAULT_ORIGIN}.` },
   {
@@ -195,24 +213,92 @@ const READ_BASE_OPTIONS = [
       `Total time for every request of the command, ${READ_MIN_TIMEOUT_MS} to ${READ_MAX_TIMEOUT_MS}. ` +
       `Default ${READ_DEFAULT_TIMEOUT_MS}.`,
   },
+  {
+    name: "--url",
+    value: "ORIGIN",
+    summary:
+      "Where a Metadata key is sent when the project is not bound. Default METERGRAPH_URL, else the hosted service. " +
+      "A bound project's origin cannot be changed here.",
+  },
+  {
+    name: "--workspace",
+    value: "UUID",
+    summary: "The workspace the credential must be for. Without it, an unbound key's own workspace is used.",
+  },
+  {
+    name: "--agent-token-file",
+    value: "PATH",
+    summary:
+      "Private (0600) file holding a coding-agent key with Metadata access. Used instead of a saved sign in. " +
+      "Without it, METERGRAPH_AGENT_TOKEN is used when this project has no saved sign in on this machine.",
+  },
+];
+const EXPERIMENTS_USAGE = [
+  "metergraph experiments list [--workload ID] [--limit N] [read options] [--json]",
+  "metergraph experiments estimate --workload ID --treatment SPEC [--treatment SPEC]... [--last-n N] " +
+    "[--sample-model MODEL] [--track PATH]... [read options] [--json]",
+  "metergraph experiments start (same as estimate) [--agent-token-file PATH] [--json]",
+  "metergraph experiments get --id UUID [read options] [--json]",
+];
+const EXPERIMENTS_OPTIONS = [
+  { name: "--workload", value: "ID", summary: "The workload (route) whose recent production calls are replayed. Required for estimate and start; a filter for list." },
+  {
+    name: "--treatment",
+    value: "SPEC",
+    summary:
+      "1 to 3 times. PROVIDER/MODEL, optionally followed by ,label=NAME ,temperature=0..2 ,max_tokens=1..32000 " +
+      "or ,reasoning_effort=none|minimal|low|medium|high|xhigh|max. Unset settings follow production.",
+  },
+  { name: "--last-n", value: "N", summary: "Replay the last N replayable calls, 10 to 40. Default 20." },
+  { name: "--sample-model", value: "MODEL", summary: "Only production calls made with this exact model, for a single-model control." },
+  { name: "--track", value: "PATH", summary: "Up to 10 times. A JSON path such as $.priority whose values the dashboard compares." },
+  { name: "--id", value: "UUID", summary: "The experiment to read (get)." },
+  { name: "--limit", value: "N", summary: "Experiments to list, 1 to 50. Default 20." },
+  ...READ_BASE_OPTIONS.filter((option) => option.name !== "--agent-token-file"),
+  {
+    name: "--agent-token-file",
+    value: "PATH",
+    summary:
+      "Private (0600) file holding a coding-agent key. For list, estimate and get: a key with Metadata access. " +
+      "For start: a key with Debug access and Allow analysis starts, used for that one request.",
+  },
+  JSON_OPTION,
 ];
 const DAYS_OPTION = {
   name: "--days",
   value: "N",
   summary: `Window of the last N days, 1 to ${READ_MAX_DAYS}. Default ${READ_DEFAULT_DAYS}.`,
 };
+const METADATA_OPTIONS = [
+  {
+    name: "--metadata",
+    value: "KEY=VALUE",
+    summary:
+      "Only calls whose metadata (SDK tags) has exactly this string value: case-sensitive, no prefix or " +
+      "trimming. Repeat for up to 5 keys, all must match. A call without the key never matches; KEY= " +
+      "matches only an empty value. Splits at the first =, so a value may contain =.",
+  },
+  {
+    name: "--metadata-json",
+    value: "JSON",
+    summary:
+      'The same filters as one JSON object, for keys that contain = (for example {"a=b":"v"}). Not with --metadata.',
+  },
+];
 const limitOption = (fallback, extra = "") => ({
   name: "--limit",
   value: "N",
   summary: `Rows to return, 1 to ${READ_MAX_LIMIT}. Default ${fallback}.${extra}`,
 });
-const READ_BASE_USAGE = "[--project DIR] [--config-dir DIR] [--timeout-ms N] [--json]";
+const READ_BASE_USAGE =
+  "[--url ORIGIN] [--workspace UUID] [--agent-token-file PATH] [--project DIR] [--config-dir DIR] [--timeout-ms N] [--json]";
 const REFUSED_NOTE =
   "--environment, --workload, --since, --until, --sql, --query, --content, --include-content, --debug and --replay " +
-  "are recognized and refused with exit code 6 before any request.";
+  "are recognized and refused with exit code 6 before any request, except --environment, --since and --until on usage.";
 
-// The read commands. Each uses the project's saved Metadata grant, makes GET
-// requests to fixed paths on the bound origin and never opens a browser.
+// The read commands. Each uses the project's saved Metadata grant or a
+// coding-agent key with Metadata access, makes GET requests to fixed paths on
+// the verified origin and never opens a browser.
 export const READ_HELP = Object.freeze([
   {
     name: "status",
@@ -237,9 +323,82 @@ export const READ_HELP = Object.freeze([
   },
   {
     name: "usage",
-    usage: `metergraph usage [--days N] [--limit N] ${READ_BASE_USAGE}`,
-    summary: "Show daily calls, errors, cost, tokens and latency per route for a recent window. Metadata only.",
-    options: [...READ_BASE_OPTIONS, DAYS_OPTION, limitOption(READ_DEFAULT_LIMIT), JSON_OPTION],
+    usage:
+      `metergraph usage [--days N | --today | --since TIME [--until TIME]] [--group-by DIMS] ` +
+      `[--route NAME]... [--provider NAME]... [--model NAME]... [--environment NAME]... ` +
+      `[--sort ORDER] [--compare previous|previous-same-time] [--limit N] ` +
+      `[--metadata KEY=VALUE]... [--metadata-json JSON] [--group-by-metadata KEY] ${READ_BASE_USAGE}`,
+    summary:
+      "Show calls, errors, cost, tokens and latency. With --group-by, a filter, a UTC window, --sort or --compare " +
+      "it reads grouped usage: cost by provider, model, route or UTC day, computed per call by the service, with " +
+      "totals over every matching call and coverage, pricing and attribution evidence. Without them it lists cost " +
+      "per route and day for the last N days. A route is not a prompt: one route can carry several prompt IDs, " +
+      'so "metergraph usage --group-by metadata.prompt_id" splits cost by prompt. "metergraph routes" lists ' +
+      "route definitions, not their cost.",
+    examples: [
+      ["Most expensive route today", "metergraph usage --group-by route --today"],
+      ["Spend with one provider this week", "metergraph usage --group-by provider --provider NAME --days 7"],
+      ["Spend by model", "metergraph usage --group-by model --days 7"],
+      ["One route's daily trend", "metergraph usage --route NAME --group-by day --days 14"],
+      ["Cost by prompt ID", "metergraph usage --group-by metadata.prompt_id --days 7"],
+      ["Today against yesterday", "metergraph usage --group-by route --today --compare previous"],
+    ],
+    options: [
+      ...READ_BASE_OPTIONS,
+      {
+        name: "--days",
+        value: "N",
+        summary:
+          `Window, 1 to ${READ_MAX_DAYS}. Default ${READ_DEFAULT_DAYS}. Grouped: the current UTC day so far and the ` +
+          "N - 1 whole UTC days before it (window.kind utc_days). Otherwise the last N x 24 hours, rolling and not " +
+          "aligned to UTC days (window.kind rolling).",
+      },
+      { name: "--today", value: null, summary: "Grouped: the current UTC day so far (--days 1)." },
+      {
+        name: "--since",
+        value: "TIME",
+        summary:
+          "Grouped: window start, inclusive. A UTC date (YYYY-MM-DD, 00:00 UTC) or an ISO 8601 timestamp with Z " +
+          `or an offset. At most ${READ_MAX_DAYS} days before --until.`,
+      },
+      { name: "--until", value: "TIME", summary: "Grouped: window end, exclusive, in the same form. Default now." },
+      {
+        name: "--group-by",
+        value: "DIMS",
+        summary: "Comma-separated, in order: provider, model, route, day (UTC calendar day). Default provider,model.",
+      },
+      { name: "--route", value: "NAME", summary: "Grouped: only this route, exactly. Repeat for up to 20; (unrouted) selects calls without one." },
+      { name: "--provider", value: "NAME", summary: "Grouped: only this provider, exactly. Repeat for up to 20." },
+      { name: "--model", value: "NAME", summary: "Grouped: only this model, exactly. Repeat for up to 20." },
+      { name: "--environment", value: "NAME", summary: "Grouped: only this environment. Repeat for several. A restricted grant reads its own environments only." },
+      {
+        name: "--sort",
+        value: "ORDER",
+        summary:
+          "cost (default), cost-per-call, calls, errors, avg-latency (mean over calls that reported latency), " +
+          "p95-latency (estimated from a fixed histogram) or day (oldest first; the default for --group-by day). " +
+          "The service returns the highest-cost groups, so another order over a cut list is marked partial.",
+      },
+      {
+        name: "--compare",
+        value: "MODE",
+        summary:
+          "Also read the period before and show the change per group. previous: the whole prior period, which is " +
+          "longer than a window ending part way through today (a warning says so). previous-same-time: the prior " +
+          "period to the same elapsed time. Not with --group-by day.",
+      },
+      limitOption(READ_DEFAULT_LIMIT, " Grouped: the most groups listed; totals still cover every call."),
+      ...METADATA_OPTIONS,
+      {
+        name: "--group-by-metadata",
+        value: "KEY",
+        summary:
+          "Group by one metadata key: the same as ending --group-by with metadata.KEY, and the way to give a key " +
+          "that holds a comma. Calls without the key or with a non-string value are one group with no value, and " +
+          "the spend not attributed to any value is totalled.",
+      },
+      JSON_OPTION,
+    ],
   },
   {
     name: "routes",
@@ -260,7 +419,7 @@ export const READ_HELP = Object.freeze([
     name: "traces",
     usage:
       `metergraph traces [--days N] [--limit N] [--route NAME] [--status success|error] ` +
-      `[--cursor CURSOR] ${READ_BASE_USAGE}`,
+      `[--metadata KEY=VALUE]... [--metadata-json JSON] [--cursor CURSOR] ${READ_BASE_USAGE}`,
     summary:
       "List one page of trace metadata: status, span count, tokens, cost, routes, providers and models. " +
       "No prompts, responses or tool calls.",
@@ -270,6 +429,7 @@ export const READ_HELP = Object.freeze([
       limitOption(TRACES_DEFAULT_LIMIT),
       { name: "--route", value: "NAME", summary: "Only traces that include this route." },
       { name: "--status", value: "STATUS", summary: "Only success or error traces." },
+      ...METADATA_OPTIONS,
       {
         name: "--cursor",
         value: "CURSOR",
@@ -280,6 +440,15 @@ export const READ_HELP = Object.freeze([
   },
 ]);
 
+// One "  FLAG  summary" line per option. The flag column keeps its usual
+// width but grows to fit the longest flag, so a flag never runs into its
+// summary.
+function optionLines(options, minimum) {
+  const flags = options.map((option) => (option.value ? `${option.name} ${option.value}` : option.name));
+  const width = Math.max(minimum, ...flags.map((flag) => flag.length + 2));
+  return options.map((option, index) => `  ${flags[index].padEnd(width)}${option.summary}`);
+}
+
 export function helpData(topic) {
   return {
     topic,
@@ -287,6 +456,7 @@ export function helpData(topic) {
       "metergraph --help [--json]",
       "metergraph --version [--json]",
       "metergraph doctor [--url ORIGIN] [--timeout-ms N] [--json]",
+      "metergraph pricing models|lookup|calculate|cost|history|market [options] [--json]",
       ...SKILL_USAGE,
       ...SKILLS_USAGE,
       LOGIN_USAGE,
@@ -294,8 +464,12 @@ export function helpData(topic) {
       SETUP_USAGE,
       VERIFY_USAGE,
       ...READ_HELP.map((entry) => entry.usage),
+      ...EXPERIMENTS_USAGE,
     ],
     commands: [
+      { name: "pricing", summary: "Public model discovery, lookup and calculation. Current market board; historical charts in local reference mode.",
+        options: [...PRICING_OPTIONS.map(name => ({ name, value: "VALUE", summary: "See metergraph help pricing and docs/pricing.md." })),
+          { name: "--batch", value: null, summary: "Use batch pricing for cost." }, JSON_OPTION] },
       {
         name: "doctor",
         summary:
@@ -351,7 +525,7 @@ export function helpData(topic) {
         name: "setup",
         summary: "Guide browser sign in and workspace choice, approve an ingest-only key, and install the selected client skill. Does not verify application traffic.",
         options: [
-          { name: "--runtime", value: "RUNTIME", summary: "Required. local only; other runtimes get a handoff." },
+          { name: "--runtime", value: "RUNTIME", summary: "Required unless a person runs setup at a terminal (then local). local only; other runtimes get a handoff." },
           { name: "--url", value: "ORIGIN", summary: "Deployment origin. Defaults to an existing project binding, else the hosted origin." },
           { name: "--workspace", value: "UUID", summary: "Expected workspace; the browser must approve this exact workspace." },
           { name: "--project", value: "DIR", summary: "Project directory. Default: current directory." },
@@ -377,7 +551,20 @@ export function helpData(topic) {
         summary: "Poll Metadata for one exact trace in an explicit invocation window. Never sends application traffic.",
         options: VERIFY_OPTIONS,
       },
-      ...READ_HELP.map(({ name, summary, options }) => ({ name, summary, options })),
+      {
+        name: "experiments",
+        summary:
+          "Estimate, start, list and read experiments: a workload's recent production calls replayed on 1 to 3 " +
+          "treatments, with built-in statistics per arm next to production. list, estimate and get are Metadata " +
+          "reads; start needs a key with Debug access and Allow analysis starts and spends within the server's budget.",
+        options: EXPERIMENTS_OPTIONS,
+      },
+      ...READ_HELP.map(({ name, summary, options, examples }) => ({
+        name,
+        summary,
+        options,
+        ...(examples ? { examples: examples.map(([question, command]) => ({ question, command })) } : {}),
+      })),
     ],
     skill_clients: Object.keys(SKILL_CLIENTS),
     skill_runtimes: [...SKILL_RUNTIMES],
@@ -391,8 +578,45 @@ export function helpData(topic) {
   };
 }
 
-export function helpText(topic) {
+export function helpText(topic, style = PLAIN) {
   const lines = [];
+  if (topic === "pricing") {
+    return `Usage: metergraph pricing models|lookup|calculate|cost|history|market [options] [--json]
+
+Public catalog prices. No account, project or token is required.
+models  [--model ID] [--provider ID | --channel ID] [--region ID] [--limit 1..100]
+lookup  --model ID [--provider ID | --channel ID] [--region ID] [--at YYYY-MM-DD]
+calculate (or cost) Same selectors; --input-tokens N --output-tokens N [--batch]
+        --cache-read-tokens N; --trace-format anthropic.messages|openai.responses|
+        openai.chat_completions|otel.gen_ai. Native format inferred for direct
+        Anthropic/OpenAI; otherwise otel.gen_ai. Only supplied counts are sent.
+        Anthropic also accepts --cache-write-tokens N or
+        --cache-write-5m-tokens N / --cache-write-1h-tokens N.
+market  --channel ID [--region ID] [--limit 1..100] (current rates, no history)
+history --model ID --channel ID [--region ID] [--format table|chart|html]
+        Requires --api reference --url LOOPBACK_ORIGIN; no public history API.
+
+All actions: --url ORIGIN --timeout-ms 100..30000 --json --api public|reference
+Default API: public; default origin: https://app.metergraph.dev.
+--at selects UTC midnight; without it public lookup/calculation use server time.
+Models and public market discovery are current-only. Filters on models run locally.
+History/market region defaults to global. Omitted input/output counts stay unknown;
+partial costs are known subtotals, not complete costs. OpenAI cache counts must
+not exceed total input. --json cannot be combined with --format.
+
+Examples:
+  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
+  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
+
+Public API: GET /v1/pricing/models; POST /v1/pricing/lookup and /calculate.
+No credentials, traces, prompts or responses are loaded from project files.
+The CLI constructs metadata-only provider-format traces from the supplied counts.
+See docs/pricing.md for the supported contract, limitations and reference previews.
+`;
+  }
   if (topic === "doctor") {
     lines.push(
       "Usage: metergraph doctor [--url ORIGIN] [--timeout-ms N] [--json]",
@@ -402,10 +626,7 @@ export function helpText(topic) {
       "",
       "Options:",
     );
-    for (const option of DOCTOR_OPTIONS) {
-      const flag = option.value ? `${option.name} ${option.value}` : option.name;
-      lines.push(`  ${flag.padEnd(18)}${option.summary}`);
-    }
+    lines.push(...optionLines(DOCTOR_OPTIONS, 18));
     lines.push(
       "",
       "ORIGIN must be a bare https origin such as https://metergraph.example.com.",
@@ -421,11 +642,10 @@ export function helpText(topic) {
       "--skip-skill is explicit. Non-hosted setup requires an explicit origin, workspace and",
       "operator prerequisite attestation; OSS remains an operator handoff. No application",
       "traffic is claimed until an exact instrumented invocation is separately verified.",
+      "", "At a terminal without --json, setup asks for any of these it needs that are",
+      "missing, prints the full command, then runs it. Scripts and agents get no questions.",
       "", "Options:");
-    for (const option of helpData(null).commands.find((entry) => entry.name === "setup").options) {
-      const flag = option.value ? `${option.name} ${option.value}` : option.name;
-      lines.push(`  ${flag.padEnd(25)}${option.summary}`);
-    }
+    lines.push(...optionLines(helpData(null).commands.find((entry) => entry.name === "setup").options, 25));
     lines.push("", ...AGENT_APPROVAL_HELP);
   } else if (topic === "login" || topic === "logout") {
     const login = topic === "login";
@@ -455,20 +675,38 @@ export function helpText(topic) {
       );
     }
     lines.push("Options:");
-    for (const option of login ? LOGIN_OPTIONS : LOGOUT_OPTIONS) {
-      const flag = option.value ? `${option.name} ${option.value}` : option.name;
-      lines.push(`  ${flag.padEnd(18)}${option.summary}`);
-    }
+    lines.push(...optionLines(login ? LOGIN_OPTIONS : LOGOUT_OPTIONS, 18));
     if (login) lines.push("", ...AGENT_APPROVAL_HELP);
   } else if (topic === "verify") {
     lines.push(`Usage: ${VERIFY_USAGE}`, "", "Uses the saved Metadata grant to poll for one exact, processed trace.",
       "The source label is supplied by the caller. A Metadata match alone does not prove application traffic.",
       "Opening requires a server link that selects the verified workspace; older links get a manual handoff.",
       "", "Options:");
-    for (const option of VERIFY_OPTIONS) {
-      const flag = option.value ? `${option.name} ${option.value}` : option.name;
-      lines.push(`  ${flag.padEnd(22)}${option.summary}`);
-    }
+    lines.push(...optionLines(VERIFY_OPTIONS, 22));
+  } else if (topic === "experiments") {
+    lines.push(
+      "Usage:",
+      ...EXPERIMENTS_USAGE.map((usage) => `  ${usage}`),
+      "",
+      "An experiment replays a workload's last 10 to 40 replayable production calls on 1 to 3 treatments",
+      "(a provider, model and settings) and compares each with what production returned on the same calls:",
+      "cost per call, p50 latency and output tokens, output length, JSON parse rate, same top-level keys,",
+      "empty or refused and cut-off rates. The statistics show differences; they do not judge them.",
+      "",
+      "estimate prices it against the server's budget and daily cap and writes nothing. start takes the",
+      "same arguments, so it starts exactly what was priced; poll it with get until it is terminal.",
+      "Each start creates a new experiment, so a start that succeeded is never retried.",
+      "",
+      "list, estimate and get use this project's saved Metadata grant or a Metadata key, as the read",
+      "commands do, and never read inputs, outputs or tracked field values; those are in the dashboard.",
+      "start needs a coding-agent key with Debug access and Allow analysis starts, which only a workspace",
+      "owner can grant, in --agent-token-file or METERGRAPH_AGENT_TOKEN. The CLI checks the key has exactly",
+      "that before it sends the one start request, and never uses it for anything else. The service then",
+      "replays the sampled calls' captured prompts on each treatment's provider within its budget.",
+      "",
+      "Options:",
+    );
+    lines.push(...optionLines(EXPERIMENTS_OPTIONS, 22));
   } else if (READ_HELP.some((entry) => entry.name === topic)) {
     const entry = READ_HELP.find((candidate) => candidate.name === topic);
     lines.push(
@@ -476,18 +714,23 @@ export function helpText(topic) {
       "",
       entry.summary,
       "",
-      "Uses this project's saved Metadata grant (see \"metergraph help login\"). Sends GET requests only, to",
-      "fixed paths on the bound origin, follows no redirects and reads bounded responses. Never opens a",
-      "browser, signs in, writes project files, reads retained content, replays or calls a model provider.",
-      "It may refresh its own saved grant, and the service may record the access (for example last used",
-      "times); it never changes workspace configuration or telemetry and never sends ingest data.",
+      "Uses this project's saved Metadata grant (see \"metergraph help login\"), or, where there is none on",
+      "this machine, a coding-agent key with Metadata access from METERGRAPH_AGENT_TOKEN or",
+      "--agent-token-file. A key is sent only after the origin answers as a supported Metergraph service,",
+      "and nothing is read until the service shows exactly the Metadata scope, no content access and the",
+      "expected workspace. Sends GET requests only, to fixed paths on that origin, follows no redirects and",
+      "reads bounded responses. Never opens a browser, signs in, writes project files or the key, reads",
+      "retained content, replays or calls a model provider. It may refresh its own saved grant, and the",
+      "service may record the access (for example last used times); it never changes workspace",
+      "configuration or telemetry and never sends ingest data.",
       REFUSED_NOTE,
       "",
       "Options:",
     );
-    for (const option of entry.options) {
-      const flag = option.value ? `${option.name} ${option.value}` : option.name;
-      lines.push(`  ${flag.padEnd(18)}${option.summary}`);
+    lines.push(...optionLines(entry.options, 25));
+    if (entry.examples) {
+      lines.push("", "Examples (add --json for one JSON line):");
+      for (const [question, command] of entry.examples) lines.push(`  ${question}:`, `    ${command}`);
     }
   } else if (topic === "skill") {
     lines.push(
@@ -501,10 +744,7 @@ export function helpText(topic) {
       "",
       "Options:",
     );
-    for (const option of SKILL_OPTIONS) {
-      const flag = option.value ? `${option.name} ${option.value}` : option.name;
-      lines.push(`  ${flag.padEnd(18)}${option.summary}`);
-    }
+    lines.push(...optionLines(SKILL_OPTIONS, 18));
     lines.push(
       "",
       "install never replaces an existing skill. update replaces only a skill this CLI",
@@ -533,10 +773,7 @@ export function helpText(topic) {
       "",
       "Options:",
     );
-    for (const option of SKILL_OPTIONS) {
-      const flag = option.value ? `${option.name} ${option.value}` : option.name;
-      lines.push(`  ${flag.padEnd(18)}${option.summary}`);
-    }
+    lines.push(...optionLines(SKILL_OPTIONS, 18));
     lines.push(
       "",
       "install never replaces an existing skill. update replaces only skills this CLI",
@@ -570,6 +807,8 @@ export function helpText(topic) {
       "  metergraph usage [options]       Daily usage per route, Metadata only",
       "  metergraph routes [options]      Routes and evaluation contract versions",
       "  metergraph traces [options]      One page of trace metadata",
+      "  metergraph experiments list|estimate|start|get  Replay a workload on other models",
+      "  metergraph pricing <action>      Public lookup, cost, history and market board",
       "",
       'Run "metergraph help doctor" for doctor options.',
       'Run "metergraph help skill" for skill options.',
@@ -577,77 +816,94 @@ export function helpText(topic) {
       'Run "metergraph help login" or "metergraph help logout" for sign in options.',
       'Run "metergraph help verify" for exact-trace verification options.',
       'Run "metergraph help COMMAND" for status, context, capabilities, usage, routes or traces.',
+      'Run "metergraph help experiments" for experiment options.',
+      "",
+      ...AGENT_PATH_HELP,
     );
   }
   lines.push("", "Exit codes:");
   for (const [outcome, code] of Object.entries(EXIT_CODES)) {
-    lines.push(`  ${String(code).padEnd(3)}${outcome.padEnd(25)}${EXIT_CODE_MEANINGS[outcome]}`);
+    lines.push(`  ${String(code).padEnd(3)}${outcome.padEnd(25)}${style.dim(EXIT_CODE_MEANINGS[outcome])}`);
   }
-  return `${lines.join("\n")}\n`;
+  // Section labels ("Usage:", "Options:", "Exit codes:") in bold.
+  return `${lines.map((line) => line.replace(/^(Usage|Options|Exit codes):/, (label) => style.bold(label))).join("\n")}\n`;
 }
 
-export function skillText(result, message) {
+export function skillText(result, message, style = PLAIN) {
   const report = result.data;
   const label = SKILL_CLIENTS[report.client]?.label ?? HANDOFF_SKILL_CLIENTS[report.client];
-  const lines = [`Metergraph ${result.command}: ${label}, ${report.runtime} runtime`];
-  if (report.path !== null) lines.push(`Path: ${report.path}`);
+  const verb = result.command === "skill update" ? "updated" : "installed";
+  const lines = [
+    result.ok
+      ? headline(style, "ok", `Metergraph skill ${report.status === "unchanged" ? "already up to date" : verb} for ${label}`)
+      : headline(style, toneFor(result.outcome), `Metergraph skill not ${verb} for ${label}`, result.outcome),
+    "",
+  ];
+  const rows = [["Runtime", report.runtime], ["Path", report.path]];
   if (result.ok) {
-    lines.push(
-      `Status: ${report.status}`,
-      `Source revision: ${report.source.revision} (sha256 ${report.source.sha256})`,
-      `Discovery: pending until ${label} loads the skill`,
-      "Authenticated: no",
-      "",
-      message,
-      `Next: ${report.next_action.message}`,
+    rows.push(
+      ["Status", report.status],
+      ["Source", `${report.source.revision} ${style.dim(`(sha256 ${report.source.sha256})`)}`],
+      ["Discovery", `pending until ${label} loads the skill`],
+      ["Authenticated", "no"],
     );
-  } else {
-    lines.push("", `Result: ${result.outcome} (exit ${result.exit_code})`, message);
-    if (report.next_action?.kind === "connection_guide") {
-      lines.push(`Connection guide: ${report.next_action.url}`);
-    }
   }
-  return `${lines.join("\n")}\n`;
+  lines.push(...fields(style, rows), "");
+  if (message) lines.push(...paragraph(style, message), "");
+  lines.push(...steps(style, [
+    ["", result.ok ? report.next_action.message : null],
+    ["Connection guide", !result.ok && report.next_action?.kind === "connection_guide" ? report.next_action.url : null],
+  ]));
+  return render(lines);
 }
 
-export function skillsText(result, message) {
+export function skillsText(result, message, style = PLAIN) {
   const report = result.data;
   const lines = [];
+  const source = report.source
+    ? ["Source", `${report.source.repository} ${style.dim(`at ${report.source.commit.slice(0, 12)}`)}`]
+    : ["Source", null];
   if (result.command === "skills list") {
-    lines.push("Metergraph skills bundled with this CLI");
-    if (report.source) lines.push(`Source: ${report.source.repository} at ${report.source.commit.slice(0, 12)}`);
-    if (!result.ok) {
-      lines.push("", `Result: ${result.outcome} (exit ${result.exit_code})`, message);
-      return `${lines.join("\n")}\n`;
-    }
+    lines.push(
+      result.ok
+        ? headline(style, "info", "Metergraph skills bundled with this CLI")
+        : headline(style, toneFor(result.outcome), "Could not list Metergraph skills", result.outcome),
+      "",
+      ...fields(style, [source]),
+    );
+    if (!result.ok) return render([...lines, "", ...paragraph(style, message)]);
     for (const skill of report.skills) {
-      lines.push("", `${skill.name} (${skill.revision})`);
-      for (const [client, state] of Object.entries(skill.installs)) {
-        lines.push(`  ${SKILL_CLIENTS[client].label.padEnd(12)}${SKILLS_STATE_LABELS[state] ?? state}`);
-      }
+      lines.push("", `${section(style, skill.name)} ${style.dim(skill.revision)}`);
+      lines.push(...fields(style, Object.entries(skill.installs).map(([client, state]) =>
+        [SKILL_CLIENTS[client].label, state === "installed" ? style.green(SKILLS_STATE_LABELS[state]) : (SKILLS_STATE_LABELS[state] ?? state)])));
     }
-    return `${lines.join("\n")}\n`;
+    return render(lines);
   }
   const label = SKILL_CLIENTS[report.client]?.label ?? HANDOFF_SKILL_CLIENTS[report.client] ?? report.client;
-  lines.push(`Metergraph ${result.command}: ${label}, ${report.runtime} runtime`);
-  if (report.source) lines.push(`Source: ${report.source.repository} at ${report.source.commit.slice(0, 12)}`);
-  for (const skill of report.skills) {
-    const status = skill.status === "failed" ? `failed (${skill.reason})` : skill.status;
-    lines.push(`  ${skill.name.padEnd(24)}${status.padEnd(12)}${skill.path}`);
+  const verb = result.command === "skills update" ? "updated" : "installed";
+  lines.push(
+    result.ok
+      ? headline(style, "ok", `Metergraph skills ${verb} for ${label}`)
+      : headline(style, toneFor(result.outcome), `Metergraph skills not ${verb} for ${label}`, result.outcome),
+    "",
+    ...fields(style, [["Runtime", report.runtime], source]),
+  );
+  if (report.skills.length > 0) {
+    lines.push("", ...fields(style, report.skills.map((skill) => {
+      const status = skill.status === "failed" ? style.red(`failed (${skill.reason})`) : skill.status;
+      return [skill.name, `${status}  ${style.dim(skill.path ?? "")}`];
+    })));
   }
   if (result.ok) {
-    lines.push(
-      `Discovery: pending until ${label} loads the skills`,
-      "Authenticated: no",
-      "",
-      `Next: ${report.next_action.message}`,
-    );
+    lines.push("", ...fields(style, [["Discovery", `pending until ${label} loads the skills`], ["Authenticated", "no"]]),
+      "", ...steps(style, [["", report.next_action.message]]));
   } else {
-    lines.push("", `Result: ${result.outcome} (exit ${result.exit_code})`, message);
-    if (report.next_action?.kind === "plugin_marketplace") lines.push(`Next: ${report.next_action.message}`);
-    if (report.next_action?.kind === "connection_guide") lines.push(`Connection guide: ${report.next_action.url}`);
+    lines.push("", ...paragraph(style, message), "", ...steps(style, [
+      ["", report.next_action?.kind === "plugin_marketplace" ? report.next_action.message : null],
+      ["Connection guide", report.next_action?.kind === "connection_guide" ? report.next_action.url : null],
+    ]));
   }
-  return `${lines.join("\n")}\n`;
+  return render(lines);
 }
 
 export function versionData() {
@@ -693,35 +949,48 @@ export function doctorMessage(outcome, reason) {
   return `${detail.charAt(0).toUpperCase()}${detail.slice(1)}.`;
 }
 
-export function doctorText(result) {
+const CHECK_MARKS = { pass: ["✓", "green"], fail: ["✗", "red"], skipped: ["-", "dim"] };
+
+export function doctorText(result, style = PLAIN) {
   const report = result.data;
-  const lines = ["Metergraph doctor (read only, no credentials sent)", `Origin: ${report.origin}`, ""];
+  const title = result.outcome === "authentication_required"
+    ? "Service is reachable and requires sign in"
+    : result.ok ? "Service is healthy" : "Service check failed";
+  const lines = [
+    headline(style, toneFor(result.outcome), title, result.outcome),
+    "",
+    ...fields(style, [["Origin", report.origin]]),
+    `  ${style.dim("Read only, no credentials sent")}`,
+    "",
+  ];
+  const width = Math.max(...report.checks.map((check) => CHECK_LABELS[check.name].length));
   for (const check of report.checks) {
-    let line = `  ${check.result.padEnd(8)}${CHECK_LABELS[check.name]} (${check.path})`;
+    const [mark, color] = CHECK_MARKS[check.result] ?? ["?", "dim"];
+    let line = `  ${style[color](mark)} ${CHECK_LABELS[check.name].padEnd(width)}  ${style.dim(check.path)}`;
     if (check.name === "deployment" && report.deployment_profile !== null) {
-      line += `: ${report.deployment_profile}`;
+      line += `  ${report.deployment_profile}`;
     } else if (check.reason !== null) {
-      line += `: ${REASON_TEXT[check.reason] ?? check.reason}`;
+      line += `  ${REASON_TEXT[check.reason] ?? check.reason}`;
     }
     lines.push(line);
   }
-  lines.push("", `Result: ${result.outcome} (exit ${result.exit_code})`);
-  if (result.error !== null) lines.push(result.error.message);
+  if (result.error !== null) lines.push("", ...paragraph(style, result.error.message));
   if (result.outcome === "authentication_required") {
-    lines.push(
-      "Doctor sends no credentials. To connect an application, follow the connection guide:",
-      CONNECTION_GUIDE_URL,
-    );
+    lines.push("", ...steps(style, [
+      ["Sign in from this machine", "metergraph login --runtime local"],
+      ["Connect an application", CONNECTION_GUIDE_URL],
+    ]));
   }
-  return `${lines.join("\n")}\n`;
+  return render(lines);
 }
 
 // Fixed text for every login, logout and session reason. Reasons shared
 // with doctor fall back to its wording.
 const AUTH_MESSAGES = {
   runtime_not_supported:
-    "Sign in needs a browser on the same machine as the CLI, so cloud runtimes cannot complete it. " +
-    "Follow the connection guide instead. Nothing was written.",
+    "--runtime says where this terminal runs, not which Metergraph service you sign in to. " +
+    "A cloud runtime is a remote sandbox, and sign in needs a browser on the same machine as the CLI, " +
+    "so it cannot finish there. Nothing was written.",
   ssh_session:
     "This is a remote shell session. A browser on your own machine cannot reach this machine's loopback " +
     "address, so sign in cannot finish here. Run login where your browser runs. Nothing was written.",
@@ -823,36 +1092,73 @@ export function authMessage(outcome, reason) {
   return AUTH_MESSAGES[reason] ?? doctorMessage(outcome, reason);
 }
 
-export function authText(result, message) {
+// Short headlines for the reasons people meet most. Others use a generic one.
+const AUTH_TITLES = {
+  runtime_not_supported: "Sign in cannot run from a cloud runtime",
+  ssh_session: "Sign in cannot run over SSH",
+  cloud_workspace: "Sign in cannot run in a cloud development environment",
+  ci_environment: "Sign in cannot run in CI",
+  browser_approval_required: "Waiting for approval in the browser",
+  access_denied: "Sign in was declined in the browser",
+  timeout: "Sign in timed out",
+  cancelled: "Sign in was cancelled",
+  bound_to_other_origin: "This project is bound to a different origin",
+  bound_to_other_workspace: "This project is bound to a different workspace",
+  not_signed_in: "This project is not signed in",
+  revocation_unconfirmed: "Signed out locally; revocation not confirmed",
+};
+
+export function authText(result, message, style = PLAIN) {
   const report = result.data;
-  const lines = [`Metergraph ${result.command}`];
-  if (report.origin !== null) lines.push(`Origin: ${report.origin}`);
-  if (report.deployment_profile) lines.push(`Deployment profile: ${report.deployment_profile}`);
-  if (report.workspace !== null) lines.push(`Workspace: ${report.workspace.id}`);
-  if (result.command === "login") {
-    if (result.ok) {
-      const status = { signed_in: "signed in", reused: "already signed in", reconnected: "reconnected" }[report.status];
-      lines.push(
-        `Status: ${status}`,
-        `Scopes: ${report.scopes.join(" ")}`,
-        `Binding: ${report.binding}`,
-        `Grant storage: ${report.credential_protection === "dpapi" ? "Windows DPAPI, current user" : "owner-only file"}`,
-      );
-      if (report.previous_grant_revocation === "unconfirmed") {
-        lines.push("The previous grant was removed locally; the service did not confirm its revocation.");
-      }
-    }
+  const login = result.command === "login";
+  const reason = result.error?.reason ?? null;
+  let title;
+  if (result.ok && login) {
+    title = { signed_in: "Signed in", reused: "Already signed in", reconnected: "Reconnected" }[report.status];
+  } else if (result.ok) {
+    title = report.binding === "none" ? "This project was not signed in" : "Signed out";
   } else {
-    lines.push(
-      `Saved grant: ${report.local_credentials}`,
-      `Binding: ${report.binding}`,
-      `Server revocation: ${report.revocation.replace("_", " ")}`,
+    title = AUTH_TITLES[reason] ?? (login ? "Sign in did not complete" : "Sign out did not complete");
+  }
+  const lines = [headline(style, toneFor(result.outcome), title, result.outcome), ""];
+  const rows = [
+    ["Origin", report.origin],
+    ["Workspace", report.workspace?.id ?? null],
+    ["Profile", report.deployment_profile || null],
+  ];
+  if (login && result.ok) {
+    rows.push(
+      ["Scopes", report.scopes.join(" ")],
+      ["Binding", report.binding],
+      ["Grant storage", report.credential_protection === "dpapi" ? "Windows DPAPI, current user" : "owner-only file"],
+    );
+  } else if (!login) {
+    rows.push(
+      ["Saved grant", report.local_credentials],
+      ["Binding", report.binding],
+      ["Server revocation", report.revocation.replace("_", " ")],
     );
-    if (result.ok && report.binding === "none") lines.push("This project was not signed in.");
   }
-  if (!result.ok) lines.push("", `Result: ${result.outcome} (exit ${result.exit_code})`, message);
+  lines.push(...fields(style, rows), "");
+  if (login && result.ok && report.previous_grant_revocation === "unconfirmed") {
+    lines.push(...paragraph(style, "The previous grant was removed locally; the service did not confirm its revocation."), "");
+  }
+  if (!result.ok) lines.push(...paragraph(style, message), "");
   const next = report.next_action;
-  if (next?.message) lines.push(`Next: ${next.message}`);
-  if (next?.url) lines.push(`Connection guide: ${next.url}`);
-  return `${lines.join("\n")}\n`;
+  const guide = next?.url ?? null;
+  // A remote handoff names the Keys page where a person creates the
+  // Metadata key the agent then reads from METERGRAPH_AGENT_TOKEN.
+  const keys = next?.kind === "use_agent_key"
+    ? next.person_steps.find((step) => step.action === "create_metadata_key")?.url ?? null
+    : null;
+  if (reason === "runtime_not_supported") {
+    lines.push(...steps(style, [
+      ["Signing in from this machine?", style.bold("metergraph login --runtime local")],
+      ["Connecting a cloud agent?", guide],
+      ["Metadata key for the agent", keys],
+    ]));
+  } else {
+    lines.push(...steps(style, [["", next?.message ?? null], ["Keys page", keys], ["Connection guide", guide]]));
+  }
+  return render(lines);
 }