ci: add Claude Code PR reviewer (comment-only)

.github/workflows/claude-review.yml

@@ -0,0 +1,63 @@
+name: Claude PR Review
+
+on:
+  pull_request:
+    types: [opened, synchronize, ready_for_review]
+
+concurrency:
+  group: claude-review-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pull-requests: write
+  id-token: write
+
+jobs:
+  review:
+    if: >-
+      github.event.pull_request.draft == false &&
+      github.event.pull_request.head.repo.full_name == github.repository &&
+      github.actor != 'dependabot[bot]' &&
+      !contains(github.event.pull_request.labels.*.name, 'skip-claude-review')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          prompt: |
+            You are an expert technical-docs reviewer for ${{ github.repository }} (the public
+            docs.sharpapi.io site), reviewing PR #${{ github.event.pull_request.number }}:
+            "${{ github.event.pull_request.title }}".
+
+            First read ./REVIEW.md and ./CLAUDE.md for project context and review rules. Honor
+            them — REVIEW.md takes priority for how to review.
+
+            Scope: review ONLY the changes this PR introduces
+            (`gh pr diff ${{ github.event.pull_request.number }}`). Do NOT comment on
+            pre-existing content the PR does not touch. This reviewer is read-only.
+
+            For each genuine problem, post an inline comment on the exact line via the
+            mcp__github_inline_comment__create_inline_comment tool (confirmed: true), prefixed
+            with a severity tag:
+              [Critical]  factually wrong docs, broken/incorrect code example, or an OpenAPI
+                          spec that contradicts the real API (customer-facing errors are bugs)
+              [Important] misleading/incomplete docs; missing required version bump
+              [Nit]       wording, formatting, link style
+
+            Cite file:line evidence; never speculate. Focus: accuracy vs the real SharpAPI
+            (endpoints, params, auth headers, tiers, response shapes), correct and runnable code
+            examples (SDK + curl), `public/openapi.json` consistency and version-bump policy, and
+            broken internal/external links.
+
+            Finish with ONE concise summary comment (`gh pr comment`): overall verdict, counts by
+            severity, top 1-3 items. Be terse. If the PR is clean, say so — do not invent issues.
+          claude_args: |
+            --model claude-sonnet-4-6
+            --max-turns 12
+            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr diff:*),Bash(gh pr view:*),Read,Grep"
+            --disallowedTools "WebSearch,Write,Edit"

REVIEW.md

@@ -0,0 +1,19 @@
+# Review rules — docs.sharpapi.io
+
+Guidance for the automated Claude PR reviewer (`.github/workflows/claude-review.yml`).
+Read together with `CLAUDE.md`. Read-only reviewer: it comments, it doesn't build the site.
+
+## Severity
+- **[Critical]** — factually wrong docs, a broken/incorrect code example, or an OpenAPI spec that contradicts the real API. Customer-facing reference errors are bugs.
+- **[Important]** — misleading or incomplete docs; missing version bump where required.
+- **[Nit]** — wording, formatting, link style.
+
+## Always check
+- **Accuracy vs the real API** — endpoints, params, auth headers, tiers, response shapes.
+- **Examples** — code samples are correct, runnable, and current (SDK + curl).
+- **OpenAPI** — `public/openapi.json` changes are consistent and version-bumped per policy.
+- **Links & anchors** — no broken internal/external links.
+
+## Don't
+- Don't flag pre-existing content this PR didn't touch.
+- Don't speculate — cite the file/line or omit. "LGTM" is valid; never invent issues.