docs(docker): comment how to add extra deps (Node, Python, Bun, Debian base)

Add a commented section to docker/Dockerfile showing how to install extra
runtimes/CLIs the agent can call: Alpine apk one-liners (nodejs, python3, go,
build tools, ripgrep), npm-global package managers (pnpm/yarn), the Bun musl
installer, and a fallback to a Debian base / official language images for
glibc-only toolchains — with the adduser->useradd note. All comments; the build
is unchanged. `docker build --check` passes with no warnings.

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

Author: jkyberneees

docker/Dockerfile

@@ -18,9 +18,50 @@ RUN CGO_ENABLED=0 go build -ldflags "-s -w" -o /out/odek ./cmd/odek
 # ---- runtime stage ----
 FROM alpine:latest
 # Tooling the agent commonly needs inside the sandbox container.
-# Trim or extend this list to taste.
+# Trim or extend this list to taste. (git is already included here.)
 RUN apk add --no-cache ca-certificates git bash coreutils curl jq
 
+# ── Adding extra dependencies the agent can use ──────────────────────────
+# The agent runs shell commands INSIDE this image, so any runtime or CLI it
+# should call must be installed here. Uncomment what you need, then rebuild
+# with `docker compose --profile <name> up --build`.
+#
+# IMPORTANT: keep all installs ABOVE the `USER odek` line below — apk, npm,
+# and the Bun installer need root.
+#
+# Alpine packages (musl libc — small and fast):
+#   RUN apk add --no-cache nodejs npm            # Node.js + npm
+#   RUN apk add --no-cache python3 py3-pip        # Python 3 + pip
+#   RUN apk add --no-cache go                      # Go toolchain
+#   RUN apk add --no-cache make gcc g++ musl-dev   # build-essential equivalents
+#   RUN apk add --no-cache ripgrep fd jq yq        # search / JSON-YAML tools
+#
+# JS package managers (once npm is present):
+#   RUN npm install -g pnpm yarn
+#
+# Bun (official installer; needs bash + unzip; BUN_INSTALL puts it on PATH).
+# Uses Bun's musl build on Alpine; libstdc++ is required at runtime:
+#   RUN apk add --no-cache bash unzip libstdc++ \
+#    && curl -fsSL https://bun.sh/install | BUN_INSTALL=/usr/local bash
+#   # → installs /usr/local/bin/bun
+#
+# ── Heavy / glibc-only toolchains: switch to a Debian base ───────────────
+# If a tool won't run on Alpine's musl, replace `FROM alpine:latest` above
+# with a Debian-based image and use apt-get instead:
+#
+#   FROM debian:bookworm-slim
+#   RUN apt-get update && apt-get install -y --no-install-recommends \
+#         ca-certificates git bash curl jq python3 python3-pip nodejs npm \
+#    && rm -rf /var/lib/apt/lists/*
+#
+# …or start from an official language image that already bundles the runtime:
+#   FROM node:20-bookworm-slim     # Node.js + npm preinstalled
+#   FROM python:3.12-slim          # Python preinstalled
+#
+# On a Debian base, the user-creation line below differs — replace
+#   `adduser -D -u 1000 odek`  with  `useradd -m -u 1000 odek`
+# (the mkdir/chown, ENV HOME, USER, and WORKDIR lines all work unchanged).
+
 # Run as a non-root user — defense in depth even inside the container.
 # Pre-create ~/.odek owned by the user so a mounted named volume (used for
 # Telegram session state) inherits uid 1000 ownership and is writable.