@wave-ai-os/wave-cli 0.1.66 → 0.1.68

package/README.md

@@ -14,7 +14,7 @@ See also:
 - Help output is human-readable and exits `0`; it does not emit a JSON error envelope.
 - `--readable` enables human formatting where a command supports it; `--json` forces the stable machine envelope where both flags are present.
 - No prompts, colors, or implicit interactive UX in this phase.
-- JWT forwarding is centralized.
+- Token handling is centralized and credentials are never printed in envelopes.
 
 ## Install
 
@@ -69,7 +69,10 @@ Notes:
 Required (from flags, stdin, env, config, or stored credentials):
 
 - `WAVE_API_TOKEN`
-- `WAVE_API_BASE_URL`
+
+The API base defaults to production: `https://api.ourwave.io`. Supply
+`--base-url`, stdin context, `WAVE_API_BASE_URL`/`WAVE_API_URL`, or config only
+when using a non-production environment.
 
 Organization-scoped data commands use the organization certified by the
 authenticated CLI token. `--organization-id` is the only local override.
@@ -92,7 +95,7 @@ Deterministic precedence:
 - stdin context (`--token-stdin` or `--auth-json-stdin`)
 - env vars (`WAVE_*`)
 - config file (`--config`, `WAVE_CONFIG_PATH`, or `~/.wave/config.json` when present)
-- failure with structured JSON error
+- production API default (`https://api.ourwave.io`)
 
 Config files are JSON objects using the same keys accepted by `--auth-json-stdin`, for example:
 
@@ -104,12 +107,12 @@ Config files are JSON objects using the same keys accepted by `--auth-json-stdin
 }
 ```
 
-For a persistent production login, configure `https://api.ourwave.io` as the
-GraphQL/API base and save only that API endpoint to the local CLI config. The
-token remains in the configured credential store, not in `config.json`:
+For a persistent production login, `wave login --save-base-url` saves the
+default production GraphQL/API base to the local CLI config. The token remains
+in the configured credential store, not in `config.json`:
 
 ```bash
-wave --base-url https://api.ourwave.io login --save-base-url
+wave login --save-base-url
 ```
 
 The API host is not the browser-login destination. When production returns a
@@ -164,6 +167,33 @@ Namespace taxonomy:
 
 `wave doctor` is read-only. It checks auth token resolution, organization ID resolution, base URL resolution, GraphQL reachability, API JSON response health, optional OpenAPI contract configuration, and CLI runtime integrity.
 
+### Fixed machine protocol
+
+Remote adapters can discover the complete supported surface through `wave api ls --json`.
+Its `data.operations` array is generated from the registered Commander action tree and
+includes every invocable command, JSON input/output schemas, examples, explicit
+classification, approval requirement, machine capabilities, CLI version, and a
+registry digest. `data.commands` is a compatibility projection derived from that same
+manifest.
+
+The only machine invocation shape is:
+
+```bash
+printf '%s' '{"id":"123"}' | wave --machine execute \
+  --operation projects.show \
+  --phase validate \
+  --input-json -
+```
+
+`validate` checks and normalizes JSON input without accessing a Wave record.
+`preview` is available only for writes and returns the exact command plus validated
+input. `execute` accepts no raw shell command or user-supplied CLI flags. Read and
+write execution requires a trusted, OAuth-bound machine-auth envelope; writes also
+require a server-managed approval bound to the operation, normalized-input digest,
+CLI version, registry digest, organization, and actor. Machine mode clears ambient
+Wave configuration and local credential storage before dispatch, so it cannot inherit
+a developer's local session.
+
 ## Commands
 
 Examples: