diff --git a/cli/examples/setup-project.sh b/cli/examples/setup-project.sh
index a8c68c8b..72b03a05 100755
--- a/cli/examples/setup-project.sh
+++ b/cli/examples/setup-project.sh
@@ -90,4 +90,4 @@ echo "  3. Sync with Moodle: aws sync --download"
 echo "  4. Batch mark: aws batch ./submissions"
 echo ""
 echo "For help: aws --help"
-echo "Documentation: cat README.md"
+echo "Documentation: cat README.adoc"
diff --git a/release/scripts/package.sh b/release/scripts/package.sh
index 39c0633f..25fa53bf 100755
--- a/release/scripts/package.sh
+++ b/release/scripts/package.sh
@@ -156,7 +156,7 @@ build_deb() {
     fi
 
     # Copy documentation
-    cp "$PROJECT_ROOT/README.md" "${pkg_dir}/usr/share/doc/${pkg_name}/" 2>/dev/null || true
+    cp "$PROJECT_ROOT/README.adoc" "${pkg_dir}/usr/share/doc/${pkg_name}/"
     cp "$PROJECT_ROOT/LICENSE" "${pkg_dir}/usr/share/doc/${pkg_name}/" 2>/dev/null || true
 
     # Build package
diff --git a/release/scripts/version.sh b/release/scripts/version.sh
index 24f12f52..0f20251e 100755
--- a/release/scripts/version.sh
+++ b/release/scripts/version.sh
@@ -154,11 +154,17 @@ update_python_version() {
 update_documentation() {
     local version=$1
 
-    # Update README.md
-    if [ -f "$PROJECT_ROOT/README.md" ]; then
+    # Update README.adoc
+    if [ -f "$PROJECT_ROOT/README.adoc" ]; then
         # Update badge version if exists
-        sed -i "s/version-[0-9.]*-/version-$version-/" "$PROJECT_ROOT/README.md" 2>/dev/null || true
-        log_success "Updated README.md"
+        # Do NOT mask this: a silently-failed badge update ships a release
+        # advertising the wrong version, and nothing surfaces it.
+        if sed -i "s/version-[0-9.]*-/version-$version-/" "$PROJECT_ROOT/README.adoc"; then
+            log_success "Updated README.adoc"
+        else
+            log_error "Failed to update the version badge in README.adoc"
+            exit 1
+        fi
     fi
 
     # Update CLAUDE.md
diff --git a/release/verify/verify_release.sh b/release/verify/verify_release.sh
index d5f6a076..bbaf1cf2 100755
--- a/release/verify/verify_release.sh
+++ b/release/verify/verify_release.sh
@@ -154,7 +154,7 @@ check_archive_contents() {
 
     # Check for essential files
     local essential_files=(
-        "README.md"
+        "README.adoc"
         "LICENSE"
     )
 
diff --git a/scripts/ci/package.sh b/scripts/ci/package.sh
index 4b3e2216..032e18a4 100755
--- a/scripts/ci/package.sh
+++ b/scripts/ci/package.sh
@@ -79,9 +79,7 @@ package_deb() {
     fi
 
     # Copy documentation
-    if [ -f "${ROOT_DIR}/README.md" ]; then
-        cp "${ROOT_DIR}/README.md" "${deb_dir}/usr/share/doc/${package_name}/"
-    fi
+    cp "${ROOT_DIR}/README.adoc" "${deb_dir}/usr/share/doc/${package_name}/"
 
     if [ -f "${ROOT_DIR}/LICENSE" ]; then
         cp "${ROOT_DIR}/LICENSE" "${deb_dir}/usr/share/doc/${package_name}/"
diff --git a/scripts/ci/test-integration.sh b/scripts/ci/test-integration.sh
index 1ba9c95d..ad053bfe 100755
--- a/scripts/ci/test-integration.sh
+++ b/scripts/ci/test-integration.sh
@@ -226,7 +226,7 @@ test_configuration_files() {
 test_documentation() {
     log_info "Testing documentation..."
 
-    local required_docs=("README.md" "CLAUDE.md")
+    local required_docs=("README.adoc" "CLAUDE.md")
 
     for doc in "${required_docs[@]}"; do
         if [ ! -f "${ROOT_DIR}/${doc}" ]; then