@lowdefy/server-dev 6.1.0 → 7.0.0

package/lib/docs/getHazards.js

@@ -0,0 +1,115 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+import { type } from '@lowdefy/helpers';
+
+import loadFrameworkHazards from './loadFrameworkHazards.js';
+import normalizeTypeKind from './normalizeTypeKind.js';
+import readBuildArtifact from './readBuildArtifact.js';
+
+// Where each kind's plugin-declared hazards land in the build: block metas
+// pick them from meta.hazards, request metas ride along whole, operators
+// get a dedicated metas artifact (they carry no other meta).
+const TYPE_ATTACHED_HAZARDS = {
+  blocks: (typeName) => readBuildArtifact({ name: 'plugins/blockMetas.json' })?.[typeName]?.hazards,
+  operators: (typeName) =>
+    readBuildArtifact({ name: 'plugins/operatorMetas.json' })?.[typeName]?.hazards,
+  requests: (typeName) =>
+    readBuildArtifact({ name: 'plugins/requestSchemas.json' })?.[typeName]?.meta?.hazards,
+};
+
+// The closed set of `when` conditions a framework hazard may declare. A
+// hazard whose `when` is not here is skipped with a warning rather than
+// guessed at — an agent must be able to rely on every hazard it is shown.
+const WHEN_CONDITIONS = {
+  connectionTenantNotNone: ({ kind, connectionId }) => {
+    if (kind !== 'requests' || type.isNone(connectionId)) {
+      return false;
+    }
+    const tenantConnections = readBuildArtifact({ name: 'tenantConnections.json' }) ?? [];
+    return tenantConnections.some((connection) => connection.connectionId === connectionId);
+  },
+};
+
+const warnedUnknownWhen = new Set();
+
+function normalizeKind(kind) {
+  if (type.isNone(kind)) {
+    return null;
+  }
+  const lowered = String(kind).toLowerCase();
+  if (lowered === 'page' || lowered === 'pages') {
+    return 'pages';
+  }
+  return normalizeTypeKind({ kind: lowered });
+}
+
+function hazardApplies({ hazard, kind, typeName, connectionId }) {
+  const { kinds, types, when } = hazard.appliesTo ?? {};
+  if (type.isNone(kinds) && type.isNone(types)) {
+    return false;
+  }
+  if (!type.isNone(kinds) && !kinds.includes(kind)) {
+    return false;
+  }
+  if (!type.isNone(types) && !types.includes(typeName)) {
+    return false;
+  }
+  if (type.isNone(when)) {
+    return true;
+  }
+  const condition = WHEN_CONDITIONS[when];
+  if (type.isNone(condition)) {
+    if (!warnedUnknownWhen.has(when)) {
+      warnedUnknownWhen.add(when);
+      console.warn(
+        `Hazard "${hazard.id}" declares unknown when condition ${JSON.stringify(
+          when
+        )} and was skipped.`
+      );
+    }
+    return false;
+  }
+  return condition({ kind, connectionId });
+}
+
+// Hazards for a type: the plugin's own (meta.hazards, via the build
+// artifacts) first, then the framework-level list filtered by kind/type and
+// its `when` condition, de-duplicated by id.
+function getHazards({ kind, type: typeName, connectionId }) {
+  const normalizedKind = normalizeKind(kind);
+  const hazards = [];
+  const seen = new Set();
+  const push = (hazard) => {
+    if (type.isNone(hazard?.id) || seen.has(hazard.id)) {
+      return;
+    }
+    seen.add(hazard.id);
+    hazards.push({ id: hazard.id, message: hazard.message, see: hazard.see ?? null });
+  };
+
+  const readTypeAttached = TYPE_ATTACHED_HAZARDS[normalizedKind];
+  if (!type.isNone(readTypeAttached) && !type.isNone(typeName)) {
+    (readTypeAttached(typeName) ?? []).forEach(push);
+  }
+
+  (loadFrameworkHazards() ?? [])
+    .filter((hazard) => hazardApplies({ hazard, kind: normalizedKind, typeName, connectionId }))
+    .forEach(push);
+
+  return hazards;
+}
+
+export default getHazards;

package/lib/docs/getHazards.test.mjs

@@ -0,0 +1,175 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+import { jest } from '@jest/globals';
+
+import setupTestFixtures from './setupTestFixtures.mjs';
+
+// getHazards reads build artifacts from process.cwd() — point it at the
+// fixture server before the module is imported.
+const fixtureDir = setupTestFixtures();
+process.chdir(fixtureDir);
+
+// The framework list ships in @lowdefy/docs-content; mock the loader so each
+// test controls the list (and the "package not installed" case).
+const mockLoadFrameworkHazards = jest.fn();
+jest.unstable_mockModule('./loadFrameworkHazards.js', () => ({
+  default: mockLoadFrameworkHazards,
+}));
+
+const { default: getHazards } = await import('./getHazards.js');
+
+const frameworkHazards = [
+  {
+    id: 'state-in-request-properties',
+    appliesTo: { kinds: ['requests'] },
+    message: '_state in request properties is always undefined.',
+    see: 'concepts/connections-and-requests',
+  },
+  {
+    id: 'visible-false-prunes-state',
+    appliesTo: { kinds: ['blocks'] },
+    message: 'visible: false removes the block and its state.',
+    see: 'concepts/lowdefy-schema',
+  },
+  {
+    id: 'link-same-page-no-onmount',
+    appliesTo: { types: ['Link'] },
+    message: 'A Link to the page already open does not remount it.',
+    see: 'actions/link',
+  },
+  {
+    id: 'tenant-wall-lookup',
+    appliesTo: { kinds: ['requests'], when: 'connectionTenantNotNone' },
+    message: 'The wall injects a tenant match into every lookup.',
+    see: null,
+  },
+];
+
+let warnSpy;
+
+beforeEach(() => {
+  mockLoadFrameworkHazards.mockReset();
+  mockLoadFrameworkHazards.mockReturnValue(frameworkHazards);
+  warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+});
+
+afterEach(() => {
+  warnSpy.mockRestore();
+});
+
+test('getHazards returns type-attached hazards only when no framework hazard applies', () => {
+  mockLoadFrameworkHazards.mockReturnValue([]);
+  expect(getHazards({ kind: 'operators', type: '_get' })).toEqual([
+    { id: 'get-fixture-hazard', message: '_get fixture hazard.', see: 'operators/_get' },
+  ]);
+});
+
+test('getHazards returns framework hazards only when the type declares none', () => {
+  const hazards = getHazards({ kind: 'blocks', type: 'Button' });
+  expect(hazards).toEqual([
+    {
+      id: 'visible-false-prunes-state',
+      message: 'visible: false removes the block and its state.',
+      see: 'concepts/lowdefy-schema',
+    },
+  ]);
+});
+
+test('getHazards matches framework hazards by exact type name across kinds', () => {
+  const hazards = getHazards({ kind: 'actions', type: 'Link' });
+  expect(hazards.map((hazard) => hazard.id)).toEqual(['link-same-page-no-onmount']);
+  expect(getHazards({ kind: 'actions', type: 'SetState' })).toEqual([]);
+});
+
+test('getHazards merges both sources, type-attached first, de-duplicated by id', () => {
+  const hazards = getHazards({ kind: 'blocks', type: 'TestBlock' });
+  expect(hazards.map((hazard) => hazard.id)).toEqual([
+    'test-block-hazard',
+    'visible-false-prunes-state',
+  ]);
+  expect(hazards[1].message).toEqual('Plugin wording for visible: false.');
+});
+
+test('getHazards accepts singular kind names', () => {
+  expect(getHazards({ kind: 'block', type: 'Button' }).map((hazard) => hazard.id)).toEqual([
+    'visible-false-prunes-state',
+  ]);
+});
+
+test('getHazards evaluates connectionTenantNotNone true for a request over a walled connection', () => {
+  const hazards = getHazards({
+    kind: 'requests',
+    type: 'WriteRequest',
+    connectionId: 'tenant_db',
+  });
+  expect(hazards.map((hazard) => hazard.id)).toEqual([
+    'write-request-hazard',
+    'state-in-request-properties',
+    'tenant-wall-lookup',
+  ]);
+});
+
+test('getHazards evaluates connectionTenantNotNone false for a shared connection or no connectionId', () => {
+  const shared = getHazards({ kind: 'requests', type: 'WriteRequest', connectionId: 'shared_db' });
+  expect(shared.map((hazard) => hazard.id)).toEqual([
+    'write-request-hazard',
+    'state-in-request-properties',
+  ]);
+  const noConnection = getHazards({ kind: 'requests', type: 'WriteRequest' });
+  expect(noConnection.map((hazard) => hazard.id)).toEqual([
+    'write-request-hazard',
+    'state-in-request-properties',
+  ]);
+});
+
+test('getHazards never applies connectionTenantNotNone outside requests', () => {
+  const hazards = getHazards({ kind: 'blocks', type: 'Button', connectionId: 'tenant_db' });
+  expect(hazards.map((hazard) => hazard.id)).toEqual(['visible-false-prunes-state']);
+});
+
+test('getHazards skips a hazard with an unknown when condition and warns once', () => {
+  mockLoadFrameworkHazards.mockReturnValue([
+    {
+      id: 'mystery',
+      appliesTo: { kinds: ['blocks'], when: 'moonIsFull' },
+      message: 'Never shown.',
+      see: null,
+    },
+  ]);
+  expect(getHazards({ kind: 'blocks', type: 'Button' })).toEqual([]);
+  expect(getHazards({ kind: 'blocks', type: 'Button' })).toEqual([]);
+  expect(warnSpy).toHaveBeenCalledTimes(1);
+  expect(warnSpy.mock.calls[0][0]).toContain('"moonIsFull"');
+});
+
+test('getHazards returns an empty list when hazards.json is unavailable and the type has none', () => {
+  mockLoadFrameworkHazards.mockReturnValue(null);
+  expect(getHazards({ kind: 'blocks', type: 'Button' })).toEqual([]);
+});
+
+test('getHazards still returns type-attached hazards when hazards.json is unavailable', () => {
+  mockLoadFrameworkHazards.mockReturnValue(null);
+  expect(getHazards({ kind: 'blocks', type: 'TestBlock' }).map((hazard) => hazard.id)).toEqual([
+    'test-block-hazard',
+    'visible-false-prunes-state',
+  ]);
+});
+
+test('getHazards returns an empty list for kinds and types without hazards', () => {
+  expect(getHazards({ kind: 'connections', type: 'AxiosHttp' })).toEqual([]);
+  expect(getHazards({ kind: 'pages' })).toEqual([]);
+  expect(getHazards({ kind: 'nonsense', type: 'X' })).toEqual([]);
+});

package/lib/docs/getMailOutboxDirectory.js

@@ -0,0 +1,26 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import path from 'path';
+
+// Where the dev mail sink writes each captured message (manager process) and
+// where journeys read them (server process). Inside .lowdefy because captured
+// mail carries sign-in tokens and must never sit in a committable spot.
+function getMailOutboxDirectory({ configDirectory }) {
+  return path.join(configDirectory, '.lowdefy', 'mail');
+}
+
+export default getMailOutboxDirectory;

package/lib/docs/getOverview.js

@@ -14,7 +14,11 @@
   limitations under the License.
 */
 
+import { parsePathPattern } from '@lowdefy/helpers';
+
+import getDocsIndex from './getDocsIndex.js';
 import getDocsManifest from './getDocsManifest.js';
+import lowdefyConfig from '../build/config.js';
 import listPlugins from './listPlugins.js';
 import readBuildArtifact from './readBuildArtifact.js';
 
@@ -31,6 +35,52 @@ function countKinds({ availableTypes }) {
   };
 }
 
+// The dev server mounts every route under config.basePath, the docs tools
+// included, so an app with a basePath must tell agents the prefix.
+function basePathLines() {
+  const basePath = lowdefyConfig.basePath ?? '';
+  if (basePath === '') return [];
+  return [
+    `This app sets \`config.basePath: ${basePath}\`, so every route below is served under it: \`GET ${basePath}/lowdefy-docs\`, \`${basePath}/lowdefy-docs/mcp\`, \`${basePath}/api/...\`.`,
+    '',
+  ];
+}
+
+// A page whose path has placeholders has one instance per set of values, so
+// the page tools need pathParams to open it.
+function patternedPageLines() {
+  const routes = readBuildArtifact({ name: 'routes.json', deserialize: true });
+  const patterned = routes.filter((route) =>
+    parsePathPattern(route.path).some((segment) => segment.name !== undefined)
+  );
+  if (patterned.length === 0) return [];
+  return [
+    '## Pages with path parameters',
+    '',
+    'These pages are served at a URL pattern with placeholders. Pass `pathParams` with a value for each placeholder (e.g. `{"ticket_id": "1"}`) to `lowdefy_screenshot_page`, `lowdefy_inspect_state`, `lowdefy_eval_operator`, `lowdefy_snapshot_state` and `lowdefy_run_journey`, or as `?pathParams=` JSON on the GET routes. A live tab is read at the instance it shows without them.',
+    '',
+    ...patterned.map((route) => `- \`${route.pageId}\`: \`${route.path}\``),
+    '',
+  ];
+}
+
+// Plugin and module docs, with each module's pages named so an agent can
+// read them without a search.
+function appDocsLines() {
+  const { entries } = getDocsIndex();
+  const pluginDocs = entries.filter(
+    (entry) => entry.source === 'plugin' || entry.source === 'local-plugin'
+  );
+  const moduleDocs = entries.filter((entry) => entry.source === 'module');
+  const lines = [
+    `- ${pluginDocs.length} plugin doc pages and ${moduleDocs.length} module doc pages from this app's own plugins and modules (search them with \`source\`, read them with \`lowdefy_get_doc\`).`,
+  ];
+  for (const entry of moduleDocs) {
+    lines.push(`  - \`${entry.slug}\`: ${entry.title}`);
+  }
+  return lines;
+}
+
 function getOverview() {
   const availableTypes = readBuildArtifact({ name: 'plugins/availableTypes.json' }) ?? {};
   const counts = countKinds({ availableTypes });
@@ -45,12 +95,15 @@ function getOverview() {
     '',
     'This server describes everything installed in THIS project — never guess type names or properties, look them up here first.',
     '',
+    ...basePathLines(),
+    ...patternedPageLines(),
     '## What is available',
     '',
     `- ${counts.blocks} block types, ${counts.operators} operators, ${counts.actions} actions, ${counts.connections} connections, ${counts.requests} request types (from ${plugins.length} plugin packages, including this project's local plugins).`,
     manifest
       ? `- ${manifest.docs.length} core documentation pages (sections: ${sections.join(', ')}).`
       : '- Core documentation package (@lowdefy/docs-content) is not installed.',
+    ...appDocsLines(),
     '',
     '## How to use this (recommended order)',
     '',
@@ -58,27 +111,34 @@ function getOverview() {
     '2. **Get the exact contract**: `GET /lowdefy-docs/schema/{kind}/{type}` (e.g. `/lowdefy-docs/schema/blocks/Button`) — or `lowdefy_get_schema`. JSON Schema of all properties.',
     '3. **See real usage**: `GET /lowdefy-docs/examples/{type}` — or `lowdefy_get_examples`. YAML examples for block types.',
     '4. **Read concept docs**: `GET /lowdefy-docs/content/{slug}` (e.g. `/lowdefy-docs/content/operators/_get`) — or `lowdefy_get_doc`. Start with `concepts/lowdefy-schema`, `concepts/blocks`, `concepts/events-and-actions`, `concepts/connections-and-requests`, `concepts/operators`.',
-    '5. **Search**: `GET /lowdefy-docs/search?q=...` — or `lowdefy_search_docs`.',
-    '6. **Plugin packages**: `GET /lowdefy-docs/plugins` lists every installed plugin; `GET /lowdefy-docs/plugin-doc/{package}` returns markdown a plugin ships itself (READMEs, guides).',
+    '5. **Search**: `GET /lowdefy-docs/search?q=...` — or `lowdefy_search_docs`. The query is split into words and pages are ranked by how many match, title matches first. Each hit names its `source` (`core`, `plugin`, `local-plugin` or `module`), package and version; `&source=` narrows the search to one source.',
+    '6. **Icons**: `GET /lowdefy-docs/icons?q=...` — or `lowdefy_search_icons`. Use a semantic name (`icon: edit`); otherwise use a Lucide name in PascalCase (`icon: Receipt`) found by search. Never invent a name. In HTML use `<i data-icon="edit"></i>`, `data-tooltip` and `data-popover`.',
+    "7. **Plugin and module docs**: search and `lowdefy_get_doc` also cover the docs this app's own plugins and modules ship, local ones included: each README (`plugins/{package}`, `modules/{id}`), each `docs/*.md` file (`plugins/{package}/{file}`, `modules/{id}/{file}`), and for each module a generated page of the components, exports and vars its `module.lowdefy.yaml` declares (`modules/{id}/manifest`). `GET /lowdefy-docs/plugins` lists every installed plugin; `GET /lowdefy-docs/plugin-doc/{package}` returns all the markdown one plugin ships as one page.",
+    '',
+    'A `stale` field on a JSON response, a `> STALE:` banner on markdown, or an `X-Lowdefy-Stale` header means the last build FAILED and the served build is behind the source — this answer predates your latest edits. Call `GET /lowdefy-docs/build-status` and fix the errors before trusting anything else.',
     '',
     '## The feedback loop (after every edit)',
     '',
     'The dev server rebuilds automatically when config files change. After EVERY edit:',
     '',
-    '1. **Check what broke**: `GET /lowdefy-docs/build-status` — or `lowdefy_build_status`. Current build errors and warnings with source file locations, plus recent browser runtime errors.',
+    '1. **Check what broke**: `GET /lowdefy-docs/build-status?wait=true` — or `lowdefy_build_status` with `wait: true`, which answers once your latest edit has been processed and the pages it touched have been built. Current build errors and warnings with source file locations, the pages that fail to build (`pages.failed`), plus recent browser runtime errors. Errors from before the latest edit come apart under `earlierErrors`.',
+    '   Or subscribe instead of polling: `GET /lowdefy-docs/events` streams `build`, `client_error`, `server_error` and `restart` events over SSE (MCP clients receive the same as `notifications/message` from logger `lowdefy`).',
     '2. **Verify the page**: `GET /lowdefy-docs/page-config/{pageId}` — or `lowdefy_get_page_config`. The fully built page config, or its structured build errors.',
-    '3. **See it rendered**: `GET /lowdefy-docs/screenshot/{pageId}` — or `lowdefy_screenshot_page`. PNG of the page in headless Chromium.',
-    '4. **Locate config**: `GET /lowdefy-docs/find/{id}?pageId=...` — or `lowdefy_find_config`. Which yaml file defines a page/block/request id.',
-    '5. **Scaffold**: `lowdefy_scaffold_page` creates a canonical new page file (then register it in lowdefy.yaml).',
+    "3. **See it rendered**: `GET /lowdefy-docs/screenshot/{pageId}` — or `lowdefy_screenshot_page`. PNG of the page in headless Chromium; `?viewportWidth=390&colorScheme=dark` (the tool's `width` and `colorScheme`) checks a phone layout in dark mode.",
+    '4. **Verify behaviour**: `POST /lowdefy-docs/journey` `{pageId, steps, user, urlQuery, state}` — or `lowdefy_run_journey`. Drive the page headless with declarative steps (`click`, `fill`, `select`, `press`, `back`, `goto`, `email`, `as`, `wait`, `screenshot`, `expect: { state | visible | text | url | title }`) and assert what happens. `user: "none"` injects no caller, so sign-up, sign-in and invitations run through the app\'s own auth. Targets are a blockId, or `{ blockId, row, column, text, nth }` to reach the button in a grid cell, a control by its exact text, or — with `text` alone — a confirm dialog / modal footer button rendered outside every block. A failing step stops the journey and returns `passed: false` with `failure: { index, step, expected, actual, message }` and the final page `state` — data, not an error. A final state over 10000 characters comes back as `stateOmitted` (its size and top-level keys); pass `state: [paths]` for the paths you need, `true` for all of it or `false` for none.',
+    '5. **Locate config**: `GET /lowdefy-docs/find/{id}?pageId=...` — or `lowdefy_find_config`. Which yaml file defines a page/block/request id.',
+    '6. **Scaffold**: `lowdefy_scaffold_page` creates a canonical new page file (then register it in lowdefy.yaml).',
     '',
     '## Live state and testing',
     '',
     "1. **Inspect live state**: `GET /lowdefy-docs/inspect-state/{pageId}` — or `lowdefy_inspect_state`. The actual state, request results, and event log of a running page. Reads the developer's open browser tab when connected (ask them to interact, then inspect), else runs the page headless.",
     '2. **Evaluate operators**: `POST /lowdefy-docs/eval-operator` `{pageId, expression}` — or `lowdefy_eval_operator`. A REPL for config: run any operator expression against live page state. The operator goes in the `expression` body key (`operator` is accepted as an alias).',
-    '3. **Run a request**: `POST /lowdefy-docs/run-request` `{pageId, requestId, payload}` — or `lowdefy_run_request`. Verify the data shape a request returns. Read-only types always run; writes need `cli.agentTools.allowWriteRequests: true` in lowdefy.yaml.',
-    '4. **Understand the app**: `GET /lowdefy-docs/app-map` — or `lowdefy_app_map`. Every page, menu, connection, endpoint, agent, and websocket in one call.',
-    '5. **Config checkpoints**: `POST /lowdefy-docs/checkpoints` `{label}` / `POST /lowdefy-docs/checkpoints/revert` `{id}` — or `lowdefy_checkpoint` / `lowdefy_revert_checkpoint`. Snapshot config files before risky changes; revert instantly.',
-    "6. **State checkpoints**: `POST /lowdefy-docs/state-checkpoints/snapshot` `{pageId, name}` captures live page state + request responses into .lowdefy/state-checkpoints/<name>/ (gitignored — checkpoints contain user/session data); `POST /lowdefy-docs/state-checkpoints/load` `{name, mode}` restores it — 'registry-only' mode returns a ?_checkpoint URL a human can open to test the app in that exact state. `lowdefy_checkpoint_to_mocks` converts one into e2e mocks.yaml fixtures.",
+    '3. **Run a request**: `POST /lowdefy-docs/run-request` `{pageId, requestId, payload}` — or `lowdefy_run_request`. Verify the data shape a request returns. The page is rebuilt first when it changed since its last build. Read-only types always run; writes need `cli.agentTools.allowWriteRequests: true` in lowdefy.yaml. A response over 40,000 characters is written in full to `responseFile` under `.lowdefy/responses/`; add `saveResponse: true` to always write it there.',
+    '4. **Run an endpoint**: `POST /lowdefy-docs/run-endpoint` `{endpointId, payload, user}` — or `lowdefy_run_endpoint`. Run an Api routine headlessly and see what it returns, rejects or throws — a `:reject` comes back as `status: "reject"` with the routine\'s own error, not as a failure. Always needs `cli.agentTools.allowWriteRequests: true` (routines are not classified read-only). Add `system: true` to run a scheduled or detached-only `InternalApi` routine as a system context (no `_user`, auth not checked), the way cron does — not combinable with `user`. A large response is written to `responseFile` the same way as for a request, and `saveResponse: true` always writes it there.',
+    '5. **Understand the app**: `GET /lowdefy-docs/app-map` — or `lowdefy_app_map`. Every page, menu, connection, endpoint, agent, and websocket in one call.',
+    '6. **Config checkpoints**: `POST /lowdefy-docs/checkpoints` `{label}` / `POST /lowdefy-docs/checkpoints/revert` `{id}` — or `lowdefy_checkpoint` / `lowdefy_revert_checkpoint`. Snapshot config files before risky changes; revert instantly.',
+    "7. **State checkpoints**: `POST /lowdefy-docs/state-checkpoints/snapshot` `{pageId, name}` captures live page state + request responses into .lowdefy/state-checkpoints/<name>/ (gitignored — checkpoints contain user/session data); `POST /lowdefy-docs/state-checkpoints/load` `{name, mode}` restores it — 'registry-only' mode returns a ?_checkpoint URL a human can open to test the app in that exact state. `lowdefy_checkpoint_to_mocks` converts one into e2e mocks.yaml fixtures.",
+    '8. **Restart the server**: `POST /lowdefy-docs/restart` `{reason}` — or `lowdefy_restart` (through `lowdefy mcp`: `lowdefy_dev_start` with `restart: true`, a full process restart when the hub runs the server). Only when the server seems stuck or build-status looks stale, or after secrets a wrapper (for example infisical) injects have changed. Answers before the restart lands: then call `GET /lowdefy-docs/build-status?wait=true`, which answers once the restarted server is ready. `.env` edits and local plugin code need no restart: `.env` is watched and restarts the server, and a local plugin change rebuilds, restarting the server when the plugin has server-side types.',
     '',
     '## Visual feedback (annotation helper)',
     '',
@@ -93,19 +153,25 @@ function getOverview() {
     '| `GET /lowdefy-docs/plugins` | Installed plugin packages and the types each provides |',
     '| `GET /lowdefy-docs/schema/{kind}/{type}` | JSON schema for a type |',
     '| `GET /lowdefy-docs/examples/{type}` | Example yaml for a block type |',
-    '| `GET /lowdefy-docs/content/{slug}` | Core doc page as markdown |',
-    '| `GET /lowdefy-docs/search?q={query}` | Search core docs |',
+    '| `GET /lowdefy-docs/content/{slug}` | A doc page as markdown: core, plugin or module |',
+    '| `GET /lowdefy-docs/search?q={query}&source={source}` | Search the docs, ranked by matching words |',
+    '| `GET /lowdefy-docs/icons?q={query}` | Search icon names (semantic names first, then Lucide names, then installed icon sets) |',
     '| `GET /lowdefy-docs/plugin-doc/{package}` | Markdown shipped inside a plugin package |',
-    '| `GET /lowdefy-docs/build-status` | Current build errors/warnings + recent browser errors |',
+    '| `GET /lowdefy-docs/build-status` | Current build errors/warnings, failing pages + recent browser errors |',
+    '| `GET /lowdefy-docs/events` | SSE push channel: `restart` on connect, then `build`, `client_error`, `server_error` events as they happen (build events carry `stale`) |',
     '| `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 |',
+    '| `POST /lowdefy-docs/journey` | Drive a page headless through declarative steps (click, fill, select, press, back, goto, email, as, wait, screenshot, expect) and assert state, visibility, text, url or title; screenshots returned as base64 |',
+    '| `POST /lowdefy-docs/mutants` | Config mutants on what journeys exercised `{pages, requests, endpoints, appEvents, operators}`: each with a stable `id`, its anchor and source line (for `lowdefy journeys harden`) |',
     '| `GET /lowdefy-docs/find/{id}?pageId=` | Locate where a page/block/request id is defined |',
     '| `GET /lowdefy-docs/inspect-state/{pageId}?source=` | 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, or `system: true` for a cron-style system run (needs agent write access; rejects return as data) |',
     '| `GET /lowdefy-docs/app-map` | Whole-app graph: pages, menus, connections, endpoints, agents |',
     '| `GET/POST /lowdefy-docs/checkpoints` + `/revert` | Config-file checkpoints: list, create, revert |',
     '| `GET/POST /lowdefy-docs/state-checkpoints` + `/snapshot`, `/load` | State & data checkpoints: capture/restore live app state |',
+    '| `POST /lowdefy-docs/restart` | Restart the dev server process (answers before the restart lands; then `build-status?wait=true` answers once it is back) |',
     '| `POST /lowdefy-feedback` | Annotation helper: enrich + format a feedback batch (overlay → clipboard) |',
     '| `ALL /lowdefy-docs/mcp` | MCP endpoint (streamable HTTP) exposing all of the above as tools |',
   ];

package/lib/docs/getOverviewBasePath.test.mjs

@@ -0,0 +1,37 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import fs from 'fs';
+import path from 'path';
+
+import setupTestFixtures from './setupTestFixtures.mjs';
+
+// lib/build/config.js reads build/config.json from process.cwd() at import
+// time, so the fixture carries the basePath before getOverview is imported.
+const fixtureDir = setupTestFixtures();
+fs.writeFileSync(path.join(fixtureDir, 'build/config.json'), JSON.stringify({ basePath: '/app' }));
+fs.writeFileSync(path.join(fixtureDir, 'build', 'routes.json'), JSON.stringify([]));
+process.chdir(fixtureDir);
+
+const { default: getOverview } = await import('./getOverview.js');
+
+test('getOverview tells agents the docs routes are served under the app basePath', () => {
+  const overview = getOverview();
+
+  expect(overview).toContain(
+    'This app sets `config.basePath: /app`, so every route below is served under it: `GET /app/lowdefy-docs`, `/app/lowdefy-docs/mcp`, `/app/api/...`.'
+  );
+});

package/lib/docs/getPageBuildStatus.js

@@ -0,0 +1,46 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import reviewPageBuilds from './reviewPageBuilds.js';
+
+// The page side of build status. The dev server builds a page when it is first
+// requested, so the config build's status says nothing about page content:
+// this reports the pages whose latest build failed, the pages changed since
+// they were built, and how many pages nothing has built yet. checked is the
+// list of pages build status just built (wait: true).
+async function getPageBuildStatus({ checked } = {}) {
+  const { edited, unbuilt, failed } = await reviewPageBuilds();
+  const status = {};
+  if (checked) {
+    status.checked = checked;
+  }
+  if (failed.length > 0) {
+    status.failed = failed;
+  }
+  if (edited.length > 0) {
+    status.changedSinceBuild = edited;
+    status.changedSinceBuildNote = checked
+      ? 'These pages changed on disk after their last build, but the dev server has not rebuilt them: it has not seen the change yet. Call again; if they stay here, the file watcher missed the edit.'
+      : 'These pages, or the config build they build against, changed after their last build and have not been rebuilt, so their errors are not known yet. Call with wait: true to build them.';
+  }
+  status.unbuilt = unbuilt.length;
+  if (unbuilt.length > 0) {
+    status.unbuiltNote = `${unbuilt.length} page(s) have not been built since the dev server started, so this status does not cover them. lowdefy_check validates every page.`;
+  }
+  return status;
+}
+
+export default getPageBuildStatus;

package/lib/docs/getPluginDoc.js

@@ -15,40 +15,38 @@
 */
 
 import fs from 'node:fs';
-import path from 'node:path';
 import { type } from '@lowdefy/helpers';
 
+import listPackageDocFiles from './listPackageDocFiles.js';
+import readBuildArtifact from './readBuildArtifact.js';
+import readPluginPackages from './readPluginPackages.js';
 import resolvePluginDir from './resolvePluginDir.js';
 
-// Local plugins have no doc convention — probe the common locations and
-// return whatever markdown ships with the package.
+// The package name comes from the caller, and a name such as "../../x" would
+// resolve outside node_modules, so only the app's own plugins are read.
+function isAppPlugin({ packageName }) {
+  const installed = readBuildArtifact({ name: 'installedPluginPackages.json' }) ?? [];
+  if (installed.includes(packageName)) {
+    return true;
+  }
+  return readPluginPackages().some((plugin) => plugin.package === packageName);
+}
+
+// Every markdown file a plugin package ships, joined into one document.
 function getPluginDoc({ packageName }) {
+  if (!isAppPlugin({ packageName })) {
+    return null;
+  }
   const pluginDir = resolvePluginDir({ packageName });
   if (type.isNone(pluginDir)) {
     return null;
   }
-  const sections = [];
-  for (const readme of ['README.md', 'readme.md']) {
-    const readmePath = path.join(pluginDir, readme);
-    if (fs.existsSync(readmePath)) {
-      sections.push(fs.readFileSync(readmePath, 'utf8'));
-      break;
-    }
-  }
-  for (const docsDir of ['docs', 'dist/docs']) {
-    const dirPath = path.join(pluginDir, docsDir);
-    if (!fs.existsSync(dirPath)) {
-      continue;
-    }
-    for (const fileName of fs.readdirSync(dirPath).sort()) {
-      if (fileName.endsWith('.md')) {
-        sections.push(fs.readFileSync(path.join(dirPath, fileName), 'utf8'));
-      }
-    }
-  }
-  if (sections.length === 0) {
+  const { readme, docs } = listPackageDocFiles({ dir: pluginDir });
+  const files = type.isNone(readme) ? docs : [readme, ...docs];
+  if (files.length === 0) {
     return null;
   }
+  const sections = files.map((filePath) => fs.readFileSync(filePath, 'utf8'));
   return { package: packageName, markdown: sections.join('\n\n---\n\n') };
 }