ci: refine docs-sync for concise updates

.github/workflows/claude-code-review.yml

@@ -25,6 +25,7 @@ jobs:
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           prompt: "/review"
+          allowed_tools: "Read,Glob,Grep"
           # CLAUDE.md is a symlink to AGENTS.md in this repo; keep repo rules there.
           claude_args: |
             --max-turns 4

.github/workflows/docs-sync.yml

@@ -33,34 +33,33 @@ jobs:
         run: |
           set -e
           if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
-            # Get changed files for the specified commit
             git fetch origin
-            CHANGED_FILES=$(git diff --name-only ${{ github.event.inputs.commit_sha }}~1 ${{ github.event.inputs.commit_sha }})
+            DIFF_BASE="${{ github.event.inputs.commit_sha }}~1"
+            DIFF_HEAD="${{ github.event.inputs.commit_sha }}"
           else
-            # Get list of changed files in the merged PR
             git fetch origin main
-            CHANGED_FILES=$(git diff --name-only ${{ github.event.pull_request.base.sha }} ${{ github.event.pull_request.merge_commit_sha }})
+            DIFF_BASE="${{ github.event.pull_request.base.sha }}"
+            DIFF_HEAD="${{ github.event.pull_request.merge_commit_sha }}"
           fi
+          CHANGED_FILES=$(git diff --name-only "$DIFF_BASE" "$DIFF_HEAD")
+          # Truncate diff to avoid blowing up the prompt
+          DIFF_CONTENT=$(git diff "$DIFF_BASE" "$DIFF_HEAD" -- '*.ts' '*.tsx' '*.md' | head -c 60000)
           echo "changed_files<<EOF" >> $GITHUB_OUTPUT
           echo "$CHANGED_FILES" >> $GITHUB_OUTPUT
           echo "EOF" >> $GITHUB_OUTPUT
+          echo "diff_content<<EOF" >> $GITHUB_OUTPUT
+          echo "$DIFF_CONTENT" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
 
       - name: Check if docs update needed
         id: check-docs
         run: |
-          # Check if changes require documentation updates
           NEEDS_DOCS_UPDATE=false
 
-          # Define patterns that typically require docs updates
           DOCS_PATTERNS=(
-            "^src/.*\.ts$"
-            "^src/.*\.tsx$"
             "^packages/.*/src/.*\.ts$"
             "^packages/.*/src/.*\.tsx$"
-            "^README\.md$"
-            "^CHANGELOG\.md$"
             "^docs/"
-            "package\.json$"
             "^api/"
             "^schema/"
           )
@@ -90,52 +89,57 @@ jobs:
         uses: anthropics/claude-code-action@beta
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          model: "claude-sonnet-4-5-20250929"
           direct_prompt: |
-            I need you to analyze the changes in this controller repository PR and update the documentation in the cartridge-gg/docs repository accordingly.
+            Analyze changes in this controller repository and update documentation
+            in the cartridge-gg/docs repository ONLY if user-facing behavior changed.
 
             **Change Information:**
             - Title: ${{ github.event.pull_request.title || format('Manual trigger for commit {0}', github.event.inputs.commit_sha) }}
             - Description: ${{ github.event.pull_request.body || 'Manually triggered documentation sync' }}
             - Files changed: ${{ steps.changed-files.outputs.changed_files }}
             - Commit SHA: ${{ github.event.pull_request.merge_commit_sha || github.event.inputs.commit_sha }}
 
-            **Your tasks:**
-            1. Review the changed files and PR description to understand what functionality was added, modified, or removed
-            2. Check the docs-repo directory to see what documentation currently exists
-            3. Determine if any existing documentation needs updates or if new documentation should be created
-            4. If updates are needed:
-               - Create or update the appropriate documentation files in the docs-repo directory
-               - Ensure the documentation accurately reflects the current state of the controller
-               - Follow the existing documentation style and structure
-               - Focus on user-facing changes, API changes, new features, or breaking changes
-
-            **Important guidelines:**
-            - Only create documentation updates if they are actually needed
-            - Don't document internal implementation details unless they affect usage
-            - If no documentation updates are needed, simply state that and exit
-            - Focus on adding documention to the 1-3 most relevant files, not everywhere
-            - DO NOT create git branches, commits, or PRs - just update the files
-            - DO NOT create many redundant code samples - create one sample and reference it as-needed
-
-            The docs repository is checked out in the `docs-repo` directory. Please analyze the controller changes and update the documentation files accordingly.
+            **Diff of user-facing files:**
+            ${{ steps.changed-files.outputs.diff_content }}
+
+            **Docs repo structure** (checked out in `docs-repo/`):
+            The site uses Vocs. Content lives in `docs-repo/src/pages/` with three sections:
+            - `controller/` — wallet, sessions, policies, presets, achievements, inventory, native integrations, examples
+            - `slot/` — Katana/Torii deployment, billing, scale, paymaster, vRNG, RPC
+            - `arcade/` — game hub setup, marketplace
+            Sidebar config is in `docs-repo/vocs.config.ts`.
+
+            **Rules — read these carefully:**
+            1. DEFAULT TO NO CHANGES. Most code PRs do not need docs updates.
+               Internal refactors, test changes, CI changes, and dependency bumps need nothing.
+               Only proceed if there is a concrete user-facing change (new API, changed behavior,
+               new feature, removed feature, changed configuration).
+            2. SINGLE CANONICAL LOCATION. Each piece of information belongs on exactly one page.
+               Find the one page that owns the topic and make your substantive edits there.
+               Other pages MAY add a brief cross-reference linking to the canonical page,
+               but do NOT duplicate explanations, code samples, or configuration details
+               across multiple pages.
+            3. MINIMAL EDITS. Update only the specific section affected. Do not rewrite
+               surrounding paragraphs, add new sections for context, or reorganize existing content.
+            4. ONE CODE EXAMPLE per concept. If a code sample is needed, add it once in the
+               canonical location. Do not add the same or similar examples to multiple pages.
+            5. Do NOT create git branches, commits, or PRs — just update files.
+            6. If no documentation updates are needed, state that clearly and exit.
 
           allowed_tools: "Read,Write,Edit,MultiEdit,Glob,Grep"
 
       - name: Create branch and commit changes
         if: steps.check-docs.outputs.needs_update == 'true'
         working-directory: docs-repo
         run: |
-          # Configure git
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
 
-          # Check if there are any changes
           if [ -n "$(git status --porcelain)" ]; then
-            # Create new branch
             BRANCH_NAME="docs-update-$(date +%s)"
             git checkout -b "$BRANCH_NAME"
 
-            # Add and commit changes
             git add .
             if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
               git commit -m "docs: Update documentation for controller commit ${{ github.event.inputs.commit_sha }}
@@ -153,10 +157,8 @@ jobs:
               Related controller PR: cartridge-gg/controller#${{ github.event.pull_request.number }}"
             fi
 
-            # Push branch
             git push origin "$BRANCH_NAME"
 
-            # Create PR
             if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
               gh pr create \
                 --title "docs: Update documentation for controller commit ${{ github.event.inputs.commit_sha }}" \
@@ -188,5 +190,4 @@ jobs:
       - name: Cleanup
         if: always()
         run: |
-          # Clean up any temporary files or directories
           rm -rf docs-repo || true