@zeyos/client 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -3,11 +3,43 @@
 Notable changes to `@zeyos/client` and `@zeyos/cli`. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## 0.4.0
+
+### Open Knowledge Format (OKF)
+- **New OKF bundle** under [`okf/`](okf/): a conformant [Open Knowledge Format v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) description of the ZeyOS data model — one Markdown concept per API-backed entity (schema, foreign keys, enums, indexes, and the real operationIds), plus curated metrics, playbooks, and cross-cutting query concepts. Generated from the OpenAPI/dbref specs into **managed blocks** so structural content stays in sync while curated `# Notes` are preserved across regeneration. Ships in the npm package.
+- **Canonical schema source**: the previously hand-maintained operationId table in `agents/shared/zeyos-entity-reference.md` is now generated from the bundle, so the skill pack and the data model can't drift apart. Skills stay the task-facing layer; OKF is the reference layer.
+- **Freshness**: `npm run generate` regenerates the bundle alongside the client; a `source_snapshot` hash and an auto-appended `okf/log.md` schema-diff track changes when the ZeyOS schema/API is updated, and `npm run okf:check` is a CI drift + conformance gate.
+
+### `@zeyos/client`
+- New OKF exports: `buildOkf()` (synthesize a conformant bundle from the client's schema — pure, browser-safe), `loadOkfBundle(dir)` (read a bundle, Node), `validateOkfBundle`/`validateOkfFiles` (OKF v0.1 conformance), `conceptIdForResource`, and `OKF_VERSION`.
+
+### `@zeyos/cli` (`zeyos`)
+- New `okf` command: `zeyos okf list | show <concept> | check | export [--out] | build [--out]` to browse, print, validate, vendor, or synthesize the OKF bundle.
+
+### Agent skills & tooling
+- The improvement loop gains a `--context skills|okf|both` axis (`run.mjs`/`loop.mjs`) to measure whether OKF-as-context lifts agent accuracy, and a new `okf:refine` loop (`refine-okf.mjs`) that drafts → validates against the schema → judges → applies improvements to a concept's curated notes (never the generated managed block).
+
+## 0.3.0
+
+### `@zeyos/client`
+- **Single-flight token refresh**: when several operations notice an expired access token at once (e.g. `Promise.all([...])`), they now share a single `getToken` refresh instead of each firing its own — avoiding redundant calls and the hard failure that refresh-token rotation would otherwise cause.
+- **Request timeout**: a new `timeoutMs` option (client-wide via `config.timeoutMs`, or per request) bounds each attempt via an `AbortController` composed with any caller `signal`. Timeouts reject with `isTimeout === true` / `code === 'ETIMEDOUT'` and are distinct from a caller abort (which always propagates and is never retried).
+- **Network-error retries (reads only)**: dropped connections / timeouts are now retried within the retry budget for safe read operations (`GET`/`HEAD` + side-effect-free `list`/`count`/`search`); writes are never auto-retried. Override per request or client with `retryOnNetworkError`.
+- **Auto-pagination**: `client.paginate(operationId, input, opts)` async-iterates every matching record by paging on `offset` (page size clamped to the 10000 server max), and `client.collect(...)` is the eager array form — removing the manual offset bookkeeping the list caps otherwise force.
+- **Richer error messages**: `ZeyosApiError.message` now folds in a short snippet of the server error body (e.g. `… failed with HTTP 400: unknown filter field: bogus`); the full body remains on `error.body`.
+
+### `@zeyos/cli` (`zeyos`)
+- **Named credential profiles**: store multiple ZeyOS instances and switch between them. `zeyos profile list | current | use <name> [--local] | add <name> [--base-url/--client-id/--secret | --from-current] | remove <name>`, a global `--profile <name>` flag on every command, and `ZEYOS_PROFILE`. Profiles live in `~/.config/zeyos/profiles.json` with an active pointer; a project can pin one via `.zeyos/profile`. Resolution: `--profile` > `ZEYOS_PROFILE` > project pin > legacy `.zeyos/auth.json` > global active > legacy global. Fully backward compatible.
+- `login --profile <name>` authenticates into (and activates) a named profile; `logout` is profile-aware; refreshed tokens persist back to whichever store they came from.
+- `login` now detects an **expired** stored token and re-authenticates instead of reporting "already logged in"; `whoami` surfaces `502/503/504` as "instance temporarily unavailable" and `401` as an expired-session hint, instead of a raw status.
+
+### Agent skills
+- New **`zeyos-time-tracking`** skill: first-person work views ("what are my current tickets/tasks?") and interactive time logging ("log 60 minutes for client XYZ" → resolve account → pick ticket/task → write effort as an actionstep), plus timesheet summaries and entry corrections.
+
 ## 0.2.0
 
 ### `@zeyos/client`
 - Added a `dryRun` request option: `client.api.*`, `client.request()`, etc. return a resolved `{ dryRun, method, url, body, bodyType, … }` descriptor without performing any network request or token work. Powers the CLI `--query` flag and is handy for debugging and tests.
-- Packaging: the published tarball now lists sample paths explicitly, so the generated `samples/missioncontrol/data.js` / `data.json` (which can contain real instance data) are never shipped to npm.
 
 ### `@zeyos/cli` (`zeyos`)
 - New `doctor agent` command: an offline readiness check for coding agents — reports CLI version, configured base URL/instance, whether auth is present via environment/local/global config, and resource-registry health. Never prints tokens or client secrets.
@@ -19,9 +51,6 @@ Notable changes to `@zeyos/client` and `@zeyos/cli`. This project follows
 - Skill packs are self-contained: each domain `SKILL.md` now points at a shared operating guide (`agents/shared/zeyos-agent-operating-guide.md`) with a bare-skill checklist and shell-safe command hygiene (inline single-quoted JSON, `--filter-file`/`--data-file`, counts via `zeyos count`).
 - Added an entity-noun → REST `operationId` reference and per-domain workflow notes (first-command examples for counts, `visibility`-column caveats, and the diverging dunning operationIds).
 
-### Samples
-- New `samples/missioncontrol` team-performance dashboard: a read-only Node fetcher (`fetch-data.mjs`) plus a static, dependency-free `index.html`. The generated data files are git-ignored and excluded from the npm package.
-
 ### Docs
 - Documented `--filter-file`/`--data-file` and the new `doctor` command across the CLI getting-started and command reference.
 

package/README.md

@@ -203,6 +203,7 @@ zeyos <command> [options] [args…]
 | `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` |
+| `okf <list\|show\|check\|export\|build>` | Work with the OKF knowledge bundle | `zeyos okf show tickets` |
 
 **Global options** (work on every command): `--json`, `--yaml`, `--no-color`, `-h/--help`, `-v/--version`.
 
@@ -405,6 +406,33 @@ See [Agent Workflows](./docs/04-agent-workflows/00-coding-agents.md): [quickstar
 
 ---
 
+## Open Knowledge Format (OKF)
+
+The client ships a conformant [**Open Knowledge Format**](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
+bundle under [`okf/`](./okf/) — a portable, Git-native Markdown description of the ZeyOS data
+model (one concept per API-backed entity: schema, foreign keys, enums, indexes, operationIds)
+plus curated metrics, playbooks, and query concepts. Agents and tools read it as a shared
+knowledge layer, independent of this client.
+
+```bash
+zeyos okf list                 # browse concepts
+zeyos okf show tickets         # print a concept (schema + curated notes)
+zeyos okf check                # validate OKF v0.1 conformance
+zeyos okf export --out ./okf   # vendor the bundle into your project
+```
+
+```js
+import { buildOkf, loadOkfBundle, validateOkfBundle } from '@zeyos/client';
+const files = buildOkf();                                  // synthesize from the client schema
+const bundle = await loadOkfBundle('node_modules/@zeyos/client/okf');
+```
+
+The bundle is **generated** from the OpenAPI/dbref specs into managed blocks, with curated
+prose preserved across regeneration, and it is **canonical** for structural facts (the shared
+skill references derive from it). It is regenerated by `npm run generate` and gated by
+`npm run okf:check`. See the [OKF docs](./docs/06-okf/01-overview.md) for the bundle layout,
+the spec-refresh runbook, and how it ties into the [skill-improvement loops](./docs/06-okf/04-loops.md).
+
 ## Sample apps
 
 Three runnable, dependency-free browser demos live in [`samples/`](./samples/):
@@ -423,9 +451,10 @@ Each can be served as static files from the repository root; see the linked docs
 - [`cli/`](./cli/) — the `@zeyos/cli` command-line tool.
 - [`docs/`](./docs/) — the authoritative documentation (Docusaurus).
 - [`agents/`](./agents/) — repo-local ZeyOS agent skills and query playbooks.
+- [`okf/`](./okf/) — the [Open Knowledge Format](./docs/06-okf/01-overview.md) bundle: a portable, Git-native Markdown description of the ZeyOS data model (canonical for structural facts).
 - [`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.
+- [`scripts/`](./scripts/) — client + OKF generation (`generate-client.mjs`, `generate-okf.mjs`) and the test runner.
 
 ---
 
@@ -439,6 +468,7 @@ Each can be served as static files from the repository root; see the linked docs
 | **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) |
+| **Open Knowledge Format** | The OKF knowledge bundle: overview, producing/consuming, keeping it fresh, refinement loops | [docs/06-okf](./docs/06-okf/01-overview.md) |
 | **Agent Skills** | What the bundled skills do and how they're organized | [agents/README.md](./agents/README.md) |
 
 ---

package/agents/README.md

@@ -5,6 +5,8 @@ This folder contains a repo-local skill pack for coding agents that use ZeyOS as
 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).
 
+The **canonical** per-entity schema (columns, types, enums, foreign keys, indexes, operationIds) now lives in the [Open Knowledge Format bundle](../okf/entities/index.md) under [`okf/`](../okf/), generated from the same specs; the shared reference's operationId table is generated from it. Cross-cutting query rules and footguns are in [`okf/concepts/`](../okf/concepts/index.md). When a schema fact in a shared reference and in `okf/` disagree, `okf/` wins.
+
 ## Structure
 
 - `shared/` contains cross-domain query rules and entity relationships, including
@@ -15,6 +17,7 @@ Cross-platform modeling guidance lives in [`shared/business-app-benchmarks.md`](
   the authenticated `zeyos` CLI. Use it when a request touches ZeyOS data and no
   domain-specific skill clearly fits.
 - `zeyos-work-management/` handles tasks, projects, tickets, and assignee workload questions.
+- `zeyos-time-tracking/` handles first-person work views ("my tickets/tasks") and interactive time logging (resolve account, pick the ticket/task, write the effort as an actionstep).
 - `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.
@@ -42,6 +45,7 @@ Cross-platform modeling guidance lives in [`shared/business-app-benchmarks.md`](
 |------|----------|-----------------|
 | `zeyos` | General-purpose ZeyOS access via the CLI; the catch-all when no domain skill fits | "How many open customers do we have?"; "List the 10 most recently modified tickets."; "Show me account 122." |
 | `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-time-tracking` | First-person work views and interactive time logging (resolve account → pick ticket/task → write effort as an actionstep) | "What are my current tickets?"; "Show my open tasks."; "Log 60 minutes for client XYZ."; "Record 2 hours on ticket 812." |
 | `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?" |

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

@@ -2,7 +2,11 @@
 
 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).
+This is the high-level relationship map (curated). For the per-entity schema — columns, enums,
+foreign keys, indexes, and operationIds — read the canonical [`okf/entities/`](../../okf/entities/index.md)
+concepts; for cross-cutting query rules read [`okf/concepts/`](../../okf/concepts/index.md). The
+source-backed inventory and the generated operationId table live in
+[zeyos-entity-reference.md](./zeyos-entity-reference.md), 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`,

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

@@ -14,6 +14,13 @@ Current source snapshot:
 
 Use this file when you need to understand what an entity is for before building a query plan.
 
+> **Canonical schema lives in the OKF bundle.** Per-entity columns, types, enums, foreign keys,
+> indexes (incl. the GIN/partial indexes behind the `filters` footgun), and operationIds are
+> generated into [`okf/entities/`](../../okf/entities/index.md) from the specs, and cross-cutting
+> rules into [`okf/concepts/`](../../okf/concepts/index.md). This reference keeps the curated
+> narrative (entity families, query priorities, use-case clusters); the operationId table below is
+> generated from the same source. When schema facts here and in `okf/` ever disagree, `okf/` wins.
+
 ## Source Note: `filter` vs `filters`
 
 Do not treat the spelling as universally settled.
@@ -58,39 +65,88 @@ Entities that follow the regular rule directly (lowercase noun, single English w
 
 `*` = read-only entity: only `list*`, `get*`, and `exists*` exist (no create/update/delete).
 
-### Exceptions (verify these — the noun does NOT map naively)
-
-Every operationId below was verified to exist in `src/generated/operations.js`. Junction tables
-(`X2Y`) become `XToY` (CamelCase, with the **left** side often re-pluralized). Some entities are
-renamed entirely (`dunning` -> `DunningNotice`), and several are compound words that must keep their
-internal capitalization (e.g. `MailingLists`, not `Mailinglists`).
-
-| dbref noun | list | get | create | update | delete | exists | Notes |
-|------------|------|-----|--------|--------|--------|--------|-------|
-| `actionsteps` | `listActionSteps` | `getActionStep` | `createActionStep` | `updateActionStep` | `deleteActionStep` | `existsActionStep` | Compound `ActionStep` |
-| `applicationassets` | `listApplicationAssets` | `getApplicationAsset` | — | — | — | `existsApplicationAsset` | Read-only; compound |
-| `binfiles` | `listBinFiles` | — | — | — | — | — | **List-only.** `BinFiles` |
-| `categories` | `listCategorys` | `getCategory` | `createCategory` | `updateCategory` | `deleteCategory` | `existsCategory` | List op is `listCategorys` (sic — no irregular plural); singular ops use `Category` |
-| `contacts2contacts` | `listContactsToContacts` | `getContactToContact` | `createContactToContact` | `updateContactToContact` | `deleteContactToContact` | `existsContactToContact` | Junction `X2Y` -> `XToY` |
-| `couponcodes` | `listCouponCodes` | `getCouponCode` | `createCouponCode` | `updateCouponCode` | `deleteCouponCode` | `existsCouponCode` | Compound `CouponCode` |
-| `customfields` | `listCustomFields` | `getCustomField` | — | — | — | `existsCustomField` | Read-only; compound |
-| `davservers` | `listDAVServers` | `getDAVServer` | `createDAVServer` | `updateDAVServer` | `deleteDAVServer` | `existsDAVServer` | Acronym uppercased: `DAVServer` |
-| `dunning` | `listDunningNotices` | `getDunningNotice` | `createDunningNotice` | `updateDunningNotice` | `deleteDunningNotice` | `existsDunningNotice` | Entity is **`DunningNotice`**, not `Dunning` |
-| `dunning2transactions` | `listDunningToTransactions` | `getDunningToTransaction` | `createDunningToTransaction` | `updateDunningToTransaction` | `deleteDunningToTransaction` | `existsDunningToTransaction` | Junction `dunning2transactions` -> `DunningToTransaction(s)` |
-| `entities2channels` | `listEntitiesToChannels` | `getEntityToChannel` | `createEntityToChannel` | `updateEntityToChannel` | `deleteEntityToChannel` | `existsEntityToChannel` | Junction; singular re-singularized to `EntityToChannel` |
-| `feedservers` | `listFeedServers` | `getFeedServer` | `createFeedServer` | `updateFeedServer` | `deleteFeedServer` | `existsFeedServer` | Compound `FeedServer` |
-| `groups2users` | `listGroupsToUsers` | `getGroupToUser` | — | — | — | `existsGroupToUser` | Read-only junction `X2Y` -> `XToY` |
-| `mailinglists` | `listMailingLists` | `getMailingList` | `createMailingList` | `updateMailingList` | `deleteMailingList` | `existsMailingList` | Compound `MailingList` |
-| `mailingrecipients` | `listMailingRecipients` | `getMailingRecipient` | `createMailingRecipient` | `updateMailingRecipient` | `deleteMailingRecipient` | `existsMailingRecipients` | Compound; **exists op is plural** `existsMailingRecipients` (sic) |
-| `mailservers` | `listMailServers` | `getMailServer` | `createMailServer` | `updateMailServer` | `deleteMailServer` | `existsMailServer` | Compound `MailServer` |
-| `messagereads` | `listMessageReads` | `getMessageRead` | `createMessageRead` | `updateMessageRead` | `deleteMessageRead` | `existsMessageRead` | Compound `MessageRead` |
-| `pricelists` | `listPriceLists` | `getPriceList` | `createPriceList` | `updatePriceList` | `deletePriceList` | `existsPriceList` | Compound `PriceList` |
-| `pricelists2accounts` | `listPriceListsToAccounts` | `getPriceListToAccount` | `createPriceListToAccount` | `updatePriceListToAccount` | `deletePriceListToAccount` | `existsPriceListToAccount` | Junction; compound on both sides |
-| `relateditems` | `listRelatedItems` | `getRelatedItem` | `createRelatedItem` | `updateRelatedItem` | `deleteRelatedItem` | `existsRelatedItem` | Compound `RelatedItem` |
-| `stocktransactions` | `listStockTransactions` | `getStockTransaction` | `createStockTransaction` | `updateStockTransaction` | `deleteStockTransaction` | `existsStockTransaction` | Compound `StockTransaction` |
-
-When in doubt, look up the operationId in `src/generated/operations.js` (or `openapi/api.json`) rather
-than constructing it from the noun.
+### The authoritative table (generated from `openapi/api.json`)
+
+The full `list`/`get`/`create`/`update`/`delete`/`exists` operationId for **every** API-backed
+entity is generated below and kept in sync with the specs by `scripts/generate-okf.mjs`. The
+tricky cases all appear with their real operationIds: junction tables (`X2Y` → `XToY`, often
+re-pluralizing the left side), renamed entities (`dunning` → `DunningNotice`), compounds that
+keep internal capitalization (`MailingLists`, not `Mailinglists`), and quirks like `listCategorys`
+(sic) or the plural `existsMailingRecipients`. A `—` means the operation does not exist
+(read-only or list-only entity). Per-entity schema, enums, and foreign keys live in the matching
+[`okf/entities/<name>.md`](../../okf/entities/index.md) concept, which is the canonical source.
+
+<!-- okf:generated:start — rewritten by scripts/generate-okf.mjs; do not edit by hand -->
+| Entity | Concept | list | get | create | update | delete | exists |
+|---|---|---|---|---|---|---|---|
+| `accounts` | [↗](../../okf/entities/accounts.md) | `listAccounts` | `getAccount` | `createAccount` | `updateAccount` | `deleteAccount` | `existsAccount` |
+| `actionsteps` | [↗](../../okf/entities/actionsteps.md) | `listActionSteps` | `getActionStep` | `createActionStep` | `updateActionStep` | `deleteActionStep` | `existsActionStep` |
+| `addresses` | [↗](../../okf/entities/addresses.md) | `listAddresses` | `getAddress` | `createAddress` | `updateAddress` | `deleteAddress` | `existsAddress` |
+| `applicationassets` | [↗](../../okf/entities/applicationassets.md) | `listApplicationAssets` | `getApplicationAsset` | — | — | — | `existsApplicationAsset` |
+| `applications` | [↗](../../okf/entities/applications.md) | `listApplications` | `getApplication` | — | — | — | `existsApplication` |
+| `appointments` | [↗](../../okf/entities/appointments.md) | `listAppointments` | `getAppointment` | `createAppointment` | `updateAppointment` | `deleteAppointment` | `existsAppointment` |
+| `associations` | [↗](../../okf/entities/associations.md) | `listAssociations` | `getAssociation` | `createAssociation` | `updateAssociation` | `deleteAssociation` | `existsAssociation` |
+| `binfiles` | [↗](../../okf/entities/binfiles.md) | `listBinFiles` | — | — | — | — | — |
+| `campaigns` | [↗](../../okf/entities/campaigns.md) | `listCampaigns` | `getCampaign` | `createCampaign` | `updateCampaign` | `deleteCampaign` | `existsCampaign` |
+| `categories` | [↗](../../okf/entities/categories.md) | `listCategorys` | `getCategory` | `createCategory` | `updateCategory` | `deleteCategory` | `existsCategory` |
+| `channels` | [↗](../../okf/entities/channels.md) | `listChannels` | `getChannel` | `createChannel` | `updateChannel` | `deleteChannel` | `existsChannel` |
+| `comments` | [↗](../../okf/entities/comments.md) | `listComments` | `getComment` | `createComment` | `updateComment` | `deleteComment` | `existsComment` |
+| `components` | [↗](../../okf/entities/components.md) | `listComponents` | `getComponent` | `createComponent` | `updateComponent` | `deleteComponent` | `existsComponent` |
+| `contacts` | [↗](../../okf/entities/contacts.md) | `listContacts` | `getContact` | `createContact` | `updateContact` | `deleteContact` | `existsContact` |
+| `contacts2contacts` | [↗](../../okf/entities/contacts2contacts.md) | `listContactsToContacts` | `getContactToContact` | `createContactToContact` | `updateContactToContact` | `deleteContactToContact` | `existsContactToContact` |
+| `contracts` | [↗](../../okf/entities/contracts.md) | `listContracts` | `getContract` | `createContract` | `updateContract` | `deleteContract` | `existsContract` |
+| `couponcodes` | [↗](../../okf/entities/couponcodes.md) | `listCouponCodes` | `getCouponCode` | `createCouponCode` | `updateCouponCode` | `deleteCouponCode` | `existsCouponCode` |
+| `coupons` | [↗](../../okf/entities/coupons.md) | `listCoupons` | `getCoupon` | `createCoupon` | `updateCoupon` | `deleteCoupon` | `existsCoupon` |
+| `customfields` | [↗](../../okf/entities/customfields.md) | `listCustomFields` | `getCustomField` | — | — | — | `existsCustomField` |
+| `davservers` | [↗](../../okf/entities/davservers.md) | `listDAVServers` | `getDAVServer` | `createDAVServer` | `updateDAVServer` | `deleteDAVServer` | `existsDAVServer` |
+| `devices` | [↗](../../okf/entities/devices.md) | `listDevices` | `getDevice` | `createDevice` | `updateDevice` | `deleteDevice` | `existsDevice` |
+| `documents` | [↗](../../okf/entities/documents.md) | `listDocuments` | `getDocument` | `createDocument` | `updateDocument` | `deleteDocument` | `existsDocument` |
+| `dunning` | [↗](../../okf/entities/dunning.md) | `listDunningNotices` | `getDunningNotice` | `createDunningNotice` | `updateDunningNotice` | `deleteDunningNotice` | `existsDunningNotice` |
+| `dunning2transactions` | [↗](../../okf/entities/dunning2transactions.md) | `listDunningToTransactions` | `getDunningToTransaction` | `createDunningToTransaction` | `updateDunningToTransaction` | `deleteDunningToTransaction` | `existsDunningToTransaction` |
+| `entities2channels` | [↗](../../okf/entities/entities2channels.md) | `listEntitiesToChannels` | `getEntityToChannel` | `createEntityToChannel` | `updateEntityToChannel` | `deleteEntityToChannel` | `existsEntityToChannel` |
+| `events` | [↗](../../okf/entities/events.md) | `listEvents` | `getEvent` | `createEvent` | `updateEvent` | `deleteEvent` | `existsEvent` |
+| `feedservers` | [↗](../../okf/entities/feedservers.md) | `listFeedServers` | `getFeedServer` | `createFeedServer` | `updateFeedServer` | `deleteFeedServer` | `existsFeedServer` |
+| `files` | [↗](../../okf/entities/files.md) | `listFiles` | `getFile` | `createFile` | `updateFile` | `deleteFile` | `existsFile` |
+| `follows` | [↗](../../okf/entities/follows.md) | `listFollows` | `getFollow` | `createFollow` | `updateFollow` | `deleteFollow` | `existsFollow` |
+| `forks` | [↗](../../okf/entities/forks.md) | `listForks` | `getFork` | — | — | — | `existsFork` |
+| `groups` | [↗](../../okf/entities/groups.md) | `listGroups` | `getGroup` | — | — | — | `existsGroup` |
+| `groups2users` | [↗](../../okf/entities/groups2users.md) | `listGroupsToUsers` | `getGroupToUser` | — | — | — | `existsGroupToUser` |
+| `invitations` | [↗](../../okf/entities/invitations.md) | `listInvitations` | `getInvitation` | `createInvitation` | `updateInvitation` | `deleteInvitation` | `existsInvitation` |
+| `items` | [↗](../../okf/entities/items.md) | `listItems` | `getItem` | `createItem` | `updateItem` | `deleteItem` | `existsItem` |
+| `ledgers` | [↗](../../okf/entities/ledgers.md) | `listLedgers` | `getLedger` | `createLedger` | `updateLedger` | `deleteLedger` | `existsLedger` |
+| `likes` | [↗](../../okf/entities/likes.md) | `listLikes` | `getLike` | `createLike` | `updateLike` | `deleteLike` | `existsLike` |
+| `links` | [↗](../../okf/entities/links.md) | `listLinks` | `getLink` | `createLink` | `updateLink` | `deleteLink` | `existsLink` |
+| `mailinglists` | [↗](../../okf/entities/mailinglists.md) | `listMailingLists` | `getMailingList` | `createMailingList` | `updateMailingList` | `deleteMailingList` | `existsMailingList` |
+| `mailingrecipients` | [↗](../../okf/entities/mailingrecipients.md) | `listMailingRecipients` | `getMailingRecipient` | `createMailingRecipient` | `updateMailingRecipient` | `deleteMailingRecipient` | `existsMailingRecipients` |
+| `mailservers` | [↗](../../okf/entities/mailservers.md) | `listMailServers` | `getMailServer` | `createMailServer` | `updateMailServer` | `deleteMailServer` | `existsMailServer` |
+| `messagereads` | [↗](../../okf/entities/messagereads.md) | `listMessageReads` | `getMessageRead` | `createMessageRead` | `updateMessageRead` | `deleteMessageRead` | `existsMessageRead` |
+| `messages` | [↗](../../okf/entities/messages.md) | `listMessages` | `getMessage` | `createMessage` | `updateMessage` | `deleteMessage` | `existsMessage` |
+| `notes` | [↗](../../okf/entities/notes.md) | `listNotes` | `getNote` | `createNote` | `updateNote` | `deleteNote` | `existsNote` |
+| `objects` | [↗](../../okf/entities/objects.md) | `listObjects` | `getObject` | `createObject` | `updateObject` | `deleteObject` | `existsObject` |
+| `opportunities` | [↗](../../okf/entities/opportunities.md) | `listOpportunities` | `getOpportunity` | `createOpportunity` | `updateOpportunity` | `deleteOpportunity` | `existsOpportunity` |
+| `participants` | [↗](../../okf/entities/participants.md) | `listParticipants` | `getParticipant` | `createParticipant` | `updateParticipant` | `deleteParticipant` | `existsParticipant` |
+| `payments` | [↗](../../okf/entities/payments.md) | `listPayments` | `getPayment` | `createPayment` | `updatePayment` | `deletePayment` | `existsPayment` |
+| `permissions` | [↗](../../okf/entities/permissions.md) | `listPermissions` | `getPermission` | — | — | — | `existsPermission` |
+| `pricelists` | [↗](../../okf/entities/pricelists.md) | `listPriceLists` | `getPriceList` | `createPriceList` | `updatePriceList` | `deletePriceList` | `existsPriceList` |
+| `pricelists2accounts` | [↗](../../okf/entities/pricelists2accounts.md) | `listPriceListsToAccounts` | `getPriceListToAccount` | `createPriceListToAccount` | `updatePriceListToAccount` | `deletePriceListToAccount` | `existsPriceListToAccount` |
+| `prices` | [↗](../../okf/entities/prices.md) | `listPrices` | `getPrice` | `createPrice` | `updatePrice` | `deletePrice` | `existsPrice` |
+| `projects` | [↗](../../okf/entities/projects.md) | `listProjects` | `getProject` | `createProject` | `updateProject` | `deleteProject` | `existsProject` |
+| `records` | [↗](../../okf/entities/records.md) | `listRecords` | `getRecord` | `createRecord` | `updateRecord` | `deleteRecord` | `existsRecord` |
+| `relateditems` | [↗](../../okf/entities/relateditems.md) | `listRelatedItems` | `getRelatedItem` | `createRelatedItem` | `updateRelatedItem` | `deleteRelatedItem` | `existsRelatedItem` |
+| `resources` | [↗](../../okf/entities/resources.md) | `listResources` | `getResource` | — | — | — | `existsResource` |
+| `services` | [↗](../../okf/entities/services.md) | `listServices` | `getService` | — | — | — | `existsService` |
+| `stocktransactions` | [↗](../../okf/entities/stocktransactions.md) | `listStockTransactions` | `getStockTransaction` | `createStockTransaction` | `updateStockTransaction` | `deleteStockTransaction` | `existsStockTransaction` |
+| `storages` | [↗](../../okf/entities/storages.md) | `listStorages` | `getStorage` | `createStorage` | `updateStorage` | `deleteStorage` | `existsStorage` |
+| `suppliers` | [↗](../../okf/entities/suppliers.md) | `listSuppliers` | `getSupplier` | `createSupplier` | `updateSupplier` | `deleteSupplier` | `existsSupplier` |
+| `tasks` | [↗](../../okf/entities/tasks.md) | `listTasks` | `getTask` | `createTask` | `updateTask` | `deleteTask` | `existsTask` |
+| `tickets` | [↗](../../okf/entities/tickets.md) | `listTickets` | `getTicket` | `createTicket` | `updateTicket` | `deleteTicket` | `existsTicket` |
+| `transactions` | [↗](../../okf/entities/transactions.md) | `listTransactions` | `getTransaction` | `createTransaction` | `updateTransaction` | `deleteTransaction` | `existsTransaction` |
+| `users` | [↗](../../okf/entities/users.md) | `listUsers` | `getUser` | — | — | — | `existsUser` |
+| `weblets` | [↗](../../okf/entities/weblets.md) | `listWeblets` | `getWeblet` | — | — | — | `existsWeblet` |
+<!-- okf:generated:end -->
+
+When in doubt, read the entity's OKF concept (linked above) or look the operationId up in
+`openapi/api.json` rather than constructing it from the noun.
 
 ## API-Backed Entities
 

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

@@ -25,9 +25,15 @@ Typical prompts:
 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.
+7. Treat textual drafts as safe. Treat message record creation/update as a write and sending or marking `mailbox=2` as high risk; require explicit confirmation plus verified sender context before any real mail mutation.
 8. Escalate to `@zeyos/client` when you need binary content, MIME expansion, or richer message correlation than the CLI can express cleanly.
 
+## Safety
+
+- Never send email from an agent test or from a summary/draft request.
+- Do not create or update message records unless the user explicitly asks for a real ZeyOS draft and the sender/mailserver context is known.
+- For "draft a reply", produce reply text in the response and leave ZeyOS unchanged.
+
 ## Output Discipline
 
 - Report the resolved customer identity and the email addresses used for matching.

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

@@ -5,6 +5,8 @@
 - `0` = inbox
 - `1` = drafts
 - `2` = sent
+- `3` = templates
+- `4` = mailings
 - `5` = archive
 - `6` = trash
 - `7` = junk
@@ -68,6 +70,17 @@ Recommended approach:
 3. Use `reference` and `messageid` to confirm direct reply relationships.
 4. Use subject matching only as a fallback.
 
+CLI example:
+
+```bash
+zeyos list messages \
+  --fields ID,date,mailbox,subject,sender_email,to_email,ticket,reference,messageid \
+  --filter '{"ticket":812}' \
+  --sort +date \
+  --limit 100 \
+  --json
+```
+
 ## Pattern: Find Unanswered Customer Mail
 
 Use this for prompts like:
@@ -80,9 +93,11 @@ 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.
+4. Look for a later sent message (`mailbox = 2`) in the same thread. The strongest match is `sent.reference == inbound.ID`; subject matching is only a fallback.
 5. Report unresolved threads and their linked tickets if available.
 
+For an operational count, use this exact definition unless the user specifies another one: inbox message (`mailbox = 0`) linked to an open ticket, with no later sent message (`mailbox = 2`) whose `reference` points back to that inbound message.
+
 ## Pattern: Draft A Reply
 
 Use this for prompts like:
@@ -95,12 +110,14 @@ 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.
+4. Create or update a draft message only if the user explicitly asks for a real ZeyOS draft and the required sender/mailserver 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.
+- Do not set `messageid` when creating test/draft messages; the API may reject it even though list/get responses can expose the field.
 - Never send email just because a user asked for a summary or a draft.
+- In agent protocol tests, "draft" means text output only. Do not call `createMessage`, `updateMessage`, or any send/dispatch path unless the scenario explicitly asks for a real draft record.
 
 ## Common Failure Modes
 

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

@@ -26,7 +26,7 @@ Typical prompts:
 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))
+   - `customfields`, `objects`, and extdata helper families for schema and custom data (`customfields` is exposed in the CLI as `customfields` for read/count; in the JS client it maps to `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.
 

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

@@ -24,11 +24,27 @@ before calling `@zeyos/client`.
 
 ## First Commands For Counts
 
-- All custom fields: `zeyos count customfields`
-- Custom fields for tickets: `zeyos count customfields --filter '{"entity":"tickets"}'`
-
-`customfields` has no `visibility` field. In the JS client the list operation is
-`listCustomFields`, not `listCustomfields`.
+- All custom fields: `zeyos count customfields --json`
+- Custom fields for tickets: `zeyos count customfields --filter '{"entity":"tickets"}' --json`
+
+`customfields` is read-only and has no `visibility` field. In the JS client the list
+operation is `listCustomFields`, not `listCustomfields`.
+
+For a total count, use the `count` value from the CLI JSON response. Do not answer `0`
+because `customfields` is missing from an old CLI registry, because a command failed, or
+because `zeyos resources` did not list it. If `zeyos count customfields` fails with
+"Unknown resource", run `zeyos doctor agent --json` to inspect the CLI version and then
+switch to the JavaScript client:
+
+```bash
+node --input-type=module -e 'const { createZeyosClient, normalizeListResult } = await import(`${process.env.ZEYOS_REPO_ROOT}/src/index.js`);
+const client = createZeyosClient({
+  platform: process.env.ZEYOS_BASE_URL,
+  auth: { mode: "oauth", oauth: { token: { accessToken: process.env.ZEYOS_TOKEN }, autoRefresh: false } }
+});
+const rows = normalizeListResult(await client.api.listCustomFields({ limit: 10000 })).data;
+console.log(rows.length);'
+```
 
 ## Pattern: Custom Fields For An Entity
 

package/agents/zeyos-time-tracking/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: zeyos-time-tracking
+description: First-person personal work and interactive time logging in ZeyOS. Use when the user speaks about their own work ("what are my current tickets?", "what's on my plate?", "what am I working on?", "my open tasks", "my action steps") or wants to record/log/book time or effort ("log 60 minutes for client XYZ", "record 2 hours on ticket 812", "book time against Project Atlas"). Resolves the current user, finds the right account and the candidate ticket/task/project to attach time to, confirms the target with the user, then writes the time entry as an actionstep with `effort`.
+---
+
+# ZeyOS Time Tracking
+
+Read [../shared/zeyos-agent-operating-guide.md](../shared/zeyos-agent-operating-guide.md) and [../shared/zeyos-query-patterns.md](../shared/zeyos-query-patterns.md) first. Read [references/workflows.md](references/workflows.md) for the concrete query and write patterns. This skill overlaps with [../zeyos-work-management/SKILL.md](../zeyos-work-management/SKILL.md): use **work-management** for third-person, analytical queries about other people's queues, project tracing, and effort *summaries*; use **time-tracking** when the request is **first-person** ("my …") or is about **recording new time**.
+
+Typical prompts:
+
+- "What are my current tickets?" / "What's on my plate?" / "What am I working on?"
+- "Show my open tasks." / "What action steps are assigned to me?"
+- "Log 60 minutes of work for client XYZ."
+- "Record 2 hours on ticket 812." / "Book 90 minutes against Project Atlas."
+- "Log half an hour for ACME, I was on a call about the renewal."
+- "How much time did I log this week?" / "Summarize my logged hours by account."
+- "Actually make that 90 minutes, not 60." / "Move that time to ticket 813."
+
+## Two jobs
+
+1. **Read "my work"** — resolve the current user, then list their open tickets / tasks / action steps. Read-only; just run it.
+2. **Log time (a write)** — resolve *who* the time is for, *what* it attaches to, then create one `actionstep` carrying the effort. This is interactive and confirmed.
+
+## The current user
+
+The logged-in user's id is `getUserInfo().sub` — a stringified positive integer that **is** the `users.ID`. Get it from `zeyos whoami --json` (read the `sub` field) before any "my …" query, and use it as `assigneduser` on the work resources. Do not guess it and do not ask the user for it.
+
+## Interactive discipline (this is the point of the skill)
+
+Interactivity here means **act first, then ask only when real data is ambiguous** — never the planning-instead-of-running failure the operating guide warns about.
+
+1. **Always run the resolution queries before asking anything.** "I found 3 accounts matching 'XYZ' — which one?" is good (grounded in a query you ran). "Which account do you mean?" with no search behind it is not.
+2. **Ask only when the data is genuinely ambiguous** and the answer changes the write: multiple account matches, or several plausible tickets/tasks. A single unambiguous match needs no question — state it and continue.
+3. **Confirm the target before the write.** Time logging creates a record. The user's "log 60 minutes" authorizes *one* entry; the confirmation is about *where* it lands (which work item) and *what* it says — show the actionstep you are about to create and let the user correct it.
+4. **Never invent the attachment.** If you cannot resolve a confident target and there is no human to ask (e.g. an automated run), stop and report what you found rather than guessing a foreign key for a write.
+
+## Safety
+
+- Read views are read-only; run them directly.
+- Logging time is a **create**, allowed because the user explicitly asked to log it. Preview with `--query` and confirm the target first; create exactly one record; then read it back.
+- Never delete or bulk-modify time entries on a category ("clear my logged time", "remove old entries") — those are per-record, by id, after preview. See the destructive-operations rules in [../zeyos-work-management/SKILL.md](../zeyos-work-management/SKILL.md).
+
+## Output discipline
+
+- For "my work": state the resolved user and the open-status definition you used, then the list.
+- For a logged entry: report the created actionstep id, the attached record (ticket/task/account), the effort in minutes, and the date.
+- Separate what you resolved from what you assumed; call out any account or work-item ambiguity you had to break.