@zeyos/client 0.3.0 → 0.5.0

package/agents/zeyos-data-quality-and-governance/references/workflows.md

@@ -0,0 +1,51 @@
+# Data Quality and Governance Workflows
+
+## Duplicate-account detection (deterministic scoring)
+
+1. Pull the active population:
+
+   ```bash
+   zeyos list accounts --filter '{"type":1,"visibility":0}' \
+     --fields ID,customernum,lastname,firstname --limit 10000 --json
+   ```
+
+2. Normalize comparison keys (lowercase, trim, collapse whitespace) but keep originals.
+3. Score candidate pairs with a published, deterministic policy:
+
+   | Evidence | Weight | Confidence |
+   |---|---|---|
+   | Exact `customernum` | 1.0 | high |
+   | Exact normalized email (via `contacts`) | 0.9 | high |
+   | Exact normalized name + address | 0.8 | high |
+   | Near name only (edit distance) | 0.4 | low |
+
+4. Sort pairs by score descending; emit `{accountA, accountB, score, reasons, confidence}`.
+   A clearly different account is not a candidate. Shared generic email domains and similar
+   names are never conclusive on their own.
+
+## Completeness gaps (anti-join)
+
+"Customers missing a billing address": list customers, list `addresses` of `type: 1`
+(billing), keep customers with no matching `account`. `addresses` has **no** `visibility`
+column — do not filter it. State whether you treat empty string, null and missing the same
+(R-020); by default they are distinct.
+
+## Remediation is a preview, not an action
+
+A "clean up duplicates" request returns:
+
+```json
+{ "executed": false,
+  "candidates": [ { "accountA": 1, "accountB": 2 } ],
+  "proposedActions": [ { "accountId": 2, "action": "archive (needs human review)" } ] }
+```
+
+Never delete, archive or merge from this analysis (R-009, R-011, R-023). Each action is a
+human decision on an exact ID. Re-query only after an approved, bounded change.
+
+## Common failure modes
+
+- Treating a fuzzy name match as a confirmed duplicate.
+- Collapsing null / empty / zero into one bucket without saying so.
+- Executing a bulk archive/delete from a "clean up" instruction.
+- Filtering `visibility` on `addresses` (no such column → HTTP 400).

package/agents/zeyos-document-and-approval/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: zeyos-document-and-approval
+description: Find formal ZeyOS documents, judge draft/final/obsolete status, run approval and finalization gates, and compare notes against formal SOPs. Use when status transitions, approval authority, version choice or formal file artifacts matter ("find the current approved onboarding SOP", "which contracts await approval", "make document 812 final", "compare the draft with the final version"). For lightweight note retrieval use zeyos-notes-and-sops.
+---
+
+# ZeyOS Document and Approval
+
+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. See the OKF `concepts/official-versus-latest` concept and the `playbooks/document-approval` playbook.
+
+> **Status, not freshness, decides authority.** The newest artifact is not necessarily the
+> current official one. Retrieve content before claiming what a document says.
+
+Primary entities: `documents` (`listDocuments`, `getDocument`, `createDocument`, `updateDocument`), `notes` (`listNotes`, `getNote`), `binfiles` (`listBinFiles`), `files`, plus `users`/`groups` for approval context. Document `status`: 0 DRAFT, 1 FEEDBACKREQUIRED, 2 INREVISION, 3 AWAITINGAPPROVAL, 4 FINAL, 5 OBSOLETE.
+
+Typical prompts:
+
+- "Find the current approved onboarding SOP."
+- "Which contracts are awaiting approval?"
+- "Compare the draft with the final version."
+- "Make document 812 final."
+
+## Workflow
+
+1. Search formal `documents` first for "official", "approved", "final" or "current".
+2. Select by **status plus freshness** — a FINAL document outranks a newer OBSOLETE one and a draft note (R-018).
+3. Retrieve binary/file content (`binfile`/`files`) before claiming its contents.
+4. Keep `notes` (lightweight) and `documents` (formal) as separate sources; do not silently merge conflicting sources (surface the conflict, name the authoritative source).
+5. For finalization/approval: fetch the exact ID + current status, show a preview and any naming conflict, require exact confirmation, `updateDocument` one ID, then re-read and report old/new status (R-005, R-006, R-011).
+
+## Routing boundaries
+
+- Note-centric retrieval/summarization → `zeyos-notes-and-sops`.
+- Use this skill when status transitions, approval authority, version choice or formal files matter.
+
+## Safety
+
+- FINAL, APPROVED, OBSOLETE and cancellation transitions are high impact (R-011).
+- Never approve on behalf of an unidentified user/group.
+- Never bulk-finalize or bulk-obsolete documents (R-009).
+- Never overwrite a binary file without an explicit target and confirmation.
+- Preserve provenance and revision identifiers in summaries.

package/agents/zeyos-document-and-approval/references/workflows.md

@@ -0,0 +1,43 @@
+# Document and Approval Workflows
+
+## Select the current official artifact
+
+1. Query formal `documents` matching the topic; read `status`, `name`, `documentnum`, `filename`.
+
+   ```bash
+   zeyos list documents --filter '{"visibility":0,"name":{"~~*":"onboarding%"}}' \
+     --fields ID,name,status,filename,documentnum --limit 100 --json
+   ```
+
+2. Rank by authority, not date: prefer `status = 4` (FINAL). A newer `status = 5`
+   (OBSOLETE) does **not** win, and a draft `note` is only fallback context (R-018).
+3. State the selection reason (which status, why it outranks the alternatives).
+
+## Compare a note against a formal SOP
+
+Retrieve the actual text of both (`notes.text`; `documents.description`/binary content).
+Report agreements and conflicts explicitly; never synthesize a single answer that hides a
+contradiction. The formal FINAL document is the authoritative source.
+
+## Finalization / approval gate
+
+```bash
+# 1. Fetch exact target + current status
+zeyos get document <id> --json
+# 2. Preview the change (no write) and surface any same-name conflict
+zeyos update document <id> --query --status 4
+# 3. Only after explicit confirmation of the exact ID:
+zeyos update document <id> --status 4
+# 4. Re-read and report old/new status
+zeyos get document <id> --fields ID,name,status --json
+```
+
+Update exactly one ID. Never fuzzy-match a name to a set of documents and finalize them in
+bulk (R-009, R-011). Leave similarly-named documents untouched.
+
+## Common failure modes
+
+- Picking the newest artifact instead of the FINAL one.
+- Claiming document contents without retrieving the file/binary.
+- Bulk-finalizing by fuzzy name match.
+- Approving without identifying the approver / authority.

package/agents/zeyos-procurement-and-supplier-performance/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: zeyos-procurement-and-supplier-performance
+description: Compare suppliers, analyze procurement orders/deliveries/invoices, lead times, price variance and reorder worklists in ZeyOS. Use for "which supplier is best for 20 units of item ABC", "which purchase orders are late", "compare supplier delivery performance", "where did procurement prices exceed the order". Read-only analysis — never place, book, cancel or transmit a procurement transaction.
+---
+
+# ZeyOS Procurement and Supplier Performance
+
+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. See the OKF `playbooks/supplier-scorecard` playbook and `metrics/supplier-delivery-performance` metric.
+
+> **Keep ordered, delivered and invoiced quantities/values distinct**, and state the
+> ranking policy before you rank. Analysis is read-only.
+
+Primary entities: `transactions` types **5 PROCUREMENT_REQUEST, 6 ORDER, 7 DELIVERY, 8 INVOICE, 9 CREDIT** (`listTransactions`), `suppliers` (item↔supplier links: `listSuppliers`), `items`, `accounts` (the supplier), `stocktransactions`, `storages`, `payments`, and `contracts` where supplier agreements matter. `transactions` has **no** `visibility` column.
+
+Typical prompts:
+
+- "Which supplier is best for 20 units of item ABC?"
+- "Which purchase orders are late?"
+- "Compare supplier delivery performance."
+- "Where did procurement prices exceed the order?"
+
+## Workflow
+
+1. Resolve the item and the supplier `accounts` (type 2 SUPPLIER).
+2. For sourcing decisions, read `suppliers` links: `price`, `minamount`, `deliverytime`, `stock`.
+3. Apply the order quantity: a supplier is eligible only if `minamount <= quantity` — never hide a minimum-quantity constraint (R-003).
+4. State the ranking policy first (e.g. eligible, then price ascending, then delivery time), then rank.
+5. For performance, keep ordered (type 6), delivered (type 7) and invoiced (type 8) values separate; compute price variance as invoiced − ordered.
+6. Compute only over a declared time window and one currency (R-014, R-019). Exclude cancelled records by documented status policy.
+7. Label reorder advice as heuristic unless a formal stock policy exists.
+
+## Safety
+
+- Never place, approve, book, cancel or transmit a procurement transaction automatically (R-010, R-011).
+- Never change supplier master data or price lists from an analytical request.
+- Any future write workflow requires exact supplier, item, quantity, currency and confirmation.

package/agents/zeyos-procurement-and-supplier-performance/references/workflows.md

@@ -0,0 +1,46 @@
+# Procurement and Supplier Performance Workflows
+
+## Procurement transaction types
+
+`transactions.type`: 5 PROCUREMENT_REQUEST, 6 PROCUREMENT_ORDER, 7 PROCUREMENT_DELIVERY,
+8 PROCUREMENT_INVOICE, 9 PROCUREMENT_CREDIT. (Billing types 0–4 are a different domain.)
+`transactions` has **no** `visibility` column — do not add `"visibility":0`.
+
+## Supplier comparison for an order quantity
+
+1. Resolve the item, then read its supplier links:
+
+   ```bash
+   zeyos list suppliers --filter '{"item":<itemId>}' \
+     --fields ID,account,price,minamount,deliverytime,stock --limit 1000 --json
+   ```
+
+2. Resolve each `account` to a supplier name.
+3. Eligibility: `minamount <= orderQuantity`. State eligibility explicitly — never drop a
+   supplier silently because of its minimum.
+4. Ranking policy (declare before ranking): eligible first, then `price` ascending, then
+   `deliverytime` ascending. Report `rank` and `eligible` per option.
+
+## Supplier scorecard over a period
+
+Group procurement `transactions` by supplier `account` within a declared window + currency:
+
+- `ordered_value` = Σ `netamount` where type 6
+- `invoiced_value` = Σ `netamount` where type 8
+- `price_variance` = invoiced_value − ordered_value
+- delivery timing from type 7 dates vs the order `duedate` (on-time when delivered by duedate)
+
+Keep all values in one currency (R-019); exclude cancelled records per documented policy.
+
+## Reorder advice
+
+Label reorder suggestions as heuristic unless the instance has a formal stock policy
+(min/max levels). Combine `stocktransactions` net-booked stock by `storages` with supplier
+`deliverytime` to flag at-risk items — but present it as advice, not an action.
+
+## Common failure modes
+
+- Mixing billing types (0–4) with procurement types (5–9).
+- Hiding a minimum-order-quantity constraint when ranking.
+- Conflating ordered, delivered and invoiced values.
+- Summing across currencies.

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

@@ -15,6 +15,7 @@ Typical prompts:
 - "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."
+- "Give me a summary of logged ticket time from the last four weeks."
 - "Actually make that 90 minutes, not 60." / "Move that time to ticket 813."
 
 ## Two jobs
@@ -44,5 +45,6 @@ Interactivity here means **act first, then ask only when real data is ambiguous*
 ## Output discipline
 
 - For "my work": state the resolved user and the open-status definition you used, then the list.
+- For ticket time summaries: include both actionsteps directly linked by `actionstep.ticket` and actionsteps linked by `actionstep.task` where `task.ticket` is the summarized ticket; dedupe by actionstep ID before summing.
 - 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.

package/agents/zeyos-time-tracking/references/workflows.md

@@ -17,6 +17,7 @@ See [../../shared/zeyos-entity-reference.md](../../shared/zeyos-entity-reference
 
 - **Time entries are `actionsteps`.** The `effort` field is **minutes** (integer). There is no separate time-entry resource.
 - **Actionstep foreign keys:** `task`, `ticket`, `account`, `transaction` — plus `assigneduser`, `date`, `duedate`, `status`, `effort`. **There is no `project` FK on an actionstep**, so project-level time attaches through a ticket/task in that project, or to the project's `account`.
+- **Ticket time rollups cross the task layer.** For "logged ticket time", count actionsteps with `ticket = <ticketId>` and actionsteps with `task = <taskId>` where that task has `ticket = <ticketId>`. Always dedupe by actionstep `ID` before summing in case a row carries both FKs.
 - **Actionstep status:** `0` DRAFT · `1` COMPLETED · `2` CANCELLED · `3` BOOKED. Log already-done work as **COMPLETED (1)**; use **BOOKED (3)** only when the instance treats booked effort as the billed/locked record and the user says so.
 - **Ticket/task 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. Treat **open/current = status `!IN [8,9,10,11]`** (exclude cancelled/completed/failed/booked). State this definition in the answer; the user can narrow it (e.g. only `4` ACTIVE).
 - **Foreign keys per resource:** `tickets` carry `account`, `project`, `assigneduser`; `tasks` carry `ticket`, `project`, `assigneduser` (no `account` — reach the account through the task's ticket/project); `projects` carry `account`, `assigneduser`; `accounts` carry `lastname`, `firstname`, `customernum` (no `name` field).
@@ -195,6 +196,72 @@ const totalMinutes = rows.reduce((sum, r) => sum + (Number(r.effort) || 0), 0);
 
 4. Sum `effort` as minutes; convert to hours only if asked. To break down "by account/ticket", group the rows by the FK and resolve the account/ticket names with a second query. Report the total and the breakdown, and state the window and status set you used.
 
+## Pattern: "Give me a summary of logged ticket time from the last four weeks"
+
+Use this whenever the user asks for ticket time, ticket hours, support time by ticket, or a ticket-level timesheet summary. A time entry can be attached directly to a ticket or indirectly to a task that belongs to a ticket; both are ticket time.
+
+1. Resolve the date window to Unix seconds and count only `actionsteps.status IN [1,3]` unless the user explicitly asks for drafts/open follow-ups.
+2. If the user named a specific ticket, resolve it first, then query:
+
+   ```bash
+   # direct ticket time
+   zeyos list actionsteps \
+     --fields ID,name,effort,date,status,ticket,task,assigneduser \
+     --filter '{"ticket":<ticketId>,"status":{"IN":[1,3]},"date":{">=":<start>,"<=":<end>}}' \
+     --limit 10000 --json
+
+   # tasks that belong to the ticket; do not filter task status for historical time
+   zeyos list tasks \
+     --fields ID,tasknum,name,ticket \
+     --filter '{"ticket":<ticketId>}' \
+     --limit 10000 --json
+
+   # time logged on those tasks
+   zeyos list actionsteps \
+     --fields ID,name,effort,date,status,ticket,task,assigneduser \
+     --filter '{"task":{"IN":[<taskIds>]},"status":{"IN":[1,3]},"date":{">=":<start>,"<=":<end>}}' \
+     --limit 10000 --json
+   ```
+
+3. If the user asks for all ticket time in a period, list actionsteps in the window with `ticket` and `task`, then resolve every referenced task to `task.ticket` and group by the resulting ticket ID. Page through results if the window is large.
+4. Build each actionstep's ticket attribution:
+   - direct row: `actionstep.ticket`
+   - task row: `taskById[actionstep.task].ticket`
+   - both present: count the actionstep once; prefer the direct ticket if it conflicts and call out the conflict
+   - neither present: keep it out of the ticket-time total unless reporting an "unassigned/general time" bucket
+5. Dedupe by actionstep `ID`, sum `effort` in minutes, and resolve ticket labels (`ticketnum`, `name`, `account.lastname`) for the summary.
+
+Client shape for a specific ticket:
+
+```js
+const [directRows, taskRows] = await Promise.all([
+  client.api.listActionSteps({
+    fields: ['ID', 'name', 'effort', 'date', 'status', 'ticket', 'task', 'assigneduser'],
+    filters: { ticket: ticketId, status: { IN: [1, 3] }, date: { '>=': start, '<=': end } },
+    limit: 10000,
+  }),
+  client.api.listTasks({
+    fields: ['ID', 'tasknum', 'name', 'ticket'],
+    filters: { ticket: ticketId },
+    limit: 10000,
+  }),
+]);
+
+const taskIds = taskRows.map((task) => task.ID);
+const taskTimeRows = taskIds.length
+  ? await client.api.listActionSteps({
+      fields: ['ID', 'name', 'effort', 'date', 'status', 'ticket', 'task', 'assigneduser'],
+      filters: { task: { IN: taskIds }, status: { IN: [1, 3] }, date: { '>=': start, '<=': end } },
+      limit: 10000,
+    })
+  : [];
+
+const rowsById = new Map();
+for (const row of [...directRows, ...taskTimeRows]) rowsById.set(String(row.ID), row);
+const totalMinutes = [...rowsById.values()]
+  .reduce((sum, row) => sum + (Number(row.effort) || 0), 0);
+```
+
 ## Pattern: Adjust or correct a logged entry
 
 For "actually that was 90 minutes, not 60" or "move that time to ticket 813" right after logging — or any later correction.
@@ -226,5 +293,6 @@ Only correct entries the user pointed to (by id, or one you just created in this
 - Filtering `visibility` on `transactions` (no such column -> HTTP 400).
 - Putting effort in hours — `effort` is **minutes**.
 - Trying to set a `project` FK on an actionstep — it does not exist; anchor on a ticket/task/account instead.
+- Summing only `actionstep.ticket` for ticket time — time logged on tasks with `task.ticket = <ticketId>` belongs in the ticket total too.
 - Treating BOOKED (status 11) tickets as current — they are terminal; the open set excludes `[8,9,10,11]`.
 - Logging time against a user id you guessed — always read `sub` from `whoami`.

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

@@ -30,9 +30,10 @@ Typical prompts:
 4. Follow relationships only after the primary record set is clear.
 5. Treat "worked on" as a proxy unless actionstep effort/date evidence exists. Assignment and timestamps show involvement; `actionsteps.effort` on `COMPLETED` or `BOOKED` records is stronger time-entry evidence.
 6. Distinguish direct project assignment from project inference through linked tickets.
-7. When the question is really about account or transaction follow-up, check `actionsteps` before inventing a new task.
-8. For mutations, preview the affected record first and update with an explicit PATCH body.
-9. Escalate from the CLI to `@zeyos/client` if the workflow needs unsupported joins, additional request control, or correlation across multiple list responses.
+7. For logged ticket-time summaries, include actionsteps directly linked to the ticket and actionsteps linked to tasks whose `task.ticket` is that ticket; dedupe actionstep IDs before summing.
+8. When the question is really about account or transaction follow-up, check `actionsteps` before inventing a new task.
+9. For mutations, preview the affected record first and update with an explicit PATCH body.
+10. Escalate from the CLI to `@zeyos/client` if the workflow needs unsupported joins, additional request control, or correlation across multiple list responses.
 
 ## Destructive Operations
 

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

@@ -160,6 +160,7 @@ zeyos count actionsteps --filter '{"ticket":812,"status":0}' --json
 Use this for prompts like:
 
 - "How many minutes were booked on ticket 812 last week?"
+- "Give me a summary of logged ticket time from the last four weeks."
 - "Summarize completed actionstep effort for this account."
 - "Which user logged effort against this project?"
 
@@ -169,7 +170,44 @@ Recommended approach:
 2. Query `actionsteps` with fields `ID`, `date`, `status`, `effort`, and the relevant FK (`ticket`, `task`, `account`, or `transaction`).
 3. Include statuses `1` COMPLETED and `3` BOOKED for time-entry totals unless the user asks for drafts/open follow-ups.
 4. Sum `effort` as minutes; convert to hours only if the user asked for hours.
-5. Keep task/ticket assignment separate from effort totals.
+5. For ticket-level totals, roll task time up to the ticket:
+   - direct ticket time is `actionsteps.ticket = <ticketId>`
+   - task ticket time is `actionsteps.task = <taskId>` where `tasks.ticket = <ticketId>`
+   - fetch tasks by `ticket` for a named ticket, or resolve every referenced `actionstep.task` to `task.ticket` for a period-wide ticket summary
+   - do not filter tasks by status when resolving historical time; a completed task can still carry valid logged time
+   - dedupe by `actionsteps.ID` before summing in case a row has both `ticket` and `task`
+6. Keep task/ticket assignment separate from effort totals.
+
+Ticket-specific client example:
+
+```js
+const [directRows, tasks] = await Promise.all([
+  client.api.listActionSteps({
+    fields: ['ID', 'date', 'status', 'effort', 'ticket', 'task', 'assigneduser'],
+    filters: { ticket: ticketId, status: { IN: [1, 3] }, date: { '>=': start, '<=': end } },
+    limit: 10000,
+  }),
+  client.api.listTasks({
+    fields: ['ID', 'ticket', 'name'],
+    filters: { ticket: ticketId },
+    limit: 10000,
+  }),
+]);
+
+const taskIds = tasks.map((task) => task.ID);
+const taskRows = taskIds.length
+  ? await client.api.listActionSteps({
+      fields: ['ID', 'date', 'status', 'effort', 'ticket', 'task', 'assigneduser'],
+      filters: { task: { IN: taskIds }, status: { IN: [1, 3] }, date: { '>=': start, '<=': end } },
+      limit: 10000,
+    })
+  : [];
+
+const uniqueRows = new Map();
+for (const row of [...directRows, ...taskRows]) uniqueRows.set(String(row.ID), row);
+const totalMinutes = [...uniqueRows.values()]
+  .reduce((sum, row) => sum + (Number(row.effort) || 0), 0);
+```
 
 ## Pattern: Create Follow-Up Work
 

package/docs/03-cli/02-commands.md

@@ -78,7 +78,7 @@ zeyos logout [--global]
 **Examples:**
 
 ```bash
-zeyos logout          # Clear local .zeyos/auth.json tokens
+zeyos logout          # Clear local .zeyos/auth.json credentials
 zeyos logout --global # Clear ~/.config/zeyos/credentials.json tokens
 ```
 
@@ -100,6 +100,11 @@ zeyos whoami --json
 zeyos whoami --show-token --json   # explicitly include the current access token
 ```
 
+If the stored refresh token is invalid or expired, interactive text-mode `whoami`
+prints the credential source and asks whether to re-authenticate immediately. In
+`--json`, `--yaml`, or non-interactive runs, it exits with the same diagnostic and
+prints the matching `zeyos login --force` command instead of prompting.
+
 ---
 
 ## profile
@@ -116,12 +121,13 @@ zeyos profile <list|current|use|add|remove> [options]
 | `profile current` | Show which profile resolves right now, and why (flag/env/pin/active) |
 | `profile use <name>` | Make `<name>` the active profile (global) |
 | `profile use <name> --local` | Pin `<name>` to the current project (`.zeyos/profile`) |
-| `profile add <name> [opts]` | Create/update a profile (`--base-url`, `--client-id`, `--secret`, or `--from-current`) |
+| `profile add [<name>] [opts]` | Create/update a profile; prompts for missing values when run without options |
 | `profile remove <name>` | Delete a profile |
 
 **Examples:**
 
 ```bash
+zeyos profile add                         # prompt for name, URL, app ID, secret
 zeyos profile add dev  --base-url https://zeyos.cms-it.de/dev
 zeyos profile add prod --from-current        # snapshot current credentials
 zeyos login --profile prod                   # authenticate into & activate a profile
@@ -481,6 +487,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/03-cli/03-configuration.md

@@ -33,6 +33,7 @@ Profiles let you store several ZeyOS instances (e.g. `dev`, `prod`, `client-x`)
 
 ```bash
 # Create profiles (connection params now; tokens via login)
+zeyos profile add                         # interactive wizard
 zeyos profile add dev  --base-url https://zeyos.cms-it.de/dev
 zeyos profile add prod --base-url https://cloud.zeyos.com/acme --client-id app --secret "$SECRET"
 

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.