@zeyos/client 0.4.0 → 0.6.0

package/agents/zeyos-collections-and-dunning/SKILL.md

@@ -26,7 +26,9 @@ Typical prompts:
 3. Use the correct primary resource:
    - `transactions` for invoice and credit obligations
    - `payments` for cash actually received
-   - `dunning` and `dunning2transactions` for reminder and notice state (operationIds: `listDunningNotices`, `listDunningToTransactions` — these dbref nouns do not map naively; see [../shared/zeyos-entity-reference.md](../shared/zeyos-entity-reference.md#entity-noun-to-rest-operationid))
+   - `dunning` and `dunning2transactions` for reminder and notice state. In the CLI, use
+     `zeyos count/list dunning` and `zeyos list dunning2transactions`; in `@zeyos/client`,
+     call `listDunningNotices` and `listDunningToTransactions`.
 4. State what "overdue" means in the answer:
    - past `duedate`
    - unpaid or not fully settled

package/agents/zeyos-collections-and-dunning/references/workflows.md

@@ -2,8 +2,9 @@
 
 ## Primary Resources
 
-The DB-table noun is not the operationId. Use the operationIds below with `@zeyos/client`
-(`client.api.<operationId>(...)`); see [../../shared/zeyos-entity-reference.md](../../shared/zeyos-entity-reference.md#entity-noun-to-rest-operationid) for the full mapping.
+The DB-table noun is not always the operationId. Use the CLI resource names below for
+`zeyos count/list ...`; use the operationIds below with `@zeyos/client`
+(`client.api.<operationId>(...)`). See [../../shared/zeyos-entity-reference.md](../../shared/zeyos-entity-reference.md#entity-noun-to-rest-operationid) for the full mapping.
 
 | Concept | dbref noun | list operationId | single-record operationIds |
 |---------|------------|------------------|----------------------------|
@@ -14,8 +15,10 @@ The DB-table noun is not the operationId. Use the operationIds below with `@zeyo
 | Dunning-to-transaction links | `dunning2transactions` | `listDunningToTransactions` | `getDunningToTransaction`, `createDunningToTransaction`, `deleteDunningToTransaction` |
 
 Note: `dunning` is the **`DunningNotice`** entity (not `Dunning`), and `dunning2transactions`
-is the `DunningToTransaction` junction. Calling `client.api.listDunning(...)` or
-`client.api.listDunning2transactions(...)` will fail with "operation not found".
+is the `DunningToTransaction` junction. The CLI maps those nouns directly, so
+`zeyos count dunning` is the shortest path for a notice count. Calling
+`client.api.listDunning(...)` or `client.api.listDunning2transactions(...)` will fail with
+"operation not found"; use the operationIds in the table when writing JavaScript.
 
 ## Important Status Caution
 

package/agents/zeyos-data-quality-and-governance/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: zeyos-data-quality-and-governance
+description: Detect duplicate accounts, completeness gaps, stale data and schema hygiene issues in ZeyOS, and produce safe, explainable remediation previews. Use for "find duplicate customer accounts", "which customers are missing billing addresses", "show stale contacts with no email", "clean up duplicate records", "which custom fields are unused". Read-only by default — detection is separate from remediation, which requires a human decision per record.
+---
+
+# ZeyOS Data Quality and Governance
+
+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. See the OKF `playbooks/duplicate-account-review` playbook and `concepts/null-empty-missing` concept.
+Read [references/workflows.md](references/workflows.md) for concrete duplicate, anti-join,
+and remediation-preview query plans.
+
+> **Detection is not remediation.** Find and explain; never bulk-merge, archive or delete
+> from a fuzzy match. Each fix is a human decision on a named ID.
+
+Primary entities (cross-domain): `accounts`, `contacts`, `addresses`, `users`, `customfields`, `objects`, plus the domain records the user names.
+
+Typical prompts:
+
+- "Find duplicate customer accounts."
+- "Which customers are missing billing addresses?"
+- "Show stale contacts with no email."
+- "Clean up duplicate records." (→ becomes a preview, not an action)
+- "Which custom fields are unused or inconsistent?"
+
+## Workflow
+
+1. Define the population and the active/archived scope (R-012).
+2. Normalize comparison fields (lowercase, trim) **without losing the original values** (R-020).
+3. Generate candidate pairs from deterministic evidence and **score + explain** each:
+   - exact customer number → strong
+   - exact normalized email (incl. via `contacts`) → strong
+   - exact normalized name/address → strong
+   - near/fuzzy name only → weak (low confidence)
+4. Sort candidates by score descending; label confidence high/medium/low.
+5. Keep detection separate from remediation. For a "clean up" request, return a bounded
+   preview: exact IDs + proposed per-ID action, and request a human decision (R-009, R-023).
+6. Re-query after any approved, bounded remediation.
+
+## Fast Path: Missing Billing Addresses
+
+For "active customers whose name starts with X and missing a billing address", use
+`accounts.lastname` with the ZeyOS pattern operator. Do **not** invent `name`,
+`name_starts`, or `lastname_starts` filters.
+If the prompt already states that billing is address type `1`, shipping is type `0`, and
+`addresses` has no visibility column, skip schema discovery and run the two list queries.
+Batch address lookup with `account:[ids]`; do not loop one account at a time.
+
+```bash
+zeyos list accounts --filter '{"type":1,"visibility":0,"lastname":{"~~*":"<prefix>%"}}' --fields ID,lastname --limit 1000 --json
+zeyos list addresses --filter '{"account":[<accountIds>],"type":[0,1]}' --fields ID,account,type --limit 1000 --json
+```
+
+`addresses` has no `visibility` column. Keep accounts with no type `1` address; derive
+`has_shipping` from presence of a type `0` address.
+
+## Safety
+
+- Read-only by default.
+- No automated merge until ZeyOS exposes a documented, reversible merge operation.
+- Never bulk archive/delete from fuzzy matching (R-009, R-011).
+- Never treat a shared generic email domain or similar name as conclusive.
+- Preserve source IDs and explain confidence (R-020).

package/agents/zeyos-data-quality-and-governance/references/workflows.md

@@ -0,0 +1,59 @@
+# Data Quality and Governance Workflows
+
+## Duplicate-account detection (deterministic scoring)
+
+1. Pull the active population:
+
+   ```bash
+   zeyos list accounts --filter '{"type":1,"visibility":0}' \
+     --fields ID,customernum,lastname,firstname --limit 10000 --json
+   ```
+
+2. Normalize comparison keys (lowercase, trim, collapse whitespace) but keep originals.
+3. Score candidate pairs with a published, deterministic policy:
+
+   | Evidence | Weight | Confidence |
+   |---|---|---|
+   | Exact `customernum` | 1.0 | high |
+   | Exact normalized email (via `contacts`) | 0.9 | high |
+   | Exact normalized name + address | 0.8 | high |
+   | Near name only (edit distance) | 0.4 | low |
+
+4. Sort pairs by score descending; emit `{accountA, accountB, score, reasons, confidence}`.
+   A clearly different account is not a candidate. Shared generic email domains and similar
+   names are never conclusive on their own.
+
+## Completeness gaps (anti-join)
+
+"Customers missing a billing address": list customers, list `addresses` of `type: 1`
+(billing), keep customers with no matching `account`. `addresses` has **no** `visibility`
+column — do not filter it. For scoped/prefix tasks, batch address lookup with
+`account:[ids]`; do not loop one account at a time. Use:
+
+```bash
+zeyos list accounts --filter '{"type":1,"visibility":0,"lastname":{"~~*":"<prefix>%"}}' --fields ID,lastname --limit 1000 --json
+zeyos list addresses --filter '{"account":[<accountIds>],"type":[0,1]}' --fields ID,account,type --limit 1000 --json
+```
+
+State whether you treat empty string, null and missing the same (R-020); by default they
+are distinct.
+
+## Remediation is a preview, not an action
+
+A "clean up duplicates" request returns:
+
+```json
+{ "executed": false,
+  "candidates": [ { "accountA": 1, "accountB": 2 } ],
+  "proposedActions": [ { "accountId": 2, "action": "archive (needs human review)" } ] }
+```
+
+Never delete, archive or merge from this analysis (R-009, R-011, R-023). Each action is a
+human decision on an exact ID. Re-query only after an approved, bounded change.
+
+## Common failure modes
+
+- Treating a fuzzy name match as a confirmed duplicate.
+- Collapsing null / empty / zero into one bucket without saying so.
+- Executing a bulk archive/delete from a "clean up" instruction.
+- Filtering `visibility` on `addresses` (no such column → HTTP 400).

package/agents/zeyos-document-and-approval/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: zeyos-document-and-approval
+description: Find formal ZeyOS documents, judge draft/final/obsolete status, run approval and finalization gates, and compare notes against formal SOPs. Use when status transitions, approval authority, version choice or formal file artifacts matter ("find the current approved onboarding SOP", "which contracts await approval", "make document 812 final", "compare the draft with the final version"). For lightweight note retrieval use zeyos-notes-and-sops.
+---
+
+# ZeyOS Document and Approval
+
+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. See the OKF `concepts/official-versus-latest` concept and the `playbooks/document-approval` playbook.
+
+> **Status, not freshness, decides authority.** The newest artifact is not necessarily the
+> current official one. Retrieve content before claiming what a document says.
+
+Primary entities: `documents` (`listDocuments`, `getDocument`, `createDocument`, `updateDocument`), `notes` (`listNotes`, `getNote`), `binfiles` (`listBinFiles`), `files`, plus `users`/`groups` for approval context. Document `status`: 0 DRAFT, 1 FEEDBACKREQUIRED, 2 INREVISION, 3 AWAITINGAPPROVAL, 4 FINAL, 5 OBSOLETE.
+
+Typical prompts:
+
+- "Find the current approved onboarding SOP."
+- "Which contracts are awaiting approval?"
+- "Compare the draft with the final version."
+- "Make document 812 final."
+
+## Workflow
+
+1. Search formal `documents` first for "official", "approved", "final" or "current".
+2. Select by **status plus freshness** — a FINAL document outranks a newer OBSOLETE one and a draft note (R-018).
+3. Retrieve binary/file content (`binfile`/`files`) before claiming its contents.
+4. Keep `notes` (lightweight) and `documents` (formal) as separate sources; do not silently merge conflicting sources (surface the conflict, name the authoritative source).
+5. For finalization/approval: fetch the exact ID + current status, show a preview and any naming conflict, require exact confirmation, `updateDocument` one ID, then re-read and report old/new status (R-005, R-006, R-011).
+
+## Routing boundaries
+
+- Note-centric retrieval/summarization → `zeyos-notes-and-sops`.
+- Use this skill when status transitions, approval authority, version choice or formal files matter.
+
+## Safety
+
+- FINAL, APPROVED, OBSOLETE and cancellation transitions are high impact (R-011).
+- Never approve on behalf of an unidentified user/group.
+- Never bulk-finalize or bulk-obsolete documents (R-009).
+- Never overwrite a binary file without an explicit target and confirmation.
+- Preserve provenance and revision identifiers in summaries.

package/agents/zeyos-document-and-approval/references/workflows.md

@@ -0,0 +1,43 @@
+# Document and Approval Workflows
+
+## Select the current official artifact
+
+1. Query formal `documents` matching the topic; read `status`, `name`, `documentnum`, `filename`.
+
+   ```bash
+   zeyos list documents --filter '{"visibility":0,"name":{"~~*":"onboarding%"}}' \
+     --fields ID,name,status,filename,documentnum --limit 100 --json
+   ```
+
+2. Rank by authority, not date: prefer `status = 4` (FINAL). A newer `status = 5`
+   (OBSOLETE) does **not** win, and a draft `note` is only fallback context (R-018).
+3. State the selection reason (which status, why it outranks the alternatives).
+
+## Compare a note against a formal SOP
+
+Retrieve the actual text of both (`notes.text`; `documents.description`/binary content).
+Report agreements and conflicts explicitly; never synthesize a single answer that hides a
+contradiction. The formal FINAL document is the authoritative source.
+
+## Finalization / approval gate
+
+```bash
+# 1. Fetch exact target + current status
+zeyos get document <id> --json
+# 2. Preview the change (no write) and surface any same-name conflict
+zeyos update document <id> --query --status 4
+# 3. Only after explicit confirmation of the exact ID:
+zeyos update document <id> --status 4
+# 4. Re-read and report old/new status
+zeyos get document <id> --fields ID,name,status --json
+```
+
+Update exactly one ID. Never fuzzy-match a name to a set of documents and finalize them in
+bulk (R-009, R-011). Leave similarly-named documents untouched.
+
+## Common failure modes
+
+- Picking the newest artifact instead of the FINAL one.
+- Claiming document contents without retrieving the file/binary.
+- Bulk-finalizing by fuzzy name match.
+- Approving without identifying the approver / authority.

package/agents/zeyos-mail-operations/SKILL.md

@@ -28,6 +28,27 @@ Typical prompts:
 7. Treat textual drafts as safe. Treat message record creation/update as a write and sending or marking `mailbox=2` as high risk; require explicit confirmation plus verified sender context before any real mail mutation.
 8. Escalate to `@zeyos/client` when you need binary content, MIME expansion, or richer message correlation than the CLI can express cleanly.
 
+## Fast Path: Unanswered Inbox Count On Open Tickets
+
+For "how many inbox messages (`mailbox` 0) are linked to open tickets and still
+unanswered", use the workflow directly. This is a joined count, not a simple
+`zeyos count messages` task.
+
+If the prompt already states mailbox values and closed ticket statuses, skip schema
+discovery. Do **not** use `notin`, `status_neq`, or `messageid` for this count.
+Use the CLI commands below directly; do not write a scratch JavaScript client script for
+this count because the CLI normalizes array filters to the API's native `IN` operator.
+
+```bash
+zeyos list tickets --fields ID,status --filter '{"visibility":0,"status":[0,1,2,3,4,5,6,7,11]}' --limit 10000 --json
+zeyos list messages --fields ID,ticket,reference,date --filter '{"mailbox":0,"ticket":[<ticketIds>]}' --limit 10000 --json
+zeyos list messages --fields ID,ticket,reference,date --filter '{"mailbox":2,"ticket":[<ticketIds>]}' --limit 10000 --json
+```
+
+Count inbound rows where no sent row has the same `ticket`, `reference == inbound.ID`,
+and `sent.date >= inbound.date`. Do not run a separate raw inbox count after listing the
+rows; the join logic is the answer.
+
 ## Safety
 
 - Never send email from an agent test or from a summary/draft request.

package/agents/zeyos-mail-operations/references/workflows.md

@@ -98,6 +98,26 @@ Recommended approach:
 
 For an operational count, use this exact definition unless the user specifies another one: inbox message (`mailbox = 0`) linked to an open ticket, with no later sent message (`mailbox = 2`) whose `reference` points back to that inbound message.
 
+Fast path for "how many inbox messages on open tickets are still unanswered":
+
+1. If the prompt already states mailbox values and closed ticket statuses, skip schema
+   discovery. Do not use `notin`; open tickets are status `IN [0,1,2,3,4,5,6,7,11]`
+   with `visibility:0`.
+   Use the CLI commands below directly; do not write a scratch JavaScript client script
+   for this count because the CLI normalizes array filters to the API's native `IN`
+   operator.
+2. Query open ticket IDs once:
+   `zeyos list tickets --fields ID,status --filter '{"visibility":0,"status":[0,1,2,3,4,5,6,7,11]}' --limit 10000 --json`
+3. Query inbox and sent messages for those ticket IDs using batched `ticket:[ids]`:
+   `zeyos list messages --fields ID,ticket,reference,date --filter '{"mailbox":0,"ticket":[<ticketIds>]}' --limit 10000 --json`
+   `zeyos list messages --fields ID,ticket,reference,date --filter '{"mailbox":2,"ticket":[<ticketIds>]}' --limit 10000 --json`
+4. Count inbound rows where no sent row has the same `ticket`, `reference == inbound.ID`,
+   and `sent.date >= inbound.date`. Do not run a separate `zeyos count messages` after
+   listing the rows; the join logic, not the raw inbox count, is the answer.
+
+For this operational count, do not select `messageid`; `ID`, `ticket`, `reference`, and
+`date` are sufficient, and some instances reject `messageid` in list field selection.
+
 ## Pattern: Draft A Reply
 
 Use this for prompts like:

package/agents/zeyos-procurement-and-supplier-performance/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: zeyos-procurement-and-supplier-performance
+description: Compare suppliers, analyze procurement orders/deliveries/invoices, lead times, price variance and reorder worklists in ZeyOS. Use for "which supplier is best for 20 units of item ABC", "which purchase orders are late", "compare supplier delivery performance", "where did procurement prices exceed the order". Read-only analysis — never place, book, cancel or transmit a procurement transaction.
+---
+
+# ZeyOS Procurement and Supplier Performance
+
+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. See the OKF `playbooks/supplier-scorecard` playbook and `metrics/supplier-delivery-performance` metric.
+
+> **Keep ordered, delivered and invoiced quantities/values distinct**, and state the
+> ranking policy before you rank. Analysis is read-only.
+
+Primary entities: `transactions` types **5 PROCUREMENT_REQUEST, 6 ORDER, 7 DELIVERY, 8 INVOICE, 9 CREDIT** (`listTransactions`), `suppliers` (item↔supplier links: `listSuppliers`), `items`, `accounts` (the supplier), `stocktransactions`, `storages`, `payments`, and `contracts` where supplier agreements matter. `transactions` has **no** `visibility` column.
+
+Typical prompts:
+
+- "Which supplier is best for 20 units of item ABC?"
+- "Which purchase orders are late?"
+- "Compare supplier delivery performance."
+- "Where did procurement prices exceed the order?"
+
+## Workflow
+
+1. Resolve the item and the supplier `accounts` (type 2 SUPPLIER).
+2. For sourcing decisions, read `suppliers` links: `price`, `minamount`, `deliverytime`, `stock`.
+3. Apply the order quantity: a supplier is eligible only if `minamount <= quantity` — never hide a minimum-quantity constraint (R-003).
+4. State the ranking policy first (e.g. eligible, then price ascending, then delivery time), then rank.
+5. For performance, keep ordered (type 6), delivered (type 7) and invoiced (type 8) values separate; compute price variance as invoiced − ordered.
+6. Compute only over a declared time window and one currency (R-014, R-019). Exclude cancelled records by documented status policy.
+7. Label reorder advice as heuristic unless a formal stock policy exists.
+
+## Safety
+
+- Never place, approve, book, cancel or transmit a procurement transaction automatically (R-010, R-011).
+- Never change supplier master data or price lists from an analytical request.
+- Any future write workflow requires exact supplier, item, quantity, currency and confirmation.

package/agents/zeyos-procurement-and-supplier-performance/references/workflows.md

@@ -0,0 +1,46 @@
+# Procurement and Supplier Performance Workflows
+
+## Procurement transaction types
+
+`transactions.type`: 5 PROCUREMENT_REQUEST, 6 PROCUREMENT_ORDER, 7 PROCUREMENT_DELIVERY,
+8 PROCUREMENT_INVOICE, 9 PROCUREMENT_CREDIT. (Billing types 0–4 are a different domain.)
+`transactions` has **no** `visibility` column — do not add `"visibility":0`.
+
+## Supplier comparison for an order quantity
+
+1. Resolve the item, then read its supplier links:
+
+   ```bash
+   zeyos list suppliers --filter '{"item":<itemId>}' \
+     --fields ID,account,price,minamount,deliverytime,stock --limit 1000 --json
+   ```
+
+2. Resolve each `account` to a supplier name.
+3. Eligibility: `minamount <= orderQuantity`. State eligibility explicitly — never drop a
+   supplier silently because of its minimum.
+4. Ranking policy (declare before ranking): eligible first, then `price` ascending, then
+   `deliverytime` ascending. Report `rank` and `eligible` per option.
+
+## Supplier scorecard over a period
+
+Group procurement `transactions` by supplier `account` within a declared window + currency:
+
+- `ordered_value` = Σ `netamount` where type 6
+- `invoiced_value` = Σ `netamount` where type 8
+- `price_variance` = invoiced_value − ordered_value
+- delivery timing from type 7 dates vs the order `duedate` (on-time when delivered by duedate)
+
+Keep all values in one currency (R-019); exclude cancelled records per documented policy.
+
+## Reorder advice
+
+Label reorder suggestions as heuristic unless the instance has a formal stock policy
+(min/max levels). Combine `stocktransactions` net-booked stock by `storages` with supplier
+`deliverytime` to flag at-risk items — but present it as advice, not an action.
+
+## Common failure modes
+
+- Mixing billing types (0–4) with procurement types (5–9).
+- Hiding a minimum-order-quantity constraint when ranking.
+- Conflating ordered, delivered and invoiced values.
+- Summing across currencies.

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

@@ -15,6 +15,7 @@ Typical prompts:
 - "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."
+- "Give me a summary of logged ticket time from the last four weeks."
 - "Actually make that 90 minutes, not 60." / "Move that time to ticket 813."
 
 ## Two jobs
@@ -44,5 +45,6 @@ Interactivity here means **act first, then ask only when real data is ambiguous*
 ## Output discipline
 
 - For "my work": state the resolved user and the open-status definition you used, then the list.
+- For ticket time summaries: include both actionsteps directly linked by `actionstep.ticket` and actionsteps linked by `actionstep.task` where `task.ticket` is the summarized ticket; dedupe by actionstep ID before summing.
 - 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

@@ -17,6 +17,7 @@ See [../../shared/zeyos-entity-reference.md](../../shared/zeyos-entity-reference
 
 - **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`.
+- **Ticket time rollups cross the task layer.** For "logged ticket time", count actionsteps with `ticket = <ticketId>` and actionsteps with `task = <taskId>` where that task has `ticket = <ticketId>`. Always dedupe by actionstep `ID` before summing in case a row carries both FKs.
 - **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).
@@ -195,6 +196,72 @@ 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: "Give me a summary of logged ticket time from the last four weeks"
+
+Use this whenever the user asks for ticket time, ticket hours, support time by ticket, or a ticket-level timesheet summary. A time entry can be attached directly to a ticket or indirectly to a task that belongs to a ticket; both are ticket time.
+
+1. Resolve the date window to Unix seconds and count only `actionsteps.status IN [1,3]` unless the user explicitly asks for drafts/open follow-ups.
+2. If the user named a specific ticket, resolve it first, then query:
+
+   ```bash
+   # direct ticket time
+   zeyos list actionsteps \
+     --fields ID,name,effort,date,status,ticket,task,assigneduser \
+     --filter '{"ticket":<ticketId>,"status":{"IN":[1,3]},"date":{">=":<start>,"<=":<end>}}' \
+     --limit 10000 --json
+
+   # tasks that belong to the ticket; do not filter task status for historical time
+   zeyos list tasks \
+     --fields ID,tasknum,name,ticket \
+     --filter '{"ticket":<ticketId>}' \
+     --limit 10000 --json
+
+   # time logged on those tasks
+   zeyos list actionsteps \
+     --fields ID,name,effort,date,status,ticket,task,assigneduser \
+     --filter '{"task":{"IN":[<taskIds>]},"status":{"IN":[1,3]},"date":{">=":<start>,"<=":<end>}}' \
+     --limit 10000 --json
+   ```
+
+3. If the user asks for all ticket time in a period, list actionsteps in the window with `ticket` and `task`, then resolve every referenced task to `task.ticket` and group by the resulting ticket ID. Page through results if the window is large.
+4. Build each actionstep's ticket attribution:
+   - direct row: `actionstep.ticket`
+   - task row: `taskById[actionstep.task].ticket`
+   - both present: count the actionstep once; prefer the direct ticket if it conflicts and call out the conflict
+   - neither present: keep it out of the ticket-time total unless reporting an "unassigned/general time" bucket
+5. Dedupe by actionstep `ID`, sum `effort` in minutes, and resolve ticket labels (`ticketnum`, `name`, `account.lastname`) for the summary.
+
+Client shape for a specific ticket:
+
+```js
+const [directRows, taskRows] = await Promise.all([
+  client.api.listActionSteps({
+    fields: ['ID', 'name', 'effort', 'date', 'status', 'ticket', 'task', 'assigneduser'],
+    filters: { ticket: ticketId, status: { IN: [1, 3] }, date: { '>=': start, '<=': end } },
+    limit: 10000,
+  }),
+  client.api.listTasks({
+    fields: ['ID', 'tasknum', 'name', 'ticket'],
+    filters: { ticket: ticketId },
+    limit: 10000,
+  }),
+]);
+
+const taskIds = taskRows.map((task) => task.ID);
+const taskTimeRows = taskIds.length
+  ? await client.api.listActionSteps({
+      fields: ['ID', 'name', 'effort', 'date', 'status', 'ticket', 'task', 'assigneduser'],
+      filters: { task: { IN: taskIds }, status: { IN: [1, 3] }, date: { '>=': start, '<=': end } },
+      limit: 10000,
+    })
+  : [];
+
+const rowsById = new Map();
+for (const row of [...directRows, ...taskTimeRows]) rowsById.set(String(row.ID), row);
+const totalMinutes = [...rowsById.values()]
+  .reduce((sum, row) => sum + (Number(row.effort) || 0), 0);
+```
+
 ## 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.
@@ -226,5 +293,6 @@ Only correct entries the user pointed to (by id, or one you just created in this
 - 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.
+- Summing only `actionstep.ticket` for ticket time — time logged on tasks with `task.ticket = <ticketId>` belongs in the ticket total too.
 - 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

@@ -30,9 +30,10 @@ Typical prompts:
 4. Follow relationships only after the primary record set is clear.
 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.
-9. Escalate from the CLI to `@zeyos/client` if the workflow needs unsupported joins, additional request control, or correlation across multiple list responses.
+7. For logged ticket-time summaries, include actionsteps directly linked to the ticket and actionsteps linked to tasks whose `task.ticket` is that ticket; dedupe actionstep IDs before summing.
+8. When the question is really about account or transaction follow-up, check `actionsteps` before inventing a new task.
+9. For mutations, preview the affected record first and update with an explicit PATCH body.
+10. Escalate from the CLI to `@zeyos/client` if the workflow needs unsupported joins, additional request control, or correlation across multiple list responses.
 
 ## Destructive Operations
 

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

@@ -155,11 +155,33 @@ For counts:
 zeyos count actionsteps --filter '{"ticket":812,"status":0}' --json
 ```
 
+For unanchored due-date counts, first narrow by equality filters and due-date presence
+server-side. The API can return misleading zero counts for comparison filters like
+`{"duedate":{"<=":4102444800}}`, and `duedate:null` is not a due item. If the
+presence count is zero, the due-date count is zero.
+
+```bash
+zeyos count actionsteps --filter '{"status":0,"duedate":{"!=":null}}' --json
+```
+
+If due dates exist, list those rows and count the timestamp range client-side.
+
+```bash
+zeyos list actionsteps \
+  --fields ID,status,duedate \
+  --filter '{"status":0,"duedate":{"!=":null}}' \
+  --limit 10000 \
+  --json
+```
+
+Then parse the JSON and count rows where `duedate != null && Number(duedate) <= cutoff`.
+
 ## Pattern: Time Entry / Effort Summaries
 
 Use this for prompts like:
 
 - "How many minutes were booked on ticket 812 last week?"
+- "Give me a summary of logged ticket time from the last four weeks."
 - "Summarize completed actionstep effort for this account."
 - "Which user logged effort against this project?"
 
@@ -168,8 +190,47 @@ 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.
+4. For a simple ungrouped total, run `zeyos sum actionsteps effort --filter '{"status":[1,3]}'`.
+   For anchored or grouped totals, list the needed rows and sum `effort` as minutes.
+   Convert to hours only if the user asked for hours.
+5. For ticket-level totals, roll task time up to the ticket:
+   - direct ticket time is `actionsteps.ticket = <ticketId>`
+   - task ticket time is `actionsteps.task = <taskId>` where `tasks.ticket = <ticketId>`
+   - fetch tasks by `ticket` for a named ticket, or resolve every referenced `actionstep.task` to `task.ticket` for a period-wide ticket summary
+   - do not filter tasks by status when resolving historical time; a completed task can still carry valid logged time
+   - dedupe by `actionsteps.ID` before summing in case a row has both `ticket` and `task`
+6. Keep task/ticket assignment separate from effort totals.
+
+Ticket-specific client example:
+
+```js
+const [directRows, tasks] = await Promise.all([
+  client.api.listActionSteps({
+    fields: ['ID', 'date', 'status', 'effort', 'ticket', 'task', 'assigneduser'],
+    filters: { ticket: ticketId, status: { IN: [1, 3] }, date: { '>=': start, '<=': end } },
+    limit: 10000,
+  }),
+  client.api.listTasks({
+    fields: ['ID', 'ticket', 'name'],
+    filters: { ticket: ticketId },
+    limit: 10000,
+  }),
+]);
+
+const taskIds = tasks.map((task) => task.ID);
+const taskRows = taskIds.length
+  ? await client.api.listActionSteps({
+      fields: ['ID', 'date', 'status', 'effort', 'ticket', 'task', 'assigneduser'],
+      filters: { task: { IN: taskIds }, status: { IN: [1, 3] }, date: { '>=': start, '<=': end } },
+      limit: 10000,
+    })
+  : [];
+
+const uniqueRows = new Map();
+for (const row of [...directRows, ...taskRows]) uniqueRows.set(String(row.ID), row);
+const totalMinutes = [...uniqueRows.values()]
+  .reduce((sum, row) => sum + (Number(row.effort) || 0), 0);
+```
 
 ## Pattern: Create Follow-Up Work