feat(ci): Ensure that the README.md is in sync with internal/readme

.github/workflows/readme-check.yml

@@ -0,0 +1,38 @@
+name: README Check
+on:
+  workflow_dispatch:  
+  pull_request:
+    paths:
+      - 'internal/readme/**'
+      - 'README.md'
+
+permissions:
+  contents: read
+
+jobs:
+  readme-check:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Set up Go
+      uses: actions/setup-go@v5
+    - name: Check out code
+      uses: actions/checkout@v4
+    - name: Check README is up-to-date
+      run: |
+        cd internal/readme
+        make
+        if [ -n "$(git status --porcelain)" ]; then
+          echo "ERROR: README.md is not up-to-date!"
+          echo ""
+          echo "The README.md file differs from what would be generated by running 'make' in internal/readme/."
+          echo "Please update internal/readme/README.src.md instead of README.md directly,"
+          echo "then run 'make' in the internal/readme/ directory to regenerate README.md."
+          echo ""
+          echo "Changes:"
+          git status --porcelain
+          echo ""
+          echo "Diff:"
+          git diff
+          exit 1
+        fi
+        echo "README.md is up-to-date"

CONTRIBUTING.md

@@ -105,6 +105,19 @@ copyright header following the format below:
 // license that can be found in the LICENSE file.
 ```
 
+### Updating the README
+
+The top-level `README.md` file is generated from `internal/readme/README.src.md`
+and should not be edited directly. To update the README:
+
+1. Make your changes to `internal/readme/README.src.md`
+2. Run `make` in the `internal/readme/` directory to regenerate `README.md`
+3. Commit both files together
+
+The CI system will automatically check that the README is up-to-date by running
+`make` and verifying no changes result. If you see a CI failure about the
+README being out of sync, follow the steps above to regenerate it.
+
 ## Code of conduct
 
 This project follows the [Go Community Code of Conduct](https://go.dev/conduct).