# Cake20 AI Core

## Authority

This document describes the public Cake20 website programming model. Apply it before
generic framework conventions. For exact signatures, use the installed
`@cake20/runtime` declarations. For an MCP session, the current tool schemas and the
connected website state override stale examples.

Cake20.js is the public website programming model formed by `@cake20/view` and
`@cake20/runtime`, with `@cake20/cli` providing its local lifecycle. Human-facing
concepts and runnable examples are published at https://js.cake20.com and
https://js.cake20.com/examples.html. AI agents must continue to use this
machine-oriented context and installed declarations as their coding authority.

## Product model

- Cake20 Core is a visual control plane for independent websites.
- Cake20 Gateway is the public HTTP and WebSocket entry point. It serves static
  releases directly and forwards dynamic website traffic without exposing Core.
- `@cake20/view` is the standard TSX screen language, compiler, and browser adapter.
- `@cake20/runtime` is the versioned full-stack build and execution engine.
- `@cake20/provider` is Core's private child process for AI, Codex, Playwright browser,
  mail, messaging, and payment execution. Website source never imports or configures it.
- `@cake20/worker` is the shared local/server engine for DB, ZIP, and XLSX execution.
  Website source does not import it.
- `@cake20/cli` creates, validates, previews, builds, runs, synchronizes, and deploys
  Cake20 websites without requiring Cake20 Core.
- A website owns one editable source workspace, one PostgreSQL database, one Redis
  namespace, persistent files, Git history, debug output, and production releases.
  Shared framework code belongs to Runtime, not website source.
- Cake20.js provides Cake20 View, Runtime, UI, data, and server capabilities through
  one smaller intentional source contract.
- Cake20 Core starts and supervises Provider and Worker as packaged child processes.
  They use private local IPC and expose no public Provider or Worker configuration.

## Required workflow

1. Read this document and the task-specific topic documents.
2. Inspect `package.json`, `README.md`, and the current source tree.
3. Classify the website mode from actual source use. If it has no own API, file
   storage, task, queue, WebSocket, SSE, database, or other executable server source,
   explicitly set `package.json` `mode` to `static`. Set it to `fullstack` when adding
   a server feature. Missing and empty values mean `auto`, but do not leave a confirmed
   static website on implicit `auto`.
4. Preserve unrelated source and existing behavior.
5. Use Runtime globals and built-in components before adding dependencies.
6. Keep UI, state, server handlers, schema, and sample data in separate files.
7. Validate with the active Cake20 surface: MCP review in Core or CLI locally.
8. Publish only when the user explicitly requests production deployment.

## Source roots

Root files:

- `package.json`: public project configuration and website dependencies.
- `README.md`: persistent human and AI requirements for this website.
- `public/`: static public files.

Frontend source is under `app`. Allowed direct folders:

- `assets`, `components`, `composables`, `middleware`, `layouts`, `lib`, `pages`,
  `preview`, `stores`, `types`, `utils`.

Backend source is under `server`. Allowed direct folders:

- `api`, `db`, `hooks`, `routes`, `tasks`, `types`, `utils`.

Cross-runtime source is under `shared`. Allowed direct folders:

- `types`, `utils`.

Nested folders are supported inside every allowed direct folder. Do not create
website `plugins` or `modules` directories. Do not place arbitrary files directly
under `app`, `server`, or `shared`.

## Import boundaries

- Frontend `~/x` resolves from `app`; backend `~/x` resolves from `server`.
- Frontend auto-imports named exports from `app/types` and `app/utils`.
- Backend auto-imports named exports from `server/types` and `server/utils`.
- Both runtimes auto-import named exports from `shared/types` and `shared/utils`.
- Do not statically import shared auto-imports. Use their exported names directly.
- Do not import app-scoped files from server or server-scoped files from app.
- Keep browser-only modules in `app/lib` and import them explicitly.

## UI rules

- Cake20 UI components and Tailwind CSS are provided by Runtime.
- Use prefix-free component names such as `Button`, `Card`, `Input`, and `Icon`.
- Create pages, layouts, and components as Cake20 View TSX by default. Existing
  `.vue` files remain supported for compatibility, but do not generate new SFC files
  unless the user explicitly requests them or the existing project requires them.
- Components under `app/components` are auto-imported. Do not import them into pages,
  layouts, or other components.
- Treat `.client` in `*.client.ts` and `*.client.tsx` as a browser-only environment
  marker, not part of the component name. Use `Chart.client.tsx` as `<Chart />`.
- Use Lucide icon names such as `i-lucide-search`.
- Pages and layouts handle routing, data flow, and composition.
- Extract independent sections, forms, dialogs, lists, and repeated elements into
  `app/components`.
- Put client state domains in `app/stores/**/<name>.store.ts`.
- A store exports one default state/action object. Optional persistence is `none`,
  `session`, or `local`.
- Do not put credentials, login tokens, or sensitive data in browser stores.
- Call `map` only on arrays. Use `Array.from({ length: count }).map(...)` for a
  numeric repetition count.
- Event callbacks must pass or invoke the function. Never generate a callback that
  only references a function name.

## Server rules

- API files belong in `server/api`; their URL starts with `/api`.
- Prefix-free routes belong in `server/routes`.
- Use filename method suffixes such as `.get.ts`, `.post.ts`, and `.patch.ts`.
- HTTP hooks use `server/hooks/*.hook.ts`.
- Scheduled handlers use `server/tasks/*.task.ts`.
- Queue handlers use `server/tasks/*.job.ts`.
- WebSocket and SSE endpoints use `server/routes/*.ws.ts` and `*.sse.ts`.
- Ubuntu production website code cannot execute system commands, child processes, or
  uploaded executable files.

## Database rules

- Put one primary table definition in `server/db/<name>.db.ts` by default.
- Export a plain field object. Runtime wraps it as a model; do not write `z.model()`.
- Connect files with `z.ref()`.
- Put reusable named database functions in `server/db/**/*.sql.ts`; call them as
  `db.sql.<name>()` from server code.
- Never call `db.sql` from `shared/utils`; shared code also runs in the browser and
  loads before SQL registration.
- End each model file with `export const seed = async () => {};`. Return deterministic
  rows without calling `db`; use an array for one model or an object keyed by model name
  for multiple models. Every non-empty row needs an explicit ID or unique field.
- Use optional `server/db/seed.sql.ts` only for final procedural initialization across
  model seeds. It may call `db`, runs after model seeds, and must be idempotent.
- A database is provisioned only when at least one model or view schema exists.
- Runtime regenerates `app/preview/<Model>.json` from returned model seed rows without
  scanning the operating database. Preview JSON is never loaded into the database.

## Authentication and secrets

- Protected websites must use `auth.login`, `auth.user`, `auth.require`, and
  `auth.logout`.
- Put first-level page and API rules in `package.json` `auth`: `true` requires login, a
  string requires one Role, an array accepts any listed Role, and `false` creates a
  public exception inside a broader protected path.
- Never create custom JWTs, session cookies, browser tokens, or localStorage auth.
- Keep login as a standalone `/login` page and enforce authorization again on server
  APIs and data access.
- `package.json` is public. Credentials belong in encrypted Cake20 Secrets.
- Telegram and Gmail integrations notify the connected website owner; they are not
  arbitrary-recipient messaging APIs.

## Build and persistent data

- Generated output belongs in `build` and is not source.
- Core builds browser assets in `build/debug/app` and `build/release/app`.
- Builds read the original workspace directly. Editor and MCP writes remain available,
  but changes saved during a build require a new review or release build to establish
  the verified result.
- Design Preview, debug review, and the production release share the website database,
  Redis namespace, and `files` storage. A review URL is not a separate data sandbox.
- Debug review disables scheduled background tasks and leaves the running production
  release unchanged until publishing.
- Database writes through MCP create an immediate backup and restore it on failure.
- Persistent uploads and generated files belong in the website root `files` storage.
- Return XLSX files generated in the current HTTP request with
  `excel.download(name, rows)` so they do not accumulate in storage.
- Use `excel.save(path, rows)` only for files that must be reopened or retained by
  asynchronous jobs. Give temporary job output an explicit overwrite, expiry, or
  removal policy.
- Runtime temporary files belong in the website root `tmp` area.
- Never store persistent user data in a release directory.
- Production publishing and debug review are separate code lifecycles. A coding
  request alone does not authorize production deployment.

## Dependency policy

- Never add Cake20 platform packages such as `@cake20/view`, `@cake20/fullstack`,
  `h3`, Prisma, or `@cake20/runtime` to website dependencies.
- Website dependencies are declared in `package.json` only when external packages are
  enabled for that website.
- Prefer Runtime APIs, Cake20 UI, Lucide icons, and documented Cake20 CDN modules.
- Keep `package.json` valid JSON and preserve its system-managed fields.