docs: Update workflow docs for @mention trigger [doc-updater]

docs/guides/github-automation.md

@@ -12,7 +12,7 @@ for how to call egg's workflows from your own repositories.
 | Workflow | Trigger | What It Does |
 |----------|---------|--------------|
 | [AI Code Review](#ai-code-review) | PR opened/updated | Reviews code changes, posts feedback via `gh pr review` |
-| [Address Review Feedback](#address-review-feedback) | Review posted on bot PR | Automatically addresses review feedback, enabling review loops |
+| [Address Review Feedback](#address-review-feedback) | Review posted on bot PR, or human @mention | Automatically addresses review feedback, enabling review loops |
 | [Design Review](#design-review) | PR opened/updated (specialized) | Applies project-specific review rules via the same reusable framework |
 | [Contract Verification](#contract-verification) | PR with sdlc:pr label or contract file | Verifies implementation matches SDLC contract |
 | [Check Autofixer](#check-autofixer) | CI check failure on a PR | Diagnoses failures, auto-fixes or reports |
@@ -98,14 +98,14 @@ wait on each other indefinitely.
 
 **Workflow:** [`.github/workflows/on-review-feedback.yml`](../../.github/workflows/on-review-feedback.yml)
 
-Triggers when a review bot posts feedback on a PR, enabling an automated review loop:
+Triggers when a review bot posts feedback on a PR, or when a human @mentions the bot, enabling an automated review loop:
 PR opened → review → address feedback → re-review → ... → approval or human escalation.
 
 ### Trigger Events
 
 The workflow runs on:
-- `pull_request_review` — Formal reviews posted via `gh pr review`
-- `issue_comment` — Legacy self-reviews posted as comments (deprecated — use a separate reviewer bot instead, see below)
+- `pull_request_review` — Formal reviews posted via `gh pr review` (bot or authorized human)
+- `issue_comment` — Bot self-reviews posted as comments, or authorized human @mentions the bot
 - `workflow_dispatch` — Manual trigger with PR number (bypasses filters for debugging)
 
 ### Separate Reviewer Bot (Recommended)
@@ -122,7 +122,13 @@ Without it, the system falls back to posting reviews as comments (self-review mo
 
 ### How It Works
 
-1. **Filter checks** — Only runs when:
+1. **Trigger authorization** — For event-triggered runs, verifies the triggering user is authorized:
+   - Bot reviews always trigger (the bot can review its own PRs)
+   - Human reviews and @mentions require the user to be in the `authorized_users` list
+   - Configured via `EGG_AUTHORIZED_USERS` repository variable (defaults to `jwbron`)
+   - Manual/workflow_call triggers bypass authorization
+
+2. **Filter checks** — Only runs when:
    - PR is open (not closed/merged)
    - PR is from the same repository (not a fork — bot can't push to forks)
    - PR author is the bot (unless manually triggered)
@@ -132,29 +138,30 @@ Without it, the system falls back to posting reviews as comments (self-review mo
      - Approvals trigger only if they include `<!-- has-suggestions -->` marker
    - Iteration count is below the limit (default: 3 rounds)
 
-2. **Wait for all reviewers** — Polls GitHub check runs for all `egg-reviewer-*` jobs
+3. **Wait for all reviewers** — For review-triggered runs, polls GitHub check runs for all `egg-reviewer-*` jobs
    to complete before proceeding. This prevents race conditions when multiple reviewers
    (e.g., Code Review and Design Review) trigger the feedback workflow concurrently.
    The workflow waits up to 10 minutes, proceeding with a warning on timeout. If no
    reviewer checks are found after 2 minutes, the workflow exits with a warning (this
    indicates a potential configuration issue since the workflow was triggered by
-   reviewer feedback).
+   reviewer feedback). Mention-triggered runs skip this step since there are no reviewer
+   checks to wait for.
 
-3. **Comment cleanup** — Minimizes previous feedback-addressing comments to reduce clutter.
+4. **Comment cleanup** — Minimizes previous feedback-addressing comments to reduce clutter.
 
-4. **Acknowledgment** — Posts a comment indicating feedback is being addressed, with an `<!-- egg-feedback-addressing -->` marker for iteration tracking.
+5. **Acknowledgment** — Posts a comment indicating feedback is being addressed, with an `<!-- egg-feedback-addressing -->` marker for iteration tracking.
 
-5. **Trusted prompt build** — Checks out `main` (not the PR branch) to run `build-feedback-prompt.sh`, preventing prompt injection from malicious PRs.
+6. **Trusted prompt build** — Checks out `main` (not the PR branch) to run `build-feedback-prompt.sh`, preventing prompt injection from malicious PRs.
 
-6. **Agent execution** — Checks out the PR branch and runs egg. The agent:
+7. **Agent execution** — Checks out the PR branch and runs egg. The agent:
    - Reads review feedback via `gh pr view`, `gh api` for reviews and line-level comments
    - Understands the current code via `gh pr diff`
    - Makes fixes addressing actionable feedback
    - Runs tests and linters before pushing
    - Commits and pushes all fixes together
    - Replies to feedback it disagrees with or cannot address
 
-7. **Result comment** — Posts success or failure status with link to run logs.
+8. **Result comment** — Posts success or failure status with link to run logs.
 
 ### Iteration Limiting
 
@@ -500,6 +507,14 @@ Event-triggered workflows require these repository variables (Settings → Secre
 
 Reusable workflows called via `workflow_call` receive these values as inputs from the caller instead.
 
+### Optional Repository Variables
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `EGG_AUTHORIZED_USERS` | Comma-separated list of GitHub users authorized to trigger review feedback via reviews or @mentions | `jwbron` |
+
+This variable controls who can trigger the Address Review Feedback workflow through human reviews or @mentions. The bot itself is always authorized to trigger via automated reviews.
+
 ### Per-Repository Customization
 
 | File | Purpose |

docs/guides/reusable-workflows.md

@@ -132,14 +132,21 @@ jobs:
 | `EGG_BOT_USERNAME` | Bot's GitHub username | `james-in-a-box[bot]` |
 | `EGG_BRANCH_PREFIX` | Branch prefix for bot-owned branches | `egg` |
 
+**OPTIONAL**: Additional variables for customization:
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `EGG_AUTHORIZED_USERS` | Comma-separated list of users authorized to trigger review feedback | `jwbron` |
+
 ### Setting Up Repository Variables
 
 1. Go to your repository's **Settings** → **Secrets and variables** → **Actions**
 2. Click the **Variables** tab
 3. Click **New repository variable**
-4. Add both `EGG_BOT_USERNAME` and `EGG_BRANCH_PREFIX` with appropriate values
+4. Add required variables (`EGG_BOT_USERNAME` and `EGG_BRANCH_PREFIX`)
+5. Optionally add `EGG_AUTHORIZED_USERS` to control who can trigger feedback via reviews or @mentions
 
-**Note**: Workflows will fail with a validation error if these variables are not set.
+**Note**: Workflows will fail with a validation error if required variables are not set.
 
 ### Using in Workflows