Configuration

A flow has a draft and published revisions. The widget loads published config with a publishable key. Publishing stores that JSON on Bootstrapware. It does not grant live entitlement by itself.

What lives in config

  • Items. Up to 32 steps: key, title, description, optional href and ctaLabel (max 80 characters; widget defaults to Continue), optional flag, dependsOn, progressScope (user or workspace), eligibility.
  • Eligibility. Optional roles, plans, and flags (max 16 flags, match all or any) on the flow and on each item. The dashboard flow editor edits those fields; evaluation stays in the widget from host context. Never send host context through MCP.
  • Toggles. requireAuthorToken, empty-state copy, snooze days (default 1 and 7), allowed origins.
  • Branding. Optional logo URL and accent (primaryColor). Cream + lime by default. When primaryColor is set, it writes --bsw-ob-accent inline and overrides the theme accent.

Local mode can pass items as props and skip hosted fetch. Hosted and BYO typically load items from the published flow so agents can update the checklist without a code deploy. Path C (adapter + flowId + publishableKey) still fetches config; the adapter only owns progress.

Theme

Visual theme is a component prop, not a published flow field. theme is "light" | "dark". Omit it and the checklist stays the light cream default, with no data-theme attribute. v1 does not follow prefers-color-scheme or the system theme. theme="dark" sets data-theme="dark".

Hosts may set these CSS custom properties on the embed root (.bsw-ob): --bsw-ob-bg, --bsw-ob-panel, --bsw-ob-fg, --bsw-ob-muted, --bsw-ob-line, --bsw-ob-ok, --bsw-ob-error, --bsw-ob-accent, --bsw-ob-accent-fg, --bsw-ob-radius. These overrides are the supported API. Do not fight .bsw-* classes. With theme="dark", target .bsw-ob[data-theme="dark"] so your values win over the dark defaults.

Next step and item CTAs

The widget highlights the first incomplete, unblocked, applicable item as the next step (in-list). focusedAnchor Spotlight stays host opt-in and is separate.

  • Items with href: the primary control is a button-styled link. Label is optional ctaLabel, otherwise Continue. Mark complete is secondary.
  • Items without href: Mark complete stays primary.
  • Blocked items: no primary CTA; existing “Complete … first” copy remains.
  • Clicking the href CTA does not auto-complete. Facts and host completeStep remain the source of truth.

Optional ctaLabel is additive and backwards compatible. It round-trips the dashboard flow editor, MCP update_draft, published config, and the widget. Omit it to keep Continue.

How to change it

  • Dashboard flow editor (preview, publish, restore). Item eligibility and Duplicate live here. Delete stays dashboard-only.
  • MCP: create_flow, update_draft (does not publish), publish_flow, list_revisions, restore_revision, get_published_config.
  • Secret HTTP: create, PATCH draft, POST publish. See API.

Live fetch still needs a plan

Live bsw_live_pub_ config fetch needs BYO ($9.99) or Hosted ($19.99). Live Hosted progress writes need Hosted ($19.99). Test keys work unpaid. Local adapters never call Bootstrapware.

Related: React component · Revisions · Eligibility · Preview and rollback · API · Environments