@zeyos/client 0.1.0

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

@@ -0,0 +1,34 @@
+---
+name: zeyos-account-intelligence
+description: Analyze ZeyOS customer and account context across accounts, contacts, addresses, opportunities, contracts, campaigns, and related records. Use when asked for customer 360 summaries, active contacts, open opportunities, contract state, address completeness, or account-centric answers that span multiple CRM entities.
+---
+
+# 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.
+
+Typical prompts:
+
+- "Give me a 360 summary for customer XYZ."
+- "Who are the active contacts for customer XYZ?"
+- "What open opportunities and active contracts do we have with ACME?"
+- "Which accounts are missing billing addresses?"
+
+## Workflow
+
+1. Resolve the account first, then fan out to related entities.
+2. Treat `accounts` as the anchor record for customer 360 work.
+3. Pull `contacts`, `addresses`, `opportunities`, and `contracts` separately unless the answer only needs one layer.
+4. Distinguish:
+   - current relationship state
+   - future pipeline
+   - historical activity
+5. Use address type codes explicitly when the question is about billing or shipping readiness.
+6. Treat campaigns and participants as outreach context, not proof of commercial engagement. Use `zeyos-campaign-and-outreach` if the user wants mailing or campaign execution detail.
+7. State whether the answer is account-wide, contact-specific, or contract-specific.
+
+## Output Discipline
+
+- Start with the resolved account and the matching logic used.
+- Separate account master data from linked people, opportunities, and contracts.
+- Call out missing CRM hygiene fields such as missing contacts or missing billing addresses.

package/agents/zeyos-account-intelligence/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ZeyOS Account Intelligence"
+  short_description: "Accounts, contacts, contracts, customer 360"
+  default_prompt: "Use $zeyos-account-intelligence to answer customer 360 questions across accounts, contacts, opportunities, contracts, and related records."

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

@@ -0,0 +1,84 @@
+# Account Intelligence Workflows
+
+## Primary Resources
+
+- `accounts`
+- `contacts`
+- `addresses`
+- `opportunities`
+- `contracts`
+- `campaigns`
+- `participants`
+
+## Pattern: Customer 360 Summary
+
+Use this for prompts like:
+
+- "Give me a 360 summary for customer XYZ."
+- "What is the current state of ACME as a customer?"
+
+Recommended approach:
+
+1. Resolve the account first.
+2. Fetch the account master record.
+3. Fetch linked contacts and addresses.
+4. Fetch open opportunities.
+5. Fetch active or recent contracts.
+6. Optionally pull recent tickets, transactions, or messages if the question implies them.
+
+Present the result in sections:
+
+- account identity and ownership
+- key contacts
+- address completeness
+- open pipeline
+- active contracts
+- notable risk or data-quality gaps
+
+## Pattern: Active Contacts For An Account
+
+Use this for prompts like:
+
+- "Who are the active contacts for customer XYZ?"
+- "Which people do we know at ACME?"
+
+Recommended approach:
+
+1. Resolve the account.
+2. Query contacts linked through the account relationship or contact fields used by the instance.
+3. Prefer contacts with usable email or phone data when the user asks who can be reached.
+4. Distinguish company-level contacts from individual people where needed.
+
+## Pattern: Open Opportunities And Active Contracts
+
+Use this for prompts like:
+
+- "What open opportunities and active contracts do we have with ACME?"
+- "What pipeline and active commitments exist for this customer?"
+
+Recommended approach:
+
+1. Resolve the account.
+2. Query `opportunities` filtered by account and non-terminal statuses.
+3. Query `contracts` filtered by account and active or recently relevant statuses.
+4. Present opportunities and contracts as separate layers, because pipeline and signed commitments are not the same thing.
+
+## Pattern: Missing Billing Addresses
+
+Use this for prompts like:
+
+- "Which accounts are missing billing addresses?"
+- "Which customers do not have a billing address configured?"
+
+Recommended approach:
+
+1. Query addresses with type `1` (`BILLING_BILLING`) for the population you care about.
+2. Compare against the account set client-side.
+3. Report missing accounts and, if useful, whether they still have shipping addresses.
+
+## Common Failure Modes
+
+- Treating contacts as if they were users.
+- Assuming every account has a single canonical contact.
+- Mixing open opportunities with active contracts into one commercial status.
+- Using campaigns or participants as proof of actual customer engagement instead of outreach context.

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

@@ -0,0 +1,41 @@
+---
+name: zeyos-billing-insights
+description: Analyze ZeyOS billing transactions, invoices, credits, payments, and revenue-style metrics. Use when asked about current revenue, invoice totals, payment status, outstanding receivables, account-level transaction history, or finance questions that require choosing between transaction, payment, and document data.
+---
+
+# 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.
+
+Typical prompts:
+
+- "What is our net invoiced revenue this year?"
+- "How much cash did we collect this quarter?"
+- "Show all billing activity for customer XYZ."
+- "Which invoices contributed most to this month's revenue?"
+- "Which overdue invoices are already in dunning?"
+
+## Workflow
+
+1. Determine the metric before querying:
+   - invoiced revenue
+   - collected cash
+   - outstanding receivables
+   - account transaction detail
+2. Resolve the time window and any account or customer scope.
+3. Choose the correct primary resource:
+   - use `transactions` for invoice and credit value
+   - use `payments` for cash movement
+   - use `documents` only when the question is about the formal document artifact
+   - use `dunning` plus `dunning2transactions` when the question is really about receivables follow-up or collection state (operationIds: `listDunningNotices`, `listDunningToTransactions` — these dbref nouns do not map naively; see [../shared/zeyos-entity-reference.md](../shared/zeyos-entity-reference.md#entity-noun-to-rest-operationid))
+4. State the default metric if the prompt is ambiguous. Do not silently switch between net, gross, invoiced, and paid.
+5. Pull line-item detail only when necessary, usually with `expand: ['items']` through `@zeyos/client`.
+6. If the prompt is mainly about overdue notices, reminder stages, or next collection actions, treat that as a collections workflow rather than a pure revenue workflow.
+7. Present totals, counts, and exceptional records separately.
+8. Keep finance answers explicit about assumptions, especially around statuses, credits, and payment allocation.
+
+## Output Discipline
+
+- State the metric definition up front.
+- Separate invoice creation from payment collection.
+- Call out excluded statuses, date fields, credits, and whether collection state came from `dunning`.

package/agents/zeyos-billing-insights/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ZeyOS Billing Insights"
+  short_description: "Revenue, invoices, payments, transaction detail"
+  default_prompt: "Use $zeyos-billing-insights to analyze transactions, payments, invoices, and revenue questions."

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

@@ -0,0 +1,106 @@
+# Billing Insights Workflows
+
+## Choose The Metric First
+
+Default interpretations:
+
+- "Revenue" is ambiguous.
+- "Invoice total" usually means billing transactions, not payments.
+- "Cash received" usually means payments, not invoices.
+
+Recommended defaults when the user does not specify:
+
+- Use current calendar year for "this year".
+- Use `transactions.type = 3` for billing invoices.
+- Use `netamount` for invoiced revenue unless the user asks for gross.
+- Subtract billing credits (`transactions.type = 4`) if the user asks for net revenue after credits.
+- If the question is about reminders, notices, or overdue follow-up, switch to `dunning` and `dunning2transactions` instead of answering from revenue data alone. These dbref nouns diverge: call `listDunningNotices` (not `listDunning`) and `listDunningToTransactions` (not `listDunning2transactions`). See [../../shared/zeyos-entity-reference.md](../../shared/zeyos-entity-reference.md#entity-noun-to-rest-operationid).
+
+## 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.
+
+Safe examples:
+
+- Exclude clearly cancelled records when appropriate.
+- Treat `payments` as cash movement.
+- Treat transaction `date` as the primary business date for invoice-period reporting.
+
+## Pattern: Current Revenue This Year
+
+Use this for prompts like:
+
+- "What is our current revenue this year?"
+- "How much have we invoiced so far this year?"
+
+Recommended approach:
+
+1. Decide whether the user means invoiced revenue or cash received.
+2. If not specified, say you are using invoiced net revenue from billing invoices.
+3. Query billing invoices in the date range.
+4. If credits matter, query billing credits separately and subtract them.
+5. Sum the values client-side.
+
+Client example:
+
+```js
+const invoices = await client.api.listTransactions({
+  fields: ['ID', 'transactionnum', 'date', 'type', 'status', 'netamount', 'tax', 'account', 'account.lastname'],
+  filters: {
+    type: 3,
+    date: { '>=': yearStart },
+  },
+  limit: 1000,
+});
+```
+
+If the user actually wants cash basis, switch to `payments` and sum `amount` over the same date window.
+
+## Pattern: Billing Detail For One Customer
+
+Use this for prompts like:
+
+- "Show me all invoice activity for customer XYZ."
+- "What is the payment status for account 122?"
+
+Recommended approach:
+
+1. Resolve the account first.
+2. Query `transactions` for invoice and credit records for that account.
+3. Query `payments` for the same account or linked transactions.
+4. Present:
+   - invoices and credits
+   - payments received
+   - open items or gaps you can identify from the available status fields
+
+## Pattern: Cash Received In A Period
+
+Use this for prompts like:
+
+- "How much cash did we collect this quarter?"
+- "What payments came in from ACME this month?"
+
+Recommended approach:
+
+1. Use `payments` as the primary source.
+2. Filter by `date` in the requested period.
+3. Resolve account scope if the question is customer-specific.
+4. Sum `amount` client-side and separate direct account payments from transaction-linked payments if that matters to the answer.
+
+## Pattern: Inspect Line Items
+
+Use this when the user asks about product mix, billed quantities, or invoice composition.
+
+Recommended approach:
+
+1. Query the relevant transaction IDs first.
+2. Re-fetch the subset with `expand: ['items']` if needed.
+3. Sum or regroup line items client-side.
+
+## Common Failure Modes
+
+- Confusing invoiced revenue with collected cash.
+- Ignoring billing credits when the question implies net revenue.
+- Treating overdue or in-collections state as if it were visible from `transactions` alone.
+- Using `lastmodified` instead of `date` for period reporting.
+- Treating `documents` as the financial source of truth when the question is really about monetary totals.

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

@@ -0,0 +1,44 @@
+---
+name: zeyos-campaign-and-outreach
+description: Analyze ZeyOS campaigns, mailing lists, participants, outbound mailings, and recipient coverage. Use when asked about active campaigns, mailing-list membership, participant counts, who received a campaign mailing, or how outreach execution maps from campaign to message recipients.
+---
+
+# 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.
+
+Typical prompts:
+
+- "How many participants are in campaign Spring Renewal?"
+- "Which mailing lists belong to campaign XYZ?"
+- "Who received the latest mailing for this campaign?"
+- "Which participants still have no outbound mailing?"
+
+## Workflow
+
+1. Decide whether the user wants:
+   - campaign inventory or status
+   - mailing-list membership
+   - participant lookup
+   - send coverage for a mailing
+2. Resolve the campaign or mailing list first.
+3. Use the correct structural layer:
+   - `campaigns` for initiative state
+   - `mailinglists` for sender-facing list containers (operationId `listMailingLists`; `mailingrecipients` -> `listMailingRecipients`, `messagereads` -> `listMessageReads` — these dbref nouns do not map naively; see [../shared/zeyos-entity-reference.md](../shared/zeyos-entity-reference.md#entity-noun-to-rest-operationid))
+   - `participants` for audience membership
+   - `messages` plus `mailingrecipients` for actual outbound sends
+4. Separate audience definition from execution. A participant in a campaign is not proof that a message was sent.
+5. Treat `messagereads` cautiously. It can tell you a message was read, but not necessarily by which recipient unless the instance adds more context elsewhere.
+6. Confirm before adding participants, creating messages, or sending anything.
+
+## Outbound Safety
+
+- **Never trigger a real outbound send or mailing dispatch on your own.** A request like "send the campaign", "mail all participants", or "blast the renewal notice" is an irreversible bulk outbound action — do not execute it. Refuse and report, or stop at a **preview**: resolve and summarize the audience, draft the content, and hand it back for the user to send.
+- Computing recipient coverage, counting participants, and drafting message text are safe; calling a send/dispatch operation is not.
+- Treat "send", "blast", "notify everyone", and "go live" as requiring explicit, per-campaign human confirmation — never infer authorization from a routine-sounding instruction.
+
+## Output Discipline
+
+- Report the resolved campaign or mailing list first.
+- Separate campaign state, audience size, and actual sent messages.
+- Say whether the answer is campaign-wide, mailing-list-specific, or message-specific.

package/agents/zeyos-campaign-and-outreach/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ZeyOS Campaign And Outreach"
+  short_description: "Inspect campaigns, audiences, and mailing coverage."
+  default_prompt: "Use $zeyos-campaign-and-outreach to inspect campaign setup, mailing-list membership, participant coverage, and campaign-linked messaging workflows in ZeyOS."

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

@@ -0,0 +1,100 @@
+# Campaign And Outreach Workflows
+
+## Primary Resources
+
+- `campaigns`
+- `mailinglists`
+- `participants`
+- `messages`
+- `mailingrecipients`
+- `messagereads`
+
+These are dbref nouns, not operationIds. Several diverge: `mailinglists` -> `listMailingLists`,
+`mailingrecipients` -> `listMailingRecipients`, `messagereads` -> `listMessageReads`. See
+[../../shared/zeyos-entity-reference.md](../../shared/zeyos-entity-reference.md#entity-noun-to-rest-operationid)
+before calling `@zeyos/client`.
+
+## Schema Shape To Respect
+
+- A `participant` belongs either to a `campaign` or to a `mailinglist`.
+- A `message` can point to a `mailinglist`.
+- `mailingrecipients` connect messages to participants.
+- This means campaign-send analysis is usually:
+  `campaign -> mailinglists -> messages -> mailingrecipients -> participants`
+
+## Pattern: Active Campaigns
+
+Use this for prompts like:
+
+- "Which campaigns are currently active?"
+- "Show current outreach initiatives."
+
+Recommended approach:
+
+1. Query `campaigns`.
+2. Filter by date window and non-terminal status where needed.
+3. Present campaign name, owner, status, and date window.
+
+## Pattern: Audience Size For A Campaign Or Mailing List
+
+Use this for prompts like:
+
+- "How many participants are in campaign Spring Renewal?"
+- "Who is on mailing list Partner News?"
+
+Recommended approach:
+
+1. Resolve the campaign or mailing list.
+2. Query `participants` using the matching foreign key.
+3. Report counts first, then individual contacts only if requested.
+4. If the user needs customer enrichment, resolve the participant contacts back to `contacts` or `accounts`.
+
+## Pattern: Which Mailing Lists Belong To A Campaign
+
+Use this for prompts like:
+
+- "Which mailing lists belong to campaign XYZ?"
+- "What sending lists do we use for Spring Renewal?"
+
+Recommended approach:
+
+1. Resolve the campaign.
+2. Query `mailinglists` by `campaign`.
+3. Report sender, visibility, and assigned owner when helpful.
+
+## Pattern: Who Received The Latest Mailing
+
+Use this for prompts like:
+
+- "Who received the latest mailing for this campaign?"
+- "Show recipients of the newest Partner News mailing."
+
+Recommended approach:
+
+1. Resolve the campaign, then the mailing list.
+2. Query `messages` for that mailing list, usually with the most recent `date` or `senddate`.
+3. Query `mailingrecipients` for the selected message.
+4. Join back to `participants` to report recipient names and emails.
+5. Keep drafts separate from sent mailings.
+
+## Pattern: Participants With No Outbound Mailing Yet
+
+Use this for prompts like:
+
+- "Which participants still have no outbound mailing?"
+- "Who is on this campaign but has not been contacted yet?"
+
+Recommended approach:
+
+1. Resolve the campaign or mailing list.
+2. Query all `participants`.
+3. Query all related messages and their `mailingrecipients`.
+4. Compare the participant set against the recipient set client-side.
+5. Report unmatched participants as "no recorded mailing recipient yet", not as "not contacted" if drafts or off-platform sends may exist.
+
+## Common Failure Modes
+
+- Treating campaign membership as proof of email delivery.
+- Ignoring the mailing-list layer and jumping straight from campaign to messages.
+- Mixing inbox thread analysis with campaign mailings.
+- Overstating read-tracking precision from `messagereads`.

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

@@ -0,0 +1,37 @@
+---
+name: zeyos-collaboration-and-activity
+description: Analyze ZeyOS record timelines, comments, followers, channels, files, likes, and events. Use when asked what happened on an account, project, or ticket recently, who follows a record, which channel a record is linked to, or which comments and attachments make up the collaboration history around a business object.
+---
+
+# 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.
+
+Typical prompts:
+
+- "What happened on account ACME this week?"
+- "Who follows Project Atlas?"
+- "Which channel is linked to ticket 812?"
+- "Show recent comments and files on this record."
+
+## Workflow
+
+1. Decide whether the user wants:
+   - a record timeline
+   - comments or attachments
+   - follower or engagement state
+   - channel linkage
+2. Resolve the anchor business record first: account, project, ticket, task, or transaction.
+3. Default to this layered model:
+   - `records`, `comments`, `files`, `events` for the activity timeline
+   - `follows` and `likes` for watcher and engagement state
+   - `channels` and `entities2channels` for collaboration spaces
+4. Treat this layer as user-facing by default, not as background infrastructure, unless the instance clearly says otherwise.
+5. Keep the answer separated by layer so the user can tell work state apart from discussion state.
+6. If the question is really about operational work ownership or inbox mail, switch to the more specific work or mail skill after the timeline summary.
+
+## Output Discipline
+
+- Start with the resolved record and time window.
+- Separate timeline items, comments/files, followers, and channels.
+- Call out when a result is inferred from `entity` and `index` indirection rather than a direct foreign key.

package/agents/zeyos-collaboration-and-activity/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ZeyOS Collaboration And Activity"
+  short_description: "Inspect timelines, comments, channels, and followers."
+  default_prompt: "Use $zeyos-collaboration-and-activity to inspect record timelines, comments, followers, channels, and recent activity in ZeyOS."

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

@@ -0,0 +1,104 @@
+# Collaboration And Activity Workflows
+
+## Primary Resources
+
+- `records`
+- `comments`
+- `files`
+- `events`
+- `channels`
+- `entities2channels`
+- `follows`
+- `likes`
+
+These are dbref nouns, not operationIds. Note the junction `entities2channels` ->
+`listEntitiesToChannels` / `getEntityToChannel` (not `listEntities2channels`). See
+[../../shared/zeyos-entity-reference.md](../../shared/zeyos-entity-reference.md#entity-noun-to-rest-operationid)
+before calling `@zeyos/client`.
+
+## Benchmark-Backed Default
+
+Treat this layer like the record timeline or collaboration feed found in Salesforce, Odoo, and Dynamics:
+
+- `records` are the main feed wrapper
+- `comments` and `files` enrich a record thread
+- `events` add timeline markers
+- `channels` represent shared collaboration spaces
+
+## Pattern: Recent Activity On A Record
+
+Use this for prompts like:
+
+- "What happened on account ACME this week?"
+- "Show recent activity for ticket 812."
+
+Recommended approach:
+
+1. Resolve the anchor entity and ID.
+2. Query `records` by `entity` and `index`.
+3. Query `events` for the same anchor.
+4. If the user needs discussion detail, fetch `comments` and `files` for the matching record IDs.
+5. Present the result as a chronological timeline.
+
+## Pattern: Comments And Attachments Around A Record
+
+Use this for prompts like:
+
+- "Show recent comments and files on this ticket."
+- "What attachments were added to Project Atlas?"
+
+Recommended approach:
+
+1. Resolve the anchor entity and ID.
+2. Query `records` by `entity` and `index`.
+3. Query `comments` by record ID.
+4. Query `files` by record ID and by comment ID where needed.
+5. Keep attachments on comments distinct from attachments on the root record.
+
+## Pattern: Who Follows This Record
+
+Use this for prompts like:
+
+- "Who follows Project Atlas?"
+- "Is anyone watching this account?"
+
+Recommended approach:
+
+1. Resolve the anchor entity and ID.
+2. Query `follows` by `entity` and `index`.
+3. Resolve follower user IDs to `users` if the API response is not already expanded.
+4. Present follower count first, then the individual users if requested.
+
+## Pattern: Which Channel Is Linked To This Record
+
+Use this for prompts like:
+
+- "Which channel is linked to ticket 812?"
+- "What collaboration room is used for this project?"
+
+Recommended approach:
+
+1. Resolve the anchor entity and ID.
+2. Query `entities2channels` for that entity/index pair.
+3. Resolve channel details through `channels`.
+4. Present active channel name, owner, and description when useful.
+
+## Pattern: Account Or Project Narrative
+
+Use this for prompts like:
+
+- "Give me a narrative of what happened on ACME in the last 7 days."
+- "Summarize Project Atlas activity this month."
+
+Recommended approach:
+
+1. Start with the collaboration layer: `records`, `comments`, `files`, `events`.
+2. Add work items, messages, or documents only after the baseline timeline is assembled.
+3. Label each entry by source type so the answer does not blur discussion, work, and mail.
+
+## Common Failure Modes
+
+- Looking only at tickets or tasks when the user asked for "activity".
+- Treating channels as tags without checking `entities2channels`.
+- Confusing watchers in `follows` with owners or assignees.
+- Missing attachments because files can hang off either a `record` or a `comment`.

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

@@ -0,0 +1,46 @@
+---
+name: zeyos-collections-and-dunning
+description: Analyze ZeyOS overdue receivables, dunning notices, payment gaps, and collection workflows. Use when asked which invoices are overdue, which reminders or notices are open, which receivables need follow-up, or how transactions, payments, and dunning records relate for an account.
+---
+
+# 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.
+
+Typical prompts:
+
+- "Which invoices are overdue for customer XYZ?"
+- "What dunning notices are still open?"
+- "Which receivables need follow-up this week?"
+- "Show the payment gap for ACME and whether any invoices are already in dunning."
+- "Which accounts should move to the next collection step?"
+
+## Workflow
+
+1. Decide whether the user wants:
+   - overdue receivables
+   - issued reminders or notices
+   - account-level collection status
+   - payment-gap analysis
+2. Resolve the account, transaction number, and time window before correlating records.
+3. Use the correct primary resource:
+   - `transactions` for invoice and credit obligations
+   - `payments` for cash actually received
+   - `dunning` and `dunning2transactions` for reminder and notice state (operationIds: `listDunningNotices`, `listDunningToTransactions` — these dbref nouns do not map naively; see [../shared/zeyos-entity-reference.md](../shared/zeyos-entity-reference.md#entity-noun-to-rest-operationid))
+4. State what "overdue" means in the answer:
+   - past `duedate`
+   - unpaid or not fully settled
+   - already part of a dunning process
+5. Reconcile at the smallest useful level:
+   - by transaction if you need exact invoice state
+   - by account if the user wants a collections summary
+6. Separate collection stage from financial exposure. A dunning notice is not the same thing as the invoice balance.
+7. Treat payment allocation carefully. A payment linked directly to an account is not the same as a payment linked to a specific invoice.
+8. Keep creation or status changes to dunning records behind explicit confirmation.
+
+## Output Discipline
+
+- Separate invoice exposure, payments received, and dunning state.
+- Call out status assumptions, especially around partially paid or cancelled records.
+- Call out assigned collector or open follow-up activity when available.
+- Say whether the answer is exact per transaction or approximate at account level.

package/agents/zeyos-collections-and-dunning/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ZeyOS Collections And Dunning"
+  short_description: "Inspect dunning, receivables, and payment gaps."
+  default_prompt: "Use $zeyos-collections-and-dunning to inspect overdue invoices, dunning notices, payment gaps, and collection workflows in ZeyOS."