metergraph-cli 0.2.3 → 0.2.4

package/src/output.js

@@ -1,3 +1,4 @@
+import { actionHelpData, displayOptions } from "./action-help.js";
 import { PRICING_OPTIONS } from "./pricing-args.js";
 import {
   CONNECTION_GUIDE_URL,
@@ -28,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
@@ -49,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 = [
@@ -126,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 = {
@@ -144,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,
@@ -173,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] " +
@@ -217,19 +257,21 @@ 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.",
   },
 ];
@@ -259,11 +301,29 @@ const EXPERIMENTS_OPTIONS = [
     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. " +
+      "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",
@@ -291,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],
   },
@@ -449,8 +511,8 @@ 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]",
@@ -465,6 +527,7 @@ export function helpData(topic) {
       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.",
@@ -492,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,
       },
@@ -525,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 unless a person runs setup at a terminal (then local). 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." },
@@ -559,6 +622,13 @@ export function helpData(topic) {
           "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,
@@ -576,12 +646,34 @@ 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 `Usage: metergraph pricing models|lookup|calculate|cost|history|market [options] [--json]
+    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]
@@ -615,7 +707,7 @@ 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(
@@ -654,15 +746,18 @@ See docs/pricing.md for the supported contract, limitations and reference previe
       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 {
@@ -683,6 +778,28 @@ See docs/pricing.md for the supported contract, limitations and reference previe
       "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:",
@@ -697,12 +814,12 @@ See docs/pricing.md for the supported contract, limitations and reference previe
       "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",
+      "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 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.",
+      "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:",
     );
@@ -715,10 +832,10 @@ See docs/pricing.md for the supported contract, limitations and reference previe
       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",
@@ -764,7 +881,7 @@ See docs/pricing.md for the supported contract, limitations and reference previe
       "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\".",
       "",
@@ -788,45 +905,110 @@ See docs/pricing.md for the supported contract, limitations and reference previe
       "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",
-      "  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.',
-      '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.',
-      'Run "metergraph help experiments" for experiment options.',
-      "",
-      ...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) {
@@ -987,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, " +
@@ -1021,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.",
@@ -1037,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:
@@ -1047,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.",
@@ -1123,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) {