@zeyos/client 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -3,6 +3,41 @@
 Notable changes to `@zeyos/client` and `@zeyos/cli`. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## 0.3.0
+
+### `@zeyos/client`
+- **Single-flight token refresh**: when several operations notice an expired access token at once (e.g. `Promise.all([...])`), they now share a single `getToken` refresh instead of each firing its own — avoiding redundant calls and the hard failure that refresh-token rotation would otherwise cause.
+- **Request timeout**: a new `timeoutMs` option (client-wide via `config.timeoutMs`, or per request) bounds each attempt via an `AbortController` composed with any caller `signal`. Timeouts reject with `isTimeout === true` / `code === 'ETIMEDOUT'` and are distinct from a caller abort (which always propagates and is never retried).
+- **Network-error retries (reads only)**: dropped connections / timeouts are now retried within the retry budget for safe read operations (`GET`/`HEAD` + side-effect-free `list`/`count`/`search`); writes are never auto-retried. Override per request or client with `retryOnNetworkError`.
+- **Auto-pagination**: `client.paginate(operationId, input, opts)` async-iterates every matching record by paging on `offset` (page size clamped to the 10000 server max), and `client.collect(...)` is the eager array form — removing the manual offset bookkeeping the list caps otherwise force.
+- **Richer error messages**: `ZeyosApiError.message` now folds in a short snippet of the server error body (e.g. `… failed with HTTP 400: unknown filter field: bogus`); the full body remains on `error.body`.
+
+### `@zeyos/cli` (`zeyos`)
+- **Named credential profiles**: store multiple ZeyOS instances and switch between them. `zeyos profile list | current | use <name> [--local] | add <name> [--base-url/--client-id/--secret | --from-current] | remove <name>`, a global `--profile <name>` flag on every command, and `ZEYOS_PROFILE`. Profiles live in `~/.config/zeyos/profiles.json` with an active pointer; a project can pin one via `.zeyos/profile`. Resolution: `--profile` > `ZEYOS_PROFILE` > project pin > legacy `.zeyos/auth.json` > global active > legacy global. Fully backward compatible.
+- `login --profile <name>` authenticates into (and activates) a named profile; `logout` is profile-aware; refreshed tokens persist back to whichever store they came from.
+- `login` now detects an **expired** stored token and re-authenticates instead of reporting "already logged in"; `whoami` surfaces `502/503/504` as "instance temporarily unavailable" and `401` as an expired-session hint, instead of a raw status.
+
+### Agent skills
+- New **`zeyos-time-tracking`** skill: first-person work views ("what are my current tickets/tasks?") and interactive time logging ("log 60 minutes for client XYZ" → resolve account → pick ticket/task → write effort as an actionstep), plus timesheet summaries and entry corrections.
+
+## 0.2.0
+
+### `@zeyos/client`
+- Added a `dryRun` request option: `client.api.*`, `client.request()`, etc. return a resolved `{ dryRun, method, url, body, bodyType, … }` descriptor without performing any network request or token work. Powers the CLI `--query` flag and is handy for debugging and tests.
+
+### `@zeyos/cli` (`zeyos`)
+- New `doctor agent` command: an offline readiness check for coding agents — reports CLI version, configured base URL/instance, whether auth is present via environment/local/global config, and resource-registry health. Never prints tokens or client secrets.
+- New `--query` dry-run flag on the data commands (`list`/`count`/`get`/`create`/`update`/`delete`): prints the resolved `METHOD url` and JSON payload without sending the request; `--query --json` emits the full machine-readable request descriptor.
+- New `--filter-file <path>` (`list`/`count`) and `--data-file <path>` (`create`/`update`): read JSON from a file instead of inline. They are mutually exclusive with the inline `--filter`/`--data`, and file-read/parse errors never echo file contents.
+- Strict flag validation: unknown flags now error with a "did you mean …?" suggestion instead of being silently ignored. `create`/`update` still accept arbitrary `--<field>` flags.
+
+### Agents / skills
+- Skill packs are self-contained: each domain `SKILL.md` now points at a shared operating guide (`agents/shared/zeyos-agent-operating-guide.md`) with a bare-skill checklist and shell-safe command hygiene (inline single-quoted JSON, `--filter-file`/`--data-file`, counts via `zeyos count`).
+- Added an entity-noun → REST `operationId` reference and per-domain workflow notes (first-command examples for counts, `visibility`-column caveats, and the diverging dunning operationIds).
+
+### Docs
+- Documented `--filter-file`/`--data-file` and the new `doctor` command across the CLI getting-started and command reference.
+
 ## 0.1.1
 
 ### `@zeyos/client`

package/agents/README.md

@@ -7,8 +7,15 @@ Cross-platform modeling guidance lives in [`shared/business-app-benchmarks.md`](
 
 ## Structure
 
-- `shared/` contains cross-domain query rules and entity relationships.
+- `shared/` contains cross-domain query rules and entity relationships, including
+  [`shared/zeyos-agent-operating-guide.md`](./shared/zeyos-agent-operating-guide.md) — the
+  runner-agnostic operating contract (you have tools, the CLI is already authenticated,
+  act don't plan, safety) that every skill builds on.
+- `zeyos/` is the generic entry-point skill: how to actually talk to a ZeyOS instance via
+  the authenticated `zeyos` CLI. Use it when a request touches ZeyOS data and no
+  domain-specific skill clearly fits.
 - `zeyos-work-management/` handles tasks, projects, tickets, and assignee workload questions.
+- `zeyos-time-tracking/` handles first-person work views ("my tickets/tasks") and interactive time logging (resolve account, pick the ticket/task, write the effort as an actionstep).
 - `zeyos-mail-operations/` handles message lookup, email summaries, threads, and safe draft workflows.
 - `zeyos-billing-insights/` handles transactions, payments, invoices, credits, and revenue questions.
 - `zeyos-notes-and-sops/` handles notes, SOP discovery, documents, and file-backed knowledge lookup.
@@ -34,7 +41,9 @@ Cross-platform modeling guidance lives in [`shared/business-app-benchmarks.md`](
 
 | Skill | Best for | Example prompts |
 |------|----------|-----------------|
+| `zeyos` | General-purpose ZeyOS access via the CLI; the catch-all when no domain skill fits | "How many open customers do we have?"; "List the 10 most recently modified tickets."; "Show me account 122." |
 | `zeyos-work-management` | Operational work queues, user workload, ticket-task-project tracing, follow-up work creation | "On which projects did Max Power work in the last two weeks?"; "Show overdue high-priority tickets for account ACME."; "What open tasks are blocking Project Atlas?" |
+| `zeyos-time-tracking` | First-person work views and interactive time logging (resolve account → pick ticket/task → write effort as an actionstep) | "What are my current tickets?"; "Show my open tasks."; "Log 60 minutes for client XYZ."; "Record 2 hours on ticket 812." |
 | `zeyos-mail-operations` | Customer mail summaries, thread reconstruction, draft preparation, mailbox analysis | "Give me a summary of all recent mails from customer XYZ."; "Which open tickets have unanswered customer emails?"; "Draft a reply to the latest complaint from ACME." |
 | `zeyos-billing-insights` | Revenue, invoices, credits, payment tracking, transaction-level finance questions | "What is our net invoiced revenue this year?"; "How much cash did we collect this quarter?"; "Show all billing activity for customer XYZ." |
 | `zeyos-notes-and-sops` | SOP retrieval, note summaries, final-document lookup, attachment discovery | "Find the current escalation SOP for billing disputes."; "Summarize our notes on failed invoice syncs."; "Which finalized onboarding SOP changed last month?" |
@@ -51,11 +60,14 @@ The CLI covers common operational resources such as accounts, contacts, document
 
 ## Recommended Loading Order
 
-1. Read `shared/zeyos-query-patterns.md`.
-2. Read `shared/business-app-benchmarks.md` when the semantics are unclear.
-3. Read `shared/zeyos-entity-reference.md` when the entity itself is unclear.
-4. Read `shared/zeyos-entity-map.md` if the question crosses domains.
-5. Load the matching skill folder and its `references/workflows.md`.
+1. Read `shared/zeyos-agent-operating-guide.md` — establishes that you have tools, the CLI
+   is authenticated, and you must run commands rather than produce a plan.
+2. Read `shared/zeyos-query-patterns.md`.
+3. Read `shared/business-app-benchmarks.md` when the semantics are unclear.
+4. Read `shared/zeyos-entity-reference.md` when the entity itself is unclear.
+5. Read `shared/zeyos-entity-map.md` if the question crosses domains.
+6. Load the matching skill folder and its `references/workflows.md` (or the generic `zeyos/`
+   skill when no domain skill fits).
 
 ## Good Next Skills
 

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

@@ -0,0 +1,112 @@
+# ZeyOS Agent Operating Guide
+
+Read this **first**, before any domain skill. It is runner-agnostic: it holds true
+whether you are driven by a coding-agent CLI (pi, opencode, Claude Code, …), an
+automated test harness, or an interactive session. The domain skills describe *what to
+query*; this file describes *that you must actually query it, and how*.
+
+## You are an operator, not a planner
+
+When a user asks a ZeyOS business question, your job is to **run commands and report the
+answer from real data** — not to describe a query you would run if you had access.
+
+- You have a **shell / command-execution tool** (often called `bash`, `shell`, `exec`, or
+  `run_command`). Use it.
+- The **`zeyos` CLI is already installed and authenticated** against the configured
+  instance. You do **not** need an API key, an "execution endpoint", a "data layer", or
+  any further setup from the user. Confirm it works at any time with `zeyos whoami`.
+- **Do not** end your turn with a query plan, a request for "the tool to run this", or a
+  statement that you "do not have tools to execute this". If you wrote a plan, the next
+  step is to **execute it yourself**.
+
+## How to actually execute (read this if you are a small/local model)
+
+The single most common failure is *planning instead of running*. Avoid it mechanically:
+
+1. **Your first action is a call to your shell/`bash` tool**, running a `zeyos …` command
+   from the tables below. Not a paragraph — a tool call.
+2. **`zeyos` is a shell command, not a tool or a sub-agent.** Do **not** call a tool named
+   `zeyos`, `zeyos-billing-insights`, `zeyos-work-management`, etc., and do **not** spawn a
+   sub-agent of those names — those tools do not exist and will error. This skill is
+   instructions *for you*; you carry them out by typing a `zeyos` command into `bash`.
+3. **Copy the command grammar exactly** as shown here (`zeyos <verb> <resource> --filter
+   '{…}'`). Do not invent flags like `zeyos --work-management "…"` — there are none.
+4. Run the command, read the real output, then answer from it.
+
+If a command fails, read the error, adjust, and try again — `zeyos describe <resource>`
+and `zeyos resources` are offline and safe for orienting yourself.
+
+## Bare-skill checklist for Pi/OpenCode/local models
+
+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.
+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.
+
+## First move for the common question shapes
+
+| The user asks… | Your first command |
+|----------------|--------------------|
+| "How many X …?" | `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 |
+| "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
+those commands correct (filters vs filter, `visibility: 0`, counting, time windows), and
+the matching domain skill for the metric definitions.
+
+## Shell-safe command hygiene
+
+- Use copy-paste-safe JSON: wrap filter JSON in single quotes and use double quotes inside
+  the JSON, for example `--filter '{"type":1,"visibility":0}'`.
+- Never execute raw JSON as a shell command. `{ "visibility": 0 }` by itself is not a
+  command; it belongs after `--filter`.
+- 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>`.
+- 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`.
+
+## Authentication and connection (do not ask the user)
+
+Credentials are already provisioned. The `zeyos` CLI picks them up automatically from
+**whichever** of these is present — you do not choose:
+
+- a local `.zeyos/auth.json` (interactive / local use), or
+- `ZEYOS_BASE_URL` + `ZEYOS_TOKEN` environment variables (harness / CI use).
+
+Never ask the user for credentials, never print tokens, and never propose configuring
+auth as a prerequisite — assume it is done and just run the command.
+
+To use the JavaScript client instead of the CLI, import from the repo's
+`src/index.js`. Construct it from the environment **if** `ZEYOS_TOKEN` is set, otherwise
+fall back to the CLI — but for almost every read/count question the CLI is enough and is
+the path of least resistance.
+
+## Output discipline
+
+1. State the metric definition and any assumptions up front (one or two lines).
+2. Give the answer grounded in the command output you actually saw.
+3. Keep totals, counts, and exceptional records separate.
+
+(An automated harness may additionally require a machine-readable `RESULT:` line — that
+requirement is documented by the harness itself, not here.)
+
+## Safety (hard constraints)
+
+- **Read-only by default.** Only create / update / delete when the task explicitly asks.
+- **Refuse unscoped bulk destructive operations** ("delete all completed", "clean up the
+  queue", "remove old accounts") — even if the records look like test data. Deletes are
+  per-record, against IDs you can name, with confirmation.
+- **Never send outbound communication** (email send, dunning dispatch, campaign send).
+  Mail and outreach tasks stop at *draft / preview*.
+- Confirm before any delete, send, revoke, or bulk update unless the workflow is already
+  explicitly authorized.

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

@@ -2,6 +2,14 @@
 
 Use this file as the default operating playbook before answering any business question against ZeyOS.
 
+> **Operate, don't plan.** You have a shell tool and the `zeyos` CLI is already
+> authenticated against the configured instance. Answer business questions by **running
+> commands and reporting real output** — never reply with a query plan, never ask for an
+> "execution endpoint" or "a tool to run this", never claim you lack execution access.
+> Confirm access any time with `zeyos whoami`. The full operating contract (tools, auth,
+> output, safety) is in [zeyos-agent-operating-guide.md](./zeyos-agent-operating-guide.md) —
+> read it first.
+
 For the full source-backed inventory, read [zeyos-entity-reference.md](./zeyos-entity-reference.md).
 For cross-platform benchmark guidance, read [business-app-benchmarks.md](./business-app-benchmarks.md).
 
@@ -21,8 +29,11 @@ For cross-platform benchmark guidance, read [business-app-benchmarks.md](./busin
 ## Common Guardrails
 
 - Discover before guessing: `zeyos describe <resource>` (or `client.schema.describe(resource)`) lists a resource's fields, types, foreign keys, and enum values; both run offline. `zeyos describe`, `create`, `update`, and `list` all accept singular, plural, or aliased resource names (`ticket`/`tickets`/`invoice`). Pre-check a call with `client.schema.validate(operationId, input)` — it flags unknown fields (with suggestions), `filter` vs `filters`, invalid enum values, and missing required create fields. An unknown operation name rejects with a "did you mean …?" suggestion.
+- 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.
 - 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.
+- 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.
 - Treat `filter` versus `filters` as a source inconsistency, not a universal rule:
   - `api.json` documents `filter`

package/agents/zeyos/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: zeyos
+description: Read or change ZeyOS business data (accounts, contacts, tickets, tasks, projects, items, transactions, documents, and more) by running the authenticated `zeyos` CLI. Use this as the general entry point whenever a request touches ZeyOS data and no more specific zeyos-* skill clearly fits — it explains how to actually talk to the instance and run queries.
+---
+
+# 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**.
+
+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.
+
+## Do this, don't just describe it
+
+When asked anything about ZeyOS data, **run a `zeyos` command and report what it
+returns.** Never reply with a query plan, never ask for "an endpoint" or "a tool to run
+this", never say you lack execution access — the `zeyos` CLI is installed and
+authenticated. If unsure it works, run `zeyos whoami`.
+
+**`zeyos` is a shell command — run it with your `bash`/shell tool.** Your first action is a
+shell tool call, e.g. `zeyos count accounts --filter '{"type":1}'`. Do **not** call a tool
+or spawn a sub-agent named `zeyos` / `zeyos-*` (those don't exist and will error), and do
+**not** invent flags like `zeyos --work-management "…"`. Use the exact grammar below.
+
+## The CLI surface
+
+```
+zeyos whoami                       # confirm auth + see the current user/instance
+zeyos resources --json             # list every available resource type
+zeyos describe <resource>          # fields, types, enums, foreign keys (offline)
+
+zeyos count  <resource> --filter '{"status":1}'
+zeyos list   <resource> --filter '{…}' --fields ID,name,status --sort -lastmodified --limit 50 --json
+zeyos get    <resource> <id> --json          # single record (alias: show)
+
+zeyos create <resource> --name "…" --priority 3
+zeyos update <resource> <id> --status 2
+zeyos delete <resource> <id> --force         # per-record only; see Safety
+```
+
+Resource names accept singular, plural, or aliases (`ticket` / `tickets` / `invoice`).
+Add `--json` whenever another step will parse the output.
+
+**Preview before you run:** append `--query` to any data command (`list`, `count`,
+`get`, `create`, `update`, `delete`) to print the resolved route + JSON payload
+**without sending the request**. Use it to confirm a filter/body is shaped the way
+you intend before hitting the live instance — especially before any write. Add
+`--json` to `--query` for the full machine-readable request descriptor.
+
+## Things that bite people (read before querying)
+
+- **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.
+- **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.
+- **`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
+  unless the user wants archived records; omit it otherwise. `zeyos describe <resource>`
+  tells you whether the column exists.
+- **Dates** are Unix timestamps in **seconds**. Use the `date` field for business-effective
+  reporting (invoice date, message date), `lastmodified` for "recently changed".
+- **Discover before guessing:** `zeyos describe <resource>` shows the real field names and
+  enum values. operationId / REST names don't always match the dbref noun.
+- **Resource not in the CLI?** If `zeyos resources` doesn't list what you need (platform,
+  pricing, campaign-recipient, permission, channel, follower resources, `expand`, binary
+  files), escalate to `@zeyos/client` — import from the repo's `src/index.js`.
+
+## Worked example: "how many open customers do we have?"
+
+```bash
+zeyos describe accounts | grep -i type      # confirm: type 1 = CUSTOMER
+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.
+
+## Safety
+
+Read-only by default. Refuse unscoped bulk deletes ("delete all …", "clean up the
+queue") even for apparent test data; deletes are per-record against IDs you can name.
+Never send outbound email/dunning/campaigns — stop at draft. See the operating guide for
+the full constraints.

package/agents/zeyos-account-intelligence/SKILL.md

@@ -5,7 +5,7 @@ description: Analyze ZeyOS customer and account context across accounts, contact
 
 # ZeyOS Account Intelligence
 
-Read [../shared/zeyos-query-patterns.md](../shared/zeyos-query-patterns.md) first. Read [../shared/zeyos-entity-map.md](../shared/zeyos-entity-map.md) for the relationship map and [../shared/zeyos-entity-reference.md](../shared/zeyos-entity-reference.md) for the source-backed inventory. Read [references/workflows.md](references/workflows.md) for account-specific 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-map.md](../shared/zeyos-entity-map.md) for the relationship map and [../shared/zeyos-entity-reference.md](../shared/zeyos-entity-reference.md) for the source-backed inventory. Read [references/workflows.md](references/workflows.md) for account-specific query plans.
 
 Typical prompts:
 

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

@@ -10,6 +10,13 @@
 - `campaigns`
 - `participants`
 
+## First Commands For Counts
+
+- Customer accounts, active only: `zeyos count accounts --filter '{"type":1,"visibility":0}'`
+- All active accounts: `zeyos count accounts --filter '{"visibility":0}'`
+
+`accounts.type = 1` is `CUSTOMER`. Use `zeyos count`, not `list` plus row length.
+
 ## Pattern: Customer 360 Summary
 
 Use this for prompts like:

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

@@ -5,7 +5,12 @@ description: Analyze ZeyOS billing transactions, invoices, credits, payments, an
 
 # ZeyOS Billing Insights
 
-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 accounts, transactions, payments, items, and documents. Read [references/workflows.md](references/workflows.md) for finance-specific metric selection and 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-map.md](../shared/zeyos-entity-map.md) when the request crosses accounts, transactions, payments, items, and documents. Read [references/workflows.md](references/workflows.md) for finance-specific metric selection and query plans.
+
+> **Run the query — don't hand back a plan.** Finance questions still get answered by
+> executing `zeyos` commands (or `@zeyos/client`) against the live instance and summing
+> real rows. State your metric definition, then go fetch the numbers. Never end by asking
+> for "an execution endpoint" or "the data layer" — it's already wired (`zeyos whoami`).
 
 Typical prompts:
 

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

@@ -16,6 +16,14 @@ Recommended defaults when the user does not specify:
 - 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).
 
+## First Commands For Counts
+
+- All transactions: `zeyos count transactions`
+- Billing invoices only: `zeyos count transactions --filter '{"type":3}'`
+
+`transactions` has no `visibility` field. Do not add `"visibility":0` to transaction
+filters.
+
 ## Important Status Caution
 
 The transaction status enum is broad and instance behavior may differ. Do not hard-code business meaning beyond what the schema documents unless the instance conventions are known.
@@ -41,17 +49,38 @@ Recommended approach:
 4. If credits matter, query billing credits separately and subtract them.
 5. Sum the values client-side.
 
-Client example:
+CLI example — do this, end to end ("what was last year's total revenue?"):
+
+```bash
+# Current year is 2026, so "last calendar year" = 2025.
+# ZeyOS dates are Unix seconds: 2025-01-01 = 1735689600, 2026-01-01 = 1767225600.
+# NOTE: transactions has NO `visibility` column — adding "visibility":0 here 400s. Don't.
+zeyos list transactions \
+  --filter '{"type":3,"date":{">=":1735689600,"<":1767225600}}' \
+  --fields ID,transactionnum,date,netamount,tax \
+  --limit 10000 --json \
+  | python3 -c 'import sys,json; rows=json.load(sys.stdin); print(sum(r.get("netamount",0) for r in rows.get("data",rows)))'
+```
+
+There is no server-side SUM — you `list` the matching rows (high `--limit`) and add
+`netamount` yourself. Use whatever summing tool you have (a shell pipe, the JS client,
+etc.); the point is to **run it and report the figure**, not to describe the plan.
+Filtering an unknown column (like `visibility` on `transactions`) returns an opaque
+HTTP 400, so only filter on fields `zeyos describe transactions` actually lists.
+
+Client example (use when you need `expand`, richer control, or to subtract credits in one pass):
 
 ```js
 const invoices = await client.api.listTransactions({
   fields: ['ID', 'transactionnum', 'date', 'type', 'status', 'netamount', 'tax', 'account', 'account.lastname'],
   filters: {
     type: 3,
-    date: { '>=': yearStart },
+    // no visibility: transactions has no such column (would 400)
+    date: { '>=': yearStart, '<': yearEnd },
   },
-  limit: 1000,
+  limit: 10000,
 });
+const total = invoices.reduce((s, r) => s + (r.netamount || 0), 0);
 ```
 
 If the user actually wants cash basis, switch to `payments` and sum `amount` over the same date window.

package/agents/zeyos-campaign-and-outreach/SKILL.md

@@ -5,7 +5,7 @@ description: Analyze ZeyOS campaigns, mailing lists, participants, outbound mail
 
 # ZeyOS Campaign And Outreach
 
-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 campaigns, mailing lists, participants, messages, and contacts. Read [references/workflows.md](references/workflows.md) for outreach-specific 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-map.md](../shared/zeyos-entity-map.md) when the request crosses campaigns, mailing lists, participants, messages, and contacts. Read [references/workflows.md](references/workflows.md) for outreach-specific query plans.
 
 Typical prompts:
 

package/agents/zeyos-campaign-and-outreach/references/workflows.md

@@ -14,6 +14,14 @@ These are dbref nouns, not operationIds. Several diverge: `mailinglists` -> `lis
 [../../shared/zeyos-entity-reference.md](../../shared/zeyos-entity-reference.md#entity-noun-to-rest-operationid)
 before calling `@zeyos/client`.
 
+## First Commands For Counts
+
+- Active campaigns: `zeyos count campaigns --filter '{"visibility":0}'`
+- All campaigns: `zeyos count campaigns`
+- Participants in a campaign: `zeyos count participants --filter '{"campaign":123}'`
+
+Replace `123` with the resolved campaign ID when the user gives a campaign name.
+
 ## Schema Shape To Respect
 
 - A `participant` belongs either to a `campaign` or to a `mailinglist`.

package/agents/zeyos-collaboration-and-activity/SKILL.md

@@ -5,7 +5,7 @@ description: Analyze ZeyOS record timelines, comments, followers, channels, file
 
 # ZeyOS Collaboration And Activity
 
-Read [../shared/zeyos-query-patterns.md](../shared/zeyos-query-patterns.md) first. Read [../shared/business-app-benchmarks.md](../shared/business-app-benchmarks.md) for the cross-platform semantic defaults. Read [../shared/zeyos-entity-map.md](../shared/zeyos-entity-map.md) when the timeline must be correlated with work, mail, or knowledge entities. Read [references/workflows.md](references/workflows.md) for activity-specific 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/business-app-benchmarks.md](../shared/business-app-benchmarks.md) for the cross-platform semantic defaults. Read [../shared/zeyos-entity-map.md](../shared/zeyos-entity-map.md) when the timeline must be correlated with work, mail, or knowledge entities. Read [references/workflows.md](references/workflows.md) for activity-specific query plans.
 
 Typical prompts:
 

package/agents/zeyos-collaboration-and-activity/references/workflows.md

@@ -16,6 +16,15 @@ These are dbref nouns, not operationIds. Note the junction `entities2channels` -
 [../../shared/zeyos-entity-reference.md](../../shared/zeyos-entity-reference.md#entity-noun-to-rest-operationid)
 before calling `@zeyos/client`.
 
+## First Commands For Counts
+
+- All timeline events: `zeyos count events`
+- Events for account ID 123: `zeyos count events --filter '{"entity":"accounts","index":123}'`
+- Feed records for account ID 123: `zeyos count records --filter '{"entity":"accounts","index":123}'`
+
+`events` and `records` use `entity` plus `index` indirection and have no `visibility`
+field.
+
 ## Benchmark-Backed Default
 
 Treat this layer like the record timeline or collaboration feed found in Salesforce, Odoo, and Dynamics:

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

@@ -5,7 +5,7 @@ description: Analyze ZeyOS overdue receivables, dunning notices, payment gaps, a
 
 # ZeyOS Collections And Dunning
 
-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 accounts, transactions, payments, and dunning. Read [references/workflows.md](references/workflows.md) for collections-specific 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-map.md](../shared/zeyos-entity-map.md) when the request crosses accounts, transactions, payments, and dunning. Read [references/workflows.md](references/workflows.md) for collections-specific query plans.
 
 Typical prompts:
 

package/agents/zeyos-commerce-and-inventory/SKILL.md

@@ -5,7 +5,7 @@ description: Analyze ZeyOS items, pricing, price lists, supplier links, stock mo
 
 # ZeyOS Commerce And Inventory
 
-Read [../shared/zeyos-query-patterns.md](../shared/zeyos-query-patterns.md) first. Read [../shared/zeyos-entity-map.md](../shared/zeyos-entity-map.md) and [../shared/zeyos-entity-reference.md](../shared/zeyos-entity-reference.md) when the request crosses pricing, accounts, and stock. Read [references/workflows.md](references/workflows.md) for commerce-specific 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-map.md](../shared/zeyos-entity-map.md) and [../shared/zeyos-entity-reference.md](../shared/zeyos-entity-reference.md) when the request crosses pricing, accounts, and stock. Read [references/workflows.md](references/workflows.md) for commerce-specific query plans.
 
 Typical prompts:
 

package/agents/zeyos-commerce-and-inventory/references/workflows.md

@@ -20,6 +20,13 @@ These are dbref nouns, not operationIds. Several diverge: `pricelists` -> `listP
 [../../shared/zeyos-entity-reference.md](../../shared/zeyos-entity-reference.md#entity-noun-to-rest-operationid)
 before calling `@zeyos/client`.
 
+## First Commands For Counts
+
+- Active catalog items/products: `zeyos count items --filter '{"visibility":0}'`
+- All catalog items/products: `zeyos count items`
+
+Use `zeyos count` for item totals; `zeyos list` defaults to one page.
+
 ## Pattern: Effective Price For A Customer
 
 Use this for prompts like:

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

@@ -5,7 +5,7 @@ description: Query, summarize, and draft ZeyOS email and message records. Use wh
 
 # ZeyOS Mail Operations
 
-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 accounts, contacts, tickets, and messages. Read [references/workflows.md](references/workflows.md) for mail-specific correlation 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 accounts, contacts, tickets, and messages. Read [references/workflows.md](references/workflows.md) for mail-specific correlation patterns.
 
 Typical prompts:
 
@@ -25,9 +25,15 @@ Typical prompts:
 4. Pull message `text` only when you actually need a summary or draft context.
 5. Group related mail using `reference`, `messageid`, and normalized subject.
 6. If the request is about campaigns, mailing lists, participant coverage, or mailing performance, switch to `zeyos-campaign-and-outreach`.
-7. Treat drafts as safe write targets. Treat sending as high risk and require explicit confirmation plus verified sender context.
+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.
 
+## Safety
+
+- Never send email from an agent test or from a summary/draft request.
+- Do not create or update message records unless the user explicitly asks for a real ZeyOS draft and the sender/mailserver context is known.
+- For "draft a reply", produce reply text in the response and leave ZeyOS unchanged.
+
 ## Output Discipline
 
 - Report the resolved customer identity and the email addresses used for matching.

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

@@ -5,6 +5,8 @@
 - `0` = inbox
 - `1` = drafts
 - `2` = sent
+- `3` = templates
+- `4` = mailings
 - `5` = archive
 - `6` = trash
 - `7` = junk
@@ -68,6 +70,17 @@ Recommended approach:
 3. Use `reference` and `messageid` to confirm direct reply relationships.
 4. Use subject matching only as a fallback.
 
+CLI example:
+
+```bash
+zeyos list messages \
+  --fields ID,date,mailbox,subject,sender_email,to_email,ticket,reference,messageid \
+  --filter '{"ticket":812}' \
+  --sort +date \
+  --limit 100 \
+  --json
+```
+
 ## Pattern: Find Unanswered Customer Mail
 
 Use this for prompts like:
@@ -80,9 +93,11 @@ Recommended approach:
 1. Start from recent inbox messages (`mailbox = 0`).
 2. Limit to customer identities you can resolve through contacts or linked tickets.
 3. Group by thread using `reference`, `messageid`, and subject.
-4. Look for a later sent message (`mailbox = 2`) in the same thread.
+4. Look for a later sent message (`mailbox = 2`) in the same thread. The strongest match is `sent.reference == inbound.ID`; subject matching is only a fallback.
 5. Report unresolved threads and their linked tickets if available.
 
+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.
+
 ## Pattern: Draft A Reply
 
 Use this for prompts like:
@@ -95,12 +110,14 @@ Recommended approach:
 1. Summarize the relevant thread first.
 2. Extract the action items, commitments, and unresolved questions.
 3. Draft reply text separately from any ZeyOS mutation.
-4. Create or update a draft message only if the user explicitly asks and the required sender context is known.
+4. Create or update a draft message only if the user explicitly asks for a real ZeyOS draft and the required sender/mailserver context is known.
 
 Important caveat:
 
 - Creating a real draft may require more than subject and body. Inspect an existing draft or the instance-specific sending setup before writing message records.
+- Do not set `messageid` when creating test/draft messages; the API may reject it even though list/get responses can expose the field.
 - Never send email just because a user asked for a summary or a draft.
+- In agent protocol tests, "draft" means text output only. Do not call `createMessage`, `updateMessage`, or any send/dispatch path unless the scenario explicitly asks for a real draft record.
 
 ## Common Failure Modes
 

package/agents/zeyos-notes-and-sops/SKILL.md

@@ -5,7 +5,7 @@ description: Retrieve and summarize ZeyOS notes, SOPs, documents, and file-backe
 
 # ZeyOS Notes And SOPs
 
-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 spans notes, documents, files, and related business records. Read [references/workflows.md](references/workflows.md) for knowledge-retrieval 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 spans notes, documents, files, and related business records. Read [references/workflows.md](references/workflows.md) for knowledge-retrieval patterns.
 
 Typical prompts: