Add revalidating cache headers to docs publish

Author: rupurt

scripts/publish-docs.sh

@@ -45,8 +45,11 @@ sync_build() {
     return 0
   fi
 
-  echo "Syncing docs build to s3://$preview_bucket/$prefix"
-  aws s3 sync "$docs_root/build/" "s3://$preview_bucket/$prefix" --delete
+  local destination="s3://$preview_bucket/$prefix"
+  echo "Uploading docs build to $destination with Cache-Control: no-cache"
+  aws s3 cp "$docs_root/build/" "$destination" --recursive --cache-control "no-cache"
+  echo "Removing stale docs objects from $destination"
+  aws s3 sync "$docs_root/build/" "$destination" --delete
 }
 
 if [[ ! -f "$docs_root/package.json" ]]; then

website/README.md

@@ -25,7 +25,9 @@ For production publication, the repository-owned
 preferred lane. It publishes the stable Keel site plus the `main` preview into
 the shared `spoke-previews` bucket through the infra-managed OIDC role. The
 checked-in [`publish-docs.sh`](../scripts/publish-docs.sh) script is the local
-repair and CI execution surface for that contract.
+repair and CI execution surface for that contract. Published docs objects use
+`Cache-Control: no-cache` so browsers revalidate with `ETag` and
+`Last-Modified`.
 
 ## Deployment Inputs