first commit

docs/configuration.md

@@ -0,0 +1,196 @@
+# Configuration Reference
+
+All configuration is managed in `tools/ai-review/config.yml`.
+
+## Provider Settings
+
+```yaml
+# LLM Provider: openai | openrouter | ollama
+provider: openai
+
+# Model per provider
+model:
+  openai: gpt-4.1-mini
+  openrouter: anthropic/claude-3.5-sonnet
+  ollama: codellama:13b
+
+# Generation settings
+temperature: 0        # 0 = deterministic
+max_tokens: 4096      # Max response tokens
+```
+
+## Review Settings
+
+```yaml
+review:
+  fail_on_severity: HIGH    # Fail CI on this severity
+  max_diff_lines: 800       # Truncate large diffs
+  inline_comments: true     # Post inline PR comments
+  security_scan: true       # Run security scanner
+```
+
+## Agent Configuration
+
+### Issue Agent
+
+```yaml
+agents:
+  issue:
+    enabled: true
+    auto_label: true           # Apply labels automatically
+    auto_triage: true          # Run triage on new issues
+    duplicate_threshold: 0.85  # Similarity threshold
+    events:
+      - opened
+      - labeled
+```
+
+### PR Agent
+
+```yaml
+agents:
+  pr:
+    enabled: true
+    inline_comments: true      # Post inline comments
+    security_scan: true        # Run security scanner
+    events:
+      - opened
+      - synchronize
+```
+
+### Codebase Agent
+
+```yaml
+agents:
+  codebase:
+    enabled: true
+    schedule: "0 0 * * 0"      # Cron schedule (weekly)
+```
+
+### Chat Agent (Bartender)
+
+```yaml
+agents:
+  chat:
+    enabled: true
+    name: "Bartender"          # Display name for the bot
+    max_iterations: 5          # Max tool calls per chat
+    tools:
+      - search_codebase        # Search repository files
+      - read_file              # Read file contents
+      - search_web             # Web search via SearXNG
+    searxng_url: ""            # SearXNG instance URL (or use SEARXNG_URL env var)
+```
+
+## Interaction Settings
+
+### Customizing the Bot Name
+
+The `mention_prefix` controls what trigger the bot responds to. You can change it to any name you prefer:
+
+```yaml
+interaction:
+  mention_prefix: "@bartender"  # Users will type @bartender to invoke the bot
+```
+
+**Important:** When changing the bot name, you must also update the workflow files:
+
+1. Edit `.github/workflows/ai-comment-reply.yml` and `ai-chat.yml` (for GitHub)
+2. Edit `.gitea/workflows/ai-comment-reply.yml` and `ai-chat.yml` (for Gitea)
+3. Change the `if:` condition to match your new prefix:
+   ```yaml
+   if: contains(github.event.comment.body, '@bartender')
+   ```
+
+**Example bot names:**
+- `@ai-bot` - Default, generic
+- `@bartender` - Friendly, conversational
+- `@uni` - Short, quick to type
+- `@joey` - Personal assistant
+- `@codebot` - Technical focus
+
+```yaml
+interaction:
+  respond_to_mentions: true
+  mention_prefix: "@ai-bot"
+  commands:
+    - explain      # Explain code/issue
+    - suggest      # Suggest solutions
+    - security     # Run security check
+    - summarize    # Summarize content
+```
+
+## Label Mappings
+
+```yaml
+labels:
+  priority:
+    high: "priority: high"
+    medium: "priority: medium"
+    low: "priority: low"
+  type:
+    bug: "type: bug"
+    feature: "type: feature"
+    question: "type: question"
+    docs: "type: documentation"
+  status:
+    ai_approved: "ai-approved"
+    ai_changes_required: "ai-changes-required"
+    ai_reviewed: "ai-reviewed"
+```
+
+## Enterprise Settings
+
+```yaml
+enterprise:
+  audit_log: true
+  audit_path: "/var/log/ai-review/"
+  metrics_enabled: true
+  rate_limit:
+    requests_per_minute: 30
+    max_concurrent: 4
+```
+
+## Security Configuration
+
+```yaml
+security:
+  enabled: true
+  fail_on_high: true
+  rules_file: "security/security_rules.yml"  # Custom rules
+```
+
+## Environment Variables
+
+These override config file settings:
+
+| Variable | Description |
+|----------|-------------|
+| `AI_REVIEW_TOKEN` | Gitea/GitHub API token |
+| `AI_REVIEW_API_URL` | API base URL (`https://api.github.com` or Gitea URL) |
+| `AI_REVIEW_REPO` | Target repository (owner/repo) |
+| `OPENAI_API_KEY` | OpenAI API key |
+| `OPENROUTER_API_KEY` | OpenRouter API key |
+| `OLLAMA_HOST` | Ollama server URL |
+| `SEARXNG_URL` | SearXNG instance URL for web search |
+| `AI_AUDIT_PATH` | Audit log directory |
+
+## Per-Repository Overrides
+
+Create `.ai-review.yml` in repository root:
+
+```yaml
+# Override global config for this repo
+agents:
+  pr:
+    security_scan: false  # Disable security scan
+  issue:
+    auto_label: false     # Disable auto-labeling
+
+# Custom labels
+labels:
+  priority:
+    high: "P0"
+    medium: "P1"
+    low: "P2"
+```