diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
index aa9f6f3..7edcc17 100644
--- a/.github/workflows/deploy.yml
+++ b/.github/workflows/deploy.yml
@@ -97,10 +97,13 @@ jobs:
       
       - name: Install dependencies
         run: |
+          # Install capiscio-sdk-python with all its dependencies (pydantic, etc.)
+          # The [dev] extra ensures all optional deps are available for mkdocstrings
+          pip install -e "capiscio-sdk-python[dev]"
+          
+          # Now install docs requirements
           cd capiscio-docs
           pip install -r requirements-docs.txt
-          # Install capiscio-sdk-python in editable mode for mkdocstrings to resolve types
-          pip install -e ../capiscio-sdk-python
       
       - name: Build documentation
         run: |
diff --git a/mkdocs.yml b/mkdocs.yml
index 1fd6380..84a6186 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -79,6 +79,10 @@ plugins:
       handlers:
         python:
           paths: ["../capiscio-sdk-python"]
+          import:
+            # Enable cross-references to Python stdlib and pydantic
+            - https://docs.python.org/3/objects.inv
+            - https://docs.pydantic.dev/latest/objects.inv
           options:
             show_source: false
             show_root_heading: true
@@ -86,12 +90,10 @@ plugins:
             separate_signature: true
             docstring_style: google
             members_order: source
-            # Allow unresolved references for external types (Exception, pydantic.BaseModel, etc.)
             show_if_no_docstring: false
-          inventories:
-            # Enable cross-references to Python stdlib and pydantic
-            - https://docs.python.org/3/objects.inv
-            - https://docs.pydantic.dev/latest/objects.inv
+            # Preload pydantic to resolve base classes
+            preload_modules:
+              - pydantic
 
 markdown_extensions:
   - admonition