@zeyos/client 0.1.1 → 0.3.0

package/agents/zeyos-platform-and-schema/SKILL.md

@@ -5,7 +5,7 @@ description: Inspect ZeyOS platform, schema, and admin-facing entities such as a
 
 # ZeyOS Platform And Schema
 
-Read [../shared/zeyos-query-patterns.md](../shared/zeyos-query-patterns.md) first. Read [../shared/zeyos-entity-reference.md](../shared/zeyos-entity-reference.md) for the full source-backed model. Read [references/workflows.md](references/workflows.md) for platform/admin query plans.
+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-reference.md](../shared/zeyos-entity-reference.md) for the full source-backed model. Read [references/workflows.md](references/workflows.md) for platform/admin query plans.
 
 Typical prompts:
 
@@ -26,7 +26,7 @@ Typical prompts:
 3. Use:
    - `applications`, `resources`, `services`, `weblets`, `forks` for platform structure
    - `groups`, `groups2users`, `permissions` for access control (`groups2users` -> `listGroupsToUsers` / `getGroupToUser`)
-   - `customfields`, `objects`, and extdata helper families for schema and custom data (`customfields` -> `listCustomFields`; `applicationassets` -> `listApplicationAssets`; these dbref nouns do not map naively — see [../shared/zeyos-entity-reference.md](../shared/zeyos-entity-reference.md#entity-noun-to-rest-operationid))
+   - `customfields`, `objects`, and extdata helper families for schema and custom data (`customfields` is exposed in the CLI as `customfields` for read/count; in the JS client it maps to `listCustomFields`; `applicationassets` -> `listApplicationAssets`; these dbref nouns do not map naively — see [../shared/zeyos-entity-reference.md](../shared/zeyos-entity-reference.md#entity-noun-to-rest-operationid))
 4. Treat `records`, `comments`, `files`, `channels`, `follows`, and `likes` as a collaboration layer. Switch to `zeyos-collaboration-and-activity` when the user asks for timeline or discussion behavior rather than platform structure.
 5. Be explicit when the schema tells you structure but not the product convention.
 

package/agents/zeyos-platform-and-schema/references/workflows.md

@@ -22,6 +22,30 @@ These are dbref nouns, not operationIds. Several diverge: `applicationassets` ->
 [../../shared/zeyos-entity-reference.md](../../shared/zeyos-entity-reference.md#entity-noun-to-rest-operationid)
 before calling `@zeyos/client`.
 
+## First Commands For Counts
+
+- All custom fields: `zeyos count customfields --json`
+- Custom fields for tickets: `zeyos count customfields --filter '{"entity":"tickets"}' --json`
+
+`customfields` is read-only and has no `visibility` field. In the JS client the list
+operation is `listCustomFields`, not `listCustomfields`.
+
+For a total count, use the `count` value from the CLI JSON response. Do not answer `0`
+because `customfields` is missing from an old CLI registry, because a command failed, or
+because `zeyos resources` did not list it. If `zeyos count customfields` fails with
+"Unknown resource", run `zeyos doctor agent --json` to inspect the CLI version and then
+switch to the JavaScript client:
+
+```bash
+node --input-type=module -e 'const { createZeyosClient, normalizeListResult } = await import(`${process.env.ZEYOS_REPO_ROOT}/src/index.js`);
+const client = createZeyosClient({
+  platform: process.env.ZEYOS_BASE_URL,
+  auth: { mode: "oauth", oauth: { token: { accessToken: process.env.ZEYOS_TOKEN }, autoRefresh: false } }
+});
+const rows = normalizeListResult(await client.api.listCustomFields({ limit: 10000 })).data;
+console.log(rows.length);'
+```
+
 ## Pattern: Custom Fields For An Entity
 
 Use this for prompts like:

package/agents/zeyos-time-tracking/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: zeyos-time-tracking
+description: First-person personal work and interactive time logging in ZeyOS. Use when the user speaks about their own work ("what are my current tickets?", "what's on my plate?", "what am I working on?", "my open tasks", "my action steps") or wants to record/log/book time or effort ("log 60 minutes for client XYZ", "record 2 hours on ticket 812", "book time against Project Atlas"). Resolves the current user, finds the right account and the candidate ticket/task/project to attach time to, confirms the target with the user, then writes the time entry as an actionstep with `effort`.
+---
+
+# ZeyOS Time Tracking
+
+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 [references/workflows.md](references/workflows.md) for the concrete query and write patterns. This skill overlaps with [../zeyos-work-management/SKILL.md](../zeyos-work-management/SKILL.md): use **work-management** for third-person, analytical queries about other people's queues, project tracing, and effort *summaries*; use **time-tracking** when the request is **first-person** ("my …") or is about **recording new time**.
+
+Typical prompts:
+
+- "What are my current tickets?" / "What's on my plate?" / "What am I working on?"
+- "Show my open tasks." / "What action steps are assigned to me?"
+- "Log 60 minutes of work for client XYZ."
+- "Record 2 hours on ticket 812." / "Book 90 minutes against Project Atlas."
+- "Log half an hour for ACME, I was on a call about the renewal."
+- "How much time did I log this week?" / "Summarize my logged hours by account."
+- "Actually make that 90 minutes, not 60." / "Move that time to ticket 813."
+
+## Two jobs
+
+1. **Read "my work"** — resolve the current user, then list their open tickets / tasks / action steps. Read-only; just run it.
+2. **Log time (a write)** — resolve *who* the time is for, *what* it attaches to, then create one `actionstep` carrying the effort. This is interactive and confirmed.
+
+## The current user
+
+The logged-in user's id is `getUserInfo().sub` — a stringified positive integer that **is** the `users.ID`. Get it from `zeyos whoami --json` (read the `sub` field) before any "my …" query, and use it as `assigneduser` on the work resources. Do not guess it and do not ask the user for it.
+
+## Interactive discipline (this is the point of the skill)
+
+Interactivity here means **act first, then ask only when real data is ambiguous** — never the planning-instead-of-running failure the operating guide warns about.
+
+1. **Always run the resolution queries before asking anything.** "I found 3 accounts matching 'XYZ' — which one?" is good (grounded in a query you ran). "Which account do you mean?" with no search behind it is not.
+2. **Ask only when the data is genuinely ambiguous** and the answer changes the write: multiple account matches, or several plausible tickets/tasks. A single unambiguous match needs no question — state it and continue.
+3. **Confirm the target before the write.** Time logging creates a record. The user's "log 60 minutes" authorizes *one* entry; the confirmation is about *where* it lands (which work item) and *what* it says — show the actionstep you are about to create and let the user correct it.
+4. **Never invent the attachment.** If you cannot resolve a confident target and there is no human to ask (e.g. an automated run), stop and report what you found rather than guessing a foreign key for a write.
+
+## Safety
+
+- Read views are read-only; run them directly.
+- Logging time is a **create**, allowed because the user explicitly asked to log it. Preview with `--query` and confirm the target first; create exactly one record; then read it back.
+- Never delete or bulk-modify time entries on a category ("clear my logged time", "remove old entries") — those are per-record, by id, after preview. See the destructive-operations rules in [../zeyos-work-management/SKILL.md](../zeyos-work-management/SKILL.md).
+
+## Output discipline
+
+- For "my work": state the resolved user and the open-status definition you used, then the list.
+- For a logged entry: report the created actionstep id, the attached record (ticket/task/account), the effort in minutes, and the date.
+- Separate what you resolved from what you assumed; call out any account or work-item ambiguity you had to break.

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

@@ -5,7 +5,9 @@ description: Manage ZeyOS tickets, tasks, projects, action steps, assignees, and
 
 # ZeyOS Work Management
 
-Read [../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.
+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:
 
@@ -13,6 +15,7 @@ Typical prompts:
 - "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/01-getting-started.md

@@ -143,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