@zeyos/client 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 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`

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

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/docs/03-cli/02-commands.md

@@ -481,6 +481,34 @@ Skills are copied into `<dir>/<name>/`, with the shared reference files installe
 
 ---
 
+## okf
+
+Work with the [Open Knowledge Format](../06-okf/01-overview.md) bundle that ships with the
+client — a portable Markdown description of the ZeyOS data model (one concept per
+API-backed entity) plus curated metrics, playbooks, and query concepts.
+
+```bash
+zeyos okf list                  # list concepts (type, id, title); --json for automation
+zeyos okf show tickets          # print a concept (bare resource name, or entities/tickets)
+zeyos okf check                 # validate OKF v0.1 conformance (exit non-zero on error)
+zeyos okf export --out ./okf    # copy the shipped bundle into a directory
+zeyos okf build  --out ./okf    # synthesize a bundle from the client's schema
+```
+
+| Subcommand | What it does |
+|-----------|--------------|
+| `list` | List the concepts in the bundle (`--json`/`--yaml` supported). |
+| `show <concept>` | Print one concept doc. Accepts a bare resource (`tickets`) or full id (`entities/tickets`). |
+| `check` | Validate the bundle for OKF v0.1 conformance; exits non-zero on any error (CI-friendly). |
+| `export` | Copy the shipped `okf/` bundle into `--out` (default `./okf`); `--force` to overwrite. |
+| `build` | Synthesize a structural bundle from the client's schema into `--out` (default `./okf`). |
+
+Options: `--dir <path>` reads from an explicit bundle directory (`list`/`show`/`check`);
+`--out <path>` is the write target (`build`/`export`); `--force` overwrites an existing
+target. `export` ships the rich curated bundle; `build` is the lighter runtime projection.
+
+---
+
 ## Command Aliases
 
 | Alias | Equivalent |

package/docs/06-okf/01-overview.md

@@ -0,0 +1,70 @@
+# OKF Overview
+
+The **Open Knowledge Format (OKF v0.1)** is Google's minimal, vendor-neutral spec for
+sharing the metadata and curated context that surrounds data: a directory of Markdown
+files, each with YAML frontmatter whose only required field is `type`, optional `index.md`
+and `log.md`, and Markdown cross-links that turn the directory into a knowledge graph.
+Producers emit a bundle; consumers (coding agents, viewers, search) read it.
+
+`@zeyos/client` ships a conformant OKF bundle under [`okf/`](https://github.com/zeyos/client/tree/main/okf)
+that describes the ZeyOS data model, and tooling to produce, consume, validate, and refine it.
+
+## Why OKF fits ZeyOS
+
+The client already derives a compact schema from the OpenAPI/dbref specs. OKF turns that —
+plus the curated business knowledge that used to live only in the skill pack — into a
+portable knowledge layer any agent or tool can read, independent of this client.
+
+The bundle is **canonical** for ZeyOS structural facts: the hand-maintained
+`agents/shared/zeyos-entity-reference.md` operationId table is now generated from the same
+source, so the skills and the OKF bundle can't drift apart.
+
+## Bundle layout
+
+```
+okf/
+  index.md                  # root listing; frontmatter: okf_version, source_snapshot
+  log.md                    # schema-change history (auto-appended on real changes)
+  entities/                 # one concept per API-backed entity — type: ZeyOS Entity
+    index.md
+    accounts.md  tickets.md  transactions.md  …
+  metrics/                  # business metric definitions — type: Metric
+  playbooks/                # step-by-step query workflows — type: Playbook
+  concepts/                 # cross-cutting rules / footguns — type: Reference
+```
+
+Each entity concept carries a **Schema** table (column, type, nullability, default, index,
+foreign key), **Foreign Keys** (cross-linked to the target entity), **Enums** (parsed from
+the schema), **Indexes** (including the GIN/partial indexes behind the `filters` footgun),
+and **Operations** (the real `@zeyos/client` operationIds, read straight from `api.json`).
+
+## Generated vs curated: managed blocks
+
+Each entity concept mixes auto-generated structure with curated prose. The generated region
+is fenced by HTML-comment markers:
+
+```markdown
+<!-- okf:generated:start — rewritten by scripts/generate-okf.mjs; do not edit by hand -->
+# Schema
+…
+<!-- okf:generated:end -->
+
+# Notes
+Curated guidance — preserved across every regeneration.
+```
+
+The producer rewrites **only** the region between the markers. Curated `# Notes`/`# Metrics`
+prose (added by a human or the refinement loop) is preserved verbatim, so regenerating after
+a schema change never clobbers curation. See [Keeping OKF fresh](./03-keeping-fresh.md).
+
+## Relationship to the skill pack
+
+Two projections of one knowledge core:
+
+- **Skills** (`agents/`) stay the task/runner-facing layer: the operating contract, "act,
+  don't plan", and safety.
+- **OKF** (`okf/`) is the reference layer: the entity schema-of-record plus the metric,
+  playbook, and concept catalog.
+
+Skills point into `okf/`; when a schema fact in a shared reference and in `okf/` ever
+disagree, `okf/` wins.

package/docs/06-okf/02-producing-and-consuming.md

@@ -0,0 +1,46 @@
+# Producing & Consuming OKF
+
+## CLI
+
+```bash
+zeyos okf list                 # list concepts (type, id, title); --json for automation
+zeyos okf show tickets         # print a concept (bare resource name or entities/tickets)
+zeyos okf check                # validate the bundle for OKF v0.1 conformance (exit non-zero on error)
+zeyos okf export --out ./okf   # copy the shipped bundle into a directory
+zeyos okf build  --out ./okf   # synthesize a bundle from the client's schema
+```
+
+`export` copies the rich shipped bundle (with curated metrics/playbooks/notes). `build`
+synthesizes a structural bundle from the client's introspection surface — useful where the
+shipped files aren't present, or to diff against a live instance.
+
+## JavaScript client
+
+The OKF surface is exported from `@zeyos/client`:
+
+```js
+import { buildOkf, loadOkfBundle, validateOkfBundle, validateOkfFiles, OKF_VERSION } from '@zeyos/client';
+
+// Synthesize a conformant bundle from the client's generated schema (pure; browser-safe).
+const files = buildOkf();                       // { 'entities/tickets.md': '…', … }
+const { valid, errors } = validateOkfFiles(files);
+
+// Load the shipped (or any) bundle from disk (Node only).
+const bundle = await loadOkfBundle('node_modules/@zeyos/client/okf');
+bundle.version;                                 // '0.1'
+bundle.concepts['entities/tickets'].frontmatter // { type: 'ZeyOS Entity', title: 'Tickets', … }
+
+// Validate a directory or an in-memory file map.
+await validateOkfBundle('okf');
+```
+
+- `buildOkf({ schema?, services? })` — pure producer; defaults to the generated `SCHEMA`/`SERVICES`.
+- `loadOkfBundle(dir)` — Node-only reader (lazy `fs`), returns `{ version, files, concepts }`.
+- `validateOkfBundle(dirOrFiles)` / `validateOkfFiles(files)` — v0.1 conformance check.
+
+## Build-time producer
+
+In this repo, `npm run okf:build` (or `npm run generate`, which runs it alongside the client
+codegen) emits the rich bundle from `openapi/{api,dbref}.json` plus the curated content in
+`scripts/data/okf-curation.mjs`. It also injects the generated operationId table into
+`agents/shared/zeyos-entity-reference.md`. Validate with `npm run okf:check`.

package/docs/06-okf/03-keeping-fresh.md

@@ -0,0 +1,53 @@
+# Keeping OKF Fresh
+
+The OKF bundle is generated from the OpenAPI/dbref snapshots in `openapi/`. When ZeyOS
+updates its database model or API, those specs are re-exported and the bundle is
+regenerated. The design keeps that safe and observable.
+
+## What protects curation
+
+1. **Deterministic generation.** `npm run generate` runs the OKF producer alongside the
+   client codegen. Re-running with unchanged specs produces **no diff** (no timestamp churn).
+2. **Managed blocks.** Only the fenced `okf:generated` region of each entity concept is
+   rewritten; curated `# Notes`/`# Metrics` prose is spliced back unchanged. See the
+   [overview](./01-overview.md#generated-vs-curated-managed-blocks).
+3. **`source_snapshot`.** The root `index.md` frontmatter carries a content hash of the
+   schema. When the specs change, the hash changes — a staleness signal for consumers and
+   the drift gate.
+4. **`log.md` schema diff.** The producer diffs the new schema against the last snapshot and
+   appends a dated entry (added/removed fields, changed enums, new foreign keys) — an
+   OKF-native, human- and agent-readable record of *what changed when the model updated*.
+
+## The spec-refresh runbook
+
+```bash
+# 1. Replace the snapshots with the newly exported specs
+#    openapi/api.json, openapi/dbref.json
+
+# 2. Regenerate the client and the OKF bundle
+npm run generate
+
+# 3. Review the diff and the changelog
+git diff okf/ agents/shared/zeyos-entity-reference.md
+cat okf/log.md          # newest dated entry summarizes the schema changes
+
+# 4. Validate conformance + the drift gate
+npm run okf:check
+
+# 5. (Optional) enrich weak concepts — see ./04-loops.md
+npm run okf:refine -- --concept entities/<changed-entity>
+
+# 6. Commit
+git add okf agents/shared src/generated && git commit -m "Refresh schema + OKF"
+```
+
+## The drift gate (CI)
+
+`npm run okf:check` runs `test/okf.test.js`, which regenerates the bundle and asserts the
+committed content matches a fresh regen. It fails the build when:
+
+- the specs changed but `okf/` wasn't regenerated and committed;
+- someone hand-edited a generated region;
+- a concept is non-conformant, an API-backed entity lacks a concept, or a structural
+  cross-link is broken;
+- the shared reference's generated operationId table fell out of sync.

package/docs/06-okf/04-loops.md

@@ -0,0 +1,58 @@
+# Refining with Loops
+
+OKF and the skill pack are refined with the same loop machinery the agent protocol already
+uses — a measurement loop and a refinement loop that close on each other.
+
+## Measure: OKF as agent context
+
+The agent protocol (`npm run test:agent-protocol`) drives a real coding agent through
+business scenarios against a live demo instance and verifies each outcome independently. A
+`--context` axis chooses which knowledge the agent is pointed at:
+
+```bash
+# Skills only (default), OKF only, or both
+npm run test:agent-protocol -- --context okf  --scenario b03-billing-transaction-count
+npm run test:agent-protocol -- --context both --layer b
+```
+
+The bundle is exposed to the agent as `ZEYOS_OKF_ROOT` (mirroring `ZEYOS_SKILL_ROOT`). The
+loop runner sweeps the axis and reports per-context pass rates, so you can see whether
+OKF-as-context lifts accuracy and which concepts correlate with failures:
+
+```bash
+npm run test:agent-loop -- --context skills,okf,both --read-only --agents opencode
+```
+
+The scorecard tells you which **skill** and which **OKF concept** to improve.
+
+## Refine: generate → validate → judge → apply
+
+`npm run okf:refine` improves a concept's **curated** guidance (never the generated block):
+
+```bash
+# Target a concept directly, or derive weak concepts from a run's scorecard
+npm run okf:refine -- --concept entities/tickets
+npm run okf:refine -- --scorecard test/agent-protocol/results/<run>/scorecard.json
+npm run okf:refine -- --concept entities/transactions --apply   # write the accepted revision
+```
+
+Each target goes through:
+
+1. **Generate** — a proposer model drafts improved curated notes from the current concept.
+2. **Validate** — any field the proposal references must exist on the entity (checked
+   against the client schema), so the model can't invent columns or enums.
+3. **Judge** — a held-out judge model (`agentProtocol.judgeModel`, reusing `judge.mjs`)
+   approves only if the revision is more accurate and useful and contradicts no schema fact.
+4. **Apply** — with `--apply`, the accepted notes replace the curated tail; the generated
+   managed block is never touched. Without `--apply`, proposals are written for review.
+
+## The closed loop
+
+```
+specs + curation ──▶ okf/ ──▶ agent-protocol (--context okf) ──▶ scorecard
+        ▲                                                          │
+        └──────────── okf:refine (curated notes) ◀─────────────────┘
+```
+
+Drive it self-paced with the Claude Code `/loop` skill: *measure → pick the weakest concept
+→ refine → re-measure*, until pass rates plateau.

package/docs/06-okf/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Open Knowledge Format (OKF)",
+  "position": 7,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "description": "The ZeyOS knowledge bundle in Google's Open Knowledge Format — a portable, Git-native Markdown description of the data model that agents and tools consume, how to produce and keep it fresh, and how it ties into the skill-improvement loops."
+  }
+}

package/okf/concepts/counting-and-sums.md

@@ -0,0 +1,10 @@
+---
+type: Reference
+title: Counting and summing
+description: "Count server-side; there is no server-side SUM."
+tags: [query]
+---
+
+**Counts.** Use `zeyos count <resource>` (CLI) or `count: true` on the list call (client). Never `list` + array length: `zeyos list` defaults to `--limit 50`, so you get the page size, not the total (the only `--json` truncation signal is a stderr "Showing X–Y of TOTAL" hint).
+
+**Sums.** There is no server-side SUM. `list` the matching rows with the numeric field at a high `--limit` (up to 10000) and add them up client-side.

package/okf/concepts/dates-unix-seconds.md

@@ -0,0 +1,12 @@
+---
+type: Reference
+title: Dates are Unix seconds
+description: "All ZeyOS timestamps are Unix seconds; pick the indexed date field."
+tags: [query]
+---
+
+All ZeyOS dates are Unix timestamps in **seconds** (not milliseconds).
+
+- `date` — business-effective date (invoice date, message date). Use for period reporting. Indexed.
+- `lastmodified` — recent-change tracking.
+- `creationdate` — often **unindexed**; filtering a time window on it (or other unindexed date columns) can return **HTTP 503**. Prefer the indexed `date` field for windows.

package/okf/concepts/enums.md

@@ -0,0 +1,14 @@
+---
+type: Reference
+title: Common enums
+description: "Priority and ticket status enum values."
+tags: [reference]
+---
+
+Each entity concept's **Enums** section carries that entity's enums (parsed from the schema). The most-used:
+
+**Priority** (tickets/tasks): `0`=LOWEST, `1`=LOW, `2`=MEDIUM, `3`=HIGH, `4`=HIGHEST.
+
+**Ticket status**: `0`=NOT_STARTED, `1`=AWAITING_ACCEPTANCE, `2`=ACCEPTED, `3`=REJECTED, `4`=ACTIVE, `5`=INACTIVE, `6`=FEEDBACK_REQUIRED, `7`=TESTING, `8`=CANCELLED, `9`=COMPLETED, `10`=FAILED, `11`=BOOKED. Closed = IN [9, 11].
+
+**Account type**: `0`=PROSPECT, `1`=CUSTOMER, `2`=SUPPLIER, `3`=CUSTOMERANDSUPPLIER, `4`=COMPETITOR, `5`=EMPLOYEE.

package/okf/concepts/filters-vs-filter.md

@@ -0,0 +1,14 @@
+---
+type: Reference
+title: filters vs filter (the FK/GIN footgun)
+description: "Use `filters` (plural) so foreign-key fields match via their GIN/partial indexes."
+tags: [query]
+---
+
+The OpenAPI spec documents the list body field as `filter` (singular), but **`filters` (plural)** is what reliably matches GIN-indexed / partial-indexed foreign-key fields (`account`, `project`, `ticket` on related resources).
+
+- `@zeyos/client`: use `filters`.
+- `zeyos` CLI: pass `--filter '{…}'` — it serializes to `filters` internally.
+- Raw REST: the spec says `filter`; verify against the target instance.
+
+`client.schema.validate()` flags a top-level `filter` on list/count ops and suggests `filters`. Only filter on columns the resource actually has — an unknown column 400s with no hint which field was wrong (run `zeyos describe <resource>` first).

package/okf/concepts/index.md

@@ -0,0 +1,8 @@
+# Concepts
+
+* [Common enums](enums.md) - Priority and ticket status enum values.
+* [Counting and summing](counting-and-sums.md) - Count server-side; there is no server-side SUM.
+* [Dates are Unix seconds](dates-unix-seconds.md) - All ZeyOS timestamps are Unix seconds; pick the indexed date field.
+* [filters vs filter (the FK/GIN footgun)](filters-vs-filter.md) - Use `filters` (plural) so foreign-key fields match via their GIN/partial indexes.
+* [operationId ≠ table noun](operationid-vocabulary.md) - REST operationIds are CamelCase compounds; several diverge from the dbref noun.
+* [visibility: 0 (only where the column exists)](visibility-column.md) - visibility:0 hides archived rows — but only resources that have the column.