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

[max-parke-scale]

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 (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

Greptile Summary

This PR decouples the MkDocs documentation build from the workspace uv.lock by introducing agentex/docs/requirements.txt and switching CI, the Makefile, and the Dockerfile docs-builder stage to install docs deps in an isolated ephemeral environment. Zero changes to pyproject.toml runtime deps or the workspace lock.

• New docs/requirements.txt: mkdocs toolchain packages are pinned to known-good versions for reproducibility; agentex-sdk>=0.12.0 stays floating so the rendered docs automatically track new SDK releases without forcing backend dependency bumps.
• CI & Makefile: Both workflows and both Makefile targets (build-docs, serve-docs) now use uv run --isolated --no-project --with-requirements requirements.txt mkdocs build/serve.
• Dockerfile docs-builder stage: Drops the uv export --frozen --group docs path in favour of uv pip install -r docs/requirements.txt; the docs dependency group is removed from both pyproject.toml and the workspace lock.

Confidence Score: 5/5

Safe to merge — the change is scoped entirely to the docs build pipeline and leaves the backend runtime deps untouched.

All CI, Makefile, and Dockerfile changes are straightforward substitutions of one install method for another. The workspace lock and backend pyproject.toml runtime dependencies are completely unchanged, so there is no risk to the running service. The only finding is a Docker layer-ordering nit in the docs-builder stage that affects build cache efficiency but not correctness.

The COPY order in the docs-builder stage of agentex/Dockerfile is worth a quick look for the caching optimization, but it does not affect build correctness.

Important Files Changed

Filename	Overview
.github/workflows/build-agentex.yml	Switched docs build from uv sync --group docs to uv run --isolated --no-project --with-requirements requirements.txt mkdocs build; one-line replacement, straightforward.
.github/workflows/ci.yml	Same isolated-env docs build switch as build-agentex.yml; no other changes.
agentex/Dockerfile	docs-builder stage now copies the full docs/ dir before running pip install, which breaks Docker layer caching whenever any doc file changes — every .md edit triggers a full dep reinstall.
agentex/Makefile	Removed install-docs target and updated serve-docs/build-docs to use isolated uv run; clean change.
agentex/docs/requirements.txt	New file with pinned mkdocs toolchain and floating agentex-sdk>=0.12.0; addresses prior review comment about reproducibility.
agentex/pyproject.toml	Removed the now-unused docs dependency group; clean-up.
pyproject.toml	Removed root-level docs group that forwarded to agentex[docs]; consistent with backend cleanup.
uv.lock	Removed all docs-only packages (mkdocs, mkdocs-material, mkdocstrings-python, griffe-pydantic, etc.) from the workspace lock; confirms zero backend-runtime deps were touched.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    subgraph Before
        A[uv sync --group docs] --> B[installs from workspace uv.lock]
        B --> C[mkdocs build]
        B --> D[forces agentex-sdk pin in lock]
    end

    subgraph After
        E[docs/requirements.txt] --> F{build context}
        F -->|CI / Makefile| G["uv run --isolated --no-project\n--with-requirements requirements.txt\nmkdocs build"]
        F -->|Dockerfile docs-builder| H["uv pip install --system\n-r docs/requirements.txt"]
        G --> I[mkdocs build]
        H --> I
        E --> J["agentex-sdk>=0.12.0 floats\ntoolchain pinned for reproducibility"]
    end

    D -. eliminated .-> E

Loading

Prompt To Fix All With AI

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

---

### Issue 1 of 1
agentex/Dockerfile:68-76
Docker layer caching is busted for every docs content change. Because `COPY ${SOURCE_DIR}/docs/ docs/` copies all Markdown, images, and config files before the `uv pip install` step, any edit to a `.md` file or `mkdocs.yml` invalidates the install layer and forces a full dependency reinstall on every docs build. Copying only `requirements.txt` first lets the install layer stay cached as long as the pins don't change.

```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/
```

_{Reviews (4): Last reviewed commit: "Merge branch 'main' into maxparke/agx1-2..." | Re-trigger Greptile}

[smoreinis]

yikes! great catch