build(docs): isolate docs build from the workspace lock

.github/workflows/build-agentex.yml

@@ -75,10 +75,9 @@ jobs:
       - name: Build documentation
         working-directory: ./agentex
         run: |
-          # Install docs dependencies
-          uv sync --group docs
-          # Build documentation
-          cd docs && uv run mkdocs build
+          # Build docs in an isolated env (deps from docs/requirements.txt),
+          # decoupled from the workspace lock so it never forces backend dep bumps.
+          cd docs && uv run --isolated --no-project --with-requirements requirements.txt mkdocs build
 
       # Build and push server image to GHCR
       - name: Build and push AgentEx server image to GHCR

.github/workflows/ci.yml

@@ -149,10 +149,9 @@ jobs:
       working-directory: ./agentex
       run: |
         echo "📚 Building documentation..."
-        # Install docs dependencies
-        uv sync --group docs
-        # Build documentation
-        cd docs && uv run mkdocs build
+        # Build docs in an isolated env (deps from docs/requirements.txt),
+        # decoupled from the workspace lock so it never forces backend dep bumps.
+        cd docs && uv run --isolated --no-project --with-requirements requirements.txt mkdocs build
         echo "✅ Documentation built successfully"
 
     # Verify docs were built

agentex/Dockerfile

@@ -65,18 +65,14 @@ FROM base AS docs-builder
 ARG SOURCE_DIR=agentex
 ARG UV_INDEX_URL=
 
-# Install docs dependencies to system Python
+COPY ${SOURCE_DIR}/docs/ docs/
+# Docs build is decoupled from the workspace lock: install the toolchain + latest
+# SDK from docs/requirements.txt so doc generation tracks SDK releases.
 RUN if [ -n "${UV_INDEX_URL}" ]; then \
-        uv export --frozen --group docs --no-emit-project --package agentex-backend \
-            -o /tmp/requirements.txt && \
-        uv pip install --system --index-url "${UV_INDEX_URL}" \
-            -r /tmp/requirements.txt && \
-        rm /tmp/requirements.txt; \
+        uv pip install --system --index-url "${UV_INDEX_URL}" -r docs/requirements.txt; \
     else \
-        uv sync --frozen --group docs --package agentex-backend; \
+        uv pip install --system -r docs/requirements.txt; \
     fi
-
-COPY ${SOURCE_DIR}/docs/ docs/
 COPY ${SOURCE_DIR}/src/ src/
 RUN cd docs && mkdocs build
 

agentex/Makefile

@@ -80,14 +80,12 @@ gen-openapi: ## Regenerate openapi.yaml from the FastAPI app
 #
 
 serve-docs: ## Serve documentation locally
-	@echo "📚 Installing docs dependencies..."
-	uv sync --group docs
-	cd docs && uv run mkdocs serve -a localhost:8001
+	@echo "📚 Serving documentation..."
+	cd docs && uv run --isolated --no-project --with-requirements requirements.txt mkdocs serve -a localhost:8001
 
 build-docs: ## Build documentation
 	@echo "📚 Building documentation..."
-	uv sync --group docs
-	cd docs && uv run mkdocs build
+	cd docs && uv run --isolated --no-project --with-requirements requirements.txt mkdocs build
 
 docker-build: ## Build production Docker image
 	@echo "🐳 Building production Docker image..."

agentex/docs/requirements.txt

@@ -0,0 +1,16 @@
+# Docs build deps — resolved independently of the workspace uv.lock so docs
+# track the latest published SDK without forcing backend dep bumps. Consumed via
+# `uv run --isolated --no-project --with-requirements` (CI, Makefile) and
+# `uv pip install -r` (Dockerfile docs-builder stage).
+#
+# agentex-sdk floats by design (docs track the latest SDK release); the mkdocs
+# toolchain is pinned for reproducible builds — Dependabot keeps the pins current.
+agentex-sdk>=0.12.0
+
+mkdocs==1.6.1
+mkdocs-material==9.7.6
+mkdocs-macros-plugin==1.5.0
+mkdocstrings-python==2.0.4
+griffe-pydantic==1.3.1
+pymdown-extensions==10.21.3
+Pygments==2.20.0