diff --git a/README.md b/README.md
index 5ce8f14..af2384f 100644
--- a/README.md
+++ b/README.md
@@ -85,7 +85,12 @@ docker compose up
 ### VS Code Devcontainer
 
 Open the project in VS Code and use the "Reopen in Container" command for a fully configured development environment.
-Devcontainer will automatically install uv, Claude Code, and pre-commit hooks.
+Devcontainer will automatically install uv, Claude Code, and pre-commit hooks. The image build installs the latest
+Codex release, so rebuilding the image updates Codex.
+
+The container mounts the host `${HOME}/.claude` and `${HOME}/.codex` directories at `/home/vscode/.claude` and
+`/home/vscode/.codex` for authentication. These bind mounts are read-write, so changes made in the container can
+affect the host configuration. The uv cache is kept in a named volume and reused across container rebuilds.
 
 ### Update Template
 
diff --git a/template/README.md b/template/README.md
index bd3209a..e3e6e78 100644
--- a/template/README.md
+++ b/template/README.md
@@ -42,3 +42,9 @@ docker compose up
 ### VS Code Devcontainer
 
 Open the project in VS Code and use the "Reopen in Container" command for a fully configured development environment.
+Devcontainer automatically installs uv and Claude Code, and installs the latest Codex release when the image is built.
+Rebuild the image to update Codex.
+
+The container mounts the host `${HOME}/.claude` and `${HOME}/.codex` directories at `/home/vscode/.claude` and
+`/home/vscode/.codex` for authentication. These bind mounts are read-write, so changes made in the container can
+affect the host configuration. The uv cache is kept in a named volume and reused across container rebuilds.