diff --git a/.github/workflows/build-and-test.js.yml b/.github/workflows/build-and-test.js.yml
index 998fbdd..82fc382 100644
--- a/.github/workflows/build-and-test.js.yml
+++ b/.github/workflows/build-and-test.js.yml
@@ -5,13 +5,12 @@ name: Build and Test
 
 on:
   push:
-    branches: [ "main" ]
+    branches: ["main"]
   pull_request:
-    branches: [ "main" ]
+    branches: ["main"]
 
 jobs:
   build:
-
     runs-on: ubuntu-latest
 
     strategy:
@@ -20,15 +19,17 @@ jobs:
         # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
 
     steps:
-    - uses: actions/checkout@v4
-    - name: Install pnpm
-      uses: pnpm/action-setup@v4
-    - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v4
-      with:
-        node-version: ${{ matrix.node-version }}
-        cache: "pnpm"
-    - name: Install dependencies
-      run: pnpm install
-    - name: Run tests
-      run: pnpm test
+      - uses: actions/checkout@v4
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: "pnpm"
+      - name: Install dependencies
+        run: pnpm install
+      - name: Run linting
+        run: pnpm lint
+      - name: Run tests
+        run: pnpm test
diff --git a/EXAMPLES.md b/EXAMPLES.md
new file mode 100644
index 0000000..e9f0fad
--- /dev/null
+++ b/EXAMPLES.md
@@ -0,0 +1,172 @@
+# 📖 Usage Examples
+
+This section provides examples of typical usage scenarios. For detailed information on how to use the library, please refer to the complete [documentation](https://docs.epilot.io/docs/deadlines/deadlines-library/index/).
+
+## Calculating a single deadline
+
+Use the function `calculateDeadline` when you only need the earliest possible contract start date for a single case, without additional details.
+
+### Example
+
+```typescript
+import { calculateDeadline, Commodity, UseCase } from '@epilot/switching-deadlines'
+
+const result = calculateDeadline(
+  {
+    commodity: Commodity.POWER,
+    useCase: UseCase.SWITCH,
+    requiresTermination: true
+  },
+  '2025-10-01' // optional date to calculate from
+)
+
+console.log(result)
+```
+
+### Expected Output
+
+```
+2025-10-07
+```
+
+## Validating a date
+
+Use the function `validateDate` if you want to quickly check whether a specific switching date is valid for a given commodity and use case.
+
+### Example
+
+```typescript
+import { validateDate, Commodity, UseCase } from '@epilot/switching-deadlines'
+
+const isValid = validateDate(
+  {
+    commodity: Commodity.POWER,
+    useCase: UseCase.SWITCH,
+    requiresTermination: true
+  },
+  '2025-01-05', // proposed start date
+  '2025-10-01'  // optional date to calculate from
+)
+
+console.log(isValid)
+```
+
+### Expected Output
+
+```
+false
+```
+
+## Using the Deadline Calculator
+
+Use the `DeadlineCalculator` class when you need more detailed results (e.g., for APIs or batch calculations), including applied rules and working days.
+
+### Example
+
+```typescript
+import { DeadlineCalculator, Commodity, UseCase } from '@epilot/switching-deadlines'
+
+const calculator = new DeadlineCalculator()
+
+const result = calculator.calculateEarliestStartDate(
+  {
+    commodity: Commodity.POWER,
+    useCase: UseCase.SWITCH,
+    requiresTermination: true
+  },
+  '2025-10-01'
+)
+
+console.log(result)
+```
+
+### Expected Output
+
+```json
+{
+  earliestStartDate: 2025-10-07T00:00:00.000Z,
+  earliestStartDateString: '2025-10-07',
+  workingDaysApplied: 2,
+  calendarDaysTotal: 6,
+  isRetrospective: false,
+  ruleApplied: {
+    id: 'power_switch_with_termination',
+    commodity: 'power',
+    useCase: 'switch',
+    requiresTermination: true,
+    requiredWorkingDays: 2,
+    allowsRetrospective: false,
+    description: 'Power contract switch with termination requires 2 working days lead time'
+  }
+```
+
+## Using a custom Calendar Provider
+
+Use a custom calendar provider if you want to include one-time or special holidays not yet reflected in the default calendar.
+
+### Example
+
+```typescript
+import { DeadlineCalculator, CalendarProvider, HolidayType } from '@epilot/switching-deadlines'
+
+const customCalendar = new CalendarProvider({
+  customCalendar: {
+    holidays: [
+      {
+        date: '2026-03-10',
+        name: 'Einmaliger Sonderfeiertag',
+        type: HolidayType.SPECIAL_HOLIDAY,
+        description: 'Special holiday for demonstration purposes',
+        isOneTime: true
+      }
+    ]
+  },
+  useSpecialHolidays: true
+})
+
+const calculator = new DeadlineCalculator({
+  customCalendarProvider: customCalendar
+})
+```
+
+## Checking the library version
+
+To verify that your library installation contains the latest holiday updates and is up to date.
+
+### Example
+
+```typescript
+import { getVersion } from '@epilot/switching-deadlines'
+
+const { version } = getVersion()
+
+console.log(`Library version: ${version}`)
+```
+
+### Expected Output
+
+```
+Library version: 2025.1.4
+```
+
+Alternatively, you can use the `CalendarProvider` to check the version details.
+
+### Example
+
+```typescript
+import { CalendarProvider } from '@epilot/switching-deadlines'
+
+const customCalendar = new CalendarProvider()
+
+console.log(customCalendar.getCalendarVersion())
+```
+
+### Expected Output
+
+```json
+{
+  version: "2025.1.4",
+  year: 2025,
+  lastUpdated: "2025-09-29T13:20:52.863Z"
+}
+```
diff --git a/README.md b/README.md
index 6366d47..fcd04e5 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 A TypeScript library for handling German energy market compliance requirements, specifically supplier switching deadlines as defined by **GPKE** (power) and **GeLi Gas** (gas).
 
-This library is regularly updated to reflect the latest calendar updates. You can find the changelog at [CHANGELOG.md](CHANGELOG.md).
+This library is regularly updated to reflect the latest calendar updates. You can find the changelog at [here](CHANGELOG.md).
 
 ## ✨ Features
 
@@ -77,10 +77,9 @@ console.log(
   `${`The earliest start date is ${relocationResult.earliestStartDate} for relocation and ${switchResult.earliestStartDate} for switching`}`
 )
 ```
+You can find more information in the 📖 [usage examples](EXAMPLES.md).
 
-## 📖 Documentation
-
-Comprehensive usage examples and background information are available in the 👉 [epilot dev center](https://docs.epilot.io/docs/deadlines/intro).
+Comprehensive documentation and background information are available in the 👉 [epilot dev center](https://docs.epilot.io/docs/deadlines/intro).
 
 ## 📜 Disclaimer
 
diff --git a/package.json b/package.json
index ebb6d4d..08e1b5d 100644
--- a/package.json
+++ b/package.json
@@ -41,7 +41,7 @@
     "clean": "rimraf dist coverage",
     "prepare": "pnpm run build",
     "prepublishOnly": "pnpm run build",
-    "gen-docs": "rm -rf docs && typedoc --plugin typedoc-plugin-markdown --out docs src && echo '{ \"label\": \"Switching Deadlines Library\", \"position\": 0 }' > docs/_category_.json"
+    "gen-docs": "rm -rf docs && typedoc --plugin typedoc-plugin-markdown --out docs src/index.ts && echo '{ \"label\": \"Switching Deadlines Library\", \"position\": 0 }' > docs/_category_.json"
   },
   "keywords": [],
   "author": "epilot GmbH",
diff --git a/src/helpers.ts b/src/helpers.ts
index 2d80ba4..654d68c 100644
--- a/src/helpers.ts
+++ b/src/helpers.ts
@@ -40,14 +40,13 @@ export function calculateDeadline(
  * ```typescript
  * import { validateDate, Commodity, UseCase } from '@epilot/switching-deadlines';
  *
- * const result = validateDate('2025-10-05', {
+ * const isValid = validateDate('2025-10-05', {
  *   commodity: Commodity.POWER,
  *   useCase: UseCase.SWITCH,
  *   requiresTermination: true
  * });
  *
- * console.log(result.isValid); // false
- * console.log(result.earliestValidDate); // Date object for 2025-10-07
+ * console.log(isValid); // false
  * ```
  */
 export function validateDate(
diff --git a/typedoc.json b/typedoc.json
new file mode 100644
index 0000000..de6a1f5
--- /dev/null
+++ b/typedoc.json
@@ -0,0 +1,3 @@
+{
+  "projectDocuments": ["./CHANGELOG.md", "./EXAMPLES.md"]
+}