chore(deps): update actions/setup-node action to v6

chore(deps): update dependency node to v24

.dockerignore

@@ -5,3 +5,5 @@
 !uv.lock
 
 !nextcloud_mcp_server/**/*.py
+!nextcloud_mcp_server/**/*.html
+!nextcloud_mcp_server/auth/static/*

.env.keycloak.sample

@@ -0,0 +1,138 @@
+# Keycloak OAuth Configuration for Nextcloud MCP Server
+#
+# This configuration uses Keycloak as the OAuth/OIDC identity provider
+# while still accessing Nextcloud APIs. Nextcloud's user_oidc app validates
+# Keycloak bearer tokens and provisions users automatically.
+#
+# Architecture: Client → Keycloak (OAuth) → MCP Server → Nextcloud (user_oidc validates) → APIs
+#
+# This enables ADR-002 authentication patterns without admin credentials!
+
+# ==============================================================================
+# OAUTH PROVIDER SELECTION
+# ==============================================================================
+
+# OAuth provider: "keycloak" or "nextcloud" (default)
+OAUTH_PROVIDER=keycloak
+
+# ==============================================================================
+# KEYCLOAK CONFIGURATION
+# ==============================================================================
+
+# Keycloak base URL (accessible from MCP server container)
+KEYCLOAK_URL=http://keycloak:8080
+
+# Keycloak realm name
+KEYCLOAK_REALM=nextcloud-mcp
+
+# OAuth client credentials (from Keycloak realm export or manual configuration)
+KEYCLOAK_CLIENT_ID=nextcloud-mcp-server
+KEYCLOAK_CLIENT_SECRET=mcp-secret-change-in-production
+
+# OIDC discovery URL (auto-constructed from URL + realm, or specify explicitly)
+KEYCLOAK_DISCOVERY_URL=http://keycloak:8080/realms/nextcloud-mcp/.well-known/openid-configuration
+
+# ==============================================================================
+# NEXTCLOUD CONFIGURATION
+# ==============================================================================
+
+# Nextcloud URL (accessible from MCP server container)
+# Used for API access - Keycloak tokens are validated by user_oidc app
+NEXTCLOUD_HOST=http://app:80
+
+# MCP server URL (for OAuth redirect URIs)
+# This is the publicly accessible URL that OAuth clients connect to
+NEXTCLOUD_MCP_SERVER_URL=http://localhost:8002
+
+# Public Keycloak issuer URL (accessible from OAuth clients)
+# If clients access Keycloak via a different URL than the internal one,
+# set this to the public URL for OAuth flows
+NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8888
+
+# ==============================================================================
+# REFRESH TOKEN STORAGE (ADR-002 Tier 1: Offline Access)
+# ==============================================================================
+
+# Enable offline_access scope to get refresh tokens
+ENABLE_OFFLINE_ACCESS=true
+
+# Encryption key for storing refresh tokens (generate with instructions below)
+# IMPORTANT: Keep this secret! Tokens are encrypted at rest using this key.
+#
+# Generate a key:
+#   python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+#
+# Example (DO NOT use this in production!):
+# TOKEN_ENCRYPTION_KEY=your-base64-encoded-fernet-key-here
+
+# Path to SQLite database for token storage
+TOKEN_STORAGE_DB=/app/data/tokens.db
+
+# ==============================================================================
+# DOCKER COMPOSE NOTES
+# ==============================================================================
+
+# When running via docker-compose, the mcp-keycloak service is pre-configured
+# with these environment variables. See docker-compose.yml for the full config.
+#
+# Start services:
+#   docker-compose up -d keycloak app mcp-keycloak
+#
+# View logs:
+#   docker-compose logs -f mcp-keycloak
+#
+# Check Keycloak realm:
+#   curl http://localhost:8888/realms/nextcloud-mcp/.well-known/openid-configuration
+#
+# Check user_oidc provider:
+#   docker compose exec app php occ user_oidc:provider keycloak
+
+# ==============================================================================
+# KEYCLOAK SETUP VERIFICATION
+# ==============================================================================
+
+# 1. Verify Keycloak is running and realm is imported:
+#    curl http://localhost:8888/realms/nextcloud-mcp/.well-known/openid-configuration
+#
+# 2. Verify Nextcloud user_oidc provider is configured:
+#    docker compose exec app php occ user_oidc:provider keycloak
+#
+# 3. Test OAuth flow manually:
+#    - Get token from Keycloak:
+#      curl -X POST "http://localhost:8888/realms/nextcloud-mcp/protocol/openid-connect/token" \
+#        -d "grant_type=password" \
+#        -d "client_id=nextcloud-mcp-server" \
+#        -d "client_secret=mcp-secret-change-in-production" \
+#        -d "username=admin" \
+#        -d "password=admin" \
+#        -d "scope=openid profile email offline_access"
+#
+#    - Use token with Nextcloud API:
+#      curl -H "Authorization: Bearer <access_token>" \
+#        http://localhost:8080/ocs/v2.php/cloud/capabilities
+#
+# 4. Connect MCP client to server:
+#    - Point your MCP client to http://localhost:8002
+#    - Complete OAuth flow via Keycloak (credentials: admin/admin)
+#    - Client should receive access token and be able to call MCP tools
+
+# ==============================================================================
+# TROUBLESHOOTING
+# ==============================================================================
+
+# If OAuth flow fails:
+# - Check that Keycloak is accessible: curl http://localhost:8888
+# - Check that user_oidc provider is configured: docker compose exec app php occ user_oidc:provider keycloak
+# - Check MCP server logs: docker-compose logs mcp-keycloak
+# - Verify redirect URIs match in Keycloak client configuration
+#
+# If token validation fails:
+# - Verify user_oidc has bearer validation enabled (--check-bearer=1)
+# - Check Nextcloud logs: docker compose exec app tail -f /var/www/html/data/nextcloud.log
+# - Verify Keycloak discovery URL is accessible from Nextcloud container:
+#   docker compose exec app curl http://keycloak:8080/realms/nextcloud-mcp/.well-known/openid-configuration
+#
+# If offline_access/refresh tokens not working:
+# - Verify TOKEN_ENCRYPTION_KEY is set and valid
+# - Check token storage database: ls -lah /app/data/tokens.db (inside container)
+# - Check that offline_access scope is requested in realm configuration

.github/workflows/bump-version.yml

@@ -7,26 +7,158 @@ on:
 
 jobs:
   bump-version:
-    if: "!startsWith(github.event.head_commit.message, 'bump:')"
+    if: "!startsWith(github.event.head_commit.message, 'bump:') && !startsWith(github.event.head_commit.message, 'chore(release):')"
     runs-on: ubuntu-latest
-    name: "Bump version and create changelog with commitizen"
+    name: "Bump version and create changelog for monorepo components"
     permissions:
       contents: write
       packages: write
     steps:
       - name: Check out
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           fetch-depth: 0
           token: "${{ secrets.PERSONAL_ACCESS_TOKEN }}"
-      - name: Create bump and changelog
-        uses: commitizen-tools/commitizen-action@5b0848cd060263e24602d1eba03710e056ef7711 # 0.24.0
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
-          github_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
-          changelog_increment_filename: body.md
-      - name: Release
-        uses: softprops/action-gh-release@6da8fa9354ddfdc4aeace5fc48d7f679b5214090 # v2.4.1
-        with:
-          body_path: "body.md"
-          tag_name: v${{ env.REVISION }}
-          token: ${{ secrets.GITHUB_TOKEN }}
+          python-version: '3.11'
+
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Detect and bump component versions
+        id: bump
+        run: |
+          set -euo pipefail
+
+          # Track which components were bumped
+          BUMPED_COMPONENTS=""
+
+          # Helper function to check for commits with specific scope since last tag
+          has_commits_since_tag() {
+            local tag_pattern="$1"
+            local scope_pattern="$2"
+
+            # Get the most recent tag matching the pattern
+            local last_tag=$(git tag --sort=-creatordate | grep -E "^${tag_pattern}" | head -n 1 || echo "")
+
+            if [ -z "$last_tag" ]; then
+              # No previous tag, check all commits on master
+              local commit_range="master"
+            else
+              # Check commits since last tag
+              local commit_range="${last_tag}..HEAD"
+            fi
+
+            # Count commits matching the scope pattern
+            local commit_count=$(git log "$commit_range" --oneline --grep="^${scope_pattern}" -E | wc -l)
+
+            if [ "$commit_count" -gt 0 ]; then
+              echo "Found $commit_count commits for scope '$scope_pattern' since $last_tag"
+              return 0
+            else
+              echo "No commits found for scope '$scope_pattern' since $last_tag"
+              return 1
+            fi
+          }
+
+          # Bump MCP server (default - all commits except helm scope)
+          echo "Checking MCP server for version bump..."
+
+          # Get the most recent MCP tag
+          last_mcp_tag=$(git tag --sort=-creatordate | grep -E "^v[0-9]" | head -n 1 || echo "")
+
+          if [ -z "$last_mcp_tag" ]; then
+            commit_range="master"
+          else
+            commit_range="${last_mcp_tag}..HEAD"
+          fi
+
+          # Count conventional commits that are NOT scoped to helm
+          mcp_commit_count=$(git log "$commit_range" --oneline --grep="^(feat|fix|docs|refactor|perf|test|build|ci|chore)" -E | \
+            { grep -v "(helm)" || true; } | wc -l)
+
+          MCP_BUMPED=false
+          if [ "$mcp_commit_count" -gt 0 ]; then
+            echo "Found $mcp_commit_count commits for MCP server since $last_mcp_tag"
+            echo "Bumping MCP server version..."
+            ./scripts/bump-mcp.sh
+            BUMPED_COMPONENTS="$BUMPED_COMPONENTS mcp"
+            MCP_BUMPED=true
+          else
+            echo "No commits found for MCP server since $last_mcp_tag"
+          fi
+
+          # Bump Helm chart (scope: helm OR when MCP appVersion changes)
+          echo "Checking Helm chart for version bump..."
+          HELM_HAS_COMMITS=false
+          if has_commits_since_tag "nextcloud-mcp-server-" "(feat|fix|docs|refactor|perf|test|build|ci|chore)\(helm\)(!)?:"; then
+            HELM_HAS_COMMITS=true
+          fi
+
+          if [ "$HELM_HAS_COMMITS" = true ]; then
+            echo "Bumping Helm chart version (helm-scoped commits)..."
+            ./scripts/bump-helm.sh
+            BUMPED_COMPONENTS="$BUMPED_COMPONENTS helm"
+          elif [ "$MCP_BUMPED" = true ]; then
+            echo "Bumping Helm chart version (appVersion changed)..."
+            ./scripts/bump-helm.sh --increment PATCH
+            BUMPED_COMPONENTS="$BUMPED_COMPONENTS helm"
+          fi
+
+          # Output summary
+          if [ -z "$BUMPED_COMPONENTS" ]; then
+            echo "No components required version bumps"
+            echo "bumped=false" >> $GITHUB_OUTPUT
+          else
+            echo "Bumped components:$BUMPED_COMPONENTS"
+            echo "bumped=true" >> $GITHUB_OUTPUT
+            echo "components=$BUMPED_COMPONENTS" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Push tags
+        if: steps.bump.outputs.bumped == 'true'
+        run: |
+          git push
+          git push --tags
+          echo "Pushed tags for components:${{ steps.bump.outputs.components }}"
+
+      - name: Summary
+        run: |
+          if [ "${{ steps.bump.outputs.bumped }}" == "true" ]; then
+            echo "## Version Bump Summary" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "The following components were bumped:" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+
+            for component in ${{ steps.bump.outputs.components }}; do
+              case $component in
+                mcp)
+                  tag=$(git tag --sort=-creatordate | grep -E '^v[0-9]' | head -n 1)
+                  echo "- **MCP Server**: \`$tag\`" >> $GITHUB_STEP_SUMMARY
+                  ;;
+                helm)
+                  tag=$(git tag --sort=-creatordate | grep -E '^nextcloud-mcp-server-' | head -n 1)
+                  echo "- **Helm Chart**: \`$tag\`" >> $GITHUB_STEP_SUMMARY
+                  ;;
+              esac
+            done
+
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "Tags have been pushed and release workflows will trigger automatically." >> $GITHUB_STEP_SUMMARY
+          else
+            echo "## Version Bump Summary" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "✅ No version bumps required - no relevant commits found since last release." >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "The workflow completed successfully with no changes." >> $GITHUB_STEP_SUMMARY
+          fi

.github/workflows/claude-code-review.yml

@@ -0,0 +1,58 @@
+name: Claude Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+    # Optional: Only run on specific file changes
+    # paths:
+    #   - "src/**/*.ts"
+    #   - "src/**/*.tsx"
+    #   - "src/**/*.js"
+    #   - "src/**/*.jsx"
+
+jobs:
+  claude-review:
+    # Optional: Filter by PR author
+    # if: |
+    #   github.event.pull_request.user.login == 'external-contributor' ||
+    #   github.event.pull_request.user.login == 'new-developer' ||
+    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
+
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code Review
+        id: claude-review
+        uses: anthropics/claude-code-action@64c7a0ef71df67b14cb4471f4d9c8565c61042bf # v1.0.66
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          allowed_bots: "renovate-bot-cbcoutinho"
+          prompt: |
+            REPO: ${{ github.repository }}
+            PR NUMBER: ${{ github.event.pull_request.number }}
+
+            Please review this pull request and provide feedback on:
+            - Code quality and best practices
+            - Potential bugs or issues
+            - Performance considerations
+            - Security concerns
+            - Test coverage
+
+            Use the repository's CLAUDE.md for guidance on style and conventions. Be constructive and helpful in your feedback.
+
+            Use `gh pr comment` with your Bash tool to leave your review as a comment on the PR.
+
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://docs.claude.com/en/docs/claude-code/cli-reference for available options
+          claude_args: '--allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"'
+

.github/workflows/claude.yml

@@ -0,0 +1,50 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@64c7a0ef71df67b14cb4471f4d9c8565c61042bf # v1.0.66
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
+          # prompt: 'Update the pull request description to include a summary of changes.'
+
+          # Optional: Add claude_args to customize behavior and configuration
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://docs.claude.com/en/docs/claude-code/cli-reference for available options
+          # claude_args: '--allowed-tools Bash(gh pr:*)'
+

.github/workflows/docker-build-publish.yml

@@ -2,7 +2,8 @@ name: Build and Publish Docker Image
 
 on:
   push:
-    tags: ["*"]
+    tags:
+      - "v*"
 
 jobs:
   build-and-push:
@@ -12,11 +13,11 @@ jobs:
       packages: write
     steps:
       - name: Checkout repository
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@c1e51972afc2121e065aed6d45c65596fe445f3f # v5
+        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5.10.0
         with:
           # list of Docker images to use as base name for tags
           images: |
@@ -33,18 +34,18 @@ jobs:
             type=raw,value=latest,enable={{is_default_branch}}
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # v3
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0
 
       - name: Log in to GitHub Container Registry
         if: github.event_name != 'pull_request'
-        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Build and push Docker image
-        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6.19.2
         with:
           push: ${{ github.event_name != 'pull_request' }}
           tags: ${{ steps.meta.outputs.tags }}

.github/workflows/helm-release.yml

@@ -0,0 +1,137 @@
+name: Release Charts
+
+on:
+  push:
+    tags:
+      - v*
+      - nextcloud-mcp-server-*
+
+jobs:
+  release:
+    # depending on default permission settings for your org (contents being read-only or read-write for workloads), you will have to add permissions
+    # see: https://docs.github.com/en/actions/security-guides/automatic-token-authentication#modifying-the-permissions-for-the-github_token
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+
+
+      - name: Configure Git
+        run: |
+          git config user.name "$GITHUB_ACTOR"
+          git config user.email "$GITHUB_ACTOR@users.noreply.github.com"
+
+      - name: Install Helm
+        uses: azure/setup-helm@1a275c3b69536ee54be43f2070a358922e12c8d4 # v4.3.1
+        with:
+          version: v3.16.0
+
+      - name: Add Helm repositories and update dependencies
+        run: |
+          helm repo add qdrant https://qdrant.github.io/qdrant-helm
+          helm repo add ollama https://otwld.github.io/ollama-helm
+          helm repo update
+          helm dependency build charts/nextcloud-mcp-server
+
+      - name: Run chart-releaser
+        uses: helm/chart-releaser-action@cae68fefc6b5f367a0275617c9f83181ba54714f # v1.7.0
+        with:
+          skip_existing: true
+        env:
+          CR_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
+
+      - name: Update gh-pages with Chart README and Index
+        run: |
+          # Get the repository name
+          REPO_NAME="${GITHUB_REPOSITORY##*/}"
+          REPO_OWNER="${GITHUB_REPOSITORY%/*}"
+
+          # Switch to gh-pages branch
+          git fetch origin gh-pages
+          git checkout gh-pages
+
+          # Copy Chart README to root
+          git checkout ${GITHUB_REF#refs/tags/} -- charts/nextcloud-mcp-server/README.md
+          mv charts/nextcloud-mcp-server/README.md README.md || true
+          rm -rf charts 2>/dev/null || true
+
+          # Create index.html with installation instructions
+          cat > 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>Nextcloud MCP Server Helm Chart</title>
+              <style>
+                  body {
+                      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+                      max-width: 800px;
+                      margin: 50px auto;
+                      padding: 20px;
+                      line-height: 1.6;
+                  }
+                  code {
+                      background: #f4f4f4;
+                      padding: 2px 6px;
+                      border-radius: 3px;
+                      font-family: "Monaco", "Courier New", monospace;
+                  }
+                  pre {
+                      background: #f4f4f4;
+                      padding: 15px;
+                      border-radius: 5px;
+                      overflow-x: auto;
+                  }
+                  h1, h2 { color: #0082c9; }
+                  a { color: #0082c9; text-decoration: none; }
+                  a:hover { text-decoration: underline; }
+              </style>
+          </head>
+          <body>
+              <h1>Nextcloud MCP Server Helm Chart</h1>
+
+              <p>A Helm chart for deploying the Nextcloud MCP (Model Context Protocol) Server on Kubernetes, enabling AI assistants to interact with your Nextcloud instance.</p>
+
+              <h2>Installation</h2>
+
+              <p>Add the Helm repository:</p>
+              <pre><code>helm repo add nextcloud-mcp https://REPO_OWNER.github.io/REPO_NAME/
+          helm repo update</code></pre>
+
+              <p>Install the chart:</p>
+              <pre><code>helm install nextcloud-mcp nextcloud-mcp/nextcloud-mcp-server \
+            --set nextcloud.host=https://cloud.example.com \
+            --set auth.basic.username=myuser \
+            --set auth.basic.password=mypassword</code></pre>
+
+              <h2>Documentation</h2>
+
+              <ul>
+                  <li><a href="README.md">Chart README</a> - Full documentation for the Helm chart</li>
+                  <li><a href="https://github.com/REPO_OWNER/REPO_NAME">GitHub Repository</a> - Source code and issues</li>
+                  <li><a href="index.yaml">Helm Repository Index</a> - Chart metadata</li>
+              </ul>
+
+              <h2>Quick Start</h2>
+
+              <p>See the <a href="README.md">full documentation</a> for detailed configuration options, examples, and troubleshooting guides.</p>
+
+              <hr>
+              <p><small>Generated by <a href="https://github.com/helm/chart-releaser">chart-releaser</a></small></p>
+          </body>
+          </html>
+          EOF
+
+          # Replace placeholders
+          sed -i "s/REPO_OWNER/$REPO_OWNER/g" index.html
+          sed -i "s/REPO_NAME/$REPO_NAME/g" index.html
+
+          # Commit changes
+          git add README.md index.html
+          git commit -m "Update README and index from chart release" || echo "No changes to commit"
+          git push origin gh-pages

.github/workflows/rag-evaluation.yml

@@ -0,0 +1,105 @@
+name: RAG Evaluation
+
+on:
+  workflow_dispatch:
+    inputs:
+      manual_path:
+        description: 'Path to Nextcloud User Manual PDF in Nextcloud'
+        required: false
+        default: 'Nextcloud Manual.pdf'
+      embedding_model:
+        description: 'OpenAI embedding model'
+        required: false
+        default: 'openai/text-embedding-3-small'
+      generation_model:
+        description: 'OpenAI generation model'
+        required: false
+        default: 'openai/gpt-4o-mini'
+
+jobs:
+  rag-evaluation:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      models: read
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Run docker compose with vector sync
+        uses: hoverkraft-tech/compose-action@4894d2492015c1774ee5a13a95b1072093087ec3 # v2.5.0
+        with:
+          compose-file: |
+            ./docker-compose.yml
+            ./docker-compose.ci.yml
+          up-flags: "--build"
+        env:
+          # Environment variables passed to docker-compose.ci.yml
+          OPENAI_API_KEY: ${{ secrets.GITHUB_TOKEN }}
+          OPENAI_BASE_URL: "https://models.github.ai/inference"
+          OPENAI_EMBEDDING_MODEL: ${{ inputs.embedding_model }}
+          OPENAI_GENERATION_MODEL: ${{ inputs.generation_model }}
+          VECTOR_SYNC_SCAN_INTERVAL: "5"
+
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@5a095e7a2014a4212f075830d4f7277575a9d098 # v7.3.1
+
+      - name: Wait for Nextcloud to be ready
+        run: |
+          echo "Waiting for Nextcloud..."
+          max_attempts=60
+          attempt=0
+          until curl -o /dev/null -s -w "%{http_code}\n" http://localhost:8080/ocs/v2.php/apps/serverinfo/api/v1/info | grep -q "401"; do
+            attempt=$((attempt + 1))
+            if [ $attempt -ge $max_attempts ]; then
+              echo "Service did not become ready in time."
+              exit 1
+            fi
+            echo "Attempt $attempt/$max_attempts: Service not ready, sleeping for 5 seconds..."
+            sleep 5
+          done
+          echo "Nextcloud is ready."
+
+      - name: Wait for MCP server to be ready
+        run: |
+          echo "Waiting for MCP server..."
+          max_attempts=30
+          attempt=0
+          until curl -o /dev/null -s -w "%{http_code}\n" http://localhost:8000/health/live | grep -q "200"; do
+            attempt=$((attempt + 1))
+            if [ $attempt -ge $max_attempts ]; then
+              echo "MCP server did not become ready in time."
+              exit 1
+            fi
+            echo "Attempt $attempt/$max_attempts: MCP not ready, sleeping for 2 seconds..."
+            sleep 2
+          done
+          echo "MCP server is ready."
+
+      - name: Run RAG evaluation tests
+        env:
+          NEXTCLOUD_HOST: "http://localhost:8080"
+          NEXTCLOUD_USERNAME: "admin"
+          NEXTCLOUD_PASSWORD: "admin"
+          RAG_MANUAL_PATH: ${{ inputs.manual_path }}
+          OPENAI_API_KEY: ${{ secrets.GITHUB_TOKEN }}
+          OPENAI_BASE_URL: "https://models.github.ai/inference"
+          OPENAI_EMBEDDING_MODEL: ${{ inputs.embedding_model }}
+          OPENAI_GENERATION_MODEL: ${{ inputs.generation_model }}
+        run: |
+          uv run pytest tests/integration/test_rag.py -v --log-cli-level=INFO --provider openai
+
+      - name: Capture MCP container logs
+        if: always()
+        run: |
+          echo "=== MCP Container Logs ==="
+          docker compose logs mcp --tail=500
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        with:
+          name: rag-evaluation-results
+          path: |
+            pytest-results.xml
+          retention-days: 30

.github/workflows/release.yml

@@ -0,0 +1,33 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - v*
+
+jobs:
+  pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    # Environment and permissions trusted publishing.
+    environment:
+      # Create this environment in the GitHub repository under Settings -> Environments
+      name: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Install uv
+        uses: astral-sh/setup-uv@5a095e7a2014a4212f075830d4f7277575a9d098 # v7.3.1
+      - name: Install Python 3.11
+        run: uv python install 3.11
+      - name: Build
+        run: uv build
+      - name: Smoke test (wheel)
+        run: uv run --isolated --no-project --with dist/*.whl nextcloud-mcp-server --help
+      - name: Smoke test (source distribution)
+        run: uv run --isolated --no-project --with dist/*.tar.gz nextcloud-mcp-server --help
+      - name: Publish
+        run: uv publish

.github/workflows/test.yml

@@ -1,4 +1,4 @@
-name: Docker Compose Action
+name: Tests
 
 on:
   pull_request:
@@ -9,57 +9,205 @@ jobs:
   linting:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@2ddd2b9cb38ad8efd50337e8ab201519a34c9f24 # v7.1.1
+        uses: astral-sh/setup-uv@5a095e7a2014a4212f075830d4f7277575a9d098 # v7.3.1
       - name: Check format
-        run: |
-          uv run --frozen ruff format --diff
+        run: uv run --frozen ruff format --diff
       - name: Linting
-        run: |
-          uv run --frozen ruff check
+        run: uv run --frozen ruff check
+      - name: Type check
+        run: uv run --frozen ty check -- nextcloud_mcp_server
 
+  unit-test:
+    runs-on: ubuntu-latest
+    needs: [linting]
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@5a095e7a2014a4212f075830d4f7277575a9d098 # v7.3.1
+      - name: Run unit tests
+        run: uv run pytest -v -m unit -o "addopts=-p no:asyncio"
 
   integration-test:
     runs-on: ubuntu-latest
+    needs: [linting]
+    strategy:
+      fail-fast: false
+      matrix:
+        nextcloud_version:
+          - "31"
+          - "32"
+          # - "33"  # Disabled until all upstream apps support NC 33
+        mode:
+          - "single-user"
+          - "multi-user-basic"
+          - "oauth"
+          - "login-flow"
+        include:
+          # Version-specific image pins — Renovate updates these via customManagers
+          # renovate: datasource=docker depName=docker.io/library/nextcloud
+          - nextcloud_version: "31"
+            nextcloud_image: "docker.io/library/nextcloud:31.0.14@sha256:9bf3fae91aad4dca3eff02c1f71df8d5c6705a349065fb537aa5c5ef578f1013"
+          # renovate: datasource=docker depName=docker.io/library/nextcloud
+          - nextcloud_version: "32"
+            nextcloud_image: "docker.io/library/nextcloud:32.0.6@sha256:5c4e09f72f096cd68379a8ae69f71e61d13da5a07430fc4a17c702a14e6a4267"
+          # renovate: datasource=docker depName=docker.io/library/nextcloud
+          # Disabled until all upstream apps support NC 33
+          # - nextcloud_version: "33"
+          #   nextcloud_image: "docker.io/library/nextcloud:33.0.0@sha256:d53f6cb35b0712aa890a5e4a8ca21043d6fcd390f38c55b710816dd7cbc2edc0"
+
+          # Mode-specific properties
+          - mode: single-user
+            profile: single-user
+            markers: "(smoke and not oauth and not keycloak and not login_flow and not multi_user_basic) or (integration and not oauth and not keycloak and not login_flow and not multi_user_basic)"
+            wait-port: 8000
+            mcp-internal-url: "http://mcp:8000"
+            needs-playwright: false
+            extra-args: >-
+              --ignore=tests/integration/test_qdrant_collection_creation.py
+              --ignore=tests/rag_evaluation/
+
+          - mode: multi-user-basic
+            profile: multi-user-basic
+            markers: "multi_user_basic"
+            wait-port: 8003
+            mcp-internal-url: "http://mcp-multi-user-basic:8000"
+            needs-playwright: true
+            extra-args: ""
+
+          - mode: oauth
+            profile: oauth
+            markers: "oauth and not keycloak"
+            wait-port: 8001
+            mcp-internal-url: "http://mcp-oauth:8001"
+            needs-playwright: true
+            extra-args: ""
+
+          - mode: login-flow
+            profile: login-flow
+            markers: "login_flow"
+            wait-port: 8004
+            mcp-internal-url: "http://mcp-login-flow:8004"
+            needs-playwright: true
+            extra-args: ""
+
+    name: integration (${{ matrix.mode }} / nc${{ matrix.nextcloud_version }})
 
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          submodules: 'true'
 
+      - name: Set up PHP 8.4
+        if: matrix.mode != 'single-user'
+        uses: shivammathur/setup-php@44454db4f0199b8b9685a5d763dc37cbf79108e1 # 2.36.0
+        with:
+          php-version: 8.4
+          coverage: none
+
+      # OIDC app installed from app store (dev mount removed from docker-compose.yml)
+
+      - name: Set up Node.js
+        if: matrix.mode != 'single-user'
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        with:
+          node-version: 24
+
+      - name: Build Astrolabe app
+        if: matrix.mode != 'single-user'
+        run: |
+          cd third_party/astrolabe
+          composer install --no-dev --optimize-autoloader
+          npm ci
+          npm run build
+
+      # Start services with the appropriate profile
       - name: Run docker compose
-        uses: hoverkraft-tech/compose-action@3846bcd61da338e9eaaf83e7ed0234a12b099b72 # v2.4.1
+        uses: hoverkraft-tech/compose-action@4894d2492015c1774ee5a13a95b1072093087ec3 # v2.5.0
         with:
           compose-file: "./docker-compose.yml"
+          compose-flags: "--profile ${{ matrix.profile }}"
           up-flags: "--build"
+        env:
+          MCP_SERVER_URL: ${{ matrix.mcp-internal-url }}
+          NEXTCLOUD_IMAGE: ${{ matrix.nextcloud_image }}
 
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@2ddd2b9cb38ad8efd50337e8ab201519a34c9f24 # v7.1.1
+        uses: astral-sh/setup-uv@5a095e7a2014a4212f075830d4f7277575a9d098 # v7.3.1
 
-      - name: Install Playwright dependencies
-        run: |
-          uv run playwright install chromium --with-deps
+      - name: Install Playwright
+        if: matrix.needs-playwright
+        run: uv run playwright install chromium --with-deps
 
-      - name: Wait for service to be ready
+      # Wait for Nextcloud to be healthy
+      - name: Wait for Nextcloud
         run: |
-          echo "Waiting for service at http://localhost:8080/ocs/v2.php/apps/serverinfo/api/v1/info to return 401..."
+          echo "Waiting for Nextcloud at http://localhost:8080..."
           max_attempts=60
           attempt=0
-          until curl -o /dev/null -s -w "%{http_code}\n" http://localhost:8080/ocs/v2.php/apps/serverinfo/api/v1/info | grep -q "401"; do
+          until curl -sSf http://localhost:8080/status.php 2>/dev/null | grep -q '"installed":true'; do
             attempt=$((attempt + 1))
             if [ $attempt -ge $max_attempts ]; then
-              echo "Service did not become ready in time."
+              echo "Nextcloud did not become ready in time."
+              docker compose logs app
               exit 1
             fi
-            echo "Attempt $attempt/$max_attempts: Service not ready, sleeping for 5 seconds..."
+            echo "Attempt $attempt/$max_attempts: Not ready, sleeping 5s..."
             sleep 5
           done
-          echo "Service is ready (returned 401)."
+          echo "Nextcloud is ready."
 
-      # Add subsequent steps here, e.g., running tests
-      - name: Run tests
+      # Wait for the MCP service to be healthy
+      - name: Wait for MCP service (${{ matrix.mode }})
+        run: |
+          echo "Waiting for MCP service on port ${{ matrix.wait-port }}..."
+          max_attempts=30
+          attempt=0
+          until curl -o /dev/null -s -w "%{http_code}\n" http://localhost:${{ matrix.wait-port }}/health 2>/dev/null | grep -qE "200|404|405"; do
+            attempt=$((attempt + 1))
+            if [ $attempt -ge $max_attempts ]; then
+              echo "MCP service did not become ready in time."
+              docker compose --profile ${{ matrix.profile }} logs
+              exit 1
+            fi
+            echo "Attempt $attempt/$max_attempts: Not ready, sleeping 5s..."
+            sleep 5
+          done
+          echo "MCP service is ready on port ${{ matrix.wait-port }}."
+
+      - name: Verify OIDC configuration
+        if: matrix.mode == 'oauth' || matrix.mode == 'login-flow'
+        run: |
+          echo "=== OIDC Discovery ==="
+          curl -s http://localhost:8080/.well-known/openid-configuration | jq .
+          echo "=== OIDC App Status ==="
+          docker compose exec -T app php occ app:list --output=json 2>/dev/null | jq '.enabled.oidc // "NOT INSTALLED"'
+
+      - name: Run tests (${{ matrix.mode }})
         env:
           NEXTCLOUD_HOST: "http://localhost:8080"
           NEXTCLOUD_USERNAME: "admin"
           NEXTCLOUD_PASSWORD: "admin"
         run: |
-          uv run pytest -v --log-level=INFO
+          uv run pytest -v \
+            --log-cli-level=WARN \
+            -m '${{ matrix.markers }}' \
+            -o "addopts=-p no:asyncio" \
+            --timeout=300 \
+            ${{ matrix.extra-args }}
+
+      - name: Collect service logs on failure
+        if: failure()
+        run: docker compose --profile ${{ matrix.profile }} logs --tail=500 > /tmp/docker-compose-logs.txt 2>&1
+
+      - name: Upload debug artifacts
+        if: failure()
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        with:
+          name: debug-${{ matrix.mode }}-nc${{ matrix.nextcloud_version }}
+          path: |
+            /tmp/*.png
+            /tmp/docker-compose-logs.txt
+          retention-days: 7
+          if-no-files-found: ignore

.gitignore

@@ -5,5 +5,14 @@ __pycache__/
 .env.local
 .env.*.local
 
+# Git
+worktrees/
+
+docker-compose.override.yml
+
 # Generated by pytest used to login users
 .nextcloud_oauth_*.json
+.playwright-mcp/
+
+# RAG Evaluation
+tests/rag_evaluation/fixtures/

.gitmodules

@@ -0,0 +1,9 @@
+[submodule "third_party/oidc"]
+	path = third_party/oidc
+	url = https://github.com/cbcoutinho/oidc
+[submodule "third_party/notes"]
+	path = third_party/notes
+	url = https://github.com/cbcoutinho/notes
+[submodule "third_party/astrolabe"]
+	path = third_party/astrolabe
+	url = https://github.com/cbcoutinho/astrolabe

.pre-commit-config.yaml

@@ -18,3 +18,9 @@ repos:
       entry: uv run ruff format
       language: system
       types: [python]
+    - id: ty-check
+      name: ty-check
+      language: system
+      types: [python]
+      exclude: tests/.*
+      entry: uv run ty check

CLAUDE.md

@@ -2,253 +2,592 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-## Development Commands
+## Coding Conventions
+
+### async/await Patterns
+- **Use anyio for all async operations** - Provides structured concurrency
+  - pytest runs in `anyio` mode (`anyio_mode = "auto"` in pyproject.toml)
+  - Use `anyio.create_task_group()` for concurrent execution (NOT `asyncio.gather()`)
+  - Use `anyio.Lock()` for synchronization primitives (NOT `asyncio.Lock()`)
+  - Use `anyio.run()` for entry points (NOT `asyncio.run()`)
+  - Prefer standard async/await syntax without explicit library imports when possible
+  - Examples: app.py, search/hybrid.py, search/verification.py, auth/token_broker.py
+
+### Type Hints
+- **Use Python 3.10+ union syntax**: `str | None` instead of `Optional[str]`
+- **Use lowercase generics**: `dict[str, Any]` instead of `Dict[str, Any]`
+- **Type all function signatures** - Parameters and return types
+- **Type checker**: `ty` is configured for static type checking
+  ```bash
+  uv run ty check -- nextcloud_mcp_server
+  ```
+
+### Code Quality
+- **Run ruff and ty before committing**:
+  ```bash
+  uv run ruff check
+  uv run ruff format
+  uv run ty check -- nextcloud_mcp_server
+  ```
+- **Ruff configuration** in pyproject.toml (extends select: ["I"] for import sorting)
+
+### Error Handling
+- **Use custom decorators**: `@retry_on_429` for rate limiting (see base_client.py)
+- **Standard exceptions**: `HTTPStatusError` from httpx, `McpError` for MCP-specific errors
+- **Logging patterns**:
+  - `logger.debug()` for expected 404s and normal operations
+  - `logger.warning()` for retries and non-critical issues
+  - `logger.error()` for actual errors
+
+### Testing Patterns
+- **Use existing fixtures** from `tests/conftest.py` (2888 lines of test infrastructure)
+- **Session-scoped fixtures** handle anyio/pytest-asyncio incompatibility
+- **Mocked unit tests** use `mocker.AsyncMock(spec=httpx.AsyncClient)`
+- **pytest-timeout**: 180s default per test
+- **Mark tests appropriately**: `@pytest.mark.unit`, `@pytest.mark.integration`, `@pytest.mark.oauth`, `@pytest.mark.smoke`
+
+### Architectural Patterns
+- **Base classes**: `BaseNextcloudClient` for all API clients
+- **Pydantic responses**: All MCP tools return Pydantic models inheriting from `BaseResponse`
+- **Decorators**: `@require_scopes`, `@require_provisioning` for access control
+- **Context pattern**: `await get_client(ctx)` to access authenticated NextcloudClient (async!)
+- **FastMCP decorators**: `@mcp.tool()`, `@mcp.resource()`
+- **Token acquisition**: `get_client()` handles both pass-through and token exchange modes
+  - Pass-through (default): Simple, stateless (ENABLE_TOKEN_EXCHANGE=false)
+  - Token exchange (opt-in): RFC 8693 delegation (ENABLE_TOKEN_EXCHANGE=true)
+
+### MCP Tool Annotations (ADR-017)
+
+**All tools MUST include annotations** following these patterns:
+
+```python
+from mcp.types import ToolAnnotations
+
+# Read-only tools (list, search, get)
+@mcp.tool(
+    title="Human Readable Name",
+    annotations=ToolAnnotations(
+        readOnlyHint=True,
+        openWorldHint=True,  # Nextcloud is external to MCP server
+    ),
+)
+
+# Create operations
+@mcp.tool(
+    title="Create Resource",
+    annotations=ToolAnnotations(
+        idempotentHint=False,  # Creates new resources each time
+        openWorldHint=True,
+    ),
+)
+
+# Update operations (with etag/version control)
+@mcp.tool(
+    title="Update Resource",
+    annotations=ToolAnnotations(
+        idempotentHint=False,  # ETag changes = different inputs
+        openWorldHint=True,
+    ),
+)
+
+# Delete operations
+@mcp.tool(
+    title="Delete Resource",
+    annotations=ToolAnnotations(
+        destructiveHint=True,   # Permanently deletes data
+        idempotentHint=True,    # Same end state if called repeatedly
+        openWorldHint=True,
+    ),
+)
+
+# HTTP PUT without version control (special case)
+@mcp.tool(
+    title="Write File",
+    annotations=ToolAnnotations(
+        idempotentHint=True,  # Same content = same end state
+        openWorldHint=True,
+    ),
+)
+```
+
+**Key Principles**:
+- **Idempotency**: Same inputs → same result. ETags change after updates, making them non-idempotent
+- **Destructive**: Operations that permanently delete/overwrite data
+- **Open World**: All Nextcloud tools access external service (openWorldHint=True)
+- **Titles**: Use human-readable names, not snake_case function names
+
+**See**: `docs/ADR-017-mcp-tool-annotations.md` for detailed rationale and examples
+
+### Project Structure
+- `nextcloud_mcp_server/client/` - HTTP clients for Nextcloud APIs
+- `nextcloud_mcp_server/server/` - MCP tool/resource definitions
+- `nextcloud_mcp_server/auth/` - OAuth/OIDC authentication
+- `nextcloud_mcp_server/models/` - Pydantic response models
+- `nextcloud_mcp_server/providers/` - Unified LLM provider infrastructure (embeddings + generation)
+- `tests/` - Layered test suite (unit, smoke, integration, load)
+
+### Provider Architecture (ADR-015)
+
+**Unified Provider System** for embeddings and text generation:
+
+**Location:** `nextcloud_mcp_server/providers/`
+- `base.py` - `Provider` ABC with optional capabilities
+- `registry.py` - Auto-detection and factory pattern
+- `ollama.py` - Ollama provider (embeddings + generation)
+- `anthropic.py` - Anthropic provider (generation only)
+- `bedrock.py` - Amazon Bedrock provider (embeddings + generation)
+- `simple.py` - Simple in-memory provider (embeddings only, fallback)
+
+**Usage:**
+```python
+from nextcloud_mcp_server.providers import get_provider
+
+provider = get_provider()  # Auto-detects from environment
+
+# Check capabilities
+if provider.supports_embeddings:
+    embeddings = await provider.embed_batch(texts)
+
+if provider.supports_generation:
+    text = await provider.generate("prompt", max_tokens=500)
+```
+
+**Environment Variables:**
+
+Bedrock:
+- `AWS_REGION` - AWS region (e.g., "us-east-1")
+- `BEDROCK_EMBEDDING_MODEL` - Embedding model ID (e.g., "amazon.titan-embed-text-v2:0")
+- `BEDROCK_GENERATION_MODEL` - Generation model ID (e.g., "anthropic.claude-3-sonnet-20240229-v1:0")
+- `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` - Optional, uses AWS credential chain
+
+Ollama:
+- `OLLAMA_BASE_URL` - API URL (e.g., "http://localhost:11434")
+- `OLLAMA_EMBEDDING_MODEL` - Embedding model (default: "nomic-embed-text")
+- `OLLAMA_GENERATION_MODEL` - Generation model (e.g., "llama3.2:1b")
+- `OLLAMA_VERIFY_SSL` - SSL verification (default: "true")
+
+Simple (fallback, no config needed):
+- `SIMPLE_EMBEDDING_DIMENSION` - Dimension (default: 384)
+
+**Auto-Detection Priority:** Bedrock → Ollama → Simple
+
+**Backward Compatibility:**
+- Old code using `nextcloud_mcp_server.embedding.get_embedding_service()` still works
+- `EmbeddingService` now wraps `get_provider()` internally
+
+**For Details:** See `docs/ADR-015-unified-provider-architecture.md`
+
+## Development Commands (Quick Reference)
 
 ### Testing
 ```bash
-# Run all tests
-uv run pytest
+# Fast feedback (recommended)
+uv run pytest tests/unit/ -v                    # Unit tests (~5s)
+uv run pytest -m smoke -v                       # Smoke tests (~30-60s)
 
-# Run integration tests only
-uv run pytest -m integration
+# Integration tests
+uv run pytest -m "integration and not oauth" -v # Without OAuth (~2-3min)
+uv run pytest -m oauth -v                       # OAuth only (~3min)
+uv run pytest                                   # Full suite (~4-5min)
 
-# Run tests with coverage
+# Coverage
 uv run pytest --cov
 
-# Skip integration tests
-uv run pytest -m "not integration"
+# Specific tests after changes
+uv run pytest tests/server/test_mcp.py -k "notes" -v
+uv run pytest tests/client/notes/test_notes_api.py -v
+```
+
+**Important**: After code changes, rebuild the correct container:
+- Single-user tests: `docker-compose up --build -d mcp`
+- OAuth tests: `docker-compose up --build -d mcp-oauth`
+- Keycloak tests: `docker-compose up --build -d mcp-keycloak`
+
+### Running the Server
+```bash
+# Local development
+export $(grep -v '^#' .env | xargs)
+mcp run --transport sse nextcloud_mcp_server.app:mcp
+
+# Docker development (rebuilds after code changes)
+docker-compose up --build -d mcp        # Single-user (port 8000)
+docker-compose up --build -d mcp-oauth  # Nextcloud OAuth (port 8001)
+docker-compose up --build -d mcp-keycloak  # Keycloak OAuth (port 8002)
+```
+
+### Environment Setup
+```bash
+uv sync                # Install dependencies
+uv sync --group dev    # Install with dev dependencies
 ```
 
 ### Load Testing
 ```bash
-# Run benchmark with default settings (10 workers, 30 seconds)
+# Quick test (default: 10 workers, 30 seconds)
 uv run python -m tests.load.benchmark
 
-# Quick test with custom concurrency and duration
-uv run python -m tests.load.benchmark --concurrency 20 --duration 60
+# Custom concurrency and duration
+uv run python -m tests.load.benchmark -c 20 -d 60
 
-# Extended load test (50 workers for 5 minutes)
-uv run python -m tests.load.benchmark -c 50 -d 300
-
-# Export results to JSON for analysis
-uv run python -m tests.load.benchmark -c 20 -d 60 --output results.json
-
-# Test OAuth server on port 8001
-uv run python -m tests.load.benchmark --url http://127.0.0.1:8001/mcp
-
-# Verbose mode with detailed logging
-uv run python -m tests.load.benchmark -c 10 -d 30 --verbose
+# Export results for analysis
+uv run python -m tests.load.benchmark --output results.json --verbose
 ```
 
-**Load Testing Features:**
-- **Mixed workload** simulating realistic MCP usage (40% reads, 20% writes, 15% search, 25% other operations)
-- **Real-time progress** bar with live RPS and error counts
-- **Detailed metrics**:
-  - Throughput (requests/second)
-  - Latency percentiles (p50, p90, p95, p99)
-  - Per-operation breakdown
-  - Error rates and types
-- **Automatic cleanup** of test data
-- **JSON export** for CI/CD integration
-- **Server health checks** before starting
+**Expected Performance**: 50-200 RPS for mixed workload, p50 <100ms, p95 <500ms, p99 <1000ms.
 
-**Understanding Results:**
-- **Requests/Second (RPS)**: Higher is better. Expected baseline: 50-200 RPS for mixed workload
-- **Latency**:
-  - p50 (median): Should be <100ms for most operations
-  - p95: Should be <500ms
-  - p99: Should be <1000ms
-- **Error Rate**: Should be <1% under normal load
+## Database Inspection
 
-**Common Bottlenecks:**
-1. Nextcloud backend API response times (most common)
-2. Database connection limits
-3. HTTP client connection pooling
-4. Network I/O between containers
+**Credentials**: root/password, nextcloud/password, database: `nextcloud`
+
+### Quick Query Script (Recommended for Agents)
+
+Use `scripts/dbquery.py` for single SQL statements without requiring approval for each `docker compose exec`:
 
-### Code Quality
 ```bash
-# Format and lint code
-uv run ruff check
-uv run ruff format
+# Basic query
+./scripts/dbquery.py "SELECT COUNT(*) FROM oc_users"
 
-# Type checking
-# No explicit type checker configured - this is a Python project using ruff for linting
+# Vertical output (one column per line) - useful for wide tables
+./scripts/dbquery.py -E "SELECT * FROM oc_oidc_clients LIMIT 1"
+
+# With different credentials
+./scripts/dbquery.py -u nextcloud -p nextcloud "SHOW TABLES"
 ```
 
-### Running the Server
+### Direct Docker Access
+
+For interactive sessions or complex operations:
+
 ```bash
-# Local development - load environment variables and run
-export $(grep -v '^#' .env | xargs)
-mcp run --transport sse nextcloud_mcp_server.app:mcp
+# Connect to database
+docker compose exec db mariadb -u root -ppassword nextcloud
 
-# Docker development environment with Nextcloud instance
-docker-compose up
+# Check OAuth clients
+docker compose exec db mariadb -u root -ppassword nextcloud -e \
+  "SELECT id, name, token_type FROM oc_oidc_clients ORDER BY id DESC LIMIT 10;"
 
-# After code changes, rebuild and restart the appropriate MCP server container:
-# For basic auth changes (most common) - uses admin credentials
-docker-compose up --build -d mcp
+# Check OAuth client scopes
+docker compose exec db mariadb -u root -ppassword nextcloud -e \
+  "SELECT c.id, c.name, s.scope FROM oc_oidc_clients c LEFT JOIN oc_oidc_client_scopes s ON c.id = s.client_id WHERE c.name LIKE '%MCP%';"
 
-# For OAuth changes - uses OAuth authentication flow
-docker-compose up --build -d mcp-oauth
-
-# Build Docker image
-docker build -t nextcloud-mcp-server .
+# Check OAuth access tokens
+docker compose exec db mariadb -u root -ppassword nextcloud -e \
+  "SELECT id, client_id, user_id, created_at FROM oc_oidc_access_tokens ORDER BY created_at DESC LIMIT 10;"
 ```
 
-**Important: Two MCP Server Containers**
-- **`mcp`** (port 8000): Uses basic auth with admin credentials. Use this for most development and testing.
-- **`mcp-oauth`** (port 8001): Uses OAuth authentication. Only use this when working on OAuth-specific features or tests.
+**Important Tables**:
+- `oc_oidc_clients` - OAuth client registrations (DCR)
+- `oc_oidc_client_scopes` - Client allowed scopes
+- `oc_oidc_access_tokens` - Issued access tokens
+- `oc_oidc_authorization_codes` - Authorization codes
+- `oc_oidc_registration_tokens` - RFC 7592 registration tokens
+- `oc_oidc_redirect_uris` - Redirect URIs
+
+### SQLite Databases (MCP Services)
+
+Use `scripts/sqlitequery.py` to query SQLite databases in MCP service containers:
 
-### Environment Setup
 ```bash
-# Install dependencies
-uv sync
+# List tables
+./scripts/sqlitequery.py ".tables"
 
-# Install development dependencies
-uv sync --group dev
+# Query specific service
+./scripts/sqlitequery.py -s oauth "SELECT * FROM refresh_tokens"
+./scripts/sqlitequery.py -s keycloak "SELECT * FROM oauth_clients"
+./scripts/sqlitequery.py -s basic "SELECT * FROM app_passwords"
+
+# With column headers
+./scripts/sqlitequery.py --column "SELECT * FROM audit_logs LIMIT 5"
+
+# JSON output
+./scripts/sqlitequery.py --json "SELECT * FROM oauth_sessions"
+
+# View schema
+./scripts/sqlitequery.py -s oauth ".schema refresh_tokens"
 ```
 
-## Architecture Overview
+**Services**: `mcp` (default), `oauth`, `keycloak`, `basic`
 
-This is a Python MCP (Model Context Protocol) server that provides LLM integration with Nextcloud. The architecture follows a layered pattern:
+**SQLite Tables**:
+- `refresh_tokens` - OAuth refresh tokens with user profiles
+- `audit_logs` - Security audit trail
+- `oauth_clients` - DCR OAuth client credentials
+- `oauth_sessions` - OAuth flow session state
+- `registered_webhooks` - Webhook registrations
+- `app_passwords` - Multi-user BasicAuth passwords
+- `alembic_version` - Migration tracking
 
-### Core Components
+## Architecture Quick Reference
 
-- **`nextcloud_mcp_server/app.py`** - Main MCP server entry point using FastMCP framework
-- **`nextcloud_mcp_server/client/`** - HTTP client implementations for different Nextcloud APIs
-- **`nextcloud_mcp_server/server/`** - MCP tool/resource definitions that expose client functionality
-- **`nextcloud_mcp_server/controllers/`** - Business logic controllers (e.g., notes search)
+**For detailed architecture, see:**
+- `docs/comparison-context-agent.md` - Overall architecture
+- `docs/oauth-architecture.md` - OAuth integration patterns
+- `docs/ADR-004-progressive-consent.md` - Progressive consent implementation
 
-### Client Architecture
+**Core Components**:
+- `nextcloud_mcp_server/app.py` - FastMCP server entry point
+- `nextcloud_mcp_server/client/` - HTTP clients (Notes, Calendar, Contacts, Tables, WebDAV)
+- `nextcloud_mcp_server/server/` - MCP tool/resource definitions
+- `nextcloud_mcp_server/auth/` - OAuth/OIDC authentication
 
-- **`NextcloudClient`** - Main orchestrating client that manages all app-specific clients
-- **`BaseNextcloudClient`** - Abstract base class providing common HTTP functionality and retry logic
-- **App-specific clients**: `NotesClient`, `CalendarClient`, `ContactsClient`, `TablesClient`, `WebDAVClient`
+**Supported Apps**: Notes, Calendar (CalDAV + VTODO tasks), Contacts (CardDAV), Tables, WebDAV, Deck, Cookbook
 
-### Server Integration
+**Key Patterns**:
+1. `NextcloudClient` orchestrates all app-specific clients
+2. `BaseNextcloudClient` provides common HTTP functionality + retry logic
+3. MCP tools use context pattern: `get_client(ctx)` → `NextcloudClient`
+4. All operations are async using httpx
 
-Each Nextcloud app has a corresponding server module that:
-1. Defines MCP tools using `@mcp.tool()` decorators
-2. Defines MCP resources using `@mcp.resource()` decorators
-3. Uses the context pattern to access the `NextcloudClient` instance
+### Progressive Consent Architecture (ADR-004)
 
-### Supported Nextcloud Apps
+**Important**: Progressive consent is a *mechanism* for granting access, not a feature flag. The architecture is always present in OAuth mode. Whether provisioning tools are available is controlled by `ENABLE_OFFLINE_ACCESS`.
 
-- **Notes** - Full CRUD operations and search
-- **Calendar** - CalDAV integration with events, recurring events, attendees, and **tasks (VTODO)**
-  - **Calendar Operations**: List, create, delete calendars
-  - **Event Operations**: Full CRUD, recurring events, attendees, reminders, bulk operations
-  - **Task Operations (VTODO)**: Full CRUD for CalDAV tasks with:
-    - Status tracking (NEEDS-ACTION, IN-PROCESS, COMPLETED, CANCELLED)
-    - Priority levels (0-9, 1=highest, 9=lowest)
-    - Due dates, start dates, completion tracking
-    - Percent complete (0-100%)
-    - Categories and filtering
-    - Search across all calendars
-  - **Note**: Calendar implementation uses caldav library's AsyncDavClient
-- **Contacts** - CardDAV integration with address book operations
-- **Tables** - Row-level operations on Nextcloud Tables
-- **WebDAV** - Complete file system access
+**What is Progressive Consent?**
+- Dual OAuth flow architecture that separates client authentication (Flow 1) from resource provisioning (Flow 2)
+- Flow 1: MCP client authenticates directly to IdP with resource scopes (notes:*, calendar:*, etc.)
+  - Token audience: "mcp-server"
+  - Client receives resource-scoped token for MCP session
+- Flow 2: Server explicitly provisions Nextcloud access via separate login (only when `ENABLE_OFFLINE_ACCESS=true`)
+  - Server requests: openid, profile, email, offline_access
+  - Token audience: "nextcloud"
+  - Server receives refresh token for offline access
+  - Client never sees this token
+- Provides clear separation between session tokens and offline access tokens
 
-### Key Patterns
+**Modes:**
+- **Pass-through mode** (`ENABLE_OFFLINE_ACCESS=false`, default):
+  - No Flow 2 provisioning
+  - Server uses client's token to access Nextcloud (pass-through)
+  - No provisioning tools available
+  - Suitable for stateless, client-driven operations
+- **Offline access mode** (`ENABLE_OFFLINE_ACCESS=true`):
+  - Flow 2 provisioning available
+  - Server stores refresh tokens for background operations
+  - Provisioning tools available: `provision_nextcloud_access`, `check_logged_in`
+  - Suitable for background jobs and server-initiated operations
 
-1. **Environment-based configuration** - Uses `NextcloudClient.from_env()` to load credentials from environment variables
-2. **Async/await throughout** - All operations are async using httpx
-3. **Retry logic** - `@retry_on_429` decorator handles rate limiting
-4. **Context injection** - MCP context provides access to the authenticated client instance
-5. **Modular design** - Each Nextcloud app is isolated in its own client/server pair
+**When to use OAuth mode:**
+- Multi-user deployments
+- Background jobs requiring offline access (with `ENABLE_OFFLINE_ACCESS=true`)
+- Enhanced security with separate authorization contexts
+- Explicit user control over resource access
 
-### MCP Response Patterns
+**When to use BasicAuth instead:**
+- Simple single-user deployments
+- Local development and testing
 
-**CRITICAL: Never return raw `List[Dict]` from MCP tools - always wrap in Pydantic response models**
+**Key features:**
+- No scope escalation - client gets exactly what it requests
+- User explicitly authorizes via `provision_nextcloud_access` tool
+- Clear security boundaries between MCP session and Nextcloud access
 
-FastMCP serialization issue: raw lists get mangled into dicts with numeric string keys.
+## MCP Response Patterns (CRITICAL)
 
-**Pattern:**
+**Never return raw `List[Dict]` from MCP tools** - FastMCP mangles them into dicts with numeric string keys.
+
+**Correct Pattern**:
 1. Client methods return `List[Dict]` (raw data)
 2. MCP tools convert to Pydantic models and wrap in response object
 3. Response models inherit from `BaseResponse`, include `results` field + metadata
 
-**Reference implementations:**
-- `SearchNotesResponse` in `nextcloud_mcp_server/models/notes.py:80`
-- `SearchFilesResponse` in `nextcloud_mcp_server/models/webdav.py:113`
-- Tool examples: `nextcloud_mcp_server/server/{notes,webdav}.py`
+**Reference implementations**:
+- `nextcloud_mcp_server/models/notes.py:80` - `SearchNotesResponse`
+- `nextcloud_mcp_server/models/webdav.py:113` - `SearchFilesResponse`
+- `nextcloud_mcp_server/server/{notes,webdav}.py` - Tool examples
 
-**Testing:** Extract `data["results"]` from MCP responses, not `data` directly.
+**Testing**: Extract `data["results"]` from MCP responses, not `data` directly.
 
-### Testing Structure
+## MCP Sampling for RAG (ADR-008)
 
-- **Integration tests** in `tests/client/` and `tests/server/` - Test real Nextcloud API interactions
-- **Fixtures** in `tests/conftest.py` - Shared test setup and utilities
-- Tests are marked with `@pytest.mark.integration` for selective running
-- **Important**: Integration tests run against live Docker containers. After making code changes:
-  - For basic auth tests: rebuild with `docker-compose up --build -d mcp`
-  - For OAuth tests: rebuild with `docker-compose up --build -d mcp-oauth`
+**What is MCP Sampling?**
+MCP sampling allows servers to request LLM completions from their clients. This enables Retrieval-Augmented Generation (RAG) patterns where the server retrieves context and the client's LLM generates answers.
 
-#### Testing Best Practices
-- **MANDATORY: Always run tests after implementing features or fixing bugs**
-  - Run tests to completion before considering any task complete
-  - If tests require modifications to pass, ask for permission before proceeding
-  - **Rebuild the correct container** after code changes:
-    - For basic auth tests (most common): `docker-compose up --build -d mcp`
-    - For OAuth tests: `docker-compose up --build -d mcp-oauth`
-- **Use existing fixtures** from `tests/conftest.py` to avoid duplicate setup work:
-  - `nc_mcp_client` - MCP client session for tool/resource testing (uses `mcp` container)
-  - `nc_mcp_oauth_client` - MCP client session for OAuth testing (uses `mcp-oauth` container)
-  - `nc_client` - Direct NextcloudClient for setup/cleanup operations
-  - `temporary_note` - Creates and cleans up test notes automatically
-  - `temporary_addressbook` - Creates and cleans up test address books
-  - `temporary_contact` - Creates and cleans up test contacts
-- **Test specific functionality** after changes:
-  - For Notes changes: `uv run pytest tests/server/test_mcp.py -k "notes" -v`
-  - For specific API changes: `uv run pytest tests/client/notes/test_notes_api.py -v`
-  - For OAuth changes: `uv run pytest tests/server/test_oauth*.py -v` (remember to rebuild `mcp-oauth` container)
-- **Avoid creating standalone test scripts** - use pytest with proper fixtures instead
+**When to use sampling:**
+- Generating natural language answers from retrieved documents
+- Synthesizing information from multiple sources
+- Creating summaries with citations
 
-#### OAuth/OIDC Testing
-OAuth integration tests use **automated Playwright browser automation** to complete the OAuth flow programmatically.
+**Implementation Pattern** (see ADR-008 for details):
 
-**OAuth Testing Setup:**
-- **Main fixtures**: `nc_oauth_client`, `nc_mcp_oauth_client` - Use Playwright automation
-- **Shared OAuth Client**: All test users authenticate using a single OAuth client
-  - Stored in `.nextcloud_oauth_shared_test_client.json`
-  - Matches production MCP server behavior
-  - Each user gets their own unique access token
-  - Implementation: `shared_oauth_client_credentials` fixture in `tests/conftest.py`
-- **Available fixtures**: `playwright_oauth_token`, `nc_oauth_client`, `nc_mcp_oauth_client`
-- **Multi-user fixtures**: `alice_oauth_token`, `bob_oauth_token`, `charlie_oauth_token`, `diana_oauth_token`
-- **Requirements**: `NEXTCLOUD_HOST`, `NEXTCLOUD_USERNAME`, `NEXTCLOUD_PASSWORD` environment variables
-- Uses `pytest-playwright-asyncio` for async Playwright fixtures
-- **Playwright configuration**: Use pytest CLI args like `--browser firefox --headed` to customize
-- **Install browsers**: `uv run playwright install firefox` (or `chromium`, `webkit`)
+```python
+from mcp.types import ModelHint, ModelPreferences, SamplingMessage, TextContent
 
-**Example Commands:**
-```bash
-# Run all OAuth tests with Playwright automation using Firefox
-uv run pytest tests/server/test_oauth*.py --browser firefox -v
+@mcp.tool()
+@require_scopes("notes:read")
+async def nc_notes_semantic_search_answer(
+    query: str, ctx: Context, limit: int = 5, max_answer_tokens: int = 500
+) -> SamplingSearchResponse:
+    # 1. Retrieve documents
+    search_response = await nc_notes_semantic_search(query, ctx, limit)
 
-# Run specific tests with visible browser for debugging
-uv run pytest tests/server/test_mcp_oauth.py --browser firefox --headed -v
+    # 2. Check for no results (don't waste sampling call)
+    if not search_response.results:
+        return SamplingSearchResponse(
+            query=query,
+            generated_answer="No relevant documents found.",
+            sources=[], total_found=0, success=True
+        )
 
-# Run with Chromium (default)
-uv run pytest tests/server/test_oauth*.py -v
+    # 3. Construct prompt with retrieved context
+    prompt = f"{query}\n\nDocuments:\n{format_sources(search_response.results)}\n\nProvide answer with citations."
+
+    # 4. Request LLM completion via sampling
+    try:
+        result = await ctx.session.create_message(
+            messages=[SamplingMessage(role="user", content=TextContent(type="text", text=prompt))],
+            max_tokens=max_answer_tokens,
+            temperature=0.7,
+            model_preferences=ModelPreferences(
+                hints=[ModelHint(name="claude-3-5-sonnet")],
+                intelligencePriority=0.8,
+                speedPriority=0.5,
+            ),
+            include_context="thisServer",
+        )
+
+        return SamplingSearchResponse(
+            query=query,
+            generated_answer=result.content.text,
+            sources=search_response.results,
+            model_used=result.model,
+            stop_reason=result.stopReason,
+            success=True
+        )
+    except Exception as e:
+        # Fallback: Return documents without generated answer
+        return SamplingSearchResponse(
+            query=query,
+            generated_answer=f"[Sampling unavailable: {e}]\n\nFound {len(search_response.results)} documents.",
+            sources=search_response.results,
+            search_method="semantic_sampling_fallback",
+            success=True
+        )
 ```
 
-**Test Environment:**
-- **Two MCP server containers are available:**
-  - `mcp` (port 8000): Uses basic auth with admin credentials - for most testing
-  - `mcp-oauth` (port 8001): Uses OAuth authentication - for OAuth-specific testing
-- Start OAuth MCP server: `docker-compose up --build -d mcp-oauth`
-- **Important**: When working on OAuth functionality, always rebuild `mcp-oauth` container, not `mcp`
-- OAuth client credentials cached in `.nextcloud_oauth_shared_test_client.json`
+**Key Points**:
+- **No server-side LLM**: Server has no API keys, client controls which model is used
+- **Graceful degradation**: Tool always returns useful results even if sampling fails
+- **User control**: MCP clients SHOULD prompt users to approve sampling requests
+- **No results optimization**: Skip sampling call when no documents found
+- **Fixed prompts**: Prompts are not user-configurable to avoid injection risks
 
-**CI/CD Notes:**
-- Playwright tests run in CI/CD environments
-- Use Firefox browser in CI: `--browser firefox` (Chromium may have issues with localhost redirects)
+**Reference**: See `nc_notes_semantic_search_answer` in `nextcloud_mcp_server/server/notes.py:517` and ADR-008 for complete implementation.
 
-### Configuration Files
+## Testing Best Practices (MANDATORY)
 
-- **`pyproject.toml`** - Python project configuration using uv for dependency management
-- **`.env`** (from `env.sample`) - Environment variables for Nextcloud connection
-- **`docker-compose.yml`** - Complete development environment with Nextcloud + database
+### Always Run Tests
+- **Run tests to completion** before considering any task complete
+- **Rebuild the correct container** after code changes (see Development Commands above)
+- **If tests require modifications**, ask for permission before proceeding
+
+### Use Existing Fixtures
+See `tests/conftest.py` for 2888 lines of test infrastructure:
+- `nc_mcp_client` - MCP client for tool/resource testing (uses `mcp` container)
+- `nc_mcp_oauth_client` - MCP client for OAuth testing (uses `mcp-oauth` container)
+- `nc_client` - Direct NextcloudClient for setup/cleanup
+- `temporary_note`, `temporary_addressbook`, `temporary_contact` - Auto-cleanup
+
+### Writing Mocked Unit Tests
+For client-layer response parsing tests, use mocked HTTP responses:
+
+```python
+async def test_notes_api_get_note(mocker):
+    """Test that get_note correctly parses the API response."""
+    mock_response = create_mock_note_response(
+        note_id=123, title="Test Note", content="Test content",
+        category="Test", etag="abc123"
+    )
+
+    mock_make_request = mocker.patch.object(
+        NotesClient, "_make_request", return_value=mock_response
+    )
+
+    client = NotesClient(mocker.AsyncMock(spec=httpx.AsyncClient), "testuser")
+    note = await client.get_note(note_id=123)
+
+    assert note["id"] == 123
+    mock_make_request.assert_called_once_with("GET", "/apps/notes/api/v1/notes/123")
+```
+
+**Mock helpers in `tests/conftest.py`**: `create_mock_response()`, `create_mock_note_response()`, `create_mock_error_response()`
+
+**When to use**: Response parsing, error handling, request parameter building
+**When NOT to use**: CalDAV/CardDAV/WebDAV protocols, OAuth flows, end-to-end MCP testing
+
+### OAuth Testing
+OAuth tests use **Playwright browser automation** to complete flows programmatically.
+
+**Test Environment**:
+- Three MCP containers: `mcp` (single-user), `mcp-oauth` (Nextcloud OIDC), `mcp-keycloak` (external IdP)
+- OAuth tests require `NEXTCLOUD_HOST`, `NEXTCLOUD_USERNAME`, `NEXTCLOUD_PASSWORD` environment variables
+- Playwright configuration: `--browser firefox --headed` for debugging
+- Install browsers: `uv run playwright install firefox`
+
+**OAuth fixtures**: `nc_oauth_client`, `nc_mcp_oauth_client`, `alice_oauth_token`, `bob_oauth_token`, etc.
+
+**Shared OAuth Client**: All test users authenticate using a single OAuth client (created via DCR, deleted at session end via RFC 7592). Matches production behavior.
+
+**Run OAuth tests**:
+```bash
+uv run pytest -m oauth -v                        # All OAuth tests
+uv run pytest tests/server/oauth/ --browser firefox -v
+uv run pytest tests/server/oauth/test_oauth_core.py --browser firefox --headed -v
+```
+
+### Keycloak OAuth Testing
+**Validates ADR-002 architecture** for external identity providers and offline access patterns.
+
+**Architecture**: `MCP Client → Keycloak (OAuth) → MCP Server → Nextcloud user_oidc (validates token) → APIs`
+
+**Setup**:
+```bash
+docker-compose up -d keycloak app mcp-keycloak
+curl http://localhost:8888/realms/nextcloud-mcp/.well-known/openid-configuration
+docker compose exec app php occ user_oidc:provider keycloak
+```
+
+**Credentials**: admin/admin (Keycloak realm: `nextcloud-mcp`)
+
+**For detailed Keycloak setup, see**:
+- `docs/oauth-setup.md` - OAuth configuration
+- `docs/ADR-002-vector-sync-authentication.md` - Offline access architecture
+- `docs/audience-validation-setup.md` - Token audience validation
+- `docs/keycloak-multi-client-validation.md` - Realm-level validation
+
+## Integration Testing with Docker
+
+**Nextcloud**: `docker compose exec app php occ ...` for occ commands
+**MariaDB**: `docker compose exec db mariadb -u [user] -p [password] [database]` for queries
+
+### Querying Nextcloud Application Logs
+
+**Use this pattern** to inspect Nextcloud application logs during debugging:
+
+```bash
+# View recent log entries
+docker compose exec app cat /var/www/html/data/nextcloud.log | jq | tail
+
+# Filter by app
+docker compose exec app cat /var/www/html/data/nextcloud.log | jq 'select(.app == "astrolabe")' | tail
+
+# Filter by log level (0=DEBUG, 1=INFO, 2=WARN, 3=ERROR, 4=FATAL)
+docker compose exec app cat /var/www/html/data/nextcloud.log | jq 'select(.level >= 3)' | tail
+
+# Search for specific messages
+docker compose exec app cat /var/www/html/data/nextcloud.log | jq 'select(.message | contains("OAuth"))' | tail -20
+
+# View full exception traces
+docker compose exec app cat /var/www/html/data/nextcloud.log | jq 'select(.exception != null)' | tail -5
+```
+
+**Log Structure**: Each entry is a JSON object with fields: `reqId`, `level`, `time`, `remoteAddr`, `user`, `app`, `method`, `url`, `message`, `userAgent`, `version`, `exception`
+
+**For detailed setup, see**:
+- `docs/installation.md` - Installation guide
+- `docs/configuration.md` - Configuration options
+- `docs/authentication.md` - Authentication modes
+- `docs/running.md` - Running the server
+
+**For additional information regarding MCP during development, see**:
+- `../../Software/modelcontextprotocol/` - MCP spec
+- `../../Software/python-sdk/` - Python MCP SDK

CONTRIBUTING.md

@@ -0,0 +1,106 @@
+# Contributing to Nextcloud MCP Server
+
+## Version Management
+
+This monorepo uses commitizen for version management with **independent versioning** for two components:
+
+### Components
+
+| Component | Scope | Bump Command | Tag Example |
+|-----------|-------|--------------|-------------|
+| MCP Server | `mcp` or none | `./scripts/bump-mcp.sh` | `v0.54.0` |
+| Helm Chart | `helm` | `./scripts/bump-helm.sh` | `nextcloud-mcp-server-0.54.0` |
+
+> **Note:** The Astrolabe Nextcloud app has been moved to its own repository at [cbcoutinho/astrolabe](https://github.com/cbcoutinho/astrolabe).
+
+### Commit Message Format
+
+Use conventional commits with **scopes** to target specific components:
+
+```bash
+# MCP server changes
+feat(mcp): add calendar sync API
+fix(mcp): resolve authentication bug
+
+# Helm chart changes
+feat(helm): add resource limits
+docs(helm): update values documentation
+```
+
+**Unscoped commits** default to the MCP server:
+```bash
+feat: add new feature  # → MCP server (v0.54.0)
+```
+
+### Release Workflow
+
+#### 1. Make Changes with Scoped Commits
+
+```bash
+git commit -m "feat(helm): add ingress annotations"
+git commit -m "feat(mcp): add calendar sync"
+```
+
+#### 2. Bump Component Versions
+
+```bash
+# Bump MCP server (reads commits with scope=mcp or unscoped)
+./scripts/bump-mcp.sh
+# → Creates tag: v0.54.0
+# → Updates: pyproject.toml, Chart.yaml:appVersion
+
+# Bump Helm chart (reads commits with scope=helm)
+./scripts/bump-helm.sh
+# → Creates tag: nextcloud-mcp-server-0.54.0
+# → Updates: Chart.yaml:version
+
+```
+
+#### 3. Push Tags
+
+```bash
+git push --follow-tags
+```
+
+### Changelog Filtering
+
+Each component maintains its own `CHANGELOG.md`:
+
+- **MCP Server**: `CHANGELOG.md` (root) - includes `feat(mcp):` and unscoped commits
+- **Helm Chart**: `charts/nextcloud-mcp-server/CHANGELOG.md` - includes `feat(helm):` only
+
+### Manual Version Bumps
+
+For specific increments:
+
+```bash
+# Patch bump (0.53.0 → 0.53.1)
+uv run cz bump --increment PATCH
+
+# Minor bump (0.53.0 → 0.54.0)
+uv run cz bump --increment MINOR
+
+# Major bump (0.53.0 → 1.0.0)
+uv run cz bump --increment MAJOR
+
+# For non-MCP components, use --config
+cd charts/nextcloud-mcp-server
+uv run cz --config .cz.toml bump --increment MINOR
+```
+
+### Versioning Philosophy
+
+- **MCP Server**: Follows PEP 440, `major_version_zero = true` (0.x.x for pre-1.0)
+- **Helm Chart**: Follows PEP 440, starts at 0.53.0 (continues from current)
+
+### Chart.yaml Version vs appVersion
+
+The Helm chart has TWO version fields:
+
+- **`version`**: Chart packaging version (bumped by `feat(helm):`)
+  - Example: `0.53.0` → `0.54.0` when adding resource limits
+
+- **`appVersion`**: MCP server version being deployed (bumped by `feat(mcp):`)
+  - Example: `"0.53.0"` → `"0.54.0"` when MCP server releases
+
+This allows the chart to evolve independently from the application.

Dockerfile

@@ -1,14 +1,28 @@
-FROM ghcr.io/astral-sh/uv:0.9.4-python3.11-alpine@sha256:1a51c7710eaf839fa3365329ad993b48d17ddd9ab0f0672efaa9b09f407ebf44
+FROM docker.io/library/python:3.12-slim-trixie@sha256:f3fa41d74a768c2fce8016b98c191ae8c1bacd8f1152870a3f9f87d350920b7c
 
-# Install git (required for caldav dependency from git)
-RUN apk add --no-cache git
+COPY --from=ghcr.io/astral-sh/uv:0.10.7@sha256:edd1fd89f3e5b005814cc8f777610445d7b7e3ed05361f9ddfae67bebfe8456a /uv /uvx /bin/
+
+# Install dependencies
+# 1. git (required for caldav dependency from git)
+# 2. sqlite for development with token db
+RUN apt update && apt install --no-install-recommends --no-install-suggests -y \
+    git \
+    tesseract-ocr \
+    sqlite3 && apt clean
 
 WORKDIR /app
 
+COPY pyproject.toml uv.lock README.md .
+
+RUN uv sync --locked --no-dev --no-install-project --no-cache
+
 COPY . .
 
-RUN uv sync --locked --no-dev
+RUN uv sync --locked --no-dev --no-editable --no-cache
 
 ENV PYTHONUNBUFFERED=1
+ENV VIRTUAL_ENV=/app/.venv
+ENV PATH=/app/.venv/bin:$PATH
+ENV TESSDATA_PREFIX=/usr/share/tesseract-ocr/5/tessdata
 
-ENTRYPOINT ["/app/.venv/bin/nextcloud-mcp-server", "--host", "0.0.0.0"]
+ENTRYPOINT ["/app/.venv/bin/nextcloud-mcp-server", "run", "--host", "0.0.0.0"]

Dockerfile.smithery

@@ -0,0 +1,44 @@
+# Dockerfile for Smithery stateless deployment
+# ADR-016: Stateless mode for multi-user public Nextcloud instances
+#
+# This image excludes:
+# - Vector database dependencies (qdrant-client)
+# - Background sync workers
+# - Admin UI routes (/app)
+# - Semantic search tools
+#
+# Features included:
+# - Core Nextcloud tools (notes, calendar, contacts, files, deck, tables, cookbook)
+# - Per-session app password authentication
+# - Multi-user support via Smithery session config
+
+FROM docker.io/library/python:3.12-slim-trixie@sha256:f3fa41d74a768c2fce8016b98c191ae8c1bacd8f1152870a3f9f87d350920b7c
+
+WORKDIR /app
+
+# Install uv for fast dependency management
+COPY --from=ghcr.io/astral-sh/uv:0.10.7@sha256:edd1fd89f3e5b005814cc8f777610445d7b7e3ed05361f9ddfae67bebfe8456a /uv /uvx /bin/
+
+# Install dependencies
+# 1. git (required for caldav dependency from git)
+# 2. sqlite for development with token db
+RUN apt update && apt install --no-install-recommends --no-install-suggests -y \
+    git
+
+# Copy project files
+COPY . .
+
+RUN uv sync --locked --no-dev --no-editable --no-cache
+
+# Set Smithery mode environment variables
+ENV SMITHERY_DEPLOYMENT=true
+ENV VECTOR_SYNC_ENABLED=false
+
+# Smithery sets PORT=8081 by default
+EXPOSE 8081
+
+# Health check endpoint
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD uv run python -c "import httpx; httpx.get('http://localhost:${PORT:-8081}/health/live').raise_for_status()"
+
+CMD ["/app/.venv/bin/smithery-main"]

README.md

@@ -1,190 +1,182 @@
+<p align="center">
+  <img src="astrolabe.svg" alt="Nextcloud MCP Server" width="128" height="128">
+</p>
+
 # Nextcloud MCP Server
 
 [![Docker Image](https://img.shields.io/badge/docker-ghcr.io/cbcoutinho/nextcloud--mcp--server-blue)](https://github.com/cbcoutinho/nextcloud-mcp-server/pkgs/container/nextcloud-mcp-server)
+[![smithery badge](https://smithery.ai/badge/@cbcoutinho/nextcloud-mcp-server)](https://smithery.ai/server/@cbcoutinho/nextcloud-mcp-server)
 
-**Enable AI assistants to interact with your Nextcloud instance.**
+**A production-ready MCP server that connects AI assistants to your Nextcloud instance.**
 
-The Nextcloud MCP (Model Context Protocol) server allows Large Language Models like Claude, GPT, and Gemini to interact with your Nextcloud data through a secure API. Create notes, manage calendars, organize contacts, work with files, and more - all through natural language.
+Enable Large Language Models like Claude, GPT, and Gemini to interact with your Nextcloud data through a secure API. Create notes, manage calendars, organize contacts, work with files, and more - all through natural language conversations.
+
+This is a **dedicated standalone MCP server** designed for external MCP clients like Claude Code and IDEs. It runs independently of Nextcloud (Docker, VM, Kubernetes, or local) and provides deep CRUD operations across Nextcloud apps.
 
 > [!NOTE]
-> **Nextcloud has two ways to enable AI access:** Nextcloud provides [Context Agent](https://github.com/nextcloud/context_agent), an AI agent backend that powers the [Assistant](https://github.com/nextcloud/assistant) app and allows AI to interact with Nextcloud apps like Calendar, Talk, and Contacts. Context Agent runs as an ExApp inside Nextcloud and also exposes an MCP server endpoint for external LLMs. This project (Nextcloud MCP Server) is a **dedicated standalone MCP server** designed specifically for external MCP clients like Claude Code and IDEs, with deep CRUD operations and OAuth support. See our [detailed comparison](docs/comparison-context-agent.md) to understand which approach fits your use case.
-
-## Features
-
-### Supported Nextcloud Apps
-
-| App | Support | Features |
-|-----|---------|----------|
-| **Notes** | ✅ Full | Create, read, update, delete, search notes. Handle attachments. |
-| **Calendar** | ✅ Full | Manage events, recurring events, reminders, attendees via CalDAV. |
-| **Contacts** | ✅ Full | CRUD operations for contacts and address books via CardDAV. |
-| **Cookbook** | ✅ Full | Manage recipes with schema.org metadata. Import from URLs, search, categorize. |
-| **Files (WebDAV)** | ✅ Full | Complete file system access - browse, read, write, organize files. |
-| **Deck** | ✅ Full | Project management - boards, stacks, cards, labels, assignments. |
-| **Tables** | ⚠️ Partial | Row-level operations. Table management not yet supported. |
-| **Tasks** | ❌ Planned | [Issue #73](https://github.com/cbcoutinho/nextcloud-mcp-server/issues/73) |
-
-Want to see another Nextcloud app supported? [Open an issue](https://github.com/cbcoutinho/nextcloud-mcp-server/issues) or contribute a pull request!
-
-### Authentication
-
-| Mode | Security | Best For |
-|------|----------|----------|
-| **OAuth2/OIDC** ⚠️ **Experimental** | 🔒 High | Testing, evaluation (requires patches) |
-| **Basic Auth** ✅ | Lower | Development, testing, production |
-
-> [!IMPORTANT]
-> **OAuth is experimental** and requires manual patches to upstream Nextcloud apps. Specifically:
-> - **Required patch**: `user_oidc` app needs modifications for Bearer token support ([issue #1221](https://github.com/nextcloud/user_oidc/issues/1221))
-> - **Impact**: Without the patch, most app-specific APIs (Notes, Calendar, Contacts, Deck, etc.) will fail with 401 errors
-> - **Production use**: Wait for upstream patches to be merged into official releases
->
-> See [OAuth Upstream Status](docs/oauth-upstream-status.md) for detailed information on required patches and workarounds.
-
-OAuth2/OIDC provides secure, per-user authentication with access tokens. See [Authentication Guide](docs/authentication.md) for details.
+> **Looking for AI features inside Nextcloud?** Nextcloud also provides [Context Agent](https://github.com/nextcloud/context_agent), which powers the Assistant app and runs as an ExApp inside Nextcloud. See [docs/comparison-context-agent.md](docs/comparison-context-agent.md) for a detailed comparison of use cases.
 
 ## Quick Start
 
-### 1. Install
+The fastest way to get started is via [Smithery](https://smithery.ai/server/@cbcoutinho/nextcloud-mcp-server) - no Docker or self-hosting required:
+
+1. Visit the [Smithery marketplace page](https://smithery.ai/server/@cbcoutinho/nextcloud-mcp-server)
+2. Click "Deploy" and configure:
+   - **Nextcloud URL**: Your Nextcloud instance (e.g., `https://cloud.example.com`)
+   - **Username**: Your Nextcloud username
+   - **App Password**: Generate one in Nextcloud → Settings → Security → Devices & sessions
+
+> [!NOTE]
+> Smithery runs in stateless mode without semantic search. For full features, use [Docker](#docker-self-hosted) or see [ADR-016](docs/ADR-016-smithery-stateless-deployment.md).
+
+## Docker (Self-Hosted)
+
+For full features including semantic search, run with Docker:
 
 ```bash
-# Clone the repository
-git clone https://github.com/cbcoutinho/nextcloud-mcp-server.git
-cd nextcloud-mcp-server
-
-# Install with uv (recommended)
-uv sync
-
-# Or using Docker
-docker pull ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
-```
-
-See [Installation Guide](docs/installation.md) for detailed instructions.
-
-### 2. Configure
-
-Create a `.env` file:
-
-```bash
-# Copy the sample
-cp env.sample .env
-```
-
-**For Basic Auth (recommended for most users):**
-```dotenv
+# 1. Create a minimal configuration
+cat > .env << EOF
 NEXTCLOUD_HOST=https://your.nextcloud.instance.com
 NEXTCLOUD_USERNAME=your_username
 NEXTCLOUD_PASSWORD=your_app_password
-```
+EOF
 
-**For OAuth (experimental - requires patches):**
-```dotenv
-NEXTCLOUD_HOST=https://your.nextcloud.instance.com
-```
-
-See [Configuration Guide](docs/configuration.md) for all options.
-
-### 3. Set Up Authentication
-
-**Basic Auth Setup (recommended):**
-1. Create an app password in Nextcloud (Settings → Security → Devices & sessions)
-2. Add credentials to `.env` file
-3. Start the server
-
-**OAuth Setup (experimental):**
-1. Install Nextcloud OIDC apps (`oidc` + `user_oidc`)
-2. **Apply required patches** to `user_oidc` app (see [OAuth Upstream Status](docs/oauth-upstream-status.md))
-3. Enable dynamic client registration
-4. Configure Bearer token validation
-5. Start the server
-
-See [OAuth Quick Start](docs/quickstart-oauth.md) for 5-minute setup or [OAuth Setup Guide](docs/oauth-setup.md) for detailed instructions.
-
-### 4. Run the Server
-
-```bash
-# Load environment variables
-export $(grep -v '^#' .env | xargs)
-
-# Start with Basic Auth (default)
-uv run nextcloud-mcp-server
-
-# Or start with OAuth (experimental - requires patches)
-uv run nextcloud-mcp-server --oauth
-
-# Or with Docker
+# 2. Start the server
 docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
   ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
+
+# 3. Test the connection
+curl http://127.0.0.1:8000/health/ready
+
+# 4. Connect to the endpoint
+http://127.0.0.1:8000/sse
+
+# Or with --transport streamable-http
+http://127.0.0.1:8000/mcp
 ```
 
-The server starts on `http://127.0.0.1:8000` by default.
-
-See [Running the Server](docs/running.md) for more options.
-
-### 5. Connect an MCP Client
-
-Test with MCP Inspector:
+**Docker Compose Profiles** (for development/testing):
 
 ```bash
-uv run mcp dev
+docker compose --profile single-user up -d       # Port 8000
+docker compose --profile multi-user-basic up -d   # Port 8003
+docker compose --profile oauth up -d              # Port 8001
+docker compose --profile login-flow up -d         # Port 8004
 ```
 
-Or connect from:
-- Claude Desktop
-- Any MCP-compatible client
+**Next Steps:**
+- Connect your MCP client (Claude Desktop, IDEs, `mcp dev`, etc.)
+- See [docs/installation.md](docs/installation.md) for other deployment options (local, Kubernetes)
+
+## Key Features
+
+- **90+ MCP Tools** - Comprehensive API coverage across 8 Nextcloud apps
+- **MCP Resources** - Structured data URIs for browsing Nextcloud data
+- **Semantic Search (Experimental)** - Optional vector-powered search for Notes, Files, News items, and Deck cards (requires Qdrant + Ollama)
+- **Document Processing** - OCR and text extraction from PDFs, DOCX, images with progress notifications
+- **Flexible Deployment** - Docker, Kubernetes (Helm), VM, or local installation
+- **Production-Ready Auth** - Basic Auth with app passwords (recommended) or OAuth2/OIDC (experimental)
+- **Multiple Transports** - SSE, HTTP, and streamable-http support
+
+## Supported Apps
+
+| App | Tools | Capabilities |
+|-----|-------|--------------|
+| **Notes** | 7 | Full CRUD, keyword search, semantic search |
+| **Calendar** | 20+ | Events, todos (tasks), recurring events, attendees, availability |
+| **Contacts** | 8 | Full CardDAV support, address books |
+| **Files (WebDAV)** | 12 | Filesystem access, OCR/document processing |
+| **Deck** | 15 | Boards, stacks, cards, labels, assignments |
+| **Cookbook** | 13 | Recipe management, URL import (schema.org) |
+| **Tables** | 5 | Row operations on Nextcloud Tables |
+| **Sharing** | 10+ | Create and manage shares |
+| **Semantic Search** | 2+ | Vector search for Notes, Files, News items, and Deck cards (experimental, opt-in, requires infrastructure) |
+
+Want to see another Nextcloud app supported? [Open an issue](https://github.com/cbcoutinho/nextcloud-mcp-server/issues) or contribute a pull request!
+
+## Authentication
+
+> [!IMPORTANT]
+> **OAuth2/OIDC is experimental** and requires a manual patch to the `user_oidc` app:
+> - **Required patch**: Bearer token support ([issue #1221](https://github.com/nextcloud/user_oidc/issues/1221))
+> - **Impact**: Without the patch, most app-specific APIs fail with 401 errors
+> - **Recommendation**: Use Basic Auth for production until upstream patches are merged
+>
+> See [docs/oauth-upstream-status.md](docs/oauth-upstream-status.md) for patch status and workarounds.
+
+**Recommended:** Basic Auth with app-specific passwords provides secure, production-ready authentication. See [docs/authentication.md](docs/authentication.md) for setup details and OAuth configuration.
+
+### Authentication Modes
+
+The server supports four authentication modes:
+
+**Single-User (BasicAuth):**
+- One set of credentials shared by all MCP clients
+- Simple setup: username + app password in environment variables
+- All clients access Nextcloud as the same user
+- Best for: Personal use, development, single-user deployments
+
+**Multi-User (BasicAuth Pass-Through):**
+- MCP clients send credentials via Authorization header
+- Server passes through to Nextcloud (stateless by default)
+- Optional offline access for background operations (`ENABLE_MULTI_USER_BASIC_AUTH=true`)
+- Best for: Multi-user setups without OAuth infrastructure
+
+**Multi-User (OAuth):**
+- Each MCP client authenticates separately with their own Nextcloud account
+- Per-user scopes and permissions (clients only see tools they're authorized for)
+- More secure: tokens expire, credentials never shared with server
+- Best for: Teams, multi-user deployments, production environments with multiple users
+- Requires: Patches to the `user_oidc` app (experimental)
+
+**Multi-User (Login Flow v2):**
+- Uses Nextcloud's native Login Flow v2 to obtain per-user app passwords
+- No OAuth patches required — works with stock Nextcloud
+- Each user authenticates via browser, server manages app passwords
+- Best for: Multi-user deployments without OAuth infrastructure (`ENABLE_LOGIN_FLOW=true`)
+- Experimental: See [ADR-022](docs/ADR-022-deployment-mode-consolidation.md) for details
+
+See [docs/authentication.md](docs/authentication.md) for detailed setup instructions.
+
+## Semantic Search
+
+The server provides an experimental RAG pipeline to enable _Semantic Search_ that enables MCP clients to find information in Nextcloud based on **meaning** rather than just keywords. Instead of matching "machine learning" only when those exact words appear, it understands that "neural networks," "AI models," and "deep learning" are semantically related concepts.
+
+**Example:**
+- **Keyword search**: Query "car" only finds notes containing "car"
+- **Semantic search**: Query "car" also finds notes about "automobile," "vehicle," "sedan," "transportation"
+
+This enables natural language queries and helps discover related content across your Nextcloud notes.
+
+> [!NOTE]
+> **Semantic Search is experimental and opt-in:**
+> - Disabled by default (`ENABLE_SEMANTIC_SEARCH=false`)
+> - Currently supports Notes app only (multi-app support planned)
+> - Requires additional infrastructure: vector database + embedding service
+> - Answer generation (`nc_semantic_search_answer`) requires MCP client sampling support
+>
+> See [docs/semantic-search-architecture.md](docs/semantic-search-architecture.md) for architecture details and [docs/configuration.md](docs/configuration.md) for setup instructions.
 
 ## Documentation
 
 ### Getting Started
-- **[Installation](docs/installation.md)** - Install the server
-- **[Configuration](docs/configuration.md)** - Environment variables and settings
-- **[Authentication](docs/authentication.md)** - OAuth vs BasicAuth
-- **[Running the Server](docs/running.md)** - Start and manage the server
+- **[Installation](docs/installation.md)** - Docker, Kubernetes, local, or VM deployment
+- **[Configuration](docs/configuration.md)** - Environment variables and advanced options
+- **[Authentication](docs/authentication.md)** - Basic Auth vs OAuth2/OIDC setup
+- **[Running the Server](docs/running.md)** - Start, manage, and troubleshoot
 
-### Architecture
-- **[Comparison with Context Agent](docs/comparison-context-agent.md)** - How this MCP server differs from Nextcloud's Context Agent
+### Features
+- **[App Documentation](docs/)** - Notes, Calendar, Contacts, WebDAV, Deck, Cookbook, Tables
+- **[Document Processing](docs/configuration.md#document-processing)** - OCR and text extraction setup
+- **[Semantic Search Architecture](docs/semantic-search-architecture.md)** - Experimental vector search (Notes, Files, News items, Deck cards; opt-in)
+- **[Vector Sync UI Guide](docs/user-guide/vector-sync-ui.md)** - Browser interface for semantic search visualization and testing
 
-### OAuth Documentation (Experimental)
-- **[OAuth Quick Start](docs/quickstart-oauth.md)** - 5-minute setup guide
-- **[OAuth Setup Guide](docs/oauth-setup.md)** - Detailed setup instructions
-- **[OAuth Architecture](docs/oauth-architecture.md)** - How OAuth works
-- **[OAuth Troubleshooting](docs/oauth-troubleshooting.md)** - OAuth-specific issues
-- **[Upstream Status](docs/oauth-upstream-status.md)** - **Required patches and PRs** ⚠️
-
-### Reference
+### Advanced Topics
+- **[OAuth Architecture](docs/oauth-architecture.md)** - How OAuth works (experimental)
+- **[OAuth Quick Start](docs/quickstart-oauth.md)** - 5-minute OAuth setup
+- **[OAuth Setup Guide](docs/oauth-setup.md)** - Detailed OAuth configuration
 - **[Troubleshooting](docs/troubleshooting.md)** - Common issues and solutions
-
-### App-Specific Documentation
-- [Notes API](docs/notes.md)
-- [Calendar (CalDAV)](docs/calendar.md)
-- [Contacts (CardDAV)](docs/contacts.md)
-- [Cookbook](docs/cookbook.md)
-- [Deck](docs/deck.md)
-- [Tables](docs/table.md)
-- [WebDAV](docs/webdav.md)
-
-## MCP Tools & Resources
-
-The server exposes Nextcloud functionality through MCP tools (for actions) and resources (for data browsing).
-
-### Tools
-Tools enable AI assistants to perform actions:
-- `nc_notes_create_note` - Create a new note
-- `nc_cookbook_import_recipe` - Import recipes from URLs with schema.org metadata
-- `deck_create_card` - Create a Deck card
-- `nc_calendar_create_event` - Create a calendar event
-- `nc_contacts_create_contact` - Create a contact
-- And many more...
-
-### Resources
-Resources provide read-only access to Nextcloud data:
-- `nc://capabilities` - Server capabilities
-- `cookbook://version` - Cookbook app version info
-- `nc://Deck/boards/{board_id}` - Deck board data
-- `notes://settings` - Notes app settings
-- And more...
-
-Run `uv run nextcloud-mcp-server --help` to see all available options.
+- **[Comparison with Context Agent](docs/comparison-context-agent.md)** - When to use each approach
 
 ## Examples
 
@@ -194,45 +186,31 @@ AI: "Create a note called 'Meeting Notes' with today's agenda"
 → Uses nc_notes_create_note tool
 ```
 
-### Manage Recipes
+### Import Recipes
 ```
-AI: "Import the recipe from this URL: https://www.example.com/recipe/chocolate-cake"
-→ Uses nc_cookbook_import_recipe tool to extract schema.org metadata
+AI: "Import the recipe from https://www.example.com/recipe/chocolate-cake"
+→ Uses nc_cookbook_import_recipe tool with schema.org metadata extraction
 ```
 
-### Manage Calendar
+### Schedule Meetings
 ```
 AI: "Schedule a team meeting for next Tuesday at 2pm"
 → Uses nc_calendar_create_event tool
 ```
 
-### Organize Files
+### Manage Files
 ```
 AI: "Create a folder called 'Project X' and move all PDFs there"
-→ Uses WebDAV tools (nc_webdav_create_directory, nc_webdav_move)
+→ Uses nc_webdav_create_directory and nc_webdav_move tools
 ```
 
-### Project Management
+### Semantic Search (Experimental, Opt-in)
 ```
-AI: "Create a new Deck board for Q1 planning with Todo, In Progress, and Done stacks"
-→ Uses deck_create_board and deck_create_stack tools
+AI: "Find notes related to machine learning concepts"
+→ Uses nc_semantic_search to find semantically similar notes (requires Qdrant + Ollama setup)
 ```
 
-## Transport Protocols
-
-The server supports multiple MCP transport protocols:
-
-- **streamable-http** (recommended) - Modern streaming protocol
-- **sse** (default, deprecated) - Server-Sent Events for backward compatibility
-- **http** - Standard HTTP protocol
-
-```bash
-# Use streamable-http (recommended)
-uv run nextcloud-mcp-server --transport streamable-http
-```
-
-> [!WARNING]
-> SSE transport is deprecated and will be removed in a future MCP specification version. Please migrate to `streamable-http`.
+**Note:** For AI-generated answers with citations, use `nc_semantic_search_answer` (requires MCP client with sampling support).
 
 ## Contributing
 
@@ -240,17 +218,17 @@ Contributions are welcome!
 
 - Report bugs or request features: [GitHub Issues](https://github.com/cbcoutinho/nextcloud-mcp-server/issues)
 - Submit improvements: [Pull Requests](https://github.com/cbcoutinho/nextcloud-mcp-server/pulls)
-- Read [CLAUDE.md](CLAUDE.md) for development guidelines
+- Development guidelines: [CLAUDE.md](CLAUDE.md)
 
 ## Security
 
 [![MseeP.ai Security Assessment](https://mseep.net/pr/cbcoutinho-nextcloud-mcp-server-badge.png)](https://mseep.ai/app/cbcoutinho-nextcloud-mcp-server)
 
 This project takes security seriously:
-- OAuth2/OIDC support (experimental - requires upstream patches)
-- Basic Auth with app-specific passwords (recommended)
-- No credential storage with OAuth mode
+- Production-ready Basic Auth with app-specific passwords
+- OAuth2/OIDC support (experimental, requires upstream patches)
 - Per-user access tokens
+- No credential storage in OAuth mode
 - Regular security assessments
 
 Found a security issue? Please report it privately to the maintainers.

alembic.ini

@@ -0,0 +1,90 @@
+# Alembic configuration file for nextcloud-mcp-server
+
+[alembic]
+# Path to migration scripts
+script_location = nextcloud_mcp_server/alembic
+
+# Template used to generate migration file names
+# Default: %%(rev)s_%%(slug)s
+file_template = %%(year)d%%(month).2d%%(day).2d_%%(hour).2d%%(minute).2d_%%(rev)s_%%(slug)s
+
+# Timezone for migration timestamps
+# Default: utc
+timezone = utc
+
+# Max length of characters to apply to the "slug" field
+# Default: 40
+# truncate_slug_length = 40
+
+# Set to 'true' to run the environment during the 'revision' command
+# Default: false
+# revision_environment = false
+
+# Set to 'true' to allow .pyc and .pyo files without a source .py file
+# Default: false
+# sourceless = false
+
+# Version location specification
+# Supports single or multiple directories
+version_locations = nextcloud_mcp_server/alembic/versions
+
+# Path separator for version locations (required to suppress deprecation warning)
+# Use os (for cross-platform compatibility)
+path_separator = os
+
+# Set to 'true' to search source files recursively in each "version_locations" directory
+# Default: false
+# recursive_version_locations = false
+
+# Output encoding used when revision files are written
+# Default: utf-8
+# output_encoding = utf-8
+
+# Database URL - can be overridden by:
+# 1. Passing -x database_url=... to alembic commands
+# 2. Setting in environment via get_database_url() in env.py
+# Default: sqlite:///app/data/tokens.db
+sqlalchemy.url = sqlite+aiosqlite:////app/data/tokens.db
+
+[post_write_hooks]
+# Post-write hooks allow you to run scripts after generating migration files
+# Example: format migrations with ruff
+# hooks = ruff
+# ruff.type = exec
+# ruff.executable = ruff
+# ruff.options = format REVISION_SCRIPT_FILENAME
+
+# Logging configuration
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

alembic/README

@@ -0,0 +1,71 @@
+Database Migrations for nextcloud-mcp-server
+============================================
+
+This directory contains Alembic database migrations for the token storage database.
+
+Structure
+---------
+- env.py: Alembic environment configuration
+- script.py.mako: Template for generating new migration files
+- versions/: Directory containing migration scripts
+
+Usage
+-----
+Migrations are managed via the CLI:
+
+    # Upgrade database to latest version
+    uv run nextcloud-mcp-server db upgrade
+
+    # Show current database version
+    uv run nextcloud-mcp-server db current
+
+    # Show migration history
+    uv run nextcloud-mcp-server db history
+
+    # Create a new migration (developers only)
+    uv run nextcloud-mcp-server db migrate "description of changes"
+
+    # Downgrade database by one version (emergency use only)
+    uv run nextcloud-mcp-server db downgrade
+
+Direct Alembic Usage
+--------------------
+You can also use Alembic commands directly:
+
+    # Specify database URL via -x flag
+    uv run alembic -x database_url=sqlite+aiosqlite:////path/to/tokens.db upgrade head
+
+    # Or set in alembic.ini and run
+    uv run alembic upgrade head
+    uv run alembic current
+    uv run alembic history
+
+Writing Migrations
+------------------
+Since we don't use SQLAlchemy models, migrations are written with raw SQL:
+
+    def upgrade() -> None:
+        op.execute("""
+            ALTER TABLE refresh_tokens
+            ADD COLUMN new_field TEXT
+        """)
+
+    def downgrade() -> None:
+        # SQLite doesn't support DROP COLUMN, use table recreation
+        op.execute("""
+            CREATE TABLE refresh_tokens_new AS
+            SELECT user_id, encrypted_token, ... FROM refresh_tokens
+        """)
+        op.execute("DROP TABLE refresh_tokens")
+        op.execute("ALTER TABLE refresh_tokens_new RENAME TO refresh_tokens")
+
+Migration File Naming
+---------------------
+Format: YYYYMMDD_HHMM_<revision>_<slug>.py
+Example: 20251217_2200_001_initial_schema.py
+
+Notes
+-----
+- Migrations run automatically when RefreshTokenStorage.initialize() is called
+- Existing databases are automatically stamped with the initial version
+- SQLite has limited ALTER TABLE support - complex changes require table recreation

alembic/script.py.mako

@@ -0,0 +1,26 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision = ${repr(up_revision)}
+down_revision = ${repr(down_revision)}
+branch_labels = ${repr(branch_labels)}
+depends_on = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    """Apply migration changes to upgrade the database schema."""
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    """Revert migration changes to downgrade the database schema."""
+    ${downgrades if downgrades else "pass"}

app-hooks/patches/cors-bearer-token.patch

@@ -0,0 +1,18 @@
+diff --git a/lib/private/AppFramework/Middleware/Security/CORSMiddleware.php b/lib/private/AppFramework/Middleware/Security/CORSMiddleware.php
+index 4453f5a7d4b..f1ca9b48d21 100644
+--- a/lib/private/AppFramework/Middleware/Security/CORSMiddleware.php
++++ b/lib/private/AppFramework/Middleware/Security/CORSMiddleware.php
+@@ -73,6 +73,13 @@ class CORSMiddleware extends Middleware {
+ 			$user = array_key_exists('PHP_AUTH_USER', $this->request->server) ? $this->request->server['PHP_AUTH_USER'] : null;
+ 			$pass = array_key_exists('PHP_AUTH_PW', $this->request->server) ? $this->request->server['PHP_AUTH_PW'] : null;
+ 
++			// Allow Bearer token authentication for CORS requests
++			// Bearer tokens are stateless and don't require CSRF protection
++			$authorizationHeader = $this->request->getHeader('Authorization');
++			if (!empty($authorizationHeader) && str_starts_with($authorizationHeader, 'Bearer ')) {
++				return;
++			}
++
+ 			// Allow to use the current session if a CSRF token is provided
+ 			if ($this->request->passesCSRFCheck()) {
+ 				return;

app-hooks/post-installation/00-setup-trusted-domains.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+set -euox pipefail
+
+php /var/www/html/occ config:system:set trusted_domains 2 --value=host.docker.internal
+
+# Set overwrite.cli.url to the external URL for OIDC discovery
+# This ensures OAuth flows redirect to the correct external URL
+# Important: The Astrolabe OAuth controller makes internal HTTP requests to /.well-known/openid-configuration
+# which needs to return URLs reachable by external browsers (localhost:8080, not localhost:80)
+php /var/www/html/occ config:system:set overwrite.cli.url --value="http://localhost:8080"

app-hooks/post-installation/01-disable-security-protections.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+set -euox pipefail
+echo "Disabling bruteforce protection and rate limiting for dev/CI..."
+php /var/www/html/occ config:system:set auth.bruteforce.protection.enabled --value=false --type=boolean
+php /var/www/html/occ config:system:set ratelimit.protection.enabled --value=false --type=boolean
+echo "Bruteforce protection and rate limiting disabled."

app-hooks/post-installation/10-install-calendar-app.sh

@@ -6,7 +6,7 @@ echo "Installing and configuring Calendar app..."
 
 # Enable calendar app
 php /var/www/html/occ app:enable calendar
-php /var/www/html/occ app:enable --force tasks # Not currently supported on 32
+php /var/www/html/occ app:enable tasks
 
 # Wait for calendar app to be fully initialized
 echo "Waiting for calendar app to initialize..."

app-hooks/post-installation/10-install-news-app.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+
+set -euox pipefail
+
+php /var/www/html/occ app:enable news

app-hooks/post-installation/10-install-notes-app.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+
+set -euox pipefail
+
+echo "Installing and configuring notes app for testing..."
+
+# Check if development notes app is mounted at /opt/apps/notes
+if [ -d /opt/apps/notes ]; then
+    echo "Development notes app found at /opt/apps/notes"
+
+    # Remove any existing notes app in apps (from app store or old symlink)
+    if [ -e /var/www/html/custom_apps/notes ]; then
+        echo "Removing existing notes in apps..."
+        rm -rf /var/www/html/custom_apps/notes
+    fi
+
+    # Create symlink from apps to the mounted development version
+    # Per Nextcloud docs: apps outside server root need symlinks in server root
+    echo "Creating symlink: custom_apps/notes -> /opt/apps/notes"
+    ln -sf /opt/apps/notes /var/www/html/custom_apps/notes
+
+    echo "Enabling notes app from /opt/apps (development mode via symlink)"
+    php /var/www/html/occ app:enable notes
+elif [ -d /var/www/html/custom_apps/notes ]; then
+    echo "notes app directory found in apps (already installed)"
+    php /var/www/html/occ app:enable notes
+else
+    echo "notes app not found, installing from app store..."
+    php /var/www/html/occ app:install notes
+    php /var/www/html/occ app:enable notes
+fi

app-hooks/post-installation/10-install-oidc-app.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+
+set -euox pipefail
+
+echo "Installing and configuring OIDC app for testing..."
+
+# Check if development OIDC app is mounted at /opt/apps/oidc
+if [ -d /opt/apps/oidc ]; then
+    echo "Development OIDC app found at /opt/apps/oidc"
+
+    # Remove any existing OIDC app in custom_apps (from app store or old symlink)
+    if [ -e /var/www/html/custom_apps/oidc ]; then
+        echo "Removing existing OIDC in custom_apps..."
+        rm -rf /var/www/html/custom_apps/oidc
+    fi
+
+    # Create symlink from custom_apps to the mounted development version
+    # Per Nextcloud docs: apps outside server root need symlinks in server root
+    echo "Creating symlink: custom_apps/oidc -> /opt/apps/oidc"
+    ln -sf /opt/apps/oidc /var/www/html/custom_apps/oidc
+
+    echo "Enabling OIDC app from /opt/apps (development mode via symlink)"
+    php /var/www/html/occ app:enable oidc
+elif [ -d /var/www/html/custom_apps/oidc ]; then
+    echo "OIDC app directory found in custom_apps (already installed)"
+    php /var/www/html/occ app:enable oidc
+else
+    echo "OIDC app not found, installing from app store..."
+    php /var/www/html/occ app:install oidc
+    php /var/www/html/occ app:enable oidc
+fi
+
+# Configure OIDC Identity Provider with dynamic client registration enabled
+php /var/www/html/occ config:app:set oidc dynamic_client_registration --value='true' # NOTE: String
+php /var/www/html/occ config:app:set oidc proof_key_for_code_exchange --value=true --type=boolean
+php /var/www/html/occ config:app:set oidc allow_user_settings --value='enabled'
+php /var/www/html/occ config:app:set oidc default_token_type --value='jwt'
+php /var/www/html/occ config:app:set oidc default_resource_identifier --value='http://localhost:8080'
+
+echo "OIDC app installed and configured successfully"

app-hooks/post-installation/10-install-user_oidc-app.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+
+set -euox pipefail
+
+echo "Installing and configuring user_oidc app for testing..."
+
+# Enable the user_oidc app (OIDC client for bearer token validation)
+php /var/www/html/occ app:enable user_oidc
+
+# Configure user_oidc to validate bearer tokens from the OIDC Identity Provider
+php /var/www/html/occ config:system:set user_oidc oidc_provider_bearer_validation --value=true --type=boolean
+php /var/www/html/occ config:system:set user_oidc httpclient.allowselfsigned --value=true --type=boolean
+
+# Allow Nextcloud to connect to local/internal servers (required for external IdP mode)
+# This enables user_oidc to fetch JWKS from internal Keycloak container
+php /var/www/html/occ config:system:set allow_local_remote_servers --value=true --type=boolean
+
+# Note: The user_oidc app_api session flag patch is NOT required when using the
+# CORSMiddleware Bearer token patch (20-apply-cors-bearer-token-patch.sh).
+# The CORSMiddleware patch fixes the root cause by allowing Bearer tokens to bypass
+# CORS/CSRF checks at the framework level.

app-hooks/post-installation/15-setup-keycloak-provider.sh

@@ -0,0 +1,108 @@
+#!/bin/bash
+#
+# Configure user_oidc to accept bearer tokens from Keycloak
+#
+# This script sets up Keycloak as an external OIDC provider for Nextcloud.
+# It enables bearer token validation, allowing the MCP server to use Keycloak
+# tokens to access Nextcloud APIs without admin credentials.
+#
+
+set -e
+
+echo "===================================================================="
+echo "Configuring user_oidc provider for Keycloak..."
+echo "===================================================================="
+
+# Quick check: Is keycloak service in the Docker network?
+# When the keycloak profile is not active, this hostname won't resolve.
+if ! getent hosts keycloak >/dev/null 2>&1; then
+    echo "  Keycloak service not detected in Docker network (profile not active)"
+    echo "  Skipping keycloak provider configuration"
+    exit 0
+fi
+
+# Wait for Keycloak to be ready and realm to be available
+echo "Waiting for Keycloak realm to be available..."
+MAX_RETRIES=30
+RETRY_COUNT=0
+
+while [ $RETRY_COUNT -lt $MAX_RETRIES ]; do
+    if curl -sf http://keycloak:8080/realms/nextcloud-mcp/.well-known/openid-configuration > /dev/null 2>&1; then
+        echo "✓ Keycloak realm is ready"
+        break
+    fi
+    echo "  Waiting for Keycloak... (attempt $((RETRY_COUNT + 1))/$MAX_RETRIES)"
+    sleep 5
+    RETRY_COUNT=$((RETRY_COUNT + 1))
+done
+
+if [ $RETRY_COUNT -eq $MAX_RETRIES ]; then
+    echo "⚠ Warning: Keycloak not available after $MAX_RETRIES attempts"
+    echo "  Keycloak provider will not be configured"
+    echo "  You can configure it manually using:"
+    echo "  docker compose exec app php occ user_oidc:provider keycloak \\"
+    echo "    --clientid='nextcloud' \\"
+    echo "    --clientsecret='nextcloud-secret-change-in-production' \\"
+    echo "    --discoveryuri='http://keycloak:8080/realms/nextcloud-mcp/.well-known/openid-configuration' \\"
+    echo "    --check-bearer=1 \\"
+    echo "    --bearer-provisioning=1 \\"
+    echo "    --unique-uid=1"
+    exit 0
+fi
+
+# Check if provider already exists
+if php /var/www/html/occ user_oidc:provider keycloak 2>/dev/null | grep -q "Identifier"; then
+    echo "  Keycloak provider already exists, updating configuration..."
+
+    # Update existing provider
+    php /var/www/html/occ user_oidc:provider keycloak \
+        --clientid="nextcloud" \
+        --clientsecret="nextcloud-secret-change-in-production" \
+        --discoveryuri="http://keycloak:8080/realms/nextcloud-mcp/.well-known/openid-configuration" \
+        --check-bearer=1 \
+        --bearer-provisioning=1 \
+        --unique-uid=1 \
+        --mapping-uid="sub" \
+        --mapping-display-name="name" \
+        --mapping-email="email" \
+        --scope="openid profile email offline_access"
+
+    echo "✓ Updated Keycloak provider configuration"
+else
+    echo "  Creating new Keycloak provider..."
+
+    # Create new provider
+    php /var/www/html/occ user_oidc:provider keycloak \
+        --clientid="nextcloud" \
+        --clientsecret="nextcloud-secret-change-in-production" \
+        --discoveryuri="http://keycloak:8080/realms/nextcloud-mcp/.well-known/openid-configuration" \
+        --check-bearer=1 \
+        --bearer-provisioning=1 \
+        --unique-uid=1 \
+        --mapping-uid="sub" \
+        --mapping-display-name="name" \
+        --mapping-email="email" \
+        --scope="openid profile email offline_access"
+
+    echo "✓ Created Keycloak provider"
+fi
+
+# Display provider details
+echo ""
+echo "Keycloak provider configuration:"
+php /var/www/html/occ user_oidc:provider keycloak
+
+echo ""
+echo "===================================================================="
+echo "✓ Keycloak provider configured successfully"
+echo "===================================================================="
+echo ""
+echo "Key features enabled:"
+echo "  • Bearer token validation (--check-bearer=1)"
+echo "  • Automatic user provisioning (--bearer-provisioning=1)"
+echo "  • Unique user IDs (--unique-uid=1)"
+echo "  • Offline access scope (for refresh tokens)"
+echo ""
+echo "MCP server can now use Keycloak tokens to access Nextcloud APIs"
+echo "without admin credentials (ADR-002 architecture)."
+echo ""

app-hooks/post-installation/20-apply-cors-bearer-token-patch.sh

@@ -0,0 +1,64 @@
+#!/bin/bash
+#
+# Apply upstream CORSMiddleware Bearer token authentication patch
+#
+# This patch allows Bearer tokens to bypass CORS/CSRF checks, fixing
+# authentication issues with app-specific APIs (Notes, Calendar, etc.)
+# when using OAuth/OIDC Bearer tokens.
+#
+# Upstream PR: https://github.com/nextcloud/server/pull/55878
+# Commit: 8fb5e77db82 (fix(cors): Allow Bearer token authentication)
+#
+
+set -e
+
+PATCH_FILE="/docker-entrypoint-hooks.d/patches/cors-bearer-token.patch"
+TARGET_FILE="/var/www/html/lib/private/AppFramework/Middleware/Security/CORSMiddleware.php"
+
+echo "===================================================================="
+echo "Applying CORSMiddleware Bearer token authentication patch..."
+echo "===================================================================="
+
+# Check if patch file exists
+if [ ! -f "$PATCH_FILE" ]; then
+    echo "⚠ Warning: Patch file not found: $PATCH_FILE"
+    echo "  Skipping CORS Bearer token patch"
+    exit 0
+fi
+
+# Check if target file exists
+if [ ! -f "$TARGET_FILE" ]; then
+    echo "⚠ Warning: Target file not found: $TARGET_FILE"
+    echo "  Skipping CORS Bearer token patch"
+    exit 0
+fi
+
+# Check if already patched
+if grep -q "Allow Bearer token authentication for CORS requests" "$TARGET_FILE"; then
+    echo "✓ CORSMiddleware already patched for Bearer token support"
+    exit 0
+fi
+
+echo "Applying patch to CORSMiddleware.php..."
+
+# Apply the patch
+cd /var/www/html
+if patch -p1 --dry-run < "$PATCH_FILE" > /dev/null 2>&1; then
+    patch -p1 < "$PATCH_FILE"
+    echo "✓ Patch applied successfully"
+else
+    echo "⚠ Warning: Patch failed to apply (may already be applied or file changed)"
+    echo "  This is expected if using a Nextcloud version that already includes the fix"
+    exit 0
+fi
+
+echo ""
+echo "===================================================================="
+echo "✓ CORSMiddleware Bearer token patch applied"
+echo "===================================================================="
+echo ""
+echo "Benefits:"
+echo "  • Bearer tokens now work with app-specific APIs (Notes, Calendar, etc.)"
+echo "  • OAuth/OIDC authentication works without CORS errors"
+echo "  • Stateless API authentication is properly supported"
+echo ""

app-hooks/post-installation/20-install-astrolabe-app.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+
+set -euox pipefail
+
+echo "Installing Astrolabe app..."
+
+# Check if development astrolabe app is mounted at /opt/apps/astrolabe
+if [ -d /opt/apps/astrolabe ]; then
+    echo "Development astrolabe app found at /opt/apps/astrolabe"
+
+    # Remove any existing astrolabe app in custom_apps (from app store or old symlink)
+    if [ -e /var/www/html/custom_apps/astrolabe ]; then
+        echo "Removing existing astrolabe in custom_apps..."
+        rm -rf /var/www/html/custom_apps/astrolabe
+    fi
+
+    # Create symlink from custom_apps to the mounted development version
+    # Per Nextcloud docs: apps outside server root need symlinks in server root
+    echo "Creating symlink: custom_apps/astrolabe -> /opt/apps/astrolabe"
+    ln -sf /opt/apps/astrolabe /var/www/html/custom_apps/astrolabe
+
+    echo "Enabling astrolabe app from /opt/apps (development mode via symlink)"
+    php /var/www/html/occ app:enable astrolabe
+elif [ -d /var/www/html/custom_apps/astrolabe ]; then
+    echo "astrolabe app directory found in custom_apps (already installed)"
+    php /var/www/html/occ app:enable astrolabe
+else
+    echo "astrolabe app not found, installing from app store..."
+    php /var/www/html/occ app:install astrolabe
+    php /var/www/html/occ app:enable astrolabe
+fi
+
+echo "Astrolabe app installed successfully"
+echo ""
+echo "Note: MCP server configuration is managed dynamically during tests"
+echo "      to support testing multiple MCP server deployments."

app-hooks/post-installation/25-configure-mcp-server-url.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+# Configure MCP server URL for Astrolabe background sync
+# This URL is used by Astrolabe to send app passwords to the MCP server
+
+set -e
+
+if [ -z "${MCP_SERVER_URL:-}" ]; then
+  echo "MCP_SERVER_URL not set, skipping Astrolabe MCP server URL configuration"
+  exit 0
+fi
+
+echo "Configuring MCP server URL: $MCP_SERVER_URL"
+
+# Set the mcp_server_url in config.php via occ
+php occ config:system:set mcp_server_url --value="$MCP_SERVER_URL"
+
+echo "MCP server URL configured successfully"

app-hooks/post-installation/30-disable-welcome-wizard.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+php /var/www/html/occ config:app:set --value false firstrunwizard wizard_enabled

app-hooks/post-installation/install-notes-app.sh

@@ -1,5 +0,0 @@
-#!/bin/bash
-
-set -euox pipefail
-
-php /var/www/html/occ app:enable notes

app-hooks/post-installation/install-oidc-app.sh

@@ -1,22 +0,0 @@
-#!/bin/bash
-
-set -euox pipefail
-
-echo "Installing and configuring OIDC apps for testing..."
-
-# Enable the OIDC Identity Provider app
-php /var/www/html/occ app:enable oidc
-
-# Enable the user_oidc app (OIDC client for bearer token validation)
-php /var/www/html/occ app:enable user_oidc
-
-patch -u /var/www/html/custom_apps/user_oidc/lib/User/Backend.php -i /docker-entrypoint-hooks.d/post-installation/0001-Fix-Bearer-token-authentication-causing-session-logo.patch
-
-# Configure OIDC Identity Provider with dynamic client registration enabled
-php /var/www/html/occ config:app:set oidc dynamic_client_registration --value='true'
-php /var/www/html/occ config:app:set oidc proof_key_for_code_exchange --value=true --type=boolean
-
-# Configure user_oidc to validate bearer tokens from the OIDC Identity Provider
-php /var/www/html/occ config:system:set user_oidc oidc_provider_bearer_validation --value=true --type=boolean
-
-echo "OIDC apps installed and configured successfully"

astrolabe.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512" viewBox="0 0 512 512">
+  <rect width="512" height="512" rx="80" ry="80" fill="#0082C9"/>
+  <path d="M255.9 21.04c-11.8 0-22.2 4.08-28.6 10.01-5.6 4.98-8.6 11.41-8.6 18.11 0 5.55 2.2 11.01 5.9 15.48-16.4 4.97-30.1 13.64-39 24.53 22.1-7.67 45.7-11.86 70.3-11.86 24.6 0 48.3 4.19 70.3 11.86-8.9-10.89-22.6-19.56-39-24.53 3.9-4.47 5.9-9.93 5.9-15.48 0-6.7-3-13.13-8.5-18.11-6.4-5.93-16.9-10.01-28.7-10.01zm0 20.34c5.3 0 10.1 1.27 13.6 3.52 1.7 1.16 3.4 2.43 3.4 4.27 0 1.76-1.7 3.03-3.4 4.19-3.5 2.33-8.3 3.61-13.6 3.61-5.3 0-10.1-1.28-13.6-3.61-1.6-1.16-3.3-2.43-3.3-4.19 0-1.84 1.7-3.11 3.3-4.27 3.5-2.25 8.3-3.52 13.6-3.52zm.1 48.1c-110.8 0-200.72 90.02-200.72 200.82S145.2 491 256 491s200.7-89.9 200.7-200.7c0-110.8-89.9-200.82-200.7-200.82zm0 32.62c92.9 0 168.2 75.3 168.2 168.2 0 92.8-75.3 168.2-168.2 168.2-92.9 0-168.26-75.4-168.26-168.2 0-92.9 75.36-168.2 168.26-168.2zm-8.2 6.3c-9.6.5-19 1.9-28.3 4.1l2.3 7.8c8.4-2 17.1-3.3 26-3.8v-8.1zm16.2 0v8.1c9 .5 17.7 1.8 26 3.8l2.2-7.8c-9.1-2.2-18.6-3.6-28.2-4.1zm-60 8.5c-9 3.2-17.6 7-25.8 11.6l4.1 7.1c7.7-4.3 15.6-7.9 23.9-10.8l-2.2-7.9zm103.7 0-2 7.9c8.4 2.9 16.2 6.5 23.8 10.8l4.2-7.1c-8.2-4.6-16.9-8.4-26-11.6zm-143.3 20.3c-7.5 5.4-14.6 11.4-21.1 17.9l5.8 5.8c5.9-6.1 12.5-11.7 19.5-16.6l-4.2-7.1zm182.9 0-4 7.1c6.9 4.9 13.5 10.5 19.5 16.6l5.7-5.8c-6.5-6.5-13.7-12.5-21.2-17.9zm-91.4 11.5c-37 0-67.4 28.6-70.3 64.9l15.9 4.7c.7-29.6 24.7-53.4 54.4-53.4 30.1 0 54.4 24.4 54.4 54.3 0 15-6.2 28.7-16 38.5l.1.1c1.7 2.7 3 5.6 4.1 8.6.9 3 1.7 5.7 2.3 8.6v.4c33.8-16.7 57.2-51.5 57.2-91.7 0-3.8-.2-7.3-.6-10.9-3.2-3.3-6.3-6.4-9.8-9.5 1.5 6.5 2.3 13.4 2.3 20.4 0 28.7-13 54.7-33.5 71.8 6.3-10.6 10.1-23 10.1-36.3 0-38.9-31.7-70.5-70.6-70.5zm-91.8 14.6c-3.3 3.1-6.5 6.2-9.7 9.5-.3 3.6-.5 7.1-.5 10.9 0 7.3.7 14.2 2.1 20.9l9.1 2.7c-2.1-7.5-3.1-15.4-3.1-23.6 0-7 .7-13.9 2.1-20.4zm-31.6 4c-5.8 7.1-10.9 14.6-15.4 22.6l7.1 4c4.1-7.4 8.8-14.3 14-20.8l-5.7-5.8zm246.8 0-5.7 5.8c5.3 6.5 10 13.4 13.9 20.8l7.1-4c-4.4-8-9.5-15.5-15.3-22.6zm-269.2 37.1c-2.5 5.7-4.6 11.4-6.4 17.6l.1-.3c3.4-5 7.9-9.3 12.9-12.5l.3-.6-6.9-4.2zm291.8 0-7.2 4.2c3.2 7.3 5.7 15.1 7.6 23.1l7.9-2.1c-2.1-8.8-4.9-17.3-8.3-25.2zm-261.2 11.5c-13.4.1-25.7 9-29.7 22.5l114.8 34.2c-4.9 16.7 4.6 34.2 21.2 39.2L361.7 366c16.6 5 34.1-4.4 39.1-21l-114.6-34.4c4.9-16.5-4.7-34.1-21.3-39.1 0 0-72.4-21.5-114.8-34.3-3.1-.9-6.3-1.4-9.4-1.3zm-42.09 29.7c-.9 6.9-1.4 14-1.4 21.3 0 1.3.1 2.9.1 4.2h8.09v-4.2c0-6.5.4-12.9 1.2-19.2l-7.99-2.1zm314.59 0-7.9 2.1c.7 6.3 1.3 12.7 1.3 19.2 0 1.3 0 2.9-.2 4.2h8.2v-4.2c0-7.3-.5-14.4-1.4-21.3zm-157.3 24.7c6.3 0 11.5 5 11.5 11.3 0 6.4-5.2 11.6-11.5 11.6s-11.5-5.2-11.5-11.6c0-6.3 5.2-11.3 11.5-11.3zM98.51 307.4c1 8.2 2.89 16.4 5.09 24.3l7.9-2.1c-2.1-7.2-3.8-14.6-4.8-22.2h-8.19zm306.69 0c-1.1 7.6-2.7 15-4.8 22.2l7.8 2.1c2.2-7.9 4.1-16.1 5.2-24.3h-8.2zm-191.3 10.9c-19 13.3-31.4 35.3-31.4 60.1 0 10.4 2.3 20.4 6.2 29.7 8.8 4.9 17.9 8.8 27.6 11.7-10.8-10.7-17.5-25.2-17.5-41.4 0-19 9.3-36 23.7-46.3-3.8-4.1-6.7-8.7-8.6-13.8zM116.8 345l-7.9 2c3.1 7.6 6.8 14.7 11 21.6l6.9-4.2c-3.8-6.2-7-12.8-10-19.4zm194.8 20.5c.9 4.1 1.4 8.5 1.4 12.9 0 16.2-6.7 30.7-17.4 41.4 9.6-2.9 18.8-6.8 27.5-11.7 4-9.3 6.2-19.3 6.2-29.7 0-2.7-.2-5.2-.4-7.7l-17.3-5.2zM136 377.9l-7.1 4.1c4.7 6.2 9.7 12.1 15.3 17.3l5.7-5.5c-5.1-5-9.7-10.3-13.9-15.9zm243.9 2.3-.2.1c-2.1.3-4 .6-6.2.7h-.1c-3.6 4.5-7.3 8.8-11.5 12.8l5.8 5.5c5.5-5.2 10.5-11.1 15.2-17.3l-3-1.8zm-217.8 24-5.9 5.9c6 4.8 12.2 9.7 18.8 13.6l3.8-7.8c-5.7-2.9-11.4-6.8-16.7-11.7zm187.7 0c-5.4 4.9-11.1 8.8-16.8 11.7l3.9 7.8c6.5-3.9 12.8-8.8 18.7-13.6l-5.8-5.9zm-156.4 19.5-4.1 6.8c6.6 4 13.7 5.8 20.7 8.8l2.2-7.9c-6.5-1.9-12.7-4.8-18.8-7.7zm125.2 0c-6.2 2.9-12.5 5.8-19.1 7.7l2.3 7.9c7.2-3 14-4.8 20.7-8.8l-3.9-6.8zm-90.7 11.7-2 7.8c7.1 1 14.5 1.9 21.9 1.9v-7.7c-6.8 0-13.5-1.1-19.9-2zm55.9 0c-6.3.9-13 2-19.8 2v7.7c7.5 0 14.8-.9 22.1-1.9l-2.3-7.8z" fill="#fff"/>
+</svg>

charts/nextcloud-mcp-server/.cz.toml

@@ -0,0 +1,25 @@
+[tool.commitizen]
+name = "cz_conventional_commits"
+version = "0.58.1"
+tag_format = "nextcloud-mcp-server-$version"
+version_scheme = "semver"
+update_changelog_on_bump = true
+major_version_zero = true
+
+# Update chart version only (NOT appVersion)
+version_files = [
+    "Chart.yaml:^version:"
+]
+
+# Ignore tags from other components
+ignored_tag_formats = [
+    "v*",              # MCP server tags
+    "astrolabe-v*",    # Astrolabe tags
+]
+
+# Filter commits by scope
+# Includes helm-scoped commits AND MCP server version bumps (which update appVersion)
+[tool.commitizen.customize]
+changelog_pattern = "^((feat|fix|docs|refactor|perf|test|build|ci|chore)\\(helm\\)(!)?:|bump: version.*→.*)"
+schema_pattern = "^(feat|fix|docs|refactor|perf|test|build|ci|chore)\\(helm\\)(!)?:\\s.+"
+message_template = "{{change_type}}(helm): {{message}}"

charts/nextcloud-mcp-server/.gitignore

@@ -0,0 +1 @@
+charts/

charts/nextcloud-mcp-server/.helmignore

@@ -0,0 +1,23 @@
+# Patterns to ignore when building packages.
+# This supports shell glob matching, relative path matching, and
+# negation (prefixed with !). Only one pattern per line.
+.DS_Store
+# Common VCS dirs
+.git/
+.gitignore
+.bzr/
+.bzrignore
+.hg/
+.hgignore
+.svn/
+# Common backup files
+*.swp
+*.bak
+*.tmp
+*.orig
+*~
+# Various IDEs
+.project
+.idea/
+*.tmproj
+.vscode/

charts/nextcloud-mcp-server/Chart.lock

@@ -0,0 +1,9 @@
+dependencies:
+- name: qdrant
+  repository: https://qdrant.github.io/qdrant-helm
+  version: 1.17.0
+- name: ollama
+  repository: https://otwld.github.io/ollama-helm
+  version: 1.47.0
+digest: sha256:08d589dd1b3386e8e8a2ac2c03a2194218ab12ed9e02016e7b981e554385dd11
+generated: "2026-03-02T11:15:27.688786078Z"

charts/nextcloud-mcp-server/Chart.yaml

@@ -0,0 +1,45 @@
+apiVersion: v2
+name: nextcloud-mcp-server
+description: A Helm chart for Nextcloud MCP Server - enables AI assistants to interact with Nextcloud
+type: application
+version: 0.58.1
+appVersion: "0.65.0"
+keywords:
+  - nextcloud
+  - mcp
+  - model-context-protocol
+  - llm
+  - ai
+  - claude
+  - webdav
+  - caldav
+  - carddav
+maintainers:
+  - name: Chris Coutinho
+    email: chris@coutinho.io
+home: https://github.com/cbcoutinho/nextcloud-mcp-server
+sources:
+  - https://github.com/cbcoutinho/nextcloud-mcp-server
+icon: https://raw.githubusercontent.com/nextcloud/server/master/core/img/logo/logo.svg
+annotations:
+  # Grafana dashboard support
+  grafana_dashboard: "true"
+  grafana_dashboard_folder: "Nextcloud MCP"
+  artifacthub.io/changes: |
+    - kind: added
+      description: Login Flow v2 auth mode for Helm chart (ADR-022)
+    - kind: added
+      description: Multi-user BasicAuth guidance in post-install NOTES
+    - kind: added
+      description: Version and changelog info in post-install NOTES
+    - kind: changed
+      description: Updated appVersion to 0.64.4
+dependencies:
+  - name: qdrant
+    version: "1.17.0"
+    repository: https://qdrant.github.io/qdrant-helm
+    condition: qdrant.networkMode.deploySubchart
+  - name: ollama
+    version: "1.47.0"
+    repository: https://otwld.github.io/ollama-helm
+    condition: ollama.enabled

charts/nextcloud-mcp-server/README.md

@@ -0,0 +1,742 @@
+# Nextcloud MCP Server Helm Chart
+
+This Helm chart deploys the Nextcloud MCP (Model Context Protocol) Server on a Kubernetes cluster, enabling AI assistants to interact with your Nextcloud instance.
+
+## Prerequisites
+
+- Kubernetes 1.19+
+- Helm 3.0+
+- A running Nextcloud instance (accessible from the Kubernetes cluster)
+- Nextcloud credentials (username/password for basic auth OR OAuth client for OAuth mode)
+
+## Installation
+
+### Quick Start with Basic Authentication
+
+```bash
+# Add the Helm repository
+helm repo add nextcloud-mcp https://cbcoutinho.github.io/nextcloud-mcp-server
+helm repo update
+
+# Install with basic auth (recommended for most users)
+helm install nextcloud-mcp nextcloud-mcp/nextcloud-mcp-server \
+  --set nextcloud.host=https://cloud.example.com \
+  --set auth.basic.username=myuser \
+  --set auth.basic.password=mypassword
+```
+
+### Using a values file
+
+Create a `custom-values.yaml` file:
+
+```yaml
+nextcloud:
+  host: https://cloud.example.com
+
+auth:
+  mode: basic
+  basic:
+    username: myuser
+    password: mypassword
+
+resources:
+  limits:
+    cpu: 1000m
+    memory: 512Mi
+  requests:
+    cpu: 100m
+    memory: 128Mi
+```
+
+Install with your custom values:
+
+```bash
+helm install nextcloud-mcp nextcloud-mcp/nextcloud-mcp-server -f custom-values.yaml
+```
+
+### OAuth Authentication Mode (Experimental)
+
+**Warning:** OAuth mode is experimental and requires patches to the Nextcloud `user_oidc` app. See the [Authentication Guide](https://github.com/cbcoutinho/nextcloud-mcp-server#authentication) for details.
+
+```yaml
+nextcloud:
+  host: https://cloud.example.com
+  mcpServerUrl: https://mcp.example.com
+  publicIssuerUrl: https://cloud.example.com
+
+auth:
+  mode: oauth
+  oauth:
+    # Optional: provide pre-registered client credentials
+    # If not provided, will use Dynamic Client Registration
+    clientId: "your-client-id"
+    clientSecret: "your-client-secret"
+    persistence:
+      enabled: true
+      size: 100Mi
+
+ingress:
+  enabled: true
+  className: nginx
+  hosts:
+    - host: mcp.example.com
+      paths:
+        - path: /
+          pathType: Prefix
+  tls:
+    - secretName: nextcloud-mcp-tls
+      hosts:
+        - mcp.example.com
+```
+
+## Configuration
+
+### Key Configuration Parameters
+
+#### Nextcloud Connection
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `nextcloud.host` | URL of your Nextcloud instance (required) | `""` |
+| `nextcloud.mcpServerUrl` | MCP server URL for OAuth callbacks (OAuth only, optional) | Smart default* |
+| `nextcloud.publicIssuerUrl` | Public URL for browser-accessible OAuth authorization endpoint (OAuth only, optional) | Smart default** |
+
+**Smart Defaults:**
+- `*mcpServerUrl`: If not set, automatically uses ingress host (if enabled) or `http://localhost:8000` (for port-forward setups)
+- `**publicIssuerUrl`: If not set, defaults to `nextcloud.host`. **Only used for authorization endpoints** that browsers must access. All server-to-server endpoints (token, JWKS, introspection, userinfo) use URLs from OIDC discovery without rewriting
+
+#### Authentication
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `auth.mode` | Authentication mode: `basic` or `oauth` | `basic` |
+| `auth.basic.username` | Nextcloud username (basic auth) | `""` |
+| `auth.basic.password` | Nextcloud password (basic auth) | `""` |
+| `auth.basic.existingSecret` | Use existing secret for credentials | `""` |
+| `auth.oauth.clientId` | OAuth client ID (OAuth mode, optional) | `""` |
+| `auth.oauth.clientSecret` | OAuth client secret (OAuth mode, optional) | `""` |
+| `auth.oauth.persistence.enabled` | Enable persistent storage for OAuth | `true` |
+| `auth.oauth.persistence.size` | Size of OAuth storage PVC | `100Mi` |
+
+#### Data Storage
+
+The `/app/data` directory is used for application data (token databases, Qdrant persistent storage, etc.). It is always mounted as writable to support the read-only root filesystem security context.
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `dataStorage.enabled` | Enable persistent storage for `/app/data` | `false` |
+| `dataStorage.size` | Size of data storage PVC | `1Gi` |
+| `dataStorage.storageClass` | Storage class (leave empty for default) | `""` |
+| `dataStorage.accessMode` | Access mode | `ReadWriteOnce` |
+| `dataStorage.existingClaim` | Use existing PVC | `""` |
+
+**When to enable persistence:**
+- Multi-user basic auth with offline access (stores `tokens.db`)
+- Qdrant persistent mode (stores vector database)
+- Any feature requiring persistent app data
+
+**When persistence is disabled:** Uses `emptyDir` (non-persistent, data lost on pod restart, but directory remains writable).
+
+#### MCP Server Configuration
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `mcp.transport` | Transport mode | `streamable-http` |
+| `mcp.port` | Server port (used by both auth modes) | `8000` |
+| `mcp.extraArgs` | Additional command-line arguments | `[]` |
+
+The `extraArgs` parameter allows you to pass additional command-line arguments to the MCP server. This is useful for enabling debug logging, enabling specific apps, or other runtime configuration.
+
+**Example:**
+```yaml
+mcp:
+  extraArgs:
+    - "--log-level"
+    - "debug"
+    - "--enable-app"
+    - "notes"
+```
+
+#### Image Configuration
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `image.repository` | Container image repository | `ghcr.io/cbcoutinho/nextcloud-mcp-server` |
+| `image.pullPolicy` | Image pull policy | `IfNotPresent` |
+
+**Note:** Image tag is automatically set to the chart's `appVersion` and cannot be overridden.
+
+#### Resources
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `resources.limits.cpu` | CPU limit | `1000m` |
+| `resources.limits.memory` | Memory limit | `512Mi` |
+| `resources.requests.cpu` | CPU request | `100m` |
+| `resources.requests.memory` | Memory request | `128Mi` |
+
+#### Service
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `service.type` | Service type | `ClusterIP` |
+| `service.port` | Service port | `8000` |
+
+#### Ingress
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `ingress.enabled` | Enable ingress | `false` |
+| `ingress.className` | Ingress class name | `""` |
+| `ingress.hosts` | Ingress host configuration | See values.yaml |
+| `ingress.tls` | Ingress TLS configuration | `[]` |
+
+#### Autoscaling
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `autoscaling.enabled` | Enable HPA | `false` |
+| `autoscaling.minReplicas` | Minimum replicas | `1` |
+| `autoscaling.maxReplicas` | Maximum replicas | `10` |
+| `autoscaling.targetCPUUtilizationPercentage` | Target CPU % | `80` |
+
+#### Health Probes
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `livenessProbe.httpGet.path` | Liveness probe endpoint | `/health/live` |
+| `livenessProbe.initialDelaySeconds` | Initial delay for liveness | `30` |
+| `livenessProbe.periodSeconds` | Check interval for liveness | `10` |
+| `readinessProbe.httpGet.path` | Readiness probe endpoint | `/health/ready` |
+| `readinessProbe.initialDelaySeconds` | Initial delay for readiness | `10` |
+| `readinessProbe.periodSeconds` | Check interval for readiness | `5` |
+
+The application exposes HTTP health check endpoints:
+- `/health/live` - Liveness probe (checks if application is running)
+- `/health/ready` - Readiness probe (checks if application is ready to serve traffic)
+
+#### Document Processing (Optional)
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `documentProcessing.enabled` | Enable document processing | `false` |
+| `documentProcessing.defaultProcessor` | Default processor | `unstructured` |
+| `documentProcessing.unstructured.enabled` | Enable Unstructured.io processor | `false` |
+| `documentProcessing.unstructured.apiUrl` | Unstructured API URL | `http://unstructured:8000` |
+| `documentProcessing.tesseract.enabled` | Enable Tesseract OCR | `false` |
+
+#### Vector Search & Semantic Capabilities (Optional)
+
+Enable semantic search capabilities with BM25 hybrid search by deploying a vector database (Qdrant) and embedding service (Ollama or OpenAI).
+
+**Semantic Search Configuration:**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `semanticSearch.enabled` | Enable semantic search and background vector synchronization | `false` |
+| `semanticSearch.scanInterval` | Scan interval in seconds | `3600` |
+| `semanticSearch.processorWorkers` | Number of concurrent processor workers | `3` |
+| `semanticSearch.queueMaxSize` | Maximum queue size for pending documents | `10000` |
+
+**Document Chunking Configuration:**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `documentChunking.chunkSize` | Number of words per chunk for embedding | `512` |
+| `documentChunking.chunkOverlap` | Number of overlapping words between chunks | `50` |
+
+**Chunking Strategy:**
+- **Small chunks (256-384)**: Better precision for searches, more storage overhead
+- **Medium chunks (512-768)**: Balanced approach (recommended for most use cases)
+- **Large chunks (1024+)**: Better context preservation, less precise matching
+- **Overlap**: Should be 10-20% of chunk size to preserve context across boundaries
+
+**Qdrant Vector Database:**
+
+Qdrant is deployed as a subchart when `qdrant.enabled` is `true`. All configuration values are passed through to the [qdrant/qdrant](https://github.com/qdrant/qdrant-helm) chart.
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `qdrant.enabled` | Deploy Qdrant as a subchart | `false` |
+| `qdrant.replicaCount` | Number of Qdrant replicas | `1` |
+| `qdrant.image.tag` | Qdrant version | `v1.12.5` |
+| `qdrant.apiKey` | Optional API key for authentication | `""` |
+| `qdrant.persistence.size` | Storage size for vector data | `10Gi` |
+| `qdrant.persistence.storageClass` | Storage class | `""` |
+| `qdrant.resources.requests.cpu` | CPU request | `200m` |
+| `qdrant.resources.requests.memory` | Memory request | `512Mi` |
+| `qdrant.resources.limits.cpu` | CPU limit | `1000m` |
+| `qdrant.resources.limits.memory` | Memory limit | `2Gi` |
+
+**Ollama Embedding Service:**
+
+Ollama is deployed as a subchart when `ollama.enabled` is `true`. All configuration values are passed through to the [ollama/ollama](https://github.com/otwld/ollama-helm) chart. Alternatively, set `ollama.url` to use an external Ollama instance.
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `ollama.enabled` | Deploy Ollama as a subchart | `false` |
+| `ollama.url` | External Ollama URL (use with `enabled: false`) | `""` |
+| `ollama.embeddingModel` | Embedding model to use | `nomic-embed-text` |
+| `ollama.verifySsl` | Verify SSL certificates | `true` |
+| `ollama.replicaCount` | Number of Ollama replicas | `1` |
+| `ollama.ollama.models.pull` | Models to pull on startup | `["nomic-embed-text"]` |
+| `ollama.persistentVolume.enabled` | Enable persistent storage | `true` |
+| `ollama.persistentVolume.size` | Storage size for models | `20Gi` |
+| `ollama.resources.requests.cpu` | CPU request | `500m` |
+| `ollama.resources.requests.memory` | Memory request | `1Gi` |
+| `ollama.resources.limits.cpu` | CPU limit | `2000m` |
+| `ollama.resources.limits.memory` | Memory limit | `4Gi` |
+
+**OpenAI Embedding Provider (Alternative):**
+
+Use OpenAI or any OpenAI-compatible API instead of Ollama.
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `openai.enabled` | Enable OpenAI embedding provider | `false` |
+| `openai.apiKey` | OpenAI API key | `""` |
+| `openai.existingSecret` | Use existing secret for API key | `""` |
+| `openai.secretKey` | Key in secret containing API key | `api-key` |
+| `openai.baseUrl` | Custom API endpoint (optional) | `""` |
+
+#### Observability & Monitoring
+
+The chart includes comprehensive observability features including Prometheus metrics, OpenTelemetry tracing, and Grafana dashboards.
+
+**Metrics Configuration:**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `observability.metrics.enabled` | Enable Prometheus metrics | `true` |
+| `observability.metrics.port` | Metrics port | `9090` |
+| `observability.metrics.path` | Metrics endpoint path | `/metrics` |
+
+**Tracing Configuration:**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `observability.tracing.enabled` | Enable OpenTelemetry tracing | `false` |
+| `observability.tracing.endpoint` | OTLP collector endpoint | `""` |
+| `observability.tracing.serviceName` | Service name in traces | `nextcloud-mcp-server` |
+| `observability.tracing.samplingRate` | Trace sampling rate (0.0-1.0) | `1.0` |
+
+**Logging Configuration:**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `observability.logging.format` | Log format (json or text) | `json` |
+| `observability.logging.level` | Log level | `INFO` |
+| `observability.logging.includeTraceContext` | Include trace IDs in logs | `true` |
+
+**ServiceMonitor (Prometheus Operator):**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `serviceMonitor.enabled` | Create ServiceMonitor resource | `false` |
+| `serviceMonitor.interval` | Scrape interval | `30s` |
+| `serviceMonitor.scrapeTimeout` | Scrape timeout | `10s` |
+| `serviceMonitor.labels` | Additional labels for ServiceMonitor | `{}` |
+
+**PrometheusRule (Prometheus Operator):**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `prometheusRule.enabled` | Create PrometheusRule with alert rules | `false` |
+| `prometheusRule.labels` | Additional labels for PrometheusRule | `{}` |
+
+**Grafana Dashboards:**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `dashboards.enabled` | Enable automatic dashboard provisioning | `false` |
+| `dashboards.grafanaFolder` | Grafana folder name for dashboards | `Nextcloud MCP` |
+| `dashboards.labels` | Additional labels for dashboard ConfigMap | `{}` |
+| `dashboards.annotations` | Additional annotations for dashboard ConfigMap | `{}` |
+
+When `dashboards.enabled` is `true`, a ConfigMap with the Grafana dashboard is created with the `grafana_dashboard: "1"` label. This enables automatic discovery by Grafana sidecar containers (commonly used with kube-prometheus-stack).
+
+The dashboard provides comprehensive monitoring including:
+- HTTP request metrics (RED pattern: Rate, Errors, Duration)
+- MCP tool performance and errors
+- Nextcloud API performance by app (notes, calendar, contacts, etc.)
+- OAuth token operations and cache hit rates
+- External dependency health (Nextcloud, Qdrant, Keycloak, Unstructured API)
+- Vector sync processing pipeline (when enabled)
+
+For manual import or more details, see `charts/nextcloud-mcp-server/dashboards/README.md`.
+
+## Examples
+
+### Example 1: Basic Auth with Ingress
+
+```yaml
+nextcloud:
+  host: https://cloud.example.com
+
+auth:
+  mode: basic
+  basic:
+    username: admin
+    password: secure-password
+
+ingress:
+  enabled: true
+  className: nginx
+  annotations:
+    cert-manager.io/cluster-issuer: letsencrypt-prod
+  hosts:
+    - host: mcp.example.com
+      paths:
+        - path: /
+          pathType: Prefix
+  tls:
+    - secretName: mcp-tls
+      hosts:
+        - mcp.example.com
+
+resources:
+  limits:
+    cpu: 2000m
+    memory: 1Gi
+  requests:
+    cpu: 200m
+    memory: 256Mi
+```
+
+### Example 2: Using Existing Secrets
+
+#### Basic Auth with Existing Secret
+
+Create a secret manually:
+
+```bash
+kubectl create secret generic nextcloud-credentials \
+  --from-literal=username=myuser \
+  --from-literal=password=mypassword
+```
+
+Then reference it in your values:
+
+```yaml
+nextcloud:
+  host: https://cloud.example.com
+
+auth:
+  mode: basic
+  basic:
+    existingSecret: nextcloud-credentials
+    usernameKey: username
+    passwordKey: password
+```
+
+#### OAuth with Existing Secret (Pre-registered Client)
+
+If you have a pre-registered OAuth client:
+
+```bash
+kubectl create secret generic nextcloud-oauth-creds \
+  --from-literal=clientId=my-oauth-client-id \
+  --from-literal=clientSecret=my-oauth-client-secret
+```
+
+Then reference it in your values:
+
+```yaml
+nextcloud:
+  host: https://cloud.example.com
+  # mcpServerUrl and publicIssuerUrl are optional!
+  # If not set, mcpServerUrl defaults to ingress host or localhost
+  # publicIssuerUrl defaults to nextcloud.host (only used for browser-accessible auth endpoint)
+
+auth:
+  mode: oauth
+  oauth:
+    existingSecret: nextcloud-oauth-creds
+    clientIdKey: clientId
+    clientSecretKey: clientSecret
+    persistence:
+      enabled: true
+
+ingress:
+  enabled: true
+  hosts:
+    - host: mcp.example.com
+      paths:
+        - path: /
+          pathType: Prefix
+  tls:
+    - secretName: mcp-tls
+      hosts:
+        - mcp.example.com
+```
+
+### Example 3: OAuth with Document Processing and Dynamic Client Registration
+
+This example shows OAuth without pre-registered credentials (using DCR) and optional URL values:
+
+```yaml
+nextcloud:
+  host: https://cloud.example.com
+  # mcpServerUrl will automatically use ingress host (https://mcp.example.com)
+  # publicIssuerUrl will automatically default to nextcloud.host (only used for browser-accessible auth endpoint)
+
+auth:
+  mode: oauth
+  oauth:
+    # No clientId/clientSecret - will use Dynamic Client Registration!
+    persistence:
+      enabled: true
+      storageClass: fast-ssd
+      size: 200Mi
+
+documentProcessing:
+  enabled: true
+  defaultProcessor: unstructured
+  unstructured:
+    enabled: true
+    apiUrl: http://unstructured-api:8000
+    strategy: hi_res
+    languages: eng,deu,fra
+
+ingress:
+  enabled: true
+  className: nginx
+  hosts:
+    - host: mcp.example.com
+      paths:
+        - path: /
+          pathType: Prefix
+```
+
+### Example 4: High Availability with Autoscaling
+
+```yaml
+replicaCount: 2
+
+autoscaling:
+  enabled: true
+  minReplicas: 2
+  maxReplicas: 20
+  targetCPUUtilizationPercentage: 70
+  targetMemoryUtilizationPercentage: 80
+
+resources:
+  limits:
+    cpu: 2000m
+    memory: 1Gi
+  requests:
+    cpu: 500m
+    memory: 512Mi
+
+affinity:
+  podAntiAffinity:
+    preferredDuringSchedulingIgnoredDuringExecution:
+      - weight: 100
+        podAffinityTerm:
+          labelSelector:
+            matchExpressions:
+              - key: app.kubernetes.io/name
+                operator: In
+                values:
+                  - nextcloud-mcp-server
+          topologyKey: kubernetes.io/hostname
+```
+
+### Example 5: Semantic Search with Qdrant and Ollama
+
+Deploy with vector search capabilities using embedded Qdrant and Ollama:
+
+```yaml
+nextcloud:
+  host: https://cloud.example.com
+
+auth:
+  mode: basic
+  basic:
+    username: admin
+    password: secure-password
+
+# Enable semantic search
+semanticSearch:
+  enabled: true
+  scanInterval: 1800  # Scan every 30 minutes
+  processorWorkers: 5
+
+# Deploy Qdrant as a subchart
+qdrant:
+  enabled: true
+  persistence:
+    size: 20Gi
+    storageClass: fast-ssd
+  resources:
+    requests:
+      cpu: 500m
+      memory: 1Gi
+    limits:
+      cpu: 2000m
+      memory: 4Gi
+
+# Deploy Ollama as a subchart
+ollama:
+  enabled: true
+  embeddingModel: nomic-embed-text
+  persistentVolume:
+    size: 30Gi
+    storageClass: standard
+  resources:
+    requests:
+      cpu: 1000m
+      memory: 2Gi
+    limits:
+      cpu: 4000m
+      memory: 8Gi
+```
+
+Or use an external Ollama instance:
+
+```yaml
+semanticSearch:
+  enabled: true
+
+qdrant:
+  enabled: true
+
+# Use external Ollama instead of deploying subchart
+ollama:
+  enabled: false
+  url: "http://ollama.ai-services.svc.cluster.local:11434"
+  embeddingModel: nomic-embed-text
+```
+
+Or use OpenAI for embeddings:
+
+```yaml
+semanticSearch:
+  enabled: true
+
+qdrant:
+  enabled: true
+
+# Use OpenAI instead of Ollama
+openai:
+  enabled: true
+  apiKey: "sk-..."
+  # Or use existing secret:
+  # existingSecret: openai-api-key
+  # secretKey: api-key
+```
+
+## Upgrading
+
+### To upgrade an existing deployment:
+
+```bash
+# Update the repository
+helm repo update
+
+# Upgrade with your custom values
+helm upgrade nextcloud-mcp nextcloud-mcp/nextcloud-mcp-server -f custom-values.yaml
+```
+
+### To upgrade with new values:
+
+```bash
+helm upgrade nextcloud-mcp nextcloud-mcp/nextcloud-mcp-server \
+  --set resources.limits.memory=1Gi
+```
+
+## Uninstalling
+
+```bash
+helm uninstall nextcloud-mcp
+```
+
+**Note:** This will delete all resources including PVCs. If you want to preserve OAuth client data, backup the PVC before uninstalling.
+
+## Troubleshooting
+
+### Check pod status
+
+```bash
+kubectl get pods -l app.kubernetes.io/name=nextcloud-mcp-server
+```
+
+### View logs
+
+```bash
+kubectl logs -l app.kubernetes.io/name=nextcloud-mcp-server --tail=100 -f
+```
+
+### Check health endpoints
+
+The application exposes health check endpoints for monitoring:
+
+```bash
+# Port forward to the service
+kubectl port-forward svc/nextcloud-mcp 8000:8000
+
+# Check liveness (if app is running)
+curl http://localhost:8000/health/live
+
+# Check readiness (if app is ready to serve traffic)
+curl http://localhost:8000/health/ready
+```
+
+**Example responses:**
+
+Liveness (always returns 200 if running):
+```json
+{
+  "status": "alive",
+  "mode": "basic"
+}
+```
+
+Readiness (returns 200 if ready, 503 if not ready):
+```json
+{
+  "status": "ready",
+  "checks": {
+    "nextcloud_configured": "ok",
+    "auth_mode": "basic",
+    "auth_configured": "ok"
+  }
+}
+```
+
+### Common Issues
+
+1. **Connection refused to Nextcloud**
+   - Verify `nextcloud.host` is accessible from the Kubernetes cluster
+   - For OAuth mode: Ensure MCP server can reach OIDC discovery endpoints (token, JWKS, introspection, userinfo URLs)
+   - Check network policies and firewall rules
+   - Note: Do not use internal Docker hostnames (like `http://app:80`) for `nextcloud.host` - use externally resolvable URLs
+
+2. **Authentication failures**
+   - For basic auth: verify username/password are correct
+   - For OAuth: check that OIDC app is properly configured
+
+3. **OAuth persistence issues**
+   - Verify PVC is bound: `kubectl get pvc`
+   - Check storage class exists: `kubectl get storageclass`
+
+4. **Resource constraints**
+   - Increase memory limits if seeing OOM errors
+   - Adjust CPU requests based on load
+
+## Security Considerations
+
+1. **Secrets Management**: Consider using external secret management (e.g., Sealed Secrets, External Secrets Operator)
+2. **TLS**: Always use TLS/HTTPS for production deployments
+3. **Network Policies**: Restrict network access to necessary services only
+4. **RBAC**: Review and customize ServiceAccount permissions as needed
+5. **App Passwords**: For basic auth, use Nextcloud app passwords instead of main account passwords
+
+## Support
+
+- GitHub Issues: https://github.com/cbcoutinho/nextcloud-mcp-server/issues
+- Documentation: https://github.com/cbcoutinho/nextcloud-mcp-server#readme
+
+## License
+
+This chart is licensed under AGPL-3.0, consistent with the Nextcloud MCP Server project.

charts/nextcloud-mcp-server/dashboards/README.md

@@ -0,0 +1,161 @@
+# Grafana Dashboards
+
+This directory contains example Grafana dashboards for monitoring the Nextcloud MCP Server.
+
+## Dashboards
+
+### nextcloud-mcp-server.json
+
+All-in-one Operations Dashboard with comprehensive monitoring across all system components.
+
+#### Overview Row
+High-level metrics for quick health assessment:
+- **Request Rate** (stat): Total requests per second
+- **Error Rate** (stat): Percentage of 5xx errors with color thresholds
+- **P95 Latency** (stat): 95th percentile request latency
+- **Active Requests** (stat): Current in-flight requests
+
+#### HTTP Metrics (RED Pattern)
+Core request/error/duration metrics:
+- **Request Rate by Endpoint** (timeseries): RPS breakdown by endpoint
+- **Error Rate by Status Code** (timeseries): Error rates for 4xx/5xx codes
+- **Latency Percentiles** (timeseries): P50, P95, P99 latency trends
+- **Status Code Distribution** (piechart): Percentage breakdown of all status codes
+
+#### MCP Tools Row
+MCP-specific tool performance:
+- **Top Tools by Call Volume** (bargauge): Top 10 most-called tools
+- **Tool Error Rate** (timeseries): Error rates per tool
+- **Tool Execution Duration** (timeseries): P95 latency by tool
+
+#### Nextcloud API Row
+Backend API performance metrics:
+- **API Calls by App** (timeseries): Request rate per Nextcloud app (notes, calendar, contacts, etc.)
+- **API Latency by App** (timeseries): P95 latency per app
+- **API Retries by Reason** (timeseries): Retry patterns (429, timeout, connection errors)
+- **API Error Rate** (stat): Overall API error percentage
+
+#### OAuth & Authentication Row
+OAuth token operations and caching:
+- **Token Validations** (timeseries): Success/failure rates for token validation
+- **Token Exchange Operations** (timeseries): RFC 8693 token exchange operations
+- **Token Cache Hit Rate** (stat): Percentage of cache hits (color-coded: red<50%, yellow<80%, green≥80%)
+- **Refresh Token Operations** (timeseries): Refresh token storage operations by type
+
+#### Dependencies & Health Row
+External dependency status monitoring:
+- **Nextcloud Health** (stat): UP/DOWN status with color coding
+- **Qdrant Health** (stat): Vector database health status
+- **Keycloak Health** (stat): Identity provider health status
+- **Unstructured API Health** (stat): Document processing API status
+- **Health Check Duration** (timeseries): Health check latency by dependency
+- **Database Operation Latency** (timeseries): P95 latency for DB operations (SQLite, Qdrant)
+
+#### Vector Sync Row (when enabled)
+Document processing pipeline metrics:
+- **Documents Processed Rate** (timeseries): Processing throughput by status (success/failure)
+- **Processing Queue Depth** (gauge): Current queue size with thresholds (yellow>50, red>100)
+- **Qdrant Operations** (timeseries): Vector database operations by type
+- **Document Processing Duration** (timeseries): P95 processing latency
+
+## Importing to Grafana
+
+### Manual Import
+
+1. Open Grafana UI
+2. Navigate to Dashboards → Import
+3. Upload `nextcloud-mcp-server.json`
+4. Select your Prometheus data source
+5. Click "Import"
+
+### Automated Import (Helm Chart)
+
+The Helm chart now supports automatic dashboard provisioning via Grafana sidecar pattern.
+
+#### Option 1: Using Helm Chart (Recommended)
+
+Enable dashboard provisioning in your Helm values:
+
+```yaml
+# values.yaml for nextcloud-mcp-server chart
+dashboards:
+  enabled: true
+  grafanaFolder: "Nextcloud MCP"  # Folder name in Grafana
+  labels: {}  # Additional labels if needed
+```
+
+Then deploy or upgrade:
+
+```bash
+helm upgrade --install nextcloud-mcp nextcloud-mcp-server \
+  --set dashboards.enabled=true
+```
+
+The dashboard will be automatically imported by Grafana if the sidecar is configured
+to watch for ConfigMaps with label `grafana_dashboard: "1"`.
+
+#### Option 2: Using kube-prometheus-stack
+
+If using kube-prometheus-stack with Grafana sidecar enabled, the dashboard will be
+automatically discovered and imported. Ensure your Grafana deployment has:
+
+```yaml
+# kube-prometheus-stack values
+grafana:
+  sidecar:
+    dashboards:
+      enabled: true
+      label: grafana_dashboard
+      folder: /tmp/dashboards
+      provider:
+        foldersFromFilesStructure: true
+```
+
+#### Option 3: Manual ConfigMap Creation
+
+For other Grafana setups, create a ConfigMap manually:
+
+```bash
+kubectl create configmap nextcloud-mcp-dashboard \
+  --from-file=nextcloud-mcp-server.json \
+  -n monitoring
+
+# Add sidecar discovery label
+kubectl label configmap nextcloud-mcp-dashboard \
+  grafana_dashboard=1 \
+  -n monitoring
+
+# Add folder annotation (annotations support spaces, unlike labels)
+kubectl annotate configmap nextcloud-mcp-dashboard \
+  grafana_folder="Nextcloud MCP" \
+  -n monitoring
+```
+
+## Dashboard Variables
+
+The dashboard includes four template variables for dynamic filtering:
+
+- **datasource**: Select your Prometheus data source
+- **namespace**: Filter metrics by Kubernetes namespace (supports "All")
+- **pod**: Filter by specific pod(s) - multi-select enabled (supports "All")
+- **interval**: Query interval for rate calculations (1m, 5m, 10m, 30m, 1h - default: 5m)
+
+## Customization
+
+You can customize the dashboard by:
+
+1. Adjusting refresh rate (default: 30s)
+2. Modifying time range (default: last 6 hours)
+3. Adding new panels for specific metrics
+4. Adjusting thresholds in existing panels
+
+## Metrics Reference
+
+All metrics are documented in `/docs/observability.md`. Key metric prefixes:
+
+- `mcp_http_*` - HTTP server metrics
+- `mcp_tool_*` - MCP tool invocation metrics
+- `mcp_nextcloud_api_*` - Nextcloud API call metrics
+- `mcp_oauth_*` - OAuth token validation metrics
+- `mcp_vector_sync_*` - Vector database sync metrics
+- `mcp_db_*` - Database operation metrics

charts/nextcloud-mcp-server/templates/NOTES.txt

@@ -0,0 +1,208 @@
+Thank you for installing {{ .Chart.Name }}!
+
+Your Nextcloud MCP Server has been deployed in {{ .Values.auth.mode }} authentication mode.
+
+1. Get the application URL by running these commands:
+{{- if .Values.ingress.enabled }}
+{{- range $host := .Values.ingress.hosts }}
+  {{- range .paths }}
+  http{{ if $.Values.ingress.tls }}s{{ end }}://{{ $host.host }}{{ .path }}
+  {{- end }}
+{{- end }}
+{{- else if contains "NodePort" .Values.service.type }}
+  export NODE_PORT=$(kubectl get --namespace {{ .Release.Namespace }} -o jsonpath="{.spec.ports[0].nodePort}" services {{ include "nextcloud-mcp-server.fullname" . }})
+  export NODE_IP=$(kubectl get nodes --namespace {{ .Release.Namespace }} -o jsonpath="{.items[0].status.addresses[0].address}")
+  echo http://$NODE_IP:$NODE_PORT
+{{- else if contains "LoadBalancer" .Values.service.type }}
+     NOTE: It may take a few minutes for the LoadBalancer IP to be available.
+           You can watch the status of by running 'kubectl get --namespace {{ .Release.Namespace }} svc -w {{ include "nextcloud-mcp-server.fullname" . }}'
+  export SERVICE_IP=$(kubectl get svc --namespace {{ .Release.Namespace }} {{ include "nextcloud-mcp-server.fullname" . }} --template "{{"{{ range (index .status.loadBalancer.ingress 0) }}{{.}}{{ end }}"}}")
+  echo http://$SERVICE_IP:{{ .Values.service.port }}
+{{- else if contains "ClusterIP" .Values.service.type }}
+  export POD_NAME=$(kubectl get pods --namespace {{ .Release.Namespace }} -l "app.kubernetes.io/name={{ include "nextcloud-mcp-server.name" . }},app.kubernetes.io/instance={{ .Release.Name }}" -o jsonpath="{.items[0].metadata.name}")
+  export CONTAINER_PORT=$(kubectl get pod --namespace {{ .Release.Namespace }} $POD_NAME -o jsonpath="{.spec.containers[0].ports[0].containerPort}")
+  echo "Visit http://127.0.0.1:8080 to use your MCP server"
+  kubectl --namespace {{ .Release.Namespace }} port-forward $POD_NAME 8080:$CONTAINER_PORT
+{{- end }}
+
+2. Check the deployment status:
+  kubectl --namespace {{ .Release.Namespace }} get pods -l "app.kubernetes.io/name={{ include "nextcloud-mcp-server.name" . }},app.kubernetes.io/instance={{ .Release.Name }}"
+
+{{- if eq .Values.auth.mode "basic" }}
+
+3. Basic Authentication Mode:
+   {{- if .Values.auth.basic.existingSecret }}
+   - Credentials: (using existing secret {{ .Values.auth.basic.existingSecret }})
+   {{- else }}
+   - Username: {{ .Values.auth.basic.username }}
+   - Password: (stored in secret {{ include "nextcloud-mcp-server.basicAuthSecretName" . }})
+   {{- end }}
+   - Connected to: {{ .Values.nextcloud.host }}
+{{- else if eq .Values.auth.mode "oauth" }}
+
+3. OAuth Authentication Mode:
+   - Server URL: {{ include "nextcloud-mcp-server.mcpServerUrl" . }}
+   - Issuer URL: {{ include "nextcloud-mcp-server.publicIssuerUrl" . }}
+   - Connected to: {{ .Values.nextcloud.host }}
+   {{- if .Values.auth.oauth.existingSecret }}
+   - Using existing OAuth client secret: {{ .Values.auth.oauth.existingSecret }}
+   {{- else if and .Values.auth.oauth.clientId .Values.auth.oauth.clientSecret }}
+   - Using pre-registered OAuth client
+   {{- else }}
+   - Using Dynamic Client Registration (DCR)
+   {{- end }}
+   {{- if .Values.auth.oauth.persistence.enabled }}
+   - OAuth client credentials are persisted in PVC: {{ include "nextcloud-mcp-server.oauthPvcName" . }}
+   {{- end }}
+
+   IMPORTANT: OAuth mode is experimental and requires patches to the user_oidc app.
+   See: https://github.com/cbcoutinho/nextcloud-mcp-server#authentication
+{{- else if eq .Values.auth.mode "multi-user-basic" }}
+
+3. Multi-User BasicAuth Mode (Pass-Through):
+   - Users provide credentials via Authorization header
+   - Connected to: {{ .Values.nextcloud.host }}
+   {{- if .Values.auth.multiUserBasic.enableOfflineAccess }}
+   - Offline access: Enabled (background operations with app passwords)
+   - Token storage: {{ .Values.auth.multiUserBasic.tokenStorageDb }}
+   {{- else }}
+   - Offline access: Disabled (stateless pass-through)
+   {{- end }}
+{{- else if eq .Values.auth.mode "login-flow" }}
+
+3. Login Flow v2 Mode (Experimental, ADR-022):
+   - Server URL: {{ include "nextcloud-mcp-server.mcpServerUrl" . }}
+   - Connected to: {{ .Values.nextcloud.host }}
+   - Token storage: {{ .Values.auth.loginFlow.tokenStorageDb }}
+
+   Users authenticate via Nextcloud's native Login Flow v2 — no OAuth patches required.
+   Each user gets a per-device app password managed by the MCP server.
+
+   IMPORTANT: Login Flow v2 is experimental. See ADR-022 for details.
+{{- end }}
+
+{{- if .Values.documentProcessing.enabled }}
+
+4. Document Processing:
+   - Enabled: {{ .Values.documentProcessing.enabled }}
+   - Default processor: {{ .Values.documentProcessing.defaultProcessor }}
+   {{- if .Values.documentProcessing.unstructured.enabled }}
+   - Unstructured API: {{ .Values.documentProcessing.unstructured.apiUrl }}
+   {{- end }}
+{{- end }}
+
+{{- if .Values.semanticSearch.enabled }}
+
+5. Semantic Search & Vector Capabilities:
+   - Semantic Search: Enabled
+   - Scan Interval: {{ .Values.semanticSearch.scanInterval }}s
+   - Processor Workers: {{ .Values.semanticSearch.processorWorkers }}
+   {{- if .Values.qdrant.enabled }}
+   - Qdrant: Deployed as subchart ({{ .Release.Name }}-qdrant:6333)
+   {{- else }}
+   - Qdrant: Not deployed (configure external instance)
+   {{- end }}
+   {{- if .Values.ollama.enabled }}
+   - Ollama: Deployed as subchart ({{ .Release.Name }}-ollama:11434)
+   - Embedding Model: {{ .Values.ollama.embeddingModel }}
+   {{- else if .Values.ollama.url }}
+   - Ollama: Using external instance at {{ .Values.ollama.url }}
+   - Embedding Model: {{ .Values.ollama.embeddingModel }}
+   {{- else if .Values.openai.enabled }}
+   - OpenAI: Enabled for embeddings
+   {{- else }}
+   - WARNING: No embedding provider configured (Ollama or OpenAI required)
+   {{- end }}
+
+   Check vector sync status:
+   kubectl --namespace {{ .Release.Namespace }} exec -it deploy/{{ include "nextcloud-mcp-server.fullname" . }} -- curl -s http://localhost:{{ include "nextcloud-mcp-server.port" . }}/user/page | grep "Vector Sync"
+{{- end }}
+
+{{- if .Values.dashboards.enabled }}
+
+6. Grafana Dashboards:
+   - Dashboard provisioning: Enabled
+   - ConfigMap: {{ include "nextcloud-mcp-server.fullname" . }}-dashboard
+   - Grafana Folder: {{ .Values.dashboards.grafanaFolder }}
+
+   The dashboard will be automatically imported by Grafana if the sidecar is configured
+   to watch for ConfigMaps with label "grafana_dashboard: 1".
+
+   To manually import the dashboard:
+   kubectl --namespace {{ .Release.Namespace }} get configmap {{ include "nextcloud-mcp-server.fullname" . }}-dashboard -o jsonpath='{.data.nextcloud-mcp-server\.json}' | jq . > dashboard.json
+
+   Then import dashboard.json via Grafana UI (Dashboards → Import).
+{{- else }}
+
+6. Grafana Dashboards:
+   - Dashboard provisioning: Disabled
+   - To enable automatic dashboard provisioning, set: dashboards.enabled=true
+
+   Manual import option:
+   The dashboard JSON is available in the chart at charts/nextcloud-mcp-server/dashboards/nextcloud-mcp-server.json
+{{- end }}
+
+{{- $legacyMultiUserBasic := eq (include "nextcloud-mcp-server.legacyMultiUserBasicPersistence" .) "true" }}
+{{- $legacyQdrant := eq (include "nextcloud-mcp-server.legacyQdrantPersistence" .) "true" }}
+{{- if or $legacyMultiUserBasic $legacyQdrant }}
+
+================================================================================
+                         DEPRECATION WARNING
+================================================================================
+
+You are using deprecated persistence configuration that will be removed in a
+future release. Your deployment will continue to work, but please migrate to
+the new unified dataStorage configuration.
+
+Deprecated settings detected:
+{{- if $legacyMultiUserBasic }}
+  - auth.multiUserBasic.persistence.* (currently enabled)
+{{- end }}
+{{- if $legacyQdrant }}
+  - qdrant.localPersistence.* (currently enabled)
+{{- end }}
+
+To migrate, update your values.yaml:
+
+  dataStorage:
+    enabled: true
+{{- if $legacyMultiUserBasic }}
+    size: {{ .Values.auth.multiUserBasic.persistence.size }}
+{{- else if $legacyQdrant }}
+    size: {{ .Values.qdrant.localPersistence.size }}
+{{- end }}
+    # storageClass: ""  # Optional: specify storage class
+    # existingClaim: "" # Optional: use existing PVC to preserve data
+
+After migrating, remove the deprecated settings:
+{{- if $legacyMultiUserBasic }}
+  - auth.multiUserBasic.persistence.enabled
+  - auth.multiUserBasic.persistence.size
+  - auth.multiUserBasic.persistence.storageClass
+  - auth.multiUserBasic.persistence.accessMode
+{{- end }}
+{{- if $legacyQdrant }}
+  - qdrant.localPersistence.enabled
+  - qdrant.localPersistence.size
+  - qdrant.localPersistence.storageClass
+  - qdrant.localPersistence.accessMode
+{{- end }}
+
+================================================================================
+{{- end }}
+
+Deployed version:
+  - Chart: {{ .Chart.Version }}
+  - App: {{ .Chart.AppVersion }}
+
+Full changelog: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/charts/nextcloud-mcp-server/CHANGELOG.md
+
+For more information and documentation:
+- GitHub: https://github.com/cbcoutinho/nextcloud-mcp-server
+- Documentation: https://github.com/cbcoutinho/nextcloud-mcp-server#readme
+
+To upgrade this deployment:
+  helm upgrade {{ .Release.Name }} nextcloud-mcp-server
+
+To uninstall:
+  helm uninstall {{ .Release.Name }}

charts/nextcloud-mcp-server/templates/_helpers.tpl

@@ -0,0 +1,237 @@
+{{/*
+Expand the name of the chart.
+*/}}
+{{- define "nextcloud-mcp-server.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Create a default fully qualified app name.
+We truncate at 63 chars because some Kubernetes name fields are limited to this (by the DNS naming spec).
+If release name contains chart name it will be used as a full name.
+*/}}
+{{- define "nextcloud-mcp-server.fullname" -}}
+{{- if .Values.fullnameOverride }}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- $name := default .Chart.Name .Values.nameOverride }}
+{{- if contains $name .Release.Name }}
+{{- .Release.Name | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
+{{- end }}
+{{- end }}
+{{- end }}
+
+{{/*
+Create chart name and version as used by the chart label.
+*/}}
+{{- define "nextcloud-mcp-server.chart" -}}
+{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Common labels
+*/}}
+{{- define "nextcloud-mcp-server.labels" -}}
+helm.sh/chart: {{ include "nextcloud-mcp-server.chart" . }}
+{{ include "nextcloud-mcp-server.selectorLabels" . }}
+{{- if .Chart.AppVersion }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+{{- end }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end }}
+
+{{/*
+Selector labels
+*/}}
+{{- define "nextcloud-mcp-server.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "nextcloud-mcp-server.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end }}
+
+{{/*
+Create the name of the service account to use
+*/}}
+{{- define "nextcloud-mcp-server.serviceAccountName" -}}
+{{- if .Values.serviceAccount.create }}
+{{- default (include "nextcloud-mcp-server.fullname" .) .Values.serviceAccount.name }}
+{{- else }}
+{{- default "default" .Values.serviceAccount.name }}
+{{- end }}
+{{- end }}
+
+{{/*
+Create the name of the secret to use for basic auth
+*/}}
+{{- define "nextcloud-mcp-server.basicAuthSecretName" -}}
+{{- if .Values.auth.basic.existingSecret }}
+{{- .Values.auth.basic.existingSecret }}
+{{- else }}
+{{- include "nextcloud-mcp-server.fullname" . }}-basic-auth
+{{- end }}
+{{- end }}
+
+{{/*
+Create the name of the secret to use for multi-user basic auth
+*/}}
+{{- define "nextcloud-mcp-server.multiUserBasicSecretName" -}}
+{{- if .Values.auth.multiUserBasic.existingSecret }}
+{{- .Values.auth.multiUserBasic.existingSecret }}
+{{- else }}
+{{- include "nextcloud-mcp-server.fullname" . }}-multi-user-basic
+{{- end }}
+{{- end }}
+
+{{/*
+Create the name of the PVC to use for multi-user basic token storage
+*/}}
+{{- define "nextcloud-mcp-server.multiUserBasicPvcName" -}}
+{{- if .Values.auth.multiUserBasic.persistence.existingClaim }}
+{{- .Values.auth.multiUserBasic.persistence.existingClaim }}
+{{- else }}
+{{- include "nextcloud-mcp-server.fullname" . }}-token-storage
+{{- end }}
+{{- end }}
+
+{{/*
+Create the name of the secret to use for OAuth
+*/}}
+{{- define "nextcloud-mcp-server.oauthSecretName" -}}
+{{- if .Values.auth.oauth.existingSecret }}
+{{- .Values.auth.oauth.existingSecret }}
+{{- else }}
+{{- include "nextcloud-mcp-server.fullname" . }}-oauth
+{{- end }}
+{{- end }}
+
+{{/*
+Create the name of the secret to use for Login Flow v2
+*/}}
+{{- define "nextcloud-mcp-server.loginFlowSecretName" -}}
+{{- if .Values.auth.loginFlow.existingSecret }}
+{{- .Values.auth.loginFlow.existingSecret }}
+{{- else }}
+{{- include "nextcloud-mcp-server.fullname" . }}-login-flow
+{{- end }}
+{{- end }}
+
+{{/*
+Create the name of the PVC to use for OAuth storage
+*/}}
+{{- define "nextcloud-mcp-server.oauthPvcName" -}}
+{{- if .Values.auth.oauth.persistence.existingClaim }}
+{{- .Values.auth.oauth.persistence.existingClaim }}
+{{- else }}
+{{- include "nextcloud-mcp-server.fullname" . }}-oauth-storage
+{{- end }}
+{{- end }}
+
+{{/*
+Create the name of the PVC to use for Qdrant local persistent storage
+*/}}
+{{- define "nextcloud-mcp-server.qdrantPvcName" -}}
+{{- if .Values.qdrant.localPersistence.existingClaim }}
+{{- .Values.qdrant.localPersistence.existingClaim }}
+{{- else }}
+{{- include "nextcloud-mcp-server.fullname" . }}-qdrant-data
+{{- end }}
+{{- end }}
+
+{{/*
+Create the name of the PVC to use for /app/data storage
+*/}}
+{{- define "nextcloud-mcp-server.dataStoragePvcName" -}}
+{{- if .Values.dataStorage.existingClaim }}
+{{- .Values.dataStorage.existingClaim }}
+{{- else }}
+{{- include "nextcloud-mcp-server.fullname" . }}-data-storage
+{{- end }}
+{{- end }}
+
+{{/*
+Determine if data storage PVC should be enabled (backward compatible)
+Checks new dataStorage.enabled OR legacy persistence configs
+*/}}
+{{- define "nextcloud-mcp-server.dataStorageEnabled" -}}
+{{- if .Values.dataStorage.enabled -}}
+true
+{{- else if and (eq .Values.auth.mode "multi-user-basic") .Values.auth.multiUserBasic.enableOfflineAccess .Values.auth.multiUserBasic.persistence.enabled -}}
+true
+{{- else if eq .Values.auth.mode "login-flow" -}}
+true
+{{- else if and (eq .Values.qdrant.mode "persistent") .Values.qdrant.localPersistence.enabled -}}
+true
+{{- else -}}
+false
+{{- end -}}
+{{- end }}
+
+{{/*
+Check if legacy multi-user-basic persistence config is being used
+*/}}
+{{- define "nextcloud-mcp-server.legacyMultiUserBasicPersistence" -}}
+{{- if and (eq .Values.auth.mode "multi-user-basic") .Values.auth.multiUserBasic.enableOfflineAccess .Values.auth.multiUserBasic.persistence.enabled (not .Values.dataStorage.enabled) -}}
+true
+{{- else -}}
+false
+{{- end -}}
+{{- end }}
+
+{{/*
+Check if legacy qdrant persistence config is being used
+*/}}
+{{- define "nextcloud-mcp-server.legacyQdrantPersistence" -}}
+{{- if and (eq .Values.qdrant.mode "persistent") .Values.qdrant.localPersistence.enabled (not .Values.dataStorage.enabled) -}}
+true
+{{- else -}}
+false
+{{- end -}}
+{{- end }}
+
+{{/*
+Return the MCP server port
+*/}}
+{{- define "nextcloud-mcp-server.port" -}}
+{{- .Values.mcp.port }}
+{{- end }}
+
+{{/*
+Return the image tag (always uses chart appVersion)
+*/}}
+{{- define "nextcloud-mcp-server.imageTag" -}}
+{{- .Chart.AppVersion }}
+{{- end }}
+
+{{/*
+Return the public issuer URL for OAuth
+Defaults to nextcloud.host if not specified
+*/}}
+{{- define "nextcloud-mcp-server.publicIssuerUrl" -}}
+{{- if .Values.nextcloud.publicIssuerUrl }}
+{{- .Values.nextcloud.publicIssuerUrl }}
+{{- else }}
+{{- .Values.nextcloud.host }}
+{{- end }}
+{{- end }}
+
+{{/*
+Return the MCP server URL for OAuth callbacks
+If not specified:
+  - Uses ingress host if ingress is enabled
+  - Otherwise defaults to http://localhost:8000 (for port-forward setups)
+*/}}
+{{- define "nextcloud-mcp-server.mcpServerUrl" -}}
+{{- if .Values.nextcloud.mcpServerUrl }}
+{{- .Values.nextcloud.mcpServerUrl }}
+{{- else if .Values.ingress.enabled }}
+{{- $host := index .Values.ingress.hosts 0 }}
+{{- if .Values.ingress.tls }}
+{{- printf "https://%s" $host.host }}
+{{- else }}
+{{- printf "http://%s" $host.host }}
+{{- end }}
+{{- else }}
+{{- printf "http://localhost:%d" (int .Values.mcp.port) }}
+{{- end }}
+{{- end }}

charts/nextcloud-mcp-server/templates/dashboard-configmap.yaml

@@ -0,0 +1,25 @@
+{{- if .Values.dashboards.enabled }}
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: {{ include "nextcloud-mcp-server.fullname" . }}-dashboard
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+    {{- with .Values.dashboards.labels }}
+    {{- toYaml . | nindent 4 }}
+    {{- end }}
+    # Grafana sidecar discovery label
+    grafana_dashboard: "1"
+  annotations:
+    {{- with .Values.dashboards.annotations }}
+    {{- toYaml . | nindent 4 }}
+    {{- end }}
+    # Grafana folder name (annotations support spaces, unlike labels)
+    {{- if .Values.dashboards.grafanaFolder }}
+    grafana_folder: {{ .Values.dashboards.grafanaFolder | quote }}
+    {{- end }}
+data:
+  nextcloud-mcp-server.json: |-
+{{ .Files.Get "dashboards/nextcloud-mcp-server.json" | indent 4 }}
+{{- end }}

charts/nextcloud-mcp-server/templates/deployment.yaml

@@ -0,0 +1,340 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ include "nextcloud-mcp-server.fullname" . }}
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+spec:
+  strategy:
+    type: Recreate
+  {{- if not .Values.autoscaling.enabled }}
+  replicas: {{ .Values.replicaCount }}
+  {{- end }}
+  selector:
+    matchLabels:
+      {{- include "nextcloud-mcp-server.selectorLabels" . | nindent 6 }}
+  template:
+    metadata:
+      annotations:
+        checksum/secret: {{ include (print $.Template.BasePath "/secret.yaml") . | sha256sum }}
+        {{- with .Values.podAnnotations }}
+        {{- toYaml . | nindent 8 }}
+        {{- end }}
+      labels:
+        {{- include "nextcloud-mcp-server.labels" . | nindent 8 }}
+        {{- with .Values.podLabels }}
+        {{- toYaml . | nindent 8 }}
+        {{- end }}
+    spec:
+      {{- with .Values.imagePullSecrets }}
+      imagePullSecrets:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      serviceAccountName: {{ include "nextcloud-mcp-server.serviceAccountName" . }}
+      securityContext:
+        {{- toYaml .Values.podSecurityContext | nindent 8 }}
+      {{- with .Values.initContainers }}
+      initContainers:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      containers:
+        - name: {{ .Chart.Name }}
+          securityContext:
+            {{- toYaml .Values.securityContext | nindent 12 }}
+          image: "{{ .Values.image.repository }}:{{ include "nextcloud-mcp-server.imageTag" . }}"
+          imagePullPolicy: {{ .Values.image.pullPolicy }}
+          args:
+            - "--transport"
+            - "{{ .Values.mcp.transport }}"
+            {{- if or (eq .Values.auth.mode "oauth") (eq .Values.auth.mode "login-flow") }}
+            - "--oauth"
+            {{- end }}
+            {{- if eq .Values.auth.mode "oauth" }}
+            - "--oauth-token-type"
+            - "{{ .Values.auth.oauth.tokenType }}"
+            {{- end }}
+            {{- with .Values.mcp.extraArgs }}
+            {{- toYaml . | nindent 12 }}
+            {{- end }}
+          ports:
+            - name: http
+              containerPort: {{ include "nextcloud-mcp-server.port" . }}
+              protocol: TCP
+            {{- if .Values.observability.metrics.enabled }}
+            - name: metrics
+              containerPort: {{ .Values.observability.metrics.port }}
+              protocol: TCP
+            {{- end }}
+          env:
+            # Nextcloud connection
+            - name: NEXTCLOUD_HOST
+              value: {{ .Values.nextcloud.host | quote }}
+            {{- if eq .Values.auth.mode "basic" }}
+            # Basic auth mode (single-user)
+            - name: NEXTCLOUD_USERNAME
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "nextcloud-mcp-server.basicAuthSecretName" . }}
+                  key: {{ .Values.auth.basic.usernameKey }}
+            - name: NEXTCLOUD_PASSWORD
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "nextcloud-mcp-server.basicAuthSecretName" . }}
+                  key: {{ .Values.auth.basic.passwordKey }}
+            {{- else if eq .Values.auth.mode "multi-user-basic" }}
+            # Multi-user BasicAuth mode (pass-through)
+            - name: ENABLE_MULTI_USER_BASIC_AUTH
+              value: "true"
+            - name: NEXTCLOUD_MCP_SERVER_URL
+              value: {{ include "nextcloud-mcp-server.mcpServerUrl" . | quote }}
+            - name: NEXTCLOUD_PUBLIC_ISSUER_URL
+              value: {{ include "nextcloud-mcp-server.publicIssuerUrl" . | quote }}
+            {{- if .Values.auth.multiUserBasic.enableOfflineAccess }}
+            # Background operations with app passwords (replaces deprecated ENABLE_OFFLINE_ACCESS)
+            - name: ENABLE_BACKGROUND_OPERATIONS
+              value: "true"
+            - name: TOKEN_STORAGE_DB
+              value: {{ .Values.auth.multiUserBasic.tokenStorageDb | quote }}
+            - name: TOKEN_ENCRYPTION_KEY
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "nextcloud-mcp-server.multiUserBasicSecretName" . }}
+                  key: {{ .Values.auth.multiUserBasic.tokenEncryptionKeyKey }}
+            - name: NEXTCLOUD_OIDC_SCOPES
+              value: {{ .Values.auth.multiUserBasic.scopes | quote }}
+            {{- if or .Values.auth.multiUserBasic.clientId .Values.auth.multiUserBasic.existingSecret }}
+            # Static OAuth credentials (optional - uses DCR if not provided)
+            - name: NEXTCLOUD_OIDC_CLIENT_ID
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "nextcloud-mcp-server.multiUserBasicSecretName" . }}
+                  key: {{ .Values.auth.multiUserBasic.clientIdKey }}
+            - name: NEXTCLOUD_OIDC_CLIENT_SECRET
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "nextcloud-mcp-server.multiUserBasicSecretName" . }}
+                  key: {{ .Values.auth.multiUserBasic.clientSecretKey }}
+            {{- end }}
+            {{- end }}
+            {{- else if eq .Values.auth.mode "oauth" }}
+            # OAuth mode
+            - name: NEXTCLOUD_MCP_SERVER_URL
+              value: {{ include "nextcloud-mcp-server.mcpServerUrl" . | quote }}
+            - name: NEXTCLOUD_PUBLIC_ISSUER_URL
+              value: {{ include "nextcloud-mcp-server.publicIssuerUrl" . | quote }}
+            - name: NEXTCLOUD_OIDC_SCOPES
+              value: {{ .Values.auth.oauth.scopes | quote }}
+            {{- if or .Values.auth.oauth.clientId .Values.auth.oauth.existingSecret }}
+            - name: NEXTCLOUD_OIDC_CLIENT_ID
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "nextcloud-mcp-server.oauthSecretName" . }}
+                  key: {{ .Values.auth.oauth.clientIdKey }}
+            - name: NEXTCLOUD_OIDC_CLIENT_SECRET
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "nextcloud-mcp-server.oauthSecretName" . }}
+                  key: {{ .Values.auth.oauth.clientSecretKey }}
+            {{- end }}
+            {{- else if eq .Values.auth.mode "login-flow" }}
+            # Login Flow v2 mode (ADR-022)
+            - name: ENABLE_LOGIN_FLOW
+              value: "true"
+            - name: NEXTCLOUD_MCP_SERVER_URL
+              value: {{ include "nextcloud-mcp-server.mcpServerUrl" . | quote }}
+            - name: NEXTCLOUD_PUBLIC_ISSUER_URL
+              value: {{ include "nextcloud-mcp-server.publicIssuerUrl" . | quote }}
+            - name: TOKEN_STORAGE_DB
+              value: {{ .Values.auth.loginFlow.tokenStorageDb | quote }}
+            - name: TOKEN_ENCRYPTION_KEY
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "nextcloud-mcp-server.loginFlowSecretName" . }}
+                  key: {{ .Values.auth.loginFlow.tokenEncryptionKeyKey }}
+            {{- end }}
+            {{- if .Values.documentProcessing.enabled }}
+            # Document processing
+            - name: ENABLE_DOCUMENT_PROCESSING
+              value: {{ .Values.documentProcessing.enabled | quote }}
+            - name: DOCUMENT_PROCESSOR
+              value: {{ .Values.documentProcessing.defaultProcessor | quote }}
+            - name: PROGRESS_INTERVAL
+              value: {{ .Values.documentProcessing.progressInterval | quote }}
+            {{- if .Values.documentProcessing.unstructured.enabled }}
+            - name: ENABLE_UNSTRUCTURED
+              value: "true"
+            - name: UNSTRUCTURED_API_URL
+              value: {{ .Values.documentProcessing.unstructured.apiUrl | quote }}
+            - name: UNSTRUCTURED_TIMEOUT
+              value: {{ .Values.documentProcessing.unstructured.timeout | quote }}
+            - name: UNSTRUCTURED_STRATEGY
+              value: {{ .Values.documentProcessing.unstructured.strategy | quote }}
+            - name: UNSTRUCTURED_LANGUAGES
+              value: {{ .Values.documentProcessing.unstructured.languages | quote }}
+            {{- end }}
+            {{- if .Values.documentProcessing.tesseract.enabled }}
+            - name: ENABLE_TESSERACT
+              value: "true"
+            {{- if .Values.documentProcessing.tesseract.cmd }}
+            - name: TESSERACT_CMD
+              value: {{ .Values.documentProcessing.tesseract.cmd | quote }}
+            {{- end }}
+            - name: TESSERACT_LANG
+              value: {{ .Values.documentProcessing.tesseract.lang | quote }}
+            {{- end }}
+            {{- if .Values.documentProcessing.custom.enabled }}
+            - name: ENABLE_CUSTOM_PROCESSOR
+              value: "true"
+            - name: CUSTOM_PROCESSOR_NAME
+              value: {{ .Values.documentProcessing.custom.name | quote }}
+            - name: CUSTOM_PROCESSOR_URL
+              value: {{ .Values.documentProcessing.custom.url | quote }}
+            {{- if .Values.documentProcessing.custom.apiKey }}
+            - name: CUSTOM_PROCESSOR_API_KEY
+              value: {{ .Values.documentProcessing.custom.apiKey | quote }}
+            {{- end }}
+            - name: CUSTOM_PROCESSOR_TIMEOUT
+              value: {{ .Values.documentProcessing.custom.timeout | quote }}
+            - name: CUSTOM_PROCESSOR_TYPES
+              value: {{ .Values.documentProcessing.custom.types | quote }}
+            {{- end }}
+            {{- end }}
+            # Semantic Search (replaces deprecated VECTOR_SYNC_ENABLED)
+            - name: ENABLE_SEMANTIC_SEARCH
+              value: {{ .Values.semanticSearch.enabled | quote }}
+            {{- if .Values.semanticSearch.enabled }}
+            - name: VECTOR_SYNC_SCAN_INTERVAL
+              value: {{ .Values.semanticSearch.scanInterval | quote }}
+            - name: VECTOR_SYNC_PROCESSOR_WORKERS
+              value: {{ .Values.semanticSearch.processorWorkers | quote }}
+            - name: VECTOR_SYNC_QUEUE_MAX_SIZE
+              value: {{ .Values.semanticSearch.queueMaxSize | quote }}
+            {{- end }}
+            # Document Chunking (always set, used by vector sync processor)
+            - name: DOCUMENT_CHUNK_SIZE
+              value: {{ .Values.documentChunking.chunkSize | quote }}
+            - name: DOCUMENT_CHUNK_OVERLAP
+              value: {{ .Values.documentChunking.chunkOverlap | quote }}
+            # Qdrant Vector Database
+            {{- if eq .Values.qdrant.mode "network" }}
+            # Network mode: Use dedicated Qdrant service
+            {{- if .Values.qdrant.networkMode.deploySubchart }}
+            - name: QDRANT_URL
+              value: "http://{{ .Release.Name }}-qdrant:6333"
+            {{- else if .Values.qdrant.networkMode.externalUrl }}
+            - name: QDRANT_URL
+              value: {{ .Values.qdrant.networkMode.externalUrl | quote }}
+            {{- end }}
+            {{- if or .Values.qdrant.networkMode.apiKey .Values.qdrant.networkMode.existingSecret }}
+            - name: QDRANT_API_KEY
+              valueFrom:
+                secretKeyRef:
+                  name: {{ .Values.qdrant.networkMode.existingSecret | default (printf "%s-qdrant" .Release.Name) }}
+                  key: {{ .Values.qdrant.networkMode.secretKey }}
+            {{- end }}
+            {{- else if eq .Values.qdrant.mode "persistent" }}
+            # Persistent local mode: File-based storage
+            - name: QDRANT_LOCATION
+              value: {{ .Values.qdrant.localPersistence.dataPath | quote }}
+            {{- else }}
+            # In-memory mode (default): Ephemeral storage
+            - name: QDRANT_LOCATION
+              value: ":memory:"
+            {{- end }}
+            - name: QDRANT_COLLECTION
+              value: {{ .Values.qdrant.collection | quote }}
+            # Ollama Embedding Service
+            {{- if or .Values.ollama.enabled .Values.ollama.url }}
+            - name: OLLAMA_BASE_URL
+              value: {{ .Values.ollama.url | default (printf "http://%s-ollama:11434" .Release.Name) | quote }}
+            - name: OLLAMA_EMBEDDING_MODEL
+              value: {{ .Values.ollama.embeddingModel | quote }}
+            - name: OLLAMA_VERIFY_SSL
+              value: {{ .Values.ollama.verifySsl | quote }}
+            {{- end }}
+            # OpenAI Embedding Provider (alternative to Ollama)
+            {{- if .Values.openai.enabled }}
+            - name: OPENAI_API_KEY
+              valueFrom:
+                secretKeyRef:
+                  name: {{ .Values.openai.existingSecret | default (printf "%s-openai" (include "nextcloud-mcp-server.fullname" .)) }}
+                  key: {{ .Values.openai.secretKey }}
+            {{- if .Values.openai.baseUrl }}
+            - name: OPENAI_BASE_URL
+              value: {{ .Values.openai.baseUrl | quote }}
+            {{- end }}
+            {{- end }}
+            # Observability
+            - name: METRICS_ENABLED
+              value: {{ .Values.observability.metrics.enabled | quote }}
+            - name: METRICS_PORT
+              value: {{ .Values.observability.metrics.port | quote }}
+            {{- if .Values.observability.tracing.enabled }}
+            - name: OTEL_EXPORTER_OTLP_ENDPOINT
+              value: {{ .Values.observability.tracing.endpoint | quote }}
+            - name: OTEL_SERVICE_NAME
+              value: {{ .Values.observability.tracing.serviceName | quote }}
+            - name: OTEL_TRACES_SAMPLER_ARG
+              value: {{ .Values.observability.tracing.samplingRate | quote }}
+            {{- end }}
+            - name: LOG_FORMAT
+              value: {{ .Values.observability.logging.format | quote }}
+            - name: LOG_LEVEL
+              value: {{ .Values.observability.logging.level | quote }}
+            - name: LOG_INCLUDE_TRACE_CONTEXT
+              value: {{ .Values.observability.logging.includeTraceContext | quote }}
+            {{- with .Values.extraEnv }}
+            {{- toYaml . | nindent 12 }}
+            {{- end }}
+          {{- with .Values.extraEnvFrom }}
+          envFrom:
+            {{- toYaml . | nindent 12 }}
+          {{- end }}
+          livenessProbe:
+            {{- toYaml .Values.livenessProbe | nindent 12 }}
+          readinessProbe:
+            {{- toYaml .Values.readinessProbe | nindent 12 }}
+          resources:
+            {{- toYaml .Values.resources | nindent 12 }}
+          volumeMounts:
+            - name: tmp
+              mountPath: /tmp
+            {{- if or (and (eq .Values.auth.mode "oauth") .Values.auth.oauth.persistence.enabled) (eq .Values.auth.mode "login-flow") }}
+            - name: oauth-storage
+              mountPath: /app/.oauth
+            {{- end }}
+            - name: data-storage
+              mountPath: /app/data
+            {{- with .Values.volumeMounts }}
+            {{- toYaml . | nindent 12 }}
+            {{- end }}
+      volumes:
+        - name: tmp
+          emptyDir: {}
+        {{- if or (and (eq .Values.auth.mode "oauth") .Values.auth.oauth.persistence.enabled) (eq .Values.auth.mode "login-flow") }}
+        - name: oauth-storage
+          persistentVolumeClaim:
+            claimName: {{ include "nextcloud-mcp-server.oauthPvcName" . }}
+        {{- end }}
+        - name: data-storage
+        {{- if eq (include "nextcloud-mcp-server.dataStorageEnabled" .) "true" }}
+          persistentVolumeClaim:
+            claimName: {{ include "nextcloud-mcp-server.dataStoragePvcName" . }}
+        {{- else }}
+          emptyDir: {}
+        {{- end }}
+        {{- with .Values.volumes }}
+        {{- toYaml . | nindent 8 }}
+        {{- end }}
+      {{- with .Values.nodeSelector }}
+      nodeSelector:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.affinity }}
+      affinity:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.tolerations }}
+      tolerations:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}

charts/nextcloud-mcp-server/templates/hpa.yaml

@@ -0,0 +1,32 @@
+{{- if .Values.autoscaling.enabled }}
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: {{ include "nextcloud-mcp-server.fullname" . }}
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: {{ include "nextcloud-mcp-server.fullname" . }}
+  minReplicas: {{ .Values.autoscaling.minReplicas }}
+  maxReplicas: {{ .Values.autoscaling.maxReplicas }}
+  metrics:
+    {{- if .Values.autoscaling.targetCPUUtilizationPercentage }}
+    - type: Resource
+      resource:
+        name: cpu
+        target:
+          type: Utilization
+          averageUtilization: {{ .Values.autoscaling.targetCPUUtilizationPercentage }}
+    {{- end }}
+    {{- if .Values.autoscaling.targetMemoryUtilizationPercentage }}
+    - type: Resource
+      resource:
+        name: memory
+        target:
+          type: Utilization
+          averageUtilization: {{ .Values.autoscaling.targetMemoryUtilizationPercentage }}
+    {{- end }}
+{{- end }}

charts/nextcloud-mcp-server/templates/ingress.yaml

@@ -0,0 +1,61 @@
+{{- if .Values.ingress.enabled -}}
+{{- $fullName := include "nextcloud-mcp-server.fullname" . -}}
+{{- $svcPort := .Values.service.port -}}
+{{- if and .Values.ingress.className (not (semverCompare ">=1.18-0" .Capabilities.KubeVersion.GitVersion)) }}
+  {{- if not (hasKey .Values.ingress.annotations "kubernetes.io/ingress.class") }}
+  {{- $_ := set .Values.ingress.annotations "kubernetes.io/ingress.class" .Values.ingress.className}}
+  {{- end }}
+{{- end }}
+{{- if semverCompare ">=1.19-0" .Capabilities.KubeVersion.GitVersion -}}
+apiVersion: networking.k8s.io/v1
+{{- else if semverCompare ">=1.14-0" .Capabilities.KubeVersion.GitVersion -}}
+apiVersion: networking.k8s.io/v1beta1
+{{- else -}}
+apiVersion: extensions/v1beta1
+{{- end }}
+kind: Ingress
+metadata:
+  name: {{ $fullName }}
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+  {{- with .Values.ingress.annotations }}
+  annotations:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+spec:
+  {{- if and .Values.ingress.className (semverCompare ">=1.18-0" .Capabilities.KubeVersion.GitVersion) }}
+  ingressClassName: {{ .Values.ingress.className }}
+  {{- end }}
+  {{- if .Values.ingress.tls }}
+  tls:
+    {{- range .Values.ingress.tls }}
+    - hosts:
+        {{- range .hosts }}
+        - {{ . | quote }}
+        {{- end }}
+      secretName: {{ .secretName }}
+    {{- end }}
+  {{- end }}
+  rules:
+    {{- range .Values.ingress.hosts }}
+    - host: {{ .host | quote }}
+      http:
+        paths:
+          {{- range .paths }}
+          - path: {{ .path }}
+            {{- if and .pathType (semverCompare ">=1.18-0" $.Capabilities.KubeVersion.GitVersion) }}
+            pathType: {{ .pathType }}
+            {{- end }}
+            backend:
+              {{- if semverCompare ">=1.19-0" $.Capabilities.KubeVersion.GitVersion }}
+              service:
+                name: {{ $fullName }}
+                port:
+                  number: {{ $svcPort }}
+              {{- else }}
+              serviceName: {{ $fullName }}
+              servicePort: {{ $svcPort }}
+              {{- end }}
+          {{- end }}
+    {{- end }}
+{{- end }}

charts/nextcloud-mcp-server/templates/openai-secret.yaml

@@ -0,0 +1,11 @@
+{{- if and .Values.openai.enabled (not .Values.openai.existingSecret) }}
+apiVersion: v1
+kind: Secret
+metadata:
+  name: {{ include "nextcloud-mcp-server.fullname" . }}-openai
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+type: Opaque
+data:
+  {{ .Values.openai.secretKey }}: {{ .Values.openai.apiKey | b64enc | quote }}
+{{- end }}

charts/nextcloud-mcp-server/templates/prometheusrule.yaml

@@ -0,0 +1,92 @@
+{{- if and .Values.observability.metrics.enabled .Values.prometheusRule.enabled }}
+apiVersion: monitoring.coreos.com/v1
+kind: PrometheusRule
+metadata:
+  name: {{ include "nextcloud-mcp-server.fullname" . }}
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+    {{- with .Values.prometheusRule.labels }}
+    {{- toYaml . | nindent 4 }}
+    {{- end }}
+spec:
+  groups:
+    - name: nextcloud-mcp-server.critical
+      interval: 30s
+      rules:
+        - alert: NextcloudMCPServerDown
+          expr: up{job="{{ include "nextcloud-mcp-server.fullname" . }}"} == 0
+          for: 5m
+          labels:
+            severity: critical
+          annotations:
+            summary: "Nextcloud MCP Server is down"
+            description: "{{ `{{` }} $labels.pod {{ `}}` }} has been down for more than 5 minutes."
+
+        - alert: NextcloudMCPHighErrorRate
+          expr: |
+            sum(rate(mcp_http_requests_total{status_code=~"5..", job="{{ include "nextcloud-mcp-server.fullname" . }}"}[5m]))
+            / sum(rate(mcp_http_requests_total{job="{{ include "nextcloud-mcp-server.fullname" . }}"}[5m])) > 0.05
+          for: 5m
+          labels:
+            severity: critical
+          annotations:
+            summary: "High error rate on Nextcloud MCP Server"
+            description: "Error rate is {{ `{{` }} printf \"%.2f%%\" (mul $value 100) {{ `}}` }} (threshold: 5%)"
+
+        - alert: NextcloudMCPHighLatency
+          expr: |
+            histogram_quantile(0.95,
+              sum(rate(mcp_http_request_duration_seconds_bucket{job="{{ include "nextcloud-mcp-server.fullname" . }}"}[5m])) by (le, endpoint)
+            ) > 1
+          for: 5m
+          labels:
+            severity: critical
+          annotations:
+            summary: "High latency on Nextcloud MCP Server"
+            description: "P95 latency is {{ `{{` }} printf \"%.2fs\" $value {{ `}}` }} on {{ `{{` }} $labels.endpoint {{ `}}` }} (threshold: 1s)"
+
+        - alert: NextcloudMCPDependencyDown
+          expr: mcp_dependency_health{job="{{ include "nextcloud-mcp-server.fullname" . }}"} == 0
+          for: 2m
+          labels:
+            severity: critical
+          annotations:
+            summary: "Nextcloud MCP dependency is down"
+            description: "Dependency {{ `{{` }} $labels.dependency {{ `}}` }} has been down for more than 2 minutes."
+
+    - name: nextcloud-mcp-server.warning
+      interval: 30s
+      rules:
+        - alert: NextcloudMCPTokenValidationErrors
+          expr: |
+            sum(rate(mcp_oauth_token_validations_total{result="error", job="{{ include "nextcloud-mcp-server.fullname" . }}"}[10m]))
+            / sum(rate(mcp_oauth_token_validations_total{job="{{ include "nextcloud-mcp-server.fullname" . }}"}[10m])) > 0.01
+          for: 10m
+          labels:
+            severity: warning
+          annotations:
+            summary: "High token validation error rate"
+            description: "Token validation error rate is {{ `{{` }} printf \"%.2f%%\" (mul $value 100) {{ `}}` }} (threshold: 1%)"
+
+        - alert: NextcloudMCPVectorSyncQueueHigh
+          expr: mcp_vector_sync_queue_size{job="{{ include "nextcloud-mcp-server.fullname" . }}"} > 100
+          for: 15m
+          labels:
+            severity: warning
+          annotations:
+            summary: "Vector sync queue is high"
+            description: "Vector sync queue size is {{ `{{` }} $value {{ `}}` }} (threshold: 100)"
+
+        - alert: NextcloudMCPQdrantSlowQueries
+          expr: |
+            histogram_quantile(0.95,
+              sum(rate(mcp_db_operation_duration_seconds_bucket{db="qdrant", job="{{ include "nextcloud-mcp-server.fullname" . }}"}[10m])) by (le)
+            ) > 0.5
+          for: 10m
+          labels:
+            severity: warning
+          annotations:
+            summary: "Qdrant queries are slow"
+            description: "P95 Qdrant query latency is {{ `{{` }} printf \"%.2fs\" $value {{ `}}` }} (threshold: 0.5s)"
+{{- end }}

charts/nextcloud-mcp-server/templates/pvc.yaml

@@ -0,0 +1,64 @@
+{{- if and (eq .Values.auth.mode "oauth") .Values.auth.oauth.persistence.enabled (not .Values.auth.oauth.persistence.existingClaim) }}
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: {{ include "nextcloud-mcp-server.fullname" . }}-oauth-storage
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+spec:
+  accessModes:
+    - {{ .Values.auth.oauth.persistence.accessMode }}
+  {{- if .Values.auth.oauth.persistence.storageClass }}
+  storageClassName: {{ .Values.auth.oauth.persistence.storageClass }}
+  {{- end }}
+  resources:
+    requests:
+      storage: {{ .Values.auth.oauth.persistence.size }}
+{{- end }}
+---
+{{- if eq .Values.auth.mode "login-flow" }}
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: {{ include "nextcloud-mcp-server.fullname" . }}-oauth-storage
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+spec:
+  accessModes:
+    - ReadWriteOnce
+  resources:
+    requests:
+      storage: 100Mi
+{{- end }}
+---
+{{- if and (eq (include "nextcloud-mcp-server.dataStorageEnabled" .) "true") (not .Values.dataStorage.existingClaim) }}
+{{- $legacyMultiUserBasic := eq (include "nextcloud-mcp-server.legacyMultiUserBasicPersistence" .) "true" }}
+{{- $legacyQdrant := eq (include "nextcloud-mcp-server.legacyQdrantPersistence" .) "true" }}
+{{- $accessMode := .Values.dataStorage.accessMode }}
+{{- $storageClass := .Values.dataStorage.storageClass }}
+{{- $size := .Values.dataStorage.size }}
+{{- if $legacyMultiUserBasic }}
+{{- $accessMode = .Values.auth.multiUserBasic.persistence.accessMode }}
+{{- $storageClass = .Values.auth.multiUserBasic.persistence.storageClass }}
+{{- $size = .Values.auth.multiUserBasic.persistence.size }}
+{{- else if $legacyQdrant }}
+{{- $accessMode = .Values.qdrant.localPersistence.accessMode }}
+{{- $storageClass = .Values.qdrant.localPersistence.storageClass }}
+{{- $size = .Values.qdrant.localPersistence.size }}
+{{- end }}
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: {{ include "nextcloud-mcp-server.fullname" . }}-data-storage
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+spec:
+  accessModes:
+    - {{ $accessMode }}
+  {{- if $storageClass }}
+  storageClassName: {{ $storageClass }}
+  {{- end }}
+  resources:
+    requests:
+      storage: {{ $size }}
+{{- end }}

charts/nextcloud-mcp-server/templates/secret.yaml

@@ -0,0 +1,61 @@
+{{- if eq .Values.auth.mode "basic" }}
+{{- if not .Values.auth.basic.existingSecret }}
+apiVersion: v1
+kind: Secret
+metadata:
+  name: {{ include "nextcloud-mcp-server.fullname" . }}-basic-auth
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+type: Opaque
+data:
+  {{ .Values.auth.basic.usernameKey }}: {{ .Values.auth.basic.username | b64enc | quote }}
+  {{ .Values.auth.basic.passwordKey }}: {{ .Values.auth.basic.password | b64enc | quote }}
+{{- end }}
+{{- end }}
+---
+{{- if eq .Values.auth.mode "multi-user-basic" }}
+{{- if and .Values.auth.multiUserBasic.enableOfflineAccess (not .Values.auth.multiUserBasic.existingSecret) }}
+apiVersion: v1
+kind: Secret
+metadata:
+  name: {{ include "nextcloud-mcp-server.fullname" . }}-multi-user-basic
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+type: Opaque
+data:
+  {{ .Values.auth.multiUserBasic.tokenEncryptionKeyKey }}: {{ .Values.auth.multiUserBasic.tokenEncryptionKey | b64enc | quote }}
+  {{- if .Values.auth.multiUserBasic.clientId }}
+  {{ .Values.auth.multiUserBasic.clientIdKey }}: {{ .Values.auth.multiUserBasic.clientId | b64enc | quote }}
+  {{ .Values.auth.multiUserBasic.clientSecretKey }}: {{ .Values.auth.multiUserBasic.clientSecret | b64enc | quote }}
+  {{- end }}
+{{- end }}
+{{- end }}
+---
+{{- if eq .Values.auth.mode "oauth" }}
+{{- if and .Values.auth.oauth.clientId (not .Values.auth.oauth.existingSecret) }}
+apiVersion: v1
+kind: Secret
+metadata:
+  name: {{ include "nextcloud-mcp-server.fullname" . }}-oauth
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+type: Opaque
+data:
+  {{ .Values.auth.oauth.clientIdKey }}: {{ .Values.auth.oauth.clientId | b64enc | quote }}
+  {{ .Values.auth.oauth.clientSecretKey }}: {{ .Values.auth.oauth.clientSecret | b64enc | quote }}
+{{- end }}
+{{- end }}
+---
+{{- if eq .Values.auth.mode "login-flow" }}
+{{- if not .Values.auth.loginFlow.existingSecret }}
+apiVersion: v1
+kind: Secret
+metadata:
+  name: {{ include "nextcloud-mcp-server.fullname" . }}-login-flow
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+type: Opaque
+data:
+  {{ .Values.auth.loginFlow.tokenEncryptionKeyKey }}: {{ .Values.auth.loginFlow.tokenEncryptionKey | b64enc | quote }}
+{{- end }}
+{{- end }}

charts/nextcloud-mcp-server/templates/service.yaml

@@ -0,0 +1,25 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "nextcloud-mcp-server.fullname" . }}
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+  {{- with .Values.service.annotations }}
+  annotations:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+spec:
+  type: {{ .Values.service.type }}
+  ports:
+    - port: {{ .Values.service.port }}
+      targetPort: http
+      protocol: TCP
+      name: http
+    {{- if .Values.observability.metrics.enabled }}
+    - port: {{ .Values.observability.metrics.port }}
+      targetPort: metrics
+      protocol: TCP
+      name: metrics
+    {{- end }}
+  selector:
+    {{- include "nextcloud-mcp-server.selectorLabels" . | nindent 4 }}

charts/nextcloud-mcp-server/templates/serviceaccount.yaml

@@ -0,0 +1,13 @@
+{{- if .Values.serviceAccount.create -}}
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: {{ include "nextcloud-mcp-server.serviceAccountName" . }}
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+  {{- with .Values.serviceAccount.annotations }}
+  annotations:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+automountServiceAccountToken: {{ .Values.serviceAccount.automount }}
+{{- end }}

charts/nextcloud-mcp-server/templates/servicemonitor.yaml

@@ -0,0 +1,32 @@
+{{- if and .Values.observability.metrics.enabled .Values.serviceMonitor.enabled }}
+apiVersion: monitoring.coreos.com/v1
+kind: ServiceMonitor
+metadata:
+  name: {{ include "nextcloud-mcp-server.fullname" . }}
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+    {{- with .Values.serviceMonitor.labels }}
+    {{- toYaml . | nindent 4 }}
+    {{- end }}
+spec:
+  selector:
+    matchLabels:
+      {{- include "nextcloud-mcp-server.selectorLabels" . | nindent 6 }}
+  endpoints:
+    - port: metrics
+      path: {{ .Values.observability.metrics.path }}
+      interval: {{ .Values.serviceMonitor.interval }}
+      scrapeTimeout: {{ .Values.serviceMonitor.scrapeTimeout }}
+      scheme: http
+      relabelings:
+        # Add namespace label
+        - sourceLabels: [__meta_kubernetes_namespace]
+          targetLabel: namespace
+        # Add pod label
+        - sourceLabels: [__meta_kubernetes_pod_name]
+          targetLabel: pod
+        # Add service label
+        - sourceLabels: [__meta_kubernetes_service_name]
+          targetLabel: service
+{{- end }}

charts/nextcloud-mcp-server/values.yaml

@@ -0,0 +1,553 @@
+# Default values for nextcloud-mcp-server
+# This is a YAML-formatted file.
+# Declare variables to be passed into your templates.
+
+# Number of replicas
+replicaCount: 1
+
+image:
+  repository: ghcr.io/cbcoutinho/nextcloud-mcp-server
+  pullPolicy: IfNotPresent
+  # Image tag is automatically set to chart appVersion
+
+imagePullSecrets: []
+nameOverride: ""
+fullnameOverride: ""
+
+# Nextcloud connection settings
+nextcloud:
+  # URL of your Nextcloud instance (required)
+  # Example: https://cloud.example.com
+  host: ""
+
+  # MCP server URL for OAuth callbacks (OAuth mode only)
+  # If not specified, will be constructed from ingress.hosts[0] if ingress is enabled,
+  # or defaults to http://localhost:8000 (suitable for port-forward setups)
+  # Example: https://mcp.example.com
+  mcpServerUrl: ""
+
+  # Public issuer URL for browser-accessible OAuth authorization endpoints (OAuth mode only)
+  # ONLY used to make authorization endpoints accessible to users' browsers
+  # All server-to-server communication (token endpoint, JWKS, introspection, userinfo)
+  # uses URLs from OIDC discovery without any rewriting
+  #
+  # Use case: When MCP server accesses Nextcloud at one URL but browsers need a different
+  # public URL for OAuth login (e.g., server uses internal DNS, browsers use public domain)
+  #
+  # If not specified, defaults to nextcloud.host (works when MCP server and browsers
+  # both access Nextcloud at the same URL)
+  # Example: https://cloud.example.com
+  publicIssuerUrl: ""
+
+# Authentication configuration
+# Choose one mode: "basic", "multi-user-basic", "oauth", or "login-flow"
+auth:
+  # Authentication mode: "basic", "multi-user-basic", "oauth", or "login-flow"
+  # basic: Single-user with username/password (recommended for personal use)
+  # multi-user-basic: Multi-user with BasicAuth pass-through (credentials in request headers)
+  # oauth: Uses OAuth2/OIDC (experimental, requires patches)
+  # login-flow: Multi-user via Nextcloud Login Flow v2 (experimental, ADR-022)
+  mode: basic
+
+  # Basic authentication settings (single-user mode)
+  basic:
+    # Nextcloud username (ignored if existingSecret is set)
+    username: ""
+    # Nextcloud password or app password (recommended) (ignored if existingSecret is set)
+    password: ""
+    # Use existing secret instead of creating one
+    # If set, username and password above are ignored
+    # Secret must contain keys specified in usernameKey and passwordKey
+    # Example:
+    #   kubectl create secret generic my-nextcloud-creds \
+    #     --from-literal=username=myuser \
+    #     --from-literal=password=mypassword
+    existingSecret: ""
+    # Keys in the existing secret
+    usernameKey: "username"
+    passwordKey: "password"
+
+  # Multi-user BasicAuth settings (pass-through mode)
+  # Users provide credentials in request headers (Authorization: Basic ...)
+  # Server optionally stores app passwords for background operations
+  multiUserBasic:
+    # Enable offline access (background operations using app passwords via Astrolabe)
+    # When enabled, requires token encryption key. OAuth client credentials are optional (uses DCR if not provided)
+    enableOfflineAccess: false
+    # Token encryption key (required if enableOfflineAccess: true, ignored if existingSecret is set)
+    # Generate with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+    tokenEncryptionKey: ""
+    # Token storage database path
+    tokenStorageDb: "/app/data/tokens.db"
+    # OAuth client credentials (optional - uses Dynamic Client Registration if not provided)
+    # Only needed if enableOfflineAccess: true
+    clientId: ""
+    clientSecret: ""
+    # OAuth scopes to request (space-separated)
+    scopes: "openid profile email offline_access notes:read notes:write calendar:read calendar:write contacts:read contacts:write cookbook:read cookbook:write deck:read deck:write tables:read tables:write files:read files:write sharing:read sharing:write todo:read todo:write"
+    # Use existing secret for multi-user basic auth credentials
+    # If set, tokenEncryptionKey, clientId, and clientSecret above are ignored
+    # Secret should contain keys specified in the *Key fields below
+    # Example:
+    #   kubectl create secret generic my-multiuser-creds \
+    #     --from-literal=token_encryption_key=ESF1BvEQ... \
+    #     --from-literal=client_id=my-client-id \
+    #     --from-literal=client_secret=my-client-secret
+    existingSecret: ""
+    # Keys in the existing secret
+    tokenEncryptionKeyKey: "token_encryption_key"
+    clientIdKey: "client_id"
+    clientSecretKey: "client_secret"
+    # Persistent storage for token database
+    persistence:
+      enabled: true
+      # Storage class (leave empty for default)
+      storageClass: ""
+      accessMode: ReadWriteOnce
+      size: 100Mi
+      # Use existing PVC
+      existingClaim: ""
+
+  # OAuth2/OIDC settings (experimental)
+  oauth:
+    # OAuth token type: "jwt" or "opaque"
+    tokenType: "jwt"
+    # Pre-registered OAuth client ID (optional, ignored if existingSecret is set)
+    # If not provided and no existingSecret, will use Dynamic Client Registration (DCR)
+    clientId: ""
+    # Pre-registered OAuth client secret (optional, ignored if existingSecret is set)
+    clientSecret: ""
+    # OAuth scopes to request (space-separated)
+    scopes: "openid profile email notes:read notes:write calendar:read calendar:write contacts:read contacts:write cookbook:read cookbook:write deck:read deck:write tables:read tables:write files:read files:write sharing:read sharing:write todo:read todo:write"
+    # Use existing secret for OAuth client credentials
+    # If set, clientId and clientSecret above are ignored
+    # Secret must contain keys specified in clientIdKey and clientSecretKey
+    # Example:
+    #   kubectl create secret generic my-oauth-creds \
+    #     --from-literal=clientId=my-client-id \
+    #     --from-literal=clientSecret=my-client-secret
+    existingSecret: ""
+    # Keys in the existing secret
+    clientIdKey: "clientId"
+    clientSecretKey: "clientSecret"
+    # Persistent storage for OAuth client credentials
+    persistence:
+      enabled: true
+      # Storage class (leave empty for default)
+      storageClass: ""
+      accessMode: ReadWriteOnce
+      size: 100Mi
+      # Use existing PVC
+      existingClaim: ""
+
+  # Login Flow v2 settings (experimental, ADR-022)
+  # Uses Nextcloud's native Login Flow v2 to obtain app passwords per user.
+  # No OAuth patches required — works with stock Nextcloud.
+  # See: docs/ADR-022-deployment-mode-consolidation.md
+  loginFlow:
+    # Token encryption key (required, ignored if existingSecret is set)
+    # Generate with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+    tokenEncryptionKey: ""
+    # Token storage database path
+    tokenStorageDb: "/app/data/tokens.db"
+    # Use existing secret instead of creating one
+    existingSecret: ""
+    # Key in the existing secret
+    tokenEncryptionKeyKey: "token_encryption_key"
+
+# Data Storage Configuration
+# Persistent volume for /app/data directory
+# Used for: token databases, qdrant persistent storage, and any app data
+# When disabled, uses emptyDir (non-persistent, but still writable)
+dataStorage:
+  # Enable persistent storage for /app/data
+  # Set to true when using:
+  # - Multi-user basic auth with offline access (stores tokens.db)
+  # - Login flow mode (stores app passwords in tokens.db)
+  # - Qdrant persistent mode (stores vector database)
+  # - Any feature requiring persistent app data
+  # Set to false for basic auth without persistence (uses emptyDir)
+  enabled: false
+  # Storage class (leave empty for default)
+  storageClass: ""
+  accessMode: ReadWriteOnce
+  # Size for data storage (should accommodate tokens.db and/or qdrant data)
+  # Recommended: 1Gi minimum, 5Gi for production with qdrant
+  size: 1Gi
+  # Use existing PVC
+  existingClaim: ""
+
+# MCP server configuration
+mcp:
+  # Transport mode (default: streamable-http for SSE)
+  transport: "streamable-http"
+  # Port for MCP server (both basic auth and OAuth modes)
+  port: 8000
+  # Additional command-line arguments to pass to nextcloud-mcp-server
+  # Example: ["--log-level", "debug", "--enable-app", "notes"]
+  extraArgs: []
+
+# Document processing configuration (optional)
+documentProcessing:
+  # Enable document processing (PDF, DOCX, images, etc.)
+  enabled: false
+  # Default processor: unstructured, tesseract, or custom
+  defaultProcessor: "unstructured"
+  # Progress reporting interval in seconds
+  progressInterval: 10
+
+  # Unstructured.io processor
+  unstructured:
+    enabled: false
+    # Unstructured API endpoint
+    apiUrl: "http://unstructured:8000"
+    # Request timeout in seconds
+    timeout: 120
+    # Parsing strategy: auto, fast, or hi_res
+    strategy: "auto"
+    # OCR languages (comma-separated ISO 639-3 codes)
+    languages: "eng,deu"
+
+  # Tesseract processor (local OCR)
+  tesseract:
+    enabled: false
+    # Path to tesseract executable (optional, auto-detected if in PATH)
+    cmd: ""
+    # OCR language (e.g., eng, deu, eng+deu for multiple)
+    lang: "eng"
+
+  # Custom processor
+  custom:
+    enabled: false
+    # Unique name for your processor
+    name: "my_ocr"
+    # Custom processor API endpoint
+    url: ""
+    # Optional API key for authentication
+    apiKey: ""
+    # Request timeout in seconds
+    timeout: 60
+    # Comma-separated MIME types your processor supports
+    types: "application/pdf,image/jpeg,image/png"
+
+serviceAccount:
+  # Specifies whether a service account should be created
+  create: true
+  # Automatically mount a ServiceAccount's API credentials?
+  automount: true
+  # Annotations to add to the service account
+  annotations: {}
+  # The name of the service account to use.
+  # If not set and create is true, a name is generated using the fullname template
+  name: ""
+
+podAnnotations: {}
+podLabels: {}
+
+podSecurityContext:
+  fsGroup: 2000
+
+securityContext:
+  capabilities:
+    drop:
+    - ALL
+  readOnlyRootFilesystem: true
+  runAsNonRoot: true
+  runAsUser: 1000
+
+# Observability Configuration
+observability:
+  # Prometheus metrics
+  metrics:
+    enabled: true
+    port: 9090
+    path: /metrics
+
+  # OpenTelemetry tracing
+  tracing:
+    enabled: false
+    endpoint: ""  # e.g., "http://opentelemetry-collector:4317"
+    serviceName: "nextcloud-mcp-server"
+    samplingRate: 1.0
+
+  # Logging configuration
+  logging:
+    format: json  # "json" or "text"
+    level: INFO
+    includeTraceContext: true
+
+# Prometheus ServiceMonitor (requires Prometheus Operator)
+serviceMonitor:
+  enabled: false
+  interval: 30s
+  scrapeTimeout: 10s
+  labels: {}
+  # Additional labels for ServiceMonitor (e.g., for Prometheus selector)
+  # Example: { prometheus: kube-prometheus }
+
+# Prometheus alert rules (requires Prometheus Operator)
+prometheusRule:
+  enabled: false
+  labels: {}
+  # Additional labels for PrometheusRule (e.g., for Prometheus selector)
+  # Example: { prometheus: kube-prometheus }
+
+# Grafana dashboards (requires Grafana with sidecar enabled)
+dashboards:
+  # Enable automatic dashboard provisioning via ConfigMap
+  enabled: false
+  # Grafana folder name where dashboards will be imported
+  # The grafana-sidecar looks for ConfigMaps with label "grafana_dashboard: 1"
+  # and reads the folder name from annotation "grafana_folder" (supports spaces)
+  grafanaFolder: "Nextcloud MCP"
+  # Additional labels for dashboard ConfigMap
+  # These will be added alongside the required "grafana_dashboard: 1" label
+  labels: {}
+  # Additional annotations for dashboard ConfigMap
+  annotations: {}
+
+service:
+  type: ClusterIP
+  port: 8000
+  annotations: {}
+
+ingress:
+  enabled: false
+  className: ""
+  annotations: {}
+    # kubernetes.io/ingress.class: nginx
+    # kubernetes.io/tls-acme: "true"
+    # cert-manager.io/cluster-issuer: letsencrypt-prod
+  hosts:
+    - host: mcp.example.com
+      paths:
+        - path: /
+          pathType: Prefix
+  tls: []
+  #  - secretName: nextcloud-mcp-tls
+  #    hosts:
+  #      - mcp.example.com
+
+resources:
+  # We recommend setting resource requests and limits
+  limits:
+    cpu: 1000m
+    memory: 512Mi
+  requests:
+    cpu: 100m
+    memory: 128Mi
+
+# Liveness probe configuration
+# Checks if the application process is running
+livenessProbe:
+  httpGet:
+    path: /health/live
+    port: http
+    scheme: HTTP
+  initialDelaySeconds: 30
+  periodSeconds: 10
+  timeoutSeconds: 5
+  failureThreshold: 3
+
+# Readiness probe configuration
+# Checks if the application is ready to serve traffic
+readinessProbe:
+  httpGet:
+    path: /health/ready
+    port: http
+    scheme: HTTP
+  initialDelaySeconds: 10
+  periodSeconds: 5
+  timeoutSeconds: 3
+  failureThreshold: 3
+
+# Autoscaling configuration
+autoscaling:
+  enabled: false
+  minReplicas: 1
+  maxReplicas: 10
+  targetCPUUtilizationPercentage: 80
+  # targetMemoryUtilizationPercentage: 80
+
+# Additional volumes on the output Deployment definition.
+volumes: []
+# - name: foo
+#   secret:
+#     secretName: mysecret
+#     optional: false
+
+# Additional volumeMounts on the output Deployment definition.
+volumeMounts: []
+# - name: foo
+#   mountPath: "/etc/foo"
+#   readOnly: true
+
+nodeSelector: {}
+
+tolerations: []
+
+affinity: {}
+
+# Init containers
+initContainers: []
+
+# Additional environment variables
+extraEnv: []
+# - name: CUSTOM_VAR
+#   value: "custom_value"
+
+# Additional environment variables from ConfigMaps or Secrets
+extraEnvFrom: []
+# - configMapRef:
+#     name: my-configmap
+# - secretRef:
+#     name: my-secret
+
+# Semantic Search Configuration
+# Enable semantic search with BM25 hybrid search and background synchronization
+# of Nextcloud content into vector database
+semanticSearch:
+  # Enable semantic search and background vector synchronization
+  enabled: false
+  # Scan interval in seconds (how often to check for changes)
+  scanInterval: 3600
+  # Number of concurrent processor workers
+  processorWorkers: 3
+  # Maximum queue size for documents pending indexing
+  queueMaxSize: 10000
+
+# Document Chunking Configuration
+# Controls how documents are split into chunks before embedding
+# Only relevant when semanticSearch.enabled is true
+documentChunking:
+  # Number of words per chunk (default: 512)
+  # Smaller chunks (256-384): Better for precise searches, more chunks to store
+  # Medium chunks (512-768): Balanced approach (recommended for most use cases)
+  # Larger chunks (1024+): Better for context, less precise matching
+  chunkSize: 512
+  # Number of overlapping words between chunks (default: 50)
+  # Recommended: 10-20% of chunkSize for context preservation across boundaries
+  # Must be less than chunkSize
+  chunkOverlap: 50
+
+# Qdrant Vector Database Configuration
+# Three deployment modes available:
+# 1. Local In-Memory: Fast, ephemeral, zero-config (mode: "memory")
+# 2. Local Persistent: File-based, survives restarts (mode: "persistent")
+# 3. Network: Dedicated Qdrant service, production-ready (mode: "network")
+qdrant:
+  # Qdrant mode: "memory", "persistent", or "network"
+  # - memory: In-memory storage (:memory:) - default, zero config, data lost on restart
+  # - persistent: Local file storage - data persists across restarts, suitable for small/medium deployments
+  # - network: Dedicated Qdrant service (see networkMode below)
+  mode: "memory"
+
+  # Collection name for vector data
+  collection: "nextcloud_content"
+
+  # Local persistent mode configuration (only used when mode: "persistent")
+  localPersistence:
+    # Enable persistent volume for local Qdrant data
+    enabled: true
+    # Storage class (leave empty for default)
+    storageClass: ""
+    accessMode: ReadWriteOnce
+    # Size for local Qdrant storage
+    size: 1Gi
+    # Path where Qdrant data is stored (relative to /app/data)
+    # Default: /app/data/qdrant
+    dataPath: "/app/data/qdrant"
+    # Use existing PVC
+    existingClaim: ""
+
+  # Network mode configuration (only used when mode: "network")
+  networkMode:
+    # Deploy Qdrant as a subchart (if true) or use external Qdrant (if false)
+    deploySubchart: false
+    # External Qdrant URL (used when deploySubchart: false)
+    # Example: "http://qdrant.default.svc.cluster.local:6333"
+    externalUrl: ""
+    # Optional API key for Qdrant authentication
+    apiKey: ""
+    # Use existing secret for API key
+    existingSecret: ""
+    secretKey: "api-key"
+
+  # Qdrant subchart configuration (only used when mode: "network" and networkMode.deploySubchart: true)
+  # All values are passed through to the qdrant/qdrant chart.
+  # See https://github.com/qdrant/qdrant-helm for full configuration options.
+  subchart:
+    # Number of Qdrant replicas
+    replicaCount: 1
+    image:
+      # Qdrant version
+      tag: v1.12.5
+    config:
+      cluster:
+        # Enable distributed cluster mode
+        enabled: false
+    # Persistent storage for vector data
+    persistence:
+      size: 10Gi
+      storageClass: ""
+      accessModes:
+        - ReadWriteOnce
+    # Resource limits and requests
+    resources:
+      requests:
+        cpu: 200m
+        memory: 512Mi
+      limits:
+        cpu: 1000m
+        memory: 2Gi
+
+# Ollama Embedding Service
+# Deployed as a subchart when enabled. All values are passed through to the ollama/ollama chart.
+# See https://github.com/otwld/ollama-helm for full configuration options.
+ollama:
+  # Enable Ollama subchart deployment
+  # Set to true to deploy Ollama as a subchart, or false to use an external Ollama instance
+  enabled: false
+  # External Ollama URL (use this if you have Ollama deployed elsewhere)
+  # When set, use enabled: false to prevent deploying the subchart
+  # Example: "http://ollama.default.svc.cluster.local:11434"
+  url: ""
+  # Embedding model to use
+  embeddingModel: "nomic-embed-text"
+  # Verify SSL certificates when connecting to Ollama
+  verifySsl: true
+  # Number of Ollama replicas (only used when subchart is deployed)
+  replicaCount: 1
+  # Ollama configuration (only used when subchart is deployed)
+  ollama:
+    # Models to automatically pull on startup
+    models:
+      pull:
+        - nomic-embed-text
+  # Persistent storage for models (only used when subchart is deployed)
+  persistentVolume:
+    enabled: true
+    size: 20Gi
+    storageClass: ""
+  # Resource limits and requests (only used when subchart is deployed)
+  resources:
+    requests:
+      cpu: 500m
+      memory: 1Gi
+    limits:
+      cpu: 2000m
+      memory: 4Gi
+
+# OpenAI-compatible Embedding Provider
+# Alternative to Ollama for embedding generation. Can be used with OpenAI or any compatible API.
+openai:
+  # Enable OpenAI embedding provider
+  enabled: false
+  # OpenAI API key (only used if existingSecret is not set)
+  apiKey: ""
+  # Name of existing secret containing the API key
+  existingSecret: ""
+  # Key in the secret that contains the API key
+  secretKey: "api-key"
+  # Optional custom API endpoint (e.g., for Azure OpenAI or local compatible services)
+  baseUrl: ""

docker-compose.ci.yml

@@ -0,0 +1,25 @@
+# CI-specific overrides for RAG evaluation pipeline
+# This file is used by the rag-evaluation.yml workflow to configure the MCP
+# container with OpenAI/GitHub Models API for vector embeddings.
+#
+# Usage:
+#   docker compose -f docker-compose.yml -f docker-compose.ci.yml up
+#
+# Environment variables (set in CI workflow):
+#   OPENAI_API_KEY - API key for embeddings (GitHub Models uses GITHUB_TOKEN)
+#   OPENAI_BASE_URL - API endpoint (e.g., https://models.github.ai/inference)
+#   OPENAI_EMBEDDING_MODEL - Model name (e.g., openai/text-embedding-3-small)
+#   OPENAI_GENERATION_MODEL - Model name for generation (e.g., openai/gpt-4o-mini)
+
+services:
+  mcp:
+    environment:
+      # OpenAI provider configuration (required for CI vector sync)
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+      - OPENAI_BASE_URL=${OPENAI_BASE_URL:-https://models.github.ai/inference}
+      - OPENAI_EMBEDDING_MODEL=${OPENAI_EMBEDDING_MODEL:-openai/text-embedding-3-small}
+      - OPENAI_GENERATION_MODEL=${OPENAI_GENERATION_MODEL:-openai/gpt-4o-mini}
+      # Faster sync for CI
+      - VECTOR_SYNC_SCAN_INTERVAL=${VECTOR_SYNC_SCAN_INTERVAL:-5}
+      # Enable document processing for PDF parsing
+      - ENABLE_DOCUMENT_PROCESSING=true

docker-compose.yml

@@ -3,11 +3,13 @@ services:
   # https://hub.docker.com/_/mariadb
   db:
     # Note: Check the recommend version here: https://docs.nextcloud.com/server/latest/admin_manual/installation/system_requirements.html#server
-    image: docker.io/library/mariadb:lts@sha256:ae6119716edac6998ae85508431b3d2e666530ddf4e94c61a10710caec9b0f71
+    image: docker.io/library/mariadb:lts@sha256:8164f184d16c30e2f159e30518113667b796306dff0fe558876ab1ff521a682f
     restart: always
     command: --transaction-isolation=READ-COMMITTED
     volumes:
       - db:/var/lib/mysql
+    ports:
+      - 127.0.0.1:3306:3306
     environment:
       - MYSQL_ROOT_PASSWORD=password
       - MYSQL_PASSWORD=password
@@ -17,20 +19,25 @@ services:
   # Note: Redis is an external service. You can find more information about the configuration here:
   # https://hub.docker.com/_/redis
   redis:
-    image: docker.io/library/redis:alpine@sha256:59b6e694653476de2c992937ebe1c64182af4728e54bb49e9b7a6c26614d8933
+    image: docker.io/library/redis:alpine@sha256:2afba59292f25f5d1af200496db41bea2c6c816b059f57ae74703a50a03a27d0
     restart: always
 
   app:
-    image: docker.io/library/nextcloud:32.0.0@sha256:3e70e4dfe882ef44738fdc30d9896fb07c12febb27c4a1177e3d63dc0004a0b4
+    image: ${NEXTCLOUD_IMAGE:-docker.io/library/nextcloud:32.0.6@sha256:5c4e09f72f096cd68379a8ae69f71e61d13da5a07430fc4a17c702a14e6a4267}
     restart: always
     ports:
-      - 0.0.0.0:8080:80
+      - 127.0.0.1:8080:80
     depends_on:
       - redis
       - db
     volumes:
       - nextcloud:/var/www/html
-      - ./app-hooks/post-installation:/docker-entrypoint-hooks.d/post-installation:ro
+      - ./app-hooks:/docker-entrypoint-hooks.d:ro
+      # Mount OIDC development directory outside /var/www/html to avoid rsync conflicts
+      # The post-installation hook will register /opt/apps as an additional app directory
+      #- ./third_party:/opt/apps:ro
+      - ./third_party/astrolabe:/opt/apps/astrolabe:ro
+      #- ./third_party/oidc:/opt/apps/oidc:ro  # Use app store version; dev mount lacks vendor/
     environment:
       - NEXTCLOUD_TRUSTED_DOMAINS=app
       - NEXTCLOUD_ADMIN_USER=admin
@@ -40,44 +47,330 @@ services:
       - MYSQL_USER=nextcloud
       - MYSQL_HOST=db
       - REDIS_HOST=redis
+      - MCP_SERVER_URL=${MCP_SERVER_URL:-}
+    healthcheck:
+      test: ["CMD-SHELL", "curl -Ss http://localhost/status.php | grep '\"installed\":true' || exit 1"]
+      interval: 10s
+      timeout: 30s
+      retries: 30
 
   recipes:
-    image: docker.io/library/nginx:alpine@sha256:61e01287e546aac28a3f56839c136b31f590273f3b41187a36f46f6a03bbfe22
+    image: docker.io/library/nginx:alpine@sha256:5878d06ae4c83d73285438255f705bb3f9a736f41cd24876ed25bb33faf76c7d
     restart: always
     volumes:
       - ./tests/fixtures/test_recipe.html:/usr/share/nginx/html/test_recipe.html:ro
       - ./tests/fixtures/nginx.conf:/etc/nginx/nginx.conf:ro
 
+  unstructured:
+    image: downloads.unstructured.io/unstructured-io/unstructured-api:latest@sha256:ba6cb073af079c498e9466a5a9152ba4b6c9cad12efeeaf053ba383023d5db08
+    restart: always
+    ports:
+      - 127.0.0.1:8002:8000
+    # Unstructured API runs on port 8000 internally
+    # We expose it on 8002 externally to avoid conflict
+    profiles:
+      - unstructured
+
   mcp:
     build: .
-    command: ["--transport", "streamable-http"]
     restart: always
+    command: ["--transport", "streamable-http"]
     depends_on:
-      - app
+      app:
+        condition: service_healthy
     ports:
       - 127.0.0.1:8000:8000
+      - 127.0.0.1:9090:9090
+    volumes:
+      - mcp-data:/app/data
     environment:
       - NEXTCLOUD_HOST=http://app:80
       - NEXTCLOUD_USERNAME=admin
       - NEXTCLOUD_PASSWORD=admin
+      - NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8080
+
+      # Semantic search configuration (ADR-007, ADR-021)
+      #- ENABLE_SEMANTIC_SEARCH=true
+      - VECTOR_SYNC_SCAN_INTERVAL=60
+      - VECTOR_SYNC_PROCESSOR_WORKERS=1
+
+      #- LOG_FORMAT=json
+
+      # Qdrant configuration (three modes):
+      # 1. Network mode: Set QDRANT_URL=http://qdrant:6333 (requires qdrant service)
+      # 2. In-memory mode: Set QDRANT_LOCATION=:memory: (default if nothing set)
+      # 3. Persistent local: Set QDRANT_LOCATION=/app/data/qdrant (stored in mcp-data volume)
+      #- QDRANT_LOCATION=/app/data/qdrant  # In-memory mode used if not set
+      #- QDRANT_URL=http://qdrant:6333  # Uncomment for network mode
+      #- QDRANT_API_KEY=${QDRANT_API_KEY:-my_secret_api_key}  # Only for network mode
+
+      # Observability
+      #- OTEL_SERVICE_NAME=nextcloud-mcp-docker-compose
+      #- OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
+
+      # Collection naming: Auto-generated as {deployment-id}-{model-name}
+      # - Deployment ID: OTEL_SERVICE_NAME (if set) or hostname (fallback)
+      # - Model name: OLLAMA_EMBEDDING_MODEL
+      # - Example: "nextcloud-mcp-server-nomic-embed-text"
+      # - Changing models creates new collection (requires re-embedding)
+      # - Set QDRANT_COLLECTION to override auto-generation:
+      #- QDRANT_COLLECTION=nextcloud_content
+
+      # Ollama configuration (optional - uses SimpleEmbeddingProvider if not set)
+      # - OLLAMA_BASE_URL=http://ollama:11434
+      # - OLLAMA_EMBEDDING_MODEL=nomic-embed-text  # Changing this creates new collection
+      # - OLLAMA_VERIFY_SSL=false
+
+      # Document chunking configuration (for vector embeddings)
+      # Tune these based on your embedding model and content type
+      # - DOCUMENT_CHUNK_SIZE=512      # Words per chunk (default: 512)
+      # - DOCUMENT_CHUNK_OVERLAP=50    # Overlapping words (default: 50, recommended: 10-20% of chunk size)
+    profiles:
+      - single-user
+
+  mcp-multi-user-basic:
+    build: .
+    restart: always
+    command: ["--transport", "streamable-http"]
+    depends_on:
+      app:
+        condition: service_healthy
+    ports:
+      - 127.0.0.1:8003:8000
+    environment:
+      # Multi-user BasicAuth pass-through mode (ADR-020)
+      - NEXTCLOUD_HOST=http://app:80
+      - NEXTCLOUD_MCP_SERVER_URL=http://localhost:8003
+      - NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8080
+      - ENABLE_MULTI_USER_BASIC_AUTH=true
+      - ENABLE_BACKGROUND_OPERATIONS=true
+
+      # Token storage (required for middleware initialization)
+      # DEVELOPMENT ONLY - generate a fresh key for production:
+      # python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+      - TOKEN_ENCRYPTION_KEY=fqqI4G51yBCOcu9cvv6wCUJB7sf_CK2za5ClC6b86yY=
+      - TOKEN_STORAGE_DB=/app/data/tokens.db
+
+      - ENABLE_SEMANTIC_SEARCH=true
+      - VECTOR_SYNC_SCAN_INTERVAL=60
+      - VECTOR_SYNC_PROCESSOR_WORKERS=1
+
+      # OAuth credentials for background sync (optional - uses DCR if not provided)
+      # Uncomment to avoid DCR:
+      # - NEXTCLOUD_OIDC_CLIENT_ID=your_client_id
+      # - NEXTCLOUD_OIDC_CLIENT_SECRET=your_client_secret
+
+      # NO admin credentials - credentials come from client Authorization header
+    volumes:
+      - multi-user-basic-data:/app/data
+    profiles:
+      - multi-user-basic
 
   mcp-oauth:
     build: .
-    command: ["--transport", "streamable-http", "--oauth", "--port", "8001"]
+    command: ["--transport", "streamable-http", "--oauth", "--port", "8001", "--oauth-token-type", "jwt"]
     restart: always
     depends_on:
-      - app
+      app:
+        condition: service_healthy
     ports:
       - 127.0.0.1:8001:8001
     environment:
+      # Generic OIDC configuration (integrated mode - Nextcloud OIDC app)
+      # OIDC_DISCOVERY_URL not set - defaults to NEXTCLOUD_HOST/.well-known/openid-configuration
+      # OIDC_CLIENT_ID not set - uses Dynamic Client Registration (DCR)
       - NEXTCLOUD_HOST=http://app:80
-      - NEXTCLOUD_MCP_SERVER_URL=http://127.0.0.1:8001
-      - NEXTCLOUD_PUBLIC_ISSUER_URL=http://127.0.0.1:8080
-      # No USERNAME/PASSWORD - will use OAuth
+      - NEXTCLOUD_MCP_SERVER_URL=http://localhost:8001
+      - NEXTCLOUD_RESOURCE_URI=http://localhost:8080  # ADR-005: Nextcloud resource identifier for audience validation
+      - NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8080
+      - NEXTCLOUD_OIDC_SCOPES=openid profile email notes:read notes:write calendar:read calendar:write contacts:read contacts:write cookbook:read cookbook:write deck:read deck:write tables:read tables:write files:read files:write sharing:read sharing:write todo:read todo:write
+
+      # Refresh token storage (ADR-002 Tier 1)
+      - ENABLE_BACKGROUND_OPERATIONS=true
+      - TOKEN_ENCRYPTION_KEY=Qh60VwZQsM7CLtSMunzC0gIGPBT948S6VSawUkODtvU=
+      - TOKEN_STORAGE_DB=/app/data/tokens.db
+
+      # ADR-005: Multi-audience mode (default - ENABLE_TOKEN_EXCHANGE=false)
+      # Tokens must contain BOTH MCP and Nextcloud audiences
+      # No token exchange needed - tokens work for both MCP auth and Nextcloud APIs
+
+      # Semantic search configuration (ADR-007, ADR-021)
+      - ENABLE_SEMANTIC_SEARCH=true
+      - VECTOR_SYNC_SCAN_INTERVAL=60
+      - VECTOR_SYNC_PROCESSOR_WORKERS=1
+
+      # Qdrant configuration - persistent local storage
+      - QDRANT_LOCATION=/app/data/qdrant
+
+      # Embedding provider for vector sync (use Simple provider as fallback)
+      # Ollama not available in CI/test environments
+      # - OLLAMA_BASE_URL=http://ollama:11434
+      # - OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+
+      # NO admin credentials - using OAuth with Dynamic Client Registration (DCR)
+      # Client credentials registered via RFC 7591 and stored in volume
+      # JWT token type is used for testing (faster validation, scopes embedded in token)
     volumes:
       - oauth-client-storage:/app/.oauth
+      - oauth-tokens:/app/data
+    profiles:
+      - oauth
+
+  keycloak:
+    image: quay.io/keycloak/keycloak:26.5.4@sha256:ae8efb0d218d8921334b03a2dbee7069a0b868240691c50a3ffc9f42fabba8b4
+    command:
+      - "start-dev"
+      - "--import-realm"
+      - "--hostname=http://localhost:8888"
+      - "--hostname-strict=false"
+      - "--hostname-backchannel-dynamic=true"
+      - "--features=preview"  # Enable Legacy V1 token exchange (supports both Standard V2 and Legacy V1)
+    ports:
+      - 127.0.0.1:8888:8080
+    environment:
+      - KC_BOOTSTRAP_ADMIN_USERNAME=admin
+      - KC_BOOTSTRAP_ADMIN_PASSWORD=admin
+    volumes:
+      - ./keycloak/realm-export.json:/opt/keycloak/data/import/realm.json:ro
+    healthcheck:
+      test: ["CMD-SHELL", "exec 3<>/dev/tcp/localhost/8080 && echo -e 'GET /realms/nextcloud-mcp HTTP/1.1\\r\\nHost: localhost\\r\\nConnection: close\\r\\n\\r\\n' >&3 && cat <&3 | grep -q 'HTTP/1.1 200'"]
+      interval: 10s
+      timeout: 5s
+      retries: 30
+    profiles:
+      - keycloak
+
+  mcp-keycloak:
+    build: .
+    command: ["--transport", "streamable-http", "--oauth", "--port", "8002"]
+    restart: always
+    depends_on:
+      keycloak:
+        condition: service_healthy
+      app:
+        condition: service_started
+    ports:
+      - 127.0.0.1:8002:8002
+    environment:
+      # Generic OIDC configuration (external IdP mode - Keycloak)
+      # Provider auto-detected from OIDC_DISCOVERY_URL issuer
+      # Using internal Docker hostname for discovery to get consistent issuer
+      - OIDC_DISCOVERY_URL=http://keycloak:8080/realms/nextcloud-mcp/.well-known/openid-configuration
+      - NEXTCLOUD_OIDC_CLIENT_ID=nextcloud-mcp-server
+      - NEXTCLOUD_OIDC_CLIENT_SECRET=mcp-secret-change-in-production
+      - OIDC_JWKS_URI=http://keycloak:8080/realms/nextcloud-mcp/protocol/openid-connect/certs
+
+      # Nextcloud API endpoint (for accessing APIs with validated token)
+      - NEXTCLOUD_HOST=http://app:80
+      - NEXTCLOUD_MCP_SERVER_URL=http://localhost:8002
+      - NEXTCLOUD_RESOURCE_URI=nextcloud  # ADR-005: Keycloak uses client IDs as audiences, not URLs
+      - NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8888/realms/nextcloud-mcp
+
+      # Refresh token storage (ADR-002 Tier 1 & 2)
+      - ENABLE_BACKGROUND_OPERATIONS=true
+      - TOKEN_ENCRYPTION_KEY=ESF1BvEQdGYsCluwMx9Cxvw3uh5pFowPH7Rg_nIliyo=
+      - TOKEN_STORAGE_DB=/app/data/tokens.db
+
+      # ADR-005: Token exchange mode (RFC 8693)
+      # Exchange MCP tokens (aud: nextcloud-mcp-server) for Nextcloud tokens (aud: http://localhost:8080)
+      # Provides strict audience separation between MCP session and Nextcloud API access
+      - ENABLE_TOKEN_EXCHANGE=true
+      - TOKEN_EXCHANGE_CACHE_TTL=300  # Cache exchanged tokens for 5 minutes (default)
+
+      # OAuth scopes (optional - uses defaults if not specified)
+      - NEXTCLOUD_OIDC_SCOPES=openid profile email offline_access notes:read notes:write calendar:read calendar:write contacts:read contacts:write cookbook:read cookbook:write deck:read deck:write tables:read tables:write files:read files:write sharing:read sharing:write todo:read todo:write
+
+      # NO admin credentials - using external IdP OAuth only!
+    volumes:
+      - keycloak-tokens:/app/data
+      - keycloak-oauth-storage:/app/.oauth
+    profiles:
+      - keycloak
+
+  # Login Flow v2 mode (ADR-022)
+  # Test with: docker compose --profile login-flow up --build -d
+  mcp-login-flow:
+    build: .
+    restart: always
+    # --oauth enables the OAuth/OIDC identity layer that Login Flow v2 builds on
+    # (user identity via OAuth session, Nextcloud access via app passwords)
+    command: ["--transport", "streamable-http", "--oauth", "--port", "8004"]
+    depends_on:
+      app:
+        condition: service_healthy
+    ports:
+      - 127.0.0.1:8004:8004
+    environment:
+      - NEXTCLOUD_HOST=http://app:80
+      - NEXTCLOUD_MCP_SERVER_URL=http://localhost:8004
+      - NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8080
+
+      # Login Flow v2 (ADR-022)
+      - ENABLE_LOGIN_FLOW=true
+
+      # Token storage (required for app password + session persistence)
+      # DEVELOPMENT ONLY - generate a fresh key for production:
+      # python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+      - TOKEN_ENCRYPTION_KEY=rxJvkBf7ZBjZZDL4a1sSqjhmjawhmbRMSOGfK8HDyKU=
+      - TOKEN_STORAGE_DB=/app/data/tokens.db
+
+      # Semantic search
+      - ENABLE_SEMANTIC_SEARCH=true
+      - VECTOR_SYNC_SCAN_INTERVAL=60
+      - VECTOR_SYNC_PROCESSOR_WORKERS=1
+    volumes:
+      - login-flow-data:/app/data
+      - login-flow-oauth-storage:/app/.oauth
+    profiles:
+      - login-flow
+
+  # Smithery stateless deployment mode (ADR-016)
+  # Test with: docker compose --profile smithery up smithery
+  # Then: curl http://localhost:8081/.well-known/mcp-config
+  smithery:
+    build:
+      context: .
+      dockerfile: Dockerfile.smithery
+    restart: always
+    depends_on:
+      app:
+        condition: service_healthy
+    ports:
+      - 127.0.0.1:8081:8081
+    environment:
+      - SMITHERY_DEPLOYMENT=true
+      - ENABLE_SEMANTIC_SEARCH=false
+      - PORT=8081
+    profiles:
+      - smithery
+
+  qdrant:
+    image: docker.io/qdrant/qdrant:v1.17.0@sha256:f1c7272cdac52b38c1a0e89313922d940ba50afd90d593a1605dbbc214e66ffb
+    restart: always
+    ports:
+      - 127.0.0.1:6333:6333  # REST API
+      - 127.0.0.1:6334:6334  # gRPC (optional)
+    volumes:
+      - qdrant-data:/qdrant/storage
+    environment:
+      - QDRANT__SERVICE__API_KEY=${QDRANT_API_KEY:-my_secret_api_key}
+    healthcheck:
+      test: ["CMD-SHELL", "test -f /qdrant/.qdrant-initialized"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+    profiles:
+      - qdrant
 
 volumes:
   nextcloud:
   db:
   oauth-client-storage:
+  oauth-tokens:
+  keycloak-tokens:
+  keycloak-oauth-storage:
+  login-flow-data:
+  login-flow-oauth-storage:
+  qdrant-data:
+  mcp-data:
+  multi-user-basic-data:

docs/ADR-002-vector-sync-authentication.md

@@ -0,0 +1,964 @@
+# ADR-002: Vector Database Background Sync Authentication
+
+> **⚠️ DEPRECATED**: This ADR has been superseded by [ADR-004: MCP Server as OAuth Client for Offline Access](./ADR-004-mcp-application-oauth.md).
+>
+> **Reason for Deprecation**: This ADR fundamentally misunderstood the MCP protocol's authentication architecture. The MCP server receives tokens from clients but cannot initiate OAuth flows or store refresh tokens, making the proposed solutions ineffective for true offline access. ADR-004 provides the correct architectural pattern where the MCP server acts as its own OAuth client.
+
+## Status
+~~Accepted - Tier 2 (Token Exchange with Delegation) Implemented~~
+**Superseded by ADR-004** - The token exchange implementation exists but doesn't solve the offline access problem.
+
+**Important**: Service account tokens (old Tier 1) have been rejected as they violate OAuth "act on-behalf-of" principles by creating Nextcloud user accounts for the MCP server.
+
+## Context
+
+To enable semantic search capabilities, the MCP server needs to index user content (notes, files, calendar events) into a vector database. This requires a background sync worker that:
+
+1. **Runs independently** of user requests (periodic or continuous operation)
+2. **Accesses multiple users' content** to build a comprehensive search index
+3. **Respects user permissions** - only index content users have access to
+4. **Operates in OAuth mode** - where the MCP server doesn't have traditional admin credentials
+
+### Current OAuth Architecture
+
+The MCP server currently operates in two authentication modes:
+
+1. **BasicAuth Mode**: Uses username/password credentials (typically admin account)
+2. **OAuth Mode**: Single OAuth client, multiple user tokens
+   - Users authenticate via OAuth flow
+   - Each request includes user's access token
+   - Server creates per-request `NextcloudClient` with user's bearer token
+   - No tokens are stored server-side
+
+### The Challenge
+
+Background workers need long-lived authentication to:
+- Index content continuously/periodically
+- Process multiple users' data in batch operations
+- Operate when users are not actively making requests
+
+However, in OAuth mode:
+- User access tokens are ephemeral (exist only during request)
+- MCP server doesn't store user credentials
+- Admin credentials defeat the purpose of OAuth
+
+We need an OAuth-native solution that maintains security while enabling background operations.
+
+## Decision
+
+We will implement a **tiered OAuth authentication strategy** for background operations in OAuth mode. When OAuth authentication is not configured or available, the background sync feature is not available.
+
+**Note**: This ADR applies only to **OAuth mode**. In BasicAuth mode (single-user deployments), credentials are already available via environment variables, and background operations work without additional configuration.
+
+### OAuth "Act On-Behalf-Of" Principle
+
+**Core Requirement**: The MCP server must NEVER create its own user identity in Nextcloud when operating in OAuth mode.
+
+**Valid Patterns**:
+- ✅ **Foreground operations**: Use user's access token from MCP request (currently implemented)
+- ✅ **Background operations**: Token exchange to impersonate/delegate as user (requires provider support)
+- ❌ **Service account**: Creates independent identity in Nextcloud (violates OAuth principles)
+
+**Why This Matters**:
+1. **Audit Trail**: All operations must be attributable to the actual user, not a service account
+2. **Stateless Server**: MCP server should not have persistent identity/state in Nextcloud
+3. **Security Model**: Avoid creating "admin by another name" with broad cross-user permissions
+4. **OAuth Design**: OAuth tokens represent user authorization, not server authorization
+
+**If Token Exchange Not Available**:
+- Background operations simply cannot happen in OAuth mode
+- This is correct behavior - not a limitation to work around
+- Don't create service accounts as "workaround" - this defeats OAuth's purpose
+- Use BasicAuth mode if background operations are critical to your deployment
+
+### Tier 1: Token Exchange with Impersonation (RFC 8693) ⚠️ **NOT IMPLEMENTED**
+
+**Better Security** - Requires provider support for user impersonation
+
+- Service account exchanges token to impersonate specific users
+- Each background operation runs as the target user
+- Uses `requested_subject` parameter in token exchange
+- Per-user permission enforcement at API level
+
+**Requirements**:
+- OIDC provider supports RFC 8693 token exchange
+- Provider supports user impersonation (rare - requires Legacy Keycloak V1 with preview features)
+- Service account has impersonation permissions
+
+**Status**: ⚠️ Not implemented - Keycloak Standard V2 doesn't support impersonation
+**Reference**: See `docs/oauth-impersonation-findings.md` for investigation details
+
+### Tier 2: Token Exchange with Delegation (RFC 8693) ✅ **IMPLEMENTED**
+
+**Best Security** - Requires provider support for delegation with `act` claim
+
+- Service account exchanges token on behalf of users (delegation, not impersonation)
+- Token includes `act` claim showing service account as actor
+- API sees both the user (`sub`) and actor (`act`) in token
+- Full audit trail of delegated operations
+- **Implementation**: `KeycloakOAuthClient.exchange_token_for_user()` (keycloak_oauth.py:397-495)
+- **Testing**: Manual test in `tests/manual/test_token_exchange.py`
+- **Limitation**: Keycloak doesn't support `act` claim yet - [Issue #38279](https://github.com/keycloak/keycloak/issues/38279)
+
+**Requirements**:
+- OIDC provider supports RFC 8693 token exchange
+- Provider supports delegation with `act` claim (very rare)
+- Proper token exchange permissions configured
+
+**Current Implementation**: Internal-to-internal token exchange with audience modification (without `act` claim)
+
+### ❌ Will Not Implement
+
+**1. Service Account with Independent Identity (client_credentials)**
+- **Status**: Previously proposed as Tier 1, now rejected
+- **Why Invalid**: Creates Nextcloud user account for MCP server (e.g., `service-account-nextcloud-mcp-server`)
+- **Problems**:
+  - **Violates OAuth "act on-behalf-of" principle**: Actions attributed to service account instead of real user
+  - **Breaks audit trail**: Can't determine which user initiated the action
+  - **Creates stateful server identity**: MCP server has persistent identity/data in Nextcloud
+  - **Security risk**: Service account becomes "admin by another name" with broad cross-user permissions
+  - **User provisioning side effect**: Nextcloud's `user_oidc` app auto-provisions service account as real user
+- **Code Status**: Implementation exists (`KeycloakOAuthClient.get_service_account_token()`) but marked with warnings
+- **Alternative**: If service account pattern truly needed, use BasicAuth mode instead of OAuth mode
+- **Reference**: See commit c12df98 for detailed analysis of why this approach was rejected
+
+**2. Offline Access with Refresh Tokens**
+- **MCP Protocol Architecture**: FastMCP SDK manages OAuth where MCP Client handles refresh tokens
+- **Security Model**: Refresh tokens must never be shared between client and server (OAuth best practice)
+- **Technical Impossibility**: MCP Server has no access to refresh tokens from the OAuth callback
+- **Alternative**: Token exchange provides similar benefits without violating OAuth security model
+
+**3. Admin Credentials Fallback**
+- **Out of Scope**: This ADR focuses on OAuth mode only
+- **Not Appropriate**: Admin credentials bypass OAuth security model
+- **BasicAuth Mode**: For single-user deployments needing background operations, use BasicAuth mode instead
+
+### Key Architectural Principles
+
+1. **Capability Detection**: Automatically detect which OAuth methods are supported
+2. **Dual-Phase Authorization**:
+   - Sync worker indexes with service credentials
+   - User requests verify access with user's OAuth token
+3. **Defense in Depth**: Vector database is search accelerator, not security boundary
+4. **Separation of Concerns**: Sync credentials ≠ Request credentials
+
+## Implementation Details
+
+### 1. Token Exchange with Impersonation (Tier 1) ✅ IMPLEMENTED (Legacy V1 only)
+
+**Status**: Implemented and working with Keycloak Legacy V1 (`--features=preview`). Requires additional permission configuration. Recommended for advanced use cases only.
+
+**When to Use**: When you need the exchanged token to have the exact same identity as the target user (sub claim changes). This provides the cleanest separation but requires preview features.
+
+#### 1.1 Impersonation Flow
+
+```python
+async def exchange_token_for_user(
+    subject_token: str,
+    target_user_id: str,
+    audience: str | None = None,
+    scopes: list[str] | None = None,
+) -> dict:
+    """Exchange service token to impersonate specific user.
+
+    Requires Keycloak Legacy V1 (--features=preview) and impersonation permissions.
+    The returned token will have the target_user_id as the 'sub' claim.
+    """
+    data = {
+        "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
+        "subject_token": subject_token,
+        "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
+        "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
+        "requested_subject": target_user_id,  # ← KEY: Impersonate this user
+    }
+
+    if audience:
+        data["audience"] = audience
+    if scopes:
+        data["scope"] = " ".join(scopes)
+
+    response = await self._http_client.post(
+        self.token_endpoint,
+        data=data,
+        auth=(self.client_id, self.client_secret),
+    )
+    response.raise_for_status()
+    return response.json()
+```
+
+**Implementation Requirements**:
+- ✅ Keycloak Legacy V1 with `--features=preview` flag
+- ✅ Impersonation role granted to service account (see configuration below)
+- ❌ NOT supported in Keycloak Standard V2 (rejects `requested_subject` parameter)
+- ⚠️ Very few OIDC providers support user impersonation via token exchange
+
+**Empirical Testing (2025-11-02)**:
+
+Tested impersonation with `requested_subject` parameter against Keycloak 26.4.2:
+
+**Test Command**: `uv run python tests/manual/test_impersonation.py`
+
+**Keycloak Standard V2 Result**:
+```
+HTTP/1.1 400 Bad Request
+{
+  "error": "invalid_request",
+  "error_description": "Parameter 'requested_subject' is not supported for standard token exchange"
+}
+```
+
+**Confirmation**: Keycloak explicitly rejects `requested_subject` in Standard V2, confirming this feature is unsupported. The error message is unambiguous - this parameter is not available in the current production token exchange implementation.
+
+**Keycloak Legacy V1 Result - Initial Test** (with `--features=preview`):
+```
+HTTP/1.1 403 Forbidden
+{
+  "error": "access_denied",
+  "error_description": "Client not allowed to exchange"
+}
+
+Keycloak logs:
+reason="subject not allowed to impersonate"
+impersonator="service-account-nextcloud-mcp-server"
+requested_subject="admin"
+```
+
+**Analysis**: Legacy V1 **accepts** the `requested_subject` parameter (error changed from "not supported" to "not allowed"), indicating the feature is present but requires permission configuration.
+
+**Configuration Steps to Enable Impersonation**:
+
+1. **Enable Keycloak preview features** (in docker-compose.yml):
+   ```yaml
+   command:
+     - "start-dev"
+     - "--features=preview"  # Required for Legacy V1 token exchange
+   ```
+
+2. **Grant impersonation role to service account** (using Keycloak CLI):
+   ```bash
+   docker compose exec keycloak /opt/keycloak/bin/kcadm.sh config credentials \
+     --server http://localhost:8080 \
+     --realm master \
+     --user admin \
+     --password admin
+
+   docker compose exec keycloak /opt/keycloak/bin/kcadm.sh add-roles \
+     -r nextcloud-mcp \
+     --uusername service-account-nextcloud-mcp-server \
+     --cclientid realm-management \
+     --rolename impersonation
+   ```
+
+**Keycloak Legacy V1 Result - After Permission Grant**:
+```
+✅ Token exchange with impersonation SUCCEEDED!
+
+📊 Response details:
+  Issued token type: urn:ietf:params:oauth:token-type:access_token
+  Token type: Bearer
+  Expires in: 300s
+
+📋 Token claims analysis:
+  Subject (sub): 47c3ba5a-9104-45e0-b84e-0e39ab942c9c  (admin user)
+  Preferred username: admin
+  Client ID (azp): nextcloud-mcp-server
+
+✅ IMPERSONATION VERIFIED:
+   Original sub: service-account-nextcloud-mcp-server
+   New sub:      47c3ba5a-9104-45e0-b84e-0e39ab942c9c
+   ➡️  The subject claim CHANGED - impersonation worked!
+```
+
+**Nextcloud API Validation**:
+The impersonated token successfully authenticated with Nextcloud APIs, confirming the token is valid and properly represents the target user.
+
+**Implementation Status**: Impersonation **IS IMPLEMENTED** and working with Keycloak Legacy V1. The implementation has been tested and verified to work correctly when properly configured.
+
+**Production Considerations**:
+- ⚠️ Requires preview features (`--features=preview`) - not production-ready
+- ⚠️ Requires Legacy V1 token exchange (may be deprecated in future Keycloak versions)
+- ⚠️ Requires manual CLI configuration for each service account
+- ⚠️ More complex permission model compared to delegation
+
+**When to Use Tier 1 (Impersonation)**:
+- ✅ You need the exchanged token to have the exact same identity as the target user
+- ✅ You want the cleanest separation (sub claim changes completely)
+- ✅ Your environment can support preview features
+- ✅ You have operational processes to manage impersonation permissions
+
+**Recommendation**: For most use cases, use Tier 2 (Delegation) instead. It provides equivalent "act on-behalf-of" capability using production-ready Standard V2 token exchange. Use Tier 1 only when you specifically need identity impersonation.
+
+**Test Scripts**:
+- `tests/manual/test_impersonation.py` - Complete impersonation test with validation
+- `tests/manual/configure_impersonation.py` - Automated permission configuration helper
+- **See**: `docs/oauth-impersonation-findings.md` for detailed investigation
+
+### 2. Token Exchange with Delegation (Tier 2) ✅ IMPLEMENTED (Standard V2)
+
+**Status**: Implemented and working with Keycloak Standard V2 (production-ready). This is the **recommended** approach for most use cases.
+
+**When to Use**: When you need "act on-behalf-of" functionality with production-ready features. The service account maintains its identity (sub claim unchanged) but acts on behalf of the user. Fully supported in Keycloak Standard V2 without preview features.
+
+#### 2.1 Capability Detection
+```python
+async def check_token_exchange_support(discovery_url: str) -> bool:
+    """Check if OIDC provider supports RFC 8693 token exchange"""
+
+    async with httpx.AsyncClient() as client:
+        response = await client.get(discovery_url)
+        discovery = response.json()
+
+        # Check for token exchange grant type
+        grant_types = discovery.get("grant_types_supported", [])
+        return "urn:ietf:params:oauth:grant-type:token-exchange" in grant_types
+```
+
+#### 2.2 Delegation Token Exchange
+```python
+async def exchange_for_user_token(
+    service_token: str,
+    target_user_id: str,
+    audience: str,
+    scopes: list[str]
+) -> str:
+    """Exchange service token for user-scoped token via RFC 8693"""
+
+    async with httpx.AsyncClient() as client:
+        response = await client.post(
+            token_endpoint,
+            data={
+                "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
+                "subject_token": service_token,
+                "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
+                "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
+                "audience": audience,  # Target resource server (e.g., "nextcloud")
+                "scope": " ".join(scopes)
+            },
+            auth=(client_id, client_secret)
+        )
+
+        if response.status_code != 200:
+            logger.warning(f"Token exchange failed: {response.status_code}")
+            raise TokenExchangeNotSupportedError()
+
+        return response.json()["access_token"]
+```
+
+**Implementation**: `KeycloakOAuthClient.exchange_token_for_user()` (keycloak_oauth.py:397-495)
+
+**Note**: Full delegation with `act` claim requires provider support that is currently very rare. Keycloak tracking: [Issue #38279](https://github.com/keycloak/keycloak/issues/38279)
+
+### 3. Comparison: When to Use Each Tier
+
+| Feature | Tier 1: Impersonation | Tier 2: Delegation (Recommended) |
+|---------|----------------------|-----------------------------------|
+| **Status** | ✅ Implemented (Legacy V1) | ✅ Implemented (Standard V2) |
+| **Token Identity** | Target user (`sub` changes) | Service account (`sub` unchanged) |
+| **Keycloak Version** | Legacy V1 (`--features=preview`) | Standard V2 (production-ready) |
+| **Setup Complexity** | High (manual permissions) | Low (automatic) |
+| **Production Ready** | ⚠️ Preview features required | ✅ Fully production-ready |
+| **Permission Grant** | Manual CLI per service account | Automatic via token exchange |
+| **Audit Trail** | Shows as target user | Shows as service account acting for user |
+| **Token Claims** | `sub: user-id` | `sub: service-account-id` |
+| **Provider Support** | Rare (Keycloak Legacy V1 only) | Common (Keycloak, Auth0, Okta) |
+| **Use Case** | Need exact user identity | Standard OAuth workflows |
+| **Recommendation** | Advanced use only | **Default choice** |
+
+**Decision Guide**:
+- ✅ **Use Tier 2 (Delegation)** for:
+  - Production deployments
+  - Standard OAuth workflows
+  - Clear audit trails (service account visible)
+  - Maximum provider compatibility
+
+- ⚠️ **Use Tier 1 (Impersonation)** only if:
+  - You specifically need exact user identity (sub claim must match)
+  - You can accept preview/experimental features
+  - You have operational processes for permission management
+  - Your IdP supports `requested_subject` parameter
+
+### 4. Sync Worker with Tiered Authentication
+
+```python
+# nextcloud_mcp_server/sync_worker.py
+class VectorSyncWorker:
+    """Background worker for indexing content into vector database"""
+
+    def __init__(self):
+        self.auth_method = None
+        self.oauth_client = None  # KeycloakOAuthClient or similar
+        self.vector_service = None
+
+    async def initialize(self):
+        """Detect and configure authentication method"""
+
+        from nextcloud_mcp_server.auth.keycloak_oauth import KeycloakOAuthClient
+
+        try:
+            self.oauth_client = KeycloakOAuthClient.from_env()
+            await self.oauth_client.discover()
+
+            # Verify service account access (Tier 1)
+            service_token = await self.oauth_client.get_service_account_token()
+            logger.info("✓ Service account token acquired")
+
+            # Check if token exchange is supported (Tier 2/3)
+            if await check_token_exchange_support(self.oauth_client.discovery_url):
+                self.auth_method = "token_exchange_delegation"
+                logger.info(
+                    "✓ Token exchange supported (RFC 8693) - will use delegation for user-scoped operations"
+                )
+            else:
+                self.auth_method = "service_account"
+                logger.info(
+                    "ℹ Token exchange not supported - using service account token for all operations"
+                )
+
+        except Exception as e:
+            logger.error(f"Failed to initialize OAuth authentication: {e}")
+            raise RuntimeError(
+                "OAuth authentication is required for background sync. "
+                "Either configure OIDC_CLIENT_ID/OIDC_CLIENT_SECRET with service account enabled, "
+                "or use BasicAuth mode for single-user deployments."
+            ) from e
+
+    async def get_user_client(self, user_id: str) -> NextcloudClient:
+        """Get authenticated client for user based on auth method"""
+
+        if self.auth_method == "token_exchange_delegation":
+            # Tier 2/3: Get service token and exchange for user-scoped token
+            service_token_data = await self.oauth_client.get_service_account_token()
+
+            user_token_data = await self.oauth_client.exchange_token_for_user(
+                subject_token=service_token_data["access_token"],
+                target_user_id=user_id,
+                audience="nextcloud",
+                scopes=["notes:read", "files:read", "calendar:read"]
+            )
+
+            return NextcloudClient.from_token(
+                base_url=nextcloud_host,
+                token=user_token_data["access_token"],
+                username=user_id
+            )
+
+        elif self.auth_method == "service_account":
+            # Tier 1: Use service account token directly (no user scoping)
+            service_token_data = await self.oauth_client.get_service_account_token()
+
+            return NextcloudClient.from_token(
+                base_url=nextcloud_host,
+                token=service_token_data["access_token"],
+                username="service-account"
+            )
+
+        raise RuntimeError(f"Unknown auth method: {self.auth_method}")
+
+    async def sync_user_content(self, user_id: str):
+        """Index a user's content into vector database"""
+
+        try:
+            # Get authenticated client for this user
+            client = await self.get_user_client(user_id)
+
+            # Sync notes
+            notes = await client.notes.list_notes()
+            for note in notes:
+                embedding = await self.vector_service.embed(note.content)
+                await self.vector_service.upsert(
+                    collection="nextcloud_content",
+                    id=f"note_{note.id}",
+                    vector=embedding,
+                    metadata={
+                        "user_id": user_id,
+                        "content_type": "note",
+                        "note_id": note.id,
+                        "title": note.title,
+                        "category": note.category
+                    }
+                )
+
+            logger.info(f"Synced {len(notes)} notes for user: {user_id}")
+
+        except Exception as e:
+            logger.error(f"Failed to sync user {user_id}: {e}")
+
+    async def run(self):
+        """Main sync loop"""
+
+        await self.initialize()
+
+        while True:
+            try:
+                # Get list of users to sync
+                # Implementation depends on how you track authenticated users
+                # Options:
+                # - Audit logs of MCP authentication events
+                # - MCP session history
+                # - Configured user list
+                # - If using service account with broad permissions: list all users
+                user_ids = await self.get_active_users()
+
+                logger.info(f"Syncing content for {len(user_ids)} users")
+
+                for user_id in user_ids:
+                    await self.sync_user_content(user_id)
+
+                logger.info("Sync complete, sleeping...")
+                await asyncio.sleep(300)  # 5 minutes
+
+            except Exception as e:
+                logger.error(f"Sync failed: {e}")
+                await asyncio.sleep(60)  # Retry after 1 minute
+```
+
+### 4. User Request Verification (Dual-Phase Authorization)
+
+```python
+@mcp.tool()
+@require_scopes("notes:read")
+async def nc_notes_semantic_search(
+    query: str,
+    ctx: Context,
+    limit: int = 10
+) -> SemanticSearchResponse:
+    """Semantic search with permission verification"""
+
+    # Get user's OAuth client (uses their access token from request)
+    user_client = get_client(ctx)
+    username = user_client.username
+
+    # Phase 1: Vector search (fast, may include false positives)
+    embedding = await vector_service.embed(query)
+    candidate_results = await qdrant.search(
+        collection_name="nextcloud_content",
+        query_vector=embedding,
+        query_filter={
+            "must": [
+                {
+                    "should": [
+                        {"key": "user_id", "match": {"value": username}},
+                        {"key": "shared_with", "match": {"any": [username]}}
+                    ]
+                },
+                {"key": "content_type", "match": {"value": "note"}}
+            ]
+        },
+        limit=limit * 2  # Get extra candidates
+    )
+
+    # Phase 2: Verify access via Nextcloud API (authoritative)
+    verified_results = []
+    for candidate in candidate_results:
+        note_id = candidate.payload["note_id"]
+        try:
+            # This uses user's OAuth token - will fail if no access
+            note = await user_client.notes.get_note(note_id)
+            verified_results.append({
+                "note": note,
+                "score": candidate.score
+            })
+            if len(verified_results) >= limit:
+                break
+        except HTTPStatusError as e:
+            if e.response.status_code == 403:
+                # User doesn't have access - skip silently
+                logger.debug(f"Filtered out note {note_id} for {username}")
+                continue
+            raise
+
+    return SemanticSearchResponse(results=verified_results)
+```
+
+### 5. Security Implementation
+
+#### 5.1 Service Account Credentials Protection
+```python
+# Store OAuth client credentials securely
+# NEVER commit to source control
+
+# Option 1: Environment variables (for development)
+export OIDC_CLIENT_ID="nextcloud-mcp-server"
+export OIDC_CLIENT_SECRET="<secure-secret>"
+
+# Option 2: Secrets manager (for production)
+import boto3
+secrets = boto3.client('secretsmanager')
+secret = secrets.get_secret_value(SecretId='nextcloud-mcp-oauth')
+client_secret = json.loads(secret['SecretString'])['client_secret']
+
+# Option 3: Encrypted storage (for self-hosted)
+from nextcloud_mcp_server.auth.refresh_token_storage import RefreshTokenStorage
+
+storage = RefreshTokenStorage.from_env()
+await storage.initialize()
+
+# Client credentials are encrypted at rest using Fernet
+client_data = await storage.get_oauth_client()
+```
+
+#### 5.2 Token Lifecycle Management
+```python
+async def manage_service_token_lifecycle():
+    """Cache and refresh service account tokens"""
+
+    # Cache service token (avoid repeated requests)
+    cached_token = None
+    token_expires_at = 0
+
+    async def get_fresh_service_token() -> str:
+        nonlocal cached_token, token_expires_at
+
+        now = time.time()
+
+        # Return cached token if still valid (with 5-minute buffer)
+        if cached_token and now < (token_expires_at - 300):
+            return cached_token
+
+        # Request new token
+        token_data = await oauth_client.get_service_account_token()
+
+        cached_token = token_data["access_token"]
+        token_expires_at = now + token_data.get("expires_in", 3600)
+
+        logger.info("Service account token refreshed")
+        return cached_token
+
+    return get_fresh_service_token
+```
+
+#### 5.3 Audit Logging
+```python
+async def audit_log(
+    event: str,
+    user_id: str,
+    resource_type: str,
+    resource_id: str,
+    auth_method: str
+):
+    """Log sync operations for audit trail"""
+
+    await audit_db.execute(
+        "INSERT INTO audit_logs VALUES (?, ?, ?, ?, ?, ?, ?)",
+        (
+            int(time.time()),
+            event,  # "index_note", "index_file"
+            user_id,
+            resource_type,
+            resource_id,
+            auth_method,
+            socket.gethostname()
+        )
+    )
+```
+
+### 6. Configuration
+
+#### 6.1 Environment Variables
+```bash
+# OAuth Configuration (Required for Background Sync in OAuth Mode)
+# Requires external OIDC provider with client_credentials support
+OIDC_DISCOVERY_URL=http://keycloak:8080/realms/nextcloud-mcp/.well-known/openid-configuration
+OIDC_CLIENT_ID=nextcloud-mcp-server
+OIDC_CLIENT_SECRET=<secure-secret>
+NEXTCLOUD_HOST=http://app:80
+
+# Tier selection is automatic:
+# - Tier 1 (service_account): Always available if client has service account enabled
+# - Tier 2/3 (token_exchange): Used if provider supports RFC 8693 token exchange
+
+# Vector Database
+QDRANT_URL=http://qdrant:6333
+QDRANT_API_KEY=<api-key>
+
+# Sync Configuration
+SYNC_INTERVAL_SECONDS=300
+SYNC_BATCH_SIZE=100
+
+# Note: For BasicAuth mode (single-user), background sync uses NEXTCLOUD_USERNAME/NEXTCLOUD_PASSWORD
+# This ADR focuses on OAuth mode only
+```
+
+#### 6.2 Keycloak Configuration (for Token Exchange)
+
+**Client Settings** (`nextcloud-mcp-server`):
+```json
+{
+  "clientId": "nextcloud-mcp-server",
+  "serviceAccountsEnabled": true,
+  "authorizationServicesEnabled": false,
+  "attributes": {
+    "token.exchange.grant.enabled": "true",
+    "client.token.exchange.standard.enabled": "true"
+  }
+}
+```
+
+**Service Account Roles**:
+- Assign appropriate Nextcloud roles/scopes to the service account
+- Configure token exchange permissions
+
+#### 6.3 Docker Compose
+```yaml
+services:
+  mcp-sync:
+    build: .
+    command: ["python", "-m", "nextcloud_mcp_server.sync_worker"]
+    environment:
+      - NEXTCLOUD_HOST=http://app:80
+
+      # External OIDC provider (Keycloak)
+      - OIDC_DISCOVERY_URL=http://keycloak:8080/realms/nextcloud-mcp/.well-known/openid-configuration
+      - OIDC_CLIENT_ID=nextcloud-mcp-server
+      - OIDC_CLIENT_SECRET=${OIDC_CLIENT_SECRET}
+
+      # Vector database
+      - QDRANT_URL=http://qdrant:6333
+      - QDRANT_API_KEY=${QDRANT_API_KEY}
+    volumes:
+      - sync-data:/app/data  # For OAuth client credential storage
+    depends_on:
+      - app
+      - keycloak
+      - qdrant
+
+volumes:
+  sync-data:  # Persistent storage for encrypted OAuth client credentials
+```
+
+## Consequences
+
+### Benefits
+
+1. **OAuth-Native Authentication**
+   - Leverages standard OAuth flows (offline_access, token exchange)
+   - No reliance on admin passwords in production
+   - Compatible with enterprise OIDC providers
+
+2. **User-Level Permissions**
+   - Each user's content indexed with their own credentials
+   - Respects sharing, permissions, and access controls
+   - Full audit trail of which user's token was used
+
+3. **Security**
+   - Tokens encrypted at rest
+   - Short-lived access tokens (refreshed as needed)
+   - Token rotation support
+   - Defense in depth with dual-phase authorization
+
+4. **Flexibility**
+   - Automatic capability detection
+   - Graceful degradation through authentication tiers
+   - Works with varying OIDC provider capabilities
+
+5. **Operational**
+   - Background sync independent of user activity
+   - Efficient batch processing
+   - Clear separation of sync vs request credentials
+
+### Limitations
+
+1. **Complexity**
+   - Multiple authentication paths to maintain
+   - Token storage and encryption infrastructure
+   - More moving parts than simple admin auth
+
+2. **User Experience**
+   - `offline_access` scope may require additional consent
+   - Users must authenticate at least once for indexing
+   - New users not automatically indexed
+
+3. **OIDC Provider Dependency**
+   - Token exchange requires RFC 8693 support (rare)
+   - Refresh token rotation varies by provider
+   - Some providers may not support offline_access
+
+4. **Operational Overhead**
+   - Token database maintenance
+   - Monitoring token expiration
+   - Handling revoked tokens gracefully
+
+### Security Considerations
+
+#### Threat Model
+
+**Threat 1: Token Storage Breach**
+- **Mitigation**: Encryption at rest using Fernet
+- **Mitigation**: Secure key management (secrets manager)
+- **Mitigation**: Minimal token lifetime
+- **Detection**: Audit logs for unusual access patterns
+
+**Threat 2: Token Replay**
+- **Mitigation**: Short-lived access tokens (refreshed frequently)
+- **Mitigation**: Token rotation on each refresh
+- **Mitigation**: Revocation support
+
+**Threat 3: Privilege Escalation**
+- **Mitigation**: Dual-phase authorization (vector DB + Nextcloud API)
+- **Mitigation**: Sync worker uses same scopes as user requests
+- **Mitigation**: Per-user token isolation
+
+**Threat 4: Vector Database Poisoning**
+- **Mitigation**: User requests always verify via Nextcloud API
+- **Mitigation**: Vector DB is cache/accelerator, not source of truth
+- **Mitigation**: Sync operations audited per user
+
+#### Security Best Practices
+
+1. **OAuth Client Secret Management**
+   ```bash
+   # Store in secrets manager (Vault, AWS Secrets Manager, etc.)
+   # Or use environment variable with restricted permissions
+
+   # For self-hosted: Use encrypted storage
+   # OAuth client credentials stored in SQLite with Fernet encryption
+   # Encryption key: TOKEN_ENCRYPTION_KEY environment variable
+
+   # Generate encryption key:
+   python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+   ```
+
+2. **Service Account Token Lifecycle**
+   - Cache service tokens to minimize requests (with expiry buffer)
+   - Automatically refresh expired tokens
+   - Use short-lived tokens (provider default, typically 1 hour)
+   - Monitor token request rates and failures
+
+3. **Database Permissions (for Client Credential Storage)**
+   ```bash
+   # Restrict database file permissions
+   chmod 600 /app/data/tokens.db
+   chown mcp-server:mcp-server /app/data/tokens.db
+   ```
+
+4. **Monitoring and Alerting**
+   - Alert on token exchange failures
+   - Monitor for unusual access patterns
+   - Track service account token usage
+   - Audit sync operations per user (if delegation supported)
+
+### Future Enhancements
+
+1. **Token Revocation Handling**
+   - Webhook endpoint for token revocation events
+   - Periodic validation of stored tokens
+   - Graceful handling of revoked tokens
+
+2. **Selective Sync**
+   - Allow users to opt-in/opt-out of indexing
+   - Per-content-type sync preferences
+   - Privacy controls for sensitive content
+
+3. **Multi-Tenant Token Storage**
+   - Separate token databases per tenant
+   - Key rotation per tenant
+   - Tenant isolation
+
+4. **Token Lifecycle Management**
+   - Automatic cleanup of expired tokens
+   - Token usage analytics
+   - Token health dashboard
+
+5. **Alternative OAuth Flows**
+   - Device flow for headless sync
+   - Resource owner password credentials (ROPC) as fallback
+   - SAML assertion grants
+
+## Alternatives Considered
+
+### Alternative 1: Admin BasicAuth Only
+
+**Approach**: Background worker always uses admin credentials
+
+**Pros**:
+- Simple implementation
+- No token storage complexity
+- Works with any authentication backend
+
+**Cons**:
+- Violates principle of least privilege
+- Single powerful credential
+- No per-user audit trail
+- Bypasses OAuth entirely
+
+**Decision**: Rejected for production use; kept as fallback only
+
+### Alternative 2: Client Credentials Grant Only
+
+**Approach**: Service account with broad read permissions
+
+**Pros**:
+- OAuth-native pattern
+- No user token storage
+- Standard OAuth flow
+
+**Cons**:
+- Requires client_credentials support (may not be available)
+- Still needs broad cross-user permissions
+- Not well-suited for multi-user indexing
+
+**Decision**: Rejected; token exchange is better fit for multi-user scenario
+
+### Alternative 3: Per-User Access Token Storage
+
+**Approach**: Store user access tokens (not refresh tokens)
+
+**Pros**:
+- Simpler than refresh token flow
+- No token refresh logic needed
+
+**Cons**:
+- Access tokens are short-lived (1-24 hours)
+- Requires frequent re-authentication
+- Poor user experience
+- Sync gaps when tokens expire
+
+**Decision**: Rejected; refresh tokens provide better UX
+
+### Alternative 4: On-Demand Indexing Only
+
+**Approach**: Index content when user searches (no background worker)
+
+**Pros**:
+- Uses user's request token
+- No background auth needed
+- Simpler architecture
+
+**Cons**:
+- Very slow first search
+- Poor user experience
+- Incomplete index
+- Can't pre-compute embeddings
+
+**Decision**: Rejected; background indexing is essential for semantic search
+
+### Alternative 5: Nextcloud App Tokens
+
+**Approach**: Generate app-specific passwords for each user
+
+**Pros**:
+- Nextcloud-native feature
+- User-controlled revocation
+- Scoped per-application
+
+**Cons**:
+- Requires user interaction to create
+- May not support programmatic creation
+- Still requires secure storage
+- Not standard OAuth
+
+**Decision**: Rejected; not automatable for background worker
+
+## Related Decisions
+
+- ADR-001: Enhanced Note Search (establishes need for vector search)
+- [Future] ADR-003: Vector Database Selection
+- [Future] ADR-004: Embedding Model Strategy
+
+## References
+
+- [RFC 8693: OAuth 2.0 Token Exchange](https://datatracker.ietf.org/doc/html/rfc8693)
+- [RFC 6749: OAuth 2.0 - Refresh Tokens](https://datatracker.ietf.org/doc/html/rfc6749#section-1.5)
+- [OpenID Connect Core - Offline Access](https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess)
+- [OWASP: OAuth Security Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/OAuth2_Cheat_Sheet.html)
+- [RFC 8707: Resource Indicators for OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)

docs/ADR-004-Code-Review.md

@@ -0,0 +1,65 @@
+Excellent and incredibly thorough work on ADR-004. It outlines a robust, secure, and modern approach to federated authentication that aligns with industry best practices. The Progressive Consent architecture with dual OAuth flows is the right direction for a system with these requirements.
+
+Here is a review of the current implementation in light of the architecture proposed in the ADR.
+
+### High-Level Assessment
+
+The project is in a good state, with a clear vision for its authentication architecture. The current implementation provides a backward-compatible "Hybrid Flow" while also containing the scaffolding for the target "Progressive Consent" flow. The hybrid flow is well-tested, which is a great foundation.
+
+The following points are intended to help bridge the gap between the current implementation and the final vision outlined in ADR-004.
+
+### Critical Security Review
+
+#### 1. Missing Token Audience (`aud`) Validation
+
+This is the most critical issue. The `require_scopes` decorator currently checks for scopes but does not validate the `audience` (`aud` claim) of the incoming JWT.
+
+*   **Risk:** This creates a "confused deputy" vulnerability. An access token issued for a different application could be used to access the MCP server, as long as the scope names happen to match.
+*   **ADR Reference:** The ADR correctly identifies this and proposes an `MCPTokenVerifier` that validates `aud: "mcp-server"`.
+*   **Recommendation:** Implement the audience validation as a central part of your token verification middleware. An incoming token should be rejected immediately if its audience is not `mcp-server`. This check should happen before any tool-specific scope checks.
+
+### Architecture and Implementation Review
+
+#### 2. Progressive Consent Flow is Untested
+
+The code for the Progressive Consent flow (behind the `ENABLE_PROGRESSIVE_CONSENT` flag) exists in `oauth_routes.py` and `oauth_tools.py`. However, there are no integration tests to validate it.
+
+*   **Risk:** Given the complexity of OAuth flows, it's likely there are bugs in the untested implementation.
+*   **Recommendation:** Create a new test file, `test_adr004_progressive_flow.py`, that uses Playwright to test the dual-flow architecture end-to-end:
+    1.  **Flow 1:** A test MCP client authenticates directly with the IdP to get an `mcp-server` token.
+    2.  **Provisioning Check:** The test verifies that calling a Nextcloud tool fails with a `ProvisioningRequiredError`.
+    3.  **Flow 2:** The test calls the `provision_nextcloud_access` tool and automates the second OAuth flow to grant the server offline access.
+    4.  **Tool Execution:** The test verifies that Nextcloud tools can now be successfully called.
+
+#### 3. Inconsistent Authorization URL Generation
+
+There is duplicated and inconsistent logic for generating the IdP authorization URL.
+
+*   **Location 1:** `oauth_tools.py` in `generate_oauth_url_for_flow2` hardcodes the authorization endpoint path.
+*   **Location 2:** `oauth_routes.py` in `oauth_authorize_nextcloud` correctly uses the OIDC discovery document to find the `authorization_endpoint`.
+*   **Risk:** The hardcoded path is brittle and will break with IdPs that use different endpoint paths (like Keycloak).
+*   **Recommendation:** Consolidate this logic. The `provision_nextcloud_access` tool should not build the URL itself. Instead, it should return a URL pointing to the MCP server's own `/oauth/authorize-nextcloud` endpoint. This endpoint (which you've already created as `oauth_authorize_nextcloud` in `oauth_routes.py`) can then be the single source of truth for generating the IdP redirect.
+
+#### 4. Poor User Experience due to Missing Token Refresh
+
+The `/oauth/token` endpoint does not implement the `refresh_token` grant type. This means that when the client's `mcp-server` access token expires (e.g., after one hour), the user must go through the entire browser-based login flow again.
+
+*   **Risk:** This creates a frustrating user experience, especially for long-lived desktop clients.
+*   **ADR Reference:** A proper Flow 1 should result in the MCP client receiving both an access token and a refresh token from the IdP.
+*   **Recommendation:**
+    1.  Ensure the IdP is configured to issue refresh tokens to the MCP client for Flow 1.
+    2.  The MCP client should securely store this refresh token.
+    3.  The client should use the refresh token to get new `mcp-server` access tokens directly from the IdP, without involving the MCP server or the user. The MCP server should not be involved in the client's session management with the IdP.
+
+### Summary
+
+The project is on the right track. The ADR is a solid plan, and the initial implementation is a good starting point.
+
+My recommendations in order of priority are:
+
+1.  **Implement Audience Validation** to close the security gap.
+2.  **Add Integration Tests** for the Progressive Consent flow.
+3.  **Refactor the client-side token refresh** to improve user experience.
+4.  **Consolidate the URL generation** logic to fix the inconsistency.
+
+Addressing these points will align the implementation with the excellent vision in ADR-004 and result in a secure, robust, and user-friendly system.

docs/ADR-006-progressive-consent-elicitation.md

@@ -0,0 +1,865 @@
+# ADR-006: Progressive Consent via URL Elicitation (SEP-1036)
+
+**Status**: Partially Implemented (Interim Workaround)
+**Date**: 2025-01-05 (Updated: 2025-01-07)
+**Related**: [SEP-1036](https://github.com/modelcontextprotocol/specification/pull/887), ADR-004
+**Depends On**: ADR-005 (token validation)
+
+## Context
+
+### What is Progressive Consent?
+
+**Progressive consent is a mechanism, not a feature**. It describes HOW users grant the MCP server access to Nextcloud resources through OAuth elicitation. The server can operate in two modes:
+
+1. **Pass-through mode (ENABLE_OFFLINE_ACCESS=false)**:
+   - No refresh tokens requested or stored
+   - Server passes through client's access token to Nextcloud
+   - No provisioning tools available
+   - Suitable for stateless, client-driven operations
+
+2. **Offline access mode (ENABLE_OFFLINE_ACCESS=true)**:
+   - Server requests `offline_access` scope and stores refresh tokens
+   - Enables background operations and server-initiated API calls
+   - Provisioning tools available (`provision_nextcloud_access`, `check_logged_in`)
+   - Requires explicit user consent via OAuth Flow 2
+
+**Single-user mode (BasicAuth)** doesn't use progressive consent at all - credentials are directly available.
+
+### Current User Experience Issues
+
+The current offline access provisioning flow (ADR-004) requires users to manually visit OAuth URLs returned by MCP tools. This creates a poor user experience:
+
+1. User calls `provision_nextcloud_access` tool
+2. Tool returns a URL as text in the response
+3. User must manually copy URL and open in browser
+4. No indication when provisioning is complete
+5. User must retry the original operation manually
+
+### SEP-1036: URL Mode Elicitation
+
+The MCP specification now supports **URL mode elicitation** ([SEP-1036](https://github.com/modelcontextprotocol/specification/pull/887)), which enables servers to:
+
+- Request out-of-band user interactions via secure URLs
+- Handle sensitive operations like OAuth flows without exposing credentials to the client
+- Provide progress tracking for async operations
+- Return errors that automatically trigger elicitation flows
+
+**Key benefits for progressive consent**:
+- **Automatic URL Opening**: Client opens URL in browser automatically (with user consent)
+- **Progress Tracking**: Server can notify client when provisioning is complete
+- **Error-Triggered Flows**: Server can return `ElicitationRequired` error to trigger provisioning
+- **Better UX**: User doesn't manually copy/paste URLs
+
+### Current Implementation Limitations
+
+The current progressive consent flow in `nextcloud_mcp_server/server/oauth_tools.py`:
+
+```python
+@mcp.tool(name="provision_nextcloud_access")
+async def tool_provision_access(ctx: Context) -> ProvisioningResult:
+    """Returns OAuth URL as text - user must manually open it."""
+    return ProvisioningResult(
+        success=True,
+        authorization_url=auth_url,  # User must copy this
+        message="Please visit the authorization URL..."
+    )
+```
+
+**Problems**:
+1. Manual URL handling (copy/paste)
+2. No progress tracking
+3. No automatic retry after provisioning
+4. Tool call required just to get URL
+5. No client integration (URL just displayed as text)
+
+## Decision
+
+We will **migrate progressive consent from manual tools to URL mode elicitation**, leveraging SEP-1036 for better user experience and OAuth security.
+
+### New Architecture: Elicitation-Driven Consent
+
+Instead of explicit tools, use **automatic elicitation** triggered by authorization errors:
+
+```
+User → Calls Nextcloud Tool → Server Checks Provisioning
+                                     ↓ Not Provisioned
+                                Error: ElicitationRequired
+                                     ↓
+                          Client Shows Consent UI
+                                     ↓ User Accepts
+                          Client Opens OAuth URL
+                                     ↓
+                          User Completes OAuth
+                                     ↓
+                          Server Sends Progress Update
+                                     ↓
+                      Original Tool Call Auto-Retries
+```
+
+### Mode 1: Elicitation-Required Error (Primary)
+
+When a tool requires provisioning, return an **ElicitationRequired error** (-32000):
+
+```python
+# In any Nextcloud tool decorated with @require_provisioning
+@mcp.tool()
+@require_provisioning  # New decorator
+async def nc_notes_list_notes(ctx: Context):
+    """List notes - auto-triggers provisioning if needed."""
+    # If not provisioned, decorator returns ElicitationRequired error
+    # If provisioned, continues normally
+    client = await get_client(ctx)
+    return await client.notes.list_notes()
+```
+
+**Error response structure**:
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "error": {
+    "code": -32000,
+    "message": "Nextcloud access provisioning required",
+    "data": {
+      "elicitations": [
+        {
+          "mode": "url",
+          "elicitationId": "550e8400-e29b-41d4-a716-446655440000",
+          "url": "https://mcp.example.com/oauth/provision?id=550e8400...",
+          "message": "Grant the MCP server access to your Nextcloud account to continue."
+        }
+      ]
+    }
+  }
+}
+```
+
+**Client behavior**:
+1. Receives error with elicitation
+2. Shows consent UI: "App wants to access Nextcloud. Open authorization page?"
+3. On user acceptance, opens URL in browser
+4. Optionally tracks progress via `elicitation/track`
+5. Auto-retries original tool call when complete
+
+### Mode 2: Explicit Elicitation Request (Fallback)
+
+For clients that don't support error-triggered elicitation, provide explicit tool:
+
+```python
+@mcp.tool(name="request_nextcloud_access")
+async def request_access(ctx: Context) -> ElicitationResponse:
+    """Explicitly request provisioning via elicitation."""
+    # Send elicitation/create request
+    return await create_elicitation(
+        mode="url",
+        url=generate_oauth_url(),
+        message="Grant access to Nextcloud",
+        elicitation_id=generate_id()
+    )
+```
+
+**Note**: This is a fallback for compatibility. Primary flow uses error-triggered elicitation.
+
+## Implementation
+
+### 1. New Decorator: `@require_provisioning`
+
+Replace explicit provisioning checks with a decorator that returns `ElicitationRequired`:
+
+```python
+# nextcloud_mcp_server/auth/provisioning_decorator.py
+
+def require_provisioning(func):
+    """
+    Decorator that ensures user has provisioned Nextcloud access.
+
+    If not provisioned, returns ElicitationRequired error with OAuth URL.
+    Otherwise, proceeds with normal tool execution.
+    """
+    @functools.wraps(func)
+    async def wrapper(ctx: Context, *args, **kwargs):
+        # Extract user ID from token
+        user_id = get_user_id_from_context(ctx)
+
+        # Check if provisioned
+        storage = RefreshTokenStorage.from_env()
+        await storage.initialize()
+
+        if not await storage.has_refresh_token(user_id):
+            # Not provisioned - return ElicitationRequired error
+            elicitation_id = str(uuid.uuid4())
+            oauth_url = await generate_oauth_url_for_provisioning(
+                user_id=user_id,
+                elicitation_id=elicitation_id,
+                ctx=ctx
+            )
+
+            # Store elicitation for tracking
+            await storage.store_elicitation(
+                elicitation_id=elicitation_id,
+                user_id=user_id,
+                status="pending",
+                created_at=datetime.now(timezone.utc)
+            )
+
+            raise McpError(
+                code=ErrorCode.ELICITATION_REQUIRED,  # -32000
+                message="Nextcloud access provisioning required",
+                data={
+                    "elicitations": [
+                        {
+                            "mode": "url",
+                            "elicitationId": elicitation_id,
+                            "url": oauth_url,
+                            "message": (
+                                "Grant the MCP server access to your Nextcloud "
+                                "account to continue. This is a one-time setup."
+                            )
+                        }
+                    ]
+                }
+            )
+
+        # Already provisioned - proceed normally
+        return await func(ctx, *args, **kwargs)
+
+    return wrapper
+```
+
+### 2. Elicitation Tracking Endpoint
+
+Implement `elicitation/track` to provide progress updates:
+
+```python
+# nextcloud_mcp_server/server/elicitation.py
+
+@mcp.request_handler("elicitation/track")
+async def track_elicitation(
+    elicitation_id: str,
+    _meta: dict = None
+) -> dict:
+    """
+    Track progress of an elicitation request.
+
+    Returns when elicitation is complete or times out.
+    """
+    progress_token = _meta.get("progressToken") if _meta else None
+
+    storage = RefreshTokenStorage.from_env()
+    await storage.initialize()
+
+    # Poll for completion (with timeout)
+    timeout = 300  # 5 minutes
+    start_time = datetime.now(timezone.utc)
+
+    while (datetime.now(timezone.utc) - start_time).seconds < timeout:
+        elicitation = await storage.get_elicitation(elicitation_id)
+
+        if not elicitation:
+            raise McpError(
+                code=-32602,  # Invalid params
+                message=f"Unknown elicitation ID: {elicitation_id}"
+            )
+
+        # Send progress notification if token provided
+        if progress_token and elicitation["status"] == "pending":
+            await send_progress_notification(
+                progress_token=progress_token,
+                progress=50,
+                message="Waiting for OAuth authorization..."
+            )
+
+        # Check if complete
+        if elicitation["status"] == "complete":
+            return {"status": "complete"}
+
+        # Check if failed
+        if elicitation["status"] == "failed":
+            return {
+                "status": "failed",
+                "error": elicitation.get("error_message")
+            }
+
+        # Wait before polling again
+        await asyncio.sleep(2)
+
+    # Timeout
+    raise McpError(
+        code=-32000,
+        message="Elicitation timed out - user did not complete authorization"
+    )
+```
+
+### 3. OAuth Callback Updates
+
+Update the OAuth callback to mark elicitations as complete:
+
+```python
+# nextcloud_mcp_server/auth/oauth_routes.py
+
+async def oauth_callback(request: Request) -> Response:
+    """Handle OAuth callback and mark elicitation complete."""
+    code = request.query_params.get("code")
+    state = request.query_params.get("state")
+
+    # Validate and exchange code for tokens
+    tokens = await exchange_authorization_code(code)
+
+    # Store refresh token
+    await storage.store_refresh_token(
+        user_id=user_id,
+        refresh_token=tokens["refresh_token"]
+    )
+
+    # Mark elicitation as complete
+    elicitation_id = request.query_params.get("elicitation_id")
+    if elicitation_id:
+        await storage.update_elicitation(
+            elicitation_id=elicitation_id,
+            status="complete",
+            completed_at=datetime.now(timezone.utc)
+        )
+
+    return Response(
+        content="<h1>Authorization Complete!</h1>"
+        "<p>You can close this window and return to the application.</p>",
+        media_type="text/html"
+    )
+```
+
+### 4. Update All Nextcloud Tools
+
+Add `@require_provisioning` decorator to all Nextcloud tools:
+
+```python
+# nextcloud_mcp_server/server/notes.py
+
+@mcp.tool()
+@require_scopes("notes:read")
+@require_provisioning  # NEW: Auto-triggers provisioning
+async def nc_notes_list_notes(
+    ctx: Context,
+    category: Optional[str] = None
+) -> NotesListResponse:
+    """List all notes - automatically handles provisioning."""
+    client = await get_client(ctx)
+    # Tool logic proceeds only if provisioned
+    notes = await client.notes.list_notes(category=category)
+    return NotesListResponse(results=notes)
+```
+
+### 5. Capability Declaration
+
+Declare URL elicitation support during initialization:
+
+```python
+# nextcloud_mcp_server/app.py
+
+capabilities = {
+    "elicitation": {
+        "url": {}  # Declare URL mode support
+        # Note: We don't support "form" mode (in-band data collection)
+    },
+    # ... other capabilities
+}
+```
+
+### 6. Environment Variables
+
+**Primary control**:
+```bash
+# ENABLE_OFFLINE_ACCESS: Controls whether server requests refresh tokens and enables provisioning tools
+# Default: false (pass-through mode)
+# Set to true to enable offline access mode with Flow 2 provisioning
+ENABLE_OFFLINE_ACCESS=true
+```
+
+**Future variables** (when URL elicitation is implemented):
+```bash
+# ELICITATION_CALLBACK_URL: Base URL for OAuth callbacks with elicitation tracking
+# Default: NEXTCLOUD_MCP_SERVER_URL + /oauth/callback
+ELICITATION_CALLBACK_URL=http://localhost:8000/oauth/callback
+
+# ELICITATION_TIMEOUT_SECONDS: How long to wait for user to complete OAuth
+# Default: 300 (5 minutes)
+ELICITATION_TIMEOUT_SECONDS=300
+```
+
+**Removed variables**:
+```bash
+# ENABLE_PROGRESSIVE_CONSENT - Removed. Progressive consent is a mechanism, not a feature toggle.
+#                               Use ENABLE_OFFLINE_ACCESS to control whether provisioning tools are available.
+# MCP_SERVER_CLIENT_ID - merged into OIDC_CLIENT_ID
+```
+
+## User Experience Comparison
+
+### Before (ADR-004 Manual Tools)
+
+```
+User: "List my notes"
+Assistant: *calls nc_notes_list_notes*
+Server: Error - not provisioned
+Assistant: "You need to provision access first. Let me do that."
+Assistant: *calls provision_nextcloud_access*
+Server: {authorization_url: "https://..."}
+Assistant: "Please visit this URL: https://..."
+User: *copies URL, opens browser, completes OAuth*
+User: "OK, I'm done"
+Assistant: *calls nc_notes_list_notes again*
+Server: Success! [notes...]
+```
+
+**Issues**: 4 interactions, manual URL handling, no automation
+
+### After (ADR-006 Elicitation)
+
+```
+User: "List my notes"
+Assistant: *calls nc_notes_list_notes*
+Server: ElicitationRequired error
+Client: Shows dialog: "Grant access to Nextcloud? [Yes] [No]"
+User: *clicks Yes*
+Client: Opens OAuth URL in browser automatically
+User: *completes OAuth*
+Server: Sends progress notification "Complete!"
+Client: Auto-retries nc_notes_list_notes
+Server: Success! [notes...]
+Assistant: "Here are your notes: ..."
+```
+
+**Benefits**: 1 interaction, automatic URL opening, seamless retry
+
+## Migration Path
+
+### Phase 1: Add Elicitation Support (v0.26.0)
+
+- Implement `@require_provisioning` decorator
+- Add `elicitation/track` endpoint
+- Keep existing tools (`provision_nextcloud_access`) for compatibility
+- Update OAuth callback to track elicitations
+- Add capability declaration
+
+**Breaking changes**: None (additive)
+
+### Phase 2: Update Documentation (v0.27.0)
+
+- Document elicitation-based flow as primary
+- Mark manual tools as deprecated
+- Update examples and guides
+
+**Breaking changes**: None (documentation only)
+
+### Phase 3: Remove Manual Tools (v0.28.0)
+
+- Remove `provision_nextcloud_access` tool
+- Remove `check_provisioning_status` tool (status in error message)
+- Remove `revoke_nextcloud_access` (or keep for explicit revocation?)
+
+**Breaking changes**: Yes (removed tools)
+
+### Phase 4: Optimize (v0.29.0+)
+
+- Add elicitation result caching
+- Implement retry strategies
+- Add metrics and monitoring
+
+## Testing
+
+### Test Cases
+
+1. **First-Time User Flow**
+   ```python
+   @pytest.mark.oauth
+   async def test_elicitation_first_time_user(nc_mcp_oauth_client):
+       """Test that first tool call triggers elicitation."""
+       # User has no provisioning
+       with pytest.raises(McpError) as exc:
+           await nc_mcp_oauth_client.call_tool("nc_notes_list_notes")
+
+       # Should get ElicitationRequired error
+       assert exc.value.code == -32000
+       assert "elicitations" in exc.value.data
+       assert exc.value.data["elicitations"][0]["mode"] == "url"
+
+       # Verify URL is valid OAuth URL
+       url = exc.value.data["elicitations"][0]["url"]
+       assert "oauth" in url
+       assert "elicitationId" in url
+   ```
+
+2. **Progress Tracking**
+   ```python
+   @pytest.mark.oauth
+   async def test_elicitation_progress_tracking(nc_mcp_oauth_client):
+       """Test progress tracking during OAuth flow."""
+       # Trigger elicitation
+       elicitation_id = trigger_elicitation()
+
+       # Start tracking
+       track_task = asyncio.create_task(
+           nc_mcp_oauth_client.track_elicitation(
+               elicitation_id=elicitation_id,
+               progress_token="test-token"
+           )
+       )
+
+       # Simulate OAuth completion
+       await asyncio.sleep(1)
+       await complete_oauth_flow(elicitation_id)
+
+       # Track should complete
+       result = await track_task
+       assert result["status"] == "complete"
+   ```
+
+3. **Auto-Retry After Provisioning**
+   ```python
+   @pytest.mark.oauth
+   async def test_auto_retry_after_provisioning(nc_mcp_oauth_client):
+       """Test that client auto-retries after elicitation."""
+       # Mock client that auto-retries on ElicitationRequired
+       client = AutoRetryMcpClient(nc_mcp_oauth_client)
+
+       # First call triggers elicitation, client handles it, retries
+       result = await client.call_tool_with_elicitation("nc_notes_list_notes")
+
+       # Should succeed after provisioning
+       assert result.success
+       assert "notes" in result.data
+   ```
+
+4. **Timeout Handling**
+   ```python
+   @pytest.mark.oauth
+   async def test_elicitation_timeout(nc_mcp_oauth_client):
+       """Test timeout if user doesn't complete OAuth."""
+       elicitation_id = trigger_elicitation()
+
+       # Track with short timeout
+       with pytest.raises(McpError, match="timed out"):
+           await nc_mcp_oauth_client.track_elicitation(
+               elicitation_id=elicitation_id,
+               timeout=5  # 5 seconds
+           )
+   ```
+
+## Security Considerations
+
+### Out-of-Band OAuth Flow
+
+**Benefit**: OAuth credentials never pass through MCP client
+- User enters credentials directly on IdP page
+- MCP server receives only authorization code
+- Client never sees passwords or refresh tokens
+
+**Threat mitigation**:
+- **Credential theft**: Client can't intercept credentials (out-of-band)
+- **Token exposure**: Client never receives Nextcloud refresh tokens
+- **CSRF**: State parameter validates OAuth callback
+- **URL tampering**: Elicitation ID ties OAuth flow to user session
+
+### Elicitation ID as Security Token
+
+The `elicitationId` serves as a capability token:
+- Cryptographically random (UUID v4)
+- Single-use (invalidated after completion)
+- Time-limited (expires after timeout)
+- User-scoped (tied to user session)
+
+**Validation**:
+```python
+async def validate_elicitation_id(elicitation_id: str, user_id: str) -> bool:
+    """Validate that elicitation belongs to user and is still valid."""
+    elicitation = await storage.get_elicitation(elicitation_id)
+
+    if not elicitation:
+        return False
+
+    # Check ownership
+    if elicitation["user_id"] != user_id:
+        logger.warning(f"Elicitation ID mismatch: {elicitation_id}")
+        return False
+
+    # Check expiry
+    if elicitation["expires_at"] < datetime.now(timezone.utc):
+        return False
+
+    # Check not already used
+    if elicitation["status"] != "pending":
+        return False
+
+    return True
+```
+
+### Progress Tracking Security
+
+**Risk**: Progress token reuse across users
+
+**Mitigation**:
+- Progress tokens tied to elicitation ID
+- Elicitation ID tied to user session
+- Server validates ownership before sending updates
+
+## Consequences
+
+### Positive
+
+1. **Better UX**: Automatic URL opening, no manual copy/paste
+2. **Seamless Flow**: Auto-retry after provisioning
+3. **Progress Feedback**: User knows when OAuth is complete
+4. **Spec Compliance**: Implements SEP-1036 correctly
+5. **Secure by Design**: Out-of-band OAuth prevents credential exposure
+6. **Simpler API**: No explicit provisioning tools needed
+
+### Negative
+
+1. **Client Dependency**: Requires client support for URL elicitation
+2. **Complexity**: More moving parts (elicitation tracking, callbacks)
+3. **Polling**: Progress tracking uses polling (not ideal)
+4. **Breaking Change**: Removes manual provisioning tools (in v0.28.0)
+
+### Neutral
+
+1. **Storage Requirements**: Need to store elicitation state
+2. **Timeout Management**: Must handle long-running OAuth flows
+3. **Fallback Support**: Still need compatibility for older clients
+
+## Alternatives Considered
+
+### 1. Keep Manual Tools Only (Rejected)
+
+**Pros**: Simple, no client changes needed
+**Cons**: Poor UX, doesn't leverage SEP-1036
+
+**Rejection reason**: SEP-1036 provides better UX and security
+
+### 2. Form Mode Elicitation (Rejected)
+
+**Pros**: No browser redirect needed
+**Cons**: Would expose OAuth credentials to client (security violation)
+
+**Rejection reason**: Form mode only for non-sensitive data per SEP-1036
+
+### 3. Hybrid: Both Tools and Elicitation (Considered)
+
+**Pros**: Maximum compatibility, gradual migration
+**Cons**: API duplication, maintenance burden, confusing for users
+
+**Decision**: Support during migration (v0.26-0.27), remove in v0.28
+
+### 4. WebSocket for Progress (Rejected)
+
+**Pros**: Real-time updates instead of polling
+**Cons**: MCP spec uses polling pattern, adds complexity
+
+**Rejection reason**: Follow spec pattern (polling via elicitation/track)
+
+## Interim Implementation: Inline Form Elicitation (Pre-SEP-1036)
+
+**Note**: SEP-1036 (URL mode elicitation) is not yet available in the stable MCP Python SDK. As a temporary workaround, we've implemented a simplified version using the current **inline form elicitation** API.
+
+### What Changed
+
+Instead of waiting for URL mode elicitation, we implemented a `check_logged_in` tool that:
+
+1. Checks if the user has completed Flow 2 (resource provisioning)
+2. If logged in, returns `"yes"`
+3. If not logged in, uses **inline form elicitation** to prompt the user
+
+### Implementation Details
+
+**New Tool**: `check_logged_in`
+
+```python
+# nextcloud_mcp_server/server/oauth_tools.py
+
+class LoginConfirmation(BaseModel):
+    """Schema for login confirmation elicitation."""
+    acknowledged: bool = Field(
+        default=False,
+        description="Check this box after completing login at the provided URL",
+    )
+
+@mcp.tool(name="check_logged_in")
+@require_scopes("openid")
+async def tool_check_logged_in(ctx: Context, user_id: Optional[str] = None) -> str:
+    """Check if user is logged in and elicit login if needed."""
+    # Check if already logged in
+    status = await get_provisioning_status(ctx, user_id)
+    if status.is_provisioned:
+        return "yes"
+
+    # Generate OAuth URL for Flow 2
+    auth_url = generate_oauth_url_for_flow2(...)
+
+    # Use inline form elicitation (current MCP API)
+    result = await ctx.elicit(
+        message=f"Please log in to Nextcloud at the following URL:\n\n{auth_url}\n\nAfter completing the login, check the box below and click OK.",
+        schema=LoginConfirmation,
+    )
+
+    if result.action == "accept":
+        # Verify login succeeded
+        status = await get_provisioning_status(ctx, user_id)
+        return "yes" if status.is_provisioned else "Login not detected"
+    elif result.action == "decline":
+        return "Login declined by user."
+    else:
+        return "Login cancelled by user."
+```
+
+**OAuth Routes** (added to `app.py`):
+
+```python
+# Flow 2 routes for resource provisioning
+routes.append(
+    Route("/oauth/authorize-nextcloud", oauth_authorize_nextcloud, methods=["GET"])
+)
+routes.append(
+    Route("/oauth/callback-nextcloud", oauth_callback_nextcloud, methods=["GET"])
+)
+```
+
+### User Experience
+
+```
+User: *calls check_logged_in tool*
+
+MCP Client: Displays form elicitation
+┌─────────────────────────────────────────────────────────┐
+│ Please log in to Nextcloud at the following URL:      │
+│                                                         │
+│ http://localhost:8000/oauth/authorize-nextcloud?...    │
+│                                                         │
+│ After completing the login, check the box below and    │
+│ click OK.                                               │
+│                                                         │
+│ ☐ Check this box after completing login                │
+│                                                         │
+│ [Accept] [Decline] [Cancel]                            │
+└─────────────────────────────────────────────────────────┘
+
+User: *copies URL, opens in browser, completes OAuth*
+User: *checks box and clicks Accept*
+
+MCP Server: Verifies login and returns "yes"
+```
+
+### Limitations of Interim Approach
+
+1. **Manual URL Handling**: User must manually copy and paste the URL (not clickable)
+2. **No Automatic Browser Opening**: Client doesn't automatically open the URL
+3. **No Progress Tracking**: Can't track OAuth completion status in real-time
+4. **URL in Message Text**: Login URL embedded in plain text message (not as structured field)
+5. **Client-Side Confirmation**: Relies on user clicking "OK" after OAuth (honor system)
+
+### Why Not Use URL Mode Now?
+
+The current stable MCP Python SDK (`main` branch) only supports **inline form elicitation**:
+
+```python
+# Current API (no 'mode' parameter)
+class ElicitRequestParams(RequestParams):
+    message: str
+    requestedSchema: ElicitRequestedSchema
+    # No 'mode', 'url', or 'elicitationId' fields
+```
+
+URL mode elicitation (`mode: "url"`) is only available in the SEP-1036 branch, which has not been merged to `main` yet.
+
+### Migration to URL Mode (When SEP-1036 Lands)
+
+Once SEP-1036 is merged and available in the stable SDK, we will migrate to URL mode elicitation:
+
+**Before (Current Workaround)**:
+```python
+result = await ctx.elicit(
+    message=f"Please log in at: {auth_url}\n\nClick OK after login.",
+    schema=LoginConfirmation,
+)
+```
+
+**After (URL Mode)**:
+```python
+result = await ctx.session.elicit_url(
+    message="Please log in to Nextcloud to authorize this MCP server.",
+    url=auth_url,
+    elicitation_id=elicitation_id,
+)
+```
+
+**Benefits of migration**:
+- Automatic URL opening (with user consent)
+- Clickable URLs in client UI
+- Progress tracking via `elicitation/track`
+- Better security (URL not in message text)
+- Auto-retry support
+
+### Testing
+
+Integration tests validate the current inline form elicitation:
+
+```python
+# tests/server/oauth/test_login_elicitation.py
+
+async def test_check_logged_in_already_authenticated(nc_mcp_oauth_client):
+    """Test immediate 'yes' for authenticated users."""
+    result = await nc_mcp_oauth_client.call_tool("check_logged_in", arguments={})
+    assert "yes" in result.content[0].text.lower()
+
+async def test_check_logged_in_url_format(nc_mcp_oauth_client):
+    """Test that login URL (when needed) contains correct OAuth parameters."""
+    result = await nc_mcp_oauth_client.call_tool("check_logged_in", arguments={})
+    response_text = result.content[0].text
+
+    # If URL present, validate OAuth parameters
+    if "http" in response_text:
+        assert "response_type=code" in response_text
+        assert "client_id=" in response_text
+        assert "redirect_uri=" in response_text
+        assert "openid" in response_text
+```
+
+### Future Work
+
+- **Monitor SEP-1036**: Watch for merge to MCP Python SDK `main` branch
+- **Implement URL Mode**: Once available, migrate `check_logged_in` to use `ctx.session.elicit_url()`
+- **Add Progress Tracking**: Implement `elicitation/track` endpoint for OAuth completion status
+- **Implement Error-Triggered Elicitation**: Use `@require_provisioning` decorator to return `ElicitationRequired` errors
+- **Remove Manual Workaround**: Deprecate inline form approach once URL mode is stable
+
+## References
+
+- [SEP-1036: URL Mode Elicitation](https://github.com/modelcontextprotocol/specification/pull/887)
+- [MCP Elicitation Specification](https://modelcontextprotocol.io/specification/draft/client/elicitation)
+- [ADR-004: Federated Authentication Architecture](./ADR-004-mcp-application-oauth.md)
+- [ADR-005: Token Audience Validation](./ADR-005-token-audience-validation.md)
+- [RFC 8252: OAuth 2.0 for Native Apps](https://datatracker.ietf.org/doc/html/rfc8252)
+
+## Implementation Checklist
+
+### Interim Implementation (Inline Form Elicitation)
+
+- [x] Create `check_logged_in` tool with inline form elicitation
+- [x] Register Flow 2 OAuth routes (`/oauth/authorize-nextcloud`, `/oauth/callback-nextcloud`)
+- [x] Write integration tests for login elicitation flow
+- [x] Update ADR-006 with interim implementation documentation
+- [x] Add `LoginConfirmation` schema for elicitation
+- [ ] Run tests to validate implementation
+
+### Future Work (URL Mode Elicitation - Post SEP-1036)
+
+- [ ] Implement `@require_provisioning` decorator with ElicitationRequired error
+- [ ] Add `elicitation/track` request handler
+- [ ] Update OAuth callback to mark elicitations complete
+- [ ] Add elicitation storage (ID, user, status, timestamps)
+- [ ] Update all Nextcloud tools with `@require_provisioning`
+- [ ] Add URL elicitation capability declaration
+- [ ] Write tests for progress tracking
+- [ ] Update documentation with URL mode examples
+- [ ] Add migration guide for manual tools → elicitation
+- [ ] Migrate `check_logged_in` from inline form to URL mode
+- [ ] Keep manual tools with deprecation warnings (v0.26-0.27)
+- [ ] Remove manual tools (v0.28.0)
+- [ ] Update CHANGELOG.md with migration timeline

docs/ADR-008-mcp-sampling-for-semantic-search.md

@@ -0,0 +1,647 @@
+# ADR-008: MCP Sampling for Multi-App Semantic Search with RAG
+
+**Status**: Proposed
+**Date**: 2025-01-11
+**Depends On**: ADR-007 (Background Vector Sync)
+
+## Context
+
+ADR-007 established a background synchronization architecture that maintains a vector database of Nextcloud content across multiple apps (notes, calendar, deck, files, contacts), enabling semantic search via the `nc_semantic_search` tool. This tool returns a list of relevant documents with excerpts, similarity scores, and metadata—providing the raw materials for answering user questions.
+
+However, users typically don't want a list of documents—they want answers to their questions. When a user asks "What are my project goals?" or "When is my next dentist appointment?", they expect a natural language response that synthesizes information from multiple sources and document types, not a ranked list of excerpts. This is the pattern of Retrieval-Augmented Generation (RAG): retrieve relevant context from all Nextcloud apps, then generate a cohesive answer.
+
+The challenge is: who should generate the answer, and how?
+
+**Option 1: Server-side LLM**
+The MCP server could maintain its own LLM connection (OpenAI API, Ollama, etc.), construct prompts from retrieved documents, and return generated answers directly. This approach has significant drawbacks:
+
+- **Duplicate infrastructure**: MCP clients (like Claude Desktop) already have LLM capabilities. The server would duplicate this with its own LLM integration, API keys, and configuration.
+- **Cost and billing**: The server operator bears LLM costs for all users, creating billing and quota management challenges.
+- **Limited model choice**: Users are locked into whatever LLM the server configures. They cannot choose their preferred model or provider.
+- **Privacy concerns**: User queries and document contents flow through a server-controlled LLM, creating a potential privacy boundary.
+- **Configuration complexity**: Server operators must configure embedding services (for search) AND generation models (for answers), each with different API keys, rate limits, and failure modes.
+
+**Option 2: Return documents, let client generate**
+The server could simply return retrieved documents and rely on the MCP client's existing LLM to generate answers. The user would call `nc_notes_semantic_search`, receive documents, and then the client would include those documents in its context when responding to the user's original question. This approach also has limitations:
+
+- **Context window waste**: The client must include all document content in its context window, even if only small excerpts are relevant. For 5-10 documents, this can consume significant context space.
+- **Inconsistent behavior**: Whether the client synthesizes an answer or just displays documents depends on the client's implementation and the user's conversational style. There's no guaranteed answer generation.
+- **Poor citations**: The client may generate an answer but fail to cite which specific documents were used, making it hard to verify claims.
+- **User confusion**: Users see a tool that returns "search results" rather than "answers", requiring them to explicitly ask for synthesis.
+
+**Option 3: MCP Sampling**
+The Model Context Protocol specification includes a **sampling** capability that allows MCP servers to request LLM completions from their clients. The server constructs a prompt with retrieved context, sends it to the client via `sampling/createMessage`, and the client's LLM generates a response that the server can return as a tool result.
+
+This approach combines the best of both options:
+
+- **No server-side LLM**: The server has no API keys, no LLM configuration, no billing concerns.
+- **User choice**: The MCP client controls which LLM is used (Claude, GPT-4, local Ollama) and who pays for it.
+- **User transparency**: MCP clients SHOULD present sampling requests to users for approval, making it clear when the server is requesting an LLM call.
+- **Consistent citations**: The server constructs a prompt that explicitly includes document references, ensuring generated answers cite sources.
+- **Single tool call**: Users call one tool (`nc_notes_semantic_search_answer`) and receive a complete answer with citations—no multi-turn conversation needed.
+
+The sampling approach shifts responsibility appropriately: the MCP server is responsible for information retrieval and context construction (its expertise), while the MCP client is responsible for LLM access and user preferences (its expertise). This follows the MCP design philosophy of separating concerns between servers (data access) and clients (user interaction).
+
+However, sampling introduces new considerations:
+
+**Client compatibility**: Not all MCP clients implement sampling. The server must gracefully degrade when sampling is unavailable, falling back to returning documents without generated answers.
+
+**Latency**: Sampling adds a full round-trip to the client and back, plus LLM generation time. A typical flow involves: (1) client calls tool, (2) server retrieves documents, (3) server requests sampling from client, (4) client generates answer, (5) server returns answer to client. This can take 2-5 seconds depending on LLM speed, compared to 100-500ms for document retrieval alone.
+
+**User approval**: MCP clients SHOULD prompt users to approve sampling requests, allowing users to review the prompt before sending it to their LLM. This is a privacy and security feature (prevents servers from making arbitrary LLM requests) but adds interaction friction.
+
+**Prompt engineering**: The server must construct effective prompts that guide the LLM to generate useful, well-cited answers. Unlike Option 1 where the server controls the LLM directly, the server has less control over how the prompt is interpreted.
+
+Despite these considerations, MCP sampling provides the most principled solution for RAG-enhanced semantic search. It respects the client-server boundary, avoids duplicate infrastructure, and delivers the user experience users expect from semantic search tools.
+
+This ADR proposes adding a new tool, `nc_semantic_search_answer`, that uses MCP sampling to generate natural language answers from retrieved Nextcloud content across all indexed apps (notes, calendar, deck, files, contacts).
+
+## Decision
+
+We will implement a new MCP tool `nc_semantic_search_answer` that retrieves relevant documents via vector similarity search across all indexed Nextcloud apps and uses MCP sampling to generate natural language answers. The tool will construct a prompt that includes the user's original query and excerpts from retrieved documents (notes, calendar events, deck cards, files, contacts), request an LLM completion via `ctx.session.create_message()`, and return the generated answer along with source citations.
+
+The existing `nc_semantic_search` tool will remain unchanged, providing users with a choice: call the original tool for raw document results, or call the new sampling-enhanced tool for generated answers. This dual-tool approach respects different use cases—some users want to browse documents, others want direct answers.
+
+### API Design
+
+**Tool Signature**:
+```python
+@mcp.tool()
+@require_scopes("semantic:read")
+async def nc_semantic_search_answer(
+    query: str,
+    ctx: Context,
+    limit: int = 5,
+    score_threshold: float = 0.7,
+    max_answer_tokens: int = 500,
+) -> SamplingSearchResponse
+```
+
+**Parameters**:
+- `query`: The user's natural language question
+- `ctx`: MCP context for session access
+- `limit`: Maximum documents to retrieve (default 5)
+- `score_threshold`: Minimum similarity score 0-1 (default 0.7)
+- `max_answer_tokens`: Maximum tokens for generated answer (default 500)
+
+**Response Model**:
+```python
+class SamplingSearchResponse(BaseResponse):
+    query: str                              # Original user query
+    generated_answer: str                   # LLM-generated answer
+    sources: list[SemanticSearchResult]     # Supporting documents
+    total_found: int                        # Total matching documents
+    search_method: str = "semantic_sampling"
+    model_used: str | None = None           # Model that generated answer
+    stop_reason: str | None = None          # Why generation stopped
+```
+
+The response includes both the generated answer (for direct user consumption) and the source documents (for verification and citation). The `model_used` field records which LLM generated the answer, allowing users to understand which model provided the response.
+
+### Sampling API Usage
+
+The tool uses the MCP Python SDK's `ServerSession.create_message()` API:
+
+```python
+from mcp.types import SamplingMessage, TextContent, ModelPreferences, ModelHint
+
+# Construct prompt with retrieved context
+prompt = (
+    f"{query}\n\n"
+    f"Here are relevant documents from Nextcloud (notes, calendar events, deck cards, files, contacts):\n\n"
+    f"{context}\n\n"
+    f"Based on the documents above, please provide a comprehensive answer. "
+    f"Cite the document numbers when referencing specific information."
+)
+
+# Request LLM completion via MCP sampling
+sampling_result = await ctx.session.create_message(
+    messages=[
+        SamplingMessage(
+            role="user",
+            content=TextContent(type="text", text=prompt),
+        )
+    ],
+    max_tokens=max_answer_tokens,
+    temperature=0.7,
+    model_preferences=ModelPreferences(
+        hints=[ModelHint(name="claude-3-5-sonnet")],
+        intelligencePriority=0.8,
+        speedPriority=0.5,
+    ),
+    include_context="thisServer",
+)
+
+# Extract answer from response
+if sampling_result.content.type == "text":
+    generated_answer = sampling_result.content.text
+```
+
+**Key parameters**:
+- `messages`: Chat-style messages with role ("user" or "assistant") and content
+- `max_tokens`: Limits response length to control costs and latency
+- `temperature`: 0.7 balances creativity with consistency for factual answers
+- `model_preferences`: Hints suggest Claude Sonnet for balanced intelligence/speed
+- `include_context`: "thisServer" includes MCP server context in client's LLM call
+
+The `include_context` parameter is particularly important. When set to "thisServer", the MCP client provides its LLM with context about the server's capabilities, tools, and resources. This allows the LLM to reference the Nextcloud MCP server when generating answers, creating more contextually appropriate responses. For example, the LLM might say "Based on your Nextcloud Notes..." rather than generic phrasing.
+
+### Prompt Construction
+
+The prompt construction follows a structured template:
+
+```
+[User's original query]
+
+Here are relevant documents from Nextcloud (notes, calendar events, deck cards, files, contacts):
+
+[Document 1]
+Type: note
+Title: Project Kickoff Notes
+Category: Work
+Excerpt: The primary goal for Q1 2025 is to improve semantic search...
+Relevance Score: 0.92
+
+[Document 2]
+Type: calendar_event
+Title: Team Planning Meeting
+Location: Conference Room A
+Excerpt: Scheduled for Jan 15 at 2pm. Agenda: Discuss Q1 objectives and timeline...
+Relevance Score: 0.88
+
+[Document 3]
+Type: deck_card
+Title: Implement semantic search
+Labels: feature, high-priority
+Excerpt: This card tracks the semantic search implementation. Due: Jan 30...
+Relevance Score: 0.85
+
+Based on the documents above, please provide a comprehensive answer.
+Cite the document numbers when referencing specific information.
+```
+
+This structure ensures:
+- The user's original query is preserved verbatim
+- Documents are clearly delineated and numbered for citation
+- Metadata (title, category, score) provides context
+- Explicit instruction to cite sources encourages proper attribution
+
+The prompt is intentionally simple and fixed (not configurable). Allowing users to customize the prompt would complicate the API and introduce prompt injection risks. The fixed structure ensures consistent, well-cited answers across all users.
+
+### Fallback Behavior
+
+Sampling may fail for several reasons:
+- Client doesn't support sampling (e.g., MCP Inspector without callbacks)
+- User declines the sampling request
+- Network errors during sampling round-trip
+- LLM generation errors
+
+The tool handles all failures gracefully by falling back to returning documents without a generated answer:
+
+```python
+try:
+    sampling_result = await ctx.session.create_message(...)
+    generated_answer = sampling_result.content.text
+except Exception as e:
+    logger.warning(f"Sampling failed: {e}, returning search results only")
+    generated_answer = (
+        f"[Sampling unavailable: {str(e)}]\n\n"
+        f"Found {total_found} relevant documents. Please review the sources below."
+    )
+```
+
+This ensures the tool always returns useful information—either a generated answer or the underlying documents—rather than failing completely. The user knows sampling was attempted (via the `[Sampling unavailable]` prefix) and can still access the retrieved context.
+
+### No Results Handling
+
+When semantic search finds no relevant documents (all below `score_threshold`), the tool returns a clear message without attempting sampling:
+
+```python
+if not search_response.results:
+    return SamplingSearchResponse(
+        query=query,
+        generated_answer="No relevant documents found in your Nextcloud content for this query.",
+        sources=[],
+        total_found=0,
+        search_method="semantic_sampling",
+        success=True,
+    )
+```
+
+This avoids wasting a sampling call (and user approval) when there's no content to base an answer on.
+
+### User Experience Flow
+
+**Typical successful flow**:
+1. User calls `nc_semantic_search_answer` with query "What are my Q1 2025 objectives?"
+2. Server retrieves 5 relevant documents via vector search (2 notes, 2 calendar events, 1 deck card)
+3. Server constructs prompt with document excerpts showing mixed content types
+4. Server sends `sampling/createMessage` request to client
+5. Client prompts user: "MCP server wants to generate an answer using these documents. Allow?"
+6. User approves (or client auto-approves based on configuration)
+7. Client sends prompt to LLM (Claude, GPT-4, etc.)
+8. LLM generates answer with citations: "Based on Document 1 (note: Project Kickoff), Document 2 (calendar: Team Planning Meeting), and Document 3 (deck card: Implement semantic search)..."
+9. Client returns answer to server
+10. Server returns `SamplingSearchResponse` with answer and sources
+11. User sees complete answer with citations across multiple Nextcloud apps
+
+**Fallback flow** (sampling unavailable):
+1-3. Same as above
+4. Server attempts `ctx.session.create_message()`
+5. Client raises exception: "Sampling not supported"
+6. Server catches exception, logs warning
+7. Server returns `SamplingSearchResponse` with documents and "[Sampling unavailable]" message
+8. User sees raw documents instead of generated answer
+
+**No results flow**:
+1-2. Same as above but no documents match threshold
+3. Server returns `SamplingSearchResponse` with "No relevant documents" message
+4. No sampling attempted (no prompt sent)
+5. User sees clear "not found" message
+
+This three-tier approach (answer → documents → error message) ensures users always receive useful feedback appropriate to the situation.
+
+## Implementation
+
+### Response Model
+
+Add to `nextcloud_mcp_server/models/semantic.py` (new file for semantic search models):
+
+```python
+from pydantic import Field
+
+class SamplingSearchResponse(BaseResponse):
+    """Response from semantic search with LLM-generated answer via MCP sampling.
+
+    This response includes both a generated natural language answer (created by
+    the MCP client's LLM via sampling) and the source documents used to generate
+    that answer. Users can read the answer for quick information and review
+    sources for verification and deeper exploration.
+
+    Attributes:
+        query: The original user query
+        generated_answer: Natural language answer generated by client's LLM
+        sources: List of semantic search results used as context
+        total_found: Total number of matching documents found
+        search_method: Always "semantic_sampling" for this response type
+        model_used: Name of model that generated the answer (e.g., "claude-3-5-sonnet")
+        stop_reason: Why generation stopped ("endTurn", "maxTokens", etc.)
+    """
+
+    query: str = Field(..., description="Original user query")
+    generated_answer: str = Field(
+        ...,
+        description="LLM-generated answer based on retrieved documents"
+    )
+    sources: list[SemanticSearchResult] = Field(
+        default_factory=list,
+        description="Source documents with excerpts and relevance scores"
+    )
+    total_found: int = Field(..., description="Total matching documents")
+    search_method: str = Field(
+        default="semantic_sampling",
+        description="Search method used"
+    )
+    model_used: str | None = Field(
+        default=None,
+        description="Model that generated the answer"
+    )
+    stop_reason: str | None = Field(
+        default=None,
+        description="Reason generation stopped"
+    )
+```
+
+### Tool Implementation
+
+Add to `nextcloud_mcp_server/server/semantic.py` (new file for semantic search tools):
+
+```python
+import logging
+from mcp.types import ModelHint, ModelPreferences, SamplingMessage, TextContent
+
+logger = logging.getLogger(__name__)
+
+
+@mcp.tool()
+@require_scopes("semantic:read")
+async def nc_semantic_search_answer(
+    query: str,
+    ctx: Context,
+    limit: int = 5,
+    score_threshold: float = 0.7,
+    max_answer_tokens: int = 500,
+) -> SamplingSearchResponse:
+    """
+    Semantic search with LLM-generated answer using MCP sampling.
+
+    Retrieves relevant documents from Nextcloud across all indexed apps (notes,
+    calendar, deck, files, contacts) using vector similarity search, then uses
+    MCP sampling to request the client's LLM to generate a natural language
+    answer based on the retrieved context.
+
+    This tool combines the power of semantic search (finding relevant content
+    across all your Nextcloud apps) with LLM generation (synthesizing that
+    content into coherent answers). The generated answer includes citations
+    to specific documents with their types, allowing users to verify claims
+    and explore sources.
+
+    The LLM generation happens client-side via MCP sampling. The MCP client
+    controls which model is used, who pays for it, and whether to prompt the
+    user for approval. This keeps the server simple (no LLM API keys needed)
+    while giving users full control over their LLM interactions.
+
+    Args:
+        query: Natural language question to answer (e.g., "What are my Q1 objectives?" or "When is my next dentist appointment?")
+        ctx: MCP context for session access
+        limit: Maximum number of documents to retrieve (default: 5)
+        score_threshold: Minimum similarity score 0-1 (default: 0.7)
+        max_answer_tokens: Maximum tokens for generated answer (default: 500)
+
+    Returns:
+        SamplingSearchResponse containing:
+        - generated_answer: Natural language answer with citations
+        - sources: List of documents with excerpts and relevance scores
+        - model_used: Which model generated the answer
+        - stop_reason: Why generation stopped
+
+    Note: Requires MCP client to support sampling. If sampling is unavailable,
+    the tool gracefully degrades to returning documents with an explanation.
+    The client may prompt the user to approve the sampling request.
+
+    Examples:
+        >>> # Query about objectives across multiple apps
+        >>> result = await nc_semantic_search_answer(
+        ...     query="What are my Q1 2025 project goals?",
+        ...     ctx=ctx
+        ... )
+        >>> print(result.generated_answer)
+        "Based on Document 1 (note: Project Kickoff), Document 2 (calendar event:
+        Q1 Planning Meeting), and Document 3 (deck card: Implement semantic search),
+        your main goals are: 1) Improve semantic search accuracy by 20%,
+        2) Deploy new embedding model, 3) Reduce indexing latency..."
+
+        >>> # Query about appointments
+        >>> result = await nc_semantic_search_answer(
+        ...     query="When is my next dentist appointment?",
+        ...     ctx=ctx,
+        ...     limit=10
+        ... )
+        >>> len(result.sources)  # Calendar events and related notes
+        3
+    """
+    # 1. Retrieve relevant documents via existing semantic search
+    search_response = await nc_semantic_search(
+        query=query,
+        ctx=ctx,
+        limit=limit,
+        score_threshold=score_threshold,
+    )
+
+    # 2. Handle no results case - don't waste a sampling call
+    if not search_response.results:
+        logger.debug(f"No documents found for query: {query}")
+        return SamplingSearchResponse(
+            query=query,
+            generated_answer="No relevant documents found in your Nextcloud content for this query.",
+            sources=[],
+            total_found=0,
+            search_method="semantic_sampling",
+            success=True,
+        )
+
+    # 3. Construct context from retrieved documents
+    context_parts = []
+    for idx, result in enumerate(search_response.results, 1):
+        context_parts.append(
+            f"[Document {idx}]\n"
+            f"Title: {result.title}\n"
+            f"Category: {result.category}\n"
+            f"Excerpt: {result.excerpt}\n"
+            f"Relevance Score: {result.score:.2f}\n"
+        )
+
+    context = "\n".join(context_parts)
+
+    # 4. Construct prompt - reuse user's query, add context and instructions
+    prompt = (
+        f"{query}\n\n"
+        f"Here are relevant documents from Nextcloud (notes, calendar events, deck cards, files, contacts):\n\n"
+        f"{context}\n\n"
+        f"Based on the documents above, please provide a comprehensive answer. "
+        f"Cite the document numbers when referencing specific information."
+    )
+
+    logger.debug(
+        f"Requesting sampling for query: {query} "
+        f"({len(search_response.results)} documents retrieved)"
+    )
+
+    # 5. Request LLM completion via MCP sampling
+    try:
+        sampling_result = await ctx.session.create_message(
+            messages=[
+                SamplingMessage(
+                    role="user",
+                    content=TextContent(type="text", text=prompt),
+                )
+            ],
+            max_tokens=max_answer_tokens,
+            temperature=0.7,
+            model_preferences=ModelPreferences(
+                hints=[ModelHint(name="claude-3-5-sonnet")],
+                intelligencePriority=0.8,
+                speedPriority=0.5,
+            ),
+            include_context="thisServer",
+        )
+
+        # 6. Extract answer from sampling response
+        if sampling_result.content.type == "text":
+            generated_answer = sampling_result.content.text
+        else:
+            # Handle non-text responses (shouldn't happen for text prompts)
+            generated_answer = (
+                f"Received non-text response of type: {sampling_result.content.type}"
+            )
+            logger.warning(
+                f"Unexpected content type from sampling: {sampling_result.content.type}"
+            )
+
+        logger.info(
+            f"Sampling successful: model={sampling_result.model}, "
+            f"stop_reason={sampling_result.stopReason}"
+        )
+
+        return SamplingSearchResponse(
+            query=query,
+            generated_answer=generated_answer,
+            sources=search_response.results,
+            total_found=search_response.total_found,
+            search_method="semantic_sampling",
+            model_used=sampling_result.model,
+            stop_reason=sampling_result.stopReason,
+            success=True,
+        )
+
+    except Exception as e:
+        # Fallback: Return documents without generated answer
+        logger.warning(
+            f"Sampling failed ({type(e).__name__}: {e}), "
+            f"returning search results only"
+        )
+
+        return SamplingSearchResponse(
+            query=query,
+            generated_answer=(
+                f"[Sampling unavailable: {str(e)}]\n\n"
+                f"Found {search_response.total_found} relevant documents. "
+                f"Please review the sources below."
+            ),
+            sources=search_response.results,
+            total_found=search_response.total_found,
+            search_method="semantic_sampling_fallback",
+            success=True,
+        )
+```
+
+### Import Updates
+
+Add to top of `nextcloud_mcp_server/server/semantic.py`:
+
+```python
+from mcp.types import ModelHint, ModelPreferences, SamplingMessage, TextContent
+```
+
+Add to `nextcloud_mcp_server/models/semantic.py` exports:
+
+```python
+__all__ = [
+    "SemanticSearchResult",
+    "SemanticSearchResponse",
+    "SamplingSearchResponse",
+]
+```
+
+## Consequences
+
+### Benefits
+
+**Improved User Experience**: Users receive direct answers to questions rather than lists of documents, matching expectations from modern AI interfaces.
+
+**Proper Attribution**: Generated answers include citations to source documents, allowing users to verify claims and explore deeper.
+
+**No Server-Side LLM**: The server has no LLM dependencies, API keys, or billing concerns. All LLM interactions happen client-side.
+
+**User Control**: MCP clients control which model is used and may prompt users to approve sampling requests, maintaining transparency and user agency.
+
+**Graceful Degradation**: The tool works even when sampling is unavailable, falling back to returning documents. Existing clients continue working without changes.
+
+**Consistent Architecture**: Follows MCP's client-server separation: servers provide data access, clients provide user interaction and LLM capabilities.
+
+### Limitations
+
+**Sampling Support Required**: Not all MCP clients implement sampling. Users with basic clients see fallback behavior (documents without answers).
+
+**Added Latency**: Sampling adds 2-5 seconds to tool execution due to client round-trip and LLM generation time. Users must wait longer for answers than for raw search results.
+
+**User Approval Friction**: MCP clients SHOULD prompt users to approve sampling requests. This adds an extra interaction step before answers are generated.
+
+**Limited Prompt Control**: The server cannot fully control how the client's LLM interprets the prompt. Different models may generate different quality answers.
+
+**No Caching**: Each query requires a new sampling call. The server doesn't cache generated answers (clients may cache if they choose).
+
+**Token Costs**: LLM generation consumes tokens from the user's or client's quota. Heavy users may incur costs or hit rate limits.
+
+### Performance Characteristics
+
+**Typical latency**:
+- Document retrieval (vector search): 100-300ms
+- Sampling round-trip (client communication): 50-200ms
+- LLM generation (client-side): 1-4 seconds
+- **Total**: 2-5 seconds end-to-end
+
+**Throughput**: Sampling is fully async. The server can handle multiple concurrent sampling requests (limited by MCP client's concurrency, not server capacity).
+
+**Resource usage**: Minimal server-side. No GPU, no LLM model loading, no large memory requirements. Sampling happens entirely client-side.
+
+### Security Considerations
+
+**Prompt Injection Risk**: If user queries contain adversarial text designed to manipulate LLM behavior, those queries are included verbatim in the sampling prompt. Mitigation: The structured prompt format and explicit instructions ("based on documents above") constrain LLM behavior.
+
+**Data Privacy**: User queries and document excerpts are sent to the client's LLM. For cloud LLMs (OpenAI, Anthropic), this means data leaves the server's control. Mitigation: MCP clients SHOULD present sampling requests to users for approval, making data flows transparent. Users choose their LLM provider.
+
+**Sampling Abuse**: A malicious server could spam sampling requests to drain user quotas. Mitigation: MCP clients control approval and can rate-limit or block sampling from misbehaving servers.
+
+## Alternatives Considered
+
+### Server-Side LLM Integration
+
+**Approach**: Configure the MCP server with OpenAI API key or local Ollama instance. Generate answers server-side.
+
+**Rejected Because**:
+- Duplicates LLM infrastructure that MCP clients already have
+- Creates billing and API key management burden for server operators
+- Locks users into server-configured models
+- Violates MCP's client-server separation principle
+
+### Multi-Turn Conversation Pattern
+
+**Approach**: `nc_notes_semantic_search` returns documents. User asks follow-up question. Client's LLM uses previous tool results as context.
+
+**Rejected Because**:
+- Requires users to know to ask follow-up questions
+- Consumes context window with full document content
+- Inconsistent behavior across clients
+- Poor citation (LLM may not reference which documents it used)
+
+### Pre-Generated Summaries
+
+**Approach**: Generate and cache summaries during indexing. Return summaries instead of excerpts.
+
+**Rejected Because**:
+- Summaries become stale as documents change
+- Summary quality depends on server-side LLM (same problems as server-side generation)
+- Summaries are generic, not tailored to specific queries
+
+### Streaming Responses
+
+**Approach**: Use MCP sampling with streaming to return incremental answer chunks.
+
+**Deferred Because**:
+- MCP sampling streaming support unclear in current specification
+- Adds significant implementation complexity
+- Tool responses in MCP are typically atomic
+- Can be added later without breaking changes
+
+## Related Decisions
+
+**ADR-007**: Background Vector Sync provides the semantic search infrastructure that this ADR enhances with LLM generation.
+
+**ADR-004**: Progressive Consent architecture applies to sampling—users consent to sampling requests via MCP client approval prompts.
+
+## References
+
+- [MCP Specification - Sampling](https://modelcontextprotocol.io/docs/specification/2025-06-18/client/sampling)
+- [MCP Python SDK - ServerSession.create_message](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/session.py#L215)
+- [MCP Python SDK - Sampling Example](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/sampling.py)
+- [MCP Types - SamplingMessage](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/types.py#L1038)
+- [MCP Types - CreateMessageResult](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/types.py#L1073)
+- [Retrieval-Augmented Generation (RAG) - Lewis et al. 2020](https://arxiv.org/abs/2005.11401)
+
+## Implementation Checklist
+
+- [ ] Create ADR-008 document (this file)
+- [ ] Create `nextcloud_mcp_server/models/semantic.py` for semantic search models
+- [ ] Add `SamplingSearchResponse` model to `nextcloud_mcp_server/models/semantic.py`
+- [ ] Create `nextcloud_mcp_server/server/semantic.py` for semantic search tools
+- [ ] Implement `nc_semantic_search_answer` tool in `nextcloud_mcp_server/server/semantic.py`
+- [ ] Add MCP sampling type imports (`SamplingMessage`, `TextContent`, etc.)
+- [ ] Write unit tests with mocked sampling (`tests/unit/server/test_semantic.py`)
+- [ ] Create integration tests (`tests/integration/test_sampling.py`)
+- [ ] Update `README.md` with new tool documentation in dedicated Semantic Search section
+- [ ] Update `CLAUDE.md` with sampling pattern guidance
+- [ ] Test with MCP client supporting sampling (Claude Desktop, MCP Inspector with callbacks)
+- [ ] Document client requirements and fallback behavior
+- [ ] Update oauth-architecture.md to add semantic:read scope
+- [ ] Create ADR-009 to document semantic:read scope decision

docs/ADR-009-semantic-search-oauth-scope.md

@@ -0,0 +1,268 @@
+# ADR-009: Generic `semantic:read` OAuth Scope for Multi-App Vector Search
+
+**Status**: Proposed
+**Date**: 2025-01-11
+**Depends On**: ADR-007 (Background Vector Sync), ADR-008 (MCP Sampling for Semantic Search)
+
+## Context
+
+ADR-007 established a background vector synchronization architecture that indexes content from multiple Nextcloud apps (notes, calendar events, deck cards, files, contacts) into a unified vector database. ADR-008 introduced semantic search tools (`nc_semantic_search`, `nc_semantic_search_answer`) that query this vector database and use MCP sampling to generate natural language answers.
+
+The question is: **What OAuth scopes should protect semantic search operations?**
+
+### Option 1: App-Specific Scopes
+
+Require users to have scopes for each app they want to search:
+
+```python
+@mcp.tool()
+@require_scopes("notes:read", "calendar:read", "deck:read", "files:read", "contacts:read")
+async def nc_semantic_search(query: str, ctx: Context) -> SemanticSearchResponse:
+    """Search across all indexed apps"""
+```
+
+**Advantages**:
+- Granular control - users explicitly consent to searching each app
+- Aligns with app-specific authorization model
+- Clear security boundary - can only search apps you can access
+
+**Disadvantages**:
+- **Brittle user experience**: If a user grants only `notes:read` but the tool requires all 5 scopes, the tool becomes invisible/unusable
+- **All-or-nothing enforcement**: Can't search notes alone - must grant all scopes or none
+- **Poor progressive consent**: User can't start with notes search and later add calendar
+- **Scope inflation**: Every new app adds another required scope
+- **Mismatched semantics**: User thinks "I want to search my notes" but must grant calendar, deck, files, contacts just to make the tool appear
+
+### Option 2: Single Generic Scope (Chosen)
+
+Introduce a new semantic search-specific scope:
+
+```python
+@mcp.tool()
+@require_scopes("semantic:read")
+async def nc_semantic_search(query: str, ctx: Context) -> SemanticSearchResponse:
+    """Search across all indexed apps"""
+```
+
+**Advantages**:
+- **Simple authorization**: One scope grants semantic search capability
+- **Progressive enablement**: User grants `semantic:read`, searches notes initially, then enables calendar indexing later
+- **Logical grouping**: Semantic search is a cross-app feature, deserving its own scope
+- **Future-proof**: New apps can be added to vector sync without changing OAuth scopes
+- **Matches user mental model**: "I want semantic search" → grant `semantic:read` (not "I want semantic search" → grant 5 unrelated app scopes)
+
+**Considerations**:
+- User could search apps they can't directly access via app-specific tools
+  - **Mitigation**: Dual-phase authorization (Phase 1: scope check passes with `semantic:read`, Phase 2: verify user can access each returned document via app-specific permissions)
+- Less granular than app-specific scopes
+  - **Counterpoint**: Semantic search is inherently cross-app - forcing per-app authorization defeats its purpose
+
+### Option 3: Hybrid Approach (Rejected)
+
+Support both: semantic search works with either `semantic:read` OR all app-specific scopes:
+
+```python
+@mcp.tool()
+@require_scopes("semantic:read", alternative_scopes=["notes:read", "calendar:read", ...])
+async def nc_semantic_search(query: str, ctx: Context) -> SemanticSearchResponse:
+    """Search across all indexed apps"""
+```
+
+**Rejected Because**:
+- Adds complexity to scope validation logic
+- Unclear to users which scopes they should grant
+- Alternative scopes still suffer from all-or-nothing problem
+- No significant benefit over Option 2 with dual-phase authorization
+
+## Decision
+
+We will introduce two new OAuth scopes specifically for semantic search operations:
+
+- **`semantic:read`**: Query vector database, perform semantic search, generate answers
+- **`semantic:write`**: Enable/disable background vector synchronization, manage indexing settings
+
+These scopes are **independent** of app-specific scopes (notes:read, calendar:read, etc.).
+
+### Tool Scope Assignments
+
+**Read Operations**:
+```python
+@mcp.tool()
+@require_scopes("semantic:read")
+async def nc_semantic_search(query: str, ctx: Context, limit: int = 10, score_threshold: float = 0.7) -> SemanticSearchResponse:
+    """Semantic search across all indexed Nextcloud apps"""
+
+@mcp.tool()
+@require_scopes("semantic:read")
+async def nc_semantic_search_answer(query: str, ctx: Context, limit: int = 5, max_answer_tokens: int = 500) -> SamplingSearchResponse:
+    """Semantic search with LLM-generated answer via MCP sampling"""
+
+@mcp.tool()
+@require_scopes("semantic:read")
+async def nc_get_vector_sync_status(ctx: Context) -> VectorSyncStatusResponse:
+    """Get current vector synchronization status (indexed count, pending count, status)"""
+```
+
+**Write Operations**:
+```python
+@mcp.tool()
+@require_scopes("semantic:write")
+async def nc_enable_vector_sync(ctx: Context) -> VectorSyncResponse:
+    """Enable background vector synchronization for this user"""
+
+@mcp.tool()
+@require_scopes("semantic:write")
+async def nc_disable_vector_sync(ctx: Context) -> VectorSyncResponse:
+    """Disable background vector synchronization"""
+```
+
+### Dual-Phase Authorization
+
+To ensure users can only access documents they have permission to view, semantic search implements **dual-phase authorization**:
+
+**Phase 1: Scope Check** (MCP Server)
+- User must have `semantic:read` scope to call semantic search tools
+- This grants permission to query the vector database
+
+**Phase 2: Document Verification** (Per-Result Filtering)
+- For each returned document, verify user has access via app-specific permissions
+- Uses `DocumentVerifier` interface per app:
+  - Notes: Call `/apps/notes/api/v1/notes/{id}` - if 404/403, exclude from results
+  - Calendar: Call `/remote.php/dav/calendars/username/calendar/event.ics` - if 404/403, exclude
+  - Deck: Call `/apps/deck/api/v1.0/boards/{board_id}/stacks/{stack_id}/cards/{card_id}` - if 404/403, exclude
+  - Files: Call `/remote.php/dav/files/username/path` with PROPFIND - if 404/403, exclude
+  - Contacts: Call `/remote.php/dav/addressbooks/username/addressbook/contact.vcf` - if 404/403, exclude
+
+This two-phase approach ensures:
+1. Semantic search is a **distinct capability** (like "global search") requiring explicit consent
+2. Results are **filtered** to only include documents the user can access
+3. No privilege escalation - users can't discover content they shouldn't see
+
+**Implementation**: See ADR-007 Phase 3 (Document Verification) and `DocumentVerifier` interface.
+
+### Scope Discovery
+
+The new scopes will be:
+- **Advertised** via PRM endpoint (`/.well-known/oauth-protected-resource/mcp`)
+- **Dynamically discovered** from `@require_scopes` decorators on semantic search tools
+- **Documented** in OAuth architecture (oauth-architecture.md)
+- **Included** in default client registration scopes
+
+## Consequences
+
+### Benefits
+
+**User Experience**:
+- Simple authorization: one scope for semantic search capability
+- Progressive enablement: grant `semantic:read`, enable indexing for apps later
+- Natural mental model: "semantic search" is a distinct feature deserving its own scope
+
+**Security**:
+- Dual-phase authorization prevents privilege escalation
+- Users explicitly consent to cross-app search capability
+- Per-document verification ensures users only see accessible content
+
+**Maintainability**:
+- Adding new apps to vector sync doesn't require OAuth scope changes
+- Clear separation between app access (notes:read) and search capability (semantic:read)
+- Logical grouping of related operations (search, sync status, enable/disable)
+
+**Future-Proof**:
+- Can add new document types without breaking existing OAuth flows
+- Supports future semantic features (recommendations, clustering) under same scope
+- Aligns with potential future Nextcloud semantic capabilities
+
+### Trade-offs
+
+**Less Granular Than App-Specific Scopes**:
+- User can't grant "semantic search notes only"
+- Semantic search is all-or-nothing across enabled apps
+- **Mitigation**: Dual-phase verification ensures users only see documents they can access
+
+**New Scope to Learn**:
+- Users must understand `semantic:read` is distinct from app scopes
+- MCP clients must present scope clearly during consent
+- **Mitigation**: Clear scope descriptions in OAuth consent UI and documentation
+
+**Backend Complexity**:
+- Requires dual-phase authorization implementation
+- DocumentVerifier interface needed for each app
+- **Benefit**: Enforces proper security regardless of scope model
+
+### Migration Impact
+
+**Breaking Change**: Existing deployments using notes-specific semantic search will break.
+
+**Before (OLD - Breaking)**:
+```python
+@mcp.tool()
+@require_scopes("notes:read")
+async def nc_notes_semantic_search(query: str, ctx: Context) -> SemanticSearchResponse:
+    """Semantic search notes"""
+```
+
+**After (NEW)**:
+```python
+@mcp.tool()
+@require_scopes("semantic:read")
+async def nc_semantic_search(query: str, ctx: Context) -> SemanticSearchResponse:
+    """Semantic search across all apps"""
+```
+
+**Migration Path**:
+1. Deploy server with new `semantic:read` scope
+2. Users re-authenticate, granting `semantic:read` scope
+3. Semantic search tools become visible/usable again
+4. **No data loss**: Vector database and indexed documents remain unchanged
+
+**Backward Compatibility**: None. This is an intentional breaking change to correct the scope model before broader adoption.
+
+## Alternatives Considered
+
+### Keep Notes-Specific Scopes
+
+**Approach**: Continue using `notes:read` for semantic search, even when searching other apps.
+
+**Rejected Because**:
+- Semantically incorrect - searching calendar events is not "reading notes"
+- Confuses users - why does searching calendar require notes:read?
+- Doesn't scale - what scope for multi-app search?
+
+### Create Per-App Semantic Scopes
+
+**Approach**: Introduce `notes:semantic`, `calendar:semantic`, `deck:semantic`, etc.
+
+**Rejected Because**:
+- Scope proliferation - doubles the number of scopes
+- Defeats purpose of unified vector search
+- Users would need to grant 5+ scopes for cross-app search
+- No clear benefit over dual-phase authorization with `semantic:read`
+
+### Require All App Scopes (Already Rejected in Option 1)
+
+**Approach**: Require `notes:read AND calendar:read AND deck:read AND files:read AND contacts:read`
+
+**Rejected Because**: Unusable UX (see Option 1 disadvantages above)
+
+## Related Decisions
+
+**ADR-007**: Background Vector Sync provides the indexing architecture that semantic scopes protect. The DocumentVerifier interface from ADR-007 Phase 3 implements dual-phase authorization.
+
+**ADR-008**: MCP Sampling for semantic search uses `semantic:read` to protect the sampling-enhanced search tool.
+
+**ADR-004**: Progressive Consent architecture supports users granting `semantic:read` initially, then enabling per-app indexing via `semantic:write` (enable_vector_sync with app selection).
+
+## Implementation Checklist
+
+- [ ] Create ADR-009 document (this file)
+- [ ] Update `oauth-architecture.md` to document `semantic:read` and `semantic:write` scopes ✅
+- [ ] Update `README.md` to show Semantic Search as separate tool category ✅
+- [ ] Update ADR-007 to reference `semantic:*` scopes instead of `sync:*` ✅
+- [ ] Update ADR-008 to use `semantic:read` instead of `notes:read` ✅
+- [ ] Implement DocumentVerifier interface for all apps (notes, calendar, deck, files, contacts)
+- [ ] Update semantic search tools to use `@require_scopes("semantic:read")`
+- [ ] Update vector sync tools to use `@require_scopes("semantic:write")`
+- [ ] Add dual-phase authorization to semantic search implementation
+- [ ] Test OAuth flow with `semantic:read` scope
+- [ ] Update scope discovery in PRM endpoint
+- [ ] Document migration path for existing deployments

docs/ADR-010-webhook-based-vector-sync.md

@@ -0,0 +1,661 @@
+# ADR-010: Webhook-Based Vector Database Synchronization
+
+**Status**: Proposed
+**Date**: 2025-01-10
+**Depends On**: ADR-007 (Background Vector Sync)
+
+## Context
+
+ADR-007 established a background synchronization architecture for maintaining the vector database using periodic polling. The scanner task runs on a configurable interval (default 3600 seconds / 1 hour) to detect changed documents across Nextcloud apps. While this polling approach is simple and reliable, it introduces significant latency between content changes and vector database updates.
+
+### Current Polling Architecture
+
+The existing scanner implementation in `nextcloud_mcp_server/vector/scanner.py` operates as follows:
+
+1. **Periodic Scanning**: The scanner task sleeps for `vector_sync_scan_interval` seconds between runs
+2. **Change Detection**: For each scan, it:
+   - Fetches all documents from Nextcloud (notes, calendar events, etc.)
+   - Queries Qdrant for the last indexed timestamp of each document
+   - Compares modification timestamps to detect changes
+   - Queues changed documents for processing
+3. **Document Processing**: Processor tasks pull from the queue, generate embeddings, and update Qdrant
+
+This architecture works but has fundamental limitations:
+
+**Latency**: With a 1-hour scan interval, content changes can take up to 1 hour to appear in semantic search results. For time-sensitive use cases (e.g., "What's on my calendar today?"), this delay is problematic.
+
+**API Load**: Every scan fetches *all* documents for *all* enabled users, regardless of whether anything changed. For large deployments with thousands of documents, this generates significant unnecessary API traffic to Nextcloud.
+
+**Resource Waste**: The scanner and processors consume compute resources even when no content has changed. During periods of low activity, the system performs wasteful polling.
+
+**Scalability**: As the number of users and documents grows, the time required to complete a full scan increases. Eventually, the scan duration may exceed the scan interval, causing scans to run continuously without idle periods.
+
+**Rate Limiting**: Fetching all documents for all users in rapid succession can trigger Nextcloud's rate limiting, especially on shared hosting environments with restrictive API quotas.
+
+These limitations are inherent to any polling-based architecture. Reducing the scan interval (e.g., to 5 minutes) reduces latency but exacerbates API load, resource waste, and rate limiting issues. The fundamental problem is that the system has no way to know *when* content changes occur—it must repeatedly check to find out.
+
+### Nextcloud Webhook Listeners
+
+Nextcloud provides a webhook_listeners app (bundled with Nextcloud 30+) that enables push-based change notifications. Instead of polling for changes, external services can register webhook endpoints and receive HTTP POST requests when specific events occur. Administrators register these webhooks using Nextcloud's OCS API or occ commands.
+
+The webhook_listeners app supports events for all Nextcloud apps relevant to this MCP server's vector database:
+
+**Files/Notes Events** (notes are stored as files):
+- `OCP\Files\Events\Node\NodeCreatedEvent`
+- `OCP\Files\Events\Node\NodeWrittenEvent`
+- `OCP\Files\Events\Node\BeforeNodeDeletedEvent` ⭐ **Use this for deletion (includes node.id)**
+- `OCP\Files\Events\Node\NodeDeletedEvent` (missing node.id - file already deleted)
+- `OCP\Files\Events\Node\NodeRenamedEvent`
+- `OCP\Files\Events\Node\NodeCopiedEvent`
+
+**Calendar Events**:
+- `OCP\Calendar\Events\CalendarObjectCreatedEvent`
+- `OCP\Calendar\Events\CalendarObjectUpdatedEvent`
+- `OCP\Calendar\Events\CalendarObjectDeletedEvent`
+- `OCP\Calendar\Events\CalendarObjectMovedEvent`
+
+**Tables Events**:
+- `OCA\Tables\Event\RowAddedEvent`
+- `OCA\Tables\Event\RowUpdatedEvent`
+- `OCA\Tables\Event\RowDeletedEvent`
+
+**Deck Events** (via file events since cards are stored as files in some configurations)
+
+Each webhook notification includes rich metadata:
+- User ID who triggered the event
+- Timestamp of the event
+- Document ID and metadata
+- Operation type (create, update, delete)
+- Path information (for files)
+
+Webhook notifications are dispatched via background jobs, with configurable delivery guarantees. Administrators can set up dedicated webhook worker processes to achieve near-real-time delivery (within seconds of the triggering event).
+
+### Why Not Replace Polling Entirely?
+
+While webhooks provide superior latency and efficiency, they cannot fully replace polling:
+
+**Missed Events**: If the MCP server is down when a webhook fires, the notification is lost. Nextcloud's background job system processes webhooks asynchronously, but does not queue failed deliveries indefinitely.
+
+**Administrator Setup**: Webhooks must be registered by Nextcloud administrators using the OCS API or occ commands. This is an optional optimization that administrators can enable when they want to reduce polling frequency.
+
+**Filter Configuration**: Webhook filters must be carefully configured to avoid notification floods. A poorly configured filter could send thousands of notifications for bulk operations (e.g., importing a calendar with hundreds of events).
+
+**Graceful Degradation**: In environments where webhooks are not configured, the system continues using polling without any degradation in functionality.
+
+**Deletion Detection**: Nextcloud's webhook system does not guarantee delivery of deletion events if the user's account is removed or the app is uninstalled. Periodic polling provides a safety mechanism to detect orphaned documents.
+
+A complementary architecture where webhooks supplement (but don't replace) polling provides low-latency updates when configured, with polling ensuring reliability.
+
+### Design Considerations
+
+**Push vs Pull Trade-offs**:
+Webhooks introduce new failure modes (network issues, endpoint unavailability, notification floods) that polling avoids. The webhook endpoint must handle failures gracefully without blocking semantic search functionality.
+
+**Webhook Endpoint Security**:
+The MCP server exposes an HTTP endpoint to receive webhooks. Authentication is optional—in production deployments, administrators can configure Nextcloud to send an `Authorization` header that the MCP server validates. For local development, authentication can be disabled for simplicity.
+
+**Idempotency**:
+The system may receive duplicate notifications (webhook + next scan) or out-of-order notifications (update fires before create completes). Document processing must be idempotent—processing the same document multiple times produces the same result.
+
+**Asynchronous Processing**:
+Nextcloud processes webhooks via background jobs, introducing delivery latency (typically seconds to minutes depending on background job configuration). This affects testing strategies—integration tests cannot rely on immediate webhook delivery.
+
+**Deployment Patterns**:
+The MCP server webhook endpoint is accessible at the same host/port as the MCP server itself. Administrators configure Nextcloud to POST to `https://<mcp-server-host>:<port>/webhooks/nextcloud` when registering webhook listeners.
+
+## Decision
+
+We will add a webhook endpoint to the MCP server that receives change notifications from Nextcloud and queues documents for vector database processing. This complements the existing polling architecture from ADR-007 without replacing it—webhooks provide low-latency updates when configured, while polling ensures reliability regardless of webhook availability.
+
+The architecture is intentionally simple: the webhook endpoint is just another producer of `DocumentTask` objects that feed into the existing processor queue. The scanner task, processor pool, and queue management remain unchanged from ADR-007.
+
+### Architecture Components
+
+**1. Webhook Endpoint**
+
+A new Starlette HTTP route will be added to receive webhook notifications from Nextcloud:
+
+```python
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+@app.route("/webhooks/nextcloud", methods=["POST"])
+async def handle_nextcloud_webhook(request: Request) -> JSONResponse:
+    """
+    Receive webhook notifications from Nextcloud.
+
+    Parses event payload, extracts document metadata, and queues
+    changed documents for processing using the same queue as the scanner.
+    """
+    # 1. Optional authentication validation
+    if settings.webhook_secret:
+        auth_header = request.headers.get("authorization", "")
+        if not auth_header.startswith("Bearer ") or \
+           auth_header[7:] != settings.webhook_secret:
+            logger.warning("Webhook authentication failed")
+            return JSONResponse(
+                {"status": "error", "message": "Unauthorized"},
+                status_code=401
+            )
+
+    # 2. Parse webhook payload
+    payload = await request.json()
+    event_class = payload["event"]["class"]
+    user_id = payload["user"]["uid"]
+
+    # 3. Extract document metadata from event
+    doc_task = extract_document_task(event_class, payload)
+    if not doc_task:
+        return JSONResponse({"status": "ignored", "reason": "unsupported event"})
+
+    # 4. Send to processor queue (same queue as scanner)
+    try:
+        await webhook_send_stream.send(doc_task)
+        logger.info(f"Queued document from webhook: {doc_task}")
+        return JSONResponse({"status": "queued"})
+    except Exception as e:
+        logger.error(f"Failed to queue webhook document: {e}")
+        return JSONResponse(
+            {"status": "error", "message": str(e)},
+            status_code=500
+        )
+```
+
+The endpoint:
+- Validates optional authentication via `Authorization: Bearer <secret>` header
+- Parses various event types (calendar, files, tables) into `DocumentTask` objects
+- Sends to the same processing queue that the scanner uses
+- Returns quickly (<50ms) to avoid blocking Nextcloud's webhook workers
+- Handles errors gracefully (invalid payload, queue full, etc.)
+
+**2. Webhook Registration Helper (Development Only)**
+
+For development and testing purposes, a helper method will be added to `NextcloudClient` for registering webhooks via the OCS API. This is NOT exposed as an MCP tool—administrators register webhooks manually using Nextcloud's admin interface or the OCS API directly.
+
+```python
+class NextcloudClient:
+    async def register_webhook(
+        self,
+        event_type: str,
+        uri: str,
+        http_method: str = "POST",
+        auth_method: str = "none",
+        headers: dict[str, str] | None = None,
+    ) -> dict:
+        """
+        Register a webhook with Nextcloud (requires admin credentials).
+
+        Used for development/testing. Production admins should register
+        webhooks using Nextcloud's admin UI or occ commands.
+        """
+        # Implementation uses OCS API: POST /ocs/v2.php/apps/webhook_listeners/api/v1/webhooks
+        ...
+```
+
+This keeps webhook registration out of the MCP tool surface while providing a convenient API for integration tests.
+
+**3. Event Parsing**
+
+A helper function extracts `DocumentTask` from various Nextcloud event types:
+
+```python
+def extract_document_task(event_class: str, payload: dict) -> DocumentTask | None:
+    """Extract DocumentTask from webhook event payload."""
+    user_id = payload["user"]["uid"]
+    event_data = payload["event"]
+
+    # File/Note events
+    if "NodeCreatedEvent" in event_class or "NodeWrittenEvent" in event_class:
+        # Only process markdown files (notes)
+        path = event_data["node"]["path"]
+        if not path.endswith(".md"):
+            return None
+        return DocumentTask(
+            user_id=user_id,
+            doc_id=event_data["node"]["id"],
+            doc_type="note",
+            operation="index",
+            modified_at=payload["time"],
+        )
+
+    # Calendar events
+    elif "CalendarObjectCreatedEvent" in event_class or \
+         "CalendarObjectUpdatedEvent" in event_class:
+        return DocumentTask(
+            user_id=user_id,
+            doc_id=str(event_data["objectData"]["id"]),
+            doc_type="calendar_event",
+            operation="index",
+            modified_at=event_data["objectData"]["lastmodified"],
+        )
+
+    # Deletion events (use BeforeNodeDeletedEvent for files to get node.id)
+    elif "BeforeNodeDeletedEvent" in event_class or \
+         "NodeDeletedEvent" in event_class or \
+         "CalendarObjectDeletedEvent" in event_class:
+        # Similar logic for delete operations
+        ...
+
+    return None  # Unsupported event type
+```
+
+**4. No Changes to Scanner or Processors**
+
+The existing scanner task from ADR-007 continues operating unchanged. It polls Nextcloud on its configured interval (`VECTOR_SYNC_SCAN_INTERVAL`), discovers changed documents, and queues them for processing. The scanner is unaware of webhooks—it simply adds `DocumentTask` objects to the queue.
+
+Similarly, the processor pool continues pulling `DocumentTask` objects from the queue, generating embeddings, and updating Qdrant. Processors don't know or care whether a task came from the scanner or a webhook.
+
+This design keeps concerns separated: webhooks and scanner are independent producers, processors are independent consumers, and the queue mediates between them.
+
+### Configuration
+
+A new optional environment variable controls webhook authentication:
+
+```bash
+# Optional: Shared secret for webhook authentication
+# If set, webhooks must include "Authorization: Bearer <secret>" header
+# If unset, no authentication is required (useful for local development)
+WEBHOOK_SECRET=<generate-random-secret>
+```
+
+The webhook endpoint is automatically available at `/webhooks/nextcloud` when the MCP server starts. No feature flags or additional configuration needed—if Nextcloud sends webhooks to this endpoint, they will be processed.
+
+**Reducing Polling Frequency**: Administrators who configure webhooks may want to reduce polling frequency to minimize API load while maintaining safety reconciliation scans:
+
+```bash
+# Increase scan interval from 1 hour (default) to 24 hours
+VECTOR_SYNC_SCAN_INTERVAL=86400
+```
+
+This is a manual configuration decision, not automatic—the scanner doesn't adapt based on webhook availability.
+
+### Webhook Event Mapping
+
+The webhook handler maps Nextcloud events to document types:
+
+| Nextcloud Event | Document Type | Operation |
+|----------------|---------------|-----------|
+| `NodeCreatedEvent` (path: `*/files/*.md`) | `note` | `index` |
+| `NodeWrittenEvent` (path: `*/files/*.md`) | `note` | `index` |
+| `NodeDeletedEvent` (path: `*/files/*.md`) | `note` | `delete` |
+| `CalendarObjectCreatedEvent` | `calendar_event` | `index` |
+| `CalendarObjectUpdatedEvent` | `calendar_event` | `index` |
+| `CalendarObjectDeletedEvent` | `calendar_event` | `delete` |
+| `RowAddedEvent` | `table_row` | `index` |
+| `RowUpdatedEvent` | `table_row` | `index` |
+| `RowDeletedEvent` | `table_row` | `delete` |
+
+Path filters in webhook registration ensure only relevant files trigger notifications (e.g., exclude `.jpg`, `.mp4` for file events).
+
+### Administrator Setup
+
+Administrators who want to enable webhooks:
+
+1. **Enable webhook_listeners app** in Nextcloud: `occ app:enable webhook_listeners`
+2. **Register webhook endpoints** using Nextcloud's OCS API or admin UI:
+   - Endpoint: `https://<mcp-server-host>:<port>/webhooks/nextcloud`
+   - Events: File created/updated/deleted, Calendar object events, Table row events
+   - Filters: Exclude non-content files (images, videos), system directories
+   - Optional: Configure `Authorization: Bearer <WEBHOOK_SECRET>` header
+3. **Optionally reduce scanner frequency**: Set `VECTOR_SYNC_SCAN_INTERVAL=86400` (24 hours)
+4. **Set up webhook workers** (optional): Configure dedicated background job workers for low-latency delivery
+
+Existing deployments continue using polling without any changes. Webhooks are purely additive.
+
+## Consequences
+
+### Benefits
+
+**Reduced Latency**: With webhooks configured, content changes appear in semantic search within seconds to minutes (depending on Nextcloud background job configuration) instead of up to 1 hour. Queries like "What meetings do I have today?" reflect recent calendar updates.
+
+**Lower API Load**: Administrators who configure webhooks can reduce scanner frequency (e.g., 24-hour intervals), eliminating most polling API calls while maintaining safety reconciliation scans. This significantly reduces load on Nextcloud servers.
+
+**Better Scalability**: Webhooks scale better than polling as content volume grows. The system only processes changed documents instead of checking all documents every hour.
+
+**Simple Architecture**: The webhook endpoint is just another producer feeding the existing processor queue. No changes to scanner, processors, or queue management—webhooks integrate cleanly into the existing architecture.
+
+**Improved User Experience**: Lower-latency semantic search feels more responsive and accurate, especially for time-sensitive queries about recent changes.
+
+### Drawbacks
+
+**Manual Configuration**: Administrators must configure webhooks outside the MCP server using Nextcloud's admin tools. This adds setup complexity compared to the zero-configuration polling approach.
+
+**Deployment Requirements**: Webhooks require the MCP server to be reachable from Nextcloud via HTTP(S). Deployments behind NAT or with restrictive firewalls may not support webhooks without additional networking configuration.
+
+**Asynchronous Delivery**: Nextcloud processes webhooks via background jobs, introducing delivery latency (typically seconds to minutes). The exact latency depends on background job worker configuration and system load.
+
+**Testing Complexity**: Integration tests cannot rely on immediate webhook delivery due to asynchronous background job processing. Tests must either poll for results or mock webhook delivery directly.
+
+**New Failure Modes**: Webhook endpoint downtime, network issues between Nextcloud and MCP server, webhook notification floods from bulk operations. The system must handle these gracefully.
+
+**Version Dependencies**: The webhook_listeners app requires Nextcloud 30+. Older versions continue using polling exclusively.
+
+### Monitoring and Observability
+
+New metrics track webhook performance:
+
+- `webhook_notifications_received_total{event_type}`: Count of webhook notifications by event type
+- `webhook_processing_duration_seconds{event_type}`: Webhook handler latency
+- `webhook_errors_total{error_type}`: Failed webhook processing by error type (auth failure, parse error, queue full)
+
+Logs include:
+- Successful webhook processing: `Queued document from webhook: DocumentTask(...)`
+- Webhook authentication failures: `Webhook authentication failed`
+- Parse errors: `Failed to parse webhook payload: ...`
+- Unsupported events: `Ignoring webhook for unsupported event: ...`
+
+### Security Considerations
+
+**Optional Authentication**: When `WEBHOOK_SECRET` is configured, webhook requests must include `Authorization: Bearer <WEBHOOK_SECRET>` header. The server validates this before processing to prevent unauthorized document queueing. For local development, authentication can be disabled by leaving `WEBHOOK_SECRET` unset.
+
+**Payload Validation**: Webhook payloads are parsed and validated against expected schemas. Malformed payloads are rejected with 400 Bad Request responses.
+
+**No Scope Enforcement**: Unlike MCP tools, webhooks do not enforce progressive consent or check if users have enabled semantic search. Webhooks queue all document changes—administrators control which events trigger webhooks via Nextcloud filters. This keeps the webhook endpoint simple and stateless.
+
+### Testing Strategy
+
+**Unit Tests**: Test webhook handler logic, event parsing, and authentication validation using mocked payloads:
+
+```python
+async def test_webhook_endpoint_parses_note_created_event():
+    """Unit test: webhook endpoint extracts DocumentTask from note created event."""
+    payload = {
+        "user": {"uid": "alice"},
+        "time": 1704067200,
+        "event": {
+            "class": "OCP\\Files\\Events\\Node\\NodeCreatedEvent",
+            "node": {"id": "123", "path": "/alice/files/test.md"}
+        }
+    }
+    # Mock send_stream and verify DocumentTask is queued
+    ...
+```
+
+**Integration Tests (Without Real Webhooks)**: Since Nextcloud processes webhooks asynchronously via background jobs, integration tests should NOT rely on triggering real Nextcloud events and waiting for webhook delivery. Instead, tests should:
+
+1. **Mock webhook delivery**: POST webhook payloads directly to the `/webhooks/nextcloud` endpoint
+2. **Verify processing**: Check that documents are queued and eventually appear in Qdrant
+3. **Test authentication**: Verify requests without valid auth header are rejected (when `WEBHOOK_SECRET` is set)
+
+```python
+async def test_webhook_integration_mocked_delivery():
+    """Integration test: webhook handler queues document for processing."""
+    # POST webhook payload directly to endpoint (bypass Nextcloud)
+    response = await client.post("/webhooks/nextcloud", json=note_created_payload)
+    assert response.status_code == 200
+
+    # Wait for processor to handle document
+    await asyncio.sleep(2)
+
+    # Verify document appears in Qdrant
+    results = await qdrant_client.scroll(...)
+    assert len(results[0]) > 0
+```
+
+**Manual Testing (Real Webhooks)**: For end-to-end validation with real Nextcloud webhook delivery:
+
+1. Register webhook via OCS API or `NextcloudClient.register_webhook()` helper
+2. Configure webhook background job workers for low-latency delivery
+3. Trigger Nextcloud events (create note, add calendar event)
+4. Monitor MCP server logs for webhook delivery
+5. Verify documents appear in Qdrant after background job processing
+
+**Failure Mode Tests**:
+- Invalid authentication: Verify 401 response when auth header is missing/incorrect
+- Malformed payload: Verify 400 response for invalid JSON or missing required fields
+- Unsupported event types: Verify graceful handling (ignored, not error)
+- Queue full: Verify 500 response with appropriate error message
+
+### Future Enhancements
+
+**Batch Processing**: Group multiple webhook notifications within a short time window (e.g., 5 seconds) into a single batch before queueing. This reduces processor overhead during bulk operations like importing calendars.
+
+**Webhook Payload Optimization**: For large documents, Nextcloud could be configured to send minimal metadata in webhooks (just user_id, doc_id, doc_type), with processors fetching full content lazily. This reduces webhook payload size and network bandwidth.
+
+**Deduplication Window**: Track recently processed documents (last 5 minutes) to avoid redundant work when webhooks and scanner both detect the same change. The processor can check a simple in-memory cache before fetching document content.
+
+## Appendix A: Manual Webhook Testing Results (2025-01-11)
+
+### Testing Summary
+
+Manual validation of Nextcloud webhook schemas and behavior confirmed that webhooks work as documented with several important findings for implementation. **5 out of 6** webhook types were successfully captured and validated.
+
+**Test Environment:**
+- Nextcloud 30+ (Docker compose)
+- webhook_listeners app enabled
+- Test endpoint: `http://mcp:8000/webhooks/nextcloud`
+- Background webhook worker running (60s timeout)
+
+**Results:**
+- ✅ NodeCreatedEvent (file creation)
+- ✅ NodeWrittenEvent (file update)
+- ✅ NodeDeletedEvent (file deletion)
+- ✅ CalendarObjectCreatedEvent
+- ✅ CalendarObjectUpdatedEvent
+- ❌ CalendarObjectDeletedEvent (webhook did not fire - potential Nextcloud bug)
+
+### Critical Implementation Findings
+
+#### 1. Deletion Events Lack `node.id` Field
+
+**Finding:** `NodeDeletedEvent` payloads do NOT include `event.node.id`, only `event.node.path`.
+
+**Example:**
+```json
+{
+  "user": {"uid": "admin", "displayName": "admin"},
+  "time": 1762851093,
+  "event": {
+    "class": "OCP\\Files\\Events\\Node\\NodeDeletedEvent",
+    "node": {
+      "path": "/admin/files/Notes/Webhooks/Webhook Test Note.md"
+      // NOTE: No "id" field present
+    }
+  }
+}
+```
+
+**Impact:** The event parser in this ADR's example code assumes `event_data["node"]["id"]` exists for all file events. This will fail for deletions.
+
+**Update (2025-11-11):** Nextcloud maintainer clarified that `BeforeNodeDeletedEvent` should be used instead of `NodeDeletedEvent` to access `node.id` before the file is deleted. See [issue #56371](https://github.com/nextcloud/server/issues/56371#issuecomment-2470896634).
+
+> "Try using the `BeforeNodeDeletedEvent`. The `id` should still be available at that time. The reason `id` is not in `NodeDeletedEvent` is because the file is effectively guaranteed to be gone and, in turn, so is the FileInfo."
+> — Josh Richards, Nextcloud maintainer
+
+**Recommended Solution:** Use `OCP\Files\Events\Node\BeforeNodeDeletedEvent` for file deletion webhooks instead of `NodeDeletedEvent`.
+
+**Alternative Fix (if using NodeDeletedEvent):** Check for `id` existence and fall back to path-based identification:
+
+```python
+def extract_document_task(event_class: str, payload: dict) -> DocumentTask | None:
+    user_id = payload["user"]["uid"]
+    event_data = payload["event"]
+
+    # File deletion events - NO node.id field
+    if "NodeDeletedEvent" in event_class:
+        path = event_data["node"]["path"]
+        if not path.endswith(".md"):
+            return None
+        # Use path-based ID since node.id is unavailable
+        return DocumentTask(
+            user_id=user_id,
+            doc_id=f"path:{path}",  # Prefix to distinguish from numeric IDs
+            doc_type="note",
+            operation="delete",
+            modified_at=payload["time"],
+        )
+
+    # File creation/update events - node.id exists
+    elif "NodeCreatedEvent" in event_class or "NodeWrittenEvent" in event_class:
+        path = event_data["node"]["path"]
+        if not path.endswith(".md"):
+            return None
+
+        # Check if 'id' exists (should, but be defensive)
+        node_id = event_data["node"].get("id")
+        if not node_id:
+            # Fallback for missing ID
+            node_id = f"path:{path}"
+
+        return DocumentTask(
+            user_id=user_id,
+            doc_id=str(node_id),
+            doc_type="note",
+            operation="index",
+            modified_at=payload["time"],
+        )
+```
+
+**Qdrant Deletion Strategy:** When deleting by path-based ID, search Qdrant for documents with matching path metadata:
+
+```python
+async def delete_document_by_path(user_id: str, path: str):
+    """Delete document from Qdrant using path (when ID unavailable)."""
+    points = await qdrant.scroll(
+        collection_name=collection,
+        scroll_filter=Filter(must=[
+            FieldCondition(key="user_id", match=MatchValue(value=user_id)),
+            FieldCondition(key="metadata.path", match=MatchValue(value=path)),
+        ]),
+    )
+    # Delete found points...
+```
+
+#### 2. Multiple Webhooks Per Operation
+
+**Finding:** Creating a single note triggers 3-5 separate webhook events in rapid succession:
+
+1. `NodeCreatedEvent` for parent folder (if new)
+2. `NodeWrittenEvent` for parent folder
+3. `NodeCreatedEvent` for the note file
+4. `NodeWrittenEvent` for the note file (sometimes fires twice)
+
+**Impact:** Without deduplication, the processor will fetch and index the same note multiple times within seconds, wasting compute and API quota.
+
+**Solution:** The processor queue should be idempotent. If the same document is queued multiple times, only the latest version needs processing. Implementation options:
+
+1. **Queue-level deduplication:** Before adding to queue, check if a task for the same `(user_id, doc_id)` is already pending. Replace the existing task instead of adding duplicate.
+
+2. **Processor-level deduplication:** Track recently processed documents in a short-lived cache (5 minutes). If a document was just processed, skip redundant fetch unless the `modified_at` timestamp is newer.
+
+3. **Accept duplicates:** Let the processor handle duplicates naturally. Qdrant upserts are idempotent—reindexing with identical content is harmless but wasteful.
+
+**Recommendation:** Implement queue-level deduplication by maintaining a map of pending tasks and replacing duplicates with newer timestamps.
+
+#### 3. Type Discrepancy in `node.id`
+
+**Finding:** Nextcloud documentation specifies `node.id` as type `string`, but actual payloads return `int`:
+
+```json
+"node": {
+  "id": 437,  // integer, not "437"
+  "path": "/admin/files/Notes/Webhooks/Webhook Test Note.md"
+}
+```
+
+**Impact:** Code that assumes `node.id` is always a string will work but may cause type confusion in strongly-typed languages.
+
+**Solution:** Explicitly convert to string when extracting: `doc_id=str(event_data["node"]["id"])`
+
+#### 4. Calendar Events Have Different ID Field Path
+
+**Finding:** Calendar events store the document ID in a different location than file events:
+
+- **File events:** `event.node.id`
+- **Calendar events:** `event.objectData.id`
+
+**Impact:** Event parser must handle different field paths for different event types. The example code in this ADR correctly shows this difference.
+
+**Calendar Event Deletion:** Calendar deletion webhooks did NOT fire during testing. This may be a Nextcloud bug or require specific configuration (e.g., trash bin enabled). Until resolved, calendar deletions will only be detected via periodic scanner runs.
+
+#### 5. Rich Metadata in Calendar Webhooks
+
+**Finding:** Calendar webhook payloads include extensive metadata not present in file webhooks:
+
+```json
+{
+  "event": {
+    "calendarId": 1,
+    "calendarData": {
+      "id": 1,
+      "uri": "personal",
+      "{http://calendarserver.org/ns/}getctag": "...",
+      "{http://sabredav.org/ns}sync-token": 21,
+      // ... many calendar-level properties
+    },
+    "objectData": {
+      "id": 3,
+      "uri": "webhook-test-event-001.ics",
+      "lastmodified": 1762851169,
+      "etag": "\"2b937b7d77dc83c77329dfdb210ba9d0\"",
+      "calendarid": 1,
+      "size": 297,
+      "component": "vevent",
+      "classification": 0,
+      "uid": "webhook-test-event-001@nextcloud",
+      "calendardata": "BEGIN:VCALENDAR\r\nVERSION:2.0\r\n...",  // Full iCal
+      "{http://nextcloud.com/ns}deleted-at": null
+    },
+    "shares": []  // Array of sharing info
+  }
+}
+```
+
+**Opportunity:** The full iCal content is available in `objectData.calendardata`. The processor could extract metadata directly from the webhook payload instead of making an additional CalDAV request, reducing API load.
+
+### Updated Event Mapping
+
+Based on testing, the actual webhook behavior:
+
+| Nextcloud Event | Fires? | `node.id`/`objectData.id` Present? | Notes |
+|----------------|--------|-------------------------------------|-------|
+| `NodeCreatedEvent` | ✅ Yes | ✅ Yes (`int`) | Fires for folders too |
+| `NodeWrittenEvent` | ✅ Yes | ✅ Yes (`int`) | Fires 1-2x per operation |
+| `NodeDeletedEvent` | ✅ Yes | ❌ **NO** (only `path`) | Critical difference |
+| `CalendarObjectCreatedEvent` | ✅ Yes | ✅ Yes (`objectData.id`) | Full iCal included |
+| `CalendarObjectUpdatedEvent` | ✅ Yes | ✅ Yes (`objectData.id`) | Full iCal included |
+| `CalendarObjectDeletedEvent` | ❌ **DID NOT FIRE** | ❓ Unknown | Possible Nextcloud bug |
+
+### Recommended Implementation Changes
+
+The webhook handler code in this ADR requires these modifications:
+
+1. **Handle missing `node.id` in deletions** (see code example in Finding #1)
+2. **Add deduplication logic** to prevent redundant processing from multiple webhooks per operation
+3. **Validate field existence** before accessing nested properties (`get()` with defaults)
+4. **Log unsupported events** at DEBUG level (not WARNING) to avoid log noise
+5. **Add calendar deletion fallback:** Since webhook unreliable, calendar deletions rely on scanner reconciliation
+6. **Consider payload optimization:** Extract calendar metadata from webhook payload to reduce CalDAV API calls
+
+### Testing Implications
+
+**Integration Test Strategy:**
+
+The asynchronous nature of Nextcloud webhooks makes real webhook delivery unreliable for automated tests:
+
+- ✅ **DO:** POST webhook payloads directly to `/webhooks/nextcloud` endpoint in tests
+- ❌ **DON'T:** Trigger Nextcloud events and wait for webhook delivery
+- ✅ **DO:** Test authentication, payload parsing, and queue integration with mocked payloads
+- ❌ **DON'T:** Assume webhooks fire immediately or reliably
+
+**Manual Testing Required:**
+- Real webhook delivery latency (depends on background job workers)
+- Calendar deletion webhook behavior (confirm bug or configuration issue)
+- Behavior under high-frequency updates (bulk operations)
+- Network failure handling (Nextcloud can't reach MCP server)
+
+### Complete Tested Payload Examples
+
+See `webhook-testing-findings.md` in the repository root for:
+- Complete JSON payloads for all tested events
+- Detailed schema validation results
+- Additional edge cases and observations
+- Screenshots of webhook logs
+
+## References
+
+- ADR-007: Background Vector Database Synchronization (polling architecture)
+- Nextcloud Documentation: `~/Software/documentation/admin_manual/webhook_listeners/index.rst`
+- Nextcloud OCS API: Webhook registration endpoint
+- Current scanner implementation: `nextcloud_mcp_server/vector/scanner.py:37`
+- Webhook Testing Report: `webhook-testing-findings.md` (2025-01-11)

docs/ADR-011-improving-semantic-search-quality.md

@@ -0,0 +1,943 @@
+# ADR-011: Improving Semantic Search Quality Through Better Chunking and Embeddings
+
+**Status**: Partially Implemented (Chunking Complete, Embeddings Pending)
+**Date**: 2025-11-12
+**Implementation Date**: 2025-11-18 (Chunking)
+**Authors**: Development Team
+**Related**: ADR-003 (Vector Database Architecture), ADR-008 (MCP Sampling for RAG)
+
+## Context
+
+The semantic search implementation provides document retrieval across Nextcloud apps using vector embeddings. Production usage has revealed that **the system frequently misses relevant documents** (recall problem).
+
+Root cause analysis identifies two fundamental issues:
+
+### 1. Poor Chunking Strategy
+
+**Current Implementation** (`nextcloud_mcp_server/vector/document_chunker.py:36`):
+```python
+words = content.split()  # Naive whitespace splitting
+chunk_size = 512  # words
+overlap = 50  # words
+chunks = [words[i:i+chunk_size] for i in range(0, len(words), chunk_size-overlap)]
+```
+
+**Problems**:
+- **Breaks semantic boundaries**: Splits mid-sentence, mid-paragraph, mid-thought
+- **Loses context**: "The meeting discussed budget. We decided to..." becomes two disconnected chunks
+- **Poor retrieval**: Relevant content split across chunks with low individual relevance scores
+- **No structure awareness**: Ignores markdown headers, lists, code blocks
+
+**Evidence**:
+- Documents with relevant content in middle sections score poorly (content split across 3+ chunks)
+- Multi-sentence concepts (spanning 60-100 words) are fragmented
+- Search for "budget planning process" misses documents where these words appear in adjacent sentences but different chunks
+
+### 2. Suboptimal Embedding Model
+
+**Current Implementation** (`nextcloud_mcp_server/embedding/ollama_provider.py:33`):
+```python
+_model = "nomic-embed-text"  # 768 dimensions
+_dimension = 768  # Hardcoded
+```
+
+**Problems**:
+- **Model selection**: `nomic-embed-text` is general-purpose, not optimized for our use case
+- **No benchmarking**: Selected without comparative evaluation
+- **Dimensionality**: 768-dim may be insufficient for nuanced semantic distinctions
+- **No domain adaptation**: Model not tuned for Nextcloud content (notes, calendar, deck cards)
+
+**Evidence**:
+- Synonymous queries return different results ("meeting notes" vs. "discussion summary")
+- Domain-specific terms poorly represented ("standup", "retrospective", "OKRs")
+- Cross-lingual content (if present) not well supported
+
+### Current Performance
+
+**Baseline Metrics** (100-document test corpus, 50 queries):
+- **Recall@10**: ~52% (misses 48% of relevant documents)
+- **Precision@10**: ~78% (acceptable but room for improvement)
+- **MRR**: 0.58 (relevant docs often not in top positions)
+- **Zero-result queries**: 18% (completely missing relevant content)
+
+## Decision Drivers
+
+1. **Address Root Causes**: Fix fundamental issues (chunking, embeddings) before adding complexity (reranking, hybrid search)
+2. **Measurable Impact**: Target 40-60% improvement in recall through chunking/embedding alone
+3. **Independence**: Improvements should be orthogonal to future enhancements (reranking, GraphRAG)
+4. **Cost Efficiency**: Minimize infrastructure and API costs
+5. **Reindexing Acceptable**: One-time reindex cost justified by long-term quality improvement
+
+## Options Considered
+
+### Chunking Strategies
+
+#### Option C1: Semantic Sentence-Aware Chunking (RECOMMENDED)
+
+**Description**: Respect sentence boundaries while maintaining target chunk size
+
+**Implementation**:
+```python
+from langchain.text_splitter import RecursiveCharacterTextSplitter
+
+splitter = RecursiveCharacterTextSplitter(
+    chunk_size=2048,  # ~512 words in characters
+    chunk_overlap=200,  # ~50 words in characters
+    separators=["\n\n", "\n", ". ", "! ", "? ", "; ", ": ", ", ", " "],
+    length_function=len,
+)
+```
+
+**How it works**:
+1. Try splitting by paragraphs (`\n\n`)
+2. If chunks too large, split by sentences (`. `, `! `, `? `)
+3. If still too large, split by clauses (`;`, `:`)
+4. Last resort: split by words
+
+**Pros**:
+- ✅ Preserves semantic boundaries (never breaks mid-sentence)
+- ✅ Maintains context coherence within chunks
+- ✅ Simple implementation (langchain library)
+- ✅ Configurable separators for different content types
+- ✅ Proven approach (used by major RAG systems)
+
+**Cons**:
+- ❌ Variable chunk sizes (not exactly 512 words, but close)
+- ❌ Adds dependency (langchain)
+- ❌ Slightly slower than naive splitting (~10-20ms per document)
+
+**Expected Impact**: 20-30% recall improvement
+
+#### Option C2: Hierarchical Context-Preserving Chunks
+
+**Description**: Create overlapping parent/child chunks
+
+**Structure**:
+```
+Document → Large parent chunks (1024 words) → Small child chunks (256 words)
+          ↓                                    ↓
+   Stored in Qdrant                       Searched first
+                                          Return parent context
+```
+
+**Implementation**:
+```python
+# Generate child chunks (searched)
+child_chunks = splitter.split_text(content, chunk_size=1024)
+
+# Generate parent chunks (context)
+parent_chunks = splitter.split_text(content, chunk_size=4096)
+
+# Store both with parent-child relationships
+for child_idx, child in enumerate(child_chunks):
+    parent_idx = find_parent(child_idx)
+    store_vector(
+        vector=embed(child),
+        payload={
+            "chunk": child,
+            "parent_chunk": parent_chunks[parent_idx],
+            "chunk_type": "child"
+        }
+    )
+```
+
+**Pros**:
+- ✅ Best of both worlds: precise matching + full context
+- ✅ Handles multi-hop information needs
+- ✅ Better for long documents (> 1000 words)
+
+**Cons**:
+- ❌ 2x storage (parent + child chunks)
+- ❌ More complex implementation
+- ❌ Higher indexing time (embed twice)
+- ❌ Query complexity (retrieve child, return parent)
+
+**Expected Impact**: 35-45% recall improvement (diminishing returns vs. complexity)
+
+**Verdict**: ⚠️ Consider only if Option C1 insufficient
+
+#### Option C3: Document Structure-Aware Chunking
+
+**Description**: Parse markdown/document structure before chunking
+
+**Implementation**:
+```python
+import mistune  # Markdown parser
+
+def structure_aware_chunk(markdown_content: str) -> list[str]:
+    ast = mistune.create_markdown(renderer='ast')(markdown_content)
+
+    chunks = []
+    for node in ast:
+        if node['type'] == 'heading':
+            # Start new chunk at each header
+            current_chunk = node['children'][0]['raw']
+        elif node['type'] == 'paragraph':
+            current_chunk += "\n" + node['children'][0]['raw']
+            if len(current_chunk) > 2048:
+                chunks.append(current_chunk)
+                current_chunk = ""
+
+    return chunks
+```
+
+**Pros**:
+- ✅ Respects document logical structure
+- ✅ Headers provide context for chunks
+- ✅ Works well for structured notes (documentation, meeting notes with sections)
+
+**Cons**:
+- ❌ Complex implementation (parser, AST traversal)
+- ❌ Markdown-specific (doesn't help calendar events, deck cards)
+- ❌ Variable chunk sizes (some sections very short/long)
+- ❌ Breaks for unstructured content
+
+**Expected Impact**: 15-25% improvement for structured content only
+
+**Verdict**: ⚠️ Future enhancement after Option C1
+
+#### Option C4: Fixed Sliding Window (Current Baseline)
+
+**Description**: Current naive word-based splitting
+
+**Verdict**: ❌ Superseded by Option C1
+
+### Embedding Model Strategies
+
+#### Option E1: Upgrade to Better General-Purpose Model (RECOMMENDED)
+
+**Description**: Switch to state-of-the-art embedding model
+
+**Candidates**:
+
+| Model | Dimensions | MTEB Score | Pros | Cons |
+|-------|-----------|------------|------|------|
+| **mxbai-embed-large** | 1024 | 64.68 | Best performance, good balance | Larger (slower) |
+| **nomic-embed-text-v1.5** | 768 | 62.39 | Upgraded version of current | Incremental improvement |
+| **bge-large-en-v1.5** | 1024 | 64.23 | Excellent for English | Not multilingual |
+| **nomic-embed-text** (current) | 768 | 60.10 | Baseline | Lower performance |
+
+**MTEB**: Massive Text Embedding Benchmark (higher = better semantic understanding)
+
+**Recommendation**: **mxbai-embed-large-v1**
+- Best MTEB score (64.68)
+- 1024 dimensions (richer semantic space)
+- Works well via Ollama
+- ~15-20% better retrieval quality in benchmarks
+
+**Implementation**:
+```python
+# config.py
+OLLAMA_EMBEDDING_MODEL = "mxbai-embed-large-v1"  # Changed from nomic-embed-text
+
+# ollama_provider.py
+async def get_dimension(self) -> int:
+    # Query Ollama for actual dimension instead of hardcoding
+    response = await self.client.post("/api/show", json={"name": self.model})
+    return response.json()["details"]["embedding_length"]
+```
+
+**Migration**:
+1. Deploy new model to Ollama
+2. Create new Qdrant collection (different dimension)
+3. Reindex all documents with new embeddings
+4. Swap collections atomically
+5. Delete old collection
+
+**Pros**:
+- ✅ Immediate quality improvement (15-20%)
+- ✅ Simple change (config + reindex)
+- ✅ No code complexity
+- ✅ Future-proof (state-of-the-art model)
+
+**Cons**:
+- ❌ Requires full reindex (2-4 hours for 1000 documents)
+- ❌ Larger model = slower embedding (~50ms vs. 30ms per chunk)
+- ❌ Higher dimensionality = more storage (~30% increase)
+
+**Expected Impact**: 15-25% recall improvement
+
+#### Option E2: Multi-Vector Embeddings (ColBERT-style)
+
+**Description**: Generate multiple embeddings per chunk (token-level)
+
+**Architecture**:
+```
+Chunk → Transformer → Token embeddings (e.g., 50 tokens × 128 dim) → Store all
+Query → Transformer → Token embeddings → MaxSim(query_tokens, doc_tokens)
+```
+
+**MaxSim scoring**:
+```python
+def maxsim_score(query_embeddings, doc_embeddings):
+    # For each query token, find max similarity with any doc token
+    scores = []
+    for q_emb in query_embeddings:
+        max_sim = max(cosine_similarity(q_emb, d_emb) for d_emb in doc_embeddings)
+        scores.append(max_sim)
+    return sum(scores)
+```
+
+**Pros**:
+- ✅ Best retrieval quality (state-of-the-art results)
+- ✅ Fine-grained matching (token-level)
+- ✅ Handles partial matches better
+
+**Cons**:
+- ❌ **50-100x storage increase** (50 vectors per chunk vs. 1)
+- ❌ **Slower search** (compute MaxSim for each candidate)
+- ❌ **Complex implementation** (custom scoring, storage schema)
+- ❌ **Requires specialized model** (ColBERTv2, not available in Ollama)
+
+**Expected Impact**: 40-50% improvement, but at very high cost
+
+**Verdict**: ❌ Too complex, too expensive for marginal gain over E1+C1
+
+#### Option E3: Fine-Tuned Domain-Specific Model
+
+**Description**: Fine-tune embedding model on Nextcloud corpus
+
+**Process**:
+1. Collect training data (query-document pairs)
+2. Fine-tune base model (e.g., `nomic-embed-text`) on domain data
+3. Deploy fine-tuned model via Ollama
+4. Reindex with fine-tuned embeddings
+
+**Training data needed**:
+- 1,000+ query-document pairs
+- Labeled relevance (positive/negative examples)
+- Representative of real usage
+
+**Pros**:
+- ✅ Optimized for specific content (notes, calendar, deck)
+- ✅ Better handling of domain terminology
+- ✅ Highest potential quality improvement (30-40%)
+
+**Cons**:
+- ❌ **Requires training data** (expensive to collect)
+- ❌ **GPU infrastructure** needed for fine-tuning
+- ❌ **Expertise required** (ML/NLP knowledge)
+- ❌ **Maintenance burden** (retrain as corpus evolves)
+- ❌ **Time investment**: 2-4 weeks initial setup
+
+**Expected Impact**: 30-40% improvement, but high cost
+
+**Verdict**: ⚠️ Consider only if E1+C1 insufficient AND have training data
+
+#### Option E4: Ensemble Embeddings
+
+**Description**: Generate embeddings with multiple models, combine scores
+
+**Implementation**:
+```python
+models = ["mxbai-embed-large-v1", "bge-large-en-v1.5"]
+
+# Index
+embeddings = [await embed(chunk, model) for model in models]
+store_multi_vector(embeddings)
+
+# Search
+query_embeddings = [await embed(query, model) for model in models]
+scores = [search(q_emb, model) for q_emb, model in zip(query_embeddings, models)]
+combined_score = 0.5 * scores[0] + 0.5 * scores[1]
+```
+
+**Pros**:
+- ✅ Robust to individual model weaknesses
+- ✅ Better coverage of semantic space
+
+**Cons**:
+- ❌ 2x storage and compute
+- ❌ Complex scoring and fusion
+- ❌ Marginal improvement (~5-10%) over single best model
+
+**Expected Impact**: 5-10% over best single model
+
+**Verdict**: ❌ Not worth complexity
+
+### Combined Strategies
+
+#### Option D1: Best Chunking + Best Embedding (RECOMMENDED)
+
+**Combination**: Option C1 (Semantic Chunking) + Option E1 (mxbai-embed-large-v1)
+
+**Expected Impact**:
+- Chunking: +20-30% recall
+- Embedding: +15-25% recall
+- **Combined**: +35-55% recall improvement (not strictly additive, but significant)
+
+**Cost**:
+- Development: 1-2 days
+- Reindex: 2-4 hours (one-time)
+- Ongoing: None (same infrastructure)
+
+**Pros**:
+- ✅ Addresses both root causes
+- ✅ Orthogonal improvements (chunking + embedding)
+- ✅ Simple implementation
+- ✅ No new infrastructure
+- ✅ Future-proof foundation for additional enhancements (reranking, hybrid search)
+
+**Cons**:
+- ❌ Requires full reindex (manageable)
+- ❌ Slightly higher storage (1024 vs. 768 dim)
+
+**Verdict**: ✅ **RECOMMENDED**
+
+## Decision
+
+**Adopt Option D1: Semantic Chunking + Upgraded Embedding Model**
+
+Implement both improvements together to maximize recall improvement:
+
+### 1. Semantic Sentence-Aware Chunking
+
+**Changes**:
+- Replace naive word splitting with `RecursiveCharacterTextSplitter`
+- Preserve sentence boundaries, paragraph structure
+- Maintain similar chunk sizes (~512 words / 2048 characters)
+
+**Implementation**:
+
+```python
+# nextcloud_mcp_server/vector/document_chunker.py
+
+from langchain.text_splitter import RecursiveCharacterTextSplitter
+
+class DocumentChunker:
+    """Chunk documents into semantically coherent pieces."""
+
+    def __init__(
+        self,
+        chunk_size: int = 2048,  # Characters, not words
+        chunk_overlap: int = 200,  # Characters, not words
+    ):
+        self.chunk_size = chunk_size
+        self.chunk_overlap = chunk_overlap
+
+        self.splitter = RecursiveCharacterTextSplitter(
+            chunk_size=chunk_size,
+            chunk_overlap=chunk_overlap,
+            separators=[
+                "\n\n",  # Paragraphs (highest priority)
+                "\n",    # Lines
+                ". ",    # Sentences
+                "! ",
+                "? ",
+                "; ",    # Clauses
+                ": ",
+                ", ",    # Phrases
+                " ",     # Words (last resort)
+            ],
+            length_function=len,
+            is_separator_regex=False,
+        )
+
+    def chunk_text(self, content: str) -> list[str]:
+        """
+        Chunk text while preserving semantic boundaries.
+
+        Args:
+            content: Full document text
+
+        Returns:
+            List of text chunks, each ending at a semantic boundary
+        """
+        if not content:
+            return []
+
+        # Use RecursiveCharacterTextSplitter for semantic boundaries
+        chunks = self.splitter.split_text(content)
+
+        return chunks
+```
+
+**Configuration Changes** (`config.py`):
+```python
+# Old (word-based)
+DOCUMENT_CHUNK_SIZE: int = 512  # words
+DOCUMENT_CHUNK_OVERLAP: int = 50  # words
+
+# New (character-based, more precise)
+DOCUMENT_CHUNK_SIZE: int = 2048  # characters (~512 words)
+DOCUMENT_CHUNK_OVERLAP: int = 200  # characters (~50 words)
+```
+
+**Dependency** (`pyproject.toml`):
+```toml
+[project]
+dependencies = [
+    # ... existing dependencies
+    "langchain-text-splitters>=0.2.0",
+]
+```
+
+### 2. Upgrade Embedding Model
+
+**Changes**:
+- Switch from `nomic-embed-text` (768-dim) to `mxbai-embed-large-v1` (1024-dim)
+- Dynamic dimension detection (query Ollama instead of hardcoding)
+- Create new Qdrant collection for new dimensions
+
+**Implementation**:
+
+```python
+# nextcloud_mcp_server/embedding/ollama_provider.py
+
+class OllamaEmbeddingProvider(EmbeddingProvider):
+    def __init__(self, base_url: str, model: str, verify_ssl: bool = True):
+        self.base_url = base_url
+        self.model = model
+        self._dimension: int | None = None  # Changed: query dynamically
+        self.client = httpx.AsyncClient(base_url=base_url, verify=verify_ssl)
+
+    async def dimension(self) -> int:
+        """Get embedding dimension from Ollama API."""
+        if self._dimension is None:
+            try:
+                response = await self.client.post(
+                    "/api/show",
+                    json={"name": self.model},
+                    timeout=10.0,
+                )
+                response.raise_for_status()
+                info = response.json()
+                self._dimension = info.get("details", {}).get("embedding_length")
+
+                if self._dimension is None:
+                    # Fallback: generate test embedding to detect dimension
+                    test_emb = await self.embed("test")
+                    self._dimension = len(test_emb)
+
+            except Exception as e:
+                logger.warning(f"Failed to get dimension from Ollama: {e}, using fallback")
+                # Fallback dimensions by model name
+                if "mxbai-embed-large" in self.model:
+                    self._dimension = 1024
+                elif "nomic-embed-text" in self.model:
+                    self._dimension = 768
+                else:
+                    self._dimension = 768  # Default
+
+        return self._dimension
+```
+
+**Configuration Changes** (`config.py`):
+```python
+# Old
+OLLAMA_EMBEDDING_MODEL: str = "nomic-embed-text"
+
+# New
+OLLAMA_EMBEDDING_MODEL: str = "mxbai-embed-large-v1"
+```
+
+**Environment Variable**:
+```bash
+OLLAMA_EMBEDDING_MODEL=mxbai-embed-large-v1
+```
+
+### 3. Migration Strategy
+
+**Reindexing Process**:
+
+```python
+# nextcloud_mcp_server/vector/migration.py
+
+async def migrate_to_new_embeddings():
+    """
+    Migrate from old embeddings to new embeddings.
+
+    Process:
+    1. Create new collection with new dimension
+    2. Reindex all documents with new embeddings
+    3. Atomic swap (update collection name in config)
+    4. Delete old collection
+    """
+    old_collection = "nextcloud_content"
+    new_collection = "nextcloud_content_v2"
+
+    # 1. Create new collection
+    await qdrant_client.create_collection(
+        collection_name=new_collection,
+        vectors_config=VectorParams(
+            size=1024,  # mxbai-embed-large-v1 dimension
+            distance=Distance.COSINE,
+        ),
+    )
+
+    # 2. Reindex all documents
+    logger.info("Starting reindex with new embeddings...")
+    scanner = VectorScanner(...)
+    processor = VectorProcessor(collection_name=new_collection, ...)
+
+    await scanner.scan_all()  # Rescans and re-embeds all documents
+
+    # 3. Wait for completion
+    while True:
+        status = await get_sync_status()
+        if status.pending_documents == 0:
+            break
+        await asyncio.sleep(5)
+
+    # 4. Atomic swap
+    # Update config to point to new collection
+    # (or use collection alias in Qdrant)
+    await qdrant_client.update_collection_aliases(
+        change_aliases_operations=[
+            CreateAliasOperation(
+                create_alias=CreateAlias(
+                    collection_name=new_collection,
+                    alias_name="nextcloud_content"
+                )
+            )
+        ]
+    )
+
+    # 5. Verify new collection works
+    test_results = await run_benchmark_queries()
+    if test_results.recall < baseline_recall:
+        # Rollback
+        logger.error("New embeddings worse than baseline, rolling back")
+        await rollback_migration()
+        return False
+
+    # 6. Delete old collection
+    await qdrant_client.delete_collection(old_collection)
+    logger.info("Migration complete!")
+    return True
+```
+
+**Downtime Mitigation**:
+- Use Qdrant collection aliases for atomic swap
+- Reindex can happen in background
+- Only brief downtime during alias swap (~1s)
+
+**Rollback Plan**:
+- Keep old collection until validation complete
+- If new embeddings worse, swap alias back to old collection
+- No data loss
+
+### 4. Validation & Benchmarking
+
+**Before/After Comparison**:
+
+```python
+# tests/benchmarks/chunking_embedding_comparison.py
+
+async def benchmark_chunking_embeddings():
+    """
+    Compare old vs. new chunking and embeddings on test queries.
+    """
+    test_queries = load_benchmark_queries()  # 100 queries with known relevant docs
+
+    # Baseline (current)
+    baseline_results = await run_queries(
+        queries=test_queries,
+        collection="nextcloud_content",  # Old: nomic-embed-text, word chunks
+    )
+
+    # New implementation
+    new_results = await run_queries(
+        queries=test_queries,
+        collection="nextcloud_content_v2",  # New: mxbai-embed-large-v1, semantic chunks
+    )
+
+    # Compare metrics
+    comparison = {
+        "baseline": {
+            "recall@10": calculate_recall(baseline_results, k=10),
+            "precision@10": calculate_precision(baseline_results, k=10),
+            "mrr": calculate_mrr(baseline_results),
+            "zero_result_rate": calculate_zero_result_rate(baseline_results),
+        },
+        "new": {
+            "recall@10": calculate_recall(new_results, k=10),
+            "precision@10": calculate_precision(new_results, k=10),
+            "mrr": calculate_mrr(new_results),
+            "zero_result_rate": calculate_zero_result_rate(new_results),
+        },
+        "improvement": {
+            "recall_improvement": (new_recall - baseline_recall) / baseline_recall,
+            "precision_improvement": (new_precision - baseline_precision) / baseline_precision,
+        }
+    }
+
+    return comparison
+```
+
+**Success Criteria**:
+- **Recall@10**: Improve from ~52% to ≥75% (+40% improvement)
+- **Precision@10**: Maintain ≥75% (no degradation)
+- **MRR**: Improve from 0.58 to ≥0.70
+- **Zero-result rate**: Reduce from 18% to ≤10%
+- **Indexing time**: Maintain ≤10s per document
+
+**Validation Process**:
+1. Run benchmark on baseline (current implementation)
+2. Implement changes
+3. Run benchmark on new implementation
+4. Compare metrics
+5. If improvement ≥40%, proceed to production
+6. If improvement <40%, investigate and iterate
+
+## Implementation Timeline
+
+### Week 1: Development & Testing
+
+**Day 1-2: Chunking Implementation**
+- [ ] Add langchain-text-splitters dependency
+- [ ] Refactor `document_chunker.py`
+- [ ] Update configuration (character-based chunk sizes)
+- [ ] Write unit tests for semantic boundaries
+- [ ] Validate: Chunks never break mid-sentence
+
+**Day 3-4: Embedding Implementation**
+- [ ] Update `ollama_provider.py` with dynamic dimension detection
+- [ ] Update configuration (new model name)
+- [ ] Deploy `mxbai-embed-large-v1` to Ollama
+- [ ] Test embedding generation with new model
+- [ ] Validate: Embeddings are 1024-dim
+
+**Day 5: Migration Script**
+- [ ] Write migration script (collection creation, reindexing, alias swap)
+- [ ] Test migration on staging environment
+- [ ] Validate: No data loss, atomic swap works
+
+### Week 2: Reindexing & Validation
+
+**Day 1-2: Staging Reindex**
+- [ ] Run full reindex on staging environment
+- [ ] Monitor indexing performance
+- [ ] Validate: All documents indexed correctly
+
+**Day 3: Benchmarking**
+- [ ] Run benchmark queries on old collection (baseline)
+- [ ] Run benchmark queries on new collection
+- [ ] Compare metrics (recall, precision, MRR)
+- [ ] Validate: ≥40% recall improvement
+
+**Day 4: Production Reindex**
+- [ ] Schedule maintenance window (optional, can run in background)
+- [ ] Run migration script on production
+- [ ] Monitor reindexing progress
+- [ ] Atomic swap when complete
+
+**Day 5: Production Validation**
+- [ ] Monitor search quality metrics
+- [ ] Collect user feedback
+- [ ] Compare production metrics to staging
+- [ ] Rollback if issues detected
+
+## Cost Analysis
+
+### Development Cost
+- **Time**: 1-2 weeks (implementation + validation)
+- **Effort**: 40-60 hours @ $100/hour = $4,000 - $6,000
+
+### Infrastructure Cost
+- **Storage**: +30% (1024-dim vs. 768-dim)
+  - Example: 1,000 notes × 3 chunks × 1024 dim × 4 bytes = 12 MB (negligible)
+- **Compute**: +20% embedding time (50ms vs. 30ms per chunk)
+  - Amortized over batch indexing, minimal impact
+- **No new infrastructure**: Uses existing Ollama + Qdrant
+
+### Reindexing Cost (One-Time)
+- **Time**: 2-4 hours for 1,000 documents
+  - 1,000 docs × 3 chunks × 50ms = 150 seconds (~2.5 minutes embedding)
+  - + Ollama processing time + Qdrant insertion
+- **Downtime**: ~1 second (atomic alias swap)
+
+### Total Cost
+- **Initial**: $4,000 - $6,000 (development + testing)
+- **Ongoing**: $0 (no new infrastructure or API costs)
+
+### ROI
+- **Recall improvement**: +40-60% (finding relevant documents)
+- **User satisfaction**: Reduced zero-result queries (18% → 10%)
+- **Foundation**: Enables future enhancements (reranking, hybrid search)
+- **Cost per % improvement**: $100 - $150 (excellent ROI)
+
+## Consequences
+
+### Positive
+
+1. **Addresses Root Causes**: Fixes fundamental issues (chunking, embeddings) not symptoms
+2. **High Impact**: Expected 40-60% recall improvement from foundational changes
+3. **Future-Proof**: Creates solid foundation for future enhancements (reranking, hybrid search, GraphRAG)
+4. **Simple**: No architectural changes, no new infrastructure
+5. **Orthogonal**: Improvements are independent, can be validated separately
+6. **Low Risk**: Proven techniques (RecursiveCharacterTextSplitter, mxbai-embed-large-v1)
+7. **Maintainable**: Standard libraries and models, easy to debug
+
+### Negative
+
+1. **Reindexing Required**: 2-4 hours one-time cost (manageable, can run in background)
+2. **Storage Increase**: +30% for higher-dimensional embeddings (12 MB vs. 9 MB for 1K docs)
+3. **Slower Indexing**: +20% embedding time (50ms vs. 30ms per chunk)
+4. **Dependency**: Adds langchain-text-splitters (minimal, well-maintained library)
+5. **Not a Complete Solution**: May still need reranking/hybrid search for optimal recall (but solid foundation)
+
+### Neutral
+
+1. **Model Lock-In**: Committed to mxbai-embed-large-v1, but can change later (another reindex)
+2. **Chunk Size Trade-offs**: ~512 words is heuristic, may need tuning for specific content types
+
+## Monitoring & Success Metrics
+
+### Real-Time Metrics (Grafana)
+
+**Search Quality**:
+- `semantic_search_recall_at_10` (target: ≥75%)
+- `semantic_search_precision_at_10` (target: ≥75%)
+- `semantic_search_mrr` (target: ≥0.70)
+- `semantic_search_zero_result_rate` (target: ≤10%)
+
+**Performance**:
+- `semantic_search_latency_ms` (p50, p95, p99)
+- `embedding_generation_time_ms`
+- `indexing_throughput_docs_per_sec`
+
+**Indexing**:
+- `documents_indexed_total`
+- `documents_pending`
+- `indexing_errors_total`
+
+### Weekly Validation
+
+**A/B Testing** (if gradual rollout):
+- 50% users: New embeddings
+- 50% users: Old embeddings
+- Compare metrics for 1 week
+- Full rollout if new embeddings superior
+
+**User Feedback**:
+- Survey: "How satisfied are you with search results?" (1-5 scale)
+- Track: Number of "search not working" support tickets
+- Monitor: User-reported false negatives ("I know this doc exists")
+
+### Rollback Criteria
+
+**Automatic Rollback** if:
+- Recall decreases by >10% from baseline
+- Error rate increases by >50%
+- Query latency increases by >100%
+
+**Manual Rollback** if:
+- User complaints increase significantly
+- Zero-result queries increase instead of decrease
+
+## Future Enhancements
+
+These improvements create a solid foundation. Future enhancements (in order of priority):
+
+1. **Cross-Encoder Reranking** (ADR-012)
+   - Two-stage retrieval: broad recall (50 candidates) → precise reranking (top 10)
+   - Expected: +15-20% additional recall improvement
+   - Builds on: Better embeddings retrieve better candidates to rerank
+
+2. **Hybrid Search** (ADR-013)
+   - Combine vector search + BM25 keyword search
+   - Expected: +10-15% additional recall (especially for exact matches)
+   - Builds on: Semantic chunks provide better keyword match context
+
+3. **Multi-App Indexing** (ADR-014)
+   - Index calendar, deck, files (currently notes-only)
+   - Expected: Expands searchable corpus 3-5x
+   - Builds on: Proven chunking and embedding strategy
+
+4. **GraphRAG** (ADR-015, conditional)
+   - Only if: Global thematic queries needed OR corpus >10K documents
+   - Expected: Relationship discovery, multi-hop reasoning
+   - Builds on: High-quality embeddings improve graph construction
+
+## References
+
+### Research Papers
+
+1. **RecursiveCharacterTextSplitter**
+   - LangChain Documentation: https://python.langchain.com/docs/modules/data_connection/document_transformers/text_splitters/recursive_text_splitter
+   - Proven technique used by major RAG systems
+
+2. **MTEB Leaderboard** (Massive Text Embedding Benchmark)
+   - https://huggingface.co/spaces/mteb/leaderboard
+   - Comprehensive embedding model comparison
+
+3. **mxbai-embed-large**
+   - Model: https://huggingface.co/mixedbread-ai/mxbai-embed-large-v1
+   - Best general-purpose embedding model (MTEB: 64.68)
+
+### Related ADRs
+
+- **ADR-003**: Vector Database and Semantic Search Architecture (original implementation)
+- **ADR-008**: MCP Sampling for Multi-App Semantic Search with RAG (answer generation)
+
+### Tools & Libraries
+
+- **LangChain Text Splitters**: https://python.langchain.com/docs/modules/data_connection/document_transformers/
+- **Ollama Embedding Models**: https://ollama.ai/library
+- **Qdrant Collections**: https://qdrant.tech/documentation/concepts/collections/
+
+## Summary
+
+This ADR addresses the root causes of poor semantic search recall:
+
+1. **Better Chunking**: Semantic sentence-aware splitting (preserves context)
+2. **Better Embeddings**: Upgrade to mxbai-embed-large-v1 (richer semantic space)
+
+**Expected Impact**: 40-60% recall improvement with minimal cost and complexity.
+
+**Why This Approach**:
+- Fixes fundamentals before adding complexity
+- Proven techniques (not experimental)
+- Simple implementation (1-2 weeks)
+- Creates foundation for future enhancements
+- No new infrastructure or ongoing costs
+
+**Next Steps**: Approve ADR → Implement changes → Reindex → Validate → Production rollout
+
+## Implementation Status
+
+### Completed (2025-11-18)
+
+**✅ Semantic Markdown-Aware Chunking (Option C1 + C3 Hybrid)**
+
+Implementation details:
+- Replaced custom word-based chunking with `MarkdownTextSplitter` from LangChain
+- Optimized for Nextcloud Notes markdown content with special handling for:
+  - Headers (`#`, `##`, `###`, etc.)
+  - Code blocks (` ``` `)
+  - Lists (`-`, `*`, `1.`)
+  - Horizontal rules (`---`)
+  - Paragraphs and sentences
+- Maintained `ChunkWithPosition` interface for backward compatibility
+- Updated configuration defaults:
+  - `DOCUMENT_CHUNK_SIZE`: 512 words → 2048 characters
+  - `DOCUMENT_CHUNK_OVERLAP`: 50 words → 200 characters
+- Updated unit tests to verify position tracking and boundary preservation
+- All tests passing with markdown-aware character-based chunking
+
+**Files Modified**:
+- `nextcloud_mcp_server/vector/document_chunker.py` - LangChain integration
+- `nextcloud_mcp_server/config.py` - Character-based defaults
+- `tests/unit/test_document_chunker.py` - Updated test suite
+
+**Dependencies Added**:
+- `langchain-text-splitters>=1.0.0` (already present in `pyproject.toml`)
+
+**Migration Required**:
+- ⚠️ Full reindex required to apply new chunking strategy
+- Existing documents in vector database use old word-based chunks
+- See "Migration Strategy" section above for reindexing process
+
+### Pending
+
+**⏳ Embedding Model Upgrade (Option E1)**
+
+Still to be implemented:
+- Switch from `nomic-embed-text` (768-dim) to `mxbai-embed-large-v1` (1024-dim)
+- Implement dynamic dimension detection in `ollama_provider.py`
+- Create migration script for collection reindexing
+- Run benchmarking to validate improvement
+- Deploy to production with atomic collection swap
+
+**Estimated Timeline**: 1-2 weeks for implementation and validation

docs/ADR-012-unified-multi-algorithm-search.md

@@ -0,0 +1,619 @@
+# ADR-012: Unified Multi-Algorithm Search with Client-Configurable Weighting
+
+## Status
+Proposed
+
+## Context
+
+### Current State
+
+The Nextcloud MCP server currently provides semantic search via vector similarity (Qdrant), as designed in ADR-003 and implemented through ADR-007. However, users and MCP clients have limited control over search behavior:
+
+1. **Single algorithm only**: Only pure vector similarity search is available
+2. **No algorithm selection**: MCP clients cannot choose between semantic, keyword, or fuzzy approaches
+3. **No weighting control**: Clients cannot adjust the balance between different search methods
+4. **Disconnected implementations**: Viz pane uses different search algorithms than MCP tools
+5. **Limited flexibility**: No way to optimize search for different use cases (exact match vs. conceptual similarity)
+
+### User Needs
+
+Different search scenarios require different algorithms:
+
+- **Exact match queries**: "Find note titled 'Q1 Budget'" → keyword search preferred
+- **Conceptual queries**: "What are my goals for next quarter?" → semantic search preferred
+- **Typo-tolerant queries**: "Find note about kuberntes" → fuzzy search needed
+- **Balanced queries**: "Find documentation about API endpoints" → hybrid search optimal
+
+Additionally, users need a **testing interface** (viz pane) to:
+- Experiment with different search algorithms on their own documents
+- Visualize search results and algorithm behavior
+- Tune weights for optimal results
+- Understand which algorithm works best for their queries
+
+### Technical Requirements
+
+1. **Unified interface**: Single MCP tool supporting multiple algorithms
+2. **Client control**: MCP clients specify algorithm and weights via tool parameters
+3. **Backward compatibility**: Existing `nc_semantic_search()` behavior preserved
+4. **Shared implementation**: Viz pane and MCP tools use identical search algorithms
+5. **User accessibility**: Viz pane available to all logged-in users with vector sync enabled
+6. **Performance**: Minimal overhead for algorithm selection
+
+## Decision
+
+We will implement a **unified multi-algorithm search architecture** with the following components:
+
+### Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         MCP Client / User Browser                            │
+│                                                                               │
+│  ┌──────────────────────────┐         ┌──────────────────────────────────┐  │
+│  │   MCP Tool Call          │         │   Viz Pane (Browser UI)          │  │
+│  │                          │         │                                  │  │
+│  │ nc_semantic_search(      │         │ - Algorithm selector dropdown    │  │
+│  │   query="kubernetes",    │         │ - Weight adjustment sliders      │  │
+│  │   algorithm="hybrid",    │         │ - Interactive 2D scatter plot    │  │
+│  │   semantic_weight=0.5,   │         │ - Side-by-side comparison        │  │
+│  │   keyword_weight=0.3,    │         │ - Real-time search testing       │  │
+│  │   fuzzy_weight=0.2       │         │                                  │  │
+│  │ )                        │         │                                  │  │
+│  └───────────┬──────────────┘         └────────────┬─────────────────────┘  │
+└──────────────┼─────────────────────────────────────┼────────────────────────┘
+               │                                      │
+               │ MCP Protocol                         │ HTTPS (htmx)
+               │                                      │
+┌──────────────▼──────────────────────────────────────▼────────────────────────┐
+│                        MCP Server (/app endpoint)                             │
+│                                                                               │
+│  ┌─────────────────────────────────────────────────────────────────────────┐ │
+│  │              Unified Search Interface (server/semantic.py)              │ │
+│  │                                                                         │ │
+│  │  @mcp.tool() nc_semantic_search(algorithm, weights...)                 │ │
+│  │  ├─ Validate parameters (weights sum ≤1.0)                             │ │
+│  │  ├─ Dispatch to algorithm selector                                     │ │
+│  │  └─ Return ranked SearchResponse                                       │ │
+│  └────────────────────────────┬────────────────────────────────────────────┘ │
+│                                │                                              │
+│  ┌────────────────────────────▼────────────────────────────────────────────┐ │
+│  │              Algorithm Dispatcher (search/algorithms.py)                │ │
+│  │                                                                         │ │
+│  │  if algorithm == "semantic":    → semantic.py                          │ │
+│  │  if algorithm == "keyword":     → keyword.py                           │ │
+│  │  if algorithm == "fuzzy":       → fuzzy.py                             │ │
+│  │  if algorithm == "hybrid":      → hybrid.py (RRF fusion)               │ │
+│  └─────────────────────────────────────────────────────────────────────────┘ │
+│                                                                               │
+│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐           │
+│  │  semantic.py     │  │  keyword.py      │  │  fuzzy.py        │           │
+│  │                  │  │                  │  │                  │           │
+│  │ • Query Qdrant   │  │ • Token matching │  │ • Char overlap   │           │
+│  │ • Cosine dist    │  │ • Title weight   │  │ • 70% threshold  │           │
+│  │ • Score ≥0.7     │  │ • ADR-001 logic  │  │ • Simple impl    │           │
+│  └────────┬─────────┘  └────────┬─────────┘  └────────┬─────────┘           │
+│           │                     │                      │                     │
+│           └─────────────────────┼──────────────────────┘                     │
+│                                 │                                            │
+│  ┌──────────────────────────────▼──────────────────────────────────────────┐ │
+│  │                    hybrid.py (Reciprocal Rank Fusion)                   │ │
+│  │                                                                         │ │
+│  │  1. Run algorithms in parallel (semantic, keyword, fuzzy)              │ │
+│  │  2. Collect ranked results from each                                   │ │
+│  │  3. Apply RRF formula: score = weight / (k + rank)                     │ │
+│  │  4. Combine scores across algorithms                                   │ │
+│  │  5. Re-rank by combined score                                          │ │
+│  └─────────────────────────────────────────────────────────────────────────┘ │
+└───────────────────────────────────┬───────────────────────────────────────────┘
+                                    │
+                    ┌───────────────┴───────────────┐
+                    │                               │
+         ┌──────────▼──────────┐         ┌─────────▼────────────┐
+         │ Qdrant Vector DB    │         │ Nextcloud APIs       │
+         │                     │         │                      │
+         │ • Vector search     │         │ • Access verification│
+         │ • user_id filter    │         │ • Full metadata fetch│
+         │ • Score threshold   │         │ • Permission checks  │
+         │ • 768-dim embeddings│         │                      │
+         └─────────────────────┘         └──────────────────────┘
+```
+
+### Data Flow
+
+#### MCP Tool Request
+```
+1. Client calls nc_semantic_search(query, algorithm="hybrid", weights...)
+2. Server validates parameters (weights sum ≤1.0)
+3. Dispatcher routes to hybrid.py
+4. Hybrid search runs semantic, keyword, fuzzy in parallel
+5. RRF combines results with weighted scores
+6. Access verification via Nextcloud API
+7. Return ranked SearchResponse to client
+```
+
+#### Viz Pane Request (Server-Side Processing)
+```
+1. User navigates to /app (Vector Visualization tab)
+2. Browser loads vector-viz fragment via htmx
+3. User enters query and adjusts algorithm/weights
+4. htmx sends request to /app/vector-viz endpoint
+5. Server executes search via search/algorithms.py:
+   - Filters by user_id (multi-tenant security)
+   - Applies selected algorithm (semantic/keyword/fuzzy/hybrid)
+   - Filters by document type (notes/files/calendar/contacts)
+   - Retrieves matching results + metadata
+6. Server performs PCA reduction (768-dim → 2D):
+   - Converts matching results to 2D coordinates
+   - Only sends coordinates + metadata (not full vectors)
+   - Dramatically reduces bandwidth (e.g., 768 floats → 2 floats per doc)
+7. Server returns JSON: {results: [...], coordinates_2d: [...], stats: {...}}
+8. Browser receives lightweight response
+9. Plotly.js renders interactive scatter plot
+10. Matching results highlighted (blue), non-matches grayed (40% opacity)
+```
+
+**Performance Benefits of Server-Side Processing**:
+- **Bandwidth reduction**: ~384x less data (2 floats vs 768 floats per document)
+- **Client efficiency**: Browser only handles visualization, not computation
+- **Scalability**: Can visualize 10,000+ documents without client-side lag
+- **Security**: Raw vectors never leave server
+- **Consistency**: Same search logic as MCP tool (no drift)
+
+### 1. Core Search Algorithms
+
+Four search algorithms will be available:
+
+#### a) Semantic Search (Vector Similarity)
+- **Method**: Cosine distance in 768-dimensional embedding space
+- **Implementation**: Qdrant `query_points` with user_id filtering
+- **Use case**: Conceptual queries, finding related content
+- **Current status**: Implemented in `nextcloud_mcp_server/server/semantic.py`
+
+#### b) Keyword Search (Token-Based)
+- **Method**: Token matching with weighted scoring (from ADR-001)
+- **Implementation**: Title matches weighted 3x higher than content
+- **Use case**: Exact phrase matching, known titles
+- **Current status**: Designed in ADR-001, not implemented
+
+#### c) Fuzzy Search (Character Overlap)
+- **Method**: Simple character-based similarity (70% threshold)
+- **Implementation**: Character set comparison (current viz pane approach)
+- **Use case**: Typo tolerance, approximate matching
+- **Current status**: Implemented in viz pane only
+
+#### d) Hybrid Search (Multi-Algorithm Fusion)
+- **Method**: Reciprocal Rank Fusion (RRF) from ADR-003
+- **Implementation**: Parallel execution + score combination
+- **Use case**: Balanced queries, general-purpose search
+- **Current status**: Designed in ADR-003, not implemented
+
+### 2. Unified MCP Tool Interface
+
+```python
+@mcp.tool()
+@require_scopes("semantic:read")
+async def nc_semantic_search(
+    query: str,
+    ctx: Context,
+    limit: int = 10,
+    score_threshold: float = 0.7,
+    algorithm: Literal["semantic", "keyword", "fuzzy", "hybrid"] = "hybrid",
+    semantic_weight: float = 0.5,
+    keyword_weight: float = 0.3,
+    fuzzy_weight: float = 0.2,
+) -> SearchResponse:
+    """
+    Search Nextcloud content using configurable algorithms.
+
+    Args:
+        query: Natural language search query
+        ctx: MCP context for authentication
+        limit: Maximum results to return
+        score_threshold: Minimum similarity score (semantic/hybrid only)
+        algorithm: Search algorithm to use
+        semantic_weight: Weight for semantic results (hybrid only, default: 0.5)
+        keyword_weight: Weight for keyword results (hybrid only, default: 0.3)
+        fuzzy_weight: Weight for fuzzy results (hybrid only, default: 0.2)
+
+    Returns:
+        Ranked search results with scores and excerpts
+    """
+```
+
+**Key decisions**:
+- **Single tool name**: Keep `nc_semantic_search` for backward compatibility
+- **Algorithm parameter**: Explicit selection via enum
+- **Weight parameters**: Client-configurable, only apply to hybrid mode
+- **Validation**: Weights must sum to ≤1.0, enforced server-side
+- **Defaults**: Hybrid mode with balanced weights (semantic 50%, keyword 30%, fuzzy 20%)
+
+### 3. Shared Algorithm Implementation
+
+Extract search algorithms into reusable module:
+
+```
+nextcloud_mcp_server/
+├── search/
+│   ├── __init__.py
+│   ├── algorithms.py          # Core search implementations
+│   ├── semantic.py             # Vector similarity search
+│   ├── keyword.py              # Token-based search (ADR-001)
+│   ├── fuzzy.py                # Character overlap search
+│   └── hybrid.py               # RRF fusion (ADR-003)
+└── server/
+    └── semantic.py             # MCP tool wrapper
+```
+
+**Benefits**:
+- Viz pane and MCP tools share identical implementations
+- Testable in isolation
+- Easy to add new algorithms (e.g., BM25, neural reranking)
+- Clear separation of concerns
+
+### 4. Viz Pane Integration
+
+Update viz pane (`nextcloud_mcp_server/auth/userinfo_routes.py`) to:
+
+1. **Use shared algorithms**: Import from `search/algorithms.py`
+2. **Server-side filtering**: All search and filtering operations happen server-side
+   - Query execution via shared search backend
+   - Document type filtering (notes, files, calendar, contacts)
+   - User ID filtering for multi-tenant security
+   - Only matching results + metadata sent to client
+   - Reduces bandwidth and improves performance
+3. **PCA reduction**: Server performs dimensionality reduction (768-dim → 2D)
+   - Only 2D coordinates sent to browser for visualization
+   - Dramatically reduces data transfer vs sending full vectors
+   - Enables visualization of large document collections
+4. **User accessibility**: Available to all users with vector sync enabled
+5. **Security**: Filter results by `user_id` (only show user's own documents)
+6. **Interactive testing**: Allow users to:
+   - Select algorithm type
+   - Adjust weights (hybrid mode)
+   - Compare results across algorithms
+   - Visualize result distribution in 2D space
+
+#### Viz Pane UI Components
+
+```
+┌────────────────────────────────────────────────────────────────────────┐
+│ Vector Visualization                                          [Status] │
+├────────────────────────────────────────────────────────────────────────┤
+│                                                                        │
+│ ┌──────────────────────────────────────────────────────────────────┐  │
+│ │ Search Configuration                                             │  │
+│ │                                                                  │  │
+│ │ Query: [_______________________________________________] [Search]│  │
+│ │                                                                  │  │
+│ │ Algorithm: [Hybrid ▼]  [Semantic] [Keyword] [Fuzzy]             │  │
+│ │                                                                  │  │
+│ │ Weights (Hybrid Mode):                                           │  │
+│ │   Semantic: [========50========] 0.5                             │  │
+│ │   Keyword:  [======30======    ] 0.3                             │  │
+│ │   Fuzzy:    [====20====        ] 0.2                             │  │
+│ │                                                                  │  │
+│ │ Document Types: ☑ Notes  ☑ Files  ☑ Calendar  ☑ Contacts        │  │
+│ └──────────────────────────────────────────────────────────────────┘  │
+│                                                                        │
+│ ┌──────────────────────────────────────────────────────────────────┐  │
+│ │ Vector Space Visualization (PCA 2D Projection)                   │  │
+│ │                                                                  │  │
+│ │        ▲                                                         │  │
+│ │    PC2 │     ●  ● ●      🔵 Matching results (full opacity)     │  │
+│ │        │  ●     ●  ●     ⚪ Non-matching results (40% opacity)   │  │
+│ │        │    🔵  ● ●                                              │  │
+│ │        │  ●  🔵  ●       Hover: Show document title + excerpt    │  │
+│ │        │  ● ●  🔵 ●      Click: Open document in Nextcloud       │  │
+│ │    ────┼──●─🔵──●─●────► PC1                                     │  │
+│ │        │   ● ●  ●                                                │  │
+│ │        │    🔵 ●   ●     Explained Variance:                     │  │
+│ │        │  ●    ●  ●      PC1: 23.4% | PC2: 18.7%                 │  │
+│ │        │     ● ●                                                 │  │
+│ │                                                                  │  │
+│ └──────────────────────────────────────────────────────────────────┘  │
+│                                                                        │
+│ ┌──────────────────────────────────────────────────────────────────┐  │
+│ │ Search Results (12 matching documents)                           │  │
+│ │                                                                  │  │
+│ │ 🔵 Kubernetes Setup Guide                        Score: 0.87     │  │
+│ │    "...configure kubectl to connect to cluster..."              │  │
+│ │    [Open in Nextcloud]                                           │  │
+│ │                                                                  │  │
+│ │ 🔵 Container Orchestration Notes                 Score: 0.82     │  │
+│ │    "...deployment strategies for kubernetes..."                 │  │
+│ │    [Open in Nextcloud]                                           │  │
+│ │                                                                  │  │
+│ │ 🔵 K8s Troubleshooting                           Score: 0.79     │  │
+│ │    "...common kuberntes errors and solutions..."                │  │
+│ │    [Open in Nextcloud]                                           │  │
+│ │                                                                  │  │
+│ │ [Show More Results...]                                           │  │
+│ └──────────────────────────────────────────────────────────────────┘  │
+│                                                                        │
+│ ┌──────────────────────────────────────────────────────────────────┐  │
+│ │ Algorithm Performance Comparison                                 │  │
+│ │                                                                  │  │
+│ │ Algorithm    │ Results │ Avg Score │ Time (ms) │ Precision     │  │
+│ │ ─────────────┼─────────┼───────────┼───────────┼───────────     │  │
+│ │ Semantic     │   45    │   0.78    │   145ms   │  ████░ 0.82   │  │
+│ │ Keyword      │   23    │   0.91    │    42ms   │  ███░░ 0.67   │  │
+│ │ Fuzzy        │   67    │   0.72    │    89ms   │  ██░░░ 0.45   │  │
+│ │ Hybrid (RRF) │   52    │   0.84    │   198ms   │  █████ 0.89   │  │
+│ └──────────────────────────────────────────────────────────────────┘  │
+└────────────────────────────────────────────────────────────────────────┘
+```
+
+**Key UI Features**:
+
+1. **Search Input**: Real-time query testing with instant visualization
+2. **Algorithm Selector**: Dropdown + quick-select buttons
+3. **Weight Sliders**: Visual adjustment with live preview (hybrid mode only)
+4. **Document Type Filters**: Checkboxes for notes, files, calendar, contacts
+5. **2D Scatter Plot**: Interactive Plotly.js visualization
+   - Blue dots = matching documents (full opacity)
+   - Gray dots = non-matching documents (40% opacity)
+   - Hover = show title + excerpt tooltip
+   - Click = open document in Nextcloud
+   - Zoom/pan controls for exploration
+6. **Results Panel**: Ranked list with scores and excerpts
+7. **Performance Table**: Compare algorithm speed and accuracy
+8. **Explained Variance**: Show how much information PCA preserves
+
+**Technology Stack**:
+- **Frontend**: htmx for dynamic loading, Alpine.js for reactivity
+- **Visualization**: Plotly.js for interactive scatter plots
+- **Styling**: Tailwind CSS (consistent with existing /app UI)
+- **Backend**: Shared `search/algorithms.py` implementation
+
+### 5. Reciprocal Rank Fusion (RRF) for Hybrid Search
+
+Following ADR-003's design:
+
+```python
+def reciprocal_rank_fusion(
+    results: dict[str, list[SearchResult]],
+    weights: dict[str, float],
+    k: int = 60
+) -> list[SearchResult]:
+    """
+    Combine multiple ranked result lists using RRF.
+
+    Args:
+        results: Dict of algorithm_name -> ranked results
+        weights: Dict of algorithm_name -> weight (0-1)
+        k: RRF constant (default: 60, standard value)
+
+    Returns:
+        Combined and re-ranked results
+    """
+    scores = defaultdict(float)
+
+    for algo_name, algo_results in results.items():
+        weight = weights.get(algo_name, 0.0)
+        for rank, result in enumerate(algo_results, start=1):
+            # RRF formula: 1 / (k + rank)
+            rrf_score = weight / (k + rank)
+            scores[result.doc_id] += rrf_score
+
+    # Sort by combined score, return top results
+    return sorted(scores.items(), key=lambda x: x[1], reverse=True)
+```
+
+**RRF properties**:
+- **Rank-based**: Uses position, not raw scores (handles score scale differences)
+- **Proven effective**: Standard approach in information retrieval
+- **Configurable**: `k` parameter controls rank decay (default: 60)
+- **Weight support**: Allows algorithm-specific importance
+
+## Implementation Plan
+
+### Phase 1: Extract and Unify Algorithms (Week 1)
+
+1. Create `nextcloud_mcp_server/search/` module
+2. Implement `algorithms.py` with base interface
+3. Extract semantic search logic from `server/semantic.py`
+4. Implement keyword search from ADR-001 design
+5. Extract fuzzy search from viz pane
+6. Implement RRF hybrid search from ADR-003
+7. Add comprehensive unit tests for each algorithm
+
+### Phase 2: Update MCP Tool (Week 1-2)
+
+1. Add `algorithm` parameter to `nc_semantic_search()`
+2. Add weight parameters (`semantic_weight`, etc.)
+3. Implement algorithm dispatcher
+4. Add parameter validation (weights sum ≤1.0)
+5. Update response model to include algorithm metadata
+6. Maintain backward compatibility (default: hybrid)
+7. Add integration tests for all algorithm modes
+
+### Phase 3: Update Viz Pane (Week 2)
+
+**Critical: All processing must happen server-side**
+
+1. **Remove client-side search filtering**
+   - Delete JavaScript-based keyword/fuzzy matching
+   - Remove client-side document type filtering
+   - No search logic in browser
+2. **Implement server-side endpoint** (`/app/vector-viz`)
+   - Accept query, algorithm, weights, doc_type filters
+   - Execute search via `search/algorithms.py`
+   - Filter results by user_id (security)
+   - Perform PCA reduction (768-dim → 2D)
+   - Return JSON with 2D coordinates + metadata only
+3. **Update frontend**
+   - htmx form submission to `/app/vector-viz`
+   - Algorithm selector dropdown
+   - Weight adjustment sliders (htmx updates on change)
+   - Document type checkboxes
+   - Plotly.js visualization of server response
+4. **Performance optimization**
+   - Limit results to user's documents only
+   - Cache PCA transformation (invalidate on new vectors)
+   - Stream large result sets if needed
+   - Add loading indicators for server processing
+
+### Phase 4: Documentation and Testing (Week 2-3)
+
+1. Update MCP tool documentation
+2. Add algorithm selection guide
+3. Document weight tuning recommendations
+4. Add end-to-end tests (MCP + viz pane)
+5. Performance benchmarks for each algorithm
+6. Update CLAUDE.md with search patterns
+
+## Consequences
+
+### Positive
+
+1. **Flexibility**: MCP clients can optimize search for their use case
+2. **Unified implementation**: Single source of truth for search algorithms
+3. **User empowerment**: Viz pane enables query testing and tuning
+4. **Backward compatible**: Existing semantic search behavior preserved
+5. **Extensible**: Easy to add new algorithms (BM25, neural reranking)
+6. **Testable**: Each algorithm can be unit tested independently
+7. **Standards-based**: RRF is proven in production systems
+
+### Negative
+
+1. **Complexity**: More parameters for clients to understand
+2. **API surface**: Larger tool signature (8 parameters)
+3. **Performance**: Hybrid search requires multiple queries
+4. **Validation overhead**: Weight validation adds processing
+5. **Documentation burden**: Need to explain when to use each algorithm
+
+### Neutral
+
+1. **Weight defaults**: May need tuning based on user feedback
+2. **Algorithm performance**: Will vary by content type and query
+3. **Viz pane adoption**: Unknown if users will utilize testing interface
+
+## Alternatives Considered
+
+### Alternative 1: Separate Tools Per Algorithm
+
+```python
+@mcp.tool()
+async def nc_semantic_search(query: str, ctx: Context, ...) -> SearchResponse:
+    """Pure vector similarity search."""
+
+@mcp.tool()
+async def nc_keyword_search(query: str, ctx: Context, ...) -> SearchResponse:
+    """Pure keyword matching."""
+
+@mcp.tool()
+async def nc_hybrid_search(query: str, ctx: Context, weights: dict, ...) -> SearchResponse:
+    """Hybrid search with weights."""
+```
+
+**Rejected because**:
+- API proliferation (3+ tools instead of 1)
+- Harder to discover capabilities
+- Backward compatibility issues
+- DRY violation (repeated parameters)
+
+### Alternative 2: Server-Wide Configuration Only
+
+```python
+# .env configuration
+SEARCH_ALGORITHM=hybrid
+SEMANTIC_WEIGHT=0.5
+KEYWORD_WEIGHT=0.3
+FUZZY_WEIGHT=0.2
+```
+
+**Rejected because**:
+- No per-query flexibility
+- MCP clients cannot optimize for different tasks
+- Requires server restart for changes
+- User's requirement: "expose a way for users to override the default weights"
+
+### Alternative 3: Production-Grade Fuzzy (Levenshtein/RapidFuzz)
+
+**Rejected because**:
+- Adds external dependency
+- Simple character overlap performs adequately
+- Can always upgrade later if needed
+- User's preference: "Keep simple character overlap"
+
+## Related ADRs
+
+- **ADR-001**: Enhanced Note Search (keyword algorithm design)
+- **ADR-003**: Vector Database and Semantic Search (hybrid search + RRF design)
+- **ADR-007**: Background Vector Sync (semantic search implementation)
+- **ADR-008**: MCP Sampling for RAG (uses semantic search results)
+- **ADR-009**: Semantic Search OAuth Scope (security model)
+- **ADR-011**: Improving Semantic Search Quality (mentions future "ADR-013" for hybrid search)
+
+**This ADR supersedes**:
+- ADR-011's placeholder for "ADR-013: Hybrid Search"
+
+**This ADR implements**:
+- ADR-003's hybrid search design (previously unimplemented)
+- ADR-001's keyword search design (previously unimplemented)
+
+## References
+
+- **Reciprocal Rank Fusion**: Cormack, G. V., Clarke, C. L., & Buettcher, S. (2009). "Reciprocal rank fusion outperforms condorcet and individual rank learning methods." SIGIR '09.
+- **Vector Search**: Malkov, Y. A., & Yashunin, D. A. (2018). "Efficient and robust approximate nearest neighbor search using Hierarchical Navigable Small World graphs." TPAMI.
+- **Hybrid Search Best Practices**: Qdrant documentation on hybrid search patterns
+- **MCP Protocol**: Model Context Protocol specification for tool design
+
+## Implementation Notes
+
+### Weight Validation
+
+```python
+def validate_weights(
+    semantic_weight: float,
+    keyword_weight: float,
+    fuzzy_weight: float
+) -> None:
+    """Validate hybrid search weights."""
+    if semantic_weight < 0 or keyword_weight < 0 or fuzzy_weight < 0:
+        raise ValueError("Weights must be non-negative")
+
+    total = semantic_weight + keyword_weight + fuzzy_weight
+    if total > 1.0:
+        raise ValueError(f"Weights sum to {total:.2f}, must be ≤1.0")
+
+    if total == 0.0:
+        raise ValueError("At least one weight must be > 0")
+```
+
+### Backward Compatibility
+
+The default behavior (`algorithm="hybrid"` with balanced weights) provides better results than current pure semantic search, while maintaining the same tool name and signature structure. Existing clients will automatically benefit from hybrid search without code changes.
+
+### Performance Considerations
+
+- **Semantic search**: ~50-200ms (vector DB query)
+- **Keyword search**: ~10-50ms (in-memory token matching)
+- **Fuzzy search**: ~20-100ms (character comparison)
+- **Hybrid search**: ~100-300ms (parallel execution + fusion)
+
+Parallel execution of algorithms minimizes hybrid search latency.
+
+### Security Model
+
+All algorithms respect the same security boundaries:
+1. **User filtering**: Qdrant queries filter by `user_id`
+2. **Access verification**: Results verified via Nextcloud API
+3. **OAuth scope**: `semantic:read` required for all algorithms
+4. **Viz pane**: Shows only current user's documents
+
+## Success Metrics
+
+1. **Adoption**: % of MCP clients using algorithm parameter
+2. **Performance**: Search latency percentiles (p50, p95, p99)
+3. **Quality**: User satisfaction with result relevance
+4. **Viz pane usage**: % of users accessing testing interface
+5. **Weight distribution**: Most common weight configurations
+
+## Future Enhancements
+
+1. **Additional algorithms**: BM25, TF-IDF, neural reranking
+2. **Auto-tuning**: Learn optimal weights per user
+3. **Query analysis**: Automatic algorithm selection based on query
+4. **Cross-app search**: Extend beyond notes to calendar, files, etc.
+5. **Feedback loop**: Use click-through rate to improve weights

docs/ADR-013-rag-evaluation.md

@@ -0,0 +1,254 @@
+## ADR-013: RAG Evaluation Testing Framework
+
+**Status:** Proposed
+
+**Date:** 2025-11-15
+
+### Context
+
+The `nc_semantic_search_answer` tool implements a Retrieval-Augmented Generation (RAG) system where:
+1. **Retrieval**: Vector sync pipeline indexes Nextcloud documents (notes, calendar, contacts, etc.) into a vector database
+2. **Generation**: MCP client's LLM synthesizes answers from retrieved documents via MCP sampling (ADR-008)
+
+We need a testing framework to evaluate RAG system performance and identify whether failures occur in retrieval (wrong documents found) or generation (poor answer quality). This framework must use industry-standard evaluation methodologies while remaining practical to implement and maintain.
+
+To establish a baseline, we will use the **BeIR/nfcorpus** dataset (medical/biomedical corpus) with ~5,000 documents and established query/answer pairs.
+
+Homepage: https://www.cl.uni-heidelberg.de/statnlpgroup/nfcorpus/
+Download: https://public.ukp.informatik.tu-darmstadt.de/thakur/BEIR/datasets/nfcorpus.zip
+
+### Decision
+
+We will implement a **two-part evaluation framework** that independently tests retrieval and generation quality using pytest fixtures.
+
+#### In Scope
+
+**1. Retrieval Evaluation**
+Tests the vector sync/embedding pipeline's ability to find relevant documents.
+
+- **Metric: Context Recall** (Did we retrieve documents containing the answer?)
+  - **Evaluation method**: Heuristic - Check if ground-truth document IDs appear in top-k retrieval results
+  - **Test**: Query → Semantic search → Assert expected doc IDs present
+
+**2. Generation Evaluation**
+Tests the MCP client LLM's ability to synthesize correct answers from retrieved context.
+
+- **Metric: Answer Correctness** (Is the generated answer factually correct?)
+  - **Evaluation method**: LLM-as-judge - Compare RAG answer against ground-truth answer
+  - **Test**: Query → `nc_semantic_search_answer` → LLM evaluates answer vs. ground truth (binary true/false)
+
+#### Out of Scope (Initial Implementation)
+
+- **Context Relevance/Precision**: Measuring irrelevant documents in retrieval results
+- **Faithfulness/Groundedness**: Detecting hallucinations not supported by retrieved context
+- **Answer Relevance**: Whether answer addresses the specific question asked
+- **Out-of-Scope Handling**: Testing "I don't know" responses when answer isn't in context
+- **Continuous benchmarking**: Automated tracking of metric trends over time
+- **Custom domain datasets**: Production-specific test data (medical corpus used initially)
+
+These remain valuable for future iterations but add complexity beyond our initial goals.
+
+#### Implementation
+
+**Test Structure**
+
+Location: `tests/rag_evaluation/`
+- `test_retrieval_quality.py` - Retrieval evaluation tests
+- `test_generation_quality.py` - Generation evaluation tests
+- `conftest.py` - Fixtures for test data, MCP clients, and evaluation LLMs
+
+**Required Pytest Fixtures**
+
+1. **`nfcorpus_test_data`** (session-scoped)
+   - Downloads/caches BeIR nfcorpus dataset at runtime
+   - Loads 5 pre-selected test queries with:
+     - Query text
+     - Pre-generated ground-truth answer (from `tests/rag_evaluation/fixtures/ground_truth.json`)
+     - Expected document IDs (from qrels with score=2)
+   - Uploads all corpus documents as notes in test Nextcloud instance
+   - Triggers vector sync to index documents
+   - Waits for indexing completion
+   - Returns test case data structure
+
+2. **`mcp_sampling_client`** (session-scoped)
+   - Creates MCP client that supports sampling
+   - Configurable LLM provider (ollama or anthropic) via environment:
+     - `RAG_EVAL_PROVIDER=ollama` (default) or `anthropic`
+     - `RAG_EVAL_OLLAMA_BASE_URL=http://localhost:11434`
+     - `RAG_EVAL_OLLAMA_MODEL=llama3.1:8b`
+     - `RAG_EVAL_ANTHROPIC_API_KEY=sk-...`
+     - `RAG_EVAL_ANTHROPIC_MODEL=claude-3-5-sonnet-20241022`
+   - Returns configured MCP client fixture
+
+3. **`evaluation_llm`** (session-scoped)
+   - Separate LLM instance for evaluation (independent from MCP client)
+   - Same provider configuration as `mcp_sampling_client`
+   - Returns callable: `async def evaluate(prompt: str) -> str`
+
+**Test Implementation Examples**
+
+```python
+# tests/rag_evaluation/test_retrieval_quality.py
+async def test_retrieval_recall(nc_client, nfcorpus_test_data):
+    """Test that semantic search retrieves documents containing the answer."""
+    for test_case in nfcorpus_test_data:
+        # Perform semantic search (retrieval only, no generation)
+        results = await nc_client.notes.semantic_search(
+            query=test_case.query,
+            limit=10
+        )
+
+        retrieved_doc_ids = {r.document_id for r in results}
+        expected_doc_ids = set(test_case.expected_document_ids)
+
+        # Context Recall: Are expected documents in top-k results?
+        recall = len(expected_doc_ids & retrieved_doc_ids) / len(expected_doc_ids)
+        assert recall >= 0.8, f"Recall {recall} below threshold for query: {test_case.query}"
+
+
+# tests/rag_evaluation/test_generation_quality.py
+async def test_answer_correctness(mcp_sampling_client, evaluation_llm, nfcorpus_test_data):
+    """Test that RAG system generates factually correct answers."""
+    for test_case in nfcorpus_test_data:
+        # Execute full RAG pipeline (retrieval + generation)
+        result = await mcp_sampling_client.call_tool(
+            "nc_semantic_search_answer",
+            arguments={"query": test_case.query, "limit": 5}
+        )
+
+        rag_answer = result["generated_answer"]
+
+        # LLM-as-judge evaluation
+        evaluation_prompt = f"""Compare these two answers and respond with only TRUE or FALSE.
+
+Question: {test_case.query}
+
+Generated Answer: {rag_answer}
+
+Ground Truth Answer: {test_case.ground_truth}
+
+Are these answers semantically equivalent (do they convey the same factual information)?
+Respond with only: TRUE or FALSE"""
+
+        evaluation_result = await evaluation_llm(evaluation_prompt)
+
+        assert evaluation_result.strip().upper() == "TRUE", \
+            f"Answer mismatch for query: {test_case.query}\nGot: {rag_answer}\nExpected: {test_case.ground_truth}"
+```
+
+**Dataset Integration**
+
+The BeIR nfcorpus dataset structure:
+- **corpus.jsonl**: 3,633 medical/biomedical documents (articles from PubMed)
+- **queries.jsonl**: 3,237 queries (questions)
+- **qrels/*.tsv**: Relevance judgments mapping query IDs to document IDs with scores (2=highly relevant, 1=somewhat relevant)
+
+**Important**: The dataset provides relevance judgments (which documents answer which queries) but does NOT include ground truth answers. We must generate synthetic ground truth offline.
+
+**Selected Test Queries** (5 diverse candidates):
+
+1. **PLAIN-2630**: "Alkylphenol Endocrine Disruptors and Allergies" (5 words, 21 highly relevant docs)
+2. **PLAIN-2660**: "How Long to Detox From Fish Before Pregnancy?" (8 words, 20 highly relevant docs)
+3. **PLAIN-2510**: "Coffee and Artery Function" (4 words, 16 highly relevant docs)
+4. **PLAIN-2430**: "Preventing Brain Loss with B Vitamins?" (6 words, 15 highly relevant docs)
+5. **PLAIN-2690**: "Chronic Headaches and Pork Tapeworms" (5 words, 14 highly relevant docs)
+
+**Ground Truth Generation** (offline, pre-test):
+
+Ground truth answers will be generated offline using a script that:
+1. Loads nfcorpus dataset
+2. For each selected query, extracts top 3-5 highly relevant documents
+3. Uses an LLM (ollama/anthropic) to synthesize a reference answer
+4. Stores ground truth in `tests/rag_evaluation/fixtures/ground_truth.json`
+
+```python
+# tools/generate_rag_ground_truth.py
+async def generate_ground_truth(query: str, relevant_docs: List[dict], llm: LLMProvider) -> str:
+    """Generate synthetic ground truth answer from highly relevant documents."""
+    context = "\n\n".join([
+        f"Document {i+1}:\nTitle: {doc['title']}\n{doc['text']}"
+        for i, doc in enumerate(relevant_docs[:5])
+    ])
+
+    prompt = f"""Based on the following documents, provide a comprehensive answer to this question:
+
+Question: {query}
+
+{context}
+
+Provide a factual, well-structured answer that synthesizes information from the documents.
+Focus on accuracy and completeness."""
+
+    return await llm.generate(prompt, max_tokens=500)
+```
+
+**Dataset Loading at Test Runtime** (in `nfcorpus_test_data` fixture):
+
+1. Download nfcorpus dataset (cached in pytest temp directory)
+2. Load corpus, queries, and qrels (relevance judgments)
+3. Load pre-generated ground truth from `tests/rag_evaluation/fixtures/ground_truth.json`
+4. Upload all corpus documents as Nextcloud notes
+5. Trigger vector sync to index documents
+6. Wait for indexing completion
+7. Return test cases with query, ground truth, and expected doc IDs
+
+**LLM Provider Abstraction**
+
+```python
+# tests/rag_evaluation/llm_providers.py
+class LLMProvider(Protocol):
+    async def generate(self, prompt: str, max_tokens: int = 100) -> str: ...
+
+class OllamaProvider:
+    def __init__(self, base_url: str, model: str):
+        self.base_url = base_url
+        self.model = model
+
+    async def generate(self, prompt: str, max_tokens: int = 100) -> str:
+        # Use httpx to call Ollama API
+        ...
+
+class AnthropicProvider:
+    def __init__(self, api_key: str, model: str):
+        self.client = anthropic.AsyncAnthropic(api_key=api_key)
+        self.model = model
+
+    async def generate(self, prompt: str, max_tokens: int = 100) -> str:
+        message = await self.client.messages.create(
+            model=self.model,
+            max_tokens=max_tokens,
+            messages=[{"role": "user", "content": prompt}]
+        )
+        return message.content[0].text
+```
+
+### Consequences
+
+**Positive:**
+
+* **Actionable debugging**: Separate retrieval/generation tests pinpoint failure location
+* **Industry-standard metrics**: Context Recall and Answer Correctness are recognized RAG evaluation metrics
+* **Simple initial implementation**: Binary LLM evaluation (true/false) is straightforward to implement and interpret
+* **Extensible framework**: Easy to add more metrics (faithfulness, relevance) later
+* **Standardized benchmark**: nfcorpus provides objective comparison against published RAG systems
+* **Hybrid evaluation**: Combines efficiency (heuristics for retrieval) with quality (LLM-as-judge for generation)
+* **Provider flexibility**: Supports both local (Ollama) and cloud (Anthropic) LLM evaluation
+
+**Negative:**
+
+* **Medical domain bias**: nfcorpus is medical/biomedical content, may not represent production use cases (personal notes, calendar events, etc.)
+* **Manual test execution**: Tests require external LLM access and are not integrated into CI pipeline
+* **Limited initial coverage**: Starting with only 5 queries provides limited statistical confidence
+* **Evaluation cost**: LLM-as-judge for generation evaluation incurs API costs (Anthropic) or requires local inference (Ollama)
+* **Single metric per component**: Initial scope tests only one metric per component, missing other important quality dimensions
+* **Synthetic ground truth**: Ground truth answers are LLM-generated, not human-validated, which may introduce evaluation bias
+* **Large corpus upload**: Uploading 3,633 documents at test runtime may be slow; caching strategy needed
+
+**Future Work:**
+
+* Expand to 50-100 queries for statistical significance
+* Add custom test dataset with production-representative documents (meeting notes, task lists, etc.)
+* Implement additional metrics (faithfulness, context relevance, answer relevance)
+* Create automated benchmarking dashboard to track metric trends
+* Test multi-hop reasoning (synthesis questions requiring multiple documents)
+* Evaluate out-of-scope handling ("I don't know" responses)

docs/ADR-014-bm25-search.md

@@ -0,0 +1,241 @@
+# ADR-014: Replace Custom Keyword Search with BM25 Hybrid Search via Qdrant
+
+**Date:** 2025-11-16
+
+**Status:** Implemented
+
+---
+
+### 1. Context
+
+Our RAG application currently employs two separate retrieval mechanisms:
+1.  **Dense (Semantic) Search:** Using vector embeddings stored in our Qdrant database to find semantically similar context.
+2.  **Keyword Search:** A custom-built fuzzy/character-based search to match-specific keywords, acronyms, and product codes that semantic search often misses.
+
+This dual-system approach has several drawbacks:
+* **Poor Relevance:** Our current keyword search is basic (e.g., `LIKE` queries or simple fuzzy matching). It is not as effective as modern full-text search algorithms like BM25.
+* **Clunky Fusion:** We lack a robust, principled method to combine the results from the two systems. This leads to disjointed logic in the application layer and suboptimal context being passed to the LLM.
+* **Architectural Complexity:** We must maintain two separate search pathways (one to Qdrant, one to the keyword search mechanism), increasing code complexity and maintenance overhead.
+
+Our vector database, **Qdrant**, natively supports **hybrid search** by combining dense vectors with BM25-based **sparse vectors** in a single collection.
+
+### 2. Decision
+
+We will **deprecate and remove** the existing custom keyword/fuzzy search functionality.
+
+We will **replace it by implementing native hybrid search within Qdrant**. This involves:
+1.  **Modifying the Qdrant Collection:** Updating our collection to support a named sparse vector index configured for BM25.
+2.  **Updating the Ingestion Pipeline:** For every document chunk, we will generate and upsert *both*:
+    * Its **dense vector** (from our existing embedding model).
+    * Its **sparse vector** (generated using a BM25-compatible model, e.g., `Qdrant/bm25` from `fastembed`).
+3.  **Refactoring Retrieval Logic:** All retrieval calls will be consolidated into a single Qdrant query using the `query_points` endpoint. This query will use the `prefetch` parameter to execute both dense and sparse searches, and Qdrant's built-in **Reciprocal Rank Fusion (RRF)** to automatically merge the results into a single, relevance-ranked list.
+4.  **Backfilling:** A one-time migration script will be created to generate and add sparse vectors for all existing documents in the Qdrant collection.
+
+---
+
+### 3. Considered Options
+
+#### Option 1: Native Qdrant Hybrid Search (Chosen)
+* Use Qdrant's built-in sparse vector and RRF capabilities.
+* **Pros:**
+    * **Consolidated Architecture:** Manages both dense and sparse indexes in one database.
+    * **No Data Sync Issues:** Updates are atomic. A single `upsert` updates both representations.
+    * **Built-in Fusion:** RRF is handled natively and efficiently by the database.
+    * **Superior Relevance:** Replaces our brittle custom search with the industry-standard BM25.
+* **Cons:**
+    * Requires a one-time data backfill which may be time-consuming.
+    * Adds a new step (sparse vector generation) to the ingestion pipeline.
+
+#### Option 2: External Full-Text Search (e.g., Elasticsearch)
+* Keep Qdrant for dense search and add a separate Elasticsearch/OpenSearch cluster for BM25.
+* **Pros:**
+    * Provides a very powerful, dedicated full-text search engine.
+* **Cons:**
+    * **High Complexity:** Introduces a new, stateful service to deploy, manage, and scale.
+    * **Data Sync Nightmare:** We would be responsible for ensuring that the document IDs and content in Qdrant and Elasticsearch are always perfectly synchronized. This is a major source of bugs.
+    * **Manual Fusion:** The application would have to query both systems and perform RRF manually.
+
+#### Option 3: Keep Current System
+* Make no changes.
+* **Pros:**
+    * No engineering effort required.
+* **Cons:**
+    * Fails to address the known relevance and architectural problems.
+    * Our RAG application's performance will remain suboptimal, especially for keyword-sensitive queries.
+
+---
+
+### 4. Rationale
+
+**Option 1 is the clear winner.** It directly solves our primary problem (poor keyword matching) by adopting the industry-standard BM25.
+
+Critically, it achieves this while **simplifying** our overall architecture, not complicating it. By leveraging features already present in our existing database (Qdrant), we avoid the massive operational and synchronization overhead of adding a second search system (Option 2).
+
+This decision consolidates our retrieval logic, eliminates the data consistency problem, and moves the complex fusion logic (RRF) from the application layer into the database, where it can be performed more efficiently.
+
+### 5. Consequences
+
+**New Work:**
+* **Ingestion:** The data ingestion pipeline must be updated to add the `fastembed` library (or similar), generate sparse vectors, and upsert them to the new named vector field in Qdrant.
+* **Retrieval:** The application's retrieval service must be refactored to use the `query_points` endpoint with `prefetch` and `fusion=models.Fusion.RRF`.
+* **Migration:** A one-time backfill script must be written and executed to add sparse vectors for all existing documents.
+* **Infrastructure:** The Qdrant collection schema must be updated (or re-created) to add the `sparse_vectors_config`.
+
+**Positive:**
+* **Improved Accuracy:** Retrieval will be significantly more accurate, handling both semantic and keyword queries robustly.
+* **Simplified Code:** The application's retrieval logic will be cleaner and simpler, with one endpoint instead of two.
+* **Reduced Maintenance:** We will remove the custom fuzzy-search code, which is brittle and difficult to maintain.
+
+**Negative:**
+* The data backfill process will require careful management to avoid downtime.
+* Ingestion time will slightly increase due to the extra step of sparse vector generation. This is considered a negligible trade-off for the gains in relevance.
+
+---
+
+### 6. Implementation Notes
+
+**Implementation completed on 2025-11-16**
+
+**Key Changes:**
+
+1. **Dependencies** (pyproject.toml:25):
+   - Added `fastembed>=0.4.2` for BM25 sparse vector embeddings
+   - Adjusted `pillow` version constraint to be compatible with fastembed
+
+2. **Qdrant Collection Schema** (nextcloud_mcp_server/vector/qdrant_client.py:113-128):
+   - Updated to named vectors: `{"dense": VectorParams(...), "sparse": SparseVectorParams(...)}`
+   - Added sparse vector configuration with BM25 index
+   - Maintains backward compatibility with existing collections (detects legacy schema)
+
+3. **BM25 Embedding Provider** (nextcloud_mcp_server/embedding/bm25_provider.py):
+   - Created `BM25SparseEmbeddingProvider` using FastEmbed's `Qdrant/bm25` model
+   - Implements `encode()` and `encode_batch()` methods
+   - Returns sparse vectors as `{indices: list[int], values: list[float]}` format
+
+4. **Document Indexing Pipeline** (nextcloud_mcp_server/vector/processor.py:229-255):
+   - Generates both dense (semantic) and sparse (BM25) embeddings for each document chunk
+   - Updates `PointStruct` to use named vectors: `vector={"dense": ..., "sparse": ...}`
+   - Maintains same chunking strategy (512 words, 50-word overlap)
+
+5. **BM25 Hybrid Search Algorithm** (nextcloud_mcp_server/search/bm25_hybrid.py):
+   - Implements `BM25HybridSearchAlgorithm` using Qdrant's native RRF fusion
+   - Uses `prefetch` parameter for parallel dense + sparse search
+   - Applies `fusion=models.Fusion.RRF` for automatic result merging
+   - Maintains same deduplication and filtering logic as semantic search
+
+6. **MCP Tool Updates** (nextcloud_mcp_server/server/semantic.py:39-68):
+   - Simplified `nc_semantic_search()` to use BM25 hybrid only
+   - Removed `algorithm`, `semantic_weight`, `keyword_weight`, `fuzzy_weight` parameters
+   - Updated default `score_threshold=0.0` for RRF scoring
+   - Returns `search_method="bm25_hybrid"` in responses
+
+7. **Legacy Algorithm Removal**:
+   - Deleted `nextcloud_mcp_server/search/keyword.py` (278 lines)
+   - Deleted `nextcloud_mcp_server/search/fuzzy.py` (220 lines)
+   - Deleted `nextcloud_mcp_server/search/hybrid.py` (238 lines - custom RRF)
+   - Updated `nextcloud_mcp_server/search/__init__.py` to export only BM25 hybrid
+
+**Migration Strategy:**
+- No migration required (vector sync feature is experimental)
+- New documents automatically indexed with both dense + sparse vectors
+- Collection re-creation on first startup with updated schema
+
+**Test Results:**
+- All unit tests passing (118 passed)
+- All integration tests passing (7 semantic search tests)
+- Code formatting verified with ruff
+
+**Benefits Realized:**
+- ✅ Consolidated architecture (single Qdrant database for both dense + sparse)
+- ✅ Native fusion algorithms (database-level, more efficient)
+- ✅ Industry-standard BM25 (replaces custom keyword search)
+- ✅ Simplified codebase (removed 736 lines of legacy code)
+- ✅ Better relevance (handles both semantic and keyword queries)
+- ✅ Configurable fusion methods (RRF and DBSF)
+
+---
+
+### 7. Fusion Algorithm Options
+
+**Update: 2025-11-16**
+
+The BM25 hybrid search now supports two fusion algorithms for combining dense (semantic) and sparse (BM25) search results:
+
+#### Reciprocal Rank Fusion (RRF)
+
+**Default fusion method.** RRF is a widely-used, well-established algorithm that combines rankings from multiple retrieval systems using the reciprocal rank formula:
+
+```
+RRF(doc) = Σ 1/(k + rank_i(doc))
+```
+
+where `k` is a constant (typically 60) and `rank_i(doc)` is the rank of the document in retrieval system `i`.
+
+**Characteristics:**
+- ✅ **General-purpose**: Works well across diverse query types and document collections
+- ✅ **Rank-based**: Focuses on relative rankings rather than absolute scores
+- ✅ **Established**: Well-tested, documented, and understood in IR literature
+- ✅ **Robust**: Less sensitive to score distribution differences between systems
+
+**When to use RRF:**
+- Default choice for most use cases
+- When you have mixed query types (semantic + keyword)
+- When retrieval systems have very different score ranges
+- When you want predictable, well-understood behavior
+
+#### Distribution-Based Score Fusion (DBSF)
+
+**Alternative fusion method.** DBSF normalizes scores from each retrieval system using distribution statistics before combining them:
+
+1. **Normalization**: For each query, calculates mean (μ) and standard deviation (σ) of scores
+2. **Outlier handling**: Uses μ ± 3σ as normalization bounds
+3. **Fusion**: Sums normalized scores across systems
+
+**Characteristics:**
+- ✅ **Score-aware**: Uses actual relevance scores, not just rankings
+- ✅ **Statistical**: Normalizes based on score distribution properties
+- ⚠️ **Experimental**: Newer algorithm, less battle-tested than RRF
+- ⚠️ **Sensitive**: May behave differently depending on score distributions
+
+**When to use DBSF:**
+- When retrieval systems have vastly different score ranges that RRF doesn't balance well
+- When you want to experiment with score-based (vs rank-based) fusion
+- When statistical normalization better matches your use case
+- For A/B testing against RRF to measure retrieval quality improvements
+
+#### Configuration
+
+Both fusion algorithms are exposed via the `fusion` parameter in MCP tools:
+
+```python
+# Use RRF (default)
+response = await nc_semantic_search(
+    query="async programming",
+    fusion="rrf"  # Can be omitted, RRF is default
+)
+
+# Use DBSF
+response = await nc_semantic_search(
+    query="async programming",
+    fusion="dbsf"
+)
+```
+
+The `nc_semantic_search_answer` tool also supports the `fusion` parameter and passes it through to the underlying search.
+
+#### Future: Configurable Weights
+
+**Current limitation**: Neither RRF nor DBSF currently support per-system weights (e.g., 0.8 for semantic, 0.2 for BM25). This is a Qdrant platform limitation tracked in [qdrant/qdrant#6067](https://github.com/qdrant/qdrant/issues/6067).
+
+When Qdrant adds weight support, the `fusion` parameter can be extended to accept weight configurations:
+
+```python
+# Hypothetical future API
+response = await nc_semantic_search(
+    query="async programming",
+    fusion="rrf",
+    fusion_weights={"dense": 0.7, "sparse": 0.3}  # Not yet implemented
+)
+```
+
+**Recommendation**: Start with RRF (default). If you encounter cases where keyword matches are under- or over-weighted, experiment with DBSF. Monitor [qdrant/qdrant#6067](https://github.com/qdrant/qdrant/issues/6067) for configurable weight support.

docs/ADR-015-unified-provider-architecture.md

@@ -0,0 +1,380 @@
+# ADR-015: Unified Provider Architecture for Embeddings and Text Generation
+
+**Status:** Accepted
+**Date:** 2025-01-16
+**Deciders:** Development Team
+**Related:** ADR-003 (Vector Database), ADR-008 (MCP Sampling), ADR-013 (RAG Evaluation)
+
+## Context
+
+Prior to this refactoring, the codebase had two separate provider systems:
+
+1. **Embedding Providers** (`nextcloud_mcp_server/embedding/`)
+   - Used `EmbeddingProvider` ABC with methods: `embed()`, `embed_batch()`, `get_dimension()`
+   - Had auto-detection via `EmbeddingService._detect_provider()`
+   - Used for semantic search and vector indexing (production)
+
+2. **LLM Providers** (`tests/rag_evaluation/llm_providers.py`)
+   - Used `LLMProvider` Protocol with method: `generate()`
+   - Had separate factory function `create_llm_provider()`
+   - Used only for RAG evaluation tests (not production)
+
+This fragmentation created several problems:
+
+### Problems with Dual Provider Systems
+
+1. **Code Duplication**
+   - Ollama configuration appeared in both `embedding/service.py` and `tests/rag_evaluation/llm_providers.py`
+   - Similar provider detection logic in multiple places
+   - Separate singleton patterns for each system
+
+2. **Limited Extensibility**
+   - Hard-coded provider detection in `EmbeddingService._detect_provider()`
+   - No support for providers that offer both capabilities (like Bedrock)
+   - Adding new providers required modifying multiple files
+
+3. **Inconsistent Patterns**
+   - BM25 provider didn't follow `EmbeddingProvider` ABC
+   - Different method names across providers (`embed` vs `encode`)
+   - ABC vs Protocol for type checking
+
+4. **Difficult Scaling**
+   - Adding Amazon Bedrock (our third provider) would exacerbate all issues
+   - No clear path for future providers (OpenAI, Cohere, etc.)
+
+### Amazon Bedrock Requirements
+
+Bedrock naturally supports **both** embeddings and text generation:
+- **Embeddings**: `amazon.titan-embed-text-v1/v2`, `cohere.embed-*`
+- **Text Generation**: `anthropic.claude-*`, `meta.llama3-*`, `amazon.titan-text-*`
+- **Unified API**: Single `invoke_model()` method via bedrock-runtime
+
+This made it the perfect opportunity to establish a unified provider architecture.
+
+## Decision
+
+We refactored the provider infrastructure to use a **unified Provider ABC** with optional capabilities:
+
+### 1. Unified Provider Interface
+
+**New Structure:**
+```
+nextcloud_mcp_server/providers/
+├── __init__.py
+├── base.py              # Provider ABC with optional capabilities
+├── registry.py          # Auto-detection and factory
+├── ollama.py            # Supports both embedding + generation
+├── anthropic.py         # Generation only
+├── bedrock.py           # Supports both embedding + generation
+└── simple.py            # Embedding only (testing fallback)
+```
+
+**Base Class (`providers/base.py`):**
+```python
+class Provider(ABC):
+    @property
+    @abstractmethod
+    def supports_embeddings(self) -> bool:
+        """Whether this provider supports embedding generation."""
+        pass
+
+    @property
+    @abstractmethod
+    def supports_generation(self) -> bool:
+        """Whether this provider supports text generation."""
+        pass
+
+    @abstractmethod
+    async def embed(self, text: str) -> list[float]:
+        """Generate embedding (raises NotImplementedError if not supported)."""
+        pass
+
+    @abstractmethod
+    async def embed_batch(self, texts: list[str]) -> list[list[float]]:
+        """Generate batch embeddings (raises NotImplementedError if not supported)."""
+        pass
+
+    @abstractmethod
+    def get_dimension(self) -> int:
+        """Get embedding dimension (raises NotImplementedError if not supported)."""
+        pass
+
+    @abstractmethod
+    async def generate(self, prompt: str, max_tokens: int = 500) -> str:
+        """Generate text (raises NotImplementedError if not supported)."""
+        pass
+
+    @abstractmethod
+    async def close(self) -> None:
+        """Close provider and release resources."""
+        pass
+```
+
+### 2. Provider Registry
+
+**Auto-Detection Priority** (`providers/registry.py`):
+```python
+class ProviderRegistry:
+    @staticmethod
+    def create_provider() -> Provider:
+        # 1. Bedrock (AWS_REGION or BEDROCK_*_MODEL)
+        # 2. Ollama (OLLAMA_BASE_URL)
+        # 3. Simple (fallback)
+```
+
+**Environment Variables:**
+
+**Bedrock:**
+- `AWS_REGION`: AWS region (e.g., "us-east-1")
+- `AWS_ACCESS_KEY_ID`: AWS access key (optional, uses credential chain)
+- `AWS_SECRET_ACCESS_KEY`: AWS secret key (optional)
+- `BEDROCK_EMBEDDING_MODEL`: Model ID for embeddings (e.g., "amazon.titan-embed-text-v2:0")
+- `BEDROCK_GENERATION_MODEL`: Model ID for text generation (e.g., "anthropic.claude-3-sonnet-20240229-v1:0")
+
+**Ollama:**
+- `OLLAMA_BASE_URL`: Ollama API base URL (e.g., "http://localhost:11434")
+- `OLLAMA_EMBEDDING_MODEL`: Model for embeddings (default: "nomic-embed-text")
+- `OLLAMA_GENERATION_MODEL`: Model for text generation (e.g., "llama3.2:1b")
+- `OLLAMA_VERIFY_SSL`: Verify SSL certificates (default: "true")
+
+**Simple (no configuration, fallback):**
+- `SIMPLE_EMBEDDING_DIMENSION`: Embedding dimension (default: 384)
+
+### 3. Backward Compatibility
+
+**Old Code Continues to Work:**
+```python
+# Old way (still works)
+from nextcloud_mcp_server.embedding import get_embedding_service
+
+service = get_embedding_service()  # Returns singleton Provider
+embeddings = await service.embed_batch(texts)
+```
+
+**New Way (recommended):**
+```python
+# New way (cleaner)
+from nextcloud_mcp_server.providers import get_provider
+
+provider = get_provider()  # Returns singleton Provider
+embeddings = await provider.embed_batch(texts)
+
+# Can also use generation if provider supports it
+if provider.supports_generation:
+    text = await provider.generate("prompt")
+```
+
+**Migration Path:**
+- `embedding/service.py` now wraps `providers.get_provider()` for compatibility
+- `tests/rag_evaluation/llm_providers.py` now uses unified providers
+- Old imports still work, marked as deprecated in docstrings
+
+### 4. Amazon Bedrock Implementation
+
+**Features:**
+- Supports both embeddings and text generation
+- Model-specific request/response handling for:
+  - Titan Embed (amazon.titan-embed-text-*)
+  - Cohere Embed (cohere.embed-*)
+  - Claude (anthropic.claude-*)
+  - Llama (meta.llama3-*)
+  - Titan Text (amazon.titan-text-*)
+  - Mistral (mistral.*)
+- Uses boto3 bedrock-runtime client
+- Graceful degradation if boto3 not installed
+- Async implementation matching existing patterns
+
+**Model-Specific Handling:**
+```python
+# Bedrock embedding request (Titan)
+{"inputText": text}
+
+# Bedrock generation request (Claude)
+{
+    "anthropic_version": "bedrock-2023-05-31",
+    "max_tokens": max_tokens,
+    "temperature": 0.7,
+    "messages": [{"role": "user", "content": prompt}]
+}
+```
+
+## Consequences
+
+### Positive
+
+1. **Sustainable Provider Additions**
+   - New providers only need to implement `Provider` ABC
+   - Auto-detection via environment variables
+   - No modifications to existing code required
+
+2. **Code Consolidation**
+   - Single provider interface instead of two
+   - Unified configuration pattern
+   - Eliminated duplication
+
+3. **Better Extensibility**
+   - Providers can support one or both capabilities
+   - Clear capability detection via properties
+   - Registry pattern simplifies auto-detection
+
+4. **Improved Testing**
+   - RAG evaluation can use any provider (Ollama, Anthropic, Bedrock)
+   - Comprehensive unit tests for all providers
+   - Mocked boto3 tests for Bedrock
+
+5. **Production-Ready Bedrock Support**
+   - Full embedding and generation support
+   - Multiple model families supported
+   - AWS credential chain integration
+
+### Neutral
+
+1. **Optional Boto3 Dependency**
+   - boto3 is dev dependency only (not required for core functionality)
+   - Bedrock provider gracefully fails if boto3 not installed
+   - Users who want Bedrock must `pip install boto3`
+
+2. **Capability Properties**
+   - All providers must implement capability properties
+   - Methods raise `NotImplementedError` if capability not supported
+   - Clear error messages guide users to alternatives
+
+### Negative
+
+1. **Migration Effort**
+   - Existing code must be migrated to new imports (optional, backward compatible)
+   - Documentation needs updating
+   - Users must learn new environment variables
+
+2. **Increased Complexity**
+   - Provider base class has more methods (embedding + generation)
+   - More environment variables to configure
+   - Capability detection adds runtime checks
+
+## Implementation
+
+### Files Created
+
+**New Provider Infrastructure:**
+- `nextcloud_mcp_server/providers/__init__.py`
+- `nextcloud_mcp_server/providers/base.py`
+- `nextcloud_mcp_server/providers/registry.py`
+- `nextcloud_mcp_server/providers/ollama.py`
+- `nextcloud_mcp_server/providers/anthropic.py`
+- `nextcloud_mcp_server/providers/bedrock.py`
+- `nextcloud_mcp_server/providers/simple.py`
+
+**Tests:**
+- `tests/unit/providers/__init__.py`
+- `tests/unit/providers/test_bedrock.py` (9 unit tests)
+
+**Documentation:**
+- `docs/ADR-015-unified-provider-architecture.md` (this file)
+
+### Files Modified
+
+**Backward Compatibility:**
+- `nextcloud_mcp_server/embedding/service.py` - Now wraps `get_provider()`
+- `tests/rag_evaluation/llm_providers.py` - Uses unified providers
+
+**Dependencies:**
+- `pyproject.toml` - Added `boto3>=1.35.0` to dev dependencies
+
+### Testing Results
+
+**Unit Tests:** 127 passed (including 9 new Bedrock tests)
+**Type Checking:** All checks passed (ty)
+**Linting:** All checks passed (ruff)
+**Backward Compatibility:** Verified - existing embedding tests work
+
+## Alternatives Considered
+
+### Alternative 1: Keep Separate Provider Systems
+
+**Pros:**
+- No refactoring needed
+- Simpler short-term
+
+**Cons:**
+- Bedrock would need to be implemented twice
+- Continued code duplication
+- No long-term scalability
+
+**Decision:** Rejected - technical debt would continue to grow
+
+### Alternative 2: Separate Embedding and Generation Providers
+
+Use composition instead of unified interface:
+```python
+class CombinedProvider:
+    def __init__(self, embedding: EmbeddingProvider, generation: LLMProvider):
+        self.embedding = embedding
+        self.generation = generation
+```
+
+**Pros:**
+- Clearer separation of concerns
+- Simpler individual providers
+
+**Cons:**
+- Bedrock and Ollama naturally do both - artificial separation
+- More complex configuration (two providers to configure)
+- More boilerplate code
+
+**Decision:** Rejected - unified interface better matches provider capabilities
+
+### Alternative 3: Plugin System
+
+Dynamic provider registration via entry points:
+```python
+# setup.py
+entry_points={
+    'nextcloud_mcp.providers': [
+        'ollama = nextcloud_mcp_server.providers.ollama:OllamaProvider',
+        'bedrock = nextcloud_mcp_server.providers.bedrock:BedrockProvider',
+    ]
+}
+```
+
+**Pros:**
+- Most extensible
+- Third-party providers possible
+
+**Cons:**
+- Over-engineered for current needs
+- Added complexity
+- No immediate benefit
+
+**Decision:** Deferred - can add later if needed
+
+## Future Work
+
+1. **Additional Providers**
+   - OpenAI (embeddings + generation)
+   - Cohere (embeddings + generation)
+   - Google Vertex AI
+   - Azure OpenAI
+
+2. **Provider Features**
+   - Streaming generation support
+   - Batch API optimization (when available)
+   - Model-specific optimizations
+   - Cost tracking and metrics
+
+3. **Configuration Improvements**
+   - Provider profiles (development, production)
+   - Model aliasing (e.g., "small", "large")
+   - Fallback provider chains
+
+4. **Testing**
+   - Integration tests with real Bedrock endpoints
+   - Performance benchmarking across providers
+   - Cost comparison analysis
+
+## References
+
+- [boto3 Bedrock Runtime Documentation](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/bedrock-runtime.html)
+- [Amazon Bedrock User Guide](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html)
+- ADR-003: Vector Database and Semantic Search
+- ADR-008: MCP Sampling for Semantic Search
+- ADR-013: RAG Evaluation Framework

docs/ADR-016-smithery-stateless-deployment.md

@@ -0,0 +1,492 @@
+# ADR-016: Smithery Stateless Deployment for Multi-User Public Nextcloud Instances
+
+**Status:** Proposed
+**Date:** 2025-01-22
+**Deciders:** Development Team
+**Related:** ADR-004 (OAuth), ADR-007 (Background Vector Sync), ADR-015 (Unified Provider)
+
+## Context
+
+[Smithery](https://smithery.ai) is a hosting platform and marketplace for MCP servers that provides:
+
+- **Discovery**: Marketplace listing for MCP servers
+- **Hosting**: Containerized deployment with auto-scaling
+- **Authentication UI**: OAuth flow presentation for users
+- **Session Configuration**: Per-user settings passed via URL parameters
+- **Observability**: Usage logs and monitoring
+
+### Current Architecture Limitations
+
+The current nextcloud-mcp-server architecture assumes a **self-hosted deployment** with:
+
+1. **Persistent Infrastructure**
+   - Qdrant vector database for semantic search
+   - Background sync worker for content indexing
+   - Refresh token storage for offline access
+
+2. **Single-Tenant Configuration**
+   - Environment variables configure one Nextcloud instance
+   - `NEXTCLOUD_HOST`, `NEXTCLOUD_USERNAME`, `NEXTCLOUD_PASSWORD`
+   - Or OAuth with a single IdP
+
+3. **Stateful Operations**
+   - Vector sync maintains index state across requests
+   - Token storage persists between sessions
+
+### Smithery Hosting Constraints
+
+Smithery-hosted containers are **stateless by design**:
+
+- No persistent storage between requests
+- No background workers or cron jobs
+- No databases (Qdrant, Redis, etc.)
+- Containers may be recycled at any time
+- Configuration passed per-session via URL parameters
+
+### Opportunity
+
+Many users have **publicly accessible Nextcloud instances** and want to:
+
+1. Try the MCP server without self-hosting infrastructure
+2. Connect multiple users to different Nextcloud instances
+3. Use basic Nextcloud tools without semantic search
+4. Benefit from Smithery's discovery and OAuth UI
+
+## Decision
+
+Implement a **stateless deployment mode** for Smithery that:
+
+1. **Disables stateful features** (vector sync, semantic search)
+2. **Creates clients per-session** from Smithery configuration
+3. **Supports multiple Nextcloud instances** via session config
+4. **Provides a useful subset of tools** that work without infrastructure
+
+### Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                    Smithery-Hosted Stateless Mode                        │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│  MCP Client                    Smithery                                  │
+│  (Cursor, Claude)              Infrastructure                            │
+│        │                            │                                    │
+│        │ 1. Connect                 │                                    │
+│        ├───────────────────────────►│                                    │
+│        │                            │                                    │
+│        │ 2. Config UI               │                                    │
+│        │◄───────────────────────────┤  User enters:                      │
+│        │    (Smithery presents)     │  - nextcloud_url                   │
+│        │                            │  - auth_mode (basic/oauth)         │
+│        │                            │  - credentials                     │
+│        │ 3. Tool call               │                                    │
+│        ├───────────────────────────►│                                    │
+│        │    + session config        │                                    │
+│        │                            │                                    │
+│        │                    ┌───────┴───────┐                            │
+│        │                    │  MCP Server   │                            │
+│        │                    │  Container    │                            │
+│        │                    │               │                            │
+│        │                    │ 4. Create     │                            │
+│        │                    │    client     │                            │
+│        │                    │    from       │                            │
+│        │                    │    config     │                            │
+│        │                    │      │        │                            │
+│        │                    │      ▼        │                            │
+│        │                    │ 5. Call       │                            │
+│        │                    │    Nextcloud  │───────► User's Nextcloud   │
+│        │                    │    API        │         Instance           │
+│        │                    │      │        │                            │
+│        │                    │      ▼        │                            │
+│        │ 6. Response        │ Return result │                            │
+│        │◄───────────────────┤               │                            │
+│        │                    └───────────────┘                            │
+│                                                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### Session Configuration Schema
+
+```python
+from pydantic import BaseModel, Field
+
+class SmitheryConfigSchema(BaseModel):
+    """Configuration schema for Smithery session."""
+
+    # Required: Nextcloud instance
+    nextcloud_url: str = Field(
+        ...,
+        description="Your Nextcloud instance URL (e.g., https://cloud.example.com)"
+    )
+
+    # Authentication mode
+    auth_mode: str = Field(
+        "app_password",
+        description="Authentication method: 'app_password' or 'oauth'"
+    )
+
+    # App Password authentication (recommended for Smithery)
+    username: str | None = Field(
+        None,
+        description="Nextcloud username (required for app_password auth)"
+    )
+    app_password: str | None = Field(
+        None,
+        description="Nextcloud app password (Settings → Security → App passwords)"
+    )
+
+    # OAuth authentication (advanced)
+    # When auth_mode='oauth', Smithery handles the OAuth flow
+    # and passes the access token automatically
+```
+
+### Feature Matrix
+
+| Feature | Self-Hosted | Smithery Stateless |
+|---------|-------------|-------------------|
+| **Notes** | | |
+| List/Search notes | ✓ | ✓ |
+| Get/Create/Update notes | ✓ | ✓ |
+| Semantic search | ✓ | ✗ |
+| **Calendar** | | |
+| List calendars | ✓ | ✓ |
+| Get/Create events | ✓ | ✓ |
+| **Contacts** | | |
+| List address books | ✓ | ✓ |
+| Search/Get contacts | ✓ | ✓ |
+| **Files (WebDAV)** | | |
+| List/Download files | ✓ | ✓ |
+| Upload files | ✓ | ✓ |
+| Search files | ✓ | ✓ (keyword only) |
+| **Deck** | | |
+| List boards/cards | ✓ | ✓ |
+| Create/Update cards | ✓ | ✓ |
+| **Tables** | | |
+| List/Query tables | ✓ | ✓ |
+| Create/Update rows | ✓ | ✓ |
+| **Cookbook** | | |
+| List/Get recipes | ✓ | ✓ |
+| **Semantic Search** | | |
+| Vector search | ✓ | ✗ |
+| RAG answers | ✓ | ✗ |
+| **Background Sync** | | |
+| Auto-indexing | ✓ | ✗ |
+| Webhook sync | ✓ | ✗ |
+| **Admin UI (`/app`)** | | |
+| Vector sync status | ✓ | ✗ |
+| Vector visualization | ✓ | ✗ |
+| Webhook management | ✓ | ✗ |
+| Session management | ✓ | ✗ |
+
+### Implementation
+
+#### 1. Deployment Mode Detection
+
+```python
+# nextcloud_mcp_server/config.py
+
+class DeploymentMode(Enum):
+    SELF_HOSTED = "self_hosted"      # Full features, env-based config
+    SMITHERY_STATELESS = "smithery"  # Stateless, session-based config
+
+def get_deployment_mode() -> DeploymentMode:
+    """Detect deployment mode from environment."""
+    if os.getenv("SMITHERY_DEPLOYMENT") == "true":
+        return DeploymentMode.SMITHERY_STATELESS
+    return DeploymentMode.SELF_HOSTED
+```
+
+#### 2. Session-Based Client Factory
+
+```python
+# nextcloud_mcp_server/context.py
+
+async def get_client(ctx: Context) -> NextcloudClient:
+    """Get NextcloudClient - from session config or environment."""
+
+    mode = get_deployment_mode()
+
+    if mode == DeploymentMode.SMITHERY_STATELESS:
+        # Create client from Smithery session config
+        config = ctx.session_config
+        if not config:
+            raise McpError("Session configuration required")
+
+        return NextcloudClient(
+            base_url=config.nextcloud_url,
+            username=config.username,
+            password=config.app_password,
+        )
+    else:
+        # Existing behavior: from environment or OAuth context
+        return await _get_client_from_context(ctx)
+```
+
+#### 3. Conditional Tool Registration
+
+```python
+# nextcloud_mcp_server/app.py
+
+def create_mcp_server(mode: DeploymentMode) -> FastMCP:
+    """Create MCP server with mode-appropriate tools."""
+
+    mcp = FastMCP("Nextcloud MCP")
+
+    # Always register core tools
+    configure_notes_tools(mcp)
+    configure_calendar_tools(mcp)
+    configure_contacts_tools(mcp)
+    configure_webdav_tools(mcp)
+    configure_deck_tools(mcp)
+    configure_tables_tools(mcp)
+    configure_cookbook_tools(mcp)
+
+    # Only register stateful tools in self-hosted mode
+    if mode == DeploymentMode.SELF_HOSTED:
+        configure_semantic_tools(mcp)  # Requires Qdrant
+        register_oauth_tools(mcp)       # Requires token storage
+
+    return mcp
+```
+
+#### 4. Exclude Admin UI Routes
+
+The `/app` admin UI should **not be installed** in Smithery mode because:
+
+- **Vector sync status** - No vector sync in stateless mode
+- **Vector visualization** - No Qdrant to visualize
+- **Webhook management** - No webhook sync without background workers
+- **Session management** - No persistent sessions to manage
+
+```python
+# nextcloud_mcp_server/app.py
+
+def create_app(mode: DeploymentMode) -> Starlette:
+    """Create Starlette app with mode-appropriate routes."""
+
+    routes = [
+        Route("/health/live", health_live, methods=["GET"]),
+        Route("/health/ready", health_ready, methods=["GET"]),
+    ]
+
+    # Only mount admin UI in self-hosted mode
+    if mode == DeploymentMode.SELF_HOSTED:
+        browser_app = create_browser_app()
+        routes.append(
+            Route("/app", lambda r: RedirectResponse("/app/", status_code=307))
+        )
+        routes.append(Mount("/app", app=browser_app))
+        logger.info("Admin UI mounted at /app")
+    else:
+        logger.info("Admin UI disabled in Smithery stateless mode")
+
+    # Mount FastMCP at root
+    mcp_app = create_mcp_server(mode).streamable_http_app()
+    routes.append(Mount("/", app=mcp_app))
+
+    return Starlette(routes=routes, lifespan=starlette_lifespan)
+```
+
+**Endpoints by Mode:**
+
+| Endpoint | Self-Hosted | Smithery |
+|----------|-------------|----------|
+| `/mcp` | ✓ | ✓ |
+| `/health/live` | ✓ | ✓ |
+| `/health/ready` | ✓ | ✓ |
+| `/.well-known/mcp-config` | ✓ | ✓ |
+| `/app` | ✓ | ✗ |
+| `/app/vector-sync/status` | ✓ | ✗ |
+| `/app/vector-viz` | ✓ | ✗ |
+| `/app/webhooks` | ✓ | ✗ |
+
+#### 5. Smithery Integration Files
+
+**smithery.yaml:**
+```yaml
+runtime: "container"
+build:
+  dockerfile: "Dockerfile.smithery"
+  dockerBuildPath: "."
+startCommand:
+  type: "http"
+  configSchema:
+    type: "object"
+    required: ["nextcloud_url", "username", "app_password"]
+    properties:
+      nextcloud_url:
+        type: "string"
+        title: "Nextcloud URL"
+        description: "Your Nextcloud instance URL (e.g., https://cloud.example.com)"
+      username:
+        type: "string"
+        title: "Username"
+        description: "Your Nextcloud username"
+      app_password:
+        type: "string"
+        title: "App Password"
+        description: "Generate at Settings → Security → App passwords"
+  exampleConfig:
+    nextcloud_url: "https://cloud.example.com"
+    username: "alice"
+    app_password: "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
+```
+
+**Dockerfile.smithery:**
+```dockerfile
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install uv
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv
+
+# Copy project files
+COPY pyproject.toml uv.lock ./
+COPY nextcloud_mcp_server ./nextcloud_mcp_server
+
+# Install dependencies (without vector/semantic extras)
+RUN uv sync --frozen --no-dev
+
+# Set Smithery mode
+ENV SMITHERY_DEPLOYMENT=true
+ENV VECTOR_SYNC_ENABLED=false
+
+# Smithery sets PORT=8081
+EXPOSE 8081
+
+CMD ["uv", "run", "python", "-m", "nextcloud_mcp_server.smithery_main"]
+```
+
+**nextcloud_mcp_server/smithery_main.py:**
+```python
+"""Smithery-specific entrypoint for stateless deployment."""
+
+import os
+import uvicorn
+from starlette.middleware.cors import CORSMiddleware
+
+from nextcloud_mcp_server.app import create_mcp_server
+from nextcloud_mcp_server.config import DeploymentMode
+
+def main():
+    # Force stateless mode
+    os.environ["SMITHERY_DEPLOYMENT"] = "true"
+    os.environ["VECTOR_SYNC_ENABLED"] = "false"
+
+    mcp = create_mcp_server(DeploymentMode.SMITHERY_STATELESS)
+    app = mcp.streamable_http_app()
+
+    # Add CORS for browser-based clients
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=True,
+        allow_methods=["GET", "POST", "OPTIONS"],
+        allow_headers=["*"],
+        expose_headers=["mcp-session-id", "mcp-protocol-version"],
+    )
+
+    # Smithery sets PORT environment variable
+    port = int(os.environ.get("PORT", 8081))
+    uvicorn.run(app, host="0.0.0.0", port=port)
+
+if __name__ == "__main__":
+    main()
+```
+
+### Security Considerations
+
+1. **App Passwords over User Passwords**
+   - Smithery config encourages app passwords (revocable, scoped)
+   - Documentation guides users to create dedicated app passwords
+   - App passwords can be revoked without changing main password
+
+2. **HTTPS Required**
+   - `nextcloud_url` must be HTTPS for production use
+   - Validation rejects HTTP URLs in Smithery mode
+
+3. **No Credential Storage**
+   - Credentials exist only for request duration
+   - No server-side persistence of user credentials
+   - Smithery handles secure config transmission
+
+4. **Scope Limitation**
+   - Stateless mode cannot access offline_access
+   - No background operations on user's behalf
+   - Clear user expectation: tools work during session only
+
+### Migration Path
+
+Users can start with Smithery stateless mode and migrate to self-hosted:
+
+1. **Try on Smithery** → Basic tools, no setup
+2. **Self-host for semantic search** → Add Qdrant, enable vector sync
+3. **Full deployment** → Background sync, webhooks, multi-user OAuth
+
+## Consequences
+
+### Positive
+
+1. **Lower barrier to entry** - Users can try without infrastructure
+2. **Multi-user support** - Each session connects to different Nextcloud
+3. **Smithery ecosystem** - Discovery, observability, OAuth UI
+4. **Clear feature tiers** - Stateless (simple) vs self-hosted (full)
+
+### Negative
+
+1. **No semantic search** - Key differentiator unavailable on Smithery
+2. **Per-request auth** - Credentials sent with each request
+3. **No offline access** - Cannot perform background operations
+4. **Maintenance burden** - Two deployment modes to support
+
+### Neutral
+
+1. **Feature subset** - May encourage users to self-host for full features
+2. **Documentation needs** - Clear guidance on mode differences required
+
+## Alternatives Considered
+
+### 1. External MCP Only
+
+**Approach:** Only support self-hosted external MCP registration on Smithery.
+
+**Rejected because:**
+- Higher barrier to entry for new users
+- Misses opportunity for Smithery marketplace visibility
+- Users want to try before committing to infrastructure
+
+### 2. Embedded Vector DB (SQLite-vec)
+
+**Approach:** Use SQLite with vector extensions for per-request indexing.
+
+**Rejected because:**
+- No persistence between requests anyway
+- Indexing latency too high for synchronous requests
+- Complexity without benefit in stateless context
+
+### 3. External Vector DB Service
+
+**Approach:** Connect to Pinecone/Weaviate Cloud from Smithery container.
+
+**Rejected because:**
+- Adds external dependency and cost
+- Per-user collections require complex multi-tenancy
+- Sync still impossible without background workers
+
+### 4. Hybrid: Smithery + User's Qdrant
+
+**Approach:** User provides their own Qdrant URL in session config.
+
+**Considered for future:**
+- Could enable semantic search for advanced users
+- Adds complexity to session config
+- Sync still requires external trigger (manual or webhook)
+
+## References
+
+- [Smithery Documentation](https://smithery.ai/docs)
+- [Smithery Session Configuration](https://smithery.ai/docs/build/session-config)
+- [Smithery External MCPs](https://smithery.ai/docs/build/external)
+- [MCP Streamable HTTP Transport](https://modelcontextprotocol.io/docs/concepts/transports)
+- [Nextcloud App Passwords](https://docs.nextcloud.com/server/latest/user_manual/en/session_management.html#app-passwords)

docs/ADR-017-mcp-tool-annotations.md

@@ -0,0 +1,506 @@
+# ADR-017: Add MCP Tool Annotations for Enhanced Client UX
+
+## Status
+
+Implemented
+
+## Context
+
+The MCP Python SDK supports tool annotations that provide behavioral hints and improved UX to MCP clients. Currently, our 101 tools across 10 modules lack these annotations, resulting in:
+
+- Snake_case function names displayed to users (e.g., "nc_notes_create_note" instead of "Create Note")
+- No behavioral hints for clients about read-only, destructive, or idempotent operations
+- Missing parameter descriptions for better auto-completion and inline help
+- Clients cannot optimize caching, warn before destructive operations, or retry safely
+
+### Available MCP Annotations
+
+The MCP SDK provides three types of annotations:
+
+#### 1. Tool Decorator Parameters
+```python
+@mcp.tool(
+    title="Human-Readable Name",
+    description="Tool description",  # Can also come from docstring
+    annotations=ToolAnnotations(...),
+    icons=[Icon(...)]  # Optional visual icons
+)
+```
+
+#### 2. ToolAnnotations Behavioral Hints
+```python
+from mcp.types import ToolAnnotations
+
+ToolAnnotations(
+    title="Alternative Title",  # Decorator title takes precedence
+    readOnlyHint=True,         # Tool doesn't modify data
+    destructiveHint=True,       # Tool may delete/overwrite data
+    idempotentHint=True,        # Repeated calls with same args are safe
+    openWorldHint=True          # Interacts with external entities
+)
+```
+
+#### 3. Parameter Descriptions
+```python
+from pydantic import Field
+
+async def tool(
+    param: str = Field(description="What this parameter does"),
+    ctx: Context
+):
+```
+
+### Idempotency Analysis
+
+**Important**: Idempotency means calling with **the same inputs** produces the same result.
+
+**NOT Idempotent** (different inputs each call):
+- **Updates with etag**: `update_note(id=1, title="X", etag="abc")` → etag changes to "def"
+  - Second call: `update_note(id=1, title="X", etag="abc")` → fails (etag mismatch)
+  - Different input (stale etag) → different result (error)
+- **Creates**: `create_note(title="X")` → creates note 1
+  - Second call → creates note 2 (different result)
+- **Append operations**: `append_content(id=1, text="X")` → adds X once
+  - Second call → adds X again (different result)
+
+**Idempotent**:
+- **Deletes**: `delete_note(id=1)` → note deleted
+  - Second call → 404 or success (same end state: note doesn't exist)
+  - Note: May return different status code, but end state is identical
+- **Full resource PUT without version control**: `write_file(path="/test.txt", content="Hello")` → file has "Hello"
+  - Second call → file still has "Hello" (same end state)
+  - Example: `nc_webdav_write_file` uses HTTP PUT without etags/version control
+- **Set operations**: `set_property(id=1, value="X")` → property = X
+  - Second call → property still = X (same result)
+  - Note: Nextcloud updates with etags use version control, so not idempotent
+
+**Read-Only** (always idempotent, never destructive):
+- All list, search, get operations
+
+## Decision
+
+Add annotations to all 101 tools in three phases:
+
+### Phase 1: Titles (Quick Win)
+Add human-readable titles to all tools:
+
+```python
+@mcp.tool(title="Create Note")
+async def nc_notes_create_note(...):
+```
+
+**Effort**: 2-3 hours
+**Impact**: Immediate UX improvement
+
+### Phase 2: ToolAnnotations (Behavioral Hints)
+Add annotations based on corrected categorization:
+
+```python
+# Read-only tools
+@mcp.tool(
+    title="Search Notes",
+    annotations=ToolAnnotations(
+        readOnlyHint=True,
+        openWorldHint=True  # Nextcloud is external to MCP server
+    )
+)
+
+# Delete tools (idempotent: same end state)
+@mcp.tool(
+    title="Delete Note",
+    annotations=ToolAnnotations(
+        destructiveHint=True,
+        idempotentHint=True,  # Deleting deleted item = same end state
+        openWorldHint=True
+    )
+)
+
+# Create tools (not idempotent: creates multiple items)
+@mcp.tool(
+    title="Create Note",
+    annotations=ToolAnnotations(
+        idempotentHint=False,
+        openWorldHint=True
+    )
+)
+
+# Update tools with etag (not idempotent: etag changes)
+@mcp.tool(
+    title="Update Note",
+    annotations=ToolAnnotations(
+        idempotentHint=False,  # Etag required = different inputs each time
+        openWorldHint=True
+    )
+)
+
+# Append operations (not idempotent: adds content each time)
+@mcp.tool(
+    title="Append to Note",
+    annotations=ToolAnnotations(
+        idempotentHint=False,
+        openWorldHint=True
+    )
+)
+```
+
+**Effort**: 4-6 hours
+**Impact**: Better client behavior (caching, warnings, retry logic)
+
+### Phase 3: Parameter Descriptions
+Add Field() descriptions to parameters:
+
+```python
+from pydantic import Field
+
+@mcp.tool(title="Create Note", annotations=ToolAnnotations(idempotentHint=False))
+async def nc_notes_create_note(
+    title: str = Field(description="The title of the note"),
+    content: str = Field(description="Markdown content of the note"),
+    category: str = Field(description="Category or folder name for organizing"),
+    ctx: Context
+) -> CreateNoteResponse:
+```
+
+**Effort**: 6-8 hours
+**Impact**: Better auto-completion and inline help
+
+## Tool Categorization
+
+### Read-Only Tools (~40 tools)
+**Pattern**: List, search, get operations
+**Annotations**: `readOnlyHint=True`, `openWorldHint=True`
+
+Examples:
+- `nc_notes_search_notes` → "Search Notes"
+- `nc_webdav_list_directory` → "List Files and Directories"
+- `nc_calendar_list_calendars` → "List Calendars"
+- `nc_contacts_get_contact` → "Get Contact"
+- `nc_semantic_search` → "Semantic Search"
+- `check_logged_in` → "Check Server Login Status"
+
+### Create Tools (~20 tools)
+**Pattern**: Create new resources
+**Annotations**: `idempotentHint=False`, `openWorldHint=True`
+
+Examples:
+- `nc_notes_create_note` → "Create Note"
+- `nc_calendar_create_event` → "Create Calendar Event"
+- `nc_contacts_create_contact` → "Create Contact"
+- `deck_create_card` → "Create Kanban Card"
+- `nc_tables_create_row` → "Create Table Row"
+
+### Update Tools (~25 tools)
+**Pattern**: Modify existing resources with etag
+**Annotations**: `idempotentHint=False` (etag changes), `openWorldHint=True`
+
+Examples:
+- `nc_notes_update_note` → "Update Note"
+- `nc_calendar_update_event` → "Update Calendar Event"
+- `nc_contacts_update_contact` → "Update Contact"
+- `deck_update_card` → "Update Kanban Card"
+
+**Rationale**: Updates require etag, which changes after each update. Same parameters on second call will fail due to stale etag = NOT idempotent.
+
+### Append/Accumulate Tools (~5 tools)
+**Pattern**: Add content without replacing
+**Annotations**: `idempotentHint=False`, `openWorldHint=True`
+
+Examples:
+- `nc_notes_append_content` → "Append to Note"
+
+**Rationale**: Each call adds content, changing the result = NOT idempotent.
+
+### Delete Tools (~10 tools)
+**Pattern**: Remove resources
+**Annotations**: `destructiveHint=True`, `idempotentHint=True`, `openWorldHint=True`
+
+Examples:
+- `nc_notes_delete_note` → "Delete Note"
+- `nc_webdav_delete_resource` → "Delete File or Directory"
+- `nc_calendar_delete_event` → "Delete Calendar Event"
+- `nc_contacts_delete_contact` → "Delete Contact"
+
+**Rationale**: Deleting already-deleted item results in same end state (item doesn't exist) = idempotent. Status code may differ, but outcome is identical.
+
+### Special Cases
+
+#### OAuth Provisioning Tools
+```python
+# Not read-only but requires user interaction
+@mcp.tool(
+    title="Grant Server Access to Nextcloud",
+    annotations=ToolAnnotations(
+        readOnlyHint=False,
+        idempotentHint=False,  # Creates new OAuth session each time
+        openWorldHint=True
+    )
+)
+async def provision_nextcloud_access(ctx: Context):
+```
+
+#### Semantic Search (Closed World)
+```python
+@mcp.tool(
+    title="Semantic Search",
+    annotations=ToolAnnotations(
+        readOnlyHint=True,
+        openWorldHint=False  # Searches only indexed Nextcloud data
+    )
+)
+async def nc_semantic_search(query: str, ctx: Context):
+```
+
+**Rationale**: Semantic search only queries pre-indexed Nextcloud content, not the "open world" like web search would.
+
+## Tool Priority Matrix
+
+### Critical Priority (~2 tools)
+OAuth tools required for server functionality:
+- `provision_nextcloud_access` → "Grant Server Access to Nextcloud"
+- `check_logged_in` → "Check Server Login Status"
+
+### High Priority (~50 tools)
+Most commonly used modules:
+- **Notes** (14 tools): Create, read, update, delete notes
+- **WebDAV** (13 tools): File operations
+- **Calendar** (15 tools): Events and todos
+- **Semantic Search** (6 tools): AI-powered search
+- **Contacts** (9 tools): Address book operations
+
+### Medium Priority (~35 tools)
+Secondary functionality:
+- **Deck** (9 tools): Kanban boards
+- **Tables** (7 tools): Structured data
+- **Sharing** (5 tools): File sharing
+
+### Low Priority (~14 tools)
+Less frequently used:
+- **Cookbook** (8 tools): Recipe management
+- **News** (6 tools): RSS feeds
+
+## Implementation Plan
+
+### Week 1: Phase 1 - Titles
+- Add human-readable titles to all 101 tools
+- Update tool name mapping in documentation
+- Manual test in MCP inspector
+
+### Week 2: Phase 2 - ToolAnnotations (High Priority)
+- Add annotations to Critical and High priority tools (~52 tools)
+- Focus on Notes, WebDAV, Calendar, Semantic, OAuth
+- Add unit tests validating annotation presence
+
+### Week 3: Phase 2 - ToolAnnotations (Medium/Low Priority)
+- Complete remaining tools (~49 tools)
+- Deck, Tables, Contacts, Cookbook, News
+- Update tool listings in README
+
+### Week 4: Phase 3 - Parameter Descriptions
+- Add Field() descriptions to Critical/High priority tools
+- Start with OAuth, Notes, WebDAV modules
+- Incremental completion over time
+
+## Benefits
+
+### For Users
+- **Clearer UI**: "Create Note" vs "nc_notes_create_note"
+- **Safety**: Warnings before destructive operations
+- **Better help**: Parameter descriptions in auto-completion
+- **Confidence**: Know which operations are safe to retry
+
+### For MCP Clients
+- **Caching**: Cache results from read-only tools
+- **Safety prompts**: Warn before destructiveHint=true
+- **Retry logic**: Safely retry idempotent operations
+- **UI organization**: Group by behavior (reads vs writes vs deletes)
+- **Performance**: Optimize based on hints
+
+### For Developers
+- **Self-documenting**: Behavior is explicit
+- **Consistency**: Standard patterns across codebase
+- **Testing**: Validate annotations match implementation
+- **Maintenance**: Clear expectations for new tools
+
+## Consequences
+
+### Positive
+- Immediate UX improvement with minimal effort
+- Clients can make smarter decisions
+- Self-documenting code
+- Follows MCP best practices
+
+### Negative
+- Initial effort to add annotations (12-15 hours total)
+- Must maintain annotations when adding new tools
+- Risk of incorrect annotations misleading clients
+
+### Neutral
+- Annotations are hints, not guarantees
+- Clients may ignore annotations
+- Backward compatible (additive change)
+
+### Mitigations
+- **Incorrect annotations**: Add tests validating behavior matches hints
+- **Maintenance burden**: Add to code review checklist and tool template
+- **Documentation**: Update CLAUDE.md with annotation guidelines
+
+## Examples
+
+### Complete Annotated Tool (Delete)
+
+```python
+from mcp.types import ToolAnnotations
+from pydantic import Field
+
+@mcp.tool(
+    title="Delete Note",
+    annotations=ToolAnnotations(
+        destructiveHint=True,   # Deletes data permanently
+        idempotentHint=True,    # Same end state (note doesn't exist)
+        openWorldHint=True      # Nextcloud is external
+    )
+)
+@require_scopes("notes:write")
+@instrument_tool
+async def nc_notes_delete_note(
+    note_id: int = Field(description="The ID of the note to delete permanently"),
+    ctx: Context
+) -> DeleteNoteResponse:
+    """Delete a note permanently (requires notes:write scope)"""
+    client = await get_client(ctx)
+    # ... implementation ...
+```
+
+### Complete Annotated Tool (Update)
+
+```python
+@mcp.tool(
+    title="Update Note",
+    annotations=ToolAnnotations(
+        idempotentHint=False,   # NOT idempotent: etag changes each update
+        openWorldHint=True
+    )
+)
+@require_scopes("notes:write")
+@instrument_tool
+async def nc_notes_update_note(
+    note_id: int = Field(description="The ID of the note to update"),
+    title: str | None = Field(
+        default=None,
+        description="New title (omit to keep current)"
+    ),
+    content: str | None = Field(
+        default=None,
+        description="New markdown content (omit to keep current)"
+    ),
+    category: str | None = Field(
+        default=None,
+        description="New category/folder (omit to keep current)"
+    ),
+    etag: str = Field(
+        description="ETag from get_note (prevents concurrent modification)"
+    ),
+    ctx: Context
+) -> UpdateNoteResponse:
+    """Update an existing note's title, content, or category.
+
+    The etag parameter is required to prevent overwriting concurrent changes.
+    Get the current ETag by first calling nc_notes_get_note.
+    If the note has been modified since you retrieved it, the update will fail.
+    """
+    client = await get_client(ctx)
+    # ... implementation ...
+```
+
+### Complete Annotated Tool (Read-Only)
+
+```python
+@mcp.tool(
+    title="Search Notes",
+    annotations=ToolAnnotations(
+        readOnlyHint=True,    # Doesn't modify data
+        openWorldHint=True    # Queries Nextcloud
+    )
+)
+@require_scopes("notes:read")
+@instrument_tool
+async def nc_notes_search_notes(
+    query: str = Field(description="Search term to match in note titles or content"),
+    ctx: Context
+) -> SearchNotesResponse:
+    """Search notes by title or content, returning id, title, and category.
+
+    This is a read-only operation that searches across all user notes.
+    Use nc_notes_get_note to retrieve the full content of matching notes.
+    """
+    client = await get_client(ctx)
+    # ... implementation ...
+```
+
+## Testing Strategy
+
+### Unit Tests
+Add tests validating annotation presence and correctness:
+
+```python
+def test_notes_tools_have_annotations():
+    """Verify all notes tools have appropriate annotations."""
+    tools = get_registered_tools(mcp)
+
+    # Check create tool
+    create_tool = tools["nc_notes_create_note"]
+    assert create_tool.title == "Create Note"
+    assert create_tool.annotations.idempotentHint is False
+
+    # Check delete tool
+    delete_tool = tools["nc_notes_delete_note"]
+    assert delete_tool.title == "Delete Note"
+    assert delete_tool.annotations.destructiveHint is True
+    assert delete_tool.annotations.idempotentHint is True
+
+    # Check read-only tool
+    search_tool = tools["nc_notes_search_notes"]
+    assert search_tool.title == "Search Notes"
+    assert search_tool.annotations.readOnlyHint is True
+```
+
+### Integration Tests
+- Verify existing tests pass with annotations
+- Manual testing in MCP inspector/client
+
+### Documentation Updates
+- Update README tool listings with new titles
+- Add annotation guidelines to CLAUDE.md
+- Include examples in developer documentation
+
+## Resolved Questions
+
+1. **WebDAV write_file idempotency** (Resolved: 2025-12-11)
+   - **Decision**: Mark as `idempotentHint=True`
+   - **Rationale**: Uses HTTP PUT without version control. Writing same content to same path repeatedly produces identical end state, which is the definition of idempotency in HTTP semantics.
+
+2. **Semantic search openWorldHint** (Resolved: 2025-12-11)
+   - **Decision**: Mark as `openWorldHint=True`
+   - **Rationale**: For consistency with other Nextcloud tools. While the data being searched is "indexed/internal", Nextcloud itself is external to the MCP server. The fact that data is indexed is an implementation detail, not a fundamental difference from other Nextcloud queries.
+
+3. **Read-only with side effects**: Should tools that log analytics still be readOnlyHint=true?
+   - **Decision**: Yes. Logging/analytics are non-visible side effects that don't change user-observable state. Read-only refers to data modifications that affect the user's content.
+
+## Future Considerations
+
+1. **Icons**: Visual icons for tools (requires design work, deferred to future ADR)
+2. **Parameter descriptions**: Add Pydantic `Field(description=...)` for better auto-completion (Phase 3, future work)
+
+## References
+
+- MCP Python SDK: `/home/chris/Software/python-sdk/`
+- ToolAnnotations spec: `src/mcp/types.py:1247`
+- FastMCP decorator: `src/mcp/server/fastmcp/server.py:444`
+- Examples: `examples/fastmcp/parameter_descriptions.py`, `examples/fastmcp/icons_demo.py`
+
+## Decision Timeline
+
+- **Proposed**: 2025-12-11
+- **Reviewed**: 2025-12-11 (Self-review during implementation)
+- **Accepted**: 2025-12-11
+- **Implemented**: 2025-12-11 (Phase 1 & 2 complete)

docs/ADR-020-deployment-modes-and-configuration-validation.md

@@ -0,0 +1,342 @@
+# ADR-020: Deployment Modes and Configuration Validation
+
+**Status:** Accepted
+**Date:** 2025-12-20
+**Deciders:** Development Team
+**Related:** ADR-002 (Vector Sync), ADR-004 (Progressive Consent), ADR-019 (Multi-user BasicAuth)
+
+## Context
+
+The MCP server supports multiple deployment scenarios with different authentication methods, storage backends, and feature sets. Over time, the configuration system evolved to support ~500+ possible combinations across deployment modes, authentication patterns, and feature toggles. This complexity made it difficult to:
+
+1. Understand what configuration is required for a given deployment
+2. Debug configuration errors (validation scattered across multiple files)
+3. Provide helpful error messages when configuration is invalid
+4. Maintain clear boundaries between deployment modes
+
+**Problems Identified:**
+- No single source of truth for "what config is required for mode X"
+- Validation happening at 4+ different points (Settings.__post_init__, setup_oauth_config(), context helpers, starlette_lifespan)
+- Startup sequence unclear (OAuth setup before FastMCP creation, sync initialization errors)
+- Error messages generic ("X is required") without explaining which deployment mode triggered the requirement
+- Multiple overlapping decision trees (deployment mode, auth mode, features)
+
+## Decision
+
+We formalize five distinct deployment modes with explicit configuration requirements and implement centralized configuration validation.
+
+### Deployment Modes
+
+#### 1. Single-User BasicAuth
+
+**Use Case:** Personal Nextcloud instance, local development
+
+**Required Configuration:**
+```bash
+NEXTCLOUD_HOST=http://localhost:8080
+NEXTCLOUD_USERNAME=admin
+NEXTCLOUD_PASSWORD=password  # Or app password
+```
+
+**Optional Configuration:**
+```bash
+# Vector sync (semantic search)
+VECTOR_SYNC_ENABLED=true
+QDRANT_LOCATION=/path/to/qdrant  # Or QDRANT_URL for remote
+
+# Embeddings (optional - Simple provider used as fallback)
+OLLAMA_BASE_URL=http://localhost:11434
+OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+
+# Document processing
+DOCUMENT_CHUNK_SIZE=512
+DOCUMENT_CHUNK_OVERLAP=50
+```
+
+**Characteristics:**
+- Single shared NextcloudClient created at startup
+- No OAuth infrastructure needed
+- No multi-user support
+- Vector sync runs as single-user background task
+- Admin UI available at /app
+
+---
+
+#### 2. Multi-User BasicAuth Pass-Through
+
+**Use Case:** Internal deployment where users provide their own credentials, no background sync needed
+
+**Required Configuration:**
+```bash
+NEXTCLOUD_HOST=http://nextcloud.example.com
+ENABLE_MULTI_USER_BASIC_AUTH=true
+```
+
+**Optional Configuration:**
+```bash
+# For background sync (requires app passwords from Astrolabe)
+ENABLE_OFFLINE_ACCESS=true
+TOKEN_ENCRYPTION_KEY=<key>
+TOKEN_STORAGE_DB=/path/to/tokens.db
+NEXTCLOUD_OIDC_CLIENT_ID=<client-id>
+NEXTCLOUD_OIDC_CLIENT_SECRET=<client-secret>
+VECTOR_SYNC_ENABLED=true
+# ... plus Qdrant and embedding config
+```
+
+**Conditional Requirements:**
+- If `ENABLE_OFFLINE_ACCESS=true`: requires `NEXTCLOUD_OIDC_CLIENT_ID`, `NEXTCLOUD_OIDC_CLIENT_SECRET`, `TOKEN_ENCRYPTION_KEY`, `TOKEN_STORAGE_DB`
+- If `VECTOR_SYNC_ENABLED=true`: requires `ENABLE_OFFLINE_ACCESS=true`
+
+**Characteristics:**
+- No OAuth for client authentication (uses BasicAuth in request headers)
+- BasicAuthMiddleware extracts credentials from Authorization header
+- Client created per-request from extracted credentials
+- Optional: Background sync using app passwords (via Astrolabe API)
+- Admin UI available at /app
+
+---
+
+#### 3. OAuth Single-Audience (Default)
+
+**Use Case:** Multi-user deployment with OAuth authentication, tokens work for both MCP and Nextcloud
+
+**Required Configuration:**
+```bash
+NEXTCLOUD_HOST=http://nextcloud.example.com
+# No NEXTCLOUD_USERNAME/PASSWORD (triggers OAuth mode)
+```
+
+**Auto-Configured:**
+- OIDC discovery URL: `{NEXTCLOUD_HOST}/.well-known/openid-configuration`
+- Client credentials: Dynamic Client Registration (DCR) if available
+- Token storage: SQLite at `~/.oauth/clients.db`
+
+**Optional Configuration:**
+```bash
+# Static client credentials (instead of DCR)
+NEXTCLOUD_OIDC_CLIENT_ID=<client-id>
+NEXTCLOUD_OIDC_CLIENT_SECRET=<client-secret>
+
+# Offline access for background sync
+ENABLE_OFFLINE_ACCESS=true
+TOKEN_ENCRYPTION_KEY=<key>
+TOKEN_STORAGE_DB=/path/to/tokens.db
+VECTOR_SYNC_ENABLED=true
+# ... plus Qdrant and embedding config
+
+# Scopes
+NEXTCLOUD_OIDC_SCOPES="openid profile email notes:read notes:write ..."
+```
+
+**Conditional Requirements:**
+- If `ENABLE_OFFLINE_ACCESS=true`: requires `TOKEN_ENCRYPTION_KEY`, `TOKEN_STORAGE_DB`
+- If `VECTOR_SYNC_ENABLED=true`: requires `ENABLE_OFFLINE_ACCESS=true`
+
+**Characteristics:**
+- Tokens contain both `aud: ["mcp-server", "nextcloud"]`
+- Pass token through to Nextcloud APIs (no exchange)
+- Client created per-request from token in Authorization header
+- Background sync uses refresh tokens (if offline_access enabled)
+- Admin UI available at /app
+
+---
+
+#### 4. OAuth Token Exchange (RFC 8693)
+
+**Use Case:** Multi-user deployment where MCP token is separate from Nextcloud token
+
+**Required Configuration:**
+```bash
+NEXTCLOUD_HOST=http://nextcloud.example.com
+ENABLE_TOKEN_EXCHANGE=true
+# No NEXTCLOUD_USERNAME/PASSWORD (triggers OAuth mode)
+```
+
+**Optional Configuration:**
+- Same as OAuth Single-Audience, plus:
+```bash
+TOKEN_EXCHANGE_CACHE_TTL=300  # Cache exchanged tokens
+```
+
+**Characteristics:**
+- Tokens contain only `aud: "mcp-server"`
+- MCP server exchanges token for Nextcloud token via RFC 8693
+- Exchanged tokens cached per-user
+- Client created per-request using exchanged token
+- Background sync uses refresh tokens (if offline_access enabled)
+
+---
+
+#### 5. Smithery Stateless
+
+**Use Case:** Multi-tenant SaaS deployment via Smithery platform
+
+**Required Configuration:**
+- None! Configuration comes from session URL params: `?nextcloud_url=...&username=...&app_password=...`
+
+**Forbidden Configuration:**
+- Must NOT set: `NEXTCLOUD_HOST`, `NEXTCLOUD_USERNAME`, `NEXTCLOUD_PASSWORD`, `ENABLE_MULTI_USER_BASIC_AUTH`, `ENABLE_TOKEN_EXCHANGE`, `ENABLE_OFFLINE_ACCESS`, `VECTOR_SYNC_ENABLED`, `NEXTCLOUD_OIDC_CLIENT_ID`, `NEXTCLOUD_OIDC_CLIENT_SECRET`
+
+**Characteristics:**
+- No persistent storage (stateless)
+- Client created per-request from session config
+- No vector sync (disabled)
+- No admin UI (no /app routes)
+- No OAuth infrastructure
+
+---
+
+### Configuration Validation
+
+**Implementation:** `nextcloud_mcp_server/config_validators.py`
+
+**Key Functions:**
+```python
+def detect_auth_mode(settings: Settings) -> AuthMode:
+    """Detect authentication mode from configuration.
+
+    Priority (most specific to most general):
+    1. Smithery (explicit flag)
+    2. Token exchange (most specific OAuth mode)
+    3. Multi-user BasicAuth
+    4. Single-user BasicAuth
+    5. OAuth single-audience (default OAuth mode)
+    """
+
+def validate_configuration(settings: Settings) -> tuple[AuthMode, list[str]]:
+    """Validate configuration for detected mode.
+
+    Returns:
+        Tuple of (detected_mode, list_of_errors)
+        Empty list means valid configuration.
+    """
+```
+
+**Validation Rules:**
+- **Required variables:** Must be set and non-empty
+- **Forbidden variables:** Must NOT be set (or must be False for booleans)
+- **Conditional requirements:** If feature X is enabled, requires variables Y and Z
+
+**Error Messages:**
+```
+Configuration validation failed for {mode} mode:
+  - [{mode}] Missing required configuration: NEXTCLOUD_HOST
+  - [{mode}] ENABLE_OFFLINE_ACCESS must be enabled when VECTOR_SYNC_ENABLED is true
+
+Mode: {mode}
+Description: {mode_description}
+
+Required configuration:
+  - VAR1
+  - VAR2
+
+Optional configuration:
+  - VAR3
+  - VAR4
+
+Conditional requirements:
+  When FEATURE is enabled:
+    - VAR5
+    - VAR6
+```
+
+**Integration:**
+- Validation runs at app startup in `get_app()` (app.py:1048-1062)
+- All errors reported before any initialization begins
+- Mode-specific error messages explain requirements
+- Validation uses the same Settings object used throughout the app
+
+### Configuration Matrix
+
+| Variable | Single BasicAuth | Multi BasicAuth | OAuth Single | OAuth Exchange | Smithery |
+|----------|------------------|-----------------|--------------|----------------|----------|
+| **NEXTCLOUD_HOST** | Required | Required | Required | Required | Forbidden |
+| **NEXTCLOUD_USERNAME** | Required | Forbidden | Forbidden | Forbidden | Forbidden |
+| **NEXTCLOUD_PASSWORD** | Required | Forbidden | Forbidden | Forbidden | Forbidden |
+| **ENABLE_MULTI_USER_BASIC_AUTH** | Forbidden | Required | Forbidden | Forbidden | Forbidden |
+| **ENABLE_TOKEN_EXCHANGE** | Forbidden | Forbidden | Forbidden | Required | Forbidden |
+| **ENABLE_OFFLINE_ACCESS** | Optional\* | Optional\* | Optional\* | Optional\* | Forbidden |
+| **TOKEN_ENCRYPTION_KEY** | If offline | If offline | If offline | If offline | Forbidden |
+| **TOKEN_STORAGE_DB** | If offline | If offline | If offline | If offline | Forbidden |
+| **OIDC_CLIENT_ID** | Forbidden | If offline | Optional\*\* | Optional\*\* | Forbidden |
+| **OIDC_CLIENT_SECRET** | Forbidden | If offline | Optional\*\* | Optional\*\* | Forbidden |
+| **VECTOR_SYNC_ENABLED** | Optional | Optional | Optional | Optional | Forbidden |
+| **QDRANT_URL/LOCATION** | If vector | If vector | If vector | If vector | Forbidden |
+| **OLLAMA_BASE_URL/OPENAI_API_KEY** | Optional | Optional | Optional | Optional | Forbidden |
+
+\* Only enables background sync for semantic search
+\*\* Uses DCR if not provided
+
+## Consequences
+
+### Positive
+
+1. **Clarity:** Single function to detect mode from config
+2. **Validation:** All config validated upfront with helpful errors
+3. **Debugging:** Clear logs showing "Running in X mode with config Y"
+4. **Maintenance:** Mode-specific logic can be isolated
+5. **Documentation:** Clear mapping of mode → required config
+6. **Error Messages:** Context-aware ("X is required for Y mode")
+7. **Testing:** Each mode testable in isolation
+
+### Negative
+
+1. **Migration:** Existing invalid configurations will now fail at startup
+2. **Flexibility:** Less flexibility in configuration combinations
+3. **Strictness:** Some previously-working combinations may be rejected
+
+### Neutral
+
+1. **Backward Compatibility:** Valid configurations continue to work
+2. **Mode Detection:** Automatic based on config (no explicit mode selection)
+3. **Default Mode:** OAuth single-audience when no credentials provided
+
+## Implementation Notes
+
+### Embedding Provider Validation
+
+Originally, validation required either `OLLAMA_BASE_URL` or `OPENAI_API_KEY` when vector sync was enabled. This was too strict because the Simple provider is always available as a fallback (ADR-015). The validation was removed to allow vector sync without explicit provider configuration.
+
+### Variable Scoping Issues
+
+During implementation, several Python variable scoping issues were discovered in `app.py`:
+- Local variable assignments in `starlette_lifespan()` shadowed outer scope variables
+- Fixed by using unique variable names (e.g., `nextcloud_host_for_context`, `basic_auth_storage`)
+- Removed redundant `settings = get_settings()` call (re-used outer scope)
+
+### Docker Compose Configuration
+
+The `mcp-oauth` service configuration was updated to remove `ENABLE_MULTI_USER_BASIC_AUTH=true` which conflicted with its intended OAuth mode. The service now runs in OAuth single-audience mode with vector sync using the Simple embedding provider as fallback.
+
+## Testing
+
+### Unit Tests
+
+`tests/unit/test_config_validators.py` provides comprehensive coverage:
+- Mode detection with priority ordering (7 tests)
+- Single-user BasicAuth validation (8 tests)
+- Multi-user BasicAuth validation (7 tests)
+- OAuth single-audience validation (6 tests)
+- OAuth token exchange validation (3 tests)
+- Smithery validation (4 tests)
+- Mode summary generation (3 tests)
+- Edge cases (3 tests)
+
+**Total: 41 tests, all passing**
+
+### Integration Tests
+
+Integration tests verify that:
+- Each mode starts successfully with valid configuration
+- Invalid configurations fail with clear error messages
+- Existing deployments continue to work
+
+## References
+
+- [ADR-002: Vector Sync Authentication](ADR-002-vector-sync-authentication.md)
+- [ADR-004: Progressive Consent](ADR-004-progressive-consent.md)
+- [ADR-015: Unified Provider Architecture](ADR-015-unified-provider-architecture.md)
+- [ADR-019: Multi-user BasicAuth Pass-Through](ADR-019-multi-user-basicauth-passthrough.md)
+- Implementation: `nextcloud_mcp_server/config_validators.py`
+- Tests: `tests/unit/test_config_validators.py`

docs/ADR-021-configuration-consolidation.md

@@ -0,0 +1,391 @@
+# ADR-021: Configuration Consolidation and Simplification
+
+**Status:** Accepted
+**Date:** 2025-12-21
+**Deciders:** Development Team
+**Related:** ADR-020 (Deployment Modes), ADR-002 (Vector Sync), ADR-004 (Progressive Consent)
+
+## Context
+
+The configuration system has grown complex with overlapping concerns that make it difficult for users to switch between deployment modes and understand configuration dependencies.
+
+### Problems Identified
+
+1. **Confusing variable names don't reflect purpose**:
+   - `ENABLE_OFFLINE_ACCESS` - Actually controls refresh token storage for background operations, not general "offline" capabilities
+   - `VECTOR_SYNC_ENABLED` - Controls semantic search background indexing (implementation detail, not user-facing feature name)
+   - Users struggle to understand what these variables actually control
+
+2. **Redundant configuration requirements**:
+   - Multi-user semantic search requires setting BOTH `ENABLE_OFFLINE_ACCESS=true` AND `VECTOR_SYNC_ENABLED=true`
+   - The dependency is one-way (semantic search needs background ops, but background ops don't need semantic search)
+   - Users must understand internal implementation details to configure a user-facing feature
+
+3. **Implicit mode detection creates ambiguity**:
+   - Five deployment modes detected via priority-based logic
+   - Users can't easily predict which mode will activate
+   - Configuration errors don't clearly indicate which mode triggered the requirement
+
+4. **OIDC_CLIENT_ID vs NEXTCLOUD_OIDC_CLIENT_ID confusion**:
+   - Investigation revealed these are NOT actually overlapping (`OIDC_CLIENT_ID` is test-only)
+   - However, their similar names create confusion
+
+### Current Configuration Complexity
+
+**Example: Multi-user OAuth with semantic search**:
+```bash
+NEXTCLOUD_HOST=https://nextcloud.example.com
+ENABLE_OFFLINE_ACCESS=true      # Why is this needed?
+VECTOR_SYNC_ENABLED=true        # And this separately?
+QDRANT_URL=http://qdrant:6333
+TOKEN_ENCRYPTION_KEY=<key>
+TOKEN_STORAGE_DB=/path/to/tokens.db
+```
+
+Users must understand:
+- Semantic search requires background token storage (ENABLE_OFFLINE_ACCESS)
+- Background token storage requires encryption keys
+- The relationship between ENABLE_OFFLINE_ACCESS and VECTOR_SYNC_ENABLED
+- Which deployment mode these settings will activate
+
+## Decision
+
+We consolidate overlapping functionality and add explicit mode selection while maintaining 100% backward compatibility.
+
+### 1. Automatic Dependency Resolution
+
+**Make ENABLE_SEMANTIC_SEARCH the primary control** that automatically enables required dependencies:
+
+**New behavior**:
+```python
+@property
+def enable_background_operations(self) -> bool:
+    """Background operations - auto-enabled by semantic search in multi-user modes."""
+    # Check new names first
+    explicit = os.getenv("ENABLE_BACKGROUND_OPERATIONS", "").lower() == "true"
+    # Fall back to old name with deprecation warning
+    legacy = os.getenv("ENABLE_OFFLINE_ACCESS", "").lower() == "true"
+    # Auto-enable if semantic search needs it
+    auto_enabled = self.enable_semantic_search and self.is_multi_user_mode()
+
+    return explicit or legacy or auto_enabled
+
+@property
+def enable_semantic_search(self) -> bool:
+    """Semantic search - renamed from VECTOR_SYNC_ENABLED."""
+    new_value = os.getenv("ENABLE_SEMANTIC_SEARCH", "").lower() == "true"
+    old_value = os.getenv("VECTOR_SYNC_ENABLED", "").lower() == "true"
+    return new_value or old_value
+```
+
+**Result**: Users set `ENABLE_SEMANTIC_SEARCH=true` and the system automatically enables background token storage when needed.
+
+### 2. Explicit Mode Selection (Optional)
+
+Add `MCP_DEPLOYMENT_MODE` environment variable to remove detection ambiguity:
+
+```bash
+# Optional: Explicitly declare deployment mode
+MCP_DEPLOYMENT_MODE=oauth_single_audience
+
+# Valid values: single_user_basic, multi_user_basic,
+#               oauth_single_audience, oauth_token_exchange, smithery
+```
+
+**Detection logic**:
+1. If `MCP_DEPLOYMENT_MODE` is set → validate and use it
+2. Otherwise → use priority-based auto-detection (existing behavior)
+3. Validate explicit mode doesn't conflict with detected mode
+
+### 3. Simplified User Experience
+
+**Before**:
+```bash
+# Multi-user OAuth with semantic search
+NEXTCLOUD_HOST=https://nextcloud.example.com
+ENABLE_OFFLINE_ACCESS=true      # Confusing
+VECTOR_SYNC_ENABLED=true        # Why both?
+QDRANT_URL=http://qdrant:6333
+TOKEN_ENCRYPTION_KEY=<key>
+TOKEN_STORAGE_DB=/path/to/tokens.db
+```
+
+**After**:
+```bash
+# Multi-user OAuth with semantic search
+NEXTCLOUD_HOST=https://nextcloud.example.com
+MCP_DEPLOYMENT_MODE=oauth_single_audience  # Explicit (optional)
+ENABLE_SEMANTIC_SEARCH=true                # Auto-enables background ops
+QDRANT_URL=http://qdrant:6333
+TOKEN_ENCRYPTION_KEY=<key>
+TOKEN_STORAGE_DB=/path/to/tokens.db
+```
+
+**Benefits**:
+- 2 fewer variables to understand/set
+- Clear intent ("I want semantic search")
+- Explicit mode declaration (optional)
+- All existing configs continue working
+
+### 4. Variable Naming Strategy
+
+**Deprecated (but still functional)**:
+- `ENABLE_OFFLINE_ACCESS` → Renamed to `ENABLE_BACKGROUND_OPERATIONS`
+- `VECTOR_SYNC_ENABLED` → Renamed to `ENABLE_SEMANTIC_SEARCH`
+
+**No change needed**:
+- `VECTOR_SYNC_SCAN_INTERVAL` - Implementation tuning parameter (keep as-is)
+- `VECTOR_SYNC_PROCESSOR_WORKERS` - Implementation tuning parameter (keep as-is)
+- `VECTOR_SYNC_QUEUE_MAX_SIZE` - Implementation tuning parameter (keep as-is)
+
+**Rationale**: Only rename user-facing feature flags, not internal tuning parameters.
+
+### 5. Backward Compatibility
+
+**Support both old and new names for minimum 2 major versions**:
+
+```python
+@property
+def enable_semantic_search(self) -> bool:
+    new_value = os.getenv("ENABLE_SEMANTIC_SEARCH", "").lower() == "true"
+    old_value = os.getenv("VECTOR_SYNC_ENABLED", "").lower() == "true"
+
+    if new_value and old_value:
+        logger.warning(
+            "Both ENABLE_SEMANTIC_SEARCH and VECTOR_SYNC_ENABLED are set. "
+            "Using ENABLE_SEMANTIC_SEARCH. VECTOR_SYNC_ENABLED is deprecated."
+        )
+
+    if old_value and not new_value:
+        logger.warning(
+            "VECTOR_SYNC_ENABLED is deprecated. Please use ENABLE_SEMANTIC_SEARCH instead."
+        )
+
+    return new_value or old_value
+```
+
+**Deprecation timeline**:
+- v0.6.0: Add new variables, deprecate old ones (both work with warnings)
+- v1.0.0: Remove old variables (breaking change, well-announced)
+- Minimum 2 major versions of support (12+ months)
+
+## Consequences
+
+### Positive
+
+1. **Reduced cognitive load**: Users set `ENABLE_SEMANTIC_SEARCH=true` instead of understanding internal dependencies
+2. **Clearer intent**: Variable names reflect user-facing features, not implementation details
+3. **Explicit mode control**: `MCP_DEPLOYMENT_MODE` removes detection ambiguity
+4. **Better onboarding**: New users see simpler configuration in env.sample
+5. **Improved error messages**: Validation can suggest "set MCP_DEPLOYMENT_MODE=X" instead of relying on implicit detection
+6. **No breaking changes**: All existing configurations continue working
+
+### Negative
+
+1. **Transition period complexity**: Both old and new names supported for 2+ versions
+2. **Documentation burden**: All docs must be updated to show new approach
+3. **Test coverage expansion**: Must test both old and new variable names in all modes
+4. **Migration effort**: Existing deployments should eventually migrate (optional but recommended)
+
+### Neutral
+
+1. **Same functionality**: No new features, just better organization
+2. **Same validation**: Underlying requirements unchanged (e.g., semantic search still needs Qdrant)
+3. **Same performance**: No runtime performance impact
+
+## Implementation
+
+### Phase 1: Configuration Consolidation (v0.6.0)
+
+**Files to modify**:
+- `nextcloud_mcp_server/config.py` - Add property-based deprecation with auto-enablement
+- `nextcloud_mcp_server/config_validators.py` - Simplify validation (semantic search no longer requires explicit background operations setting)
+- `nextcloud_mcp_server/app.py` - Add informative logging for auto-enablement
+- `tests/unit/test_config_validators.py` - Add auto-enablement tests
+- `docs/configuration-migration-v2.md` - Create migration guide
+
+**Key changes**:
+1. `enable_background_operations` property auto-enables when `enable_semantic_search=true` in multi-user modes
+2. `enable_semantic_search` property accepts both `ENABLE_SEMANTIC_SEARCH` and `VECTOR_SYNC_ENABLED`
+3. Smart logging when auto-enablement occurs or deprecated variables used
+4. Validation simplified to remove redundant requirements
+
+### Phase 2: Explicit Mode Selection (v0.6.0)
+
+**Files to modify**:
+- `nextcloud_mcp_server/config.py` - Add `deployment_mode` field
+- `nextcloud_mcp_server/config_validators.py` - Check explicit mode first, fall back to auto-detection
+- `tests/unit/test_config_validators.py` - Test mode override and conflict detection
+- `docs/configuration.md` - Document mode selection
+
+**Key changes**:
+1. Add `MCP_DEPLOYMENT_MODE` environment variable (optional)
+2. Mode detection checks explicit mode first, then auto-detects
+3. Validate explicit mode doesn't conflict with detected mode
+4. Better error messages referencing explicit mode setting
+
+### Phase 3: env.sample Reorganization (v0.6.0)
+
+**Files to create/modify**:
+- `env.sample` - Reorganize by deployment mode
+- `env.sample.single-user` - Simplest config template
+- `env.sample.oauth-multi-user` - Multi-user template showing consolidation
+- `env.sample.oauth-advanced` - Token exchange mode template
+- `README.md` - Update Quick Start to reference templates
+
+**Key changes**:
+1. Group related settings by deployment mode
+2. Show simplified configuration (only essential variables)
+3. Document automatic dependencies inline
+4. Provide mode-specific quick-start templates
+
+### Phase 4: Documentation Updates (v0.7.0)
+
+**Files to modify**:
+- `docs/configuration.md` - Lead with consolidated approach
+- `docs/authentication.md` - Update mode guidance with `MCP_DEPLOYMENT_MODE`
+- `docs/troubleshooting.md` - Add consolidation troubleshooting section
+- `docs/configuration-migration-v2.md` - Expand with comprehensive examples
+- `docs/ADR-020-deployment-modes-and-configuration-validation.md` - Update configuration matrix
+- All other ADRs - Update variable references
+
+**Key changes**:
+1. Update all examples to use new variable names
+2. Add before/after migration examples
+3. Document automatic dependency resolution
+4. Add mode selection decision tree diagram
+
+## Validation Strategy
+
+### Test Coverage Requirements
+
+**Backward compatibility tests**:
+- Old variable names still work (ENABLE_OFFLINE_ACCESS, VECTOR_SYNC_ENABLED)
+- New variable names work (ENABLE_BACKGROUND_OPERATIONS, ENABLE_SEMANTIC_SEARCH)
+- Setting both old and new triggers deprecation warning but works correctly
+- All 41 existing config validation tests pass
+
+**Auto-enablement tests**:
+- `ENABLE_SEMANTIC_SEARCH=true` in OAuth mode → `enable_background_operations=true`
+- `ENABLE_SEMANTIC_SEARCH=true` in single-user mode → `enable_background_operations=false` (not needed)
+- `ENABLE_SEMANTIC_SEARCH=false` → `enable_background_operations=false` (unless explicitly set)
+
+**Mode selection tests**:
+- `MCP_DEPLOYMENT_MODE=oauth_single_audience` → mode correctly detected
+- `MCP_DEPLOYMENT_MODE` conflicts with detected mode → validation error
+- No `MCP_DEPLOYMENT_MODE` → auto-detection works as before
+
+## Success Metrics
+
+**Immediate** (v0.6.0 release):
+- Zero breaking changes in existing deployments
+- All 41 config validation tests pass
+- New users report clearer configuration process
+
+**Medium-term** (6 months after v0.6.0):
+- 80% of new deployments use new variable names
+- Mode selection errors decrease by 50%
+- Support requests about configuration decrease
+
+**Long-term** (12+ months):
+- 90% of deployments migrated to new names
+- Old variable names can be safely removed in v1.0.0
+- Configuration-related issues in issue tracker decrease
+
+## Alternatives Considered
+
+### Alternative 1: Just Rename Variables
+
+**Rejected**: User feedback: "There's no reason to just rename variables without consolidating functionality"
+
+This would make names clearer but wouldn't reduce the number of variables users need to set. The real problem is requiring users to set both ENABLE_OFFLINE_ACCESS and VECTOR_SYNC_ENABLED when they just want semantic search.
+
+### Alternative 2: Remove ENABLE_OFFLINE_ACCESS Entirely
+
+**Rejected**: Advanced users need background operations without semantic search
+
+Some deployments might want background token storage for future features (background Deck sync, background Calendar sync, etc.) without enabling semantic search. Keeping ENABLE_BACKGROUND_OPERATIONS (renamed) allows this.
+
+### Alternative 3: Always Auto-Enable Background Operations
+
+**Rejected**: Single-user mode doesn't need background token storage
+
+Auto-enablement is only needed in multi-user modes. Single-user mode uses a shared client with BasicAuth, so background token storage is unnecessary. Always enabling it would waste resources and create confusing log messages.
+
+### Alternative 4: Require All New Names Immediately
+
+**Rejected**: Breaking change would affect all existing deployments
+
+Forcing migration to new variable names in v0.6.0 would break every existing deployment. Supporting both old and new names with deprecation warnings provides a smooth migration path.
+
+## References
+
+- [ADR-020: Deployment Modes and Configuration Validation](ADR-020-deployment-modes-and-configuration-validation.md)
+- [ADR-002: Vector Sync Authentication](ADR-002-vector-sync-authentication.md)
+- [ADR-004: Progressive Consent](ADR-004-mcp-application-oauth.md)
+- [Issue: Configuration complexity for multi-user semantic search](https://github.com/cbcoutinho/nextcloud-mcp-server/issues/XXX)
+
+## Migration Examples
+
+### Example 1: Single-User BasicAuth with Semantic Search
+
+**Before**:
+```bash
+NEXTCLOUD_HOST=http://localhost:8080
+NEXTCLOUD_USERNAME=admin
+NEXTCLOUD_PASSWORD=password
+VECTOR_SYNC_ENABLED=true
+QDRANT_LOCATION=:memory:
+```
+
+**After** (optional migration):
+```bash
+NEXTCLOUD_HOST=http://localhost:8080
+NEXTCLOUD_USERNAME=admin
+NEXTCLOUD_PASSWORD=password
+ENABLE_SEMANTIC_SEARCH=true  # Renamed
+QDRANT_LOCATION=:memory:
+# Note: Background operations NOT auto-enabled (not needed in single-user mode)
+```
+
+### Example 2: Multi-User OAuth with Semantic Search
+
+**Before**:
+```bash
+NEXTCLOUD_HOST=https://nextcloud.example.com
+ENABLE_OFFLINE_ACCESS=true
+VECTOR_SYNC_ENABLED=true
+TOKEN_ENCRYPTION_KEY=<key>
+TOKEN_STORAGE_DB=/path/to/tokens.db
+QDRANT_URL=http://qdrant:6333
+```
+
+**After** (simplified):
+```bash
+NEXTCLOUD_HOST=https://nextcloud.example.com
+MCP_DEPLOYMENT_MODE=oauth_single_audience  # Explicit (optional)
+ENABLE_SEMANTIC_SEARCH=true                # Auto-enables background operations
+TOKEN_ENCRYPTION_KEY=<key>
+TOKEN_STORAGE_DB=/path/to/tokens.db
+QDRANT_URL=http://qdrant:6333
+# Note: ENABLE_OFFLINE_ACCESS no longer needed (auto-enabled)
+```
+
+### Example 3: Multi-User OAuth WITHOUT Semantic Search
+
+**Before**:
+```bash
+NEXTCLOUD_HOST=https://nextcloud.example.com
+ENABLE_OFFLINE_ACCESS=true  # For future background features
+TOKEN_ENCRYPTION_KEY=<key>
+TOKEN_STORAGE_DB=/path/to/tokens.db
+```
+
+**After** (optional migration):
+```bash
+NEXTCLOUD_HOST=https://nextcloud.example.com
+MCP_DEPLOYMENT_MODE=oauth_single_audience
+ENABLE_BACKGROUND_OPERATIONS=true  # Renamed for clarity
+TOKEN_ENCRYPTION_KEY=<key>
+TOKEN_STORAGE_DB=/path/to/tokens.db
+```

docs/ADR-023-oauth-as-proxy.md

@@ -0,0 +1,169 @@
+# ADR-023: OAuth Authorization Server Proxy
+
+## Status
+
+Accepted
+
+## Date
+
+2026-03-02
+
+## Context
+
+When the MCP server operates in OAuth mode (e.g., `mcp-login-flow` profile), MCP clients like Claude Code need to authenticate before calling any tools. The server advertises itself as an OAuth Protected Resource via RFC 9728 (Protected Resource Metadata / PRM), which tells clients where to find the Authorization Server.
+
+### The Problem
+
+The original design used a **pass-through** pattern for Flow 1 (client authentication):
+
+1. PRM at `/.well-known/oauth-protected-resource` pointed `authorization_servers` to Nextcloud's public URL
+2. Claude Code performed OIDC discovery on Nextcloud, used DCR to register its own client, and obtained tokens directly from Nextcloud
+3. Tokens issued by Nextcloud had Claude Code's `client_id` as the `aud` (audience) claim
+
+This caused an audience mismatch:
+
+```
+Token rejected: Missing MCP audience.
+Got klehQp8uHCK9fu... (Claude Code's client_id),
+need 8ilzB5ZPWr2Qt4... (MCP server's client_id) or http://localhost:8004
+```
+
+The `_has_mcp_audience()` check in `unified_verifier.py` correctly requires tokens to contain either the MCP server's `client_id` or its URL as the audience — but tokens obtained directly from Nextcloud by a third-party client will never have that audience.
+
+This meant Claude Code could never authenticate → could never call `nc_auth_provision_access` → Login Flow v2 never triggered → the server was unusable.
+
+### Why Not Just Relax Audience Validation?
+
+Audience validation exists for security (RFC 7519 §4.1.3). Removing it would allow any valid Nextcloud token to access the MCP server, including tokens issued for completely different purposes.
+
+## Decision
+
+Make the MCP server act as its own **OAuth Authorization Server proxy** (intermediary pattern). The MCP server advertises itself as the AS, handles client registration and authorization, but proxies the actual authentication to Nextcloud using its own credentials. This ensures all tokens have the correct audience.
+
+### Flow Overview
+
+```
+Client                    MCP Server (AS Proxy)              Nextcloud (IdP)
+  |                              |                                |
+  |-- POST /oauth/register ----->| ---- proxy DCR --------------->|
+  |<---- client_id, etc. --------|<---- client_id, etc. ----------|
+  |                              |                                |
+  |-- GET /oauth/authorize ----->| (store client params)          |
+  |  (client_id, redirect,       | redirect with MCP's client_id  |
+  |   code_challenge, state)     |------- GET /authorize -------->|
+  |                              |  (MCP client_id, MCP callback) |
+  |                              |                                |
+  |                              |    [user authenticates]        |
+  |                              |                                |
+  |                              |<------ code + state -----------|
+  |                              | (exchange code server-side)    |
+  |                              |------- POST /token ----------->|
+  |                              |  (code, MCP client_id+secret)  |
+  |                              |<------ NC token (aud=MCP) -----|
+  |                              |                                |
+  |                              | (generate proxy_code, store    |
+  |                              |  mapping to NC token)          |
+  |<-- redirect to client -------|                                |
+  |    (proxy_code, state)       |                                |
+  |                              |                                |
+  |-- POST /oauth/token -------->| (verify PKCE, lookup code)    |
+  |  (proxy_code, code_verifier) | return stored NC token        |
+  |<---- access_token -----------|                                |
+  |                              |                                |
+  |-- POST /mcp (Bearer token) ->| verify_access_token()         |
+  |  (NC token with aud=MCP ✓)   | _has_mcp_audience() → PASS    |
+```
+
+### Key Design Decisions
+
+#### 1. PKCE Handling — Local Verification
+
+The MCP server receives the client's `code_challenge` but does **not** forward it to Nextcloud. Instead:
+
+- **Nextcloud side**: MCP server authenticates as a confidential client (`client_id` + `client_secret`), so PKCE is not required
+- **Client side**: MCP server verifies PKCE locally when the client exchanges the proxy code at `/oauth/token`
+
+This avoids the impossible situation where the server would need the `code_verifier` to exchange code with Nextcloud but doesn't have it (only the client does).
+
+#### 2. In-Memory Proxy Code Storage
+
+Proxy codes (the authorization codes issued by the AS proxy to clients) use in-memory storage rather than SQLite because:
+
+- They have a 60-second TTL
+- They are single-use (deleted on exchange)
+- They only exist during the brief OAuth flow
+- The MCP server is single-instance
+
+#### 3. PRM Points to MCP Server
+
+The `authorization_servers` field in the PRM response now points to the MCP server URL instead of Nextcloud's public URL. This is what triggers the entire proxy flow — clients discover the MCP server as their AS.
+
+#### 4. DCR Proxy
+
+Client registration requests at `/oauth/register` are proxied to Nextcloud's DCR endpoint. The resulting `client_id` is stored in the local `ClientRegistry` so that `/oauth/authorize` can validate it. The client receives the same DCR response it would get from Nextcloud directly.
+
+## Alternatives Considered
+
+### 1. Relax Audience Validation
+
+Remove `_has_mcp_audience()` check entirely. **Rejected**: Violates RFC 7519 security model.
+
+### 2. Client Pre-Registration
+
+Require clients to register directly with Nextcloud and configure the MCP server with their `client_id`. **Rejected**: Poor UX, doesn't work with DCR-based clients like Claude Code.
+
+### 3. Token Exchange (RFC 8693)
+
+The MCP server could accept any Nextcloud token and exchange it for one with the correct audience. **Rejected**: Nextcloud's OIDC app doesn't support RFC 8693 token exchange. This was already explored in ADR-005.
+
+### 4. Custom Audience Configuration
+
+Add configuration to accept specific external `client_id` values as valid audiences. **Rejected**: Requires manual configuration per client, doesn't scale with DCR.
+
+## New Endpoints
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/.well-known/oauth-authorization-server` | GET | RFC 8414 AS metadata |
+| `/oauth/authorize` | GET | Authorization (modified: intermediary, not pass-through) |
+| `/oauth/token` | POST | Token exchange (proxy codes + refresh token proxy) |
+| `/oauth/register` | POST | DCR proxy to Nextcloud |
+
+## Files Modified
+
+| File | Changes |
+|------|---------|
+| `nextcloud_mcp_server/auth/oauth_routes.py` | New: `oauth_as_metadata`, `oauth_register_proxy`, `oauth_token_endpoint`, `_oauth_callback_as_proxy`. Modified: `oauth_authorize` (intermediary pattern), `oauth_callback` (AS proxy routing) |
+| `nextcloud_mcp_server/app.py` | New routes, PRM `authorization_servers` → MCP server URL, `app.state.supported_scopes` |
+| `nextcloud_mcp_server/auth/client_registry.py` | New: `register_proxy_client()`, wildcard scope support |
+
+## Consequences
+
+### Positive
+
+- Tokens always have the correct audience — `_has_mcp_audience()` passes
+- Works with any MCP client that implements RFC 9728 (PRM) discovery
+- No changes needed to Nextcloud's OIDC configuration
+- DCR still works transparently (clients register via proxy)
+- Existing Flow 2 (resource provisioning) and browser login are unaffected
+
+### Negative
+
+- MCP server is now stateful during the OAuth flow (in-memory proxy codes)
+- Extra network hop for token exchange (MCP server → Nextcloud → back)
+- Token refresh requires proxying through the MCP server
+- Single-instance limitation for proxy code storage (acceptable for current deployment model)
+
+### Risks
+
+- In-memory proxy codes are lost on server restart (mitigated by 60s TTL — user just retries)
+- Discovery endpoint fetch during OAuth flow adds latency (could be cached)
+
+## References
+
+- [RFC 8414 — OAuth 2.0 Authorization Server Metadata](https://tools.ietf.org/html/rfc8414)
+- [RFC 9728 — OAuth 2.0 Protected Resource Metadata](https://tools.ietf.org/html/rfc9728)
+- [RFC 7636 — PKCE](https://tools.ietf.org/html/rfc7636)
+- [RFC 7591 — Dynamic Client Registration](https://tools.ietf.org/html/rfc7591)
+- ADR-004 — MCP Application OAuth (progressive consent architecture)
+- ADR-005 — Token Audience Validation

docs/CRITICAL-TOKEN-EXCHANGE-PATTERN.md

@@ -0,0 +1,348 @@
+# Token Acquisition Patterns for ADR-004 Progressive Consent
+
+## Overview
+
+ADR-004 Progressive Consent establishes the authorization architecture (Flow 1 for client auth, Flow 2 for resource provisioning). This document describes **how tokens are acquired for different operational contexts** within that architecture.
+
+**Key Principle**: Refresh tokens from Flow 2 (Progressive Consent) should **NEVER** be used for MCP tool calls - they are exclusively for background jobs.
+
+## Implementation Status
+
+**Current Status**: ✅ Token exchange infrastructure implemented, available as opt-in feature
+
+The MCP server supports two token acquisition modes:
+1. **Pass-through mode** (default, `ENABLE_TOKEN_EXCHANGE=false`): Simple, stateless
+2. **Token exchange mode** (opt-in, `ENABLE_TOKEN_EXCHANGE=true`): Enhanced security with token delegation
+
+Both modes maintain the critical separation: **refresh tokens are never used for tool calls**.
+
+## Current Default (Pass-Through Mode)
+
+### What Happens (ENABLE_TOKEN_EXCHANGE=false):
+1. Client gets Flow 1 token (`aud: "mcp-server"`)
+2. Client calls MCP tool
+3. Server validates Flow 1 token
+4. Server passes Flow 1 token to Nextcloud
+5. Nextcloud validates token with IdP
+6. Refresh tokens (from Flow 2) used **only** for background jobs
+
+### Characteristics:
+- ✅ Simple, stateless operation
+- ✅ Clear separation: Flow 1 tokens for sessions, refresh tokens for background
+- ✅ Lower latency (no token exchange round-trip)
+- ✅ Works with any OAuth IdP
+
+## Optional Token Exchange Mode
+
+### Token Exchange Pattern (ENABLE_TOKEN_EXCHANGE=true)
+
+**MCP Session (Foreground Operations)**:
+
+```
+┌─────────────┐     Flow 1 Token      ┌──────────────┐
+│  MCP Client │ ───(aud: mcp-server)──> │  MCP Server  │
+└─────────────┘                        └──────────────┘
+                                              │
+                    Tool Call                 │
+                    "search_notes()"          │
+                                              ▼
+                                    ┌─────────────────────┐
+                                    │ Token Exchange      │
+                                    │ 1. Validate Flow 1  │
+                                    │ 2. Check permission │
+                                    │ 3. Request delegated│
+                                    │    Nextcloud token  │
+                                    └─────────────────────┘
+                                              │
+                                              │ Exchange Request
+                                              ▼
+                                    ┌─────────────────────┐
+                                    │ IdP Token Endpoint  │
+                                    │ (Token Exchange)    │
+                                    └─────────────────────┘
+                                              │
+                                              │ Delegated Token
+                                              │ (aud: nextcloud)
+                                              │ (limited scopes)
+                                              │ (short-lived)
+                                              ▼
+                                    ┌─────────────────────┐
+                                    │ Nextcloud API Call  │
+                                    │ GET /notes          │
+                                    └─────────────────────┘
+```
+
+**Key Properties of Session Tokens:**
+- ✅ Generated **on-demand** during tool execution
+- ✅ **Ephemeral** - used only for current operation
+- ✅ **NOT stored** - discarded after use
+- ✅ **Limited scopes** - only what tool needs (e.g., `notes:read` for search)
+- ✅ **Short-lived** - expires quickly (e.g., 5 minutes)
+
+**Background Jobs (Offline Operations)**:
+
+```
+┌─────────────────┐     Scheduled Job      ┌──────────────┐
+│ Background      │ ──────────────────────> │  Worker      │
+│ Scheduler       │                         │  Process     │
+└─────────────────┘                         └──────────────┘
+                                                    │
+                                                    │ Use stored
+                                                    │ refresh token
+                                                    ▼
+                                          ┌─────────────────────┐
+                                          │ Refresh Token Store │
+                                          │ (Flow 2 provisioned)│
+                                          └─────────────────────┘
+                                                    │
+                                                    │ Refresh Token
+                                                    ▼
+                                          ┌─────────────────────┐
+                                          │ IdP Token Endpoint  │
+                                          │ (Refresh Grant)     │
+                                          └─────────────────────┘
+                                                    │
+                                                    │ Background Token
+                                                    │ (aud: nextcloud)
+                                                    │ (different scopes)
+                                                    │ (longer-lived)
+                                                    ▼
+                                          ┌─────────────────────┐
+                                          │ Nextcloud API       │
+                                          │ (Background Sync)   │
+                                          └─────────────────────┘
+```
+
+**Key Properties of Background Tokens:**
+- ✅ Obtained from **stored refresh token** (Flow 2)
+- ✅ **Different scopes** than session tokens (e.g., `notes:sync`, `files:sync`)
+- ✅ **Longer-lived** for background operations
+- ✅ **Never used for MCP sessions**
+- ✅ **Only for offline/background jobs**
+
+## Implementation Requirements
+
+### 1. Token Exchange Endpoint
+
+Implement RFC 8693 Token Exchange:
+
+```python
+# nextcloud_mcp_server/auth/token_exchange.py
+
+async def exchange_token_for_delegation(
+    flow1_token: str,
+    requested_audience: str = "nextcloud",
+    requested_scopes: list[str] | None = None
+) -> tuple[str, int]:
+    """
+    Exchange Flow 1 MCP token for delegated Nextcloud token.
+
+    This implements RFC 8693 Token Exchange for on-behalf-of delegation.
+
+    IMPORTANT: Nextcloud doesn't support OAuth scopes natively. Scopes are
+    soft-scopes enforced by the MCP server via @require_scopes decorator,
+    not by the IdP or Nextcloud. Therefore, requested_scopes are not passed
+    to the IdP during token exchange.
+
+    Args:
+        flow1_token: The MCP session token (aud: "mcp-server")
+        requested_audience: Target audience (usually "nextcloud")
+        requested_scopes: Ignored (Nextcloud doesn't support scopes)
+
+    Returns:
+        Tuple of (delegated_token, expires_in)
+    """
+    # 1. Validate Flow 1 token (audience check)
+    # 2. Check user has provisioned Nextcloud access (Flow 2)
+    # 3. Request token exchange from IdP (without scopes - Nextcloud doesn't support them)
+    # 4. Return ephemeral delegated token
+```
+
+### 2. Unified get_client() Pattern
+
+The token acquisition mode is handled transparently by `get_client()`:
+
+```python
+# nextcloud_mcp_server/context.py
+
+async def get_client(ctx: Context) -> NextcloudClient:
+    """
+    Get the appropriate Nextcloud client based on authentication mode.
+
+    This function handles three modes:
+    1. BasicAuth mode: Returns shared client from lifespan context
+    2. OAuth pass-through mode (ENABLE_TOKEN_EXCHANGE=false, default):
+       Verifies Flow 1 token and passes it to Nextcloud
+    3. OAuth token exchange mode (ENABLE_TOKEN_EXCHANGE=true):
+       Exchanges Flow 1 token for ephemeral Nextcloud token via RFC 8693
+    """
+    settings = get_settings()
+    lifespan_ctx = ctx.request_context.lifespan_context
+
+    # BasicAuth mode - use shared client (no token exchange)
+    if hasattr(lifespan_ctx, "client"):
+        return lifespan_ctx.client
+
+    # OAuth mode (has 'nextcloud_host' attribute)
+    if hasattr(lifespan_ctx, "nextcloud_host"):
+        # Check if token exchange is enabled
+        if settings.enable_token_exchange:
+            # Token exchange mode: Exchange Flow 1 token for ephemeral Nextcloud token
+            return await get_session_client_from_context(
+                ctx, lifespan_ctx.nextcloud_host
+            )
+        else:
+            # Pass-through mode (default): Verify and pass Flow 1 token to Nextcloud
+            return get_client_from_context(ctx, lifespan_ctx.nextcloud_host)
+```
+
+### 3. MCP Tool Pattern (No Changes Required!)
+
+Tools use the same pattern regardless of token acquisition mode:
+
+```python
+@mcp.tool()
+@require_scopes("notes:read")  # Soft-scope enforced by MCP server, not Nextcloud
+@require_provisioning
+async def nc_notes_search_notes(query: str, ctx: Context) -> SearchNotesResponse:
+    """Search notes by title or content."""
+
+    # get_client() handles both pass-through and token exchange modes
+    client = await get_client(ctx)
+
+    # Execute operation
+    results = await client.notes.search_notes(query=query)
+
+    # In token exchange mode, ephemeral token is automatically discarded
+    # In pass-through mode, Flow 1 token was validated and passed through
+    return SearchNotesResponse(results=results)
+```
+
+**Key Benefit**: Tools don't need to know which mode is active. The token acquisition pattern is configured at the server level via `ENABLE_TOKEN_EXCHANGE`.
+
+### 4. Background Job Pattern
+
+Background jobs use a **different token acquisition pattern** - they use refresh tokens from Flow 2:
+
+```python
+# Background worker
+async def sync_notes_job(user_id: str):
+    """Background job to sync notes."""
+
+    # Get refresh token stored during Flow 2 (Progressive Consent)
+    token_storage = get_token_storage()
+    refresh_token = await token_storage.get_refresh_token(user_id)
+
+    if not refresh_token:
+        logger.warning(f"No refresh token for user {user_id}")
+        return
+
+    # Use refresh token to get Nextcloud access token
+    idp_client = get_idp_client()
+    response = await idp_client.refresh_token(
+        refresh_token=refresh_token,
+        audience='nextcloud'
+    )
+
+    # Create client with background token (can be cached)
+    client = NextcloudClient.from_token(
+        base_url=NEXTCLOUD_HOST,
+        token=response.access_token,
+        username=user_id
+    )
+
+    # Perform background sync
+    await client.notes.sync_all()
+```
+
+**Key differences from tool calls:**
+- Uses refresh tokens from Flow 2 (Progressive Consent provisioning)
+- Tokens can be cached for efficiency (longer-lived operations)
+- No user interaction possible (offline)
+- Never triggered during MCP tool execution
+
+## Security Benefits
+
+### Proper Token Exchange:
+1. ✅ **Least Privilege**: Each operation gets only needed scopes
+2. ✅ **Time-Limited**: Session tokens expire quickly
+3. ✅ **Audit Trail**: Each exchange can be logged
+4. ✅ **Token Isolation**: Session ≠ Background tokens
+5. ✅ **Revocation**: Can revoke background access without affecting active sessions
+
+### Current Incorrect Pattern:
+1. ❌ **Over-Privileged**: Refresh token has all scopes
+2. ❌ **Long-Lived**: Same token reused indefinitely
+3. ❌ **No Separation**: Sessions and background jobs use same credential
+4. ❌ **Revocation Issues**: Revoking affects everything
+
+## Implementation Steps
+
+### Phase 1: Token Exchange (High Priority)
+1. Implement RFC 8693 token exchange endpoint
+2. Update Token Broker with `get_session_token()` vs `get_background_token()`
+3. Modify tool pattern to use token exchange
+
+### Phase 2: Scope Separation (High Priority)
+1. Define session scopes vs background scopes
+2. Update provisioning flow to request appropriate scopes
+3. Validate scopes in token exchange
+
+### Phase 3: Background Jobs (Medium Priority)
+1. Implement background worker pattern
+2. Create scheduled jobs (note sync, etc.)
+3. Use background token pattern
+
+### Phase 4: Testing (High Priority)
+1. Test token exchange flow end-to-end
+2. Verify session tokens are ephemeral
+3. Verify background tokens are separate
+4. Load test token exchange performance
+
+## References
+
+- **RFC 8693**: OAuth 2.0 Token Exchange
+- **RFC 9068**: JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens
+- **ADR-004**: Progressive Consent OAuth Flows
+- **OAuth 2.0 Delegation**: On-Behalf-Of vs Impersonation patterns
+
+## Status
+
+**Current Status**: ✅ Token exchange infrastructure implemented, available as opt-in feature
+**Modes Available**:
+- ✅ Pass-through mode (default, `ENABLE_TOKEN_EXCHANGE=false`): Simple, stateless
+- ✅ Token exchange mode (opt-in, `ENABLE_TOKEN_EXCHANGE=true`): Enhanced security
+
+**Implementation Complete**:
+- ✅ `token_exchange.py` module with RFC 8693 support
+- ✅ Fallback to refresh grant when RFC 8693 not supported
+- ✅ `get_client()` unified pattern (handles both modes transparently)
+- ✅ Tokens never cached in token exchange mode (ephemeral)
+- ✅ Background jobs use separate pattern (refresh tokens from Flow 2)
+
+## Configuration
+
+To enable token exchange mode:
+
+```bash
+# docker-compose.yml or .env
+ENABLE_TOKEN_EXCHANGE=true
+```
+
+When enabled, all MCP tool calls will use token exchange (RFC 8693) to obtain ephemeral Nextcloud tokens. When disabled (default), Flow 1 tokens are passed through to Nextcloud.
+
+## Nextcloud Scope Limitation
+
+**IMPORTANT**: Nextcloud does not support OAuth scopes natively. Scopes like "notes:read" are **soft-scopes** enforced by the MCP server via `@require_scopes` decorator, not by the IdP or Nextcloud.
+
+This means:
+- Token exchange provides audit and delegation benefits, not scope restriction
+- All Nextcloud tokens have equivalent permissions at the Nextcloud level
+- Fine-grained access control is enforced by MCP server, not Nextcloud
+
+## Next Actions (Optional Enhancements)
+
+1. [ ] Add integration tests for token exchange mode with actual MCP tools
+2. [ ] Document background job patterns for scheduled sync operations
+3. [ ] Add metrics for token exchange performance
+4. [ ] Consider making token exchange the default in future major version

docs/MCP-1.23-DNS-REBINDING-FIX.md

@@ -0,0 +1,104 @@
+# MCP 1.23.x DNS Rebinding Protection Fix
+
+## Problem
+
+MCP Python SDK 1.23.0 introduced **automatic DNS rebinding protection** that breaks containerized deployments (Kubernetes, Docker) when the protection is unintentionally auto-enabled.
+
+### Root Cause
+
+From `mcp/server/fastmcp/server.py:177-183` in the Python SDK:
+
+```python
+# Auto-enable DNS rebinding protection for localhost (IPv4 and IPv6)
+if transport_security is None and host in ("127.0.0.1", "localhost", "::1"):
+    transport_security = TransportSecuritySettings(
+        enable_dns_rebinding_protection=True,
+        allowed_hosts=["127.0.0.1:*", "localhost:*", "[::1]:*"],
+        allowed_origins=["http://127.0.0.1:*", "http://localhost:*", "http://[::1]:*"],
+    )
+```
+
+### What Was Happening
+
+1. **FastMCP initialization** in `app.py` didn't pass `host` or `transport_security` parameters
+2. **Defaults applied**: `host="127.0.0.1"`, `transport_security=None`
+3. **Auto-enablement triggered**: Condition `transport_security is None and host == "127.0.0.1"` was TRUE
+4. **Protection activated** with `allowed_hosts=["127.0.0.1:*", "localhost:*", "[::1]:*"]`
+5. **Kubernetes requests rejected**: `Host: nextcloud-mcp-server.default.svc.cluster.local:8000` didn't match allowed hosts
+
+### Why `--host 0.0.0.0` Didn't Help
+
+The `--host` CLI flag (used in Dockerfile/docker-compose) controls **uvicorn's bind address**, NOT the **FastMCP `host` parameter**. These are separate concerns:
+
+- **Uvicorn bind address** (`--host 0.0.0.0`): Where the HTTP server listens
+- **FastMCP host parameter** (defaulted to `"127.0.0.1"`): Used for auto-enablement logic
+
+## Solution
+
+Explicitly disable DNS rebinding protection by passing `transport_security=TransportSecuritySettings(enable_dns_rebinding_protection=False)` to all FastMCP instances.
+
+### Changes Made
+
+Modified `nextcloud_mcp_server/app.py`:
+
+1. **Import** `TransportSecuritySettings` from `mcp.server.transport_security`
+2. **Updated all three FastMCP initializations**:
+   - OAuth mode (line 1015)
+   - Smithery stateless mode (line 1030)
+   - BasicAuth mode (line 1040)
+
+Each now includes:
+```python
+transport_security=TransportSecuritySettings(enable_dns_rebinding_protection=False)
+```
+
+## Impact
+
+### ✅ What This Fixes
+
+- **Kubernetes deployments**: Requests with k8s service DNS names now work
+- **Docker deployments**: Port-mapped requests (localhost:8000 → container) now work
+- **Reverse proxy deployments**: Proxied requests with various Host headers now work
+- **Ingress controllers**: Requests via ingress hostnames now work
+
+### 🔒 Security Considerations
+
+DNS rebinding protection defends against attacks where:
+1. Attacker controls a DNS domain (e.g., `evil.com`)
+2. DNS initially resolves to attacker's IP
+3. After victim's browser caches the origin, DNS changes to victim's localhost
+4. Attacker's page can now make requests to victim's localhost services
+
+**Why it's safe to disable for this deployment:**
+
+1. **OAuth authentication required** in production deployments (ADR-002, ADR-004)
+2. **Network-level isolation** in containerized environments (k8s network policies, Docker networks)
+3. **MCP is server-to-server**, not exposed to browsers (no CORS concerns)
+4. **Host header validation inappropriate** for multi-tenant k8s environments
+
+If DNS rebinding protection is needed for specific deployments, it can be re-enabled with a custom allowed hosts list:
+
+```python
+transport_security=TransportSecuritySettings(
+    enable_dns_rebinding_protection=True,
+    allowed_hosts=[
+        "nextcloud-mcp-server.default.svc.cluster.local:*",
+        "mcp.example.com:*",
+        # Add all your expected Host header values
+    ]
+)
+```
+
+## Testing
+
+- ✅ Ruff linting passes
+- ✅ Type checking passes (pre-existing warnings unrelated)
+- ✅ Module imports successfully
+- ✅ Compatible with MCP 1.23.x
+
+## References
+
+- [MCP Python SDK 1.23.0 Release](https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.23.0)
+- Commit: `d3a1841` - "Auto-enable DNS rebinding protection for localhost servers"
+- Issue #373 (original report of k8s breakage)
+- PR #382 (MCP 1.23.x upgrade)

docs/audience-validation-setup.md

@@ -0,0 +1,521 @@
+# Audience Validation Setup
+
+## Overview
+
+This document explains the **separate clients architecture** for Keycloak → MCP Server → Nextcloud integration, following OAuth 2.0 best practices and RFC 8707 (Resource Indicators).
+
+## Architecture: Separate Clients Pattern
+
+```
+Keycloak Realm: nextcloud-mcp
+├── Client: "nextcloud" (Resource Server)
+│   └── Represents Nextcloud as a protected resource
+│   └── Used by user_oidc for bearer token validation
+│   └── Validates tokens with aud="nextcloud"
+│
+└── Client: "nextcloud-mcp-server" (OAuth Client)
+    └── MCP Server uses this to REQUEST tokens
+    └── Issues tokens with aud="nextcloud" (targeting resource)
+    └── Future: aud=["nextcloud", "other-service"]
+
+Token Flow:
+MCP Server (client: nextcloud-mcp-server)
+  ↓ requests token from Keycloak
+Token issued:
+  - aud: "nextcloud"             (intended for Nextcloud resource)
+  - azp: "nextcloud-mcp-server"  (requested by MCP Server)
+  - preferred_username: "admin"  (on behalf of user)
+  ↓ sent to Nextcloud API
+Nextcloud user_oidc (client: nextcloud)
+  ✓ validates aud matches configured client_id
+```
+
+**Key Benefits**:
+- ✅ **Proper OAuth separation**: OAuth client ≠ resource server
+- ✅ **Future extensibility**: MCP Server can request multi-resource tokens
+- ✅ **RFC 8707 compliance**: Audience indicates intended resource
+- ✅ **Clear requester identification**: azp claim identifies MCP Server
+
+## Token Claims
+
+Tokens issued by the `nextcloud-mcp-server` client contain:
+
+- **`aud: "nextcloud"`** - Audience: Token intended for Nextcloud resource server (matches user_oidc client_id)
+- **`azp: "nextcloud-mcp-server"`** - Authorized Party: Identifies MCP Server as the OAuth client that requested the token
+- **`preferred_username: "admin"`** - User identifier (Keycloak uses this for password grant; `sub` for authorization_code grant)
+- **`scope: "openid profile email offline_access"`** - Requested scopes including offline access for background jobs
+
+**How user_oidc Validates**:
+1. SelfEncodedValidator checks: `aud == user_oidc.client_id`?
+   - ✓ "nextcloud" == "nextcloud" → PASS
+2. Fast JWT verification with JWKS (no HTTP call to userinfo endpoint)
+3. User provisioned based on `preferred_username` or `sub` claim
+
+**For Background Jobs**:
+- MCP Server stores encrypted refresh tokens
+- Refreshes access tokens when needed
+- All tokens have `aud: "nextcloud"` → validated by user_oidc
+- No admin credentials required
+
+## Configuration
+
+The configuration requires **two separate clients** in Keycloak:
+
+1. **`nextcloud`** - Resource server client (for user_oidc validation)
+2. **`nextcloud-mcp-server`** - OAuth client (for MCP Server to request tokens)
+
+### 1. Keycloak - Create Resource Server Client
+
+First, create the `nextcloud` client that represents Nextcloud as a resource server:
+
+**Via Keycloak Admin API:**
+
+```bash
+# Get admin token
+ADMIN_TOKEN=$(curl -X POST "http://localhost:8888/realms/master/protocol/openid-connect/token" \
+  -d "grant_type=password" \
+  -d "client_id=admin-cli" \
+  -d "username=admin" \
+  -d "password=admin" | jq -r '.access_token')
+
+# Create 'nextcloud' resource server client
+curl -X POST "http://localhost:8888/admin/realms/nextcloud-mcp/clients" \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "clientId": "nextcloud",
+    "name": "Nextcloud Resource Server",
+    "description": "Resource server for Nextcloud APIs - used by user_oidc for bearer token validation",
+    "enabled": true,
+    "clientAuthenticatorType": "client-secret",
+    "secret": "nextcloud-secret-change-in-production",
+    "bearerOnly": true,
+    "standardFlowEnabled": false,
+    "directAccessGrantsEnabled": false,
+    "serviceAccountsEnabled": false,
+    "publicClient": false
+  }'
+```
+
+**Via Realm Export** (`keycloak/realm-export.json`):
+
+```json
+{
+  "clients": [
+    {
+      "clientId": "nextcloud",
+      "name": "Nextcloud Resource Server",
+      "enabled": true,
+      "bearerOnly": true,
+      "secret": "nextcloud-secret-change-in-production"
+    }
+  ]
+}
+```
+
+### 2. Keycloak - Create OAuth Client with Audience Mapper
+
+Next, create the `nextcloud-mcp-server` client that MCP Server uses to request tokens:
+
+**Via Keycloak Admin API:**
+
+```bash
+# Create 'nextcloud-mcp-server' OAuth client
+curl -X POST "http://localhost:8888/admin/realms/nextcloud-mcp/clients" \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "clientId": "nextcloud-mcp-server",
+    "name": "Nextcloud MCP Server",
+    "enabled": true,
+    "clientAuthenticatorType": "client-secret",
+    "secret": "mcp-secret-change-in-production",
+    "standardFlowEnabled": true,
+    "directAccessGrantsEnabled": true,
+    "redirectUris": ["http://localhost:*/callback"]
+  }'
+
+# Get client internal ID
+CLIENT_ID=$(curl "http://localhost:8888/admin/realms/nextcloud-mcp/clients" \
+  -H "Authorization: Bearer $ADMIN_TOKEN" | jq -r '.[] | select(.clientId=="nextcloud-mcp-server") | .id')
+
+# Add audience mapper targeting 'nextcloud' resource
+curl -X POST "http://localhost:8888/admin/realms/nextcloud-mcp/clients/$CLIENT_ID/protocol-mappers/models" \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "audience-nextcloud",
+    "protocol": "openid-connect",
+    "protocolMapper": "oidc-audience-mapper",
+    "consentRequired": false,
+    "config": {
+      "included.custom.audience": "nextcloud",
+      "access.token.claim": "true",
+      "id.token.claim": "false"
+    }
+  }'
+```
+
+**Option B: Via Realm Export** (for infrastructure-as-code)
+
+Update `keycloak/realm-export.json`:
+
+```json
+{
+  "clients": [
+    {
+      "clientId": "nextcloud-mcp-server",
+      "name": "Nextcloud MCP Server",
+      "protocolMappers": [
+        {
+          "name": "audience-nextcloud-mcp-server",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-audience-mapper",
+          "consentRequired": false,
+          "config": {
+            "included.custom.audience": "nextcloud-mcp-server",
+            "access.token.claim": "true",
+            "id.token.claim": "false"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+Then re-import realm or restart Keycloak.
+
+**Option C: Via Keycloak Admin UI**
+
+1. Go to Keycloak Admin Console → Realm → Clients → `nextcloud-mcp-server`
+2. Click "Client scopes" tab
+3. Click "Add client scope" → "Create dedicated scope"
+4. Add protocol mapper: "Audience"
+   - Mapper Type: `Audience`
+   - Included Custom Audience: `nextcloud`
+   - Add to access token: ON
+   - Add to ID token: OFF
+
+### 3. Nextcloud user_oidc - Configure Resource Server Client
+
+Configure user_oidc to use the `nextcloud` resource server client:
+
+```bash
+docker compose exec app php occ user_oidc:provider keycloak \
+  --clientid="nextcloud" \
+  --clientsecret="nextcloud-secret-change-in-production" \
+  --discoveryuri="http://keycloak:8080/realms/nextcloud-mcp/.well-known/openid-configuration" \
+  --check-bearer=1 \
+  --bearer-provisioning=1 \
+  --unique-uid=1 \
+  --mapping-uid="sub" \
+  --mapping-display-name="name" \
+  --mapping-email="email"
+```
+
+**Result**: user_oidc validates tokens with `aud="nextcloud"` using SelfEncodedValidator (fast JWT verification).
+
+### 3. Nextcloud user_oidc - Realm-Level Validation
+
+Nextcloud's `user_oidc` app validates at **realm level** via userinfo endpoint:
+
+- ✅ **No configuration needed** - works automatically
+- ✅ Validates any token from Keycloak realm
+- ✅ Audience check is **optional** (disabled by default)
+
+**Optional: Disable strict audience checking** (if enabled):
+
+```bash
+docker compose exec app php occ config:app:set user_oidc \
+  selfencoded_bearer_validation_audience_check --value=false --type=boolean
+```
+
+## Verification
+
+### 1. Check Token Claims
+
+```bash
+# Get token from Keycloak
+TOKEN=$(curl -X POST "http://localhost:8888/realms/nextcloud-mcp/protocol/openid-connect/token" \
+  -d "grant_type=password" \
+  -d "client_id=nextcloud-mcp-server" \
+  -d "client_secret=mcp-secret-change-in-production" \
+  -d "username=admin" \
+  -d "password=admin" | jq -r '.access_token')
+
+# Decode JWT
+echo $TOKEN | cut -d'.' -f2 | base64 -d | jq '.'
+
+# Should show:
+{
+  "aud": "nextcloud",  # ✓ Intended for Nextcloud
+  "azp": "nextcloud-mcp-server",  # ✓ Requested by MCP Server
+  "iss": "http://localhost:8888/realms/nextcloud-mcp",
+  "scope": "openid email profile offline_access",
+  ...
+}
+```
+
+### 2. Test with Nextcloud API
+
+```bash
+# Token should be accepted
+curl -H "Authorization: Bearer $TOKEN" \
+  "http://localhost:8080/ocs/v2.php/cloud/capabilities"
+
+# Should return HTTP 200 OK
+```
+
+### 3. Test Audience Rejection
+
+```bash
+# Get token from different client (without audience mappers)
+TOKEN_WRONG=$(curl -X POST "http://localhost:8888/realms/nextcloud-mcp/protocol/openid-connect/token" \
+  -d "grant_type=password" \
+  -d "client_id=test-client-b" \
+  -d "client_secret=test-secret-b" \
+  -d "username=admin" \
+  -d "password=admin" | jq -r '.access_token')
+
+# This token has NO audience claim - should be rejected by MCP server
+# (But accepted by Nextcloud user_oidc which validates at realm level)
+```
+
+## Token Flow Example
+
+### Successful Request (Background Job)
+
+```
+1. User authorizes MCP Client via OAuth
+   └─ MCP Server gets refresh token (stored encrypted)
+
+2. Background worker needs to sync data
+   └─ MCP Server refreshes access token from Keycloak
+   └─ Token issued with aud: "nextcloud", azp: "nextcloud-mcp-server"
+
+3. MCP Server → Nextcloud API (with token)
+   └─ user_oidc validates via userinfo endpoint ✓
+   └─ Nextcloud identifies:
+       - Token intended for Nextcloud (aud: "nextcloud")
+       - Request from MCP Server (azp: "nextcloud-mcp-server")
+       - On behalf of user (sub: "user-id")
+
+4. Success! MCP Server can act on behalf of user in background.
+```
+
+### Rejected Request
+
+```
+1. Attacker gets token for different client
+   └─ Token has aud: "other-service"
+
+2. Attacker → Nextcloud API (with wrong token)
+   └─ user_oidc validates via userinfo endpoint
+   └─ Token validation fails (invalid/expired/wrong realm)
+   └─ HTTP 401 Unauthorized
+
+3. Request blocked - token not valid for this realm/service
+```
+
+## OAuth Flows and User Consent
+
+### When Does the User Grant Consent?
+
+User consent happens during the **Authorization Code Flow** (production OAuth):
+
+```
+1. User clicks "Connect" in MCP Client (e.g., Claude Desktop)
+2. MCP Client initiates OAuth flow by opening browser to Keycloak:
+   https://keycloak/realms/nextcloud-mcp/protocol/openid-connect/auth?
+     client_id=nextcloud-mcp-server&
+     redirect_uri=<mcp-client-redirect-uri>&
+     response_type=code&
+     scope=openid profile email offline_access
+
+3. Keycloak shows login screen (if not logged in)
+4. **Keycloak shows consent screen:**
+   "Nextcloud MCP Server wants to access your Nextcloud data on your behalf"
+   Requested permissions:
+   - Access your profile (openid, profile, email)
+   - Offline access (background operations with refresh tokens)
+
+5. User clicks "Allow" → grants consent
+6. Keycloak redirects back to MCP Client with authorization code
+7. MCP Client exchanges code for tokens (receives access + refresh tokens)
+8. MCP Client shares tokens with MCP Server via MCP protocol
+9. MCP Server stores refresh token encrypted for background operations
+```
+
+**Key Architecture Notes:**
+- **MCP Server is a protected resource** (requires OAuth to access)
+- **MCP Client** (Claude Desktop) is the OAuth client that initiates the flow
+- **MCP Client handles the redirect** and token exchange with Keycloak
+- **MCP Client shares refresh token** with MCP Server so it can act on behalf of user in background
+
+**Key Points:**
+- ✅ **Explicit user consent** before any access
+- ✅ **Scopes displayed** so user knows what's being requested
+- ✅ **Offline access** must be explicitly granted (for background jobs)
+- ✅ **Revocable** - user can revoke consent in Keycloak at any time
+
+### Grant Types
+
+Our architecture supports multiple OAuth grant types:
+
+**1. Authorization Code + PKCE (Production)**
+```
+Use case: Interactive login from MCP clients
+Consent: Yes - explicit user authorization
+Tokens: Access token + Refresh token (if offline_access granted)
+Security: PKCE prevents authorization code interception
+```
+
+**2. Password Grant (Testing Only)**
+```
+Use case: Integration testing with docker-compose
+Consent: No - username/password provided directly
+Tokens: Access token + Refresh token
+Security: NOT for production - exposes user credentials
+```
+
+**3. Refresh Token Grant (Background Jobs)**
+```
+Use case: MCP Server refreshing expired access tokens
+Consent: No new consent - uses previously granted refresh token
+Tokens: New access token (refresh token may rotate)
+Security: Refresh tokens stored encrypted, rotated on use
+```
+
+## Authentication Strategies for Background Jobs
+
+> **Note on Service Account Tokens**: Service account tokens (`client_credentials` grant) were evaluated but **rejected** as they create Nextcloud user accounts (e.g., `service-account-{client_id}`) which violates OAuth "act on-behalf-of" principles. See ADR-002 "Will Not Implement" section for details.
+
+### Current Approach: Offline Access with Refresh Tokens
+
+The MCP server uses **offline_access** scope to enable background operations:
+
+**How it works:**
+1. User grants `offline_access` scope during OAuth consent
+2. MCP Client receives refresh token from Keycloak
+3. MCP Client shares refresh token with MCP Server via MCP protocol
+4. MCP Server stores refresh token encrypted (see ADR-002)
+5. Background jobs exchange refresh token for fresh access tokens as needed
+
+**Benefits:**
+- ✅ Works today with Keycloak and all OIDC providers
+- ✅ Standard OAuth pattern (RFC 6749)
+- ✅ Explicit user consent to `offline_access` scope
+- ✅ MCP Server can act on behalf of user in background
+
+**Limitations:**
+- ⚠️ Requires secure token storage on MCP Server
+- ⚠️ MCP Client must trust MCP Server with refresh token
+- ⚠️ Weak audit trail - API requests appear to come from user directly
+- ⚠️ No visibility that MCP Server is the actual actor
+
+### Token Exchange with Delegation (ADR-002 Tier 2 - Implemented)
+
+**RFC 8693 Delegation** would provide better audit trail and security:
+
+**How it would work:**
+1. User grants `may_act:nextcloud-mcp-server` scope during authentication
+2. Subject token includes: `{ "may_act": { "client": "nextcloud-mcp-server" } }`
+3. MCP Server has its own service account token (actor_token)
+4. Background job requests token exchange:
+   - `subject_token` (user's token with may_act claim)
+   - `actor_token` (mcp-server's service token)
+5. Keycloak validates actor matches may_act claim
+6. Returns delegated token: `{ "sub": "user", "act": "nextcloud-mcp-server" }`
+
+**Benefits:**
+- ✅ Better audit trail - Nextcloud APIs see both user and actor
+- ✅ No token storage needed (tokens generated on-demand)
+- ✅ Fine-grained permissions via `may_act` claim
+- ✅ User explicitly consents to MCP Server acting on their behalf
+- ✅ RFC 8693 compliant
+
+**Current Status:**
+- ❌ **NOT implemented in Keycloak yet** ([Issue #38279](https://github.com/keycloak/keycloak/issues/38279))
+- ❌ Would require custom implementation or waiting for upstream
+- 📝 Proposal includes `act` claim and `may_act` consent mechanism
+
+**Why Not Available:**
+- Keycloak supports **impersonation** (changes `sub` claim), but not **delegation** (`act` claim)
+- Impersonation has poor audit trail (actor invisible)
+- Delegation proposal is open but not implemented yet
+
+**Reference:** See `docs/ADR-002-vector-sync-authentication.md` for detailed comparison of authentication tiers.
+
+## Security Benefits
+
+1. **Intent Validation**: Tokens explicitly declare Nextcloud as the intended recipient via `aud` claim
+2. **Requester Identification**: The `azp` claim identifies MCP Server as the requester
+3. **User Context**: The `sub` claim preserves user identity for audit and authorization
+4. **Background Jobs**: Refresh tokens enable MCP Server to act on behalf of users without admin credentials
+5. **OAuth Standards**: Follows RFC 8707 (Resource Indicators) and RFC 6749 (OAuth 2.0)
+
+**Current Limitations:**
+- API requests from background jobs appear to come from user directly (no `act` claim yet)
+- See "Authentication Strategies for Background Jobs" section for future delegation support
+
+## Token Claims
+
+### Key Claims
+
+- **`aud: "nextcloud"`** - Audience: Token intended for Nextcloud APIs
+- **`azp: "nextcloud-mcp-server"`** - Authorized Party: MCP Server requested the token
+- **`sub: "user-id"`** - Subject: User on whose behalf the request is made
+- **`scope: "openid profile email offline_access"`** - Requested scopes including offline access for background jobs
+
+### Client Naming
+
+The Keycloak client is named `nextcloud-mcp-server` to clarify:
+- **MCP Server** uses this client to get tokens for Nextcloud
+- **MCP Clients** (like Claude Desktop) connect to MCP Server via separate OAuth flows
+- **Not** named "mcp-client" to avoid confusion about which component is the client
+
+## Troubleshooting
+
+### Token Has No Audience
+
+**Symptom**: `"aud": null` in decoded JWT
+
+**Cause**: Protocol mappers not configured
+
+**Solution**: Add audience mappers via Keycloak Admin API (see Configuration section)
+
+### MCP Server Rejects Token
+
+**Symptom**: HTTP 401 with "JWT validation failed"
+
+**Cause**: Token audience doesn't match expected value
+
+**Solution**:
+1. Check token has correct `aud` claim
+2. Verify MCP server expects correct audience value in code
+3. Check logs for specific JWT validation error
+
+### Nextcloud Rejects Token
+
+**Symptom**: HTTP 401 from Nextcloud API
+
+**Cause**: User not provisioned or token invalid
+
+**Solution**:
+1. Check user_oidc provider is configured: `php occ user_oidc:provider keycloak`
+2. Check bearer validation enabled: `--check-bearer=1`
+3. Test token with userinfo endpoint: `curl -H "Authorization: Bearer $TOKEN" http://keycloak/realms/.../userinfo`
+
+## Related Documentation
+
+- **Multi-client validation**: `docs/keycloak-multi-client-validation.md`
+- **ADR-002**: `docs/ADR-002-vector-sync-authentication.md`
+- **OAuth setup**: `docs/oauth-setup.md`
+- **Keycloak integration**: `docs/keycloak-integration.md` (if created)
+
+## References
+
+- [RFC 8707 - Resource Indicators for OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)
+- [OIDC Core - ID Token aud claim](https://openid.net/specs/openid-connect-core-1_0.html#IDToken)
+- [Keycloak Audience Protocol Mappers](https://www.keycloak.org/docs/latest/server_admin/#_audience)

docs/auth-flows.md

@@ -0,0 +1,422 @@
+# Authentication Flows by Deployment Mode
+
+This document provides a unified reference for authentication flows across all deployment modes. For configuration details, see [Authentication](authentication.md). For OAuth protocol details, see [OAuth Architecture](oauth-architecture.md).
+
+## Quick Reference Matrix
+
+| Mode | Client → MCP → NC | Background Sync | Astrolabe → MCP |
+|------|-------------------|-----------------|-----------------|
+| [Single-User BasicAuth](#1-single-user-basicauth) | Embedded credentials | Same credentials | N/A |
+| [Multi-User BasicAuth](#2-multi-user-basicauth) | Header pass-through | App password (optional) | Bearer token |
+| [OAuth Single-Audience](#3-oauth-single-audience-default) | Multi-audience token | Refresh token exchange | Bearer token |
+| [OAuth Token Exchange](#4-oauth-token-exchange-rfc-8693) | RFC 8693 exchange | Refresh token exchange | Bearer token |
+| [Smithery Stateless](#5-smithery-stateless) | Session parameters | Not supported | N/A |
+
+## Communication Patterns
+
+This document covers three distinct communication patterns:
+
+1. **MCP Client → MCP Server → Nextcloud**: Interactive tool calls initiated by users through MCP clients (Claude Desktop, etc.)
+2. **MCP Server → Nextcloud**: Background operations like vector sync that run without user interaction
+3. **Astrolabe → MCP Server**: Nextcloud app backend communication for settings UI and unified search
+
+---
+
+## Deployment Modes
+
+### 1. Single-User BasicAuth
+
+**Use Case:** Personal Nextcloud instance, local development, single-user deployments.
+
+#### MCP Client → MCP Server → Nextcloud
+
+```
+MCP Client                    MCP Server                   Nextcloud
+    │                             │                            │
+    │── MCP Request ─────────────▶│                            │
+    │   (no auth required)        │                            │
+    │                             │── HTTP + BasicAuth ───────▶│
+    │                             │   Authorization: Basic     │
+    │                             │   (embedded credentials)   │
+    │                             │◀── API Response ───────────│
+    │◀── Tool Result ─────────────│                            │
+```
+
+**Key characteristics:**
+- Credentials embedded in server configuration (`NEXTCLOUD_USERNAME`, `NEXTCLOUD_PASSWORD`)
+- Single shared `NextcloudClient` created at startup
+- No MCP-level authentication required (server trusts local clients)
+- All requests use the same Nextcloud user
+
+**Implementation:** `context.py:78-79` - Returns shared client from lifespan context
+
+#### Background Sync
+
+Uses the same embedded credentials as interactive requests. The background job accesses Nextcloud with the configured username/password.
+
+**Implementation:** Background jobs use `get_settings()` to access credentials
+
+#### Astrolabe Integration
+
+Not applicable - Astrolabe is only used in multi-user deployments where users need personal settings and token management.
+
+---
+
+### 2. Multi-User BasicAuth
+
+**Use Case:** Internal deployment where users provide their own credentials via HTTP headers.
+
+#### MCP Client → MCP Server → Nextcloud
+
+```
+MCP Client                    MCP Server                   Nextcloud
+    │                             │                            │
+    │── MCP Request ─────────────▶│                            │
+    │   Authorization: Basic      │                            │
+    │   (user credentials)        │                            │
+    │                             │── BasicAuthMiddleware ────▶│
+    │                             │   Extracts credentials     │
+    │                             │                            │
+    │                             │── HTTP + BasicAuth ───────▶│
+    │                             │   (pass-through)           │
+    │                             │◀── API Response ───────────│
+    │◀── Tool Result ─────────────│                            │
+```
+
+**Key characteristics:**
+- `BasicAuthMiddleware` extracts credentials from `Authorization: Basic` header
+- Credentials passed through to Nextcloud (not stored)
+- Client created per-request from extracted credentials
+- Stateless - no credential storage between requests
+
+**Implementation:** `context.py:187-248` - `_get_client_from_basic_auth()` extracts credentials from request state
+
+#### Background Sync (Optional)
+
+Requires `ENABLE_OFFLINE_ACCESS=true`. Users can store app passwords via Astrolabe for background operations.
+
+```
+Astrolabe                     MCP Server                   Nextcloud
+    │                             │                            │
+    │── Store App Password ──────▶│                            │
+    │   (via management API)      │                            │
+    │                             │── Store in SQLite ────────▶│
+    │                             │   (encrypted)              │
+    │◀── Confirmation ────────────│                            │
+    │                             │                            │
+    │         [Background Job]    │                            │
+    │                             │── Retrieve app password ──▶│
+    │                             │   (from encrypted storage) │
+    │                             │── HTTP + BasicAuth ───────▶│
+    │                             │   (stored app password)    │
+    │                             │◀── API Response ───────────│
+```
+
+**Requirements:**
+- `ENABLE_OFFLINE_ACCESS=true`
+- `TOKEN_ENCRYPTION_KEY` for credential encryption
+- `TOKEN_STORAGE_DB` for SQLite storage path
+
+#### Astrolabe → MCP Server
+
+```
+Astrolabe                     MCP Server                   Nextcloud OIDC
+    │                             │                            │
+    │── OAuth Flow ──────────────▶│◀── Token from IdP ────────▶│
+    │   (user initiates)          │                            │
+    │                             │                            │
+    │── Bearer Token ────────────▶│                            │
+    │   (management API calls)    │                            │
+    │                             │── Validate via JWKS ──────▶│
+    │                             │   (or introspection)       │
+    │◀── API Response ────────────│                            │
+```
+
+**Key characteristics:**
+- Astrolabe has its own OAuth client (`astrolabe_client_id` in Nextcloud config)
+- Tokens are validated by MCP server using Nextcloud OIDC JWKS
+- Authorization check: `token.sub == requested_resource_owner`
+- Any valid Nextcloud OIDC token accepted (relaxed audience validation per ADR-018)
+
+**Implementation:** `unified_verifier.py:120-183` - `verify_token_for_management_api()` validates without strict audience check
+
+---
+
+### 3. OAuth Single-Audience (Default)
+
+**Use Case:** Multi-user deployment with OAuth authentication. Tokens work for both MCP and Nextcloud.
+
+This is the default mode when `NEXTCLOUD_USERNAME`/`NEXTCLOUD_PASSWORD` are not set.
+
+#### MCP Client → MCP Server → Nextcloud
+
+```
+MCP Client                    MCP Server                   Nextcloud
+    │                             │                            │
+    │── Bearer Token ────────────▶│                            │
+    │   aud: ["mcp-server",       │                            │
+    │         "nextcloud"]        │                            │
+    │                             │── Validate MCP audience ──▶│
+    │                             │   (UnifiedTokenVerifier)   │
+    │                             │                            │
+    │                             │── HTTP + Same Token ──────▶│
+    │                             │   Authorization: Bearer    │
+    │                             │   (multi-audience token)   │
+    │                             │                            │
+    │                             │   NC validates its own aud │
+    │                             │◀── API Response ───────────│
+    │◀── Tool Result ─────────────│                            │
+```
+
+**Key characteristics:**
+- Token contains both audiences: `aud: ["mcp-server", "nextcloud"]`
+- MCP server validates only MCP audience (per RFC 7519)
+- Nextcloud independently validates its own audience
+- No token exchange needed - same token used throughout
+- Stateless operation for interactive requests
+
+**Token validation flow:**
+1. `UnifiedTokenVerifier.verify_token()` validates MCP audience
+2. Token passed directly to Nextcloud via `get_client_from_context()`
+3. Nextcloud validates its own audience when receiving API calls
+
+**Implementation:**
+- `unified_verifier.py:185-252` - `_verify_mcp_audience()` validates MCP audience only
+- `context.py:96-99` - Uses token directly in multi-audience mode
+
+#### Background Sync
+
+Requires `ENABLE_OFFLINE_ACCESS=true`. Uses stored refresh tokens to obtain access tokens for background operations.
+
+```
+                              MCP Server                   Nextcloud OIDC
+                                  │                            │
+    [Background Job starts]       │                            │
+                                  │── Get refresh token ──────▶│
+                                  │   (from encrypted storage) │
+                                  │                            │
+                                  │── Token refresh request ──▶│
+                                  │   grant_type=refresh_token │
+                                  │   scope=openid profile ... │
+                                  │◀── New access + refresh ───│
+                                  │   (rotation)               │
+                                  │                            │
+                                  │── Store rotated refresh ──▶│
+                                  │   (encrypted)              │
+                                  │                            │
+                                  │── HTTP + Access Token ────▶│
+                                  │   Authorization: Bearer    │
+                                  │◀── API Response ───────────│
+```
+
+**Key characteristics:**
+- Refresh tokens stored encrypted in SQLite (`TOKEN_STORAGE_DB`)
+- Nextcloud OIDC rotates refresh tokens on every use (one-time use)
+- `TokenBrokerService` handles token lifecycle
+- Per-user locking prevents race conditions during concurrent refresh
+
+**Implementation:**
+- `token_broker.py:269-362` - `get_background_token()` handles refresh with locking
+- `token_broker.py:428-509` - `_refresh_access_token_with_scopes()` exchanges refresh token
+
+#### Astrolabe → MCP Server
+
+Same as Multi-User BasicAuth. See [Astrolabe → MCP Server](#astrolabe--mcp-server) above.
+
+---
+
+### 4. OAuth Token Exchange (RFC 8693)
+
+**Use Case:** Multi-user deployment where MCP tokens are separate from Nextcloud tokens. Provides stronger security boundaries.
+
+Enabled by `ENABLE_TOKEN_EXCHANGE=true`.
+
+#### MCP Client → MCP Server → Nextcloud
+
+```
+MCP Client                    MCP Server                   Nextcloud OIDC
+    │                             │                            │
+    │── Bearer Token ────────────▶│                            │
+    │   aud: "mcp-server"         │                            │
+    │   (MCP audience only)       │                            │
+    │                             │── Validate MCP audience ──▶│
+    │                             │                            │
+    │                             │── RFC 8693 Exchange ──────▶│
+    │                             │   grant_type=              │
+    │                             │     urn:ietf:params:oauth: │
+    │                             │     grant-type:token-exchange
+    │                             │   subject_token=<mcp-token>│
+    │                             │   requested_audience=      │
+    │                             │     "nextcloud"            │
+    │                             │◀── Delegated Token ────────│
+    │                             │   aud: "nextcloud"         │
+    │                             │                            │
+    │                             │── HTTP + Delegated Token ─▶│
+    │                             │   Authorization: Bearer    │
+    │                             │◀── API Response ───────────│
+    │◀── Tool Result ─────────────│                            │
+```
+
+**Key characteristics:**
+- Strict audience separation: MCP token has `aud: "mcp-server"` only
+- Server exchanges for Nextcloud-audience token on each request
+- Ephemeral delegated tokens (not cached by default)
+- Strongest security boundary between MCP and Nextcloud access
+
+**Token exchange details:**
+- Uses RFC 8693 "urn:ietf:params:oauth:grant-type:token-exchange"
+- Subject token: MCP access token
+- Requested audience: Nextcloud resource URI
+- Result: Short-lived token scoped for Nextcloud
+
+**Implementation:**
+- `token_broker.py:220-267` - `get_session_token()` performs on-demand exchange
+- `token_exchange.py` - `exchange_token_for_delegation()` implements RFC 8693
+- `context.py:88-94` - Routes to session client in exchange mode
+
+#### Background Sync
+
+Same as OAuth Single-Audience. Uses stored refresh tokens from Flow 2 provisioning.
+
+```
+                              MCP Server                   Nextcloud OIDC
+                                  │                            │
+    [User provisions access]      │                            │
+                                  │── Flow 2 OAuth ───────────▶│
+                                  │   client_id="mcp-server"   │
+                                  │   scope=offline_access ... │
+                                  │◀── Refresh Token ──────────│
+                                  │   (stored encrypted)       │
+                                  │                            │
+    [Background Job runs later]   │                            │
+                                  │── Refresh for background ─▶│
+                                  │   (same as single-audience)│
+```
+
+**Key difference from interactive:**
+- Interactive: On-demand token exchange per request
+- Background: Uses pre-provisioned refresh tokens (Flow 2)
+
+#### Astrolabe → MCP Server
+
+Same as Multi-User BasicAuth. See [Astrolabe → MCP Server](#astrolabe--mcp-server) above.
+
+---
+
+### 5. Smithery Stateless
+
+**Use Case:** Multi-tenant SaaS deployment via Smithery platform. Fully stateless.
+
+Enabled by `SMITHERY_DEPLOYMENT=true`.
+
+#### MCP Client → MCP Server → Nextcloud
+
+```
+MCP Client                    MCP Server                   Nextcloud
+    │                             │                            │
+    │── SSE Connect ─────────────▶│                            │
+    │   ?nextcloud_url=...        │                            │
+    │   &username=...             │                            │
+    │   &app_password=...         │                            │
+    │                             │── SmitheryConfigMiddleware │
+    │                             │   Extract URL params       │
+    │                             │                            │
+    │── MCP Request ─────────────▶│                            │
+    │   (no Authorization header) │                            │
+    │                             │── Create per-request ─────▶│
+    │                             │   NextcloudClient          │
+    │                             │                            │
+    │                             │── HTTP + BasicAuth ───────▶│
+    │                             │   (from session params)    │
+    │                             │◀── API Response ───────────│
+    │◀── Tool Result ─────────────│                            │
+```
+
+**Key characteristics:**
+- Configuration passed via URL query parameters (Smithery `configSchema`)
+- No persistent state - client created fresh per request
+- No OAuth infrastructure
+- No background sync support (stateless)
+- No admin UI available
+
+**Required session parameters:**
+- `nextcloud_url`: Nextcloud instance URL
+- `username`: Nextcloud username
+- `app_password`: Nextcloud app password
+
+**Implementation:** `context.py:108-184` - `_get_client_from_session_config()` creates client from session params
+
+#### Background Sync
+
+Not supported. Smithery mode is fully stateless with no credential storage.
+
+#### Astrolabe Integration
+
+Not applicable. Smithery deployments don't integrate with Astrolabe.
+
+---
+
+## Configuration Quick Reference
+
+### Single-User BasicAuth
+```bash
+NEXTCLOUD_HOST=http://localhost:8080
+NEXTCLOUD_USERNAME=admin
+NEXTCLOUD_PASSWORD=password
+```
+
+### Multi-User BasicAuth
+```bash
+NEXTCLOUD_HOST=http://nextcloud.example.com
+ENABLE_MULTI_USER_BASIC_AUTH=true
+
+# Optional: For background sync
+ENABLE_OFFLINE_ACCESS=true
+TOKEN_ENCRYPTION_KEY=<32-byte-key>
+TOKEN_STORAGE_DB=/data/tokens.db
+```
+
+### OAuth Single-Audience (Default)
+```bash
+NEXTCLOUD_HOST=http://nextcloud.example.com
+# No username/password triggers OAuth mode
+
+# Optional: Static client credentials (instead of DCR)
+NEXTCLOUD_OIDC_CLIENT_ID=<client-id>
+NEXTCLOUD_OIDC_CLIENT_SECRET=<client-secret>
+
+# Optional: For background sync
+ENABLE_OFFLINE_ACCESS=true
+TOKEN_ENCRYPTION_KEY=<32-byte-key>
+TOKEN_STORAGE_DB=/data/tokens.db
+```
+
+### OAuth Token Exchange
+```bash
+NEXTCLOUD_HOST=http://nextcloud.example.com
+ENABLE_TOKEN_EXCHANGE=true
+NEXTCLOUD_OIDC_CLIENT_ID=<client-id>
+NEXTCLOUD_OIDC_CLIENT_SECRET=<client-secret>
+
+# Optional: For background sync
+ENABLE_OFFLINE_ACCESS=true
+TOKEN_ENCRYPTION_KEY=<32-byte-key>
+TOKEN_STORAGE_DB=/data/tokens.db
+```
+
+### Smithery Stateless
+```bash
+SMITHERY_DEPLOYMENT=true
+# All other config comes from session URL parameters
+```
+
+---
+
+## Related Documentation
+
+- [Authentication](authentication.md) - Configuration details and setup guides
+- [OAuth Architecture](oauth-architecture.md) - Deep OAuth protocol details
+- [ADR-004: Progressive Consent](ADR-004-mcp-application-oauth.md) - Dual OAuth flow architecture
+- [ADR-005: Token Audience Validation](ADR-005-token-audience-validation.md) - Audience validation strategy
+- [ADR-018: Nextcloud PHP App](ADR-018-nextcloud-php-app-for-settings-ui.md) - Astrolabe integration
+- [ADR-020: Deployment Modes](ADR-020-deployment-modes-and-configuration-validation.md) - Mode detection and validation

docs/authentication.md

@@ -140,6 +140,97 @@ Basic Authentication uses username and password credentials directly.
 - [Configuration](configuration.md#basic-authentication-legacy) - BasicAuth environment variables
 - [Running the Server](running.md#basicauth-mode-legacy) - BasicAuth examples
 
+## Hybrid Authentication (Multi-User BasicAuth + OAuth)
+
+When running in multi-user BasicAuth mode with `ENABLE_OFFLINE_ACCESS=true`, the server operates in **hybrid authentication mode**. This provides the simplicity of BasicAuth for normal operations with the security of OAuth for administrative functions.
+
+### Authentication Domains
+
+**MCP Operations** (Tools, Resources):
+- **Auth Method**: BasicAuth (HTTP Basic username/password)
+- **Characteristics**:
+  - Stateless - no token storage
+  - Simple configuration
+  - Direct credential validation against Nextcloud
+  - Credentials passed per-request in Authorization header
+- **Used For**: MCP tool calls from Claude, MCP client operations
+
+**Management APIs** (Webhooks, Admin UI):
+- **Auth Method**: OAuth bearer tokens
+- **Characteristics**:
+  - Per-user authorization via OAuth consent flow
+  - Refresh tokens stored for background operations
+  - Token validation via UnifiedTokenVerifier
+  - Explicit user consent required
+- **Used For**: Astrolabe admin UI, webhook management, vector sync operations
+
+### Configuration
+
+```env
+# Enable multi-user BasicAuth
+ENABLE_MULTI_USER_BASIC_AUTH=true
+
+# Enable hybrid mode (OAuth provisioning for management APIs)
+ENABLE_OFFLINE_ACCESS=true
+
+# Enable background sync (required for hybrid mode currently)
+VECTOR_SYNC_ENABLED=true
+
+# Encryption key for refresh token storage
+TOKEN_ENCRYPTION_KEY=<base64-encoded-key>
+
+# Nextcloud connection
+NEXTCLOUD_HOST=https://cloud.example.com
+
+# OAuth credentials (optional - uses DCR if not set)
+NEXTCLOUD_OIDC_CLIENT_ID=<client-id>
+NEXTCLOUD_OIDC_CLIENT_SECRET=<client-secret>
+```
+
+### OAuth Provisioning Flow
+
+1. Admin opens Astrolabe admin settings in Nextcloud
+2. Clicks "Authorize" to enable webhook management
+3. Redirected to `/oauth/authorize-nextcloud` on MCP server
+4. MCP server redirects to Nextcloud OAuth consent page
+5. Admin grants OAuth consent (scopes: `openid`, `profile`, `offline_access`)
+6. Redirected back to `/oauth/callback` on MCP server
+7. MCP server stores refresh token (encrypted)
+8. Admin can now manage webhooks from Astrolabe UI
+
+### Benefits
+
+- **Simple MCP client setup**: Use BasicAuth (no OAuth complexity for end users)
+- **Secure background operations**: Webhooks use per-user OAuth tokens (no shared credentials)
+- **Explicit authorization**: Admins must explicitly grant OAuth consent for webhook operations
+- **Per-user isolation**: Each admin's webhook operations use their own refresh token
+
+### Trade-offs
+
+- **Two auth systems**: More complex server configuration than pure BasicAuth or OAuth
+- **OAuth setup required**: Admins must complete OAuth flow before managing webhooks
+- **Token storage**: Requires database and encryption key for refresh tokens
+
+### Comparison
+
+| Feature | Pure BasicAuth | Hybrid Mode | Pure OAuth |
+|---------|---------------|-------------|------------|
+| MCP Operations | BasicAuth | BasicAuth | OAuth Bearer Token |
+| Management API | N/A | OAuth Bearer Token | OAuth Bearer Token |
+| Webhook Operations | N/A | OAuth Refresh Token | OAuth Refresh Token |
+| MCP Client Setup | Simple | Simple | Complex (PKCE flow) |
+| Admin UI Auth | N/A | OAuth Consent | OAuth Login |
+| Token Storage | None | Refresh tokens only | All tokens |
+| Deployment Complexity | Low | Medium | High |
+
+### Astrolabe User Setup (Hybrid Mode)
+
+For Astrolabe-specific user setup instructions in hybrid mode, see the [Astrolabe documentation](https://github.com/cbcoutinho/astrolabe/blob/master/docs/user-setup-hybrid-mode.md).
+
+### See Also
+- [OAuth Architecture](oauth-architecture.md) - Progressive Consent (Flow 2) details
+- [Configuration](configuration.md#enable_offline_access) - Hybrid mode configuration
+
 ## Mode Detection
 
 The server automatically detects the authentication mode:

docs/bedrock-setup.md

@@ -0,0 +1,338 @@
+# Amazon Bedrock Setup Guide
+
+This guide covers how to configure the Nextcloud MCP Server to use Amazon Bedrock for embeddings and text generation.
+
+## Prerequisites
+
+1. **AWS Account** with access to Amazon Bedrock
+2. **boto3 library** installed: `pip install boto3` or `uv sync --group dev`
+3. **Model Access** - Request access to models in AWS Bedrock console
+
+## Required AWS Permissions
+
+### IAM Policy for Bedrock Access
+
+The AWS IAM user or role needs the following permissions:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Sid": "BedrockInvokeModels",
+      "Effect": "Allow",
+      "Action": [
+        "bedrock:InvokeModel",
+        "bedrock:InvokeModelWithResponseStream"
+      ],
+      "Resource": [
+        "arn:aws:bedrock:*::foundation-model/*"
+      ]
+    }
+  ]
+}
+```
+
+### Minimal Permissions (Production)
+
+For production deployments, restrict to specific models:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Sid": "BedrockEmbeddings",
+      "Effect": "Allow",
+      "Action": [
+        "bedrock:InvokeModel"
+      ],
+      "Resource": [
+        "arn:aws:bedrock:us-east-1::foundation-model/amazon.titan-embed-text-v2:0"
+      ]
+    },
+    {
+      "Sid": "BedrockGeneration",
+      "Effect": "Allow",
+      "Action": [
+        "bedrock:InvokeModel"
+      ],
+      "Resource": [
+        "arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-3-sonnet-20240229-v1:0"
+      ]
+    }
+  ]
+}
+```
+
+### Additional Permissions (Optional)
+
+For advanced use cases:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Sid": "BedrockListModels",
+      "Effect": "Allow",
+      "Action": [
+        "bedrock:ListFoundationModels",
+        "bedrock:GetFoundationModel"
+      ],
+      "Resource": "*"
+    },
+    {
+      "Sid": "BedrockAsyncInvoke",
+      "Effect": "Allow",
+      "Action": [
+        "bedrock:InvokeModelAsync",
+        "bedrock:GetAsyncInvoke",
+        "bedrock:ListAsyncInvokes"
+      ],
+      "Resource": [
+        "arn:aws:bedrock:*::foundation-model/*"
+      ]
+    }
+  ]
+}
+```
+
+## Model Access
+
+Before using Bedrock models, you must request access in the AWS Console:
+
+1. Navigate to **Amazon Bedrock** → **Model access**
+2. Click **Manage model access**
+3. Select models you want to use:
+   - **Embeddings:** Amazon Titan Embed Text, Cohere Embed
+   - **Text Generation:** Anthropic Claude, Meta Llama, Amazon Titan Text
+4. Click **Request model access**
+5. Wait for approval (usually instant for most models)
+
+## Supported Models
+
+### Embedding Models
+
+| Provider | Model ID | Dimensions | Best For |
+|----------|----------|------------|----------|
+| Amazon Titan | `amazon.titan-embed-text-v1` | 1,536 | General purpose |
+| Amazon Titan | `amazon.titan-embed-text-v2:0` | 1,024 | Latest, improved quality |
+| Cohere | `cohere.embed-english-v3` | 1,024 | English text |
+| Cohere | `cohere.embed-multilingual-v3` | 1,024 | Multilingual |
+
+### Text Generation Models
+
+| Provider | Model ID | Context | Best For |
+|----------|----------|---------|----------|
+| Anthropic | `anthropic.claude-3-sonnet-20240229-v1:0` | 200K | Balanced performance |
+| Anthropic | `anthropic.claude-3-haiku-20240307-v1:0` | 200K | Fast, cost-effective |
+| Anthropic | `anthropic.claude-3-opus-20240229-v1:0` | 200K | Highest quality |
+| Meta | `meta.llama3-8b-instruct-v1:0` | 8K | Fast, open-source |
+| Meta | `meta.llama3-70b-instruct-v1:0` | 8K | High quality |
+| Amazon | `amazon.titan-text-express-v1` | 8K | Fast, low cost |
+| Mistral | `mistral.mistral-7b-instruct-v0:2` | 32K | Efficient |
+
+## Configuration
+
+### Environment Variables
+
+**Required:**
+```bash
+AWS_REGION=us-east-1
+```
+
+**Optional (at least one model required):**
+```bash
+# For embeddings
+BEDROCK_EMBEDDING_MODEL=amazon.titan-embed-text-v2:0
+
+# For text generation (RAG evaluation)
+BEDROCK_GENERATION_MODEL=anthropic.claude-3-sonnet-20240229-v1:0
+```
+
+**AWS Credentials (choose one method):**
+
+**Method 1: Environment Variables**
+```bash
+AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
+AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
+```
+
+**Method 2: AWS Credentials File** (`~/.aws/credentials`)
+```ini
+[default]
+aws_access_key_id = AKIAIOSFODNN7EXAMPLE
+aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
+```
+
+**Method 3: IAM Role** (when running on AWS EC2/ECS/Lambda)
+- No credentials needed, uses instance/task role automatically
+
+### Docker Configuration
+
+Add to your `docker-compose.yml`:
+
+```yaml
+services:
+  mcp:
+    environment:
+      - AWS_REGION=us-east-1
+      - BEDROCK_EMBEDDING_MODEL=amazon.titan-embed-text-v2:0
+      - BEDROCK_GENERATION_MODEL=anthropic.claude-3-sonnet-20240229-v1:0
+      - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}
+      - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}
+```
+
+Or use AWS credentials file volume mount:
+
+```yaml
+services:
+  mcp:
+    volumes:
+      - ~/.aws:/root/.aws:ro
+    environment:
+      - AWS_REGION=us-east-1
+      - BEDROCK_EMBEDDING_MODEL=amazon.titan-embed-text-v2:0
+```
+
+## Usage Examples
+
+### Embeddings Only
+
+```bash
+export AWS_REGION=us-east-1
+export BEDROCK_EMBEDDING_MODEL=amazon.titan-embed-text-v2:0
+export AWS_ACCESS_KEY_ID=your-key
+export AWS_SECRET_ACCESS_KEY=your-secret
+
+uv run nextcloud-mcp-server
+```
+
+### Both Embeddings and Generation
+
+```bash
+export AWS_REGION=us-east-1
+export BEDROCK_EMBEDDING_MODEL=amazon.titan-embed-text-v2:0
+export BEDROCK_GENERATION_MODEL=anthropic.claude-3-sonnet-20240229-v1:0
+
+# For RAG evaluation with Bedrock
+export RAG_EVAL_PROVIDER=bedrock
+export RAG_EVAL_BEDROCK_MODEL=anthropic.claude-3-sonnet-20240229-v1:0
+
+uv run python -m tests.rag_evaluation.evaluate
+```
+
+### Programmatic Usage
+
+```python
+from nextcloud_mcp_server.providers import BedrockProvider
+
+# Embeddings only
+provider = BedrockProvider(
+    region_name="us-east-1",
+    embedding_model="amazon.titan-embed-text-v2:0",
+)
+
+embeddings = await provider.embed_batch(["text1", "text2"])
+
+# Both capabilities
+provider = BedrockProvider(
+    region_name="us-east-1",
+    embedding_model="amazon.titan-embed-text-v2:0",
+    generation_model="anthropic.claude-3-sonnet-20240229-v1:0",
+)
+
+# Generate embeddings
+embedding = await provider.embed("query text")
+
+# Generate text
+response = await provider.generate("Write a summary", max_tokens=500)
+```
+
+## Cost Considerations
+
+### Embedding Costs (as of Jan 2025)
+
+| Model | Price per 1K tokens |
+|-------|---------------------|
+| Titan Embed Text v2 | $0.0001 |
+| Cohere Embed English v3 | $0.0001 |
+
+### Generation Costs (as of Jan 2025)
+
+| Model | Input (per 1K tokens) | Output (per 1K tokens) |
+|-------|----------------------|------------------------|
+| Claude 3 Haiku | $0.00025 | $0.00125 |
+| Claude 3 Sonnet | $0.003 | $0.015 |
+| Claude 3 Opus | $0.015 | $0.075 |
+| Llama 3 8B | $0.0003 | $0.0006 |
+| Titan Text Express | $0.0002 | $0.0006 |
+
+**Note:** Prices vary by region. Check [AWS Bedrock Pricing](https://aws.amazon.com/bedrock/pricing/) for current rates.
+
+## Troubleshooting
+
+### Error: "Executable doesn't exist" or boto3 not found
+
+**Solution:**
+```bash
+uv sync --group dev  # Installs boto3
+```
+
+### Error: "AccessDeniedException"
+
+**Causes:**
+1. IAM permissions missing
+2. Model access not requested
+3. Wrong AWS region
+
+**Solution:**
+1. Verify IAM policy includes `bedrock:InvokeModel`
+2. Request model access in Bedrock console
+3. Check model is available in your region
+
+### Error: "ResourceNotFoundException"
+
+**Cause:** Invalid model ID or model not available in region
+
+**Solution:**
+- Verify model ID matches exactly (case-sensitive)
+- Check model availability in your AWS region
+- Use `aws bedrock list-foundation-models` to see available models
+
+### Error: "ThrottlingException"
+
+**Cause:** Rate limit exceeded
+
+**Solution:**
+- Reduce request rate
+- Request quota increase via AWS Support
+- Use batch operations where possible
+
+## Security Best Practices
+
+1. **Use IAM Roles** when running on AWS infrastructure
+2. **Rotate Access Keys** regularly if using IAM users
+3. **Restrict Permissions** to only required models
+4. **Enable CloudTrail** for audit logging
+5. **Use AWS Secrets Manager** for credential management
+6. **Monitor Costs** with AWS Cost Explorer and Budgets
+
+## Regional Availability
+
+Amazon Bedrock is available in:
+- **US East (N. Virginia)**: `us-east-1` ✅ Most models
+- **US West (Oregon)**: `us-west-2` ✅ Most models
+- **Asia Pacific (Singapore)**: `ap-southeast-1`
+- **Asia Pacific (Tokyo)**: `ap-northeast-1`
+- **Europe (Frankfurt)**: `eu-central-1`
+
+**Note:** Model availability varies by region. Check the [AWS Bedrock documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/models-regions.html) for current availability.
+
+## References
+
+- [AWS Bedrock Documentation](https://docs.aws.amazon.com/bedrock/)
+- [AWS Bedrock Pricing](https://aws.amazon.com/bedrock/pricing/)
+- [boto3 Bedrock Runtime API](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/bedrock-runtime.html)
+- [Provider Architecture ADR](./ADR-015-unified-provider-architecture.md)

docs/configuration-migration-v2.md

@@ -0,0 +1,564 @@
+# Configuration Migration Guide v2
+
+**Version:** v0.58.0
+**Status:** Active
+**Related ADR:** [ADR-021: Configuration Consolidation and Simplification](ADR-021-configuration-consolidation.md)
+
+## Overview
+
+This guide helps you migrate from the old configuration variables to the new consolidated approach introduced in v0.58.0.
+
+**Key Changes:**
+- `VECTOR_SYNC_ENABLED` → `ENABLE_SEMANTIC_SEARCH`
+- `ENABLE_OFFLINE_ACCESS` → `ENABLE_BACKGROUND_OPERATIONS`
+- New: `MCP_DEPLOYMENT_MODE` for explicit mode selection
+- Automatic dependency resolution: semantic search auto-enables background operations
+
+**Backward Compatibility:**
+- Old variable names still work in v0.58.0+
+- Deprecation warnings logged when old names used
+- Old names will be removed in v1.0.0
+
+---
+
+## Quick Reference: Variable Name Changes
+
+| Old Name | New Name | Status |
+|----------|----------|--------|
+| `VECTOR_SYNC_ENABLED` | `ENABLE_SEMANTIC_SEARCH` | Deprecated |
+| `ENABLE_OFFLINE_ACCESS` | `ENABLE_BACKGROUND_OPERATIONS` | Deprecated |
+| N/A (auto-detected) | `MCP_DEPLOYMENT_MODE` | New (optional) |
+
+**Tuning parameters unchanged:**
+- `VECTOR_SYNC_SCAN_INTERVAL` - Keep as-is
+- `VECTOR_SYNC_PROCESSOR_WORKERS` - Keep as-is
+- `VECTOR_SYNC_QUEUE_MAX_SIZE` - Keep as-is
+
+---
+
+## Migration Scenarios
+
+### Scenario 1: Single-User BasicAuth with Semantic Search
+
+**Before (v0.57.x):**
+```bash
+NEXTCLOUD_HOST=http://localhost:8080
+NEXTCLOUD_USERNAME=admin
+NEXTCLOUD_PASSWORD=password
+VECTOR_SYNC_ENABLED=true
+QDRANT_LOCATION=:memory:
+OLLAMA_BASE_URL=http://ollama:11434
+```
+
+**After (v0.58.0+):**
+```bash
+NEXTCLOUD_HOST=http://localhost:8080
+NEXTCLOUD_USERNAME=admin
+NEXTCLOUD_PASSWORD=password
+
+# Optional: Explicit mode declaration (recommended)
+MCP_DEPLOYMENT_MODE=single_user_basic
+
+# Updated variable name
+ENABLE_SEMANTIC_SEARCH=true  # Previously VECTOR_SYNC_ENABLED
+
+QDRANT_LOCATION=:memory:
+OLLAMA_BASE_URL=http://ollama:11434
+```
+
+**What Changed:**
+- ✅ Renamed `VECTOR_SYNC_ENABLED` to `ENABLE_SEMANTIC_SEARCH`
+- ✅ Added optional `MCP_DEPLOYMENT_MODE` for clarity
+- ✅ Background operations NOT auto-enabled (not needed in single-user mode)
+
+**Migration Steps:**
+1. Replace `VECTOR_SYNC_ENABLED=true` with `ENABLE_SEMANTIC_SEARCH=true`
+2. Optionally add `MCP_DEPLOYMENT_MODE=single_user_basic`
+3. Restart server
+4. Verify deprecation warnings are gone
+
+---
+
+### Scenario 2: Multi-User OAuth with Semantic Search
+
+**Before (v0.57.x):**
+```bash
+NEXTCLOUD_HOST=https://nextcloud.example.com
+NEXTCLOUD_USERNAME=
+NEXTCLOUD_PASSWORD=
+
+# Both variables required - confusing!
+ENABLE_OFFLINE_ACCESS=true
+VECTOR_SYNC_ENABLED=true
+
+TOKEN_ENCRYPTION_KEY=your-key-here
+TOKEN_STORAGE_DB=/app/data/tokens.db
+QDRANT_URL=http://qdrant:6333
+OLLAMA_BASE_URL=http://ollama:11434
+NEXTCLOUD_OIDC_CLIENT_ID=mcp-server
+NEXTCLOUD_OIDC_CLIENT_SECRET=secret
+```
+
+**After (v0.58.0+ - Simplified):**
+```bash
+NEXTCLOUD_HOST=https://nextcloud.example.com
+NEXTCLOUD_USERNAME=
+NEXTCLOUD_PASSWORD=
+
+# Optional: Explicit mode declaration
+MCP_DEPLOYMENT_MODE=oauth_single_audience
+
+# One variable does it all!
+ENABLE_SEMANTIC_SEARCH=true  # Automatically enables background operations
+
+TOKEN_ENCRYPTION_KEY=your-key-here
+TOKEN_STORAGE_DB=/app/data/tokens.db
+QDRANT_URL=http://qdrant:6333
+OLLAMA_BASE_URL=http://ollama:11434
+NEXTCLOUD_OIDC_CLIENT_ID=mcp-server
+NEXTCLOUD_OIDC_CLIENT_SECRET=secret
+
+# Note: ENABLE_OFFLINE_ACCESS no longer needed!
+# Background operations are auto-enabled by ENABLE_SEMANTIC_SEARCH
+```
+
+**What Changed:**
+- ✅ Removed need for explicit `ENABLE_OFFLINE_ACCESS`
+- ✅ `ENABLE_SEMANTIC_SEARCH` automatically enables background operations in multi-user modes
+- ✅ Renamed `VECTOR_SYNC_ENABLED` to `ENABLE_SEMANTIC_SEARCH`
+- ✅ Added optional explicit mode declaration
+
+**Migration Steps:**
+1. Replace `VECTOR_SYNC_ENABLED=true` with `ENABLE_SEMANTIC_SEARCH=true`
+2. Remove `ENABLE_OFFLINE_ACCESS=true` (auto-enabled)
+3. Optionally add `MCP_DEPLOYMENT_MODE=oauth_single_audience`
+4. Restart server
+5. Check logs for confirmation: "Automatically enabled background operations for semantic search"
+
+---
+
+### Scenario 3: Multi-User OAuth WITHOUT Semantic Search
+
+**Before (v0.57.x):**
+```bash
+NEXTCLOUD_HOST=https://nextcloud.example.com
+NEXTCLOUD_USERNAME=
+NEXTCLOUD_PASSWORD=
+
+# Enable background operations for future features
+ENABLE_OFFLINE_ACCESS=true
+
+TOKEN_ENCRYPTION_KEY=your-key-here
+TOKEN_STORAGE_DB=/app/data/tokens.db
+NEXTCLOUD_OIDC_CLIENT_ID=mcp-server
+NEXTCLOUD_OIDC_CLIENT_SECRET=secret
+```
+
+**After (v0.58.0+):**
+```bash
+NEXTCLOUD_HOST=https://nextcloud.example.com
+NEXTCLOUD_USERNAME=
+NEXTCLOUD_PASSWORD=
+
+# Optional: Explicit mode declaration
+MCP_DEPLOYMENT_MODE=oauth_single_audience
+
+# Renamed for clarity
+ENABLE_BACKGROUND_OPERATIONS=true  # Previously ENABLE_OFFLINE_ACCESS
+
+TOKEN_ENCRYPTION_KEY=your-key-here
+TOKEN_STORAGE_DB=/app/data/tokens.db
+NEXTCLOUD_OIDC_CLIENT_ID=mcp-server
+NEXTCLOUD_OIDC_CLIENT_SECRET=secret
+```
+
+**What Changed:**
+- ✅ Renamed `ENABLE_OFFLINE_ACCESS` to `ENABLE_BACKGROUND_OPERATIONS`
+- ✅ Added optional explicit mode declaration
+
+**Migration Steps:**
+1. Replace `ENABLE_OFFLINE_ACCESS=true` with `ENABLE_BACKGROUND_OPERATIONS=true`
+2. Optionally add `MCP_DEPLOYMENT_MODE=oauth_single_audience`
+3. Restart server
+
+---
+
+### Scenario 4: Multi-User BasicAuth with Semantic Search
+
+**Before (v0.57.x):**
+```bash
+NEXTCLOUD_HOST=https://nextcloud.example.com
+ENABLE_MULTI_USER_BASIC_AUTH=true
+
+# Both required - redundant
+ENABLE_OFFLINE_ACCESS=true
+VECTOR_SYNC_ENABLED=true
+
+TOKEN_ENCRYPTION_KEY=your-key-here
+TOKEN_STORAGE_DB=/app/data/tokens.db
+QDRANT_URL=http://qdrant:6333
+OLLAMA_BASE_URL=http://ollama:11434
+NEXTCLOUD_OIDC_CLIENT_ID=mcp-server
+NEXTCLOUD_OIDC_CLIENT_SECRET=secret
+```
+
+**After (v0.58.0+ - Simplified):**
+```bash
+NEXTCLOUD_HOST=https://nextcloud.example.com
+ENABLE_MULTI_USER_BASIC_AUTH=true
+
+# Optional: Explicit mode declaration
+MCP_DEPLOYMENT_MODE=multi_user_basic
+
+# One variable handles both!
+ENABLE_SEMANTIC_SEARCH=true  # Auto-enables background operations
+
+TOKEN_ENCRYPTION_KEY=your-key-here
+TOKEN_STORAGE_DB=/app/data/tokens.db
+QDRANT_URL=http://qdrant:6333
+OLLAMA_BASE_URL=http://ollama:11434
+NEXTCLOUD_OIDC_CLIENT_ID=mcp-server
+NEXTCLOUD_OIDC_CLIENT_SECRET=secret
+
+# Note: ENABLE_OFFLINE_ACCESS no longer needed!
+```
+
+**What Changed:**
+- ✅ Semantic search auto-enables background operations
+- ✅ Removed need for explicit `ENABLE_OFFLINE_ACCESS`
+- ✅ Clearer variable naming
+
+**Migration Steps:**
+1. Replace `VECTOR_SYNC_ENABLED=true` with `ENABLE_SEMANTIC_SEARCH=true`
+2. Remove `ENABLE_OFFLINE_ACCESS=true` (auto-enabled)
+3. Optionally add `MCP_DEPLOYMENT_MODE=multi_user_basic`
+4. Restart server
+
+---
+
+### Scenario 5: Token Exchange Mode with Semantic Search
+
+**Before (v0.57.x):**
+```bash
+NEXTCLOUD_HOST=https://nextcloud.example.com
+ENABLE_TOKEN_EXCHANGE=true
+
+# Both required
+ENABLE_OFFLINE_ACCESS=true
+VECTOR_SYNC_ENABLED=true
+
+TOKEN_ENCRYPTION_KEY=your-key-here
+TOKEN_STORAGE_DB=/app/data/tokens.db
+TOKEN_EXCHANGE_CACHE_TTL=300
+QDRANT_URL=http://qdrant:6333
+OLLAMA_BASE_URL=http://ollama:11434
+```
+
+**After (v0.58.0+ - Simplified):**
+```bash
+NEXTCLOUD_HOST=https://nextcloud.example.com
+ENABLE_TOKEN_EXCHANGE=true
+
+# Optional: Explicit mode declaration
+MCP_DEPLOYMENT_MODE=oauth_token_exchange
+
+# One variable!
+ENABLE_SEMANTIC_SEARCH=true  # Auto-enables background operations
+
+TOKEN_ENCRYPTION_KEY=your-key-here
+TOKEN_STORAGE_DB=/app/data/tokens.db
+TOKEN_EXCHANGE_CACHE_TTL=300
+QDRANT_URL=http://qdrant:6333
+OLLAMA_BASE_URL=http://ollama:11434
+```
+
+**What Changed:**
+- ✅ Semantic search auto-enables background operations
+- ✅ Explicit mode declaration available
+
+**Migration Steps:**
+1. Replace `VECTOR_SYNC_ENABLED=true` with `ENABLE_SEMANTIC_SEARCH=true`
+2. Remove `ENABLE_OFFLINE_ACCESS=true` (auto-enabled)
+3. Optionally add `MCP_DEPLOYMENT_MODE=oauth_token_exchange`
+4. Restart server
+
+---
+
+## Understanding Automatic Dependency Resolution
+
+### How It Works
+
+In v0.58.0+, the server uses smart dependency resolution:
+
+```python
+# In multi-user modes (OAuth, Multi-User BasicAuth):
+if ENABLE_SEMANTIC_SEARCH == true:
+    background_operations = automatically enabled
+    refresh_tokens = automatically requested
+    token_storage = required (TOKEN_ENCRYPTION_KEY, TOKEN_STORAGE_DB)
+    oauth_credentials = required (for app password retrieval)
+```
+
+**What this means:**
+- ✅ Set `ENABLE_SEMANTIC_SEARCH=true`
+- ✅ Provide required infrastructure (Qdrant, Ollama, encryption key)
+- ✅ System automatically enables background operations
+- ❌ No need to set `ENABLE_BACKGROUND_OPERATIONS` separately
+
+### When Automatic Enablement Happens
+
+| Deployment Mode | Semantic Search Enabled | Background Operations Auto-Enabled? |
+|----------------|------------------------|-----------------------------------|
+| Single-User BasicAuth | ✅ | ❌ No (not needed) |
+| Multi-User BasicAuth | ✅ | ✅ Yes |
+| OAuth Single-Audience | ✅ | ✅ Yes |
+| OAuth Token Exchange | ✅ | ✅ Yes |
+| Smithery Stateless | N/A (not supported) | N/A |
+
+### When to Explicitly Set ENABLE_BACKGROUND_OPERATIONS
+
+Only needed when you want background operations **without** semantic search:
+
+```bash
+# Example: OAuth mode with background operations but NO semantic search
+NEXTCLOUD_HOST=https://nextcloud.example.com
+MCP_DEPLOYMENT_MODE=oauth_single_audience
+
+# Explicitly enable background operations for future features
+ENABLE_BACKGROUND_OPERATIONS=true
+
+TOKEN_ENCRYPTION_KEY=your-key-here
+TOKEN_STORAGE_DB=/app/data/tokens.db
+
+# Semantic search disabled
+ENABLE_SEMANTIC_SEARCH=false
+```
+
+---
+
+## Explicit Mode Selection
+
+### Why Use MCP_DEPLOYMENT_MODE?
+
+**Benefits:**
+- ✅ Removes ambiguity about which mode is active
+- ✅ Validation errors reference specific mode requirements
+- ✅ Catches configuration mistakes early
+- ✅ Self-documenting configuration
+
+**Example:**
+```bash
+# Without explicit mode:
+NEXTCLOUD_HOST=https://nextcloud.example.com
+# Is this OAuth or Multi-User BasicAuth? Not immediately clear.
+
+# With explicit mode:
+MCP_DEPLOYMENT_MODE=oauth_single_audience
+NEXTCLOUD_HOST=https://nextcloud.example.com
+# Clear: This is OAuth mode
+```
+
+### Valid Mode Values
+
+| Mode Value | Description |
+|-----------|-------------|
+| `single_user_basic` | Single-user with username/password |
+| `multi_user_basic` | Multi-user with BasicAuth pass-through |
+| `oauth_single_audience` | Multi-user OAuth (recommended) |
+| `oauth_token_exchange` | Multi-user OAuth with token exchange |
+| `smithery` | Smithery platform deployment |
+
+### Mode Detection Priority
+
+When `MCP_DEPLOYMENT_MODE` is set:
+1. ✅ Explicit mode is used
+2. ✅ Server validates configuration matches explicit mode
+3. ❌ Auto-detection is skipped
+
+When `MCP_DEPLOYMENT_MODE` is NOT set:
+1. ✅ Auto-detection runs (existing behavior)
+2. ✅ Priority: Smithery → Token Exchange → Multi-User BasicAuth → Single-User BasicAuth → OAuth Single-Audience
+
+---
+
+## Validation and Error Messages
+
+### Old Validation (v0.57.x)
+
+```
+Error: [multi_user_basic] ENABLE_OFFLINE_ACCESS is required when VECTOR_SYNC_ENABLED is enabled
+```
+
+**Problem:** User must understand internal dependency relationship
+
+### New Validation (v0.58.0+)
+
+```
+Error: [multi_user_basic] TOKEN_ENCRYPTION_KEY is required when ENABLE_SEMANTIC_SEARCH is enabled
+```
+
+**Benefit:** Clear what's needed, no mention of internal ENABLE_BACKGROUND_OPERATIONS flag
+
+---
+
+## Troubleshooting Migration
+
+### Issue: Deprecation Warning After Migration
+
+**Symptom:**
+```
+WARNING: VECTOR_SYNC_ENABLED is deprecated. Please use ENABLE_SEMANTIC_SEARCH instead.
+```
+
+**Solution:**
+1. Check for `VECTOR_SYNC_ENABLED` in `.env` file
+2. Replace with `ENABLE_SEMANTIC_SEARCH`
+3. Search for any scripts/CI configs using old name
+4. Restart server
+
+### Issue: Both Old and New Names Set
+
+**Symptom:**
+```
+WARNING: Both ENABLE_SEMANTIC_SEARCH and VECTOR_SYNC_ENABLED are set. Using ENABLE_SEMANTIC_SEARCH.
+```
+
+**Solution:**
+1. Remove `VECTOR_SYNC_ENABLED` from `.env`
+2. Keep `ENABLE_SEMANTIC_SEARCH`
+3. Restart server
+
+### Issue: Missing Required Dependencies
+
+**Symptom:**
+```
+Error: [oauth_single_audience] TOKEN_ENCRYPTION_KEY is required when ENABLE_SEMANTIC_SEARCH is enabled
+```
+
+**Solution:**
+When semantic search is enabled in multi-user modes, you need:
+- `TOKEN_ENCRYPTION_KEY` - Generate with: `python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"`
+- `TOKEN_STORAGE_DB` - Path to SQLite database (e.g., `/app/data/tokens.db`)
+- `NEXTCLOUD_OIDC_CLIENT_ID` and `NEXTCLOUD_OIDC_CLIENT_SECRET` - For app password retrieval
+
+### Issue: Unexpected Mode Detected
+
+**Symptom:**
+Server activates `oauth_single_audience` mode when you expected `multi_user_basic`
+
+**Solution:**
+Add explicit mode declaration:
+```bash
+MCP_DEPLOYMENT_MODE=multi_user_basic
+ENABLE_MULTI_USER_BASIC_AUTH=true
+```
+
+---
+
+## Testing Your Migration
+
+### Step 1: Verify Configuration
+
+```bash
+# Set new variable names in .env
+cat .env | grep -E "(ENABLE_SEMANTIC_SEARCH|ENABLE_BACKGROUND_OPERATIONS|MCP_DEPLOYMENT_MODE)"
+```
+
+### Step 2: Check for Old Variable Names
+
+```bash
+# Should return nothing after migration
+cat .env | grep -E "(VECTOR_SYNC_ENABLED|ENABLE_OFFLINE_ACCESS)"
+```
+
+### Step 3: Start Server and Check Logs
+
+```bash
+# Start server
+docker-compose up mcp
+
+# Look for:
+# 1. No deprecation warnings
+# 2. Correct mode detected
+# 3. Auto-enablement messages (if using semantic search in multi-user mode)
+```
+
+**Expected Log Output (Multi-User OAuth + Semantic Search):**
+```
+INFO: Using explicit deployment mode: oauth_single_audience
+INFO: Automatically enabled background operations for semantic search in multi-user mode.
+INFO: Vector sync enabled. Starting background scanner...
+```
+
+### Step 4: Verify Functionality
+
+Test that existing features still work:
+- [ ] Semantic search returns results
+- [ ] Background indexing runs
+- [ ] OAuth flow completes successfully
+- [ ] Refresh tokens are stored/retrieved
+
+---
+
+## Quick Start Templates
+
+We provide mode-specific templates for new deployments:
+
+| Template | Use Case |
+|----------|----------|
+| `env.sample.single-user` | Simplest setup |
+| `env.sample.oauth-multi-user` | Recommended multi-user |
+| `env.sample.oauth-advanced` | Token exchange mode |
+
+**Usage:**
+```bash
+cp env.sample.oauth-multi-user .env
+# Edit .env with your values
+docker-compose up -d
+```
+
+---
+
+## Timeline and Support
+
+| Version | Status | Old Variable Support |
+|---------|--------|---------------------|
+| v0.57.x | Stable | Old names only |
+| v0.58.0 | Current | Both old and new (with warnings) |
+| v1.0.0 | Breaking | New names only |
+
+**Recommendation:** Migrate before v1.0.0 (12+ months minimum)
+
+---
+
+## Getting Help
+
+If you encounter issues during migration:
+
+1. **Check the logs** - Look for deprecation warnings and error messages
+2. **Review ADR-021** - See [docs/ADR-021-configuration-consolidation.md](ADR-021-configuration-consolidation.md)
+3. **Use mode-specific templates** - See `env.sample.*` files
+4. **File an issue** - Include your `.env` (redacted), logs, and mode
+
+---
+
+## Summary
+
+**What You Need to Do:**
+1. ✅ Rename `VECTOR_SYNC_ENABLED` → `ENABLE_SEMANTIC_SEARCH`
+2. ✅ (Optional) Rename `ENABLE_OFFLINE_ACCESS` → `ENABLE_BACKGROUND_OPERATIONS`
+3. ✅ (Recommended) Add `MCP_DEPLOYMENT_MODE` for clarity
+4. ✅ Remove redundant settings (semantic search auto-enables background ops in multi-user modes)
+5. ✅ Test your configuration
+
+**What the Server Does Automatically:**
+- ✅ Supports both old and new variable names
+- ✅ Logs deprecation warnings for old names
+- ✅ Auto-enables background operations when semantic search is enabled in multi-user modes
+- ✅ Validates configuration and provides clear error messages
+
+**Migration Timeline:**
+- Now → v1.0.0: Both old and new names work
+- v1.0.0+: Only new names supported
+
+**Questions?** See [docs/configuration.md](configuration.md) or file an issue.

docs/configuration.md

@@ -2,25 +2,82 @@
 
 The Nextcloud MCP server requires configuration to connect to your Nextcloud instance. Configuration is provided through environment variables, typically stored in a `.env` file.
 
+> **Note:** Configuration was significantly simplified in v0.58.0. If you're upgrading from v0.57.x, see the [Configuration Migration Guide](configuration-migration-v2.md).
+
 ## Quick Start
 
-Create a `.env` file based on `env.sample`:
+We provide mode-specific configuration templates for quick setup:
 
 ```bash
+# Choose a template based on your deployment mode:
+cp env.sample.single-user .env         # Simplest - one user, local dev
+cp env.sample.oauth-multi-user .env    # Recommended - multi-user OAuth
+cp env.sample.oauth-advanced .env      # Advanced - token exchange mode
+
+# Or start from the full example:
 cp env.sample .env
+
 # Edit .env with your Nextcloud details
 ```
 
-Then choose your authentication mode:
+Then choose your deployment mode:
 
-- [OAuth2/OIDC Configuration](#oauth2oidc-configuration) (Recommended)
-- [Basic Authentication Configuration](#basic-authentication-legacy)
+- [Single-User BasicAuth](#single-user-basicauth-mode) - Simplest for personal instances
+- [Multi-User OAuth](#multi-user-oauth-modes) - Recommended for production
+- [Deployment Mode Selection](#deployment-mode-selection) - Explicit mode declaration
 
 ---
 
-## OAuth2/OIDC Configuration
+## Deployment Mode Selection
 
-OAuth2/OIDC is the recommended authentication mode for production deployments.
+**New in v0.58.0:** You can explicitly declare your deployment mode to remove ambiguity and catch configuration errors early.
+
+```dotenv
+# Optional but recommended
+MCP_DEPLOYMENT_MODE=oauth_single_audience
+```
+
+**Valid values:**
+- `single_user_basic` - Single-user with username/password
+- `multi_user_basic` - Multi-user with BasicAuth pass-through
+- `oauth_single_audience` - Multi-user OAuth (recommended)
+- `oauth_token_exchange` - Multi-user OAuth with token exchange
+- `smithery` - Smithery platform deployment
+
+**Benefits:**
+- ✅ Clear which mode is active
+- ✅ Better validation error messages
+- ✅ Self-documenting configuration
+- ✅ Catches configuration mistakes early
+
+**Auto-detection:** If `MCP_DEPLOYMENT_MODE` is not set, the server auto-detects the mode based on other settings (existing behavior).
+
+See [Authentication Modes](authentication.md) for detailed comparison of deployment modes.
+
+---
+
+## Single-User BasicAuth Mode
+
+BasicAuth with a single user is the simplest deployment mode. Use for personal instances, local development, and testing.
+
+```dotenv
+# Minimal single-user configuration
+NEXTCLOUD_HOST=http://localhost:8080
+NEXTCLOUD_USERNAME=admin
+NEXTCLOUD_PASSWORD=password
+
+# Optional: Explicit mode declaration
+MCP_DEPLOYMENT_MODE=single_user_basic
+```
+
+> [!WARNING]
+> **Security Notice:** BasicAuth stores credentials in environment variables and is less secure than OAuth. Use OAuth for production multi-user deployments.
+
+---
+
+## Multi-User OAuth Modes
+
+OAuth2/OIDC is the recommended authentication mode for production multi-user deployments.
 
 ### Minimal Configuration (Auto-registration)
 
@@ -28,6 +85,9 @@ OAuth2/OIDC is the recommended authentication mode for production deployments.
 # .env file for OAuth with auto-registration
 NEXTCLOUD_HOST=https://your.nextcloud.instance.com
 
+# Optional: Explicit mode declaration (recommended)
+MCP_DEPLOYMENT_MODE=oauth_single_audience
+
 # Leave these EMPTY for OAuth mode
 NEXTCLOUD_USERNAME=
 NEXTCLOUD_PASSWORD=
@@ -41,12 +101,14 @@ This minimal configuration uses dynamic client registration to automatically reg
 # .env file for OAuth with pre-configured client
 NEXTCLOUD_HOST=https://your.nextcloud.instance.com
 
+# Optional: Explicit mode declaration (recommended)
+MCP_DEPLOYMENT_MODE=oauth_single_audience
+
 # OAuth Client Credentials (optional - auto-registers if not provided)
 NEXTCLOUD_OIDC_CLIENT_ID=your-client-id
 NEXTCLOUD_OIDC_CLIENT_SECRET=your-client-secret
 
-# OAuth Storage and Callback Settings (optional)
-NEXTCLOUD_OIDC_CLIENT_STORAGE=.nextcloud_oauth_client.json
+# OAuth Callback Settings (optional)
 NEXTCLOUD_MCP_SERVER_URL=http://localhost:8000
 
 # Leave these EMPTY for OAuth mode
@@ -61,7 +123,6 @@ NEXTCLOUD_PASSWORD=
 | `NEXTCLOUD_HOST` | ✅ Yes | - | Full URL of your Nextcloud instance (e.g., `https://cloud.example.com`) |
 | `NEXTCLOUD_OIDC_CLIENT_ID` | ⚠️ Optional | - | OAuth client ID (auto-registers if empty) |
 | `NEXTCLOUD_OIDC_CLIENT_SECRET` | ⚠️ Optional | - | OAuth client secret (auto-registers if empty) |
-| `NEXTCLOUD_OIDC_CLIENT_STORAGE` | ⚠️ Optional | `.nextcloud_oauth_client.json` | Path to store auto-registered client credentials |
 | `NEXTCLOUD_MCP_SERVER_URL` | ⚠️ Optional | `http://localhost:8000` | MCP server URL for OAuth callbacks |
 | `NEXTCLOUD_USERNAME` | ❌ Must be empty | - | Leave empty to enable OAuth mode |
 | `NEXTCLOUD_PASSWORD` | ❌ Must be empty | - | Leave empty to enable OAuth mode |
@@ -110,6 +171,418 @@ NEXTCLOUD_PASSWORD=your_app_password_or_password
 
 ---
 
+## SSL/TLS Configuration (Optional)
+
+If your Nextcloud instance uses a self-signed certificate or a private CA (common with reverse proxies like Traefik or Caddy), the MCP server will reject the connection by default. Use these settings to configure certificate verification.
+
+### Custom CA Bundle (Recommended)
+
+Point the server at your CA certificate file:
+
+```dotenv
+NEXTCLOUD_CA_BUNDLE=/etc/ssl/certs/my-ca.pem
+```
+
+With Docker, mount the certificate as a read-only volume:
+
+```bash
+docker run \
+  -v /path/to/my-ca.pem:/etc/ssl/certs/my-ca.pem:ro \
+  -e NEXTCLOUD_CA_BUNDLE=/etc/ssl/certs/my-ca.pem \
+  -e NEXTCLOUD_HOST=https://nextcloud.local \
+  --env-file .env \
+  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
+```
+
+### Disable Verification (Development Only)
+
+> [!WARNING]
+> Disabling TLS verification is insecure. Only use this for local development or testing.
+
+```dotenv
+NEXTCLOUD_VERIFY_SSL=false
+```
+
+### Environment Variables Reference
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `NEXTCLOUD_VERIFY_SSL` | ⚠️ Optional | `true` | Set to `false` to disable TLS certificate verification |
+| `NEXTCLOUD_CA_BUNDLE` | ⚠️ Optional | - | Path to a PEM CA bundle file for custom certificate authorities |
+
+### Scope
+
+These settings apply to **all** outbound connections to Nextcloud and its OIDC endpoints, including:
+
+- Nextcloud API calls (Notes, Calendar, Contacts, WebDAV, etc.)
+- OIDC discovery and token endpoints
+- OAuth client registration (DCR)
+- Health checks
+
+They do **not** affect connections to internal services (Ollama, Qdrant, Unstructured) which have their own SSL configuration.
+
+---
+
+## Semantic Search Configuration (Optional)
+
+**New in v0.58.0:** Simplified semantic search configuration with automatic dependency resolution.
+
+The MCP server includes semantic search capabilities powered by vector embeddings. This feature requires a vector database (Qdrant) and an embedding service.
+
+### Quick Start
+
+**Single-User Mode:**
+```dotenv
+NEXTCLOUD_HOST=http://localhost:8080
+NEXTCLOUD_USERNAME=admin
+NEXTCLOUD_PASSWORD=password
+
+# Enable semantic search
+ENABLE_SEMANTIC_SEARCH=true
+
+# Vector database
+QDRANT_LOCATION=:memory:
+
+# Embedding provider
+OLLAMA_BASE_URL=http://ollama:11434
+```
+
+**Multi-User OAuth Mode:**
+```dotenv
+NEXTCLOUD_HOST=https://nextcloud.example.com
+MCP_DEPLOYMENT_MODE=oauth_single_audience
+
+# Enable semantic search
+# In multi-user modes, this AUTOMATICALLY enables background operations!
+ENABLE_SEMANTIC_SEARCH=true
+
+# Required for background operations (auto-enabled by semantic search)
+TOKEN_ENCRYPTION_KEY=your-key-here
+TOKEN_STORAGE_DB=/app/data/tokens.db
+
+# Vector database
+QDRANT_URL=http://qdrant:6333
+
+# Embedding provider
+OLLAMA_BASE_URL=http://ollama:11434
+```
+
+> **Note:** In multi-user modes (OAuth, Multi-User BasicAuth), enabling `ENABLE_SEMANTIC_SEARCH` automatically enables background operations and refresh token storage. You don't need to set `ENABLE_BACKGROUND_OPERATIONS` separately!
+
+### Qdrant Vector Database Modes
+
+The server supports three Qdrant deployment modes:
+
+1. **In-Memory Mode** (Default) - Simplest for development and testing
+2. **Persistent Local Mode** - For single-instance deployments with persistence
+3. **Network Mode** - For production with dedicated Qdrant service
+
+#### 1. In-Memory Mode (Default)
+
+No configuration needed! If neither `QDRANT_URL` nor `QDRANT_LOCATION` is set, the server defaults to in-memory mode:
+
+```dotenv
+# No Qdrant configuration needed - defaults to :memory:
+ENABLE_SEMANTIC_SEARCH=true
+```
+
+**Pros:**
+- Zero configuration
+- Fast startup
+- Perfect for testing
+
+**Cons:**
+- Data lost on restart
+- Limited to available RAM
+
+#### 2. Persistent Local Mode
+
+For single-instance deployments that need persistence without a separate Qdrant service:
+
+```dotenv
+# Local persistent storage
+QDRANT_LOCATION=/app/data/qdrant  # Or any writable path
+ENABLE_SEMANTIC_SEARCH=true
+```
+
+**Pros:**
+- Data persists across restarts
+- No separate service needed
+- Suitable for small/medium deployments
+
+**Cons:**
+- Limited to single instance
+- Shares resources with MCP server
+
+#### 3. Network Mode
+
+For production deployments with a dedicated Qdrant service:
+
+```dotenv
+# Network mode configuration
+QDRANT_URL=http://qdrant:6333
+QDRANT_API_KEY=your-secret-api-key  # Optional
+QDRANT_COLLECTION=nextcloud_content  # Optional
+ENABLE_SEMANTIC_SEARCH=true
+```
+
+**Pros:**
+- Scalable and performant
+- Can be shared across multiple MCP instances
+- Supports clustering and replication
+
+**Cons:**
+- Requires separate Qdrant service
+- More complex deployment
+
+### Qdrant Collection Naming
+
+Collection names are automatically generated to include the embedding model, ensuring safe model switching and preventing dimension mismatches.
+
+#### Auto-Generated Naming (Default)
+
+**Format:** `{deployment-id}-{model-name}`
+
+**Components:**
+- **Deployment ID:** `OTEL_SERVICE_NAME` (if configured) or `hostname` (fallback)
+- **Model name:** `OLLAMA_EMBEDDING_MODEL`
+
+**Examples:**
+
+```bash
+# With OTEL service name configured
+OTEL_SERVICE_NAME=my-mcp-server
+OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+# → Collection: "my-mcp-server-nomic-embed-text"
+
+# Simple Docker deployment (OTEL not configured)
+# hostname=mcp-container
+OLLAMA_EMBEDDING_MODEL=all-minilm
+# → Collection: "mcp-container-all-minilm"
+```
+
+#### Switching Embedding Models
+
+When you change `OLLAMA_EMBEDDING_MODEL`, a new collection is automatically created:
+
+```bash
+# Initial setup
+OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+# Collection: "my-server-nomic-embed-text" (768 dimensions)
+
+# Change model
+OLLAMA_EMBEDDING_MODEL=all-minilm
+# Collection: "my-server-all-minilm" (384 dimensions)
+# → New collection created, full re-embedding occurs
+```
+
+**Important:**
+- **Collections are mutually exclusive** - vectors cannot be shared between different embedding models
+- **Switching models requires re-embedding** all documents (may take time for large note collections)
+- **Old collection remains** in Qdrant and can be deleted manually if no longer needed
+
+#### Explicit Override
+
+Set `QDRANT_COLLECTION` to use a specific collection name:
+
+```bash
+QDRANT_COLLECTION=my-custom-collection  # Bypasses auto-generation
+```
+
+**Use cases:**
+- Backward compatibility with existing deployments
+- Custom naming schemes
+- Sharing a collection across deployments (advanced)
+
+#### Multi-Server Deployments
+
+Each server should have a unique deployment ID to avoid collection collisions:
+
+```bash
+# Server 1 (Production)
+OTEL_SERVICE_NAME=mcp-prod
+OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+# → Collection: "mcp-prod-nomic-embed-text"
+
+# Server 2 (Staging)
+OTEL_SERVICE_NAME=mcp-staging
+OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+# → Collection: "mcp-staging-nomic-embed-text"
+
+# Server 3 (Different model)
+OTEL_SERVICE_NAME=mcp-experimental
+OLLAMA_EMBEDDING_MODEL=bge-large
+# → Collection: "mcp-experimental-bge-large"
+```
+
+**Benefits:**
+- Multiple MCP servers can share one Qdrant instance safely
+- No naming collisions between deployments
+- Clear collection ownership (can see which deployment and model)
+
+#### Dimension Validation
+
+The server validates collection dimensions on startup:
+
+```
+Dimension mismatch for collection 'my-server-nomic-embed-text':
+  Expected: 384 (from embedding model 'all-minilm')
+  Found: 768
+This usually means you changed the embedding model.
+Solutions:
+  1. Delete the old collection: Collection will be recreated with new dimensions
+  2. Set QDRANT_COLLECTION to use a different collection name
+  3. Revert OLLAMA_EMBEDDING_MODEL to the original model
+```
+
+**What this prevents:**
+- Runtime errors from dimension mismatches
+- Data corruption in Qdrant
+- Confusing error messages during indexing
+
+### Background Indexing Configuration
+
+Control background indexing behavior:
+
+```dotenv
+# Semantic search (ADR-007, ADR-021)
+ENABLE_SEMANTIC_SEARCH=true           # Enable background indexing
+
+# Tuning parameters (advanced - only modify if needed)
+VECTOR_SYNC_SCAN_INTERVAL=300         # Scan interval in seconds (default: 5 minutes)
+VECTOR_SYNC_PROCESSOR_WORKERS=3       # Concurrent indexing workers (default: 3)
+VECTOR_SYNC_QUEUE_MAX_SIZE=10000      # Max queued documents (default: 10000)
+
+# Document chunking settings (for vector embeddings)
+DOCUMENT_CHUNK_SIZE=512               # Words per chunk (default: 512)
+DOCUMENT_CHUNK_OVERLAP=50             # Overlapping words between chunks (default: 50)
+```
+
+> **Note:** The `VECTOR_SYNC_*` tuning parameters keep their names as they're implementation details. Only the user-facing feature flag was renamed to `ENABLE_SEMANTIC_SEARCH`.
+
+### Embedding Service Configuration
+
+The server uses an embedding service to generate vector representations. Two options are available:
+
+#### Ollama (Recommended)
+
+Use a local Ollama instance for embeddings:
+
+```dotenv
+OLLAMA_BASE_URL=http://ollama:11434
+OLLAMA_EMBEDDING_MODEL=nomic-embed-text  # Default model
+OLLAMA_VERIFY_SSL=true                   # Verify SSL certificates
+```
+
+#### Simple Embedding Provider (Fallback)
+
+If `OLLAMA_BASE_URL` is not set, the server uses a simple random embedding provider for testing. This is **not suitable for production** as it generates random embeddings with no semantic meaning.
+
+### Document Chunking Configuration
+
+The server chunks documents before embedding to handle documents larger than the embedding model's context window. Chunk size and overlap can be tuned based on your embedding model and content type.
+
+#### Choosing Chunk Size
+
+**Smaller chunks (256-384 words)**:
+- More precise matching
+- Less context per chunk
+- Better for finding specific information
+- Higher storage requirements (more vectors)
+
+**Larger chunks (768-1024 words)**:
+- More context per chunk
+- Less precise matching
+- Better for understanding broader topics
+- Lower storage requirements (fewer vectors)
+
+**Default (512 words)**:
+- Balanced approach suitable for most use cases
+- Works well with typical note lengths
+- Good compromise between precision and context
+
+#### Choosing Overlap
+
+Overlap preserves context across chunk boundaries. Recommended settings:
+
+- **10-20% of chunk size** (e.g., 50-100 words for 512-word chunks)
+- **Too small** (<10%): May lose context at boundaries
+- **Too large** (>20%): Redundant storage, diminishing returns
+
+**Examples**:
+```dotenv
+# Precise matching for short notes
+DOCUMENT_CHUNK_SIZE=256
+DOCUMENT_CHUNK_OVERLAP=25
+
+# Default balanced configuration
+DOCUMENT_CHUNK_SIZE=512
+DOCUMENT_CHUNK_OVERLAP=50
+
+# More context for long documents
+DOCUMENT_CHUNK_SIZE=1024
+DOCUMENT_CHUNK_OVERLAP=100
+```
+
+**Important**: Changing chunk size requires re-embedding all documents. The collection naming strategy (see "Qdrant Collection Naming" above) helps manage this by creating separate collections for different configurations.
+
+### Environment Variables Reference
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `ENABLE_SEMANTIC_SEARCH` | ⚠️ Optional | `false` | Enable semantic search with background indexing (replaces `VECTOR_SYNC_ENABLED`) |
+| `QDRANT_URL` | ⚠️ Optional | - | Qdrant service URL (network mode) - mutually exclusive with `QDRANT_LOCATION` |
+| `QDRANT_LOCATION` | ⚠️ Optional | `:memory:` | Local Qdrant path (`:memory:` or `/path/to/data`) - mutually exclusive with `QDRANT_URL` |
+| `QDRANT_API_KEY` | ⚠️ Optional | - | Qdrant API key (network mode only) |
+| `QDRANT_COLLECTION` | ⚠️ Optional | Auto-generated | Qdrant collection name |
+| `VECTOR_SYNC_SCAN_INTERVAL` | ⚠️ Optional | `300` | Document scan interval (seconds) |
+| `VECTOR_SYNC_PROCESSOR_WORKERS` | ⚠️ Optional | `3` | Concurrent indexing workers |
+| `VECTOR_SYNC_QUEUE_MAX_SIZE` | ⚠️ Optional | `10000` | Max queued documents |
+| `OLLAMA_BASE_URL` | ⚠️ Optional | - | Ollama API endpoint for embeddings |
+| `OLLAMA_EMBEDDING_MODEL` | ⚠️ Optional | `nomic-embed-text` | Embedding model to use |
+| `OLLAMA_VERIFY_SSL` | ⚠️ Optional | `true` | Verify SSL certificates |
+| `DOCUMENT_CHUNK_SIZE` | ⚠️ Optional | `512` | Words per chunk for document embedding |
+| `DOCUMENT_CHUNK_OVERLAP` | ⚠️ Optional | `50` | Overlapping words between chunks (must be < chunk size) |
+
+**Deprecated variables (still functional):**
+- `VECTOR_SYNC_ENABLED` - Use `ENABLE_SEMANTIC_SEARCH` instead (will be removed in v1.0.0)
+
+### Docker Compose Example
+
+Enable network mode Qdrant with docker-compose:
+
+```yaml
+services:
+  mcp:
+    environment:
+      - QDRANT_URL=http://qdrant:6333
+      - ENABLE_SEMANTIC_SEARCH=true
+
+  qdrant:
+    image: qdrant/qdrant:latest
+    ports:
+      - 127.0.0.1:6333:6333
+    volumes:
+      - qdrant-data:/qdrant/storage
+    profiles:
+      - qdrant  # Optional service
+
+volumes:
+  qdrant-data:
+```
+
+Start with Qdrant service:
+```bash
+docker-compose --profile qdrant up
+```
+
+Or use default in-memory mode (no `--profile` needed):
+```bash
+docker-compose up
+```
+
+---
+
 ## Loading Environment Variables
 
 After creating your `.env` file, load the environment variables:
@@ -160,10 +633,6 @@ Options:
                                   NEXTCLOUD_OIDC_CLIENT_ID env var)
   --oauth-client-secret TEXT      OAuth client secret (can also use
                                   NEXTCLOUD_OIDC_CLIENT_SECRET env var)
-  --oauth-storage-path TEXT       Path to store OAuth client credentials
-                                  (can also use
-                                  NEXTCLOUD_OIDC_CLIENT_STORAGE env var)
-                                  [default: .nextcloud_oauth_client.json]
   --mcp-server-url TEXT           MCP server URL for OAuth callbacks (can
                                   also use NEXTCLOUD_MCP_SERVER_URL env
                                   var)  [default: http://localhost:8000]
@@ -225,10 +694,7 @@ uv run nextcloud-mcp-server --no-oauth \
 - Store OAuth client credentials securely
 - Use environment variables from your deployment platform (Docker secrets, Kubernetes ConfigMaps, etc.)
 - Never commit credentials to version control
-- Set appropriate file permissions on credential storage:
-  ```bash
-  chmod 600 .nextcloud_oauth_client.json
-  ```
+- SQLite database permissions are handled automatically by the server
 
 ### For Docker
 
@@ -243,6 +709,7 @@ uv run nextcloud-mcp-server --no-oauth \
 
 ## See Also
 
+- [Configuration Migration Guide v2](configuration-migration-v2.md) - **New in v0.58.0:** Migrate from old variable names
 - [OAuth Quick Start](quickstart-oauth.md) - 5-minute OAuth setup for development
 - [OAuth Setup Guide](oauth-setup.md) - Detailed OAuth configuration for production
 - [OAuth Architecture](oauth-architecture.md) - How OAuth works in the MCP server
@@ -251,3 +718,4 @@ uv run nextcloud-mcp-server --no-oauth \
 - [Running the Server](running.md) - Starting the server with different configurations
 - [Troubleshooting](troubleshooting.md) - Common configuration issues
 - [OAuth Troubleshooting](oauth-troubleshooting.md) - OAuth-specific troubleshooting
+- [ADR-021](ADR-021-configuration-consolidation.md) - Configuration consolidation architecture decision

docs/database-migrations.md

@@ -0,0 +1,301 @@
+# Database Migrations
+
+This document describes the database migration system for nextcloud-mcp-server's token storage database.
+
+## Overview
+
+The token storage database uses [Alembic](https://alembic.sqlalchemy.org/) for schema versioning and migrations. Alembic provides:
+
+- **Version Control**: Track schema changes in Git
+- **Rollback Support**: Safely downgrade schema if needed
+- **Audit Trail**: Migration files serve as schema changelog
+- **Automated Upgrades**: Database schema updates automatically on startup
+
+## Architecture
+
+### Migration Strategy
+
+The system handles three scenarios:
+
+1. **New Database**: Runs migrations from scratch to create all tables
+2. **Pre-Alembic Database**: Stamps existing database with initial revision (no changes)
+3. **Alembic-Managed Database**: Upgrades to latest version automatically
+
+### Directory Structure
+
+```
+nextcloud-mcp-server/
+├── alembic/                              # Alembic migrations
+│   ├── versions/                         # Migration scripts
+│   │   └── 20251217_2200_001_initial_schema.py
+│   ├── env.py                            # Alembic environment
+│   ├── script.py.mako                    # Migration template
+│   └── README                            # Migration usage guide
+├── alembic.ini                           # Alembic configuration
+└── nextcloud_mcp_server/
+    ├── auth/storage.py                   # Uses migrations on init
+    └── migrations.py                     # Migration utilities
+```
+
+## Usage
+
+### Automatic Migration on Startup
+
+Migrations run automatically when the server starts:
+
+```bash
+uv run nextcloud-mcp-server
+```
+
+The `RefreshTokenStorage.initialize()` method:
+1. Checks if database is Alembic-managed
+2. Stamps pre-Alembic databases with initial revision
+3. Upgrades to latest version
+
+### Manual Migration Commands
+
+```bash
+# Show current database version
+uv run nextcloud-mcp-server db current
+
+# Upgrade database to latest version
+uv run nextcloud-mcp-server db upgrade
+
+# Show migration history
+uv run nextcloud-mcp-server db history
+
+# Downgrade by one version (emergency use only)
+uv run nextcloud-mcp-server db downgrade
+
+# Specify custom database path
+uv run nextcloud-mcp-server db current -d /path/to/tokens.db
+```
+
+### Environment Variables
+
+- `TOKEN_STORAGE_DB`: Path to database file (default: `/app/data/tokens.db`)
+
+## Creating Migrations (Developers)
+
+### Step 1: Create Migration File
+
+```bash
+uv run nextcloud-mcp-server db migrate "add user preferences table"
+```
+
+This creates a new migration file in `alembic/versions/` with empty `upgrade()` and `downgrade()` functions.
+
+### Step 2: Write Migration SQL
+
+Since we don't use SQLAlchemy models, write raw SQL:
+
+```python
+def upgrade() -> None:
+    """Add user preferences table."""
+    op.execute("""
+        CREATE TABLE user_preferences (
+            user_id TEXT PRIMARY KEY,
+            theme TEXT DEFAULT 'light',
+            language TEXT DEFAULT 'en',
+            created_at INTEGER NOT NULL
+        )
+    """)
+
+    op.execute("""
+        CREATE INDEX idx_user_preferences_user_id
+        ON user_preferences(user_id)
+    """)
+
+
+def downgrade() -> None:
+    """Remove user preferences table."""
+    op.execute("DROP INDEX IF EXISTS idx_user_preferences_user_id")
+    op.execute("DROP TABLE IF EXISTS user_preferences")
+```
+
+### Step 3: Test Migration
+
+```bash
+# Test upgrade
+uv run nextcloud-mcp-server db upgrade -d /tmp/test.db
+
+# Verify schema
+sqlite3 /tmp/test.db ".schema"
+
+# Test downgrade
+uv run nextcloud-mcp-server db downgrade -d /tmp/test.db
+
+# Verify removal
+sqlite3 /tmp/test.db ".schema"
+```
+
+### Step 4: Commit Migration
+
+```bash
+git add alembic/versions/YYYYMMDD_HHMM_XXX_description.py
+git commit -m "feat: add user preferences table migration"
+```
+
+## SQLite Limitations
+
+SQLite has limited `ALTER TABLE` support:
+
+### Supported Operations
+
+- ✅ Add columns: `ALTER TABLE table ADD COLUMN ...`
+- ✅ Rename table: `ALTER TABLE old RENAME TO new`
+- ✅ Rename column: `ALTER TABLE table RENAME COLUMN old TO new` (SQLite 3.25+)
+
+### Unsupported Operations (Requires Table Recreation)
+
+- ❌ Drop column
+- ❌ Change column type
+- ❌ Add constraints to existing columns
+
+### Table Recreation Pattern
+
+For complex schema changes:
+
+```python
+def upgrade() -> None:
+    # Create new table with desired schema
+    op.execute("""
+        CREATE TABLE refresh_tokens_new (
+            user_id TEXT PRIMARY KEY,
+            encrypted_token BLOB NOT NULL,
+            new_field TEXT,  -- New column
+            expires_at INTEGER,
+            created_at INTEGER NOT NULL
+        )
+    """)
+
+    # Copy data from old table
+    op.execute("""
+        INSERT INTO refresh_tokens_new
+        (user_id, encrypted_token, expires_at, created_at)
+        SELECT user_id, encrypted_token, expires_at, created_at
+        FROM refresh_tokens
+    """)
+
+    # Drop old table and rename new table
+    op.execute("DROP TABLE refresh_tokens")
+    op.execute("ALTER TABLE refresh_tokens_new RENAME TO refresh_tokens")
+
+    # Recreate indexes
+    op.execute("CREATE INDEX idx_user_id ON refresh_tokens(user_id)")
+```
+
+## Best Practices
+
+### Naming Conventions
+
+- **Migrations**: `YYYYMMDD_HHMM_XXX_description.py`
+- **Revision IDs**: Sequential numbers (`001`, `002`, `003`)
+- **Descriptions**: Imperative mood ("add table", "remove column")
+
+### Migration Guidelines
+
+1. **Test Thoroughly**: Test both upgrade and downgrade paths
+2. **Preserve Data**: Ensure data migration logic is correct
+3. **Document Changes**: Add comments explaining complex operations
+4. **Small Changes**: One logical change per migration
+5. **No Breaking Changes**: Maintain backward compatibility when possible
+
+### Downgrade Considerations
+
+- **Data Loss**: Downgrade may lose data (dropped columns, tables)
+- **Confirmation**: Downgrade command requires explicit confirmation
+- **Testing**: Always test downgrade path before deploying
+- **Emergency Only**: Use downgrades only for critical rollbacks
+
+## Backward Compatibility
+
+### Pre-Alembic Databases
+
+Existing databases created before Alembic integration are automatically detected and stamped with revision `001`:
+
+1. Server detects no `alembic_version` table
+2. Checks if `refresh_tokens` table exists
+3. If yes, stamps database with `001` (no schema changes)
+4. Future updates use normal migration path
+
+### Migration Path
+
+```
+Pre-Alembic DB → Stamp(001) → Upgrade(002) → Upgrade(003) → ...
+New DB → Migrate(001) → Upgrade(002) → Upgrade(003) → ...
+```
+
+## Troubleshooting
+
+### Migration Fails
+
+```bash
+# Check current state
+uv run nextcloud-mcp-server db current -d /path/to/tokens.db
+
+# View migration history
+uv run nextcloud-mcp-server db history -d /path/to/tokens.db
+
+# Manually inspect database
+sqlite3 /path/to/tokens.db ".schema"
+```
+
+### Reset to Initial State
+
+**WARNING: This destroys all data!**
+
+```bash
+# Downgrade to base (empty database)
+uv run nextcloud-mcp-server db downgrade -d /path/to/tokens.db --revision base
+
+# Upgrade to latest
+uv run nextcloud-mcp-server db upgrade -d /path/to/tokens.db
+```
+
+### Corrupted Migration State
+
+If `alembic_version` table is corrupted:
+
+```bash
+# Manually fix via SQL
+sqlite3 /path/to/tokens.db
+> DELETE FROM alembic_version;
+> INSERT INTO alembic_version (version_num) VALUES ('001');
+> .quit
+
+# Verify and upgrade
+uv run nextcloud-mcp-server db current -d /path/to/tokens.db
+uv run nextcloud-mcp-server db upgrade -d /path/to/tokens.db
+```
+
+## CI/CD Integration
+
+### Pre-Deployment
+
+```bash
+# Run migrations in test environment
+export TOKEN_STORAGE_DB=/app/data/tokens.db
+uv run nextcloud-mcp-server db upgrade
+
+# Verify current version
+uv run nextcloud-mcp-server db current
+```
+
+### Docker Deployment
+
+Migrations run automatically on container startup via `RefreshTokenStorage.initialize()`.
+
+### Rollback Plan
+
+1. Stop application
+2. Backup database: `cp tokens.db tokens.db.backup`
+3. Downgrade: `uv run nextcloud-mcp-server db downgrade --revision XXX`
+4. Deploy previous application version
+5. Restart application
+
+## References
+
+- [Alembic Documentation](https://alembic.sqlalchemy.org/)
+- [SQLite ALTER TABLE Limitations](https://www.sqlite.org/lang_altertable.html)
+- [ADR-004: Progressive Consent](./ADR-004-progressive-consent.md) (migration 001)