@hyperscale0/cli 1.0.330 → 1.0.332

package/AGENTS.md

@@ -56,18 +56,33 @@ the grant runs directly. A live action exits 3 with `agent_approval_required`
 and a browser link; a human approves it with their password. The CLI cannot
 approve its own work.
 
-`agent setup [claude-code|codex|cursor]` writes the Hyperscale MCP server into
-that host's project config and prints the file it wrote. The config reads a
-sandbox Product key from `HYPERSCALE_API_KEY` (`--key-env` names another
-variable) and never contains the key. `--oauth` writes browser sign-in instead.
+`agent setup [claude-code|codex|cursor]` uses the founder's CLI login to mint
+a named, sandbox-only agent credential (`agent_grant.create`). It keeps the
+token in the login's store, writes the host's MCP entry with
+`HYPERSCALE_TOKEN` as the bearer variable, and installs the skill into the
+host's skills folder. `agent token <host>` prints the stored token so the
+shell can export it as `HYPERSCALE_TOKEN`; MCP and the CLI then use the same
+door.
+`--oauth` writes browser sign-in instead and mints nothing.
+
+Credential order for product commands: `--api-key`, `HYPERSCALE_API_KEY`,
+`--token`, `HYPERSCALE_TOKEN`, then the stored login. A key never moves a
+command off the selected Product: a key for another Product exits 2 with
+`api_key_product_mismatch`, names both Products and says what to unset.
+`whoami` names the credential in use; `--verbose` adds grant and token ids.
+The Keychain item is keyed by the config folder, so two folders hold two
+logins; `doctor` names the item it reads.
 
 Every command accepts `--json`. Ordinary success is one JSON value on stdout;
 failure is an error object on stderr. Errors retain status, code, message,
 fix, details and available request, operation, receipt and trace IDs.
 JSON output has no ANSI codes, banners, spinners or prompts.
-Exit codes: 0 success, 1 failure, 2 usage error or HSX check or plan cannot
-proceed, 3 live action waiting for human approval, 4 not signed in or missing
-scope, 5 not found, 6 conflict such as a reused idempotency key.
+Exit codes: 0 success, 1 server refusal or failure, 2 usage (unknown command
+or option, or an argument, flag or input refused before any request; also an
+HSX check or plan that cannot proceed), 3 live action waiting for human
+approval, 4 not signed in or not allowed (401, 403), 5 not found (404), 6
+conflict with the current state (409). `refusals.js` holds the table;
+`help --json` prints it as `exitCodes`.
 
 `hsx watch --json` emits one JSON object per line with `type` set to `check`,
 `plan` or `error`. Check and plan events contain `data`; errors contain `error`.

package/README.md

@@ -252,14 +252,28 @@ run `npm install -g @hyperscale0/cli@latest`.
 
 `hyperscale help --json` returns the whole command tree with flags, examples,
 scopes and operations; `help --all` adds the advanced operations.
-Use `hyperscale <group> <command> --help` for one command. Exit codes are 0 for
-success, 1 for failure, 2 for a usage error or an HSX check or plan that cannot
-proceed, 3 for a live action waiting for approval, 4 for a missing login or
-scope, 5 for not found and 6 for a conflict.
+Use `hyperscale <group> <command> --help` for one command.
+
+| Exit | Meaning                                                                                                              |
+| ---- | -------------------------------------------------------------------------------------------------------------------- |
+| 0    | Success.                                                                                                             |
+| 1    | The server refused the request or could not finish it.                                                               |
+| 2    | Usage: an unknown command or option, an argument, flag or input refused before any request, or an HSX check failure. |
+| 3    | A live action is waiting for a person to approve it.                                                                 |
+| 4    | Not signed in, or this login or key may not do that (HTTP 401 or 403).                                               |
+| 5    | The thing named does not exist (HTTP 404).                                                                           |
+| 6    | The request conflicts with the current state (HTTP 409).                                                             |
+
+`help --json` lists the same table under `exitCodes`. A mistyped command or
+option suggests the nearest one, and every refusal carries a runnable `fix`.
 
 Set `HYPERSCALE_BASE_URL` for the API origin and `HYPERSCALE_ENVIRONMENT` for
 `sandbox` or `live`. `HYPERSCALE_TOKEN` supplies a login token and
 `HYPERSCALE_API_KEY` supplies a product key. Each has a matching command flag.
+Product commands use the first one set: `--api-key`, `HYPERSCALE_API_KEY`,
+`--token`, `HYPERSCALE_TOKEN`, then the stored login. `whoami` names it.
+`agent setup <host>` gives a coding agent its own sandbox token for both MCP
+and the CLI; see https://hyperscale0.ai/auth.md.
 
 The API defaults to `https://hyperscale0.ai`, which maps to the Launch and
 Build portals. `open` refuses other API origins because they do not identify