diffray 0.1.3 → 0.3.1

package/README.md

@@ -1,403 +1,803 @@
+<table>
+  <tr>
+    <td><img src="logo.svg" alt="diffray" width="120"></td>
+    <td>
+      <h1>diffray</h1>
+      <strong>Free open-source multi-agent code review</strong>
+    </td>
+  </tr>
+</table>
+
+> **What is this?** A CLI tool that runs multiple AI agents to review your code changes. Each agent specializes in different aspects: bugs, security, performance, code style. Works with [Claude Code](https://github.com/anthropics/claude-code) or [Cursor Agent](https://cursor.com).
+>
+> **How is it different from [diffray.ai](https://diffray.ai)?** The cloud platform automatically learns from your team's review feedback and generates rules. This CLI version requires manual rule configuration but gives you full control and runs locally.
+
 <p align="center">
-  <img src="logo.svg" alt="diffray" width="200">
+  <img src="/docs/diffray.png" alt="diffray in action" width="800">
 </p>
 
-<h1 align="center">diffray</h1>
+---
 
-<p align="center">
-  <strong>Multi-agent AI code review with minimal false positives</strong>
-</p>
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Prerequisites](#prerequisites)
+- [How It Works](#how-it-works)
+- [Configuration](#configuration-optional)
+- [Creating Custom Agents](#creating-custom-agents)
+- [Creating Custom Rules](#creating-custom-rules)
+- [Overriding Agents and Rules](#overriding-agents-and-rules)
+- [FAQ](#faq)
+- [Development](#development)
+
+---
+
+## Quick Start
 
+### 1. Install diffray
+
+```bash
+# Install globally from npm
+npm install -g diffray
 ```
-Git Diffs → Specialized Agents → Deduplication → Validation → Verified Issues
+
+### 2. Run your first review
+
+```bash
+# Go to your project
+cd your-project
+
+# Review your uncommitted changes (or last commit if working tree is clean)
+diffray
+
+# Or review changes between branches
+diffray --base main
 ```
 
-## About This Version
+That's it! diffray will analyze your changes and show any issues found.
 
-This is a **simplified, lightweight version** of the full [diffray.ai](https://diffray.ai) platform — and it's **completely free**.
+### Common Commands
 
-Despite its minimal footprint, it achieves **high bug detection rates** and **low false positive noise** by leveraging **Claude Code** as the primary executor.
+```bash
+# Review uncommitted changes, or last commit if clean
+diffray
 
-Claude Code provides:
-- **Deep codebase understanding** - full file access and navigation
-- **Context-aware analysis** - reads related files to understand impact
-- **Accurate issue validation** - verifies findings against actual code
+# Review changes compared to main branch
+diffray --base main
 
-The result: fewer false alarms, more actionable findings.
+# Review last 3 commits
+diffray --base HEAD~3
 
-## Why diffray?
+# Show only critical and high severity issues
+diffray --severity critical,high
 
-### Multi-Agent Architecture
-Each agent is a specialist focused on one domain:
-- **security-scan** - finds vulnerabilities with concrete attack paths
-- **bug-hunter** - detects logic errors and runtime issues
-- **performance-check** - identifies performance bottlenecks
+# Run only specific agent
+diffray --agent bug-hunter
 
-Specialized agents produce higher quality findings than one generalist trying to catch everything.
+# Output as JSON (for CI/CD pipelines)
+diffray --json
 
-### Minimal False Positives
-Two-stage filtering eliminates noise:
-1. **Deduplication** - removes duplicate issues across agents
-2. **Validation** - LLM verifies each issue against actual code, filters out false positives
+# Show detailed progress
+diffray --stream
 
-Only issues that are verified with 90%+ confidence make it to the final report.
+# List available agents and rules
+diffray agents
+diffray rules
+```
 
-### Flexible Execution
-Agents can run via different executors:
-- **claude-cli** - Claude Code with file access for deep analysis
-- **cerebras-api** - Fast Cerebras API for quick checks
-- Mix and match based on cost, speed, and capability needs
+## Prerequisites
 
-## Key Features
+- **Git** - your project must be a git repository
+- **AI CLI Tool** - diffray uses external AI tools to analyze code. You need to install and authorize one of them:
 
-- **Multi-agent pipeline** - Specialized agents for security, bugs, performance
-- **False positive filtering** - Validation stage verifies issues against actual code
-- **Parallel execution** - All agents run simultaneously
-- **Rule matching** - Run different agents on different file types
-- **Markdown config** - Define agents and rules in simple `.md` files
-- **Global CLI** - Works in any git repository
-- **Zero config** - Sensible defaults, customize when needed
+### Claude Code CLI (default)
 
-## Get Results in Your PRs
+Claude Code is an official Anthropic CLI tool with agentic capabilities.
 
-Want automated code reviews directly in your GitHub Pull Requests?
+```bash
+# Install
+npm install -g @anthropic-ai/claude-code
 
-**Sign up at [diffray.ai](https://diffray.ai)** - connect your repo and get AI code review comments on every PR.
+# Authorize (opens browser for OAuth)
+claude auth login
+```
 
-The hosted version includes:
-- **50+ specialized rules** for TypeScript, Python, Go, Rust, and more
-- **Language-specific agents** tuned for each ecosystem
-- **GitHub integration** - comments appear directly on PR diffs
-- **Team dashboard** - track issues across repositories
+### Cursor Agent CLI (alternative)
 
-## Installation (CLI)
+If you use Cursor IDE, you can use its agent CLI instead:
 
-### From source
+```bash
+# Install
+curl https://cursor.com/install -fsS | bash
+
+# Authorize (opens browser)
+cursor-agent
+```
+
+Then switch diffray to use it:
 
 ```bash
-# Clone and install
-git clone <your-repo>
-cd diffray
-bun install
+# Via config
+diffray config init
+# Edit .diffray.json and add: "executor": "cursor-agent-cli"
 
-# Link globally
-bun link
+# Or per-run
+diffray review --executor cursor-agent-cli
 ```
 
-Now you can use `diffray` anywhere!
+Costs depend on your AI provider's pricing. Claude Code uses your Anthropic account or Claude Pro subscription. Cursor Agent uses your Cursor subscription.
 
-## Usage
+**Tips to reduce costs:**
+- Review smaller changesets more frequently
+- Use `--agent` flag to run only specific agents
+- Use `--skip-validation` to skip the validation stage (faster but more false positives)
 
-### Run Pipeline
+## How It Works
 
-```bash
-# Run code review pipeline
-diffray
+### Pipeline
 
-# Output:
-# ⚡ diffray - AI Code Review
-#
-# ■ Analyzing changes...
-# ◇ 8 files: 7 modified, 1 added
-#    624 changes: +612 -12
-# ◉ Loading agents...
-# ✓ Loaded 2 agent(s)
-#
-# ↻ Running 2 agent(s) in parallel...
-# ✓ Custom Code Review (101ms)
-# ✓ Security Scanner (101ms)
-#
-# ✓ Pipeline completed successfully in 102ms
-# ■ 2/2 agents succeeded
-
-# Verbose mode (shows file details and prompts)
-diffray --verbose
-
-# JSON output (machine-readable)
-diffray --json
+```
+┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
+│  Git Diffs  │───▶│ Match Rules │───▶│ Run Agents  │───▶│  Deduplicate│
+└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
+                                            │                   │
+                                            ▼                   ▼
+                                      ┌─────────────┐    ┌─────────────┐
+                                      │  Agent 1    │    │  Validate   │
+                                      │  Agent 2    │    │  (filter    │
+                                      │  Agent 3    │    │   false +)  │
+                                      │  ...        │    └─────────────┘
+                                      └─────────────┘           │
+                                                                ▼
+                                                         ┌─────────────┐
+                                                         │   Report    │
+                                                         └─────────────┘
+```
+
+### Agents
+
+diffray uses multiple specialized AI "agents" that each focus on one type of problem:
+
+| Agent | What it finds |
+|-------|---------------|
+| `general` | Code quality, readability, simplicity issues |
+| `bug-hunter` | Logic errors, null checks, edge cases |
+| `security-scan` | Vulnerabilities, exposed secrets |
+| `performance-check` | Memory leaks, slow code |
+| `consistency-check` | Inconsistent patterns, naming conventions |
+
+Each agent analyzes your code independently, then results are:
+1. **Deduplicated** - remove duplicates if multiple agents found the same issue
+2. **Validated** - AI double-checks each issue to filter out false alarms
+
+Only verified issues are shown in the final report.
+
+> **Want to understand the architecture?** See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for details on agents, executors, and the stage pipeline.
+
+## Configuration (Optional)
+
+diffray works out of the box with sensible defaults. Create `.diffray.json` in your project to customize:
+
+### Example configuration
+
+```json
+{
+  "excludePatterns": [
+    "**/*.test.ts",
+    "**/*.spec.ts",
+    "**/__tests__/**",
+    "dist/**"
+  ],
+  "concurrency": 6,
+  "executor": "claude-cli",
+  "agents": {
+    "performance-check": { "enabled": false },
+    "bug-hunter": { "model": "haiku", "timeout": 60 }
+  },
+  "rules": {
+    "code-security": { "enabled": false }
+  },
+  "executors": {
+    "claude-cli": {
+      "review": { "model": "sonnet", "timeout": 120, "concurrency": 6 },
+      "validation": { "model": "opus", "timeout": 180, "batchSize": 10 }
+    }
+  }
+}
+```
 
-# Filter by severity (show only critical)
-diffray --severity=critical
+### Options reference
 
-# Filter by multiple severities (critical and high)
-diffray --severity=critical,high
+| Option | Description |
+|--------|-------------|
+| `extends` | Load agents/rules from git repos (e.g., `["https://github.com/owner/repo#v1.0"]`) |
+| `excludePatterns` | Glob patterns for files to skip |
+| `concurrency` | Max parallel agents (1-10, default: **6**). Stage-specific settings override this. |
+| `executor` | Which executor to use (`claude-cli`, `cursor-agent-cli`) |
+| `agents.<name>` | Override agent settings (`enabled`, `model`, `timeout`) |
+| `rules.<name>` | Override rule settings (`enabled`, `agent`) |
+| `executors.<name>.<stage>` | Per-executor, per-stage settings (`model`, `timeout`, `concurrency`, `batchSize`) |
 
-# Combine options
-diffray --json --severity=critical
+### Extends
 
-# Output includes:
-#    ~ README.md: +141 -5
-#    ~ src/cli.ts: +107 -3
-#    + src/config.test.ts: +52 -0
-#    ...
+Share agents and rules across projects by loading them from any git repository:
+
+```json
+{
+  "extends": [
+    "https://github.com/diffray/diffray-rules"
+  ]
+}
 ```
 
-### Manage Agents
+Supports any git URL:
+- `https://github.com/owner/repo` — HTTPS, default branch
+- `https://github.com/owner/repo#v1.0` — specific tag/branch
+- `git@github.com:owner/repo.git` — SSH format
+
+Then run `diffray extends install` to download. Agents/rules from extends have lower priority than local ones.
+
+### Config commands
 
 ```bash
-# List all agents
-diffray agents list
+# Create config file
+diffray config init
 
-# Show agent details
-diffray agents show bug-hunter
+# Edit config in your editor
+diffray config edit
+
+# Show current config
+diffray config show
 ```
 
-**Creating Custom Agents:**
+## Creating Custom Agents
+
+You can create your own agents to check for anything you want! Agents are simple Markdown files.
+
+### Where to put agent files
 
-Agents are defined using Markdown files! See [Agent Configuration Guide](./docs/AGENTS.md) for details.
+| Location | When to use |
+|----------|-------------|
+| `~/.diffray/agents/` | Your personal agents (work in all projects) |
+| `.diffray/agents/` | Project-specific agents (share with team via git) |
 
-Create a new `.md` file in `~/.diffray/agents/` or `.diffray/agents/` with frontmatter and a system prompt.
+### Agent file format
 
-### Manage Executors
+Each agent is a `.md` file with two parts:
+
+1. **Header** (between `---` lines) - settings in YAML format
+2. **Body** - instructions for the AI (what to look for)
+
+### Step-by-step: Create your first agent
+
+**Step 1.** Create the folder (if it doesn't exist):
 
 ```bash
-# List all executors
-diffray executors list
+mkdir -p ~/.diffray/agents
+```
+
+**Step 2.** Create a new file `~/.diffray/agents/my-rules.md`:
+
+```markdown
+---
+name: my-rules
+description: Checks for my team's coding standards
+enabled: true
+---
+
+You are a code reviewer checking for our team's coding standards.
 
-# Show executor details
-diffray executors show claude-cli
+## What to check:
 
-# Enable/disable executors
-diffray executors enable cerebras-api
-diffray executors disable claude-cli
+1. **No console.log** - All console.log statements should be removed before commit
+2. **Function comments** - All exported functions must have a description comment
+3. **Error handling** - All async functions must have try/catch blocks
+4. **Naming** - Variables should have meaningful names (no single letters except in loops)
+
+## How to report:
+
+- Only report clear violations
+- Be specific about what line and what's wrong
+- Suggest how to fix it
+```
+
+**Step 3.** Verify your agent is loaded:
+
+```bash
+diffray agents
 ```
 
-### Manage Rules
+You should see `my-rules` in the list.
 
-Rules allow you to run different agents on different file types using glob patterns. Rules are defined in Markdown files.
+**Step 4.** Run a review - your agent will now analyze your code!
 
 ```bash
-# List all rules
-diffray rules list
+diffray
+```
 
-# Show rule details
-diffray rules show code-bugs
+### Header fields explained
 
-# Test rule matching against specific files
-diffray rules test code-bugs src/cli.ts src/agents.ts README.md
-# Output:
-# ✓ Matched 2 file(s):
-#   ● src/cli.ts
-#   ● src/agents.ts
-# Not matched 1 file(s):
-#   ○ README.md
+```yaml
+---
+name: my-rules              # Unique ID (lowercase, use dashes)
+description: What it does   # Short description
+enabled: true               # Set to false to disable temporarily
+order: 10                   # Lower = runs first (optional, default: 0)
+---
 ```
 
-**Creating Custom Rules:**
+### Example agents
 
-Create a new `.md` file in `~/.diffray/rules/` or `.diffray/rules/` with frontmatter:
+#### React best practices checker
 
 ```markdown
 ---
-name: my-rule
-description: Description of what this rule does
-patterns:
-  - "**/*.ts"
-  - "**/*.tsx"
-agent: bug-hunter
+name: react-checker
+description: Checks React code for common mistakes
+enabled: true
 ---
 
-Additional instructions for the agent when this rule matches.
+You are a React expert reviewing code for common mistakes.
+
+## Check for:
+
+1. **Missing keys in lists** - All .map() rendering elements need unique key props
+2. **useEffect dependencies** - Missing dependencies in useEffect arrays
+3. **State mutations** - Direct state mutations instead of setState
+4. **Memory leaks** - Missing cleanup in useEffect (event listeners, subscriptions)
+
+## Ignore:
+- Styling preferences
+- Minor formatting issues
 ```
 
-**Default Rules:**
-- `code-bugs`: Run bug-hunter on code files `**/*.{ts,tsx,js,jsx,py,go,rs,java,rb,php}`
-- `code-security`: Run security-scan on code files `**/*.{ts,tsx,js,jsx,py,go,rs,java,rb,php}`
-- `config-security`: Run security-scan on config files `**/*.{json,yaml,yml,toml}`
+#### API security checker
 
-### Configuration
+```markdown
+---
+name: api-security
+description: Checks API endpoints for security issues
+enabled: true
+---
 
-diffray stores configuration in `~/.diffray/config.json`. This file stores executor settings and other preferences.
+You are a security engineer reviewing API code.
 
-```bash
-# Initialize configuration file
-diffray config init
+## Check for:
 
-# Show current configuration
-diffray config show
+1. **Missing authentication** - Endpoints without auth checks
+2. **SQL injection** - User input in SQL queries without parameterization
+3. **Missing rate limiting** - Public endpoints without rate limits
+4. **Exposed secrets** - API keys, passwords, tokens in code
 
-# Edit configuration in your $EDITOR
-diffray config edit
+## Report format:
+- Severity: CRITICAL for exploitable issues, HIGH for potential issues
+- Include the specific line and code snippet
+- Explain the attack vector
+- Provide a fix
+```
 
-# Reset to defaults
-diffray config reset
+#### TypeScript strict checker
+
+```markdown
+---
+name: typescript-strict
+description: Enforces strict TypeScript practices
+enabled: true
+---
+
+You are a TypeScript expert checking for type safety.
+
+## Check for:
+
+1. **any type** - Usage of 'any' type (should be specific type or 'unknown')
+2. **Type assertions** - Unnecessary 'as' casts that could hide errors
+3. **Missing null checks** - Accessing properties that could be null/undefined
+4. **Implicit any** - Function parameters without type annotations
+
+## Ignore:
+- Third-party library types
+- Test files
 ```
 
-#### Configuration Structure
+### Tips for writing good agents
 
-The configuration file has the following structure:
+1. **Be specific** - "Check for console.log" is better than "check for debug code"
+2. **Give examples** - Show what bad code looks like
+3. **Set priorities** - Tell the AI what's important vs minor
+4. **Define what to ignore** - Reduce false positives
 
-```json
+### Managing agents
+
+```bash
+# List all agents (shows name, description, enabled status)
+diffray agents
+
+# Show full details of an agent
+diffray agents bug-hunter
+
+# Disable an agent via config (without deleting the file)
+# Add to .diffray.json:
 {
-  "excludePatterns": ["*.lock", "*.min.js", "dist/*", "node_modules/**"],
-  "output": {
-    "colorize": true,
-    "verbose": false,
-    "format": "terminal"
-  },
-  "executors": [...],
-  "stages": [...]
+  "agents": {
+    "my-rules": { "enabled": false }
+  }
 }
 ```
 
-**Key Sections:**
+### Troubleshooting
 
-- `excludePatterns`: File patterns to exclude from review (array of glob patterns)
-- `output.colorize`: Enable colored output (boolean, default: `true`)
-- `output.verbose`: Show verbose output (boolean, default: `false`)
-- `output.format`: Output format - `terminal`, `markdown`, or `json` (default: `terminal`)
-- `executors`: Executor configurations (managed via `diffray executors` commands)
-- `stages`: Pipeline stage configurations with enabled/disabled status
+**Agent not showing up?**
+- Check file has `.md` extension
+- Check file is in correct folder (`~/.diffray/agents/` or `.diffray/agents/`)
+- Check YAML header syntax (must be between `---` lines)
 
-**Dynamic Data (loaded from MD files on each run):**
-- `agents`: Loaded from `~/.diffray/agents/`, `.diffray/agents/`, `src/defaults/agents/`
-- `rules`: Loaded from `~/.diffray/rules/`, `.diffray/rules/`, `src/defaults/rules/`
+**Agent not finding issues?**
+- Make instructions more specific
+- Add examples of what to look for
+- Check `enabled: true` in header
 
-### Executors Configuration
+## Creating Custom Rules
 
-Executors define **how** to run Agents. diffray supports multiple executor types:
+Rules connect agents to files. They tell diffray: "Run this agent on these files".
 
-- **CLI Executors** - Run CLI tools like `claude`, `auggie`, etc.
-- **LLM API Executors** - Call LLM APIs directly (Claude, GPT, etc.)
+### What are rules?
 
-Executors are configured in `~/.diffray/config.json`.
+By default, diffray runs ALL agents on ALL changed files. But with rules you can:
 
-#### Executor Configuration
+- Run `security-scan` agent **only** on `*.ts` files
+- Run `python-checker` agent **only** on `*.py` files
+- Add extra instructions for specific file types
 
-Executors can be configured in `~/.diffray/config.json`:
+### Where to put rule files
 
-```json
-{
-  "executors": [
-    {
-      "name": "claude-cli",
-      "enabled": true,
-      "model": "opus",
-      "timeout": 180
-    },
-    {
-      "name": "cerebras-api",
-      "enabled": true,
-      "model": "llama-3.1-8b",
-      "temperature": 0.5,
-      "maxTokens": 4096
-    }
-  ]
-}
+| Location | When to use |
+|----------|-------------|
+| `~/.diffray/rules/` | Your personal rules (work in all projects) |
+| `.diffray/rules/` | Project-specific rules (share with team via git) |
+
+### Rule file format
+
+Rules are also Markdown files with a header:
+
+```markdown
+---
+name: frontend-bugs
+description: Bug detection for React frontend
+patterns:
+  - "src/components/**/*.tsx"
+  - "src/hooks/**/*.ts"
+agent: bug-hunter
+---
+
+Extra instructions for this rule (optional).
+
+Focus on React-specific issues like:
+- Missing useCallback/useMemo
+- Incorrect dependency arrays
+```
+
+### Step-by-step: Create your first rule
+
+**Step 1.** Create the folder:
+
+```bash
+mkdir -p ~/.diffray/rules
+```
+
+**Step 2.** Create `~/.diffray/rules/python-security.md`:
+
+```markdown
+---
+name: python-security
+description: Security checks for Python files
+patterns:
+  - "**/*.py"
+agent: security-scan
+---
+
+Focus on Python-specific security issues:
+
+1. **eval() and exec()** - Dynamic code execution
+2. **pickle** - Insecure deserialization
+3. **subprocess** - Command injection via shell=True
+4. **SQL** - String formatting in SQL queries
+5. **YAML** - yaml.load() without safe_load
+```
+
+**Step 3.** Verify your rule is loaded:
+
+```bash
+diffray rules
+```
+
+**Step 4.** Test which files match your rule:
+
+```bash
+diffray rules python-security --test src/
 ```
 
-#### Executor Options
+### Header fields explained
 
-**CLI Executors (claude-cli):**
-- `enabled` - Enable/disable executor
-- `model` - Model to use (default: `sonnet`)
-- `timeout` - Timeout in seconds (default: 120)
+```yaml
+---
+name: python-security       # Unique ID (lowercase, use dashes)
+description: What it does   # Short description
+patterns:                   # Which files to match (glob patterns)
+  - "**/*.py"               # All Python files
+  - "scripts/*.sh"          # Shell scripts in scripts/ folder
+agent: security-scan        # Which agent to run on matched files
+---
+```
 
-**API Executors (cerebras-api):**
-- `enabled` - Enable/disable executor
-- `model` - Model to use (default: `llama-3.3-70b`)
-- `temperature` - Temperature (default: 0.7)
-- `maxTokens` - Max tokens (default: 8192)
+### Understanding patterns (glob syntax)
 
-#### Linking Agents to Executors
+Patterns use "glob" syntax to match files:
 
-Agents reference executors via the `executor` field in their Markdown configuration:
+| Pattern | What it matches |
+|---------|-----------------|
+| `*.ts` | All `.ts` files in root folder only |
+| `**/*.ts` | All `.ts` files in any folder |
+| `src/**/*.ts` | All `.ts` files inside `src/` folder |
+| `src/*.ts` | Only `.ts` files directly in `src/` (not subfolders) |
+| `**/*.{ts,tsx}` | All `.ts` and `.tsx` files |
+| `!**/*.test.ts` | Exclude test files (prefix with `!`) |
+
+### Example rules
+
+#### Backend API security
 
 ```markdown
 ---
-name: bug-hunter
-executor: claude-cli
+name: api-security
+description: Security review for API endpoints
+patterns:
+  - "src/api/**/*.ts"
+  - "src/routes/**/*.ts"
+  - "src/controllers/**/*.ts"
+agent: security-scan
+---
+
+Focus on API security:
+
+1. Check authentication on all endpoints
+2. Validate all user input
+3. Check for SQL/NoSQL injection
+4. Verify rate limiting
+5. Check CORS configuration
+```
+
+#### React components quality
+
+```markdown
 ---
+name: react-quality
+description: Quality checks for React components
+patterns:
+  - "src/components/**/*.tsx"
+  - "src/pages/**/*.tsx"
+agent: bug-hunter
+---
+
+Focus on React best practices:
+
+1. Missing key props in lists
+2. useEffect dependency arrays
+3. Memory leaks (missing cleanup)
+4. Prop types validation
+5. Conditional rendering bugs
 ```
 
-## Agent Configuration
+#### Config files security
 
-Agents are configured using **Markdown files** in `src/defaults/agents/`. See the [Agent Configuration Guide](./docs/AGENTS.md) for complete documentation.
+```markdown
+---
+name: config-security
+description: Check config files for exposed secrets
+patterns:
+  - "**/*.json"
+  - "**/*.yaml"
+  - "**/*.yml"
+  - "**/*.env.example"
+agent: security-scan
+---
+
+Check for:
 
-### Agent Markdown Format
+1. Hardcoded API keys or tokens
+2. Database credentials
+3. Private keys
+4. Sensitive URLs
+```
 
-Each agent is defined in a `.md` file with frontmatter metadata:
+#### Documentation checker
+
+```markdown
+---
+name: docs-quality
+description: Check documentation for issues
+patterns:
+  - "**/*.md"
+  - "docs/**/*"
+agent: general
+---
+
+Check documentation for:
+
+1. Broken links
+2. Outdated code examples
+3. Missing sections
+4. Typos in commands
+```
+
+### Default rules (built-in)
+
+diffray comes with these rules out of the box:
+
+| Rule | Files | Agent |
+|------|-------|-------|
+| `code-general` | `*.ts, *.js, *.py, *.go, *.rs, *.java, *.rb, *.php, ...` | `general` |
+| `code-bugs` | Same as above | `bug-hunter` |
+| `code-security` | Same as above | `security-scan` |
+| `code-performance` | Same as above | `performance-check` |
+| `code-consistency` | Same as above + `*.md, *.json, *.yaml` | `consistency-check` |
+| `config-security` | `*.json, *.yaml, *.yml, *.toml` | `security-scan` |
+
+### Managing rules
+
+```bash
+# List all rules
+diffray rules
+
+# Show rule details
+diffray rules code-bugs
+
+# Test which files a rule matches
+diffray rules code-bugs --test src/
+
+# Disable a rule via config
+# Add to .diffray.json:
+{
+  "rules": {
+    "code-performance": { "enabled": false }
+  }
+}
+```
+
+### Rules vs Agents: What's the difference?
+
+| | Agent | Rule |
+|---|-------|------|
+| **What** | The AI reviewer (what to check) | The file filter (where to check) |
+| **Contains** | Instructions for AI | File patterns + which agent to use |
+| **Example** | "Check for SQL injection" | "Run security-scan on *.py files" |
+
+**Think of it this way:**
+- **Agent** = The inspector (knows what problems to look for)
+- **Rule** = The assignment (tells inspector which rooms to check)
+
+### Troubleshooting
+
+**Rule not matching files?**
+- Check pattern syntax (use `**/*.ts` not `*.ts` for recursive)
+- Test with `diffray rules your-rule --test path/`
+- Remember patterns are relative to project root
+
+**Agent not running on expected files?**
+- Make sure rule's `agent` field matches an existing agent name
+- Check that both rule and agent have `enabled: true`
+
+## Overriding Agents and Rules
+
+Besides config file overrides (see [Configuration](#configuration-optional)), you can completely replace built-in agents/rules by creating files with the same name.
+
+**Priority order (highest to lowest):**
+1. `.diffray/agents/` or `.diffray/rules/` (project folder)
+2. `~/.diffray/agents/` or `~/.diffray/rules/` (home folder)
+3. Built-in defaults
+
+**Example:** To replace the built-in `bug-hunter` agent:
+
+```bash
+mkdir -p .diffray/agents
+```
+
+Create `.diffray/agents/bug-hunter.md`:
 
 ```markdown
 ---
 name: bug-hunter
-description: Detects bugs, logic errors and runtime issues
+description: My custom bug hunter
 enabled: true
-executor: claude-cli
 ---
 
-You are a code reviewer analyzing changes for:
+Your completely custom instructions here...
+```
+
+## FAQ
 
-### Logic Errors
-- Identify bugs and edge cases
-- Check error handling
+### Why is it slow?
 
-### Code Quality
-- Assess readability
-- Check naming conventions
+diffray uses Claude AI which takes time to analyze code properly. Typical review takes 10-30 seconds. For faster (but less accurate) reviews, use:
+
+```bash
+diffray --skip-validation
 ```
 
-The system automatically loads all `.md` files from `~/.diffray/agents/`, `.diffray/agents/`, and `src/defaults/agents/`.
+### Why didn't it find an obvious bug?
+
+AI isn't perfect. diffray is tuned for **low false positives** (fewer wrong alerts) rather than finding every possible issue. If you think it missed something, please [open an issue](https://github.com/diffray/diffray/issues).
+
+### Can I use it in CI/CD?
 
-## Example Output
+Yes! Use `--json` flag for machine-readable output:
 
+```bash
+diffray --json --severity critical,high
 ```
-⚡ diffray - AI Code Review
 
-■ Analyzing changes...
+Exit code is non-zero if issues are found.
+
+**GitHub Actions example:**
 
-Summary: 2 modified, 1 added
+```yaml
+name: Code Review
+on: [pull_request]
 
-================================================================================
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
-src/index.ts (modified)
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
 
-+ export function greet(name: string): string {
-+   return `Hello, ${name}!`;
-+ }
+      - run: npm install -g diffray @anthropic-ai/claude-code
 
---------------------------------------------------------------------------------
+      - run: claude auth login --api-key ${{ secrets.ANTHROPIC_API_KEY }}
 
-✓ Reviewed 3 file(s)
+      - run: diffray --base origin/${{ github.base_ref }} --json --severity critical,high
 ```
 
+### How much does it cost?
+
+The CLI is free, but uses Claude AI which has API costs. With Claude Code CLI, costs are typically $0.01-0.05 per review.
+
+## Get Results in Your PRs
+
+Want automated reviews directly in GitHub Pull Requests?
+
+**Sign up at [diffray.ai](https://diffray.ai)** - connect your repo and get AI review comments on every PR automatically.
+
 ## Development
 
 ```bash
-# Run in development mode
-bun run dev
+# Clone the repo
+git clone https://github.com/diffray/diffray.git
+cd diffray
 
-# Build standalone binary
-bun run build
+# Install dependencies
+npm install
 
-# Run tests
-bun test
-```
+# Run in dev mode
+npm run dev
 
-## Project Structure
+# Run tests
+npm test
 
+# Build
+npm run build
 ```
-diffray/
-├── bin/
-│   └── diffray.ts           # CLI entry point
-├── src/
-│   ├── cli.ts               # Main CLI logic
-│   ├── pipeline.ts          # Pipeline execution
-│   ├── stages/              # Pipeline stages
-│   ├── agents/              # Agent registry and loaders
-│   ├── executors/           # Executor implementations
-│   ├── commands/            # CLI commands
-│   ├── defaults/            # Default agents and rules (Markdown)
-│   ├── git.ts               # Git operations
-│   └── issue-formatter.ts   # Issue formatting
-└── package.json
-```
-
-## Built With
 
-- [Bun](https://bun.sh) - Fast JavaScript runtime
-- TypeScript - Type safety
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed development guidelines.
 
 ## License
 
 MIT
+
+---
+
+**[Changelog](CHANGELOG.md)** · **[Contributing](CONTRIBUTING.md)** · **[Architecture](docs/ARCHITECTURE.md)**