@zeyos/client 0.1.0

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

@@ -0,0 +1,570 @@
+# ZeyOS Entity Reference For Agents
+
+This file is optimized for coding agents. It is derived from:
+
+- [../../openapi/dbref.json](../../openapi/dbref.json)
+- [../../openapi/api.json](../../openapi/api.json)
+
+Current source snapshot:
+
+- `dbref.json`: 357 entities total
+- `dbref.json`: 312 tables and 45 views
+- `api.json`: 64 listable API resources under the public REST surface
+- `api.json`: `config` and `settings` are API endpoints, but not `dbref.json` entities
+
+Use this file when you need to understand what an entity is for before building a query plan.
+
+## Source Note: `filter` vs `filters`
+
+Do not treat the spelling as universally settled.
+
+- `openapi/api.json` documents the list request body field as `filter`.
+- The repo CLI accepts `--filter` but serializes the JSON into `body.filters`.
+- The repo client examples consistently use `filters`.
+
+Agent rule:
+
+- For `@zeyos/client`, follow repo convention and use `filters`.
+- For CLI, use the documented `--filter` flag.
+- For raw REST/OpenAPI examples, mention that the spec documents `filter` and verify behavior against the target instance before hardcoding one spelling as universally correct.
+
+## Entity Noun to REST operationId
+
+The DB-table noun (from `dbref.json`, also the REST URL path segment) is **not** the
+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".
+
+### The regular rule (most entities)
+
+For most entities the operationIds follow this pattern, where `<Plural>` is the CamelCase plural
+and `<Singular>` is the CamelCase singular:
+
+- `list<Plural>`, `get<Singular>`, `create<Singular>`, `update<Singular>`, `delete<Singular>`, `exists<Singular>`
+
+Example (`accounts`): `listAccounts`, `getAccount`, `createAccount`, `updateAccount`, `deleteAccount`, `existsAccount`.
+
+Entities that follow the regular rule directly (lowercase noun, single English word): `accounts`,
+`addresses`, `applications`*, `appointments`, `associations`, `campaigns`, `channels`, `comments`,
+`components`, `contacts`, `contracts`, `coupons`, `devices`, `documents`, `events`, `files`,
+`follows`, `forks`*, `groups`*, `invitations`, `items`, `ledgers`, `likes`, `links`, `messages`,
+`notes`, `objects`, `opportunities`, `participants`, `payments`, `permissions`*, `prices`,
+`projects`, `records`, `resources`*, `services`*, `storages`, `suppliers`, `tasks`, `tickets`,
+`transactions`, `users`*, `weblets`*.
+
+`*` = read-only entity: only `list*`, `get*`, and `exists*` exist (no create/update/delete).
+
+### Exceptions (verify these — the noun does NOT map naively)
+
+Every operationId below was verified to exist in `src/generated/operations.js`. Junction tables
+(`X2Y`) become `XToY` (CamelCase, with the **left** side often re-pluralized). Some entities are
+renamed entirely (`dunning` -> `DunningNotice`), and several are compound words that must keep their
+internal capitalization (e.g. `MailingLists`, not `Mailinglists`).
+
+| dbref noun | list | get | create | update | delete | exists | Notes |
+|------------|------|-----|--------|--------|--------|--------|-------|
+| `actionsteps` | `listActionSteps` | `getActionStep` | `createActionStep` | `updateActionStep` | `deleteActionStep` | `existsActionStep` | Compound `ActionStep` |
+| `applicationassets` | `listApplicationAssets` | `getApplicationAsset` | — | — | — | `existsApplicationAsset` | Read-only; compound |
+| `binfiles` | `listBinFiles` | — | — | — | — | — | **List-only.** `BinFiles` |
+| `categories` | `listCategorys` | `getCategory` | `createCategory` | `updateCategory` | `deleteCategory` | `existsCategory` | List op is `listCategorys` (sic — no irregular plural); singular ops use `Category` |
+| `contacts2contacts` | `listContactsToContacts` | `getContactToContact` | `createContactToContact` | `updateContactToContact` | `deleteContactToContact` | `existsContactToContact` | Junction `X2Y` -> `XToY` |
+| `couponcodes` | `listCouponCodes` | `getCouponCode` | `createCouponCode` | `updateCouponCode` | `deleteCouponCode` | `existsCouponCode` | Compound `CouponCode` |
+| `customfields` | `listCustomFields` | `getCustomField` | — | — | — | `existsCustomField` | Read-only; compound |
+| `davservers` | `listDAVServers` | `getDAVServer` | `createDAVServer` | `updateDAVServer` | `deleteDAVServer` | `existsDAVServer` | Acronym uppercased: `DAVServer` |
+| `dunning` | `listDunningNotices` | `getDunningNotice` | `createDunningNotice` | `updateDunningNotice` | `deleteDunningNotice` | `existsDunningNotice` | Entity is **`DunningNotice`**, not `Dunning` |
+| `dunning2transactions` | `listDunningToTransactions` | `getDunningToTransaction` | `createDunningToTransaction` | `updateDunningToTransaction` | `deleteDunningToTransaction` | `existsDunningToTransaction` | Junction `dunning2transactions` -> `DunningToTransaction(s)` |
+| `entities2channels` | `listEntitiesToChannels` | `getEntityToChannel` | `createEntityToChannel` | `updateEntityToChannel` | `deleteEntityToChannel` | `existsEntityToChannel` | Junction; singular re-singularized to `EntityToChannel` |
+| `feedservers` | `listFeedServers` | `getFeedServer` | `createFeedServer` | `updateFeedServer` | `deleteFeedServer` | `existsFeedServer` | Compound `FeedServer` |
+| `groups2users` | `listGroupsToUsers` | `getGroupToUser` | — | — | — | `existsGroupToUser` | Read-only junction `X2Y` -> `XToY` |
+| `mailinglists` | `listMailingLists` | `getMailingList` | `createMailingList` | `updateMailingList` | `deleteMailingList` | `existsMailingList` | Compound `MailingList` |
+| `mailingrecipients` | `listMailingRecipients` | `getMailingRecipient` | `createMailingRecipient` | `updateMailingRecipient` | `deleteMailingRecipient` | `existsMailingRecipients` | Compound; **exists op is plural** `existsMailingRecipients` (sic) |
+| `mailservers` | `listMailServers` | `getMailServer` | `createMailServer` | `updateMailServer` | `deleteMailServer` | `existsMailServer` | Compound `MailServer` |
+| `messagereads` | `listMessageReads` | `getMessageRead` | `createMessageRead` | `updateMessageRead` | `deleteMessageRead` | `existsMessageRead` | Compound `MessageRead` |
+| `pricelists` | `listPriceLists` | `getPriceList` | `createPriceList` | `updatePriceList` | `deletePriceList` | `existsPriceList` | Compound `PriceList` |
+| `pricelists2accounts` | `listPriceListsToAccounts` | `getPriceListToAccount` | `createPriceListToAccount` | `updatePriceListToAccount` | `deletePriceListToAccount` | `existsPriceListToAccount` | Junction; compound on both sides |
+| `relateditems` | `listRelatedItems` | `getRelatedItem` | `createRelatedItem` | `updateRelatedItem` | `deleteRelatedItem` | `existsRelatedItem` | Compound `RelatedItem` |
+| `stocktransactions` | `listStockTransactions` | `getStockTransaction` | `createStockTransaction` | `updateStockTransaction` | `deleteStockTransaction` | `existsStockTransaction` | Compound `StockTransaction` |
+
+When in doubt, look up the operationId in `src/generated/operations.js` (or `openapi/api.json`) rather
+than constructing it from the noun.
+
+## API-Backed Entities
+
+These are the 64 entities that have direct list endpoints in `api.json`.
+
+### CRM, Customer, and Relationship Entities
+
+| Entity | Purpose | Agent relevance |
+|------|---------|-----------------|
+| `accounts` | Customer, supplier, prospect, or employee master records | Resolve customers, suppliers, and account-level ownership |
+| `contacts` | People linked to accounts | Resolve human contacts and email addresses |
+| `addresses` | Additional address records linked to accounts or contacts | Find customer delivery or contact location details |
+| `contacts2contacts` | Contact-to-contact relationships | Trace person-to-person links |
+| `opportunities` | Sales pipeline and deal records | Revenue forecasting and pre-sales analysis |
+| `campaigns` | Marketing or outreach campaigns | Attribution and participant targeting |
+| `contracts` | Long-lived commercial agreements | Billing-cycle and subscription-style reasoning |
+| `participants` | Contacts enrolled in campaigns or mailing lists | Audience and outreach analysis |
+| `mailinglists` | Mailing list definitions | Bulk communication grouping |
+
+### Work, Delivery, and Calendar Entities
+
+| Entity | Purpose | Agent relevance |
+|------|---------|-----------------|
+| `tickets` | Support or service work items | Backlog, SLA, customer issue tracking |
+| `tasks` | Actionable delivery work | Assignee workload and execution detail |
+| `actionsteps` | Cross-record follow-up work items with assignee, due date, status, and effort | Track operational next steps below or alongside tasks and tickets |
+| `projects` | Top-level initiatives | Initiative state and work grouping |
+| `appointments` | Calendar appointments | Meeting and schedule queries |
+| `invitations` | Appointment invitations | Attendance and invite state |
+| `events` | Generic event records attached to entities | Timeline or activity display |
+
+### Messaging, Knowledge, and Collaboration Entities
+
+| Entity | Purpose | Agent relevance |
+|------|---------|-----------------|
+| `messages` | Email and message records | Inbox summaries, draft preparation, thread reconstruction |
+| `mailingrecipients` | Recipient records for a message | Audit mail recipients beyond the primary `to` field |
+| `messagereads` | Read-tracking records for messages | Detect whether users opened a message |
+| `notes` | Text-centric internal knowledge items | SOP summaries and operational notes |
+| `documents` | Formal file-like business documents | Final SOPs, policies, controlled artifacts |
+| `files` | Attachments linked to a record or comment | Attachment lookup and file inventory |
+| `comments` | Record-linked comments | Discussion and audit context |
+| `channels` | Collaboration or distribution channels | Group records into shared streams; practical business meaning should be confirmed |
+| `entities2channels` | Junction between records and channels | Determine which records belong to which channels |
+| `follows` | Follow/watch subscriptions on entities | Track who follows a record |
+| `likes` | Lightweight positive reactions on records | Lightweight engagement signal |
+| `records` | Generic feed and discussion records with entity/index references | Activity, posting, and collaboration wrapper for comments, likes, files, and channels |
+
+### Billing, Payments, and Collections Entities
+
+| Entity | Purpose | Agent relevance |
+|------|---------|-----------------|
+| `transactions` | Billing, procurement, or production business transactions | Invoice totals, revenue-like metrics, line-item analysis |
+| `payments` | Cash movement records | Cash received, settlement, payment history |
+| `ledgers` | Payment ledger definitions | Ledger-scoped payment analysis |
+| `dunning` | Collection or dunning notices | Overdue collection workflows |
+| `dunning2transactions` | Dunning-to-transaction junction | Trace which invoices are part of a dunning process |
+
+### Inventory, Pricing, and Commerce Entities
+
+| Entity | Purpose | Agent relevance |
+|------|---------|-----------------|
+| `items` | Product and service catalog entries | Price, SKU, and product mix analysis |
+| `categories` | Category definitions | Organize items or related commerce objects |
+| `components` | Item-to-item composition records | BOM or kit-like breakdowns |
+| `relateditems` | Related product links | Cross-sell, substitute, or accessory logic |
+| `stocktransactions` | Inventory movements | Stock flow and location history |
+| `storages` | Inventory storage locations | Warehouse and storage analysis |
+| `suppliers` | Supplier-to-item links | Procurement sourcing and vendor pricing |
+| `pricelists` | Price list definitions | Segment or channel pricing |
+| `pricelists2accounts` | Account-to-price-list assignments | Determine which pricing applies to a customer |
+| `prices` | Item prices within a price list | Effective sell price and discounts |
+| `coupons` | Coupon definitions | Promotion logic |
+| `couponcodes` | Codes under a coupon definition | Redeemable campaign-style coupon values |
+
+### Platform, Extensibility, Admin, and Dev Entities
+
+| Entity | Purpose | Agent relevance |
+|------|---------|-----------------|
+| `users` | System users | Resolve assignees and ownership |
+| `groups` | User groups | Access control and team grouping |
+| `groups2users` | Group membership junction | Resolve team membership |
+| `permissions` | Group-level permission grants | Access and authorization analysis |
+| `applications` | Application definitions | Dev/admin surface, app inventory |
+| `applicationassets` | Assets linked to an application | App packaging and static resources |
+| `resources` | Named resources linked to an application or standalone | Dev/admin runtime surface; likely asset/resource registry |
+| `services` | Hook, timing, or remote-call services | Automation and lifecycle hook inventory |
+| `weblets` | UI modules with view/type metadata | Embedded or detached UI component inventory |
+| `forks` | Module/fork definitions with identifiers and module names | Platform modularization and ownership boundaries |
+| `customfields` | Custom field definitions | Understand extdata and dynamic schema |
+| `objects` | Custom object records with arbitrary JSON payloads | Custom domain data not covered by core entities |
+| `links` | Link records with name and description | Generic linkage surface; exact business role should be confirmed |
+| `davservers` | DAV server definitions | Calendar/contact sync infrastructure |
+| `feedservers` | Feed server definitions | Feed ingestion infrastructure |
+| `binfiles` | Binary file storage records | Underlying binary payload access |
+| `associations` | Generic cross-entity relation records with metadata | Flexible graph-style linking when typed FKs do not exist |
+| `devices` | Inventory device records | Hardware or device inventory tracking |
+| `mailservers` | Mail server definitions | Messaging infrastructure and account routing |
+
+## Non-API Entity Families And Helper Structures
+
+These entities exist in `dbref.json` but are not listed as top-level list resources in `api.json`. Agents should understand them as storage helpers, views, metadata, or internal runtime tables.
+
+### Extdata Helper Families
+
+Purpose:
+
+- support indexed custom-field storage
+- separate regular, numeric, empty, and zero-like extdata states
+- materialize query-friendly views over custom data
+
+Family members are defined for these 40 base entities:
+
+`accounts`, `actionsteps`, `applications`, `appointments`, `campaigns`, `channels`, `contacts`, `contracts`, `couponcodes`, `coupons`, `customfields`, `davservers`, `devices`, `documents`, `dunning`, `feedservers`, `forks`, `groups`, `items`, `ledgers`, `links`, `mailinglists`, `mailservers`, `messages`, `notes`, `objects`, `opportunities`, `participants`, `payments`, `pricelists`, `projects`, `resources`, `services`, `stocktransactions`, `storages`, `tasks`, `tickets`, `transactions`, `users`, `weblets`
+
+Families:
+
+- `extdataempty_*`
+- `extdatanumeric_*`
+- `extdataregular_*`
+- `extdatazero_*`
+- `extdatavalues_*`
+
+Exact entity names:
+
+```text
+extdataempty_accounts
+extdataempty_actionsteps
+extdataempty_applications
+extdataempty_appointments
+extdataempty_campaigns
+extdataempty_channels
+extdataempty_contacts
+extdataempty_contracts
+extdataempty_couponcodes
+extdataempty_coupons
+extdataempty_customfields
+extdataempty_davservers
+extdataempty_devices
+extdataempty_documents
+extdataempty_dunning
+extdataempty_feedservers
+extdataempty_forks
+extdataempty_groups
+extdataempty_items
+extdataempty_ledgers
+extdataempty_links
+extdataempty_mailinglists
+extdataempty_mailservers
+extdataempty_messages
+extdataempty_notes
+extdataempty_objects
+extdataempty_opportunities
+extdataempty_participants
+extdataempty_payments
+extdataempty_pricelists
+extdataempty_projects
+extdataempty_resources
+extdataempty_services
+extdataempty_stocktransactions
+extdataempty_storages
+extdataempty_tasks
+extdataempty_tickets
+extdataempty_transactions
+extdataempty_users
+extdataempty_weblets
+extdatanumeric_accounts
+extdatanumeric_actionsteps
+extdatanumeric_applications
+extdatanumeric_appointments
+extdatanumeric_campaigns
+extdatanumeric_channels
+extdatanumeric_contacts
+extdatanumeric_contracts
+extdatanumeric_couponcodes
+extdatanumeric_coupons
+extdatanumeric_customfields
+extdatanumeric_davservers
+extdatanumeric_devices
+extdatanumeric_documents
+extdatanumeric_dunning
+extdatanumeric_feedservers
+extdatanumeric_forks
+extdatanumeric_groups
+extdatanumeric_items
+extdatanumeric_ledgers
+extdatanumeric_links
+extdatanumeric_mailinglists
+extdatanumeric_mailservers
+extdatanumeric_messages
+extdatanumeric_notes
+extdatanumeric_objects
+extdatanumeric_opportunities
+extdatanumeric_participants
+extdatanumeric_payments
+extdatanumeric_pricelists
+extdatanumeric_projects
+extdatanumeric_resources
+extdatanumeric_services
+extdatanumeric_stocktransactions
+extdatanumeric_storages
+extdatanumeric_tasks
+extdatanumeric_tickets
+extdatanumeric_transactions
+extdatanumeric_users
+extdatanumeric_weblets
+extdataregular_accounts
+extdataregular_actionsteps
+extdataregular_applications
+extdataregular_appointments
+extdataregular_campaigns
+extdataregular_channels
+extdataregular_contacts
+extdataregular_contracts
+extdataregular_couponcodes
+extdataregular_coupons
+extdataregular_customfields
+extdataregular_davservers
+extdataregular_devices
+extdataregular_documents
+extdataregular_dunning
+extdataregular_feedservers
+extdataregular_forks
+extdataregular_groups
+extdataregular_items
+extdataregular_ledgers
+extdataregular_links
+extdataregular_mailinglists
+extdataregular_mailservers
+extdataregular_messages
+extdataregular_notes
+extdataregular_objects
+extdataregular_opportunities
+extdataregular_participants
+extdataregular_payments
+extdataregular_pricelists
+extdataregular_projects
+extdataregular_resources
+extdataregular_services
+extdataregular_stocktransactions
+extdataregular_storages
+extdataregular_tasks
+extdataregular_tickets
+extdataregular_transactions
+extdataregular_users
+extdataregular_weblets
+extdatavalues_accounts
+extdatavalues_actionsteps
+extdatavalues_applications
+extdatavalues_appointments
+extdatavalues_campaigns
+extdatavalues_channels
+extdatavalues_contacts
+extdatavalues_contracts
+extdatavalues_couponcodes
+extdatavalues_coupons
+extdatavalues_customfields
+extdatavalues_davservers
+extdatavalues_devices
+extdatavalues_documents
+extdatavalues_dunning
+extdatavalues_feedservers
+extdatavalues_forks
+extdatavalues_groups
+extdatavalues_items
+extdatavalues_ledgers
+extdatavalues_links
+extdatavalues_mailinglists
+extdatavalues_mailservers
+extdatavalues_messages
+extdatavalues_notes
+extdatavalues_objects
+extdatavalues_opportunities
+extdatavalues_participants
+extdatavalues_payments
+extdatavalues_pricelists
+extdatavalues_projects
+extdatavalues_resources
+extdatavalues_services
+extdatavalues_stocktransactions
+extdatavalues_storages
+extdatavalues_tasks
+extdatavalues_tickets
+extdatavalues_transactions
+extdatavalues_users
+extdatavalues_weblets
+extdatazero_accounts
+extdatazero_actionsteps
+extdatazero_applications
+extdatazero_appointments
+extdatazero_campaigns
+extdatazero_channels
+extdatazero_contacts
+extdatazero_contracts
+extdatazero_couponcodes
+extdatazero_coupons
+extdatazero_customfields
+extdatazero_davservers
+extdatazero_devices
+extdatazero_documents
+extdatazero_dunning
+extdatazero_feedservers
+extdatazero_forks
+extdatazero_groups
+extdatazero_items
+extdatazero_ledgers
+extdatazero_links
+extdatazero_mailinglists
+extdatazero_mailservers
+extdatazero_messages
+extdatazero_notes
+extdatazero_objects
+extdatazero_opportunities
+extdatazero_participants
+extdatazero_payments
+extdatazero_pricelists
+extdatazero_projects
+extdatazero_resources
+extdatazero_services
+extdatazero_stocktransactions
+extdatazero_storages
+extdatazero_tasks
+extdatazero_tickets
+extdatazero_transactions
+extdatazero_users
+extdatazero_weblets
+```
+
+Global extdata support objects:
+
+- `extdata`
+- `extdatafields`
+- `extdatavalues`
+
+### Tagging Structures
+
+Purpose:
+
+- provide global tag names and per-entity tag assignments
+
+Global objects:
+
+- `tagnames`
+- `tags`
+- `tagrels`
+
+Per-entity tag relation tables exist for these 37 base entities:
+
+`accounts`, `actionsteps`, `applications`, `appointments`, `campaigns`, `channels`, `contacts`, `contracts`, `coupons`, `customfields`, `davservers`, `devices`, `documents`, `dunning`, `feedservers`, `forks`, `groups`, `items`, `ledgers`, `links`, `mailinglists`, `mailservers`, `messages`, `notes`, `objects`, `opportunities`, `payments`, `pricelists`, `projects`, `resources`, `services`, `storages`, `tasks`, `tickets`, `transactions`, `users`, `weblets`
+
+Exact entity names:
+
+```text
+tagrels_accounts
+tagrels_actionsteps
+tagrels_applications
+tagrels_appointments
+tagrels_campaigns
+tagrels_channels
+tagrels_contacts
+tagrels_contracts
+tagrels_coupons
+tagrels_customfields
+tagrels_davservers
+tagrels_devices
+tagrels_documents
+tagrels_dunning
+tagrels_feedservers
+tagrels_forks
+tagrels_groups
+tagrels_items
+tagrels_ledgers
+tagrels_links
+tagrels_mailinglists
+tagrels_mailservers
+tagrels_messages
+tagrels_notes
+tagrels_objects
+tagrels_opportunities
+tagrels_payments
+tagrels_pricelists
+tagrels_projects
+tagrels_resources
+tagrels_services
+tagrels_storages
+tagrels_tasks
+tagrels_tickets
+tagrels_transactions
+tagrels_users
+tagrels_weblets
+```
+
+### Static Metadata Tables
+
+Purpose:
+
+- provide reference dictionaries for geography, currencies, languages, taxonomies, modules, time zones, and units
+
+Entities:
+
+`meta_cities`, `meta_countries`, `meta_countries_borders`, `meta_countries_languages`, `meta_countries_names`, `meta_currencies`, `meta_currencies_names`, `meta_languages`, `meta_languages_names`, `meta_modules`, `meta_modules_names`, `meta_postalcodes`, `meta_regions`, `meta_regions_names`, `meta_states`, `meta_subregions`, `meta_subregions_names`, `meta_taxonomy_cn`, `meta_taxonomy_cn_names`, `meta_taxonomy_cpv`, `meta_taxonomy_cpv_names`, `meta_taxonomy_google`, `meta_taxonomy_google_names`, `meta_taxonomy_gpc`, `meta_taxonomy_gpc_names`, `meta_taxonomy_hts`, `meta_taxonomy_hts_names`, `meta_taxonomy_unspsc`, `meta_taxonomy_unspsc_names`, `meta_timezones`, `meta_timezones_offsets`, `meta_tlds`, `meta_units`
+
+### Versioning, Mapping, and Sync Tables
+
+Purpose:
+
+- store binary version history, protocol mappings, or sync identifiers
+
+Entities:
+
+- `documentversions`
+- `enhancementversions`
+- `feedids`
+- `imapids`
+- `davids`
+
+### Runtime, Audit, Session, and Personalization Tables
+
+Purpose:
+
+- store usage, authentication, imports, recently viewed records, saved views, and user-specific UI state
+
+Entities:
+
+- `cpu`
+- `cpucollector`
+- `imports`
+- `logins`
+- `notifications`
+- `numcounters`
+- `recent`
+- `tokens`
+- `usagestats`
+- `userfields`
+- `userfilters`
+- `views`
+
+## Agent Query Priority
+
+Use this priority order when deciding what to read first:
+
+1. Core business entities such as `accounts`, `contacts`, `tickets`, `tasks`, `projects`, `messages`, `notes`, `documents`, `transactions`, and `payments`
+2. Junction entities such as `mailingrecipients`, `pricelists2accounts`, `dunning2transactions`, `groups2users`, `entities2channels` (note: these have diverging operationIds — see [Entity Noun to REST operationId](#entity-noun-to-rest-operationid))
+3. Platform and extensibility entities such as `customfields`, `objects`, `applications`, `services`, `weblets`, `forks`
+4. Internal helper families such as `extdata*`, `tagrels*`, `meta_*`, and runtime tables
+
+## High-Value Use Cases By Entity Cluster
+
+- Customer 360: `accounts`, `contacts`, `addresses`, `tickets`, `transactions`, `payments`, `messages`
+- Work routing: `users`, `tasks`, `tickets`, `projects`, `actionsteps`
+- Customer mail summaries: `accounts`, `contacts`, `messages`, `mailingrecipients`, `tickets`
+- Revenue and collections: `transactions`, `payments`, `ledgers`, `dunning`, `dunning2transactions`
+- Campaign and outreach execution: `campaigns`, `mailinglists`, `participants`, `messages`, `mailingrecipients`, `messagereads`
+- Knowledge retrieval: `notes`, `documents`, `files`, `comments`
+- Pricing and stock: `items`, `prices`, `pricelists`, `pricelists2accounts`, `stocktransactions`, `storages`, `suppliers`
+- Collaboration and activity feeds: `records`, `comments`, `files`, `channels`, `entities2channels`, `follows`, `likes`, `events`
+- Platform and schema: `applications`, `resources`, `services`, `weblets`, `forks`, `groups`, `groups2users`, `permissions`, `customfields`, `objects`
+
+## Benchmark-Backed Agent Defaults
+
+Use these defaults unless the target instance clearly behaves differently:
+
+- `actionsteps`: record-bound activities or follow-ups
+- `records`, `comments`, `files`, and `events`: user-facing timeline/feed layer
+- `channels` and `entities2channels`: collaboration spaces and record-to-channel links
+- `follows`: watcher/subscription state
+- `likes`: lightweight engagement signal
+- `dunning`: collection-stage object, not the receivable itself
+
+## Open Product-Semantics Questions
+
+These are structurally understandable from the schema, but their business meaning is still partly product-specific:
+
+- `links`: what business object does a link usually represent in your instance?
+- `records`, `comments`, `follows`, `likes`, and `events`: how important is this collaboration layer in real customer deployments?
+- `channels` and `entities2channels`: are they widely used as collaboration rooms, or only in selected app modules?
+- `forks`, `resources`, `services`, and `weblets`: should these stay low-priority platform/admin surfaces for agents, or are they intended to be queried by external coding agents regularly?

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

@@ -0,0 +1,89 @@
+# ZeyOS Query Patterns
+
+Use this file as the default operating playbook before answering any business question against ZeyOS.
+
+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).
+
+## Default Execution Order
+
+1. Resolve the business nouns in the prompt into concrete ZeyOS entities.
+2. Resolve human labels to IDs before querying related records.
+3. Normalize the time window into Unix timestamps in seconds.
+4. Choose the primary resource first. Do not join across domains until the primary record set is clear.
+5. Choose the interface:
+   - Use the CLI for registry-backed CRUD and straightforward list/get/count flows.
+   - Use `@zeyos/client` when you need unsupported resources, `expand`, binary access, richer request control, or multi-step correlation logic.
+6. Query only the fields needed for the next decision.
+7. Run follow-up queries only for relationships that affect the answer.
+8. State assumptions and ambiguities in the final answer.
+
+## 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.
+- 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.
+- Treat list operations as `POST` queries.
+- Treat `filter` versus `filters` as a source inconsistency, not a universal rule:
+  - `api.json` documents `filter`
+  - repo client and sample code use `filters`
+  - the CLI exposes `--filter` but writes `filters` internally
+- Use `body: { ... }` for PATCH updates that also pass `ID`.
+- Treat `extdata` and `expand` as different features:
+  - `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.
+- 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.
+
+## Benchmark-Backed Semantic Defaults
+
+Use these defaults unless the target instance clearly behaves differently:
+
+- `projects`, `tickets`, and `tasks` are governed work objects.
+- `actionsteps` are record-bound follow-up activities:
+  - use them for next promises, reminders, and collector or account follow-ups
+  - do not automatically inflate them into full project tasks
+- `records`, `comments`, `files`, and `events` form a record timeline or activity feed:
+  - use them when the user asks "what happened on this account/project/ticket?"
+  - do not treat them as mere infrastructure if there is evidence of user-facing activity
+- `channels` and `entities2channels` are collaboration spaces or record-to-channel sharing links:
+  - prefer this interpretation over pure categorization unless the instance says otherwise
+- `follows` and `likes` are attention and engagement signals, not access-control objects.
+- `dunning` is a stage in a collections process, not the receivable itself:
+  - separate invoice exposure from collection stage and next action
+- `links` should stay low-priority until the instance proves they represent a meaningful business domain rather than a generic URL store.
+
+## 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 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`.
+- Resolve a transaction with `transactions.transactionnum`.
+- Resolve a note or document with `name`, `documentnum`, `filename`, and status.
+
+## Time Windows
+
+- ZeyOS timestamps are Unix seconds, not milliseconds.
+- Use `date` for business-effective dates such as invoice date or message date.
+- Use `lastmodified` for recent activity or change tracking.
+- For phrases like "this year", anchor to the current calendar year unless the user asks for fiscal logic.
+
+## Answering Discipline
+
+- Separate facts from inference.
+- When the schema does not encode the business concept directly, explain the proxy.
+- When an answer mixes governed work, activity feed, and collaboration spaces, label those layers separately.
+- If a query depends on an unstated metric definition, ask or make the assumption explicit.
+
+## Escalation Checklist
+
+Escalate from the CLI to `@zeyos/client` when you need any of the following:
+
+- unsupported resources or operations
+- `expand` or binary-file access
+- client-side aggregation after multiple list calls
+- more careful response normalization
+- raw request control or custom retries