@lowdefy/docs-content 0.0.0-experimental-20260710073520

package/content/concepts/ai-agent-docs.md

@@ -0,0 +1,190 @@
+# Docs for AI Agents
+
+When you run `lowdefy dev`, the development server also serves a documentation API and an [MCP](https://modelcontextprotocol.io) endpoint built for AI coding agents. It describes everything installed in _your_ project — every block, operator, action, connection and request type from core Lowdefy plugins _and_ your own local plugins — plus the full Lowdefy documentation as markdown. This means an agent like Claude Code never has to guess type names or property shapes: it can look up the exact schema, real examples, and the relevant docs page while it writes your config.
+
+Everything is served under the `/lowdefy-docs` path of your dev server (default `http://localhost:3000`). No setup or configuration is needed — it is always on in dev, and never part of your production server.
+
+> The `/lowdefy-docs` route prefix is reserved by the dev server. A page with `id: lowdefy-docs` will not be reachable in dev.
+
+## The MCP endpoint
+
+The dev server exposes an MCP server (streamable HTTP) at:
+
+```
+http://localhost:3000/lowdefy-docs/mcp
+```
+
+It provides these tools:
+
+| Tool                     | Purpose                                                                 |
+| ------------------------ | ----------------------------------------------------------------------- |
+| `lowdefy_overview`       | Start here — what is installed, counts per kind, and how to use the rest |
+| `lowdefy_list_types`     | List ALL available types of a kind (blocks, operators, actions, connections, requests) |
+| `lowdefy_list_plugins`   | Installed plugin packages, including local plugins, and the types each provides |
+| `lowdefy_get_schema`     | JSON Schema for a specific type — all properties and events              |
+| `lowdefy_get_examples`   | Real YAML usage examples for a block type                                |
+| `lowdefy_get_doc`        | A Lowdefy docs page as markdown, by slug or by type name                 |
+| `lowdefy_search_docs`    | Keyword search over the Lowdefy docs                                     |
+| `lowdefy_get_plugin_doc` | Markdown (READMEs, guides) shipped inside an installed plugin package    |
+| `lowdefy_build_status`   | Current build errors and warnings (with source file locations) plus recent browser runtime errors — call after every edit |
+| `lowdefy_get_page_config`| The fully built config for a page, or its structured build errors        |
+| `lowdefy_screenshot_page`| PNG screenshot of a rendered page (headless Chromium) for visual verification |
+| `lowdefy_find_config`    | Which yaml file (and line) defines a given page, block, or request id    |
+| `lowdefy_scaffold_page`  | Create a new page yaml file with a canonical minimal structure           |
+| `lowdefy_app_map`        | The whole-app graph: every page, menu, connection, endpoint, and agent in one call |
+| `lowdefy_inspect_state`  | The LIVE state, request results, and event log of a running page — reads your open browser tab, or runs the page headless |
+| `lowdefy_eval_operator`  | Evaluate any operator expression against live page state — a REPL for config |
+| `lowdefy_run_request`    | Execute a request with a test payload to verify data shape (read-only unless opted in) |
+| `lowdefy_snapshot_state` | Capture live page state + request responses into a committable checkpoint folder |
+| `lowdefy_load_state`     | Restore a state checkpoint — headless, or a `?_checkpoint=` URL for manual testing |
+| `lowdefy_list_state_checkpoints` | List saved state checkpoints |
+| `lowdefy_checkpoint_to_mocks` | Convert a state checkpoint into e2e `mocks.yaml` fixtures |
+| `lowdefy_checkpoint`     | Snapshot all config files before risky changes                           |
+| `lowdefy_revert_checkpoint` | Restore config files from a checkpoint                                |
+
+## The feedback loop
+
+The dev server rebuilds automatically when config changes, so an agent works in a tight loop:
+
+1. Discover types and schemas, write or edit YAML.
+2. Call `lowdefy_build_status` — did the build succeed? Errors come back with the exact source file and location.
+3. Call `lowdefy_get_page_config` to confirm the page builds, and `lowdefy_screenshot_page` to see it rendered.
+4. Runtime errors from the browser (operator errors, block render errors) also appear in `lowdefy_build_status`, so problems that only show at runtime still reach the agent.
+
+## Live state — the agent sees what you see
+
+When you have a page open in your browser, the agent can read its **actual live state** — page state, request results, and the event log of recent actions — via `lowdefy_inspect_state`. Reproduce a problem by clicking through the app, then ask the agent to look: it inspects your exact tab, not a guess. `lowdefy_eval_operator` then evaluates any operator expression (like `{"_state": "customer.name"}`) against that same live context, so `_state`/`_request` binding bugs get debugged against real data. With no tab open, both tools run the page headless instead.
+
+## State checkpoints — put the app in a known state
+
+`lowdefy_snapshot_state` captures a moment — page state plus every request's recorded response — into a folder you can commit:
+
+```
+checkpoints/broken-refund-flow/
+  checkpoint.json        # manifest
+  state.json
+  urlQuery.json
+  requests/
+    get_order.json       # one file per request — easy to review and edit
+```
+
+Loading it back (`lowdefy_load_state`) serves the recorded request data from the dev server and re-injects the page state. Three ways to use it:
+
+- **Agent verification**: the agent restores a scenario headless and confirms its fix works against the exact data that caused the bug.
+- **Manual testing**: `mode: registry-only` returns a URL like `http://localhost:3000/orders?_checkpoint=broken-refund-flow` — open it and the app is in that state, no clicking required.
+- **e2e fixtures**: `lowdefy_checkpoint_to_mocks` converts a checkpoint into `mocks.yaml` entries for [e2e tests](/e2e-introduction), so "write an e2e test for this flow" starts from captured reality.
+
+## Running requests safely
+
+`lowdefy_run_request` executes a request with a test payload so the agent can verify the data shape a page will receive. Read-only request types (like `MongoDBFind`) always run. Write requests are refused unless you opt in:
+
+```yaml
+cli:
+  agentTools:
+    allowWriteRequests: true
+```
+
+This is dev-only — enable it when you're comfortable with the agent writing to your dev data.
+
+## Setting up a project — one command
+
+```bash
+npx lowdefy agent-setup
+```
+
+This writes three files into your project (merging safely if they exist): `.mcp.json` registering the `lowdefy-docs` MCP server, `.claude/skills/lowdefy-config/SKILL.md` teaching Claude Code the workflow, and an `AGENTS.md` section for other coding agents. Use `--port` if your dev server doesn't run on 3000.
+
+## Using it with Claude Code manually
+
+Add the MCP server to your project so Claude Code can use it. In your project directory run:
+
+```bash
+claude mcp add --transport http lowdefy-docs http://localhost:3000/lowdefy-docs/mcp
+```
+
+Or commit a `.mcp.json` file at your project root so the whole team gets it:
+
+```json
+{
+  "mcpServers": {
+    "lowdefy-docs": {
+      "type": "http",
+      "url": "http://localhost:3000/lowdefy-docs/mcp"
+    }
+  }
+}
+```
+
+If your dev server runs on a different port, adjust the URL. The MCP server includes instructions that teach the agent the workflow (list types first, then fetch schemas and examples), so it works well without any extra prompting.
+
+## Referencing it in a skill
+
+For the best results, add a skill to your project that tells the agent to use the docs server whenever it writes Lowdefy config. Create `.claude/skills/lowdefy-config/SKILL.md`:
+
+```markdown
+---
+name: lowdefy-config
+description: Use when writing or editing Lowdefy YAML config — pages, blocks, operators, actions, connections, or requests. Looks up exact type names, schemas, and examples from the running dev server instead of guessing.
+---
+
+# Writing Lowdefy config
+
+The dev server serves docs for everything installed in this project at
+`http://localhost:3000/lowdefy-docs` (also as MCP tools via the `lowdefy-docs` server).
+
+Never guess type names or properties. Before writing config:
+
+1. Call `lowdefy_list_types` (or `GET /lowdefy-docs/blocks`, `/lowdefy-docs/operators`,
+   `/lowdefy-docs/actions`, `/lowdefy-docs/connections`, `/lowdefy-docs/requests`) to find the exact
+   type name — this includes this project's local plugins.
+2. Call `lowdefy_get_schema` (or `GET /lowdefy-docs/schema/{kind}/{type}`) for the
+   exact properties and events of that type.
+3. Call `lowdefy_get_examples` (or `GET /lowdefy-docs/examples/{type}`) to see real
+   usage YAML for blocks.
+4. For concepts (state, operators, events, requests), call `lowdefy_get_doc`
+   or `lowdefy_search_docs`.
+
+After every edit, call `lowdefy_build_status` and fix what it reports. Use
+`lowdefy_inspect_state` to read the live state of the page (ask the developer
+to interact with it first when debugging), `lowdefy_eval_operator` to test
+operator expressions against real state, and `lowdefy_snapshot_state` /
+`lowdefy_load_state` to capture and restore app states for testing.
+```
+
+## Plain HTTP routes
+
+Everything the MCP tools serve is also available as plain GET routes — useful for `curl`, scripts, or agents without MCP support:
+
+| Route                       | Purpose                                                        |
+| --------------------------- | -------------------------------------------------------------- |
+| `GET /lowdefy-docs`                 | Overview and route index                                        |
+| `GET /lowdefy-docs/{kind}`          | List all available types of a kind, e.g. `/lowdefy-docs/blocks`         |
+| `GET /lowdefy-docs/plugins`         | Installed plugin packages and the types each provides           |
+| `GET /lowdefy-docs/schema/{kind}/{type}` | JSON schema for a type, e.g. `/lowdefy-docs/schema/blocks/Button` |
+| `GET /lowdefy-docs/examples/{type}` | Example YAML for a block type                                   |
+| `GET /lowdefy-docs/content/{slug}`  | A docs page as markdown, e.g. `/lowdefy-docs/content/operators/_get`    |
+| `GET /lowdefy-docs/search?q={query}`| Search the docs                                                 |
+| `GET /lowdefy-docs/plugin-doc/{package}` | Markdown shipped inside a plugin package                   |
+| `GET /lowdefy-docs/build-status`    | Current build errors/warnings + recent browser runtime errors   |
+| `GET /lowdefy-docs/page-config/{pageId}` | Fully built page config, or its build errors               |
+| `GET /lowdefy-docs/screenshot/{pageId}` | PNG screenshot of the rendered page                         |
+| `GET /lowdefy-docs/find/{id}?pageId=` | Locate where a page/block/request id is defined               |
+| `GET /lowdefy-docs/app-map`         | Whole-app graph: pages, menus, connections, endpoints, agents   |
+| `GET /lowdefy-docs/inspect-state/{pageId}` | Live state/requests/eventLog of a running page (tab or headless) |
+| `POST /lowdefy-docs/eval-operator`  | Evaluate an operator expression against live page state         |
+| `POST /lowdefy-docs/run-request`    | Execute a request with a test payload (read-only unless opted in) |
+| `GET/POST /lowdefy-docs/checkpoints` + `/revert` | Config-file checkpoints                            |
+| `GET/POST /lowdefy-docs/state-checkpoints` + `/snapshot`, `/load` | State & data checkpoints          |
+
+## Local plugins
+
+Your project's own plugins (declared under `plugins:` in `lowdefy.yaml`) are included automatically:
+
+- Types appear in `lowdefy_list_types` and `/lowdefy-docs/{kind}` listings.
+- Block schemas are derived from each block's `meta`, and connection/request schemas from the `schema` property on your connection and request definitions.
+- Ship a `gallery.yaml` or `examples.yaml` next to a block in your plugin's `dist/blocks/{BlockName}/` and it is served by `lowdefy_get_examples`.
+- A `README.md` or `docs/*.md` files in your plugin package are served by `lowdefy_get_plugin_doc`.
+
+## Docs for crawling agents
+
+The docs site itself serves agent-friendly formats: every page as raw markdown at `https://docs.lowdefy.com/md/{section}/{slug}.md`, an [llms.txt](https://llmstxt.org) index at `https://docs.lowdefy.com/llms.txt`, and the full documentation as one file at `https://docs.lowdefy.com/llms-full.txt`. Generic browser tools like Playwright MCP and Chrome DevTools MCP also work well against a running Lowdefy app — blocks render stable DOM ids matching their `blockId`.

package/content/concepts/cli.md

@@ -0,0 +1,213 @@
+# The CLI
+
+The Lowdefy CLI is used to develop a Lowdefy app locally, and to build Lowdefy apps for deployment.
+
+We recommend running the CLI using `pnpx`, to always use the latest version:
+
+```
+pnpx lowdefy@5 <command>
+```
+
+or, to use a specific version:
+
+```
+pnpx lowdefy@version <command>
+```
+
+Alternative, you can install the CLI globally or to a Javascript project (with a `package.json` file) via pnpm.
+
+To install the CLI globally run:
+
+```
+pnpm add -g lowdefy
+```
+
+The CLI can then be run using `lowdefy` as the executable name:
+
+```
+lowdefy <command>
+```
+
+# CLI commands
+
+## build
+
+The `build` command runs a Lowdefy build. This builds a production Lowdefy app in the server directory, which can then be started using the `lowdefy start` command. The options are:
+
+- `--config-directory <config-directory>`: Change the config directory. The default is the current working directory.
+- `--disable-telemetry`: Disable telemetry.
+- `--log-level <level>`: The minimum severity of logs to show in the CLI output. Options are `debug`, `info`, `warn` or `error`. The default is `info`.
+- `--no-client-build`: Do not run the Vite client build, and only build the Lowdefy config. Used in some deployment scripts where the client build is done as a separate step. The previous `--no-next-build` flag still works as a deprecated alias.
+- `--ref-resolver <ref-resolver-function-path>`: Path to a JavaScript file containing a `_ref` resolver function to be used as the app default `_ref` resolver.
+- `--server-directory <server-directory>`: Change the server directory, the directory in which the production server is placed. The default is `<config-directory>/.lowdefy/server`.
+- `--skip-codemod-check`: Suppress warnings about pending codemod upgrades.
+
+
+## dev
+
+The `dev` command starts a Lowdefy development server, running locally. It can be accessed in a browser at [http://localhost:3000](http://localhost:3000). The CLI watches the file system, and rebuilds the app and reloads served pages every time a change is made to any of the files in the project directory. The `dev` command should not be used to serve a production app, the `build` and `start` commands should be used instead.
+
+- `--config-directory <config-directory>`: Change the config directory. The default is the current working directory.
+- `--dev-directory <dev-directory>`: Change the dev directory, the directory in which the development server is placed. The default is `<config-directory>/.lowdefy/dev`.
+- `--disable-telemetry`: Disable telemetry.
+- `--log-level <level>`: The minimum severity of logs to show in the CLI output. Options are `debug`, `info`, `warn` or `error`. The default is `info`.
+- `--no-open`: Do not open a new tab in the default browser.
+- `--port <port>`: Change the port the server is hosted at. The default is `3000`.
+- `--ref-resolver <ref-resolver-function-path>`: Path to a JavaScript file containing a `_ref` resolver function to be used as the app default `_ref` resolver.
+- `--watch <paths...>`: A list of paths to files or directories that should be watched for changes. Globs are supported. Specify each path to watch separated by spaces.
+- `--watch-ignore <patterns...>`: A list of paths to files or directories that should be ignored by the file watcher. Globs are supported. Specify each path to watch separated by spaces.
+- `--skip-codemod-check`: Suppress warnings about pending codemod upgrades.
+
+## emails
+
+The `emails` command previews the [notification](/notifications) emails your app renders, using [React Email](https://react.email/)'s preview server. It builds the app, renders each notification from its `testData`, and opens the preview so you can iterate on templates without sending real mail. It warns when a template renders a data key your `testData` is missing (which would show as an empty section), and errors if the app has no `notifications:` section.
+
+The preview tooling (`react-email`) is installed just-in-time by this command — it is never a dependency of your app or its production server.
+
+- `--config-directory <config-directory>`: Change the config directory. The default is the current working directory.
+- `--disable-telemetry`: Disable telemetry.
+- `--log-level <level>`: The minimum severity of logs to show in the CLI output. Options are `debug`, `info`, `warn` or `error`. The default is `info`.
+- `--port <port>`: Change the port the email preview server is hosted at. The default is `3001`.
+- `--ref-resolver <ref-resolver-function-path>`: Path to a JavaScript file containing a `_ref` resolver function to be used as the app default `_ref` resolver.
+- `--server-directory <server-directory>`: Change the server directory, the directory in which the production server is placed. The default is `<config-directory>/.lowdefy/server`.
+
+## agent-setup
+
+The `agent-setup` command sets up a project for AI coding agents. It writes `.mcp.json` registering the dev server's [`lowdefy-docs` MCP endpoint](/ai-agent-docs), a Claude Code skill at `.claude/skills/lowdefy-config/SKILL.md`, and a `## Lowdefy` section in `AGENTS.md`. Existing files are merged, not overwritten.
+
+- `--config-directory <config-directory>`: Change the config directory. The default is the current working directory.
+- `--disable-telemetry`: Disable telemetry.
+- `--log-level <level>`: The minimum severity of logs to show in the CLI output. Options are `debug`, `info`, `warn` or `error`. The default is `info`.
+- `--port <port>`: The port your dev server runs on, used in the generated URLs. The default is `3000`.
+
+## init
+
+The `init` command initializes a Lowdefy application. It creates the `lowdefy.yaml` and `.gitignore` in the working directory.
+
+- `--disable-telemetry`: Disable telemetry.
+- `--log-level <level>`: The minimum severity of logs to show in the CLI output. Options are `debug`, `info`, `warn` or `error`. The default is `info`.
+
+## init-docker
+
+The `init-docker` command initializes a Dockerfile in the config directory that can be used to build a Docker image of the Lowdefy app.
+
+- `--config-directory <config-directory>`: Change the config directory. The default is the current working directory.
+- `--disable-telemetry`: Disable telemetry.
+- `--log-level <level>`: The minimum severity of logs to show in the CLI output. Options are `debug`, `info`, `warn` or `error`. The default is `info`.
+
+## init-vercel
+
+The `init-vercel` command initializes the installation scripts needed to deploy an app on [Vercel](https://vercel.com). It creates a directory called deploy, and a script called vercel.install.sh. It also creates a README file with instructions on how to configure Vercel.
+
+- `--config-directory <config-directory>`: Change the config directory. The default is the current working directory.
+- `--disable-telemetry`: Disable telemetry.
+- `--log-level <level>`: The minimum severity of logs to show in the CLI output. Options are `debug`, `info`, `warn` or `error`. The default is `info`.
+
+## upgrade
+
+The `upgrade` command upgrades a Lowdefy app to a newer version by walking you through migration prompts that handle breaking changes.
+
+It fetches the latest `@lowdefy/codemods` package, resolves the version chain from your current version to the target, and presents migration prompts phase by phase.
+
+```
+pnpx lowdefy@5 upgrade
+pnpx lowdefy@5 upgrade --to 6.0.0
+```
+
+- `--to <version>`: Target version to upgrade to. Defaults to the latest stable release.
+- `--plan`: Show the upgrade plan without executing.
+- `--resume`: Resume a previously interrupted upgrade.
+- `--config-directory <config-directory>`: Change the config directory. The default is the current working directory.
+- `--log-level <level>`: The minimum severity of logs to show in the CLI output. Options are `debug`, `info`, `warn` or `error`. The default is `info`.
+
+### How it works
+
+1. Reads your current version from `lowdefy.yaml`.
+2. Queries npm for the latest stable Lowdefy version (or uses `--to`).
+3. Fetches `@lowdefy/codemods@latest` — the codemods package containing all migration prompts.
+4. Resolves the upgrade chain — which intermediate versions need codemods.
+5. Presents migration prompts phase by phase. Each prompt can be copied to clipboard for use with any AI coding tool, viewed as a manual guide, or skipped for later.
+6. Updates `lowdefy.yaml` after each phase and suggests a git commit.
+
+See the [Upgrade Guide](/upgrade-guide) for more detail on how the upgrade system works.
+
+## start
+
+The `start` command starts a Lowdefy production server. To start a Lowdefy server, tha app should first be built using the `build` command.
+
+- `--config-directory <config-directory>`: Change the config directory. The default is the current working directory.
+- `--disable-telemetry`: Disable telemetry.
+- `--log-level <level>`: The minimum severity of logs to show in the CLI output. Options are `debug`, `info`, `warn` or `error`. The default is `info`.
+- `--port <port>`: Change the port the server is hosted at. The default is `3000`.
+- `--server-directory <server-directory>`: Change the server directory, the directory in which the production server is placed. The default is `<config-directory>/.lowdefy/server`.
+
+
+#### Examples
+
+
+Run the dev server, watching a relative directory for file changes:
+```txt
+pnpx lowdefy@5 dev --watch ../other-project
+```
+
+Run the dev server, ignoring the public directory:
+```txt
+pnpx lowdefy@5 dev --watch-ignore public/**
+```
+
+
+
+# Module Fetching
+
+When your app uses [modules](/modules), the build automatically fetches module sources during the build phase. GitHub modules are downloaded as tarballs and cached in `.lowdefy/modules/`. Multiple module entries from the same monorepo share a single cache entry. Local `file:` sources are read directly from disk.
+
+For private GitHub repositories, set the `GITHUB_TOKEN` environment variable:
+
+```
+GITHUB_TOKEN=ghp_your_token_here
+```
+
+The CLI also checks for `gh` CLI credentials and git credential helpers as fallbacks.
+
+In development mode (`lowdefy dev`), local module sources (`file:` paths) are watched for changes and trigger rebuilds automatically.
+
+# Configuration
+
+All the CLI options can either be set as command line options, or the `cli` config object in your `lowdefy.yaml` file. Options set as command line options take precedence over options set in the `lowdefy.yaml` file. The config in the `lowdefy.yaml` cannot be referenced using the `_ref` operator, but need to be set in the file itself.
+
+Options set in the `lowdefy.yaml` should be defined in camelCase. The options that can be set are:
+- `devDirectory: string`: Change the dev directory, the directory in which the development server is placed. The default is `<config-directory>/.lowdefy/dev`.
+- `disableTelemetry: boolean`: Disable telemetry.
+- `logLevel: enum`: The minimum severity of logs to show in the CLI output. Options are `debug`, `info`, `warn` or `error`. The default is `info`.
+- `noOpen`: Do not open a new tab in the default browser.
+- `port: number`: Change the port the server is hosted at. The default is `3000`.
+- `refResolver: string`: Path to a JavaScript file containing a `_ref` resolver function to be used as the app default `_ref` resolver.
+- `serverDirectory: string`: Change the server directory, the directory in which the production server is placed. The default is `<config-directory>/.lowdefy/server`.
+- `watch: string[]`: A list of paths to files or directories that should be watched for changes.
+- `watchIgnore: string[]`: A list of paths to files or directories that should be ignored by the file watcher. Globs are supported.
+- `skipCodemodCheck: boolean`: Suppress warnings about pending codemod upgrades during build and dev.
+
+The `--config-directory` option cannot be set from the `lowdefy.yaml` file.
+
+# Telemetry
+
+The CLI collects usage and error information to help us fix bugs, prioritize features, and understand how Lowdefy is being used.
+
+All telemetry can be disabled by setting the `disableTelemetry` flag in `cli` config object in your `lowdefy.yaml` file (this cannot be a reference to another file), or by using the `--disable-telemetry` command line flag.:
+
+###### `lowdefy.yaml`
+```yaml
+lowdefy: LOWDEFY_VERSION
+
+cli:
+  disableTelemetry: true
+```
+
+We collect the following information:
+
+- The CLI version.
+- The Lowdefy version of your app.
+- A random local app id (stored locally in your project folder at `.lowdefy/cli.json`).
+- The CLI command used.
+- Your IP address.
+- Error messages and stack traces for any errors.

package/content/concepts/connections-and-requests.md

@@ -0,0 +1,7 @@
+# Connections and Requests
+
+In a Lowdefy app you can integrate with other services like API's or databases using `connections` and `requests`. Connections configure the settings to the external service, and often contain parameters like connection strings, urls and secrets like passwords or API keys. Requests are used to interact with the connection, such as inserting a data record, executing a query or calling an API end-point.
+
+> Sensitive information like passwords or API keys are often required to use external services. The <a href = "./_secret">_secret</a> operator should be used to reference these secrets, they should never be coded directly in your app, or committed to source control.
+
+> The <code>_user</code> operator should be used under <code>properties</code> and not <code>payload</code>. This is important since operators under <code>payload</code> are evaluated on the client, and are therefore vulnerable to users with malicious intent.

package/content/concepts/custom-html.md

@@ -0,0 +1,3 @@
+# Custom HTML
+
+> SECURITY WARNING: Custom HTML can execute JavaScript inside your Lowdefy app. Insecure code can expose your app or data. Since Lowdefy doesn't validate your custom code, make sure that you only load trusted code.

package/content/concepts/custom-styling.md

@@ -0,0 +1,161 @@
+# Custom Styling
+
+Lowdefy provides several ways to style blocks and customize the look of your app:
+
+- **`class`** — Apply CSS class names (including Tailwind CSS utility classes) to blocks.
+- **`style`** — Apply inline CSS styles to blocks. Use `--`-prefixed keys to target specific parts (CSS slots).
+- **`properties.theme`** — Override antd design tokens per block. See [Theming](/theming) for details.
+- **`public/styles.css`** — A global CSS file for custom styles.
+
+## The `class` property
+
+The `class` property applies CSS class names to a block. [Tailwind CSS](https://tailwindcss.com/) is always available in Lowdefy apps, so you can use any Tailwind utility classes directly.
+
+`class` can be a string, an array of strings, or an object keyed by the block's CSS keys:
+
+```yaml
+# String — applied to the block wrapper
+- id: my_card
+  type: Card
+  class: "p-4 shadow-lg rounded-xl"
+
+# Array — all classes joined
+- id: my_card
+  type: Card
+  class:
+    - p-4
+    - shadow-lg
+    - rounded-xl
+
+# Object — target specific parts of the block using CSS keys (-- prefix)
+- id: my_card
+  type: Card
+  class:
+    .element: "shadow-lg"
+    .header: "bg-gray-100"
+    .body: "p-8"
+```
+
+Tailwind responsive prefixes work as expected:
+
+```yaml
+- id: my_box
+  type: Box
+  class: "p-4 sm:p-8 lg:p-16"
+```
+
+### Theme-aware Tailwind classes
+
+Lowdefy bridges antd design tokens to Tailwind, so utility classes like `text-primary` and `bg-bg-container` automatically reflect your theme configuration (including dark mode):
+
+```yaml
+- id: themed_card
+  type: Box
+  class: "bg-bg-container text-text-primary border border-border rounded-lg p-4"
+```
+
+See [Theming](/theming) for the full list of bridged tokens and how to add custom Tailwind tokens via `theme.tailwind`.
+
+## The `style` property
+
+The `style` property applies inline CSS styles to a block. When used with flat CSS properties (no `--` prefix), it targets the block's layout wrapper:
+
+```yaml
+- id: my_block
+  type: Box
+  style:
+    maxWidth: 800
+    margin: "0 auto"
+```
+
+To target specific parts of a block, use `.`-prefixed **CSS slot keys**. Each block declares which slots it supports in its `meta.cssKeys`. Common keys include `.block` (layout wrapper), `.element` (main component), `.header`, `.body`, `.footer`, etc.
+
+```yaml
+- id: my_card
+  type: Card
+  style:
+    .element:
+      borderRadius: 12
+    .header:
+      backgroundColor: "#f5f5f5"
+      fontWeight: bold
+    .body:
+      padding: 32
+```
+
+You can mix flat CSS (which targets `.block`) with explicit slot keys:
+
+```yaml
+- id: my_card
+  type: Card
+  style:
+    .block:
+      flex: 1
+    .element:
+      borderRadius: 12
+```
+
+Each block's documentation page lists its supported CSS keys.
+
+> **Note:** The responsive `style.sm`, `style.md` breakpoint syntax from v4 has been removed. Use Tailwind responsive classes via `class` instead.
+
+## CSS keys
+
+Each block declares named style targets in its `meta.cssKeys`. For example, the [Card](/Card) block supports: `element`, `header`, `body`, `cover`, `actions`, `extra`.
+
+Both `class` (object form) and `style` use `--`-prefixed versions of these keys to target specific parts of a block. The `--` prefix mirrors CSS custom property convention and avoids confusion with CSS property names.
+
+To find the CSS keys for a block, check the block's documentation page.
+
+## Global styles with `public/styles.css`
+
+To add global custom CSS to your app, create a file named `styles.css` in your app's `public` folder. This replaces the `styles.less` file used in v4.
+
+```css
+/* public/styles.css */
+
+h1 {
+  font-size: 32px;
+  color: #2ac8bb;
+}
+
+.my-custom-class {
+  border: 2px solid var(--ant-color-primary);
+  border-radius: 8px;
+}
+```
+
+Additional CSS files can be imported:
+
+```css
+/* public/styles.css */
+@import 'other.css';
+```
+
+## CSS variables
+
+Antd v6 uses CSS custom properties (CSS variables) for all its design tokens. You can reference these in your custom CSS or inline styles:
+
+```css
+/* Access antd theme tokens as CSS variables */
+.my-class {
+  color: var(--ant-color-primary);
+  background: var(--ant-color-bg-container);
+  border: 1px solid var(--ant-color-border);
+  font-size: var(--ant-font-size);
+}
+```
+
+These variables are automatically set based on your app's theme configuration. See [Theming](/theming) for how to configure theme tokens.
+
+## Migration from v4
+
+| v4 | v5 |
+|---|---|
+| `public/styles.less` | `public/styles.css` |
+| `@primary-color: #2ac8bb;` | `theme.antd.token.colorPrimary: '#2ac8bb'` in `lowdefy.yaml` |
+| `style.sm.padding: 32` | `class: "p-8 sm:p-4"` |
+| `properties.bodyStyle: {...}` | `style: { .body: {...} }` |
+| `@import 'antd/dist/antd.dark.less';` | `theme.antd.algorithm: dark` in `lowdefy.yaml` |
+
+See the [Migration Guide](/v4-to-v5) for full details.