docs: clarify macOS onboarding and troubleshooting

.nvmrc

@@ -1 +1 @@
-v24.15.0
+24

CONTRIBUTING.md

@@ -44,9 +44,14 @@ Flowise has 3 different modules in a single mono repository.
 
 #### Prerequisite
 
--   Install [PNPM](https://pnpm.io/installation). The project is configured to use pnpm v10.
+-   Install [PNPM](https://pnpm.io/installation). The project is currently tested with pnpm `10.26.x`.
     ```bash
-    npm i -g pnpm
+    npm i -g pnpm@10
+    ```
+-   Use Node `24.x` for local development.
+    ```bash
+    nvm install 24
+    nvm use 24
     ```
 
 #### Step by step
@@ -74,6 +79,49 @@ Flowise has 3 different modules in a single mono repository.
     pnpm install
     ```
 
+#### Local environment troubleshooting (macOS)
+
+-   Verify installed versions and paths:
+
+    ```bash
+    node -v
+    pnpm -v
+    which pnpm
+    ```
+
+-   The repository is currently tested against pnpm `10.26.x`. Using pnpm `11.x` may result in engine mismatch errors.
+
+-   If `pnpm` is not found:
+
+    ```bash
+    corepack enable
+    corepack prepare pnpm@10.26.2 --activate
+    ```
+
+    Or install globally:
+
+    ```bash
+    npm install -g pnpm@10.26.2
+    ```
+
+-   If you recently switched pnpm versions or changed your PATH, refresh zsh’s command cache:
+
+    ```bash
+    hash -r
+    ```
+
+-   If `which pnpm` points to a Homebrew installation while using `nvm`, you may have conflicting pnpm binaries in your PATH.
+    If you use both Homebrew and `nvm`, make sure the expected pnpm binary is first in your PATH.
+
+-   If you encounter `JavaScript heap out of memory` during build:
+
+    ```bash
+    export NODE_OPTIONS="--max-old-space-size=8192"
+    pnpm build
+    ```
+
+    Adjust the heap size depending on available system memory (for example: `4096` or `8192`).
+
 7. Build all the code:
 
     ```bash

README.md

@@ -90,12 +90,38 @@ Flowise has 3 different modules in a single mono repository.
 -   `components`: Third-party nodes integrations
 -   `api-documentation`: Auto-generated swagger-ui API docs from express
 
-### Prerequisite
+### Prerequisites
 
--   Install [PNPM](https://pnpm.io/installation)
-    ```bash
-    npm i -g pnpm
-    ```
+#### macOS Setup
+
+-   Node: v24.x (recommended)
+
+    -   Using nvm:
+        ```bash
+        nvm install 24
+        nvm use 24
+        ```
+    -   Verify:
+        ```bash
+        node -v
+        # Expected output: v24.x.x
+        ```
+
+-   pnpm: v10.26.x (recommended)
+    -   Recommended via `corepack`:
+        ```bash
+        corepack enable
+        corepack prepare pnpm@10.26.2 --activate
+        ```
+    -   Or via npm:
+        ```bash
+        npm install -g pnpm@10.26.2
+        ```
+    -   Verify:
+        ```bash
+        pnpm -v
+        # Expected output: 10.26.x
+        ```
 
 ### Setup
 
@@ -117,6 +143,9 @@ Flowise has 3 different modules in a single mono repository.
     pnpm install
     ```
 
+    > [!NOTE]
+    > The repository is currently tested against pnpm `10.26.x`. Using pnpm `11.x` may result in engine mismatch errors.
+
 4.  Build all the code:
 
     ```bash
@@ -129,7 +158,7 @@ Flowise has 3 different modules in a single mono repository.
 
     ```bash
     # macOS / Linux / Git Bash
-    export NODE_OPTIONS="--max-old-space-size=4096"
+    export NODE_OPTIONS="--max-old-space-size=8192"
 
     # Windows PowerShell
     $env:NODE_OPTIONS="--max-old-space-size=4096"
@@ -138,6 +167,8 @@ Flowise has 3 different modules in a single mono repository.
     set NODE_OPTIONS=--max-old-space-size=4096
     ```
 
+    Adjust the value depending on available system memory (for example: `4096` or `8192`).
+
     Then run:
 
     ```bash