chore: make generate:assets idempotent

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.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-

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).
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-

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.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-

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

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",

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'
+);