@zeyos/client 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+Notable changes to `@zeyos/client` and `@zeyos/cli`. This project follows
+[Semantic Versioning](https://semver.org/).
+
+## 0.1.0 — Initial release
+
+### `@zeyos/client`
+- Zero-dependency JavaScript client (browser + Node 18+) for the ZeyOS OpenAPI
+  services (`api`, `oauth2`, `legacyAuth`), with methods generated from the specs.
+- Authentication modes: `auto`, `oauth` (bearer + refresh; authorization-code and
+  password grants), `session` (ZEYOSID cookie), and `none`; pluggable token store
+  (`MemoryTokenStore`) and token-set helpers.
+- Schema introspection (`client.schema`): describe resources, fields, enums, and
+  foreign keys; pre-flight `validate()` flags unknown fields, bad enums, the
+  `filter`-vs-`filters` footgun, and required-on-create fields.
+- Resilience: automatic 429 retry honoring `Retry-After`, structured
+  `ZeyosApiError` / `ZeyosValidationError`, CRUD body inference, and
+  `normalizeListResult`.
+
+### `@zeyos/cli` (`zeyos`)
+- CRUD against common resources with `--json`/`--yaml`, field selection and
+  aliasing, dot-notation joins, pagination, and config-driven field display.
+- OAuth login flow, credential cascade (env → `.zeyos` → global config),
+  `describe` / `resources` / `skills` / `whoami`, and safe delete confirmation.
+- Accepts a JSON body passed positionally to `create` / `update`.
+
+### Docs, samples & agent skills
+- Docusaurus documentation (API reference, JavaScript client, CLI, agent
+  workflows, tutorials), three sample apps (Kanban, CRM, Dashboard), and a
+  repo-local agent skill pack under `agents/`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZeyOS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,458 @@
+# ZeyOS Client & CLI
+
+A dependency-light JavaScript client, a command-line tool, and agent guidance for integrating external tools with [ZeyOS](https://www.zeyos.com) — the ERP/CRM platform. Read and write business data (tickets, accounts, tasks, projects, billing, and 50+ more resources) over the ZeyOS OpenAPI surface.
+
+This repository ships two npm packages plus the docs, OpenAPI specs, sample apps, and coding-agent skills:
+
+| Package | What it is | Install |
+|---------|-----------|---------|
+| [`@zeyos/client`](#javascript-client) | Zero-runtime-dependency JS client (browser + Node 18+). Auto-generated methods for the full API. | `npm install @zeyos/client` |
+| [`@zeyos/cli`](#cli) | The `zeyos` command — login, CRUD, schema introspection, agent-skill installer. | `npm install -g @zeyos/cli` |
+
+The authoritative, in-depth documentation lives in [`docs/`](./docs/). This README is the quick tour.
+
+---
+
+## Table of contents
+
+- [Quick start](#quick-start)
+- [Authentication & login](#authentication--login)
+- [CLI](#cli)
+- [JavaScript client](#javascript-client)
+- [Using ZeyOS with a coding agent](#using-zeyos-with-a-coding-agent)
+- [Sample apps](#sample-apps)
+- [Repository layout](#repository-layout)
+- [Documentation](#documentation)
+- [Testing](#testing)
+- [Conventions & gotchas](#conventions--gotchas)
+- [License](#license)
+
+---
+
+## Quick start
+
+### From the command line
+
+```bash
+npm install -g @zeyos/cli
+
+# Authenticate once (opens a browser for the OAuth flow)
+zeyos login --base-url https://cloud.zeyos.com/demo --client-id myapp --secret "$ZEYOS_CLIENT_SECRET"
+
+# Read and write
+zeyos list tickets --filter '{"status":4}' --sort -lastmodified --limit 10
+zeyos count tickets --filter '{"status":4}'
+zeyos get ticket 42 --all
+zeyos create ticket --name "Fix login bug" --status 0 --priority 3
+zeyos update ticket 42 --status 9
+```
+
+### From JavaScript
+
+```js
+import { createZeyosClient, MemoryTokenStore } from '@zeyos/client';
+
+const client = createZeyosClient({
+  platform: 'https://cloud.zeyos.com/demo/',
+  auth: {
+    mode: 'oauth',
+    oauth: {
+      tokenStore: new MemoryTokenStore({ accessToken: process.env.ZEYOS_TOKEN }),
+    },
+  },
+});
+
+const tickets = await client.api.listTickets({
+  fields: ['ID', 'name', 'status', 'priority'],
+  filters: { visibility: 0 },
+  limit: 10,
+});
+```
+
+> **`platform`** is your instance URL: `https://<host>/<instance>/`. For `https://cloud.zeyos.com/demo/`, the instance is `demo`. The string `'live'` is a shorthand preset for `https://cloud.zeyos.com`.
+
+---
+
+## Authentication & login
+
+ZeyOS uses OAuth 2.0. You register an application in your ZeyOS instance to get a **client ID** and **client secret**, then obtain tokens via one of the flows below. The client also supports legacy session-cookie auth.
+
+The client supports four auth **modes**:
+
+| Mode | Behavior |
+|------|----------|
+| `auto` (default) | Bearer token → auto-refresh on expiry/401 → session-cookie fallback |
+| `oauth` | Bearer token only |
+| `session` | Session cookies only |
+| `none` | No authentication (public endpoints) |
+
+### Option 1 — Log in with the CLI
+
+The easiest path. `zeyos login` runs the OAuth authorization-code flow: it prints the URLs, opens your browser, starts a local callback server to capture the redirect, and stores the resulting tokens.
+
+```bash
+zeyos login \
+  --base-url https://cloud.zeyos.com/demo \
+  --client-id myapp \
+  --secret "$ZEYOS_CLIENT_SECRET"
+
+zeyos whoami        # confirm you're authenticated
+```
+
+- Omit any of `--base-url` / `--client-id` / `--secret` to be prompted interactively (the secret prompt is masked).
+- `--global` stores credentials in `~/.config/zeyos/credentials.json` instead of a local `.zeyos/auth.json`.
+- `--manual` skips the browser and prompts you to paste the authorization code (useful over SSH).
+- `--force` re-authenticates even if a token is already stored; `--clean` discards the saved config and re-prompts for everything.
+
+Tokens auto-refresh on use, and the refreshed token is written back to whichever config file you logged into. **Add `.zeyos/auth.json` to your `.gitignore`** — it holds credentials and tokens.
+
+### Option 2 — Programmatic OAuth (authorization-code flow)
+
+For server-side apps that run their own OAuth flow:
+
+```js
+import { createZeyosClient } from '@zeyos/client';
+
+const client = createZeyosClient({
+  platform: 'https://cloud.zeyos.com/demo/',
+  auth: { mode: 'oauth', oauth: { clientId: 'myapp', clientSecret: process.env.ZEYOS_CLIENT_SECRET } },
+});
+
+// 1. Send the user to the authorization URL
+const authUrl = client.oauth2.buildAuthorizationUrl({
+  redirectUri: 'https://myapp.example.com/callback',
+  scope: 'all',
+  state: 'csrf-token-here',
+});
+
+// 2. On your callback route, exchange the code for tokens (stored in the token store)
+const { code } = client.oauth2.parseAuthorizationCallback(req.url);
+await client.oauth2.exchangeAuthorizationCode({
+  code,
+  redirectUri: 'https://myapp.example.com/callback',
+});
+
+// 3. Make authenticated calls — tokens refresh automatically when they expire
+const me = await client.oauth2.getUserInfo();
+```
+
+PKCE is supported by passing `codeChallenge` / `codeChallengeMethod` to `buildAuthorizationUrl` and `codeVerifier` to `exchangeAuthorizationCode`.
+
+### Option 3 — Use an access token directly
+
+If you already have an access token (and optionally a refresh token), seed a `MemoryTokenStore`:
+
+```js
+import { createZeyosClient, MemoryTokenStore } from '@zeyos/client';
+
+const client = createZeyosClient({
+  platform: 'https://cloud.zeyos.com/demo/',
+  auth: {
+    mode: 'oauth',
+    oauth: {
+      clientId: 'myapp',
+      clientSecret: process.env.ZEYOS_CLIENT_SECRET, // required for auto-refresh
+      tokenStore: new MemoryTokenStore({
+        accessToken: process.env.ZEYOS_TOKEN,
+        refreshToken: process.env.ZEYOS_REFRESH_TOKEN,
+      }),
+    },
+  },
+});
+```
+
+Implement your own persistent token store by providing an object with `async get()` and `async set(tokenSet)` — see [server-side integrations](./docs/05-tutorials/03-server-side-integrations.md).
+
+### CLI credential resolution
+
+The CLI resolves credentials in this order (first match wins, field by field):
+
+1. **Environment variables** — `ZEYOS_BASE_URL`, `ZEYOS_INSTANCE`, `ZEYOS_CLIENT_ID`, `ZEYOS_CLIENT_SECRET`, `ZEYOS_TOKEN`, `ZEYOS_REFRESH_TOKEN`
+2. **Local** `.zeyos/auth.json` (found by walking up from the current directory, like `.git`)
+3. **Global** `~/.config/zeyos/credentials.json`
+
+Environment variables make CI and ephemeral agent environments easy:
+
+```bash
+export ZEYOS_BASE_URL=https://cloud.zeyos.com/demo
+export ZEYOS_TOKEN=your-access-token
+zeyos list accounts --limit 5
+```
+
+---
+
+## CLI
+
+Install globally (`npm install -g @zeyos/cli`) or run from this repo with `node cli/bin/zeyos.mjs <command>`.
+
+```
+zeyos <command> [options] [args…]
+```
+
+| Command | What it does | Example |
+|---------|--------------|---------|
+| `login` | OAuth login, stores tokens | `zeyos login --base-url https://cloud.zeyos.com/demo --client-id myapp --secret $S` |
+| `logout` | Revoke session and clear stored tokens | `zeyos logout` |
+| `whoami` | Show the authenticated user | `zeyos whoami --json` |
+| `list <resource>` | List / query records | `zeyos list tickets --filter '{"status":4}' --sort -lastmodified` |
+| `count <resource>` | Count records (true total) | `zeyos count tickets --filter '{"status":4}'` |
+| `get <resource> <id>` | Fetch one record (`show` is an alias) | `zeyos get ticket 42 --all` |
+| `create <resource>` | Create a record | `zeyos create ticket --name "Bug" --status 0 --priority 3` |
+| `update <resource> <id>` | Update a record (`edit` is an alias) | `zeyos update ticket 42 --status 9` |
+| `delete <resource> <id>` | Delete a record (`rm`/`remove` aliases) | `zeyos delete ticket 42 --force` |
+| `resources` | List resource types the CLI exposes | `zeyos resources --json` |
+| `describe <resource>` | Show a resource's fields, types and enums | `zeyos describe ticket` |
+| `skills <list\|show\|install>` | Manage bundled coding-agent skills | `zeyos skills install --target claude` |
+
+**Global options** (work on every command): `--json`, `--yaml`, `--no-color`, `-h/--help`, `-v/--version`.
+
+### Querying
+
+```bash
+# Field selection: comma list, JSON array, or JSON object (with aliasing + dot-notation joins)
+zeyos list tickets --fields ID,name,status --limit 10
+zeyos list accounts --fields '{"Name": "lastname", "City": "contact.city"}'
+
+# Filtering (JSON object) and sorting (prefix - for descending)
+zeyos list tickets --filter '{"status":4,"priority":4}' --sort -lastmodified
+
+# Pagination
+zeyos list tickets --limit 100 --offset 100
+```
+
+> `zeyos list` defaults to `--limit 50` and prints a `Showing X–Y of TOTAL` hint to **stderr** when the result is truncated. To count records, use `zeyos count <resource>` — counting the rows of a `list` only counts the current page.
+
+### Creating & updating
+
+Pass fields as individual flags or as a JSON blob:
+
+```bash
+zeyos create ticket --name "Fix login bug" --status 0 --priority 3
+zeyos create account --lastname "Acme Corp" --currency EUR --type 1
+zeyos update ticket 42 --status 9 --data '{"priority":4}'
+```
+
+`--json` / `--yaml` switch any command to machine-readable output, which is what you want for scripting and agents:
+
+```bash
+zeyos list tickets --filter '{"status":4}' --json | jq '.[].name'
+```
+
+Full CLI reference: [docs/03-cli](./docs/03-cli/01-getting-started.md).
+
+---
+
+## JavaScript client
+
+`createZeyosClient(config)` returns a frozen client. Every API operation is available as a method under `client.api.*` (and `client.oauth2.*`, `client.legacyAuth.*`).
+
+```js
+import {
+  createZeyosClient,
+  MemoryTokenStore,
+  ZeyosApiError,
+  normalizeListResult,
+  normalizeCountResult,
+} from '@zeyos/client';
+
+const client = createZeyosClient({
+  platform: 'https://cloud.zeyos.com/demo/',
+  auth: { mode: 'oauth', oauth: { tokenStore: new MemoryTokenStore({ accessToken: TOKEN }) } },
+});
+```
+
+### CRUD
+
+```js
+// List with field selection, filters, and sorting
+const tickets = await client.api.listTickets({
+  fields: ['ID', 'name', 'status', 'priority', 'lastmodified'],
+  filters: { visibility: 0, status: 4 },
+  sort: ['-lastmodified'],
+  limit: 25,
+});
+
+// Count (count is a boolean flag)
+const open = await client.api.listTickets({ filters: { visibility: 0, status: 4 }, count: true });
+const total = normalizeCountResult(open);
+
+// Fetch one
+const ticket = await client.api.getTicket({ ID: 42 });
+
+// Create (returns the new record)
+const created = await client.api.createTicket({ name: 'Fix login bug', status: 0, priority: 3 });
+
+// Update — flat spread or an explicit body both work
+await client.api.updateTicket({ ID: 42, status: 9 });
+
+// Delete
+await client.api.deleteTicket({ ID: 42 });
+```
+
+### Normalizing responses
+
+List endpoints return either a plain array or a `{ data, count }` wrapper depending on the call. `normalizeListResult` smooths that over:
+
+```js
+const raw = await client.api.listAccounts({ filters: { visibility: 0 } });
+const { data, count } = normalizeListResult(raw); // data is always an array
+```
+
+### Schema introspection
+
+`client.schema` is a read-only view of resources, fields, enums, and operations — handy for building UIs and for agents that need to self-correct:
+
+```js
+client.schema.resources();                 // ['accounts', 'tickets', ...]
+client.schema.fields('tickets');           // ['ID', 'name', 'status', ...]
+client.schema.describe('accounts');        // { name, type, fields }
+client.schema.operationIds();              // every callable operationId
+
+// Opt-in pre-flight validation: catches unknown fields, filter/filters
+// spelling, bad enum values, and required-create fields before the request.
+const result = client.schema.validate('createAccount', { lastname: 'Acme' });
+// → { valid: false, errors: [{ field: 'currency', message: 'Missing required field "currency" …' }] }
+```
+
+Enable validation on every call with `createZeyosClient({ validate: true })`, or per call with `client.api.createAccount(input, { validate: true })` (throws `ZeyosValidationError`).
+
+### Error handling
+
+Non-2xx responses throw a `ZeyosApiError` carrying the full response context:
+
+```js
+try {
+  await client.api.getTicket({ ID: 999999 });
+} catch (err) {
+  if (err instanceof ZeyosApiError) {
+    console.error(err.status, err.statusText); // 404 'Not Found'
+    console.error(err.body);                   // parsed server response
+    console.error(err.operationId, err.url);   // 'getTicket', full URL
+  }
+}
+```
+
+Calling an operation that doesn't exist throws a helpful `ZeyosApiError` with a "did you mean …?" suggestion instead of an opaque `TypeError`.
+
+### Retries & low-level access
+
+- **Retries**: 429/503 are retried automatically with exponential backoff that honors `Retry-After`. Configure with `retry: { maxRetries, retryOn, baseDelayMs, maxDelayMs }`, or disable with `retry: false`.
+- **Escape hatch**: `client.request({ service, operationId, ... })` or `client.request({ service, method, path, ... })` for anything the generated methods don't cover. Pass `{ raw: true }` to get the full `{ status, headers, data }` response.
+
+Full client reference: [docs/02-javascript-client](./docs/02-javascript-client/01-getting-started.md). For battle-tested patterns and gotchas, see the [Practical Guide](./docs/02-javascript-client/04-practical-guide.md).
+
+---
+
+## Using ZeyOS with a coding agent
+
+ZeyOS ships **agent skills** — curated instructions and query playbooks that teach a coding agent (Claude Code, Codex, etc.) how to operate against ZeyOS with the right conventions out of the box. This is the fastest way to let an agent read and write your business data correctly.
+
+### 1. Install the skills into your project
+
+```bash
+zeyos skills list                              # see what's available
+zeyos skills install --target claude           # copies skills into .claude/skills/
+zeyos skills install zeyos-work-management      # or install just one
+```
+
+`--target claude` writes to `.claude/skills/`, `--target codex` writes to `.codex/skills/`; with no `--target`, it auto-detects an existing `.claude`/`.codex` directory (defaulting to Claude). Shared reference docs are installed alongside so the skills' cross-links resolve. Point your agent at the install directory.
+
+Bundled skills:
+
+| Skill | Focus |
+|-------|-------|
+| `zeyos-work-management` | Tickets, tasks, projects, action steps, assignees, workload |
+| `zeyos-account-intelligence` | Accounts, contacts, addresses, opportunities |
+| `zeyos-billing-insights` | Transactions, invoices, credits, payments, revenue |
+| `zeyos-collections-and-dunning` | Overdue receivables, dunning notices, collection workflows |
+| `zeyos-commerce-and-inventory` | Items, pricing, price lists, stock, suppliers |
+| `zeyos-campaign-and-outreach` | Campaigns, mailing lists, outbound mailings |
+| `zeyos-collaboration-and-activity` | Timelines, comments, followers, channels, files, events |
+| `zeyos-mail-operations` | Querying, summarizing, and drafting email/message records |
+| `zeyos-notes-and-sops` | Notes, SOPs, documents, file-backed knowledge |
+| `zeyos-platform-and-schema` | Platform/admin entities, schema, custom fields |
+
+### 2. Give the agent the CLI as its tool
+
+For most agent workflows, the CLI with `--json` is the right interface: stable machine-readable output, built-in auth, and a safe delete confirmation. The agent runs `zeyos` commands and pipes JSON through `jq` or parses it directly.
+
+```bash
+zeyos describe ticket --json          # discover fields & enums
+zeyos list tickets --filter '{"status":4}' --json
+zeyos count accounts --filter '{"type":1}'
+```
+
+When a task needs a resource or request shape the CLI doesn't expose, the agent escalates to `@zeyos/client`, which covers the full generated API surface.
+
+See [Agent Workflows](./docs/04-agent-workflows/00-coding-agents.md): [quickstart](./docs/04-agent-workflows/01-agent-quickstart.md), [recipes](./docs/04-agent-workflows/02-agent-recipes.md), and [CLI coverage & escalation](./docs/04-agent-workflows/03-cli-coverage-and-escalation.md).
+
+---
+
+## Sample apps
+
+Three runnable, dependency-free browser demos live in [`samples/`](./samples/):
+
+- [**Kanban**](./docs/04-sample-apps/01-kanban.md) — drag-and-drop ticket board (status updates, detail view).
+- [**CRM**](./docs/04-sample-apps/02-crm.md) — contact list with dot-notation joins, full-text search, sortable columns, pagination, inline editing.
+- [**Dashboard**](./docs/04-sample-apps/03-dashboard.md) — KPI cards and charts built from parallel `count` queries.
+
+Each can be served as static files from the repository root; see the linked docs for run and configuration instructions.
+
+---
+
+## Repository layout
+
+- [`src/`](./src/) — the `@zeyos/client` JavaScript client (`src/runtime/` is hand-written; `src/generated/` is generated from the OpenAPI specs).
+- [`cli/`](./cli/) — the `@zeyos/cli` command-line tool.
+- [`docs/`](./docs/) — the authoritative documentation (Docusaurus).
+- [`agents/`](./agents/) — repo-local ZeyOS agent skills and query playbooks.
+- [`openapi/`](./openapi/) — the OpenAPI specifications and DB schema reference.
+- [`samples/`](./samples/) — the sample browser applications.
+- [`scripts/`](./scripts/) — client generation (`generate-client.mjs`) and the test runner.
+
+---
+
+## Documentation
+
+| Section | Covers | Entry point |
+|---------|--------|-------------|
+| **API Reference** | Query language, OAuth2, every resource endpoint, field schema | [docs/01-api-reference](./docs/01-api-reference/01-data-retrieval.md) |
+| **JavaScript Client** | Install, auth modes, CRUD, filtering, schema, retries, errors, patterns | [docs/02-javascript-client](./docs/02-javascript-client/01-getting-started.md) |
+| **CLI** | Install, login, all commands, config & field display | [docs/03-cli](./docs/03-cli/01-getting-started.md) |
+| **Agent Workflows** | CLI-first agent orientation, JSON recipes, escalation | [docs/04-agent-workflows](./docs/04-agent-workflows/00-coding-agents.md) |
+| **Sample Apps** | Kanban, CRM, Dashboard walkthroughs | [docs/04-sample-apps](./docs/04-sample-apps/01-kanban.md) |
+| **Tutorials** | Architecture guide, build-your-own frontend, server-side integration | [docs/05-tutorials](./docs/05-tutorials/00-application-developers.md) |
+| **Agent Skills** | What the bundled skills do and how they're organized | [agents/README.md](./agents/README.md) |
+
+---
+
+## Testing
+
+```bash
+npm test                       # offline unit + schema tests (mocked fetch)
+npm test -- --live             # adds a live OAuth smoke test (needs config.test.json)
+npm run test:cli-integration   # live CLI CRUD lifecycle (requires `zeyos login`)
+npm run test:agent-protocol    # agent-driven live protocol; --dry-run to verify wiring first
+```
+
+The CLI has its own offline suite: `node --test cli/test/offline.mjs`.
+
+The **agent test protocol** drives a coding agent against a live instance and uses a model-rotation rule to separate real client defects from model flakiness. See [`test/agent-protocol/PROTOCOL.md`](./test/agent-protocol/PROTOCOL.md).
+
+---
+
+## Conventions & gotchas
+
+A few platform facts that save debugging time (full list in the [Practical Guide](./docs/02-javascript-client/04-practical-guide.md)):
+
+- **Use `filters` (plural)**, not `filter`, in client/CLI code. `filters` also matches GIN-indexed foreign-key fields (`account`, `project`, `ticket`); `filter` silently ignores them.
+- **Always include `visibility: 0`** in filters unless you want archived (`1`) or deleted (`2`) records.
+- **Dates are Unix timestamps in seconds**, not milliseconds (`new Date(value * 1000)`).
+- **`createAccount` requires `currency`** (e.g. `"EUR"`) — it's `NOT NULL` with no default and otherwise fails with an opaque HTTP 500. Accounts use `lastname`/`firstname` (there is no `name` field) and `type` (not `accounttype`).
+- **`operationId`s are CamelCase compounds** that don't always match DB table names (e.g. `dunning` → `listDunningNotices`). Use `client.schema.operationIds()` or `zeyos resources` to discover them.
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/agents/README.md

@@ -0,0 +1,66 @@
+# ZeyOS Agent Skills
+
+This folder contains a repo-local skill pack for coding agents that use ZeyOS as a business operating system. The focus is not generic chat behavior. The focus is repeatable business queries and actions that depend on the ZeyOS entity model, its query rules, and safe escalation from the CLI to the JavaScript client.
+
+The source-backed model reference lives in [`shared/zeyos-entity-reference.md`](./shared/zeyos-entity-reference.md) and is derived from [`openapi/dbref.json`](../openapi/dbref.json) and [`openapi/api.json`](../openapi/api.json).
+Cross-platform modeling guidance lives in [`shared/business-app-benchmarks.md`](./shared/business-app-benchmarks.md).
+
+## Structure
+
+- `shared/` contains cross-domain query rules and entity relationships.
+- `zeyos-work-management/` handles tasks, projects, tickets, and assignee workload questions.
+- `zeyos-mail-operations/` handles message lookup, email summaries, threads, and safe draft workflows.
+- `zeyos-billing-insights/` handles transactions, payments, invoices, credits, and revenue questions.
+- `zeyos-notes-and-sops/` handles notes, SOP discovery, documents, and file-backed knowledge lookup.
+- `zeyos-account-intelligence/` handles customer 360 questions across accounts, contacts, addresses, opportunities, and contracts.
+- `zeyos-commerce-and-inventory/` handles catalog, pricing, stock, supplier, and price-list questions.
+- `zeyos-collections-and-dunning/` handles overdue receivables, reminders, notices, and payment-gap analysis.
+- `zeyos-campaign-and-outreach/` handles campaigns, mailing lists, participants, mailing activity, and recipient coverage.
+- `zeyos-collaboration-and-activity/` handles record timelines, comments, followers, channels, files, and recent-activity reconstruction.
+- `zeyos-platform-and-schema/` handles applications, services, custom fields, objects, groups, and permissions.
+
+## Shared Design Rules
+
+- Resolve business names to IDs before answering cross-record questions.
+- Start with the smallest primary query, then follow relationships with a second query when needed.
+- Use `visibility: 0` for resources that expose a `visibility` field.
+- Check `zeyos resources --json` before assuming CLI coverage. If a required resource is missing from the curated CLI registry, switch to `@zeyos/client`.
+- Treat `filter` vs `filters` as a source inconsistency; follow the interface-native convention and verify raw REST behavior against the target instance.
+- Treat list responses and count-enabled responses defensively.
+- Treat "worked on", "revenue", and "latest SOP" as potentially ambiguous business concepts and state the chosen interpretation.
+- Keep destructive actions and outbound email sends behind explicit confirmation.
+
+## Skill Catalog
+
+| Skill | Best for | Example prompts |
+|------|----------|-----------------|
+| `zeyos-work-management` | Operational work queues, user workload, ticket-task-project tracing, follow-up work creation | "On which projects did Max Power work in the last two weeks?"; "Show overdue high-priority tickets for account ACME."; "What open tasks are blocking Project Atlas?" |
+| `zeyos-mail-operations` | Customer mail summaries, thread reconstruction, draft preparation, mailbox analysis | "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." |
+| `zeyos-billing-insights` | Revenue, invoices, credits, payment tracking, transaction-level finance questions | "What is our net invoiced revenue this year?"; "How much cash did we collect this quarter?"; "Show all billing activity for customer XYZ." |
+| `zeyos-notes-and-sops` | SOP retrieval, note summaries, final-document lookup, attachment discovery | "Find the current escalation SOP for billing disputes."; "Summarize our notes on failed invoice syncs."; "Which finalized onboarding SOP changed last month?" |
+| `zeyos-account-intelligence` | Customer 360, contacts, contracts, opportunities, CRM hygiene | "Give me a 360 summary for customer XYZ."; "What open opportunities and active contracts do we have with ACME?"; "Which accounts are missing billing addresses?" |
+| `zeyos-commerce-and-inventory` | Customer-specific pricing, stock, suppliers, catalog structure | "What price does customer XYZ get for item ABC?"; "Which items are low on stock?"; "Who are the suppliers for item ABC?" |
+| `zeyos-collections-and-dunning` | Overdue invoices, dunning notices, payment gaps, receivables follow-up | "Which invoices are overdue for customer XYZ?"; "What dunning notices are still open?"; "Which receivables need follow-up this week?" |
+| `zeyos-campaign-and-outreach` | Campaign setup, mailing-list membership, participant coverage, outreach execution | "How many participants are in campaign Spring Renewal?"; "Which mailing lists belong to campaign XYZ?"; "Who received the latest mailing?" |
+| `zeyos-collaboration-and-activity` | Activity timelines, comments, channels, followers, attachments, recent changes | "What happened on account ACME this week?"; "Who follows Project Atlas?"; "Which channel is linked to ticket 812?" |
+| `zeyos-platform-and-schema` | App inventory, service hooks, custom schema, group permissions | "Which custom fields exist on tickets?"; "Which services run after ticket modification?"; "Which groups grant access to application XYZ?" |
+
+## Interface Boundary
+
+The CLI covers common operational resources such as accounts, contacts, documents, items, projects, tasks, tickets, users, and groups. Skills that depend on platform, pricing, campaign-recipient, permission, channel, follower, or other specialist resources should start with `zeyos resources --json`; if the resource is absent, use `@zeyos/client` and the generated operation names from the API reference.
+
+## Recommended Loading Order
+
+1. Read `shared/zeyos-query-patterns.md`.
+2. Read `shared/business-app-benchmarks.md` when the semantics are unclear.
+3. Read `shared/zeyos-entity-reference.md` when the entity itself is unclear.
+4. Read `shared/zeyos-entity-map.md` if the question crosses domains.
+5. Load the matching skill folder and its `references/workflows.md`.
+
+## Good Next Skills
+
+Potential next additions that would fit this folder well are:
+
+- calendar and appointment coordination
+- document generation and approval flows
+- purchasing and supplier performance analysis