bump: version 0.57.62 → 0.57.63

Merge pull request #431 from cbcoutinho/renovate/actions-setup-python-6.x
chore(deps): update actions/setup-python action to v6
2026-02-18 14:31:35 +00:00 · 2026-02-18 15:31:19 +01:00 · 2026-02-18 11:38:32 +00:00 · 2026-02-18 11:38:32 +00:00 · 2026-02-18 12:38:11 +01:00 · 2026-02-18 11:15:45 +00:00
205 changed files with 12109 additions and 31848 deletions
@@ -1,89 +0,0 @@
-name: Build and Publish Astrolabe App Release
-
-on:
-  push:
-    tags:
-      - 'astrolabe-v*'
-
-env:
-  APP_NAME: astrolabe
-  APP_DIR: third_party/astrolabe
-
-jobs:
-  build-and-publish:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
-
-      - name: Get version from tag
-        id: tag
-        run: |
-          echo "TAG=${GITHUB_REF#refs/tags/astrolabe-v}" >> $GITHUB_OUTPUT
-
-      - name: Validate version in info.xml matches tag
-        working-directory: ${{ env.APP_DIR }}
-        run: |
-          INFO_VERSION=$(sed -n 's/.*<version>\(.*\)<\/version>.*/\1/p' appinfo/info.xml | tr -d '\t')
-          if [ "$INFO_VERSION" != "${{ steps.tag.outputs.TAG }}" ]; then
-            echo "Version mismatch: info.xml has $INFO_VERSION but tag is ${{ steps.tag.outputs.TAG }}"
-            exit 1
-          fi
-          echo "Version validated: $INFO_VERSION"
-
-      - name: Setup Node
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
-        with:
-          node-version: 22
-
-      - name: Setup PHP
-        uses: shivammathur/setup-php@44454db4f0199b8b9685a5d763dc37cbf79108e1 # v2
-        with:
-          php-version: 8.1
-          coverage: none
-
-      - name: Checkout Nextcloud server (for signing)
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
-        with:
-          repository: nextcloud/server
-          ref: stable30
-          path: server
-
-      - name: Install dependencies and build
-        working-directory: ${{ env.APP_DIR }}
-        run: |
-          composer install --no-dev --optimize-autoloader
-          npm ci
-          npm run build
-
-      - name: Setup signing certificate
-        run: |
-          mkdir -p $HOME/.nextcloud/certificates
-          echo "${{ secrets.APP_PRIVATE_KEY }}" > $HOME/.nextcloud/certificates/${{ env.APP_NAME }}.key
-          echo "${{ secrets.APP_PUBLIC_CRT }}" > $HOME/.nextcloud/certificates/${{ env.APP_NAME }}.crt
-
-      - name: Build app store package
-        working-directory: ${{ env.APP_DIR }}
-        run: make appstore server_dir=${{ github.workspace }}/server
-
-      - name: Create GitHub release and attach tarball
-        uses: svenstaro/upload-release-action@6b7fa9f267e90b50a19fef07b3596790bb941741 # v2
-        with:
-          repo_token: ${{ secrets.GITHUB_TOKEN }}
-          file: ${{ env.APP_DIR }}/build/artifacts/${{ env.APP_NAME }}.tar.gz
-          asset_name: ${{ env.APP_NAME }}-${{ steps.tag.outputs.TAG }}.tar.gz
-          tag: ${{ github.ref }}
-          release_name: Astrolabe ${{ steps.tag.outputs.TAG }}
-          prerelease: ${{ contains(steps.tag.outputs.TAG, '-alpha') || contains(steps.tag.outputs.TAG, '-beta') || contains(steps.tag.outputs.TAG, '-rc') }}
-
-      - name: Upload to Nextcloud App Store
-        uses: R0Wi/nextcloud-appstore-push-action@9244bb5445776688cfe90fa1903ea8dff95b0c28 # v1.0.4
-        with:
-          app_name: ${{ env.APP_NAME }}
-          appstore_token: ${{ secrets.APPSTORE_TOKEN }}
-          download_url: ${{ github.server_url }}/${{ github.repository }}/releases/download/${{ github.ref_name }}/${{ env.APP_NAME }}-${{ steps.tag.outputs.TAG }}.tar.gz
-          app_private_key: ${{ secrets.APP_PRIVATE_KEY }}
-          nightly: ${{ contains(steps.tag.outputs.TAG, '-alpha') || contains(steps.tag.outputs.TAG, '-beta') || contains(steps.tag.outputs.TAG, '-rc') }}
@@ -1,275 +0,0 @@
-# Consolidated CI workflow for Astroglobe Nextcloud app
-#
-# Runs on PRs that modify the astroglobe directory
-# Based on Nextcloud app skeleton workflows
-#
-# SPDX-FileCopyrightText: 2025 Nextcloud MCP Server contributors
-# SPDX-License-Identifier: MIT
-
-name: Astroglobe CI
-
-on:
-  pull_request:
-    paths:
-      - 'third_party/astroglobe/**'
-      - '.github/workflows/astroglobe-ci.yml'
-
-permissions:
-  contents: read
-
-concurrency:
-  group: astroglobe-ci-${{ github.head_ref || github.run_id }}
-  cancel-in-progress: true
-
-jobs:
-  changes:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      pull-requests: read
-    outputs:
-      frontend: ${{ steps.changes.outputs.frontend }}
-      php: ${{ steps.changes.outputs.php }}
-    steps:
-      - uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
-        id: changes
-        continue-on-error: true
-        with:
-          filters: |
-            frontend:
-              - 'third_party/astroglobe/src/**'
-              - 'third_party/astroglobe/package.json'
-              - 'third_party/astroglobe/package-lock.json'
-              - 'third_party/astroglobe/vite.config.js'
-              - 'third_party/astroglobe/**/*.js'
-              - 'third_party/astroglobe/**/*.ts'
-              - 'third_party/astroglobe/**/*.vue'
-            php:
-              - 'third_party/astroglobe/lib/**'
-              - 'third_party/astroglobe/appinfo/**'
-              - 'third_party/astroglobe/composer.json'
-              - 'third_party/astroglobe/psalm.xml'
-
-  # Node.js build and lint
-  node-build:
-    runs-on: ubuntu-latest
-    needs: changes
-    if: needs.changes.outputs.frontend != 'false'
-    name: Node.js build
-    defaults:
-      run:
-        working-directory: third_party/astroglobe
-    steps:
-      - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-
-      - name: Read package.json node and npm engines version
-        uses: skjnldsv/read-package-engines-version-actions@06d6baf7d8f41934ab630e97d9e6c0bc9c9ac5e4 # v3
-        id: versions
-        with:
-          path: third_party/astroglobe
-          fallbackNode: '^20'
-          fallbackNpm: '^10'
-
-      - name: Set up node ${{ steps.versions.outputs.nodeVersion }}
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
-        with:
-          node-version: ${{ steps.versions.outputs.nodeVersion }}
-
-      - name: Set up npm ${{ steps.versions.outputs.npmVersion }}
-        run: npm i -g 'npm@${{ steps.versions.outputs.npmVersion }}'
-
-      - name: Install dependencies & build
-        env:
-          CYPRESS_INSTALL_BINARY: 0
-          PUPPETEER_SKIP_DOWNLOAD: true
-        run: |
-          npm ci
-          npm run build --if-present
-
-      - name: Check webpack build changes
-        run: |
-          bash -c "[[ ! \"`git status --porcelain `\" ]] || (echo 'Please recompile and commit the assets' && exit 1)"
-
-  # ESLint
-  eslint:
-    runs-on: ubuntu-latest
-    needs: changes
-    if: needs.changes.outputs.frontend != 'false'
-    name: ESLint
-    defaults:
-      run:
-        working-directory: third_party/astroglobe
-    steps:
-      - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-
-      - name: Read package.json node and npm engines version
-        uses: skjnldsv/read-package-engines-version-actions@06d6baf7d8f41934ab630e97d9e6c0bc9c9ac5e4 # v3
-        id: versions
-        with:
-          path: third_party/astroglobe
-          fallbackNode: '^20'
-          fallbackNpm: '^10'
-
-      - name: Set up node ${{ steps.versions.outputs.nodeVersion }}
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
-        with:
-          node-version: ${{ steps.versions.outputs.nodeVersion }}
-
-      - name: Set up npm ${{ steps.versions.outputs.npmVersion }}
-        run: npm i -g 'npm@${{ steps.versions.outputs.npmVersion }}'
-
-      - name: Install dependencies
-        env:
-          CYPRESS_INSTALL_BINARY: 0
-          PUPPETEER_SKIP_DOWNLOAD: true
-        run: npm ci
-
-      - name: Lint
-        run: npm run lint
-
-  # Stylelint
-  stylelint:
-    runs-on: ubuntu-latest
-    needs: changes
-    if: needs.changes.outputs.frontend != 'false'
-    name: Stylelint
-    defaults:
-      run:
-        working-directory: third_party/astroglobe
-    steps:
-      - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-
-      - name: Read package.json node and npm engines version
-        uses: skjnldsv/read-package-engines-version-actions@06d6baf7d8f41934ab630e97d9e6c0bc9c9ac5e4 # v3
-        id: versions
-        with:
-          path: third_party/astroglobe
-          fallbackNode: '^20'
-          fallbackNpm: '^10'
-
-      - name: Set up node ${{ steps.versions.outputs.nodeVersion }}
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
-        with:
-          node-version: ${{ steps.versions.outputs.nodeVersion }}
-
-      - name: Set up npm ${{ steps.versions.outputs.npmVersion }}
-        run: npm i -g 'npm@${{ steps.versions.outputs.npmVersion }}'
-
-      - name: Install dependencies
-        env:
-          CYPRESS_INSTALL_BINARY: 0
-          PUPPETEER_SKIP_DOWNLOAD: true
-        run: npm ci
-
-      - name: Lint
-        run: npm run stylelint
-
-  # PHP Code Style
-  php-cs:
-    runs-on: ubuntu-latest
-    needs: changes
-    if: needs.changes.outputs.php != 'false'
-    name: PHP CS Fixer
-    defaults:
-      run:
-        working-directory: third_party/astroglobe
-    steps:
-      - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-
-      - name: Get php version
-        id: versions
-        uses: icewind1991/nextcloud-version-matrix@58becf3b4bb6dc6cef677b15e2fd8e7d48c0908f # v1.3.1
-        with:
-          filename: third_party/astroglobe/appinfo/info.xml
-
-      - name: Set up php${{ steps.versions.outputs.php-min }}
-        uses: shivammathur/setup-php@cf4cade2721270509d5b1c766ab3549210a39a2a # v2.33.0
-        with:
-          php-version: ${{ steps.versions.outputs.php-min }}
-          extensions: bz2, ctype, curl, dom, fileinfo, gd, iconv, intl, json, libxml, mbstring, openssl, pcntl, posix, session, simplexml, xmlreader, xmlwriter, zip, zlib, sqlite, pdo_sqlite
-          coverage: none
-          ini-file: development
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Install dependencies
-        run: |
-          composer remove nextcloud/ocp --dev || true
-          composer i
-
-      - name: Lint
-        run: composer run cs:check || ( echo 'Please run `composer run cs:fix` to format your code' && exit 1 )
-
-  # Psalm Static Analysis
-  psalm:
-    runs-on: ubuntu-latest
-    needs: changes
-    if: needs.changes.outputs.php != 'false'
-    name: Psalm
-    defaults:
-      run:
-        working-directory: third_party/astroglobe
-    steps:
-      - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-
-      - name: Get php version
-        id: versions
-        uses: icewind1991/nextcloud-version-matrix@58becf3b4bb6dc6cef677b15e2fd8e7d48c0908f # v1.3.1
-        with:
-          filename: third_party/astroglobe/appinfo/info.xml
-
-      - name: Set up php${{ steps.versions.outputs.php-min }}
-        uses: shivammathur/setup-php@cf4cade2721270509d5b1c766ab3549210a39a2a # v2.33.0
-        with:
-          php-version: ${{ steps.versions.outputs.php-min }}
-          extensions: bz2, ctype, curl, dom, fileinfo, gd, iconv, intl, json, libxml, mbstring, openssl, pcntl, posix, session, simplexml, xmlreader, xmlwriter, zip, zlib, sqlite, pdo_sqlite
-          coverage: none
-          ini-file: development
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Install dependencies
-        run: |
-          composer remove nextcloud/ocp --dev || true
-          composer i
-
-      - name: Get OCP version matrix
-        id: ocp-versions
-        uses: icewind1991/nextcloud-version-matrix@58becf3b4bb6dc6cef677b15e2fd8e7d48c0908f # v1.3.1
-        with:
-          filename: third_party/astroglobe/appinfo/info.xml
-
-      - name: Install OCP for static analysis
-        run: |
-          # Get first OCP version from matrix
-          OCP_VERSION=$(echo '${{ steps.ocp-versions.outputs.ocp-matrix }}' | jq -r '.include[0]."ocp-version"')
-          composer require --dev "nextcloud/ocp:$OCP_VERSION" --ignore-platform-reqs --with-dependencies
-
-      - name: Run Psalm
-        run: composer run psalm -- --threads=1 --monochrome --no-progress --output-format=github
-
-  # Summary job
-  summary:
-    permissions:
-      contents: none
-    runs-on: ubuntu-latest
-    needs: [changes, node-build, eslint, stylelint, php-cs, psalm]
-    if: always()
-    name: astroglobe-ci-summary
-    steps:
-      - name: Summary status
-        run: |
-          if ${{ needs.changes.outputs.frontend != 'false' && (needs.node-build.result != 'success' || needs.eslint.result != 'success' || needs.stylelint.result != 'success') }}; then
-            echo "Frontend checks failed"
-            exit 1
-          fi
-          if ${{ needs.changes.outputs.php != 'false' && (needs.php-cs.result != 'success' || needs.psalm.result != 'success') }}; then
-            echo "PHP checks failed"
-            exit 1
-          fi
-          echo "All checks passed"
@@ -15,13 +15,13 @@ jobs:
      packages: write
    steps:
      - name: Check out
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          fetch-depth: 0
          token: "${{ secrets.PERSONAL_ACCESS_TOKEN }}"

      - name: Set up Python
-        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
        with:
          python-version: '3.11'

@@ -71,7 +71,7 @@ jobs:
            fi
          }

-          # Bump MCP server (default - all commits except helm/astrolabe scopes)
+          # Bump MCP server (default - all commits except helm scope)
          echo "Checking MCP server for version bump..."

          # Get the most recent MCP tag
@@ -83,33 +83,36 @@ jobs:
            commit_range="${last_mcp_tag}..HEAD"
          fi

-          # Count conventional commits that are NOT scoped to helm or astrolabe
+          # 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; } | { grep -v "(astrolabe)" || true; } | wc -l)
+            { 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)
+          # 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
-            echo "Bumping Helm chart version..."
-            ./scripts/bump-helm.sh
-            BUMPED_COMPONENTS="$BUMPED_COMPONENTS helm"
+            HELM_HAS_COMMITS=true
          fi

-          # Bump Astrolabe (scope: astrolabe)
-          echo "Checking Astrolabe for version bump..."
-          if has_commits_since_tag "astrolabe-v" "(feat|fix|docs|refactor|perf|test|build|ci|chore)\(astrolabe\)(!)?:"; then
-            echo "Bumping Astrolabe version..."
-            ./scripts/bump-astrolabe.sh
-            BUMPED_COMPONENTS="$BUMPED_COMPONENTS astrolabe"
+          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
@@ -147,10 +150,6 @@ jobs:
                  tag=$(git tag --sort=-creatordate | grep -E '^nextcloud-mcp-server-' | head -n 1)
                  echo "- **Helm Chart**: \`$tag\`" >> $GITHUB_STEP_SUMMARY
                  ;;
-                astrolabe)
-                  tag=$(git tag --sort=-creatordate | grep -E '^astrolabe-v' | head -n 1)
-                  echo "- **Astrolabe**: \`$tag\`" >> $GITHUB_STEP_SUMMARY
-                  ;;
              esac
            done

@@ -27,15 +27,16 @@ jobs:

    steps:
      - name: Checkout repository
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          fetch-depth: 1

      - name: Run Claude Code Review
        id: claude-review
-        uses: anthropics/claude-code-action@d7b6d50442a89f005016e778bf825a72ef582525 # v1
+        uses: anthropics/claude-code-action@2f8ba26a219c06cfb0f468eef8d97055fa814f97 # v1.0.53
        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 }}
@@ -26,13 +26,13 @@ jobs:
      actions: read # Required for Claude to read CI results on PRs
    steps:
      - name: Checkout repository
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          fetch-depth: 1

      - name: Run Claude Code
        id: claude
-        uses: anthropics/claude-code-action@d7b6d50442a89f005016e778bf825a72ef582525 # v1
+        uses: anthropics/claude-code-action@2f8ba26a219c06cfb0f468eef8d97055fa814f97 # v1.0.53
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

@@ -13,11 +13,11 @@ jobs:
      packages: write
    steps:
      - name: Checkout repository
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

      - name: Docker meta
        id: meta
-        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5
+        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5.10.0
        with:
          # list of Docker images to use as base name for tags
          images: |
@@ -34,18 +34,18 @@ 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@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0

      - name: Log in to GitHub Container Registry
        if: github.event_name != 'pull_request'
-        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and push Docker image
-        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6
+        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
        with:
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
@@ -4,6 +4,7 @@ on:
  push:
    tags:
      - v*
+      - nextcloud-mcp-server-*

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

@@ -24,10 +24,10 @@ jobs:
      models: read

    steps:
-      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

      - name: Run docker compose with vector sync
-        uses: hoverkraft-tech/compose-action@248470ecc5ed40d8ed3d4480d8260d77179ef579 # v2.4.2
+        uses: hoverkraft-tech/compose-action@4894d2492015c1774ee5a13a95b1072093087ec3 # v2.5.0
        with:
          compose-file: |
            ./docker-compose.yml
@@ -42,7 +42,7 @@ jobs:
          VECTOR_SYNC_SCAN_INTERVAL: "5"

      - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@681c641aba71e4a1c380be3ab5e12ad51f415867 # v7.1.6
+        uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0

      - name: Wait for Nextcloud to be ready
        run: |
@@ -97,7 +97,7 @@ jobs:

      - name: Upload test results
        if: always()
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
        with:
          name: rag-evaluation-results
          path: |
@@ -18,9 +18,9 @@ jobs:
      contents: read
    steps:
      - name: Checkout
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
      - name: Install uv
-        uses: astral-sh/setup-uv@681c641aba71e4a1c380be3ab5e12ad51f415867 # v7.1.6
+        uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
      - 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@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
      - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@681c641aba71e4a1c380be3ab5e12ad51f415867 # v7.1.6
+        uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
      - 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@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        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@44454db4f0199b8b9685a5d763dc37cbf79108e1 # 2.36.0
        with:
          php-version: 8.4
          coverage: none
@@ -48,32 +48,15 @@ jobs:
      ###### Required to build OIDC App ######


-      ###### Required to build Astrolabe App ######
-
-      - name: Set up Node.js for Astrolabe
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
-        with:
-          node-version: '20'
-
-      - name: Build Astrolabe app
-        run: |
-          cd third_party/astrolabe
-          composer install --no-dev --optimize-autoloader
-          npm ci
-          npm run build
-
-      ###### Required to build Astrolabe App ######
-
-
      - name: Run docker compose
-        uses: hoverkraft-tech/compose-action@248470ecc5ed40d8ed3d4480d8260d77179ef579 # v2.4.2
+        uses: hoverkraft-tech/compose-action@4894d2492015c1774ee5a13a95b1072093087ec3 # v2.5.0
        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@681c641aba71e4a1c380be3ab5e12ad51f415867 # v7.1.6
+        uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0

      - name: Install Playwright dependencies
        run: |
@@ -4,3 +4,6 @@
 [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
@@ -5,6 +5,223 @@ 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.64.1 (2026-02-18)
+
+### Fix
+
+- **deps**: update dependency mcp to >=1.26,<1.27
+
+## v0.64.0 (2026-02-16)
+
+### Feat
+
+- add self-signed SSL certificate support for Nextcloud connections
+
+### Fix
+
+- add type: ignore for caldav ssl_verify_cert parameter
+- convert CA bundle path to ssl.SSLContext to avoid httpx deprecation warning
+
+## v0.63.5 (2026-02-16)
+
+### Refactor
+
+- remove stale astrolabe references from commitizen config
+- extract Astrolabe to separate repository
+
+## 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
@@ -239,6 +239,25 @@ 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
@@ -264,6 +283,40 @@ 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:**
@@ -2,7 +2,7 @@

 ## Version Management

-This monorepo uses commitizen for version management with **independent versioning** for three components:
+This monorepo uses commitizen for version management with **independent versioning** for two components:

 ### Components

@@ -10,7 +10,8 @@ This monorepo uses commitizen for version management with **independent versioni
 |-----------|-------|--------------|-------------|
 | 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` |
-| Astrolabe App | `astrolabe` | `./scripts/bump-astrolabe.sh` | `astrolabe-v0.2.0` |
+
+> **Note:** The Astrolabe Nextcloud app has been moved to its own repository at [cbcoutinho/astrolabe](https://github.com/cbcoutinho/astrolabe).

 ### Commit Message Format

@@ -24,10 +25,6 @@ fix(mcp): resolve authentication bug
 # Helm chart changes
 feat(helm): add resource limits
 docs(helm): update values documentation
-
-# Astrolabe app changes
-feat(astrolabe): add dark mode toggle
-fix(astrolabe): resolve search UI bug
 ```

 **Unscoped commits** default to the MCP server:
@@ -40,7 +37,6 @@ feat: add new feature  # → MCP server (v0.54.0)
 #### 1. Make Changes with Scoped Commits

 ```bash
-git commit -m "feat(astrolabe): add dark mode toggle"
 git commit -m "feat(helm): add ingress annotations"
 git commit -m "feat(mcp): add calendar sync"
 ```
@@ -58,10 +54,6 @@ git commit -m "feat(mcp): add calendar sync"
 # → Creates tag: nextcloud-mcp-server-0.54.0
 # → Updates: Chart.yaml:version

-# Bump Astrolabe (reads commits with scope=astrolabe)
-./scripts/bump-astrolabe.sh
-# → Creates tag: astrolabe-v0.2.0
-# → Updates: info.xml, package.json
 ```

 #### 3. Push Tags
@@ -76,7 +68,6 @@ 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
- **Astrolabe**: `third_party/astrolabe/CHANGELOG.md` - includes `feat(astrolabe):` only

 ### Manual Version Bumps

@@ -101,7 +92,6 @@ uv run cz --config .cz.toml bump --increment MINOR

 - **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)
- **Astrolabe**: Follows PEP 440, `major_version_zero = true` (0.x.x for alpha/beta)

 ### Chart.yaml Version vs appVersion

@@ -1,6 +1,6 @@
-FROM docker.io/library/python:3.12-slim-trixie@sha256:fa48eefe2146644c2308b909d6bb7651a768178f84fc9550dcd495e4d6d84d01
+FROM docker.io/library/python:3.12-slim-trixie@sha256:9e01bf1ae5db7649a236da7be1e94ffbbbdd7a93f867dd0d8d5720d9e1f89fab

-COPY --from=ghcr.io/astral-sh/uv:0.9.18@sha256:5713fa8217f92b80223bc83aac7db36ec80a84437dbc0d04bbc659cae030d8c9 /uv /uvx /bin/
+COPY --from=ghcr.io/astral-sh/uv:0.10.4@sha256:4cac394b6b72846f8a85a7a0e577c6d61d4e17fe2ccee65d9451a8b3c9efb4ac /uv /uvx /bin/

 # Install dependencies
 # 1. git (required for caldav dependency from git)
@@ -12,12 +12,12 @@
 # - Per-session app password authentication
 # - Multi-user support via Smithery session config

-FROM docker.io/library/python:3.12-slim-trixie@sha256:fa48eefe2146644c2308b909d6bb7651a768178f84fc9550dcd495e4d6d84d01
+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.9.18@sha256:5713fa8217f92b80223bc83aac7db36ec80a84437dbc0d04bbc659cae030d8c9 /uv /uvx /bin/
+COPY --from=ghcr.io/astral-sh/uv:0.10.4@sha256:4cac394b6b72846f8a85a7a0e577c6d61d4e17fe2ccee65d9451a8b3c9efb4ac /uv /uvx /bin/

 # Install dependencies
 # 1. git (required for caldav dependency from git)
@@ -99,7 +99,7 @@ Want to see another Nextcloud app supported? [Open an issue](https://github.com/

 ### Authentication Modes

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

 **Single-User Mode (BasicAuth):**
 - One set of credentials shared by all MCP clients
@@ -113,6 +113,12 @@ The server supports two 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
@@ -4,8 +4,8 @@ set -euox pipefail

 php /var/www/html/occ config:system:set trusted_domains 2 --value=host.docker.internal

-# Set overwrite settings for URL generation (needed for OIDC discovery to return correct URLs)
-# These ensure that URLs generated by Nextcloud include the correct host:port
-php /var/www/html/occ config:system:set overwritehost --value="localhost:8080"
-php /var/www/html/occ config:system:set overwriteprotocol --value="http"
+# 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"
@@ -2,35 +2,17 @@

 set -euox pipefail

-echo "Installing Astrolabe app for testing..."
+echo "Installing Astrolabe app from app store..."

-# Check if development astrolabe app is mounted at /opt/apps/astrolabe
-if [ -d /opt/apps/astrolabe ]; then
-    echo "Development astrolabe app found at /opt/apps/astrolabe"
-
-    # Remove any existing astrolabe app in custom_apps (from app store or old symlink)
-    if [ -e /var/www/html/custom_apps/astrolabe ]; then
-        echo "Removing existing astrolabe in custom_apps..."
-        rm -rf /var/www/html/custom_apps/astrolabe
-    fi
-
-    # Create symlink from custom_apps to the mounted development version
-    # Per Nextcloud docs: apps outside server root need symlinks in server root
-    echo "Creating symlink: custom_apps/astrolabe -> /opt/apps/astrolabe"
-    ln -sf /opt/apps/astrolabe /var/www/html/custom_apps/astrolabe
-
-    echo "Enabling astrolabe app from /opt/apps (development mode via symlink)"
-    php /var/www/html/occ app:enable astrolabe
-elif [ -d /var/www/html/custom_apps/astrolabe ]; then
+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
-    echo "astrolabe app not found, installing from app store..."
    php /var/www/html/occ app:install astrolabe
    php /var/www/html/occ app:enable astrolabe
 fi

-echo "✓ Astrolabe app installed successfully"
+echo "Astrolabe app installed successfully"
 echo ""
 echo "Note: MCP server configuration is managed dynamically during tests"
 echo "      to support testing multiple MCP server deployments."
@@ -0,0 +1,16 @@
+#!/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,6 +1,6 @@
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "0.54.0"
+version = "0.57.63"
 tag_format = "nextcloud-mcp-server-$version"
 version_scheme = "semver"
 update_changelog_on_bump = true
@@ -14,6 +14,333 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Configurable resource limits
 - Grafana dashboard annotations

+## nextcloud-mcp-server-0.57.63 (2026-02-18)
+
+## nextcloud-mcp-server-0.57.62 (2026-02-18)
+
+### Fix
+
+- **deps**: update dependency mcp to >=1.26,<1.27
+
+## nextcloud-mcp-server-0.57.61 (2026-02-18)
+
+## nextcloud-mcp-server-0.57.60 (2026-02-18)
+
+## nextcloud-mcp-server-0.57.59 (2026-02-18)
+
+## nextcloud-mcp-server-0.57.58 (2026-02-18)
+
+## nextcloud-mcp-server-0.57.57 (2026-02-18)
+
+## nextcloud-mcp-server-0.57.56 (2026-02-18)
+
+## nextcloud-mcp-server-0.57.55 (2026-02-17)
+
+## nextcloud-mcp-server-0.57.54 (2026-02-17)
+
+## nextcloud-mcp-server-0.57.53 (2026-02-17)
+
+## nextcloud-mcp-server-0.57.52 (2026-02-17)
+
+## nextcloud-mcp-server-0.57.51 (2026-02-16)
+
+### Feat
+
+- add self-signed SSL certificate support for Nextcloud connections
+
+### Fix
+
+- add type: ignore for caldav ssl_verify_cert parameter
+- convert CA bundle path to ssl.SSLContext to avoid httpx deprecation warning
+
+## nextcloud-mcp-server-0.57.50 (2026-02-16)
+
+## nextcloud-mcp-server-0.57.49 (2026-02-16)
+
+### Refactor
+
+- remove stale astrolabe references from commitizen config
+- extract Astrolabe to separate repository
+
+## nextcloud-mcp-server-0.57.48 (2026-02-15)
+
+## nextcloud-mcp-server-0.57.47 (2026-02-15)
+
+## nextcloud-mcp-server-0.57.46 (2026-02-12)
+
+## nextcloud-mcp-server-0.57.45 (2026-02-12)
+
+## nextcloud-mcp-server-0.57.44 (2026-02-11)
+
+## nextcloud-mcp-server-0.57.43 (2026-02-11)
+
+## nextcloud-mcp-server-0.57.42 (2026-02-08)
+
+### Fix
+
+- strip whitespace from category names when splitting
+- handle categories, recurrence_rule, attendees, and reminder_minutes in update_event
+
+## nextcloud-mcp-server-0.57.41 (2026-02-08)
+
+### Fix
+
+- expand recurring events in date-range queries
+
+## nextcloud-mcp-server-0.57.40 (2026-02-07)
+
+### Fix
+
+- use CalDAV time-range filter for calendar date range queries
+
+## nextcloud-mcp-server-0.57.39 (2026-02-07)
+
+## nextcloud-mcp-server-0.57.38 (2026-02-07)
+
+## nextcloud-mcp-server-0.57.37 (2026-02-06)
+
+## nextcloud-mcp-server-0.57.36 (2026-02-06)
+
+## nextcloud-mcp-server-0.57.35 (2026-02-06)
+
+## nextcloud-mcp-server-0.57.34 (2026-02-06)
+
+## nextcloud-mcp-server-0.57.33 (2026-02-06)
+
+## nextcloud-mcp-server-0.57.32 (2026-02-06)
+
+## nextcloud-mcp-server-0.57.31 (2026-02-06)
+
+## nextcloud-mcp-server-0.57.30 (2026-02-06)
+
+## nextcloud-mcp-server-0.57.29 (2026-02-04)
+
+## nextcloud-mcp-server-0.57.28 (2026-02-03)
+
+## nextcloud-mcp-server-0.57.27 (2026-02-03)
+
+### Fix
+
+- **helm**: add backward compatibility for legacy persistence configs
+
+## nextcloud-mcp-server-0.57.26 (2026-01-31)
+
+## nextcloud-mcp-server-0.57.25 (2026-01-31)
+
+## nextcloud-mcp-server-0.57.24 (2026-01-31)
+
+## nextcloud-mcp-server-0.57.23 (2026-01-30)
+
+## nextcloud-mcp-server-0.57.22 (2026-01-30)
+
+## nextcloud-mcp-server-0.57.21 (2026-01-30)
+
+## nextcloud-mcp-server-0.57.20 (2026-01-29)
+
+## nextcloud-mcp-server-0.57.19 (2026-01-28)
+
+## nextcloud-mcp-server-0.57.18 (2026-01-28)
+
+## nextcloud-mcp-server-0.57.17 (2026-01-28)
+
+## nextcloud-mcp-server-0.57.16 (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
+
+## nextcloud-mcp-server-0.57.15 (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
+
+## nextcloud-mcp-server-0.57.14 (2026-01-26)
+
+## nextcloud-mcp-server-0.57.13 (2026-01-24)
+
+## nextcloud-mcp-server-0.57.12 (2026-01-20)
+
+## nextcloud-mcp-server-0.57.11 (2026-01-20)
+
+## nextcloud-mcp-server-0.57.10 (2026-01-19)
+
+## nextcloud-mcp-server-0.57.9 (2026-01-19)
+
+## nextcloud-mcp-server-0.57.8 (2026-01-18)
+
+## nextcloud-mcp-server-0.57.7 (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
+
+## nextcloud-mcp-server-0.57.6 (2026-01-16)
+
+## nextcloud-mcp-server-0.57.5 (2026-01-16)
+
+## nextcloud-mcp-server-0.57.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
+
+## nextcloud-mcp-server-0.57.3 (2026-01-15)
+
+## nextcloud-mcp-server-0.57.2 (2026-01-15)
+
+### Fix
+
+- **astrolabe**: address review feedback for Vue 3 bindings
+- **astrolabe**: update Vue component bindings for Vue 3 compatibility
+
+## nextcloud-mcp-server-0.57.1 (2026-01-15)
+
+### Fix
+
+- **ci**: bump helm chart version when MCP appVersion changes
+- **astrolabe**: define appName and appVersion for @nextcloud/vue
+
+## nextcloud-mcp-server-0.57.0 (2026-01-15)
+
+### 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
+- **deck**: use correct endpoint for reorder_card to fix cross-stack moves
+- **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
+
+### Refactor
+
+- Use get_settings() for vector sync enabled check
+- Extract storage helper and improve PHP error handling
+
+## nextcloud-mcp-server-0.56.2 (2025-12-29)
+
+### Fix
+
+- **oauth**: Enable browser OAuth routes for Management API in hybrid mode
+
+## nextcloud-mcp-server-0.56.1 (2025-12-26)
+
+### Fix
+
+- **mcp**: Move all imports to the top of modules
+
+## nextcloud-mcp-server-0.56.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
+
+## nextcloud-mcp-server-0.55.2 (2025-12-22)
+
+### Fix
+
+- **helm**: set OIDC client env vars when using existingSecret
+
+## nextcloud-mcp-server-0.55.1 (2025-12-22)
+
+### Fix
+
+- **helm**: trigger chart release workflow on helm chart tags
+
+## nextcloud-mcp-server-0.55.0 (2025-12-22)
+
+### BREAKING CHANGE
+
+- MCP server now bumps for ANY conventional commit except
+those explicitly scoped to helm or astrolabe.
+
+### Feat
+
+- **helm**: add support for multi-user BasicAuth mode
+- **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)
+- **auth**: add multi-user BasicAuth pass-through mode
+- **astrolabe**: add dynamic MCP server configuration for testing
+- **ci**: add --increment flag to bump scripts for manual version control
+
+### Fix
+
+- **helm**: address PR #447 reviewer feedback
+- **helm**: include MCP server version bumps in changelog pattern
+- **config**: address reviewer feedback
+- **astrolabe**: screenshots in info.xml
+- **astrolabe**: screenshots in info.xml
+- **astrolabe**: Update screenshots
+- **ci**: skip existing Helm chart releases to prevent duplicate release errors
+- **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
+- **ci**: push all tags explicitly in bump workflow
+- **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
+
+### Refactor
+
+- **config**: centralize configuration validation and simplify startup
+
 ## nextcloud-mcp-server-0.54.0 (2025-12-19)

 ### Feat
@@ -4,6 +4,6 @@ dependencies:
  version: 1.16.3
 - name: ollama
  repository: https://otwld.github.io/ollama-helm
-  version: 1.36.0
-digest: sha256:7f0979ec4110ff41ebeb55bf586b41366a350cc39fe65a2da7d2da03f723fe9b
-generated: "2025-12-22T11:09:39.166328543Z"
+  version: 1.43.0
+digest: sha256:533eda3fdb4bd92cdafee49bd7b0428fc87d21b509032442c04ed645900e464a
+generated: "2026-02-16T11:16:41.257136832Z"
@@ -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.54.0
-appVersion: "0.57.0"
+version: 0.57.63
+appVersion: "0.64.1"
 keywords:
  - nextcloud
  - mcp
@@ -31,6 +31,6 @@ dependencies:
    repository: https://qdrant.github.io/qdrant-helm
    condition: qdrant.networkMode.deploySubchart
  - name: ollama
-    version: "1.36.0"
+    version: "1.43.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 issuer URL for OAuth (OAuth only, optional) | Smart default** |
+| `nextcloud.publicIssuerUrl` | Public URL for browser-accessible OAuth authorization endpoint (OAuth only, optional) | Smart default** |

 **Smart Defaults:**
 - `*mcpServerUrl`: If not set, automatically uses ingress host (if enabled) or `http://localhost:8000` (for port-forward setups)
- `**publicIssuerUrl`: If not set, automatically defaults to `nextcloud.host` (which works when both clients and MCP server access Nextcloud at the same URL)
+- `**publicIssuerUrl`: If not set, defaults to `nextcloud.host`. **Only used for authorization endpoints** that browsers must access. All server-to-server endpoints (token, JWKS, introspection, userinfo) use URLs from OIDC discovery without rewriting

 #### Authentication

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

 #### Vector Search & Semantic Capabilities (Optional)

-Enable semantic search capabilities by deploying a vector database (Qdrant) and embedding service (Ollama or OpenAI).
+Enable semantic search capabilities with BM25 hybrid search by deploying a vector database (Qdrant) and embedding service (Ollama or OpenAI).

-**Vector Sync Configuration:**
+**Semantic Search Configuration:**

 | Parameter | Description | Default |
 |-----------|-------------|---------|
-| `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` |
+| `semanticSearch.enabled` | Enable semantic search and background vector synchronization | `false` |
+| `semanticSearch.scanInterval` | Scan interval in seconds | `3600` |
+| `semanticSearch.processorWorkers` | Number of concurrent processor workers | `3` |
+| `semanticSearch.queueMaxSize` | Maximum queue size for pending documents | `10000` |

 **Document Chunking Configuration:**

@@ -427,7 +446,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
+  # publicIssuerUrl defaults to nextcloud.host (only used for browser-accessible auth endpoint)

 auth:
  mode: oauth
@@ -459,7 +478,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
+  # publicIssuerUrl will automatically default to nextcloud.host (only used for browser-accessible auth endpoint)

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

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

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

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

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

 qdrant:
@@ -689,7 +708,9 @@ 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.vectorSync.enabled }}
+{{- if .Values.semanticSearch.enabled }}

-5. Vector Search & Semantic Capabilities:
-   - Vector Sync: Enabled
-   - Scan Interval: {{ .Values.vectorSync.scanInterval }}s
-   - Processor Workers: {{ .Values.vectorSync.processorWorkers }}
+5. Semantic Search & Vector Capabilities:
+   - Semantic Search: Enabled
+   - Scan Interval: {{ .Values.semanticSearch.scanInterval }}s
+   - Processor Workers: {{ .Values.semanticSearch.processorWorkers }}
   {{- if .Values.qdrant.enabled }}
   - Qdrant: Deployed as subchart ({{ .Release.Name }}-qdrant:6333)
   {{- else }}
@@ -120,6 +120,55 @@ 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
@@ -127,6 +127,55 @@ 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
 */}}
@@ -88,8 +88,8 @@ spec:
            - name: NEXTCLOUD_PUBLIC_ISSUER_URL
              value: {{ include "nextcloud-mcp-server.publicIssuerUrl" . | quote }}
            {{- if .Values.auth.multiUserBasic.enableOfflineAccess }}
-            # Background operations with app passwords
-            - name: ENABLE_OFFLINE_ACCESS
+            # 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 }}
@@ -100,7 +100,7 @@ spec:
                  key: {{ .Values.auth.multiUserBasic.tokenEncryptionKeyKey }}
            - name: NEXTCLOUD_OIDC_SCOPES
              value: {{ .Values.auth.multiUserBasic.scopes | quote }}
-            {{- if .Values.auth.multiUserBasic.clientId }}
+            {{- 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:
@@ -122,7 +122,7 @@ spec:
              value: {{ include "nextcloud-mcp-server.publicIssuerUrl" . | quote }}
            - name: NEXTCLOUD_OIDC_SCOPES
              value: {{ .Values.auth.oauth.scopes | quote }}
-            {{- if .Values.auth.oauth.clientId }}
+            {{- if or .Values.auth.oauth.clientId .Values.auth.oauth.existingSecret }}
            - name: NEXTCLOUD_OIDC_CLIENT_ID
              valueFrom:
                secretKeyRef:
@@ -182,16 +182,16 @@ spec:
              value: {{ .Values.documentProcessing.custom.types | quote }}
            {{- end }}
            {{- end }}
-            # Vector Sync
-            - name: VECTOR_SYNC_ENABLED
-              value: {{ .Values.vectorSync.enabled | quote }}
-            {{- if .Values.vectorSync.enabled }}
+            # Semantic Search (replaces deprecated VECTOR_SYNC_ENABLED)
+            - name: ENABLE_SEMANTIC_SEARCH
+              value: {{ .Values.semanticSearch.enabled | quote }}
+            {{- if .Values.semanticSearch.enabled }}
            - name: VECTOR_SYNC_SCAN_INTERVAL
-              value: {{ .Values.vectorSync.scanInterval | quote }}
+              value: {{ .Values.semanticSearch.scanInterval | quote }}
            - name: VECTOR_SYNC_PROCESSOR_WORKERS
-              value: {{ .Values.vectorSync.processorWorkers | quote }}
+              value: {{ .Values.semanticSearch.processorWorkers | quote }}
            - name: VECTOR_SYNC_QUEUE_MAX_SIZE
-              value: {{ .Values.vectorSync.queueMaxSize | quote }}
+              value: {{ .Values.semanticSearch.queueMaxSize | quote }}
            {{- end }}
            # Document Chunking (always set, used by vector sync processor)
            - name: DOCUMENT_CHUNK_SIZE
@@ -286,14 +286,8 @@ spec:
            - name: oauth-storage
              mountPath: /app/.oauth
            {{- end }}
-            {{- if and (eq .Values.auth.mode "multi-user-basic") .Values.auth.multiUserBasic.enableOfflineAccess .Values.auth.multiUserBasic.persistence.enabled }}
-            - name: token-storage
+            - name: data-storage
              mountPath: /app/data
-            {{- end }}
-            {{- 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 }}
@@ -305,15 +299,12 @@ spec:
          persistentVolumeClaim:
            claimName: {{ include "nextcloud-mcp-server.oauthPvcName" . }}
        {{- end }}
-        {{- if and (eq .Values.auth.mode "multi-user-basic") .Values.auth.multiUserBasic.enableOfflineAccess .Values.auth.multiUserBasic.persistence.enabled }}
-        - name: token-storage
+        - name: data-storage
+        {{- if eq (include "nextcloud-mcp-server.dataStorageEnabled" .) "true" }}
          persistentVolumeClaim:
-            claimName: {{ include "nextcloud-mcp-server.multiUserBasicPvcName" . }}
-        {{- end }}
-        {{- if and (eq .Values.qdrant.mode "persistent") .Values.qdrant.localPersistence.enabled }}
-        - name: qdrant-data
-          persistentVolumeClaim:
-            claimName: {{ include "nextcloud-mcp-server.qdrantPvcName" . }}
+            claimName: {{ include "nextcloud-mcp-server.dataStoragePvcName" . }}
+        {{- else }}
+          emptyDir: {}
        {{- end }}
        {{- with .Values.volumes }}
        {{- toYaml . | nindent 8 }}
@@ -16,38 +16,34 @@ spec:
      storage: {{ .Values.auth.oauth.persistence.size }}
 {{- end }}
 ---
-{{- if and (eq .Values.auth.mode "multi-user-basic") .Values.auth.multiUserBasic.enableOfflineAccess .Values.auth.multiUserBasic.persistence.enabled (not .Values.auth.multiUserBasic.persistence.existingClaim) }}
+{{- if and (eq (include "nextcloud-mcp-server.dataStorageEnabled" .) "true") (not .Values.dataStorage.existingClaim) }}
+{{- $legacyMultiUserBasic := eq (include "nextcloud-mcp-server.legacyMultiUserBasicPersistence" .) "true" }}
+{{- $legacyQdrant := eq (include "nextcloud-mcp-server.legacyQdrantPersistence" .) "true" }}
+{{- $accessMode := .Values.dataStorage.accessMode }}
+{{- $storageClass := .Values.dataStorage.storageClass }}
+{{- $size := .Values.dataStorage.size }}
+{{- if $legacyMultiUserBasic }}
+{{- $accessMode = .Values.auth.multiUserBasic.persistence.accessMode }}
+{{- $storageClass = .Values.auth.multiUserBasic.persistence.storageClass }}
+{{- $size = .Values.auth.multiUserBasic.persistence.size }}
+{{- else if $legacyQdrant }}
+{{- $accessMode = .Values.qdrant.localPersistence.accessMode }}
+{{- $storageClass = .Values.qdrant.localPersistence.storageClass }}
+{{- $size = .Values.qdrant.localPersistence.size }}
+{{- end }}
 apiVersion: v1
 kind: PersistentVolumeClaim
 metadata:
-  name: {{ include "nextcloud-mcp-server.fullname" . }}-token-storage
+  name: {{ include "nextcloud-mcp-server.fullname" . }}-data-storage
  labels:
    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
 spec:
  accessModes:
-    - {{ .Values.auth.multiUserBasic.persistence.accessMode }}
-  {{- if .Values.auth.multiUserBasic.persistence.storageClass }}
-  storageClassName: {{ .Values.auth.multiUserBasic.persistence.storageClass }}
+    - {{ $accessMode }}
+  {{- if $storageClass }}
+  storageClassName: {{ $storageClass }}
  {{- end }}
  resources:
    requests:
-      storage: {{ .Values.auth.multiUserBasic.persistence.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" . }}-qdrant-data
-  labels:
-    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
-spec:
-  accessModes:
-    - {{ .Values.qdrant.localPersistence.accessMode }}
-  {{- if .Values.qdrant.localPersistence.storageClass }}
-  storageClassName: {{ .Values.qdrant.localPersistence.storageClass }}
-  {{- end }}
-  resources:
-    requests:
-      storage: {{ .Values.qdrant.localPersistence.size }}
+      storage: {{ $size }}
 {{- end }}
@@ -26,9 +26,16 @@ nextcloud:
  # Example: https://mcp.example.com
  mcpServerUrl: ""

-  # 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
+  # Public issuer URL for browser-accessible OAuth authorization endpoints (OAuth mode only)
+  # ONLY used to make authorization endpoints accessible to users' browsers
+  # All server-to-server communication (token endpoint, JWKS, introspection, userinfo)
+  # uses URLs from OIDC discovery without any rewriting
+  #
+  # Use case: When MCP server accesses Nextcloud at one URL but browsers need a different
+  # public URL for OAuth login (e.g., server uses internal DNS, browsers use public domain)
+  #
+  # If not specified, defaults to nextcloud.host (works when MCP server and browsers
+  # both access Nextcloud at the same URL)
  # Example: https://cloud.example.com
  publicIssuerUrl: ""

@@ -132,6 +139,27 @@ 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)
@@ -358,10 +386,11 @@ extraEnvFrom: []
 # - secretRef:
 #     name: my-secret

-# Vector Sync Configuration
-# Background synchronization of Nextcloud content into vector database for semantic search
-vectorSync:
-  # Enable background vector synchronization
+# Semantic Search Configuration
+# Enable semantic search with BM25 hybrid search and background synchronization
+# of Nextcloud content into vector database
+semanticSearch:
+  # Enable semantic search and background vector synchronization
  enabled: false
  # Scan interval in seconds (how often to check for changes)
  scanInterval: 3600
@@ -372,7 +401,7 @@ vectorSync:

 # Document Chunking Configuration
 # Controls how documents are split into chunks before embedding
-# Only relevant when vectorSync.enabled is true
+# Only relevant when semanticSearch.enabled is true
 documentChunking:
  # Number of words per chunk (default: 512)
  # Smaller chunks (256-384): Better for precise searches, more chunks to store
@@ -3,11 +3,13 @@ services:
  # https://hub.docker.com/_/mariadb
  db:
    # Note: Check the recommend version here: https://docs.nextcloud.com/server/latest/admin_manual/installation/system_requirements.html#server
-    image: docker.io/library/mariadb:lts@sha256:1cac8492bd78b1ec693238dc600be173397efd7b55eabc725abc281dc855b482
+    image: docker.io/library/mariadb:lts@sha256:8164f184d16c30e2f159e30518113667b796306dff0fe558876ab1ff521a682f
    restart: always
    command: --transaction-isolation=READ-COMMITTED
    volumes:
      - db:/var/lib/mysql
+    ports:
+      - 127.0.0.1:3306:3306
    environment:
      - MYSQL_ROOT_PASSWORD=password
      - MYSQL_PASSWORD=password
@@ -17,14 +19,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:6cbef353e480a8a6e7f10ec545f13d7d3fa85a212cdcc5ffaf5a1c818b9d3798
+    image: docker.io/library/redis:alpine@sha256:fd83658b0e40e2164617d262f13c02ca9ee9e1e6b276fd2fa06617e09bd5c780
    restart: always

  app:
-    image: docker.io/library/nextcloud:32.0.3@sha256:53231a9fb9233af2c15bfe70fc03ebe639fd53243fa42a9369884b1e0008deae
+    image: docker.io/library/nextcloud:32.0.6@sha256:0e1084cc59df77bec7d6bb29d9ac6939da8372512237a9c51f74ff0a970524f2
    restart: always
    ports:
-      - 0.0.0.0:8080:80
+      - 127.0.0.1:8080:80
    depends_on:
      - redis
      - db
@@ -35,7 +37,6 @@ services:
      # Mount OIDC development directory outside /var/www/html to avoid rsync conflicts
      # The post-installation hook will register /opt/apps as an additional app directory
      #- ./third_party:/opt/apps:ro
-      - ./third_party/astrolabe:/opt/apps/astrolabe:ro
    environment:
      - NEXTCLOUD_TRUSTED_DOMAINS=app
      - NEXTCLOUD_ADMIN_USER=admin
@@ -52,14 +53,14 @@ services:
      retries: 30

  recipes:
-    image: docker.io/library/nginx:alpine@sha256:052b75ab72f690f33debaa51c7e08d9b969a0447a133eb2b99cc905d9188cb2b
+    image: docker.io/library/nginx:alpine@sha256:5878d06ae4c83d73285438255f705bb3f9a736f41cd24876ed25bb33faf76c7d
    restart: always
    volumes:
      - ./tests/fixtures/test_recipe.html:/usr/share/nginx/html/test_recipe.html:ro
      - ./tests/fixtures/nginx.conf:/etc/nginx/nginx.conf:ro

  unstructured:
-    image: downloads.unstructured.io/unstructured-io/unstructured-api:latest@sha256:54282d3a25f33fd6cf69bc45b3d37770f213593f58b6dfe5e85fe546376b2807
+    image: downloads.unstructured.io/unstructured-io/unstructured-api:latest@sha256:3b9280eb9aa53d76a8f4a2465400ae747774d4bfd71dd73d603353b0b55c435d
    restart: always
    ports:
      - 127.0.0.1:8002:8000
@@ -86,8 +87,8 @@ services:
      - NEXTCLOUD_PASSWORD=admin
      - NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8080

-      # Vector sync configuration (ADR-007)
-      #- VECTOR_SYNC_ENABLED=true
+      # Semantic search configuration (ADR-007, ADR-021)
+      #- ENABLE_SEMANTIC_SEARCH=true
      - VECTOR_SYNC_SCAN_INTERVAL=60
      - VECTOR_SYNC_PROCESSOR_WORKERS=1

@@ -138,14 +139,13 @@ services:
      - NEXTCLOUD_MCP_SERVER_URL=http://localhost:8003
      - NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8080
      - ENABLE_MULTI_USER_BASIC_AUTH=true
-      - ENABLE_OFFLINE_ACCESS=true
      - ENABLE_BACKGROUND_OPERATIONS=true

      # Token storage (required for middleware initialization)
      - TOKEN_ENCRYPTION_KEY=ESF1BvEQdGYsCluwMx9Cxvw3uh5pFowPH7Rg_nIliyo=
      - TOKEN_STORAGE_DB=/app/data/tokens.db

-      - VECTOR_SYNC_ENABLED=true
+      - ENABLE_SEMANTIC_SEARCH=true
      - VECTOR_SYNC_SCAN_INTERVAL=60
      - VECTOR_SYNC_PROCESSOR_WORKERS=1

@@ -178,7 +178,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_OFFLINE_ACCESS=true
+      - ENABLE_BACKGROUND_OPERATIONS=true
      - TOKEN_ENCRYPTION_KEY=ESF1BvEQdGYsCluwMx9Cxvw3uh5pFowPH7Rg_nIliyo=
      - TOKEN_STORAGE_DB=/app/data/tokens.db

@@ -186,8 +186,8 @@ services:
      # Tokens must contain BOTH MCP and Nextcloud audiences
      # No token exchange needed - tokens work for both MCP auth and Nextcloud APIs

-      # Vector sync configuration (ADR-007)
-      - VECTOR_SYNC_ENABLED=true
+      # Semantic search configuration (ADR-007, ADR-021)
+      - ENABLE_SEMANTIC_SEARCH=true
      - VECTOR_SYNC_SCAN_INTERVAL=60
      - VECTOR_SYNC_PROCESSOR_WORKERS=1

@@ -207,7 +207,7 @@ services:
      - oauth-tokens:/app/data

  keycloak:
-    image: quay.io/keycloak/keycloak:26.4.7@sha256:9409c59bdfb65dbffa20b11e6f18b8abb9281d480c7ca402f51ed3d5977e6007
+    image: quay.io/keycloak/keycloak:26.5.3@sha256:5a236ae4dd8ece77490115bace15a11a4d15e9cbcf58a490b95a7da2cd71d32a
    command:
      - "start-dev"
      - "--import-realm"
@@ -255,7 +255,7 @@ services:
      - NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8888/realms/nextcloud-mcp

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

@@ -288,13 +288,13 @@ services:
      - 127.0.0.1:8081:8081
    environment:
      - SMITHERY_DEPLOYMENT=true
-      - VECTOR_SYNC_ENABLED=false
+      - ENABLE_SEMANTIC_SEARCH=false
      - PORT=8081
    profiles:
      - smithery

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

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

 The server automatically detects the authentication mode:
@@ -171,6 +171,58 @@ NEXTCLOUD_PASSWORD=your_app_password_or_password

 ---

+## SSL/TLS Configuration (Optional)
+
+If your Nextcloud instance uses a self-signed certificate or a private CA (common with reverse proxies like Traefik or Caddy), the MCP server will reject the connection by default. Use these settings to configure certificate verification.
+
+### Custom CA Bundle (Recommended)
+
+Point the server at your CA certificate file:
+
+```dotenv
+NEXTCLOUD_CA_BUNDLE=/etc/ssl/certs/my-ca.pem
+```
+
+With Docker, mount the certificate as a read-only volume:
+
+```bash
+docker run \
+  -v /path/to/my-ca.pem:/etc/ssl/certs/my-ca.pem:ro \
+  -e NEXTCLOUD_CA_BUNDLE=/etc/ssl/certs/my-ca.pem \
+  -e NEXTCLOUD_HOST=https://nextcloud.local \
+  --env-file .env \
+  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
+```
+
+### Disable Verification (Development Only)
+
+> [!WARNING]
+> Disabling TLS verification is insecure. Only use this for local development or testing.
+
+```dotenv
+NEXTCLOUD_VERIFY_SSL=false
+```
+
+### Environment Variables Reference
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `NEXTCLOUD_VERIFY_SSL` | ⚠️ Optional | `true` | Set to `false` to disable TLS certificate verification |
+| `NEXTCLOUD_CA_BUNDLE` | ⚠️ Optional | - | Path to a PEM CA bundle file for custom certificate authorities |
+
+### Scope
+
+These settings apply to **all** outbound connections to Nextcloud and its OIDC endpoints, including:
+
+- Nextcloud API calls (Notes, Calendar, Contacts, WebDAV, etc.)
+- OIDC discovery and token endpoints
+- OAuth client registration (DCR)
+- Health checks
+
+They do **not** affect connections to internal services (Ollama, Qdrant, Unstructured) which have their own SSL configuration.
+
+---
+
 ## Semantic Search Configuration (Optional)

 **New in v0.58.0:** Simplified semantic search configuration with automatic dependency resolution.
@@ -0,0 +1,339 @@
+# 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
+```
@@ -217,6 +217,19 @@ NEXTCLOUD_PASSWORD=
 #CUSTOM_PROCESSOR_TIMEOUT=60
 #CUSTOM_PROCESSOR_TYPES=application/pdf,image/jpeg,image/png

+# ===== SSL/TLS =====
+# For Nextcloud behind reverse proxies with self-signed or private CA certificates
+#
+# Disable TLS certificate verification (insecure, development only):
+#NEXTCLOUD_VERIFY_SSL=false
+#
+# Use a custom CA bundle (path to PEM file):
+#NEXTCLOUD_CA_BUNDLE=/etc/ssl/certs/my-ca.pem
+#
+# Docker example: mount the CA bundle as a volume
+#   docker run -v /path/to/ca.pem:/etc/ssl/certs/my-ca.pem:ro \
+#     -e NEXTCLOUD_CA_BUNDLE=/etc/ssl/certs/my-ca.pem ...
+
 # ===== SECURITY & ADVANCED =====
 # Cookie security (browser UI)
 # Auto-detects from NEXTCLOUD_HOST protocol if not set
@@ -0,0 +1,50 @@
+"""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")
@@ -3,4 +3,74 @@
 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",
+]
@@ -0,0 +1,435 @@
+"""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
+
+from ..http import nextcloud_httpx_client
+
+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 nextcloud_httpx_client(
+            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 nextcloud_httpx_client(
+            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,
+        )
@@ -0,0 +1,813 @@
+"""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,
+        )
@@ -0,0 +1,309 @@
+"""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
+
+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,
+)
+
+from ..http import nextcloud_httpx_client
+
+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 nextcloud_httpx_client(
+            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 nextcloud_httpx_client(
+            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 nextcloud_httpx_client(
+            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 nextcloud_httpx_client(
+            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,3 +1,7 @@
+from __future__ import annotations
+
+import base64
+import json
 import logging
 import os
 import time
@@ -7,14 +11,15 @@ from contextlib import AsyncExitStack, asynccontextmanager
 from contextvars import ContextVar
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Optional, cast
+from urllib.parse import urlparse

+import anyio
 from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor

 if TYPE_CHECKING:
    from nextcloud_mcp_server.auth.storage import RefreshTokenStorage


-import anyio
 import click
 import httpx
 from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
@@ -42,6 +47,7 @@ from nextcloud_mcp_server.auth.unified_verifier import UnifiedTokenVerifier
 from nextcloud_mcp_server.client import NextcloudClient
 from nextcloud_mcp_server.config import (
    DeploymentMode,
+    Settings,
    get_document_processor_config,
    get_settings,
 )
@@ -52,6 +58,7 @@ from nextcloud_mcp_server.config_validators import (
 )
 from nextcloud_mcp_server.context import get_client as get_nextcloud_client
 from nextcloud_mcp_server.document_processors import get_registry
+from nextcloud_mcp_server.http import nextcloud_httpx_client
 from nextcloud_mcp_server.observability import (
    ObservabilityMiddleware,
    setup_metrics,
@@ -380,8 +387,6 @@ class BasicAuthMiddleware:

            if auth_header.startswith(b"Basic "):
                try:
-                    import base64
-
                    # Decode base64(username:password)
                    encoded = auth_header[6:]  # Skip "Basic "
                    decoded = base64.b64decode(encoded).decode("utf-8")
@@ -535,11 +540,10 @@ async def load_oauth_client_credentials(
        dcr_scopes = "openid profile email notes:read notes:write calendar:read calendar:write todo:read todo: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 news:read news:write"

        # Add offline_access scope if refresh tokens are enabled
-        enable_offline_access = os.getenv("ENABLE_OFFLINE_ACCESS", "false").lower() in (
-            "true",
-            "1",
-            "yes",
-        )
+        # Use settings.enable_offline_access which handles both ENABLE_BACKGROUND_OPERATIONS (new)
+        # and ENABLE_OFFLINE_ACCESS (deprecated) environment variables
+        dcr_settings = get_settings()
+        enable_offline_access = dcr_settings.enable_offline_access
        if enable_offline_access:
            dcr_scopes = f"{dcr_scopes} offline_access"
            logger.info("✓ offline_access scope enabled for refresh tokens")
@@ -668,6 +672,10 @@ async def setup_oauth_config():
    Returns:
        Tuple of (nextcloud_host, token_verifier, auth_settings, refresh_token_storage, oauth_client, oauth_provider, client_id, client_secret)
    """
+    # Get settings for enable_offline_access check (handles both ENABLE_BACKGROUND_OPERATIONS
+    # and ENABLE_OFFLINE_ACCESS environment variables)
+    settings = get_settings()
+
    nextcloud_host = os.getenv("NEXTCLOUD_HOST")
    if not nextcloud_host:
        raise ValueError(
@@ -683,7 +691,7 @@ async def setup_oauth_config():
    logger.info(f"Performing OIDC discovery: {discovery_url}")

    # Perform OIDC discovery
-    async with httpx.AsyncClient() as client:
+    async with nextcloud_httpx_client(follow_redirects=True) as client:
        response = await client.get(discovery_url)
        response.raise_for_status()
        discovery = response.json()
@@ -700,36 +708,6 @@ async def setup_oauth_config():
    introspection_uri = discovery.get("introspection_endpoint")
    registration_endpoint = discovery.get("registration_endpoint")

-    # Allow overriding JWKS URI (useful when running in Docker with frontendUrl)
-    # Example: frontendUrl=http://localhost:8888 but MCP server needs http://keycloak:8080
-    jwks_uri_override = os.getenv("OIDC_JWKS_URI")
-    if jwks_uri_override:
-        logger.info(f"OIDC_JWKS_URI override: {jwks_uri} → {jwks_uri_override}")
-        jwks_uri = jwks_uri_override
-
-    # Rewrite discovered endpoint URLs from public issuer to internal host
-    # This is needed when OIDC discovery returns public URLs (e.g., http://localhost:8080)
-    # but the server needs to access them via internal docker network (e.g., http://app:80)
-    from urllib.parse import urlparse
-
-    issuer_parsed = urlparse(issuer)
-    nextcloud_parsed = urlparse(nextcloud_host)
-    issuer_base = f"{issuer_parsed.scheme}://{issuer_parsed.netloc}"
-    nextcloud_base = f"{nextcloud_parsed.scheme}://{nextcloud_parsed.netloc}"
-
-    if issuer_base != nextcloud_base:
-        logger.info(f"Rewriting OIDC endpoints: {issuer_base} → {nextcloud_base}")
-
-        def rewrite_url(url: str | None) -> str | None:
-            if url and url.startswith(issuer_base):
-                return url.replace(issuer_base, nextcloud_base, 1)
-            return url
-
-        userinfo_uri = rewrite_url(userinfo_uri) or userinfo_uri
-        jwks_uri = rewrite_url(jwks_uri)
-        introspection_uri = rewrite_url(introspection_uri)
-        registration_endpoint = rewrite_url(registration_endpoint)
-
    logger.info("OIDC endpoints discovered:")
    logger.info(f"  Issuer: {issuer}")
    logger.info(f"  Userinfo: {userinfo_uri}")
@@ -756,16 +734,8 @@ async def setup_oauth_config():
    issuer_normalized = normalize_url(issuer)
    nextcloud_normalized = normalize_url(nextcloud_host)

-    # Use NEXTCLOUD_PUBLIC_ISSUER_URL for IdP detection when set
-    # This handles the case where MCP server accesses Nextcloud via internal URL (http://app:80)
-    # but the issuer in OIDC discovery is the public URL (http://localhost:8080)
-    public_issuer_for_detection = os.getenv("NEXTCLOUD_PUBLIC_ISSUER_URL")
-    if public_issuer_for_detection:
-        comparison_issuer = normalize_url(public_issuer_for_detection)
-    else:
-        comparison_issuer = nextcloud_normalized
-
-    is_external_idp = not issuer_normalized.startswith(comparison_issuer)
+    # Determine if this is an external IdP by comparing discovered issuer with Nextcloud host
+    is_external_idp = not issuer_normalized.startswith(nextcloud_normalized)

    if is_external_idp:
        oauth_provider = "external"  # Could be Keycloak, Auth0, Okta, etc.
@@ -777,34 +747,10 @@ async def setup_oauth_config():
        oauth_provider = "nextcloud"
        logger.info("✓ Detected integrated mode (Nextcloud OIDC app)")

-        # For integrated mode, rewrite OIDC endpoints to use internal URL
-        # The discovery document returns external URLs (http://localhost:8080)
-        # but the MCP server needs internal URLs (http://app:80) for backend requests
-        if jwks_uri and not os.getenv("OIDC_JWKS_URI"):
-            internal_jwks_uri = f"{nextcloud_host}/apps/oidc/jwks"
-            logger.info(
-                f"  Auto-rewriting JWKS URI for internal access: {jwks_uri} → {internal_jwks_uri}"
-            )
-            jwks_uri = internal_jwks_uri
-        if introspection_uri and not os.getenv("OIDC_INTROSPECTION_URI"):
-            internal_introspection_uri = f"{nextcloud_host}/apps/oidc/introspect"
-            logger.info(
-                f"  Auto-rewriting introspection URI for internal access: {introspection_uri} → {internal_introspection_uri}"
-            )
-            introspection_uri = internal_introspection_uri
-        if userinfo_uri:
-            internal_userinfo_uri = f"{nextcloud_host}/apps/oidc/userinfo"
-            logger.info(
-                f"  Auto-rewriting userinfo URI for internal access: {userinfo_uri} → {internal_userinfo_uri}"
-            )
-            userinfo_uri = internal_userinfo_uri
-
    # Check if offline access (refresh tokens) is enabled
-    enable_offline_access = os.getenv("ENABLE_OFFLINE_ACCESS", "false").lower() in (
-        "true",
-        "1",
-        "yes",
-    )
+    # Use settings.enable_offline_access which handles both ENABLE_BACKGROUND_OPERATIONS (new)
+    # and ENABLE_OFFLINE_ACCESS (deprecated) environment variables
+    enable_offline_access = settings.enable_offline_access

    # Initialize refresh token storage if enabled
    refresh_token_storage = None
@@ -854,21 +800,11 @@ async def setup_oauth_config():
            f"Discovery URL: {discovery_url}"
        )

-    # Handle public issuer override (for clients accessing via different URL)
-    # When clients access Nextcloud via a public URL (e.g., http://127.0.0.1:8080),
-    # but the MCP server accesses via internal URL (e.g., http://app:80),
-    # we need to use the public URL for JWT validation and client configuration
-    public_issuer = os.getenv("NEXTCLOUD_PUBLIC_ISSUER_URL")
-    if public_issuer:
-        public_issuer = public_issuer.rstrip("/")
-        logger.info(
-            f"Using public issuer URL override for JWT validation: {public_issuer}"
-        )
-        client_issuer = public_issuer
-    else:
-        client_issuer = issuer
-
    # ADR-005: Unified Token Verifier with proper audience validation
+    # Use public issuer URL for JWT validation if set (handles Docker internal/external URL mismatch)
+    # Tokens are issued with the public URL, but OIDC discovery returns internal URL
+    public_issuer_url = os.getenv("NEXTCLOUD_PUBLIC_ISSUER_URL")
+    client_issuer = public_issuer_url if public_issuer_url else issuer
    # Get MCP server URL for audience validation
    mcp_server_url = os.getenv("NEXTCLOUD_MCP_SERVER_URL", "http://localhost:8000")
    nextcloud_resource_uri = os.getenv("NEXTCLOUD_RESOURCE_URI", nextcloud_host)
@@ -885,10 +821,8 @@ async def setup_oauth_config():
            "This should be set explicitly for proper audience validation."
        )

-    # Create settings for UnifiedTokenVerifier
-    from nextcloud_mcp_server.config import get_settings
-
-    settings = get_settings()
+    # Create settings for UnifiedTokenVerifier (use same settings instance from start of function)
+    # settings is already set at the start of setup_oauth_config()
    # Override with discovered values if not set in environment
    if not settings.oidc_client_id:
        settings.oidc_client_id = client_id
@@ -1012,6 +946,166 @@ async def setup_oauth_config():
    )


+async def setup_oauth_config_for_multi_user_basic(
+    settings: Settings,
+    client_id: str,
+    client_secret: str,
+) -> tuple[UnifiedTokenVerifier, RefreshTokenStorage | None, str, str]:
+    """
+    Setup minimal OAuth configuration for multi-user BasicAuth mode.
+
+    This is a lightweight version of setup_oauth_config() that:
+    - Performs OIDC discovery to get endpoints
+    - Creates UnifiedTokenVerifier for management API token validation
+    - Creates RefreshTokenStorage for webhook token storage
+    - Skips OAuth client creation (not needed for BasicAuth background sync)
+    - Skips AuthSettings creation (not needed for BasicAuth MCP operations)
+
+    This enables hybrid authentication mode where:
+    - MCP operations use BasicAuth (stateless, simple)
+    - Management APIs use OAuth bearer tokens (secure, per-user)
+    - Background operations use OAuth refresh tokens (webhook sync)
+
+    Args:
+        settings: Application settings
+        client_id: OAuth client ID (from DCR or static config)
+        client_secret: OAuth client secret
+
+    Returns:
+        Tuple of (token_verifier, refresh_token_storage, client_id, client_secret)
+
+    Raises:
+        ValueError: If NEXTCLOUD_HOST is not set
+        httpx.HTTPError: If OIDC discovery fails
+    """
+    nextcloud_host = settings.nextcloud_host
+    if not nextcloud_host:
+        raise ValueError("NEXTCLOUD_HOST is required for OAuth infrastructure setup")
+
+    nextcloud_host = nextcloud_host.rstrip("/")
+
+    # Get OIDC discovery URL (always Nextcloud integrated mode for multi-user BasicAuth)
+    discovery_url = os.getenv(
+        "OIDC_DISCOVERY_URL",
+        f"{nextcloud_host}/.well-known/openid-configuration",
+    )
+    logger.info(
+        f"Performing OIDC discovery for multi-user BasicAuth hybrid mode: {discovery_url}"
+    )
+
+    # Perform OIDC discovery
+    try:
+        async with nextcloud_httpx_client(
+            timeout=30.0, follow_redirects=True
+        ) as http_client:
+            response = await http_client.get(discovery_url)
+            response.raise_for_status()
+            discovery = response.json()
+    except httpx.HTTPStatusError as e:
+        logger.error(
+            f"OIDC discovery failed: HTTP {e.response.status_code} from {discovery_url}"
+        )
+        raise ValueError(
+            f"OIDC discovery failed: HTTP {e.response.status_code} from {discovery_url}. "
+            "Ensure Nextcloud OIDC (user_oidc app) is installed and configured."
+        ) from e
+    except httpx.RequestError as e:
+        logger.error(f"OIDC discovery failed: {e}")
+        raise ValueError(
+            f"OIDC discovery failed: Cannot connect to {discovery_url}. Error: {e}"
+        ) from e
+    except (KeyError, ValueError) as e:
+        logger.error(
+            f"OIDC discovery failed: Invalid response from {discovery_url}: {e}"
+        )
+        raise ValueError(
+            f"OIDC discovery failed: Invalid response from {discovery_url}. "
+            "The endpoint did not return valid OIDC configuration."
+        ) from e
+
+    logger.info("✓ OIDC discovery successful (multi-user BasicAuth)")
+
+    # Extract OIDC endpoints from discovery
+    issuer = discovery["issuer"]
+    userinfo_uri = discovery["userinfo_endpoint"]
+    jwks_uri = discovery.get("jwks_uri")
+    introspection_uri = discovery.get("introspection_endpoint")
+
+    logger.info("OIDC endpoints configured for management API:")
+    logger.info(f"  Issuer: {issuer}")
+    logger.info(f"  Userinfo: {userinfo_uri}")
+    logger.info(f"  JWKS: {jwks_uri}")
+    logger.info(f"  Introspection: {introspection_uri}")
+
+    # Get MCP server URL for audience validation
+    mcp_server_url = os.getenv("NEXTCLOUD_MCP_SERVER_URL", "http://localhost:8000")
+    nextcloud_resource_uri = os.getenv("NEXTCLOUD_RESOURCE_URI", nextcloud_host)
+
+    # Use public issuer URL for JWT validation if set (handles Docker internal/external URL mismatch)
+    # Tokens are issued with the public URL, but OIDC discovery returns internal URL
+    public_issuer_url = os.getenv("NEXTCLOUD_PUBLIC_ISSUER_URL")
+    client_issuer = public_issuer_url if public_issuer_url else issuer
+
+    # Update settings with discovered values for UnifiedTokenVerifier
+    if not settings.oidc_client_id:
+        settings.oidc_client_id = client_id
+    if not settings.oidc_client_secret:
+        settings.oidc_client_secret = client_secret
+    if not settings.jwks_uri:
+        settings.jwks_uri = jwks_uri
+    if not settings.introspection_uri:
+        settings.introspection_uri = introspection_uri
+    if not settings.userinfo_uri:
+        settings.userinfo_uri = userinfo_uri
+    if not settings.oidc_issuer:
+        settings.oidc_issuer = client_issuer
+    if not settings.nextcloud_mcp_server_url:
+        settings.nextcloud_mcp_server_url = mcp_server_url
+    if not settings.nextcloud_resource_uri:
+        settings.nextcloud_resource_uri = nextcloud_resource_uri
+
+    # Create Unified Token Verifier for management API authentication
+    token_verifier = UnifiedTokenVerifier(settings)
+    logger.info("✓ Token verifier created for management API (hybrid mode)")
+
+    if introspection_uri:
+        logger.info("  Opaque token introspection enabled (RFC 7662)")
+    if jwks_uri:
+        logger.info("  JWT signature verification enabled (JWKS)")
+
+    # Initialize refresh token storage for background operations
+    refresh_token_storage = None
+    if settings.enable_offline_access:
+        try:
+            from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
+
+            encryption_key = os.getenv("TOKEN_ENCRYPTION_KEY")
+            if not encryption_key:
+                logger.warning(
+                    "ENABLE_OFFLINE_ACCESS=true but TOKEN_ENCRYPTION_KEY not set. "
+                    "Refresh tokens will NOT be stored. Generate a key with:\n"
+                    '  python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"'
+                )
+            else:
+                refresh_token_storage = RefreshTokenStorage.from_env()
+                await refresh_token_storage.initialize()
+                logger.info(
+                    "✓ Refresh token storage initialized for background operations (hybrid mode)"
+                )
+        except Exception as e:
+            logger.error(f"Failed to initialize refresh token storage: {e}")
+            logger.debug(f"Full traceback:\n{traceback.format_exc()}")
+            logger.warning(
+                "Continuing without refresh token storage - webhook management may be limited"
+            )
+
+    logger.info(
+        "OAuth infrastructure setup complete for multi-user BasicAuth hybrid mode"
+    )
+
+    return (token_verifier, refresh_token_storage, client_id, client_secret)
+
+
 def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None = None):
    # Initialize observability (logging will be configured by uvicorn)
    settings = get_settings()
@@ -1043,6 +1137,15 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
        else DeploymentMode.SELF_HOSTED
    )

+    # Log hybrid authentication status for multi-user BasicAuth with offline access
+    if mode == AuthMode.MULTI_USER_BASIC and settings.enable_offline_access:
+        logger.info(
+            "🔄 Hybrid authentication mode will be enabled:\n"
+            "  - MCP operations: BasicAuth (stateless, credentials per-request)\n"
+            "  - Management APIs: OAuth bearer tokens (secure, per-user)\n"
+            "  - Background operations: OAuth refresh tokens (webhook sync)"
+        )
+
    # Setup Prometheus metrics (always enabled by default)
    if settings.metrics_enabled:
        setup_metrics(port=settings.metrics_port)
@@ -1070,17 +1173,19 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
    # This must happen BEFORE uvicorn starts (same lifecycle point as OAuth modes)
    # to avoid async context issues
    multi_user_basic_oauth_creds: tuple[str, str] | None = None
+    multi_user_token_verifier: UnifiedTokenVerifier | None = None
+    multi_user_refresh_storage: RefreshTokenStorage | None = None

    if (
        mode == AuthMode.MULTI_USER_BASIC
        and settings.vector_sync_enabled
-        and settings.enable_offline_access
+        and settings.enable_background_operations
    ):
        print(
-            f"DEBUG: Multi-user BasicAuth mode detected, vector_sync={settings.vector_sync_enabled}, offline_access={settings.enable_offline_access}"
+            f"DEBUG: Multi-user BasicAuth mode detected, vector_sync={settings.vector_sync_enabled}, background_operations={settings.enable_background_operations}"
        )
        logger.info(
-            "Multi-user BasicAuth with vector sync - checking for OAuth credentials"
+            "Multi-user BasicAuth with vector sync - checking for OAuth/app password credentials"
        )

        # Check for static credentials first
@@ -1098,8 +1203,6 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
                "OAuth credentials not configured - attempting Dynamic Client Registration..."
            )

-            import anyio
-
            async def setup_multi_user_basic_dcr():
                """Setup DCR for multi-user BasicAuth background operations."""
                # Construct registration endpoint directly from nextcloud_host
@@ -1135,11 +1238,57 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
            # Run DCR synchronously before uvicorn starts
            multi_user_basic_oauth_creds = anyio.run(setup_multi_user_basic_dcr)

+        # Setup OAuth infrastructure for management APIs and background operations
+        # This creates the UnifiedTokenVerifier needed by management.py and
+        # RefreshTokenStorage for webhook token persistence
+        if multi_user_basic_oauth_creds:
+            sync_client_id, sync_client_secret = multi_user_basic_oauth_creds
+
+            logger.info(
+                "Setting up OAuth infrastructure for management APIs (hybrid mode)..."
+            )
+
+            try:
+                (
+                    multi_user_token_verifier,
+                    multi_user_refresh_storage,
+                    _,
+                    _,
+                ) = anyio.run(
+                    setup_oauth_config_for_multi_user_basic,
+                    settings,
+                    sync_client_id,
+                    sync_client_secret,
+                )
+                logger.info(
+                    "✓ OAuth infrastructure setup complete for multi-user BasicAuth hybrid mode"
+                )
+            except (httpx.HTTPError, ValueError, KeyError) as e:
+                # Expected errors during OAuth infrastructure setup:
+                # - httpx.HTTPError: Network issues, OIDC discovery failures
+                # - ValueError: Missing required configuration (NEXTCLOUD_HOST)
+                # - KeyError: Missing required fields in OIDC discovery response
+                logger.error(f"Failed to setup OAuth infrastructure: {e}")
+                logger.debug(f"Full traceback:\n{traceback.format_exc()}")
+                logger.warning(
+                    "Management API will be unavailable. "
+                    "Webhook management from Astrolabe admin UI will not work."
+                )
+                # Set to None to indicate failure
+                multi_user_token_verifier = None
+                multi_user_refresh_storage = None
+            except Exception as e:
+                # Unexpected error - this is a programming error, re-raise it
+                logger.error(
+                    f"Unexpected error during OAuth infrastructure setup: {e}. "
+                    "This is likely a programming error that should be fixed."
+                )
+                raise
+
    # Create MCP server based on detected mode
    if mode in (AuthMode.OAUTH_SINGLE_AUDIENCE, AuthMode.OAUTH_TOKEN_EXCHANGE):
        logger.info("Configuring MCP server for OAuth mode")
        # Asynchronously get the OAuth configuration
-        import anyio

        (
            nextcloud_host,
@@ -1275,13 +1424,9 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
    enable_token_exchange = (
        os.getenv("ENABLE_TOKEN_EXCHANGE", "false").lower() == "true"
    )
-    enable_offline_access_for_tools = os.getenv(
-        "ENABLE_OFFLINE_ACCESS", "false"
-    ).lower() in (
-        "true",
-        "1",
-        "yes",
-    )
+    # Use settings.enable_offline_access which handles both ENABLE_BACKGROUND_OPERATIONS (new)
+    # and ENABLE_OFFLINE_ACCESS (deprecated) environment variables
+    enable_offline_access_for_tools = settings.enable_offline_access
    if oauth_enabled and enable_offline_access_for_tools and not enable_token_exchange:
        logger.info("Registering OAuth provisioning tools for offline access")
        register_oauth_tools(mcp)
@@ -1410,11 +1555,14 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
            # For multi-user BasicAuth with offline access, create oauth_context for management APIs
            # This allows Astrolabe to use management APIs with OAuth bearer tokens
            if settings.enable_multi_user_basic_auth and settings.enable_offline_access:
-                # Check if we have OAuth credentials from DCR
-                if multi_user_basic_oauth_creds:
+                # Check if we have OAuth credentials AND infrastructure from setup
+                if (
+                    multi_user_basic_oauth_creds
+                    and multi_user_token_verifier is not None
+                ):
                    sync_client_id, sync_client_secret = multi_user_basic_oauth_creds

-                    # Create minimal oauth_context for management API authentication
+                    # Create oauth_context for management API authentication
                    nextcloud_host_for_context = settings.nextcloud_host
                    mcp_server_url = os.getenv(
                        "NEXTCLOUD_MCP_SERVER_URL", "http://localhost:8000"
@@ -1425,9 +1573,10 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
                    )

                    oauth_context_dict = {
-                        "storage": basic_auth_storage,
+                        # Use OAuth refresh token storage if available, fallback to basic_auth_storage
+                        "storage": multi_user_refresh_storage or basic_auth_storage,
                        "oauth_client": None,  # Not needed for management APIs
-                        "token_verifier": None,  # Will be set when token broker is created
+                        "token_verifier": multi_user_token_verifier,  # FIXED: Now has real verifier!
                        "config": {
                            "mcp_server_url": mcp_server_url,
                            "discovery_url": discovery_url,
@@ -1441,7 +1590,19 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
                    }
                    app.state.oauth_context = oauth_context_dict
                    logger.info(
-                        f"OAuth context initialized for management APIs (multi-user BasicAuth, client_id={sync_client_id[:16]}...)"
+                        f"✓ OAuth context initialized for management APIs (hybrid mode, client_id={sync_client_id[:16]}...)"
+                    )
+                elif multi_user_basic_oauth_creds and multi_user_token_verifier is None:
+                    logger.warning(
+                        "OAuth infrastructure setup failed - management API will be unavailable. "
+                        "This is expected if OIDC discovery failed or token verifier creation failed. "
+                        "Webhook management from Astrolabe admin UI will not work."
+                    )
+                else:
+                    logger.warning(
+                        "OAuth credentials not available - management API will be unavailable. "
+                        "This is expected if DCR failed or static credentials were not provided. "
+                        "Webhook management from Astrolabe admin UI will not work."
                    )

            # Also share with browser_app for webhook routes
@@ -1465,7 +1626,6 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =

        # Start background vector sync tasks (ADR-007)
        # Scanner runs at server-level (once), not per-session
-        import anyio as anyio_module

        # Re-use settings from outer scope (already validated)
        # Note: enable_offline_access_for_sync, encryption_key, and refresh_token_storage
@@ -1505,11 +1665,11 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
                ) from e

            # Initialize shared state
-            send_stream, receive_stream = anyio_module.create_memory_object_stream(
+            send_stream, receive_stream = anyio.create_memory_object_stream(
                max_buffer_size=settings.vector_sync_queue_max_size
            )
-            shutdown_event = anyio_module.Event()
-            scanner_wake_event = anyio_module.Event()
+            shutdown_event = anyio.Event()
+            scanner_wake_event = anyio.Event()

            # Store in app state for access from routes (ADR-007)
            app.state.document_send_stream = send_stream
@@ -1536,7 +1696,7 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
                    break

            # Start background tasks using anyio TaskGroup
-            async with anyio_module.create_task_group() as tg:
+            async with anyio.create_task_group() as tg:
                # Start scanner task
                await tg.start(
                    scanner_task,
@@ -1578,10 +1738,10 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
        elif (
            settings.vector_sync_enabled
            and (oauth_enabled or settings.enable_multi_user_basic_auth)
-            and settings.enable_offline_access
+            and settings.enable_background_operations
        ):
-            # OAuth mode with offline access - multi-user sync
-            # Also used for multi-user BasicAuth mode (client auth is BasicAuth, background sync uses app passwords)
+            # OAuth mode with background operations - multi-user sync
+            # Also used for multi-user BasicAuth mode (client auth is BasicAuth, background sync uses app passwords or OAuth)
            mode_desc = "OAuth mode" if oauth_enabled else "Multi-user BasicAuth mode"
            logger.info(f"Starting background vector sync tasks for {mode_desc}")

@@ -1667,11 +1827,11 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
                    ) from e

                # Initialize shared state
-                send_stream, receive_stream = anyio_module.create_memory_object_stream(
+                send_stream, receive_stream = anyio.create_memory_object_stream(
                    max_buffer_size=settings.vector_sync_queue_max_size
                )
-                shutdown_event = anyio_module.Event()
-                scanner_wake_event = anyio_module.Event()
+                shutdown_event = anyio.Event()
+                scanner_wake_event = anyio.Event()

                # User state tracking for user manager
                user_states: dict = {}
@@ -1702,19 +1862,25 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
                        )
                        break

+                # Determine authentication mode for background sync
+                # Multi-user BasicAuth: use app passwords via Astrolabe (NOT OAuth)
+                # OAuth mode: use OAuth refresh tokens (NOT app passwords)
+                use_basic_auth = not oauth_enabled
+
                # Start background tasks using anyio TaskGroup
-                async with anyio_module.create_task_group() as tg:
+                async with anyio.create_task_group() as tg:
                    # Start user manager task (supervises per-user scanners)
                    await tg.start(
                        user_manager_task,
                        send_stream,
                        shutdown_event,
                        scanner_wake_event,
-                        token_broker,
+                        token_broker if not use_basic_auth else None,
                        token_storage,  # Use token_storage (works for both OAuth and multi-user BasicAuth)
                        nextcloud_host_for_sync,
                        user_states,
                        tg,
+                        use_basic_auth,  # Pass as positional arg (before task_status)
                    )

                    # Start processor pool (each gets a cloned receive stream)
@@ -1724,8 +1890,9 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
                            i,
                            receive_stream.clone(),
                            shutdown_event,
-                            token_broker,
+                            token_broker if not use_basic_auth else None,
                            nextcloud_host_for_sync,
+                            use_basic_auth,  # Pass as positional arg (before task_status)
                        )

                    logger.info(
@@ -1809,7 +1976,7 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
            # Try to connect to Nextcloud
            start_time = time.time()
            try:
-                async with httpx.AsyncClient(timeout=2.0) as client:
+                async with nextcloud_httpx_client(timeout=2.0) as client:
                    response = await client.get(f"{nextcloud_host}/status.php")
                    duration = time.time() - start_time
                    if response.status_code == 200:
@@ -1846,7 +2013,7 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
            checks["auth_mode"] = "multi_user_basic"
            checks["auth_configured"] = "ok"
            # Indicate if app passwords are supported (when offline_access enabled)
-            checks["supports_app_passwords"] = settings.enable_offline_access
+            checks["supports_app_passwords"] = get_settings().enable_offline_access
        elif mode == AuthMode.SINGLE_USER_BASIC:
            username = os.getenv("NEXTCLOUD_USERNAME")
            password = os.getenv("NEXTCLOUD_PASSWORD")
@@ -1863,9 +2030,9 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =

        # Check Qdrant status if using network mode (external Qdrant service)
        # In-memory and persistent modes use embedded Qdrant, no external service to check
-        vector_sync_enabled = (
-            os.getenv("VECTOR_SYNC_ENABLED", "false").lower() == "true"
-        )
+        # Note: get_settings() supports both ENABLE_SEMANTIC_SEARCH and VECTOR_SYNC_ENABLED
+        settings = get_settings()
+        vector_sync_enabled = settings.vector_sync_enabled
        qdrant_url = os.getenv("QDRANT_URL")  # Only set in network mode

        if vector_sync_enabled and qdrant_url:
@@ -1908,7 +2075,6 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
        This is a temporary endpoint for testing webhook schemas and payloads.
        It logs the full payload and returns 200 OK immediately.
        """
-        import json

        try:
            payload = await request.json()
@@ -1947,15 +2113,19 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
        settings.enable_multi_user_basic_auth and settings.enable_offline_access
    )
    if enable_management_apis:
-        from nextcloud_mcp_server.api.management import (
+        from nextcloud_mcp_server.api import (
            create_webhook,
+            delete_app_password,
            delete_webhook,
+            get_app_password_status,
            get_chunk_context,
            get_installed_apps,
+            get_pdf_preview,
            get_server_status,
            get_user_session,
            get_vector_sync_status,
            list_webhooks,
+            provision_app_password,
            revoke_user_access,
            unified_search,
            vector_search,
@@ -1983,12 +2153,36 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
                methods=["POST"],
            )
        )
+        # App password endpoints for multi-user BasicAuth mode
+        routes.append(
+            Route(
+                "/api/v1/users/{user_id}/app-password",
+                provision_app_password,
+                methods=["POST"],
+            )
+        )
+        routes.append(
+            Route(
+                "/api/v1/users/{user_id}/app-password",
+                get_app_password_status,
+                methods=["GET"],
+            )
+        )
+        routes.append(
+            Route(
+                "/api/v1/users/{user_id}/app-password",
+                delete_app_password,
+                methods=["DELETE"],
+            )
+        )
        routes.append(
            Route("/api/v1/vector-viz/search", vector_search, methods=["POST"])
        )
        routes.append(
            Route("/api/v1/chunk-context", get_chunk_context, methods=["GET"])
        )
+        # PDF preview endpoint for Astrolabe (server-side rendering)
+        routes.append(Route("/api/v1/pdf-preview", get_pdf_preview, methods=["GET"]))
        # ADR-018: Unified search endpoint for Nextcloud PHP app integration
        routes.append(Route("/api/v1/search", unified_search, methods=["POST"]))
        routes.append(Route("/api/v1/apps", get_installed_apps, methods=["GET"]))
@@ -2001,8 +2195,9 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
        logger.info(
            "Management API endpoints enabled: /api/v1/status, /api/v1/vector-sync/status, "
            "/api/v1/users/{user_id}/session, /api/v1/users/{user_id}/revoke, "
+            "/api/v1/users/{user_id}/app-password, "
            "/api/v1/vector-viz/search, /api/v1/search, /api/v1/apps, "
-            "/api/v1/webhooks"
+            "/api/v1/webhooks, /api/v1/pdf-preview"
        )

    # ADR-016: Add Smithery well-known config endpoint for container runtime discovery
@@ -2028,7 +2223,21 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
    # Note: Metrics endpoint is NOT exposed on main HTTP port for security reasons.
    # Metrics are served on dedicated port via setup_metrics() (default: 9090)

-    if oauth_enabled:
+    # Determine if OAuth provisioning is available
+    # This is true for:
+    # 1. OAuth modes (primary auth method for MCP operations)
+    # 2. Multi-user BasicAuth with offline access (hybrid mode)
+    oauth_provisioning_available = oauth_enabled or (
+        mode == AuthMode.MULTI_USER_BASIC
+        and settings.enable_offline_access
+        and multi_user_token_verifier is not None  # Ensure OAuth setup succeeded
+    )
+
+    if oauth_provisioning_available:
+        logger.info(
+            f"OAuth provisioning routes enabled for mode: {mode.value} "
+            f"(oauth_enabled={oauth_enabled}, hybrid_mode={not oauth_enabled})"
+        )
        # Import OAuth routes (ADR-004 Progressive Consent)
        from nextcloud_mcp_server.auth.oauth_routes import oauth_authorize

@@ -2091,10 +2300,6 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
            "Protected Resource Metadata (PRM) endpoints enabled (path-based + root)"
        )

-        # Add OAuth login routes (ADR-004 Progressive Consent Flow 1)
-        routes.append(Route("/oauth/authorize", oauth_authorize, methods=["GET"]))
-        logger.info("OAuth login routes enabled: /oauth/authorize (Flow 1)")
-
        # Add unified OAuth callback endpoint supporting both flows
        from nextcloud_mcp_server.auth.oauth_routes import (
            oauth_authorize_nextcloud,
@@ -2124,11 +2329,21 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
            )
        )
        logger.info(
-            "OAuth resource provisioning routes enabled: /oauth/authorize-nextcloud, /oauth/callback-nextcloud (Flow 2, legacy)"
+            "OAuth resource provisioning routes enabled: /oauth/authorize-nextcloud, /oauth/callback-nextcloud (Flow 2)"
        )

-    # Add browser OAuth login routes (OAuth mode only)
+    # Add OAuth Flow 1 routes (MCP client login) - ONLY for OAuth modes
+    # Multi-user BasicAuth uses hybrid mode with only Flow 2 (resource provisioning)
    if oauth_enabled:
+        from nextcloud_mcp_server.auth.oauth_routes import oauth_authorize
+
+        routes.append(Route("/oauth/authorize", oauth_authorize, methods=["GET"]))
+        logger.info("OAuth login routes enabled: /oauth/authorize (Flow 1)")
+
+    # Add browser OAuth login routes for Management API access
+    # Available in OAuth modes AND multi-user BasicAuth with offline access
+    # (hybrid mode). Separate from MCP tool auth - Management API uses OAuth
+    if oauth_provisioning_available:
        from nextcloud_mcp_server.auth.browser_oauth_routes import (
            oauth_login,
            oauth_login_callback,
@@ -2281,8 +2496,6 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
                # Starlette caches the body internally, so it's safe to read here
                body = await request.body()
                try:
-                    import json
-
                    data = json.loads(body)
                    # Check if this is an initialize request
                    if data.get("method") == "initialize":
@@ -9,7 +9,7 @@ import logging
 import time
 from typing import Optional

-import httpx
+from ..http import nextcloud_httpx_client

 logger = logging.getLogger(__name__)

@@ -60,7 +60,7 @@ class AstrolabeClient:
        # Discover token endpoint
        discovery_url = f"{self.nextcloud_host}/.well-known/openid-configuration"

-        async with httpx.AsyncClient() as client:
+        async with nextcloud_httpx_client() as client:
            logger.debug(f"Discovering token endpoint from {discovery_url}")
            discovery_resp = await client.get(discovery_url)
            discovery_resp.raise_for_status()
@@ -107,7 +107,7 @@ class AstrolabeClient:
        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:
+        async with nextcloud_httpx_client() as client:
            logger.debug(f"Retrieving app password for user: {user_id}")

            response = await client.get(
@@ -8,6 +8,7 @@ import hashlib
 import logging
 import os
 import secrets
+import time
 from base64 import urlsafe_b64encode
 from urllib.parse import urlencode

@@ -21,6 +22,8 @@ from nextcloud_mcp_server.auth.userinfo_routes import (
    _query_idp_userinfo,
 )

+from ..http import nextcloud_httpx_client
+
 logger = logging.getLogger(__name__)


@@ -141,7 +144,7 @@ async def oauth_login(request: Request) -> RedirectResponse | JSONResponse:
            )

        # Fetch authorization endpoint
-        async with httpx.AsyncClient() as http_client:
+        async with nextcloud_httpx_client() as http_client:
            response = await http_client.get(discovery_url)
            response.raise_for_status()
            discovery = response.json()
@@ -285,7 +288,7 @@ async def oauth_login_callback(request: Request) -> RedirectResponse | HTMLRespo
            if code_verifier:
                token_params["code_verifier"] = code_verifier

-            async with httpx.AsyncClient() as http_client:
+            async with nextcloud_httpx_client() as http_client:
                response = await http_client.post(
                    oauth_client.token_endpoint,
                    data=token_params,
@@ -295,31 +298,12 @@ async def oauth_login_callback(request: Request) -> RedirectResponse | HTMLRespo
        else:
            # Integrated mode (Nextcloud OIDC)
            discovery_url = oauth_config.get("discovery_url")
-            async with httpx.AsyncClient() as http_client:
+            async with nextcloud_httpx_client() as http_client:
                response = await http_client.get(discovery_url)
                response.raise_for_status()
                discovery = response.json()
                token_endpoint = discovery["token_endpoint"]

-            # Rewrite token_endpoint from public URL to internal Docker URL
-            # Discovery document returns public URLs (e.g., http://localhost:8080/...)
-            # but server-side requests must use internal Docker network (e.g., http://app:80/...)
-            public_issuer = os.getenv("NEXTCLOUD_PUBLIC_ISSUER_URL")
-            if public_issuer:
-                from urllib.parse import urlparse as parse_url
-
-                internal_host = oauth_config["nextcloud_host"]
-                internal_parsed = parse_url(internal_host)
-                token_parsed = parse_url(token_endpoint)
-                public_parsed = parse_url(public_issuer)
-
-                if token_parsed.hostname == public_parsed.hostname:
-                    # Replace public URL with internal Docker URL
-                    token_endpoint = f"{internal_parsed.scheme}://{internal_parsed.netloc}{token_parsed.path}"
-                    logger.info(
-                        f"Rewrote token endpoint to internal URL: {token_endpoint}"
-                    )
-
            token_params = {
                "grant_type": "authorization_code",
                "code": code,
@@ -332,7 +316,7 @@ async def oauth_login_callback(request: Request) -> RedirectResponse | HTMLRespo
            if code_verifier:
                token_params["code_verifier"] = code_verifier

-            async with httpx.AsyncClient() as http_client:
+            async with nextcloud_httpx_client() as http_client:
                response = await http_client.post(
                    token_endpoint,
                    data=token_params,
@@ -400,8 +384,6 @@ async def oauth_login_callback(request: Request) -> RedirectResponse | HTMLRespo
    refresh_expires_in = token_data.get("refresh_expires_in")
    refresh_expires_at = None
    if refresh_expires_in:
-        import time
-
        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})"
@@ -10,6 +10,8 @@ import httpx

 from nextcloud_mcp_server.auth.storage import RefreshTokenStorage

+from ..http import nextcloud_httpx_client
+
 logger = logging.getLogger(__name__)


@@ -132,7 +134,7 @@ async def register_client(
    logger.info(f"Registering OAuth client with Nextcloud: {client_name}")
    logger.debug(f"Registration endpoint: {registration_endpoint}")

-    async with httpx.AsyncClient(timeout=30.0) as client:
+    async with nextcloud_httpx_client(timeout=30.0) as client:
        try:
            response = await client.post(
                registration_endpoint,
@@ -229,7 +231,7 @@ async def delete_client(
    logger.info(f"Deleting OAuth client: {client_id[:16]}...")
    logger.debug(f"Deletion endpoint: {deletion_endpoint}")

-    async with httpx.AsyncClient(timeout=30.0) as http_client:
+    async with nextcloud_httpx_client(timeout=30.0) as http_client:
        for attempt in range(max_retries):
            try:
                # Prefer RFC 7592 Bearer token authentication
@@ -8,6 +8,7 @@ Handles OAuth flows with Keycloak as the identity provider, including:
 - Integration with RefreshTokenStorage
 """

+import base64
 import hashlib
 import logging
 import os
@@ -17,6 +18,8 @@ from urllib.parse import urlencode, urlparse

 import httpx

+from ..http import nextcloud_httpx_client
+
 logger = logging.getLogger(__name__)


@@ -106,7 +109,7 @@ class KeycloakOAuthClient:
    async def _get_http_client(self) -> httpx.AsyncClient:
        """Get or create HTTP client"""
        if self._http_client is None:
-            self._http_client = httpx.AsyncClient(timeout=30.0)
+            self._http_client = nextcloud_httpx_client(timeout=30.0)
        return self._http_client

    async def close(self) -> None:
@@ -155,7 +158,6 @@ class KeycloakOAuthClient:
        Returns:
            Tuple of (code_verifier, code_challenge)
        """
-        import base64

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

-import httpx
 import jwt
 from starlette.requests import Request
 from starlette.responses import JSONResponse, RedirectResponse
@@ -34,6 +34,8 @@ from starlette.responses import JSONResponse, RedirectResponse
 from nextcloud_mcp_server.auth.client_registry import get_client_registry
 from nextcloud_mcp_server.auth.storage import RefreshTokenStorage

+from ..http import nextcloud_httpx_client
+
 logger = logging.getLogger(__name__)


@@ -217,7 +219,7 @@ async def oauth_authorize(request: Request) -> RedirectResponse | JSONResponse:
            )

        # Fetch authorization endpoint from discovery
-        async with httpx.AsyncClient() as http_client:
+        async with nextcloud_httpx_client() as http_client:
            response = await http_client.get(discovery_url)
            response.raise_for_status()
            discovery = response.json()
@@ -353,7 +355,7 @@ async def oauth_authorize_nextcloud(
            status_code=500,
        )

-    async with httpx.AsyncClient() as http_client:
+    async with nextcloud_httpx_client() as http_client:
        response = await http_client.get(discovery_url)
        response.raise_for_status()
        discovery = response.json()
@@ -461,7 +463,7 @@ async def oauth_callback_nextcloud(request: Request):
    callback_uri = f"{mcp_server_url}/oauth/callback"

    discovery_url = oauth_config.get("discovery_url")
-    async with httpx.AsyncClient() as http_client:
+    async with nextcloud_httpx_client() as http_client:
        response = await http_client.get(discovery_url)
        response.raise_for_status()
        discovery = response.json()
@@ -481,7 +483,7 @@ async def oauth_callback_nextcloud(request: Request):
        token_params["code_verifier"] = code_verifier

    # Exchange code for tokens
-    async with httpx.AsyncClient() as http_client:
+    async with nextcloud_httpx_client() as http_client:
        response = await http_client.post(
            token_endpoint,
            data=token_params,
@@ -521,8 +523,6 @@ async def oauth_callback_nextcloud(request: Request):
        refresh_expires_in = token_data.get("refresh_expires_in")
        refresh_expires_at = None
        if refresh_expires_in:
-            import time
-
            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}")
@@ -9,6 +9,7 @@ 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
@@ -78,8 +79,6 @@ 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")
@@ -163,8 +162,6 @@ 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,7 +1,6 @@
 """Scope-based authorization for MCP tools."""

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

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

            # Check if offline access is enabled
-            enable_offline_access = (
-                os.getenv("ENABLE_OFFLINE_ACCESS", "false").lower() == "true"
-            )
+            # 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

            # In offline access mode, check if Nextcloud scopes require provisioning
            if enable_offline_access:
@@ -28,6 +28,7 @@ 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
@@ -830,7 +831,6 @@ class RefreshTokenStorage:
            resource_id: Resource identifier
            auth_method: Authentication method used
        """
-        import socket

        hostname = socket.gethostname()
        timestamp = int(time.time())
@@ -1240,6 +1240,180 @@ 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:
    """
@@ -25,6 +25,8 @@ import jwt
 from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
 from nextcloud_mcp_server.auth.token_exchange import exchange_token_for_delegation

+from ..http import nextcloud_httpx_client
+
 logger = logging.getLogger(__name__)


@@ -136,7 +138,7 @@ class TokenBrokerService:
    async def _get_http_client(self) -> httpx.AsyncClient:
        """Get or create HTTP client."""
        if self._http_client is None:
-            self._http_client = httpx.AsyncClient(
+            self._http_client = nextcloud_httpx_client(
                timeout=httpx.Timeout(30.0), follow_redirects=True
            )
        return self._http_client
@@ -168,37 +170,6 @@ class TokenBrokerService:
            self._oidc_config = response.json()
        return self._oidc_config

-    def _rewrite_token_endpoint(self, token_endpoint: str) -> str:
-        """Rewrite token endpoint from public URL to internal Docker URL.
-
-        OIDC discovery documents return public URLs (e.g., http://localhost:8080/...)
-        but server-side requests must use internal Docker network (e.g., http://app:80/...).
-
-        Args:
-            token_endpoint: Token endpoint URL from discovery document
-
-        Returns:
-            Rewritten URL using internal Docker host
-        """
-        import os
-        from urllib.parse import urlparse
-
-        public_issuer = os.getenv("NEXTCLOUD_PUBLIC_ISSUER_URL")
-        if not public_issuer:
-            return token_endpoint
-
-        internal_parsed = urlparse(self.nextcloud_host)
-        token_parsed = urlparse(token_endpoint)
-        public_parsed = urlparse(public_issuer)
-
-        if token_parsed.hostname == public_parsed.hostname:
-            # Replace public URL with internal Docker URL
-            rewritten = f"{internal_parsed.scheme}://{internal_parsed.netloc}{token_parsed.path}"
-            logger.info(f"Rewrote token endpoint: {token_endpoint} -> {rewritten}")
-            return rewritten
-
-        return token_endpoint
-
    async def get_nextcloud_token(self, user_id: str) -> Optional[str]:
        """
        Get a valid Nextcloud access token for the user.
@@ -407,7 +378,7 @@ class TokenBrokerService:
            Tuple of (access_token, expires_in_seconds)
        """
        config = await self._get_oidc_config()
-        token_endpoint = self._rewrite_token_endpoint(config["token_endpoint"])
+        token_endpoint = config["token_endpoint"]

        client = await self._get_http_client()

@@ -477,7 +448,7 @@ class TokenBrokerService:
            Tuple of (access_token, expires_in_seconds)
        """
        config = await self._get_oidc_config()
-        token_endpoint = self._rewrite_token_endpoint(config["token_endpoint"])
+        token_endpoint = config["token_endpoint"]

        client = await self._get_http_client()

@@ -20,6 +20,7 @@ import httpx
 import jwt

 from ..config import get_settings
+from ..http import nextcloud_httpx_client
 from .storage import RefreshTokenStorage

 logger = logging.getLogger(__name__)
@@ -68,7 +69,7 @@ class TokenExchangeService:
        self.storage: Optional[RefreshTokenStorage] = None

        # Create HTTP client
-        self.http_client = httpx.AsyncClient(
+        self.http_client = nextcloud_httpx_client(
            timeout=30.0,
            follow_redirects=True,
        )
@@ -31,6 +31,8 @@ from nextcloud_mcp_server.observability.metrics import (
    record_oauth_token_validation,
 )

+from ..http import nextcloud_httpx_client
+
 logger = logging.getLogger(__name__)


@@ -61,7 +63,7 @@ class UnifiedTokenVerifier(TokenVerifier):
        self.mode = "exchange" if settings.enable_token_exchange else "multi-audience"

        # Common components for all modes
-        self.http_client = httpx.AsyncClient(timeout=10.0)
+        self.http_client = nextcloud_httpx_client(timeout=10.0)

        # JWT verification support
        self.jwks_client: PyJWKClient | None = None
@@ -117,6 +119,71 @@ 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.
@@ -186,6 +253,78 @@ 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.
@@ -230,12 +369,15 @@ class UnifiedTokenVerifier(TokenVerifier):
        """
        return "." in token and token.count(".") == 2

-    async def _verify_jwt_signature(self, token: str) -> dict[str, Any] | None:
+    async def _verify_jwt_signature(
+        self, token: str, skip_issuer_check: bool = False
+    ) -> 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
@@ -248,25 +390,22 @@ 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 hasattr(self.settings, "oidc_issuer")
-                    else None
-                ),
+                issuer=(self.settings.oidc_issuer if should_verify_issuer else None),
                options={
                    "verify_signature": True,
                    "verify_exp": True,
                    "verify_iat": True,
-                    "verify_iss": (
-                        True
-                        if hasattr(self.settings, "oidc_issuer")
-                        and self.settings.oidc_issuer
-                        else False
-                    ),
+                    "verify_iss": should_verify_issuer,
                    "verify_aud": False,  # We handle audience validation separately
                },
            )
@@ -358,6 +497,24 @@ 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
        """
@@ -382,14 +539,13 @@ class UnifiedTokenVerifier(TokenVerifier):
            logger.warning("No 'exp' claim in token, using default TTL")
            exp = int(time.time() + self.cache_ttl)

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

        return AccessToken(
            token=token,
@@ -9,16 +9,19 @@ For OAuth mode: Requires browser-based OAuth login to establish session.

 import logging
 import os
+import traceback
 from pathlib import Path
 from typing import Any

-import httpx
 from jinja2 import Environment, FileSystemLoader
 from starlette.authentication import requires
 from starlette.requests import Request
 from starlette.responses import HTMLResponse, JSONResponse

 from nextcloud_mcp_server.client import NextcloudClient
+from nextcloud_mcp_server.config import get_settings
+
+from ..http import nextcloud_httpx_client

 logger = logging.getLogger(__name__)

@@ -105,9 +108,9 @@ async def _get_processing_status(request: Request) -> dict[str, Any] | None:
            "status": str,  # "syncing" or "idle"
        }
    """
-    # Check if vector sync is enabled
-    vector_sync_enabled = os.getenv("VECTOR_SYNC_ENABLED", "false").lower() == "true"
-    if not vector_sync_enabled:
+    # Check if vector sync is enabled (supports both old and new env var names)
+    settings = get_settings()
+    if not settings.vector_sync_enabled:
        return None

    try:
@@ -126,10 +129,8 @@ async def _get_processing_status(request: Request) -> dict[str, Any] | None:
        # Get Qdrant client and query indexed count
        indexed_count = 0
        try:
-            from nextcloud_mcp_server.config import get_settings
            from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client

-            settings = get_settings()
            qdrant_client = await get_qdrant_client()

            # Count documents in collection
@@ -257,7 +258,7 @@ async def _get_userinfo_endpoint(oauth_ctx: dict[str, Any]) -> str | None:
        return None

    try:
-        async with httpx.AsyncClient(timeout=10.0) as client:
+        async with nextcloud_httpx_client(timeout=10.0) as client:
            response = await client.get(discovery_url)
            response.raise_for_status()
            discovery = response.json()
@@ -290,7 +291,7 @@ async def _query_idp_userinfo(
        User info dictionary from IdP, or None if query fails
    """
    try:
-        async with httpx.AsyncClient(timeout=10.0) as client:
+        async with nextcloud_httpx_client(timeout=10.0) as client:
            response = await client.get(
                userinfo_uri,
                headers={"Authorization": f"Bearer {access_token_str}"},
@@ -385,8 +386,6 @@ async def _get_user_info(request: Request) -> dict[str, Any]:
        return user_context

    except Exception as e:
-        import traceback
-
        logger.error(f"Error retrieving user info: {e}")
        logger.error(f"Traceback: {traceback.format_exc()}")
        return {
@@ -635,7 +634,9 @@ async def user_info_html(request: Request) -> HTMLResponse:
        """

    # Check if vector sync is enabled (needed for Welcome tab)
-    vector_sync_enabled = os.getenv("VECTOR_SYNC_ENABLED", "false").lower() == "true"
+    # Note: get_settings() supports both ENABLE_SEMANTIC_SEARCH and VECTOR_SYNC_ENABLED
+    settings = get_settings()
+    vector_sync_enabled = settings.vector_sync_enabled

    # Render template
    template = _jinja_env.get_template("user_info.html")
@@ -15,6 +15,7 @@ import logging
 import time
 from pathlib import Path

+import anyio
 import numpy as np
 from jinja2 import Environment, FileSystemLoader
 from starlette.authentication import requires
@@ -396,8 +397,6 @@ async def vector_visualization_search(request: Request) -> JSONResponse:
            coords = pca.fit_transform(vectors)
            return coords, pca

-        import anyio
-
        with trace_operation(
            "vector_viz.pca_compute",
            attributes={
@@ -20,6 +20,8 @@ from nextcloud_mcp_server.server.webhook_presets import (
    get_preset,
 )

+from ..http import nextcloud_httpx_client
+
 logger = logging.getLogger(__name__)


@@ -140,7 +142,7 @@ async def _get_authenticated_client(request: Request) -> httpx.AsyncClient:

        assert nextcloud_host is not None  # Type narrowing for type checker
        assert username is not None and password is not None  # Type narrowing
-        return httpx.AsyncClient(
+        return nextcloud_httpx_client(
            base_url=nextcloud_host,
            auth=(username, password),
            timeout=30.0,
@@ -163,7 +165,7 @@ async def _get_authenticated_client(request: Request) -> httpx.AsyncClient:
    if not nextcloud_host:
        raise RuntimeError("Nextcloud host not configured")

-    return httpx.AsyncClient(
+    return nextcloud_httpx_client(
        base_url=nextcloud_host,
        headers={"Authorization": f"Bearer {access_token}"},
        timeout=30.0,
@@ -4,7 +4,6 @@ import os
 from httpx import (
    AsyncBaseTransport,
    AsyncClient,
-    AsyncHTTPTransport,
    Auth,
    BasicAuth,
    Request,
@@ -13,6 +12,7 @@ from httpx import (
 )

 from ..controllers.notes_search import NotesSearchController
+from ..http import nextcloud_httpx_transport
 from .calendar import CalendarClient
 from .contacts import ContactsClient
 from .cookbook import CookbookClient
@@ -67,7 +67,7 @@ class NextcloudClient:
        self._client = AsyncClient(
            base_url=base_url,
            auth=auth,
-            transport=AsyncDisableCookieTransport(AsyncHTTPTransport()),
+            transport=AsyncDisableCookieTransport(nextcloud_httpx_transport()),
            event_hooks={"request": [log_request], "response": [log_response]},
            timeout=Timeout(timeout=30, connect=5),
        )
@@ -13,6 +13,8 @@ from icalendar import Alarm, Calendar, vRecur
 from icalendar import Event as ICalEvent
 from icalendar import Todo as ICalTodo

+from ..config import get_nextcloud_ssl_verify
+
 logger = logging.getLogger(__name__)


@@ -34,6 +36,7 @@ class CalendarClient:
            url=f"{base_url}/remote.php/dav/",
            username=username,
            auth=auth,
+            ssl_verify_cert=get_nextcloud_ssl_verify(),  # type: ignore[arg-type]  # caldav types say bool|str but passes through to httpx which accepts SSLContext
        )
        self._calendar_home_url = f"{base_url}/remote.php/dav/calendars/{username}/"

@@ -255,18 +258,35 @@ class CalendarClient:
        """List events in a calendar within date range."""
        calendar = self._get_calendar(calendar_name)

-        # Get all events using caldav library (now with proper filter)
-        events = await calendar.events()
+        if start_datetime or end_datetime:
+            # Build CalDAV REPORT with time-range filter for server-side filtering
+            events = await self._search_events_by_date(
+                calendar, start_datetime, end_datetime
+            )
+            # Expand is only used when both bounds are provided
+            expanded = bool(start_datetime and end_datetime)
+        else:
+            # No date filter — fetch all events
+            events = await calendar.events()
+            expanded = False

        result = []
        for event in events:
            await event.load(only_if_unloaded=True)
            if event.data:
-                event_dict = self._parse_ical_event(event.data)
-                if event_dict:
-                    event_dict["href"] = str(event.url)
-                    event_dict["etag"] = ""
-                    result.append(event_dict)
+                if expanded:
+                    # Server-side expansion: each response resource may contain
+                    # multiple VEVENTs (one per recurrence occurrence)
+                    for event_dict in self._parse_all_ical_events(event.data):
+                        event_dict["href"] = str(event.url)
+                        event_dict["etag"] = ""
+                        result.append(event_dict)
+                else:
+                    event_dict = self._parse_ical_event(event.data)
+                    if event_dict:
+                        event_dict["href"] = str(event.url)
+                        event_dict["etag"] = ""
+                        result.append(event_dict)

            if len(result) >= limit:
                break
@@ -274,6 +294,57 @@ class CalendarClient:
        logger.debug(f"Found {len(result)} events")
        return result

+    async def _search_events_by_date(
+        self,
+        calendar: AsyncCalendar,
+        start_datetime: Optional[dt.datetime] = None,
+        end_datetime: Optional[dt.datetime] = None,
+    ) -> list:
+        """Execute a CalDAV REPORT with time-range filter."""
+        from caldav.async_collection import AsyncEvent
+        from caldav.elements import cdav, dav
+        from lxml import etree  # type: ignore[import-untyped]
+
+        # Ensure naive datetimes are treated as UTC
+        if start_datetime and start_datetime.tzinfo is None:
+            start_datetime = start_datetime.replace(tzinfo=dt.UTC)
+        if end_datetime and end_datetime.tzinfo is None:
+            end_datetime = end_datetime.replace(tzinfo=dt.UTC)
+
+        # Build comp-filter with time-range (mirrors sync Calendar.build_search_xml_query)
+        inner_comp_filter = cdav.CompFilter(name="VEVENT")
+        inner_comp_filter += cdav.TimeRange(start_datetime, end_datetime)
+        outer_comp_filter = cdav.CompFilter(name="VCALENDAR") + inner_comp_filter
+        filter_element = cdav.Filter() + outer_comp_filter
+
+        # When both bounds are provided, request server-side expansion of
+        # recurring events (RFC 4791 §9.6.5). Each occurrence is returned as
+        # a separate VEVENT with its own DTSTART, with RRULE stripped.
+        data = cdav.CalendarData()
+        if start_datetime and end_datetime:
+            data += cdav.Expand(start_datetime, end_datetime)
+
+        query = cdav.CalendarQuery() + [dav.Prop() + data] + filter_element
+
+        body = etree.tostring(
+            query.xmlelement(), encoding="utf-8", xml_declaration=True
+        )
+        assert calendar.client is not None
+        response = await calendar.client.report(str(calendar.url), body, depth=1)
+
+        # Parse response (same pattern as AsyncCalendar.search)
+        objects = []
+        response_data = response.expand_simple_props([cdav.CalendarData()])
+        for href, props in response_data.items():
+            if href == str(calendar.url):
+                continue
+            cal_data = props.get(cdav.CalendarData.tag)
+            if cal_data:
+                obj = AsyncEvent(client=calendar.client, data=cal_data, parent=calendar)
+                objects.append(obj)
+
+        return objects
+
    async def create_event(
        self, calendar_name: str, event_data: Dict[str, Any]
    ) -> Dict[str, Any]:
@@ -583,7 +654,7 @@ class CalendarClient:
        # Add categories
        categories = event_data.get("categories", "")
        if categories:
-            event.add("categories", categories.split(","))
+            event.add("categories", [c.strip() for c in categories.split(",")])

        # Add priority and status
        priority = event_data.get("priority", 5)
@@ -633,75 +704,92 @@ class CalendarClient:
        cal.add_component(event)
        return cal.to_ical().decode("utf-8")

+    def _extract_vevent_data(self, component) -> Dict[str, Any]:
+        """Extract event data from a single VEVENT component.
+
+        Shared helper used by both _parse_ical_event() and _parse_all_ical_events().
+        """
+        event_data: Dict[str, Any] = {
+            "uid": str(component.get("uid", "")),
+            "title": str(component.get("summary", "")),
+            "description": str(component.get("description", "")),
+            "location": str(component.get("location", "")),
+            "status": str(component.get("status", "CONFIRMED")),
+            "priority": int(component.get("priority", 5)),
+            "privacy": str(component.get("class", "PUBLIC")),
+            "url": str(component.get("url", "")),
+        }
+
+        # Handle dates
+        dtstart = component.get("dtstart")
+        if dtstart:
+            if isinstance(dtstart.dt, dt.date) and not isinstance(
+                dtstart.dt, dt.datetime
+            ):
+                event_data["start_datetime"] = dtstart.dt.isoformat()
+                event_data["all_day"] = True
+            else:
+                event_data["start_datetime"] = dtstart.dt.isoformat()
+                event_data["all_day"] = False
+
+        dtend = component.get("dtend")
+        if dtend:
+            if isinstance(dtend.dt, dt.date) and not isinstance(dtend.dt, dt.datetime):
+                event_data["end_datetime"] = dtend.dt.isoformat()
+            else:
+                event_data["end_datetime"] = dtend.dt.isoformat()
+
+        # Handle categories
+        categories = component.get("categories")
+        if categories:
+            event_data["categories"] = self._extract_categories(categories)
+
+        # Handle recurrence
+        rrule = component.get("rrule")
+        if rrule:
+            event_data["recurring"] = True
+            event_data["recurrence_rule"] = str(rrule)
+
+        # Handle attendees
+        attendees = []
+        for attendee in component.get("attendee", []):
+            if isinstance(attendee, list):
+                attendees.extend(str(a).replace("mailto:", "") for a in attendee)
+            else:
+                attendees.append(str(attendee).replace("mailto:", ""))
+        if attendees:
+            event_data["attendees"] = ",".join(attendees)
+
+        return event_data
+
    def _parse_ical_event(self, ical_text: str) -> Optional[Dict[str, Any]]:
-        """Parse iCalendar text and extract event data."""
+        """Parse iCalendar text and extract the first event."""
        try:
            cal = Calendar.from_ical(ical_text)
            for component in cal.walk():
                if component.name == "VEVENT":
-                    event_data = {
-                        "uid": str(component.get("uid", "")),
-                        "title": str(component.get("summary", "")),
-                        "description": str(component.get("description", "")),
-                        "location": str(component.get("location", "")),
-                        "status": str(component.get("status", "CONFIRMED")),
-                        "priority": int(component.get("priority", 5)),
-                        "privacy": str(component.get("class", "PUBLIC")),
-                        "url": str(component.get("url", "")),
-                    }
-
-                    # Handle dates
-                    dtstart = component.get("dtstart")
-                    if dtstart:
-                        if isinstance(dtstart.dt, dt.date) and not isinstance(
-                            dtstart.dt, dt.datetime
-                        ):
-                            event_data["start_datetime"] = dtstart.dt.isoformat()
-                            event_data["all_day"] = True
-                        else:
-                            event_data["start_datetime"] = dtstart.dt.isoformat()
-                            event_data["all_day"] = False
-
-                    dtend = component.get("dtend")
-                    if dtend:
-                        if isinstance(dtend.dt, dt.date) and not isinstance(
-                            dtend.dt, dt.datetime
-                        ):
-                            event_data["end_datetime"] = dtend.dt.isoformat()
-                        else:
-                            event_data["end_datetime"] = dtend.dt.isoformat()
-
-                    # Handle categories
-                    categories = component.get("categories")
-                    if categories:
-                        event_data["categories"] = self._extract_categories(categories)
-
-                    # Handle recurrence
-                    rrule = component.get("rrule")
-                    if rrule:
-                        event_data["recurring"] = True
-                        event_data["recurrence_rule"] = str(rrule)
-
-                    # Handle attendees
-                    attendees = []
-                    for attendee in component.get("attendee", []):
-                        if isinstance(attendee, list):
-                            attendees.extend(
-                                str(a).replace("mailto:", "") for a in attendee
-                            )
-                        else:
-                            attendees.append(str(attendee).replace("mailto:", ""))
-                    if attendees:
-                        event_data["attendees"] = ",".join(attendees)
-
-                    return event_data
-
+                    return self._extract_vevent_data(component)
            return None
-
        except Exception as e:
            logger.error(f"Error parsing iCalendar event: {e}")
            return None

+    def _parse_all_ical_events(self, ical_text: str) -> list[Dict[str, Any]]:
+        """Parse iCalendar text and extract ALL event occurrences.
+
+        Used with server-side expansion where a single VCALENDAR contains
+        multiple VEVENT components (one per recurrence occurrence).
+        """
+        results: list[Dict[str, Any]] = []
+        try:
+            cal = Calendar.from_ical(ical_text)
+            for component in cal.walk():
+                if component.name == "VEVENT":
+                    results.append(self._extract_vevent_data(component))
+        except Exception as e:
+            logger.error(f"Error parsing iCalendar events: {e}")
+        return results
+
    def _merge_ical_properties(
        self, raw_ical: str, event_data: Dict[str, Any], event_uid: str
    ) -> str:
@@ -727,6 +815,50 @@ class CalendarClient:
                    if "url" in event_data:
                        component["URL"] = event_data["url"]

+                    # Handle categories
+                    if "categories" in event_data:
+                        categories_str = event_data["categories"]
+                        if categories_str:
+                            component["CATEGORIES"] = [
+                                c.strip() for c in categories_str.split(",")
+                            ]
+                        elif "CATEGORIES" in component:
+                            del component["CATEGORIES"]
+
+                    # Handle recurrence rule
+                    if "recurrence_rule" in event_data:
+                        rrule_str = event_data["recurrence_rule"]
+                        if rrule_str:
+                            component["RRULE"] = vRecur.from_ical(rrule_str)
+                        elif "RRULE" in component:
+                            del component["RRULE"]
+
+                    # Handle attendees
+                    if "attendees" in event_data:
+                        attendees_str = event_data["attendees"]
+                        # Remove all existing attendees first
+                        while "ATTENDEE" in component:
+                            del component["ATTENDEE"]
+                        if attendees_str:
+                            for email in attendees_str.split(","):
+                                if email.strip():
+                                    component.add("attendee", f"mailto:{email.strip()}")
+
+                    # Handle reminder (VALARM)
+                    if "reminder_minutes" in event_data:
+                        component.subcomponents = [
+                            sub
+                            for sub in component.subcomponents
+                            if sub.name != "VALARM"
+                        ]
+                        minutes = event_data["reminder_minutes"]
+                        if minutes > 0:
+                            alarm = Alarm()
+                            alarm.add("action", "DISPLAY")
+                            alarm.add("description", "Event reminder")
+                            alarm.add("trigger", dt.timedelta(minutes=-minutes))
+                            component.add_component(alarm)
+
                    # Handle dates
                    if "start_datetime" in event_data:
                        start_str = event_data["start_datetime"]
@@ -960,7 +1092,9 @@ class CalendarClient:
                    if "categories" in todo_data:
                        categories_str = todo_data["categories"]
                        if categories_str:
-                            component["CATEGORIES"] = categories_str.split(",")
+                            component["CATEGORIES"] = [
+                                c.strip() for c in categories_str.split(",")
+                            ]
                            logger.debug(f"Set CATEGORIES to {categories_str}")

                    # Update timestamps
@@ -285,28 +285,23 @@ class DeckClient(BaseNextcloudClient):
        archived: Optional[bool] = None,
        done: Optional[str] = None,
    ) -> None:
-        # First, get the current card to use existing values for required fields
+        # Deck PUT API is a full replacement - all required fields must be sent.
+        # Fetch current card to preserve values for fields not being updated.
        current_card = await self.get_card(board_id, stack_id, card_id)

-        json_data = {}
-        if title is not None:
-            json_data["title"] = title
-        if description is not None:
-            json_data["description"] = description
-        # Type is required by the API, use provided or keep current
-        json_data["type"] = type if type is not None else current_card.type
-        # Owner is required by the API, use provided or keep current
-        json_data["owner"] = (
-            owner
-            if owner is not None
-            else (
-                current_card.owner
-                if isinstance(current_card.owner, str)
-                else current_card.owner.uid
-                if hasattr(current_card.owner, "uid")
-                else current_card.owner.primaryKey
-            )
-        )
+        # Build payload with required fields always included
+        json_data = {
+            # Title is required by the API
+            "title": title if title is not None else current_card.title,
+            # Type is required by the API
+            "type": type if type is not None else current_card.type,
+            # Owner is required by the API (model validator ensures it's a string)
+            "owner": owner if owner is not None else current_card.owner,
+            # Description must be sent to preserve it (PUT clears omitted fields)
+            "description": description
+            if description is not None
+            else (current_card.description or ""),
+        }
        if order is not None:
            json_data["order"] = order
        if duedate is not None:
@@ -391,11 +386,17 @@ class DeckClient(BaseNextcloudClient):
        order: int,
        target_stack_id: int,
    ) -> None:
+        # Use the non-API route /cards/{cardId}/reorder which correctly reads
+        # stackId from the body. The API route /api/.../stacks/{stackId}/cards/...
+        # has a parameter conflict where URL stackId overrides body stackId.
+        # See: https://github.com/cbcoutinho/nextcloud-mcp-server/issues/469
        json_data = {"order": order, "stackId": target_stack_id}
+        headers = self._get_deck_headers()
        await self._make_request(
            "PUT",
-            f"/apps/deck/api/v1.0/boards/{board_id}/stacks/{stack_id}/cards/{card_id}/reorder",
+            f"/apps/deck/cards/{card_id}/reorder",
            json=json_data,
+            headers=headers,
        )

    # Labels
@@ -1,6 +1,8 @@
 import logging
 import logging.config
 import os
+import socket
+import ssl
 from dataclasses import dataclass
 from enum import Enum
 from typing import Any, Optional
@@ -180,6 +182,10 @@ class Settings:
    nextcloud_username: Optional[str] = None
    nextcloud_password: Optional[str] = None

+    # Nextcloud SSL/TLS settings
+    nextcloud_verify_ssl: bool = True
+    nextcloud_ca_bundle: Optional[str] = None
+
    # ADR-005: Token Audience Validation (required for OAuth mode)
    nextcloud_mcp_server_url: Optional[str] = None  # MCP server URL (used as audience)
    nextcloud_resource_uri: Optional[str] = None  # Nextcloud resource identifier
@@ -251,9 +257,25 @@ class Settings:
    log_include_trace_context: bool = True

    def __post_init__(self):
-        """Validate Qdrant configuration and set defaults."""
+        """Validate configuration and set defaults."""
        logger = logging.getLogger(__name__)

+        # Validate SSL/TLS configuration
+        if not self.nextcloud_verify_ssl:
+            logger.warning(
+                "NEXTCLOUD_VERIFY_SSL is disabled. "
+                "TLS certificate verification is turned off for all Nextcloud connections. "
+                "This is insecure and should only be used for development/testing."
+            )
+        if self.nextcloud_ca_bundle:
+            import os as _os
+
+            if not _os.path.isfile(self.nextcloud_ca_bundle):
+                raise ValueError(
+                    f"NEXTCLOUD_CA_BUNDLE path does not exist: {self.nextcloud_ca_bundle}"
+                )
+            logger.info("Using custom CA bundle: %s", self.nextcloud_ca_bundle)
+
        # Ensure mutual exclusivity
        if self.qdrant_url and self.qdrant_location:
            raise ValueError(
@@ -337,7 +359,6 @@ class Settings:
        Returns:
            Collection name string
        """
-        import socket

        # Use explicit override if user configured non-default value
        if self.qdrant_collection != "nextcloud_content":
@@ -356,6 +377,19 @@ class Settings:

        return f"{deployment_id}-{model_name}"

+    # ADR-021: Property aliases for new naming convention
+    # These provide the new names while maintaining backward compatibility with old field names
+
+    @property
+    def enable_semantic_search(self) -> bool:
+        """Semantic search enabled (ADR-021 alias for vector_sync_enabled)."""
+        return self.vector_sync_enabled
+
+    @property
+    def enable_background_operations(self) -> bool:
+        """Background operations enabled (ADR-021 alias for enable_offline_access)."""
+        return self.enable_offline_access
+

 def _get_semantic_search_enabled() -> bool:
    """Get semantic search enabled status, supporting both old and new variable names.
@@ -491,6 +525,11 @@ def get_settings() -> Settings:
        nextcloud_host=os.getenv("NEXTCLOUD_HOST"),
        nextcloud_username=os.getenv("NEXTCLOUD_USERNAME"),
        nextcloud_password=os.getenv("NEXTCLOUD_PASSWORD"),
+        # Nextcloud SSL/TLS settings
+        nextcloud_verify_ssl=(
+            os.getenv("NEXTCLOUD_VERIFY_SSL", "true").lower() == "true"
+        ),
+        nextcloud_ca_bundle=os.getenv("NEXTCLOUD_CA_BUNDLE"),
        # ADR-005: Token Audience Validation
        nextcloud_mcp_server_url=os.getenv("NEXTCLOUD_MCP_SERVER_URL"),
        nextcloud_resource_uri=os.getenv("NEXTCLOUD_RESOURCE_URI"),
@@ -556,3 +595,20 @@ def get_settings() -> Settings:
        log_include_trace_context=os.getenv("LOG_INCLUDE_TRACE_CONTEXT", "true").lower()
        == "true",
    )
+
+
+def get_nextcloud_ssl_verify() -> bool | ssl.SSLContext:
+    """Return the SSL verification setting for Nextcloud connections.
+
+    Returns:
+        - False if NEXTCLOUD_VERIFY_SSL=false (disable verification)
+        - ssl.SSLContext if NEXTCLOUD_CA_BUNDLE is set (custom CA)
+        - True otherwise (default system CA verification)
+    """
+    settings = get_settings()
+    if not settings.nextcloud_verify_ssl:
+        return False
+    if settings.nextcloud_ca_bundle:
+        ctx = ssl.create_default_context(cafile=settings.nextcloud_ca_bundle)
+        return ctx
+    return True
@@ -9,6 +9,7 @@ See ADR-020 for detailed architecture and deployment mode documentation.
 """

 import logging
+import os
 from dataclasses import dataclass
 from enum import Enum

@@ -240,8 +241,6 @@ def detect_auth_mode(settings: Settings) -> AuthMode:
    Raises:
        ValueError: If explicit deployment_mode is invalid or conflicts with detected mode
    """
-    import logging
-    import os

    logger = logging.getLogger(__name__)

@@ -6,6 +6,8 @@ import tempfile
 from collections.abc import Awaitable, Callable
 from typing import Any, Optional

+import anyio
+
 # NOTE: Do NOT call pymupdf.layout.activate() here!
 # It changes the behavior of pymupdf4llm.to_markdown() when page_chunks=True,
 # causing it to return a string instead of a list[dict].
@@ -95,7 +97,6 @@ class PyMuPDFProcessor(DocumentProcessor):
        Raises:
            ProcessorError: If PDF processing fails
        """
-        import anyio

        try:
            if progress_callback:
@@ -3,6 +3,7 @@
 import logging
 from typing import Any

+import anyio
 from fastembed import SparseTextEmbedding

 logger = logging.getLogger(__name__)
@@ -67,7 +68,6 @@ class BM25SparseEmbeddingProvider:
        Returns:
            Dictionary with 'indices' and 'values' keys for Qdrant sparse vector
        """
-        import anyio

        # Run CPU-bound BM25 encoding in thread pool
        return await anyio.to_thread.run_sync(lambda: self.encode(text))  # type: ignore[attr-defined]
@@ -82,7 +82,6 @@ class BM25SparseEmbeddingProvider:
        Returns:
            List of dictionaries with 'indices' and 'values' for each text
        """
-        import anyio

        # Run CPU-bound BM25 encoding in thread pool to avoid blocking event loop
        sparse_embeddings = await anyio.to_thread.run_sync(  # type: ignore[attr-defined]
@@ -0,0 +1,45 @@
+"""Centralized HTTP client factory for Nextcloud connections.
+
+All outbound connections to Nextcloud (API calls, OIDC endpoints) should use
+these factories to ensure consistent SSL/TLS configuration from environment
+variables (NEXTCLOUD_VERIFY_SSL, NEXTCLOUD_CA_BUNDLE).
+"""
+
+from typing import Any
+
+import httpx
+
+from .config import get_nextcloud_ssl_verify
+
+
+def nextcloud_httpx_client(**kwargs: Any) -> httpx.AsyncClient:
+    """Create an httpx.AsyncClient with Nextcloud SSL settings applied.
+
+    Reads NEXTCLOUD_VERIFY_SSL and NEXTCLOUD_CA_BUNDLE from the environment
+    via ``get_nextcloud_ssl_verify()``. Caller-supplied ``verify`` kwarg
+    takes precedence if explicitly provided.
+
+    Args:
+        **kwargs: Forwarded to ``httpx.AsyncClient()``.
+
+    Returns:
+        Configured ``httpx.AsyncClient``.
+    """
+    kwargs.setdefault("verify", get_nextcloud_ssl_verify())
+    return httpx.AsyncClient(**kwargs)
+
+
+def nextcloud_httpx_transport(**kwargs: Any) -> httpx.AsyncHTTPTransport:
+    """Create an httpx.AsyncHTTPTransport with Nextcloud SSL settings applied.
+
+    Used by ``NextcloudClient`` which wraps the transport in
+    ``AsyncDisableCookieTransport``.
+
+    Args:
+        **kwargs: Forwarded to ``httpx.AsyncHTTPTransport()``.
+
+    Returns:
+        Configured ``httpx.AsyncHTTPTransport``.
+    """
+    kwargs.setdefault("verify", get_nextcloud_ssl_verify())
+    return httpx.AsyncHTTPTransport(**kwargs)
@@ -6,6 +6,7 @@ provides CLI integration.
 """

 import logging
+import sqlite3
 from pathlib import Path

 from alembic.config import Config
@@ -98,7 +99,6 @@ def get_current_revision(database_path: str | Path | None = None) -> str | None:
    Returns:
        Current revision ID or None if not versioned
    """
-    import sqlite3

    if database_path is None:
        database_path = "/app/data/tokens.db"
@@ -14,7 +14,9 @@ and resource usage. Metrics are organized by category:
 - External Dependency Health Metrics
 """

+import functools
 import logging
+import time

 from prometheus_client import (
    Counter,
@@ -423,8 +425,6 @@ def instrument_tool(func):
    Returns:
        Wrapped function with metrics and tracing instrumentation
    """
-    import functools
-    import time

    from nextcloud_mcp_server.observability.tracing import trace_operation

@@ -1,9 +1,16 @@
 """Base interfaces and data structures for search algorithms."""

+import logging
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
 from typing import Any, Protocol, runtime_checkable

+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
+

@runtime_checkable
 class NextcloudClientProtocol(Protocol):
@@ -78,13 +85,6 @@ async def get_indexed_doc_types(user_id: str) -> set[str]:
        >>> if "note" in types:
        ...     # Search notes
    """
-    import logging
-
-    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

    logger = logging.getLogger(__name__)
    settings = get_settings()
@@ -7,6 +7,9 @@ position markers for better visualization and understanding of search results.
 import logging
 from dataclasses import dataclass

+import pymupdf
+import pymupdf4llm
+
 from nextcloud_mcp_server.client import NextcloudClient

 logger = logging.getLogger(__name__)
@@ -549,8 +552,6 @@ async def _fetch_document_text(
                    # Extract text from PDF using PyMuPDF
                    # IMPORTANT: Use pymupdf4llm.to_markdown() to match indexing extraction
                    # This ensures character offsets align between indexed chunks and retrieval
-                    import pymupdf
-                    import pymupdf4llm

                    logger.debug(f"Extracting text from PDF: {file_path}")
                    pdf_doc = pymupdf.open(stream=file_content, filetype="pdf")
@@ -10,6 +10,9 @@ varies between indexing and rendering.

 import logging
 import re
+import shutil
+import tempfile
+from pathlib import Path
 from typing import Optional

 import pymupdf
@@ -77,8 +80,6 @@ class PDFHighlighter:
            Tuple of (full_text, page_boundaries) where page_boundaries is a list of:
            {"page": 1, "start_offset": 0, "end_offset": 1234}
        """
-        import tempfile
-        from pathlib import Path

        page_boundaries = []
        text_parts = []
@@ -110,7 +111,6 @@ class PDFHighlighter:
        full_text = "".join(text_parts)

        # Clean up temp directory and extracted images
-        import shutil

        try:
            shutil.rmtree(temp_dir)
@@ -590,8 +590,6 @@ class PDFHighlighter:
        Returns:
            Tuple of (png_bytes, page_number, highlight_count) or None if failed
        """
-        import tempfile
-        from pathlib import Path

        temp_pdf_path = None
        try:
@@ -637,7 +637,9 @@ def configure_deck_tools(mcp: FastMCP):

    @mcp.tool(
        title="Remove Label from Deck Card",
-        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+        annotations=ToolAnnotations(
+            destructiveHint=True, idempotentHint=True, openWorldHint=True
+        ),
    )
    @require_scopes("deck:write")
    @instrument_tool
@@ -692,7 +694,9 @@ def configure_deck_tools(mcp: FastMCP):

    @mcp.tool(
        title="Unassign User from Deck Card",
-        annotations=ToolAnnotations(idempotentHint=False, openWorldHint=True),
+        annotations=ToolAnnotations(
+            destructiveHint=True, idempotentHint=True, openWorldHint=True
+        ),
    )
    @require_scopes("deck:write")
    @instrument_tool
@@ -11,7 +11,7 @@ import secrets
 from typing import Optional
 from urllib.parse import urlencode

-import httpx
+import jwt
 from mcp.server.auth.middleware.auth_context import get_access_token
 from mcp.server.auth.provider import AccessToken
 from mcp.server.fastmcp import Context
@@ -23,6 +23,8 @@ from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
 from nextcloud_mcp_server.auth.token_broker import TokenBrokerService
 from nextcloud_mcp_server.auth.userinfo_routes import _query_idp_userinfo

+from ..http import nextcloud_httpx_client
+
 logger = logging.getLogger(__name__)


@@ -53,8 +55,6 @@ async def extract_user_id_from_token(ctx: Context) -> str:
    # Try JWT decode first
    if is_jwt:
        try:
-            import jwt
-
            payload = jwt.decode(token, options={"verify_signature": False})
            user_id = payload.get("sub", "unknown")
            logger.info(f"  ✓ JWT decode successful: user_id={user_id}")
@@ -70,7 +70,7 @@ async def extract_user_id_from_token(ctx: Context) -> str:
            "OIDC_DISCOVERY_URI",
            "http://localhost:8080/.well-known/openid-configuration",
        )
-        async with httpx.AsyncClient() as http_client:
+        async with nextcloud_httpx_client() as http_client:
            discovery_response = await http_client.get(oidc_discovery_uri)
            discovery_response.raise_for_status()
            discovery = discovery_response.json()
@@ -303,16 +303,17 @@ async def provision_nextcloud_access(
                ),
            )

-        # Get configuration
-        enable_offline_access = (
-            os.getenv("ENABLE_OFFLINE_ACCESS", "false").lower() == "true"
-        )
-        if not enable_offline_access:
+        # Get configuration using settings (handles both ENABLE_BACKGROUND_OPERATIONS
+        # and ENABLE_OFFLINE_ACCESS environment variables)
+        from nextcloud_mcp_server.config import get_settings
+
+        settings = get_settings()
+        if not settings.enable_offline_access:
            return ProvisioningResult(
                success=False,
                message=(
                    "Offline access is not enabled. "
-                    "Set ENABLE_OFFLINE_ACCESS=true to use this feature."
+                    "Set ENABLE_BACKGROUND_OPERATIONS=true to use this feature."
                ),
            )

@@ -488,13 +489,14 @@ async def check_logged_in(ctx: Context, user_id: Optional[str] = None) -> str:
        logger.info("=" * 60)

        # Not logged in - generate OAuth URL for Flow 2
-        enable_offline_access = (
-            os.getenv("ENABLE_OFFLINE_ACCESS", "false").lower() == "true"
-        )
-        if not enable_offline_access:
+        # Use settings (handles both ENABLE_BACKGROUND_OPERATIONS and ENABLE_OFFLINE_ACCESS)
+        from nextcloud_mcp_server.config import get_settings
+
+        settings = get_settings()
+        if not settings.enable_offline_access:
            return (
                "Not logged in. Offline access is not enabled. "
-                "Set ENABLE_OFFLINE_ACCESS=true to use this feature."
+                "Set ENABLE_BACKGROUND_OPERATIONS=true to use this feature."
            )

        # Get MCP server's OAuth client credentials
@@ -656,14 +656,12 @@ def configure_semantic_tools(mcp: FastMCP):
        This is useful for determining when vector indexing is complete
        after creating or updating content across all indexed apps.
        """
-        import os

-        # Check if vector sync is enabled
-        vector_sync_enabled = (
-            os.getenv("VECTOR_SYNC_ENABLED", "false").lower() == "true"
-        )
+        # Check if vector sync is enabled (supports both old and new env var names)
+        from nextcloud_mcp_server.config import get_settings

-        if not vector_sync_enabled:
+        settings = get_settings()
+        if not settings.vector_sync_enabled:
            return VectorSyncStatusResponse(
                indexed_count=0,
                pending_count=0,
@@ -1,3 +1,4 @@
+import base64
 import logging

 from mcp.server.fastmcp import Context, FastMCP
@@ -120,7 +121,6 @@ def configure_webdav_tools(mcp: FastMCP):
                pass

        # For binary files, return metadata and base64 encoded content
-        import base64

        return {
            "path": path,
@@ -156,8 +156,6 @@ def configure_webdav_tools(mcp: FastMCP):

        # Handle base64 encoded content
        if content_type and "base64" in content_type.lower():
-            import base64
-
            content_bytes = base64.b64decode(content)
            content_type = content_type.replace(";base64", "")
        else:
@@ -3,6 +3,7 @@
 import logging
 from dataclasses import dataclass

+import anyio
 from langchain_text_splitters import RecursiveCharacterTextSplitter

 logger = logging.getLogger(__name__)
@@ -68,7 +69,6 @@ class DocumentChunker:
        Returns:
            List of chunks with their character positions in the original content
        """
-        import anyio

        # Handle empty content - return single empty chunk for backward compatibility
        if not content:
@@ -1,6 +1,7 @@
 """HTML to Markdown conversion utilities for vector sync."""

 import logging
+import re

 from markdownify import markdownify as md

@@ -43,7 +44,6 @@ def html_to_markdown(html_content: str | None) -> str:
    except Exception as e:
        logger.warning(f"Failed to convert HTML to Markdown: {e}")
        # Fallback: strip all HTML tags as a last resort
-        import re

        text = re.sub(r"<[^>]+>", " ", html_content)
        return " ".join(text.split())  # Normalize whitespace
@@ -1,14 +1,23 @@
-"""OAuth mode vector sync orchestration.
+"""Multi-user vector sync orchestration.

-Manages multi-user background vector sync when running in OAuth mode
-with ENABLE_OFFLINE_ACCESS=true:
- User Manager: Monitors RefreshTokenStorage for user changes
+Manages background vector sync for multi-user deployments:
+- User Manager: Monitors storage for user changes
 - Per-User Scanners: One scanner task per provisioned user
 - Shared Processor Pool: Processes documents from all users

-Supports dual credential types for background sync:
- App passwords (interim solution, works today)
- OAuth refresh tokens (future, when Nextcloud supports OAuth for app APIs)
+Authentication strategies are mutually exclusive by deployment mode:
+
+Multi-user BasicAuth mode (ENABLE_MULTI_USER_BASIC_AUTH=true):
+- Uses app passwords stored locally in MCP server's database
+- Users provision via Astrolabe personal settings, which sends to MCP API
+- OAuth is NOT used
+
+OAuth mode (with external IdP like Keycloak):
+- Uses OAuth refresh tokens via TokenBrokerService
+- Users provision via browser OAuth flow
+- App passwords are NOT used
+
+These are separate concerns - no fallback between them.
 """

 import logging
@@ -24,7 +33,6 @@ from anyio.streams.memory import (
 )
 from httpx import BasicAuth

-from nextcloud_mcp_server.auth.astrolabe_client import AstrolabeClient
 from nextcloud_mcp_server.client import NextcloudClient
 from nextcloud_mcp_server.config import get_settings
 from nextcloud_mcp_server.vector.scanner import DocumentTask, scan_user_documents
@@ -59,16 +67,61 @@ class UserSyncState:
    started_at: float = field(default_factory=time.time)


-async def get_user_client(
+async def get_user_client_basic_auth(
+    user_id: str,
+    nextcloud_host: str,
+    storage: "RefreshTokenStorage | None" = None,
+) -> NextcloudClient:
+    """Get an authenticated NextcloudClient using app password (BasicAuth mode).
+
+    For multi-user BasicAuth deployments where users provision app passwords
+    via Astrolabe personal settings. The app password is stored locally in the
+    MCP server's database after being provisioned through the management API.
+
+    Args:
+        user_id: User identifier
+        nextcloud_host: Nextcloud base URL
+        storage: Optional RefreshTokenStorage instance (created from env if not provided)
+
+    Returns:
+        Authenticated NextcloudClient with BasicAuth
+
+    Raises:
+        NotProvisionedError: If user has not provisioned an app password
+    """
+    from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
+
+    # Get or create storage instance
+    if storage is None:
+        storage = RefreshTokenStorage.from_env()
+        await storage.initialize()
+
+    # Retrieve app password from local storage
+    app_password = await storage.get_app_password(user_id)
+
+    if not app_password:
+        raise NotProvisionedError(
+            f"User {user_id} has not provisioned an app password. "
+            f"User must configure background sync in Astrolabe personal settings."
+        )
+
+    logger.info(f"Using app password for background sync: {user_id}")
+    return NextcloudClient(
+        base_url=nextcloud_host,
+        username=user_id,
+        auth=BasicAuth(user_id, app_password),
+    )
+
+
+async def get_user_client_oauth(
    user_id: str,
    token_broker: "TokenBrokerService",
    nextcloud_host: str,
 ) -> NextcloudClient:
-    """Get an authenticated NextcloudClient for a user.
+    """Get an authenticated NextcloudClient using OAuth refresh token.

-    Supports dual credential types with priority:
-    1. App password from Astrolabe (works today with BasicAuth)
-    2. OAuth refresh token from storage (for future when OAuth fully supported)
+    For OAuth deployments with external IdP where users provision via
+    browser OAuth flow. App passwords are NOT used in this mode.

    Args:
        user_id: User identifier
@@ -76,45 +129,19 @@ async def get_user_client(
        nextcloud_host: Nextcloud base URL

    Returns:
-        Authenticated NextcloudClient
+        Authenticated NextcloudClient with Bearer token

    Raises:
        NotProvisionedError: If user has not provisioned offline access
    """
-    settings = get_settings()
-
-    # Try app password first (interim solution, works today)
-    if settings.oidc_client_id and settings.oidc_client_secret:
-        try:
-            astrolabe = AstrolabeClient(
-                nextcloud_host=nextcloud_host,
-                client_id=settings.oidc_client_id,
-                client_secret=settings.oidc_client_secret,
-            )
-            app_password = await astrolabe.get_user_app_password(user_id)
-
-            if app_password:
-                logger.info(
-                    f"Using app password for background sync: {user_id} "
-                    f"(credential_type=app_password)"
-                )
-                return NextcloudClient(
-                    base_url=nextcloud_host,
-                    username=user_id,
-                    auth=BasicAuth(user_id, app_password),
-                )
-        except Exception as e:
-            logger.debug(f"App password not available for {user_id}: {e}")
-
-    # Fall back to OAuth refresh token
-    logger.info(
-        f"Using OAuth refresh token for background sync: {user_id} "
-        f"(credential_type=refresh_token)"
-    )
    token = await token_broker.get_background_token(user_id, VECTOR_SYNC_SCOPES)
    if not token:
-        raise NotProvisionedError(f"User {user_id} has not provisioned offline access")
+        raise NotProvisionedError(
+            f"User {user_id} has not provisioned offline access. "
+            f"User must complete the OAuth provisioning flow."
+        )

+    logger.info(f"Using OAuth refresh token for background sync: {user_id}")
    return NextcloudClient.from_token(
        base_url=nextcloud_host,
        token=token,
@@ -122,30 +149,66 @@ async def get_user_client(
    )


+async def get_user_client(
+    user_id: str,
+    token_broker: "TokenBrokerService | None",
+    nextcloud_host: str,
+    *,
+    use_basic_auth: bool = False,
+) -> NextcloudClient:
+    """Get an authenticated NextcloudClient for a user.
+
+    Dispatches to the appropriate authentication strategy based on mode.
+    These are mutually exclusive - no fallback between them.
+
+    Args:
+        user_id: User identifier
+        token_broker: Token broker for OAuth mode (can be None for BasicAuth mode)
+        nextcloud_host: Nextcloud base URL
+        use_basic_auth: If True, use app passwords via Astrolabe (BasicAuth mode).
+                       If False, use OAuth refresh tokens (OAuth mode).
+
+    Returns:
+        Authenticated NextcloudClient
+
+    Raises:
+        NotProvisionedError: If user has not provisioned access for the mode
+    """
+    if use_basic_auth:
+        return await get_user_client_basic_auth(user_id, nextcloud_host)
+    else:
+        if token_broker is None:
+            raise ValueError("token_broker required for OAuth mode")
+        return await get_user_client_oauth(user_id, token_broker, nextcloud_host)
+
+
 async def user_scanner_task(
    user_id: str,
    send_stream: MemoryObjectSendStream[DocumentTask],
    shutdown_event: anyio.Event,
    wake_event: anyio.Event,
-    token_broker: "TokenBrokerService",
+    token_broker: "TokenBrokerService | None",
    nextcloud_host: str,
    *,
+    use_basic_auth: bool = False,
    task_status: TaskStatus = anyio.TASK_STATUS_IGNORED,
 ) -> None:
-    """Scanner task for a single user in OAuth mode.
+    """Scanner task for a single user.

-    Gets a fresh token at the start of each scan cycle.
+    Gets fresh credentials at the start of each scan cycle.

    Args:
        user_id: User to scan
        send_stream: Stream to send changed documents to processors
        shutdown_event: Event signaling shutdown
        wake_event: Event to trigger immediate scan
-        token_broker: Token broker for obtaining access tokens
+        token_broker: Token broker for OAuth mode (None for BasicAuth mode)
        nextcloud_host: Nextcloud base URL
+        use_basic_auth: If True, use app passwords; if False, use OAuth tokens
        task_status: Status object for signaling task readiness
    """
-    logger.info(f"[OAuth] Scanner started for user: {user_id}")
+    mode_label = "BasicAuth" if use_basic_auth else "OAuth"
+    logger.info(f"[{mode_label}] Scanner started for user: {user_id}")
    settings = get_settings()

    task_status.started()
@@ -153,8 +216,10 @@ async def user_scanner_task(
    while not shutdown_event.is_set():
        nc_client = None
        try:
-            # Get fresh token for this scan cycle
-            nc_client = await get_user_client(user_id, token_broker, nextcloud_host)
+            # Get fresh credentials for this scan cycle
+            nc_client = await get_user_client(
+                user_id, token_broker, nextcloud_host, use_basic_auth=use_basic_auth
+            )

            # Scan user's documents
            await scan_user_documents(
@@ -165,12 +230,14 @@ async def user_scanner_task(

        except NotProvisionedError:
            logger.warning(
-                f"[OAuth] User {user_id} no longer provisioned, stopping scanner"
+                f"[{mode_label}] User {user_id} no longer provisioned, stopping scanner"
            )
            break

        except Exception as e:
-            logger.error(f"[OAuth] Scanner error for {user_id}: {e}", exc_info=True)
+            logger.error(
+                f"[{mode_label}] Scanner error for {user_id}: {e}", exc_info=True
+            )

        finally:
            if nc_client:
@@ -183,33 +250,36 @@ async def user_scanner_task(
        except anyio.get_cancelled_exc_class():
            break

-    logger.info(f"[OAuth] Scanner stopped for user: {user_id}")
+    logger.info(f"[{mode_label}] Scanner stopped for user: {user_id}")


-async def oauth_processor_task(
+async def multi_user_processor_task(
    worker_id: int,
    receive_stream: MemoryObjectReceiveStream[DocumentTask],
    shutdown_event: anyio.Event,
-    token_broker: "TokenBrokerService",
+    token_broker: "TokenBrokerService | None",
    nextcloud_host: str,
+    use_basic_auth: bool = False,
    *,
    task_status: TaskStatus = anyio.TASK_STATUS_IGNORED,
 ) -> None:
-    """Processor task for OAuth mode.
+    """Processor task for multi-user mode.

-    Handles documents from any user by fetching tokens on-demand.
+    Handles documents from any user by fetching credentials on-demand.

    Args:
        worker_id: Worker identifier for logging
        receive_stream: Stream to receive documents from
        shutdown_event: Event signaling shutdown
-        token_broker: Token broker for obtaining access tokens
+        token_broker: Token broker for OAuth mode (None for BasicAuth mode)
        nextcloud_host: Nextcloud base URL
+        use_basic_auth: If True, use app passwords; if False, use OAuth tokens
        task_status: Status object for signaling task readiness
    """
    from nextcloud_mcp_server.vector.processor import process_document

-    logger.info(f"[OAuth] Processor {worker_id} started")
+    mode_label = "BasicAuth" if use_basic_auth else "OAuth"
+    logger.info(f"[{mode_label}] Processor {worker_id} started")
    task_status.started()

    while not shutdown_event.is_set():
@@ -220,9 +290,12 @@ async def oauth_processor_task(
            with anyio.fail_after(1.0):
                doc_task = await receive_stream.receive()

-            # Get token for THIS document's user
+            # Get credentials for THIS document's user
            nc_client = await get_user_client(
-                doc_task.user_id, token_broker, nextcloud_host
+                doc_task.user_id,
+                token_broker,
+                nextcloud_host,
+                use_basic_auth=use_basic_auth,
            )

            # Process the document
@@ -232,13 +305,13 @@ async def oauth_processor_task(
            continue

        except anyio.EndOfStream:
-            logger.info(f"[OAuth] Processor {worker_id}: Stream closed, exiting")
+            logger.info(f"[{mode_label}] Processor {worker_id}: Stream closed, exiting")
            break

        except NotProvisionedError:
            if doc_task:
                logger.warning(
-                    f"[OAuth] User {doc_task.user_id} not provisioned, "
+                    f"[{mode_label}] User {doc_task.user_id} not provisioned, "
                    f"skipping {doc_task.doc_type}_{doc_task.doc_id}"
                )
            continue
@@ -246,18 +319,24 @@ async def oauth_processor_task(
        except Exception as e:
            if doc_task:
                logger.error(
-                    f"[OAuth] Processor {worker_id} error processing "
+                    f"[{mode_label}] Processor {worker_id} error processing "
                    f"{doc_task.doc_type}_{doc_task.doc_id}: {e}",
                    exc_info=True,
                )
            else:
-                logger.error(f"[OAuth] Processor {worker_id} error: {e}", exc_info=True)
+                logger.error(
+                    f"[{mode_label}] Processor {worker_id} error: {e}", exc_info=True
+                )

        finally:
            if nc_client:
                await nc_client.close()

-    logger.info(f"[OAuth] Processor {worker_id} stopped")
+    logger.info(f"[{mode_label}] Processor {worker_id} stopped")
+
+
+# Backward compatibility alias
+oauth_processor_task = multi_user_processor_task


 async def _run_user_scanner_with_scope(
@@ -266,9 +345,10 @@ async def _run_user_scanner_with_scope(
    send_stream: MemoryObjectSendStream[DocumentTask],
    shutdown_event: anyio.Event,
    wake_event: anyio.Event,
-    token_broker: "TokenBrokerService",
+    token_broker: "TokenBrokerService | None",
    nextcloud_host: str,
    user_states: dict[str, UserSyncState],
+    use_basic_auth: bool = False,
 ) -> None:
    """Wrapper to run scanner with cancellation scope.

@@ -284,6 +364,7 @@ async def _run_user_scanner_with_scope(
                wake_event=wake_event,
                token_broker=token_broker,
                nextcloud_host=nextcloud_host,
+                use_basic_auth=use_basic_auth,
            )
    finally:
        # Clean up on exit
@@ -296,48 +377,60 @@ async def user_manager_task(
    send_stream: MemoryObjectSendStream[DocumentTask],
    shutdown_event: anyio.Event,
    wake_event: anyio.Event,
-    token_broker: "TokenBrokerService",
+    token_broker: "TokenBrokerService | None",
    refresh_token_storage: "RefreshTokenStorage",
    nextcloud_host: str,
    user_states: dict[str, UserSyncState],
    tg: TaskGroup,
+    use_basic_auth: bool = False,
    *,
    task_status: TaskStatus = anyio.TASK_STATUS_IGNORED,
 ) -> None:
    """Supervisor task that manages per-user scanners.

-    Periodically polls RefreshTokenStorage to detect:
-    - New users who have provisioned offline access -> start scanner
+    Periodically polls storage to detect:
+    - New users who have provisioned access -> start scanner
    - Users who have revoked access -> cancel their scanner

    Args:
        send_stream: Stream to send documents to processors
        shutdown_event: Event signaling shutdown
        wake_event: Event to wake scanners for immediate scan
-        token_broker: Token broker for obtaining access tokens
-        refresh_token_storage: Storage for refresh tokens
+        token_broker: Token broker for OAuth mode (None for BasicAuth mode)
+        refresh_token_storage: Storage for tracking provisioned users
        nextcloud_host: Nextcloud base URL
        user_states: Shared dict tracking active user scanners
        tg: Task group for spawning scanner tasks
+        use_basic_auth: If True, use app passwords; if False, use OAuth tokens
        task_status: Status object for signaling task readiness
    """
    settings = get_settings()
    poll_interval = settings.vector_sync_user_poll_interval
+    mode_label = "BasicAuth" if use_basic_auth else "OAuth"

-    logger.info(f"[OAuth] User manager started (poll interval: {poll_interval}s)")
+    logger.info(
+        f"[{mode_label}] User manager started (poll interval: {poll_interval}s)"
+    )
    task_status.started()

    while not shutdown_event.is_set():
        try:
-            # Get current provisioned users
-            provisioned_users = set(await refresh_token_storage.get_all_user_ids())
+            # Get current provisioned users based on mode
+            if use_basic_auth:
+                # BasicAuth mode: query app_passwords table
+                provisioned_users = set(
+                    await refresh_token_storage.get_all_app_password_user_ids()
+                )
+            else:
+                # OAuth mode: query refresh_tokens table
+                provisioned_users = set(await refresh_token_storage.get_all_user_ids())
            active_users = set(user_states.keys())

            # Start scanners for new users
            new_users = provisioned_users - active_users
            for user_id in new_users:
                logger.info(
-                    f"[OAuth] Starting scanner for newly provisioned user: {user_id}"
+                    f"[{mode_label}] Starting scanner for newly provisioned user: {user_id}"
                )
                cancel_scope = anyio.CancelScope()
                user_states[user_id] = UserSyncState(
@@ -356,24 +449,27 @@ async def user_manager_task(
                    token_broker,
                    nextcloud_host,
                    user_states,
+                    use_basic_auth,  # Positional after user_states
                )

            # Cancel scanners for revoked users
            revoked_users = active_users - provisioned_users
            for user_id in revoked_users:
-                logger.info(f"[OAuth] Stopping scanner for revoked user: {user_id}")
+                logger.info(
+                    f"[{mode_label}] Stopping scanner for revoked user: {user_id}"
+                )
                state = user_states.get(user_id)
                if state:
                    state.cancel_scope.cancel()
                    # Note: state will be removed by _run_user_scanner_with_scope on exit

            if new_users:
-                logger.info(f"[OAuth] Started {len(new_users)} new scanner(s)")
+                logger.info(f"[{mode_label}] Started {len(new_users)} new scanner(s)")
            if revoked_users:
-                logger.info(f"[OAuth] Stopped {len(revoked_users)} scanner(s)")
+                logger.info(f"[{mode_label}] Stopped {len(revoked_users)} scanner(s)")

        except Exception as e:
-            logger.error(f"[OAuth] User manager error: {e}", exc_info=True)
+            logger.error(f"[{mode_label}] User manager error: {e}", exc_info=True)

        # Sleep until next poll
        try:
@@ -384,9 +480,9 @@ async def user_manager_task(

    # Cancel all remaining scanners on shutdown
    logger.info(
-        f"[OAuth] User manager shutting down, cancelling {len(user_states)} scanner(s)"
+        f"[{mode_label}] User manager shutting down, cancelling {len(user_states)} scanner(s)"
    )
    for state in list(user_states.values()):
        state.cancel_scope.cancel()

-    logger.info("[OAuth] User manager stopped")
+    logger.info(f"[{mode_label}] User manager stopped")
@@ -3,6 +3,7 @@
 Processes documents from stream: fetches content, generates embeddings, stores in Qdrant.
 """

+import base64
 import logging
 import time
 import uuid
@@ -585,8 +586,6 @@ async def _index_document(
                "vector_sync.pdf_size": len(content_bytes),
            },
        ):
-            import base64
-
            from nextcloud_mcp_server.search.pdf_highlighter import PDFHighlighter

            # Build chunk data for batch processing
@@ -5,6 +5,7 @@ Periodically scans enabled users' content and queues changed documents for proce

 import logging
 import os
+import random
 import time
 from dataclasses import dataclass

@@ -167,7 +168,6 @@ async def scan_user_documents(
        nc_client: Authenticated Nextcloud client
        initial_sync: If True, send all documents (first-time sync)
    """
-    import random

    scan_id = random.randint(1000, 9999)
    logger.info(
@@ -1,6 +1,6 @@
 [project]
 name = "nextcloud-mcp-server"
-version = "0.57.0"
+version = "0.64.1"
 description = "Model Context Protocol (MCP) server for Nextcloud integration - enables AI assistants to interact with Nextcloud data"
 authors = [
    {name = "Chris Coutinho", email = "chris@coutinho.io"}
@@ -10,7 +10,7 @@ license = {text = "AGPL-3.0-only"}
 requires-python = ">=3.11"
 keywords = ["nextcloud", "mcp", "model-context-protocol", "llm", "ai", "claude", "webdav", "caldav", "carddav"]
 dependencies = [
-    "mcp[cli] (>=1.23,<1.24)",
+    "mcp[cli] (>=1.26,<1.27)",
    "httpx (>=0.28.1,<0.29.0)",
    "pillow (>=10.3.0,<12.0.0)", # Compatible with fastembed
    "icalendar (>=6.0.0,<7.0.0)",
@@ -64,7 +64,7 @@ Changelog = "https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/CHAN

 [tool.pytest.ini_options]
 anyio_mode = "auto"
-addopts = "-p no:asyncio -x"  # Disable pytest-asyncio plugin, use only anyio
+addopts = "-p no:asyncio"  # Disable pytest-asyncio plugin, use only anyio
 log_cli = 1
 log_cli_level = "ERROR"
 log_level = "ERROR"
@@ -98,13 +98,12 @@ version_files = [
 # Ignore tags from other components
 ignored_tag_formats = [
    "nextcloud-mcp-server-*",  # Helm chart tags
-    "astrolabe-v*",            # Astrolabe tags
 ]

-# Filter commits by scope (all scopes except helm and astrolabe)
+# Filter commits by scope (all scopes except helm)
 [tool.commitizen.customize]
-changelog_pattern = "^(feat|fix|docs|refactor|perf|test|build|ci|chore)(?!\\((?:helm|astrolabe)\\))(\\([^)]+\\))?(!)?:"
-schema_pattern = "^(feat|fix|docs|refactor|perf|test|build|ci|chore)(?!\\((?:helm|astrolabe)\\))(\\([^)]+\\))?(!)?:\\s.+"
+changelog_pattern = "^(feat|fix|docs|refactor|perf|test|build|ci|chore)(?!\\((?:helm)\\))(\\([^)]+\\))?(!)?:"
+schema_pattern = "^(feat|fix|docs|refactor|perf|test|build|ci|chore)(?!\\((?:helm)\\))(\\([^)]+\\))?(!)?:\\s.+"

 [tool.ruff.lint]
 extend-select = ["I"]
@@ -114,7 +113,7 @@ caldav = { git = "https://github.com/cbcoutinho/caldav", branch = "feature/httpx
 qdrant-client = { git = "https://github.com/cbcoutinho/qdrant-client", branch = "fix/fusion-score-threshold" }

 [build-system]
-requires = ["uv_build>=0.9.4,<0.10.0"]
+requires = ["uv_build>=0.10.0,<0.11.0"]
 build-backend = "uv_build"

 [tool.uv.build-backend]
@@ -1,90 +0,0 @@
-#!/bin/bash
-# Bump Astrolabe app version
-set -euo pipefail
-
-# Parse optional --increment flag
-INCREMENT=""
-while [[ $# -gt 0 ]]; do
-    case $1 in
-        --increment)
-            INCREMENT="$2"
-            shift 2
-            ;;
-        *)
-            echo "❌ Error: Unknown option: $1" >&2
-            echo "Usage: $0 [--increment PATCH|MINOR|MAJOR]" >&2
-            exit 1
-            ;;
-    esac
-done
-
-# Validate dependencies
-command -v uv >/dev/null 2>&1 || {
-    echo "❌ Error: uv not found" >&2
-    echo "   Install from https://docs.astral.sh/uv/" >&2
-    exit 1
-}
-
-# Validate Astrolabe directory exists
-if [ ! -d "third_party/astrolabe" ]; then
-    echo "❌ Error: Must run from repository root (third_party/astrolabe not found)" >&2
-    exit 1
-fi
-
-cd third_party/astrolabe
-
-# Validate required files exist
-if [ ! -f "appinfo/info.xml" ]; then
-    echo "❌ Error: appinfo/info.xml not found" >&2
-    exit 1
-fi
-
-if [ ! -f "package.json" ]; then
-    echo "❌ Error: package.json not found" >&2
-    exit 1
-fi
-
-echo "Bumping Astrolabe version..."
-if [ -n "$INCREMENT" ]; then
-    echo "  Forcing $INCREMENT bump"
-fi
-
-# Build commitizen command
-CZ_CMD="uv run cz --config .cz.toml bump --yes"
-if [ -n "$INCREMENT" ]; then
-    CZ_CMD="$CZ_CMD --increment $INCREMENT"
-fi
-
-# Run commitizen bump and capture output
-if ! output=$($CZ_CMD 2>&1); then
-    cd ../..
-
-    # Check if this is the expected "no commits to bump" case
-    if echo "$output" | grep -q "\[NO_COMMITS_TO_BUMP\]"; then
-        echo "ℹ️  No commits eligible for version bump" >&2
-        echo "$output" >&2
-        exit 0
-    fi
-
-    # Otherwise, this is an actual error
-    echo "❌ Error: Version bump failed" >&2
-    echo "$output" >&2
-    echo "" >&2
-    echo "Common causes:" >&2
-    echo "  - No commits with scope 'astrolabe' since last version" >&2
-    echo "  - No conventional commits found (use feat(astrolabe):, fix(astrolabe):, etc.)" >&2
-    echo "  - Git working directory not clean" >&2
-    exit 1
-fi
-
-echo "$output"
-echo ""
-echo "✓ Astrolabe version bumped successfully"
-echo "  Updated: appinfo/info.xml, package.json"
-echo "  Tag format: astrolabe-v\${version}"
-echo ""
-echo "Next steps:"
-echo "  cd ../.."
-echo "  git push --follow-tags"
-
-cd ../..
@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""
+Database query helper for development.
+
+Wraps `docker compose exec db mariadb` to execute SQL statements against
+the Nextcloud MariaDB database.
+
+Usage:
+    ./scripts/dbquery.py "SELECT * FROM oc_notes LIMIT 5"
+    ./scripts/dbquery.py -u root -p password "SHOW TABLES"
+    ./scripts/dbquery.py --json "SELECT * FROM oc_oidc_clients"
+"""
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+
+def find_compose_dir() -> Path:
+    """Find the directory containing docker-compose.yml."""
+    current = Path(__file__).resolve().parent
+    while current != current.parent:
+        if (current / "docker-compose.yml").exists():
+            return current
+        if (current / "compose.yml").exists():
+            return current
+        current = current.parent
+    # Default to script's parent directory
+    return Path(__file__).resolve().parent.parent
+
+
+def run_query(
+    sql: str,
+    user: str = "root",
+    password: str = "password",
+    database: str = "nextcloud",
+    vertical: bool = False,
+    json_output: bool = False,
+) -> tuple[int, str, str]:
+    """
+    Execute SQL via docker compose exec.
+
+    Returns:
+        Tuple of (return_code, stdout, stderr)
+    """
+    compose_dir = find_compose_dir()
+
+    cmd = [
+        "docker",
+        "compose",
+        "exec",
+        "-T",  # Disable pseudo-TTY allocation
+        "db",
+        "mariadb",
+        f"-u{user}",
+        f"-p{password}",
+        database,
+        "-e",
+        sql,
+    ]
+
+    if vertical:
+        cmd.insert(-2, "-E")  # Vertical output format
+
+    result = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        cwd=compose_dir,
+    )
+
+    return result.returncode, result.stdout, result.stderr
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Execute SQL queries against the Nextcloud MariaDB database",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+    %(prog)s "SELECT COUNT(*) FROM oc_notes"
+    %(prog)s "SELECT id, name FROM oc_oidc_clients"
+    %(prog)s -E "SELECT * FROM oc_users LIMIT 1"
+    %(prog)s --user nextcloud --password nextcloud "SHOW TABLES"
+        """,
+    )
+    parser.add_argument("sql", help="SQL statement to execute")
+    parser.add_argument(
+        "-u", "--user", default="root", help="Database user (default: root)"
+    )
+    parser.add_argument(
+        "-p",
+        "--password",
+        default="password",
+        help="Database password (default: password)",
+    )
+    parser.add_argument(
+        "-d",
+        "--database",
+        default="nextcloud",
+        help="Database name (default: nextcloud)",
+    )
+    parser.add_argument(
+        "-E",
+        "--vertical",
+        action="store_true",
+        help="Print output vertically (one column per line)",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        dest="json_output",
+        help="Request JSON output (if supported)",
+    )
+
+    args = parser.parse_args()
+
+    returncode, stdout, stderr = run_query(
+        sql=args.sql,
+        user=args.user,
+        password=args.password,
+        database=args.database,
+        vertical=args.vertical,
+        json_output=args.json_output,
+    )
+
+    if stdout:
+        print(stdout, end="")
+    if stderr:
+        # Filter out the password warning
+        filtered_stderr = "\n".join(
+            line
+            for line in stderr.splitlines()
+            if "Using a password on the command line interface can be insecure"
+            not in line
+        )
+        if filtered_stderr:
+            print(filtered_stderr, file=sys.stderr)
+
+    return returncode
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -0,0 +1,177 @@
+#!/usr/bin/env python3
+"""
+SQLite database query helper for MCP service development.
+
+Wraps `docker compose exec <service> sqlite3` to execute SQL statements
+against the token storage database in any MCP service container.
+
+Usage:
+    ./scripts/sqlitequery.py ".tables"
+    ./scripts/sqlitequery.py -s oauth "SELECT * FROM refresh_tokens"
+    ./scripts/sqlitequery.py -s keycloak --headers "SELECT * FROM oauth_clients"
+    ./scripts/sqlitequery.py --json "SELECT * FROM audit_logs LIMIT 5"
+"""
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+# Service name aliases for convenience
+SERVICE_ALIASES = {
+    "mcp": "mcp",
+    "oauth": "mcp-oauth",
+    "mcp-oauth": "mcp-oauth",
+    "keycloak": "mcp-keycloak",
+    "mcp-keycloak": "mcp-keycloak",
+    "basic": "mcp-multi-user-basic",
+    "multi-user-basic": "mcp-multi-user-basic",
+    "mcp-multi-user-basic": "mcp-multi-user-basic",
+}
+
+
+def find_compose_dir() -> Path:
+    """Find the directory containing docker-compose.yml."""
+    current = Path(__file__).resolve().parent
+    while current != current.parent:
+        if (current / "docker-compose.yml").exists():
+            return current
+        if (current / "compose.yml").exists():
+            return current
+        current = current.parent
+    # Default to script's parent directory
+    return Path(__file__).resolve().parent.parent
+
+
+def resolve_service(service: str) -> str:
+    """Resolve service alias to container name."""
+    resolved = SERVICE_ALIASES.get(service.lower())
+    if resolved is None:
+        # Not a known alias, use as-is (might be a custom service)
+        return service
+    return resolved
+
+
+def run_query(
+    sql: str,
+    service: str = "mcp",
+    database: str = "/app/data/tokens.db",
+    headers: bool = False,
+    json_output: bool = False,
+    column_mode: bool = False,
+) -> tuple[int, str, str]:
+    """
+    Execute SQL via docker compose exec.
+
+    Returns:
+        Tuple of (return_code, stdout, stderr)
+    """
+    compose_dir = find_compose_dir()
+    container = resolve_service(service)
+
+    # Build sqlite3 command with options
+    sqlite_args = []
+
+    # Set output mode
+    if json_output:
+        sqlite_args.extend(["-json"])
+    elif column_mode:
+        sqlite_args.extend(["-column"])
+
+    # Enable headers
+    if headers or column_mode:
+        sqlite_args.extend(["-header"])
+
+    cmd = [
+        "docker",
+        "compose",
+        "exec",
+        "-T",  # Disable pseudo-TTY allocation
+        container,
+        "sqlite3",
+        *sqlite_args,
+        database,
+        sql,
+    ]
+
+    result = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        cwd=compose_dir,
+    )
+
+    return result.returncode, result.stdout, result.stderr
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Execute SQL queries against SQLite databases in MCP service containers",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Services:
+    mcp              Single-user BasicAuth mode (default)
+    oauth            Nextcloud OAuth mode (mcp-oauth)
+    keycloak         Keycloak OAuth mode (mcp-keycloak)
+    basic            Multi-user BasicAuth mode (mcp-multi-user-basic)
+
+Examples:
+    %(prog)s ".tables"
+    %(prog)s -s oauth "SELECT user_id FROM refresh_tokens"
+    %(prog)s -s keycloak ".schema oauth_clients"
+    %(prog)s --headers "SELECT * FROM audit_logs LIMIT 5"
+    %(prog)s --json "SELECT * FROM oauth_sessions"
+        """,
+    )
+    parser.add_argument("sql", help="SQL statement or SQLite command to execute")
+    parser.add_argument(
+        "-s",
+        "--service",
+        default="mcp",
+        help="Target service (mcp, oauth, keycloak, basic) (default: mcp)",
+    )
+    parser.add_argument(
+        "-d",
+        "--database",
+        default="/app/data/tokens.db",
+        help="Database path inside container (default: /app/data/tokens.db)",
+    )
+    parser.add_argument(
+        "--headers",
+        action="store_true",
+        help="Show column headers",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        dest="json_output",
+        help="Output in JSON format",
+    )
+    parser.add_argument(
+        "--column",
+        action="store_true",
+        dest="column_mode",
+        help="Output in column format with headers",
+    )
+
+    args = parser.parse_args()
+
+    returncode, stdout, stderr = run_query(
+        sql=args.sql,
+        service=args.service,
+        database=args.database,
+        headers=args.headers,
+        json_output=args.json_output,
+        column_mode=args.column_mode,
+    )
+
+    if stdout:
+        print(stdout, end="")
+    if stderr:
+        print(stderr, file=sys.stderr)
+
+    return returncode
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -273,6 +273,86 @@ async def test_update_event(nc_client: NextcloudClient, temporary_event: dict):
        raise


+async def test_update_event_extended_fields(
+    nc_client: NextcloudClient, temporary_calendar: str
+):
+    """Test updating categories, recurrence_rule, attendees, and reminder_minutes."""
+    calendar_name = temporary_calendar
+
+    tomorrow = datetime.now() + timedelta(days=1)
+    event_data = {
+        "title": "Extended Fields Update Test",
+        "start_datetime": tomorrow.strftime("%Y-%m-%dT10:00:00"),
+        "end_datetime": tomorrow.strftime("%Y-%m-%dT11:00:00"),
+        "description": "Base event for extended-field update test",
+    }
+
+    event_uid = None
+    try:
+        result = await nc_client.calendar.create_event(calendar_name, event_data)
+        event_uid = result["uid"]
+        logger.info(f"Created base event for extended fields test: {event_uid}")
+
+        # --- Phase 1: Set all four extended fields ---
+        updated_data = {
+            "categories": "work,meeting",
+            "recurrence_rule": "FREQ=WEEKLY;COUNT=4",
+            "attendees": "alice@example.com,bob@example.com",
+            "reminder_minutes": 15,
+        }
+        await nc_client.calendar.update_event(calendar_name, event_uid, updated_data)
+
+        retrieved, _ = await nc_client.calendar.get_event(calendar_name, event_uid)
+
+        # Verify categories
+        assert "work" in retrieved.get("categories", "")
+        assert "meeting" in retrieved.get("categories", "")
+
+        # Verify recurrence rule
+        assert retrieved.get("recurring") is True
+        assert "WEEKLY" in retrieved.get("recurrence_rule", "")
+
+        # Verify attendees
+        attendees = retrieved.get("attendees", "")
+        assert "alice@example.com" in attendees
+        assert "bob@example.com" in attendees
+
+        logger.info("Phase 1 passed: all extended fields set correctly")
+
+        # --- Phase 2: Clear all four extended fields ---
+        cleared_data = {
+            "categories": "",
+            "recurrence_rule": "",
+            "attendees": "",
+            "reminder_minutes": 0,
+        }
+        await nc_client.calendar.update_event(calendar_name, event_uid, cleared_data)
+
+        cleared, _ = await nc_client.calendar.get_event(calendar_name, event_uid)
+
+        # Verify categories cleared
+        assert not cleared.get("categories")
+
+        # Verify recurrence cleared
+        assert cleared.get("recurring") is not True
+        assert not cleared.get("recurrence_rule")
+
+        # Verify attendees cleared
+        assert not cleared.get("attendees")
+
+        logger.info("Phase 2 passed: all extended fields cleared correctly")
+
+    except Exception as e:
+        logger.error(f"Extended fields update test failed: {e}")
+        raise
+    finally:
+        if event_uid:
+            try:
+                await nc_client.calendar.delete_event(calendar_name, event_uid)
+            except Exception:
+                pass
+
+
 async def test_create_event_with_attendees(
    nc_client: NextcloudClient, temporary_calendar: str
 ):
@@ -380,6 +460,177 @@ async def test_event_with_url_and_categories(
        raise


+async def test_list_events_date_range_filtering(
+    nc_client: NextcloudClient, temporary_calendar: str
+):
+    """Test that date range filtering actually excludes events outside the range.
+
+    Reproduces GH-538: get_calendar_events() accepted date range parameters
+    but returned events from the entire calendar history, ignoring date filters.
+    """
+    calendar_name = temporary_calendar
+    past_uid = None
+    future_uid = None
+
+    try:
+        # Create Event A: 30 days in the past
+        past_date = datetime.now() - timedelta(days=30)
+        past_event_data = {
+            "title": f"Past Event {uuid.uuid4().hex[:8]}",
+            "start_datetime": past_date.strftime("%Y-%m-%dT10:00:00"),
+            "end_datetime": past_date.strftime("%Y-%m-%dT11:00:00"),
+            "description": "Event in the past for date range test",
+        }
+        result_past = await nc_client.calendar.create_event(
+            calendar_name, past_event_data
+        )
+        past_uid = result_past["uid"]
+        logger.info(f"Created past event: {past_uid}")
+
+        # Create Event B: 1 day in the future
+        future_date = datetime.now() + timedelta(days=1)
+        future_event_data = {
+            "title": f"Future Event {uuid.uuid4().hex[:8]}",
+            "start_datetime": future_date.strftime("%Y-%m-%dT14:00:00"),
+            "end_datetime": future_date.strftime("%Y-%m-%dT15:00:00"),
+            "description": "Event in the future for date range test",
+        }
+        result_future = await nc_client.calendar.create_event(
+            calendar_name, future_event_data
+        )
+        future_uid = result_future["uid"]
+        logger.info(f"Created future event: {future_uid}")
+
+        # Query with date range: today → 7 days ahead
+        now = datetime.now()
+        week_ahead = now + timedelta(days=7)
+
+        events = await nc_client.calendar.get_calendar_events(
+            calendar_name=calendar_name,
+            start_datetime=now,
+            end_datetime=week_ahead,
+            limit=50,
+        )
+
+        event_uids = [e["uid"] for e in events]
+
+        # Future event (tomorrow) SHOULD be in results
+        assert future_uid in event_uids, (
+            f"Future event {future_uid} should be in date-filtered results"
+        )
+
+        # Past event (30 days ago) should NOT be in results
+        assert past_uid not in event_uids, (
+            f"Past event {past_uid} should be excluded by date range filter "
+            f"(GH-538: date range was being ignored)"
+        )
+
+        logger.info(
+            f"Date range filtering works: {len(events)} events returned, "
+            f"past event correctly excluded"
+        )
+
+    finally:
+        # Cleanup both events
+        for uid in [past_uid, future_uid]:
+            if uid:
+                try:
+                    await nc_client.calendar.delete_event(calendar_name, uid)
+                except Exception as e:
+                    logger.warning(f"Cleanup failed for event {uid}: {e}")
+
+
+async def test_recurring_event_date_range_expansion(
+    nc_client: NextcloudClient, temporary_calendar: str
+):
+    """Test that recurring events are expanded into individual occurrences.
+
+    When querying with a date range, a recurring event should return one
+    event dict per occurrence within the range, each with the correct
+    start_datetime for that occurrence (not the original master event date).
+
+    This is a follow-up to GH-538: the time-range filter correctly selected
+    recurring events, but returned the master event with its original DTSTART
+    instead of expanding occurrences.
+    """
+    calendar_name = temporary_calendar
+    event_uid = None
+
+    try:
+        # Create a daily recurring event starting 7 days ago
+        start = datetime.now() - timedelta(days=7)
+        event_data = {
+            "title": f"Daily Recurrence {uuid.uuid4().hex[:8]}",
+            "start_datetime": start.strftime("%Y-%m-%dT09:00:00"),
+            "end_datetime": start.strftime("%Y-%m-%dT10:00:00"),
+            "description": "Daily recurring event for expansion test",
+            "recurring": True,
+            "recurrence_rule": "FREQ=DAILY",
+        }
+        result = await nc_client.calendar.create_event(calendar_name, event_data)
+        event_uid = result["uid"]
+        logger.info(f"Created daily recurring event: {event_uid}")
+
+        # Query with date range: today → 3 days ahead
+        query_start = datetime.now().replace(hour=0, minute=0, second=0, microsecond=0)
+        query_end = query_start + timedelta(days=3)
+
+        events = await nc_client.calendar.get_calendar_events(
+            calendar_name=calendar_name,
+            start_datetime=query_start,
+            end_datetime=query_end,
+            limit=50,
+        )
+
+        # Filter to only our recurring event (calendar may have others)
+        our_events = [e for e in events if e["uid"] == event_uid]
+
+        # Should have multiple occurrences (one per day in the range)
+        assert len(our_events) >= 2, (
+            f"Expected multiple expanded occurrences, got {len(our_events)}. "
+            f"Expansion may not be working."
+        )
+
+        # Each occurrence should have a different start_datetime
+        start_dates = [e["start_datetime"] for e in our_events]
+        assert len(set(start_dates)) == len(our_events), (
+            f"Each occurrence should have a unique start_datetime, got: {start_dates}"
+        )
+
+        # No start_datetime should fall outside the queried range
+        for e in our_events:
+            event_start = datetime.fromisoformat(e["start_datetime"])
+            # Remove timezone info for comparison if present
+            if event_start.tzinfo is not None:
+                event_start = event_start.replace(tzinfo=None)
+            assert event_start >= query_start - timedelta(hours=1), (
+                f"Occurrence {e['start_datetime']} is before query start {query_start}"
+            )
+            assert event_start < query_end + timedelta(hours=1), (
+                f"Occurrence {e['start_datetime']} is after query end {query_end}"
+            )
+
+        # Expanded occurrences should NOT have recurrence rules
+        # (server strips RRULE when expanding)
+        for e in our_events:
+            assert not e.get("recurring"), (
+                "Expanded occurrence should not have recurring=True, "
+                "RRULE should be stripped by server-side expansion"
+            )
+
+        logger.info(
+            f"Recurring event expansion works: {len(our_events)} occurrences "
+            f"returned with unique start dates"
+        )
+
+    finally:
+        if event_uid:
+            try:
+                await nc_client.calendar.delete_event(calendar_name, event_uid)
+            except Exception as e:
+                logger.warning(f"Cleanup failed for recurring event {event_uid}: {e}")
+
+
 async def test_calendar_operations_error_handling(
    nc_client: NextcloudClient,
 ):
@@ -1,3 +1,5 @@
+import json
+
 import httpx

 # ============================================================================
@@ -22,14 +24,13 @@ def create_mock_response(
    Returns:
        Mock httpx.Response object
    """
-    import json as json_module

    if headers is None:
        headers = {}

    # If json_data is provided, serialize it to content
    if json_data is not None:
-        content = json_module.dumps(json_data).encode("utf-8")
+        content = json.dumps(json_data).encode("utf-8")
        headers.setdefault("content-type", "application/json")

    if content is None:
@@ -0,0 +1,194 @@
+"""
+Integration tests for DeckClient.update_card API behavior.
+
+These tests define the EXPECTED behavior for partial card updates:
+- Only fields explicitly passed should be modified
+- All other fields should be preserved unchanged
+
+Related issues:
+- nextcloud-mcp-server #452: DeckClient.update_card partial update bugs
+- deck #3127: REST API Docs: missing parameter in "update cards"
+- deck #4106: Provide a working example of API usage to update a cards details
+"""
+
+import pytest
+
+pytestmark = [pytest.mark.integration]
+
+
+@pytest.fixture
+async def deck_test_card(nc_client):
+    """Create a board, stack, and card for testing, cleanup after."""
+    board = await nc_client.deck.create_board("Test Update Card API", "FF0000")
+    stack = await nc_client.deck.create_stack(board.id, "Test Stack", 1)
+    card = await nc_client.deck.create_card(
+        board.id,
+        stack.id,
+        "Original Title",
+        type="plain",
+        description="Original description",
+    )
+
+    yield {
+        "board_id": board.id,
+        "stack_id": stack.id,
+        "card_id": card.id,
+        "card": card,
+    }
+
+    # Cleanup
+    await nc_client.deck.delete_board(board.id)
+
+
+class TestDeckClientUpdateCard:
+    """
+    Test DeckClient.update_card() partial update behavior.
+
+    Expected: Only explicitly provided fields are updated, all others preserved.
+    """
+
+    async def test_update_title_only_preserves_description(
+        self, nc_client, deck_test_card
+    ):
+        """Updating only the title should preserve the description."""
+        await nc_client.deck.update_card(
+            board_id=deck_test_card["board_id"],
+            stack_id=deck_test_card["stack_id"],
+            card_id=deck_test_card["card_id"],
+            title="New Title",
+        )
+
+        updated = await nc_client.deck.get_card(
+            deck_test_card["board_id"],
+            deck_test_card["stack_id"],
+            deck_test_card["card_id"],
+        )
+        assert updated.title == "New Title"
+        assert updated.description == "Original description"
+
+    async def test_update_description_only(self, nc_client, deck_test_card):
+        """Updating only the description should work and preserve other fields."""
+        await nc_client.deck.update_card(
+            board_id=deck_test_card["board_id"],
+            stack_id=deck_test_card["stack_id"],
+            card_id=deck_test_card["card_id"],
+            description="New description only",
+        )
+
+        updated = await nc_client.deck.get_card(
+            deck_test_card["board_id"],
+            deck_test_card["stack_id"],
+            deck_test_card["card_id"],
+        )
+        assert updated.title == "Original Title"
+        assert updated.description == "New description only"
+
+    async def test_update_title_and_description(self, nc_client, deck_test_card):
+        """Updating title and description together should work."""
+        await nc_client.deck.update_card(
+            board_id=deck_test_card["board_id"],
+            stack_id=deck_test_card["stack_id"],
+            card_id=deck_test_card["card_id"],
+            title="New Title",
+            description="New description",
+        )
+
+        updated = await nc_client.deck.get_card(
+            deck_test_card["board_id"],
+            deck_test_card["stack_id"],
+            deck_test_card["card_id"],
+        )
+        assert updated.title == "New Title"
+        assert updated.description == "New description"
+
+    async def test_update_duedate_only(self, nc_client, deck_test_card):
+        """Updating only the duedate should work and preserve other fields."""
+        await nc_client.deck.update_card(
+            board_id=deck_test_card["board_id"],
+            stack_id=deck_test_card["stack_id"],
+            card_id=deck_test_card["card_id"],
+            duedate="2025-12-31T23:59:59+00:00",
+        )
+
+        updated = await nc_client.deck.get_card(
+            deck_test_card["board_id"],
+            deck_test_card["stack_id"],
+            deck_test_card["card_id"],
+        )
+        assert updated.title == "Original Title"
+        assert updated.description == "Original description"
+        assert updated.duedate is not None
+
+    async def test_update_archived_only(self, nc_client, deck_test_card):
+        """Updating only the archived status should work and preserve other fields."""
+        await nc_client.deck.update_card(
+            board_id=deck_test_card["board_id"],
+            stack_id=deck_test_card["stack_id"],
+            card_id=deck_test_card["card_id"],
+            archived=True,
+        )
+
+        updated = await nc_client.deck.get_card(
+            deck_test_card["board_id"],
+            deck_test_card["stack_id"],
+            deck_test_card["card_id"],
+        )
+        assert updated.title == "Original Title"
+        assert updated.description == "Original description"
+        assert updated.archived is True
+
+    async def test_update_order_only(self, nc_client, deck_test_card):
+        """Updating only the order should work and preserve other fields."""
+        await nc_client.deck.update_card(
+            board_id=deck_test_card["board_id"],
+            stack_id=deck_test_card["stack_id"],
+            card_id=deck_test_card["card_id"],
+            order=99,
+        )
+
+        updated = await nc_client.deck.get_card(
+            deck_test_card["board_id"],
+            deck_test_card["stack_id"],
+            deck_test_card["card_id"],
+        )
+        assert updated.title == "Original Title"
+        assert updated.description == "Original description"
+        assert updated.order == 99
+
+    async def test_update_preserves_type(self, nc_client, deck_test_card):
+        """Type should be preserved when not explicitly changed."""
+        original = deck_test_card["card"]
+
+        await nc_client.deck.update_card(
+            board_id=deck_test_card["board_id"],
+            stack_id=deck_test_card["stack_id"],
+            card_id=deck_test_card["card_id"],
+            title="Changed Title",
+        )
+
+        updated = await nc_client.deck.get_card(
+            deck_test_card["board_id"],
+            deck_test_card["stack_id"],
+            deck_test_card["card_id"],
+        )
+        assert updated.type == original.type
+        assert updated.description == "Original description"
+
+    async def test_update_preserves_owner(self, nc_client, deck_test_card):
+        """Owner should be preserved when not explicitly changed."""
+        original = deck_test_card["card"]
+
+        await nc_client.deck.update_card(
+            board_id=deck_test_card["board_id"],
+            stack_id=deck_test_card["stack_id"],
+            card_id=deck_test_card["card_id"],
+            title="Changed Title",
+        )
+
+        updated = await nc_client.deck.get_card(
+            deck_test_card["board_id"],
+            deck_test_card["stack_id"],
+            deck_test_card["card_id"],
+        )
+        assert updated.owner == original.owner
+        assert updated.description == "Original description"
@@ -1,7 +1,17 @@
+import base64
+import hashlib
+import json
 import logging
 import os
+import re
+import secrets
+import subprocess
+import threading
+import time
 import uuid
+from http.server import BaseHTTPRequestHandler, HTTPServer
 from typing import Any, AsyncGenerator
+from urllib.parse import parse_qs, quote, urlparse

 import anyio
 import httpx
@@ -257,7 +267,6 @@ async def nc_mcp_basic_auth_client(

    Uses anyio pytest plugin for proper async fixture handling.
    """
-    import base64

    credentials = base64.b64encode(b"admin:admin").decode("utf-8")
    auth_header = f"Basic {credentials}"
@@ -342,7 +351,6 @@ async def nc_mcp_oauth_client_with_elicitation(
        logger.info(f"  Schema: {params.schema}")

        # Extract OAuth URL from elicitation message
-        import re

        url_pattern = r"https?://[^\s]+"
        urls = re.findall(url_pattern, params.message)
@@ -1108,10 +1116,6 @@ def oauth_callback_server():
    # "OAuth tests with browser automation not supported in GitHub Actions CI"
    # )

-    import threading
-    from http.server import BaseHTTPRequestHandler, HTTPServer
-    from urllib.parse import parse_qs, urlparse
-
    # Use a dict to store auth codes keyed by state parameter
    # This allows multiple concurrent OAuth flows
    auth_states = {}
@@ -1758,9 +1762,6 @@ async def playwright_oauth_token(
    - Browser fixture provided by pytest-playwright-asyncio
    - See: https://playwright.dev/python/docs/test-runners
    """
-    import secrets
-    import time
-    from urllib.parse import quote

    nextcloud_host = os.getenv("NEXTCLOUD_HOST")
    username = os.getenv("NEXTCLOUD_USERNAME")
@@ -2047,9 +2048,6 @@ async def _get_oauth_token_with_scopes(
    Returns:
        OAuth access token string with requested scopes
    """
-    import secrets
-    import time
-    from urllib.parse import quote

    nextcloud_host = os.getenv("NEXTCLOUD_HOST")
    username = os.getenv("NEXTCLOUD_USERNAME")
@@ -2353,32 +2351,41 @@ async def test_users_setup(anyio_backend, nc_client: NextcloudClient):
        except Exception as e:
            logger.warning(f"Error creating editors group (may already exist): {e}")

-        # Create each test user
+        # Create each test user (idempotent - check if exists first)
        for username, config in test_user_configs.items():
+            # Check if user already exists
+            user_exists = False
            try:
-                await nc_client.users.create_user(
-                    userid=username,
-                    password=config["password"],
-                    display_name=config["display_name"],
-                    email=config["email"],
-                )
-                logger.info(f"Created test user: {username}")
-                created_users.append(username)
+                await nc_client.users.get_user_details(username)
+                user_exists = True
+                logger.info(f"Test user {username} already exists, skipping creation")
+            except Exception:
+                # User doesn't exist, proceed with creation
+                pass

-                # Add user to groups if specified
-                for group in config["groups"]:
-                    try:
-                        await nc_client.users.add_user_to_group(username, group)
-                        logger.info(f"Added {username} to group {group}")
-                    except Exception as e:
-                        logger.warning(f"Error adding {username} to group {group}: {e}")
+            if not user_exists:
+                try:
+                    await nc_client.users.create_user(
+                        userid=username,
+                        password=config["password"],
+                        display_name=config["display_name"],
+                        email=config["email"],
+                    )
+                    logger.info(f"Created test user: {username}")
+                    created_users.append(username)  # Only track users WE created

-            except Exception as e:
-                # User might already exist, that's okay
-                logger.warning(
-                    f"Could not create user {username} (may already exist): {e}"
-                )
-                created_users.append(username)  # Add to list anyway for cleanup
+                    # Add user to groups if specified
+                    for group in config["groups"]:
+                        try:
+                            await nc_client.users.add_user_to_group(username, group)
+                            logger.info(f"Added {username} to group {group}")
+                        except Exception as e:
+                            logger.warning(
+                                f"Error adding {username} to group {group}: {e}"
+                            )
+
+                except Exception as e:
+                    logger.warning(f"Could not create user {username}: {e}")

        logger.info(f"Test users setup complete: {created_users}")
        yield test_user_configs
@@ -2417,9 +2424,6 @@ async def _get_oauth_token_for_user(
    Returns:
        OAuth access token string
    """
-    import secrets
-    import time
-    from urllib.parse import quote

    nextcloud_host = os.getenv("NEXTCLOUD_HOST")

@@ -2560,7 +2564,6 @@ async def all_oauth_tokens(
    Now uses the real callback server with state parameters for reliable
    concurrent token acquisition without race conditions.
    """
-    import time

    # Get auth_states dict from callback server
    auth_states, callback_url = oauth_callback_server
@@ -2711,7 +2714,6 @@ async def test_user(nc_client: NextcloudClient):
            user_config = test_user
            await nc_client.users.create_user(**user_config)
    """
-    import uuid

    # Generate unique user ID to avoid conflicts
    userid = f"testuser_{uuid.uuid4().hex[:8]}"
@@ -2747,7 +2749,6 @@ async def test_group(nc_client: NextcloudClient):

    Returns the group ID.
    """
-    import uuid

    # Generate unique group ID to avoid conflicts
    groupid = f"testgroup_{uuid.uuid4().hex[:8]}"
@@ -2882,11 +2883,6 @@ async def _get_keycloak_oauth_token(
    Returns:
        OAuth access token string from Keycloak
    """
-    import base64
-    import hashlib
-    import secrets
-    import time
-    from urllib.parse import quote

    # Get auth_states dict from callback server
    auth_states, _ = oauth_callback_server
@@ -3252,8 +3248,6 @@ async def configure_astrolabe_for_mcp_server(nc_client):
            - mcp_server_public_url: Public URL for OAuth token audience validation
            - client_id: Optional OAuth client ID (default: "nextcloudMcpServerUIPublicClient")
    """
-    import json
-    import subprocess

    async def _configure(
        mcp_server_internal_url: str,
@@ -1,6 +1,7 @@
 """Integration tests for document processing with progress notifications."""

 import io
+import os

 import pytest
 from PIL import Image
@@ -13,7 +14,6 @@ class TestDocumentProcessingProgress:

    async def test_unstructured_processor_with_progress_callback(self, nc_client):
        """Test that UnstructuredProcessor calls progress callback during processing."""
-        import os

        # Skip if unstructured is not enabled
        if os.getenv("ENABLE_UNSTRUCTURED", "false").lower() != "true":
@@ -71,7 +71,6 @@ class TestDocumentProcessingProgress:
        self, nc_mcp_client, nc_client
    ):
        """Test that reading a document via WebDAV MCP tool sends progress notifications."""
-        import os

        # Skip if document processing is not enabled
        if os.getenv("ENABLE_DOCUMENT_PROCESSING", "false").lower() != "true":
@@ -110,7 +109,6 @@ class TestDocumentProcessingProgress:

    async def test_progress_callback_not_required(self, nc_client):
        """Test that processing works without progress callback (backward compatibility)."""
-        import os

        if os.getenv("ENABLE_UNSTRUCTURED", "false").lower() != "true":
            pytest.skip("Unstructured processor not enabled")
@@ -4,6 +4,12 @@ This conftest.py provides hooks and fixtures specific to integration tests,
 including the --provider flag for RAG tests.
 """

+import logging
+
+import pytest
+
+logger = logging.getLogger(__name__)
+
 # Valid provider names
 VALID_PROVIDERS = ["openai", "ollama", "anthropic", "bedrock"]

@@ -24,3 +30,89 @@ def pytest_configure(config):
    config.addinivalue_line(
        "markers", "rag: mark test as RAG integration test (requires --provider flag)"
    )
+
+
+@pytest.fixture(autouse=True, scope="module")
+async def reset_all_singletons():
+    """Reset ALL global singletons between test modules.
+
+    Prevents anyio.WouldBlock errors caused by stale singleton state
+    from previous test modules holding references to dead event loops
+    or closed memory streams.
+    """
+    # Import all modules with singletons
+    import nextcloud_mcp_server.app as app_module
+    import nextcloud_mcp_server.auth.client_registry as client_registry_module
+    import nextcloud_mcp_server.auth.token_exchange as token_exchange_module
+    import nextcloud_mcp_server.embedding.service as embedding_module
+    import nextcloud_mcp_server.observability.tracing as tracing_module
+    import nextcloud_mcp_server.providers.registry as registry_module
+    import nextcloud_mcp_server.vector.qdrant_client as qdrant_module
+
+    # Store originals for restoration after test
+    originals = {
+        "qdrant_client": qdrant_module._qdrant_client,
+        "embedding_service": embedding_module._embedding_service,
+        "bm25_service": embedding_module._bm25_service,
+        "provider": registry_module._provider,
+        "vector_sync_state": (
+            app_module._vector_sync_state.document_send_stream,
+            app_module._vector_sync_state.document_receive_stream,
+            app_module._vector_sync_state.shutdown_event,
+            app_module._vector_sync_state.scanner_wake_event,
+        ),
+        "tracer": tracing_module._tracer,
+        "registry": client_registry_module._registry,
+        "token_exchange_service": token_exchange_module._token_exchange_service,
+    }
+
+    # Close any open memory streams before reset
+    if app_module._vector_sync_state.document_send_stream is not None:
+        try:
+            await app_module._vector_sync_state.document_send_stream.aclose()
+        except Exception:
+            pass
+    if app_module._vector_sync_state.document_receive_stream is not None:
+        try:
+            await app_module._vector_sync_state.document_receive_stream.aclose()
+        except Exception:
+            pass
+
+    # Reset all singletons to None/fresh state
+    qdrant_module._qdrant_client = None
+    embedding_module._embedding_service = None
+    embedding_module._bm25_service = None
+    registry_module._provider = None
+    app_module._vector_sync_state.document_send_stream = None
+    app_module._vector_sync_state.document_receive_stream = None
+    app_module._vector_sync_state.shutdown_event = None
+    app_module._vector_sync_state.scanner_wake_event = None
+    tracing_module._tracer = None
+    client_registry_module._registry = None
+    token_exchange_module._token_exchange_service = None
+
+    logger.debug("All singletons reset for test module")
+
+    yield
+
+    # Cleanup: Close async resources created during test
+    if qdrant_module._qdrant_client is not None:
+        try:
+            await qdrant_module._qdrant_client.close()
+        except Exception:
+            pass
+
+    # Restore originals
+    qdrant_module._qdrant_client = originals["qdrant_client"]
+    embedding_module._embedding_service = originals["embedding_service"]
+    embedding_module._bm25_service = originals["bm25_service"]
+    registry_module._provider = originals["provider"]
+    (
+        app_module._vector_sync_state.document_send_stream,
+        app_module._vector_sync_state.document_receive_stream,
+        app_module._vector_sync_state.shutdown_event,
+        app_module._vector_sync_state.scanner_wake_event,
+    ) = originals["vector_sync_state"]
+    tracing_module._tracer = originals["tracer"]
+    client_registry_module._registry = originals["registry"]
+    token_exchange_module._token_exchange_service = originals["token_exchange_service"]
@@ -1,151 +1,262 @@
-"""Integration tests for app password provisioning via Astrolabe.
+"""Integration tests for app password provisioning via management API.

-Tests the complete flow:
-1. User stores app password via Astrolabe API
-2. MCP server retrieves it via OAuth client credentials
-3. Background sync uses it to access Nextcloud
+Tests the complete flow for multi-user BasicAuth mode:
+1. User stores app password via management API endpoint
+2. MCP server stores it locally (encrypted)
+3. Background sync uses locally stored password to access Nextcloud
+
+These tests verify that BasicAuth and OAuth are completely separate concerns
+with no fallback between them.
 """

+import tempfile
+from pathlib import Path
+
 import pytest
-from httpx import BasicAuth
+from cryptography.fernet import Fernet

-from nextcloud_mcp_server.auth.astrolabe_client import AstrolabeClient
-from nextcloud_mcp_server.config import get_settings
-from nextcloud_mcp_server.vector.oauth_sync import get_user_client
+from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
+from nextcloud_mcp_server.vector.oauth_sync import (
+    NotProvisionedError,
+    get_user_client,
+    get_user_client_basic_auth,
+    get_user_client_oauth,
+)
+
+
+@pytest.fixture
+def encryption_key():
+    """Generate a test encryption key."""
+    return Fernet.generate_key().decode()
+
+
+@pytest.fixture
+async def temp_storage(encryption_key):
+    """Create temporary storage instance with encryption for testing."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        db_path = Path(tmpdir) / "test_provisioning.db"
+        storage = RefreshTokenStorage(
+            db_path=str(db_path), encryption_key=encryption_key
+        )
+        await storage.initialize()
+        yield storage


@pytest.mark.integration
-async def test_astrolabe_client_initialization():
-    """Test AstrolabeClient can be instantiated."""
-    client = AstrolabeClient(
+async def test_basic_auth_mode_uses_local_storage(temp_storage, mocker):
+    """Test that BasicAuth mode uses locally stored app passwords.
+
+    In multi-user BasicAuth mode, app passwords are stored locally
+    in the MCP server's database after being provisioned via the API.
+    """
+    # Store an app password in local storage
+    await temp_storage.store_app_password("test_user", "JHWzB-ZYgLZ-3qBDj-ZQe5o-LdKpB")
+
+    # Call get_user_client_basic_auth with local storage
+    client = await get_user_client_basic_auth(
+        user_id="test_user",
        nextcloud_host="http://localhost:8080",
-        client_id="test-client",
-        client_secret="test-secret",
+        storage=temp_storage,
    )

+    # Verify client was created with correct credentials
    assert client is not None
-    assert client.nextcloud_host == "http://localhost:8080"
-    assert client.client_id == "test-client"
-    assert client.client_secret == "test-secret"
-    assert client._token_cache is None
+    assert client.username == "test_user"


@pytest.mark.integration
-async def test_astrolabe_client_get_access_token_requires_oidc():
-    """Test that getting access token requires OIDC discovery endpoint."""
-    client = AstrolabeClient(
-        nextcloud_host="http://localhost:8080",
-        client_id="test-client",
-        client_secret="test-secret",
-    )
+async def test_basic_auth_mode_raises_error_without_app_password(temp_storage):
+    """Test that BasicAuth mode raises NotProvisionedError if no app password.

-    # This will fail without proper OIDC setup, which is expected
-    # The test verifies the client follows the OAuth client credentials flow
-    try:
-        token = await client.get_access_token()
-        # If we get here, OIDC is configured
-        assert token is not None
-    except Exception as e:
-        # Expected if OIDC not fully configured for test client
-        # 400/401/403/404 all indicate the flow is working but credentials are invalid
-        assert any(code in str(e) for code in ["400", "401", "403", "404"])
+    There is NO fallback to OAuth - if no app password, user must provision one.
+    """
+    # Don't store any app password

-
-@pytest.mark.integration
-async def test_get_user_app_password_returns_none_for_unconfigured_user():
-    """Test that get_user_app_password returns None for users without app passwords."""
-    # This requires valid OAuth client credentials
-    settings = get_settings()
-
-    if not settings.oidc_client_id or not settings.oidc_client_secret:
-        pytest.skip("OAuth client credentials not configured")
-
-    client = AstrolabeClient(
-        nextcloud_host=settings.nextcloud_host or "http://localhost:8080",
-        client_id=settings.oidc_client_id,
-        client_secret=settings.oidc_client_secret,
-    )
-
-    # Try to get app password for a user that hasn't provisioned one
-    try:
-        app_password = await client.get_user_app_password("nonexistent_user")
-        # Should return None for unconfigured user (404 response)
-        assert app_password is None
-    except Exception as e:
-        # May fail with auth error if OAuth not fully configured
-        assert any(code in str(e) for code in ["400", "401", "403", "404"])
-
-
-@pytest.mark.integration
-async def test_dual_credential_support_in_background_sync(mocker):
-    """Test that background sync tries app password first, then refresh token."""
-    from nextcloud_mcp_server.auth.token_broker import TokenBrokerService
-
-    # Mock AstrolabeClient to return an app password
-    mock_astrolabe = mocker.AsyncMock()
-    mock_astrolabe.get_user_app_password.return_value = "test-app-password-12345"
-
-    mocker.patch(
-        "nextcloud_mcp_server.vector.oauth_sync.AstrolabeClient",
-        return_value=mock_astrolabe,
-    )
-
-    # Mock TokenBrokerService (shouldn't be called if app password works)
-    mock_token_broker = mocker.MagicMock(spec=TokenBrokerService)
-
-    # Call get_user_client - should use app password
-    try:
-        _client = await get_user_client(
+    # Call get_user_client_basic_auth - should raise NotProvisionedError
+    with pytest.raises(NotProvisionedError) as exc_info:
+        await get_user_client_basic_auth(
            user_id="test_user",
-            token_broker=mock_token_broker,
            nextcloud_host="http://localhost:8080",
+            storage=temp_storage,
        )

-        # Verify app password was requested
-        mock_astrolabe.get_user_app_password.assert_called_once_with("test_user")
-
-        # Verify token broker was NOT called (app password took priority)
-        mock_token_broker.get_background_token.assert_not_called()
-
-        # Verify client uses BasicAuth
-        assert _client.auth is not None
-        assert isinstance(_client.auth, BasicAuth)
-    except Exception:
-        # May fail in test environment, but we verified the priority logic
-        pass
+    # Verify error message mentions app password provisioning
+    assert "app password" in str(exc_info.value).lower()
+    assert "test_user" in str(exc_info.value)


@pytest.mark.integration
-async def test_background_sync_falls_back_to_refresh_token(mocker):
-    """Test that background sync falls back to refresh token if no app password."""
-    from nextcloud_mcp_server.auth.token_broker import TokenBrokerService
-
-    # Mock AstrolabeClient to return None (no app password)
-    mock_astrolabe = mocker.AsyncMock()
-    mock_astrolabe.get_user_app_password.return_value = None
+async def test_get_user_client_dispatches_to_basic_auth(temp_storage, mocker):
+    """Test that get_user_client dispatches to BasicAuth mode correctly."""
+    # Store an app password
+    await temp_storage.store_app_password("alice", "aaaaa-bbbbb-ccccc-ddddd-eeeee")

+    # Mock RefreshTokenStorage.from_env at the source module
    mocker.patch(
-        "nextcloud_mcp_server.vector.oauth_sync.AstrolabeClient",
-        return_value=mock_astrolabe,
+        "nextcloud_mcp_server.auth.storage.RefreshTokenStorage.from_env",
+        return_value=temp_storage,
    )
+    # Also mock initialize since from_env returns an uninitialized instance
+    mocker.patch.object(temp_storage, "initialize", return_value=None)
+
+    # Call get_user_client in BasicAuth mode
+    client = await get_user_client(
+        user_id="alice",
+        token_broker=None,  # No token broker needed for BasicAuth mode
+        nextcloud_host="http://localhost:8080",
+        use_basic_auth=True,
+    )
+
+    # Verify client was created successfully
+    assert client is not None
+    assert client.username == "alice"
+
+
+@pytest.mark.integration
+async def test_oauth_mode_uses_refresh_token_only(mocker):
+    """Test that OAuth mode uses ONLY refresh tokens, NOT app passwords.
+
+    In OAuth mode, app passwords are NOT used.
+    This is a complete separation of concerns.
+    """
+    from nextcloud_mcp_server.auth.token_broker import TokenBrokerService

    # Mock TokenBrokerService to return an access token
    mock_token_broker = mocker.AsyncMock(spec=TokenBrokerService)
    mock_token_broker.get_background_token.return_value = "test-access-token"

-    # Call get_user_client - should fall back to refresh token
-    try:
-        _client = await get_user_client(
+    # Call get_user_client in OAuth mode
+    _client = await get_user_client(
+        user_id="test_user",
+        token_broker=mock_token_broker,
+        nextcloud_host="http://localhost:8080",
+        use_basic_auth=False,  # OAuth mode
+    )
+
+    # Verify token broker was called
+    mock_token_broker.get_background_token.assert_called_once()
+
+
+@pytest.mark.integration
+async def test_oauth_mode_raises_error_without_token(mocker):
+    """Test that OAuth mode raises NotProvisionedError if no refresh token.
+
+    There is NO fallback to app passwords - if no token, user must provision.
+    """
+    from nextcloud_mcp_server.auth.token_broker import TokenBrokerService
+
+    # Mock TokenBrokerService to return None (no token)
+    mock_token_broker = mocker.AsyncMock(spec=TokenBrokerService)
+    mock_token_broker.get_background_token.return_value = None
+
+    # Call get_user_client in OAuth mode - should raise NotProvisionedError
+    with pytest.raises(NotProvisionedError) as exc_info:
+        await get_user_client(
            user_id="test_user",
            token_broker=mock_token_broker,
            nextcloud_host="http://localhost:8080",
+            use_basic_auth=False,
        )

-        # Verify app password was attempted first
-        mock_astrolabe.get_user_app_password.assert_called_once_with("test_user")
+    # Verify error message mentions OAuth provisioning
+    assert "oauth" in str(exc_info.value).lower()
+    assert "test_user" in str(exc_info.value)

-        # Verify token broker was called as fallback
-        mock_token_broker.get_background_token.assert_called_once()
-    except Exception:
-        # May fail in test environment, but we verified the fallback logic
-        pass
+
+@pytest.mark.integration
+async def test_get_user_client_oauth_function(mocker):
+    """Test the dedicated get_user_client_oauth function."""
+    from nextcloud_mcp_server.auth.token_broker import TokenBrokerService
+
+    # Mock TokenBrokerService
+    mock_token_broker = mocker.AsyncMock(spec=TokenBrokerService)
+    mock_token_broker.get_background_token.return_value = "test-bearer-token"
+
+    # Call dedicated function
+    client = await get_user_client_oauth(
+        user_id="alice",
+        token_broker=mock_token_broker,
+        nextcloud_host="http://localhost:8080",
+    )
+
+    assert client is not None
+    assert client.username == "alice"
+    mock_token_broker.get_background_token.assert_called_once()
+
+
+@pytest.mark.integration
+async def test_oauth_mode_requires_token_broker():
+    """Test that OAuth mode requires a token broker."""
+    with pytest.raises(ValueError, match="token_broker required"):
+        await get_user_client(
+            user_id="test_user",
+            token_broker=None,  # Missing token broker
+            nextcloud_host="http://localhost:8080",
+            use_basic_auth=False,  # OAuth mode
+        )
+
+
+@pytest.mark.integration
+async def test_multiple_users_basic_auth_mode(temp_storage, mocker):
+    """Test that multiple users can be provisioned independently."""
+    # Store app passwords for multiple users
+    users = {
+        "alice": "aaaaa-aaaaa-aaaaa-aaaaa-aaaaa",
+        "bob": "bbbbb-bbbbb-bbbbb-bbbbb-bbbbb",
+        "charlie": "ccccc-ccccc-ccccc-ccccc-ccccc",
+    }
+
+    for user_id, password in users.items():
+        await temp_storage.store_app_password(user_id, password)
+
+    # Verify each user can get a client
+    for user_id in users.keys():
+        client = await get_user_client_basic_auth(
+            user_id=user_id,
+            nextcloud_host="http://localhost:8080",
+            storage=temp_storage,
+        )
+        assert client is not None
+        assert client.username == user_id
+
+
+@pytest.mark.integration
+async def test_get_all_provisioned_users(temp_storage):
+    """Test that we can list all provisioned users for BasicAuth mode."""
+    # Store app passwords for multiple users
+    await temp_storage.store_app_password("alice", "aaaaa-aaaaa-aaaaa-aaaaa-aaaaa")
+    await temp_storage.store_app_password("bob", "bbbbb-bbbbb-bbbbb-bbbbb-bbbbb")
+
+    # Get all provisioned users
+    user_ids = await temp_storage.get_all_app_password_user_ids()
+
+    assert len(user_ids) == 2
+    assert "alice" in user_ids
+    assert "bob" in user_ids
+
+
+@pytest.mark.integration
+async def test_revoke_app_password(temp_storage):
+    """Test that deleting app password revokes background access."""
+    # Provision user
+    await temp_storage.store_app_password("alice", "aaaaa-aaaaa-aaaaa-aaaaa-aaaaa")
+
+    # Verify user is provisioned
+    user_ids = await temp_storage.get_all_app_password_user_ids()
+    assert "alice" in user_ids
+
+    # Revoke access
+    deleted = await temp_storage.delete_app_password("alice")
+    assert deleted is True
+
+    # Verify user is no longer provisioned
+    user_ids = await temp_storage.get_all_app_password_user_ids()
+    assert "alice" not in user_ids
+
+    # Verify get_user_client now raises NotProvisionedError
+    with pytest.raises(NotProvisionedError):
+        await get_user_client_basic_auth(
+            user_id="alice",
+            nextcloud_host="http://localhost:8080",
+            storage=temp_storage,
+        )
@@ -1,5 +1,10 @@
 """Integration test for multi-user Astrolabe background sync enablement.

+Cross-system interface test: Tests the MCP server's integration with the
+Astrolabe Nextcloud app, which is installed from the Nextcloud app store via
+app-hooks/post-installation/20-install-astrolabe-app.sh. Astrolabe source
+lives in a separate repository (https://github.com/cbcoutinho/astrolabe).
+
 This test verifies that multiple users can independently:
 1. Log in to Nextcloud
 2. Generate an app password in Security settings
@@ -13,6 +18,8 @@ app password entry → background sync activation → database verification.
 """

 import logging
+import re
+import subprocess

 import anyio
 import pytest
@@ -41,8 +48,19 @@ async def login_to_nextcloud(page: Page, username: str, password: str):
    await page.fill('input[name="user"]', username)
    await page.fill('input[name="password"]', password)

-    # Submit form
-    await page.click('button[type="submit"]')
+    # Submit form - use force=True to bypass stability check (CSS transitions)
+    submit_button = page.locator('button[type="submit"]')
+    try:
+        await submit_button.click(force=True, timeout=10000)
+    except Exception:
+        # Fallback: JavaScript click
+        logger.info("Using JavaScript click for login button...")
+        await page.evaluate(
+            """
+            const btn = document.querySelector('button[type="submit"]');
+            if (btn) btn.click();
+            """
+        )
    await page.wait_for_load_state("networkidle", timeout=30000)

    # Verify logged in (should redirect away from login page)
@@ -73,6 +91,289 @@ async def navigate_to_astrolabe_settings(page: Page):
    logger.info("✓ Successfully loaded Astrolabe settings page")


+async def authorize_search_access(page: Page, username: str) -> bool:
+    """Complete Step 1: OAuth Authorization for Astrolabe.
+
+    Handles the OAuth flow:
+    1. Check if already authorized (Step 1 shows "Complete")
+    2. Click "Authorize" link
+    3. Handle Nextcloud OIDC consent screen
+    4. Wait for redirect back to Astrolabe settings
+    5. Verify "Complete" badge appears on Step 1
+
+    Args:
+        page: Playwright page instance (must be on Astrolabe settings page)
+        username: Username for logging
+
+    Returns:
+        True if authorization completed successfully
+    """
+    nextcloud_url = "http://localhost:8080"
+
+    logger.info(f"Authorizing search access (Step 1) for {username}...")
+
+    # Check if already on Astrolabe settings page, if not navigate there
+    if "/settings/user/astrolabe" not in page.url:
+        await navigate_to_astrolabe_settings(page)
+
+    # Wait for page to fully render
+    await anyio.sleep(1)
+
+    # Check if already authorized (either "Active" badge or Step 1 "Complete" badge)
+    try:
+        # Check for "Active" badge (fully configured state)
+        active_badge = page.get_by_text("Active", exact=True)
+        if await active_badge.count() > 0 and await active_badge.is_visible():
+            logger.info(f"✓ Already fully authorized for {username} (Active badge)")
+            return True
+    except Exception:
+        pass
+
+    try:
+        step1_section = page.locator('h4:has-text("Step 1")')
+        if await step1_section.count() > 0:
+            # Look for "Complete" text in the Step 1 section's parent
+            step1_parent = step1_section.locator("..")
+            complete_badge = step1_parent.get_by_text("Complete", exact=True)
+            if await complete_badge.count() > 0 and await complete_badge.is_visible():
+                logger.info(f"✓ Step 1 already complete for {username}")
+                return True
+    except Exception:
+        pass
+
+    # Find and click the "Authorize" button
+    authorize_button = page.locator('a.button.primary:has-text("Authorize")')
+
+    try:
+        await authorize_button.wait_for(timeout=5000, state="visible")
+        logger.info(f"Found Authorize button for {username}")
+    except Exception:
+        # Take screenshot for debugging
+        screenshot_path = f"/tmp/astrolabe_no_authorize_button_{username}.png"
+        await page.screenshot(path=screenshot_path)
+        logger.error(
+            f"Could not find Authorize button for {username}. Screenshot: {screenshot_path}"
+        )
+        raise ValueError(f"Authorize button not found for {username}")
+
+    # Click the Authorize button - this will redirect to OAuth provider
+    # Use force=True to bypass stability check which can timeout due to CSS transitions
+    await authorize_button.click(force=True)
+    logger.info(f"Clicked Authorize button for {username}")
+
+    # Wait for OAuth redirect to complete
+    await page.wait_for_load_state("networkidle", timeout=30000)
+    logger.info(f"After networkidle, current URL: {page.url}")
+
+    # Take screenshot to see current state
+    await page.screenshot(path=f"/tmp/astrolabe_after_authorize_{username}.png")
+    logger.info(f"Screenshot saved: /tmp/astrolabe_after_authorize_{username}.png")
+
+    # Handle OIDC consent screen if present
+    consent_handled = await _handle_oauth_consent_screen(page, username)
+    if consent_handled:
+        logger.info(f"✓ OAuth consent granted for {username}")
+    else:
+        logger.info(
+            f"No consent screen required for {username} (may be previously authorized)"
+        )
+
+    # Wait for redirect back to Astrolabe settings
+    # The OAuth callback will redirect back to /settings/user/astrolabe
+    try:
+        await page.wait_for_url(
+            f"**{nextcloud_url}/settings/user/astrolabe**", timeout=30000
+        )
+        logger.info(f"Redirected back to Astrolabe settings for {username}")
+    except Exception:
+        # Check if we're already on settings page
+        if "/settings/user/astrolabe" not in page.url:
+            logger.warning(
+                f"Not redirected to Astrolabe settings, current URL: {page.url}"
+            )
+            # Navigate manually
+            await page.goto(
+                f"{nextcloud_url}/settings/user/astrolabe", wait_until="networkidle"
+            )
+
+    # Wait for page to reload and render
+    await anyio.sleep(2)
+
+    # Verify authorization completed - check for various success indicators
+    # When fully configured, shows "Active" badge; when only Step 1 done, shows "Complete"
+    try:
+        # First check if "Active" badge is shown (fully configured state)
+        active_badge = page.get_by_text("Active", exact=True)
+        if await active_badge.count() > 0 and await active_badge.is_visible():
+            logger.info(f"✓ OAuth authorization complete for {username} (Active badge)")
+            return True
+    except Exception:
+        pass
+
+    try:
+        # Check for Step 1 "Complete" badge (partial configuration)
+        step1_section = page.locator('h4:has-text("Step 1")')
+        if await step1_section.count() > 0:
+            step1_parent = step1_section.locator("..")
+            complete_badge = step1_parent.get_by_text("Complete", exact=True)
+            await complete_badge.wait_for(timeout=5000, state="visible")
+            logger.info(f"✓ Step 1 OAuth authorization complete for {username}")
+            return True
+    except Exception:
+        pass
+
+    # Neither badge found - authorization failed
+    screenshot_path = f"/tmp/astrolabe_step1_not_complete_{username}.png"
+    await page.screenshot(path=screenshot_path)
+    logger.error(
+        f"Authorization badge not visible for {username}. Screenshot: {screenshot_path}"
+    )
+    raise ValueError(f"OAuth authorization did not complete for {username}")
+
+
+async def _handle_oauth_consent_screen(page: Page, username: str) -> bool:
+    """Handle the OIDC consent screen during OAuth flow.
+
+    Reuses the proven pattern from tests/conftest.py.
+
+    Args:
+        page: Playwright page instance
+        username: Username for logging
+
+    Returns:
+        True if consent was handled, False if no consent screen was found
+    """
+    try:
+        logger.info(f"Checking for consent screen at URL: {page.url}")
+
+        # Check if consent screen is present - try multiple selectors
+        # The consent screen may be #oidc-consent or use a different format
+        consent_div = await page.query_selector("#oidc-consent")
+
+        if consent_div:
+            logger.info(f"Consent screen detected via #oidc-consent for {username}")
+            # Get consent screen data attributes for logging
+            client_name = await consent_div.get_attribute("data-client-name")
+            scopes_attr = await consent_div.get_attribute("data-scopes")
+            logger.info(f"  Client: {client_name}")
+            logger.info(f"  Requested scopes: {scopes_attr}")
+        else:
+            # Check for Allow button directly (different consent screen format)
+            allow_button = page.locator('button:has-text("Allow")')
+            if await allow_button.count() > 0:
+                logger.info(f"Consent screen detected via Allow button for {username}")
+            else:
+                logger.info(f"No consent screen found for {username} at {page.url}")
+                await page.screenshot(path=f"/tmp/no_consent_screen_{username}.png")
+                logger.info(f"Screenshot: /tmp/no_consent_screen_{username}.png")
+                return False
+
+        # Wait for Vue.js to render the Allow button
+        try:
+            await page.wait_for_selector('button:has-text("Allow")', timeout=10000)
+            logger.info("  Allow button rendered by Vue.js")
+        except Exception as e:
+            screenshot_path = f"/tmp/consent_no_allow_button_{username}.png"
+            await page.screenshot(path=screenshot_path)
+            logger.error(f"  Timeout waiting for Allow button: {e}")
+            raise
+
+        # Check all scope checkboxes
+        scope_checkboxes = await page.query_selector_all('input[type="checkbox"]')
+        if scope_checkboxes:
+            logger.info(f"  Found {len(scope_checkboxes)} scope checkboxes")
+            for i, checkbox in enumerate(scope_checkboxes):
+                is_checked = await checkbox.is_checked()
+                is_disabled = await checkbox.is_disabled()
+                if not is_checked and not is_disabled:
+                    await checkbox.check()
+                    logger.info(f"    ✓ Checked scope checkbox {i + 1}")
+
+        # Click the Allow button using JavaScript (handles viewport issues)
+        allow_button_locator = page.locator('button:has-text("Allow")')
+
+        # Debug: take screenshot before clicking Allow
+        await page.screenshot(path=f"/tmp/consent_before_allow_{username}.png")
+        logger.info(
+            f"  Screenshot before Allow: /tmp/consent_before_allow_{username}.png"
+        )
+
+        button_count = await allow_button_locator.count()
+        logger.info(f"  Found {button_count} Allow button(s)")
+
+        if button_count > 0:
+            current_url = page.url
+            logger.info(f"  Current URL: {current_url}")
+            logger.info(f"  Clicking Allow button for {username}...")
+
+            # Use JavaScript click to handle consent buttons (proven pattern from conftest.py)
+            # This is more reliable than Playwright's click for Vue.js rendered buttons
+            await page.evaluate(
+                """
+                const buttons = document.querySelectorAll('button');
+                for (const btn of buttons) {
+                    if (btn.textContent.trim() === 'Allow') {
+                        btn.click();
+                        break;
+                    }
+                }
+                """
+            )
+
+            # Wait for URL to change (Vue.js uses window.location.href after fetch)
+            # networkidle doesn't detect fetch-based redirects
+            try:
+                await page.wait_for_url(
+                    lambda url: url != current_url,
+                    timeout=30000,
+                )
+                logger.info(f"  URL changed to: {page.url}")
+            except Exception as wait_error:
+                # If URL didn't change, check console for errors
+                logger.warning(f"  URL didn't change after click: {wait_error}")
+                await page.screenshot(path=f"/tmp/consent_after_allow_{username}.png")
+
+                # Try alternative: manually POST consent and navigate
+                logger.info("  Trying manual consent submission...")
+                try:
+                    redirect_url = await page.evaluate(
+                        """
+                        async () => {
+                            const selectedScopes = Array.from(document.querySelectorAll('input[type="checkbox"]:checked'))
+                                .map(cb => cb.value).join(' ');
+
+                            const response = await fetch('/index.php/apps/oidc/consent/grant', {
+                                method: 'POST',
+                                headers: {
+                                    'Content-Type': 'application/x-www-form-urlencoded',
+                                    'requesttoken': OC.requestToken,
+                                },
+                                body: 'scopes=' + encodeURIComponent(selectedScopes),
+                                redirect: 'follow',
+                            });
+
+                            return response.url || '/index.php/apps/oidc/authorize';
+                        }
+                        """
+                    )
+                    logger.info(f"  Manual consent returned URL: {redirect_url}")
+                    await page.goto(redirect_url, wait_until="networkidle")
+                except Exception as manual_error:
+                    logger.error(f"  Manual consent also failed: {manual_error}")
+                    raise
+
+            await page.screenshot(path=f"/tmp/consent_after_allow_{username}.png")
+            logger.info(f"  Consent granted for {username}")
+            return True
+        else:
+            logger.error(f"  Allow button not found for {username}")
+            return False
+
+    except Exception as e:
+        logger.error(f"Error handling consent screen for {username}: {e}")
+        raise
+
+
 async def generate_app_password(
    page: Page, username: str, app_name: str = "Astrolabe Background Sync"
 ) -> str:
@@ -103,16 +404,32 @@ async def generate_app_password(
    await anyio.sleep(1.0)
    logger.info("Waited for Vue.js to process input and enable button")

-    # Click the create button
+    # Click the create button - use force=True to bypass stability check (CSS transitions)
    create_button = page.locator(
        'button[type="submit"]:has-text("Create new app password")'
    )
-    await create_button.click()
+    try:
+        await create_button.click(force=True, timeout=10000)
+    except Exception:
+        # Fallback: JavaScript click
+        logger.info("Using JavaScript click for create button...")
+        await page.evaluate(
+            """
+            const btn = document.querySelector('button[type="submit"]');
+            if (btn) btn.click();
+            """
+        )
    logger.info("Clicked create app password button")

    # Wait for app password to be generated and displayed in the dialog
    await anyio.sleep(3)  # Give it more time to generate and display

+    # Debug screenshot after clicking create
+    await page.screenshot(path=f"/tmp/app_password_after_create_{username}.png")
+    logger.info(
+        f"Screenshot after create: /tmp/app_password_after_create_{username}.png"
+    )
+
    # Find the Login input field which should have the username value
    # Then find the Password input field which is in the same form
    app_password = None
@@ -151,7 +468,6 @@ async def generate_app_password(
        )

    # Validate password format before returning
-    import re

    if not re.match(
        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}$",
@@ -171,11 +487,11 @@ async def generate_app_password(
        f"✓ Generated app password for {username}: {app_password[:10]}... (validated)"
    )

-    # Close the dialog by clicking the Close button
-    close_button = page.get_by_role("button", name="Close")
-    await close_button.click()
+    # Close dialog with Escape key (bypasses CSS layout issues with h2 intercepting clicks)
+    logger.info("Closing app password dialog with Escape key...")
+    await page.keyboard.press("Escape")
+    await anyio.sleep(0.5)  # Wait for dialog close animation
    logger.info("Closed app password dialog")
-    await anyio.sleep(0.5)

    return app_password

@@ -225,9 +541,9 @@ async def enable_background_sync_via_app_password(
    # Wait for page to load
    await anyio.sleep(1)

-    # Check if already active (look for "Active" text in the Background Sync Access section)
+    # Check if already complete (look for Step 2 "Complete" badge or overall "Active" state)
    try:
-        # The "Active" badge appears as a <span> with text "Active"
+        # First check for overall "Active" badge (both steps complete)
        active_text = page.get_by_text("Active", exact=True)
        if await active_text.is_visible(timeout=2000):
            logger.info(f"✓ Background sync already active for {username}")
@@ -235,6 +551,18 @@ async def enable_background_sync_via_app_password(
    except Exception:
        pass

+    try:
+        # Check for Step 2 "Complete" badge (app password already set)
+        step2_section = page.locator('h4:has-text("Step 2")')
+        if await step2_section.count() > 0:
+            step2_parent = step2_section.locator("..")
+            complete_badge = step2_parent.get_by_text("Complete", exact=True)
+            if await complete_badge.count() > 0 and await complete_badge.is_visible():
+                logger.info(f"✓ Step 2 (app password) already complete for {username}")
+                return True
+    except Exception:
+        pass
+
    # Find the app password input field using the placeholder text
    # Based on manual testing: textbox with placeholder "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
    app_password_input = page.get_by_placeholder("xxxxx-xxxxx-xxxxx-xxxxx-xxxxx")
@@ -318,21 +646,120 @@ async def enable_background_sync_via_app_password(
    except Exception:
        pass

-    # Verify "Active" text appears after reload
+    # Verify Step 2 "Complete" badge or overall "Active" badge appears after reload
+    try:
+        # First try to find "Active" badge (both steps complete)
+        active_text = page.get_by_text("Active", exact=True)
+        if await active_text.count() > 0:
+            await active_text.wait_for(timeout=5000, state="visible")
+            logger.info(
+                f"✓ Background sync enabled for {username} - Active badge visible"
+            )
+            return True
+    except Exception:
+        pass
+
+    try:
+        # Check for Step 2 "Complete" badge
+        step2_section = page.locator('h4:has-text("Step 2")')
+        if await step2_section.count() > 0:
+            step2_parent = step2_section.locator("..")
+            complete_badge = step2_parent.get_by_text("Complete", exact=True)
+            await complete_badge.wait_for(timeout=5000, state="visible")
+            logger.info(
+                f"✓ Step 2 (app password) enabled for {username} - Complete badge visible"
+            )
+            return True
+    except Exception:
+        pass
+
+    # If neither badge found, raise error
+    screenshot_path = f"/tmp/astrolabe_after_password_{username}.png"
+    await page.screenshot(path=screenshot_path)
+    logger.error(
+        f"Neither Active nor Complete badge appeared for {username}. "
+        f"Screenshot: {screenshot_path}"
+    )
+    raise ValueError(f"Background sync setup did not complete for {username}")
+
+
+async def complete_astrolabe_authorization(
+    page: Page, username: str, password: str
+) -> dict:
+    """Complete full Astrolabe two-step authorization.
+
+    Performs the complete authorization flow:
+    1. Navigate to Astrolabe settings
+    2. OAuth authorization (Step 1) if needed
+    3. Generate app password in Security settings
+    4. App password entry (Step 2) if needed
+
+    Args:
+        page: Playwright page instance (must be logged in)
+        username: Nextcloud username
+        password: Nextcloud password (for reference, not used directly)
+
+    Returns:
+        Dict with {"step1": bool, "step2": bool, "app_password": str | None}
+    """
+    logger.info(f"Starting full Astrolabe authorization for {username}...")
+
+    result = {"step1": False, "step2": False, "app_password": None}
+
+    # Navigate to Astrolabe settings
+    await navigate_to_astrolabe_settings(page)
+
+    # Step 1: OAuth authorization
+    try:
+        result["step1"] = await authorize_search_access(page, username)
+        logger.info(f"✓ Step 1 complete for {username}")
+    except Exception as e:
+        logger.error(f"Step 1 failed for {username}: {e}")
+        raise
+
+    # Navigate back to settings if needed (OAuth might have redirected elsewhere)
+    if "/settings/user/astrolabe" not in page.url:
+        await navigate_to_astrolabe_settings(page)
+
+    # Check if Step 2 is already complete
+    try:
+        step2_section = page.locator('h4:has-text("Step 2")')
+        if await step2_section.count() > 0:
+            step2_parent = step2_section.locator("..")
+            complete_badge = step2_parent.get_by_text("Complete", exact=True)
+            if await complete_badge.count() > 0 and await complete_badge.is_visible():
+                logger.info(f"✓ Step 2 already complete for {username}")
+                result["step2"] = True
+                return result
+    except Exception:
+        pass
+
+    # Also check for overall "Active" badge
    try:
        active_text = page.get_by_text("Active", exact=True)
-        await active_text.wait_for(timeout=5000, state="visible")
-        logger.info(f"✓ Background sync enabled for {username} - Active badge visible")
-        return True
+        if await active_text.count() > 0 and await active_text.is_visible():
+            logger.info(f"✓ Authorization already fully active for {username}")
+            result["step2"] = True
+            return result
    except Exception:
-        # Take screenshot for debugging
-        screenshot_path = f"/tmp/astrolabe_after_password_{username}.png"
-        await page.screenshot(path=screenshot_path)
-        logger.error(
-            f"Active badge did not appear for {username}. Screenshot: {screenshot_path}"
+        pass
+
+    # Step 2: Generate app password and enter it
+    app_password = await generate_app_password(page, username)
+    result["app_password"] = app_password
+
+    try:
+        result["step2"] = await enable_background_sync_via_app_password(
+            page, username, app_password
        )
+        logger.info(f"✓ Step 2 complete for {username}")
+    except Exception as e:
+        logger.error(f"Step 2 failed for {username}: {e}")
        raise

+    logger.info(f"✓ Full Astrolabe authorization complete for {username}")
+    return result
+

 async def verify_app_password_created(username: str) -> bool:
    """Verify that background sync app password was stored for the user.
@@ -350,7 +777,6 @@ async def verify_app_password_created(username: str) -> bool:

    # Query the database to check for background sync credentials
    # Astrolabe stores app passwords in oc_preferences, not oc_authtoken
-    import subprocess

    query = f"""
    SELECT userid, configkey, configvalue
@@ -559,3 +985,259 @@ async def test_multi_user_astrolabe_background_sync_enablement(
    logger.info(
        f"\n✓ All {len(test_users)} users successfully enabled background sync via app passwords!"
    )
+
+
+async def revoke_background_sync_access(page: Page, username: str) -> bool:
+    """Revoke background sync access by clicking the Revoke Access button.
+
+    Args:
+        page: Playwright page instance (must be authenticated)
+        username: Username (for logging)
+
+    Returns:
+        True if revocation was successful
+    """
+    logger.info(f"Revoking background sync access for {username}...")
+
+    nextcloud_url = "http://localhost:8080"
+
+    # Set up network request and console listeners
+    network_requests = []
+    network_responses = []
+    console_messages = []
+
+    def log_request(req):
+        network_requests.append(f"{req.method} {req.url}")
+
+    def log_response(resp):
+        response_info = f"{resp.status} {resp.url}"
+        network_responses.append(response_info)
+        logger.info(f"Response: {response_info}")
+
+    def log_console(msg):
+        console_messages.append(f"[{msg.type}] {msg.text}")
+
+    page.on("request", log_request)
+    page.on("response", log_response)
+    page.on("console", log_console)
+
+    # Navigate to Astrolabe settings
+    await page.goto(
+        f"{nextcloud_url}/settings/user/astrolabe", wait_until="networkidle"
+    )
+
+    # Wait for page to load
+    await anyio.sleep(1)
+
+    # Check if "Active" badge is visible (indicating background sync is enabled)
+    try:
+        active_text = page.get_by_text("Active", exact=True)
+        if not await active_text.is_visible(timeout=2000):
+            logger.warning(
+                f"Background sync not active for {username}, nothing to revoke"
+            )
+            return False
+    except Exception:
+        logger.warning(f"Could not find Active badge for {username}")
+        return False
+
+    # Find the "Revoke Access" button
+    revoke_button = page.get_by_role("button", name="Revoke Access")
+
+    try:
+        await revoke_button.wait_for(timeout=5000, state="visible")
+        logger.info("Found Revoke Access button")
+    except Exception:
+        screenshot_path = f"/tmp/astrolabe_no_revoke_button_{username}.png"
+        await page.screenshot(path=screenshot_path)
+        raise ValueError(
+            f"Could not find Revoke Access button for {username}. Screenshot: {screenshot_path}"
+        )
+
+    # Set up dialog handler for confirmation dialog
+    page.once("dialog", lambda dialog: dialog.accept())
+
+    # Click the Revoke Access button
+    await revoke_button.click()
+    logger.info("Clicked Revoke Access button")
+
+    # Wait for the request to complete and page to reload
+    await page.wait_for_load_state("networkidle", timeout=15000)
+    await anyio.sleep(2)
+
+    # Log network requests after clicking
+    logger.info(f"Network requests after Revoke for {username}:")
+    for req in network_requests[-10:]:
+        logger.info(f"  {req}")
+
+    # Log network responses
+    logger.info(f"Network responses after Revoke for {username}:")
+    for resp in network_responses[-10:]:
+        logger.info(f"  {resp}")
+
+    # Check specifically for the revoke POST response
+    revoke_responses = [r for r in network_responses if "credentials/revoke" in r]
+    if revoke_responses:
+        logger.info(f"Revoke endpoint response: {revoke_responses[-1]}")
+        if "200" not in revoke_responses[-1]:
+            logger.error(f"Revoke POST did not return 200 OK: {revoke_responses[-1]}")
+            return False
+    else:
+        logger.warning("No response found for credentials/revoke endpoint!")
+        # Take screenshot for debugging
+        screenshot_path = f"/tmp/astrolabe_revoke_no_response_{username}.png"
+        await page.screenshot(path=screenshot_path)
+        return False
+
+    # Log any console messages
+    if console_messages:
+        logger.info(f"Console messages for {username}:")
+        for msg in console_messages:
+            logger.info(f"  {msg}")
+
+    # Check for error notifications (toast messages)
+    try:
+        error_toast = page.locator(".toastify.toast-error, .toast-error")
+        if await error_toast.count() > 0:
+            error_text = await error_toast.first.text_content()
+            logger.error(f"Error notification for {username}: {error_text}")
+            return False
+    except Exception:
+        pass
+
+    # Verify "Active" badge is no longer visible
+    try:
+        active_text = page.get_by_text("Active", exact=True)
+        if await active_text.is_visible(timeout=2000):
+            logger.error(f"Active badge still visible for {username} after revoke!")
+            screenshot_path = f"/tmp/astrolabe_revoke_still_active_{username}.png"
+            await page.screenshot(path=screenshot_path)
+            return False
+    except Exception:
+        pass
+
+    logger.info(f"✓ Background sync access revoked for {username}")
+    return True
+
+
+async def verify_app_password_deleted(username: str) -> bool:
+    """Verify that background sync app password was deleted for the user.
+
+    Args:
+        username: Nextcloud username
+
+    Returns:
+        True if background sync credentials no longer exist
+    """
+    logger.info(f"Verifying background sync credentials deleted for {username}...")
+
+    query = f"""
+    SELECT userid, configkey, configvalue
+    FROM oc_preferences
+    WHERE userid = '{username}'
+    AND appid = 'astrolabe'
+    AND configkey IN ('background_sync_password', 'background_sync_type', 'background_sync_provisioned_at')
+    ORDER BY configkey;
+    """
+
+    try:
+        result = subprocess.run(
+            [
+                "docker",
+                "compose",
+                "exec",
+                "-T",
+                "db",
+                "mariadb",
+                "-u",
+                "root",
+                "-ppassword",
+                "nextcloud",
+                "-e",
+                query,
+            ],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+
+        output = result.stdout
+        logger.debug(f"Background sync credentials query result:\n{output}")
+
+        # After deletion, we should NOT see background_sync_password
+        if "background_sync_password" not in output:
+            logger.info(f"✓ Background sync credentials deleted for {username}")
+            return True
+        else:
+            logger.warning(f"Background sync credentials still exist for {username}")
+            return False
+
+    except Exception as e:
+        logger.error(f"Error checking background sync credentials for {username}: {e}")
+        return False
+
+
+@pytest.mark.integration
+@pytest.mark.oauth
+async def test_revoke_background_sync_access(
+    browser,
+    nc_client,
+    test_users_setup,
+    configure_astrolabe_for_mcp_server,
+):
+    """Test that users can revoke background sync access via the Revoke Access button.
+
+    This test verifies:
+    1. User enables background sync via app password
+    2. User clicks "Revoke Access" button
+    3. Confirmation dialog is handled
+    4. POST request is sent to /api/v1/background-sync/credentials/revoke
+    5. "Active" badge disappears from settings page
+    6. Background sync credentials are deleted from database
+
+    This tests the fix for the issue where POST requests to the revoke endpoint
+    were returning errors due to HTTP method mismatch (was DELETE, now POST).
+    """
+    # Configure Astrolabe to point to the mcp-multi-user-basic server
+    logger.info("Configuring Astrolabe for mcp-multi-user-basic server...")
+    await configure_astrolabe_for_mcp_server(
+        mcp_server_internal_url="http://mcp-multi-user-basic:8000",
+        mcp_server_public_url="http://localhost:8003",
+    )
+
+    # Test with a single user for this specific test
+    username = "alice"
+    user_config = test_users_setup[username]
+    password = user_config["password"]
+
+    # Create new browser context
+    context = await browser.new_context(ignore_https_errors=True)
+    page = await context.new_page()
+
+    try:
+        # Step 1: Login to Nextcloud
+        await login_to_nextcloud(page, username, password)
+
+        # Step 2: Generate app password and enable background sync
+        app_password = await generate_app_password(page, username)
+        await enable_background_sync_via_app_password(page, username, app_password)
+
+        # Step 3: Verify background sync is enabled
+        assert await verify_app_password_created(username), (
+            f"Background sync not enabled for {username}"
+        )
+
+        # Step 4: Revoke background sync access
+        revoke_success = await revoke_background_sync_access(page, username)
+        assert revoke_success, f"Failed to revoke background sync access for {username}"
+
+        # Step 5: Verify credentials are deleted from database
+        credentials_deleted = await verify_app_password_deleted(username)
+        assert credentials_deleted, (
+            f"Background sync credentials not deleted for {username}"
+        )
+
+        logger.info(f"\n✓ Successfully revoked background sync access for {username}!")
+
+    finally:
+        await context.close()
@@ -0,0 +1,376 @@
+"""Integration test for Astrolabe Plotly 3D visualization with multi-user BasicAuth mode.
+
+Cross-system interface test: Tests the MCP server's integration with the
+Astrolabe Nextcloud app, which is installed from the Nextcloud app store via
+app-hooks/post-installation/20-install-astrolabe-app.sh. Astrolabe source
+lives in a separate repository (https://github.com/cbcoutinho/astrolabe).
+
+This test verifies that:
+1. User can provision background sync access via app password
+2. Content created via MCP tools is indexed by vector sync
+3. Semantic search via Astrolabe UI returns results
+4. Plotly 3D visualization container renders correctly
+
+Requires:
+- docker-compose up -d app db mcp-multi-user-basic
+- ENABLE_SEMANTIC_SEARCH=true on the mcp-multi-user-basic container
+"""
+
+import base64
+import json
+import logging
+import re
+import uuid
+
+import anyio
+import pytest
+from playwright.async_api import Page
+
+# Import helper functions from existing test
+from tests.conftest import create_mcp_client_session
+from tests.integration.test_astrolabe_multi_user_background_sync import (
+    complete_astrolabe_authorization,
+    login_to_nextcloud,
+)
+
+logger = logging.getLogger(__name__)
+
+pytestmark = [pytest.mark.integration, pytest.mark.oauth]
+
+
+async def wait_for_vector_sync(
+    mcp_client, initial_indexed_count: int, timeout_seconds: int = 60
+) -> tuple[bool, dict | None]:
+    """Wait for vector sync to index new content.
+
+    Args:
+        mcp_client: MCP client session
+        initial_indexed_count: Initial indexed document count before creating content
+        timeout_seconds: Maximum time to wait for sync
+
+    Returns:
+        Tuple of (success, status_data)
+    """
+    wait_interval = 2
+    waited = 0
+    status_data = None
+
+    while waited < timeout_seconds:
+        sync_status = await mcp_client.call_tool("nc_get_vector_sync_status", {})
+        if sync_status.isError:
+            logger.warning(f"Vector sync status error: {sync_status}")
+            return False, None
+
+        status_data = json.loads(sync_status.content[0].text)
+        indexed_count = status_data.get("indexed_count", 0)
+        pending_count = status_data.get("pending_count", 1)
+
+        logger.info(
+            f"Sync status at {waited}s: indexed={indexed_count}, "
+            f"pending={pending_count}, status={status_data.get('status')}"
+        )
+
+        if indexed_count > initial_indexed_count and pending_count == 0:
+            logger.info(
+                f"✓ Sync complete: {indexed_count} documents indexed "
+                f"(was {initial_indexed_count})"
+            )
+            return True, status_data
+
+        await anyio.sleep(wait_interval)
+        waited += wait_interval
+
+    return False, status_data
+
+
+async def navigate_to_astrolabe_main(page: Page):
+    """Navigate to Astrolabe main app page (Semantic Search section).
+
+    Args:
+        page: Playwright page instance (must be authenticated)
+    """
+    nextcloud_url = "http://localhost:8080"
+
+    logger.info("Navigating to Astrolabe main app...")
+    await page.goto(f"{nextcloud_url}/apps/astrolabe", wait_until="networkidle")
+
+    # Wait for the app to load
+    await anyio.sleep(1)
+
+    logger.info("✓ Successfully loaded Astrolabe main app")
+
+
+@pytest.mark.integration
+@pytest.mark.oauth
+@pytest.mark.timeout(
+    300
+)  # 5 minutes - this test involves OAuth, app password, and vector sync
+async def test_astrolabe_plotly_visualization_with_basic_auth(
+    browser,
+    test_users_setup,
+    configure_astrolabe_for_mcp_server,
+):
+    """Test Plotly 3D visualization in Astrolabe with multi-user BasicAuth mode.
+
+    This test:
+    1. Configures Astrolabe for the mcp-multi-user-basic service
+    2. Provisions background sync access for alice via app password
+    3. Creates a note with unique searchable content (as alice)
+    4. Waits for vector sync to index the note
+    5. Performs semantic search in Astrolabe UI
+    6. Verifies the Plotly visualization renders and results are displayed
+    """
+    # Phase 1: Configure Astrolabe for mcp-multi-user-basic
+    await configure_astrolabe_for_mcp_server(
+        mcp_server_internal_url="http://mcp-multi-user-basic:8000",
+        mcp_server_public_url="http://localhost:8003",
+    )
+
+    username = "alice"
+    password = test_users_setup[username]["password"]
+    note_id = None
+    unique_term = None
+
+    # Create MCP client with alice's credentials for the multi-user BasicAuth server
+    credentials = base64.b64encode(f"{username}:{password}".encode()).decode("utf-8")
+    auth_header = f"Basic {credentials}"
+
+    context = await browser.new_context(ignore_https_errors=True)
+    page = await context.new_page()
+
+    try:
+        # Phase 2: Complete full Astrolabe authorization (OAuth + app password)
+        await login_to_nextcloud(page, username, password)
+        auth_result = await complete_astrolabe_authorization(page, username, password)
+        logger.info(f"Authorization result: {auth_result}")
+
+        # Create MCP client session as alice - all MCP operations inside this block
+        async for alice_mcp_client in create_mcp_client_session(
+            url="http://localhost:8003/mcp",
+            headers={"Authorization": auth_header},
+            client_name="Alice BasicAuth MCP",
+        ):
+            # Phase 3: Get initial indexed count
+            initial_sync = await alice_mcp_client.call_tool(
+                "nc_get_vector_sync_status", {}
+            )
+
+            if initial_sync.isError:
+                pytest.skip("Vector sync not enabled on mcp-multi-user-basic")
+
+            initial_data = json.loads(initial_sync.content[0].text)
+            initial_count = initial_data.get("indexed_count", 0)
+            logger.info(f"Initial indexed count: {initial_count}")
+
+            # Create note with unique searchable term
+            unique_term = f"plotly_viz_test_{uuid.uuid4().hex[:8]}"
+            note_response = await alice_mcp_client.call_tool(
+                "nc_notes_create_note",
+                {
+                    "title": f"Visualization Test Note {unique_term}",
+                    "content": f"""# Testing Plotly Visualization
+
+This note contains the unique term: {unique_term}
+
+It is used to test the 3D vector space visualization in the Astrolabe app.
+The visualization should show this document as a point in PCA-reduced space.
+
+## Key Features
+- Semantic search with embeddings
+- PCA dimension reduction to 3D
+- Interactive Plotly scatter3d plot
+""",
+                    "category": "Test",
+                },
+            )
+
+            if note_response.isError:
+                pytest.fail(f"Failed to create test note: {note_response}")
+
+            note_data = json.loads(note_response.content[0].text)
+            note_id = note_data.get("id")
+            logger.info(f"Created test note ID: {note_id}")
+
+            # Phase 4: Wait for vector indexing
+            sync_complete, status = await wait_for_vector_sync(
+                alice_mcp_client, initial_count, timeout_seconds=90
+            )
+            assert sync_complete, f"Vector sync did not complete in time: {status}"
+
+            # Phase 5: Navigate to Astrolabe and perform search
+            await navigate_to_astrolabe_main(page)
+
+            # Fill search query - find the Astrolabe search input specifically
+            # The NcTextField component wraps the input in a div with class mcp-search-input
+            search_input = page.locator(".mcp-search-input input")
+            await search_input.wait_for(timeout=10000, state="visible")
+            await search_input.fill(unique_term)
+            logger.info(f"Entered search query: {unique_term}")
+
+            # Trigger search by pressing Enter on the input field
+            # This is wired to performSearch via @keyup.enter in the Vue component
+            await search_input.press("Enter")
+            logger.info("Pressed Enter to trigger search")
+
+            # Wait for loading to complete - watch for loading indicator to disappear
+            loading_indicator = page.locator(".mcp-loading")
+            try:
+                # If loading indicator appears, wait for it to disappear
+                if await loading_indicator.count() > 0:
+                    await loading_indicator.wait_for(state="hidden", timeout=30000)
+                    logger.info("Loading completed")
+            except Exception:
+                # Loading might be too fast to catch
+                pass
+
+            # Brief wait for UI to settle
+            await anyio.sleep(1)
+
+            # Take diagnostic screenshot
+            await page.screenshot(path="/tmp/astrolabe_search_after_click.png")
+            logger.info(
+                "Took diagnostic screenshot: /tmp/astrolabe_search_after_click.png"
+            )
+
+            # Wait for search results using text-based detection
+            # This is more reliable than class-based selectors
+            # The UI shows "N results" when search completes successfully
+            results_text_pattern = page.get_by_text(re.compile(r"\d+ results?"))
+            no_results_text = page.get_by_text("No results found")
+            error_note = page.locator(".mcp-error")
+
+            # Wait for one of: results count, no results message, or error
+            try:
+                # Poll for results or error states (don't rely on Nextcloud core CSS classes)
+                found_state = False
+                for attempt in range(60):  # 60 attempts, 500ms each = 30s total
+                    if await error_note.count() > 0:
+                        error_text = await error_note.text_content()
+                        logger.error(f"Search error: {error_text}")
+                        pytest.fail(f"Search failed with error: {error_text}")
+
+                    if await no_results_text.count() > 0:
+                        logger.warning(
+                            "No results found - vector sync may not have completed"
+                        )
+                        await page.screenshot(path="/tmp/astrolabe_no_results.png")
+                        pytest.fail(
+                            f"Search returned no results for '{unique_term}'. "
+                            "Check if vector sync completed for alice's content."
+                        )
+
+                    if await results_text_pattern.count() > 0:
+                        results_text = await results_text_pattern.first.text_content()
+                        logger.info(f"Found results: {results_text}")
+                        found_state = True
+                        break
+
+                    if attempt % 10 == 0:
+                        logger.info(
+                            f"Waiting for results... (attempt {attempt + 1}/60)"
+                        )
+
+                    await anyio.sleep(0.5)
+
+                if not found_state:
+                    await page.screenshot(path="/tmp/astrolabe_search_timeout.png")
+                    page_content = await page.content()
+                    logger.error(f"Search state not resolved. Page URL: {page.url}")
+                    logger.error(f"Page content snippet: {page_content[:2000]}")
+                    raise AssertionError("Search did not complete within timeout")
+
+            except AssertionError:
+                raise  # Re-raise AssertionError as-is
+            except Exception as e:
+                # Take another screenshot and get page content for debugging
+                await page.screenshot(path="/tmp/astrolabe_search_timeout.png")
+                page_content = await page.content()
+                logger.error(f"Search state not resolved. Page URL: {page.url}")
+                logger.error(f"Page content snippet: {page_content[:2000]}")
+                raise AssertionError(f"Search did not complete: {e}")
+
+            logger.info("Results loaded")
+
+            # Phase 6: Verify visualization
+            # Check Plotly container is visible
+            viz_plot = page.locator("#viz-plot")
+            await viz_plot.wait_for(timeout=15000, state="visible")
+            logger.info("Plotly container is visible")
+
+            # Verify Plotly has rendered content (SVG/canvas elements inside)
+            has_viz_content = await page.evaluate(
+                """
+                () => {
+                    const plot = document.getElementById('viz-plot');
+                    if (!plot) return false;
+                    // Plotly creates .plotly class, canvas, or svg elements
+                    return plot.children.length > 0 ||
+                           plot.querySelector('.plotly, canvas, svg, .main-svg') !== null;
+                }
+            """
+            )
+            assert has_viz_content, "Plotly visualization did not render any content"
+            logger.info("✓ Plotly visualization rendered content")
+
+            # Verify results are displayed
+            result_items = page.locator(".mcp-result-item")
+            result_count = await result_items.count()
+            assert result_count > 0, "No search results displayed"
+            logger.info(f"✓ Found {result_count} search result(s)")
+
+            # Verify our note appears in results
+            found_note = False
+            for i in range(result_count):
+                item = result_items.nth(i)
+                title_elem = item.locator(".mcp-result-title")
+                title_text = await title_elem.text_content()
+                if title_text and unique_term in title_text:
+                    found_note = True
+                    logger.info(f"✓ Found test note in results: {title_text}")
+                    break
+
+            assert found_note, f"Created note with '{unique_term}' not found in results"
+
+            # Optional: Take screenshot for verification
+            await page.screenshot(path="/tmp/astrolabe_plotly_test_success.png")
+            logger.info("✓ All Plotly visualization assertions passed")
+
+            # Cleanup: delete the created note (inside the MCP client context)
+            if note_id:
+                try:
+                    delete_response = await alice_mcp_client.call_tool(
+                        "nc_notes_delete_note", {"note_id": note_id}
+                    )
+                    if not delete_response.isError:
+                        logger.info(f"✓ Cleaned up test note {note_id}")
+                        note_id = None  # Mark as cleaned
+                    else:
+                        logger.warning(
+                            f"Failed to delete note {note_id}: {delete_response}"
+                        )
+                except Exception as e:
+                    logger.warning(f"Cleanup failed for note {note_id}: {e}")
+
+    finally:
+        # Cleanup note if not already cleaned (create new client for cleanup)
+        if note_id:
+            try:
+                async for cleanup_client in create_mcp_client_session(
+                    url="http://localhost:8003/mcp",
+                    headers={"Authorization": auth_header},
+                    client_name="Cleanup MCP",
+                ):
+                    delete_response = await cleanup_client.call_tool(
+                        "nc_notes_delete_note", {"note_id": note_id}
+                    )
+                    if not delete_response.isError:
+                        logger.info(f"✓ Cleaned up test note {note_id} (finally)")
+                    else:
+                        logger.warning(
+                            f"Failed to delete note {note_id}: {delete_response}"
+                        )
+            except Exception as e:
+                logger.warning(f"Cleanup failed for note {note_id}: {e}")
+
+        # Close browser context
+        await context.close()
@@ -1,5 +1,10 @@
 """Integration tests for Astrolabe personal settings page buttons.

+Cross-system interface test: Tests the MCP server's integration with the
+Astrolabe Nextcloud app, which is installed from the Nextcloud app store via
+app-hooks/post-installation/20-install-astrolabe-app.sh. Astrolabe source
+lives in a separate repository (https://github.com/cbcoutinho/astrolabe).
+
 Tests the button functionality on /settings/user/astrolabe:
 1. Disable Indexing button (POST to /apps/astrolabe/api/revoke)
 2. Disconnect button (POST to /apps/astrolabe/oauth/disconnect)
@@ -0,0 +1,700 @@
+"""Integration tests for Astrolabe token refresh flow.
+
+Cross-system interface test: Tests the MCP server's integration with the
+Astrolabe Nextcloud app, which is installed from the Nextcloud app store via
+app-hooks/post-installation/20-install-astrolabe-app.sh. Astrolabe source
+lives in a separate repository (https://github.com/cbcoutinho/astrolabe).
+
+Tests the token refresh mechanism between Astrolabe (Nextcloud app)
+and the MCP server backend in a multi-user basic auth deployment.
+
+This test verifies:
+1. User provisions access via Astrolabe personal settings
+2. Token is stored encrypted in Nextcloud database
+3. Token expires (simulated via database manipulation)
+4. MCP server requests new token via refresh
+5. Astrolabe refreshes token with IdP
+6. New token is stored and used successfully
+
+Note: The mcp-multi-user-basic deployment uses "hybrid mode" which requires
+BOTH OAuth authorization AND app password for full configuration. These tests
+focus on the app password/credential storage aspects and verify database state
+directly rather than relying on UI elements that require both steps.
+"""
+
+import logging
+import re
+import subprocess
+
+import anyio
+import pytest
+from playwright.async_api import Page
+
+pytestmark = [pytest.mark.integration, pytest.mark.oauth]
+
+logger = logging.getLogger(__name__)
+
+
+async def login_to_nextcloud(page: Page, username: str, password: str):
+    """Helper function to login to Nextcloud via Playwright.
+
+    Args:
+        page: Playwright page instance
+        username: Nextcloud username
+        password: Nextcloud password
+    """
+    nextcloud_url = "http://localhost:8080"
+
+    logger.info(f"Logging in to Nextcloud as {username}...")
+    await page.goto(f"{nextcloud_url}/login", wait_until="networkidle")
+
+    # Fill in login form
+    await page.wait_for_selector('input[name="user"]', timeout=10000)
+    await page.fill('input[name="user"]', username)
+    await page.fill('input[name="password"]', password)
+
+    # Submit form
+    await page.click('button[type="submit"]')
+    await page.wait_for_load_state("networkidle", timeout=30000)
+
+    # Verify logged in (should redirect away from login page)
+    current_url = page.url
+    assert "/login" not in current_url, (
+        f"Login failed for {username}, still on login page"
+    )
+    logger.info(f"✓ Successfully logged in as {username}")
+
+
+async def generate_app_password(
+    page: Page, username: str, app_name: str = "Astrolabe Test"
+) -> str:
+    """Generate an app password in Nextcloud Security settings.
+
+    Args:
+        page: Playwright page instance (must be authenticated)
+        username: Username (for logging)
+        app_name: Name for the app password
+
+    Returns:
+        The generated app password string
+    """
+    logger.info(f"Generating app password for {username}...")
+
+    nextcloud_url = "http://localhost:8080"
+
+    # Navigate to Security settings
+    await page.goto(f"{nextcloud_url}/settings/user/security", wait_until="networkidle")
+    logger.info("Navigated to Security settings")
+
+    # Fill the app password input field
+    app_password_input = page.locator('input[placeholder="App name"]')
+    await app_password_input.fill(app_name)
+    logger.info(f"Entered app name: {app_name}")
+
+    # Wait for Vue.js to react and enable the button
+    await anyio.sleep(1.0)
+
+    # Click the create button
+    create_button = page.locator(
+        'button[type="submit"]:has-text("Create new app password")'
+    )
+    await create_button.click()
+    logger.info("Clicked create app password button")
+
+    # Wait for app password to be generated
+    await anyio.sleep(3)
+
+    # Find the generated app password
+    app_password = None
+    try:
+        await page.wait_for_selector('text="New app password"', timeout=10000)
+        logger.info("App password dialog appeared")
+
+        all_inputs = await page.locator('input[type="text"]').all()
+        for idx, input_elem in enumerate(all_inputs):
+            try:
+                value = await input_elem.input_value()
+                if value and "-" in value and len(value) > 20:
+                    app_password = value.strip()
+                    logger.info(f"Found app password in input {idx}")
+                    break
+            except Exception:
+                continue
+    except Exception as e:
+        logger.error(f"Failed to find app password dialog: {e}")
+
+    if not app_password:
+        screenshot_path = f"/tmp/app_password_generation_{username}.png"
+        await page.screenshot(path=screenshot_path)
+        raise ValueError(
+            f"Could not find generated app password. Screenshot: {screenshot_path}"
+        )
+
+    # Validate password format
+    if not re.match(
+        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}$",
+        app_password,
+    ):
+        raise ValueError(f"App password format validation failed: {app_password}")
+
+    logger.info(f"✓ Generated app password for {username}")
+
+    # Close the dialog
+    close_button = page.get_by_role("button", name="Close")
+    await close_button.click()
+    await anyio.sleep(0.5)
+
+    return app_password
+
+
+async def save_app_password_in_astrolabe(
+    page: Page, username: str, app_password: str
+) -> bool:
+    """Save app password in Astrolabe settings (Step 2 of hybrid mode).
+
+    This function only saves the app password - it does NOT verify the "Active"
+    badge since that requires both OAuth and app password in hybrid mode.
+
+    Args:
+        page: Playwright page instance
+        username: Username (for logging)
+        app_password: App password to enter
+
+    Returns:
+        True if the password was saved successfully (based on network response)
+    """
+    logger.info(f"Saving app password in Astrolabe for {username}...")
+
+    nextcloud_url = "http://localhost:8080"
+
+    # Track network responses
+    credentials_response_status = None
+
+    def capture_response(resp):
+        nonlocal credentials_response_status
+        if "background-sync/credentials" in resp.url or "storeAppPassword" in resp.url:
+            credentials_response_status = resp.status
+            logger.info(f"Credentials endpoint response: {resp.status} {resp.url}")
+
+    page.on("response", capture_response)
+
+    # Navigate to Astrolabe settings
+    await page.goto(
+        f"{nextcloud_url}/settings/user/astrolabe", wait_until="networkidle"
+    )
+    await anyio.sleep(1)
+
+    # Check if Step 2 already shows "Complete"
+    try:
+        complete_badge = page.locator('text="Complete"').first
+        if await complete_badge.is_visible(timeout=2000):
+            logger.info(f"✓ App password already configured for {username}")
+            return True
+    except Exception:
+        pass
+
+    # Find the app password input field
+    app_password_input = page.get_by_placeholder("xxxxx-xxxxx-xxxxx-xxxxx-xxxxx")
+
+    try:
+        await app_password_input.wait_for(timeout=5000, state="visible")
+        logger.info("Found app password input field")
+    except Exception:
+        screenshot_path = f"/tmp/astrolabe_no_password_field_{username}.png"
+        await page.screenshot(path=screenshot_path)
+        raise ValueError(
+            f"Could not find app password input field. Screenshot: {screenshot_path}"
+        )
+
+    # Enter the app password
+    await app_password_input.fill(app_password)
+    logger.info(f"Entered app password for {username}")
+
+    await anyio.sleep(0.5)
+
+    # Click Save button
+    save_button = page.get_by_role("button", name="Save")
+    await save_button.click()
+    logger.info("Clicked Save button")
+
+    # Wait for the request to complete and page to reload
+    await page.wait_for_load_state("networkidle", timeout=15000)
+    await anyio.sleep(2)
+
+    # Verify the save was successful by checking network response
+    if credentials_response_status == 200:
+        logger.info(f"✓ App password saved successfully for {username}")
+        return True
+    else:
+        logger.error(
+            f"App password save failed for {username}, status: {credentials_response_status}"
+        )
+        screenshot_path = f"/tmp/astrolabe_save_failed_{username}.png"
+        await page.screenshot(path=screenshot_path)
+        return False
+
+
+def get_background_sync_credentials(username: str) -> dict | None:
+    """Get background sync credentials for a user from the database.
+
+    Args:
+        username: Nextcloud username
+
+    Returns:
+        Dict with credential details, or None if not found
+    """
+    query = f"""
+    SELECT configkey, configvalue
+    FROM oc_preferences
+    WHERE userid = '{username}'
+    AND appid = 'astrolabe'
+    AND configkey IN ('background_sync_password', 'background_sync_type', 'background_sync_provisioned_at')
+    ORDER BY configkey;
+    """
+
+    try:
+        result = subprocess.run(
+            [
+                "docker",
+                "compose",
+                "exec",
+                "-T",
+                "db",
+                "mariadb",
+                "-u",
+                "root",
+                "-ppassword",
+                "nextcloud",
+                "-e",
+                query,
+            ],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+
+        output = result.stdout
+        if "background_sync_type" in output:
+            return {
+                "has_password": "background_sync_password" in output,
+                "has_type": "background_sync_type" in output,
+                "has_timestamp": "background_sync_provisioned_at" in output,
+                "is_app_password": "app_password" in output,
+            }
+        return None
+
+    except Exception as e:
+        logger.error(f"Error getting credentials for {username}: {e}")
+        return None
+
+
+def delete_user_credentials(username: str) -> bool:
+    """Delete all stored credentials for a user (for cleanup).
+
+    Args:
+        username: Nextcloud username
+
+    Returns:
+        True if successful
+    """
+    query = f"""
+    DELETE FROM oc_preferences
+    WHERE userid = '{username}'
+    AND appid = 'astrolabe'
+    AND configkey IN ('oauth_tokens', 'background_sync_password', 'background_sync_type', 'background_sync_provisioned_at');
+    """
+
+    try:
+        result = subprocess.run(
+            [
+                "docker",
+                "compose",
+                "exec",
+                "-T",
+                "db",
+                "mariadb",
+                "-u",
+                "root",
+                "-ppassword",
+                "nextcloud",
+                "-e",
+                query,
+            ],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+
+        logger.info(f"Deleted credentials for {username}")
+        return result.returncode == 0
+
+    except Exception as e:
+        logger.error(f"Error deleting credentials for {username}: {e}")
+        return False
+
+
+@pytest.mark.integration
+@pytest.mark.oauth
+async def test_app_password_storage_and_cleanup(
+    browser,
+    nc_client,
+    test_users_setup,
+    configure_astrolabe_for_mcp_server,
+):
+    """Test that app passwords are stored and cleaned up correctly.
+
+    This test verifies:
+    1. User can save app password in Astrolabe settings
+    2. Password is stored encrypted in the database
+    3. Credentials can be revoked and are deleted from database
+
+    Note: In hybrid mode (mcp-multi-user-basic), this only tests Step 2
+    (app password storage). The "Active" badge requires both OAuth and
+    app password, which is tested separately.
+    """
+    # Configure Astrolabe for mcp-multi-user-basic
+    logger.info("Configuring Astrolabe for mcp-multi-user-basic server...")
+    await configure_astrolabe_for_mcp_server(
+        mcp_server_internal_url="http://mcp-multi-user-basic:8000",
+        mcp_server_public_url="http://localhost:8003",
+    )
+
+    username = "alice"
+    user_config = test_users_setup[username]
+    password = user_config["password"]
+
+    # Cleanup any existing credentials
+    delete_user_credentials(username)
+
+    context = await browser.new_context(ignore_https_errors=True)
+    page = await context.new_page()
+
+    try:
+        # Step 1: Login
+        await login_to_nextcloud(page, username, password)
+
+        # Step 2: Verify no credentials exist initially
+        initial_creds = get_background_sync_credentials(username)
+        assert initial_creds is None, f"Expected no credentials, found: {initial_creds}"
+        logger.info("✓ Verified no initial credentials")
+
+        # Step 3: Generate app password
+        app_password = await generate_app_password(page, username)
+        assert app_password, "Failed to generate app password"
+
+        # Step 4: Save app password in Astrolabe
+        save_success = await save_app_password_in_astrolabe(
+            page, username, app_password
+        )
+        assert save_success, "Failed to save app password"
+
+        # Step 5: Verify credentials are stored in database
+        stored_creds = get_background_sync_credentials(username)
+        assert stored_creds is not None, "Expected credentials to be stored"
+        assert stored_creds["has_password"], "Expected password to be stored"
+        assert stored_creds["has_type"], "Expected type to be stored"
+        assert stored_creds["is_app_password"], "Expected type to be 'app_password'"
+        logger.info("✓ Verified credentials stored in database")
+
+        # Step 6: Verify password is encrypted (not plaintext)
+        query = f"""
+        SELECT configvalue
+        FROM oc_preferences
+        WHERE userid = '{username}'
+        AND appid = 'astrolabe'
+        AND configkey = 'background_sync_password';
+        """
+
+        result = subprocess.run(
+            [
+                "docker",
+                "compose",
+                "exec",
+                "-T",
+                "db",
+                "mariadb",
+                "-u",
+                "root",
+                "-ppassword",
+                "nextcloud",
+                "-N",
+                "-e",
+                query,
+            ],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+
+        encrypted_value = result.stdout.strip()
+        assert app_password not in encrypted_value, "Password appears in plaintext!"
+        assert len(encrypted_value) > len(app_password), (
+            "Encrypted value should be longer"
+        )
+        logger.info("✓ Verified password is encrypted")
+
+    finally:
+        await context.close()
+        # Cleanup
+        delete_user_credentials(username)
+
+
+@pytest.mark.integration
+@pytest.mark.oauth
+async def test_credential_isolation_between_users(
+    browser,
+    nc_client,
+    test_users_setup,
+    configure_astrolabe_for_mcp_server,
+):
+    """Test that credentials are properly isolated between users.
+
+    This test verifies:
+    1. Multiple users can provision credentials independently
+    2. Each user's encrypted credentials are unique
+    3. Deleting one user's credentials doesn't affect others
+    """
+    await configure_astrolabe_for_mcp_server(
+        mcp_server_internal_url="http://mcp-multi-user-basic:8000",
+        mcp_server_public_url="http://localhost:8003",
+    )
+
+    test_users = ["alice", "bob"]
+    user_passwords = {}
+
+    # Cleanup all users first
+    for username in test_users:
+        delete_user_credentials(username)
+
+    # Provision each user
+    for username in test_users:
+        user_config = test_users_setup[username]
+        password = user_config["password"]
+
+        context = await browser.new_context(ignore_https_errors=True)
+        page = await context.new_page()
+
+        try:
+            await login_to_nextcloud(page, username, password)
+            app_password = await generate_app_password(
+                page, username, f"Test {username}"
+            )
+            save_success = await save_app_password_in_astrolabe(
+                page, username, app_password
+            )
+
+            assert save_success, f"Failed to save app password for {username}"
+            user_passwords[username] = app_password
+
+            # Verify stored
+            creds = get_background_sync_credentials(username)
+            assert creds is not None, f"Credentials not stored for {username}"
+            logger.info(f"✓ Credentials provisioned for {username}")
+
+        finally:
+            await context.close()
+
+    # Verify isolation - get encrypted values
+    encrypted_values = {}
+    for username in test_users:
+        query = f"""
+        SELECT configvalue
+        FROM oc_preferences
+        WHERE userid = '{username}'
+        AND appid = 'astrolabe'
+        AND configkey = 'background_sync_password';
+        """
+
+        result = subprocess.run(
+            [
+                "docker",
+                "compose",
+                "exec",
+                "-T",
+                "db",
+                "mariadb",
+                "-u",
+                "root",
+                "-ppassword",
+                "nextcloud",
+                "-N",
+                "-e",
+                query,
+            ],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        encrypted_values[username] = result.stdout.strip()
+
+    # Different users should have different encrypted values
+    assert encrypted_values["alice"] != encrypted_values["bob"], (
+        "Different users should have different encrypted values"
+    )
+    logger.info("✓ Verified credentials are unique per user")
+
+    # Delete alice's credentials and verify bob's are unaffected
+    delete_user_credentials("alice")
+
+    alice_creds = get_background_sync_credentials("alice")
+    bob_creds = get_background_sync_credentials("bob")
+
+    assert alice_creds is None, "Alice's credentials should be deleted"
+    assert bob_creds is not None, "Bob's credentials should still exist"
+    logger.info("✓ Verified credential deletion is isolated")
+
+    # Cleanup
+    for username in test_users:
+        delete_user_credentials(username)
+
+
+@pytest.mark.integration
+@pytest.mark.oauth
+async def test_credential_revoke_and_reprovision(
+    browser,
+    nc_client,
+    test_users_setup,
+    configure_astrolabe_for_mcp_server,
+):
+    """Test that credentials can be revoked and reprovisioned.
+
+    This test verifies:
+    1. User provisions credentials
+    2. User revokes credentials (deletes from database)
+    3. User provisions again with new app password
+    4. New credentials are stored correctly
+
+    Note: The UI prevents overwriting credentials directly - users must
+    revoke first before provisioning new credentials.
+    """
+    await configure_astrolabe_for_mcp_server(
+        mcp_server_internal_url="http://mcp-multi-user-basic:8000",
+        mcp_server_public_url="http://localhost:8003",
+    )
+
+    username = "alice"
+    user_config = test_users_setup[username]
+    password = user_config["password"]
+
+    delete_user_credentials(username)
+
+    context = await browser.new_context(ignore_https_errors=True)
+    page = await context.new_page()
+
+    try:
+        await login_to_nextcloud(page, username, password)
+
+        # First provisioning
+        app_password_1 = await generate_app_password(page, username, "First Password")
+        await save_app_password_in_astrolabe(page, username, app_password_1)
+
+        # Get first encrypted value
+        query = f"""
+        SELECT configvalue
+        FROM oc_preferences
+        WHERE userid = '{username}'
+        AND appid = 'astrolabe'
+        AND configkey = 'background_sync_password';
+        """
+
+        result1 = subprocess.run(
+            [
+                "docker",
+                "compose",
+                "exec",
+                "-T",
+                "db",
+                "mariadb",
+                "-u",
+                "root",
+                "-ppassword",
+                "nextcloud",
+                "-N",
+                "-e",
+                query,
+            ],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        first_encrypted = result1.stdout.strip()
+        assert first_encrypted, "First credential should be stored"
+        logger.info("✓ First credential stored")
+
+        # Revoke credentials (simulating user clicking "Revoke Access")
+        delete_user_credentials(username)
+        logger.info("✓ Credentials revoked")
+
+        # Verify credentials are gone
+        creds_after_revoke = get_background_sync_credentials(username)
+        assert creds_after_revoke is None, "Credentials should be deleted after revoke"
+
+        # Second provisioning with different password
+        app_password_2 = await generate_app_password(page, username, "Second Password")
+        await save_app_password_in_astrolabe(page, username, app_password_2)
+
+        result2 = subprocess.run(
+            [
+                "docker",
+                "compose",
+                "exec",
+                "-T",
+                "db",
+                "mariadb",
+                "-u",
+                "root",
+                "-ppassword",
+                "nextcloud",
+                "-N",
+                "-e",
+                query,
+            ],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        second_encrypted = result2.stdout.strip()
+        assert second_encrypted, "Second credential should be stored"
+        logger.info("✓ Second credential stored")
+
+        # Verify the encrypted values are different (different passwords)
+        assert first_encrypted != second_encrypted, (
+            "Different passwords should produce different encrypted values"
+        )
+
+        # Verify only one row exists
+        count_query = f"""
+        SELECT COUNT(*)
+        FROM oc_preferences
+        WHERE userid = '{username}'
+        AND appid = 'astrolabe'
+        AND configkey = 'background_sync_password';
+        """
+
+        count_result = subprocess.run(
+            [
+                "docker",
+                "compose",
+                "exec",
+                "-T",
+                "db",
+                "mariadb",
+                "-u",
+                "root",
+                "-ppassword",
+                "nextcloud",
+                "-N",
+                "-e",
+                count_query,
+            ],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        count = int(count_result.stdout.strip())
+        assert count == 1, f"Expected 1 credential row, found {count}"
+        logger.info("✓ Verified clean reprovision after revoke")
+
+    finally:
+        await context.close()
+        delete_user_credentials(username)
@@ -0,0 +1,177 @@
+"""Integration tests for Deck card reorder functionality.
+
+Tests issue #469: Moving Deck card from one column (stack) to another not working.
+https://github.com/cbcoutinho/nextcloud-mcp-server/issues/469
+"""
+
+import logging
+import uuid
+
+import pytest
+
+from nextcloud_mcp_server.client import NextcloudClient
+
+logger = logging.getLogger(__name__)
+pytestmark = pytest.mark.integration
+
+
+@pytest.fixture
+async def board_with_two_stacks(nc_client: NextcloudClient):
+    """Create a temporary board with two stacks for testing card movement.
+
+    Yields:
+        tuple: (board_data, source_stack_data, target_stack_data)
+    """
+    unique_suffix = uuid.uuid4().hex[:8]
+    board_title = f"Reorder Test Board {unique_suffix}"
+    board = None
+
+    logger.info(f"Creating board with two stacks: {board_title}")
+    try:
+        board = await nc_client.deck.create_board(board_title, "0000FF")
+        board_id = board.id
+
+        # Create source stack (stack 1)
+        source_stack = await nc_client.deck.create_stack(
+            board_id, f"Source Stack {unique_suffix}", order=1
+        )
+        source_stack_data = {
+            "id": source_stack.id,
+            "title": source_stack.title,
+            "order": source_stack.order,
+        }
+        logger.info(f"Created source stack with ID: {source_stack.id}")
+
+        # Create target stack (stack 2)
+        target_stack = await nc_client.deck.create_stack(
+            board_id, f"Target Stack {unique_suffix}", order=2
+        )
+        target_stack_data = {
+            "id": target_stack.id,
+            "title": target_stack.title,
+            "order": target_stack.order,
+        }
+        logger.info(f"Created target stack with ID: {target_stack.id}")
+
+        board_data = {
+            "id": board_id,
+            "title": board.title,
+            "color": board.color,
+        }
+
+        yield (board_data, source_stack_data, target_stack_data)
+
+    finally:
+        if board:
+            logger.info(f"Cleaning up board ID: {board.id}")
+            try:
+                await nc_client.deck.delete_board(board.id)
+            except Exception as e:
+                logger.warning(f"Error cleaning up board: {e}")
+
+
+async def test_reorder_card_move_to_different_stack(
+    nc_client: NextcloudClient, board_with_two_stacks: tuple
+):
+    """Test moving a card from one stack to another (issue #469).
+
+    This test reproduces the bug where the reorder_card API reports success
+    but the card doesn't actually move to the target stack.
+    """
+    board_data, source_stack_data, target_stack_data = board_with_two_stacks
+    board_id = board_data["id"]
+    source_stack_id = source_stack_data["id"]
+    target_stack_id = target_stack_data["id"]
+
+    # Create a card in the source stack
+    unique_suffix = uuid.uuid4().hex[:8]
+    card_title = f"Test Card {unique_suffix}"
+    card = await nc_client.deck.create_card(
+        board_id, source_stack_id, card_title, description="Card to be moved"
+    )
+    card_id = card.id
+    logger.info(f"Created card ID: {card_id} in source stack ID: {source_stack_id}")
+
+    try:
+        # Verify card is in source stack
+        card_before = await nc_client.deck.get_card(board_id, source_stack_id, card_id)
+        assert card_before.stackId == source_stack_id, (
+            f"Card should start in source stack {source_stack_id}, "
+            f"but is in {card_before.stackId}"
+        )
+        logger.info(f"Verified card is in source stack: {source_stack_id}")
+
+        # Move card to target stack
+        logger.info(
+            f"Moving card {card_id} from stack {source_stack_id} "
+            f"to stack {target_stack_id}"
+        )
+        await nc_client.deck.reorder_card(
+            board_id=board_id,
+            stack_id=source_stack_id,
+            card_id=card_id,
+            order=0,
+            target_stack_id=target_stack_id,
+        )
+        logger.info("reorder_card API call completed")
+
+        # Verify card moved to target stack
+        # Note: After moving, the card should be accessible from the target stack
+        card_after = await nc_client.deck.get_card(board_id, target_stack_id, card_id)
+        assert card_after.stackId == target_stack_id, (
+            f"Card should have moved to target stack {target_stack_id}, "
+            f"but is in {card_after.stackId}"
+        )
+        logger.info(f"SUCCESS: Card moved to target stack {target_stack_id}")
+
+    finally:
+        # Clean up - try to delete from target stack first, then source
+        try:
+            await nc_client.deck.delete_card(board_id, target_stack_id, card_id)
+        except Exception:
+            try:
+                await nc_client.deck.delete_card(board_id, source_stack_id, card_id)
+            except Exception as e:
+                logger.warning(f"Error cleaning up card: {e}")
+
+
+async def test_reorder_card_within_same_stack(
+    nc_client: NextcloudClient, board_with_two_stacks: tuple
+):
+    """Test reordering a card within the same stack (should work)."""
+    board_data, source_stack_data, _ = board_with_two_stacks
+    board_id = board_data["id"]
+    source_stack_id = source_stack_data["id"]
+
+    # Create two cards in the source stack
+    unique_suffix = uuid.uuid4().hex[:8]
+    card1 = await nc_client.deck.create_card(
+        board_id, source_stack_id, f"Card 1 {unique_suffix}", order=0
+    )
+    card2 = await nc_client.deck.create_card(
+        board_id, source_stack_id, f"Card 2 {unique_suffix}", order=1
+    )
+    logger.info(f"Created cards {card1.id} (order 0) and {card2.id} (order 1)")
+
+    try:
+        # Reorder card1 to position after card2
+        await nc_client.deck.reorder_card(
+            board_id=board_id,
+            stack_id=source_stack_id,
+            card_id=card1.id,
+            order=2,  # Move to position 2
+            target_stack_id=source_stack_id,  # Same stack
+        )
+        logger.info(f"Reordered card {card1.id} to order 2")
+
+        # Verify card is still in the same stack
+        card_after = await nc_client.deck.get_card(board_id, source_stack_id, card1.id)
+        assert card_after.stackId == source_stack_id
+        logger.info("Card reorder within same stack succeeded")
+
+    finally:
+        try:
+            await nc_client.deck.delete_card(board_id, source_stack_id, card1.id)
+            await nc_client.deck.delete_card(board_id, source_stack_id, card2.id)
+        except Exception as e:
+            logger.warning(f"Error cleaning up cards: {e}")
@@ -4,18 +4,26 @@ Tests that BasicAuth credentials are extracted from request headers
 and passed through to Nextcloud APIs without storage (stateless).
 """

+import json
+
 import pytest


@pytest.mark.integration
-async def test_basic_auth_pass_through_notes_list(nc_mcp_basic_auth_client):
-    """Test BasicAuth pass-through with notes list tool."""
+async def test_basic_auth_pass_through_notes_search(nc_mcp_basic_auth_client):
+    """Test BasicAuth pass-through with notes search tool."""
    # Call tool - BasicAuth header is set at connection level by fixture
-    response = await nc_mcp_basic_auth_client.call_tool("nc_notes_list", {})
+    response = await nc_mcp_basic_auth_client.call_tool(
+        "nc_notes_search_notes", {"query": "test"}
+    )

    # Verify tool executed successfully with pass-through auth
    assert response is not None
-    assert "results" in response or "content" in response
+    assert not response.isError, f"Tool returned error: {response.content}"
+    # Response should have content with results
+    assert len(response.content) > 0
+    data = json.loads(response.content[0].text)
+    assert "results" in data


@pytest.mark.integration
@@ -23,7 +31,7 @@ async def test_basic_auth_pass_through_notes_create(nc_mcp_basic_auth_client):
    """Test BasicAuth pass-through with notes create tool."""
    # Create a note using BasicAuth
    response = await nc_mcp_basic_auth_client.call_tool(
-        "nc_notes_create",
+        "nc_notes_create_note",
        {
            "title": "BasicAuth Test Note",
            "content": "This note was created via BasicAuth pass-through",
@@ -32,16 +40,35 @@ async def test_basic_auth_pass_through_notes_create(nc_mcp_basic_auth_client):
    )

    assert response is not None
-    assert response.get("success") is True or "note_id" in response
+    assert not response.isError, f"Tool returned error: {response.content}"
+    # Parse response and verify note was created
+    data = json.loads(response.content[0].text)
+    assert data.get("success") is True or "note_id" in data


@pytest.mark.integration
-async def test_basic_auth_pass_through_search(nc_mcp_basic_auth_client):
-    """Test BasicAuth pass-through with search tool."""
-    # Search notes using BasicAuth
+async def test_basic_auth_pass_through_get_note(nc_mcp_basic_auth_client):
+    """Test BasicAuth pass-through with get note tool."""
+    # First create a note to get
+    create_response = await nc_mcp_basic_auth_client.call_tool(
+        "nc_notes_create_note",
+        {
+            "title": "BasicAuth Get Test",
+            "content": "Note to retrieve",
+            "category": "Test",
+        },
+    )
+    assert not create_response.isError
+    create_data = json.loads(create_response.content[0].text)
+    note_id = create_data.get("id")
+
+    # Now get the note using BasicAuth
    response = await nc_mcp_basic_auth_client.call_tool(
-        "nc_notes_search", {"query": "BasicAuth"}
+        "nc_notes_get_note", {"note_id": note_id}
    )

    assert response is not None
-    assert "results" in response or "content" in response
+    assert not response.isError, f"Tool returned error: {response.content}"
+    data = json.loads(response.content[0].text)
+    # Nextcloud may append a number to duplicate titles
+    assert data.get("title", "").startswith("BasicAuth Get Test")
@@ -10,12 +10,21 @@ These tests validate that:
 from unittest.mock import Mock

 import pytest
+from qdrant_client.models import VectorParams

 from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client

 pytestmark = pytest.mark.integration


+def get_vector_params(collection_info) -> VectorParams:
+    """Get vector params from collection info, handling named vectors format."""
+    vectors = collection_info.config.params.vectors
+    if isinstance(vectors, dict):
+        return vectors["dense"]
+    return vectors
+
+
@pytest.fixture(autouse=True)
 async def reset_singleton():
    """Reset the global Qdrant client singleton between tests."""
@@ -75,7 +84,7 @@ async def test_collection_auto_created_on_first_access(monkeypatch):

    # Verify collection has correct dimensions
    collection_info = await client.get_collection(collection_name)
-    assert collection_info.config.params.vectors.size == 384
+    assert get_vector_params(collection_info).size == 384


@pytest.mark.integration
@@ -127,7 +136,7 @@ async def test_existing_collection_reused(monkeypatch):

    # Verify dimensions unchanged
    collection_info = await client2.get_collection(collection_name)
-    assert collection_info.config.params.vectors.size == 384
+    assert get_vector_params(collection_info).size == 384


@pytest.mark.integration
@@ -164,7 +173,7 @@ async def test_dimension_mismatch_detected(monkeypatch, tmp_path):

    # Verify collection created
    collection_info = await client1.get_collection(collection_name)
-    assert collection_info.config.params.vectors.size == 384
+    assert get_vector_params(collection_info).size == 384

    # Close client1 to release file lock
    await client1.close()
@@ -248,12 +257,10 @@ async def test_collection_name_generation(monkeypatch):
    mock_settings = Settings(
        qdrant_location=":memory:",
        ollama_embedding_model="test-model",
+        otel_service_name="test-deployment",
        vector_sync_enabled=False,
    )

-    # Mock deployment ID
-    monkeypatch.setenv("MCP_DEPLOYMENT_ID", "test-deployment")
-
    monkeypatch.setattr(
        "nextcloud_mcp_server.vector.qdrant_client.get_settings", lambda: mock_settings
    )
@@ -319,4 +326,4 @@ async def test_collection_uses_cosine_distance(monkeypatch):

    from qdrant_client.models import Distance

-    assert collection_info.config.params.vectors.distance == Distance.COSINE
+    assert get_vector_params(collection_info).distance == Distance.COSINE
@@ -51,6 +51,14 @@ logger = logging.getLogger(__name__)
 DEFAULT_MANUAL_PATH = "Nextcloud Manual.pdf"


+async def require_vector_sync_tools(nc_mcp_client):
+    """Skip test if vector sync tools are not available."""
+    tools = await nc_mcp_client.list_tools()
+    tool_names = [t.name for t in tools.tools]
+    if "nc_get_vector_sync_status" not in tool_names:
+        pytest.skip("Vector sync tools not available (VECTOR_SYNC_ENABLED not set)")
+
+
 async def llm_judge(
    provider: Provider,
    ground_truth: str,
@@ -116,6 +124,8 @@ async def indexed_manual_pdf(nc_client, nc_mcp_client):
    Environment Variables:
        RAG_MANUAL_PATH: Path to manual PDF in Nextcloud (default: Nextcloud Manual.pdf)
    """
+    await require_vector_sync_tools(nc_mcp_client)
+
    manual_path = os.getenv("RAG_MANUAL_PATH", DEFAULT_MANUAL_PATH)

    logger.info(f"Setting up indexed manual PDF: {manual_path}")
@@ -152,7 +162,7 @@ async def indexed_manual_pdf(nc_client, nc_mcp_client):
            )

            if not result.isError:
-                content = result.structuredContent or {}
+                content = json.loads(result.content[0].text) if result.content else {}
                indexed = content.get("indexed_count", 0)
                pending = content.get("pending_count", 1)

@@ -248,7 +258,7 @@ async def test_semantic_search_retrieval(
    )

    assert result.isError is False, f"Tool call failed: {result}"
-    data = result.structuredContent
+    data = json.loads(result.content[0].text)

    # Verify we got results
    assert data["success"] is True
@@ -295,7 +305,7 @@ async def test_semantic_search_answer_with_sampling(
    )

    assert result.isError is False, f"Tool call failed: {result}"
-    data = result.structuredContent
+    data = json.loads(result.content[0].text)

    # Verify response structure
    assert data["success"] is True
@@ -369,7 +379,7 @@ async def test_retrieval_quality_all_queries(
    )

    assert result.isError is False
-    data = result.structuredContent
+    data = json.loads(result.content[0].text)

    assert data["total_found"] >= min_expected_results, (
        f"Query '{query}' returned {data['total_found']} results, "
@@ -393,7 +403,7 @@ async def test_no_results_for_unrelated_query(nc_mcp_client, indexed_manual_pdf)
    )

    assert result.isError is False
-    data = result.structuredContent
+    data = json.loads(result.content[0].text)

    # Should have few or no high-scoring results
    # Low score threshold means we might get some results, but they should be low quality
@@ -13,14 +13,24 @@ Note: These tests require VECTOR_SYNC_ENABLED=true and a configured
 vector database with indexed test data.
 """

+import json
 from unittest.mock import MagicMock

+import anyio
 import pytest
 from mcp.types import CreateMessageResult, TextContent

 pytestmark = pytest.mark.integration


+async def require_vector_sync_tools(nc_mcp_client):
+    """Skip test if vector sync tools are not available."""
+    tools = await nc_mcp_client.list_tools()
+    tool_names = [t.name for t in tools.tools]
+    if "nc_get_vector_sync_status" not in tool_names:
+        pytest.skip("Vector sync tools not available (VECTOR_SYNC_ENABLED not set)")
+
+
@pytest.fixture
 def mock_sampling_result():
    """Mock successful sampling result from MCP client."""
@@ -55,13 +65,14 @@ async def test_semantic_search_answer_successful_sampling(
    4. Mock ctx.session.create_message to return answer
    5. Verify response contains generated answer and sources
    """
+    await require_vector_sync_tools(nc_mcp_client)
+
    # Get initial indexed count before creating note
-    import asyncio

    initial_sync = await nc_mcp_client.call_tool(
        "nc_get_vector_sync_status", arguments={}
    )
-    initial_indexed_count = initial_sync.structuredContent["indexed_count"]
+    initial_indexed_count = json.loads(initial_sync.content[0].text)["indexed_count"]
    print(f"Initial indexed count: {initial_indexed_count}")

    # Create a note with content about Python async
@@ -90,7 +101,7 @@ Avoid blocking operations in async code.""",
        sync_status = await nc_mcp_client.call_tool(
            "nc_get_vector_sync_status", arguments={}
        )
-        status_data = sync_status.structuredContent
+        status_data = json.loads(sync_status.content[0].text)

        print(
            f"Sync status at {waited}s: indexed={status_data['indexed_count']}, pending={status_data['pending_count']}, status={status_data['status']}"
@@ -107,7 +118,7 @@ Avoid blocking operations in async code.""",
            )
            break

-        await asyncio.sleep(wait_interval)
+        await anyio.sleep(wait_interval)
        waited += wait_interval

    # Verify sync completed
@@ -135,7 +146,7 @@ Avoid blocking operations in async code.""",
    assert call_result.isError is False, (
        f"Tool call failed: {call_result.content[0].text if call_result.isError else ''}"
    )
-    result = call_result.structuredContent
+    result = json.loads(call_result.content[0].text)

    # Verify response structure
    assert result is not None
@@ -179,6 +190,8 @@ async def test_semantic_search_answer_no_results(nc_mcp_client):
    2. Verify response indicates no documents found
    3. Verify no sampling call was made (no sources to base answer on)
    """
+    await require_vector_sync_tools(nc_mcp_client)
+
    call_result = await nc_mcp_client.call_tool(
        "nc_semantic_search_answer",
        arguments={
@@ -192,7 +205,7 @@ async def test_semantic_search_answer_no_results(nc_mcp_client):
    assert call_result.isError is False, (
        f"Tool call failed: {call_result.content[0].text if call_result.isError else ''}"
    )
-    result = call_result.structuredContent
+    result = json.loads(call_result.content[0].text)

    # Should get "no documents found" message
    assert result is not None
@@ -214,6 +227,8 @@ async def test_semantic_search_answer_with_limit(nc_mcp_client, temporary_note_f
    3. Query with limit=2
    4. Verify at most 2 sources in response
    """
+    await require_vector_sync_tools(nc_mcp_client)
+
    # Create multiple related notes
    _note1 = await temporary_note_factory(
        title="Python Async Part 1",
@@ -232,7 +247,6 @@ async def test_semantic_search_answer_with_limit(nc_mcp_client, temporary_note_f
    )

    # Wait for vector indexing to complete
-    import asyncio

    max_wait = 30
    wait_interval = 1
@@ -242,12 +256,12 @@ async def test_semantic_search_answer_with_limit(nc_mcp_client, temporary_note_f
        sync_status = await nc_mcp_client.call_tool(
            "nc_get_vector_sync_status", arguments={}
        )
-        status_data = sync_status.structuredContent
+        status_data = json.loads(sync_status.content[0].text)

        if status_data["status"] == "idle" and status_data["pending_count"] == 0:
            break

-        await asyncio.sleep(wait_interval)
+        await anyio.sleep(wait_interval)
        waited += wait_interval

    assert waited < max_wait, f"Vector sync did not complete within {max_wait} seconds"
@@ -265,7 +279,7 @@ async def test_semantic_search_answer_with_limit(nc_mcp_client, temporary_note_f
    assert call_result.isError is False, (
        f"Tool call failed: {call_result.content[0].text if call_result.isError else ''}"
    )
-    result = call_result.structuredContent
+    result = json.loads(call_result.content[0].text)

    # Should respect limit
    assert len(result["sources"]) <= 2
@@ -282,6 +296,8 @@ async def test_semantic_search_answer_score_threshold(
    3. Query with high threshold (0.9)
    4. Verify only high-scoring results returned
    """
+    await require_vector_sync_tools(nc_mcp_client)
+
    _note = await temporary_note_factory(
        title="Exact Match Test",
        content="This is a very specific test document about widget manufacturing",
@@ -289,7 +305,6 @@ async def test_semantic_search_answer_score_threshold(
    )

    # Wait for vector indexing to complete
-    import asyncio

    max_wait = 30
    wait_interval = 1
@@ -299,12 +314,12 @@ async def test_semantic_search_answer_score_threshold(
        sync_status = await nc_mcp_client.call_tool(
            "nc_get_vector_sync_status", arguments={}
        )
-        status_data = sync_status.structuredContent
+        status_data = json.loads(sync_status.content[0].text)

        if status_data["status"] == "idle" and status_data["pending_count"] == 0:
            break

-        await asyncio.sleep(wait_interval)
+        await anyio.sleep(wait_interval)
        waited += wait_interval

    assert waited < max_wait, f"Vector sync did not complete within {max_wait} seconds"
@@ -323,7 +338,7 @@ async def test_semantic_search_answer_score_threshold(
    assert call_result.isError is False, (
        f"Tool call failed: {call_result.content[0].text if call_result.isError else ''}"
    )
-    result = call_result.structuredContent
+    result = json.loads(call_result.content[0].text)

    # Note: Semantic search scores depend on embedding model
    # We just verify the tool accepts the parameter
@@ -345,6 +360,8 @@ async def test_semantic_search_answer_max_tokens(nc_mcp_client, temporary_note_f
    Note: Token limiting is enforced by the MCP client's LLM, not the server.
    This test just verifies the parameter is correctly passed.
    """
+    await require_vector_sync_tools(nc_mcp_client)
+
    _note = await temporary_note_factory(
        title="Long Document",
        content="This is a document with lots of content. " * 50,
@@ -352,7 +369,6 @@ async def test_semantic_search_answer_max_tokens(nc_mcp_client, temporary_note_f
    )

    # Wait for vector indexing to complete
-    import asyncio

    max_wait = 30
    wait_interval = 1
@@ -362,12 +378,12 @@ async def test_semantic_search_answer_max_tokens(nc_mcp_client, temporary_note_f
        sync_status = await nc_mcp_client.call_tool(
            "nc_get_vector_sync_status", arguments={}
        )
-        status_data = sync_status.structuredContent
+        status_data = json.loads(sync_status.content[0].text)

        if status_data["status"] == "idle" and status_data["pending_count"] == 0:
            break

-        await asyncio.sleep(wait_interval)
+        await anyio.sleep(wait_interval)
        waited += wait_interval

    assert waited < max_wait, f"Vector sync did not complete within {max_wait} seconds"
@@ -386,7 +402,7 @@ async def test_semantic_search_answer_max_tokens(nc_mcp_client, temporary_note_f
    assert call_result.isError is False, (
        f"Tool call failed: {call_result.content[0].text if call_result.isError else ''}"
    )
-    result = call_result.structuredContent
+    result = json.loads(call_result.content[0].text)

    # Should not error, even if sampling fails
    assert result is not None
--- a/Show More
+++ b/Show More