diff --git a/docs/README.md b/docs/README.md
index e33093d8..940cc50b 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -66,44 +66,3 @@ Get an overview of how telemetry works for this project
 
 ### [AI Assistants](./ai-assistants.md)
 Connect AI assistants like Claude Code, Cursor, and Windsurf to The Codegen Project via MCP (Model Context Protocol) for intelligent code generation assistance.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/contributing.md b/docs/contributing.md
index 781352fd..9f8c6871 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -134,94 +134,3 @@ Pull requests should have a title that follows the specification, otherwise, mer
 What about MAJOR release? just add `!` to the prefix, like `fix!: ` or `refactor!: `
 
 Prefix that follows specification is not enough though. Remember that the title must be clear and descriptive with usage of [imperative mood](https://chris.beams.io/posts/git-commit/#imperative).
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/migrations/v0.md b/docs/migrations/v0.md
index 35bc87ac..6b1ca3b1 100644
--- a/docs/migrations/v0.md
+++ b/docs/migrations/v0.md
@@ -222,34 +222,3 @@ import * as NodeFetch from 'node-fetch';
 1. Regenerate your code.
 2. Remove `node-fetch` and `@types/node-fetch` from your project's dependencies if they were only used by the generated client.
 3. Ensure your runtime provides a global `fetch` (Node.js 18+). If you need a custom HTTP implementation, supply it through the `makeRequest` hook instead of relying on the default.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/usage.md b/docs/usage.md
index 48cda2a0..61018564 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -8,7 +8,7 @@ $ npm install -g @the-codegen-project/cli
 $ codegen COMMAND
 running command...
 $ codegen (--version)
-@the-codegen-project/cli/0.81.1 linux-x64 node-v22.23.1
+@the-codegen-project/cli/0.81.1 <platform> node-<version>
 $ codegen --help [COMMAND]
 USAGE
   $ codegen COMMAND
diff --git a/package.json b/package.json
index 70db2b7d..58503fa7 100644
--- a/package.json
+++ b/package.json
@@ -109,7 +109,8 @@
     "build:browser:minify": "node esbuild.browser.mjs --minify",
     "dev": "tsc --watch",
     "generate:readme:commands": "oclif readme --readme-path=\"./docs/usage.md\" --output-dir=\"./docs\"",
-    "generate:assets": "npm run generate:readme:toc && npm run generate:commands && npm run generate:schema && npm run format && npm run generate:examples",
+    "generate:assets": "npm run generate:readme:toc && npm run generate:commands && npm run generate:docs:normalize && npm run generate:schema && npm run format && npm run generate:examples",
+    "generate:docs:normalize": "node scripts/normalizeGeneratedDocs.js",
     "generate:schema": "node scripts/generateSchemaFiles.js",
     "generate:playground": "npm run build:browser && cd website && npm run copy:bundle && npm run copy:schema",
     "generate:mcp:docs": "cd mcp-server && npm ci && npm run bundle-docs",
diff --git a/scripts/normalizeGeneratedDocs.js b/scripts/normalizeGeneratedDocs.js
new file mode 100644
index 00000000..38b5dda7
--- /dev/null
+++ b/scripts/normalizeGeneratedDocs.js
@@ -0,0 +1,53 @@
+/**
+ * Makes `npm run generate:assets` idempotent for the markdown docs it rewrites.
+ *
+ * Two upstream tools leave non-deterministic output behind:
+ *
+ * 1. `markdown-toc -i` appends one blank line every time it actually rewrites a
+ *    file, so each release grew docs/README.md, docs/contributing.md and
+ *    docs/migrations/v0.md by one trailing newline.
+ * 2. `oclif readme` renders the sample `codegen --version` output using the
+ *    platform and Node.js version of whoever ran it, so the line flipped
+ *    between machines (and between Node.js patch releases on CI).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const repoRoot = path.resolve(__dirname, '..');
+
+/** Files rewritten by `generate:readme:toc` / `generate:commands`. */
+const docs = [
+  'README.md',
+  'docs/usage.md',
+  'docs/README.md',
+  'docs/contributing.md',
+  'docs/migrations/v0.md'
+];
+
+/** `@the-codegen-project/cli/1.2.3 darwin-arm64 node-v24.15.0` */
+const versionSample = /^(@the-codegen-project\/cli\/\S+) \S+ node-\S+$/m;
+const versionSampleReplacement = '$1 <platform> node-<version>';
+
+const changed = [];
+
+for (const relativePath of docs) {
+  const filePath = path.join(repoRoot, relativePath);
+  const original = fs.readFileSync(filePath, 'utf8');
+
+  let normalized = `${original.replace(/\s+$/, '')}\n`;
+  if (relativePath === 'docs/usage.md') {
+    normalized = normalized.replace(versionSample, versionSampleReplacement);
+  }
+
+  if (normalized !== original) {
+    fs.writeFileSync(filePath, normalized);
+    changed.push(relativePath);
+  }
+}
+
+console.log(
+  changed.length > 0
+    ? `Normalized:\n  ${changed.join('\n  ')}`
+    : 'Normalized: no changes needed'
+);