fix: keep host node_modules out of the Docker build context (issue #333) (#335)

* fix: keep host node_modules out of the Docker build context (issue #333)

* fix: keep docs/ in the Docker build context for the help agent

* feat: ship the documentation markdown in the Docker image so the help agent is grounded

.dockerignore

@@ -0,0 +1,36 @@
+# Build context excludes. Every path the Dockerfile COPYs from the context must
+# stay out of this list: talemate_frontend/, src/, docs/, scenes/, templates/,
+# tts/, chroma*, pyproject.toml, uv.lock, frontend_wsgi.py, config.example.yaml
+# and docker-entrypoint.sh.
+
+.git
+.github
+tests
+
+# docs/ is NOT excluded. The help agent reads TALEMATE_ROOT/docs at runtime, so
+# the backend-build stage copies it and keeps the markdown.
+
+# A host node_modules lands on top of the one the image installed. pnpm then
+# reads the host's own paths out of it, decides the dependencies are stale, and
+# reinstalls mid-build - which aborts when no TTY can confirm the purge.
+**/node_modules
+talemate_frontend/dist
+
+.venv
+talemate_env
+embedded_python
+embedded_node
+**/__pycache__
+**/*.pyc
+*.egg-info
+.pytest_cache
+.ruff_cache
+.coverage
+
+# Runtime state and credentials. docker-compose mounts these as volumes, so an
+# image layer never needs them.
+config.yaml
+secrets
+pi
+logs
+chats

CHANGELOG.yaml

@@ -82,6 +82,8 @@
   - "Drawer Widths: The director console and help chat drawers no longer stay locked to the window size measured when the page was loaded — they now follow the current window size."
   - "Dependencies: Excluded nltk 3.10.1 from the accepted version range — that release ships a CWD-import security hook that breaks Talemate's standard install layout (virtualenv inside the project directory), crashing startup on any install not using the committed lock. The lock now resolves nltk 3.10.2, where the hook was removed upstream."
   - "Docker: Loading a scene no longer fails with a Memory Agent database error. The image installed an FFmpeg build that had moved past the versions torchcodec supports, so the embedding model could not be imported. The FFmpeg version is now pinned, and a mismatch fails the image build instead of shipping."
+  - "Docker: Building the image from a working copy that had already run the frontend outside Docker no longer fails at `pnpm build` with `ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY`. The repository had no `.dockerignore`, so the build context carried the host's `talemate_frontend/node_modules` into the image on top of the one the build had just installed; pnpm read the host's own paths out of it, judged the dependencies stale, and tried to reinstall them mid-build, which needs a terminal to confirm. A `.dockerignore` now keeps host build output, virtual environments, caches, `config.yaml` and `secrets/` out of the build context, and the frontend stage runs pnpm in CI mode. The corepack and uv versions the image installs are pinned as well, so neither can drift into the next broken build."
+  - "Docker: The Help agent can now read the documentation in the container. The image never carried the bundled `docs/` directory the agent reads at runtime, so in Docker it answered without any grounding in the manual - it could neither search nor open a page. The image now ships the documentation markdown (the screenshots stay out, the agent only ever reads the text)."
 
 0.38.0:
   features:

Dockerfile

@@ -1,3 +1,7 @@
+# The backend-build stage creates the virtual environment and the final stage
+# runs it, so both must install the same uv.
+ARG UV_VERSION=0.12.5
+
 # Stage 1: Frontend build
 FROM node:22-slim AS frontend-build
 
@@ -5,7 +9,11 @@ WORKDIR /app
 
 # Enable pnpm via corepack (version pinned by package.json "packageManager").
 ENV COREPACK_ENABLE_DOWNLOAD_PROMPT=0
-RUN npm install -g corepack@latest && corepack enable
+# pnpm asks before it purges a modules directory, and aborts when no TTY can
+# answer. https://pnpm.io/settings#confirmmodulespurge
+ENV CI=true
+ARG COREPACK_VERSION=0.35.0
+RUN npm install -g corepack@${COREPACK_VERSION} && corepack enable
 
 # Copy frontend manifest, lockfile and pnpm settings
 COPY talemate_frontend/package.json talemate_frontend/pnpm-lock.yaml talemate_frontend/pnpm-workspace.yaml ./
@@ -31,7 +39,8 @@ RUN apt-get update && apt-get install -y \
     && rm -rf /var/lib/apt/lists/*
 
 # Install uv
-RUN pip install uv
+ARG UV_VERSION
+RUN pip install uv==${UV_VERSION}
 
 # Copy installation files
 COPY pyproject.toml uv.lock /app/
@@ -42,6 +51,13 @@ COPY ./src /app/src
 # Create virtual environment and install dependencies (includes CUDA support via pyproject.toml)
 RUN uv sync
 
+# The help agent reads the bundled documentation from TALEMATE_ROOT/docs, and it
+# reads nothing but markdown. Dropping the rest here keeps 36 MB of screenshots
+# out of the final image instead of deleting them in a layer that still ships.
+COPY docs /app/docs
+RUN find /app/docs -type f ! -name "*.md" -delete && \
+    find /app/docs -depth -type d -empty -delete
+
 # Stage 3: Final image
 FROM python:3.11-slim
 
@@ -57,7 +73,8 @@ RUN apt-get update && apt-get install -y \
     && rm -rf /var/lib/apt/lists/*
 
 # Install uv in the final stage
-RUN pip install uv
+ARG UV_VERSION
+RUN pip install uv==${UV_VERSION}
 
 # Node.js runtime for the pi coding agent (Pi Bridge client), reused from the
 # frontend build stage so the final image needs no extra apt source
@@ -100,6 +117,8 @@ RUN /app/.venv/bin/python -B -c "import torchcodec.decoders"
 # Copy Python source code
 COPY --from=backend-build /app/src /app/src
 
+COPY --from=backend-build /app/docs /app/docs
+
 # Copy Node.js build artifacts from frontend-build stage
 COPY --from=frontend-build /app/dist /app/talemate_frontend/dist