docs: lead onboarding with the npm SDK install path (#37)

Author: piotrblaszczyk

.changeset/wb-217-actions-hook.md

@@ -2,4 +2,4 @@
 '@workflowbuilder/sdk': minor
 ---
 
-feat: add `useWorkflowBuilderActions()`. Gives custom layouts that omit `<WorkflowBuilder.TopBar />` imperative save / import / export / settings / read-only / theme / layout-direction actions. Also exports the `WorkflowBuilderActions`, `LayoutChangeOptions`, and `Theme` types. See [Custom layout without the app bar](https://www.workflowbuilder.io/docs/get-started/quick-start/wb-as-react-component/#custom-layout-without-the-app-bar).
+feat: add `useWorkflowBuilderActions()`. Gives custom layouts that omit `<WorkflowBuilder.TopBar />` imperative save / import / export / settings / read-only / theme / layout-direction actions. Also exports the `WorkflowBuilderActions`, `LayoutChangeOptions`, and `Theme` types. See [Custom toolbar without the app bar](https://www.workflowbuilder.io/docs/guides/configuring-the-editor/#custom-toolbar-without-the-app-bar).

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/**` |

README.md

@@ -2,7 +2,7 @@
 
 <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/)
 
 **Workflow Builder**
 
@@ -38,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    |
 
-Want to skip the clone entirely? [Try the live demo](https://app.workflowbuilder.io) first.
+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:
+
+```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.
 
@@ -81,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.
 
@@ -104,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.
 
@@ -180,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                                                                              |

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

@@ -5,7 +5,7 @@
 >
 > 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/execution-worker/README.md

@@ -1,6 +1,6 @@
 # @workflow-builder/execution-worker
 
-> **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 worker's internals.
+> **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 worker's internals.
 
 Background process that executes workflow graphs submitted by the backend. Currently backed by Temporal; structured so other engines (in-memory, BullMQ, …) can slot in without touching domain logic.
 

packages/sdk/src/features/integration/README.md

@@ -16,7 +16,7 @@ By default, Workflow Builder is a standalone app. You can build the application
 
 Workflow Builder can function as a component within an existing React application. This allows you to integrate its functionality directly into your app rather than hosting it separately.
 
-How to embed Workflow Builder in an existing React codebase: see the [React component quick-start](https://www.workflowbuilder.io/docs/get-started/quick-start/wb-as-react-component/), which covers installation, peer deduplication (local-path build until npm publish), usage, and configuration.
+How to embed Workflow Builder in an existing React codebase: see the [React component quick-start](https://www.workflowbuilder.io/docs/get-started/quick-start/wb-as-react-component/), which covers installation from npm, usage, and configuration.
 
 You can also build your application as an npm package and then simply consume it in your application.