@zeyos/client 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -3,6 +3,43 @@
 Notable changes to `@zeyos/client` and `@zeyos/cli`. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## 0.6.0
+
+### `@zeyos/cli` (`zeyos`)
+- Added direct resource coverage and aliases for common API nouns whose generated
+  operationIds differ from user-facing names, including group/user junctions,
+  mailing lists/recipients, price lists, price-list account junctions, prices,
+  and dunning junction aliases.
+- Expanded forgiving filter normalization for agent and shell workflows:
+  Mongo-style operators, bare comparison operators, array-to-`IN`, suffix forms
+  such as `field__in`/`field__nin`/`field__like`, and negative-set filters now
+  normalize to the native ZeyOS request shape and remain visible in dry-run JSON.
+- Expanded `zeyos sum` coverage and regression tests for actionsteps, payments,
+  and transactions, including the documented actionsteps oversized-page failure
+  mode.
+
+### Agent skills (shipped)
+- The generic ZeyOS entrypoint is slash-command-free and explicitly supports direct
+  execution for simple counts once the resource and filter constraints are clear.
+- Shared guidance now prefers `zeyos sum` for simple ungrouped totals while keeping
+  manual aggregation for grouped, joined, or conditional totals.
+
+### Agent test protocol (dev-only)
+- The fixed benchmark mode is now DeepSeek-only
+  (`openrouter/deepseek/deepseek-v4-flash`) and defaults to one-attempt strict
+  data (`--transient-retries 0`), while normal report runs can still use transient
+  retries.
+- Added efficiency budgets for direct count, b14, b22, dunning, mail, and sum
+  scenarios; pass-but-expensive cases are now separated from correctness defects
+  in Markdown and HTML scorecards.
+- Added transcript leakage detection for user-home/global skill paths and classifies
+  those runs as `ENVIRONMENT_DEFECT`.
+- Hardened RESULT parsing/output-contract checks for Markdown-wrapped markers and
+  file-output mistakes.
+- Added complex collections and mail regression scenarios and coverage for minimal
+  query shape, zero API errors, API-call budgets, provider/runner failure clarity,
+  and token/cost capture.
+
 ## 0.5.0
 
 ### `@zeyos/cli` (`zeyos`)

package/README.md

@@ -42,6 +42,7 @@ zeyos login --base-url https://cloud.zeyos.com/demo --client-id myapp --secret "
 # Read and write
 zeyos list tickets --filter '{"status":4}' --sort -lastmodified --limit 10
 zeyos count tickets --filter '{"status":4}'
+zeyos sum actionsteps effort --filter '{"status":[1,3]}'
 zeyos get ticket 42 --all
 zeyos create ticket --name "Fix login bug" --status 0 --priority 3
 zeyos update ticket 42 --status 9
@@ -200,6 +201,7 @@ zeyos <command> [options] [args…]
 | `whoami` | Show the authenticated user | `zeyos whoami --json` |
 | `list <resource>` | List / query records | `zeyos list tickets --filter '{"status":4}' --sort -lastmodified` |
 | `count <resource>` | Count records (true total) | `zeyos count tickets --filter '{"status":4}'` |
+| `sum <resource> <field>` | Sum a numeric field across matching records | `zeyos sum actionsteps effort --filter '{"status":[1,3]}'` |
 | `get <resource> <id>` | Fetch one record (`show` is an alias) | `zeyos get ticket 42 --all` |
 | `create <resource>` | Create a record | `zeyos create ticket --name "Bug" --status 0 --priority 3` |
 | `update <resource> <id>` | Update a record (`edit` is an alias) | `zeyos update ticket 42 --status 9` |
@@ -221,6 +223,10 @@ zeyos list accounts --fields '{"Name": "lastname", "City": "contact.city"}'
 # Filtering (JSON object) and sorting (prefix - for descending)
 zeyos list tickets --filter '{"status":4,"priority":4}' --sort -lastmodified
 
+# Agent-friendly filter normalization: arrays become IN, Mongo/suffix operators
+# are normalized before the request is sent and are visible with --query --json.
+zeyos list tickets --filter '{"status":{"$nin":[8,9,10]},"priority":[3,4]}' --query --json
+
 # Pagination
 zeyos list tickets --limit 100 --offset 100
 ```

package/agents/shared/zeyos-agent-operating-guide.md

@@ -41,21 +41,29 @@ and `zeyos resources` are offline and safe for orienting yourself.
 When you only have this skill text and a shell, keep the loop small:
 
 1. Pick the resource from the domain workflow.
-2. If the question says "how many", run `zeyos count …` first.
+2. If the question says "how many" and one filtered resource directly answers it, run
+   `zeyos count …` first. Joined/anti-join counts (for example unanswered mail, missing
+   related records, or "with no later reply") need the domain workflow instead.
 3. Put filters inline as single-quoted JSON: `--filter '{"visibility":0}'`.
 4. If a field is uncertain, run `zeyos describe <resource>` before filtering on it.
 5. Never answer from a plan. Run the command, read stdout/stderr, then report the result.
 
+For a simple single-resource count, a successful `zeyos count <resource> ...` is the
+answer. Do not follow it with `zeyos list` just to verify the number; listing costs an
+extra API call, can hit server limits, and is only needed when the user asks for the
+records or the count fails.
+
 ## First move for the common question shapes
 
 | The user asks… | Your first command |
 |----------------|--------------------|
-| "How many X …?" | `zeyos count <resource> --filter '{…}'` |
+| "How many X …?" where one resource/filter answers it | `zeyos count <resource> --filter '{…}'` |
 | "List / show X …" | `zeyos list <resource> --filter '{…}' --fields … --json` |
 | "Details of record N" | `zeyos get <resource> <id> --json` |
 | "What fields / enums does X have?" | `zeyos describe <resource>` |
 | "Is resource X even available?" | `zeyos resources --json` |
-| A total / sum (e.g. revenue) | `zeyos list <resource> --filter '{…}' --fields … --limit 10000 --json`, then sum client-side |
+| A simple numeric total / sum | `zeyos sum <resource> <field> --filter '{…}'` |
+| A grouped or joined total | `zeyos list <resource> --filter '{…}' --fields … --limit 10000 --json`, then aggregate client-side |
 | "Will this request do what I think?" | append `--query` to any data command to print the route + JSON body **without sending it** (preview a write before running it) |
 
 Then read [zeyos-query-patterns.md](./zeyos-query-patterns.md) for the rules that make
@@ -71,6 +79,7 @@ the matching domain skill for the metric definitions.
 - Prefer inline JSON for small filters. For complex filters, `zeyos list` and
   `zeyos count` support `--filter-file <path>`, while `zeyos create` and
   `zeyos update` support `--data-file <path>`.
+- In CLI filters, arrays normalize to `IN`: `--filter '{"status":[1,3]}'`.
 - Do not pass `@filter.json` or any other response-file syntax; use the documented
   `--filter-file` / `--data-file` flags when a file is safer than inline JSON.
 - For counts, use `zeyos count <resource>` rather than `zeyos list … --json | length`.
@@ -128,7 +137,7 @@ contract above as checkable invariants.
 - **R-010 External side effects are high risk.** Email, campaign, dunning and calendar-invitation dispatch are never automatic. In protocol tests they are prohibited; interactively they require sender/audience/content/time preview and confirmation.
 - **R-011 High-impact state transitions.** Final, approved, booked, paid, cancelled, archived, deleted, sent and similar terminal states require exact target preview and confirmation.
 - **R-012 Conditional visibility.** Use `visibility:0` only when the resource exposes `visibility`; inspect the schema first.
-- **R-013 Count and sum discipline.** Use server-side count for counts. For sums, page through every matching row and aggregate the documented numeric field client-side.
+- **R-013 Count and sum discipline.** Use server-side count for counts. For simple ungrouped sums, use `zeyos sum`; for grouped, joined, or conditional sums, page through every matching row and aggregate the documented numeric field client-side.
 - **R-014 Time and timezone discipline.** ZeyOS timestamps are Unix seconds. State timezone, window boundaries and whether the end is inclusive or exclusive.
 - **R-015 Operation discovery.** Use `zeyos resources`, `zeyos describe`, `client.schema`, or OKF operation metadata before guessing resource names or operationIds.
 - **R-016 Financial basis separation.** Invoices, credits, payments, receivables and dunning are different facts. State invoiced/cash/collection basis, currency and credit treatment.

package/agents/shared/zeyos-entity-reference.md

@@ -41,10 +41,11 @@ The DB-table noun (from `dbref.json`, also the REST URL path segment) is **not**
 operationId. The `@zeyos/client` methods and the names you reason about are CamelCase
 compound operationIds, and several diverge from a naive "capitalize + pluralize the noun".
 
-**Agent rule: when calling `@zeyos/client` (`client.api.<operationId>(...)`) or constructing
-CLI resource names, use the operationIds below, not the raw `dbref.json` table noun.** Building
-`client.api.listDunning(...)` or `zeyos list dunning` from the noun will fail with
-"operation not found".
+**Agent rule: when calling `@zeyos/client` (`client.api.<operationId>(...)`), use the
+operationIds below, not the raw `dbref.json` table noun.** Building
+`client.api.listDunning(...)` from the noun will fail with "operation not found". The CLI
+accepts curated resource aliases for common divergent nouns, including
+`zeyos count/list dunning` and `zeyos list dunning2transactions`.
 
 ### The regular rule (most entities)
 

package/agents/shared/zeyos-query-patterns.md

@@ -32,6 +32,15 @@ For cross-platform benchmark guidance, read [business-app-benchmarks.md](./busin
 - CLI filters are inline JSON strings. Use `--filter '{"field":123}'`; never run the raw
   JSON as a shell command, and do not use `@filter.json` unless the CLI help explicitly
   documents response-file support.
+- CLI filter arrays normalize to `IN`, e.g. `--filter '{"status":[1,3]}'`.
+- CLI filters also normalize common negative-set aliases to native `!IN`, e.g.
+  `--filter '{"status":{"$nin":[8,9,10]}}'`.
+- Do not invent filter operators. For text search use ZeyOS' documented
+  case-insensitive LIKE operator, e.g. `{"lastname":{"~~*":"%Bureau3%"}}`; do not use
+  `contains`, `like`, or `ilike` unless `zeyos describe` documents that exact operator.
+- For numeric/date comparisons, prefer native ZeyOS operators such as `<`, `<=`, `>`,
+  and `>=`. The CLI also normalizes common Mongo-style range aliases (`$lt`, `$lte`,
+  `$gt`, `$gte`) before sending, but use the native operators in examples and docs.
 - Creating accounts requires `currency` (e.g. `"EUR"`): the column is NOT NULL with no DB default, so a create that omits it fails with an opaque HTTP 500 even though the OpenAPI spec does not mark it required. `validate('createAccount', …)` now catches this; supply a currency code. (The spec carries no required-field metadata at all, so unknown required fields can still surface only as a server-side 500 — when a create 500s, suspect a missing NOT-NULL column.)
 - Use `visibility: 0` on resources that expose a `visibility` field, unless the user explicitly wants archived or deleted records. Not every resource has the column: `tickets`, `accounts`, and `items` do; **`transactions` does not — filtering `visibility` there returns an opaque HTTP 400**. More generally, filtering on any column a resource lacks 400s with no hint which field was wrong, so filter only on fields `zeyos describe <resource>` lists.
 - Treat list operations as `POST` queries.
@@ -44,6 +53,10 @@ For cross-platform benchmark guidance, read [business-app-benchmarks.md](./busin
   - `extdata` exposes custom fields
   - `expand` inlines JSON or binary columns
 - For a "how many?" question, count server-side: `zeyos count <resource>` on the CLI, or pass `count: true` to the list call on the client (e.g. `client.api.listItems({ filters: { visibility: 0 }, count: true })`). Never use `list` + array length. `zeyos list` defaults to `--limit 50` (the client default is 1000), so counting listed rows silently returns the page size, not the total. In `--json` mode the only truncation signal is a stderr "Showing X–Y of TOTAL" hint.
+- After a successful `zeyos count`, stop and report the count. Do not run `zeyos list` as a second check unless the user also asked for records or the count command failed.
+- For a simple numeric total, use `zeyos sum <resource> <field> --filter '{...}'`; it
+  pages internally. Use `list` and aggregate yourself only for grouped, conditional,
+  joined, or per-row outputs.
 - Treat `count: true` responses defensively because wrappers vary across resources and client layers.
 - Confirm delete, send, revoke, or bulk-update actions before executing them unless the workflow is already explicitly automated.
 
@@ -68,7 +81,7 @@ Use these defaults unless the target instance clearly behaves differently:
 ## Default Resolution Patterns
 
 - Resolve a user with `users.name` or `users.email` first.
-- Resolve a customer with `accounts.customernum`, `accounts.lastname`, `accounts.firstname`, then `contacts.email` or contact name if needed.
+- Resolve a customer with `accounts.customernum`, `accounts.lastname`, `accounts.firstname`, then `contacts.email` or contact name if needed. Company names live in `accounts.lastname`; there is no generic `accounts.name` column.
 - Resolve a project with `projects.projectnum` or `projects.name`.
 - Resolve a ticket with `tickets.ticketnum` or `tickets.name`.
 - Resolve a task with `tasks.tasknum` or `tasks.name`.

package/agents/zeyos/SKILL.md

@@ -6,13 +6,47 @@ description: Read or change ZeyOS business data (accounts, contacts, tickets, ta
 # Working with ZeyOS via the CLI
 
 This is the generic, do-it-now skill for talking to a ZeyOS instance. The specialized
-`zeyos-*` skills add metric definitions and domain rules; this one just makes sure you
-**run real commands against the live instance and answer from the result**.
+`zeyos-*` skills add metric definitions and domain rules; this one routes to the right
+guide, makes sure you **run real commands against the live instance**, and answers from
+the result.
 
 Read [../shared/zeyos-agent-operating-guide.md](../shared/zeyos-agent-operating-guide.md)
 first (it establishes that you have tools and the CLI is already authenticated), then
 [../shared/zeyos-query-patterns.md](../shared/zeyos-query-patterns.md) for the query rules.
 
+## Route first, then execute
+
+When this guide is used, inspect the user request and read the matching specialized skill
+before querying. Do not depend on a runner-global slash command, do not ask the user to
+pick the skill, and do not answer from this generic guide if the request needs domain
+rules.
+
+| Request area | Read this guide |
+| --- | --- |
+| Accounts, customers, contacts, CRM profile, account type, relationship lookup | [../zeyos-account-intelligence/SKILL.md](../zeyos-account-intelligence/SKILL.md) |
+| Tickets, tasks, projects, actionstep queues, workload, third-person effort summaries | [../zeyos-work-management/SKILL.md](../zeyos-work-management/SKILL.md) |
+| First-person work ("my ...") or logging/booking time | [../zeyos-time-tracking/SKILL.md](../zeyos-time-tracking/SKILL.md) |
+| Transactions, invoices, delivery notes, revenue, payments, billing documents | [../zeyos-billing-insights/SKILL.md](../zeyos-billing-insights/SKILL.md) |
+| Dunning notices, receivables follow-up, collection state | [../zeyos-collections-and-dunning/SKILL.md](../zeyos-collections-and-dunning/SKILL.md) |
+| Items, products, catalog, stock, inventory, orders | [../zeyos-commerce-and-inventory/SKILL.md](../zeyos-commerce-and-inventory/SKILL.md) |
+| Mail, inbound/outbound messages, drafts, unanswered ticket mail | [../zeyos-mail-operations/SKILL.md](../zeyos-mail-operations/SKILL.md) |
+| Campaigns, mailing lists, outreach recipients, message reads | [../zeyos-campaign-and-outreach/SKILL.md](../zeyos-campaign-and-outreach/SKILL.md) |
+| Activity events, timeline, collaboration history | [../zeyos-collaboration-and-activity/SKILL.md](../zeyos-collaboration-and-activity/SKILL.md) |
+| Notes, SOPs, knowledge retrieval | [../zeyos-notes-and-sops/SKILL.md](../zeyos-notes-and-sops/SKILL.md) |
+| Documents, approval gates, official/latest file state | [../zeyos-document-and-approval/SKILL.md](../zeyos-document-and-approval/SKILL.md) |
+| Calendar availability, scheduling, appointment creation | [../zeyos-calendar-and-scheduling/SKILL.md](../zeyos-calendar-and-scheduling/SKILL.md) |
+| Custom fields, schema/admin resources, operationId traps, platform model lookup | [../zeyos-platform-and-schema/SKILL.md](../zeyos-platform-and-schema/SKILL.md) |
+| Supplier scorecards, procurement, supplier delivery performance | [../zeyos-procurement-and-supplier-performance/SKILL.md](../zeyos-procurement-and-supplier-performance/SKILL.md) |
+| Duplicate accounts, null/empty/missing checks, remediation previews | [../zeyos-data-quality-and-governance/SKILL.md](../zeyos-data-quality-and-governance/SKILL.md) |
+
+If multiple domains apply, read each relevant specialized guide plus
+[../shared/zeyos-entity-map.md](../shared/zeyos-entity-map.md), then choose the smallest
+query plan that answers the user.
+
+For simple counts where the user already names the resource and filter constraints, run
+the direct `zeyos count <resource> --filter '{...}'` command and stop after the successful
+count. Do not add a discovery round-trip unless the resource or field is unclear.
+
 ## Do this, don't just describe it
 
 When asked anything about ZeyOS data, **run a `zeyos` command and report what it
@@ -33,6 +67,7 @@ zeyos resources --json             # list every available resource type
 zeyos describe <resource>          # fields, types, enums, foreign keys (offline)
 
 zeyos count  <resource> --filter '{"status":1}'
+zeyos sum    <resource> <field> --filter '{"status":[1,3]}'
 zeyos list   <resource> --filter '{…}' --fields ID,name,status --sort -lastmodified --limit 50 --json
 zeyos get    <resource> <id> --json          # single record (alias: show)
 
@@ -55,13 +90,22 @@ you intend before hitting the live instance — especially before any write. Add
 - **Counting:** use `zeyos count <resource>`. Do **not** `zeyos list` and count rows —
   `list` defaults to `--limit 50`, so you get the page size, not the total. In `--json`
   the only truncation signal is a stderr `Showing X–Y of TOTAL` hint.
-- **Totals / sums:** there is no server-side sum. `list` the matching records with the
-  numeric field and a high `--limit` (up to 10000), then add them up yourself.
+- **Stop after count:** for a simple "how many" task, a successful `zeyos count` is
+  sufficient. Do not list records afterward unless the user asks for them or the count
+  command fails.
+- **Joined counts are not simple counts:** questions such as unanswered mail, missing
+  related records, or "with no later reply" require the domain workflow and usually a
+  small client-side join. Do not answer from a raw `zeyos count` on one resource.
+- **Totals / sums:** for a simple numeric total, use `zeyos sum <resource> <field>
+  --filter '{...}'`; it pages internally and prints the total. For grouped, conditional,
+  or joined totals, list the needed fields and aggregate client-side.
 - **Filters:** the flag is `--filter '{…}'` (JSON). The CLI writes it to the API's
   `filters` key internally, which is the form that works for foreign-key (GIN-indexed)
   fields like `account`, `project`, `ticket`. **Only filter on columns the resource
   actually has** — filtering an unknown field returns an opaque HTTP 400 with no hint
   which field was wrong. When unsure, run `zeyos describe <resource>` first.
+  Arrays in CLI filters normalize to `IN`, so `{"status":[1,3]}` is the compact form
+  for "status is 1 or 3".
 - **`visibility: 0`** hides archived/deleted records — but **only some resources have a
   `visibility` column** (e.g. `tickets`, `accounts`, `items` do; `transactions` does
   **not** — adding `"visibility":0` there 400s). Include it on resources that have it
@@ -83,9 +127,8 @@ zeyos count accounts --filter '{"type":1,"visibility":0}'
 ```
 
 Report the number, and state the definition you used ("customer = `accounts.type` 1,
-excluding archived"). For a domain-specific metric (revenue, receivables, workload),
-hand off to the matching `zeyos-*` skill for the correct definition, but still run the
-query here.
+excluding archived"). For a domain-specific metric (revenue, receivables, workload), read
+the matching `zeyos-*` skill for the correct definition, then still run the query here.
 
 ## Safety
 

package/agents/zeyos-account-intelligence/references/workflows.md

@@ -79,9 +79,15 @@ Use this for prompts like:
 
 Recommended approach:
 
-1. Query addresses with type `1` (`BILLING_BILLING`) for the population you care about.
-2. Compare against the account set client-side.
-3. Report missing accounts and, if useful, whether they still have shipping addresses.
+1. Query the customer account population first. Company names are in `accounts.lastname`,
+   not `accounts.name`:
+   `zeyos list accounts --filter '{"type":1,"visibility":0,"lastname":{"~~*":"<prefix>%"}}' --fields ID,lastname --limit 1000 --json`
+2. Query addresses for those accounts in one call. `addresses` has no `visibility`
+   column. Use type `1` for billing and type `0` for shipping:
+   `zeyos list addresses --filter '{"account":[<accountIds>],"type":[0,1]}' --fields ID,account,type --limit 1000 --json`
+3. Compare client-side: keep accounts with no type `1` row, and set `has_shipping`
+   from presence of a type `0` row. For CSV exports, write the file first and end with
+   the required `RESULT_FILE:` marker.
 
 ## Common Failure Modes
 

package/agents/zeyos-billing-insights/SKILL.md

@@ -32,7 +32,7 @@ Typical prompts:
    - use `transactions` for invoice and credit value
    - use `payments` for cash movement
    - use `documents` only when the question is about the formal document artifact
-   - use `dunning` plus `dunning2transactions` when the question is really about receivables follow-up or collection 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))
+   - use `dunning` plus `dunning2transactions` when the question is really about receivables follow-up or collection state. In the CLI, call `zeyos count/list dunning` and `zeyos list dunning2transactions`; in `@zeyos/client`, call `listDunningNotices` and `listDunningToTransactions`.
 4. State the default metric if the prompt is ambiguous. Do not silently switch between net, gross, invoiced, and paid.
 5. Pull line-item detail only when necessary, usually with `expand: ['items']` through `@zeyos/client`.
 6. If the prompt is mainly about overdue notices, reminder stages, or next collection actions, treat that as a collections workflow rather than a pure revenue workflow.

package/agents/zeyos-billing-insights/references/workflows.md

@@ -14,7 +14,7 @@ Recommended defaults when the user does not specify:
 - Use `transactions.type = 3` for billing invoices.
 - Use `netamount` for invoiced revenue unless the user asks for gross.
 - Subtract billing credits (`transactions.type = 4`) if the user asks for net revenue after credits.
-- If the question is about reminders, notices, or overdue follow-up, switch to `dunning` and `dunning2transactions` instead of answering from revenue data alone. These dbref nouns diverge: call `listDunningNotices` (not `listDunning`) and `listDunningToTransactions` (not `listDunning2transactions`). See [../../shared/zeyos-entity-reference.md](../../shared/zeyos-entity-reference.md#entity-noun-to-rest-operationid).
+- If the question is about reminders, notices, or overdue follow-up, switch to `dunning` and `dunning2transactions` instead of answering from revenue data alone. The CLI maps these nouns directly (`zeyos count/list dunning`, `zeyos list dunning2transactions`). In JavaScript, use `listDunningNotices` (not `listDunning`) and `listDunningToTransactions` (not `listDunning2transactions`). See [../../shared/zeyos-entity-reference.md](../../shared/zeyos-entity-reference.md#entity-noun-to-rest-operationid).
 
 ## First Commands For Counts
 
@@ -90,18 +90,41 @@ If the user actually wants cash basis, switch to `payments` and sum `amount` ove
 Use this for prompts like:
 
 - "Show me all invoice activity for customer XYZ."
+- "List all delivery notes for customer XYZ."
 - "What is the payment status for account 122?"
 
 Recommended approach:
 
-1. Resolve the account first.
-2. Query `transactions` for invoice and credit records for that account.
+1. Resolve the account first. Company names are stored in `accounts.lastname`, not
+   `accounts.name`; for partial customer names use `{"lastname":{"~~*":"%XYZ%"}}`, not
+   an invented operator such as `contains`.
+2. Query `transactions` for the requested transaction type for that account.
+   - Billing delivery notes are `transactions.type = 2`.
+   - Billing invoices are `transactions.type = 3`.
+   - Billing credits are `transactions.type = 4`.
 3. Query `payments` for the same account or linked transactions.
 4. Present:
+   - delivery notes when requested
    - invoices and credits
    - payments received
    - open items or gaps you can identify from the available status fields
 
+CLI example for delivery notes:
+
+```bash
+zeyos list accounts \
+  --filter '{"lastname":{"~~*":"%Bureau3%"},"visibility":0}' \
+  --fields ID,customernum,firstname,lastname,type \
+  --limit 20 \
+  --json
+
+zeyos list transactions \
+  --filter '{"account":<accountId>,"type":2}' \
+  --fields ID,transactionnum,type,account,date,status,netamount \
+  --limit 100 \
+  --json
+```
+
 ## Pattern: Cash Received In A Period
 
 Use this for prompts like:

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

@@ -6,6 +6,8 @@ description: Detect duplicate accounts, completeness gaps, stale data and schema
 # 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.
@@ -34,6 +36,23 @@ Typical prompts:
    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.

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

@@ -27,8 +27,16 @@
 
 "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. State whether you treat empty string, null and missing the same
-(R-020); by default they are distinct.
+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
 

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-work-management/references/workflows.md

@@ -155,6 +155,27 @@ 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:
@@ -169,7 +190,9 @@ 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.
+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>`

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

@@ -18,6 +18,13 @@ These options work with any command:
 | `--no-color` | Disable ANSI color output |
 | `-h`, `--help` | Show help for a command |
 
+Global options may be placed before or after the command name:
+
+```bash
+zeyos --profile dev whoami
+zeyos whoami --profile dev
+```
+
 ---
 
 ## login
@@ -169,6 +176,14 @@ The `--fields` option supports three formats:
 | JSON object (with aliases) | `--fields '{"Name":"lastname","City":"contact.city"}'` |
 | JSON array | `--fields '["ID","name","status"]'` |
 
+**Filter compatibility:**
+
+The CLI normalizes common agent-generated filter forms before sending the request:
+arrays become `IN`, `$lt`/`$lte`/`$gt`/`$gte`/`$ne`/`$in`/`$nin` become native ZeyOS
+operators, and suffix keys such as `lastname__startswith`, `lastname__like`, `ID__gt`,
+`status__in`, and `status__nin` become native filters. On `accounts`, `name` in filters
+or `--fields` resolves to `lastname`.
+
 **Examples:**
 
 ```bash
@@ -245,6 +260,37 @@ zeyos count accounts --json
 
 ---
 
+## sum
+
+Sum a numeric field across matching records. The CLI pages internally, so this is the
+short path for simple totals that would otherwise require `list` plus a script.
+
+```
+zeyos sum <resource> <field> [options]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--filter <json>` | Filter criteria — JSON object. Arrays normalize to `IN`, e.g. `{"status":[1,3]}` |
+| `--filter-file <path>` | Read filter criteria from a JSON file |
+| `--page-size <n>` | Records per API page (default: 50) |
+| `--limit <n>` | Maximum records to inspect |
+| `--offset <n>` | Initial offset |
+| `--json` | Output as `{"sum": N, "count": N, "field": "..."}` |
+| `--yaml` | YAML output |
+
+**Examples:**
+
+```bash
+# Completed or booked effort minutes
+zeyos sum actionsteps effort --filter '{"status":[1,3]}'
+
+# Invoice net amount as JSON
+zeyos sum transactions netamount --filter '{"type":3}' --json
+```
+
+---
+
 ## get
 
 Fetch a single record by ID.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeyos/client",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Dependency-light JavaScript client for ZeyOS OpenAPI services",
   "type": "module",
   "license": "MIT",
@@ -54,6 +54,7 @@
     "test": "node scripts/test.mjs",
     "test:cli-integration": "node --test cli/test/integration.mjs",
     "test:agent-protocol": "node test/agent-protocol/harness/run.mjs",
+    "test:agent-benchmark": "node test/agent-protocol/harness/run.mjs --benchmark",
     "test:agent-loop": "node test/agent-protocol/harness/loop.mjs",
     "test:agent-validate": "node test/agent-protocol/harness/validate-live.mjs"
   }