epismo 1.7.1 → 1.9.0

package/README.md

@@ -42,15 +42,25 @@ The npm package contains a dependency-free JavaScript launcher and all supported
 ```sh
 epismo login
 epismo workspace list
-epismo workspace use WORKSPACE_ID # optional: save a default workspace
-epismo playbook search --query onboarding
+epismo workspace use acme # optional: save a default workspace by ID or handle
+epismo --workspace acme playbook search onboarding
+epismo playbook resource list --kind cli
+epismo playbook init --title Onboarding > playbook.json
+epismo playbook create --definition @playbook.json
 ```
 
 Run `epismo --help` for command groups, or append `--help` to any group or command for its options.
 
+Use `epismo examples` for common workflows, `epismo doctor` to inspect local setup, and `epismo completion zsh` (or `bash`, `fish`, `powershell`) to install shell completion.
+The source man page is available at [`docs/epismo.1`](docs/epismo.1).
+
 ## Output and input
 
-Successful commands write JSON to stdout; warnings and errors write JSON to stderr. This keeps output easy to use from scripts and agents.
+Successful commands write one JSON document to stdout. Progress events, warnings, and errors are written to stderr as newline-delimited JSON (one compact JSON object per line). This keeps output easy to use from scripts and agents while allowing interactive commands to report progress.
+
+CLI JSON field names and enum values use `snake_case`. Machine-readable warning and error codes use `SCREAMING_SNAKE_CASE`. Input supplied through `--input` accepts both `snake_case` and `camelCase` fields at every nesting level. Do not provide both spellings of the same field in one object. OAuth protocol fields retain their standard wire names such as `access_token` and `grant_type`.
+
+Interactive prompts such as the email-code input prompt are plain terminal text. All machine-readable diagnostic records remain one-line JSON objects.
 
 ```json
 {
@@ -62,6 +72,12 @@ Successful commands write JSON to stdout; warnings and errors write JSON to stde
 }
 ```
 
+Progress and warnings use a common event envelope:
+
+```json
+{"event":{"level":"info","code":"BROWSER_WAITING","message":"Waiting for authorization in your browser...","details":{"timeout_seconds":300}}}
+```
+
 Commands that accept a request body support inline JSON, a file, or stdin:
 
 ```sh
@@ -69,7 +85,32 @@ epismo playbook create --input @playbook.json
 epismo case record append CASE_ID --input - < record.json
 ```
 
-Explicit flags override fields supplied through `--input`. Mutations create an idempotency key automatically unless you provide `--idempotency-key` or `idempotencyKey` in the input.
+Explicit flags override fields supplied through `--input`. Mutations create an idempotency key automatically unless you provide `--idempotency-key` or `idempotency_key` in the input.
+
+## Everyday terminal use
+
+The default output is JSON for scripts and agents. Choose a human-friendly output format when working interactively:
+
+```sh
+epismo workspace list --output table
+epismo credit checkout --quantity 500 --output value --field checkout_url
+epismo task list --all --output jsonl
+epismo playbook search --query onboarding --jq '.playbooks[] | .id'
+```
+
+Global options may appear before or after the command:
+
+```sh
+epismo --workspace acme playbook list
+epismo -w acme task list --all
+EPISMO_WORKSPACE=acme epismo case list
+```
+
+Workspace references accept an exact ID or unique handle. The effective workspace is chosen in this order: `--workspace`, `EPISMO_WORKSPACE`, a workspace-scoped token, then the saved default workspace. A scoped token cannot grant access outside its scope.
+
+`--dry-run` previews archive, delete, revoke, close, ACL replacement, and workspace-clear operations without sending a request. In an interactive terminal those operations ask for confirmation; pass `--yes` to skip that prompt in scripts that allocate a TTY.
+
+`--input` also works on list/search commands for agent workflows; there it supplies query parameters rather than a request body.
 
 ## Authentication and configuration
 
@@ -94,6 +135,8 @@ sh scripts/sync-openapi.sh
 
 Do not edit the snapshot manually. Its `info.version` represents API compatibility (for example, `1.0.0` for `/v1`), not the CLI release version. Contract tests ensure remote commands and query options remain compatible with the API.
 
+The OpenAPI snapshot describes the server wire format, which uses `camelCase` for Epismo fields. The CLI translates those fields to and from its public `snake_case` representation at the process boundary.
+
 ## Develop
 
 The CLI runtime uses only the Go standard library.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "epismo",
-  "version": "1.7.1",
+  "version": "1.9.0",
   "description": "Dependency-free CLI for discovering, authoring, and coordinating reusable AI Playbooks.",
   "type": "module",
   "license": "Apache-2.0",