diff --git a/get-started/deploy.mdx b/get-started/deploy.mdx
index 9ee9012..8d10a57 100644
--- a/get-started/deploy.mdx
+++ b/get-started/deploy.mdx
@@ -71,6 +71,8 @@ Because the file is generated locally, someone can change a data source or custo
     git diff --exit-code .forestadmin-schema.json
     ```
 
+    If `typingsPath` is set, `generateSchemaOnly()` also rewrites the typings file. Add it to the diff when you commit it (`git diff --exit-code .forestadmin-schema.json typings.ts`) so a stale one fails CI too; if you don't commit the typings, leave them out of the diff so a regenerated local copy doesn't break the build.
+
     Your CI job needs the same environment variables as your back-end (`FOREST_ENV_SECRET`, `FOREST_AUTH_SECRET`, `DATABASE_URL`): `createAgent` requires the secrets even though generation is offline by default. Experimental no-code customizations also fetch their configuration from Forest, which requires connectivity.
   </Tab>
   <Tab title="Ruby">
diff --git a/reference/agent-api/nodejs.mdx b/reference/agent-api/nodejs.mdx
index c898071..b9c12dd 100644
--- a/reference/agent-api/nodejs.mdx
+++ b/reference/agent-api/nodejs.mdx
@@ -309,7 +309,11 @@ Build the schema (`.forestadmin-schema.json`) and the TypeScript typings and wri
 await agent.generateSchemaOnly(): Promise<void>;
 ```
 
-It writes to the `schemaPath` (and `typingsPath`, when set) you configured in `createAgent`. Unlike `agent.start()`, it always rebuilds the schema, even when `isProduction` is `true`, and it never contacts Forest, with one exception: if you enable experimental no-code customizations, it still fetches their configuration from the Forest API, so connectivity is required in that case.
+It takes no arguments: it reads `schemaPath`, `typingsPath` and `typingsMaxDepth` from the options you passed to `createAgent`. It always writes the schema to `schemaPath`, and **also writes the TypeScript typings to `typingsPath` in the same pass whenever that option is set**. Unlike `agent.start()`, it always rebuilds the schema, even when `isProduction` is `true`, and it never contacts Forest, with one exception: if you enable experimental no-code customizations, it still fetches their configuration from the Forest API, so connectivity is required in that case.
+
+<Note>
+  Despite the name, `Only` means it *only generates the files* without starting the agent or sending the schema to Forest, not "the schema only". If you want to regenerate **only** the typings, use `agent.updateTypesOnFileSystem()` instead.
+</Note>
 
 **Example:**