@zeyos/client 0.1.0

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

@@ -0,0 +1,97 @@
+# Platform And Schema Workflows
+
+## Primary Resources
+
+- `applications`
+- `applicationassets`
+- `resources`
+- `services`
+- `weblets`
+- `forks`
+- `groups`
+- `groups2users`
+- `permissions`
+- `customfields`
+- `objects`
+
+These are dbref nouns, not operationIds. Several diverge: `applicationassets` ->
+`listApplicationAssets`, `groups2users` -> `listGroupsToUsers` / `getGroupToUser`, `customfields` ->
+`listCustomFields`. Note that `applications`, `applicationassets`, `customfields`, `forks`, `groups`,
+`groups2users`, `permissions`, `resources`, `services`, and `weblets` are **read-only** (only
+`list*`, `get*`, `exists*` — no create/update/delete). See
+[../../shared/zeyos-entity-reference.md](../../shared/zeyos-entity-reference.md#entity-noun-to-rest-operationid)
+before calling `@zeyos/client`.
+
+## Pattern: Custom Fields For An Entity
+
+Use this for prompts like:
+
+- "Which custom fields exist on tickets?"
+- "What dynamic fields do we have on accounts?"
+
+Recommended approach:
+
+1. Query `customfields`.
+2. Filter by target entity where the field model exposes it.
+3. Report identifier, data type, activity state, and indexing implications if relevant.
+4. If the user needs values rather than definitions, switch to the extdata views or the resource itself with `extdata`.
+
+## Pattern: Service Hooks For An Entity
+
+Use this for prompts like:
+
+- "Which services run after ticket modification?"
+- "What timing services are configured?"
+
+Recommended approach:
+
+1. Query `services`.
+2. Distinguish timing services from entity lifecycle hooks using `services.type`.
+3. For lifecycle hooks, filter by `entity`.
+4. Report application ownership, schedule or interval, and activity state.
+
+## Pattern: Application Surface Inventory
+
+Use this for prompts like:
+
+- "Which weblets belong to application XYZ?"
+- "Show me the active resources and services for this app."
+
+Recommended approach:
+
+1. Resolve the application.
+2. Query `resources`, `services`, and `weblets` separately.
+3. Report identifiers, activity state, and UI/service type.
+
+## Pattern: Group Access And Membership
+
+Use this for prompts like:
+
+- "Which groups grant access to application XYZ?"
+- "Which users belong to the billing admin group?"
+
+Recommended approach:
+
+1. Resolve the group or application.
+2. Query `permissions` for app-, fork-, or identifier-based grants.
+3. Query `groups2users` for membership.
+4. Report whether the group membership or permission is writable where that matters.
+
+## Pattern: Custom Objects
+
+Use this for prompts like:
+
+- "What custom objects exist for entity quote_review?"
+- "Show recent objects for this custom entity."
+
+Recommended approach:
+
+1. Query `objects` by `entity`.
+2. Pull `data` only when the answer needs JSON payload content.
+3. Treat custom objects as instance-defined domain data and avoid guessing semantics from the entity name alone.
+
+## Common Failure Modes
+
+- Assuming custom fields and custom objects are the same thing.
+- Confusing app resources with weblets or services.
+- Treating collaboration entities such as `records` or `channels` as if they were only low-level infrastructure when the user is actually asking for activity history.

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

@@ -0,0 +1,45 @@
+---
+name: zeyos-work-management
+description: Manage ZeyOS tickets, tasks, projects, action steps, assignees, and workload questions. Use when asked to summarize work queues, trace which projects or tickets a user worked on, create follow-up work, inspect active or overdue work items, or answer operational questions that span tickets, tasks, projects, accounts, transactions, and users.
+---
+
+# ZeyOS Work Management
+
+Read [../shared/zeyos-query-patterns.md](../shared/zeyos-query-patterns.md) first. Read [../shared/zeyos-entity-map.md](../shared/zeyos-entity-map.md) when the request crosses users, accounts, tickets, tasks, and projects. Read [references/workflows.md](references/workflows.md) for the concrete query patterns.
+
+Typical prompts:
+
+- "On which projects did Max Power work in the last two weeks?"
+- "Show overdue high-priority tickets for customer ACME."
+- "Which open tasks are blocking Project Atlas?"
+- "Which action steps are due this week for ACME?"
+- "Create a follow-up ticket for this billing issue."
+
+## Workflow
+
+1. Resolve user, project, account, ticket, task, and transaction names to IDs before correlating records.
+2. Decide whether the primary record set is `tickets`, `tasks`, `projects`, `actionsteps`, or a mixed workload view.
+3. Start with the narrowest query that can answer the question:
+   - use `tickets` for queue, backlog, priority, and account-linked support work
+   - use `tasks` for actionable delivery work and short-lived assignments
+   - use `actionsteps` for smaller cross-record follow-ups attached to tasks, tickets, accounts, or transactions
+   - use `projects` for top-level initiative state
+4. Follow relationships only after the primary record set is clear.
+5. Treat "worked on" as a proxy unless a stronger activity source exists. Use assignment plus recent timestamps, optionally strengthened by linked action steps, and say so explicitly.
+6. Distinguish direct project assignment from project inference through linked tickets.
+7. When the question is really about account or transaction follow-up, check `actionsteps` before inventing a new task.
+8. For mutations, preview the affected record first and update with an explicit PATCH body.
+9. Escalate from the CLI to `@zeyos/client` if the workflow needs unsupported joins, additional request control, or correlation across multiple list responses.
+
+## Destructive Operations
+
+- **Refuse unscoped bulk deletes.** A request to delete a *category* of work — "delete all completed tickets", "clean up the queue", "close out everything old" — is a bulk destructive operation. Do not perform it: refuse and ask the user to confirm the specific record IDs, even if the matched records look like throwaway/test data.
+- Delete or bulk-modify only records the user has explicitly identified by ID (or that you created yourself in this session), one at a time, after previewing each.
+- "Clean up", "tidy", or "archive the queue" are not authorization to delete — treat them as requests for a *proposed* list the user approves before any deletion.
+- Never pass `--force` or auto-answer a delete confirmation prompt on the user's behalf for records you did not create.
+
+## Output Discipline
+
+- Report the resolved entities and time window first.
+- Separate direct evidence from inferred relationships.
+- Call out missing project links, ambiguous user resolution, incomplete task-ticket chains, or action steps that only prove account-level follow-up rather than project activity.

package/agents/zeyos-work-management/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ZeyOS Work Management"
+  short_description: "Tasks, projects, tickets, workload tracing"
+  default_prompt: "Use $zeyos-work-management to answer questions about tickets, tasks, projects, assignees, and work status."

package/agents/zeyos-work-management/references/workflows.md

@@ -0,0 +1,148 @@
+# Work Management Workflows
+
+## Primary Resources
+
+- `projects`: top-level initiatives
+- `tickets`: support and service work, often linked to accounts or projects
+- `tasks`: actionable units linked to tickets or projects
+- `actionsteps`: smaller follow-up work linked to tasks, tickets, accounts, or transactions; default to these when the user is really asking for a scheduled follow-up rather than a broader deliverable
+- `users`: system identities for assignees
+
+These are dbref nouns, not operationIds. Note `actionsteps` -> `listActionSteps` /
+`getActionStep` / `createActionStep` (compound CamelCase, not `listActionsteps`). See
+[../../shared/zeyos-entity-reference.md](../../shared/zeyos-entity-reference.md#entity-noun-to-rest-operationid)
+before calling `@zeyos/client`.
+
+## Resolve Before Querying
+
+1. Resolve the user or account first.
+2. Resolve the time window second.
+3. Query `tasks`, `tickets`, and `actionsteps` separately if the question asks what work happened.
+4. Dedupe projects only after collecting both direct and inferred project IDs.
+
+## Pattern: Projects A User Worked On In The Last Two Weeks
+
+Use this for prompts like:
+
+- "On which projects did Max Power work in the last two weeks?"
+- "What has Sarah been touching recently?"
+
+Recommended approach:
+
+1. Resolve the user from `users.name` or `users.email`.
+2. Query recent tasks assigned to that user with `lastmodified > cutoff`.
+3. Query recent tickets assigned to that user with `lastmodified > cutoff`.
+4. Optionally query recent `actionsteps` for the same user when you want stronger evidence of follow-up activity.
+5. Collect direct `project` links from tasks and tickets.
+6. For tasks that only link to a ticket, fetch the ticket or include `ticket.project` if available in the selected fields.
+7. For action steps linked to tasks or tickets, infer the project through the linked parent only if the user asked for a broad activity summary.
+8. Dedupe project IDs and present them as:
+   - directly linked through tasks/projects
+   - inferred through linked tickets
+   - indirectly supported by recent action steps
+
+Client example:
+
+```js
+const recentTasks = await client.api.listTasks({
+  fields: ['ID', 'name', 'project', 'project.name', 'ticket', 'ticket.name', 'lastmodified'],
+  filters: {
+    assigneduser: userId,
+    visibility: 0,
+    lastmodified: { '>': cutoff },
+  },
+  limit: 200,
+});
+
+const recentTickets = await client.api.listTickets({
+  fields: ['ID', 'name', 'project', 'project.name', 'lastmodified'],
+  filters: {
+    assigneduser: userId,
+    visibility: 0,
+    lastmodified: { '>': cutoff },
+  },
+  limit: 200,
+});
+```
+
+Important caveat:
+
+- The documented schema does not expose timesheets or effort logs here. "Worked on" is therefore an activity proxy, not proof of time spent.
+
+## Pattern: Review A Ticket Queue
+
+Use `tickets` as the primary record set when the question is about backlog, SLAs, due dates, or support prioritization.
+
+CLI example:
+
+```bash
+zeyos list tickets \
+  --fields ID,ticketnum,name,status,priority,duedate,assigneduser,project,account \
+  --filter '{"visibility":0,"status":4}' \
+  --sort -priority,+duedate \
+  --limit 100 \
+  --json
+```
+
+Follow up with `tasks` only if the answer requires execution detail below the ticket level.
+Follow up with `actionsteps` if the queue management style in this instance uses reminders or next steps below the ticket.
+
+## Pattern: Overdue Work For An Account Or Project
+
+Use this for prompts like:
+
+- "Show overdue high-priority tickets for customer ACME."
+- "Which tasks are overdue on Project Atlas?"
+
+Recommended approach:
+
+1. Resolve the account or project first.
+2. Query the primary work entity with `duedate < now`.
+3. Keep status filters explicit so closed/completed work stays out of the result set.
+4. Present overdue work ordered by priority and due date.
+
+For account-scoped support work, start with `tickets`.
+For project delivery work, query both `tickets` and `tasks` if the project uses both layers.
+For account-scoped or transaction-scoped follow-up work, query `actionsteps` as well.
+
+## Pattern: Open Action Steps For A Customer, Ticket, Or Invoice
+
+Use this for prompts like:
+
+- "Which action steps are due this week for ACME?"
+- "What follow-ups are open on invoice 2025-0191?"
+- "Show me the next steps on ticket 812."
+
+Recommended approach:
+
+1. Resolve the anchor record first: account, ticket, task, or transaction.
+2. Query `actionsteps` as the primary resource.
+3. Filter by the direct foreign key you actually have.
+4. Keep due date and status visible in the result.
+5. If the anchor is a transaction and the user also wants broader work context, then check related tickets or account-level tasks second.
+
+## Pattern: Create Follow-Up Work
+
+For prompts like:
+
+- "Create a task for this ticket."
+- "Open a follow-up ticket for the billing issue."
+
+Recommended approach:
+
+1. Get the source record first.
+2. Preserve the strongest available context:
+   - use `ticket` on a task if the task belongs to a ticket
+   - use `project` if the follow-up is project-wide
+   - use `actionsteps` if the follow-up is small, account-scoped, or transaction-scoped and does not justify a standalone task
+   - keep `visibility: 0`
+3. Confirm the new owner, due date, and priority if they are not explicit.
+4. Use explicit PATCH or create bodies and return the created record ID.
+
+## Common Failure Modes
+
+- The same person may exist as a contact and as a user with different names.
+- A ticket can link to an account or a project, but not both in the documented schema.
+- A task can link to a ticket or a project, but not both in the documented schema.
+- An action step can link to a task, ticket, or account, plus an optional transaction.
+- Project answers become noisy if you do not dedupe project IDs gathered from tasks and tickets.