@lowdefy/docs-content 6.1.0 → 7.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (285) hide show
  1. package/README.md +1 -0
  2. package/content/actions/downloadcsv.md +1 -1
  3. package/content/actions/emailotpsend.md +58 -0
  4. package/content/actions/emailotpverify.md +79 -0
  5. package/content/actions/getlocalstorage.md +43 -0
  6. package/content/actions/link.md +47 -1
  7. package/content/actions/login.md +25 -5
  8. package/content/actions/logout.md +7 -5
  9. package/content/actions/magiclinkverify.md +117 -0
  10. package/content/actions/pdfmake.md +2 -2
  11. package/content/actions/posthogalias.md +29 -0
  12. package/content/actions/posthogcapture.md +49 -0
  13. package/content/actions/posthogcapturepageleave.md +38 -0
  14. package/content/actions/posthogfeatureflag.md +50 -0
  15. package/content/actions/posthoggroup.md +37 -0
  16. package/content/actions/posthogidentify.md +54 -0
  17. package/content/actions/posthoginit.md +96 -0
  18. package/content/actions/posthogoptin.md +29 -0
  19. package/content/actions/posthogoptout.md +29 -0
  20. package/content/actions/posthogpageview.md +37 -0
  21. package/content/actions/posthogreloadfeatureflags.md +47 -0
  22. package/content/actions/posthogreset.md +28 -0
  23. package/content/actions/posthogsetpersonproperties.md +36 -0
  24. package/content/actions/removelocalstorage.md +28 -0
  25. package/content/actions/resetvalidation.md +5 -3
  26. package/content/actions/setdarkmode.md +3 -3
  27. package/content/actions/setglobal.md +2 -0
  28. package/content/actions/setlocale.md +1 -1
  29. package/content/actions/setlocalstorage.md +34 -0
  30. package/content/actions/setstate.md +2 -0
  31. package/content/actions/validate.md +7 -4
  32. package/content/adapter-reference/mongodbauthadapter.md +46 -0
  33. package/content/agents/agent-endpoint-tools.md +24 -0
  34. package/content/agents/agent-properties.md +13 -3
  35. package/content/agents/agent-server-hooks.md +1 -1
  36. package/content/agents/agentchat.md +43 -7
  37. package/content/agents/agentconversations.md +42 -8
  38. package/content/agents/agents-introduction.md +107 -0
  39. package/content/callback-reference/auth0logoutcallback.md +54 -0
  40. package/content/concepts/ai-agent-docs.md +455 -106
  41. package/content/concepts/blocks.md +150 -0
  42. package/content/concepts/connections-and-requests.md +402 -0
  43. package/content/concepts/custom-html.md +42 -0
  44. package/content/concepts/custom-styling.md +50 -5
  45. package/content/concepts/dynamic-page-content.md +309 -0
  46. package/content/concepts/events-and-actions.md +154 -2
  47. package/content/concepts/four-primitives.md +31 -0
  48. package/content/concepts/html-attributes.md +293 -0
  49. package/content/concepts/i18n.md +8 -3
  50. package/content/concepts/keyboard-shortcuts.md +2 -2
  51. package/content/concepts/layout-overview.md +1 -1
  52. package/content/concepts/logger.md +99 -0
  53. package/content/concepts/lowdefy-api.md +1319 -0
  54. package/content/concepts/lowdefy-schema.md +136 -3
  55. package/content/concepts/menus.md +8 -7
  56. package/content/concepts/module-authoring.md +76 -5
  57. package/content/concepts/modules.md +3 -1
  58. package/content/concepts/notifications.md +180 -0
  59. package/content/concepts/operators.md +7 -0
  60. package/content/concepts/page-and-app-state.md +252 -0
  61. package/content/concepts/page-paths.md +209 -0
  62. package/content/concepts/theming.md +582 -0
  63. package/content/connections/aigateway.md +375 -0
  64. package/content/connections/anthropic.md +169 -2
  65. package/content/connections/awss3.md +178 -2
  66. package/content/connections/axioshttp.md +181 -0
  67. package/content/connections/google.md +169 -2
  68. package/content/connections/mongodb.md +1014 -3
  69. package/content/connections/openai-connection.md +169 -2
  70. package/content/connections/sendgridmail.md +2 -0
  71. package/content/connections/smtp.md +3 -1
  72. package/content/connections/treg.md +329 -0
  73. package/content/container-blocks/affix.md +47 -7
  74. package/content/container-blocks/alert.md +76 -24
  75. package/content/container-blocks/badge.md +100 -24
  76. package/content/container-blocks/box.md +9 -9
  77. package/content/container-blocks/card.md +132 -27
  78. package/content/container-blocks/carousel.md +60 -7
  79. package/content/container-blocks/collapse.md +153 -9
  80. package/content/container-blocks/configprovider.md +35 -13
  81. package/content/container-blocks/confirmmodal.md +69 -23
  82. package/content/container-blocks/content.md +62 -98
  83. package/content/container-blocks/descriptions.md +45 -4
  84. package/content/container-blocks/drawer.md +139 -28
  85. package/content/container-blocks/dropdownmenu.md +119 -31
  86. package/content/container-blocks/flex.md +40 -62
  87. package/content/container-blocks/footer.md +15 -11
  88. package/content/container-blocks/googlemapsheatmap.md +1 -1
  89. package/content/container-blocks/googlemapsscript.md +2 -2
  90. package/content/container-blocks/header.md +71 -36
  91. package/content/container-blocks/label.md +34 -7
  92. package/content/container-blocks/layout.md +52 -34
  93. package/content/container-blocks/masonry.md +17 -71
  94. package/content/container-blocks/mobilemenu.md +131 -88
  95. package/content/container-blocks/modal.md +161 -26
  96. package/content/container-blocks/pageheadermenu.md +138 -31
  97. package/content/container-blocks/pagesidebarlayout.md +230 -27
  98. package/content/container-blocks/pagesidermenu.md +153 -43
  99. package/content/container-blocks/popover.md +34 -31
  100. package/content/container-blocks/result.md +32 -21
  101. package/content/container-blocks/sider.md +85 -122
  102. package/content/container-blocks/span.md +7 -7
  103. package/content/container-blocks/spinner.md +3 -3
  104. package/content/container-blocks/splitter.md +150 -68
  105. package/content/container-blocks/tabs.md +64 -12
  106. package/content/container-blocks/tooltip.md +22 -46
  107. package/content/container-blocks/watermark.md +22 -4
  108. package/content/controls/parallel_for.md +21 -2
  109. package/content/controls/reject.md +24 -3
  110. package/content/controls/return.md +17 -1
  111. package/content/controls/throw.md +1 -0
  112. package/content/controls/try.md +4 -2
  113. package/content/controls/while.md +46 -0
  114. package/content/deployment/deployment-environments.md +10 -7
  115. package/content/deployment/docker.md +22 -7
  116. package/content/deployment/node-server.md +4 -0
  117. package/content/deployment/vercel.md +17 -6
  118. package/content/display-blocks/aggrid.md +33 -16
  119. package/content/display-blocks/anchor.md +16 -15
  120. package/content/display-blocks/avatar.md +57 -37
  121. package/content/display-blocks/breadcrumb.md +70 -21
  122. package/content/display-blocks/button.md +93 -19
  123. package/content/display-blocks/calendar.md +12 -0
  124. package/content/display-blocks/clickablehtml.md +239 -0
  125. package/content/display-blocks/dangeroushtml.md +1 -1
  126. package/content/display-blocks/difflist.md +1 -1
  127. package/content/display-blocks/difftimeline.md +1 -1
  128. package/content/display-blocks/divider.md +64 -3
  129. package/content/display-blocks/dropdownbutton.md +81 -30
  130. package/content/display-blocks/echart.md +35 -1
  131. package/content/display-blocks/eventlog.md +363 -0
  132. package/content/display-blocks/floatbutton.md +129 -42
  133. package/content/display-blocks/html.md +61 -1
  134. package/content/display-blocks/icon.md +250 -67
  135. package/content/display-blocks/img.md +2 -2
  136. package/content/display-blocks/menu.md +146 -73
  137. package/content/display-blocks/message.md +38 -124
  138. package/content/display-blocks/notification.md +94 -222
  139. package/content/display-blocks/paragraph.md +59 -9
  140. package/content/display-blocks/pollingtimer.md +263 -0
  141. package/content/display-blocks/progress.md +96 -17
  142. package/content/display-blocks/qrcode.md +19 -4
  143. package/content/display-blocks/s3download.md +1 -1
  144. package/content/display-blocks/search.md +19 -9
  145. package/content/display-blocks/skeletonbutton.md +1 -0
  146. package/content/display-blocks/skeletoninput.md +1 -0
  147. package/content/display-blocks/statistic.md +75 -17
  148. package/content/display-blocks/steps.md +58 -25
  149. package/content/display-blocks/table.md +2527 -0
  150. package/content/display-blocks/tablelight.md +621 -0
  151. package/content/display-blocks/tag.md +102 -17
  152. package/content/display-blocks/title.md +50 -11
  153. package/content/display-blocks/tour.md +33 -23
  154. package/content/input-blocks/autocomplete.md +81 -9
  155. package/content/input-blocks/buttonselector.md +45 -8
  156. package/content/input-blocks/captcha.md +40 -0
  157. package/content/input-blocks/checkboxselector.md +97 -7
  158. package/content/input-blocks/checkboxswitch.md +33 -3
  159. package/content/input-blocks/colorselector.md +63 -14
  160. package/content/input-blocks/daterangeselector.md +165 -45
  161. package/content/input-blocks/dateselector.md +139 -41
  162. package/content/input-blocks/datetimeselector.md +158 -49
  163. package/content/input-blocks/inputgallery.md +3 -3
  164. package/content/input-blocks/intentinput.md +207 -0
  165. package/content/input-blocks/monthselector.md +120 -52
  166. package/content/input-blocks/multipleselector.md +150 -39
  167. package/content/input-blocks/numberinput.md +98 -12
  168. package/content/input-blocks/pagination.md +70 -14
  169. package/content/input-blocks/paragraphinput.md +51 -37
  170. package/content/input-blocks/passwordinput.md +60 -6
  171. package/content/input-blocks/phonenumberinput.md +59 -26
  172. package/content/input-blocks/placesautocomplete.md +319 -0
  173. package/content/input-blocks/radioselector.md +83 -7
  174. package/content/input-blocks/ratingslider.md +57 -26
  175. package/content/input-blocks/s3uploadbutton.md +24 -24
  176. package/content/input-blocks/s3uploaddragger.md +3 -3
  177. package/content/input-blocks/s3uploadphoto.md +5 -5
  178. package/content/input-blocks/segmentedselector.md +72 -32
  179. package/content/input-blocks/selector.md +109 -21
  180. package/content/input-blocks/switch.md +65 -17
  181. package/content/input-blocks/tableinput.md +445 -0
  182. package/content/input-blocks/tagmultipleselector.md +114 -0
  183. package/content/input-blocks/tagselector.md +114 -0
  184. package/content/input-blocks/textarea.md +32 -3
  185. package/content/input-blocks/textinput.md +70 -29
  186. package/content/input-blocks/tiptapinput.md +1 -1
  187. package/content/input-blocks/tiptapmentioninput.md +2 -2
  188. package/content/input-blocks/titleinput.md +39 -12
  189. package/content/input-blocks/treeinput.md +49 -25
  190. package/content/input-blocks/treemultipleselector.md +127 -10
  191. package/content/input-blocks/treeselector.md +97 -9
  192. package/content/input-blocks/upload.md +64 -15
  193. package/content/input-blocks/uploaddragger.md +17 -1
  194. package/content/input-blocks/uploadphoto.md +18 -1
  195. package/content/input-blocks/weekselector.md +120 -55
  196. package/content/learn/introduction.md +27 -0
  197. package/content/learn/quickstart.md +53 -0
  198. package/content/learn/showcase.md +8 -0
  199. package/content/list-blocks/controlledlist.md +24 -15
  200. package/content/list-blocks/list.md +11 -11
  201. package/content/list-blocks/masonrylist.md +7 -34
  202. package/content/migration/auth-upgrade.md +337 -0
  203. package/content/migration/upgrade-guide.md +1 -0
  204. package/content/migration/v3-to-v4.md +417 -0
  205. package/content/migration/v6-to-v7.md +620 -0
  206. package/content/operators/_agent.md +155 -0
  207. package/content/operators/_app.md +2 -1
  208. package/content/operators/_array.md +122 -1
  209. package/content/operators/_build.md +1 -0
  210. package/content/operators/_credential.md +57 -0
  211. package/content/operators/_cron.md +292 -0
  212. package/content/operators/_date.md +2 -0
  213. package/content/operators/_error.md +24 -1
  214. package/content/operators/_get.md +6 -6
  215. package/content/operators/_hmac.md +78 -0
  216. package/content/operators/_js.md +2 -1
  217. package/content/operators/_location.md +1 -1
  218. package/content/operators/_media.md +13 -0
  219. package/content/operators/_module.md +56 -2
  220. package/content/operators/_operator.md +17 -3
  221. package/content/operators/_path_params.md +82 -0
  222. package/content/operators/_ref.md +258 -0
  223. package/content/operators/_request.md +1 -1
  224. package/content/operators/_request_details.md +6 -0
  225. package/content/operators/_type.md +14 -3
  226. package/content/operators/_url_query.md +2 -0
  227. package/content/operators/_user.md +3 -3
  228. package/content/plugins/plugins-actions.md +10 -0
  229. package/content/plugins/plugins-connections.md +25 -0
  230. package/content/plugins/plugins-dev.md +66 -0
  231. package/content/plugins/plugins-icon-sets.md +267 -0
  232. package/content/plugins/plugins-introduction.md +27 -1
  233. package/content/plugins/plugins.md +19 -0
  234. package/content/plugins/posthog.md +359 -0
  235. package/content/provider-reference/auth-js-providers.md +107 -0
  236. package/content/provider-reference/openidconnectprovider.md +44 -0
  237. package/content/recipes/recipes.md +16 -0
  238. package/content/reference/actions-reference.md +31 -0
  239. package/content/reference/blocks-reference.md +35 -0
  240. package/content/reference/cli.md +403 -0
  241. package/content/reference/connections-reference.md +23 -0
  242. package/content/reference/operators-reference.md +47 -0
  243. package/content/reference/reference.md +16 -0
  244. package/content/reference/schema-reference.md +12 -0
  245. package/content/testing/config-tests.md +677 -0
  246. package/content/testing/e2e-configuration.md +31 -1
  247. package/content/testing/e2e-getting-started.md +1 -1
  248. package/content/testing/e2e-introduction.md +1 -1
  249. package/content/testing/e2e-writing-tests.md +12 -1
  250. package/content/testing/explore-pull-request.md +136 -0
  251. package/content/testing/journey-data-sets.md +326 -0
  252. package/content/tutorial/tutorial-actions-operators.md +2 -2
  253. package/content/tutorial/tutorial-add-blocks.md +2 -2
  254. package/content/tutorial/tutorial-create-page.md +48 -2
  255. package/content/tutorial/tutorial-display-data-page.md +3 -3
  256. package/content/tutorial/tutorial-requests-api.md +155 -0
  257. package/content/tutorial/tutorial-requests-sql.md +153 -0
  258. package/content/tutorial/tutorial-start.md +66 -1
  259. package/content/user-authentication/auth-configuration.md +267 -0
  260. package/content/user-authentication/auth-providers.md +24 -0
  261. package/content/user-authentication/auth-steps.md +141 -0
  262. package/content/user-authentication/login-and-logout.md +160 -8
  263. package/content/user-authentication/mcp-oauth.md +424 -0
  264. package/content/user-authentication/organizations.md +246 -0
  265. package/content/user-authentication/protected-pages-apis.md +97 -0
  266. package/content/user-authentication/roles.md +49 -0
  267. package/content/user-authentication/two-factor.md +229 -0
  268. package/content/user-authentication/user-object.md +58 -0
  269. package/content/user-authentication/users-introduction.md +8 -0
  270. package/content/websockets/websocket-publish.md +105 -0
  271. package/content/websockets/websocket-subscriptions.md +136 -0
  272. package/content/websockets/websockets-introduction.md +101 -0
  273. package/hazards.json +56 -0
  274. package/index.json +3458 -14
  275. package/package.json +10 -1
  276. package/scripts/extractAgentDocs.js +41 -30
  277. package/scripts/hashDocSources.js +38 -0
  278. package/scripts/isRedirectPage.js +26 -0
  279. package/scripts/recordSourceHashes.js +97 -0
  280. package/scripts/resolvePageSections.js +42 -0
  281. package/scripts/sectionKind.js +27 -0
  282. package/content/concepts/cli.md +0 -223
  283. package/content/other/introduction.md +0 -39
  284. package/content/other/next-auth-providers.md +0 -3
  285. /package/content/{other → actions}/updatesession.md +0 -0
@@ -2,45 +2,130 @@
2
2
 
3
3
  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.
4
4
 
5
- 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.
5
+ 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.
6
6
 
7
7
  > The `/lowdefy-docs` route prefix is reserved by the dev server. A page with `id: lowdefy-docs` will not be reachable in dev.
8
8
 
9
- ## The MCP endpoint
10
-
11
- The dev server exposes an MCP server (streamable HTTP) at:
12
-
13
- ```
14
- http://localhost:3000/lowdefy-docs/mcp
15
- ```
16
-
17
- It provides these tools:
18
-
19
- | Tool | Purpose |
20
- | ------------------------ | ----------------------------------------------------------------------- |
21
- | `lowdefy_overview` | Start here — what is installed, counts per kind, and how to use the rest |
22
- | `lowdefy_list_types` | List ALL available types of a kind (blocks, operators, actions, connections, requests) |
23
- | `lowdefy_list_plugins` | Installed plugin packages, including local plugins, and the types each provides |
24
- | `lowdefy_get_schema` | JSON Schema for a specific type — all properties and events |
25
- | `lowdefy_get_examples` | Real YAML usage examples for a block type |
26
- | `lowdefy_get_doc` | A Lowdefy docs page as markdown, by slug or by type name |
27
- | `lowdefy_search_docs` | Keyword search over the Lowdefy docs |
28
- | `lowdefy_get_plugin_doc` | Markdown (READMEs, guides) shipped inside an installed plugin package |
29
- | `lowdefy_build_status` | Current build errors and warnings (with source file locations) plus recent browser runtime errors — call after every edit |
30
- | `lowdefy_get_page_config`| The fully built config for a page, or its structured build errors |
31
- | `lowdefy_screenshot_page`| PNG screenshot of a rendered page (headless Chromium) for visual verification |
32
- | `lowdefy_find_config` | Which yaml file (and line) defines a given page, block, or request id |
33
- | `lowdefy_scaffold_page` | Create a new page yaml file with a canonical minimal structure |
34
- | `lowdefy_app_map` | The whole-app graph: every page, menu, connection, endpoint, and agent in one call |
35
- | `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 |
36
- | `lowdefy_eval_operator` | Evaluate any operator expression against live page state — a REPL for config |
37
- | `lowdefy_run_request` | Execute a request with a test payload to verify data shape (read-only unless opted in) |
38
- | `lowdefy_snapshot_state` | Capture live page state + request responses into a committable checkpoint folder |
39
- | `lowdefy_load_state` | Restore a state checkpoint — headless, or a `?_checkpoint=` URL for manual testing |
40
- | `lowdefy_list_state_checkpoints` | List saved state checkpoints |
41
- | `lowdefy_checkpoint_to_mocks` | Convert a state checkpoint into e2e `mocks.yaml` fixtures |
42
- | `lowdefy_checkpoint` | Snapshot all config files before risky changes |
43
- | `lowdefy_revert_checkpoint` | Restore config files from a checkpoint |
9
+ ## Connect your agent: `lowdefy mcp`
10
+
11
+ Run `npx lowdefy@<app version> agent-setup` once in your project (see _Setting up a project_ below). It registers the `lowdefy` MCP server in `.mcp.json`, pinned to the version of the CLI that ran it:
12
+
13
+ ```json
14
+ {
15
+ "mcpServers": {
16
+ "lowdefy": {
17
+ "type": "stdio",
18
+ "command": "npx",
19
+ "args": ["--prefer-offline", "--yes", "lowdefy@7.1.0", "mcp"]
20
+ }
21
+ }
22
+ }
23
+ ```
24
+
25
+ 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 or a `node_modules` path, so the same checked-in file works in every git worktree, including a fresh one nobody has installed yet: npx keeps the pinned version in the shared npm cache and starts it offline in under a second after the first download.
26
+
27
+ Before it writes the entry, `agent-setup` runs the pinned version's `lowdefy mcp` through npx. A version npm cannot serve — one that is not published, or one from before `lowdefy mcp` — is refused and `.mcp.json` is left as it was, because the file is committed and an entry that fails would leave every teammate's session without tools. To run your own build of the CLI instead, override the entry for yourself only with Claude Code's local scope, which wins over the project and user entries and is never committed: `claude mcp add --scope local lowdefy -- node <path to lowdefy>/dist/index.js mcp`. The refusal prints this command.
28
+
29
+ On native Windows, Claude Code cannot start the plain `npx` command a project entry uses. Add a local-scope entry that runs it through `cmd /c` (`claude mcp add --scope local lowdefy -- cmd /c npx --prefer-offline --yes lowdefy@<version> mcp`), use `agent-setup --user` (below), or work in WSL.
30
+
31
+ ### Every project at once: `agent-setup --user`
32
+
33
+ If you work across several projects, register `lowdefy mcp` once for your user instead:
34
+
35
+ ```bash
36
+ npx lowdefy agent-setup --user
37
+ ```
38
+
39
+ This adds the same `lowdefy` server to Claude Code's user scope (`claude mcp add --scope user lowdefy -- npx --prefer-offline --yes lowdefy@<version> mcp`), pinned to the version of the CLI you run it with, so every session has the Lowdefy tools — in a repository nobody set up, in a directory above several projects, anywhere. It needs no app. It runs that version's `lowdefy mcp` through npx first, which downloads it into the npm cache so the first session does not wait, and refuses a version npm cannot serve. The version must be a published one that has `lowdefy mcp`; until Lowdefy 7 is released, run `npx lowdefy@experimental agent-setup --user`.
40
+
41
+ - On Windows it registers `cmd /c npx ...`, since Claude Code cannot start `npx` there without a shell.
42
+ - Without Claude Code on your `PATH` it prints the entry to add to your agent client's user configuration.
43
+ - Rerun it to move to another version. It replaces the `lowdefy` registration, and an old `lowdefy-docs` one. If Claude Code fails to add the new entry, your existing registration stays in place and the error prints the commands to finish by hand.
44
+ - A project whose `.mcp.json` defines `lowdefy` uses its own entry instead, so a session never has two sets of Lowdefy tools.
45
+
46
+ ### Projects on different Lowdefy versions
47
+
48
+ One session can work with dev servers of several Lowdefy versions, through a `lowdefy mcp` pinned to yet another. When `lowdefy mcp` connects to a dev server, it reads that server's tools: tools it does not know are added to the session's tool list, and a tool both have takes its description and input schema from whichever of the two Lowdefy versions is newer. So each tool follows the newest Lowdefy version the session has met, and the client is told to list the tools again. Tools are never removed during a session, since the session may still use the older app. When `lowdefy mcp` and a dev server run different versions, calls go to the dev server's own tools, and the first result from it carries a note naming both versions and how to match them; a call that fails carries the note every time.
49
+
50
+ Versions are compared only when both are releases, or both have the same major version. An experimental build (`0.0.0-experimental-...`) is not compared with a release of another major, so neither replaces the other's tools.
51
+
52
+ `lowdefy mcp` sends each tool call to the dev server of the app and checkout the agent is working in:
53
+
54
+ - **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).
55
+ - **It acts on the session's checkout, its git worktrees, and repositories you trust.** Starting a dev server runs the app's `package.json` dev script, so an app outside the checkout the session started in (and outside `git worktree list` of that repository) needs your approval — an agent must not run the scripts of a repository it just cloned without you seeing it. See [Working across projects](#working-across-projects).
56
+ - **It tells the agent what to install.** A fresh git worktree has no `node_modules`. When a `package.json` in the app's checkout lists `lowdefy` (in the app directory, or at a monorepo's root) but no `node_modules` from the app up to the checkout root has it, `lowdefy_dev_start` answers with the install command and where to run it, instead of starting a dev script that would fail in a log the agent does not read; the agent runs it and starts again. The command follows the repository: the `packageManager` field in `package.json` first, then the nearest lockfile (`pnpm-lock.yaml`, `yarn.lock`, `bun.lock`, `package-lock.json`, ...), for example `pnpm install` at the workspace root, else `npm install` in the app directory. It looks no higher than the checkout root, so a worktree created inside an installed checkout still counts as not installed. A Yarn Plug'n'Play install, and an app whose dev script brings its own Lowdefy (no `package.json` lists `lowdefy`), are left to run.
57
+ - **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.
58
+ - **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.
59
+
60
+ Agents manage the dev server with these tools, and never run `lowdefy dev`, choose ports, or kill processes themselves:
61
+
62
+ | Tool | Purpose |
63
+ | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
64
+ | `lowdefy_dev_start` | Start the app's dev server (or return the running one) and wait until it is ready. `restart: true` when it seems stuck, or after secrets a wrapper injects have changed (`.env` and local plugin code need none); `clean: true` also deletes the build directory |
65
+ | `lowdefy_dev_stop` | Stop the app's dev server if the hub started it |
66
+ | `lowdefy_dev_status` | Owner, state, URL and build status, without starting anything |
67
+ | `lowdefy_dev_logs` | Recent output of a hub-started dev server, optionally filtered |
68
+ | `lowdefy_run_tests` | Run the app's journeys against its dev server, as `lowdefy test` does: all of them, a folder or glob (`paths`), or a tagged section (`tags`), narrowed by name with `filter`. Returns each result as data |
69
+ | `lowdefy_dev_list` | Dev servers across the checkout's apps and other checkouts |
70
+
71
+ 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`.
72
+
73
+ 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.
74
+
75
+ ## Working across projects
76
+
77
+ A session can start and query the dev servers of several projects side by side — say, an app and the shared plugin repository it uses. Pass each call the `directory` of the app it is for. Without anything set up, `lowdefy mcp` allows apps in the session's own checkout and its git worktrees; for any other app it asks you first.
78
+
79
+ - **When the client can ask** (MCP elicitation), `lowdefy mcp` asks whether to allow that app's git repository. Allowing it holds for the rest of the session, for every worktree of that repository. Tick **Always allow this repository** to trust it in every session from then on. Declining also holds for the session, so an agent cannot keep asking.
80
+ - **Ahead of time, or when the client cannot ask**, run `lowdefy hub trust <directory>` yourself, in your own terminal. It refuses to run without an interactive terminal, so an agent cannot trust a repository in passing; the refusal an agent gets tells it to ask you. To work on two projects side by side, trust each once, and any session can start and query both.
81
+ - **Trust is per git repository**, and covers all of its worktrees, wherever they are. `lowdefy hub trusted` lists each trusted repository by its git directory (for example `/home/me/code/crm/.git`, or `crm.git` for a bare repository) and marks entries whose directory is gone (`(missing)`); `lowdefy hub untrust <path>` removes one, including a missing one by its old path. The list lives in `~/.lowdefy/hub/trusted.json`, readable only by you.
82
+ - **An app outside git cannot be trusted.** It is allowed for a session started in it or in a directory inside it, or for one session when you answer the question. A session started in a directory above several projects does not get all of them.
83
+
84
+ This is a consent check on the tools, not a sandbox: an agent that can run shell commands can run any script without `lowdefy mcp`.
85
+
86
+ ## The tools
87
+
88
+ The dev server provides these tools:
89
+
90
+ | Tool | Purpose |
91
+ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
92
+ | `lowdefy_overview` | Start here — what is installed, counts per kind, and how to use the rest |
93
+ | `lowdefy_list_types` | List ALL available types of a kind (blocks, operators, actions, connections, requests) |
94
+ | `lowdefy_list_plugins` | Installed plugin packages, including local plugins, and the types each provides |
95
+ | `lowdefy_get_schema` | JSON Schema for a specific type — all properties and events |
96
+ | `lowdefy_get_examples` | Real YAML usage examples for a block type |
97
+ | `lowdefy_get_doc` | A docs page as markdown, by slug or by type name: a Lowdefy docs page, or a page this app's own plugins and modules ship |
98
+ | `lowdefy_search_docs` | Search the Lowdefy docs and this app's plugin and module docs. Pages are ranked by how many query words match, title matches first; each hit names its source (`core`, `plugin`, `local-plugin` or `module`), package and version, and `source` narrows the search |
99
+ | `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 |
100
+ | `lowdefy_get_plugin_doc` | All the markdown (README, `docs/*.md`) an installed plugin package ships, as one page |
101
+ | `lowdefy_build_status` | Current build errors and warnings (with source file locations) plus recent browser runtime errors — call after every edit |
102
+ | `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 |
103
+ | `lowdefy_get_page_config` | The fully built config for a page, or its structured build errors |
104
+ | `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; `urlQuery` opens it at a query string; `pathParams` opens an instance of a page whose [`path`](/page-paths) has placeholders; `steps` (`{"open": "blockId"}`, `click`, `fill`, `select`, `wait`, …) run first so the capture shows an open dropdown, calendar or modal |
105
+ | `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 |
106
+ | `lowdefy_journey_session` | The recorded dev sessions, or one as a log (one line per interaction with what the app did, e.g. `click save → Validate failed [priority]`), to write journeys from |
107
+ | `lowdefy_find_config` | Which yaml file (and line) defines a given page, block, or request id |
108
+ | `lowdefy_scaffold_page` | Create a new page yaml file with a canonical minimal structure |
109
+ | `lowdefy_app_map` | The whole-app graph: every page, menu, connection, endpoint, and agent in one call |
110
+ | `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 |
111
+ | `lowdefy_eval_operator` | Evaluate any operator expression against live page state — a REPL for config |
112
+ | `lowdefy_run_request` | Execute a request with a test payload, as a given `user`, to verify data shape (read-only unless opted in) |
113
+ | `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) |
114
+ | `lowdefy_snapshot_state` | Capture live page state + request responses into a committable checkpoint folder |
115
+ | `lowdefy_load_state` | Restore a state checkpoint — headless, or a `?_checkpoint=` URL for manual testing |
116
+ | `lowdefy_list_state_checkpoints` | List saved state checkpoints |
117
+ | `lowdefy_checkpoint_to_mocks` | Convert a state checkpoint into e2e `mocks.yaml` fixtures |
118
+ | `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 |
119
+ | `lowdefy_checkpoint` | Snapshot all config files before risky changes |
120
+ | `lowdefy_revert_checkpoint` | Restore config files from a checkpoint |
121
+
122
+ ## Hazards — what the schema cannot tell you
123
+
124
+ 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`.
125
+
126
+ `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.
127
+
128
+ 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.
44
129
 
45
130
  ## Annotate your app — point, draw, copy, paste
46
131
 
@@ -68,19 +153,85 @@ Hold **Option** (macOS) or **Alt** (Windows/Linux) and click any element in your
68
153
  The dev server rebuilds automatically when config changes, so an agent works in a tight loop:
69
154
 
70
155
  1. Discover types and schemas, write or edit YAML.
71
- 2. Call `lowdefy_build_status` — did the build succeed? Errors come back with the exact source file and location.
72
- 3. Call `lowdefy_get_page_config` to confirm the page builds, and `lowdefy_screenshot_page` to see it rendered.
73
- 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.
156
+ 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.
157
+ 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.
158
+ 4. Call `lowdefy_get_page_config` to confirm the page builds, and `lowdefy_screenshot_page` to see it rendered.
159
+ 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.
160
+ 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.
161
+ 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.
162
+
163
+ ### Events are pushed — no need to poll
164
+
165
+ The dev server pushes what changed instead of waiting to be asked. Two channels carry the same events:
166
+
167
+ - **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`.
168
+ - **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.
169
+
170
+ Every event carries `type` and an ISO `timestamp`. The four types:
171
+
172
+ | Type | When | Carries |
173
+ | -------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
174
+ | `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 |
175
+ | `build` | Every time a rebuild finishes, success or failure | `status`, `errorCount`, `warningCount`, `errors`, `warnings`, and `stale` / `staleSince` (see below) |
176
+ | `client_error` | A browser reports a runtime error | The same entry `lowdefy_build_status` lists under `clientErrors` |
177
+ | `server_error` | A request, endpoint, MCP tool or agent tool fails on the server | The same entry `lowdefy_build_status` lists under `serverErrors` |
178
+
179
+ 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.
180
+
181
+ ### When a build fails, answers are marked stale
182
+
183
+ 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.
184
+
185
+ So while the last build is failing, every answer says so:
186
+
187
+ - MCP tool results start with a `STALE: ...` text item.
188
+ - JSON responses from `/lowdefy-docs` carry `stale: true`, `staleSince` and `staleReason`.
189
+ - Markdown responses are prefixed with a `> STALE: ...` banner.
190
+ - Every `/lowdefy-docs` response carries the `X-Lowdefy-Stale` and `X-Lowdefy-Stale-Since` headers.
191
+
192
+ 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.
193
+
194
+ 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.
195
+
196
+ ### Agent instructions are checked, and said once
197
+
198
+ `lowdefy agent-setup` writes Lowdefy's guidance for coding agents as a marked block in `AGENTS.md` (or `CLAUDE.md`), stamped with the Lowdefy version that wrote it. The dev server checks that block and reports what it finds under `agentFiles` in `lowdefy_build_status`, as `{ code, message }` notices, never among the build's warnings:
199
+
200
+ | `code` | When |
201
+ | ----------------------- | ------------------------------------------------------------------------------------------------------- |
202
+ | `version_mismatch` | The block comes from a different Lowdefy minor version than `lowdefy.yaml` (a patch difference is fine) |
203
+ | `claude_import_missing` | The block is in `AGENTS.md`, but the root `CLAUDE.md` is missing or has no `@AGENTS.md` line |
204
+ | `block_missing` | No block, but `.mcp.json` registers the `lowdefy` server, so the project set up agents |
205
+
206
+ The check reads the nearest `AGENTS.md` or `CLAUDE.md` holding the block, from the app folder up to the git root, and runs on every read, so a fix shows at once. It never changes a file. Apps on `lowdefy: local` get no version or missing-block notice. The dev server also prints the notices once when it starts.
207
+
208
+ `lowdefy mcp` passes each notice on once per agent session for each app, and again only if its text changes; later build-status results in that session leave `agentFiles` out. `GET /lowdefy-docs/build-status` reports it on every read. Each notice tells the agent to tell you rather than fix it: the fix (`npx lowdefy@<app version> agent-setup`) rewrites committed files on whatever branch is open, and in a repository whose apps pin different Lowdefy versions only you know which version the files should follow.
74
209
 
75
210
  ## Live state — the agent sees what you see
76
211
 
77
212
  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.
78
213
 
214
+ ## Pages with path parameters
215
+
216
+ A page whose [`path`](/page-paths) has placeholders, such as `tickets/{space}/{ticket_id}`, has one instance per set of values, each with its own state and requests. `lowdefy_app_map` shows each page's `path`, and `lowdefy_overview` lists the pages that have placeholders. The tools that open or read a page take `pathParams`, an object with one value per placeholder, next to `pageId` and `urlQuery`:
217
+
218
+ ```json
219
+ { "pageId": "ticket", "pathParams": { "space": "support", "ticket_id": "1234" } }
220
+ ```
221
+
222
+ - **Headless** (`lowdefy_screenshot_page`, `lowdefy_inspect_state`, `lowdefy_eval_operator`, `lowdefy_snapshot_state`, `lowdefy_run_journey`): `pathParams` is required to open a page that has placeholders. A missing placeholder is an error that names it, returned before a browser opens.
223
+ - **Your open tab** (`lowdefy_inspect_state`, `lowdefy_eval_operator`, `lowdefy_snapshot_state`): with `pathParams`, the tool reads that instance. With only a `pageId`, it reads the instance your tab shows for that page, or the instance of that page most recently shown when no tab is on it.
224
+ - **Checkpoints**: `lowdefy_snapshot_state` keeps the instance's `pathParams` next to `urlQuery`, and `lowdefy_load_state` opens that instance.
225
+ - **Plain HTTP routes**: the screenshot, page-config and inspect-state routes take a page id with several segments, the GET routes take `pathParams` as JSON in the query (`?pathParams={"ticket_id":"1"}`), and the POST routes as an object in the body.
226
+ - **Annotations** from the in-page feedback overlay carry the `pathParams` of the instance they were made on.
227
+
228
+ 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.
229
+
79
230
  ## Auth-protected pages
80
231
 
81
- 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.
232
+ 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.
82
233
 
83
- 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`:
234
+ 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`:
84
235
 
85
236
  ```json
86
237
  { "pageId": "users", "user": { "roles": ["admin"] } }
@@ -88,9 +239,21 @@ To act as a specific caller, pass `user` — every tool that renders a page head
88
239
 
89
240
  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.
90
241
 
91
- `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.
242
+ Every one of these tools takes `user` in the same three forms:
92
243
 
93
- 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).
244
+ - a user object, as above;
245
+ - `"none"`: no injected caller, so the call runs signed out and the app's own auth decides what it sees;
246
+ - the name of a user in a [journey data set](/journey-data-sets), together with `data`, the data set's name. The call then acts as that user and runs on a fresh database of its own loaded with the data set, exactly as a journey with `data` does, so it never touches the app's real data:
247
+
248
+ ```json
249
+ { "pageId": "tickets", "user": "member", "data": "crm" }
250
+ ```
251
+
252
+ A data set user name without `data` is refused, as are a data set while a dev mock user is active and `"none"` on a data set while auth is configured. `lowdefy_run_endpoint` also takes `system: true`, which cannot be combined with `user`.
253
+
254
+ `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 params: `?user={"roles":["admin"]}` (or `?user=member&data=crm`, or `?user=none`) 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.
255
+
256
+ 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).
94
257
 
95
258
  ## State checkpoints — put the app in a known state
96
259
 
@@ -101,11 +264,12 @@ checkpoints/broken-refund-flow/
101
264
  checkpoint.json # manifest
102
265
  state.json
103
266
  urlQuery.json
267
+ pathParams.json # the instance's path values, {} for a page without placeholders
104
268
  requests/
105
269
  get_order.json # one file per request — easy to review and edit
106
270
  ```
107
271
 
108
- 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:
272
+ Loading it back (`lowdefy_load_state`) opens the instance the checkpoint was taken on, serves the recorded request data from the dev server and re-injects the page state. Three ways to use it:
109
273
 
110
274
  - **Agent verification**: the agent restores a scenario headless and confirms its fix works against the exact data that caused the bug.
111
275
  - **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.
@@ -113,7 +277,11 @@ Loading it back (`lowdefy_load_state`) serves the recorded request data from the
113
277
 
114
278
  ## Running requests safely
115
279
 
116
- `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:
280
+ `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`.
281
+
282
+ 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.
283
+
284
+ 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:
117
285
 
118
286
  ```yaml
119
287
  cli:
@@ -121,97 +289,268 @@ cli:
121
289
  allowWriteRequests: true
122
290
  ```
123
291
 
292
+ ## Running endpoints
293
+
294
+ `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:
295
+
296
+ ```json
297
+ { "endpointId": "create_order", "payload": { "sku": "A1" }, "user": { "roles": ["admin"] } }
298
+ ```
299
+
300
+ 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.
301
+
302
+ 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 `user` or `data` the call cannot act as — is a `400`.
303
+
304
+ 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:
305
+
306
+ ```json
307
+ { "endpointId": "purge_stale_conversations", "payload": { "mode": "full" }, "system": true }
308
+ ```
309
+
310
+ `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.
311
+
124
312
  This is dev-only — enable it when you're comfortable with the agent writing to your dev data.
125
313
 
126
- ## Setting up a project — one command
314
+ ## Journeys — verify behaviour, not just layout
127
315
 
128
- ```bash
129
- npx lowdefy agent-setup
316
+ 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:
317
+
318
+ ```json
319
+ {
320
+ "pageId": "new_customer",
321
+ "user": { "roles": ["admin"] },
322
+ "urlQuery": { "ref": "campaign-1" },
323
+ "steps": [
324
+ { "fill": { "blockId": "name", "value": "Ada Lovelace" } },
325
+ { "select": { "blockId": "country", "value": "United Kingdom" } },
326
+ { "click": "submit" },
327
+ { "wait": { "request": "create_customer" } },
328
+ { "expect": { "state": { "path": "created", "equals": true } } },
329
+ { "expect": { "visible": "success_modal" } },
330
+ { "expect": { "text": { "blockId": "success_message", "contains": "Ada Lovelace" } } },
331
+ { "screenshot": "after-submit" },
332
+ { "press": "Escape" },
333
+ { "click": "go_to_list" },
334
+ { "expect": { "url": { "contains": "/customers" } } }
335
+ ]
336
+ }
130
337
  ```
131
338
 
132
- 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.
339
+ Every step is an object with exactly one key:
340
+
341
+ | Step | What it does |
342
+ | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
343
+ | `{ "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) |
344
+ | `{ "click": { ...target, "count": 2 } }` | Clicks 2 or 3 times in quick succession, a double click, before the runner settles the page |
345
+ | `{ "fill": { ...target, value } }` | Fills the block's (or grid cell's) `input` or `textarea` with `value` (converted to a string) |
346
+ | `{ "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, a radio, button or segmented selector's option is clicked by its label, and a checkbox option is ticked (left ticked if it already is) |
347
+ | `{ "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 |
348
+ | `{ "back": true }` | Goes back one page, like the browser's Back button; fails when the journey has not navigated from an earlier page |
349
+ | `{ "goto": pageId }` | Loads a page like a typed URL (`{ pageId, pathParams, urlQuery }` adds the values of a [page path](/page-paths)'s placeholders and a query); a protected page may redirect to sign-in, so assert where it landed |
350
+ | `{ "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` |
351
+ | `{ "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 |
352
+ | `{ "wait": { "ms": n } }` | Sleeps `n` milliseconds |
353
+ | `{ "wait": { "request": requestId } }` | Waits until the request has finished loading |
354
+ | `{ "wait": { "state": path } }` | Waits until the state path is defined |
355
+ | `{ "screenshot": name? }` | Captures a PNG of the viewport; returned with the result (`true`, `null` or a missing name defaults to `step-<index>`) |
356
+ | `{ "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 |
357
+ | `{ "expect": { "visible": target } }` | The block, or the control a target narrows to, is visible |
358
+ | `{ "expect": { "hidden": target } }` | Nothing the target names is visible: no element matches, or every match is hidden. Passes at once when nothing matches yet, so pair it with something that must be present first |
359
+ | `{ "expect": { "text": { ...target, contains } } }` | The block's text — or a grid row's or cell's — contains the string |
360
+ | `{ "expect": { "url": { contains } } }` | The page url contains the string |
361
+ | `{ "expect": { "title": { equals } } }` | The document title (the browser tab's text) is exactly the string; `{ contains }` checks part of it |
362
+ | `{ "expect": { "calls": { request, pageId?, count } } }` | This actor's browser called the request (on `pageId`, default the current page) exactly `count` times since the journey started, compared once after the page settles; `{ endpoint, count }` counts an endpoint. Counts survive full page loads |
363
+ | `{ "expect": { "error": text } }` | The interaction step just before it raised an app error whose message contains `text` (below); must directly follow a click, open, fill, select, press or back |
364
+
365
+ 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:
366
+
367
+ | Target key | Meaning |
368
+ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------ |
369
+ | `blockId` | The block to search inside |
370
+ | `row` | A grid row, zero-based as displayed (`AgGrid*` blocks, `.ag-row[row-index]`); needs `blockId` |
371
+ | `column` | A grid cell in that row, by the column's `field` or `colId` (`.ag-cell[col-id]`); needs `blockId` |
372
+ | `text` | The visible interactive control whose text is exactly this — a button label, a tab, a menu item (`"Cat"` never matches `"Category"`) |
373
+ | `nth` | When several elements match, the zero-based one to use |
374
+
375
+ 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.
376
+
377
+ `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.
378
+
379
+ A `click`, `open`, `fill` or `select` whose `text` or `containing` matches more than one visible element fails with `Matched <n> controls with text "<text>" in <scope>; add nth: 0..<n-1>, or a blockId/row to narrow it.` Add `nth` or narrow the scope. Expectations accept any match: `expect.visible` passes when one is visible, `expect.hidden` when none is.
133
380
 
134
- ## Using it with Claude Code manually
381
+ ```json
382
+ [
383
+ { "click": { "blockId": "controls_grid", "row": 1, "text": "Delete" } },
384
+ { "expect": { "visible": { "text": "Are you sure?" } } },
385
+ { "click": { "text": "Delete" } },
386
+ { "wait": { "request": "delete_control" } },
387
+ {
388
+ "expect": {
389
+ "text": {
390
+ "blockId": "controls_grid",
391
+ "row": 1,
392
+ "column": "title",
393
+ "contains": "Key rotation"
394
+ }
395
+ }
396
+ },
397
+ { "click": { "blockId": "controls_grid", "row": 0, "column": "more" } },
398
+ { "click": { "text": "Archive" } }
399
+ ]
400
+ ```
135
401
 
136
- Add the MCP server to your project so Claude Code can use it. In your project directory run:
402
+ 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`, `pathParams` and `urlQuery` handling as the other tools.
137
403
 
138
- ```bash
139
- claude mcp add --transport http lowdefy-docs http://localhost:3000/lowdefy-docs/mcp
404
+ 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:
405
+
406
+ ```json
407
+ {
408
+ "pageId": "new_customer",
409
+ "passed": false,
410
+ "steps": [
411
+ {
412
+ "index": 0,
413
+ "step": { "fill": { "blockId": "name", "value": "Ada Lovelace" } },
414
+ "status": "ok",
415
+ "durationMs": 18
416
+ },
417
+ { "index": 1, "step": { "click": "submit" }, "status": "ok", "durationMs": 71 },
418
+ {
419
+ "index": 2,
420
+ "step": { "expect": { "state": { "path": "created", "equals": true } } },
421
+ "status": "failed",
422
+ "durationMs": 1
423
+ },
424
+ { "index": 3, "step": { "screenshot": "after-submit" }, "status": "skipped", "durationMs": 0 }
425
+ ],
426
+ "failure": {
427
+ "index": 2,
428
+ "step": { "expect": { "state": { "path": "created", "equals": true } } },
429
+ "expected": true,
430
+ "actual": null,
431
+ "message": "Expected state \"created\" to equal true but found undefined."
432
+ },
433
+ "screenshots": [],
434
+ "state": { "name": "Ada Lovelace", "country": null }
435
+ }
140
436
  ```
141
437
 
142
- Or commit a `.mcp.json` file at your project root so the whole team gets it:
438
+ `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:
439
+
440
+ | `state` | The result carries |
441
+ | ----------------------- | --------------------------------------------------------------------- |
442
+ | omitted | The whole state when it is small, otherwise `stateOmitted` |
443
+ | `["form.name", "rows"]` | `state: { "form.name": …, "rows": … }`, `null` for a path not defined |
444
+ | `true` | The whole state, however large |
445
+ | `false` | No state |
446
+
447
+ A journey also fails at the step that causes an **app error**, even when every expectation holds: an action that fails with an error that is not a user error, an uncaught page exception or a client error report, a server error from a request or endpoint, or a 5xx from one. Only errors the journey's own browsers cause count, and they are reported in its result, not in `build-status` or the event stream. A failed `Validate`, a `Throw` action and 401/403 refusals never count. The failure carries each error with its kind, its config `source` and a `key` that names the error by its kind, page and source, the same across runs:
143
448
 
144
449
  ```json
145
450
  {
146
- "mcpServers": {
147
- "lowdefy-docs": {
148
- "type": "http",
149
- "url": "http://localhost:3000/lowdefy-docs/mcp"
451
+ "index": 1,
452
+ "step": { "click": "save" },
453
+ "kind": "app-error",
454
+ "message": "Step 1 (click) caused an app error: server-error: MongoDB: MongoDB rejected the MongoDBInsertOne command.",
455
+ "expected": "no app error",
456
+ "actual": ["server-error: MongoDB: MongoDB rejected the MongoDBInsertOne command."],
457
+ "errors": [
458
+ {
459
+ "kind": "server-error",
460
+ "message": "MongoDB: MongoDB rejected the MongoDBInsertOne command.",
461
+ "source": "pages/tickets.yaml:42",
462
+ "configKey": null,
463
+ "key": "server-error|tickets|pages/tickets.yaml:42"
150
464
  }
151
- }
465
+ ]
152
466
  }
153
467
  ```
154
468
 
155
- 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.
469
+ The kinds are `action-error`, `client-error`, `server-error`, `request-failed` (a 5xx no server error explains) and `environment` (a `$search` stage the journey's data set cannot run). An error raised while the first page opens fails with `"phase": "open"` in place of `index` and `step`, every step skipped. When the step failed on its own too, the app error leads `message` and the step's own message is kept as `stepMessage`. Where an error is the intended outcome, `{ "expect": { "error": text } }` straight after the interaction claims the errors whose message contains `text`, with the failed action that reported them; any other error from that interaction still fails it.
156
470
 
157
- ## Referencing it in a skill
471
+ 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.
472
+
473
+ 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.
474
+
475
+ 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.
476
+
477
+ Journeys are also the file format of `tests/journeys/`, 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.
478
+
479
+ ## Setting up a project — one command
480
+
481
+ ```bash
482
+ npx lowdefy@<app version> agent-setup
483
+ ```
158
484
 
159
- 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`:
485
+ Run it with the Lowdefy version your app's `lowdefy.yaml` pins. It writes to the project root, the nearest folder holding `.git` above the app (or `--project-directory`), and merges into files that already exist:
160
486
 
161
- ```markdown
162
- ---
163
- name: lowdefy-config
164
- 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.
165
- ---
487
+ - **`.mcp.json`** registers the `lowdefy` MCP server, pinned to the version of the CLI running `agent-setup` (`npx lowdefy@<version> mcp`; see [Connect your agent](#connect-your-agent-lowdefy-mcp)). Other servers in the file stay.
488
+ - **Lowdefy's block** of guidance for coding agents: the dev server, looking up types and docs, icons and HTML, testing a change, visual feedback and the installed skills. It sits between `<!-- BEGIN:lowdefy-agent-rules version=<version> -->` and `<!-- END:lowdefy-agent-rules -->`, stamped with the version of the CLI that wrote it, and each run rewrites the whole block. Text outside the markers is yours and never touched. An existing block is replaced where it is. Otherwise the block is appended to `AGENTS.md` when it exists, else to `CLAUDE.md` when that is all the project has (no `AGENTS.md` is created), else to a new `AGENTS.md`.
489
+ - **The root `CLAUDE.md` imports `AGENTS.md`.** Claude Code skips `AGENTS.md` whenever it finds a Claude file in or above the working directory, including one outside the repository on your machine. When the block is in `AGENTS.md`, `agent-setup` creates a root `CLAUDE.md` holding only `@AGENTS.md`, or adds that line to the top of an existing one that lacks it. It never edits `.claude/CLAUDE.md` or `CLAUDE.local.md`.
490
+ - **Skills**, each written to both `.agents/skills/<name>/SKILL.md` (read by Codex, Cursor, Copilot, Gemini, Amp and opencode) and `.claude/skills/<name>/SKILL.md` (read by Claude Code). Agents that read both folders may list a skill twice.
491
+ - `lowdefy-config`: writing Lowdefy config with exact types, schemas and examples from the dev server.
492
+ - `journeys-from-dev`: turns what you tried in the development server into journeys (see [Dev recordings](/config-tests#dev-recordings)).
493
+ - `journeys-from-production`: turns what real users do in production into journeys (see [Production journeys](/config-tests#production-journeys)).
494
+ - `journeys-from-pr`: explores a pull request (or a bug bash goal) page by page, writes a journey for every path a user can take, keeps those that pass and reports those that fail as findings (see [Exploring a pull request](/explore-pull-request)).
495
+ - `journeys-harden`: replays, lints and mutation-tests your journeys and writes their edge-case variants, never deleting a journey (see [Hardening journeys](/config-tests#hardening-journeys)).
496
+ - `journeys-autopilot`: builds and hardens the journeys of a whole app on its own, cycle after cycle (see [Journeys on autopilot](/config-tests#journeys-on-autopilot)).
166
497
 
167
- # Writing Lowdefy config
498
+ **Everything follows the CLI, not the app.** Nothing `agent-setup` writes names an app, so running it from any app in a repository writes the same files. A plain `npx lowdefy agent-setup` runs the latest release, whatever your app pins. When the CLI's version differs from your app's, `agent-setup` still writes, and warns with the command that matches them, such as `npx lowdefy@7.1.0 agent-setup`. The dev server keeps a notice about the block until someone does (see [Agent instructions are checked, and said once](#agent-instructions-are-checked-and-said-once)). Rerun `agent-setup` the same way after upgrading Lowdefy.
168
499
 
169
- The dev server serves docs for everything installed in this project at
170
- `http://localhost:3000/lowdefy-docs` (also as MCP tools via the `lowdefy-docs` server).
500
+ **Which app agents work on.** A Lowdefy app is a folder containing `lowdefy.yaml`. The block tells agents the rule the `lowdefy_` tools follow: the app folder the session started in, else the repository's only app; otherwise the tools fail and list the apps, and the agent passes the folder it means as `directory`. Shell commands such as `lowdefy test` take it as `--config-directory <app>`. The unattended `journeys-autopilot` skill stops and lists the apps rather than guess.
171
501
 
172
- Never guess type names or properties. Before writing config:
502
+ **Skills you edit are kept.** Each `SKILL.md` carries a `lowdefy-skill-hash` of its content. A rerun refreshes both copies of a skill, and recreates a missing one, while every copy still matches its hash. Edit either copy and both are frozen; `agent-setup` names the edited copy and its twin, so you can copy the edit across, or delete both and rerun to go back to Lowdefy's. A skill Lowdefy no longer ships is removed when unedited: its `SKILL.md` is deleted, and its folder only when nothing else is left in it. An edited one stays, and `agent-setup` says Lowdefy no longer maintains it. Skills without a `lowdefy-skill-hash` are not Lowdefy's and are never touched.
173
503
 
174
- 1. Call `lowdefy_list_types` (or `GET /lowdefy-docs/blocks`, `/lowdefy-docs/operators`,
175
- `/lowdefy-docs/actions`, `/lowdefy-docs/connections`, `/lowdefy-docs/requests`) to find the exact
176
- type name — this includes this project's local plugins.
177
- 2. Call `lowdefy_get_schema` (or `GET /lowdefy-docs/schema/{kind}/{type}`) for the
178
- exact properties and events of that type.
179
- 3. Call `lowdefy_get_examples` (or `GET /lowdefy-docs/examples/{type}`) to see real
180
- usage YAML for blocks.
181
- 4. For concepts (state, operators, events, requests), call `lowdefy_get_doc`
182
- or `lowdefy_search_docs`.
504
+ **Apps on `lowdefy: local`** are not supported: `agent-setup` stops with an error and writes nothing.
183
505
 
184
- After every edit, call `lowdefy_build_status` and fix what it reports. Use
185
- `lowdefy_inspect_state` to read the live state of the page (ask the developer
186
- to interact with it first when debugging), `lowdefy_eval_operator` to test
187
- operator expressions against real state, and `lowdefy_snapshot_state` /
188
- `lowdefy_load_state` to capture and restore app states for testing.
506
+ **Projects set up by an earlier version.** In `.mcp.json`, the `lowdefy` entry is replaced whatever it ran before (a dev server port such as `http://localhost:<port>/lowdefy-docs/mcp`, or the CLI in `node_modules`), and port-pinned entries under other names, such as `lowdefy-3010`, are removed. Approvals in `.claude/settings.json` under the server's old name, `lowdefy-docs`, carry over to `lowdefy`, whose tools are named `mcp__lowdefy__*`; remove an old `lowdefy-docs` entry from `.mcp.json` by hand. Guidance written before the block is not migrated: an unmarked `## Lowdefy` section stays where it is, and a `lowdefy-config` skill without a hash counts as edited. Delete them, then rerun `agent-setup`.
507
+
508
+ ## Using it with Claude Code manually
509
+
510
+ Commit a `.mcp.json` file at your project root, pinning your app's Lowdefy version:
511
+
512
+ ```json
513
+ {
514
+ "mcpServers": {
515
+ "lowdefy": {
516
+ "type": "stdio",
517
+ "command": "npx",
518
+ "args": ["--prefer-offline", "--yes", "lowdefy@7.1.0", "mcp"]
519
+ }
520
+ }
521
+ }
189
522
  ```
190
523
 
524
+ Or register it for every project with `claude mcp add --scope user lowdefy -- npx --prefer-offline --yes lowdefy@7.1.0 mcp` (on Windows, `-- cmd /c npx ...`), which is what `lowdefy agent-setup --user` runs. 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.
525
+
191
526
  ## Plain HTTP routes
192
527
 
193
528
  Everything the MCP tools serve is also available as plain GET routes — useful for `curl`, scripts, or agents without MCP support:
194
529
 
195
- | Route | Purpose |
196
- | --------------------------- | -------------------------------------------------------------- |
197
- | `GET /lowdefy-docs` | Overview and route index |
198
- | `GET /lowdefy-docs/{kind}` | List all available types of a kind, e.g. `/lowdefy-docs/blocks` |
199
- | `GET /lowdefy-docs/plugins` | Installed plugin packages and the types each provides |
200
- | `GET /lowdefy-docs/schema/{kind}/{type}` | JSON schema for a type, e.g. `/lowdefy-docs/schema/blocks/Button` |
201
- | `GET /lowdefy-docs/examples/{type}` | Example YAML for a block type |
202
- | `GET /lowdefy-docs/content/{slug}` | A docs page as markdown, e.g. `/lowdefy-docs/content/operators/_get` |
203
- | `GET /lowdefy-docs/search?q={query}`| Search the docs |
204
- | `GET /lowdefy-docs/plugin-doc/{package}` | Markdown shipped inside a plugin package |
205
- | `GET /lowdefy-docs/build-status` | Current build errors/warnings + recent browser runtime errors |
206
- | `GET /lowdefy-docs/page-config/{pageId}` | Fully built page config, or its build errors |
207
- | `GET /lowdefy-docs/screenshot/{pageId}` | PNG screenshot of the rendered page |
208
- | `GET /lowdefy-docs/find/{id}?pageId=` | Locate where a page/block/request id is defined |
209
- | `GET /lowdefy-docs/app-map` | Whole-app graph: pages, menus, connections, endpoints, agents |
210
- | `GET /lowdefy-docs/inspect-state/{pageId}` | Live state/requests/eventLog of a running page (tab or headless) |
211
- | `POST /lowdefy-docs/eval-operator` | Evaluate an operator expression against live page state |
212
- | `POST /lowdefy-docs/run-request` | Execute a request with a test payload (read-only unless opted in) |
213
- | `GET/POST /lowdefy-docs/checkpoints` + `/revert` | Config-file checkpoints |
214
- | `GET/POST /lowdefy-docs/state-checkpoints` + `/snapshot`, `/load` | State & data checkpoints |
530
+ | Route | Purpose |
531
+ | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
532
+ | `GET /lowdefy-docs` | Overview and route index |
533
+ | `GET /lowdefy-docs/{kind}` | List all available types of a kind, e.g. `/lowdefy-docs/blocks` |
534
+ | `GET /lowdefy-docs/plugins` | Installed plugin packages and the types each provides |
535
+ | `GET /lowdefy-docs/schema/{kind}/{type}` | JSON schema for a type, e.g. `/lowdefy-docs/schema/blocks/Button` |
536
+ | `GET /lowdefy-docs/examples/{type}` | Example YAML for a block type |
537
+ | `GET /lowdefy-docs/content/{slug}` | A docs page as markdown, e.g. `/lowdefy-docs/content/operators/_get` |
538
+ | `GET /lowdefy-docs/search?q={query}` | Search the docs |
539
+ | `GET /lowdefy-docs/plugin-doc/{package}` | Markdown shipped inside a plugin package |
540
+ | `GET /lowdefy-docs/build-status` | Current build errors/warnings + recent browser runtime errors |
541
+ | `GET /lowdefy-docs/events` | SSE stream of `restart`, `build`, `client_error` and `server_error` events |
542
+ | `GET /lowdefy-docs/page-config/{pageId}` | Fully built page config, or its build errors |
543
+ | `GET /lowdefy-docs/screenshot/{pageId}` | PNG screenshot of the rendered page; `?viewportWidth=390&viewportHeight=844&colorScheme=dark` sets the viewport and colour scheme |
544
+ | `POST /lowdefy-docs/journey` | Drive a page headless through declarative steps and assert what happens; screenshots returned as base64 |
545
+ | `GET /lowdefy-docs/find/{id}?pageId=` | Locate where a page/block/request id is defined |
546
+ | `GET /lowdefy-docs/app-map` | Whole-app graph: pages, menus, connections, endpoints, agents |
547
+ | `GET /lowdefy-docs/inspect-state/{pageId}` | Live state/requests/eventLog of a running page (tab or headless) |
548
+ | `POST /lowdefy-docs/eval-operator` | Evaluate an operator expression against live page state |
549
+ | `POST /lowdefy-docs/run-request` | Execute a request with a test payload (read-only unless opted in) |
550
+ | `POST /lowdefy-docs/run-endpoint` | Execute an Api endpoint routine with a test payload and caller (needs `allowWriteRequests`; rejects return as data) |
551
+ | `GET/POST /lowdefy-docs/checkpoints` + `/revert` | Config-file checkpoints |
552
+ | `GET/POST /lowdefy-docs/state-checkpoints` + `/snapshot`, `/load` | State & data checkpoints |
553
+ | `POST /lowdefy-docs/restart` | Restart the dev server process (`{reason}` optional; then `build-status?wait=true` answers once it is back) |
215
554
 
216
555
  ## Local plugins
217
556
 
@@ -220,7 +559,17 @@ Your project's own plugins (declared under `plugins:` in `lowdefy.yaml`) are inc
220
559
  - Types appear in `lowdefy_list_types` and `/lowdefy-docs/{kind}` listings.
221
560
  - Block schemas are derived from each block's `meta`, and connection/request schemas from the `schema` property on your connection and request definitions.
222
561
  - 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`.
223
- - A `README.md` or `docs/*.md` files in your plugin package are served by `lowdefy_get_plugin_doc`.
562
+ - A `README.md` and `docs/*.md` files in your plugin package are searched by `lowdefy_search_docs` and read with `lowdefy_get_doc` (`plugins/<package>` for the README, `plugins/<package>/<file>` for a docs file). A docs file named after a type, such as `docs/MyBlock.md`, is the doc `lowdefy_get_doc` returns for that type. `lowdefy_get_plugin_doc` returns them all as one page.
563
+ - 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`.
564
+
565
+ ## Modules
566
+
567
+ The docs of your app's modules, fetched or local `file:`, are searched and read the same way:
568
+
569
+ - `modules/<id>` is the module's `README.md`, and `modules/<id>/<file>` each file in its `docs/` folder.
570
+ - `modules/<id>/manifest` lists the vars (type, required, description and default), components and exports its `module.lowdefy.yaml` declares.
571
+
572
+ `<id>` is the module's id in your `lowdefy.yaml`. Search with `source: module` to find only module docs. Plugin and module docs are read from the files the packages carry, so a change to one is served on the next call.
224
573
 
225
574
  ## Docs for crawling agents
226
575