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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lowdefy/docs-content",
-  "version": "0.0.0-experimental-20260928120643",
+  "version": "6.1.0",
   "license": "Apache-2.0",
   "description": "Lowdefy documentation extracted as markdown for AI coding agents.",
   "homepage": "https://lowdefy.com",
@@ -20,20 +20,14 @@
   "type": "module",
   "exports": {
     "./index.json": "./index.json",
-    "./hazards.json": "./hazards.json",
     "./scripts/extractAgentDocs.js": "./scripts/extractAgentDocs.js",
-    "./scripts/hashDocSources.js": "./scripts/hashDocSources.js",
     "./content/*": "./content/*"
   },
   "files": [
     "content/**",
-    "hazards.json",
     "index.json",
     "scripts/*"
   ],
-  "dependencies": {
-    "@lowdefy/nunjucks": "0.0.0-experimental-20260928120643"
-  },
   "publishConfig": {
     "access": "public"
   }

package/scripts/extractAgentDocs.js

@@ -18,8 +18,6 @@ import fs from 'fs';
 import path, { dirname } from 'path';
 import { fileURLToPath } from 'url';
 
-import { nunjucksFunction } from '@lowdefy/nunjucks';
-
 // Runs inside the docs app build (see packages/docs/templates/generateSiteAssets.js),
 // where pages are fully resolved: _refs inlined, template vars substituted.
 // Markdown content lives on Markdown/MarkdownWithCode block properties in
@@ -53,37 +51,12 @@ function resolvePageSections(pages, menus) {
   return sectionMap;
 }
 
-function isPlainObject(value) {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-// Many docs pages write their markdown as a `_nunjucks` template so it can
-// print the current version (`on: { version: _ref: version.yaml }`). With its
-// _refs resolved, such a template renders to the same markdown at build time
-// as in the browser. A template that reads state or other runtime operators
-// (the live examples on block pages) has no static rendering and is skipped.
-function renderStaticNunjucks(value) {
-  if (!isPlainObject(value) || !isPlainObject(value._nunjucks)) return undefined;
-  const { template, on = {} } = value._nunjucks;
-  if (typeof template !== 'string' || !isPlainObject(on)) return undefined;
-  const vars = {};
-  for (const [key, varValue] of Object.entries(on)) {
-    if (key.startsWith('~')) continue;
-    if (key.startsWith('_') || (typeof varValue === 'object' && varValue !== null)) {
-      return undefined;
-    }
-    vars[key] = varValue;
-  }
-  return nunjucksFunction(template)(vars);
-}
-
 function extractPageMarkdown(page) {
   const parts = [];
   function collect(value) {
-    const markdown = typeof value === 'string' ? value : renderStaticNunjucks(value);
-    // Other runtime operators are objects — only static content is docs content.
-    if (typeof markdown === 'string' && markdown.trim() !== '') {
-      parts.push(markdown.trim());
+    // Unresolved runtime operators are objects — only static strings are docs content.
+    if (typeof value === 'string' && value.trim() !== '') {
+      parts.push(value.trim());
     }
   }
   function walkBlock(block) {
@@ -126,10 +99,6 @@ function extractAgentDocs({ pages, menus, outputDir }) {
   fs.rmSync(contentDir, { recursive: true, force: true });
 
   const docs = [];
-  // The ref each page was resolved from (a non-enumerable build marker).
-  // recordSourceHashes, which runs after the build, maps it to the page's
-  // source files through the build's refMap.
-  const sources = {};
   pages.filter(Boolean).forEach((page) => {
     const title = page.properties?.title ?? page.id;
     const section = sectionMap.get(page.id)?.label ?? 'Other';
@@ -150,12 +119,11 @@ function extractAgentDocs({ pages, menus, outputDir }) {
       doc.typeName = title;
     }
     docs.push(doc);
-    sources[slug] = { refId: page['~r'] };
   });
 
   fs.writeFileSync(
     path.join(outputDir, 'index.json'),
-    JSON.stringify({ version: packageJson.version, docs, sources }, null, 2)
+    JSON.stringify({ version: packageJson.version, docs }, null, 2)
   );
 }
 

package/content/actions/emailotpsend.md

@@ -1,58 +0,0 @@
-# EmailOtpSend
-
-```
-(params: {
-  email: string
-  captchaToken?: string
-}): void
-```
-
-The `EmailOtpSend` action emails a one-time sign-in code to an address. It requires `auth.emailOTP` to be enabled — see [Configuration](/auth-configuration).
-
-A code is typed into the tab the person started from, so the sign-in survives corporate mail security that pre-fetches links (which consumes a single-use magic link before the person clicks it), and it works when the email is read on another device.
-
-Use [`EmailOtpVerify`](/EmailOtpVerify) to complete the sign-in with the code.
-
-When `auth.magicLink` is enabled alongside `auth.emailOTP`, the magic-link email already carries the code: the [`Login`](/Login) action with `magicLink: true` sends one email that serves both paths, and `EmailOtpSend` is then only needed for a code-only page that offers no link at all.
-
-Under an invite-only signup policy an address that is not admitted gets no email, and the action still resolves successfully — the response is identical either way, so the "check your email" screen gives nothing away about who has an account.
-
-#### Parameters
-
-###### object
-- `email: string`: __required__ - The email address to send the sign-in code to.
-- `captchaToken: string`: A captcha token minted by a `Captcha` block, sent as the `x-captcha-response` header when `auth.captcha` is enabled. Tokens are single-use, so reset the `Captcha` block in `onError` for retries.
-
-#### Examples
-
-###### Send a sign-in code:
-```yaml
-- id: send_code
-  type: EmailOtpSend
-  params:
-    email:
-      _state: email
-```
-
-###### Send a code and tell the user to check their inbox:
-```yaml
-- id: send_code
-  type: Button
-  properties:
-    title: Send code
-  events:
-    onClick:
-      - id: validate
-        type: Validate
-        params:
-          regex: ^email$
-      - id: send
-        type: EmailOtpSend
-        params:
-          email:
-            _state: email
-      - id: sent
-        type: DisplayMessage
-        params:
-          content: Check your email for the sign-in code.
-```

package/content/actions/emailotpverify.md

@@ -1,77 +0,0 @@
-# EmailOtpVerify
-
-```
-(params: {
-  email: string
-  otp: string
-  callbackUrl?: {
-    home?: boolean
-    pageId?: string
-    url?: string
-    urlQuery?: object
-  } | false
-}): void
-```
-
-The `EmailOtpVerify` action signs a user in with the one-time code emailed to them by [`EmailOtpSend`](/EmailOtpSend), or carried on the magic-link email when `auth.magicLink` and `auth.emailOTP` are both enabled. It requires `auth.emailOTP` to be enabled — see [Configuration](/auth-configuration).
-
-On success the session cookie is set — creating the account on first sign-in, unless `emailOTP.disableSignUp` is `true` — and the browser lands on the resolved `callbackUrl`. Three sources are consulted, in order:
-
-1. The `callbackUrl` param, if given.
-2. The `?callbackUrl=` query parameter, which Lowdefy sets when it redirects an unauthenticated user to the sign-in page.
-3. The app's home page.
-
-To sign in without navigating, set `callbackUrl: false` — valid here, unlike on the magic-link and social paths, because this is a plain JSON sign-in with no redirect hop.
-
-If the user has two-factor authentication enrolled, the code mints a challenge rather than a session: the action navigates to `authPages.twoFactor` carrying the resolved destination as `?callbackUrl=`, where [`TwoFactorVerify`](/two-factor) finishes the sign-in, and the event chain stops.
-
-An expired, mistyped or already-used code is the auth server rejecting the attempt, not an app fault. The action throws a `UserError`: `catch` actions still run and the message still displays, but it is logged to the browser console only and is never reported to the server.
-
-#### Parameters
-
-###### object
-- `email: string`: __required__ - The email address the code was sent to.
-- `otp: string`: __required__ - The one-time code from the email.
-- `callbackUrl: object | false`: Set to `false` to sign in without navigating. As an object:
-  - `home: boolean`: Land on the app's home page.
-  - `pageId: string`: The pageId to land on.
-  - `url: string`: The URL to land on. An absolute URL is not `basePath`-prefixed, so it can be an external landing page.
-  - `urlQuery: object`: The urlQuery to set on the destination.
-
-#### Examples
-
-###### Sign in with the code and land on the home page (or the page the user was bounced from):
-```yaml
-- id: verify_code
-  type: EmailOtpVerify
-  params:
-    email:
-      _state: email
-    otp:
-      _state: otp
-```
-
-###### Sign in and land on a specific page:
-```yaml
-- id: verify_code
-  type: EmailOtpVerify
-  params:
-    email:
-      _state: email
-    otp:
-      _state: otp
-    callbackUrl:
-      pageId: dashboard
-```
-
-###### Sign in inside a modal, without navigating:
-```yaml
-- id: verify_code
-  type: EmailOtpVerify
-  params:
-    email:
-      _state: email
-    otp:
-      _state: otp
-    callbackUrl: false
-```

package/content/actions/getlocalstorage.md

@@ -1,41 +0,0 @@
-# GetLocalStorage
-
-```
-(params: {
-  key: string,
-  default?: any
-}): any
-```
-
-The `GetLocalStorage` action reads a value from the browser's [local storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage). Values written by the [`SetLocalStorage`](/SetLocalStorage) action are deserialized, so objects, arrays and dates are returned as the same types that were stored.
-
-Local storage is per browser and per origin, so a value stored in one browser is not available in another.
-
-A value that was not written by `SetLocalStorage` and is not valid JSON is returned as the plain string that is stored. If the browser blocks local storage, the action returns the `default` value, as if the key were not set. Keys starting with `lowdefy_` or `lf-` are reserved for settings Lowdefy stores itself, such as the dark mode preference, and the action throws an error if one is used.
-
-#### Parameters
-
-###### object
-  - `key: string`: __Required__ - The local storage key to read. Keys starting with `lowdefy_` or `lf-` are reserved.
-  - `default: any`: The value returned when the key is not set in local storage, or when the browser blocks local storage.
-
-#### Response
-
-The value stored at the key, or the `default` value when the key is not set or local storage is blocked. When the key is not set and no `default` is given, the response is `undefined`.
-
-#### Examples
-
-###### Restore a user preference on page load:
-```yaml
-- id: read_preference
-  type: GetLocalStorage
-  params:
-    key: dashboard_filters
-    default:
-      status: open
-- id: apply_preference
-  type: SetState
-  params:
-    filters:
-      _actions: read_preference.response
-```

package/content/actions/magiclinkverify.md

@@ -1,113 +0,0 @@
-# MagicLinkVerify
-
-```
-(params?: {
-  callbackUrl?: {
-    home?: boolean
-    pageId?: string
-    url?: string
-    urlQuery?: object
-  }
-  errorCallbackUrl?: {
-    home?: boolean
-    pageId?: string
-    url?: string
-    urlQuery?: object
-  }
-  newUserCallbackUrl?: {
-    home?: boolean
-    pageId?: string
-    url?: string
-    urlQuery?: object
-  }
-  token?: string
-}): void
-```
-
-The `MagicLinkVerify` action completes a magic-link sign-in from the landing page the sign-in email points at. It navigates the browser to the auth server's verify endpoint, which sets the session cookie and redirects the user on to their destination.
-
-## Why a landing page
-
-A magic-link token is single-use, and the verify endpoint consumes it on the **first** `GET` of the URL. Corporate mail security — Microsoft Defender Safe Links, Proofpoint URL Defense, Mimecast — fetches every link in a message as it is delivered. When the email links straight at the verify endpoint the scanner spends the token minutes before the person clicks, and the person lands on the auth error page with `INVALID_TOKEN`.
-
-Setting [`auth.authPages.magicLink`](/auth-configuration#the-magic-link-landing-page) to a page in your app moves the email's link to that page, carrying the token and callback destinations on the URL query. Fetching a Lowdefy page has no side effect, so the token stays unspent until a person clicks a button that runs `MagicLinkVerify`.
-
-This action **must** be bound to a click. Do not run it in `onMount` and do not auto-redirect from the landing page: scanning sandboxes that execute JavaScript would consume the token anyway, and you would be no better off than linking at the verify endpoint directly.
-
-## Defaults come from the URL query
-
-Every parameter is optional. The auth server minted the landing URL with the verify query on it, so the action reads its defaults from the page's own URL:
-
-| Parameter | Default |
-| --------- | ------- |
-| `token` | the `?token=` query parameter |
-| `callbackUrl` | the `?callbackURL=` query parameter, else the auth server's default |
-| `newUserCallbackUrl` | the `?newUserCallbackURL=` query parameter, else `callbackUrl` |
-| `errorCallbackUrl` | the `?errorCallbackURL=` query parameter, else `auth.authPages.error` |
-
-Pass a parameter only to override what the email carried. The action throws if there is no token in either place, because there is nothing to verify.
-
-`callbackUrl: false` is not valid here. Verification redirects through a hop the app does not control, so there is no staying put.
-
-The event chain ends after this action, like every other action that navigates the browser away — a step after it would race the page being replaced.
-
-#### Parameters
-
-###### object
-- `token: string`: The single-use magic-link token. Defaults to the `?token=` URL query parameter of the landing page.
-- `callbackUrl: object`: Where a successful sign-in lands. Defaults to the `?callbackURL=` URL query parameter.
-  - `home: boolean`: Land on the app's home page.
-  - `pageId: string`: The pageId to land on.
-  - `url: string`: The URL to land on. An absolute URL is not `basePath`-prefixed, so it can be an external landing page.
-  - `urlQuery: object`: The urlQuery to set on the destination.
-- `newUserCallbackUrl: object`: Where a sign-in that creates a new account lands, for a first-run or onboarding page. Defaults to the `?newUserCallbackURL=` URL query parameter. Same fields as `callbackUrl`.
-- `errorCallbackUrl: object`: Where a failed verification lands, with the reason in `?error=`. Defaults to the `?errorCallbackURL=` URL query parameter, then to `auth.authPages.error`. Same fields as `callbackUrl`.
-
-#### Examples
-
-###### The landing page, with everything taken from the URL query:
-```yaml
-id: magic-link
-type: PageHeaderMenu
-blocks:
-  - id: content
-    type: Box
-    blocks:
-      - id: title
-        type: Title
-        properties:
-          content: Sign in
-          level: 3
-      - id: description
-        type: Paragraph
-        properties:
-          content: Click the button below to finish signing in.
-      - id: verify_button
-        type: Button
-        properties:
-          title: Sign in
-        events:
-          onClick:
-            - id: verify
-              type: MagicLinkVerify
-```
-
-###### Send a new user to an onboarding page instead:
-```yaml
-- id: verify
-  type: MagicLinkVerify
-  params:
-    newUserCallbackUrl:
-      pageId: welcome
-```
-
-###### Override where a successful sign-in lands:
-```yaml
-- id: verify
-  type: MagicLinkVerify
-  params:
-    callbackUrl:
-      pageId: dashboard
-      urlQuery:
-        source: magic-link
-```

package/content/actions/posthogalias.md

@@ -1,29 +0,0 @@
-# PostHogAlias
-
-```
-(params: {
-  alias: string,
-}): Promise<null>
-```
-
-The `PostHogAlias` action points a second id at the person PostHog already knows, for example when an app has its own identifier alongside the one used by [`PostHogIdentify`](/PostHogIdentify).
-
-When PostHog is disabled or `posthog-js` could not be loaded, the action does nothing. Invalid params always throw, even when PostHog is disabled.
-
-The action is part of the [`@lowdefy/plugin-posthog`](/PostHog) plugin, which is included by default. See the [PostHog guide](/PostHog) for how the actions fit together.
-
-#### Parameters
-
-###### object
-  - `alias: string`: __Required__ - The second id for the current person.
-
-#### Examples
-
-###### Alias a customer number:
-```yaml
-- id: alias_person
-  type: PostHogAlias
-  params:
-    alias:
-      _user: customerNumber
-```

package/content/actions/posthogcapture.md

@@ -1,49 +0,0 @@
-# PostHogCapture
-
-```
-(params: {
-  event: string,
-  properties?: object,
-  groups?: object,
-}): Promise<null>
-```
-
-The `PostHogCapture` action captures a named product event in [PostHog](https://posthog.com).
-
-Autocapture already records clicks and pageviews, so keep the set of named events small. Every event is billable, and a funnel of thirty near identical events tells you less than one of five. Never send personally identifiable information as a property.
-
-When PostHog is disabled or `posthog-js` could not be loaded, the action does nothing. Invalid params always throw, even when PostHog is disabled.
-
-The action is part of the [`@lowdefy/plugin-posthog`](/PostHog) plugin, which is included by default. See the [PostHog guide](/PostHog) for how the actions fit together.
-
-#### Parameters
-
-###### object
-  - `event: string`: __Required__ - The event name. Snake case names that read as a completed action, like `report_submitted`, work best in funnels.
-  - `properties: object`: Event properties.
-  - `groups: object`: Groups to attach to this one event, as `{ groupType: groupKey }`. Sent to PostHog as the `$groups` property.
-
-#### Examples
-
-###### Capture an event after a request:
-```yaml
-- id: submit_report
-  type: Button
-  properties:
-    title: Submit report
-  events:
-    onClick:
-      - id: submit
-        type: Request
-        params: submit_report
-      - id: capture_event
-        type: PostHogCapture
-        params:
-          event: report_submitted
-          properties:
-            report_type:
-              _state: report_type
-            line_item_count:
-              _array.length:
-                _state: line_items
-```

package/content/actions/posthogcapturepageleave.md

@@ -1,38 +0,0 @@
-# PostHogCapturePageLeave
-
-```
-(params: {
-  properties?: object,
-}): Promise<null>
-```
-
-The `PostHogCapturePageLeave` action captures a `$pageleave` event by hand, the counterpart to [`PostHogPageview`](/PostHogPageview). PostHog uses pageleaves to compute bounce rate and time on page.
-
-`posthog-js` captures a pageleave itself when the tab is closed, as long as automatic pageviews are on, because `capture_pageleave` defaults to `if_capture_pageview`. With `capture_pageview: false`, set `capture_pageleave: true` in the [`PostHogInit`](/PostHogInit) options to keep them, or use this action, for example before a `Link` or `Logout` action. The page `onHidden` event is not a page leave: it also fires when the browser window loses focus.
-
-When PostHog is disabled or `posthog-js` could not be loaded, the action does nothing. Invalid params always throw, even when PostHog is disabled.
-
-The action is part of the [`@lowdefy/plugin-posthog`](/PostHog) plugin, which is included by default. See the [PostHog guide](/PostHog) for how the actions fit together.
-
-#### Parameters
-
-###### object
-  - `properties: object`: Properties to add to the `$pageleave` event.
-
-#### Examples
-
-###### Capture a pageleave before signing out:
-```yaml
-- id: sign_out
-  type: Button
-  properties:
-    title: Sign out
-  events:
-    onClick:
-      - id: capture_pageleave
-        type: PostHogCapturePageLeave
-      - id: reset_posthog
-        type: PostHogReset
-      - id: logout
-        type: Logout
-```

package/content/actions/posthogfeatureflag.md

@@ -1,50 +0,0 @@
-# PostHogFeatureFlag
-
-```
-(params: {
-  key: string,
-  default?: any,
-  enabled?: boolean,
-  payload?: boolean,
-}): Promise<any>
-```
-
-The `PostHogFeatureFlag` action reads a PostHog feature flag and returns its value, so it can be used further down the action chain with the [`_actions`](/_actions) operator.
-
-The value is whatever PostHog resolved for this person when flags were last loaded; the action does not wait for a network call. When the person or their groups just changed, reload the flags first with [`PostHogReloadFeatureFlags`](/PostHogReloadFeatureFlags).
-
-Reading a flag value, with or without `enabled`, sends a `$feature_flag_called` event to PostHog, which is what PostHog experiments use to count exposures. Reading a payload does not.
-
-When PostHog is disabled, not initialised, or `posthog-js` could not be loaded, the action returns `default`. Invalid params always throw, even when PostHog is disabled.
-
-The action is part of the [`@lowdefy/plugin-posthog`](/PostHog) plugin, which is included by default. See the [PostHog guide](/PostHog) for how the actions fit together.
-
-#### Parameters
-
-###### object
-  - `key: string`: __Required__ - The feature flag key.
-  - `default: any`: Returned when the flag has no value for this person, and when PostHog is disabled. Defaults to `null`.
-  - `enabled: boolean`: Return a boolean, using `isFeatureEnabled`, instead of the variant value.
-  - `payload: boolean`: Return the flag payload, using `getFeatureFlagPayload`, instead of the flag value. Takes precedence over `enabled`.
-
-#### Response
-
-The flag value, the payload, or a boolean, depending on the params. `default` when the flag has no value.
-
-#### Examples
-
-###### Store a flag variant in state:
-```yaml
-events:
-  onMount:
-    - id: read_flag
-      type: PostHogFeatureFlag
-      params:
-        key: new-checkout
-        default: control
-    - id: store_flag
-      type: SetState
-      params:
-        checkout_variant:
-          _actions: read_flag.response
-```

package/content/actions/posthoggroup.md

@@ -1,37 +0,0 @@
-# PostHogGroup
-
-```
-(params: {
-  type: string,
-  key: string,
-  properties?: object,
-}): Promise<null>
-```
-
-The `PostHogGroup` action associates the current person with a group, so events can be analysed per organization, team or account. The association sticks until [`PostHogReset`](/PostHogReset) is called, so run it after [`PostHogIdentify`](/PostHogIdentify). Group types have to be enabled on the PostHog project.
-
-When PostHog is disabled or `posthog-js` could not be loaded, the action does nothing. Invalid params always throw, even when PostHog is disabled.
-
-The action is part of the [`@lowdefy/plugin-posthog`](/PostHog) plugin, which is included by default. See the [PostHog guide](/PostHog) for how the actions fit together.
-
-#### Parameters
-
-###### object
-  - `type: string`: __Required__ - The group type, for example `organization`.
-  - `key: string`: __Required__ - The id of the group instance.
-  - `properties: object`: Group properties.
-
-#### Examples
-
-###### Associate the person with their organization:
-```yaml
-- id: set_group
-  type: PostHogGroup
-  params:
-    type: organization
-    key:
-      _user: organizationId
-    properties:
-      plan:
-        _user: plan
-```

package/content/actions/posthogidentify.md

@@ -1,54 +0,0 @@
-# PostHogIdentify
-
-```
-(params: {
-  id?: string | null,
-  properties?: object,
-  propertiesOnce?: object,
-}): Promise<null>
-```
-
-The `PostHogIdentify` action ties the current browser session to a person in [PostHog](https://posthog.com). Run it once the user is known, usually right after [`PostHogInit`](/PostHogInit) in the shared page `onInit` actions, or after a successful login.
-
-A missing, `null` or empty `id` is a no-op, so on a public page the anonymous session is left alone. That anonymous session is what a later `PostHogIdentify` merges into the person, which is what makes signup funnels work.
-
-The action is safe to run on every page. It reads the identity `posthog-js` already holds:
-
-- __Same person__: when `id` is already the current `distinct_id`, it only updates the person properties, if any are given. `posthog-js` skips a property update identical to the previous one.
-- __Person swap__: PostHog refuses to move an identified `distinct_id` onto a different person, so when the browser is identified as someone else, the action calls `reset()` before identifying the new person.
-- __Anonymous visitor__: identified without a reset, so the anonymous session merges into the person.
-
-Never send personally identifiable information as a person property.
-
-When PostHog is disabled or `posthog-js` could not be loaded, the action does nothing. Invalid params always throw, even when PostHog is disabled.
-
-The action is part of the [`@lowdefy/plugin-posthog`](/PostHog) plugin, which is included by default. See the [PostHog guide](/PostHog) for how the actions fit together.
-
-#### Parameters
-
-###### object
-  - `id: string`: The person's id.
-  - `properties: object`: Person properties to set. `null` and `undefined` values are dropped, so an absent value never overwrites one PostHog already has.
-  - `propertiesOnce: object`: Person properties that are only set the first time, for example a signup date.
-
-#### Examples
-
-###### Identify the logged in user on every page:
-```yaml
-# shared/posthog_init.yaml
-- id: init_posthog
-  type: PostHogInit
-  params:
-    apiKey:
-      _build.env: POSTHOG_API_KEY
-- id: identify_person
-  type: PostHogIdentify
-  params:
-    id:
-      _user: id
-    properties:
-      role:
-        _user: role
-      locale:
-        _locale: active
-```