@zeyos/client 0.1.0

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

@@ -0,0 +1,132 @@
+# Collections And Dunning Workflows
+
+## Primary Resources
+
+The DB-table noun is not the operationId. Use the operationIds below with `@zeyos/client`
+(`client.api.<operationId>(...)`); see [../../shared/zeyos-entity-reference.md](../../shared/zeyos-entity-reference.md#entity-noun-to-rest-operationid) for the full mapping.
+
+| Concept | dbref noun | list operationId | single-record operationIds |
+|---------|------------|------------------|----------------------------|
+| Accounts | `accounts` | `listAccounts` | `getAccount`, `createAccount`, `updateAccount`, `deleteAccount` |
+| Transactions / invoices | `transactions` | `listTransactions` | `getTransaction`, `createTransaction`, `updateTransaction`, `deleteTransaction` |
+| Payments | `payments` | `listPayments` | `getPayment`, `createPayment`, `updatePayment`, `deletePayment` |
+| Dunning notices | `dunning` | `listDunningNotices` | `getDunningNotice`, `createDunningNotice`, `updateDunningNotice`, `deleteDunningNotice` |
+| Dunning-to-transaction links | `dunning2transactions` | `listDunningToTransactions` | `getDunningToTransaction`, `createDunningToTransaction`, `deleteDunningToTransaction` |
+
+Note: `dunning` is the **`DunningNotice`** entity (not `Dunning`), and `dunning2transactions`
+is the `DunningToTransaction` junction. Calling `client.api.listDunning(...)` or
+`client.api.listDunning2transactions(...)` will fail with "operation not found".
+
+## Important Status Caution
+
+- `transactions.status` is broad and mixes lifecycle states such as invoiced, partly paid, paid, cancelled, and closed.
+- `payments` can point either to a `transaction` or directly to an `account`.
+- Do not claim exact open balance from schema alone if the available payment records are only account-level and not transaction-linked.
+- Do not invent multi-level dunning procedures if the instance only exposes `type`, `status`, `date`, and `duedate`.
+
+## Pattern: Overdue Invoices For A Customer
+
+Use this for prompts like:
+
+- "Which invoices are overdue for customer XYZ?"
+- "Show overdue receivables for ACME."
+
+Recommended approach:
+
+1. Resolve the account.
+2. Query billing invoices from `transactions` for that account.
+3. Filter by `type = 3` and `duedate < now`.
+4. Exclude clearly cancelled records.
+5. If the user asks whether they are already in collections, follow with `dunning2transactions` and `dunning`.
+
+Client example:
+
+```js
+const overdueInvoices = await client.api.listTransactions({
+  fields: ['ID', 'transactionnum', 'account', 'date', 'duedate', 'status', 'netamount', 'currency'],
+  filters: {
+    account: accountId,
+    type: 3,
+    duedate: { '<': nowTs },
+  },
+  sort: ['+duedate'],
+  limit: 200,
+});
+```
+
+## Pattern: Open Dunning Notices And Covered Invoices
+
+Use this for prompts like:
+
+- "What dunning notices are still open?"
+- "Which invoices are part of reminder notice 2025-004?"
+
+Recommended approach:
+
+1. Resolve the dunning record or account first.
+2. Query `dunning` notices via `listDunningNotices` for active or recently relevant notices.
+3. Query `dunning2transactions` via `listDunningToTransactions` for the linked transaction IDs.
+4. Fetch the linked `transactions` to show invoice numbers, due dates, and values.
+5. Present the result by dunning notice, then by covered invoice.
+
+## Pattern: Account Collection Status
+
+Use this for prompts like:
+
+- "Show the payment gap for ACME and whether any invoices are already in dunning."
+- "What is the current collection status for customer XYZ?"
+
+Recommended approach:
+
+1. Resolve the account.
+2. Query invoice transactions for the account.
+3. Query payments for the same account, and separately note which payments are directly tied to transactions.
+4. Query dunning notices for the account.
+5. Use `dunning2transactions` to mark which invoices are already in a reminder or notice flow.
+6. Present:
+   - overdue invoices
+   - payments received
+   - invoices already in dunning
+   - invoices still overdue but not yet in dunning
+
+## Pattern: Receivables Needing Follow-Up This Week
+
+Use this for prompts like:
+
+- "Which receivables need follow-up this week?"
+- "What should collections work on next?"
+
+Recommended approach:
+
+1. Start from overdue invoices.
+2. Split them into:
+   - already in dunning
+   - overdue without dunning
+   - near due date but not yet overdue
+3. If open `actionsteps` exist on the same account or transaction, include them as the operational next-step layer.
+4. Be explicit when the prioritization is heuristic rather than enforced by schema.
+
+## Pattern: Next Collection Step
+
+Use this for prompts like:
+
+- "Which accounts should move to the next collection step?"
+- "What should collections do next?"
+
+Recommended approach:
+
+1. Start from overdue invoices and current dunning notices.
+2. Group by account.
+3. Distinguish:
+   - overdue with no dunning yet
+   - reminder issued but still unpaid
+   - notice issued and still unpaid
+4. If `assigneduser` or open `actionsteps` exist, use them as the operational ownership layer.
+5. Present the recommendation as a heuristic next action unless the instance has a fully defined dunning procedure elsewhere.
+
+## Common Failure Modes
+
+- Treating invoice creation and cash receipt as the same thing.
+- Assuming every payment can be allocated exactly to one invoice.
+- Treating dunning state as visible from `transactions` without checking `dunning2transactions`.
+- Ignoring credits when the user asks for net receivable exposure.

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

@@ -0,0 +1,38 @@
+---
+name: zeyos-commerce-and-inventory
+description: Analyze ZeyOS items, pricing, price lists, supplier links, stock movement, storage, coupons, and related commerce entities. Use when asked about customer-specific pricing, item catalogs, stock availability, supplier sourcing, applicable price lists, or product and inventory questions that span items, prices, accounts, and stock transactions.
+---
+
+# 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.
+
+Typical prompts:
+
+- "What price does customer XYZ get for item ABC?"
+- "Which items are low on stock?"
+- "Who are the suppliers for item ABC?"
+- "Which price list applies to account ACME?"
+
+## Workflow
+
+1. Resolve the item, account, price list, or storage first.
+2. Distinguish catalog questions from pricing questions and stock questions.
+3. Use:
+   - `items` for product identity
+   - `prices` and `pricelists` for effective commercial pricing
+   - `pricelists2accounts` for account-specific price-list assignment (operationId `listPriceListsToAccounts`; `pricelists` -> `listPriceLists`)
+   - `stocktransactions` and `storages` for inventory movement and location (`stocktransactions` -> `listStockTransactions`; these dbref nouns do not map naively — see [../shared/zeyos-entity-reference.md](../shared/zeyos-entity-reference.md#entity-noun-to-rest-operationid))
+   - `suppliers` for vendor sourcing
+4. State whether a quoted price is:
+   - base item price
+   - price-list override
+   - customer-specific via price-list assignment
+5. Treat stock answers as derived from movements unless the question explicitly asks for transaction history.
+6. Keep procurement-side and billing-side price logic separate.
+
+## Output Discipline
+
+- Start with the resolved item/account/storage identity.
+- Separate price determination from stock determination.
+- Call out whether the answer came from item defaults, price lists, supplier pricing, or stock movements.

package/agents/zeyos-commerce-and-inventory/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ZeyOS Commerce and Inventory"
+  short_description: "Items, pricing, stock, suppliers, catalogs"
+  default_prompt: "Use $zeyos-commerce-and-inventory to analyze items, prices, stock, suppliers, and customer-specific pricing."

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

@@ -0,0 +1,101 @@
+# Commerce And Inventory Workflows
+
+## Primary Resources
+
+- `items`
+- `prices`
+- `pricelists`
+- `pricelists2accounts`
+- `stocktransactions`
+- `storages`
+- `suppliers`
+- `relateditems`
+- `components`
+- `coupons`
+- `couponcodes`
+
+These are dbref nouns, not operationIds. Several diverge: `pricelists` -> `listPriceLists`,
+`pricelists2accounts` -> `listPriceListsToAccounts`, `stocktransactions` -> `listStockTransactions`,
+`relateditems` -> `listRelatedItems`, `couponcodes` -> `listCouponCodes`. See
+[../../shared/zeyos-entity-reference.md](../../shared/zeyos-entity-reference.md#entity-noun-to-rest-operationid)
+before calling `@zeyos/client`.
+
+## Pattern: Effective Price For A Customer
+
+Use this for prompts like:
+
+- "What price does customer XYZ get for item ABC?"
+- "Which price applies to ACME for this SKU?"
+
+Recommended approach:
+
+1. Resolve the account.
+2. Resolve the item.
+3. Query `pricelists2accounts` to find assigned price lists.
+4. Query `prices` for the item across those price lists.
+5. If no override exists, fall back to item default selling or purchase price depending on the commercial context.
+
+Important caveat:
+
+- `prices.price` may explicitly fall back to item defaults according to the schema. Say when that happened.
+
+## Pattern: Low Stock Or Stock History
+
+Use this for prompts like:
+
+- "Which items are low on stock?"
+- "Show stock movements for item ABC in the last month."
+
+Recommended approach:
+
+1. Resolve the item or storage scope.
+2. Query `stocktransactions` in the relevant period.
+3. Aggregate movement client-side for availability-style answers.
+4. Keep the raw transaction list for audit-style answers.
+
+## Pattern: Supplier Lookup
+
+Use this for prompts like:
+
+- "Who are the suppliers for item ABC?"
+- "What supplier price do we have for this item?"
+
+Recommended approach:
+
+1. Resolve the item.
+2. Query `suppliers` for that item.
+3. Resolve supplier accounts to readable names if needed.
+4. Present supplier price, minimum amount, and delivery time when available.
+
+## Pattern: Price List Coverage
+
+Use this for prompts like:
+
+- "Which price list applies to ACME?"
+- "Which accounts use price list Spring 2026?"
+
+Recommended approach:
+
+1. Resolve either the account or the price list first.
+2. Query `pricelists2accounts`.
+3. Join to `pricelists` or `accounts` for names and active dates.
+
+## Pattern: Promotions And Coupon Codes
+
+Use this for prompts like:
+
+- "Which coupons are active right now?"
+- "Which codes belong to coupon Spring Promo?"
+
+Recommended approach:
+
+1. Query `coupons` for active date windows and activity state.
+2. Query `couponcodes` when the user needs concrete redeemable codes.
+3. Keep generic promotion definitions separate from individual codes.
+
+## Common Failure Modes
+
+- Quoting a price without saying whether it is default or overridden.
+- Mixing billing and procurement price logic.
+- Reporting stock from one storage as if it were global inventory.
+- Ignoring minimum quantities or supplier-specific constraints.

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

@@ -0,0 +1,35 @@
+---
+name: zeyos-mail-operations
+description: Query, summarize, and draft ZeyOS email and message records. Use when asked to summarize recent customer mail, reconstruct threads, find inbox or draft messages, prepare reply drafts, or explain how messages connect to tickets, opportunities, and customer identities.
+---
+
+# 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.
+
+Typical prompts:
+
+- "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."
+- "Show me the conversation behind ticket 812."
+
+## Workflow
+
+1. Resolve the business subject first:
+   - customer account
+   - contact or email address
+   - linked ticket or opportunity
+2. Decide whether the user wants inbox analysis, thread reconstruction, or draft creation.
+3. Query `messages` with a minimal field set first: sender, recipient, subject, date, mailbox, ticket, opportunity, reference, and message ID.
+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.
+8. Escalate to `@zeyos/client` when you need binary content, MIME expansion, or richer message correlation than the CLI can express cleanly.
+
+## Output Discipline
+
+- Report the resolved customer identity and the email addresses used for matching.
+- Separate inbound, draft, and sent messages.
+- Call out whether a thread match was direct by email address or inferred through ticket/opportunity context.

package/agents/zeyos-mail-operations/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ZeyOS Mail Operations"
+  short_description: "Email search, summaries, drafts, threads"
+  default_prompt: "Use $zeyos-mail-operations to summarize messages, trace customer email threads, and draft replies."

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

@@ -0,0 +1,110 @@
+# Mail Operations Workflows
+
+## Mailbox Values
+
+- `0` = inbox
+- `1` = drafts
+- `2` = sent
+- `5` = archive
+- `6` = trash
+- `7` = junk
+
+## Key Constraint
+
+The documented `messages` schema does not expose a direct `account` foreign key. Customer mail questions usually require one of these paths:
+
+- resolve customer email addresses and match `sender_email` / `to_email`
+- resolve linked tickets or opportunities and match `message.ticket` / `message.opportunity`
+
+Mailing-list and campaign questions are different:
+
+- `messages.mailinglist` links a message to a mailing list
+- `mailingrecipients` links that message to `participants`
+- deeper outreach analysis belongs in `zeyos-campaign-and-outreach`
+
+## Pattern: Summarize Recent Mail From A Customer
+
+Use this for prompts like:
+
+- "Give me a summary of all recent mails from customer XYZ."
+- "What has Acme sent us this week?"
+
+Recommended approach:
+
+1. Resolve the customer account.
+2. Resolve related contacts and likely email addresses.
+3. Query recent messages where `sender_email` or `to_email` matches those addresses.
+4. Sort by descending `date`.
+5. Pull `text` only for the matched subset you need to summarize.
+6. Group by thread using `reference`, `messageid`, and subject.
+
+Client example:
+
+```js
+const recentMessages = await client.api.listMessages({
+  fields: ['ID', 'date', 'mailbox', 'subject', 'sender_email', 'to_email', 'ticket', 'reference', 'messageid', 'text'],
+  filters: {
+    sender_email: customerEmail,
+    date: { '>': cutoff },
+  },
+  sort: ['-date'],
+  limit: 100,
+});
+```
+
+If more than one customer email exists, run one query per address or build a composite filter group.
+
+## Pattern: Reconstruct A Thread
+
+Use this for prompts like:
+
+- "Show me the conversation behind ticket 812."
+- "What happened in this email thread?"
+
+Recommended approach:
+
+1. Query messages linked to the ticket or opportunity if you have that ID.
+2. Sort by ascending `date` for reading order.
+3. Use `reference` and `messageid` to confirm direct reply relationships.
+4. Use subject matching only as a fallback.
+
+## Pattern: Find Unanswered Customer Mail
+
+Use this for prompts like:
+
+- "Which open tickets have unanswered customer emails?"
+- "Show inbox messages from customers that still need a reply."
+
+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.
+5. Report unresolved threads and their linked tickets if available.
+
+## Pattern: Draft A Reply
+
+Use this for prompts like:
+
+- "Draft a response to the latest mail from customer XYZ."
+- "Prepare an answer but do not send it."
+
+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.
+
+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.
+- Never send email just because a user asked for a summary or a draft.
+
+## Common Failure Modes
+
+- Matching only on subject can merge unrelated threads.
+- Matching only on company name misses messages from individual contacts.
+- Messages may be linked to tickets or opportunities but not directly to accounts.
+- Campaign mailings run through `mailinglists` and `mailingrecipients`, which is a different workflow from inbox thread analysis.

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

@@ -0,0 +1,31 @@
+---
+name: zeyos-notes-and-sops
+description: Retrieve and summarize ZeyOS notes, SOPs, documents, and file-backed knowledge. Use when asked to find an internal procedure, summarize notes, locate the latest finalized operating document, inspect attachments, or explain whether knowledge lives in notes, documents, or files.
+---
+
+# 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.
+
+Typical prompts:
+
+- "Find the current escalation SOP for billing disputes."
+- "Summarize our notes on failed invoice syncs."
+- "Which finalized onboarding SOP changed last month?"
+- "Which files are attached to this document?"
+
+## Workflow
+
+1. Decide whether the user is asking for note text, a formal document, or an attachment.
+2. Prefer `notes` when the question is about readable text.
+3. Prefer `documents` when the question is about the official SOP artifact or finalized file.
+4. Use `files` only when the request is explicitly about attachments or file inventory.
+5. Prefer finalized material for SOP-style questions and say which status/date you used.
+6. Do not claim to have read binary document content unless you actually fetched it through the appropriate path.
+7. Present competing matches when names are similar or multiple revisions exist.
+
+## Output Discipline
+
+- State whether the answer came from a note, document, or attachment.
+- Report the status and last-modified context for SOP-style answers.
+- Call out when the documented schema does not expose direct business-record linkage.

package/agents/zeyos-notes-and-sops/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ZeyOS Notes and SOPs"
+  short_description: "Notes, SOP search, internal knowledge lookup"
+  default_prompt: "Use $zeyos-notes-and-sops to retrieve notes, SOPs, documents, and operational guidance."

package/agents/zeyos-notes-and-sops/references/workflows.md

@@ -0,0 +1,85 @@
+# Notes And SOP Workflows
+
+## Resource Choice
+
+Use `notes` when:
+
+- the user wants text content to summarize
+- the content is likely lightweight operational knowledge
+
+Use `documents` when:
+
+- the user wants the official or finalized SOP
+- the artifact is file-like and may have filename or document number metadata
+
+Use `files` when:
+
+- the user asks for attachments
+- you need to inspect what file objects are linked to a record or comment
+
+## Pattern: Find The Current SOP
+
+Use this for prompts like:
+
+- "Find the current escalation SOP for billing disputes."
+- "Which onboarding SOP is final right now?"
+
+Recommended approach:
+
+1. Search `documents` first with name- or filename-oriented filters plus final status where possible.
+2. Search `notes` second if the SOP may live as text rather than a file artifact.
+3. Prefer status `4` (`FINAL`) for both documents and notes when the user asks for the current or official process.
+4. If multiple finals exist, sort by `lastmodified` and present the top candidates instead of guessing.
+
+## Pattern: Summarize Internal Notes
+
+Use this for prompts like:
+
+- "Summarize the notes about the migration checklist."
+- "What do our notes say about handling failed invoice syncs?"
+
+Recommended approach:
+
+1. Search `notes` by `name`, `assigneduser`, or broader text-oriented query terms.
+2. Pull `text` only for the shortlisted notes.
+3. Summarize common instructions, warnings, and unresolved items.
+
+Important caveat:
+
+- The documented note schema does not show direct account, project, or ticket foreign keys. Search may therefore be keyword-driven unless the instance stores those references in note names or text.
+
+## Pattern: Retrieve A Formal File Or Attachment
+
+Use this for prompts like:
+
+- "Get me the attached SOP file."
+- "Which files are attached to this record?"
+
+Recommended approach:
+
+1. Resolve the parent note, document, or record first.
+2. Query `files` for attachments when the file inventory matters.
+3. Escalate to `@zeyos/client` if you need binary expansion or file-body handling.
+
+## Pattern: Compare Note Guidance Versus Formal SOP
+
+Use this for prompts like:
+
+- "Do our notes and the finalized SOP say the same thing?"
+- "Is the current onboarding SOP aligned with the internal notes?"
+
+Recommended approach:
+
+1. Retrieve the likely final document candidate first.
+2. Retrieve notes on the same topic second.
+3. Compare:
+   - procedural steps
+   - warnings and exceptions
+   - revision freshness
+4. Report conflicts explicitly instead of merging them into one synthetic answer.
+
+## Common Failure Modes
+
+- Claiming document text content without fetching the underlying binary.
+- Mixing drafts, revisions, and finals into one answer without saying so.
+- Assuming notes and documents have the same linkage model.

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

@@ -0,0 +1,37 @@
+---
+name: zeyos-platform-and-schema
+description: Inspect ZeyOS platform, schema, and admin-facing entities such as applications, resources, services, weblets, forks, groups, permissions, custom fields, custom objects, and generic record structures. Use when asked about application inventory, service hooks, UI modules, group permissions, custom schema, or how the extensibility model is wired.
+---
+
+# 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.
+
+Typical prompts:
+
+- "Which custom fields exist on tickets?"
+- "Which services run after ticket modification?"
+- "Which groups grant access to application XYZ?"
+- "Which weblets belong to application XYZ?"
+
+## Workflow
+
+1. Decide whether the question is about:
+   - platform application inventory
+   - automation hooks and services
+   - UI surfaces and weblets
+   - access control
+   - schema extensibility
+2. Resolve the application, group, entity, or custom field target first.
+3. Use:
+   - `applications`, `resources`, `services`, `weblets`, `forks` for platform structure
+   - `groups`, `groups2users`, `permissions` for access control (`groups2users` -> `listGroupsToUsers` / `getGroupToUser`)
+   - `customfields`, `objects`, and extdata helper families for schema and custom data (`customfields` -> `listCustomFields`; `applicationassets` -> `listApplicationAssets`; these dbref nouns do not map naively — see [../shared/zeyos-entity-reference.md](../shared/zeyos-entity-reference.md#entity-noun-to-rest-operationid))
+4. Treat `records`, `comments`, `files`, `channels`, `follows`, and `likes` as a collaboration layer. Switch to `zeyos-collaboration-and-activity` when the user asks for timeline or discussion behavior rather than platform structure.
+5. Be explicit when the schema tells you structure but not the product convention.
+
+## Output Discipline
+
+- Separate confirmed schema facts from product-level inference.
+- Report entity identifiers, activity states, and dependencies.
+- Call out when a recommendation depends on instance-specific app conventions.

package/agents/zeyos-platform-and-schema/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ZeyOS Platform and Schema"
+  short_description: "Apps, services, custom fields, schema admin"
+  default_prompt: "Use $zeyos-platform-and-schema to inspect applications, services, weblets, custom fields, groups, permissions, and custom objects."