build: bump submodule

2025-11-16 11:20:51 +01:00
240 changed files with 4338 additions and 46327 deletions
@@ -5,5 +5,3 @@
 !uv.lock

 !nextcloud_mcp_server/**/*.py
-!nextcloud_mcp_server/**/*.html
-!nextcloud_mcp_server/auth/static/*
@@ -7,158 +7,26 @@ on:

 jobs:
  bump-version:
-    if: "!startsWith(github.event.head_commit.message, 'bump:') && !startsWith(github.event.head_commit.message, 'chore(release):')"
+    if: "!startsWith(github.event.head_commit.message, 'bump:')"
    runs-on: ubuntu-latest
-    name: "Bump version and create changelog for monorepo components"
+    name: "Bump version and create changelog with commitizen"
    permissions:
      contents: write
      packages: write
    steps:
      - name: Check out
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
        with:
          fetch-depth: 0
          token: "${{ secrets.PERSONAL_ACCESS_TOKEN }}"
-
-      - name: Set up Python
-        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+      - name: Create bump and changelog
+        uses: commitizen-tools/commitizen-action@5b0848cd060263e24602d1eba03710e056ef7711 # 0.24.0
        with:
-          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_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
+          changelog_increment_filename: body.md
+      - name: Release
+        uses: softprops/action-gh-release@5be0e66d93ac7ed76da52eca8bb058f665c3a5fe # v2.4.2
+        with:
+          body_path: "body.md"
+          tag_name: v${{ env.REVISION }}
+          token: ${{ secrets.GITHUB_TOKEN }}
@@ -1,58 +0,0 @@
-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@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
-        with:
-          fetch-depth: 1
-
-      - name: Run Claude Code Review
-        id: claude-review
-        uses: anthropics/claude-code-action@b113f49a56229d8276e2bf05743ad6900121239c # v1.0.45
-        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:*)"'
-
@@ -1,50 +0,0 @@
-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@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
-        with:
-          fetch-depth: 1
-
-      - name: Run Claude Code
-        id: claude
-        uses: anthropics/claude-code-action@b113f49a56229d8276e2bf05743ad6900121239c # v1.0.45
-        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:*)'
-
@@ -2,8 +2,7 @@ name: Build and Publish Docker Image

 on:
  push:
-    tags:
-      - "v*"
+    tags: ["*"]

 jobs:
  build-and-push:
@@ -13,11 +12,11 @@ jobs:
      packages: write
    steps:
      - name: Checkout repository
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5

      - name: Docker meta
        id: meta
-        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5
+        uses: docker/metadata-action@318604b99e75e41977312d83839a89be02ca4893 # v5
        with:
          # list of Docker images to use as base name for tags
          images: |
@@ -34,7 +33,7 @@ jobs:
            type=raw,value=latest,enable={{is_default_branch}}

      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3
+        uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # v3

      - name: Log in to GitHub Container Registry
        if: github.event_name != 'pull_request'
@@ -4,7 +4,6 @@ on:
  push:
    tags:
      - v*
-      - nextcloud-mcp-server-*

 jobs:
  release:
@@ -15,7 +14,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
        with:
          fetch-depth: 0

@@ -39,8 +38,6 @@ jobs:

      - name: Run chart-releaser
        uses: helm/chart-releaser-action@cae68fefc6b5f367a0275617c9f83181ba54714f # v1.7.0
-        with:
-          skip_existing: true
        env:
          CR_TOKEN: "${{ secrets.GITHUB_TOKEN }}"

@@ -1,105 +0,0 @@
-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@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
-
-      - 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@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
-
-      - 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@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5
-        with:
-          name: rag-evaluation-results
-          path: |
-            pytest-results.xml
-          retention-days: 30
@@ -18,9 +18,9 @@ jobs:
      contents: read
    steps:
      - name: Checkout
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
      - name: Install uv
-        uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
+        uses: astral-sh/setup-uv@5a7eac68fb9809dea845d802897dc5c723910fa3 # v7.1.3
      - name: Install Python 3.11
        run: uv python install 3.11
      - name: Build
@@ -9,9 +9,9 @@ jobs:
  linting:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
      - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
+        uses: astral-sh/setup-uv@5a7eac68fb9809dea845d802897dc5c723910fa3 # v7.1.3
      - name: Check format
        run: |
          uv run --frozen ruff format --diff
@@ -27,7 +27,7 @@ jobs:
    runs-on: ubuntu-latest

    steps:
-      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
        with:
          submodules: 'true'

@@ -35,7 +35,7 @@ jobs:
      ###### Required to build OIDC App ######

      - name: Set up php 8.4
-        uses: shivammathur/setup-php@44454db4f0199b8b9685a5d763dc37cbf79108e1 # v2
+        uses: shivammathur/setup-php@bf6b4fbd49ca58e4608c9c89fba0b8d90bd2a39f # v2
        with:
          php-version: 8.4
          coverage: none
@@ -49,14 +49,14 @@ jobs:


      - name: Run docker compose
-        uses: hoverkraft-tech/compose-action@4894d2492015c1774ee5a13a95b1072093087ec3 # v2.5.0
+        uses: hoverkraft-tech/compose-action@3846bcd61da338e9eaaf83e7ed0234a12b099b72 # v2.4.1
        with:
          compose-file: "./docker-compose.yml"
          #compose-flags: "--profile qdrant"
          up-flags: "--build"

      - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
+        uses: astral-sh/setup-uv@5a7eac68fb9809dea845d802897dc5c723910fa3 # v7.1.3

      - name: Install Playwright dependencies
        run: |
@@ -85,4 +85,4 @@ jobs:
          NEXTCLOUD_USERNAME: "admin"
          NEXTCLOUD_PASSWORD: "admin"
        run: |
-          uv run pytest -v --log-cli-level=WARN -m unit -m smoke
+          uv run pytest -v --log-cli-level=WARN -m smoke
@@ -13,6 +13,3 @@ docker-compose.override.yml
 # Generated by pytest used to login users
 .nextcloud_oauth_*.json
 .playwright-mcp/
-
-# RAG Evaluation
-tests/rag_evaluation/fixtures/
@@ -1,9 +1,9 @@
+[submodule "oidc"]
+	path = third_party/oidc
+	url = https://github.com/cbcoutinho/oidc
 [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
@@ -1,596 +1,3 @@
-# Changelog - MCP Server
-
-All notable changes to the Nextcloud MCP Server will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [PEP 440](https://peps.python.org/pep-0440/).
-
-## v0.63.4 (2026-02-08)
-
-### Fix
-
- strip whitespace from category names when splitting
- handle categories, recurrence_rule, attendees, and reminder_minutes in update_event
-
-## v0.63.3 (2026-02-08)
-
-### Fix
-
- expand recurring events in date-range queries
-
-## v0.63.2 (2026-02-07)
-
-### Fix
-
- use CalDAV time-range filter for calendar date range queries
-
-## v0.63.1 (2026-02-03)
-
-### Fix
-
- **helm**: add backward compatibility for legacy persistence configs
-
-## v0.63.0 (2026-01-28)
-
-### Feat
-
- **astrolabe**: add background token refresh job
-
-### Fix
-
- **astrolabe**: add pagination and psalm fixes for token refresh
- **astrolabe**: add locking to prevent token refresh race condition
- **astrolabe**: add issued_at to on-demand token refresh
-
-## v0.62.0 (2026-01-26)
-
-### Feat
-
- **scripts**: add database query helpers for development
-
-### Fix
-
- **astrolabe**: resolve Psalm type errors in PDF preview code
- **astrolabe**: fix Psalm baseline and ESLint import order
- **astrolabe**: load pdfjs-dist externally to fix PDF viewer
- **astrolabe**: improve error messages for authorization issues
- **astrolabe**: rename OAuthController and fix app password check
- **tests**: improve Astrolabe integration test reliability
- **astrolabe**: update Plotly title attributes for v3 compatibility
- **deps**: update dependency plotly.js-dist-min to v3
-
-### Refactor
-
- **api**: split management.py into domain-focused modules
- **astrolabe**: replace client-side PDF.js with server-side PyMuPDF rendering
-
-## v0.61.5 (2026-01-17)
-
-### Fix
-
- **astrolabe**: improve token refresh error handling and validation
- **astrolabe**: delete stale tokens when refresh fails
- **astrolabe**: resolve CI failures for code quality checks
- **astrolabe**: use internal URL for OAuth token refresh
-
-### Refactor
-
- **astrolabe**: add PHP property types to fix Psalm errors
- **astrolabe**: upgrade to @nextcloud/vue 9.3.3 API
-
-## v0.61.4 (2026-01-16)
-
-### Fix
-
- **astrolabe**: Address reviewer feedback for hybrid mode
- **astrolabe**: Fix NcSelect options and CSS loading
- **astrolabe**: fix OAuth flow and settings UI for hybrid mode
- **api**: return OIDC config in hybrid mode for Astrolabe OAuth flow
-
-## v0.61.3 (2026-01-15)
-
-### Fix
-
- **astrolabe**: address review feedback for Vue 3 bindings
- **astrolabe**: update Vue component bindings for Vue 3 compatibility
-
-## v0.61.2 (2026-01-15)
-
-### Fix
-
- **ci**: bump helm chart version when MCP appVersion changes
-
-## v0.61.1 (2026-01-15)
-
-### Fix
-
- **astrolabe**: define appName and appVersion for @nextcloud/vue
-
-## v0.61.0 (2026-01-14)
-
-### Feat
-
- Add rate limiting and extract helpers for app password endpoints
-
-### Fix
-
- Add missing annotations for deck remove/unassign operations
- **auth**: Store app passwords locally for multi-user BasicAuth background sync
-
-### Refactor
-
- Use get_settings() for vector sync enabled check
- Extract storage helper and improve PHP error handling
-
-## v0.60.4 (2026-01-12)
-
-### Fix
-
- **deck**: use correct endpoint for reorder_card to fix cross-stack moves
-
-## v0.60.3 (2025-12-31)
-
-### Fix
-
- **deck**: Always preserve fields in update_card for partial updates
- **astrolabe**: Fix CSS loading for Nextcloud apps
- **astrolabe**: Fix revoke access button HTTP method mismatch
-
-## v0.60.2 (2025-12-29)
-
-### Fix
-
- **oauth**: Enable browser OAuth routes for Management API in hybrid mode
-
-## v0.60.1 (2025-12-26)
-
-### Fix
-
- **mcp**: Move all imports to the top of modules
-
-## v0.60.0 (2025-12-26)
-
-### Feat
-
- Remove URL rewriting in favor of proper nextcloud config
- **helm**: migrate to new environment variable naming convention
- Migrate to vue 3
- **astrolabe**: upgrade to Vue 3 and @nextcloud/vue 9
-
-### Fix
-
- **tests**: Add singleton reset fixture to prevent anyio.WouldBlock errors
- **tests**: Fix integration test failures in qdrant, sampling, and rag tests
- **auth**: Skip issuer validation for management API tokens
- Use settings.enable_offline_access for env var consolidation
- Add required config.py attributes
- **docker**: remove overwritehost to fix container-to-container DCR
- **deps**: update dependency @nextcloud/vue to v9
- **deps**: update dependency vue to v3
-
-### Refactor
-
- **auth**: Decouple BasicAuth and OAuth authentication strategies
-
-## v0.59.1 (2025-12-22)
-
-### Fix
-
- **helm**: set OIDC client env vars when using existingSecret
- **helm**: trigger chart release workflow on helm chart tags
-
-## v0.59.0 (2025-12-22)
-
-### Feat
-
- **helm**: add support for multi-user BasicAuth mode
-
-### Fix
-
- **helm**: address PR #447 reviewer feedback
- **helm**: include MCP server version bumps in changelog pattern
-
-## v0.58.0 (2025-12-22)
-
-### Feat
-
- **config**: enable DCR for multi-user BasicAuth with offline access
- **astrolabe**: implement app password provisioning for multi-user background sync
- **config**: consolidate configuration with smart dependency resolution (ADR-021)
-
-## v0.57.0 (2025-12-20)
-
-### Feat
-
- **auth**: add multi-user BasicAuth pass-through mode
- **astrolabe**: add dynamic MCP server configuration for testing
-
-### Fix
-
- **config**: address reviewer feedback
-
-### Refactor
-
- **config**: centralize configuration validation and simplify startup
-
-## v0.56.2 (2025-12-20)
-
-### Fix
-
- **astrolabe**: screenshots in info.xml
- **astrolabe**: screenshots in info.xml
-
-## v0.56.1 (2025-12-19)
-
-### Fix
-
- **astrolabe**: Update screenshots
- **ci**: skip existing Helm chart releases to prevent duplicate release errors
-
-## v0.56.0 (2025-12-19)
-
-### Feat
-
- **ci**: add --increment flag to bump scripts for manual version control
-
-### Fix
-
- **astrolabe**: add contents:write permission to appstore workflow
- **astrolabe**: update commitizen pattern to properly update info.xml version
- **astrolabe**: prevent workflow failure when only helm/astrolabe commits exist
- **astrolabe**: info.xml
-
-## v0.55.1 (2025-12-19)
-
-### Fix
-
- **ci**: push all tags explicitly in bump workflow
-
-## v0.55.0 (2025-12-19)
-
-### BREAKING CHANGE
-
- MCP server now bumps for ANY conventional commit except
-those explicitly scoped to helm or astrolabe.
-
-### Feat
-
- **ci**: implement monorepo-aware version bumping workflow
-
-### Fix
-
- **ci**: make MCP server default bump target for all non-scoped commits
- **ci**: restrict docker build to MCP server tags only
- **ci**: correct appstore-push-action version to v1.0.4
-
-## v0.54.0 (2025-12-19)
-
-### Feat
-
- **astrolabe**: add Nextcloud App Store deployment automation
- configure commitizen monorepo with independent versioning
-
-### Fix
-
- **ci**: improve versioning and error handling
- **ci**: address critical workflow and validation issues
- **astrolabe**: address code review feedback
-
-## v0.53.0 (2025-12-19)
-
-### Feat
-
- add Alembic database migration system
- make chunk modal title clickable link to documents
- add native Plotly hover styling for clickable points
- add click interactivity to Plotly 3D scatter chart
- improve chunk viewer with fixed navigation and markdown rendering
- **astrolabe**: enable multi-select for document types and refactor PDF viewer
- **auth**: implement refresh token rotation for Nextcloud OIDC
- **astrolabe**: enhance unified search and add webhook management
- **astrolabe**: add webhook management UI to admin settings
- **astrolabe**: add OAuth token refresh and webhook presets
- **search**: add file_path metadata and chunk offsets to search results
- **astrolabe**: use proper icons and thumbnails in unified search
- **astrolabe**: add admin search settings and enhanced UI
- **astrolabe**: add unified search provider with clickable file links
- **astrolabe**: add 3D PCA visualization for semantic search
- **astrolabe**: add Nextcloud PHP app for MCP server management
- **vector-sync**: enable background sync in OAuth mode
-
-### Fix
-
- **security**: address critical security issues from PR #401 code review
- **oauth**: enable PKCE for all clients and add token_broker to oauth_context
- **astrolabe**: revert invalid files_pdfviewer URL for file links
- resolve type checking warnings for CI
- move Alembic to package submodule for Docker compatibility
- update unified search results to match chunk viz display
- **astrolabe**: handle OAuth refresh token rotation
- address critical code review issues (4 fixes)
- resolve CI linting issues for Astroglobe
-
-### Refactor
-
- **astrolabe**: extract PDF viewer to dedicated component
- **astrolabe**: reframe UI as semantic search service
-
-## v0.52.1 (2025-12-13)
-
-### Perf
-
- **deck**: optimize card lookup by storing board_id/stack_id in metadata
-
-## v0.52.0 (2025-12-13)
-
-### Feat
-
- **vector**: add Deck card vector search with visualization support
-
-## v0.51.0 (2025-12-13)
-
-### Feat
-
- **vector-viz**: add news_item support for links and chunk expansion
-
-## v0.50.2 (2025-12-13)
-
-### Fix
-
- **news**: revert get_item() to use get_items() + filter
-
-## v0.50.1 (2025-12-12)
-
-### Fix
-
- Disable DNS rebinding protection for containerized deployments
- **deps**: update dependency mcp to >=1.23,<1.24
-
-## v0.50.0 (2025-12-11)
-
-### Feat
-
- add MCP tool annotations for enhanced UX
-
-### Fix
-
- address PR review feedback
-
-## v0.49.2 (2025-12-09)
-
-### Fix
-
- Update lockfile
-
-## v0.49.1 (2025-12-09)
-
-### Fix
-
- Revert mcp version <1.23
-
-## v0.49.0 (2025-12-08)
-
-### Feat
-
- **news**: add Nextcloud News app integration
-
-### Fix
-
- resolve all type checking errors (8 errors fixed)
-
-### Refactor
-
- **news**: simplify vector sync to fetch all items
-
-### Perf
-
- **news**: use direct API endpoint for get_item()
-
-## v0.48.6 (2025-12-03)
-
-### Fix
-
- **deps**: update dependency mcp to >=1.23,<1.24
-
-## v0.48.5 (2025-11-28)
-
-### Fix
-
- **deps**: update dependency pillow to v12
-
-## v0.48.4 (2025-11-23)
-
-### Fix
-
- Add rate limit retry logic to OpenAI provider
-
-## v0.48.3 (2025-11-23)
-
-### Fix
-
- Increase MCP sampling timeout to 5 minutes for slower LLMs
-
-## v0.48.2 (2025-11-23)
-
-### Fix
-
- Share vector sync state with FastMCP session lifespan via module singleton
- Share vector sync state with FastMCP session lifespan via module singleton
-
-## v0.48.1 (2025-11-23)
-
-### Fix
-
- Use WebDAV for tag creation and add LLM-as-a-judge for RAG tests
-
-### Refactor
-
- Move background tasks to server lifespan and deprecate SSE transport
-
-## v0.48.0 (2025-11-23)
-
-### Feat
-
- Add tag management methods to WebDAV client
-
-## v0.47.0 (2025-11-23)
-
-### Feat
-
- Add OpenAI provider support for embeddings and generation
-
-## v0.46.2 (2025-11-22)
-
-### Fix
-
- **smithery**: Enable JSON response format for scanner compatibility
-
-## v0.46.1 (2025-11-22)
-
-### Perf
-
- Optimize vector viz search performance
-
-## v0.46.0 (2025-11-22)
-
-### Feat
-
- Add Smithery CLI deployment support
- Implement ADR-016 Smithery stateless deployment mode
-
-### Fix
-
- **smithery**: Add JSON Schema metadata to mcp-config endpoint
- **smithery**: Use container runtime pattern for config discovery
- Add Smithery lifespan and auth mode detection
-
-## v0.45.0 (2025-11-22)
-
-### Feat
-
- Add context expansion to semantic search with chunk overlap removal
- Use Ollama native batch API in embed_batch()
- Implement Qdrant placeholder state management
- Switch files to use numeric IDs with file_path resolution
- Implement per-chunk vector visualization with context expansion
-
-### Fix
-
- Use alpha_composite for proper RGBA highlight blending
- Remove pymupdf.layout.activate() to fix page_chunks behavior
- Centralize PDF processing and generate separate images per chunk
- Set is_placeholder=False in processor to fix search filtering
- Increase placeholder staleness threshold to 5x scan interval
- Add placeholder staleness check to prevent duplicate processing
- Use empty SparseVector instead of None for placeholders
- Return empty array instead of null for query_coords when no results
- Align PDF text extraction between indexing and context expansion
- Update models and viz to use int-only doc_id
- Reconstruct full content for notes to match indexed offsets
- Add async/await, PDF metadata, and type safety fixes
-
-### Refactor
-
- Simplify PDF text extraction with single to_markdown call
-
-### Perf
-
- Optimize PDF processing with parallel extraction and single-render highlights
-
-## v0.44.1 (2025-11-21)
-
-### Fix
-
- **deps**: update dependency mcp to >=1.22,<1.23
-
-## v0.44.0 (2025-11-19)
-
-### Feat
-
- Improve vector visualization with static assets and fixes
- Redesign UI to match Nextcloud ecosystem aesthetic
-
-### Fix
-
- Improve 3D plot rendering with explicit dimensions and window resize support
- Preserve 3D plot camera and improve documentation
- Preserve 3D plot camera position and fix CSS loading
-
-## v0.43.0 (2025-11-18)
-
-### Feat
-
- Replace custom document chunker with LangChain MarkdownTextSplitter
-
-## v0.42.0 (2025-11-17)
-
-### Feat
-
- **viz**: Add dual-score display and improve UI controls
-
-## v0.41.0 (2025-11-17)
-
-### Feat
-
- add configurable fusion algorithms for BM25 hybrid search
- add chunk position tracking to vector indexing and search
- add vector viz template and chunk context endpoint
-
-### Fix
-
- prevent infinite loop in DocumentChunker with position tracking
- Relax SearchResult validation to support DBSF fusion scores > 1.0
-
-## v0.40.0 (2025-11-16)
-
-### Feat
-
- add unified provider architecture with Amazon Bedrock support
-
-### Fix
-
- suppress Starlette middleware type warnings in ty checker
-
-## v0.39.0 (2025-11-16)
-
-### Feat
-
- Implement BM25 hybrid search with native Qdrant RRF fusion
-
-### Fix
-
- Handle named vectors in visualization and semantic search
- Update vizApp to use bm25_hybrid algorithm and remove deprecated weights
- Update viz routes to use BM25 hybrid search after refactor
-
-## v0.38.0 (2025-11-16)
-
-### Feat
-
- add concurrent uploads and --force flag to upload command
- implement RAG evaluation framework with CLI tooling
-
-### Fix
-
- download qrels from BEIR ZIP instead of HuggingFace
-
-### Refactor
-
- migrate asyncio to anyio for consistent structured concurrency
- replace httpx client with NextcloudClient in upload command
-
-### Perf
-
- Eliminate double-fetching in semantic search sampling
- fix vector viz search performance and visual encoding
- make note deletion concurrent in upload --force
-
-## v0.37.0 (2025-11-16)
-
-### Feat
-
- Add OpenTelemetry tracing to @instrument_tool decorator
-
 ## v0.36.0 (2025-11-15)

 ### BREAKING CHANGE
@@ -5,29 +5,23 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## Coding Conventions

 ### async/await Patterns
- **Use anyio for all async operations** - Provides structured concurrency
+- **Use anyio + asyncio hybrid** - Both libraries are available
  - 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()`)
+  - asyncio used in auth modules (refresh_token_storage.py, token_exchange.py, token_broker.py)
+  - anyio used in calendar.py, client_registration.py, app.py
  - 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
-  ```
+- **No explicit type checker configured** - Ruff handles linting only

 ### Code Quality
- **Run ruff and ty before committing**:
+- **Run ruff 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)

@@ -56,127 +50,13 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
  - 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
@@ -239,25 +119,6 @@ uv run python -m tests.load.benchmark --output results.json --verbose

 **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`:
-
-```bash
-# Basic query
-./scripts/dbquery.py "SELECT COUNT(*) FROM oc_users"
-
-# 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"
-```
-
-### Direct Docker Access
-
-For interactive sessions or complex operations:
-
 ```bash
 # Connect to database
 docker compose exec db mariadb -u root -ppassword nextcloud
@@ -283,40 +144,6 @@ docker compose exec db mariadb -u root -ppassword nextcloud -e \
 - `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:
-
-```bash
-# List tables
-./scripts/sqlitequery.py ".tables"
-
-# 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"
-```
-
-**Services**: `mcp` (default), `oauth`, `keycloak`, `basic`
-
-**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
-
 ## Architecture Quick Reference

 **For detailed architecture, see:**
@@ -559,29 +386,6 @@ docker compose exec app php occ user_oidc:provider keycloak
 **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
@@ -1,106 +0,0 @@
-# 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.
@@ -1,28 +1,17 @@
-FROM docker.io/library/python:3.12-slim-trixie@sha256:9e01bf1ae5db7649a236da7be1e94ffbbbdd7a93f867dd0d8d5720d9e1f89fab
-
-COPY --from=ghcr.io/astral-sh/uv:0.10.0@sha256:78a7ff97cd27b7124a5f3c2aefe146170793c56a1e03321dd31a289f6d82a04f /uv /uvx /bin/
+FROM ghcr.io/astral-sh/uv:0.9.9-python3.11-alpine@sha256:0faa7934fac1db7f5056f159c1224d144bab864fd2677a4066d25a686ae32edd

 # 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
+RUN apk add --no-cache git sqlite

 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 --no-editable --no-cache
+RUN uv sync --locked --no-dev --no-editable

 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", "run", "--host", "0.0.0.0"]
+ENTRYPOINT ["/app/.venv/bin/nextcloud-mcp-server", "--host", "0.0.0.0"]
@@ -1,44 +0,0 @@
-# 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:9e01bf1ae5db7649a236da7be1e94ffbbbdd7a93f867dd0d8d5720d9e1f89fab
-
-WORKDIR /app
-
-# Install uv for fast dependency management
-COPY --from=ghcr.io/astral-sh/uv:0.10.0@sha256:78a7ff97cd27b7124a5f3c2aefe146170793c56a1e03321dd31a289f6d82a04f /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"]
@@ -1,11 +1,6 @@
-<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)

 **A production-ready MCP server that connects AI assistants to your Nextcloud instance.**

@@ -18,20 +13,7 @@ This is a **dedicated standalone MCP server** designed for external MCP clients

 ## Quick Start

-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:
+Get up and running in 60 seconds using Docker:

 ```bash
 # 1. Create a minimal configuration
@@ -47,15 +29,10 @@ docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \

 # 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
 ```

 **Next Steps:**
+- Create an app password in Nextcloud: Settings → Security → Devices & sessions
 - Connect your MCP client (Claude Desktop, IDEs, `mcp dev`, etc.)
 - See [docs/installation.md](docs/installation.md) for other deployment options (local, Kubernetes)

@@ -63,7 +40,7 @@ http://127.0.0.1:8000/mcp

 - **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)
+- **Semantic Search (Experimental)** - Optional vector-powered search for Notes (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)
@@ -81,7 +58,7 @@ http://127.0.0.1:8000/mcp
 | **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) |
+| **Semantic Search** | 2+ | Vector search for Notes (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!

@@ -99,7 +76,7 @@ Want to see another Nextcloud app supported? [Open an issue](https://github.com/

 ### Authentication Modes

-The server supports three authentication modes:
+The server supports two authentication modes:

 **Single-User Mode (BasicAuth):**
 - One set of credentials shared by all MCP clients
@@ -113,12 +90,6 @@ The server supports three authentication modes:
 - More secure: tokens expire, credentials never shared with server
 - Best for: Teams, multi-user deployments, production environments with multiple users

-**Hybrid Mode (Multi-User BasicAuth + OAuth):**
- MCP clients use BasicAuth (simple, stateless)
- Admin operations use OAuth (webhooks, background sync)
- Best for: Nextcloud deployments with admin-managed webhooks and semantic search
- Requires: `ENABLE_MULTI_USER_BASIC_AUTH=true` + `ENABLE_OFFLINE_ACCESS=true`
-
 See [docs/authentication.md](docs/authentication.md) for detailed setup instructions.

 ## Semantic Search
@@ -133,7 +104,7 @@ This enables natural language queries and helps discover related content across

 > [!NOTE]
 > **Semantic Search is experimental and opt-in:**
-> - Disabled by default (`ENABLE_SEMANTIC_SEARCH=false`)
+> - Disabled by default (`VECTOR_SYNC_ENABLED=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
@@ -151,8 +122,7 @@ This enables natural language queries and helps discover related content across
 ### 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
+- **[Semantic Search Architecture](docs/semantic-search-architecture.md)** - Experimental vector search (Notes only, opt-in)

 ### Advanced Topics
 - **[OAuth Architecture](docs/oauth-architecture.md)** - How OAuth works (experimental)
@@ -1,90 +0,0 @@
-# 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
@@ -1,71 +0,0 @@
-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
@@ -1,26 +0,0 @@
-"""${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"}
@@ -3,9 +3,3 @@
 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"
@@ -1,5 +0,0 @@
-#!/bin/bash
-
-set -euox pipefail
-
-php /var/www/html/occ app:enable news
@@ -9,19 +9,19 @@ 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
+    if [ -e /var/www/html/apps/notes ]; then
        echo "Removing existing notes in apps..."
-        rm -rf /var/www/html/custom_apps/notes
+        rm -rf /var/www/html/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 "Creating symlink: apps/notes -> /opt/apps/notes"
+    ln -sf /opt/apps/notes /var/www/html/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
+elif [ -d /var/www/html/apps/notes ]; then
    echo "notes app directory found in apps (already installed)"
    php /var/www/html/occ app:enable notes
 else
@@ -1,18 +0,0 @@
-#!/bin/bash
-
-set -euox pipefail
-
-echo "Installing Astrolabe app from app store..."
-
-if [ -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
-    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."
@@ -1,16 +0,0 @@
-#!/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
-
-# The MCP multi-user BasicAuth service runs on port 8000 inside the container
-# From Nextcloud's perspective (inside Docker network), we reach it via service name
-MCP_SERVER_URL="${MCP_SERVER_URL:-http://mcp-multi-user-basic:8000}"
-
-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"
@@ -1,4 +0,0 @@
-<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>
@@ -1,25 +0,0 @@
-[tool.commitizen]
-name = "cz_conventional_commits"
-version = "0.57.44"
-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}}"
@@ -1,9 +1,9 @@
 dependencies:
 - name: qdrant
  repository: https://qdrant.github.io/qdrant-helm
-  version: 1.16.3
+  version: 1.15.5
 - name: ollama
  repository: https://otwld.github.io/ollama-helm
-  version: 1.42.0
-digest: sha256:a9aef6e290f23b1ed961450e0635eb0bce42f8c52805276901a80df7c27473f6
-generated: "2026-02-10T11:10:44.457881902Z"
+  version: 1.34.0
+digest: sha256:d51c97d05be2614b751c0dd7267ef7dc959eff5ebef859c5f895c5c554b7a874
+generated: "2025-11-09T17:08:02.86648061Z"
@@ -2,8 +2,8 @@ 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.57.44
-appVersion: "0.63.4"
+version: 0.36.0
+appVersion: "0.36.0"
 keywords:
  - nextcloud
  - mcp
@@ -27,10 +27,10 @@ annotations:
  grafana_dashboard_folder: "Nextcloud MCP"
 dependencies:
  - name: qdrant
-    version: "1.16.3"
+    version: "1.15.5"
    repository: https://qdrant.github.io/qdrant-helm
    condition: qdrant.networkMode.deploySubchart
  - name: ollama
-    version: "1.42.0"
+    version: "1.34.0"
    repository: https://otwld.github.io/ollama-helm
    condition: ollama.enabled
@@ -99,11 +99,11 @@ ingress:
 |-----------|-------------|---------|
 | `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** |
+| `nextcloud.publicIssuerUrl` | Public issuer URL for OAuth (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
+- `**publicIssuerUrl`: If not set, automatically defaults to `nextcloud.host` (which works when both clients and MCP server access Nextcloud at the same URL)

 #### Authentication

@@ -118,25 +118,6 @@ ingress:
 | `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 |
@@ -227,16 +208,16 @@ The application exposes HTTP health check endpoints:

 #### 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).
+Enable semantic search capabilities by deploying a vector database (Qdrant) and embedding service (Ollama or OpenAI).

-**Semantic Search Configuration:**
+**Vector Sync 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` |
+| `vectorSync.enabled` | Enable background vector synchronization | `false` |
+| `vectorSync.scanInterval` | Scan interval in seconds | `3600` |
+| `vectorSync.processorWorkers` | Number of concurrent processor workers | `3` |
+| `vectorSync.queueMaxSize` | Maximum queue size for pending documents | `10000` |

 **Document Chunking Configuration:**

@@ -446,7 +427,7 @@ 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)
+  # publicIssuerUrl defaults to nextcloud.host

 auth:
  mode: oauth
@@ -478,7 +459,7 @@ This example shows OAuth without pre-registered credentials (using DCR) and opti
 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)
+  # publicIssuerUrl will automatically default to nextcloud.host

 auth:
  mode: oauth
@@ -556,8 +537,8 @@ auth:
    username: admin
    password: secure-password

-# Enable semantic search
-semanticSearch:
+# Enable vector sync
+vectorSync:
  enabled: true
  scanInterval: 1800  # Scan every 30 minutes
  processorWorkers: 5
@@ -595,7 +576,7 @@ ollama:
 Or use an external Ollama instance:

 ```yaml
-semanticSearch:
+vectorSync:
  enabled: true

 qdrant:
@@ -611,7 +592,7 @@ ollama:
 Or use OpenAI for embeddings:

 ```yaml
-semanticSearch:
+vectorSync:
  enabled: true

 qdrant:
@@ -708,9 +689,7 @@ Readiness (returns 200 if ready, 503 if not ready):

 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
@@ -69,12 +69,12 @@ Your Nextcloud MCP Server has been deployed in {{ .Values.auth.mode }} authentic
   {{- end }}
 {{- end }}

-{{- if .Values.semanticSearch.enabled }}
+{{- if .Values.vectorSync.enabled }}

-5. Semantic Search & Vector Capabilities:
-   - Semantic Search: Enabled
-   - Scan Interval: {{ .Values.semanticSearch.scanInterval }}s
-   - Processor Workers: {{ .Values.semanticSearch.processorWorkers }}
+5. Vector Search & Semantic Capabilities:
+   - Vector Sync: Enabled
+   - Scan Interval: {{ .Values.vectorSync.scanInterval }}s
+   - Processor Workers: {{ .Values.vectorSync.processorWorkers }}
   {{- if .Values.qdrant.enabled }}
   - Qdrant: Deployed as subchart ({{ .Release.Name }}-qdrant:6333)
   {{- else }}
@@ -120,55 +120,6 @@ Your Nextcloud MCP Server has been deployed in {{ .Values.auth.mode }} authentic
   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 }}
-
 For more information and documentation:
 - GitHub: https://github.com/cbcoutinho/nextcloud-mcp-server
 - Documentation: https://github.com/cbcoutinho/nextcloud-mcp-server#readme
@@ -72,28 +72,6 @@ Create the name of the secret to use for 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
 */}}
@@ -127,55 +105,6 @@ Create the name of the PVC to use for Qdrant local persistent storage
 {{- 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 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
 */}}
@@ -68,7 +68,7 @@ spec:
            - name: NEXTCLOUD_HOST
              value: {{ .Values.nextcloud.host | quote }}
            {{- if eq .Values.auth.mode "basic" }}
-            # Basic auth mode (single-user)
+            # Basic auth mode
            - name: NEXTCLOUD_USERNAME
              valueFrom:
                secretKeyRef:
@@ -79,41 +79,6 @@ spec:
                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
@@ -122,7 +87,7 @@ spec:
              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 }}
+            {{- if .Values.auth.oauth.clientId }}
            - name: NEXTCLOUD_OIDC_CLIENT_ID
              valueFrom:
                secretKeyRef:
@@ -182,16 +147,16 @@ spec:
              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 }}
+            # Vector Sync
+            - name: VECTOR_SYNC_ENABLED
+              value: {{ .Values.vectorSync.enabled | quote }}
+            {{- if .Values.vectorSync.enabled }}
            - name: VECTOR_SYNC_SCAN_INTERVAL
-              value: {{ .Values.semanticSearch.scanInterval | quote }}
+              value: {{ .Values.vectorSync.scanInterval | quote }}
            - name: VECTOR_SYNC_PROCESSOR_WORKERS
-              value: {{ .Values.semanticSearch.processorWorkers | quote }}
+              value: {{ .Values.vectorSync.processorWorkers | quote }}
            - name: VECTOR_SYNC_QUEUE_MAX_SIZE
-              value: {{ .Values.semanticSearch.queueMaxSize | quote }}
+              value: {{ .Values.vectorSync.queueMaxSize | quote }}
            {{- end }}
            # Document Chunking (always set, used by vector sync processor)
            - name: DOCUMENT_CHUNK_SIZE
@@ -286,8 +251,10 @@ spec:
            - name: oauth-storage
              mountPath: /app/.oauth
            {{- end }}
-            - name: data-storage
+            {{- if and (eq .Values.qdrant.mode "persistent") .Values.qdrant.localPersistence.enabled }}
+            - name: qdrant-data
              mountPath: /app/data
+            {{- end }}
            {{- with .Values.volumeMounts }}
            {{- toYaml . | nindent 12 }}
            {{- end }}
@@ -299,12 +266,10 @@ spec:
          persistentVolumeClaim:
            claimName: {{ include "nextcloud-mcp-server.oauthPvcName" . }}
        {{- end }}
-        - name: data-storage
-        {{- if eq (include "nextcloud-mcp-server.dataStorageEnabled" .) "true" }}
+        {{- if and (eq .Values.qdrant.mode "persistent") .Values.qdrant.localPersistence.enabled }}
+        - name: qdrant-data
          persistentVolumeClaim:
-            claimName: {{ include "nextcloud-mcp-server.dataStoragePvcName" . }}
-        {{- else }}
-          emptyDir: {}
+            claimName: {{ include "nextcloud-mcp-server.qdrantPvcName" . }}
        {{- end }}
        {{- with .Values.volumes }}
        {{- toYaml . | nindent 8 }}
@@ -16,34 +16,20 @@ spec:
      storage: {{ .Values.auth.oauth.persistence.size }}
 {{- 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 }}
+{{- if and (eq .Values.qdrant.mode "persistent") .Values.qdrant.localPersistence.enabled (not .Values.qdrant.localPersistence.existingClaim) }}
 apiVersion: v1
 kind: PersistentVolumeClaim
 metadata:
-  name: {{ include "nextcloud-mcp-server.fullname" . }}-data-storage
+  name: {{ include "nextcloud-mcp-server.fullname" . }}-qdrant-data
  labels:
    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
 spec:
  accessModes:
-    - {{ $accessMode }}
-  {{- if $storageClass }}
-  storageClassName: {{ $storageClass }}
+    - {{ .Values.qdrant.localPersistence.accessMode }}
+  {{- if .Values.qdrant.localPersistence.storageClass }}
+  storageClassName: {{ .Values.qdrant.localPersistence.storageClass }}
  {{- end }}
  resources:
    requests:
-      storage: {{ $size }}
+      storage: {{ .Values.qdrant.localPersistence.size }}
 {{- end }}
@@ -13,24 +13,6 @@ data:
 {{- 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
@@ -26,29 +26,21 @@ nextcloud:
  # 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)
+  # Public issuer URL for OAuth (OAuth mode only)
+  # If not specified, defaults to nextcloud.host
+  # Only set this if your Nextcloud is accessible at a different URL for OAuth
  # Example: https://cloud.example.com
  publicIssuerUrl: ""

 # Authentication configuration
-# Choose one mode: "basic", "multi-user-basic", or "oauth"
+# Choose either basic auth OR oauth (not both)
 auth:
-  # Authentication mode: "basic", "multi-user-basic", or "oauth"
-  # basic: Single-user with username/password (recommended for personal use)
-  # multi-user-basic: Multi-user with BasicAuth pass-through (credentials in request headers)
+  # Authentication mode: "basic" or "oauth"
+  # basic: Uses username/password (recommended for most users)
  # oauth: Uses OAuth2/OIDC (experimental, requires patches)
  mode: basic

-  # Basic authentication settings (single-user mode)
+  # Basic authentication settings
  basic:
    # Nextcloud username (ignored if existingSecret is set)
    username: ""
@@ -66,47 +58,6 @@ auth:
    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"
@@ -139,27 +90,6 @@ auth:
      # Use existing PVC
      existingClaim: ""

-# 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)
-  # - 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)
@@ -386,11 +316,10 @@ extraEnvFrom: []
 # - 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
+# Vector Sync Configuration
+# Background synchronization of Nextcloud content into vector database for semantic search
+vectorSync:
+  # Enable background vector synchronization
  enabled: false
  # Scan interval in seconds (how often to check for changes)
  scanInterval: 3600
@@ -401,7 +330,7 @@ semanticSearch:

 # Document Chunking Configuration
 # Controls how documents are split into chunks before embedding
-# Only relevant when semanticSearch.enabled is true
+# Only relevant when vectorSync.enabled is true
 documentChunking:
  # Number of words per chunk (default: 512)
  # Smaller chunks (256-384): Better for precise searches, more chunks to store
@@ -1,25 +0,0 @@
-# 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
@@ -3,13 +3,11 @@ 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:345fa26d595e8c7fe298e0c4098ed400356f502458769c8902229b3437d6da2b
+    image: docker.io/library/mariadb:lts@sha256:6b848cb24fbbd87429917f6c4422ac53c343e85692eb0fef86553e99e4f422f3
    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
@@ -19,14 +17,14 @@ 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:0804c395e634e624243387d3c3a9c45fcaca876d313c2c8b52c3fdf9a912dded
+    image: docker.io/library/redis:alpine@sha256:28c9c4d7596949a24b183eaaab6455f8e5d55ecbf72d02ff5e2c17fe72671d31
    restart: always

  app:
-    image: docker.io/library/nextcloud:32.0.5@sha256:4b66e9bd8cb2c8af5457c1e2606c9937af2fcccbe4f6338956bc5990caec8968
+    image: docker.io/library/nextcloud:32.0.1@sha256:5b043f7ea2f609d5ff5635f475c30d303bec17775a5c3f7fa435e3818e669120
    restart: always
    ports:
-      - 127.0.0.1:8080:80
+      - 0.0.0.0:8080:80
    depends_on:
      - redis
      - db
@@ -53,14 +51,14 @@ services:
      retries: 30

  recipes:
-    image: docker.io/library/nginx:alpine@sha256:5878d06ae4c83d73285438255f705bb3f9a736f41cd24876ed25bb33faf76c7d
+    image: docker.io/library/nginx:alpine@sha256:b3c656d55d7ad751196f21b7fd2e8d4da9cb430e32f646adcf92441b72f82b14
    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:dcc82dcdd57241a7db2d78fd73c595d399ef4c1265fc8028fbe624a5eb51ecc3
+    image: downloads.unstructured.io/unstructured-io/unstructured-api:latest@sha256:54282d3a25f33fd6cf69bc45b3d37770f213593f58b6dfe5e85fe546376b2807
    restart: always
    ports:
      - 127.0.0.1:8002:8000
@@ -72,13 +70,11 @@ services:
  mcp:
    build: .
    restart: always
-    command: ["--transport", "streamable-http"]
    depends_on:
      app:
        condition: service_healthy
    ports:
      - 127.0.0.1:8000:8000
-      - 127.0.0.1:9090:9090
    volumes:
      - mcp-data:/app/data
    environment:
@@ -87,9 +83,9 @@ services:
      - 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 configuration (ADR-007)
+      - VECTOR_SYNC_ENABLED=true
+      - VECTOR_SYNC_SCAN_INTERVAL=10
      - VECTOR_SYNC_PROCESSOR_WORKERS=1

      #- LOG_FORMAT=json
@@ -124,40 +120,6 @@ services:
      # - DOCUMENT_CHUNK_SIZE=512      # Words per chunk (default: 512)
      # - DOCUMENT_CHUNK_OVERLAP=50    # Overlapping words (default: 50, recommended: 10-20% of chunk size)

-  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)
-      - TOKEN_ENCRYPTION_KEY=ESF1BvEQdGYsCluwMx9Cxvw3uh5pFowPH7Rg_nIliyo=
-      - 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
-
  mcp-oauth:
    build: .
    command: ["--transport", "streamable-http", "--oauth", "--port", "8001", "--oauth-token-type", "jwt"]
@@ -178,7 +140,7 @@ services:
      - 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
+      - ENABLE_OFFLINE_ACCESS=true
      - TOKEN_ENCRYPTION_KEY=ESF1BvEQdGYsCluwMx9Cxvw3uh5pFowPH7Rg_nIliyo=
      - TOKEN_STORAGE_DB=/app/data/tokens.db

@@ -186,19 +148,6 @@ services:
      # 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)
@@ -207,7 +156,7 @@ services:
      - oauth-tokens:/app/data

  keycloak:
-    image: quay.io/keycloak/keycloak:26.5.1@sha256:b80a48090594367bd8cf6fe2019466ac4ea49de4d0830fb2a43256eda37b18f5
+    image: quay.io/keycloak/keycloak:26.4.5@sha256:653852bfdea2be6e958b9e90a976eff1c6de34edd55f2f679bdc48ef16bc528e
    command:
      - "start-dev"
      - "--import-realm"
@@ -244,8 +193,8 @@ services:
      # 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_CLIENT_ID=nextcloud-mcp-server
+      - 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)
@@ -255,7 +204,7 @@ services:
      - NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8888/realms/nextcloud-mcp

      # Refresh token storage (ADR-002 Tier 1 & 2)
-      - ENABLE_BACKGROUND_OPERATIONS=true
+      - ENABLE_OFFLINE_ACCESS=true
      - TOKEN_ENCRYPTION_KEY=ESF1BvEQdGYsCluwMx9Cxvw3uh5pFowPH7Rg_nIliyo=
      - TOKEN_STORAGE_DB=/app/data/tokens.db

@@ -273,28 +222,8 @@ services:
      - keycloak-tokens:/app/data
      - keycloak-oauth-storage:/app/.oauth

-  # 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.16.3@sha256:0425e3e03e7fd9b3dc95c4214546afe19de2eb2e28ca621441a56663ac6e1f46
+    image: qdrant/qdrant:v1.15.5@sha256:0fb8897412abc81d1c0430a899b9a81eb8328aa634e7242d1bc804c1fe8fe863
    restart: always
    ports:
      - 127.0.0.1:6333:6333  # REST API
@@ -311,6 +240,17 @@ services:
    profiles:
      - qdrant

+  open-webui:
+    image: ghcr.io/open-webui/open-webui:main
+    environment:
+      - OLLAMA_BASE_URL=https://ollama.internal.coutinho.io
+    ports:
+      - 127.0.0.1:3000:8080
+    volumes:
+      - open-webui:/app/backend/data
+    profiles:
+      - open-webui
+
 volumes:
  nextcloud:
  db:
@@ -320,4 +260,4 @@ volumes:
  keycloak-oauth-storage:
  qdrant-data:
  mcp-data:
-  multi-user-basic-data:
+  open-webui:
@@ -1,8 +1,7 @@
 # ADR-011: Improving Semantic Search Quality Through Better Chunking and Embeddings

-**Status**: Partially Implemented (Chunking Complete, Embeddings Pending)
+**Status**: Proposed
 **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)

@@ -894,50 +893,3 @@ This ADR addresses the root causes of poor semantic search recall:
 - 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
@@ -1,254 +0,0 @@
-## 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)
@@ -1,241 +0,0 @@
-# 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.
@@ -1,380 +0,0 @@
-# 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
@@ -1,492 +0,0 @@
-# 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)
@@ -1,506 +0,0 @@
-# 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)
@@ -1,342 +0,0 @@
-# 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`
@@ -1,391 +0,0 @@
-# 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
-```
@@ -1,104 +0,0 @@
-# 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)
@@ -1,422 +0,0 @@
-# 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
@@ -140,97 +140,6 @@ 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:
@@ -1,338 +0,0 @@
-# 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)
@@ -1,564 +0,0 @@
-# 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.
@@ -2,82 +2,25 @@

 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

-We provide mode-specific configuration templates for quick setup:
+Create a `.env` file based on `env.sample`:

 ```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 deployment mode:
+Then choose your authentication mode:

- [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](#oauth2oidc-configuration) (Recommended)
+- [Basic Authentication Configuration](#basic-authentication-legacy)

 ---

-## Deployment Mode Selection
+## OAuth2/OIDC Configuration

-**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.
+OAuth2/OIDC is the recommended authentication mode for production deployments.

 ### Minimal Configuration (Auto-registration)

@@ -85,9 +28,6 @@ OAuth2/OIDC is the recommended authentication mode for production multi-user dep
 # .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=
@@ -101,9 +41,6 @@ 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
@@ -173,50 +110,8 @@ NEXTCLOUD_PASSWORD=your_app_password_or_password

 ## 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:
@@ -231,7 +126,7 @@ No configuration needed! If neither `QDRANT_URL` nor `QDRANT_LOCATION` is set, t

 ```dotenv
 # No Qdrant configuration needed - defaults to :memory:
-ENABLE_SEMANTIC_SEARCH=true
+VECTOR_SYNC_ENABLED=true
 ```

 **Pros:**
@@ -250,7 +145,7 @@ For single-instance deployments that need persistence without a separate Qdrant
 ```dotenv
 # Local persistent storage
 QDRANT_LOCATION=/app/data/qdrant  # Or any writable path
-ENABLE_SEMANTIC_SEARCH=true
+VECTOR_SYNC_ENABLED=true
 ```

 **Pros:**
@@ -271,7 +166,7 @@ For production deployments with a dedicated Qdrant service:
 QDRANT_URL=http://qdrant:6333
 QDRANT_API_KEY=your-secret-api-key  # Optional
 QDRANT_COLLECTION=nextcloud_content  # Optional
-ENABLE_SEMANTIC_SEARCH=true
+VECTOR_SYNC_ENABLED=true
 ```

 **Pros:**
@@ -388,15 +283,13 @@ Solutions:
 - Data corruption in Qdrant
 - Confusing error messages during indexing

-### Background Indexing Configuration
+### Vector Sync 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 settings (ADR-007)
+VECTOR_SYNC_ENABLED=true              # Enable background indexing
 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)
@@ -406,8 +299,6 @@ 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:
@@ -478,11 +369,11 @@ DOCUMENT_CHUNK_OVERLAP=100

 | 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 |
+| `QDRANT_COLLECTION` | ⚠️ Optional | `nextcloud_content` | Qdrant collection name |
+| `VECTOR_SYNC_ENABLED` | ⚠️ Optional | `false` | Enable background vector indexing |
 | `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 |
@@ -492,9 +383,6 @@ DOCUMENT_CHUNK_OVERLAP=100
 | `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:
@@ -504,7 +392,7 @@ services:
  mcp:
    environment:
      - QDRANT_URL=http://qdrant:6333
-      - ENABLE_SEMANTIC_SEARCH=true
+      - VECTOR_SYNC_ENABLED=true

  qdrant:
    image: qdrant/qdrant:latest
@@ -657,7 +545,6 @@ 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
@@ -666,4 +553,3 @@ 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
@@ -1,301 +0,0 @@
-# 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)
@@ -243,7 +243,7 @@ If you see cardinality warnings:
 The observability stack integrates at multiple layers:

 1. **HTTP Layer**: `ObservabilityMiddleware` tracks all HTTP requests
-2. **MCP Layer**: Tools use `@instrument_tool` for automatic metrics and trace span creation
+2. **MCP Layer**: Tools use `@trace_mcp_tool` for span creation
 3. **Client Layer**: `BaseNextcloudClient` tracks all API calls
 4. **OAuth Layer**: Token operations are traced and metered
 5. **Background Tasks**: Vector sync operations emit metrics/traces
@@ -14,10 +14,100 @@ Before running the server:

 ## Quick Start

-Start the server using Docker:
+Load your environment variables and start the server:

 ```bash
-# OAuth mode (recommended)
+# Load environment variables from .env
+export $(grep -v '^#' .env | xargs)
+
+# Start the server
+uv run nextcloud-mcp-server
+```
+
+The server will start on `http://127.0.0.1:8000` by default.
+
+---
+
+## Running Locally
+
+### Method 1: Using nextcloud-mcp-server CLI (Recommended)
+
+The CLI provides a simple interface with built-in defaults:
+
+#### OAuth Mode
+
+```bash
+# Auto-detected when NEXTCLOUD_USERNAME/PASSWORD not set
+uv run nextcloud-mcp-server
+
+# Explicitly force OAuth mode
+uv run nextcloud-mcp-server --oauth
+
+# OAuth with custom host and port
+uv run nextcloud-mcp-server --oauth --host 0.0.0.0 --port 8080
+
+# OAuth with pre-configured client
+uv run nextcloud-mcp-server --oauth \
+  --oauth-client-id abc123 \
+  --oauth-client-secret xyz789
+
+# OAuth with specific apps only
+uv run nextcloud-mcp-server --oauth \
+  --enable-app notes \
+  --enable-app calendar
+```
+
+#### BasicAuth Mode (Legacy)
+
+```bash
+# Auto-detected when NEXTCLOUD_USERNAME/PASSWORD are set
+uv run nextcloud-mcp-server
+
+# Explicitly force BasicAuth mode
+uv run nextcloud-mcp-server --no-oauth
+
+# BasicAuth with specific apps
+uv run nextcloud-mcp-server --no-oauth \
+  --enable-app notes \
+  --enable-app webdav
+```
+
+### Method 2: Using uvicorn
+
+For more control over server options (workers, reload, etc.):
+
+```bash
+# Load environment variables
+export $(grep -v '^#' .env | xargs)
+
+# Run with uvicorn
+uv run uvicorn nextcloud_mcp_server.app:get_app \
+  --factory \
+  --host 127.0.0.1 \
+  --port 8000 \
+  --reload  # Enable auto-reload for development
+```
+
+See all uvicorn options at [https://www.uvicorn.org/settings/](https://www.uvicorn.org/settings/)
+
+### Method 3: Using Python Module
+
+```bash
+# Load environment variables
+export $(grep -v '^#' .env | xargs)
+
+# Run as Python module
+python -m nextcloud_mcp_server.app --oauth --port 8000
+```
+
+---
+
+## Running with Docker
+
+### Basic Docker Run
+
+```bash
+# OAuth mode
 docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth

@@ -26,56 +116,11 @@ docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
 ```

-The server will start on `http://127.0.0.1:8000` by default.
-
---
-
-## Running with Docker
-
-### Basic Docker Run
-
-#### OAuth Mode (Recommended)
+### Docker with Persistent OAuth Storage

 ```bash
-# OAuth with auto-registration
-docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
-  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
-
-# OAuth with custom port
-docker run -p 127.0.0.1:8080:8000 --env-file .env --rm \
-  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
-
-# OAuth with pre-configured client
-docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
-  -e NEXTCLOUD_OIDC_CLIENT_ID=abc123 \
-  -e NEXTCLOUD_OIDC_CLIENT_SECRET=xyz789 \
-  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
-
-# OAuth with specific apps only
-docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
-  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
-  --enable-app notes --enable-app calendar
-```
-
-#### BasicAuth Mode (Legacy)
-
-```bash
-# BasicAuth (requires NEXTCLOUD_USERNAME/PASSWORD in .env)
-docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
-  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
-
-# BasicAuth with specific apps
-docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
-  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest \
-  --enable-app notes --enable-app webdav
-```
-
-### Docker with Persistent Token Storage
-
-```bash
-# Mount volume for persistent OAuth token storage
 docker run -p 127.0.0.1:8000:8000 --env-file .env \
-  -v $(pwd)/data:/app/data \
+  -v $(pwd)/.oauth:/app/.oauth \
  --rm ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
 ```

@@ -95,7 +140,7 @@ services:
    env_file:
      - .env
    volumes:
-      - ./data:/app/data  # Persistent token storage
+      - ./oauth-storage:/app/.oauth
    restart: unless-stopped
 ```

@@ -123,39 +168,30 @@ docker-compose down

 ```bash
 # Bind to all interfaces (accessible from network)
-docker run -p 0.0.0.0:8000:8000 --env-file .env --rm \
-  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
+uv run nextcloud-mcp-server --host 0.0.0.0 --port 8000

 # Bind to localhost only (default, more secure)
-docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
-  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
+uv run nextcloud-mcp-server --host 127.0.0.1 --port 8000

-# Use a different port (map host port 8080 to container port 8000)
-docker run -p 127.0.0.1:8080:8000 --env-file .env --rm \
-  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
+# Use a different port
+uv run nextcloud-mcp-server --port 8080
 ```

-**Security Note:** Binding to `0.0.0.0` exposes the server to your network. Only use this if you understand the security implications.
+**Security Note:** Using `--host 0.0.0.0` exposes the server to your network. Only use this if you understand the security implications.

 ### Transport Protocols

 The server supports multiple MCP transport protocols:

 ```bash
-# Streamable HTTP (default, recommended)
-docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
-  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
-  --transport streamable-http
+# Streamable HTTP (recommended)
+uv run nextcloud-mcp-server --transport streamable-http

-# SSE - Server-Sent Events (deprecated)
-docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
-  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
-  --transport sse
+# SSE - Server-Sent Events (default, deprecated)
+uv run nextcloud-mcp-server --transport sse

 # HTTP
-docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
-  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
-  --transport http
+uv run nextcloud-mcp-server --transport http
 ```

 > [!WARNING]
@@ -165,14 +201,10 @@ docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \

 ```bash
 # Set log level (critical, error, warning, info, debug, trace)
-docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
-  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
-  --log-level debug
+uv run nextcloud-mcp-server --log-level debug

 # Production: use warning or error
-docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
-  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
-  --log-level warning
+uv run nextcloud-mcp-server --log-level warning
 ```

 ### Selective App Enablement
@@ -180,26 +212,22 @@ docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
 By default, all supported Nextcloud apps are enabled. You can enable specific apps only:

 ```bash
-# Available apps: notes, tables, webdav, calendar, contacts, cookbook, deck
+# Available apps: notes, tables, webdav, calendar, contacts, deck

 # Enable all apps (default)
-docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
-  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
+uv run nextcloud-mcp-server

 # Enable only Notes
-docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
-  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
-  --enable-app notes
+uv run nextcloud-mcp-server --enable-app notes

 # Enable multiple apps
-docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
-  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
-  --enable-app notes --enable-app calendar --enable-app contacts
+uv run nextcloud-mcp-server \
+  --enable-app notes \
+  --enable-app calendar \
+  --enable-app contacts

 # Enable only WebDAV for file operations
-docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
-  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
-  --enable-app webdav
+uv run nextcloud-mcp-server --enable-app webdav
 ```

 **Use cases:**
@@ -212,68 +240,24 @@ docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \

 ## Development Mode

-### Running for Development
-
-For active development with auto-reload, mount your source code as a volume:
+For active development with auto-reload:

 ```bash
-# Development mode with source code mounted
-docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
-  -v $(pwd):/app \
-  -v $(pwd)/data:/app/data \
-  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
+# Using uvicorn with reload
+uv run uvicorn nextcloud_mcp_server.app:get_app \
+  --factory \
+  --reload \
+  --host 127.0.0.1 \
+  --port 8000 \
  --log-level debug
 ```

-For local development without Docker:
+Or use the CLI with reload flag:

 ```bash
-# Load environment variables
-export $(grep -v '^#' .env | xargs)
-
-# Run the server with auto-reload
-uv run nextcloud-mcp-server run --oauth --log-level debug
+uv run nextcloud-mcp-server --reload --log-level debug
 ```

-### CLI Subcommands
-
-The `nextcloud-mcp-server` CLI has two main subcommands:
-
-1. **`run`** - Start the MCP server (default command in Docker)
-   ```bash
-   uv run nextcloud-mcp-server run --oauth --host 0.0.0.0 --port 8000
-   ```
-
-2. **`db`** - Database migration management (Alembic)
-   ```bash
-   # Show current migration revision
-   uv run nextcloud-mcp-server db current
-
-   # Upgrade to latest migration
-   uv run nextcloud-mcp-server db upgrade
-
-   # Show migration history
-   uv run nextcloud-mcp-server db history
-
-   # Create new migration (developers only)
-   uv run nextcloud-mcp-server db migrate "description of changes"
-   ```
-
-### Database Migrations
-
-Token storage uses **Alembic** for schema management:
-
- **Automatic migrations**: Database is upgraded automatically on server startup
- **Backward compatibility**: Pre-Alembic databases are automatically stamped with the initial revision
- **Migration files**: Located in `alembic/versions/`
- **For developers**: When changing the schema:
-  1. Create a migration: `uv run nextcloud-mcp-server db migrate "add new column"`
-  2. Edit the generated file in `alembic/versions/` to add SQL statements
-  3. Test upgrade: `uv run nextcloud-mcp-server db upgrade`
-  4. Test downgrade: `uv run nextcloud-mcp-server db downgrade`
-
-See [Database Migrations Guide](database-migrations.md) for detailed information.
-
 ---

 ## Connecting to the Server
@@ -282,15 +266,15 @@ See [Database Migrations Guide](database-migrations.md) for detailed information

 MCP Inspector is a browser-based tool for testing MCP servers:

-1. Start your MCP server using Docker (see above)
-2. Start MCP Inspector:
-   ```bash
-   npx @modelcontextprotocol/inspector
-   ```
-3. In the browser:
-   - Enter server URL: `http://localhost:8000`
-   - Complete OAuth flow (if using OAuth)
-   - Explore tools and resources
+```bash
+# Start MCP Inspector
+uv run mcp dev
+
+# In the browser:
+# 1. Enter server URL: http://localhost:8000
+# 2. Complete OAuth flow (if using OAuth)
+# 3. Explore tools and resources
+```

 ### Using MCP Clients

@@ -338,13 +322,48 @@ INFO     Initializing Nextcloud client with BasicAuth

 ### Running as a Background Service

-Use Docker Compose with `restart: unless-stopped` (see [Docker Compose section](#docker-compose) above).
+#### Using systemd (Linux)
+
+Create `/etc/systemd/system/nextcloud-mcp.service`:
+
+```ini
+[Unit]
+Description=Nextcloud MCP Server
+After=network.target
+
+[Service]
+Type=simple
+User=your-user
+WorkingDirectory=/path/to/nextcloud-mcp-server
+EnvironmentFile=/path/to/.env
+ExecStart=/path/to/uv run nextcloud-mcp-server --oauth
+Restart=on-failure
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Enable and start:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable nextcloud-mcp
+sudo systemctl start nextcloud-mcp
+sudo systemctl status nextcloud-mcp
+```
+
+#### Using Docker Compose
+
+See [Docker Compose section](#docker-compose) above - includes `restart: unless-stopped`.

 ### Monitoring Logs

 ```bash
-# Docker (find container name first)
-docker ps
+# Local installation with systemd
+sudo journalctl -u nextcloud-mcp -f
+
+# Docker
 docker logs -f <container-name>

 # Docker Compose
@@ -355,37 +374,34 @@ docker-compose logs -f mcp

 ## Performance Tuning

-### Production Settings
+### Multiple Workers

-For production deployments, use Docker Compose with the recommended settings:
+For production deployments with higher load:

-```yaml
-version: '3.8'
+```bash
+# Using CLI (if supported)
+uv run nextcloud-mcp-server --workers 4

-services:
-  mcp:
-    image: ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
-    command: --oauth --log-level warning --transport streamable-http
-    ports:
-      - "127.0.0.1:8000:8000"
-    env_file:
-      - .env
-    volumes:
-      - ./data:/app/data
-    restart: unless-stopped
-    deploy:
-      resources:
-        limits:
-          cpus: '2'
-          memory: 1G
-        reservations:
-          cpus: '0.5'
-          memory: 512M
+# Using uvicorn
+uv run uvicorn nextcloud_mcp_server.app:get_app \
+  --factory \
+  --workers 4 \
+  --host 0.0.0.0 \
+  --port 8000
 ```

-### Scaling with Multiple Replicas
+### Production Settings

-For higher load, use Docker Swarm or Kubernetes. See the [Helm Chart](../helm/) for Kubernetes deployments.
+```bash
+# Recommended production configuration
+uv run nextcloud-mcp-server \
+  --oauth \
+  --host 127.0.0.1 \
+  --port 8000 \
+  --log-level warning \
+  --transport streamable-http \
+  --workers 2
+```

 ---

@@ -395,18 +411,12 @@ For higher load, use Docker Swarm or Kubernetes. See the [Helm Chart](../helm/)

 Check logs for errors:
 ```bash
-# View container logs
-docker logs <container-name>
-
-# Or run with debug logging
-docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
-  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
-  --log-level debug
+uv run nextcloud-mcp-server --log-level debug
 ```

 Common issues:
- Environment variables not loaded - Check your `.env` file
- Port already in use - Use a different host port (e.g., `-p 127.0.0.1:8080:8000`)
+- Environment variables not loaded - See [Configuration](configuration.md#loading-environment-variables)
+- Port already in use - Try a different port with `--port`
 - OAuth configuration errors - See [Troubleshooting](troubleshooting.md)

 ### Can't connect to server
@@ -5,7 +5,7 @@ This document explains the architecture of the semantic search feature in the Ne
 > [!IMPORTANT]
 > **Status: Experimental**
 > - Disabled by default (`VECTOR_SYNC_ENABLED=false`)
-> - Currently supports **Notes, Files (PDFs), News items, and Deck cards**
+> - Currently supports **Notes app only** (multi-app architecture ready, additional apps planned)
 > - Requires additional infrastructure (Qdrant vector database + Ollama embedding service)
 > - RAG answer generation requires MCP client sampling support

@@ -39,9 +39,9 @@ Semantic search enables:

 ### Current Support

- **Supported Apps**: Notes, Files (PDFs with text extraction), News items, Deck cards
- **Planned Apps**: Calendar events, Calendar tasks, Contacts
- **Architecture**: Multi-app plugin system ready for additional apps
+- **Supported Apps**: Notes (fully implemented)
+- **Planned Apps**: Calendar events, Calendar tasks, Deck cards, Files (with text extraction), Contacts
+- **Architecture**: Multi-app plugin system ready, awaiting implementation

 ## System Components

@@ -4,146 +4,6 @@ This guide covers common issues and solutions for the Nextcloud MCP server.

 > **OAuth-specific issues?** See the dedicated [OAuth Troubleshooting Guide](oauth-troubleshooting.md) for OAuth authentication problems, OIDC discovery issues, token validation failures, and more.

-> **Upgrading from v0.57.x?** See the [Configuration Migration Guide](configuration-migration-v2.md) for help with new variable names.
-
-## Configuration Issues (v0.58.0+)
-
-### Issue: Deprecation warning for VECTOR_SYNC_ENABLED
-
-**Symptom:**
-```
-WARNING: VECTOR_SYNC_ENABLED is deprecated. Please use ENABLE_SEMANTIC_SEARCH instead.
-```
-
-**Cause:** You're using the old variable name from v0.57.x.
-
-**Solution:**
-```bash
-# In your .env file, replace:
-VECTOR_SYNC_ENABLED=true
-
-# With:
-ENABLE_SEMANTIC_SEARCH=true
-```
-
-See [Configuration Migration Guide](configuration-migration-v2.md) for complete migration instructions.
-
---
-
-### Issue: Deprecation warning for ENABLE_OFFLINE_ACCESS
-
-**Symptom:**
-```
-WARNING: ENABLE_OFFLINE_ACCESS is deprecated. Please use ENABLE_BACKGROUND_OPERATIONS instead.
-```
-
-**Cause:** You're using the old variable name from v0.57.x.
-
-**Solution:**
-
-**If you have semantic search enabled:**
-```bash
-# In multi-user modes, you can remove ENABLE_OFFLINE_ACCESS entirely!
-# ENABLE_SEMANTIC_SEARCH automatically enables background operations
-
-# Before (v0.57.x):
-ENABLE_OFFLINE_ACCESS=true
-VECTOR_SYNC_ENABLED=true
-
-# After (v0.58.0+):
-ENABLE_SEMANTIC_SEARCH=true  # This is all you need!
-```
-
-**If you only want background operations (no semantic search):**
-```bash
-# Replace:
-ENABLE_OFFLINE_ACCESS=true
-
-# With:
-ENABLE_BACKGROUND_OPERATIONS=true
-```
-
---
-
-### Issue: "Invalid MCP_DEPLOYMENT_MODE"
-
-**Symptom:**
-```
-ValueError: Invalid MCP_DEPLOYMENT_MODE: 'oauth'. Valid values: single_user_basic, multi_user_basic, oauth_single_audience, oauth_token_exchange, smithery
-```
-
-**Cause:** Invalid value for `MCP_DEPLOYMENT_MODE`.
-
-**Solution:**
-Use one of the valid mode values:
-```bash
-# Correct values:
-MCP_DEPLOYMENT_MODE=single_user_basic          # Single-user with username/password
-MCP_DEPLOYMENT_MODE=multi_user_basic           # Multi-user BasicAuth
-MCP_DEPLOYMENT_MODE=oauth_single_audience      # OAuth (recommended)
-MCP_DEPLOYMENT_MODE=oauth_token_exchange       # OAuth with token exchange
-MCP_DEPLOYMENT_MODE=smithery                   # Smithery deployment
-```
-
-Or remove `MCP_DEPLOYMENT_MODE` to use automatic detection.
-
---
-
-### Issue: Missing TOKEN_ENCRYPTION_KEY when semantic search enabled
-
-**Symptom:**
-```
-Error: [oauth_single_audience] TOKEN_ENCRYPTION_KEY is required when ENABLE_SEMANTIC_SEARCH is enabled
-```
-
-**Cause:** In multi-user modes, semantic search automatically enables background operations, which require encrypted token storage.
-
-**Solution:**
-Generate an encryption key and add required token storage configuration:
-
-```bash
-# Generate encryption key
-python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
-
-# Add to .env:
-TOKEN_ENCRYPTION_KEY=<generated-key>
-TOKEN_STORAGE_DB=/app/data/tokens.db
-NEXTCLOUD_OIDC_CLIENT_ID=your-client-id       # Required for app password retrieval
-NEXTCLOUD_OIDC_CLIENT_SECRET=your-client-secret
-```
-
-**Why this happens:**
- v0.58.0+ automatically enables background operations when `ENABLE_SEMANTIC_SEARCH=true` in multi-user modes
- Background operations need encrypted refresh token storage
- This simplifies configuration but requires the encryption infrastructure
-
-See [Configuration Guide - Semantic Search](configuration.md#semantic-search-configuration-optional) for details.
-
---
-
-### Issue: Both old and new variable names set
-
-**Symptom:**
-```
-WARNING: Both ENABLE_SEMANTIC_SEARCH and VECTOR_SYNC_ENABLED are set. Using ENABLE_SEMANTIC_SEARCH.
-```
-
-**Cause:** You have both the old and new variable names in your configuration.
-
-**Solution:**
-Remove the old variable name:
-```bash
-# Remove this line:
-VECTOR_SYNC_ENABLED=true
-
-# Keep this line:
-ENABLE_SEMANTIC_SEARCH=true
-```
-
-The server will use the new name and ignore the old one, but it's cleaner to remove the old variable entirely.
-
---
-
 ## OAuth Issues (Quick Reference)

 ### Issue: "OAuth mode requires NEXTCLOUD_HOST environment variable"
@@ -1,93 +0,0 @@
-# Vector Sync UI Guide
-
-This guide covers the browser-based interface for the Nextcloud MCP Server's semantic search and vector synchronization features.
-
-## Overview
-
-The Vector Sync UI (`/app`) provides an interactive interface to test semantic search queries and visualize results from your Nextcloud documents. It exposes the same retrieval capabilities that LLMs use in Retrieval-Augmented Generation (RAG) workflows, powered by Alpine.js for reactive state, htmx for dynamic updates, and Plotly.js for 3D visualization.
-
-**Supported Apps**: Notes, Files (text/PDF), Calendar (events/tasks), Contacts (CardDAV), and Deck are indexed and searchable.
-
-## Accessing the UI
-
-Navigate to `/app` after authentication:
- **BasicAuth mode**: `http://localhost:8000/app` (uses credentials from environment)
- **OAuth mode**: `http://localhost:8000/app` (redirects to login if not authenticated)
-
-## Tabs
-
-### Welcome Page
-
-Landing page that introduces semantic search and RAG workflows. Shows authentication status, explains how vector embeddings work, and provides feature navigation. Adapts content based on whether `VECTOR_SYNC_ENABLED=true`.
-
-### User Info
-
-Displays authentication details and session information:
- **BasicAuth**: Username, mode badge, Nextcloud host
- **OAuth**: Username, session ID (truncated), background access status, IdP profile, revocation option
-
-### Vector Sync Status
-
-Real-time monitoring of document indexing:
- **Indexed Documents**: Total chunks stored in Qdrant vector database (immediately searchable)
- **Pending Documents**: Queue awaiting embedding processing
- **Status**: "✓ Idle" (green) when up-to-date, "⟳ Syncing" (orange) during processing
-
-Auto-refreshes every 10 seconds via htmx. Check this tab after adding content to verify indexing completion.
-
-### Vector Visualization
-
-Interactive search interface with 3D PCA plot of semantic space.
-
-**Search Controls**:
- **Query**: Natural language search (e.g., "health benefits of coffee")
- **Algorithm**: Semantic (Dense) for pure vector search, or BM25 Hybrid (default) combining vectors + keywords
- **Fusion** (Hybrid only): RRF (Reciprocal Rank Fusion) or DBSF (Distribution-Based Score Fusion)
- **Advanced**: Filter by document type, adjust score threshold (0.0-1.0), set result limit (max 100)
-
-**3D Visualization**:
-
-The plot uses Principal Component Analysis (PCA) to reduce 768-dimensional embeddings to 3D. Documents are positioned by semantic similarity with the query point shown in red. Point size and opacity indicate relevance, and the Viridis color scale shows relative scores (yellow = highest match).
-
-**Critical Fix**: Vectors are L2-normalized before PCA to match Qdrant's cosine distance, ensuring query points position accurately near similar documents. Without normalization, magnitude differences cause misleading spatial separation.
-
-**Results List**:
-
-Each result shows document title (clickable link to Nextcloud), excerpt, raw score, relative percentage, and document type. Click "Show Chunk" to view the matched text segment with surrounding context (up to 500 characters before/after).
-
-## Configuration
-
-**Required**:
-```bash
-VECTOR_SYNC_ENABLED=true
-```
-
-**Optional** (for browser-accessible links):
-```bash
-NEXTCLOUD_PUBLIC_ISSUER_URL=https://your-public-nextcloud-url.com
-```
-
-**Admin Access**: Webhooks tab only visible to Nextcloud admins (verified via Provisioning API).
-
-## Use Cases
-
-**Testing Search Queries**: Preview results before they reach LLMs in RAG workflows. Compare semantic vs. hybrid algorithms, verify relevance scores, and validate that correct documents are retrieved. Use chunk context to see exactly which text segments match and why unexpected documents appear.
-
-**Monitoring Indexing**: Track real-time progress after creating or modifying documents. Check if the queue is backing up (high pending count) or confirm the system is idle after bulk imports. Verify documents become searchable immediately after indexing completes.
-
-**Algorithm Comparison**: Pure semantic search excels at conceptual queries and synonyms. BM25 hybrid combines semantic understanding with precise keyword matching for better accuracy on specific terms. Experiment with RRF vs. DBSF fusion for different score distributions.
-
-## Troubleshooting
-
-**Vector Sync Tab Not Visible**: Set `VECTOR_SYNC_ENABLED=true` and restart the server.
-
-**No Search Results**: Check Vector Sync Status to confirm documents are indexed (not just pending). Try broader queries or lower the score threshold in Advanced options. Initial indexing may take time depending on document volume.
-
-**Links to Nextcloud Apps Not Working**: Set `NEXTCLOUD_PUBLIC_ISSUER_URL` to your browser-accessible Nextcloud URL for correct link generation.
-
-## Related Documentation
-
- [Configuration Guide](../configuration.md) - Environment variables and settings
- [Authentication Modes](../authentication.md) - BasicAuth vs OAuth setup
- [Installation Guide](../installation.md) - Getting started
- [ADR-008: MCP Sampling for RAG](../ADR-008-mcp-sampling-for-rag.md) - Technical details on RAG workflows
@@ -1,339 +0,0 @@
-# Webhook Management Guide
-
-This guide explains how to enable and disable webhooks for vector sync in each MCP server deployment mode. Webhooks enable near-real-time synchronization of content changes to the vector database, complementing the default polling-based sync.
-
-**Related ADRs:**
- ADR-010: Webhook-Based Vector Sync
- ADR-020: Deployment Modes and Configuration Validation
-
-## Prerequisites
-
-Before enabling webhooks, ensure:
-
-1. **Nextcloud 30+** with `webhook_listeners` app enabled
-2. **[Astrolabe app](https://github.com/cbcoutinho/astrolabe)** installed in Nextcloud (provides settings UI and credentials API)
-3. **MCP server** accessible from Nextcloud via HTTP(S)
-4. **Vector sync enabled** on the MCP server
-
-## Webhook Architecture Overview
-
-The webhook system has two components:
-
-1. **Webhook Registration** - Configuring Nextcloud to send change notifications to the MCP server
-2. **Background Sync Credentials** - Allowing the MCP server to access Nextcloud APIs on behalf of users
-
-Both must be configured for webhooks to function properly.
-
-## Deployment Mode Specifics
-
-### 1. Single-User BasicAuth
-
-**Configuration:**
-```bash
-NEXTCLOUD_HOST=http://localhost:8080
-NEXTCLOUD_USERNAME=admin
-NEXTCLOUD_PASSWORD=password
-VECTOR_SYNC_ENABLED=true
-```
-
-**Enable Webhooks:**
-1. Register webhooks using occ commands (requires Nextcloud admin):
-   ```bash
-   # Enable webhook_listeners app
-   php occ app:enable webhook_listeners
-
-   # Register webhooks for vector sync
-   php occ webhook_listeners:add \
-     --event "OCP\Files\Events\Node\NodeCreatedEvent" \
-     --uri "http://mcp-server:8000/webhooks/nextcloud" \
-     --method POST
-
-   # Repeat for other events (see Event Types below)
-   ```
-
-2. Optionally reduce polling frequency:
-   ```bash
-   VECTOR_SYNC_SCAN_INTERVAL=86400  # 24 hours
-   ```
-
-**Disable Webhooks:**
-```bash
-# List registered webhooks
-php occ webhook_listeners:list
-
-# Remove specific webhook by ID
-php occ webhook_listeners:remove <webhook-id>
-```
-
-**Notes:**
- Simplest mode - admin credentials used for all operations
- No per-user provisioning required
- Background sync runs as the configured admin user
-
---
-
-### 2. Multi-User BasicAuth Pass-Through
-
-**Configuration:**
-```bash
-NEXTCLOUD_HOST=http://nextcloud.example.com
-ENABLE_MULTI_USER_BASIC_AUTH=true
-ENABLE_BACKGROUND_OPERATIONS=true
-TOKEN_ENCRYPTION_KEY=<key>
-TOKEN_STORAGE_DB=/app/data/tokens.db
-VECTOR_SYNC_ENABLED=true
-# OAuth client for Astrolabe API access
-NEXTCLOUD_OIDC_CLIENT_ID=<client-id>
-NEXTCLOUD_OIDC_CLIENT_SECRET=<client-secret>
-```
-
-**Credential Architecture:**
-This mode uses **two separate credential mechanisms**:
-
-1. **OAuth Session** (for management API access, including webhooks):
-   - Obtained via browser OAuth flow (`/oauth/login`)
-   - Stores refresh token in MCP server's `tokens.db`
-   - Used for webhook registration/management APIs
-
-2. **App Password** (for background sync):
-   - Generated in Nextcloud Security settings
-   - Stored encrypted in Nextcloud's `oc_preferences` via Astrolabe
-   - Used by background scanners to access Nextcloud APIs
-
-**Enable Webhooks:**
-
-#### Step 1: Complete OAuth Login (for Management API)
-Users must authorize the MCP server to access their Nextcloud:
-
-1. Navigate to **Nextcloud Settings → Astrolabe** (Personal settings)
-2. Click **"Authorize via OAuth"** under "Option 1"
-3. Complete OAuth consent flow
-4. Verify the page shows "Background Sync Access: Active"
-
-#### Step 2: Configure App Password (for Background Sync)
-Since OAuth refresh tokens have short expiry, users should also configure an app password:
-
-1. Navigate to **Nextcloud Settings → Security**
-2. Generate a new app password (name it "Astrolabe" or "MCP Server")
-3. Return to **Nextcloud Settings → Astrolabe**
-4. Under "Option 2: App Password", paste the app password
-5. Click **Save**
-
-#### Step 3: Register Webhooks (Admin)
-Same as Single-User BasicAuth:
-```bash
-php occ webhook_listeners:add \
-  --event "OCP\Files\Events\Node\NodeCreatedEvent" \
-  --uri "http://mcp-server:8003/webhooks/nextcloud" \
-  --method POST
-```
-
-**Disable Webhooks:**
-
-*Per-User:*
-1. Navigate to **Nextcloud Settings → Astrolabe**
-2. Click **"Revoke Access"** (for OAuth tokens) or **"Revoke Access"** (for app password)
-
-*System-Wide:*
-```bash
-php occ webhook_listeners:remove <webhook-id>
-```
-
-**Troubleshooting:**
-
-If OAuth login fails with "Access forbidden - Your client is not authorized":
-1. Check if OAuth client is registered:
-   ```sql
-   SELECT id, name, client_identifier FROM oc_oidc_clients
-   WHERE dcr = 1 ORDER BY id DESC LIMIT 5;
-   ```
-2. Restart MCP server to trigger DCR re-registration
-3. Verify `NEXTCLOUD_OIDC_CLIENT_ID` and `NEXTCLOUD_OIDC_CLIENT_SECRET` are set
-
-If background sync fails with "User no longer provisioned":
-1. Verify app password is stored:
-   ```sql
-   SELECT userid, configkey FROM oc_preferences
-   WHERE appid = 'astrolabe' AND userid = 'username';
-   ```
-2. Ensure user completed **both** OAuth login AND app password setup
-
---
-
-### 3. OAuth Single-Audience (Default OAuth Mode)
-
-**Configuration:**
-```bash
-NEXTCLOUD_HOST=http://nextcloud.example.com
-# No NEXTCLOUD_USERNAME/PASSWORD
-ENABLE_BACKGROUND_OPERATIONS=true
-TOKEN_ENCRYPTION_KEY=<key>
-TOKEN_STORAGE_DB=/app/data/tokens.db
-VECTOR_SYNC_ENABLED=true
-```
-
-**Enable Webhooks:**
-
-#### Step 1: User Provisioning
-Users authorize via OAuth with `offline_access` scope:
-
-1. MCP client initiates OAuth flow
-2. User consents to requested scopes including `offline_access`
-3. MCP server stores refresh token for background operations
-
-Alternatively, via Astrolabe UI:
-1. Navigate to **Nextcloud Settings → Astrolabe**
-2. Click **"Authorize via OAuth"**
-3. Complete consent flow
-
-#### Step 2: Register Webhooks (Admin)
-```bash
-php occ webhook_listeners:add \
-  --event "OCP\Files\Events\Node\NodeCreatedEvent" \
-  --uri "http://mcp-server:8001/webhooks/nextcloud" \
-  --method POST
-```
-
-**Disable Webhooks:**
-
-*Per-User:*
- Via Astrolabe UI: Click "Disable Indexing" or "Disconnect"
- Via MCP tool: Use `revoke_nextcloud_access` if available
-
-*System-Wide:*
-```bash
-php occ webhook_listeners:remove <webhook-id>
-```
-
---
-
-### 4. OAuth Token Exchange (RFC 8693)
-
-**Configuration:**
-```bash
-NEXTCLOUD_HOST=http://nextcloud.example.com
-ENABLE_TOKEN_EXCHANGE=true
-ENABLE_BACKGROUND_OPERATIONS=true
-TOKEN_ENCRYPTION_KEY=<key>
-TOKEN_STORAGE_DB=/app/data/tokens.db
-VECTOR_SYNC_ENABLED=true
-```
-
-**Enable/Disable Webhooks:**
-Same process as OAuth Single-Audience. The token exchange happens transparently when the MCP server accesses Nextcloud APIs.
-
---
-
-### 5. Smithery Stateless
-
-**Configuration:**
- Configuration from session URL params
- `VECTOR_SYNC_ENABLED=false` (required)
-
-**Webhooks:**
-**Not supported.** This mode is stateless with no persistent storage or background operations.
-
---
-
-## Webhook Event Types
-
-Register these webhook events for full vector sync coverage:
-
-### File/Note Events
-```bash
-# Use BeforeNodeDeletedEvent for deletions (includes node.id)
-php occ webhook_listeners:add --event "OCP\Files\Events\Node\NodeCreatedEvent" --uri "$MCP_URL/webhooks/nextcloud"
-php occ webhook_listeners:add --event "OCP\Files\Events\Node\NodeWrittenEvent" --uri "$MCP_URL/webhooks/nextcloud"
-php occ webhook_listeners:add --event "OCP\Files\Events\Node\BeforeNodeDeletedEvent" --uri "$MCP_URL/webhooks/nextcloud"
-```
-
-### Calendar Events
-```bash
-php occ webhook_listeners:add --event "OCP\Calendar\Events\CalendarObjectCreatedEvent" --uri "$MCP_URL/webhooks/nextcloud"
-php occ webhook_listeners:add --event "OCP\Calendar\Events\CalendarObjectUpdatedEvent" --uri "$MCP_URL/webhooks/nextcloud"
-php occ webhook_listeners:add --event "OCP\Calendar\Events\CalendarObjectDeletedEvent" --uri "$MCP_URL/webhooks/nextcloud"
-```
-
-### Tables Events
-```bash
-php occ webhook_listeners:add --event "OCA\Tables\Event\RowAddedEvent" --uri "$MCP_URL/webhooks/nextcloud"
-php occ webhook_listeners:add --event "OCA\Tables\Event\RowUpdatedEvent" --uri "$MCP_URL/webhooks/nextcloud"
-php occ webhook_listeners:add --event "OCA\Tables\Event\RowDeletedEvent" --uri "$MCP_URL/webhooks/nextcloud"
-```
-
-## Security Considerations
-
-### Webhook Authentication
-Configure `WEBHOOK_SECRET` to require authentication for incoming webhooks:
-
-```bash
-# MCP Server
-WEBHOOK_SECRET=<generate-random-secret>
-
-# Nextcloud webhook registration
-php occ webhook_listeners:add \
-  --event "..." \
-  --uri "$MCP_URL/webhooks/nextcloud" \
-  --header "Authorization: Bearer <secret>"
-```
-
-### Token Storage
- Refresh tokens and app passwords are encrypted using `TOKEN_ENCRYPTION_KEY`
- Store the key securely (environment variable, secrets manager)
- Different users have isolated credential storage
-
-## Monitoring
-
-### MCP Server Logs
-```bash
-# Docker
-docker compose logs mcp-multi-user-basic | grep -i webhook
-
-# Key log messages
-# - "Queued document from webhook: ..." - Success
-# - "Webhook authentication failed" - Auth error
-# - "User X no longer provisioned" - Missing credentials
-```
-
-### Nextcloud Logs
-```bash
-docker compose exec app cat /var/www/html/data/nextcloud.log | \
-  jq 'select(.message | contains("webhook"))' | tail
-```
-
-### Database Checks
-```sql
-- Check registered webhooks
-SELECT * FROM oc_webhook_listeners;
-
-- Check OAuth clients
-SELECT id, name, token_type FROM oc_oidc_clients WHERE dcr = 1;
-
-- Check user credentials stored by Astrolabe app
-SELECT userid, configkey FROM oc_preferences WHERE appid = 'astrolabe';
-```
-
-## Common Issues
-
-### "Access forbidden - Your client is not authorized to connect"
-**Cause:** OAuth client registration expired or not present in Nextcloud
-**Fix:** Restart MCP server to trigger DCR re-registration
-
-### "User X no longer provisioned, stopping scanner"
-**Cause:** Background sync credentials missing or expired
-**Fix:** User must complete credential provisioning (see mode-specific steps)
-
-### "Failed to fetch" in browser console during OAuth
-**Cause:** Network issue between browser and MCP server callback endpoint
-**Fix:** Verify MCP server is accessible at the configured `NEXTCLOUD_MCP_SERVER_URL`
-
-### Webhooks not firing
-**Causes:**
-1. `webhook_listeners` app not enabled
-2. Webhook not registered for the event type
-3. Background job workers not running
-**Fix:**
-```bash
-php occ app:enable webhook_listeners
-php occ background:cron  # or configure systemd cron
-```
@@ -1,236 +1,198 @@
-# ============================================
-# DEPLOYMENT MODE SELECTION
-# ============================================
-# Optional: Explicitly declare deployment mode (ADR-021)
-# If not set, mode is auto-detected from other settings
-# Valid values: single_user_basic, multi_user_basic, oauth_single_audience,
-#               oauth_token_exchange, smithery
-#
-# Recommendation: Set this for clarity and to catch configuration errors early
-#MCP_DEPLOYMENT_MODE=oauth_single_audience
-
-# ============================================
-# COMMON SETTINGS (Required for all modes)
-# ============================================
-# Your Nextcloud instance URL (without trailing slash)
+# Nextcloud Instance
 NEXTCLOUD_HOST=

-# ============================================
-# SINGLE-USER BASICAUTH MODE
-# ============================================
-# Simplest deployment - one user, credentials in environment
-# Use for: Personal instances, local development, testing
-#
-# Required:
+# ===== AUTHENTICATION MODE =====
+# Choose ONE of the following:
+
+# Option 1: OAuth2/OIDC (RECOMMENDED - More Secure)
+# - Requires Nextcloud OIDC app installed and configured
+# - Admin must enable "Dynamic Client Registration" in OIDC app settings
+# - Leave NEXTCLOUD_USERNAME and NEXTCLOUD_PASSWORD empty to use OAuth mode
+# - OAuth client credentials are stored encrypted in SQLite (TOKEN_STORAGE_DB)
+# - Optional: Pre-register client and provide credentials (otherwise auto-registers)
+NEXTCLOUD_OIDC_CLIENT_ID=
+NEXTCLOUD_OIDC_CLIENT_SECRET=
+NEXTCLOUD_MCP_SERVER_URL=http://localhost:8000
+
+# OAuth Storage Configuration (SQLite storage for OAuth clients and refresh tokens)
+# TOKEN_ENCRYPTION_KEY: Required for encrypting OAuth client secrets and refresh tokens
+# Generate with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+#TOKEN_ENCRYPTION_KEY=
+# TOKEN_STORAGE_DB: Path to SQLite database (default: /app/data/tokens.db)
+#TOKEN_STORAGE_DB=/app/data/tokens.db
+
+# ===== ADR-004 PROGRESSIVE CONSENT CONFIGURATION =====
+# Enable Progressive Consent mode (dual OAuth flows)
+# When enabled: Flow 1 for client auth, Flow 2 for Nextcloud resource access
+# When disabled: Uses existing hybrid flow (backward compatible)
+
+# MCP Server OAuth Client Configuration
+# The MCP server's own OAuth client credentials for Flow 2
+# If not set, will use dynamic client registration
+#MCP_SERVER_CLIENT_ID=
+#MCP_SERVER_CLIENT_SECRET=
+
+# Allowed MCP Client IDs (comma-separated list)
+# Client IDs that are allowed to authenticate in Flow 1
+# Examples: claude-desktop,continue-dev,zed-editor
+#ALLOWED_MCP_CLIENTS=claude-desktop,continue-dev,zed-editor
+
+# Token cache configuration for Token Broker Service
+# Cache TTL in seconds (default: 300 = 5 minutes)
+#TOKEN_CACHE_TTL=300
+# Early refresh threshold in seconds (default: 30)
+#TOKEN_CACHE_EARLY_REFRESH=30
+
+# Option 2: Basic Authentication (LEGACY - Less Secure)
+# - Requires username and password
+# - Credentials stored in environment variables
+# - Use only for backward compatibility or if OAuth unavailable
+# - If these are set, OAuth mode is disabled
 NEXTCLOUD_USERNAME=
 NEXTCLOUD_PASSWORD=
-#
-# Optional features (semantic search, document processing):
-# See "Optional Features" section below

 # ============================================
-# MULTI-USER BASICAUTH MODE
+# Document Processing Configuration
 # ============================================
-# Users provide credentials in request headers (pass-through)
-# Use for: Multi-user without OAuth, simple shared deployments
-#
-# Required:
-#ENABLE_MULTI_USER_BASIC_AUTH=true
-#
-# Optional - Background Operations (for semantic search, future features):
-# Enable background token storage using app passwords (via Astrolabe)
-# Required for semantic search in multi-user mode
-# Note: ENABLE_SEMANTIC_SEARCH automatically enables this in multi-user modes
-#ENABLE_BACKGROUND_OPERATIONS=true
-#NEXTCLOUD_OIDC_CLIENT_ID=
-#NEXTCLOUD_OIDC_CLIENT_SECRET=
-#TOKEN_ENCRYPTION_KEY=
-#TOKEN_STORAGE_DB=/app/data/tokens.db
-#
-# Optional features (semantic search, document processing):
-# See "Optional Features" section below
+# Enable document processing (PDF, DOCX, images, etc.)
+# Set to false to disable all document processing
+ENABLE_DOCUMENT_PROCESSING=false
+
+# Default processor to use when multiple are available
+# Options: unstructured, tesseract, custom
+DOCUMENT_PROCESSOR=unstructured

 # ============================================
-# OAUTH SINGLE-AUDIENCE MODE (Recommended)
+# Unstructured.io Processor
 # ============================================
-# Multi-user OAuth with single-audience tokens
-# Use for: Multi-user production deployments, enhanced security
-# Tokens work for both MCP server and Nextcloud APIs (pass-through)
-#
-# Required: None (uses Dynamic Client Registration if credentials not provided)
-#
-# Optional - Pre-registered OAuth Client:
-# If you pre-register the client instead of using DCR:
-#NEXTCLOUD_OIDC_CLIENT_ID=
-#NEXTCLOUD_OIDC_CLIENT_SECRET=
-#
-# Optional - Background Operations (for semantic search, future features):
-# Enable refresh token storage for offline access
-# Note: ENABLE_SEMANTIC_SEARCH automatically enables this in multi-user modes
-#ENABLE_BACKGROUND_OPERATIONS=true
-#TOKEN_ENCRYPTION_KEY=
-#TOKEN_STORAGE_DB=/app/data/tokens.db
-#
-# Optional - Custom OIDC Discovery:
-# Auto-detected from NEXTCLOUD_HOST if not set
-#NEXTCLOUD_OIDC_DISCOVERY_URL=
-#
-# Optional - Custom Scopes:
-# Default: openid profile email offline_access notes:* calendar:* contacts:* tables:* webdav:* deck:* cookbook:*
-#NEXTCLOUD_OIDC_SCOPES=openid profile email notes:* calendar:*
-#
-# MCP Server URL (for OAuth redirects):
-#NEXTCLOUD_MCP_SERVER_URL=http://localhost:8000
-#
-# Optional features (semantic search, document processing):
-# See "Optional Features" section below
+# Enable Unstructured processor (requires unstructured service in docker-compose)
+# This is a cloud-based/API processor supporting many document types
+ENABLE_UNSTRUCTURED=false
+
+# Unstructured API endpoint
+UNSTRUCTURED_API_URL=http://unstructured:8000
+
+# Request timeout in seconds (default: 120)
+# OCR operations can take 30-120 seconds for large documents
+UNSTRUCTURED_TIMEOUT=120
+
+# Parsing strategy: auto, fast, hi_res
+# - auto: Automatically choose based on document type
+# - fast: Fast parsing without OCR
+# - hi_res: High-resolution with OCR (slowest, most accurate)
+UNSTRUCTURED_STRATEGY=auto
+
+# OCR languages (comma-separated ISO 639-3 codes)
+# Common: eng=English, deu=German, fra=French, spa=Spanish
+UNSTRUCTURED_LANGUAGES=eng,deu
+
+# Progress reporting interval in seconds (default: 10)
+# During long-running OCR operations, progress notifications are sent to the MCP client
+# at this interval to prevent timeouts and provide status updates
+PROGRESS_INTERVAL=10

 # ============================================
-# OAUTH TOKEN EXCHANGE MODE (Advanced)
+# Tesseract Processor (Local OCR)
 # ============================================
-# Multi-user OAuth with RFC 8693 token exchange
-# Use for: Advanced deployments requiring separate MCP and Nextcloud tokens
-# MCP tokens are separate from Nextcloud tokens
-#
-# Required:
-#ENABLE_TOKEN_EXCHANGE=true
-#
-# Optional - Pre-registered OAuth Client:
-# If you pre-register the client instead of using DCR:
-#NEXTCLOUD_OIDC_CLIENT_ID=
-#NEXTCLOUD_OIDC_CLIENT_SECRET=
-#
-# Optional - Token Exchange Configuration:
-# Cache TTL in seconds (default: 300 = 5 minutes)
-#TOKEN_EXCHANGE_CACHE_TTL=300
-#
-# Optional - Background Operations:
-# Note: ENABLE_SEMANTIC_SEARCH automatically enables this in multi-user modes
-#ENABLE_BACKGROUND_OPERATIONS=true
-#TOKEN_ENCRYPTION_KEY=
-#TOKEN_STORAGE_DB=/app/data/tokens.db
-#
-# Optional - Custom OIDC Discovery:
-#NEXTCLOUD_OIDC_DISCOVERY_URL=
-#
-# MCP Server URL (for OAuth redirects):
-#NEXTCLOUD_MCP_SERVER_URL=http://localhost:8000
-#
-# Optional features (semantic search, document processing):
-# See "Optional Features" section below
+# Enable Tesseract processor (requires tesseract binary installed)
+# This is a local, lightweight OCR solution for images only
+ENABLE_TESSERACT=false

-# ============================================
-# SMITHERY STATELESS MODE
-# ============================================
-# Stateless multi-tenant deployment for Smithery platform
-# Configuration comes from session URL parameters
-# No persistent storage, no OAuth, no vector sync
-#
-# Required: None (all config from session URL)
-# This mode is activated automatically when deployed to Smithery
-
-# ============================================
-# OPTIONAL FEATURES (All Deployment Modes)
-# ============================================
-
-# ===== SEMANTIC SEARCH =====
-# AI-powered semantic search across Nextcloud content
-# Requires: Qdrant vector database + embedding provider (Ollama, Bedrock, or Simple fallback)
-#
-# Enable semantic search:
-#ENABLE_SEMANTIC_SEARCH=true
-#
-# Note for Multi-User Modes:
-# ENABLE_SEMANTIC_SEARCH automatically enables background operations when needed
-# No need to set ENABLE_BACKGROUND_OPERATIONS separately
-# The server will automatically request refresh tokens and store them encrypted
-#
-# Vector Database - Choose ONE mode:
-# 1. In-memory (default): Set neither QDRANT_URL nor QDRANT_LOCATION
-# 2. Persistent local: Set QDRANT_LOCATION=/path/to/data
-# 3. Network: Set QDRANT_URL=http://qdrant:6333
-#
-#QDRANT_URL=http://qdrant:6333
-#QDRANT_LOCATION=:memory:
-#QDRANT_API_KEY=
-#QDRANT_COLLECTION=nextcloud_content
-#
-# Embedding Provider - Choose ONE:
-# 1. Ollama (recommended for local deployment):
-#OLLAMA_BASE_URL=http://ollama:11434
-#OLLAMA_EMBEDDING_MODEL=nomic-embed-text
-#OLLAMA_VERIFY_SSL=true
-#
-# 2. Amazon Bedrock (for AWS deployments):
-#AWS_REGION=us-east-1
-#BEDROCK_EMBEDDING_MODEL=amazon.titan-embed-text-v2:0
-# Optional: AWS credentials (uses credential chain if not set)
-#AWS_ACCESS_KEY_ID=
-#AWS_SECRET_ACCESS_KEY=
-#
-# 3. Simple (automatic fallback, no configuration needed)
-# Uses basic in-memory embeddings if no provider configured
-#
-# Document Chunking:
-# Configure how documents are split before embedding
-#DOCUMENT_CHUNK_SIZE=512
-#DOCUMENT_CHUNK_OVERLAP=50
-
-# ===== SEMANTIC SEARCH TUNING =====
-# Advanced parameters for vector sync background operations
-# Only modify if you understand the implications
-#
-# Document scan interval in seconds (default: 300 = 5 minutes)
-#VECTOR_SYNC_SCAN_INTERVAL=300
-#
-# Concurrent indexing workers (default: 3)
-#VECTOR_SYNC_PROCESSOR_WORKERS=3
-#
-# Max queued documents (default: 10000)
-#VECTOR_SYNC_QUEUE_MAX_SIZE=10000
-
-# ===== DOCUMENT PROCESSING =====
-# Extract text from PDFs, images, DOCX, etc. for semantic search
-# Disabled by default
-#
-#ENABLE_DOCUMENT_PROCESSING=false
-#DOCUMENT_PROCESSOR=unstructured
-#
-# Unstructured.io Processor (recommended):
-#ENABLE_UNSTRUCTURED=false
-#UNSTRUCTURED_API_URL=http://unstructured:8000
-#UNSTRUCTURED_TIMEOUT=120
-#UNSTRUCTURED_STRATEGY=auto
-#UNSTRUCTURED_LANGUAGES=eng,deu
-#PROGRESS_INTERVAL=10
-#
-# Tesseract OCR (lightweight, images only):
-#ENABLE_TESSERACT=false
+# Path to tesseract executable (optional, auto-detected if in PATH)
 #TESSERACT_CMD=/usr/bin/tesseract
-#TESSERACT_LANG=eng
-#
-# Custom Processor (your own API):
-#ENABLE_CUSTOM_PROCESSOR=false
+
+# OCR language (e.g., eng, deu, eng+deu for multiple)
+TESSERACT_LANG=eng
+
+# ============================================
+# Custom Processor (Your own API)
+# ============================================
+# Enable custom document processor via HTTP API
+ENABLE_CUSTOM_PROCESSOR=false
+
+# Unique name for your processor
 #CUSTOM_PROCESSOR_NAME=my_ocr
+
+# Your custom processor API endpoint
 #CUSTOM_PROCESSOR_URL=http://localhost:9000/process
-#CUSTOM_PROCESSOR_API_KEY=
+
+# Optional API key for authentication
+#CUSTOM_PROCESSOR_API_KEY=your-api-key-here
+
+# Request timeout in seconds
 #CUSTOM_PROCESSOR_TIMEOUT=60
+
+# Comma-separated MIME types your processor supports
 #CUSTOM_PROCESSOR_TYPES=application/pdf,image/jpeg,image/png

-# ===== SECURITY & ADVANCED =====
-# Cookie security (browser UI)
-# Auto-detects from NEXTCLOUD_HOST protocol if not set
-#COOKIE_SECURE=true
+# ============================================
+# Semantic Search & Vector Sync Configuration
+# ============================================
+# EXPERIMENTAL: Semantic search for Notes app (multi-app support planned)
+# Requires: Qdrant vector database + Ollama embedding service
+# Disabled by default
+
+# Enable background vector indexing
+VECTOR_SYNC_ENABLED=false
+
+# Document scan interval in seconds (default: 300 = 5 minutes)
+# How often to check for new/updated documents
+#VECTOR_SYNC_SCAN_INTERVAL=300
+
+# Concurrent indexing workers (default: 3)
+# Number of parallel workers for embedding generation
+#VECTOR_SYNC_PROCESSOR_WORKERS=3
+
+# Max queued documents (default: 10000)
+# Maximum documents waiting to be processed
+#VECTOR_SYNC_QUEUE_MAX_SIZE=10000

 # ============================================
-# DEPRECATED VARIABLES (Backward Compatibility)
+# Qdrant Vector Database Configuration
 # ============================================
-# These variables still work but will be removed in v1.0.0
-# Please migrate to new names:
-#
-# Old Name                  → New Name
-# VECTOR_SYNC_ENABLED      → ENABLE_SEMANTIC_SEARCH
-# ENABLE_OFFLINE_ACCESS    → ENABLE_BACKGROUND_OPERATIONS
-#
-# Migration is optional - both old and new names work
-# Deprecation warnings will be logged when old names are used
+# Choose ONE of three modes:
+# 1. In-memory mode (default): Set neither QDRANT_URL nor QDRANT_LOCATION
+# 2. Persistent local: Set QDRANT_LOCATION=/path/to/data
+# 3. Network mode: Set QDRANT_URL=http://qdrant:6333
+
+# Network mode: URL to Qdrant service
+#QDRANT_URL=http://qdrant:6333
+
+# Local mode: Path to store vectors (use :memory: for in-memory)
+#QDRANT_LOCATION=:memory:
+
+# API key for network mode (optional)
+#QDRANT_API_KEY=
+
+# Collection name (optional - auto-generated if not set)
+# Auto-generation format: {deployment-id}-{model-name}
+# Allows safe model switching and multi-server deployments
+#QDRANT_COLLECTION=nextcloud_content
+
+# ============================================
+# Ollama Embedding Service Configuration
+# ============================================
+# Ollama endpoint for embeddings (if not set, uses SimpleEmbeddingProvider fallback)
+#OLLAMA_BASE_URL=http://ollama:11434
+
+# Embedding model to use (default: nomic-embed-text, 768 dimensions)
+# Changing this creates a new collection (requires re-embedding all documents)
+#OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+
+# Verify SSL certificates (default: true)
+#OLLAMA_VERIFY_SSL=true
+
+# ============================================
+# Document Chunking Configuration
+# ============================================
+# Configure how documents are split before embedding
+
+# Words per chunk (default: 512)
+# Smaller chunks (256-384): More precise, less context, more storage
+# Larger chunks (768-1024): More context, less precise, less storage
+#DOCUMENT_CHUNK_SIZE=512
+
+# Overlapping words between chunks (default: 50)
+# Recommended: 10-20% of chunk size
+# Preserves context across chunk boundaries
+#DOCUMENT_CHUNK_OVERLAP=50
@@ -1,80 +0,0 @@
-# ============================================
-# OAUTH TOKEN EXCHANGE QUICK START (Advanced)
-# ============================================
-# Advanced OAuth deployment with RFC 8693 token exchange
-# Use for: Deployments requiring separate MCP and Nextcloud tokens
-# Features: Dual-audience tokens, enhanced security boundaries
-#
-# Copy this file to .env and configure
-
-# ===== REQUIRED SETTINGS =====
-# Your Nextcloud instance URL (without trailing slash)
-NEXTCLOUD_HOST=https://nextcloud.example.com
-
-# Enable token exchange mode
-ENABLE_TOKEN_EXCHANGE=true
-
-# ===== REQUIRED: LEAVE USERNAME/PASSWORD EMPTY =====
-# OAuth mode activates when these are NOT set
-NEXTCLOUD_USERNAME=
-NEXTCLOUD_PASSWORD=
-
-# ===== OPTIONAL: EXPLICIT MODE DECLARATION =====
-# Recommended for clarity
-MCP_DEPLOYMENT_MODE=oauth_token_exchange
-
-# ===== OPTIONAL: PRE-REGISTERED OAUTH CLIENT =====
-# If you pre-register the OAuth client instead of using DCR:
-#NEXTCLOUD_OIDC_CLIENT_ID=your-client-id
-#NEXTCLOUD_OIDC_CLIENT_SECRET=your-client-secret
-
-# MCP Server URL (for OAuth redirects)
-NEXTCLOUD_MCP_SERVER_URL=http://localhost:8000
-
-# ===== OPTIONAL: TOKEN EXCHANGE TUNING =====
-# Cache TTL for exchanged tokens (default: 300 seconds = 5 minutes)
-TOKEN_EXCHANGE_CACHE_TTL=300
-
-# ===== OPTIONAL: SEMANTIC SEARCH =====
-# AI-powered semantic search with automatic background operation setup
-#
-# Note: ENABLE_SEMANTIC_SEARCH automatically enables background operations
-# in token exchange mode, just like in OAuth single-audience mode
-#
-ENABLE_SEMANTIC_SEARCH=true
-
-# Vector Database (required for semantic search)
-QDRANT_URL=http://qdrant:6333
-
-# Embedding Provider (required for semantic search)
-OLLAMA_BASE_URL=http://ollama:11434
-OLLAMA_EMBEDDING_MODEL=nomic-embed-text
-
-# Token Storage (required for background operations - auto-enabled by semantic search)
-# Generate encryption key: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
-TOKEN_ENCRYPTION_KEY=your-encryption-key-here
-TOKEN_STORAGE_DB=/app/data/tokens.db
-
-# ===== OPTIONAL: DOCUMENT PROCESSING =====
-# Extract text from PDFs, images, DOCX for semantic search
-#ENABLE_DOCUMENT_PROCESSING=true
-#ENABLE_UNSTRUCTURED=true
-#UNSTRUCTURED_API_URL=http://unstructured:8000
-
-# ===== TOKEN EXCHANGE MODE EXPLANATION =====
-# In this mode:
-# 1. MCP clients authenticate with tokens scoped to "mcp-server" audience
-# 2. Server exchanges MCP tokens for Nextcloud tokens on each request
-# 3. Provides clear separation between MCP session and Nextcloud access
-# 4. Enables fine-grained token lifecycle management
-#
-# When to use:
-# - Strict security requirements (separate token contexts)
-# - Complex multi-service architectures
-# - Need independent token expiration policies
-#
-# When NOT to use:
-# - Simple deployments (use oauth_single_audience instead)
-# - High-performance requirements (token exchange adds latency)
-
-# For more configuration options, see env.sample
@@ -1,77 +0,0 @@
-# ============================================
-# OAUTH MULTI-USER QUICK START (Recommended)
-# ============================================
-# Multi-user deployment with OAuth authentication
-# Use for: Multi-user production deployments, enhanced security
-# Features: Single-audience tokens, automatic client registration (DCR)
-#
-# Copy this file to .env and configure
-
-# ===== REQUIRED SETTINGS =====
-# Your Nextcloud instance URL (without trailing slash)
-NEXTCLOUD_HOST=https://nextcloud.example.com
-
-# ===== REQUIRED: LEAVE USERNAME/PASSWORD EMPTY =====
-# OAuth mode activates when these are NOT set
-NEXTCLOUD_USERNAME=
-NEXTCLOUD_PASSWORD=
-
-# ===== OPTIONAL: EXPLICIT MODE DECLARATION =====
-# Recommended for clarity
-MCP_DEPLOYMENT_MODE=oauth_single_audience
-
-# ===== OPTIONAL: PRE-REGISTERED OAUTH CLIENT =====
-# If you pre-register the OAuth client instead of using DCR:
-#NEXTCLOUD_OIDC_CLIENT_ID=your-client-id
-#NEXTCLOUD_OIDC_CLIENT_SECRET=your-client-secret
-
-# MCP Server URL (for OAuth redirects)
-NEXTCLOUD_MCP_SERVER_URL=http://localhost:8000
-
-# ===== OPTIONAL: SEMANTIC SEARCH (Recommended) =====
-# AI-powered semantic search with automatic background operation setup
-#
-# When you enable semantic search in multi-user mode:
-# 1. ENABLE_SEMANTIC_SEARCH automatically enables background operations
-# 2. Server requests refresh tokens for offline indexing
-# 3. Tokens are stored encrypted in TOKEN_STORAGE_DB
-# 4. No need to set ENABLE_BACKGROUND_OPERATIONS separately!
-#
-ENABLE_SEMANTIC_SEARCH=true
-
-# Vector Database (required for semantic search)
-QDRANT_URL=http://qdrant:6333
-# OR for in-memory mode:
-#QDRANT_LOCATION=:memory:
-
-# Embedding Provider (required for semantic search)
-# Option 1: Ollama (recommended for local deployment)
-OLLAMA_BASE_URL=http://ollama:11434
-OLLAMA_EMBEDDING_MODEL=nomic-embed-text
-
-# Option 2: Amazon Bedrock (for AWS deployments)
-#AWS_REGION=us-east-1
-#BEDROCK_EMBEDDING_MODEL=amazon.titan-embed-text-v2:0
-
-# Token Storage (required for background operations - auto-enabled by semantic search)
-# Generate encryption key: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
-TOKEN_ENCRYPTION_KEY=your-encryption-key-here
-TOKEN_STORAGE_DB=/app/data/tokens.db
-
-# ===== OPTIONAL: DOCUMENT PROCESSING =====
-# Extract text from PDFs, images, DOCX for semantic search
-#ENABLE_DOCUMENT_PROCESSING=true
-#ENABLE_UNSTRUCTURED=true
-#UNSTRUCTURED_API_URL=http://unstructured:8000
-
-# ===== SUMMARY OF AUTO-ENABLEMENT =====
-# With ENABLE_SEMANTIC_SEARCH=true in OAuth mode:
-# ✅ Background operations enabled automatically
-# ✅ Refresh token storage enabled automatically
-# ✅ OAuth credentials required (DCR or pre-registered)
-# ✅ Encryption key required for token storage
-#
-# You only need to set ENABLE_SEMANTIC_SEARCH and provide the required
-# infrastructure (Qdrant, Ollama, encryption key). The rest is automatic!
-
-# For more advanced configuration, see env.sample
@@ -1,37 +0,0 @@
-# ============================================
-# SINGLE-USER BASICAUTH QUICK START
-# ============================================
-# Simplest deployment mode - one user, credentials in environment
-# Use for: Personal instances, local development, testing
-#
-# Copy this file to .env and fill in your credentials
-
-# ===== REQUIRED SETTINGS =====
-# Your Nextcloud instance URL (without trailing slash)
-NEXTCLOUD_HOST=http://localhost:8080
-
-# Your Nextcloud credentials
-NEXTCLOUD_USERNAME=admin
-NEXTCLOUD_PASSWORD=password
-
-# ===== OPTIONAL: EXPLICIT MODE DECLARATION =====
-# Recommended to avoid ambiguity
-MCP_DEPLOYMENT_MODE=single_user_basic
-
-# ===== OPTIONAL: SEMANTIC SEARCH =====
-# Uncomment to enable AI-powered semantic search
-# Requires: Qdrant + embedding provider (Ollama or Bedrock)
-#
-#ENABLE_SEMANTIC_SEARCH=true
-#QDRANT_LOCATION=:memory:
-#OLLAMA_BASE_URL=http://ollama:11434
-#OLLAMA_EMBEDDING_MODEL=nomic-embed-text
-
-# ===== OPTIONAL: DOCUMENT PROCESSING =====
-# Extract text from PDFs, images, DOCX for semantic search
-#ENABLE_DOCUMENT_PROCESSING=true
-#ENABLE_UNSTRUCTURED=true
-#UNSTRUCTURED_API_URL=http://unstructured:8000
-
-# That's it! Single-user mode is the simplest to configure.
-# For more options, see env.sample
@@ -1,133 +0,0 @@
-"""Alembic environment configuration for nextcloud-mcp-server.
-
-This module configures how Alembic runs database migrations for the
-token storage database. It supports both online and offline migration modes.
-
-Uses anyio for async operations, consistent with the project's async patterns.
-"""
-
-import logging
-from pathlib import Path
-
-import anyio
-from sqlalchemy import pool
-from sqlalchemy.engine import Connection
-from sqlalchemy.ext.asyncio import async_engine_from_config
-
-from alembic import context
-
-# Configure logging
-logger = logging.getLogger("alembic.env")
-
-# This is the Alembic Config object, which provides
-# access to the values within the .ini file in use.
-config = context.config
-
-# Update script location to point to package location
-# This allows alembic to find migrations when installed in site-packages
-script_location = Path(__file__).parent
-config.set_main_option("script_location", str(script_location))
-
-# We don't use SQLAlchemy models, so target_metadata is None
-# Migrations will be written manually using op.execute() for raw SQL
-target_metadata = None
-
-
-def get_database_url() -> str:
-    """
-    Get the database URL from Alembic config or environment.
-
-    The URL can be set in alembic.ini or passed via -x database_url=...
-    when running Alembic commands.
-
-    Returns:
-        Database URL (SQLite URL format)
-    """
-    # Check if URL is passed via -x database_url=...
-    url = context.get_x_argument(as_dictionary=True).get("database_url")
-
-    if not url:
-        # Fall back to alembic.ini configuration
-        url = config.get_main_option("sqlalchemy.url")
-
-    if not url:
-        # Default to /app/data/tokens.db for Docker deployments
-        db_path = Path("/app/data/tokens.db")
-        url = f"sqlite+aiosqlite:///{db_path}"
-        logger.warning(
-            f"No database URL configured, using default: {url}. "
-            "Set sqlalchemy.url in alembic.ini or pass -x database_url=..."
-        )
-
-    return url
-
-
-def run_migrations_offline() -> None:
-    """Run migrations in 'offline' mode.
-
-    This configures the context with just a URL and not an Engine,
-    though an Engine is acceptable here as well. By skipping the
-    Engine creation we don't even need a DBAPI to be available.
-
-    Calls to context.execute() here emit the given string to the
-    script output.
-
-    This mode is useful for generating SQL scripts without database access.
-    """
-    url = get_database_url()
-    context.configure(
-        url=url,
-        target_metadata=target_metadata,
-        literal_binds=True,
-        dialect_opts={"paramstyle": "named"},
-    )
-
-    with context.begin_transaction():
-        context.run_migrations()
-
-
-def do_run_migrations(connection: Connection) -> None:
-    """Execute migrations within a database connection."""
-    context.configure(connection=connection, target_metadata=target_metadata)
-
-    with context.begin_transaction():
-        context.run_migrations()
-
-
-async def run_async_migrations() -> None:
-    """Run migrations in 'online' mode with async support.
-
-    In this scenario we create an async Engine and associate
-    a connection with the context.
-    """
-    # Get database URL and update config
-    url = get_database_url()
-    config.set_main_option("sqlalchemy.url", url)
-
-    # Create async engine
-    connectable = async_engine_from_config(
-        config.get_section(config.config_ini_section, {}),
-        prefix="sqlalchemy.",
-        poolclass=pool.NullPool,  # Don't pool connections for migrations
-    )
-
-    async with connectable.connect() as connection:
-        await connection.run_sync(do_run_migrations)
-
-    await connectable.dispose()
-
-
-def run_migrations_online() -> None:
-    """Run migrations in 'online' mode.
-
-    This function is called from storage.py's initialize() method via
-    anyio.to_thread.run_sync(), so it always runs in a worker thread
-    with its own event loop. We can safely use anyio.run() here.
-    """
-    anyio.run(run_async_migrations)
-
-
-if context.is_offline_mode():
-    run_migrations_offline()
-else:
-    run_migrations_online()
@@ -1,185 +0,0 @@
-"""Initial schema for token storage database
-
-This migration creates the initial database schema including:
- refresh_tokens: OAuth refresh tokens and user profiles
- audit_logs: Audit trail for security events
- oauth_clients: OAuth client credentials (DCR)
- oauth_sessions: OAuth flow session state (ADR-004 Progressive Consent)
- registered_webhooks: Webhook registration tracking (both OAuth and BasicAuth)
- schema_version: Legacy schema version tracking (deprecated, use alembic_version)
-
-Revision ID: 001
-Revises:
-Create Date: 2025-12-17 22:00:00.000000
-
-"""
-
-from alembic import op
-
-# revision identifiers, used by Alembic.
-revision = "001"
-down_revision = None
-branch_labels = None
-depends_on = None
-
-
-def upgrade() -> None:
-    """Create initial database schema."""
-
-    # Refresh tokens table (OAuth mode only, for background jobs)
-    op.execute(
-        """
-        CREATE TABLE IF NOT EXISTS refresh_tokens (
-            user_id TEXT PRIMARY KEY,
-            encrypted_token BLOB NOT NULL,
-            expires_at INTEGER,
-            created_at INTEGER NOT NULL,
-            updated_at INTEGER NOT NULL,
-            -- ADR-004 Progressive Consent fields
-            flow_type TEXT DEFAULT 'hybrid',
-            token_audience TEXT DEFAULT 'nextcloud',
-            provisioned_at INTEGER,
-            provisioning_client_id TEXT,
-            scopes TEXT,
-            -- Browser session profile cache
-            user_profile TEXT,
-            profile_cached_at INTEGER
-        )
-        """
-    )
-
-    # Audit logs table (both OAuth and BasicAuth modes)
-    op.execute(
-        """
-        CREATE TABLE IF NOT EXISTS audit_logs (
-            id INTEGER PRIMARY KEY AUTOINCREMENT,
-            timestamp INTEGER NOT NULL,
-            event TEXT NOT NULL,
-            user_id TEXT NOT NULL,
-            resource_type TEXT,
-            resource_id TEXT,
-            auth_method TEXT,
-            hostname TEXT
-        )
-        """
-    )
-
-    # Index on audit logs for efficient queries
-    op.execute(
-        """
-        CREATE INDEX IF NOT EXISTS idx_audit_user_timestamp
-        ON audit_logs(user_id, timestamp)
-        """
-    )
-
-    # OAuth client credentials storage (OAuth mode only)
-    op.execute(
-        """
-        CREATE TABLE IF NOT EXISTS oauth_clients (
-            id INTEGER PRIMARY KEY,
-            client_id TEXT UNIQUE NOT NULL,
-            encrypted_client_secret BLOB NOT NULL,
-            client_id_issued_at INTEGER NOT NULL,
-            client_secret_expires_at INTEGER NOT NULL,
-            redirect_uris TEXT NOT NULL,
-            encrypted_registration_access_token BLOB,
-            registration_client_uri TEXT,
-            created_at INTEGER NOT NULL,
-            updated_at INTEGER NOT NULL
-        )
-        """
-    )
-
-    # OAuth flow sessions (ADR-004 Progressive Consent)
-    op.execute(
-        """
-        CREATE TABLE IF NOT EXISTS oauth_sessions (
-            session_id TEXT PRIMARY KEY,
-            client_id TEXT,
-            client_redirect_uri TEXT NOT NULL,
-            state TEXT,
-            code_challenge TEXT,
-            code_challenge_method TEXT,
-            mcp_authorization_code TEXT UNIQUE,
-            idp_access_token TEXT,
-            idp_refresh_token TEXT,
-            user_id TEXT,
-            created_at INTEGER NOT NULL,
-            expires_at INTEGER NOT NULL,
-            -- ADR-004 Progressive Consent fields
-            flow_type TEXT DEFAULT 'hybrid',
-            requested_scopes TEXT,
-            granted_scopes TEXT,
-            is_provisioning BOOLEAN DEFAULT FALSE
-        )
-        """
-    )
-
-    # Index for MCP authorization code lookups
-    op.execute(
-        """
-        CREATE INDEX IF NOT EXISTS idx_oauth_sessions_mcp_code
-        ON oauth_sessions(mcp_authorization_code)
-        """
-    )
-
-    # Legacy schema version tracking table
-    # NOTE: This is deprecated in favor of Alembic's alembic_version table
-    # Kept for backward compatibility with pre-Alembic databases
-    op.execute(
-        """
-        CREATE TABLE IF NOT EXISTS schema_version (
-            version INTEGER PRIMARY KEY,
-            applied_at REAL NOT NULL
-        )
-        """
-    )
-
-    # Registered webhooks tracking (both BasicAuth and OAuth modes)
-    op.execute(
-        """
-        CREATE TABLE IF NOT EXISTS registered_webhooks (
-            id INTEGER PRIMARY KEY AUTOINCREMENT,
-            webhook_id INTEGER NOT NULL UNIQUE,
-            preset_id TEXT NOT NULL,
-            created_at REAL NOT NULL
-        )
-        """
-    )
-
-    # Indexes for efficient webhook queries
-    op.execute(
-        """
-        CREATE INDEX IF NOT EXISTS idx_webhooks_preset
-        ON registered_webhooks(preset_id)
-        """
-    )
-
-    op.execute(
-        """
-        CREATE INDEX IF NOT EXISTS idx_webhooks_created
-        ON registered_webhooks(created_at)
-        """
-    )
-
-
-def downgrade() -> None:
-    """Drop all tables and indexes.
-
-    WARNING: This will destroy all data in the database!
-    Use with extreme caution.
-    """
-
-    # Drop indexes first
-    op.execute("DROP INDEX IF EXISTS idx_webhooks_created")
-    op.execute("DROP INDEX IF EXISTS idx_webhooks_preset")
-    op.execute("DROP INDEX IF EXISTS idx_oauth_sessions_mcp_code")
-    op.execute("DROP INDEX IF EXISTS idx_audit_user_timestamp")
-
-    # Drop tables
-    op.execute("DROP TABLE IF EXISTS registered_webhooks")
-    op.execute("DROP TABLE IF EXISTS schema_version")
-    op.execute("DROP TABLE IF EXISTS oauth_sessions")
-    op.execute("DROP TABLE IF EXISTS oauth_clients")
-    op.execute("DROP TABLE IF EXISTS audit_logs")
-    op.execute("DROP TABLE IF EXISTS refresh_tokens")
@@ -1,50 +0,0 @@
-"""Add app_passwords table for multi-user BasicAuth mode
-
-This migration adds support for storing app passwords that are provisioned
-via Astrolabe's personal settings. This enables background sync in
-multi-user BasicAuth mode without requiring OAuth.
-
-Revision ID: 002
-Revises: 001
-Create Date: 2026-01-13 12:00:00.000000
-
-"""
-
-from alembic import op
-
-# revision identifiers, used by Alembic.
-revision = "002"
-down_revision = "001"
-branch_labels = None
-depends_on = None
-
-
-def upgrade() -> None:
-    """Add app_passwords table for multi-user BasicAuth mode."""
-
-    # App passwords table for multi-user BasicAuth background sync
-    op.execute(
-        """
-        CREATE TABLE IF NOT EXISTS app_passwords (
-            user_id TEXT PRIMARY KEY,
-            encrypted_password BLOB NOT NULL,
-            created_at INTEGER NOT NULL,
-            updated_at INTEGER NOT NULL
-        )
-        """
-    )
-
-    # Index for efficient user lookups
-    op.execute(
-        """
-        CREATE INDEX IF NOT EXISTS idx_app_passwords_updated
-        ON app_passwords(updated_at)
-        """
-    )
-
-
-def downgrade() -> None:
-    """Drop app_passwords table."""
-
-    op.execute("DROP INDEX IF EXISTS idx_app_passwords_updated")
-    op.execute("DROP TABLE IF EXISTS app_passwords")
@@ -1,76 +0,0 @@
-"""Management API for Nextcloud MCP Server.
-
-Provides REST endpoints for the Nextcloud PHP app to query server status,
-user sessions, and vector sync metrics. All endpoints use OAuth bearer token
-authentication via the UnifiedTokenVerifier.
-
-This package is organized into modules by domain:
- management.py: Server status, user sessions, shared helpers
- passwords.py: App password provisioning for multi-user BasicAuth
- webhooks.py: Webhook registration management
- visualization.py: Search and PDF visualization endpoints
-"""
-
-# Re-export all public functions for backward compatibility
-from nextcloud_mcp_server.api.management import (
-    __version__,
-    _parse_float_param,
-    _parse_int_param,
-    _sanitize_error_for_client,
-    _validate_query_string,
-    extract_bearer_token,
-    get_server_status,
-    get_user_session,
-    get_vector_sync_status,
-    revoke_user_access,
-    validate_token_and_get_user,
-)
-from nextcloud_mcp_server.api.passwords import (
-    delete_app_password,
-    get_app_password_status,
-    provision_app_password,
-)
-from nextcloud_mcp_server.api.visualization import (
-    get_chunk_context,
-    get_pdf_preview,
-    unified_search,
-    vector_search,
-)
-from nextcloud_mcp_server.api.webhooks import (
-    create_webhook,
-    delete_webhook,
-    get_installed_apps,
-    list_webhooks,
-)
-
-__all__ = [
-    # Version
-    "__version__",
-    # Shared helpers (from management.py)
-    "extract_bearer_token",
-    "validate_token_and_get_user",
-    "_sanitize_error_for_client",
-    "_parse_int_param",
-    "_parse_float_param",
-    "_validate_query_string",
-    # Status endpoints (from management.py)
-    "get_server_status",
-    "get_vector_sync_status",
-    # Session endpoints (from management.py)
-    "get_user_session",
-    "revoke_user_access",
-    # Password endpoints (from passwords.py)
-    "provision_app_password",
-    "get_app_password_status",
-    "delete_app_password",
-    # Webhook endpoints (from webhooks.py)
-    "get_installed_apps",
-    "list_webhooks",
-    "create_webhook",
-    "delete_webhook",
-    # Visualization endpoints (from visualization.py)
-    "unified_search",
-    "vector_search",
-    "get_chunk_context",
-    "get_pdf_preview",
-]
@@ -1,519 +0,0 @@
-"""Management API endpoints for Nextcloud PHP app integration.
-
-ADR-018: Provides REST API endpoints for the Nextcloud PHP app to query:
- Server status and version
- User session information and background access status
- Vector sync metrics
-
-All endpoints use OAuth bearer token authentication via UnifiedTokenVerifier.
-The PHP app obtains tokens through PKCE flow and uses them to access these endpoints.
-
-Shared helper functions for other API modules are also exported from here:
- extract_bearer_token: Extract OAuth token from request
- validate_token_and_get_user: Validate token and get user ID
- _sanitize_error_for_client: Return safe error messages
- _parse_int_param, _parse_float_param, _validate_query_string: Parameter validation
-"""
-
-import logging
-import time
-from importlib.metadata import version
-from typing import Any
-
-from starlette.requests import Request
-from starlette.responses import JSONResponse
-
-logger = logging.getLogger(__name__)
-
-
-# Get package version from metadata
-__version__ = version("nextcloud-mcp-server")
-
-# Track server start time for uptime calculation
-_server_start_time = time.time()
-
-
-def extract_bearer_token(request: Request) -> str | None:
-    """Extract OAuth bearer token from Authorization header.
-
-    Args:
-        request: Starlette request
-
-    Returns:
-        Token string or None if no valid Authorization header
-    """
-    auth_header = request.headers.get("Authorization")
-    if not auth_header:
-        return None
-
-    # Parse "Bearer <token>"
-    parts = auth_header.split()
-    if len(parts) != 2 or parts[0].lower() != "bearer":
-        return None
-
-    return parts[1]
-
-
-async def validate_token_and_get_user(
-    request: Request,
-) -> tuple[str, dict[str, Any]]:
-    """Validate OAuth bearer token and extract user ID.
-
-    Uses verify_token_for_management_api which accepts any valid Nextcloud OIDC
-    token (not just MCP-audience tokens). This is needed because Astrolabe
-    (NC PHP app) uses its own OAuth client, separate from MCP server's client.
-
-    Security Model:
-    ~~~~~~~~~~~~~~~
-    - **Authentication** (this function): Verifies token is cryptographically valid
-      and extracts user identity from the `sub` claim.
-    - **Authorization** (calling endpoints): Each endpoint MUST verify that the
-      authenticated user owns the requested resource. For example:
-      - GET /users/{user_id}/session: Checks token_user_id == path_user_id (403 if mismatch)
-      - POST /users/{user_id}/revoke: Checks token_user_id == path_user_id (403 if mismatch)
-
-    This separation ensures that even without audience validation, users can only
-    access their own resources. Cross-user access is blocked at the authorization layer.
-
-    Args:
-        request: Starlette request with Authorization header
-
-    Returns:
-        Tuple of (user_id, validated_token_data)
-
-    Raises:
-        Exception: If token is invalid or missing
-    """
-    token = extract_bearer_token(request)
-    if not token:
-        raise ValueError("Missing Authorization header")
-
-    # Get token verifier from app state
-    # Note: This is set in app.py starlette_lifespan for OAuth mode
-    token_verifier = request.app.state.oauth_context["token_verifier"]
-
-    # Validate token for management API (handles both JWT and opaque tokens)
-    # Uses verify_token_for_management_api which accepts any valid Nextcloud token
-    # without requiring MCP audience - needed for Astrolabe integration (ADR-018)
-    access_token = await token_verifier.verify_token_for_management_api(token)
-
-    if not access_token:
-        raise ValueError("Token validation failed")
-
-    # Extract user ID from AccessToken.resource field (set during verification)
-    user_id = access_token.resource
-    if not user_id:
-        raise ValueError("Token missing user identifier")
-
-    # Return user_id and a dict with token info for compatibility
-    validated = {
-        "sub": user_id,
-        "client_id": access_token.client_id,
-        "scopes": access_token.scopes,
-        "expires_at": access_token.expires_at,
-    }
-
-    return user_id, validated
-
-
-def _sanitize_error_for_client(error: Exception, context: str = "") -> str:
-    """
-    Return a safe, generic error message for clients.
-
-    Detailed error is logged internally but not exposed to clients to prevent
-    information leakage (database paths, API URLs, tokens, etc.).
-
-    Args:
-        error: The exception that occurred
-        context: Optional context for logging (e.g., "revoke_user_access")
-
-    Returns:
-        Generic error message safe for client consumption
-    """
-    # Log detailed error for debugging
-    logger.error(f"Error in {context}: {error}", exc_info=True)
-
-    # Return generic message
-    return "An internal error occurred. Please contact your administrator."
-
-
-def _parse_int_param(
-    value: str | None,
-    default: int,
-    min_val: int,
-    max_val: int,
-    param_name: str,
-) -> int:
-    """Parse and validate integer parameter."""
-    if value is None:
-        return default
-    try:
-        parsed = int(value)
-    except ValueError:
-        raise ValueError(f"Invalid {param_name}: must be an integer")
-    if parsed < min_val or parsed > max_val:
-        raise ValueError(
-            f"Invalid {param_name}: must be between {min_val} and {max_val}"
-        )
-    return parsed
-
-
-def _parse_float_param(
-    value: Any,
-    default: float,
-    min_val: float,
-    max_val: float,
-    param_name: str,
-) -> float:
-    """Parse and validate float parameter."""
-    if value is None:
-        return default
-    try:
-        parsed = float(value)
-    except (ValueError, TypeError):
-        raise ValueError(f"Invalid {param_name}: must be a number")
-    if parsed < min_val or parsed > max_val:
-        raise ValueError(
-            f"Invalid {param_name}: must be between {min_val} and {max_val}"
-        )
-    return parsed
-
-
-def _validate_query_string(query: str, max_length: int = 10000) -> None:
-    """Validate query string length."""
-    if len(query) > max_length:
-        raise ValueError(f"Query too long: maximum {max_length} characters")
-
-
-async def get_server_status(request: Request) -> JSONResponse:
-    """GET /api/v1/status - Server status and version.
-
-    Returns basic server information including version, auth mode,
-    vector sync status, and uptime.
-
-    Public endpoint - no authentication required.
-    """
-    # Public endpoint - no authentication required
-
-    # Get configuration
-    from nextcloud_mcp_server.config import get_settings
-
-    settings = get_settings()
-
-    # Calculate uptime
-    uptime_seconds = int(time.time() - _server_start_time)
-
-    # Determine auth mode using proper mode detection
-    from nextcloud_mcp_server.config_validators import AuthMode, detect_auth_mode
-
-    mode = detect_auth_mode(settings)
-
-    # Map deployment mode to auth_mode for API response
-    # This helps clients (like Astrolabe) determine which auth flow to use
-    if mode == AuthMode.OAUTH_SINGLE_AUDIENCE or mode == AuthMode.OAUTH_TOKEN_EXCHANGE:
-        auth_mode = "oauth"
-    elif mode == AuthMode.MULTI_USER_BASIC:
-        auth_mode = "multi_user_basic"
-    elif mode == AuthMode.SINGLE_USER_BASIC:
-        auth_mode = "basic"
-    elif mode == AuthMode.SMITHERY_STATELESS:
-        auth_mode = "smithery"
-    else:
-        auth_mode = "unknown"
-
-    response_data = {
-        "version": __version__,
-        "auth_mode": auth_mode,
-        "vector_sync_enabled": settings.vector_sync_enabled,
-        "uptime_seconds": uptime_seconds,
-        "management_api_version": "1.0",
-    }
-
-    # Add app password support indicator for multi-user BasicAuth mode
-    if mode == AuthMode.MULTI_USER_BASIC:
-        response_data["supports_app_passwords"] = settings.enable_offline_access
-
-    # Include OIDC configuration if OAuth is available
-    # This includes OAuth mode AND hybrid mode (multi_user_basic + offline_access)
-    # Astrolabe needs OIDC config to discover IdP for OAuth flow in hybrid mode
-    oauth_provisioning_available = auth_mode == "oauth" or (
-        mode == AuthMode.MULTI_USER_BASIC and settings.enable_offline_access
-    )
-    if oauth_provisioning_available:
-        # Provide IdP discovery information for NC PHP app
-        oidc_config = {}
-
-        if settings.oidc_discovery_url:
-            oidc_config["discovery_url"] = settings.oidc_discovery_url
-
-        if settings.oidc_issuer:
-            oidc_config["issuer"] = settings.oidc_issuer
-
-        if oidc_config:
-            response_data["oidc"] = oidc_config
-
-    return JSONResponse(response_data)
-
-
-async def get_vector_sync_status(request: Request) -> JSONResponse:
-    """GET /api/v1/vector-sync/status - Vector sync metrics.
-
-    Returns real-time indexing status and metrics.
-
-    Requires: VECTOR_SYNC_ENABLED=true
-
-    Public endpoint - no authentication required.
-    """
-    # Public endpoint - no authentication required
-
-    from nextcloud_mcp_server.config import get_settings
-
-    settings = get_settings()
-    if not settings.vector_sync_enabled:
-        return JSONResponse(
-            {"error": "Vector sync is disabled on this server"},
-            status_code=404,
-        )
-
-    try:
-        # Get document receive stream from app state (set by starlette_lifespan in app.py)
-        document_receive_stream = getattr(
-            request.app.state, "document_receive_stream", None
-        )
-
-        if document_receive_stream is None:
-            logger.debug("document_receive_stream not available in app state")
-            return JSONResponse(
-                {
-                    "status": "unknown",
-                    "indexed_documents": 0,
-                    "pending_documents": 0,
-                    "message": "Vector sync stream not initialized",
-                }
-            )
-
-        # Get pending count from stream statistics
-        stream_stats = document_receive_stream.statistics()
-        pending_count = stream_stats.current_buffer_used
-
-        # Get Qdrant client and query indexed count
-        indexed_count = 0
-        try:
-            from qdrant_client.models import Filter
-
-            from nextcloud_mcp_server.vector.placeholder import get_placeholder_filter
-            from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
-
-            qdrant_client = await get_qdrant_client()
-
-            # Count documents in collection, excluding placeholders
-            count_result = await qdrant_client.count(
-                collection_name=settings.get_collection_name(),
-                count_filter=Filter(must=[get_placeholder_filter()]),
-            )
-            indexed_count = count_result.count
-
-        except Exception as e:
-            logger.warning(f"Failed to query Qdrant for indexed count: {e}")
-            # Continue with indexed_count = 0
-
-        # Determine status
-        status = "syncing" if pending_count > 0 else "idle"
-
-        return JSONResponse(
-            {
-                "status": status,
-                "indexed_documents": indexed_count,
-                "pending_documents": pending_count,
-            }
-        )
-
-    except Exception as e:
-        error_msg = _sanitize_error_for_client(e, "get_vector_sync_status")
-        return JSONResponse(
-            {"error": error_msg},
-            status_code=500,
-        )
-
-
-async def get_user_session(request: Request) -> JSONResponse:
-    """GET /api/v1/users/{user_id}/session - User session details.
-
-    Returns information about the user's MCP session including:
-    - Background access status (offline_access)
-    - IdP profile information
-
-    Requires OAuth bearer token. The user_id in the path must match
-    the user_id in the token.
-    """
-    try:
-        # Validate OAuth token and extract user
-        token_user_id, validated = await validate_token_and_get_user(request)
-    except Exception as e:
-        error_msg = _sanitize_error_for_client(e, "get_user_session_auth")
-        return JSONResponse(
-            {"error": error_msg},
-            status_code=401,
-        )
-
-    # Get user_id from path
-    path_user_id = request.path_params.get("user_id")
-
-    # Verify token user matches requested user
-    if token_user_id != path_user_id:
-        logger.warning(
-            f"User {token_user_id} attempted to access session for {path_user_id}"
-        )
-        return JSONResponse(
-            {
-                "error": "Forbidden",
-                "message": "Cannot access another user's session",
-            },
-            status_code=403,
-        )
-
-    # Check if offline access is enabled
-    # Use settings.enable_offline_access which handles both ENABLE_BACKGROUND_OPERATIONS (new)
-    # and ENABLE_OFFLINE_ACCESS (deprecated) environment variables
-    from nextcloud_mcp_server.config import get_settings
-
-    settings = get_settings()
-    enable_offline_access = settings.enable_offline_access
-
-    if not enable_offline_access:
-        # Offline access disabled - return minimal session info
-        return JSONResponse(
-            {
-                "session_id": token_user_id,
-                "background_access_granted": False,
-            }
-        )
-
-    # Get refresh token storage from app state
-    storage = request.app.state.oauth_context.get("storage")
-    if not storage:
-        logger.error("Refresh token storage not available in app state")
-        return JSONResponse(
-            {
-                "session_id": token_user_id,
-                "background_access_granted": False,
-                "error": "Storage not configured",
-            }
-        )
-
-    try:
-        # Check if user has refresh token stored
-        refresh_token_data = await storage.get_refresh_token(token_user_id)
-
-        if not refresh_token_data:
-            # No refresh token - user hasn't provisioned background access
-            return JSONResponse(
-                {
-                    "session_id": token_user_id,
-                    "background_access_granted": False,
-                }
-            )
-
-        # User has background access - get profile info
-        profile = await storage.get_user_profile(token_user_id)
-
-        response_data = {
-            "session_id": token_user_id,
-            "background_access_granted": True,
-            "background_access_details": {
-                "granted_at": refresh_token_data.get("created_at"),
-                "scopes": refresh_token_data.get("scope", "").split(),
-            },
-        }
-
-        if profile:
-            response_data["idp_profile"] = profile
-
-        return JSONResponse(response_data)
-
-    except Exception as e:
-        error_msg = _sanitize_error_for_client(e, "get_user_session")
-        return JSONResponse(
-            {"error": error_msg},
-            status_code=500,
-        )
-
-
-async def revoke_user_access(request: Request) -> JSONResponse:
-    """POST /api/v1/users/{user_id}/revoke - Revoke user's background access.
-
-    Deletes the user's stored refresh token, removing their offline access.
-
-    Requires OAuth bearer token. The user_id in the path must match
-    the user_id in the token.
-    """
-    try:
-        # Validate OAuth token and extract user
-        token_user_id, validated = await validate_token_and_get_user(request)
-    except Exception as e:
-        logger.warning(f"Unauthorized access to /api/v1/users/{{user_id}}/revoke: {e}")
-        return JSONResponse(
-            {
-                "error": "Unauthorized",
-                "message": _sanitize_error_for_client(e, "revoke_user_access"),
-            },
-            status_code=401,
-        )
-
-    # Get user_id from path
-    path_user_id = request.path_params.get("user_id")
-
-    # Verify token user matches requested user
-    if token_user_id != path_user_id:
-        logger.warning(
-            f"User {token_user_id} attempted to revoke access for {path_user_id}"
-        )
-        return JSONResponse(
-            {
-                "error": "Forbidden",
-                "message": "Cannot revoke another user's access",
-            },
-            status_code=403,
-        )
-
-    # Get token broker from app state
-    oauth_context = request.app.state.oauth_context
-    if oauth_context is None:
-        logger.error("OAuth context not initialized")
-        return JSONResponse(
-            {"error": "OAuth not enabled"},
-            status_code=500,
-        )
-
-    token_broker = oauth_context.get("token_broker")
-    if not token_broker:
-        logger.error("Token broker not available in app state")
-        return JSONResponse(
-            {"error": "Token broker not configured"},
-            status_code=500,
-        )
-
-    try:
-        # Delete refresh token from storage
-        await token_broker.storage.delete_refresh_token(token_user_id)
-
-        # CRITICAL: Invalidate all cached tokens for this user
-        await token_broker.cache.invalidate(token_user_id)
-
-        logger.info(
-            f"Revoked background access for user {token_user_id} (cache and storage cleared)"
-        )
-
-        return JSONResponse(
-            {
-                "success": True,
-                "message": f"Background access revoked for {token_user_id}",
-            }
-        )
-
-    except Exception as e:
-        error_msg = _sanitize_error_for_client(e, "revoke_user_access")
-        return JSONResponse(
-            {"success": False, "error": error_msg},
-            status_code=500,
-        )
@@ -1,429 +0,0 @@
-"""App password management API endpoints.
-
-Provides REST API endpoints for app password provisioning in multi-user BasicAuth mode.
-These endpoints are used by the Nextcloud PHP app (Astrolabe) to:
- Store app passwords for background sync operations
- Check app password status
- Delete stored app passwords
-
-Authentication is via BasicAuth with the user's Nextcloud credentials.
-Passwords are validated against Nextcloud before being stored.
-"""
-
-import base64
-import logging
-import re
-import time
-from collections import defaultdict
-from typing import TYPE_CHECKING
-
-import httpx
-from starlette.requests import Request
-from starlette.responses import JSONResponse
-
-if TYPE_CHECKING:
-    from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
-
-from nextcloud_mcp_server.api.management import _sanitize_error_for_client
-
-logger = logging.getLogger(__name__)
-
-# App password format regex (Nextcloud format: xxxxx-xxxxx-xxxxx-xxxxx-xxxxx)
-APP_PASSWORD_PATTERN = re.compile(
-    r"^[a-zA-Z0-9]{5}-[a-zA-Z0-9]{5}-[a-zA-Z0-9]{5}-[a-zA-Z0-9]{5}-[a-zA-Z0-9]{5}$"
-)
-
-# Timeout for Nextcloud API validation requests (seconds)
-NEXTCLOUD_VALIDATION_TIMEOUT = 10.0
-
-# Rate limiting configuration for app password provisioning
-# Limits: 5 attempts per user per hour
-RATE_LIMIT_MAX_ATTEMPTS = 5
-RATE_LIMIT_WINDOW_SECONDS = 3600  # 1 hour
-
-# In-memory rate limiter storage
-# Structure: {user_id: [(timestamp, success), ...]}
-_rate_limit_attempts: dict[str, list[tuple[float, bool]]] = defaultdict(list)
-
-
-def _check_rate_limit(user_id: str) -> tuple[bool, int]:
-    """Check if user is rate limited for app password operations.
-
-    Implements a sliding window rate limiter to prevent brute-force attacks
-    on the app password provisioning endpoint.
-
-    Args:
-        user_id: User identifier to check
-
-    Returns:
-        Tuple of (is_allowed, seconds_until_retry)
-        - is_allowed: True if request should be allowed
-        - seconds_until_retry: Seconds to wait if rate limited (0 if allowed)
-    """
-    current_time = time.time()
-    window_start = current_time - RATE_LIMIT_WINDOW_SECONDS
-
-    # Clean up old attempts outside the window
-    _rate_limit_attempts[user_id] = [
-        (ts, success)
-        for ts, success in _rate_limit_attempts[user_id]
-        if ts > window_start
-    ]
-
-    # Count recent attempts (both successful and failed)
-    recent_attempts = len(_rate_limit_attempts[user_id])
-
-    if recent_attempts >= RATE_LIMIT_MAX_ATTEMPTS:
-        # Find when the oldest attempt in the window will expire
-        oldest_attempt = min(ts for ts, _ in _rate_limit_attempts[user_id])
-        seconds_until_retry = int(
-            oldest_attempt + RATE_LIMIT_WINDOW_SECONDS - current_time
-        )
-        return False, max(1, seconds_until_retry)
-
-    return True, 0
-
-
-def _record_rate_limit_attempt(user_id: str, success: bool) -> None:
-    """Record an app password provisioning attempt for rate limiting.
-
-    Args:
-        user_id: User identifier
-        success: Whether the attempt was successful
-    """
-    _rate_limit_attempts[user_id].append((time.time(), success))
-
-
-def _extract_basic_auth(
-    request: Request, path_user_id: str
-) -> tuple[str, str, JSONResponse | None]:
-    """Extract and validate BasicAuth credentials from request.
-
-    Validates:
-    1. Authorization header is present and valid BasicAuth format
-    2. Username in credentials matches the path user_id
-
-    Args:
-        request: Starlette request with Authorization header
-        path_user_id: User ID from the URL path to verify against
-
-    Returns:
-        Tuple of (username, password, error_response)
-        - If successful: (username, password, None)
-        - If failed: ("", "", JSONResponse with error)
-    """
-    auth_header = request.headers.get("Authorization")
-
-    if not auth_header or not auth_header.startswith("Basic "):
-        return (
-            "",
-            "",
-            JSONResponse(
-                {"success": False, "error": "Missing BasicAuth credentials"},
-                status_code=401,
-            ),
-        )
-
-    try:
-        # Decode BasicAuth
-        encoded = auth_header.split(" ", 1)[1]
-        decoded = base64.b64decode(encoded).decode("utf-8")
-        username, password = decoded.split(":", 1)
-    except Exception:
-        return (
-            "",
-            "",
-            JSONResponse(
-                {"success": False, "error": "Invalid BasicAuth format"},
-                status_code=401,
-            ),
-        )
-
-    # Verify username matches path user_id
-    if username != path_user_id:
-        logger.warning(
-            f"Username mismatch in app password operation for path user {path_user_id}"
-        )
-        return (
-            "",
-            "",
-            JSONResponse(
-                {"success": False, "error": "Username does not match path user_id"},
-                status_code=403,
-            ),
-        )
-
-    return username, password, None
-
-
-async def _get_app_password_storage(request: Request) -> "RefreshTokenStorage":
-    """Get or initialize RefreshTokenStorage for app password operations.
-
-    Checks app.state.storage first, then falls back to creating from environment.
-    This helper avoids repeated storage initialization logic across endpoints.
-
-    Args:
-        request: Starlette request with app state
-
-    Returns:
-        Initialized RefreshTokenStorage instance
-    """
-    from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
-
-    storage = getattr(request.app.state, "storage", None)
-
-    if not storage:
-        # Multi-user BasicAuth mode may not have oauth_context
-        # Initialize storage from environment
-        storage = RefreshTokenStorage.from_env()
-        await storage.initialize()
-
-    return storage
-
-
-async def provision_app_password(request: Request) -> JSONResponse:
-    """POST /api/v1/users/{user_id}/app-password - Store app password for background sync.
-
-    This endpoint is used by Astrolabe (Nextcloud PHP app) to provision app passwords
-    for multi-user BasicAuth mode background sync.
-
-    The request must include BasicAuth credentials where:
-    - username: Nextcloud user ID (must match path user_id)
-    - password: The app password being provisioned
-
-    The MCP server validates the app password against Nextcloud before storing it.
-    This proves the user owns the password and has access to Nextcloud.
-
-    Security model:
-    - User identity is verified via BasicAuth against Nextcloud
-    - App password is encrypted before storage
-    - Only the user who owns the password can provision it
-    - Rate limited to prevent brute-force attacks
-    """
-    from nextcloud_mcp_server.config import get_settings
-
-    # Get user_id from path
-    path_user_id = request.path_params.get("user_id")
-    if not path_user_id:
-        return JSONResponse(
-            {"success": False, "error": "Missing user_id in path"},
-            status_code=400,
-        )
-
-    # Check rate limit before processing
-    is_allowed, retry_after = _check_rate_limit(path_user_id)
-    if not is_allowed:
-        logger.warning(
-            f"Rate limit exceeded for app password provisioning: {path_user_id}"
-        )
-        return JSONResponse(
-            {
-                "success": False,
-                "error": f"Rate limit exceeded. Try again in {retry_after} seconds.",
-            },
-            status_code=429,
-            headers={"Retry-After": str(retry_after)},
-        )
-
-    # Extract and validate BasicAuth credentials
-    username, app_password, error_response = _extract_basic_auth(request, path_user_id)
-    if error_response is not None:
-        _record_rate_limit_attempt(path_user_id, success=False)
-        return error_response
-
-    # Validate app password format
-    if not APP_PASSWORD_PATTERN.match(app_password):
-        _record_rate_limit_attempt(path_user_id, success=False)
-        return JSONResponse(
-            {"success": False, "error": "Invalid app password format"},
-            status_code=400,
-        )
-
-    # Get Nextcloud host from settings
-    settings = get_settings()
-    nextcloud_host = settings.nextcloud_host
-
-    if not nextcloud_host:
-        logger.error("NEXTCLOUD_HOST not configured")
-        return JSONResponse(
-            {"success": False, "error": "Server not configured"},
-            status_code=500,
-        )
-
-    # Validate app password against Nextcloud
-    try:
-        async with httpx.AsyncClient(timeout=NEXTCLOUD_VALIDATION_TIMEOUT) as client:
-            # Use OCS API to verify credentials
-            test_url = f"{nextcloud_host}/ocs/v1.php/cloud/user"
-            response = await client.get(
-                test_url,
-                auth=(username, app_password),
-                params={"format": "json"},
-                headers={"OCS-APIRequest": "true"},
-            )
-
-            if response.status_code != 200:
-                logger.warning(
-                    f"App password validation failed for user: HTTP {response.status_code}"
-                )
-                _record_rate_limit_attempt(path_user_id, success=False)
-                return JSONResponse(
-                    {"success": False, "error": "Invalid app password"},
-                    status_code=401,
-                )
-
-            # Verify the user ID from response matches
-            data = response.json()
-            ocs_user_id = data.get("ocs", {}).get("data", {}).get("id")
-            if ocs_user_id != username:
-                logger.warning("User ID mismatch in OCS response")
-                _record_rate_limit_attempt(path_user_id, success=False)
-                return JSONResponse(
-                    {"success": False, "error": "User ID mismatch"},
-                    status_code=403,
-                )
-
-    except httpx.RequestError as e:
-        logger.error(f"Failed to validate app password: {e}")
-        return JSONResponse(
-            {"success": False, "error": "Failed to validate credentials"},
-            status_code=500,
-        )
-
-    # Store the validated app password
-    try:
-        storage = await _get_app_password_storage(request)
-        await storage.store_app_password(username, app_password)
-
-        _record_rate_limit_attempt(path_user_id, success=True)
-        logger.info(f"Provisioned app password for user: {username}")
-
-        return JSONResponse(
-            {
-                "success": True,
-                "message": f"App password stored for {username}",
-            }
-        )
-
-    except Exception as e:
-        error_msg = _sanitize_error_for_client(e, "provision_app_password")
-        return JSONResponse(
-            {"success": False, "error": error_msg},
-            status_code=500,
-        )
-
-
-async def get_app_password_status(request: Request) -> JSONResponse:
-    """GET /api/v1/users/{user_id}/app-password - Check if user has provisioned app password.
-
-    Returns status of background sync access for multi-user BasicAuth mode.
-
-    Requires BasicAuth with the user's app password for authentication.
-    """
-    # Get user_id from path
-    path_user_id = request.path_params.get("user_id")
-    if not path_user_id:
-        return JSONResponse(
-            {"success": False, "error": "Missing user_id in path"},
-            status_code=400,
-        )
-
-    # Extract and validate BasicAuth credentials
-    username, _, error_response = _extract_basic_auth(request, path_user_id)
-    if error_response is not None:
-        return error_response
-
-    try:
-        storage = await _get_app_password_storage(request)
-        app_password = await storage.get_app_password(username)
-
-        return JSONResponse(
-            {
-                "success": True,
-                "user_id": username,
-                "has_app_password": app_password is not None,
-            }
-        )
-
-    except Exception as e:
-        error_msg = _sanitize_error_for_client(e, "get_app_password_status")
-        return JSONResponse(
-            {"success": False, "error": error_msg},
-            status_code=500,
-        )
-
-
-async def delete_app_password(request: Request) -> JSONResponse:
-    """DELETE /api/v1/users/{user_id}/app-password - Delete stored app password.
-
-    Removes the user's app password from MCP server storage.
-
-    Requires BasicAuth with the user's credentials.
-    """
-    from nextcloud_mcp_server.config import get_settings
-
-    # Get user_id from path
-    path_user_id = request.path_params.get("user_id")
-    if not path_user_id:
-        return JSONResponse(
-            {"success": False, "error": "Missing user_id in path"},
-            status_code=400,
-        )
-
-    # Extract and validate BasicAuth credentials
-    username, password, error_response = _extract_basic_auth(request, path_user_id)
-    if error_response is not None:
-        return error_response
-
-    # Validate credentials against Nextcloud
-    settings = get_settings()
-    nextcloud_host = settings.nextcloud_host
-
-    try:
-        async with httpx.AsyncClient(timeout=NEXTCLOUD_VALIDATION_TIMEOUT) as client:
-            test_url = f"{nextcloud_host}/ocs/v1.php/cloud/user"
-            response = await client.get(
-                test_url,
-                auth=(username, password),
-                params={"format": "json"},
-                headers={"OCS-APIRequest": "true"},
-            )
-
-            if response.status_code != 200:
-                return JSONResponse(
-                    {"success": False, "error": "Invalid credentials"},
-                    status_code=401,
-                )
-    except httpx.RequestError as e:
-        logger.error(f"Failed to validate credentials: {e}")
-        return JSONResponse(
-            {"success": False, "error": "Failed to validate credentials"},
-            status_code=500,
-        )
-
-    try:
-        storage = await _get_app_password_storage(request)
-        deleted = await storage.delete_app_password(username)
-
-        if deleted:
-            logger.info(f"Deleted app password for user: {username}")
-            return JSONResponse(
-                {
-                    "success": True,
-                    "message": f"App password deleted for {username}",
-                }
-            )
-        else:
-            return JSONResponse(
-                {
-                    "success": True,
-                    "message": "No app password found to delete",
-                }
-            )
-
-    except Exception as e:
-        error_msg = _sanitize_error_for_client(e, "delete_app_password")
-        return JSONResponse(
-            {"success": False, "error": error_msg},
-            status_code=500,
-        )
@@ -1,813 +0,0 @@
-"""Visualization API endpoints for search and PDF preview.
-
-ADR-018: Provides REST API endpoints for the Nextcloud PHP app (Astrolabe) to:
- Execute unified search with semantic/BM25/hybrid algorithms
- Execute vector search with PCA visualization coordinates
- Fetch chunk context with surrounding text
- Render PDF pages server-side (avoiding CSP/worker issues)
-
-All endpoints require OAuth bearer token authentication via UnifiedTokenVerifier.
-"""
-
-import base64
-import logging
-from typing import TYPE_CHECKING, Any
-
-import pymupdf
-
-if TYPE_CHECKING:
-    pass
-
-from starlette.requests import Request
-from starlette.responses import JSONResponse
-
-from nextcloud_mcp_server.api.management import (
-    _parse_float_param,
-    _parse_int_param,
-    _sanitize_error_for_client,
-    _validate_query_string,
-    extract_bearer_token,
-    validate_token_and_get_user,
-)
-
-logger = logging.getLogger(__name__)
-
-
-async def unified_search(request: Request) -> JSONResponse:
-    """POST /api/v1/search - Search endpoint for Nextcloud Unified Search.
-
-    Optimized search endpoint for the Nextcloud Unified Search provider
-    and other PHP app integrations. Returns results with metadata needed
-    for navigation to source documents.
-
-    Request body:
-    {
-        "query": "search query",
-        "algorithm": "semantic|bm25|hybrid",  // default: hybrid
-        "limit": 20,  // max: 100
-        "offset": 0,  // pagination offset
-        "include_pca": false,  // optional PCA coordinates
-        "include_chunks": true  // include text snippets
-    }
-
-    Response:
-    {
-        "results": [{
-            "id": "doc123",
-            "doc_type": "note",
-            "title": "Document Title",
-            "excerpt": "Matching text snippet...",
-            "score": 0.85,
-            "path": "/path/to/file.txt",  // for files
-            "board_id": 1,  // for deck cards
-            "card_id": 42
-        }],
-        "total_found": 150,
-        "algorithm_used": "hybrid"
-    }
-
-    Requires OAuth bearer token for user filtering.
-    """
-    from nextcloud_mcp_server.config import get_settings
-
-    settings = get_settings()
-    if not settings.vector_sync_enabled:
-        return JSONResponse(
-            {"error": "Vector sync is disabled on this server"},
-            status_code=404,
-        )
-
-    # Validate OAuth token and extract user
-    try:
-        user_id, _validated = await validate_token_and_get_user(request)
-    except Exception as e:
-        logger.warning(f"Unauthorized access to /api/v1/search: {e}")
-        return JSONResponse(
-            {
-                "error": "Unauthorized",
-                "message": _sanitize_error_for_client(e, "unified_search"),
-            },
-            status_code=401,
-        )
-
-    try:
-        # Parse request body
-        body = await request.json()
-
-        # Validate and parse parameters
-        try:
-            query = body.get("query", "")
-            _validate_query_string(query, max_length=10000)
-
-            limit = _parse_int_param(
-                str(body.get("limit")) if body.get("limit") is not None else None,
-                20,
-                1,
-                100,
-                "limit",
-            )
-
-            offset = _parse_int_param(
-                str(body.get("offset")) if body.get("offset") is not None else None,
-                0,
-                0,
-                1000000,
-                "offset",
-            )
-
-            score_threshold = _parse_float_param(
-                body.get("score_threshold"),
-                0.0,
-                0.0,
-                1.0,
-                "score_threshold",
-            )
-        except ValueError as e:
-            return JSONResponse({"error": str(e)}, status_code=400)
-
-        algorithm = body.get("algorithm", "hybrid")
-        fusion = body.get("fusion", "rrf")
-        include_pca = body.get("include_pca", False)
-        include_chunks = body.get("include_chunks", True)
-        doc_types = body.get("doc_types")  # Optional filter
-
-        if not query:
-            return JSONResponse({"results": [], "total_found": 0})
-
-        # Validate algorithm
-        valid_algorithms = {"semantic", "bm25", "hybrid"}
-        if algorithm not in valid_algorithms:
-            algorithm = "hybrid"
-
-        # Validate fusion method
-        valid_fusions = {"rrf", "dbsf"}
-        if fusion not in valid_fusions:
-            fusion = "rrf"
-
-        # Execute search using the appropriate algorithm
-        from nextcloud_mcp_server.search import (
-            BM25HybridSearchAlgorithm,
-            SemanticSearchAlgorithm,
-        )
-
-        # Select search algorithm
-        if algorithm == "semantic":
-            search_algo = SemanticSearchAlgorithm(score_threshold=score_threshold)
-        else:
-            search_algo = BM25HybridSearchAlgorithm(
-                score_threshold=score_threshold, fusion=fusion
-            )
-
-        # Request extra results to handle offset
-        search_limit = limit + offset
-
-        # Execute search
-        all_results = []
-        if doc_types and isinstance(doc_types, list):
-            for doc_type in doc_types:
-                if doc_type:
-                    results = await search_algo.search(
-                        query=query,
-                        user_id=user_id,
-                        limit=search_limit,
-                        doc_type=doc_type,
-                    )
-                    all_results.extend(results)
-            all_results.sort(key=lambda r: r.score, reverse=True)
-        else:
-            all_results = await search_algo.search(
-                query=query,
-                user_id=user_id,
-                limit=search_limit,
-            )
-
-        # Sort results by score (no deduplication - show all chunks)
-        sorted_results = sorted(all_results, key=lambda r: r.score, reverse=True)
-
-        # Calculate total and apply pagination
-        total_found = len(sorted_results)
-        paginated_results = sorted_results[offset : offset + limit]
-
-        # Format results for Unified Search
-        formatted_results = []
-        for result in paginated_results:
-            # Get document ID (prefer note_id for notes)
-            doc_id = result.id
-            if result.metadata and "note_id" in result.metadata:
-                doc_id = result.metadata["note_id"]
-
-            result_data: dict[str, Any] = {
-                "id": doc_id,
-                "doc_type": result.doc_type,
-                "title": result.title,
-                "score": result.score,
-            }
-
-            # Include excerpt/chunk if requested (full content, no truncation)
-            if include_chunks and result.excerpt:
-                result_data["excerpt"] = result.excerpt
-
-            # Include navigation metadata from result.metadata
-            if result.metadata:
-                # File path and mimetype for files
-                if "path" in result.metadata:
-                    result_data["path"] = result.metadata["path"]
-                if "mime_type" in result.metadata:
-                    result_data["mime_type"] = result.metadata["mime_type"]
-
-                # Deck card navigation
-                if "board_id" in result.metadata:
-                    result_data["board_id"] = result.metadata["board_id"]
-                if "card_id" in result.metadata:
-                    result_data["card_id"] = result.metadata["card_id"]
-
-                # Calendar event metadata
-                if "calendar_id" in result.metadata:
-                    result_data["calendar_id"] = result.metadata["calendar_id"]
-                if "event_uid" in result.metadata:
-                    result_data["event_uid"] = result.metadata["event_uid"]
-
-            # Add PDF page metadata
-            if result.page_number is not None:
-                result_data["page_number"] = result.page_number
-            if result.page_count is not None:
-                result_data["page_count"] = result.page_count
-
-            # Add chunk metadata (always present, defaults to 0 and 1)
-            result_data["chunk_index"] = result.chunk_index
-            result_data["total_chunks"] = result.total_chunks
-
-            # Add chunk offsets for modal navigation
-            if result.chunk_start_offset is not None:
-                result_data["chunk_start_offset"] = result.chunk_start_offset
-            if result.chunk_end_offset is not None:
-                result_data["chunk_end_offset"] = result.chunk_end_offset
-
-            formatted_results.append(result_data)
-
-        response_data: dict[str, Any] = {
-            "results": formatted_results,
-            "total_found": total_found,
-            "algorithm_used": algorithm,
-        }
-
-        # Optional PCA coordinates
-        if include_pca and len(paginated_results) >= 2:
-            try:
-                from nextcloud_mcp_server.vector.visualization import (
-                    compute_pca_coordinates,
-                )
-
-                if search_algo.query_embedding is not None:
-                    query_embedding = search_algo.query_embedding
-                else:
-                    from nextcloud_mcp_server.embedding.service import (
-                        get_embedding_service,
-                    )
-
-                    embedding_service = get_embedding_service()
-                    query_embedding = await embedding_service.embed(query)
-
-                pca_data = await compute_pca_coordinates(
-                    paginated_results, query_embedding
-                )
-                response_data["pca_data"] = pca_data
-            except Exception as e:
-                logger.warning(f"Failed to compute PCA for unified search: {e}")
-
-        return JSONResponse(response_data)
-
-    except Exception as e:
-        logger.error(f"Error in unified search: {e}")
-        return JSONResponse(
-            {
-                "error": "Internal error",
-                "message": _sanitize_error_for_client(e, "unified_search"),
-            },
-            status_code=500,
-        )
-
-
-async def vector_search(request: Request) -> JSONResponse:
-    """POST /api/v1/vector-viz/search - Vector search for visualization.
-
-    Executes semantic search and returns results with optional PCA coordinates
-    for 2D visualization.
-
-    Request body:
-    {
-        "query": "search query",
-        "algorithm": "semantic|bm25|hybrid",  // default: hybrid
-        "limit": 10,  // max: 50
-        "include_pca": true,  // whether to include 2D coordinates
-        "doc_types": ["note", "file"]  // optional filter by document types
-    }
-
-    Requires OAuth bearer token for user filtering.
-    """
-    from nextcloud_mcp_server.config import get_settings
-
-    settings = get_settings()
-    if not settings.vector_sync_enabled:
-        return JSONResponse(
-            {"error": "Vector sync is disabled on this server"},
-            status_code=404,
-        )
-
-    # Validate OAuth token and extract user
-    try:
-        user_id, _validated = await validate_token_and_get_user(request)
-    except Exception as e:
-        logger.warning(f"Unauthorized access to /api/v1/vector-viz/search: {e}")
-        return JSONResponse(
-            {
-                "error": "Unauthorized",
-                "message": _sanitize_error_for_client(e, "vector_search"),
-            },
-            status_code=401,
-        )
-
-    try:
-        # Parse request body
-        body = await request.json()
-        query = body.get("query", "")
-        algorithm = body.get("algorithm", "hybrid")
-        fusion = body.get("fusion", "rrf")
-        score_threshold = body.get("score_threshold", 0.0)
-        limit = min(body.get("limit", 10), 50)  # Enforce max limit
-        include_pca = body.get("include_pca", True)
-        doc_types = body.get("doc_types")  # Optional list of document types
-
-        if not query:
-            return JSONResponse(
-                {"error": "Missing required parameter: query"},
-                status_code=400,
-            )
-
-        # Validate algorithm
-        valid_algorithms = {"semantic", "bm25", "hybrid"}
-        if algorithm not in valid_algorithms:
-            algorithm = "hybrid"
-
-        # Validate fusion method
-        valid_fusions = {"rrf", "dbsf"}
-        if fusion not in valid_fusions:
-            fusion = "rrf"
-
-        # Execute search using the appropriate algorithm
-        from nextcloud_mcp_server.search import (
-            BM25HybridSearchAlgorithm,
-            SemanticSearchAlgorithm,
-        )
-
-        # Select search algorithm
-        if algorithm == "semantic":
-            search_algo = SemanticSearchAlgorithm(score_threshold=score_threshold)
-        else:
-            # Both "hybrid" and "bm25" use the BM25HybridSearchAlgorithm
-            # which combines dense semantic and sparse BM25 vectors
-            search_algo = BM25HybridSearchAlgorithm(
-                score_threshold=score_threshold, fusion=fusion
-            )
-
-        # Execute search for each doc_type if specified, otherwise search all
-        all_results = []
-        if doc_types and isinstance(doc_types, list):
-            # Search each doc_type separately and merge results
-            for doc_type in doc_types:
-                if doc_type:  # Skip empty strings
-                    results = await search_algo.search(
-                        query=query,
-                        user_id=user_id,
-                        limit=limit,
-                        doc_type=doc_type,
-                    )
-                    all_results.extend(results)
-            # Sort merged results by score and limit
-            all_results.sort(key=lambda r: r.score, reverse=True)
-            all_results = all_results[:limit]
-        else:
-            # Search all document types
-            all_results = await search_algo.search(
-                query=query,
-                user_id=user_id,
-                limit=limit,
-            )
-
-        # Format results for PHP client
-        formatted_results = []
-        for result in all_results:
-            formatted_result = {
-                "id": result.id,
-                "doc_type": result.doc_type,
-                "title": result.title,
-                "excerpt": result.excerpt[:200] if result.excerpt else "",
-                "score": result.score,
-                "metadata": result.metadata,
-                # Chunk information for context display
-                "chunk_index": result.chunk_index,
-                "total_chunks": result.total_chunks,
-            }
-            # Include optional fields if present
-            if result.chunk_start_offset is not None:
-                formatted_result["chunk_start_offset"] = result.chunk_start_offset
-            if result.chunk_end_offset is not None:
-                formatted_result["chunk_end_offset"] = result.chunk_end_offset
-            if result.page_number is not None:
-                formatted_result["page_number"] = result.page_number
-            if result.page_count is not None:
-                formatted_result["page_count"] = result.page_count
-            formatted_results.append(formatted_result)
-
-        response_data: dict[str, Any] = {
-            "results": formatted_results,
-            "algorithm_used": algorithm,
-            "total_documents": len(formatted_results),
-        }
-
-        # Compute PCA coordinates for visualization using shared function
-        if include_pca and len(all_results) >= 2:
-            try:
-                from nextcloud_mcp_server.vector.visualization import (
-                    compute_pca_coordinates,
-                )
-
-                # Get query embedding from search algorithm or generate it
-                if search_algo.query_embedding is not None:
-                    query_embedding = search_algo.query_embedding
-                else:
-                    from nextcloud_mcp_server.embedding.service import (
-                        get_embedding_service,
-                    )
-
-                    embedding_service = get_embedding_service()
-                    query_embedding = await embedding_service.embed(query)
-
-                pca_data = await compute_pca_coordinates(all_results, query_embedding)
-                response_data["coordinates_3d"] = pca_data["coordinates_3d"]
-                response_data["query_coords"] = pca_data["query_coords"]
-                if "pca_variance" in pca_data:
-                    response_data["pca_variance"] = pca_data["pca_variance"]
-            except Exception as e:
-                logger.warning(f"Failed to compute PCA coordinates: {e}")
-                response_data["coordinates_3d"] = []
-                response_data["query_coords"] = []
-        elif include_pca:
-            # Not enough results for PCA
-            response_data["coordinates_3d"] = []
-            response_data["query_coords"] = []
-
-        return JSONResponse(response_data)
-
-    except Exception as e:
-        error_msg = _sanitize_error_for_client(e, "vector_search")
-        return JSONResponse(
-            {"error": error_msg},
-            status_code=500,
-        )
-
-
-async def get_chunk_context(request: Request) -> JSONResponse:
-    """GET /api/v1/chunk-context - Fetch chunk text with context.
-
-    Retrieves the matched chunk along with surrounding text and metadata.
-    Used by clients to display chunk context and highlighted PDFs.
-
-    Query parameters:
-        doc_type: Document type (e.g., "note")
-        doc_id: Document ID
-        start: Chunk start offset (character position)
-        end: Chunk end offset (character position)
-        context: Characters of context before/after (default: 500)
-
-    Requires OAuth bearer token for authentication.
-    """
-    try:
-        # Validate OAuth token and extract user
-        user_id, validated = await validate_token_and_get_user(request)
-    except Exception as e:
-        logger.warning(f"Unauthorized access to /api/v1/chunk-context: {e}")
-        return JSONResponse(
-            {
-                "error": "Unauthorized",
-                "message": _sanitize_error_for_client(e, "get_chunk_context"),
-            },
-            status_code=401,
-        )
-
-    try:
-        # Get query parameters
-        doc_type = request.query_params.get("doc_type")
-        doc_id = request.query_params.get("doc_id")
-        start_str = request.query_params.get("start")
-        end_str = request.query_params.get("end")
-
-        # Validate required parameters
-        if not all([doc_type, doc_id, start_str, end_str]):
-            return JSONResponse(
-                {
-                    "success": False,
-                    "error": "Missing required parameters: doc_type, doc_id, start, end",
-                },
-                status_code=400,
-            )
-
-        # Type narrowing: we already checked these are not None above
-        assert start_str is not None
-        assert end_str is not None
-        assert doc_id is not None
-        assert doc_type is not None
-
-        # Parse and validate integer parameters with bounds checking
-        try:
-            context_chars = _parse_int_param(
-                request.query_params.get("context"),
-                500,
-                0,
-                10000,
-                "context_chars",
-            )
-            start = _parse_int_param(start_str, 0, 0, 10000000, "start")
-            end = _parse_int_param(end_str, 0, 0, 10000000, "end")
-            if end <= start:
-                raise ValueError("end must be greater than start")
-        except ValueError as e:
-            return JSONResponse({"success": False, "error": str(e)}, status_code=400)
-        # Convert doc_id to int if possible (most IDs are int)
-        doc_id_val: str | int = int(doc_id) if doc_id.isdigit() else doc_id
-
-        # Get bearer token for client initialization
-        token = extract_bearer_token(request)
-        if not token:
-            raise ValueError("Missing token")
-
-        # Get Nextcloud host from OAuth context
-        oauth_ctx = request.app.state.oauth_context
-        nextcloud_host = oauth_ctx.get("config", {}).get("nextcloud_host", "")
-
-        if not nextcloud_host:
-            raise ValueError("Nextcloud host not configured")
-
-        # Initialize authenticated Nextcloud client
-        from nextcloud_mcp_server.client import NextcloudClient
-        from nextcloud_mcp_server.search.context import get_chunk_with_context
-
-        async with NextcloudClient.from_token(
-            base_url=nextcloud_host, token=token, username=user_id
-        ) as nc_client:
-            chunk_context = await get_chunk_with_context(
-                nc_client=nc_client,
-                user_id=user_id,
-                doc_id=doc_id_val,
-                doc_type=doc_type,
-                chunk_start=start,
-                chunk_end=end,
-                context_chars=context_chars,
-            )
-
-        if chunk_context is None:
-            return JSONResponse(
-                {
-                    "success": False,
-                    "error": f"Failed to fetch chunk context for {doc_type} {doc_id}",
-                },
-                status_code=404,
-            )
-
-        # For PDF files, also fetch the highlighted page image from Qdrant if available
-        # This is useful for clients that want to show a pre-rendered image
-        highlighted_page_image = None
-        page_number = chunk_context.page_number
-
-        if doc_type == "file":
-            try:
-                from qdrant_client.models import FieldCondition, Filter, MatchValue
-
-                from nextcloud_mcp_server.config import get_settings
-                from nextcloud_mcp_server.vector.placeholder import (
-                    get_placeholder_filter,
-                )
-                from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
-
-                settings = get_settings()
-                qdrant_client = await get_qdrant_client()
-
-                # Query for this specific chunk's highlighted image
-                points_response = await qdrant_client.scroll(
-                    collection_name=settings.get_collection_name(),
-                    scroll_filter=Filter(
-                        must=[
-                            get_placeholder_filter(),
-                            FieldCondition(
-                                key="doc_id", match=MatchValue(value=doc_id_val)
-                            ),
-                            FieldCondition(
-                                key="user_id", match=MatchValue(value=user_id)
-                            ),
-                            FieldCondition(
-                                key="chunk_start_offset", match=MatchValue(value=start)
-                            ),
-                            FieldCondition(
-                                key="chunk_end_offset", match=MatchValue(value=end)
-                            ),
-                        ]
-                    ),
-                    limit=1,
-                    with_vectors=False,
-                    with_payload=["highlighted_page_image", "page_number"],
-                )
-
-                if points_response[0]:
-                    payload = points_response[0][0].payload
-                    if payload:
-                        highlighted_page_image = payload.get("highlighted_page_image")
-                        # Trust Qdrant page number if available (might be more accurate than context expansion logic)
-                        if payload.get("page_number") is not None:
-                            page_number = payload.get("page_number")
-
-            except Exception as e:
-                logger.warning(f"Failed to fetch highlighted image: {e}")
-
-        # Build response
-        response_data = {
-            "success": True,
-            "chunk_text": chunk_context.chunk_text,
-            "before_context": chunk_context.before_context,
-            "after_context": chunk_context.after_context,
-            "has_more_before": chunk_context.has_before_truncation,
-            "has_more_after": chunk_context.has_after_truncation,
-            "page_number": page_number,
-            "chunk_index": chunk_context.chunk_index,
-            "total_chunks": chunk_context.total_chunks,
-        }
-
-        if highlighted_page_image:
-            response_data["highlighted_page_image"] = highlighted_page_image
-
-        return JSONResponse(response_data)
-
-    except Exception as e:
-        error_msg = _sanitize_error_for_client(e, "get_chunk_context")
-        return JSONResponse(
-            {"error": error_msg},
-            status_code=500,
-        )
-
-
-async def get_pdf_preview(request: Request) -> JSONResponse:
-    """GET /api/v1/pdf-preview - Render PDF page to PNG image.
-
-    Server-side PDF rendering using PyMuPDF. This endpoint allows Astrolabe
-    to display PDF pages without requiring client-side PDF.js, avoiding CSP
-    worker restrictions and ES private field issues in Chromium.
-
-    Query parameters:
-        file_path: WebDAV path to PDF file (e.g., "/Documents/report.pdf")
-        page: Page number (1-indexed, default: 1)
-        scale: Zoom factor for rendering (default: 2.0 = 144 DPI)
-
-    Returns:
-        {
-            "success": true,
-            "image": "<base64-encoded-png>",
-            "page_number": 1,
-            "total_pages": 10
-        }
-
-    Requires OAuth bearer token for authentication.
-    """
-    # Log incoming request
-    file_path_param = request.query_params.get("file_path", "<not provided>")
-    page_param = request.query_params.get("page", "1")
-    logger.info(f"PDF preview request: file_path={file_path_param}, page={page_param}")
-
-    try:
-        # Validate OAuth token and extract user
-        user_id, validated = await validate_token_and_get_user(request)
-        logger.info(f"PDF preview authenticated for user: {user_id}")
-    except Exception as e:
-        logger.warning(f"Unauthorized access to /api/v1/pdf-preview: {e}")
-        return JSONResponse(
-            {
-                "success": False,
-                "error": "Unauthorized",
-                "message": _sanitize_error_for_client(e, "get_pdf_preview"),
-            },
-            status_code=401,
-        )
-
-    try:
-        # Parse and validate parameters
-        file_path = request.query_params.get("file_path")
-        if not file_path:
-            return JSONResponse(
-                {"success": False, "error": "Missing required parameter: file_path"},
-                status_code=400,
-            )
-
-        # Validate no path traversal sequences
-        if ".." in file_path:
-            return JSONResponse(
-                {"success": False, "error": "Invalid file path"},
-                status_code=400,
-            )
-
-        try:
-            page_num = _parse_int_param(
-                request.query_params.get("page"), 1, 1, 10000, "page"
-            )
-            scale = _parse_float_param(
-                request.query_params.get("scale"), 2.0, 0.5, 5.0, "scale"
-            )
-        except ValueError as e:
-            return JSONResponse({"success": False, "error": str(e)}, status_code=400)
-
-        # Get bearer token for WebDAV authentication
-        token = extract_bearer_token(request)
-        if not token:
-            raise ValueError("Missing token")
-
-        # Get Nextcloud host from OAuth context
-        oauth_ctx = request.app.state.oauth_context
-        nextcloud_host = oauth_ctx.get("config", {}).get("nextcloud_host", "")
-
-        if not nextcloud_host:
-            raise ValueError("Nextcloud host not configured")
-
-        # Download PDF via WebDAV using user's token
-        from nextcloud_mcp_server.client import NextcloudClient
-
-        async with NextcloudClient.from_token(
-            base_url=nextcloud_host, token=token, username=user_id
-        ) as nc_client:
-            pdf_bytes, _ = await nc_client.webdav.read_file(file_path)
-
-        # Check file size limit (50 MB)
-        max_pdf_size = 50 * 1024 * 1024
-        if len(pdf_bytes) > max_pdf_size:
-            return JSONResponse(
-                {
-                    "success": False,
-                    "error": f"PDF file exceeds maximum size limit ({max_pdf_size // (1024 * 1024)} MB)",
-                },
-                status_code=413,
-            )
-
-        # Render page with PyMuPDF
-        doc = pymupdf.open(stream=pdf_bytes, filetype="pdf")
-        try:
-            total_pages = doc.page_count
-
-            # Validate page number
-            if page_num > total_pages:
-                return JSONResponse(
-                    {
-                        "success": False,
-                        "error": f"Page {page_num} does not exist (document has {total_pages} pages)",
-                    },
-                    status_code=400,
-                )
-
-            page = doc[page_num - 1]  # 0-indexed
-            mat = pymupdf.Matrix(scale, scale)
-            pix = page.get_pixmap(matrix=mat, alpha=False)
-            png_bytes = pix.tobytes("png")
-        finally:
-            doc.close()
-
-        # Encode as base64
-        image_b64 = base64.b64encode(png_bytes).decode("ascii")
-
-        logger.info(
-            f"Rendered PDF preview: {file_path} page {page_num}/{total_pages}, "
-            f"{len(png_bytes):,} bytes"
-        )
-
-        return JSONResponse(
-            {
-                "success": True,
-                "image": image_b64,
-                "page_number": page_num,
-                "total_pages": total_pages,
-            }
-        )
-
-    except FileNotFoundError:
-        logger.warning(f"PDF file not found: {file_path_param}")
-        return JSONResponse(
-            {"success": False, "error": "PDF file not found"},
-            status_code=404,
-        )
-    except (pymupdf.FileDataError, pymupdf.EmptyFileError):
-        logger.warning(f"Invalid or corrupted PDF file: {file_path_param}")
-        return JSONResponse(
-            {"success": False, "error": "Invalid or corrupted PDF file"},
-            status_code=400,
-        )
-    except Exception as e:
-        logger.error(f"PDF preview error: {e}", exc_info=True)
-        error_msg = _sanitize_error_for_client(e, "get_pdf_preview")
-        return JSONResponse(
-            {"success": False, "error": error_msg},
-            status_code=500,
-        )
@@ -1,308 +0,0 @@
-"""Webhook management API endpoints.
-
-Provides REST API endpoints for managing webhook registrations with Nextcloud.
-These endpoints are used by the Nextcloud PHP app (Astrolabe) to:
- List installed Nextcloud apps
- Create, list, and delete webhook registrations
-
-All endpoints require OAuth bearer token authentication via UnifiedTokenVerifier.
-"""
-
-import logging
-
-import httpx
-from starlette.requests import Request
-from starlette.responses import JSONResponse
-
-from nextcloud_mcp_server.api.management import (
-    _sanitize_error_for_client,
-    extract_bearer_token,
-    validate_token_and_get_user,
-)
-
-logger = logging.getLogger(__name__)
-
-
-async def get_installed_apps(request: Request) -> JSONResponse:
-    """GET /api/v1/apps - Get list of installed Nextcloud apps.
-
-    Returns a list of installed app IDs for filtering webhook presets.
-
-    Requires OAuth bearer token for authentication.
-    """
-    try:
-        # Validate OAuth token and extract user
-        user_id, validated = await validate_token_and_get_user(request)
-    except Exception as e:
-        logger.warning(f"Unauthorized access to /api/v1/apps: {e}")
-        return JSONResponse(
-            {
-                "error": "Unauthorized",
-                "message": _sanitize_error_for_client(e, "get_installed_apps"),
-            },
-            status_code=401,
-        )
-
-    try:
-        # Get Bearer token from request
-        token = extract_bearer_token(request)
-        if not token:
-            raise ValueError("Missing Authorization header")
-
-        # Get Nextcloud host from OAuth context
-        oauth_ctx = request.app.state.oauth_context
-        nextcloud_host = oauth_ctx.get("config", {}).get("nextcloud_host", "")
-
-        if not nextcloud_host:
-            raise ValueError("Nextcloud host not configured")
-
-        # Create authenticated HTTP client
-        async with httpx.AsyncClient(
-            base_url=nextcloud_host,
-            headers={"Authorization": f"Bearer {token}"},
-            timeout=30.0,
-        ) as client:
-            # Get installed apps using OCS API
-            # Notes, Calendar, Deck, Tables, etc. are apps that support webhooks
-            # We check which ones are installed and enabled
-            ocs_url = "/ocs/v1.php/cloud/apps"
-            params = {"filter": "enabled"}
-
-            response = await client.get(
-                ocs_url,
-                params=params,
-                headers={"OCS-APIRequest": "true", "Accept": "application/json"},
-            )
-
-            if response.status_code != 200:
-                raise ValueError(f"OCS API returned status {response.status_code}")
-
-            data = response.json()
-            apps = data.get("ocs", {}).get("data", {}).get("apps", [])
-
-            return JSONResponse({"apps": apps})
-
-    except Exception as e:
-        logger.error(f"Error getting installed apps for user {user_id}: {e}")
-        return JSONResponse(
-            {
-                "error": "Internal error",
-                "message": _sanitize_error_for_client(e, "get_installed_apps"),
-            },
-            status_code=500,
-        )
-
-
-async def list_webhooks(request: Request) -> JSONResponse:
-    """GET /api/v1/webhooks - List all registered webhooks.
-
-    Returns list of webhook registrations for the authenticated user.
-
-    Requires OAuth bearer token for authentication.
-    """
-    try:
-        # Validate OAuth token and extract user
-        user_id, validated = await validate_token_and_get_user(request)
-    except Exception as e:
-        logger.warning(f"Unauthorized access to /api/v1/webhooks: {e}")
-        return JSONResponse(
-            {
-                "error": "Unauthorized",
-                "message": _sanitize_error_for_client(e, "list_webhooks"),
-            },
-            status_code=401,
-        )
-
-    try:
-        from nextcloud_mcp_server.client.webhooks import WebhooksClient
-
-        # Get Bearer token from request
-        token = extract_bearer_token(request)
-        if not token:
-            raise ValueError("Missing Authorization header")
-
-        # Get Nextcloud host from OAuth context
-        oauth_ctx = request.app.state.oauth_context
-        nextcloud_host = oauth_ctx.get("config", {}).get("nextcloud_host", "")
-
-        if not nextcloud_host:
-            raise ValueError("Nextcloud host not configured")
-
-        # Create authenticated HTTP client
-        async with httpx.AsyncClient(
-            base_url=nextcloud_host,
-            headers={"Authorization": f"Bearer {token}"},
-            timeout=30.0,
-        ) as client:
-            # Use WebhooksClient to list webhooks
-            webhooks_client = WebhooksClient(client, user_id)
-            webhooks = await webhooks_client.list_webhooks()
-
-            return JSONResponse({"webhooks": webhooks})
-
-    except Exception as e:
-        logger.error(f"Error listing webhooks for user {user_id}: {e}")
-        return JSONResponse(
-            {
-                "error": "Internal error",
-                "message": _sanitize_error_for_client(e, "list_webhooks"),
-            },
-            status_code=500,
-        )
-
-
-async def create_webhook(request: Request) -> JSONResponse:
-    """POST /api/v1/webhooks - Create a new webhook registration.
-
-    Request body:
-    {
-        "event": "OCP\\Files\\Events\\Node\\NodeCreatedEvent",
-        "uri": "http://mcp:8000/webhooks/nextcloud",
-        "eventFilter": {"event.node.path": "/^\\/.*\\/files\\/Notes\\//"}
-    }
-
-    Returns the created webhook data including the webhook ID.
-
-    Requires OAuth bearer token for authentication.
-    """
-    try:
-        # Validate OAuth token and extract user
-        user_id, validated = await validate_token_and_get_user(request)
-    except Exception as e:
-        logger.warning(f"Unauthorized access to /api/v1/webhooks: {e}")
-        return JSONResponse(
-            {
-                "error": "Unauthorized",
-                "message": _sanitize_error_for_client(e, "create_webhook"),
-            },
-            status_code=401,
-        )
-
-    try:
-        from nextcloud_mcp_server.client.webhooks import WebhooksClient
-
-        # Parse request body
-        body = await request.json()
-        event = body.get("event")
-        uri = body.get("uri")
-        # Accept both camelCase (eventFilter) and snake_case (event_filter)
-        event_filter = body.get("eventFilter") or body.get("event_filter")
-
-        if not event or not uri:
-            return JSONResponse(
-                {
-                    "error": "Bad request",
-                    "message": "Missing required fields: event, uri",
-                },
-                status_code=400,
-            )
-
-        # Get Bearer token from request
-        token = extract_bearer_token(request)
-        if not token:
-            raise ValueError("Missing Authorization header")
-
-        # Get Nextcloud host from OAuth context
-        oauth_ctx = request.app.state.oauth_context
-        nextcloud_host = oauth_ctx.get("config", {}).get("nextcloud_host", "")
-
-        if not nextcloud_host:
-            raise ValueError("Nextcloud host not configured")
-
-        # Create authenticated HTTP client
-        async with httpx.AsyncClient(
-            base_url=nextcloud_host,
-            headers={"Authorization": f"Bearer {token}"},
-            timeout=30.0,
-        ) as client:
-            # Use WebhooksClient to create webhook
-            webhooks_client = WebhooksClient(client, user_id)
-            webhook_data = await webhooks_client.create_webhook(
-                event=event, uri=uri, event_filter=event_filter
-            )
-
-            return JSONResponse({"webhook": webhook_data})
-
-    except Exception as e:
-        logger.error(f"Error creating webhook for user {user_id}: {e}")
-        return JSONResponse(
-            {
-                "error": "Internal error",
-                "message": _sanitize_error_for_client(e, "create_webhook"),
-            },
-            status_code=500,
-        )
-
-
-async def delete_webhook(request: Request) -> JSONResponse:
-    """DELETE /api/v1/webhooks/{webhook_id} - Delete a webhook registration.
-
-    Returns success/failure status.
-
-    Requires OAuth bearer token for authentication.
-    """
-    try:
-        # Validate OAuth token and extract user
-        user_id, validated = await validate_token_and_get_user(request)
-    except Exception as e:
-        logger.warning(f"Unauthorized access to /api/v1/webhooks: {e}")
-        return JSONResponse(
-            {
-                "error": "Unauthorized",
-                "message": _sanitize_error_for_client(e, "delete_webhook"),
-            },
-            status_code=401,
-        )
-
-    try:
-        from nextcloud_mcp_server.client.webhooks import WebhooksClient
-
-        # Get webhook_id from path parameter
-        webhook_id = request.path_params.get("webhook_id")
-        if not webhook_id:
-            return JSONResponse(
-                {"error": "Bad request", "message": "Missing webhook_id"},
-                status_code=400,
-            )
-
-        try:
-            webhook_id = int(webhook_id)
-        except ValueError:
-            return JSONResponse(
-                {"error": "Bad request", "message": "Invalid webhook_id"},
-                status_code=400,
-            )
-
-        # Get Bearer token from request
-        token = extract_bearer_token(request)
-        if not token:
-            raise ValueError("Missing Authorization header")
-
-        # Get Nextcloud host from OAuth context
-        oauth_ctx = request.app.state.oauth_context
-        nextcloud_host = oauth_ctx.get("config", {}).get("nextcloud_host", "")
-
-        if not nextcloud_host:
-            raise ValueError("Nextcloud host not configured")
-
-        # Create authenticated HTTP client
-        async with httpx.AsyncClient(
-            base_url=nextcloud_host,
-            headers={"Authorization": f"Bearer {token}"},
-            timeout=30.0,
-        ) as client:
-            # Use WebhooksClient to delete webhook
-            webhooks_client = WebhooksClient(client, user_id)
-            await webhooks_client.delete_webhook(webhook_id=webhook_id)
-
-            return JSONResponse({"success": True, "message": "Webhook deleted"})
-
-    except Exception as e:
-        logger.error(f"Error deleting webhook for user {user_id}: {e}")
-        return JSONResponse(
-            {
-                "error": "Internal error",
-                "message": _sanitize_error_for_client(e, "delete_webhook"),
-            },
-            status_code=500,
-        )
@@ -1,152 +0,0 @@
-"""
-Client for querying Astrolabe Management API for background sync credentials.
-
-This client uses OAuth client credentials flow to authenticate to Nextcloud
-and retrieve user app passwords for background sync operations.
-"""
-
-import logging
-import time
-from typing import Optional
-
-import httpx
-
-logger = logging.getLogger(__name__)
-
-
-class AstrolabeClient:
-    """Client for querying Astrolabe API for background sync credentials.
-
-    Uses OAuth client credentials flow to authenticate as the MCP server
-    and retrieve user app passwords that are stored in Nextcloud.
-    """
-
-    def __init__(
-        self,
-        nextcloud_host: str,
-        client_id: str,
-        client_secret: str,
-    ):
-        """
-        Initialize Astrolabe client.
-
-        Args:
-            nextcloud_host: Nextcloud base URL (e.g., https://cloud.example.com)
-            client_id: OAuth client ID for MCP server
-            client_secret: OAuth client secret
-        """
-        self.nextcloud_host = nextcloud_host.rstrip("/")
-        self.client_id = client_id
-        self.client_secret = client_secret
-        self._token_cache: Optional[dict] = None  # {access_token, expires_at}
-
-    async def get_access_token(self) -> str:
-        """
-        Get access token using OAuth client credentials flow.
-
-        Tokens are cached with 1-minute early refresh to avoid expiration.
-
-        Returns:
-            Access token string
-
-        Raises:
-            httpx.HTTPError: If token request fails
-        """
-        # Check cache
-        if self._token_cache and time.time() < self._token_cache["expires_at"]:
-            logger.debug("Using cached OAuth token for Astrolabe API")
-            return self._token_cache["access_token"]
-
-        # Discover token endpoint
-        discovery_url = f"{self.nextcloud_host}/.well-known/openid-configuration"
-
-        async with httpx.AsyncClient() as client:
-            logger.debug(f"Discovering token endpoint from {discovery_url}")
-            discovery_resp = await client.get(discovery_url)
-            discovery_resp.raise_for_status()
-            token_endpoint = discovery_resp.json()["token_endpoint"]
-
-            logger.debug(f"Requesting client credentials token from {token_endpoint}")
-
-            # Request token using client credentials grant
-            token_resp = await client.post(
-                token_endpoint,
-                data={
-                    "grant_type": "client_credentials",
-                    "client_id": self.client_id,
-                    "client_secret": self.client_secret,
-                    "scope": "openid",  # Minimal scope
-                },
-            )
-            token_resp.raise_for_status()
-            data = token_resp.json()
-
-            # Cache with 1-minute early refresh
-            expires_in = data.get("expires_in", 3600)
-            self._token_cache = {
-                "access_token": data["access_token"],
-                "expires_at": time.time() + expires_in - 60,
-            }
-
-            logger.info(f"Obtained Astrolabe API token (expires in {expires_in}s)")
-            return data["access_token"]
-
-    async def get_user_app_password(self, user_id: str) -> Optional[str]:
-        """
-        Retrieve user's app password for background sync.
-
-        Args:
-            user_id: Nextcloud user ID
-
-        Returns:
-            App password string, or None if user hasn't provisioned
-
-        Raises:
-            httpx.HTTPError: If API request fails (except 404)
-        """
-        token = await self.get_access_token()
-        url = f"{self.nextcloud_host}/apps/astrolabe/api/v1/background-sync/credentials/{user_id}"
-
-        async with httpx.AsyncClient() as client:
-            logger.debug(f"Retrieving app password for user: {user_id}")
-
-            response = await client.get(
-                url,
-                headers={"Authorization": f"Bearer {token}"},
-                timeout=10.0,
-            )
-
-            if response.status_code == 404:
-                logger.debug(f"No app password configured for user: {user_id}")
-                return None
-
-            response.raise_for_status()
-            data = response.json()
-
-            logger.info(
-                f"Retrieved app password for user: {user_id} (type: {data.get('credential_type')})"
-            )
-            return data.get("app_password")
-
-    async def get_background_sync_status(self, user_id: str) -> dict:
-        """
-        Get background sync status for a user.
-
-        Args:
-            user_id: Nextcloud user ID
-
-        Returns:
-            Dict with keys: has_access, credential_type, provisioned_at
-
-        Raises:
-            httpx.HTTPError: If API request fails
-        """
-        # For now, check if app password exists
-        # In the future, this could query a dedicated status endpoint
-        app_password = await self.get_user_app_password(user_id)
-
-        return {
-            "has_access": app_password is not None,
-            "credential_type": "app_password" if app_password else None,
-            "provisioned_at": None,  # TODO: Get from API if available
-        }
@@ -8,7 +8,6 @@ import hashlib
 import logging
 import os
 import secrets
-import time
 from base64 import urlsafe_b64encode
 from urllib.parse import urlencode

@@ -25,26 +24,6 @@ from nextcloud_mcp_server.auth.userinfo_routes import (
 logger = logging.getLogger(__name__)


-def _should_use_secure_cookies() -> bool:
-    """Determine if cookies should have secure flag.
-
-    Checks COOKIE_SECURE env var first, then auto-detects from NEXTCLOUD_HOST.
-
-    Returns:
-        True if cookies should be secure (HTTPS), False otherwise
-    """
-    # Explicit configuration takes precedence
-    explicit = os.getenv("COOKIE_SECURE", "").lower()
-    if explicit == "true":
-        return True
-    if explicit == "false":
-        return False
-
-    # Auto-detect from NEXTCLOUD_HOST protocol
-    nextcloud_host = os.getenv("NEXTCLOUD_HOST", "")
-    return nextcloud_host.startswith("https://")
-
-
 async def oauth_login(request: Request) -> RedirectResponse | JSONResponse:
    """Browser OAuth login endpoint - redirects to IdP for authentication.

@@ -71,10 +50,6 @@ async def oauth_login(request: Request) -> RedirectResponse | JSONResponse:
    logger.info(f"oauth_login called - client_id: {oauth_config.get('client_id')}")
    logger.info(f"oauth_login called - oauth_client: {oauth_client is not None}")

-    # Get redirect URL from query params (default to /app)
-    next_url = request.query_params.get("next", "/app")
-    logger.info(f"oauth_login - next_url: {next_url}")
-
    # Generate state for CSRF protection
    state = secrets.token_urlsafe(32)

@@ -96,7 +71,7 @@ async def oauth_login(request: Request) -> RedirectResponse | JSONResponse:
    await storage.store_oauth_session(
        session_id=state,  # Use state as session ID
        client_id="browser-ui",
-        client_redirect_uri=next_url,  # Store the redirect URL for after auth
+        client_redirect_uri="/app",
        state=state,
        code_challenge=code_challenge,
        code_challenge_method="S256",
@@ -110,11 +85,6 @@ async def oauth_login(request: Request) -> RedirectResponse | JSONResponse:
        if not oauth_client.authorization_endpoint:
            await oauth_client.discover()

-        # Get Nextcloud resource URI for audience (background sync needs Nextcloud-scoped tokens)
-        nextcloud_resource_uri = oauth_config.get(
-            "nextcloud_resource_uri", oauth_config.get("nextcloud_host")
-        )
-
        idp_params = {
            "client_id": oauth_client.client_id,
            "redirect_uri": callback_uri,
@@ -124,7 +94,6 @@ async def oauth_login(request: Request) -> RedirectResponse | JSONResponse:
            "code_challenge": code_challenge,
            "code_challenge_method": "S256",
            "prompt": "consent",  # Ensure refresh token
-            "resource": nextcloud_resource_uri,  # Request tokens for Nextcloud API access
        }

        auth_url = f"{oauth_client.authorization_endpoint}?{urlencode(idp_params)}"
@@ -162,11 +131,6 @@ async def oauth_login(request: Request) -> RedirectResponse | JSONResponse:
                    f"{public_parsed.scheme}://{public_parsed.netloc}{auth_parsed.path}"
                )

-        # Get Nextcloud resource URI for audience (background sync needs Nextcloud-scoped tokens)
-        nextcloud_resource_uri = oauth_config.get(
-            "nextcloud_resource_uri", oauth_config.get("nextcloud_host")
-        )
-
        idp_params = {
            "client_id": oauth_config["client_id"],
            "redirect_uri": callback_uri,
@@ -176,7 +140,6 @@ async def oauth_login(request: Request) -> RedirectResponse | JSONResponse:
            "code_challenge": code_challenge,
            "code_challenge_method": "S256",
            "prompt": "consent",  # Ensure refresh token
-            "resource": nextcloud_resource_uri,  # Request tokens for Nextcloud API access
        }

        # Debug: Log full parameters
@@ -251,15 +214,12 @@ async def oauth_login_callback(request: Request) -> RedirectResponse | HTMLRespo
    oauth_client = oauth_ctx["oauth_client"]
    oauth_config = oauth_ctx["config"]

-    # Retrieve code_verifier and redirect URL from session storage
+    # Retrieve code_verifier from session storage (PKCE required for all modes)
    code_verifier = ""
-    next_url = "/app"  # Default redirect
    oauth_session = await storage.get_oauth_session(state)
    if oauth_session:
        # code_verifier was stored in mcp_authorization_code field
        code_verifier = oauth_session.get("mcp_authorization_code", "")
-        # next_url was stored in client_redirect_uri field
-        next_url = oauth_session.get("client_redirect_uri", "/app")
        # Clean up the temporary session
        # Note: We don't have delete_oauth_session method, but it will expire after TTL

@@ -378,33 +338,16 @@ async def oauth_login_callback(request: Request) -> RedirectResponse | HTMLRespo
        user_id = f"user-{secrets.token_hex(8)}"
        username = "unknown"

-    # Calculate refresh token expiration from token response
-    refresh_expires_in = token_data.get("refresh_expires_in")
-    refresh_expires_at = None
-    if refresh_expires_in:
-        refresh_expires_at = int(time.time()) + refresh_expires_in
-        logger.info(
-            f"Refresh token expires in {refresh_expires_in}s (at timestamp {refresh_expires_at})"
-        )
-
-    # Extract granted scopes
-    granted_scopes = (
-        token_data.get("scope", "").split() if token_data.get("scope") else None
-    )
-
    # Store refresh token (for background jobs ONLY)
    if refresh_token:
        logger.info(f"Storing refresh token for user_id: {user_id}")
        logger.info(f"  State parameter (provisioning_client_id): {state[:16]}...")
-        logger.info(f"  Granted scopes: {granted_scopes}")
-        logger.info(f"  Expires at: {refresh_expires_at}")
        await storage.store_refresh_token(
            user_id=user_id,
            refresh_token=refresh_token,
-            expires_at=refresh_expires_at,
+            expires_at=None,
            flow_type="browser",  # Browser-based login flow
            provisioning_client_id=state,  # Store state for unified session lookup
-            scopes=granted_scopes,
        )
        logger.info(f"✓ Refresh token stored successfully for user_id: {user_id}")
        logger.info(
@@ -440,14 +383,13 @@ async def oauth_login_callback(request: Request) -> RedirectResponse | HTMLRespo
            # Continue anyway - profile cache is optional for browser UI

    # Create response and set session cookie
-    # Redirect to stored next_url (from OAuth session) or /app as default
-    response = RedirectResponse(next_url, status_code=302)
+    response = RedirectResponse("/app", status_code=302)
    response.set_cookie(
        key="mcp_session",
        value=user_id,
        max_age=86400 * 30,  # 30 days
        httponly=True,
-        secure=_should_use_secure_cookies(),
+        secure=False,  # Set to True in production with HTTPS
        samesite="lax",
    )

@@ -8,7 +8,6 @@ Handles OAuth flows with Keycloak as the identity provider, including:
 - Integration with RefreshTokenStorage
 """

-import base64
 import hashlib
 import logging
 import os
@@ -156,6 +155,7 @@ class KeycloakOAuthClient:
        Returns:
            Tuple of (code_verifier, code_challenge)
        """
+        import base64

        # Generate code verifier (43-128 characters)
        code_verifier = secrets.token_urlsafe(32)
@@ -23,7 +23,6 @@ import hashlib
 import logging
 import os
 import secrets
-import time
 from base64 import urlsafe_b64encode
 from urllib.parse import urlencode

@@ -518,21 +517,12 @@ async def oauth_callback_nextcloud(request: Request):
            token_data.get("scope", "").split() if token_data.get("scope") else None
        )

-        # Calculate refresh token expiration from token response
-        refresh_expires_in = token_data.get("refresh_expires_in")
-        refresh_expires_at = None
-        if refresh_expires_in:
-            refresh_expires_at = int(time.time()) + refresh_expires_in
-            logger.info(f"  refresh_expires_in: {refresh_expires_in}s")
-            logger.info(f"  refresh_expires_at: {refresh_expires_at}")
-
        logger.info("Storing refresh token:")
        logger.info(f"  user_id: {user_id}")
        logger.info("  flow_type: flow2")
        logger.info("  token_audience: nextcloud")
        logger.info(f"  provisioning_client_id: {state[:16]}...")
        logger.info(f"  scopes: {granted_scopes}")
-        logger.info(f"  expires_at: {refresh_expires_at}")

        await storage.store_refresh_token(
            user_id=user_id,
@@ -541,7 +531,7 @@ async def oauth_callback_nextcloud(request: Request):
            token_audience="nextcloud",
            provisioning_client_id=state,  # Store which client initiated provisioning
            scopes=granted_scopes,
-            expires_at=refresh_expires_at,
+            expires_at=None,  # Refresh tokens typically don't expire
        )
        logger.info(f"✓ Stored Flow 2 master refresh token for user {user_id}")
        logger.info("=" * 60)
@@ -9,7 +9,6 @@ import functools
 import logging
 from typing import Callable

-import jwt
 from mcp.server.fastmcp import Context
 from mcp.shared.exceptions import McpError
 from mcp.types import ErrorData
@@ -79,6 +78,8 @@ def require_provisioning(func: Callable) -> Callable:
        user_id = None
        if hasattr(ctx, "authorization") and ctx.authorization:
            try:
+                import jwt
+
                token = ctx.authorization.token
                payload = jwt.decode(token, options={"verify_signature": False})
                user_id = payload.get("sub")
@@ -162,6 +163,8 @@ def require_provisioning_or_suggest(func: Callable) -> Callable:
                # Get user_id from authorization token
                user_id = None
                if hasattr(ctx, "authorization") and ctx.authorization:
+                    import jwt
+
                    token = ctx.authorization.token
                    payload = jwt.decode(token, options={"verify_signature": False})
                    user_id = payload.get("sub")
@@ -1,6 +1,7 @@
 """Scope-based authorization for MCP tools."""

 import logging
+import os
 from functools import wraps
 from typing import Any, Callable

@@ -130,12 +131,9 @@ def require_scopes(*required_scopes: str):
            required_scopes_set = set(required_scopes)

            # Check if offline access is enabled
-            # Use settings.enable_offline_access which handles both ENABLE_BACKGROUND_OPERATIONS (new)
-            # and ENABLE_OFFLINE_ACCESS (deprecated) environment variables
-            from nextcloud_mcp_server.config import get_settings
-
-            settings = get_settings()
-            enable_offline_access = settings.enable_offline_access
+            enable_offline_access = (
+                os.getenv("ENABLE_OFFLINE_ACCESS", "false").lower() == "true"
+            )

            # In offline access mode, check if Nextcloud scopes require provisioning
            if enable_offline_access:
@@ -1,219 +0,0 @@
-.viz-layout {
-    display: flex;
-    flex-direction: column;
-    gap: 16px;
-    height: 100%;
-    min-height: 0;
-    overflow-y: auto;
-}
-.viz-card {
-    background: var(--color-main-background);
-    border-radius: 0;
-    padding: 16px;
-    box-shadow: none;
-}
-.viz-controls-card {
-    flex: 0 0 auto;
-    border-bottom: 1px solid var(--color-border);
-    padding-bottom: 16px;
-}
-.viz-controls-grid {
-    display: grid;
-    grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
-    gap: 12px;
-    align-items: end;
-}
-@media (min-width: 768px) {
-    .viz-controls-grid {
-        grid-template-columns: 2fr 1.5fr 1.5fr auto auto;
-    }
-}
-.viz-control-group {
-    display: flex;
-    flex-direction: column;
-    gap: 4px;
-}
-.viz-control-group label {
-    font-weight: 500;
-    color: var(--color-main-text);
-    font-size: 13px;
-}
-.viz-control-group input[type="text"],
-.viz-control-group input[type="number"],
-.viz-control-group select {
-    width: 100%;
-    padding: 7px 10px;
-    border: 1px solid var(--color-border-dark);
-    border-radius: var(--border-radius);
-    font-size: 14px;
-    background: var(--color-main-background);
-    color: var(--color-main-text);
-}
-.viz-control-group input:focus,
-.viz-control-group select:focus {
-    outline: none;
-    border-color: var(--color-primary-element);
-}
-.viz-control-group input[type="range"] {
-    width: 100%;
-}
-.viz-control-group select[multiple] {
-    min-height: 100px;
-}
-.viz-weight-display {
-    display: inline-block;
-    min-width: 40px;
-    text-align: right;
-    color: #666;
-}
-.viz-btn {
-    background: var(--color-primary-element);
-    color: white;
-    border: none;
-    padding: 7px 16px;
-    border-radius: var(--border-radius);
-    cursor: pointer;
-    font-size: 14px;
-    font-weight: 500;
-    white-space: nowrap;
-}
-.viz-btn:hover {
-    background: #0052a3;
-}
-.viz-btn-secondary {
-    background: #6c757d;
-    color: white;
-    border: none;
-    padding: 7px 16px;
-    border-radius: var(--border-radius);
-    cursor: pointer;
-    font-size: 14px;
-    white-space: nowrap;
-}
-.viz-btn-secondary:hover {
-    background: #5a6268;
-}
-.viz-card-plot {
-    flex: 0 0 auto;
-    display: flex;
-    flex-direction: column;
-    min-height: 500px;
-    height: 600px;
-    /* Remove horizontal padding to extend to full viewport width */
-    padding-left: 0;
-    padding-right: 0;
-    margin-left: -16px;
-    margin-right: -16px;
-}
-#viz-plot-container {
-    width: 100%;
-    height: 100%;
-    position: relative;
-    overflow: visible;
-}
-#viz-plot {
-    width: 100%;
-    height: 100%;
-}
-.viz-loading {
-    text-align: center;
-    padding: 40px;
-    color: #666;
-}
-.viz-loading-overlay {
-    position: absolute;
-    inset: 0;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    background: white;
-    color: #666;
-}
-.viz-no-results {
-    text-align: center;
-    padding: 40px;
-    color: #666;
-    font-style: italic;
-}
-.viz-advanced-section {
-    margin-top: 12px;
-    padding: 12px;
-    background: var(--color-background-hover);
-    border-radius: var(--border-radius);
-    border: 1px solid var(--color-border);
-}
-.viz-info-box {
-    background: var(--color-primary-element-light);
-    border-left: 3px solid var(--color-primary-element);
-    padding: 10px 12px;
-    margin-bottom: 16px;
-    font-size: 13px;
-    color: var(--color-main-text);
-}
-.chunk-toggle-btn {
-    background: #6c757d;
-    color: white;
-    border: none;
-    padding: 4px 10px;
-    border-radius: 3px;
-    cursor: pointer;
-    font-size: 12px;
-    margin-top: 6px;
-}
-.chunk-toggle-btn:hover {
-    background: #5a6268;
-}
-.chunk-context {
-    background: var(--color-background-hover);
-    border: 1px solid var(--color-border);
-    border-radius: var(--border-radius);
-    padding: 12px;
-    margin-top: 8px;
-    font-family: 'SFMono-Regular', 'Consolas', 'Liberation Mono', 'Menlo', monospace;
-    font-size: 13px;
-    line-height: 1.6;
-    white-space: pre-wrap;
-    word-wrap: break-word;
-}
-.chunk-text {
-    color: var(--color-text-maxcontrast);
-}
-.chunk-matched {
-    background: #fff3cd;
-    border: 1px solid #ffc107;
-    padding: 2px 4px;
-    border-radius: var(--border-radius);
-    font-weight: 500;
-    color: var(--color-main-text);
-}
-.chunk-ellipsis {
-    color: var(--color-text-maxcontrast);
-    font-style: italic;
-}
-
-/* PDF highlighted image styles */
-.chunk-image-container {
-    margin-bottom: 16px;
-    border: 1px solid var(--color-border);
-    border-radius: var(--border-radius);
-    overflow: hidden;
-    background: #fff;
-}
-.chunk-image-header {
-    background: var(--color-background-dark);
-    padding: 8px 12px;
-    font-size: 12px;
-    font-weight: 500;
-    color: var(--color-text-maxcontrast);
-    border-bottom: 1px solid var(--color-border);
-    font-family: var(--font-face);
-}
-.chunk-highlighted-image {
-    display: block;
-    max-width: 100%;
-    height: auto;
-    cursor: zoom-in;
-}
-.chunk-highlighted-image:hover {
-    opacity: 0.95;
-}
@@ -1,260 +0,0 @@
-// Initialize vizApp for vector visualization
-function vizApp() {
-    return {
-        query: '',
-        algorithm: 'bm25_hybrid',
-        fusion: 'rrf',
-        showAdvanced: false,
-        showQueryPoint: true,
-        docTypes: [''],
-        limit: 50,
-        scoreThreshold: 0.0,
-        loading: false,
-        results: [],
-        coordinates: null,
-        queryCoords: null,
-        expandedChunks: {},
-        chunkLoading: {},
-
-        init() {
-            // Set up window resize listener to resize plot
-            window.addEventListener('resize', () => {
-                if (this.coordinates && this.results.length > 0) {
-                    Plotly.Plots.resize('viz-plot');
-                }
-            });
-        },
-
-        async executeSearch() {
-            this.loading = true;
-            this.results = [];
-
-            try {
-                const params = new URLSearchParams({
-                    query: this.query,
-                    algorithm: this.algorithm,
-                    limit: this.limit,
-                    score_threshold: this.scoreThreshold,
-                });
-
-                if (this.algorithm === 'bm25_hybrid') {
-                    params.append('fusion', this.fusion);
-                }
-
-                const selectedTypes = this.docTypes.filter(t => t !== '');
-                if (selectedTypes.length > 0) {
-                    params.append('doc_types', selectedTypes.join(','));
-                }
-
-                const response = await fetch(`/app/vector-viz/search?${params}`);
-                const data = await response.json();
-
-                if (data.success) {
-                    this.results = data.results;
-                    this.coordinates = data.coordinates_3d;
-                    this.queryCoords = data.query_coords;
-                    this.renderPlot(this.coordinates, this.queryCoords, this.results);
-                } else {
-                    alert('Search failed: ' + data.error);
-                }
-            } catch (error) {
-                alert('Error: ' + error.message);
-            } finally {
-                this.loading = false;
-            }
-        },
-
-        updatePlot() {
-            // Toggle query point visibility without recreating the plot
-            // This preserves camera position naturally since layout is untouched
-            if (this.coordinates && this.queryCoords && this.results.length > 0) {
-                const plotDiv = document.getElementById('viz-plot');
-
-                // If plot exists, just toggle the query trace visibility
-                if (plotDiv && plotDiv.data && plotDiv.data.length >= 2) {
-                    // Trace index 1 is the query point
-                    Plotly.restyle('viz-plot', { visible: this.showQueryPoint }, [1]);
-                } else {
-                    // Plot doesn't exist yet, render it
-                    this.renderPlot(this.coordinates, this.queryCoords, this.results);
-                }
-            }
-        },
-
-        renderPlot(coordinates, queryCoords, results) {
-            // Get container dimensions before creating layout
-            const container = document.getElementById('viz-plot-container');
-            const width = container.clientWidth;
-            const height = container.clientHeight;
-
-            const scores = results.map(r => r.score);
-
-            // Trace 1: Document results (always visible)
-            const documentTrace = {
-                x: coordinates.map(c => c[0]),
-                y: coordinates.map(c => c[1]),
-                z: coordinates.map(c => c[2]),
-                mode: 'markers',
-                type: 'scatter3d',
-                name: 'Documents',
-                visible: true,
-                customdata: results.map((r, i) => ({
-                    title: r.title,
-                    raw_score: r.original_score,
-                    relative_score: r.score,
-                    x: coordinates[i][0],
-                    y: coordinates[i][1],
-                    z: coordinates[i][2]
-                })),
-                hovertemplate:
-                    '<b>%{customdata.title}</b><br>' +
-                    'Raw Score: %{customdata.raw_score:.3f} (%{customdata.relative_score:.0%} relative)<br>' +
-                    '(x=%{customdata.x}, y=%{customdata.y}, z=%{customdata.z})' +
-                    '<extra></extra>',
-                marker: {
-                    size: results.map(r => 4 + (Math.pow(r.score, 2) * 10)),
-                    opacity: results.map(r => 0.3 + (r.score * 0.7)),
-                    color: scores,
-                    colorscale: 'Viridis',
-                    showscale: true,
-                    colorbar: {
-                        title: 'Relative Score',
-                        x: 1.02,
-                        xanchor: 'left',
-                        thickness: 20,
-                        len: 0.8
-                    },
-                    cmin: 0,
-                    cmax: 1
-                }
-            };
-
-            // Trace 2: Query point (visibility controlled by toggle)
-            const queryTrace = {
-                x: [queryCoords[0]],
-                y: [queryCoords[1]],
-                z: [queryCoords[2]],
-                mode: 'markers',
-                type: 'scatter3d',
-                name: 'Query',
-                visible: this.showQueryPoint,  // Initial visibility from state
-                hovertemplate:
-                    '<b>Search Query</b><br>' +
-                    `(x=${queryCoords[0]}, y=${queryCoords[1]}, z=${queryCoords[2]})` +
-                    '<extra></extra>',
-                marker: {
-                    size: 10,
-                    color: '#ef5350',  // Subdued red (Material Design Red 400)
-                    line: {
-                        color: '#c62828',  // Darker red border (Material Design Red 800)
-                        width: 1
-                    }
-                }
-            };
-
-            const layout = {
-                title: `Vector Space (PCA 3D) - ${results.length} results`,
-                width: width,   // Explicit width from container
-                height: height, // Explicit height from container
-                scene: {
-                    xaxis: { title: 'PC1' },
-                    yaxis: { title: 'PC2' },
-                    zaxis: { title: 'PC3' },
-                    camera: {
-                        eye: { x: 1.5, y: 1.5, z: 1.5 }
-                    },
-                    // Full width for 3D scene
-                    domain: {
-                        x: [0, 1],
-                        y: [0, 1]
-                    }
-                },
-                hovermode: 'closest',
-                autosize: true,  // Enable auto-sizing for window resizes
-                showlegend: false,  // Hide legend
-                margin: { l: 0, r: 100, t: 40, b: 0 }  // Right margin for colorbar
-            };
-
-            // Always render both traces - visibility is controlled by the visible property
-            const traces = [documentTrace, queryTrace];
-
-            // Enable responsive resizing
-            const config = {
-                responsive: true,
-                displayModeBar: true
-            };
-
-            // Use newPlot() with explicit dimensions - renders at correct size immediately
-            // Camera position will be preserved by subsequent Plotly.restyle() calls in updatePlot()
-            Plotly.newPlot('viz-plot', traces, layout, config);
-        },
-
-        getNextcloudUrl(result) {
-            // Use global NEXTCLOUD_BASE_URL if set, otherwise construct from window location
-            const baseUrl = window.NEXTCLOUD_BASE_URL || '';
-            switch (result.doc_type) {
-                case 'note':
-                    return `${baseUrl}/apps/notes/note/${result.id}`;
-                case 'file':
-                    return `${baseUrl}/apps/files/?fileId=${result.id}`;
-                case 'calendar':
-                    return `${baseUrl}/apps/calendar`;
-                case 'contact':
-                    return `${baseUrl}/apps/contacts`;
-                case 'deck_card':
-                    // URL pattern: /apps/deck/board/:boardId/card/:cardId
-                    if (result.metadata && result.metadata.board_id) {
-                        return `${baseUrl}/apps/deck/board/${result.metadata.board_id}/card/${result.id}`;
-                    }
-                    // Fallback if board_id not available
-                    return `${baseUrl}/apps/deck`;
-                case 'news_item':
-                    return `${baseUrl}/apps/news/item/${result.id}`;
-                default:
-                    return `${baseUrl}`;
-            }
-        },
-
-        hasChunkPosition(result) {
-            return result.chunk_start_offset != null && result.chunk_end_offset != null;
-        },
-
-        isChunkExpanded(resultKey) {
-            return this.expandedChunks[resultKey] !== undefined;
-        },
-
-        async toggleChunk(result) {
-            const resultKey = `${result.doc_type}_${result.id}_${result.chunk_start_offset || 0}`;
-
-            if (this.isChunkExpanded(resultKey)) {
-                delete this.expandedChunks[resultKey];
-                return;
-            }
-
-            this.chunkLoading[resultKey] = true;
-
-            try {
-                const params = new URLSearchParams({
-                    doc_type: result.doc_type,
-                    doc_id: result.id,
-                    start: result.chunk_start_offset,
-                    end: result.chunk_end_offset,
-                    context: 500
-                });
-
-                const response = await fetch(`/app/chunk-context?${params}`);
-                const data = await response.json();
-
-                if (data.success) {
-                    this.expandedChunks[resultKey] = data;
-                } else {
-                    alert('Failed to load chunk: ' + data.error);
-                }
-            } catch (error) {
-                alert('Error loading chunk: ' + error.message);
-            } finally {
-                delete this.chunkLoading[resultKey];
-            }
-        }
-    };
-}
@@ -28,7 +28,6 @@ Sensitive data (tokens, secrets) is encrypted at rest using Fernet symmetric enc
 import json
 import logging
 import os
-import socket
 import time
 from pathlib import Path
 from typing import Any, Optional
@@ -118,14 +117,7 @@ class RefreshTokenStorage:
        return cls(db_path=db_path, encryption_key=encryption_key)

    async def initialize(self) -> None:
-        """
-        Initialize database schema using Alembic migrations.
-
-        This method handles three scenarios:
-        1. New database: Run migrations from scratch
-        2. Pre-Alembic database: Stamp with initial revision (no changes)
-        3. Alembic-managed database: Upgrade to latest version
-        """
+        """Initialize database schema"""
        if self._initialized:
            return

@@ -133,59 +125,137 @@ class RefreshTokenStorage:
        db_dir = Path(self.db_path).parent
        db_dir.mkdir(parents=True, exist_ok=True)

-        # Set restrictive permissions on database file if it exists
+        # Set restrictive permissions on database file
        if Path(self.db_path).exists():
            os.chmod(self.db_path, 0o600)

-        # Check database state and run appropriate migration strategy
        async with aiosqlite.connect(self.db_path) as db:
-            # Check if database is managed by Alembic
-            cursor = await db.execute(
-                "SELECT name FROM sqlite_master WHERE type='table' AND name='alembic_version'"
+            await db.execute(
+                """
+                CREATE TABLE IF NOT EXISTS refresh_tokens (
+                    user_id TEXT PRIMARY KEY,
+                    encrypted_token BLOB NOT NULL,
+                    expires_at INTEGER,
+                    created_at INTEGER NOT NULL,
+                    updated_at INTEGER NOT NULL,
+                    -- ADR-004 Progressive Consent fields
+                    flow_type TEXT DEFAULT 'hybrid',  -- 'hybrid', 'flow1', 'flow2'
+                    token_audience TEXT DEFAULT 'nextcloud',  -- 'mcp-server' or 'nextcloud'
+                    provisioned_at INTEGER,  -- When Flow 2 was completed
+                    provisioning_client_id TEXT,  -- Which MCP client initiated Flow 1
+                    scopes TEXT,  -- JSON array of granted scopes
+                    -- Browser session profile cache
+                    user_profile TEXT,  -- JSON cache of IdP user profile (for browser UI only)
+                    profile_cached_at INTEGER  -- When profile was last cached
+                )
+                """
            )
-            has_alembic = await cursor.fetchone() is not None

-            if not has_alembic:
-                # Check if this is a pre-Alembic database with existing schema
-                cursor = await db.execute(
-                    "SELECT name FROM sqlite_master WHERE type='table' AND name='refresh_tokens'"
+            await db.execute(
+                """
+                CREATE TABLE IF NOT EXISTS audit_logs (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    timestamp INTEGER NOT NULL,
+                    event TEXT NOT NULL,
+                    user_id TEXT NOT NULL,
+                    resource_type TEXT,
+                    resource_id TEXT,
+                    auth_method TEXT,
+                    hostname TEXT
                )
-                has_schema = await cursor.fetchone() is not None
+                """
+            )

-                if has_schema:
-                    logger.info(
-                        f"Detected pre-Alembic database at {self.db_path}, "
-                        "stamping with initial revision"
-                    )
-                else:
-                    logger.info(
-                        f"Initializing new database at {self.db_path} with migrations"
-                    )
+            # Create index on audit logs for efficient queries
+            await db.execute(
+                "CREATE INDEX IF NOT EXISTS idx_audit_user_timestamp "
+                "ON audit_logs(user_id, timestamp)"
+            )

-        # Run migrations in a worker thread using anyio.to_thread
-        # This allows Alembic to run its own async operations in a separate context
-        from anyio import to_thread
-
-        from nextcloud_mcp_server.migrations import stamp_database, upgrade_database
-
-        if not has_alembic:
-            if has_schema:
-                # Stamp existing database without running migrations
-                await to_thread.run_sync(stamp_database, self.db_path, "001")
-                logger.info(
-                    "Pre-Alembic database stamped successfully. "
-                    "Future schema changes will use migrations."
+            # OAuth client credentials storage
+            await db.execute(
+                """
+                CREATE TABLE IF NOT EXISTS oauth_clients (
+                    id INTEGER PRIMARY KEY,
+                    client_id TEXT UNIQUE NOT NULL,
+                    encrypted_client_secret BLOB NOT NULL,
+                    client_id_issued_at INTEGER NOT NULL,
+                    client_secret_expires_at INTEGER NOT NULL,
+                    redirect_uris TEXT NOT NULL,
+                    encrypted_registration_access_token BLOB,
+                    registration_client_uri TEXT,
+                    created_at INTEGER NOT NULL,
+                    updated_at INTEGER NOT NULL
                )
-            else:
-                # New database - run migrations
-                await to_thread.run_sync(upgrade_database, self.db_path, "head")
-                logger.info("Database initialized with migrations")
-        else:
-            # Alembic-managed database - upgrade to latest
-            await to_thread.run_sync(upgrade_database, self.db_path, "head")
-            logger.info("Database upgraded to latest version")
+                """
+            )

-        # Set restrictive permissions after initialization
+            # OAuth flow sessions (ADR-004 Progressive Consent)
+            await db.execute(
+                """
+                CREATE TABLE IF NOT EXISTS oauth_sessions (
+                    session_id TEXT PRIMARY KEY,
+                    client_id TEXT,
+                    client_redirect_uri TEXT NOT NULL,
+                    state TEXT,
+                    code_challenge TEXT,
+                    code_challenge_method TEXT,
+                    mcp_authorization_code TEXT UNIQUE,
+                    idp_access_token TEXT,
+                    idp_refresh_token TEXT,
+                    user_id TEXT,
+                    created_at INTEGER NOT NULL,
+                    expires_at INTEGER NOT NULL,
+                    -- ADR-004 Progressive Consent fields
+                    flow_type TEXT DEFAULT 'hybrid',  -- 'hybrid', 'flow1', 'flow2'
+                    requested_scopes TEXT,  -- JSON array of requested scopes
+                    granted_scopes TEXT,  -- JSON array of granted scopes
+                    is_provisioning BOOLEAN DEFAULT FALSE  -- True if this is a Flow 2 provisioning session
+                )
+                """
+            )
+
+            # Create index for MCP authorization code lookups
+            await db.execute(
+                "CREATE INDEX IF NOT EXISTS idx_oauth_sessions_mcp_code "
+                "ON oauth_sessions(mcp_authorization_code)"
+            )
+
+            # Schema version tracking
+            await db.execute(
+                """
+                CREATE TABLE IF NOT EXISTS schema_version (
+                    version INTEGER PRIMARY KEY,
+                    applied_at REAL NOT NULL
+                )
+                """
+            )
+
+            # Registered webhooks tracking (both BasicAuth and OAuth modes)
+            await db.execute(
+                """
+                CREATE TABLE IF NOT EXISTS registered_webhooks (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    webhook_id INTEGER NOT NULL UNIQUE,
+                    preset_id TEXT NOT NULL,
+                    created_at REAL NOT NULL
+                )
+                """
+            )
+
+            # Create indexes for efficient webhook queries
+            await db.execute(
+                "CREATE INDEX IF NOT EXISTS idx_webhooks_preset "
+                "ON registered_webhooks(preset_id)"
+            )
+            await db.execute(
+                "CREATE INDEX IF NOT EXISTS idx_webhooks_created "
+                "ON registered_webhooks(created_at)"
+            )
+
+            await db.commit()
+
+        # Set restrictive permissions after creation
        os.chmod(self.db_path, 0o600)

        self._initialized = True
@@ -217,8 +287,6 @@ class RefreshTokenStorage:
        if not self._initialized:
            await self.initialize()

-        # Type narrowing: cipher is set after initialize()
-        assert self.cipher is not None
        encrypted_token = self.cipher.encrypt(refresh_token.encode())
        now = int(time.time())
        scopes_json = json.dumps(scopes) if scopes else None
@@ -364,9 +432,6 @@ class RefreshTokenStorage:
        if not self._initialized:
            await self.initialize()

-        # Type narrowing: cipher is set after initialize()
-        assert self.cipher is not None
-
        start_time = time.time()
        try:
            async with aiosqlite.connect(self.db_path) as db:
@@ -451,9 +516,6 @@ class RefreshTokenStorage:
        if not self._initialized:
            await self.initialize()

-        # Type narrowing: cipher is set after initialize()
-        assert self.cipher is not None
-
        async with aiosqlite.connect(self.db_path) as db:
            async with db.execute(
                """
@@ -625,9 +687,6 @@ class RefreshTokenStorage:
        if not self._initialized:
            await self.initialize()

-        # Type narrowing: cipher is set after initialize()
-        assert self.cipher is not None
-
        # Encrypt sensitive data
        encrypted_secret = self.cipher.encrypt(client_secret.encode())
        encrypted_reg_token = (
@@ -698,9 +757,6 @@ class RefreshTokenStorage:
        if not self._initialized:
            await self.initialize()

-        # Type narrowing: cipher is set after initialize()
-        assert self.cipher is not None
-
        async with aiosqlite.connect(self.db_path) as db:
            async with db.execute(
                """
@@ -831,6 +887,7 @@ class RefreshTokenStorage:
            resource_id: Resource identifier
            auth_method: Authentication method used
        """
+        import socket

        hostname = socket.gethostname()
        timestamp = int(time.time())
@@ -1240,180 +1297,6 @@ class RefreshTokenStorage:

        return deleted

-    # ============================================================================
-    # App Password Storage (multi-user BasicAuth mode)
-    # ============================================================================
-
-    async def store_app_password(
-        self,
-        user_id: str,
-        app_password: str,
-    ) -> None:
-        """
-        Store encrypted app password for background sync (multi-user BasicAuth mode).
-
-        Args:
-            user_id: Nextcloud user ID
-            app_password: Nextcloud app password to store
-        """
-        if not self._initialized:
-            await self.initialize()
-
-        if not self.cipher:
-            raise RuntimeError(
-                "Encryption key not configured. "
-                "Set TOKEN_ENCRYPTION_KEY for app password storage."
-            )
-
-        encrypted_password = self.cipher.encrypt(app_password.encode())
-        now = int(time.time())
-
-        start_time = time.time()
-        try:
-            async with aiosqlite.connect(self.db_path) as db:
-                await db.execute(
-                    """
-                    INSERT OR REPLACE INTO app_passwords
-                    (user_id, encrypted_password, created_at, updated_at)
-                    VALUES (
-                        ?,
-                        ?,
-                        COALESCE((SELECT created_at FROM app_passwords WHERE user_id = ?), ?),
-                        ?
-                    )
-                    """,
-                    (user_id, encrypted_password, user_id, now, now),
-                )
-                await db.commit()
-
-            duration = time.time() - start_time
-            record_db_operation("sqlite", "insert", duration, "success")
-            logger.info(f"Stored app password for user {user_id}")
-
-        except Exception:
-            duration = time.time() - start_time
-            record_db_operation("sqlite", "insert", duration, "error")
-            raise
-
-        # Audit log
-        await self._audit_log(
-            event="store_app_password",
-            user_id=user_id,
-            auth_method="app_password",
-        )
-
-    async def get_app_password(self, user_id: str) -> Optional[str]:
-        """
-        Retrieve and decrypt app password for a user.
-
-        Args:
-            user_id: Nextcloud user ID
-
-        Returns:
-            Decrypted app password, or None if not found
-        """
-        if not self._initialized:
-            await self.initialize()
-
-        if not self.cipher:
-            raise RuntimeError(
-                "Encryption key not configured. "
-                "Set TOKEN_ENCRYPTION_KEY for app password retrieval."
-            )
-
-        start_time = time.time()
-        try:
-            async with aiosqlite.connect(self.db_path) as db:
-                async with db.execute(
-                    "SELECT encrypted_password FROM app_passwords WHERE user_id = ?",
-                    (user_id,),
-                ) as cursor:
-                    row = await cursor.fetchone()
-
-            if not row:
-                logger.debug(f"No app password found for user {user_id}")
-                duration = time.time() - start_time
-                record_db_operation("sqlite", "select", duration, "success")
-                return None
-
-            encrypted_password = row[0]
-            decrypted_password = self.cipher.decrypt(encrypted_password).decode()
-
-            duration = time.time() - start_time
-            record_db_operation("sqlite", "select", duration, "success")
-            logger.debug(f"Retrieved app password for user {user_id}")
-
-            return decrypted_password
-
-        except Exception as e:
-            duration = time.time() - start_time
-            record_db_operation("sqlite", "select", duration, "error")
-            logger.error(f"Failed to decrypt app password for user {user_id}: {e}")
-            return None
-
-    async def delete_app_password(self, user_id: str) -> bool:
-        """
-        Delete app password for a user.
-
-        Args:
-            user_id: Nextcloud user ID
-
-        Returns:
-            True if password was deleted, False if not found
-        """
-        if not self._initialized:
-            await self.initialize()
-
-        start_time = time.time()
-        try:
-            async with aiosqlite.connect(self.db_path) as db:
-                cursor = await db.execute(
-                    "DELETE FROM app_passwords WHERE user_id = ?",
-                    (user_id,),
-                )
-                await db.commit()
-                deleted = cursor.rowcount > 0
-
-            duration = time.time() - start_time
-            record_db_operation("sqlite", "delete", duration, "success")
-
-            if deleted:
-                logger.info(f"Deleted app password for user {user_id}")
-                await self._audit_log(
-                    event="delete_app_password",
-                    user_id=user_id,
-                    auth_method="app_password",
-                )
-            else:
-                logger.debug(f"No app password to delete for user {user_id}")
-
-            return deleted
-
-        except Exception:
-            duration = time.time() - start_time
-            record_db_operation("sqlite", "delete", duration, "error")
-            raise
-
-    async def get_all_app_password_user_ids(self) -> list[str]:
-        """
-        Get list of all user IDs with stored app passwords.
-
-        Returns:
-            List of user IDs
-        """
-        if not self._initialized:
-            await self.initialize()
-
-        async with aiosqlite.connect(self.db_path) as db:
-            async with db.execute(
-                "SELECT user_id FROM app_passwords ORDER BY updated_at DESC"
-            ) as cursor:
-                rows = await cursor.fetchall()
-
-        user_ids = [row[0] for row in rows]
-        logger.debug(f"Found {len(user_ids)} users with app passwords")
-        return user_ids
-

 async def generate_encryption_key() -> str:
    """
@@ -1427,7 +1310,7 @@ async def generate_encryption_key() -> str:

 # Example usage
 if __name__ == "__main__":
-    import anyio
+    import asyncio

    async def main():
        # Generate a key for testing
@@ -1435,4 +1318,4 @@ if __name__ == "__main__":
        print(f"Generated encryption key: {key}")
        print(f"Set this in your environment: export TOKEN_ENCRYPTION_KEY='{key}'")

-    anyio.run(main)
+    asyncio.run(main())
@@ -1,524 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="UTF-8">
-    <meta http-equiv="X-UA-Compatible" content="IE=edge">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1">
-    <meta name="apple-mobile-web-app-capable" content="yes">
-    <meta name="theme-color" content="#0082c9">
-    <title>{% block title %}Nextcloud MCP Server{% endblock %}</title>
-
-    <!-- Favicon -->
-    <link rel="icon" type="image/svg+xml" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' width='32' height='32' viewBox='0 0 512 512'><rect width='512' height='512' rx='80' ry='80' fill='%230082C9'/><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='%23fff'/></svg>">
-
-    <!-- Open Sans font -->
-    <style>
-        @font-face {
-            font-family: 'Open Sans';
-            font-style: normal;
-            font-weight: normal;
-            src: local('Open Sans'), local('OpenSans');
-        }
-        @font-face {
-            font-family: 'Open Sans';
-            font-style: normal;
-            font-weight: bold;
-            src: local('Open Sans Semibold'), local('OpenSans-Semibold');
-        }
-    </style>
-
-    {% block extra_head %}{% endblock %}
-
-    <style>
-        /* Nextcloud App Design System */
-
-        /* CSS Variables */
-        :root {
-            /* Primary Colors */
-            --color-primary: #00679e;
-            --color-primary-element: #00679e;
-            --color-primary-light: #e5eff5;
-            --color-primary-element-light: #e5eff5;
-
-            /* Background Colors */
-            --color-main-background: #ffffff;
-            --color-background-dark: #ededed;
-            --color-background-hover: #f5f5f5;
-
-            /* Text Colors */
-            --color-main-text: #222222;
-            --color-text-maxcontrast: #6b6b6b;
-            --color-text-light: #767676;
-
-            /* Border Colors */
-            --color-border: #ededed;
-            --color-border-dark: #dbdbdb;
-
-            /* Borders & Radius */
-            --border-radius: 3px;
-            --border-radius-large: 10px;
-            --border-radius-pill: 100px;
-
-            /* Spacing */
-            --default-grid-baseline: 4px;
-            --default-clickable-area: 44px;
-        }
-
-        /* SVG Icon Styles */
-        .nav-icon {
-            width: 20px;
-            height: 20px;
-            display: inline-block;
-            fill: var(--color-main-text);
-            opacity: 0.7;
-        }
-
-        .app-navigation-entry.active .nav-icon {
-            fill: var(--color-primary-element);
-            opacity: 1;
-        }
-
-        /* General */
-        * {
-            box-sizing: border-box;
-        }
-
-        body {
-            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
-            color: var(--color-main-text);
-            background: var(--color-main-background);
-            margin: 0;
-            padding: 0;
-        }
-
-        h1, h2, h3 {
-            font-weight: 300;
-            line-height: 1.2;
-        }
-
-        h1 {
-            font-size: 32px;
-            margin: 0 0 20px 0;
-            color: var(--color-main-text);
-        }
-
-        h2 {
-            font-size: 20px;
-            margin: 20px 0 12px 0;
-            color: var(--color-main-text);
-            border-bottom: 1px solid var(--color-border);
-            padding-bottom: 8px;
-        }
-
-        h3 {
-            font-size: 16px;
-            margin: 16px 0 8px 0;
-            color: var(--color-main-text);
-            font-weight: 500;
-        }
-
-        img {
-            max-width: 100%;
-        }
-
-        /* App Header (simplified, no full menu) */
-        .app-header {
-            height: 50px;
-            background: var(--color-primary-element);
-            box-shadow: 0 2px 4px rgba(0,0,0,0.1);
-            position: sticky;
-            top: 0;
-            z-index: 100;
-            display: flex;
-            align-items: center;
-            padding: 0 20px;
-        }
-
-        .app-header__brand {
-            color: white;
-            font-size: 18px;
-            font-weight: 600;
-            text-decoration: none;
-            display: flex;
-            align-items: center;
-            gap: 12px;
-        }
-
-        .app-header__brand:hover {
-            opacity: 0.9;
-        }
-
-        .app-header__logo {
-            height: 32px;
-            width: 32px;
-            fill: white;
-        }
-
-        /* App Layout */
-        .app-content-wrapper {
-            display: flex;
-            height: calc(100vh - 50px);
-            overflow: hidden;
-        }
-
-        /* Side Navigation */
-        #app-navigation {
-            width: 250px;
-            background: var(--color-main-background);
-            border-right: 1px solid var(--color-border);
-            display: flex;
-            flex-direction: column;
-            flex-shrink: 0;
-            transition: margin-left 0.3s ease;
-        }
-
-        #app-navigation.app-navigation--closed {
-            margin-left: -250px;
-        }
-
-        .app-navigation__content {
-            flex: 1;
-            overflow-y: auto;
-            padding: 8px;
-            display: flex;
-            flex-direction: column;
-        }
-
-        .app-navigation-list {
-            list-style: none;
-            padding: 0;
-            margin: 0;
-            flex: 1;
-        }
-
-        .app-navigation-entry {
-            position: relative;
-            margin-bottom: 2px;
-        }
-
-        .app-navigation-entry__wrapper {
-            display: flex;
-            align-items: center;
-            position: relative;
-        }
-
-        .app-navigation-entry-link {
-            display: flex;
-            align-items: center;
-            padding: 0 8px;
-            min-height: var(--default-clickable-area);
-            border-radius: var(--border-radius);
-            transition: background-color 100ms ease-in-out;
-            text-decoration: none;
-            color: var(--color-main-text);
-            flex: 1;
-            font-size: 14px;
-        }
-
-        .app-navigation-entry-link:hover {
-            background-color: var(--color-background-hover);
-        }
-
-        .app-navigation-entry.active .app-navigation-entry-link {
-            background-color: var(--color-primary-element-light);
-            font-weight: 500;
-        }
-
-        .app-navigation-entry-icon {
-            width: var(--default-clickable-area);
-            height: var(--default-clickable-area);
-            display: flex;
-            align-items: center;
-            justify-content: center;
-            margin-right: 0;
-        }
-
-        .app-navigation-entry__name {
-            flex: 1;
-            white-space: nowrap;
-            overflow: hidden;
-            text-overflow: ellipsis;
-        }
-
-        .app-navigation-entry__counter {
-            margin-left: auto;
-            padding: 2px 6px;
-            border-radius: var(--border-radius-pill);
-            background-color: var(--color-background-dark);
-            font-size: 11px;
-            color: var(--color-text-maxcontrast);
-            min-width: 20px;
-            text-align: center;
-        }
-
-        .app-navigation__settings {
-            list-style: none;
-            padding: 8px 0 0 0;
-            margin: 8px 0 0 0;
-            border-top: 1px solid var(--color-border);
-            flex-shrink: 0;
-        }
-
-        .app-navigation-toggle {
-            display: flex;
-            align-items: center;
-            justify-content: center;
-            position: fixed;
-            top: 60px;
-            left: 10px;
-            z-index: 110;
-            background: var(--color-main-background);
-            border: 1px solid var(--color-border);
-            border-radius: var(--border-radius);
-            padding: 8px 12px;
-            cursor: pointer;
-            box-shadow: 0 0 5px rgba(0,0,0,0.1);
-            transition: left 0.3s ease;
-        }
-
-        .app-navigation-toggle:hover {
-            background: var(--color-background-hover);
-        }
-
-        #app-navigation:not(.app-navigation--closed) ~ * .app-navigation-toggle {
-            left: 260px;
-        }
-
-        /* Main Content Area */
-        #app-content {
-            flex: 1;
-            overflow-y: auto;
-            background: var(--color-main-background);
-        }
-
-        .page-content {
-            max-width: 1000px;
-            margin: 0 auto;
-            padding: 24px;
-        }
-
-        .content-section {
-            background: var(--color-main-background);
-            border-radius: 0;
-            padding: 0;
-            box-shadow: none;
-        }
-
-        .content-section h1 {
-            font-size: 24px;
-            font-weight: 600;
-            margin-bottom: 24px;
-        }
-
-        .content-section h2 {
-            font-size: 18px;
-            font-weight: 500;
-            margin: 24px 0 12px 0;
-            border-bottom: none;
-            padding-bottom: 0;
-        }
-
-        .content-section h3 {
-            font-size: 16px;
-            font-weight: 500;
-        }
-
-        /* Responsive */
-        @media (max-width: 768px) {
-            #app-navigation {
-                position: fixed;
-                height: calc(100vh - 50px);
-                z-index: 105;
-                box-shadow: 2px 0 8px rgba(0,0,0,0.1);
-            }
-
-            .page-content {
-                padding: 16px;
-            }
-        }
-
-        /* Footer */
-        footer.page-footer {
-            background-color: #0F0833;
-            color: #ffffff;
-            padding: 40px 0;
-            margin-top: 60px;
-        }
-
-        footer.page-footer .bootstrap-container {
-            max-width: 1200px;
-            margin: 0 auto;
-            padding: 0 20px;
-        }
-
-        footer.page-footer h1 {
-            font-size: 15px;
-            font-weight: bold;
-            line-height: 1.8;
-            color: #ffffff;
-            margin-top: 20px;
-        }
-
-        footer.page-footer ul {
-            list-style-type: none;
-            padding-left: 0;
-        }
-
-        footer.page-footer li {
-            font-size: 13px;
-            line-height: 1.8;
-            color: #ffffff;
-            margin-top: 0;
-        }
-
-        footer.page-footer li a {
-            color: #ffffff;
-            text-decoration: none;
-            display: block;
-            padding: 4px 0;
-        }
-
-        footer.page-footer li a:hover {
-            text-decoration: underline;
-        }
-
-        footer.page-footer p {
-            font-size: 15px;
-            line-height: 1.8;
-            color: #ffffff;
-        }
-
-        footer.page-footer p.copyright {
-            color: rgba(255, 255, 255, 0.5);
-            font-size: 13px;
-            text-align: center;
-            margin-top: 30px;
-        }
-
-        /* Buttons */
-        .btn {
-            border-radius: 50px;
-            padding: 10px 20px;
-            text-decoration: none;
-            display: inline-block;
-            cursor: pointer;
-            border: none;
-            font-size: 14px;
-            transition: all 0.3s;
-        }
-
-        .btn-primary {
-            background: #0082C9;
-            border: 1px solid #0062C9;
-            color: #fff;
-        }
-
-        .btn-primary:hover {
-            background: #006ba3;
-        }
-
-        /* Tables */
-        table {
-            width: 100%;
-            border-collapse: collapse;
-            margin: 20px 0;
-        }
-
-        td {
-            padding: 12px 8px;
-            border-bottom: 1px solid var(--color-border);
-            font-size: 14px;
-        }
-
-        td:first-child {
-            width: 180px;
-            color: var(--color-text-maxcontrast);
-            font-weight: 500;
-        }
-
-        code {
-            background-color: var(--color-background-dark);
-            padding: 2px 6px;
-            border-radius: var(--border-radius);
-            font-family: 'SFMono-Regular', 'Consolas', 'Liberation Mono', 'Menlo', monospace;
-            font-size: 90%;
-            color: var(--color-main-text);
-        }
-
-        /* Badges */
-        .badge {
-            display: inline-block;
-            padding: 3px 8px;
-            border-radius: 12px;
-            font-size: 12px;
-            font-weight: bold;
-            text-transform: uppercase;
-        }
-
-        .badge-oauth {
-            background-color: #4caf50;
-            color: white;
-        }
-
-        .badge-basic {
-            background-color: #2196f3;
-            color: white;
-        }
-
-        /* Messages */
-        .warning {
-            background-color: #fff3cd;
-            border-left: 4px solid #ffc107;
-            padding: 15px;
-            margin: 15px 0;
-            color: #856404;
-        }
-
-        .info-message {
-            background-color: #e3f2fd;
-            border-left: 4px solid #2196f3;
-            padding: 15px;
-            margin: 15px 0;
-            color: #1565c0;
-        }
-
-        .error {
-            background-color: #ffebee;
-            border-left: 4px solid #d32f2f;
-            padding: 15px;
-            margin: 15px 0;
-            color: #c62828;
-        }
-
-        .success {
-            background-color: #e8f5e9;
-            border: 2px solid #4caf50;
-            padding: 30px;
-            border-radius: 8px;
-            text-align: center;
-        }
-
-        .success h1 {
-            color: #4caf50;
-        }
-
-        {% block extra_styles %}{% endblock %}
-    </style>
-</head>
-<body>
-    <!-- App Header -->
-    <header class="app-header">
-        <a href="/app" class="app-header__brand">
-            <svg class="app-header__logo" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
-                <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>
-            <span>Nextcloud MCP Server</span>
-        </a>
-    </header>
-
-    <!-- App Content Wrapper (Sidebar + Main Content) -->
-    {% block content %}{% endblock %}
-
-    {% block scripts %}{% endblock %}
-</body>
-</html>
@@ -1,19 +0,0 @@
-{% extends "base.html" %}
-
-{% block title %}{{ error_title|default('Error') }} - Nextcloud MCP Server{% endblock %}
-
-{% block content %}
-<h1>{{ error_title|default('Error') }}</h1>
-
-<div class="error">
-    <strong>Error:</strong> {{ error_message }}
-</div>
-
-{% if login_url %}
-<p><a href="{{ login_url }}" class="btn btn-primary">Login again</a></p>
-{% endif %}
-
-{% if back_url %}
-<p><a href="{{ back_url }}" class="btn">Go Back</a></p>
-{% endif %}
-{% endblock %}
@@ -1,21 +0,0 @@
-{% extends "base.html" %}
-
-{% block title %}{{ success_title|default('Success') }} - Nextcloud MCP Server{% endblock %}
-
-{% block extra_head %}
-{% if redirect_url and redirect_delay %}
-<meta http-equiv="refresh" content="{{ redirect_delay }};url={{ redirect_url }}">
-{% endif %}
-{% endblock %}
-
-{% block content %}
-<div class="success">
-    <h1>{{ success_title|default('✓ Success') }}</h1>
-    {% for message in success_messages %}
-    <p>{{ message }}</p>
-    {% endfor %}
-    {% if redirect_url %}
-    <p>Redirecting...</p>
-    {% endif %}
-</div>
-{% endblock %}
@@ -1,650 +0,0 @@
-{% extends "base.html" %}
-
-{% block title %}Nextcloud MCP Server{% endblock %}
-
-{% block extra_head %}
-    <!-- htmx for dynamic loading -->
-    <script src="https://unpkg.com/htmx.org@1.9.10"></script>
-
-    <!-- Alpine.js for state management -->
-    <script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>
-
-    <!-- Plotly.js for vector visualization -->
-    <script src="https://cdn.plot.ly/plotly-3.3.0.min.js"></script>
-
-    <!-- Vector Viz static assets -->
-    <link rel="stylesheet" href="/app/static/vector-viz.css">
-{% endblock %}
-
-{% block extra_styles %}
-    /* Smooth htmx transitions */
-    .htmx-swapping {
-        opacity: 0;
-        transition: opacity 200ms ease-out;
-    }
-
-    .htmx-settling {
-        opacity: 1;
-        transition: opacity 200ms ease-in;
-    }
-
-    /* Logout button styling */
-    .logout-section {
-        margin-top: 20px;
-        padding-top: 20px;
-        border-top: 1px solid var(--color-border);
-    }
-
-    /* Welcome tab specific styles */
-    .hero-section {
-        background: linear-gradient(135deg, var(--color-primary-element) 0%, #0082c9 100%);
-        color: white;
-        padding: 60px 24px;
-        margin: -24px -24px 40px -24px;
-        border-radius: 0 0 var(--border-radius-large) var(--border-radius-large);
-        text-align: center;
-    }
-
-    .hero-section h1 {
-        color: white;
-        font-size: 36px;
-        margin: 0 0 16px 0;
-        font-weight: 600;
-    }
-
-    .hero-section p {
-        font-size: 18px;
-        opacity: 0.95;
-        max-width: 700px;
-        margin: 0 auto;
-        line-height: 1.6;
-    }
-
-    .feature-grid {
-        display: grid;
-        grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
-        gap: 24px;
-        margin: 32px 0;
-    }
-
-    .feature-card {
-        background: var(--color-main-background);
-        border: 2px solid var(--color-border);
-        border-radius: var(--border-radius-large);
-        padding: 24px;
-        transition: all 0.2s;
-        cursor: pointer;
-        text-decoration: none;
-        color: inherit;
-        display: block;
-    }
-
-    .feature-card:hover {
-        border-color: var(--color-primary-element);
-        box-shadow: 0 4px 12px rgba(0, 103, 158, 0.15);
-        transform: translateY(-2px);
-    }
-
-    .feature-card h3 {
-        color: var(--color-primary-element);
-        font-size: 20px;
-        margin: 12px 0 8px 0;
-        font-weight: 600;
-        display: flex;
-        align-items: center;
-        gap: 12px;
-    }
-
-    .feature-card p {
-        color: var(--color-text-maxcontrast);
-        font-size: 14px;
-        line-height: 1.6;
-        margin: 8px 0 0 0;
-    }
-
-    .feature-icon {
-        width: 48px;
-        height: 48px;
-        background: var(--color-primary-element-light);
-        border-radius: var(--border-radius);
-        display: flex;
-        align-items: center;
-        justify-content: center;
-        margin-bottom: 8px;
-    }
-
-    .feature-icon svg {
-        width: 28px;
-        height: 28px;
-        fill: var(--color-primary-element);
-    }
-
-    .info-section {
-        background: var(--color-background-hover);
-        border-radius: var(--border-radius-large);
-        padding: 32px;
-        margin: 32px 0;
-    }
-
-    .info-section h2 {
-        color: var(--color-main-text);
-        font-size: 24px;
-        margin: 0 0 16px 0;
-        border: none;
-        padding: 0;
-    }
-
-    .info-section p {
-        color: var(--color-text-maxcontrast);
-        line-height: 1.7;
-        margin: 12px 0;
-    }
-
-    .info-section ul {
-        margin: 12px 0;
-        padding-left: 24px;
-    }
-
-    .info-section li {
-        color: var(--color-text-maxcontrast);
-        line-height: 1.7;
-        margin: 8px 0;
-    }
-
-    .info-section code {
-        background: var(--color-main-background);
-        padding: 2px 8px;
-        border-radius: var(--border-radius);
-        font-size: 13px;
-    }
-
-    .auth-status {
-        background: var(--color-primary-element-light);
-        border-left: 4px solid var(--color-primary-element);
-        padding: 16px 20px;
-        margin: 24px 0;
-        border-radius: var(--border-radius);
-        display: flex;
-        align-items: center;
-        gap: 12px;
-    }
-
-    .auth-status svg {
-        width: 24px;
-        height: 24px;
-        fill: var(--color-primary-element);
-        flex-shrink: 0;
-    }
-
-    .auth-status-text {
-        flex: 1;
-    }
-
-    .auth-status-text strong {
-        display: block;
-        color: var(--color-main-text);
-        font-size: 14px;
-        margin-bottom: 4px;
-    }
-
-    .auth-status-text span {
-        color: var(--color-text-maxcontrast);
-        font-size: 13px;
-    }
-{% endblock %}
-
-{% block content %}
-<div class="app-content-wrapper" x-data="{ activeSection: 'welcome', navOpen: true }">
-    <!-- Side Navigation -->
-    <nav id="app-navigation" :class="{ 'app-navigation--closed': !navOpen }">
-        <div class="app-navigation__content">
-            <!-- Navigation List -->
-            <ul class="app-navigation-list">
-                <li class="app-navigation-entry" :class="{ 'active': activeSection === 'welcome' }">
-                    <div class="app-navigation-entry__wrapper">
-                        <a href="#"
-                           @click.prevent="activeSection = 'welcome'"
-                           class="app-navigation-entry-link">
-                            <span class="app-navigation-entry-icon">
-                                <svg class="nav-icon" viewBox="0 0 24 24">
-                                    <path d="M10,20V14H14V20H19V12H22L12,3L2,12H5V20H10Z" />
-                                </svg>
-                            </span>
-                            <span class="app-navigation-entry__name">Welcome</span>
-                        </a>
-                    </div>
-                </li>
-
-                <li class="app-navigation-entry" :class="{ 'active': activeSection === 'user-info' }">
-                    <div class="app-navigation-entry__wrapper">
-                        <a href="#"
-                           @click.prevent="activeSection = 'user-info'"
-                           class="app-navigation-entry-link">
-                            <span class="app-navigation-entry-icon">
-                                <svg class="nav-icon" viewBox="0 0 24 24">
-                                    <path d="M12,4A4,4 0 0,1 16,8A4,4 0 0,1 12,12A4,4 0 0,1 8,8A4,4 0 0,1 12,4M12,14C16.42,14 20,15.79 20,18V20H4V18C4,15.79 7.58,14 12,14Z" />
-                                </svg>
-                            </span>
-                            <span class="app-navigation-entry__name">User Info</span>
-                        </a>
-                    </div>
-                </li>
-
-                {% if show_vector_sync_tab %}
-                <li class="app-navigation-entry" :class="{ 'active': activeSection === 'vector-sync' }">
-                    <div class="app-navigation-entry__wrapper">
-                        <a href="#"
-                           @click.prevent="activeSection = 'vector-sync'"
-                           class="app-navigation-entry-link">
-                            <span class="app-navigation-entry-icon">
-                                <svg class="nav-icon" viewBox="0 0 24 24">
-                                    <path d="M12,18A6,6 0 0,1 6,12C6,11 6.25,10.03 6.7,9.2L5.24,7.74C4.46,8.97 4,10.43 4,12A8,8 0 0,0 12,20V23L16,19L12,15M12,4V1L8,5L12,9V6A6,6 0 0,1 18,12C18,13 17.75,13.97 17.3,14.8L18.76,16.26C19.54,15.03 20,13.57 20,12A8,8 0 0,0 12,4Z" />
-                                </svg>
-                            </span>
-                            <span class="app-navigation-entry__name">Vector Sync</span>
-                        </a>
-                    </div>
-                </li>
-
-                <li class="app-navigation-entry" :class="{ 'active': activeSection === 'vector-viz' }">
-                    <div class="app-navigation-entry__wrapper">
-                        <a href="#"
-                           @click.prevent="activeSection = 'vector-viz'"
-                           class="app-navigation-entry-link">
-                            <span class="app-navigation-entry-icon">
-                                <svg class="nav-icon" viewBox="0 0 24 24">
-                                    <path d="M22,21H2V3H4V19H6V10H10V19H12V6H16V19H18V14H22V21Z" />
-                                </svg>
-                            </span>
-                            <span class="app-navigation-entry__name">Vector Viz</span>
-                        </a>
-                    </div>
-                </li>
-                {% endif %}
-
-                {% if show_webhooks_tab %}
-                <li class="app-navigation-entry" :class="{ 'active': activeSection === 'webhooks' }">
-                    <div class="app-navigation-entry__wrapper">
-                        <a href="#"
-                           @click.prevent="activeSection = 'webhooks'"
-                           class="app-navigation-entry-link">
-                            <span class="app-navigation-entry-icon">
-                                <svg class="nav-icon" viewBox="0 0 24 24">
-                                    <path d="M10.59,13.41C11,13.8 11,14.44 10.59,14.83C10.2,15.22 9.56,15.22 9.17,14.83C7.22,12.88 7.22,9.71 9.17,7.76V7.76L12.71,4.22C14.66,2.27 17.83,2.27 19.78,4.22C21.73,6.17 21.73,9.34 19.78,11.29L18.29,12.78C18.3,11.96 18.17,11.14 17.89,10.36L18.36,9.88C19.54,8.71 19.54,6.81 18.36,5.64C17.19,4.46 15.29,4.46 14.12,5.64L10.59,9.17C9.41,10.34 9.41,12.24 10.59,13.41M13.41,9.17C13.8,8.78 14.44,8.78 14.83,9.17C16.78,11.12 16.78,14.29 14.83,16.24V16.24L11.29,19.78C9.34,21.73 6.17,21.73 4.22,19.78C2.27,17.83 2.27,14.66 4.22,12.71L5.71,11.22C5.7,12.04 5.83,12.86 6.11,13.65L5.64,14.12C4.46,15.29 4.46,17.19 5.64,18.36C6.81,19.54 8.71,19.54 9.88,18.36L13.41,14.83C14.59,13.66 14.59,11.76 13.41,10.59C13,10.2 13,9.56 13.41,9.17Z" />
-                                </svg>
-                            </span>
-                            <span class="app-navigation-entry__name">Webhooks</span>
-                        </a>
-                    </div>
-                </li>
-                {% endif %}
-            </ul>
-
-            <!-- Settings/Logout at bottom -->
-            {% if logout_url %}
-            <ul class="app-navigation__settings">
-                <li class="app-navigation-entry">
-                    <div class="app-navigation-entry__wrapper">
-                        <a href="{{ logout_url }}" class="app-navigation-entry-link">
-                            <span class="app-navigation-entry-icon">
-                                <svg class="nav-icon" viewBox="0 0 24 24">
-                                    <path d="M16,17V14H9V10H16V7L21,12L16,17M14,2A2,2 0 0,1 16,4V6H14V4H5V20H14V18H16V20A2,2 0 0,1 14,22H5A2,2 0 0,1 3,20V4A2,2 0 0,1 5,2H14Z" />
-                                </svg>
-                            </span>
-                            <span class="app-navigation-entry__name">Logout</span>
-                        </a>
-                    </div>
-                </li>
-            </ul>
-            {% endif %}
-        </div>
-
-        <!-- Toggle Button (mobile) -->
-        <button @click="navOpen = !navOpen"
-                class="app-navigation-toggle"
-                :aria-expanded="navOpen.toString()">
-            ☰
-        </button>
-    </nav>
-
-    <!-- Main Content Area -->
-    <main id="app-content">
-        <div class="page-content">
-            <!-- Welcome Section -->
-            <div x-show="activeSection === 'welcome'">
-                <!-- Hero Section -->
-                <div class="hero-section">
-                    <h1>Welcome to Nextcloud MCP Server</h1>
-                    <p>
-                        Interactive user interface for semantic search and document retrieval.
-                        Test queries, visualize results, and explore your Nextcloud content using RAG workflows.
-                    </p>
-                </div>
-
-                <!-- Authentication Status -->
-                <div class="auth-status">
-                    <svg viewBox="0 0 24 24">
-                        <path d="M12,4A4,4 0 0,1 16,8A4,4 0 0,1 12,12A4,4 0 0,1 8,8A4,4 0 0,1 12,4M12,14C16.42,14 20,15.79 20,18V20H4V18C4,15.79 7.58,14 12,14Z" />
-                    </svg>
-                    <div class="auth-status-text">
-                        <strong>Authenticated as: {{ username }}</strong>
-                        <span>Authentication mode: <code>{{ auth_mode }}</code></span>
-                    </div>
-                </div>
-
-                {% if vector_sync_enabled %}
-                <!-- Vector Sync Enabled Content -->
-                <div class="info-section">
-                    <h2>About Semantic Search</h2>
-                    <p>
-                        This interface provides access to <strong>semantic search</strong> capabilities powered by vector embeddings.
-                        Unlike traditional keyword search, semantic search understands the <em>meaning</em> of your queries and finds
-                        conceptually similar content across your Nextcloud apps.
-                    </p>
-                    <p>
-                        <strong>How it works:</strong>
-                    </p>
-                    <ul>
-                        <li>Documents from Notes, Calendar, Files, Contacts, and Deck are indexed into a vector database</li>
-                        <li>Each document chunk is converted to a 768-dimensional vector embedding that captures semantic meaning</li>
-                        <li>Queries are also converted to embeddings and matched against document vectors using similarity search</li>
-                        <li>Results can be retrieved using pure semantic search or hybrid BM25 search combining keywords and semantics</li>
-                    </ul>
-                </div>
-
-                <div class="info-section">
-                    <h2>RAG Workflow Integration</h2>
-                    <p>
-                        This UI allows you to <strong>test the same queries that Large Language Models (LLMs) would use</strong> in a
-                        Retrieval-Augmented Generation (RAG) workflow. When an AI assistant needs to answer questions about your data:
-                    </p>
-                    <ul>
-                        <li><strong>Step 1:</strong> The assistant converts your question into a search query</li>
-                        <li><strong>Step 2:</strong> The MCP server retrieves relevant document chunks using semantic search</li>
-                        <li><strong>Step 3:</strong> Retrieved context is passed to the LLM to generate an informed answer</li>
-                    </ul>
-
-                    <!-- RAG Workflow Diagram -->
-                    <div style="background: var(--color-main-background); border: 2px solid var(--color-primary-element); border-radius: var(--border-radius-large); padding: 24px; margin: 24px 0; overflow-x: auto;">
-                        <div style="text-align: center; font-weight: 600; margin-bottom: 20px; color: var(--color-primary-element); font-size: 16px;">
-                            MCP Sampling RAG Workflow
-                        </div>
-
-                        <!-- Four-component bidirectional flow -->
-                        <div style="max-width: 1000px; margin: 0 auto;">
-                            <div style="display: grid; grid-template-columns: 0.7fr auto 1fr auto 1fr auto 0.9fr; gap: 10px; align-items: center;">
-                                <!-- User -->
-                                <div style="background: var(--color-background-hover); border: 2px solid var(--color-border); border-radius: var(--border-radius-large); padding: 14px; text-align: center;">
-                                    <div style="font-size: 26px; margin-bottom: 5px;">👤</div>
-                                    <div style="font-weight: 600; color: var(--color-main-text); font-size: 12px;">User</div>
-                                    <div style="font-size: 9px; color: var(--color-text-maxcontrast); font-style: italic; margin-top: 5px; line-height: 1.2;">
-                                        "What are health<br>benefits of coffee?"
-                                    </div>
-                                </div>
-
-                                <!-- Arrow User <-> Client -->
-                                <div style="text-align: center;">
-                                    <div style="font-size: 20px; color: var(--color-text-maxcontrast);">↔</div>
-                                </div>
-
-                                <!-- MCP Client + LLM (combined) -->
-                                <div style="background: var(--color-primary-element-light); border: 2px solid var(--color-primary-element); border-radius: var(--border-radius-large); padding: 12px; text-align: center;">
-                                    <div style="font-weight: 600; color: var(--color-primary-element); font-size: 13px; margin-bottom: 8px;">MCP Client + LLM</div>
-
-                                    <div style="background: var(--color-main-background); border-radius: var(--border-radius); padding: 8px; margin-bottom: 6px;">
-                                        <div style="font-size: 9px; color: var(--color-text-maxcontrast);">(Claude Code)</div>
-                                    </div>
-
-                                    <div style="background: var(--color-main-background); border-radius: var(--border-radius); padding: 8px; border: 2px solid var(--color-primary-element);">
-                                        <div style="font-size: 16px; margin-bottom: 2px;">🧠</div>
-                                        <div style="font-weight: 600; color: var(--color-main-text); font-size: 10px;">Client's LLM</div>
-                                        <div style="font-size: 8px; color: var(--color-text-maxcontrast);">(Claude)</div>
-                                    </div>
-
-                                    <div style="margin-top: 8px; font-size: 8px; color: var(--color-text-maxcontrast); line-height: 1.2;">
-                                        <strong>Enables RAG:</strong><br>
-                                        Receives context,<br>
-                                        generates answer
-                                    </div>
-                                </div>
-
-                                <!-- Arrow Client <-> Server -->
-                                <div style="text-align: center;">
-                                    <div style="font-size: 20px; color: var(--color-primary-element);">↔</div>
-                                    <div style="font-size: 7px; color: var(--color-text-maxcontrast); margin-top: 2px; font-weight: 600; line-height: 1.1;">
-                                        Query +<br>
-                                        Sampling
-                                    </div>
-                                </div>
-
-                                <!-- MCP Server -->
-                                <div style="background: var(--color-primary-element-light); border: 2px solid var(--color-primary-element); border-radius: var(--border-radius-large); padding: 12px; text-align: center;">
-                                    <div style="font-weight: 600; color: var(--color-primary-element); font-size: 13px; margin-bottom: 8px;">MCP Server</div>
-
-                                    <div style="background: var(--color-main-background); border-radius: var(--border-radius); padding: 7px; margin-bottom: 5px;">
-                                        <div style="font-weight: 600; color: var(--color-main-text); font-size: 9px; margin-bottom: 2px;">1. Semantic Search</div>
-                                        <div style="font-size: 7px; color: var(--color-text-maxcontrast); line-height: 1.2;">
-                                            Vector embeddings<br>
-                                            BM25 Hybrid + RRF
-                                        </div>
-                                    </div>
-
-                                    <div style="background: var(--color-main-background); border-radius: var(--border-radius); padding: 7px; margin-bottom: 5px;">
-                                        <div style="font-weight: 600; color: var(--color-main-text); font-size: 9px; margin-bottom: 2px;">2. Retrieve Context</div>
-                                        <div style="font-size: 7px; color: var(--color-text-maxcontrast); line-height: 1.2;">
-                                            Top relevant docs<br>
-                                            with scores
-                                        </div>
-                                    </div>
-
-                                    <div style="background: var(--color-main-background); border-radius: var(--border-radius); padding: 7px; margin-bottom: 5px;">
-                                        <div style="font-weight: 600; color: var(--color-main-text); font-size: 9px; margin-bottom: 2px;">3. Format Response</div>
-                                        <div style="font-size: 7px; color: var(--color-text-maxcontrast); line-height: 1.2;">
-                                            Document chunks<br>
-                                            with citations
-                                        </div>
-                                    </div>
-
-                                    <div style="background: var(--color-main-background); border-radius: var(--border-radius); padding: 7px;">
-                                        <div style="font-weight: 600; color: var(--color-main-text); font-size: 9px; margin-bottom: 2px;">4. Send to LLM</div>
-                                        <div style="font-size: 7px; color: var(--color-text-maxcontrast); line-height: 1.2;">
-                                            Via MCP sampling<br>
-                                            for answer generation
-                                        </div>
-                                    </div>
-                                </div>
-
-                                <!-- Arrow Server <-> Nextcloud -->
-                                <div style="text-align: center;">
-                                    <div style="font-size: 20px; color: var(--color-primary-element);">↔</div>
-                                    <div style="font-size: 7px; color: var(--color-text-maxcontrast); margin-top: 2px; font-weight: 600; line-height: 1.1;">
-                                        Retrieve
-                                    </div>
-                                </div>
-
-                                <!-- Nextcloud -->
-                                <div style="background: var(--color-background-hover); border: 2px solid var(--color-border); border-radius: var(--border-radius-large); padding: 12px; text-align: center; position: relative;">
-                                    <img src="/app/static/nextcloud-logo.png" alt="Nextcloud" style="width: 40px; height: 40px; margin-bottom: 6px;" />
-                                    <div style="font-weight: 600; color: var(--color-main-text); font-size: 12px; margin-bottom: 4px;">Nextcloud</div>
-                                    <div style="font-size: 8px; color: var(--color-text-maxcontrast); line-height: 1.2;">
-                                        Notes, Calendar,<br>
-                                        Files, Contacts,<br>
-                                        Deck
-                                    </div>
-                                </div>
-                            </div>
-
-                            <!-- Explanation below diagram -->
-                            <div style="margin-top: 24px; padding: 16px; background: var(--color-background-hover); border-radius: var(--border-radius); border-left: 4px solid var(--color-primary-element);">
-                                <div style="font-size: 12px; color: var(--color-main-text); line-height: 1.6;">
-                                    <strong>How RAG works via MCP Sampling:</strong>
-                                </div>
-                                <ol style="margin: 8px 0 0 0; padding-left: 20px; font-size: 11px; color: var(--color-text-maxcontrast); line-height: 1.6;">
-                                    <li>User asks question through MCP Client</li>
-                                    <li>Client sends query to MCP Server</li>
-                                    <li>Server retrieves relevant document context from Nextcloud</li>
-                                    <li><strong>Server sends context back to Client's LLM</strong> (MCP Sampling)</li>
-                                    <li>Client's LLM generates answer with citations using retrieved context</li>
-                                    <li>Answer returned to user</li>
-                                </ol>
-                                <div style="margin-top: 8px; font-size: 10px; color: var(--color-text-maxcontrast); font-style: italic;">
-                                    The server has no LLM - it only retrieves context. The client's existing LLM is reused for answer generation.
-                                </div>
-                            </div>
-                        </div>
-                    </div>
-
-                    <p style="margin-top: 16px;">
-                        <strong>Key Point:</strong> The MCP server retrieves context but doesn't generate answers itself.
-                        Through <strong>MCP sampling</strong>, it requests the client's LLM to generate responses, giving users
-                        full control over which model is used and ensuring all processing happens client-side.
-                    </p>
-
-                    <p>
-                        By using this interface, you can preview search results, understand relevance scores, and verify
-                        that the system retrieves the right information before it reaches the LLM.
-                    </p>
-                </div>
-
-                <!-- Feature Cards -->
-                <h2>Available Features</h2>
-                <div class="feature-grid">
-                    <a href="#" @click.prevent="activeSection = 'user-info'" class="feature-card">
-                        <div class="feature-icon">
-                            <svg viewBox="0 0 24 24">
-                                <path d="M12,4A4,4 0 0,1 16,8A4,4 0 0,1 12,12A4,4 0 0,1 8,8A4,4 0 0,1 12,4M12,14C16.42,14 20,15.79 20,18V20H4V18C4,15.79 7.58,14 12,14Z" />
-                            </svg>
-                        </div>
-                        <h3>User Information</h3>
-                        <p>
-                            View your authentication details, session information, and IdP profile.
-                            Manage background access permissions.
-                        </p>
-                    </a>
-
-                    <a href="#" @click.prevent="activeSection = 'vector-sync'" class="feature-card">
-                        <div class="feature-icon">
-                            <svg viewBox="0 0 24 24">
-                                <path d="M12,18A6,6 0 0,1 6,12C6,11 6.25,10.03 6.7,9.2L5.24,7.74C4.46,8.97 4,10.43 4,12A8,8 0 0,0 12,20V23L16,19L12,15M12,4V1L8,5L12,9V6A6,6 0 0,1 18,12C18,13 17.75,13.97 17.3,14.8L18.76,16.26C19.54,15.03 20,13.57 20,12A8,8 0 0,0 12,4Z" />
-                            </svg>
-                        </div>
-                        <h3>Vector Sync Status</h3>
-                        <p>
-                            Monitor real-time indexing progress with metrics for indexed documents, pending queue,
-                            and synchronization status.
-                        </p>
-                    </a>
-
-                    <a href="#" @click.prevent="activeSection = 'vector-viz'" class="feature-card">
-                        <div class="feature-icon">
-                            <svg viewBox="0 0 24 24">
-                                <path d="M22,21H2V3H4V19H6V10H10V19H12V6H16V19H18V14H22V21Z" />
-                            </svg>
-                        </div>
-                        <h3>Vector Visualization</h3>
-                        <p>
-                            Interactive search interface with 2D PCA visualization. Compare algorithms,
-                            view relevance scores, and explore matched document chunks.
-                        </p>
-                    </a>
-                </div>
-
-                {% else %}
-                <!-- Vector Sync Disabled Content -->
-                <div class="warning">
-                    <h3 style="margin-top: 0;">Vector Sync is Disabled</h3>
-                    <p>
-                        Semantic search and vector visualization features are currently disabled.
-                        To enable these features, set <code>VECTOR_SYNC_ENABLED=true</code> in your environment configuration.
-                    </p>
-                    <p style="margin-bottom: 0;">
-                        <strong>Learn more:</strong>
-                        <a href="https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/configuration.md" target="_blank" style="color: inherit; text-decoration: underline;">
-                            Configuration Guide
-                        </a>
-                    </p>
-                </div>
-
-                <!-- Limited Feature Card -->
-                <h2>Available Features</h2>
-                <div class="feature-grid">
-                    <a href="#" @click.prevent="activeSection = 'user-info'" class="feature-card">
-                        <div class="feature-icon">
-                            <svg viewBox="0 0 24 24">
-                                <path d="M12,4A4,4 0 0,1 16,8A4,4 0 0,1 12,12A4,4 0 0,1 8,8A4,4 0 0,1 12,4M12,14C16.42,14 20,15.79 20,18V20H4V18C4,15.79 7.58,14 12,14Z" />
-                            </svg>
-                        </div>
-                        <h3>User Information</h3>
-                        <p>
-                            View your authentication details, session information, and IdP profile.
-                            Manage background access permissions.
-                        </p>
-                    </a>
-                </div>
-                {% endif %}
-
-                <!-- Documentation Section -->
-                <div class="info-section" style="margin-top: 40px;">
-                    <h2>Documentation</h2>
-                    <p>
-                        For detailed information about configuration, authentication modes, and advanced features,
-                        please refer to the project documentation:
-                    </p>
-                    <ul>
-                        <li><a href="https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/installation.md" target="_blank">Installation Guide</a></li>
-                        <li><a href="https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/configuration.md" target="_blank">Configuration Options</a></li>
-                        <li><a href="https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/authentication.md" target="_blank">Authentication Modes</a></li>
-                        {% if vector_sync_enabled %}
-                        <li><a href="https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/user-guide/vector-sync-ui.md" target="_blank">Vector Sync UI Guide</a></li>
-                        {% endif %}
-                    </ul>
-                </div>
-            </div>
-
-            <!-- User Info Section -->
-            <div x-show="activeSection === 'user-info'">
-                <div class="content-section">
-                    <h1>User Information</h1>
-                    {{ user_info_tab_html|safe }}
-                </div>
-            </div>
-
-            {% if show_vector_sync_tab %}
-            <!-- Vector Sync Section -->
-            <div x-show="activeSection === 'vector-sync'">
-                <div class="content-section">
-                    <h1>Vector Sync Status</h1>
-                    {{ vector_sync_tab_html|safe }}
-                </div>
-            </div>
-
-            <!-- Vector Viz Section -->
-            <div x-show="activeSection === 'vector-viz'">
-                <div class="content-section">
-                    <h1>Vector Visualization</h1>
-                    <div hx-get="/app/vector-viz" hx-trigger="load" hx-swap="outerHTML">
-                        <p style="color: #999;">Loading vector visualization...</p>
-                    </div>
-                </div>
-            </div>
-            {% endif %}
-
-            {% if show_webhooks_tab %}
-            <!-- Webhooks Section -->
-            <div x-show="activeSection === 'webhooks'">
-                <div class="content-section">
-                    <h1>Webhook Management</h1>
-                    {{ webhooks_tab_html|safe }}
-                </div>
-            </div>
-            {% endif %}
-        </div>
-    </main>
-</div>
-
-<script>
-    // Set global Nextcloud base URL for use in external JS
-    window.NEXTCLOUD_BASE_URL = '{{ nextcloud_host_for_links }}';
-</script>
-<script src="/app/static/vector-viz.js"></script>
-{% endblock %}
@@ -1,184 +0,0 @@
-<div x-data="vizApp()">
-    <div class="viz-layout">
-        <!-- Top: Search Controls -->
-        <div class="viz-card viz-controls-card">
-            <form @submit.prevent="executeSearch">
-                <div class="viz-controls-grid">
-                    <div class="viz-control-group">
-                        <label>Search Query</label>
-                        <input type="text" x-model="query" placeholder="Enter search query..." required />
-                    </div>
-
-                    <div class="viz-control-group">
-                        <label>Algorithm</label>
-                        <select x-model="algorithm">
-                            <option value="semantic">Semantic (Dense)</option>
-                            <option value="bm25_hybrid" selected>BM25 Hybrid</option>
-                        </select>
-                    </div>
-
-                    <div class="viz-control-group">
-                        <label>Fusion</label>
-                        <select x-model="fusion" :disabled="algorithm !== 'bm25_hybrid'" :style="algorithm !== 'bm25_hybrid' ? 'opacity: 0.5; cursor: not-allowed;' : ''">
-                            <option value="rrf" selected>RRF</option>
-                            <option value="dbsf">DBSF</option>
-                        </select>
-                    </div>
-
-                    <div class="viz-control-group">
-                        <label>&nbsp;</label>
-                        <button type="submit" class="viz-btn">Search</button>
-                    </div>
-
-                    <div class="viz-control-group">
-                        <label>&nbsp;</label>
-                        <button type="button" class="viz-btn-secondary" @click="showAdvanced = !showAdvanced">
-                            <span x-text="showAdvanced ? 'Hide' : 'Advanced'"></span>
-                        </button>
-                    </div>
-                </div>
-
-                <!-- Advanced Options (Collapsible) -->
-                <div x-show="showAdvanced" style="margin-top: 16px;">
-                    <div class="viz-controls-grid" style="grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));">
-                        <div class="viz-control-group">
-                            <label>Document Types</label>
-                            <div style="display: grid; grid-template-columns: 1fr 1fr; gap: 8px; font-size: 13px;">
-                                <label style="display: flex; align-items: center; cursor: pointer; font-weight: normal;">
-                                    <input type="checkbox" x-model="docTypes" value="" style="margin-right: 4px;">
-                                    <span>All</span>
-                                </label>
-                                <label style="display: flex; align-items: center; cursor: pointer; font-weight: normal;">
-                                    <input type="checkbox" x-model="docTypes" value="note" style="margin-right: 4px;">
-                                    <span>Notes</span>
-                                </label>
-                                <label style="display: flex; align-items: center; cursor: pointer; font-weight: normal;">
-                                    <input type="checkbox" x-model="docTypes" value="file" style="margin-right: 4px;">
-                                    <span>Files</span>
-                                </label>
-                                <label style="display: flex; align-items: center; cursor: pointer; font-weight: normal;">
-                                    <input type="checkbox" x-model="docTypes" value="calendar" style="margin-right: 4px;">
-                                    <span>Calendar</span>
-                                </label>
-                                <label style="display: flex; align-items: center; cursor: pointer; font-weight: normal;">
-                                    <input type="checkbox" x-model="docTypes" value="contact" style="margin-right: 4px;">
-                                    <span>Contacts</span>
-                                </label>
-                                <label style="display: flex; align-items: center; cursor: pointer; font-weight: normal;">
-                                    <input type="checkbox" x-model="docTypes" value="deck_card" style="margin-right: 4px;">
-                                    <span>Deck Cards</span>
-                                </label>
-                                <label style="display: flex; align-items: center; cursor: pointer; font-weight: normal;">
-                                    <input type="checkbox" x-model="docTypes" value="news_item" style="margin-right: 4px;">
-                                    <span>News</span>
-                                </label>
-                            </div>
-                        </div>
-
-                        <div class="viz-control-group">
-                            <label>Score Threshold</label>
-                            <input type="number" x-model.number="scoreThreshold" min="0" max="1" step="any" />
-                        </div>
-
-                        <div class="viz-control-group">
-                            <label>Result Limit</label>
-                            <input type="number" x-model.number="limit" min="1" max="1000" />
-                        </div>
-
-                        <div class="viz-control-group">
-                            <label>Display Options</label>
-                            <label style="display: flex; align-items: center; cursor: pointer; font-weight: normal; margin-top: 4px;">
-                                <input type="checkbox" x-model="showQueryPoint" @change="updatePlot()" style="margin-right: 6px;">
-                                <span>Show Query Point</span>
-                            </label>
-                        </div>
-                    </div>
-                </div>
-            </form>
-        </div>
-
-        <!-- Plot -->
-        <div class="viz-card viz-card-plot">
-            <div id="viz-plot-container">
-                <div x-show="loading" class="viz-loading-overlay" x-transition.opacity.duration.200ms>
-                    Executing search and computing PCA projection...
-                </div>
-                <div id="viz-plot" x-show="!loading" x-transition.opacity.duration.200ms></div>
-            </div>
-        </div>
-
-        <!-- Results -->
-        <div class="viz-card" style="flex: 0 0 auto;">
-            <h3 style="margin-top: 0;">Search Results (<span x-text="loading ? '...' : results.length"></span>)</h3>
-
-        <div x-show="loading" class="viz-loading" x-transition.opacity.duration.200ms>
-            Loading results...
-        </div>
-
-        <div x-show="!loading && results.length === 0" class="viz-no-results" x-transition.opacity.duration.200ms>
-            No results found. Try a different query or adjust your search parameters.
-        </div>
-
-        <template x-if="!loading && results.length > 0">
-            <div x-transition.opacity.duration.200ms>
-                <template x-for="result in results" :key="`${result.doc_type}_${result.id}_${result.chunk_start_offset || 0}`">
-                    <div style="padding: 12px; border-bottom: 1px solid #eee;">
-                        <a :href="getNextcloudUrl(result)" target="_blank" style="font-weight: 500; color: #0066cc; text-decoration: none;">
-                            <span x-text="result.title"></span>
-                        </a>
-                        <div style="font-size: 14px; color: #666; margin-top: 4px;"
-                             x-text="result.excerpt.length > 200 ? result.excerpt.substring(0, 200) + '...' : result.excerpt"></div>
-                        <div style="font-size: 12px; color: #999; margin-top: 4px;">
-                            Raw Score: <span x-text="result.original_score.toFixed(3)"></span>
-                            (<span x-text="(result.score * 100).toFixed(0)"></span>% relative) |
-                            Type: <span x-text="result.doc_type"></span>
-                        </div>
-
-                        <!-- Show Chunk button (only if chunk position is available) -->
-                        <template x-if="hasChunkPosition(result)">
-                            <button
-                                class="chunk-toggle-btn"
-                                @click="toggleChunk(result)"
-                                x-text="isChunkExpanded(`${result.doc_type}_${result.id}_${result.chunk_start_offset || 0}`) ? 'Hide Chunk' : 'Show Chunk'"
-                            ></button>
-                        </template>
-
-                        <!-- Chunk context (expanded inline) -->
-                        <template x-if="isChunkExpanded(`${result.doc_type}_${result.id}_${result.chunk_start_offset || 0}`)">
-                            <div class="chunk-context" x-transition.opacity.duration.200ms>
-                                <template x-if="chunkLoading[`${result.doc_type}_${result.id}_${result.chunk_start_offset || 0}`]">
-                                    <div style="color: #666; font-style: italic;">Loading chunk...</div>
-                                </template>
-                                <template x-if="!chunkLoading[`${result.doc_type}_${result.id}_${result.chunk_start_offset || 0}`]">
-                                    <div>
-                                        <!-- Highlighted page image for PDFs -->
-                                        <template x-if="expandedChunks[`${result.doc_type}_${result.id}_${result.chunk_start_offset || 0}`]?.highlighted_page_image">
-                                            <div class="chunk-image-container">
-                                                <div class="chunk-image-header">
-                                                    <span>Page <span x-text="expandedChunks[`${result.doc_type}_${result.id}_${result.chunk_start_offset || 0}`]?.page_number"></span></span>
-                                                </div>
-                                                <img
-                                                    :src="'data:image/png;base64,' + expandedChunks[`${result.doc_type}_${result.id}_${result.chunk_start_offset || 0}`]?.highlighted_page_image"
-                                                    :alt="'Page ' + expandedChunks[`${result.doc_type}_${result.id}_${result.chunk_start_offset || 0}`]?.page_number"
-                                                    class="chunk-highlighted-image"
-                                                />
-                                            </div>
-                                        </template>
-                                        <!-- Text context -->
-                                        <template x-if="expandedChunks[`${result.doc_type}_${result.id}_${result.chunk_start_offset || 0}`]?.has_more_before">
-                                            <span class="chunk-ellipsis">...</span>
-                                        </template>
-                                        <span class="chunk-text" x-text="expandedChunks[`${result.doc_type}_${result.id}_${result.chunk_start_offset || 0}`]?.before_context"></span><span class="chunk-matched" x-text="expandedChunks[`${result.doc_type}_${result.id}_${result.chunk_start_offset || 0}`]?.chunk_text"></span><span class="chunk-text" x-text="expandedChunks[`${result.doc_type}_${result.id}_${result.chunk_start_offset || 0}`]?.after_context"></span><template x-if="expandedChunks[`${result.doc_type}_${result.id}_${result.chunk_start_offset || 0}`]?.has_more_after">
-                                            <span class="chunk-ellipsis">...</span>
-                                        </template>
-                                    </div>
-                                </template>
-                            </div>
-                        </template>
-                    </div>
-                </template>
-            </div>
-        </template>
-        </div><!-- Search Results -->
-    </div><!-- .viz-layout -->
-</div><!-- x-data="vizApp()" -->
@@ -1,392 +0,0 @@
-{% extends "base.html" %}
-
-{% block title %}Welcome - Nextcloud MCP Server{% endblock %}
-
-{% block extra_head %}
-    <!-- Alpine.js for interactive elements -->
-    <script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>
-{% endblock %}
-
-{% block extra_styles %}
-    /* Welcome page specific styles */
-    .hero-section {
-        background: linear-gradient(135deg, var(--color-primary-element) 0%, #0082c9 100%);
-        color: white;
-        padding: 60px 24px;
-        margin: -24px -24px 40px -24px;
-        border-radius: 0 0 var(--border-radius-large) var(--border-radius-large);
-        text-align: center;
-    }
-
-    .hero-section h1 {
-        color: white;
-        font-size: 36px;
-        margin: 0 0 16px 0;
-        font-weight: 600;
-    }
-
-    .hero-section p {
-        font-size: 18px;
-        opacity: 0.95;
-        max-width: 700px;
-        margin: 0 auto;
-        line-height: 1.6;
-    }
-
-    .feature-grid {
-        display: grid;
-        grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
-        gap: 24px;
-        margin: 32px 0;
-    }
-
-    .feature-card {
-        background: var(--color-main-background);
-        border: 2px solid var(--color-border);
-        border-radius: var(--border-radius-large);
-        padding: 24px;
-        transition: all 0.2s;
-        cursor: pointer;
-        text-decoration: none;
-        color: inherit;
-        display: block;
-    }
-
-    .feature-card:hover {
-        border-color: var(--color-primary-element);
-        box-shadow: 0 4px 12px rgba(0, 103, 158, 0.15);
-        transform: translateY(-2px);
-    }
-
-    .feature-card h3 {
-        color: var(--color-primary-element);
-        font-size: 20px;
-        margin: 12px 0 8px 0;
-        font-weight: 600;
-        display: flex;
-        align-items: center;
-        gap: 12px;
-    }
-
-    .feature-card p {
-        color: var(--color-text-maxcontrast);
-        font-size: 14px;
-        line-height: 1.6;
-        margin: 8px 0 0 0;
-    }
-
-    .feature-icon {
-        width: 48px;
-        height: 48px;
-        background: var(--color-primary-element-light);
-        border-radius: var(--border-radius);
-        display: flex;
-        align-items: center;
-        justify-content: center;
-        margin-bottom: 8px;
-    }
-
-    .feature-icon svg {
-        width: 28px;
-        height: 28px;
-        fill: var(--color-primary-element);
-    }
-
-    .info-section {
-        background: var(--color-background-hover);
-        border-radius: var(--border-radius-large);
-        padding: 32px;
-        margin: 32px 0;
-    }
-
-    .info-section h2 {
-        color: var(--color-main-text);
-        font-size: 24px;
-        margin: 0 0 16px 0;
-        border: none;
-        padding: 0;
-    }
-
-    .info-section p {
-        color: var(--color-text-maxcontrast);
-        line-height: 1.7;
-        margin: 12px 0;
-    }
-
-    .info-section ul {
-        margin: 12px 0;
-        padding-left: 24px;
-    }
-
-    .info-section li {
-        color: var(--color-text-maxcontrast);
-        line-height: 1.7;
-        margin: 8px 0;
-    }
-
-    .info-section code {
-        background: var(--color-main-background);
-        padding: 2px 8px;
-        border-radius: var(--border-radius);
-        font-size: 13px;
-    }
-
-    .auth-status {
-        background: var(--color-primary-element-light);
-        border-left: 4px solid var(--color-primary-element);
-        padding: 16px 20px;
-        margin: 24px 0;
-        border-radius: var(--border-radius);
-        display: flex;
-        align-items: center;
-        gap: 12px;
-    }
-
-    .auth-status svg {
-        width: 24px;
-        height: 24px;
-        fill: var(--color-primary-element);
-        flex-shrink: 0;
-    }
-
-    .auth-status-text {
-        flex: 1;
-    }
-
-    .auth-status-text strong {
-        display: block;
-        color: var(--color-main-text);
-        font-size: 14px;
-        margin-bottom: 4px;
-    }
-
-    .auth-status-text span {
-        color: var(--color-text-maxcontrast);
-        font-size: 13px;
-    }
-{% endblock %}
-
-{% block content %}
-<div class="app-content-wrapper">
-    <!-- Main Content Area -->
-    <main id="app-content">
-        <div class="page-content">
-            <!-- Hero Section -->
-            <div class="hero-section">
-                <h1>Welcome to Nextcloud MCP Server</h1>
-                <p>
-                    Interactive user interface for semantic search and document retrieval.
-                    Test queries, visualize results, and explore your Nextcloud content using RAG workflows.
-                </p>
-            </div>
-
-            <!-- Authentication Status -->
-            <div class="auth-status">
-                <svg viewBox="0 0 24 24">
-                    <path d="M12,4A4,4 0 0,1 16,8A4,4 0 0,1 12,12A4,4 0 0,1 8,8A4,4 0 0,1 12,4M12,14C16.42,14 20,15.79 20,18V20H4V18C4,15.79 7.58,14 12,14Z" />
-                </svg>
-                <div class="auth-status-text">
-                    <strong>Authenticated as: {{ username }}</strong>
-                    <span>Authentication mode: <code>{{ auth_mode }}</code></span>
-                </div>
-            </div>
-
-            {% if vector_sync_enabled %}
-            <!-- Vector Sync Enabled Content -->
-            <div class="info-section">
-                <h2>About Semantic Search</h2>
-                <p>
-                    This interface provides access to <strong>semantic search</strong> capabilities powered by vector embeddings.
-                    Unlike traditional keyword search, semantic search understands the <em>meaning</em> of your queries and finds
-                    conceptually similar content across your Nextcloud apps.
-                </p>
-                <p>
-                    <strong>How it works:</strong>
-                </p>
-                <ul>
-                    <li>Documents from Notes, Calendar, Files, Contacts, and Deck are indexed into a vector database</li>
-                    <li>Each document chunk is converted to a 768-dimensional vector embedding that captures semantic meaning</li>
-                    <li>Queries are also converted to embeddings and matched against document vectors using similarity search</li>
-                    <li>Results can be retrieved using pure semantic search or hybrid BM25 search combining keywords and semantics</li>
-                </ul>
-            </div>
-
-            <div class="info-section">
-                <h2>RAG Workflow Integration</h2>
-                <p>
-                    This UI allows you to <strong>test the same queries that Large Language Models (LLMs) would use</strong> in a
-                    Retrieval-Augmented Generation (RAG) workflow. When an AI assistant needs to answer questions about your data:
-                </p>
-                <ul>
-                    <li><strong>Step 1:</strong> The assistant converts your question into a search query</li>
-                    <li><strong>Step 2:</strong> The MCP server retrieves relevant document chunks using semantic search</li>
-                    <li><strong>Step 3:</strong> Retrieved context is passed to the LLM to generate an informed answer</li>
-                </ul>
-
-                <!-- RAG Workflow Diagram -->
-                <div style="background: var(--color-main-background); border: 2px solid var(--color-primary-element); border-radius: var(--border-radius-large); padding: 24px; margin: 24px 0; font-family: 'SFMono-Regular', 'Consolas', 'Liberation Mono', 'Menlo', monospace; font-size: 13px; line-height: 1.8; overflow-x: auto;">
-                    <div style="text-align: center; font-weight: 600; margin-bottom: 16px; color: var(--color-primary-element); font-size: 14px;">
-                        MCP Sampling RAG Workflow
-                    </div>
-                    <pre style="margin: 0; color: var(--color-main-text);">
-┌─────────────────┐
-│   <strong>MCP Client</strong>   │  User asks: "What are health benefits of coffee?"
-│  (Claude Code)  │
-└────────┬────────┘
-         │ (1) User question
-         ↓
-┌────────────────────────────────────────────────────────────────────────┐
-│                      <strong>Nextcloud MCP Server</strong>                          │
-│  ┌──────────────────────────────────────────────────────────────────┐  │
-│  │ <strong>nc_semantic_search_answer</strong> Tool (MCP Sampling-enabled)      │  │
-│  │                                                                  │  │
-│  │  (2) Semantic Search                                             │  │
-│  │  ┌────────────────────────────────────────────────────────┐     │  │
-│  │  │ Query: "health benefits of coffee"                     │     │  │
-│  │  │ → Convert to 768D vector embedding                     │     │  │
-│  │  │ → Search Qdrant (BM25 Hybrid + RRF fusion)             │     │  │
-│  │  │ → Retrieve top 5 relevant document chunks              │     │  │
-│  │  └────────────────────────────────────────────────────────┘     │  │
-│  │                                                                  │  │
-│  │  (3) Construct Prompt with Context                               │  │
-│  │  ┌────────────────────────────────────────────────────────┐     │  │
-│  │  │ "What are health benefits of coffee?                   │     │  │
-│  │  │                                                         │     │  │
-│  │  │  Documents:                                             │     │  │
-│  │  │  - [MED-2155] Effects of habitual coffee consumption...│     │  │
-│  │  │  - [MED-1646] Beverage consumption guidance...         │     │  │
-│  │  │  - [MED-1627] Coffee and depression risk...            │     │  │
-│  │  │  ...                                                    │     │  │
-│  │  │                                                         │     │  │
-│  │  │  Provide answer with citations."                        │     │  │
-│  │  └────────────────────────────────────────────────────────┘     │  │
-│  │                                                                  │  │
-│  │  (4) MCP Sampling Request                                        │  │
-│  │  ─────────────────────────────────────────────────────────────> │  │
-│  └──────────────────────────────────────────────────────────────────┘  │
-└────────────────────────────────────────────────────────────────────────┘
-         │
-         │ Sampling request with prompt + context
-         ↓
-┌─────────────────┐
-│   <strong>MCP Client</strong>   │  (5) Client's LLM generates answer using retrieved context
-│    (Claude)     │      → "Coffee consumption (2-3 cups/day) is associated with
-└────────┬────────┘         reduced risk of type 2 diabetes, cardiovascular disease,
-         │                  and improved liver health (Document 1, 2)..."
-         │
-         │ (6) Answer with citations
-         ↓
-┌─────────────────┐
-│      User       │  Receives comprehensive answer with source citations
-└─────────────────┘</pre>
-                </div>
-
-                <p style="margin-top: 16px;">
-                    <strong>Key Point:</strong> The MCP server retrieves context but doesn't generate answers itself.
-                    Through <strong>MCP sampling</strong>, it requests the client's LLM to generate responses, giving users
-                    full control over which model is used and ensuring all processing happens client-side.
-                </p>
-
-                <p>
-                    By using this interface, you can preview search results, understand relevance scores, and verify
-                    that the system retrieves the right information before it reaches the LLM.
-                </p>
-            </div>
-
-            <!-- Feature Cards -->
-            <h2>Available Features</h2>
-            <div class="feature-grid">
-                <a href="/app/user-info" class="feature-card">
-                    <div class="feature-icon">
-                        <svg viewBox="0 0 24 24">
-                            <path d="M12,4A4,4 0 0,1 16,8A4,4 0 0,1 12,12A4,4 0 0,1 8,8A4,4 0 0,1 12,4M12,14C16.42,14 20,15.79 20,18V20H4V18C4,15.79 7.58,14 12,14Z" />
-                        </svg>
-                    </div>
-                    <h3>User Information</h3>
-                    <p>
-                        View your authentication details, session information, and IdP profile.
-                        Manage background access permissions.
-                    </p>
-                </a>
-
-                <a href="/app/user-info#vector-sync" class="feature-card">
-                    <div class="feature-icon">
-                        <svg viewBox="0 0 24 24">
-                            <path d="M12,18A6,6 0 0,1 6,12C6,11 6.25,10.03 6.7,9.2L5.24,7.74C4.46,8.97 4,10.43 4,12A8,8 0 0,0 12,20V23L16,19L12,15M12,4V1L8,5L12,9V6A6,6 0 0,1 18,12C18,13 17.75,13.97 17.3,14.8L18.76,16.26C19.54,15.03 20,13.57 20,12A8,8 0 0,0 12,4Z" />
-                        </svg>
-                    </div>
-                    <h3>Vector Sync Status</h3>
-                    <p>
-                        Monitor real-time indexing progress with metrics for indexed documents, pending queue,
-                        and synchronization status.
-                    </p>
-                </a>
-
-                <a href="/app/user-info#vector-viz" class="feature-card">
-                    <div class="feature-icon">
-                        <svg viewBox="0 0 24 24">
-                            <path d="M22,21H2V3H4V19H6V10H10V19H12V6H16V19H18V14H22V21Z" />
-                        </svg>
-                    </div>
-                    <h3>Vector Visualization</h3>
-                    <p>
-                        Interactive search interface with 2D PCA visualization. Compare algorithms,
-                        view relevance scores, and explore matched document chunks.
-                    </p>
-                </a>
-            </div>
-
-            {% else %}
-            <!-- Vector Sync Disabled Content -->
-            <div class="warning">
-                <h3 style="margin-top: 0;">Vector Sync is Disabled</h3>
-                <p>
-                    Semantic search and vector visualization features are currently disabled.
-                    To enable these features, set <code>VECTOR_SYNC_ENABLED=true</code> in your environment configuration.
-                </p>
-                <p style="margin-bottom: 0;">
-                    <strong>Learn more:</strong>
-                    <a href="https://github.com/YOUR_REPO/docs/configuration.md" target="_blank" style="color: inherit; text-decoration: underline;">
-                        Configuration Guide
-                    </a>
-                </p>
-            </div>
-
-            <!-- Limited Feature Card -->
-            <h2>Available Features</h2>
-            <div class="feature-grid">
-                <a href="/app/user-info" class="feature-card">
-                    <div class="feature-icon">
-                        <svg viewBox="0 0 24 24">
-                            <path d="M12,4A4,4 0 0,1 16,8A4,4 0 0,1 12,12A4,4 0 0,1 8,8A4,4 0 0,1 12,4M12,14C16.42,14 20,15.79 20,18V20H4V18C4,15.79 7.58,14 12,14Z" />
-                        </svg>
-                    </div>
-                    <h3>User Information</h3>
-                    <p>
-                        View your authentication details, session information, and IdP profile.
-                        Manage background access permissions.
-                    </p>
-                </a>
-            </div>
-            {% endif %}
-
-            <!-- Documentation Section -->
-            <div class="info-section" style="margin-top: 40px;">
-                <h2>Documentation</h2>
-                <p>
-                    For detailed information about configuration, authentication modes, and advanced features,
-                    please refer to the project documentation:
-                </p>
-                <ul>
-                    <li><a href="https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/installation.md" target="_blank">Installation Guide</a></li>
-                    <li><a href="https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/configuration.md" target="_blank">Configuration Options</a></li>
-                    <li><a href="https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/authentication.md" target="_blank">Authentication Modes</a></li>
-                    {% if vector_sync_enabled %}
-                    <li><a href="https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/user-guide/vector-sync-ui.md" target="_blank">Vector Sync UI Guide</a></li>
-                    {% endif %}
-                </ul>
-            </div>
-        </div>
-    </main>
-</div>
-{% endblock %}
@@ -14,13 +14,14 @@ The Token Broker provides:
 - Session vs background token separation (RFC 8693)
 """

+import asyncio
 import logging
 from datetime import datetime, timedelta, timezone
 from typing import Dict, Optional, Tuple

-import anyio
 import httpx
 import jwt
+from cryptography.fernet import Fernet

 from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
 from nextcloud_mcp_server.auth.token_exchange import exchange_token_for_delegation
@@ -42,7 +43,7 @@ class TokenCache:
        self._cache: Dict[str, Tuple[str, datetime]] = {}
        self._ttl = timedelta(seconds=ttl_seconds)
        self._early_refresh = timedelta(seconds=early_refresh_seconds)
-        self._lock = anyio.Lock()
+        self._lock = asyncio.Lock()

    async def get(self, user_id: str) -> Optional[str]:
        """Get cached token if valid."""
@@ -103,8 +104,7 @@ class TokenBrokerService:
        storage: RefreshTokenStorage,
        oidc_discovery_url: str,
        nextcloud_host: str,
-        client_id: str,
-        client_secret: str,
+        encryption_key: str,
        cache_ttl: int = 300,
        cache_early_refresh: int = 30,
    ):
@@ -112,25 +112,23 @@ class TokenBrokerService:
        Initialize the Token Broker Service.

        Args:
-            storage: Database storage for refresh tokens (handles encryption internally)
+            storage: Database storage for refresh tokens
            oidc_discovery_url: OIDC provider discovery URL
            nextcloud_host: Nextcloud server URL
-            client_id: OAuth client ID for token operations
-            client_secret: OAuth client secret for token operations
+            encryption_key: Fernet key for token encryption
            cache_ttl: Cache TTL in seconds (default: 5 minutes)
            cache_early_refresh: Early refresh threshold in seconds (default: 30 seconds)
        """
        self.storage = storage
        self.oidc_discovery_url = oidc_discovery_url
        self.nextcloud_host = nextcloud_host
-        self.client_id = client_id
-        self.client_secret = client_secret
+        self.fernet = Fernet(
+            encryption_key.encode()
+            if isinstance(encryption_key, str)
+            else encryption_key
+        )
        self.cache = TokenCache(cache_ttl, cache_early_refresh)
        self._oidc_config = None
-
-        # Per-user locks for token refresh operations (prevents race conditions)
-        self._user_refresh_locks: dict[str, anyio.Lock] = {}
-        self._locks_lock = anyio.Lock()  # Protects the locks dict itself
        self._http_client = None

    async def _get_http_client(self) -> httpx.AsyncClient:
@@ -141,24 +139,6 @@ class TokenBrokerService:
            )
        return self._http_client

-    async def _get_user_refresh_lock(self, user_id: str) -> anyio.Lock:
-        """
-        Get or create a lock for a specific user's refresh operations.
-
-        This prevents race conditions when multiple concurrent requests
-        attempt to refresh the same user's token simultaneously.
-
-        Args:
-            user_id: User ID to get lock for
-
-        Returns:
-            anyio.Lock for this user's refresh operations
-        """
-        async with self._locks_lock:
-            if user_id not in self._user_refresh_locks:
-                self._user_refresh_locks[user_id] = anyio.Lock()
-            return self._user_refresh_locks[user_id]
-
    async def _get_oidc_config(self) -> dict:
        """Get OIDC configuration from discovery endpoint."""
        if self._oidc_config is None:
@@ -200,8 +180,9 @@ class TokenBrokerService:
            return None

        try:
-            # storage.get_refresh_token() returns already-decrypted token
-            refresh_token = refresh_data["refresh_token"]
+            # Decrypt refresh token
+            encrypted_token = refresh_data["refresh_token"]
+            refresh_token = self.fernet.decrypt(encrypted_token.encode()).decode()

            # Exchange refresh token for new access token
            access_token, expires_in = await self._refresh_access_token(refresh_token)
@@ -290,79 +271,41 @@ class TokenBrokerService:
        """
        # Check cache first (background tokens can be cached)
        cache_key = f"{user_id}:background:{','.join(sorted(required_scopes))}"
-        refresh_in_progress_key = f"{user_id}:refresh_in_progress"
-
        cached_token = await self.cache.get(cache_key)
        if cached_token:
            return cached_token

-        # Acquire per-user lock BEFORE refresh operation to prevent race conditions
-        refresh_lock = await self._get_user_refresh_lock(user_id)
-        async with refresh_lock:
-            # Double-check cache after acquiring lock
-            # (another thread may have refreshed while we waited)
-            cached_token = await self.cache.get(cache_key)
-            if cached_token:
-                logger.debug(
-                    f"Token found in cache after lock acquisition for user {user_id}"
-                )
-                return cached_token
+        # Get stored refresh token
+        refresh_data = await self.storage.get_refresh_token(user_id)
+        if not refresh_data:
+            logger.info(f"No refresh token found for user {user_id}")
+            return None

-            # Check if another thread is currently refreshing
-            if await self.cache.get(refresh_in_progress_key):
-                logger.debug(f"Refresh in progress for user {user_id}, waiting briefly")
-                await anyio.sleep(0.1)  # Brief wait for in-progress refresh
-                # Check cache one more time after wait
-                cached_token = await self.cache.get(cache_key)
-                if cached_token:
-                    logger.debug(
-                        f"Token refreshed by another thread for user {user_id}"
-                    )
-                    return cached_token
+        try:
+            # Decrypt refresh token
+            encrypted_token = refresh_data["refresh_token"]
+            refresh_token = self.fernet.decrypt(encrypted_token.encode()).decode()

-            # Mark refresh as in-progress
-            await self.cache.set(refresh_in_progress_key, "true", expires_in=5)
+            # Get token with specific scopes for background operation
+            access_token, expires_in = await self._refresh_access_token_with_scopes(
+                refresh_token, required_scopes
+            )

-            try:
-                # Get stored refresh token
-                refresh_data = await self.storage.get_refresh_token(user_id)
-                if not refresh_data:
-                    logger.info(f"No refresh token found for user {user_id}")
-                    return None
+            # Cache the background token
+            await self.cache.set(cache_key, access_token, expires_in)

-                # storage.get_refresh_token() returns already-decrypted token
-                refresh_token = refresh_data["refresh_token"]
+            logger.info(
+                f"Generated background token for user {user_id} with scopes: {required_scopes}"
+            )

-                # Get token with specific scopes for background operation
-                # Pass user_id to enable refresh token rotation storage
-                access_token, expires_in = await self._refresh_access_token_with_scopes(
-                    refresh_token, required_scopes, user_id=user_id
-                )
+            return access_token

-                # Cache the background token
-                await self.cache.set(cache_key, access_token, expires_in)
+        except Exception as e:
+            logger.error(f"Failed to get background token for user {user_id}: {e}")
+            await self.cache.invalidate(cache_key)
+            return None

-                logger.info(
-                    f"Generated background token for user {user_id} with scopes: {required_scopes}"
-                )
-
-                return access_token
-
-            except Exception as e:
-                logger.error(
-                    f"Failed to get background token for user {user_id}: {e}",
-                    exc_info=True,
-                )
-                await self.cache.invalidate(cache_key)
-                return None
-
-            finally:
-                # Always clear the in-progress marker
-                await self.cache.invalidate(refresh_in_progress_key)
-
-    async def _refresh_access_token(
-        self, refresh_token: str, user_id: str | None = None
-    ) -> Tuple[str, int]:
+    async def _refresh_access_token(self, refresh_token: str) -> Tuple[str, int]:
        """
        Exchange refresh token for new access token.

@@ -370,7 +313,6 @@ class TokenBrokerService:

        Args:
            refresh_token: The refresh token
-            user_id: If provided, store the rotated refresh token for this user

        Returns:
            Tuple of (access_token, expires_in_seconds)
@@ -381,13 +323,10 @@ class TokenBrokerService:
        client = await self._get_http_client()

        # Request new access token using refresh token
-        # Include client credentials as required by most OAuth servers
        data = {
            "grant_type": "refresh_token",
            "refresh_token": refresh_token,
-            "scope": "openid profile email offline_access notes:read notes:write calendar:read calendar:write",
-            "client_id": self.client_id,
-            "client_secret": self.client_secret,
+            "scope": "openid profile email notes:read notes:write calendar:read calendar:write",
        }

        response = await client.post(
@@ -406,41 +345,23 @@ class TokenBrokerService:
        access_token = token_data["access_token"]
        expires_in = token_data.get("expires_in", 3600)  # Default 1 hour

-        # Handle refresh token rotation (Nextcloud OIDC rotates on every use)
-        new_refresh_token = token_data.get("refresh_token")
-        if user_id and new_refresh_token and new_refresh_token != refresh_token:
-            # Calculate expiry as Unix timestamp (90 days from now)
-            expires_at = int(
-                (datetime.now(timezone.utc) + timedelta(days=90)).timestamp()
-            )
-            await self.storage.store_refresh_token(
-                user_id=user_id,
-                refresh_token=new_refresh_token,
-                expires_at=expires_at,
-            )
-            logger.info(f"Stored rotated refresh token for user {user_id}")
-
-        # Note: Nextcloud validates token audience on API calls - no need to pre-validate here
+        # Validate audience
+        await self._validate_token_audience(access_token, "nextcloud")

        logger.info(f"Refreshed access token (expires in {expires_in}s)")
        return access_token, expires_in

    async def _refresh_access_token_with_scopes(
-        self, refresh_token: str, required_scopes: list[str], user_id: str | None = None
+        self, refresh_token: str, required_scopes: list[str]
    ) -> Tuple[str, int]:
        """
        Exchange refresh token for new access token with specific scopes.

        This method implements scope downscoping for least privilege.

-        IMPORTANT: Nextcloud OIDC rotates refresh tokens on every use (one-time use).
-        When user_id is provided, this method stores the new refresh token returned
-        by Nextcloud to ensure subsequent refresh operations succeed.
-
        Args:
            refresh_token: The refresh token
            required_scopes: Minimal scopes needed for this operation
-            user_id: If provided, store the rotated refresh token for this user

        Returns:
            Tuple of (access_token, expires_in_seconds)
@@ -450,25 +371,16 @@ class TokenBrokerService:

        client = await self._get_http_client()

-        # Always include basic OpenID scopes + offline_access to get new refresh token
-        scopes = list(
-            set(["openid", "profile", "email", "offline_access"] + required_scopes)
-        )
+        # Always include basic OpenID scopes
+        scopes = list(set(["openid", "profile", "email"] + required_scopes))

        # Request new access token with specific scopes
-        # Include client credentials as required by most OAuth servers
        data = {
            "grant_type": "refresh_token",
            "refresh_token": refresh_token,
            "scope": " ".join(scopes),
-            "client_id": self.client_id,
-            "client_secret": self.client_secret,
        }

-        logger.info(
-            f"Token refresh request to {token_endpoint} with client_id={self.client_id[:16]}..."
-        )
-
        response = await client.post(
            token_endpoint,
            data=data,
@@ -479,29 +391,14 @@ class TokenBrokerService:
            logger.error(
                f"Token refresh with scopes failed: {response.status_code} - {response.text}"
            )
-            logger.error(f"  client_id used: {self.client_id[:16]}...")
            raise Exception(f"Token refresh failed: {response.status_code}")

        token_data = response.json()
        access_token = token_data["access_token"]
        expires_in = token_data.get("expires_in", 3600)  # Default 1 hour

-        # Handle refresh token rotation (Nextcloud OIDC rotates on every use)
-        new_refresh_token = token_data.get("refresh_token")
-        if user_id and new_refresh_token and new_refresh_token != refresh_token:
-            # Store the new refresh token for future use
-            # Calculate expiry as Unix timestamp (90 days from now)
-            expires_at = int(
-                (datetime.now(timezone.utc) + timedelta(days=90)).timestamp()
-            )
-            await self.storage.store_refresh_token(
-                user_id=user_id,
-                refresh_token=new_refresh_token,
-                expires_at=expires_at,
-            )
-            logger.info(f"Stored rotated refresh token for user {user_id}")
-
-        # Note: Nextcloud validates token audience on API calls - no need to pre-validate here
+        # Validate audience
+        await self._validate_token_audience(access_token, "nextcloud")

        logger.info(
            f"Refreshed access token with scopes {scopes} (expires in {expires_in}s)"
@@ -556,8 +453,11 @@ class TokenBrokerService:
            return False

        try:
-            # storage.get_refresh_token() returns already-decrypted token
-            current_refresh_token = refresh_data["refresh_token"]
+            # Decrypt current refresh token
+            encrypted_token = refresh_data["refresh_token"]
+            current_refresh_token = self.fernet.decrypt(
+                encrypted_token.encode()
+            ).decode()

            # Get OIDC configuration
            config = await self._get_oidc_config()
@@ -586,15 +486,13 @@ class TokenBrokerService:
            new_refresh_token = token_data.get("refresh_token")

            if new_refresh_token and new_refresh_token != current_refresh_token:
-                # storage.store_refresh_token() handles encryption internally
-                # Convert datetime to Unix timestamp (int) for database storage
-                expires_at = int(
-                    (datetime.now(timezone.utc) + timedelta(days=90)).timestamp()
-                )
+                # Encrypt and store new refresh token
+                encrypted_new = self.fernet.encrypt(new_refresh_token.encode()).decode()
                await self.storage.store_refresh_token(
                    user_id=user_id,
-                    refresh_token=new_refresh_token,
-                    expires_at=expires_at,
+                    refresh_token=encrypted_new,
+                    expires_at=datetime.now(timezone.utc)
+                    + timedelta(days=90),  # 90-day expiry
                )
                logger.info(f"Rotated master refresh token for user {user_id}")

@@ -638,8 +536,11 @@ class TokenBrokerService:
            refresh_data = await self.storage.get_refresh_token(user_id)
            if refresh_data:
                try:
-                    # storage.get_refresh_token() returns already-decrypted token
-                    refresh_token = refresh_data["refresh_token"]
+                    # Attempt to revoke at IdP
+                    encrypted_token = refresh_data["refresh_token"]
+                    refresh_token = self.fernet.decrypt(
+                        encrypted_token.encode()
+                    ).decode()
                    await self._revoke_token_at_idp(refresh_token)
                except Exception as e:
                    logger.warning(f"Failed to revoke at IdP: {e}")
@@ -117,71 +117,6 @@ class UnifiedTokenVerifier(TokenVerifier):
        # Both modes do the same validation (MCP audience only)
        return await self._verify_mcp_audience(token)

-    async def verify_token_for_management_api(self, token: str) -> AccessToken | None:
-        """
-        Verify token for management API access (ADR-018 NC PHP app integration).
-
-        This verification accepts ANY valid Nextcloud OIDC token, not just tokens
-        with MCP server audience. This is needed because:
-        - Astrolabe (NC PHP app) uses its own OAuth client with Nextcloud OIDC
-        - Tokens from Astrolabe have Astrolabe's client_id as audience
-        - MCP server's management API should accept these tokens
-
-        Security Model:
-        ~~~~~~~~~~~~~~~~
-        This relaxed audience validation is secure because:
-
-        1. **Authentication layer** (this method):
-           - Verifies token signature against Nextcloud's JWKS (cryptographic proof)
-           - Verifies token is not expired
-           - Extracts user identity from validated token claims
-
-        2. **Authorization layer** (management API endpoints):
-           - EVERY endpoint verifies: token.sub == requested_resource_owner
-           - Example: GET /users/{user_id}/session checks token_user_id == path_user_id
-           - Users can ONLY access their own resources, never another user's
-
-        3. **Attack scenario analysis**:
-           - Attacker with stolen token for App A cannot access user B's data
-           - Token's `sub` claim is cryptographically bound to a specific user
-           - Authorization layer rejects cross-user access attempts (403 Forbidden)
-
-        4. **Why audience validation isn't needed here**:
-           - Audience validation prevents token confusion attacks across services
-           - But management API authorization already gates access per-user
-           - A token valid for "astrolabe" is still bound to user X, not user Y
-
-        Args:
-            token: Bearer token to verify
-
-        Returns:
-            AccessToken if valid (regardless of audience), None otherwise
-        """
-        # Check cache first (using separate cache key to avoid mixing with MCP tokens)
-        cache_key = f"mgmt:{hashlib.sha256(token.encode()).hexdigest()}"
-        if cache_key in self._token_cache:
-            userinfo, expiry = self._token_cache[cache_key]
-            if time.time() < expiry:
-                logger.debug("Management API token found in cache")
-                oauth_token_cache_hits_total.labels(hit="true").inc()
-                username = userinfo.get("sub") or userinfo.get("preferred_username")
-                scope_string = userinfo.get("scope", "")
-                scopes = scope_string.split() if scope_string else []
-                return AccessToken(
-                    token=token,
-                    client_id=userinfo.get("client_id", ""),
-                    scopes=scopes,
-                    expires_at=int(expiry),
-                    resource=username,
-                )
-            else:
-                del self._token_cache[cache_key]
-
-        oauth_token_cache_hits_total.labels(hit="false").inc()
-
-        # Verify token without audience check
-        return await self._verify_without_audience_check(token, cache_key)
-
    async def _verify_mcp_audience(self, token: str) -> AccessToken | None:
        """
        Validate token has MCP audience.
@@ -251,78 +186,6 @@ class UnifiedTokenVerifier(TokenVerifier):
            record_oauth_token_validation(validation_method, "error")
            return None

-    async def _verify_without_audience_check(
-        self, token: str, cache_key: str
-    ) -> AccessToken | None:
-        """
-        Verify token validity without checking MCP audience or issuer.
-
-        Used for management API where tokens from Astrolabe (NC PHP app) need to
-        be accepted. These tokens are issued by Nextcloud OIDC to Astrolabe's
-        OAuth client, not MCP server's client.
-
-        What we verify:
-        - ✓ Token signature (cryptographic proof token is from Nextcloud OIDC)
-        - ✓ Token expiration (not expired)
-        - ✓ Token structure (valid JWT format)
-
-        What we skip:
-        - ✗ Audience check (token may have Astrolabe's audience, not MCP's)
-        - ✗ Issuer check (token may have internal Nextcloud URL as issuer)
-
-        Security guarantee:
-        - Authorization is enforced by management API endpoints
-        - Each endpoint verifies: token.sub == requested_resource_owner
-        - See verify_token_for_management_api() docstring for full security model
-
-        Args:
-            token: Bearer token to verify
-            cache_key: Cache key for storing validation result
-
-        Returns:
-            AccessToken if valid, None otherwise
-        """
-        validation_method = "unknown"
-        try:
-            # Attempt JWT verification first
-            # Skip issuer check for management API tokens (may have internal URL)
-            if self._is_jwt_format(token) and self.jwks_client:
-                validation_method = "jwt"
-                payload = await self._verify_jwt_signature(
-                    token, skip_issuer_check=True
-                )
-                if payload:
-                    record_oauth_token_validation("jwt", "valid")
-                else:
-                    record_oauth_token_validation("jwt", "invalid")
-                    return None
-            else:
-                # Fall back to introspection for opaque tokens
-                validation_method = "introspect"
-                payload = await self._introspect_token(token)
-                if payload:
-                    record_oauth_token_validation("introspect", "valid")
-                else:
-                    record_oauth_token_validation("introspect", "invalid")
-                    return None
-
-            # Check payload is valid
-            if not payload:
-                return None
-
-            # Skip audience validation - any valid Nextcloud token is accepted
-            logger.debug(
-                f"Management API token validated (no audience check) for user: {payload.get('sub')}"
-            )
-
-            # Cache and return the token
-            return self._create_access_token_with_cache_key(token, payload, cache_key)
-
-        except Exception as e:
-            logger.error(f"Management API token verification failed: {e}")
-            record_oauth_token_validation(validation_method, "error")
-            return None
-
    def _has_mcp_audience(self, payload: dict[str, Any]) -> bool:
        """
        Check if token has MCP audience.
@@ -367,15 +230,12 @@ class UnifiedTokenVerifier(TokenVerifier):
        """
        return "." in token and token.count(".") == 2

-    async def _verify_jwt_signature(
-        self, token: str, skip_issuer_check: bool = False
-    ) -> dict[str, Any] | None:
+    async def _verify_jwt_signature(self, token: str) -> dict[str, Any] | None:
        """
        Verify JWT token with signature validation using JWKS.

        Args:
            token: JWT token to verify
-            skip_issuer_check: If True, skip issuer validation (for management API tokens)

        Returns:
            Decoded payload if valid, None if invalid
@@ -388,22 +248,25 @@ class UnifiedTokenVerifier(TokenVerifier):

            # Verify and decode JWT
            # Note: We don't validate audience here - that's done separately based on mode
-            # Issuer validation can be skipped for management API tokens (from Astrolabe)
-            should_verify_issuer = (
-                not skip_issuer_check
-                and hasattr(self.settings, "oidc_issuer")
-                and self.settings.oidc_issuer
-            )
            payload = jwt.decode(
                token,
                signing_key.key,
                algorithms=["RS256"],
-                issuer=(self.settings.oidc_issuer if should_verify_issuer else None),
+                issuer=(
+                    self.settings.oidc_issuer
+                    if hasattr(self.settings, "oidc_issuer")
+                    else None
+                ),
                options={
                    "verify_signature": True,
                    "verify_exp": True,
                    "verify_iat": True,
-                    "verify_iss": should_verify_issuer,
+                    "verify_iss": (
+                        True
+                        if hasattr(self.settings, "oidc_issuer")
+                        and self.settings.oidc_issuer
+                        else False
+                    ),
                    "verify_aud": False,  # We handle audience validation separately
                },
            )
@@ -440,13 +303,10 @@ class UnifiedTokenVerifier(TokenVerifier):

        try:
            # Introspection requires client authentication
-            client_id = self.settings.oidc_client_id
-            client_secret = self.settings.oidc_client_secret
-            assert client_id is not None and client_secret is not None
            response = await self.http_client.post(
                self.introspection_uri,
                data={"token": token},
-                auth=(client_id, client_secret),
+                auth=(self.settings.oidc_client_id, self.settings.oidc_client_secret),
            )

            if response.status_code == 200:
@@ -495,24 +355,6 @@ class UnifiedTokenVerifier(TokenVerifier):
            token: The bearer token
            payload: Validated token payload

-        Returns:
-            AccessToken object or None if required fields missing
-        """
-        # Use default cache key (hash of token)
-        cache_key = hashlib.sha256(token.encode()).hexdigest()
-        return self._create_access_token_with_cache_key(token, payload, cache_key)
-
-    def _create_access_token_with_cache_key(
-        self, token: str, payload: dict[str, Any], cache_key: str
-    ) -> AccessToken | None:
-        """
-        Create AccessToken object from validated token payload with custom cache key.
-
-        Args:
-            token: The bearer token
-            payload: Validated token payload
-            cache_key: Key to use for caching (allows separate caches for MCP vs management API)
-
        Returns:
            AccessToken object or None if required fields missing
        """
@@ -537,13 +379,14 @@ class UnifiedTokenVerifier(TokenVerifier):
            logger.warning("No 'exp' claim in token, using default TTL")
            exp = int(time.time() + self.cache_ttl)

-        # Cache the result with the provided key
+        # Cache the result
+        token_hash = hashlib.sha256(token.encode()).hexdigest()
        userinfo = {
            "sub": username,
            "scope": scope_string,
            **{k: v for k, v in payload.items() if k not in ["sub", "scope"]},
        }
-        self._token_cache[cache_key] = (userinfo, exp)
+        self._token_cache[token_hash] = (userinfo, exp)

        return AccessToken(
            token=token,
--- a/Show More
+++ b/Show More