docs: Critical documentation refactor - VitePress site with MCP install badges (#133)

* docs: migrate README to VitePress static site with MCP install badges (#24)

- Add VitePress with docs:dev/build/preview scripts
- Create full documentation site: guide, security, advanced, cli, tools
- Migrate all README sections to dedicated pages
- Add GitHub Actions workflow for docs deployment to Pages
- Add MCP one-click install badges (VS Code, VS Code Insiders)
- Create CONTRIBUTING.md with dev setup, testing, and PR guidelines
- Reduce README from 1125 to 129 lines (links to docs site)
- Fix outdated tool count: 62 → 47 (post-CQRS consolidation)
- Remove outdated per-tool listings (replaced by auto-generated TOOLS.md)

* ci(docs): unified Pages deployment with release trigger

* ci(docs): conditional coverage on release only

* docs: clean up README and fix MCP install badge URLs

Remove duplicate author attribution, streamline README structure,
and fix VS Code one-click install deeplinks to use correct
URL-encoded JSON format.

* docs(config): configurable base path and canonical domain links

* ci(docs): set DOCS_BASE=/ for custom domain, add continue-on-error

* ci(docs): add yarn.lock to workflow path triggers

The docs deploy workflow uses `yarn install --immutable` which
depends on yarn.lock. Include it in path filters so lockfile
changes trigger a rebuild.

* docs: clarify opt-in tool groups and read-only exceptions

- Note manage_context exception in read-only mode docs
- Add 'opt-in' label to disabled-by-default feature flags
- Add section header explaining opt-in groups reduce tool count

* docs: fix feature flag defaults, add /register endpoint, set DOCS_BASE

- All feature flags default to true (code uses !== "false" pattern)
- Add /register (Dynamic Client Registration) to OAuth endpoints
- Set DOCS_BASE=/ in local VitePress scripts for correct local preview

* docs: add missing feature flags and fix tool categorization

- Add USE_RELEASES, USE_REFS, USE_MEMBERS, USE_SEARCH to all docs
- Move gated tools out of "Core (Always Available)" into own sections
- Fix Docker example to forward all USE_* flags
- Fix npm example with all 15 feature flags

Author: polaz

.github/workflows/coverage-pages.yml

@@ -1,33 +1,14 @@
-# GitHub Actions Workflow: Deploy Coverage Reports to GitHub Pages
+# GitHub Actions Workflow: Coverage Reports for Pull Requests
 #
-# This workflow runs tests with coverage, generates HTML reports, and deploys
-# them to GitHub Pages for easy viewing of test coverage metrics.
+# This workflow runs tests with coverage on PRs and comments the results.
+# Actual deployment to GitHub Pages is handled by docs.yml workflow.
 #
-# The coverage reports will be available at:
+# Coverage reports on the live site:
 # https://structured-world.github.io/gitlab-mcp/coverage/
-#
-# Triggers:
-# - Push to main branch (updates coverage reports)
-# - Pull requests (generates preview but doesn't deploy)
-# - Manual workflow dispatch
 
-name: Deploy Coverage to GitHub Pages
+name: Coverage Report
 
 on:
-  # Trigger on pushes to main branch
-  push:
-    branches:
-      - main
-    # Only run if relevant files changed
-    paths:
-      - "src/**"
-      - "package.json"
-      - "yarn.lock"
-      - "tsconfig.json"
-      - "jest.config.*"
-      - ".github/workflows/coverage-pages.yml"
-
-  # Trigger on pull requests for preview
   pull_request:
     branches:
       - main
@@ -38,312 +19,102 @@ on:
       - "tsconfig.json"
       - "jest.config.*"
 
-  # Allow manual triggering
-  workflow_dispatch:
-
-# Ensure only one deployment runs at a time
 concurrency:
-  group: pages-${{ github.ref }}
+  group: coverage-${{ github.ref }}
   cancel-in-progress: true
 
-# Set permissions for GitHub Pages deployment and PR comments
 permissions:
   contents: read
-  pages: write
-  id-token: write
   pull-requests: write
   issues: write
-  actions: read
 
 jobs:
-  # Job 1: Generate coverage reports
   coverage:
-    name: Generate Coverage Reports
+    name: Generate Coverage Report
     runs-on: ubuntu-latest
-
-    # Set outputs for use in deployment job
-    outputs:
-      coverage-percentage: ${{ steps.coverage.outputs.percentage }}
-      should-deploy: ${{ steps.should-deploy.outputs.result }}
-
     steps:
-      # Step 1: Check out the repository
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
-      # Step 2: Set up Node.js environment
       - name: Set up Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: "22"
-          # Don't cache yarn yet - enable corepack first
+          node-version: 24
 
-      # Step 3: Enable Corepack for Yarn 4
       - name: Enable Corepack
         run: corepack enable
 
-      # Step 4: Install dependencies
       - name: Install dependencies
         run: yarn install --immutable
 
-      # Step 5: Run tests with coverage
       - name: Run tests with coverage
         run: yarn test:cov
 
-      # Step 6: Extract coverage percentage for badge/display
       - name: Extract coverage percentage
         id: coverage
         run: |
-          # Extract coverage percentage from Jest output
           COVERAGE=$(cat coverage/lcov-report/index.html | grep -o 'class="strong">[0-9.]*%' | head -1 | grep -o '[0-9.]*')
           echo "percentage=${COVERAGE:-0}" >> $GITHUB_OUTPUT
-          echo "Coverage: ${COVERAGE:-0}%"
-
-      # Step 7: Create coverage summary for PR comments
-      - name: Generate coverage summary
-        if: github.event_name == 'pull_request'
-        run: |
-          # Extract coverage metrics from JSON summary (more reliable than HTML parsing)
-          if [ -f coverage/coverage-summary.json ]; then
-            STATEMENTS=$(jq -r '.total.statements.pct' coverage/coverage-summary.json)
-            BRANCHES=$(jq -r '.total.branches.pct' coverage/coverage-summary.json)
-            FUNCTIONS=$(jq -r '.total.functions.pct' coverage/coverage-summary.json)
-            LINES=$(jq -r '.total.lines.pct' coverage/coverage-summary.json)
-          else
-            STATEMENTS="N/A"
-            BRANCHES="N/A"
-            FUNCTIONS="N/A"
-            LINES="N/A"
-          fi
-
-          OVERALL="${{ steps.coverage.outputs.percentage }}"
-
-          # Format percentages (add % only if value is numeric)
-          format_pct() {
-            if [[ "$1" =~ ^[0-9]+(\.[0-9]+)?$ ]]; then
-              echo "${1}%"
-            elif [[ "$1" == "null" ]]; then
-              echo "N/A"
-            else
-              echo "$1"
-            fi
-          }
-          
-          STATEMENTS_FMT=$(format_pct "$STATEMENTS")
-          BRANCHES_FMT=$(format_pct "$BRANCHES")
-          FUNCTIONS_FMT=$(format_pct "$FUNCTIONS")
-          LINES_FMT=$(format_pct "$LINES")
-
-          # Create a markdown summary of coverage
-          cat > coverage-summary.md << EOF
-          ## 📊 Test Coverage Report
 
-          **Overall Coverage:** ${OVERALL}%
-
-          ### Coverage Details
-          | Metric | Percentage |
-          |--------|------------|
-          | Statements | ${STATEMENTS_FMT} |
-          | Branches | ${BRANCHES_FMT} |
-          | Functions | ${FUNCTIONS_FMT} |
-          | Lines | ${LINES_FMT} |
-
-          **Coverage Report:** [View detailed coverage report](https://structured-world.github.io/gitlab-mcp/coverage/)
-
-          > This report was generated automatically from your PR changes.
-          EOF
-
-      # Step 8: Comment coverage summary on PR
       - name: Comment coverage on PR
-        if: github.event_name == 'pull_request'
+        continue-on-error: true
         uses: actions/github-script@v7
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
             const fs = require('fs');
-            const summary = fs.readFileSync('coverage-summary.md', 'utf8');
+            let summary;
 
             try {
-              // Find existing coverage comment
-              const comments = await github.rest.issues.listComments({
+              const json = JSON.parse(fs.readFileSync('coverage/coverage-summary.json', 'utf8'));
+              const t = json.total;
+              summary = [
+                '## Test Coverage Report',
+                '',
+                `**Overall Coverage:** ${t.lines.pct}%`,
+                '',
+                '| Metric | Percentage |',
+                '|--------|------------|',
+                `| Statements | ${t.statements.pct}% |`,
+                `| Branches | ${t.branches.pct}% |`,
+                `| Functions | ${t.functions.pct}% |`,
+                `| Lines | ${t.lines.pct}% |`,
+                '',
+                '[View detailed coverage report](https://structured-world.github.io/gitlab-mcp/coverage/)',
+              ].join('\n');
+            } catch {
+              summary = `## Test Coverage Report\n\n**Coverage:** ${{ steps.coverage.outputs.percentage }}%`;
+            }
+
+            const comments = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+
+            const existing = comments.data.find(c => c.body.includes('## Test Coverage Report'));
+
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body: summary
+              });
+            } else {
+              await github.rest.issues.createComment({
                 owner: context.repo.owner,
                 repo: context.repo.repo,
                 issue_number: context.issue.number,
+                body: summary
               });
-              
-              const existingComment = comments.data.find(comment => 
-                comment.body.includes('## 📊 Test Coverage Report')
-              );
-              
-              if (existingComment) {
-                // Update existing comment
-                await github.rest.issues.updateComment({
-                  owner: context.repo.owner,
-                  repo: context.repo.repo,
-                  comment_id: existingComment.id,
-                  body: summary
-                });
-                console.log('Updated existing coverage comment');
-              } else {
-                // Create new comment
-                await github.rest.issues.createComment({
-                  owner: context.repo.owner,
-                  repo: context.repo.repo,
-                  issue_number: context.issue.number,
-                  body: summary
-                });
-                console.log('Created new coverage comment');
-              }
-            } catch (error) {
-              console.log('Failed to comment on PR (this may be due to organization permissions):', error.message);
-              // Don't fail the workflow if commenting fails
             }
 
-      # Step 9: Prepare coverage reports for deployment
-      - name: Prepare coverage for deployment
-        run: |
-          # Create deployment directory
-          mkdir -p pages-deploy/coverage
-
-          # Copy coverage reports to match expected URL structure
-          cp -r coverage/* pages-deploy/coverage/
-
-          # Create index.html that redirects to coverage report
-          cat > pages-deploy/index.html << 'EOF'
-          <!DOCTYPE html>
-          <html lang="en">
-          <head>
-              <meta charset="UTF-8">
-              <meta name="viewport" content="width=device-width, initial-scale=1.0">
-              <title>Project Nexus MCP - Coverage Reports</title>
-              <meta http-equiv="refresh" content="0; url=./coverage/lcov-report/">
-              <style>
-                  body {
-                      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
-                      max-width: 800px;
-                      margin: 2rem auto;
-                      padding: 2rem;
-                      line-height: 1.6;
-                  }
-                  .header {
-                      text-align: center;
-                      margin-bottom: 2rem;
-                  }
-                  .coverage-badge {
-                      display: inline-block;
-                      padding: 0.5rem 1rem;
-                      background: #28a745;
-                      color: white;
-                      border-radius: 4px;
-                      text-decoration: none;
-                      font-weight: bold;
-                  }
-                  .links {
-                      margin-top: 2rem;
-                  }
-                  .links a {
-                      display: inline-block;
-                      margin: 0.5rem 1rem 0.5rem 0;
-                      padding: 0.5rem 1rem;
-                      background: #007bff;
-                      color: white;
-                      text-decoration: none;
-                      border-radius: 4px;
-                  }
-                  .links a:hover {
-                      background: #0056b3;
-                  }
-              </style>
-          </head>
-          <body>
-              <div class="header">
-                  <h1>Project Nexus MCP</h1>
-                  <h2>Test Coverage Reports</h2>
-                  <div class="coverage-badge">
-                      Coverage: ${{ steps.coverage.outputs.percentage }}%
-                  </div>
-              </div>
-              
-              <p>You will be automatically redirected to the coverage report. If not, click the link below:</p>
-              
-              <div class="links">
-                  <a href="./coverage/lcov-report/">📊 View Coverage Report</a>
-                  <a href="https://github.com/structured-world/gitlab-mcp">📁 View Source Code</a>
-                  <a href="https://github.com/structured-world/gitlab-mcp/actions">🔄 View CI/CD</a>
-              </div>
-              
-              <div style="margin-top: 2rem; padding: 1rem; background: #f8f9fa; border-radius: 4px;">
-                  <h3>About This Report</h3>
-                  <p>This coverage report is automatically generated from the latest tests on the main branch. 
-                  It shows which parts of the codebase are covered by tests and helps identify areas that may need additional testing.</p>
-                  
-                  <p><strong>Last Updated:</strong> ${{ steps.coverage.outputs.timestamp || 'Unknown' }}</p>
-                  <p><strong>Generated by:</strong> Jest + GitHub Actions</p>
-              </div>
-          </body>
-          </html>
-          EOF
-
-          # Add timestamp
-          echo "timestamp=$(date -u '+%Y-%m-%d %H:%M:%S UTC')" >> $GITHUB_OUTPUT
-
-      # Step 10: Determine if we should deploy (only on main branch pushes)
-      - name: Determine deployment
-        id: should-deploy
-        run: |
-          if [[ "${{ github.ref }}" == "refs/heads/main" && "${{ github.event_name }}" == "push" ]]; then
-            echo "result=true" >> $GITHUB_OUTPUT
-          else
-            echo "result=false" >> $GITHUB_OUTPUT
-          fi
-
-      # Step 11: Upload coverage artifacts for PR preview
       - name: Upload coverage artifacts
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v4
         with:
           name: coverage-reports-${{ github.sha }}
-          path: pages-deploy/
-          retention-days: 30
-
-      # Step 12: Upload pages artifact (for deployment)
-      - name: Upload Pages artifact
-        if: steps.should-deploy.outputs.result == 'true'
-        uses: actions/upload-pages-artifact@v4
-        with:
-          path: pages-deploy/
-
-  # Job 2: Deploy to GitHub Pages (only on main branch)
-  deploy:
-    name: Deploy to GitHub Pages
-    runs-on: ubuntu-latest
-    needs: coverage
-    if: needs.coverage.outputs.should-deploy == 'true'
-
-    # Deploy to the github-pages environment
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-
-    steps:
-      # Step 1: Deploy to GitHub Pages
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4
-
-      # Step 2: Create deployment summary
-      - name: Create deployment summary
-        run: |
-          echo "## 🚀 Coverage Report Deployed" >> $GITHUB_STEP_SUMMARY
-          echo "" >> $GITHUB_STEP_SUMMARY
-          echo "**Coverage Percentage:** ${{ needs.coverage.outputs.coverage-percentage }}%" >> $GITHUB_STEP_SUMMARY
-          echo "" >> $GITHUB_STEP_SUMMARY
-          echo "**📊 Live Coverage Report:** ${{ steps.deployment.outputs.page_url }}" >> $GITHUB_STEP_SUMMARY
-          echo "" >> $GITHUB_STEP_SUMMARY
-          echo "The coverage report has been successfully deployed and is now available at the link above." >> $GITHUB_STEP_SUMMARY
-          echo "" >> $GITHUB_STEP_SUMMARY
-          echo "### Quick Links" >> $GITHUB_STEP_SUMMARY
-          echo "- [Coverage Report](${{ steps.deployment.outputs.page_url }})" >> $GITHUB_STEP_SUMMARY
-          echo "- [Detailed Coverage](${{ steps.deployment.outputs.page_url }}coverage/lcov-report/)" >> $GITHUB_STEP_SUMMARY
-          echo "- [Repository](https://github.com/${{ github.repository }})" >> $GITHUB_STEP_SUMMARY
+          path: coverage/
+          retention-days: 14