ZeyOS client and CLI 1.0.0

ZeyOS client and CLI 1.0.0 validate complete documented join paths and individual custom fields before API requests. Unknown fields and missing custom metadata now fail with actionable errors.

Migration: upgrade both packages together. Existing validated integrations using extdata.* must supply a reviewed customFields contract, or set ZEYOS_CUSTOM_FIELDS_FILE for CLI/MCP to an instance-bound snapshot. Reading the full extdata collection remains supported. Do not disable validation to conceal an unverified field.

The release also includes Kilo/native development setup, copyable agent instructions, authoritative Zymba reference discovery, and the previously unreleased MCP compatibility and catalog fixes listed in CHANGELOG.md.

Validation: 40 focused local schema, CLI and snapshot checks passed; both package contents were inspected with npm pack --dry-run. The publication workflow runs the repository's existing suites. Native iXML/Zymba runtime behavior and live tenant requests were not exercised by this release work.

v0.8.0 — Machine-readable failures

Closes the two gaps a two-model review (Kimi K3, Grok 4.6) ranked first and second when comparing this CLI against SAP, Salesforce and Workday on agent usability: a failure a machine can read, and a command model a machine can discover.

Machine-readable failures

In --json/--yaml mode a failure now writes a structured envelope to stdout:

{ "ok": false, "error": { "code": "unknown_entity", "exitCode": 2, "message": "…", "field": "…", "suggestion": "…", "actions": ["…"] } }

Previously stdout was empty and the reason was prose on stderr, which made the published exit-code contract unusable for its stated purpose. Success output is unchanged — a list is still a bare array, and the two are told apart by shape.

Every command emits it, including login, logout, profile, skills and okf, which until now exited 1 with a bare stderr line. A bad --port or --target is 2, a failed token exchange 3, a missing bundled directory 1 with a missing_bundle code.

zeyos commands

Publishes the command graph — every command, its aliases, the flags it accepts and each option's type — as data. zeyos describe exposes the data model; this exposes the command model, so an agent no longer infers flags from prose help. The equivalent of sf commands --json.

Entities

Five new (contract, supplier, stocktransaction, comment, ledger) and twelve transaction pseudo-entities (billing_invoice, procurement_delivery, …) bound to transactions.type.

stocktransaction, ledger and payment are an append-only record rather than a working document, so they now carry a historyBearing note that zeyos describe publishes and the delete confirmation states before asking. The capability is unchanged — --force still honours the caller.

Also fixed

• Error hints (actions) reached --json callers but not the terminal. They now go to stderr too.
• A corrupt .zeyos/api/<resource>.json no longer echoes its own contents; it reports the file, the position and a config_invalid code.
• delete --yes works (it was declared but never allow-listed).
• JSON parse errors no longer leak the payload — Node embeds the input in its own message.

Full detail in CHANGELOG.md.

v0.7.0

A full review of the CLI, its credential layer, the MCP server, and the release
pipeline, plus a pass focused on making the CLI usable by AI agents.

This release contains breaking behaviour changes — see Breaking below. Both
packages move to 0.7.0 together and @zeyos/cli now requires @zeyos/client@^0.7.0.

Agent usability

The benchmark harness in test/agent-protocol and its RECOMMENDATIONS.md record one
lesson repeatedly: absorb model syntax drift at the CLI boundary, because prompt guidance
alone is high-variance. This round acts on that.

• Filter syntax drift is translated instead of 400-ing. The CLI now accepts Mongo
  ($lt $lte $gt $gte $ne $in $nin $like $ilike $regex $eq $between), suffix
  (field__gt, field__startswith, field__endswith, field__contains,
  field__between, field__exact), and the single-underscore form where unambiguous
  (status_neq, ID_gt — but never splitting a real field like sender_email).
  status_neq and name_starts are both shapes the benchmark recorded models emitting
  and then looping on.
• $or / $and now work. ZeyOS expresses them as numbered logical groups
  ({"0": ["OR", …]}), a syntax no model guesses. They are translated rather than
  rejected, and the schema validator understands the resulting groups.
• Unknown filter operators fail before the request, naming the supported set, instead
  of being passed through for the server to reject opaquely. {"status":{"$eq":9}} used
  to ship verbatim; {"status":{"between":[1,5]}} was actively mangled.
• field__isnull is rejected with the alternative rather than guessing semantics
  ZeyOS does not have.
• startswith/endswith/contains now escape % and _ in the caller's text, so
  searching for "50%" matches a percent sign. like/ilike still take a raw pattern.
• zeyos describe publishes the filter vocabulary — a filter operators section in
  the human view and filterOperators in --json — so an agent can read the syntax
  instead of discovering it by trial and error.
• Unknown entity names suggest the closest spelling. zeyos list billing_invoces now
  answers "Did you mean billing_invoices?" like flags, fields and presets already did.
• zeyos doctor agent honours --profile instead of silently diagnosing the default
  credentials, no longer calls an expired token with no refresh token "ready", and emits a
  nextSteps array with the remediation for whatever is wrong.
• MCP list_records and get_record gained extdata, expand and (on get_record)
  tags. An MCP-only agent previously could not reach transaction line items, custom
  fields or expanded JSON columns at all.
• MCP find_records now honours a pseudo-entity's bound type, matching zeyos find.
• MCP sum_records no longer reports truncation when the result lands exactly on the cap.
• Skill pack corrections: the billing workflow taught list --limit 10000 | python3,
  which silently drops rows past 10,000 — it now uses zeyos sum. The shared guide no
  longer tells agents to escalate to the JS client for expand, which the CLI supports.
  Added rule R-024 covering the exit-code table.
• --timeout and --no-validate are now listed in the global help.

Fixed (correctness)

• The bound transaction type is now an invariant. zeyos list billing_invoices --filter '{"type":8}' returned procurement invoices under the billing-invoice name, and
  zeyos create billing_invoices --type 8 filed the record under the wrong type. Both are
  now refused with the entity that owns the requested type. The same merge-order bug
  existed on MCP create_record.
• The parser no longer fails open on writes. zeyos create ticket --name Fix login bug
  created a ticket named Fix and exited 0; surplus positionals are now a usage error
  that suggests quoting. zeyos find accounts Acme Corp silently searched only Acme.
• Unknown short flags are rejected. zeyos list tickets -j silently ignored the flag
  and printed a table; long flags already failed correctly.
• Integer options are parsed strictly. --limit 10junk became 10, --limit 3.7
  became 3, and --limit -5 was passed through.
• Enum validation now inspects array and operator filter forms.
  --filter '{"status":[999]}' and {"status":{"IN":[999]}} passed validation while the
  equivalent scalar was correctly rejected — so the array syntax the CLI actively
  encourages was the one that skipped the check.

Added

• Transaction types are now first-class entities. transactions holds twelve
  different business documents separated only by the type column, which meant
  remembering that an invoice is type: 3. Each type now has its own entity —
  billing_quotes, billing_orders, billing_deliveries, billing_invoices,
  billing_credits, procurement_requests, procurement_orders,
  procurement_deliveries, procurement_invoices, procurement_credits,
  production_fabrications, production_disassemblies — with the type bound
  beneath any --preset and --filter, and set automatically on create.
  Singular, plural and hyphenated spellings resolve; bills, po and
  purchase_orders reach the procurement side. Codes verified against
  cloud.zeyos.com/__doc/dbref.json. Invoice and credit entities gain
  open / overdue / paid / draft / booked / cancelled presets. The
  MCP server advertises them too, with the bound transaction_type.
• zeyos list with no entity now lists what you can query, grouped by
  business area, instead of failing with a usage error. zeyos resources shows
  the same overview.
• Float columns are formatted. Columns the schema types as double precision,
  numeric, decimal, real or money render with grouped thousands and two
  decimals in table and record views, right-aligned (17.009,00). Integer
  columns are untouched, since IDs, foreign keys, enum codes and timestamps are
  all integers. The locale comes from ZEYOS_LOCALE, then the resource config's
  locale, then the host default. --json/--yaml keep the raw number.

Breaking

• invoices now means billing invoices, not documents. invoice/invoices
  were aliased to the documents entity, so zeyos list invoices returned PDF
  file records rather than invoices. They now resolve to billing_invoices.
  documents is unchanged and still reaches the document records.
• zeyos resources --json gained fields. It remains a flat array of
  { name, operations } — existing consumers are unaffected — and now also
  carries group, description, and transactionType for pseudo-entities.
• Exit codes are now differentiated. Failures previously all exited 1.
  They now use: 2 usage error, 3 auth error, 4 not found, 5 aborted, and
  1 for everything else. Scripts testing for an exact 1 need updating;
  != 0 checks are unaffected.
• A declined or unanswerable delete confirmation exits 5, not 0.
  zeyos delete <resource> <id> with stdin closed previously printed Aborted
  and exited 0, which a script read as a successful delete. It also no longer
  hangs when stdin is closed without a newline. Use --force for
  non-interactive deletes.
• --flag=value on a boolean option is now rejected instead of being read
  as true. zeyos delete … --force=false previously skipped the confirmation
  and deleted; it is now a usage error.
• zeyos profile list --json/--yaml no longer prints credential values.
  Each profile now reports baseUrl, instance, clientId,
  hasClientSecret, and a token status. clientSecret, accessToken and
  refreshToken were previously emitted in plaintext to stdout.
• zeyos update … --json/--yaml no longer echoes the request when the API
  returns no body; it prints { "ID": …, "updated": true } instead, so a
  caller can tell a confirmed write from an unverified one.

@zeyos/cli (zeyos)

• --<field> values are now typed from the resource schema instead of being
  guessed from the literal. Text columns keep their string value, so
  --customernum 00123 no longer writes 123, --phone +49… no longer loses
  its +, and Infinity no longer becomes null. Numeric columns still
  coerce. Values that cannot round-trip exactly (very large integers) stay text.
• Added a default 30s request timeout, with --timeout <seconds> and
  ZEYOS_TIMEOUT_MS. The runtime has always supported timeouts; the CLI never
  enabled one, so a stalled connection hung forever and the retry logic — which
  keys off timeouts — could not fire.
• zeyos get --fields is now honoured in --json/--yaml, which previously
  printed the whole record.
• zeyos doctor agent exits non-zero when the environment is not ready, so it
  works as a CI health check.
• Fixed profile-pin precedence: a nearer .zeyos/auth.json now correctly beats
  a pin further up the tree. The previous check compared path string lengths,
  which both inverted the documented rule and mis-ordered unrelated paths — a
  parent directory pinned to production could capture a nested test project.
• Credential files and directories now have their permissions repaired on every
  write (0600/0700); mode: on create alone left pre-existing 0644 files
  world-readable.
• The OAuth state parameter now uses node:crypto rather than Math.random().
• The browser opener no longer passes the authorization URL through a shell, and
  validates it as http(s) first.
• Refreshed tokens are now persisted even when the API call afterwards fails,
  so a rotated refresh token is not silently discarded.
• Empty objects and arrays now render as valid YAML (a: {}, not a:{}, which
  parsers read back as a string).
• Pagination hints no longer claim a further page at a non-zero --offset when
  the result is already complete, and no longer blame the default --limit when
  the caller pass...

v0.6.0

0.6.0

@zeyos/cli

• Added direct resource coverage and aliases for common API nouns whose generated operationIds differ from user-facing names, including group/user junctions, mailing lists/recipients, price lists, price-list account junctions, prices, and dunning junction aliases.
• Expanded forgiving filter normalization for Mongo-style operators, bare comparison operators, array-to-IN, suffix forms, and negative-set filters, with dry-run JSON visibility.
• Expanded zeyos sum coverage and regression tests for actionsteps, payments, and transactions.

Agent skills and benchmark protocol

• Made the generic ZeyOS entrypoint slash-command-free and direct-count friendly.
• Added DeepSeek-only strict benchmark mode, efficiency budgets, environment-defect leakage detection, result contract stress coverage, and pass-but-expensive scorecard separation.
• Added complex collections/mail benchmark scenarios and report clarity for provider/runner failures after successful API traces.

Validated locally with npm test, npm --prefix cli test, package dry-runs, and the DeepSeek-only benchmark report agent-report-deepseek-20260626-codex-pass6.

v0.5.0: agent skills, OKF expansion, test-protocol v2

Adds four ZeyOS agent skills, expands the OKF knowledge bundle, hardens zeyos logout, and substantially expands the (dev-only) agent test protocol.

Agent skills (shipped)

• Four new domain skills, installable via zeyos skills install: zeyos-calendar-and-scheduling, zeyos-document-and-approval, zeyos-procurement-and-supplier-performance, zeyos-data-quality-and-governance — each with stated routing boundaries.
• Shared operating guide gains the R-001–R-023 rule set + a confirmation matrix; the query-pattern guide gains anti-join, result-file, half-open-window, currency, state-diff and prompt-injection patterns.

Open Knowledge Format (shipped)

• +8 concepts, +8 playbooks, +3 metrics, generated through the curated bundle so the drift gate stays green.

@zeyos/cli

• logout now clears the selected local legacy credentials in full (connection params, not just tokens); profile/global logout unchanged.

Agent test protocol (dev-only — not in the npm tarball)

• Scenario schema v2; catalog 29 → 69 scenarios; policy proxy (the agent gets an opaque run-local token, never the real bearer); 6 new deterministic verifiers (computeProjection, verifyResult, verifyFile, verifyStateDiff, verifyTrace, verifyNoLeak); JUnit + coverage reporting. Live-validated on a sandbox instance (65/69 seed+query clean, 4 environment-skip).

npm test green (216 tests); OKF drift gate green.

🤖 Generated with Claude Code

v0.4.0 — Open Knowledge Format (OKF) integration

Open Knowledge Format (OKF) integration

Ships a conformant OKF v0.1 knowledge bundle (okf/) describing the ZeyOS data model, plus client/CLI tooling to produce, consume, validate, and refine it. The bundle is canonical for schema facts (the skill pack's operationId table now derives from it), kept fresh by the codegen pipeline, and wired into the agent-protocol improvement loops.

Highlights

• 64 entity concepts (schema, foreign keys, enums, indexes, real operationIds) plus curated metrics/playbooks/concepts; managed blocks preserve curated notes across regeneration.
• @zeyos/client: buildOkf, loadOkfBundle, validateOkfBundle, validateOkfFiles, OKF_VERSION.
• zeyos okf list|show|check|export|build.
• Freshness: source_snapshot hash + auto okf/log.md schema-diff + npm run okf:check drift gate.
• Loops: --context skills|okf|both measurement + okf:refine (generate → validate → judge → apply).

See CHANGELOG.md and docs/06-okf/ for details.

🤖 Generated with Claude Code

v0.3.0 — credential profiles, time-tracking skill, client reliability

@zeyos/client

• Single-flight token refresh — concurrent operations share one getToken instead of each firing its own (avoids redundant calls and refresh-token-rotation failures).
• Request timeout — timeoutMs (per-request or config.timeoutMs), composed with any AbortSignal.
• Network-error retries (reads only) — dropped connections/timeouts retried for safe reads; writes never auto-retried. Override via retryOnNetworkError.
• Auto-pagination — client.paginate() async iterator + client.collect().
• Richer errors — server error detail folded into ZeyosApiError.message.

@zeyos/cli (zeyos)

• Named credential profiles — zeyos profile list|current|use|add|remove, global --profile, ZEYOS_PROFILE, project pins (.zeyos/profile); login --profile, profile-aware logout.
• Expired-token detection on login; friendlier whoami 503/401 messages.

Agent skills

• New zeyos-time-tracking skill: first-person work views + interactive time logging (resolve account → pick ticket/task → write effort as an actionstep), timesheet summaries, entry corrections.

Full notes in CHANGELOG.md.

v0.2.0

Minor release of @zeyos/client and @zeyos/cli (both 0.2.0).

@zeyos/client

• Added a dryRun request option that returns a resolved request descriptor (method/url/body/bodyType) without any network or token work — powers the CLI --query flag.
• Packaging: sample paths are listed explicitly so the generated samples/missioncontrol/data.* (possible real instance data) never ship to npm.

@zeyos/cli (zeyos)

• New doctor agent offline readiness check for coding agents (never prints tokens or secrets).
• New --query dry-run flag on the data commands; --query --json emits the full request descriptor.
• New --filter-file (list/count) and --data-file (create/update); mutually exclusive with inline --filter/--data, and read errors never echo file contents.
• Strict unknown-flag validation with "did you mean …?" suggestions.

Agents / skills

• Self-contained skill packs pointing at a shared operating guide; entity-noun → operationId reference; per-domain count/visibility/dunning notes.

Samples

• New read-only mission control team-performance dashboard.

Full notes: see CHANGELOG.md.

v0.1.1

Maintenance + feature release for @zeyos/client and @zeyos/cli.

@zeyos/client

• oauth2.buildAuthorizationUrl() now includes the scope parameter when provided (was dropped).
• Retry timing hardened: an empty/whitespace Retry-After falls back to exponential backoff; an already-aborted signal stops a zero-delay retry.
• normalizeListResult() preserves a numeric-string count.

@zeyos/cli (zeyos)

• Added --version / -v.
• Fixed the --key=value argument form (previously parsed as an unknown flag and silently ignored).
• YAML output quotes ambiguous scalar strings (true/false/null/yes/no, numeric strings).
• skills install reworked into a multi-agent installer: claude, codex, opencode, droid, pi, and a generic agents layout; --global/--local scope, --dir <path>, an interactive agent/scope picker, -y/--yes, --no-logo, and a --json/--yaml install summary.
• login prints the callback URL before prompting for the application ID/secret so it can be registered as the OAuth redirect URI.

Docs

• Rewrote the top-level README with CLI, JavaScript client, login/OAuth, and coding-agent examples.
• Documented the multi-agent skills installer; assorted accuracy and cross-link fixes.

Full details in CHANGELOG.md.

v0.1.0 — Initial release

@zeyos/client

• Zero-dependency JavaScript client (browser + Node 18+) for the ZeyOS OpenAPI services (api, oauth2, legacyAuth), with methods generated from the specs.
• Authentication modes: auto, oauth (bearer + refresh; authorization-code and password grants), session (ZEYOSID cookie), and none; pluggable token store (MemoryTokenStore) and token-set helpers.
• Schema introspection (client.schema): describe resources, fields, enums, and foreign keys; pre-flight validate() flags unknown fields, bad enums, the filter-vs-filters footgun, and required-on-create fields.
• Resilience: automatic 429 retry honoring Retry-After, structured ZeyosApiError / ZeyosValidationError, CRUD body inference, and normalizeListResult.

@zeyos/cli (zeyos)

• CRUD against common resources with --json/--yaml, field selection and aliasing, dot-notation joins, pagination, and config-driven field display.
• OAuth login flow, credential cascade (env → .zeyos → global config), describe / resources / skills / whoami, and safe delete confirmation.
• Accepts a JSON body passed positionally to create / update.

Docs, samples & agent skills

• Docusaurus documentation (API reference, JavaScript client, CLI, agent workflows, tutorials), three sample apps (Kanban, CRM, Dashboard), and a repo-local agent skill pack under agents/.

See CHANGELOG.md for full details.