@lowdefy/docs-content 0.0.0-experimental-20260928120643 → 6.1.0

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

@@ -2,92 +2,45 @@
 
 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. It is always on in dev, and never part of your production server. When your app sets `config.basePath`, the dev server serves these routes under the base path too, like the rest of the app: with `basePath: /app` they live at `/app/lowdefy-docs`. `lowdefy mcp` finds the right address by itself.
+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.
 
-## Connect your agent: `lowdefy mcp`
+## The MCP endpoint
 
-Run `lowdefy agent-setup` once in your project. It registers the `lowdefy-docs` MCP server in `.mcp.json`:
+The dev server exposes an MCP server (streamable HTTP) at:
 
-```json
-{
-  "mcpServers": {
-    "lowdefy-docs": {
-      "type": "stdio",
-      "command": "node",
-      "args": ["apps/main/node_modules/lowdefy/dist/index.js", "mcp"]
-    }
-  }
-}
+```
+http://localhost:3000/lowdefy-docs/mcp
 ```
 
-Your agent client starts `lowdefy mcp` itself at the start of each session, so the tools are always there — whether or not a dev server is running yet. Nothing in the entry names a port, so the same checked-in file works in every git worktree.
-
-`lowdefy mcp` sends each tool call to the dev server of the app and checkout the agent is working in:
-
-- **It works out the app** from the session's working directory. Every tool also takes an optional `directory` argument — pass it when the repository holds several apps, or when an agent works in a different git worktree from the session (a subagent in its own worktree, for example).
-- **It only acts on the session's checkout and its git worktrees.** Starting a dev server runs the app's `package.json` dev script, so a `directory` outside the checkout the session started in (and outside `git worktree list` of that repository) is refused. When the agent client supports MCP elicitation, `lowdefy mcp` asks you first instead; your answer holds for the session.
-- **It starts the dev server when needed**, through the [Lowdefy hub](/cli#hub): a small per-user background process that gives each app its own port, runs the app's own dev script (so a secrets-manager wrapper still applies — set `cli.devScript` if several scripts run `lowdefy dev`), and stops servers nobody uses. A dev server you started yourself with `lowdefy dev` is used as it is, and never stopped by an agent.
-- **Every result starts with the app and checkout it came from**, for example `apps/main @ app-wt-invoices · http://localhost:4102`, so an agent never mistakes another worktree's answer for its own.
-
-Agents manage the dev server with these tools, and never run `lowdefy dev`, choose ports, or kill processes themselves:
-
-| Tool                 | Purpose                                                                                                                                                                                 |
-| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `lowdefy_dev_start`  | Start the app's dev server (or return the running one) and wait until it is ready. `restart: true` after local plugin or `.env` changes; `clean: true` also deletes the build directory |
-| `lowdefy_dev_stop`   | Stop the app's dev server if the hub started it                                                                                                                                         |
-| `lowdefy_dev_status` | Owner, state, URL and build status, without starting anything                                                                                                                           |
-| `lowdefy_dev_logs`   | Recent output of a hub-started dev server, optionally filtered                                                                                                                          |
-| `lowdefy_run_tests`  | Run the app's journeys (`tests/journeys/*.yaml`, as `lowdefy test` does) against its dev server and return each result as data                                                          |
-| `lowdefy_dev_list`   | Dev servers across the checkout's apps and other checkouts                                                                                                                              |
-
-The dev server itself also serves the MCP endpoint over streamable HTTP at `/lowdefy-docs/mcp`, for clients that connect by URL. Through `lowdefy mcp`, restart is `lowdefy_dev_start` with `restart: true` rather than `lowdefy_restart`.
-
-The `/lowdefy-docs` tools accept requests from agents and tools on your machine and from the dev app's own pages; a request a browser makes on behalf of another website is refused.
-
-## The tools
-
-The dev server 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_search_icons`           | Search icon names: semantic names first, then Lucide names, then the names of installed icon sets (qualified). Never invent an icon name                                                                               |
-| `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_check`                  | Validate the whole app as `lowdefy build` would, without building — every page, and the prod-only checks dev shows as warnings come back as errors. Call before calling a change done                                  |
-| `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; `width`, `height` and `colorScheme: "dark"` check a phone layout or dark mode                                                           |
-| `lowdefy_run_journey`            | Drive a page headless through declarative steps (`click`, `fill`, `goto`, `email`, `as`, `expect`, …) and assert state, visibility, text, url, title or email — verify behaviour, not just layout                      |
-| `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, as a given `user`, to verify data shape (read-only unless opted in)                                                                                                             |
-| `lowdefy_run_endpoint`           | Execute an Api endpoint routine with a test payload, as a given `user` or as a system context (`system: true`), to see what it returns, rejects or throws (needs `allowWriteRequests`; a `:reject` comes back as data) |
-| `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_restart`                | Restart the dev server process — after editing a local plugin's server-side code, or when `build_status` looks stale. Then call `lowdefy_build_status` with `wait: true`, which answers once the server is back        |
-| `lowdefy_checkpoint`             | Snapshot all config files before risky changes                                                                                                                                                                         |
-| `lowdefy_revert_checkpoint`      | Restore config files from a checkpoint                                                                                                                                                                                 |
-
-## Hazards — what the schema cannot tell you
-
-A hazard is a behaviour of a type that its schema does not show, but that an agent must know before writing config: the `Html` block sanitises its content, so a `<style>` tag is stripped; closing a `Modal` keeps the state of the blocks inside it, while `visible: false` prunes it; `_state` inside a request's `properties` is always `undefined`; a `_ref` to a `.njk` file renders at build time. Each hazard is `{ id, message, see }` — a stable kebab-case `id`, one or two sentences saying what happens and what to do instead, and a docs slug (or `null`) for `lowdefy_get_doc`.
-
-`lowdefy_get_schema`, `lowdefy_get_doc` (when looked up by kind and type) and `lowdefy_find_config` (per match) return `hazards` alongside their normal result — `lowdefy_get_doc` appends them as a `## Hazards` section of the markdown. Some hazards are contextual: `tenant-wall-lookup` is only returned for a request whose connection is tenant-walled, so `find_config` on that request explains the wall's `$lookup` injection while the same request over a `tenant: shared` connection stays quiet.
-
-Hazards come from two places. Framework-level hazards ship with `@lowdefy/docs-content` (`hazards.json`). Type-attached hazards are declared by the plugin: a block sets `meta.hazards`, a request sets `meta.hazards` on the request function, and an operator package exports a `./metas` module with `{ hazards }` per operator — see [Plugins](/plugins-introduction). Local plugins in your project use the same channel, so your own blocks can warn an agent about their own surprises.
+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                                |
 
 ## Annotate your app — point, draw, copy, paste
 
@@ -115,57 +68,19 @@ Hold **Option** (macOS) or **Alt** (Windows/Linux) and click any element in your
 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` with `wait: true` (`GET /lowdefy-docs/build-status?wait=true`) — it answers once the dev server has processed your edit, rather than with the build before it. That includes a server restart or plugin install the edit needs (a new connection type, a new plugin package, a `.env` change), so the next call reaches a ready server. Did the build succeed? Errors come back with the exact source file and location. A build that fails with an internal error carries its message, stack and the config file it was resolving.
-3. Pages are built when they are first requested, so the config build's status says nothing about page content. With `wait: true`, build status also builds every page your edit touched (a page whose files changed since its last build, a page built before the latest config build, or a page file changed since the dev server started) and reports under `pages`: `checked` lists the pages it built, `failed` the pages whose last build failed with their errors, `changedSinceBuild` pages changed on disk that the dev server has not rebuilt yet, and `unbuilt` how many pages nothing has built since the dev server started. `lowdefy_check` validates every page.
-4. Call `lowdefy_get_page_config` to confirm the page builds, and `lowdefy_screenshot_page` to see it rendered.
-5. Runtime errors from the browser (operator errors, block render errors) also appear in `lowdefy_build_status` under `clientErrors`, so problems that only show at runtime still reach the agent.
-6. Server-side failures appear beside them under `serverErrors` — a request whose database filter is malformed, an endpoint step that throws, an MCP tool call or an agent tool call that fails — each with the yaml `source` (`file:line`) and `config` path that produced it, plus the `endpointId`, `requestId` and `pageId` where known. The store holds the last 50 errors and is cleared on dev server restart.
-7. Each browser and server error carries the `buildId` it happened under: the time of the latest config build or page edit. Errors from before the current build are listed apart under `earlierErrors`, since they may already be fixed; `clientErrors` and `serverErrors` hold only errors under the current build.
-
-### Events are pushed — no need to poll
-
-The dev server pushes what changed instead of waiting to be asked. Two channels carry the same events:
-
-- **MCP clients** receive them as `notifications/message` from logger `lowdefy` on the standalone GET stream of `/lowdefy-docs/mcp` (the server declares the `logging` capability, so any MCP client surfaces them). Failed builds arrive at level `error`, everything else at `info`.
-- **Everything else** uses `GET /lowdefy-docs/events`, a Server-Sent Events stream — `curl -N http://localhost:3000/lowdefy-docs/events` — with one frame per event, named by the event type.
-
-Every event carries `type` and an ISO `timestamp`. The four types:
-
-| Type           | When                                                            | Carries                                                                                                               |
-| -------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| `restart`      | First event on every connection                                 | `bootedAt` — the dev server process start time, so a reconnecting client can tell a restart from a dropped connection |
-| `build`        | Every time a rebuild finishes, success or failure               | `status`, `errorCount`, `warningCount`, `errors`, `warnings`, and `stale` / `staleSince` (see below)                  |
-| `client_error` | A browser reports a runtime error                               | The same entry `lowdefy_build_status` lists under `clientErrors`                                                      |
-| `server_error` | A request, endpoint, MCP tool or agent tool fails on the server | The same entry `lowdefy_build_status` lists under `serverErrors`                                                      |
-
-Events are not buffered: a client that connects after an event missed it, and should call `lowdefy_build_status` — which is derived from the same `build/buildStatus.json` — for the current picture. Act on a `build` event with `status: "error"` immediately; `lowdefy_build_status` remains the full report.
-
-### When a build fails, answers are marked stale
-
-A failed rebuild does not take the dev server down — it keeps serving the last build that succeeded, so you can carry on looking at the app while you fix the error. That means every tool can keep answering from a build that predates the latest edits, which is a trap for an agent.
-
-So while the last build is failing, every answer says so:
-
-- MCP tool results start with a `STALE: ...` text item.
-- JSON responses from `/lowdefy-docs` carry `stale: true`, `staleSince` and `staleReason`.
-- Markdown responses are prefixed with a `> STALE: ...` banner.
-- Every `/lowdefy-docs` response carries the `X-Lowdefy-Stale` and `X-Lowdefy-Stale-Since` headers.
-
-Nothing is refused — the last-known-good schema or page config is often exactly what you need while fixing the build. The flag disappears as soon as a build succeeds. Call `lowdefy_build_status` (or `GET /lowdefy-docs/build-status`) for the errors.
-
-Some build warnings are only warnings in `lowdefy dev` — they fail `lowdefy build`. Those carry `"prodError": true` in `lowdefy_build_status`, are printed in the dev terminal as `[ConfigWarning · fails in prod] …`, and are badged **fails in prod** on a dark-orange bar in the browser error bar. Treat them as errors: the production build will not pass until they are fixed.
+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.
 
-A headless capture waits for the page's full async lifecycle before it reads anything: `onInit`, `onInitAsync`, `onMount` and `onMountAsync`, every in-flight request, and the first message on each websocket subscription. A page whose data arrives through an `onMountAsync` `Request` action is therefore captured with its data, not empty. If a page has not settled within 15 seconds the result is still returned, carrying `ready: false` and a note — read that result as a snapshot of a page that was still loading, not as the page's settled state. One case escapes the wait: an event with a `debounce` is not yet marked loading during its delay, so a debounced `onMountAsync` can be captured before it runs.
-
 ## Auth-protected pages
 
-The headless renderer behind `lowdefy_screenshot_page` and `lowdefy_inspect_state` authenticates as a signed-in user, so pages with `auth.public: false` render for the agent instead of bouncing to the sign-in page. That default user carries **no roles**, so a page or request gated on a role still comes back refused or empty.
+The headless renderer behind `lowdefy_screenshot_page` and `lowdefy_inspect_state` authenticates as a signed-in user, so pages with `auth.public: false` render for the agent instead of returning a 404. That default user carries **no roles**, so a page or request gated on a role still comes back refused or empty.
 
-To act as a specific caller, pass `user` — every tool that renders a page headless accepts it (`lowdefy_screenshot_page`, `lowdefy_run_journey`, `lowdefy_inspect_state`, `lowdefy_eval_operator`, `lowdefy_load_state`), as do `lowdefy_run_request` and `lowdefy_run_endpoint`:
+To act as a specific caller, pass `user` — every tool that renders a page headless accepts it: `lowdefy_screenshot_page`, `lowdefy_inspect_state`, `lowdefy_eval_operator` and `lowdefy_load_state`:
 
 ```json
 { "pageId": "users", "user": { "roles": ["admin"] } }
@@ -173,9 +88,9 @@ To act as a specific caller, pass `user` — every tool that renders a page head
 
 It is merged over the default user, so `{"roles": [...]}` is usually all you need. No auth engine runs for an injected caller, so nothing derives the rest of the record — include `email`, `profile` or `attributes` in the object if the page reads them. Every call opens its own browser context, so one call can act as an admin and the next as a plain member.
 
-`user` applies to the headless renderer only — it is never applied to a page you open in your own browser, which carries your real session and cannot be re-identified. `lowdefy_inspect_state` and `lowdefy_eval_operator` normally prefer your open tab, so passing `user` selects the headless source instead; combining it with `source: "tab"` is an error rather than a silently ignored role, as is combining it with `lowdefy_load_state`'s `mode: "registry-only"` (that mode hands you a URL to open yourself). The plain HTTP routes take the same param: `?user={"roles":["admin"]}` on the GET routes, a `user` key in the body of `POST /lowdefy-docs/journey`, `POST /lowdefy-docs/eval-operator`, `POST /lowdefy-docs/state-checkpoints/load`, `POST /lowdefy-docs/run-request` and `POST /lowdefy-docs/run-endpoint`. They answer a malformed or contradictory `user` with a `400`, distinct from the `502` a failed render returns.
+`user` applies to the headless renderer only — it is never applied to a page you open in your own browser, which carries your real session and cannot be re-identified. `lowdefy_inspect_state` and `lowdefy_eval_operator` normally prefer your open tab, so passing `user` selects the headless source instead; combining it with `source: "tab"` is an error rather than a silently ignored role, as is combining it with `lowdefy_load_state`'s `mode: "registry-only"` (that mode hands you a URL to open yourself). The plain HTTP routes take the same param: `?user={"roles":["admin"]}` on the GET routes, a `user` key in the body of `POST /lowdefy-docs/eval-operator` and `POST /lowdefy-docs/state-checkpoints/load`. They answer a malformed or contradictory `user` with a `400`, distinct from the `502` a failed render returns.
 
-To bypass login for the whole dev server — your own browser included — start it with a mock user instead: `lowdefy dev --mock-user '{"id":"dev","roles":["admin"]}'` (or configure `auth.dev.mockUser`). See [Auth Configuration](/auth-configuration#mock-user-for-testing-dev-server-only).
+To bypass login for the whole dev server — your own browser included — start it with a mock user instead: `lowdefy dev --mock-user '{"sub":"dev","roles":["admin"]}'` (or configure `auth.dev.mockUser`). See [Auth Configuration](/auth-configuration#mock-user-for-testing-dev-server-only).
 
 ## State checkpoints — put the app in a known state
 
@@ -198,11 +113,7 @@ Loading it back (`lowdefy_load_state`) serves the recorded request data from the
 
 ## 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. The page is built first when it changed since its last build, so the request that runs is the one in the config now; a page that fails to build answers `refused: true` with its `buildErrors`.
-
-A response over 40,000 serialized characters is not returned inline: it is written in full to a JSON file under `.lowdefy/responses/` in the app directory, and the result carries `responseFile` (its path), `responseChars` and, for an array, `responseItems`. Pass `saveResponse: true` to always write the response there. `lowdefy_run_endpoint` does the same. Only the 20 most recent response files are kept.
-
-Pass `user` to run the request as a specific caller — `{ "pageId": "users", "requestId": "get_users", "user": { "roles": ["admin"] } }`. Without `user` the request runs as a roleless anonymous caller, so a tenant-walled or role-gated request returns empty rows rather than an error. Impersonation never unlocks writes: the write gate below applies to every caller. Write requests are refused unless you opt in:
+`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:
@@ -210,219 +121,97 @@ cli:
     allowWriteRequests: true
 ```
 
-## Running endpoints
+This is dev-only — enable it when you're comfortable with the agent writing to your dev data.
 
-`lowdefy_run_endpoint` (or `POST /lowdefy-docs/run-endpoint`) executes an `Api` endpoint routine headlessly with a test payload, so the agent can verify what a routine returns, rejects or throws without clicking through the page that calls it:
+## Setting up a project — one command
 
-```json
-{ "endpointId": "create_order", "payload": { "sku": "A1" }, "user": { "roles": ["admin"] } }
+```bash
+npx lowdefy agent-setup
 ```
 
-Endpoints are not classified read-only — a routine has no `checkWrite` meta, and a single routine can read, write, call other endpoints and send notifications — so running one always requires the same `cli.agentTools.allowWriteRequests: true` opt-in as write requests. Without it the tool answers `refused: true` with the reason and how to enable it, and nothing runs.
+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.
 
-The result is the same `{ error, response, status, success }` object the HTTP endpoint route returns. A `:reject` or `:throw` in the routine is not a tool failure: it comes back as `success: false` with `status: "reject"` or `"error"` and the routine's own `error`, so the agent can assert on the shape it designed. `InternalApi` endpoints are refused with the same message HTTP callers get, an unknown `endpointId` answers `refused: true`, and faults that escape the routine (an auth refusal, a missing connection) come back as `error: { name, message, source, configKey }`. Only malformed input — a missing `endpointId` or a non-object `user` — is a `400`.
+## Using it with Claude Code manually
 
-Scheduled and detached-only endpoints are `InternalApi` by design, so a plain run refuses them. Pass `system: true` to run the routine as a system context instead — the same code path `/api/cron` and `/api/detached` use: no session, no user (`_user` is `undefined`), the endpoint's `auth` is not checked, and `InternalApi` endpoints are allowed. This is the local test path for a `schedules` routine, without setting `CRON_SECRET` or curling the cron route:
+Add the MCP server to your project so Claude Code can use it. In your project directory run:
 
-```json
-{ "endpointId": "purge_stale_conversations", "payload": { "mode": "full" }, "system": true }
+```bash
+claude mcp add --transport http lowdefy-docs http://localhost:3000/lowdefy-docs/mcp
 ```
 
-`system` cannot be combined with `user` (a `400`); everything else — the `allowWriteRequests` gate, the result shape, rejects as data — is unchanged. One limit: a nested `CallApi` step with `detached: true` is not faked. It still dispatches over HTTP against the dev server's origin and needs `CRON_SECRET` set, so without it the routine's own error comes back as the result.
-
-This is dev-only — enable it when you're comfortable with the agent writing to your dev data.
-
-## Journeys — verify behaviour, not just layout
-
-A screenshot shows what rendered; it cannot tell the agent whether the form submits, the modal opens or the filter works. `lowdefy_run_journey` (or `POST /lowdefy-docs/journey`) opens a page headless and drives it through a declarative list of steps — a tiny Playwright — then reports what happened as data. Blocks are addressed by their `blockId`, through the same `#bl-<blockId>` DOM contract `@lowdefy/e2e-utils` uses, so a journey reads like the config it tests:
+Or commit a `.mcp.json` file at your project root so the whole team gets it:
 
 ```json
 {
-  "pageId": "new_customer",
-  "user": { "roles": ["admin"] },
-  "urlQuery": { "ref": "campaign-1" },
-  "steps": [
-    { "fill": { "blockId": "name", "value": "Ada Lovelace" } },
-    { "select": { "blockId": "country", "value": "United Kingdom" } },
-    { "click": "submit" },
-    { "wait": { "request": "create_customer" } },
-    { "expect": { "state": { "path": "created", "equals": true } } },
-    { "expect": { "visible": "success_modal" } },
-    { "expect": { "text": { "blockId": "success_message", "contains": "Ada Lovelace" } } },
-    { "screenshot": "after-submit" },
-    { "press": "Escape" },
-    { "click": "go_to_list" },
-    { "expect": { "url": { "contains": "/customers" } } }
-  ]
-}
-```
-
-Every step is an object with exactly one key:
-
-| Step                                                | What it does                                                                                                                                                                                                                              |
-| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `{ "click": target }`                               | Clicks the block — its interactive control (button, link, input, checkbox…) when it has one, otherwise the block itself — or the control a target object narrows to (below)                                                               |
-| `{ "fill": { ...target, value } }`                  | Fills the block's (or grid cell's) `input` or `textarea` with `value` (converted to a string)                                                                                                                                             |
-| `{ "select": { ...target, value } }`                | Opens the block's (or grid cell's) dropdown and clicks the option whose text is exactly `value`; a native `<select>` inside the block is set by label instead, and a radio, button or segmented selector's option is clicked by its label |
-| `{ "press": key }`                                  | Presses a key or chord, e.g. `"Enter"`, `"Escape"`, `"Mod+k"` — `Mod` becomes `Meta` or `Control` for the platform the page reports, the same way the app's shortcuts resolve it                                                          |
-| `{ "back": true }`                                  | Goes back one page, like the browser's Back button; fails when the journey has not navigated from an earlier page                                                                                                                         |
-| `{ "goto": pageId }`                                | Loads a page like a typed URL (`{ pageId, urlQuery }` adds a query); a protected page may redirect to sign-in, so assert where it landed                                                                                                  |
-| `{ "email": { to, subject? } }`                     | Opens the newest email to `to` that arrived during the journey, waiting for it; `click` follows its links by text. Needs `LOWDEFY_DEV_SMTP_PORT`                                                                                          |
-| `{ "as": name }`                                    | Switches to another person with their own browser and cookies; the journey starts as `"main"`, and a new name opens the journey's page                                                                                                    |
-| `{ "wait": { "ms": n } }`                           | Sleeps `n` milliseconds                                                                                                                                                                                                                   |
-| `{ "wait": { "request": requestId } }`              | Waits until the request has finished loading                                                                                                                                                                                              |
-| `{ "wait": { "state": path } }`                     | Waits until the state path is defined                                                                                                                                                                                                     |
-| `{ "screenshot": name? }`                           | Captures a PNG of the viewport; returned with the result (`true`, `null` or a missing name defaults to `step-<index>`)                                                                                                                    |
-| `{ "expect": { "state": { path, equals } } }`       | The state at `path` structurally equals `equals` (key order does not matter); a path that does not exist reads as `null`, so `equals: null` also passes for a misspelt path                                                               |
-| `{ "expect": { "visible": target } }`               | The block, or the control a target narrows to, is visible                                                                                                                                                                                 |
-| `{ "expect": { "text": { ...target, contains } } }` | The block's text — or a grid row's or cell's — contains the string                                                                                                                                                                        |
-| `{ "expect": { "url": { contains } } }`             | The page url contains the string                                                                                                                                                                                                          |
-| `{ "expect": { "title": { equals } } }`             | The document title (the browser tab's text) is exactly the string; `{ contains }` checks part of it                                                                                                                                       |
-
-A **target** is a `blockId` string, or an object that narrows the search to a control that is not itself a block — a grid row's cell buttons, a confirm dialog's OK, a dropdown menu's items:
-
-| Target key | Meaning                                                                                                                              |
-| ---------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `blockId`  | The block to search inside                                                                                                           |
-| `row`      | A grid row, zero-based as displayed (`AgGrid*` blocks, `.ag-row[row-index]`); needs `blockId`                                        |
-| `column`   | A grid cell in that row, by the column's `field` or `colId` (`.ag-cell[col-id]`); needs `blockId`                                    |
-| `text`     | The visible interactive control whose text is exactly this — a button label, a tab, a menu item (`"Cat"` never matches `"Category"`) |
-| `nth`      | When several controls match, the zero-based one to use                                                                               |
-
-A radio, checkbox or segmented option is reached through its label: `{ "click": { "blockId": "period", "text": "Month" } }` clicks the Month option of a `SegmentedSelector`, whose own radio input has no size.
-
-`text` without a `blockId` searches the page, front-most layer first — an open dropdown menu (`[role="menu"]`), then an open dialog (`[role="dialog"]`), then the page — so `{ "click": { "text": "Delete" } }` with a confirm dialog open clicks the dialog's Delete and not the grid's, without counting buttons. `fill`, `select` and `expect.text` always need a `blockId`. Unknown target keys are rejected before a browser opens.
-
-```json
-[
-  { "click": { "blockId": "controls_grid", "row": 1, "text": "Delete" } },
-  { "expect": { "visible": { "text": "Are you sure?" } } },
-  { "click": { "text": "Delete" } },
-  { "wait": { "request": "delete_control" } },
-  {
-    "expect": {
-      "text": {
-        "blockId": "controls_grid",
-        "row": 1,
-        "column": "title",
-        "contains": "Key rotation"
-      }
+  "mcpServers": {
+    "lowdefy-docs": {
+      "type": "http",
+      "url": "http://localhost:3000/lowdefy-docs/mcp"
     }
-  },
-  { "click": { "blockId": "controls_grid", "row": 0, "column": "more" } },
-  { "click": { "text": "Archive" } }
-]
-```
-
-Each step gets 5 seconds (Playwright's own auto-waiting — a `click` waits for the block to be attached, visible and enabled; nothing is retried); pass `timeout` (milliseconds, up to 60000) to give every step of a journey longer on a slow machine. After an interaction the runner waits for the page to settle — the event the interaction fired, the requests it called — using the same readiness check the page open uses, so the next `expect` asserts against the outcome instead of racing it. The page opens with the same headless `user` and `urlQuery` handling as the other tools.
-
-A step that fails **stops the journey and comes back as data**, never as a tool error — a failed journey is the answer, not a fault:
-
-```json
-{
-  "pageId": "new_customer",
-  "passed": false,
-  "steps": [
-    {
-      "index": 0,
-      "step": { "fill": { "blockId": "name", "value": "Ada Lovelace" } },
-      "status": "ok",
-      "durationMs": 18
-    },
-    { "index": 1, "step": { "click": "submit" }, "status": "ok", "durationMs": 71 },
-    {
-      "index": 2,
-      "step": { "expect": { "state": { "path": "created", "equals": true } } },
-      "status": "failed",
-      "durationMs": 1
-    },
-    { "index": 3, "step": { "screenshot": "after-submit" }, "status": "skipped", "durationMs": 0 }
-  ],
-  "failure": {
-    "index": 2,
-    "step": { "expect": { "state": { "path": "created", "equals": true } } },
-    "expected": true,
-    "actual": null,
-    "message": "Expected state \"created\" to equal true but found undefined."
-  },
-  "screenshots": [],
-  "state": { "name": "Ada Lovelace", "country": null }
+  }
 }
 ```
 
-`expected` and `actual` hold the compared values for an `expect` step, and for an interaction step what the runner needed (`block "submit" to be actionable`, `option "Chile" in the dropdown of block "country"`) against Playwright's own message. The remaining steps are marked `skipped`. A passing journey returns `passed: true` and no `failure`. The final page `state` is included, pass or fail — it is what the agent needs to write the next assertion. A page holding large request results can have hundreds of KB of state, so when the state is over 10000 characters of JSON the result carries `stateOmitted` instead: its size, each top-level key with its size, and a note. The `state` option picks what comes back:
+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.
 
-| `state`                 | The result carries                                                    |
-| ----------------------- | --------------------------------------------------------------------- |
-| omitted                 | The whole state when it is small, otherwise `stateOmitted`            |
-| `["form.name", "rows"]` | `state: { "form.name": …, "rows": … }`, `null` for a path not defined |
-| `true`                  | The whole state, however large                                        |
-| `false`                 | No state                                                              |
+## Referencing it in a skill
 
-Screenshots taken before the failure are kept: over MCP they arrive as image content after the JSON (with the JSON listing only their names); over HTTP they are base64 in the JSON body.
+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`:
 
-Malformed steps are answered before a browser opens — an unknown key returns `Unknown journey step "hover". Steps are: click, fill, select, press, back, goto, email, as, wait, screenshot, expect.` (a `400` on the HTTP route), distinct from the `502` a render that could not run returns.
+```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.
+---
 
-To test auth itself — sign-up, email verification, sign-in, invitations, organization switching — pass `"user": "none"`: no caller is injected, the journey starts signed out, and the app's own sessions carry through its steps. [Config Tests](/config-tests#testing-sign-up-and-sign-in) covers the mail sink and the database these journeys need.
+# Writing Lowdefy config
 
-Journeys are also the file format of `tests/journeys/*.yaml`, which `lowdefy test` runs through this same route — write the journey the agent used to verify a change, and it becomes the regression test for it.
+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).
 
-## Setting up a project — one command
+Never guess type names or properties. Before writing config:
 
-```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 (`lowdefy mcp`, see [Connect your agent](#connect-your-agent-lowdefy-mcp)), `.claude/skills/lowdefy-config/SKILL.md` teaching Claude Code the workflow, and an `AGENTS.md` section for other coding agents. Add `lowdefy` to your app's `devDependencies` first, so `.mcp.json` runs your app's own version of the CLI; each git worktree then needs its own `pnpm install` (or equivalent) before an agent session starts there.
-
-Projects set up by an earlier version, with an `http://localhost:<port>/lowdefy-docs/mcp` entry, are migrated when you rerun the command: the entry is replaced, per-port entries such as `lowdefy-3010` are removed, and the skill and `AGENTS.md` section it wrote are updated. The server keeps its `lowdefy-docs` name, so tool names and approvals carry over.
-
-## Using it with Claude Code manually
-
-Commit a `.mcp.json` file at your project root, pointing at your app's installed CLI:
+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`.
 
-```json
-{
-  "mcpServers": {
-    "lowdefy-docs": {
-      "type": "stdio",
-      "command": "node",
-      "args": ["node_modules/lowdefy/dist/index.js", "mcp"]
-    }
-  }
-}
+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.
 ```
 
-In a monorepo, use the path to the app's `node_modules`, for example `apps/main/node_modules/lowdefy/dist/index.js`. The MCP server includes instructions that teach the agent the workflow (list types first, then fetch schemas and examples; let `lowdefy mcp` run the dev server), so it works well without any extra prompting.
-
 ## 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/events`                                        | SSE stream of `restart`, `build`, `client_error` and `server_error` events                                                        |
-| `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; `?viewportWidth=390&viewportHeight=844&colorScheme=dark` sets the viewport and colour scheme |
-| `POST /lowdefy-docs/journey`                                      | Drive a page headless through declarative steps and assert what happens; screenshots returned as base64                           |
-| `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)                                                                 |
-| `POST /lowdefy-docs/run-endpoint`                                 | Execute an Api endpoint routine with a test payload and caller (needs `allowWriteRequests`; rejects return as data)               |
-| `GET/POST /lowdefy-docs/checkpoints` + `/revert`                  | Config-file checkpoints                                                                                                           |
-| `GET/POST /lowdefy-docs/state-checkpoints` + `/snapshot`, `/load` | State & data checkpoints                                                                                                          |
-| `POST /lowdefy-docs/restart`                                      | Restart the dev server process (`{reason}` optional; then `build-status?wait=true` answers once it is back)                       |
+| 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
 
@@ -432,7 +221,6 @@ Your project's own plugins (declared under `plugins:` in `lowdefy.yaml`) are inc
 - 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`.
-- Editing a local plugin (a package linked from your workspace) rebuilds the config, so a new or renamed type is defined and a build the plugin broke clears once it is fixed. When the plugin has server-side types (connections, requests, server operators, agents, websockets, notifications, auth) the dev server also restarts, so the new implementation is what runs; block, action and client-operator edits hot-reload through Vite without a restart. If the server still looks stale, call `lowdefy_restart` or `POST /lowdefy-docs/restart`.
 
 ## Docs for crawling agents