@zeyos/client 0.2.0 → 0.4.0

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.

package/okf/concepts/operationid-vocabulary.md

@@ -0,0 +1,17 @@
+---
+type: Reference
+title: operationId ≠ table noun
+description: "REST operationIds are CamelCase compounds; several diverge from the dbref noun."
+tags: [query]
+---
+
+The dbref table noun (also the REST URL path segment) is **not** the `@zeyos/client` operationId. Most follow `list<Plural>`/`get<Singular>`/… but several diverge:
+
+- `dunning` → `listDunningNotices` / `getDunningNotice`
+- `dunning2transactions` → `listDunningToTransactions`
+- `pricelists` → `listPriceLists`; `pricelists2accounts` → `listPriceListsToAccounts`
+- `mailinglists` → `listMailingLists`; `actionsteps` → `listActionSteps`
+- `categories` → `listCategorys` (sic) but `getCategory`
+- `davservers` → `listDAVServers`; `binfiles` → `listBinFiles` (list-only)
+
+Each entity concept's **Operations** section lists its real operationIds (read straight from `api.json`). `client.schema.validate()` suggests the closest operationId for an unknown name.

package/okf/concepts/visibility-column.md

@@ -0,0 +1,13 @@
+---
+type: Reference
+title: visibility: 0 (only where the column exists)
+description: "visibility:0 hides archived rows — but only resources that have the column."
+tags: [query]
+---
+
+`visibility = 0` excludes archived/deleted rows, but **only some resources have a `visibility` column**:
+
+- Have it: [tickets](/entities/tickets.md), [accounts](/entities/accounts.md), [items](/entities/items.md).
+- Do **not** have it: [transactions](/entities/transactions.md) — adding `"visibility":0` there returns an opaque **HTTP 400**.
+
+More generally, filtering on any column a resource lacks 400s with no field name. Include `visibility:0` on resources that have it unless the user wants archived records; `zeyos describe <resource>` tells you whether the column exists.

package/okf/entities/accounts.md

@@ -0,0 +1,82 @@
+---
+type: ZeyOS Entity
+title: Accounts
+description: Customer, supplier, prospect, or employee master records.
+resource: zeyos://api/accounts
+tags: [crm, generated]
+api_backed: true
+list_operation: listAccounts
+visibility_column: true
+---
+
+<!-- okf:generated:start — rewritten by scripts/generate-okf.mjs; do not edit by hand -->
+# Schema
+
+| Column | Type | Nullable | Default | Indexed | FK |
+|---|---|---|---|---|---|
+| `ID` | integer | no | — | yes | — |
+| `fork` | integer | yes | — | yes | [forks](/entities/forks.md) |
+| `ownergroup` | integer | yes | — | yes | [groups](/entities/groups.md) |
+| `creator` | integer | yes | — | — | — |
+| `assigneduser` | integer | yes | — | yes | [users](/entities/users.md) |
+| `creationdate` | bigint | no | `date_part('epoch', now())` | — | — |
+| `lastmodified` | bigint | no | `date_part('epoch', now())` | — | — |
+| `contact` | integer | yes | — | yes | [contacts](/entities/contacts.md) |
+| `visibility` | smallint | no | `0` | — | — |
+| `lastname` | text | no | `''` | yes | — |
+| `firstname` | text | no | `''` | yes | — |
+| `type` | smallint | no | `0` | — | — |
+| `customernum` | text | no | `''` | yes | — |
+| `suppliernum` | text | no | `''` | yes | — |
+| `taxid` | text | no | `''` | — | — |
+| `currency` | character varying(3) | no | — | — | — |
+| `locked` | smallint | no | `0` | — | — |
+| `excludetax` | smallint | no | `0` | — | — |
+| `description` | text | no | `''` | — | — |
+
+# Foreign Keys
+
+- `fork` → [forks](/entities/forks.md) (`forks.ID`)
+- `ownergroup` → [groups](/entities/groups.md) (`groups.ID`)
+- `assigneduser` → [users](/entities/users.md) (`users.ID`)
+- `contact` → [contacts](/entities/contacts.md) (`contacts.ID`)
+
+# Enums
+
+### `visibility`
+
+`0` = REGULAR · `1` = ARCHIVED · `2` = DELETED
+
+### `type`
+
+`0` = PROSPECT · `1` = CUSTOMER · `2` = SUPPLIER · `3` = CUSTOMERANDSUPPLIER · `4` = COMPETITOR · `5` = EMPLOYEE
+
+# Indexes
+
+- `fk_accounts_assigneduser` — gin, partial on `assigneduser`
+- `fk_accounts_contact` — btree, partial on `contact`
+- `fk_accounts_fork` — gin, partial on `fork`
+- `fk_accounts_ownergroup` — gin on `ownergroup`
+- `i_accounts_lastname_firstname` — btree on `lastname, firstname`
+- `i_accounts_nofork` — gin, partial on `fork`
+- `i_accounts_noowner` — gin, partial on `ownergroup`
+- `s_accounts_customernum` — gin, partial on `customernum`
+- `s_accounts_firstname` — gin, partial on `firstname`
+- `s_accounts_lastname` — gin, partial on `lastname`
+- `s_accounts_suppliernum` — gin, partial on `suppliernum`
+
+> Partial/GIN indexes back the `filters` (plural) query form for foreign-key fields. See [filters-vs-filter](/concepts/filters-vs-filter.md).
+
+# Operations
+
+- list: `listAccounts`
+- get: `getAccount`
+- create: `createAccount`
+- update: `updateAccount`
+- delete: `deleteAccount`
+- exists: `existsAccount`
+<!-- okf:generated:end -->
+
+# Notes
+
+No `name` column — use `lastname` + `firstname`. `type`: 0=PROSPECT,1=CUSTOMER,2=SUPPLIER,3=CUSTOMERANDSUPPLIER,4=COMPETITOR,5=EMPLOYEE. `createAccount` REQUIRES `currency` (NOT NULL, no default) or it 500s.

package/okf/entities/actionsteps.md

@@ -0,0 +1,84 @@
+---
+type: ZeyOS Entity
+title: Action Steps
+description: Cross-record follow-up work items with assignee, due date, status, and effort.
+resource: zeyos://api/actionsteps
+tags: [work, generated]
+api_backed: true
+list_operation: listActionSteps
+visibility_column: false
+---
+
+<!-- okf:generated:start — rewritten by scripts/generate-okf.mjs; do not edit by hand -->
+# Schema
+
+| Column | Type | Nullable | Default | Indexed | FK |
+|---|---|---|---|---|---|
+| `ID` | integer | no | — | yes | — |
+| `fork` | integer | yes | — | yes | [forks](/entities/forks.md) |
+| `owneruser` | integer | yes | — | yes | [users](/entities/users.md) |
+| `ownergroup` | integer | yes | — | yes | [groups](/entities/groups.md) |
+| `creator` | integer | yes | — | — | — |
+| `assigneduser` | integer | yes | — | yes | [users](/entities/users.md) |
+| `creationdate` | bigint | no | `date_part('epoch', now())` | — | — |
+| `lastmodified` | bigint | no | `date_part('epoch', now())` | — | — |
+| `task` | integer | yes | — | yes | [tasks](/entities/tasks.md) |
+| `ticket` | integer | yes | — | yes | [tickets](/entities/tickets.md) |
+| `account` | integer | yes | — | yes | [accounts](/entities/accounts.md) |
+| `transaction` | integer | yes | — | yes | [transactions](/entities/transactions.md) |
+| `name` | text | no | — | yes | — |
+| `actionnum` | text | no | `''` | yes | — |
+| `date` | bigint | no | `date_part('epoch', now())` | yes | — |
+| `duedate` | bigint | yes | — | — | — |
+| `status` | smallint | no | `0` | — | — |
+| `effort` | integer | no | `0` | — | — |
+| `description` | text | no | `''` | — | — |
+
+# Foreign Keys
+
+- `fork` → [forks](/entities/forks.md) (`forks.ID`)
+- `owneruser` → [users](/entities/users.md) (`users.ID`)
+- `ownergroup` → [groups](/entities/groups.md) (`groups.ID`)
+- `assigneduser` → [users](/entities/users.md) (`users.ID`)
+- `task` → [tasks](/entities/tasks.md) (`tasks.ID`)
+- `ticket` → [tickets](/entities/tickets.md) (`tickets.ID`)
+- `account` → [accounts](/entities/accounts.md) (`accounts.ID`)
+- `transaction` → [transactions](/entities/transactions.md) (`transactions.ID`)
+
+# Enums
+
+### `status`
+
+`0` = DRAFT · `1` = COMPLETED · `2` = CANCELLED · `3` = BOOKED
+
+# Indexes
+
+- `fk_actionsteps_account` — btree, partial on `account`
+- `fk_actionsteps_assigneduser` — gin, partial on `assigneduser`
+- `fk_actionsteps_fork` — gin, partial on `fork`
+- `fk_actionsteps_ownergroup` — gin, partial on `ownergroup`
+- `fk_actionsteps_owneruser` — gin, partial on `owneruser`
+- `fk_actionsteps_task` — btree, partial on `task`
+- `fk_actionsteps_ticket` — btree, partial on `ticket`
+- `fk_actionsteps_transaction` — btree, partial on `transaction`
+- `i_actionsteps_date` — btree on `date`
+- `i_actionsteps_nofork` — gin, partial on `fork`
+- `i_actionsteps_noowner` — gin, partial on `ownergroup`
+- `s_actionsteps_actionnum` — gin, partial on `actionnum`
+- `s_actionsteps_name` — gin on `name`
+
+> Partial/GIN indexes back the `filters` (plural) query form for foreign-key fields. See [filters-vs-filter](/concepts/filters-vs-filter.md).
+
+# Operations
+
+- list: `listActionSteps`
+- get: `getActionStep`
+- create: `createActionStep`
+- update: `updateActionStep`
+- delete: `deleteActionStep`
+- exists: `existsActionStep`
+<!-- okf:generated:end -->
+
+# Notes
+
+Record-bound follow-ups (linked to a task, ticket, or account, with optional transaction). Do not inflate into full project tasks.

package/okf/entities/addresses.md

@@ -0,0 +1,50 @@
+---
+type: ZeyOS Entity
+title: Addresses
+description: Additional address records linked to accounts or contacts.
+resource: zeyos://api/addresses
+tags: [crm, generated]
+api_backed: true
+list_operation: listAddresses
+visibility_column: false
+---
+
+<!-- okf:generated:start — rewritten by scripts/generate-okf.mjs; do not edit by hand -->
+# Schema
+
+| Column | Type | Nullable | Default | Indexed | FK |
+|---|---|---|---|---|---|
+| `ID` | bigint | no | — | yes | — |
+| `creator` | integer | yes | — | — | — |
+| `creationdate` | bigint | no | `date_part('epoch', now())` | — | — |
+| `lastmodified` | bigint | no | `date_part('epoch', now())` | — | — |
+| `account` | integer | no | — | yes | [accounts](/entities/accounts.md) |
+| `contact` | integer | no | — | yes | [contacts](/entities/contacts.md) |
+| `type` | smallint | no | `0` | yes | — |
+| `default` | smallint | no | `0` | yes | — |
+
+# Foreign Keys
+
+- `account` → [accounts](/entities/accounts.md) (`accounts.ID`)
+- `contact` → [contacts](/entities/contacts.md) (`contacts.ID`)
+
+# Enums
+
+### `type`
+
+`0` = BILLING_SHIPPING · `1` = BILLING_BILLING · `2` = PROCUREMENT_SHIPPING · `3` = PROCUREMENT_BILLING · `4` = COLLECTION · `5` = BILLING_SELLER · `6` = PROCUREMENT_SELLER
+
+# Indexes
+
+- `fk_addresses_contact` — btree on `contact`
+- `u_addresses_account_contact_type` — btree, unique on `account, contact, type, +default`
+
+# Operations
+
+- list: `listAddresses`
+- get: `getAddress`
+- create: `createAddress`
+- update: `updateAddress`
+- delete: `deleteAddress`
+- exists: `existsAddress`
+<!-- okf:generated:end -->

package/okf/entities/applicationassets.md

@@ -0,0 +1,43 @@
+---
+type: ZeyOS Entity
+title: Application Assets
+description: Assets linked to an application.
+resource: zeyos://api/applicationassets
+tags: [platform, generated]
+api_backed: true
+list_operation: listApplicationAssets
+visibility_column: false
+---
+
+<!-- okf:generated:start — rewritten by scripts/generate-okf.mjs; do not edit by hand -->
+# Schema
+
+| Column | Type | Nullable | Default | Indexed | FK |
+|---|---|---|---|---|---|
+| `ID` | bigint | no | — | yes | — |
+| `creator` | integer | yes | — | — | — |
+| `creationdate` | bigint | no | `EXTRACT(epoch FROM now())` | — | — |
+| `lastmodified` | bigint | no | `EXTRACT(epoch FROM now())` | — | — |
+| `application` | integer | no | — | yes | [applications](/entities/applications.md) |
+| `binfile` | integer | yes | — | yes | [binfiles](/entities/binfiles.md) |
+| `filename` | text | no | — | yes | — |
+| `mimetype` | text | no | `'application/octet-stream'` | — | — |
+
+# Foreign Keys
+
+- `application` → [applications](/entities/applications.md) (`applications.ID`)
+- `binfile` → [binfiles](/entities/binfiles.md) (`binfiles.ID`)
+
+# Indexes
+
+- `fk_applicationassets_binfile` — btree, partial on `binfile`
+- `u_applicationassets_application_filename` — btree, unique on `application, filename`
+
+> Partial/GIN indexes back the `filters` (plural) query form for foreign-key fields. See [filters-vs-filter](/concepts/filters-vs-filter.md).
+
+# Operations
+
+- list: `listApplicationAssets`
+- get: `getApplicationAsset`
+- exists: `existsApplicationAsset`
+<!-- okf:generated:end -->

package/okf/entities/applications.md

@@ -0,0 +1,62 @@
+---
+type: ZeyOS Entity
+title: Applications
+description: Application definitions.
+resource: zeyos://api/applications
+tags: [platform, generated]
+api_backed: true
+list_operation: listApplications
+visibility_column: false
+---
+
+<!-- okf:generated:start — rewritten by scripts/generate-okf.mjs; do not edit by hand -->
+# Schema
+
+| Column | Type | Nullable | Default | Indexed | FK |
+|---|---|---|---|---|---|
+| `ID` | integer | no | — | yes | — |
+| `creator` | integer | yes | — | — | — |
+| `creationdate` | bigint | no | `date_part('epoch', now())` | — | — |
+| `lastmodified` | bigint | no | `date_part('epoch', now())` | — | — |
+| `activity` | smallint | no | `0` | — | — |
+| `readmebinfile` | integer | yes | — | — | [binfiles](/entities/binfiles.md) |
+| `name` | text | no | — | yes | — |
+| `identifier` | character varying(200) | no | — | yes | — |
+| `vendor` | text | no | `''` | — | — |
+| `restricted` | smallint | no | `0` | — | — |
+| `callbackurls` | text[] | yes | — | — | — |
+| `settingscodebinfile` | integer | yes | — | yes | [binfiles](/entities/binfiles.md) |
+| `usersettingscodebinfile` | integer | yes | — | yes | [binfiles](/entities/binfiles.md) |
+| `secret` | bytea | yes | — | yes | — |
+| `defaultsettings` | json | yes | — | — | — |
+| `settings` | json | yes | — | — | — |
+
+# Foreign Keys
+
+- `readmebinfile` → [binfiles](/entities/binfiles.md) (`binfiles.ID`)
+- `settingscodebinfile` → [binfiles](/entities/binfiles.md) (`binfiles.ID`)
+- `usersettingscodebinfile` → [binfiles](/entities/binfiles.md) (`binfiles.ID`)
+
+# Enums
+
+### `activity`
+
+`0` = ACTIVE · `1` = DEACTIVATED · `2` = DELETED
+
+# Indexes
+
+- `fk_applications_settingscodebinfile` — btree, partial on `settingscodebinfile`
+- `fk_applications_usersettingscodebinfile` — btree, partial on `usersettingscodebinfile`
+- `s_applications_identifier` — gin on `identifier`
+- `s_applications_name` — gin on `name`
+- `u_applications_identifier` — btree, unique on `identifier`
+- `u_applications_secret` — btree, unique, partial on `secret`
+
+> Partial/GIN indexes back the `filters` (plural) query form for foreign-key fields. See [filters-vs-filter](/concepts/filters-vs-filter.md).
+
+# Operations
+
+- list: `listApplications`
+- get: `getApplication`
+- exists: `existsApplication`
+<!-- okf:generated:end -->