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

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

@@ -0,0 +1,105 @@
+---
+name: metergraph-investigate
+description: Investigate a failed or anomalous LLM trace, usage spike or incident through an already connected Metergraph Agent Access server, answering only from bounded, cited evidence. Use after setup is verified; use the metergraph skill first when not connected.
+---
+
+# Investigate with Metergraph evidence
+
+This skill expands the bounded investigation section of the public `metergraph`
+skill. It adds no tools, scopes or authority. When no Metergraph MCP server is
+connected, or the user has not chosen a client, runtime and deployment, stop and
+use the `metergraph` skill for setup routing. Never ask for, echo or store a
+key.
+
+## 1. Discover before reading data
+
+1. Call `metergraph_get_workspace_context`, then `metergraph_get_capabilities`.
+   Do not call any other Metergraph tool first.
+2. Confirm with the user that `provenance.workspace_id`, the workspace name and
+   `provenance.deployment_profile` match the installation they intend. A staging
+   or demo workspace is not their production workspace. Stop on a mismatch,
+   an authorization error, or revoked or expired access, and tell the human to
+   reconnect through their client's secure flow.
+3. Build the tool plan only from what the server returns: the workspace
+   context's `access.scopes`, and each capability under the capabilities
+   response's `agent` object with its `available`, `privacy_class` (metadata,
+   content or replay), `required_scope`, `mutates` and `external_calls`, plus
+   `bounds` (`max_days`, `max_rows`). Treat the tools your client lists as the
+   only callable tools. A tool or capability that is absent, or has
+   `available: false`, is a blocker to report, not something to
+   guess, retry under another name or replace with a dashboard API, generic SQL
+   or a shell command. Some deployments are content-blind or have no replay,
+   incidents, ingestion health or reports.
+
+## 2. Fix the question and the bound
+
+Restate the question, the route or workload if known, and an explicit window in
+whole days (tools accept `days` from 1 to 90; default to the shortest window
+that answers the question). Then choose the smallest tool that can answer:
+
+| Question | First tool | Bound |
+| --- | --- | --- |
+| How much, how many, which route costs most | `metergraph_get_usage` | `days`, small `limit` |
+| Which routes exist or are replay eligible | `metergraph_list_routes` | none needed |
+| Is data arriving | `metergraph_get_ingestion_health` | `days` |
+| Known alert or anomaly | `metergraph_list_incidents` | small `limit` |
+| One failed, slow or costly call | `metergraph_query_traces` with `status`, `route`, `trace_id` or `request_id` | `limit` 1 to 5 |
+| A finished analysis | `metergraph_list_reports`, then `metergraph_get_report` | small `limit` |
+
+Follow `next_cursor` only while you are still inside the agreed bound, and say
+how many pages you read. Never request every trace, every report or unbounded
+history.
+
+## 3. Escalate privacy classes one step at a time
+
+- Metadata tools answer most questions. Stay there unless the answer needs
+  captured prompts, outputs, tool calls or report evidence.
+- `metergraph_get_trace` and `metergraph_get_report_evidence` return captured
+  content (`agent:read`). Ask the user before calling them, name the single trace
+  or workload you will read, and do not quote more captured content than the
+  answer needs. Never paste secrets you find in content.
+- `metergraph_replay_trace` (`agent:replay`) sends a captured trace to a model
+  provider and can spend money. It needs separate, explicit approval that names
+  the trace, the overrides and the timeout. Replay is non-persistent: it does not
+  change production telemetry, prove a fix or substitute for an evaluation run.
+
+Read access never grants evaluation writes, analysis launch, dashboard changes,
+key rotation or production configuration changes. Refuse those requests and
+point to the human action in the Metergraph app instead.
+
+## 4. Answer only from returned evidence
+
+Every answer cites, from the tool responses you actually received:
+
+- **Workspace**: workspace name and `provenance.workspace_id`, plus
+  `deployment_profile`.
+- **Window**: `window.since` to `window.until` (or `days`) for each read.
+- **Provenance**: the tool name, `provenance.source` and `generated_at`.
+- **Evidence and completeness**: `evidence.rows`, `evidence.complete`,
+  `page.truncated` and whether a `next_cursor` was left unread.
+- **Warnings**: every returned `warnings[].code` with its message. Say "no
+  warnings returned" when the list is empty.
+- **Identifiers and links**: trace, request, incident or analysis IDs, and
+  `metergraph_links` values exactly as returned. Never construct a link.
+
+Keep these states distinct and name the one that applies: no data in the
+window, incomplete or truncated evidence, capability unavailable in this
+deployment, classification pending, ambiguous request match
+(`request_match.ambiguous`), failed analysis, and missing report. An empty page
+does not prove there was no traffic; check ingestion health or a longer bounded
+window before saying so. Do not round, extrapolate or invent totals.
+
+## 5. Worked workflow: one failed trace
+
+1. Discover: context, then capabilities. Confirm the workspace with the user.
+2. Find: `metergraph_query_traces` with `status` set to the failure status, the
+   agreed `days` and `limit` 1. If the user gave a request ID and the match is
+   ambiguous, list the candidates and ask which one.
+3. Explain from metadata: route, model, provider, tokens, cost, latency, status
+   and span count, with the citations above. If metadata is enough, stop here.
+4. Optional content: with consent, `metergraph_get_trace` for that one trace to
+   read the error, tool calls and root-cause classification.
+5. Optional replay: only with explicit approval and when the trace is replay
+   eligible, run one bounded `metergraph_replay_trace`, report the returned
+   status and comparison, and state that nothing in production changed.
+6. Close with what is known, what is unknown, and the next bounded check.

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-local-bundle/SKILL.md

@@ -0,0 +1,283 @@
+---
+name: metergraph-local-bundle
+description: Verify and start the signed Metergraph customer-local bundle on a person's own machine, preserve existing local data and secrets, then hand over to metergraph setup. Use when customer-local setup reports that the bundle_started_verified prerequisite is incomplete or when installing the commercial local bundle from a public release.
+---
+
+# Start the signed customer-local bundle
+
+Stand up the released bundle only on the person's own machine, then run
+`metergraph setup`. The CLI does not provision it, and
+`--confirm-prerequisites` records confirmation rather than installing anything.
+
+Keep registry, admin and database secrets out of chat, command arguments and
+output. Never read or print `.env` values, `~/.docker/config.json`,
+`docker compose config` output or container environment from `docker inspect`.
+Do not configure model-provider keys.
+
+## Stop in remote runtimes
+
+Before changing anything, determine where the agent executes. Check only
+whether these variables exist, never their values:
+
+```sh
+for name in SSH_CONNECTION SSH_CLIENT SSH_TTY CODESPACES GITPOD_WORKSPACE_ID CLOUD_SHELL CI; do
+  if printenv "$name" >/dev/null 2>&1; then printf '%s is set\n' "$name"; fi
+done
+```
+
+If any is set, or this is otherwise a hosted/cloud runtime, download, verify,
+extract and start nothing. Prefer an installed `metergraph` whose `--help`
+lists `setup`; otherwise state that the fallback fetches the preview CLI and
+use `npx --yes metergraph-cli@next` as the prefix. Run only:
+
+```sh
+metergraph setup --runtime cloud --deployment customer-local --url http://localhost:8080 --workspace 11111111-1111-4111-8111-111111111111 --skip-skill --json
+```
+
+Relay its `data.next_action.kind: "run_on_customer_machine"` handoff and tell
+the person to run this skill on their own machine. The placeholder workspace is
+intentional: the runtime check refuses before making a request or writing a
+file. When an SSH, cloud or CI marker is set, even `--runtime local` is refused
+with reason `run_on_local_machine` and the same handoff. Valid runtimes are
+`local`, `cloud` and `cloud-no-shell`. Never expose localhost to the remote
+session.
+
+## Preflight and reuse
+
+Ask for the coding client and bundle version. Default to the newest version at
+https://www.metergraph.dev/docs/releases/ and record its `v`-prefixed value.
+Record the application repository directory to return to for setup. Run:
+
+```sh
+docker info >/dev/null
+docker compose version
+cosign version
+curl -fsS http://localhost:8080/v1/deployment
+lsof -nP -iTCP:8080 -sTCP:LISTEN
+```
+
+Docker with Compose must be running and `cosign` installed. If the deployment
+endpoint returns the `local` profile, reuse that stack and download nothing.
+Find its bundle directory using only the Compose working-directory label:
+
+```sh
+container_id="$(docker ps --filter publish=8080 --format '{{.ID}}' | head -n 1)"
+bundle_dir="$(docker inspect --format '{{ index .Config.Labels "com.docker.compose.project.working_dir" }}' "$container_id")"
+(cd "$bundle_dir" && ./bin/status)
+```
+
+Do not inspect container environment. Read the workspace ID from the
+`workspace` check and skip to **Run setup**. If the directory cannot be found,
+ask for the workspace ID from Settings. If nothing listens on 8080, continue.
+If anything else owns it, stop and ask; never stop or reconfigure it.
+
+Use `~/metergraph/<version>` and set
+`bundle_dir="$HOME/metergraph/$version/local"`. If it contains `.env`, reuse
+that existing installation: never overwrite, delete or read the file, and
+never extract over `local/`. Continue at **Log in and start**. Otherwise check:
+
+```sh
+docker volume inspect local_pgdata >/dev/null 2>&1
+```
+
+Because the extracted directory and Compose project are `local`, an existing
+volume is `local_pgdata`. If it exists without the matching `local/.env`, stop
+and ask for the prior bundle/configuration. Postgres fixed its password when
+the volume was created; a new `.env` can cause `password authentication failed`.
+Never remove the volume, delete `.env` or use `down --volumes`.
+
+## Download and verify
+
+Require a fresh, empty version directory. Before creating it, tell the person
+the directory and four public files that will be written. No account is needed.
+Set `version` to the recorded version and run:
+
+```sh
+release_dir="$HOME/metergraph/$version"; mkdir -p "$release_dir"; cd "$release_dir"
+archive="metergraph-customer-local-$version.tar.gz"
+base="https://www.metergraph.dev/releases/$version"
+curl -fsSLO "$base/$archive"
+curl -fsSLO "$base/metergraph-byoc-release.json"
+curl -fsSLO "$base/metergraph-byoc-release.json.sig"
+curl -fsSLO "$base/metergraph-byoc-release.json.pem"
+```
+
+Do not list, extract or run archive contents. Verify the manifest signature
+with exactly this command. The issuer and identity are pinned here, not read
+from the release page, so a changed download site cannot change who must have
+signed the release:
+
+```sh
+cosign verify-blob \
+  --certificate metergraph-byoc-release.json.pem \
+  --signature metergraph-byoc-release.json.sig \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+  --certificate-identity-regexp '^https://github\.com/PioneerSquareLabs/metergraph-internal/\.github/workflows/byoc-release\.yml@refs/(heads/main|tags/v.+)$' \
+  metergraph-byoc-release.json
+```
+
+Never loosen or drop the issuer or identity, and never add
+`--insecure-ignore-tlog` or a similar bypass. If the release page publishes a
+different identity, stop and tell the person rather than using it.
+
+If cosign fails, stop: "The manifest signature did not verify. Do not extract
+or run this bundle." After it succeeds, check signed fields:
+
+```sh
+python3 - "$version" "$archive" <<'EOF'
+import json, sys
+version, archive = sys.argv[1:]
+m = json.load(open("metergraph-byoc-release.json"))
+required = ("release", "local_bundle", "local_bundle_sha256",
+            "local_image_digest", "local_analysis_image_digest")
+missing = [key for key in required if not m.get(key)]
+if missing: sys.exit("Signed manifest is missing: " + ", ".join(missing))
+if m["release"] != version: sys.exit("Signed manifest release mismatch. Do not run it.")
+if m["local_bundle"] != archive: sys.exit("Signed archive name mismatch. Do not run it.")
+print("Signed manifest release, archive, and image digests are present.")
+EOF
+```
+
+Then run this digest check, still before any `tar` command:
+
+```sh
+python3 - <<'EOF'
+import hashlib, json, sys
+manifest = json.load(open("metergraph-byoc-release.json"))
+name = manifest["local_bundle"]
+actual = hashlib.sha256(open(name, "rb").read()).hexdigest()
+if actual != manifest["local_bundle_sha256"]:
+    sys.exit(f"{name} does not match the signed manifest. Do not run it.")
+print(f"{name} matches the signed manifest.")
+EOF
+```
+
+Stop on failure. After both checks pass, list and validate archive paths:
+
+```sh
+tar -tzf "$archive"
+python3 - "$archive" <<'EOF'
+from pathlib import PurePosixPath
+import sys, tarfile
+bad = []
+with tarfile.open(sys.argv[1], "r:gz") as bundle:
+    for member in bundle.getmembers():
+        path = PurePosixPath(member.name)
+        if path.is_absolute() or not path.parts or path.parts[0] != "local" or ".." in path.parts:
+            bad.append(member.name)
+if bad: sys.exit("Unsafe archive paths; do not extract: " + ", ".join(bad[:10]))
+print("Every archive entry is beneath local/ with a safe relative path.")
+EOF
+```
+
+Only now tell the person extraction will create `local/`, then run:
+
+```sh
+tar xzf "$archive"
+mv metergraph-byoc-release.json* local/
+cd local
+```
+
+## Configure without exposing passwords
+
+Reuse an existing `.env` unchanged. For a new installation, state that a
+mode-0600 file with random admin/database passwords and empty provider keys
+will be created. Confirm `local_pgdata` did not exist, then run:
+
+```sh
+umask 077; cp .env.example .env; chmod 600 .env
+python3 - <<'EOF'
+from pathlib import Path
+import secrets
+path = Path(".env")
+keys = ("METERGRAPH_LOCAL_ADMIN_PASSWORD", "METERGRAPH_DB_PASSWORD")
+values = {key: secrets.token_urlsafe(24) for key in keys}
+lines, found = path.read_text().splitlines(), set()
+for i, line in enumerate(lines):
+    for key in keys:
+        if line.startswith(key + "="):
+            lines[i], found = key + "=" + values[key], found | {key}
+if found != set(keys): raise SystemExit("Password keys missing from .env.example")
+path.write_text("\n".join(lines) + "\n")
+print("Set random values for: " + ", ".join(keys))
+EOF
+```
+
+Do not display, source or parse `.env`. Leave `AI_GATEWAY_API_KEY`,
+`FIREWORKS_API_KEY`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` and `GOOGLE_API_KEY`
+empty.
+
+## Log in and start
+
+Stop for the person to log in to the registry in their own terminal. They use
+the pull-only invitation values, never chat or an agent-visible command:
+
+```sh
+echo "$METERGRAPH_PULL_TOKEN" | docker login ghcr.io -u "$METERGRAPH_PULL_USER" --password-stdin
+```
+
+Wait for confirmation only; never read Docker's credential file. State that
+`./bin/start` will re-verify the manifest and both image digests, pull by digest,
+start containers, and on a new database send one synthetic demo trace labeled
+`environment=local-demo`. Then run:
+
+```sh
+./bin/start
+./bin/status
+```
+
+An image-pull failure usually means login is missing or expired. On other
+failure, read only the log named by `./bin/start` and `./bin/status`; never read
+rendered Compose configuration or container environment. On password
+authentication failure with `local_pgdata`, stop and ask for its matching
+`.env`. Never delete data. Read the workspace ID and suggested command from the
+status JSON's `workspace` check. The service listens only on localhost:8080.
+
+## Run setup
+
+Return to the application repository. Prefer installed `metergraph` only when
+its help lists `setup`; otherwise state that `npx --yes metergraph-cli@next`
+fetches the preview CLI and use it as the prefix. Run with `--json`:
+
+```sh
+metergraph setup --runtime local --deployment customer-local --url http://localhost:8080 --workspace 11111111-1111-4111-8111-111111111111 --confirm-prerequisites --client <client> --json
+```
+
+Replace the example UUID and client only. Setup writes an ingest key to the
+application `.env`, installs the skill and requests Metadata access only; never
+print that file. Setup opens the deployment's browser consent page and waits;
+the person signs in as the local admin and completes two approvals. If the
+browser cannot open, follow the `metergraph` skill's guidance for handing the
+person the approval URL. Continue until `data.status` is `ok`. For
+`operator_handoff`, relay `data.next_action.kind` (`complete_prerequisite`,
+`run_on_customer_machine`, `connection_guide`, or other); never report a
+handoff as success.
+
+The agent never runs a command that reads `.env`. To see the admin login without
+printing it, the person runs these no-output pipelines themselves, one at a
+time, in their own terminal or in Claude Code with the `!` prefix. Fill in the
+absolute bundle directory for them; their shell does not have `bundle_dir`:
+
+```sh
+sed -n 's/^METERGRAPH_LOCAL_ADMIN_EMAIL=//p' ~/metergraph/<version>/local/.env | pbcopy
+sed -n 's/^METERGRAPH_LOCAL_ADMIN_PASSWORD=//p' ~/metergraph/<version>/local/.env | pbcopy
+```
+
+They may instead use their own editor. Never use `cat`, `grep` or any other
+command that prints `.env`, particularly with `!`, because `!` output lands in
+the transcript. A new configuration keeps `admin@example.com` as the email.
+
+## Recovery and stopping
+
+| State | Action |
+| --- | --- |
+| Signature, manifest, digest or path check fails | Stop; extract and run nothing |
+| Port 8080 belongs to something else | Stop and ask; do not alter it |
+| Registry pull is denied | Person repeats private login; never request the token |
+| Existing `.env` | Reuse unchanged; never regenerate passwords |
+| `local_pgdata` lacks its matching `.env` | Stop and find prior configuration; never remove it |
+| Startup fails | Use status and only the named log; preserve secrets and data |
+| Setup returns a handoff | Relay exact status/next action; do not report success |
+
+To stop later, follow the bundle README's `stop`. Prefer it over `down`, which
+loses raw payloads in local object storage. Never use `down --volumes`.

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.