@hyperscale0/cli 1.0.335 → 1.0.337

package/AGENTS.md

@@ -86,8 +86,12 @@ JSON output has no ANSI codes, banners, spinners or prompts.
 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;
+approval, 4 sign in (401, or no login found; Code `auth_required`), 5 not
+found (404), 6 conflict with the current state (409), 7 signed in but not
+allowed (403; the Code names the missing permission or scope, or
+`live_not_enabled` when `--environment live` asks for live the company does
+not have yet). New codes take
+the next number; a code never changes meaning. `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`,

package/README.md

@@ -55,8 +55,9 @@ way. The browser signup and its email link keep working.
 `hyperscale auth logout` removes the local login. Add `--revoke` to revoke the
 token too. Tokens and saved requests use macOS Keychain when available, with
 an owner-only file fallback (mode 0600). `HYPERSCALE_CREDENTIAL_STORE=file`
-selects file storage. `HYPERSCALE_CONFIG_DIR` or `--config-dir <path>` sets its
-directory.
+selects file storage. `HYPERSCALE_CONFIG_DIR` or `--config-dir <path>` sets the
+settings folder. The token stays in the Keychain, one entry per folder, so
+deleting the folder does not sign out: run `hyperscale auth logout` first.
 
 ## Work on a product
 
@@ -129,7 +130,9 @@ step that fails:
 Each customer is created, given a sandbox account and funded first. `create`
 makes an object, `run` runs an action on it, `fund` adds sandbox money,
 `advance` moves the sandbox clock (`30m`, `4h`, `2d`, `1w` or an ISO time) and
-`expect` checks balances. A plain balance compares to `available`; an object
+`expect` checks balances. The clock is the Product's, shared by every record in
+it, so `scenario run` names its advances before the first step. The starter
+`init` writes takes one payment and never moves the clock. A plain balance compares to `available`; an object
 can name `available`, `settled` or `pending`. Amounts are major units, as
 `fund` takes them (`"750"` or `"750.50"` in SAR), in money fields and action
 input too; the runner sends the API minor units. Funding and actions need the
@@ -254,15 +257,16 @@ run `npm install -g @hyperscale0/cli@latest`.
 scopes and operations; `help --all` adds the advanced operations.
 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).                                                             |
+| 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    | Sign in: no login, or the login or key was not accepted (HTTP 401). Code `auth_required` when the CLI finds no login. |
+| 5    | The thing named does not exist (HTTP 404).                                                                            |
+| 6    | The request conflicts with the current state (HTTP 409).                                                              |
+| 7    | Signed in, but this login, its role or the key may not do that (HTTP 403). The Code names the missing permission.     |
 
 `help --json` lists the same table under `exitCodes`. A mistyped command or
 option suggests the nearest one, and every refusal carries a runnable `fix`.