@zeyos/client 0.1.0 → 0.2.0

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.
@@ -142,6 +143,13 @@ zeyos list tickets --filter '{"status":1,"priority":3}'
 zeyos count tickets --filter '{"status":1}'
 ```
 
+For larger filters, store the JSON in a file and use `--filter-file`:
+
+```bash
+zeyos list tickets --filter-file ./filters/open-tickets.json --json
+zeyos count tickets --filter-file ./filters/open-tickets.json --json
+```
+
 For normal operational views, include `visibility: 0`:
 
 ```bash

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

@@ -113,6 +113,7 @@ zeyos list <resource> [options]
 |--------|-------------|
 | `--fields <fields>` | Field selection — comma-separated, JSON object, or JSON array (see below) |
 | `--filter <json>` | Filter criteria — JSON object |
+| `--filter-file <path>` | Read filter criteria from a JSON file |
 | `--sort <fields>` | Sort fields, comma-separated (prefix `+` asc, `-` desc) |
 | `--limit <n>` | Maximum records to return (default: `50`) |
 | `--offset <n>` | Skip the first n records |
@@ -140,6 +141,9 @@ zeyos list tickets
 # Custom filters
 zeyos list tickets --filter '{"status":1,"priority":3}'
 
+# Custom filters from a file
+zeyos list tickets --filter-file ./filters/open-tickets.json
+
 # Specify fields with aliases
 zeyos list accounts --fields '{"Name":"lastname","City":"contact.city"}'
 
@@ -179,6 +183,7 @@ zeyos count <resource> [options]
 | Option | Description |
 |--------|-------------|
 | `--filter <json>` | Filter criteria — JSON object |
+| `--filter-file <path>` | Read filter criteria from a JSON file |
 | `--json` | Output as `{"count": N}` |
 | `--yaml` | YAML output |
 
@@ -193,6 +198,9 @@ zeyos count tickets
 zeyos count tickets --filter '{"status":1}'
 # → 12
 
+# Filtered count using a JSON file
+zeyos count tickets --filter-file ./filters/open-tickets.json
+
 # JSON output for scripting
 zeyos count accounts --json
 # → {"count": 156}
@@ -261,6 +269,7 @@ zeyos create <resource> [--data <json>] [--field value ...]
 | Option | Description |
 |--------|-------------|
 | `--data <json>` | Complete record as a JSON string |
+| `--data-file <path>` | Read the complete record from a JSON file |
 | `--<field> <value>` | Set individual field (any unknown flag becomes a field) |
 
 **Examples:**
@@ -269,6 +278,9 @@ zeyos create <resource> [--data <json>] [--field value ...]
 # Using --data JSON
 zeyos create ticket --data '{"name":"Fix login bug","status":0,"priority":3}'
 
+# Using a JSON file
+zeyos create ticket --data-file ./ticket.json
+
 # Using individual field flags
 zeyos create ticket --name "Fix login bug" --status 0 --priority 3
 
@@ -301,6 +313,9 @@ zeyos update <resource> <id> [--data <json>] [--field value ...]
 # Using --data JSON
 zeyos update ticket 42 --data '{"status":4}'
 
+# Using a JSON file
+zeyos update ticket 42 --data-file ./ticket-update.json
+
 # Using field flags
 zeyos update ticket 42 --status 4 --priority 2
 
@@ -368,9 +383,22 @@ Foreign keys are shown as `→ <table>`, and enum fields list their valid values
 
 ---
 
+## doctor
+
+Check local CLI readiness for coding agents. This runs offline and never prints tokens or client secrets.
+
+```bash
+zeyos doctor agent
+zeyos doctor agent --json
+```
+
+The report includes the CLI version, configured base URL and instance, whether auth values are present through environment/local/global config, and whether the curated resource registry can be loaded.
+
+---
+
 ## 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 +407,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.2.0",
   "description": "Dependency-light JavaScript client for ZeyOS OpenAPI services",
   "type": "module",
   "license": "MIT",
@@ -31,7 +31,12 @@
     "scripts/generate-client.mjs",
     "openapi",
     "docs",
-    "samples",
+    "samples/crm",
+    "samples/dashboard",
+    "samples/kanban",
+    "samples/missioncontrol/README.md",
+    "samples/missioncontrol/fetch-data.mjs",
+    "samples/missioncontrol/index.html",
     "agents",
     "README.md",
     "CHANGELOG.md",
@@ -44,6 +49,7 @@
     "generate": "node scripts/generate-client.mjs",
     "test": "node scripts/test.mjs",
     "test:cli-integration": "node --test cli/test/integration.mjs",
-    "test:agent-protocol": "node test/agent-protocol/harness/run.mjs"
+    "test:agent-protocol": "node test/agent-protocol/harness/run.mjs",
+    "test:agent-loop": "node test/agent-protocol/harness/loop.mjs"
   }
 }

package/samples/missioncontrol/README.md

@@ -0,0 +1,106 @@
+# Mission Control
+
+A team-performance dashboard for an IT consultancy running on ZeyOS — built on
+the [`@zeyos/client`](../../README.md) library. It answers the managing
+director's question: **who is actually working, and where is there untapped
+capacity?**
+
+A dark "mission control" view: a velocity KPI row, a 13-week throughput trend,
+a team-capacity strip, and a searchable/sortable/filterable grid of per-employee
+activity cards (click one for a per-type digest + contribution graph).
+
+## What it shows
+
+1. **Velocity** — tickets opened vs closed in the window, net flow, average /
+   median / p90 **cycle time** (open → close), open backlog (with overdue), and
+   total **hours booked**. A 13-week **throughput trend** of opened vs closed.
+2. **Activity card per employee** — open tickets, open tasks, tickets closed,
+   hours booked, a weekly-hours sparkline, team/location tags, a **capacity
+   badge** (Overloaded / Balanced / Available / Idle / Former), and **last
+   activity** (the most recent time entry) — flagged red when it's **older than
+   7 days**. Hover "last activity" to see the engineer's **last 10 time entries**
+   (date · type · customer · ticket · hours).
+3. **Per-employee digest** (click a card) — **booked hours stacked by
+   `extdata.type`** (Weekly / Monthly), and a **GitHub-style contribution graph**
+   of their time-entry activity over the last 53 weeks.
+
+Filters: search by name, **filter by team / department / location** (group
+membership), capacity chips (Engaged / Spare capacity / Inactive >7d /
+Overloaded / All), and sort by activity, hours, throughput, workload, cycle,
+overdue, or least-recent.
+
+The **Team capacity** strip and the *Spare capacity* filter surface the
+"untapped resources": active engineers running light or with no load at all,
+contrasted with the overloaded ones — the clearest place to rebalance work.
+
+## Run it
+
+```bash
+# 1. Authenticate once (if you haven't already)
+zeyos login --base-url https://zeyos.cms-it.de/dev
+
+# 2. Pull live data into data.js (read-only; reuses your CLI credentials)
+node samples/missioncontrol/fetch-data.mjs            # 90-day window
+node samples/missioncontrol/fetch-data.mjs --days 180 # custom window
+
+# 3. Open the dashboard
+#    Either open index.html directly, or serve the folder:
+python3 -m http.server 8765 --directory samples/missioncontrol
+#    → http://localhost:8765
+```
+
+`fetch-data.mjs` writes `data.js` (a `window.MISSION_DATA = …` assignment) so
+`index.html` works straight from disk — no server, no CORS, no token pasting.
+Re-run the fetcher to refresh; the page is otherwise a static, dependency-free
+single file (hand-rolled CSS + inline-SVG charts).
+
+## How it works
+
+`fetch-data.mjs` reads the credentials `zeyos login` stored
+(`.zeyos/auth.json` or `~/.config/zeyos/credentials.json`), builds an
+auto-refreshing client with `createZeyosClient`, and issues a handful of
+**read-only** `list` queries (tickets, `actionsteps`, tasks, groups), then
+aggregates them client-side (ZeyOS has no server-side group-by). It never writes
+to ZeyOS.
+
+### Metric definitions (so the numbers are reproducible)
+
+| Metric | Definition |
+|--------|------------|
+| **Time entry** | an `actionsteps` row with `status IN [1, 3]` (COMPLETED + BOOKED), attributed to an engineer via **`assigneduser`** (`owneruser` is unused here). `effort` is in **minutes**. |
+| **Last activity** | the engineer's most recent time-entry `date`; **stale** (red ⚠) when it's >7 days before the "as of" date. |
+| **Type** | `extdata.type` of each time entry (Intern / Auftrag / Consulting / Wartung / …), selected on `list` via the `extdata.type` field. Top 6 are charted; the rest roll into *Other*. |
+| **Closed / done** | tickets with `status IN [9, 11]` — COMPLETED + BOOKED (BOOKED, completed & billed, is the dominant terminal state). |
+| **Open backlog** | `status IN [0, 1, 2, 4, 6, 7]` — started/accepted/active but not done. |
+| **Opened in window** | tickets whose indexed `date` falls in the window. |
+| **Cycle time** | `lastmodified − creationdate` for tickets closed in the window (a proxy for the close timestamp, which ZeyOS does not store separately). |
+| **Capacity** | relative to the engaged-and-active cohort: *overloaded* (top-quintile workload or ≥3 overdue), *available* (low workload **and** below-median throughput), *idle* (active user, zero load), *balanced* (else), *former* (deactivated user with leftover assignments). |
+| **Team / location** | the engineer's **group memberships** (see below). |
+
+### Notes & limitations
+
+- **Department/location = groups.** ZeyOS *defines* custom fields
+  `users.department`/`users.location`/`users.team`, but the API returns
+  *"Extension data not available for users"* — they can't be read. The org
+  structure instead lives in **group membership** (e.g. `Developers`,
+  `Services`, `Technik`, `Berlin`, `Bayern`, `Nordrhein-Westfalen`), which is
+  what the team/location filter uses.
+- **`extdata` only lists via dot-fields.** Custom fields aren't returned by a
+  plain `list` (or `extdata=1`); they must be selected explicitly, e.g.
+  `fields: ['…','extdata.type']` (returned as `extdata_type`). On single records
+  `getTicket(…, { query:{ extdata:1 } })` returns them under an `extdata` object.
+- **Corrupt time-entry dates.** Many `actionsteps` have far-future `date` values
+  (year 2099+); the fetcher bounds queries to `date ≤ now` to exclude them.
+- **"As of" anchoring.** Windows are measured back from the latest activity in
+  the data, not wall-clock today — so a frozen/dev snapshot still produces
+  meaningful windows (and the 7-day staleness check is relative to it). The
+  anchor date is shown in the header.
+- **`date`, not `creationdate`, for windows.** `creationdate`/`lastmodified` are
+  unindexed on `tickets`; range-scanning them can time out (HTTP 503). The
+  indexed `date` column is used for opened-in-window queries.
+- **Roles aren't distinguished.** Every active user is included; a salesperson
+  with no tickets shows as *Idle*. Use the team filter / search to focus on a
+  delivery team.
+
+> `data.js` / `data.json` are generated and contain real names from your
+> instance — they are git-ignored. Commit only the source.