> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cessy.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cessy.ai/_mcp/server.

# Builder Journey

> Follow the recommended path from business language to a published Cessy app with APIs, agents, and custom pages.

The fastest way to build well in Cessy is to move from business language to runtime verification in a tight loop. Do not begin with REST endpoints or page layouts. Begin with the decisions the business needs to make and the facts the business needs to remember.

## Journey map

| Step          | Builder question                              | Cessy artifact                              |
| ------------- | --------------------------------------------- | ------------------------------------------- |
| 1. Understand | What business decision is being made?         | Decision model, command names, event names  |
| 2. Model      | What state is required to decide safely?      | Decider scope, command schema, event schema |
| 3. Read       | What questions must users and systems answer? | Projections and projection views            |
| 4. Automate   | What should happen after an event?            | Policies, webhooks, subscriptions           |
| 5. Protect    | Who may do what?                              | Roles, attributes, permissions, principals  |
| 6. Operate    | How do builders and users inspect behavior?   | Data Explorer, Activity, channels, errors   |
| 7. Extend     | What needs a custom experience?               | Custom pages, adapters, runtime APIs        |

## Use Design MCP from the start

Design MCP is part of onboarding, not an advanced integration. A connected builder agent can inspect the real app, fetch Cessy-specific reference material, validate changes, and use workspace changesets instead of guessing from stale screenshots.

Use the read-only Design MCP endpoint for discovery, review, product shaping, and PRD work. Use the full Design MCP endpoint only for trusted agents that are allowed to mutate the model.

## Definition of done

A builder change is ready to publish when:

* the current model has been inspected, not assumed
* the change is isolated in a workspace or clearly scoped manual edit
* validation passes without ignored errors
* generated runtime contracts still express the intended external behavior
* permissions are verified for the expected actors
* at least one command and one projection path have been smoke-tested after publish

## Common trap

Avoid treating Cessy as a CRUD generator. Commands are business decisions, events are durable facts, and projections are read models. If a proposed endpoint does not map to that language, model the business flow first and only then expose the runtime contract.