Add daily workflow to refresh generated developer docs

.claude/commands/update-docs.md

@@ -35,11 +35,40 @@ For each stale doc:
 1. Re-read the source file.
 2. Rewrite the `.md` with updated content and a new `revision` from `git log -1 --format=%h -- <source>`.
 
-**Writing style**: Describe the code's **current state**, not what changed.
-Avoid changelog language like "now", "added", "new", "no longer", "has been removed", "previously", "was replaced".
-Write as if describing the code to someone seeing it for the first time.
-Good: "`MZ_DATABASES` is a `BuiltinMaterializedView` backed by a query over the catalog."
-Bad: "`MZ_DATABASES` is now a `BuiltinMaterializedView` (rather than a `BuiltinTable`)."
+## Editing Existing Documentation
+
+Make surgical edits. Only change text that is:
+  - Factually incorrect
+  - Grammatically broken
+  - Directly related to the task you were given
+
+Do not rephrase, reword, or restructure text that is already correct.
+Treat existing wording as intentional. If a sentence is awkward but
+accurate, leave it alone unless you were specifically asked to improve it.
+
+When updating docs to reflect a code change, touch only the sentences
+that the change invalidates. Everything else stays verbatim.
+
+## Documentation Writing Style
+
+Describe the code's current state, not what changed.
+
+Write as if the reader is seeing the codebase for the first time.
+They have no knowledge of prior implementations, so references to
+what something "used to be" are meaningless to them.
+
+Avoid changelog language:
+  - "now", "added", "new"
+  - "no longer", "has been removed"
+  - "previously", "was replaced"
+  - "changed from", "updated to", "instead of"
+
+Examples:
+  Good: "`MZ_DATABASES` is a `BuiltinMaterializedView` backed by a query over the catalog."
+  Bad:  "`MZ_DATABASES` is now a `BuiltinMaterializedView` (rather than a `BuiltinTable`)."
+
+The "bad" example fails twice: "now" implies a change, and the parenthetical
+references an implementation the reader never saw.
 
 ### 5. Create docs for new files
 

.github/workflows/update-generated-docs.yml

@@ -0,0 +1,114 @@
+# Copyright Materialize, Inc. and contributors. All rights reserved.
+#
+# Use of this software is governed by the Business Source License
+# included in the LICENSE file at the root of this repository.
+#
+# As of the Change Date specified in that file, in accordance with
+# the Business Source License, use of this software will be governed
+# by the Apache License, Version 2.0.
+
+name: Update Generated Docs
+
+on:
+  schedule:
+    # Run daily at 06:00 UTC
+    - cron: '0 6 * * *'
+  workflow_dispatch: {} # Allow manual triggering
+
+jobs:
+  update-docs:
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    permissions:
+      contents: write
+      pull-requests: write
+      id-token: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Run Claude Code to update docs
+        id: claude
+        uses: anthropics/claude-code-action@02438e66d09982e371c6559d3a2ccdff9032f203 # v1.0.77
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          direct_prompt: |
+            Run the procedure described in .claude/commands/update-docs.md
+
+            IMPORTANT: You may ONLY create or modify files under doc/developer/generated/.
+            Do NOT modify any other files.
+          claude_args: '--allowedTools Edit Read Glob Grep Bash(git log:*) Bash(git diff:*) Bash(find:*) Bash(wc:*) Bash(head:*)'
+
+      - name: Check for changes
+        id: changes
+        run: |
+          if git diff --quiet HEAD -- doc/developer/generated/; then
+            echo "has_changes=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_changes=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Create or update pull request
+        if: steps.changes.outputs.has_changes == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          BRANCH="automated/update-generated-docs"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git remote set-url origin "https://x-access-token:${GH_TOKEN}@github.com/${{ github.repository }}.git"
+
+          # Check if there's already an open PR from this branch
+          EXISTING_PR=$(gh pr list --state open --head "$BRANCH" --json number --jq '.[0].number // empty')
+
+          if [ -n "$EXISTING_PR" ]; then
+            echo "Updating existing PR #$EXISTING_PR on branch $BRANCH"
+            git fetch origin "$BRANCH"
+            git checkout "$BRANCH"
+            git merge --no-edit origin/main || true
+          else
+            echo "Creating new branch $BRANCH"
+            git checkout -b "$BRANCH"
+          fi
+
+          git add doc/developer/generated/
+          git commit -m "doc: update generated developer documentation
+
+          Automated daily refresh of doc/developer/generated/ to reflect
+          source changes since each doc was last written.
+
+          Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>"
+          git push origin "$BRANCH"
+
+          if [ -z "$EXISTING_PR" ]; then
+            gh pr create \
+              --title "doc: update generated developer documentation" \
+              --body "$(cat <<'EOF'
+          ## Summary
+
+          Automated daily refresh of `doc/developer/generated/` to reflect source code changes.
+
+          This PR was generated by the `update-generated-docs` workflow running `.claude/commands/update-docs.md`.
+
+          ## Scope
+
+          Only files under `doc/developer/generated/` are modified.
+
+          ## Review checklist
+
+          - [ ] No unrelated rewording or restructuring of existing text
+          - [ ] No changelog language ("now", "added", "previously", etc.)
+          - [ ] Changes correspond to actual source code changes
+
+          🤖 Generated with [Claude Code](https://claude.com/claude-code)
+          EOF
+          )" \
+              --label "A-doc" \
+              --reviewer bosconi
+          fi
+          # Automerge is intentionally NOT enabled here.
+          # A human must review and approve before merging to prevent
+          # doc degeneration (see PR #35775 discussion).