metergraph-cli 0.2.2 → 0.2.4

package/src/output.js

@@ -1,3 +1,5 @@
+import { actionHelpData, displayOptions } from "./action-help.js";
+import { PRICING_OPTIONS } from "./pricing-args.js";
 import {
   CONNECTION_GUIDE_URL,
   DEFAULT_ORIGIN,
@@ -27,7 +29,7 @@ import {
   SUPPORTED_PROFILES,
   VERSION,
 } from "./constants.js";
-import { PLAIN, fields, headline, paragraph, render, section, steps, toneFor } from "./style.js";
+import { PLAIN, fields, headline, paragraph, render, section, steps, toneFor, workspaceShown } from "./style.js";
 
 // Every JSON result, success or failure, has the same top-level keys:
 //   schema_version, command, ok, outcome, exit_code, data, error
@@ -48,7 +50,20 @@ export function envelope({ command, outcome, data = null, reason = null, message
 }
 
 export function toJsonLine(result) {
-  return `${JSON.stringify(result)}\n`;
+  return `${jsonText(result)}\n`;
+}
+
+// JSON.stringify escapes C0 controls but leaves C1 controls (a terminal may
+// read U+009B as an escape sequence) and bidirectional overrides as they are.
+// Inside a JSON string \uXXXX means the same character, so escaping them
+// changes nothing a parser sees and keeps them away from the terminal.
+const TERMINAL_UNSAFE = /[\u061c\u007f-\u009f\u200e\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069]/g;
+
+export function jsonText(value, indent = undefined) {
+  return JSON.stringify(value, null, indent).replace(
+    TERMINAL_UNSAFE,
+    (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`,
+  );
 }
 
 const DOCTOR_OPTIONS = [
@@ -125,9 +140,14 @@ const AGENT_PATH_HELP = [
   "  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",
+  "  A 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.",
+  "  Evaluations and analyses         A workspace owner creates a key with the Debug role and",
+  "                                   Allow evaluation writes, Allow evaluation previews and",
+  "                                   Allow analysis starts; the same METERGRAPH_AGENT_TOKEN",
+  "                                   serves the reads. status --json reports the role and each",
+  "                                   permission in data.access",
+  "Never pass a key as an argument. Replay keys are refused.",
 ];
 
 const CONFIG_DIR_OPTION = {
@@ -143,14 +163,34 @@ const LOGIN_OPTIONS = [
     name: "--runtime",
     value: "RUNTIME",
     summary:
-      "Required. Where this terminal runs, not which Metergraph service. local: your own machine, " +
+      "Required for scripts; inferred as local in an interactive local terminal. 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}.` },
   {
     name: "--workspace",
-    value: "UUID",
-    summary: "Expected workspace ID. Sign in fails unless the browser grants exactly this workspace.",
+    value: "SLUG",
+    summary:
+      "The workspace to sign in to, by its slug (on its Settings page) or its name. A service that can, offers " +
+      "approval for that workspace alone; sign in fails unless the browser grants it.",
+  },
+  {
+    name: "--role",
+    value: "ROLE",
+    summary:
+      "metadata (default): usage, cost and trace questions, no captured content. debug: also reads captured " +
+      "prompts and responses through Agent Access; the --allow-* options add workflow permissions to it.",
+  },
+  {
+    name: "--allow-evaluation-writes",
+    value: null,
+    summary: "With --role debug: Allow evaluation writes. Only a workspace owner approves the workflow permissions.",
+  },
+  { name: "--allow-evaluation-previews", value: null, summary: "With --role debug: Allow evaluation previews." },
+  {
+    name: "--allow-analysis-starts",
+    value: null,
+    summary: "With --role debug: Allow analysis starts, which replays captured prompts on model providers and spends money.",
   },
   { name: "--project", value: "DIR", summary: "Existing project directory to bind. Default: the current directory." },
   CONFIG_DIR_OPTION,
@@ -172,8 +212,9 @@ const LOGOUT_OPTIONS = [
 ];
 
 const LOGIN_USAGE =
-  "metergraph login --runtime local [--url ORIGIN] [--workspace UUID] [--project DIR] [--config-dir DIR] " +
-  "[--timeout-ms N] [--signup] [--no-browser] [--reconnect] [--json]";
+  "metergraph login --runtime local [--url ORIGIN] [--workspace SLUG] [--role metadata|debug] " +
+  "[--allow-evaluation-writes] [--allow-evaluation-previews] [--allow-analysis-starts] [--project DIR] " +
+  "[--config-dir DIR] [--timeout-ms N] [--signup] [--no-browser] [--reconnect] [--json]";
 const LOGOUT_USAGE = "metergraph logout [--project DIR] [--config-dir DIR] [--json]";
 const SETUP_USAGE = "metergraph setup --runtime local (--client codex|claude|cursor | --skip-skill) " +
   "[--url ORIGIN] [--workspace UUID] [--project DIR] [--config-dir DIR] [--env-file .env] " +
@@ -216,22 +257,73 @@ const READ_BASE_OPTIONS = [
     name: "--url",
     value: "ORIGIN",
     summary:
-      "Where a Metadata key is sent when the project is not bound. Default METERGRAPH_URL, else the hosted service. " +
+      "Where a coding-agent 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.",
+    value: "SLUG",
+    summary:
+      "The workspace the credential must be for, by its slug or name (or ID). 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. " +
+      "Private (0600) file holding a coding-agent key with the Metadata or Debug role. 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 the Metadata or Debug role. " +
+      "For start: a key with Debug access and Allow analysis starts, used for that one request.",
+  },
+  JSON_OPTION,
+];
+const TOOLS_USAGE = [
+  "metergraph tools list [--name TOOL] [read options] [--json]",
+  "metergraph tools call TOOL [--args JSON | --args-file PATH] [--yes] [read options] [--json]",
+];
+const TOOLS_OPTIONS = [
+  { name: "--name", value: "TOOL", summary: "list only: show one tool, with its input schema under --json." },
+  { name: "--args", value: "JSON", summary: "call only: the tool's arguments as one JSON object. Default {}." },
+  { name: "--args-file", value: "PATH", summary: "call only: a file holding the arguments as one JSON object, up to 1 MiB." },
+  {
+    name: "--yes",
+    value: null,
+    summary:
+      "call only: run a tool that writes, starts work or calls a model provider. Pass it only after the person " +
+      "has approved this exact call.",
+  },
+  ...READ_BASE_OPTIONS,
+  JSON_OPTION,
+];
 const DAYS_OPTION = {
   name: "--days",
   value: "N",
@@ -259,21 +351,23 @@ const limitOption = (fallback, extra = "") => ({
   summary: `Rows to return, 1 to ${READ_MAX_LIMIT}. Default ${fallback}.${extra}`,
 });
 const READ_BASE_USAGE =
-  "[--url ORIGIN] [--workspace UUID] [--agent-token-file PATH] [--project DIR] [--config-dir DIR] [--timeout-ms N] [--json]";
+  "[--url ORIGIN] [--workspace SLUG] [--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, except --environment, --since and --until on usage.";
 
 // 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.
+// coding-agent key with the Metadata or Debug role, makes GET requests to fixed
+// paths on the verified origin and never opens a browser.
 export const READ_HELP = Object.freeze([
   {
     name: "status",
     usage: `metergraph status ${READ_BASE_USAGE}`,
     summary:
       "Show whether this project is configured, the service is reachable and reports the bound deployment " +
-      "profile, and the grant is verified for the bound workspace, with its Metadata capabilities. " +
+      "profile, and the grant is verified for the bound workspace, with its Metadata capabilities. Reports " +
+      "the credential's role (Metadata or Debug) and its workflow permissions (Allow evaluation writes, Allow " +
+      "evaluation previews, Allow analysis starts) in data.access, and how to grant them. " +
       "Never claims application traffic is verified.",
     options: [...READ_BASE_OPTIONS, JSON_OPTION],
   },
@@ -417,13 +511,14 @@ function optionLines(options, minimum) {
   return options.map((option, index) => `  ${flags[index].padEnd(width)}${option.summary}`);
 }
 
-export function helpData(topic) {
-  return {
+export function helpData(topic, action = null) {
+  const data = {
     topic,
     usage: [
       "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,
@@ -431,8 +526,13 @@ export function helpData(topic) {
       SETUP_USAGE,
       VERIFY_USAGE,
       ...READ_HELP.map((entry) => entry.usage),
+      ...EXPERIMENTS_USAGE,
+      ...TOOLS_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:
@@ -455,7 +555,7 @@ export function helpData(topic) {
       {
         name: "skills install",
         summary:
-          "Copy the Metergraph workflow skills bundled with this CLI, such as the model-swap loop, into one " +
+          "Copy the Metergraph workflow skills bundled with this CLI, such as model swap, into one " +
           "client's project skill directory. Never replaces a skill it did not install. No network requests, no sign in.",
         options: SKILL_OPTIONS,
       },
@@ -488,13 +588,13 @@ 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: "Local terminal: inferred automatically. Scripts: required. 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." },
           CONFIG_DIR_OPTION,
           { name: "--env-file", value: "FILE", summary: "Project-relative env file. Default: .env." },
-          { name: "--client", value: "CLIENT", summary: "Install the bundled skill for codex, claude or cursor." },
+          { name: "--client", value: "CLIENT", summary: "codex, claude or cursor. A local interactive setup asks when omitted." },
           { name: "--skip-skill", value: null, summary: "Explicitly leave client skill installation pending." },
           { name: "--timeout-ms", value: "N", summary: "Time to wait for browser approval." },
           { name: "--signup", value: null, summary: "Start at hosted sign up when the project needs login." },
@@ -514,6 +614,21 @@ export function helpData(topic) {
         summary: "Poll Metadata for one exact trace in an explicit invocation window. Never sends application traffic.",
         options: VERIFY_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,
+      },
+      {
+        name: "tools",
+        summary:
+          "List the Agent Access tools this credential can use and call one, as an MCP client would. A tool that " +
+          "writes, starts work or calls a model provider runs only with --yes.",
+        options: TOOLS_OPTIONS,
+      },
       ...READ_HELP.map(({ name, summary, options, examples }) => ({
         name,
         summary,
@@ -531,10 +646,69 @@ export function helpData(topic) {
       meaning: EXIT_CODE_MEANINGS[outcome],
     })),
   };
+  if (action) data.action = { name: action, ...actionHelpData(topic, action, data.commands) };
+  return data;
 }
 
-export function helpText(topic, style = PLAIN) {
+export function helpText(topic, style = PLAIN, action = null, advanced = false) {
   const lines = [];
+  if (action) {
+    const entry = actionHelpData(topic, action, helpData(topic).commands);
+    if (entry) return formatHelp([
+      `Usage: ${entry.usage}`, "", entry.summary, "", "Examples:",
+      ...entry.examples.map(example => `  ${example}`), "", "Options:",
+      ...optionLines(displayOptions(entry.options, topic, action, advanced), 20), "", entry.note, "",
+      ...(advanced ? [] : [`Connection settings: metergraph ${topic} ${action} --help --advanced`]),
+    ], style);
+  }
+  if (topic === "exit-codes") {
+    lines.push("Exit codes:", "", "For scripts. Human output describes the result and what to do next.", "");
+    for (const [outcome, code] of Object.entries(EXIT_CODES)) {
+      lines.push(`  ${String(code).padEnd(4)}${outcome}`, ...paragraph(style, EXIT_CODE_MEANINGS[outcome], "      "), "");
+    }
+    return formatHelp(lines, style);
+  }
+  if (topic === "agents") return formatHelp([
+    "Connect a coding agent", "", ...AGENT_PATH_HELP, "", ...AGENT_APPROVAL_HELP,
+    "", 'Use --json for structured results. Run "metergraph help exit-codes" for scripting outcomes.',
+  ], style);
+  if (topic === "pricing") {
+    return formatHelp(`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.
+`.split("\n"), style);
+  }
   if (topic === "doctor") {
     lines.push(
       "Usage: metergraph doctor [--url ORIGIN] [--timeout-ms N] [--json]",
@@ -560,6 +734,8 @@ export function helpText(topic, style = PLAIN) {
       "--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:");
     lines.push(...optionLines(helpData(null).commands.find((entry) => entry.name === "setup").options, 25));
     lines.push("", ...AGENT_APPROVAL_HELP);
@@ -570,15 +746,18 @@ export function helpText(topic, style = PLAIN) {
       lines.push(
         "Opens your browser on the service's own sign in and workspace consent pages, then",
         "binds this project to the workspace you approve. The CLI receives a delegated grant",
-        `limited to the Metadata scope (${METADATA_SCOPE}) and verifies the workspace, profile`,
-        "and scope with the service before saving anything. Your browser keeps its own sign in.",
+        `limited to the Metadata role (${METADATA_SCOPE}), or with --role debug to the Debug role and`,
+        "the workflow permissions the --allow-* options name, which only a workspace owner approves.",
+        "It verifies the workspace, profile and scope with the service before saving anything. Your",
+        "browser keeps its own sign in. Signing in again with another role or other permissions",
+        "replaces the grant.",
         "The grant is saved in your private config directory; the project gets only",
         ".metergraph/project.json, which holds no credentials.",
         "",
         "Login does not create an application ingest key, and no manual API key is required.",
-        "The service records the grant as a Metadata-only OAuth connection, separate from any",
-        "API or ingest key you manage. Login reads no telemetry or content and never asks for",
-        "Debug or Replay access. Rerunning it on a signed in project changes nothing.",
+        "The service records the grant as an OAuth connection, separate from any API or ingest",
+        "key you manage. Login reads no telemetry or content and never asks for Replay access.",
+        "Rerunning it on a signed in project with the same role and permissions changes nothing.",
         "",
       );
     } else {
@@ -599,6 +778,52 @@ export function helpText(topic, style = PLAIN) {
       "Opening requires a server link that selects the verified workspace; older links get a manual handoff.",
       "", "Options:");
     lines.push(...optionLines(VERIFY_OPTIONS, 22));
+  } else if (topic === "tools") {
+    lines.push(
+      "Usage:",
+      ...TOOLS_USAGE.map((usage) => `  ${usage}`),
+      "",
+      "Every Agent Access tool the service offers this credential, through its MCP endpoint, with the same",
+      "saved sign in or coding-agent key as the read commands and the same checks first. The service decides",
+      "which tools a credential sees: a Metadata credential gets the Metadata tools; the Debug role adds trace",
+      "content and evaluation reads, and Allow evaluation writes, Allow evaluation previews and Allow analysis",
+      "starts add the tools they name. Replay keys are refused.",
+      "",
+      "list prints the tools with whether each only reads. Under --json each carries its title, description",
+      "and input schema. call sends one tools/call with --args or --args-file and prints the tool's structured",
+      "result in data.result. A tool the service does not mark read-only, or marks as calling a model provider,",
+      "needs --yes: without it the command exits 18 (action_required, confirmation_required) and sends",
+      "nothing. Pass --yes only after the person has approved that exact call. A refusal by the tool exits 19",
+      "(refused) with the service's error in data.tool_error; a write whose answer was lost exits 20",
+      "(unconfirmed).",
+      "",
+      "Options:",
+    );
+    lines.push(...optionLines(TOOLS_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 sign in or a coding-agent 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 the Debug role and Allow analysis starts, which only a",
+      "workspace owner can grant, in --agent-token-file or METERGRAPH_AGENT_TOKEN.",
+      "The CLI checks the key before it sends the one start request. 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(
@@ -607,10 +832,10 @@ export function helpText(topic, style = PLAIN) {
       entry.summary,
       "",
       "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",
+      "this machine, a coding-agent key from METERGRAPH_AGENT_TOKEN or --agent-token-file, with the",
+      "Metadata role or the Debug role. A key is sent only after the origin answers as a supported",
+      "Metergraph service, and nothing is read until the service shows one of those roles (never",
+      "Replay) 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",
@@ -656,7 +881,7 @@ export function helpText(topic, style = PLAIN) {
       "Copies the Metergraph workflow skills bundled with this CLI into one client's project",
       "skill directory, one folder per skill, and records ownership of each in",
       ".metergraph/skills/NAME.json. The skills come from https://github.com/metergraph/skills",
-      "at the commit this release pins. They cover investigation and the model-swap loop:",
+      "at the commit this release pins. They cover investigation and model swap:",
       "choose a workload, choose traces and models, define the eval, run the analysis,",
       "summarize the report and rerun. The setup skill is installed by \"metergraph skill\".",
       "",
@@ -680,42 +905,110 @@ export function helpText(topic, style = PLAIN) {
       "Discovery stays pending until the client itself loads the skills.",
     );
   } else {
-    lines.push(
-      `metergraph ${VERSION} (preview)`,
-      "",
-      "Usage:",
-      "  metergraph --help [--json]       Show this help",
-      "  metergraph --version [--json]    Show the CLI version",
-      "  metergraph doctor [options]      Check a Metergraph service, read only",
-      "  metergraph skill install|update  Install or update the agent skill in a project",
-      "  metergraph skills install|update|list  Workflow skills, such as the model-swap loop",
-      "  metergraph login [options]       Sign in and bind a project to a workspace",
-      "  metergraph logout [options]      Revoke and remove a project's sign in",
-      "  metergraph setup [options]       Approve and write a private ingest key",
-      "  metergraph verify [options]      Find one exact processed trace",
-      "  metergraph status [options]      Show configured, reachable and verified state",
-      "  metergraph context [options]     Show the verified workspace",
-      "  metergraph capabilities [opts]   Show the agent reads offered to this grant",
-      "  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",
-      "",
-      'Run "metergraph help doctor" for doctor options.',
-      'Run "metergraph help skill" for skill options.',
-      'Run "metergraph help skills" for workflow skill options.',
-      '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.',
-      "",
-      ...AGENT_PATH_HELP,
-    );
+    return rootHelp(style);
   }
-  lines.push("", "Exit codes:");
-  for (const [outcome, code] of Object.entries(EXIT_CODES)) {
-    lines.push(`  ${String(code).padEnd(3)}${outcome.padEnd(25)}${style.dim(EXIT_CODE_MEANINGS[outcome])}`);
+  // Reference material is opt-in; everyday help stays focused on this command.
+  return commandHelp(topic, lines, style, advanced);
+}
+
+function commandHelp(topic, lines, style, advanced) {
+  const optionsAt = lines.indexOf("Options:");
+  if (optionsAt < 0) return formatHelp(lines, style);
+  const optionsEnd = lines.indexOf("", optionsAt + 1);
+  const usageEnd = lines.indexOf("");
+  const examples = {
+    setup: ["metergraph setup", "metergraph setup --runtime local --client codex --json --no-browser"],
+    login: ["metergraph login", "metergraph login --runtime local --no-browser"],
+    logout: ["metergraph logout"], doctor: ["metergraph doctor"],
+    verify: ["metergraph verify --trace-id TRACE_ID --since START_ISO_TIME --until END_ISO_TIME"],
+    status: ["metergraph status"], context: ["metergraph context"], capabilities: ["metergraph capabilities"],
+    usage: ["metergraph usage --days 7"], routes: ["metergraph routes"], traces: ["metergraph traces --limit 10"],
+    skill: ["metergraph skill install --client codex"], skills: ["metergraph skills list"],
+    experiments: ["metergraph experiments list", "metergraph experiments estimate --help"],
+  }[topic] ?? [];
+  const notes = lines.slice(usageEnd + 1, optionsAt);
+  const command = helpData(topic).commands.find(entry => entry.name === topic);
+  const options = command ? ["Options:", ...optionLines(displayOptions(command.options, topic, null, advanced), 22)]
+    : lines.slice(optionsAt, optionsEnd < 0 ? lines.length : optionsEnd);
+  const synopsis = {
+    setup: "metergraph setup [--client CLIENT | --skip-skill] [options]",
+    login: "metergraph login [--runtime local] [options]",
+    logout: "metergraph logout [options]",
+    verify: "metergraph verify (--trace-id ID | --request-id ID) --since TIME --until TIME [options]",
+    ...Object.fromEntries(READ_HELP.map(entry => [entry.name, `metergraph ${entry.name} [options]`])),
+  }[topic];
+  return formatHelp([
+    ...(synopsis ? [`Usage: ${synopsis}`] : lines.slice(0, usageEnd)), "", "Examples:", ...examples.map(example => `  ${example}`),
+    ...(topic === "setup" || topic === "login" ? ["", "Local terminals guide missing choices. Scripts require explicit flags.",
+      "With --json --no-browser, a step that needs browser approval exits 18 (action_required) with the URL in " +
+      "data.next_action.url; approve it, then run the same command again."] : []),
+    "", ...options,
+    ...(advanced ? ["", "Details", ...notes, ...lines.slice(optionsEnd < 0 ? lines.length : optionsEnd)]
+      : ["", `Connection settings and details: metergraph ${topic} --help --advanced`]),
+  ], style);
+}
+
+function rootHelp(style) {
+  const groups = [
+    ["Get started", [
+      ["setup", "Connect your app and install an agent skill"],
+      ["login", "Sign in to a workspace"],
+      ["status", "Check this project's connection"],
+    ]],
+    ["Explore", [
+      ["usage", "View costs and token usage"],
+      ["traces", "Browse trace metadata"],
+      ["routes", "List routes and evaluation contracts"],
+      ["experiments", "Estimate and run model comparisons"],
+      ["tools", "List and call the tools your coding agent can use"],
+      ["pricing", "Look up public model prices; no account needed"],
+    ]],
+    ["Manage", [
+      ["verify", "Verify one processed trace"],
+      ["doctor", "Check service health"],
+      ["context", "Show the connected workspace"],
+      ["capabilities", "Show available workspace reads"],
+      ["skill", "Install or update the setup skill"],
+      ["skills", "Install, update or list workflow skills"],
+      ["logout", "Sign out of this project"],
+    ]],
+  ];
+  const lines = [style.bold("Metergraph") + " " + style.dim(`${VERSION} · preview`),
+    "Understand your AI usage and compare models.", "", "Usage: metergraph <command> [options]", ""];
+  for (const [title, commands] of groups) {
+    lines.push(section(style, title), ...fields(style, commands), "");
   }
-  // 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`;
+  lines.push(section(style, "Try it"),
+    "  metergraph setup --runtime local --client codex",
+    "  metergraph pricing models --limit 10", "",
+    'Run "metergraph <command> --help" for options and examples.',
+    'Use --json for scripts; --version to show the version.',
+    'Scripting reference: metergraph help exit-codes.',
+    'Connecting a cloud agent? Run "metergraph help agents".');
+  return formatHelp(lines, style);
+}
+
+function formatHelp(lines, style) {
+  return render(lines.flatMap((line) => {
+    if (!line) return [""];
+    if (line.length <= style.width && !/^(Usage|Options|Examples|Exit codes):/.test(line)) return [line];
+    if (/^(Usage|Options|Examples|Exit codes):/.test(line)) {
+      const [first, ...rest] = paragraph(style, line, "");
+      return [style.bold(first), ...rest];
+    }
+    // Preserve option and command columns, with a hanging indent on small terminals.
+    const row = /^(  \S.*?) {2,}(\S.*)$/.exec(line);
+    if (row && Number.isFinite(style.width)) {
+      const prefix = row[1] + "  ";
+      if (prefix.length > style.width / 2) {
+        return [row[1], ...paragraph(style, row[2], "    ")];
+      }
+      const wrapped = paragraph(style, row[2], " ".repeat(prefix.length));
+      return [prefix + wrapped[0].trimStart(), ...wrapped.slice(1)];
+    }
+    return paragraph(style, line.trimStart(), line.match(/^ */)[0]);
+  }));
+
 }
 
 export function skillText(result, message, style = PLAIN) {
@@ -876,6 +1169,8 @@ export function doctorText(result, style = PLAIN) {
 // Fixed text for every login, logout and session reason. Reasons shared
 // with doctor fall back to its wording.
 const AUTH_MESSAGES = {
+  local_docker_transport_required:
+    "Local credentials and consent require a verified Docker transport. This CLI has no configured Docker transport; nothing was sent. Update the local bundle and use its Docker-mediated bin/agent-key command, or connect this CLI to an authenticated HTTPS deployment.",
   runtime_not_supported:
     "--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, " +
@@ -910,6 +1205,7 @@ const AUTH_MESSAGES = {
   oauth_metadata_missing: "This service does not support CLI sign in yet. Nothing was written.",
   metadata_scope_unsupported:
     "This service does not offer Metadata-only access for the CLI yet. The CLI does not fall back to broader access.",
+  debug_scope_unsupported: "This service does not offer Debug access for CLI sign in. Nothing was saved.",
   endpoint_not_allowed: "The service advertised an authorization endpoint outside its own origin or known paths.",
   resource_mismatch: "The service's protected resource does not match this origin.",
   issuer_mismatch: "The service's authorization issuer does not match this origin.",
@@ -926,6 +1222,14 @@ const AUTH_MESSAGES = {
   client_mismatch: "The issued grant is for a different client. Nothing was saved.",
   scope_mismatch: "The issued grant is not limited to exactly the Metadata scope. It was not kept.",
   workspace_mismatch: "The browser granted a different workspace than --workspace. It was not kept.",
+  workspace_hint_ambiguous:
+    "More than one of your workspaces has the name --workspace gave, so the consent page offered no approval. " +
+    "Nothing was granted.",
+  workspace_hint_unknown:
+    "None of your workspaces has the slug or name --workspace gave, so the consent page offered no approval. " +
+    "Nothing was granted.",
+  workspace_name_unsupported:
+    "This service cannot match a workspace by name. Use its slug, which its Settings page shows. Nothing was sent.",
   workspace_context_mismatch: "The service reported a different workspace than the grant names. It was not kept.",
   profile_mismatch: "The service reported a different deployment profile than before sign in. It was not kept.",
   deployment_profile_mismatch:
@@ -936,6 +1240,8 @@ const AUTH_MESSAGES = {
     "The grant would allow content, replay or provider access, which login never accepts. It was not kept.",
   access_rejected: "The service refused the new grant. Nothing was saved.",
   invalid_project: "--project must name an existing directory.",
+  secure_writes_unavailable:
+    "Secure automatic file writes are unavailable on this platform or the bundled filesystem helper failed verification. Nothing was written.",
   invalid_config_dir: "METERGRAPH_CONFIG_DIR must be an absolute path.",
   unsafe_path: "A path in .metergraph is a symbolic link or is not a regular file or directory. Nothing was changed.",
   binding_invalid: "The project binding .metergraph/project.json is not valid. Nothing was changed.",
@@ -1012,7 +1318,7 @@ export function authText(result, message, style = PLAIN) {
   const lines = [headline(style, toneFor(result.outcome), title, result.outcome), ""];
   const rows = [
     ["Origin", report.origin],
-    ["Workspace", report.workspace?.id ?? null],
+    ["Workspace", workspaceShown(report.workspace)],
     ["Profile", report.deployment_profile || null],
   ];
   if (login && result.ok) {