docs: update README with comprehensive usage examples

- Add natural language query examples for all tools
- Include use case scenarios (sprint retros, performance reviews, etc)
- Add tips for getting the most value from the MCP
- Expand tool documentation with example queries

Author: jonmatum

README.md

@@ -12,6 +12,12 @@ This server provides tools to extract meaningful metrics from git repositories,
 - **Author Metrics**: Per-developer performance breakdown
 - **File Churn Analysis**: Identify frequently modified files (quality indicators)
 - **Team Summaries**: Comprehensive team performance reports
+- **Commit Patterns**: Analyze when people commit (burnout detection)
+- **Code Ownership**: Bus factor and knowledge distribution analysis
+- **Velocity Trends**: Week/month productivity tracking
+- **Collaboration Metrics**: Team interaction patterns
+- **Quality Metrics**: Commit size, reverts, and fix rates
+- **Technical Debt**: Stale files and complexity hotspots
 
 ## Installation
 
@@ -70,6 +76,100 @@ Add to `~/.kiro/settings/mcp.json`:
 }
 ```
 
+## Usage with Kiro CLI
+
+Start Kiro CLI:
+```bash
+kiro-cli chat
+```
+
+Then ask natural language questions about your repositories:
+
+### Basic Metrics
+
+**Get overall stats:**
+```
+Get commit stats for /home/user/myproject since 2025-11-01
+```
+
+**Team breakdown:**
+```
+Show me author metrics for this repo since last month
+```
+
+**Find problematic files:**
+```
+What files have the most churn in /home/user/myproject since October?
+```
+
+### Team Performance
+
+**Sprint retrospective:**
+```
+Generate a team summary for /home/user/project since 2025-11-01
+```
+
+**Individual performance:**
+```
+Get commit stats for /home/user/project since 2025-11-01 for author john@example.com
+```
+
+**Velocity tracking:**
+```
+Show me velocity trends by week for this repo since November
+```
+
+### Code Quality & Health
+
+**Burnout detection:**
+```
+Show me commit patterns for /home/user/project since last month
+Are people committing late at night or on weekends?
+```
+
+**Quality indicators:**
+```
+What are the quality metrics for this repo since last sprint?
+How many reverts and fixes do we have?
+```
+
+**Technical debt:**
+```
+Identify technical debt in /home/user/project
+Show me stale files and complexity hotspots
+```
+
+### Team Collaboration
+
+**Bus factor analysis:**
+```
+What's our bus factor for /home/user/project?
+Who owns critical code areas?
+```
+
+**Collaboration patterns:**
+```
+Show me collaboration metrics for this repo
+Who works together most often?
+```
+
+### Advanced Queries
+
+**Compare time periods:**
+```
+Compare velocity trends for this repo: last month vs this month
+```
+
+**Multi-metric analysis:**
+```
+Analyze /home/user/project: show me quality metrics, technical debt, and bus factor
+```
+
+**Custom date ranges:**
+```
+Get team summary for /home/user/project from 2025-10-01 to 2025-10-31
+```
+
 ## Available Tools
 
 ### get_commit_stats
@@ -82,11 +182,6 @@ Get overall commit statistics for a time period.
 - `until` (optional): End date (YYYY-MM-DD)
 - `author` (optional): Filter by author
 
-**Example:**
-```
-Get commit stats for /home/user/myproject since 2025-11-01
-```
-
 **Returns:**
 ```json
 {
@@ -159,44 +254,177 @@ Comprehensive team performance report.
 }
 ```
 
-## Example Queries
+### get_commit_patterns
 
-**Sprint Review:**
+Analyze when people commit (burnout detection).
+
+**Parameters:**
+- `repo_path` (required): Path to git repository
+- `since` (required): Start date (YYYY-MM-DD)
+- `until` (optional): End date (YYYY-MM-DD)
+
+**Returns:**
+```json
+{
+  "byDay": { "Mon": 45, "Tue": 38, ... },
+  "byHour": { "09": 12, "14": 18, ... },
+  "patterns": {
+    "weekendPercentage": "15.2%",
+    "lateNightPercentage": "8.3%"
+  }
+}
 ```
-Generate a team summary for /home/user/project since 2025-11-01
+
+### get_code_ownership
+
+Bus factor and knowledge distribution.
+
+**Parameters:**
+- `repo_path` (required): Path to git repository
+- `since` (required): Start date (YYYY-MM-DD)
+
+**Returns:**
+```json
+{
+  "totalFiles": 150,
+  "sharedFiles": 80,
+  "soloFiles": 70,
+  "busFactor": [
+    { "author": "John <john@example.com>", "exclusiveFiles": 25 }
+  ]
+}
 ```
 
-**Individual Performance:**
+### get_velocity_trends
+
+Track velocity over time.
+
+**Parameters:**
+- `repo_path` (required): Path to git repository
+- `since` (required): Start date (YYYY-MM-DD)
+- `interval` (optional): "week" or "month", default "week"
+
+**Returns:**
+```json
+{
+  "interval": "week",
+  "trends": [
+    { "period": "2025-11-01", "commits": 45, "additions": 1250, "deletions": 380 }
+  ]
+}
 ```
-Get commit stats for /home/user/project since 2025-11-01 for author john@example.com
+
+### get_collaboration_metrics
+
+Team interaction patterns.
+
+**Parameters:**
+- `repo_path` (required): Path to git repository
+- `since` (required): Start date (YYYY-MM-DD)
+
+**Returns:**
+```json
+{
+  "collaborativeFiles": 80,
+  "topCollaborations": [
+    { "pair": "John <-> Jane", "sharedFiles": 25 }
+  ]
+}
+```
+
+### get_quality_metrics
+
+Code quality indicators.
+
+**Parameters:**
+- `repo_path` (required): Path to git repository
+- `since` (required): Start date (YYYY-MM-DD)
+
+**Returns:**
+```json
+{
+  "averageCommitSize": 125,
+  "medianCommitSize": 85,
+  "revertRate": "2.3%",
+  "fixRate": "18.5%"
+}
+```
+
+### get_technical_debt
+
+Identify technical debt.
+
+**Parameters:**
+- `repo_path` (required): Path to git repository
+- `stale_days` (optional): Days to consider stale, default 90
+
+**Returns:**
+```json
+{
+  "staleFiles": [
+    { "file": "old-module.js", "daysSinceLastChange": 180 }
+  ],
+  "largeFiles": [
+    { "file": "big-file.js", "sizeBytes": 50000, "churn": 25 }
+  ],
+  "complexityHotspots": [ ... ]
+}
 ```
 
-**Code Quality Check:**
+## Use Cases
+
+### Sprint Retrospectives
 ```
-Show me file churn for /home/user/project since 2025-10-01 limit 20
+Show me team summary and velocity trends for the last 2 weeks
+What's our commit pattern? Are we burning out?
 ```
 
-**Weekly Standup:**
+### Performance Reviews
 ```
-Get author metrics for /home/user/project since 2025-11-15
+Get author metrics for john@example.com since last quarter
+Compare their velocity to team average
 ```
 
-## Use Cases
+### Code Quality Reviews
+```
+Show me quality metrics and technical debt
+What files have high churn and need refactoring?
+```
+
+### Team Health Checks
+```
+What's our bus factor? Who are single points of failure?
+Show me collaboration metrics - is the team working together?
+```
 
-- **Sprint Retrospectives**: Review team velocity and contribution patterns
-- **Performance Reviews**: Data-driven developer assessments
-- **Code Quality**: Identify problematic files with high churn
-- **Team Balance**: Ensure even workload distribution
-- **Onboarding**: Track new developer ramp-up
+### Onboarding Tracking
+```
+Get commit stats for new-dev@example.com since their start date
+Show their velocity trend over the first 3 months
+```
 
 ## KPIs You Can Track
 
-- Commits per developer per week/sprint
-- Code volume (lines added/deleted)
-- File change frequency
-- Code churn (quality indicator)
-- Contribution balance across team
-- Commit patterns and consistency
+- **Velocity**: Commits per developer per week/sprint
+- **Code Volume**: Lines added/deleted
+- **Activity**: Files changed
+- **Churn**: Files changed repeatedly (quality indicator)
+- **Contribution Balance**: Even distribution across team
+- **Commit Frequency**: Daily/weekly patterns
+- **Burnout Indicators**: Weekend/late-night commits
+- **Bus Factor**: Knowledge concentration risk
+- **Collaboration**: Team interaction frequency
+- **Quality**: Commit size, revert rate, fix rate
+- **Technical Debt**: Stale files, large files, complexity
+
+## Tips for Best Results
+
+1. **Use natural language**: Kiro understands context, so ask questions naturally
+2. **Combine metrics**: Ask for multiple analyses in one query
+3. **Compare periods**: Track trends over time
+4. **Be specific with dates**: Use "since 2025-11-01" or "last month"
+5. **Filter by author**: Focus on individual or team performance
+6. **Regular reviews**: Run weekly/monthly to track trends
 
 ## Development