ZeoCore Documentation

Connecting a service? Start with integration account setup for exact credential screens, separate test/production accounts and E2E checks for every supported integration.

This is the learning hub. It tells you what to read, in what order, and what each piece is for.

Brand new to ZeoCore? Go straight to QUICKSTART.md — it installs Python 3.14, sets up a virtual environment, and gets a capability running on your machine in about ten minutes.

The learning path

Work through these in order. Each step assumes the one before it.

#	Read	Time	You'll be able to
1	README.md	5 min	Say what ZeoCore is, who it's for, and how a capability is shaped.
2	QUICKSTART.md	10 min	Install ZeoCore and run your own capability, and explain every line of it.
3	Concepts	15 min	Understand capabilities, contracts, context, and where the runner's job begins.
4	Capability authoring tutorial	20 min	Register capabilities, add guards, build manifests, and bind to adapters.
5	Results and errors	20 min	Choose correctly between returning a result and raising an exception.
6	Context, configuration, and files	20 min	Wire ToolContext, load_config(), and filesystem access together.
7	Bounded retries and explicit fallback	15 min	Put one-attempt capabilities behind a total deadline without hidden or multiplied retries.
8	GET-STARTED.md	reference	Use paths, plugins, integrations, and adapters in depth.
9	An integration tutorial (ZEOconnect, MCP, Supabase, Notion, Calendar, Google Docs, or Bluesky)	20 min	Connect your capability to the outside world.

Unfamiliar term along the way? The glossary defines them in one place.

Tutorials

Step-by-step guides for people building on ZeoCore.

Core

• Author your first capability — @capability, the registry, invoking, OpenAI projection, and HTTP/MCP binding. Start here after the quickstart.
• Results and errors — the difference between an expected outcome and a bug, and how each is reported.
• Context, configuration, and files — ToolContext, configuration loading, and filesystem access, and how they relate.
• Bounded retries and explicit fallback — one total deadline, explicit attempt plans, cancellation, and truthful live/simulated labels.

Added in 0.11.0, after capability authoring

• Provider registration — terminology, an explicit factory and the offline catalogue example.
• Runtime host — trusted launch context, admission, canonical bytes and Runtime-owned results; requires runtime-host.
• Meeting operations — admitted reads, Notion upsert and Gmail draft operations, with a request-only offline example.

Integrations and adapters

• Kit marketing — newsletters, sequence authoring, subscriber consent, tags and metrics through agent capabilities.

• HubSpot marketing — newsletters, campaigns, subscriptions and email drip sequences, with agent capabilities.

• ZEOconnect managed profile — run one typed service under fake, local, hosted, or governed placement without putting provider credentials in application code.

• MCP server with Claude Code / Cursor — expose your tools to MCP-native coding agents.
• Notion integration — read and write Notion pages and databases.
• Supabase integration — Database, Auth, Storage, Edge Functions, Realtime, and the Vault boundary.
• Google Calendar integration — OAuth setup, reading and creating events.
• Google Docs integration — reading document text, creating documents, and batch edits.
• Bluesky integration — posting, and why link positions are UTF-8 byte offsets.

Runnable examples

Every script in examples/ runs as-is with uv run examples/<name>.py. None are illustrative fragments. Some need an optional extra installed (noted below); the credential-backed ones skip gracefully when the credential isn't set, rather than crashing.

Authoring the core surface

• capability_authoring.py — the canonical @capability function, registry, and invoke_sync.
• minimal_tool.py — the smallest class-based tool: no mixins, no services, just run().
• tool_to_capability.py — adapt a BaseZeoTool class into a BoundCapability.
• capability_guards.py — a RequestGuard rejecting a request before the handler body runs.
• toolkit_usage.py — lifecycle hooks, an optional integration, and a graceful skip when a service isn't wired.

Infrastructure

• config_usage.py — load_config()'s three real behaviors, including the failure mode caught on purpose.
• error_handling.py — the ZeoError family and when to raise instead of returning a result.
• explicit_plugin_loading_example.py — discover and load plugins with no import-time side effects.

Exposing capabilities

• llm_tools_usage.py — project a CapabilityManifest to an OpenAI function tool, or refuse cleanly.
• http_adapter_usage.py — bind a capability into OperationRegistry and exercise the FastAPI app (zeocore[http]).
• mcp_server_usage.py — expose a tool as an MCP server (zeocore[mcp]).

Integrations

• notion_demo.py — current Notion API, simulated by default with an explicit read-only live mode.
• calendar_usage.py — Google Calendar read/write, skipped when OAuth isn't configured.
• jupytext_usage.py — script ↔ notebook round-trip.
• ffmpeg_usage.py — probe, transcode, and thumbnail a synthetic test video it generates itself.

Release 0.10.0 workflows

• Managed test and production and environment_usage.py: explicit state and credential selection before launching an application.
• Native service profiles and zeoconnect_usage.py: an offline fake first, then deliberately configured local, hosted or governed placement.
• Gemini reference images and gemini_request.py: key acquisition, separate projects, host custody, admission and reconciliation.
• Notebook execution and the authoring reference: local conversion, execution and staging with observable receipts.
• Release notes: upgrade instructions and qualification limits.

Reference

• API reference — the public surface, symbol by symbol, and which import paths are supported.
• Concepts — the model behind the API: capabilities, contracts, context, and the runner boundary.
• Glossary — one-line definitions of the vocabulary used throughout these docs.
• GET-STARTED.md — the full manual, and the place to look things up once you're past the tutorials. Includes a troubleshooting section.
• src/zeo_core/contracts/README.md — the contracts kernel: identities, definitions, manifests, results.
• src/zeo_core/contracts/EXAMPLES.md — worked contract examples.
• llms.txt — a condensed import map for coding agents.
• CHANGELOG.md — what changed, and which things were deliberately not built.

Browse the documentation site for searchable guides and generated API signatures. The public API map defines supported import paths.

Contributing

CONTRIBUTING.md covers dev environment setup (make setup), the verification gate (make verify), and how to submit a change. Conduct expectations are in CODE_OF_CONDUCT.md; security reports go through SECURITY.md.

Maintainer / ecosystem reports

These are not end-user documentation. They record how ZeoCore relates to Sovereign Agent and the wider Zero Employee ecosystem.

• Capability symbol audit
• Sovereign Agent replacement readiness