@zeyos/client 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -3,6 +3,47 @@
 Notable changes to `@zeyos/client` and `@zeyos/cli`. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## 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.
+- Packaging: the published tarball now lists sample paths explicitly, so the generated `samples/missioncontrol/data.js` / `data.json` (which can contain real instance data) are never shipped to npm.
+
+### `@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).
+
+### Samples
+- New `samples/missioncontrol` team-performance dashboard: a read-only Node fetcher (`fetch-data.mjs`) plus a static, dependency-free `index.html`. The generated data files are git-ignored and excluded from the npm package.
+
+### Docs
+- Documented `--filter-file`/`--data-file` and the new `doctor` command across the CLI getting-started and command reference.
+
+## 0.1.1
+
+### `@zeyos/client`
+- `oauth2.buildAuthorizationUrl()` now includes the `scope` parameter when provided (previously dropped).
+- Retry timing hardened: an empty/whitespace `Retry-After` header falls back to exponential backoff instead of retrying instantly, and an already-aborted signal reliably stops a zero-delay retry.
+- `normalizeListResult()` preserves a numeric-string `count` (e.g. `"17"`), matching `normalizeCountResult()`.
+
+### `@zeyos/cli` (`zeyos`)
+- Added `--version` / `-v`.
+- Fixed the `--key=value` argument form, which was previously parsed as an unknown flag and silently ignored (e.g. `--filter='{...}'`).
+- YAML output now quotes ambiguous scalar strings (`true`, `false`, `null`, `yes`/`no`, and numeric-looking strings) so downstream YAML parsers don't re-interpret them.
+- `describe`, `resources`, and `skills` help text now documents the global `--json` / `--yaml` / `--help` options.
+- `skills install` reworked into a multi-agent installer: targets `claude`, `codex`, `opencode`, `droid`, `pi`, and a generic `agents` layout; adds `--global`/`--local` scope, `--dir <path>` for an explicit directory, an interactive agent/scope picker (with a ZeyOS banner) when run bare, `-y`/`--yes` and `--no-logo` to skip prompts/banner, and a `--json`/`--yaml` install summary.
+- `login` now prints the local callback URL before prompting for the application ID/secret, so it can be registered as the OAuth app's redirect URI.
+
+### Docs
+- Rewrote the top-level `README.md` into a full guide with CLI, JavaScript client, login/OAuth, and coding-agent examples.
+- Documentation accuracy fixes: accounts use `lastname` (no `name` field); updates accept the flat `{ ID, ...fields }` form (explicit `body` optional); clarified that the schema's `(required)` marker means `NOT NULL` (most such fields have defaults — `currency` on accounts is the real exception); fixed cross-links and a duplicate tutorial sidebar prefix.
+
 ## 0.1.0 — Initial release
 
 ### `@zeyos/client`

package/README.md

@@ -202,7 +202,7 @@ zeyos <command> [options] [args…]
 | `delete <resource> <id>` | Delete a record (`rm`/`remove` aliases) | `zeyos delete ticket 42 --force` |
 | `resources` | List resource types the CLI exposes | `zeyos resources --json` |
 | `describe <resource>` | Show a resource's fields, types and enums | `zeyos describe ticket` |
-| `skills <list\|show\|install>` | Manage bundled coding-agent skills | `zeyos skills install --target claude` |
+| `skills <list\|show\|install>` | Manage bundled coding-agent skills | `zeyos skills install --target claude --global` |
 
 **Global options** (work on every command): `--json`, `--yaml`, `--no-color`, `-h/--help`, `-v/--version`.
 
@@ -351,11 +351,28 @@ ZeyOS ships **agent skills** — curated instructions and query playbooks that t
 
 ```bash
 zeyos skills list                              # see what's available
-zeyos skills install --target claude           # copies skills into .claude/skills/
-zeyos skills install zeyos-work-management      # or install just one
+zeyos skills install                           # interactive: pick an agent, then local vs. global
+zeyos skills install --target claude --global  # or skip the prompts with flags
+zeyos skills install zeyos-work-management      # install just one skill
 ```
 
-`--target claude` writes to `.claude/skills/`, `--target codex` writes to `.codex/skills/`; with no `--target`, it auto-detects an existing `.claude`/`.codex` directory (defaulting to Claude). Shared reference docs are installed alongside so the skills' cross-links resolve. Point your agent at the install directory.
+Run bare, `install` shows the ZeyOS banner and asks **(a)** which coding agent to target and **(b)** whether to install for this project or globally. Flags skip the prompts:
+
+- `--target <agent>` — `claude`, `codex`, `opencode`, `droid`, `pi`, or `agents` (auto-detected when omitted)
+- `--global` / `--local` — install into the agent's home directory or just this project (default `--local`)
+- `--dir <path>` — install into any directory you choose (overrides `--target`)
+- `-y`/`--yes` — skip all prompts and use flags + defaults (also implied when piped non-interactively)
+
+| Agent | local | global |
+|-------|-------|--------|
+| `claude` | `.claude/skills/` | `~/.claude/skills/` |
+| `codex` | `.codex/skills/` | `~/.codex/skills/` |
+| `opencode` | `.opencode/skills/` | `~/.config/opencode/skills/` |
+| `droid` | `.factory/skills/` | `~/.factory/skills/` |
+| `pi` | `.pi/skills/` | `~/.pi/agent/skills/` |
+| `agents` | `.agents/skills/` | `~/.agents/skills/` |
+
+Shared reference docs are installed alongside so the skills' cross-links resolve. Point your agent at the install directory.
 
 Bundled skills:
 

package/agents/README.md

@@ -7,7 +7,13 @@ 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-mail-operations/` handles message lookup, email summaries, threads, and safe draft workflows.
 - `zeyos-billing-insights/` handles transactions, payments, invoices, credits, and revenue questions.
@@ -34,6 +40,7 @@ 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-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." |
@@ -51,11 +58,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:
 

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:
 

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

@@ -5,7 +5,7 @@ description: Inspect ZeyOS platform, schema, and admin-facing entities such as a
 
 # ZeyOS Platform And Schema
 
-Read [../shared/zeyos-query-patterns.md](../shared/zeyos-query-patterns.md) first. Read [../shared/zeyos-entity-reference.md](../shared/zeyos-entity-reference.md) for the full source-backed model. Read [references/workflows.md](references/workflows.md) for platform/admin query plans.
+Read [../shared/zeyos-agent-operating-guide.md](../shared/zeyos-agent-operating-guide.md) and [../shared/zeyos-query-patterns.md](../shared/zeyos-query-patterns.md) first. Read [../shared/zeyos-entity-reference.md](../shared/zeyos-entity-reference.md) for the full source-backed model. Read [references/workflows.md](references/workflows.md) for platform/admin query plans.
 
 Typical prompts:
 

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

@@ -22,6 +22,14 @@ These are dbref nouns, not operationIds. Several diverge: `applicationassets` ->
 [../../shared/zeyos-entity-reference.md](../../shared/zeyos-entity-reference.md#entity-noun-to-rest-operationid)
 before calling `@zeyos/client`.
 
+## First Commands For Counts
+
+- All custom fields: `zeyos count customfields`
+- Custom fields for tickets: `zeyos count customfields --filter '{"entity":"tickets"}'`
+
+`customfields` has no `visibility` field. In the JS client the list operation is
+`listCustomFields`, not `listCustomfields`.
+
 ## Pattern: Custom Fields For An Entity
 
 Use this for prompts like:

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

@@ -5,7 +5,7 @@ description: Manage ZeyOS tickets, tasks, projects, action steps, assignees, and
 
 # ZeyOS Work Management
 
-Read [../shared/zeyos-query-patterns.md](../shared/zeyos-query-patterns.md) first. Read [../shared/zeyos-entity-map.md](../shared/zeyos-entity-map.md) when the request crosses users, accounts, tickets, tasks, and projects. Read [references/workflows.md](references/workflows.md) for the concrete query patterns.
+Read [../shared/zeyos-agent-operating-guide.md](../shared/zeyos-agent-operating-guide.md) and [../shared/zeyos-query-patterns.md](../shared/zeyos-query-patterns.md) first. Read [../shared/zeyos-entity-map.md](../shared/zeyos-entity-map.md) when the request crosses users, accounts, tickets, tasks, and projects. Read [references/workflows.md](references/workflows.md) for the concrete query patterns.
 
 Typical prompts: