Merge pull request #39 from synergycodes/main

Release v2.1.0

Author: piotrblaszczyk

.github/workflows/release-sdk.yml

@@ -104,7 +104,9 @@ jobs:
         # so the GitHub Release body matches what consumers see on npm.
         run: |
           VERSION=$(node -p "require('./packages/sdk/package.json').version")
-          NOTES=$(awk "/^## ${VERSION}\$/{flag=1;next}/^## /{flag=0}flag" packages/sdk/CHANGELOG.md)
+          # Matches either a bracketed Keep-a-Changelog heading
+          # (`## [X.Y.Z] - 2026-06-16`) or a bare Changesets heading (`## X.Y.Z`).
+          NOTES=$(awk -v v="$VERSION" '$0 ~ ("^## \\[?" v "\\]?([ -]|$)"){flag=1;next}/^## /{flag=0}flag' packages/sdk/CHANGELOG.md)
           {
             echo "notes<<EOF"
             echo "$NOTES"

CLAUDE.md

@@ -4,25 +4,25 @@ Visual workflow editor SDK (React) with a reference backend and Temporal-based e
 
 ## Quick Reference
 
-Three onboarding paths (A, B local-run; C docs-only). README "Get started" is the canonical guide for A and B. Path C ("Embed the SDK") lives in the [docs site](https://www.workflowbuilder.io/docs/get-started/quick-start/wb-as-react-component/) and has no local-stack commands.
+Three onboarding paths (A installs from npm; B, C run the repo locally). README "Get started" covers all three. Path A ("Embed the SDK") installs `@workflowbuilder/sdk` from npm; the README has install + a minimal snippet, and the full guide lives in the [docs site](https://www.workflowbuilder.io/docs/get-started/quick-start/wb-as-react-component/).
 
 | Command                      | Path | What it does                                                                |
 | ---------------------------- | ---- | --------------------------------------------------------------------------- |
-| `pnpm preflight`             | both | Verify Node / pnpm / Docker / ports / `.env` files. Add `--json` for agents |
-| `pnpm dev` / `pnpm dev:demo` | A    | Demo (UI only, port 4200). No backend, no Docker                            |
-| `pnpm infra:up`              | B    | Start Postgres + Temporal in Docker. Required before backend/worker         |
-| `pnpm -F backend db:migrate` | B    | Apply Drizzle migrations. First run, or after schema changes                |
-| `pnpm dev:ai-studio`         | B    | Full stack: infra + backend (3001) + worker + AI Studio frontend (4201)     |
-| `pnpm dev:backend`           | B    | Backend only (debug). Needs infra up                                        |
-| `pnpm dev:worker`            | B    | Execution worker only (debug). Needs infra up                               |
-| `pnpm infra:down`            | B    | Stop the Docker stack                                                       |
+| `pnpm preflight`             | B/C  | Verify Node / pnpm / Docker / ports / `.env` files. Add `--json` for agents |
+| `pnpm dev` / `pnpm dev:demo` | B    | Demo (UI only, port 4200). No backend, no Docker                            |
+| `pnpm infra:up`              | C    | Start Postgres + Temporal in Docker. Required before backend/worker         |
+| `pnpm -F backend db:migrate` | C    | Apply Drizzle migrations. First run, or after schema changes                |
+| `pnpm dev:ai-studio`         | C    | Full stack: infra + backend (3001) + worker + AI Studio frontend (4201)     |
+| `pnpm dev:backend`           | C    | Backend only (debug). Needs infra up                                        |
+| `pnpm dev:worker`            | C    | Execution worker only (debug). Needs infra up                               |
+| `pnpm infra:down`            | C    | Stop the Docker stack                                                       |
 | `pnpm dev:docs`              | -    | Docs site (Astro + Starlight)                                               |
 | `pnpm build:lib`             | -    | Build the SDK package (`packages/sdk`)                                      |
 | `pnpm build`                 | -    | Build the demo app                                                          |
 | `pnpm test`                  | -    | Run tests in `packages/sdk` and `packages/execution-core`                   |
 | `pnpm check`                 | -    | Lint + typecheck + format + knip                                            |
 
-Path A is UI-only and does not need Docker. Path B requires `pnpm infra:up` before backend/worker can start, and `db:migrate` on the first run.
+Path B is UI-only and does not need Docker. Path C requires `pnpm infra:up` before backend/worker can start, and `db:migrate` on the first run.
 
 ### Agent signals
 
@@ -123,7 +123,7 @@ If you're new to this repo and want to build your own consumer app or POC, follo
 | `/wb.create-plugin <name>`         | Scaffold a new SDK plugin — asks for target app (default `demo`)                                                                      |
 | `/wb.create-template <name>`       | Scaffold a new diagram template — asks for target app (default `demo`)                                                                |
 | `/wb.add-execution-handler <type>` | Wire a node type into execution-core + worker registry (global pipeline, no target)                                                   |
-| `/wb.run-locally`                  | Bring up the stack — Path A (`pnpm dev:demo`) or Path B (infra + backend + worker + AI Studio frontend)                               |
+| `/wb.run-locally`                  | Bring up the stack — Path B (`pnpm dev:demo`) or Path C (infra + backend + worker + AI Studio frontend)                               |
 | `/wb.task`                         | Fetch assigned ClickUp tasks via MCP and recommend one to pick up                                                                     |
 | `/wb.task WB-42`                   | Pick up a specific task with an inline plan                                                                                           |
 | `/wb.changeset <bump> "<summary>"` | Add a changeset for SDK changes (`patch` / `minor` / `major`) — required before merging consumer-visible changes to `packages/sdk/**` |
@@ -145,9 +145,11 @@ The SDK is the only npm-published workspace; everything else under `apps/` and `
    ```
 4. Open PR to `main`. The changeset file is part of the PR diff — reviewer sees the declared bump alongside the change.
 
+**`<WorkflowBuilder.Root>` props live on three surfaces.** The type in `packages/sdk/src/workflow-builder-root/workflow-builder-root.types.ts` is the source of truth; the `/api/core/workflowbuilderrootprops/` reference is generated from its JSDoc and never drifts. Two hand-written tables mirror it: `packages/sdk/README.md` (npm landing) and `apps/docs/src/content/docs/guides/configuring-the-editor.md` (docs guide). When you add, rename, or remove a prop, update both tables in the same change. Descriptions may differ per surface (the README leans on gotchas, the guide on how / when); the set of prop names must match.
+
 **Release moment** (maintainer, not Claude):
 
-1. Open PR `release/vX.Y.Z` → `release`. In the branch, run `pnpm changeset version` — bumps `packages/sdk/package.json`, regenerates `packages/sdk/CHANGELOG.md`, deletes consumed `.changeset/*.md`.
+1. Open PR `release/vX.Y.Z` → `release`. In the branch, run `pnpm changeset version` — bumps `packages/sdk/package.json`, regenerates `packages/sdk/CHANGELOG.md` (then reformat it into Keep a Changelog style before committing, see [`packages/sdk/RELEASE.md`](packages/sdk/RELEASE.md) § "Reformat the generated CHANGELOG section"), deletes consumed `.changeset/*.md`.
 2. Review the diff, merge the PR into `release`.
 3. Tag the merge commit on `release`: `git tag vX.Y.Z && git push origin vX.Y.Z`.
 4. GitHub Action triggered by the tag runs lint + typecheck + test + `pnpm publish --provenance` (authenticated via npm Trusted Publisher / OIDC, no `NPM_TOKEN` stored anywhere) + creates a GitHub Release.

README.md

@@ -2,11 +2,13 @@
 
 <a href="https://www.workflowbuilder.io/"><img alt="Workflow Builder" src="https://cdn.synergycodes.com/workflow-builder-logo-solid.svg" width="201" height="40"></a>
 
-[Live Demo](https://app.workflowbuilder.io/) &nbsp;|&nbsp; [Documentation](https://www.workflowbuilder.io/docs/overview/) &nbsp;|&nbsp; [Website](https://www.workflowbuilder.io/)
+[Live Demo](https://app.workflowbuilder.io/) &nbsp;|&nbsp; [Documentation](https://www.workflowbuilder.io/docs/overview/) &nbsp;|&nbsp; [npm](https://www.npmjs.com/package/@workflowbuilder/sdk) &nbsp;|&nbsp; [Website](https://www.workflowbuilder.io/)
 
-**Frontend SDK for embedding production-ready workflow editors.**
+**Workflow Builder**
 
-Workflow Builder is an open-source SDK that gives you a ready-made workflow editor UI - canvas, nodes, edges, layout, and configuration panels - so you don't have to build workflow UX from scratch. It focuses exclusively on the frontend editor layer; execution, orchestration, and business logic stay fully under your control. The SDK outputs workflow definitions as JSON that your own backend executes.
+**Apache 2.0 React SDK for embedding visual workflow editors.**
+
+Drag-and-drop workflow builder UI with a reference back-end and an execution engine swappable by design, proven with Temporal. Back-end agnostic. Built on React Flow and Temporal. Reference stack for AI workflows and automations in digital products.
 
 ---
 
@@ -36,16 +38,47 @@ Three onboarding paths. Pick one based on what you want to evaluate.
 
 | Goal                                                   | Path                                                          | Setup time | Docker |
 | ------------------------------------------------------ | ------------------------------------------------------------- | ---------- | ------ |
-| See the editor running in your browser                 | [A. Try the demo](#path-a-try-the-demo)                       | ~2 min     | no     |
-| Run the full reference stack (editor + execution + AI) | [B. Run the full stack demo](#path-b-run-the-full-stack-demo) | ~10 min    | yes    |
-| Use the SDK inside your own React app                  | [C. Embed the SDK](#path-c-embed-the-sdk)                     | see docs   | no     |
+| Use the SDK inside your own React app                  | [A. Embed the SDK](#path-a-embed-the-sdk)                     | ~1 min     | no     |
+| See the editor running in your browser                 | [B. Try the demo](#path-b-try-the-demo)                       | ~2 min     | no     |
+| Run the full reference stack (editor + execution + AI) | [C. Run the full stack demo](#path-c-run-the-full-stack-demo) | ~10 min    | yes    |
+
+Don't want to install or clone anything yet? [Try the live demo](https://app.workflowbuilder.io) in your browser first.
+
+### Path A. Embed the SDK
+
+Use Workflow Builder inside your own React app. No clone, no Docker. Install the SDK and its peer dependencies from npm:
+
+```bash
+npm install @workflowbuilder/sdk \
+  react react-dom \
+  @xyflow/react \
+  @jsonforms/core @jsonforms/react \
+  i18next react-i18next i18next-browser-languagedetector \
+  immer zustand
+```
+
+Render the editor:
 
-Want to skip the clone entirely? [Try the live demo](https://app.workflowbuilder.io) first.
+```tsx
+import { WorkflowBuilder } from '@workflowbuilder/sdk';
+
+import '@workflowbuilder/sdk/style.css';
+
+export function App() {
+  return <WorkflowBuilder.Root name="my-workflow" />;
+}
+```
+
+It mounts the default layout (top bar, palette, canvas, properties panel) and persists to `localStorage` out of the box. The palette is empty until you pass `nodeTypes`.
+
+Full guide (props, persistence strategies, theming, plugins, and the API reference): [React Component on the docs site](https://www.workflowbuilder.io/docs/get-started/quick-start/wb-as-react-component/).
+
+The two paths below run this repository locally (demo and full stack). They share the requirements and preflight check that follow. Path A needs neither.
 
 ### Requirements
 
 - Node `22.12.0` and pnpm `10.9.0`. Both pinned in `package.json`. Use `nvm`, `fnm`, or `corepack` to match.
-- Docker Desktop. Only required for Path B.
+- Docker Desktop. Only required for Path C.
 
 Works the same on macOS, Linux, and Windows. No platform-specific steps.
 
@@ -79,11 +112,11 @@ Workflow Builder preflight
 Ready to go. Pick a path in README.md "Get started".
 ```
 
-The two `.env` warnings are expected on a fresh clone. They are only required for Path B and get created by `pnpm setup:env` in step 1 of that path. After that they switch to `✅ present`.
+The two `.env` warnings are expected on a fresh clone. They are only required for Path C and get created by `pnpm setup:env` in step 1 of that path. After that they switch to `✅ present`.
 
 Fix any red (`❌`) items before continuing. The script also has a `--json` mode for tooling: `pnpm preflight --json`.
 
-### Path A. Try the demo
+### Path B. Try the demo
 
 UI only. No backend, no Docker. The fastest way to see the editor in action.
 
@@ -102,7 +135,7 @@ Expected output:
 
 Open `http://localhost:4200`. The editor loads with the default plugin set and a starter template. That's it.
 
-### Path B. Run the full stack demo
+### Path C. Run the full stack demo
 
 Full reference product: editor, Hono backend, Temporal worker, Postgres. The frontend on port 4201 is the **AI Studio** reference product (`apps/ai-studio`). Demonstrates end-to-end workflow execution.
 
@@ -178,10 +211,6 @@ AI_MODEL=anthropic/claude-3.5-haiku
 
 If the key is missing the worker fails to start with `OPENROUTER_API_KEY is required`. If the model id is wrong the first AI node fails at runtime and the error surfaces in the UI log panel.
 
-### Path C. Embed the SDK
-
-To build your own React app on top of `@workflowbuilder/sdk`, follow the [React Component guide on the docs site](https://www.workflowbuilder.io/docs/get-started/quick-start/wb-as-react-component/). It covers installation, peer deduplication (for local-path builds until npm publish), usage, persistence strategies, theming, and the full API reference.
-
 ### Troubleshooting
 
 | Symptom                                                                 | Cause                                                                 | Fix                                                                              |
@@ -266,7 +295,7 @@ Workflow Builder is available in two editions:
 
 For companies that need end-to-end implementations or any other support, we offer professional consulting services.
 
-Our team has delivered **170+ custom workflow tools** across 20+ industries and brings **15+ years** of experience building enterprise-class diagramming and automation tools. We can help with:
+Our team has delivered **200+ custom workflow tools** across 20+ industries and brings **15+ years** of experience building enterprise-class diagramming and automation tools. We can help with:
 
 - backend execution engines
 - custom integrations

apps/ai-studio/README.md

@@ -4,7 +4,7 @@ Reference frontend for the Workflow Builder AI Studio product. Consumes `@workfl
 
 > ⚠️ Local development only. Depends on the reference backend, which has no auth/authz. See [apps/backend/README.md](../backend/README.md).
 
-> **Note:** setup is in [root README "Path B. Run the full stack demo"](../../README.md#path-b-run-the-full-stack-demo).
+> **Note:** setup is in [root README "Path C. Run the full stack demo"](../../README.md#path-c-run-the-full-stack-demo).
 
 ## What this is
 

apps/backend/README.md

@@ -2,8 +2,10 @@
 
 > ⚠️ **Reference implementation, local development only.**
 > No real authentication. The bundled `AllowAllAuthPort` permits every caller and every action (see `src/auth/`), and the constructor refuses to start without the explicit `WB_AUTH_PORT=allow-all` opt-in so a forgotten env var fails loudly. No tenant isolation. The HTTP server and the docker-compose services bind to `127.0.0.1` by default. Do not expose to the internet or shared networks without first plugging in a real `AuthPort`, see [`auth-port.decision-log.md`](./auth-port.decision-log.md) for the seam, default, and a JWT adapter sketch.
+>
+> Seams for consumers to plug in: [`AuthPort`](./auth-port.decision-log.md) for authn/authz, [`TenantContextPort`](./tenant-context-port.decision-log.md) for multi-tenant identity propagation (wiring guide: [`multi-tenancy.md`](./multi-tenancy.md)).
 
-> **Note:** setup is in [root README "Path B. Run the full stack demo"](../../README.md#path-b-run-the-full-stack-demo). This file documents the backend's internals, not how to start it.
+> **Note:** setup is in [root README "Path C. Run the full stack demo"](../../README.md#path-c-run-the-full-stack-demo). This file documents the backend's internals, not how to start it.
 
 Backend execution layer for Workflow Builder AI Studio plugin. Runs AI workflows defined on the canvas via Temporal + OpenRouter.
 

apps/backend/drizzle/0001_odd_iron_lad.sql

@@ -0,0 +1,4 @@
+ALTER TABLE "execution_events" ADD COLUMN "tenant_id" text;--> statement-breakpoint
+ALTER TABLE "executions" ADD COLUMN "tenant_id" text;--> statement-breakpoint
+CREATE INDEX "execution_events_tenant_id_idx" ON "execution_events" USING btree ("tenant_id");--> statement-breakpoint
+CREATE INDEX "executions_tenant_id_idx" ON "executions" USING btree ("tenant_id");