metergraph-cli 0.2.0-preview.3 → 0.2.0-preview.5

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

@@ -0,0 +1,73 @@
+---
+name: metergraph-iterate
+description: Refine and rerun a Metergraph model-swap analysis after the person has inspected the report in the app - turn their findings into a specific change (eval revision, cases, candidates, traffic or route settings), start a new approved run linked to the previous one, and compare the two honestly. Use when someone returns with "the grader is wrong on these cases", "drop that model", "rerun it", "what changed since last run", or stage 6 of the metergraph-model-swap loop.
+---
+
+# Refine and rerun
+
+A rerun is a new run with one deliberate change. The earlier run, report and
+eval revision stay as they are.
+
+## 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. Recover where the loop is
+
+1. Read the loop record (in the conversation or `.metergraph/model-swap.md`). If
+   there is none, `metergraph_list_analysis_runs` and `metergraph_get_report`
+   on the latest run for this workload, and rebuild it.
+2. Confirm the workload's `selection_reference` still exists with
+   `metergraph_list_classified_workloads`. A newer classification may have
+   replaced it; say so and pick the matching workload by its traces, not by its
+   name alone.
+
+## 2. Turn the finding into one change
+
+Ask what the person saw in the app, then map it:
+
+| Finding | Change | Skill |
+| --- | --- | --- |
+| A grade is wrong on some cases | Fix the check or rubric criterion; save a new eval revision; add the cases as reference cases | `metergraph-evals` |
+| The bar is missing something important | Add a check or criterion, test it on the preview, save a new revision | `metergraph-evals` |
+| A candidate is clearly out, or one is missing | Change candidate selection on the Opportunities page | `metergraph-candidates` |
+| Too few samples, or `insufficient_samples` | More production traffic for this workload, then rerun | `metergraph-workloads` |
+| Traces were skipped | Replay opt-out or residency on a route; the person changes it in the app | `metergraph-candidates` |
+| The winner looks right | No rerun. Plan the code change and a canary instead | — |
+
+Change one thing per rerun when you can, so the comparison means something.
+If several must change, list them all in the confirmation.
+
+## 3. Rerun only with a new yes
+
+A rerun spends money and sends captured prompts to providers again. Get the
+same explicit confirmation as the first run (see `metergraph-analyze`), plus
+what changed. If the request already names the change and approves a budget and
+time, that is the confirmation: restate it, make the change (for an eval fix,
+save the new revision first, as in `metergraph-evals`), then start. Then call `metergraph_start_analysis` with:
+
+- a **new** `request_key`, for example `rerun-<pattern_id>-<yyyymmdd>-<n>`;
+- the same `pinned_workload`, unless the workload itself changed;
+- `rerun_of_run_id` set to the previous run ID;
+- `reference_binding_id` when reference cases were bound.
+
+Poll and read the report as in `metergraph-analyze` and `metergraph-report`.
+
+## 4. Compare honestly
+
+Show the two runs side by side only for what is comparable:
+
+```
+            run <a> (<date>)        run <b> (<date>)
+eval        <revision a>            <revision b>
+samples     <n>                     <n>
+<candidate> <grade, cost ratio>     <grade, cost ratio>
+```
+
+If the eval revision, the sample or the candidate set changed, say that a
+different grade may come from the change, not from the model. Then give the
+decision line from `metergraph-report` with the new report link, and update the
+loop record.

package/assets/skills/metergraph-model-swap/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: metergraph-model-swap
+description: Run the Metergraph model-swap loop from a coding agent - choose a workload, choose traces and candidate models, define or refine the eval, start the analysis, summarize the report with its app link, then refine and rerun. Use when someone asks whether a workload could use a cheaper or better model, asks to plan or run a model swap analysis, asks "what should my largest workload run on", or comes back after inspecting a Metergraph report. Use the metergraph skill first when Metergraph is not connected.
+---
+
+# Model-swap loop
+
+This skill is the map. Each stage has its own skill; load it when you reach the
+stage. The person stays in the coding agent for choosing, defining and
+rerunning, and goes to the Metergraph app to read the detailed report and
+inspect evidence.
+
+```
+choose workload → choose traces and models → define or refine eval
+      → run analysis → summary + report link → (person inspects evidence in the app)
+      → refine and rerun ↺
+```
+
+| Stage | Skill | Ends with |
+| --- | --- | --- |
+| 1. Choose workload | `metergraph-workloads` | One classified workload, with its `selection_reference` and why it was picked |
+| 2. Choose traces and models | `metergraph-candidates` | A run plan: environment, window, candidate models, route settings that must change |
+| 3. Define or refine the eval | `metergraph-evals` | A saved eval revision bound to the workload, or a written rubric the person enters in the app |
+| 4. Run the analysis | `metergraph-analyze` | A run ID, polled to a final state |
+| 5. Summarize | `metergraph-report` | A short summary and the report link |
+| 6. Refine and rerun | `metergraph-iterate` | What changed and a new, separately approved run |
+
+## Start every session the same way
+
+1. Call `metergraph_get_workspace_context`, then `metergraph_get_capabilities`.
+   Say which workspace and deployment you are connected to in one line. Stop if
+   it is not the one the person means.
+2. Call `metergraph_list_analysis_runs` with a small limit. If a run already
+   exists for this workload, the person is probably on stage 6: read its report
+   first instead of starting over, and give the report link
+   (`<origin>/#analysis?report=<analysis_id>`, as in `metergraph-report`).
+3. Write down the tools that are advertised. Plan only with those. When a stage
+   needs a tool that is not advertised, say which one, keep the selection you
+   have, and hand that step to the app page named in the stage skill. Never
+   invent a tool, call a dashboard API with an agent key, or drive the app in a
+   browser unless the person asks for that specific change.
+
+## Rules that hold across stages
+
+- **Workloads are not routes.** Routes are labels on traffic. An analysis runs
+  on a classified workload, identified by `source_run_id`, `pattern_id` and
+  `pattern_set_version`. Do not rank or plan on routes and then discover this at
+  the start step.
+- **Check the data before planning.** A workspace created today, data that all
+  arrived in one batch, fewer than 10 samples, or totals that disagree between
+  tools and the app all change the plan. Say so first, with the numbers.
+- **One decision at a time.** End each turn with the single decision you need
+  from the person, not a list of everything that could be configured.
+- **Spending and data egress need a yes.** Starting an analysis sends copies of
+  captured prompts to other model providers and costs money. Stage 4 has the
+  exact confirmation to get. A connected key, a configured provider key or an
+  earlier yes for a different run is not approval.
+- **Settings are the person's.** Replay opt-out, data residency, candidate
+  models, cost and latency limits and the size floor are changed in the app.
+  Explain the change and give the page; do not make it for them.
+- **Keep answers short.** Lead with the answer or the blocker. Tables only for
+  three or more rows. Give confidence once, where it matters.
+
+## Keep a loop record
+
+Keep these values in the conversation, and, if you can write files in the
+person's project and they agree, in `.metergraph/model-swap.md`. They are not
+secret. They let a later session pick up at stage 6.
+
+```
+workspace: <name> (<workspace_id>) at <origin>
+workload: <display_name>  source_run_id=<…> pattern_id=<…> pattern_set_version=<…>
+environment: <production|…>  window: <from>–<to>
+candidates: <model ids>
+eval: <suite or rubric revision id, or "rubric in chat, not saved">
+runs: <run_id> (<status>) → report <analysis_id> <link>
+decision: <switch | no switch | more testing> because <reason>
+next: <the one next step>
+```
+
+Never put keys, `.env` values or captured prompt or response text in it.

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

@@ -0,0 +1,155 @@
+---
+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 the released bundle and 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metergraph-cli",
-  "version": "0.2.0-preview.3",
+  "version": "0.2.0-preview.5",
   "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/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);
@@ -293,6 +310,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]. " +

package/src/cli.js

@@ -10,12 +10,13 @@ import {
   helpData,
   helpText,
   skillText,
+  skillsText,
   toJsonLine,
   versionData,
 } from "./output.js";
 import { runRead } from "./read.js";
 import { readMessage, readText } from "./read-output.js";
-import { runSkill } from "./skill.js";
+import { listSkillPack, runSkill, runSkillPack } from "./skill.js";
 import { runSetup } from "./setup.js";
 import { containsKnownCredential, preflightNonHostedSetup } from "./setup-deployment.js";
 import { VERSION } from "./constants.js";
@@ -151,6 +152,20 @@ async function run(argv, { stdout, stderr }) {
     return result;
   }
 
+  if (parsed.command === "skills") {
+    const { outcome, reason, message, data } =
+      parsed.action === "list" ? listSkillPack(parsed) : runSkillPack(parsed);
+    const result = envelope({
+      command: `skills ${parsed.action}`,
+      outcome,
+      reason,
+      data,
+      message: outcome === "ok" ? null : message,
+    });
+    stdout.write(parsed.json ? toJsonLine(result) : skillsText(result, message));
+    return result;
+  }
+
   const { outcome, reason, report } = await runDoctor({
     origin: parsed.origin,
     timeoutMs: parsed.timeoutMs,