@zeyos/client 0.1.0

package/agents/shared/business-app-benchmarks.md

@@ -0,0 +1,111 @@
+# Business App Benchmarks For ZeyOS Agents
+
+This file summarizes how established business platforms model activities, timelines, collaboration spaces, and collections workflows. Use it to set better default assumptions for ZeyOS agents.
+
+## Source Set
+
+- [Salesforce Trailhead: Collaborate with Everyone](https://trailhead.salesforce.com/content/learn/modules/chatter_basics/chatter_basics_collaborate)
+- [Salesforce Help: Access Salesforce Records in Slack Channels](https://help.salesforce.com/s/articleView?id=slack.salesforce_record_access_slack.htm&type=5)
+- [Odoo Documentation: Activities](https://www.odoo.com/documentation/19.0/applications/essentials/activities.html)
+- [Odoo Documentation: Channels](https://www.odoo.com/documentation/19.0/applications/productivity/discuss/team_communication.html)
+- [Odoo Documentation: Follow-up on Invoices](https://www.odoo.com/documentation/19.0/applications/finance/accounting/payments/follow_up.html)
+- [SAP Help: Dunning](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/99fb46a79ab241d5984df80fe7a9aa32/4df4cd53d7667514e10000000a174cb4.html)
+- [SAP Help: SAP Collections Management](https://help.sap.com/docs/SAP_ERP/d7d4594de25b40e895b13d63b17437bb/7401d553088f4308e10000000a174cb4.html)
+- [SAP Help: Analysis of Receivables in Connection with SAP Collections Management](https://help.sap.com/doc/saphelp_scm700_ehp02/7.0.2/en-US/c5/63652eb3b34e97ba6f9fefcebf5d36/content.htm)
+- [Workday: Business Process Framework Datasheet](https://forms.workday.com/en-us/reports/business-process-framework-datasheet/form.html)
+- [Workday Everywhere for Slack and Microsoft Teams](https://www.workday.com/en-us/products/workday-everywhere.html)
+- [Microsoft Dynamics 365: Timeline Wall and Activities](https://learn.microsoft.com/en-us/dynamics365/customerengagement/on-premises/basics/activities-activity-feeds?view=op-9-1)
+
+## Stable Cross-Platform Patterns
+
+### 1. Activities Are Smaller Than Tasks Or Projects
+
+- Salesforce lets users turn collaboration posts into tasks.
+- Odoo has scheduled activities directly on records.
+- Dynamics treats activities as record-level work and reminders.
+- Workday routes work as inbox tasks inside business processes.
+
+Implication for ZeyOS:
+
+- Treat `actionsteps` as record-bound activities or follow-ups.
+- Prefer `tasks` for broader delivery work.
+- Prefer `projects` for governed multi-record initiatives.
+
+### 2. Mature Systems Keep A Record Timeline
+
+- Salesforce record pages surface feed tracking, posts, comments, and tasks.
+- Odoo chatter keeps notes, messages, followers, and activities on the record.
+- Dynamics uses a timeline to combine notes, posts, and activities.
+- Workday is less social, but still centers process history and in-context tasks around the record or process step.
+
+Implication for ZeyOS:
+
+- Treat `records`, `comments`, `files`, and `events` as a likely user-facing timeline layer.
+- When the user asks for "what happened recently?", start there before over-querying operational tables.
+
+### 3. Collaboration Spaces And Record Feeds Are Separate
+
+- Salesforce distinguishes record feeds from Slack channels and groups.
+- Odoo distinguishes chatter on a business record from Discuss channels.
+- Dynamics distinguishes the record timeline from broader collaboration tooling.
+
+Implication for ZeyOS:
+
+- Treat `channels` as shared collaboration spaces.
+- Treat `entities2channels` as the bridge between a business record and a collaboration room.
+- Do not collapse channels into tags or categories unless instance evidence supports that.
+
+### 4. Followers Mean Attention, Not Ownership
+
+- Salesforce users follow records to receive updates.
+- Odoo followers receive record updates in chatter.
+- Dynamics and adjacent CRMs use subscriptions or following similarly.
+
+Implication for ZeyOS:
+
+- Treat `follows` as watcher or notification intent.
+- Do not confuse a follower with the assignee, owner, or permission holder.
+
+### 5. Collections Is Stage-Based And Worklist-Driven
+
+- SAP models dunning with procedures, levels, and specialist worklists.
+- SAP Collections Management prioritizes overdue receivables and assigns them to collectors.
+- Odoo follow-up runs can send letters, emails, SMS, or create activities depending on the configured level.
+
+Implication for ZeyOS:
+
+- Separate:
+  - receivable exposure in `transactions`
+  - cash received in `payments`
+  - collection stage in `dunning`
+  - collector next step in `actionsteps` or other operational work
+- Collection answers should report both balance state and follow-up stage.
+
+### 6. Process Systems Favor Explicit Responsibility
+
+- Workday business processes push named approval, review, and action tasks to users.
+- SAP collections assigns worklist items to collection specialists or groups.
+- Odoo activities always carry an assigned user and deadline.
+
+Implication for ZeyOS:
+
+- Favor `assigneduser`, `duedate`, and status when choosing which entity best represents a next action.
+- If the user asks "who should act next?", prefer the entity with explicit assignee and due date over looser discussion artifacts.
+
+## Recommended Default Interpretations For ZeyOS
+
+- `actionsteps`: scheduled activities or follow-ups
+- `tasks`: broader execution work
+- `tickets`: service or issue work
+- `records` + `comments` + `files` + `events`: timeline/feed layer
+- `channels`: collaboration rooms or shared streams
+- `follows`: subscriptions/watchers
+- `dunning`: collection-stage object
+
+## Enhancements This Benchmark Supports
+
+- Add a dedicated collaboration and activity skill for `records`, `comments`, `files`, `channels`, and `follows`.
+- Route "what happened on X?" questions through a timeline workflow instead of only querying tickets and tasks.
+- Prefer `actionsteps` for promised next actions on accounts, invoices, and tickets.
+- Strengthen collections answers with stage, assignee, and next-step language.
+- Treat record feed questions and channel questions as related but distinct workflows.

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

@@ -0,0 +1,142 @@
+# ZeyOS Entity Map
+
+Use this file when a question spans more than one business area.
+
+This is the high-level relationship map. For the source-backed inventory, read [zeyos-entity-reference.md](./zeyos-entity-reference.md), which is derived from [../../openapi/dbref.json](../../openapi/dbref.json) and [../../openapi/api.json](../../openapi/api.json).
+
+The names below are dbref/DB-table nouns used to describe relationships. They are **not** the
+`@zeyos/client` operationIds. Several diverge (e.g. `dunning` -> `listDunningNotices`,
+`dunning2transactions` -> `listDunningToTransactions`, `pricelists2accounts` ->
+`listPriceListsToAccounts`, `mailinglists` -> `listMailingLists`). Before constructing a call, map
+the noun to its operationId via [zeyos-entity-reference.md](./zeyos-entity-reference.md#entity-noun-to-rest-operationid).
+
+## Work Graph
+
+- `projects` are the top-level work containers.
+- `tickets` link to either an `account` or a `project`.
+- `tasks` link to either a `ticket` or a `project`.
+- `actionsteps` are smaller follow-up work items linked to a `task`, `ticket`, or `account`, with an optional `transaction`.
+- `assigneduser` appears on projects, tickets, tasks, transactions, documents, notes, and payments.
+
+Implication:
+
+- To answer project-workload questions, you often need `tasks`, `tickets`, and sometimes `actionsteps`.
+- To infer project activity from tasks, follow `task.project` directly or infer it through `task.ticket -> ticket.project`.
+- Account or transaction follow-up work can live in `actionsteps` even when there is no standalone task.
+
+## Customer Graph
+
+- `accounts` are the main company/customer records.
+- `contacts` are people linked to accounts.
+- `addresses` add typed billing and shipping address records.
+- `opportunities` add pipeline state and expected commercial value.
+- `contracts` add signed or active commercial commitments.
+- `pricelists2accounts` maps account-specific pricing.
+- `users` are system identities and may not match contact names directly.
+
+Implication:
+
+- Human prompts such as "customer XYZ" often resolve through `accounts`.
+- Human prompts such as "Max Power" may require checking both `users` and `contacts`.
+- Customer 360 answers often need multiple follow-up queries rather than one joined query.
+
+## Communication Graph
+
+- `messages` link directly to `ticket`, `opportunity`, `mailinglist`, and `reference`.
+- `messages` do not expose a direct `account` foreign key in the documented schema.
+- `mailingrecipients` link outbound messages to `participants`.
+- Email context often has to be inferred from `sender_email`, `to_email`, or linked tickets/opportunities.
+
+Implication:
+
+- For "recent mails from customer XYZ", resolve customer email addresses first, then search messages.
+- Use `reference`, `messageid`, and `subject` to reconstruct threads.
+- For mailing or campaign questions, go through `mailinglist -> messages -> mailingrecipients -> participants`.
+
+## Outreach Graph
+
+- `campaigns` define outreach initiatives and status windows.
+- `mailinglists` belong to campaigns and define sender-facing communication groups.
+- `participants` belong either to a `campaign` or a `mailinglist`.
+- `messages` can point to a `mailinglist`.
+- `mailingrecipients` connect outbound messages to individual participants.
+
+Implication:
+
+- Audience definition and actual message delivery are different layers.
+- To answer "who received this campaign mailing?", resolve the campaign, then the mailing list, then the messages, then the recipients.
+
+## Finance Graph
+
+- `transactions` are the main billing and procurement records.
+- `payments` link either to a `transaction` or directly to an `account`.
+- `dunning` stores reminder and notice records for overdue receivables.
+- `dunning2transactions` links collection notices back to the covered invoices.
+- `items` appear in product catalogs and transaction line-item JSON.
+- `pricelists`, `prices`, and `pricelists2accounts` shape effective commercial pricing.
+- `documents` can represent invoice-like business documents, but `transactions` are the better source for monetary analysis.
+
+Implication:
+
+- Use `transactions` for invoice value, credits, and billing pipeline questions.
+- Use `payments` for cash movement and settlement questions.
+- Use `dunning` and `dunning2transactions` when the question is about collection stage, notices, or reminder fees.
+- Use `expand: ['items']` or the raw JSON field when line-item analysis matters.
+
+## Commerce Graph
+
+- `items` are the catalog anchor.
+- `prices` belong to items and price lists.
+- `pricelists2accounts` applies price lists to customers.
+- `stocktransactions` move item quantities across `storages`.
+- `suppliers` link items to vendor accounts.
+
+Implication:
+
+- "What price does customer XYZ get?" usually needs account resolution, price-list resolution, then item pricing.
+- "What stock do we have?" is often an aggregation over stock movements, not a single scalar field.
+
+## Platform Graph
+
+- `applications` own app-level assets.
+- `resources`, `services`, and `weblets` describe runtime, automation, and UI surfaces.
+- `groups`, `groups2users`, and `permissions` shape access.
+- `customfields` and `objects` extend the schema.
+
+Implication:
+
+- Builder and admin questions often require platform entities rather than business entities.
+- The schema often reveals structure even when product semantics remain instance-specific.
+
+## Collaboration Graph
+
+- `records` are the generic activity and posting wrapper tied to an `entity` and `index`.
+- `comments` attach to a `record`.
+- `files` can attach to either a `record` or a `comment`.
+- `channels` group records, and `entities2channels` map business records into channels.
+- `follows`, `likes`, and `events` add watchers, reactions, and timeline-style activity.
+
+Implication:
+
+- Questions like "what happened on this project recently?" may require `records`, `comments`, `files`, and `events`, not only tickets and tasks.
+- This layer looks powerful in the schema, but the product importance still needs confirmation per instance.
+
+## Knowledge Graph
+
+- `notes` store plain text and are the easiest source for direct summarization.
+- `documents` store formal file-like artifacts and metadata such as `documentnum`, `filename`, and status.
+- `files` are attachment records linked to a `record` or `comment`.
+
+Implication:
+
+- Prefer `notes` when the user wants readable text now.
+- Prefer `documents` when the user wants the official or final SOP artifact.
+- Prefer `files` only when the question is explicitly about attachments.
+
+## Ambiguity Patterns
+
+- "Worked on" is not the same as logged time. The documented schema shows assignment and modification timestamps, not timesheets.
+- "Revenue" can mean invoiced value, net revenue, gross revenue, or cash received.
+- "Latest SOP" can mean most recently modified, most recently finalized, or the document currently in force.
+
+Always state which interpretation you used.