@zeyos/client 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -3,6 +3,25 @@
 Notable changes to `@zeyos/client` and `@zeyos/cli`. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## 0.1.1
+
+### `@zeyos/client`
+- `oauth2.buildAuthorizationUrl()` now includes the `scope` parameter when provided (previously dropped).
+- Retry timing hardened: an empty/whitespace `Retry-After` header falls back to exponential backoff instead of retrying instantly, and an already-aborted signal reliably stops a zero-delay retry.
+- `normalizeListResult()` preserves a numeric-string `count` (e.g. `"17"`), matching `normalizeCountResult()`.
+
+### `@zeyos/cli` (`zeyos`)
+- Added `--version` / `-v`.
+- Fixed the `--key=value` argument form, which was previously parsed as an unknown flag and silently ignored (e.g. `--filter='{...}'`).
+- YAML output now quotes ambiguous scalar strings (`true`, `false`, `null`, `yes`/`no`, and numeric-looking strings) so downstream YAML parsers don't re-interpret them.
+- `describe`, `resources`, and `skills` help text now documents the global `--json` / `--yaml` / `--help` options.
+- `skills install` reworked into a multi-agent installer: targets `claude`, `codex`, `opencode`, `droid`, `pi`, and a generic `agents` layout; adds `--global`/`--local` scope, `--dir <path>` for an explicit directory, an interactive agent/scope picker (with a ZeyOS banner) when run bare, `-y`/`--yes` and `--no-logo` to skip prompts/banner, and a `--json`/`--yaml` install summary.
+- `login` now prints the local callback URL before prompting for the application ID/secret, so it can be registered as the OAuth app's redirect URI.
+
+### Docs
+- Rewrote the top-level `README.md` into a full guide with CLI, JavaScript client, login/OAuth, and coding-agent examples.
+- Documentation accuracy fixes: accounts use `lastname` (no `name` field); updates accept the flat `{ ID, ...fields }` form (explicit `body` optional); clarified that the schema's `(required)` marker means `NOT NULL` (most such fields have defaults — `currency` on accounts is the real exception); fixed cross-links and a duplicate tutorial sidebar prefix.
+
 ## 0.1.0 — Initial release
 
 ### `@zeyos/client`

package/README.md

@@ -202,7 +202,7 @@ zeyos <command> [options] [args…]
 | `delete <resource> <id>` | Delete a record (`rm`/`remove` aliases) | `zeyos delete ticket 42 --force` |
 | `resources` | List resource types the CLI exposes | `zeyos resources --json` |
 | `describe <resource>` | Show a resource's fields, types and enums | `zeyos describe ticket` |
-| `skills <list\|show\|install>` | Manage bundled coding-agent skills | `zeyos skills install --target claude` |
+| `skills <list\|show\|install>` | Manage bundled coding-agent skills | `zeyos skills install --target claude --global` |
 
 **Global options** (work on every command): `--json`, `--yaml`, `--no-color`, `-h/--help`, `-v/--version`.
 
@@ -351,11 +351,28 @@ ZeyOS ships **agent skills** — curated instructions and query playbooks that t
 
 ```bash
 zeyos skills list                              # see what's available
-zeyos skills install --target claude           # copies skills into .claude/skills/
-zeyos skills install zeyos-work-management      # or install just one
+zeyos skills install                           # interactive: pick an agent, then local vs. global
+zeyos skills install --target claude --global  # or skip the prompts with flags
+zeyos skills install zeyos-work-management      # install just one skill
 ```
 
-`--target claude` writes to `.claude/skills/`, `--target codex` writes to `.codex/skills/`; with no `--target`, it auto-detects an existing `.claude`/`.codex` directory (defaulting to Claude). Shared reference docs are installed alongside so the skills' cross-links resolve. Point your agent at the install directory.
+Run bare, `install` shows the ZeyOS banner and asks **(a)** which coding agent to target and **(b)** whether to install for this project or globally. Flags skip the prompts:
+
+- `--target <agent>` — `claude`, `codex`, `opencode`, `droid`, `pi`, or `agents` (auto-detected when omitted)
+- `--global` / `--local` — install into the agent's home directory or just this project (default `--local`)
+- `--dir <path>` — install into any directory you choose (overrides `--target`)
+- `-y`/`--yes` — skip all prompts and use flags + defaults (also implied when piped non-interactively)
+
+| Agent | local | global |
+|-------|-------|--------|
+| `claude` | `.claude/skills/` | `~/.claude/skills/` |
+| `codex` | `.codex/skills/` | `~/.codex/skills/` |
+| `opencode` | `.opencode/skills/` | `~/.config/opencode/skills/` |
+| `droid` | `.factory/skills/` | `~/.factory/skills/` |
+| `pi` | `.pi/skills/` | `~/.pi/agent/skills/` |
+| `agents` | `.agents/skills/` | `~/.agents/skills/` |
+
+Shared reference docs are installed alongside so the skills' cross-links resolve. Point your agent at the install directory.
 
 Bundled skills:
 

package/docs/02-javascript-client/01-getting-started.md

@@ -65,6 +65,21 @@ The returned `client` object exposes:
 - **`client.auth`** -- Token management (`getTokenSet`, `setTokenSet`, `clearTokenSet`)
 - **`client.metadata`** -- Read-only info about the generated client (`generatedAt` timestamp, `services` array)
 
+Alongside the `createZeyosClient` factory, the package exports a few named helpers and error types you can import directly:
+
+```js
+import {
+  createZeyosClient,
+  MemoryTokenStore,        // in-memory token store (or implement get()/set() yourself)
+  ZeyosApiError,           // thrown on non-2xx responses
+  ZeyosValidationError,    // thrown by pre-flight validation (validate: true)
+  normalizeListResult,     // normalise a list response to { data, count? }
+  normalizeCountResult,    // normalise a count response to a number
+  normalizeTokenSet,       // normalise a raw token object to a TokenSet
+  tokenResponseToTokenSet, // map an OAuth token response to a TokenSet
+} from '@zeyos/client';
+```
+
 ## Platform Configuration
 
 The `platform` option tells the client where your ZeyOS instance lives. There are three ways to specify it:

package/docs/03-cli/01-getting-started.md

@@ -118,11 +118,12 @@ zeyos describe accounts --json
 
 ## Install Agent Skills
 
-If you are driving the CLI from a coding agent (Claude, Codex, …), install the bundled ZeyOS skill packs into your project so the agent picks up the right query conventions:
+If you are driving the CLI from a coding agent (Claude Code, Codex, opencode, Factory Droid, pi, …), install the bundled ZeyOS skill packs so the agent picks up the right query conventions:
 
 ```bash
 zeyos skills list                 # see the available skills
-zeyos skills install              # copy them into .claude/skills (or .codex)
+zeyos skills install              # interactive: pick an agent, then local vs. global
+zeyos skills install --target claude --global   # or skip the prompts with flags
 ```
 
 See the [Commands Reference](./02-commands.md#skills) for details.

package/docs/03-cli/02-commands.md

@@ -370,7 +370,7 @@ Foreign keys are shown as `→ <table>`, and enum fields list their valid values
 
 ## skills
 
-Discover and install the bundled ZeyOS agent skill packs into the local project, so a coding agent (Claude, Codex, …) operates against ZeyOS with the right conventions out of the box.
+Discover and install the bundled ZeyOS agent skill packs into any coding agent, so the agent (Claude Code, Codex, opencode, Factory Droid, pi, …) operates against ZeyOS with the right conventions out of the box.
 
 ```
 # List the bundled skills
@@ -379,19 +379,43 @@ zeyos skills list
 # Print a skill's instructions
 zeyos skills show zeyos-work-management
 
-# Install all skills (or named ones) into the project
+# Install — interactive: pick a coding agent, then local vs. global
 zeyos skills install
-zeyos skills install zeyos-billing-insights --target claude
+
+# Install non-interactively with flags
+zeyos skills install --target claude --global       # all projects
+zeyos skills install --target opencode --local      # this project only
+zeyos skills install zeyos-billing-insights -y      # one skill, defaults
+zeyos skills install --dir ./vendor/skills          # any directory
 ```
 
+Run bare, `install` prints the ZeyOS banner and prompts for **(a)** which coding agent to target and **(b)** whether to install for this project or globally for every project. Pass `--target` and/or `--global`/`--local` to skip the matching prompt; pass `-y`/`--yes` (or pipe non-interactively) to skip all prompts and use flags plus sensible defaults.
+
 Options for `install`:
 
 | Option | Description |
 |--------|-------------|
-| `--target claude\|codex` | Where to install (default: auto-detect, fallback `.claude/skills`) |
+| `--target <agent>` | Coding agent: `claude`, `codex`, `opencode`, `droid`, `pi`, `agents` (prompted when omitted; otherwise auto-detected) |
+| `--global` | Install into the agent's home directory (all projects) |
+| `--local` | Install into the current project (default) |
+| `--dir <path>` | Install into an explicit directory (overrides `--target`) |
 | `--force` | Overwrite existing skill folders |
-
-Skills are copied into `<target>/skills/<name>/`, with the shared reference files installed alongside (`<target>/skills/shared/`) so the skills' `../shared/…` links resolve.
+| `-y`, `--yes` | Skip prompts and use flags / sensible defaults |
+| `--no-logo` | Don't print the ZeyOS banner |
+| `--json` / `--yaml` | Print a machine-readable install summary (also silences the banner) |
+
+Per-agent skill directories:
+
+| Agent | `--local` | `--global` |
+|-------|-----------|------------|
+| `claude` | `.claude/skills/` | `~/.claude/skills/` |
+| `codex` | `.codex/skills/` | `~/.codex/skills/` |
+| `opencode` | `.opencode/skills/` | `~/.config/opencode/skills/` |
+| `droid` | `.factory/skills/` | `~/.factory/skills/` |
+| `pi` | `.pi/skills/` | `~/.pi/agent/skills/` |
+| `agents` | `.agents/skills/` | `~/.agents/skills/` |
+
+Skills are copied into `<dir>/<name>/`, with the shared reference files installed alongside (`<dir>/shared/`) so the skills' `../shared/…` links resolve.
 
 ---
 

package/docs/04-agent-workflows/01-agent-quickstart.md

@@ -29,7 +29,8 @@ Before doing real work, install the bundled skill packs so the agent picks up Ze
 
 ```bash
 zeyos skills list                 # see what's available
-zeyos skills install              # install all into .claude/skills (or .codex)
+zeyos skills install              # interactive: pick an agent (claude, codex, opencode, droid, pi…), then local/global
+zeyos skills install --target claude --global -y   # or non-interactively with flags
 ```
 
 This is the recommended entry point for an agent: the skills encode how to resolve names to IDs, which resource to query first, and how to escalate from the CLI to `@zeyos/client`.

package/docs/intro.md

@@ -88,7 +88,7 @@ Across the CLI, JavaScript client, and sample applications, the same operational
 
 - Prefer `filters` in JavaScript client code for compatibility across scalar and foreign-key fields.
 - Include `visibility: 0` unless you intentionally want archived or deleted records.
-- Use an explicit `body` object for updates that also pass a path parameter such as `ID`.
+- For updates, pass changed fields alongside the `ID` directly (`{ ID, status }`) or wrap them in an explicit `body` object (`{ ID, body: { status } }`) — both work; the explicit `body` is only needed to disambiguate a payload field that collides with a reserved control key.
 - Treat `extdata` and `expand` as separate features:
   - `extdata` includes custom fields
   - `expand` inlines JSON or binary columns

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeyos/client",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Dependency-light JavaScript client for ZeyOS OpenAPI services",
   "type": "module",
   "license": "MIT",