Agents In Cessy

Agent Docs Contract

Cessy docs must serve two readers:

  • human builders deciding what to model or verify
  • AI agents that need exact surfaces, scopes, and constraints

Write pages so both readers can act without guessing.

Page contract

Each page should answer:

  • who should use this page
  • what surface is involved
  • what authority is required
  • what the safe path is
  • what not to do
  • what to verify before handoff

Avoid generic platform prose that does not help a builder make a decision.

Reference contract

Reference pages should name exact endpoints, tool families, scopes, and runtime behavior. If a surface is generated from DomainConfig, say that the generated contract is canonical.

For MCP pages, identify whether the server is design-time or runtime and whether read-only or mutation authority is required.

Example contract

Examples should use placeholders for tenant, app, workspace, environment, and token values. Never include real secrets.

Prefer examples that teach the shape of the workflow over examples that imply a fixed endpoint name for every app.

Drift contract

Update docs when a change affects:

  • Builder UI workflows
  • Design MCP tools or auth
  • Runtime API generation
  • Runtime MCP tools
  • custom page behavior
  • permissions
  • webhooks, subscriptions, adapters, or sandbox behavior

If the code changes the builder mental model, update the docs in the same PR.