docs: add MkDocs documentation site and align with team health philosophy

- **Documentation Site**: MkDocs with Material theme, dark mode, search, and feedback
- **Philosophy Alignment**: Updated README and docs to focus on team health, not individual performance
- **Real-World Use Case**: Added comprehensive team analysis example
- **Security**: Updated MCP SDK to fix DNS rebinding vulnerability
- **Code Quality**: Added ESLint with TypeScript support, fixed all linting issues
- **Dependencies**: Updated express to 5.2.1

Author: jonmatum

.github/workflows/docs.yml

@@ -0,0 +1,30 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      
+      - name: Install MkDocs
+        run: pip install mkdocs-material
+      
+      - name: Deploy
+        run: mkdocs gh-deploy --force

.gitignore

@@ -6,3 +6,6 @@ build/
 coverage/
 test-repo/
 
+
+# MkDocs
+site/

.npmignore

@@ -1,8 +1,29 @@
+# Source files
 src/
+*.test.ts
+
+# Build config
+tsconfig.json
+vitest.config.ts
+
+# Development
 node_modules/
+coverage/
+.vscode/
+.idea/
+
+# Git
 .git/
 .gitignore
-tsconfig.json
+.github/
+
+# Docs (use GitHub Pages)
+docs/
+mkdocs.yml
+site/
+
+# Misc
 *.log
 .DS_Store
 .env
+.npmignore

README.md

@@ -1,10 +1,12 @@
 # Git Metrics MCP Server
 
-MCP server for analyzing git repository metrics and tracking team performance KPIs. Built for Kiro CLI (Amazon Q CLI) and other MCP clients.
+MCP server for analyzing git repository metrics and understanding team health. Built for Kiro CLI (Amazon Q CLI) and other MCP clients.
 
 ## Overview
 
-This server provides tools to extract meaningful metrics from git repositories, helping teams track productivity, code quality, and collaboration patterns.
+This server provides tools to extract meaningful metrics from git repositories, helping teams understand their development patterns, identify risks early, and have better conversations about code quality and team health.
+
+**This is a mirror, not a microscope.** Use it to reflect on team health and process quality, not to surveil individual behavior. See [INTENT.md](INTENT.md) for our philosophy on responsible metrics usage.
 
 ## Features
 
@@ -419,60 +421,143 @@ Analyze conventional commit usage and release patterns.
 }
 ```
 
+## Real-World Use Case: Team Health Analysis
+
+Here's how a real engineering team used this tool to understand their development patterns across 5 repositories with 83 contributors:
+
+### The Challenge
+A team needed to understand their development health across multiple repositories without manually parsing git logs. They wanted to identify risks, improve collaboration, and ensure sustainable work practices.
+
+### What They Discovered
+
+**Team Health Insights:**
+- ✅ Excellent work-life balance: Only 1.3% weekend commits
+- ✅ Strong release discipline: 114 releases with 86.3% conventional commit adoption
+- ⚠️ Bus factor risk: Two developers owned 61% of exclusive files in one repo
+- ⚠️ High fix rate (36.3%) indicated reactive development in one project
+
+**Collaboration Patterns:**
+- Best practice: One repo had 88.9% shared files (excellent knowledge distribution)
+- Needs improvement: Another repo had only 30.5% shared files
+- Identified top collaboration pairs for knowledge sharing
+
+**Code Quality Indicators:**
+- Found complexity hotspots: Files with 66+ changes needing refactoring
+- Identified technical debt: Stale files and high-churn areas
+- Discovered optimal commit patterns: Median 17 lines (focused commits)
+
+### Actions Taken
+1. **Immediate:** Scheduled knowledge transfer sessions for high bus factor areas
+2. **Process:** Implemented pair programming to increase file sharing
+3. **Quality:** Added pre-commit hooks to reduce fix rate
+4. **Culture:** Replicated best practices from high-performing repos
+
+**Time Saved:** What would have taken days of manual analysis was completed in minutes with natural language queries.
+
+**Read the full analysis:** [team-activity-analysis.md](team-activity-analysis.md)
+
+---
+
 ## Use Cases
 
-### Sprint Retrospectives
+### ✅ Good Use Cases
+
+**Sprint Retrospectives**
 ```
 Show me team summary and velocity trends for the last 2 weeks
 What's our commit pattern? Are we burning out?
 ```
 
-### Performance Reviews
+**Risk Management**
 ```
-Get author metrics for john@example.com since last quarter
-Compare their velocity to team average
+What's our bus factor? Who are single points of failure?
+Show me code ownership - where do we have knowledge concentration?
 ```
 
-### Code Quality Reviews
+**Code Quality Reviews**
 ```
 Show me quality metrics and technical debt
 What files have high churn and need refactoring?
 ```
 
-### Team Health Checks
+**Team Health Checks**
 ```
-What's our bus factor? Who are single points of failure?
+Are people committing late at night or on weekends?
 Show me collaboration metrics - is the team working together?
 ```
 
-### Onboarding Tracking
+**Onboarding Support**
 ```
 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
+### ❌ What This Is NOT For
+
+- ❌ Micromanagement or surveillance
+- ❌ Comparing developers against each other
+- ❌ Performance review ammunition
+- ❌ Daily productivity tracking
+
+**See [INTENT.md](INTENT.md) for our philosophy on responsible metrics usage.**
 
-- **Velocity**: Commits per developer per week/sprint
-- **Code Volume**: Lines added/deleted
-- **Activity**: Files changed
+## Team Health Indicators You Can Track
+
+### Risk Management
+- **Bus Factor**: Knowledge concentration risk - who are single points of failure?
+- **Code Ownership**: File sharing patterns - is knowledge distributed?
+- **Technical Debt**: Stale files, complexity hotspots needing attention
+
+### Team Well-being
+- **Burnout Indicators**: Weekend/late-night commits - is the team overworked?
+- **Work Patterns**: When people commit - are boundaries healthy?
+- **Velocity Trends**: Sustainable pace or sprint-and-crash cycles?
+
+### Code Quality
 - **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
+- **Commit Size**: Focused commits vs. large dumps
+- **Revert Rate**: How often do we undo work?
+- **Fix Rate**: Reactive (high fixes) vs. proactive development
+
+### Collaboration Health
+- **File Sharing**: How much code is touched by multiple people?
+- **Collaboration Pairs**: Who works together most often?
+- **Contribution Balance**: Even distribution or bottlenecks?
+
+### Process Maturity
+- **Conventional Commits**: Adoption rate of commit standards
+- **Release Frequency**: How often do we ship?
+- **Breaking Changes**: How disruptive are our releases?
+
+## Tips for Responsible Usage
 
-## Tips for Best Results
+### How to Use This Tool Well
 
 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
+2. **Focus on trends, not snapshots**: Weekly/monthly patterns matter more than daily counts
+3. **Combine metrics**: Ask for multiple analyses to get the full picture
+4. **Start conversations, don't end them**: Use data to ask "why?" not to judge
+5. **Look for patterns**: Team health indicators, not individual performance scores
+6. **Regular reviews**: Weekly health checks (5 min), sprint retrospectives (15 min), monthly trends (30 min)
+
+### Red Flags (Don't Do This)
+
+- ❌ Checking metrics more than once per day
+- ❌ Creating leaderboards or rankings
+- ❌ Setting commit quotas or targets
+- ❌ Using metrics in performance reviews without context
+- ❌ Comparing developers directly
+
+### Green Flags (Good Usage)
+
+- ✅ You check trends weekly/monthly, not daily
+- ✅ You ask "what does this tell us about our process?"
+- ✅ You use it to start conversations, not end them
+- ✅ You focus on team health, not individual performance
+- ✅ You look for patterns, not outliers
+- ✅ You use it to help, not judge
+
+**Remember:** The best teams are built on trust, not metrics. Use this tool to support your team, not surveil them.
 
 ## Development
 

docs/git-metrics-analysis-prompt.md

@@ -0,0 +1,78 @@
+# Git Metrics Analysis Prompt
+
+Use this prompt with Kiro CLI to generate comprehensive team activity reports for any repository collection.
+
+## Prompt
+
+```
+Use my git-metrics MCP server to analyze team health and development patterns across all repositories in this path.
+
+IMPORTANT: This analysis is for team reflection, process improvement, and risk management—NOT individual performance evaluation. Focus on collaboration patterns, sustainable practices, and code quality trends.
+
+Include:
+- Team collaboration patterns and file sharing
+- Bus factor and knowledge distribution risks
+- Work-life balance indicators (weekend/late-night commits)
+- Code quality trends (commit size, revert rate, fix rate)
+- Velocity trends and sustainable pace
+- Technical debt hotspots (stale files, high churn)
+- Release discipline and conventional commit adoption
+- Cross-team collaboration patterns
+
+Generate a comprehensive markdown report with:
+1. Executive summary highlighting team health
+2. Repository-level insights on collaboration and quality
+3. Risk identification (bus factor, technical debt)
+4. Process improvement recommendations (not individual critiques)
+5. Team health score and best practices to replicate
+
+Frame all findings as conversation starters for team improvement, not as judgments of individual performance.
+
+Analyze from 2024-01-01 to present.
+```
+
+## Usage
+
+1. Navigate to the directory containing your repositories:
+   ```bash
+   cd /path/to/your/repos
+   ```
+
+2. Start Kiro CLI:
+   ```bash
+   kiro-cli chat
+   ```
+
+3. Paste the prompt above
+
+4. The analysis will be saved as `team-activity-analysis.md` in the current directory
+
+## Customization
+
+To analyze a different time period, modify the prompt:
+```
+Analyze from YYYY-MM-DD to present.
+```
+
+To focus on specific repositories:
+```
+Focus the analysis on these repositories: repo1, repo2, repo3
+```
+
+To change the output filename, add:
+```
+Save the report as custom-report-name.md
+```
+
+## MCP Server Requirements
+
+Ensure the git-metrics MCP server is configured in your Kiro CLI setup with these capabilities:
+- get_team_summary
+- get_code_ownership
+- get_velocity_trends
+- get_quality_metrics
+- get_collaboration_metrics
+- get_commit_patterns
+- get_technical_debt
+- get_file_churn
+- get_conventional_commits

docs/index.md

@@ -0,0 +1,56 @@
+# Git Metrics MCP Server
+
+MCP server for analyzing git repository metrics and understanding team health.
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install -g @jonmatum/git-metrics-mcp-server
+```
+
+### Kiro CLI Configuration
+
+Add to `~/.kiro/settings/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "git-metrics": {
+      "command": "git-metrics-mcp-server",
+      "args": []
+    }
+  }
+}
+```
+
+### Usage
+
+```bash
+kiro-cli chat
+```
+
+Ask natural language questions:
+```
+Get commit stats for /home/user/myproject since 2025-11-01
+Show me team summary for the last 2 weeks
+What's our bus factor?
+```
+
+## Documentation
+
+- **[Philosophy](intent.md)** - Responsible usage guidelines
+- **[Analysis Prompt](git-metrics-analysis-prompt.md)** - Copy-paste prompt for comprehensive analysis
+
+## Features
+
+- Commit statistics and author metrics
+- File churn analysis
+- Team collaboration patterns
+- Burnout detection (commit patterns)
+- Bus factor analysis
+- Velocity trends
+- Quality metrics
+- Technical debt identification
+- Conventional commits analysis