@zeyos/client 0.2.0 → 0.4.0

package/agents/zeyos-time-tracking/references/workflows.md

@@ -0,0 +1,230 @@
+# Time Tracking Workflows
+
+## Resources and operation IDs
+
+These are dbref nouns; the REST/client operationIds differ for action steps (compound CamelCase):
+
+- `tickets` -> `listTickets` / `getTicket` / `createTicket` / `updateTicket`
+- `tasks` -> `listTasks` / `getTask` / `createTask` / `updateTask`
+- `projects` -> `listProjects` / `getProject`
+- `accounts` -> `listAccounts` / `getAccount`
+- `actionsteps` -> `listActionSteps` / `getActionStep` / `createActionStep` / `updateActionStep` (not `listActionsteps`)
+- current user -> `getUserInfo` (oauth2 service); `zeyos whoami --json` exposes its `sub`
+
+See [../../shared/zeyos-entity-reference.md](../../shared/zeyos-entity-reference.md#entity-noun-to-rest-operationid) before calling `@zeyos/client`.
+
+## Schema facts this skill relies on
+
+- **Time entries are `actionsteps`.** The `effort` field is **minutes** (integer). There is no separate time-entry resource.
+- **Actionstep foreign keys:** `task`, `ticket`, `account`, `transaction` — plus `assigneduser`, `date`, `duedate`, `status`, `effort`. **There is no `project` FK on an actionstep**, so project-level time attaches through a ticket/task in that project, or to the project's `account`.
+- **Actionstep status:** `0` DRAFT · `1` COMPLETED · `2` CANCELLED · `3` BOOKED. Log already-done work as **COMPLETED (1)**; use **BOOKED (3)** only when the instance treats booked effort as the billed/locked record and the user says so.
+- **Ticket/task status:** `0` NOT_STARTED · `1` AWAITING_ACCEPTANCE · `2` ACCEPTED · `3` REJECTED · `4` ACTIVE · `5` INACTIVE · `6` FEEDBACK_REQUIRED · `7` TESTING · `8` CANCELLED · `9` COMPLETED · `10` FAILED · `11` BOOKED. Treat **open/current = status `!IN [8,9,10,11]`** (exclude cancelled/completed/failed/booked). State this definition in the answer; the user can narrow it (e.g. only `4` ACTIVE).
+- **Foreign keys per resource:** `tickets` carry `account`, `project`, `assigneduser`; `tasks` carry `ticket`, `project`, `assigneduser` (no `account` — reach the account through the task's ticket/project); `projects` carry `account`, `assigneduser`; `accounts` carry `lastname`, `firstname`, `customernum` (no `name` field).
+- **Visibility:** `tickets`, `tasks`, `projects`, `accounts` expose `visibility` (use `0` for live records). `transactions` do **not** — never filter `visibility` there.
+- All dates are **Unix timestamps in seconds**.
+
+## Filter operators (server-side)
+
+`{"field": value}` is equality. Object values take operators: `{">=":3}`, `{"!=":0}`, `{"IN":[1,3]}`, `{"!IN":[8,9,10,11]}`. For name search, `~~*` is case-insensitive LIKE: `{"lastname": {"~~*": "%acme%"}}`. The client accepts `filters` (plural); the CLI flag is `--filter` (it writes `filters` internally).
+
+---
+
+## Pattern: "What are my current tickets / tasks / action steps?"
+
+1. Resolve the current user id:
+
+   ```bash
+   zeyos whoami --json   # read the "sub" field — this is your users.ID
+   ```
+
+2. List open work assigned to that id. Use `--limit` high enough that nothing is silently truncated, or `zeyos count` first if the user asked "how many".
+
+   ```bash
+   # my open tickets, most urgent first
+   zeyos list tickets \
+     --fields ID,ticketnum,name,status,priority,duedate,account.lastname,project \
+     --filter '{"assigneduser":<sub>,"visibility":0,"status":{"!IN":[8,9,10,11]}}' \
+     --sort -priority,+duedate \
+     --limit 200 --json
+
+   # my open tasks
+   zeyos list tasks \
+     --fields ID,tasknum,name,status,priority,duedate,ticket,project,projectedeffort \
+     --filter '{"assigneduser":<sub>,"visibility":0,"status":{"!IN":[8,9,10,11]}}' \
+     --sort -priority,+duedate --limit 200 --json
+
+   # my open action steps (follow-ups)
+   zeyos list actionsteps \
+     --fields ID,actionnum,name,status,date,duedate,effort,ticket,task,account \
+     --filter '{"assigneduser":<sub>,"status":0}' \
+     --sort +duedate --limit 200 --json
+   ```
+
+   Client form:
+
+   ```js
+   const me = await client.oauth2.getUserInfo();          // me.sub === users.ID (string)
+   const myTickets = await client.api.listTickets({
+     fields: ['ID', 'ticketnum', 'name', 'status', 'priority', 'duedate', 'account.lastname', 'project'],
+     filters: { assigneduser: me.sub, visibility: 0, status: { '!IN': [8, 9, 10, 11] } },
+     limit: 200,
+   });
+   ```
+
+3. Report the resolved user and the open-status definition, then the list ordered by priority and due date. Flag overdue items (`duedate < now`).
+
+---
+
+## Pattern: Interactive time logging — "Log 60 minutes of work for client XYZ"
+
+This is the headline interactive flow. Run each step; ask the user only at the marked decision points.
+
+### Step 1 — Parse the request
+
+- **Duration -> minutes.** "60 minutes" -> `60`; "2 hours" -> `120`; "1.5h"/"an hour and a half" -> `90`; "half an hour" -> `30`. `effort` is integer minutes.
+- **Date.** Default to now (`date` = current Unix seconds). Honor an explicit date if given ("yesterday", "on Monday").
+- **Note.** Use any description the user gave ("call about the renewal") as the actionstep `name`/`description`; otherwise compose a short one and confirm it.
+
+### Step 2 — Resolve the account (ask only if ambiguous)
+
+```bash
+zeyos list accounts \
+  --fields ID,customernum,lastname,firstname,type \
+  --filter '{"visibility":0,"lastname":{"~~*":"%xyz%"}}' \
+  --limit 25 --json
+```
+
+- Also try `customernum` and `firstname` if `lastname` yields nothing.
+- **0 matches:** report it and ask for a customer number or exact name — do not create anything.
+- **1 match:** state it ("Logging against ACME Corp (#10042)") and continue.
+- **>1 match (DECISION POINT):** list the candidates with `customernum`, name, and `type`, and ask which one. Do not guess.
+
+### Step 3 — Enumerate candidate work items for that account
+
+Run these in parallel; you are building the menu of places the time could land. (Tasks have no `account` FK, so reach them through the account's tickets/projects.)
+
+```bash
+# open tickets on the account
+zeyos list tickets --fields ID,ticketnum,name,status,priority \
+  --filter '{"account":<accountId>,"visibility":0,"status":{"!IN":[8,9,10,11]}}' --limit 50 --json
+
+# active projects on the account
+zeyos list projects --fields ID,projectnum,name,status \
+  --filter '{"account":<accountId>,"visibility":0,"status":{"!IN":[8,9,10,11]}}' --limit 50 --json
+
+# open tasks under those tickets/projects (use the IDs gathered above)
+zeyos list tasks --fields ID,tasknum,name,status,ticket,project \
+  --filter '{"visibility":0,"status":{"!IN":[8,9,10,11]},"ticket":{"IN":[<ticketIds>]}}' --limit 50 --json
+```
+
+### Step 4 — Choose the attachment (DECISION POINT)
+
+Present the candidates grouped (tickets / tasks / projects) and ask where the time should go. Map the choice to exactly one actionstep FK:
+
+- a ticket -> `ticket: <id>`
+- a task -> `task: <id>`
+- a project -> attach to a ticket/task in that project, or fall back to the project's `account` (no `project` FK exists on actionsteps — say so)
+- "just the account / general" or no work items exist -> `account: <accountId>`
+
+If there is exactly one obvious candidate (e.g. a single open ticket), propose it as the default and let the user confirm rather than asking open-endedly.
+
+### Step 5 — Preview, confirm, then write
+
+Preview the exact request without sending it, show it to the user, and create it only after confirmation:
+
+```bash
+# dry-run preview (no network, no write)
+zeyos create actionstep \
+  --name "Call about the renewal" \
+  --ticket <ticketId> \
+  --account <accountId> \
+  --assigneduser <sub> \
+  --effort 60 --status 1 --date <nowSeconds> \
+  --query
+
+# after the user confirms, drop --query to actually create, then read it back
+zeyos create actionstep --name "Call about the renewal" --ticket <ticketId> \
+  --assigneduser <sub> --effort 60 --status 1 --date <nowSeconds> --json
+zeyos get actionstep <newId> --json
+```
+
+Client form:
+
+```js
+const now = Math.floor(Date.now() / 1000);
+const created = await client.api.createActionStep({
+  name: 'Call about the renewal',
+  ticket: ticketId,          // or task / account — exactly one work anchor
+  assigneduser: me.sub,
+  effort: 60,                // minutes
+  status: 1,                 // COMPLETED (logged work)
+  date: now,
+});
+const verify = await client.api.getActionStep({ ID: created.ID });
+```
+
+Set **one** of `ticket` / `task` / `account` as the work anchor (a ticket already implies its account, so you do not need both). Report the created id, the anchor, effort minutes, and date.
+
+---
+
+## Pattern: "How much time did I log this week?" (timesheet summary)
+
+The read complement to logging — totals the effort the current user already booked over a period, optionally grouped by account/ticket.
+
+1. Resolve the current user id (`zeyos whoami --json` → `sub`).
+2. Normalize the window to Unix **seconds**. The actionstep `date` field carries the business date of the entry; filter on it.
+3. List the user's time entries in the window and sum `effort` (minutes). Count only COMPLETED (1) and BOOKED (3) — those are real logged time, not open follow-ups (status 0).
+
+```bash
+# my logged minutes between two timestamps
+zeyos list actionsteps \
+  --fields ID,name,effort,date,status,account,ticket,task \
+  --filter '{"assigneduser":<sub>,"status":{"IN":[1,3]},"date":{">=":<weekStart>,"<=":<weekEnd>}}' \
+  --limit 10000 --json
+```
+
+```js
+const me = await client.oauth2.getUserInfo();
+const rows = await client.api.listActionSteps({
+  fields: ['ID', 'effort', 'date', 'status', 'account', 'ticket', 'task'],
+  filters: { assigneduser: me.sub, status: { IN: [1, 3] }, date: { '>=': weekStart, '<=': weekEnd } },
+  limit: 10000,
+});
+const totalMinutes = rows.reduce((sum, r) => sum + (Number(r.effort) || 0), 0);
+```
+
+4. Sum `effort` as minutes; convert to hours only if asked. To break down "by account/ticket", group the rows by the FK and resolve the account/ticket names with a second query. Report the total and the breakdown, and state the window and status set you used.
+
+## Pattern: Adjust or correct a logged entry
+
+For "actually that was 90 minutes, not 60" or "move that time to ticket 813" right after logging — or any later correction.
+
+1. Get the entry first so you preview the current values: `zeyos get actionstep <id> --json`.
+2. Build a minimal PATCH with only the changed fields. Preview with `--query`, confirm with the user (it is a mutation on an existing record), then update and read back.
+
+```bash
+zeyos update actionstep <id> --effort 90 --query        # preview the change
+zeyos update actionstep <id> --effort 90 --json         # after confirmation
+zeyos get actionstep <id> --json                        # verify
+```
+
+```js
+await client.api.updateActionStep({ ID: id, effort: 90 });   // spread form: ID + changed fields
+const verify = await client.api.getActionStep({ ID: id });
+```
+
+Only correct entries the user pointed to (by id, or one you just created in this turn). Re-anchoring time to a different work item means changing the `ticket`/`task`/`account` FK — set the new anchor and clear the old one if it conflicts. Never bulk-rewrite a category of entries.
+
+## Degrading when there is no human (automated / harness runs)
+
+- "My work" reads still work: resolve `sub`, run the list, report it.
+- For a **write**, never break ambiguity by guessing. If the account or the work item is ambiguous and nothing can be asked, stop and report the candidates and what was missing. A wrong foreign key on a created time entry is worse than an unanswered request.
+
+## Common failure modes
+
+- Counting a `list` page instead of the real total — use `zeyos count` for "how many of my …".
+- Filtering `visibility` on `transactions` (no such column -> HTTP 400).
+- Putting effort in hours — `effort` is **minutes**.
+- Trying to set a `project` FK on an actionstep — it does not exist; anchor on a ticket/task/account instead.
+- Treating BOOKED (status 11) tickets as current — they are terminal; the open set excludes `[8,9,10,11]`.
+- Logging time against a user id you guessed — always read `sub` from `whoami`.

package/agents/zeyos-work-management/SKILL.md

@@ -7,12 +7,15 @@ description: Manage ZeyOS tickets, tasks, projects, action steps, assignees, and
 
 Read [../shared/zeyos-agent-operating-guide.md](../shared/zeyos-agent-operating-guide.md) and [../shared/zeyos-query-patterns.md](../shared/zeyos-query-patterns.md) first. Read [../shared/zeyos-entity-map.md](../shared/zeyos-entity-map.md) when the request crosses users, accounts, tickets, tasks, and projects. Read [references/workflows.md](references/workflows.md) for the concrete query patterns.
 
+For **first-person** requests ("what are *my* current tickets?", "my open tasks") or for **recording new time** ("log 60 minutes for client XYZ"), use [../zeyos-time-tracking/SKILL.md](../zeyos-time-tracking/SKILL.md) instead — it resolves the current user and runs the interactive account → work-item → time-entry flow. This skill stays focused on third-person analytical queues, tracing, and effort *summaries*.
+
 Typical prompts:
 
 - "On which projects did Max Power work in the last two weeks?"
 - "Show overdue high-priority tickets for customer ACME."
 - "Which open tasks are blocking Project Atlas?"
 - "Which action steps are due this week for ACME?"
+- "How much booked effort did this user log last week?"
 - "Create a follow-up ticket for this billing issue."
 
 ## Workflow
@@ -22,10 +25,10 @@ Typical prompts:
 3. Start with the narrowest query that can answer the question:
    - use `tickets` for queue, backlog, priority, and account-linked support work
    - use `tasks` for actionable delivery work and short-lived assignments
-   - use `actionsteps` for smaller cross-record follow-ups attached to tasks, tickets, accounts, or transactions
+   - use `actionsteps` for smaller cross-record follow-ups and effort/time-entry evidence attached to tasks, tickets, accounts, or transactions
    - use `projects` for top-level initiative state
 4. Follow relationships only after the primary record set is clear.
-5. Treat "worked on" as a proxy unless a stronger activity source exists. Use assignment plus recent timestamps, optionally strengthened by linked action steps, and say so explicitly.
+5. Treat "worked on" as a proxy unless actionstep effort/date evidence exists. Assignment and timestamps show involvement; `actionsteps.effort` on `COMPLETED` or `BOOKED` records is stronger time-entry evidence.
 6. Distinguish direct project assignment from project inference through linked tickets.
 7. When the question is really about account or transaction follow-up, check `actionsteps` before inventing a new task.
 8. For mutations, preview the affected record first and update with an explicit PATCH body.

package/agents/zeyos-work-management/references/workflows.md

@@ -9,10 +9,20 @@
 - `users`: system identities for assignees
 
 These are dbref nouns, not operationIds. Note `actionsteps` -> `listActionSteps` /
-`getActionStep` / `createActionStep` (compound CamelCase, not `listActionsteps`). See
+`getActionStep` / `createActionStep` / `updateActionStep` / `deleteActionStep`
+(compound CamelCase, not `listActionsteps`). See
 [../../shared/zeyos-entity-reference.md](../../shared/zeyos-entity-reference.md#entity-noun-to-rest-operationid)
 before calling `@zeyos/client`.
 
+Actionstep status values:
+
+- `0` = DRAFT / open follow-up
+- `1` = COMPLETED
+- `2` = CANCELLED
+- `3` = BOOKED
+
+Use `effort` as minutes of effort only when the question is about time entries or booked/completed work. Do not infer booked time from task assignment alone.
+
 ## Resolve Before Querying
 
 1. Resolve the user or account first.
@@ -32,7 +42,7 @@ Recommended approach:
 1. Resolve the user from `users.name` or `users.email`.
 2. Query recent tasks assigned to that user with `lastmodified > cutoff`.
 3. Query recent tickets assigned to that user with `lastmodified > cutoff`.
-4. Optionally query recent `actionsteps` for the same user when you want stronger evidence of follow-up activity.
+4. Query recent `actionsteps` for the same user when you need stronger evidence of follow-up activity or booked effort.
 5. Collect direct `project` links from tasks and tickets.
 6. For tasks that only link to a ticket, fetch the ticket or include `ticket.project` if available in the selected fields.
 7. For action steps linked to tasks or tickets, infer the project through the linked parent only if the user asked for a broad activity summary.
@@ -67,7 +77,7 @@ const recentTickets = await client.api.listTickets({
 
 Important caveat:
 
-- The documented schema does not expose timesheets or effort logs here. "Worked on" is therefore an activity proxy, not proof of time spent.
+- Assignment-based "worked on" answers are activity proxies. `actionsteps` with `date`, `status` COMPLETED/BOOKED, and `effort` are the better evidence for time-entry summaries.
 
 ## Pattern: Review A Ticket Queue
 
@@ -87,6 +97,13 @@ zeyos list tickets \
 Follow up with `tasks` only if the answer requires execution detail below the ticket level.
 Follow up with `actionsteps` if the queue management style in this instance uses reminders or next steps below the ticket.
 
+For ticket work packets, include:
+
+- ticket status, priority, due date, account/project links
+- open tasks linked by `task.ticket`
+- open actionsteps linked by `actionstep.ticket` or by task
+- recent messages linked by `message.ticket` if the request asks for customer context
+
 ## Pattern: Overdue Work For An Account Or Project
 
 Use this for prompts like:
@@ -121,6 +138,39 @@ Recommended approach:
 4. Keep due date and status visible in the result.
 5. If the anchor is a transaction and the user also wants broader work context, then check related tickets or account-level tasks second.
 
+CLI examples:
+
+```bash
+zeyos list actionsteps \
+  --fields ID,actionnum,name,status,date,duedate,effort,ticket,task,account,transaction \
+  --filter '{"ticket":812}' \
+  --sort +duedate \
+  --limit 100 \
+  --json
+```
+
+For counts:
+
+```bash
+zeyos count actionsteps --filter '{"ticket":812,"status":0}' --json
+```
+
+## Pattern: Time Entry / Effort Summaries
+
+Use this for prompts like:
+
+- "How many minutes were booked on ticket 812 last week?"
+- "Summarize completed actionstep effort for this account."
+- "Which user logged effort against this project?"
+
+Recommended approach:
+
+1. Resolve the anchor and the date window.
+2. Query `actionsteps` with fields `ID`, `date`, `status`, `effort`, and the relevant FK (`ticket`, `task`, `account`, or `transaction`).
+3. Include statuses `1` COMPLETED and `3` BOOKED for time-entry totals unless the user asks for drafts/open follow-ups.
+4. Sum `effort` as minutes; convert to hours only if the user asked for hours.
+5. Keep task/ticket assignment separate from effort totals.
+
 ## Pattern: Create Follow-Up Work
 
 For prompts like:
@@ -136,7 +186,7 @@ Recommended approach:
    - use `project` if the follow-up is project-wide
    - use `actionsteps` if the follow-up is small, account-scoped, or transaction-scoped and does not justify a standalone task
    - keep `visibility: 0`
-3. Confirm the new owner, due date, and priority if they are not explicit.
+3. Confirm the new owner, due date, and priority/effort if they are not explicit.
 4. Use explicit PATCH or create bodies and return the created record ID.
 
 ## Common Failure Modes

package/docs/02-javascript-client/03-making-requests.md

@@ -253,6 +253,26 @@ const page2 = await client.api.listTickets({
 Use `count: true` to get the total number of matching records without fetching the full dataset. This is useful for building pagination controls.
 :::
 
+### Auto-pagination
+
+To iterate an entire result set without managing `offset` yourself, use `client.paginate(operationId, input, opts)` — an async iterator that pages until a short/empty page (or `opts.max`) is reached. It removes the off-by-one and "I only got the first 1000 / 50 rows" mistakes the list caps otherwise invite.
+
+```js
+// Stream every matching ticket, one page at a time
+for await (const ticket of client.paginate('listTickets', { filters: { visibility: 0 } }, { pageSize: 1000 })) {
+  process(ticket);
+}
+
+// Eagerly collect up to a cap
+const recent = await client.collect(
+  'listTickets',
+  { filters: { visibility: 0 }, sort: ['-lastmodified'] },
+  { pageSize: 500, max: 2000 }
+);
+```
+
+`opts`: `pageSize` (default 1000, clamped to the server max of 10000), `max` (stop after N records), and `requestOptions` (forwarded to each underlying call, e.g. `{ signal, timeoutMs }`). `collect` is the eager array form of `paginate`.
+
 ## Normalising List Responses
 
 List endpoints are not uniform across the full surface area. Depending on the endpoint and response mode, you may see:
@@ -432,9 +452,32 @@ const noRetry = createZeyosClient({ platform: 'live', instance: 'demo', retry: f
 Only `429`/`503` are retried by default -- statuses that clearly mean "try again later". `5xx` codes such as `500`/`502` are **not** retried automatically, to avoid re-applying a non-idempotent write that may have partially succeeded. Add them to `retryOn` only for read-heavy workloads.
 :::
 
+### Request timeout
+
+A request with no built-in deadline can hang indefinitely if the connection stalls (e.g. an instance restarting). Set `timeoutMs` to bound each attempt; it composes with any `AbortSignal` you pass. The timeout applies **per attempt**, so a retry gets a fresh deadline.
+
+```js
+// Per request
+await client.api.listTickets({ filters: { visibility: 0 } }, { timeoutMs: 8000 });
+
+// Or a client-wide default
+const client = createZeyosClient({ platform: 'live', instance: 'demo', timeoutMs: 8000 });
+```
+
+A timeout rejects with an `Error` whose `isTimeout === true` (and `code === 'ETIMEDOUT'`). A timeout is distinct from a caller abort: aborting your own `AbortSignal` always propagates immediately and is never retried.
+
+### Network-error retries
+
+Network-level failures (a dropped connection, DNS blip, or a timeout) are retried for **read** operations only — `GET`/`HEAD` plus side-effect-free `list`/`count`/`search` queries — using the same retry budget and backoff. Writes (`create`/`update`/`delete`) are **never** auto-retried on a network error, so a dropped connection can't cause a duplicate mutation. Override per request or per client with `retryOnNetworkError: true | false`.
+
+```js
+await client.api.listTickets({ filters: {} }, { retryOnNetworkError: true });  // force (already on for reads)
+await client.api.createTicket({ name: 'x' }, { retryOnNetworkError: true });   // opt a write in, at your own risk
+```
+
 ## Error Handling
 
-All API errors are thrown as `ZeyosApiError` instances. This class extends `Error` and includes structured information about the failed request.
+All API errors are thrown as `ZeyosApiError` instances. This class extends `Error` and includes structured information about the failed request. When the server returns an error body with a message, a short snippet of it is folded into `err.message` (e.g. `api.listTickets failed with HTTP 400: unknown filter field: bogus`), so the thrown error says *why*, not just the status code. The full body is always on `err.body`.
 
 ```js
 import { ZeyosApiError } from '@zeyos/client';
@@ -535,6 +578,8 @@ All generated methods and `client.request()` accept an optional second argument
 | Option | Type | Description |
 |--------|------|-------------|
 | `signal` | `AbortSignal` | An `AbortController` signal to cancel the request |
+| `timeoutMs` | `number` | Abort this attempt after N ms (composes with `signal`); also settable client-wide as `timeoutMs` |
+| `retryOnNetworkError` | `boolean` | Force/disable retrying network errors & timeouts for this call (default: on for reads, off for writes) |
 | `raw` | `boolean` | Return the full response envelope instead of just the data |
 | `auth` | `string \| { mode?: string, accessToken?: string, access_token?: string, refreshToken?: string, refresh_token?: string, clientId?: string, client_id?: string, clientSecret?: string, client_secret?: string }` | Override the authentication mode or credentials for this request |
 | `baseUrl` | `string` | Override the base URL for this request |

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

@@ -14,6 +14,7 @@ These options work with any command:
 |--------|-------------|
 | `--json` | Output as formatted JSON |
 | `--yaml` | Output as YAML |
+| `--profile <name>` | Use a named credential profile for this command |
 | `--no-color` | Disable ANSI color output |
 | `-h`, `--help` | Show help for a command |
 
@@ -101,6 +102,36 @@ zeyos whoami --show-token --json   # explicitly include the current access token
 
 ---
 
+## profile
+
+Manage named credential profiles and switch between ZeyOS instances. See [Configuration → Profiles](./03-configuration.md#profiles) for the full model.
+
+```
+zeyos profile <list|current|use|add|remove> [options]
+```
+
+| Command | Description |
+|---------|-------------|
+| `profile list` | List all profiles; the active one is marked `*`, with token status |
+| `profile current` | Show which profile resolves right now, and why (flag/env/pin/active) |
+| `profile use <name>` | Make `<name>` the active profile (global) |
+| `profile use <name> --local` | Pin `<name>` to the current project (`.zeyos/profile`) |
+| `profile add <name> [opts]` | Create/update a profile (`--base-url`, `--client-id`, `--secret`, or `--from-current`) |
+| `profile remove <name>` | Delete a profile |
+
+**Examples:**
+
+```bash
+zeyos profile add dev  --base-url https://zeyos.cms-it.de/dev
+zeyos profile add prod --from-current        # snapshot current credentials
+zeyos login --profile prod                   # authenticate into & activate a profile
+zeyos profile use dev                         # switch active profile
+zeyos profile use prod --local                # pin to this project
+zeyos list tickets --profile dev              # one-off override on any command
+```
+
+---
+
 ## list
 
 Query and list records for a resource with filtering, sorting, and pagination.
@@ -363,7 +394,10 @@ List all curated CLI resources and their operations. This is the authoritative b
 zeyos resources
 ```
 
-Shows a table of all CLI-supported resource types and available operations.
+Shows a table of all CLI-supported resource types and available operations. Operational
+workflows can use `actionstep` / `actionsteps` / `time-entries` for follow-ups and
+effort records. Read-only platform schema definitions are available as `customfield` /
+`customfields` with `list`, `get`, and therefore `count` support.
 
 ---
 
@@ -447,6 +481,34 @@ Skills are copied into `<dir>/<name>/`, with the shared reference files installe
 
 ---
 
+## okf
+
+Work with the [Open Knowledge Format](../06-okf/01-overview.md) bundle that ships with the
+client — a portable Markdown description of the ZeyOS data model (one concept per
+API-backed entity) plus curated metrics, playbooks, and query concepts.
+
+```bash
+zeyos okf list                  # list concepts (type, id, title); --json for automation
+zeyos okf show tickets          # print a concept (bare resource name, or entities/tickets)
+zeyos okf check                 # validate OKF v0.1 conformance (exit non-zero on error)
+zeyos okf export --out ./okf    # copy the shipped bundle into a directory
+zeyos okf build  --out ./okf    # synthesize a bundle from the client's schema
+```
+
+| Subcommand | What it does |
+|-----------|--------------|
+| `list` | List the concepts in the bundle (`--json`/`--yaml` supported). |
+| `show <concept>` | Print one concept doc. Accepts a bare resource (`tickets`) or full id (`entities/tickets`). |
+| `check` | Validate the bundle for OKF v0.1 conformance; exits non-zero on any error (CI-friendly). |
+| `export` | Copy the shipped `okf/` bundle into `--out` (default `./okf`); `--force` to overwrite. |
+| `build` | Synthesize a structural bundle from the client's schema into `--out` (default `./okf`). |
+
+Options: `--dir <path>` reads from an explicit bundle directory (`list`/`show`/`check`);
+`--out <path>` is the write target (`build`/`export`); `--force` overwrites an existing
+target. `export` ships the rich curated bundle; `build` is the lighter runtime projection.
+
+---
+
 ## Command Aliases
 
 | Alias | Equivalent |

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

@@ -12,15 +12,47 @@ These settings apply to the CLI's curated resource registry. If you need a resou
 
 ## Credential Cascade
 
-Credentials are resolved from three sources in priority order:
+The CLI first decides **which credential set** is the base, then lets environment credential variables field-override on top. The base is chosen by the first match in this 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` |
+| 1 (highest) | `--profile <name>` flag | named profile (per command) |
+| 2 | `ZEYOS_PROFILE` env var | named profile |
+| 3 | Project pin | `.zeyos/profile` (walks up from CWD) |
+| 4 | Local config file | `.zeyos/auth.json` (walks up from CWD) |
+| 5 | Global active profile | `~/.config/zeyos/profiles.json` (`active`) |
+| 6 (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.
+On top of the chosen base, the credential **environment variables** (`ZEYOS_BASE_URL`, `ZEYOS_TOKEN`, …) always override individual fields — so you can keep `baseUrl` and client credentials in a profile while overriding just the token via `ZEYOS_TOKEN` in CI.
+
+If you have never created a profile, nothing changes: the CLI falls through to the legacy local `.zeyos/auth.json` and global `credentials.json` exactly as before.
+
+## Profiles
+
+Profiles let you store several ZeyOS instances (e.g. `dev`, `prod`, `client-x`) and switch between them without re-running `login`. Each profile is a full credential set (URL, OAuth app, tokens) kept in `~/.config/zeyos/profiles.json`, with one marked **active**.
+
+```bash
+# Create profiles (connection params now; tokens via login)
+zeyos profile add dev  --base-url https://zeyos.cms-it.de/dev
+zeyos profile add prod --base-url https://cloud.zeyos.com/acme --client-id app --secret "$SECRET"
+
+# Authenticate into a profile (also makes it active)
+zeyos login --profile prod
+
+# See and switch profiles
+zeyos profile list                 # active marked with *, shows token status
+zeyos profile use dev              # switch the global active profile
+zeyos profile current             # what resolves right now, and why
+
+# Per-project: pin a profile so cd-ing into a repo selects its instance
+cd ~/work/acme && zeyos profile use prod --local   # writes ./.zeyos/profile
+
+# One-off override on any command (beats env, pin, and active)
+zeyos whoami --profile dev
+zeyos list tickets --profile prod
+```
+
+`zeyos profile add <name> --from-current` snapshots whatever credentials are in effect (including tokens) into a new profile — handy for adopting an existing `.zeyos/auth.json` setup. Add `.zeyos/profile` to `.gitignore` alongside `.zeyos/auth.json`.
 
 ## Environment Variables
 

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

@@ -107,6 +107,28 @@ Count matching records:
 
 ```bash
 zeyos count tickets --filter '{"visibility":0,"status":4}' --json
+zeyos count customfields --json
+zeyos count actionsteps --filter '{"status":0}' --json
+```
+
+Summarize actionstep effort/time-entry evidence:
+
+```bash
+zeyos list actionsteps \
+  --fields ID,name,status,date,duedate,effort,ticket,task,account \
+  --filter '{"status":3}' \
+  --limit 100 \
+  --json
+```
+
+Inspect ticket-linked mail without sending anything:
+
+```bash
+zeyos list messages \
+  --fields ID,date,mailbox,subject,sender_email,to_email,ticket,reference,messageid \
+  --filter '{"ticket":42}' \
+  --sort +date \
+  --json
 ```
 
 ## Write Data
@@ -145,4 +167,6 @@ zeyos delete ticket 42 --force
 - Include `visibility: 0` in filters for normal business views.
 - Prefer `--data '<json>'` over many separate flags in automation.
 - Run `zeyos resources` before assuming a resource is CLI-supported.
+- Use `actionsteps.effort` for time-entry totals; do not infer booked time from task assignment.
+- Draft e-mail text in the response unless the user explicitly asks for a real ZeyOS draft record; never send mail from an agent workflow.
 - Escalate to [`@zeyos/client`](./03-cli-coverage-and-escalation.md) when the CLI resource registry is not enough.

package/docs/04-agent-workflows/03-cli-coverage-and-escalation.md

@@ -13,10 +13,11 @@ The command `zeyos resources` is the source of truth for CLI-supported resource
 
 | Resource | Operations |
 |----------|------------|
-| `account`, `appointment`, `campaign`, `contact`, `document`, `event`, `file`, `invitation`, `item`, `message`, `note`, `opportunity`, `payment`, `project`, `storage`, `task`, `ticket`, `transaction` | `list`, `get`, `create`, `update`, `delete` |
+| `account`, `actionstep`, `appointment`, `campaign`, `contact`, `document`, `event`, `file`, `invitation`, `item`, `message`, `note`, `opportunity`, `payment`, `project`, `storage`, `task`, `ticket`, `transaction` | `list`, `get`, `create`, `update`, `delete` |
+| `customfield` / `customfields` | `list`, `get` |
 | `group`, `user` | `list`, `get` |
 
-Plural names and common aliases such as `tickets`, `docs`, `invoice`, and `crm` are resolved by the CLI, but the underlying coverage boundary is still the registry above.
+Plural names and common aliases such as `tickets`, `actionsteps`, `time-entries`, `docs`, `invoice`, and `crm` are resolved by the CLI, but the underlying coverage boundary is still the registry above.
 
 ## What the CLI Does Not Try to Cover