metergraph-cli 0.1.0 → 0.2.0-preview.1

package/README.md

@@ -1,8 +1,9 @@
 # metergraph-cli
 
-The Metergraph command line tool. This is a **development preview** (version 0.1.0).
+The Metergraph command line tool. Version `0.2.0-preview.1` is published on the
+`next` npm tag. The `latest` tag remains on `0.1.0`.
 
-Install the preview channel with npm or run it directly:
+Install the released preview channel with npm or run it directly:
 
 ```sh
 npx --yes metergraph-cli@next --help
@@ -10,18 +11,45 @@ npx --yes metergraph-cli@next doctor --json
 npm install -g metergraph-cli@next
 ```
 
-The installed command is `metergraph`. Pin `metergraph-cli@0.1.0` when you need
-this exact preview. Authentication and hosted setup are not included yet.
-
-This preview does two things:
+The installed command is `metergraph`. Pin `metergraph-cli@0.2.0-preview.1`
+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.
+- 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.
-
-It does not sign in or connect a workspace, and it does not query workspace
-telemetry or send application data. Sign in, workspace binding and hosted setup commands are planned as separate
-follow-up releases and are not part of this package yet.
+- `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.
 
 ## Requirements
 
@@ -41,10 +69,38 @@ 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]
 ```
 
 `--help`, `--version` and the `skill` commands work offline and make no network
-requests.
+requests. `login`, `logout`, `setup`, `verify` and the read commands are not in the published `0.1.0`
+package.
+
+### Exact trace verification
+
+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.
 
 ### doctor
 
@@ -148,9 +204,320 @@ does not match. It never downloads the skill or runs a remote script. A new skil
 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.
+
+```sh
+metergraph login --runtime local --url https://metergraph.example.com
+metergraph logout
+```
+
+| 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. Not with `--json`. |
+| `--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:
+
+```sh
+metergraph setup --runtime local --client codex --project /path/to/project
+```
+
+For a customer-local bundle, point setup at its installed origin and exact
+workspace:
+
+```sh
+metergraph setup --runtime local --deployment customer-local --url http://localhost:8080 --workspace 11111111-1111-4111-8111-111111111111 --confirm-prerequisites --client codex
+```
+
+`--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
+}
+```
+
+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`.
+
 ## Exit codes
 
-Exit codes are stable. Changing one is a breaking change.
+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`.
 
 | Code | Outcome | Meaning |
 | --- | --- | --- |
@@ -160,10 +527,18 @@ Exit codes are stable. Changing one is a breaking change.
 | 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. |
 | 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. 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. Nothing was changed. |
-| 9 | `filesystem_error` | Project files could not be read or written. Partial changes were rolled back unless the message says otherwise. |
+| 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. |
+| 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. |
+| 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. |
 
 ## JSON output
 
@@ -226,8 +601,8 @@ A successful `skill install`:
     "status": "installed",
     "source": {
       "name": "metergraph",
-      "revision": "sha256-90f7d8d78a5b",
-      "sha256": "90f7d8d78a5b0b7a57436f194222f0c73310b0b04201c297c8fbf0b00ad6bb3f"
+      "revision": "sha256-57b920677adf",
+      "sha256": "57b920677adf62759c7221629327192a2d16b7e6034f7948ffd96cee402d4891"
     },
     "discovery": "pending",
     "authenticated": false,
@@ -247,7 +622,57 @@ A successful `skill install`:
   `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
 
@@ -259,7 +684,7 @@ Without `--json`, results are printed as text on stdout and usage errors go to s
 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.md](SECURITY.md).
+to the network, so do not put secrets in a hostname. See [Security](#security).
 
 ## Deployment profiles
 
@@ -287,6 +712,36 @@ CLI never assumes such a server is hosted.
 - 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
@@ -295,13 +750,20 @@ npm run test:package      # npm pack into a temporary directory, clean install,
 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.1.0.tgz -- metergraph --version
+npx --yes --package=/path/to/metergraph-cli-0.2.0-preview.1.tgz -- metergraph --version
 ```
 
 Do not commit tarballs or other generated files.
@@ -310,8 +772,9 @@ Do not commit tarballs or other generated files.
 
 The source of truth is the public repository
 [github.com/metergraph/cli](https://github.com/metergraph/cli), licensed Apache-2.0.
-The first preview uses the `next` npm tag. Subsequent releases must pass the
-checks below before publication.
+`0.2.0-preview.1` 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
@@ -343,12 +806,12 @@ commit:
 - 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
+### First package bootstrap (completed for 0.1.0)
 
 npm trusted publishing is configured on a package that already exists, so the very
-first version cannot come from this workflow. Creating the package is a one time,
-human step that a Metergraph maintainer must approve and perform. Nothing in this
-repository automates it, and no npm token or secret is stored here.
+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.
@@ -377,15 +840,13 @@ Trusted publishing requires npm 11.5.1 or newer. The publish job checks this bef
 publishes. After the trusted publisher works, consider restricting the package to
 trusted publishing so that long lived tokens cannot publish it.
 
-### Remaining maintainer setup
+### Release configuration
 
-The source repository and license are settled. Before any automated release, a
-maintainer still has to:
+Before an automated publish, confirm the following settings are still in place:
 
-- complete the [first package bootstrap](#first-package-bootstrap);
-- configure the [trusted publisher](#trusted-publishing);
-- create the `npm-release` environment with required reviewers;
-- set the repository variable `METERGRAPH_CLI_PUBLISH_ENABLED` to `true`.
+- 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.
 
@@ -404,7 +865,13 @@ Releases from the workflow should show a provenance attestation that names
 
 ## Security
 
-See [SECURITY.md](SECURITY.md).
+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.
 
 ## License