npm - metergraph-cli - Versions diffs - 0.2.0-preview.2 → 0.2.0-preview.4 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/README.md +147 -839
package/assets/skill/SKILL.md +22 -2
package/assets/skill/manifest.json +3 -3
package/package.json +1 -1
package/src/args.js +13 -3
package/src/auth-login.js +10 -9
package/src/auth-oauth.js +26 -0
package/src/cli.js +19 -1
package/src/output.js +5 -2
package/src/repository-identity.js +246 -0
package/src/setup.js +31 -8
package/src/skill-bundle.js +1 -1
package/src/verify.js +7 -2

package/README.md CHANGED Viewed

@@ -1,536 +1,136 @@
 # metergraph-cli
-The Metergraph command line tool. Version `0.2.0-preview.2` is published on the
-`next` npm tag. The `latest` tag remains on `0.1.0`.
-Install the released preview channel with npm or run it directly:
+[![npm](https://img.shields.io/npm/v/metergraph-cli/next?label=npm%40next)](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)
+Connect a project to [Metergraph](https://www.metergraph.dev/) from the terminal or from
+your coding agent. Metergraph learns from your application's LLM traces, benchmarks
+models against your real usage and routes each task to the model that clears your
+quality bar. This CLI signs a project in, writes its ingest key, installs the Metergraph
+skill for Codex, Claude Code or Cursor, proves that a trace arrived, and reads cost,
+token and route metadata back. Every command has stable `--json` output and exit codes,
+so agents can run it as well as people.
 ```sh
 npx --yes metergraph-cli@next --help
-npx --yes metergraph-cli@next doctor --json
-npm install -g metergraph-cli@next
 ```
-The installed command is `metergraph`. Pin `metergraph-cli@0.2.0-preview.2`
-when you need this exact preview rather than whichever version `next` names later.
-**Availability:**
-- `metergraph-cli@0.1.0` contains only `doctor` and `skill install` /
-  `skill update`. It has no sign in commands.
-- `metergraph-cli@0.2.0-preview.0` adds `login`, `logout`, `setup`, `verify`,
-  `status`, `context`, `capabilities`, `usage`, `routes` and `traces`.
-- `metergraph-cli@0.2.0-preview.1` makes `setup` write the SDK service root as
-  `METERGRAPH_INGEST_URL` and repairs the full ingest endpoint that
-  `0.2.0-preview.0` wrote, after checking the saved key. It also keeps validated,
-  workspace-bound trace links in Metadata reads.
-- `metergraph-cli@0.2.0-preview.2` makes `verify` exit 11 `verification_failed`
-  when its deadline expires after the service reported the trace as pending, lets
-  `login` and `setup` reruns that need no approval succeed with `--json
-  --no-browser`, and reports why `verify --open` did not launch a browser.
-- Sign in needs a Metergraph service that offers Metadata-only CLI grants and grant
-  revocation. A service without them is reported as unsupported, and the CLI never
-  falls back to broader access.
-- The read commands need a project signed in with `login`. `setup` also needs the
-  deployment's ingest bootstrap API and browser approval by a workspace member.
-  `verify` checks one exact trace identity in an explicit invocation window using
-  Metadata access. It never sends application data.
-The preview includes:
-- `doctor` checks whether a Metergraph service is reachable, healthy and supported.
-- `skill install` and `skill update` copy the Metergraph agent skill bundled with the
-  CLI into one coding agent's project skill directory.
-- `login` and `logout` sign a project in to one workspace through your
-  browser with a delegated, Metadata-only grant, and sign it out again.
-- The read commands use that grant to read bounded workspace Metadata:
-  connection status, workspace context, capabilities, daily usage, routes and one page
-  of trace metadata.
-- `setup` guides browser sign in and workspace choice, asks for
-  ingest-only approval, writes a private project env file, confirms delivery, and
-  installs the selected client skill.
-- `verify` polls for one exact processed trace in a bounded window.
-  It does not infer application provenance from a Metadata match.
-It does not read retained content, replay traces, call model providers or send
-application data. Setup does not prove that the application sent a trace.
+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).
-## Requirements
+## Quickstart
-| | Supported |
-| --- | --- |
-| Node.js | 22 and 24 |
-| Operating systems | Linux, macOS and Windows (each in the CI matrix) |
-| Runtime dependencies | None |
-## Commands
+**1. Set up the project.** Run this in your project directory. It opens your browser to
+sign in and choose a workspace, asks a workspace member to approve an ingest-only key,
+writes `METERGRAPH_APP_TOKEN` and `METERGRAPH_INGEST_URL` to a private `.env`, and
+installs the skill for your coding agent.
 ```sh
-metergraph --help [--json]
-metergraph help doctor [--json]
-metergraph --version [--json]
-metergraph doctor [--url ORIGIN] [--timeout-ms N] [--json]
-metergraph help skill [--json]
-metergraph skill install --client CLIENT --runtime RUNTIME [--project DIR] [--json]
-metergraph skill update --client CLIENT --runtime RUNTIME [--project DIR] [--json]
-metergraph help login [--json]
-metergraph login --runtime local [--url ORIGIN] [--workspace UUID] [--project DIR] [--config-dir DIR] [--timeout-ms N] [--signup] [--no-browser] [--reconnect] [--json]
-metergraph logout [--project DIR] [--config-dir DIR] [--json]
-metergraph setup --runtime local (--client codex|claude|cursor | --skip-skill) [--deployment managed|customer-local|byoc|oss] [--url ORIGIN] [--workspace UUID] [--confirm-prerequisites] [--agent-token-file FILE] [--project DIR] [--config-dir DIR] [--env-file .env] [--timeout-ms N] [--signup] [--reconnect] [--no-browser] [--repair] [--json]
-metergraph status [--project DIR] [--config-dir DIR] [--timeout-ms N] [--json]
-metergraph context [--project DIR] [--config-dir DIR] [--timeout-ms N] [--json]
-metergraph capabilities [--project DIR] [--config-dir DIR] [--timeout-ms N] [--json]
-metergraph usage [--days N] [--limit N] [--project DIR] [--config-dir DIR] [--timeout-ms N] [--json]
-metergraph routes [--limit N] [--project DIR] [--config-dir DIR] [--timeout-ms N] [--json]
-metergraph traces [--days N] [--limit N] [--route NAME] [--status success|error] [--cursor CURSOR] [--project DIR] [--config-dir DIR] [--timeout-ms N] [--json]
-metergraph verify (--trace-id ID | --request-id ID) --since TIME --until TIME [--source application|synthetic|demo|import|unspecified] [--days N] [--timeout-ms N] [--poll-ms N] [--max-attempts N] [--open] [--no-browser] [--project DIR] [--config-dir DIR] [--json]
+npx --yes metergraph-cli@next setup --runtime local --client claude
 ```
-`--help`, `--version` and the `skill` commands work offline and make no network
-requests. `login`, `logout`, `setup`, `verify` and the read commands are not in the published `0.1.0`
-package.
-### Exact trace verification
+Use `--client codex` or `--client cursor` for the other agents.
-After an application invocation, pass its exact trace ID or request ID and the
-invocation start and end timestamps to `verify`. The optional `--source` label is a
-caller assertion. A matching Metadata row proves a processed trace is visible in the
-bound workspace, but does not independently prove that it came from your application.
-The result therefore keeps `application_traffic_verified: false` until a separate
-application instrumentation check supplies that evidence. A missing, ambiguous, stale
-or wrong-workspace result fails closed. The command neither creates an ingest key nor
-sends a test event.
-`--open` launches only a server-provided link carrying the exact trace and the
-verified workspace ID. The dashboard must check that ID against its signed-in
-workspace before displaying traces. Older links without a workspace remain a
-manual handoff; a conflicting workspace or unsafe link is refused. The result's
-`browser` field is `launcher_started`, `launcher_unavailable`, `not_requested`
-(no `--open`), or `suppressed_by_json` / `suppressed_by_no_browser` when `--open`
-was given but that flag returned the link instead of launching it.
-If `--timeout-ms` expires after the service has answered at least once with a
-pending result, `verify` exits 11 `verification_failed` with reason
-`verification_timeout`: the origin is reachable and the trace is not visible yet.
-Exit 4 `connection_failed` with that reason means no valid answer arrived before
-the deadline.
-### doctor
-`doctor` sends three unauthenticated, read-only `GET` requests to one origin, in order,
-and stops at the first problem:
-1. `/healthz` must answer `200` with the JSON body `{"ok": true}`.
-2. `/v1/deployment` must answer `200` with a JSON `deployment_profile` this CLI supports.
-3. `/v1/agent/capabilities` must answer `401` with a `WWW-Authenticate: Bearer` challenge.
-Options:
-| Option | Default | Notes |
-| --- | --- | --- |
-| `--url ORIGIN` | `https://app.metergraph.dev` | Bare origin only, see [Safe origins](#safe-origins). |
-| `--timeout-ms N` | `5000` | Whole number from 100 to 30000. Covers the whole probe, not each request. |
-| `--json` | off | Print exactly one JSON line on stdout and nothing on stderr. |
+**2. Run your application once**, instrumented with a Metergraph SDK (see the
+[first trace guide](https://www.metergraph.dev/docs/start/first-trace/)). Note the trace
+ID or request ID and when the call started and ended.
-A healthy, supported service exits with code **3, `authentication_required`**. That is
-the best result this preview can report: the service is reachable, but this CLI holds
-no credentials, so `authenticated` is always `false` and `workspace` is always `null`.
-A reachable service is not a working workspace connection. To connect an application,
-follow the [connection guide](https://www.metergraph.dev/docs/guides/agent-access/).
-`doctor` never opens a browser, never prompts and never reads stdin, so it is safe in
-scripts and CI.
-### skill install and skill update
-`skill install` copies the Metergraph skill bundled with this CLI into one client's
-native project skill directory. Both `--client` and `--runtime` are required, so the
-command never guesses where the skill will be used.
-| `--client` | Client | Skill file written | Client documentation |
-| --- | --- | --- | --- |
-| `codex` | Codex | `.agents/skills/metergraph/SKILL.md` | [Build skills](https://learn.chatgpt.com/docs/build-skills) |
-| `claude` | Claude Code | `.claude/skills/metergraph/SKILL.md` | [Skills](https://code.claude.com/docs/en/skills) |
-| `cursor` | Cursor | `.cursor/skills/metergraph/SKILL.md` | [Skills](https://cursor.com/docs/skills) |
-Each client has its own directory, so installing for several clients never makes one
-overwrite another.
-| Option | Default | Notes |
-| --- | --- | --- |
-| `--client CLIENT` | required | `codex`, `claude` or `cursor`. |
-| `--runtime RUNTIME` | required | `local` when the client runs on this machine, `cloud` when it runs in a cloud environment with a shell and a checkout of the project. Recorded, not detected. |
-| `--project DIR` | current directory | Must be an existing directory. Symbolic links in this path are resolved once; nothing below it is followed. |
-| `--json` | off | Print exactly one JSON line on stdout and nothing on stderr. |
-What it writes, and nothing else:
-1. The skill file in the table above, plus any of its missing parent directories.
-2. `.metergraph/skill-installations.json`, a small ownership receipt. For each client it
-   records the relative skill path, the skill name, the source revision and SHA-256,
-   and the runtimes requested. It contains no credentials, user names or absolute
-   paths, so it is safe to commit.
-Ownership rules:
-- `install` never replaces a skill it did not install, even one with identical bytes.
-- Running `install` again on an unchanged skill it installed changes nothing.
-- A skill it installed that was edited since is never overwritten, by `install` or by
-  `update`. Restore or remove the file first.
-- `update` is the only way to replace an older revision this CLI installed. There is no
-  force option.
-- A skill file this CLI installed that has gone missing is written again.
-- Symbolic links and other non-regular entries on the skill or receipt path are
-  refused.
-- Files are written to an exclusive temporary file and renamed into place, under a lock
-  file, `.metergraph/skill-installations.lock`. The receipt is written only after the
-  skill file, and a failed receipt write puts the skill file back as it was. If the
-  process is killed between the two writes, the skill is left without a receipt entry,
-  so later runs refuse to touch it, and the lock stays until you delete it.
-- It never changes client settings, MCP configuration, `AGENTS.md`, `CLAUDE.md` or any
-  other file, and keeps the permissions of a file it replaces.
-`--runtime cloud` writes the same project file. A cloud client sees it only through
-its own checkout of the project, so commit the file if you installed it elsewhere.
-Writing a skill file in a cloud checkout does not connect MCP, sign in or copy anything
-from your own machine. Local skills do not sync to desktop or cloud apps on their own.
-Clients and runtimes that cannot load project skill files get a pointer to the
-[connection guide](https://www.metergraph.dev/docs/guides/agent-access/) with exit code
-6, and nothing is written: `--client claude-desktop`, `--client chatgpt` and
-`--runtime cloud-no-shell` (a cloud runtime without a shell or project checkout).
-A successful run exits `0` with `discovery: "pending"` and `authenticated: false`.
-Writing the file does not prove that a client has loaded it. Start or reload the client
-in the project and check that it lists the `metergraph` skill. The skill itself is
-instructions for the agent; it holds no credentials and does not connect a workspace.
-#### Bundled skill source
-`assets/skill/SKILL.md` is a byte-for-byte copy of the public skill at
-<https://www.metergraph.dev/SKILL.md>. The source has no version number of its own, so
-`assets/skill/manifest.json` records its source URL, size and SHA-256, and a revision
-derived from that hash (`sha256-` followed by the first 12 hex digits). The package
-version is not the skill version. At runtime the CLI checks the bundled file against a
-hash pinned in its code and in the manifest, and refuses to write anything if either
-does not match. It never downloads the skill or runs a remote script. A new skill
-revision ships only in a new CLI release; `skill update` then upgrades projects that
-hold an unchanged earlier revision.
-### login and logout
-`login` binds a project directory to one Metergraph workspace. Your browser does the
-sign in, sign up, invitation and workspace consent on the service's own pages and
-keeps its own session. The CLI receives only a delegated OAuth grant limited to the
-Metadata scope, `agent:metadata`, checks it with the service and saves it privately.
+**3. Prove the trace arrived.** Setup only proves the key works; `verify` checks that this
+exact trace is visible in your workspace.
 ```sh
-metergraph login --runtime local --url https://metergraph.example.com
-metergraph logout
+npx --yes metergraph-cli@next verify --trace-id TRACE_ID \
+  --since 2026-01-08T12:00:00Z --until 2026-01-08T12:00:05Z
 ```
-| Option | Default | Notes |
-| --- | --- | --- |
-| `--runtime RUNTIME` | required | `local`: the browser runs on this machine. `cloud` and `cloud-no-shell` get a handoff to the [connection guide](https://www.metergraph.dev/docs/guides/agent-access/) with exit code 6. |
-| `--url ORIGIN` | `https://app.metergraph.dev` | Bare origin only, see [Safe origins](#safe-origins). |
-| `--workspace UUID` | none | The workspace you expect. Sign in fails unless the browser grants exactly this one. Without it, the workspace you choose in the browser is used after the service confirms it. |
-| `--project DIR` | current directory | Existing project directory to bind. |
-| `--config-dir DIR` | see below | Private per-user directory for the saved grant. |
-| `--timeout-ms N` | `300000` | How long to wait for the browser, 1000 to 900000. |
-| `--signup` | off | Start at the hosted sign up page, which returns to the same authorization request. Managed service only; other profiles exit 6. |
-| `--no-browser` | off | Print the authorization URL on stderr for you to open on this machine, then wait. With `--json`, a rerun that needs no approval succeeds; one that needs approval exits 6 `no_browser_requires_terminal`. |
-| `--reconnect` | off | Allow replacing a binding to a different origin or workspace. |
-| `--json` | off | Print exactly one JSON line on stdout and nothing on stderr. |
-What `login` does, in order:
-1. Refuses cloud runtimes, SSH sessions, cloud development environments and CI (by the
-   presence of variables such as `SSH_CONNECTION`, `CODESPACES` or `CI`; values are
-   never read into output) before any request, listener or file write.
-2. Reads the project binding. A project bound to another origin or workspace is refused
-   with exit code 8 unless you pass `--reconnect`. A project that is already signed in
-   and still verified is left as it is, with no browser and no new client.
-3. Runs the same checks as `doctor`, then reads the service's OAuth metadata from the
-   same origin. Every endpoint must be a fixed path on that origin, and the service must
-   offer `agent:metadata`, PKCE with `S256`, public clients and revocation.
-4. Registers a public client named `Metergraph CLI` for one loopback redirect,
-   `http://127.0.0.1:PORT/callback` on an ephemeral port, creates a random state and
-   PKCE verifier, and arms the callback listener and its timeout before the browser
-   opens.
-5. Opens the authorization URL with the operating system's launcher (no shell). The
-   listener accepts one `GET` with the exact host, path and state. Other requests get a
-   fixed page and do not end the wait.
-6. Exchanges the code and accepts only a Bearer grant for exactly `agent:metadata` whose
-   claims name this issuer, resource, client and one workspace. The claims are a sanity
-   check; the CLI does not verify token signatures.
-7. Asks the service, with the new token, for `/v1/agent/workspace` and
-   `/v1/agent/capabilities`. The workspace ID, its provenance and the token must agree,
-   the deployment profile must match step 3, the access scopes must be exactly
-   `agent:metadata`, and content, evidence and replay capabilities must be unavailable.
-   Nothing else is read.
-8. Saves the grant in the config directory and writes `.metergraph/project.json`.
-Once the token response has been validated and holds a usable refresh token, a grant
-the CLI decides not to keep (a workspace other than the one expected or bound, failed
-verification, cancellation) is sent to the revocation endpoint before the command
-exits. If the grant cannot be saved or the binding cannot be written, the saved grant
-is removed, revocation is requested the same way, and the command exits 9. This is best
-effort: the service may not answer or may not confirm, and the CLI does not retry. A
-token response that fails validation is dropped without a revocation request, because
-the CLI cannot safely use anything in it; a server-side grant may remain active until it
-expires or is revoked from the service.
-The config directory is `--config-dir`, else `METERGRAPH_CONFIG_DIR` (an absolute
-path), else `~/.config/metergraph` on Linux and macOS or `AppData\Roaming\Metergraph` in
-your Windows profile. It holds `credentials/SLOT.json`:
-- On Linux and macOS the directories must be `0700` and the file `0600`, all owned by
-  you. Existing paths with other permissions, other owners or symbolic links are
-  refused and never changed.
-- On Windows the grant is encrypted with DPAPI for the current user before it is
-  written. File permissions alone are not relied on there.
-`.metergraph/project.json` holds the origin, workspace ID, deployment profile and the
-name of the credential slot. It holds no token, user name or absolute path, so it is
-safe to commit. Other files in `.metergraph`, such as the skill receipt, are kept.
-Access tokens near expiry are refreshed once, under a lock, and the new refresh token
-is saved before it is used. If a refresh request may have reached the service but its
-result was not saved (a timeout after sending, a dropped connection, a server error or
-an unusable answer), the old refresh token is never sent again: the next use asks you
-to run `login` again. A revoked grant or lost workspace access fails closed with exit
-code 12.
-`logout` asks the service to revoke the project's grant through its revocation
-endpoint, then removes the saved grant and `.metergraph/project.json`. Other credential
-slots and project files are kept. A `200` from the service means it accepted the
-revocation request. If it does not answer `200`, local sign out still happens and the
-command exits 13 with `revocation: "unconfirmed"`. A project that is not signed in
-exits 0 without any request.
-### setup
-Run setup once from a project directory, choosing the coding client that will use
-the skill:
+Then read what Metergraph has recorded:
 ```sh
-metergraph setup --runtime local --client codex --project /path/to/project
+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
 ```
-For a customer-local bundle, point setup at its installed origin and exact
-workspace:
+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.4`, when a
+script must not change with the `next` tag.
-```sh
-metergraph setup --runtime local --deployment customer-local --url http://localhost:8080 --workspace 11111111-1111-4111-8111-111111111111 --confirm-prerequisites --client codex
-```
+## Requirements
-`--confirm-prerequisites` records the operator's attestation that the released
-signed bundle, registry invitation, local admin, and separate Metadata access
-prerequisites are ready. It is not proof of bundle publication or registry
-access. Setup checks the live deployment profile before login. BYOC uses
-`--deployment byoc` and an explicit HTTPS private origin; its provisioning,
-network, and identity prerequisites remain the operator's work. An optional
-`--agent-token-file` can verify a separate Metadata credential for either
-route. OSS uses separate `MG_TOKENS` ingestion and `MG_AGENT_TOKENS` read
-credentials; `--deployment oss` verifies its Metadata route with a private
-agent token file and hands ingest configuration to the operator. It does not
-try hosted login or ingest bootstrap against OSS. Remote runtimes are handed
-off to a local machine, with no implicit tunnel or credential forwarding.
-If the project has no usable Metadata sign in, `setup` opens the deployment's
-browser sign in and workspace choice. `--signup` starts at hosted sign up;
-`--workspace UUID` requires that exact workspace. An existing binding to a
-different origin or workspace requires explicit `--reconnect`. The selected
-deployment must advertise `metergraph.cli-setup/v1` on its own origin. Setup
-refuses reconnecting an existing ingest family to another workspace; its
-original workspace must be restored before that family can be reused. Setup
-checks the env file and Git state, then opens the deployment's consent page. An
-owner or member of the verified workspace approves an ingest-only key. The CLI
-redeems the single-use receipt, writes `METERGRAPH_APP_TOKEN` and
-`METERGRAPH_INGEST_URL` into `.env`, checks the new key with the service, and
-acknowledges delivery. It then installs the bundled skill for `codex`, `claude`
-or `cursor`. Use `--skip-skill` only if you intentionally want to install it
-later. Neither sign in nor setup requests Debug or Replay access. The browser
-page shows the workspace and the consequence of approval. A signed-in browser
-on another workspace must switch in Metergraph and rerun; the CLI does not
-switch it automatically.
-`METERGRAPH_INGEST_URL` is the deployment's service root. The Python SDK
-appends `/v1/ingest` itself. A setup rerun with a verified
-key repairs the endpoint value written by the first preview without minting a
-new key.
-The env file must be a project-relative `.env`, `.env.<name>` or `<name>.env`
-(`--env-file` selects another). The writer refuses tracked files, links,
-ambiguous dotenv syntax and unsafe paths. It adds a project `.gitignore` rule
-when needed and makes the env file private; Windows uses a user-only ACL.
-The env token is never printed, read from argv or stdin, or copied to the
-project's setup state file. An already working key is checked and reused without
-another browser approval.
-`.metergraph/setup.json` holds a family UUID, its current key ID and fixed state,
-but no credential. It is written before approval. If the redemption response is
-lost, a rerun asks for a new browser approval for that same family. The server
-resolves the request to creation if no key was issued or replacement of that
-family's pending key if one exists; the old receipt is not retried. If an
-acknowledged key no longer verifies or its env file was lost, use `--repair`
-to explicitly approve replacement of that exact key.
-An unsafe or changed state file is refused. If the earlier approval never
-reached redemption, rerun the command; the `create` intent is still safe.
-The JSON result includes a secret-free `receipt` with the origin, workspace ID,
-deployment profile, selected client, and completed and pending steps. A skill
-conflict leaves the delivered key in place and reports `credential_ready_skill_pending`;
-resolve the skill file conflict and rerun setup without another approval.
-Success means the key was delivered and the project is ready to instrument.
-It does **not** mean application traffic has arrived. Run your application and
-verify one exact trace afterward. The hosted service advertises the setup
-contract, but each non-hosted deployment must be checked at its own origin.
-Local protocol tests do not prove browser approval or real application traffic.
-### Read commands
-The read commands use the grant `login` saved for this project. They never open a
-browser, never sign in on their own and never request another scope. Each one:
-- reads `.metergraph/project.json` and the saved grant, and refreshes the grant at most
-  once, under the same lock and rules as `login` (an interrupted refresh is never
-  retried with a possibly used token);
-- asks the service for `/v1/agent/workspace` and `/v1/agent/capabilities` and checks,
-  as `login` does, that the workspace, deployment profile and `agent:metadata` scope
-  still match the binding and that content, evidence and replay are unavailable;
-- sends only `GET` requests to fixed paths on the bound origin, follows no redirects and
-  reads at most 1 MiB of a response;
-- runs every request, including a refresh and any wait for another command that is
-  refreshing the same grant, within one total `--timeout-ms` deadline (1000 to 60000,
-  default 15000), which is never reset per request or page. A deadline exits 4
-  (`timeout`) and Ctrl+C exits 17, also while waiting for that lock; a lock held by
-  another process is never removed or taken over;
-- prints only fields it validated. Unknown response fields are ignored and never named.
-  A metadata row that holds a field such as `prompt`, `messages`, `tool_calls` or
-  `access_token` is refused as a whole (exit 11). Names that contain control or
-  formatting characters are shown as `null`. Service warning and error text is not
-  printed. If any printed value, such as a workspace name, route name, cursor or
-  provenance source, contains a token the CLI holds for this project, nothing is
-  printed and the command exits 11 with `credential_in_metadata_response`.
-Read commands do not change workspace configuration or telemetry, send no ingest data
-and call no model provider. They are not side-effect free on the service: a command may
-refresh its own saved grant, and the service may update its audit records and last used
-times for the grant.
-| Command | Request | What it prints |
-| --- | --- | --- |
-| `status` | `GET /healthz` and `GET /v1/deployment` (no credentials, checked as `doctor` does), then the two checks above | `configured`, `reachable`, `healthy`, `authenticated`, the bound (`intended`) and verified (`actual`) workspace, the bound deployment profile and `deployment_profile_verified`, scopes and capability flags. A `/v1/deployment` profile that differs from the binding exits 11 with `profile_mismatch` before the grant is used. `application_traffic_verified` is always `false`: a signed in project, existing data or a configured SDK does not prove that your application sends traffic. |
-| `context` | the two checks above | Workspace ID, slug, name and creation time, Metadata retention days, whether the workspace captures content (never included here) and the access scope. |
-| `capabilities` | the two checks above | Each known agent capability with `available`, `privacy_class`, `required_scope` and flags, and the service's bounds. Privacy class descriptions are not printed. |
-| `usage` | `GET /v1/agent/usage?days=N&limit=N` | Daily rows per route: calls, errors, cost, tokens and latency (latency may be `null`), the window, evidence completeness, warning codes and totals of the returned rows. |
-| `routes` | `GET /v1/agent/routes` | Route name, calls, replay eligible calls, evaluation contract version and hash, and whether a description or contract exists. |
-| `traces` | `GET /v1/agent/traces?days=N&limit=N[&route=&status=&cursor=]` | One page of trace metadata: IDs, name, status, times, span count, tokens, cost (may be `null`), routes, providers and models, plus `next_cursor`. |
-Bounds and honesty rules:
-- `--days` is 1 to 90 (default 7) and `--limit` 1 to 200 (default 50, or 20 for
-  `traces`). Values outside these ranges exit 2. A value above the service's own
-  advertised `max_days` or `max_rows` exits 6 with `exceeds_service_bounds`; it is never
-  reduced silently.
-- `usage` and `traces` report `truncated` and `complete`. Totals are sums of the
-  returned rows only; when `complete` is `false` they are not workspace totals. An
-  empty window is a successful result with `empty: true`.
-- `GET /v1/agent/routes` takes no limit or window. The CLI validates every returned row,
-  keeps the first `--limit`, and reports `server_rows`, `truncated` and
-  `truncation: "local"`. Route descriptions, constraints and evaluation contract bodies
-  are never printed; `omitted_fields` lists them.
-- `traces` fetches exactly one page. When more exist it returns `next_cursor`; pass it
-  back with `--cursor` to read the next page. The cursor is opaque and at most 512
-  printable characters. A page whose `limit` differs from the request, or rows that do
-  not match `--status` or `--route`, exit 11. Free-text filter values are not printed
-  back.
-- The `traces` listing prints no trace links; each row has `link: null` and the
-  page reports `link_status: "server_link_unavailable"`. Exact-trace
-  `verify --open` uses a server link only when it includes the verified
-  workspace binding.
-- `--environment`, `--workload`, `--since`, `--until`, `--sql`, `--query`, `--content`,
-  `--include-content`, `--debug` and `--replay` are recognized and refused with exit 6
-  before any request. The agent access contract has no environment selector or
-  absolute time range, and these commands never read content or replay. `--workload`
-  is refused by this CLI version because the returned trace rows do not show which
-  workload they belong to, so a filtered page could not be verified.
-- A capability the service does not offer to this grant exits 14 without a read. A
-  refused read exits 15 (`insufficient_scope` or `forbidden`), rate limiting exits 16
-  with `retry_after_seconds` when the service sends a whole number of seconds, and a
-  token refused during the read exits 12. Nothing is retried. Ctrl+C exits 17.
-A successful `usage`, shortened:
-```json
-{
-  "schema_version": 1,
-  "command": "usage",
-  "ok": true,
-  "outcome": "ok",
-  "exit_code": 0,
-  "data": {
-    "origin": "https://metergraph.example.com",
-    "workspace": { "id": "0b5c7c1e-1a2b-4c3d-8e4f-5a6b7c8d9e01" },
-    "deployment_profile": "managed",
-    "authenticated": true,
-    "scopes": ["agent:metadata"],
-    "result": {
-      "provenance": {
-        "deployment_profile": "managed",
-        "workspace_id": "0b5c7c1e-1a2b-4c3d-8e4f-5a6b7c8d9e01",
-        "generated_at": "2026-01-08T12:00:00Z",
-        "source": "example-source"
-      },
-      "window": { "days": 7, "since": "2026-01-01T12:00:00Z", "until": "2026-01-08T12:00:00Z" },
-      "evidence": { "sources": ["telemetry"], "rows": 1, "complete": true },
-      "warnings": [],
-      "content_included": false,
-      "truncated": false,
-      "complete": true,
-      "empty": false,
-      "rows": 1,
-      "items": [
-        {
-          "date": "2026-01-02",
-          "route": "checkout-summary",
-          "calls": 40,
-          "error_calls": 2,
-          "cost_usd": 0.0125,
-          "input_tokens": 12000,
-          "output_tokens": 3400,
-          "avg_latency_ms": 820,
-          "p95_latency_ms": null
-        }
-      ],
-      "totals": {
-        "scope": "returned_rows",
-        "complete": true,
-        "calls": 40,
-        "error_calls": 2,
-        "cost_usd": 0.0125,
-        "input_tokens": 12000,
-        "output_tokens": 3400
-      }
-    },
-    "retry_after_seconds": null,
-    "notices": [],
-    "next_action": null
-  },
-  "error": null
-}
+| | Supported |
+| --- | --- |
+| Node.js | 22 and 24 |
+| Operating systems | Linux, macOS and Windows, each tested in CI |
+| Runtime dependencies | None |
+| Service | Hosted Metergraph, or a self-hosted deployment (see [Deployments](#deployments)) |
+Sign in needs a service that offers Metadata-only CLI grants and grant revocation; a
+service without them is reported as unsupported, and the CLI never falls back to
+broader access. `setup` also needs the deployment's ingest bootstrap API and approval by
+a workspace member. Sign in needs a browser on the same machine. From SSH sessions,
+cloud development environments and CI, `login` and `setup` hand off to a local machine
+instead (exit 6).
+## Using it with a coding agent
+The CLI is built to be run by Codex, Claude Code and Cursor as well as by people:
+- **Skill.** `setup` installs the Metergraph skill, which tells the agent how to set up
+  and query Metergraph. To install or update only the skill, with no sign in and no
+  network access:
+  ```sh
+  npx --yes metergraph-cli@next skill install --client codex --runtime local
+  ```
+  A Python equivalent, [`metergraph-skills`](https://github.com/metergraph/cli/blob/main/python/metergraph-skills/README.md), is
+  ready for its first PyPI release. Both write the same files and recognise each
+  other's installs.
+- **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.
+- **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/).
+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;
+  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.
 ```
-On failure `result` is `null`, `authenticated` says whether the grant was verified
-before the failure, and `notices` lists fixed tokens such as `rows_truncated`,
-`evidence_incomplete`, `routes_truncated_locally`, `unsafe_text_omitted` or
-`trace_links_unavailable`.
+## Commands
+| Command | What it does | Network |
+| --- | --- | --- |
+| `setup` | Sign in, choose a workspace, write the ingest key to `.env`, record the repository, install the skill | Yes |
+| `verify` | Confirm that one exact trace, by trace ID or request ID, reached the workspace | Yes |
+| `usage` | Daily calls, errors, cost, tokens and latency per route | Yes |
+| `traces` | One page of trace metadata, with a cursor for the next page | Yes |
+| `routes` | Routes with call counts and evaluation contract status | Yes |
+| `status` | Whether the project is signed in, and to which workspace | Yes |
+| `context` | Workspace details and retention | Yes |
+| `capabilities` | What the workspace makes available to this project | Yes |
+| `login`, `logout` | Sign a project in or out without the rest of `setup` | Yes |
+| `doctor` | Check that a service is reachable, healthy and supported, without credentials | Yes |
+| `skill install`, `skill update` | Install or update the Metergraph skill for one agent | No |
+`metergraph help COMMAND` lists a command's options. The
+[CLI reference](https://github.com/metergraph/cli/blob/main/docs/reference.md) covers every option, what each command reads and
+writes, and full JSON examples.
 ## Exit codes
-Exit codes are stable. Changing one is a breaking change. Codes 10 to 17 were
-added in `0.2.0-preview.0` and are unavailable in `0.1.0`.
+Exit codes are stable. Changing one is a breaking change. Codes 10 to 17 are not in
+`0.1.0`.
 | Code | Outcome | Meaning |
 | --- | --- | --- |
@@ -538,14 +138,14 @@ added in `0.2.0-preview.0` and are unavailable in `0.1.0`.
 | 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. |
+| 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. 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, or `--json --no-browser` needs a browser approval it cannot show (`no_browser_requires_terminal`). 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. |
 | 10 | `authorization_failed` | Browser authorization did not finish: it was denied, cancelled, timed out or returned an invalid callback. Nothing was saved. |
-| 11 | `verification_failed` | The service issued a grant that does not match the requested origin, workspace, client, resource or Metadata scope. Nothing was saved. |
+| 11 | `verification_failed` | The service issued a grant that does not match the requested origin, workspace, client, resource or Metadata scope. Nothing was saved. For `verify`, the exact trace was not confirmed: for example `trace_not_found_within_bounds` when the service kept answering but the trace was not visible before attempts or the deadline ran out. |
 | 12 | `login_required` | No usable sign in for this project: none was saved, it expired, was revoked, lost access or could not be refreshed safely. Run login again. |
 | 13 | `revocation_unconfirmed` | Local credentials were removed, but the service did not confirm that the grant was revoked. |
 | 14 | `capability_unavailable` | The service does not make this read available to the project's Metadata grant. No data was read. |
@@ -553,339 +153,47 @@ added in `0.2.0-preview.0` and are unavailable in `0.1.0`.
 | 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. |
-## JSON output
-With `--json`, every command prints one line with the same top-level keys:
-```json
-{
-  "schema_version": 1,
-  "command": "doctor",
-  "ok": false,
-  "outcome": "authentication_required",
-  "exit_code": 3,
-  "data": {
-    "origin": "https://app.metergraph.dev",
-    "reachable": true,
-    "healthy": true,
-    "deployment_profile": "managed",
-    "profile_status": "supported",
-    "authentication_required": true,
-    "authenticated": false,
-    "workspace": null,
-    "checks": [
-      { "name": "health", "path": "/healthz", "result": "pass", "http_status": 200, "reason": null },
-      { "name": "deployment", "path": "/v1/deployment", "result": "pass", "http_status": 200, "reason": null },
-      { "name": "capabilities", "path": "/v1/agent/capabilities", "result": "pass", "http_status": 401, "reason": "bearer_token_required" }
-    ],
-    "next_action": { "kind": "connection_guide", "url": "https://www.metergraph.dev/docs/guides/agent-access/" }
-  },
-  "error": {
-    "code": "authentication_required",
-    "reason": "bearer_token_required",
-    "message": "The service is reachable and supported, and it requires authentication. No workspace is connected."
-  }
-}
-```
-(Shown formatted here. The CLI prints it on a single line.)
-- `ok` is `true` only when `outcome` is `ok`. When `ok` is `false`, `error.code` equals
-  `outcome` and `error.reason` is a fixed token such as `timeout`, `invalid_url`,
-  `unrecognized_profile` or `response_too_large`.
-- `profile_status` is `supported`, `unrecognized`, `unavailable` (the server has no
-  `/v1/deployment` endpoint) or `unknown` (not checked).
-- Checks that did not run have `result: "skipped"`.
-- `--help --json` includes the command list and the exit code table.
-A successful `skill install`:
-```json
-{
-  "schema_version": 1,
-  "command": "skill install",
-  "ok": true,
-  "outcome": "ok",
-  "exit_code": 0,
-  "data": {
-    "client": "claude",
-    "runtime": "local",
-    "path": ".claude/skills/metergraph/SKILL.md",
-    "status": "installed",
-    "source": {
-      "name": "metergraph",
-      "revision": "sha256-57b920677adf",
-      "sha256": "57b920677adf62759c7221629327192a2d16b7e6034f7948ffd96cee402d4891"
-    },
-    "discovery": "pending",
-    "authenticated": false,
-    "next_action": {
-      "kind": "reload_client",
-      "message": "Start or restart Claude Code in this project, then confirm that it lists the metergraph skill."
-    }
-  },
-  "error": null
-}
-```
-- `status` is `installed`, `updated` or `reused` (already in place, nothing rewritten).
-- `path` is always relative to the project. Absolute paths are never printed.
-- On failure `status` and `discovery` are `null`, and `error.reason` is a fixed token
-  such as `not_owned`, `modified`, `update_required`, `not_installed`, `unsafe_path`,
-  `receipt_invalid`, `locked`, `invalid_project`, `client_not_supported`,
-  `write_failed` or `bundled_skill_invalid`.
-A successful `login`:
-```json
-{
-  "schema_version": 1,
-  "command": "login",
-  "ok": true,
-  "outcome": "ok",
-  "exit_code": 0,
-  "data": {
-    "origin": "https://metergraph.example.com",
-    "runtime": "local",
-    "deployment_profile": "managed",
-    "workspace": { "id": "0b5c7c1e-1a2b-4c3d-8e4f-5a6b7c8d9e01" },
-    "scopes": ["agent:metadata"],
-    "authenticated": true,
-    "configured": true,
-    "status": "signed_in",
-    "binding": ".metergraph/project.json",
-    "credential_protection": "owner_only_file",
-    "previous_grant_revocation": null,
-    "next_action": {
-      "kind": "connected",
-      "message": "This project is signed in with Metadata access. Run \"metergraph logout\" to sign out."
-    }
-  },
-  "error": null
-}
-```
-- `status` is `signed_in`, `reused` (already signed in and verified, nothing changed)
-  or `reconnected` (a new grant replaced the previous one; `previous_grant_revocation`
-  is then `accepted`, `unconfirmed` or `not_attempted`).
-- `credential_protection` is `owner_only_file` or `dpapi`.
-- On failure `authenticated` and `configured` are `false`, `scopes` is empty, and
-  `next_action` is `null` or a handoff such as `connection_guide`, `reconnect`,
-  `run_in_terminal` or `no_browser`.
-- The schema version `1` is the version of this CLI's own JSON output. It is unrelated
-  to the service's agent access contract version, `metergraph.agent-access/v1`.
-- `login` and `logout` never print tokens, the authorization code, the PKCE verifier,
-  user names, email addresses, workspace names, absolute paths or server text. The
-  read commands never print tokens, email addresses, absolute paths or server error
-  text either; `context` prints the workspace slug and name, and the read commands
-  print validated route, trace, provider and model names, as described above.
-`logout` prints `local_credentials` (`removed` or `none`), `binding` (`removed`,
-`kept` or `none`) and `revocation` (`accepted`, `unconfirmed` or `not_attempted`).
-Without `--json`, results are printed as text on stdout and usage errors go to stderr.
-`login` prints progress lines, and with `--no-browser` the authorization URL, on
-stderr.
-## Safe origins
-`--url` accepts only a bare origin, with an optional trailing slash:
-- `https://` origins on any host, for example `https://metergraph.example.com`.
-- `http://` only for `localhost`, `127.0.0.1` and `[::1]`, with an optional port.
-Usernames, passwords, paths, queries and fragments are rejected before any request is
-made. Invalid values and unknown arguments are not printed back, because a mistyped
-argument can contain a credential. An accepted origin is printed in the output and sent
-to the network, so do not put secrets in a hostname. See [Security](#security).
-## Deployment profiles
-The CLI recognizes these `deployment_profile` values: `local`, `managed` and
-`byoc-core`. Managed staging uses the `managed` profile. Any other value is reported as `unsupported` and is not echoed. A server
-without `/v1/deployment`, such as a self-hosted open source server, is reported as
-`unsupported` with `profile_status: "unavailable"` until a dedicated adapter ships. The
-CLI never assumes such a server is hosted.
-## What doctor does not do
-- It reads no credentials from environment variables, files, arguments or cookies, and
-  sends no `Authorization` or `Cookie` header.
-- It follows no redirects.
-- It reads at most 32 KiB of any response body and stops at the `--timeout-ms` limit.
-- It never prints response bodies, response headers, authentication challenges,
-  server-supplied URLs or error text from the network stack.
-- It makes no model provider calls, sends no usage data and reads no stored traces.
-## What skill install does not do
-- It makes no network requests and no model provider calls. The skill comes from this
-  package, not from a download.
-- It does not sign in, store credentials, configure MCP or edit client settings.
-- It does not claim a client has loaded the skill. `discovery` stays `pending`.
-- It never prints file contents, absolute paths or raw error text.
-## What login does not do
-- It never asks for Debug (`agent:read`) or Replay (`agent:replay`) access, and never
-  falls back to them when the service does not offer `agent:metadata`.
-- It never copies browser cookies or the browser's sign in.
-- It does not create an application ingest key, and no manual API key is required. The
-  service records the grant as an OAuth connection on its own side; that connection
-  can only use `agent:metadata`, is separate from any API or ingest key you manage, and
-  is what `logout` asks the service to revoke.
-- It reads no telemetry, retained content or traces, and makes no model provider calls.
-- It sends the grant only to the origin it came from, follows no redirects and reads
-  bounded responses within fixed time limits.
-- It accepts no credential on the command line, in the environment or on stdin.
-## What the read commands do not do
-- They never sign in, open a browser, create a grant or change the project binding.
-  The only file they may write is the saved grant, when a refresh rotates it.
-- They never request `agent:read` or `agent:replay`, never read retained content,
-  evidence or replays, and never call a model provider.
-- They make only `GET` requests to the read endpoints (a grant refresh, when needed, is
-  the only `POST`). They send no ingest data and change no evaluations, provider
-  settings, workspace configuration or telemetry. The service may still record the
-  access, for example audit entries and the grant's last used time.
-- They never print a token the CLI holds, even inside an otherwise valid name.
-- They never follow a cursor or page on their own, and never widen a request: an
-  unsupported option, an out of range value or a capability the grant lacks fails
-  instead.
-- They accept no credential on the command line, in the environment or on stdin.
-## Development
-```sh
-npm test                  # unit tests and CLI subprocess tests against loopback servers
-npm run test:package      # npm pack into a temporary directory, clean install, run the installed bin
-node bin/metergraph.js --help
-node bin/metergraph.js doctor --url http://127.0.0.1:8080 --json
-node bin/metergraph.js skill install --client claude --runtime local --project /path/to/project --json
-node bin/metergraph.js login --runtime local --url http://127.0.0.1:8080 --project /path/to/project
-```
-The sign in and read command tests run against a synthetic loopback service and a
-test-only browser stand-in loaded with `--import`. They prove the protocol, file
-handling and output rules, not the real service, a real browser, real workspace
-consent or real workspace data. The Windows DPAPI round trip
-runs only on the Windows CI runner.
-To try a packed artifact without publishing:
-```sh
-npm pack --pack-destination "$(mktemp -d)"
-npx --yes --package=/path/to/metergraph-cli-0.2.0-preview.2.tgz -- metergraph --version
-```
-Do not commit tarballs or other generated files.
-## Releasing
-The source of truth is the public repository
-[github.com/metergraph/cli](https://github.com/metergraph/cli), licensed Apache-2.0.
-`0.2.0-preview.2` is published on the `next` npm tag; `latest` remains on
-`0.1.0`. The hosted service supports sign in, Metadata reads and ingest bootstrap.
-Subsequent releases must pass the checks below before publication.
-Releases are manual. The `Release CLI` workflow (`.github/workflows/release.yml`) runs
-only when a maintainer starts it from `main`. It does not run on tags, pushes or a
-schedule. It:
-1. checks that `commit_sha` equals the commit the run started from (see
-   [Exact revision rule](#exact-revision-rule)), that it is on `main`, and that
-   `version` equals `package.json`;
-2. asks the npm registry for that exact version and continues only on a `404`. An
-   existing version, any other status or a network failure stops the run;
-3. runs `npm test` and `npm run test:package` at that commit;
-4. packs the tarball and records its SHA-256;
-5. only if `publish` is true, waits for approval on the `npm-release` environment,
-   checks out the same commit again, verifies the checksum and runs
-   `npm publish --provenance` for that exact tarball.
-Leave `publish` false for a dry run that validates and packs without publishing.
-### Exact revision rule
-npm provenance records the commit that triggered the workflow (`GITHUB_SHA`) as the
-source of the package. To keep that statement true, the workflow only releases that
-commit:
-- `commit_sha` must be the full 40 character SHA of the current head of `main`, and it
-  must equal `GITHUB_SHA` for the run. Older commits on `main` are rejected even though
-  they are ancestors of `main`.
-- Both the validate job and the publish job check out that commit and confirm it.
-- If `main` moves after you copy the SHA, the run fails. Start a new run with the new
-  head. To release an older state, land it on `main` first.
-### First package bootstrap (completed for 0.1.0)
-npm trusted publishing is configured on a package that already exists, so the very
-first version could not come from this workflow. The steps below describe the
-completed bootstrap of `0.1.0`; they are not part of subsequent releases. No npm
-token or secret is stored here.
-1. Confirm the intended npm maintainer accounts and that `metergraph-cli` is
-   available. The first approved publish establishes package ownership.
-2. Run the `Release CLI` workflow with `publish` false. Download the
-   `metergraph-cli-release` artifact and check its SHA-256 against the run summary.
-3. From a maintainer machine with npm two-factor authentication, publish that exact
-   tarball manually using `npm publish /path/to/metergraph-cli-0.1.0.tgz --access public
-   --tag next --provenance=false --ignore-scripts`. This bootstrap version has no
-   provenance attestation. Use a new version for the first trusted release.
-4. Configure trusted publishing as described below.
-### Trusted publishing
-After the package exists, follow the official npm guide,
-[Trusted publishing for npm packages](https://docs.npmjs.com/trusted-publishers/), and
-add a GitHub Actions trusted publisher with exactly these values:
-| Field | Value |
-| --- | --- |
-| Organization or user | `metergraph` |
-| Repository | `cli` |
-| Workflow filename | `release.yml` |
-| Environment name | `npm-release` |
-Trusted publishing requires npm 11.5.1 or newer. The publish job checks this before it
-publishes. After the trusted publisher works, consider restricting the package to
-trusted publishing so that long lived tokens cannot publish it.
-### Release configuration
-Before an automated publish, confirm the following settings are still in place:
-- the [trusted publisher](#trusted-publishing) matches this repository and workflow;
-- the `npm-release` environment has required reviewers;
-- the repository variable `METERGRAPH_CLI_PUBLISH_ENABLED` is `true`.
-Until all of these are done, leave `publish` false.
-### After a release
-After each release, confirm from a clean machine, replacing `VERSION`:
-```sh
-npx --yes metergraph-cli@VERSION --version --json
-npx --yes metergraph-cli@VERSION doctor --json
-npm view metergraph-cli@VERSION dist.attestations
-```
-Releases from the workflow should show a provenance attestation that names
-`metergraph/cli` and the released commit. The bootstrap version will not.
-## Security
-Report security issues privately through
-[GitHub private vulnerability reporting](https://github.com/metergraph/cli/security/advisories/new)
-for `metergraph/cli`. Do not open a public issue, and do not include real credentials,
-tokens or customer data in a report. The security policy and the CLI's security
-properties are in `SECURITY.md` in the
-[source repository](https://github.com/metergraph/cli); it is not shipped in the npm
-package.
+## Security and privacy
+- **No usage telemetry.** The CLI collects no analytics about how you use it. It talks
+  only to the Metergraph origin you point it at.
+- **Least access.** Sign in grants only the Metadata scope, `agent:metadata`. The CLI
+  never requests Debug or Replay access, never falls back to broader access, and never
+  reads retained prompts, responses or other content. It calls no model provider.
+- **Credentials.** The sign in grant is stored per user in `~/.config/metergraph`
+  (`AppData\Roaming\Metergraph` on Windows), as owner-only files on Linux and macOS and
+  encrypted with DPAPI on Windows. The ingest key goes only into the project's private
+  `.env`, which `setup` adds to `.gitignore`. No command accepts a credential on the
+  command line, in the environment or on stdin, or prints one.
+- **Files it writes in your project:** `.env` (from `setup`), the skill file, and
+  secret-free state under `.metergraph/` that is safe to commit. The skill installer
+  never replaces a file it did not write and has no force option.
+- **Network.** Only `GET` requests to fixed paths for reads, no redirects followed,
+  bounded response sizes and fixed timeouts. Mistyped arguments are never echoed, since
+  they may hold a secret. `--help`, `--version` and `skill` make no network requests.
+The [CLI reference](https://github.com/metergraph/cli/blob/main/docs/reference.md) states what each command does and does not do.
+Report vulnerabilities privately through
+[GitHub private vulnerability reporting](https://github.com/metergraph/cli/security/advisories/new),
+not in a public issue, and leave real credentials, tokens and customer data out of the
+report. See [SECURITY.md](https://github.com/metergraph/cli/blob/main/SECURITY.md).
+## Deployments
+`--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 reference](https://github.com/metergraph/cli/blob/main/docs/reference.md#setup).
+## Links
+- [Documentation](https://www.metergraph.dev/docs/)
+- [CLI reference](https://github.com/metergraph/cli/blob/main/docs/reference.md) and [changelog](https://github.com/metergraph/cli/blob/main/CHANGELOG.md)
+- [Issues](https://github.com/metergraph/cli/issues)
+- [Contributing](https://github.com/metergraph/cli/blob/main/CONTRIBUTING.md) and [releasing](https://github.com/metergraph/cli/blob/main/RELEASING.md)
 ## License
-Apache-2.0. See [LICENSE](LICENSE).
+Apache-2.0. See [LICENSE](https://github.com/metergraph/cli/blob/main/LICENSE).