diff --git a/README.md b/README.md
index 4d88760..8acd837 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,8 @@
 
 ![GitHub](https://img.shields.io/github/license/pacnpal/claude-code-review)
 ![GitHub Actions Workflow Status](https://img.shields.io/badge/actions-passing-brightgreen)
+![Claude](https://img.shields.io/badge/Claude-Sonnet%204.5-blue)
+![Node](https://img.shields.io/badge/node-20-green)
 
 A GitHub Action that performs automated code reviews using Claude Sonnet 4.5, Anthropic's latest AI model for code analysis.
 
@@ -22,14 +24,18 @@ A GitHub Action that performs automated code reviews using Claude Sonnet 4.5, An
 - [Inputs](#inputs)
 - [Outputs](#outputs)
 - [Review Format](#review-format)
+- [Technical Details](#technical-details)
+- [Limitations](#limitations)
+- [Troubleshooting](#troubleshooting)
 - [Development](#development)
 - [Contributing](#contributing)
+- [FAQ](#frequently-asked-questions)
 - [License](#license)
 - [Support](#support)
 
 ## Features
 
-- 🤖 **AI-Powered Reviews**: Leverages Claude Sonnet 4.5 for intelligent code analysis
+- 🤖 **AI-Powered Reviews**: Leverages Claude Sonnet 4.5 (claude-sonnet-4-5-20250929) for intelligent code analysis
 - 🔍 **Comprehensive Analysis**: Examines code changes in pull requests thoroughly
 - 💡 **Detailed Feedback**: Provides actionable feedback on code quality and structure
 - 🐛 **Bug Detection**: Identifies potential issues and suggests improvements
@@ -37,6 +43,8 @@ A GitHub Action that performs automated code reviews using Claude Sonnet 4.5, An
 - ⚡ **Performance Insights**: Highlights performance implications of code changes
 - 📋 **Best Practices**: Ensures adherence to coding standards and best practices
 - 🎯 **Severity Ratings**: Categorizes issues by severity (Critical/High/Medium/Low)
+- 🔄 **Automatic Retries**: Built-in retry logic with exponential backoff for reliability
+- ⏱️ **Rate Limit Handling**: Automatically manages API rate limits
 
 ## Usage
 
@@ -134,9 +142,15 @@ You can also make it conditional based on labels or other criteria:
    - The `GITHUB_TOKEN` is automatically provided by GitHub Actions
    - No additional configuration needed
 
-3. **Set Permissions** (if needed):
+3. **Set Permissions**:
    - Ensure your workflow has proper permissions (see Usage example above)
    - Required permissions: `contents: read` and `pull-requests: write`
+   - For organization repositories, you may need to enable workflows to create/approve pull requests in Settings
+
+4. **Optional: Environment Protection**:
+   - For additional security, create a GitHub Environment (e.g., `development_environment`)
+   - Add `ANTHROPIC_API_KEY` as an environment secret instead of repository secret
+   - This provides additional control and approval gates for sensitive operations
 
 ## Inputs
 
@@ -172,6 +186,90 @@ Each issue found includes:
 - Specific recommendations
 - Code examples where helpful
 
+## Technical Details
+
+### Model Configuration
+
+- **Model**: Claude Sonnet 4.5 (`claude-sonnet-4-5-20250929`)
+- **Max Tokens**: 4096 tokens per review
+- **Temperature**: 0.7 for balanced creativity and consistency
+- **Context**: 10 lines of context around each change (git diff -U10)
+
+### Reliability Features
+
+**Automatic Retry Logic**:
+- Network failures are automatically retried up to 4 times
+- Exponential backoff strategy (2s, 4s, 8s, 16s delays)
+- Non-retryable errors (401, 403, 400) fail immediately
+
+**Timeout Protection**:
+- API requests timeout after 2 minutes
+- Prevents hanging workflows on slow responses
+
+**Rate Limit Handling**:
+- Automatically respects `Retry-After` headers
+- Graceful handling of 429 rate limit responses
+
+### Diff Size Limits
+
+- **Maximum Diff Size**: ~100KB (100,000 bytes)
+- Large diffs are automatically truncated with a notice
+- Helps stay within API token limits and ensures fast reviews
+
+## Limitations
+
+- **Diff Size**: Changes larger than ~100KB will be truncated
+- **Review Timeout**: Reviews exceeding 2 minutes will timeout
+- **PR State**: Can review closed PRs, but a warning is logged
+- **File Types**: All text-based files are analyzed; binary files in diffs are ignored
+- **API Costs**: Each review consumes Anthropic API credits based on diff size
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue**: "Failed to get PR details"
+- **Solution**: Ensure `GITHUB_TOKEN` has `pull-requests: read` permission
+- **Solution**: Verify the PR number is correct
+
+**Issue**: "anthropic-key does not match expected format"
+- **Solution**: Verify your API key starts with `sk-ant-`
+- **Solution**: Check for extra spaces or newlines in the secret
+
+**Issue**: "Diff is empty - no changes found"
+- **Solution**: This is expected when comparing identical commits
+- **Solution**: Ensure the PR has actual code changes
+
+**Issue**: "Rate limited" or 429 errors
+- **Solution**: The action will automatically retry with backoff
+- **Solution**: Consider reducing review frequency if you hit limits often
+- **Solution**: Check your Anthropic API rate limits and quotas
+
+**Issue**: "API request timed out"
+- **Solution**: This may happen with very large diffs (>100KB)
+- **Solution**: Break large PRs into smaller, more focused changes
+- **Solution**: The action will automatically truncate diffs that are too large
+
+**Issue**: Action fails with authentication errors
+- **Solution**: Verify `ANTHROPIC_API_KEY` is set correctly in repository secrets
+- **Solution**: Ensure the API key is active and not expired
+- **Solution**: Check that your Anthropic account has available credits
+
+### Debug Mode
+
+To enable verbose logging, add this to your workflow:
+
+```yaml
+- name: Run Claude Review
+  uses: pacnpal/claude-code-review@main
+  with:
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+    anthropic-key: ${{ secrets.ANTHROPIC_API_KEY }}
+    pr-number: ${{ github.event.pull_request.number }}
+  env:
+    ACTIONS_STEP_DEBUG: true
+```
+
 ## Example Review
 
 ```markdown
@@ -248,6 +346,68 @@ Contributions are welcome! Please:
 4. Run tests
 5. Submit a pull request
 
+## Frequently Asked Questions
+
+### How much does it cost?
+
+The action is free, but you'll need an Anthropic API subscription. Costs vary based on:
+- Diff size (larger diffs = more tokens)
+- Review frequency (more PRs = more API calls)
+- Current Claude API pricing (check [Anthropic's pricing](https://www.anthropic.com/pricing))
+
+Typical small PR review (~1-2KB diff) costs a few cents.
+
+### Can I use this with private repositories?
+
+Yes! The action works with both public and private repositories. Just ensure:
+- GitHub Actions is enabled for your repository
+- You've added the `ANTHROPIC_API_KEY` secret
+- Workflow permissions are properly configured
+
+### Will this slow down my CI/CD pipeline?
+
+The action runs asynchronously and doesn't block other checks. Typical review times:
+- Small PRs (<10KB): 10-30 seconds
+- Medium PRs (10-50KB): 30-60 seconds
+- Large PRs (50-100KB): 60-120 seconds
+
+You can also use `auto-review: false` to only run reviews on-demand.
+
+### Can I customize the review criteria?
+
+Currently, the review criteria are built into the action. Future versions may support custom prompts. You can:
+- Fork the repository and modify `action.js` to customize the prompt
+- Use the review as a baseline and add custom checks with other actions
+
+### Does it support languages other than English?
+
+The action's prompts are in English, but Claude can analyze code in any programming language. Review comments will be in English.
+
+### What happens if my diff is too large?
+
+Diffs larger than ~100KB are automatically truncated. A notice is added to the review indicating truncation. For large PRs:
+- Consider breaking them into smaller, focused changes
+- The most important changes (first ~100KB) will still be reviewed
+
+### Can I run this on forked PRs?
+
+Yes, but be cautious with secrets. Use GitHub's `pull_request_target` event with proper security:
+- Don't expose secrets to untrusted code
+- Consider requiring manual approval for fork PRs
+- Review GitHub's [security hardening guide](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions)
+
+### How do I prevent reviews on draft PRs?
+
+Add a condition to your workflow:
+
+```yaml
+jobs:
+  code-review:
+    if: github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+    # ... rest of job
+```
+
 ## License
 
 MIT License - see the [LICENSE](LICENSE) file for details