metergraph-cli 0.2.0-preview.5 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # metergraph-cli
 
-[![npm](https://img.shields.io/npm/v/metergraph-cli/next?label=npm%40next)](https://www.npmjs.com/package/metergraph-cli)
+[![npm](https://img.shields.io/npm/v/metergraph-cli?label=npm)](https://www.npmjs.com/package/metergraph-cli)
 [![CI](https://github.com/metergraph/cli/actions/workflows/ci.yml/badge.svg)](https://github.com/metergraph/cli/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/metergraph/cli/blob/main/LICENSE)
 
@@ -13,11 +13,10 @@ token and route metadata back. Every command has stable `--json` output and exit
 so agents can run it as well as people.
 
 ```sh
-npx --yes metergraph-cli@next --help
+npx --yes metergraph-cli --help
 ```
 
-This is a preview, published on the `next` npm tag. `latest` is still `0.1.0`, which has
-only `doctor` and `skill`. See the [changelog](https://github.com/metergraph/cli/blob/main/CHANGELOG.md).
+Published on npm as `latest`. See the [changelog](https://github.com/metergraph/cli/blob/main/CHANGELOG.md).
 
 ## Quickstart
 
@@ -27,7 +26,7 @@ writes `METERGRAPH_APP_TOKEN` and `METERGRAPH_INGEST_URL` to a private `.env`, a
 installs the skill for your coding agent.
 
 ```sh
-npx --yes metergraph-cli@next setup --runtime local --client claude
+npx --yes metergraph-cli setup --runtime local --client claude
 ```
 
 Use `--client codex` or `--client cursor` for the other agents.
@@ -40,20 +39,20 @@ ID or request ID and when the call started and ended.
 exact trace is visible in your workspace.
 
 ```sh
-npx --yes metergraph-cli@next verify --trace-id TRACE_ID \
+npx --yes metergraph-cli verify --trace-id TRACE_ID \
   --since 2026-01-08T12:00:00Z --until 2026-01-08T12:00:05Z
 ```
 
 Then read what Metergraph has recorded:
 
 ```sh
-npx --yes metergraph-cli@next usage --days 7      # calls, errors, cost and tokens per route per day
-npx --yes metergraph-cli@next traces --limit 20   # one page of trace metadata
+npx --yes metergraph-cli usage --days 7      # calls, errors, cost and tokens per route per day
+npx --yes metergraph-cli traces --limit 20   # one page of trace metadata
 ```
 
-To install it globally instead, run `npm install -g metergraph-cli@next`. The command is
-`metergraph`. Pin an exact version, such as `metergraph-cli@0.2.0-preview.5`, when a
-script must not change with the `next` tag.
+To install it globally instead, run `npm install -g metergraph-cli`. The command is
+`metergraph`. Pin an exact version, such as `metergraph-cli@0.2.0`, when a
+script must not change with the `latest` tag. Previews use the `next` tag.
 
 ## Requirements
 
@@ -80,11 +79,11 @@ The CLI is built to be run by Codex, Claude Code and Cursor as well as by people
   network access:
 
   ```sh
-  npx --yes metergraph-cli@next skill install --client codex --runtime local
+  npx --yes metergraph-cli skill install --client codex
   ```
 
   Python users can run `pip install metergraph-skills` and
-  `metergraph-skills install --client codex --runtime local` instead
+  `metergraph-skills install --client codex` instead
   ([details](https://github.com/metergraph/cli/blob/main/python/metergraph-skills/README.md)).
   Both write the same files and recognise each other's installs.
 - **Model-swap skills.** `skills install` adds the workflow skills from
@@ -94,17 +93,26 @@ The CLI is built to be run by Codex, Claude Code and Cursor as well as by people
   the `metergraph/skills` plugin marketplace instead.
 
   ```sh
-  npx --yes metergraph-cli@next skills install --client claude --runtime local
+  npx --yes metergraph-cli skills install --client claude
   ```
 
+  `--runtime` defaults to `local`. Pass `--runtime cloud` when the client runs in a
+  cloud environment with a checkout of the project.
+
 - **Machine output.** Every command takes `--json` and then prints exactly one JSON
   line on stdout and nothing on stderr. All results share one envelope:
   `schema_version`, `command`, `ok`, `outcome`, `exit_code`, `data` and `error`.
   Failures carry a fixed `error.reason` and, where useful, a `data.next_action` that
   tells the agent what to do next.
 - **No hidden prompts.** No command reads stdin or asks a question. `--no-browser`
-  prints the sign in URL for a person to open instead of launching a browser; with
-  `--json`, a step that needs approval exits 6 with a `run_in_terminal` next action.
+  prints the sign in URL for a person to open instead of launching a browser. With
+  `--json`, a step that needs approval exits within seconds with 18
+  `action_required` and `data.next_action` set to
+  `{"kind": "open_url", "url": "...", "timeout_seconds": N, "message": "..."}`, so an
+  agent can show the URL to the person. A background process waits for the approval
+  until `--timeout-ms`; afterwards, run the same command again to continue from the
+  saved state
+  ([details](https://github.com/metergraph/cli/blob/main/docs/reference.md#approval-from-an-agent)).
 - **MCP.** Workspace tools for agents are served by the hosted MCP endpoint, not by this
   CLI. See the [MCP server guide](https://www.metergraph.dev/docs/guides/mcp-server/)
   and the [agent access guide](https://www.metergraph.dev/docs/guides/agent-access/).
@@ -112,7 +120,7 @@ The CLI is built to be run by Codex, Claude Code and Cursor as well as by people
 Suggested `AGENTS.md` or `CLAUDE.md` lines for a project that uses Metergraph:
 
 ```md
-- Metergraph CLI: `npx --yes metergraph-cli@next <command> --json`. Check exit codes;
+- Metergraph CLI: `npx --yes metergraph-cli <command> --json`. Check exit codes;
   follow `data.next_action` on failure.
 - After changing instrumented code, run the app once and confirm the trace with
   `metergraph verify` before reporting that tracing works.
@@ -141,18 +149,18 @@ writes, and full JSON examples.
 
 ## Exit codes
 
-Exit codes are stable. Changing one is a breaking change. Codes 10 to 17 are not in
+Exit codes are stable. Changing one is a breaking change. Codes 10 to 18 are not in
 `0.1.0`.
 
 | Code | Outcome | Meaning |
 | --- | --- | --- |
-| 0 | `ok` | Command succeeded. `doctor` does not return this in this preview. For `skill`, the file is in place; discovery is still pending. |
+| 0 | `ok` | Command succeeded. `doctor` does not return this in this release. For `skill`, the file is in place; discovery is still pending. |
 | 1 | `internal_error` | Unexpected failure inside the CLI. |
 | 2 | `invalid_input` | Unknown command or argument, or an invalid option value. No request was made. |
 | 3 | `authentication_required` | Service is reachable, healthy and supported, and requires authentication. No workspace is connected. |
 | 4 | `connection_failed` | The origin could not be reached, the connection failed, or the probe timed out. For `verify`, the deadline expired before any valid answer arrived. A trace that is still pending is exit 11, not 4. |
 | 5 | `unhealthy` | The service answered but reported that it is not healthy, or answered with a server error. |
-| 6 | `unsupported` | The service answered with a response, deployment profile or status this CLI does not support, or the skill client or runtime cannot use project skill files, or sign in cannot run in this environment, or `--json --no-browser` needs a browser approval it cannot show (`no_browser_requires_terminal`). Nothing was written. |
+| 6 | `unsupported` | The service answered with a response, deployment profile or status this CLI does not support, or the skill client or runtime cannot use project skill files, or sign in cannot run in this environment. Nothing was written. |
 | 7 | `redirect_rejected` | The service answered with a redirect. Redirects are never followed. |
 | 8 | `conflict` | The skill target is not owned by this CLI, was modified, is unsafe, is locked or needs an explicit update, or the project is bound to a different origin or workspace. Nothing was changed. |
 | 9 | `filesystem_error` | Project or credential files could not be read or written. Partial changes were rolled back unless the message says otherwise. |
@@ -164,6 +172,7 @@ Exit codes are stable. Changing one is a breaking change. Codes 10 to 17 are not
 | 15 | `permission_denied` | The service refused this read for the signed in grant, for example for a missing scope or permission. |
 | 16 | `rate_limited` | The service asked the CLI to slow down. Nothing was retried. Try again later. |
 | 17 | `cancelled` | A read command was interrupted before it finished. Read commands never change workspace configuration or telemetry. |
+| 18 | `action_required` | A person must act before the command can finish; `data.next_action` says what to do. `login` and `setup` with `--json --no-browser` exit with this as soon as an approval URL exists (`next_action.kind: "open_url"`), while a background process waits for the approval until `--timeout-ms`. After approval, run the same command again to continue. |
 
 ## Security and privacy
 
@@ -194,9 +203,11 @@ report. See [SECURITY.md](https://github.com/metergraph/cli/blob/main/SECURITY.m
 
 `--url ORIGIN` selects the service; the default is `https://app.metergraph.dev`. It
 accepts a bare `https://` origin, or `http://` on `localhost`, `127.0.0.1` or `[::1]`.
-`setup --deployment` supports the hosted service (`managed`), the commercial
-`customer-local` bundle, customer-owned cloud (`byoc`) and the open source server
-(`oss`). See [self-hosting](https://www.metergraph.dev/docs/self-host/local/) and the
+`setup --deployment` routes to the hosted service (`managed`), the commercial
+`customer-local` bundle, customer-owned cloud (`byoc`) or the open source server
+(`oss`). The hosted service and released customer-local bundle are the release
+targets; `byoc` and `oss` are not yet verified against a live deployment. See
+[self-hosting](https://www.metergraph.dev/docs/self-host/local/) and the
 [setup reference](https://github.com/metergraph/cli/blob/main/docs/reference.md#setup).
 
 ## Links

package/assets/skill/SKILL.md

@@ -36,6 +36,15 @@ package does not support. A CLI login or health probe alone does not prove
 application traffic. Verification needs an exact trace or request ID from an
 application invocation, its time window and the intended workspace.
 
+`login` and `setup` need the person to approve in a browser on this machine. If the
+installed CLI's help lists exit code 18 `action_required`, run them with
+`--json --no-browser`. When a step needs approval, the command exits 18 within
+seconds. Show `data.next_action.url` to the person and ask them to approve; a
+background process waits for the approval. After they approve, run the same command
+again. A new project takes three runs: sign in, ingest approval, then a final check.
+An older CLI exits 6 `no_browser_requires_terminal` instead. Then the person has to
+run setup in their own terminal.
+
 Repository identity is optional for capture but keeps traces attributable when
 several repositories share a workspace. If the installed CLI's `setup` help lists
 `--repository`, setup records `owner/name` from the git remote in a committed
@@ -68,7 +77,7 @@ For hosted Claude Desktop on an individual account, guide the human through Cust
 
 For a fresh hosted workspace, first ask whether the human already has a Metergraph account and workspace. Direct them to https://app.metergraph.dev/ and the signup, invitation or sign-in flow actually offered. The hosted UI can offer "Get a free API key" for self-service signup, but do not assume that button or a workspace invitation is available to everyone. If access is unavailable, direct them to their workspace owner or Metergraph. Confirm the workspace before creating a coding-agent key.
 
-For the commercial customer-local bundle, direct them to https://www.metergraph.dev/docs/self-host/local/#the-customer-local-bundle and the signed public release. They need a separate pull-only registry credential from Metergraph to pull the images; the public bundle download does not grant registry access. Verify the release before installation. Local admin credentials from the bundle's private configuration provide dashboard sign-in; create a coding-agent key in that installation's Keys page. Do not substitute hosted signup or a hosted key. Do not clone the private implementation or run development seed commands.
+For the commercial customer-local bundle, direct them to https://www.metergraph.dev/docs/self-host/local/#the-customer-local-bundle and the signed public release. They need a separate pull-only registry credential from Metergraph to pull the images; the public bundle download does not grant registry access. Verify the release before installation. Local admin credentials from the bundle's private configuration provide dashboard sign-in; create a coding-agent key in that installation's Keys page. Do not substitute hosted signup or a hosted key. Do not clone the private implementation or run development seed commands. Use `metergraph-local-bundle` to stand the bundle up when that skill is installed.
 
 For customer-owned AWS, direct them to https://www.metergraph.dev/docs/self-host/aws/. An operator provisions the installation, identity and membership. There is no public signup. Ask for the installation's actual reachable address and use a coding-agent key from its Keys page. Its default internal load balancer is private, and its Agent Access surface excludes trace content and replay.
 

package/assets/skill/manifest.json

@@ -3,7 +3,7 @@
   "name": "metergraph",
   "file": "SKILL.md",
   "source_url": "https://www.metergraph.dev/SKILL.md",
-  "sha256": "92f7955f6f8761a20a1886ad81f22dfcee239afddf8e9f1e761c35eb8e70f218",
-  "size": 12980,
-  "revision": "sha256-92f7955f6f87"
+  "sha256": "e7fc4eb7a22eeb16c357bede9d0a080ad3b415aaab1d9c72f164d5350d48c4b1",
+  "size": 13664,
+  "revision": "sha256-e7fc4eb7a22e"
 }

package/assets/skills/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 1,
   "repository": "metergraph/skills",
-  "commit": "25a62e420589cb805e3dd7d9bb3e3a35d85e2ece",
+  "commit": "dda4d5f130448f12a7fb2549ed264503d8b51d8d",
   "skills": [
     {
       "name": "metergraph-analyze",
@@ -33,6 +33,12 @@
       "size": 3789,
       "revision": "sha256-9ce5a2cf527e"
     },
+    {
+      "name": "metergraph-local-bundle",
+      "sha256": "692cd8952a8a8896ec2c06091b329a7a01912e261e87d62a9458452172a7c9b0",
+      "size": 12245,
+      "revision": "sha256-692cd8952a8a"
+    },
     {
       "name": "metergraph-model-swap",
       "sha256": "d77ee37f882ab1e50dc4a093e64a2c3661f4cd9bb59f184da6dccbd76fd51a18",
@@ -41,9 +47,9 @@
     },
     {
       "name": "metergraph-onboarding",
-      "sha256": "15be9083f5b0d18cc6fe0d225f0921e2f16c5b4fb3d811c3984cef5cbc7941ba",
-      "size": 10208,
-      "revision": "sha256-15be9083f5b0"
+      "sha256": "6e6f418933f37b34437035ab3171344d43f37dee3770815b19f97efb62e5f1d1",
+      "size": 10267,
+      "revision": "sha256-6e6f418933f3"
     },
     {
       "name": "metergraph-report",

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

@@ -34,8 +34,9 @@ skill installation; a later installed version may offer `login`, `setup` and
 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
+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,

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,7 +1,7 @@
 {
   "name": "metergraph-cli",
-  "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",
+  "version": "0.2.0",
+  "description": "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": {
     "metergraph": "bin/metergraph.js"

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;
+}