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

@@ -6,7 +6,7 @@
 # Development Commands
 #
 
-.PHONY: install install-dev install-docs clean help
+.PHONY: install install-dev clean help
 
 help: ## Show this help message
 	@echo "AgentEx Development Commands:"
@@ -25,10 +25,6 @@ install-dev: ../repo-setup ## Install dependencies including dev group
 ../repo-setup:
 	@$(MAKE) -C .. repo-setup
 
-install-docs: ## Install docs dependencies
-	@echo "🚀 Installing docs dependencies..."
-	uv sync --group docs
-
 clean: ## Clean virtual environment and lock file
 	@echo "🧹 Cleaning virtual environment..."
 	rm -rf .venv uv.lock
@@ -80,14 +76,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

agentex/pyproject.toml

@@ -53,17 +53,6 @@ test = [
     "greenlet>=3.2.3",
     "asyncpg>=0.29.0",
 ]
-docs = [
-    "mkdocs-material>=9.6.14,<10",
-    "mkdocs-macros-plugin>=1.3.7,<2",
-    "mkdocstrings-python>=1.16.12",
-    "mkdocs>=1.6.1",
-    "agentex-sdk",
-    "griffe-pydantic>=1.1.4",
-    "pymdown-extensions>=10.0,<11",
-    "Pygments>=2.19.2,<2.20",
-    "agentex-sdk",
-]
 
 [tool.hatch.build.targets.sdist]
 include = ["src"]

pyproject.toml

@@ -16,9 +16,6 @@ dev = [
     "pre-commit>=3.0.0",
     "ruff>=0.3.4",
 ]
-docs = [
-    "agentex[docs]",
-]
 
 [tool.uv]
 environments = [