@zeyos/client 0.1.0

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

@@ -0,0 +1,407 @@
+---
+sidebar_label: Commands Reference
+---
+
+# Commands Reference
+
+Complete reference for every CLI command, with options and examples.
+
+## Global Options
+
+These options work with any command:
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output as formatted JSON |
+| `--yaml` | Output as YAML |
+| `--no-color` | Disable ANSI color output |
+| `-h`, `--help` | Show help for a command |
+
+---
+
+## login
+
+Authenticate with a ZeyOS instance via OAuth 2.0 authorization code flow.
+
+```
+zeyos login [options]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--base-url <url>` | ZeyOS platform URL |
+| `--client-id <id>` | OAuth application ID |
+| `--secret <secret>` | OAuth application secret |
+| `--scope <scope>` | OAuth scope |
+| `--port <port>` | Local callback port (default: `9005`) |
+| `--global` | Save credentials to global config |
+| `--force` | Overwrite existing credentials |
+| `--clean` | Discard saved config and re-prompt for everything |
+| `--manual` | Don't open browser; paste code manually |
+
+**Examples:**
+
+```bash
+# Interactive login (prompts for missing values)
+zeyos login
+
+# Pre-fill connection values; the OAuth browser/code step still runs
+zeyos login --base-url https://cloud.zeyos.com/demo \
+            --client-id myapp --secret "$ZEYOS_CLIENT_SECRET"
+
+# Start fresh, ignore any saved credentials
+zeyos login --clean
+
+# Manual mode (useful in SSH / headless environments)
+zeyos login --manual
+```
+
+:::info
+When values are not provided as flags, the CLI prompts interactively for the ZeyOS URL, application ID, and application secret. The secret prompt does not echo input. For CI or fully unattended agents, provide `ZEYOS_BASE_URL`, `ZEYOS_TOKEN`, and optionally `ZEYOS_REFRESH_TOKEN`, `ZEYOS_CLIENT_ID`, and `ZEYOS_CLIENT_SECRET` through the environment instead of running `zeyos login`.
+:::
+
+---
+
+## logout
+
+Revoke the stored token and clear saved credentials.
+
+```
+zeyos logout [--global]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--global` | Clear global credentials instead of local |
+
+**Examples:**
+
+```bash
+zeyos logout          # Clear local .zeyos/auth.json tokens
+zeyos logout --global # Clear ~/.config/zeyos/credentials.json tokens
+```
+
+---
+
+## whoami
+
+Show information about the currently authenticated user.
+
+```
+zeyos whoami [--json|--yaml]
+```
+
+**Examples:**
+
+```bash
+zeyos whoami          # Table output
+zeyos whoami --json
+zeyos whoami --show-token --json   # explicitly include the current access token
+```
+
+---
+
+## list
+
+Query and list records for a resource with filtering, sorting, and pagination.
+
+```
+zeyos list <resource> [options]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--fields <fields>` | Field selection — comma-separated, JSON object, or JSON array (see below) |
+| `--filter <json>` | Filter criteria — JSON object |
+| `--sort <fields>` | Sort fields, comma-separated (prefix `+` asc, `-` desc) |
+| `--limit <n>` | Maximum records to return (default: `50`) |
+| `--offset <n>` | Skip the first n records |
+| `--expand <fields>` | Expand JSON/binary columns (e.g. binfile, items) |
+| `--extdata` | Include extended data fields |
+| `--json` | JSON output |
+| `--yaml` | YAML output |
+
+**Fields format:**
+
+The `--fields` option supports three formats:
+
+| Format | Example |
+|--------|---------|
+| Comma-separated | `--fields ID,name,status` |
+| JSON object (with aliases) | `--fields '{"Name":"lastname","City":"contact.city"}'` |
+| JSON array | `--fields '["ID","name","status"]'` |
+
+**Examples:**
+
+```bash
+# List tickets with default configured fields
+zeyos list tickets
+
+# Custom filters
+zeyos list tickets --filter '{"status":1,"priority":3}'
+
+# Specify fields with aliases
+zeyos list accounts --fields '{"Name":"lastname","City":"contact.city"}'
+
+# Comma-separated fields
+zeyos list tickets --fields ID,name,status,priority
+
+# Sort by multiple columns
+zeyos list tickets --sort "+name,-lastmodified"
+
+# Pagination
+zeyos list tickets --limit 10 --offset 20
+
+# Include extended data
+zeyos list tickets --extdata
+
+# JSON output for scripting
+zeyos list tickets --json | jq length
+```
+
+:::tip Pagination Info
+When results fill the page limit, the CLI makes a second API call to get the total count and displays:
+```
+Showing 1–10 of 47  (--offset 10 for next page)
+```
+:::
+
+---
+
+## count
+
+Count records for a resource, with optional filtering. Returns a plain number by default.
+
+```
+zeyos count <resource> [options]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--filter <json>` | Filter criteria — JSON object |
+| `--json` | Output as `{"count": N}` |
+| `--yaml` | YAML output |
+
+**Examples:**
+
+```bash
+# Total tickets
+zeyos count tickets
+# → 47
+
+# Filtered count
+zeyos count tickets --filter '{"status":1}'
+# → 12
+
+# JSON output for scripting
+zeyos count accounts --json
+# → {"count": 156}
+```
+
+---
+
+## get
+
+Fetch a single record by ID.
+
+```
+zeyos get <resource> <id> [options]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--fields <fields>` | Field selection — comma-separated, JSON object, or JSON array |
+| `--extdata` | Include extended data fields |
+| `--tags` | Include tags |
+| `--all` | Fetch all data (extdata + tags + all fields) |
+| `--json` | JSON output |
+| `--yaml` | YAML output |
+
+**Aliases:** `show`
+
+**Examples:**
+
+```bash
+# Get a ticket with configured fields
+zeyos get ticket 42
+
+# Include extended data
+zeyos get ticket 42 --extdata
+
+# Include tags
+zeyos get ticket 42 --tags
+
+# Include both extdata and tags
+zeyos get ticket 42 --extdata --tags
+
+# Get everything — all fields, extdata, and tags
+zeyos get ticket 42 --all
+
+# JSON output
+zeyos get account 15 --json
+
+# Using the alias
+zeyos show ticket 42
+```
+
+:::info Date Formatting
+Date fields like `duedate`, `lastmodified`, and `creationdate` are automatically formatted as `YYYY-MM-DD` in table/record output. Raw Unix timestamps are preserved in JSON and YAML output. The format is configurable via `dateFormat` in your auth config file.
+:::
+
+---
+
+## create
+
+Create a new record. Fields can be provided as a JSON blob or as individual flags.
+
+```
+zeyos create <resource> [--data <json>] [--field value ...]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--data <json>` | Complete record as a JSON string |
+| `--<field> <value>` | Set individual field (any unknown flag becomes a field) |
+
+**Examples:**
+
+```bash
+# Using --data JSON
+zeyos create ticket --data '{"name":"Fix login bug","status":0,"priority":3}'
+
+# Using individual field flags
+zeyos create ticket --name "Fix login bug" --status 0 --priority 3
+
+# Create an account (accounts use --lastname, not --name)
+zeyos create account --lastname "ACME Corp" --currency EUR --visibility 0
+
+# JSON output (returns the created record)
+zeyos create ticket --name "New feature" --json
+```
+
+:::info Type Coercion
+Field values are automatically coerced: `"true"` → `true`, `"false"` → `false`, `"null"` → `null`, and numeric strings become numbers. This means `--status 0` sends the integer `0`, not the string `"0"`.
+:::
+
+---
+
+## update
+
+Update an existing record by ID. Same input modes as `create`.
+
+```
+zeyos update <resource> <id> [--data <json>] [--field value ...]
+```
+
+**Aliases:** `edit`
+
+**Examples:**
+
+```bash
+# Using --data JSON
+zeyos update ticket 42 --data '{"status":4}'
+
+# Using field flags
+zeyos update ticket 42 --status 4 --priority 2
+
+# Update account name (accounts use --lastname, not --name)
+zeyos update account 15 --lastname "ACME Corporation"
+```
+
+---
+
+## delete
+
+Delete a record by ID. Prompts for confirmation by default.
+
+```
+zeyos delete <resource> <id> [--force]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--force` | Skip confirmation prompt |
+
+**Aliases:** `rm`, `remove`
+
+**Examples:**
+
+```bash
+# Interactive confirmation
+zeyos delete ticket 42
+
+# Skip confirmation
+zeyos delete ticket 42 --force
+
+# Using aliases
+zeyos rm ticket 42
+zeyos remove ticket 42
+```
+
+---
+
+## resources
+
+List all curated CLI resources and their operations. This is the authoritative boundary for what the CLI supports directly.
+
+```
+zeyos resources
+```
+
+Shows a table of all CLI-supported resource types and available operations.
+
+---
+
+## describe
+
+Show a resource's schema — fields, types, foreign keys and enum values — from the generated schema. Runs **offline** (no login required), so an agent can discover the data model before making any call.
+
+```
+# Field/type/enum/foreign-key listing for a resource
+zeyos describe tickets
+
+# Machine-readable schema
+zeyos describe accounts --json
+```
+
+Foreign keys are shown as `→ <table>`, and enum fields list their valid values (e.g. `status` → `0=NOTSTARTED 1=AWAITINGACCEPTANCE …`). The operations available for the resource are listed at the bottom.
+
+---
+
+## 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.
+
+```
+# List the bundled skills
+zeyos skills list
+
+# Print a skill's instructions
+zeyos skills show zeyos-work-management
+
+# Install all skills (or named ones) into the project
+zeyos skills install
+zeyos skills install zeyos-billing-insights --target claude
+```
+
+Options for `install`:
+
+| Option | Description |
+|--------|-------------|
+| `--target claude\|codex` | Where to install (default: auto-detect, fallback `.claude/skills`) |
+| `--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.
+
+---
+
+## Command Aliases
+
+| Alias | Equivalent |
+|-------|-----------|
+| `show` | `get` |
+| `edit` | `update` |
+| `rm` | `delete` |
+| `remove` | `delete` |
+| `resource` | `resources` |
+| `skill` | `skills` |

package/docs/03-cli/03-configuration.md

@@ -0,0 +1,220 @@
+---
+sidebar_label: Configuration
+---
+
+# Configuration
+
+The CLI uses a layered configuration system for credentials, output preferences, and per-resource field display.
+
+:::info Coverage Boundary
+These settings apply to the CLI's curated resource registry. If you need a resource or request shape outside that registry, switch to [`@zeyos/client`](../02-javascript-client/01-getting-started.md).
+:::
+
+## Credential Cascade
+
+Credentials are resolved from three sources in priority order:
+
+| Priority | Source | Location |
+|----------|--------|----------|
+| 1 (highest) | Environment variables | `ZEYOS_BASE_URL`, `ZEYOS_TOKEN`, etc. |
+| 2 | Local config file | `.zeyos/auth.json` (walks up from CWD) |
+| 3 (lowest) | Global config file | `~/.config/zeyos/credentials.json` |
+
+Configuration is merged from global, then local, then environment variables. Higher-priority sources override individual fields from lower-priority sources. For example, setting `ZEYOS_TOKEN` as an environment variable overrides the stored token while still allowing `baseUrl` and client credentials to come from a config file.
+
+## Environment Variables
+
+| Variable | Maps to | Description |
+|----------|---------|-------------|
+| `ZEYOS_BASE_URL` | `baseUrl` | ZeyOS platform URL |
+| `ZEYOS_INSTANCE` | `instance` | ZeyOS instance name |
+| `ZEYOS_CLIENT_ID` | `clientId` | OAuth application ID |
+| `ZEYOS_CLIENT_SECRET` | `clientSecret` | OAuth application secret |
+| `ZEYOS_TOKEN` | `accessToken` | Access token |
+| `ZEYOS_REFRESH_TOKEN` | `refreshToken` | Refresh token |
+
+**Example:**
+
+```bash
+# Use environment variables for CI/CD pipelines
+export ZEYOS_BASE_URL="https://cloud.zeyos.com/demo"
+export ZEYOS_TOKEN="your-access-token"
+
+zeyos list tickets
+```
+
+If you want the CLI to auto-refresh expired access tokens, also provide `ZEYOS_CLIENT_ID`, `ZEYOS_CLIENT_SECRET`, and a refresh token via config or environment variables.
+
+## Local Config File
+
+The CLI stores credentials in `.zeyos/auth.json`, located in your project directory. When resolving config, the CLI walks up from the current working directory (like Git does for `.gitconfig`) until it finds a `.zeyos/auth.json` file.
+
+**File format:**
+
+```json
+{
+  "baseUrl": "https://cloud.zeyos.com/demo",
+  "clientId": "myapp",
+  "clientSecret": "...",
+  "accessToken": "...",
+  "refreshToken": "...",
+  "expiresAt": 1735568880,
+  "refreshTokenExpiresAt": 1738160880,
+  "dateFormat": "YYYY-MM-DD"
+}
+```
+
+This file is created automatically when you run `zeyos login`.
+
+`expiresAt` and `refreshTokenExpiresAt` are stored as Unix timestamps in **seconds**.
+
+:::warning
+Always add `.zeyos/auth.json` to your `.gitignore` — it contains access tokens and secrets:
+```gitignore
+.zeyos/auth.json
+```
+:::
+
+## Global Config File
+
+For credentials shared across all projects, use the global config:
+
+```bash
+zeyos login --global
+```
+
+This saves to `~/.config/zeyos/credentials.json` (same format as the local file). Local config values override global values field-by-field, so a project can override only the fields it needs.
+
+## Resource Field Configuration
+
+Customize which fields are displayed for each resource type. The CLI supports per-resource configs that control the `list` and `get` output.
+
+### Config Cascade
+
+Resource configs are also resolved in priority order:
+
+| Priority | Location | Purpose |
+|----------|----------|---------|
+| 1 (highest) | `.zeyos/api/<resource>.json` | Project-specific overrides |
+| 2 | `~/.zeyos/api/<resource>.json` | User-wide preferences |
+| 3 (lowest) | `cli/config/<resource>.json` | Shipped defaults |
+
+### Config Format
+
+```json
+{
+  "list": {
+    "fields": {
+      "ID": "ID",
+      "Name": "lastname",
+      "City": "contact.city",
+      "Country": "contact.country",
+      "Agent": "assigneduser.name",
+      "Modified": "lastmodified"
+    }
+  },
+  "get": {
+    "fields": [
+      "ID", "name", "status", "priority",
+      "description", "duedate", "lastmodified"
+    ],
+    "params": {
+      "extdata": 1,
+      "tags": 1
+    }
+  }
+}
+```
+
+**`list.fields`** — An object mapping display aliases to API field paths. Keys become column headers; values are the actual API fields (supports dot-notation for joins).
+
+**`get.fields`** — An array of field names to display in the detail view. Use `--all` to override and show everything.
+
+**`get.params`** — An object of query parameters to include by default. These are sent as URL query parameters (e.g. `?extdata=1&tags=1`) and control which additional data sections are returned. Common params: `extdata` (extended data fields), `tags` (record tags).
+
+:::note
+The `--extdata` and `--tags` CLI flags override the corresponding values in `get.params`. For example, running `zeyos get ticket 42` with `"params": {"extdata": 1}` in the config is equivalent to running `zeyos get ticket 42 --extdata`.
+:::
+
+### Shipped Defaults
+
+The CLI ships with configs for commonly used resources:
+
+| File | Resource |
+|------|----------|
+| `cli/config/ticket.json` | Tickets |
+| `cli/config/account.json` | Accounts |
+| `cli/config/task.json` | Tasks |
+| `cli/config/project.json` | Projects |
+| `cli/config/item.json` | Items |
+
+Resources without a config file return all fields from the API.
+
+:::tip Customizing for Your Project
+Create `.zeyos/api/ticket.json` in your project to override the default field display:
+```bash
+mkdir -p .zeyos/api
+```
+```json title=".zeyos/api/ticket.json"
+{
+  "list": {
+    "fields": {
+      "ID": "ID",
+      "Title": "name",
+      "Client": "account.lastname",
+      "Sprint": "extdata.sprint",
+      "Due": "duedate"
+    }
+  }
+}
+```
+:::
+
+## Date Formatting
+
+Unix timestamps in table and record output are automatically formatted as human-readable dates. Configure the format in your auth config file:
+
+```json title=".zeyos/auth.json"
+{
+  "baseUrl": "https://cloud.zeyos.com/demo",
+  "dateFormat": "YYYY-MM-DD HH:mm"
+}
+```
+
+**Available tokens:**
+
+| Token | Output | Example |
+|-------|--------|---------|
+| `YYYY` | 4-digit year | `2026` |
+| `MM` | 2-digit month | `03` |
+| `DD` | 2-digit day | `02` |
+| `HH` | 2-digit hour (24h) | `14` |
+| `mm` | 2-digit minute | `30` |
+| `ss` | 2-digit second | `00` |
+
+**Default format:** `YYYY-MM-DD`
+
+Date formatting only affects table and record output. JSON and YAML output always preserves raw Unix timestamps for programmatic use.
+
+**Auto-detected date fields:** `duedate`, `lastmodified`, `creationdate`, `created`, `date`, `startdate`, `enddate`, and any field name ending in `date` or `modified`.
+
+## Output Formats
+
+| Flag | Format | Best For |
+|------|--------|----------|
+| *(none)* | Formatted table | Human reading in the terminal |
+| `--json` | Pretty-printed JSON | Scripting, piping to `jq`, APIs |
+| `--yaml` | YAML | Config files, readability |
+
+**Table output** is the default — it shows aligned columns with optional date formatting and pagination info.
+
+**JSON output** preserves all raw data exactly as returned by the API, including numeric timestamps and null values.
+
+**YAML output** is similar to JSON but more readable for nested structures.
+
+```bash
+# Compare the outputs
+zeyos get ticket 42           # Table with formatted dates
+zeyos get ticket 42 --json    # Raw JSON with Unix timestamps
+zeyos get ticket 42 --yaml    # YAML with readable structure
+```

package/docs/03-cli/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "CLI",
+  "position": 4,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "description": "The ZeyOS command-line interface for scripting, automation, and coding-agent workflows across the curated CLI resource registry."
+  }
+}

package/docs/04-agent-workflows/00-coding-agents.md

@@ -0,0 +1,35 @@
+---
+sidebar_position: 1
+sidebar_label: Coding Agents
+---
+
+# Coding Agents
+
+This path is for coding agents, automation scripts, and operational tools that need a deterministic way to read and write business data in ZeyOS.
+
+ZeyOS should be treated as the central system for business records and business rules. For v1, these docs stay focused on **external integrations**: the CLI, the JavaScript client, and the REST/OpenAPI surface exposed by a ZeyOS instance.
+
+## Start Here
+
+For most agent workflows, start with the CLI:
+
+| Need | Recommended interface | Why |
+|------|-----------------------|-----|
+| Fast CRUD against common business resources | [`zeyos`](../03-cli/01-getting-started.md) | Human-readable help, JSON output, built-in auth flow, safe delete confirmation |
+| Reliable shell automation and pipelines | [`zeyos --json`](./01-agent-quickstart.md) | Stable machine-readable output, easy to combine with `jq` and scripts |
+| Access beyond the CLI's curated resource registry | [`@zeyos/client`](../02-javascript-client/01-getting-started.md) | Covers the full generated API surface |
+| Non-JavaScript or custom HTTP clients | [REST/OpenAPI](../01-api-reference/03-resources.md) | Raw endpoint and schema reference |
+
+## Recommended Route
+
+1. Follow the [Agent Quickstart](./01-agent-quickstart.md) to authenticate and make your first read/write calls.
+2. Use [Agent Recipes](./02-agent-recipes.md) for common ticket, account, task, and project workflows.
+3. Check [CLI Coverage and Escalation](./03-cli-coverage-and-escalation.md) whenever you need a resource or request shape the CLI does not expose directly.
+
+## Working Rules
+
+- Prefer `--json` for agent-driven flows.
+- Prefer `filters`-style JSON payloads in CLI examples so the transition to `@zeyos/client` stays consistent.
+- Include `visibility: 0` unless you intentionally want archived or deleted records.
+- Treat `delete` as destructive. The CLI prompts by default; use `--force` only in deliberate automation.
+- Switch to the JavaScript client when the task needs unsupported resources, browser/session behavior, or low-level request control.