# @cake20/cli AI Reference

## Purpose

Use `@cake20/cli` to create and operate a Cake20 website outside Cake20 Core. The
CLI delegates compilation and execution to its compatible `@cake20/runtime`.
It also installs and automatically manages a compatible `@cake20/worker` package.
Together, the Cake20 View source model and Runtime are called Cake20.js.

Before coding, run `cake ai` or read `https://ai.cake20.com/llms.txt`. Human-facing
examples are available at `https://js.cake20.com/examples.html`. Use
`cake ai <topic>` when only one topic is needed. Valid topics are `core`,
`architecture`, `view`, `runtime`, `cli`, `patterns`, `mcp`, `errors`, `contract`,
`project`, `manifest`, and `full`.

## Local workflow

- `data: "auto"` and `data: "local"` start or reuse the packaged Worker through local
  IPC. Never instruct the user to start Worker manually or configure a Worker port.
- `data: "server"` authenticates through Cake20 and uses the private Worker gateway.
- `cake login` opens browser authentication, discovers the account's assigned Core,
  and stores that Core connection locally.
- A logged-in project receives its approved mail, Gmail, Telegram, and payment Runtime
  connections through Core. Provider identity and IPC details remain hidden.
- Website code keeps the same generated `db` type and Runtime globals in every mode.

1. `cake init <path> --standard` creates an English project.
2. Read the generated `README.md`, `package.json`, and source tree.
3. `cake prepare <path>` generates TypeScript configuration and Runtime types.
4. `cake doctor <path>` validates configuration and source policy.
5. `cake design <path>` runs UI-only Design Preview.
6. `cake dev <path>` runs UI HMR, API, database, and Runtime.
7. `cake build <path>` creates a production release.
8. `cake start <path>` runs the current release.
9. `cake deploy <path>` uploads, builds, and deploys only when explicitly requested.

On the first deploy of an unconnected local project, Core shows the project name,
asks whether to create and deploy the website, assigns a new `web-` ID, and writes it
to `package.json` `name`. Later deploys use that system-managed name. An unregistered
local `web-` name is never trusted as a remote target; Core assigns a new ID instead.

## Command map

- `cake ai [topic]`: print official machine-oriented Cake20 context.
- `cake init [path]`: create a project; accepts `--standard`, `--template`, `--yes`.
- `cake prepare [path]`: generate managed editor types and settings.
- `cake doctor [path]`: validate; `--fix` regenerates managed editor files.
- `cake design [path]`: UI-only preview; `preview` is an alias.
- `cake dev [path]`: full local development.
- `cake build [path]`: create a production release.
- `cake start [path]`: run the current production release.
- `cake test [path] <file>`: run one test file; `--suite` selects suite mode.
- `cake pull <web-id> [path]`: replace a directory with server project source.
- `cake sync status|diff|local|server`: inspect or synchronize source.
- `cake db version|export|import`: inspect or transfer PostgreSQL data.
- `cake login`, `logout`, `whoami`, `sites`: account and access operations.
- `cake deploy [path]`: upload, review-build, and publish a website.
- `cake run <archive>`: build and run `.zip`, `.cake.zip`, or `.cake` input.
- `cake update`: update CLI and compatible Runtime.
- `cake version`: print installed Runtime version.

Use `cake <command> --help` for the exact installed command syntax.

## Source synchronization

- `cake sync status` and `cake sync diff` are read-only inspection commands.
- `cake sync local` downloads server source into the local project.
- `cake sync server` uploads local source and creates a server commit.
- Review conflicts before using `--force`.
- A `web-*` project ID belongs to a website. A `tmp-*` ID belongs to a template.
- A connected website stores its `web-*` ID in `package.json` `name`; a separate
  `package.json` `id` is legacy and must not be created.
- `cake push web-*` is deprecated; use `cake deploy` for websites.

## Dependency and version rules

- Install the CLI; it installs compatible Runtime and Worker dependencies. Provider is
  managed by the connected Core server and is not a local CLI configuration.
- Do not add Runtime or framework packages to website `package.json` dependencies.
- Installed Runtime declarations are the exact API source for that version.
- Patch Runtime updates should run existing compatible releases without requiring a
  template rebuild. Rebuild is recommended when the Runtime minor number changes.
- Use `cake update --check` before changing installed versions.

## Agent safety

- Do not run `deploy`, destructive synchronization, DB import, or forced replacement
  without explicit authorization.
- A build is local and reversible; a deployment changes the remote website.
- Do not edit managed `package.json`, generated `build`, or editor type output.
- Preserve user files outside the requested change.