Skip to main content

AI Resources

This page describes how AI agents interact with ZeyOS and lists the statically hosted, machine-readable documentation surface.

Choose your task​

/llms.txt lists the same paths, with the reading order and each page's Markdown URL.

Set up a coding agent​

For native iXML/Zymba development and external integrations, start with Agent Setup, then copy the ZeyOS project instructions into your agent's project rules. The native-code validation workflow covers XML formatting, command parameters, database identifiers, and native compiler checks without execution.

Use client/CLI 1.0.0 or later: the zeyos CLI's schema descriptions and request previews, or enable validate: true in the JavaScript client, for API preflight checks. Validation follows every foreign-key hop and checks the terminal field against the target schema. Supply a reviewed custom-field snapshot for the target instance through the client's customFields option or the CLI's ZEYOS_CUSTOM_FIELDS_FILE JSON file to validate extdata references and writes. Missing custom-field metadata is a validation error, not evidence that a field is valid.

These checks do not validate native SQL or compile iXML/Zymba scripts. Use the ZeyOS SDK’s compile or lint commands for native compiler diagnostics without running code. They require a linked application and authenticated network access and send source to the configured instance. zeysdk run is a separate execution step, used only when the task calls for it. Upgrade the client and CLI together; older releases do not provide these checks. Verify the installed version, and use the tagged-source setup if the registry has not published the required release.

Start here​

How an agent connects to ZeyOS​

ZeyOS data lives behind a per-instance REST API. An agent connects like this:

  1. Authenticate - obtain an OAuth 2.0 bearer token from https://cloud.zeyos.com/{INSTANCE}/oauth2/v1/ (see the Authentication Guide).
  2. Query - POST to https://cloud.zeyos.com/{INSTANCE}/api/v1/{resource}/ with a JSON body (fields, sort, limit, offset, expand, count, and filtering). The OpenAPI contract names the filtering key filter; the client and CLI use filters. Follow the contract for the interface you use. See the REST API introduction.
  3. Use the official client - for most agent and scripting work, use @zeyos/client and the zeyos CLI instead of hand-rolling HTTP. The client, CLI, agent quickstart, and recipes live under API Guide.

/llms.txt contains the full version of this flow, a copy-paste curl example, the client snippet, and the query-model gotchas - point your agent there first.

Connecting clients​

Machine-readable specs (mirrored when available)​

Canonical source-of-truth is https://cloud.zeyos.com/__doc/.... These are mirrored onto this docs host during build (when available) to reduce cross-domain friction.

Authoritative Zymba lookup​

Use the Zymba symbol index to find exact declarations, then retrieve a namespace index entry or one namespace such as Array. Each declaration retains its raw definition, source JSON pointer and source SHA256 from the official JSON mirror. Multiple declarations with the same name remain separate. Check static versus instance receivers and raw parameter/default/return metadata and annotations; generated signatures are display aids, not compiler checks.

The index is generated from the official reference, not the deferred Zymba guide drafts. Reference lookup cannot establish all application inputs or current runtime behavior. Keep the source hash with validation evidence. Compile native code without execution first; use a confirmed sandbox when a behavioral test is requested. The Zymba reference working set provides all reference namespaces for offline reading.

Derived, chunked indexes​

Per-page Markdown​

Guide, SDK, iXML, Zymba and REST API pages have a View Markdown control. The same files follow one URL rule: an HTML route maps to /ai/guide<route>.md.

Text
/guide/agent-workflows/agent-setup
/ai/guide/guide/agent-workflows/agent-setup.md
  • /ai/guide/index.json lists every page with its route, canonical URL, source, sha256 and bytes. Here sha256 covers the page body after the frontmatter, so it changes with the content, not with the source revision. bytes is the whole file.
  • Frontmatter holds title, description, canonical_url, section, authority and the source: source_revision for repository pages, or source_sha256 for pages projected from a specification. source_dirty: true marks a build from uncommitted documentation.
  • Links are absolute and code fences are preserved.
  • authority: draft-guide marks Zymba guide pages. They are explanatory drafts: they stay out of the working sets and do not override the Zymba reference.

Index and full working sets​

In every scope, llms.txt is an index of links and llms-full.txt is that index followed by the complete text. Manifest entries state this as workingSet: "index" or "full". Check bytes in the manifest before loading a full set.

ScopeIndexFull working set
Everything/llms.txt/llms-full.txt
Client guide, iXML guide, SDK/guide/llms.txt/guide/llms-full.txt
REST API/api/llms.txt/api/llms-full.txt
Database/db/llms.txt/db/llms-full.txt
iXML reference/ixml/llms.txt/ixml/llms-full.txt
Zymba reference/zymba/llms.txt/zymba/llms-full.txt

Bundles (optional, for RAG)​

Contract, change detection & caching​

  • The paths listed in /ai/manifest.json are treated as the public contract. It lists specs, entrypoints, indexes and bundles, rather than every per-tag, per-table or per-namespace file.
  • Follow the derived indexes above to discover individual files. Their chunk records in /ai/docs.jsonl include url, sha256, bytes and full UTF-8 text.
  • /ai/index.json is the same artifact list but includes generatedAt and changes every build.
  • Cache listed artifacts by the manifest's sha256 + bytes, and individual chunks by the corresponding JSONL record's hash and size, to avoid re-ingesting unchanged content.
  • The manifest inside the offline archive omits the archive itself to avoid a checksum cycle; the served manifest includes the download.
  • Alias entries expose aliasOf for their canonical URL.
  • If an AI-surface URL must change, ZeyOS keeps an alias copy for a deprecation window (no silent removals).
  • documentationRevision and sources in the manifests record the fetched documentation revisions. Hashes identify content, not compatibility.

Inclusion / redaction​

  • This surface contains technical documentation only (guides, OpenAPI, DB reference, iXML and Zymba references + derived indexes).
  • It does not include tenant/customer data. Examples are documentation-only.

Locale notes​

  • English is served at /…
  • German is served under /de/… (e.g. /de/llms.txt, /de/ai/manifest.json)

Usage examples (integration-focused)​

Set BASE_URL once (replace with your docs host):

Bash
export BASE_URL="https://www.zeyos.com"

Fetch the agent entrypoint:

Bash
curl -sS "$BASE_URL/llms.txt"

Find an endpoint and then fetch its tag slice:

Bash
curl -sS "$BASE_URL/ai/openapi/operations.json" | jq '.operations[] | select(.path=="/accounts/{ID}" and .method=="GET")'
curl -sS "$BASE_URL/ai/openapi/tag.accounts.openapi.json"

Fetch a DB table definition as JSON (schema + constraints/indexes + inbound refs):

Bash
curl -sS "$BASE_URL/ai/db/table.accounts.json"

Download the full deterministic bundle for offline/RAG ingestion:

Bash
curl -L -o zeyos-ai-docs.tar.gz "$BASE_URL/ai/download/zeyos-ai-docs.tar.gz"

Maintainers​

  • Validate AI surface: npm run verify:ai-docs
  • Full build + link check: npm run verify