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

## Summary

Decouples the documentation build from the backend's workspace `uv.lock`
so documenting a newly released SDK API surface no longer forces backend
dependency bumps.

## Problem

The mkdocs site documents the published `agentex` SDK via mkdocstrings,
which introspects the *installed* `agentex` package. The build installed
it from the frozen workspace lock (`uv sync --group docs`), pinning the
docs to whatever `agentex-sdk` the backend's lock resolved. Documenting
a new path like `agentex.protocol.*` (released in `agentex-sdk` 0.11.5)
therefore required bumping `agentex-sdk` in the lock — and because every
protocol-supporting SDK floors `openai-agents>=0.14.3` (→
`websockets>=15`) and `temporalio>=1.26`, that cascaded backend-runtime
bumps the docs don't need.

## Change

Docs deps now live in `agentex/docs/requirements.txt` and install into
an ephemeral environment, independent of the workspace lock:

- **CI** (`ci.yml`, `build-agentex.yml`) and **Makefile** (`serve-docs`,
`build-docs`): `uv run --isolated --no-project --with-requirements
requirements.txt mkdocs build`
- **Dockerfile** `docs-builder` stage: `uv pip install --system -r
docs/requirements.txt` (honors `UV_INDEX_URL` for private-index prod
builds)

The workspace lock and backend dependency resolution are untouched —
**zero `pyproject.toml` / `uv.lock` changes**. Docs always render
against the latest published SDK.

## Verified

- Isolated `mkdocs build` green locally — griffe introspects an
ephemeral uv env, not `.venv`.
- `make build-docs` green.

## Notes

- The `docs` dependency-group in `agentex/pyproject.toml` is now unused
by the build (left in place; `install-docs` still references it).
Removing it + relocking is a trivial follow-up.
- [#254](#254) (canonical
`agentex.protocol.acp` doc paths) stacks on this branch and goes green
because the isolated build pulls `agentex-sdk>=0.12.0`.

🧑‍💻🤖 — posted via [Claude Code](https://claude.com/claude-code)
<!-- claude-code -->

<!-- greptile_comment -->

<h3>Greptile Summary</h3>

This PR decouples the mkdocs documentation build from the workspace
`uv.lock` by introducing `agentex/docs/requirements.txt` and switching
all build paths (CI, Makefile, Dockerfile) to an isolated `uv`
invocation that installs directly from that file. Backend runtime
dependencies are completely untouched.

- **New `docs/requirements.txt`**: `agentex-sdk>=0.12.0` floats so the
docs always track the latest SDK release; the mkdocs toolchain
(`mkdocs`, `mkdocs-material`, `mkdocstrings-python`, etc.) is pinned to
known-good versions with Dependabot keeping them current.
- **CI & Makefile**: All `uv sync --group docs` invocations replaced
with `uv run --isolated --no-project --with-requirements
requirements.txt mkdocs build`; the docs job in `ci.yml` intentionally
omits uv caching to always resolve the latest SDK.
- **Dockerfile `docs-builder` stage**: Now runs `uv pip install --system
-r docs/requirements.txt` with a `UV_INDEX_URL` conditional preserved
for private-index production builds; the `docs` dependency group removed
from both `pyproject.toml` files and `uv.lock`.

<details><summary><h3>Confidence Score: 5/5</h3></summary>

Safe to merge — build isolation is well-structured and backend
dependencies are untouched.

The change is purely mechanical: three build surfaces (CI workflows,
Makefile, Dockerfile) are updated in a consistent pattern, all verified
locally by the author. Backend runtime dependencies and uv.lock are
untouched.

agentex/Dockerfile — minor layer-ordering opportunity to avoid busting
the install cache on every markdown edit.
</details>

<h3>Important Files Changed</h3>

| Filename | Overview |
|----------|----------|
| .github/workflows/build-agentex.yml | Docs build step switched from uv
sync --group docs to isolated uv run --isolated --no-project
--with-requirements requirements.txt; no issues. |
| .github/workflows/ci.yml | Same isolated docs-build invocation as
build-agentex.yml; docs job intentionally omits uv caching to always
resolve the latest agentex-sdk. |
| agentex/Dockerfile | docs-builder stage now installs from
docs/requirements.txt via uv pip install; COPY of full docs/ before the
install step sacrifices Docker layer cache efficiency. |
| agentex/Makefile | Removed install-docs target; serve-docs and
build-docs now use isolated uv invocations consistent with CI. |
| agentex/docs/requirements.txt | New file with agentex-sdk>=0.12.0
floating and all mkdocs toolchain packages pinned to known-good
versions; clean. |
| agentex/pyproject.toml | Removed the docs dependency-group; workspace
lock is untouched. |
| pyproject.toml | Removed the top-level docs group that forwarded to
agentex[docs]; clean. |
| uv.lock | All docs-only packages removed from lock; backend runtime
dependencies untouched. |

</details>

<details><summary><h3>Flowchart</h3></summary>

```mermaid
%%{init: {'theme': 'neutral'}}%%
flowchart TD
    subgraph OLD["Before (workspace-coupled)"]
        A1["uv sync --group docs\n(reads uv.lock)"] --> B1["uv run mkdocs build"]
        A1 -.->|"forces lock bump\nfor new SDK APIs"| C1["agentex-sdk in uv.lock"]
    end

    subgraph NEW["After (isolated)"]
        A2["docs/requirements.txt\nagentex-sdk>=0.12.0 (float)\nmkdocs==1.6.1 (pinned)\n..."] --> B2["uv run --isolated --no-project\n--with-requirements requirements.txt\nmkdocs build"]
        A2 -.->|"no workspace lock\ninvolved"| C2["agentex-sdk from PyPI\n(latest >= 0.12.0)"]
    end

    subgraph DOCKER["Dockerfile docs-builder stage"]
        D1["COPY docs/requirements.txt"] --> D2["uv pip install --system\n-r docs/requirements.txt\n(UV_INDEX_URL conditional)"]
        D2 --> D3["COPY docs/ + src/"]
        D3 --> D4["mkdocs build"]
    end

    NEW --> DOCKER
```
</details>

<a
href="https://app.greptile.com/api/ide/cursor?prompt=Fix%20the%20following%201%20code%20review%20issue.%20Work%20through%20them%20one%20at%20a%20time%2C%20proposing%20concise%20fixes.%0A%0A---%0A%0A%23%23%23%20Issue%201%20of%201%0Aagentex%2FDockerfile%3A68-77%0AOnly%20%60docs%2Frequirements.txt%60%20is%20needed%20to%20run%20the%20install%20step%20%E2%80%94%20copying%20the%20entire%20%60docs%2F%60%20directory%20first%20means%20any%20change%20to%20a%20markdown%20file%20or%20config%20will%20bust%20the%20%60uv%20pip%20install%60%20cache%20layer%2C%20forcing%20a%20fresh%20package%20download%20on%20every%20docs%20edit.%20Copy%20just%20the%20requirements%20file%20for%20the%20install%2C%20then%20copy%20the%20rest%20of%20%60docs%2F%60.%0A%0A%60%60%60suggestion%0ACOPY%20%24%7BSOURCE_DIR%7D%2Fdocs%2Frequirements.txt%20docs%2Frequirements.txt%0A%23%20Docs%20build%20is%20decoupled%20from%20the%20workspace%20lock%3A%20install%20the%20toolchain%20%2B%20latest%0A%23%20SDK%20from%20docs%2Frequirements.txt%20so%20doc%20generation%20tracks%20SDK%20releases.%0ARUN%20if%20%5B%20-n%20%22%24%7BUV_INDEX_URL%7D%22%20%5D%3B%20then%20%5C%0A%20%20%20%20%20%20%20%20uv%20pip%20install%20--system%20--index-url%20%22%24%7BUV_INDEX_URL%7D%22%20-r%20docs%2Frequirements.txt%3B%20%5C%0A%20%20%20%20else%20%5C%0A%20%20%20%20%20%20%20%20uv%20pip%20install%20--system%20-r%20docs%2Frequirements.txt%3B%20%5C%0A%20%20%20%20fi%0ACOPY%20%24%7BSOURCE_DIR%7D%2Fdocs%2F%20docs%2F%0ACOPY%20%24%7BSOURCE_DIR%7D%2Fsrc%2F%20src%2F%0ARUN%20cd%20docs%20%26%26%20mkdocs%20build%0A%60%60%60%0A%0A&pr=286&platform=github"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://greptile-static-assets.s3.amazonaws.com/badges/FixAllInCursorDark.svg?v=3"><source
media="(prefers-color-scheme: light)"
srcset="https://greptile-static-assets.s3.amazonaws.com/badges/FixAllInCursor.svg?v=3"><img
alt="Fix All in Cursor"
src="https://greptile-static-assets.s3.amazonaws.com/badges/FixAllInCursor.svg?v=3"
height="20"></picture></a> <a
href="https://app.greptile.com/ide/claude-code?prompt=Fix%20the%20following%201%20code%20review%20issue.%20Work%20through%20them%20one%20at%20a%20time%2C%20proposing%20concise%20fixes.%0A%0A---%0A%0A%23%23%23%20Issue%201%20of%201%0Aagentex%2FDockerfile%3A68-77%0AOnly%20%60docs%2Frequirements.txt%60%20is%20needed%20to%20run%20the%20install%20step%20%E2%80%94%20copying%20the%20entire%20%60docs%2F%60%20directory%20first%20means%20any%20change%20to%20a%20markdown%20file%20or%20config%20will%20bust%20the%20%60uv%20pip%20install%60%20cache%20layer%2C%20forcing%20a%20fresh%20package%20download%20on%20every%20docs%20edit.%20Copy%20just%20the%20requirements%20file%20for%20the%20install%2C%20then%20copy%20the%20rest%20of%20%60docs%2F%60.%0A%0A%60%60%60suggestion%0ACOPY%20%24%7BSOURCE_DIR%7D%2Fdocs%2Frequirements.txt%20docs%2Frequirements.txt%0A%23%20Docs%20build%20is%20decoupled%20from%20the%20workspace%20lock%3A%20install%20the%20toolchain%20%2B%20latest%0A%23%20SDK%20from%20docs%2Frequirements.txt%20so%20doc%20generation%20tracks%20SDK%20releases.%0ARUN%20if%20%5B%20-n%20%22%24%7BUV_INDEX_URL%7D%22%20%5D%3B%20then%20%5C%0A%20%20%20%20%20%20%20%20uv%20pip%20install%20--system%20--index-url%20%22%24%7BUV_INDEX_URL%7D%22%20-r%20docs%2Frequirements.txt%3B%20%5C%0A%20%20%20%20else%20%5C%0A%20%20%20%20%20%20%20%20uv%20pip%20install%20--system%20-r%20docs%2Frequirements.txt%3B%20%5C%0A%20%20%20%20fi%0ACOPY%20%24%7BSOURCE_DIR%7D%2Fdocs%2F%20docs%2F%0ACOPY%20%24%7BSOURCE_DIR%7D%2Fsrc%2F%20src%2F%0ARUN%20cd%20docs%20%26%26%20mkdocs%20build%0A%60%60%60%0A%0A&repo=scaleapi%2Fscale-agentex&pr=286&platform=github"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://greptile-static-assets.s3.amazonaws.com/badges/FixAllInClaudeDark.svg?v=3"><source
media="(prefers-color-scheme: light)"
srcset="https://greptile-static-assets.s3.amazonaws.com/badges/FixAllInClaude.svg?v=3"><img
alt="Fix All in Claude Code"
src="https://greptile-static-assets.s3.amazonaws.com/badges/FixAllInClaude.svg?v=3"
height="20"></picture></a> <a
href="https://app.greptile.com/api/ide/codex?prompt=IMPORTANT%3A%20Work%20in%20the%20repository%20%22scaleapi%2Fscale-agentex%22%20on%20the%20existing%20branch%20%22maxparke%2Fagx1-292-docs-build-isolation%22.%20Checkout%20that%20branch%20%E2%80%94%20do%20NOT%20create%20a%20new%20branch%20or%20open%20a%20new%20PR.%20Push%20your%20changes%20to%20%22maxparke%2Fagx1-292-docs-build-isolation%22.%0A%0AFix%20the%20following%201%20code%20review%20issue.%20Work%20through%20them%20one%20at%20a%20time%2C%20proposing%20concise%20fixes.%0A%0A---%0A%0A%23%23%23%20Issue%201%20of%201%0Aagentex%2FDockerfile%3A68-77%0AOnly%20%60docs%2Frequirements.txt%60%20is%20needed%20to%20run%20the%20install%20step%20%E2%80%94%20copying%20the%20entire%20%60docs%2F%60%20directory%20first%20means%20any%20change%20to%20a%20markdown%20file%20or%20config%20will%20bust%20the%20%60uv%20pip%20install%60%20cache%20layer%2C%20forcing%20a%20fresh%20package%20download%20on%20every%20docs%20edit.%20Copy%20just%20the%20requirements%20file%20for%20the%20install%2C%20then%20copy%20the%20rest%20of%20%60docs%2F%60.%0A%0A%60%60%60suggestion%0ACOPY%20%24%7BSOURCE_DIR%7D%2Fdocs%2Frequirements.txt%20docs%2Frequirements.txt%0A%23%20Docs%20build%20is%20decoupled%20from%20the%20workspace%20lock%3A%20install%20the%20toolchain%20%2B%20latest%0A%23%20SDK%20from%20docs%2Frequirements.txt%20so%20doc%20generation%20tracks%20SDK%20releases.%0ARUN%20if%20%5B%20-n%20%22%24%7BUV_INDEX_URL%7D%22%20%5D%3B%20then%20%5C%0A%20%20%20%20%20%20%20%20uv%20pip%20install%20--system%20--index-url%20%22%24%7BUV_INDEX_URL%7D%22%20-r%20docs%2Frequirements.txt%3B%20%5C%0A%20%20%20%20else%20%5C%0A%20%20%20%20%20%20%20%20uv%20pip%20install%20--system%20-r%20docs%2Frequirements.txt%3B%20%5C%0A%20%20%20%20fi%0ACOPY%20%24%7BSOURCE_DIR%7D%2Fdocs%2F%20docs%2F%0ACOPY%20%24%7BSOURCE_DIR%7D%2Fsrc%2F%20src%2F%0ARUN%20cd%20docs%20%26%26%20mkdocs%20build%0A%60%60%60%0A%0A&repo=scaleapi%2Fscale-agentex&pr=286&platform=github"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://greptile-static-assets.s3.amazonaws.com/badges/FixAllInCodexDark.svg?v=3"><source
media="(prefers-color-scheme: light)"
srcset="https://greptile-static-assets.s3.amazonaws.com/badges/FixAllInCodex.svg?v=3"><img
alt="Fix All in Codex"
src="https://greptile-static-assets.s3.amazonaws.com/badges/FixAllInCodex.svg?v=3"
height="20"></picture></a>

<details><summary>Prompt To Fix All With AI</summary>

`````markdown
Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
agentex/Dockerfile:68-77
Only `docs/requirements.txt` is needed to run the install step — copying the entire `docs/` directory first means any change to a markdown file or config will bust the `uv pip install` cache layer, forcing a fresh package download on every docs edit. Copy just the requirements file for the install, then copy the rest of `docs/`.

```suggestion
COPY ${SOURCE_DIR}/docs/requirements.txt docs/requirements.txt
# 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 pip install --system --index-url "${UV_INDEX_URL}" -r
docs/requirements.txt; \
    else \
        uv pip install --system -r docs/requirements.txt; \
    fi
COPY ${SOURCE_DIR}/docs/ docs/
COPY ${SOURCE_DIR}/src/ src/
RUN cd docs && mkdocs build
```

`````

</details>

<sub>Reviews (3): Last reviewed commit: ["build(docs): drop the
now-unused docs
de..."](1afad5c)
| [Re-trigger
Greptile](https://app.greptile.com/api/retrigger?id=36304983)</sub>

<!-- /greptile_comment -->

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: max-parke-scale

.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 = [