@@ -14,7 +14,7 @@ paths:
 
 ## Comments
 
-Comment only what the JSON can't say: a reason, a constraint, an issue number, or what a template adopter must change. A comment that restates the key below it (`// Show workspace folder name in window title` above `"window.title"`) is noise; leave it out.
+Skip a comment that only repeats the line below it in other words, such as `// Show workspace folder name in window title` above `"window.title"`. Extension descriptions are not that: they say what an extension ID does.
 
 ## node_modules Mount
 
@@ -28,11 +28,12 @@ Always include to keep node_modules off the host:
 
 ## VS Code Extensions
 
-Group by category with a header comment. No per-extension description: the ID names the extension.
+Group by category with header comments:
 
 ```jsonc
 "extensions": [
   // **Category Name**
+  // Extension Description
   "publisher.extension-id"
 ]
 ```
 
@@ -33,13 +33,18 @@
           "bash": { "path": "bash", "icon": "terminal-bash" }
         },
         "extensions.ignoreRecommendations": true,
+        // ── Formatter settings (customize per project) ──────────────────
+        // Change "editor.defaultFormatter" to match your tooling:
+        //   Biome: "biomejs.biome"  |  Prettier: "esbenp.prettier-vscode"
+        //   OXC:   "oxc.oxc-vscode" |  None: remove these three settings
         "editor.formatOnSave": true,
         "editor.defaultFormatter": "oxc.oxc-vscode",
         "editor.codeActionsOnSave": {
           "source.fixAll": "explicit",
           "source.organizeImports": "explicit"
         },
         "window.title": "${localWorkspaceFolderBasename}",
+        // Sandbox visual identity — Claude Dark theme with coral remote indicator
         "workbench.colorTheme": "Claude Dark",
         "workbench.colorCustomizations": {
           "statusBarItem.remoteBackground": "#C15F3C",
 
@@ -5,6 +5,7 @@ IFS=$'\n\t'
 # 1. Extract Docker DNS info BEFORE any flushing
 DOCKER_DNS_RULES=$(iptables-save -t nat | grep "127\.0\.0\.11" || true)
 
+# Flush existing rules and delete existing ipsets
 iptables -F
 iptables -X
 iptables -t nat -F
@@ -31,8 +32,10 @@ iptables -A INPUT -p tcp --sport 22 -m state --state ESTABLISHED -j ACCEPT
 iptables -A INPUT -i lo -j ACCEPT
 iptables -A OUTPUT -o lo -j ACCEPT
 
+# Create ipset with CIDR support
 ipset create allowed-domains hash:net
 
+# Fetch GitHub IP ranges
 echo "Fetching GitHub IP ranges..."
 gh_ranges=$(curl -s https://api.github.com/meta)
 if [ -z "$gh_ranges" ]; then
 
@@ -15,12 +15,17 @@
     "vscode": {
       "extensions": [
         // **AI Agents**
+        // Claude Code - AI assistant
         "anthropic.claude-code",
 
         // **General**
+        // YAML - YAML support (for workflows and docker-compose)
         "redhat.vscode-yaml",
+        // Markdown Preview Github Styles - Markdown preview
         "bierner.markdown-preview-github-styles",
+        // Markdown Preview Mermaid Support - Mermaid diagrams
         "bierner.markdown-mermaid",
+        // Docker - Dockerfile support
         "ms-azuretools.vscode-docker"
       ],
       "settings": {
@@ -30,13 +35,18 @@
           "bash": { "path": "bash", "icon": "terminal-bash" }
         },
         "extensions.ignoreRecommendations": true,
+        // ── Formatter settings (customize per project) ──────────────────
+        // Change "editor.defaultFormatter" to match your tooling:
+        //   Biome: "biomejs.biome"  |  Prettier: "esbenp.prettier-vscode"
+        //   OXC:   "oxc.oxc-vscode" |  None: remove these three settings
         "editor.formatOnSave": true,
         "editor.defaultFormatter": "oxc.oxc-vscode",
         "editor.codeActionsOnSave": {
           "source.fixAll": "explicit",
           "source.organizeImports": "explicit"
         },
         "window.title": "${localWorkspaceFolderBasename}",
+        // Visual identity — Claude Dark theme with coral remote indicator
         "workbench.colorTheme": "Claude Dark",
         "workbench.colorCustomizations": {
           "statusBarItem.remoteBackground": "#C15F3C",
 
@@ -13,21 +13,27 @@
 
   "customizations": {
     "vscode": {
+      // Use zsh as the default shell for better VS Code integration
       "settings": {
         "terminal.integrated.defaultProfile.linux": "zsh",
+        // Suppress extension recommendation prompts (e.g., Container Tools in Codespaces)
         "extensions.ignoreRecommendations": true
       },
+      // Add the IDs of extensions you want installed when the container is created.
       "extensions": [
         // **Claude Code**
         "anthropic.claude-code",
 
         // **Bun**
         "oven.bun-vscode",
 
+        // Prettier - Code Formatter
         "esbenp.prettier-vscode",
 
         // **Tailwind**
+        // Tailwind CSS IntelliSense
         "bradlc.vscode-tailwindcss",
+        // Tailwind Fold
         "stivo.tailwind-fold"
       ]
     }
 
@@ -18,13 +18,15 @@
   "mounts": [
     // Keep node_modules out of a host machine
     "source=${localWorkspaceFolderBasename}-node_modules,target=${containerWorkspaceFolder}/node_modules,type=volume",
-    // zsh writes its history here (HISTFILE in the Dockerfile); the volume name is legacy.
+    // Persist shell history between container rebuilds. zsh writes here
+    // (HISTFILE in the Dockerfile); the volume name is legacy.
     "source=claude-code-bashhistory-${devcontainerId},target=/commandhistory,type=volume",
     "source=claude-code-config-${devcontainerId},target=/home/bun/.claude,type=volume"
   ],
 
   "customizations": {
     "vscode": {
+      // Use zsh as the default shell for better VS Code integration
       "settings": {
         "terminal.integrated.defaultProfile.linux": "zsh",
         "terminal.integrated.profiles.linux": {
@@ -36,6 +38,7 @@
             "path": "zsh"
           }
         },
+        // Suppress extension recommendation prompts (e.g., Container Tools in Codespaces)
         "extensions.ignoreRecommendations": true,
         "editor.formatOnSave": true,
         "editor.defaultFormatter": "biomejs.biome",
@@ -44,6 +47,7 @@
           "source.organizeImports.biome": "explicit"
         }
       },
+      // Add the IDs of extensions you want installed when the container is created.
       "extensions": [
         // **Claude Code**
         "anthropic.claude-code",
@@ -52,10 +56,13 @@
         "oven.bun-vscode",
 
         // **Code Quality**
+        // Biome - Fast formatter and linter for JavaScript/TypeScript
         "biomejs.biome",
 
         // **Tailwind**
+        // Tailwind CSS IntelliSense
         "bradlc.vscode-tailwindcss",
+        // Tailwind Fold
         "stivo.tailwind-fold"
       ]
     }
 
@@ -4,9 +4,13 @@
   "dockerComposeFile": "docker-compose.yml",
   "service": "devcontainer",
   "workspaceFolder": "/workspace",
-  // initializeCommand: see the default variant.
+  // Pull the prebuilt image on the HOST before the build, so "Rebuild Without
+  // Cache" always layers on the freshest base. Replaces `pull_policy: always` in
+  // docker-compose.yml, which breaks on Linux/WSL2 when `updateRemoteUserUID`
+  // builds a local-only image (issue #109). `|| exit 0` keeps offline/outage opens
+  // working (valid in POSIX sh and Windows cmd.exe). Keep in sync with the compose image.
   "initializeCommand": "docker pull ghcr.io/gatezh/devcontainers/claude-code-sandbox:latest || exit 0",
-  // For the iptables firewall.
+  // Capabilities required for iptables firewall setup
   "capAdd": ["NET_ADMIN", "NET_RAW"],
   "init": true,
   "updateRemoteUserUID": true,
@@ -16,42 +20,59 @@
     "vscode": {
       "extensions": [
         // **AI Agents**
+        // Claude Code - AI coding assistant with chat, inline edits, and terminal integration
         "anthropic.claude-code",
 
         // **Runtime**
+        // Bun - Bun runtime support (debugging, lockfile viewer, bundler integration)
         "oven.bun-vscode",
 
         // **Code Quality**
+        // OXC - Fast linter and formatter for JavaScript/TypeScript (Rust-based)
         "oxc.oxc-vscode",
 
         // **Tailwind**
+        // Tailwind CSS IntelliSense - autocomplete, syntax highlighting, linting for Tailwind classes
         "bradlc.vscode-tailwindcss",
+        // Tailwind Fold - collapse long Tailwind class strings in the editor for readability
         "stivo.tailwind-fold",
 
         // **General**
+        // YAML - YAML language support (for workflows and docker-compose)
         "redhat.vscode-yaml",
+        // Markdown Preview Github Styles - renders Markdown preview with GitHub's CSS
         "bierner.markdown-preview-github-styles",
+        // Markdown Preview Mermaid Support - renders Mermaid diagrams in Markdown preview
         "bierner.markdown-mermaid",
+        // Docker - Dockerfile and Compose syntax, linting, and image management
         "ms-azuretools.vscode-docker",
 
         // **Spelling**
+        // Code Spell Checker - catches typos in code and comments
         "streetsidesoftware.code-spell-checker",
 
         // **JavaScript / TypeScript**
+        // npm IntelliSense - autocomplete npm imports in import statements
         "christian-kohler.npm-intellisense",
+        // TypeScript Error Translator - human-readable TS error messages
         "mattpocock.ts-error-translator",
 
         // **CSS / Colors**
+        // Color Info - preview CSS colors on hover
         "bierner.color-info",
+        // Colorize - visualize CSS colors inline in the editor
         "kamikillerto.vscode-colorize",
 
         // **Frameworks**
+        // Drizzle ORM Snippets - code snippets for Drizzle ORM
         "drizzle-team.drizzle-orm-snippets",
 
         // **Testing**
+        // Playwright - run, debug, and generate Playwright tests from VS Code
         "ms-playwright.playwright",
 
         // **Sandbox Theme**
+        // Claude Theme - provides "Claude Dark" referenced by workbench.colorTheme
         "SamiHindi.claude-theme-sami-hindi"
       ],
       "settings": {
@@ -68,7 +89,7 @@
           "source.organizeImports": "explicit"
         },
         "window.title": "${localWorkspaceFolderBasename}",
-        // Tells a sandbox window apart from the default variant at a glance.
+        // Sandbox visual identity — Claude Dark theme with coral remote indicator
         "workbench.colorTheme": "Claude Dark",
         "workbench.colorCustomizations": {
           "statusBarItem.remoteBackground": "#C15F3C",
@@ -78,35 +99,46 @@
       }
     }
   },
-  // Volume names end in ${localWorkspaceFolderBasename} so the default and sandbox
-  // variants share them. Replace "myproject" with your project name in both variants.
+  // Named volumes keep node_modules OFF the host machine and persist across rebuilds.
+  // Uses ${localWorkspaceFolderBasename} so default and sandbox variants share volumes.
+  // Replace "myproject" with your project name (must match across both variants).
   "mounts": [
-    // Every workspace with a package.json needs its own node_modules volume, or
-    // node_modules lands in the bind mount and shows up on the host.
+    // ── node_modules isolation (one per workspace) ─────────────────────
+    // Each workspace with a package.json needs its own volume mount.
+    // Without one, node_modules lands in the bind mount and shows up on the host.
     "source=myproject-node-modules-root-${localWorkspaceFolderBasename},target=/workspace/node_modules,type=volume",
+    // ── Monorepo: uncomment and customize for your structure ──────────
     // "source=myproject-node-modules-api-${localWorkspaceFolderBasename},target=/workspace/services/api/node_modules,type=volume",
     // "source=myproject-node-modules-web-${localWorkspaceFolderBasename},target=/workspace/apps/web/node_modules,type=volume",
+    // ── Persistent config ──────────────────────────────────────────────
     "source=myproject-claude-config-${localWorkspaceFolderBasename},target=/home/node/.claude,type=volume",
     "source=myproject-zsh-history-${localWorkspaceFolderBasename},target=/commandhistory,type=volume",
+    // gh CLI auth/state (~/.config/gh/hosts.yml) — keeps `gh auth login` across rebuilds
     "source=myproject-gh-config-${localWorkspaceFolderBasename},target=/home/node/.config/gh,type=volume",
-    // The image has iptables, ipset and the sudo rule but not the script: each project
-    // mounts its own, with its own domain allowlist.
+    // ── Firewall script ────────────────────────────────────────────────
+    // The image provides iptables/ipset packages and sudo rule but NOT the script itself.
+    // Each project provides its own script via bind mount to customize the domain allowlist.
     "source=${localWorkspaceFolder}/.devcontainer/claude-sandbox/init-firewall.sh,target=/usr/local/bin/init-firewall.sh,type=bind"
   ],
   "containerEnv": {
     "TZ": "${localEnv:TZ:America/Edmonton}",
     "DEVCONTAINER": "true",
     "NODE_OPTIONS": "--max-old-space-size=4096",
     "CLAUDE_CONFIG_DIR": "/home/node/.claude",
-    // Only needed without the default variant, whose sign-in lands on the shared
-    // ~/.claude volume. See "Sandbox Authentication" in the README.
+    // Optional — only needed when the sandbox is used without the default variant, whose
+    // sign-in lands on the shared ~/.claude volume. Resolves to "" when the host var is
+    // unset. See "Sandbox Authentication" section in README.
     "CLAUDE_CODE_OAUTH_TOKEN": "${localEnv:CLAUDE_CODE_OAUTH_TOKEN}"
   },
-  // Plugins install here, before postStartCommand brings the firewall up (which is also
-  // why Chromium comes from the image). The chowns are the same safety net as in the
-  // default variant.
+  // The find command chowns all node_modules volume mount points in one pass.
+  // Chromium is baked into the sandbox image (firewall blocks runtime install).
+  // bun install and init-plugins.sh are skipped when their file is absent. Plugins
+  // install here, before postStartCommand brings the firewall up.
   "postCreateCommand": "sudo find /workspace -maxdepth 4 -name node_modules -type d -exec chown node {} + && sudo chown -R node /home/node/.claude /commandhistory /home/node/.config/gh && mise install && if [ -f package.json ]; then bun install; fi && if [ -f .devcontainer/init-plugins.sh ]; then bash .devcontainer/init-plugins.sh; fi",
-  // patch-playwright-mcp: see the default variant.
+  // Firewall init (bind-mounted from project) + re-patch the Playwright MCP
+  // plugin's .mcp.json. The patch is defense in depth alongside the SessionStart
+  // hook in /etc/claude-code/managed-settings.json, which handles the case where
+  // the plugin auto-updates mid-container-run. See issues #85, #87, #98.
   "postStartCommand": "sudo /usr/local/bin/init-firewall.sh && /usr/local/bin/patch-playwright-mcp",
   "waitFor": "postStartCommand"
 }