diff --git a/markdown-pages/docs/manual/installation.mdx b/markdown-pages/docs/manual/installation.mdx
index 62a979517..f02c9ba87 100644
--- a/markdown-pages/docs/manual/installation.mdx
+++ b/markdown-pages/docs/manual/installation.mdx
@@ -133,6 +133,15 @@ bun create rescript-app
 
   </CodeTab>
 
+  <Info>
+    **pnpm users:** ReScript-compiled JS imports from `@rescript/runtime` directly, but pnpm's strict isolation does not expose transitive dependencies at the app root. Either install the runtime as a direct dependency (`pnpm add @rescript/runtime`), or hoist it by adding the following to `pnpm-workspace.yaml`:
+
+    ```yaml
+    publicHoistPattern:
+      - "*@rescript/runtime*"
+    ```
+  </Info>
+
 - Create a ReScript build configuration file (called `rescript.json`) at the root:
   ```json
   {
diff --git a/markdown-pages/docs/manual/migrate-to-v12.mdx b/markdown-pages/docs/manual/migrate-to-v12.mdx
index 684405dbe..fecf60840 100644
--- a/markdown-pages/docs/manual/migrate-to-v12.mdx
+++ b/markdown-pages/docs/manual/migrate-to-v12.mdx
@@ -51,7 +51,17 @@ if you had `@rescript/std` installed, remove it as well:
 npm uninstall @rescript/std
 ```
 
-this is replaced by `@rescript/runtime`, which is a installed as a dependency of `rescript` now.
+this is replaced by `@rescript/runtime`, which is installed as a dependency of `rescript` now.
+
+<Info>
+  **pnpm users:** since pnpm does not hoist transitive dependencies, you may need to install `@rescript/runtime` as a direct dependency (`pnpm add @rescript/runtime`), or hoist it by adding the following to `pnpm-workspace.yaml`:
+
+```yaml
+publicHoistPattern:
+  - "*@rescript/runtime*"
+```
+
+</Info>
 
 ## Replacements