Update documentation incorrectly reverted after refactor (#399)

docs/experimental.md

@@ -4,7 +4,7 @@
 
 ## Execution Modes
 
-The action supports two execution modes, each optimized for different use cases:
+The action supports three execution modes, each optimized for different use cases:
 
 ### Tag Mode (Default)
 
@@ -23,9 +23,11 @@ The traditional implementation mode that responds to @claude mentions, issue ass
 
 ### Agent Mode
 
-For automation and scheduled tasks without trigger checking.
+**Note: Agent mode is currently in active development and may undergo breaking changes.**
 
-- **Triggers**: Always runs (no trigger checking)
+For automation with workflow_dispatch and scheduled events only.
+
+- **Triggers**: Only works with `workflow_dispatch` and `schedule` events - does NOT work with PR/issue events
 - **Features**: Perfect for scheduled tasks, works with `override_prompt`
 - **Use case**: Maintenance tasks, automated reporting, scheduled checks
 
@@ -38,7 +40,26 @@ For automation and scheduled tasks without trigger checking.
       Check for outdated dependencies and create an issue if any are found.
 ```
 
-See [`examples/claude-modes.yml`](../examples/claude-modes.yml) for complete examples of each mode.
+### Experimental Review Mode
+
+**Warning: This is an experimental feature that may change or be removed at any time.**
+
+For automated code reviews on pull requests.
+
+- **Triggers**: Pull request events (`opened`, `synchronize`) or `@claude review` comments
+- **Features**: Provides detailed code reviews with inline comments and suggestions
+- **Use case**: Automated PR reviews, code quality checks
+
+```yaml
+- uses: anthropics/claude-code-action@beta
+  with:
+    mode: experimental-review
+    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+    custom_instructions: |
+      Focus on code quality, security, and best practices.
+```
+
+See [`examples/claude-modes.yml`](../examples/claude-modes.yml) and [`examples/claude-experimental-review-mode.yml`](../examples/claude-experimental-review-mode.yml) for complete examples of each mode.
 
 ## Network Restrictions
 

docs/faq.md

@@ -135,6 +135,14 @@ allowed_tools: "Bash(npm:*),Bash(git:*)" # Allows only npm and git commands
 
 No, Claude's GitHub app token is sandboxed to the current repository only. It cannot push to any other repositories. It can, however, read public repositories, but to get access to this, you must configure it with tools to do so.
 
+### Why aren't comments posted as claude[bot]?
+
+Comments appear as claude[bot] when the action uses its built-in authentication. However, if you provide a `github_token` in your workflow, the action will use that token's authentication instead, causing comments to appear under a different username.
+
+**Solution**: Remove `github_token` from your workflow file unless you're using a custom GitHub App.
+
+**Note**: The `use_sticky_comment` feature only works with claude[bot] authentication. If you're using a custom `github_token`, sticky comments won't update properly since they expect the claude[bot] username.
+
 ## MCP Servers and Extended Functionality
 
 ### What MCP servers are available by default?

docs/usage.md

@@ -47,8 +47,8 @@ jobs:
 ## Inputs
 
 | Input                          | Description                                                                                                                           | Required | Default   |
-| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | -------- | --------- |
-| `mode`                         | Execution mode: 'tag' (default - triggered by mentions/assignments), 'agent' (for automation with no trigger checking) | No       | `tag`     |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------- |
+| `mode`                         | Execution mode: 'tag' (default - triggered by mentions/assignments), 'agent' (for automation), 'experimental-review' (for PR reviews) | No       | `tag`     |
 | `anthropic_api_key`            | Anthropic API key (required for direct API, not needed for Bedrock/Vertex)                                                            | No\*     | -         |
 | `claude_code_oauth_token`      | Claude Code OAuth token (alternative to anthropic_api_key)                                                                            | No\*     | -         |
 | `direct_prompt`                | Direct prompt for Claude to execute automatically without needing a trigger (for automated workflows)                                 | No       | -         |