From 867c80d02a5d225bb865446a937ccfa97557122a Mon Sep 17 00:00:00 2001
From: John Doe <john.doe@example.com>
Date: Tue, 2 Dec 2025 21:54:16 +0100
Subject: [PATCH 01/24] refactor: move models-transformers into tools

---
 packages/models/project.json                  |  2 +-
 packages/models/tsconfig.lib.json             |  8 +--
 tools/jsdoc-annotation-transformer/README.md  | 69 +++++++++++++++++++
 .../eslint.config.cjs                         |  2 +-
 .../package.json                              |  2 +-
 .../project.json                              | 10 +--
 .../src/index.ts                              |  0
 .../src/lib/transformers.ts                   |  0
 .../tsconfig.json                             |  2 +-
 .../tsconfig.lib.json                         |  3 +-
 .../tsconfig.spec.json                        | 29 ++++++++
 .../vitest.unit.config.ts                     |  3 +
 12 files changed, 113 insertions(+), 17 deletions(-)
 create mode 100644 tools/jsdoc-annotation-transformer/README.md
 rename {packages/models/transformers => tools/jsdoc-annotation-transformer}/eslint.config.cjs (67%)
 rename {packages/models/transformers => tools/jsdoc-annotation-transformer}/package.json (82%)
 rename {packages/models/transformers => tools/jsdoc-annotation-transformer}/project.json (58%)
 rename {packages/models/transformers => tools/jsdoc-annotation-transformer}/src/index.ts (100%)
 rename {packages/models/transformers => tools/jsdoc-annotation-transformer}/src/lib/transformers.ts (100%)
 rename {packages/models/transformers => tools/jsdoc-annotation-transformer}/tsconfig.json (81%)
 rename {packages/models/transformers => tools/jsdoc-annotation-transformer}/tsconfig.lib.json (76%)
 create mode 100644 tools/jsdoc-annotation-transformer/tsconfig.spec.json
 create mode 100644 tools/jsdoc-annotation-transformer/vitest.unit.config.ts

diff --git a/packages/models/project.json b/packages/models/project.json
index 0045b607e..d76e0034f 100644
--- a/packages/models/project.json
+++ b/packages/models/project.json
@@ -21,7 +21,7 @@
       "dependsOn": [
         "^build",
         "generate-docs",
-        { "projects": "models-transformers", "target": "build" }
+        { "projects": "jsdocs-annotation-transformer", "target": "build" }
       ]
     },
     "lint": {},
diff --git a/packages/models/tsconfig.lib.json b/packages/models/tsconfig.lib.json
index 2c92983e0..23ebd7dba 100644
--- a/packages/models/tsconfig.lib.json
+++ b/packages/models/tsconfig.lib.json
@@ -3,13 +3,7 @@
   "compilerOptions": {
     "outDir": "../../dist/out-tsc",
     "declaration": true,
-    "types": ["node"],
-    "plugins": [
-      {
-        "transform": "./packages/models/transformers/dist",
-        "afterDeclarations": true
-      }
-    ]
+    "types": ["node"]
   },
   "include": ["src/**/*.ts"],
   "exclude": [
diff --git a/tools/jsdoc-annotation-transformer/README.md b/tools/jsdoc-annotation-transformer/README.md
new file mode 100644
index 000000000..033289349
--- /dev/null
+++ b/tools/jsdoc-annotation-transformer/README.md
@@ -0,0 +1,69 @@
+# @code-pushup/jsdocs-annotation-transformer
+
+TypeScript transformer plugin that automatically enhances type definitions with JSDoc comments and schema metadata.
+
+## Purpose
+
+This package provides a TypeScript compiler transformer that automatically adds JSDoc documentation to type aliases and interfaces during compilation. It's designed to improve developer experience by injecting helpful metadata and documentation links directly into generated type definitions.
+
+## How It Works
+
+The transformer hooks into the TypeScript compilation process using `ts-patch` and automatically adds JSDoc comments above type definitions. Each comment includes:
+
+- The type name
+- A description explaining the type is derived from a Zod schema
+- A link to the models reference documentation
+
+## Example
+
+Given a type definition like:
+
+```typescript
+export type Report = {
+  // ... type properties
+};
+```
+
+The transformer automatically generates:
+
+```typescript
+/**
+ * Type Definition: `Report`
+ *
+ * This type is derived from a Zod schema and represents
+ * the validated structure of `Report` used within the application.
+ *
+ * @see {@link https://github.com/code-pushup/cli/blob/main/packages/models/docs/models-reference.md#report}
+ */
+export type Report = {
+  // ... type properties
+};
+```
+
+## Usage
+
+1. ts-patch install
+
+2. Add the transformer to your `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "plugins": [
+      {
+        "transform": "./packages/models/transformers/dist",
+        "afterDeclarations": true
+      }
+    ]
+  }
+}
+```
+
+3. Build your TypeScript project. The transformer will run automatically and add JSDoc comments to your type definitions.
+
+### Options
+
+| Option              | Type      | Required | Description                                                                                                                                                         |
+| ------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `transform`         | `string`  | Yes      | Path to the transformer module                                                                                                                                      |
+| `afterDeclarations` | `boolean` | No       | Set to `true` to run the transformer after TypeScript generates declaration files (`.d.ts`). This ensures JSDoc comments are added to the emitted type definitions. |
diff --git a/packages/models/transformers/eslint.config.cjs b/tools/jsdoc-annotation-transformer/eslint.config.cjs
similarity index 67%
rename from packages/models/transformers/eslint.config.cjs
rename to tools/jsdoc-annotation-transformer/eslint.config.cjs
index 4eaecdb17..467b6c94b 100644
--- a/packages/models/transformers/eslint.config.cjs
+++ b/tools/jsdoc-annotation-transformer/eslint.config.cjs
@@ -1,4 +1,4 @@
-const baseConfig = require('../../../eslint.config.js').default;
+const baseConfig = require('../../eslint.config.js').default;
 
 module.exports = [
   ...baseConfig,
diff --git a/packages/models/transformers/package.json b/tools/jsdoc-annotation-transformer/package.json
similarity index 82%
rename from packages/models/transformers/package.json
rename to tools/jsdoc-annotation-transformer/package.json
index e5d33d01b..273fd5821 100644
--- a/packages/models/transformers/package.json
+++ b/tools/jsdoc-annotation-transformer/package.json
@@ -1,5 +1,5 @@
 {
-  "name": "@code-pushup/models-transformers",
+  "name": "@code-pushup/jsdocs-annotation-transformer",
   "version": "0.0.0",
   "description": "TypeScript transformers enhancing models with JSDoc and schema metadata",
   "type": "commonjs",
diff --git a/packages/models/transformers/project.json b/tools/jsdoc-annotation-transformer/project.json
similarity index 58%
rename from packages/models/transformers/project.json
rename to tools/jsdoc-annotation-transformer/project.json
index 9b3ed9b10..bcdbbeb48 100644
--- a/packages/models/transformers/project.json
+++ b/tools/jsdoc-annotation-transformer/project.json
@@ -1,7 +1,7 @@
 {
-  "name": "models-transformers",
+  "name": "jsdoc-annotation-transformer",
   "$schema": "../../../node_modules/nx/schemas/project-schema.json",
-  "sourceRoot": "packages/models/transformers/src",
+  "sourceRoot": "tools/jsdoc-annotation-transformer/src",
   "projectType": "library",
   "targets": {
     "build": {
@@ -9,9 +9,9 @@
       "outputs": ["{options.outputPath}"],
       "dependsOn": ["pre-build"],
       "options": {
-        "outputPath": "packages/models/transformers/dist",
-        "main": "packages/models/transformers/src/index.ts",
-        "tsConfig": "packages/models/transformers/tsconfig.lib.json"
+        "outputPath": "tools/jsdoc-annotation-transformer/dist",
+        "main": "tools/jsdoc-annotation-transformer/src/index.ts",
+        "tsConfig": "tools/jsdoc-annotation-transformer/tsconfig.lib.json"
       }
     },
     "pre-build": {
diff --git a/packages/models/transformers/src/index.ts b/tools/jsdoc-annotation-transformer/src/index.ts
similarity index 100%
rename from packages/models/transformers/src/index.ts
rename to tools/jsdoc-annotation-transformer/src/index.ts
diff --git a/packages/models/transformers/src/lib/transformers.ts b/tools/jsdoc-annotation-transformer/src/lib/transformers.ts
similarity index 100%
rename from packages/models/transformers/src/lib/transformers.ts
rename to tools/jsdoc-annotation-transformer/src/lib/transformers.ts
diff --git a/packages/models/transformers/tsconfig.json b/tools/jsdoc-annotation-transformer/tsconfig.json
similarity index 81%
rename from packages/models/transformers/tsconfig.json
rename to tools/jsdoc-annotation-transformer/tsconfig.json
index fe17bec70..0c1036efe 100644
--- a/packages/models/transformers/tsconfig.json
+++ b/tools/jsdoc-annotation-transformer/tsconfig.json
@@ -1,5 +1,5 @@
 {
-  "extends": "../../../tsconfig.base.json",
+  "extends": "../../tsconfig.base.json",
   "compilerOptions": {
     "module": "commonjs",
     "verbatimModuleSyntax": false
diff --git a/packages/models/transformers/tsconfig.lib.json b/tools/jsdoc-annotation-transformer/tsconfig.lib.json
similarity index 76%
rename from packages/models/transformers/tsconfig.lib.json
rename to tools/jsdoc-annotation-transformer/tsconfig.lib.json
index 48174f134..bebaef047 100644
--- a/packages/models/transformers/tsconfig.lib.json
+++ b/tools/jsdoc-annotation-transformer/tsconfig.lib.json
@@ -4,7 +4,8 @@
     "outDir": "./dist",
     "rootDir": "./",
     "module": "commonjs",
-    "types": ["node"]
+    "types": ["node"],
+    "esModuleInterop": true
   },
   "include": ["src/**/*.ts"]
 }
diff --git a/tools/jsdoc-annotation-transformer/tsconfig.spec.json b/tools/jsdoc-annotation-transformer/tsconfig.spec.json
new file mode 100644
index 000000000..827403667
--- /dev/null
+++ b/tools/jsdoc-annotation-transformer/tsconfig.spec.json
@@ -0,0 +1,29 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "types": [
+      "vitest/globals",
+      "vitest/importMeta",
+      "vite/client",
+      "node",
+      "vitest"
+    ]
+  },
+  "include": [
+    "vite.config.ts",
+    "vite.config.mts",
+    "vitest.config.ts",
+    "vitest.config.mts",
+    "vitest.unit.config.ts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.ts",
+    "src/**/*.test.tsx",
+    "src/**/*.spec.tsx",
+    "src/**/*.test.js",
+    "src/**/*.spec.js",
+    "src/**/*.test.jsx",
+    "src/**/*.spec.jsx",
+    "src/**/*.d.ts"
+  ]
+}
diff --git a/tools/jsdoc-annotation-transformer/vitest.unit.config.ts b/tools/jsdoc-annotation-transformer/vitest.unit.config.ts
new file mode 100644
index 000000000..0c1d15939
--- /dev/null
+++ b/tools/jsdoc-annotation-transformer/vitest.unit.config.ts
@@ -0,0 +1,3 @@
+import { createUnitTestConfig } from '../../testing/test-setup-config/src/index.js';
+
+export default createUnitTestConfig('jsdoc-annotation-transformer');

From 594f45129ac178611ea0de1a14ac7f1676ea4d44 Mon Sep 17 00:00:00 2001
From: John Doe <john.doe@example.com>
Date: Tue, 2 Dec 2025 22:59:33 +0100
Subject: [PATCH 02/24] refactor: add zod2md-nx-plugin

---
 nx.json                                  |  1 +
 packages/models/project.json             | 13 -------
 tools/zod2md-nx-plugin/README.md         | 40 ++++++++++++++++++++
 tools/zod2md-nx-plugin/eslint.config.js  | 21 +++++++++++
 tools/zod2md-nx-plugin/package.json      | 30 +++++++++++++++
 tools/zod2md-nx-plugin/project.json      | 10 +++++
 tools/zod2md-nx-plugin/src/lib/plugin.js | 48 ++++++++++++++++++++++++
 tsconfig.base.json                       |  3 +-
 8 files changed, 152 insertions(+), 14 deletions(-)
 create mode 100644 tools/zod2md-nx-plugin/README.md
 create mode 100644 tools/zod2md-nx-plugin/eslint.config.js
 create mode 100644 tools/zod2md-nx-plugin/package.json
 create mode 100644 tools/zod2md-nx-plugin/project.json
 create mode 100644 tools/zod2md-nx-plugin/src/lib/plugin.js

diff --git a/nx.json b/nx.json
index 648165e0f..1a562452b 100644
--- a/nx.json
+++ b/nx.json
@@ -337,6 +337,7 @@
     "releaseTagPattern": "v{version}"
   },
   "plugins": [
+    "./tools/zod2md-nx-plugin/src/lib/plugin.js",
     {
       "plugin": "@push-based/nx-verdaccio",
       "options": {
diff --git a/packages/models/project.json b/packages/models/project.json
index d76e0034f..ae716fb18 100644
--- a/packages/models/project.json
+++ b/packages/models/project.json
@@ -4,19 +4,6 @@
   "sourceRoot": "packages/models/src",
   "projectType": "library",
   "targets": {
-    "generate-docs": {
-      "executor": "nx:run-commands",
-      "options": {
-        "commands": [
-          "zod2md --config {projectRoot}/zod2md.config.ts",
-          "prettier --write {projectRoot}/docs/models-reference.md"
-        ],
-        "parallel": false
-      },
-      "cache": true,
-      "inputs": ["production", "^production", "{projectRoot}/zod2md.config.ts"],
-      "outputs": ["{projectRoot}/docs/models-reference.md"]
-    },
     "build": {
       "dependsOn": [
         "^build",
diff --git a/tools/zod2md-nx-plugin/README.md b/tools/zod2md-nx-plugin/README.md
new file mode 100644
index 000000000..dc8a8145b
--- /dev/null
+++ b/tools/zod2md-nx-plugin/README.md
@@ -0,0 +1,40 @@
+# @code-pushup/zod2md-nx-plugin
+
+[![npm](https://img.shields.io/npm/v/%40code-pushup%2Futils.svg)](https://www.npmjs.com/package/@code-pushup/zod2md-nx-plugin)
+[![downloads](https://img.shields.io/npm/dm/%40code-pushup%2Futils)](https://npmtrends.com/@code-pushup/zod2md-nx-plugin)
+[![dependencies](https://img.shields.io/librariesio/release/npm/%40code-pushup/utils)](https://www.npmjs.com/package/@code-pushup/zod2md-nx-plugin?activeTab=dependencies)
+
+Low-level **utilities** (helper functions, etc.) used by [Code PushUp CLI](../cli/README.md).
+
+## Setup
+
+If you've already installed another `@code-pushup/*` package, then you may have already installed `@code-pushup/zod2md-nx-plugin` indirectly.
+
+If not, you can always install it separately:
+
+```sh
+npm install --save-dev @code-pushup/zod2md-nx-plugin
+```
+
+```sh
+yarn add --dev @code-pushup/zod2md-nx-plugin
+```
+
+```sh
+pnpm add --save-dev @code-pushup/zod2md-nx-plugin
+```
+
+## Usage
+
+```ts
+import { executeProcess, readJsonFile, slugify } from '@code-pushup/zod2md-nx-plugin';
+
+await executeProcess({
+  command: 'npx',
+  args: ['eslint', '--format=json', '--output-file=output.json', '**/*.js'],
+});
+
+const data = await readJsonFile('output.json');
+
+const slug = slugify('Hello, world!'); // "hello-world"
+```
diff --git a/tools/zod2md-nx-plugin/eslint.config.js b/tools/zod2md-nx-plugin/eslint.config.js
new file mode 100644
index 000000000..fb044aa16
--- /dev/null
+++ b/tools/zod2md-nx-plugin/eslint.config.js
@@ -0,0 +1,21 @@
+import tseslint from 'typescript-eslint';
+import baseConfig from '../../eslint.config.js';
+
+export default tseslint.config(
+  ...baseConfig,
+  {
+    files: ['**/*.ts'],
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+  },
+  {
+    files: ['**/*.json'],
+    rules: {
+      '@nx/dependency-checks': ['error', { ignoredDependencies: [] }],
+    },
+  },
+);
diff --git a/tools/zod2md-nx-plugin/package.json b/tools/zod2md-nx-plugin/package.json
new file mode 100644
index 000000000..81e3c16ba
--- /dev/null
+++ b/tools/zod2md-nx-plugin/package.json
@@ -0,0 +1,30 @@
+{
+  "name": "@code-pushup/zod2md-nx-plugin",
+  "version": "0.0.0",
+  "license": "MIT",
+  "homepage": "https://github.com/code-pushup/cli/tree/main/tools/zod2md-nx-plugin#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=17.0.0"
+  },
+  "dependencies": {
+    "@code-pushup/models": "0.92.0",
+    "ansis": "^3.3.0",
+    "build-md": "^0.4.2",
+    "bundle-require": "^5.1.0",
+    "esbuild": "^0.25.2",
+    "ora": "^9.0.0",
+    "semver": "^7.6.0",
+    "simple-git": "^3.20.0",
+    "string-width": "^8.1.0",
+    "wrap-ansi": "^9.0.2",
+    "zod": "^4.0.5"
+  },
+  "files": [
+    "src",
+    "!**/*.tsbuildinfo"
+  ]
+}
diff --git a/tools/zod2md-nx-plugin/project.json b/tools/zod2md-nx-plugin/project.json
new file mode 100644
index 000000000..7841ae50c
--- /dev/null
+++ b/tools/zod2md-nx-plugin/project.json
@@ -0,0 +1,10 @@
+{
+  "name": "zod2md-nx-plugin",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "tools/zod2md-nx-plugin/src",
+  "projectType": "library",
+  "targets": {
+    "lint": {}
+  },
+  "tags": ["scope:shared", "type:util", "publishable"]
+}
diff --git a/tools/zod2md-nx-plugin/src/lib/plugin.js b/tools/zod2md-nx-plugin/src/lib/plugin.js
new file mode 100644
index 000000000..4ad425fe4
--- /dev/null
+++ b/tools/zod2md-nx-plugin/src/lib/plugin.js
@@ -0,0 +1,48 @@
+import { dirname } from 'node:path';
+
+export const createNodesV2 = [
+  `**/zod2md.config.ts`,
+  async (zod2MdConfigurationFiles, createNodesOptions, context) => {
+    return Promise.all(
+      zod2MdConfigurationFiles.map(async zod2MdConfigurationFile => {
+        const projectRoot = dirname(zod2MdConfigurationFile);
+        const normalizedProjectRoot = projectRoot === '.' ? '' : projectRoot;
+        const result = {
+          projects: {
+            [normalizedProjectRoot]: {
+              targets: {
+                'generate-docs': {
+                  executor: 'nx:run-commands',
+                  options: {
+                    commands: [
+                      'zod2md --config {projectRoot}/zod2md.config.ts',
+                      'prettier --write {projectRoot}/docs/{projectName}-reference.md',
+                    ],
+                    parallel: false,
+                  },
+                  cache: true,
+                  inputs: [
+                    'production',
+                    '^production',
+                    '{projectRoot}/zod2md.config.ts',
+                  ],
+                  outputs: ['{projectRoot}/docs/{projectName}-reference.md'],
+                },
+              },
+            },
+          },
+        };
+
+        return [zod2MdConfigurationFile, result];
+      }),
+    );
+  },
+];
+
+// default export for nx.json#plugins
+const plugin = {
+  name: 'zod2md-nx-plugin',
+  createNodesV2,
+};
+
+export default plugin;
diff --git a/tsconfig.base.json b/tsconfig.base.json
index ac98b47ed..d5991b570 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -47,7 +47,8 @@
       "@code-pushup/typescript-plugin": [
         "packages/plugin-typescript/src/index.ts"
       ],
-      "@code-pushup/utils": ["packages/utils/src/index.ts"]
+      "@code-pushup/utils": ["packages/utils/src/index.ts"],
+      "@code-pushup/zod2md-nx-plugin": ["tools/zod2md-nx-plugin/src/index.ts"]
     }
   },
   "exclude": ["node_modules", "tmp"]

From 00256ee630b88f63b0e4c62af5eceaf8868cf20a Mon Sep 17 00:00:00 2001
From: John Doe <john.doe@example.com>
Date: Tue, 2 Dec 2025 23:13:20 +0100
Subject: [PATCH 03/24] refactor: wip

---
 tools/jsdoc-annotation-transformer/README.md    | 4 ++--
 tools/jsdoc-annotation-transformer/project.json | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/tools/jsdoc-annotation-transformer/README.md b/tools/jsdoc-annotation-transformer/README.md
index 033289349..b857dbae6 100644
--- a/tools/jsdoc-annotation-transformer/README.md
+++ b/tools/jsdoc-annotation-transformer/README.md
@@ -12,7 +12,7 @@ The transformer hooks into the TypeScript compilation process using `ts-patch` a
 
 - The type name
 - A description explaining the type is derived from a Zod schema
-- A link to the models reference documentation
+- A link to the type reference documentation
 
 ## Example
 
@@ -51,7 +51,7 @@ export type Report = {
   "compilerOptions": {
     "plugins": [
       {
-        "transform": "./packages/models/transformers/dist",
+        "transform": "./path/to/transformer/dist",
         "afterDeclarations": true
       }
     ]
diff --git a/tools/jsdoc-annotation-transformer/project.json b/tools/jsdoc-annotation-transformer/project.json
index bcdbbeb48..08705b324 100644
--- a/tools/jsdoc-annotation-transformer/project.json
+++ b/tools/jsdoc-annotation-transformer/project.json
@@ -1,6 +1,6 @@
 {
   "name": "jsdoc-annotation-transformer",
-  "$schema": "../../../node_modules/nx/schemas/project-schema.json",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
   "sourceRoot": "tools/jsdoc-annotation-transformer/src",
   "projectType": "library",
   "targets": {

From 9112bf0157615e7fa61202e1d913454fe835597d Mon Sep 17 00:00:00 2001
From: John Doe <john.doe@example.com>
Date: Wed, 3 Dec 2025 00:04:23 +0100
Subject: [PATCH 04/24] refactor: adjust plugin code

---
 tools/zod2md-nx-plugin/README.md         | 106 ++++++++++++++++++-----
 tools/zod2md-nx-plugin/package.json      |  15 +---
 tools/zod2md-nx-plugin/src/lib/plugin.js |  13 ++-
 3 files changed, 93 insertions(+), 41 deletions(-)

diff --git a/tools/zod2md-nx-plugin/README.md b/tools/zod2md-nx-plugin/README.md
index dc8a8145b..998512994 100644
--- a/tools/zod2md-nx-plugin/README.md
+++ b/tools/zod2md-nx-plugin/README.md
@@ -1,40 +1,100 @@
 # @code-pushup/zod2md-nx-plugin
 
-[![npm](https://img.shields.io/npm/v/%40code-pushup%2Futils.svg)](https://www.npmjs.com/package/@code-pushup/zod2md-nx-plugin)
-[![downloads](https://img.shields.io/npm/dm/%40code-pushup%2Futils)](https://npmtrends.com/@code-pushup/zod2md-nx-plugin)
-[![dependencies](https://img.shields.io/librariesio/release/npm/%40code-pushup/utils)](https://www.npmjs.com/package/@code-pushup/zod2md-nx-plugin?activeTab=dependencies)
+The Nx Plugin for [zod2md](https://github.com/code-pushup/zod2md), a tool for generating documentation from Zod schemas.
 
-Low-level **utilities** (helper functions, etc.) used by [Code PushUp CLI](../cli/README.md).
+Why should you use this plugin?
 
-## Setup
+- Zero setup cost. Just add a `zod2md.config.ts` file and you're good to go.
+- Automatic target generation
+- Minimal configuration
+- Automated caching and dependency tracking
 
-If you've already installed another `@code-pushup/*` package, then you may have already installed `@code-pushup/zod2md-nx-plugin` indirectly.
-
-If not, you can always install it separately:
+## Usage
 
-```sh
-npm install --save-dev @code-pushup/zod2md-nx-plugin
+```jsonc
+// nx.json
+{
+  //...
+  "plugins": ["./tools/zod2md-nx-plugin/src/lib/plugin.js"],
+}
 ```
 
-```sh
-yarn add --dev @code-pushup/zod2md-nx-plugin
+or with options:
+
+```jsonc
+// nx.json
+{
+  //...
+  "plugins": [
+    {
+      "plugin": "./tools/zod2md-nx-plugin/src/lib/plugin.js",
+      "options": {
+        "targetName": "docs",
+      },
+    },
+  ],
+}
 ```
 
-```sh
-pnpm add --save-dev @code-pushup/zod2md-nx-plugin
+Now every project with a `zod2md.config.ts` file will have a `generate-docs` target automatically created.
+
+- `nx run <project-name>:generate-docs`
+
+Run it and the project will automatically generate documentation from your Zod schemas.
+
+```text
+Root/
+├── project-name/
+│   ├── zod2md.config.ts
+│   ├── docs/
+│   │   └── project-name-reference.md 👈 generated
+│   └── ...
+└── ...
 ```
 
-## Usage
+The generated target:
 
-```ts
-import { executeProcess, readJsonFile, slugify } from '@code-pushup/zod2md-nx-plugin';
+1. Runs `zod2md` with the project's configuration
+2. Formats the generated markdown with Prettier
+3. Caches the result for better performance
 
-await executeProcess({
-  command: 'npx',
-  args: ['eslint', '--format=json', '--output-file=output.json', '**/*.js'],
-});
+## Options
 
-const data = await readJsonFile('output.json');
+| Name           | type                               | description                                            |
+| -------------- | ---------------------------------- | ------------------------------------------------------ |
+| **targetName** | `string` (DEFAULT 'generate-docs') | The id used to identify a target in your project.json. |
 
-const slug = slugify('Hello, world!'); // "hello-world"
+All options are optional and provided in the `nx.json` file.
+
+```jsonc
+// nx.json
+{
+  //...
+  "plugins": [
+    {
+      "plugin": "./tools/zod2md-nx-plugin/src/lib/plugin.js",
+      "options": {
+        "targetName": "docs",
+      },
+    },
+  ],
+}
+```
+
+## Configuration
+
+Create a `zod2md.config.ts` file in your project:
+
+```ts
+import type { Config } from 'zod2md';
+
+export default {
+  entry: 'packages/models/src/index.ts',
+  tsconfig: 'packages/models/tsconfig.lib.json',
+  format: 'esm',
+  title: 'Models reference',
+  output: 'packages/models/docs/models-reference.md',
+} satisfies Config;
 ```
+
+For a full list of configuration options visit the [zod2md documentation](https://github.com/code-pushup/zod2md#readme).
diff --git a/tools/zod2md-nx-plugin/package.json b/tools/zod2md-nx-plugin/package.json
index 81e3c16ba..ebcfdaf59 100644
--- a/tools/zod2md-nx-plugin/package.json
+++ b/tools/zod2md-nx-plugin/package.json
@@ -2,7 +2,6 @@
   "name": "@code-pushup/zod2md-nx-plugin",
   "version": "0.0.0",
   "license": "MIT",
-  "homepage": "https://github.com/code-pushup/cli/tree/main/tools/zod2md-nx-plugin#readme",
   "publishConfig": {
     "access": "public"
   },
@@ -10,19 +9,7 @@
   "engines": {
     "node": ">=17.0.0"
   },
-  "dependencies": {
-    "@code-pushup/models": "0.92.0",
-    "ansis": "^3.3.0",
-    "build-md": "^0.4.2",
-    "bundle-require": "^5.1.0",
-    "esbuild": "^0.25.2",
-    "ora": "^9.0.0",
-    "semver": "^7.6.0",
-    "simple-git": "^3.20.0",
-    "string-width": "^8.1.0",
-    "wrap-ansi": "^9.0.2",
-    "zod": "^4.0.5"
-  },
+  "dependencies": {},
   "files": [
     "src",
     "!**/*.tsbuildinfo"
diff --git a/tools/zod2md-nx-plugin/src/lib/plugin.js b/tools/zod2md-nx-plugin/src/lib/plugin.js
index 4ad425fe4..01db44686 100644
--- a/tools/zod2md-nx-plugin/src/lib/plugin.js
+++ b/tools/zod2md-nx-plugin/src/lib/plugin.js
@@ -3,6 +3,9 @@ import { dirname } from 'node:path';
 export const createNodesV2 = [
   `**/zod2md.config.ts`,
   async (zod2MdConfigurationFiles, createNodesOptions, context) => {
+    const options = createNodesOptions ?? {};
+    const targetName = options.targetName ?? 'generate-docs';
+
     return Promise.all(
       zod2MdConfigurationFiles.map(async zod2MdConfigurationFile => {
         const projectRoot = dirname(zod2MdConfigurationFile);
@@ -11,14 +14,16 @@ export const createNodesV2 = [
           projects: {
             [normalizedProjectRoot]: {
               targets: {
-                'generate-docs': {
+                [targetName]: {
                   executor: 'nx:run-commands',
                   options: {
                     commands: [
-                      'zod2md --config {projectRoot}/zod2md.config.ts',
-                      'prettier --write {projectRoot}/docs/{projectName}-reference.md',
+                      'zod2md --config {args.config} --output {args.output}',
+                      'prettier --write {args.output}',
                     ],
                     parallel: false,
+                    config: '{projectRoot}/zod2md.config.ts',
+                    output: '{projectRoot}/docs/{projectName}-reference.md',
                   },
                   cache: true,
                   inputs: [
@@ -26,7 +31,7 @@ export const createNodesV2 = [
                     '^production',
                     '{projectRoot}/zod2md.config.ts',
                   ],
-                  outputs: ['{projectRoot}/docs/{projectName}-reference.md'],
+                  outputs: ['{projectRoot}/docs/{outputFile}'],
                 },
               },
             },

From c7882cb6571f3e1c0920c72cf63b223178b5f308 Mon Sep 17 00:00:00 2001
From: John Doe <john.doe@example.com>
Date: Wed, 3 Dec 2025 00:13:56 +0100
Subject: [PATCH 05/24] refactor: wip

---
 packages/models/project.json                  |  2 +-
 .../models/transformers}/eslint.config.cjs    |  2 +-
 .../models/transformers}/package.json         |  2 +-
 packages/models/transformers/project.json     | 23 +++++++
 .../models/transformers}/src/index.ts         |  0
 .../transformers}/src/lib/transformers.ts     |  0
 .../models/transformers}/tsconfig.json        |  2 +-
 .../models/transformers}/tsconfig.lib.json    |  3 +-
 packages/models/tsconfig.lib.json             |  8 ++-
 tools/jsdoc-annotation-transformer/README.md  | 69 -------------------
 .../jsdoc-annotation-transformer/project.json | 23 -------
 .../tsconfig.spec.json                        | 29 --------
 .../vitest.unit.config.ts                     |  3 -
 tsconfig.base.json                            |  3 +-
 14 files changed, 36 insertions(+), 133 deletions(-)
 rename {tools/jsdoc-annotation-transformer => packages/models/transformers}/eslint.config.cjs (67%)
 rename {tools/jsdoc-annotation-transformer => packages/models/transformers}/package.json (82%)
 create mode 100644 packages/models/transformers/project.json
 rename {tools/jsdoc-annotation-transformer => packages/models/transformers}/src/index.ts (100%)
 rename {tools/jsdoc-annotation-transformer => packages/models/transformers}/src/lib/transformers.ts (100%)
 rename {tools/jsdoc-annotation-transformer => packages/models/transformers}/tsconfig.json (81%)
 rename {tools/jsdoc-annotation-transformer => packages/models/transformers}/tsconfig.lib.json (76%)
 delete mode 100644 tools/jsdoc-annotation-transformer/README.md
 delete mode 100644 tools/jsdoc-annotation-transformer/project.json
 delete mode 100644 tools/jsdoc-annotation-transformer/tsconfig.spec.json
 delete mode 100644 tools/jsdoc-annotation-transformer/vitest.unit.config.ts

diff --git a/packages/models/project.json b/packages/models/project.json
index ae716fb18..0da8b6fcf 100644
--- a/packages/models/project.json
+++ b/packages/models/project.json
@@ -8,7 +8,7 @@
       "dependsOn": [
         "^build",
         "generate-docs",
-        { "projects": "jsdocs-annotation-transformer", "target": "build" }
+        { "projects": "models-transformers", "target": "build" }
       ]
     },
     "lint": {},
diff --git a/tools/jsdoc-annotation-transformer/eslint.config.cjs b/packages/models/transformers/eslint.config.cjs
similarity index 67%
rename from tools/jsdoc-annotation-transformer/eslint.config.cjs
rename to packages/models/transformers/eslint.config.cjs
index 467b6c94b..4eaecdb17 100644
--- a/tools/jsdoc-annotation-transformer/eslint.config.cjs
+++ b/packages/models/transformers/eslint.config.cjs
@@ -1,4 +1,4 @@
-const baseConfig = require('../../eslint.config.js').default;
+const baseConfig = require('../../../eslint.config.js').default;
 
 module.exports = [
   ...baseConfig,
diff --git a/tools/jsdoc-annotation-transformer/package.json b/packages/models/transformers/package.json
similarity index 82%
rename from tools/jsdoc-annotation-transformer/package.json
rename to packages/models/transformers/package.json
index 273fd5821..e5d33d01b 100644
--- a/tools/jsdoc-annotation-transformer/package.json
+++ b/packages/models/transformers/package.json
@@ -1,5 +1,5 @@
 {
-  "name": "@code-pushup/jsdocs-annotation-transformer",
+  "name": "@code-pushup/models-transformers",
   "version": "0.0.0",
   "description": "TypeScript transformers enhancing models with JSDoc and schema metadata",
   "type": "commonjs",
diff --git a/packages/models/transformers/project.json b/packages/models/transformers/project.json
new file mode 100644
index 000000000..9b3ed9b10
--- /dev/null
+++ b/packages/models/transformers/project.json
@@ -0,0 +1,23 @@
+{
+  "name": "models-transformers",
+  "$schema": "../../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "packages/models/transformers/src",
+  "projectType": "library",
+  "targets": {
+    "build": {
+      "executor": "@nx/js:tsc",
+      "outputs": ["{options.outputPath}"],
+      "dependsOn": ["pre-build"],
+      "options": {
+        "outputPath": "packages/models/transformers/dist",
+        "main": "packages/models/transformers/src/index.ts",
+        "tsConfig": "packages/models/transformers/tsconfig.lib.json"
+      }
+    },
+    "pre-build": {
+      "command": "ts-patch install",
+      "cache": true,
+      "inputs": ["sharedGlobals", { "runtime": "ts-patch check" }]
+    }
+  }
+}
diff --git a/tools/jsdoc-annotation-transformer/src/index.ts b/packages/models/transformers/src/index.ts
similarity index 100%
rename from tools/jsdoc-annotation-transformer/src/index.ts
rename to packages/models/transformers/src/index.ts
diff --git a/tools/jsdoc-annotation-transformer/src/lib/transformers.ts b/packages/models/transformers/src/lib/transformers.ts
similarity index 100%
rename from tools/jsdoc-annotation-transformer/src/lib/transformers.ts
rename to packages/models/transformers/src/lib/transformers.ts
diff --git a/tools/jsdoc-annotation-transformer/tsconfig.json b/packages/models/transformers/tsconfig.json
similarity index 81%
rename from tools/jsdoc-annotation-transformer/tsconfig.json
rename to packages/models/transformers/tsconfig.json
index 0c1036efe..fe17bec70 100644
--- a/tools/jsdoc-annotation-transformer/tsconfig.json
+++ b/packages/models/transformers/tsconfig.json
@@ -1,5 +1,5 @@
 {
-  "extends": "../../tsconfig.base.json",
+  "extends": "../../../tsconfig.base.json",
   "compilerOptions": {
     "module": "commonjs",
     "verbatimModuleSyntax": false
diff --git a/tools/jsdoc-annotation-transformer/tsconfig.lib.json b/packages/models/transformers/tsconfig.lib.json
similarity index 76%
rename from tools/jsdoc-annotation-transformer/tsconfig.lib.json
rename to packages/models/transformers/tsconfig.lib.json
index bebaef047..48174f134 100644
--- a/tools/jsdoc-annotation-transformer/tsconfig.lib.json
+++ b/packages/models/transformers/tsconfig.lib.json
@@ -4,8 +4,7 @@
     "outDir": "./dist",
     "rootDir": "./",
     "module": "commonjs",
-    "types": ["node"],
-    "esModuleInterop": true
+    "types": ["node"]
   },
   "include": ["src/**/*.ts"]
 }
diff --git a/packages/models/tsconfig.lib.json b/packages/models/tsconfig.lib.json
index 23ebd7dba..2c92983e0 100644
--- a/packages/models/tsconfig.lib.json
+++ b/packages/models/tsconfig.lib.json
@@ -3,7 +3,13 @@
   "compilerOptions": {
     "outDir": "../../dist/out-tsc",
     "declaration": true,
-    "types": ["node"]
+    "types": ["node"],
+    "plugins": [
+      {
+        "transform": "./packages/models/transformers/dist",
+        "afterDeclarations": true
+      }
+    ]
   },
   "include": ["src/**/*.ts"],
   "exclude": [
diff --git a/tools/jsdoc-annotation-transformer/README.md b/tools/jsdoc-annotation-transformer/README.md
deleted file mode 100644
index b857dbae6..000000000
--- a/tools/jsdoc-annotation-transformer/README.md
+++ /dev/null
@@ -1,69 +0,0 @@
-# @code-pushup/jsdocs-annotation-transformer
-
-TypeScript transformer plugin that automatically enhances type definitions with JSDoc comments and schema metadata.
-
-## Purpose
-
-This package provides a TypeScript compiler transformer that automatically adds JSDoc documentation to type aliases and interfaces during compilation. It's designed to improve developer experience by injecting helpful metadata and documentation links directly into generated type definitions.
-
-## How It Works
-
-The transformer hooks into the TypeScript compilation process using `ts-patch` and automatically adds JSDoc comments above type definitions. Each comment includes:
-
-- The type name
-- A description explaining the type is derived from a Zod schema
-- A link to the type reference documentation
-
-## Example
-
-Given a type definition like:
-
-```typescript
-export type Report = {
-  // ... type properties
-};
-```
-
-The transformer automatically generates:
-
-```typescript
-/**
- * Type Definition: `Report`
- *
- * This type is derived from a Zod schema and represents
- * the validated structure of `Report` used within the application.
- *
- * @see {@link https://github.com/code-pushup/cli/blob/main/packages/models/docs/models-reference.md#report}
- */
-export type Report = {
-  // ... type properties
-};
-```
-
-## Usage
-
-1. ts-patch install
-
-2. Add the transformer to your `tsconfig.json`:
-
-```json
-{
-  "compilerOptions": {
-    "plugins": [
-      {
-        "transform": "./path/to/transformer/dist",
-        "afterDeclarations": true
-      }
-    ]
-  }
-}
-```
-
-3. Build your TypeScript project. The transformer will run automatically and add JSDoc comments to your type definitions.
-
-### Options
-
-| Option              | Type      | Required | Description                                                                                                                                                         |
-| ------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `transform`         | `string`  | Yes      | Path to the transformer module                                                                                                                                      |
-| `afterDeclarations` | `boolean` | No       | Set to `true` to run the transformer after TypeScript generates declaration files (`.d.ts`). This ensures JSDoc comments are added to the emitted type definitions. |
diff --git a/tools/jsdoc-annotation-transformer/project.json b/tools/jsdoc-annotation-transformer/project.json
deleted file mode 100644
index 08705b324..000000000
--- a/tools/jsdoc-annotation-transformer/project.json
+++ /dev/null
@@ -1,23 +0,0 @@
-{
-  "name": "jsdoc-annotation-transformer",
-  "$schema": "../../node_modules/nx/schemas/project-schema.json",
-  "sourceRoot": "tools/jsdoc-annotation-transformer/src",
-  "projectType": "library",
-  "targets": {
-    "build": {
-      "executor": "@nx/js:tsc",
-      "outputs": ["{options.outputPath}"],
-      "dependsOn": ["pre-build"],
-      "options": {
-        "outputPath": "tools/jsdoc-annotation-transformer/dist",
-        "main": "tools/jsdoc-annotation-transformer/src/index.ts",
-        "tsConfig": "tools/jsdoc-annotation-transformer/tsconfig.lib.json"
-      }
-    },
-    "pre-build": {
-      "command": "ts-patch install",
-      "cache": true,
-      "inputs": ["sharedGlobals", { "runtime": "ts-patch check" }]
-    }
-  }
-}
diff --git a/tools/jsdoc-annotation-transformer/tsconfig.spec.json b/tools/jsdoc-annotation-transformer/tsconfig.spec.json
deleted file mode 100644
index 827403667..000000000
--- a/tools/jsdoc-annotation-transformer/tsconfig.spec.json
+++ /dev/null
@@ -1,29 +0,0 @@
-{
-  "extends": "./tsconfig.json",
-  "compilerOptions": {
-    "outDir": "../../dist/out-tsc",
-    "types": [
-      "vitest/globals",
-      "vitest/importMeta",
-      "vite/client",
-      "node",
-      "vitest"
-    ]
-  },
-  "include": [
-    "vite.config.ts",
-    "vite.config.mts",
-    "vitest.config.ts",
-    "vitest.config.mts",
-    "vitest.unit.config.ts",
-    "src/**/*.test.ts",
-    "src/**/*.spec.ts",
-    "src/**/*.test.tsx",
-    "src/**/*.spec.tsx",
-    "src/**/*.test.js",
-    "src/**/*.spec.js",
-    "src/**/*.test.jsx",
-    "src/**/*.spec.jsx",
-    "src/**/*.d.ts"
-  ]
-}
diff --git a/tools/jsdoc-annotation-transformer/vitest.unit.config.ts b/tools/jsdoc-annotation-transformer/vitest.unit.config.ts
deleted file mode 100644
index 0c1d15939..000000000
--- a/tools/jsdoc-annotation-transformer/vitest.unit.config.ts
+++ /dev/null
@@ -1,3 +0,0 @@
-import { createUnitTestConfig } from '../../testing/test-setup-config/src/index.js';
-
-export default createUnitTestConfig('jsdoc-annotation-transformer');
diff --git a/tsconfig.base.json b/tsconfig.base.json
index d5991b570..ac98b47ed 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -47,8 +47,7 @@
       "@code-pushup/typescript-plugin": [
         "packages/plugin-typescript/src/index.ts"
       ],
-      "@code-pushup/utils": ["packages/utils/src/index.ts"],
-      "@code-pushup/zod2md-nx-plugin": ["tools/zod2md-nx-plugin/src/index.ts"]
+      "@code-pushup/utils": ["packages/utils/src/index.ts"]
     }
   },
   "exclude": ["node_modules", "tmp"]

From 1cf9a7ad720d68b83fbc2b00fdd619df1d7cd793 Mon Sep 17 00:00:00 2001
From: John Doe <john.doe@example.com>
Date: Wed, 3 Dec 2025 00:24:28 +0100
Subject: [PATCH 06/24] refactor: wip

---
 tools/zod2md-nx-plugin/README.md | 22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/tools/zod2md-nx-plugin/README.md b/tools/zod2md-nx-plugin/README.md
index 998512994..ae05d280d 100644
--- a/tools/zod2md-nx-plugin/README.md
+++ b/tools/zod2md-nx-plugin/README.md
@@ -29,7 +29,7 @@ or with options:
     {
       "plugin": "./tools/zod2md-nx-plugin/src/lib/plugin.js",
       "options": {
-        "targetName": "docs",
+        "targetName": "zod-docs",
       },
     },
   ],
@@ -58,6 +58,26 @@ The generated target:
 2. Formats the generated markdown with Prettier
 3. Caches the result for better performance
 
+### Options
+
+You can override the config and output paths when running the target:
+
+```bash
+# Use custom output file
+nx generate-docs my-project --output=docs/custom-api.md
+
+# Use custom config file
+nx generate-docs my-project --config=custom-zod2md.config.ts
+
+# Use both
+nx generate-docs my-project --config=custom.config.ts --output=docs/api.md
+```
+
+Default values:
+
+- `config`: `{projectRoot}/zod2md.config.ts`
+- `output`: `{projectRoot}/docs/{projectName}-reference.md`
+
 ## Options
 
 | Name           | type                               | description                                            |

From 12a12d5966fdeb71d7e52dca6378a297aed3e565 Mon Sep 17 00:00:00 2001
From: John Doe <john.doe@example.com>
Date: Wed, 3 Dec 2025 00:26:26 +0100
Subject: [PATCH 07/24] refactor: wip

---
 tools/zod2md-nx-plugin/project.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/zod2md-nx-plugin/project.json b/tools/zod2md-nx-plugin/project.json
index 7841ae50c..f97a9de50 100644
--- a/tools/zod2md-nx-plugin/project.json
+++ b/tools/zod2md-nx-plugin/project.json
@@ -6,5 +6,5 @@
   "targets": {
     "lint": {}
   },
-  "tags": ["scope:shared", "type:util", "publishable"]
+  "tags": ["scope:shared", "type:util"]
 }

From 4d629f4791692b26aff7df138acc9648e482db69 Mon Sep 17 00:00:00 2001
From: John Doe <john.doe@example.com>
Date: Wed, 3 Dec 2025 00:27:34 +0100
Subject: [PATCH 08/24] refactor: wip

---
 tools/zod2md-nx-plugin/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/zod2md-nx-plugin/README.md b/tools/zod2md-nx-plugin/README.md
index ae05d280d..135c0eb0d 100644
--- a/tools/zod2md-nx-plugin/README.md
+++ b/tools/zod2md-nx-plugin/README.md
@@ -58,7 +58,7 @@ The generated target:
 2. Formats the generated markdown with Prettier
 3. Caches the result for better performance
 
-### Options
+### Passing zod2md options
 
 You can override the config and output paths when running the target:
 

From fb004e10fa4aa2956f7955864e97cd8c7a37f000 Mon Sep 17 00:00:00 2001
From: John Doe <john.doe@example.com>
Date: Wed, 3 Dec 2025 00:28:18 +0100
Subject: [PATCH 09/24] refactor: wip

---
 tools/zod2md-nx-plugin/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/zod2md-nx-plugin/README.md b/tools/zod2md-nx-plugin/README.md
index 135c0eb0d..75d90ed22 100644
--- a/tools/zod2md-nx-plugin/README.md
+++ b/tools/zod2md-nx-plugin/README.md
@@ -117,4 +117,4 @@ export default {
 } satisfies Config;
 ```
 
-For a full list of configuration options visit the [zod2md documentation](https://github.com/code-pushup/zod2md#readme).
+For a full list of configuration options visit the [zod2md documentation](https://github.com/matejchalk/zod2md?tab=readme-ov-file#configuration).

From 8253323f2ee77fac3d3bf7277e306c1dfa6b3636 Mon Sep 17 00:00:00 2001
From: Michael Hladky <10064416+BioPhoton@users.noreply.github.com>
Date: Wed, 3 Dec 2025 16:20:50 +0100
Subject: [PATCH 10/24] Update tools/zod2md-nx-plugin/eslint.config.js
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Matěj Chalk <34691111+matejchalk@users.noreply.github.com>
---
 tools/zod2md-nx-plugin/eslint.config.js | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/tools/zod2md-nx-plugin/eslint.config.js b/tools/zod2md-nx-plugin/eslint.config.js
index fb044aa16..9094d2a29 100644
--- a/tools/zod2md-nx-plugin/eslint.config.js
+++ b/tools/zod2md-nx-plugin/eslint.config.js
@@ -12,10 +12,4 @@ export default tseslint.config(
       },
     },
   },
-  {
-    files: ['**/*.json'],
-    rules: {
-      '@nx/dependency-checks': ['error', { ignoredDependencies: [] }],
-    },
-  },
 );

From 670b2327c5041545518e8353cc986bef7f889c07 Mon Sep 17 00:00:00 2001
From: Michael Hladky <10064416+BioPhoton@users.noreply.github.com>
Date: Wed, 3 Dec 2025 16:21:10 +0100
Subject: [PATCH 11/24] Update tools/zod2md-nx-plugin/README.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Matěj Chalk <34691111+matejchalk@users.noreply.github.com>
---
 tools/zod2md-nx-plugin/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/zod2md-nx-plugin/README.md b/tools/zod2md-nx-plugin/README.md
index 75d90ed22..bb9cfa3c4 100644
--- a/tools/zod2md-nx-plugin/README.md
+++ b/tools/zod2md-nx-plugin/README.md
@@ -1,6 +1,6 @@
 # @code-pushup/zod2md-nx-plugin
 
-The Nx Plugin for [zod2md](https://github.com/code-pushup/zod2md), a tool for generating documentation from Zod schemas.
+The Nx Plugin for [zod2md](https://github.com/matejchalk/zod2md), a tool for generating documentation from Zod schemas.
 
 Why should you use this plugin?
 

From a4cf4b9f0e52289caa5af6ab245752b58ab3c098 Mon Sep 17 00:00:00 2001
From: Michael Hladky <john.doe@example.com>
Date: Wed, 3 Dec 2025 17:05:04 +0100
Subject: [PATCH 12/24] refactor: wip

---
 tools/zod2md-nx-plugin/package.json | 17 -----------------
 1 file changed, 17 deletions(-)
 delete mode 100644 tools/zod2md-nx-plugin/package.json

diff --git a/tools/zod2md-nx-plugin/package.json b/tools/zod2md-nx-plugin/package.json
deleted file mode 100644
index ebcfdaf59..000000000
--- a/tools/zod2md-nx-plugin/package.json
+++ /dev/null
@@ -1,17 +0,0 @@
-{
-  "name": "@code-pushup/zod2md-nx-plugin",
-  "version": "0.0.0",
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
-  "type": "module",
-  "engines": {
-    "node": ">=17.0.0"
-  },
-  "dependencies": {},
-  "files": [
-    "src",
-    "!**/*.tsbuildinfo"
-  ]
-}

From b02a6a0b93ebb9e0062a51cf14ad3c095ce60337 Mon Sep 17 00:00:00 2001
From: Michael Hladky <john.doe@example.com>
Date: Wed, 3 Dec 2025 17:13:36 +0100
Subject: [PATCH 13/24] refactor: wip

---
 tools/zod2md-nx-plugin/src/lib/plugin.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/zod2md-nx-plugin/src/lib/plugin.js b/tools/zod2md-nx-plugin/src/lib/plugin.js
index 01db44686..72463442d 100644
--- a/tools/zod2md-nx-plugin/src/lib/plugin.js
+++ b/tools/zod2md-nx-plugin/src/lib/plugin.js
@@ -31,7 +31,7 @@ export const createNodesV2 = [
                     '^production',
                     '{projectRoot}/zod2md.config.ts',
                   ],
-                  outputs: ['{projectRoot}/docs/{outputFile}'],
+                  outputs: ['{projectRoot}/docs/{projectName}-reference.md'],
                 },
               },
             },

From 4d6c335db0b4e88637ca1fdf339278caa12cbed0 Mon Sep 17 00:00:00 2001
From: Michael Hladky <john.doe@example.com>
Date: Wed, 3 Dec 2025 17:17:24 +0100
Subject: [PATCH 14/24] refactor: wip

---
 tools/zod2md-nx-plugin/eslint.config.js  | 17 +++++++----------
 tools/zod2md-nx-plugin/src/lib/plugin.js |  4 ++--
 2 files changed, 9 insertions(+), 12 deletions(-)

diff --git a/tools/zod2md-nx-plugin/eslint.config.js b/tools/zod2md-nx-plugin/eslint.config.js
index 9094d2a29..2656b27cb 100644
--- a/tools/zod2md-nx-plugin/eslint.config.js
+++ b/tools/zod2md-nx-plugin/eslint.config.js
@@ -1,15 +1,12 @@
 import tseslint from 'typescript-eslint';
 import baseConfig from '../../eslint.config.js';
 
-export default tseslint.config(
-  ...baseConfig,
-  {
-    files: ['**/*.ts'],
-    languageOptions: {
-      parserOptions: {
-        projectService: true,
-        tsconfigRootDir: import.meta.dirname,
-      },
+export default tseslint.config(...baseConfig, {
+  files: ['**/*.ts'],
+  languageOptions: {
+    parserOptions: {
+      projectService: true,
+      tsconfigRootDir: import.meta.dirname,
     },
   },
-);
+});
diff --git a/tools/zod2md-nx-plugin/src/lib/plugin.js b/tools/zod2md-nx-plugin/src/lib/plugin.js
index 72463442d..7185189ca 100644
--- a/tools/zod2md-nx-plugin/src/lib/plugin.js
+++ b/tools/zod2md-nx-plugin/src/lib/plugin.js
@@ -1,4 +1,4 @@
-import { dirname } from 'node:path';
+import path from 'node:path';
 
 export const createNodesV2 = [
   `**/zod2md.config.ts`,
@@ -8,7 +8,7 @@ export const createNodesV2 = [
 
     return Promise.all(
       zod2MdConfigurationFiles.map(async zod2MdConfigurationFile => {
-        const projectRoot = dirname(zod2MdConfigurationFile);
+        const projectRoot = path.dirname(zod2MdConfigurationFile);
         const normalizedProjectRoot = projectRoot === '.' ? '' : projectRoot;
         const result = {
           projects: {

From ce500c757ff11231cd30e70612f4f47fedc91d16 Mon Sep 17 00:00:00 2001
From: Michael Hladky <john.doe@example.com>
Date: Wed, 3 Dec 2025 17:19:14 +0100
Subject: [PATCH 15/24] refactor: wip

---
 tools/zod2md-nx-plugin/src/lib/plugin.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/zod2md-nx-plugin/src/lib/plugin.js b/tools/zod2md-nx-plugin/src/lib/plugin.js
index 7185189ca..30ff74429 100644
--- a/tools/zod2md-nx-plugin/src/lib/plugin.js
+++ b/tools/zod2md-nx-plugin/src/lib/plugin.js
@@ -2,7 +2,7 @@ import path from 'node:path';
 
 export const createNodesV2 = [
   `**/zod2md.config.ts`,
-  async (zod2MdConfigurationFiles, createNodesOptions, context) => {
+  async (zod2MdConfigurationFiles, createNodesOptions) => {
     const options = createNodesOptions ?? {};
     const targetName = options.targetName ?? 'generate-docs';
 

From 9068301396d50843a0f25b97b827bc1aae0cabb4 Mon Sep 17 00:00:00 2001
From: Michael Hladky <john.doe@example.com>
Date: Fri, 5 Dec 2025 13:50:30 +0100
Subject: [PATCH 16/24] refactor: wip

---
 nx.json                                       |  2 +-
 tools/zod2md-jsdocs/README.md                 | 64 ++++++-----------
 .../docs/zod2md-jsdocs-nx-plugin.md}          |  8 +--
 .../docs/zod2md-jsdocs-ts-transformer.md      | 71 +++++++++++++++++++
 .../src/nx-plugin.js}                         |  6 +-
 tools/zod2md-nx-plugin/eslint.config.js       | 12 ----
 tools/zod2md-nx-plugin/project.json           | 10 ---
 7 files changed, 99 insertions(+), 74 deletions(-)
 rename tools/{zod2md-nx-plugin/README.md => zod2md-jsdocs/docs/zod2md-jsdocs-nx-plugin.md} (91%)
 create mode 100644 tools/zod2md-jsdocs/docs/zod2md-jsdocs-ts-transformer.md
 rename tools/{zod2md-nx-plugin/src/lib/plugin.js => zod2md-jsdocs/src/nx-plugin.js} (95%)
 delete mode 100644 tools/zod2md-nx-plugin/eslint.config.js
 delete mode 100644 tools/zod2md-nx-plugin/project.json

diff --git a/nx.json b/nx.json
index 4182eb3f5..46fbaf88d 100644
--- a/nx.json
+++ b/nx.json
@@ -337,7 +337,7 @@
     "releaseTagPattern": "v{version}"
   },
   "plugins": [
-    "./tools/zod2md-nx-plugin/src/lib/plugin.js",
+    "./tools/zod2md-jsdocs/src/nx-plugin.js",
     {
       "plugin": "@push-based/nx-verdaccio",
       "options": {
diff --git a/tools/zod2md-jsdocs/README.md b/tools/zod2md-jsdocs/README.md
index c56a57a0b..d40a648a5 100644
--- a/tools/zod2md-jsdocs/README.md
+++ b/tools/zod2md-jsdocs/README.md
@@ -1,57 +1,41 @@
-# @code-pushup/zod2md-jsdocs
+# zod2md-jsdocs
 
-TypeScript transformer plugin that automatically enhances type definitions with JSDoc comments and schema metadata.
+A comprehensive toolset for generating and enhancing TypeScript documentation from Zod schemas. This package combines an Nx plugin for automated documentation generation with a TypeScript transformer that enriches type definitions with JSDoc comments.
 
-## Purpose
+## What's Included
 
-This package provides a TypeScript compiler transformer that automatically adds JSDoc documentation to type aliases and interfaces during compilation. It's designed to improve developer experience by injecting helpful metadata and documentation links directly into generated type definitions.
+This package provides two main components:
 
-## How It Works
+1. **[Nx Plugin](./docs/zod2md-jsdocs-nx-plugin.md)** - Automatically generates documentation targets for projects with Zod schemas
+2. **[TypeScript Transformer](./docs/zod2md-jsdocs-ts-transformer.md)** - Enhances generated type definitions with JSDoc comments and schema metadata
 
-The [TS transformer](https://github.com/itsdouges/typescript-transformer-handbook) hooks into the TypeScript compilation process using `ts-patch` and automatically adds JSDoc comments above type definitions. Each comment includes:
+## Quick Start
 
-- The type name
-- A description explaining the type is derived from a Zod schema
-- A link to the type reference documentation
+### Using the Nx Plugin
 
-## Example
+Add the plugin to your `nx.json`:
 
-Given a type definition like:
-
-```typescript
-export type Report = {
-  // ... type properties
-};
+```jsonc
+{
+  "plugins": ["./tools/zod2md-jsdocs/src/lib/plugin.js"],
+}
 ```
 
-The transformer automatically generates:
+Create a `zod2md.config.ts` in your project, and you'll automatically get a `generate-docs` target.
 
-```typescript
-/**
- * Type Definition: `Report`
- *
- * This type is derived from a Zod schema and represents
- * the validated structure of `Report` used within the application.
- *
- * @see {@link https://github.com/code-pushup/cli/blob/main/packages/models/docs/models-reference.md#report}
- */
-export type Report = {
-  // ... type properties
-};
-```
+[Learn more about the Nx Plugin →](./docs/zod2md-jsdocs-nx-plugin.md)
 
-## Usage
+### Using the TypeScript Transformer
 
-1. `ts-patch install`
-
-2. Add the transformer to your `tsconfig.json`:
+1. Install ts-patch: `ts-patch install`
+2. Add to your `tsconfig.json`:
 
 ```json
 {
   "compilerOptions": {
     "plugins": [
       {
-        "transform": "./path/to/transformer/dist",
+        "transform": "./tools/zod2md-jsdocs/dist/src",
         "afterDeclarations": true,
         "baseUrl": "https://example.com/docs/api-reference.md"
       }
@@ -60,12 +44,4 @@ export type Report = {
 }
 ```
 
-3. Build your TypeScript project. The transformer will run automatically and add JSDoc comments to your type definitions.
-
-### Options
-
-| Option              | Type      | Required | Description                                                                                                                                                         |
-| ------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `transform`         | `string`  | Yes      | Path to the transformer module                                                                                                                                      |
-| `afterDeclarations` | `boolean` | No       | Set to `true` to run the transformer after TypeScript generates declaration files (`.d.ts`). This ensures JSDoc comments are added to the emitted type definitions. |
-| `baseUrl`           | `string`  | Yes      | Base URL for documentation links (e.g., `https://example.com/docs/api-reference.md`)                                                                                |
+[Learn more about the TypeScript Transformer →](./docs/zod2md-jsdocs-ts-transformer.md)
diff --git a/tools/zod2md-nx-plugin/README.md b/tools/zod2md-jsdocs/docs/zod2md-jsdocs-nx-plugin.md
similarity index 91%
rename from tools/zod2md-nx-plugin/README.md
rename to tools/zod2md-jsdocs/docs/zod2md-jsdocs-nx-plugin.md
index bb9cfa3c4..f6430ab9a 100644
--- a/tools/zod2md-nx-plugin/README.md
+++ b/tools/zod2md-jsdocs/docs/zod2md-jsdocs-nx-plugin.md
@@ -1,4 +1,4 @@
-# @code-pushup/zod2md-nx-plugin
+# @code-pushup/zod2md-jsdocs-nx-plugin
 
 The Nx Plugin for [zod2md](https://github.com/matejchalk/zod2md), a tool for generating documentation from Zod schemas.
 
@@ -15,7 +15,7 @@ Why should you use this plugin?
 // nx.json
 {
   //...
-  "plugins": ["./tools/zod2md-nx-plugin/src/lib/plugin.js"],
+  "plugins": ["./tools/zod2md-jsdocs-nx-plugin/src/lib/plugin.js"],
 }
 ```
 
@@ -27,7 +27,7 @@ or with options:
   //...
   "plugins": [
     {
-      "plugin": "./tools/zod2md-nx-plugin/src/lib/plugin.js",
+      "plugin": "./tools/zod2md-jsdocs-nx-plugin/src/lib/plugin.js",
       "options": {
         "targetName": "zod-docs",
       },
@@ -92,7 +92,7 @@ All options are optional and provided in the `nx.json` file.
   //...
   "plugins": [
     {
-      "plugin": "./tools/zod2md-nx-plugin/src/lib/plugin.js",
+      "plugin": "./tools/zod2md-jsdocs-nx-plugin/src/lib/plugin.js",
       "options": {
         "targetName": "docs",
       },
diff --git a/tools/zod2md-jsdocs/docs/zod2md-jsdocs-ts-transformer.md b/tools/zod2md-jsdocs/docs/zod2md-jsdocs-ts-transformer.md
new file mode 100644
index 000000000..2bfcae90f
--- /dev/null
+++ b/tools/zod2md-jsdocs/docs/zod2md-jsdocs-ts-transformer.md
@@ -0,0 +1,71 @@
+# zod2md-jsdocs-ts-transformer
+
+TypeScript transformer plugin that automatically enhances type definitions with JSDoc comments and schema metadata.
+
+## Purpose
+
+This package provides a TypeScript compiler transformer that automatically adds JSDoc documentation to type aliases and interfaces during compilation. It's designed to improve developer experience by injecting helpful metadata and documentation links directly into generated type definitions.
+
+## How It Works
+
+The [TS transformer](https://github.com/itsdouges/typescript-transformer-handbook) hooks into the TypeScript compilation process using `ts-patch` and automatically adds JSDoc comments above type definitions. Each comment includes:
+
+- The type name
+- A description explaining the type is derived from a Zod schema
+- A link to the type reference documentation
+
+## Example
+
+Given a type definition like:
+
+```typescript
+export type Report = {
+  // ... type properties
+};
+```
+
+The transformer automatically generates:
+
+```typescript
+/**
+ * Type Definition: `Report`
+ *
+ * This type is derived from a Zod schema and represents
+ * the validated structure of `Report` used within the application.
+ *
+ * @see {@link https://github.com/code-pushup/cli/blob/main/packages/models/docs/models-reference.md#report}
+ */
+export type Report = {
+  // ... type properties
+};
+```
+
+## Usage
+
+1. `ts-patch install`
+
+2. Add the transformer to your `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "plugins": [
+      {
+        "transform": "./path/to/transformer/dist",
+        "afterDeclarations": true,
+        "baseUrl": "https://example.com/docs/api-reference.md"
+      }
+    ]
+  }
+}
+```
+
+3. Build your TypeScript project. The transformer will run automatically and add JSDoc comments to your type definitions.
+
+### Options
+
+| Option              | Type      | Required | Description                                                                                                                                                         |
+| ------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `transform`         | `string`  | Yes      | Path to the transformer module                                                                                                                                      |
+| `afterDeclarations` | `boolean` | No       | Set to `true` to run the transformer after TypeScript generates declaration files (`.d.ts`). This ensures JSDoc comments are added to the emitted type definitions. |
+| `baseUrl`           | `string`  | Yes      | Base URL for documentation links (e.g., `https://example.com/docs/api-reference.md`)                                                                                |
diff --git a/tools/zod2md-nx-plugin/src/lib/plugin.js b/tools/zod2md-jsdocs/src/nx-plugin.js
similarity index 95%
rename from tools/zod2md-nx-plugin/src/lib/plugin.js
rename to tools/zod2md-jsdocs/src/nx-plugin.js
index 30ff74429..280317857 100644
--- a/tools/zod2md-nx-plugin/src/lib/plugin.js
+++ b/tools/zod2md-jsdocs/src/nx-plugin.js
@@ -45,9 +45,9 @@ export const createNodesV2 = [
 ];
 
 // default export for nx.json#plugins
-const plugin = {
-  name: 'zod2md-nx-plugin',
+const nxPlugin = {
+  name: 'zod2md-jsdocs-nx-plugin',
   createNodesV2,
 };
 
-export default plugin;
+export default nxPlugin;
diff --git a/tools/zod2md-nx-plugin/eslint.config.js b/tools/zod2md-nx-plugin/eslint.config.js
deleted file mode 100644
index 2656b27cb..000000000
--- a/tools/zod2md-nx-plugin/eslint.config.js
+++ /dev/null
@@ -1,12 +0,0 @@
-import tseslint from 'typescript-eslint';
-import baseConfig from '../../eslint.config.js';
-
-export default tseslint.config(...baseConfig, {
-  files: ['**/*.ts'],
-  languageOptions: {
-    parserOptions: {
-      projectService: true,
-      tsconfigRootDir: import.meta.dirname,
-    },
-  },
-});
diff --git a/tools/zod2md-nx-plugin/project.json b/tools/zod2md-nx-plugin/project.json
deleted file mode 100644
index f97a9de50..000000000
--- a/tools/zod2md-nx-plugin/project.json
+++ /dev/null
@@ -1,10 +0,0 @@
-{
-  "name": "zod2md-nx-plugin",
-  "$schema": "../../node_modules/nx/schemas/project-schema.json",
-  "sourceRoot": "tools/zod2md-nx-plugin/src",
-  "projectType": "library",
-  "targets": {
-    "lint": {}
-  },
-  "tags": ["scope:shared", "type:util"]
-}

From c0385c470280446853a0aceba540be1d8b7e1def Mon Sep 17 00:00:00 2001
From: Michael Hladky <john.doe@example.com>
Date: Fri, 5 Dec 2025 15:02:57 +0100
Subject: [PATCH 17/24] refactor:  wip

---
 nx.json                                                 | 2 +-
 tools/zod2md-jsdocs/src/{nx-plugin.js => nx-plugin.cjs} | 7 ++++---
 2 files changed, 5 insertions(+), 4 deletions(-)
 rename tools/zod2md-jsdocs/src/{nx-plugin.js => nx-plugin.cjs} (92%)

diff --git a/nx.json b/nx.json
index 46fbaf88d..310a34180 100644
--- a/nx.json
+++ b/nx.json
@@ -337,7 +337,7 @@
     "releaseTagPattern": "v{version}"
   },
   "plugins": [
-    "./tools/zod2md-jsdocs/src/nx-plugin.js",
+    "./tools/zod2md-jsdocs/src/nx-plugin.cjs",
     {
       "plugin": "@push-based/nx-verdaccio",
       "options": {
diff --git a/tools/zod2md-jsdocs/src/nx-plugin.js b/tools/zod2md-jsdocs/src/nx-plugin.cjs
similarity index 92%
rename from tools/zod2md-jsdocs/src/nx-plugin.js
rename to tools/zod2md-jsdocs/src/nx-plugin.cjs
index 280317857..753957961 100644
--- a/tools/zod2md-jsdocs/src/nx-plugin.js
+++ b/tools/zod2md-jsdocs/src/nx-plugin.cjs
@@ -1,6 +1,6 @@
-import path from 'node:path';
+const path = require('node:path');
 
-export const createNodesV2 = [
+const createNodesV2 = [
   `**/zod2md.config.ts`,
   async (zod2MdConfigurationFiles, createNodesOptions) => {
     const options = createNodesOptions ?? {};
@@ -50,4 +50,5 @@ const nxPlugin = {
   createNodesV2,
 };
 
-export default nxPlugin;
+module.exports = nxPlugin;
+module.exports.createNodesV2 = createNodesV2;

From df9cdd29d48210326fcbd590da1f859f01467b88 Mon Sep 17 00:00:00 2001
From: Michael Hladky <john.doe@example.com>
Date: Fri, 5 Dec 2025 15:10:00 +0100
Subject: [PATCH 18/24] refactor:  wip

---
 tools/zod2md-jsdocs/src/nx-plugin.cjs | 20 +++++++++-----------
 1 file changed, 9 insertions(+), 11 deletions(-)

diff --git a/tools/zod2md-jsdocs/src/nx-plugin.cjs b/tools/zod2md-jsdocs/src/nx-plugin.cjs
index 753957961..6877856b9 100644
--- a/tools/zod2md-jsdocs/src/nx-plugin.cjs
+++ b/tools/zod2md-jsdocs/src/nx-plugin.cjs
@@ -1,7 +1,9 @@
 const path = require('node:path');
 
+const ZOD2MD_CONFIG_FILE = 'zod2md.config.ts';
+
 const createNodesV2 = [
-  `**/zod2md.config.ts`,
+  `**/${ZOD2MD_CONFIG_FILE}`,
   async (zod2MdConfigurationFiles, createNodesOptions) => {
     const options = createNodesOptions ?? {};
     const targetName = options.targetName ?? 'generate-docs';
@@ -10,6 +12,8 @@ const createNodesV2 = [
       zod2MdConfigurationFiles.map(async zod2MdConfigurationFile => {
         const projectRoot = path.dirname(zod2MdConfigurationFile);
         const normalizedProjectRoot = projectRoot === '.' ? '' : projectRoot;
+        const output = '{projectRoot}/docs/{projectName}-reference.md';
+        const config = `{projectRoot}/${ZOD2MD_CONFIG_FILE}`;
         const result = {
           projects: {
             [normalizedProjectRoot]: {
@@ -18,20 +22,14 @@ const createNodesV2 = [
                   executor: 'nx:run-commands',
                   options: {
                     commands: [
-                      'zod2md --config {args.config} --output {args.output}',
-                      'prettier --write {args.output}',
+                      `zod2md --config ${config} --output ${output}`,
+                      `prettier --write ${output}`,
                     ],
                     parallel: false,
-                    config: '{projectRoot}/zod2md.config.ts',
-                    output: '{projectRoot}/docs/{projectName}-reference.md',
                   },
                   cache: true,
-                  inputs: [
-                    'production',
-                    '^production',
-                    '{projectRoot}/zod2md.config.ts',
-                  ],
-                  outputs: ['{projectRoot}/docs/{projectName}-reference.md'],
+                  inputs: ['production', '^production', config],
+                  outputs: [output],
                 },
               },
             },

From 765ff26f89604e6cbb839e8a81cc35db58aecafd Mon Sep 17 00:00:00 2001
From: Michael Hladky <john.doe@example.com>
Date: Fri, 5 Dec 2025 15:26:34 +0100
Subject: [PATCH 19/24] refactor:  wip

---
 nx.json                                     |  2 +-
 packages/models/eslint.config.js            |  3 ---
 tools/zod2md-jsdocs/eslint.config.cjs       | 11 -----------
 tools/zod2md-jsdocs/eslint.config.js        | 22 +++++++++++++++++++++
 tools/zod2md-jsdocs/project.json            | 10 ++--------
 tools/zod2md-jsdocs/src/lib/transformers.ts |  5 ++---
 6 files changed, 27 insertions(+), 26 deletions(-)
 delete mode 100644 tools/zod2md-jsdocs/eslint.config.cjs
 create mode 100644 tools/zod2md-jsdocs/eslint.config.js

diff --git a/nx.json b/nx.json
index 310a34180..6b5087763 100644
--- a/nx.json
+++ b/nx.json
@@ -46,7 +46,7 @@
       "options": {
         "command": "eslint",
         "args": [
-          "'{projectRoot}/**/*.ts'",
+          "'{projectRoot}/**/*.{ts,cjs,mjs,js}'",
           "{projectRoot}/package.json",
           "--config={projectRoot}/eslint.config.js",
           "--max-warnings=0",
diff --git a/packages/models/eslint.config.js b/packages/models/eslint.config.js
index 26af011ea..48fd0b2be 100644
--- a/packages/models/eslint.config.js
+++ b/packages/models/eslint.config.js
@@ -18,7 +18,4 @@ export default tseslint.config(
       '@nx/dependency-checks': 'error',
     },
   },
-  {
-    ignores: ['packages/models/transformers/**/*.ts'],
-  },
 );
diff --git a/tools/zod2md-jsdocs/eslint.config.cjs b/tools/zod2md-jsdocs/eslint.config.cjs
deleted file mode 100644
index 467b6c94b..000000000
--- a/tools/zod2md-jsdocs/eslint.config.cjs
+++ /dev/null
@@ -1,11 +0,0 @@
-const baseConfig = require('../../eslint.config.js').default;
-
-module.exports = [
-  ...baseConfig,
-  {
-    files: ['**/*.json'],
-    rules: {
-      '@nx/dependency-checks': 'error',
-    },
-  },
-];
diff --git a/tools/zod2md-jsdocs/eslint.config.js b/tools/zod2md-jsdocs/eslint.config.js
new file mode 100644
index 000000000..4facd9089
--- /dev/null
+++ b/tools/zod2md-jsdocs/eslint.config.js
@@ -0,0 +1,22 @@
+const baseConfig = require('../../eslint.config.js').default;
+
+module.exports = [
+  ...baseConfig,
+  {
+    files: ['**/*.json'],
+    rules: {
+      '@nx/dependency-checks': 'error',
+    },
+  },
+  {
+    files: ['**/*.ts', '**/*.cjs', '**/*.js'],
+    rules: {
+      'import/no-commonjs': 'off',
+      '@typescript-eslint/no-require-imports': 'off',
+      '@typescript-eslint/no-unused-vars': 'off',
+      'unicorn/prefer-module': 'off',
+      'functional/immutable-data': 'off',
+      'arrow-body-style': 'off',
+    },
+  },
+];
diff --git a/tools/zod2md-jsdocs/project.json b/tools/zod2md-jsdocs/project.json
index 18501546f..ee0df63e4 100644
--- a/tools/zod2md-jsdocs/project.json
+++ b/tools/zod2md-jsdocs/project.json
@@ -4,15 +4,9 @@
   "sourceRoot": "tools/zod2md-jsdocs/src",
   "projectType": "library",
   "targets": {
+    "lint": {},
     "build": {
-      "executor": "@nx/js:tsc",
-      "outputs": ["{options.outputPath}"],
-      "dependsOn": ["pre-build"],
-      "options": {
-        "outputPath": "tools/zod2md-jsdocs/dist",
-        "main": "tools/zod2md-jsdocs/src/index.ts",
-        "tsConfig": "tools/zod2md-jsdocs/tsconfig.lib.json"
-      }
+      "dependsOn": ["pre-build"]
     },
     "pre-build": {
       "command": "ts-patch install",
diff --git a/tools/zod2md-jsdocs/src/lib/transformers.ts b/tools/zod2md-jsdocs/src/lib/transformers.ts
index 33fb2e6ba..ac49bd276 100644
--- a/tools/zod2md-jsdocs/src/lib/transformers.ts
+++ b/tools/zod2md-jsdocs/src/lib/transformers.ts
@@ -46,9 +46,8 @@ function annotateTypeDefinitions(
       }
       return tsLib.visitEachChild(node, visitor, context);
     };
-    return (sourceFile: ts.SourceFile) => {
-      return tsLib.visitNode(sourceFile, visitor, tsLib.isSourceFile);
-    };
+    return (sourceFile: ts.SourceFile) =>
+      tsLib.visitNode(sourceFile, visitor, tsLib.isSourceFile);
   };
 }
 

From c33212756ab954b1b447a105426c8c42c70b6fef Mon Sep 17 00:00:00 2001
From: Michael Hladky <john.doe@example.com>
Date: Fri, 5 Dec 2025 17:08:26 +0100
Subject: [PATCH 20/24] refactor: wip

---
 packages/models/project.json                  |  1 +
 .../docs/zod2md-jsdocs-nx-plugin.md           | 10 +--
 tools/zod2md-jsdocs/project.json              | 10 +--
 tools/zod2md-jsdocs/src/lib/transformers.ts   | 10 ++-
 .../src/lib/transformers.unit.test.ts         | 49 +++++++++++++++
 tools/zod2md-jsdocs/src/nx-plugin.cjs         | 62 ++++++++++++++-----
 6 files changed, 114 insertions(+), 28 deletions(-)
 create mode 100644 tools/zod2md-jsdocs/src/lib/transformers.unit.test.ts

diff --git a/packages/models/project.json b/packages/models/project.json
index 966e659a0..282f79504 100644
--- a/packages/models/project.json
+++ b/packages/models/project.json
@@ -8,6 +8,7 @@
       "dependsOn": [
         "^build",
         "generate-docs",
+        "ts-patch",
         { "projects": "zod2md-jsdocs", "target": "build" }
       ]
     },
diff --git a/tools/zod2md-jsdocs/docs/zod2md-jsdocs-nx-plugin.md b/tools/zod2md-jsdocs/docs/zod2md-jsdocs-nx-plugin.md
index f6430ab9a..2dd2d58a4 100644
--- a/tools/zod2md-jsdocs/docs/zod2md-jsdocs-nx-plugin.md
+++ b/tools/zod2md-jsdocs/docs/zod2md-jsdocs-nx-plugin.md
@@ -80,9 +80,10 @@ Default values:
 
 ## Options
 
-| Name           | type                               | description                                            |
-| -------------- | ---------------------------------- | ------------------------------------------------------ |
-| **targetName** | `string` (DEFAULT 'generate-docs') | The id used to identify a target in your project.json. |
+| Name                        | type                               | description                                                         |
+| --------------------------- | ---------------------------------- | ------------------------------------------------------------------- |
+| **docsTargetName**          | `string` (DEFAULT 'generate-docs') | The name of the docs generation target.                             |
+| **jsDocsTypesAugmentation** | `boolean` (DEFAULT `true`)         | Whether to enable TypeScript transformer integration with ts-patch. |
 
 All options are optional and provided in the `nx.json` file.
 
@@ -94,7 +95,8 @@ All options are optional and provided in the `nx.json` file.
     {
       "plugin": "./tools/zod2md-jsdocs-nx-plugin/src/lib/plugin.js",
       "options": {
-        "targetName": "docs",
+        "docsTargetName": "docs",
+        "jsDocsTypesAugmentation": true,
       },
     },
   ],
diff --git a/tools/zod2md-jsdocs/project.json b/tools/zod2md-jsdocs/project.json
index ee0df63e4..3ad54a536 100644
--- a/tools/zod2md-jsdocs/project.json
+++ b/tools/zod2md-jsdocs/project.json
@@ -5,13 +5,7 @@
   "projectType": "library",
   "targets": {
     "lint": {},
-    "build": {
-      "dependsOn": ["pre-build"]
-    },
-    "pre-build": {
-      "command": "ts-patch install",
-      "cache": true,
-      "inputs": ["sharedGlobals", { "runtime": "ts-patch check" }]
-    }
+    "build": {},
+    "unit-test": {}
   }
 }
diff --git a/tools/zod2md-jsdocs/src/lib/transformers.ts b/tools/zod2md-jsdocs/src/lib/transformers.ts
index ac49bd276..dc146fd1d 100644
--- a/tools/zod2md-jsdocs/src/lib/transformers.ts
+++ b/tools/zod2md-jsdocs/src/lib/transformers.ts
@@ -3,7 +3,15 @@ import type * as ts from 'typescript';
 
 const tsInstance: typeof ts = require('typescript');
 
-function generateJSDocComment(typeName: string, baseUrl: string): string {
+/**
+ * Generates a JSDoc comment for a given type name and base URL.
+ * @param typeName
+ * @param baseUrl
+ */
+export function generateJSDocComment(
+  typeName: string,
+  baseUrl: string,
+): string {
   const markdownLink = `${baseUrl}#${typeName.toLowerCase()}`;
   return `*
  * Type Definition: \`${typeName}\`
diff --git a/tools/zod2md-jsdocs/src/lib/transformers.unit.test.ts b/tools/zod2md-jsdocs/src/lib/transformers.unit.test.ts
new file mode 100644
index 000000000..09169947d
--- /dev/null
+++ b/tools/zod2md-jsdocs/src/lib/transformers.unit.test.ts
@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import { generateJSDocComment } from './transformers';
+
+describe('generateJSDocComment', () => {
+  it('should generate JSDoc comment with type name and base URL', () => {
+    const result = generateJSDocComment(
+      'UserSchema',
+      'https://example.com/docs',
+    );
+    expect(result).toMatchInlineSnapshot(`
+      "*
+       * Type Definition: \`UserSchema\`
+       *
+       * This type is derived from a Zod schema and represents
+       * the validated structure of \`UserSchema\` used within the application.
+       *
+       * @see {@link https://example.com/docs#userschema}
+       "
+    `);
+  });
+
+  it('should generate JSDoc comment for different type name', () => {
+    const result = generateJSDocComment(
+      'ConfigOptions',
+      'https://docs.site.com',
+    );
+    expect(result).toBe(
+      `*
+ * Type Definition: \`ConfigOptions\`
+ *
+ * This type is derived from a Zod schema and represents
+ * the validated structure of \`ConfigOptions\` used within the application.
+ *
+ * @see {@link https://docs.site.com#configoptions}
+ `,
+    );
+  });
+
+  it('should convert type name to lowercase in the link anchor', () => {
+    const result = generateJSDocComment('MyComplexType', 'https://example.com');
+    expect(result).toContain('https://example.com#');
+  });
+
+  it('should handle type names with numbers', () => {
+    const result = generateJSDocComment('Schema123', 'https://example.com/api');
+    expect(result).toContain('Type Definition: `Schema123`');
+    expect(result).toContain('#schema123');
+  });
+});
diff --git a/tools/zod2md-jsdocs/src/nx-plugin.cjs b/tools/zod2md-jsdocs/src/nx-plugin.cjs
index 6877856b9..256a87ece 100644
--- a/tools/zod2md-jsdocs/src/nx-plugin.cjs
+++ b/tools/zod2md-jsdocs/src/nx-plugin.cjs
@@ -1,12 +1,49 @@
 const path = require('node:path');
 
 const ZOD2MD_CONFIG_FILE = 'zod2md.config.ts';
+const TS_PATCH_TARGET_NAME = 'ts-patch';
+const GENERATE_DOCS_TARGET_NAME = 'generate-docs';
+
+/**
+ * Creates the ts-patch target configuration
+ * @returns {object} ts-patch target configuration
+ */
+const createTsPatchTargetConfig = {
+  command: 'ts-patch install',
+  cache: true,
+  inputs: ['sharedGlobals', { runtime: 'ts-patch check' }],
+};
+
+/**
+ * Creates the docs generation target configuration
+ * @param {object} params - Configuration parameters
+ * @param {string} params.config - Path to the zod2md config file
+ * @param {string} params.output - Path to the output markdown file
+ * @returns {object} Docs target configuration
+ */
+function createDocsTargetConfig({ config, output }) {
+  return {
+    executor: 'nx:run-commands',
+    options: {
+      commands: [
+        `zod2md --config ${config} --output ${output}`,
+        `prettier --write ${output}`,
+      ],
+      parallel: false,
+    },
+    cache: true,
+    inputs: ['production', '^production', config],
+    outputs: [output],
+  };
+}
 
 const createNodesV2 = [
   `**/${ZOD2MD_CONFIG_FILE}`,
   async (zod2MdConfigurationFiles, createNodesOptions) => {
-    const options = createNodesOptions ?? {};
-    const targetName = options.targetName ?? 'generate-docs';
+    const {
+      docsTargetName = GENERATE_DOCS_TARGET_NAME,
+      jsDocsTypesAugmentation = true,
+    } = createNodesOptions ?? {};
 
     return Promise.all(
       zod2MdConfigurationFiles.map(async zod2MdConfigurationFile => {
@@ -14,23 +51,18 @@ const createNodesV2 = [
         const normalizedProjectRoot = projectRoot === '.' ? '' : projectRoot;
         const output = '{projectRoot}/docs/{projectName}-reference.md';
         const config = `{projectRoot}/${ZOD2MD_CONFIG_FILE}`;
+
         const result = {
           projects: {
             [normalizedProjectRoot]: {
               targets: {
-                [targetName]: {
-                  executor: 'nx:run-commands',
-                  options: {
-                    commands: [
-                      `zod2md --config ${config} --output ${output}`,
-                      `prettier --write ${output}`,
-                    ],
-                    parallel: false,
-                  },
-                  cache: true,
-                  inputs: ['production', '^production', config],
-                  outputs: [output],
-                },
+                ...(jsDocsTypesAugmentation
+                  ? { [TS_PATCH_TARGET_NAME]: createTsPatchTargetConfig }
+                  : {}),
+                [docsTargetName]: createDocsTargetConfig({
+                  config,
+                  output,
+                }),
               },
             },
           },

From 551b7913485fde5d1501a12863e040748e0e874a Mon Sep 17 00:00:00 2001
From: Michael Hladky <john.doe@example.com>
Date: Fri, 5 Dec 2025 17:10:46 +0100
Subject: [PATCH 21/24] refactor: wip

---
 nx.json | 1 -
 1 file changed, 1 deletion(-)

diff --git a/nx.json b/nx.json
index 6b5087763..879cc1050 100644
--- a/nx.json
+++ b/nx.json
@@ -9,7 +9,6 @@
       "!{projectRoot}/CHANGELOG.md",
       "!{projectRoot}/perf/**/*",
       "!{projectRoot}/tools/**/*",
-      "!{projectRoot}/zod2md.config.ts",
       "!{projectRoot}/eslint.config.?(c)js",
       "!{workspaceRoot}/**/.code-pushup/**/*",
       "!{projectRoot}/code-pushup.config.?(m)[jt]s",

From 7f32330b81bc806fc6935b0ff7584cf02c73f1fa Mon Sep 17 00:00:00 2001
From: Michael Hladky <john.doe@example.com>
Date: Fri, 5 Dec 2025 17:28:33 +0100
Subject: [PATCH 22/24] refactor: wip

---
 eslint.config.js                                      | 1 +
 packages/models/package.json                          | 3 ++-
 tools/zod2md-jsdocs/src/lib/transformers.unit.test.ts | 2 +-
 3 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/eslint.config.js b/eslint.config.js
index cf20609ed..6f51e4832 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -140,6 +140,7 @@ export default tseslint.config(
     ignores: [
       '**/*.mock.*',
       '**/code-pushup.config.ts',
+      '**/zod2md.config.ts',
       '**/mocks/fixtures/**',
       '**/__snapshots__/**',
       '**/dist',
diff --git a/packages/models/package.json b/packages/models/package.json
index be3e4daee..68c536727 100644
--- a/packages/models/package.json
+++ b/packages/models/package.json
@@ -29,7 +29,8 @@
   "dependencies": {
     "ansis": "^3.3.2",
     "vscode-material-icons": "^0.1.0",
-    "zod": "^4.0.5"
+    "zod": "^4.0.5",
+    "zod2md": "^0.2.4"
   },
   "files": [
     "src",
diff --git a/tools/zod2md-jsdocs/src/lib/transformers.unit.test.ts b/tools/zod2md-jsdocs/src/lib/transformers.unit.test.ts
index 09169947d..2ad2cece9 100644
--- a/tools/zod2md-jsdocs/src/lib/transformers.unit.test.ts
+++ b/tools/zod2md-jsdocs/src/lib/transformers.unit.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { generateJSDocComment } from './transformers';
+import { generateJSDocComment } from './transformers.js';
 
 describe('generateJSDocComment', () => {
   it('should generate JSDoc comment with type name and base URL', () => {

From 3598f8a7b411e7ba23c34d697f8438697abcca8a Mon Sep 17 00:00:00 2001
From: Michael Hladky <john.doe@example.com>
Date: Fri, 5 Dec 2025 17:36:16 +0100
Subject: [PATCH 23/24] refactor: wip

---
 .../src/lib/transformers.unit.test.ts         | 30 +++++--------------
 1 file changed, 8 insertions(+), 22 deletions(-)

diff --git a/tools/zod2md-jsdocs/src/lib/transformers.unit.test.ts b/tools/zod2md-jsdocs/src/lib/transformers.unit.test.ts
index 2ad2cece9..45df65b4f 100644
--- a/tools/zod2md-jsdocs/src/lib/transformers.unit.test.ts
+++ b/tools/zod2md-jsdocs/src/lib/transformers.unit.test.ts
@@ -19,31 +19,17 @@ describe('generateJSDocComment', () => {
     `);
   });
 
-  it('should generate JSDoc comment for different type name', () => {
-    const result = generateJSDocComment(
-      'ConfigOptions',
-      'https://docs.site.com',
-    );
-    expect(result).toBe(
-      `*
- * Type Definition: \`ConfigOptions\`
- *
- * This type is derived from a Zod schema and represents
- * the validated structure of \`ConfigOptions\` used within the application.
- *
- * @see {@link https://docs.site.com#configoptions}
- `,
-    );
-  });
-
   it('should convert type name to lowercase in the link anchor', () => {
-    const result = generateJSDocComment('MyComplexType', 'https://example.com');
+    const result = generateJSDocComment('Schema', 'https://example.com');
     expect(result).toContain('https://example.com#');
   });
 
-  it('should handle type names with numbers', () => {
-    const result = generateJSDocComment('Schema123', 'https://example.com/api');
-    expect(result).toContain('Type Definition: `Schema123`');
-    expect(result).toContain('#schema123');
+  it('should use type name in description', () => {
+    const result = generateJSDocComment('Schema', 'https://example.com');
+    expect(result).toContain('Type Definition: `SchemaName123`');
+  });
+  it('should convert type name to lowercase in the link anchor', () => {
+    const result = generateJSDocComment('SchemaName123', 'https://example.com');
+    expect(result).toContain('#schemaname123');
   });
 });

From 8d90f872b2d744080d925691a3ab2b7e85168e3e Mon Sep 17 00:00:00 2001
From: Michael Hladky <john.doe@example.com>
Date: Fri, 5 Dec 2025 17:41:00 +0100
Subject: [PATCH 24/24] refactor: wip

---
 .../zod2md-jsdocs/src/lib/transformers.unit.test.ts | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/tools/zod2md-jsdocs/src/lib/transformers.unit.test.ts b/tools/zod2md-jsdocs/src/lib/transformers.unit.test.ts
index 45df65b4f..55b090a03 100644
--- a/tools/zod2md-jsdocs/src/lib/transformers.unit.test.ts
+++ b/tools/zod2md-jsdocs/src/lib/transformers.unit.test.ts
@@ -19,17 +19,18 @@ describe('generateJSDocComment', () => {
     `);
   });
 
-  it('should convert type name to lowercase in the link anchor', () => {
-    const result = generateJSDocComment('Schema', 'https://example.com');
-    expect(result).toContain('https://example.com#');
-  });
-
   it('should use type name in description', () => {
-    const result = generateJSDocComment('Schema', 'https://example.com');
+    const result = generateJSDocComment('SchemaName123', 'https://example.com');
     expect(result).toContain('Type Definition: `SchemaName123`');
   });
+
   it('should convert type name to lowercase in the link anchor', () => {
     const result = generateJSDocComment('SchemaName123', 'https://example.com');
     expect(result).toContain('#schemaname123');
   });
+
+  it('should baseUrl in the link', () => {
+    const result = generateJSDocComment('Schema', 'https://example.com');
+    expect(result).toContain('https://example.com#');
+  });
 });