feat(ci): auto-commit docs fixes from the docs check

Set `auto_fix: true` on the `_claude-docs-check.yml` call so a FAIL verdict
is repaired and pushed instead of only reported. The toolkit runs a second
Claude pass scoped to Read/Edit/Write/Grep/Glob/Bash(git:*), commits as
`docs(claude): fix documentation issues (auto-fix)`, and pushes directly to
the PR head branch using `WORKFLOW_PAT` so the push re-triggers the check.

`auto_commit` is deliberately left dispatch-only. It is a different
mechanism — it overwrites whole files with the model's `suggested_content`
and carries no loop guard — and its commit subject does not match the
anchored regex `auto_fix`'s loop guard keys on, so enabling both would make
the two push over each other indefinitely.

Fork PRs are unaffected: the job-level `if:` already requires
`head.repo.full_name == github.repository`, and every auto-fix step inside
the reusable workflow re-checks the PR's live head repo independently.

Auto-fix is dormant on bot-authored PRs until ai-toolkit plumbs
`allowed_bots` through, because the job still fails at claude-code-action's
actor check before any verdict is produced.

Author: claude

.github/workflows/CLAUDE.md

@@ -300,6 +300,61 @@ needed to merge here, but the durable fix is to drop
 `docs-check / docs-check` from the ruleset in favour of a context that
 always reports.
 
+#### Auto-committing doc fixes (`auto_fix: true`)
+
+**This workflow now pushes commits to PR head branches.** `auto_fix: true`
+is set on the reusable-workflow call. When the check reaches a verdict and
+that verdict is `FAIL` — or it produced any suggestions or missing updates —
+the toolkit runs a **second** Claude pass, scoped to
+`Read,Edit,Write,Grep,Glob,Bash(git:*)`, commits whatever it changed as
+`docs(claude): fix documentation issues (auto-fix)` authored by
+`github-actions[bot]`, and pushes **straight to the PR's head branch**. It
+does not open a fixup branch and it does not open a follow-up PR.
+
+Blast radius, stated plainly:
+
+- The job holds `contents: write` and will rewrite **contributors' branches**,
+  not just its own. It applies to **human-authored PRs as much as bot ones** —
+  nothing in the gate distinguishes them for this purpose.
+- **Fork PRs are unaffected.** Two independent guards: this repo's job-level
+  `if:` still requires
+  `github.event.pull_request.head.repo.full_name == github.repository`, and
+  every auto-fix step inside the reusable workflow separately re-checks
+  `steps.pr-branch.outputs.repo_full_name == github.repository` against the
+  PR's live head repo. Either one alone would be sufficient.
+- **A loop guard exists.** Auto-fix is skipped when the PR head commit is
+  authored by `github-actions[bot]` **and** its subject matches
+  `^\w+\(claude\):.*\(auto-fix\)$`. The author check uses `.author.login`
+  from the API (GitHub-verified) rather than `.commit.author.name`
+  (user-controlled git metadata), and fails open — an unlinked email means
+  auto-fix runs.
+- **It flips the check green when it pushes.** With `WORKFLOW_PAT` set, a
+  `FAIL` verdict that produced a push exits `0` on the theory that the push
+  re-triggers a fresh check. If `WORKFLOW_PAT` is _unset_, the push falls
+  back to `GITHUB_TOKEN`, which does not trigger workflows, and the toolkit
+  fails the job with an explicit message rather than reporting green against
+  unvalidated code. That is the failure mode to look for if auto-fix commits
+  land but no follow-up check appears.
+
+**Not yet effective on bot-authored PRs.** Auto-fix runs off
+`steps.process-results.outputs.verdict`, and on a `claude[bot]` PR the job
+still dies earlier at `claude-code-action`'s `allowed_bots` actor check
+(above), so `Process Results` is skipped and no verdict is ever produced.
+Auto-fix is therefore live for human-authored PRs today and dormant on bot
+PRs until `allowed_bots` is plumbed through `_claude-docs-check.yml` in
+`Uniswap/ai-toolkit`.
+
+**Do not enable `auto_commit` as well.** It is a different mechanism —
+`post-docs-check.ts`'s `autoCommitChanges`, which applies the model's
+structured `suggestions[]` by overwriting whole files with
+`suggested_content`, has no loop guard of its own, and commits as
+`docs: auto-update documentation`. That subject does not match the anchored
+regex `auto_fix`'s loop guard keys on, so with both enabled the two
+mechanisms push over each other indefinitely. `auto_commit` remains wired to
+`github.event.inputs.auto_commit`, which is empty on `pull_request` events
+and so always `false` there — that expression is why the check has never
+auto-committed on a PR, and it is intentionally left alone.
+
 ### Generate PR Title & Description
 
 **File:** `generate-pr-title-description.yml`

.github/workflows/claude-docs-check.yml

@@ -94,7 +94,34 @@ jobs:
     with:
       pr_number: ${{ github.event.pull_request.number || github.event.inputs.pr_number }}
       suggestion_mode: ${{ github.event.inputs.suggestion_mode || 'suggest' }}
+      # `auto_commit` stays manual-dispatch-only. On a `pull_request` event
+      # `github.event.inputs` is empty, so this expression is always `false`
+      # there — which is why the docs check has never auto-committed anything
+      # on a PR. Auto-committing is enabled via `auto_fix` below instead, not
+      # by flipping this. The two are different mechanisms and enabling both
+      # is a mistake: `auto_commit` applies the model's structured
+      # `suggestions[]` array by *overwriting whole files* with
+      # `suggested_content` (`post-docs-check.ts`, `autoCommitChanges`), it
+      # has no loop guard, and its commit subject
+      # (`docs: auto-update documentation`) does not match the anchored
+      # `^\w+\(claude\):.*\(auto-fix\)$` regex that `auto_fix`'s loop guard
+      # keys on — so the two would push over each other indefinitely.
       auto_commit: ${{ github.event.inputs.auto_commit == 'true' }}
+      # AUTO-COMMIT DOC FIXES. When the check returns a FAIL verdict (or finds
+      # any suggestions / missing updates), the toolkit runs a second Claude
+      # pass scoped to `Read,Edit,Write,Grep,Glob,Bash(git:*)`, commits the
+      # result as `docs(claude): fix documentation issues (auto-fix)` authored
+      # by `github-actions[bot]`, and pushes it **directly to the PR's head
+      # branch** — not to a fixup branch and not as a follow-up PR. The push
+      # uses `WORKFLOW_PAT` (passed below), which is what lets the resulting
+      # commit re-trigger this workflow so the fixed code gets a fresh verdict;
+      # a `GITHUB_TOKEN` push would not re-trigger, and the toolkit
+      # deliberately fails the job in that case rather than leaving a stale
+      # green. Blast radius: this rewrites contributors' branches, human- and
+      # bot-authored alike. It cannot touch a fork — every auto-fix step is
+      # additionally gated on `head.repo.full_name == github.repository`
+      # inside the reusable workflow, on top of this job's own `if:`.
+      auto_fix: true
       # Use sonnet for faster, cheaper checks
       model: 'claude-sonnet-5'
       # Fail if plugin versions aren't bumped
@@ -106,7 +133,12 @@ jobs:
     secrets:
       # Use OAuth token (Pro/Max) instead of API key
       CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
-      # PAT for branch creation
+      # PAT for branch creation and for the `auto_fix` push. Required for
+      # auto-fix to be useful: the toolkit falls back to `GITHUB_TOKEN` when
+      # this is unset, and a `GITHUB_TOKEN` push does not trigger workflows,
+      # so the fix would never be re-validated. The toolkit's `Set Exit Code`
+      # step detects that case and fails the job with an explicit message
+      # rather than reporting a passing check against unverified code.
       WORKFLOW_PAT: ${{ secrets.WORKFLOW_PAT }}
     permissions:
       contents: write