feat: add auto modification to docs files on reference frontmatter changes

this is a stage one for the pipeline of modifying underlying docs files after a detected change in the frontmatter

in stage one, the diff is only sent to slack and is not actually applied

please note that this will require the addition of claude and api keys to the ci workflow

requirements
claude (Claude Code CLI) - needs to be installed in CI runner
ANTHROPIC_API_KEY
SLACK_BOT_TOKEN

Author: sklppy88

.github/workflows/ci3.yml

@@ -73,6 +73,8 @@ jobs:
           DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
           SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
+          # For automatic documentation updates via Claude Code
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
           # Nightly test env vars.
           EXTERNAL_ETHEREUM_HOSTS: "https://json-rpc.${{ secrets.GCP_SEPOLIA_URL }}?key=${{ secrets.GCP_SEPOLIA_API_KEY }},${{ secrets.INFURA_SEPOLIA_URL }}"
           EXTERNAL_ETHEREUM_CONSENSUS_HOST: "https://beacon.${{ secrets.GCP_SEPOLIA_URL }}"

docs/README.md

@@ -487,6 +487,57 @@ When documentation references source code files, the CI system can automatically
 - For individual files: `"path/to/file.ts"`
 - For directories (all files within): `"path/to/directory/*"`
 
+### Automatic Documentation Update Notifications
+
+Building on the DevRel review automation, the docs CI can analyze PRs and notify the team when documentation updates may be needed.
+
+**How it works:**
+
+1. **Detection**: When a PR modifies files that are referenced in documentation (via the `references` frontmatter), the system detects which docs may need updates.
+
+2. **AI Analysis**: The system uses Claude Code to:
+   - Analyze the code changes (diffs) in the PR
+   - Review the affected documentation files
+   - Determine if documentation updates are needed
+   - Generate suggested documentation changes
+
+3. **Slack Notification**: If documentation updates are suggested:
+   - A message is sent to the configured Slack channel (default: `#devrel`)
+   - The message includes the PR details, affected docs, and suggested changes
+   - The DevRel team can review and apply the changes manually
+
+**Requirements**:
+- `ANTHROPIC_API_KEY` must be set in CI secrets
+- `SLACK_BOT_TOKEN` must be set for Slack notifications
+- Claude Code CLI must be installed (`@anthropic-ai/claude-code`)
+- The PR must not be a draft
+
+**Environment Variables**:
+- `SLACK_DOC_UPDATE_CHANNEL` - Slack channel for notifications (default: `#devrel`)
+- `DRY_RUN=1` - Skip Slack notification, just print what would be sent
+
+**Implementation**: The automation is handled by `scripts/update_doc_references.sh`, which runs as part of the docs CI pipeline after `check_doc_references.sh`.
+
+**Script Architecture**:
+- `scripts/update_doc_references.sh` - Main script that orchestrates the workflow
+- `scripts/lib/extract_doc_references.sh` - Shared library for parsing frontmatter references
+- `scripts/lib/create_doc_update_pr.sh` - (Reserved for future use) PR creation logic
+- `scripts/test_update_doc_references.sh` - Local testing helper
+
+**Local Testing**:
+```bash
+# Find a PR with referenced file changes and test
+./scripts/test_update_doc_references.sh
+
+# Test against a specific PR
+LOCAL_TEST=1 DRY_RUN=1 ./scripts/update_doc_references.sh 19803
+```
+
+**Limitations**:
+- Only analyzes documentation in the source folders (`docs-developers/`, `docs-network/`), not versioned docs
+- Suggested changes should always be reviewed by a human before applying
+- The AI may occasionally suggest unnecessary or incorrect changes
+
 ## Contributing
 
 We welcome contributions from the community. Please review our [contribution guidelines](CONTRIBUTING.md) for more information.

docs/bootstrap.sh

@@ -55,6 +55,17 @@ function check_references {
   ./scripts/check_doc_references.sh docs
 }
 
+function update_doc_references {
+  echo_header "Auto-update doc references"
+  # Only run if Claude Code CLI is available
+  if command -v claude &> /dev/null; then
+    ./scripts/update_doc_references.sh docs
+  else
+    echo "Claude Code CLI not available. Skipping automatic doc updates."
+    echo "To enable automatic doc updates, install Claude Code: npm install -g @anthropic-ai/claude-code"
+  fi
+}
+
 function build_examples {
   echo_header "Building examples"
   (cd examples && ./bootstrap.sh "$@")
@@ -66,6 +77,7 @@ case "$cmd" in
     build_docs
     test
     check_references
+    update_doc_references
     ;;
   "")
     build_examples

docs/scripts/lib/create_doc_update_pr.sh

@@ -0,0 +1,156 @@
+#!/usr/bin/env bash
+# create_doc_update_pr.sh - Create a PR with documentation updates
+#
+# This script is extracted from update_doc_references.sh for future use.
+# It handles:
+# - Creating a branch for doc updates
+# - Committing changes
+# - Pushing to remote
+# - Creating/updating a PR
+# - Commenting on the original PR
+#
+# Usage: source this file and call create_doc_update_pr
+#
+# Required variables (must be set before calling):
+#   PR_NUMBER - Original PR number
+#   PR_TITLE - Original PR title
+#   PR_URL - Original PR URL
+#   PR_AUTHOR - Original PR author
+#   BASE_BRANCH - Base branch name
+#   MODIFIED_FILES - List of modified doc files
+#   FILE_TO_DOCS_MAP - Associative array of source files to doc files
+#
+# Optional variables:
+#   DRY_RUN - Set to 1 to skip PR creation
+
+create_doc_update_pr() {
+  local pr_number="$1"
+  local pr_title="$2"
+  local pr_url="$3"
+  local pr_author="$4"
+  local base_branch="$5"
+  local modified_files="$6"
+
+  local doc_update_branch="docs/auto-update-pr-${pr_number}"
+  local original_ref=$(git rev-parse HEAD)
+  local original_branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+
+  echo "Creating documentation update branch: $doc_update_branch"
+
+  # Configure git for CI (needed for commits)
+  git config user.email "[email protected]"
+  git config user.name "Aztec Bot"
+
+  # Check if branch already exists on remote (from a previous run)
+  if git ls-remote --exit-code --heads origin "$doc_update_branch" &>/dev/null; then
+    echo "Remote branch $doc_update_branch already exists. Will update it..."
+    git fetch origin "$doc_update_branch" 2>/dev/null || true
+  fi
+
+  # Delete local branch if it exists
+  git branch -D "$doc_update_branch" 2>/dev/null || true
+
+  # Create the new branch from the base branch
+  git checkout -b "$doc_update_branch" "origin/$base_branch"
+
+  # Stage and commit the changes
+  echo "Committing documentation updates..."
+
+  git add -A
+  git commit -m "docs: auto-update documentation for PR #$pr_number
+
+This commit contains automatic documentation updates generated by Claude Code
+in response to code changes in PR #$pr_number.
+
+Original PR: $pr_url
+
+The following documentation files were updated based on changes to their
+referenced source files:
+
+$(echo "$modified_files" | sed 's/^/- /')
+
+Co-Authored-By: Claude Opus 4.5 <[email protected]>"
+
+  # Check for dry run mode
+  if [[ "${DRY_RUN:-0}" == "1" ]]; then
+    echo ""
+    echo "DRY_RUN mode: Skipping PR creation."
+    echo "Changes committed to branch: $doc_update_branch"
+    git checkout "$original_ref" 2>/dev/null || git checkout "$original_branch" 2>/dev/null || true
+    return 0
+  fi
+
+  # Push the branch
+  echo "Pushing branch to origin..."
+  git push -u origin "$doc_update_branch" --force
+
+  # Create the PR
+  echo "Creating pull request..."
+
+  local pr_body=$(cat << EOF
+## Summary
+
+This PR contains automatic documentation updates generated by Claude Code in response to code changes.
+
+### Original PR
+- **PR:** #$pr_number
+- **Title:** $pr_title
+- **Author:** @$pr_author
+- **URL:** $pr_url
+
+### Documentation Updates
+
+The following documentation files were updated based on changes to their referenced source files:
+
+$(echo "$modified_files" | sed 's/^/- `/' | sed 's/$/`/')
+
+---
+
+> **Note:** This PR was automatically generated. Please review the changes carefully before merging.
+
+Generated with [Claude Code](https://claude.ai/code)
+EOF
+)
+
+  # Check if a PR already exists for this branch
+  local existing_pr=$(gh pr list --head "$doc_update_branch" --json number --jq '.[0].number' 2>/dev/null || echo "")
+  local doc_pr_url=""
+
+  if [[ -n "$existing_pr" ]]; then
+    echo "Updating existing PR #$existing_pr..."
+    gh pr edit "$existing_pr" --body "$pr_body"
+    doc_pr_url=$(gh pr view "$existing_pr" --json url -q .url)
+  else
+    doc_pr_url=$(gh pr create \
+      --title "docs: auto-update for PR #$pr_number - $pr_title" \
+      --body "$pr_body" \
+      --base "$base_branch" \
+      --head "$doc_update_branch" \
+      --label "documentation" \
+      --label "auto-generated" 2>/dev/null || echo "")
+  fi
+
+  if [[ -n "$doc_pr_url" ]]; then
+    echo ""
+    echo "Documentation update PR created successfully!"
+    echo "  URL: $doc_pr_url"
+
+    # Add a comment to the original PR linking to the docs PR
+    local link_comment="**Automatic Documentation Update**
+
+A documentation update PR has been created in response to code changes in this PR:
+
+**Documentation PR:** $doc_pr_url
+
+Please review the documentation changes and merge them after this PR is merged."
+
+    gh pr comment "$pr_number" --body "$link_comment" 2>/dev/null || echo "Warning: Could not add comment to original PR"
+  else
+    echo "Warning: Could not create documentation update PR"
+  fi
+
+  # Return to original ref/branch
+  git checkout "$original_ref" 2>/dev/null || git checkout "$original_branch" 2>/dev/null || true
+
+  echo "$doc_pr_url"
+}

docs/scripts/lib/extract_doc_references.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+# extract_doc_references.sh - Shared functions for extracting doc references
+#
+# This library provides reusable functions for extracting references from
+# documentation frontmatter.
+#
+# Usage: source this file and call the functions
+
+# Extract references from markdown frontmatter and build a mapping file
+# Arguments:
+#   $1 - docs_dir: The documentation directory (e.g., "docs")
+#   $2 - output_file: Path to write the mapping (format: "ref_file|doc_file")
+extract_references_mapping() {
+  local docs_dir="$1"
+  local output_file="$2"
+
+  # Clear output file
+  > "$output_file"
+
+  # Scan docs-developers and docs-network subdirectories
+  for docs_subdir in docs-developers docs-network; do
+    if [[ -d "$docs_dir/$docs_subdir/docs" ]]; then
+      _extract_from_directory "$docs_dir/$docs_subdir/docs" "$output_file"
+    fi
+  done
+
+  # Also scan main docs folder if it exists
+  if [[ -d "$docs_dir/docs" ]]; then
+    _extract_from_directory "$docs_dir/docs" "$output_file"
+  fi
+}
+
+# Internal function to extract references from a directory
+_extract_from_directory() {
+  local search_dir="$1"
+  local output_file="$2"
+
+  find "$search_dir" -type f -name "*.md" -print0 | while IFS= read -r -d '' doc_file; do
+    awk -v doc="$doc_file" '
+      BEGIN { in_frontmatter = 0 }
+      /^---$/ {
+        if (NR == 1) {
+          in_frontmatter = 1
+        } else if (in_frontmatter) {
+          in_frontmatter = 0
+        }
+        next
+      }
+      in_frontmatter && /^references:/ {
+        if (match($0, /\[.*\]/)) {
+          refs = substr($0, RSTART, RLENGTH)
+          gsub(/[\[\]"'\''"]/, "", refs)
+          split(refs, arr, /,[ ]*/)
+          for (i in arr) {
+            if (arr[i] != "") {
+              print arr[i] "|" doc
+            }
+          }
+        }
+      }
+    ' "$doc_file"
+  done >> "$output_file"
+}
+
+# Get unique reference files from a mapping file
+# Arguments:
+#   $1 - mapping_file: Path to the mapping file
+get_unique_references() {
+  local mapping_file="$1"
+  cut -d'|' -f1 "$mapping_file" | sort -u
+}
+
+# Find which docs reference a given file pattern
+# Arguments:
+#   $1 - mapping_file: Path to the mapping file
+#   $2 - pattern: The file pattern to search for
+find_docs_for_reference() {
+  local mapping_file="$1"
+  local pattern="$2"
+  grep -F "$pattern" "$mapping_file" | cut -d'|' -f2 | sort -u
+}
+
+# Build associative arrays for file-to-docs and docs-to-files mappings
+# Arguments:
+#   $1 - mapping_file: Path to the mapping file
+#   $2 - changed_files: Newline-separated list of changed files
+# Sets global variables:
+#   FILE_TO_DOCS_MAP - associative array
+#   DOC_TO_FILES_MAP - associative array
+#   CHANGED_REFERENCES - newline-separated list of changed reference files
+build_change_mappings() {
+  local mapping_file="$1"
+  local changed_files="$2"
+
+  # Initialize global associative arrays
+  declare -gA FILE_TO_DOCS_MAP
+  declare -gA DOC_TO_FILES_MAP
+  CHANGED_REFERENCES=""
+
+  local reference_files=$(get_unique_references "$mapping_file")
+
+  while IFS= read -r ref_file; do
+    [[ -z "$ref_file" ]] && continue
+    local match_pattern="${ref_file%/\*}"
+
+    if echo "$changed_files" | grep -qF "$match_pattern"; then
+      CHANGED_REFERENCES="${CHANGED_REFERENCES}${ref_file}\n"
+
+      while IFS='|' read -r src_file doc_file; do
+        if [[ "$src_file" == "$ref_file" ]]; then
+          if [[ -n "${FILE_TO_DOCS_MAP[$ref_file]:-}" ]]; then
+            FILE_TO_DOCS_MAP[$ref_file]="${FILE_TO_DOCS_MAP[$ref_file]}|${doc_file}"
+          else
+            FILE_TO_DOCS_MAP[$ref_file]="$doc_file"
+          fi
+
+          if [[ -n "${DOC_TO_FILES_MAP[$doc_file]:-}" ]]; then
+            DOC_TO_FILES_MAP[$doc_file]="${DOC_TO_FILES_MAP[$doc_file]}|${ref_file}"
+          else
+            DOC_TO_FILES_MAP[$doc_file]="$ref_file"
+          fi
+        fi
+      done < "$mapping_file"
+    fi
+  done <<< "$reference_files"
+}