metergraph-cli 0.2.0-preview.4 → 0.2.0-preview.6

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

@@ -0,0 +1,156 @@
+---
+name: metergraph-onboarding
+description: Guide a coding agent from an empty local or hosted MeterGraph workspace to a verified application trace, then hand off to workload and eval selection.
+---
+
+# Set up MeterGraph through the first usable trace
+
+Confirm the user's deployment choice, application repository, target workspace,
+coding client and whether they want SDK instrumentation or an existing supported
+import. Use the actual MeterGraph origin the user selected. Do not guess an
+origin from a credential. Record client/version, application revision, setup
+start time and fixture source. Keep demo, synthetic, import and application
+traffic distinct.
+
+## Establish the deployment and workspace
+
+For hosted MeterGraph, connect with OAuth. No operator-issued key is needed.
+Add the hosted endpoint as an HTTP MCP server with no credential or headers,
+for example `claude mcp add --transport http metergraph
+https://app.metergraph.dev/v1/agent/mcp`. Then use the client's own
+authentication step (in Claude Code, `/mcp`, choose `metergraph`, then
+Authenticate). The human completes browser sign-in and consent in the browser,
+in the workspace they intend to use, and confirms the workspace shown on the
+consent page. The consent page names the requested role; a client following
+the server's challenge requests Metadata. If the client cannot
+complete OAuth, or the user needs retained content or replay, describe the
+Keys-page scoped connection as a manual alternative and obtain the user's
+choice. Never silently fall back to a key.
+
+For the first application trace, check the installed Metergraph CLI's version
+and help before naming commands. `metergraph-cli@0.1.0` has `doctor` and project
+skill installation; a later installed version may offer `login`, `setup` and
+`verify`. Use only commands present in that installation. Otherwise follow
+https://www.metergraph.dev/docs/start/first-trace/ and its manual setup steps.
+Do not infer that a server endpoint or source-only CLI command has shipped.
+
+For customer-local MeterGraph, use `metergraph-local-bundle` to stand up the
+released bundle, then continue here. Use its included README, signed manifest
+and verification files. The human obtains the current
+pull-only registry credential; registry access is not yet universally self-serve.
+Use password-stdin and the local secret store for registry login. Verify the
+archive before running its scripts. Configure the bundle's local settings,
+start with `./bin/start`, and inspect `./bin/status` and the reported readiness.
+Use the bundle's printed loopback URL. Record bundle version and image digests.
+The human sets their local admin/database passwords and signs in. Reuse the
+bundle's startup/recovery instructions; do not replace them with an ad-hoc
+Compose stack. First boot may ingest a demo trace, which is synthetic evidence.
+
+## Connect the coding client
+
+For hosted OAuth, the connection is the URL-only server added above. For a
+keyed or customer-local connection, reuse the Keys page's client-specific
+instructions, documented in
+https://www.metergraph.dev/docs/guides/agent-access/. The endpoint is
+`<origin>/v1/agent/mcp`; the stdio bridge is `metergraph-mcp` with
+`METERGRAPH_URL` and `METERGRAPH_AGENT_TOKEN` in its environment. Verify
+`tools/list`, then `metergraph_get_workspace_context` and
+`metergraph_get_capabilities`. Record the selected origin separately: `managed` identifies the hosted profile
+and does not distinguish staging from production. Match the returned workspace ID and deployment
+to the user's selection before reading traces. Capabilities and required scopes
+from this connection are authoritative. Do not infer write authority from
+`agent:read` or provider authority from a healthy MCP connection.
+
+Keep these credentials separate:
+
+| Credential | Destination and purpose | Human step |
+| --- | --- | --- |
+| Registry pull credential | Image registry only | Obtain/refresh through the supported distribution channel |
+| Ingest credential | Application SDK or supported import connector | Create an ingest key for the selected workspace |
+| Agent Access credential | Coding client's supported OAuth/secret configuration | Sign in/consent or create a scoped connection |
+| Model-provider credential | Deployment's supported runner/provider configuration | Set the provider key and approve paid execution |
+
+Never ask for secrets in chat, commit them, put them in a shared MCP file or
+save them in verification evidence. A read connection is sufficient for this
+onboarding verification. Replay, eval previews and analyses make separate
+authorization and cost decisions.
+
+## Instrument or import application traffic
+
+Reuse the appropriate language/provider instructions and the repository prompt
+at https://www.metergraph.dev/docs/agents/instrument-a-repo/#verify-one-application-call, or a supported
+connector under https://www.metergraph.dev/docs/import/overview/. Inspect the real
+application entry points first. Exclude tests, fixtures, mock libraries, demos
+and validation jobs from production traffic claims. Keep provider base URLs,
+gateway credentials and application behavior intact. Review instrumentation
+changes with the user, including calls that could not be captured.
+
+Use the selected deployment's ingestion destination and the ingest credential,
+not its MCP URL or Agent Access key. Use that deployment's SDK/connector setup
+instructions to choose the complete ingest URL. Set capture/retention as the
+workspace owner intends; metadata-only telemetry does not prove retained
+inputs/outputs needed for eval replay. Do not silently enable content capture.
+Avoid treating received HTTP acceptance as worker processing completion.
+
+With user authorization, trigger one normal application request/job and record
+its application-owned trace ID and time. For an import, record the supported
+connector, source trace identity and imported time window. Do not create an LLM
+connection, paid eval rule or provider invocation just to manufacture proof.
+
+## Verify and hand off
+
+1. Read bounded `metergraph_get_ingestion_health` if available. Preserve pending,
+   processed and failed states and receive/process timestamps. Counts apply to
+   a workspace window; they do not identify the batch that contains one trace.
+2. Read bounded `metergraph_query_traces` in the same workspace/time window and
+   locate the exact application/import trace ID. Continue bounded pagination
+   when advertised. An empty page is a setup state, not proof of no ingestion.
+3. If the user permits a content-class read and `trace_content` is available,
+   inspect one `metergraph_get_trace` for retained usable input/output and capture
+   warnings. Record availability and omissions, never the content in setup logs.
+4. When advertised, use classified-workload and model-readiness tools to explain
+   available cohorts, capture eligibility, supported checks and missing provider
+   credentials. A configured credential is not proof of a successful provider
+   call. Missing capability is an explicit handoff blocker.
+5. Return workspace/profile, bundle/app/client revisions, source label, exact
+   trace ID/time window, ingestion and capture evidence, warnings, human steps
+   still needed and the next eval selection action. A synthetic demonstration
+   does not meet real application or hosted pilot acceptance.
+
+Verify the named trace through the connected client's advertised MCP tools,
+with an explicit source label and the same workspace/deployment before and
+after any permitted content read. The older trace-debug contract has no
+workspace envelope, so confirm its tenant-bound connection separately. Trace
+discovery is not analysis readiness. Keep retained content out of setup reports.
+
+## Recovery
+
+| State | Next action |
+| --- | --- |
+| Signup, sign-in or OAuth consent required | Hand the browser step to the human, then reconnect and verify workspace identity |
+| Registry access expired/denied | Refresh the pull credential through the supported distribution channel, repeat registry login, retain local data |
+| Local startup or bootstrap failure | Inspect `bin/status` and the bundle's named logs/readiness checks; follow its recovery instructions |
+| Runner unavailable | Use the bundle's runner health instructions; do not claim MCP health proves analysis readiness |
+| Empty data | Check application environment, correct ingest destination/key, flush/import window and worker status; exclude demos/mocks |
+| Received but pending/failed | Inspect ingestion failure classes and the existing retry/recovery flow before changing instrumentation |
+| Missing/retained content unavailable | Explain capture policy, retention and omission; collect a new permitted application trace |
+| Agent credential revoked or insufficient scope | Reconnect/re-authorize through the workspace owner's supported path; do not use an ingest key |
+| Provider key absent or candidate unsupported | Complete the runner/provider setup or choose an available candidate; defer paid execution |
+| API capability unavailable | State the unsupported deployment boundary and the specific supported next step |
+
+Do not run destructive `down --volumes` as recovery. The bundle warns that raw
+payload persistence differs from database persistence; prefer its stop/start
+procedure and preserve existing data. Refine and rerun evals only through the
+separately authorized workflow. Packaging this skill belongs to the distribution
+workflow; this source does not assert that plugin OAuth/configuration or hosted
+onboarding has already shipped.
+
+Use the public skill's current client/runtime/deployment table at
+https://www.metergraph.dev/SKILL.md. An unimplemented cloud/OAuth client path
+is blocked even if server code exists. Query an exact SDK trace ID, or resolve a
+provider request ID only when that argument is advertised. Ambiguous request IDs
+need confirmation from the application; never select the first match. Preserve
+checkpoint source run, pattern and pattern-set identities in workload queries and
+cursor continuation. Missing/fallback IDs and expired records leave incomplete
+evidence. Read classification availability separately from failed analysis and
+report availability. Discovery must not launch or spend on classification or analysis.

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

@@ -0,0 +1,91 @@
+---
+name: metergraph-report
+description: Summarize a finished Metergraph analysis in a few lines with the link to its report in the app, say whether the evidence supports a switch, no switch or more testing, and tell the person exactly what to inspect in the app. Use after an analysis completes, when someone asks "what did the analysis find", "should we switch", "give me the report link", or stage 5 of the metergraph-model-swap loop.
+---
+
+# Summarize the report and hand off to the app
+
+The coding agent gives the answer and the link. The app is where the person
+reads the full report and inspects case-level evidence.
+
+## 0. Confirm the connection
+
+If this conversation has not already confirmed the workspace, call
+`metergraph_get_workspace_context`, then `metergraph_get_capabilities`, before
+anything else. Say which workspace you are connected to in one line, and plan
+only with the tools the capabilities advertise.
+
+## 1. Read it
+
+1. `metergraph_get_analysis_run` with the run ID. Continue only when the status
+   is final. If `report.available` is false on a completed run, the report is
+   missing: say so and give the run's page (below).
+2. `metergraph_get_report` with `report.analysis_id`. Read the `outcome`, each
+   workload's `state`, `sample_count` and `reason`, each `model_swap`
+   opportunity (`recommendation_status`, `quality_vs_reference`,
+   `safe_switch_rate`, `cost_ratio`, `quality_grade_counts`,
+   `evaluation_gate`, `savings_usd`), `spend_projection`,
+   `analysis_generation_cost` and every warning.
+3. Read evidence with `metergraph_get_report_evidence` only if the person asks
+   about specific cases and the key has the Debug role. It returns captured
+   content.
+
+## 2. Write the summary
+
+At most eight lines, in this order:
+
+```
+<Switch | Don't switch | Test more>: <workload> from <current model> to <candidate>.
+Quality: <quality_vs_reference>, <safe_switch_rate> of cases safe to switch, graded on <n> samples against <eval revision or "default graders">.
+Cost: <cost_ratio>× per call; about $<savings_usd>/month projected from <observed_days> days of traffic.
+Runner-up: <candidate> — <one reason it lost>.
+Caveats: <sample size, short window, partial coverage, failed candidates, no eval bound>.
+Report: <link>
+Inspect: <the one thing to look at in the app>
+```
+
+Rules:
+
+- Every number comes from the report. Say "projected" for `spend_projection`
+  figures; a projection from a few days of traffic is not observed savings.
+- Keep quality failures, evaluator or execution failures and missing coverage
+  apart. A candidate with missing results has not passed.
+- If no eval was bound, say the grades came from default graders, not from the
+  person's own quality bar, and point to `metergraph-evals`.
+- `no_opportunities` is a real answer: the candidates did not beat the current
+  model within the bar. `no_eligible_workloads` with `insufficient_samples`
+  needs more traffic, not a rerun.
+- If the person's code shows where this workload's model is set, name the file
+  and line and suggest a canary experiment. Do not change code without a
+  separate instruction.
+
+## 3. Links
+
+Use a link a tool returned (`metergraph_links`, `links`) exactly as given.
+Otherwise build it from the origin of the Metergraph server the agent is
+connected to (hosted is `https://app.metergraph.dev`; the customer-local bundle
+is normally `http://127.0.0.1:8080`) and these app routes:
+
+| Page | Route |
+| --- | --- |
+| Report | `<origin>/#analysis?report=<analysis_id>` |
+| One workload's results in a report | `<origin>/#analysis/<analysis_id>/workloads/<workload_id>/model_evaluation` |
+| Workload evidence | `<origin>/#workloads?pattern=<workload_id>&report=<analysis_id>` |
+| Eval definition used | `<origin>/#analysis/<analysis_id>/workloads/<workload_id>/eval_definition` |
+| All analyses and runs | `<origin>/#opportunities` |
+
+Say that a built link was built, not returned, in a few words. If the person
+says it does not open, give the Opportunities page instead.
+
+## 4. What to inspect in the app
+
+Name one or two concrete things, from what the report shows:
+
+- cases where the candidate was graded worse than the current model, to judge
+  whether the grader or the candidate is wrong;
+- a check with a surprising pass rate, which may be a bad check;
+- the cost of the cases that drive most of the spend.
+
+Then ask the person to come back with what they found: grades they disagree
+with, cases that should be added, or a candidate to drop. That is the input to
+`metergraph-iterate`.

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

@@ -0,0 +1,94 @@
+---
+name: metergraph-workloads
+description: Choose which Metergraph workload to analyze - list classified workloads, rank them by spend with the source of each number stated, flag anomalies and suspect data, check readiness, and hand off when classification has not run. Use for "what is my largest workload", "list my workloads", "which workload should we optimize", or stage 1 of the metergraph-model-swap loop.
+---
+
+# Choose a workload
+
+The goal is one classified workload, its exact `selection_reference`, and a
+one-sentence reason it was chosen.
+
+## 0. Confirm the connection
+
+If this conversation has not already confirmed the workspace, call
+`metergraph_get_workspace_context`, then `metergraph_get_capabilities`, before
+anything else. Say which workspace you are connected to in one line, and plan
+only with the tools the capabilities advertise.
+
+## 1. Read what exists
+
+1. `metergraph_list_classified_workloads` with a small limit (10). Each item
+   has a `display_name`, `classified_sample_count` and a `selection_reference`
+   of `source_run_id`, `pattern_id` and `pattern_set_version`. Keep the
+   reference exactly as returned. The name is a label.
+2. `metergraph_list_routes` and `metergraph_get_usage` with `days: 30`. These
+   give cost, calls, tokens, latency and errors per route per UTC day, plus
+   each route's `constraints` and `replay_eligible_calls`.
+3. `metergraph_list_reports` with a small limit. If a recent report exists,
+   `metergraph_get_report` gives each workload's `spend_projection`.
+
+## 2. Rank by spend, and say where each number came from
+
+There are two kinds of spend number. Do not mix them in one column.
+
+| Number | Source | Meaning |
+| --- | --- | --- |
+| Observed cost | `metergraph_get_usage` | What was ingested in the window. Per route, not per workload. |
+| Projected spend | a report's `spend_projection` (`daily_rate_usd`, `projected_monthly_cost_usd`, `population`) | An extrapolation the analysis made. Per workload. |
+
+The app's pages can show projected numbers. If the person quotes figures from
+the app that do not match what you read, say which source each one is before
+ranking, and ask which one they mean. Never rank on classified sample counts:
+they are the sample, not the traffic.
+
+Rank on a typical day, not the total. Compute each route's median daily cost
+over the window. If one day or one hour dominates a route's total, call it out
+as a spike and investigate it with `metergraph_list_incidents` and
+`metergraph_query_traces` (status and error counts) before treating that route
+as large. A runaway loop or retry storm is a bug to fix, not a model to swap.
+
+Present at most the top five, one line each: workload, current model(s), typical
+daily cost, share of typical spend, and one reason it is or is not a good
+candidate. Opus-class models on extraction, classification or short-output
+work are the usual best candidates. Workloads already on small models, or
+under about 5% of spend, rarely repay an analysis.
+
+## 3. Check the data is real
+
+Say so before planning when any of these hold, with the numbers:
+
+- the workspace or all its data is only hours old, or arrived in one ingest
+  batch (`metergraph_get_ingestion_health`);
+- incidents or usage disagree with each other for the same day;
+- traces are labeled synthetic or demo, or a route mixes staging and
+  production. Ask which environment the analysis should use.
+
+An analysis of seeded data proves the pipeline works and says nothing about
+real costs.
+
+## 4. Check readiness of the chosen workload
+
+`metergraph_get_workload_readiness` with the selection reference and the
+chosen environment. Report `blocking_reasons`, the counts and the
+`retained_window` in one or two lines. An analysis needs at least **10
+samples**. Below that it completes with `no_eligible_workloads`; the fix is
+more traffic, not a rerun. `stale_checkpoint` means the classification is
+older than the current window.
+
+## 5. When nothing is classified yet
+
+An empty list with `classification_pending` or `no_traces` means classification
+has not run. No agent tool starts classification on its own. Tell the person:
+
+1. Open the **Opportunities** page in the Metergraph app and choose **Find
+   opportunities**.
+2. Choose to pick a specific workload rather than the automatic option. That
+   run classifies the traffic and then waits for them to choose a workload,
+   before any candidate model is called.
+3. The automatic option classifies and then immediately analyzes the largest
+   workloads with the saved candidate models, which sends captured prompts to
+   those providers and spends money. Point this out before they click.
+
+When they are back, list classified workloads again and continue. Do not click
+through the app yourself unless the person asks you to and has approved what
+the button will do.

package/bin/metergraph.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
+import { handOff, handsOff } from "../src/approval-handoff.js";
 import { main } from "../src/cli.js";
 
 // A closed pipe on stdout (for example "metergraph --help | head -1") is not
 // a CLI failure.
 process.stdout.on("error", () => {});
 
-process.exitCode = await main(process.argv.slice(2), {
-  stdout: process.stdout,
-  stderr: process.stderr,
-});
+const argv = process.argv.slice(2);
+const io = { stdout: process.stdout, stderr: process.stderr };
+process.exitCode = handsOff(argv) ? await handOff(argv, io) : await main(argv, io);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metergraph-cli",
-  "version": "0.2.0-preview.4",
+  "version": "0.2.0-preview.6",
   "description": "Preview Metergraph command line tool with a read-only connection probe, a project skill installer, Metadata-only sign in and bounded workspace Metadata reads",
   "type": "module",
   "bin": {
@@ -14,6 +14,8 @@
     "src/*.js",
     "assets/skill/SKILL.md",
     "assets/skill/manifest.json",
+    "assets/skills/manifest.json",
+    "assets/skills/*/SKILL.md",
     "LICENSE",
     "README.md"
   ],

package/src/approval-handoff.js

@@ -0,0 +1,91 @@
+import childProcess from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+import { parseArgs } from "./args.js";
+import { envelope, toJsonLine } from "./output.js";
+
+// login and setup with --json --no-browser may need a person to approve in a
+// browser. The approval returns to a loopback listener, so something must
+// keep listening after the agent has the URL. Agent shells usually show a
+// command's output only after it exits, so that cannot be this process.
+//
+// This process runs the same command as a detached waiter and relays the
+// waiter's one JSON line. When the line is action_required, it exits with it
+// at once and leaves the waiter listening until approval or --timeout-ms; the
+// waiter saves what the approval completes and prints nothing more. Any other
+// line is the command's result, and this process waits for the waiter to
+// finish. The arguments carry no credential, and the waiter's environment is
+// this one plus a marker.
+const BIN = fileURLToPath(new URL("../bin/metergraph.js", import.meta.url));
+const WAITER = "METERGRAPH_APPROVAL_WAITER";
+
+export function handsOff(argv, env = process.env) {
+  if (env[WAITER] === "1") return false;
+  const parsed = parseArgs(argv);
+  return parsed.ok && (parsed.command === "login" || parsed.command === "setup") && parsed.json && parsed.noBrowser;
+}
+
+export function handOff(argv, { stdout }) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = childProcess.spawn(process.execPath, [...process.execArgv, BIN, ...argv], {
+        env: { ...process.env, [WAITER]: "1" },
+        stdio: ["ignore", "pipe", "ignore"],
+        detached: true,
+        windowsHide: true,
+      });
+    } catch {
+      resolve(failed(argv, stdout));
+      return;
+    }
+    let text = "";
+    let settled = false;
+    // Ctrl+C before the line arrives cancels the waiter, which reports it.
+    const forward = (signal) => child.kill(signal);
+    const signals = ["SIGINT", "SIGTERM"];
+    for (const signal of signals) process.on(signal, forward);
+    const finish = (code) => {
+      if (settled) return;
+      settled = true;
+      for (const signal of signals) process.removeListener(signal, forward);
+      resolve(code);
+    };
+    child.once("error", () => finish(failed(argv, stdout)));
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      if (settled) return;
+      text += chunk;
+      const end = text.indexOf("\n");
+      if (end === -1) return;
+      let line;
+      try { line = JSON.parse(text.slice(0, end)); } catch { line = null; }
+      if (line?.outcome !== "action_required") return;
+      stdout.write(text.slice(0, end + 1));
+      child.stdout.destroy();
+      child.unref();
+      finish(line.exit_code);
+    });
+    child.once("close", (code) => {
+      if (settled) return;
+      if (text.endsWith("\n") && text.indexOf("\n") === text.length - 1) {
+        stdout.write(text);
+        finish(code ?? 1);
+      } else {
+        finish(failed(argv, stdout));
+      }
+    });
+  });
+}
+
+function failed(argv, stdout) {
+  const parsed = parseArgs(argv);
+  const result = envelope({
+    command: parsed.command ?? null,
+    outcome: "internal_error",
+    reason: "unexpected_failure",
+    message: "The CLI failed unexpectedly. No details are shown to avoid exposing sensitive input.",
+  });
+  stdout.write(toJsonLine(result));
+  return result.exit_code;
+}

package/src/args.js

@@ -26,13 +26,15 @@ import { parseOrigin } from "./origin.js";
 import { isCursor, isSafeFilter } from "./read-contract.js";
 
 export const READ_COMMANDS = Object.freeze(["status", "context", "capabilities", "usage", "routes", "traces"]);
-const COMMANDS = new Set(["doctor", "help", "skill", "login", "logout", "setup", "verify", ...READ_COMMANDS]);
-const HELP_TOPICS = new Set(["doctor", "skill", "login", "logout", "setup", "verify", ...READ_COMMANDS]);
+const COMMANDS = new Set(["doctor", "help", "skill", "skills", "login", "logout", "setup", "verify", ...READ_COMMANDS]);
+const HELP_TOPICS = new Set(["doctor", "skill", "skills", "login", "logout", "setup", "verify", ...READ_COMMANDS]);
 const SKILL_ACTIONS = new Set(["install", "update"]);
+const SKILLS_ACTIONS = new Set(["install", "update", "list"]);
 const READ_BASE = ["--project", "--config-dir", "--timeout-ms"];
 const OPTIONS = {
   doctor: new Set(["--url", "--timeout-ms"]),
   skill: new Set(["--client", "--runtime", "--project"]),
+  skills: new Set(["--client", "--runtime", "--project"]),
   login: new Set(["--runtime", "--url", "--workspace", "--project", "--config-dir", "--timeout-ms"]),
   setup: new Set(["--runtime", "--url", "--workspace", "--project", "--config-dir", "--env-file", "--client", "--timeout-ms", "--deployment", "--agent-token-file", "--repository"]),
   logout: new Set(["--project", "--config-dir"]),
@@ -86,6 +88,8 @@ const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 //   { ok: true, command: "version", json }
 //   { ok: true, command: "doctor", origin, timeoutMs, json }
 //   { ok: true, command: "skill", action, client, runtime, project, json }
+//   { ok: true, command: "skills", action, client, runtime, project, json }
+//     (client and runtime are null for list)
 //   { ok: true, command: "login", runtime, origin, workspace, project,
 //     configDir, timeoutMs, signup, noBrowser, reconnect, json }
 //   { ok: true, command: "logout", project, configDir, json }
@@ -113,7 +117,9 @@ export function parseArgs(argv) {
 
   const fail = (code, message, outcome = "invalid_input") => ({
     ok: false,
-    command: command === "skill" && action !== null ? `skill ${action}` : command ?? (version ? "version" : null),
+    command: (command === "skill" || command === "skills") && action !== null
+      ? `${command} ${action}`
+      : command ?? (version ? "version" : null),
     json,
     code,
     message,
@@ -142,6 +148,10 @@ export function parseArgs(argv) {
       action = arg;
       continue;
     }
+    if (command === "skills" && action === null && SKILLS_ACTIONS.has(arg)) {
+      action = arg;
+      continue;
+    }
 
     if (READ_COMMANDS.includes(command)) {
       const equals = arg.indexOf("=");
@@ -192,6 +202,12 @@ export function parseArgs(argv) {
         `Unknown skill subcommand at argument ${position}. Use install or update.`,
       );
     }
+    if (command === "skills" && action === null && !arg.startsWith("-")) {
+      return fail(
+        "unknown_subcommand",
+        `Unknown skills subcommand at argument ${position}. Use install, update or list.`,
+      );
+    }
     return fail(
       "unknown_argument",
       `Unrecognized argument at position ${position}. Run "metergraph --help" for usage.`,
@@ -203,6 +219,7 @@ export function parseArgs(argv) {
     return { ok: true, command: "help", topic, json };
   }
   if (command === "skill") return parseSkill(action, values, json, fail);
+  if (command === "skills") return parseSkills(action, values, json, fail);
   if (command === "login") return parseLogin(values, flags, json, fail);
   if (command === "setup") return parseSetup(values, flags, json, fail);
   if (command === "verify") return parseVerify(values, flags, json, fail);
@@ -262,9 +279,10 @@ function parseVerify(values, flags, json, fail) {
     open: flags.has("--open"), noBrowser: flags.has("--no-browser"), json };
 }
 
-// Client and runtime are required, so a script states where the skill is
-// used instead of the CLI guessing. Values for clients and runtimes that
-// cannot use project skill files are accepted here and handed off later.
+// The client is required, so a script states which client loads the skill.
+// The runtime defaults to local, the runtime setup installs the skill for;
+// pass --runtime cloud for a cloud checkout. Values for clients and runtimes
+// that cannot use project skill files are accepted here and handed off later.
 function parseSkill(action, values, json, fail) {
   if (action === null) {
     return fail(
@@ -279,10 +297,7 @@ function parseSkill(action, values, json, fail) {
   if (!Object.hasOwn(SKILL_CLIENTS, client) && !Object.hasOwn(HANDOFF_SKILL_CLIENTS, client)) {
     return fail("invalid_client", "--client must be codex, claude or cursor.");
   }
-  const runtime = values["--runtime"];
-  if (runtime === undefined) {
-    return fail("missing_runtime", "--runtime is required. Use local or cloud.");
-  }
+  const runtime = values["--runtime"] ?? "local";
   if (!SKILL_RUNTIMES.includes(runtime) && !HANDOFF_SKILL_RUNTIMES.includes(runtime)) {
     return fail("invalid_runtime", "--runtime must be local or cloud.");
   }
@@ -293,6 +308,29 @@ function parseSkill(action, values, json, fail) {
   return { ok: true, command: "skill", action, client, runtime, project: project ?? null, json };
 }
 
+// skills install and update take the same options as skill. list is read
+// only and takes just --project.
+function parseSkills(action, values, json, fail) {
+  if (action === null) {
+    return fail(
+      "missing_subcommand",
+      'skills requires a subcommand: install, update or list. Run "metergraph help skills" for usage.',
+    );
+  }
+  if (action === "list") {
+    if (values["--client"] !== undefined || values["--runtime"] !== undefined) {
+      return fail("unexpected_option", "skills list takes only --project. It reports every client.");
+    }
+    const project = values["--project"];
+    if (project !== undefined && (project === "" || project.includes("\0"))) {
+      return fail("invalid_project", "--project must name an existing directory.");
+    }
+    return { ok: true, command: "skills", action, client: null, runtime: null, project: project ?? null, json };
+  }
+  const parsed = parseSkill(action, values, json, fail);
+  return parsed.ok ? { ...parsed, command: "skills" } : parsed;
+}
+
 const INVALID_URL =
   "--url must be a bare https origin such as https://metergraph.example.com, " +
   "or an http origin on localhost, 127.0.0.1 or [::1]. " +
@@ -402,7 +440,8 @@ function parseSetup(values, flags, json, fail) {
     parseTimeout(rawTimeout, LOGIN_MIN_TIMEOUT_MS, LOGIN_MAX_TIMEOUT_MS);
   if (timeoutMs === null) return fail("invalid_timeout", `--timeout-ms must be a whole number from ${LOGIN_MIN_TIMEOUT_MS} to ${LOGIN_MAX_TIMEOUT_MS}.`);
   return { ok: true, command: "setup", runtime, origin, originExplicit: values["--url"] !== undefined,
-    deployment, confirmPrerequisites: flags.has("--confirm-prerequisites"), agentTokenFile,
+    deployment, deploymentExplicit: values["--deployment"] !== undefined,
+    confirmPrerequisites: flags.has("--confirm-prerequisites"), agentTokenFile,
     workspace: rawWorkspace === undefined ? null : rawWorkspace.toLowerCase(),
     project: paths.project, configDir: paths.configDir, envFile, client, skipSkill: flags.has("--skip-skill"),
     timeoutMs, noBrowser: flags.has("--no-browser"), repair: flags.has("--repair"),