diff --git a/docs/introduction.md b/docs/introduction.md
index cff0f2ac2..59f04df2b 100644
--- a/docs/introduction.md
+++ b/docs/introduction.md
@@ -33,9 +33,19 @@ _Note: OpenAPI 2.x is supported with versions `5.x` and previous_
 This library requires the latest version of [Node.js](https://nodejs.org) installed (20.x or higher recommended). With that present, run the following in your project:
 
 ```bash
-npm i -D openapi-typescript typescript
+npm i -D openapi-typescript typescript@5
 ```
 
+::: warning TypeScript 7 applications
+
+The generator needs the JavaScript compiler API provided by its TypeScript 5 peer dependency.
+TypeScript 7.0 does not expose that API through `typescript`. Keep your application's TypeScript 7
+compiler and run generation in a separate tooling package with `openapi-typescript` and
+`typescript@5`. Your application can still type-check the generated types with TypeScript 7.
+See [Node.js setup](./node.md#setup) for the compiler boundary when using custom transforms.
+
+:::
+
 And in your `tsconfig.json`, to load the types properly:
 
 ::: code-group
diff --git a/docs/node.md b/docs/node.md
index bd837887a..665169c21 100644
--- a/docs/node.md
+++ b/docs/node.md
@@ -10,9 +10,16 @@ The Node API may be useful if dealing with dynamically-created schemas, or you
 ## Setup
 
 ```bash
-npm i --save-dev openapi-typescript typescript
+npm i --save-dev openapi-typescript typescript@5
 ```
 
+For applications using TypeScript 7, run the generator script in a separate tooling package with
+these dependencies; leave the application's compiler unchanged. Import `typescript` from that
+tooling package in custom transforms too: callbacks and returned AST nodes must use the same
+JavaScript compiler API as the generator. Pass the generated source file, not compiler AST objects,
+to the TypeScript 7 application. This is side-by-side tooling, not native TypeScript 7 API support.
+See [TypeScript's side-by-side guidance](https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/#running-side-by-side-with-typescript-6.0).
+
 ::: tip Recommended
 
 For the best experience, use Node ESM by adding `"type": "module"` to `package.json` ([docs](https://nodejs.org/api/esm.html#enabling))