From 5adafe46a3106dc1ea0fd279ae0ee4ae20076f4a Mon Sep 17 00:00:00 2001
From: Niall Munro <niall.munro@ed.ac.uk>
Date: Fri, 26 Sep 2025 11:44:24 +0100
Subject: [PATCH 01/15] Update VSCODE_COMMIT handling in devcontainer
 configuration and workflow

---
 .devcontainer/devcontainer.json          |  2 +-
 .github/workflows/build-devcontainer.yml | 27 +++++++++++++++++-------
 2 files changed, 20 insertions(+), 9 deletions(-)

diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
index 3393cea..8fe64b2 100644
--- a/.devcontainer/devcontainer.json
+++ b/.devcontainer/devcontainer.json
@@ -6,7 +6,7 @@
 	"build": {
 		"dockerfile": "Dockerfile",
 		"args": {
-			"VSCODE_COMMIT": "f220831ea2d946c0dcb0f3eaa480eb435a2c1260"
+			"VSCODE_COMMIT": "${VSCODE_COMMIT:-f220831ea2d946c0dcb0f3eaa480eb435a2c1260}"
 		}
 	},
 
diff --git a/.github/workflows/build-devcontainer.yml b/.github/workflows/build-devcontainer.yml
index 87ca677..5a72c71 100644
--- a/.github/workflows/build-devcontainer.yml
+++ b/.github/workflows/build-devcontainer.yml
@@ -1,12 +1,6 @@
 name: Build and Publish Dev Container
 
 on:
-  push:
-    branches:
-      - main
-    paths:
-      - '.devcontainer/**'
-      - '.github/workflows/build-devcontainer.yml'
   pull_request:
     branches:
       - main
@@ -14,6 +8,11 @@ on:
       - '.devcontainer/**'
       - '.github/workflows/build-devcontainer.yml'
   workflow_dispatch:
+    inputs:
+      vscode_commit:
+        description: 'VS Code commit hash to use'
+        required: true
+        type: string
 
 env:
   REGISTRY: ghcr.io
@@ -32,10 +31,19 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Read VSCODE_COMMIT from devcontainer.json
+      - name: Determine VSCODE_COMMIT
         id: vscode-commit
         run: |
-          VSCODE_COMMIT=$(grep 'VSCODE_COMMIT' .devcontainer/devcontainer.json | tr -d '"' | cut -d " " -f 2)
+          # For manual dispatch, use the required input
+          # For PR builds, read from devcontainer.json
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            VSCODE_COMMIT="${{ github.event.inputs.vscode_commit }}"
+            echo "Using VSCODE_COMMIT from workflow input: $VSCODE_COMMIT"
+          else
+            VSCODE_COMMIT=$(grep 'VSCODE_COMMIT' .devcontainer/devcontainer.json | tr -d '"' | cut -d " " -f 2)
+            echo "Using VSCODE_COMMIT from devcontainer.json: $VSCODE_COMMIT"
+          fi
+          
           VSCODE_SHORT=${VSCODE_COMMIT:0:7}
           echo "vscode_commit=$VSCODE_COMMIT" >> $GITHUB_OUTPUT
           echo "vscode_short=$VSCODE_SHORT" >> $GITHUB_OUTPUT
@@ -76,6 +84,9 @@ jobs:
 
       - name: Build and publish dev container
         uses: devcontainers/ci@v0.3
+        env:
+          # Pass the resolved VSCODE_COMMIT as an environment variable for the build
+          VSCODE_COMMIT: ${{ steps.vscode-commit.outputs.vscode_commit }}
         with:
           imageName: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           imageTag: ${{ steps.tags.outputs.tags }}

From 1f60c6a4d44fac5ed8ea78e3c386fe5db1f24b0e Mon Sep 17 00:00:00 2001
From: Niall Munro <niall.munro@ed.ac.uk>
Date: Fri, 26 Sep 2025 15:54:08 +0100
Subject: [PATCH 02/15] Refactor VSCODE_COMMIT handling in build workflow to
 simplify input management

---
 .github/workflows/build-devcontainer.yml | 23 +++++++++++------------
 1 file changed, 11 insertions(+), 12 deletions(-)

diff --git a/.github/workflows/build-devcontainer.yml b/.github/workflows/build-devcontainer.yml
index 5a72c71..70a42d0 100644
--- a/.github/workflows/build-devcontainer.yml
+++ b/.github/workflows/build-devcontainer.yml
@@ -31,23 +31,22 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Determine VSCODE_COMMIT
+      - name: Override VSCODE_COMMIT if provided
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          # Update devcontainer.json with the provided VSCODE_COMMIT
+          sed -i 's/"VSCODE_COMMIT": "${VSCODE_COMMIT:-[^}]*}"/"VSCODE_COMMIT": "${{ github.event.inputs.vscode_commit }}"/' .devcontainer/devcontainer.json
+          echo "Updated devcontainer.json with VSCODE_COMMIT: ${{ github.event.inputs.vscode_commit }}"
+
+      - name: Read VSCODE_COMMIT from devcontainer.json
         id: vscode-commit
         run: |
-          # For manual dispatch, use the required input
-          # For PR builds, read from devcontainer.json
-          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
-            VSCODE_COMMIT="${{ github.event.inputs.vscode_commit }}"
-            echo "Using VSCODE_COMMIT from workflow input: $VSCODE_COMMIT"
-          else
-            VSCODE_COMMIT=$(grep 'VSCODE_COMMIT' .devcontainer/devcontainer.json | tr -d '"' | cut -d " " -f 2)
-            echo "Using VSCODE_COMMIT from devcontainer.json: $VSCODE_COMMIT"
-          fi
-          
+          # Always read from devcontainer.json (which may have been updated above)
+          VSCODE_COMMIT=$(grep 'VSCODE_COMMIT' .devcontainer/devcontainer.json | tr -d '"' | cut -d " " -f 2)
           VSCODE_SHORT=${VSCODE_COMMIT:0:7}
           echo "vscode_commit=$VSCODE_COMMIT" >> $GITHUB_OUTPUT
           echo "vscode_short=$VSCODE_SHORT" >> $GITHUB_OUTPUT
-          echo "Full VSCODE_COMMIT: $VSCODE_COMMIT"
+          echo "Using VSCODE_COMMIT: $VSCODE_COMMIT"
           echo "Short VSCODE_COMMIT: $VSCODE_SHORT"
 
       - name: Set up Docker Buildx

From e778afe51396608eb6c4d5126c69d67724decdaf Mon Sep 17 00:00:00 2001
From: Niall Munro <niall.munro@ed.ac.uk>
Date: Fri, 26 Sep 2025 17:20:02 +0100
Subject: [PATCH 03/15] Update VSCODE_COMMIT input to be optional and simplify
 tagging logic in build workflow

---
 .github/workflows/build-devcontainer.yml | 23 +++++++++--------------
 1 file changed, 9 insertions(+), 14 deletions(-)

diff --git a/.github/workflows/build-devcontainer.yml b/.github/workflows/build-devcontainer.yml
index 70a42d0..175aebe 100644
--- a/.github/workflows/build-devcontainer.yml
+++ b/.github/workflows/build-devcontainer.yml
@@ -11,10 +11,14 @@ on:
     inputs:
       vscode_commit:
         description: 'VS Code commit hash to use'
-        required: true
+        required: false
         type: string
 
 env:
+  # Set a default VS Code commit hash for tagging purposes
+  # This can be overridden via workflow_dispatch input if needed
+  # For PRs, the default value will be used
+  VSCODE_COMMIT: ${{ github.event.inputs.vscode_commit || 'f220831ea2d946c0dcb0f3eaa480eb435a2c1260' }}
   REGISTRY: ghcr.io
   IMAGE_NAME: ${{ github.repository }}
 
@@ -31,23 +35,14 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Override VSCODE_COMMIT if provided
-        if: github.event_name == 'workflow_dispatch'
-        run: |
-          # Update devcontainer.json with the provided VSCODE_COMMIT
-          sed -i 's/"VSCODE_COMMIT": "${VSCODE_COMMIT:-[^}]*}"/"VSCODE_COMMIT": "${{ github.event.inputs.vscode_commit }}"/' .devcontainer/devcontainer.json
-          echo "Updated devcontainer.json with VSCODE_COMMIT: ${{ github.event.inputs.vscode_commit }}"
-
-      - name: Read VSCODE_COMMIT from devcontainer.json
+      - name: Set VSCODE_COMMIT for tagging
         id: vscode-commit
         run: |
-          # Always read from devcontainer.json (which may have been updated above)
-          VSCODE_COMMIT=$(grep 'VSCODE_COMMIT' .devcontainer/devcontainer.json | tr -d '"' | cut -d " " -f 2)
+          # For manual dispatch, use the input; for PRs use default value for tagging
+          VSCODE_COMMIT="${{ github.event.inputs.vscode_commit }}"
           VSCODE_SHORT=${VSCODE_COMMIT:0:7}
           echo "vscode_commit=$VSCODE_COMMIT" >> $GITHUB_OUTPUT
           echo "vscode_short=$VSCODE_SHORT" >> $GITHUB_OUTPUT
-          echo "Using VSCODE_COMMIT: $VSCODE_COMMIT"
-          echo "Short VSCODE_COMMIT: $VSCODE_SHORT"
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
@@ -84,7 +79,7 @@ jobs:
       - name: Build and publish dev container
         uses: devcontainers/ci@v0.3
         env:
-          # Pass the resolved VSCODE_COMMIT as an environment variable for the build
+          # Only override VSCODE_COMMIT for manual dispatch; PRs use devcontainer.json default
           VSCODE_COMMIT: ${{ steps.vscode-commit.outputs.vscode_commit }}
         with:
           imageName: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}

From f12a3d8a648d870064e2474fc29a589b627d8406 Mon Sep 17 00:00:00 2001
From: Niall Munro <niall.munro@ed.ac.uk>
Date: Fri, 26 Sep 2025 18:48:18 +0100
Subject: [PATCH 04/15] Update Dockerfile and workflow to enforce required
 VSCODE_COMMIT input and adjust environment variable handling

---
 .devcontainer/Dockerfile                 | 2 ++
 .devcontainer/devcontainer.json          | 1 -
 .github/workflows/build-devcontainer.yml | 2 +-
 3 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
index 436d7e2..9e41c53 100644
--- a/.devcontainer/Dockerfile
+++ b/.devcontainer/Dockerfile
@@ -3,6 +3,8 @@ FROM mcr.microsoft.com/devcontainers/base:noble
 # VS Code commit ID for devcontainer compatibility, argument supplied at build time via devcontainer.json
 ARG VSCODE_COMMIT
 
+ENV VSCODE_COMMIT=${VSCODE_COMMIT}
+
 # Copy and run VS Code installation files
 COPY ./vscode-init /opt/vscode-init
 RUN cd /opt/vscode-init \ 
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
index 8fe64b2..37b5814 100644
--- a/.devcontainer/devcontainer.json
+++ b/.devcontainer/devcontainer.json
@@ -2,7 +2,6 @@
 // README at: https://github.com/devcontainers/templates/tree/main/src/ubuntu
 {
 	"name": "Python Development Environment",
-	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
 	"build": {
 		"dockerfile": "Dockerfile",
 		"args": {
diff --git a/.github/workflows/build-devcontainer.yml b/.github/workflows/build-devcontainer.yml
index 175aebe..e3b641c 100644
--- a/.github/workflows/build-devcontainer.yml
+++ b/.github/workflows/build-devcontainer.yml
@@ -11,7 +11,7 @@ on:
     inputs:
       vscode_commit:
         description: 'VS Code commit hash to use'
-        required: false
+        required: true
         type: string
 
 env:

From b16d0124a0007bab477b20adcc8f7074e51632d9 Mon Sep 17 00:00:00 2001
From: Niall Munro <niall.munro@ed.ac.uk>
Date: Fri, 26 Sep 2025 21:59:29 +0100
Subject: [PATCH 05/15] Remove redundant environment variable declaration for
 VSCODE_COMMIT in Dockerfile

---
 .devcontainer/Dockerfile | 2 --
 1 file changed, 2 deletions(-)

diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
index 9e41c53..436d7e2 100644
--- a/.devcontainer/Dockerfile
+++ b/.devcontainer/Dockerfile
@@ -3,8 +3,6 @@ FROM mcr.microsoft.com/devcontainers/base:noble
 # VS Code commit ID for devcontainer compatibility, argument supplied at build time via devcontainer.json
 ARG VSCODE_COMMIT
 
-ENV VSCODE_COMMIT=${VSCODE_COMMIT}
-
 # Copy and run VS Code installation files
 COPY ./vscode-init /opt/vscode-init
 RUN cd /opt/vscode-init \ 

From 5969b252af71d6ef96be6909bb5b25e1f01df454 Mon Sep 17 00:00:00 2001
From: Niall Munro <niall.munro@ed.ac.uk>
Date: Fri, 26 Sep 2025 22:08:54 +0100
Subject: [PATCH 06/15] Refactor VSCODE_COMMIT handling in build workflow to
 use environment variable for consistency

---
 .github/workflows/build-devcontainer.yml | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/build-devcontainer.yml b/.github/workflows/build-devcontainer.yml
index e3b641c..e21ad3f 100644
--- a/.github/workflows/build-devcontainer.yml
+++ b/.github/workflows/build-devcontainer.yml
@@ -39,7 +39,7 @@ jobs:
         id: vscode-commit
         run: |
           # For manual dispatch, use the input; for PRs use default value for tagging
-          VSCODE_COMMIT="${{ github.event.inputs.vscode_commit }}"
+          VSCODE_COMMIT="${{ env.VSCODE_COMMIT }}"
           VSCODE_SHORT=${VSCODE_COMMIT:0:7}
           echo "vscode_commit=$VSCODE_COMMIT" >> $GITHUB_OUTPUT
           echo "vscode_short=$VSCODE_SHORT" >> $GITHUB_OUTPUT
@@ -78,14 +78,13 @@ jobs:
 
       - name: Build and publish dev container
         uses: devcontainers/ci@v0.3
-        env:
-          # Only override VSCODE_COMMIT for manual dispatch; PRs use devcontainer.json default
-          VSCODE_COMMIT: ${{ steps.vscode-commit.outputs.vscode_commit }}
         with:
           imageName: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           imageTag: ${{ steps.tags.outputs.tags }}
           cacheFrom: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           push: always
+          env: |
+            VSCODE_COMMIT=${{ steps.vscode-commit.outputs.vscode_commit }}
           # Test the container with a simple validation
           runCmd: |
             echo "=== Testing dev container ==="

From 921c27178f431d52996b74c2f6ada7b35c800657 Mon Sep 17 00:00:00 2001
From: Niall Munro <niall.munro@ed.ac.uk>
Date: Fri, 26 Sep 2025 22:21:51 +0100
Subject: [PATCH 07/15] Refactor build step to set VSCODE_COMMIT in env
 directly for clarity

---
 .github/workflows/build-devcontainer.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/build-devcontainer.yml b/.github/workflows/build-devcontainer.yml
index e21ad3f..1d235fd 100644
--- a/.github/workflows/build-devcontainer.yml
+++ b/.github/workflows/build-devcontainer.yml
@@ -78,13 +78,13 @@ jobs:
 
       - name: Build and publish dev container
         uses: devcontainers/ci@v0.3
+        env:
+          VSCODE_COMMIT: ${{ steps.vscode-commit.outputs.vscode_commit }}
         with:
           imageName: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           imageTag: ${{ steps.tags.outputs.tags }}
           cacheFrom: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           push: always
-          env: |
-            VSCODE_COMMIT=${{ steps.vscode-commit.outputs.vscode_commit }}
           # Test the container with a simple validation
           runCmd: |
             echo "=== Testing dev container ==="

From 6ad941ebdfde1157fef87e4da320952089be91b9 Mon Sep 17 00:00:00 2001
From: Niall Munro <niall.munro@ed.ac.uk>
Date: Fri, 26 Sep 2025 22:52:41 +0100
Subject: [PATCH 08/15] Update VSCODE_COMMIT argument in devcontainer.json to
 use localEnv for consistency

---
 .devcontainer/devcontainer.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
index 37b5814..093ba91 100644
--- a/.devcontainer/devcontainer.json
+++ b/.devcontainer/devcontainer.json
@@ -5,7 +5,7 @@
 	"build": {
 		"dockerfile": "Dockerfile",
 		"args": {
-			"VSCODE_COMMIT": "${VSCODE_COMMIT:-f220831ea2d946c0dcb0f3eaa480eb435a2c1260}"
+			"VSCODE_COMMIT": "${localEnv:VSCODE_COMMIT:0f0d87fa9e96c856c5212fc86db137ac0d783365}"
 		}
 	},
 

From 7d1dbbef8219af179479cd925f2b2628981c37a0 Mon Sep 17 00:00:00 2001
From: Niall Munro <niall.munro@ed.ac.uk>
Date: Fri, 26 Sep 2025 23:46:47 +0100
Subject: [PATCH 09/15] Update documentation to include VS Code Server
 versioning and tagging strategy

---
 DEVCONTAINER.md                 | 23 +++++++++++++++-----
 README.md                       | 37 ++++++++++++++++++++++-----------
 SDF_TRE_SETUP.md                |  6 +++---
 docs/BUILD_PUBLISH_CONTAINER.md |  3 ++-
 4 files changed, 48 insertions(+), 21 deletions(-)

diff --git a/DEVCONTAINER.md b/DEVCONTAINER.md
index 8c2ad03..259cc6e 100644
--- a/DEVCONTAINER.md
+++ b/DEVCONTAINER.md
@@ -13,11 +13,14 @@ The dev container is automatically built and published with multiple tags:
   - `main` - Latest build from main branch  
   - `main-<commit-sha>` - Specific commit builds from main branch
   - `pr-<number>` - Pull request builds for testing
+  - `vscode-<vscode-commit-sha>` - Builds with specific VS Code Server versions
+  - `vscode-<vscode-commit-sha>-<commit-sha>` - Combination of VS Code Server and container commit
 
 ### Choosing the Right Tag
 
 - **For production/stable use**: `ghcr.io/smartdatafoundry/devcontainer:latest`
-- **For reproducible builds**: `ghcr.io/smartdatafoundry/devcontainer:main-abc1234` 
+- **For reproducible builds**: `ghcr.io/smartdatafoundry/devcontainer:vscode-<vscode-commit-sha>-<commit-sha>` 
+- **For specific VS Code Server versions**: `ghcr.io/smartdatafoundry/devcontainer:vscode-<vscode-commit-sha>`
 - **For testing PR changes**: `ghcr.io/smartdatafoundry/devcontainer:pr-123`
 
 ## 🚀 Quick Start
@@ -76,17 +79,25 @@ This dev container includes:
   - Jupyter support
   - Markdown All in One
   - Rainbow CSV
+  - etc.
 
 ## 🔄 Automated Builds
 
-The container is automatically built and published using GitHub Actions:
+The container is built using GitHub Actions with controlled publishing:
 
 ### Build Workflow (`build-devcontainer.yml`)
-- **Triggers**: Push to main branch, PRs, manual dispatch
-- **Features**: Single platform (linux/amd64), intelligent caching, comprehensive validation tests
-- **Publishing**: Multi-tag publishing with `latest`, `main`, `main-<sha>`, and `pr-<number>` tags
+- **PR Triggers**: Pull requests automatically build test images (`pr-<number>` tags) using default VS Code Server commit
+- **Manual Dispatch**: Production builds require manual trigger with VS Code Server commit hash
+  - **Required Input**: VS Code Server commit hash for reproducible builds
+  - **Publishing**: Multi-tag publishing with `latest`, `main`, `vscode-<vscode-commit>`, and SHA-based tags
+- **Features**: Single platform (linux/amd64), intelligent caching, comprehensive validation tests, security scanning
 - **Testing**: Validates Python, Git, Zsh, and Quarto installations
 
+### VS Code Server Version Control
+- Default VS Code Server commit is defined in the `VSCODE_COMMIT` environment variable in `.github/workflows/build-devcontainer.yml`
+- Can be overridden via manual workflow dispatch input for custom builds
+- The VS Code Server commit hash is embedded in container tags for version tracking
+
 ## 📁 Repository Structure
 
 ```
@@ -143,6 +154,8 @@ The build system creates multiple tags from a single build:
 - `main`: Latest commit from main branch
 - `main-<sha>`: Specific commit SHA for reproducible builds
 - `pr-<number>`: Pull request builds for testing changes
+- `vscode-<vscode-commit-sha>`: Builds with specific VS Code Server versions
+- `vscode-<vscode-commit-sha>-<container-sha>`: Complete version specification
 
 ## 🧪 Testing
 
diff --git a/README.md b/README.md
index ad06e5c..73226cb 100644
--- a/README.md
+++ b/README.md
@@ -19,10 +19,10 @@ This dev container is automatically built and published to GitHub Container Regi
   - `main` - Latest build from main branch  
   - `main-<commit-sha>` - Specific commit builds from main branch
   - `pr-<number>` - Pull request builds for testing
-  - `vscode-<vscode-commit-sha>` - Builds with specific VS Code versions
-  - `vscode-<vscode-commit-sha>-<commit-sha>` - Combination of VS Code and git commit
+  - `vscode-<vscode-commit-sha>` - Builds with specific VS Code Server versions
+  - `vscode-<vscode-commit-sha>-<commit-sha>` - Combination of VS Code Server and container commit
 
-**Recommended**: Use `latest` for stable deployments or `main-<commit-sha>` for reproducible builds.
+**Recommended**: Use `latest` for stable deployments or `vscode-<vscode-commit-sha>` for reproducible builds with specific VS Code Server versions.
 
 ## 🚀 Quick Start
 
@@ -59,7 +59,7 @@ This includes:
 
 - [SDF TRE Setup Guide](SDF_TRE_SETUP.md) - Complete setup guide for SDF Trusted Research Environment
 - [Dev Container Details](DEVCONTAINER.md) - Complete documentation about the container
-- [Usage Examples](examples/USAGE.md) - Examples of how to use the published container
+- [Build & Publish Guide](docs/BUILD_PUBLISH_CONTAINER.md) - Guide for building and publishing containers
 - [Dev Container Spec](https://containers.dev) - Learn more about dev containers
 
 ## 🛠️ What's Included
@@ -101,24 +101,37 @@ The container comes with VS Code Server pre-installed for immediate development.
 
 ## Adding New Extensions
 To add new VS Code extensions to the container, follow these steps:
-1. Open the `.devcontainer/vscode-init/vscode-extensions.txt` file.
+1. Open the appropriate file in `.devcontainer/vscode-init/`:
+   - `extensions-to-install.txt` for extensions to install directly
+   - `extensions-to-download.txt` for extensions that need to be downloaded first
 2. Add the identifier of the desired extension in the format `publisher.extensionName` on a new line.
-3. Save the changes to the `vscode-extensions.txt` file.
+3. Save the changes to the extension file.
 4. Commit and push the changes to your repository to trigger the build workflow with the updated extensions
 
 ## 🔄 Automated Builds
 
 The container is built automatically with smart tagging:
 
-- **Main Branch Pushes**: Creates `latest`, `main`, and `main-<commit-sha>` tags
-- **Pull Requests**: Creates `pr-<number>` tags for testing
-- **VS Code Commits**: Creates `vscode-<vscode-commit-sha>` and `vscode-<vscode-commit-sha>-<commit-sha>` tags
-- **Manual Dispatch**: Available for on-demand builds
+- **Pull Requests**: Creates `pr-<number>` tags for testing (uses default VS Code Server commit)
+- **Manual Dispatch**: Creates production tags with custom VS Code Server commit hash
+  - Required input: VS Code Server commit hash
+  - Creates `latest`, `main`, `vscode-<vscode-commit-sha>`, and commit-based tags
 - **Platform**: linux/amd64 optimized for development speed
 
+### Manual Build Process
+
+To create a production build with a specific VS Code Server version:
+
+1. Go to [Actions → Build and Publish Dev Container](../../actions/workflows/build-devcontainer.yml)
+2. Click "Run workflow"
+3. Enter the desired VS Code Server commit hash (required)
+4. Click "Run workflow"
+
+This ensures all published builds use the correct VS Code Server version and prevents automatic builds with mismatched versions.
+
 ### Tag Strategy
 - Use `latest` for the most recent stable release
 - Use `main-<commit-sha>` when you need reproducible builds
 - Use `pr-<number>` tags to test specific pull request changes
-- Use `vscode-<commit-sha>` tags to match specific VS Code versions
-- Use `vscode-<commit-sha>-<container-commit-sha>` tags for a combination of VS Code and git commits
+- Use `vscode-<vscode-commit-sha>` tags to match specific VS Code Server versions
+- Use `vscode-<vscode-commit-sha>-<container-commit-sha>` tags for complete reproducibility (specific VS Code Server + container version)
diff --git a/SDF_TRE_SETUP.md b/SDF_TRE_SETUP.md
index 7033482..ffa43a5 100644
--- a/SDF_TRE_SETUP.md
+++ b/SDF_TRE_SETUP.md
@@ -147,20 +147,20 @@ This approach leverages container technology directly while maintaining the abil
 The container comes with VS Code Server pre-installed and to control the version to match your TRE environment, you can specify the commit hash of the VS Code Server version to use as follows:
 
 1. Check your TRE VS Code version via _Help > About_
-2. Specify the VS Code commit in this repository's `devcontainer.json` file which is used for building the container, not to be confused with TRE workspace settings:
+2. The VS Code commit is defined in this repository's `.github/workflows/build-devcontainer.yml` with support for environment variable substitution, replace `default_commit_hash` with the commit hash you want to use:
 
    ```json
    {
      "build": {
        "dockerfile": "Dockerfile", 
        "args": {
-         "VSCODE_COMMIT": "your_commit_hash_here"
+         "VSCODE_COMMIT": "${localEnv:VSCODE_COMMIT:default_commit_hash}"
        }
      }
    }
    ```
 
-3. This is typically only needed for custom container builds, not when using the published container
+   This allows you to override the VS Code Server version using the `VSCODE_COMMIT` environment variable when building locally.
 
 ## Troubleshooting
 
diff --git a/docs/BUILD_PUBLISH_CONTAINER.md b/docs/BUILD_PUBLISH_CONTAINER.md
index 5cbe51d..5a52348 100644
--- a/docs/BUILD_PUBLISH_CONTAINER.md
+++ b/docs/BUILD_PUBLISH_CONTAINER.md
@@ -91,7 +91,8 @@ For further help, consult the GitHub Actions documentation or reach out to your
 | Use Case | Recommended Tag | Example | Benefits |
 |----------|----------------|---------|----------|
 | **Development** | `latest` | `ghcr.io/smartdatafoundry/devcontainer:latest` | Always up-to-date, stable |
-| **Production/CI** | `main-<sha>` | `ghcr.io/smartdatafoundry/devcontainer:main-abc1234` | Reproducible, immutable |
+| **Production/CI** | `vscode-<vscode-sha>-<sha>` | `ghcr.io/smartdatafoundry/devcontainer:vscode-f220831-abc1234` | Reproducible, immutable, specific VS Code Server |
+| **VS Code Version Match** | `vscode-<vscode-sha>` | `ghcr.io/smartdatafoundry/devcontainer:vscode-f220831` | Match specific VS Code Server version |
 | **Testing PRs** | `pr-<number>` | `ghcr.io/smartdatafoundry/devcontainer:pr-42` | Test specific changes |
 | **Latest Main** | `main` | `ghcr.io/smartdatafoundry/devcontainer:main` | Latest main branch |
 

From 7f838b4fec4ec613c21ac42aa2a9314f37a10325 Mon Sep 17 00:00:00 2001
From: Niall Munro <niall.munro@ed.ac.uk>
Date: Fri, 26 Sep 2025 23:47:55 +0100
Subject: [PATCH 10/15] Update VSCODE_COMMIT argument in devcontainer.json to
 use the latest commit hash

---
 .devcontainer/devcontainer.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
index 093ba91..c3d1d79 100644
--- a/.devcontainer/devcontainer.json
+++ b/.devcontainer/devcontainer.json
@@ -5,7 +5,7 @@
 	"build": {
 		"dockerfile": "Dockerfile",
 		"args": {
-			"VSCODE_COMMIT": "${localEnv:VSCODE_COMMIT:0f0d87fa9e96c856c5212fc86db137ac0d783365}"
+			"VSCODE_COMMIT": "${localEnv:VSCODE_COMMIT:f220831ea2d946c0dcb0f3eaa480eb435a2c1260}"
 		}
 	},
 

From 94d2d45bb360eed248befc97359132b16a9405d9 Mon Sep 17 00:00:00 2001
From: Niall Munro <niall.munro@ed.ac.uk>
Date: Fri, 26 Sep 2025 23:57:22 +0100
Subject: [PATCH 11/15] Remove default VS Code commit hash in build workflow to
 defer control to devontainer.json or manual input

---
 .github/workflows/build-devcontainer.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/build-devcontainer.yml b/.github/workflows/build-devcontainer.yml
index 1d235fd..7532e8a 100644
--- a/.github/workflows/build-devcontainer.yml
+++ b/.github/workflows/build-devcontainer.yml
@@ -18,7 +18,7 @@ env:
   # Set a default VS Code commit hash for tagging purposes
   # This can be overridden via workflow_dispatch input if needed
   # For PRs, the default value will be used
-  VSCODE_COMMIT: ${{ github.event.inputs.vscode_commit || 'f220831ea2d946c0dcb0f3eaa480eb435a2c1260' }}
+  VSCODE_COMMIT: ${{ github.event.inputs.vscode_commit }}
   REGISTRY: ghcr.io
   IMAGE_NAME: ${{ github.repository }}
 

From bd11e40656fcec4d33f7ef7422c3350fc85f122c Mon Sep 17 00:00:00 2001
From: Niall Munro <niall.munro@ed.ac.uk>
Date: Mon, 29 Sep 2025 12:44:06 +0100
Subject: [PATCH 12/15] Add debug step to validate VSCODE_COMMIT input in build
 workflow

---
 .github/workflows/build-devcontainer.yml | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/build-devcontainer.yml b/.github/workflows/build-devcontainer.yml
index 7532e8a..9db2f49 100644
--- a/.github/workflows/build-devcontainer.yml
+++ b/.github/workflows/build-devcontainer.yml
@@ -30,8 +30,19 @@ jobs:
       packages: write        # For publishing container images
       pull-requests: write   # For PR comments from security scan
       actions: write         # For uploading artifacts from security scan
-      
+    
     steps:
+
+      # Write a step to test recieving the VSCODE_COMMIT input and fail
+      - name: Debug VSCODE_COMMIT input
+        run: |
+          echo "Received VSCODE_COMMIT input: '${{ github.event.inputs.vscode_commit }}'"
+          if [ -z "${{ env.VSCODE_COMMIT }}" ]; then
+            echo "❌ VSCODE_COMMIT is not set. Failing the build."
+          else
+            echo "✅ VSCODE_COMMIT is set to '${{ env.VSCODE_COMMIT }}'"
+          fi
+          exit 1
       - name: Checkout repository
         uses: actions/checkout@v4
 

From b16d9bc0124b6a2e40b7f80e45b637655f4b5d2c Mon Sep 17 00:00:00 2001
From: Niall Munro <niall.munro@ed.ac.uk>
Date: Mon, 29 Sep 2025 12:57:48 +0100
Subject: [PATCH 13/15] Set default VSCODE_COMMIT to 'OTHER' if input is not
 provided

---
 .github/workflows/build-devcontainer.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/build-devcontainer.yml b/.github/workflows/build-devcontainer.yml
index 9db2f49..b3058dd 100644
--- a/.github/workflows/build-devcontainer.yml
+++ b/.github/workflows/build-devcontainer.yml
@@ -18,7 +18,7 @@ env:
   # Set a default VS Code commit hash for tagging purposes
   # This can be overridden via workflow_dispatch input if needed
   # For PRs, the default value will be used
-  VSCODE_COMMIT: ${{ github.event.inputs.vscode_commit }}
+  VSCODE_COMMIT: ${{ github.event.inputs.vscode_commit || 'OTHER' }}
   REGISTRY: ghcr.io
   IMAGE_NAME: ${{ github.repository }}
 

From c98899daa8e1514330ea7f3d3607fb9c1993345c Mon Sep 17 00:00:00 2001
From: Niall Munro <niall.munro@ed.ac.uk>
Date: Mon, 29 Sep 2025 22:38:36 +0100
Subject: [PATCH 14/15] Refactor VSCODE_COMMIT handling in Dockerfile and
 workflows for improved clarity and flexibility

---
 .devcontainer/Dockerfile                 |  7 +++-
 .devcontainer/devcontainer.json          |  2 +-
 .github/workflows/build-devcontainer.yml | 49 +++++++++++++-----------
 DEVCONTAINER.md                          | 20 ++++++++--
 4 files changed, 50 insertions(+), 28 deletions(-)

diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
index 436d7e2..43081c9 100644
--- a/.devcontainer/Dockerfile
+++ b/.devcontainer/Dockerfile
@@ -1,7 +1,10 @@
 FROM mcr.microsoft.com/devcontainers/base:noble
 
-# VS Code commit ID for devcontainer compatibility, argument supplied at build time via devcontainer.json
-ARG VSCODE_COMMIT
+# VS Code commit ID for devcontainer compatibility. Can be overridden at build time via build args.
+# Default chosen for current stable VS Code Server version used in this repository.
+ARG VSCODE_COMMIT=f220831ea2d946c0dcb0f3eaa480eb435a2c1260
+
+ENV VSCODE_COMMIT=${VSCODE_COMMIT}
 
 # Copy and run VS Code installation files
 COPY ./vscode-init /opt/vscode-init
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
index c3d1d79..fffe73b 100644
--- a/.devcontainer/devcontainer.json
+++ b/.devcontainer/devcontainer.json
@@ -5,7 +5,7 @@
 	"build": {
 		"dockerfile": "Dockerfile",
 		"args": {
-			"VSCODE_COMMIT": "${localEnv:VSCODE_COMMIT:f220831ea2d946c0dcb0f3eaa480eb435a2c1260}"
+			"VSCODE_COMMIT": "${localEnv:VSCODE_COMMIT}"
 		}
 	},
 
diff --git a/.github/workflows/build-devcontainer.yml b/.github/workflows/build-devcontainer.yml
index b3058dd..4829dd4 100644
--- a/.github/workflows/build-devcontainer.yml
+++ b/.github/workflows/build-devcontainer.yml
@@ -10,15 +10,11 @@ on:
   workflow_dispatch:
     inputs:
       vscode_commit:
-        description: 'VS Code commit hash to use'
-        required: true
+        description: 'VS Code commit hash to use (defaults to Dockerfile ARG default if not provided)'
+        required: false
         type: string
 
 env:
-  # Set a default VS Code commit hash for tagging purposes
-  # This can be overridden via workflow_dispatch input if needed
-  # For PRs, the default value will be used
-  VSCODE_COMMIT: ${{ github.event.inputs.vscode_commit || 'OTHER' }}
   REGISTRY: ghcr.io
   IMAGE_NAME: ${{ github.repository }}
 
@@ -30,30 +26,38 @@ jobs:
       packages: write        # For publishing container images
       pull-requests: write   # For PR comments from security scan
       actions: write         # For uploading artifacts from security scan
-    
-    steps:
 
-      # Write a step to test recieving the VSCODE_COMMIT input and fail
-      - name: Debug VSCODE_COMMIT input
-        run: |
-          echo "Received VSCODE_COMMIT input: '${{ github.event.inputs.vscode_commit }}'"
-          if [ -z "${{ env.VSCODE_COMMIT }}" ]; then
-            echo "❌ VSCODE_COMMIT is not set. Failing the build."
-          else
-            echo "✅ VSCODE_COMMIT is set to '${{ env.VSCODE_COMMIT }}'"
-          fi
-          exit 1
+    steps:
       - name: Checkout repository
         uses: actions/checkout@v4
-
-      - name: Set VSCODE_COMMIT for tagging
+        
+      - name: Resolve VSCODE_COMMIT (input override > Dockerfile default)
         id: vscode-commit
         run: |
-          # For manual dispatch, use the input; for PRs use default value for tagging
-          VSCODE_COMMIT="${{ env.VSCODE_COMMIT }}"
+          # If user provided an input, trust it. Otherwise parse Dockerfile ARG default.
+          if [ -n "${{ github.event.inputs.vscode_commit }}" ]; then
+            VSCODE_COMMIT="${{ github.event.inputs.vscode_commit }}"
+            SOURCE="workflow_input"
+          else
+            # Extract default from ARG line: ARG VSCODE_COMMIT=<hash>
+            VSCODE_COMMIT=$(grep -E '^ARG VSCODE_COMMIT=' .devcontainer/Dockerfile | head -n1 | cut -d= -f2-)
+            if [ -z "$VSCODE_COMMIT" ]; then
+              echo "❌ Could not find default VSCODE_COMMIT in Dockerfile" >&2
+              exit 1
+            fi
+            SOURCE="dockerfile_default"
+          fi
+          # Basic validation (40 hex chars)
+          if ! echo "$VSCODE_COMMIT" | grep -Eq '^[0-9a-f]{40}$'; then
+            echo "❌ VSCODE_COMMIT '$VSCODE_COMMIT' is not a 40-char hex commit hash" >&2
+            exit 1
+          fi
           VSCODE_SHORT=${VSCODE_COMMIT:0:7}
+          echo "Resolved VSCODE_COMMIT=$VSCODE_COMMIT (source=$SOURCE)"
           echo "vscode_commit=$VSCODE_COMMIT" >> $GITHUB_OUTPUT
           echo "vscode_short=$VSCODE_SHORT" >> $GITHUB_OUTPUT
+          echo "source=$SOURCE" >> $GITHUB_OUTPUT
+          echo "Short: $VSCODE_SHORT"
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
@@ -166,6 +170,7 @@ jobs:
           echo "📝 Labels: ${{ steps.meta.outputs.labels }}"
           echo "🔧 VSCode Commit: ${{ steps.vscode-commit.outputs.vscode_commit }}"
           echo "📋 Short Commit: ${{ steps.vscode-commit.outputs.vscode_short }}"
+          echo "🗂️ Source: ${{ steps.vscode-commit.outputs.source }}"
           echo ""
           echo "To use this dev container:"
           echo "1. Reference it in your devcontainer.json:"
diff --git a/DEVCONTAINER.md b/DEVCONTAINER.md
index 259cc6e..9efed9a 100644
--- a/DEVCONTAINER.md
+++ b/DEVCONTAINER.md
@@ -94,9 +94,23 @@ The container is built using GitHub Actions with controlled publishing:
 - **Testing**: Validates Python, Git, Zsh, and Quarto installations
 
 ### VS Code Server Version Control
-- Default VS Code Server commit is defined in the `VSCODE_COMMIT` environment variable in `.github/workflows/build-devcontainer.yml`
-- Can be overridden via manual workflow dispatch input for custom builds
-- The VS Code Server commit hash is embedded in container tags for version tracking
+- Default VS Code Server commit is declared once in the Dockerfile via: `ARG VSCODE_COMMIT=<hash>`
+- Manual workflow dispatch can override this by providing the `vscode_commit` input
+- The workflow extracts the Dockerfile default automatically if no input is provided
+- The commit hash is embedded in container tags: `vscode-<short>` and `vscode-<short>-<container-sha>`
+
+Local override examples:
+
+```bash
+# Use Dockerfile default
+devcontainer build --workspace-folder .
+
+# Override for build
+export VSCODE_COMMIT=0f0d87fa9e96c856c5212fc86db137ac0d783365
+devcontainer build --workspace-folder .
+```
+
+This keeps maintenance simple: update the default by editing a single line in `Dockerfile` with support for overrides when needed via workflow inputs.
 
 ## 📁 Repository Structure
 

From 57e28af985382bd665ebe8290e28b11967a7ee0d Mon Sep 17 00:00:00 2001
From: Niall Munro <niall.munro@ed.ac.uk>
Date: Mon, 29 Sep 2025 23:14:29 +0100
Subject: [PATCH 15/15] Update documentation for Python & R development
 container, enhancing clarity on setup and usage

---
 DEVCONTAINER.md                 |  35 ++++-----
 README.md                       | 126 +++++++++++++++++++-------------
 SDF_TRE_SETUP.md                |  23 ++----
 docs/BUILD_PUBLISH_CONTAINER.md |   6 +-
 4 files changed, 98 insertions(+), 92 deletions(-)

diff --git a/DEVCONTAINER.md b/DEVCONTAINER.md
index 9efed9a..3ad38a9 100644
--- a/DEVCONTAINER.md
+++ b/DEVCONTAINER.md
@@ -1,6 +1,6 @@
-# Dev Container for Python Development
+# Dev Container for Python & R Development
 
-This repository contains a development container configuration optimized for Python development, along with automated workflows to build and publish the container image to GitHub Container Registry (GHCR).
+This repository contains a development container configuration optimized for Python (and first-class R) development, along with automated workflows to build and publish the container image to GitHub Container Registry (GHCR). For high-level usage see `README.md`; this document focuses on implementation details.
 
 ## 📦 Published Container
 
@@ -66,20 +66,15 @@ docker run --rm -it -v $(pwd):/workspace ghcr.io/smartdatafoundry/devcontainer:l
 
 This dev container includes:
 
-- **Base**: Ubuntu Noble (24.04) via Microsoft's `mcr.microsoft.com/devcontainers/base:noble`
-- **Python**: System Python with pip and development tools (via devcontainer feature)
-- **Git**: Latest version with configuration support
-- **Shell**: Zsh with Oh My Zsh configuration (via common-utils feature)
-- **Quarto**: For document publishing and data science workflows (latest version)
-- **Marimo**: Markdown presentation tool, alternative to Jupyter Notebooks (latest version)
-- **VS Code Server**: Pre-installed for immediate development
-- **VS Code Extensions**:
-  - Continue (AI assistant)
-  - Black formatter for Python
-  - Jupyter support
-  - Markdown All in One
-  - Rainbow CSV
-  - etc.
+* **Base**: Ubuntu Noble (24.04) via Microsoft's `mcr.microsoft.com/devcontainers/base:noble`
+* **Python**: System Python with pip and development tools (via feature)
+* **R**: Installed via Rocker devcontainer feature (languageserver, httpgd, rmarkdown, renv, devtools, radian, vscDebugger)
+* **Git**: Latest stable
+* **Shell**: Zsh + Oh My Zsh (via common-utils feature)
+* **Quarto**: Latest (document publishing)
+* **Marimo**: Alternative interactive notebook/presentation tool
+* **VS Code Server**: Pre-installed (pin via tag families)
+* **VS Code Extensions**: Curated list (see `.devcontainer/vscode-init/extensions-to-install.txt`)
 
 ## 🔄 Automated Builds
 
@@ -97,7 +92,7 @@ The container is built using GitHub Actions with controlled publishing:
 - Default VS Code Server commit is declared once in the Dockerfile via: `ARG VSCODE_COMMIT=<hash>`
 - Manual workflow dispatch can override this by providing the `vscode_commit` input
 - The workflow extracts the Dockerfile default automatically if no input is provided
-- The commit hash is embedded in container tags: `vscode-<short>` and `vscode-<short>-<container-sha>`
+- The commit hash is embedded in container tags: `vscode-<short>` and `vscode-<short>-<branch-sha>`
 
 Local override examples:
 
@@ -131,7 +126,7 @@ This keeps maintenance simple: update the default by editing a single line in `D
 ├── docs/                          # Additional documentation
 ├── DEVCONTAINER.md                # Detailed documentation
 ├── README.md                      # Overview and quick start
-└── SDF_TRE_SETUP.md              # SDF TRE setup guide
+└── SDF_TRE_SETUP.md               # SDF TRE setup guide
 ```
 
 ## 🔧 Customization
@@ -169,7 +164,7 @@ The build system creates multiple tags from a single build:
 - `main-<sha>`: Specific commit SHA for reproducible builds
 - `pr-<number>`: Pull request builds for testing changes
 - `vscode-<vscode-commit-sha>`: Builds with specific VS Code Server versions
-- `vscode-<vscode-commit-sha>-<container-sha>`: Complete version specification
+- `vscode-<vscode-commit-sha>-<branch-sha>`: Complete version specification
 
 ## 🧪 Testing
 
@@ -198,7 +193,7 @@ The GitHub Action will automatically test your changes when you submit a PR.
 
 ## 📝 License
 
-This project is open source and available under the [MIT License](LICENSE).
+Licensed under [MIT](LICENSE).
 
 ---
 
diff --git a/README.md b/README.md
index 73226cb..8ea8c95 100644
--- a/README.md
+++ b/README.md
@@ -4,25 +4,41 @@
 
 # devcontainer
 
-Container to support Python development that comes with baked in support for the Visual Studio Code Dev Container extension, additionally includes supporting tooling and a rich set of IDE extensions.
+Development container focused on Python (with first-class R support) providing a reproducible, batteries‑included environment. It ships with the VS Code Dev Containers extension assets, curated tooling, and a consistent tagging strategy for deterministic rebuilds.
+
+## Table of Contents
+1. Published Container
+2. Quick Start
+3. Using in SDF TRE
+4. Documentation
+5. What's Included
+6. R Language Support
+7. VS Code Server
+8. Adding Extensions
+9. Automated Builds & Tag Strategy
+10. Contributing
+11. License
 
 [![Build and Publish Dev Container](https://github.com/smartdatafoundry/devcontainer/actions/workflows/build-devcontainer.yml/badge.svg)](https://github.com/smartdatafoundry/devcontainer/actions/workflows/build-devcontainer.yml)
 
 ## 📦 Published Container
 
-This dev container is automatically built and published to GitHub Container Registry with multiple tags:
+Built and published automatically to GitHub Container Registry (GHCR):
 
-- **Registry**: GitHub Container Registry (GHCR)  
-- **Base Image**: `ghcr.io/smartdatafoundry/devcontainer`
-- **Available Tags**:
-  - `latest` - Latest stable build from main branch
-  - `main` - Latest build from main branch  
-  - `main-<commit-sha>` - Specific commit builds from main branch
-  - `pr-<number>` - Pull request builds for testing
-  - `vscode-<vscode-commit-sha>` - Builds with specific VS Code Server versions
-  - `vscode-<vscode-commit-sha>-<commit-sha>` - Combination of VS Code Server and container commit
+* **Registry**: `ghcr.io`
+* **Image**: `ghcr.io/smartdatafoundry/devcontainer`
+* **Tag Families**:
+  * `latest` – Most recent stable main build
+  * `main` – Moving pointer to HEAD of main
+  * `main-<branch-sha>` – Immutable build for a specific main commit
+  * `pr-<number>` – Ephemeral preview for a pull request
+  * `vscode-<vscode-sha>` – Locks VS Code Server version (container content may still move)
+  * `vscode-<vscode-sha>-<branch-sha>` – Fully reproducible (VS Code Server + container commit)
 
-**Recommended**: Use `latest` for stable deployments or `vscode-<vscode-commit-sha>` for reproducible builds with specific VS Code Server versions.
+Recommended:
+* Daily development: `latest`
+* CI / Reproducibility: `vscode-<vscode-sha>-<branch-sha>`
+* VS Code Server pin only: `vscode-<vscode-sha>`
 
 ## 🚀 Quick Start
 
@@ -39,15 +55,11 @@ Add this to your `.devcontainer/devcontainer.json`:
 
 ### Using in SDF Trusted Research Environment
 
-For detailed instructions on setting up and using this dev container within the SDF Trusted Research Environment, see:
-
-**[📋 SDF TRE Setup Guide](SDF_TRE_SETUP.md)**
-
-This includes:
-- Manual Dev Containers extension installation
-- TRE-specific configuration requirements
-- Proxy and network setup
-- Troubleshooting TRE-specific issues
+See the **[SDF TRE Setup Guide](SDF_TRE_SETUP.md)** for:
+* Manual Dev Containers extension install & extraction
+* Podman configuration
+* Proxy / network specifics
+* Troubleshooting in constrained environments
 
 ### Using This Repository Directly
 
@@ -57,10 +69,12 @@ This includes:
 
 ## 📚 Documentation
 
-- [SDF TRE Setup Guide](SDF_TRE_SETUP.md) - Complete setup guide for SDF Trusted Research Environment
-- [Dev Container Details](DEVCONTAINER.md) - Complete documentation about the container
-- [Build & Publish Guide](docs/BUILD_PUBLISH_CONTAINER.md) - Guide for building and publishing containers
-- [Dev Container Spec](https://containers.dev) - Learn more about dev containers
+| Topic | Reference |
+|-------|-----------|
+| SDF TRE usage | `SDF_TRE_SETUP.md` |
+| Full container internals | `DEVCONTAINER.md` |
+| Reusable publish workflow | `docs/BUILD_PUBLISH_CONTAINER.md` |
+| Dev Container Specification | https://containers.dev |
 
 ## 🛠️ What's Included
 
@@ -71,13 +85,14 @@ This includes:
 - **Shell**: Zsh with Oh My Zsh (via common-utils feature)
 - **Quarto**: Document publishing platform (latest version)
 - **Marimo**: Markdown presentation tool, alternative to Jupyter Notebooks
-- **VS Code Extensions**:
-  - Continue (AI coding assistant)
-  - Python Black formatter
-  - Jupyter notebook support
+- **VS Code Extensions (curated)**:
+  - Continue (AI assistant)
+  - Black (Python formatting)
+  - Jupyter
   - Marimo
   - Markdown All in One
   - Rainbow CSV
+  - (See `.devcontainer/vscode-init/extensions-to-install.txt` for authoritative list)
 - **VS Code Server**: Pre-installed for immediate development
 
 ## 📊 R Language Support
@@ -97,41 +112,50 @@ This dev container includes comprehensive R language support through the [Rocker
 
 ## ⚙️ VS Code Server
 
-The container comes with VS Code Server pre-installed for immediate development. For TRE-specific VS Code Server configuration, see the [SDF TRE Setup Guide](SDF_TRE_SETUP.md).
+Pre-installed. Pin a version using the tag families described above or via build arg `VSCODE_COMMIT`. For environment-specific considerations (e.g. TRE) see `SDF_TRE_SETUP.md`.
 
 ## Adding New Extensions
 To add new VS Code extensions to the container, follow these steps:
 1. Open the appropriate file in `.devcontainer/vscode-init/`:
    - `extensions-to-install.txt` for extensions to install directly
-   - `extensions-to-download.txt` for extensions that need to be downloaded first
+   - `extensions-to-download.txt` for extensions that need to be downloaded
 2. Add the identifier of the desired extension in the format `publisher.extensionName` on a new line.
 3. Save the changes to the extension file.
 4. Commit and push the changes to your repository to trigger the build workflow with the updated extensions
 
-## 🔄 Automated Builds
+## 🔄 Automated Builds & Tag Strategy
+
+Workflow: `.github/workflows/build-devcontainer.yml`
+
+Triggers:
+* Pull Requests touching devcontainer/workflow files → build + `pr-<number>` tag
+* Manual dispatch (with required `vscode_commit` input) → publish full tag set
+
+Outputs per production run:
+* `latest`, `main`, `main-<branch-sha>`
+* `vscode-<vscode-sha>`, `vscode-<vscode-sha>-<branch-sha>`
 
-The container is built automatically with smart tagging:
+Manual build steps:
+1. Open Actions → Build and Publish Dev Container
+2. Run workflow, supplying VS Code Server commit hash
+3. Await completion & verify tags on GHCR package page
 
-- **Pull Requests**: Creates `pr-<number>` tags for testing (uses default VS Code Server commit)
-- **Manual Dispatch**: Creates production tags with custom VS Code Server commit hash
-  - Required input: VS Code Server commit hash
-  - Creates `latest`, `main`, `vscode-<vscode-commit-sha>`, and commit-based tags
-- **Platform**: linux/amd64 optimized for development speed
+Tag usage quick reference:
+| Need | Tag |
+|------|-----|
+| Stable rolling | `latest` |
+| Immutable main snapshot | `main-<sha>` |
+| Test PR | `pr-<number>` |
+| Pin VS Code Server only | `vscode-<vscode-sha>` |
+| Full reproducibility | `vscode-<vscode-sha>-<sha>` |
 
-### Manual Build Process
+Reusable generic Docker workflow documentation: see `docs/BUILD_PUBLISH_CONTAINER.md`.
 
-To create a production build with a specific VS Code Server version:
+---
+## 🤝 Contributing & License
 
-1. Go to [Actions → Build and Publish Dev Container](../../actions/workflows/build-devcontainer.yml)
-2. Click "Run workflow"
-3. Enter the desired VS Code Server commit hash (required)
-4. Click "Run workflow"
+Contribution workflow is standard GitHub Flow. See section above plus open issues for opportunities.
 
-This ensures all published builds use the correct VS Code Server version and prevents automatic builds with mismatched versions.
+License: [MIT](LICENSE)
 
-### Tag Strategy
-- Use `latest` for the most recent stable release
-- Use `main-<commit-sha>` when you need reproducible builds
-- Use `pr-<number>` tags to test specific pull request changes
-- Use `vscode-<vscode-commit-sha>` tags to match specific VS Code Server versions
-- Use `vscode-<vscode-commit-sha>-<container-commit-sha>` tags for complete reproducibility (specific VS Code Server + container version)
+---
diff --git a/SDF_TRE_SETUP.md b/SDF_TRE_SETUP.md
index ffa43a5..4dbee9c 100644
--- a/SDF_TRE_SETUP.md
+++ b/SDF_TRE_SETUP.md
@@ -6,8 +6,8 @@ This guide provides step-by-step instructions for setting up and using dev conta
 
 The quick start is for users familiar with the TRE and using Dev Containers. If you haven't done this setup before, please read the rest of this document instead of the quick start.
 
-1. Pull the `devcontainer image`
-2. Install the Dev Containers extension
+1. Pull the devcontainer image
+2. Extract and install the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
 3. Create your project directory
 4. Add project config file `.devcontainer/devcontainer.json`
 5. Open the project in VS Code
@@ -45,7 +45,7 @@ ces-pull a a ghcr.io/smartdatafoundry/devcontainer:latest
 
 ### 2. Extract the Dev Containers Extension
 
-The extension is baked into the container image. Extract it using:
+The Dev Containers extension VSIX is baked into the image for offline / restricted environments. Extract it:
 
 ```bash
 podman run --rm -it \
@@ -144,23 +144,10 @@ This approach leverages container technology directly while maintaining the abil
 
 ### VS Code Server Version Management
 
-The container comes with VS Code Server pre-installed and to control the version to match your TRE environment, you can specify the commit hash of the VS Code Server version to use as follows:
+The container ships with VS Code Server pre-installed. To ensure reproducibility or to match an existing TRE host version, specify the commit hash:
 
 1. Check your TRE VS Code version via _Help > About_
-2. The VS Code commit is defined in this repository's `.github/workflows/build-devcontainer.yml` with support for environment variable substitution, replace `default_commit_hash` with the commit hash you want to use:
-
-   ```json
-   {
-     "build": {
-       "dockerfile": "Dockerfile", 
-       "args": {
-         "VSCODE_COMMIT": "${localEnv:VSCODE_COMMIT:default_commit_hash}"
-       }
-     }
-   }
-   ```
-
-   This allows you to override the VS Code Server version using the `VSCODE_COMMIT` environment variable when building locally.
+2. The VS Code commit  value is declared in the `Dockerfile`  and can be overriden via workflow inputs.
 
 ## Troubleshooting
 
diff --git a/docs/BUILD_PUBLISH_CONTAINER.md b/docs/BUILD_PUBLISH_CONTAINER.md
index 5a52348..dc6583d 100644
--- a/docs/BUILD_PUBLISH_CONTAINER.md
+++ b/docs/BUILD_PUBLISH_CONTAINER.md
@@ -22,7 +22,7 @@ on:
 
 jobs:
   publish:
-    uses: smartdatafoundry/devcontainer/.github/workflows/build-publish-container.yml@v1.0.0
+  uses: smartdatafoundry/devcontainer/.github/workflows/build-publish-container.yml@v1.0.0
     with:
       dockerfile: Dockerfile # Optional, defaults to 'Dockerfile'
       image-name: ${{ github.repository }} # Optional, defaults to repo name
@@ -91,11 +91,11 @@ For further help, consult the GitHub Actions documentation or reach out to your
 | Use Case | Recommended Tag | Example | Benefits |
 |----------|----------------|---------|----------|
 | **Development** | `latest` | `ghcr.io/smartdatafoundry/devcontainer:latest` | Always up-to-date, stable |
-| **Production/CI** | `vscode-<vscode-sha>-<sha>` | `ghcr.io/smartdatafoundry/devcontainer:vscode-f220831-abc1234` | Reproducible, immutable, specific VS Code Server |
+| **Production/CI** | `vscode-<vscode-sha>-<branch-sha>` | `ghcr.io/smartdatafoundry/devcontainer:vscode-f220831-abc1234` | Reproducible, immutable, specific VS Code Server + container commit |
 | **VS Code Version Match** | `vscode-<vscode-sha>` | `ghcr.io/smartdatafoundry/devcontainer:vscode-f220831` | Match specific VS Code Server version |
 | **Testing PRs** | `pr-<number>` | `ghcr.io/smartdatafoundry/devcontainer:pr-42` | Test specific changes |
 | **Latest Main** | `main` | `ghcr.io/smartdatafoundry/devcontainer:main` | Latest main branch |
 
 ### Finding Available Tags
 
-Visit the [GitHub Container Registry page](https://github.com/smartdatafoundry/devcontainer/pkgs/container/devcontainer) to see all available tags and their creation dates.
+Visit the [GitHub Container Registry page](https://github.com/smartdatafoundry/devcontainer/pkgs/container/devcontainer) to see available tags and creation dates. See also high-level tag usage guidance in the top-level `README.md`.